thoughtdag why 教程:如何在终端一键查到某个文件的 AI 对话史,附 MCP 接入完整指南

原创2026-11-01 19:28:301,851 阅读

thoughtdag why 教程:如何在终端一键查到某个文件的 AI 对话史,附 MCP 接入完整指南

用 Claude Code、Codex 这类 AI 编码工具的人都有同一个困惑:这个文件到底是被哪次 AI 对话改出来的? thoughtdag 的 why 层正是为此而生——在终端运行一条 thoughtdag why <文件路径>,即可一键查出所有碰过这个文件的 AI 对话轮次:什么时候改的、改了什么、当时问了什么、模型怎么回答。它是完全本地、只读的历史查询工具,还可作为 MCP 服务接入你的 Agent,让 AI 在动手改文件前先自查历史。

Agent 对话地图界面:按项目聚合本机的 Claude Code 与 Codex 会话,一键导入画布

为什么需要"文件 AI 对话史"

想象这个场景:三个月前你让 Agent 修过一个流式输出崩溃,当时改了 src/lib/api.ts。今天再碰这个文件,你已经完全不记得当初的来龙去脉——是重试退避?还是换了限流策略?

传统做法是翻 git log、翻聊天记录、凭印象猜测。thoughtdag why 提供了一条捷径:以文件为起点,反向检索塑造它的对话。它的工作原理是解析本机会话日志中的工具调用(读了哪个文件、写了哪个文件),而不是靠模型自由发挥,所以结果是可核验的事实:

  • 会话文件只读,永远不会被写入或修改
  • 派生索引存放在 ~/.thoughtdag(目录权限 0700、文件 0600),随时可 thoughtdag purge 一键清除
  • 输出区分证据等级:Δ 表示观察到的真实改动,≈ 只是从回答里提取的候选解释,不是已验证的原因

💡 一句话理解:Δ 是"我亲眼看到它改了",≈ 是"它自己说是这么回事"。

快速上手:3 步建立本地 AI 对话索引

第 1 步:零安装试一次查询

想立刻看看效果?无需安装,直接:

npx thoughtdag why src/lib/api.ts

第 2 步:全局安装并建立索引

日常使用建议全局安装,然后构建一次本地索引:

npm install -g thoughtdag
thoughtdag index

index 命令会扫描本机已存在的 Claude Code、Codex、DeepSeek Harness、Pi 会话日志,按"每个轮次读了/写了/编辑了哪些文件"建立索引。之后查询索引过期时会自动增量刷新,无需手动干预。

第 3 步:一条命令查文件对话史

在项目目录下运行:

thoughtdag why src/lib/api.ts

典型输出长这样:

why src/lib/api.ts · 12 turns in 6 sessions
claude-code  ✏️ edit  Q: 免费档模型一用就崩,帮我查
             Δ x = 1 → x = retry(1)
             ≈ 崩溃来自流式输出没有节流,加了重试和退避
             ↗ thoughtdag://open?session=sid-1&turn=u1

如何读懂 why 的输出标记

thoughtdag why 的输出采用一套简洁的标记字典,看懂之后信息密度极高:

标记 含义 信任度
Q 用户问题的原文片段 事实
A Agent 回答的原文片段 事实
M 画布节点所附的文字材料 事实
Δ 从工具调用中观察到的编辑或写入 事实
≈ 从回答中提取的候选解释 不是已核验的原因
↗ 指回来源轮次的深链接(装桌面版可直接点开) —

几个实用技巧:

  • 想连"只读"的轮次也看:加 --include-read,子代理(subagent)的访问也会一并列出
  • 只想知道"有没有历史":thoughtdag why --check <path> 输出一行并返回退出码(0 有 / 1 无),非常适合脚本化,例如在 CI 或 Agent 前置检查中使用
  • 同名文件多处匹配:加 --all 放宽工作区范围,或直接看候选列表挑一个
  • 要机器可读:加 --json,拿到带 locators、open 深链的结构化结果

ThoughtDAG 上下文图:对话、材料与引用组成可编辑的思绪地图,节点可分支与重算

配套命令:从"文件"到"原话"再到"完整轮次"

why 回答"谁碰过这个文件",另外两条命令补齐检索闭环(源码见 cli/src/lib.ts):

find:按原话找对话

thoughtdag find "流式输出没有节流" --in a

精确、不区分大小写地检索这些词在哪里被问过(q)、答过(a)、附上过材料(m)。每个命中都是原文片段加指针。

recall:完整回放某一轮

从 why/find 输出里复制会话 id 与轮次编号:

thoughtdag recall sid-1 0

完整打印这一轮的问题、回答、工具调用及其 diff。

status / purge:查看与清理

thoughtdag status    # 索引规模 + 证据覆盖率(多少改动有观察到的变更头)
thoughtdag purge     # 删除全部派生数据(原始会话不受影响)

完整命令表与更多示例,见官方文档 docs/guides/why-layer.md(中文版 docs/zh/guides/why-layer.md)。

MCP 接入教程:让 AI 改文件前自己查历史

在真实 ThoughtDAG 界面中选中回答文字,选择探索并建立新的对话分支

thoughtdag 把 why 层的四个问题封装成 MCP(Model Context Protocol)只读服务,让你的 Agent 自己调用。工具定义见 cli/src/lib.ts:

MCP 工具 参数 返回内容
why_check path 一行说明该对象有无历史
why_file path,可选 include_read、limit 命中的轮次与观察到的文件改动
find phrase,可选 in、limit 问题/回答/材料中的精确命中
recall_turn session、turn 一轮完整的问题、回答与工具轨迹

最快方式:一条命令自动注册

在你要使用的项目目录里运行:

thoughtdag setup mcp

它会自动完成两件事(实现见 cli/src/main.ts):

  1. Claude Code:写入当前项目的 .mcp.json(项目级作用域,不污染全局)
  2. Codex:在 ~/.codex/config.toml 追加一个带标记的 [mcp_servers.thoughtdag] 块(只写一次)

想再进一步,让 Agent 养成"改文件前先查历史"的习惯:

thoughtdag setup rules        # 向 CLAUDE.md 与 AGENTS.md 加入带标记的两条规则
thoughtdag setup rules --remove   # 随时完整移除

写入的规则核心就两条:编辑文件前先跑 why --check,报告有历史就读完再改;被问"代码为什么这样写"时先查询、后读码。

手动配置:其他支持 stdio 的 MCP 客户端

手动配置可参照仓库里的示例文件 mcp.config.example.json,把 thoughtdag 加进 mcpServers:

{
  "mcpServers": {
    "thoughtdag": {
      "command": "npx",
      "args": ["-y", "thoughtdag@0.2.2", "mcp"]
    }
  }
}

注意事项:

  • 需要 Node.js 20 或更新版本
  • 请在目标项目目录下启动,这样文件查询才能按预期工作区解析相对路径
  • 服务本身只读:它能检索与回忆,不能编辑画布或源会话

隐私与数据安全要点

thoughtdag 在设计上把"不越界"做成了默认行为:

  • 原始会话只读:索引、缓存全部是派生数据,存在 ~/.thoughtdag,purge 即焚
  • 索引不含自由文本答案:事实层只存工具调用产生的客观事实,不泄漏完整回答
  • 查询过期自动刷新:新对话追加后,下一次 why 查询会自动增量刷新索引并提示你,并发查询由文件锁保护,不会互相踩坏
  • 提示一点:MCP 检索到的历史文本会返回给调用的 Agent,可能进入其模型上下文。若会话涉及私密内容,请先确认你的客户端与模型服务商设置

端到端的信任性质(文件权限、事实不泄漏、并发安全等)都有可复现的自动化测试覆盖,见 cli/test/why.test.mjs。

写在最后

把 AI 对话史从"凭记忆"变成"一条命令",就是 thoughtdag why 想做的事。总结一下今天的路线图:

  1. npx thoughtdag why src/lib/api.ts —— 零安装试手
  2. npm install -g thoughtdag && thoughtdag index —— 建立本地只读索引
  3. thoughtdag why / find / recall —— 文件、原话、轮次三种检索闭环
  4. thoughtdag setup mcp —— 让 Agent 自己先查历史再动手

从"文件"出发回到"对话",从"对话"再回到桌面端的可编辑思绪图上继续工作(参考 docs/zh/guides/session-atlas.md)——你的每一次 AI 讨论,都值得被一张地图记住。

登录后查看全文
thoughtdag