code-tour

用途

Code Tour 用于创建 CodeTour .tour 文件，为代码库生成可直接打开到真实文件和行范围的走查。走查文件存放在 .tours/ 目录，面向 CodeTour 格式，而不是临时的 Markdown 笔记。

一个好的走查是写给特定读者的叙事，回答：读者正在看什么、为什么重要、接下来应沿什么路径阅读。

该技能只创建 .tour JSON 文件，不修改源代码。

何时使用

用户要求代码走查、入职导览、架构讲解或 PR 走查
用户说“解释 X 如何工作”，并希望得到可复用的引导性产物
用户希望为新工程师或审查者提供上手路径
任务更适合引导式序列而非平铺摘要

示例：新维护者入职、单个服务或包的架构走查、锚定变更文件的 PR 审查走查、展示故障路径的 RCA 走查、信任边界与关键检查的安全审查走查。

何时不使用

聊天中一次性解释即可：直接回答
用户想要散文文档而非 .tour 产物：使用 documentation-lookup 或编辑仓库文档
任务是实现或重构：直接做实现工作
任务是宽泛的代码库入职且不需要走查产物：使用 codebase-onboarding

工作流程

发现：写任何内容前先探索仓库，包括 README 与应用入口点、文件夹结构、相关配置文件，若走查聚焦 PR 则查看变更文件。在理解代码形态前不要开始写步骤。
推断读者：根据请求确定人物角色与深度。

请求形态	人物角色	建议深度
“onboarding”“new joiner”	new-joiner	9-13 步
“quick tour”“vibe check”	vibecoder	5-8 步
“architecture”	architect	14-18 步
“tour this PR”	pr-reviewer	7-11 步
“why did this break”	rca-investigator	7-11 步
“security review”	security-reviewer	7-11 步
“explain how this feature works”	feature-explainer	7-11 步
“debug this path”	bug-fixer	7-11 步

读取并验证锚点：每个文件路径与行锚点都必须真实——确认文件存在、确认行号在范围内、若使用选区则验证确切代码块、若文件易变则优先使用基于模式的锚点。绝不要猜测行号。
编写 .tour：写入 .tours/<persona>-<focus>.tour，保持路径确定且可读。
验证：完成前确认每个引用的路径存在、每个行或选区有效、第一步锚定到真实文件或目录、ref 指向确实包含走查所引用全部文件的分支或提交、走查讲述连贯故事而非罗列文件。

ref 字段

ref 将走查绑定到 git 分支或提交。当 ref 不是读者已检出的分支时，CodeTour 会从该 git 修订版打开每个步骤的文件，而非磁盘上的文件。若某文件不在该修订版中，步骤将无法打开——读者会看到“The editor could not be opened because the file was not found”，即使文件就在那里。走查及其评论仍会显示，因此真正原因容易被忽略。

按走查类型选择 ref：

走查类型	ref 设为
PR 走查	PR 分支——绝不用基础分支
入职 / 架构	读者将所在的分支（通常是 main），或省略
不确定	省略 ref，让 CodeTour 直接从磁盘读取文件

PR 情况是常见陷阱：PR 通常新增文件，而新文件在基础分支上尚不存在。把 ref 指向基础分支（如 develop），每个新文件上的步骤都会打开失败。完成前确认每个步骤的文件确实存在于所选 ref。

步骤类型

内容：谨慎使用，通常仅用于收尾步骤：

{ "title": "Next Steps", "description": "You can now trace the request path end to end." }

不要让第一步仅为内容。

目录：用于让读者定位某个模块：

{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }

文件 + 行：默认步骤类型：

{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." }

选区：当某个代码块比整个文件更重要时使用：

{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "Request Pipeline",
  "description": "This block wires validation, auth, and downstream execution."
}

模式：当确切行号可能漂移时使用：

{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" }

URI：在有用时用于 PR、issue 或文档：

{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" }

写作规则：SMIG

每条描述应回答：

Situation：读者正在看什么
Mechanism：它如何工作
Implication：为什么对该人物角色重要
Gotcha：聪明的读者可能忽略什么

保持描述紧凑、具体，并扎根于实际代码。

叙事形态

除非任务明显需要不同结构，使用此弧线：定位、模块地图、核心执行路径、边界情况或陷阱、收尾 / 下一步。走查应感觉像一条路径，而非清单。

示例

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "API Service Tour",
  "description": "Walkthrough of the request path for the payments service.",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "Source Root",
      "description": "All runtime code for the service starts here."
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "Entry Point",
      "description": "The server boots here and wires middleware before any route is reached."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Payment Routes",
      "description": "Every payments request enters through this router before hitting service logic."
    },
    {
      "title": "Next Steps",
      "description": "You can now follow any payment request end to end with the main anchors in place."
    }
  ]
}

反模式

反模式	修复
平铺文件清单	用步骤间的依赖关系讲故事
泛泛的描述	点名具体代码路径或模式
猜测的锚点	先验证每个文件与行号
快速走查步骤过多	大幅删减
第一步仅为内容	将第一步锚定到真实文件或目录
人物角色不匹配	为实际读者写作，而非泛泛的工程师

最佳实践

步骤数量与仓库规模和人物角色深度成比例
用目录步骤定位，用文件步骤承载实质内容
PR 走查优先覆盖变更文件
单体仓库中限定到相关包，而非走查全部
以读者现在能做什么收尾，而非回顾

技能介绍

用途