codetour插件已停用，推荐用vscode原生机制替代：纯markdown file://链接或vscode-notebook+注释跳转，稳定兼容、无扩展依赖、路径可显式映射、错误提示明确。
CodeTour 插件已不可用——微软于 2023 年底正式弃用并下架该扩展，当前 VSCode 市场中搜到的 code-tour-community 等复刻版，既不兼容原 .tour 格式，也无法在 GitHub Codespaces 或新版 VSCode 的 WebWorker 沙箱中正常运行。
CodeTour 安装失败或找不到插件的直接原因
- 在 VSCode 扩展市场搜索
CodeTour，看到的全是社区复刻版，作者不是Microsoft - 即使手动安装旧版
.vsix，也会因 API 变更（如vscode.workspace.findFiles()被沙箱限制）而报错或静默失效 - 启动命令如
CodeTour: Start New Tour在命令面板中完全不出现，说明插件未注册成功
替代方案：用 vscode-notebook + 注释跳转实现等效功能
核心思路是放弃“插件驱动跳转”，改用 VSCode 原生支持的机制：
- 新建一个
onboarding.code-notebook文件，类型设为 “Plain Text Notebook” - 每段 Markdown 单元格末尾加一行注释：
<!-- goto: ./src/utils/auth.ts:42 --> - 编写极简脚本
goto.js（放在项目根目录），调用vscode.window.showTextDocument()解析该注释并跳转 - 绑定快捷键（如
Ctrl+Alt+G）触发脚本，全程无扩展依赖
这样做的好处：
- 不扫描整个工作区，大型 monorepo 下无卡顿
- 路径解析可显式处理别名（如把
@/hooks/useApi映射为真实路径） - 跳转失败时能弹出明确错误提示，而不是静默跳过
更轻量、更稳定的选择：纯 Markdown + file:// 链接
如果你只需要“点击即跳转”，不需要自动播放、步骤控制或高亮，这个方案最可靠：
- 在
./docs/guide.md中写：@#@#@#@#@#@#@#@#@#@0 - 路径必须是绝对路径，但可用
${workspaceFolder}变量（需开启设置markdown.preview.useWorkspaceRoot） - 配合
markdown.extension.footnotes插件，把每步讲解写成带编号脚注，避免长文档滚动迷失
注意：
-
file://链接在 Windows/macOS/Linux 全平台生效，且不依赖任何插件 - Git 合并冲突几乎为零——Markdown 是文本，diff 清晰可读
- 所有路径别名（如
@/、~/）需提前转换为真实相对路径，否则链接失效
真正容易被忽略的点是：导览的目的不是“做出酷炫动画”，而是让新人第一次打开项目就能精准定位、理解上下文、不卡在环境或路径上。越依赖插件、越追求自动播放，就越容易在升级、换机器、开 Codespaces 时崩掉。稳定压倒一切，而稳定来自 VSCode 原生能力——比如 file:// 链接、Notebook 注释解析、甚至只是右键菜单里的 “Go to Definition”。
