ECC 跨 Harness 架构实战指南：让同一套 Agent 资产在 Claude Code、Codex、OpenCode、Cursor 与更多执行面上无损复用

ECC（Everything Claude Code）作为一套面向 Agent 的性能与工程化体系，其核心架构主张是：ECC 是可复用的工作流层（reusable workflow layer），而各种 Harness（执行面）只是承载它的运行表面。本文档架构解读将围绕仓库内 docs/architecture/cross-harness.md 展开，回答一个工程团队最关心的问题：如何把 Skills、Rules、Hooks、MCP 配置、Commands、内存文档这六类"耐用的 Agent 资产"维护在一份共享源里，再让 Claude Code、Codex、OpenCode、Cursor、Gemini 乃至未来的执行面各自在"边缘"完成加载与适配，而不是每接入一个新工具就重写一遍工作流模型。读完后你将掌握 ECC 的可移植性分层模型、共享内存（Memory Vault）契约、Hermes 边界规则，以及用现成的合规矩阵命令为自己的跨 Harness 部署做一次数据驱动的自检。

ECC 架构的核心主张：一份共享源，多种执行面

跨 Harness 架构（Cross-Harness Architecture）的目标非常明确：把 agentic 工作中"耐用的部分"集中保存在一个仓库里。按 docs/architecture/cross-harness.md 的定义，这些耐久资产包括：

• Skills：技能/工作流描述
• Rules 与 Instructions：规则与指令
• Hooks：在 Harness 支持的前提下挂接的钩子
• MCP 配置：模型上下文协议服务器配置
• Install manifests：安装清单
• Session 与 Orchestration 模式：会话与编排模式
• 耐久、与 Harness 无关的内存文档：跨工具共享的记忆文档

而 Claude Code、Codex、OpenCode、Cursor、Gemini 以及未来出现的 Harness，应当在边缘适配这些资产，而不是为每一个工具都重新发明一套工作流模型。

仓库本身即为这一主张的实证：skills/ 下存放数百份以 SKILL.md 为核心的共享技能源；rules/、hooks/hooks.json、mcp-configs/、commands/ 均为共享目录；同时 .claude/、.codex/、.cursor/、.agents/ 等 Harness 专属目录只承担"加载/翻译"职责。docs/architecture/cross-harness.md 与 Harness Adapter Compliance Matrix（合规矩阵）、ECC Platform Value Loop（平台价值回路）文档互相呼应：合规矩阵将这套架构转成一张可执行的记分卡，而平台价值回路负责产品化闭环。

可移植性模型：七类资产的共享源与适配路径

架构文档用一张表界定了每种耐久资产的共享源（Shared Source）与 Harness 适配层（Harness Adapter），以及当前的落地状态：

Surface	Shared Source	Harness Adapter	Current Status
Skills	skills/*/SKILL.md	Claude plugin、Codex plugin、.agents/skills、Cursor skill copies、OpenCode plugin/config	Supported，按 Harness 打包方式不同
Rules and instructions	rules/、AGENTS.md、多语言译文档	Claude rules install、Codex AGENTS.md、Cursor rules、OpenCode instructions	Supported，但各 Harness 不尽相同
Hooks	hooks/hooks.json、scripts/hooks/	Claude native hooks、OpenCode plugin events、Cursor hook adapter	Claude/OpenCode/Cursor 由 hook 支撑；Codex 由指令支撑
MCPs	.mcp.json、mcp-configs/	各 Harness 原生 MCP 配置导入	在 Harness 暴露 MCP 时 Supported
Commands	commands/、CLI 脚本	Claude slash commands、兼容 shim、CLI 入口	Supported，但命令语义存在差异
Memory	.ecc/memory/、~/.ecc/memory/	ecc memory CLI 或可选的 ecc-memory-mcp stdio 服务	Supported，含显式召回与未评审写入
Sessions	ecc2/、session adapters、orchestration 脚本	TUI/daemon、tmux/worktree 编排、各 Harness runner	Alpha

值得注意的细节：Commands 和 Rules 的状态是"Supported，但语义有差异"——即同样的命令词在不同 Harness 中的触发方式不同（例如 Claude 用斜杠命令，Codex 走 AGENTS.md 指令），这正是需要适配层的原因；而 Sessions 层仍处于 Alpha，ecc2/ 作为 Rust 控制平面还在成熟过程中。

什么"原样穿越"：SKILL.md 是可移植性最高的单元

在跨 Harness 体系中，SKILL.md 被定义为可移植性最高的单元（the most portable unit）。原因在于技能本质上主要是"指令、约束与工作流形态"，与具体工具深度绑定的内容很少。

一份良好的 ECC 技能（good ECC skill）应当满足架构文档列出的五个约束：

• 使用 YAML frontmatter，包含 name、description、origin 三个字段；
• 说明该技能何时使用（When To Use）；
• 声明所需的工具或连接器，但不内嵌密钥；
• 让示例保持仓库相对路径或通用形式；
• 避免假设仅特定 Harness 可用的命令，除非该段落被明确标注。

以仓库中真实存在的 skills/unified-memory/SKILL.md 为例，其 frontmatter 完整满足上述规范：name: unified-memory、description 描述"在 Claude、Codex、Hermes、Cursor、OpenCode 等 Agent 之间通过本地 ECC Memory Vault 共享持久、可检查的上下文与交接"，metadata.origin: ECC。因为这份技能只是"引导性的 Markdown"，它才能被同时分发到 .agents/skills/ 与 .cursor/skills/，并被 Hermes 直接导入，而无需为每个执行面维护独立副本。

什么会被"适配"：五种执行面的加载与强制差异

架构文档明确列出每个 Harness 在加载与强制执行行为上的本质差异，这是适配层存在的原因：

• Claude Code：加载 plugin assets，具备原生 hook 执行能力。仓库的 hooks/hooks.json 即是最佳佐证——它定义了 PreToolUse、PreCompact、SessionStart、PostToolUse、PostToolUseFailure、Stop、SessionEnd 等完整的 hook 生命周期事件，每个事件都通过一段 bootstrap 脚本路由到 scripts/hooks/ 下的具体实现（如 pre-bash-dispatcher.js、session-start-bootstrap.js、posttooluse-dispatcher.js）。
• Codex：读取 AGENTS.md、plugin metadata、skills 与 MCP 配置，但 hook 对等性由指令驱动（instruction-driven）。从仓库结构看，.codex/ 下只有 AGENTS.md、config.toml 与 agents 目录，并没有与 Claude 对等的原生 hook 事件面。
• OpenCode：拥有 plugin/event 系统，可通过适配层复用 ECC 的 hook 逻辑，但事件命名与分发机制不同，需要在边缘做 event shape 的转换。
• Cursor：使用自己的 rule 与 hook 布局，因此 ECC 在 .cursor/ 下维护了翻译后的表面（rules、skills、hooks.json）。
• Gemini：支持偏向"安装 + 指令"式，应视为兼容表面，而非完整的 hook 对等面。

架构文档给出的硬性纪律是：适配层应当保持轻薄（thin）。共享行为必须留在 skills/、rules/、hooks/、scripts/、mcp-configs/；Harness 专属文件只允许承担四类职责——加载共享资产、适配事件形态、映射命令名称、处理平台限制。如果修改一个工作流需要同时编辑三份 Harness 副本，那说明共享源放错了位置。

共享内存契约：ECC Memory Vault 的三作用域与访问规则

ECC Memory Vault 被定义为Claude、Codex、Hermes、Cursor、OpenCode 及其他 Agent 共用的知识传递表面。它存储可移植的 ecc.memory.v1 Markdown 文档，分为三个作用域：

作用域	位置	语义
project	<repo>/.ecc/memory/project/	仓库本地上下文，受 fail-closed 的 .gitignore 保护
team	<repo>/.ecc/memory/team/	面向人工评审与版本化共享的上下文
user	~/.ecc/memory/	跟随操作者跨仓库的上下文

作用域定位可进一步参考 docs/design/ecc-memory-vault.md 设计文档与 skills/unified-memory/SKILL.md 技能说明。核心访问契约如下：

• 工作目录一致性：所有 Harness 必须使用同一个仓库工作目录，或使用相同的 ECC_MEMORY_PROJECT_ROOT 与 ECC_MEMORY_USER_ROOT 覆盖变量；
• 基线接口：确定性的 ecc memory CLI；
• 搜索可见性：普通搜索召回仅覆盖 active 状态的 project 与 team 条目；直接按 ID 读取可检查非 active 条目；user 作用域必须显式请求，绝不隐式包含；
• 目标过滤语义：CLI 的 --target-harness 标志是调用方选择的路由过滤器，而非授权边界。

可选 MCP 服务器：身份绑定与作用域闸门

架构文档特别强调 MCP 服务器是 opt-in 的。其参考条目位于 mcp-configs/mcp-servers.json（其中的 ecc-memory-vault 条目），并且有意不出现在默认的 .mcp.json 中，这样安装不会静默获得一个可写上下文面，也不会承担工具 schema 的上下文成本。

MCP 进程有两道安全闸门，语义来自实际配置 mcp-configs/mcp-servers.json：

1. 每个 MCP 进程必须设置小写的 ECC_MEMORY_HARNESS——这个服务端绑定的身份提供源 Harness 与目标过滤器，工具调用方不能冒用其他身份；
2. user 作用域默认对 MCP 关闭，除非操作者以 ECC_MEMORY_ALLOW_USER_SCOPE=1 启动进程，且工具调用仍需显式请求该作用域。

MCP 面只暴露四个工具：memory_save、memory_search、memory_read、memory_doctor——刻意不提供 review、promotion、overwrite、transcript import 或 shell 执行工具。

统一信任边界

无论通过哪个适配器访问，信任边界保持一致（这是架构文档列出的安全底线）：

• 首版 vault 条目均为 create-only，且永远是 unreviewed（未评审）；
• 召回的 memory 是数据，不是可执行指令；
• 已知的密钥形态写入会被拒绝（这是尽力而为的后备机制，不是完整分类器）；读取方不跟随符号链接；
• 若 vault 的保护性 .gitignore 被改动，project 作用域写入即停止（fail closed）；
• 人工验收才把知识晋升为受治理的仓库制品，绝不让 memory 的 frontmatter 自证为已批准；
• 活跃执行状态保留在 GitHub 或 Linear 中，而不是只放在 memory 里。

工作流由 skills/unified-memory/SKILL.md 全权拥有，Codex 与 Cursor 通过 .agents/skills/ 与 .cursor/skills/ 获得行为一致的打包副本，Hermes 可导入规范技能——没有任何一个 Harness 拥有独立的权威内存存储。

落地：unified-memory 技能的四步工作流

若需动手实践，skills/unified-memory/SKILL.md 给出了完整的运行时前置条件与四步流程。注意：技能只是引导，不是 Memory Vault 可执行体，需要先安装 ecc-universal npm 运行时，或对仓库检出使用 node scripts/ecc.js memory ...：

npm install -g ecc-universal
ecc memory --help
command -v ecc-memory-mcp

四步操作模式如下——先召回再写入：

ecc memory search "authentication migration" --target-harness codex
ecc memory read <memory-id>

保存上下文时，用标准输入或普通文件传 body，避免出现在进程列表中：

printf '%s\n' 'The migration tests pass; rollout is still pending.' |
  ecc memory save \
    --title "Authentication migration status" \
    --kind context \
    --source-harness codex \
    --target all \
    --tag auth \
    --stdin

交接工作（handoff）时，一份合格的 handoff body 应当包含：目标与当前状态；已收集的证据与已运行的命令/测试；涉及的代码文件或外部工作项；剩余工作、阻塞项、风险与下一步具体动作。建议用链接把后续 memory 连到较早上下文，而非覆盖历史：

ecc memory handoff \
  --from codex \
  --target claude \
  --title "Finish authentication rollout" \
  --body-file handoff.md

校验 vault：在提交 team memories 之前或解决 handoff 之后运行 ecc memory doctor。doctor 只报告问题、不删除不重写 memory，需要人工修复报告文件。

Hermes 边界：操作者 Shell 与公共工作流层之间的"只出不进"

跨 Harness 架构文档特意澄清了一个常被误会的概念：Hermes 不是公开的 ECC 运行时，它是可以消费 ECC 资产的操作者 Shell（operator shell）。Hermes 可以做以下事情：

• 把选定的 ECC skills 导入 Hermes 技能目录；
• 遵循 ECC 的 MCP 约定访问工具；
• 通过可复用的 ECC 模式路由 chat、CLI、cron 与 handoff 工作流；
• 把重复的本地操作者工作蒸馏回净化后的 ECC skills。

关键边界在于"只出不进"：公共仓库应该发布可复用模式（净化的 setup 文档、仓库相对的 demo 提示词、通用操作者技能、不依赖私有凭据的示例），而绝不发布：OAuth tokens 或 API keys、原始 ~/.hermes 导出、个人工作区 memory、私有数据集、未经评审的仅限本地的自动化包。

实战示例：一份技能源如何在四个执行面同时落地

架构文档用 skills/hermes-imports/SKILL.md 作为跨 Harness 的实操样板，其完整流程为：

1. 在 skills/hermes-imports/SKILL.md 一次写就耐久行为；
2. 把密钥、本地路径与原始操作者 memory 排除在技能之外；
3. 让每个 Harness 自行适配技能的加载方式；
4. 分别测试源技能与面向 Harness 的元数据。

随后看它在各执行面的落地路径：

• Claude Code 通过 Claude plugin 面获得该技能，并能原生强制相关 hooks；
• Codex 读取仓库指令、.codex-plugin/plugin.json 与 MCP 参考配置，同一技能源仍能描述工作流，但 hook 对等性靠指令支撑（除非 Codex 未来增加原生 hook 面）；
• OpenCode 通过 package/plugin 面获得技能，事件处理可在适配层复用 ECC hook 逻辑，技能文本本身保持不变。

skills/hermes-imports/SKILL.md 内容本身也是一份极佳的反面示范教材——它定义了从 Hermes 导入工作流时的净化规则：本地路径转仓库相对路径或占位符、真实账号名替换为 operator/default profile 等角色标签、凭据需求只按 provider 名描述、绝不发布 ~/.hermes 路径或原始工作区导出。文档中的 Launch Handoff 与 Quiet-Hours Operator Job 两个示例清晰地展示了同一逻辑在净化前后的差异——本地化提示词变为"返回公共 release pack 下的 X 线程、LinkedIn 帖、录制清单与缺失资源清单"这类可公开复用的形态，其 Output Contract（候选技能名、净化摘要、公共输入、已移除的私有输入、剩余风险、待建文件）可作为技能入库前的验收清单。

今日能力与成熟中路线

从 docs/architecture/cross-harness.md 的路线图看，ECC 跨 Harness 能力的边界是透明的：

今天已支持：skills/ 共享技能源；Claude Code plugin 打包；Codex plugin metadata 与 MCP 参考配置；OpenCode package/plugin 面；Cursor 适配的 rules、hooks 与 skills；通过 CLI 与 opt-in MCP 适配器实现的 file-first 跨 Harness 内存；ecc2/ 作为 alpha 的 Rust 控制平面（ecc2/src/ 下已含 comms、config、session、tui、worktree、observability 等模块）。

仍在成熟中：跨所有 Harness 的精确 hook 对等性；向 Hermes 的自动化技能同步；ecc2/ 的发布打包；跨 Harness 会话恢复语义；可选的语义重排序与被治理的内存晋升工作流；完整平台回路（外部产品向 ECC 回馈 skill packs、gated APIs、evals 与案例研究）。

用合规矩阵把架构变成可验证的记分卡

要让"跨 Harness 架构"从设计文档变成可审计的事实，仓库提供了配套的 Harness Adapter Compliance Matrix。该矩阵的四类合规状态分别是：Native（ECC 可直接为该 Harness 安装/校验该表面）、Adapter-backed（ECC 有轻量适配器/插件/包，但各 Harness 对等性不同）、Instruction-backed（ECC 只提供指导与文件，Harness 不暴露 ECC 强制所需的运行时 hook/session 面）、Reference-only（仅作为设计压力或外部运行时，暂无直接安装器/适配器）。

矩阵本身由 scripts/lib/harness-adapter-compliance.js 渲染。从源码结构看，该文件把合规状态、必填字段（id、harness、state、supported_assets、unsupported_surfaces、install_or_onramp、verification_commands、risk_notes、last_verified_at、owner、source_docs）固化为常量与 freezeRecord 校验逻辑，并用 matrix-start/matrix-end 标记块与文档保持同步。校验器在公开的适配器声明缺少安装路径、验证命令、风险说明、owner、来源文档或验证日期时即判定失败——这保证了"声称 Native 就必须有安装路径与验证命令"这条操作规则可被自动执行。

对照 package.json 中的实际脚本定义（harness:adapters → scripts/harness-adapter-compliance.js、harness:audit → scripts/harness-audit.js、observability:ready → scripts/observability-readiness.js），官方给出的 Scorecard 上手指引如下：

npm run harness:adapters -- --check
npm run harness:audit -- --format json
npm run observability:ready
node scripts/session-inspect.js --list-adapters
node scripts/loop-status.js --json --write-dir .ecc/loop-status

各命令的判定语义（数据来源见 docs/architecture/harness-adapter-compliance.md）：

• harness:adapters -- --check：证明上述公开矩阵仍与适配器源数据及必填证据字段一致；
• harness:audit：对工具覆盖、上下文效率、质量门禁、内存持久化、eval 覆盖、安全护栏与成本效率打分；
• observability:ready：证明仓库仍暴露本地状态、会话、工具活动、风险台账与发布上手指引信号；
• session-inspect --list-adapters：列出当前环境中实际可检查的会话表面；
• loop-status --json：为更长的自主运行生成机器可读的交接/状态载荷。

新增工作流的黄金法则：把耐久行为先放进 ECC

架构文档以一条面向未来的"新工作流规则"收尾，这也是整个跨 Harness 体系最简明的决策标准：

当新增一个工作流时，先把耐久行为放进 ECC。Harness 专属文件只用于：加载共享资产、适配事件形态、映射命令名称、处理平台限制。如果一个工作流只能在某个 Harness 中运行，直接文档化这个边界，而不是假装它可移植。

与之配套的矩阵操作规则还包括：优先做小而增量的适配器，而非对同一工作流做 Harness 专属 fork；在适配器同时具备安装路径与验证命令之前，不得宣称该 Harness 为 Native；当 Codex、Gemini、Zed 的强制是 instruction-backed 而非 runtime-backed 时保持诚实；把 reference-only 工具当作设计压力对待；并始终保证 terminal-only 路径健康——因为它就是整个体系的可移植性下限（portability floor）。

综合来看，ECC 的跨 Harness 架构给出的是一条可复制的工程路线：共享源（skills/、rules/、hooks/、scripts/、mcp-configs/）沉淀耐久行为，Harness 适配层只做加载与翻译，Memory Vault 提供唯一的知识传递契约，Hermes 等操作者 Shell 只做单向的净化回流，而合规矩阵脚本把每一份公开声明都绑定到可验证的安装路径与验证命令上。这套模式既适合希望在多款 AI 编码工具间统一团队工程规范的技术负责人，也适合所有正在面对"Agent 工具碎片化"问题的工程团队参考。