SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场code-tour

code-tour

编程与开发

查看项目

更新于 10-15 14:34

技能介绍

用途

Code Tour 技能用于创建 CodeTour 文件——一种面向特定角色、逐步引导的代码库导览，直接链接到真实文件和行号。CodeTour 文件存放于 .tours/ 目录，配合 VS Code CodeTour 扩展使用。

该技能的目标是写出“目标读者在第一次打开这个仓库时希望存在的那份导览”。一份好的导览不只是给文件加注释，而是面向特定人群讲述一个叙事：什么重要、为什么重要、接下来该做什么。

主要能力

技能内置两个脚本：

  • scripts/validate_tour.py：在写完任何导览后运行。检查 JSON 有效性、文件/目录是否存在、行号是否在范围内、模式匹配、nextTour 交叉引用以及叙事结构。运行命令： python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .

  • scripts/generate_from_docs.py：当用户要求从 README/文档生成时，先运行此脚本提取骨架，再填充内容。运行命令： python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour

技能还附带两个参考文件：

  • references/codetour-schema.json：权威 JSON schema，用于核对任何字段名或类型。
  • references/examples.md：来自生产仓库的 8 个真实 CodeTour 导览，附有技术注解，展示 commands、selection、view、pattern、isPrimary、多导览系列等特性的实际用法。

支持的步骤类型

所有步骤类型包括：content（介绍/结尾，最多 2 个）、directory、file+line（主力类型）、selection（代码块）、pattern（正则匹配）、uri（外部链接）、view（聚焦 VS Code 面板）、commands（运行 VS Code 命令）。

路径规则：file 和 directory 必须相对于仓库根目录，不能使用绝对路径，也不能有前导 ./。

使用方式

技能的工作流程分为四步：

  1. 探索仓库：列出根目录、阅读 README、检查关键配置文件（package.json、pyproject.toml、go.mod、Cargo.toml、composer.json 等），识别语言、框架和项目用途，映射 1–2 层目录结构，找到入口点，并记录实际存在的文件。

  2. 读取意图：从用户的一条消息中推断角色、深度和关注点。技能提供了一张意图映射表，将“onboarding”“PR review”“debug X”“architecture”等说法映射到对应角色和深度。仅在无法推断时才提问。

  3. 阅读实际文件：导览中的每个文件路径和行号都必须通过阅读文件来验证。指向错误文件或不存在的行号比没有导览更糟。

  4. 编写导览：保存到 .tours/<persona>-<focus>.tour，并参照 schema 核对字段。

适用场景

技能覆盖 20 种角色，包括：Vibecoder（快速了解）、New joiner（结构化上手）、Bug fixer（快速定位根因）、RCA investigator（失败因果链）、Feature explainer（单功能端到端）、PR reviewer（正确审查变更）、Security reviewer（信任边界）、Refactorer（安全重构）、External contributor（不破坏地贡献）、Tech lead / architect（模块边界与权衡）等。

技能还针对不同仓库类型（服务/API、库/SDK、CLI 工具、Monorepo、框架、数据管道、前端应用）给出不同的关注重点和典型锚点文件。

对于复杂代码库，技能支持设计导览系列，通过 nextTour 字段串联多个导览，形成从宽泛到深入、从入门到深潜的升级路径。

限制

技能明确列出 CodeTour 不支持的功能：

  • 不支持在 X 秒后自动前进到下一步。导航始终是手动的，没有计时器、延迟或自动播放机制。
  • 不支持在步骤中嵌入视频或 GIF。描述只能是 Markdown 文本。
  • 不支持运行任意 shell 命令。commands 只能执行 VS Code 命令（如 workbench.action.terminal.focus），不能执行 shell 命令。
  • 不支持分支或条件下一步。导览是线性的。when 控制导览是否显示，而不是哪一步接哪一步。
  • 仅部分支持不打开文件就显示步骤（content-only 步骤）。

此外，技能强调：只创建 .tour JSON 文件，绝不创建、修改或搭建任何其他文件。