ECC 质量门Quality Gate实战指南从 PostToolUse 钩子到 on-demand 格式检查流水线【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECCECCEverything Claude Code作为 Agent harness 性能优化系统在每次文件编辑后都会通过钩子体系自动执行轻量级质量检查而quality-gate正是这一机制面向操作员的按需入口。本文基于 commands/quality-gate.md对应日文版 docs/ja-JP/commands/quality-gate.md展开结合 scripts/hooks/quality-gate.js 源码与 tests/hooks/quality-gate.test.js 测试完整讲解命令用法、钩子接线方式、格式化器检测逻辑与各语言工具链行为帮助读者既能手动触发检查也能理解其底层原理并自行扩展。命令概览与核心用途quality-gate是一个按需on-demand质量流水线命令它镜像了 ECC 中同名 PostToolUse 钩子的行为但改由操作员显式调用适用于编辑完成后想立即验证格式、而不是等待下一次钩子触发的场景。默认目标当前目录.--fix在已配置的位置允许自动格式化 / 修复--strict在支持的位置警告即失败将格式化失败视为门禁失败命令镜像的钩子即 scripts/hooks/quality-gate.js。需要特别说明的是该钩子的真实入口是 stdin JSON 而非 CLI 参数脚本从钩子输入的tool_input.file_path读取目标文件行为开关通过环境变量控制这一点在钩子视角章节详述。流水线执行步骤命令按照以下流水线对目标执行检查检测目标的语言 / 工具依据文件扩展名.ts/.tsx/.js/.jsx/.json/.md、.go、.py选择对应的格式化器并探测项目根与已配置的格式化工具运行格式化检查对目标文件执行格式化器的 check 模式或 fix 模式在可用时运行 lint / 类型检查需要说明的是lint 与类型检查并不属于本门禁的范畴见下文能力边界此步骤在实际实现中由验证类 Skill 承担输出简洁的修复清单报告格式化器发现的问题与具体的整改步骤。能力边界什么不在这个门禁里从 quality-gate.js 的实现看该门禁只做单文件格式化检查不包含 lint 与类型检查。源码注释与命令文档均明确如果需要 lint / type / test 的完整流水线应使用 skills/verification-loop/SKILL.md 或各语言的验证类 Skill如 python-review、go-review、rust-review 等。这意味着quality-gate的价值在于快速、低噪声、只聚焦格式一致性而不是替代完整的 CI 门禁。钩子视角quality-gate 在 ECC 中如何被触发PostToolUse 分发器接线命令文档提到Hook wiring enters through the async PostToolUse dispatcher inhooks/hooks.json。在 hooks/hooks.json 中PostToolUse阶段注册了同步与异步两个分发入口post:dispatcher:sync与post:dispatcher:async它们都加载 scripts/hooks/posttooluse-dispatcher.js。分发器内部维护了一个钩子注册表其中就包含{ id: post:quality-gate, matcher: Edit|Write|MultiEdit, profiles: standard,strict, script: scripts/hooks/quality-gate.js, run: runQualityGate }可见post:quality-gate钩子匹配Edit / Write / MultiEdit三类工具调用即任何文件写入后都会经过它归属于standard与strict两个 profileminimalprofile 不执行通过run直接内联调用quality-gate.js导出的run()函数避免子进程开销。与 post-edit-format 的分工JS/TS 文件在 ECC 中实际上有两条格式化路径scripts/hooks/post-edit-format.js在每次 Edit 后自动对 JS/TS 文件执行格式化Biome 使用check --write一次完成 format lintPrettier 使用--writescripts/hooks/quality-gate.js当项目配置了 Biome 时对.ts/.tsx/.js/.jsx直接跳过因为post-edit-format已经用biome check --write处理过避免重复调用但.json与.md仍会走 quality-gate 的 Biome 检查。这种分工在quality-gate.js第 69-89 行的代码注释中有明确说明。手动运行向脚本输送钩子风格 JSON由于脚本本身不接受 CLI 参数手动检查单个文件的标准做法是构造钩子风格的 stdin JSON并在需要时先设置环境变量开关echo {tool_input:{file_path:src/example.ts}} \ | ECC_QUALITY_GATE_FIXtrue node scripts/hooks/quality-gate.jsECC_QUALITY_GATE_FIXtrue以修复模式运行对文件应用格式化修复而不是仅检查ECC_QUALITY_GATE_STRICTtrue以严格模式运行将格式化失败记为门禁失败向 stderr 输出[QualityGate] ... failed ...日志两者都不设置时默认只检查check-only且失败仅被静默忽略不阻塞。在命令文档/quality-gate [path|.] [--fix] [--strict]中如果传入了目标路径则应将该路径替换为 stdin JSON 中的tool_input.file_path后再执行例如echo {tool_input:{file_path:src/example.go}} \ | ECC_QUALITY_GATE_STRICTtrue node scripts/hooks/quality-gate.js环境变量开关的解析方式从源码看开关解析对大小写不敏感且严格匹配字符串trueconst fix String(process.env.ECC_QUALITY_GATE_FIX || ).toLowerCase() true; const strict String(process.env.ECC_QUALITY_GATE_STRICT || ).toLowerCase() true;即ECC_QUALITY_GATE_FIX1或ECC_QUALITY_GATE_FIXTRUE都不会生效只有字面量true有效。按文件类型的检查行为矩阵maybeRunQualityGate(filePath)依据扩展名分发到不同的工具链见 scripts/hooks/quality-gate.js扩展名工具检查模式默认修复模式FIXtrue备注.ts/.tsx/.js/.jsxBiome跳过跳过已由post-edit-format用biome check --write处理.json/.mdBiomebiome check filebiome check --write file项目配置了 Biome 时.ts/.tsx/.js/.jsx/.json/.mdPrettierprettier --check fileprettier --write file项目配置了 Prettier 时.gogofmtgofmt -l filegofmt -w filecheck 模式下 stdout 非空即视为未通过.pyruffruff format --check fileruff format file—其他扩展名—跳过no-op跳过工具不可用时同样静默跳过几个实现细节值得注意Go 的 check 模式gofmt -l会列出需要格式化的文件名因此 strict 模式下还要检查stdout是否非空有输出即未通过而不是只看退出码Python 的 ruffcheck 模式追加--checkfix 模式仅format不存在的文件maybeRunQualityGate开头fs.existsSync(filePath)不通过就直接返回 no-op未配置格式化器探测不到 Biome / Prettier 配置时直接跳过工具二进制缺失时resolveFormatterBin返回 null也跳过——即fail silently。格式化器探测与二进制解析quality-gate 复用 scripts/lib/resolve-formatter.js 提供的三个核心函数与post-edit-format共享同一套逻辑与进程内缓存projectRootCache/formatterCache/binCache避免重复文件系统查找。项目根发现findProjectRoot从filePath所在目录向上逐级查找直到命中任一项目根标记package.json、biome.json、biome.jsonc或任意 Prettier 配置文件。查找在到达用户主目录home之前停止以避免把~/.prettierrc之类的全局 dotfile 误判为项目根标记。找不到标记时回退到起始目录。格式化器探测detectFormatter探测优先级为存在biome.json或biome.jsonc→biomepackage.json中存在prettier键 →prettier存在任意 Prettier 配置文件.prettierrc、.prettierrc.json/.js/.cjs/.mjs/.yml/.yaml/.toml、prettier.config.js/.cjs/.mjs→prettier以上皆无 →null不执行任何检查。即Biome 优先于 Prettier只要项目同时声明了两者就使用 Biome。二进制解析resolveFormatterBin优先使用项目本地node_modules/.bin下的二进制避免 npx 每次解析包的开销这也是 post-edit-format.js 注释中提到的 200-500ms 节省来源若本地未安装则回退到包管理器执行命令npx/pnpm/yarn/bunx可通过CLAUDE_PACKAGE_MANAGER环境变量与项目配置调整此时会追加biomejs/biome或prettier作为前缀参数。Windows 平台下还会将npx等映射为对应的.cmdshim。严格模式strict与失败处理strict是本命令区分检查与门禁的关键维度非 strict 下格式化检查失败不产生任何输出、不阻塞流程只是静默返回这与fail silently的钩子设计哲学一致——钩子不应打断 Agent 的编辑节奏strict 下各工具的失败非零退出码、或 gofmt 的-l有输出会向stderr写入一行[QualityGate] Tool check failed for filePath日志作为门禁失败被记录。注意脚本本身不会改变进程退出码run()永远是输入原样透传pass-through这一点由 tests/hooks/quality-gate.test.js 系统性地验证见下节。源码级验证测试如何保证稳健性tests/hooks/quality-gate.test.js 覆盖了run()的健壮性契约可以手工运行验证node tests/hooks/quality-gate.test.js测试分组与断言要点有效 JSON 透传无论tool_input.file_path存在与否、是否有嵌套结构run()都原样返回输入无效 JSON 不崩溃非 JSON、残缺 JSON、尾部垃圾均原样返回文件不存在指向不存在文件的.js/.py/.go路径均安全 no-op空输入空字符串、纯空白字符串原样返回缺失 / 为 null 的 tool_input{}、tool_input: null、空file_path均被优雅处理存在文件但未配置格式化器真实临时文件 无格式化器配置时同样安全 no-op。这套测试明确了 quality-gate 的第一原则绝不因解析错误或环境缺失而崩溃永远透传输入——这是所有静默失败设计的基础保障。与其他命令 / Skill 的协作边界更深的验证需要 lint / type / test 全流程时转向 skills/verification-loop/SKILL.md其文档明确指出complements PostToolUse hooks but provides deeper verification典型流程如npm run lint 21 | head -30与类型错误报告或各语言的验证 Skill编辑期自动格式化JS/TS 的自动格式化由 scripts/hooks/post-edit-format.js 承担quality-gate 与其共享格式化器解析逻辑CI 质量门如需对提交做更全面的门禁例如校验变更范围与代码质量可参考epic-validate等命令的职责划分。小结ECC 的quality-gate是一个小而专的格式质量门禁对外它是操作员可按需触发的命令对内它是挂载在Edit|Write|MultiEdit后的post:quality-gate钩子。理解它的关键在于三件事入口是 stdin JSON 而非 CLI 参数、行为由ECC_QUALITY_GATE_FIX/ECC_QUALITY_GATE_STRICT两个环境变量驱动、失败默认静默。结合 scripts/lib/resolve-formatter.js 的共享探测逻辑与 tests/hooks/quality-gate.test.js 的透传契约你可以安全地把它接入自己的流水线或在其基础上扩展新的文件类型支持——扩展时请保持绝不崩溃、静默失败、输入透传的既有契约。【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考