🚀 ShellPulse

轻量级终端命令智能分析与学习引擎
Lightweight Terminal Command Intelligence Analysis & Learning Engine

简体中文 · 繁體中文 · English

---

📖 简体中文

💡 一句话介绍：ShellPulse 是一款零依赖的终端命令分析工具，它能读懂你的命令历史，发现使用模式，检测安全风险，并帮你成为更高效的终端用户。

✨ 核心特性

特性	说明
📊 命令历史分析	全面支持 Bash、Zsh、Fish、PowerShell 四大主流 Shell
🔍 使用模式发现	频率统计、类别分布、命令链分析，深度洞察你的操作习惯
🛡️ 安全风险检测	内置 30+ 安全规则，覆盖 CRITICAL / HIGH / MEDIUM / LOW 四个风险等级
🧠 命令知识图谱	内置知识库，智能推荐学习路径，系统提升命令行功力
📟 TUI 交互式仪表盘	终端内可视化展示，数据一目了然
👁️ 实时命令监控	实时检测新写入命令的安全风险，防患于未然
💡 智能别名建议	基于使用频率智能推荐 Shell 别名，减少重复输入
📄 报告导出	支持 JSON / Markdown 格式导出，方便分享与存档

🎯 为什么选择 ShellPulse？

• 🪶 极致轻量 — 纯 Python 实现，零外部依赖，pip install 即可使用
• 🔒 隐私优先 — 所有分析均在本地完成，不上传任何数据
• 🎨 开箱即用 — 无需配置，自动识别 Shell 环境
• 📈 持续进化 — 模块化架构，轻松扩展新的分析规则和知识条目

⚡ 快速开始

安装

# 方式一：使用 pip 安装
pip install .

# 方式二：使用 pipx 安装（推荐，隔离环境）
pipx install .

# 方式三：免安装直接运行
PYTHONPATH=src python -m shellpulse

基本使用

# 分析当前 Shell 的命令历史（自动检测 Shell 类型）
shellpulse analyze

# 指定 Shell 类型分析
shellpulse analyze -s zsh

# 指定历史文件路径
shellpulse analyze -f ~/.bash_history

# 限制分析条数（最近 100 条）
shellpulse analyze -n 100

# 选择分析视图
shellpulse analyze -V overview     # 总览视图
shellpulse analyze -V patterns     # 模式分析
shellpulse analyze -V risk         # 风险检测
shellpulse analyze -V knowledge    # 知识图谱

# 导出分析报告
shellpulse analyze -e report.json
shellpulse analyze -e report.md

📚 详细使用指南

1. 命令历史分析

ShellPulse 能智能解析多种 Shell 的历史文件格式，提取有效的命令记录：

# 分析 Bash 历史
shellpulse analyze -s bash -f ~/.bash_history

# 分析 Zsh 历史
shellpulse analyze -s zsh -f ~/.zsh_history

# 分析 Fish 历史
shellpulse analyze -s fish -f ~/.local/share/fish/fish_history

# 分析 PowerShell 历史
shellpulse analyze -s powershell -f (Get-PSReadLineOption).HistorySavePath

2. 安全风险检测

对命令历史进行安全审计，识别潜在风险：

# 检测历史命令中的安全风险
shellpulse analyze -V risk

# 检测单条命令
shellpulse check --cmd "rm -rf /tmp/test"

# 查看风险等级说明
# CRITICAL — 极度危险，可能导致数据丢失或系统被控
# HIGH     — 高风险，可能造成安全隐患
# MEDIUM   — 中等风险，需要关注
# LOW      — 低风险，建议优化

3. 命令搜索与学习

# 搜索命令相关知识
shellpulse search "docker"

# 搜索特定用法
shellpulse search "git rebase"

4. 实时命令监控

开启实时监控模式，对新执行的命令进行即时安全检测：

# 启动实时监控（默认 2 秒间隔）
shellpulse watch

# 自定义监控间隔（5 秒）
shellpulse watch -i 5

🏗️ 设计思路

ShellPulse 的架构设计遵循以下原则：

┌─────────────────────────────────────────────┐
│                  ShellPulse                  │
├──────────┬──────────┬───────────┬───────────┤
│  Parser  │ Analyzer │  Detector  │  Exporter │
│  模块    │  模块    │   模块     │   模块    │
├──────────┴──────────┴───────────┴───────────┤
│              Core Engine (核心引擎)           │
├─────────────────────────────────────────────┤
│         Shell History Files (历史文件)        │
└─────────────────────────────────────────────┘

• Parser（解析器）：负责解析不同 Shell 的历史文件格式，统一输出为标准命令记录
• Analyzer（分析器）：对命令进行频率统计、模式识别、类别归类
• Detector（检测器）：基于规则引擎进行安全风险检测与评估
• Exporter（导出器）：将分析结果序列化为 JSON / Markdown 等格式

📦 打包与部署

# 安装构建工具
pip install build

# 构建 Wheel 包
python -m build

# 生成的包位于 dist/ 目录下
ls dist/
# shellpulse-1.0.0-py3-none-any.whl
# shellpulse-1.0.0.tar.gz

# 上传到 PyPI
pip install twine
twine upload dist/*

🤝 贡献指南

我们欢迎任何形式的贡献！无论是提交 Bug、改进文档，还是添加新功能。

1. 🍴 Fork 本仓库
2. 🌿 创建特性分支：git checkout -b feature/amazing-feature
3. 💾 提交更改：git commit -m '✨ Add some amazing feature'
4. 📤 推送分支：git push origin feature/amazing-feature
5. 🎉 提交 Pull Request

📄 开源协议

本项目基于 MIT License 开源。

---

📖 繁體中文

💡 一句話介紹：ShellPulse 是一款零依賴的終端命令分析工具，它能讀懂你的命令歷史，發現使用模式，偵測安全風險，並幫助你成為更高效的終端使用者。

✨ 核心特性

特性	說明
📊 命令歷史分析	全面支援 Bash、Zsh、Fish、PowerShell 四大主流 Shell
🔍 使用模式發現	頻率統計、類別分佈、命令鏈分析，深度洞察你的操作習慣
🛡️ 安全風險偵測	內建 30+ 安全規則，涵蓋 CRITICAL / HIGH / MEDIUM / LOW 四個風險等級
🧠 命令知識圖譜	內建知識庫，智慧推薦學習路徑，系統性提升命令列功力
📟 TUI 互動式儀表板	終端內視覺化展示，資料一目了然
👁️ 即時命令監控	即時偵測新寫入命令的安全風險，防患於未然
💡 智慧別名建議	基於使用頻率智慧推薦 Shell 別名，減少重複輸入
📄 報告匯出	支援 JSON / Markdown 格式匯出，方便分享與存檔

🎯 為什麼選擇 ShellPulse？

• 🪶 極致輕量 — 純 Python 實作，零外部依賴，pip install 即可使用
• 🔒 隱私優先 — 所有分析均在本地完成，不上傳任何資料
• 🎨 開箱即用 — 無需配置，自動辨識 Shell 環境
• 📈 持續進化 — 模組化架構，輕鬆擴充新的分析規則與知識條目

⚡ 快速開始

安裝

# 方式一：使用 pip 安裝
pip install .

# 方式二：使用 pipx 安裝（推薦，隔離環境）
pipx install .

# 方式三：免安裝直接執行
PYTHONPATH=src python -m shellpulse

基本使用

# 分析當前 Shell 的命令歷史（自動偵測 Shell 類型）
shellpulse analyze

# 指定 Shell 類型分析
shellpulse analyze -s zsh

# 指定歷史檔案路徑
shellpulse analyze -f ~/.bash_history

# 限制分析條數（最近 100 條）
shellpulse analyze -n 100

# 選擇分析視圖
shellpulse analyze -V overview     # 總覽視圖
shellpulse analyze -V patterns     # 模式分析
shellpulse analyze -V risk         # 風險偵測
shellpulse analyze -V knowledge    # 知識圖譜

# 匯出分析報告
shellpulse analyze -e report.json
shellpulse analyze -e report.md

📚 詳細使用指南

1. 命令歷史分析

ShellPulse 能智慧解析多種 Shell 的歷史檔案格式，提取有效的命令記錄：

# 分析 Bash 歷史
shellpulse analyze -s bash -f ~/.bash_history

# 分析 Zsh 歷史
shellpulse analyze -s zsh -f ~/.zsh_history

# 分析 Fish 歷史
shellpulse analyze -s fish -f ~/.local/share/fish/fish_history

# 分析 PowerShell 歷史
shellpulse analyze -s powershell -f (Get-PSReadLineOption).HistorySavePath

2. 安全風險偵測

對命令歷史進行安全稽核，識別潛在風險：

# 偵測歷史命令中的安全風險
shellpulse analyze -V risk

# 偵測單條命令
shellpulse check --cmd "rm -rf /tmp/test"

# 查看風險等級說明
# CRITICAL — 極度危險，可能導致資料遺失或系統被控
# HIGH     — 高風險，可能造成安全隱患
# MEDIUM   — 中等風險，需要關注
# LOW      — 低風險，建議優化

3. 命令搜尋與學習

# 搜尋命令相關知識
shellpulse search "docker"

# 搜尋特定用法
shellpulse search "git rebase"

4. 即時命令監控

開啟即時監控模式，對新執行的命令進行即時安全偵測：

# 啟動即時監控（預設 2 秒間隔）
shellpulse watch

# 自訂監控間隔（5 秒）
shellpulse watch -i 5

🏗️ 設計思路

ShellPulse 的架構設計遵循以下原則：

┌─────────────────────────────────────────────┐
│                  ShellPulse                  │
├──────────┬──────────┬───────────┬───────────┤
│  Parser  │ Analyzer │  Detector  │  Exporter │
│  模組    │  模組    │   模組     │   模組    │
├──────────┴──────────┴───────────┴───────────┤
│            Core Engine (核心引擎)            │
├─────────────────────────────────────────────┤
│        Shell History Files (歷史檔案)        │
└─────────────────────────────────────────────┘

• Parser（解析器）：負責解析不同 Shell 的歷史檔案格式，統一輸出為標準命令記錄
• Analyzer（分析器）：對命令進行頻率統計、模式識別、類別歸類
• Detector（偵測器）：基於規則引擎進行安全風險偵測與評估
• Exporter（匯出器）：將分析結果序列化為 JSON / Markdown 等格式

📦 打包與部署

# 安裝建置工具
pip install build

# 建置 Wheel 套件
python -m build

# 生成的套件位於 dist/ 目錄下
ls dist/
# shellpulse-1.0.0-py3-none-any.whl
# shellpulse-1.0.0.tar.gz

# 上傳至 PyPI
pip install twine
twine upload dist/*

🤝 貢獻指南

我們歡迎任何形式的貢獻！無論是回報 Bug、改進文件，還是新增功能。

1. 🍴 Fork 本儲存庫
2. 🌿 建立特性分支：git checkout -b feature/amazing-feature
3. 💾 提交變更：git commit -m '✨ Add some amazing feature'
4. 📤 推送分支：git push origin feature/amazing-feature
5. 🎉 提交 Pull Request

📄 開源授權

本專案基於 MIT License 開源。

---

📖 English

💡 In a nutshell: ShellPulse is a zero-dependency terminal command analysis tool that reads your command history, discovers usage patterns, detects security risks, and helps you become a more productive terminal user.

✨ Core Features

Feature	Description
📊 Command History Analysis	Full support for Bash, Zsh, Fish, and PowerShell
🔍 Usage Pattern Discovery	Frequency stats, category distribution, and command chain analysis for deep insight into your habits
🛡️ Security Risk Detection	30+ built-in rules covering CRITICAL / HIGH / MEDIUM / LOW severity levels
🧠 Command Knowledge Graph	Built-in knowledge base with smart learning path recommendations
📟 TUI Interactive Dashboard	In-terminal visualization for at-a-glance data overview
👁️ Real-time Command Monitoring	Instant security scanning of newly executed commands
💡 Smart Alias Suggestions	Frequency-based Shell alias recommendations to reduce repetitive typing
📄 Report Export	Export to JSON / Markdown formats for easy sharing and archiving

🎯 Why ShellPulse?

• 🪶 Ultra Lightweight — Pure Python with zero external dependencies; just pip install and go
• 🔒 Privacy First — All analysis runs locally; no data ever leaves your machine
• 🎨 Works Out of the Box — No configuration needed; auto-detects your Shell environment
• 📈 Extensible by Design — Modular architecture makes it easy to add new analysis rules and knowledge entries

⚡ Quick Start

Installation

# Option 1: Install with pip
pip install .

# Option 2: Install with pipx (recommended, isolated environment)
pipx install .

# Option 3: Run without installing
PYTHONPATH=src python -m shellpulse

Basic Usage

# Analyze current Shell history (auto-detects Shell type)
shellpulse analyze

# Specify Shell type
shellpulse analyze -s zsh

# Specify history file path
shellpulse analyze -f ~/.bash_history

# Limit the number of entries to analyze (most recent 100)
shellpulse analyze -n 100

# Select analysis view
shellpulse analyze -V overview     # Overview
shellpulse analyze -V patterns     # Pattern analysis
shellpulse analyze -V risk         # Risk detection
shellpulse analyze -V knowledge    # Knowledge graph

# Export analysis report
shellpulse analyze -e report.json
shellpulse analyze -e report.md

📚 Detailed Usage Guide

1. Command History Analysis

ShellPulse intelligently parses history file formats from multiple Shells and extracts valid command records:

# Analyze Bash history
shellpulse analyze -s bash -f ~/.bash_history

# Analyze Zsh history
shellpulse analyze -s zsh -f ~/.zsh_history

# Analyze Fish history
shellpulse analyze -s fish -f ~/.local/share/fish/fish_history

# Analyze PowerShell history
shellpulse analyze -s powershell -f (Get-PSReadLineOption).HistorySavePath

2. Security Risk Detection

Perform a security audit on your command history to identify potential risks:

# Detect security risks in command history
shellpulse analyze -V risk

# Check a single command
shellpulse check --cmd "rm -rf /tmp/test"

# Risk severity levels:
# CRITICAL — Extremely dangerous; may cause data loss or system compromise
# HIGH     — High risk; potential security vulnerability
# MEDIUM   — Medium risk; warrants attention
# LOW      — Low risk; recommended for optimization

3. Command Search & Learning

# Search for command-related knowledge
shellpulse search "docker"

# Search for specific usage
shellpulse search "git rebase"

4. Real-time Command Monitoring

Enable real-time monitoring mode for instant security scanning of newly executed commands:

# Start monitoring (default 2-second interval)
shellpulse watch

# Custom monitoring interval (5 seconds)
shellpulse watch -i 5

🏗️ Architecture

ShellPulse's architecture follows these design principles:

┌─────────────────────────────────────────────┐
│                  ShellPulse                  │
├──────────┬──────────┬───────────┬───────────┤
│  Parser  │ Analyzer │  Detector  │  Exporter │
│  Module  │  Module  │   Module   │  Module   │
├──────────┴──────────┴───────────┴───────────┤
│              Core Engine                     │
├─────────────────────────────────────────────┤
│         Shell History Files                  │
└─────────────────────────────────────────────┘

• Parser — Parses history file formats from different Shells and normalizes them into standard command records
• Analyzer — Performs frequency statistics, pattern recognition, and category classification on commands
• Detector — Rule-engine-based security risk detection and assessment
• Exporter — Serializes analysis results into JSON, Markdown, and other formats

📦 Packaging & Distribution

# Install build tools
pip install build

# Build the Wheel package
python -m build

# Built packages are located in the dist/ directory
ls dist/
# shellpulse-1.0.0-py3-none-any.whl
# shellpulse-1.0.0.tar.gz

# Publish to PyPI
pip install twine
twine upload dist/*

🤝 Contributing

Contributions of all kinds are welcome! Whether it's filing a bug, improving documentation, or adding new features.

1. 🍴 Fork this repository
2. 🌿 Create a feature branch: git checkout -b feature/amazing-feature
3. 💾 Commit your changes: git commit -m '✨ Add some amazing feature'
4. 📤 Push the branch: git push origin feature/amazing-feature
5. 🎉 Open a Pull Request

📄 License

This project is licensed under the MIT License.

---

Made with ❤️ by gitstq