ECC 2.0 平滑升级指南：从 everything-claude-code 1.x 迁移到 ecc@ecc

本指南针对已经从 ECC 1.x（旧仓库名 everything-claude-code）安装过插件、随后仓库与插件标识更名为 2.0 的用户，给出从安装新插件、卸载旧插件、清理残留目录，到跨 Claude Code / Codex / OpenCode / Cursor 等多 harness 重新安装的完整升级路径。读完本文，你将能够判断当前环境属于哪种安装方式、用最短命令完成 1.x → 2.0 切换，并避免“双插件重复执行”“残留目录占用磁盘”“插件与脚本安装叠加”这三类最常见的升级事故。全文依据仓库根目录的 README.md 与官方迁移文档 docs/MIGRATION-1X-TO-2.0.md 整理，关键命令均可直接复制运行。

为什么 2.0 必须经历一次迁移

ECC 2.0 对外的三组公开标识发生了整体切换，官方在 README 的 “Naming + Migration Note” 一节中明确说明，这三组标识不可互换：

标识维度	1.x	2.0
源码仓库	everything-claude-code	ECC
Claude 插件（marketplace/plugin 标识）	everything-claude-code@everything-claude-code	ecc@ecc
npm 包	——（旧手动安装脚本）	ecc-universal

这种短化是有意为之：Anthropic marketplace / plugin 安装以“规范插件标识（canonical plugin identifier）”为准，ecc@ecc 可以让工具名和斜杠命令命名空间足够短，从而通过严格的 Desktop/API 校验器。因此，旧帖子或旧教程中出现的超长 marketplace 标识只能视为“历史别名”，而不是可继续安装的目标。迁移文档正文见 docs/MIGRATION-1X-TO-2.0.md，命名与迁移说明见 README.md 的 Naming + Migration Note 章节。

需要注意：仓库名、插件标识变了，但 npm 包名特意保持在 ecc-universal（见 package.json 中 "name": "ecc-universal"），npm 安装路径与 marketplace 安装路径使用的是两套不同的名字，升级时不要混淆。

升级前：先确认你的 1.x 安装形态

在动手之前，先判断自己属于哪一类安装者，这决定后续清理范围：

• Claude Code 插件方式：通过 /plugin 安装的 everything-claude-code@everything-claude-code，插件缓存在 ~/.claude/plugins/ 下，可能还带手工拷贝到 ~/.claude/ 的 skills/、commands/、agents/ 表面文件。
• 脚本/克隆方式：曾在主目录克隆过 1.x 仓库（一个 everything-claude-code/ 目录），或运行过旧版安装脚本把规则、技能拷贝进各 harness 目录。
• 两种叠加：既装了插件又跑了脚本，这是最容易出问题的情况，需要按下文“只保留一种安装路径”的恢复顺序处理。

ECC 本身是一个 harness 层（skills / commands / agents / hooks 的集合），它不会修改项目代码与 git 历史，所以升级不影响你现有仓库里由 ECC 产生的任何 commit、文件与 PR。唯一可见的变化是：下一个会话将加载 2.0 的 surface，斜杠命令命名空间从 everything-claude-code:* 变为 ecc:*。

快速升级：三条命令完成主流程

迁移文档给出 TL;DR 版本，按顺序执行即可完成新旧插件的替换：

# 1. 安装 2.0
/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

# 2. 移除旧插件
/plugin uninstall everything-claude-code@everything-claude-code

随后再清理残留目录（见下文清单），并重启会话，让 Claude Code 重新加载插件列表。两条 install 命令是幂等的，重复执行不会产生副作用。

如果你更习惯直接改配置文件，README 也给出了与上述两条 /plugin 命令等效的 JSON 配置方式：在 Claude Code 的设置 JSON 中声明 marketplace 来源，并设置 enabledPlugins 为 {"ecc@ecc": true}，即可得到相同结果（详见 README.md 的插件配置章节）。这种方式适合需要把插件配置纳入版本管理的团队。

升级后“看到两个 ECC 插件”是预期现象

迁移文档特别强调：ecc@ecc 与 everything-claude-code@everything-claude-code 在 Claude Code 眼里是两个互不相关的插件，因此在旧插件尚未卸载前，/plugin 列表里同时出现两条 ECC 是正常的。

此时应立即卸载旧插件、只保留 ecc@ecc。因为同时运行两个插件会导致以下三重重复：

1. skills 重复：同一技能被加载两份；
2. commands 重复：斜杠命令空间出现 ecc:* 与 everything-claude-code:* 两份同名命令；
3. hooks 重复执行：同一个 hook 事件被触发两次，可能造成会话开销翻倍甚至行为叠加。

判定标准：/plugin 列表不再出现旧标识后，才算清理完成。

卸载 1.x 后：可删与禁删清单

/plugin uninstall 只会把旧插件从“激活列表”移除，但通常会在 Claude 插件缓存中留下旧目录，主目录中手工拷贝的副本也不会被自动清除。迁移文档给出了明确的清理边界：

旧插件不再出现在 /plugin 列表后，可以安全删除：

• Claude 插件目录下的旧插件文件夹，例如 ~/.claude/plugins/...everything-claude-code...；
• 主目录中的 1.x 手动安装目录（克隆的 everything-claude-code/ 目录）——前提是你没有把它当作工作检出（working checkout）继续使用；
• 从 1.x 手工拷贝到 ~/.claude/ 下的旧表面文件：skills/、commands/、agents/ 中来自 1.x 的条目——2.0 插件会提供当前版本，无需保留旧副本。

明确不要删除：

• ~/.claude/rules/ 中你有意手动拷贝的内容；
• 个人记忆 / 状态类文件（memory、session state 等）。

这条边界的底层逻辑与 ECC 2.0 的状态追踪机制一致：卸载程序只删除记录在 install-state 中的、它能证明归属的文件，绝不认领 harness 目录里与它无关的文件。需要系统性排查时，可从源码检出运行 node scripts/ecc.js list-installed 查看管理清单，再用 doctor / repair 检查与修复（详见 README.md 的 Reset / Uninstall ECC 章节）。

移除 1.x 会影响现有项目吗

不会。文档对此有明确结论：ECC 是一个 harness 层，只向 agent 环境注入 skills、commands、agents、hooks，不触碰你的项目代码与 git 历史。你在仓库中通过 ECC 产生的所有产出（commits、文件、PR）原封不动。切换之后，下一次会话加载的就是 2.0 的 surface，而不是 1.x 的；对命令层面的可感知变化是斜杠命令命名空间从 everything-claude-code:* 统一变为 ecc:*。

也就是说：迁移是一个“环境层替换”，不是“数据迁移”，不存在项目被改写或历史被回滚的风险。

只保留一种安装路径，不要叠加

这是升级中最重要的纪律：不要在插件安装之上再叠加手动安装器。所谓“手动安装器”包括仓库根目录的 install.sh / install.ps1，以及 npx ecc-universal install --profile full 这类 universal 包命令。叠加的后果与“双插件”类似：skills 重复、hooks 重复执行。

从源码看，install.sh 本身是“旧版 shell 入口”，它只负责解析真实的仓库/包根目录（兼容 npm bin 软链接场景），最终仍委托给 Node 安装器运行时 scripts/install-apply.js 执行。也就是说，脚本安装与 ecc-universal 安装最终落在同一套 Node 安装管线（scripts/install-plan.js 规划 + scripts/install-apply.js 落地），叠加安装就等于对同一套状态重复写入。

如果不小心已经叠加，按以下顺序清理（来自 README 的官方恢复流程）：

1. 先移除 Claude Code 的插件安装；
2. 在包含管理 install-state 的项目目录下运行 ECC 的 uninstall 命令；
3. 删除你手工拷贝且不再需要的额外规则目录；
4. 只选一种路径重新安装一次。

完整命令族如下，建议先 --dry-run 预览再真正执行：

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

如果是从源码检出安装，改用等价的 Node 入口（同样从安装时所在的项目目录执行）：

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/ecc.js uninstall

另外，README 中特别提醒：不要使用 npx ecc-install --profile minimal --target claude 这类写法——ecc-install 只是 ecc-universal 包内部的二进制别名（package.json 的 bin 字段将其映射到 scripts/install-apply.js），并不是独立发布的 npm 包，直接 npx 会失败。

在 Claude Code 之外使用 2.0：跨 harness 安装

ECC 2.0 是跨 harness 的，迁移指南给出了面向其他 agent 的安装形态。使用 universal 安装器时，通过 --target 指定目标 harness、--profile 选择安装内容档位：

npx ecc-universal install --profile core --target codex      # Codex CLI
npx ecc-universal install --profile core --target opencode   # OpenCode
npx ecc-universal install --profile core --target cursor     # Cursor

安装前可以先运行 consult 子命令“预览匹配度”，它只做评估、不写文件：

npx ecc-universal consult "<what you need>" --target <harness>

--profile 的可选值并非随手写的，而是由 manifest 驱动：仓库的 manifests/install-profiles.json 中定义了 minimal、opencode、core、developer、security、research、full 等档位。以本文使用的 core 为例，其定义为“最小化 harness 基线”，包含 rules-core、agents-core、commands-core、hooks-runtime、platform-configs、workflow-quality 六个模块；而 full 则是“完整安装所有当前已分类模块”，包括 26 个模块（覆盖框架语言、数据库、安全、研究 API、媒体生成、编排等）。这也是文档警告不要把 --profile full 与插件安装叠加的原因之一——full 会写入大量表面文件。

这些命令要求 ecc-universal 2.2.0 或更新版本、Node.js 18+。仓库 package.json 中 engines.node 声明为 >=18，与官方要求一致。

各 harness 有对应的深度适配指南（均在 docs 目录下）：ANTIGRAVITY-GUIDE.md、HERMES-SETUP.md、QWEN-GUIDE.md、JOYCODE-GUIDE.md。以 Codex 为例，较新的 Codex 发行版已支持原生 repo-marketplace 插件：codex plugin marketplace add + codex plugin add ecc@ecc，再从 ECC 检出执行 node scripts/codex/check-plugin-cache.js 验证缓存内容是否真的可加载（详见 plugins/ecc/README.md 的说明与 README.md 的 Codex 小节）。注意这些能力因 harness 版本而异，请以你所用 CLI 版本的实际支持情况为准。

升级后的健康检查与验证

完成切换、清理残留并重启会话后，可用以下方式确认环境处于“单一、干净”状态：

1. 在 Claude Code 中执行 /plugin，确认只剩 ecc@ecc；
2. 尝试一次斜杠命令（如 ecc:* 命名空间下的任一命令），确认命令前缀已切换；
3. 运行 npx ecc-universal doctor 检查已管理文件与 install-state 是否存在漂移，必要时 repair；
4. 若在多个 harness 之间切换，分别对每个目标执行一次 consult + install --dry-run，确认不会重复写入同一套规则目录。

若升级后 Claude 本地配置被重置或误删，也无需重新走完整安装：README 的建议是先 node scripts/ecc.js list-installed 查看状态，再 doctor 与 repair，多数情况下即可恢复 ECC 管理的文件，而无需重建整套配置。

小结

ECC 1.x → 2.0 的迁移本质是一场“标识切换 + 安装路径归一”：仓库、插件标识与 npm 包名三组身份各司其职，Claude Code 用户只需“装新卸旧 + 清残留”，跨 harness 用户则改用 npx ecc-universal install --profile core --target <harness> 的 manifest 驱动安装。坚持“单一安装路径”原则，善用 doctor、repair、uninstall --dry-run 等可回滚的检查手段，就能在不影响任何既有项目产出的前提下，平稳过渡到 2.0。