oh-my-claudecode 贡献实战指南：本地构建 OMC 插件、三种插件挂载流程与 PR 工作流

本文基于仓库根目录的 CONTRIBUTING.md 展开，系统讲解如何为 oh-my-claudecode（OMC）这个面向 Claude Code 的多智能体编排系统做贡献：从环境准备、Fork/Clone、完整构建链路，到将本地 checkout 挂载为 Claude Code 插件的三种方式（--plugin-dir、Marketplace、--no-plugin 兜底），再到测试、rebase 与 PR 提交的全过程。读完并照做后，你可以在本地完成 OMC 的"修改代码 → 重建 → 立即在 Claude Code 会话中验证"的完整开发闭环。

1. 读者对象与前置要求

贡献 OMC 之前，需要满足以下环境条件（依据 CONTRIBUTING.md 第 1 节）：

• Node.js ≥ 20（必需，用 node --version 检查）。从 package.json 的 engines 字段可以看到官方支持的运行范围为 20.x || 22.x || 23.x || 24.x || 25.x || 26.x；
• npm（随 Node.js 自带）；
• git（版本控制）；
• Claude Code 已安装（用于在会话中测试 skills 和命令）；
• 对 TypeScript、ESBuild 和 git 工作流有基本了解。

该指南假设你熟悉终端命令和 git 分支操作。从 package.json 的依赖清单也能印证技术栈：TypeScript 5.7、esbuild 0.27、vitest 4、eslint 9、prettier 3、commander 12 等，均属于当前主流版本。

2. Fork 与 Clone：理解双分支模型

贡献的标准起点是 Fork + Clone + 添加上游 remote：

1. 在 GitHub 上 Fork 项目（点击仓库页的 "Fork" 按钮）；
2. 克隆你的 Fork：

git clone <你的 Fork 仓库地址>
cd oh-my-claudecode

3. 添加 upstream remote，以便随时同步主仓库：

git remote add upstream <主仓库地址>

4. 验证 remote 配置：

git remote -v
# origin    <你的 Fork 地址> (fetch)
# origin    <你的 Fork 地址> (push)
# upstream  <主仓库地址> (fetch)
# upstream  <主仓库地址> (read-only)

5. 查看可用分支：

git branch -r
# origin/HEAD -> origin/main
# origin/main
# upstream/dev
# upstream/main

仓库有两个核心分支，这一点直接影响你后续 PR 的目标分支选择：

• upstream/dev — 开发分支，功能开发工作的默认目标；
• upstream/main — 发布分支，稳定、可生产使用。

3. 安装依赖与完整构建链路

3.1 安装依赖

npm install

3.2 构建链路解析（以当前 package.json 为准）

CONTRIBUTING.md 第 3 节给出了一条简化的构建链描述，而当前 package.json 中 build 脚本的实际内容比文档更完整，包含前置的 entitlement 校验与 prompt 投影生成步骤：

npm run build

当前仓库实际的 build 脚本执行序列为（引自 package.json 第 50 行）：

1. node scripts/generate-skill-entitlements.mjs --verify — 校验 skill 授权清单一致性；
2. tsc — TypeScript 编译到 JavaScript；
3. node scripts/build-workflow-stage-prompts.mjs — 生成工作流 stage prompt；
4. node scripts/build-skill-bridge.mjs — 将 skills 打包供插件系统使用；
5. node scripts/build-mcp-server.mjs — 构建 MCP 服务器（Claude Code 集成的桥梁）；
6. node scripts/build-bridge-entry.mjs — 构建插件入口点（即 bridge/ 下的 CJS bundle）；
7. npm run compose-docs — 从 partials 组装文档；
8. npm run generate:prompt-projections — 生成 prompt 投影产物；
9. npm run build:claude-md-coordinator — 构建 CLAUDE.md 协调器；
10. npm run build:runtime-cli — 打包 CLI 运行时（bridge/runtime-cli.cjs）；
11. npm run build:team-server — 构建 team server；
12. npm run build:cli — 打包 CLI 入口（bridge/cli.cjs）。

CONTRIBUTING.md 中列出的 build-skill-bridge、build-mcp-server、build-bridge-entry、compose-docs、build:runtime-cli、build:team-server、build:cli 等步骤均能在 package.json 的 scripts 字段中找到一一对应的独立脚本，说明文档描述的是主干链路，而实际 npm run build 会在其前后追加校验与生成步骤。

构建产物输出到 dist/（TypeScript 编译结果与 npm 包入口）和 bridge/（CJS 打包产物，供 Claude Code 以 require 方式直接加载）。npm 包的 bin 映射也印证了这一点：omc 命令指向 bin/oh-my-claudecode.js，omc-cli 直接指向 bridge/cli.cjs；而 files 字段则声明了发布时随包分发的 bridge/ 各 CJS 文件、agents/、skills/、commands/、hooks/、templates/ 等目录。

4. 将本地 checkout 挂载为 OMC 插件：三种流程

构建完成后，需要让 Claude Code 使用你的本地代码。CONTRIBUTING.md 第 4 节给出三种挂载流程（Flow A/B/C），下面逐一说明并结合源码解释其底层机制。

4.0 Bootstrap：先让 omc 命令可用

三种流程都依赖 omc CLI。如果尚未全局安装（npm i -g oh-my-claude-sisyphus，注意 npm 包名是 oh-my-claude-sisyphus，见 package.json 的 name 字段），可以直接为 checkout 创建符号链接：

# 创建 ~/.local/bin（如不存在）
mkdir -p ~/.local/bin

# 将 omc 符号链接到 checkout 的 bridge 入口
ln -sf "$PWD/bridge/cli.cjs" ~/.local/bin/omc

# 验证（可能需将 ~/.local/bin 加入 PATH）
omc --version

这里链接的 bridge/cli.cjs 正是第 3 节中 build:cli 的打包产物，它是一个自包含的 CJS bundle（内部打包了 commander 等依赖），因此无需 node_modules 在位即可独立运行。

4.1 Flow A（推荐）：omc --plugin-dir + omc setup --plugin-dir-mode

优势：单条命令、自动处理环境变量、与 OMC 的设计哲学一致，摩擦最小。

# 在你的 checkout 目录下执行
omc --plugin-dir "$PWD" setup --plugin-dir-mode

之后正常启动 Claude Code，它就会使用你的本地 checkout。

源码层面的机制：从源码结构看，omc --plugin-dir <path> 并不是把参数透传给 Claude Code 就结束，而是在启动前完成两件事：

1. src/cli/index.ts 中的 applyPluginDirOption()（第 80–98 行）把 --plugin-dir 解析为绝对路径，与已存在的 OMC_PLUGIN_ROOT 冲突时给出警告，然后写入 process.env[OMC_PLUGIN_ROOT]；
2. src/cli/launch.ts 的启动参数扫描逻辑（第 1120–1125 行）捕获 --plugin-dir <path> / --plugin-dir=<path> 两种写法，将值写入 OMC_PLUGIN_ROOT 环境变量，使得 HUD wrapper 等 Claude Code 子进程也能解析当前插件根目录。

环境变量名本身定义在 src/lib/env-vars.ts（第 2 行：OMC_PLUGIN_ROOT_ENV = "OMC_PLUGIN_ROOT"）。

omc setup 子命令的 --plugin-dir-mode 选项在 src/cli/index.ts 第 1298 行注册，其官方描述是"Treat OMC as launched via --plugin-dir at runtime（跳过 agent/skill 拷贝；HUD + hooks + CLAUDE.md 照常安装）"。更值得注意的是第 1327–1333 行的自动检测逻辑：即使不显式传 --plugin-dir-mode，只要 OMC_PLUGIN_ROOT 已设置（即由 omc --plugin-dir 启动），setup 会自动进入 dev plugin-dir 模式并打印提示。第 1334–1339 行还明确了优先级：--no-plugin 与 --plugin-dir-mode 冲突时，--no-plugin 生效。

setup 命令完整支持的选项（第 1293–1300 行）：

选项	作用
-f, --force	即使已最新也强制重装
-q, --quiet	除错误外静默输出
--no-plugin	从当前包安装内置 skills，而非依赖插件提供的 skills
--plugin-dir-mode	按 --plugin-dir 运行时模式处理，跳过 agent/skill 拷贝
--skip-hooks	跳过 hooks 安装
--force-hooks	即使未变化也强制重装 hooks

解决 .mcp.json 的服务器命名冲突：仓库自带 .mcp.json，其中注册了一个名为 "t" 的 MCP 服务器（指向 ${CLAUDE_PLUGIN_ROOT}/bridge/mcp-server.cjs）。使用 --plugin-dir 时，插件自身也会注册一个同名 "t" 服务器，造成命名冲突。解决办法是在 ~/.claude/settings.json（或 $CLAUDE_CONFIG_DIR/settings.json）中加入：

{
  "disabledMcpjsonServers": ["t"]
}

这会告诉 Claude Code 忽略仓库 .mcp.json 里的条目，改用插件注册的版本。

在 Claude Code 内验证：

/autopilot "your task here"

重建流程：代码改动后：

npm run build
omc setup --plugin-dir-mode  # 或者直接重新 build 后重启 Claude Code

4.2 Flow B：Marketplace 生命周期（偏好插件系统隔离时）

优势：使用 Claude Code 原生插件系统，遵循 marketplace 语义。

# 把本地目录添加为 marketplace 源
claude plugin marketplace add /path/to/oh-my-claudecode

# 安装插件
claude plugin install oh-my-claudecode@oh-my-claudecode

# 运行 setup
/setup

代码改动后的重建：

npm run build
claude plugin marketplace update oh-my-claudecode
claude plugin update oh-my-claudecode@oh-my-claudecode
/setup

本地 marketplace 的元数据位于 .claude-plugin/ 目录（含 marketplace.json 与 plugin.json），这是该流程能够识别本地 checkout 为合法插件源的前提。

4.3 Flow C：omc setup --no-plugin（兜底，内置 skills）

优势：完全绕过插件系统，把本地内置的 agents/skills 直接复制到 ~/.claude/skills/ 等目录，适合排障。

omc --plugin-dir "$PWD" setup --no-plugin

从源码看，--no-plugin 是 commander 的否定式标志：src/cli/index.ts 第 1320–1322 行将其解析为 options.plugin === false，再以 noPlugin: true 显式传给 installer，由安装器走"直拷内置 skills"的路径。

4.4 三种流程对比表

Flow	命令	使用插件系统？	文件位置	重建成本	适用场景
A（推荐）	omc --plugin-dir "$PWD" setup --plugin-dir-mode	是，经 --plugin-dir	实时来自 checkout	低（重建不需拷贝）	开发 OMC 本身
B	claude plugin marketplace add + install	是，完整 marketplace	插件缓存	中（需 marketplace update）	测试插件隔离性
C	omc setup --no-plugin	否	~/.claude/skills/	低（直接拷贝）	兜底 / 排障

5. 社区推荐的 Shell 别名（非强制）

把以下内容加入 .bashrc / .zshrc，可显著改善开发工作流（路径按实际调整）：

# 你的 OMC 开发根目录
export OMC_DEV_ROOT="$HOME/_Git/_Claude/oh-my-claudecode"

# 从本地 checkout 运行 OMC
alias omcdev='omc --plugin-dir "$OMC_DEV_ROOT"'

# 快速构建
alias omcbuild='(cd "$OMC_DEV_ROOT" && npm run build)'

# 运行测试
alias omctest='(cd "$OMC_DEV_ROOT" && npm run test:run)'

# 完整 watch 模式（tsc + esbuild）
alias omcwatch='(cd "$OMC_DEV_ROOT" && npm run dev:full)'

之后即可：

omcbuild                                # 重建，约 10–15 秒
omcdev setup --plugin-dir-mode          # 挂载你的 checkout
omcwatch                                # 文件变更时自动重建
omctest                                 # 运行测试套件

dev:full 对应 package.json 第 62 行的脚本：用 concurrently 并行拉起 7 个 watch 进程（tsc --watch 加上 cli、mcp、bridge-entry、skill-bridge、runtime、team 六个 esbuild bundle 的 --watch），因此改任意一类产物都会在保存后自动重打包。

6. 代码改动后的重建策略

6.1 仅改动 TypeScript

只编辑了 src/ 下的 .ts 文件（未动 agent/skill markdown）时，二选一：

# 选项 A：仅 tsc 快速反馈（不重打包）
npm run dev

# 选项 B：完整 bundle watch — tsc + esbuild 全部进入 watch 模式（推荐）
npm run dev:full

二选一，不要同时跑。 npm run dev（即 tsc --watch）类型检查反馈更快，但不会重建 dist/ 与 bridge/ 下的 bundle；npm run dev:full 则每次变更都重建全部产物，适合需要端到端测试 CLI 的场景。

6.2 Agent、Skill 或 Command 改动

编辑 agents/、skills/、commands/ 下的 markdown 后：

npm run build
omc setup --plugin-dir-mode

setup 命令会重新读取 markdown 文件并刷新会话内命令注册表。

6.3 完整构建（推荐）

npm run build

执行完整流水线：tsc → esbuild bundles → 文档组装 → 全部 bridge 产物。

6.4 生成的 dist/ 与 bridge/ 变更不应提交

npm run build 会重新生成 dist/ 和 bridge/。普通 PR 中不要提交这些构建产物：虽然多数产物被 gitignore，但被追踪的 bridge/*.cjs bundle 在重建后可能出现 diff。提交它们会膨胀 diff、制造合并冲突，并掩盖真正的源码改动。提交前恢复它们：

git restore dist/ bridge/

仓库还配有一个 No Committed Build Artifacts 的 PR 检查作业作为兜底：它是无凭据的候选端分类器，可以被 PR 分支替换、对所有贡献者和维护者均非权威，会以任何候选 dist/ 或 bridge/ 的变更给出 OWNER_CONFIRMATION_REQUIRED 的 hold 状态；它不能批准生成式变更、也不能授权合并。被 hold 的生成式 diff 需要 owners 提供受保护的分根（split-root）授权（workflow root W 为默认 main 上经过评审的 workflow 提交，verifier/manifest root B 为 detached 受保护 dev 的 event-base 提交），且受保护证据必须绑定最终 PR head H、其唯一 merge base 以及完整的生成 diff 记录，并在 B 存在后的新合格事件中评估；合并前，目标分支治理需将该普通候选检查移出必选项或替换为受保护 split-root 检查。简言之：贡献者侧只需记住"永远不要带着 dist//bridge/ 的 diff 提交 PR"。

7. 测试与 Lint

提交 PR 前，以下命令必须全部通过（GitHub CI 也会执行同样的校验）：

# 交互式 watch 模式
npm test

# 运行一次并退出
npm run test:run

# 生成覆盖率报告
npm run test:coverage

# Lint
npm run lint

# 格式化
npm run format

从 package.json 看，test / test:run / test:coverage 底层都是 vitest，且统一排除 tests/perf/** 下的性能测试；lint 使用 eslint 扫描 src；format 使用 prettier 处理 src/**/*.ts。仓库中 src/__tests__/ 下有数百个单元测试文件（覆盖 installer、hooks、team、HUD、CLI 等模块），tests/ 目录下还有集成测试与 lint 测试，benchmarks/ 目录则提供 prompt 基准（npm run bench:prompts 等脚本），可作为你修改对应模块时的回归参考。

8. Rebase 到上游

功能分支（目标 upstream/dev）

# 拉取上游最新
git fetch upstream

# 将你的分支 rebase 到 dev
git rebase upstream/dev

# 如有冲突：解决后执行 git rebase --continue

# 强制推送到你的 Fork（分支无他人协同时安全）
git push --force-with-lease origin <your-branch>

# rebase 后重跑测试
npm run build
npm run test:run

发布分支（目标 upstream/main）

git fetch upstream
git rebase upstream/main   # 仅当你的 PR 目标是 main
git push --force-with-lease origin <your-branch>
npm run build
npm run test:run

为什么用 --force-with-lease？ 它比 --force 更安全：如果自上次 fetch 后有人向你的分支推送过提交，推送会被中止，避免覆盖他人工作。

9. 提交 PR

1. 推送分支到 Fork：

   git push origin <your-branch>
   

2. 发起 PR：进入主仓库的 Pull Requests 页面，点击 "New pull request"，选择你的 Fork 与分支，填写标题与描述，并在描述中引用相关 issue（例如 "Fixes #123"）。

3. PR 模板：检查 .github/pull_request_template.md（如存在）中的必备章节；发起 PR 时 GitHub 会自动填充模板。

4. 发布工作流（进阶）：如果你的 PR 需要触发发版，可以调用 /oh-my-claudecode:release skill（对应 skills/release/SKILL.md 与 commands/release.md）。这通常面向维护者；不确定时在 PR 中询问。

5. 后续流程：GitHub Actions 会运行测试、lint 与构建检查；审阅者给出反馈；通过向同一分支追加提交来更新 PR；获得批准后由维护者合并。

10. 常见故障排查

10.1 "OMC_PLUGIN_ROOT is not set"

说明你绕过了 omc shim 直接用了 claude --plugin-dir。手动导出即可：

export OMC_PLUGIN_ROOT=/path/to/oh-my-claudecode
claude --plugin-dir /path/to/oh-my-claudecode

或者使用会自动设置该变量的 omc shim：

omc --plugin-dir /path/to/oh-my-claudecode

这与第 4.1 节源码分析吻合：OMC_PLUGIN_ROOT 是 OMC 运行时识别"当前插件根目录"的核心环境变量，omc shim 的作用之一就是替你正确设置它。

10.2 重建后 skills/agents 不显示

npm run build 之后必须重跑 setup 以刷新会话内命令注册表：

omc setup --plugin-dir-mode

然后重启 Claude Code。

10.3 构建报 "esbuild: not found"

npm install
npm run build

若仍不行，清除重装：

rm -rf node_modules package-lock.json
npm install
npm run build

10.4 Rebase 后测试失败

# 清除缓存并重装
npm ci
npm run test:run

10.5 插件仍显示旧版本

插件缓存可能需要刷新：

npm run build
omc setup --plugin-dir-mode
# 重启 Claude Code

10.6 更多帮助：诊断工具

omc doctor
omc doctor conflicts
omc doctor --plugin-dir /path/to/oh-my-claudecode

更多排查内容见 docs/LOCAL_PLUGIN_INSTALL.md 以及 docs/REFERENCE.md 的 Plugin directory flags 章节。

11. 延伸资源

• 主 README：README.md（Quick Start 章节适合先读一遍）；
• 参考文档：docs/REFERENCE.md；
• 本地插件安装：docs/LOCAL_PLUGIN_INSTALL.md；
• 入门指南：docs/GETTING-STARTED.md；
• CLI 入口源码：src/cli/index.ts（setup/install/doctor 等全部子命令的注册处）；
• 启动与 --plugin-dir 处理：src/cli/launch.ts。

遵循以上流程，你就能在 OMC 仓库中安全地开发、验证并提交贡献：源码改动走 dev:full 快速迭代，markdown 资源改动走 build + setup，提交前记得 git restore dist/ bridge/，让 PR 只包含真正的源码变更。