thoughtdag why 教程:如何在终端一键查到某个文件的 AI 对话史,附 MCP 接入完整指南
thoughtdag why 教程:如何在终端一键查到某个文件的 AI 对话史,附 MCP 接入完整指南
用 Claude Code、Codex 这类 AI 编码工具的人都有同一个困惑:这个文件到底是被哪次 AI 对话改出来的? thoughtdag 的 why 层正是为此而生——在终端运行一条 thoughtdag why <文件路径>,即可一键查出所有碰过这个文件的 AI 对话轮次:什么时候改的、改了什么、当时问了什么、模型怎么回答。它是完全本地、只读的历史查询工具,还可作为 MCP 服务接入你的 Agent,让 AI 在动手改文件前先自查历史。
为什么需要"文件 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深链的结构化结果
配套命令:从"文件"到"原话"再到"完整轮次"
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 把 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):
- Claude Code:写入当前项目的
.mcp.json(项目级作用域,不污染全局) - 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 想做的事。总结一下今天的路线图:
npx thoughtdag why src/lib/api.ts—— 零安装试手npm install -g thoughtdag && thoughtdag index—— 建立本地只读索引thoughtdag why / find / recall—— 文件、原话、轮次三种检索闭环thoughtdag setup mcp—— 让 Agent 自己先查历史再动手
从"文件"出发回到"对话",从"对话"再回到桌面端的可编辑思绪图上继续工作(参考 docs/zh/guides/session-atlas.md)——你的每一次 AI 讨论,都值得被一张地图记住。


