ECC for CodeBuddy：基于统一 Target Adapter 架构的完整安装与生命周期管理指南

ECC（Everything Claude Code）将命令、Agent、技能与规则体系打包为可安装的 Agent 工作流资产。本文聚焦仓库中的 CodeBuddy 安装说明文档，系统讲解如何通过统一安装系统（--target codebuddy）把 ECC 工作流装入 CodeBuddy IDE 项目，并深入结合仓库源码剖析安装计划生成、Rules 扁平化、安装状态追踪与卸载安全校验的实现细节。读完后，你可以独立完成安装、健康检查、修复、卸载的全流程操作，并理解 Target Adapter 架构在跨平台 Agent 工具适配中的设计思路。

一、ECC for CodeBuddy 是什么

CodeBuddy 是 ECC 统一 Target Adapter 架构所支持的安装目标之一。该架构的核心思想是：将仓库根目录下的 commands/、agents/、skills/、rules/ 四类资产，按照不同宿主工具（Claude Code、Cursor、Codex、CodeBuddy、Qwen、Zed 等）的目录约定，投影到对应的 .codebuddy/ 目录中。

从源码结构看，install-apply.js 的帮助文本列出了全部 14 个安装目标，其中 codebuddy 的定位是：

codebuddy - Install commands, agents, skills, and flattened rules into ./.codebuddy/

即向项目内 .codebuddy/ 目录安装命令、Agent、技能以及扁平化后的规则文件。注册表 registry.js 中挂载了专门的适配器 codebuddy-project，其核心配置定义在 codebuddy-project.js：

module.exports = createInstallTargetAdapter({
  id: 'codebuddy-project',
  target: 'codebuddy',
  kind: 'project',                        // 项目级安装（非用户主目录级）
  rootSegments: ['.codebuddy'],           // 安装根目录
  installStatePathSegments: ['ecc-install-state.json'], // 安装状态文件
  nativeRootRelativePath: '.codebuddy',
  // ...
});

几个关键字段决定了后续行为：

• kind: 'project'：安装根目录锚定在当前项目（process.cwd()），而非用户主目录；
• rootSegments: ['.codebuddy']：所有受管文件都落在项目内的 .codebuddy/ 下；
• installStatePathSegments：状态文件 ecc-install-state.json 记录本次安装的完整清单，是 doctor/repair/uninstall 三大生命周期命令的数据基础。

二、推荐安装方式：统一安装系统

README 推荐的方式是走统一安装系统，因为它提供完整的生命周期管理（安装、体检、修复、卸载全链路可追踪）：

# 使用 developer 档案安装
node scripts/install-apply.js --target codebuddy --profile developer

# 使用 full 档案安装（全部模块）
node scripts/install-apply.js --target codebuddy --profile full

# Dry-run 预览变更而不实际写盘
node scripts/install-apply.js --target codebuddy --profile full --dry-run

安装计划的工作机制

执行上述命令时，install-apply.js 的主流程分为三步：

1. parseInstallArgs 解析命令行参数（--target、--profile、--modules、--skills、--with、--without、--dry-run、--json 等）；
2. createInstallPlanFromRequest 结合 manifests/install-profiles.json 等清单，把 profile 解析为一组模块，再由对应适配器生成逐文件的安装操作（operations）；
3. --dry-run 时调用 previewInstallPlan 仅输出计划；否则 applyInstallPlan 落盘并写入 ecc-install-state.json。

人类可读的计划输出包含 Mode、Target、Adapter、Install root、Install-state 路径、选中/跳过的模块清单，以及每一条 source -> destination 的文件操作，便于安装前审计将写入哪些文件。

常用参数说明

结合 install-apply.js 的 Usage 文本，与 codebuddy 目标相关的核心参数如下：

参数	说明
--target codebuddy	指定安装目标为 CodeBuddy 项目目录
--profile <name>	解析并安装清单中定义的档案（如 developer、full）
--modules <id,id,...>	跳过 profile，直接指定模块 ID 安装
--with <component> / --without <component>	包含/排除特定用户可见组件
--skills <skill-id,...>	仅安装指定技能目录（如 continuous-learning-v2）
--dry-run	只输出安装计划，不复制任何文件
--json	输出机器可读的 JSON 计划/结果

profile 与模块的清单数据位于 manifests/install-profiles.json 与 manifests/install-modules.json，安装组件清单见 manifests/install-components.json。

三、Rules 扁平化：CodeBuddy 适配的核心差异

README 指出：「Rules are flattened into namespaced files (e.g., common-coding-style.md) for CodeBuddy compatibility.」这条约定在源码中有明确实现。

codebuddy-project.js 的 planOperations 对模块路径做了特殊处理：当路径是 rules 时，不走普通的 createScaffoldOperation（保留相对目录结构），而是调用 createFlatRuleOperations 生成分层策略为 flatten-copy 的操作。

扁平化算法位于 helpers.js：

// 源路径 rules/common/coding-style.md
// 目标路径 .codebuddy/rules/common-coding-style.md
const flattenedFileName = `${namespace}-${normalizeRelativePath(relativeFile).replace(/\//g, '-')}`;
operations.push(createManagedOperation({
  moduleId,
  sourceRelativePath: sourceRelativeFile,
  destinationPath: path.join(destinationDir, flattenedFileName),
  strategy: 'flatten-copy',
}));

即取规则所在的子目录名作为命名空间前缀（common、python、react 等），目录内相对路径中的 / 替换为 -，最终所有规则平铺到 .codebuddy/rules/ 单目录下。例如仓库中的 rules/common/coding-style.md 会安装为 .codebuddy/rules/common-coding-style.md。这样做是为了适配 CodeBuddy 对规则文件的读取约定，同时通过命名空间前缀避免不同语言/框架规则之间的文件名冲突。

适配器在生成操作前还有一个「外来平台路径」过滤：isForeignPlatformPath 依据 PLATFORM_SOURCE_PATH_OWNERS 映射（.claude-plugin → claude、.codex → codex、.cursor → cursor……）判断某条源路径是否归属于其他宿主平台，若源路径属于别的平台则直接跳过，防止把 Claude 或 Cursor 专属内容误装进 CodeBuddy 目录。

四、生命周期管理：doctor、repair、uninstall

统一安装系统以 ecc-install-state.json 为锚点，提供三个管理命令（均支持 --target codebuddy 与 --json 输出）：

# 检查安装健康状态，检测文件漂移
node scripts/doctor.js --target codebuddy

# 重建 install-state 中记录的受损文件
node scripts/repair.js --target codebuddy

# 干净卸载（仅移除 ECC 追踪的文件）
node scripts/uninstall.js --target codebuddy

doctor：漂移诊断

doctor.js 调用 buildDoctorReport，以当前项目（projectRoot: process.cwd()）和主目录为上下文，检索对应的 ecc-install-state.json，逐条核对受管文件是否仍然存在于磁盘。输出包含每个适配器的 Status（OK/WARNING/ERROR）、状态文件路径与问题列表（severity + code + message），并在存在告警时以退出码 1 结束——这意味着它可以被 CI 或 hook 用作安装完整性门禁。

repair：按状态清单自动修复

repair.js 调用 repairInstalledStates，从 install-state 中读取清单，重新把缺失的受管文件从仓库源路径复制回目标位置。支持 --dry-run 先预览将修复的路径（plannedRepairs），确认后执行则输出 repairedPaths 统计。修复完成后还会通过 reconcileCanonicalInstallStates 同步规范化的安装状态，保证状态文件与实际磁盘一致。

卸载：只删 ECC 管的东西

scripts/uninstall.js 基于 install-state 精确卸载：只删除清单中记录的文件，用户自行添加的文件不受影响。这一「安全卸载」承诺是统一安装相对旧版脚本的核心优势。

五、Legacy 安装脚本：manifest 机制与安全防护

在统一安装系统之外，.codebuddy/ 目录保留了 legacy 安装入口，适合快速搭建：

# 安装到当前项目
cd /path/to/your/project
.codebuddy/install.sh

# 全局安装（安装到 ~/.codebuddy/）
.codebuddy/install.sh ~

其 Node 实现是 install.js。几个值得注意的实现细节：

• 目标解析：参数解析逻辑 支持 ~（映射到 USERPROFILE/HOME）与任意项目路径；若传入路径本身就叫 .codebuddy 则直接作为安装根，否则在其下新建 .codebuddy/；
• 幂等且不覆盖：copyManagedFile 在目标文件已存在时直接跳过（无论是否受管），因此重复执行 install.js 不会破坏你对已安装命令/规则的本地修改；
• manifest 追踪：每复制一个文件，就在 .codebuddy/.ecc-manifest 中追加一行相对路径（如 commands/plan.md），供卸载时精确识别受管文件；
• 安装范围：commands 与 agents 仅复制顶层 .md（doInstall 中校验 basename(dirname) === 'commands'），而 skills 与 rules 递归复制完整子目录结构，并保留相对路径；
• 跳过脚本自复制：README 复制段落 刻意跳过 install.sh/uninstall.sh 的复制，避免拷贝出的脚本在目标目录运行时路径引用失效。

对应的 .codebuddy/uninstall.js 在安全性上做了双重防护：

1. 条目级校验：isValidManifestEntry 拒绝空条目、绝对路径、~ 开头以及任何包含 .. 的条目；
2. 路径逃逸二次拦截：删除循环 用 path.relative(codebuddyRootResolved, path.resolve(fullPath)) 验证最终路径必须仍位于 .codebuddy/ 根内（relative.startsWith('..') 或绝对路径则跳过并打印 Skipped: ... (outside target directory)）。

此外，目录条目只有在为空时才被删除（含用户文件的目录会打印 Skipped: ... (not empty - contains user files)），删除前还会交互式确认（y/N）。若 .ecc-manifest 缺失，脚本会提示可能源于旧版本安装或手动删除，并在用户确认后才整体移除 .codebuddy/ 目录。

六、安装产物结构

一次完整安装后，项目内 .codebuddy/ 目录的形态如下（对应 README 的 Project Structure 一节）：

.codebuddy/
├── commands/              # 命令文件（复用于项目根 commands/）
├── agents/                # Agent 文件（复用于项目根 agents/）
├── skills/                # 技能文件（复用于项目 skills/）
├── rules/                 # 扁平化后的规则（如 common-coding-style.md）
├── ecc-install-state.json # 统一安装的状态追踪文件
├── install.sh             # Legacy 安装脚本
├── uninstall.sh           # Legacy 卸载脚本
└── README.md              # 安装说明

• Commands 是聊天 / 菜单中可调用的按需工作流，全部复用自仓库根 commands/ 目录（如 plan.md、code-review.md）；
• Agents 是带特定工具配置的专业助手，复用自根 agents/ 目录；
• Skills 同样是 / 菜单中的按需工作流，复用自 skills/ 目录并保留子目录结构；
• Rules 是常驻生效的规则上下文，如 rules/common/coding-style.md 会被扁平化为 common-coding-style.md。

README 总结的 Target Adapter 安装收益可以归纳为五点：基于 install-state 的安全卸载、doctor 漂移检测、repair 自动修复、profile 驱动的选择性安装，以及跨 Windows/macOS/Linux 的 Node.js 实现。

七、推荐工作流与注意事项

README 给出的日常开发工作流为：

1. 先规划：用 /plan 拆解复杂功能（对应 commands/plan.md）；
2. 测试先行：实现前先调用 /tdd 编写测试；
3. 代码评审：写完代码后用 /code-review 检查（对应 commands/code-review.md）；
4. 安全复查：涉及认证、API 端点或敏感数据处理时再次运行 /code-review；
5. 构建修复：出现构建错误时使用 /build-fix。

需要说明的是：从当前仓库 commands/ 目录的文件清单看，plan 与 code-review 均有对应命令文件，而 README 中提到的 /tdd 与 /build-fix 在当前版本中未找到同名命令文件，实际可用命令以安装后 CodeBuddy 中 / 菜单展示的列表为准。

最后给出几条实操注意事项：

• 安装位置由 kind 决定：codebuddy 适配器是 project 级目标，必须在目标项目根目录下执行安装命令，产物落在该项目的 .codebuddy/ 中，不要误装到仓库外路径；
• 先 dry-run 再落盘：--dry-run 会完整打印 source -> destination 操作列表，建议在生产项目中安装前先预览；
• doctor 的退出码语义：存在 warning 或 error 时 doctor 以退出码 1 结束，脚本化使用时可据此做门禁；
• 两套安装体系不要混用：统一安装（install-apply.js + ecc-install-state.json）与 legacy 脚本（install.js + .ecc-manifest）各自维护独立的追踪清单，卸载时请使用与安装方式对应的 uninstall 入口，避免状态不一致。

八、小结

CodeBuddy 目标是 ECC 统一 Target Adapter 架构的一个标准成员：通过 codebuddy-project 适配器 把仓库的 commands/agents/skills 原样投影、把 rules 按「命名空间-文件名」扁平化，再以 ecc-install-state.json 串联起 install / doctor / repair / uninstall 全生命周期。对使用者而言，掌握 install-apply.js --target codebuddy 的 profile 选择与 --dry-run 预览、配合 doctor/repair 做健康运维，即可在任何 CodeBuddy 项目中稳定获得 ECC 的完整工作流能力。