Skill Code Doctor — Skill 代码工程体检

定位

对被测 Skill 做静态为主的代码工程审查，覆盖八个维度：

不做的事：不在无隔离条件下运行被测代码、不做深度安全扫描（交给 skill-safety-vetter 类技能）、不直接修改被测文件（只出报告）。

关于执行边界：默认静态。唯一被允许的执行是自带的只读扫描器 scripts/static_scan.py，以及自带沙盒执行器 scripts/sandbox/（已随附，须满足 references/scoring-and-report.md 的「沙盒执行器准入条件」六项全满足）。沙盒是轻隔离，逃逸面与结论强度限制见同文件「沙盒局限声明」——它只能证「未观测到」，不能证「不存在」。

环境要求：Python ≥ 3.9（scripts/sandbox/static_rules.py 依赖 ast.unparse；审计钩子本身只需 3.8+）。低于此版本时静态规则引擎与沙盒均不可用，须先如实报告环境不满足，不得降级为无证据的结论。

工作流

第 1 步：定位被测对象

确认被测 Skill 的根目录。来源优先级：用户显式给的路径 > ~/.workbuddy/skills/<skill-name>/ > 当前工作区内 .workbuddy/skills/<skill-name>/。目录不存在即终止并报告，不猜测。

第 2 步：收集计数类证据（必做）

运行自带扫描器（只读，不触碰被测代码）：

python scripts/static_scan.py <被测skill根目录>

需要原始数据做交叉核验时加 --json。扫描器输出：文件清单与体量、SKILL.md front matter 字段与 TODO 残留、重复代码块（滑窗检测）、模板残留文件、单文件巨石嫌疑、安全入口级特征。

第 2.5 步（可选）：沙盒行为自检与交叉印证

需要回答「它运行时实际动了什么」时才做；纯结构体检可跳过。先确认环境满足（Python ≥3.9），再执行：

python scripts/sandbox/verdict.py --skill <被测skill根目录> --timeout 20

输出四象限判定：实证（静态命中且实际发生）/ 潜伏（静态命中但未发生）/ 盲区（实际发生但静态漏检）/ 已声明（文档已说明的能力，按可选级处理）。盲区是静态规则漏检的硬证据，必须写进报告。

启用沙盒的报告，口径说明须按 references/scoring-and-report.md「沙盒局限声明」写明：隔离级别（轻隔离）、未覆盖的逃逸面（ctypes / 原生二进制）、执行脚本数与阻断策略。

注意：执行器按设计跳过 scripts/sandbox/（执行器目录本身），故该目录下的静态命中会呈「潜伏」态——这属预期，不是漏检。判读时若发现潜伏项的命中位置全部落在该目录，可降为可选级。

第 3 步：逐维度人工判读

加载 references/dimensions-core.md 与 references/dimensions-support.md，将扫描器证据逐条对照检查项判读。铁律：

1. 每条结论挂 文件:行号 + 计数证据；无证据不下结论。
2. 扫描器特征命中 ≠ 问题成立，必须读上下文二次确认（如 eval 出现在注释里不算）。
3. 无法静态判定的项标「待人工确认」，不给无风险结论。

第 4 步：评分与出报告

按 references/scoring-and-report.md 的评分制与模板输出报告。达标线：总分 ≥85 且无阻塞项。报告末尾的「口径说明」必须包含：扫描时间、被测路径、扫描器版本；并按是否启用沙盒执行器二选一写明——未启用则写「本次为纯静态体检，未做任何运行时验证」，已启用则写明隔离级别（轻隔离）、未覆盖的逃逸面（ctypes / 原生二进制）、执行脚本数与阻断策略。静态分析局限声明同样必含（建议用户如需行为验收另跑行为测试类技能）。

第 5 步：经验沉淀（统一模块 · 2026-10-24 启用）

每次报告交付与用户复核反馈后，加载 references/learnings.md 执行采集与分级判定；工具/环境类通用教训按该文件第七节桥接全局教训库。

分级判定速查