surface-coverage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: surface-coverage

Đúc kết từ phiên Openship ↔ devops-agent ngày 01/10/2026 (GH#191).

/orca-onboard

chọn ra 18 flow, rồi sinh 19 bài học, và báo cáo như thể đã giải thích hết app. Bề mặt thật đọc từ code có 62 trang dashboard và 37 module API. Gần một nửa (servers, clusters, jobs, billing, members…) không có bài nào. Không có gì báo đỏ, vì không có gì đem danh sách đó so với sản phẩm. Một con số không phải độ phủ. Độ phủ là một phép diff với bề mặt thật.

总结自 2026-10-01 的 Openship ↔ devops-agent 会话（GH#191）。

/orca-onboard

选出 18 个 flow，随后生成 19 篇 lesson，并报告称已解释整个 app。然而，从 code 读取的真实表面包含 62 个 dashboard 页面和 37 个 API module。其中接近一半（servers、clusters、jobs、billing、members……）没有任何 lesson。没有任何内容报红，是因为根本没有将这份列表与产品进行比对。数字不等于覆盖率。覆盖率是与真实表面的一次 diff。

WHAT

Purpose và context

目的与上下文

Purpose: trước khi nói tài liệu, bài học, sơ đồ, test, bề mặt CLI/MCP hay graph onboarding "phủ" một sản phẩm, phải chứng minh bằng diff. Liệt kê bề mặt thật từ code. Có một sổ phủ (coverage ledger), trong đó mỗi mục bề mặt trỏ tới thứ giải thích nó, hoặc được loại trừ kèm lý do. Có một cổng (gate) đỏ khi xuất hiện mục mới chưa phủ.
Trigger:
- User hỏi "đã phủ hết chưa", "có đủ chưa", "tương ứng hết các chức năng trên dashboard chưa", "vét cạn", "không lọt chức năng", "sổ chức năng".
- Đang sinh bài học, flow hay docs cho một codebase (
```
/orca-onboard
```
  Phase 2,
```
/teach-me
```
  toàn hệ thống).
- Sắp báo một con số artefact ("19 bài", "18 flow", "CLI có 40 lệnh") như thể nó đã đủ.
Non-goals: không đo độ phủ dòng code của test (đó là coverage của test runner). Không tự sinh nội dung cho mục còn thiếu. Skill chỉ chỉ ra thiếu gì và cách lần code để lấp. Không thay schema
```
domain-graph.json
```
của
```
orca-onboard
```
.

目的： 在声称文档、lesson、图示、test、CLI/MCP 表面或 onboarding graph 已“覆盖”某个产品之前，必须通过 diff 证明。从 code 枚举真实表面。维护一份覆盖台账，其中每个表面条目都指向解释它的 artefact，或附带理由予以排除。设置一个红色门禁，一旦出现尚未覆盖的新条目就报错。
触发条件：
- 用户询问“是否已全部覆盖”“是否足够”“是否涵盖 dashboard 上的全部功能”“彻底排查”“不遗漏功能”“功能台账”。
- 正在为一个 codebase 生成 lesson、flow 或 docs（
```
/orca-onboard
```
  Phase 2、
```
/teach-me
```
  全系统）。
- 即将报告 artefact 数量（“19 篇 lesson”“18 个 flow”“CLI 有 40 条命令”）并暗示它已足够完整。
非目标： 不衡量 test 的代码行覆盖率（那是 test runner 的 coverage）。不自动为缺失条目生成内容。Skill 只指出缺少什么，以及如何追踪 code 来补齐。不替换
```
/orca-onboard
```
的
```
domain-graph.json
```
schema。

Mental model

心智模型

code ──scan (script, tất định)──▶ surface.json {commit, items: page:/x · api:/x · module:x · cli:x …}
artefact (flow · bài · doc · op) ──người/agent ghi──▶ coverage.json {commit, items: mục → by[] | exclude:"lý do"}
surface.json ⊖ coverage.json ──check──▶ "N/M mục được phủ, K loại trừ" + danh sách CHƯA PHỦ + lỗi (rc 1)

Cùng một hình dạng lỗi xuất hiện ở nhiều chỗ khác: "CLI phủ mọi tính năng" cho tới khi có một lời gọi UI không có op tương ứng, "docs phủ mọi endpoint", "test phủ mọi route".

code ──scan (script, tất định)──▶ surface.json {commit, items: page:/x · api:/x · module:x · cli:x …}
artefact (flow · bài · doc · op) ──người/agent ghi──▶ coverage.json {commit, items: mục → by[] | exclude:"lý do"}
surface.json ⊖ coverage.json ──check──▶ "N/M mục được phủ, K loại trừ" + danh sách CHƯA PHỦ + lỗi (rc 1)

同一种失败形态会出现在许多地方：“CLI 覆盖了所有功能”，直到发现某个 UI 调用没有对应的 op；“docs 覆盖了所有 endpoint”；“test 覆盖了所有 route”。

Input và output contract

输入与输出契约

	Field	Required?	Ý nghĩa
In	thư mục code của sản phẩm	có	nơi đọc bề mặt; nên là git repo để ghi commit
In	bộ artefact đang khẳng định là phủ	có	flow, bài học, trang docs, op CLI/MCP, test
In	glob thư mục module API / lệnh CLI	không	khi khung không phải file-based router
Out	`surface.json`	có	mọi mục bề mặt kèm file nguồn và commit lúc đọc
Out	`coverage.json`	có	mỗi mục → `by[]` (id artefact) hoặc `exclude` có lý do
Out	dòng báo cáo `N/M mục bề mặt được phủ, K loại trừ` + danh sách chưa phủ	có	thay mọi con số artefact trơn
Out	một test hoặc gate trong dự án chạy lại `check`	có	đỏ khi bề mặt mọc thêm mục

	字段	必填？	含义
输入	产品代码目录	是	读取表面的位置；最好是 git repo，以便记录 commit
输入	当前声称已覆盖的 artefact 集合	是	flow、lesson、docs 页面、CLI/MCP op、test
输入	API module 目录／CLI 命令的 glob	否	当框架不是 file-based router 时使用
输出	`surface.json`	是	所有表面条目，以及来源文件和读取时的 commit
输出	`coverage.json`	是	每个条目 → `by[]` （artefact id）或附带理由的 `exclude`
输出	报告行 `N/M 个表面条目已覆盖，K 个排除项` + 未覆盖列表	是	取代所有只有 artefact 数量的报告
输出	项目中可重新运行 `check` 的 test 或 gate	是	表面新增条目时报红

Rules và capabilities

规则与能力

RULE-01 (MUST): bề mặt lấy từ CODE bằng script tất định. Không lấy từ trí nhớ, README hay bản tóm tắt của model. Ghi commit lúc đọc.
RULE-02 (MUST): mọi mục bề mặt có đúng một dòng sổ:
```
by[]
```
không rỗng, hoặc
```
exclude
```
kèm lý do người đọc kiểm lại được (vd "chuyển hướng sang /servers", "callback đóng cửa sổ OAuth"). Loại trừ không lý do tính là lỗi.
RULE-03 (MUST): báo độ phủ dạng "N/M mục bề mặt được phủ, K loại trừ" và nêu nguồn bề mặt (script nào, commit nào). Chưa chạy diff thì nói "chưa đối chiếu với code", không nói "đủ rồi".
RULE-04 (MUST): bước flow có
```
file:line
```
phải được kiểm máy trước khi gộp: file tồn tại, dòng nằm trong file, ký hiệu được nhắc xuất hiện gần dòng đó. Sai thì từ chối gộp. Một
```
file:line
```
sai trong sơ đồ dạy học còn tệ hơn là thiếu.
RULE-05 (MUST): cổng đỏ khi có: mục không có dòng sổ, dòng sổ trỏ mục đã mất, loại trừ không lý do, sổ dựng ở commit khác bề mặt.
RULE-06 (SHOULD): lấp chỗ trống bằng cách lần code (trang → route API → controller → service → adapter, mỗi bước
```
file:line
```
), không đoán. Nhiều mục thì chia theo mảng cho nhiều agent song song, mỗi agent nhận đúng danh sách mục của mình và schema đầu ra.
Capabilities: đọc cây thư mục và git của sản phẩm; chạy script cục bộ; ghi 2 file JSON; thêm 1 test vào dự án.

RULE-01（MUST）：表面必须通过确定性脚本从 CODE 中获取。不得来自记忆、README 或 model 的摘要。记录读取时的 commit。
RULE-02（MUST）：每个表面条目在台账中必须恰好有一行：
```
by[]
```
非空，或
```
exclude
```
附带读者可复核的理由（例如“重定向至 /servers”“OAuth 窗口关闭回调”）。没有理由的排除项视为错误。
RULE-03（MUST）：必须以 “N/M 个表面条目已覆盖，K 个排除项” 的形式报告覆盖率，并注明表面来源（哪个脚本、哪个 commit）。尚未运行 diff 时，应说“尚未与 code 对账”，而不能说“已经足够”。
RULE-04（MUST）：包含
```
file:line
```
的 flow 步骤在合并前必须经过机器校验：文件存在、行号位于文件范围内、被提及的符号出现在该行附近。任何错误都拒绝合并。教学图示中的错误
```
file:line
```
比缺少它更糟糕。
RULE-05（MUST）：出现以下情况时门禁报红：条目没有台账记录、台账指向已经消失的条目、排除项没有理由、台账基于与表面不同的 commit 构建。
RULE-06（SHOULD）：通过追踪 code 补齐空白（页面 → API route → controller → service → adapter，每一步都带
```
file:line
```
），不得猜测。条目较多时，按分片拆分给多个 agent 并行处理，每个 agent 只接收自己的条目列表和输出 schema。
能力：读取产品目录树和 git；运行本地脚本；写入 2 个 JSON 文件；向项目添加 1 个 test。

Failure boundaries

失败边界

Khung không có router theo file (Express đăng ký route bằng code, Go, Rails…) →
```
scan
```
chỉ ra được
```
module:
```
từ
```
--modules
```
. Phần route phải viết script riêng cho khung đó (vd grep
```
router.get(
```
/
```
app.post(
```
) rồi gộp vào
```
surface.json
```
. Khai rõ "bề mặt route lấy bằng script riêng".
Không phải git repo →
```
commit: null
```
, kiểm lệch commit bị bỏ qua. Báo "không ghim được commit".
Bề mặt quá lớn (hàng trăm mục) → partial hợp lệ nếu báo đúng
```
N/M
```
và liệt kê phần chưa phủ. Không được làm tròn thành "đủ".
Không đọc được code (chỉ có site đang chạy) → dừng skill này; dùng
```
ui-kit-from-code
```
W01b (khám phá theo link) để lấy bề mặt UI.

框架没有 file-based router（Express 以代码注册 route、Go、Rails……）→
```
scan
```
只能通过
```
--modules
```
枚举
```
module:
```
。route 部分必须为该框架编写专用脚本（例如 grep
```
router.get(
```
/
```
app.post(
```
），然后合并到
```
surface.json
```
。必须明确说明“route 表面通过专用脚本获取”。
不是 git repo →
```
commit: null
```
，跳过 commit 不一致检查。报告“无法固定 commit”。
表面过大（数百个条目）→ 只要正确报告
```
N/M
```
并列出未覆盖部分，partial 就是可接受结果。不得取整后宣称“已经完整”。
无法读取 code（只有运行中的站点）→ 停止使用此 skill；改用
```
ui-kit-from-code
```
W01b（按链接探索）获取 UI 表面。

HOW

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	thư mục code	`python3 ~/.claude/harness/fdk/tools/surface-coverage.py scan <root> [--modules 'apps/api/src/modules/*'] --out surface.json` (trong repo framework: `fdk/tools/surface-coverage.py` )	`surface.json` + dòng `bề mặt M mục @commit · page … · api … · module …`	M = 0 → kiểm lại `<root>` / `--modules` , khung không file-based → nhánh B01
W02	judgment	`surface.json` + artefact hiện có	ghi `coverage.json` : mỗi mục → id artefact giải thích nó, hoặc `exclude` kèm lý do	sổ phủ	—
W03	deterministic	2 file JSON (+ `domain-graph.json` )	`surface-coverage.py check surface.json coverage.json [--flows domain-graph.json --root <root>]`	rc 0 + `N/M mục …`	rc 1 → W04
W04	judgment	danh sách CHƯA PHỦ + LỖI	lần code từng mục chưa phủ thành flow/bài mới (RULE-06); sửa `file:line` sai	artefact mới + sổ cập nhật	quay W03, tối đa 3 vòng rồi báo partial
W05	effect	sổ xanh	thêm test hoặc bước CI trong dự án chạy lại W01 + W03 trước mỗi lần sinh lại artefact	gate	dự án không có test runner → ghi lệnh vào README của artefact
W06	judgment	kết quả	báo theo RULE-03: `N/M` , K loại trừ kèm lý do, nguồn bề mặt @commit, danh sách còn thiếu (nếu partial)	báo cáo	—

步骤	类型	输入	操作	输出／退出	失败／下一步
W01	确定性	代码目录	`python3 ~/.claude/harness/fdk/tools/surface-coverage.py scan <root> [--modules 'apps/api/src/modules/*'] --out surface.json` （框架 repo 内： `fdk/tools/surface-coverage.py` ）	`surface.json` + `表面 M 个条目 @commit · page … · api … · module …`	M = 0 → 检查 `<root>` / `--modules` ；框架不是 file-based → 分支 B01
W02	判断型	`surface.json` + 现有 artefact	写入 `coverage.json` ：每个条目 → 解释它的 artefact id，或附带理由的 `exclude`	覆盖台账	—
W03	确定性	2 个 JSON 文件（+ `domain-graph.json` ）	`surface-coverage.py check surface.json coverage.json [--flows domain-graph.json --root <root>]`	rc 0 + `N/M 个条目……`	rc 1 → W04
W04	判断型	未覆盖列表 + 错误	逐个追踪未覆盖条目的 code，生成 flow/lesson（RULE-06）；修复错误的 `file:line`	新 artefact + 更新后的台账	返回 W03，最多 3 轮；之后报告 partial
W05	执行效果	绿色台账	在项目中添加 test 或 CI 步骤，使每次重新生成 artefact 前都运行 W01 + W03	gate	项目没有 test runner → 将命令写入 artefact 的 README
W06	判断型	结果	按 RULE-03 报告： `N/M` 、带理由的 K 个排除项、表面来源 @commit，以及缺失列表（若为 partial）	报告	—

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	khung không có router theo file	viết script nhỏ liệt kê route của khung đó, ghi cùng định dạng `items` vào `surface.json`	khung file-based → skip	W02
B02	conditional_required	artefact là sổ chức năng CLI/MCP của chính app	bề mặt = route + lời gọi `/api` từ UI + tham số route; mỗi mục phải là một op của registry (mẫu `src/surface/manifest.ts` + `tests/manifest.test.ts` ở devops-agent)	—	W03

ID	类型	条件	行为	跳过／失败	汇合点
B01	conditional_required	框架没有 file-based router	编写小型脚本枚举该框架的 route，并将相同 `items` 格式写入 `surface.json`	file-based → 跳过	W02
B02	conditional_required	artefact 是应用自身的 CLI/MCP 功能台账	表面 = route + UI 发出的 `/api` 调用 + route 参数；每个条目必须是 registry 中的一个 op（devops-agent 中的示例： `src/surface/manifest.ts` + `tests/manifest.test.ts` ）	—	W03

Validation và stopping

校验与停止条件

Máy kiểm:

surface-coverage.py check

rc 0. Test của chính tool:

python3 -m pytest -q harness/tests/test_surface_coverage.py

. Thêm một trang giả vào fixture thì test phải đỏ với

CHƯA PHỦ page:/…

. Người kiểm: lý do của từng

exclude

. Tối đa 3 vòng W03↔W04, sau đó báo partial kèm danh sách còn thiếu.

机器校验：

surface-coverage.py check

返回 rc 0。工具自身的 test：

python3 -m pytest -q harness/tests/test_surface_coverage.py

。向 fixture 添加一个虚假页面后，test 必须以

未覆盖 page:/…

报红。人工审核：每个

exclude

的理由。W03↔W04 最多运行 3 轮，随后报告 partial 并附上缺失列表。

Examples

示例

Positive: Openship @4fefe217.
```
scan
```
ra 62 trang + 37 module. Sổ ban đầu chỉ từ 18 flow →
```
check
```
báo khoảng nửa bề mặt CHƯA PHỦ. 6 agent lần code theo mảng ra 81 flow mới, mỗi bước có
```
file:line
```
. Kiểm máy từng bước rồi gộp →
```
99 flow / 21 domain
```
,
```
check
```
báo
```
62/62 trang, 37/37 module
```
và có test
```
lessons-coverage
```
gác.
Boundary/failure: user hỏi "19 bài đủ chưa" nhưng chưa có
```
surface.json
```
→ câu trả lời đúng là "chưa đối chiếu với code", rồi chạy W01. Không được trả lời "đủ rồi" dựa trên số bài.

正面示例： Openship @4fefe217。
```
scan
```
枚举出 62 个页面 + 37 个 module。初始台账只来自 18 个 flow →
```
check
```
报告约一半表面尚未覆盖。6 个 agent 按分片追踪 code，产出 81 个新 flow，每个步骤都带
```
file:line
```
。逐个步骤经机器校验后合并 →
```
99 flow / 21 domain
```
，
```
check
```
报告
```
62/62 页面, 37/37 module
```
，并由
```
lessons-coverage
```
test 把关。
边界／失败示例： 用户问“19 篇 lesson 是否足够”，但还没有
```
surface.json
```
→ 正确回答是“尚未与 code 对账”，然后运行 W01。不得仅根据 lesson 数量回答“已经足够”。