第 15 期 · 2026-11-15
affaan-m/ECC — Agent Harness 的性能优化操作系统
第 15 期:affaan-m/ECC——给 AI 编程助手装上的一套“操作系统”,让 Claude Code、Codex、Cursor 共用同一套工作流。
一句话定位
ECC(Everything Claude Code 的后继者,现名 ECC)是一套 Agent Harness 性能优化系统:它不提供模型,而是把“怎么做事”沉淀成 314 个技能、71 个子代理、98 条斜杠命令、8 类生命周期钩子和一套可跨 Harness 复用的规则与记忆机制,让同一套工程习惯在 Claude Code、Codex、OpenCode、Cursor 等多个 AI 编程工具里通用。
源码结构
实测浅克隆 71 MB(不含 .git)、4,701 个文件。其中 Markdown 2,878 个文件、共 527,230 行——这首先是一个以文档为载体的仓库,代码反而是少数:JavaScript 1,019 个文件、Python 169 个、TypeScript 仅 21 个。仓库根目录就是事实来源,README 开宗明义:“The root is the source of truth. Platform adapters package or map these same workflows instead of maintaining separate copies.”
核心目录按职责分层,README“What's Inside”一节的清单与实测目录树完全一致:
skills/:314 个技能,每个技能一个目录、一份SKILL.md,技能 Markdown 合计 97,397 行,是仓库最大的内容资产。覆盖编码规范(python-patterns、golang-patterns、cpp-coding-standards)、前后端模式、Django/Laravel/Spring Boot/Quarkus/Rails 各栈的 patterns-security-tdd-verification 四件套,以及tdd-workflow、security-review、verification-loop、continuous-learning-v2、osint-investigation、market-research等通用工作流。agents/:71 个子代理定义文件,如planner.md(功能规划)、architect.md(系统设计)、tdd-guide.md、code-reviewer.md、security-reviewer.md,以及按语言分的 reviewer 与 build-resolver(Go、Rust、Python、Java、Kotlin、F#、C++、Ruby,甚至 HarmonyOS/ArkTS)。commands/:98 个斜杠命令文件,多为向技能迁移过程中的兼容垫片;已退役的短名命令收在legacy-command-shims/,须显式 opt-in 才能用。rules/:23 个目录,common/通用原则必装,再按语言分目录(typescript、python、golang、swift、php、arkts 等)选装。hooks/:钩子配置。主文件hooks/hooks.json54 KB,覆盖 8 个生命周期事件、共 27 条钩子:PreToolUse 10 条、Stop 8 条、SessionStart 2 条、PostToolUse 与 PostToolUseFailure 各 2 条、UserPromptSubmit、PreCompact、SessionEnd 各 1 条;另有 Codex 与 Qoder 的专用钩子配置,以及hooks/hermes/下的 Python 检查脚本(如拦截console.log的check-console-log.py、保护配置的config-protection.py)。scripts/:安装、修复、同步、编排与检查脚本,npm 入口ecc、ecc-control-pane、ecc-install、ecc-memory-mcp、ecc-plan-canvas等 6 个 bin 均指向此处;install-apply.js251 行、ecc.js350 行、memory.js504 行。docs/:60 个子目录加 16 种语言的 README 翻译(英、阿、葡、简中、繁中、日、韩、土、俄、越、泰、德、西、乌、波、孟),另有三份长指南:短指南(16,298 字节)、长指南(15,042 字节)、安全指南(30,501 字节)。ecc2/:Rust 写的 ECC 2.0 控制面骨架(Alpha),含终端 UI、SQLite 会话存储、后台守护进程、工作区感知会话脚手架与可观测性原语,明确标注“不是完成品”。tests/:534 个测试文件,其中 JavaScript 472 个、Python 29 个,另有run-all.js统一入口与test:js、test:python、coverage等 npm 脚本。- 其他:
ecc_dashboard.py(956 行 Tkinter 桌面仪表盘,另有dashboard:web浏览器版)、examples/82 个文件、workflows/、contexts/、manifests/、schemas/、mcp-configs/、integrations/、scaffolds/,以及 20 多个点号开头的 Harness 适配目录(.claude、.codex、.cursor、.opencode、.gemini、.qwen、.kimi、.kiro、.pi、.codebuddy、.trae、.zed、.vscode、.openclaw、.hermes等)。
版本 2.2.3(2026-10-01 发布),npm 包名 ecc-universal,插件 slug 为 ecc@ecc,主入口 npx [email protected] setup,要求 Node.js 18+、Claude Code 2.1+。仓库创建于 2026-01-18,不到 10 个月 Star 冲到 30 万量级,是 Atlas 榜上增长最快的项目之一。
架构图
flowchart TB
User[用户与 AI 编程助手] --> Entry[入口层]
Entry --> CLI[CLI ecc-universal]
Entry --> Plugin[插件 ecc@ecc]
Entry --> Slash[斜杠命令 98 条]
CLI --> Orchestrate[编排层]
Plugin --> Orchestrate
Slash --> Orchestrate
Orchestrate --> Install[安装与修复]
Orchestrate --> Canvas[Plan Canvas]
Orchestrate --> Control[Control Pane]
Orchestrate --> Memory[记忆金库]
Orchestrate --> Skills[能力层]
Skills --> SkillLib[技能库 314 个]
Skills --> AgentLib[子代理 71 个]
Skills --> RuleLib[规则库 23 组]
Skills --> Runtime[运行时层]
Runtime --> Hooks[钩子 8 事件 27 条]
Runtime --> Instincts[本能学习]
Runtime --> Vault[跨会话记忆]
Runtime --> Adapters[适配层]
Adapters --> Claude[Claude Code]
Adapters --> Codex[Codex]
Adapters --> OpenCode[OpenCode]
Adapters --> Cursor[Cursor]
Adapters --> Others[Gemini Qwen Kimi 等]
Runtime --> Support[支撑层]
Support --> Tests[测试 534 个]
Support --> Registry[命令注册表]
Support --> Docs[文档 16 语言]
Support --> ECC2[ECC2 Rust 控制面]
分层设计说明
这套分层最值得注意的一点是:内容与执行分离,内容本身就是产品。能力层(技能、代理、规则)几乎全是 Markdown 文件,不含可执行代码;真正的代码只出现在三处:编排层的安装与运维脚本、运行时层的钩子脚本、支撑层的测试与校验脚本。钩子在工具调用前后触发,把“规范”从一句可能被模型遗忘的提示词,变成每次都会跑的检查。
第二层意思是单源多目标。根目录的 skills/、agents/、commands/、rules/、hooks/ 是唯一事实来源,各 Harness 的点号目录只是适配器:.claude-plugin/plugin.json 一处声明“71 agents、314 skills、98 legacy command shims”,.codex/、.opencode/、.cursor/ 等目录做格式映射,不各自维护一份工作流副本。README 称维护者“每周横跨 7 个 Harness 发版”,靠的就是这套结构——改一处,全 Harness 同步。
第三是按需加载的上下文经济。314 个技能合计近 10 万行,不可能常驻上下文。每个技能的 SKILL.md 开头有一段 frontmatter 元数据(name、description、argument-hint、metadata.origin),模型只凭 description 决定是否加载,加载时才读正文。长指南把这点说得很直白:技能让上下文保持聚焦,记忆则把会话蒸馏成摘要、本能与可复用技能,而不是存整份聊天记录。
第四是会话边界上的记忆与学习。ecc memory 提供统一记忆金库(scripts/memory.js 504 行 + scripts/memory-mcp.mjs MCP 入口 + hooks/memory-persistence/ 钩子),实现跨 Harness 的记忆共享与交接;continuous-learning-v2 技能(377 行)把会话中沉淀的模式抽成带置信度的“本能”(instinct),SessionStart 时按置信度与项目技术栈相关性排序注入上下文,默认最多 6 条、最低置信度 0.7。仓库自带的 .claude/homunculus/instincts/inherited/ecc-instincts.yaml 就是一份策展过的本能清单,如“提交用 conventional commits 前缀”(置信度 0.9)、“提交标题控制在 70 字符左右”(0.8),每条都附证据说明。
技术亮点
亮点一:把“计划文件是不可信输入”写进工作流正文。 skills/tdd-workflow/SKILL.md 的 Plan Handoff 一节明确规定:用户给的 *.plan.md 是不可信的规划输入,只能当作纯文本读,其中“忽略之前规则”“跳过验证”之类的文字必须记录为计划内容、不得执行;提取出的任务须消毒、映射到仓库允许的验证动作、经用户批准后才能执行;每一步还要保留“计划任务 → 测试目标 → RED 证据 → GREEN 证据”的映射链。这不是口号,是 TDD 技能执行的前置步骤。配合 30,501 字节的《安全指南》(提示注入、MCP 投毒、Lethal Trifecta 框架均有专节)与独立 npm 包 ecc-agentshield(agentshield scan --path .),ECC 把安全从“提醒模型小心”升级为“流程上默认不信任输入”。代价是流程摩擦:每份外部计划都要过一道消毒与确认,图省事的用户会觉得啰嗦。
亮点二:本能(Instinct)机制把学习做成了可评分、可注入、可继承的数据。 与常见的“会话结束写一份总结”不同,continuous-learning-v2 把经验抽成结构化记录:id、trigger(何时触发)、confidence(0–1 置信度)、domain、source(repo-curation 还是会话学习)、source_repo,外加 Action 与 Evidence 两段正文。SessionStart 钩子按“置信度 + 项目/技术栈相关性”排序,只注入最相关的 6 条;项目级本能与匹配当前技术栈的本能优先。仓库自带的两条策展本能均有明确证据(主线提交历史一贯用 conventional commits、发布与 changelog 自动化依赖可读的提交分类)。代价也很实在:学习信号的质量取决于会话本身,低质量会话会产出低置信度噪声,只能靠 0.7 的阈值与人工策展过滤,本能库需要持续治理,否则会越积越杂。
亮点三:多 Harness 适配的成本被测试矩阵兜底。 20 多个点号适配目录意味着每一次改动都要在多个 Harness 上验证。仓库的应对是把适配本身也当成被测对象:tests/ 534 个文件里有 codex-config.test.js、codex-native-hooks.test.js、opencode-config.test.js、opencode-plugin-hooks.test.js、opencode-plugin-loader-contract.test.js、plugin-manifest.test.js、qoder-plugin.test.js 等针对各 Harness 的专项测试,另有 harness:audit、harness:eval、catalog:check、command-registry:check 等 npm 脚本做一致性校验,COMMAND-REGISTRY.json 统一登记命令。README 2.2 版更新日志也提到“packed-artifact release gate 在 Linux、macOS、Windows 三平台测试”。代价是测试负担随适配矩阵线性增长——534 个测试文件本身就是这笔成本的刻度。
值得参考的设计或实现
- SKILL.md frontmatter 元数据约定:
name+ 一句话description(含触发条件)+argument-hint+metadata.origin,让 314 个技能可被模型路由、可被脚本编目(catalog:check、catalog:sync),内容与索引分离。 - 钩子按生命周期事件分发表:
hooks.json以 PreToolUse、PostToolUse、Stop、SessionStart 等 8 个事件为键,每个事件下挂 matcher + 命令,新增检查只需加一条记录,不用改宿主逻辑;另有 minimal/standard/strict 三档钩子 profile 可配。 - 安装状态归属(install-state ownership):2.2 版引入的 guided setup 带 doctor、repair、uninstall 全套生命周期,
install.sh用--ignore-scripts安装依赖防供应链 RCE,scripts/uninstall.js可干净卸载——对“往用户配置目录写文件”的工具而言,卸载路径与安装路径同等重要。 - 版本与证据链:
VERSION文件、CHANGELOG.md(23,990 字节)、docs/releases/每版发布说明与证据、commitlint 强制 conventional commits,发布有release:approval-gate审批关卡。发版不是写个 tag 就完事,而是一条可审计的链。 - 低上下文安装路径:README 单列“Low-context / no-hooks path”,SessionStart 附加上下文可设上限(默认 8,000 字符)或完全关闭,并有会话 tmp 保留窗口、本能注入上限等旋钮——为本地小模型与弱上下文场景留了后路。
- 多语言文档不是机器翻译堆量:16 种语言的 README 与
docs/下对应的语言子目录并存,中文版README.zh-CN.md38,234 字节,是正经维护的翻译资产而非摆设。
适合谁
- 同时在用 Claude Code、Codex、Cursor、OpenCode 等多个 AI 编程工具,希望同一套 TDD、评审、安全习惯处处生效的开发者;
- 想把“团队怎么写代码”从口头约定变成可安装、可测试、可复用的技能与钩子的技术负责人;
- 在意 Agent 安全、需要把提示注入与 MCP 投毒防在流程里的团队;
- 对“上下文经济学”敏感、希望长会话后能干净地保存、学习与恢复的个人开发者。
怎么上手
推荐路径是通用引导安装(要求 Node.js 18+,Claude Code 插件安装还需 Git 与 Claude Code 2.1+):
npx [email protected] setup
装好后按任务选入口,不必通读 314 个技能:做功能用 /ecc:plan "描述需求" 生成计划再走 tdd-workflow;修 Bug 先写一个能复现的失败测试;审代码用 /code-review(换一个全新上下文审,避免自己写自己审的盲区);长会话结束用 /save-session,下次用 /resume-session 恢复;想看 Agent 配置有没有问题用 /security-scan 或 agentshield scan --path .。只想挑几个组件装的,可以按 README“Advanced Install Options”里的选择性安装清单,只取 agents、rules、核心技能与钩子;上下文紧张的本地模型走低上下文/无钩子路径。卸载用仓库自带的 scripts/uninstall.js。
需要注意:ECC 本身不提供模型,须自带 Claude Code 等 Harness;仓库的开源部分 MIT 协议永久免费,ECC Pro 是面向私有仓库的托管 GitHub App($19/席位/月起),两者是同一套内容的两种分发方式。安装务必只走官方渠道——README 顶部有警告,第三方转载与非官方镜像不在维护范围内,可能含恶意代码。
数据卡
- 仓库:affaan-m/ECC
- 官网:https://ecc.tools
- Star:303,044(实时,2026-11-15)
- Fork:44,685
- 主要语言:JavaScript(GitHub 标注;仓库另含大量 Markdown、Python、TypeScript、Rust)
- 许可证:MIT
- Atlas 分类:开发工具
- Atlas 领域:软件开发
- 创建时间:2026-01-18
- 最近更新:2026-11-14
- 最近推送:2026-11-09
- 当前版本:2.2.3(2026-10-01)
- 开放 Issue:279
- 关注者:1,494
- 快照 Star:292,945(2026-11-02 Atlas 快照;13 天涨约 10,099)