企业官网建设流程全解析

awesome-copilot 的 VSCode Tour Expert：编写高质量 CodeTour.tour文件的完整指南

【免费下载链接】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 仓库中，VSCode Tour Expert（定义于 code-tour.agent.md）是一个面向"创建与维护 CodeTour 文件"的专家 Agent：它以 CodeTour 官方 Schema 为准绳，帮助开发者编写结构完整、路径真实、叙事清晰的.tourJSON 文件，让新工程师在 VS Code 中沿着真实文件与行号完成"有讲解的代码走查"，从而显著改善代码库的上手体验。仓库同时提供配套的 CodeTour 技能、权威 Schema 文件 与可运行的 校验脚本。读完本文，你将掌握.tour文件的完整字段语义、六种步骤类型与 CodeTour 专属 Markdown 语法、三大高频 Tour 模式、版本化策略与团队集成方式，并学会用脚本化校验保证每条导览真实可靠。

CodeTour 与.tour文件的定位

CodeTour 是一种把"代码讲解"沉淀为可交互导览的格式：一个.tour文件是一段 JSON，描述了若干步骤（step），每一步可关联到工作区内的某个文件、某个行号、某个目录、一段选中代码，甚至一个外部 URI 或一条 VS Code 命令。读者（例如刚入职的新人）在 VS Code 中"播放"这个 Tour 时，编辑器会依次跳转到每个锚点，并在导览面板中展示 Markdown 讲解文字。

在 code-tour.agent.md 的定义中，该专家 Agent 的核心能力被划分为四个层次：

1. Tour 文件的创建与管理：按官方 Schema 编写完整.tourJSON；为复杂代码库设计逐步走查；实现正确的文件引用、目录步骤与内容步骤；用 git ref（分支、提交、标签）配置版本关联；设置 primary tour 与 tour 串联序列；用when子句创建条件导览。
2. 进阶步骤能力：内容步骤、目录步骤、选区步骤、命令链接、终端命令、可插入代码块与{{VARIABLE_NAME}}环境变量。
3. CodeTour 风格 Markdown：以工作区相对路径引用文件、用[#stepNumber]引用步骤、用[TourTitle]/[TourTitle#step]引用其他导览、内嵌图片与富 Markdown/HTML。
4. Schema 层面的严谨性：对文件结构、目录结构与 git 版本策略给出最佳实践。

值得强调的是，本仓库把这些规则做成了可运行、可校验的资产：专家 Agent 负责"怎么想"，SKILL.md 负责"怎么执行"，references/codetour-schema.json提供字段级别的权威约束，scripts/validate_tour.py负责机器化兜底——这为团队化复用提供了完整闭环。

.tour文件的 Schema 全景

顶层结构

一个.tour文件由"导览级字段 + 步骤数组"构成。code-tour.agent.md 给出了权威骨架，仓库内的 codetour-schema.json 进一步明确了字段类型与必填约束（title与steps为顶层必填）。

{ "title": "Required - Display name of the tour", "description": "Optional description shown as tooltip", "ref": "Optional git ref (branch/tag/commit)", "isPrimary": false, "nextTour": "Title of subsequent tour", "when": "JavaScript condition for conditional display", "steps": [ { "description": "Required - Step explanation with markdown", "file": "relative/path/to/file.js", "directory": "relative/path/to/directory", "uri": "absolute://uri/for/external/files", "line": 42, "pattern": "regex pattern for dynamic line matching", "title": "Optional friendly step name", "commands": ["command.id?[\"arg1\",\"arg2\"]"], "view": "viewId to focus when navigating" } ] }

导览级字段（Tour 顶层字段）

其中stepMarker与when不在主 Agent 文档的 JSON 骨架里，但在 codetour-schema.json 中均有明确定义（stepMarker为"标识一行代码是某导览步骤的 marker 字符串"），属于进阶可选项。

步骤级字段（Step 字段）

从 codetour-schema.json 的示例可见，commands的常见取值包括editor.action.goToDeclaration（跳转到声明）、workbench.action.terminal.focus（聚焦终端）、editor.action.showHover（显示悬浮提示）、references-view.findReferences（查找引用）、workbench.action.tasks.runTask（运行任务）。这些命令与字段共同支撑了"边讲解边操作"的导览体验。

步骤类型：何时用哪一种

file + line是导览的主力步骤，但六类锚点各有适用场景。综合 code-tour.agent.md 的能力清单与 SKILL.md 的决策表：

两条关键纪律（来自仓库配套技能与校验脚本）：

• 路径必须相对仓库根目录。校验脚本 validate_tour.py 中，/开头的路径直接判为 error，./开头的路径给出 warning——因为这两类路径在 CodeTour 中会静默失效。
• 开篇步骤尽量带锚点。仓库技能文档明确提示：首步如果只写内容（没有file/directory/uri），在 VS Code CodeTour 中会渲染成空白页（这是扩展侧的已知行为，不可配置）。因此即便 Agent 文档中的 Onboarding 示例以 Introduction 内容步骤开篇，工程上仍建议用"file": "README.md", "line": 1或"directory": "src"承载欢迎语。

CodeTour 专属 Markdown：让讲解"活"起来

步骤的description并非普通文本，而是带有一组 CodeTour 约定语法：

• 文件引用：使用工作区相对路径，如src/player/index.ts。
• 步骤引用：[#stepNumber]，可直接跳到本导览的某一步。
• 导览引用：[TourTitle]或[TourTitle#step]，可跨导览跳转到某段落的某一步。
• 命令链接（command:scheme）：在讲解中点开可交互元素，例如"点击这里 运行测试"。
• 终端命令（>>语法）：在描述中嵌入>> npm run build，渲染为可执行的终端命令快捷方式，把"读代码"和"跑命令"衔接起来。
• 代码块：将待插入代码放在 Markdown 代码围栏中，适合交互式教程。
• 图片嵌入：架构图、运行截图均可放进描述，让导览自包含。
• 富 Markdown/HTML：标题、列表、强调、HTML 均可使用。
• 环境变量：以{{VARIABLE_NAME}}形式实现动态内容，例如把导览写在通用位置、按使用者环境展开。

其中>>终端命令与{{VAR}}环境变量尤其值得说明：>>让教程场景中的"构建、测试"步骤无需读者手动敲命令；环境变量则让一份导览模板能被不同工作区复用，例如Your project is located at {{HOME}}/projects/{{WORKSPACE_NAME}}。

三种高频 Tour 模式（可直接复用）

code-tour.agent.md 给出了三种经实战验证的结构模式，下面完整列出。

模式一：新人 Onboarding（isPrimary+nextTour串联）

用isPrimary: true标记为主导览，配合nextTour指向下一段更深的导览，形成平滑的进阶路径：

{ "title": "1 - Getting Started", "description": "Essential concepts for new team members", "isPrimary": true, "nextTour": "2 - Core Architecture", "steps": [ { "description": "# Welcome!\n\nThis tour will guide you through our codebase...", "title": "Introduction" }, { "description": "This is our main application entry point...", "file": "src/app.ts", "line": 1 } ] }

模式二：功能深潜（目录定位 + 锚定实现）

适合讲解"认证系统"这类跨文件的横切功能：先用directory步骤圈定范围，再用file+line/pattern精确讲解关键实现，并可加ref: "main"把导览锁定在某分支语义上：

{ "title": "Authentication System", "description": "Complete walkthrough of user authentication", "ref": "main", "steps": [ { "description": "## Authentication Overview\n\nOur auth system consists of...", "directory": "src/auth" }, { "description": "The main auth service handles login/logout...", "file": "src/auth/auth-service.ts", "line": 15, "pattern": "class AuthService" } ] }

模式三：交互式教程（可插入代码 + 终端命令）

适合"跟着做"的教学场景：让读者在某文件中插入给定代码块，再通过>>语法触发构建，形成"写代码 → 运行验证"的闭环：

{ "steps": [ { "description": "Let's add a new component. Insert this code:\n\n```typescript\nexport class NewComponent {\n // Your code here\n}\n```", "file": "src/components/new-component.ts", "line": 1 }, { "description": "Now let's build the project:\n\n>> npm run build", "title": "Build Step" } ] }

进阶特性：条件导览、命令集成与环境变量

• 条件导览（when）：按运行环境/工作区动态展示。例如只为 Windows 开发者展示的平台设置导览：

{ "title": "Windows-Specific Setup", "when": "isWindows", "description": "Setup steps for Windows developers only" }

• 命令集成：把讲解与 VS Code 动作绑定。注意commands执行的是VS Code 命令（如聚焦终端、运行任务、执行 CodeQL 查询），而非任意 shell 命令：

{ "description": "Click here to run tests or open terminal" }

• 环境变量：让文本在不同机器上展开为各自的值：

{ "description": "Your project is located at {{HOME}}/projects/{{WORKSPACE_NAME}}" }

仓库配套的真实案例集 examples.md 中收录了多类生产级用法作为佐证，例如：用selection在 Terraform 中圈出整块配置、用view切换到 CodeQL 面板、用commands在读者到达某步时自动runQuery、用纯内容步骤充当长教程中的"里程碑/检查点"（title形如"看看你的页面！🎉"）、以及用多段.tour+nextTour把"应用代码 / IaC / CI/CD"拆成三层独立导览分别讲解。这些"技术要点速查"说明：一个字段该在什么叙事时刻出现，往往比字段本身更值得学习。

版本化策略：ref的四种选择

导览讲解的是"某个时间点上的代码"，因此要把导览与代码快照对齐。Agent 文档给出四档策略：

校验脚本对ref的约定是：若设置了就必须是真实存在的分支/标签/提交（人工核对项）；而 SKILL.md 补充了一个实用细节——不设ref的导览在任何分支打开都会出现，这通常是工作区级导览（如 onboarding）的首选。在实操中，"要不要带版本"与"给谁看"强相关：讲解仓库全局结构的导览不要钉死在提交上，否则半年后路径早已失效。

编写最佳实践

Tour 组织

1. 渐进式展开（Progressive Disclosure）：先给高层概念，再逐步下钻细节；
2. 逻辑连贯（Logical Flow）：沿着自然的代码执行路径或功能开发路径推进；
3. 上下文分组（Contextual Grouping）：把相关联的功能与概念组织在一起；
4. 导航清晰（Clear Navigation）：使用有描述性的步骤标题与导览串联。

文件结构与命名

• 导览存放目录：.tours/、.vscode/tours/或.github/tours/（技能文档的标准路径是.tours/）；
• 文件名应有语义，如getting-started.tour、authentication-flow.tour；
• 复杂项目用编号组织：1-setup.tour、2-core-concepts.tour；
• 为新人打造 primary tour。

步骤设计

• 讲解清晰：用对话式、有帮助的口吻，而不是复述代码；
• 范围恰当：一个步骤只讲一个概念，避免信息过载；
• 善用可视化：代码片段、图示、相关链接都可纳入；
• 加入交互元素：命令链接与代码插入功能让读者"动手"而非只"读"。

写作心法（来自仓库配套技能）

配套的 SKILL.md 把"如何写好一条讲解"提炼为SMIG 公式，每条description按顺序回答四个问题：S（Situation）读者正看着什么、M（Mechanism）这段代码如何工作、I（Implication）对这个读者的目标为什么重要、G（Gotcha）聪明人最容易在哪踩坑。讲解应该告诉读者"光读文件学不到的东西"——点名设计模式、解释取舍、标记失效模式、交叉引用上下文。同时它还定义了数十种目标 persona（新员工、bug 修复者、PR 审查者、安全审查者、架构师等）与对应的叙事深度建议，让同一段代码库能长出"给人看"的不同导览。这与 Agent 文档结尾的总结一脉相承：好的导览是在讲述关于代码的故事，把复杂系统讲得平易近人，帮读者建立"各部件如何协同"的心智模型。

端到端编写流程与脚本化质量保障

标准工作流（继承自 Agent 文档）

1. 分析代码库：理解架构、入口点与核心概念；
2. 定义学习目标：这次导览希望读者最终理解什么；
3. 规划导览结构：按清晰递进关系排列多段导览；
4. 编写步骤大纲：把每个概念映射到具体文件与行号；
5. 撰写有吸引力的正文：对话式口吻 + 清晰解释；
6. 加入交互：命令链接、代码块、导航辅助；
7. 测试导览：验证所有文件路径、行号与命令确实可用；
8. 维护导览：代码变更后及时更新，防止漂移。

仓库把第 4、7 步脚本化到了两个工具中：

① 骨架生成器 generate_from_docs.py：当需要"从 README/文档生成导览"时，它解析 README 与文档，抽取真实的文件/目录引用（只保留在磁盘上真实存在的路径）、结构章节与外部链接，自动产出带[TODO: ...]占位的骨架.tour，再交由作者逐个填充。其解析细节可见源码：路径候选来自文档行内代码、Markdown 链接正则抓取、README 章节按标题切分并命中structure|architecture|overview|getting.started等关键词识别为目录步骤，并保证开头有 Welcome、结尾有"下一步看什么"。典型运行方式：

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

② 导览校验器 validate_tour.py：写作完成后必须运行，它按"错误 / 警告 / 提示"三级输出报告，覆盖以下机器可查的检查项：

• JSON 是否合法、title/steps/每步description是否齐全；
• 每个file路径真实存在且为文件，每个directory真实存在且为目录；
• line必须 ≥1 且不超出文件实际行数；selection的起止行在文件范围内且 start 不晚于 end；
• pattern正则能编译、且能匹配文件中至少一行（源码中用re.compile(...).search(...)验证，防止"匹配不到任何内容"的悬空锚点）；
• uri以https://或http://开头；
• nextTour能在.tours/目录内找到title完全一致的另一个.tour（源码遍历同级目录逐文件比对）；
• 内容步骤数量（无 file/dir/uri 的步骤）超过 2 个时告警；
• 首步是否缺少定位锚点、末步是否缺少收尾——输出叙事结构提示。

典型运行方式：

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

不放文件参数时，脚本会直接校验.tours/下全部导览并汇总退出码，便于接入 CI。仓库技能文档给出的兜底要求是：如果环境无法运行脚本，至少人工核对"首步有 file/directory 锚点、所有路径存在、行号在界内、nextTour精确匹配"。

③ 文件命名规范：<persona>-<focus>.tour（kebab-case），例如onboarding-new-joiner.tour、bug-fixer-payment-flow.tour、rca-login-outage.tour、pr-review-auth-refactor.tour。

需要避开的反模式

配套技能文档还明确列出五类反模式，作为质量红线：文件清单式（每步只写"此文件包含……"而没有叙事依赖）、通用化描述（未点名本代码库特有的模式/坑）、猜测行号（不读文件就不写行号）、忽略受众（保留所有不为该 persona 目标服务的步骤）、幻觉文件（路径不存在就应删步而非硬编）。这些与本 Agent 文档"路径必须真实、讲解必须对话式、范围必须聚焦"的导向完全一致。

团队落地与持续集成

code-tour.agent.md 对团队级使用给出了分层建议：

• 文件放置（File Placement）：工作区级共享导览放.tours/；文档化导览放.github/tours/或docs/tours/；个人导览可导出为外部文件单独使用。
• CI/CD 集成：在 PR 审查阶段检测导览漂移，在构建流水线中校验导览文件（可参考CodeTour Watch/CodeTour Watcher一类的现有方案），把validate_tour.py接入流水线即可实现"导览随代码一起被守卫"。
• 团队采用（Team Adoption）：先做一条 primary tour 让新人立刻受益；在 README.md 与 CONTRIBUTING.md 中挂出导览入口；把导览维护纳入常规迭代，持续收集反馈并改进正文。

配合技能文档给出的体验细节：isPrimary: true+ 工作区设置codetour.promptForPrimaryTour可在仓库打开时自动询问是否启动主导览；公开仓库可用浏览器版（vscode.dev/github.com/...）免安装直接播放。

结语

从 code-tour.agent.md 定义的方法论，到 codetour-schema.json 的字段权威约束、examples.md 的真实案例、以及 validate_tour.py / generate_from_docs.py 两个配套脚本，awesome-copilot 把"编写 CodeTour 导览"沉淀为一套从方法论到可执行工具的完整资产。掌握本文的 Schema、步骤类型、Markdown 语法、三种模式与版本化策略后，你就能为任意仓库（任何语言、任何规模）产出新人真正用得起来的导览——记住 Agent 文档那句收尾：好的导览讲述代码的故事，让复杂系统变得平易近人，帮助读者建立关于"一切如何协同工作"的心智模型。

【免费下载链接】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