第 2 章：总体架构与主数据流
四层架构
把 ECC 的文件按“谁消费它”分成四层，比按目录罗列更容易理解：
┌────────────────────────────────────────────────────────────┐
│ Harness 表面：Claude Code · Codex · Cursor · OpenCode · ... │
├────────────────────────────────────────────────────────────┤
│ 适配层：.claude-plugin / .codex / .cursor / .opencode / ... │
├────────────────────────────────────────────────────────────┤
│ 控制层：installer · manifests · install-state · doctor │
├────────────────────────────────────────────────────────────┤
│ 内容与运行时：agents · skills · commands · rules · hooks │
│ scripts · memory · mcp-configs · tests │
└────────────────────────────────────────────────────────────┘
底层资产不是简单的“复制源文件”。安装器会先读取 manifests/install-components.json、install-modules.json、install-profiles.json，解析依赖和目标，再产出操作计划；执行后写入 ecc.install.v1 状态，供 doctor、repair 和 uninstall 继续使用。
一次安装的时序
用户选择 profile / module / component / target
↓
scripts/ecc.js：解析命令，统一转发子命令
↓
install-manifests.js：读取 81 components、34 modules、7 profiles
↓
resolveInstallPlan：依赖闭包 + target 过滤 + 排序
↓
install target adapter：决定用户级/项目级目标路径和合并策略
↓
install-executor / install-lifecycle：复制、合并、构建、记录状态
↓
目标 harness 读取 agents / skills / commands / hooks
这里有两个关键点。
第一，manifest 是产品选择器，脚本是执行器。选择器描述“想要什么”，执行器处理文件系统、JSON merge、OpenCode 构建产物和安全路径检查。第二，target 是语义而不是目录名：同一个 commands-core 在 Claude、Cursor、OpenCode 的投影路径和策略可以不同。
一次会话的时序
SessionStart
├─ session-start：加载有界历史上下文、检测项目
└─ plan-canvas：恢复未完成的审查/计划状态
↓
Agent 选择 skill / agent / command 并调用工具
↓
PreToolUse：安全、tmux、配置保护、治理捕获、观察
↓
工具执行
↓
PostToolUse：质量门、格式化、typecheck、构建分析、会话活动
↓
Stop：console.log 审计、session summary、学习与成本标记
↓
SessionEnd：生命周期标记与最终持久化
hooks/hooks.json 的注册表是运行时事实，hooks/memory-persistence/ 是面向人阅读的稳定契约；两者刻意分开，使实现可以演进而不破坏生命周期语义。
为什么这种架构可扩展
- 内容与执行解耦：新增领域能力通常只需加 skill/agent，不必改安装器。
- 安装与宿主解耦：新增 harness 主要增加 adapter/scaffold，而不复制全部内容。
- 强制与建议分离：规则/hook 可以阻断，skill/command 更适合作为指导和入口。
- 状态可追踪：install-state 记录请求、解析结果、源版本和操作，修复不是盲目重新复制。