需要把代码库问题、功能、概念或待合并 PR…

当你需要以引导式代码漫游回答代码库问题、解释功能/概念或审查 PR，并在浏览器中分步导航和高亮代码时使用。

适用场景

解决思路

1. 接收必填参数 question，它可以是用户问题、主题、概念或 GitHub PR URL；示例：`/diffity-tour how does authentication work?`、`/diffity-tour explain the request lifecycle`、`/diffity-tour how are comments stored and retrieved?`、`/diffity-tour closures`、`/diffity-tour React hooks`、`/diffity-tour walk me through this branch before I merge`、`/diffity-tour https://github.com/owner/repo/pull/123`。
2. 若 question 是 GitHub PR URL（匹配 `github.com/owner/repo/pull/N`），导览自动锁定为 Review 模式；由 PR 的 diff 驱动范围，结论必须包含 PR-flags 列表。
3. 检查 `{{binary}}` 可用：运行 `which {{binary}}`；若未找到，执行 `{{install_hint}}`。
4. 若参数是 GitHub PR URL：检查 `gh` 已安装并认证，运行 `gh auth status`；若未认证，停止并让用户运行 `gh auth login`。
5. 若参数是 GitHub PR URL：验证当前仓库匹配 PR 仓库，运行 `gh repo view --json nameWithOwner -q .nameWithOwner`，确认与 URL 中 `owner/repo` 一致；不一致则停止并告知用户需在 PR 的仓库克隆内。
6. 若参数是 GitHub PR URL：启动 diffity，用 Bash 工具以 `run_in_background: true` 运行 `{{binary}} --no-open <pr-url>`；`--no-open` 必须在 URL 之前，否则 commander 的 `passThroughOptions()` 会把 URL 后的 flag 吞入 refs 数组，跳过 PR 处理并产生 `unknown ref` 错误；该命令会本地检出 PR 分支并启动 diff-scoped session；等待 2 秒，运行 `{{binary}} list --json` 获取端口；无需额外 tree 实例，diff session 支持 `agent tour-*`。
7. 否则确保 tree 实例运行：运行 `{{binary}} list --json`；若无实例运行，用 Bash 工具以 `run_in_background: true` 运行 `{{binary}} tree --no-open`，等待 2 秒，再运行 `{{binary}} list --json` 获取端口。
8. 在做任何工具调用前先选择模式；若参数是 GitHub PR URL，跳过决定，锁定 Review 模式。
9. 模式选择：Focused 用于窄的「how does X work?」问题，按一个代码路径限定，目标 3-6 步；Feature 用于「how does this feature work?」，按功能边界限定，目标 6-10 步；System 用于「how does the whole thing work?」，按架构限定，目标 8-15 步；Concept 用于编程概念，按代码中示例限定，目标 3-8 步；Review 用于合并前审计分支/PR/功能，按 `git diff <base>..HEAD` 限定，步数可变，覆盖每个有意义的变更。
10. 模式触发词：Focused 为“how does X validate”“walk me through the Y endpoint”；Feature 为“how does authentication work”“explain the comment system”；System 为“how does the app work”“give me the architecture overview”；Concept 为单独概念名（`closures`、`React hooks`、`async/await`、`generics`）；Review 为“before I merge”“review this branch”“walk me through the whole feature”“audit this PR”“I'm about to merge”。
11. 若多个模式匹配，优先更具体的：Review > Concept > Focused > Feature > System；若确实无法判断用户想要哪个模式，先询问再研究，不要猜测并产出错误形状。
12. 模式决定本技能哪些章节适用：Concept 模式读 Concept tours 章节；Review 模式读 Review tours 章节；Focused/Feature/System 模式直接应用默认 Phase 1-3。
13. Phase 1 第 1 步：确认范围；模式设定大致步数；若问题太宽以致不适合该规模，缩窄到最重要方面，并在 intro 中说明覆盖什么、不覆盖什么。
14. Phase 1 第 2 步：识别受众；若问「How does X work?」假设读者对此代码库陌生，解释架构决策而非仅代码机制；若问「Why does X do Y?」假设读者在调试或审查，关注推理和边界情况；若问「Walk me through X」假设读者想要全貌，要详尽并包含上下文。
15. Phase 1 第 3 步：研究代码库；彻底阅读相关源文件，从入口点到完成跟随代码路径。
16. 对 review tours 尤其：读 `git log --reverse <base>..HEAD`，打开提交消息描述非显然修复、重构或防御性变更的提交；作者自己的叙述常是 why 的最佳来源；在步骤正文中引用或转述提交理由。
17. 当导览 GitHub PR 时，用 `gh` 获取元数据和 diff：`gh pr view <url> --json title,body,baseRefName,headRefName,commits,files` 获取 PR 标题、正文、base/head 分支、提交列表、变更文件列表；PR 正文常含最丰富的 why，在 intro 中引用或总结。
18. 用 `gh pr diff <url>` 获取定义导览范围的 unified diff，确认完整表面积，而不只是 `git diff` 所见。
19. 使用 PR 的 `baseRefName`（来自上述 JSON）作为 diff base，不要默认 `master`/`main`；`git log --reverse <baseRefName>..<headRefName>` 按作者顺序走 PR 提交；源文件可从工作树读取，因为 `{{binary}} <pr-url>` 已本地检出 PR 分支。
20. Phase 1 第 4 步：识别讲清故事的关键位置——用户需要看到的文件和行范围。
21. Phase 1 第 5 步：注意配置依赖；若行为随环境变量、feature flags、配置文件或运行时条件变化，标出它们；在导览中说明「当 X 配置时如此，若 Y 设置则此处流程不同」。
22. Phase 1 第 6 步：规划逻辑步骤序列，逐步建立理解；每步自然引出下一步。
23. 选择步骤指南：从真实入口点开始——外部输入到达处（HTTP 路由、CLI 命令、计划任务、webhook）；配置、schema、常量、helper 不是入口点，而是流程依赖。
24. 选择步骤指南：及时引入基础——流程第一次读 schema 时导览 schema，第一次调用 helper 时导览 helper，第一次引用配置值时导览配置；不要前置基础 Prelude。
25. 选择步骤指南：最多一个 orientation 步（如显示所有端点的路由表）可先于入口点；其他一切都应被读者刚看到的内容驱动；按实际发生顺序跟随执行路径；只包含理解必要的位置，跳过样板；以最终结果结束（响应发送、数据持久化、UI 渲染）；每步覆盖单一概念或代码段；尽可能包含具体例子（如「当用户运行 `{{binary}} main`，这变成……」）。
26. 自顶向下，而非自底向上：导览镜像运行时，不是构建过程；不要走 config → schema → helpers → routes → actions，而要走 route → action →（此处出现 schema 因为查询读取它）→（此处出现 config 因为 handler 引用它）→（此处出现 helper 因为某处调用它）；读者在每块新内容变得相关时引入，保留上下文更好。
27. 处理跨模块流程：当代码路径进入库、工具模块或深层抽象时，若逻辑对理解答案必要则跟随；若模块做标准或众所周知的事，则总结（如「这调用 Express router，它匹配路径并调用我们的 handler」），在步骤正文提及但不单独设步；若纯样板或管道（re-exports、type-only files），则跳过。
28. 跨多文件重复模式：当单个变更复制到 N 个相似调用点（同一 guard 加到 8 个 handler、同一 middleware 注册到每个路由），不要做 N 步；对最代表性文件做一步并给完整上下文，然后在正文列其他调用点为 goto 链接；一个概念一步。
29. 重复模式的例外：若某个应用与其他细微不同（如 transfer flow 中调用两次，或参数不同），为它单独一步。
30. Phase 2 第 1 步：用短 topic 和 intro body 启动导览：`{{binary}} agent tour-start --topic "<short title>" --body "<intro>" --json`。
31. `--topic` 显示在导览面板头；保持 3–6 词（如 “Authentication Flow”“How Routing Works”“Comment System Architecture”）；不要把用户完整问题当 topic。
32. 写 intro body（step 0）：这是读者第一眼看到的内容，填满整个解释面板；用它写详尽架构总览，包含关键组件/包/模块及职责、它们如何连接（数据流、调用链或依赖关系）、读者应知道的关键抽象或模式、用粗体文本写摘要流程图（如 **CLI args → git diff → parser → JSON API → React render**）、配置上下文（若功能行为依赖配置、环境变量或 feature flags，在此提及，让读者知道导览假设的模式/状态）。
33. 若缩小了宽泛问题，在 intro 中说明覆盖范围：如「本导览聚焦 OAuth 登录流程；token 刷新和会话管理相关但单独覆盖」；intro body 用丰富 markdown：段落、粗体、`code`、表格、代码块；它不是导览内容的目录，而是独立总览；从 JSON 输出提取 tour ID。
34. Phase 2 第 2 步：按顺序添加步骤：`{{binary}} agent tour-step --tour <id> --file <path> --line <start> --end-line <end> --body "<narrative>" --annotation "<short label>" --json`。
35. 步骤参数：`--file` 是相对仓库根路径（如 `src/server.ts`）；`--line`/`--end-line` 是要高亮的精确行范围，保持聚焦相关部分；`--annotation` 是短标签（3-6 词）作为步骤标题；`--body` 是解释面板叙事，空间大，用 markdown 写详尽解释。
36. 提交步骤前验证目标：确认 `--file` 路径从仓库根可读，描述的函数或块确实位于 `--line`/`--end-line` 范围；读该范围，不要相信本会话早前记忆；每个正文中的 `goto:` 链接同样验证；坏 goto 链接比没有链接更糟，因为读者信任它却会被放到错位置且无信号；若不确定精确行，用普通反引号代码而不是 goto 链接。
37. 步骤正文结构：每步按顺序遵循 1) 过渡（1 句）连接上一步；2) 解释（主体）这段代码做什么及为何这样组织——设计决策、权衡、具体例子；若范围分成不同部分可用 sub-highlights（`focus:X-Y`）；3) 收获（1-2 句）陷阱、边界情况或「若要改这里……」；没有过渡的步骤正文显得突兀，没有收获显得未完成；每步正文约 150-300 词，超过 400 词可能覆盖两件事，考虑拆分。
38. 步骤过渡：每步正文开头用过渡句连接前文，如「现在我们已经看到请求如何解析，接着看它在哪里验证……」；绝不开始一个好像读者无上下文到达的步骤；导览是故事，每步是章节，不是孤立段落。
39. 步骤正文做：用散文段落，辅以结构化内容；用 `code` 写函数名、变量、refs、命令；当引用已知文件和行的函数、类或符号时，用 goto 链接：`` [`symbolName`](goto:path/to/file.ts:startLine-endLine) `` 或单行 `` [`symbolName`](goto:path/to/file.ts:line) ``；它们渲染为可点击内联代码，跳转并高亮目标行；泛称、CLI 命令或未定位符号用普通反引号代码；用 **粗体** 引入关键概念；解释代码为何存在和设计决策，而不只是做什么；用具体例子（如「当你运行 `diffity main`，这一行调用 `normalizeRef('main')`，它计算 `git merge-base main HEAD`」）；用表格做映射（输入 → 输出、ref → git 命令）；用代码块展示数据结构或命令输出；将每步连接回 intro 中的大图；指出边界情况和陷阱；对大高亮范围用 sub-highlight 链接 `[label](focus:startLine-endLine)`，行范围必须在步骤的 `--line`/`--end-line` 范围内。
40. 步骤正文做：概念更适合视觉理解时（架构关系、数据流、状态机、序列图）包含 mermaid 代码块；不要每步强行加图，只在真正澄清处用；合适类型：`graph TD/LR` 用于架构/模块依赖/数据流，`sequenceDiagram` 用于调用链/请求响应流，`stateDiagram-v2` 用于状态机/生命周期转换，`classDiagram` 用于类型层级/结构关系，`flowchart` 用于算法/决策树/控制流；图保持简洁（约 12 节点以内）。
41. 步骤正文不要：写一堆 bullet；只描述语法；重复高亮代码中可见的信息；在步骤正文使用标题（annotation 作为标题）；每步强行加图；开始步骤不连接上一步。
42. Phase 2 第 3 步：添加结论步骤；导览最后一步应收尾；复用最后一个有意义步骤的文件/行范围，写正文：用 2-3 句总结完整流程并给高层心智模型；强调 2-3 个最重要设计决策及原因；指出扩展点——想改/扩展功能从哪开始、改哪些文件；指出相关领域——1-2 个相关功能或流程供下一步探索；annotation 用 `"Putting It Together"`。
43. Phase 2 第 4 步：完成导览：`{{binary}} agent tour-done --tour <id> --json`。
44. Phase 3 第 1 步：从 `{{binary}} list --json` 获取运行实例端口。
45. Phase 3 第 2 步：打开导览：`open "http://localhost:<port>/tour/<tour-id>"`（或用用户 OS 相应命令）。
46. Phase 3 第 3 步：告诉用户导览已就绪：`Your tour is ready — check your browser.`
47. Concept tours：当用户问编程概念而非功能/流程（如 `closures`、`generics`、`error handling patterns`），导览成为教学工具；研究阶段不跟随执行路径，而是用 grep、glob、文件读取搜索代码库中该概念的真实实例，广泛找——闭包可能出现在回调、工厂函数、事件处理器；选 3-8 个覆盖不同方面的例子，从简单到复杂，不要展示 5 个相同用法；intro body 为可能从未遇到该概念的人写，包括无术语定义、为什么存在（解决什么问题）、心智模型或类比、要找的语法线索；step bodies 每步通过真实例子教一个方面，结构为：在代码中定位读者 → 指出概念在行动 → 解释为什么这里使用 → 关键收获，术语首次出现时内联定义；第一个例子应让读者觉得「哦，就这么简单？」，最后一个应是最复杂用法；总结步骤回顾 3-5 条关键规则，列出 2-3 个常见错误，建议下一步学习相关概念；若少于 3 个真实例子，创建临时教学片段文件，作为导览步骤（明确标为独立示例），导览创建后删除它们；其他所有导览指南（过渡、goto 链接、sub-highlights、mermaid 图、结论）仍适用。
48. Review tours：当用户要求在合并前审查分支、PR 或功能，组织为通过用户流程的请求追踪，而不是架构漫游；范围来自 diff，开始读 `git diff <base>...HEAD`（及相关提交）了解完整表面积，每个有意义变更都要访问，只跳过纯样板；intro 用一段话说明功能，然后包含 moving-parts 表（区域 → 位置 → 目的）、高层流程图、短配置上下文块（环境变量、新常量、行为默认值）；允许一个 orientation 步（路由表、webhook switch 或其他端点目录）作为 step 1 的线程菜单，之后必须流程驱动；一次一个线程，先选最常见用户旅程（通常「create → activate → ongoing management」），端到端走，及时触及基础，然后对剩余线程重复，不要交错线程；最终跨切门控（访问检查、速率限制、feature flags 或共享 guard）放在主流程之后，让读者先看到什么被门控，再看如何门控；结论除通常心智模型 + 扩展点外，包含 `"Things to flag in the PR conversation"` 列表——非显然权衡、防御代码、竞态窗口、过期默认值、非事务写入；其他所有导览指南（过渡、goto 链接、sub-highlights、mermaid 图、结论）仍适用。
49. 完成前 Quality Checklist：逐项验证——Intro（step 0）给出详尽架构总览，不是目录；若问题被缩小，intro 说明覆盖和不覆盖；配置依赖在相关处指出；第一个代码步骤是真实入口点（路由、CLI handler、事件处理器），不是 config 文件、schema 或 helper；基础部分（schema、config、常量、helpers）出现在流程首次引用它们的步骤，而不是前奏；入口点前不超过一个 orientation 步；步骤遵循实际执行/数据流，不是文件字母顺序；每步以连接上一步的过渡开始；解释设计决策和「为什么」，不只是代码做什么；有边界情况和陷阱处标出；没有连续两步高亮同文件同行的；跨模块跳转要么跟随、要么总结、要么跳过；结论步用心智模型、设计决策、扩展点串联一切；每个有已知文件位置的函数、类或符号引用用 goto 链接；每个 `goto:` 链接和每个 `--file`/`--line` 值都已对照实际文件验证，不要猜行号；重复模式（同一 guard/middleware 跨 N 文件）用一步覆盖，不是 N 步；步骤正文遵循 transition → explanation → takeaway，并在 150-300 词范围；Review tours 中结论出现 `"Things to flag in the PR conversation"` 列表。

适用边界 · 注意事项

• 未安装 `{{binary}}` 或无法按 `{{install_hint}}` 安装/启动本地服务时不适用。
• 参数是 GitHub PR URL 但 `gh` 未认证，或当前仓库与 PR 的 `owner/repo` 不匹配时不适用。
• 用户问题过于宽泛且无法缩小到某个模式步数范围，或无法判断模式时不适用；应先询问而不是生成错误形状的导览。