鸭梨公共文档

主题

ECC (Everything Claude Code) 深度研究：AI 编程智能体的终极框架 ​

执行摘要 ​

ECC 是目前最完整的 AI 编程智能体框架之一，它不仅仅是一套配置文件，而是一个完整的智能体性能优化系统。该项目源自 Anthropic 黑客马拉松的获奖作品，经过 10 个多月的生产环境打磨，现已发展成为支持 Claude Code、Codex、Cursor、OpenCode、Zed 等 7+ 个主流 AI 编程工具的统一框架。

核心发现：

  1. 跨平台统一架构：ECC 通过适配器模式实现了真正的"一次编写，到处运行"
  2. 本能学习系统 v2.1：创新的项目级学习机制，支持置信度评分和技能进化
  3. Hook 驱动的自动化：基于事件钩子的工作流引擎，实现 100% 可靠的观察与响应
  4. 模块化技能系统：261+ 个可复用技能，覆盖 12+ 编程语言生态系统

1. 背景与研究范围 ​

1.1 项目起源 ​

ECC 由 Affaan Mustafa 创建，最初是 Claude Code 的配置集合。作者在 2025 年 9 月的 Anthropic x Forum Ventures 黑客马拉松中，完全使用 Claude Code 构建了 zenith.chat 项目并获奖。此后，ECC 从一个简单的配置仓库演变为一个完整的智能体工作流框架。

1.2 研究边界 ​

本研究聚焦于以下核心维度：

  • 架构设计：模块化组件如何协同工作
  • 技能系统：SKILL.md 规范与自动激活机制
  • Hook 引擎：事件驱动的工作流自动化
  • 持续学习 v2.1：本能学习与技能进化
  • 跨平台适配：多 IDE/CLI 的统一抽象层

2. 核心架构分析 ​

2.1 整体架构概览 ​

ECC 采用分层架构设计，各层之间通过明确定义的接口进行交互：

2.2 组件详解 ​

2.2.1 技能系统 (Skills) ​

技能是 ECC 的主要工作流表面，采用 SKILL.md 格式定义：

markdown
---
name: skill-name
description: 用于自动激活的简要描述
origin: ECC
---

# 技能标题

## 何时激活
描述 Claude 应该使用此技能的场景

## 核心概念
主要模式和指导原则

## 代码示例
实用的、经过测试的示例

## 反模式
展示不应该做什么的具体示例

## 相关技能
链接到互补技能

关键洞察：SKILL.md 的 YAML frontmatter 不仅用于元数据，更是智能体路由的关键信号。描述字段的质量直接影响自动激活的准确率。

2.2.2 智能体系统 (Agents) ​

ECC 包含 64 个专门的子智能体，按功能域组织：

功能域代表智能体职责
代码审查code-reviewer质量、安全、可维护性审查
构建修复go-build-resolver特定语言的构建错误修复
测试驱动tdd-guideTDD 工作流指导
架构设计architect系统设计决策
安全审计security-reviewer漏洞分析

每个智能体定义采用标准格式：

markdown
---
name: agent-name
description: 智能体描述
tools: ["Read", "Grep", "Glob", "Bash"]
model: opus
---

你是高级代码审查员...

2.2.3 钩子引擎 (Hooks) ​

Hook 是 ECC 的自动化核心，基于事件驱动架构：

关键发现：ECC v2.0 将 Hook 系统从简单的 Shell 脚本演进为完整的 Node.js 运行时，支持跨平台（Windows/macOS/Linux）兼容。

3. 持续学习系统 v2.1 ​

3.1 架构演进 ​

ECC 的学习系统经历了两个主要版本的演进：

特性v1 (已弃用)v2.1 (当前)
观察机制Stop Hook (会话结束)PreToolUse/PostToolUse (100% 可靠)
分析方式主上下文后台智能体 (Haiku)
粒度完整技能原子"本能"
置信度无0.3-0.9 加权
进化路径直接到技能本能 → 聚类 → 技能/命令/智能体
共享机制无导出/导入本能

3.2 本能学习流程 ​

3.3 项目级隔离 ​

关键洞察：ECC v2.1 引入了项目级本能的概念，防止跨项目污染：

text
${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/
+-- projects/
|   +-- a1b2c3d4e5f6/       # 项目哈希（来自 git remote URL）
|   |   +-- instincts/
|   |   |   +-- personal/   # 项目特定自动学习
|   |   |   +-- inherited/  # 项目特定导入
|   |   +-- evolved/
|   |       +-- skills/
|   |       +-- commands/
|   +-- f6e5d4c3b2a1/       # 另一个项目

4. 跨平台适配机制 ​

4.1 适配器模式 ​

ECC 采用DRY 适配器模式实现跨平台支持：

4.2 功能对比矩阵 ​

特性Claude CodeCursorCodexOpenCodeGitHub Copilot
智能体6448共享 AGENTS.md12不支持
命令84共享指令式356 prompts
技能261共享1037指令式
Hook 事件8 类型15 类型无11 类型无
Hook 脚本20+16 (DRY)无插件 Hooks无
规则3434 (YAML)指令式131 文件

5. 安装与部署架构 ​

5.1 选择性安装系统 ​

ECC 2.0 引入了清单驱动的安装管道，支持细粒度组件选择：

bash
# 咨询式安装 - 自然语言查询
npx ecc consult "security reviews" --target claude

# 配置文件驱动安装
ecc install --config ecc-install.json

# 技能级安装
npx ecc install --skills continuous-learning-v2 --target claude

5.2 安装状态管理 ​

ECC 维护安装状态合约 (install-state)，实现可追踪、可修复的部署：

json
{
  "schemaVersion": "ecc.install.v1",
  "installedAt": "2026-03-13T00:00:00Z",
  "target": {
    "id": "claude-home",
    "root": "/Users/example/.claude"
  },
  "request": {
    "profile": "developer",
    "modules": ["orchestration"]
  },
  "resolution": {
    "selectedModules": [...]
  }
}

6. 关键洞察 ​

6.1 架构设计亮点 ​

  1. Hook 优先于 Skill 观察：v2 架构的核心洞察是——技能激活是概率性的（50-80% 触发率），而 Hook 是确定性的（100% 可靠）。因此将观察逻辑从技能移至 Hook 层。

  2. 原子本能 vs 完整技能：将学习粒度从"完整技能"降至"原子本能"，配合置信度评分，实现了更精细的学习与进化控制。

  3. 项目级隔离：通过 git remote URL 哈希实现项目级本能隔离，防止不同项目的上下文污染。

6.2 工程实践洞察 ​

  1. 跨平台兼容性：所有脚本使用 Node.js 重写，确保 Windows/macOS/Linux 三平台兼容，这是许多类似项目忽视的关键点。

  2. DRY 适配器模式：Cursor 的 16 个 Hook 脚本实际上都复用 Claude Code 的 scripts/hooks/*.js，通过适配器转换输入格式，避免代码重复。

  3. Schema 验证：从 ECC 2.0 开始，所有配置文件都有对应的 JSON Schema，确保类型安全和向后兼容。

6.3 局限性与注意事项 ​

  1. MCP 工具膨胀：启用过多 MCP 服务器会严重消耗上下文窗口（200k 可降至 70k），ECC 建议保持 10 个 MCP 以内、80 个工具以内。

  2. Hook 重复注册风险：Claude Code v2.1+ 会自动加载插件的 hooks/hooks.json，手动复制到 settings.json 会导致重复执行。

  3. Token 消耗：Agent Teams 功能会同时启动多个上下文窗口，每个智能体独立消耗 Token，不适合简单顺序任务。

7. 应用场景与实践建议 ​

7.1 适用场景 ​

  • 多语言开发团队：需要统一的代码审查和构建修复流程
  • 长期维护项目：利用持续学习积累项目特定知识
  • 跨平台开发：需要在 Claude Code、Cursor、Codex 之间切换的团队
  • 安全敏感项目：需要系统化的安全审计流程

7.2 快速开始建议 ​

bash
# 1. 克隆仓库
git clone https://github.com/affaan-m/ECC.git
cd ECC

# 2. 安装依赖
npm install

# 3. 选择式安装（推荐）
node scripts/install-plan.js --profile minimal --target claude
node scripts/install-apply.js --profile minimal --target claude --dry-run

# 4. 启用持续学习 v2.1
npx ecc install --skills continuous-learning-v2 --target claude

8. 参考资料 ​

9. 总结 ​

ECC 代表了 AI 编程智能体框架的工程化成熟阶段。它不仅仅是配置的集合，而是通过系统化的架构设计解决了以下核心问题：

  1. 可复用性：SKILL.md 规范实现了知识的模块化与可复用
  2. 可靠性：Hook 驱动的自动化确保 100% 的执行覆盖率
  3. 可进化性：本能学习系统让框架能够随使用自我改进
  4. 可移植性：适配器模式实现了真正的跨平台支持

对于希望提升 AI 编程工具效能的开发者和团队，ECC 提供了一个经过生产验证的完整解决方案。

本文研究日期：2026年6月10日
ECC 版本：v2.0.0-rc.1
项目 Stars：182K+ | Forks：28K+ | 贡献者：170+