## 安装
```
cd your-project
npx treetrace
```
Node.js 18 或更高版本。TreeTrace 没有运行时依赖，因此 `npx treetrace` 不需要额外安装任何东西。无需账户，不上传数据，无遥测。你的记录永远不会离开你的机器。
## 为什么存在
Git 历史记录展示了发生了什么变化。TreeTrace 展示了工作实际上是如何完成的。
编码和 CLI agent 的会话包含了你生成的最有用的引导数据：模型在哪里误解了目标，哪次纠正修复了它，哪个分支被放弃了，什么约束一直被忽略，agent 被拒绝或拒绝了什么，以及应该保留什么以便下一次会话不会重复这些浪费。这些数据在会话结束后就会消失。TreeTrace 在本地将其捕获为结构化的、供应商中立的记录。
## 一条记录能实现什么
一条记录。多种用途。
### 今天
|
**模型训练数据**
真实的纠正成为回归 evals。无需 LLM judge。
|
**开发与 token 效率洞察**
查看返工的成本以及哪里需要引导。
|
### 未来发展方向？
|
**合规与 GRC**
关于 agent 做了什么以及被拒绝了什么的、经过脱敏和签署的记录。目前尚不支持此功能——正在为此奠定基础。
|
## 捕获内容
TreeTrace 读取编码和 CLI agent 会话（Claude Code、Codex、Cursor、Copilot、ChatGPT 导出、Gemini、Grok）并提取：
- **Prompt 谱系** - 节点、边、父链以及 prompt 类型（根节点、方向指引、纠正、范围变更、检查点、提问、拒绝）
- **Token 使用量** - 每个会话的输入和输出 token 计数（适配器覆盖范围有所不同；参见下方的矩阵）
- **使用的模型** - 哪个模型处理了每一轮对话
- **工具与文件** - 每一次工具调用及触及的文件路径
- **人类引导** - 纠正、范围变更、检查点以及放弃的分支
- **拒绝与驳回** - 分类的拒绝事件：`user_declined_tool`、`user_interrupt`、`user_text_decline`、`tool_execution_error`、`permission_denied`、`model_refusal`
- **失败任务** - 包含类型、置信度分数、证据文本和来源节点 ID 的失败信号
- **时间戳** - 跨所有适配器的会话首个和最后时间戳
### 按适配器划分的信号覆盖范围
信号覆盖范围取决于每个工具导出的内容。下方的矩阵反映了实际的源代码 (v0.10.0)；标记为 `--` 的单元格已确认缺失。使用 `--from transcript` 导入的普通 `User:` / `Assistant:` 记录也能捕获 prompt 谱系、纠正、模型拒绝以及用户驳回。
| 信号 | Claude Code | ChatGPT | Codex | Cursor | Copilot | Gemini | Grok |
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| Prompt 谱系 | 完整 | 完整 | 完整 | 完整 | 完整 | 完整 | 完整 |
| 输入 tokens | 完整 | -- | 完整 | -- | -- | 部分 | -- |
| 输出 tokens | 完整 | -- | 完整 | -- | -- | 部分 | -- |
| 美元成本 | -- | -- | -- | -- | -- | -- | -- |
| 缓存 tokens | -- | -- | -- | -- | -- | -- | -- |
| 使用的模型 | 完整 | 部分 | 完整 | 部分 | 部分 | 部分 | 部分 |
| 工具使用 | 完整 | 部分 | 完整 | 完整 | 完整 | 完整 | 部分 |
| 触及的文件 | 完整 | -- | 完整 | 完整 | 完整 | 完整 | -- |
| Bash 命令 | 完整 | -- | 部分 | 部分 | 部分 | 部分 | -- |
| 拒绝 / 驳回 | 完整 | 部分 | 部分 | 部分 | -- | 部分 | -- |
| 思考 / 推理块 | 部分 | -- | 完整 | -- | -- | 完整 | -- |
| 时间戳（首个/最后） | 完整 | 部分 | 部分 | 部分 | 部分 | 部分 | 部分 |
| 每轮延迟 | -- | -- | -- | -- | -- | -- | -- |
| 纠正 / 范围变更 | 完整 | 完整 | 完整 | 完整 | 完整 | 完整 | 完整 |
| 分类拒绝 | 完整 | 部分 | 部分 | 部分 | -- | 部分 | -- |
拒绝捕获：Claude Code 为 `完整`（通过文本和 stop-reason 实现的模型拒绝、用户驳回、工具权限被拒）；ChatGPT、Codex、Cursor 和 Gemini 为 `部分`（assistant 文本形式的模型拒绝）。Copilot 和 Grok 导出目前不提供拒绝信号。
**单元格说明：** `完整` - 已提取并存储在 schema 字段中。`部分` - 在源格式暴露该信息处已提取。`--` - 未捕获；在源代码中确认缺失。
Claude Code（原生 JSONL）是最丰富的数据源：它涵盖所有拒绝类型、思考块、基于消息 ID 的 token 去重，以及来自工具输入的文件路径。所有其他适配器都能捕获 prompt 谱系和纠正；token 和拒绝的覆盖情况则各不相同。
## 准确性
TreeTrace 的分析层在一个包含 40 个场景的随机种子真值基准上进行了验证。每个场景将一个真实信号与一个良性干扰项配对，因此该基准衡量的是精确率和召回率，而不仅仅是覆盖率。盲测保留集被排除在开发之外，因此报告的准确性反映的是泛化能力，而不是记忆能力。每个结果都在提交的代码上重现，并且完整的测试套件为每次变更把关。
| 指标 | 结果 |
| --- | --- |
| 盲测保留集 F1 | **0.93**（从 0.72 提升） |
| 误报（基准） | **40 → 18**（减少了一半以上） |
| 分析层精确率 / 召回率 | 0.95 / 0.97 |
| 单元测试 | **166 / 0** |
| 场景 / 盲测拆分 | 40 / 2 |
检测器是确定性的、精确匹配的规则，这些规则针对已发布的分类法进行了调优，并按信号类别（纠正和驳回、凭据和安全暴露、幻觉文件引用、破坏性操作以及经验教训质量）进行独立评分。精确率在每一步都得到保持或提升，因此该工具不会为了覆盖率而牺牲误报率。
## 输出
| 产物 | 用途 |
|----------|---------|
| `TREETRACE_REPORT.md` | 组合的人类可读报告，用于审查、终端展示及聊天交接 |
| `PROMPT_TREE.md` | 人类可读的构建路径叙述 |
| `.treetrace/tree.json` | 标准的机器可读谱系 schema |
| `.treetrace/failures.json` | 失败信号、纠正链及摘要 |
| `.treetrace/rejections.json` | 分类的拒绝、拒执、驳回、工具错误和权限被拒事件 |
| `.treetrace/hallucinations.json` | agent 引用但在工作树中不存在的文件、路径、import 和 package |
| `.treetrace/lessons.md` | 人类可读的未来工作经验教训 |
| `.treetrace/evals.jsonl` | 通用的、模型无关的 eval 用例 |
| `.treetrace/agent-memory.md` | 用于 Codex、Claude Code、Cursor 或其他 agent 的紧凑内存包 |
| `PROMPT_TREE_GRAPH.md` | 通过 `treetrace --graph` 生成的 branded Mermaid 提示树状图；可在 GitHub 上免费渲染且无依赖，大型项目会自动进行摘要 |
| `treetrace --handoff` | 打印到 stdout 的、agent 可直接使用的续接简报 |
逐步工作原理
1. **发现本地记录。** Claude Code 会话文件会自动从 `~/.claude/projects/...` 中发现；普通记录可以通过 `--file` 或 `--stdin` 导入。
2. **提取 prompt 谱系。** 过滤或折叠工具噪音、斜杠命令包装器、侧链闲聊、重复重发以及“continue”等催促信息。
3. **构建具备分支感知能力的树。** 从提示拓扑结构和用户文本中推导出纠正、范围变更、检查点、提问、放弃的分支以及接受的路径。
4. **分析失败、拒绝和纠正。** TreeTrace 使用透明的启发式方法添加失败信号、分类的拒绝/拒执事件、纠正链、经验教训以及 eval 候选项。
5. **导出结构化产物。** 在本地写入 JSON、Markdown、JSONL 和交接记忆，供 agent、CI、eval harness 和人类使用。
6. **以脱敏作为每次导出的门控。** 在写入任何内容之前必须解决检测到的 secret；非交互式运行会自动进行脱敏，并对渲染输出进行影子扫描。
所有命令
| 命令 | 功能说明 |
|---------|--------------|
| `npx treetrace` | 追踪此项目并写入所有产物 |
| `npx treetrace --report` | 写入所有产物并打印人类可读报告 |
| `npx treetrace --handoff` | 打印 agent 可直接使用的续接简报 |
| `npx treetrace --file session.jsonl` | 导入特定的会话或记录文件（自动检测格式） |
| `npx treetrace --from chatgpt --file conversations.json` | 以显式格式导入其他工具的导出文件 |
| `npx treetrace --stdin < chat.txt` | 解析粘贴的 `User:` / `Assistant:` 记录 |
| `npx treetrace --failures` | 写入并打印 `.treetrace/failures.json` |
| `npx treetrace --rejections` | 写入并打印 `.treetrace/rejections.json` |
| `npx treetrace --lessons` | 写入并打印 `.treetrace/lessons.md` |
| `npx treetrace --evals` | 写入并打印 `.treetrace/evals.jsonl` |
| `npx treetrace --memory` | 写入并打印 `.treetrace/agent-memory.md` |
| `npx treetrace --graph` | 写入 `PROMPT_TREE_GRAPH.md`，这是一个 branded Mermaid 状图，可在 GitHub 上免费渲染且无依赖；大型项目会自动进行摘要，且 `--full` 或 `--summary` 可强制指定模式 |
| `npx treetrace --security` | 打印聚焦安全的报告并写入 `.treetrace/hallucinations.json` |
| `npx treetrace --each` | 将每个会话的完整报告包写入 `--out-dir`（默认为 `treetrace-reports/`），以及 `INDEX.md 和 `index.json` 清单；自动对每个包进行脱敏并在遇到问题时安全关闭 |
| `npx treetrace --deterministic` | 锁定生成时间戳，以便在同一会话上重新运行时生成字节完全相同的产物 |
| `npx treetrace mcp` | 通过 stdio 启动只读 MCP server |
| `npx treetrace --titles-only` | 紧凑的人类可读树，无完整的 prompt 细节 |
| `npx treetrace --redact-auto` | 无需提示即可对每个检测到的 secret 进行脱敏 |
| `npx treetrace --since 2026-06-01` | 限定在指定日期或之后的会话 |
对于 Terminus、Codex CLI、Claude Code 或 SSH 会话，如果你希望在终端窗口中查看报告，请使用 `npx treetrace --report --redact-auto`。如果既需要终端输出，又想要一份额外被 shell 捕获的副本，请通过管道传输：`npx treetrace --report --redact-auto | tee treetrace-output.md`。
**终端输出模式（`--graph`、`--full`、`--summary`）：** 这三个标志会激活终端图形模式，该模式在写入 `PROMPT_TREE_GRAPH.md` 后会提前返回。它们不能与 `--report` 或 `--analysis` 组合使用：当它们中的任何一个存在时，图形将被写入并且运行停止——其他输出将被跳过。`--full` 和 `--summary` 控制图形的详细程度（完整节点展开与仅限主干的摘要），而不是控制写入哪些产物。请将运行图形作为独立的调用，与任何报告或分析过程分开。
如果你看到一个字面名为 `output` 的文件，通常来源于 `--out output` 或 shell 重定向（如 `> output`）。推荐使用 `TREETRACE_REPORT.md` 供人类阅读，并将 `.treetrace/*.json` / `.jsonl` 留给工具使用。
## 拒绝与拒执
`treetrace --rejections` 会写入 `.treetrace/rejections.json`，这是一个按时间戳排序的分类人类和环境停止信号账本。原生 Claude Code JSONL 捕获目前可以识别：
- `user_declined_tool` - 人类拒绝了提议的工具使用
- `user_interrupt` - 人类在响应中途打断了 agent
- `user_text_decline` - 人类输入了诸如“stop, don't do that”的驳回文本
- `tool_execution_error` - 工具结果返回了执行错误
- `permission_denied` - 环境拒绝了访问或权限
- `model_refusal` - 模型拒绝了请求
每个条目都包含源节点 ID、类型、来源、置信度、时间戳、可选的工具使用 ID 以及脱敏后的证据。拒绝也会作为失败信号、经验教训和 eval 候选项呈现，因此被拒执或拒绝的路径会成为与安全和范围纠正相同的“从失败到 eval 再到交接”闭环的一部分。
## 安全报告
`treetrace --security` 打印一份以具体失败分类为先的安全聚焦报告。它复用了与完整运行相同的分析，并回答了五个问题：
1. agent 是否涉及了 auth、secrets、访问控制、加密、依赖配置、CI、部署或测试？
2. 它是否禁用或跳过了测试？
3. 它是否运行了高风险的 shell 命令？
4. 它是否引用了不存在的文件、路径、import 或 package？
5. 什么样的人类纠正应该成为未来的 eval 或记忆项？
这是一个真实的例子，来自一个 agent 构建 API key auth 的实际会话 (`examples/api-key-auth/`)：
```
# TreeTrace 安全报告 - api-key-auth
## 触及的 Surfaces
- secrets: src/auth/apiKey.js [node_001, node_002]
## 安全信号（最高层级优先）
- (high) [node_003] risky command: "git commit -am 'wip' --no-verify && git push --force"
- (stated intent) [node_001] human security correction: "No, do not hardcode the
secret in the source. Read the API key from an environment variable instead."
## 测试跳过
- (node_003) "The auth tests are failing. Just skip the auth tests for now so we can ship."
## 幻觉引用
- (hallucinated_file_or_path) [node_001] "./src/middleware/rateLimit.js" does not exist
- (hallucinated_import_or_package) [node_001] "jsonwebtoken" is not a declared dependency
## 待推广的修正
- (node_002) "Read the API key from an environment variable instead." -> eval candidate
```
每一行都是你可以核对的带有节点 ID 的透明启发式规则。没有任何模型渲染出那个结论。报告会输出到 stdout，并且运行时会写入 `.treetrace/hallucinations.json`；两者在打印或写入任何内容之前都会通过脱敏影子扫描。完整版本：[examples/api-key-auth/SECURITY_REPORT.md](examples/api-key-auth/SECURITY_REPORT.md)。
确定性幻觉检测
TreeTrace 在代码仓库内部运行，因此它可以对照实际存在的内容验证 agent 的声明。它提取在 prompt 和捕获的操作中引用的文件、路径、import 和 package，然后根据真实的工作树和清单文件（`package.json`、`package-lock.json` 和 Python 依赖文件）进行检查。无法解析的引用会被分为两类进行标记：
- `hallucinated_file_or_path`
- `hallucinated_import_or_package`
每一项都会成为一个 eval 候选项，例如“在编辑之前验证文件或 import 是否存在”。这些检查是完全确定性的：文件和路径的存在性，以及 import 和 package 的声明。文件引用包括具有已知扩展名的路径、常见的无扩展名文件（如 `Dockerfile`、`Makefile`、`README` 和 `.env`），以及包含斜杠的本地路径（如 `src/route`）。为了避免误报，agent 在会话期间创建的文件、相对路径、Node 内置模块和 Python 标准库模块会被排除，像 `JSON.parse` 或 `test.skip` 这样的普通带点代码符号不会被视为路径，已知的文件名词汇只有在附近存在文件操作动词时才会被标记。
这对它的局限性是诚实的。文件、路径、import 和 package 的存在性检查是可靠的。不会尝试对模块内的每个符号和 API 进行解析，因为这需要 AST 和语言工具链，这将打破零依赖的承诺。TreeTrace 不声称能够检测到真实模块上出现幻觉的函数或方法。
失败分析与类型
TreeTrace 并不声称能完美理解每一个会话。第一遍的分析是启发式的且可解释的：每个失败信号都包含类型、置信度分数、证据文本和源节点 ID。
初始的失败类型包括 `ignored_constraint`、`misunderstood_goal`、`scope_drift`、`wrong_tool_choice`、`hallucinated_file_or_api`、`repeated_failed_fix`、`overbuilt_solution`、`underbuilt_solution`、`security_or_privacy_risk`、`dependency_or_environment_mismatch`、`format_violation`、`user_frustration`、`abandoned_path`、`user_rejected_action`、`tool_execution_failed`、`model_refused` 和 `permission_denied`。
目标不在于评判。目标在于建立一份结构化记录：识别出未来的 agent 应该保留什么、避免什么或测试什么。
## Eval 导出
`.treetrace/evals.jsonl` 将真实的会话纠正转化为通用的 eval 用例：
```
{"id":"eval_001","source":"treetrace","type":"scope_drift_detection","task":"Continue development without drifting outside the corrected scope.","expected_behavior":["Stay inside the corrected scope","Do not add unrequested product surfaces"],"sourceNodeIds":["node_002","node_003"]}
```
该格式是故意设计为模型无关的。适用于 promptfoo、OpenAI Evals 风格 harness、LangSmith 风格数据集和其他 eval 系统的适配器可以基于此 JSONL 进行构建，而无需更改 TreeTrace 的本地优先核心。
## MCP server
`treetrace mcp`（或 `treetrace --mcp`）通过 stdio 启动 Model Context Protocol server。它使用 JSON-RPC 2.0 进行通信，手动编写且无任何依赖，并实现了 `initialize`、`tools/list` 和 `tools/call`。它暴露了六个只读工具，每个工具都复用了现有的功能：
- `handoff` - 给下一个 agent 的续接简报
- `lessons` - 接受的约束和重复的纠正
- `security_summary` - 有证据支持的安全敏感操作
- `eval_candidates` - 紧凑的回归测试用例
- `tree` - 标准的 prompt 谱系 JSON
- `rejections_summary` - 分类的拒绝、拒执、驳回、工具错误和权限被拒事件
没有任何工具会修改文件、运行 shell、连接网络或需要身份验证。每一段返回的文本都会通过与文件导出相同的脱敏影子扫描。使用 `--dir` 将其指向一个项目，或使用 `--file` 导入记录。MCP server 使用 stdin 作为其 JSON-RPC 传输通道，因此在 MCP 模式下无法使用 `--stdin` 记录粘贴；请改用 `--file`。
脱敏门控
一个注重隐私的工具对于你的 secret 只有一次机会，因此每一次导出都会经过相同的门控：
- 精心策划的针对 AWS、GitHub、GitLab、Anthropic、OpenAI、Slack、Stripe、npm、Tailscale、Google、SendGrid、Twilio、Telegram、Discord webhooks、JWTs、私钥块、WireGuard 密钥、基本认证 URL、bearer tokens 以及 secret 赋值的提供商规则。
- 针对未知 token 形状的高熵回退机制。
- 对常见的换行提供商 token 的检测。
- 在 TTY 中对每个唯一的命中结果进行交互式审查。
- 在 TTY 之外自动脱敏。
- 在写入之前对渲染的产物进行影子扫描。
- `.treetrace/redactions.json` 仅存储内容哈希和操作，绝不存储原始 secret。
支持的来源与适配器
TreeTrace 会自动读取 Claude Code，并可通过 `--file` 导入其他工具的数据。当你传递一个 `.json` 或 `.jsonl` 文件时，格式会被自动检测；你也可以使用 `--from ` 强制指定。所有数据都保留在本地，并经过相同的脱敏门控。通用的 `User:` / `Assistant:` 记录解析器仍作为无法识别内容的后备方案。
已验证意味着该适配器已经针对真实的会话或真实的公开导出数据进行了验证。实验性意味着它是根据工具文档记载的导出 schema 构建的，并针对该确切结构中的测试夹具进行了验证，但尚未针对捕获的真实会话进行验证。有关每个夹具的来源，请参见 [test/fixtures/adapters/PROVENANCE.md](test/fixtures/adapters/PROVENANCE.md)。
| 来源 | `--from` | 状态 |
|--------|----------|--------|
| Claude Code (`~/.claude/projects` JSONL) | `claude` | 内置，零配置，已验证 |
| Codex CLI (`~/.codex/sessions/.../rollout-*.jsonl`) | `codex` | 已针对真实会话验证 |
| ChatGPT / OpenAI 账户导出 (`conversations.json`) | `chatgpt` | 已针对真实的公开导出样本验证 |
| Google Gemini CLI 会话 (ChatRecordingService JSON) | `gemini` | 已针对真实的 gemini-cli 会话文件验证 |
| GitHub Copilot Chat 会话 (`chatSessions/*.json`) | `copilot` | 已针对真实的公开会话样本验证 |
| Cursor 导出的聊天 JSON | `cursor` | 已针对导出 schema 验证（见说明） |
| xAI Grok 导出的对话 JSON | `grok` | 实验性，根据导出器 schema 构建 |
| 粘贴 / 纯文本记录 (`User:` / `Assistant:`) | `transcript` | 内置后备 |
**为什么 TreeTrace 不读取 SQLite。** Cursor 将其聊天内容存储在 `state.vscdb` SQLite 数据库中，常见的 Grok CLI 也将历史记录保存在 SQLite 中。该原始数据库内容丰富：它保存了真实的文件 diff、推理过程、被拒绝的编辑以及附件上下文。TreeTrace 刻意不读取它，因为零运行时依赖的承诺是一项功能，而不是偶然。目前无需安装额外组件、更小的供应链和攻击面，以及一个注重隐私或安全团队可以一次性审计的工具，比额外的信号更为重要。因此，Cursor 适配器改为吸收导出的聊天 JSON：首先将你的 Cursor 聊天导出为 JSON（例如使用社区的 Cursor 聊天导出器），然后运行 `treetrace --from cursor --file your-chat.json`。
## Schema
`.treetrace/tree.json` 使用了在 [SCHEMA.md](SCHEMA.md) 中记录的 TreeTrace v0.3 schema。它被设计为可与 Agent Trace 组合：Agent Trace 可以描述哪些代码行是由 AI 生成的，而 TreeTrace 则描述塑造了构建过程的人类指令谱系。消费者应忽略未知字段；失败信号、拒绝事件、纠正链、经验教训和 eval 候选项都是可累加的。
## 示例
请参阅 [examples/](examples/) 以查看通过运行 CLI 且未经手动编辑而生成的产物。已提交的示例是为 v0.9.1 重新生成的版本快照；页脚以及自上一版本以来引入的任何 schema 字段均反映当前发布版本。
- [examples/weather-dashboard](examples/weather-dashboard) 展示了一次干净会话中的谱系和脱敏门控。
- [examples/api-key-auth](examples/api-key-auth) 展示了 [`--security` 报告](examples/api-key-auth/SECURITY_REPORT.md)、[拒绝捕获](examples/api-key-auth/.treetrace/rejections.json) 和 [幻觉检测](examples/api-key-auth/.treetrace/hallucinations.json) 在一次涉及 auth、硬编码 secret、跳过测试、强制推送、引用缺失文件以及 import 未声明的 package 的会话中是如何被触发的。
- [examples/rejections](
标签：AI编程助手, MITM代理, SOC Prime, 安全测试, 开发工具, 攻击性安全, 时序数据库, 暗色界面, 本地化, 自定义脚本
