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 的核心能力被划分为四个层次Tour 文件的创建与管理按官方 Schema 编写完整.tourJSON为复杂代码库设计逐步走查实现正确的文件引用、目录步骤与内容步骤用 git ref分支、提交、标签配置版本关联设置 primary tour 与 tour 串联序列用when子句创建条件导览。进阶步骤能力内容步骤、目录步骤、选区步骤、命令链接、终端命令、可插入代码块与{{VARIABLE_NAME}}环境变量。CodeTour 风格 Markdown以工作区相对路径引用文件、用[#stepNumber]引用步骤、用[TourTitle]/[TourTitle#step]引用其他导览、内嵌图片与富 Markdown/HTML。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 顶层字段字段类型语义说明titlestring必填。导览的展示名称也是nextTour串联时用于精确匹配的名称descriptionstring可选。展示为 tooltip 的导览说明常写成给谁看、看完能懂什么的一句话refstring可选。绑定的 git ref取值分支 / 提交 / 标签见下文版本化策略isPrimaryboolean是否为该代码库的主导览团队内通常只有一个 primary tour用于新人一进仓库就能触达nextTourstring后续导览的title结束时 VS Code 会提示自动衔接下一段导览值必须与另一.tour的title完全一致whenstring条件导览运行时求值的 JavaScript 表达式为真才展示该导览stepMarkerstring源码注释中的步骤锚点标记设置后从源文件注释如// CT定位步骤适合行号频繁漂移的活跃代码需改动源码默认不建议stepsarray必填。步骤列表每步至少包含description其中stepMarker与when不在主 Agent 文档的 JSON 骨架里但在 codetour-schema.json 中均有明确定义stepMarker为标识一行代码是某导览步骤的 marker 字符串属于进阶可选项。步骤级字段Step 字段字段类型语义与约束descriptionstring必填。步骤讲解正文支持 Markdowntitlestring可选。步骤的友好标题filestring步骤关联的文件必须相对工作区根目录不允许绝对路径与./前缀directorystring步骤关联的目录同样必须为相对仓库根目录的路径uristring步骤关联的绝对 URIhttps://典型用于 PR、Issue、RFC、ADR 与外部文档linenumber关联的行号Schema 描述为1 起始1-basedpatternstring用正则按内容而非行号匹配行适合行号经常漂移的文件selectionobject文本选区含start/end各自带 1-based 的line与character当一整块代码才是讲解重点时使用commandsarray到达该步时执行的 VS Code 命令 URI 列表如workbench.action.terminal.focus、workbench.action.tasks.runTaskviewstring到达该步时自动聚焦的 VS Code 面板/侧边栏 viewId如terminal、explorer、problems、scm、codeQLDatabases从 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 的决策表场景建议步骤类型导览开篇/收尾的纯讲解content内容步骤无文件关联正文中建议最多 2 个开头 结尾这个文件夹里装了什么directory目录步骤——无需逐一讲解每个文件即可建立结构感一行代码就能讲清一个概念file line讲解重点是一个函数/类/配置段这样的代码块selection选区步骤文件易变、行号不断漂移pattern用正则匹配内容如pattern: class AuthServicePR / Issue / 文档提供了为什么uri如https://...读者应打开终端或资源管理器view聚焦某面板或commands自动执行某命令两条关键纪律来自仓库配套技能与校验脚本路径必须相对仓库根目录。校验脚本 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 给出了三种经实战验证的结构模式下面完整列出。模式一新人 OnboardingisPrimarynextTour串联用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步骤圈定范围再用fileline/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: Lets add a new component. Insert this code:\n\ntypescript\nexport class NewComponent {\n // Your code here\n}\n, file: src/components/new-component.ts, line: 1 }, { description: Now lets 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形如看看你的页面、以及用多段.tournextTour把应用代码 / IaC / CI/CD拆成三层独立导览分别讲解。这些技术要点速查说明一个字段该在什么叙事时刻出现往往比字段本身更值得学习。版本化策略ref的四种选择导览讲解的是某个时间点上的代码因此要把导览与代码快照对齐。Agent 文档给出四档策略策略ref取值适用场景无None不设ref教程类导览读者会在游览中亲手修改代码导览需始终跟随当前工作区当前分支如ref: main讲解仅存在于某分支的特性或文档当前提交具体 commit内容稳定、不希望随时间漂移的导览标签Tags如ref: v2.3.0发布专属导览与版本说明校验脚本对ref的约定是若设置了就必须是真实存在的分支/标签/提交人工核对项而 SKILL.md 补充了一个实用细节——不设ref的导览在任何分支打开都会出现这通常是工作区级导览如 onboarding的首选。在实操中要不要带版本与给谁看强相关讲解仓库全局结构的导览不要钉死在提交上否则半年后路径早已失效。编写最佳实践Tour 组织渐进式展开Progressive Disclosure先给高层概念再逐步下钻细节逻辑连贯Logical Flow沿着自然的代码执行路径或功能开发路径推进上下文分组Contextual Grouping把相关联的功能与概念组织在一起导航清晰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按顺序回答四个问题SSituation读者正看着什么、MMechanism这段代码如何工作、IImplication对这个读者的目标为什么重要、GGotcha聪明人最容易在哪踩坑。讲解应该告诉读者光读文件学不到的东西——点名设计模式、解释取舍、标记失效模式、交叉引用上下文。同时它还定义了数十种目标 persona新员工、bug 修复者、PR 审查者、安全审查者、架构师等与对应的叙事深度建议让同一段代码库能长出给人看的不同导览。这与 Agent 文档结尾的总结一脉相承好的导览是在讲述关于代码的故事把复杂系统讲得平易近人帮读者建立各部件如何协同的心智模型。端到端编写流程与脚本化质量保障标准工作流继承自 Agent 文档分析代码库理解架构、入口点与核心概念定义学习目标这次导览希望读者最终理解什么规划导览结构按清晰递进关系排列多段导览编写步骤大纲把每个概念映射到具体文件与行号撰写有吸引力的正文对话式口吻 清晰解释加入交互命令链接、代码块、导航辅助测试导览验证所有文件路径、行号与命令确实可用维护导览代码变更后及时更新防止漂移。仓库把第 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 不晚于 endpattern正则能编译、且能匹配文件中至少一行源码中用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.tourkebab-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考