CodeTour 是将代码上下文转化为可播放、可分享、可版本控制的交互路径的工具；需在项目根目录 .tours/ 下创建 .tour.json 文件，路径须为小写相对路径，行号从1起，多行用 range，命令嵌入需以 >> 开头独占一行，且依赖插件、Git 提交 .tours/ 目录及静态源码路径。
CodeTour 不是“看文档”的替代品，而是把代码上下文变成可播放、可分享、可版本控制的交互路径——只要路径写对、文件存在、行号有效，导览就能跑起来。
如何快速创建并保存第一个 .tour 文件
CodeTour 默认把导览存为 JSON 文件，路径固定在项目根目录下的 .tours/ 子目录中（不是 .vscode/，也不是随意位置）。命名后缀是 .tour.json，比如你起名 setup-flow，最终生成的就是 .tours/setup-flow.tour.json。
- 必须先打开一个源码文件（哪怕只是空的
index.ts），否则CodeTour: Start New Tour命令会灰掉 - 命令面板里输入
CodeTour: Start New Tour（不是Record Tour，后者是旧版或混淆项） - 输入名称后回车，此时编辑器右下角会出现 Tour 状态栏，但还没任何步骤——得手动加
- 光标停在某行，右键 →
CodeTour: Add Step to Current Tour，填描述再回车才算真正落盘 - 别忘了点右下角软盘图标
Save Tour，否则关窗口就丢步骤
跨文件跳转时路径和行号怎么写才不报错
导览能跨文件，但路径必须是相对于项目根目录的**相对路径**，且文件必须真实存在。VS Code 不会帮你创建不存在的文件，也不会自动修正拼错的路径。
- 错误写法：
"file": "src/config/index.ts"—— 如果项目没src/config/index.ts，播放时直接卡住，无提示 - 正确写法：
"file": "src/config/index.ts"（小写、斜杠方向一致、无多余空格） - 行号从 1 开始计数，
"line": 0或负数会被忽略，"line": 999超出文件长度则跳到末尾 - 想高亮多行？用
"range": [12, 15]（表示第 12–15 行），不是"line": 12+ 手动拖选 - 路径区分大小写：macOS/Linux 下
Src/≠src/，Windows 虽不敏感但建议统一小写避免协作问题
导览里执行命令（如 npm run dev）为什么点不动
CodeTour 支持在步骤描述中嵌入可点击命令，但格式非常严格：必须以 >> 开头，且独占一行，后面紧跟完整 shell 命令。
- 有效写法：
>> npm run dev
或>> git status
- 无效写法：
运行 >> npm run dev
（带前缀文字）、>>npm run dev
（>>和命令间无空格）、>> npm run dev && echo done
（含&&会截断） - 命令在当前工作区根目录下执行，不是在步骤所在文件目录
- 权限问题常见：Windows 上若启用了 PowerShell 执行策略限制，
>> npm可能静默失败，建议改用>> cmd /c npm run dev
导览文件提交 Git 后别人打不开？检查这三点
导览本质是 JSON 配置，但依赖三个隐性条件才能复现：工作区结构、VS Code 版本、CodeTour 插件状态。缺一不可。
- 确认对方也装了 CodeTour 插件（v0.19+ 推荐，老版本不支持
range或命令执行） -
.tours/目录要进 Git，但别把.tours/*.tour.json加进.gitignore—— 这是最常被忽略的点 - 如果导览里引用了
node_modules/下的文件，或临时生成的dist/，别人拉代码后这些路径不存在，播放必然失败
最稳妥的做法：所有导览只绑定项目源码（src/、lib/、config/），避开构建产物和依赖目录。路径越“静态”，越容易跨环境复现。
