每日壁纸
yuanjing's blog
#agent#claude-code#codex#hooks#context-engineering

ECC

JavaScriptMITaffaan-m/ECC官网

/---

一句话项目 slogan：Optimize the context window. Persist everything else.（把上下文窗口省着用，其它一切都落盘。）

这是「一天一个开源项目」系列的一篇。今天讲 ECC（Everything Claude Code）。

和 agent 协作过半年的人，真正值钱的东西往往不在代码里。它散在三十个会话里：先写测试再实现、review 要换一个干净的上下文、提交前跑哪几个检查、什么任务该拆给子代理。这些规矩你每开一个新会话都得重讲一遍，换个 harness（Claude Code 换 Codex、换 Cursor）更是直接归零。

更麻烦的是第二层：等你终于把它们写成两百个 skill、五十条 rule，系统提示被自己的资源塞满，模型开始忽略中间那段。为了让它记住更多，结果让它忘得更快。

ECC 的赌注是把「工程制度」从散文变成可安装、可校验、有预算的资源：装一次，然后变成 agent 干活的方式。

项目速览

⭐ 290,384 Stars ｜ 🍴 43,022 Forks ｜ 📄 MIT 协议 ｜ 🔧 4,059 次提交 ｜ 🐛 252 个 Open Issues

截至 2026-10-27。仓库创建于 2026-01-18，九个多月长到 29 万星；412 位贡献者里作者 affaan-m 占 1,778 次提交（约 44%）。装起来的体积也不小：ecc-universal 这个 npm 包解压后 19.5 MB。

阅读价值与前置说明

读完你应该能回答：

  • 为什么一个「提示词合集」要管自己叫操作系统？它到底在管什么？
  • 上下文只有 8000 token 额度时，怎么决定哪三个 skill 进场、哪六条经验被注入？
  • 「支持某个 harness」除了写进 README，还能怎么被验证？
  • 为什么这个项目的安全工具拒绝用一个没版本号的 npx 命令下发？
  • 一个治理得这么严的项目，在哪几件事上照样是坏的？

前置知识：

  • 用过至少一个 coding agent（Claude Code / Codex / Cursor 任一）
  • 知道系统提示、skill、hook、子代理这些概念大概是什么
  • 可选：了解 CI 里的 schema 校验与快照测试，读第八段会更顺

项目背景与完整档案

官方定位（GitHub 描述）："The agent harness performance optimization system." README 的说法更具体：你的 agent 会写代码，ECC 给它一套工程系统——先计划再动手、用测试验证、换新上下文自审、记住重要的、把重复的成功变成可复用技能。核心流水线就一行：

plan -> test -> implement -> review -> verify -> remember -> improve

归属上要说清楚：这是个人主导的项目（作者 affaan-m），不是 Anthropic 官方产物——它装进你自己的 Claude Code / Codex，并不产出模型。README 的 Background 里，作者自述 2025 年 9 月拿过 Anthropic x Forum Ventures 黑客松（作品是 zenith.chat），这组配置是他的「在生产应用里打过仗」的沉淀。另外别把仓库里那句「Built at the Claude Code Hackathon（Cerebral Valley x Anthropic, Feb 2026）」安到 ECC 头上——那句话在 AgentShield 小节里，说的是那个安全工具。

基础信息：

  • 仓库：affaan-m/ECC，当前 v2.2.3（2026-10-01）
  • npm：ecc-universal 2.2.3；另有安全审计工具 ecc-agentshield 1.6.0
  • 协议：MIT
  • 运行要求：Node.js 18+；Claude Code 插件路径还需 Git 与 Claude Code 2.1+
  • 代码构成：JavaScript 11.4 MB / Rust 1.9 MB / Python 1.6 MB / Shell 242 KB
  • 仓库规模：4,649 个文件；311 个技能（skills/*/SKILL.md）、71 个 agent、97 个命令、122 条规则文件、518 个测试文件
  • 文档成本：docs/ 下 1,540 个文件，README 另有 16 种译文

项目数据（截至 2026-10-27）：

  • ⭐ Stars 290,384 ｜ 🍴 Forks 43,022 ｜ 🐛 Open Issues 252
  • 🔧 提交 4,059 ｜ 👥 贡献者 412
  • 🗓️ 创建于 2026-01-18，最近推送 2026-10-26
  • 🏷️ 版本节奏很密：v2.2.0（08-28）、v2.2.1（09-08）、v2.2.2（09-30）、v2.2.3（10-01）

它解决什么问题

和 agent 长期协作的人都会撞上的墙：

  • 经验不可携带：你调出来的工作流写在自己的会话和笔记里；换 harness、换项目、换机器，全部重来
  • 规矩不可靠：「请记得先写测试」是一句建议，模型忘了就忘了，没有东西兜底
  • 上下文被自己的资源挤爆：技能越写越多，全量加载后系统提示臃肿，模型反而更糊
  • 「支持某工具」是一句空话：装完才发现 hooks 在这个 harness 里只是提示文本，不是强制
  • agent 的配置本身没人审计：CLAUDE.md、settings.json、mcp.json、hooks 都是能执行代码的东西，却默认被信任

ECC 的解法分四步：

第一步，制度写成文件。技能、规则、命令、hook 都以仓库根为唯一源（skills/*/SKILL.md、rules/、commands/、hooks/hooks.json），各 harness 侧只做加载映射。

第二步，能在提示之外强制的，就不放进提示。质量检查交给 hook 做确定性执行，而不是指望模型记得。

第三步，进上下文的量要预算化。安装按模块/画像分层（minimal 连 hook 运行时不装），上下文有 token 与条数上限。

第四步，把跨 harness 的支持程度写成可校验的契约。分四档，每档绑定安装路径、验证命令和风险说明，缺一项 CI 就失败。

使用场景：

  • 一个人跨多个 agent：白天 Claude Code、晚上 Codex，技能和记忆共用一套
  • 团队要统一 agent 行为：把内网规范写进 rules + hooks，用 profile 按项目类型装
  • 长任务编排：用子代理分工 + worktree 隔离，配 ecc2 的会话控制面
  • 给 agent 配置做体检：装第三方插件、改 hook 之前先跑一遍 AgentShield

快速上手

前提：Node.js 18+；走 Claude Code 插件路径还需要 Git 和 Claude Code 2.1+。

最省事的路径（Claude Code 插件，官方推荐）：

npx ecc-universal@2.2.3 setup

想一次配多个 harness，用引导式安装（可选 Claude Code / Codex / Kimi Code 任意组合，写盘前会预检并要一次确认）：

npx ecc-universal@2.2.3 install --guided

装完新开一个 Claude Code 会话，验证插件已启用：

/plugin list

如果你更信 Claude Code 自己的插件机制，也可以在里面执行：

/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

两个注意点，都是官方文档强调的：每个 harness 只选一种安装方式（叠加装会把 skill、命令、hook 复制两份）；低上下文或本地小模型环境用 --profile minimal（这个画像刻意不装 hook 运行时）。

核心特性拆解

311 个技能——技能是主要工作面：TDD、研究、安全、前端、数据、ML、运维各有成套，按需加载而不是全量塞进提示。

71 个子代理——planner、architect、各语言 reviewer、build-error-resolver、e2e-runner、security-reviewer 等，用有限工具集分派任务，让「写代码的上下文」和「review 的上下文」分开。

97 个命令——/plan、/code-review、/quality-gate、/learn、/instinct-status、/evolve 这些入口。README 说得很直白：命令正在向技能迁移，保留是为了兼容。

Hook 运行时 + 三档强度——hooks 在工具事件上触发，ECC_HOOK_PROFILE 选强度，ECC_DISABLED_HOOKS 能按 ID 精确关掉某一条。这个是「制度」和「建议」的分界线。

规则按语言选装——rules/common/ 之外，TypeScript、Python、Go、Swift、PHP、ArkTS 各自一套，只装你用的。

记忆库（memory vault）——.ecc/memory/ 和 ~/.ecc/memory/ 下的人类可读文档，跨 harness 共享，同时提供 ecc memory CLI 和本地 stdio MCP 两个入口。

AgentShield——扫描 agent 配置本身的漏洞：CLAUDE.md 里的硬编码密钥和注入话术、settings.json 里过宽的 allow 列表、mcp.json 里可疑的服务器、hooks 里的命令注入、agent 定义里不受限的工具权限。

ecc2 控制面——2.0 之后多了一个 Rust 写的守护进程：会话生命周期管理、TUI 看板、worktree、通知、可观测性。

深度设计剖析

设计亮点一：上下文是一次有预算、有排序、且明确「不可观测」的注入决策

常规方案：

绝大多数「agent 增强包」的加载逻辑是「装了就用」：所有 skill 的描述、所有规则、所有学到的经验，一股脑进系统提示。资源少的时候看不出问题，写多了就变成上下文互相挤占——而且没有人知道到底是谁把额度吃掉了。

ECC 的做法：

先把安装本身分层。安装画像（profile）是一组模块的集合，minimal 的说明写着「低上下文 Claude Code 配置，有规则、agent、命令、平台配置和质量流程，但不含 hook 运行时」；full 则列了 33 个模块。想省上下文，先省在安装这一步。

再往上，是两层显式的上下文清单（manifests/context-profiles/）：

// lean@1.json
"selection": {
  "eager": ["skill:configure-ecc", "skill:context-budget", "skill:ecc-guide"],
  "required": ["skill:configure-ecc", "skill:context-budget", "skill:ecc-guide"],
  "remainder": "routed"
},
"budget": { "tokens": 8000, "mode": "blocking" }

lean@1 只让三个技能常驻（装配置、算上下文预算、看总览），其余全部走「路由」；full@1 是 eager: "all"，但预算同样是 8000 token，模式是 report-only。这两份清单的 description 里有句话值得单独拎出来："this profile does not activate or modify a harness"、"native activation is unobserved"——它们描述的是意图投影，不是强制结果，作者明确告诉你「harness 到底照做没照做，我们观测不到」。

第二层是「直觉」（instincts）注入。ECC 会把会话里学到的模式存成带置信度的直觉，然后决定哪些进上下文。默认值写在环境变量文档里：最多注入 6 条（ECC_MAX_INJECTED_INSTINCTS）、置信度门槛 0.7（ECC_INSTINCT_CONFIDENCE_THRESHOLD）、SessionStart 附加上下文上限 8000 字符（ECC_SESSION_START_MAX_CHARS）。

排序逻辑在 scripts/lib/instinct-relevance.js：

const DEFAULT_PROJECT_SCOPE_BOOST = 0.25
const DEFAULT_STACK_MATCH_BOOST = 0.2

项目内范围的直觉 +0.25，domain/trigger/stack 命中当前技术栈的 +0.2。注释把数值的来历交代了：这样一条项目内的 0.7 能（0.7+0.25=0.95）压过一条无关的全局 0.9，一条栈匹配的 0.75 也能压过无关的 0.9。而且这两个值故意不做成环境变量可调——因为相关的那条 issue 要求的是「相关性排序」，不是再多几个旋钮。

几个有说服力的工程细节：

  • 匹配按整词切分，不是子串。注释专门点名：避免关键字 go 命中单词 good。
  • 技术栈探测必须便宜：只看项目根目录顶层（非递归），因为这段代码跑在一次会阻塞的 SessionStart hook 里。除了常规语言/框架探测，还额外加 *.tf / *.tfvars → terraform、dbt_project.yml → dbt。
  • 优雅降级：没有项目内直觉、也没探到技术栈时，所有 boost 归零，排序退化成纯置信度——行为和加这个功能之前一致。

为什么这么做：

因为「记住更多」和「别把窗口塞满」是一对直接冲突的目标。把注入变成一道有上限、有排序的题，才能让「学到的东西变多」不等于「提示变长」。而把兜底的排序权重写死在代码里、把不可观测的部分写进文档，是在承认一件事：这部分结果依赖 harness，ECC 只能管住自己这一侧。

代价：

  • 注入上限意味着主动遗忘：第 7 条够格的直觉就是进不去，没有例外通道
  • 排序权重不可调，遇到「我的项目就是需要全局经验优先」的场景只能关掉整个排序
  • 预算有两种模式：lean@1 是 blocking，full@1 只是 report-only；加上「不可观测」的自述，说明这套额度里有一部分是自述而非强制

设计亮点二：把「支持某个 harness」写成能被 CI 打回的契约

常规方案：

跨工具项目的 README 上写一排 logo：Claude Code ✓、Codex ✓、Cursor ✓、Gemini ✓。何为「支持」没有定义，装完发现 hooks 不生效、命令不认、agent 起不来，也很正常。

ECC 的做法：

先定义四种状态，写进 docs/architecture/harness-adapter-compliance.md：

状态含义
Native能直接为这个 harness 安装或验证该能力面
Adapter-backed有薄适配层，但各 harness 的完成度不同
Instruction-backed只能提供文件与指引，harness 不暴露 ECC 需要的 hook/会话面
Reference-only只能当设计参照，还没有安装器或适配器

然后是一张从源码渲染出来的矩阵：它不是手写的表格，而是由 scripts/lib/harness-adapter-compliance.js 生成，用 npm run harness:adapters -- --check 校验公开文档和数据源是否还对得上。

矩阵里每一条适配记录必须带齐九个字段：状态、支持的资产、不支持或不同的能力面、安装方式、验证命令、风险说明、最后验证时间、负责人、来源文档。文档写得很清楚：任何一条公开声明缺安装路径、验证命令、风险说明、负责人、来源文档或验证日期，校验器就失败。

配套的操作原则也只有一句话："Do not call a harness native until the adapter has an install path and a verification command."

几个能体现这套东西有多较真的条目：

  • Codex 标的是 Instruction-backed，风险说明直接写「除非 Codex 有原生 hook 面，否则把 hooks 当作策略文本看待」——不假装有强制力。
  • Pi 标 Adapter-backed，同时承认「agent 链、审批提示、持久 todo 需要配套包，不在本适配器内」；风险栏还写明 Pi 扩展以完整用户权限执行。
  • DeepSeek Harness 那条更细：命令 hook 走官方桥接，覆盖 7 个桥接事件里的 5 个、23 条命令；并点名 PreCompact、PostToolUseFailure、SessionEnd 三个事件没有对应物，配置里「裸的顶层 patch 条目会被静默丢弃」。这种细节写到「哪个事件没有对应物」的粒度，基本只有真跑过的人写得出来。

为什么这么做：

因为跨 harness 的复杂度不会被「支持」两个字吸收，只会转移。把它写成可校验的状态机加字段清单，等于把「我们做到了哪一步」变成可以回归测试的东西——升级 harness 之后跑一遍 --check，声明和数据源对不上就红。

工程价值与代价：

价值是三重的：用户可以按状态预期功能，而不是按 logo；维护者升级适配器时不会忘记改文档；CI 能拦住「README 承诺了但代码没有」这种最常见的漂移。

代价也很清楚：文档变成代码的一部分，改一个适配器要同步改字段、跑校验；四种状态对用户来说是需要学习的额外概念；而且状态再细也回答不了「这个 harness 上 hooks 到底有没有真的跑」——Instruction-backed 本质上就是一句「我们只能提供文本」。

项目细节补充

安全工具自己拒绝被随便分发。 AgentShield 扫的是 agent 配置这个攻击面：CLAUDE.md 里的硬编码密钥与注入话术、settings.json 里过宽的 allow 列表和危险 bypass 开关、mcp.json 里可疑的服务器与 npx 供应链风险、hooks 里的插值注入与静默吞错、agent 定义里不受限的工具权限。但它自己的安装说明有一段「Runner provenance」：这些命令要求已经安装且审查过的 ecc-agentshield，ECC 不提供经过审计的版本 pin，也不允许「用一次性的无版本 npx 跑一下」。一个安全工具先对自己执行这条纪律，比写在口号里可信。

记忆库的三条硬约束。 docs/design/ecc-memory-vault.md 里写着：Markdown 是唯一真源，SQLite 图、embedding、托管系统都只能当索引；记忆是上下文，不是指令——每条新记忆初始 trust: "unreviewed"，不能被静默提升成规则或策略；写入是 create-only，永不覆盖已有 ID，取代关系靠新文档加显式链接表达。它连威胁边界都写了：这份实现对「同一 OS 用户下的并发进程」不构成安全边界，因为 Node.js 给不了 openat2 那种保证——需要隔离就用独立账户或容器。

Rust 那 1.9 MB 不是装饰。 ecc2/ 是 2.0 之后加的控制面：session/ 下有 daemon、manager、runtime、store，另有 TUI 看板、worktree、通知和可观测性模块。主体逻辑仍在 JS 和 markdown 里，Rust 只承担「长任务要有人管状态」这件事。

文档成本是真的。 docs/ 1,540 个文件，README 另有 16 种译文，全都签进仓库。好处是各地开发者能读懂；代价是每次改安装流程，翻译版就落后一截——这类项目最后往往靠「英文版为准」的约定兜底。

免费的部分和收费的部分。 README 有一节写得挺直白：ECC 免费，靠赞助和 Pro 用户养着；ECC Pro 换成托管的 GitHub App，加私有仓库分析、PR 触发的审计、AgentShield 扫描、团队用量池和优先支持。开源部分和商业部分的边界写在明面上，不是「先开源再收网」。

它自己承认坏掉的地方。 平台支持表里直接挂着 issue 号：macOS 上独立的 GAN 路径与系统 Bash 3.2 不兼容、且存在评分解析缺陷（#2674）；Windows 原生下连续学习的 observer 守护进程和记忆库写入都有未修复缺陷（#2489、#2626）。这种「把坏掉的地方和 bug 号并排放进支持矩阵」的做法，比一张全绿的表格有用得多。

项目资源汇总

官方资源

  • GitHub：affaan-m/ECC
  • 官网：ecc.tools
  • 开源协议：MIT
  • 版本：v2.2.3（2026-10-01）；npm 包 ecc-universal
  • 更新日志：仓库内 CHANGELOG.md；逐版本说明在 docs/releases/
  • 安装与适配：docs/architecture/harness-adapter-compliance.md（跨 harness 合规矩阵）
  • 三份指南：the-shortform-guide.md（上手）、the-longform-guide.md（上下文经济学、记忆、评测、并行）、the-security-guide.md（提示注入、hooks、MCP、AgentShield）
  • 安全工具：ecc-agentshield
  • 社区：Discord（README 顶部有邀请链接）、GitHub App

相关资源

媒体报道与延伸阅读

  • DeepWiki 架构导读（第三方自动生成，覆盖控制面、组件地图、安装画像、跨 harness 分层；注意它滞后于仓库，页面上还写着 68 agents / 290 skills，当前是 71 / 311）

核心要点回顾

  • ECC 不是提示词合集，而是把工程制度产品化：311 个技能、71 个 agent、97 个命令、规则和 hook 都以仓库根为唯一源
  • 上下文被当成预算管：整体 8000 token、SessionStart 附加 8000 字符、最多注入 6 条直觉、门槛 0.7，排序靠 +0.25 项目内 / +0.2 栈匹配，且这两个权重故意不给调
  • 跨 harness 支持是一份四档契约，矩阵由源码生成、--check 校验，缺安装路径或验证命令的声明直接判失败
  • 它最可信的地方是写清了「管不到的部分」：profile 只是投影、Instruction-backed 只有策略文本、记忆库不是安全边界

适合谁

  • 同时在两三个 coding agent 之间切换、受够了每次重讲规矩的人
  • 想把团队规范变成 agent 的强制检查（而不是又一份共读文档）的工程团队
  • 需要给 agent 配置做安全体检的平台/安全工程师
  • 对上下文工程、资源加载预算这类问题感兴趣的架构爱好者

一句话评价

它最狠的地方不是存了 311 个技能，而是敢在文档里写明哪些技能「装了也不一定生效」。

← Previous projectuv
Next project →Biome