ECC 架构设计与核心组件

调研日期：2026-05-25

一、整体架构分层

ECC 采用四层架构设计，每层通过显式契约解耦，技能层是核心可移植单元。

分层总览

┌─────────────────────────────────────────────┐
│             插件 / 市场层                      │  ← .claude-plugin/、marketplace.json
│  自托管 marketplace + 插件安装                │
├─────────────────────────────────────────────┤
│             技能层 (Skills Layer)              │  ← .agents/skills/ (最核心)
│  SKILL.md + agents/ 子目录                    │
│  可移植性最高，跨 harness 共享                  │
├─────────────────────────────────────────────┤
│             钩子层 (Hooks Layer)               │  ← hooks/、scripts/hooks/
│  会话生命周期钩子 (Pre/Post ToolUse)           │
├─────────────────────────────────────────────┤
│             规则层 (Rules Layer)               │  ← rules/ (语言/框架专属)
│  CLAUDE.md 级别的约束和规则                    │
├─────────────────────────────────────────────┤
│             基础设施层                          │  ← scripts/、mcp-configs/、commands/
│  安装脚本、MCP 配置、命令路由                   │
└─────────────────────────────────────────────┘

层间关系

• 技能层是最核心的可移植单元，一个 SKILL.md 可以在 7 个 harness 间共享
• 钩子层和规则层是 harness-specific 的适配面
• 插件层解决发现和安装问题，不改变其他层的逻辑
• 基础设施层提供 CLI/MCP/Script 的执行能力

二、插件模型

ECC 使用 Claude Code 原生的插件机制。

plugin.json 结构

{
  "name": "ecc",
  "version": "2.0.0-rc.1",
  "skills": ["./skills/"],
  "commands": ["./commands/"],
  "mcpServers": {},
  "license": "MIT"
}

关键设计决策：

• 扁平结构 — skills 和 commands 直接指向目录，按 convention 自动发现
• 增量加载 — 插件只注册路径，实际按需加载
• 零运行时依赖 — 插件本身不注入运行时，所有执行由 harness 原生能力完成
• 自托管 marketpace — marketplace.json 指向 GitHub 仓库，不走 Anthropic 官方市场

自托管市场

/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

插件标识符 ecc@ecc 的设计考虑：保持命名空间足够短，兼容 Claude Desktop/API 的严格校验器。

三、安装体系

安装流水线

ECC 的安装系统经历了三个迭代阶段：

1. v1.x： 单一 install.sh 脚本，全量安装
2. v1.9.0： Manifest 驱动，选择性安装
3. v2.0.0： install-plan.js + install-apply.js，增量更新

安装组件

install-plan.js        → 分析当前环境，生成安装计划
install-apply.js       → 执行安装计划
State store (SQLite)   → 追踪已安装组件，支持增量更新

三种安装路径

⚠️ 混装风险（ECC 官方反复强调）： 如果已通过 /plugin install​ 安装，再运行 ./install.sh --profile full，会造成 skills + hooks 重复注册，运行时行为不可预期。

Profile 系统

Profile 可以交叉组合：--profile minimal --with capability:machine-learning

包管理器自动检测

ECC 自动检测 npm/pnpm/yarn/bun，优先级：
CLAUDE_PACKAGE_MANAGER 环境变量 > 项目配置 > package.json > 锁文件 > 全局配置 > 回退

四、技能系统 (Skills)

SKILL.md 规范

每个技能是一个目录下的 SKILL.md 文件，使用 YAML frontmatter：

---
name: "skill-name"
description: "一句话描述技能适用场景"
origin: "ecc"
---

每个技能还可以附带 agents/ 子目录（存放 Agent 定义 + openai.yaml 兼容层）。

技能的三大特性

1. 可移植性最好 — 纯指令集，不依赖 harness 特定 API
2. 可组合 — 技能之间通过引用/继承组合，形成 skill packs
3. 自描述 — frontmatter + 规则内容自带判断条件

Skill Packs（技能包）

ECC 在 v2.0.0 引入了 Skill Pack 概念，将相关技能聚合为有边界的集合：

• 优化包：parallel-execution-optimizer, benchmark-optimization-loop, data-throughput-accelerator, latency-critical-systems, recursive-decision-ledger
• 预测市场包：ito-market-intelligence, ito-basket-compare, ito-trade-planner, ito-data-atlas-agent, prediction-market-oracle-research
• 框架包：nestjs-patterns, pytorch-patterns, bun-runtime, nextjs-turbopack

Skills 数量演进

五、钩子系统 (Hooks)

钩子类型

ECC 定义了三类钩子，对应 Claude Code 的工具调用生命周期：

• PreToolUse — 工具调用前拦截，可用于安全检查、频率限制
• PostToolUse — 工具调用后处理，可用于结果验证、日志记录
• Stop — 停止信号，可用于中断执行链条

钩子运行时控制

export ECC_HOOK_PROFILE=standard    # strict / standard / relaxed
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

关键钩子

• session-start.js — 会话启动时加载上下文
• session-end.js — 会话结束时保存状态
• pre-compact.js — 上下文精简前状态保存
• suggest-compact.js — 策略性精简建议
• evaluate-session.js — 从会话中提取模式

六、状态存储

ECC 使用 SQLite 作为本地状态存储引擎：

• 记录已安装的组件清单
• 追踪会话状态
• 存储本能/直觉的置信度评分
• 通过 query CLI 可交互式查询

状态存储覆盖三层：

Install state     → 哪些组件已安装、版本号
Session state     → 会话 ID、持续时间、工具调用记录
Learning state    → 本能条目、置信度分数、来源记录

七、跨 Harness 适配架构

这是 ECC 架构中最有亮点的设计。

可移植性矩阵

核心设计原则

“把耐用的行为放在 skills/ 中，每个 harness 只在边缘做适配（loading、event shape、command routing）”

这意味着：如果要修改一个工作流，只需要改 skills/ 下的一个文件，不用改 7 个 harness。Harness 适配层只负责”怎么加载”和”事件怎么映射”，不负责”行为是什么”。

当前支持情况

八、文件布局

everything-claude-code/
├── .claude-plugin/          # 插件注册与市场元数据
│   ├── plugin.json
│   └── marketplace.json
├── .agents/
│   ├── plugins/             # 跨 harness 安装工具
│   └── skills/              # 243 个可移植技能 ← 核心
├── agents/                  # 60 个 Agent 定义 // 下一代
├── skills/                  # 传统技能目录 // 兼容
├── commands/                # Slash commands + CLI shims
├── hooks/                   # 钩子定义 + 运行时
│   ├── hooks.json
│   ├── memory-persistence/
│   └── strategic-compact/
├── rules/                   # 语言/框架专属规则（12 语言）
├── scripts/                 # 跨平台 Node.js 工具
├── mcp-configs/             # MCP 服务端配置
├── contexts/                # 动态系统提示上下文
├── examples/                # 各框架 CLAUDE.md 示例
├── tests/                   # 测试套件
├── ecc2/                    # Rust 控制面原型
├── install-plan.js          # 安装计划生成
└── install-apply.js         # 安装执行

九、关键架构决策总结

十、与 PE 工程组架构的对照

ECC 的架构思路与点点正在构建的产线平台化有一些值得借鉴的对应关系：

• SKILL.md 作为可移植单元 → 对应产线的观测单元（最小不可分割的数据/评估单元）
• Manifest 安装流水线 → 对应产线平台化的自动化 pipeline 设计
• Edge-only 适配层 → 对应双角色设计（策略工程师 + 技术工程师）的职责边界
• SQLite State Store → 对应数据质量的追踪审计需求
• 组件式 Profile → 对应差异化场景的灵活组装策略