用途:在声称文档、课程、流程图、测试或 CLI/MCP 表面已“覆盖”某产品之前,用与代码真实表面的 diff 来证明,而不是用产物数量(如“19 篇”“18 个流程”)充当覆盖率。
主要能力:用脚本确定性地从代码中扫描出表面(page、api、module、cli 等),生成 surface.json(含读取时的 commit);维护覆盖率台账 coverage.json,每个表面项必须指向解释它的产物 id,或带可核查理由的 exclude;用 check 命令输出“N/M 项已覆盖,K 项排除”并列出未覆盖项;出现未登记项、台账指向已消失项、无理由排除、台账与表面 commit 不一致时报错。
使用方式:先运行扫描 python3 ~/.claude/harness/fdk/tools/surface-coverage.py scan <root> [--modules 'apps/api/src/modules/*'] --out surface.json(框架仓库内为 fdk/tools/surface-coverage.py),再编写 coverage.json,然后运行 surface-coverage.py check surface.json coverage.json [--flows domain-graph.json --root <root>]。机器校验 rc 0;自身测试用 python3 -m pytest -q harness/tests/test_surface_coverage.py。最多 W03↔W04 三轮,之后报告 partial 并列出未覆盖项。
适用场景:生成课程/流程/文档时(如 /orca-onboard Phase 2、/teach-me 全系统),或用户问“是否覆盖全了”“有没有漏功能”时。
限制:不衡量测试的行覆盖(那是测试运行器的 coverage);不自动生成缺失内容,只指出缺什么并说明如何沿代码补齐;不替换 orca-onboard 的 domain-graph.json schema。非文件式路由框架(Express、Go、Rails 等)扫描只能给出 module,route 需自行写脚本,且须声明“route 表面由单独脚本获取”。非 git 仓库时 commit 为 null 并提示无法固定 commit。表面过大(数百项)时允许 partial,但必须如实报告 N/M 与未覆盖列表,不得四舍五入成“足够”。若只能访问运行中的站点、读不到代码,则停止本技能,改用 ui-kit-from-code W01b。