ECC 使用指南：装了什么、哪些机制真的在跑、哪些说法别照信

0030 秒速览：先记住三句话，再按处境挑一条路

读完这一篇，你能做三个判断：这套东西该不该装、装哪一条路、以及哪些功能你以为装上了其实没在跑。下面三句是主心骨，后面每一节都在给它们补细节。

按你现在的处境，直接照这张表走

最小上手路径：五步，十分钟

读完你应该能

• 说清它是什么：给你的 AI 编程助手（harness）加装的一套工程制度，由文件、角色和钩子组成，不碰模型本身。
• 选对安装路径：知道四条路各自适用谁，以及为什么同一个助手只能走一条。
• 分清软硬：知道 292 个技能 / 122 个规则是「请求模型遵守」，24 条钩子才是「模型不遵守也得停」。
• 预判最常见的三个翻车点：钩子被装两遍、技能被嵌套安装导致一个都不生效、把「持续学习」当成开箱即用。
• 自己核对官方数字：拿到一组命令，能在 clone 出来的仓库上把 292 / 68 / 94 / 122 / 24 这些数逐个数一遍（19）。

关键数字先给量级

这些数字都是我在 2026-09-13 把仓库完整文件树取下来逐个数的，每个都配了核对方式，写在 05 与 19。

01它到底是什么：不是提示词合集，是装在助手外面的一套制度

先把最容易错的那一步说清楚：ECC 不是「一大包提示词」，也不是某个模型或某个命令行工具。它是一个装在你现有 AI 编程助手旁边的目录集合——装完之后，你的 Claude Code / Codex / Cursor 里会多出一些技能、专家子代理、钩子和规则文件。这里先解释两个马上要用到的词：harness 指承载模型的编程助手外壳（Claude Code、Codex、Cursor、OpenCode 都是），模型指真正生成文字的那部分大脑；ECC 完全工作在 harness 这一层，不训练也不代理模型。

它自己的定位原话是（README.md:127，逐字抄自官方仓库）：

Your agent can write code, but ECC gives it a coordinated engineering
system and toolbox: it plans before it builds, verifies changes with tests,
reviews its own work from a fresh context, remembers what matters, and turns
repeated wins into reusable skills and workflows.

换成中文：它补的不是「模型会不会写代码」，而是「模型写完代码之后有没有制度约束」。模型本来就能写代码，问题在于它容易把计划丢在聊天记录里、把测试留到最后、自己审自己的代码、每次会话从零开始。ECC 的做法是把这些环节外化成文件与钩子——计划变成磁盘上的 *.plan.md 文件，测试先变红才有资格改生产代码，复核交给一个新上下文的子代理，质量检查交给钩子而不是靠模型记性。

它不是什么（先做一遍负向定义）

• 不是模型：它不训练、不微调，也不代理你的接口调用。你用哪个模型它不管——官方明确说钩子、技能、命令、规则都与模型供应商无关。
• 不是一堆常驻服务：它曾经捆绑 6 个默认 MCP 连接器，2026 年 6 月审计后砍到只剩 1 个（chrome-devtools）。MCP 在这里指一种让助手调用外部工具的插件协议，你可以先理解成「给助手插的外设」。现在的 ECC 主体是纯文本与 Node.js 脚本。
• 不是运行时框架：没有常驻进程、没有需要你装进项目的依赖树。安装的本质就是把文件放进你的助手目录。
• 不是只给 Claude Code 的，但也没到「处处功能对齐」：官方支持矩阵里只有 Claude Code 是稳定主力，Cursor / OpenCode 是测试版，GitHub Copilot 只有「指令文本」这一层（矩阵全文在 14）。

它的全部主张可以压成七个词

这条链在仓库里有一个更短的写法，出现在 README.md:130：

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

后面 06 会把这条链逐环拆开，说清每一环由哪个文件、哪个子代理、哪条钩子在真正兜底，以及哪几环其实只是「建议」。这里先记住一件事：ECC 的七成内容是在为这七个词服务，而不是在堆功能。

02三个名字，用错就装不上

这是新手第一天最容易踩的坑，而且官方专门写了一节解释它为什么不统一。三个名字指向同一个项目，但分别用在三个地方，互相不能替换：

官方对「为什么不统一」的解释很实在：npm 那边保持 ecc-universal 不动，是为了让包管理器安装与市场安装故意用不同的名字；插件侧用 ecc@ecc，是为了让工具名与斜杠命令的命名空间短到能通过严格的校验器。

还有一条关于版本号的口径

官方说明：npm 版本是按版本标签切的，不是按提交切的，所以 ecc-universal 跟的是发布版本（2.1、2.2……），而不是 main 分支上的每一次提交。你要「最新」就用 git 装；要「可复现」就钉死 @2.2.1。这两件事别混（16 的坑 4）。

03怎么装：四条路，每个助手只能选一条

官方在这个问题上罕见地强硬：不要叠加安装方式。原文逐字如下：

**Do not stack install methods.** Installing ECC twice into the same harness
can duplicate skills, commands, hooks, or configuration; installing it once
into multiple harnesses does not.

路一：包管理器向导（Claude Code 首选）

npx ecc-universal@2.2.1 setup

npm view ecc-universal version

pnpm dlx ecc-universal@2.2.1 setup
yarn dlx ecc-universal@2.2.1 setup      # 需要 Yarn 2 及以上
bunx ecc-universal@2.2.1 setup

路二：多助手向导（一次配好 Claude Code + Codex + Kimi）

npx ecc-universal@2.2.1 install --guided

它让你选任意组合，先展示每个目标的安装通道与落地目录，并在第一次写盘之前做预检，最后只问一次总确认。三个目标在向导里的行为并不一样：

自动化场景把所有选择显式写出来：

npx ecc-universal@2.2.1 install --guided \\
  --harness claude --harness codex --harness kimi \\
  --claude-scope local --claude-hooks standard \\
  --profile core --yes

想先看不落盘的结果，加 --dry-run：

npx ecc-universal@2.2.1 install --guided --harness codex --dry-run
npx ecc-universal@2.2.1 install --profile core --target kimi --dry-run

按下回车之后，磁盘上到底发生了什么

答案不是「把仓库复制到 ~/.claude」，而是三层结构：① install.sh 自己不装任何东西，它的头注释写着自己只是「旧版入口」，实际动作是把参数交给 scripts/install-apply.js（顺带处理 Windows 路径转换）；② manifests/ 里的 JSON 声明「源路径」（实测 37 个模块 / 7 个档位 / 84 个组件），再给每个平台一个适配器，把源路径翻译成「目标路径 + 策略」；③ 装完之后写一份 install-state，记住自己写了哪些文件。

这套设计里最值得记的推论是：卸载只删 install-state 里属于 ECC 的文件（官方原话："ECC only removes files recorded in its install-state. It does not claim unrelated files in your harness directories."）。反过来也成立——你手抄进 ~/.claude/rules/ 的文件 ECC 不知道也不管，卸载时必须自己删。

选了 Codex 的话，还有一套原生命令

Codex 这一路除了走向导，也可以直接在 Codex 命令行里装（这两条命令是幂等的，重复跑不会出问题）：

codex plugin marketplace add affaan-m/ECC
codex plugin add ecc@ecc
codex plugin list --json
node scripts/codex/check-plugin-cache.js

# 以后刷新：先升级市场，再重新 add
codex plugin marketplace upgrade ecc
codex plugin add ecc@ecc

两点差异要记住：Codex 没有 Claude 那套「用户 / 项目 / 本地」作用域（它只存一份启用状态），而且它的原生钩子需要你显式信任，不走 Claude 的四档钩子档位。旧的 scripts/sync-ecc-to-codex.sh 同步流已经降级为兼容选项，只有你确实需要「把配置拷进 ~/.codex 并合并」时才用它。

路三：在 Claude Code 里敲原生插件命令

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

这条路的边界要说清：这两条命令是 Claude Code 自带的，报错也归它管——市场已存在、作用域冲突这类错误 ECC 拦不到，只能自己解决冲突后再试，不要在同一份配置上再叠一次手动安装。

如果你更习惯改配置文件，可以声明式地写进 ~/.claude/settings.json，效果与上面两条命令相同：

{
  "extraKnownMarketplaces": {
    "ecc": {
      "source": { "source": "github", "repo": "affaan-m/ECC" }
    }
  },
  "enabledPlugins": { "ecc@ecc": true }
}

路四：源码 / 手装（其余助手走这条）

先克隆仓库，再按目标选。下面是官方 README 里逐个目标给出的命令（我原样抄下来，你按自己用的那行取一条）：

git clone https://github.com/affaan-m/ECC.git
cd ECC

./install.sh --profile minimal --target cursor        # 项目里的 .cursor/
./install.sh --profile minimal --target gemini        # 项目里的 .gemini/
./install.sh --profile minimal --target zed           # 项目里的 .zed/
./install.sh --profile minimal --target antigravity   # 落到 .agents/，不是 .antigravity/
./install.sh --profile minimal --target qwen          # ~/.qwen/
./install.sh --profile minimal --target hermes        # ~/.hermes/
./install.sh --profile minimal --target openclaw      # ~/.openclaw/
./install.sh --profile minimal --target kimi          # 项目里的 .kimi-code/
./install.sh --profile minimal --target codebuddy     # 项目里的 .codebuddy/
./install.sh --profile minimal --target joycode       # 项目里的 .joycode/
./install.sh --profile minimal --target opencode      # 见下方注意事项

./install.sh --profile full                           # 完整手装（Claude）
.\\install.ps1 --profile full                          # Windows 对等物

装之前先决定：要不要钩子

装钩子这件事是一条同意闸门，不是默认行为。任何会让钩子运行时被装到磁盘上的选择，都必须给出一个明确决定：

# 要钩子：显式打开
./install.sh --target claude --modules hooks-runtime --enable-hooks

# 不要钩子：显式关掉（两种写法等价）
./install.sh --profile core --without baseline:hooks --target claude
./install.sh --profile core --no-hooks --target claude

# 低上下文起步：minimal 档位故意不含钩子运行时
npx ecc-universal@2.2.1 install --profile minimal --target claude

没给这两个开关时，安装器会先把钩子能干什么打印出来，然后停下，不写任何文件。多助手向导会交互式地问你这个选择。

Windows 上的一条对等命令

pwsh -File .\\install.ps1 --target claude --modules hooks-runtime --enable-hooks

Windows 上 Claude 的配置根目录是 %USERPROFILE%\\.claude。

允许与禁止的组合（官方原表）

装错了怎么退：先诊断，再修，最后才卸

ECC 对「装了两遍」给出的处理顺序不是重装，而是先看它自己认为装了什么：

npx ecc-universal@2.2.1 list-installed    # 先看它认为自己装了什么
npx ecc-universal@2.2.1 doctor            # 体检
npx ecc-universal@2.2.1 repair            # 修（通常不需要重装）
npx ecc-universal@2.2.1 uninstall --dry-run
npx ecc-universal@2.2.1 uninstall

源码检出的对等命令是 node scripts/ecc.js list-installed / doctor / repair / uninstall，直接卸源码那份则用 node scripts/uninstall.js --dry-run 与 node scripts/uninstall.js。--dry-run 是全局旗标（几乎所有子命令都能加），作用是把计划打印出来但不写盘。

如果你确实叠加装过，官方给的清理顺序是四步：先移除 Claude 插件安装，再从装过的那份受管状态所在目录跑卸载命令，然后自己删掉手工拷过、现在不要的规则目录，最后只用一个路径重装一次。

04装完怎么知道它在干活：三层验证，第三层最能说明问题

「装完了」和「在干活」是两件事。区别在于：技能和规则是请模型遵守的建议，模型不理它们你也看不出来；只有钩子是外部程序，它有没有跑，可以用一次故意违规来验证。

第一层：看插件状态

/plugin list ecc@ecc

这一步回答「装上了没有、装在哪个作用域」。如果这里就是空的，后面两层不用看了，回到 03 检查你是不是叠加安装或装错了作用域。

第二层：体检 + 看它认为自己写了什么

npx ecc-universal@2.2.1 list-installed
npx ecc-universal@2.2.1 doctor

list-installed 打印的是它记录的受管文件清单（这份清单的文件名是 install-state，见 05 里的解释）；doctor 检查安装状态与钩子配置是否对得上。两者不一致时，先 repair，不要直接重装。

第三层：故意撞一次闸门

这是唯一能证明「钩子真的在跑」的办法，因为它不依赖任何人的自我报告。挑一条已知会被拦的行为，看它是否真的被拦下：

三条里任一条被拦下，说明钩子这层是活的。三条都没反应，就按 16 的坑 1、坑 2 排查：多半是钩子被装了两遍（反而冲突），或者你装的是 minimal 那种故意不含钩子的档位。

顺手记下装完之后从哪儿看钩子的档位

export ECC_HOOK_PROFILE=standard      # off | minimal | standard | strict，默认 standard
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
export ECC_SESSION_START_MAX_CHARS=4000   # 默认 8000
export ECC_SESSION_RETENTION_DAYS=14      # 默认 30；设 0 / off 表示不清理
export ECC_SESSION_START_CONTEXT=off       # 完全关掉会话开始时的附加上下文

这几条环境变量的细节、以及插件里对应的开关（hooks_enabled、hook_profile），在 07 展开。

05装完多了什么：五件套实测盘点

ECC 把自己的内容分成五类。下面每个数字都是我在 2026-09-13 取下的完整仓库文件树上实际数出来的，核对命令一并给出，你可以自己复核：

先接受一个反直觉的前提：多不是优点

这些数字和官方文档对不上，差在哪

光「有多少个技能」这一个问题，官方同一时期的材料里就有五个答案。我把它们并列出来，因为它示范了这类项目该怎么读文档：

结论不是「它在骗人」，而是：同一份仓库里同时存在历史数字、发布基线数字和分支现状数字，而它们都长得像「当前值」。所以本文一律用 目录数 作口径——它是唯一能由你自己复现的一种：官方数字随文档更新漂移，而 find | wc -l 不会。这也是 14 那几种说法能站得住的原因：它们全是文件系统的可复核事实，不是观点。

06核心闭环七个环节：哪一环是硬的，哪一环只是建议

plan → test → implement → review → verify → remember → improve 这七个词是 ECC 的骨架。下表把每一环对应到具体文件 / 角色，并标出它是硬的还是软的——这张表能回答很多营销话术回答不了的问题。

它还有一条更长的流水（orch-pipeline）

仓库里另有一套更正式的工作流引擎（skills/orch-pipeline/SKILL.md），把上面这条链扩成七个阶段、两个人工闸门：

0 Intake → 1 Research & Reuse → 2 Plan (→ GATE 1) → 3 Scaffold
→ 4 Implement (TDD) → 5 Review → 6 Commit (→ GATE 2)

五个薄封装（orch-add-feature、orch-change-feature、orch-fix-defect、orch-refine-code、orch-build-mvp）按「改动面积 / 新依赖 / 设计歧义」把任务分成 trivial / small / standard / large 四档，再决定跑哪几个阶段——它承认「小改动不该走完整流程」，这比一刀切的流程实用。

07hooks：唯一能物理拦住模型的部件

如果只能记住 ECC 的一个部件，我建议记钩子。原因很直接：技能与规则是「请模型遵守」，钩子是「模型不遵守也得停」。官方定义原文（hooks/README.md）：

Hooks are event-driven automations that fire before or after Claude Code tool
executions. They enforce code quality, catch mistakes early, and automate
repetitive checks.

它是怎么回事：模型每动一次手，外面就有人看一眼

钩子不是模型的一部分，而是harness 在调用工具前后去执行的外部程序。这里「工具」指模型能发起的动作——读文件、改文件、执行命令都算。所以钩子能做一件提示词做不到的事：它可以让这次动作失败。这就是「物理」两个字的含义：不是劝，是拦。

实测结构：7 类事件、24 条条目

结构上还有一个细节值得知道：钩子在 hooks.json 里是内联的 node -e "..." 单行脚本，本体只是一层薄壳，真正的逻辑在 scripts/hooks/ 的 53 个文件里。被引用最多的两个入口是转发器 run-with-flags.js（20 次）与 plugin-hook-bootstrap.js（14 次）。

它们到底拦什么：三个真实例子

设计意图在这些脚本的注释里写得很直白（config-protection.js 开头，逐字）：

* Blocks modifications to linter/formatter config files.
* Agents frequently modify these to make checks pass instead of fixing the
  actual code. The hook steers the agent back to fixing the source.

翻成中文：模型经常去改静态检查配置来让检查通过，而不是真去修代码——这条钩子就是把这条路堵掉。同理，block-no-verify.js 的存在理由被它自己写在注释里：防止 AI 代理跳过提交前检查的钩子。

四档严格度与开关

插件安装时对应两个选项：hooks_enabled（布尔，默认开）与 hook_profile（默认 standard，非法值安全回退到 standard）。源码检出方式则用环境变量：

export ECC_HOOK_PROFILE=standard      # off | minimal | standard | strict
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
export ECC_SESSION_START_MAX_CHARS=4000   # 默认 8000
export ECC_SESSION_RETENTION_DAYS=14      # 默认 30；0/off 表示不清理会话临时文件

MCP 也要单独管：别一次全开

MCP 在这里指一种让助手调用外部工具的插件协议；每个 MCP 都会把自己的工具清单塞进模型能看到的上下文里，所以它是开销最大的一类插件。官方给的经验线是每个项目 MCP 少于 10 个、活跃工具少于 80 个，并且明确提醒：全开会把 20 万 token 的窗口压到约 7 万。

「ECC 有多少条钩子」为什么没有唯一答案

顺带把「省 token」的那份配置也核一遍

官方建议改 ~/.claude/settings.json 里的三处：

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

两条比百分比更有用的硬建议：① MCP 是上下文重灾区——每个项目少于 10 个、活跃工具少于 80 个；② 压缩要看时机——strategic-compact 技能建议在逻辑断点上压，并明确列出不要压的时候（实现到一半时压缩，你会丢掉变量名、文件路径和半截状态）。

08agents：把脏活扔出主上下文，只把结论拿回来

# 直接点名（Claude Code 中的常见写法）
/ecc:plan "Add user authentication with OAuth"   # → planner
/code-review                                # → code-reviewer
/build-fix                                  # → build-error-resolver

---
name: code-reviewer
description: Expert code review specialist. ... MUST BE USED for all code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

它还带一个社区工具桥：multi-* 命令与 ccg-workflow

仓库里有五条名字带 multi- 的命令：/multi-plan、/multi-execute、/multi-backend、/multi-frontend、/multi-workflow。它们不在基础安装范围内——要让它们跑起来，你得另外装第三方运行时 ccg-workflow 并初始化它，这些命令依赖的外部文件包括 ~/.claude/bin/codeagent-wrapper 与 ~/.claude/.ccg/prompts/*。

# multi-* 五条命令的前置：必须另外装并初始化 ccg-workflow（上游安装指南在 README 里给了链接）
# 缺少它时，这五条命令不会正确运行
ls ~/.claude/bin/codeagent-wrapper ~/.claude/.ccg/prompts/   # 自查这两个外部依赖在不在

09skills：默认工作流面，但 292 个不是安装清单

# 方式一：让模型按 description 自己选（推荐，默认就是这样）
# 方式二：手动点名一个技能目录
./install.sh --target claude --skills tdd-workflow,security-review
# 方式三：先问顾问该装哪些
node scripts/ecc.js consult "security reviews" --target claude
# 按能力装（2.2 新增的写法）
node scripts/ecc.js install --profile minimal --target claude --with capability:machine-learning

「按语言精确装」这个粒度目前是假的

官方文档建议用 --with lang:python 这样按语言装。但清单文件 manifests/install-components.json 里，19 个语言 / 框架组件的 modules 字段全都指向同一个 framework-language 模块——它们的描述里自己写着 "Currently resolves through the shared framework-language module"。

# 这两条命令装出来的东西是一样的——不是 bug，是清单还没拆开
./install.sh --profile minimal --target claude --with lang:python
./install.sh --profile minimal --target claude --with lang:typescript

少数例外已经开始拆：lang:swift 指向独立的 swift-apple，framework:quarkus、lang:perl、lang:ruby、framework:rails、framework:laravel 额外挂了 security。结论：别指望用 --with lang:* 做精确裁剪，要精确就用 --skills 点名。

10rules：总是占着上下文，而且插件给不了你

规则是总是加载的标准——这是它与技能最本质的差别，也是它数量少一个数量级的原因（122 vs 292）。结构很规整：

每个语言目录通常是 5 个文件（coding-style / hooks / patterns / security / testing），例外是 python（6）、web（7）、react-native（8）。

git clone https://github.com/affaan-m/ECC.git
cd ECC
mkdir -p ~/.claude/rules/ecc
cp -R rules/common ~/.claude/rules/ecc/
cp -R rules/typescript ~/.claude/rules/ecc/   # 换成你自己的技术栈

只想管住一个仓库：把规则拷进项目

cd your-project
mkdir -p .claude/rules/ecc
cp -R /path/to/ECC/rules/common .claude/rules/ecc/
cp -R /path/to/ECC/rules/typescript .claude/rules/ecc/

手动拷技能与命令（不想走安装器时）

每个组件都被设计成互相独立，所以你也可以只拷自己要的那一块：

# 只拷 agents
cp agents/*.md ~/.claude/agents/

# 技能：Claude Code 只发现 ~/.claude/skills 的直接子目录，所以不要嵌套
mkdir -p ~/.claude/skills
cp -r .agents/skills/* ~/.claude/skills/
cp -r skills/search-first ~/.claude/skills/

# 命令（迁移期的斜杠入口兼容层，可选）
mkdir -p ~/.claude/commands
cp commands/*.md ~/.claude/commands/

手动拷贝时的一条硬规矩

官方专门写了一条：拷整个语言目录，不要拷目录里的单个文件，否则相对引用会断、文件名会撞。这条看起来琐碎，但它解释了为什么 rules/ 的单位是「目录」而不是「文件」。而且因为规则是每次都吃上下文的常驻成本，官方建议从 common 加一个你真正在用的包开始，别一口气全拷。

11最小例子：给已有项目加「用 OAuth 登录」

不讲概念了，走一遍最小可用流程。场景：你有一个已有项目，要加一个 OAuth 登录（OAuth 是一种「不把密码交给第三方、而是跳转去授权」的登录方式）。ECC 装好了，钩子是 standard 档。

Do not edit production code until this RED state is confirmed.

这条流程在官方文档里有一段一模一样的流水，可以直接对照：

/ecc:plan "Add usage-based billing alerts"
  -> confirm or edit the plan
  -> activate tdd-workflow
  -> capture RED evidence before implementation
  -> implement until GREEN
  -> review from fresh context
  -> fix findings with regression tests
  -> verify build, lint, types, and tests

同一件事的入口速查：你现在想干什么

插件的命令用带命名空间的形式（/ecc:plan）；手动安装有时会暴露更短的兼容形式（/plan）。不确定装了哪些，用 /plugin list ecc@ecc 看。

12instincts：把你纠正过它一次，变成下次自动生效

这是 ECC 最有辨识度、也最容易被误解的机制。先说结论：它设计得很讲究，但开箱是关闭的，而且文档里 v1 / v2 两代并存。三层都讲清。

instinct 可以直译成「本能」：它不是规则、也不是技能，而是一条带置信度的小行为约定，由系统在你干活的过程中观察出来、写上置信度、下次会话开始时按置信度挑几条塞进上下文。

一条 instinct 长什么样

它是「一段元数据 + 一段正文」，正文里必须有 ## Action（没有的话会在注入阶段被丢掉）。下面是仓库里唯一一份真实数据文件中的一条（逐字）：

---
id: everything-claude-code-conventional-commits
trigger: "when making a commit in everything-claude-code"
confidence: 0.9
domain: git
source: repo-curation
source_repo: affaan-m/everything-claude-code
---

# Everything Claude Code Conventional Commits

## Action

Use conventional commit prefixes such as `feat:`, `fix:`, `docs:`, `test:`,
`chore:`, and `refactor:`.

## Evidence

- Mainline history consistently uses conventional commit subjects.
- Release and changelog automation expect readable commit categorization.

这个文件里一共 8 条 instinct（按行首的 id: 数就是 8）：领域分布是 workflow ×4、git ×2、code-style ×1、testing ×1，置信度区间 0.8–0.9。但有一条很关键：8 条全部是 source: repo-curation——也就是人工写的，不是「会话里学出来的」。这一点值得单独记住，因为它说明了这个机制的现实形态。

闭环四步

四个步骤的关键参数（都能在 README 的环境变量表里核对）：

• 注入阈值：confidence ≥ 0.7（环境变量 ECC_INSTINCT_CONFIDENCE_THRESHOLD），最多注入 6 条（ECC_MAX_INJECTED_INSTINCTS），且只注入 ## Action 的第一行——为了省上下文。
• 排序不是纯置信度：分数 = 置信度 + 加成，项目作用域加、技术栈命中也加。注释里给了理由：这样「本项目 0.7 的本能」能压过「别处 0.9 的无关本能」。可用 ECC_INSTINCT_RELEVANCE_RANKING=off 关掉。
• 置信度怎么涨跌（观察者角色定义里的原文数值）：观察 1–2 次给 0.3、3–5 次 0.5、6–10 次 0.7、11 次以上 0.85；此后每次确认 +0.05、被反驳 −0.1、每周没被观察到衰减 −0.02。
• 项目隔离：v2.1 起 instinct 默认项目作用域，存到 ${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects/<项目哈希>/；只有在两个以上项目里都出现、且均值 ≥ 0.8 时才通过 /promote 升为全局。待定状态的 instinct 还有 30 天保质期。

13memory：一份「是背景资料、不是指令」的记忆库

ECC 里有两套记忆，第二套是 memory vault（可以理解成「一个只往里存事实、不往里存命令的档案柜」）。它和 instincts 的分工可以一句话概括：instincts 记「怎么做事」，memory 记「发生了什么、决定了什么」。设计文档自己用的说法（docs/design/ecc-memory-vault.md，逐字）：

- A memory is context, not an instruction.

其余约束：记忆种类 8 种（context / decision / fact / handoff / lesson / note / preference / runbook），作用域 3 种（project / team / user，默认检索只覆盖 project + team），状态 3 种（active / rejected / superseded）。写入前会跑 10 条密钥正则（OpenAI sk-、Stripe、npm、HuggingFace、GitHub gh[pors]_、Google AIza、Slack xox*、AWS AKIA/ASIA、PEM 私钥）——命中就拒绝写入。正则在这里就是「按模式匹配的一段规则」，你可以理解成查重用的模板。

MCP 在这里的角色：只是一个读写口，不是通道

scripts/memory-mcp.mjs 是一个手写的标准输入输出服务（669 行、零框架），只暴露 4 个工具：memory_save、memory_search、memory_read、memory_doctor。设计文档用一句话锁死了它的边界："It has no review or promotion tool."

还有一条实用信息：它默认不启用——根目录 .mcp.json 只声明了 chrome-devtools 一个，而 mcp-configs/mcp-servers.json 里那一条的说明直接写着 Not enabled by default.（我 2026-09-13 核对，两处都仍是如此）。

14四种说法我核对不上，实测是什么

这一节示范怎么用可复核的方式检验一个项目的宣称：把文档里的每个说法都拿去仓库或注册表里数一遍。八条旧发现逐条重核后，四条仍然成立，四条已修掉或换了形态。

仍然对不上的四条

第 4 条牵涉它最核心的一条自述，所以我把官方原文逐字抄在这里，你可以直接对着看：

The root is the source of truth. Platform adapters package or map these same
workflows instead of maintaining separate copies.

已经修掉或换了形态的四条

把这四条自己验一遍的命令

git clone --depth 1 https://github.com/affaan-m/ECC.git && cd ECC

# 1) 技能数：数目录，不数文档里的字
find skills -mindepth 2 -maxdepth 2 -name SKILL.md | wc -l

# 2) Cursor 三个数：规则文件、钩子事件、有没有 48 个子代理
find .cursor/rules -type f | wc -l
python3 -c "import json;print(sorted(json.load(open('.cursor/hooks.json'))['hooks']))"
find .cursor -name '*agent*' | wc -l

# 3) MCP 与 .agents/skills 的真实数量
python3 -c "import json;print(list(json.load(open('.mcp.json'))['mcpServers']))"
find .agents/skills -name SKILL.md | wc -l

# 4) 「不维护副本」是否成立：源与副本逐目录比对
for d in .agents/skills/*/; do n=$(basename $d); diff -q "$d/SKILL.md" "skills/$n/SKILL.md" >/dev/null 2>&1 || echo "不同: $n"; done

# 5) 版本：注册表才是事实
npm view ecc-universal version time.2.2.1

15安全：它把自己当攻击面，也承认自己不是沙箱

ECC 的安全观有一句很像样的话（官方 README，逐字）：

Hooks can run shell commands, MCP servers can hold credentials, and project
instructions can enter an agent's context. Treat all three as executable
configuration.

中文：钩子会执行系统命令、MCP 服务器会存凭据、项目说明会进上下文——这三样都应当当成「可执行配置」对待。这句话的意思是：装了 ECC 之后，你机器上多了一份会被执行的配置，它和代码一样需要被审视。

它提供了四层防线，但只有一层能真的拦

三处「看着像控制、其实不是」

• 仓库里有 .gitleaksignore，但没有任何流程调用 gitleaks。（gitleaks 是一个扫描仓库、防止把密钥误提交进去的工具。）我实测：.github/workflows/ 下 12 个 workflow、scripts/ 与 package.json 里对 gitleaks 的引用是零；那份 ignore 文件里只有一条「文档中的示例 API key」的豁免。它是一份没人执行的文件——就密钥扫描这件事，别把它算进 ECC 的能力。
• 提示层的防注入是散文，不是机制。CLAUDE.md 的 Prompt Defense Baseline（把 unicode、同形字、不可见字符、紧急感、权威声明，以及用户提供的工具或文档内容里夹带的指令都当可疑）写得确实到位，68 个子代理里也各带一份；但它的效力完全取决于模型是否遵守——这正是钩子存在的理由，也是这一层不该被当成防线的原因。
• the-security-guide.md 是一篇引用外部研究的科普长文，不是实现文档。想判断「ECC 到底防住了什么」，读代码比读它有用。

它自己对「安全工作」的定义很克制，这点值得学

关于 AgentShield 这个扫描器的运行器来源，官方写了一段罕见的诚实说明：这些命令要求你已经装好并审阅过的 AgentShield 二进制；要记录你选的版本、审阅过的源码与校验过的包完整性；仅仅「发在包注册表上」不等于经过审计，而且官方明说 "ECC does not supply an audited AgentShield pin here"——它不在这里给你一个已审计的版本锚点，也别用不带版本号的一次性下载代替。

漏洞响应流程也给的是具体承诺（SECURITY.md）：48 小时内确认、7 天内初步评估、影响受支持版本且跨真实信任边界时 14 天内给出关键修复或缓解；并明确要求报告里写清「利用是否需要本地 shell、恶意仓库、恶意包、远程未认证攻击者，还是维护者凭据」——按攻击路径分类，而不是笼统说「有安全问题」。

Candidate execution and staged gate runs are disabled: no actual OS
containment exists. Offline validation and a receipt signature do not
establish safe execution or promotion authority.

16八个坑，每个都给改法

坑 1：叠加安装方式

坑 2：插件装完再把钩子抄进 settings.json

坑 3：把技能嵌套安装

坑 4：指望「持续学习」开箱可用

坑 5：把仓库根当成发布版

坑 6：拿别人的技能数字当自己该装的量

坑 7：把 ECC 当沙箱

坑 8：以为「支持很多助手」等于功能等价

八个坑速查：症状 → 真因 → 改法

装乱了的标准修法（照顺序做）

# 1) 看它认为自己装了什么、体检、修
npx ecc-universal@2.2.1 list-installed
npx ecc-universal@2.2.1 doctor
npx ecc-universal@2.2.1 repair

# 2) 决定要卸：先看不写盘的后果
npx ecc-universal@2.2.1 uninstall --dry-run

# 3) 真卸（源码检出用 node scripts/ecc.js uninstall）
npx ecc-universal@2.2.1 uninstall

卸载只删它自己在 install-state 里记录过的文件；你手工拷进 ~/.claude/rules/ 的那些不在保护范围内，要自己删。官方给的叠加安装清理顺序是四步：移除插件 → 从受管状态所在目录跑卸载 → 删掉手工拷的规则目录 → 只用一个路径重装一次。

17你大概会问的六个问题

18术语对照表

19参考来源、我实测了什么、证据边界

用到的来源（都可点开复核）

• github.com/affaan-m/ECC——官方仓库（本文所有逐字引用与文件数字的来源；取数日 2026-09-13，取的是 main 分支的完整文件树，最新提交 8321021）
• npmjs.com/package/ecc-universal——官方 npm 包（版本历史与发布时间取的这里：latest = 2.2.1，发布于 2026-09-08）
• npmjs.com/package/ecc-agentshield——AgentShield 包
• ecc.tools——项目官网（README 里链接的定价 / Pro 页面入口）；GitHub 公开 API 的星标 / fork / 创建时间等统计，也取自这里（取数日 2026-09-13：星标 25.7 万、fork 3.8 万、仓库创建于 2026-01-18）
• 仓库内一手文档：README.md（2,012 行）、SECURITY.md、CHANGELOG.md、docs/ROADMAP.md、docs/token-optimization.md、docs/releases/2.2.1/patch-execution.md、hooks/README.md、skills/continuous-learning-v2/SKILL.md、skills/continuous-learning-v2/agents/observer.md、docs/design/ecc-memory-vault.md、manifests/install-*.json

我这次实测出来的东西（可自己复核）

• 目录计数：skills 292、agents/*.md 68、commands/*.md 94、rules/ 122、scripts/hooks/ 53、hooks.json 24 条条目 / 7 类事件、仓库总文件 3,716、schemas/ 13、legacy-command-shims/ 12 条命令、安装适配器 15 个。
• 自算数据：思考预算从 31,999 降到 10,000 的削减率是 (31999−10000)/31999 = 68.75%（文档写「~70%」——方向与量级都对，但略高）；docs/ 各语言目录的文件数（ja-JP 521、zh-CN 416、es 142、tr 142、ko-KR 64、zh-TW 58、pt-BR 47、de-DE 2，ru / th / uk-UA / ur / vi-VN 各 1）——语言栏里列了 13 种语言，其中 5 种只有一个文件。
• 清单级发现：--with lang:* 与 --with framework:* 里的 19 个组件全部指向同一个 framework-language 模块（只有 lang:swift 例外）；装卸策略实测 5 种（preserve-relative-path / flatten-copy / merge-json / merge-hook-ids / sync-root-children）。

99一句话总结