关于
创建 CodeTour .tour 文件 — 面向特定角色的、带真实文件和行锚点的分步演练。用于入职导览、架构演练、PR 导览和 RCA 导览。
name: code-tour
description: 创建CodeTour .tour文件——面向特定角色的、逐步引导的代码漫游，带有真实文件和行号锚点。适用于入职引导、架构漫游、PR漫游、RCA漫游，以及结构化的"解释这是如何工作的"请求。
origin: ECC
Code Tour
创建CodeTour .tour文件，用于代码库漫游，可直接打开到真实文件和行范围。Tour文件存放在.tours/目录中，采用CodeTour格式，而非临时Markdown笔记。
好的tour是为特定读者编写的叙事：
- 他们正在看什么
- 为什么重要
- 接下来应该走什么路径
仅创建.tour JSON文件。不要在此技能中修改源代码。
何时使用
在以下情况使用此技能：
- 用户要求代码漫游、入职引导、架构漫游或PR漫游
- 用户说"解释X是如何工作的"并希望得到可复用的引导产物
- 用户希望为新工程师或审查者提供学习路径
- 任务更适合用引导序列而非平面摘要来呈现
示例：
- 为新维护者做入职引导
- 单个服务或包的架构漫游
- 锚定到变更文件的PR审查漫游
- 展示故障路径的RCA漫游
- 信任边界和关键检查的安全审查漫游
何时不使用
| 不使用code-tour的情况 | 替代方案 |
| --- | --- |
| 在聊天中一次性解释就够了 | 直接回答 |
| 用户想要散文文档，而非.tour产物 | documentation-lookup或编辑仓库文档 |
| 任务是实现或重构 | 执行实现工作 |
| 任务是广泛的代码库入职但不需要tour产物 | codebase-onboarding |
工作流程
1. 探索
在编写任何内容前探索仓库：
- README和包/应用入口点
- 文件夹结构
- 相关配置文件
- 如果是PR相关的tour，查看变更文件
在理解代码结构前不要开始编写步骤。
2. 推断读者
根据请求确定角色和深度。
| 请求形式 | 角色 | 建议深度 |
| --- | --- | --- |
| "入职"、"新人" | new-joiner | 9-13步 |
| "快速浏览"、"概览" | vibecoder | 5-8步 |
| "架构" | architect | 14-18步 |
| "漫游这个PR" | pr-reviewer | 7-11步 |
| "为什么出故障了" | rca-investigator | 7-11步 |
| "安全审查" | security-reviewer | 7-11步 |
| "解释这个功能如何工作" | feature-explainer | 7-11步 |
| "调试这个路径" | bug-fixer | 7-11步 |
3. 读取并验证锚点
每个文件路径和行号锚点必须是真实的：
- 确认文件存在
- 确认行号在范围内
- 如果使用选区，验证确切的代码块
- 如果文件经常变动，优先使用基于模式的锚点
永远不要猜测行号。
4. 编写.tour
写入到：
.tours/<persona>-<focus>.tour
保持路径确定性和可读性。
5. 验证
完成前：
- 每个引用的路径都存在
- 每个行号或选区都有效
- 第一步锚定到真实文件或目录
- tour讲述连贯的故事而非列举文件
步骤类型
内容
谨慎使用，通常仅用于结束步骤：
{ "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）：聪明的读者可能会忽略什么
保持描述紧凑、具体，并扎根于实际代码。
叙事结构
除非任务明确需要不同结构，否则使用此弧线：
- 定位
- 模块地图
- 核心执行路径
- 边缘情况或陷阱
- 结束/下一步行动
tour应该感觉像一条路径，而非一份清单。
示例
{
"$schema": "https://aka.ms/codetour-schema",
"title": "AP
