代码导览

解决什么问题

团队中的代码库往往缺乏一份"会说话的文档"。新成员拿到仓库后，常需要花半天甚至更长时间才能理清入口在哪、核心模块怎么流转；PR 评审者面对一堆改动，很难快速判断风险点分布在哪里；故障排查时，因果链散落在多个文件里，靠人脑记忆容易遗漏关键环节。传统 README 或架构文档又容易与实际代码脱节，时间一长就失去参考价值。

code-tour 技能针对的就是这一痛点：它不写普通文档，而是生成可直接在 VS Code 中运行的 CodeTour 导览文件，把"看哪里、为什么重要、下一步做什么"串成一条叙事线，锚点精确到文件和行号。

技能如何工作

技能的核心流程分为四步：

1. 探索仓库 —— 并行执行根目录列表、README 阅读、配置文件检查，识别语言、框架和项目用途，映射 1-2 层目录结构，找到入口点。
2. 推断意图 —— 根据用户表述自动判断 persona 和深度，无需反复追问。
3. 读取实际文件 —— 每个文件路径和行号都必须经过实际阅读验证，绝不猜测。
4. 写入导览 —— 保存为 .tours/xxx.tour 文件，支持六种步骤类型：Content（内容页）、Directory（目录定位）、File + line（文件行号锚点）、Selection（代码块高亮）、Pattern（正则匹配，适用于易变文件）、URI（外链 PR、issue 或文档）。

导览的步骤数按深度分档：Quick 5-8 步、Standard 9-13 步、Deep 14-18 步。每条步骤描述遵循 SMIG 公式：Situation（读者在看什么）、Mechanism（代码怎么运作）、Implication（对当前 persona 为何重要）、Gotcha（容易踩的坑）。

技能内置十种 persona，覆盖新成员、PR 评审者、RCA 调查者、架构师、安全审查者等场景，每种 persona 都定义了必须覆盖的内容和目标。

适用边界与注意点

• 技能只生成 .tour 文件，绝不修改源代码。
• 文件路径必须相对于仓库根目录，不能以 / 或 ./ 开头。
• 如果仓库源码文件少于 5 个，直接创建 quick 深度导览，不必强行拉长。
• 第一步必须锚定到文件或目录，纯内容页会导致 VS Code 中显示空白。
• 内容页最多 2 个，分别用于开头和结尾。
• 避免把导览写成文件列表或复述式结尾，每条步骤都应该推进叙事，结尾告诉读者"现在能做什么"。