ECC（affaan-m/ECC）：GateGuard 事实强制门、四档保真度矩阵与三作用域记忆，把编码智能体的软约束换成硬闸门

一、导读

ECC（仓库 affaan-m/ECC，官网 ecc.tools）今日以单日涨星 1,183 进入 GitHub Trending daily 榜第 6，累计 290,802 星（GitHub REST API，2026-10-27 抓取），MIT 协议，主语言 JavaScript。本文不复述站内 9 月 21 日那篇已讲过的五层架构与 instinct 闭环，而聚焦 2.2.3 线（VERSION 为 2.2.3，CHANGELOG 标注 2.2.3 发布于 2026-10-01，另有大量 GateGuard 改动停在 Unreleased 段）真正新增的四件事：GateGuard 事实强制门、Context Profiles 只读提案层、Memory Vault 三作用域记忆、以及把「跨 harness 保真度」写成公开合规矩阵与 pi/core 离线裁剪档。核心结论：ECC 的价值重心已从「配置包够大」转向「把不可验证的软约束换成可验证的硬闸门」。

二、项目速览

项目	详情
仓库	`affaan-m/ECC`（官网 ecc.tools；Claude 插件标识 `ecc@ecc`；npm 包 `ecc-universal`）
维护模式	单人主导、每周发版（README 自述「ships weekly across 7 harnesses」）
主语言	JavaScript（Node.js CLI + 大量 Markdown 资产；另含 `ecc2/` 控制面原型）
Star 总数	290,802（GitHub REST API，2026-10-27 抓取）
当日涨星	+1,183（Trending daily，2026-10-27 页面，当日第 6）
License	MIT（仓库根 `LICENSE`；商业层 ECC Pro 为独立托管服务）
首次发布	2026-01-18（仓库创建）；最近推送 2026-10-27
当前版本	`VERSION` = 2.2.3；CHANGELOG 记录 2.2.3（2026-10-01）、2.2.2（2026-09-15）
组件规模	71 agents / 311 skills / 97 legacy command shims（README 当前口径）
商业边界	本体 MIT 永久免费；ECC Pro + GitHub App 面向私有仓库，自 19 美元/席/月起

站内 2026-09-21 已发过一篇 ECC 深度文（user-382caab285），距今 36 天，已超出近 14 天查重窗口；那篇组件口径是 68/292/94，本次为 71/311/97，属版本漂移而非矛盾。为避免重复，本文重心放在 9 月那篇未覆盖的 2.2.3 新增面。

三、为什么是它：从「配置包」到「门禁系统」

一，它把「提示词里的请求」升级成「hook 里的门禁」。 2.2.3 线最密集的改动全集中在 GateGuard——一个 PreToolUse 钩子，在代理第一次编辑文件前直接拒绝，并要求它先交出具体事实。这不是「你确定吗」式自我评估，而是强制调查。官方在 skills/gateguard/SKILL.md 的判断很直白：「LLM 自我评估不起作用。问『你违反任何政策了吗』，答案永远是『没有』。这是被实验验证过的。」

二，它开始给「跨工具承诺」标注保真度等级。 仓库新增 docs/architecture/harness-adapter-compliance.md，把适配状态硬性分成四档：Native（可直接安装或校验）、Adapter-backed（有薄适配器但保真度因 harness 而异）、Instruction-backed（只能提供指令与文件，不暴露运行时钩子面）、Reference-only（仅作设计参照）。Claude Code 是 Native，Codex 与 Gemini 是 Instruction-backed，OpenCode、Pi、Cursor、Zed、dmux 等是 Adapter-backed。敢自陈「不支持」，比声称「支持一切」可信得多。

三，它把「记忆」当成有信任边界的数据治理。 Memory Vault 每条首版条目都是 trust: "unreviewed"、只创建不覆盖、召回内容是数据而非可执行指令——直接回应了「代理自己写的记忆反过来指挥代理」这一攻击面。

也要克制看待：290,802 星的项目由单人高频迭代，跨 7 个 harness 意味着 7 处上游变更风险；README 的组件计数与版本口径历史上出现过不一致。

四、架构原理

4.1 整体架构：五层运行面 + 三项新增横切能力

官方 docs/ECC-2.0-REFERENCE-ARCHITECTURE.md 的权威声明是：ECC 要做 harness operating system，而不只是一堆命令、代理与技能的目录集。它把系统切成五个横向层，2.2.3 的三项新增能力分别横切在操作面、适配层与运行时层之间：

┌────────────────────────────────────────────────────────────┐
│ ① Operator Surface  操作面                                  │
│   CLI(ecc) · Claude 插件(ecc@ecc) · 斜杠命令 · HUD/状态行   │
│   ↳ 新增：Context Profiles（lean@1 / full@1 只读提案）      │
├────────────────────────────────────────────────────────────┤
│ ② Harness Adapter Layer  适配层                             │
│   Claude Code(Native) · Codex/Gemini(Instruction-backed)    │
│   · OpenCode/Pi/Cursor/Zed/dmux/DSH(Adapter-backed)         │
│   ↳ 新增：Harness Adapter Compliance Matrix（四档保真度）   │
├────────────────────────────────────────────────────────────┤
│ ③ Worktree / Session / Queue Runtime  运行时                │
│   worktree 生命周期 · pane/session/todo · 合并与冲突队列    │
│   ↳ 新增：GateGuard PreToolUse 事实强制门                   │
├────────────────────────────────────────────────────────────┤
│ ④ Observability & Evaluation Loop  观测与评测环             │
│   JSONL 轨迹 · 状态快照 · 风险台账 · harness 审计           │
│   ↳ 新增：GateGuard 决策指标 + 72 场 A/B 试点夹具           │
├────────────────────────────────────────────────────────────┤
│ ⑤ Security & Commercial Platform  安全与商业平台            │
│   AgentShield 策略/SARIF · ECC Tools 检查 · 计费 · 企业报告 │
│   ↳ 新增：供应链 IOC 扫描手册（TanStack / node-ipc 事件）   │
└────────────────────────────────────────────────────────────┘
        ↕ 贯穿各层：Memory Vault（ecc.memory.v1，三作用域）

这份文档的写法值得注意：它把每层的「外部参考压力」（orca、superset、dmux、meta-harness、autocontext 等公开项目）与「ECC 要落地的具体增量」一一对应，并要求每一项最终都落成适配器、检查、可观测信号或发布闸门。第④层明确规定：任何改进必须先存「轨迹 + 产物」，经验证器证明「改善场景且不扩大爆炸半径」后才允许晋升为 playbook，并保留回滚路径。

4.2 分层模块拆解

资产层（root 即唯一真源）。 仓库目录本身就是它的数据模型：agents/（71 个子代理，frontmatter 声明 tools、model）、skills/（311 个按需载入的工作流）、commands/（97 个迁移期斜杠命令 shim）、rules/、hooks/（hooks.json 声明 PreToolUse/PostToolUse/Stop 等事件）、scripts/。官方明确：根目录是唯一真源，适配器只做「打包或映射」，不维护副本——cross-harness.md 的原话是「Adapters should stay thin」。

适配层（十余个 harness 目录）。 仓库根同时存在 .claude-plugin/、.codex/、.opencode/、.cursor/、.gemini/、.kimi/、.zed/、.hermes/、.pi/、.adal/ 等。合规矩阵由 scripts/lib/harness-adapter-compliance.js 渲染，并用 npm run harness:adapters -- --check 校验，防止文档与代码漂移。

安装与生命周期层（控制面雏形）。 docs/SELECTIVE-INSTALL-ARCHITECTURE.md 把目标写得很清楚：安装系统必须能确定性地回答「请求了什么、解析成什么、复制或生成了什么、做了什么目标特定变换、ECC 拥有什么因而可以安全删除或修复」。已落地骨架包括 manifests/install-modules.json、install-profiles.json、四个 JSON Schema、scripts/lib/install/ 下的请求归一化与执行器，以及 list-installed/doctor/repair/uninstall 命令。文档自陈局限也很诚实：部分模块的目标特定合并/删除语义仍是脚手架级。

记忆层（Memory Vault）。 三作用域：项目 <repo>/.ecc/memory/project/、团队 <repo>/.ecc/memory/team/、用户 ~/.ecc/memory/。基线接口是确定性的 ecc memory CLI；有 MCP 能力的 harness 可另启 ecc-memory-mcp stdio 服务，暴露 memory_save/memory_search/memory_read/memory_doctor。该 MCP 是 opt-in 的：参考条目写在 mcp-configs/mcp-servers.json，但故意不出现在默认 .mcp.json 里，理由是「不让安装悄悄获得一个可写上下文面，也不付它的 schema token 成本」。

4.3 核心机制一：GateGuard 的三阶段事实强制门

这是 2.2.3 线最有技术含量的部分，实现落在 scripts/hooks/gateguard-fact-force.js 与 scripts/lib/gateguard-*.js。

三阶段状态机（skills/gateguard/SKILL.md 原文）：

1. DENY  — 拦下第一次 Edit/Write/Bash（含 MultiEdit、NotebookEdit）尝试
2. FORCE — 明确告诉模型需要收集哪几条事实
3. ALLOW — 事实齐备后放行重试

官方强调「No competitor does all three. Most stop at deny.」——只拒绝而不告诉模型该查什么，就退化成纯粹的摩擦。

模块布局与「不许漂移」的约束（docs/gateguard/design-notes.md）：

模块	职责
`hooks/gateguard-fact-force.js`	钩子本体：shell 解析器、状态文件 I/O、门禁消息
`lib/gateguard-target-class.js`	目标身份与分类：路径键、目标类及问题、敏感目标与硬链接检测
`lib/gateguard-turn-scan.js`	对 JSONL 转录做有界尾部读取，回溯到当前轮起点
`lib/gateguard-search-evidence.js`	判定当前轮检索是否覆盖目标（prior-search credit）
`lib/gateguard-search-filters.js`	解析 include/exclude 过滤器，判断是否接纳目标
`lib/gateguard-change-profile.js`	对变更文本做纯分析，决定问哪几个问题

设计文档解释了一个反直觉取舍：钩子文件明知超过 800 行规范仍保持单文件，因为「破坏性检测器与检索证据所依赖的 shell 解析器不能各自漂移」——宁可违反行数规范，也不容忍重复实现。

问题按目标类动态生成。 对 code 目标，Edit 门默认问四件事：

Before editing {file_path}, present these facts:

1. List ALL files that import/require this file
   (search the tree — Glob/Grep, or find/grep via Bash)
2. List the public functions/classes affected by this change
3. If this file reads/writes data files, show field names, structure,
   and date format (use redacted or synthetic values, not raw production data)
4. Quote the user's current instruction verbatim

关键在于这四问不是固定的。gateguard-change-profile.js 会读它即将放行的变更文本（Edit 的 old_string/new_string、MultiEdit 的每个条目、Write 的 content），判定三件事：

是否触及公开面：JS/TS 看 export/public/declare（.d.ts 恒真）；Python 看非下划线开头的 def/class、__all__（__init__.py 恒真）；Go 看大写开头的 func/type/var/const；Rust 看 pub/impl/trait/extern；shell 看函数定义与 export；PowerShell 看 function/param。不触及公开面时，第 1、2 问被替换为「列出本文件或本模块内依赖被改行为的调用点」——问题从「谁依赖你」收窄到「你影响谁」。
是否处理数据：看文件 I/O、格式词（json/csv/yaml）、序列化、编码、schema、SQL、数据存储、日期与时钟读取；shell 脚本里还看重定向到文件、curl、wget、jq。没有这些词就删掉第 3 问。
是否琐碎变更：注释与纯空白编辑直接放行并附说明，且不把该文件标记为已检查，因此下一次真正改代码仍会被门禁。

这套设计有明确实验依据。CHANGELOG 未发布段记录：「Hidden-intent trials did not show it helps」——外部契约问题（「说出仓库之外是什么决定了格式、单位、时区或协议语义」）在隐藏意图试验中没有显示收益，因此改为通过 GATEGUARD_EXTERNAL_CONTRACT_QUESTION 显式 opt-in、默认关闭。这是项目公开承认某功能无效并降级为默认关闭的例子，相当罕见。

prior-search credit：承认「调查已经发生过」。 门禁不是无条件拒绝。若当前人类轮次中已有一次完成且无错误的 Glob、Grep、LS 或搜索式 Bash/PowerShell 命令，且该命令点名了目标、作用域包含目标，则第一次触碰直接放行并附说明。边界极细：

Read 永远不算证据（设计文档专设 Read is not evidence 一节）；
同一批次内的搜索、压缩之前的搜索、带错误结果的搜索，都不算；
文件类型过滤器（rg -t、fd -e、Grep 的 type）、Glob 的 pattern、shell glob 操作数、git pathspec 都按 include glob 语义过滤，所以 rg -t py tokenizer src 不能为 tokenizer.js 记功；
仅限定在目标自身文件名上的检索（Glob **/tokenizer.js）被判为「查表」而非「树搜索」，永不记功。

敏感目标不享受任何宽容。 .env*、密钥与证书、credentials*、secrets.*、路径段含 auth/security/payment(s)/billing/migrations、.github/workflows/，以及硬链接数大于 1 的文件，按「书写路径」与真实位置双重判定，子代理中同样门禁。GATEGUARD_EXEMPT_GLOBS 优先级高于此。

状态与度量。 会话状态按 session id 或转录路径为键，空闲过期从 30 分钟延长到 8 小时。opt-in 的 GATEGUARD_FACT_FORCE_MAX_DENIALS 提供每会话拒绝上限——达到上限后新路径直接放行。GATEGUARD_METRICS 只记录决策码，永不记录路径、命令或内容。

4.4 核心机制二：Context Profiles 的「只读提案」纪律

docs/design/context-profiles.md 描述的 2.2.3 新增能力，其设计纪律比功能本身更值得学。状态标注为「accepted first development slice, P0/P1, September 8, 2026」，并明确声明「它不宣布已发布的运行时能力，也不改变安装默认值」。

它把四个控制面彻底分开，禁止互相映射：

控制面	含义	兼容规则
既有安装 `--profile`	按 `install-profiles.json` 选择安装模块	`minimal`/`core`/`full` 等语义不变
上下文 profile `lean@1`/`full@1`	提议哪些技能元数据被选中用于发现	与安装 profile 无自动映射；`full@1` 不等于完整安装
选择意图 `manual`/`suggest`/`auto`	记录选择意图	此切片不存在任务分类器或自动应用
运行时与能力	执行隔离、工具权限、密钥、副作用	上下文选择不授予任何权限，也不选择沙箱

它还规定了一个反直觉的返回约定：成功的 preview 故意返回 status: "warning" 与退出码 0，因为运行时激活状态仍是 unobserved；无效请求才返回错误与退出码 1。计划对象必须携带 active: false 与 disposition: "proposed"，且这两个字段必须在下游呈现中存活——这是把「尚未生效」写进 API 契约、防止下游误读的样板做法。

4.5 性能优化手段与设计取舍

取舍一：门禁的收益与成本必须同时公布。 docs/gateguard/question-effectiveness.md 把假设写在跑之前，并公开试点结果：72 场会话（6 场景 × 4 臂 × 3 次重复）、每一个臂在每一个试验中都通过，因此这次试点「测到了门禁的成本（约多 45% 轮次），而关于它的效果什么也没测到」；它还自陈作者知道分类法、这不是盲测。同时 skills/gateguard/SKILL.md 给出另一组 A/B 数字：分析模块 8.0 vs 6.5、Webhook 校验器 10.0 vs 7.0，平均 9.0 vs 6.75、+2.25 分，并注明「两者代码都能跑、都能过测试，差别在设计深度」。两组口径不同、结论不同，项目把它们并排放着而不是只留好看的那组——这是本文最看重它的一点。

取舍二：把「全量常驻」换成「按需载入」。 311 个技能若全部常驻，任何会话在写第一行提示前就被配置吃掉预算。对策是技能按需加载 + 命令降级为兼容 shim + 选择性安装档位。代价是能力不再「默认在场」，发现成本转移给用户。

取舍三：pi/core 用「离线可加载」验证裁剪正确性。 2.2.2 新增 pi/core/：只含技能与提示词的 Pi 原生档，123 个可移植工程技能 + 24 个纯提示词命令，无扩展、无 hooks、无运行时下载、无网络依赖。它由 manifests/pi-core.json 的显式 include/exclude 列表经 scripts/build-pi-core.js 确定性生成并提交入库。构建会在安全违规时失败：非白名单 URL 主机、pipe-to-shell 下载形式、密钥或 token、绝对用户主目录路径、符号链接、非法 frontmatter、重复技能名。CI 重建 pi/core 并校验其已提交且最新，然后安装 Pi CLI 并证明该档能完全离线加载（PI_OFFLINE=1），断言每条精选命令确实已注册。这是「用可执行的负向断言替代人工审查」的典型。

取舍四：跨 harness 采用「降级保真」而非「假装一致」。 一个根目录 + 薄适配器的代价是能力上限不同——Copilot 不支持 hooks、Codex 的 hook 对等性由指令驱动。ECC 的应对是公开四档矩阵与逐 harness 风险注记，例如 Pi 档写着「扩展以完整用户权限执行，hooks 无 shell 运行」。

4.6 与其他架构路线的差异

单一 harness 的配置包解决的是「某一种工具的用法沉淀」，不解决跨工具漂移；ECC 是内容 + 适配器 + 生命周期三层打包，并额外承担「保真度声明」这一诚实成本。harness 自身负责模型调用、权限与会话，ECC 只在其上做操作系统层，因此要承担上游 API 变更的传导风险。Agent 编排 IDE / worktree 工具（Orca、Superset、dmux）强在并行执行与工作区管理，ECC 把它们当作「要吸收的压力」而非竞争对手。通用记忆工具方面，ECC 以 Markdown 为源真相、SQLite/embedding 只作索引，首版检索是有界词法检索，语义适配器只允许后续重排而不改文档契约——牺牲召回上限，换取可解释、可导出、跨工具可读。

五、应用场景

场景一：把「改一个函数」变成「先查清谁依赖它」

痛点：编码智能体最典型的翻车不是写错语法，而是改了一个被三处引用的私有函数却只更新了一处。让模型自问「你确定吗」无效。

做法：启用 GateGuard，让第一次 Edit 被拒，模型被迫去跑 Grep/Glob 找引用点，事实齐备后重试放行。

npx ecc-universal@2.2.3 setup      # 安装（Claude Code 插件路径）
/plugin list ecc@ecc               # 确认插件启用
# 之后正常提需求即可：第一次编辑会被拦
#   用户：把 parseDate 的返回类型从字符串改成 Date 对象
#   门禁：DENY → 要求列出 importers / 受影响公开函数 / 数据结构 / 原话指令
#   模型：跑 Grep 找到三个模块 → 交事实 → 自动 ALLOW 重试

收益与量化：官方两组 A/B 的平均差距是 9.0 vs 6.75（+2.25 分），且明确「两者代码都能跑、都能过测试，差别在设计深度」；代价是约 45% 轮次增加。门禁买设计深度，付轮次。

适用边界：单文件脚本、原型验证、一次性数据清洗，摩擦大于收益；几十个文件同批改的重构应设拒绝上限或排除目录；敏感路径不享受任何宽容。

场景二：多 harness 团队的标准统一（按保真度排优先级）

痛点：团队里有人用 Claude Code、有人用 Codex、有人用 Cursor；同一份「提交前必须跑测试与类型检查」的规范被抄成三份，各自漂移。

做法：把规范下沉到根目录的 AGENTS.md + rules/，用多 harness 向导一次性落到各自目录。

npx ecc-universal@2.2.3 install --guided        # 一次选定多个 harness
npx ecc-universal@2.2.3 install --guided \
  --harness claude --harness codex --harness kimi \
  --claude-scope local --claude-hooks standard --profile core --yes
npx ecc-universal@2.2.3 install --guided --harness codex --dry-run   # 先干跑
npm run harness:adapters -- --check             # 校验矩阵与代码一致

收益与量化：规范只需维护一份。按官方合规矩阵，Claude Code 为 Native（插件资产、技能、命令、hooks、MCP 配置全支持）；Codex 与 Gemini 为 Instruction-backed（原生 hook 强制不具对等性）；OpenCode/Pi/Cursor/Zed 为 Adapter-backed。

适用边界：GitHub Copilot 明确不是对齐目标（无 hooks，仅指令引用）。Pi 档的风险注记必须读：扩展以完整用户权限执行。

场景三：跨会话、跨工具的记忆与交接

痛点：长任务结束时状态散落在聊天记录里；更危险的是，代理自己写下的「记忆」可能在下一轮被当成指令执行。

做法：用 Memory Vault 把知识存成可读 Markdown，在另一个 harness 里召回。

ecc memory                                      # 确定性 CLI：不需要模型/网络/数据库/embedding
export ECC_MEMORY_PROJECT_ROOT=/path/to/repo    # 需要时覆盖
export ECC_MEMORY_USER_ROOT=~/.ecc/memory
# 可选：启用 MCP 服务（默认不在 .mcp.json 中，须显式 opt-in）
#   每个 MCP 进程要求小写 ECC_MEMORY_HARNESS（服务端绑定身份，调用方无法自选）
#   用户作用域默认被阻止，除非以 ECC_MEMORY_ALLOW_USER_SCOPE=1 启动

收益与量化：四条硬约束给出可验证边界：① 首版条目只创建、永不覆盖，取代关系用新文档加显式链接表达；② 每条都是 trust: "unreviewed"，召回的记忆是数据不是可执行指令，人类接受才把知识晋升为受治理的仓库产物；③ 已知凭据形态与私钥在写盘前被拒（自陈「尽力而为的兜底」），读取器不跟随符号链接；④ 项目作用域写入在 vault 的保护性 .gitignore 被改动时停止。

适用边界：首版检索是有界词法检索，语义召回上限受限；直接读取会拒绝被截断的扫描（ECC_MEMORY_INCOMPLETE，MCP 返回 MEMORY_READ_INCOMPLETE），此时不返回任何部分内容——调用方必须处理该错误而非当成「没找到」。

场景四：审计并加固「代理配置」本身

痛点：代理配置是新的攻击面。2026 年 5 月的 TanStack npm 供应链事件中，攻击者的持久化 IOC 就包括 Claude Code 的 .claude/settings.json、VS Code 的 .vscode/tasks.json 与 OS 级 gh-token-monitor 服务。

做法：先扫描再修复，运行时叠加 GateGuard 拦截。

npx ecc-agentshield scan --path .        # 或 /security-scan
npx ecc-agentshield scan --fix           # 自动修复安全项
npx ecc-agentshield scan --opus          # 红队/蓝队/审计三段式
npm run security:ioc-scan                # 发布候选、大范围依赖升级后必跑

收益与量化：仓库的 docs/security/supply-chain-incident-response.md 是一份可直接照抄的 IOC 手册：TanStack 报告 42 个 @tanstack/* 包中 84 个恶意版本，发布于 2026-05-11 的 19:20–19:26 UTC（6 分钟内）；CVE-2026-45321 描述安装期恶意代码，收割云凭据、GitHub token、npm 凭据、Vault token、Kubernetes token 与 SSH 私钥；node-ipc 事件涉及 9.1.6、9.2.3、12.0.1。

适用边界：手册强调「注册表签名、provenance 与 trusted publishing 是有用信号，但不能证明工作流执行了预期代码路径」；--fix 只应作用于安全项；SARIF 与策略包属规划项，落地程度待确认。

场景五：上下文成本治理

痛点：Opus + 高思考预算 + 多个常驻 MCP，一天就把额度烧完；本地模型上下文更紧。

做法：关闭不需要的常驻面，用 Context Profiles 只读提案先看清「装了哪些技能会被发现」。

npx ecc-universal@2.2.3 install --profile minimal --target claude
export ECC_HOOK_PROFILE=minimal        # minimal / standard / strict
node scripts/ecc.js profile show --json
node scripts/ecc.js profile preview lean@1 --target codex --selection auto --json

收益与量化：官方 token 优化指南口径（未给基准环境，宜自行复测）：model 由 opus 改 sonnet 约省 60%；CLAUDE_CODE_SUBAGENT_MODEL 设 haiku 使子代理便宜约 80%；CLAUDE_CODE_EFFORT_LEVEL 设 medium 按任务复杂度调整力度。

适用边界：CLAUDE_CODE_EFFORT_LEVEL 需要支持力度控制的模型（Bedrock、Google Cloud Agent Platform、Microsoft Foundry 上 sonnet 别名当前解析到 Sonnet 4.5，不支持）；MAX_THINKING_TOKENS 只作用于固定预算思考模式，在自适应推理模型上正值会被忽略，不构成通用成本上限；社区报告 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 在某些构建中只能降低压缩阈值，若遇到应移除、改用手动 /compact。

六、快速上手

# 前置：Node.js 18+、Git、Claude Code 2.1+ 在 PATH 中
node --version && git --version && claude --version
npx ecc-universal@2.2.3 setup     # 引导式安装，不需克隆仓库；个人环境选 Global user + Standard hooks
/plugin list ecc@ecc              # 验证
/ecc:plan "add usage-based billing alerts"

其他包管理器等价写法：pnpm dlx、yarn dlx、bunx 后接同一包与版本；Yarn Classic 1 无 yarn dlx，改用 npx。源码检出可用 ./install.sh --profile minimal --target claude（Windows 对应 install.ps1）。官方安全提醒：版本钉扎不是安全审计，也不是完整性校验；README 顶部警告只从已验证渠道安装（GitHub 仓库、npm 包 ecc-universal 与 ecc-agentshield、GitHub App、插件 slug ecc@ecc、官网 ecc.tools），第三方重传与镜像「可能含恶意软件」。

七、横向对比

维度	ECC	单一 harness 配置包	harness 原生	并行编排 IDE	通用 agent 框架
解决的问题	跨工具配置/记忆/安全/评测共享层	单工具用法沉淀	模型调用、权限、会话	多 worktree 并行与评审	从零构建 agent 应用
跨 harness 可移植	核心卖点，且公开四档保真度矩阵	无	无	各异	不涉及 harness
运行时强制	GateGuard 事实强制门（DENY→FORCE→ALLOW）	通常无	权限模型为主	少	需自建
记忆治理	Markdown 为源真相、三作用域、只创建、`unreviewed`、不跟符号链接	取决于作者	会话级	不涉及	需自建
上下文控制	选择性安装 + 按需技能 + 只读提案 + MCP opt-in	取决于作者	会话级压缩	不涉及	需自建
效果证据	自陈 72 场试点「只测到成本」+ 另一组 +2.25 分 A/B	少见	厂商基准	少见	论文为主
成本结构	MIT 本体免费；Pro 自 19 美元/席/月起	免费	按订阅/用量	多为商业	自建运维

站内 9 月那篇记录的是 2.0.0 时期的 68/292/94，本次 README 为 71/311/97，属版本漂移。合规矩阵中 Cursor 的 hook 事件数与 Claude Code 不等价，迁移时应逐项对照能力表。

八、局限、风险与社区观察

最诚实的风险由项目自己公布：GateGuard 的效果尚未被证明。 docs/gateguard/question-effectiveness.md 明确写着 72 场试点中「每一个臂在每一个试验中都通过」，因此测到的是门禁的成本（约多 45% 轮次），而「关于它的效果什么也没测到」；该文档还自陈作者知道分类法、这不是盲测，并规定只有试点显示 gate 减 off 通过率差至少 15 个百分点时才值得投入完整测试。这与 SKILL.md 里 +2.25 分的 A/B 结论并不一致，后者待独立复现。

单维护者高频迭代的耦合风险。 README 自述「ships weekly across 7 harnesses」，跨 7 个 harness 就有 7 处上游 hook API 与配置格式变更可能打破它。仓库内还留有 docs/hook-bug-workarounds.md 这类修复记录，说明 hook 层确实出现过需要绕过的问题。

平台差异真实存在且被公开标注。 风险注记包括：Pi 扩展以完整用户权限执行、hooks 无 shell 运行并从已安装包而非用户项目解析；Cursor 适配器必须保留既有项目规则、避免静默覆盖；Zed 不应把 BYOK 密钥复制进 .zed/。CHANGELOG 的 Unreleased 段还记录了一处已修复故障：Claude Code home 安装此前无视 CLAUDE_CONFIG_DIR，配置根被重定向时出现「installs, but nothing loads」，settings.json、plugin.json 与安装状态全部滞留在 ~/.claude。

安全与治理的边界。 AgentShield 与 GateGuard 降低了风险，但「让代理读你的配置、hooks 与 MCP」本身需要信任链：扫描器、--fix 与 --opus 都应在受控环境验证后再进主线。供应链手册也自陈 provenance 不能证明工作流执行了预期代码路径。

商业分层与 License。 本体 MIT 永久免费，但私有仓库分析与团队能力走 ECC Pro + GitHub App。README 的赞助与合作伙伴位（CodeRabbit、Greptile、Moonshot AI - Kimi 等）意味着项目存在商业关联，评估时应把「文档中的推荐」与「独立验证的结论」分开看。

九、小结与行动建议

ECC 在 2.2.3 线的真正价值不是又多了 19 个技能，而是它把三件常被含糊处理的事写成了可验证契约：门禁该问什么（按目标类动态生成）、跨工具能到什么程度（四档保真度矩阵）、记忆能不能被信任（只创建 + unreviewed + 拒密钥 + 不跟符号链接）。它最值得学的甚至不是功能，而是把负面结果一起放进仓库——72 场试点「只测到成本」、外部契约问题因此默认关闭、pi/core 用离线加载断言证明裁剪正确。落地建议：

先用 minimal 档跑一周再决定是否开门禁：用 /context-budget 观察上下文压力。GateGuard 的代价是约 45% 轮次增加，先确认任务类型是否值得。
把门禁当「敏感路径保险」而非「全局加速器」：.env*、.github/workflows/、硬链接文件在任何配置下都被门禁，这是优点；高频批量重构则设拒绝上限或排除目录。
多 harness 场景按保真度排优先级：Claude Code 作为 Native 主参考；Codex/Gemini 接受 Instruction-backed 并用 AGENTS.md 兜底；Copilot 不纳入对齐承诺。
记忆当数据治理，不当自动知识库：保持默认项目隔离，定期审查 unreviewed 条目；处理 ECC_MEMORY_INCOMPLETE 错误而非当成「没找到」。
锁版本 + 自建回归 + 先扫自己：固定 ecc-universal 版本，升级前跑 npm run harness:adapters -- --check 做基线；接入团队仓库前先 npx ecc-agentshield scan --path .。

资料来源（抓取日期 2026-10-27）：GitHub Trending daily/weekly 页面；GitHub REST API（元数据、git tree、Releases）；仓库内 README.md、VERSION、CHANGELOG.md、docs/ECC-2.0-REFERENCE-ARCHITECTURE.md、docs/architecture/{cross-harness,harness-adapter-compliance}.md、docs/design/{context-profiles,ecc-memory-vault}.md、docs/gateguard/{design-notes,change-profile,question-effectiveness}.md、skills/gateguard/SKILL.md、docs/token-optimization.md、docs/security/supply-chain-incident-response.md。

官方口径未给基准环境的数字（如「省约 60%」「便宜约 80%」）、第三方转述或口径不一致处，文中均已标注「官方口径」或「待确认」。GateGuard 的 +2.25 分 A/B 与 72 场试点的负面结论并存，前者待独立复现。