medic

技能：medic

万能钥匙：一条命令 = 最后一层防线。它不会修复任何问题——只会证明系统仍然健康；如果不是，就精确指出缺口 + 给出 1 行修复命令。

WHAT

Purpose 和 context

• **Purpose：**用一条命令证明 overstack 框架仍然健康（规则生效、不漂移、文档与磁盘一致、代码可编译、评测无回归、Git 后备机制正常）；如果有问题，就精确指出缺口 + 给出修复命令。
• Trigger（何时使用）：
  • 提交 / 开启 PR 前——做最后确认：有红项就别推送。
  • 拉取新版本 / 更换机器后——检查 overstack 是否仍然完好。
  • 怀疑某条规则“似乎不再拦截”——单独检查规则层。
  • 刚添加技能 / 规则 / 生成器——如果忘了为它设置防护栏，medic 会自动报告（自动扩展覆盖范围）。
  • 只想查看现有防御结构——medic --list。
• **Non-goals：**不修复任何问题，不偿还大型技术债（由提案 030726-medic 处理），不替代 /fdk-uat（远程安装路径）。

Mental model

范围（用户描述）→ probe（rules · coverage · docs · code · eval · backstop）→ ✓/⚠/✗ + 详情 + ↳ 修复 → 判定结果。Probe 是检查单元；medic.py 是唯一的 hub——新增检查 = 新增 probe，不另造零散工具。

Input 和 output contract

	Field	Required?	含义
In	范围	否（默认为 all）	匹配 probe 名称 / 标签的关键词，多个范围以空格分隔
In	--ci	否	需要 exit-code 时使用（pre-commit/CI）
Out	报告	是	每个 probe 的 ✓/⚠/✗ + 详情 + ↳ 修复、判定结果、摘要、目录结构——原样转交给用户
Out	exit code	使用 --ci 时	FAIL → exit 1；没有 FAIL → 0

Rules 和 capabilities

• RULE-01 (MUST)：检查过程中不做任何修改——medic 只负责诊断；修复是单独且有意为之的步骤。
• RULE-02 (MUST)：遵循 fail-open：probe 出错 → SKIP，不判定“系统已损坏”。
• RULE-03 (MUST)：描述范围，不另造命令——如果用户需要的检查尚不存在，就在 medic.py 中添加 probe（一处修改即可），不要创建新的零散工具。
• RULE-04 (MUST)：独立运行：medic.py 仅使用 stdlib；组合已有工具，不引入外部依赖。
• RULE-05 (MUST)：漂移 / 过期时只重新生成 / 同步，不能修改逻辑；同步 validator 前必须验证方向——当前正在生效的版本才是正确版本（030726 的教训：错误方向的同步会让 rail 变黑）。
• Capabilities：读取框架仓库 + 运行本地 probe（只读）；不写入，无需联网。

Failure boundaries

• 出现 ✗ → 判定为 FAIL（使用 --ci 时 exit 1）；只建议 1 行 ↳ 修复，不自行运行。
• 只有 ⚠ → 报告已知技术债，不自动进行大型修复。
• Probe 崩溃 → SKIP（fail-open），不计为 FAIL。
• 范围未匹配任何 probe → 提示 probe 列表（medic --list），不做猜测。

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	用户描述	根据用户描述选择范围（无需记住子命令）：全部 → 不带参数；部分 → 使用与 probe 名称 / 标签匹配的关键词（rules、coverage、docs、code、eval、backstop）	范围列表	不明确 → all
W02	deterministic	范围	运行 python3 fdk/tools/medic.py [范围]（如果已有符号链接 ~/.local/bin/medic，也可运行 medic [范围]）；需要 exit-code 时添加 --ci	报告 + rc	→ W03
W03	deterministic	报告	将输出原样转交给用户——medic 已经简明输出；不要删减这部分内容	用户看到完整报告	有 ✗ → B01；只有 ⚠ → B02；全部通过 → 完成

Branches

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	recovery	有 ✗（失败）	建议运行 medic 提供的唯一一行 ↳ 修复 命令；漂移 / 过期时只重新生成 / 同步（RULE-05）	用户拒绝 → 停止，判定结果仍为 FAIL	修复后重新运行 W02
B02	conditional_required	有 ⚠（警告），例如 coverage 5/17、尚未安装 pre-commit	告知用户这是已知技术债；不要擅自进行大型修复——这由提案 030726-medic 处理	—	结束

Validation 和 stopping

判定结果由 medic.py 决定（确定性），模型不得自行判断。每次调用最多进行一轮 B01 → W02；如果仍有红项，就停止并报告。

Examples

• Positive: "chạy medic trước khi commit" → python3 fdk/tools/medic.py --ci → mọi probe ✓ → exit 0, báo "hệ khoẻ, commit được".
• Boundary/failure: "medic docs" khi CAPABILITIES lệch đĩa → probe docs ✗ kèm ↳ sửa regen → đề nghị đúng lệnh đó, không tự sửa; --ci trả exit 1.