ECC：跨 Harness 资产、安装器、Hooks 与经验治理

ECC 管理 Skills、Rules、Hooks 与安装策略，模型和工具主循环由宿主执行。顺着“共享资产—安装计划—平台适配—事件检查—经验更新”分析它的工程内核，最后区分已实现能力与 ECC 2.0 Alpha。

Everything Claude Code（ECC）把 Skills、Rules、Hooks 和安装策略分发到多个 Agent Harness。本文分析固定提交 22e8cf0：共享资产描述工作方式，安装器把它们转换为目标平台文件，模型调用与工具主循环仍由宿主承担。

先把 ECC 放对位置：它是 Meta-Harness，不是模型代理层

传统 Agent Framework 通常拥有自己的主循环：接收任务，调用模型，解析 Tool Call，执行工具，再把结果送回模型。ECC 的公开版本没有试图替代这一层。Claude Code 或 Codex 仍然掌握模型会话、工具协议、权限询问和基础执行循环。

ECC 插在另一个位置：它管理 Agent 如何工作，而不是亲自扮演 Agent。

ECC 位于模型 Harness 之外，以资产、安装器和 Adapter 把工程意图投射到不同平台。 ECC 自己的跨 Harness 架构文档给出了很准确的分工：ECC 是 reusable workflow layer，Claude Code、Codex、OpenCode 和 Cursor 是 execution surfaces。稳定的工作方式应该留在共享源中，平台文件只处理加载方式、事件格式、命令映射与能力缺口。

迁移时要区分路径差异和能力缺口：路径差异由 Adapter 处理；目标平台缺少阻断事件时，应报告门禁不可用，不能用一段说明宣称等价。例如同一“测试通过才发布”流程，可以共享检查脚本，但发布拦截必须在目标平台或受保护 CI 中另行验证。

ECC 管的是五类不同对象

这些目录看似都是 Markdown，运行语义却不同：

资产	解决的问题	加载方式	约束强度
Rules / `AGENTS.md`	默认应遵守哪些长期规范	常驻或随项目加载	软约束
Skills	某类任务应该如何完成	按描述匹配、渐进加载	软约束，但流程更完整
Agents	谁以什么角色、工具和上下文完成子任务	由 Harness 创建隔离会话	受 Harness 能力影响
Commands	用户如何显式进入常见工作流	命令或兼容入口	入口层
Hooks	在工具与会话事件上必须检查什么	事件触发的本地进程	可警告、可阻断

这五类对象不能互相替代。把所有规范放进常驻 Rule 会造成上下文膨胀；把安全边界写进 Skill 又只能期待模型自觉执行；把每项工作都拆成 Agent，则会制造额外的上下文与协调成本。

ECC 的架构价值，首先来自把不同强度、不同生命周期的知识放进不同容器。

资产层：用渐进式披露对抗“上下文越多越聪明”的错觉

ECC 最显眼的部分是庞大的 Skills 目录。但它并不是要把 286 份说明一次性交给模型。

一个 Skill 通常由短描述负责被发现，完整 SKILL.md 只在任务命中时加载，参考材料和脚本再在执行过程中按需读取。这种结构本质上是三级索引：

能力目录与 description
        ↓ 命中任务后
SKILL.md 的约束与工作流
        ↓ 确实需要时
references / scripts / examples

因此，Skill 的价值不只在于复用提示词，更在于控制注意力预算。模型先看到“有哪些能力”，再读取“这一项怎么做”，最后才取用证据或执行脚本。仓库首页那句“Optimize the context window. Persist everything else”不是宣传口号，而是资产设计的核心约束。README也明确把 ECC 描述为从计划、测试、实现、审查、验证到记忆和改进的连续流程。

Profile 与 Module：规模扩大后的第二道上下文阀门

ECC 没有要求每个用户安装整个仓库。manifests/install-profiles.json 定义 minimal、core、developer、security、research 和 full 等配置；install-modules.json 再把资产划分为 rules-core、agents-core、hooks-runtime、workflow-quality、framework-language、security 等模块，并记录依赖、目标平台、成本和稳定性。

因此安装不是“复制全部文件”，而是一次能力解析：

用户选择 Profile / Module / Component
              ↓
解析依赖与目标平台兼容性
              ↓
生成文件复制、JSON 合并、路径改写等操作计划
              ↓
安全应用并记录所有权与内容摘要

这解决了大目录必然遇到的两个问题：一是用户不需要的 Skill 也会增加发现噪声；二是 Hooks、Rules 等高影响资产不应该在用户不知情时自动叠加。

安装层才是隐藏的核心：ECC 实际上实现了一个小型编译器

如果只阅读 Markdown，会低估 ECC 的工程复杂度。真正把“共享源”变成“可运行安装”的核心位于 manifests/ 与 scripts/lib/install*。

把这条链类比成编译器会更容易理解：

编译器概念	ECC 中的对应物
源语言	Skills、Rules、Agents、Hooks、MCP 配置
构建参数	Profile、Module、Component、目标 Harness
中间表示	Manifest 解析后的 Install Plan
后端	Claude、Codex、Cursor、OpenCode 等 target adapter
代码生成	copy-file、merge-json、内容转换、链接重写
构建记录	install state、来源版本、操作清单、SHA-256
增量修复	doctor、repair、uninstall

在源码中，createManifestInstallPlan() 会先解析 Manifest，再选择 Target Adapter，把目录级 Scaffold 展开为具体文件操作，最后生成安装状态预览。安装计划实现甚至会去重写向同一目标的复制操作，避免通用文件与平台特化文件相互覆盖后，让 doctor 永久误报漂移。

Target Adapter 则统一暴露几类能力：

判断自己是否支持某个目标名称；
验证当前环境；
计算目标根目录和安装状态路径；
把共享 Module 转换为目标平台上的操作列表。

当前注册表中有 Claude Home、Claude Project、Codex Home、Cursor Project、OpenCode Home、Gemini Project、Hermes、Kimi、Qwen、Zed 等多种适配器。适配器注册表说明所谓“跨平台”不是把同一文件复制到十五个目录，而是共享语义、分别落盘。

仓库实际上还有第二组 Adapter：安装 Adapter 负责把资产投射到文件系统，Session Adapter 则把 Claude History、Codex Worktree、OpenCode 与 dmux / tmux 的运行状态归一化为 ecc.session.v1 快照。前者解决“能力怎样安装”，后者解决“控制平面怎样看懂正在运行的会话”。二者如果混在一起，安装器就会被会话生命周期污染；ECC 把它们拆开，是走向多 Harness 控制平面的关键一步。

Plan 与 Apply 分离为什么重要

ECC 把解析计划与执行计划拆开，这不只是为了支持 --dry-run。

Agent 工具链的安装目标通常位于用户 Home 目录，里面可能已有个人规则、MCP、插件与权限设置。如果边解析边写入，一次失败就可能留下半完成状态；如果覆盖整个 JSON，又会破坏不属于 ECC 的配置。

ECC 的 Apply 层因此要处理：

JSON 深合并，而不是整文件覆盖；
安装内容的相对链接改写；
只在受信根目录内写入；
读取和写入时拒绝符号链接跳转；
记录每个受管文件的内容摘要；
卸载时只移除自己能够证明拥有的内容；
用户修改过的旧文件不盲目删除。

这已经不是一个 cp -R 脚本，而是一套带所有权模型的配置部署系统。

架构代价：可靠性集中在安装生命周期内核

这种设计也形成了明显的风险集中点。scripts/lib/install-lifecycle.js 超过 2,000 行，负责发现已有安装、漂移诊断、修复计划、兼容迁移与安全卸载；不同平台的差异最终都会回流到这个生命周期内核。

集中实现便于统一行为，也可能扩大回归范围；文件行数本身不能证明必须重构。应先检查平台变更是否反复触及无关逻辑，再决定是否拆分文件安全、安装状态和平台迁移。跨平台固定样本应覆盖覆盖冲突、用户修改和卸载失败。

运行时层：在配置匹配的事件边界执行检查

Skills 与 Rules 会影响模型决策，但它们无法证明模型一定运行了测试、一定没有执行危险命令，也无法保证会话结束时一定保存状态。

在指定提交 22e8cf0 中，Hooks 为配置匹配的事件提供程序检查；是否阻断仍取决于宿主支持、启用状态、超时和错误处理策略。

ECC Hook 在确定性事件边界执行阻断检查、同步改写与异步反馈。 ECC 在 PreToolUse 处理开发服务器、Git Push、提交质量、文档路径与危险 Shell 操作；在 PostToolUse 处理格式化、类型检查、构建分析和质量反馈；在 SessionStart、PreCompact、Stop 与 SessionEnd 处理上下文恢复、压缩前保存、模式提取和会话收尾。完整事件表见Hooks 文档。

这里有三个值得借鉴的设计细节。

1. Hook 有统一的能力开关，而不是散落的环境判断

hook-flags.js 把控制收敛成三层：总开关、minimal / standard / strict Profile、单 Hook 禁用列表；环境变量优先于插件配置，插件配置再优先于受管安装配置。源码让同一套 Hook 可以按组织风险偏好渐进启用，而不是只有“全开或全关”。

2. Bootstrap 负责平台差异和输出卫生

Hook 本质上是 Harness 启动的子进程。Windows Shell、插件根路径、超时、标准输入输出和退出码都会影响可靠性。plugin-hook-bootstrap.js 统一解析插件根目录、校验路径不能逃逸、选择 Node 或 Shell 运行时，并处理 Windows PowerShell 与 Bash 的差异。

更细的一处优化很能说明 Harness 工程的特殊性：部分 Hook 会把原始输入原样输出，导致工具结果再次进入 Transcript。Bootstrap 会识别这种 byte-exact passthrough 并输出空内容，避免会话记录被几十到几百 KB 的重复 JSON 填满。Bootstrap 实现把“上下文成本”当作运行时正确性的一部分，而不只是 Token 优化。

3. 可阻断检查与异步反馈被明确区分

PreToolUse 可以用退出码 2 阻断工具；PostToolUse 只能观察和反馈；异步 Hook 不应承担强制门禁。这个边界避免把一个耗时的构建分析误放到每次工具调用之前，也避免团队以为某条事后警告已经提供了安全保证。

例如工具已修改文件，随后 PostToolUse 类型检查失败，文件不会因此自动回滚。Harness 必须记录失败并安排修复；事后检查既不能撤销既成副作用，也不能补发执行授权。

Hook 同时约束了 ECC 的跨 Harness 能力。Claude Code 拥有完整的原生事件能力，Codex 插件只打包满足其协议和信任模型的同步 Hook 子集，OpenCode 与 Cursor 则通过各自的事件适配层复用部分逻辑，其他平台还可能只能依靠说明性规则。资产可移植不等于执行语义等价。 ECC 自己也在支持矩阵中承认这种差异；选型时应该验证关键门禁在目标 Harness 上究竟是 Hook-backed 还是 instruction-backed。

记忆与持续学习：保存记录与批准规则分开

很多 Agent 系统会把完整 Transcript 塞回向量数据库，再把相似内容自动注入后续会话。这样做很方便，也混合了三个完全不同的问题：

当前任务如何在压缩或中断后继续；
跨 Harness 如何传递事实、决策与交接；
重复出现的做法何时应该升级为稳定流程。

ECC 分别使用会话状态、Memory Vault 与 Instinct / Skill Evolution 处理这三层。

Memory Vault：Markdown 是原始记录，索引是投影

Memory Vault 使用 ecc.memory.v1 Markdown 文档保存 project、team 和 user 三种作用域的事实、决策、交接、经验与笔记，并同时提供确定性 CLI 和可选的本地 MCP 接口。设计文档规定了几条很克制的边界：

所有新记忆都是 unreviewed；
写入只允许创建，不覆盖旧 ID；
废弃关系用新文档显式链接表达；
默认检索只返回 active 的 project 与 team 记忆；
user scope 需要显式请求；
记忆是数据，不是可执行指令；
人工认可的知识要晋升到 Rule、ADR、Runbook 或正式文档，而不是修改记忆里的信任标签。

这套设计把“可记忆”与“可信任”彻底拆开。即使某段上下文已经被团队提交进 Git，它仍然只是待核验的背景材料。一个同样拥有 Shell 权限的 Agent 不能充当自己的批准人。

MCP 也没有默认开启。每个 MCP 进程必须从服务端环境取得固定 Harness 身份，调用者不能在参数里伪装成另一个 Harness；user scope 还需要额外环境开关。这里的思路是：可写上下文面本身就是攻击面，不能为了“自动记忆”悄悄增加工具 Schema 与权限。

Continuous Learning：先观察，再形成 Instinct，最后才可能成为 Skill

持续学习 v2 的目标链是：Hook 捕获观察，后台 Observer 分析模式，Instinct 以置信度持久化，相关 Instinct 再聚类演化为 Skill 或 Command。它不是模型权重更新，也不是让 Agent 自动重写规则。

Tool / Session Events
        ↓
结构化 Observation
        ↓ 多次证据与置信度
Instinct（候选经验）
        ↓ 聚类、评估、人工检查
Skill / Command（可复用工作流）

真正好的地方是中间保留了 Instinct 层。一次成功操作可能只是偶然；重复成功也可能只适用于某个项目；只有在证据、作用域和验证方式都清楚后，它才应该扩大影响范围。

这与 ECC 2.0 规划的“观察—提议—验证—晋升—回滚”循环一致：系统保存的不只是最后一份修改，还包括 Scenario、Trace、Candidate Playbook 与 Verifier Result。换句话说，自我改进的产品不是会修改自己，而是能够证明为什么这次修改值得被保留。

安全模型：把 Agent 自己的配置也当作供应链

AI 编程工具的攻击面不只在生成的业务代码。一个恶意 Skill、过宽的 MCP 权限、一段被篡改的 Hook 或一个允许任意 Shell 的配置，都可能在模型真正开始写代码之前突破边界。

ECC 的安全模型分成四层：

层级	机制	处理的风险
安装边界	trusted root、路径包含校验、no-follow 读写、所有权记录	路径逃逸、符号链接、误删用户文件
执行边界	GateGuard、PreToolUse 阻断、Profile	危险 Shell、绕过校验、误操作
配置审计	AgentShield	Prompt、Hooks、MCP、权限、Secrets 与 Agent 文件风险
演进治理	未审查 Memory、Instinct 晋升、Evaluator Gate	污染长期上下文、错误经验扩散

其中 AgentShield 是独立发布的扫描器，不应与 ECC 主仓库中的 Hook 混为一谈。ECC 负责提供入口和安全工作流，AgentShield 负责静态与运行时安全检查；更完整的 Hosted Fleet 与 Enterprise Policy 仍属于路线图。主仓库的安全说明和AgentShield 路线图必须结合阅读，才能区分已经存在的本地扫描能力与尚未完成的企业平台。

ECC 的安全取向不是声称“所有攻击都能检测”，而是尽量缩小每一步的权力：安装器只写受信根目录，Memory 不自动成为指令，MCP 不默认开放，强制门禁放在 PreToolUse，扫描器提供独立证据，未来的策略变更还要经过评估与晋升。

ECC 2.0：Rust 控制平面是真实 Alpha，不是现有系统的同义词

仓库里最容易被误读的是 ecc2/。

ECC 2.0 的参考架构规划了五层：Operator Surface、Harness Adapter、Worktree / Session / Queue Runtime、Observability / Evaluation Loop，以及 Security / Commercial Platform。它希望从“安装在现有 Harness 里的资产层”继续向上，形成多会话、多 Worktree、可观察、可评估的 Agent 控制平面。

当前 Rust 实现已经具备：

基于 SQLite 的 Session Store；
Session start / stop / resume 与后台 Daemon；
Worktree 感知的会话脚手架；
输出流、风险评分、通知与基础多会话状态；
上下文图谱、观察、召回与压缩原语；
候选 Harness 配置的摘要寻址、基线比较、晋升与回滚审计。

尤其值得注意的是 Harness Evaluation：候选配置先以 SHA-256 地址保存，再用相同 Seed 与基线做配对比较；只有满足样本数、均值增益、胜率和健康检查时才晋升，SQLite 事务同时更新 active pointer 与审计证据，失败则恢复原指针。

但 ecc2/README.md明确写着 Alpha。当前评估器只读取操作者提供的测量结果，不调用网络、模型或 Shell；证据引用和分数也是操作者声明，不是经过认证的事实。更丰富的多 Agent 编排、可视化 Diff Review、完整跨 Harness 恢复语义和发布安装链仍在建设中。

因此，谈 ECC 时必须同时保留三条时间线：

层	当前成熟度	正确理解
Skills / Agents / Commands / Rules	大规模可用	内容与工作流资产库
Manifest Installer / Hooks / Memory CLI	已有真实实现与测试	当前工程内核
ECC 2.0 Control Plane / Hosted Platform	Rust Alpha 与路线图并存	需要继续验证，不能按 GA 能力采购

采用时验证五个故障场景

以下是基于固定提交 22e8cf0 的采用建议，不是本文完成过的测试结果。先选择一个目标 Harness 和最小安装 Profile，再检查：

场景	应观察的结果	不能据此推断什么
安装后用户手动修改受管文件	doctor 标出漂移，卸载保留用户变更	内容摘要不能证明文件业务正确
目标平台没有所需阻断事件	能力矩阵标记缺口，用独立 CI 或受控执行器补足	安装成功不代表门禁生效
Hook 被禁用或超时	高风险路径按明确策略停止，并留下记录	事后告警不能撤销已执行操作
一条错误 Memory 被多次召回	保留来源与未审查状态，不自动晋升 Rule	高频出现不代表经验可信
Evaluator 收到人为夸大的分数	能追溯输入证据，晋升前有独立复核	Alpha 的事务审计不能认证测量真实性

ECC 的可复用部分是资产类型、可预览安装计划、文件所有权和平台适配边界。代价是维护多平台语义差异、资产过期与额外的安装生命周期。需要自有模型循环时，应另选运行框架；需要生产级多会话控制面时，应单独验证 ECC 2.0，而不能从成熟的 Skills 目录推断 Alpha 的可靠性。