用 AI 编程代理写代码的人,多半都经历过这种场面:需求刚说完,它已经噼里啪啦写了三百行;你问它为什么这么设计,它答不上来;构建挂了,它改一处坏两处;好不容易调通,第二天新开一个会话,它把昨天的教训忘得一干二净。模型本身不笨,缺的是流程——没有规划环节,没有验证习惯,没有记忆沉淀,更没有安全边界。ECC(Everything Claude Code 生态的通用版)想补的正是这一层:它自称是「The agent harness performance optimization system」,给 AI 编程代理用的工程操作系统,把技能、本能、记忆、安全扫描和研究优先的开发流程打包成一套可安装、可维护的运行时,覆盖 Claude Code、Codex、OpenCode、Cursor 等多个 harness(代理宿主环境)。
项目地址:https://github.com/affaan-m/ECC
这个仓库 2026 年 1 月 18 日创建,不到一年时间攒下约 30.4 万星、4.47 万 fork,MIT 许可,当前发布版 2.2.3(2026 年 10 月 1 日),官网是 ecc.tools。它的工作环只有七步:plan → test → implement → review → verify → remember → improve,规划、测试、实现、审查、验证、记住、改进。理念浓缩成一句话:Optimize the context window. Persist everything else.——上下文窗口只留当下最要紧的东西,其余一切都持久化下来。这篇文章把它的内容构成、安装方式、日常工作流和几条必须守住的纪律一次讲清。
为什么裸用编程代理总出问题
先把痛点摆明白,才能理解 ECC 的每个组件是在治什么病。
第一是不规划。裸用的代理接到需求就直接写代码,方案没过脑子,边界条件、数据结构、影响面全靠写的时候现想,写错方向了就整段返工。第二是不验证。代码写完就算交付,测试不跑、构建不看、安全问题更没人管,等 CI 红了或者上线炸了才回头补。第三是不记事。会话一关,上下文清零:这个项目用什么测试框架、上次踩过什么坑、你纠正过它哪些习惯,统统归零,下次还得从头教一遍。
ECC 的应对是把「好工程师的工作习惯」拆成可执行的结构:规划有专门的规划代理和 plan 命令,验证有 TDD 技能和审查命令,记忆有 hooks 驱动的会话摘要、持续学习和 instincts(本能)机制,安全有内置扫描器。关于技能这个概念本身,之前拆箱过一个技能存档仓库(/posts/ai-museai-skills/),那边是把技能文档当资料存档来读;ECC 不一样,它是可以直接安装进你的代理环境、当场跑起来的技能系统,一个偏收藏,一个偏实战。
内容清单:六大件各管什么
ECC 不是一个大提示词文件,而是一组分工明确的部件。先看全貌:
| 部件 | 规模 | 管什么 |
|---|---|---|
| Agents(代理) | 71 个 | 规划、审查、构建修复、安全、架构与领域工作的专职代理,各自带明确职责 |
| Skills(技能) | 314 个 | TDD、研究、安全、文档、前端、数据、机器学习、运维等可复用的工作方法 |
| Commands(命令) | 98 个 legacy command shims | 兼容旧版命令入口的垫片,让老用法平滑过渡到新体系 |
| Hooks 与 Memory 运行时 | 一套 | 会话摘要、持续学习、instincts 本能、上下文控制,负责「记住」这一环 |
| Rules(规则) | 按需选取 | 按语言、按项目选择的常驻规范,让代理在特定代码库里守规矩 |
| AgentShield | 内置 | 安全扫描器,扫描 prompts、hooks、MCP 配置、权限、密钥与代理文件 |
几个部件值得多说两句。Agents 是「专职的人」:写功能之前先让规划代理出方案,写完之后让审查代理在新上下文里挑毛病,构建挂了交给构建修复代理,职责分开是为了避免一个代理既当运动员又当裁判。Skills 是「成文的方法」:比如 tdd-workflow 技能会强制代理先写测试再写实现,而不是嘴上答应心里跳过。Instincts(本能)是记忆运行时里比较有意思的一层:代理在长期使用中沉淀下来的行为倾向会被记录、复用,相当于把「这个项目里我们习惯这么干」固化下来,而不是每次靠你在提示词里重复叮嘱。
Rules 和 AgentShield 是一对搭档:Rules 决定代理平时守什么规矩,AgentShield 负责定期体检——它扫的不是你的业务代码,而是代理环境本身:提示词文件、hooks 脚本、MCP 配置、权限设置、有没有密钥明文躺在代理文件里。代理工具链越强大,它自己的配置面就越值得扫一遍。
记忆运行时值得单独展开,因为「不记事」是裸用代理最伤效率的毛病,而它恰好是 ECC 区别于普通技能包的地方。这套运行时由四部分组成:会话摘要在会话结束时把关键结论、未完成事项和踩过的坑压缩存档,下次开工不用从零交代背景;持续学习把多次会话里反复出现的模式沉淀下来,而不是只记住孤立的一次;instincts 本能层存的是行为倾向——比如「这个仓库的提交信息要用英文」「改接口之前先全局搜调用方」,这类习惯不必每次写进提示词;上下文控制则负责在窗口吃紧时决定什么留下、什么归档,呼应它那句理念:窗口只留当下要紧的,其余全部持久化。研究优先也是这套流程的一部分:动手之前先让代理查文档、看现有实现、摸清代码库的既有约定,再进入规划,而不是凭训练记忆里的印象直接开写——印象会过期,仓库里的代码不会骗人。
平台支持:先看清哪端是全功能
ECC 覆盖多个 harness,但各端能力并不对等,动手之前先对号入座:
- Claude Code:支持最完整,原生插件 slug 是
ecc@ecc,下文的安装与命令都以它为主线。 - Codex、Qoder:有原生插件路径,体验接近完整版。
- Cursor、OpenCode、Gemini、Zed、GitHub Copilot、Antigravity、Qwen、Kimi Code 等:走能力受限的适配器,能用核心技能与流程,但功能不完全对等,具体差异看官方支持矩阵,别默认每个命令在每个端都存在。
这一点也影响选型预期:如果你主力是 Claude Code,ECC 基本是全量体验;如果主力在适配器名单里,先查矩阵确认你想要的那几个技能在不在,再决定投入多少配置时间。本站之前介绍过几款终端里的 AI 编程助手(/posts/ai-cli-assistants/),ECC 和它们的关系是互补的——那些是代理本体,ECC 是装在代理之上的流程层。
换个角度看,这种「一个流程层、多个宿主」的结构也是它生态长得快的原因:技能、规则和记忆格式是宿主无关的,换代理不用把积累的工作方法推倒重来;各端的差异被收敛在适配器和插件里,官方支持矩阵把哪端缺什么写得明明白白,不靠用户自己踩坑去发现。对同时用两三个代理的人来说,这比每个端各维护一份提示词文件现实得多。
安装:只选一条路径
前置要求
通用安装包需要 Node.js 18 或更高版本。走 Claude Code 插件路径的话,还要保证 Git 和 Claude Code 2.1+ 都在 PATH 里能直接调用。先自查一遍:
node --version # 需要 18+git --versionclaude --version # 插件路径需要 2.1+引导式安装(推荐)
官方推荐的是引导式安装,一条命令起步:
npx ecc-universal@2.2.3 setupWindows 在 PowerShell 里跑同一条命令即可;习惯 pnpm 的用 pnpm dlx ecc-universal@2.2.3 setup,用 bun 的换成 bunx ecc-universal@2.2.3 setup。
向导的流程是先盘点:它会检查官方 marketplace 和本机各个可安装范围的现状,然后让你做两道选择题——安装范围(个人使用典型选 Global user,即全局用户级)和 hooks 档位(选 Standard 标准档)。选完才真正落盘。装完之后新开一个会话,验证插件已启用:
/plugin list列表里能看到 ecc@ecc 处于启用状态,安装就算成功。
多代理一次配置
手上有好几个代理要一起配,用带引导的批量安装:
npx ecc-universal@2.2.3 install --guidedClaude Code、Codex、Kimi Code 可以任意组合勾选。它的稳妥之处在于:所有目标在写入之前全部先预检一遍,最后统一让你确认一次,没问题才落盘,不会装一半发现某个端缺前置条件。
一条铁律
WARNING每种 harness 只选一条安装路径。不要把完整手动安装叠在插件安装之上,两套机制管同一批文件,必然互相打架。先想清楚走插件还是走手动,选定之后就只维护这一条。
上手工作流:三条线
装好之后,日常使用围绕三条线展开。注意命令命名:插件版带 /ecc: 前缀,手动安装的是短名,下面以插件版为主写法。
做新功能:先规划,后动手
/ecc:plan "给订单模块加一个按状态筛选的接口"plan 命令会让规划代理先产出方案:改哪些文件、接口长什么样、测试怎么写,你确认之后再进入实现。实现阶段挂上 tdd-workflow 技能,它强制先写测试、看着测试失败、再写实现让它变绿。写完想复查,另开一个新上下文做审查:
/code-review强调「新上下文」是因为审查者不该带着实现者的思路惯性,换一个干净视角更容易挑出真问题。
修 bug:先复现,再修
ECC 里修 bug 的标准姿势只有一条:先写一个能复现问题的失败测试,再动手修。没有复现测试就直接改代码,改完你无法证明问题真的没了,也无法防止它下周复发。构建层面的报错则交给专门命令:
/build-fix它负责定位构建失败、最小化修复,而不是顺手把半个模块重写一遍。
上线前:安全与上下文检查
/security-scan/context-budget前者跑安全审查(底层就是 AgentShield 那套扫描逻辑,重点看提示词、hooks、MCP 配置、权限和密钥),后者查当前上下文的占用压力——上下文快爆的时候先做摘要和裁剪,而不是硬塞到模型开始胡言乱语。会话层面的两个命令也建议养成习惯:收工时 /save-session 存档,下次 /resume-session 恢复;长期项目里用 /learn-eval 把这次会话里值得留下的经验沉淀进学习系统,喂给 remember 和 improve 两环。
技能不够用、想自己造或改造技能的,可以配合技能构建类工具一起看(/posts/ai-skill-seekers/);想先横向了解各家编程助手分工的,另有一篇编程助手综述(/posts/ai-coding-assistants/)可对照。
纪律一:hooks 不要重复装
这是插件用户最容易踩的坑。插件安装完成后,Claude Code 2.1+ 会自动加载插件自带的 hooks/hooks.json,hooks 已经生效了。有些人照着旧教程,又把同一批 hooks 手工复制进 ~/.claude/settings.json,结果是同一批 hooks 被执行两遍,还会引发跨平台冲突。
WARNING插件路径下,hooks 以插件自带的为准,
~/.claude/settings.json里不要再出现 ECC 的同名 hooks。发现会话摘要生成两份、某个 hook 报错两次,先查这里。
纪律二:MCP 不要默认全开
插件安装默认不自动启用 ECC 自带的 MCP 定义,这是刻意的克制。ECC 只带一个默认连接器 chrome-devtools,其余所谓 MCP 能力,要么是技能包装的 CLI/REST 调用,要么是可选目录项,需要你自己点头才装。
如果你已经自备了同款 MCP,不想让 ECC 再碰它,可以在安装或同步时排除:
ECC_DISABLED_MCPS="chrome-devtools"把这个环境变量设好,安装和同步流程就会跳过 chrome-devtools。反过来,想给某个项目单独加 MCP 定义时,去仓库的 mcp-configs/mcp-servers.json 里挑需要的条目,复制到项目级的 .mcp.json:
{ "mcpServers": { "example": { "command": "npx", "args": ["-y", "example-mcp-server"], "env": { "EXAMPLE_API_KEY": "YOUR_API_KEY_HERE" } } }}注意定义里的 YOUR_*_HERE 全是占位符,必须换成你自己的密钥再保存,原样提交进仓库等于把假钥匙和真配置一起公开示众。
维护与卸载
日常维护用同一套 CLI 入口,先看装了什么、再体检、再修复:
npx ecc-universal@2.2.3 list-installed # 列出受管的已安装内容npx ecc-universal@2.2.3 doctor # 体检:版本、前置、配置一致性npx ecc-universal@2.2.3 repair # 按体检结果修复卸载分两步,先预演再真删:
npx ecc-universal@2.2.3 uninstall --dry-run # 只列出将删的文件,不动手npx ecc-universal@2.2.3 uninstall # 确认无误后执行卸载只删它自己记录在案的受管文件,harness 目录里的无关文件不会动,这也是为什么 dry-run 值得每次都跑——清单对得上,才说明受管状态是干净的。
如果你早期不懂纪律、叠装过多种方式,清理顺序是固定的:先移除 Claude Code 插件,再到装有受管状态的项目目录里跑 uninstall,然后删掉手工复制的 rules 文件夹,最后只选一条路径重新安装。顺序反了容易出现插件删了但手动文件还在、或者状态文件找不到主人的半吊子局面。
自托管模型:通道自己说了算
ECC 不写死 Anthropic 官方通道。harness 能连上的接口它都能用:官方接口、兼容网关、自托管模型都行。Claude Code 侧的示例是把通道指向自己的网关:
export ANTHROPIC_BASE_URL="https://你的网关地址"export ANTHROPIC_AUTH_TOKEN="你的令牌"模型名映射在 Claude Code 里配,不在 ECC 里配——ECC 只管流程层,谁来当模型、模型名怎么对应,是宿主环境的职责。这个边界划得清楚,对已经有自建网关的人很友好,不用为了用一套流程被迫换通道。
安全提醒:只认官方渠道
WARNINGECC 只从官方渠道安装:GitHub 仓库、npm 上的
ecc-universal与ecc-agentshield、官方 GitHub App、插件 slugecc@ecc、官网 ecc.tools。第三方重传与镜像未经维护者审核,可能夹带恶意代码——给代理装的东西权限极大,能读代码、能跑命令,来源这关没有将就的余地。
另外别把 ECC Pro 和开源版混为一谈:ECC Pro 是面向私有仓库的托管 GitHub App,付费产品;开源仓库本身是 MIT 许可、永久免费。你在 GitHub 上装到的这套东西,不存在「试用期到了要付费」这回事。
排障
1. hooks 重复执行(摘要生成两份、hook 报错成双)
多半是插件 hooks 和手工复制进 ~/.claude/settings.json 的 hooks 撞车。删掉 settings 里手工加的那一份,只保留插件自带加载,重启会话验证。
2. 插件命令找不到(输入 /ecc/plugin list 确认 ecc@ecc 在列表里且已启用;不在就检查前置:Git 与 Claude Code 2.1+ 是否在 PATH 中,然后重跑引导安装。再确认自己装的是插件版还是手动版——手动版命令是短名,没有 /ecc: 前缀,两种写法混用是新手期最高频的乌龙。
3. 和自备 MCP 重复(同名连接器出现两套)
给安装/同步流程设置 ECC_DISABLED_MCPS="chrome-devtools"(或把你要排除的名字填进去),让 ECC 跳过自带定义;同时检查项目 .mcp.json 里有没有从官方目录复制后忘了删的重复条目,一处定义只留一份。
4. 装过多种方式、状态混乱
不要逐个文件猜着删。按固定顺序来:移除 Claude Code 插件 → 在有受管状态的项目目录跑 uninstall(先 --dry-run 看清单)→ 删手工复制的 rules 文件夹 → 只选一条路径重装。
小结
ECC 的价值不在某个单独的技能或命令,而在于它把 plan → test → implement → review → verify → remember → improve 这条工作环做成了可安装、可维护的运行时:71 个专职代理分工,314 个技能沉淀方法,hooks 与记忆系统负责不忘事,AgentShield 守住代理环境自身的安全。用好它的前提是三条纪律:每种 harness 只选一条安装路径,hooks 不重复装,MCP 不默认全开。把这三条守住,再让它陪你跑几个真实项目,那种「代理终于像个靠谱同事」的感觉,大概就是这 30 多万颗星的来历。