ECC Harness Audit用确定性评分卡审计与优化 Agent 工具链的完整指南【免费下载链接】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本指南以 docs/ja-JP/commands/harness-audit.md及其英文权威版本 commands/harness-audit.md为核心深入讲解 ECCEverything Claude Code仓库中/harness-audit命令的设计原理、使用方式与落地实践。读完本文你将掌握如何对 ECC 仓库自身或任意使用 ECC 的消费方项目执行一次可复现的确定性工具链harness审计、读懂优先级评分卡并依据top_actions与配套技能逐步提升工具覆盖、上下文效率、质量门禁、记忆持久化、评估覆盖、安全护栏与成本效率。命令是什么/harness-audit是 ECC 提供的一条命令式指令slash command其职责是对仓库的工具链harness配置执行一次确定性的审计并返回一份带优先级的评分卡。这里的“harness”指的是围绕 Agent 运行的一组工程化表面hooks钩子、skills技能、commands命令、agents角色定义、记忆持久化、安全护栏、测试与评估体系等。与常见的“让大模型凭感觉打分”不同该命令强调决定性deterministic评分完全来自显式的文件/规则检查对同一个 commit 可以稳定复现。它既是 ECC 自检的入口package.json中通过harness:audit: node scripts/harness-audit.js暴露也是 agents/harness-optimizer.md 中“harness 优化专家”角色做基线信号采集与效果验收的依据。使用方式与参数命令的标准形态如下/harness-audit [scope] [--format text|json] [--root path]参数说明scope可选审计范围repo默认全仓库、hooks仅钩子表面、skills仅技能、commands仅命令、agents仅角色定义--format输出样式text默认人类可读、json供自动化消费--root指定要审计的目录路径默认审计当前工作目录命令文档约定Agent 在收到该指令时始终运行底层确定性脚本而非自行评估node scripts/harness-audit.js scope --format text|json [--root path]从源码 scripts/harness-audit.js 的parseArgs实现可以看到CLI 还支持多种等价写法便于脚本与交互式终端使用空格分隔node scripts/harness-audit.js --format json --scope skills --root ./my-project等号赋值node scripts/harness-audit.js --formatjson --scopehooks --root./my-project位置参数node scripts/harness-audit.js commands等价于--scope commands帮助--help/-h参数校验严格scope必须属于repo|hooks|skills|commands|agents之一--format必须为text|json否则脚本会抛出Invalid scope: xxx/Invalid format: xxx并以非零退出码结束——这一点由 tests/scripts/harness-audit.test.js 中的参数解析与 CLI 退出行为用例直接验证。确定性引擎评分的单一事实来源命令文档强调一条铁律脚本scripts/harness-audit.js是评分与检查的单一事实来源source of truth禁止自行发明额外维度或临时加分。这样做是为了保证可复现同一 commit 每次审计结果一致可纳入 CI 或评审门禁可解释每个扣分都能追溯到一条明确的文件/规则检查可执行每条失败检查都附带精确文件路径与修复建议。当前评分标准rubric版本号为2026-05-19在脚本中以RUBRIC_VERSION常量定义scripts/harness-audit.js并随 JSON 报告一起输出方便对接审计方核对评分口径。需要说明的是仓库中日文版文档docs/ja-JP/commands/harness-audit.md记录的早期 rubric2026-03-30固定 7 类已随版本演进英文权威版与源码当前为最多 12 个固定类别每个类别标准化为0-10分。脚本计算如下类别scripts/harness-audit.js#类别含义主要检查面1Tool Coverage工具覆盖度hooks 配置与实现数量、agents/skills 定义数量、命令文档同步2Context Efficiency上下文效率上下文压缩指引、压缩钩子、模型路由、Token 优化文档3Quality Gates质量门禁中心化测试入口、CI 校验链、钩子测试、安装漂移诊断4Memory Persistence记忆持久化记忆持久化钩子目录、会话起止持久化脚本、持续学习技能5Eval Coverage评估覆盖度评估 harness 技能、checkpoint 命令、自动化测试数量6Security Guardrails安全护栏安全评审技能与角色、提示词/工具预检钩子、安全扫描命令7Cost Efficiency成本效率成本感知 LLM 技能、Token 优化文档、复杂度感知模型路由8GitHub IntegrationGitHub 集成Actions 工作流、PR/Issue 模板、CODEOWNERS、依赖自动更新9Vercel IntegrationVercel 部署集成仅在检测到vercel.json或.vercel/时生效10Netlify IntegrationNetlify 部署集成仅在检测到netlify.toml或.netlify/时生效11Cloudflare IntegrationCloudflare 部署集成仅在检测到wrangler.toml或wrangler.jsonc时生效12Fly IntegrationFly 部署集成仅在检测到fly.toml时生效前 8 个类别始终适用后 4 个部署平台类别是条件适用的——只有目标目录中出现对应的标记文件marker时才会进入评分这正是“绝不假设固定满分”的原因。部署平台的标记检测以源码中PROVIDERS映射scripts/harness-audit.js为准各平台通过以下标记启用对应类别Vercelvercel.json或.vercel/project.json或.vercel/目录存在并进一步检查package.json脚本、.env.example键名、GitHub workflow 中是否出现vercel-action或vercel deploy等模式Netlifynetlify.toml或.netlify/存在检查netlify/actions、netlify deploy等模式Cloudflarewrangler.toml或wrangler.jsonc存在检查cloudflare/wrangler-action、wrangler deploy等模式Flyfly.toml存在检查superfly/flyctl-actions、flyctl deploy、fly deploy等模式。当平台类别被激活时脚本会额外生成 4 条检查部署配置文件是否入库、package.json脚本是否引用该平台、.env.example是否记录平台环境变量、GitHub workflow 是否使用对应 Action 或 CLI见 scripts/harness-audit.js。双模式自动检测审计 ECC 自身与消费方项目脚本默认审计当前工作目录并自动判断目标属于哪一种模式scripts/harness-audit.jsrepo 模式ECC 仓库本身当package.json的name为everything-claude-code或同时存在scripts/harness-audit.js、.claude-plugin/plugin.json、agents/、skills/等结构标记时判定。此时使用getRepoChecksscripts/harness-audit.js对 ECC 自身的工具链成熟度打分consumer 模式使用 ECC 的消费方项目否则判定。此时使用getConsumerChecksscripts/harness-audit.js重点检查ECC 插件是否已安装扫描installed_plugins.json、~/.claude/plugins/下的扁平布局与 marketplace 缓存布局、项目是否有.claude/本地覆盖、AGENTS.md/CLAUDE.md指令、.mcp.json或.claude/settings.json本地工具配置、测试入口、CI 工作流、记忆/ADR、评估目录、SECURITY.md与.gitignore中的密钥卫生等。消费方项目的检查项中也包含 GitHub Integration 与平台类别见getConsumerChecks末尾对buildGithubChecks与collectProviderChecks的调用因此在消费方仓库上同样可以拿到一份完整的“工具链健康度”报告。测试用例对两种模式均有覆盖既有“结构标记识别 repo 模式”tests/scripts/harness-audit.test.js也有“从 cwd 审计消费方项目”tests/scripts/harness-audit.test.js以及“空消费方项目应得到 0 分与 3 条 top actions”tests/scripts/harness-audit.test.js。评分规则与输出契约评分如何计算每条检查都是一个显式的{ category, points, pass, path, fix }记录。汇总时summarizeCategoryScoresscripts/harness-audit.js每个类别 通过检查得分之和 / 该类别检查满分之和再归一到0-10的整数Math.round((earned / max) * 10)max_score 当前范围下所有适用检查的points之和随 scope 与适用类别动态变化绝不是一个固定常数overall_score 通过检查的points之和未通过的检查按points降序取前 3 条构成top_actions见buildReportscripts/harness-audit.js。因此 repo 模式的全量满分不再固定为 70——只有当所有始终适用类别与 GitHub Integration 的全部检查都通过且没有激活任何平台类别时满分才可能是 808 个类别合计。输出契约命令文档明确规定了调用方Agent应返回给用户的六项内容overall_score/max_score其中max_score取决于目标上实际适用的类别调用方不得假设固定总分applicable_categories[]与category_count说明哪些类别参与了计分各类别分数与具体发现findings失败的检查及其精确文件路径来自确定性输出的前 3 条行动top_actions下一步建议应用的 ECC 技能。当--format json被请求时脚本直接输出完整 JSON 报告字段包括scope、root_dir、target_mode、deterministic、rubric_version、overall_score、max_score、categories、applicable_categories、category_count、checks[]含id/category/points/path/description/pass与top_actions[]。文本模式则由printTextscripts/harness-audit.js渲染为易读的评分卡。输出解读评分卡示例以英文权威版文档中的示例结果为准Harness Audit (repo, repo): 71/80 - Tool Coverage: 10/10 (10/10 pts) - Context Efficiency: 9/10 (9/10 pts) - Quality Gates: 10/10 (10/10 pts) - GitHub Integration: 2/10 (2/10 pts) Top 3 Actions: 1) [GitHub Integration] Add at least one workflow under .github/workflows/. (.github/workflows/) 2) [Security Guardrails] Add prompt/tool preflight security guards in hooks/hooks.json. (hooks/hooks.json) 3) [Eval Coverage] Increase automated test coverage across scripts/hooks/lib. (tests/)解读要点第一行Harness Audit (repo, repo): 71/80中括号内第一个值是 scope第二个是target_mode此处均为repo71/80即overall_score/max_score每个类别行给出归一化分x/10与原始分earned/max ptsTop 3 Actions按可挽回分值从高到低排列每条都标注了[类别]、修复动作与目标路径可直接作为下一步改进的待办清单失败检查列表Checks: N total, M failing会完整列出每条未通过检查及其精确文件路径供人工或 Agent 定位。注意若文本模式下失败检查为 0则不会打印Top 3 Actions见 scripts/harness-audit.js此时表示目标已通过全部适用检查。调用方检查清单Agent 使用规范命令文档为执行该指令的 Agent 约定了四条硬性规则确保审计不被“人工重打分”污染直接使用脚本输出不要手动重新评分如果请求--format json原样返回脚本 JSON不做二次加工如果请求文本输出汇总失败的检查与 top actions必须包含来自checks[]与top_actions[]的精确文件路径。结合源码深入理解核心检查项为了让读者能读懂评分卡背后的依据这里从getRepoChecksscripts/harness-audit.js摘取几条有代表性的检查并说明其判定逻辑Tool Coverage要求存在 hooks/hooks.json2 分、scripts/hooks/下至少 8 个 JS 钩子实现2 分、agents/下至少 10 个角色定义2 分、skills/下至少 20 个含SKILL.md的技能目录2 分并且commands/harness-audit.md与 .opencode/commands/harness-audit.md 内容完全一致命令文档同步2 分Context Efficiency要求存在 skills/strategic-compact/SKILL.md上下文压缩指引3 分、scripts/hooks/suggest-compact.js压缩建议钩子3 分、commands/model-route.md模型路由命令2 分与 docs/token-optimization.mdToken 优化文档2 分Quality Gates要求存在 tests/run-all.js中心测试入口3 分且package.json的test脚本同时包含validate-commands.js与tests/run-all.js校验链前置3 分——这正是当前仓库 package.json 中test脚本的形态Memory Persistence要求存在 hooks/memory-persistence4 分、scripts/hooks/session-start.js与session-end.js会话起止持久化4 分、skills/continuous-learning-v2/SKILL.md2 分Eval Coverage要求存在 skills/eval-harness/SKILL.md4 分、commands/checkpoint.md 加评估/验证技能4 分、tests/下至少 10 个.test.js文件2 分Security Guardrails要求存在 skills/security-review/SKILL.md3 分、agents/security-reviewer.md3 分、hooks/hooks.json中包含beforeSubmitPrompt或PreToolUse事件引用2 分、commands/security-scan.md2 分Cost Efficiency要求存在 skills/cost-aware-llm-pipeline/SKILL.md4 分、docs/token-optimization.md3 分、commands/model-route.md3 分。可以看出各类别之间并非孤立例如model-route命令同时支撑上下文效率与成本效率两个维度hooks/hooks.json同时被工具覆盖与安全护栏检查体现了 ECC“以文件为检查锚点”的设计——一次修复可以同时提升多个类别得分。测试与验证确定性如何被保证scripts/harness-audit.js 的确定性并非口头承诺而是被 tests/scripts/harness-audit.test.js 中的一组测试用例系统性验证输出可复现连续两次repo --format json输出逐字节一致tests/scripts/harness-audit.test.js分数有界overall_score在0..max_score之间类别名固定且包含全部 8 个始终适用类别tests/scripts/harness-audit.test.js类别适用性applicable_categories中每个类别max 0且category_count与数组长度一致tests/scripts/harness-audit.test.js平台类别条件触发分别以vercel.json、netlify.toml、wrangler.toml、fly.toml构造 fixture断言对应类别被激活并正确计分tests/scripts/harness-audit.test.js满分动态化带vercel.json的项目的max_score严格大于不带的项目tests/scripts/harness-audit.test.jsscope 过滤hooks范围下max_score与检查数量均小于repo全量且每条检查路径都落在 hooks 表面上tests/scripts/harness-audit.test.js插件安装发现覆盖installed_plugins.json清单、cache/everything-claude-code/ecc/version缓存布局并取最新版本、home 与项目两级 marketplace 布局等场景tests/scripts/harness-audit.test.js。这些测试本身就是“审计的审计”它们保证了任何对该脚本的改动都不会破坏评分的稳定性与边界行为。在真实工作流中的用法1. 独立审计在 ECC 仓库根目录执行node scripts/harness-audit.js repo --format text node scripts/harness-audit.js repo --format json node scripts/harness-audit.js hooks --format json node scripts/harness-audit.js skills --format text node scripts/harness-audit.js --root /path/to/consumer-project --format json或通过 npm script 入口npm run harness:audit2. 配合 harness-optimizer 角色做“审计 → 优化 → 复验”闭环agents/harness-optimizer.md 展示了审计输出在 ECC 中的标准用法该角色以node scripts/harness-audit.js repo --format json作为 Code-Based Grader 的基线信号先定义EVAL DEFINITION: harness-optimization能力评估覆盖 hooks、evals、routing、context、safety回归评估覆盖既有 hooks 与质量门禁再对每条 leverage area 做最小可逆改动最后重新运行审计脚本与node tests/run-all.js验证——任一失败即自动回滚快照绝不留下半成品配置。3. 纳入 CI 与评审门禁由于审计是确定性的同一 commit 结果不变完全可以在 CI 或 PR 评审中把harness:audit作为质量门禁之一例如要求overall_score不低于某个阈值、top_actions为空或将 JSON 报告归档用于趋势追踪。相关思路可在 docs/architecture/observability-readiness.md 与 docs/architecture/platform-value-loop.md 的架构讨论中找到呼应。常见问题问为什么满分不是固定的 70 或 80答max_score由当前 scope 与适用类别共同决定。平台类别Vercel/Netlify/Cloudflare/Fly只有在目标目录出现对应标记文件时才计分因此不同项目之间总分不可直接横向比较应关注同一项目随迭代的纵向变化与类别内earned/max明细。问审计结果可以被“优化”吗答检查是显式文件/规则判定任何改动都会如实反映在下一次审计中。但要注意脚本是评分权威不要通过修改 scripts/harness-audit.js 之外的途径伪造分数优化应来自真实的配置补齐如补安全钩子、同步命令文档、增加测试覆盖这与 harness-optimizer 角色的职责边界一致——它只允许修改 harness 配置表面不允许改写业务代码。问日文与中文文档中提到的“7 个固定类别”“repo 满分 70”为何与本文不同答这些翻译文档记录的 rubric 版本2026-03-30、2026-03-16早于当前源码RUBRIC_VERSION 2026-05-19。以当前仓库源码与英文权威版 commands/harness-audit.md 为准始终适用类别从 7 个扩展为 8 个新增 GitHub Integration另加 4 个条件适用的部署平台类别总分不再固定。使用审计结果时请以脚本实际输出的rubric_version与max_score为准。延伸阅读命令权威文档commands/harness-audit.md、.opencode/commands/harness-audit.md多语言版本docs/ja-JP/commands/harness-audit.md、docs/zh-CN/commands/harness-audit.md实现源码scripts/harness-audit.js测试用例tests/scripts/harness-audit.test.js关联角色与技能agents/harness-optimizer.md、skills/eval-harness/SKILL.md审计所覆盖的部分核心资产hooks/hooks.json、docs/token-optimization.md、commands/model-route.md、commands/security-scan.md、tests/run-all.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），仅供参考