repo-autopilot-plugin

三、使用方法

3.1 工具与参数

工具名：repo_autopilot_check

参数	必填	类型	说明
mode	是	string	doctor / drill / acceptance / compare
repo_root	否	string	repo-autopilot 仓库的绝对路径；不填则用随插件自带的那份
target	仅 compare	string	要比对的副本目录
python	否	string	解释器绝对路径；不填则自动探测（见 3.4）

3.2 四种模式

doctor —— 七项环境自检

& '
' 'scripts/doctor.py' '--json'

退出码	含义
0	七项自检全过

七项分别是：state 目录完整性、mode.json 合法性、队列孤儿任务、 闸门悬挂审批、写 token 文件、本地小模型探活、GitHub 连通性。

真实输出（成功时，插件渲染为）：

[doctor] 七项自检全过
解释器：由 python 参数指定（未探测）
$ & 'D:\PythonEnv\venv\Scripts\python.exe' 'scripts/doctor.py' '--json'
    "name": "本地小模型探活",
    "ok": true,
    "detail": "embedding 维度 1024",
...

drill —— 7 天实战演练台账

& '
' 'tools/daily_drill.py' '--summary'

退出码	含义
0	7 天台账合格
1	还没满 7 天，不是失败

这条退出码语义是这套系统的典型情况：工具用退出码表达状态而不是成败。 插件把它编码进模式表，模型不需要猜。

[drill] 7 天演练台账合格（仍需人类评审补丁质量）
$ & '...python.exe' 'tools/daily_drill.py' '--summary'
演练累计记录 7 条：
  day  1　2026-09-12　模式 full　人类介入 0 次　对外写 0 次　误操作 0　通过
  ...
  · 7 天记录齐了 —— 剩下的判断（补丁质量）按路线属于人类评审

acceptance —— 验收步骤表

& '
' 'tools/acceptance.py' '--list'

退出码	含义
0	验收步骤表可加载

列出 0.1 ~ 8.2 全部验收步骤及其检查项（capabilities / baseline / queue / gate / drill …）。

compare —— 副本哈希比对

& '
' 'tools/package.py' 'compare' ''

退出码	含义
0	副本与源仓库一致，没有合并风险
1	有差异 —— 合并前先问清是谁改的

合并两份副本之前先跑它。 真实输出：

[compare] 副本与源仓库一致，没有合并风险
$ & '...python.exe' 'tools/package.py' 'compare' 'D:\apps\repo-autopilot'
比对 源仓库 ↔ D:\apps\repo-autopilot
  源仓库清单 189 个文件
  （副本多出 17 个非包内文件，**不算合并风险**，列出来给你看：...）
  （另有 173 个本机自有文件，按设计不算差异）
结论：189 个包内文件内容哈希逐一相同，没有合并风险

判据是内容哈希，不是时间戳、不是文件名、不是"推送成功的提示"。 副本多出的文件是告知（不算风险）；缺文件或内容不符才是合并风险。

3.3 输出格式

[doctor] 七项自检全过                    ← 结论（人话）
解释器：由 python 参数指定（未探测）      ← 用的哪个解释器、怎么来的
$ & 'D:\...\python.exe' 'scripts/doctor.py' '--json'   ← 实际命令行（可复制重跑）
                   ← 原始输出

• 命令行的实际文本永远回显，便于手工复现与排错；
• 输出tail 限 25 行，避免撑爆上下文；
• 结论永远是人话，不是退出码。

3.4 解释器解析顺序

不填 python 参数时，按顺序探测，第一个能 import yaml, requests 的胜出：

1. 环境变量 REPO_AUTOPILOT_PYTHON
2. python3
3. python

探测结果会缓存，同一次运行只探一次。三个都不行时明确报：

找不到能用的解释器（试过：环境变量 REPO_AUTOPILOT_PYTHON、python3、python，
都没法 import yaml, requests）—— 这是环境问题，不是仓库问题。
请用 python 参数指向装了依赖的解释器，或设环境变量 REPO_AUTOPILOT_PYTHON

3.5 故障分类

插件会先把「谁的错」分清楚再报告，避免把环境问题说成仓库问题：

症状	插件的结论
解释器不存在	解释器找不到（是环境的问题，不是仓库的问题）
解释器缺依赖	解释器缺依赖（是环境的问题，不是仓库的问题）
repo_root 给错	repo_root 下找不到这个入口点（多半是路径给错了，不是仓库坏了）
退出码不在预期集合	照常给出模式结论，并注明「退出码不在预期集合内」

3.6 典型用法

① 合并两份副本之前确认没风险

repo_autopilot_check(mode='compare', repo_root='D:\work\repo-autopilot', target='D:\apps\repo-autopilot')

② 一条命令看这台机器能不能跑

repo_autopilot_check(mode='doctor', repo_root='D:\work\repo-autopilot')

③ 交付前确认演练台账合格

repo_autopilot_check(mode='drill', repo_root='D:\work\repo-autopilot')

---