ECC开源项目分析

affaan-m/ECC 完整实现原理拆解

一、项目基础定位

全称：Agent Harness Performance Optimization System（智能体调度性能优化框架）

技术栈：纯 JavaScript 构建，兼容 Node.js / 浏览器双端

适配客户端：Claude Code、OpenAI Codex、OpenCode、Cursor 全部主流 AI 代码编辑器插件

核心目标：解决 AI 编码智能体三大痛点------上下文溢出、工具调用混乱、安全权限失控、多轮思考低效。

当前数据：总星标 198560，本周新增 10239（涨幅 5.16%），累计星标 208799。

二、整体架构分层（自底向上）

1. 底层：Memory 分层记忆引擎（核心模块）

原生 AI 工具缺陷：对话上下文无淘汰机制，代码文件、历史指令、工具返回结果全部塞入 Prompt，长会话 Token 爆炸、推理速度暴跌。

ECC 实现方案：

1. 三级存储分层

◦ 瞬时记忆（上下文窗口）：仅保留当前任务最近 3 轮交互，实时截断冗余代码片段；

◦ 短期记忆（内存哈希池）：缓存当前项目打开文件、函数签名、导入依赖，自动提取代码摘要替代完整源码；

◦ 长期记忆（本地 JSON/CSV 持久化）：按任务标签归档历史解决方案、报错修复方案、库版本适配记录，仓库自带 CSV 用于批量导出记忆库。

2. 相关性召回算法

   基于代码 AST 结构+指令语义向量匹配，当 Agent 接收到新编码需求，只拉取高度相关历史记录，而非全部上下文；

3. 自动遗忘策略

   闲置超过阈值的记忆块自动降权，低权重内容在 Token 不足时优先剔除，避免手动清理会话。

4. 中层：Skills & Instincts 智能工具调度层

Skills = 标准化工具调用封装；Instincts = 内置决策推理逻辑

1. Skill 统一抽象协议

   抹平不同 AI 客户端（Cursor/Claude Code）工具调用格式差异，统一入参、返回体、错误捕获结构，一套工具逻辑多平台复用。

   内置开箱即用 Skill：文件读写、Git 操作、终端命令、依赖安装、语法校验、单元测试生成、API 请求。

2. Instincts 自主决策内核（项目核心创新）

   普通 Agent：人类每一步下发指令，被动执行；

   ECC 优化：内置规则推理链，Agent 自主判断下一步动作：

◦ 需求解析 → 自动判断是否需要读取本地代码；

◦ 代码修改后自动触发语法校验 Skill；

◦ 报错自动检索长期记忆匹配同类问题修复方案；

◦ 多文件改动自动生成 Git commit 描述，无需人工指令。

3. 工具调用限流与缓存

   重复文件读取、重复终端指令做结果缓存，减少重复 IO 与 LLM 交互，大幅降低接口耗时与 Token 消耗。

4. 安全沙箱管控层（Security 独立隔离模块）

解决 AI 工具高危操作风险（删除文件、执行危险 shell、访问系统敏感目录）

1. 权限分级白名单

◦ 只读权限：读取源码、查看 Git 日志；

◦ 受限写入：仅允许修改项目内代码文件；

◦ 高危操作阻断：rm -rf、系统目录读写、网络外发本地文件默认拦截；

2. 操作审计日志

   所有文件修改、终端调用记录写入本地日志，支持导出 CSV 审计；

3. 敏感信息过滤

   自动扫描代码内密钥、token、数据库密码，拦截带入 LLM Prompt，防止泄露。

4. 顶层：Research-First 研发调度入口

框架对外统一入口，面向开发者的工作流编排层，对接各类 AI 编码客户端：

1. 预调研前置流程

   接收编码需求后，先自动执行一轮调研：拉取项目依赖版本、读取文档、检索记忆历史，再将精简调研结果送入 LLM，避免模型无依据空想；

2. 多客户端适配器

   内置适配层转换不同代码助手的 Prompt 格式、窗口上下文协议，无需修改原有 Cursor/Claude Code 配置，直接接入 ECC 调度；

3. 性能指标监控

   实时统计 Token 消耗、推理耗时、工具调用次数、上下文压缩率，日志写入仓库 CSV 文件，用于调优框架自身参数。

三、完整工作流程（一次编码任务全链路）

1. 用户在 Cursor/Claude Code 下发编码需求；

2. ECC Research 模块启动前置调研：读取当前项目结构、召回长期记忆相关历史方案；

3. Memory 引擎对调研数据做摘要压缩，过滤无关代码片段，控制总 Token 长度；

4. Instincts 推理判断需要调用哪些文件/终端工具，生成标准化 Skill 调用指令；

5. Security 沙箱校验所有操作是否在白名单内，拦截高危行为；

6. 指令转发至对应 AI 模型获取代码输出；

7. 返回代码写入本地文件，自动触发语法校验 Skill；

8. 本次任务全部交互、代码改动、工具记录分层存入三级记忆库，追加日志至 CSV。

四、性能优化核心原理（为什么星标暴涨）

1. 上下文压缩降本

   通过记忆分层+AST 摘要，长会话 Token 消耗平均降低 40%~70%，减少 LLM 计费与响应延迟；

2. 自主执行减少交互轮次

   Instincts 自动串联读文件、改代码、校验、测试全流程，原本 5~8 轮人工指令压缩至 1~2 轮；

3. 跨客户端统一抽象

   无需为每个代码 AI 单独写工具脚本，一套 JS 框架全平台复用，降低二次开发成本；

4. 轻量化无依赖

   原生 JavaScript，无重型编译依赖，Windows/macOS/Linux 本地一键运行，开箱即用。

五、仓库 CSV / 日志文件作用

1. CSV：结构化存储记忆快照、性能监控指标、安全审计记录，支持 Excel 查看、批量导入导出记忆库；

2. 仓库日志：记录框架版本更新、内置 Skill 新增、安全规则迭代、适配客户端更新记录，用于排查兼容性问题。

六、技术局限补充

1. 基于规则+轻量语义召回，无独立大模型，依赖外接 Claude / Codex 等模型完成代码生成；

2. 记忆向量匹配仅轻量本地实现，无向量数据库，超大型项目（万行以上）召回精度会下降；

3. 安全策略为本地静态白名单，无动态风险识别，复杂自定义 shell 命令仍需人工配置放行。

ECC（affaan-m/ECC）使用方式完整说明

一、核心定位：分两种接入模式

1. 首选：Claude Code 内置插件（完整功能）

   ECC 原生是 Claude Code 插件，依托 Claude Code 插件市场安装，能解锁全部能力：自定义 /ecc: 命令、60个专用子Agent、232套工具技能、自动钩子、分层记忆引擎、安全沙箱完整调度。

2. 兼容模式：Cursor / Opencode / Codex 纯规则配置（阉割版）

   Cursor 没有插件市场，不能装插件，只能手动复制 rules/hooks 配置文件，仅能使用上下文优化、代码规范、记忆压缩；无法使用插件命令、自动Agent调度、完整技能链。

3. 独立脚本部署（自研/本地自定义AI）

   不依赖编辑器，直接克隆仓库运行 Node 脚本，对接任意代码大模型做中间调度层。

二、Claude Code 插件完整安装流程（推荐，功能最全）

前置依赖

Node.js ≥18、Git、Claude Code 客户端（终端 claude 命令可用）

步骤1：添加ECC插件市场源

打开 Claude Code 对话输入框执行：

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

步骤2：安装ECC核心插件

/plugin install ecc@ecc

校验安装：

/plugin list ecc@ecc

出现插件信息即成功，插件会自动加载所有 Agent、Skill、调度逻辑。

步骤3：必做！手动复制规则文件（插件无法自动分发规则）

插件仅负责调度引擎，上下文约束、记忆策略、安全白名单规则需要本地落地：

克隆仓库拿规则文件

git clone https://github.com/affaan-m/ECC.git

cd ECC

创建全局规则目录

mkdir -p ~/.claude/rules/ecc

复制通用基础规则（必须）

cp -r rules/common ~/.claude/rules/ecc/

按需复制你项目所用语言（示例TS/JS，其他自行替换）

cp -r rules/typescript ~/.claude/rules/ecc/

Windows 使用 PowerShell 复制对应目录即可。

步骤4：插件基础使用命令

安装完成后直接在 Claude Code 调用 ECC 专属指令：

自动拆解需求、生成完整开发方案（最常用）

/ecc:plan "开发用户登录接口，包含密码加密与JWT鉴权"

全局配置ECC记忆、安全、Token压缩参数

/ecc:configure

查看本次会话性能统计、Token消耗、记忆召回日志

/ecc:stats

导出本次任务审计/记忆CSV日志

/ecc:export-log

启动后自动生效三层记忆、工具自动调度、高危操作拦截，无需额外操作。

三、Cursor 编辑器接入（无插件，仅配置文件）

Cursor 不支持 Claude 插件体系，无法执行 /plugin 命令，只能手动部署规则与钩子，仅保留上下文优化、代码校验、记忆持久化能力：

1. 克隆仓库
   git clone https://github.com/affaan-m/ECC
   cd ECC
2. 复制 Cursor 专用规则、钩子到全局目录

全局生效所有项目

cp -r .cursor/rules/* ~/.cursor/rules/

cp -r .cursor/hooks/* ~/.cursor/hooks/

3. 重启 Cursor，内置 Composer、对话会自动加载 ECC 上下文压缩策略

限制：无 /ecc: 指令、无自动Agent链式执行、工具调用需要手动引导AI。

四、独立脚本部署（不依赖编辑器，通用中间层）

适合 Opencode、自研本地代码Agent、第三方大模型接入，作为独立 JS 调度服务：

1. 克隆仓库安装依赖
   git clone https://github.com/affaan-m/ECC
   cd ECC
   npm install
2. 一键安装全量配置

目标平台可选 claude / cursor / custom

minimal 轻量化模式，full完整全量技能

./install.sh --profile minimal --target custom

3. 启动调度服务

node src/harness.js

可对接任意代码模型 API，自定义记忆存储、安全规则，作为独立中间件拦截、优化所有Prompt与工具调用。

五、关键注意事项

1. 插件安装与脚本部署二选一，禁止混用

   同时安装会重复加载技能、上下文Token爆炸、工具调用冲突。

2. 插件模式优势（Claude Code）

   自动多轮自主执行、内置60个垂直开发Agent、一键导出CSV日志、完整安全审计、自动遗忘记忆策略全部可用。

3. Cursor 局限性

   缺失自主决策 Instincts 内核，无法自动串联「读文件→改代码→校验→测试」完整流程，只能辅助精简上下文。

4. 卸载方式

• 插件：/plugin uninstall ecc@ecc，删除 ~/.claude/rules/ecc 目录

• Cursor：删除 _{/.cursor/rules、}/.cursor/hooks 内ECC相关文件

六、日常工作流（插件模式完整流程）

1. 打开 Claude Code，输入 /ecc:plan 需求

2. ECC Research 模块自动扫描项目结构、召回历史记忆

3. Memory 引擎压缩冗余代码，控制Token消耗

4. Instincts 自主判断需要读写文件、执行终端、语法校验

5. Security 沙箱拦截高危操作

6. 完成后自动保存本次交互到长期记忆，可 /ecc:export-log 导出CSV记录