ECC 仓库提交前全面验证：解析 /verify 命令的六阶段质量门禁

导读

在 GitHub 精选项目 ECC（the agent harness performance optimization system）中，verify 命令是每次代码变更落地前必须触发的全量质量验证入口：它按固定顺序依次执行构建、类型检查、静态检查（Lint）、测试套件、console.log 审计与 Git 状态盘点，最后汇总为一份可供人工或 Agent 直接裁决的"是否可提交 PR"报告。读完本文，你将掌握该命令六阶段流水线的执行细则、结构化报告格式与 quick/full/pre-commit/pre-pr 四种参数模式的差异，并能从源码层理解它与仓库内 verification-loop skill、遗留 shim 命令之间的继承与调用关系。

一、Verify 命令在 ECC 中的定位

verify 命令的命令级定义记录于 docs/es/commands/verify.md（同步存在于 docs/zh-CN/commands/verify.md 等多语言目录），其职责概括为一句核心目标：对代码库当前状态执行穷尽式验证（ejecutar verificación exhaustiva sobre el estado actual del código base）。

在 ECC 的指令体系中，它并不是孤立的命令行工具，而是一条聚合了多套既有质量子系统的编排入口。从源码结构看，verify 至少有三种形态并存：

• skills/verification-loop/SKILL.md：技能层的主维护工作流，定义了 Phase 1～6 的具体命令与输出格式，是当前推荐的正式实现；
• legacy-command-shims/commands/verify.md：兼容层 shim，明确指出"maintained workflow 位于 skills/verification-loop/SKILL.md"，自身只保留 $ARGUMENTS 透传与委托说明，供仍习惯敲 /verify 的旧会话使用；
• .opencode/commands/verify.md：面向 Codex/Opencode 侧 Agent（agent: build）的命令化版本，补充了 TypeScript 覆盖率 80%+、函数小于 50 行、文件小于 800 行等更细粒度的清单项。

因此本文讲解的六阶段流程在三种形态中语义一致，命令细节以技能实现为准。

二、六阶段验证流水线（严格按序执行）

命令文档要求"精确按此顺序（en este orden）"执行，且任一步骤失败必须显式上报。其哲学是：越便宜的检查越靠前，越昂贵、越需要前面结果才有效的检查越靠后，避免在构建都失败的情况下浪费时间跑完整测试套件。

1. 构建验证（Verificación de Build）——失败即 STOP

对当前项目执行构建命令。技能实现中给出了两种等价形式：

npm run build 2>&1 | tail -20
# OR
pnpm build 2>&1 | tail -20

关键规则：构建失败时，报告错误并立即停止（DETENER），不允许带着失败的构建继续后续阶段。这是整个流水线唯一的硬性阻断点——后续的类型、测试阶段都无法在产物不完整时给出有意义的结果。

2. 类型检查（Verificación de Tipos）

执行 TypeScript/类型检查器，并以 archivo:línea（文件:行号）的格式逐条上报所有错误。技能层按语言分支给出实际命令：

# TypeScript 项目（不联网安装，直接使用本地 tsc）
set -o pipefail
npx --no-install tsc --noEmit 2>&1 | head -30

# Python 项目
pyright . 2>&1 | head -30

注意 --no-install 与 set -o pipefail 的配合：前者保证使用仓库已锁定的类型检查器版本、避免隐性升级，后者确保 tsc 的非零退出码在管道中被正确保留，防止类型错误被 head 吞掉而误报通过。

3. 静态检查 Lint（Verificación de Lint）

运行 linter，区分上报 warning 与 error：

# JavaScript/TypeScript
npm run lint 2>&1 | head -30

# Python
ruff check . 2>&1 | head -30

lint 结果不阻断流程（无 STOP 要求），但必须完整计入最终报告的问题计数。若需要对齐仓库自带的格式化门禁，可参考 commands/quality-gate.md：该门禁以 post:quality-gate PostToolUse hook 形式运行（scripts/hooks/quality-gate.js），按文件类型分别调用 Biome/Prettier（JS/TS/JSON/MD）、gofmt（Go）、ruff format（Python），并支持 ECC_QUALITY_GATE_FIX=true 自动修复与 ECC_QUALITY_GATE_STRICT=true 严格模式；其文档明确说明 lint 与类型检查不属于该门禁，请交给 verification-loop 技能或语言验证技能——这正是 verify 命令的职责边界所在。

4. 测试套件（Suite de Pruebas）

运行全部测试，报告三组数字：通过数/失败数（pasadas/fallidas）与覆盖率百分比。技能实现给出了带覆盖率的运行方式：

npm run test -- --coverage 2>&1 | tail -50

并约定覆盖率目标为 80% 下限。输出需报告：测试总数 X、通过 X、失败 X、覆盖率 X%。

覆盖率不达标时的后续动作可衔接 commands/test-coverage.md：它按测试框架提供检测命令映射（npx jest --coverage --coverageReporters=json-summary、npx vitest run --coverage、pytest --cov=src --cov-report=json、cargo llvm-cov --json、go test -coverprofile=coverage.out ./... 等），并把低于 80% 的文件按缺口优先级补测：happy path → 错误处理 → 边界值 → 分支覆盖，最终输出 Before/After 覆盖率对照表。

5. console.log 审计（Auditoría de console.log）

在源码中搜索 console.log 并逐条上报位置。技能层的搜索模式如下：

grep -rn "console.log" --include="*.ts" --include="*.tsx" src/ 2>/dev/null | head -10

其意图是捕捉遗留的调试输出——它们一旦进入生产路径既污染日志又泄露中间状态。从仓库自身的命令族（如 commands/code-review.md、commands/sessions.md）也能观察到 ECC 对日志与输出纪律的同等关注；.opencode 侧的实现更将 "No console.log statements" 直接列为代码质量复选框之一。

6. Git 状态盘点（Estado de Git）

展示自上次 commit 以来的未提交变更与已修改文件清单：

git diff --stat
git diff HEAD~1 --name-only

技能层进一步要求：对每个变更文件做 diff 复核，重点排查非预期改动（unintended changes）、缺失的错误处理、潜在边界条件三类问题。

三、结构化验证报告格式

全部六阶段跑完后，命令要求输出一份可被一眼裁决的摘要报告（reporte de verificación resumido）。原文规定的模板为：

VERIFICACIÓN: [PASÓ/FALLÓ]

Build:    [OK/FALLÓ]
Tipos:    [OK/X errores]
Lint:     [OK/X problemas]
Pruebas:  [X/Y pasaron, Z% cobertura]
Secretos: [OK/X encontrados]
Logs:     [OK/X console.log]

Listo para PR: [SÍ/NO]

值得注意的两点设计：

1. 报告模板中比六阶段多出一行 Secretos（密钥/机密扫描）——它对应技能实现中的 Phase 5 Security Scan（如 grep -rn "sk-" 与 grep -rn "api_key"），说明"六阶段"是命令层的最小可见顺序，安全扫描在技能层被显式地内嵌在 console.log 审计之前执行；
2. 最终裁决收敛为二值：所有阶段汇总为 Listo para PR: SÍ/NO（是否可提交 PR）。技能层的同构模板使用 Overall: [READY/NOT READY] for PR，.opencode 版本则为每一项给出 PASS/FAIL 表格并附 Action Items——即所有问题的修复清单。

命令文档同时要求：若存在任何关键问题（problema crítico），必须列出并附带修复建议（sugerencias de corrección），而非只给失败标记。

四、四种参数模式（$ARGUMENTS）

命令通过 $ARGUMENTS 接收执行深度，文档定义四种模式：

参数	含义	执行范围
quick	仅构建 + 类型检查	最快反馈，适合开发中快速自检
full	全部验证（默认值）	六阶段全量执行
pre-commit	与提交相关的验证	提交前子集
pre-pr	安全扫描 + 全部验证	在 full 基础上叠加密钥/漏洞扫描

策略逻辑清晰：日常高频使用 quick 获得秒级反馈；提交前用 pre-commit 过滤脏提交；提 PR 前必须上 pre-pr 全量档。legacy shim 明确委托"为请求的模式选择正确的验证深度（Choose the right verification depth for the user's requested mode）"，可见模式的取舍实际由技能在运行时决定。

五、与仓库验证体系的配合关系

将 verify 放入 ECC 的整体质量闭环中，可得到如下分工图景：

• hook 层：hooks/hooks.json 及 codex-hooks.json 中注册的 PostToolUse hooks 在每次工具调用后即时捕获问题（如 commands/quality-gate.md 所述的 post-edit-format 会在编辑后自动执行 biome check --write）；
• verify 层：本命令提供的是跨越整个会话/整个变更集的深度复核——技能文档的结语对此有明确定位："This skill complements PostToolUse hooks but provides deeper verification. Hooks catch issues immediately; this skill provides comprehensive review."（hooks 即时拦截，verify 全面审查）；
• 持续模式：技能层还建议长会话中每 15 分钟或完成大改动后运行一次验证，并把检查点内嵌到"完成每个函数/组件、切换任务前"的思维循环中。

六、实践建议与落地要点

把 verify 接入你自己的开发流时，可以遵循以下要点（均可在当前仓库内找到对应依据）：

1. 严守顺序、失败即停：构建失败不进入类型阶段；报告必须带 archivo:línea 级别定位，便于直接跳转修复；
2. 让报告机器可读：直接采用第三节的摘要模板，把 Secretos/Logs 计数纳入 PR 就绪裁决，避免人肉翻找日志；
3. 分场景选档：日常 quick，本地提交前 pre-commit，推送 PR 前 pre-pr（补全安全扫描）；
4. 衔接已有工具而非重复造轮子：覆盖率缺口交给 commands/test-coverage.md 的补测流程，格式化问题交给 scripts/hooks/quality-gate.js 门禁，verify 只做总装与裁决；
5. 以旧命令形态触发新技能：即便你的会话仍通过 /verify 进入，legacy shim（legacy-command-shims/commands/verify.md）也会把请求委托给 verification-loop 技能执行，不必担心新旧入口语义漂移。

综上，verify 是 ECC 对"提交前到底该检查什么"这一工程问题的标准化回答：它把构建、类型、lint、测试、日志与密钥审计、diff 复核六道工序固化为一条可重复、可报告、可裁决的流水线，是每次安全提交 PR 前最后一道也是最重要的一道闸门。