ECC 2.2 发布：面向 AI harness 的智能体工程系统

语言： English | Português (Brasil) | 简体中文 | 繁體中文 | 日本語 | 한국어 | Türkçe | Русский | Tiếng Việt | ไทย | Deutsch | Español | Українська | Polski

警告

仅限官方来源。 请仅从已验证渠道安装 ECC：GitHub 仓库 github.com/affaan-m/ECC、npm 包 ecc-universal 和 ecc-agentshield、GitHub App、插件 slug ecc@ecc，以及项目网站 ecc.tools。第三方重新上传和非官方镜像不受项目维护或审查，可能包含恶意软件。

使用 Claude Code 安装

使用引导式设置或原生插件命令。两者安装的是同一个 ecc@ecc 插件。选择其一，不要在其上再叠加完整的 Claude 手动安装。

_{开源软件永远免费。 本仓库永久采用 MIT 许可证。ECC Pro 是面向私有仓库的托管 GitHub App。赞助者和 Pro 订阅者为这项工作提供资金。这就是为什么一位维护者每周能在 7 个 harness 上发布更新。}

跳转到安装 ↓

你的 agent 可以编写代码，但 ECC 为它提供了一个协调的工程系统和工具箱：它在构建之前先规划，用测试验证更改，从全新上下文中审查自己的工作，记住重要事项，并将重复的成功转化为可复用的技能和工作流。

plan -> test -> implement -> review -> verify -> remember -> improve

无需在每个提示中重建这一流程，你只需安装一次，就让它成为 agent 工作方式的一部分。

优化上下文窗口。持久化其他一切。

ECC 是 MIT 许可的开源软件。它目前与 Claude Code 配合最佳，拥有受支持的 Codex 同步路径，并为 Cursor、OpenCode、Gemini、Zed、GitHub Copilot、Antigravity、Qwen 及其他 harness 提供能力受限的适配器。在假设功能对等之前，请查看支持状态矩阵。

可访问 68 个 agents、293 项 skills 和 94 个旧版命令 shim，以及 hooks、规则、记忆、持续学习和 AgentShield 安全扫描。这些 agents 专精于规划、审查、构建修复、安全、架构和领域工作。

安装 ECC

重要

ECC 2.2 包含面向 Claude Code、Codex 和 Kimi Code 的引导式包设置。 通用包需要 Node.js 18 或更高版本。Claude 插件设置还需要 Git 和 Claude Code 2.1 或更高版本，运行于 PATH。

推荐：通用引导式设置

对于 Claude Code 插件设置、更新、范围变更和 hook 配置变更：

npx ecc-universal@2.2.3 setup

Windows 首次使用演练

如果你是命令行工具新手，请使用这条复制粘贴路径：

1. 安装 Node.js 18 或更高版本、Git 和 Claude Code。

2. 从 Windows 开始菜单打开 PowerShell。

3. 确认每个先决条件均可用：

   node --version
   git --version
   claude --version

4. 运行引导式安装程序：

   npx ecc-universal@2.2.3 setup

5. 对于典型的个人设置，选择 Global user，选择 Standard hooks，然后确认。

6. 启动一个新的 Claude Code 会话并运行 /plugin list，以验证 ecc@ecc 已启用。

此路径不需要克隆仓库。如果找不到任何前置命令，请先安装或修复该前置项，然后再重新运行 ECC 设置。

如果 npm 报告版本或缓存错误，请在重试前确认注册表版本：

npm view ecc-universal version

ECC 2.2 通过现代包运行器支持相同的引导式设置：

这些示例选择 已发布的 ECC 2.2.3 版本，与本仓库的发布版本一致。版本固定不是安全审计或完整性检查。在运行包代码之前，请审查发布源代码和注册表完整性；对于未发布的更改，请使用经过审查的检出。

Yarn Classic 1 不提供 yarn dlx；请使用 npx、全局安装该包，或升级 Yarn 以进行临时一次性运行。

该向导会在进行更改之前清点官方市场以及每个原生 Claude 安装范围，然后安装、更新或将 ecc@ecc 安全地移动到您选择的范围。每当您想要更新 ECC、更改范围或更改其 hook 配置文件时，请重新运行相同的命令。此设置向导目前配置 Claude Code 插件；对于 Codex 或 Kimi Code，请使用下面的多框架向导。

要在一次经过审查的流程中配置多个编码代理，请使用多框架向导：

npx ecc-universal@2.2.3 install --guided

它允许您选择 Claude Code、Codex 和 Kimi Code 的任意组合，显示每个安装渠道和目标位置，在首次写入之前预检每个选择，并请求一次最终确认。

对于自动化，请明确每个提供商特定的选择：

npx ecc-universal@2.2.3 install --guided \
  --harness claude --harness codex --harness kimi \
  --claude-scope local --claude-hooks standard \
  --profile core --yes

在不写入的情况下验证原生引导式 Codex 路径和受管 Kimi 路径：

npx ecc-universal@2.2.3 install --guided --harness codex --dry-run
npx ecc-universal@2.2.3 install --profile core --target kimi --dry-run

通过 2.2 别名还可以使用其他包名命令：

npx ecc-universal@2.2.3 consult "security reviews" --target claude
npx ecc-universal@2.2.3 install --profile minimal --target claude --with capability:machine-learning
npx ecc-universal@2.2.3 doctor --target kimi

不要使用 npx ecc-install --profile minimal --target claude：ecc-install 是 ecc-universal 内的二进制名称，而不是单独发布的 npm 包。

ECC 还为 cursor、antigravity、gemini、opencode、codebuddy、joycode、qwen、zed、hermes 和 openclaw 提供高级受管适配器。在每个适配器通过引导式冲突、更新、修复和卸载生命周期矩阵之前，这些目标仍使用其文档化的 ecc install --target ... 路径。两个向导都不会静默安装到每个检测到的框架中。

仅选择一种路径（每个框架）

您可以同时将 ECC 与 Claude Code、Codex 和其他框架一起使用。为每个框架选择一种安装方法：

• 推荐的默认方式：运行上面的引导式 Claude 插件设置
• Claude Code 也支持：使用 原生插件命令
• 2.2 版本中可用：针对 Claude Code、Codex 和 Kimi Code 的引导式包设置
• 可用：Claude Code 插件 + Codex 原生插件
• 可用：Claude Code 插件 + 旧版 Codex 同步流程
• 避免：Claude Code 插件 + 完整的 Claude 手动安装
• 避免：Codex 同步 + Codex 市场插件

不要叠加安装方式。将 ECC 两次安装到同一个 harness 中可能会重复技能、命令、钩子或配置；将其一次安装到多个 harness 中则不会。

如果你已经叠加了多次安装并且看起来有重复，请直接跳到 重置 / 卸载 ECC。

安装遇到问题？打开简短的 安装或运行时问题表单，或运行 ecc feedback。ECC 从不会自动上传诊断信息。

Claude Code 详情

或者，在 Claude Code 内运行 Claude Code 的原生插件命令：

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

原生路径会安装 ECC 的技能、代理、命令和插件管理的钩子。如果你选择它，就到此为止。不要再向 Claude Code 运行完整的手动安装。

Claude Code 拥有这些内置命令，包括当市场、插件或冲突作用域已存在时它们产生的错误。ECC 无法拦截该解析器。如果任一原生命令报告已存在安装或作用域冲突，请使用 2.2 引导式设置，或在重试前解决冲突的 Claude 插件作用域；不要在之上叠加手动安装。

ECC 安装后，/ecc:configure-ecc 是带命名空间的 Claude 内重新配置技能。它委托给相同的安全设置流程，但仅在插件安装后才可用，并且无法在首次安装期间替代 Claude Code 的内置 /plugin 命令。

Claude Code 插件无法分发 rules，因此只添加你实际想要的规则包：

git clone https://github.com/affaan-m/ECC.git
cd ECC
mkdir -p ~/.claude/rules/ecc
cp -R rules/common ~/.claude/rules/ecc/
cp -R rules/typescript ~/.claude/rules/ecc/  # replace with your stack

从 rules/common 加上一个你实际使用的语言或框架包开始。如果你安装了插件，之后不要运行 ./install.sh --profile full。

更喜欢 settings.json？以声明方式添加市场

直接添加到你的 ~/.claude/settings.json：

{
  "extraKnownMarketplaces": {
    "ecc": {
      "source": {
        "source": "github",
        "repo": "affaan-m/ECC"
      }
    }
  },
  "enabledPlugins": {
    "ecc@ecc": true
  }
}

这与上面两个 /plugin 命令的结果相同。

命名 + 迁移说明（ecc@ecc、affaan-m/ECC、ecc-universal）

ECC 有三个公开标识符，它们不可互换：

• GitHub 源仓库：affaan-m/ECC
• Claude 市场/插件标识符：ecc@ecc
• npm 包：ecc-universal

这是有意为之。Anthropic 市场/插件安装以规范插件标识符为键，因此 ECC 使用 ecc@ecc 来保持工具名称和斜杠命令命名空间足够短，以满足严格的 Desktop/API 验证器。较早的帖子可能仍显示以前的长市场标识符；仅将其视为遗留别名。另外，npm 包保留在 ecc-universal 上，因此 npm 安装和市场安装有意使用不同的名称。

npm 发布按版本标签而非按提交进行，因此 ecc-universal 跟踪的是发布版本（2.1、2.2、……），而不是每次推送到 main。如果你想要最新前沿版本，请从 git 安装。

如果你的本地 Claude 设置被清除或重置，这并不意味着你需要重新购买任何东西。从 node scripts/ecc.js list-installed 开始，然后在重新安装前运行 node scripts/ecc.js doctor 和 node scripts/ecc.js repair。这通常能恢复 ECC 管理的文件，而无需重建你的设置。

Codex 应用和 CLI

当前的 Codex 版本可以将 ECC 作为原生仓库市场插件安装。市场条目使用仓库根目录，因此 Codex 的缓存会收到清单以及所有引用的技能、MCP 配置、钩子运行时、脚本和资源：

codex plugin marketplace add affaan-m/ECC
codex plugin add ecc@ecc
codex plugin list --json
node scripts/codex/check-plugin-cache.js

两个添加命令都是幂等的。以后要刷新，请运行 codex plugin marketplace upgrade ecc，然后运行 codex plugin add ecc@ecc。Codex 在活动的 CODEX_HOME 中存储一个启用的插件状态；它不提供 Claude 的 user、project 和 local 作用域。其原生钩子需要明确的信任决定，并且不使用 Claude 的四个 ECC 钩子配置文件。在 Codex 内，调用 $configure-ecc 以进行引导式提供程序感知流程。

较旧的 scripts/sync-ecc-to-codex.sh 路径是一个已弃用的兼容选项，适用于有意需要在 ~/.codex 中复制并合并配置的用户；原生插件并不需要它。新的同步运行会写入所有权清单，以便清理时能保留被修改过的用户文件。先运行一次 Codex，使 ~/.codex/config.toml 存在，然后：

git clone https://github.com/affaan-m/ECC.git
cd ECC
npm install
bash scripts/sync-ecc-to-codex.sh

要在不触及 Codex 对话或原生插件缓存的情况下检查或移除该旧版层：

node scripts/ecc.js uninstall --legacy-codex-sync --dry-run
node scripts/ecc.js uninstall --legacy-codex-sync

对清单生成之前的安装会保守处理：ECC 会移除其标记的 AGENTS.md 块，但会保留它无法证明归自己所有的已复制文件，并报告这些文件以供审查。

你也可以直接在 Codex 中打开 ECC 仓库，进行项目本地设置。Codex 会读取根目录的 AGENTS.md 以及 .codex/ 中受信任的项目配置，无需全局同步。不要在同步流程之上再添加原生市场插件。

关于仓库导航、表面所有权和 PR diff 包指引，请阅读 Codex ECC 导航图。有关原生生命周期详情，请参阅 .codex 插件说明。

其他代理和编辑器

Cursor、OpenCode、Gemini、Zed、Antigravity、Qwen、Hermes、OpenClaw、Kimi、CodeBuddy、JoyCode、Copilot

克隆一次 ECC，然后选择与你的运行环境匹配的目标：

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

GitHub Copilot 支持已包含在此仓库中。.github/copilot-instructions.md 提供指令层，.github/prompts/ 包含可复用的 /plan、/tdd、/security-review、/build-fix 和 /refactor 提示词，而 .vscode/settings.json 启用 chat.promptFiles。

对于没有原生 ECC 目标的运行环境，请使用 手动适配指南。它说明了如何将一小组 ECC 技能和工作流指令带入聊天式工具，而不假装 hooks 或原生技能发现功能可用。

Cursor 会将代理定义安装到 .cursor/agents/ecc-*.md 下。Cursor 原生的加载行为可能因 Cursor 构建版本而异。ECC 不会将根目录的 AGENTS.md 安装到 .cursor/ 中。该适配器会将 Cursor 的上下文限定在其原生规则和代理表面上。

各运行环境的深入说明（功能对等性、hook 适配器、限制）见下方的 平台支持。

高级安装选项

无 hook 运行时的低上下文安装

低上下文 / 无 hooks 路径

当你想要 ECC 的规则、代理、命令、平台配置和核心工作流，但不想要运行时 hooks 时，请使用此方式：

npx ecc-universal@2.2.3 install --profile minimal --target claude

从源码检出开始，等效命令为：

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

Windows：

.\install.ps1 --profile minimal --target claude

此配置文件有意排除 hooks-runtime。

Claude 手动安装会将每个技能直接放在 ~/.claude/skills/<skill-name>/ 下（对于 claude-project 则放在 .claude/skills/<skill-name>/ 下），以便 Claude Code 能够发现它。升级较旧的 ECC 手动安装时，安装程序只会迁移 ECC 安装状态中记录的嵌套 skills/ecc/ 文件。如果扁平技能目录归用户所有，ECC 会保留它，打印冲突警告，并继续跟踪任何较旧的受管理副本以便安全卸载，而不是覆盖用户文件。

对于启用 hooks 的常规核心配置文件：

./install.sh --profile core --without baseline:hooks --target claude
./install.sh --profile core --no-hooks --target claude

仅在需要时稍后添加 hook 运行时：

./install.sh --target claude --modules hooks-runtime --enable-hooks

任何会实体化 hook 运行时的 profile 或模块安装都需要明确决定。如果没有 --enable-hooks 或 --no-hooks，安装程序会打印 hook 能做什么，并在写入任何内容之前停止。引导式安装程序（ecc install --guided）会交互式地询问此选择。

只选择你需要的组件

先找到正确的组件

询问打包的顾问哪些组件与你的工作匹配：

node scripts/ecc.js consult "security reviews" --target claude

它会返回匹配的组件、相关 profile 以及预览/安装命令。如果你想检查确切的文件计划，请在安装前使用预览命令。

你也可以安装显式的 skills 或 capabilities：

./install.sh --target claude --skills tdd-workflow,security-review
node scripts/ecc.js install --profile minimal --target claude --with capability:machine-learning

手动逐组件复制也可以。每个组件完全独立：

# Just agents
mkdir -p ~/.claude/agents
cp agents/*.md ~/.claude/agents/

# Rules directories (common + language-specific)
mkdir -p ~/.claude/rules/ecc
cp -r rules/common ~/.claude/rules/ecc/
cp -r rules/typescript ~/.claude/rules/ecc/   # pick your stack

# Core/general skills only (Claude Code loads skills from direct children
# of ~/.claude/skills; do not nest manual installs under ~/.claude/skills/ecc/)
mkdir -p ~/.claude/skills
cp -r .agents/skills/* ~/.claude/skills/
cp -r skills/search-first ~/.claude/skills/

# Optional: maintained slash-command compatibility during migration
mkdir -p ~/.claude/commands
cp commands/*.md ~/.claude/commands/

已退役的 shim 位于 legacy-command-shims/。仅当你仍然需要诸如 /tdd 之类的旧名称时，才从那里复制单个文件。

项目本地规则而非全局规则

当 ECC 的标准应适用于单个仓库而非每个 Claude Code 会话时，请使用项目本地规则：

cd your-project
mkdir -p .claude/rules/ecc
cp -R /path/to/ECC/rules/common .claude/rules/ecc/
cp -R /path/to/ECC/rules/typescript .claude/rules/ecc/

规则是始终加载的上下文，因此请从 common 和你实际使用的技术栈的一个包开始。手动复制规则时，请复制整个语言目录（例如 rules/common 或 rules/golang），而不是其中的文件，以便相对引用保持有效且文件名不会冲突。

完全手动安装 Claude

仅当你有意跳过插件路径时才使用此方法：

git clone https://github.com/affaan-m/ECC.git
cd ECC
./install.sh --profile full --enable-hooks

Windows：

git clone https://github.com/affaan-m/ECC.git
cd ECC
.\install.ps1 --profile full --enable-hooks

这些示例启用自动 hook 运行时。若要在没有 hook 的情况下安装，请将 --enable-hooks 替换为 --no-hooks。

如果你选择此路径，请就此停止。不要同时运行 /plugin install。

对于手动挑选的安装，Claude 会将 skills 发现为 ~/.claude/skills/ 的直接子项；不要将它们嵌套在 ~/.claude/skills/ecc/ 下。

安装 hooks

不要将原始仓库 hooks/hooks.json 复制到 ~/.claude/settings.json 或 ~/.claude/hooks/hooks.json。该文件面向插件/仓库；请使用安装程序，以便 hook 命令路径被正确重写：

bash ./install.sh --target claude --modules hooks-runtime --enable-hooks

这会将 hook 脚本安装到 ~/.claude/ 下，并在 ~/.claude/settings.json 中注册解析后的 hook 条目。现有的用户设置和 hooks 会被保留；ECC 拥有的条目通过稳定 ID 进行跟踪，以实现幂等更新和安全卸载。

如果你通过 /plugin install 安装了 ECC，请不要将这些 hooks 复制到 settings.json。Claude Code v2.1+ 已经自动加载插件 hooks/hooks.json，在 settings.json 中重复它们会导致重复执行和跨平台 hook 冲突。

在 Windows 上，Claude 的配置根目录是 %USERPROFILE%\.claude；使用以下命令安装 hook 运行时：

pwsh -File .\install.ps1 --target claude --modules hooks-runtime --enable-hooks

配置 MCP

Claude 插件安装有意不自动启用 ECC 捆绑的 MCP 服务器定义。这避免了在严格的第三方网关上出现过长的插件 MCP 工具名称，同时保持手动 MCP 设置可用。

使用 Claude Code 的 /mcp 命令或 CLI 管理的 MCP 设置来进行实时 Claude Code 服务器更改；Claude Code 会将这些选择持久化到 ~/.claude.json 中。对于仓库本地 MCP 访问，请将所需的 MCP 服务器定义从 mcp-configs/mcp-servers.json 复制到项目范围的 .mcp.json 中。

ECC 仅附带一个默认连接器（chrome-devtools）；其他所有内容都是包装 CLI/REST API 的 skill 或可选的目录条目。该规则以及 2026 年 6 月退役先前六个默认项的审计记录在 docs/MCP-CONNECTOR-POLICY.md 中。

如果你已经运行自己的 ECC 捆绑 MCP 副本，请设置：

export ECC_DISABLED_MCPS="chrome-devtools"

ECC 管理的安装和 Codex 同步流程将跳过或移除这些捆绑服务器，而不是重新添加重复项。ECC_DISABLED_MCPS 是 ECC 安装/同步过滤器，而不是实时 Claude Code 开关。

重要：将 YOUR_*_HERE 占位符替换为你的实际 API 密钥。

多模型命令需要额外设置

multi-* 命令不包含在基础插件/规则安装中。

要使用 /multi-plan、/multi-execute、/multi-backend、/multi-frontend 和 /multi-workflow，你还必须安装 ccg-workflow 运行时。请使用 上游 CCG 安装指南 选择并查看确切的版本，然后初始化已安装的运行时。ECC 不捆绑 CCG，也不保证存在兼容且经过审计的 CCG 版本；本指南不会引导安装未指定版本的注册表版本。

该运行时提供这些命令所需的外部依赖，包括：

• ~/.claude/bin/codeagent-wrapper
• ~/.claude/.ccg/prompts/*

如果没有 ccg-workflow，这些 multi-* 命令将无法正确运行。

重置、修复或卸载

重置 / 卸载 ECC

如果你是从通用包安装的，请在安装时所用的同一项目目录中运行这些命令：

npx ecc-universal@2.2.3 list-installed
npx ecc-universal@2.2.3 doctor
npx ecc-universal@2.2.3 repair
npx ecc-universal@2.2.3 uninstall --dry-run
npx ecc-universal@2.2.3 uninstall

从源码检出安装时，请在重新安装前检查受管状态：

node scripts/ecc.js list-installed
node scripts/ecc.js doctor
node scripts/ecc.js repair
node scripts/ecc.js uninstall --dry-run

对于直接源码检出卸载：

node scripts/uninstall.js --dry-run
node scripts/uninstall.js

如果你要离开，卸载命令会打印一个可选的 20 秒反馈表单。它是一个公开的 GitHub issue，绝不会阻止卸载，ECC 也不会上传诊断信息。你也可以随时运行 ecc feedback 来查看问题、反馈和功能路由。

插件用户应从 Claude Code 中移除该插件，然后仅删除他们手动复制且不再需要的规则文件夹。ECC 只删除其安装状态中记录的文件。它不会声称拥有你的 harness 目录中的无关文件。

如果你叠加了多种方法，请按以下顺序清理：

1. 移除 Claude Code 插件安装。
2. 在包含受管安装状态的项目目录中运行 ECC 卸载命令。
3. 删除你手动复制且不再需要的任何额外规则文件夹。
4. 使用单一路径重新安装一次。

开始使用 ECC

从你需要的工作流开始，而不是完整目录。

插件命令和手动命令

Claude Code 插件命令使用命名空间形式：

/ecc:plan "Add authentication"

手动安装可能会暴露较短的兼容形式：

/plan "Add authentication"

Skills 是主要的工作流界面。命令仍然是便捷入口和兼容垫片。使用以下命令检查已安装的内容：

/plugin list ecc@ecc

我应该使用哪个 agent？

Skills 是规范的工作流界面；维护的斜杠条目仍可用于命令优先的工作流。

常见工作流

以下斜杠形式在仍属于维护命令界面的地方显示。已退役的短名称垫片（如 /tdd 和 /eval）位于 legacy-command-shims/ 中，仅供显式选择加入。

开始新功能：

/ecc:plan "Add user authentication with OAuth"
                                              -> planner creates implementation blueprint
tdd-workflow skill                            -> tdd-guide enforces write-tests-first
/code-review                                  -> code-reviewer checks your work

修复 bug：

tdd-workflow skill                            -> tdd-guide: write a failing test that reproduces it
                                              -> implement the fix, verify test passes
/code-review                                  -> code-reviewer: catch regressions

准备生产环境：

/security-scan                                -> security-reviewer: OWASP Top 10 audit
e2e-testing skill                             -> e2e-runner: critical user flow tests
/test-coverage                                -> verify 80%+ coverage

自托管模型与自定义端点

ECC 通过每个 harness 的正常配置工作，因此你可以使用官方提供商、兼容的自定义 API 端点或模型网关，或自托管模型，而无需更改 ECC 的工作流。

对于 Claude Code，ECC 不会硬编码 Anthropic 托管的传输设置。最小网关示例：

export ANTHROPIC_BASE_URL=https://your-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=your-token
claude

如果你的网关重映射了模型名称，请在 Claude Code 中配置，而不是在 ECC 中。一旦 claude CLI 已经正常工作，ECC 的 hooks、skills、commands 和 rules 就与模型提供商无关。参见 Anthropic 的 LLM 网关文档 和 模型配置文档。

使用独立的计算和推理服务设置，在该网关后面运行或自托管任何开源模型。如果你需要 GPU 算力，Itô 是 ECC 的首选计算赞助商；任何 GPU 提供商都可以。赞助链接是被动的：它不会发起 RFQ、预留容量、配置计算或设置推理服务。另外，ecc ito find 会调用显式配置的规范 Itô CLI 并提交实时认证的 RFQ；它不会预留容量。通过 Itô 的托管推理尚未上线。

使用 ECC + Itô 算力自托管 Kimi

Kimi Code harness 和模型推理层是分开的。ECC 配置 agent harness；你提供 API 端点（获取 Kimi API 密钥）或在你自己的 GPU 算力上自托管开放权重的 Kimi 模型。此适配器已针对 Kimi Code 0.31.x 验证（@moonshot-ai/kimi-code）：

使用 Kimi Code 的官方提供商指南配置端点，然后安装 ECC：

bash ./install.sh --target kimi --profile minimal
node scripts/ecc.js doctor --target kimi
kimi

Kimi Code 会原生发现已安装的 .kimi-code/AGENTS.md 指令和 .kimi-code/skills/ 工作流；项目级 .agents/skills/ 也是官方发现位置。ECC 会安全地将项目 MCP 条目合并到 .kimi-code/mcp.json 中，并且不会更改用户级 ~/.kimi-code/config.toml。Kimi Code 支持原生 hooks，但 ECC 当前的管理项目适配器不会配置它们，因此此安装程序不提供 Kimi hook 配置文件。安装程序的 dry-run 和回归测试套件会验证每次受管理的 Kimi 写入都保持在项目本地的 .kimi-code/ 根目录内。

Itô 计算 CLI 桥接

ecc ito 委托给单独安装的规范 Itô 客户端；ECC 不维护第二个 API 客户端。ecc ito login [--no-browser] 执行设备授权，默认打开 Itô 验证页面，并将设备令牌持久化到 macOS Keychain；--no-browser 会抑制页面跳转。ECC 本身不进行浏览器自动化。ecc ito auth 仅用于验证，并拒绝 --no-browser。可用的操作有 ecc ito login、ecc ito auth、ecc ito find、ecc ito status，以及单独门控的 ecc ito evals。匹配的 MCP 工具仍为 ito_auth、ito_find 和 ito_status；ito_auth 验证现有凭据，节点资格仅通过 CLI 进行。

ito-compute-cli 包目前尚未发布。请在 cli/ito-compute-cli 下从 Itô 运行时仓库（在 desk 加固期间为私有；设计合作伙伴可访问）本地构建它，运行 npm ci 和 npm run check，然后将 ECC_ITO_CLI_EXECUTABLE 设置为该构建的绝对 dist/bin/ito.js 路径。登录永远不会继承 ITO_API_KEY；auth、find 和 status 在配置后直接转发 ITO_API_KEY，且不需要 ITO_AUTH_MODE=legacy。ecc ito logout 会撤销当前设备凭据，如果无法确认远程撤销，则保留其本地副本。设备令牌默认使用 macOS Keychain；显式文件回退必须保留仅所有者可访问的目录/文件权限。ECC 不会通过 PATH 发现这个携带凭据的客户端。有关完整的 RFQ 权限和 MCP 设置契约，请参见 ito-compute skill。

find 提交一个实时认证的 RFQ。它不预留容量。evals 同时需要 ITO_ENABLE_SIXTYTWO_LIVE=1 和 --live-sixtytwo、一个单独安装的 sixtytwo-cli==0.3.33、一个显式的节点列表，以及一个已存在的绝对配置目录。它不能租用、启动、恢复、修复或购买。ECC 不暴露任何报价锁定、购买、工作负载或推理路径，并且它绝不会用本地结果替代缺失的客户端或失败的实时调用。

新内容

当前版本：2.2.3（2026-10-01）。2.2 系列的亮点：

• 跨 Claude Code、Codex 和 Kimi Code 的引导式、清单驱动安装，具备安装状态所有权、doctor、修复和卸载。
• 原生 Antigravity 安装、轻量 Pi 适配器，以及在 Linux、macOS 和 Windows 上测试的打包产物发布门禁。
• Plan Canvas 浏览器审查、统一记忆库（ecc memory）以及 Itô 计算技能家族。

完整历史：CHANGELOG.md。各版本说明和证据位于 docs/releases/ 下。

v2.0.0：Agent Harness 操作系统（2026 年 6 月）

2.0 系列的稳定毕业：控制面板基板、工作树生命周期服务、orch-* 编排器家族以及 Discord 社区。说明：docs/releases/2.0.0/release-notes.md。

内部内容

ECC/
|-- agents/           # 68 specialized subagents for delegation
|-- skills/           # 293 reusable workflows loaded on demand
|-- commands/         # 94 maintained slash-command shims
|-- rules/            # opt-in common and language standards
|-- hooks/            # runtime automation and enforcement
|-- scripts/          # install, repair, sync, orchestration, and checks
|-- .claude-plugin/   # Claude Code marketplace manifest
|-- .codex/           # Codex reference configuration and agent roles
|-- .opencode/        # OpenCode plugin, commands, and instructions
|-- .cursor/          # Cursor rules and hook adapter
|-- docs/             # public setup, architecture, and operating guides

根目录是唯一事实来源。平台适配器打包或映射这些相同的工作流，而不是维护单独的副本。

带注释的组件目录

ECC/
|-- .claude-plugin/   # Plugin and marketplace manifests
|   |-- plugin.json         # Plugin metadata and component paths
|   |-- marketplace.json    # Marketplace catalog for /plugin marketplace add
|
|-- agents/           # 67 specialized subagents for delegation
|   |-- planner.md           # Feature implementation planning
|   |-- architect.md         # System design decisions
|   |-- tdd-guide.md         # Test-driven development
|   |-- code-reviewer.md     # Quality and security review
|   |-- security-reviewer.md # Vulnerability analysis
|   |-- build-error-resolver.md
|   |-- e2e-runner.md        # Playwright E2E testing
|   |-- refactor-cleaner.md  # Dead code cleanup
|   |-- doc-updater.md       # Documentation sync
|   |-- docs-lookup.md       # Documentation/API lookup
|   |-- chief-of-staff.md    # Communication triage and drafts
|   |-- loop-operator.md     # Autonomous loop execution
|   |-- harness-optimizer.md # Harness config tuning
|   |-- cpp-reviewer.md      # C++ code review
|   |-- cpp-build-resolver.md # C++ build error resolution
|   |-- fsharp-reviewer.md   # F# functional code review
|   |-- go-reviewer.md       # Go code review
|   |-- go-build-resolver.md # Go build error resolution
|   |-- python-reviewer.md   # Python code review
|   |-- database-reviewer.md # Database/Supabase review
|   |-- typescript-reviewer.md # TypeScript/JavaScript code review
|   |-- java-reviewer.md     # Java/Spring Boot code review
|   |-- java-build-resolver.md # Java/Maven/Gradle build errors
|   |-- kotlin-reviewer.md   # Kotlin/Android/KMP code review
|   |-- kotlin-build-resolver.md # Kotlin/Gradle build errors
|   |-- harmonyos-app-resolver.md # HarmonyOS/ArkTS app development
|   |-- rust-reviewer.md     # Rust code review
|   |-- rust-build-resolver.md # Rust build error resolution
|   |-- pytorch-build-resolver.md # PyTorch/CUDA training errors
|   |-- mle-reviewer.md      # Production ML pipeline, eval, serving, and monitoring review
|
|-- skills/           # Workflow definitions and domain knowledge
|   |-- coding-standards/           # Language best practices
|   |-- clickhouse-io/              # ClickHouse analytics, queries, data engineering
|   |-- backend-patterns/           # API, database, caching patterns
|   |-- frontend-patterns/          # React, Next.js patterns
|   |-- frontend-slides/            # HTML slide decks and PPTX-to-web presentation workflows
|   |-- article-writing/            # Long-form writing in a supplied voice without generic AI tone
|   |-- content-engine/             # Multi-platform social content and repurposing workflows
|   |-- market-research/            # Source-attributed market, competitor, and investor research
|   |-- investor-materials/         # Pitch decks, one-pagers, memos, and financial models
|   |-- investor-outreach/          # Personalized fundraising outreach and follow-up
|   |-- continuous-learning/        # Legacy v1 Stop-hook pattern extraction
|   |-- continuous-learning-v2/     # Instinct-based learning with confidence scoring
|   |-- iterative-retrieval/        # Progressive context refinement for subagents
|   |-- strategic-compact/          # Manual compaction suggestions (Longform Guide)
|   |-- tdd-workflow/               # TDD methodology
|   |-- security-review/            # Security checklist
|   |-- eval-harness/               # Verification loop evaluation (Longform Guide)
|   |-- verification-loop/          # Continuous verification (Longform Guide)
|   |-- videodb/                    # Video and audio: ingest, search, edit, generate, stream
|   |-- golang-patterns/            # Go idioms and best practices
|   |-- golang-testing/             # Go testing patterns, TDD, benchmarks
|   |-- cpp-coding-standards/       # C++ coding standards from C++ Core Guidelines
|   |-- cpp-testing/                # C++ testing with GoogleTest, CMake/CTest
|   |-- django-patterns/            # Django patterns, models, views
|   |-- django-security/            # Django security best practices
|   |-- django-tdd/                 # Django TDD workflow
|   |-- django-verification/        # Django verification loops
|   |-- laravel-patterns/           # Laravel architecture patterns
|   |-- laravel-security/           # Laravel security best practices
|   |-- laravel-tdd/                # Laravel TDD workflow
|   |-- laravel-verification/       # Laravel verification loops
|   |-- python-patterns/            # Python idioms and best practices
|   |-- python-testing/             # Python testing with pytest
|   |-- quarkus-patterns/           # Java Quarkus patterns
|   |-- quarkus-security/           # Quarkus security
|   |-- quarkus-tdd/                # Quarkus TDD
|   |-- quarkus-verification/       # Quarkus verification
|   |-- rails-patterns/             # Rails architecture patterns
|   |-- springboot-patterns/        # Java Spring Boot patterns
|   |-- springboot-security/        # Spring Boot security
|   |-- springboot-tdd/             # Spring Boot TDD
|   |-- springboot-verification/    # Spring Boot verification
|   |-- configure-ecc/              # Interactive installation wizard
|   |-- security-scan/              # AgentShield security auditor integration
|   |-- java-coding-standards/      # Java coding standards
|   |-- jpa-patterns/               # JPA/Hibernate patterns
|   |-- postgres-patterns/          # PostgreSQL optimization patterns
|   |-- nutrient-document-processing/ # Document processing with Nutrient API
|   |-- database-migrations/        # Migration patterns (Prisma, Drizzle, Django, Go)
|   |-- api-design/                 # REST API design, pagination, error responses
|   |-- deployment-patterns/        # CI/CD, Docker, health checks, rollbacks
|   |-- docker-patterns/            # Docker Compose, networking, volumes, container security
|   |-- e2e-testing/                # Playwright E2E patterns and Page Object Model
|   |-- content-hash-cache-pattern/ # SHA-256 content hash caching for file processing
|   |-- cost-aware-llm-pipeline/    # LLM cost optimization, model routing, budget tracking
|   |-- regex-vs-llm-structured-text/ # Decision framework: regex vs LLM for text parsing
|   |-- swift-actor-persistence/    # Thread-safe Swift data persistence with actors
|   |-- swift-protocol-di-testing/  # Protocol-based DI for testable Swift code
|   |-- search-first/               # Research-before-coding workflow
|   |-- skill-stocktake/            # Audit skills and commands for quality
|   |-- liquid-glass-design/        # iOS 26 Liquid Glass design system
|   |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels
|   |-- swift-concurrency-6-2/      # Swift 6.2 Approachable Concurrency
|   |-- mle-workflow/               # Production ML data contracts, evals, deployment, monitoring
|   |-- perl-patterns/              # Modern Perl 5.36+ idioms and best practices
|   |-- perl-security/              # Perl security patterns, taint mode, safe I/O
|   |-- perl-testing/               # Perl TDD with Test2::V0, prove, Devel::Cover
|   |-- autonomous-loops/           # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration
|   |-- plankton-code-quality/      # Write-time code quality enforcement with Plankton hooks
|   |-- codehealth-mcp/             # Optional CodeScene Code Health MCP skill (opt-in)
|   |-- docs/examples/project-guidelines-template.md  # Template for project-specific skills
|
|-- commands/         # Maintained slash-entry compatibility; prefer skills/
|   |-- plan.md             # /plan - Implementation planning
|   |-- code-review.md      # /code-review - Quality review
|   |-- build-fix.md        # /build-fix - Fix build errors
|   |-- refactor-clean.md   # /refactor-clean - Dead code removal
|   |-- quality-gate.md     # /quality-gate - Verification gate
|   |-- learn.md            # /learn - Extract patterns mid-session (Longform Guide)
|   |-- learn-eval.md       # /learn-eval - Extract, evaluate, and save patterns
|   |-- checkpoint.md       # /checkpoint - Save verification state (Longform Guide)
|   |-- setup-pm.md         # /setup-pm - Configure package manager
|   |-- go-review.md        # /go-review - Go code review
|   |-- go-test.md          # /go-test - Go TDD workflow
|   |-- go-build.md         # /go-build - Fix Go build errors
|   |-- skill-create.md     # /skill-create - Generate skills from git history
|   |-- instinct-status.md  # /instinct-status - View learned instincts
|   |-- instinct-import.md  # /instinct-import - Import instincts
|   |-- instinct-export.md  # /instinct-export - Export instincts
|   |-- evolve.md           # /evolve - Cluster instincts into skills
|   |-- prune.md            # /prune - Delete expired pending instincts
|   |-- pm2.md              # /pm2 - PM2 service lifecycle management
|   |-- multi-plan.md       # /multi-plan - Multi-agent task decomposition
|   |-- multi-execute.md    # /multi-execute - Orchestrated multi-agent workflows
|   |-- multi-backend.md    # /multi-backend - Backend multi-service orchestration
|   |-- multi-frontend.md   # /multi-frontend - Frontend multi-service orchestration
|   |-- multi-workflow.md   # /multi-workflow - General multi-service workflows
|   |-- sessions.md         # /sessions - Session history management
|   |-- test-coverage.md    # /test-coverage - Test coverage analysis
|   |-- update-docs.md      # /update-docs - Update documentation
|   |-- update-codemaps.md  # /update-codemaps - Update codemaps
|   |-- python-review.md    # /python-review - Python code review
|-- legacy-command-shims/   # Opt-in archive for retired shims such as /tdd and /eval
|   |-- tdd.md              # /tdd - Prefer the tdd-workflow skill
|   |-- e2e.md              # /e2e - Prefer the e2e-testing skill
|   |-- eval.md             # /eval - Prefer the eval-harness skill
|   |-- verify.md           # /verify - Prefer the verification-loop skill
|   |-- orchestrate.md      # /orchestrate - Prefer dmux-workflows or multi-workflow
|
|-- rules/            # Always-follow guidelines (copy to ~/.claude/rules/ecc/)
|   |-- README.md            # Structure overview and installation guide
|   |-- common/              # Language-agnostic principles
|   |   |-- coding-style.md    # Immutability, file organization
|   |   |-- git-workflow.md    # Commit format, PR process
|   |   |-- testing.md         # TDD, 80% coverage requirement
|   |   |-- performance.md     # Model selection, context management
|   |   |-- patterns.md        # Design patterns, skeleton projects
|   |   |-- hooks.md           # Hook architecture, TodoWrite
|   |   |-- agents.md          # When to delegate to subagents
|   |   |-- security.md        # Mandatory security checks
|   |-- typescript/          # TypeScript/JavaScript specific
|   |-- python/              # Python specific
|   |-- golang/              # Go specific
|   |-- swift/               # Swift specific
|   |-- php/                 # PHP specific
|   |-- arkts/               # HarmonyOS / ArkTS specific
|
|-- hooks/            # Trigger-based automations
|   |-- README.md                 # Hook documentation, recipes, and customization guide
|   |-- hooks.json                # All hooks config (PreToolUse, PostToolUse, Stop, etc.)
|   |-- memory-persistence/       # Session lifecycle hooks (Longform Guide)
|   |-- strategic-compact/        # Compaction suggestions (Longform Guide)
|
|-- scripts/          # Cross-platform Node.js scripts
|   |-- lib/                     # Shared utilities
|   |   |-- utils.js             # Cross-platform file/path/system utilities
|   |   |-- package-manager.js   # Package manager detection and selection
|   |-- hooks/                   # Hook implementations
|   |   |-- session-start.js     # Load context on session start
|   |   |-- session-end.js       # Save state on session end
|   |   |-- pre-compact.js       # Pre-compaction state saving
|   |   |-- suggest-compact.js   # Strategic compaction suggestions
|   |   |-- evaluate-session.js  # Extract patterns from sessions
|   |-- setup-package-manager.js # Interactive PM setup
|
|-- tests/            # Test suite
|   |-- lib/                     # Library tests
|   |-- hooks/                   # Hook tests
|   |-- run-all.js               # Run all tests
|
|-- contexts/         # Dynamic system prompt injection contexts (Longform Guide)
|   |-- dev.md              # Development mode context
|   |-- review.md           # Code review mode context
|   |-- research.md         # Research/exploration mode context
|
|-- examples/         # Example configurations and sessions
|   |-- CLAUDE.md             # Example project-level config
|   |-- user-CLAUDE.md        # Example user-level config
|   |-- saas-nextjs-CLAUDE.md   # Real-world SaaS (Next.js + Supabase + Stripe)
|   |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL)
|   |-- django-api-CLAUDE.md      # Real-world Django REST API (DRF + Celery)
|   |-- laravel-api-CLAUDE.md     # Real-world Laravel API (PostgreSQL + Redis)
|   |-- rust-api-CLAUDE.md        # Real-world Rust API (Axum + SQLx + PostgreSQL)
|
|-- mcp-configs/      # MCP server configurations
|   |-- mcp-servers.json    # GitHub, Supabase, Vercel, Railway, etc.
|
|-- ecc_dashboard.py  # Desktop GUI dashboard (Tkinter)
|
|-- marketplace.json  # Self-hosted marketplace config (for /plugin marketplace add)

仪表盘 GUI

启动桌面仪表盘以可视化探索 ECC 组件：

npm run dashboard
# or
python3 ./ecc_dashboard.py

功能：

• 选项卡式界面：Agents、Skills、Commands、Rules、Settings
• 深色/浅色主题切换
• 字体自定义（字体族和大小）
• 页眉和任务栏中的项目徽标
• 跨所有组件搜索和筛选

关键概念

Agents、skills、hooks 和 rules 详解

Agents

子代理以有限范围处理委派任务。示例：

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: Read, Grep, Glob, Bash
model: opus
---

You are a senior code reviewer...

Skills

Skills 是主要的工作流界面。它们可以被直接调用、自动建议，并由代理复用。ECC 在迁移期间仍提供维护中的 commands/，而已退役的短名称垫片位于 legacy-command-shims/ 下，仅用于显式选择加入。新的工作流开发应首先落在 skills/ 中。

# TDD Workflow

1. Define interfaces first
2. Write failing tests (RED)
3. Implement minimal code (GREEN)
4. Refactor (IMPROVE)
5. Verify 80%+ coverage

Hooks

Hooks 在工具事件上触发。示例：对 console.log 发出警告：

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
  "hooks": [{
    "type": "command",
    "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] Remove console.log' >&2"
  }]
}

Rules

Rules 是始终遵循的准则，组织为 common/（语言无关）+ 特定语言目录：

rules/
  common/          # Universal principles (always install)
  typescript/      # TS/JS specific patterns and tools
  python/          # Python specific patterns and tools
  golang/          # Go specific patterns and tools
  swift/           # Swift specific patterns and tools
  php/             # PHP specific patterns and tools
  arkts/           # HarmonyOS / ArkTS patterns and constraints

有关安装和结构详情，请参阅 rules/README.md。

指南

本仓库是原始代码。指南解释一切。

命令快速参考 | 手动适配指南 | 故障排除 FAQ | 路线图

为什么选择 ECC？

TDD：测试驱动开发

/ecc:plan "Add usage-based billing alerts"
  -> confirm or edit the plan
  -> activate tdd-workflow
  -> capture RED evidence before implementation
  -> implement until GREEN
  -> review from fresh context
  -> fix findings with regression tests
  -> verify build, lint, types, and tests

结果不只是代码。它是一条证据链：计划、失败的测试、通过的测试、评审发现以及最终验证。

技能让上下文保持聚焦

规则、技能、Agent 和钩子解决不同的问题。将这些职责分开，正是 ECC 在不把整个仓库塞进每个会话的情况下增加能力的方式。

在 harness 之间共享上下文

ECC 的 Memory Vault 为 Claude、Codex、Hermes、OpenClaw、Kimi 和其他 harness 提供一种本地、可检查的 Markdown 格式，用于持久上下文和交接。项目和团队记忆位于 .ecc/memory/ 下；用户记忆位于 ~/.ecc/memory/ 下。

仅技能、最小、手动和 Claude 插件安装不会把 Memory Vault 运行时放到 PATH 上。在使用 CLI 或可选 MCP 服务器之前，请单独安装 npm 运行时：

npm install -g ecc-universal@2.2.3
ecc memory init --scope project
ecc memory search "authentication migration" --target-harness codex
ecc memory doctor

记忆是未经审查的上下文，不是可执行策略。请对照权威来源验证重要声明，并将已接受的知识提升为受治理的项目文档。可选的 ecc-memory-mcp 服务器暴露相同的受限保存、搜索、读取和 doctor 接口，但默认不会自行启用。

打开统一记忆工作流 →

深入 Memory Vault：作用域、交接和信任边界

Memory Vault 存储可移植的 ecc.memory.v1 Markdown 文档，而不是复制供应商记录或在 Agent 之间通过电子邮件传递上下文。项目记忆由故障关闭的 .gitignore 保护；团队作用域仅用于经人工检查、受版本控制的共享。团队记忆即使在提交后也仍是未经审查的上下文。

安装上述运行时后，检查 CLI 和可选 MCP 入口点是否可用：

ecc memory --help
command -v ecc-memory-mcp

# Initialize the project vault.
ecc memory init --scope project

# Write a handoff body to a regular file, then target the next harness.
ecc memory handoff \
  --from hermes \
  --target codex \
  --title "Continue authentication migration" \
  --body-file ./handoff.md

# Recall it from another harness.
ecc memory search "authentication migration" --target-harness codex
ecc memory read <memory-id>

# Validate the vault before sharing team memories.
ecc memory doctor

记忆正文只能通过 --stdin 或 --body-file 接受，不能作为命令行值传入。首个版本让每个 vault 条目都保持未经审查且仅可创建；人工审查会将已接受的知识提升为受治理的项目文档，而不是改变记忆信任。正常搜索召回会返回活动的项目和团队记忆。直接按 ID 读取可以检查非活动条目。用户作用域召回必须显式请求。Agent 必须对照权威来源验证重要声明，并且绝不能将召回正文视为可执行指令或策略。

对于可选的 MCP 访问，请将 mcp-configs/mcp-servers.json 中的 ecc-memory-vault 条目添加到每个需要它的 harness，然后运行 ecc-memory-mcp。该服务器仅暴露 memory_save、memory_search、memory_read 和 memory_doctor。每个服务器都必须以小写 ECC_MEMORY_HARNESS 身份启动；该身份与服务器绑定，不能由工具调用方提供。用户作用域还要求由操作员控制的 ECC_MEMORY_ALLOW_USER_SCOPE=1 选择加入。工作流和信任边界见 skills/unified-memory/SKILL.md，能力契约见 docs/design/ecc-memory-vault.md。

平台支持

ECC 的核心 Node.js CLI 和托管安装程序可在 Windows、macOS 和 Linux 上运行，但可选功能并未完全对等。部分持续学习、GAN 和编排路径仍需要 Bash 或 Python；各 harness 还暴露了不同的 hook、agent 和 skill API。

将下方的 stable、beta、experimental 和 instruction-only 视为能力声明，而非营销层级。

包管理器检测

插件会自动检测你偏好的包管理器（npm、pnpm、yarn 或 bun），优先级如下：

1. 环境变量：CLAUDE_PACKAGE_MANAGER
2. 项目配置：.claude/package-manager.json
3. package.json：packageManager 字段
4. 锁文件：从 package-lock.json、yarn.lock、pnpm-lock.yaml 或 bun.lockb 检测
5. 全局配置：~/.claude/package-manager.json
6. 回退：第一个可用的包管理器

要设置你偏好的包管理器：

# Via environment variable
export CLAUDE_PACKAGE_MANAGER=pnpm

# Via global config
node scripts/setup-package-manager.js --global pnpm

# Via project config
node scripts/setup-package-manager.js --project bun

# Detect current setting
node scripts/setup-package-manager.js --detect

或使用 /setup-pm 命令。

Hook 运行时控制（环境变量）

使用运行时标志来调整严格程度或临时禁用特定 hook：

# Hook strictness profile (default: standard)
export ECC_HOOK_PROFILE=standard

# Comma-separated hook IDs to disable
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

# Cap SessionStart additional context (default: 8000 chars)
export ECC_SESSION_START_MAX_CHARS=4000

# Disable SessionStart additional context entirely for low-context/local-model setups
export ECC_SESSION_START_CONTEXT=off

# Session-tmp retention window in days (default: 30).
# Set to 0, off, false, disabled, never, or none to keep all sessions (disable pruning).
export ECC_SESSION_RETENTION_DAYS=14

# Cap how many learned instincts SessionStart injects into context (default: 6)
export ECC_MAX_INJECTED_INSTINCTS=6

# Minimum confidence an instinct needs to be injected, 0-1 (default: 0.7)
export ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7

# SessionStart ranks injected instincts by confidence + project/stack relevance
# (default: on). Project-scoped instincts, and instincts whose domain/trigger
# matches the detected stack (languages, frameworks, plus terraform/dbt markers),
# get a small ranking boost so they surface above unrelated higher-confidence
# ones. Set to off/false/0/no to rank by confidence alone.
export ECC_INSTINCT_RELEVANCE_RANKING=on

# Keep context/scope/loop warnings but suppress API-rate cost estimates
export ECC_CONTEXT_MONITOR_COST_WARNINGS=off

Windows PowerShell：

[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User')
[Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User')

Agent 数据主目录（多 harness 隔离）

记忆持久化 hook（会话摘要、学到的技能、会话别名、指标）将数据存储在单个 agent 数据根目录下。默认情况下该根目录为 ~/.claude。当你在同一台机器上同时在 Claude Code 和 Cursor 中使用 ECC 时，请为 Cursor 设置单独的根目录，以免两个环境互相覆盖对方的会话文件：

# Cursor-only boundary (Claude Code keeps the default ~/.claude)
export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc"

在该根目录下解析的路径包括：

• $ECC_AGENT_DATA_HOME/session-data/：会话摘要
• $ECC_AGENT_DATA_HOME/skills/learned/：来自 evaluate-session 的已学技能
• $ECC_AGENT_DATA_HOME/session-aliases.json：会话别名
• $ECC_AGENT_DATA_HOME/metrics/：成本和活动指标

参见 affaan-m/ECC#2065。

Cross-tool capability map and per-harness notes

Cross-tool capability map

Key architectural decisions:

• AGENTS.md at root is the universal cross-tool file (read by Claude Code, Cursor, Codex, and OpenCode; GitHub Copilot uses .github/copilot-instructions.md instead)
• DRY adapter pattern lets Cursor reuse Claude Code's hook scripts without duplication
• Skills format (SKILL.md with YAML frontmatter) works across Claude Code, Codex, and OpenCode
• Codex's narrower native hook set is supplemented by AGENTS.md, optional model_instructions_file overrides, and sandbox permissions

Cursor IDE support in depth

ECC provides Cursor IDE support with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's project layout.

# macOS/Linux
./install.sh --target cursor typescript
./install.sh --target cursor python golang swift php

# Windows PowerShell
.\install.ps1 --target cursor typescript
.\install.ps1 --target cursor python golang swift php

What's included for Cursor

Cursor loading notes

ECC does not install root AGENTS.md into .cursor/. Cursor treats nested AGENTS.md files as directory context, so copying ECC's repo identity into a host project would pollute that project.

Cursor-native loading behavior can vary by Cursor build. ECC installs agents as .cursor/agents/ecc-*.md; if your Cursor build does not expose project agents, those files still work as explicit reference definitions instead of hidden global prompt context.

Memory and data isolation (Cursor + Claude Code)

ECC memory hooks reuse the same scripts/hooks/*.js as Claude Code. For Cursor, ECC tries to keep memory out of ~/.claude automatically:

1. Cursor sessionStart hook (installed to .cursor/hooks.json on --target cursor) injects ECC_AGENT_DATA_HOME for the whole composer session.
2. Hook runtime default: when CURSOR_VERSION or CURSOR_PROJECT_DIR is present, hooks default to ~/.cursor/ecc if the env var is unset.
3. Project config: .cursor/ecc-agent-data.json documents and overrides the path (agentDataHome).
4. Always-on rule: .cursor/rules/ecc-agent-data-home.mdc reminds the agent where memory lives.

You can still override explicitly:

export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc"

To share memory with Claude Code on purpose, set ECC_AGENT_DATA_HOME=~/.claude in the shell or in .cursor/ecc-agent-data.json.

Continuous learning v2 instincts remain separate under CLV2_HOMUNCULUS_DIR (default ~/.local/share/ecc-homunculus).

Hook architecture (DRY adapter pattern)

Cursor has more hook events than Claude Code (20 vs 8). The .cursor/hooks/adapter.js module transforms Cursor's stdin JSON to Claude Code's format, allowing existing scripts/hooks/*.js to be reused without duplication.

Cursor stdin JSON -> adapter.js -> transforms -> scripts/hooks/*.js
                                                (shared with Claude Code)

关键钩子：

• beforeShellExecution：阻止在 tmux 外运行开发服务器（退出码 2），git push 审查
• afterFileEdit：自动格式化 + TypeScript 检查 + console.log 警告
• beforeSubmitPrompt：检测提示词中的密钥（sk-、ghp_、AKIA 模式）
• beforeTabFileRead：阻止 Tab 读取 .env、.key、.pem 文件（退出码 2）
• beforeMCPExecution / afterMCPExecution：MCP 审计日志

规则格式

Cursor 规则使用 YAML frontmatter，包含 description、globs 和 alwaysApply：

---
description: "TypeScript coding style extending common rules"
globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
alwaysApply: false
---

Codex macOS 应用 + CLI 深度支持

ECC 为 macOS 应用和 CLI 提供了受支持的 Codex 原生市场插件和仓库本地配置。原生插件携带共享技能、MCP 配置和经过审查的钩子子集；Codex 将钩子信任置于用户明确控制之下。较旧的同步路径仅保留兼容性。关于仓库导航、表面所有权和 PR diff 包指导，请从 docs/CODEX-NAVIGATION-GUIDE.md 开始。

# Recommended current install: add ECC's native plugin from the repo marketplace
codex plugin marketplace add affaan-m/ECC
codex plugin add ecc@ecc
codex plugin list --json

# Or run Codex CLI in the repo: AGENTS.md and .codex/ are auto-detected
codex

当你确实需要时，旧版复制配置兼容性仍然可用：

# Compatibility-only managed sync into ~/.codex
npm install && bash scripts/sync-ecc-to-codex.sh

# Or copy only the reference config manually
cp .codex/config.toml ~/.codex/config.toml

常规 MCP 同步会保留现有服务器设置，并在其与 ECC 推荐不同时发出警告。因此现有的 chrome-devtools-mcp@latest 条目保持不变；仅更新仓库不会采用推荐的 chrome-devtools-mcp@1.10.1 固定版本。现有的旧版同步用户可以从更新后的 ECC 检出中预览并明确应用刷新：

bash scripts/sync-ecc-to-codex.sh --dry-run --update-mcp
bash scripts/sync-ecc-to-codex.sh --update-mcp

应用前请查看预览：--update-mcp 会替换整个推荐的 chrome-devtools 服务器部分，包括自定义命令参数和嵌套设置。无关的用户管理服务器保持不变。已弃用的默认项（如 Context7）不会通过此标志刷新或迁移。

Codex macOS 应用：

• 将此仓库作为工作区打开。
• 根目录的 AGENTS.md 会被自动检测。
• .codex/config.toml 和 .codex/agents/*.toml 保持项目本地时效果最佳。
• 参考 .codex/config.toml 有意不固定 model 或 model_provider，因此除非你覆盖，Codex 会使用其自身的当前默认值。
• 可选：将 .codex/config.toml 复制到 ~/.codex/config.toml 以设置全局默认值；除非你也复制 .codex/agents/，否则将多智能体角色文件保持项目本地。

仓库和旧版配置层中包含的内容

位于 .agents/skills/ 的技能由 Codex 自动加载。规范的 Anthropic 技能（如 claude-api、frontend-design 和 skill-creator）有意不在此重新打包。当你需要官方版本时，请从 anthropics/skills 安装。

关键限制

Codex 不提供 Claude 风格的钩子执行对等性。原生 ECC 插件包含一个经过审查的钩子子集，需要在 /hooks 中明确信任；AGENTS.md、可选的 model_instructions_file 覆盖以及沙箱/批准设置提供了其余的指令和策略层。

多智能体支持

当前 Codex 构建支持稳定的多智能体工作流。

• 在 .codex/config.toml 中启用 features.multi_agent = true
• 在 [agents.<name>] 下定义角色
• 将每个角色指向 .codex/agents/ 下的一个文件
• 在 CLI 中使用 /agent 来检查或引导子智能体

ECC 附带三个示例角色配置：

Zed 支持

ECC 通过一个保守的 .zed 适配器为项目本地设置、扁平化规则、代理、命令和技能提供 Zed 项目支持。

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

.\install.ps1 --profile minimal --target zed

该适配器将 ECC 管理的文件写入 .zed/ 下，并将 BYOK/OpenRouter 凭据排除在仓库之外。通过 Zed 自己的设置 UI 或本地用户设置配置 Zed 账户或 API 密钥。

深入 OpenCode 支持

ECC 提供测试版 OpenCode 插件集成，包含指令、目录子集、命令、自定义工具和钩子事件。它不提供与 Claude Code 的功能对等。参考配置继承用户的 OpenCode 模型选择，而不是固定某个特定提供商的模型。

# Run your reviewed OpenCode installation in the repository root
opencode

安装时，请使用官方 OpenCode 说明，选择一个确切的版本，并在执行前进行验证。上游 npm 包是 opencode-ai，而不是 opencode。ECC 不保证经过审计的 OpenCode 运行时版本。

配置会从 .opencode/opencode.json 自动检测。

通过插件支持钩子

OpenCode 的插件系统有 20 多种事件类型：

其他 OpenCode 事件：file.edited、file.watcher.updated、message.updated、lsp.client.diagnostics、tui.toast.show 等。

插件安装

选项 1：直接使用

cd ECC
opencode

选项 2：作为 npm 包安装

npm install ecc-universal@2.2.3

然后添加到你的 opencode.json：

{
  "plugin": ["ecc-universal"]
}

该 npm 插件条目会启用 ECC 已发布的 OpenCode 插件模块（钩子/事件和插件工具）。它不会自动将 ECC 的完整命令/代理/指令目录添加到你的项目配置中。

要获得完整的 ECC OpenCode 设置，可以：

• 在此仓库内运行 OpenCode，或
• 将捆绑的 .opencode/ 配置资产复制到你的项目中，并在 opencode.json 中接入 instructions、agent 和 command 条目

文档

• 迁移指南：.opencode/MIGRATION.md
• OpenCode 插件 README：.opencode/README.md
• 合并规则：.opencode/instructions/INSTRUCTIONS.md
• LLM 文档：llms.txt（面向 LLM 的完整 OpenCode 文档）

深入 GitHub Copilot 支持

ECC 通过 Copilot Chat 的原生指令和提示文件系统为 VS Code 提供 GitHub Copilot 支持。无需额外工具。

GitHub Copilot 包含的内容

这些文件已经就位：打开任何包含此项目的仓库，GitHub Copilot Chat 将自动读取 .github/copilot-instructions.md。已提交的 .vscode/settings.json 启用了 chat.promptFiles，因此 VS Code 可以从 .github/prompts/ 加载可复用的提示。

要在 Copilot Chat 中使用工作流提示：

1. 在 VS Code 中打开 Copilot Chat 面板。
2. 点击 回形针 / 附件 图标并选择 Prompt...，或输入 / 并选择一个提示。
3. 选择提示（例如 plan、tdd、security-review）。

功能覆盖

限制

GitHub Copilot 没有 hook 系统或 subagent API，因此 ECC 的 hook 自动化（自动格式化、TypeScript 检查、会话持久化、dev-server 守卫）和 agent 委派均不可用。指令和提示层仍将完整的 ECC 编码理念（标准、安全、TDD 和工作流）带入每个 Copilot Chat 会话。

v2.0.0 中的变化

ECC v2.0.0 稳定了 2.0 系列，包含公开的 Hermes 操作员故事、281 项技能、67 个 agent、94 个命令 shim、会话适配器、MCP 清单、worktree 生命周期服务、编排器工作流以及 ECC Discord 社区。

• v2.0.0 发布说明
• ECC 2.0 参考架构
• Hermes 设置指南
• 从 1.x 迁移指南

Token 优化

如果不管理 token 消耗，agent 使用可能会很昂贵。这些设置可显著降低成本，同时不牺牲质量。完整指南：docs/token-optimization.md。

推荐设置

添加到 ~/.claude/settings.json：

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

Switch to Opus only when you need deep architectural reasoning:

/model opus

Daily workflow commands

If you use a subscription and the context monitor's API-rate estimates are not useful, set ECC_CONTEXT_MONITOR_COST_WARNINGS=off. This only suppresses the agent-facing cost warnings; it does not disable context exhaustion, scope, or loop warnings.

Strategic compaction

The strategic-compact skill suggests /compact at logical breakpoints instead of relying on auto-compaction at 95% context. See skills/strategic-compact/SKILL.md for the full decision guide.

When to compact:

• After research/exploration, before implementation
• After completing a milestone, before starting the next
• After debugging, before continuing feature work
• After a failed approach, before trying a new one

When NOT to compact:

• Mid-implementation (you'll lose variable names, file paths, partial state)

Context window management

Critical: Don't enable all MCPs at once. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k.

• Keep under 10 MCPs enabled per project
• Keep under 80 tools active
• Use /mcp to disable unused Claude Code MCP servers; those runtime choices persist in ~/.claude.json
• Use ECC_DISABLED_MCPS only to filter ECC-generated MCP configs during install/sync flows
• If context is getting heavy, run /context-budget and remove rules you do not need

Agent teams cost warning: Agent Teams spawns multiple context windows. Each teammate consumes tokens independently. Only use for tasks where parallelism provides clear value (multi-module work, parallel reviews). For simple sequential tasks, subagents are more token-efficient.

Requirements

Claude Code CLI version + hooks auto-loading behavior

Claude Code CLI version

Minimum version: v2.1.0 or later. The plugin requires Claude Code CLI v2.1.0+ due to changes in how the plugin system handles hooks.

Check your version:

claude --version

Important: hooks auto-loading behavior

WARNING: For Contributors: Do NOT add a "hooks" field to .claude-plugin/plugin.json. This is enforced by a regression test.

Claude Code v2.1+ automatically loads hooks/hooks.json from any installed plugin by convention. Explicitly declaring it in plugin.json causes a duplicate detection error:

Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file

History: This has caused repeated fix/revert cycles in this repo (#29, #52, #103). The behavior changed between Claude Code versions, leading to confusion. There is now a regression test to prevent this from being reintroduced.

Security

Install ECC only from official sources:

• GitHub repository: https://github.com/affaan-m/ECC
• Claude Code plugin: ecc@ecc
• npm packages: ecc-universal and ecc-agentshield
• GitHub App: https://github.com/apps/ecc-tools
• Website: https://ecc.tools

Scan a project with an already installed, reviewed AgentShield binary (see runner provenance):

agentshield scan --path .

• Report a vulnerability. Use the private process in SECURITY.md (GitHub private vulnerability reporting). Please do not open public issues for security reports.
• Built-in guardrails. GateGuard gates destructive shell commands (including rm, force/path git checkout, and destructive find -exec) before they run; the supply-chain IOC scanner runs in CI; and AgentShield audits your own agent, hook, MCP, permission, and secret surfaces (/security-scan).

Hooks, MCP servers, and context controls

Hooks can run shell commands, MCP servers can hold credentials, and project instructions can enter an agent's context. Treat all three as executable configuration.

Do not copy raw hooks/hooks.json into ~/.claude/settings.json after a plugin install. Modern Claude Code versions load plugin hooks automatically, and a second copy can make them fire twice.

Use /mcp for Claude Code runtime disables; Claude Code persists those choices in ~/.claude.json.

ECC_DISABLED_MCPS is an ECC install/sync filter, not a live Claude Code toggle.

If context is getting heavy, run /context-budget, remove rules you do not need, and disable unused MCP servers. See the token optimization guide.

Security references:

• Security policy
• Security guide
• MCP connector policy
• Supply-chain incident response

Ecosystem Tools

Skill Creator: generate skills from your git history

Two ways to generate skills from your repository:

Option A: Local Analysis (Built-in)

Use the /skill-create command for local analysis without external services:

/skill-create                    # Analyze current repo
/skill-create --instincts        # Also generate instincts for continuous-learning-v2

This analyzes your git history locally and generates SKILL.md files.

Option B: GitHub App (Advanced)

For advanced features (10k+ commits, auto-PRs, team sharing):

Install ECC Tools GitHub App | ecc.tools

# Comment on any issue:
/ecc-tools analyze

Both options create:

• SKILL.md files: Ready-to-use skills for the active harness
• Instinct collections: For continuous-learning-v2
• Pattern extraction: Learns from your commit history

AgentShield: security auditor for agent configs

Built at the Claude Code Hackathon (Cerebral Valley x Anthropic, Feb 2026). 1282 tests, 98% coverage, 102 static analysis rules.

Scan your agent configuration for vulnerabilities, misconfigurations, and injection risks.

Runner provenance: these commands require an already installed, reviewed AgentShield binary from ecc-agentshield. The official package documents the agentshield CLI. Record the selected release, reviewed source and verified package integrity in your installation record. Registry publication alone does not establish an audit; ECC does not supply an audited AgentShield pin here. Do not substitute an unversioned one-shot download. /security-scan is workflow guidance and has the same runner prerequisite.

# Scan only the intended project directory
agentshield scan --path .

# Auto-fix safe issues
agentshield scan --path . --fix

# Deep analysis with three Opus 4.6 agents
agentshield scan --path . --opus --stream

# Generate secure config from scratch
agentshield init

What it scans: CLAUDE.md, settings.json, MCP configs, hooks, agent definitions, and skills across 5 categories: secrets detection (14 patterns), permission auditing, hook injection analysis, MCP server risk profiling, and agent config review.

The --opus flag runs three Claude Opus 4.6 agents in a red-team/blue-team/auditor pipeline. The attacker finds exploit chains, the defender evaluates protections, and the auditor synthesizes both into a prioritized risk assessment. Adversarial reasoning, not just pattern matching.

Output formats: Terminal (color-graded A-F), JSON (CI pipelines), Markdown, HTML. Exit code 2 on critical findings for build gates.

Use /security-scan in Claude Code to run it, or add to CI with the GitHub Action.

GitHub | npm

Continuous Learning v2: instincts

The instinct-based learning system automatically learns your patterns:

/instinct-status        # Show learned instincts with confidence
/instinct-import <file> # Import instincts from others
/instinct-export        # Export your instincts for sharing
/evolve                 # Cluster related instincts into skills

See skills/continuous-learning-v2/ for full documentation. Keep continuous-learning/ only when you explicitly want the legacy v1 Stop-hook learned-skill flow.

Troubleshooting

ECC appears twice or hooks fire twice

The usual cause is installing the Claude plugin and then running ./install.sh --profile full on top of it.

1. Remove the Claude Code plugin install.
2. Run node scripts/ecc.js uninstall --dry-run from the ECC checkout.
3. Remove extra rule folders you manually copied and no longer want.
4. Reinstall once, using one path.

For hook-specific checks, see the hooks README.

My hooks aren't working / "Duplicate hooks file" errors

Do NOT add a "hooks" field to .claude-plugin/plugin.json. Claude Code v2.1+ automatically loads hooks/hooks.json from installed plugins. Explicitly declaring it causes duplicate detection errors. See #29, #52, #103.

Codex marketplace installs but skills do not load

Run the cache check from an ECC checkout:

node scripts/codex/check-plugin-cache.js

If it reports unresolved parent references, refresh the native cache with codex plugin marketplace upgrade ecc, run codex plugin add ecc@ecc again, and restart Codex. Registration in codex plugin list confirms the marketplace entry, while the cache check verifies that the installed manifest can resolve its skills, MCP configuration, and assets. Use bash scripts/sync-ecc-to-codex.sh only when you intentionally need the legacy copied-configuration compatibility path.

More answers: TROUBLESHOOTING.md covers memory, hooks, installation, performance, and common error messages. docs/TROUBLESHOOTING.md tracks workarounds for open Claude Code bugs.

Running Tests

The plugin includes a comprehensive test suite:

# Run all tests
node tests/run-all.js

# Run individual test files
node tests/lib/utils.test.js
node tests/lib/package-manager.test.js
node tests/hooks/hooks.test.js

Background

I've been using Claude Code since the experimental rollout. Won the Anthropic x Forum Ventures hackathon in Sep 2025 with @DRodriguezFX, built zenith.chat entirely with agentic workflows.

These configs are battle-tested across multiple production applications.

Community and Project

Sponsors and ECC Pro

ECC stays free because sponsors and Pro users fund the work. Sponsor logos are at the top of this README; the full roster and tiers are in SPONSORS.md.

ECC Pro adds private-repo analysis, PR-triggered audits, AgentShield-backed scanning, automatic push and PR checks, pooled team usage, and priority support through the hosted GitHub App.

Become a sponsor | Sponsor tiers | Sponsorship program

Contributing

Contributions are welcome across skills, agents, rules, hooks, docs, tests, adapters, and security improvements.

• Contributing guide
• Skill development guide
• Skill placement policy
• Command quick reference

The short version:

1. Fork the repo
2. Create your skill in skills/your-skill-name/SKILL.md (with YAML frontmatter)
3. Or create an agent in agents/your-agent.md
4. Submit a PR with a clear description of what it does and when to use it

Ideas for contributions:

• Language-specific skills (Rust, C#, Kotlin, Java): Go, Python, Perl, Swift, TypeScript, and HarmonyOS/ArkTS already included
• Framework-specific configs (Rails, FastAPI): Django, NestJS, Spring Boot, and Laravel already included
• DevOps agents (Kubernetes, Terraform, AWS, Docker)
• Testing strategies (different frameworks, visual regression)
• Domain-specific knowledge (ML, data engineering, mobile)

Links

• Shorthand Guide (Start Here): The Shorthand Guide to ECC
• Longform Guide (Advanced): The Longform Guide to ECC
• Security Guide: Security Guide | Thread
• Follow: @affaan

License

MIT. Use it freely, adapt it to your workflow, and contribute back when you can.

Star this repo if it helps. Read the guides. Build something great.