跨执行载体架构¶

ECC 是可复用的工作流层。执行载体是执行面。

目标是将智能体工作中持久化的部分保存在一个仓库中：

• 技能
• 规则与说明
• 在执行载体支持的地方使用钩子
• MCP 配置
• 安装清单
• 会话与编排模式
• 持久的、执行载体无关的记忆文档

Claude Code、Codex、OpenCode、Cursor、Gemini 以及未来的执行载体应在边缘适配这些资产，而不是为每个工具要求一套新的工作流模型。

如需查看面向操作者的支持矩阵和记分卡工作流，请参阅
执行载体适配器合规矩阵。
如需查看全栈平台框架和产品集成循环，请参阅
ECC 平台价值循环。

可移植性模型¶

原样迁移的内容¶

SKILL.md 是最可移植的单元。

一个好的 ECC 技能应当：

• 使用带有 name、description 和 origin 的 YAML frontmatter
• 描述何时使用该技能
• 说明所需工具或连接器，而不嵌入密钥
• 保持示例为仓库相对路径或通用示例
• 避免假设仅限执行载体的命令，除非该部分已明确标注

同一个源技能可以安装到多个执行载体中，因为它主要由说明、约束和工作流形态组成。

需要适配的内容¶

每个执行载体都有不同的加载和强制执行行为：

• Claude Code 加载插件资产，并具有原生钩子执行能力。
• Codex 读取 AGENTS.md、插件元数据、技能和 MCP 配置，但钩子一致性由说明驱动。
• OpenCode 具有插件/事件系统，可以通过适配层复用 ECC 钩子逻辑。
• Cursor 使用自己的规则和钩子布局，因此 ECC 在 .cursor/ 下维护翻译后的界面。
• Gemini 支持以安装/说明为导向，应将其视为兼容性界面，而非完整的钩子一致性。

适配器应保持轻量。共享行为应放在 skills/、rules/、hooks/、scripts/ 和 mcp-configs/ 中。

共享记忆契约¶

该契约的会话快照部分（ecc.session.v1）在
session-adapter-contract.md 中定义。

ECC Memory Vault 是 Claude、Codex、Hermes、Cursor、OpenCode 和其他智能体的通用知识传递界面。它在三个作用域中存储可移植的
ecc.memory.v1 Markdown 文档：

• 项目：<repo>/.ecc/memory/project/
• 团队：<repo>/.ecc/memory/team/
• 用户：~/.ecc/memory/

每个执行载体必须使用相同的仓库工作目录，或相同的
ECC_MEMORY_PROJECT_ROOT 和 ECC_MEMORY_USER_ROOT 覆盖值。确定性的
ecc memory CLI 是基线接口。支持 MCP 的执行载体也可以改为启动
ecc-memory-mcp，并使用 memory_save、memory_search、
memory_read 和 memory_doctor。常规搜索召回在 project 和 team 中仅召回活动条目；直接按 ID 读取可以检查非活动条目，而
user 必须显式请求。CLI 目标标志是调用方选择的路由过滤器，而不是授权边界。

MCP 服务器是可选启用的。其参考条目位于
mcp-configs/mcp-servers.json；它被有意从默认
.mcp.json 中省略，以免安装过程静默获得可写的上下文界面或承担其工具模式成本。每个 MCP 进程都需要小写的
ECC_MEMORY_HARNESS；这个绑定到服务器的身份提供源执行载体和目标过滤器，因此工具调用方无法选择另一个身份。除非操作者使用
ECC_MEMORY_ALLOW_USER_SCOPE=1 启动进程，否则用户作用域的 MCP 访问仍被阻止。

信任边界在所有适配器中保持一致：

• 所有首次发布的 vault 条目仅可创建，且始终为 unreviewed；
• 召回的记忆是数据，而不是可执行指令；
• 已知密钥形状的写入会作为尽力而为的最后防线被拒绝，并且读取器不跟随符号链接；
• 如果 vault 的保护性 .gitignore 被修改，项目作用域写入将停止；
• 人工接受会将知识提升为受治理的仓库工件；它永远不会将记忆 frontmatter 变成自我声明的批准；
• 活动执行状态保留在 GitHub 或 Linear 中，而不仅仅在记忆中。

skills/unified-memory/SKILL.md 拥有此工作流。Codex 和 Cursor 在
.agents/skills/ 和 .cursor/skills/ 下接收行为一致的打包副本；Hermes 可以导入规范技能。没有任何执行载体拥有单独的权威记忆存储。

Hermes 边界¶

Hermes 不是公开的 ECC 运行时。

Hermes 是一个可以消费 ECC 资产的操作者外壳：

• 将选定的 ECC 技能导入 Hermes 技能目录
• 使用 ECC MCP 约定进行工具访问
• 通过可复用的 ECC 模式路由聊天、CLI、cron 和交接工作流
• 将重复的本地操作者工作提炼回脱敏的 ECC 技能

公共仓库应提供可复用模式，而不是本地 Hermes 状态。

应包含：

• 已脱敏的配置文档
• 相对于仓库的演示提示词
• 通用操作员技能
• 不依赖私有凭据的示例

不应包含：

• OAuth 令牌或 API 密钥
• 原始 ~/.hermes 导出
• 个人工作区记忆
• 私有数据集
• 未经审查的仅限本地的自动化包

实际示例¶

在多个框架中使用 skills/hermes-imports/SKILL.md 作为相同的技能源。

工作流如下：

1. 在 skills/hermes-imports/SKILL.md 中一次性编写持久行为。
2. 将密钥、本地路径和原始操作员记忆排除在技能之外。
3. 让每个框架自行适配技能的加载方式。
4. 分别测试源技能和面向框架的元数据。

Claude Code 通过 Claude 插件接口获取该技能，并可以原生执行相关钩子。

Codex 读取仓库说明、.codex-plugin/plugin.json 和 MCP 参考配置。相同的技能源仍然描述该工作流，但除非 Codex 添加原生钩子接口，否则钩子一致性由指令支撑。

OpenCode 通过 OpenCode 包/插件接口获取该技能。事件处理可以通过适配层复用 ECC 钩子逻辑，同时技能文本保持不变。

如果某项更改需要编辑同一工作流的三个框架副本，则共享源的位置不正确。请将工作流放回 skills/，然后仅在框架边缘适配加载、事件形状或命令路由。

当前与后续¶

当前支持：

• skills/ 中的共享技能源
• Claude Code 插件打包
• Codex 插件元数据和 MCP 参考配置
• OpenCode 包/插件接口
• Cursor 适配的规则、钩子和技能
• 通过 CLI 和可选 MCP 适配器实现的以文件优先的跨框架记忆
• 作为 alpha Rust 控制平面的 ecc2/

仍在完善：

• 所有框架之间的精确钩子一致性
• 自动将技能同步到 Hermes
• ecc2/ 的发布打包
• 跨框架会话恢复语义
• 可选的语义重排序和受治理的记忆晋升工作流
• 完整的平台闭环，外部产品将技能包、 受控 API、评估和案例研究贡献回 ECC

新工作规则¶

添加工作流时，先将持久行为放入 ECC。

仅将框架特定文件用于：

• 加载共享资产
• 适配事件形状
• 映射命令名称
• 处理平台限制

如果某工作流仅在一个框架中可用，请直接记录该边界。