内容
# TracePulse
<img src="gitbook/.gitbook/assets/tracepulse-logo.png" alt="TracePulse" width="120" align="right"/>
[](https://www.npmjs.com/package/tracepulse)
[](https://www.gnu.org/licenses/agpl-3.0)
[]()
**用于 AI 编程代理的运行时反馈 MCP 服务器**
*减少浪费的 tokens。更快的交付。更低的碳足迹。负责任的 AI 实践。*
[ViewGraph](https://chaoslabz.gitbook.io/viewgraph) 看到了 UI。TracePulse 听到了后端。
> "大型语言模型（LLM）无法看到代码实际运行时发生了什么。它们是在黑暗中投掷飞镖。" - [Sentry Engineering](https://blog.sentry.io/vibe-coding-closing-the-feedback-loop-with-traceability/)
>
> TracePulse 在开发时关闭了这个循环 - 代码更改后几秒钟，而不是部署后几分钟。
TracePulse 监视您的开发服务器的 stdout/stderr，解析错误为结构化事件并附带信号评分，并将它们暴露为 MCP 工具，任何 AI 编程代理都可以调用。代理编辑代码，调用 `get_errors`，并立即知道修复是否有效 - 无需手动阅读日志，无需复制粘贴。
## 状态
🟡 **Alpha v0.9.31 - 第 1-5 阶段完成。** [核心管道](docs/architecture/architecture-guide.md#the-data-pipeline)，[监视模式](docs/architecture/architecture-guide.md#mcp-tools---what-the-agent-can-call)，[多进程支持](docs/architecture/architecture-guide.md#multi-process-architecture-phase-3)，[前端-后端关联](docs/architecture/architecture-guide.md#frontend-backend-correlation-phase-4)，主动监控。[25 个错误解析器](docs/architecture/architecture-guide.md#error-parsers---what-languages-are-supported)，[44 个 MCP 工具](docs/architecture/architecture-guide.md#mcp-tools---what-the-agent-can-call)，[1380 个测试](tests/) 通过。
## 快速开始
将 TracePulse 添加到您的 MCP 客户端的配置文件中。文件位置取决于您使用的工具：
### 配置文件位置
| MCP 客户端 | 配置文件 |
|------------|-------------|
| **Kiro CLI** | `.kiro/settings/mcp.json`（在您的项目中） |
| **Claude Code** | `~/.claude.json` 下 `projects["/path"].mcpServers` |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS） |
| **Claude Desktop** | `%APPDATA%\Claude\claude_desktop_config.json`（Windows） |
| **Cursor** | `.cursor/mcp.json`（在您的项目中） |
| **VS Code (Copilot)** | `.vscode/mcp.json`（在您的项目中） |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **通用** | `.mcp.json`（在您的项目根目录中） |
> ⚠️ **常见错误：** Kiro CLI 使用 `.kiro/settings/mcp.json`，而不是 `.kiro/mcp.json`。如果 TracePulse 工具未出现，请检查您是否正在编辑正确的文件。
### 零配置（适用于任何项目）
```json
{
"mcpServers": {
"tracepulse": {
"command": "tracepulse"
}
}
}
```
TracePulse 自动检测您的项目类型（Node、Python、Go、Rust、Java）并立即提供工具。无需服务器命令 - 代理可以在需要时调用 `start_server()`。
> 💡 **推荐：** 运行 `tracepulse init` 而不是手动配置。它为所有 TracePulse 工具添加 `autoApprove`，确保代理在没有权限提示的情况下使用它们。如果没有 `autoApprove`，代理默认使用 shell（零摩擦）- 这是 TracePulse 利用不足的主要原因。
对于非 Node 项目，请全局安装：`npm install -g tracepulse`
要直接从 GitHub 安装最新未发布的版本：
```bash
npm install -g github:sourjya/tracepulse
```
### 启动模式 - 生成并监视您的开发服务器
**Node.js 项目**（项目中可用 npm/pnpm/Bun）：
```json
{
"mcpServers": {
"tracepulse": {
"command": "npx",
"args": ["tracepulse", "start", "npm run dev"]
}
}
}
```
**Python、Go、Java、Rust 或任何非 Node 项目：
Node.js 可能不在您的项目路径中。全局安装 TracePulse 一次：
```bash
npm install -g tracepulse
```
然后直接使用全局二进制文件：
```json
{
"mcpServers": {
"tracepulse": {
"command": "tracepulse",
"args": ["start", "python manage.py runserver"]
}
}
}
```
用您的开发服务器替换命令：`uvicorn main:app --reload`、`go run main.go`、`mvn spring-boot:run`、`cargo run` 等。
**如果您的服务器需要环境变量**（例如 `PYTHONPATH`），请使用 `env` 字段：
```json
{
"mcpServers": {
"tracepulse": {
"command": "tracepulse",
"args": ["start", "python -m myapp.server"],
"env": { "PYTHONPATH": "src" }
}
}
}
```
**如果您的服务器使用启动脚本**（bash、shell）：
```json
{
"mcpServers": {
"tracepulse": {
"command": "tracepulse",
"args": ["start", "bash scripts/start.sh"]
}
}
}
```
> ⚠️ **环境变量放在 `env` 字段中，而不是命令中。** `"args": ["start", "PYTHONPATH=src python app.py"]` 不起作用。将变量放在 `env` 中并保持命令清洁。
### 附加模式 - 附加到现有的日志文件
在以下情况下使用此模式：您的服务器已经运行（由脚本、Docker、进程管理器等管理）：
```json
{
"mcpServers": {
"tracepulse": {
"command": "npx",
"args": ["tracepulse", "attach", "--log-file", "./logs/server.log"]
}
}
}
```
### 本地开发（无需 npm 发布）
直接指向已构建的 CLI：
```json
{
"mcpServers": {
"tracepulse": {
"command": "node",
"args": ["/path/to/tracepulse/dist/cli.js", "start", "npm run dev"]
}
}
}
```
### 应该使用哪种模式？
| 情况 | 模式 |
|-----------|------|
| 简单的 `npm run dev` 或 `python manage.py runserver` | **启动** - TracePulse 生成它 |
| 由脚本、Docker、tmux、pm2 管理的服务器 | **附加** - TracePulse 附加到日志文件 |
| 新项目、库或尚未有服务器 | **独立** - 仅工具，无收集器 |
| 多个服务（API + 工作进程 + 前端） | **启动 --service** 或 **配置文件** |
| Docker Compose 设置 | **compose** |
## MCP 工具
### 核心（第 1 阶段）
| 工具 | 描述 | tokens |
|------|-------------|--------|
| `get_errors(since?, source?, service?, limit?)` | 按信号评分排序的最新错误（最高优先） | ~1,000 |
| `get_server_logs(level?, since?, limit?)` | 按时间戳排序的所有日志事件（最新优先） | ~2,000 |
| `get_runtime_status()` | 健康检查：连接、错误计数、关联源 | ~100 |
| `clear_errors()` | 重置事件缓冲区以进行干净的验证循环 | ~50 |
### 监视模式（第 2 阶段）
| 工具 | 描述 | tokens |
|------|-------------|--------|
| `watch_for_errors(duration_seconds?, source?)` | 阻塞 N 秒，收集热重载后的新错误 | ~1,000 |
| `get_build_errors(limit?)` | TypeScript、ESLint、Vite/webpack 编译错误 | ~1,500 |
| `get_error_context(fingerprint)` | 深入探讨：完整的错误 + 周围的日志 ±5s + 出现次数 | ~3,000 |
| `get_timeline(since, duration_seconds?, limit?)` | 所有事件的统一时间顺序流 | ~5,000 |
### 多进程（第 3 阶段）
| 工具 | 描述 | tokens |
|------|-------------|--------|
| `list_services()` | 服务名称、状态、错误计数、最后活动 | ~200 |
| `start_server(command, env?, cwd?, name?)` | 在会话中启动开发服务器。预验证命令，激活监控。 | ~100 |
| `stop_server(name?)` | 停止正在运行的开发服务器。发送 SIGTERM，等待，然后如果需要发送 SIGKILL。 | ~50 |
| `restart_server()` | 杀死并重启开发服务器（仅启动模式）。自动清除错误缓冲区。 | ~100 |
### 关联（第 4 阶段）
| 工具 | 描述 | tokens |
|------|-------------|--------|
| `get_correlated_errors(url?)` | 将浏览器 HTTP 故障与后端堆栈跟踪匹配 | ~2,000 |
| `get_cross_layer_diagnosis(time_window_seconds?)` | 跨层故障诊断。将后端、前端、git 和进程信号关联成可行的根本原因诊断。 | ~500 |
### 主动式（第 5 阶段）
| 工具 | 描述 | tokens |
|------|-------------|--------|
| `get_new_errors(limit?)` | 仅具有以前会话中未见的指纹的错误 | ~1,000 |
| `get_error_trends(fingerprint)` | 指纹的跨会话频率和历史记录 | ~500 |
| `correlate_with_diff()` | 将错误链接到最近的未提交 git 更改 | ~1,000 |
### 执行和健康
| 工具 | 描述 | tokens |
|------|-------------|--------|
| `run_and_watch(command, timeout_seconds?, cwd?)` | 运行测试/检查/类型检查器，获取解析结果。`cwd` 用于 monorepo。 | ~1,000 |
| `get_requests(path?, limit?, status_code_min?)` | 按路径和状态过滤的最近 HTTP 请求 | ~1,000 |
| `get_health_summary()` | 一行健康检查：错误、警告、正常运行时间 | ~100 |
| `verify_fix(duration_seconds?)` | 具有通过/失败判决的整体修复后验证 | ~500 |
| `verify_loop(claim, since?, fingerprint?)` | 具有置信度评分的复合修复验证。折叠 5-7 个调用成 1 个。 | ~300 |
| `wait_for_build(timeout_seconds?)` | 阻塞直到下一个构建完成（事件驱动） | ~200 |
| `wait_for_event(type?, timeout_seconds?)` | 阻塞直到下一个错误/警告/构建/崩溃事件 | ~200 |
| `verify_mcp(command, timeout_seconds?)` | 测试 MCP 服务器启动并响应初始化握手。在更改服务器代码或依赖项后使用。 | ~200 |
### 错误智能
| 工具 | 描述 | tokens |
|------|-------------|--------|
| `get_error_clusters(min_count?)` | 按类型 + 模块路径对错误进行分组。查看代码库中的模式。 | ~500 |
| `get_bug_patterns()` | 跨会话模式：重复、速度、链条、易失、回归。包括 token 成本。 | ~500 |
| `get_prompt_context(fingerprint, max_tokens?)` | 预装的推理包：错误 + 堆栈 + 日志 + 文件上下文。按 token 预算。 | ~3,000 |
| `get_migration_status(framework?)` | 检查待处理迁移。自动检测 alembic/prisma/django/knex。 | ~200 |
| `get_perf_baseline(path?, limit?)` | 按端点划分的 P50/P95/max 响应时间，来自 HTTP 访问日志。 | ~500 |
| `get_audit_trail(limit?, since?)` | 查看此会话的工具使用情况。优化工作流程。 | ~500 |
## 错误解析器
TracePulse 开箱即带有 25 个错误解析器：
**运行时错误：**
- **Node.js** - TypeError、ReferenceError、SyntaxError 等，带有 V8 堆栈跟踪
- **Python** - 带有文件：行提取的回溯
- **Go** - 带有 goroutine 堆栈跟踪的恐慌
- **Java** - 带有 `at` 帧和 `Caused by:` 链的异常
- **Rust** - 带有 `RUST_BACKTRACE` 输出的恐慌
- **JSON** - 结构化日志（pino、structlog JSON、logback）带有 level/message 字段
- **Structlog** - Python structlog 键值格式（ `[info]`、 `[warning]`、 `[error]` 括号）
- **Pydantic** - FastAPI 验证错误、字段必填、类型错误
**构建错误：**
- **TypeScript** - `tsc` 编译器错误（TS####）
- **ESLint** - 带有规则名称的 lint 错误
- **Vite/webpack** - 构建工具错误（模块未找到、转换失败）
- **构建统计** - 模块数量、构建时间来自 Vite/webpack
**测试运行器：**
- **pytest** - FAILED、ERROR、摘要行
- **Jest** - FAIL 头、断言详细信息
- **vitest** - FAIL 文件、Expected/Received
- **Go test** - `--- FAIL`、文件：行错误
- **cargo test** - 测试 FAILED、恐慌、文件：行、摘要
- **JUnit/Maven/Gradle** - Surefire 摘要、Gradle 任务 FAILED、AssertionError
**基础设施：**
- **HTTP 访问日志** - uvicorn、express/morgan、nginx 带有状态和持续时间
- **迁移** - alembic 和 Django 迁移输出
- **npm 审计** - 漏洞严重性摘要
- **覆盖率** - Istanbul/pytest-cov 百分比提取
**后台工作进程：**
- **Celery** - 任务引发/重试/超时/成功
- **Sidekiq** - WARN/ERROR/FATAL 作业事件、完成计时
- **BullMQ** - 作业失败/卡住/完成、队列错误
## 信号评分
每个事件都有一个 `signal_score`（0-100）和 `signal_strength`（高/中/低）：
| 信号 | 分数 | 示例 |
|--------|-------|---------|
| **高** | ≥ 50 | 未处理的异常，带有用户代码堆栈跟踪 |
| **中** | 20-49 | 无堆栈跟踪的错误日志，HTTP 4xx |
| **低** | < 20 | 警告、弃用通知、热重载标记 |
## CLI 用法
```bash
# 单个进程 - 生成并监视
tracepulse start "npm run dev"
```
生成您的开发服务器作为子进程，捕获其 stdout/stderr，并监视错误。TracePulse 管理进程生命周期 - 在关闭时转发 SIGTERM/SIGKILL。
```bash
# 附加到现有日志文件
tracepulse attach --log-file ./server.log
```
附加到现有日志文件而无需生成任何进程。在服务器已经运行时使用 - 由 Docker、tmux、pm2、systemd 或自定义脚本管理。
```bash
# 多进程 - 监视多个服务
tracepulse start --service api="npm run dev:api" --service worker="npm run worker"
```
同时生成多个服务。每个服务的输出都带有其名称 - 使用 `get_errors(service: "api")` 过滤或使用 `list_services()` 查看所有服务。
```bash
# 配置文件
tracepulse start --config tracepulse.config.json
```
从 JSON 配置文件中读取服务定义、传输设置和持久化选项，而不是 CLI 标志。请参阅 [配置](docs/architecture/architecture-guide.md) 获取模式。
```bash
# Docker Compose
tracepulse compose --file docker-compose.yml
```
从 Docker Compose 文件中发现服务，并通过 Docker 引擎 API 附加到它们的容器日志。每个容器的输出都带有其 compose 服务名称。
```bash
# 带有持久化（会话间保存指纹）
tracepulse start --persist "npm run dev"
```
```bash
# 群集模式（7 个网关而不是 44 个工具 - 减少 80% 的模式）
tracepulse start --clustered "npm run dev"
```
将 44 个工具折叠成 7 个语义网关。代理按需发现子工具，仅加载所需内容。模式开销从每回合 ~1,000 下降到 ~200 个 token。
```bash
# 使用 HTTP 传输（用于多客户端场景）
tracepulse start --http "npm run dev"
```
在默认 stdio 传输旁边启动一个 Streamable HTTP 服务器，监听 `127.0.0.1:9800`。允许多个 MCP 客户端同时连接到同一个 TracePulse 实例。
```bash
# 项目设置 - 安装配置、转向、钩子和提示快捷方式
tracepulse init
```
自动检测您的 MCP 客户端（Kiro、Claude Code、Cursor）并：
- **合并** TracePulse 到您的现有 MCP 配置（保留其他服务器）
- **安装** 转向文件和钩子以实现最佳代理行为
- **安装** 提示快捷方式（`@tp-debug`、`@tp-health`、`@tp-test`、`@tp-diagnose`、`@tp-start`）
- **更新** `.gitignore` 以排除 `.tracepulse/` 会话数据
- **检查更新** 以获取最新的 npm 注册表
在更新 TracePulse 后重新运行 `tracepulse init` 以同步最新的转向和提示。
### Kiro 的提示快捷方式
运行 `tracepulse init` 后，这些快捷方式在 Kiro 中可用：
| 快捷方式 | 功能 |
|----------|-------------|
| `@tp-debug` | 调查并修复最新的后端错误 |
| `@tp-health` | 全面项目健康检查：服务器、基础设施、错误、构建 |
| `@tp-test` | 运行测试并修复故障 |
| `@tp-diagnose` | 跨层诊断：关联后端、前端、git、基础设施 |
| `@tp-start` | 启动开发服务器，实时错误监控 |
## 为什么使用 `run_and_watch` 而不是 Shell？
`run_and_watch` 不仅仅是一个方便的功能 - 它解决了真正的可靠性问题：
**结构化输出。** Shell 命令返回原始文本，代理必须解析。`run_and_watch` 返回具有通过/失败计数、错误详细信息和文件：行引用的结构化 JSON。
**WSL 可靠性。** 在 WSL（Windows 子系统 Linux）上，终端输出捕获不可靠 - Kiro IDE 和其他工具通常无法从终端读取测试结果。`run_and_watch` 通过 Node.js 管道捕获输出，并通过 MCP 协议（stdio 上的 JSON-RPC）返回数据，这是一个完全独立于终端的通道。
**Monorepo 支持。** `cwd` 参数在子目录中运行命令，而无需 `cd` 前缀黑客：
```
run_and_watch("npx vitest run", cwd: "./frontend")
run_and_watch("pytest tests/", cwd: "./backend")
```
**解析器管道。** 输出流经 TracePulse 的 25 个解析器，因此测试失败、构建错误和运行时崩溃都标准化为代理已经知道的相同结构化格式。
## 云日志监控
使用零额外依赖项监控云服务日志 - 使用您现有的云 CLI：
| 平台 | 命令 |
|----------|---------|
| **[AWS CloudWatch](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)** | `run_and_watch("aws logs tail /aws/lambda/my-fn --follow")` |
| **[Google Cloud](https://cloud.google.com/sdk/docs/install)** | `run_and_watch("gcloud logging tail '...'")` |
| **[Azure](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)** | `run_and_watch("az webapp log tail --name my-app")` |
| **[Kubernetes](https://kubernetes.io/docs/tasks/tools/)** | `run_and_watch("kubectl logs -f deployment/my-app")` |
| **[Docker](https://docs.docker.com/get-started/get-docker/)** | `run_and_watch("docker logs -f my-container")` |
| **[Heroku](https://devcenter.heroku.com/articles/heroku-cli)** | `run_and_watch("heroku logs --tail --app my-app")` |
| **[Vercel](https://vercel.com/docs/cli)** / **[Railway](https://docs.railway.com/guides/cli)** / **[Fly.io](https://fly.io/docs/flyctl/install/)** | 使用其 CLI 采用相同的模式 |
与本地开发服务器错误相同的 25 个解析器也能捕获云错误。
## 热重载检测
TracePulse 从 8 种开发工具中检测热重载事件：
- **Vite** - 编译成功，HMR 更新
- **webpack** - 编译完成
- **nodemon** - 重启/启动事件
- **Next.js** - 编译，路由编译
- **ts-node-dev** - 重启，编译完成
- **uvicorn** - 文件变更检测，重新加载进程
- **Django** - 文件变更监视，系统检查
- **Flask** - 重启，状态监视，变更检测
当 `watch_for_errors` 检测到热重载时，它会在响应中设置 `hot_reload_detected: true`，以便代理知道服务器实际重新加载了。
## 安全
- 所有日志输出都会被编辑，以隐藏密钥（16种模式：API 密钥、Bearer/JWT令牌、连接字符串、PEM 密钥、GitHub/GitLab/Slack 令牌、GCP 服务账号、Azure 连接字符串、Datadog 密钥），然后才进入管道
- MCP 响应、环缓冲区或诊断输出中没有密钥
- HTTP 端点仅绑定到 `127.0.0.1` - 没有外部访问
- 指纹持久性仅存储哈希值，而不存储原始错误消息
- 除可选指纹持久性外，不写入文件系统
## TracePulse 团队版（即将推出）
**本地：** 您的代理看到您的服务器。 **团队：** 每个代理看到所有服务器。
为您的工程团队部署一个共享的 TracePulse 实例。每个开发者的 AI 代理通过 HTTPS 连接到一台服务器，该服务器：
- **聚合错误**，跨所有开发环境
- **共享指纹** - 如果一个开发者遇到一个错误，每个代理都知道
- **团队审计轨迹** - 查看团队中工具的使用情况和令牌节省
- **集中式偏移检测** - 一个健康检查涵盖共享的预发布环境
- **SSO/API 密钥身份验证** - 企业级访问控制
```json
{
"mcpServers": {
"tracepulse": {
"type": "streamable-http",
"url": "https://tracepulse.internal.company.com/mcp",
"headers": { "Authorization": "Bearer <team-api-key>" }
}
}
}
```
通过 Docker 自主托管，或在 Railway/Fly.io 上一键部署。 [路线图](docs/roadmap/roadmap.md)
## 配套工具
TracePulse 设计用于与以下工具配合使用：
- **[ViewGraph](https://github.com/sourjya/viewgraph)** - 视觉皮层：结构化 UI 感知（DOM，可访问性，布局，注释）
- **[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)** - 运动皮层：浏览器交互（控制台，网络，性能）
TracePulse 是听觉皮层 - 它听到了后端在说什么。一起，代理具有与高级开发者相同的情境意识：看到 UI，在浏览器中操作，听到服务器的声音。
*皮层类比映射到感知-规划-行动模块化架构，该架构在 GUI 代理研究中正式化（[arXiv 2412.13501](https://arxiv.org/abs/2412.13501)， [arXiv 2504.20464](https://arxiv.org/abs/2504.20464)。 ViewGraph 提供感知模块，Chrome DevTools MCP 提供行动模块，TracePulse 提供环境反馈模块。*
## 架构
参见 [docs/architecture/architecture-guide.md](docs/architecture/architecture-guide.md)，获取完整的架构指南和图表。
## 许可证
AGPL-3.0
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器