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

repo-doctor

部署与运维

查看项目

更新于 10-15 11:59

技能介绍

Repo Doctor 是一个命令行工具集合，用于审计代码仓库是否符合 agentic-quality 标准，并管理 AGENTS.md 入口文档。

用途 Repo Doctor 对仓库进行评分，评分依据是 agentic-quality 标准（位于 rules/agentic-quality.md 的跨仓库规范），该标准关注代码、注释、文档和结构是否能让一个冷启动的智能体会话顺利导航。同时，它负责 AGENTS.md 协议：创建、审计、升级和组织级调查仓库的入口文档。

主要能力

  • 仓库评分器：运行 scripts/repo-doctor.py，审计当前目录或其他仓库，输出人类可读面板或 JSON 格式。包含六个维度，每个维度 0-5 分，加权后给出字母等级：
    • entry_docs：AGENTS.md/CLAUDE.md 是否存在、Landmines 章节、200 行/16,000 字符预算、提交新鲜度、CLAUDE.md 遮蔽 AGENTS.md 的情况。权重 2.0。
    • docs_health：README、当文档超过 6 个文件时的 docs/ 索引、索引中的幽灵链接。权重 1.5。
    • comments：最大源文件上的契约块、超过 400 行的文件中的章节标记。权重 2.0。
    • structure：巨型文件（>800 警告，>1500 严重；生成文件豁免）、仓库根目录杂物。权重 2.0。
    • enforcement：测试、CI、单一检查入口点、不变量门禁脚本。权重 1.5。
    • doc_pairing：最近的 feat/fix 提交中同时修改 *.md 文件的比例。权重 1.0。 完整评分标准见 references/scoring-rubric.md。
  • 深度扫描：scripts/repo-scan.py 生成确定性事实 JSON，每个事实引用 file:line 或命令，并从 git 历史中提取地雷候选（始终是问题，而非事实）。支持 --json 和 --only 参数。
  • AGENTS.md 管理：scripts/agents-md.py 提供 scaffold（创建）、audit（审计，可用 --diff 生成补丁）、survey（组织调查，只读 gh api，不克隆）。audit 在发现警告或严重问题时退出码为 10。
  • AGENTS.md 协议：references/agents-md-protocol.md 定义了内容、排除项、大小与拆分、CLAUDE.md 遮蔽、陈旧性等。关键事实：Claude Code 仅在工作目录或其上层没有 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时读取 AGENTS.md，除非该 CLAUDE.md 导入了 @AGENTS.md。
  • 检查脚本：scripts/check-memory-docs.py 作为协议编码的 Claude Code 事实的绊线，支持 --offline 用于 PR CI，--live 用于计划的新鲜度工作流。

使用方式

  1. 深度扫描：python scripts/repo-scan.py --repo path/to/repo --json > facts.json
  2. 创建：python scripts/agents-md.py scaffold --repo path/to/repo --facts facts.json > AGENTS.draft.md 或 python scripts/agents-md.py scaffold --repo path/to/repo --write（创建，不覆盖）
  3. 审计：python scripts/agents-md.py audit --repo path/to/repo（警告/严重时退出码 10）；生成补丁：python scripts/agents-md.py audit --repo path/to/repo --diff > agents-md.patch，然后 git apply。
  4. 组织调查：python scripts/agents-md.py survey --org my-org --json | jq '.meta'
  5. 评分：python scripts/repo-doctor.py [--repo path] [--json] [--strict]

工作流规则：

  • 先扫描再起草。脚手架的原型模板（assets/agents-md/：PHP CMS + DDEV + bundler、Node/TS app、Python service、静态站点、通用）只包含占位符，而非声明。扫描无法验证的内容变成 TODO(owner) 问题。
  • 所有者完成草稿：回答或删除每个 TODO(owner)，运行每个命令一次并去掉其 [untested] 标签，删除 DRAFT 注释。审计会标记所有三项直到完成。
  • 补丁从不移除地雷。--diff 添加缺失章节存根、为遮蔽的 CLAUDE.md 添加 @AGENTS.md 导入、注释死命令、移动过大章节。
  • 与 Claude Code 自身的检查配对。/doctor prompt-audit 进行语义检查（过时或矛盾的指令）；本工具是确定性的、可 CI 化的。
  • 永远不要运行仓库工具来“验证”命令：Composer 插件、justfile 反引号和 make $(shell ...) 即使列出也会执行仓库代码。扫描仅读取跟踪文件和 git 元数据，从不打开秘密文件，并从 .env.example 保留变量名（而非值）。

适用场景

  • 审计单个仓库或整个组织的仓库入口文档质量。
  • 在 CI 中作为门禁，确保 AGENTS.md 和文档标准不被退化。
  • 为新建仓库或现有仓库创建、审计、升级 AGENTS.md。
  • 在 monorepo 中管理嵌套入口文档，根入口文档作为路由器，每个有契约的包需要自己的入口文档和检查。

限制

  • 评分器是启发式的，标记的文件可能合理（例如单一写入者模块），需要人工验证后再行动。
  • 补丁从不移除地雷，仅添加缺失章节、导入、注释和移动。
  • 不评估代码级债务（重复、死代码、安全），那是 techdebt 工具的职责。
  • 默认只读，唯一写入步骤是 scaffold --write，且拒绝覆盖。
  • 工具不运行仓库工具来验证命令，以避免执行仓库代码。
  • 在 cp1252/纯终端上降级为 ASCII 输出。

资源：scripts/repo-doctor.py、scripts/repo-scan.py、scripts/agents-md.py、scripts/check-memory-docs.py、references/agents-md-protocol.md、references/scoring-rubric.md、references/comment-doctrine.md、references/monorepo-structure.md、assets/agents-md/、assets/AGENTS-template.md、assets/docs-index-template.md。