使用方式
关于
当用户要求创建 CodeTour .tour 文件时使用——面向特定角色、逐步链接到真实文件和行号的代码导览。触发词：创建导览、入职导览、架构导览、PR 审查导览、解释 X 如何工作、贡献者指南等。
代码导览
创建 CodeTour 文件——面向特定角色的、逐步引导的代码库演练，直接链接到文件和行号。CodeTour 文件存放在 .tours/ 目录中，配合 VS Code CodeTour 扩展 使用。
概述
优秀的导览是一个叙事——针对特定人群讲述的故事，说明什么重要、为什么重要、以及下一步该做什么。只创建 .tour JSON 文件，绝不修改源代码。
何时使用此技能
- 用户要求创建代码导览、入职导览或架构演练
- 用户说"为这个 PR 做导览"、"解释 X 如何工作"、"快速了解"、"RCA 导览"
- 用户需要贡献者指南、安全审查或 Bug 调查演练
- 任何需要带有文件/行号锚点的结构化演练的请求
核心工作流程
1. 探索仓库
在提问之前，先探索代码库：
并行执行：列出根目录、阅读 README、检查配置文件。 然后：识别语言、框架、项目用途。映射 1-2 层深的文件夹结构。找到入口点——导览中的每个路径必须真实存在。
如果仓库源文件少于 5 个，无论角色如何都创建快速深度导览——内容不足以支撑深度导览。
2. 推断意图
一条消息应该足够。静默推断角色、深度和焦点。
| 用户说的 | 角色 | 深度 | |-----------|---------|-------| | "为这个 PR 做导览" | PR 审查者 | 标准 | | "为什么 X 坏了" / "RCA" | RCA 调查者 | 标准 | | "入职" / "新人" | 新人 | 标准 | | "快速导览" / "快速了解" | 快速浏览者 | 快速 | | "架构" | 架构师 | 深度 | | "安全" / "认证审查" | 安全审查者 | 标准 | | （无限定词） | 新人 | 标准 |
当意图不明确时，默认使用新人角色和标准深度——这是最通用的选择。
3. 读取实际文件
每个文件路径和行号必须经过验证。 指向错误行号的导览比没有导览更糟糕。
4. 编写导览
保存到 .tours/<persona>-<focus>.tour。
{
"$schema": "https://aka.ms/codetour-schema",
"title": "Descriptive Title — Persona / Goal",
"description": "Who this is for and what they'll understand after.",
"ref": "<current-branch-or-commit>",
"steps": []
}
步骤类型
| 类型 | 何时使用 | 示例 |
|------|-------------|---------|
| 内容 | 仅用于开头/结尾（最多 2 个） | { "title": "Welcome", "description": "..." } |
| 目录 | 定位到模块 | { "directory": "src/services", "title": "..." } |
| 文件 + 行号 | 主力类型 | { "file": "src/auth.ts", "line": 42, "title": "..." } |
| 选区 | 高亮代码块 | { "file": "...", "selection": {...}, "title": "..." } |
| 模式 | 正则匹配（易变文件） | { "file": "...", "pattern": "class App", "title": "..." } |
| URI | 链接到 PR、Issue、文档 | { "uri": "https://...", "title": "..." } |
步骤数量
| 深度 | 步骤数 | 适用场景 | |-------|-------|---------| | 快速 | 5-8 | 快速浏览者，快速探索 | | 标准 | 9-13 | 大多数角色 | | 深度 | 14-18 | 架构师，RCA |
编写描述——SMIG 公式
- S — 情境（Situation）：读者正在看什么？
- M — 机制（Mechanism）：这段代码如何工作？
- I — 影响（Implication）：这对该角色为什么重要？
- G — 陷阱（Gotcha）：聪明人会在哪里犯错？
5. 验证
- [ ] 每个
file路径相对于仓库根目录（不带前导/或./） - [ ] 每个
file确认存在 - [ ] 每个
line通过读取文件验证 - [ ] 第一步有
file或directory锚点 - [ ] 最多 2 个纯内容步骤
- [ ] 如果设置了
nextTour，必须精确匹配另一个导览的title
角色
| 角色 | 目标 | 必须覆盖 | |---------|------|------------| | 快速浏览者 | 快速了解全貌 | 入口点、主要模块。最多 8 步。 | | 新人 | 结构化上手 | 目录、设置、业务上下文 | | Bug 修复者 | 快速定位根因 | 触发点 -> 故障点 -> 测试 | | RCA 调查者 | 为什么失败 | 因果链、可观测性锚点 | | 功能讲解者 | 端到端 | UI -> API -> 后端 -> 存储 | | PR 审查者 | 正确审查 | 变更故事、不变量、风险区域 | | 架构师 | 形态与理由 | 边界、权衡、扩展点 | | 安全审查者 | 信任边界 | 认证流程、验证、密钥处理 | | 重构者 | 安全重构 | 接缝、隐藏依赖、提取顺序 | | 外部贡献者 | 安全贡献 | 安全区域、约定、地雷 |
叙事弧线
- 定位 ——
file或directory步骤（第一步绝不用纯内容——在 VS Code 中会显示空白） - 高层地图 —— 1-3 个目录步骤展示主要模块
- 核心路径 —— 文件/行号步骤，导览的核心
- 收尾 —— 读者现在能做什么，建议的后续步骤
反模式
| 反模式 | 修复方法 | |---|---| | 文件列表 | 每步讲一个故事，不是列清单 |
