CodeTour 技能实战指南：在 GitHub Copilot 中生成面向 20 种角色的代码导览

CodeTour 技能实战指南：在 GitHub Copilot 中生成面向 20 种角色的代码导览

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot

导读

本文聚焦 awesome-copilot 仓库中内置的code-tour 技能（skills/code-tour/SKILL.md），系统讲解如何让 Copilot 为任意语言、任意规模代码库生成「以人为中心、逐步展开、直连真实文件与行号」的 CodeTour 导览文件。读完本文，你将掌握：从仓库侦察、意图推断、步骤类型选择到验证器兜底的完整创作流水线，能够为新人入职、Bug 排查、RCA 复盘、PR 评审、架构讲解等 20 种开发者角色产出可直接在 VS Code 中播放的.tour文件，并理解这套技能捆绑的校验脚本与 JSON Schema 的底层实现原理。

一、技能定位：CodeTour 是什么，这份技能解决了什么问题

CodeTour 是一种以 JSON 描述的交互式代码导览（.tour文件），通过 VS Code 扩展在编辑器内播放：每一步都指向真实文件的具体行、代码块、目录或外部链接，并配有一段 Markdown 讲解文字。它把「阅读源码」从线性翻文件变成一次有叙事的向导。

code-tour 技能的核心立场是：一个好的导览不是文件的注释集合，而是一个叙事——针对某个具体的人，告诉他什么重要、为什么重要、接下来该做什么。因此该技能提供了一套完整的创作方法论与工具链：

• 两个捆绑脚本（骨架生成器、验证器）；
• 两个参考文件（权威 JSON Schema、8 个生产环境真实案例）；
• 20 种开发者 persona 与对应的覆盖策略；
• 一套叙事弧模板、SMIG 描述公式与反模式清单。

技能元数据（name: code-tour与触发词列表）见 SKILL.md，安装方式为gh skills install github/awesome-copilot code-tour（见 docs/README.skills.md）。仓库中还配有同主题的专用 Agent 描述 agents/code-tour.agent.md，可作为团队级 CodeTour 维护者的补充角色定义。

二、技能捆绑资源一览

关键约束：本技能只允许创建.tourJSON 文件，禁止创建、修改或脚手架化任何其他文件——导览不能碰源码。

三、六步创作工作流

Step 1：侦察仓库

在询问用户任何问题之前，先探索代码库：

• 列出根目录、阅读 README、检查关键配置文件（package.json、pyproject.toml、go.mod、Cargo.toml、composer.json等）；
• 识别语言、框架与项目职责；
• 向下 1–2 层映射目录结构；
• 找到入口点（main、index、应用引导文件）；
• 记录哪些文件真实存在——导览中写到的每个路径都必须是真实的。

仓库稀疏或为空时，如实说明并按现状创作。下表给出按技术栈推荐的入口点，避免大海捞针：

按仓库类型调整关注点：Service/API 强调请求生命周期、认证、错误契约（锚点文件：router、middleware、handler、schema）；Library/SDK 强调公开 API 面、扩展点、版本化（index/exports、types、changelog）；CLI 强调命令解析、配置加载、输出格式（main、commands/、config）；Monorepo 强调包边界、共享契约、构建图（根 package.json/pnpm-workspace、shared/、packages/）；Framework 强调插件系统、生命周期钩子、逃生舱（core/、plugins/、lifecycle）。

大仓库策略（100+ 文件）：先读入口点与 README → 建立 top 5–7 模块心智模型 → 针对 persona 挑出最重要的 2–3 个模块深入阅读 → 未覆盖的模块在导览开篇注明「本次导览范围之外」→ 对只做了地图映射而未细读的区域使用directory步骤。原则是：一个聚焦的 10 步导览胜过散乱的 25 步导览。

Step 2：读懂意图——能推断的绝不问

理想情况下，用户一条消息就够了。从请求中推断 persona、深度与聚焦点，只有真正无法推断时才提问（例如只说「bug tour」但没描述 bug，或只说「feature tour」但没指名功能）。用户明确指定的文件必须作为必停点。永远不要主动追问nextTour、commands、when、stepMarker，除非用户自己提到了。

意图映射表（节选）：

用户自定义定制一律照办：

PR tour 配方：ref设为分支，先以uri步骤打开 PR，优先覆盖变更文件，再覆盖未变更但关键的文件，最后以评审者检查清单收尾。

Step 3：阅读真实文件——没有例外

导览中每一个文件路径与行号都必须通过阅读文件验证。指向错误文件或不存在的行，比没有导览更糟。对每个计划步骤：读文件 → 找到要强调的精确代码行 → 理解到能向目标 persona 讲解的程度。用户指定的文件不存在时直接说明，不要默默替换成别的文件。

Step 4：写导览

保存到.tours/<persona>-<focus>.tour，命名规则为 kebab-case，同时传达 persona 与主题：

onboarding-new-joiner.tour bug-fixer-payment-flow.tour architect-overview.tour vibecoder-quickstart.tour pr-review-auth-refactor.tour security-auth-boundaries.tour concept-dependency-injection.tour rca-login-outage.tour

导览根对象

{ "$schema": "https://aka.ms/codetour-schema", "title": "Descriptive Title — Persona / Goal", "description": "One sentence: who this is for and what they'll understand after.", "ref": "main", "isPrimary": false, "nextTour": "Title of follow-up tour", "steps": [] }

不适用的字段一律省略。依据 codetour-schema.json，顶层必填字段只有title与steps，其余均为可选：ref（关联的 git ref：分支/提交/标签）、isPrimary（是否本代码库主导览）、nextTour（后续导览标题，须精确匹配另一.tour文件的title）、stepMarker、when。

when条件显示：运行时求值的 JavaScript 表达式，只有条件为真才展示该导览，适用于按 persona 自动启动或隐藏高级导览：

{ "when": "workspaceFolders[0].name === 'api'" }

stepMarker步进锚点：把步骤锚点直接嵌进源码注释。设置"stepMarker": "CT"后，CodeTour 会在文件中寻找// CT注释作为步骤位置（可替代行号）。适合行号频繁漂移的活跃代码。但此方案需要修改源文件，非用户要求不要建议。

步骤类型全参考

路径规则："file"与"directory"必须相对仓库根目录。禁止绝对路径、禁止./前缀。

依据 codetour-schema.json，每个 step 必填description（支持 Markdown），可选字段包括title、file、directory、uri、line（1-based）、pattern、selection（start/end各含 1-basedline与character）、view、commands（VS Code 命令 URI 数组，如editor.action.goToDeclaration、workbench.action.terminal.focus、editor.action.showHover、references-view.findReferences、workbench.action.tasks.runTask）。

步骤数量校准

同时按仓库规模缩放：3 文件的小 CLI 不需要 15 步，200 文件的大型单体也不该被压进 5 步。

写出色的描述——SMIG 公式

每段描述按顺序回答四个问题（不必写四段话，但四要素都要有，哪怕很简短）：

• S — Situation（情境）：读者正看到什么？一句话把他锚定在上下文里。
• M — Mechanism（机制）：这段代码如何工作？涉及什么模式、规则或设计。
• I — Implication（含义）：为什么这对这个 persona 的目标特别重要？
• G — Gotcha（坑）：聪明人会在这里犯什么错？什么是不显而易见、脆弱或反直觉的？

描述要让读者获得自己读文件学不到的东西：点出模式名、解释设计决策、标记失败模式、交叉引用相关上下文。

Step 5：验证导览

写完文件后必须立即运行验证器，不可跳过：

python skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .

从 validate_tour.py 的源码可以看到验证器实际检查的内容：

• JSON 合法性：解析失败直接返回passed: False（validate_tour.py）；
• 顶层必填字段：缺少title、steps，或steps非数组/为空均报错；
• file路径：必须是相对路径（以/开头报错、./开头警告），文件必须存在且是文件；line必须是 ≥1 的整数且不超过文件行数；selection的 start/end 行必须在文件长度内且 start ≤ end；pattern正则必须能编译且至少匹配文件中的一行（validate_tour.py）；
• directory路径：必须存在且是目录；
• uri：必须以https://或http://开头（否则警告）；
• commands：必须是字符串数组；
• nextTour：会在.tours/目录中搜索标题精确匹配的其他.tour文件，找不到则警告；
• 纯内容步骤数量：超过 2 个（intro + closing）时警告；
• 叙事弧：首步是否为file/directory定向步骤、末步是否为收尾步骤，均给出提示信息。

报告输出格式见 print_report：统计 file/dir/content/uri 步骤数，错误以 ✗ 显示、警告以 ⚠ 显示、提示以 ℹ 显示；passed且无警告时输出绿色✓ All checks passed。修复所有错误后才可继续，警告为建议性，由你自行判断。验证通过前不要给用户看导览。

常见 VS Code 问题：纯内容首步渲染为空白页（改用 file/directory 锚点）；绝对路径或./前缀路径静默失败；越界行号滚动到空白处。

无法运行脚本时手动核对：首步有file/directory、所有路径存在、行号在界内、nextTour精确匹配。

自动播放（Autoplay）：isPrimary: true+.vscode/settings.json中的{ "codetour.promptForPrimaryTour": true }，可在打开仓库时自动弹出主导览；省略ref则导览在任意分支都可见。

分享：公开仓库的导览无需安装即可通过 vscode.dev 的在线 VS Code 打开体验。

Step 6：交付总结

写完导览后向用户汇报：文件路径（.tours/<name>.tour）、一段导览覆盖内容与目标读者的概括、公开仓库的 vscode.dev 分享地址、2–3 条建议的后续导览（或系列中的下一站），以及用户指定但不存在于仓库的文件（要明确说明，不要悄悄替换）。

四、叙事弧：每个导览、每个 persona 的骨架

1. 定向（Orientation）——必须是file或directory步骤，绝不能是纯 content。用"file": "README.md", "line": 1或"directory": "src"，欢迎语写在 description 里。纯 content 首步在 VS Code CodeTour 中会渲染成空白页，这是扩展的已知行为、不可配置。
2. 高层地图（1–3 个 directory 或 uri 步骤）——主要模块及其关系。只呈现该 persona 需要知道的。
3. 核心路径（file/line、selection、pattern、uri 步骤）——真正重要的具体代码。这是导览的心脏，逐行阅读并讲解，不能走马观花。
4. 收尾（content）——读者现在理解了什​​么、接下来能做什么、建议 2–3 个后续导览；若设置了nextTour，在此处按名称引用。

收尾步骤不要做总结（读者刚读完），而是告诉他们现在能做什么、要避免什么，并建议后续导览。

五、20 种 persona 与覆盖策略

六、设计导览系列

代码库足够复杂、单个导览无法覆盖时，用nextTour字段串联成系列：读者完成一个导览后，VS Code 会自动提议启动下一个。

写任何导览之前先规划系列。一个好系列应有：清晰的升级路径（宽 → 窄，定向 → 深潜）、导览间无重复步骤、每个导览独立成篇、单独使用也有价值。nextTour的值必须与下一个导览的title精确一致。参照 examples.md 中多导览架构系列案例：复杂系统按层拆成多个导览（函数代码、IaC、CI/CD 各一个），用nextTour链式衔接。

七、CodeTour 不能做什么

被要求以下功能时，明确说不支持，不要建议不存在的变通方案：

八、反模式

九、写文件前的质量清单

• 每个file路径相对仓库根目录（无前导/或./）
• 每个file路径已阅读并确认存在
• 每个line行号已通过阅读文件验证（非猜测）
• 每个directory相对仓库根目录且已确认存在
• 每个pattern正则会匹配文件中的真实行
• 每个uri是完整真实 URL（https://...）
• ref若是分支/标签/提交则为真实值
• 若设置nextTour，与另一.tour文件的title精确一致
• 只创建.tourJSON 文件——不碰任何源码
• 首步有file或directory锚点（纯 content 首步 = VS Code 空白页）
• 以告诉读者接下来能做什么的 content 收尾步骤结束
• 每段描述满足 SMIG——Situation、Mechanism、Implication、Gotcha
• persona 优先级驱动步骤选择（删掉不服务于其目标的一切）
• 步数与请求深度和仓库规模匹配（见校准表）
• 至多 2 个纯 content 步骤（intro + closing）
• 所有字段符合 references/codetour-schema.json

十、从文档生成骨架：读懂 generate_from_docs.py

当用户说「从 README 生成」或「用文档」时，先运行骨架生成器，再通过阅读真实文件填充每个[TODO: ...]：

python skills/code-tour/scripts/generate_from_docs.py \ --persona new-joiner \ --output .tours/skeleton.tour

从源码看其内部逻辑（generate_from_docs.py）：

1. 读取README.md（及可选的CONTRIBUTING.md、ARCHITECTURE.md、docs/architecture.md、docs/README.md）；
2. 用正则提取行内代码中「长得像路径」的字符串（_CODE_PATH、_LOOKS_LIKE_PATH），并只保留仓库中真实存在的路径（_extract_paths_from_text中full.exists()检查）；
3. 结构/架构类章节（标题命中 structure/architecture/layout/setup 等关键词）→ 生成directory或file步骤；
4. 外部链接 → 生成uri步骤（最多 3 个，过滤图片链接与「here/link」等泛化锚文本）；
5. 若文件步骤不足 3 个，回退为顶层目录扫描；
6. 首尾自动补 Welcome 与 What to Explore Next 两个 content 步骤，并去重。

生成结果含_skeleton_generated_by与_instructions字段，填充内容后需删除这两个元数据字段。注意该脚本生成的骨架是创作起点而非终点——它只负责提取骨架，描述质量仍由技能的执行判断决定。

十一、真实案例技法速查

references/examples.md 收录了 8 个生产仓库的真实导览及可复用技法，核心速查如下：

该文件同时提供了从 GitHub 代码搜索发现更多.tour文件的思路（按path:*.tour检索，可叠加language:或关键词过滤），以及官方/社区进一步阅读材料。撰写时若需要某个步骤类型或叙事结构的实战样本，优先取用这些已确认的生产文件，而不是凭记忆创作。

十二、配套资源与落地建议

• 配套 Agent：agents/code-tour.agent.md 定义了「VSCode Tour Expert」角色，补充了 CodeTour 风味 Markdown（[#stepNumber]步骤引用、[TourTitle]导览引用、{{VARIABLE_NAME}}环境变量、command:交互链接）、版本化策略（None / 当前分支 / 当前提交 / 标签）以及 CI/CD 集成思路（在 PR 中检测导览漂移、在构建管道中验证导览文件）。
• 团队采纳路径：为新人创建 primary 导览 → 在 README/CONTRIBUTING 中链接导览 → 定期维护防漂移 → 收集反馈迭代内容。
• 技能市场入口：docs/README.skills.md 中的 code-tour 条目给出了安装命令与完整触发词清单，适合作为团队发现该能力的入口。

一句话收束：伟大的导览是在讲述代码的故事——它让复杂系统变得可接近，帮助开发者建立「各部分如何协同」的心智模型。用本文的六步流水线、SMIG 公式、叙事弧与验证器兜底，你就能为任何仓库、任何角色写出让人「希望当初自己打开仓库时就有」的那份导览。

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot