ECC 新手教程 · 在 Cursor 中使用

1这是什么

一句话：ECC 是「代理工具的操作系统」——官方原话是 "The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond."。它来自 Anthropic 黑客马拉松的获胜项目，经过 10 个月以上的高强度日常开发打磨，如今是一份 4 万星的开源仓库。

它解决的问题是：你装了 Cursor，Agent 很聪明，但没有纪律——不先规划就动手、写完不验证、每次会话都失忆、把密钥粘进提示词也没人拦。ECC 把一整套工程实践（先规划、测试先行、审查、记忆、安全扫描）做成可安装的配置层，装上之后 Agent 默认就按这套流程干活。

它不做什么（反向界定）

• 不是模型，也不是 MCP 服务器。本体是 Markdown 文件 + Node.js 脚本的配置层；MCP 连接器默认只开 1 个（chrome-devtools），其余全部 opt-in。
• 不给 Cursor 提供斜杠命令。94 条 /命令 是 Claude Code 的原生体系；在 Cursor 里，这些能力由规则（常驻注入）和技能（按需点名）承接。
• 不承诺与 Claude Code 功能对等。官方明确标注 Cursor 适配器是 Beta project adapter——文件放置和指令可移植性经过测试，但别期待 1:1 体验。
• 不上传任何数据。规则、技能、记忆全部是本地 Markdown，可检查、可 git diff、可版本化。

2为什么需要

先想想你（或你身边同事）可能已经尝试过的三种做法——它们各自会怎么失败。

ECC 的核心洞察只有一句话，也是它 README 里反复出现的口号：

围绕这句话，它把 Agent 的默认工作循环定义为：plan → test → implement → review → verify → remember → improve。这不是口号——每一步都有对应的规则、技能或钩子在背后托着（第 3 节展开）。

3核心概念与工作循环

ECC 有五个概念要分清，它们在 Cursor 里的「存在形式」各不相同：

把五个概念串起来，就是 ECC 定义的默认工作循环——每个环节都有配置层在托底，而不是靠 Agent 自觉：

4Cursor 里装的是什么

ECC 仓库为 Cursor 准备了一整套适配层。安装器会把选定内容写进你项目根目录的 .cursor/ 文件夹——五类东西：

Hook 事件都干了什么

15 个事件按职责分六组，安全相关的占了一半以上——这是 ECC 最「值回票价」的部分：

5安装

给 Cursor 装 ECC 只有一条一等公民路径：克隆仓库 → 在你的项目目录里运行安装脚本。先认识三条路，别走岔：

三步装进你的项目

假设你的项目在 ~/projects/demo（路径换成你自己的）：

# 1. 克隆 ECC 到本地工具目录（别放进项目里）
git clone https://github.com/affaan-m/ECC.git ~/tools/ECC

# 2. 进入你的目标项目
cd ~/projects/demo

# 3. 运行安装器 —— 写入当前项目的 ./.cursor/
bash ~/tools/ECC/install.sh --profile minimal --target cursor

想先看会动哪些文件再决定，加 --dry-run；自动化脚本里加 --yes 免交互。Windows 用户等价命令：

# 在你的项目目录里运行
pwsh -File ~/tools/ECC/install.ps1 --profile minimal --target cursor

profile 怎么选

6环境自检

装完别急着用，先花一分钟确认三件事：文件在、状态对、诊断绿。

# 1. 目录结构在不在（在你的项目根目录）
ls .cursor/
#   预期看到: rules/  hooks/  hooks.json  agents/  skills/  ecc-install-state.json

# 2. 安装状态是否完整记录
cat .cursor/ecc-install-state.json

# 3. 用 ECC 自带诊断器体检（源码检出路径）
node ~/tools/ECC/scripts/ecc.js doctor --target cursor
node ~/tools/ECC/scripts/ecc.js list-installed

doctor 会比对每个受管文件的实际内容与安装状态里记录的摘要，缺了、漂了都会指出来；repair 能按状态文件原样重建。这是 ECC 2.0 「确定性安装」的底座——卸载、修复都不靠猜。

平台支持与已知限制

Node 与记忆的两个前提

• hooks 全是 Node.js 脚本——确保 node 在 PATH 里（node -v 能出版本号即可）。
• 记忆默认写到 ~/.claude——这是有意设计（ECC_AGENT_DATA_HOME，issue #2066）：让 ECC 记忆钩子不与 Claude Code 自己的记忆冲突。想改位置，用项目里的 .cursor/ecc-agent-data.json 指定（支持相对路径，从项目根解析）。

7第一次实战

下面六个动作在 15 分钟内做完，每个都有明确的预期结果——做完整套，你就亲眼看过了 ECC 的三层能力（规则、钩子、工作流）各自怎么发力。

第 1 步：装进一个实验项目

mkdir -p ~/projects/ecc-demo && cd ~/projects/ecc-demo
git init
bash ~/tools/ECC/install.sh --profile minimal --target cursor --dry-run   # 先看清单
bash ~/tools/ECC/install.sh --profile minimal --target cursor             # 确认后真装

第 2 步：让 Cursor 重新加载

重启 Cursor，或在命令面板执行 Reload Window。项目规则与 hooks 都在会话/窗口启动时加载——热改不生效，先重启再说。

第 3 步：感受规则常驻

在 Agent 对话里说：「写一个管理购物车的小模块，用 Python」。留意它是否主动：把函数拆小（规则要求 <50 行）、不原地改对象而是返回新对象、每个系统边界做输入校验、文件控制在几百行内。这些不是模型自觉——是 common-coding-style 规则里的 Code Quality Checklist 在每轮对话里被注入。

第 4 步：亲眼见一次 hook 拦截

对 Agent 说：「帮我提交代码，用 git commit --no-verify」。before-shell-execution-block-no-verify.js 会拦下这条命令——它是专门防 Agent 绕过你仓库 pre-commit / commit-msg / pre-push 钩子的。被拦了，说明 hooks 链路通了。

第 5 步：测试密钥防线

在提示词里粘一条假密钥（比如 sk-test1234567890abcdef）。beforeSubmitPrompt 的密钥模式检测（sk- / ghp_ / AKIA）应当告警。真密钥再也不会「顺手」溜进对话上下文。

第 6 步：走一轮完整循环

提一个真实小需求，并显式说：「先别写代码，先给我实施计划和风险点，我确认后再动手」——这就是循环里 plan 环节的正确打开方式。确认后让它按 TDD 走：先写失败测试，再最小实现，最后按语言规则自查一遍。整个过程里 afterFileEdit 会自动做格式化和类型检查，会话结束时 session-end 钩子把状态写进记忆。

8产物结构与设计原则

装完之后项目里多了什么、为什么这么放：

your-project/
├── .cursor/
│   ├── rules/                    # 34 条规则：common-* 9 条 + 每语言 5 条
│   │   ├── common-coding-style.md      # 不可变、小文件、错误处理、输入校验
│   │   ├── common-security.md          # 密钥管理、依赖审计、边界校验
│   │   ├── common-testing.md           # 测试策略与覆盖率要求
│   │   ├── common-git-workflow.md      # 提交规范与分支纪律
│   │   └── python-coding-style.md ...  # TS/Python/Go/Kotlin/Swift/PHP 各 5 条
│   ├── hooks.json                # 15 个事件 → 16 个脚本的注册表
│   ├── hooks/                    # Node.js 脚本本体（session-start.js 等）
│   ├── agents/                   # 48 个 ecc-*.md 子代理定义
│   ├── skills/                   # 11 个精选技能目录
│   └── ecc-install-state.json    # 安装状态（卸载/修复的依据）

三条设计原则，理解了就知道该怎么和它相处：

• 项目本地，跟仓库走。所有内容都在项目里，git commit 后全团队共享同一套纪律——这正是团队统一规范最省事的路径。
• 规则是常量，技能是变量。规则每轮都在（所以必须精炼）；技能按需加载（所以可以写得很厚）。别把长流程塞进规则——官方速览指南的忠告是「持久逻辑应该活在技能里」。
• 一切受管、一切可逆。每个写入的文件都在 ecc-install-state.json 里有记录（含内容摘要），doctor 查漂移、repair 修复、uninstall 只删自己装过的——不会碰到你项目里的其他文件。

9日常怎么用

日常不需要记命令，记住一个映射就够：你说意图，配置层出动作。五个高频场景：

规则是自动的，但你依然可以显式点名技能来加强约束——这是 Cursor 下最接近「斜杠命令」的用法：在对话里直接说「按 xxx 技能的流程来」，Agent 会去读 .cursor/skills/xxx/ 里的说明并照做。

会发生 vs 不会发生

10进阶玩法

基础盘稳了之后，按需拧这四颗旋钮：

1. 换 profile / 增减模块

# 升级到 core，但不要 hooks 运行时
bash ~/tools/ECC/install.sh --profile core --without baseline:hooks --target cursor

# 事后补装 hooks
bash ~/tools/ECC/install.sh --target cursor --modules hooks-runtime --enable-hooks

# 精准点名技能
bash ~/tools/ECC/install.sh --target cursor --skills tdd-workflow,security-review

重跑安装脚本本身就是更新/改配置的方式；受管文件漂移了用 ecc.js repair 修。

2. 用官方的 MCP 连接器策略

ECC 对「装哪些 MCP」做过审计，结论写进 docs/MCP-CONNECTOR-POLICY.md：默认只保留 chrome-devtools，其余六个 opt-in，且每个都给出了「原生替代方案」：

3. 跨工具记忆交接

ecc memory init      # 建项目/团队/用户记忆库
ecc memory save      # 存决策、事实、教训、偏好、runbook（正文走 --stdin）
ecc memory handoff   # 把有边界的工作状态从一个工具交接给另一个
ecc memory search    # 按文本/范围/类型检索
ecc memory doctor    # 查坏文件、重复 ID、断链

handoff 的价值在于：同一个项目今天在 Cursor 里做，明天换 Claude Code 接手时，上下文不是靠聊天记录搬运，而是一份可检查的 Markdown 交接文档。

4. 团队统一规范

把 .cursor/ 提交进仓库，规则、hooks、技能随代码分发；个人偏好放 ~/.ecc/（用户级记忆）。新人 clone 下来第一行命令都还没跑，Agent 纪律已经就位。

11上下文与性能

ECC 对性能的影响只有一个变量：常驻上下文多了多少字。hooks 本身是本地 Node 进程，毫秒级，不占模型上下文。它甚至给了你调节数字的手柄：

12FAQ / 踩坑

每条都给可执行的解法，按症状检索：

13卸载与合规

ECC 的卸载和它安装一样讲究：按状态文件精确清理，两步走。

# 在当初安装时的项目目录里运行
node ~/tools/ECC/scripts/ecc.js uninstall --dry-run   # 先看会删什么
node ~/tools/ECC/scripts/ecc.js uninstall             # 确认后执行

# 装过多个位置的话，先盘点再逐个清
node ~/tools/ECC/scripts/ecc.js list-installed

它只删除 ecc-install-state.json 里登记的受管文件——你自己写进 .cursor/ 的规则、项目代码、记忆文件都不在清理范围内。

合规与数据

• 许可证：MIT，永久免费开源，商用无顾虑。
• 数据本地性：规则、技能、记忆、会话状态全部是本地文件；不内嵌遥测上传。记忆文件的本质是「未经审查的上下文，不是可执行策略」——官方提醒得直白：别把它当成信任边界。
• 配置来源：所有组件来自公开仓库，装之前可以逐文件审阅——这也正是 AgentShield 存在的意义：它扫描的就是「你装进 Agent 的配置本身」。

14参考链接

官方资源清单，按用途分组：

仓库结构速览

ECC/
├── install.sh / install.ps1   # 安装器（--target 支持 claude/cursor 等）
├── README.md / README.zh-CN.md
├── COMMANDS-QUICK-REF.md      # 94 条命令速查
├── rules/                     # 规则源（common + 各语言）
├── skills/                    # 286 个技能
├── agents/                    # 68 个子代理
├── hooks/                     # hooks 脚本源
├── .cursor/                   # Cursor 适配层（rules/hooks/agents/skills）
├── manifests/                 # 安装模块与 profile 清单
├── docs/                      # 架构、指南、排障、多语言翻译
└── scripts/                   # ecc.js 诊断/卸载等工具链