开源 Agent 套件 ECC 上手第一周：先开哪几样、第三天加什么、哪些先别碰
本文基于 ECC 仓库 commit 591ab5c（2026-07-29）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/affaan-m/ECC 最新代码与文档为准。
第一周决定 ECC 对你是提效还是变成噪音的，不是你装了多少件，而是你有没有守住两条线：常驻上下文的预算，和一条能原路退回去的卸载路径。 这套东西的默认全量安装会把二十多个模块、几百个技能定义和一整套生命周期钩子塞进你的 Agent 运行环境，其中相当一部分跟你手上的仓库毫无关系。先摊开它由什么组成，再谈开合顺序。
站内已有的 Claude Code 教程 讲的是编码 Agent 本身怎么用，AI 落地场景怎么选 讲的是该不该上、上在哪；这两篇是通用方法论。本篇只做一件事：把一个真实存在、你能当场 clone 下来对照的开源项目，按目录、清单和开关拆开，说清第一周每一步动了什么、代价是什么。
一、先弄明白你装进来的是什么
ECC 采用 MIT 许可证。README 里写明它提供 67 个 agent、281 个技能、94 个命令兼容入口，外加钩子、规则、记忆与安全扫描。数量本身没什么意义，重要的是这些东西在你机器上的加载方式完全不同——有的是常驻上下文，有的是按需触发，有的是每次工具调用都要跑一次的子进程。
| 组成部分 | 它负责什么 | 仓库位置 | 你什么时候会碰到它 |
|---|---|---|---|
| 规则（rules） | 你选定后每次会话都加载的常驻标准 | rules/，含 rules/common 和各语言目录 | 第一天，装完立刻影响每一次对话 |
| 技能（skills） | 可复用的工作流包，项目主推的承载面 | skills/ | 第一天起，按名字被触发 |
| 代理（agents） | 计划、审查、修构建、安全等分工角色定义 | agents/ | 第一到第二天，需要委派时 |
| 命令（commands） | 斜杠入口，迁移期的兼容层 | commands/，退役的在 legacy-command-shims/ | 想沿用老斜杠名时 |
| 钩子（hooks） | 挂在工具调用与会话生命周期上的自动动作 | hooks/hooks.json，脚本在 scripts/hooks/ | 第三天，也是最容易翻车的一天 |
| 安装清单 | 描述 profile 与 module 怎么组合的数据文件 | manifests/install-profiles.json、manifests/install-modules.json | 决定装哪些的时候 |
| 上下文片段 | 用 --system-prompt 动态注入的模式文件 | contexts/dev.md、contexts/review.md、contexts/research.md | 第一周后期做精细控制时 |
这张表值得你在动手前先照着 ls 一遍。仓库里 the-shortform-guide.md 把这套分层讲得比较直白：技能是主要的工作流面，钩子是绑死在事件上的触发式自动化，两者的约束范围不一样；命令层在这份文档里被明确定位成迁移期的斜杠入口兼容，真正该沉淀的逻辑放在技能里。你如果一上来就照着命令列表逐个试，方向就偏了。
二、第一天：只开规则、代理和技能，不开钩子运行时
manifests/install-profiles.json 里定义了七个 profile。minimal 的组成是 rules-core、agents-core、commands-core、platform-configs、workflow-quality 五个模块，它的描述里写得很清楚：低上下文的 Claude Code 配置，有规则、代理、命令、平台配置和质量工作流支持，但没有钩子运行时。core 在这基础上加 hooks-runtime，developer 再加框架语言、数据库和编排，full 则是把当前分类过的全部模块都装上。
第一天选 minimal。理由不是”保守一点比较好”这种废话，而是这五个模块里只有 rules-core 是真正常驻的——README 明说规则属于总在加载的上下文，所以它建议你从 rules/common 加上一个你实际在用的语言包开始，而不是把 rules/ 整个拷进去。技能和代理是按需触发的，多装几个的边际成本远低于多装一份规则。
装法上有个容易踩的分叉。Claude Code 走插件路径是 /plugin marketplace add https://github.com/affaan-m/ECC 加 /plugin install ecc@ecc，但 README 特别提醒：Claude Code 插件没法分发 rules，所以规则得你自己 clone 仓库后手动拷到 ~/.claude/rules/ecc/ 下。而且插件装完之后不要再跑 ./install.sh --profile full——文档把”插件 + 完整手工安装”和”Codex sync + Codex 市场插件”都列进了明确的避免项，重复叠装会让技能、命令、钩子和配置出现重复副本。
手工安装路径是 ./install.sh --profile minimal --target claude，Windows 上对应 install.ps1。另有一条 npx ecc-install --profile minimal --target claude，省掉先 clone 这一步。
第一天你实际要验证的只有三件事：技能目录是不是平铺的（README 强调 Claude 只从 ~/.claude/skills/ 的直接子目录发现技能，手动装不要嵌套到 ~/.claude/skills/ecc/ 里去）、规则只有 common 加一个语言包、以及 node scripts/ecc.js list-installed 能列出被管理的文件。最后这条尤其关键，它是你之后能干净卸载的凭据。
三、第二天：用一个真实任务压一遍技能面
第二天不加任何东西，拿一个手上真实的小改动，从头到尾走一遍。挑几个 minimal 已经带进来的技能试：skills/tdd-workflow 和 skills/verification-loop 都在 workflow-quality 模块的路径清单里，覆盖先写测试和收敛验证两段；skills/context-budget 处理上下文预算；skills/codebase-onboarding 适合拿一个你不熟的仓库开局。
这里要先堵一个常见的误装。网上被推荐得比较多的 skills/search-first（写代码前先找现成方案的流程，它的第 0 步是工具可用性预检：仓库搜索、包管理器、GitHub CLI、MCP 与文档工具、本地技能目录逐项确认，某个通道用不了就如实声明只看了哪些范围，而不是含糊带过）并不属于 workflow-quality，它归在 agentic-patterns 模块下，minimal 装完是没有这个目录的。第二天不建议为它单独破例加模块——先把手边已有的几个跑熟，你才有基准判断后面加进来的东西到底带来了什么。
这一天的目的是校准期望值。这些技能本质上是结构化的提示与流程约定，不是运行时程序——skills/agent-sort 的写法就很典型，它要求每一条 DAILY 分类都必须引用仓库里的具体证据（文件扩展名、锁文件、框架配置、CI 配置、构建测试脚本、依赖清单），而不是凭感觉。你能从中拿到的是流程纪律，不是自动化魔法。分不清这两者，第三天加钩子的时候你会把所有不如预期都归咎于配置。
上下文这块的通用取舍可以对照站内的 Agent 上下文预算怎么定，那篇讲的是预算方法本身，这里只强调一点：ECC 的 README 把自己的原则写成”优化上下文窗口，其余全部持久化”，规则、技能、钩子输出三者都在抢同一份预算。
四、第三天：接钩子运行时，同时先学会关它
钩子是这套东西里唯一会往你机器上持续写文件、拦截命令、拉起后台进程的部分，也是收益最直接的部分。加法是单独装模块：
./install.sh --target claude --modules hooks-runtime
hooks/README.md 反复强调不要把仓库里的 hooks/hooks.json 原样贴进 ~/.claude/settings.json 或直接拷到 ~/.claude/hooks/hooks.json——那份文件是面向插件和仓库的，路径没有解析过，必须走安装器改写成你本机的实际根目录。如果你已经是插件安装，README 更是明说较新的 Claude Code 会自动加载插件里的 hooks/hooks.json，再往 settings.json 里复制一份会导致重复执行和跨平台冲突。
真正要提前掌握的是关的方式。scripts/lib/hook-flags.js 里的逻辑很简单：ECC_HOOK_PROFILE 取 minimal、standard、strict 三档，默认 standard；ECC_DISABLED_HOOKS 是逗号分隔的钩子 ID 列表，命中就直接禁用。hooks/README.md 给的例子是 ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"。三档的语义也在同一份文档里：minimal 只保留必要的生命周期和安全钩子，standard 是平衡的质量加安全检查，strict 打开更多提醒和更严的护栏。
第三天的正确姿势是先 ECC_HOOK_PROFILE=minimal 跑一天，确认没有东西挡你的路，再升到 standard。因为这里面有会真正阻断的钩子：hooks/README.md 的表格里，开发服务器拦截器（对 Bash，把 tmux 之外的 npm run dev 一类命令拦下来）标注的退出码是 2，也就是硬阻断；提交前质量检查（对 Bash，在 git commit 前跑，检查暂存文件、带 -m 时校验提交信息格式、检测 console.log/debugger/密钥）标的是碰到严重问题退出码 2、其余情况退出码 0 只警告。表里其余多数条目都是退出码 0 的警告。TROUBLESHOOTING.md 里单列了一节讲开发服务器拦截器的误报，成因包括 heredoc 内容触发模式匹配、参数里带 dev 字样的非 dev 命令。
同一份文档还给了几个粒度更细的开关：ECC_GATEGUARD=off 在安装或恢复期间单独关掉 GateGuard，ECC_SESSION_START_MAX_CHARS 限制 SessionStart 注入的额外上下文字符数，ECC_SESSION_START_CONTEXT=off 彻底关掉这份注入，ECC_CONTEXT_MONITOR_COST_WARNINGS=off 保留上下文和作用域警告但压掉费率估算提示。GateGuard 按 README 的说法拦的是破坏性 shell 命令，包括 rm、带 force 或路径的 git checkout、以及破坏性的 find -exec。
钩子在 hooks/hooks.json 里覆盖 PreToolUse、PostToolUse、PostToolUseFailure、Stop、SessionStart、SessionEnd、PreCompact 七类事件，条目集中在 PreToolUse 和 Stop 两头。Stop 是每次响应结束后跑的收尾队列——console.log 审计、会话状态持久化、模式抽取、成本追踪标记、桌面通知都挂在这里；格式化和类型检查不在 Stop 上，它们是 PostToolUse 按 Edit 匹配触发的，你每编辑一次文件就跑一次。每一条都是一个 Node 子进程。这就是为什么第三天要先从 minimal 起步：你得先知道每次响应结束时机器上到底跑了什么。钩子机制本身的通用讲法在 Claude Code hooks 用法 那篇，这里只谈 ECC 的这套配置。
五、第一周先别碰的几样
manifests/install-modules.json 里定义了三十多个模块，下面这几类第一周不要动。
编排类。 orchestration 模块的描述是 worktree/tmux 编排运行时与工作流文档。它会引入多进程、多检出的并行执行模型，调试成本高，而且它解决的问题（多个 Agent 并行不打架）你第一周还遇不上。
运营与领域类。 operator-workflows 是连接外部应用的运营工作流（安装审计、账单操作、项目跟踪、Google Workspace 等），ito-compute 需要经过认证的外部算力接口，prediction-market-skills 带有受控的外部 API 访问。这几类的共同点是把外部服务凭据引进你的 Agent 环境，第一周你还没建立起判断哪些调用是必要的能力时，不要打开。
ECC2 相关面。 仓库根目录有个 ecc2/ 的 Rust 工程（带 Cargo.toml 和 rust-toolchain.toml），scripts/ecc.js 里也注册了 control-pane 子命令，说明写的是运行本地 ECC2 运营控制台。但仓库自己的开发笔记 WORKING-CONTEXT.md 里明确写着这条线在树内、能构建，却仍处于 alpha 而非 GA 阶段。既然维护者自己这么标注，第一周就当它不存在——你要评估的是这套配置层对日常编码有没有用，不是替一个还没定型的新运行时做小白鼠。
MCP 自动接入。 README 里写明 Claude 插件安装故意不自动启用 ECC 自带的 MCP server 定义。这个默认值是对的，别急着改。the-shortform-guide.md 里那段关于 MCP 数量的经验值也值得记：配置里放着一批，但保持启用的是少数，否则工具定义会吃掉相当一部分本来能用于任务的上下文。
full profile。 它的描述就是”装上当前所有已分类模块”，会把上面这几类连同 swift-apple、machine-learning、supply-chain-domain、document-processing 这些跟你手上仓库多半无关的领域包一并拉进来。顺便纠正一个容易想当然的点：manifests/install-modules.json 里另有一批多语种翻译文档模块（docs-zh-cn、docs-ja-jp 等），它们不在 full 的模块列表里，要装得自己用 --modules 点名——所以”装了 full 就等于装了全部”这个印象本身就不准。除非你在做仓库本身的贡献，否则没有理由第一周走 full 这条路。
六、边界与代价：它明确不管什么
这套东西的设计取向在文档里表达得挺一致，值得如实写出来。
它不提供运行时保证。WORKING-CONTEXT.md 里对新增技能的描述用了”刻意做成指导优先而非假的运行时自动化”这样的措辞，说的是捕捉失败状态、归类模式、执行最小的收敛动作，然后交接出去。换句话说，多数技能的产出是流程和判断，执行仍然落在模型身上。你要的如果是确定性的流水线，这里给不了。
它会在你的机器上留下痕迹。钩子运行时会写解析后的 ~/.claude/hooks/hooks.json，会话与观测数据会落盘——TROUBLESHOOTING.md 排查记忆持久化失败时让你去检查 ~/.claude/homunculus/projects/*/observations.jsonl 是否在记录。这些是本地文件，但它确实是”往你的开发机写东西”，而且是持续写。介意的话，第一周就把钩子那部分放到项目级而不是用户级。
它对叠装不宽容。README 用了整整一节讲”每个 harness 只选一条安装路径”，并给出重复安装后的补救入口。这套设计的代价是：你没法像装 npm 包那样随手多试几种装法。
它不适合的场景也比较明确。没有原生钩子和技能发现机制的对话式工具，仓库提供的是 docs/MANUAL-ADAPTATION-GUIDE.md 这样一份手工适配说明，README 对它的定位是把少量技能和工作流指令带过去，而不是假装那边也有钩子和原生技能发现。所以如果你的主力工具不在支持列表里，你拿到的会是一份写作规范，不是一套运行系统。
七、上手与避坑清单
别把插件装法和手工完整安装叠起来。 会踩是因为两条路径都能”装成功”，没有报错提示你重复了。避法是一开始就写下你选的是哪条，插件路径就只跑 /plugin install ecc@ecc 加手动拷规则；发现已经叠了，走 README 的 Reset / Uninstall 一节，node scripts/ecc.js doctor 和 node scripts/ecc.js repair 先诊断修复，node scripts/ecc.js uninstall --dry-run 先看清要删什么再真删。
别把 rules/ 整个拷过去。 会踩是因为拷贝命令写起来只差一个通配符，而规则是常驻加载的，多拷十个语言包不会报错，只会安静地吃掉上下文。避法是只拷 rules/common 加你实际在用的那一个语言目录，而且要整目录拷（README 提醒按目录拷才能让相对引用继续有效、文件名不撞车）。
别第一天就开 standard 档钩子。 会踩是因为阻断型钩子的误报往往出现在你最赶的时候——一个带 dev 字样的命令被拦，或者提交被质量检查挡住。避法是先 ECC_HOOK_PROFILE=minimal，把具体添堵的条目用 ECC_DISABLED_HOOKS 按 ID 关掉，再升档。
别信仓库里任何一份状态快照文件的数字。 会踩是因为这类文件看起来很权威。实际上 WORKING-CONTEXT.md 里记的目录数量与 README 现在写的对不上——前者是当时那个 sprint 的快照，后者跟着仓库走。避法是需要确切数量时自己 ls agents | wc -l 数一遍，别引用文档里的历史数字。
别跳过 list-installed。 会踩是因为装的时候一切顺利，没人想到留退路；等到某天要换机器或者要排查冲突，你不知道哪些文件是这套东西写的。避法是每次安装或加模块之后跑一次 node scripts/ecc.js list-installed，这份 install-state 也是卸载能干净执行的前提。
先用顾问命令再决定加什么模块。 会踩是因为二十多个模块名字都挺像那么回事，看名字选很容易多选。仓库提供了 npx ecc consult "security reviews" --target claude 这样的查询方式，返回匹配的组件、相关 profile 和预览/安装命令；也支持 ./install.sh --target claude --skills tdd-workflow,security-review 这种点名到技能的装法。先预览文件计划，再决定。
跨 harness 之前先看目标说明。 会踩是因为 README 的表格里各 harness 的默认 profile 并不相同，比如 OpenCode 需要先构建插件载荷再走完整安装，多数其他 harness 走的是 minimal 加项目级适配目录。照抄 Claude Code 那套命令过去大概率不对。
收束：第一周结束时的自检
按顺序回答这七个问题，能全部答上来，说明这一周没白装：你走的是插件路径还是手工路径，只有一条吗；~/.claude/rules/ecc/ 下有几个目录；node scripts/ecc.js list-installed 输出里有多少条是你认得的；ECC_HOOK_PROFILE 现在是哪一档，ECC_DISABLED_HOOKS 里有哪些 ID；有没有哪个阻断型钩子在这周挡过你，挡的是什么；orchestration、operator-workflows、ito-compute 这几个模块是不是还没装；卸载命令你跑过 --dry-run 没有。
接下来该读的文件按这个顺序：manifests/install-profiles.json 和 manifests/install-modules.json 看清可选面，hooks/README.md 看清每个钩子的匹配器和退出码，TROUBLESHOOTING.md 提前认识常见误报，最后才是 the-shortform-guide.md 和 the-longform-guide.md 那两份长文——它们讲的是作者的整体工作方式，先有了实际配置再读，收获会大得多。至于技能到底该怎么组织、什么时候该拆成独立能力，可以对照站内的 Claude Code Skills 怎么写。
本文属于 ECC 开源 Agent 套件专题（共 40 篇，从选择性安装一直拆到内部机制）。同一批还写了另一种取向的项目——不给你资产、只给你纪律的 superpowers 方法论专题。