企业官网建设流程全解析

• CLI
• AI 技能

本文以tests/cli_e2e/demo/coverage.md为核心骨架，系统讲解 lark-cli（Lark/飞书官方 CLI）端到端测试体系中"每域一覆盖率文件"的维护规范：Metrics 指标口径、Summary 工作流摘要、Command Table 命令表格、Notes 注意事项，以及覆盖率分母如何从真实lark-cli --help输出重算、哪些执行路径不该计入覆盖、被阻塞命令如何记录原因。读完你可以为任意业务域（如task、docs）编写或维护一份既机械又可信的coverage.md。

一、coverage.md 在 lark-cli E2E 体系中的定位

lark-cli 的端到端测试模块位于 tests/cli_e2e，其使命是从用户视角验证真实 CLI 工作流：编译出二进制、逐条执行命令、捕捉单元测试发现不了的回归。该目录下每个业务域（application/、task/、docs/、im/、drive/等）都拥有一份独立的coverage.md，用来回答三个问题：

1. 本域共有多少个叶子命令（可执行动作的命令，无下级子命令）；
2. 其中多少被 E2E 测试用断言真正覆盖；
3. 未覆盖的每条命令为什么未覆盖（缺少真实用户 fixture、清理专用执行、环境不稳等）。

tests/cli_e2e/demo/coverage.md就是这份文件的示范模板：目录本身只含文档和参考用例，没有真实的lark-cli demo命令树，因此它展示的是"即使目录只做文档用途、背后没有真实命令树时，如何维护一份每域覆盖率文件"的形态。正如文件头部反复强调的：demo 是参考素材（reference material），不计入正式的 CLI E2E 覆盖统计，lark-cli demo --help不存在，因而该文件无法从实时域帮助输出重算。

真实域（如 tests/cli_e2e/task/coverage.md、tests/cli_e2e/docs/coverage.md）则展示了这套模板在生产中的完整样貌。

二、Metrics：覆盖率指标的口径

模板Metrics一节给出了三个数字，这是每份 coverage.md 都必须具备的最小指标集：

分母如何确定：只数叶子命令

按 tests/cli_e2e/cli-e2e-testcase-writer/SKILL.md 中的硬性规则：

• 叶子命令= 执行动作、没有进一步子命令的命令；
• 若lark-cli <domain> <group> --help没有列出子命令，则该<group>本身就是叶子；
• task +create计 1 个叶子，task tasks get计 1 个叶子；
• 不计算参数组合（+create带summary和带due仍是同一个命令）；
• 复用tests/cli_e2e/{domain}/下已有覆盖，不计入tests/cli_e2e/demo/。

探索实时 CLI 的标准命令序列为：

lark-cli --help lark-cli <domain> --help lark-cli <domain> +<shortcut> -h lark-cli <domain> <group> --help lark-cli <domain> <group> <method> -h lark-cli schema <domain>.<group>.<method>

demo 模板特意标注"在真实域中，应从实时lark-cli --help探索重算分母，而不是照抄本文件"，正是因为 demo 的数字（8/3/37.5%）纯属示意、不可复用。

三、Summary：如何用一句话讲清一个工作流

模板Summary部分的要点是：每个Test...一条要点，讲清证明链路（proof surface），而不是罗列测试代码。以 demo 的TestDemo_TaskLifecycle为例，它被拆成三个要点：

• create：执行task +create并携带summary、description，捕获返回的taskGUID，并在父测试注册清理钩子；
• update：执行task +update --task-id <guid>，同时变更summary与description；
• get：对同一任务执行task tasks get，断言持久化的guid、更新后的summary与description。

这段摘要与参考用例 tests/cli_e2e/demo/task_lifecycle_test.go 一一对应：create as bot子测试用gjson.Get(result.Stdout, "data.guid")取出任务 GUID，update as bot与get as bot分别完成写入与读回校验，最终通过assert.Equal比对 GUID、summary、description 三处字段。

真实的task域摘要则展示了"多工作流 + 阻塞点"的写法，例如TestTask_StatusWorkflow证明+complete与+reopen让status在done/todo间翻转、completed_at先置后清；TestTask_GetMyTasksDryRun则只做--dry-run请求形状校验，不调用真实 API。

清理路径与阻塞点的诚实记录

模板明确给出了两条重要的"诚实度"约定，真实域同样遵守：

1. 清理专用执行不计覆盖：task tasks delete执行在parentT.Cleanup中，但模板故意将其保持为未覆盖，因为"工作流断言必须与清理机制保持区分"——删除只是清理手段，不是被断言证明的测试面。
2. Demo 缺口标注：task +complete、task +reopen、task +assign、task +get-my-tasks在最小模板中故意留作未覆盖示例；其中+assign是"用户身份敏感命令"的典型（需要真实用户 fixture），+get-my-tasks是"当前用户依赖命令"的典型（bot-only 环境常不可用）。

四、Command Table：命令表格的六列规范

模板给出了统一的命令表头，这是每个域 coverage.md 都必须保持的列结构：

• Status：✓覆盖 /✕未覆盖；
• Cmd：命令路径，如task +create（shortcut）或task tasks get（api）；
• Type：shortcut（快捷命令）或api（API 直调命令）二选一；
• Testcase：以go test -run友好的形式写出用例位置，格式为文件_test.go::TestXxx/子测试；
• Key parameter shapes：关键参数形态，如--task-id、summary+description、task_guid in --params；
• Notes / uncovered reason：覆盖要点或未覆盖原因。

demo 表格完整继承如下（八行全部保留）：

对比真实域（task/coverage.md），其 29 个叶子命令中 15 个被覆盖，未覆盖行给出了精确到 fixture 层面的原因，例如task +assign："requires real assignee open_id fixtures; shortcut defaults to--as user"；task tasks list："UAT did not return the workflow-created user task deterministically in list views"——宁可留白也不把 flaky 结果计入覆盖。

五、Notes：注意事项与"可复算"原则

模板Notes一节约束了 coverage.md 的维护方式，包含三条铁律：

1. 真实域必须重算分母：从实时lark-cli --help探索得出，而不是复制 demo 文件；
2. 替换 demo 行：用该域真实命令清单替换示例行；
3. 保持未覆盖命令为未勾选：复用t.Skip(...)的原因作为未覆盖原因，避免测试跳过原因与 coverage 记录不一致。

此外，SKILL.md 还补充了两条覆盖计数的边界规则：

• 仅在parentT.Cleanup中执行的命令不计为已覆盖（唯一例外：在同一工作流中创建资源后紧接的delete）；
• 一条命令只有在测试用例断言了返回字段或持久化状态时才视为已覆盖——仅断言退出码不算。这一口径在 tests/cli_e2e/core.go 的AssertExitCode与AssertStdoutStatus设计中体现为：所有用例统一先断言退出码与ok/code状态键，再断言字段路径（gjson提取），二者缺一不可。

六、配套机制：demo 参考用例与 E2E 测试框架

demo 目录只有两个文件，构成"覆盖率文档 + 参考测试"的最小组合：

• coverage.md：本文讲解的模板；
• task_lifecycle_test.go：最小任务生命周期参考用例，展示标准的clie2e.RunCmd(ctx, clie2e.Request{...})写法。

从参考用例可以看到 E2E 测试的基本形态：Request结构体把命令参数拆成Args（命令路径与普通 flag）、Params（URL/路径参数，转为--params '<json>'）、Data（请求体，转为--data '<json>'），以及DefaultAs（bot/user）、Yes（高风险写命令确认）等字段。BuildArgs与ResolveBinaryPath分别负责参数组装与二进制查找（LARK_CLI_BIN环境变量 → 项目根目录./lark-cli→PATH）。

对于真实域的测试编写，仓库提供了专门的本地 Skill tests/cli_e2e/cli-e2e-testcase-writer/SKILL.md，安装方式为：

npx skills add ./tests/cli_e2e/cli-e2e-testcase-writer

随后在 tests/cli_e2e/README.md 列出的工作流下操作：先make build，再运行go test ./tests/cli_e2e/... -count=1。

七、为真实域落地 coverage.md 的检查清单

综合模板、SKILL.md 与真实域样例，为某个新域编写或更新coverage.md时按以下清单执行：

1. 探索：对域执行完整的--help/-h/schema命令序列，列出全部叶子命令（不数参数组合）；
2. 重算分母：只统计真实lark-cli --help输出中的叶子命令数，勿照抄 demo；
3. 写工作流用例：一个顶层测试配多个t.Run子步骤，create 后紧跟 read-after-write 断言；清理钩子注册在parentT.Cleanup上以在子测试失败时仍能执行；
4. 标注命令类型：shortcut与api分行列出，全部命令放在同一张表，不拆成已覆盖/未覆盖两节；
5. 诚实记录未覆盖：清理专用执行、缺少真实用户 fixture、UAT 不稳定等一律保持✕并写明原因，复用t.Skip(...)的理由；
6. 保持机械与简洁：Metrics/Summary/Command Table 三节齐备，摘要每个Test...一条，突出 keyt.Run(...)证明点与主要阻塞点。

遵循这套口径产出的覆盖率文件，既能让人类维护者一眼看出"哪些命令可证明、哪些被环境阻塞"，也能让 AI Agent 在扩展测试时快速对齐当前域的覆盖边界，避免重复工作或虚构覆盖。

• CLI
• AI 技能