每天一个开源项目#86 ECC：245K星的 Agent 工程操作层

GitHub Trending #10｜快照日期：2026-09-01｜Stars：245,429（同日 GitHub API 核验，原始榜单未保留该项）｜Forks：37,062｜主语言：JavaScript｜License：MIT｜仓库：github.com/affaan-m/EC...

AI 编程工具真正进入日常之后，一个问题会反复出现：不是模型会不会写代码，而是你能不能把它固定在一套靠谱的工程流程里。今天让 Claude Code 写，明天换 Codex 修，后天再用 Cursor 做 review，技能、规则、记忆、Hook、MCP 配置散在不同目录里，很快就变成一堆靠人脑维护的隐性约定。

ECC（Everything Claude Code）试图把这层约定产品化。它不是单纯的提示词合集，而是把 Agent、Skills、Rules、Hooks、Memory Vault、安装清单和多 Harness 适配器放在同一个仓库里。看完源码后，我更愿意把它理解成"Agent 工程操作层"：它不替模型做推理，但会尽量规定模型什么时候该计划、什么时候该跑测试、什么时候该被 Hook 拦一下。

这类项目最容易被写成玄学工具。ECC 有它夸张的一面，比如 README 里 245K Stars 和 37K Forks 的数字非常醒目；但它也有实打实的工程结构：3,519 个 Git 跟踪文件、68 个 Agent 定义、286 个主技能入口、94 个命令 shim、23 个 Hook matcher，以及一组跨 npm、Claude Code、Codex、OpenCode、Hermes、Kimi 等环境的安装适配代码。好坏都得拆开看。

📋 项目概览

项目	内容
项目名	affaan-m/ECC
一句话	面向 Claude Code、Codex、OpenCode、Cursor 等 Harness 的 Agent 工程流程层
Stars	245,429（2026-09-01 同日 API 核验）
Forks	37,062
语言	JavaScript 70.8%、Rust 20.9%、Python 4.6%、Shell 2.4%、TypeScript 1.1%
License	MIT（GitHub API、package.json、插件 manifest 一致）
版本	源码 package.json / plugin.json：2.2.1；npm latest：2.2.0；最新 GitHub Release：v2.2.0
默认分支	main
最近提交	ca185ef，2026-08-31 22:14:22Z，`chore(release): prepare signed 2.2.1 patch (#2920)`
社区状态	43 个 Open Issues、83 个 Open PRs；Top contributor affaan-m 为 1,544 commits

🔥 为什么值得关注

过去半年，AI Coding 的关注点从"模型能生成多少代码"转向"生成之后谁兜底"。一个 Agent 可以修改文件、跑 shell、装 MCP、读仓库、写配置。只靠一句"请谨慎操作"很脆。ECC 的思路比较直接：把常见工程动作拆成可安装的工作流和 Hook，让模型每次行动前后都被同一套规则夹住。

我觉得它真正有意思的地方在于"多 Harness"。很多团队已经不是只用一个 Agent 入口：Claude Code 适合长任务，Codex 适合某些 CLI 流程，Cursor 仍然贴着 IDE，OpenCode、Gemini、Kimi 又各有自己的配置目录。ECC 用安装 manifest 把 rules、agents、skills、commands、hooks、platform-configs 拆成模块，再按 target 复制到不同 Harness 的原生位置。这样做很笨，但笨得有效：比起指望每个工具都原生兼容同一套协议，文件级适配更容易落地。

它也没有把安全说成魔法。仓库里的 GateGuard Hook 会识别 rm -rf、git reset --hard、git push --force、DROP TABLE 这类危险动作，然后要求 Agent 先说清影响范围、回滚方式和用户原始指令。这个边界仍然只是 Hook，不是容器或 VM；但至少它把"模型自我确认"替换成了一个可测试的阻断点。

🏗️ 核心特性

多 Harness 安装层

ECC 的入口不是单个库函数，而是一组安装器。scripts/ecc.js 把 setup、install、plan、catalog、memory、doctor、repair、platform-audit 等命令收束到一个 CLI；scripts/install-apply.js 支持 --guided；scripts/setup.js --help 显示 Claude plugin 的 scope、hooks、dry-run、json 等参数。下面这些命令都经过 help 或 registry 核验。

bash 复制代码

# 已通过源码 help 核验：scripts/ecc.js 支持 setup
npx ecc-universal setup

# 已通过 npm registry 查询核验：当前 npm latest 为 2.2.0
npm view ecc-universal version

安装器背后是 manifest，而不是把所有文件一股脑复制过去。manifests/install-modules.json 把能力拆成 rules-core、agents-core、commands-core、hooks-runtime、platform-configs 等模块，并为每个模块列出支持目标，例如 claude、claude-project、cursor、codex、gemini、opencode、hermes、openclaw、kimi、adal。

Skills-first 的知识层

README 声称仓库包含 68 agents、286 skills、94 commands。这个数字不是只写在 README 里，源码扫描也能对应上：agents/ 下有 68 个 Markdown Agent 定义，skills/*/SKILL.md 有 286 个主技能入口，commands/ 下有 94 个命令文档。CI 的 validate-skills.js 会扫到 805 个 skill directories，因为多语言文档和适配目录也进入了校验范围；产品口径和验证口径要分开看。

text 复制代码

agents/          68 个专用 Agent 定义
skills/          286 个主 SKILL.md 入口
commands/        94 个 legacy slash-command shim
rules/           122 个规则文件
hooks/           Claude/Codex/OpenCode 等 Hook 配置
scripts/         安装、诊断、记忆、Hook 调度、CI 校验脚本

Hook 调度与事实强制

hooks/hooks.json 注册了 Claude Code 的 PreToolUse、PostToolUse、SessionStart、Stop 等阶段。真正的 Bash 前置调度在 scripts/hooks/bash-hook-dispatcher.js：它按 profile 执行 block-no-verify、auto-tmux-dev、git-push-reminder、commit-quality、gateguard-fact-force 等子 Hook，并把多个 Hook 的 additionalContext 合并后输出给 Claude Code。

GateGuard 的逻辑比较值得看。它不是简单匹配字符串，而是先处理 quote、subshell、brace group，再检查命令段。源码里专门处理了这些形态：

风险动作	ECC 的处理方式
`rm -rf` / `rm -fr`	解析 `rm` 参数，要求同时出现递归和 force
`git reset --hard`	识别 destructive git 子命令
`git clean -fdx`	识别 `clean` 的 force 参数
`git push --force`	区分 `--force-with-lease` 和裸 force
`$(...)` / 反引号	抽取可执行子表达式后再检查
`DROP TABLE` / `DELETE FROM`	quote-stripped 之后做 SQL 风险匹配

Memory Vault 与跨 Harness handoff

scripts/memory.js 暴露 init、save、handoff、search、read、doctor。它的命令帮助里写得很清楚：默认 recall scope 是 project 和 team，user scope 需要显式传入；写入必须从 --stdin 或 --body-file 二选一；tool-created memories 被标记为 unreviewed context，不会变成可执行 policy。

bash 复制代码

# 已通过 scripts/memory.js --help 核验
node scripts/ecc.js memory init
printf 'Continue migration context' | node scripts/ecc.js memory handoff \
  --from codex \
  --target claude \
  --title "Continue migration" \
  --stdin

AgentShield 与治理事件

ECC 把安全分成几层：README 的 AgentShield 是用户面入口；Hook 层负责拦截工具使用；scripts/hooks/governance-capture.js 会扫描 secret、敏感路径、危险命令，并把事件以结构化形式输出。比如它识别 AWS key、JWT、GitHub token、private key、.env、.pem、id_rsa，也会给 git reset --hard、rm -rf、DROP TABLE 这类命令打上 approval 事件。

这里要说清楚边界：这是 Harness 级 guardrail，不是 OS sandbox。Agent 仍然运行在用户授予的权限里。如果团队要让 Agent 处理不可信仓库、邮件附件、PDF 或外部网页，容器、VM、最小权限 token、网络出口控制仍然不能省。

工程规模与验证结果

| 项目 | 数值 / 结果 | 口径 |
|---------------|--------:|----------------------------------------------------------------------------|--------------|
| Git 跟踪文件 | 3,519 | git ls-files -z 写入临时文件后解析，并用 `git ls-files | wc -l` 交叉核验 |
| Markdown 文件 | 2,520 | 文件后缀统计 |
| JavaScript 文件 | 537 | 文件后缀统计 |
| Tests 目录文件 | 278 | Git tracked paths，含 JS/Python/fixture |
| skills 主入口 | 286 | skills/*/SKILL.md |
| agents 定义 | 68 | agents/*.md |
| commands shim | 94 | commands/*.md |
| CI 组件校验 | 通过 | agents、hooks、commands、skills、install manifests、workflow security 全部 exit 0 |
| 完整 npm test | 未作为通过证据 | 本地运行超过 6 分钟仍未完成，已观察到多个子套件通过，但未把最终绿色结果写进结论 |

🔬 技术架构深度解析

ECC 的架构可以按"安装面、运行面、治理面、记忆面"拆。它不像传统 SDK 那样给你一个 import 后调用的 API，而是把文件和脚本安装到各个 Harness 能识别的位置。

text 复制代码

                ┌────────────────────────────┐
                │        User / Team          │
                │  setup, install, catalog    │
                └──────────────┬─────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────┐
│                    ecc-universal CLI                    │
│ scripts/ecc.js -> setup/install/plan/catalog/memory/... │
└──────────────┬───────────────┬───────────────┬──────────┘
               │               │               │
               ▼               ▼               ▼
       ┌────────────┐   ┌────────────┐   ┌──────────────┐
       │ manifests  │   │  content   │   │ diagnostics  │
       │ modules    │   │ skills/rules│  │ doctor/repair│
       │ profiles   │   │ agents/cmds │  │ platform-audit│
       └─────┬──────┘   └──────┬─────┘   └──────┬───────┘
             │                 │                │
             ▼                 ▼                ▼
┌─────────────────────────────────────────────────────────┐
│              Harness-specific materialization            │
│ Claude plugin / Codex config / Cursor adapter / Hermes   │
│ OpenCode / Kimi / Gemini / Qwen / Zed / OpenClaw / ...   │
└─────────────────────────────────────────────────────────┘

运行时最核心的是 Hook 链。以 Bash 为例，Claude Code 的 PreToolUse 会进入 pre-bash-dispatcher.js，再交给 bash-hook-dispatcher.js。Dispatcher 会按 profile 决定哪些 Hook 生效；Hook 可以返回 deny，也可以追加 context。这个设计的好处是每个 Hook 可以保持小而可测，坏处是 Harness 的 Hook schema 一变，整条链就需要跟着适配。

text 复制代码

Bash tool call
   │
   ▼
PreToolUse matcher: Bash
   │
   ▼
pre-bash-dispatcher.js
   │
   ▼
bash-hook-dispatcher.js
   ├─ block-no-verify
   ├─ auto-tmux-dev
   ├─ tmux reminder       (strict)
   ├─ git push reminder   (strict)
   ├─ commit quality      (strict)
   └─ gateguard fact force(standard / strict)
          │
          ├─ allow: 原始工具调用继续执行
          └─ deny: 返回 Claude Code Hook JSON，要求先补充事实再重试

GateGuard 的状态机也很典型。它不指望 Agent 永远听话，而是让第一次编辑、第一次创建文件、第一次 routine Bash、第一次 destructive Bash 经过一个"事实确认"门。确认内容不是"你确定吗"，而是要求列出调用方、影响 API、数据结构、修改目标、回滚步骤和用户原始指令。这个设计比 prompt 自律更硬，但仍然存在绕过面：如果某个 Harness 不触发对应 Hook，或者用户主动关闭 Hook，ECC 就无法拦截；如果 Agent 在已允许的脚本内部间接执行危险动作，也需要更底层的沙箱补位。

text 复制代码

Tool input
   │
   ▼
parse JSON / normalize tool name
   │
   ├─ Edit / Write / MultiEdit
   │     ├─ settings path / exempt path / subagent -> allow
   │     ├─ first touch -> deny + 要求 importers/API/schema/原始指令
   │     └─ already checked -> allow
   │
   └─ Bash
         ├─ read-only git introspection -> allow
         ├─ destructive command -> first time deny, retry allow
         ├─ routine Bash disabled -> allow
         └─ first routine Bash -> deny + 要求说明命令产物

README 声明与源码证据

README / 文档声明	源码证据	判断
68 agents	`agents/*.md` 数量为 68，`AGENTS.md` 也列出主 Agent	可核验
286 skills	`skills/*/SKILL.md` 数量为 286；CI validator 扫 805 skill directories	可核验，但口径不同
94 commands	`commands/*.md` 数量为 94，`scripts/ecc.js` 仍称 commands 为 legacy surface	可核验
Claude Code plugin	`.claude-plugin/plugin.json` name 为 `ecc`、version 为 2.2.1、声明 skills/commands 路径	可核验
Hook profiles	plugin userConfig 包含 `hooks_enabled` 和 `hook_profile`，默认 standard	可核验
Codex native plugin	README 给出 `codex plugin marketplace add affaan-m/ECC` 等命令，仓库有 `.codex-plugin/README.md`	有源码和文档支撑，实际 Codex 环境需单独验证
AgentShield security scanning	README 和 `scripts/ecc.js` 暴露 `security-ioc-scan` 命令	有入口，效果取决于扫描规则和运行环境
Memory across harnesses	`scripts/memory.js`、`scripts/lib/memory-vault.js` 实现 CLI 和 vault doctor	有实现
npm latest 2.2.1	源码 package.json 是 2.2.1；`npm view ecc-universal version` 返回 2.2.0	存在版本窗口，安装时按 npm registry 为准

验证口径

验证项	命令 / 来源	结果
Node 环境	`node --version`	v22.22.3
CLI help	`node scripts/ecc.js --help`	列出 setup/install/memory/doctor/security-ioc-scan 等命令
Install help	`node scripts/install-apply.js --help`	确认 `--guided`、`--profile`、`--modules`、`--skills`、`--target`、`--enable-hooks`、`--no-hooks`
Setup help	`node scripts/setup.js --help`	确认 `--mode claude-plugin`、`--scope`、`--hooks`、`--yes`、`--dry-run`、`--json`
Memory help	`node scripts/memory.js --help`	确认 init/save/handoff/search/read/doctor 和 `--stdin`/`--body-file`
CI validators	`validate-agents/hooks/commands/skills/install-manifests/workflow-security`	全部 exit 0
npm registry	`npm view ecc-universal version dist-tags --json`	latest 为 2.2.0

这张表里我刻意没有写"完整测试全部通过"。本地 npm test 运行时间较长，写稿前已经看到多个子套件通过，但没有拿到最终 exit 0。技术博客里最怕把半截输出当成结论，这里按可复现证据说话。

📖 README 核心内容摘要

README 的主线很清楚：安装一次，让 Agent 走 plan -> test -> implement -> review -> verify -> remember -> improve 的循环。这个循环本身不新鲜，很多团队手工 prompt 也会这么写；ECC 的差异是把循环拆成可安装文件、命令和 Hook。

核心安装路径有两条。Claude Code 用户可以走 npx ecc-universal setup，也可以在 Claude Code 内走 /plugin marketplace add https://github.com/affaan-m/ECC 和 /plugin install ecc@ecc。README 明确提醒不要把 native plugin 和手工安装叠在一起，这个提醒很实际，因为多个入口重复安装后，skills、commands、hooks 都可能重复触发。

Codex 路径更偏插件缓存：README 给出的命令是 codex plugin marketplace add affaan-m/ECC、codex plugin add ecc@ecc、codex plugin list --json，再用 node scripts/codex/check-plugin-cache.js 检查缓存。仓库同时保留了旧的 scripts/sync-ecc-to-codex.sh 兼容路径，并在文档里把它标为 deprecated compatibility option。

其他 Harness 采用目标目录安装。install-apply.js --help 显示的 target 包括 claude、claude-project、cursor、antigravity、codex、gemini、opencode、codebuddy、joycode、qwen、zed、hermes、openclaw、kimi、adal。这说明 ECC 当前不是一套统一运行时协议，而是面向各工具的文件布局适配。

README 还强调自托管模型和自定义 endpoint。这里 ECC 的定位比较克制：它不接管模型服务，只依赖每个 Harness 自己的 provider 配置。比如 Claude Code 场景里，README 只给 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 的网关示例，并提醒模型名 remap 应该在 Claude Code 配置里处理，不在 ECC 里硬编码。

🚀 快速上手

如果你只是想看 ECC 的能力面，先不要直接写入自己的 Claude/Codex 配置。更稳的方式是先 clone 仓库，读 help 和 dry-run，再决定安装目标。

bash 复制代码

# 1. 查看源码
 git clone https://github.com/affaan-m/ECC.git
 cd ECC

# 2. 查看统一 CLI 帮助
node scripts/ecc.js --help

# 3. 查看安装器支持的 target/profile/module
node scripts/install-apply.js --help
node scripts/catalog.js profiles
node scripts/catalog.js components --family language

# 4. 只预览安装计划，不复制文件
node scripts/ecc.js --dry-run install --profile core --target claude --no-hooks

面向 Claude Code 的官方推荐路径更短：

bash 复制代码

npx ecc-universal setup

如果你要把 ECC 用在多工具团队里，我建议先从 --dry-run 和 project-local target 开始，确认它会写哪些目录，再考虑 user scope。尤其是 Hook runtime，最好让团队先看过 hooks/hooks.json 和 scripts/hooks/，理解哪些操作会被拦截、哪些只是记录。

一个最小的 Memory Vault 例子如下：

bash 复制代码

node scripts/ecc.js memory init --scope project --json

printf 'ADR: prefer pnpm for workspace installs' | node scripts/ecc.js memory save \
  --title "Package manager decision" \
  --kind decision \
  --tag build \
  --stdin \
  --json

node scripts/ecc.js memory search "package manager" --scope project --json

这些参数都来自 scripts/memory.js --help 和 scripts/ecc.js --help。需要注意的是，memory 写入是 context，不是 policy；不要把它当成安全规则或权限系统。

📊 增长速度与社区热度

ECC 的仓库创建于 2026-01-18，到 2026-09-01 约 226.3 天。以 245,429 Stars 粗算，生命周期平均约 1,084 Stars/天。这个数只能说明它的整体传播速度，不能替代 GitHub Trending 的当日新增，因为原始榜单没有保留每个仓库的 daily stars。

社区结构上，ECC 的关注度很集中也很高：37,062 Forks、1,262 watchers/subscribers，GitHub API 的 open_issues_count 为 126，但拆开看是 43 个 Open Issues 和 83 个 Open PRs。Top contributors 里 affaan-m 为 1,544 commits，haelyra 为 145 commits，dependabot 为 57 commits。这个分布说明主维护者影响很强，后续企业使用时要关注 bus factor 和 release 节奏。

版本面也有一个小坑：源码 package.json 和 .claude-plugin/plugin.json 都是 2.2.1；GitHub Releases 最新是 v2.2.0；npm latest 也是 2.2.0。很可能是 2.2.1 patch 已经准备进 main，但 npm/release 尚未完成同步。安装生产环境时，应该按 registry 和 release tag，而不是只看 main 分支。

Rank	Repository	Language	Stars	当日新增
1	THU-MAIC/OpenMAIC	TypeScript	28,265	未保留
2	tt-a1i/archify	JavaScript	40,166	未保留
3	K-Dense-AI/scientific-agent-skills	Python	41,074	未保留
4	k1tbyte/Wand-Enhancer	C#	23,501	未保留
5	majd/ipatool	Go	10,661	未保留
6	jingyaogong/minimind	Python	56,540	未保留
7	Osmantic/ODS	Python	5,699	未保留
8	checkstyle/checkstyle	Java	9,479	未保留
9	zhaoxuya520/reverse-skill	PowerShell	33,483	未保留
10	affaan-m/ECC	JavaScript	245,429	未保留
11	kaifcodec/user-scanner	Python	4,456	未保留
12	every-app/open-seo	TypeScript	15,916	未保留
13	p-e-w/heretic	Python	29,806	未保留
14	handsomestWei/patent-disclosure-skill	Python	6,477	未保留
15	firecrawl/pdf-inspector	Rust	17,558	未保留
16	pollen-robotics/microduck_rl	Python	1,300	未保留

🎯 适用场景

场景	为什么适合	需要注意
Claude Code 重度使用者	插件、skills、commands、hooks 支持最完整	不要重复叠加 native plugin 和 manual install
多 Harness 团队	Codex、Cursor、OpenCode、Hermes、Kimi 等目标目录都有适配	各 Harness 能力不等，Hook 语义不能假设一致
AI Coding 流程标准化	把 plan、TDD、review、verify、memory 写成可复用技能和规则	Markdown 规则仍依赖模型执行，不等于确定性 linter
Agent 安全基线	GateGuard、governance capture、security-ioc-scan 提供 Hook 级拦截和记录	Hook 不是沙箱，仍需容器、VM、最小权限 token
团队知识沉淀	Memory Vault 支持 handoff、search、doctor 和跨 Harness target	Tool-created memory 是未审查上下文，不能当权限策略
插件/规则库研究	仓库有大量 manifest、CI validator、适配器和测试样例	规模很大，升级前要先 dry-run 和备份配置

💡 总结

ECC 的价值不在于某个单独 prompt 多聪明，而在于它把 Agent 工程里最容易散掉的东西打包成可安装的层：技能、命令、规则、Hook、记忆、诊断、安装清单。这个方向我很认同。团队一旦把 AI Coding 当成正式生产力，就必须把"怎么让 Agent 做事"从口头约定变成文件、脚本和 CI。

但别把它神化。ECC 的很多控制仍然是 Agent-mediated：Markdown 技能需要模型遵守，Hook 需要 Harness 正确触发，Memory 需要治理，安全扫描也不等于系统隔离。它更像一套工程脚手架和 guardrail，能减少混乱，不能替你承担最终责任。

如果你正在用 Claude Code 或 Codex 做中大型代码任务，ECC 值得认真读源码。先看 scripts/ecc.js、manifests/install-modules.json、hooks/hooks.json、scripts/hooks/gateguard-fact-force.js 和 scripts/memory.js。这几个文件读完，基本就能判断它适不适合放进你的工作流。

每天一个开源项目#86 ECC：245K星的 Agent 工程操作层

📋 项目概览

🔥 为什么值得关注

🏗️ 核心特性

工程规模与验证结果

🔬 技术架构深度解析

README 声明与源码证据

验证口径

📖 README 核心内容摘要

🚀 快速上手

📊 增长速度与社区热度

今日 GitHub Trending 榜单

🎯 适用场景

💡 总结