Code Tour 是微软出品的轻量 VSCode 插件，通过 JSON 文件在项目中创建可执行交互式导览，支持添加带 Markdown 说明的代码步骤、启动播放、Git 协作与 PR 集成。
code tour 是一个轻量但实用的 vscode 插件，能帮你为项目关键路径、模块结构或新成员上手流程制作可执行的交互式导览。它不依赖外部服务，所有信息以 json 文件形式保存在项目中，便于版本管理与协作。
安装与初始化导览
在 VSCode 扩展市场搜索 Code Tour（作者：Microsoft），安装后重启编辑器。首次使用时，按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），输入 Code Tour: Create Tour，回车后会生成一个 .vscode/tours/ 目录，并创建首个 tour 文件（如 getting-started.tour）。
添加步骤：聚焦真实代码上下文
打开你要讲解的源文件，将光标定位到某行（比如一个核心函数定义、配置入口或报错高发位置），然后调用命令 Code Tour: Add Step。插件会自动记录当前文件、行号、折叠状态，并弹出输入框让你填写说明文字。支持 Markdown 语法，可加粗、列表、代码片段（用反引号包裹）。
- 建议每步只讲一个明确目的，例如：“这是 JWT 验证中间件，请求头中的 token 在此处解析”
- 避免长段落，多用短句 + 行内代码标注，如
authMiddleware.js#L23 - 可对同一文件添加多个步骤，形成逻辑递进（如从路由入口 → 控制器 → 服务层）
运行与分享导览
通过命令 Code Tour: Start Tour 选择要播放的 tour 文件，VSCode 会在侧边栏打开导览面板，逐条高亮代码并显示说明。支持暂停、跳转、退出。导览过程不修改代码，纯只读引导。
- 导览文件是普通 JSON，可直接提交到 Git，新成员克隆后装好插件就能运行
- 适合嵌入 PR 描述中，例如：“本次重构涉及三处关键改动，详见
.vscode/tours/refactor-v2.tour” - 团队可约定命名规范，如
onboarding.tour、api-flow.tour、debug-cache.tour
进阶技巧：提升导览实用性
导览不是文档替代品，而是“带路的人”。可以配合其他能力增强效果：
- 用 Code Tour: Insert Code Snippet 在说明中插入当前选中代码块，方便对比前后变化
- 在 tour 文件里手动编辑
when字段，设置条件触发（如仅当存在env.local时显示某步） - 结合 Settings Sync 或 Workspace Trust，确保团队成员开启相同插件配置
基本上就这些。不需要写文档、不用搭平台，几步操作就能把“口头讲三遍”的知识，变成点开就看懂的代码现场导览。
