开源 Agent 增强套件 ECC 是什么：一张五类组件的全景地图
本文基于 ECC 仓库 commit 591ab5c（2026-07-29）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/affaan-m/ECC 最新代码与文档为准。
**ECC 不是一个新的编码 Agent，它是一层配置：把「先计划、先写测试、换个上下文复审、把结论存下来」这套流程，从你每次手打的提示词里搬出来，钉进 Agent 的加载路径。**装完之后你用的还是 Claude Code、还是 Codex，只是它们身上多了一堆你没写过的目录文件。
这件事的价值和风险是同一个来源：它往你的机器里写文件、往会话里注入始终加载的文本、往工具调用前后挂 shell 脚本。看懂这五类东西分别落在哪、什么时候被触发，比记住它有多少个技能有用得多。
站内的 Agent 框架横向对比 和 多 Agent 框架怎么选 讲的是通用方法论——怎么比、按什么维度选。本篇不重复那层，只干一件事：把 ECC 这一个具体项目拆开，看它的方法论是用什么文件结构落地的。你可以把这篇当成前两篇的实物样本。
一、它插在你工具链的哪一层
ECC 采用 MIT 许可证，仓库在 affaan-m/ECC。README 里对它的定位是：你的 Agent 本来就会写代码，ECC 给它加的是一套协调好的工程系统——先计划再动手、用测试验证改动、从干净上下文里复审自己的产出、把重复奏效的做法沉淀成可复用的技能。
它主要面向 Claude Code，同时对 Codex 有一等支持，另有面向 Cursor、OpenCode、Gemini、Zed、GitHub Copilot、Antigravity、Qwen 等 harness 的适配层。这里的 harness 指的是承载模型的那层客户端外壳，也就是你每天敲命令的那个 CLI 或编辑器插件。ECC 不改模型，不改 harness，只往 harness 认识的那几个约定目录里放东西。
所以判断要不要装它，第一个问题不是「它功能多不多」，而是「我用的 harness 支持到什么程度」。仓库对不同 harness 的支持深度写得很直白：Claude Code 走插件安装最顺，Codex 推荐用 scripts/sync-ecc-to-codex.sh 同步流程，而 Codex 的插件市场路径被明确标注为实验性——插件包引用的共享仓库内容可能没被复制进 Codex 的安装缓存，所以需要全部技能可靠可用时，仍建议走同步流程。对于没有原生适配目标的 harness，仓库提供了手工适配指南，并且直说了一句实在话：不要假装那些工具有钩子机制或原生技能发现能力。
二、五类组件各管什么
先看这张表，它是理解后面所有内容的骨架。表里的路径都是仓库根目录下真实存在的位置。
| 组成部分 | 它负责什么 | 对应仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| Agent | 有独立上下文和工具权限的专职角色，把规划、实现、复审隔开 | agents/，共 67 个 .md 文件 | 委派任务时，或被命令自动调起时 |
| 技能（Skill） | 可复用的工作流，例如 TDD、安全复审、深度调研 | skills/<name>/SKILL.md，共 281 个 | 任务需要时被加载，也可直接调用 |
| 命令（Command） | 斜杠入口，是使用技能与 agent 的便捷门面 | commands/，共 94 个 | 你手动敲 / 的时候 |
| 规则（Rules） | 语言或项目层面的长期标准 | rules/，分 common/ 与各语言目录 | 每一次会话，它是始终加载的 |
| 钩子（Hooks） | 由 harness 事件触发的脚本，在模型上下文之外运行 | hooks/hooks.json 及配套脚本 | 你完全不知情的时候，它已经跑过了 |
这五类的分工不是随意切的，README 里给出的划分逻辑是上下文行为的差异：技能按需加载，agent 各自持有独立上下文，规则始终占位，钩子干脆不进上下文。这也是它敢于携带大量组件却声称不把整个仓库塞进每次会话的前提。想深入理解前两类在 Claude Code 里的原生机制，可以先看 Claude Code 技能怎么用 和 Claude Code 钩子机制。
值得单独说的是格式约束，因为它决定了你能不能自己往里加东西。仓库的 RULES.md 规定：agent 文件放在 agents/*.md，YAML frontmatter 需要 name、description、tools、model 四项，文件名小写连字符且必须与 agent 名一致；技能放在 skills/<name>/SKILL.md，frontmatter 要有 name 和 description，并用 origin 区分第一方与社区来源。实际打开 agents/code-reviewer.md，头部是这样的：
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code. MUST BE USED for all code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---
对照 agents/planner.md，它的 tools 只有 Read, Grep, Glob，model 是 opus。这个差别值得停一秒：规划角色被剥夺了执行类工具，只能读不能写。权限收窄是写在文件里的，不是靠提示词里说一句「请不要改代码」。
顺带一个诚实的观察：仓库里不同文档对组件数量的清点并不同步，SOUL.md 里的计数明显停留在更早的版本。遇到这种情况，以你 ls 出来的目录内容为准，不要以任何一份说明文档为准。
三、一次完整的流程长什么样
README 里把主线概括成一串箭头：plan、test、implement、review、verify、remember、improve。落到实际操作，官方给的入口大致是这样几段。
开始一个功能时，用 /ecc:plan "描述你的功能"，由 planner 产出实现蓝图；然后激活 tdd-workflow 技能，由 tdd-guide 强制先写测试；写完用 /code-review 让 code-reviewer 在干净上下文里复审。修 bug 的路径略有不同：先用一个能复现问题的失败测试起手，再进 TDD 流程。构建挂了用 /build-fix，清理死代码用 /refactor-clean，上线前用 /security-scan。
命令和 agent 的对应关系不用猜，docs/COMMAND-AGENT-MAP.md 就是这张映射表。里面能看到一些有意思的条目：/harness-audit、/quality-gate、/model-route 这几个命令在「主要 agent」一列写的是破折号，也就是它们不走 agent，而是脚本或流水线行为；/checkpoint 和 /verify 背后是 verification-loop 技能；/learn-eval、/evolve、/promote 这一串背后是 continuous-learning-v2，而老的 /learn 仍挂在 continuous-learning 上——同一条学习线上并存着两代技能，这种细节只有翻这张表才看得出来。
这里透露出项目当前的走向：技能是主要的工作流表面，命令更多是迁移期的便捷入口与兼容垫片。退役掉的短名字（例如 /tdd）被移到了 legacy-command-shims/，需要的人自己去那里挑文件复制，不再默认提供。你如果照着旧教程敲短命令发现没反应，原因通常在这。
仓库近期加进来的 Plan Canvas 是这条主线上比较特别的一环：Agent 写完计划后在一个仅限回环地址的浏览器页面里打开，你点选具体段落挂编号批注、从侧栏对话，最后按「Approve plan」或「Request changes」，这个结论直接映射到 /plan 的 CONFIRM 关卡。它做成了一个说 JSON 的独立 CLI（ecc-plan-canvas），所以理论上不绑定某个 harness 或模型。
跨会话的记忆走的是另一套：Memory Vault 把持久上下文存成本地可检视的 Markdown，项目和团队范围的记忆放在 .ecc/memory/，用户范围的放在 ~/.ecc/memory/。操作入口是 ecc memory init、save、handoff、search、read、doctor 这几条。关于上下文该怎么组织，上下文工程怎么做 里的原则在这里同样适用。
四、边界与代价：它放弃了什么
这一节是我认为装之前必须读完的部分，而且这些限制大多是仓库自己写明的，不是外部批评。
规则是始终加载的，所以它必然吃上下文。 README 反复强调「有选择地安装」，建议从 rules/common 加上你实际在用的那一个语言包起步。手工复制时还要求整个语言目录一起拷，而不是拷目录里的文件，否则相对引用会断、文件名会撞。这意味着你每开一个会话都在为这些文本付费——项目自己提供了 context-budget 技能来审计这笔开销，反过来说明这笔开销真实存在——顺带一提，同名的斜杠命令现在只躺在 legacy-command-shims/commands/ 里，README 里却还按老名字引用，这类文档与目录的不同步在这个仓库里不止一处。
钩子是在你机器上跑的脚本。 hooks/hooks.json 注册的事件包括 PreToolUse、PostToolUse、PostToolUseFailure、PreCompact、SessionStart、Stop、SessionEnd，匹配器写的是 Bash、Edit|Write|MultiEdit 这类工具名。安全文档里说得很清楚：钩子能运行 shell 命令、MCP 服务器能持有凭据、项目指令能进入 Agent 上下文，这三样都要当成可执行配置来看待。这不是危言耸听，而是这类套件的固有代价——你换来的确定性，是用「允许陌生脚本在工具调用前后执行」买的。
配套的 GateGuard 是个很能说明设计取向的例子。它是一个 PreToolUse 门，三段式行为：先拒掉第一次 Edit/Write/Bash 尝试，再明确告诉模型该去搜集哪些事实，等事实呈上来才放行。它的立论是 LLM 的自我评估无效——问「你确定吗」永远得到肯定答复，但问「列出所有 import 这个模块的文件」会逼出真实的 Grep 和 Read。这个思路的代价同样明显：你的每一次首轮编辑都会被打回。
记忆是未经审阅的上下文，不是可执行策略。 仓库把这条写进了文档：召回的内容必须回到权威来源去核实，绝不能当作可执行指令或策略；即使团队范围的记忆已经提交进版本库，它仍然是未审阅内容。写入方式也做了收窄，记忆正文只接受 --stdin 或 --body-file，不接受命令行参数传值。可选的 MCP 适配器只暴露 memory_save、memory_search、memory_read、memory_doctor 四个操作，用户范围的访问还需要额外的显式开关。
有些能力它明确不管。 模型服务商的接入方式归 harness 管，ECC 不硬编码传输设置——网关如果做了模型名重映射，要在 Claude Code 里配而不是在 ECC 里配。各家服务商的规则不同且会调整，以官方最新说明为准。插件安装也不会自动启用捆绑的 MCP 服务器定义，需要你自己用 /mcp 或复制 mcp-configs/mcp-servers.json 里的条目。multi-* 那组命令更直接：基础安装根本不覆盖它们，必须另外初始化 ccg-workflow 运行时才能跑。
五、上手清单：会踩什么，怎么避
别把两种安装方式叠在同一个 harness 上。 会踩是因为教程各写各的：一份教你装插件，另一份教你跑 ./install.sh --profile full，你都照做了。后果是技能、命令、钩子、配置出现重复，钩子甚至会触发两次。避法是每个 harness 只选一条路径；已经叠了就先移除插件安装，再从仓库根目录跑 node scripts/ecc.js uninstall --dry-run 看清要删什么，删掉手工拷的多余规则目录，最后只用一条路径重装。注意「同一个 harness 装两次」才是问题，「同时装进多个 harness」不是。
别以为三个标识符可以互换。 会踩是因为它们长得像：GitHub 源仓库是 affaan-m/ECC，Claude 插件标识是 ecc@ecc，npm 包是 ecc-universal。文档说明这是有意为之——插件安装以规范化标识为键，短名字是为了让工具名和斜杠命令的命名空间通过严格校验。避法是照抄文档里对应场景的那个名字，不要凭印象换。另外 npm 发布是按版本标签切的而不是按 commit，想跟最新代码就从 git 装。
装完插件发现规则没生效。 会踩是因为 Claude Code 插件机制无法分发 rules，这不是你装错了。避法是自己建 ~/.claude/rules/ecc/，把 rules/common 和你实际用的那个语言目录拷进去。想只对单个仓库生效，就拷到项目里的 .claude/rules/ecc/。
别把仓库里的 hooks/hooks.json 直接复制到 ~/.claude/settings.json。 会踩是因为那个文件看起来就是「钩子配置」，复制过去顺理成章。实际上它是面向插件和仓库的，路径没被改写；而且较新的 Claude Code 会自动加载插件自带的 hooks/hooks.json，你再复制一份就会重复执行，跨平台还会冲突。避法是走安装器：bash ./install.sh --target claude --modules hooks-runtime，它会写出路径已解析的钩子文件，并且不动你现有的 settings。这个坑在仓库里反复出现过，现在有回归测试守着。
手工安装技能时别嵌套目录。 会踩是因为你觉得放进 ~/.claude/skills/ecc/ 更整齐。但 Claude Code 只把 ~/.claude/skills/ 的直接子目录当作技能来发现，嵌一层就发现不了。避法是每个技能直接作为一级子目录存在。
ecc memory 敲下去提示找不到命令。 会踩是因为你以为装了 ECC 就有这个 CLI。实际上纯技能安装、minimal、手工安装和 Claude 插件安装都不会把它放进 PATH。避法是单独装 npm 运行时，再用 ecc memory --help 确认。
只从官方渠道装。 仓库首屏就挂了警告：第三方转载和非官方镜像不受项目维护与审查，可能含有恶意代码。这类套件本身就要往你的家目录写文件、挂钩子、连外部服务，来源错了后果比普通依赖严重得多。装完可以用 npx -y ecc-agentshield scan --path . 扫一遍自己的 agent、钩子、MCP 配置、权限和密钥面。
收束：装之前先回答三个问题
把这篇的判断压成一份自检：
第一，你的 harness 支持到哪一层？如果是 Claude Code，插件路径最顺，但仓库对 CLI 有一条最低版本要求（原因是插件系统处理钩子的方式变过），装之前先照 README 核一下自己的版本；如果是 Codex，认准同步流程；如果是别的工具，先接受钩子和原生技能发现可能都没有这个事实。
第二，你愿意为始终加载的规则付多少上下文？答案决定你是走完整安装还是从 minimal 起步——仓库专门提供了不带钩子运行时的低上下文路径，也提供了 ECC_HOOK_PROFILE 和 ECC_DISABLED_HOOKS 这类环境变量做运行期收紧，不必改钩子文件。
第三，你能接受多少「自动发生的事」？钩子在上下文之外运行，GateGuard 会拦你的第一次编辑，记忆会被写进项目目录。这些都是它奏效的原因，也都是它讨人嫌的原因。
真要动手，读文件的顺序建议是：README.md 先只看安装那一节和「What’s Inside」的目录树，RULES.md 看格式约束，docs/COMMAND-AGENT-MAP.md 当查询手册用；然后打开 agents/ 里任意两三个 .md 看 frontmatter 里的 tools 和 model 被收到了多窄——这比读任何介绍都更快让你明白它到底在管什么。
本文属于 ECC 开源 Agent 套件专题（共 40 篇，从选择性安装一直拆到内部机制）。同一批还写了另一种取向的项目——不给你资产、只给你纪律的 superpowers 方法论专题。