medic

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: medic

Chìa vạn năng: một lệnh = tuyến phòng thủ cuối. Nó KHÔNG sửa gì — chỉ chứng minh hệ còn khoẻ và, nếu không, in đúng chỗ hở + 1 dòng lệnh sửa.

万能钥匙：一个命令 = 最后一道防线。它不会修改任何内容——只会证明系统仍然健康；如果不健康，则准确指出问题 + 给出 1 行修复命令。

WHAT

WHAT（是什么）

Purpose và context

目的与上下文

Purpose: chứng minh bằng MỘT lệnh rằng framework overstack còn khoẻ (luật cắn, không drift, docs khớp đĩa, code compile, eval không regress, backstop git sống); hỏng thì chỉ đúng chỗ hở + lệnh sửa.
Trigger (when to use):
- Trước khi commit / mở PR — chốt: đỏ thì đừng đẩy.
- Sau khi kéo bản mới / đổi máy — xem overstack còn nguyên vẹn.
- Nghi một rule "có vẻ không chặn nữa" — rà riêng tầng luật.
- Vừa thêm skill / rule / generator — medic tự báo nếu quên hàng rào cho nó (tự-mở-coverage).
- Chỉ muốn coi cấu trúc phòng thủ đang có —
```
medic --list
```
  .
Non-goals: không sửa gì, không vá nợ lớn (việc của proposal
```
030726-medic
```
), không thay
```
/fdk-uat
```
(đường cài remote).

目的：通过一个命令证明 framework overstack 仍然健康（rule 仍能拦截、没有 drift、docs 与磁盘内容一致、code 可编译、eval 无回归、backstop git 仍有效）；如果有问题，只指出具体故障 + 修复命令。
Trigger（何时使用）：
- 在 commit / 开启 PR 前——最终把关：出现红灯就不要推送。
- 拉取新版本 / 更换机器后——检查 overstack 是否仍然完整。
- 怀疑某条 rule「似乎不再拦截」——单独检查 rule 层。
- 刚添加 skill / rule / generator——如果遗漏对应护栏，medic 会自动报告（自动开启 coverage）。
- 只想查看现有防御结构——
```
medic --list
```
  。
**Non-goals：**不修改任何内容，不处理大型技术债（这是 proposal
```
030726-medic
```
的工作），不替代
```
/fdk-uat
```
（远程安装路径）。

Mental model

心智模型

phạm vi (user mô tả) → probe (rules · coverage · docs · code · eval · backstop) → ✓/⚠/✗ + detail + ↳ sửa → verdict

. Probe là đơn vị kiểm;

medic.py

là hub duy nhất — thêm kiểm tra = thêm probe, không đẻ tool lẻ.

范围（用户描述）→ probe（rules · coverage · docs · code · eval · backstop）→ ✓/⚠/✗ + 详情 + ↳ 修复 → verdict

。Probe 是检查单元；

medic.py

是唯一的 Hub——新增检查 = 新增 probe，不要创建零散工具。

Input và output contract

输入与输出契约

	Field	Required?	Ý nghĩa
In	phạm vi	không (mặc định = all)	từ khoá khớp tên/tag probe, nhiều phạm vi cách nhau khoảng trắng
In	`--ci`	không	cần exit-code để chốt (pre-commit/CI)
Out	báo cáo	có	mỗi probe ✓/⚠/✗ + detail + `↳ sửa` , verdict, recap, cấu trúc thư mục — chuyển NGUYÊN cho user
Out	exit code	khi `--ci`	FAIL → exit 1; không FAIL → 0

	字段	是否必填	含义
In	scope	否（默认 = all）	与 probe 名称/tag 匹配的关键字；多个范围之间用空格分隔
In	`--ci`	否	需要 exit code 用于把关（pre-commit/CI）
Out	报告	是	每个 probe 的 ✓/⚠/✗ + 详情 + `↳ 修复` 、verdict、recap、目录结构——原样传递给用户
Out	exit code	使用 `--ci` 时	FAIL → exit 1；没有 FAIL → 0

Rules và capabilities

规则与能力

RULE-01 (MUST): Không sửa gì trong lúc rà — medic chỉ chẩn đoán; sửa là bước riêng, có chủ đích.
RULE-02 (MUST): Tôn trọng fail-open: một probe lỗi → SKIP, không kết luận "hệ hỏng".
RULE-03 (MUST): Mô tả phạm vi, đừng đẻ lệnh — user cần kiểm tra chưa có thì thêm probe vào
```
medic.py
```
(một chỗ), đừng tạo tool lẻ mới.
RULE-04 (MUST): Self-contained:
```
medic.py
```
chỉ stdlib; compose tool đã có, không dependency ngoài.
RULE-05 (MUST): drift/stale chỉ regen/sync, KHÔNG sửa logic; xác minh hướng trước khi sync validator — bản đang CẮN mới là bản đúng (bài học 030726: sync sai hướng làm rail thành đen).
Capabilities: đọc repo framework + chạy probe cục bộ (read-only); không ghi, không mạng bắt buộc.

RULE-01（MUST）：检查期间绝不修改任何内容——medic 只负责诊断；修复是独立且有意图的步骤。
RULE-02（MUST）：尊重 fail-open：某个 probe 出错 → SKIP，不得据此断定「系统已损坏」。
RULE-03（MUST）：描述范围，不要额外生成命令——如果用户需要尚未存在的检查，应在
```
medic.py
```
中添加 probe（集中在一个位置），不要创建零散的新工具。
RULE-04（MUST）：Self-contained：
```
medic.py
```
仅使用 stdlib；组合使用已有工具，不引入外部 dependency。
RULE-05（MUST）：对于 drift/stale，只执行 regen/sync，不得修改逻辑；sync validator 前必须验证方向——当前实际拦截问题的版本才是正确版本（030726 的教训：sync 方向错误会导致护栏失效）。
能力：读取 framework 仓库并运行本地 probe（read-only）；不写入内容，也不强制联网。

Failure boundaries

失败边界

Có ✗ → verdict FAIL (exit 1 với
```
--ci
```
); đề nghị đúng 1 dòng
```
↳ sửa
```
, không tự chạy.
Chỉ ⚠ → nợ đã biết, báo user, không tự vá lớn.
Probe crash → SKIP (fail-open), không tính là FAIL.
Phạm vi không khớp probe nào → báo lại danh sách probe (
```
medic --list
```
), không đoán.

存在 ✗ → verdict 为 FAIL（使用
```
--ci
```
时 exit 1）；只建议恰好 1 行
```
↳ 修复
```
命令，不自行执行。
只有 ⚠ → 属于已知技术债，向用户报告，不自行进行大规模修复。
Probe crash → SKIP（fail-open），不计入 FAIL。
范围未匹配任何 probe → 返回 probe 列表（
```
medic --list
```
），不得猜测。

HOW

HOW（如何）

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	lời user	Chọn phạm vi theo mô tả user (không bắt nhớ subcommand): toàn bộ → không tham số; một phần → từ khoá khớp tên/tag probe ( `rules` , `coverage` , `docs` , `code` , `eval` , `backstop` )	danh sách phạm vi	mơ hồ → all
W02	deterministic	phạm vi	Chạy `python3 fdk/tools/medic.py [phạm vi]` (hoặc `medic [phạm vi]` nếu symlink `~/.local/bin/medic` đã có); thêm `--ci` khi cần exit-code	báo cáo + rc	→ W03
W03	deterministic	báo cáo	Chuyển cho user NGUYÊN output — medic đã in cô đọng; đừng cắt gọn phần này	user thấy đủ	có ✗ → B01; chỉ ⚠ → B02; sạch → xong

步骤	类型	输入	操作	输出/exit	失败/下一步
W01	judgment	用户输入	根据用户描述选择范围（不要死记 subcommand）：全部 → 不带参数；部分 → 使用与 probe 名称/tag 匹配的关键字（ `rules` 、 `coverage` 、 `docs` 、 `code` 、 `eval` 、 `backstop` ）	范围列表	不明确 → all
W02	deterministic	scope	运行 `python3 fdk/tools/medic.py [scope]` （如果已有 `~/.local/bin/medic` symlink，也可运行 `medic [scope]` ）；需要 exit code 时添加 `--ci`	报告 + rc	→ W03
W03	deterministic	报告	将 output 原样传递给用户——medic 已打印简洁报告；不要截取这一部分	用户看到完整内容	有 ✗ → B01；仅 ⚠ → B02；全部通过 → 完成

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	recovery	có ✗ (fail)	đề nghị chạy đúng 1 dòng `↳ sửa` medic gợi ý; drift/stale thì chỉ regen/sync (RULE-05)	user từ chối → dừng, verdict vẫn FAIL	chạy lại W02 sau khi sửa
B02	conditional_required	có ⚠ (warn), vd coverage 5/17, pre-commit chưa cài	báo user là nợ đã biết; không tự ý vá lớn — đó là việc của proposal `030726-medic`	—	kết thúc

ID	类型	Guard	行为	Skip / failure	Rejoin
B01	recovery	存在 ✗（fail）	建议运行 medic 给出的恰好 1 行 `↳ 修复` 命令；遇到 drift/stale 时只执行 regen/sync（RULE-05）	用户拒绝 → 停止，verdict 仍为 FAIL	修复后重新运行 W02
B02	conditional_required	存在 ⚠（warn），例如 coverage 5/17、pre-commit 尚未安装	告知用户这是已知技术债；不得自行进行大规模修复——这是 proposal `030726-medic` 的工作	—	结束

Validation và stopping

验证与停止条件

Verdict do

medic.py

quyết (tất định), không do model tự kết luận. Tối đa một vòng B01 → W02 mỗi lần gọi; còn đỏ thì dừng và báo.

Verdict 由

medic.py

决定（确定性），不得由 model 自行下结论。每次调用最多进行一轮 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.

正向：「在 commit 前运行 medic」→
```
python3 fdk/tools/medic.py --ci
```
→ 所有 probe 均为 ✓ → exit 0，报告「系统健康，可以 commit」。
**边界/失败：**当 CAPABILITIES 与磁盘内容不一致时执行
```
medic docs
```
→ docs probe 为 ✗，并附带
```
↳ 修复
```
regen → 建议执行该条准确命令，不自行修复；
```
--ci
```
返回 exit 1。