diff-tour - 用资深工程师的视角带你走读一次代码变更

diff-tour 是一个命令行工具，作用是把一次 git 变更变成一份可以按左右方向键逐步翻阅的「导览」。它面向的读者是那些需要读懂别人（或 AI 生成）代码的人：代码能跑通，并不等于读者明白它为什么这么写、评审时该担心什么。据项目自述，diff-tour 想补上的正是这一段——把资深工程师读 diff 时的关注点组织成一条有顺序的讲解路径，而不是丢给你一份变更摘要。

维护者与状态

项目由 init-co-jp 维护，仓库创建于 2026-10-10，最后一次提交在 2026-10-15，最新正式版本为 v0.5.0，发布于 2026-10-15。截至 2026-10-23，仓库获得 274 个星标。

项目自述中明确说明，diff-tour 目前是早期版本，导览的格式与界面仍可能变化。这一点与版本号 v0.5.0 相称，使用前应对界面和输出结构的不稳定有预期。

主要能力

以下内容来自项目 README 的自述，未经独立验证。

• 按「怎么读」组织内容。 导览会说明这次变更的目的是什么、时间该花在哪里、接下来该跳到哪些文件，其中也包括本次没有改动但相关的文件。
• 按「会问什么」组织追问。 README 列举的典型问题包括：改动是否维持了旧代码原有的承诺；失败或重复执行时会发生什么；能否安全上线与回滚；谁能以什么输入调用它；数据量放大到一百倍时会怎样；下一次改动会更容易还是更难；如果代码坏了，测试会不会失败。
• 按「怎么判断」给出结论。 导览会区分哪些问题必须修、哪些只是建议或细枝末节，哪些看起来有风险但其实没问题以及原因，哪些地方做得好，以及这次改动整体上是否让代码库更好。
• 在关键处停下来提问。 这些以问题的形式出现，让读者先自己预测答案，再看讲解。
• 只读。 项目自述 diff-tour 不会修改你的文件或仓库。

据项目说明，上述视角来自经验丰富的工程师关于阅读与评审代码的书面材料，收集在仓库的 internal/generate/lessons 目录中（以日文撰写），LLM 在每次生成导览前会先读取这些材料。

使用入口

仓库地址：init-co-jp/diff-tour。

据 README，使用前需要本机装有 git，并已登录 Claude Code、Codex CLI、Gemini CLI、OpenCode 2 或 Copilot CLI 中的任意一个。安装与启动方式为：

curl -fsSL https://raw.githubusercontent.com/init-co-jp/diff-tour/main/install.sh | sh
cd your-repo
tour

首次运行会进入设置，选择显示语言与负责撰写导览的 LLM，两项都有推荐选项，直接回车即可。随后从列表中选择要导览的变更（默认选中当前分支），LLM 开始撰写，README 称这一过程需要 2 到 5 分钟。完成后用右方向键前进、左方向键后退、q 退出。如果提示找不到 tour 命令，需要把安装脚本打印的那行配置加入 shell profile。

关于工作方式，README 描述为四步：先用 git archive、git diff 和 git log 把相关文件导出到缓存目录中的新目录；再在该目录下以只读权限启动所选 LLM 的命令行工具，按固定提示词撰写导览；然后校验导览 JSON 中引用的每个文件与行号是否存在，有误则让 LLM 只修正该处，最多两次；最后展示导览。屏幕上显示的真实代码始终从 git 对应提交读取，不在仓库中的示例代码会被标注为 Example。导出目录在导览写完后删除，成品导览保存在缓存中，再次打开无需重新生成。

许可与限制

许可证为 MIT。

据项目说明，使用 diff-tour 意味着把代码发送给你选择的 LLM 服务商。发送内容包括：参与比较的两个提交下的仓库文件、diff 与提交信息（仅 git 跟踪的文件，以及在导览未提交改动时未被忽略的未跟踪文件）；internal/generate/prompts 中的提示词；按下 ? 提问时，你的问题与整份导览以及同样的文件。这些内容会按你与该服务商账户的条款处理。项目自述 diff-tour 本身不发起网络请求、没有服务端、不收集遥测。

README 同时说明了 LLM 被禁止做的事：读取导出目录之外的文件（包括真实工作区、.git 与主目录）；读取被 .gitignore 忽略的文件（因为它们从未被导出）；写入、编辑或删除任何文件；执行会改变状态的命令或访问网络；使用 MCP 服务器、插件、扩展或网页搜索。这些限制由 diff-tour 传给各工具的命令行参数强制执行，而不只依赖提示词。

已知的边界条件包括：Codex CLI 的沙箱方案在 Linux 上测试过，macOS 上使用的 Seatbelt 沙箱尚未测试；Gemini CLI 总会把会话保存到 ~/.gemini/tmp，默认 30 天后删除，且无法从命令行关闭。此外，导览生成需要 2 到 5 分钟，属于需要等待的交互方式，不适合追求即时反馈的场景。