内容
<div align="center">
---
# ⚡ TerminalPulse
***人工智能代理的短期记忆。实时记录你的编程上下文 - 静默进行。***
检测错误，跟踪你的焦点，即时修复 bug - 无需复制粘贴，无需解释，无需切换上下文。TerminalPulse 监视你的终端、编辑器和文件系统。当出现问题时，它已经知道发生了什么。
---
</div>
---
## 📋 目录
- [问题](#-每个开发者都遇到的问题)
- [解决方案](#-解决方案)
- [工作原理](#-工作原理)
- [安装](#-安装)
- [设置](#-设置-一次性)
- [命令](#-命令)
- [现实场景](#-现实场景)
- [错误自动建议](#-错误自动建议)
- [MCP 集成](#-mcp-集成-claude-desktop--cursor)
- [语言和项目支持](#-语言和项目支持)
- [差异](#-差异)
- [安全和隐私](#-安全和隐私)
- [需求](#-需求)
- [测试](#-测试)
- [贡献](#-贡献)
- [许可证](#-许可证)
---
## 🔥 每个开发者都遇到的问题
你正在深入一个功能。你的构建失败了。现在你必须：
1. 阅读错误跟踪信息
2. 复制错误
3. 切换到 Claude / ChatGPT / Cursor
4. 解释你的项目、git 分支、正在编辑的文件
5. 粘贴文件内容
6. 等待答案
7. 切换回终端
8. 手动应用修复
**这意味着每次都要进行 2 分钟的上下文切换摩擦。**
最糟糕的是？AI 不知道你当时在做什么。你必须从头开始重新解释一切。
---
## ✅ 解决方案
```bash
# 你的 Next.js 构建在 2am 失败
npm run build
# TypeError: Cannot read properties of undefined (reading 'userId')
# ⚡ 检测到错误。运行 'pulse fix' 进行自动修复。
pulse fix
# TerminalMind 已经知道：
# → 项目：Next.js + TypeScript
# → 分支：feature/auth
# → 上次提交： "add JWT middleware"
# → 活动文件：src/middleware/auth.ts
# → 完整的构建错误输出
# → 实际文件内容
# → 精确的修复在几秒内
```
无需切换标签。无需解释。无需复制粘贴。
---
## 🏗️ 工作原理
三个静默流馈送到一个时间衰减的知识图：
| 流 | 源 | 它捕获的内容 |
|---|---|---|
| **焦点** | VS Code 窗口标题 | 编辑器中哪个文件是活动的 |
| **活动** | 文件系统监视器 | 哪些文件刚刚保存 |
| **困扰** | Bash 钩子 | 哪些终端命令刚刚失败 |
每个事件都有一个热量值，该值会随着时间衰减：
```
heat = e^(-λ × seconds_since_event) × severity
```
较旧的事件会自动淡出。AI 总是能获得当前最相关的信息 - 而不是今天早些时候的工作噪音。
### 数据流
```
VS Code (Windows) → HTTP:7077 ─┐
终端错误 → Unix 套接字 ─┼→ pulsed 守护进程 → ~/.devpulse_state.json
文件保存 → 监视器 ─┘ ↓
pulse fix → TerminalMind → 修复
```
### 技术栈
| 层 | 技术 | 角色 |
|---|---|---|
| **守护进程** | Python asyncio | 长寿命后台进程 |
| **图** | NetworkX + Pydantic | 时间衰减知识图 |
| **CLI** | Typer + Rich | 命令和格式化输出 |
| **AI 桥接** | TerminalMind | 由实时上下文驱动的自动修复 |
---
## 🚀 安装
```bash
pip install terminalpulse
pip install terminalmind
tmind auth
```
---
## ⚙️ 设置（一次性）
```bash
# 安装系统依赖
pulse install-deps
# 注入 shell 钩子
pulse init
source ~/.bashrc
# 开始监视你的项目
cd your-project
pulse watch
```
就这样。TerminalPulse 从现在开始在后台静默运行。
---
## 🛠️ 命令
| 命令 | 它执行的操作 |
|---|---|
| `pulse watch` | 自动检测项目类型并启动守护进程 |
| `pulse fix` | 向 AI 发送完整上下文 - 无需输入 |
| `pulse context` | 为任何 AI 复制格式化上下文块 |
| `pulse summary` | 编程会话的纯英语摘要 |
| `pulse insights` | 检测重复出现的故障模式 |
| `pulse report` | 每天结束时的编码摘要 |
| `pulse history` | 30 分钟活动时间线 |
| `pulse state` | 显示原始 JSON 上下文 |
| `pulse init` | 将 shell 钩子注入 `.bashrc` |
| `pulse install-deps` | 安装系统依赖 |
| `pulse mcp` | 为 Claude Desktop / Cursor 启动 MCP 服务器 |
| `pulse_run <cmd>` | 为大型构建捕获完整的 stderr |
---
## 🧑💻 现实场景
### 场景 1 — 全栈开发者（Next.js + TypeScript）
```bash
cd ~/my-saas
pulse watch
# 检测到项目：Next.js + TypeScript
# 监视中：/home/user/my-saas
# 稍后 - 构建失败
npm run build
# Module not found: Can't resolve '@/components/AuthGuard'
# ⚡ 检测到错误。运行 'pulse fix' 进行自动修复。
pulse fix
# 发送到 TerminalMind：
# → 项目：Next.js + TypeScript
# → 分支：feature/dashboard
# → 已更改文件：components/AuthGuard.tsx, pages/dashboard.tsx
# → 完整的 webpack 错误
# → dashboard.tsx 的文件内容
# → 即时精确修复
```
---
### 场景 2 — 后端开发者（Python / FastAPI）
```bash
cd ~/api-server
pulse watch
# 检测到项目：Python
# 服务器崩溃
python3 main.py
# sqlalchemy.exc.OperationalError: no such table: users
# ⚡ 检测到错误。运行 'pulse fix' 进行自动修复。
pulse fix
# AI 知道你刚刚编辑了 models.py 并运行了一个迁移
# 提供确切的 Alembic 修复，而不是通用答案
```
---
### 场景 3 — 你使用 Claude，而不是 TerminalMind
```bash
pulse context
# 复制到剪贴板：
# === TerminalPulse 上下文 ===
# 项目： React + TypeScript
# 分支： fix/payment-flow
# 活动文件： src/checkout/PaymentForm.tsx
# 上次错误： npm run build (exit 1)
# 已更改文件： PaymentForm.tsx, useStripe.ts
# 文件内容： [实际代码]
# =============================
# 粘贴到 Claude - 完整上下文一次性粘贴
```
---
### 场景 4 — 重复出现的 Bug 模式
```bash
# 在今天遇到同一个错误 4 次后
pulse insights
# ⚡ TerminalPulse 见解
# 项目：Python | 分支：feature/auth
#
# 重复故障：python3 server.py 失败 4 次
# → 所有故障都发生在编辑 config.py 之后
# → 建议：运行 pulse fix 来调查根本原因
# 高错误率：80%
# → 考虑在 config.py 中添加输入验证
```
---
### 场景 5 — 每天结束时的汇报
```bash
pulse report
# 📊 TerminalPulse 每日报表
# 分支：feature/payment-integration
#
# • 保存的文件： 23
# • 遇到的错误： 6
# • 焦点变化： 14
#
# 最多编辑的文件： PaymentForm.tsx (6 次保存)
# 最常见的错误： npm run build (4 次)
#
# 糟糕的会话 - 6 个错误。运行 pulse insights 来查找模式。
```
---
### 场景 6 — 快速会话总结
```bash
pulse summary
# 📝 会话总结
#
# 您正在从事一个 Python 项目，分支为 feature/auth。
# 大部分时间都花在编辑 models.py 上（6 次保存）。
# 您当前的活动文件是 models.py。
# 您遇到了 3 个错误，大多数来自 python3 server.py (3 次)。
# 上次提交：add user authentication
```
在休息后返回时非常有用 - 即时了解您离开时的状态。
```bash
# 真实的输出示例：
(terminalpulse) prajwal@Prajwal:~/terminalpulse$ pulse summary
📝 会话总结
您正在分支 master 上工作。
大部分时间都花在编辑 cli.py 上（1 次保存）。
您在这次会话中遇到了 1 个错误。
上次提交：v0.5.0 - 优雅的回退，pulse context，自动建议，install-deps
```
---
## ⚡ 错误自动建议
每次命令失败时，TerminalPulse 都会打印：
```
⚡ 检测到错误。运行 'pulse fix' 进行自动修复。
```
您无需记住要使用它。
---
## 🔌 MCP 集成（Claude Desktop / Cursor）
```bash
pulse mcp
```
添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"terminalpulse": {
"command": "pulse",
"args": ["mcp"]
}
}
}
```
Claude Desktop 现在使用您的编码上下文。询问它：
- *"我当时在做什么？*
- *"我今天遇到了哪些错误？*
- *"哪个文件导致的问题最多？*
可用工具：
| 工具 | 返回 |
|---|---|
| `get_pulse_state` | 完整的当前编码上下文 |
| `get_hottest_error` | 最近的错误，包含完整的 stderr |
| `get_active_context` | 活动文件、语言、git 分支 |
| `get_history` | 过去 30 分钟的时间线 |
---
## 🌍 语言和项目支持
| 堆栈 | 检测 | 错误捕获 | 修复 |
|---|---|---|---|
| Python / FastAPI / Django | ✓ | ✓ | ✓ |
| React / Next.js | ✓ | ✓ | ✓ |
| TypeScript / Node.js | ✓ | ✓ | ✓ |
| Rust | ✓ | ✓ | ✓ |
| Go | ✓ | ✓ | ✓ |
| Java / Spring | ✓ | ✓ | ✓ |
| 大型构建（webpack、gradle、pytest） | ✓ via `pulse_run` | ✓ | ✓ |
---
## 📊 差异
| 没有 TerminalPulse | 使用 TerminalPulse |
|---|---|
| 手动复制错误 | 自动捕获 |
| 切换到 AI 聊天 | 已经连接 |
| 解释你的项目 | 自动检测 |
| 解释 git 分支 | 自动检测 |
| 粘贴文件内容 | 自动读取 |
| 等待响应 | 即时 |
| 手动应用修复 | 一键 |
| **每次 ~2 分钟** | **~5 秒** |
---
## 🛡️ 安全和隐私
- **本地优先** - 您的上下文图完全存在于您的机器上
- **无遥测** - 在未经您命令的情况下，不会将任何内容发送到任何地方
- **有针对性的上下文** - 只有特定的错误和活动文件会发送到 AI
- **安全密钥** - API 密钥存储在 OS 密钥环中，从不存储在纯文本文件中
---
## 📋 需求
- Python 3.10+
- WSL Ubuntu（Linux 守护进程）
- `netcat` - 在 Ubuntu 上预安装
- `terminalmind` - 用于 `pulse fix`
- Windows 11 + VS Code - 用于焦点跟踪（可选）
---
## 🧪 测试
**29 个单元测试 - 全部通过。**
```bash
.venv/bin/pytest tests/ -v
# 29 passed in 0.83s
```
| 类别 | 测试 | 验证内容 |
|---|---|---|
| **事件模型** | 4 | `COMMAND_FAILED`、`FILE_SAVED`、`FOCUS_CHANGED`、`COMMAND_OK` - 正确字段和时间戳 |
| **语言检测** | 8 | `.py` → python、`.ts` → typescript、`.tsx` → typescript、`.js` → javascript、`.rs` → rust、`.go` → go、未知扩展、 `None` 输入 |
| **项目类型检测** | 8 | `pyproject.toml` → python、 `requirements.txt` → python、 `package.json` → react-typescript / nextjs / node、 `Cargo.toml` → rust、 `go.mod` → go、空文件夹 → 未知 |
| **PulseGraph** | 9 | 事件添加到图中、热量分数 0-1、错误链接到活动文件、最新事件按热量排序、状态写入磁盘、历史记录 |
---
## 🤝 贡献
1. 复刻仓库
2. 创建分支：`git checkout -b feature/your-feature`
3. 为您的功能添加测试 - 所有 PR 都必须包含覆盖新行为的新测试
4. 确保所有 29 个现有测试仍然通过：`.venv/bin/pytest tests/ -v`
5. 提交：`git commit -m 'Add your feature'`
6. 推送：`git push origin feature/your-feature`
7. 打开拉取请求
> 没有通过测试的 PR 不会被合并。
---
## 📝 更新日志
| 版本 | 新增功能 |
|---|---|
| `v0.5.0` | `pulse summary`、优雅的回退、`pulse context`、每个错误自动建议、`pulse install-deps`、29 个单元测试、演示截图 |
| `v0.4.0` | 与 Claude Desktop / Cursor 的 MCP 集成 |
| `v0.3.0` | `pulse insights`、`pulse report`、模式检测 |
| `v0.2.0` | `pulse fix`、TerminalMind 桥、Unix 套接字守护进程 |
| `v0.1.0` | 初始版本 - shell 钩子、文件监视器、热量图 |
---
## 📄 许可证
MIT © 2026 Prajwal Hulle - 请参阅 **[LICENSE](https://github.com/prajwal-2509/terminalpulse/blob/main/LICENSE)** 获取完整详情。
---
<div align="center">
为厌倦向 AI 复制粘贴错误的开发者而建。
<br/>
[](https://pypi.org/project/terminalpulse)
[](https://github.com/prajwal-2509/terminalpulse)
[](https://github.com/prajwal-2509/terminalpulse/issues)
</div>
