ccgx-workflow — Claude × Codex × Gemini 多模型协作

简体中文 | English

这是什么

Claude Code 编排 Codex（后端）+ Gemini（前端）的多模型协作开发系统。前端任务自动路由 Gemini，后端任务自动路由 Codex，Claude 负责编排决策与代码审核。外部模型无写入权限——它们只返回 patch，由 Claude 审核后落地。

Claude Code (编排)
       │
   ┌───┴───┐
   ↓       ↓
Codex   Gemini
(后端)   (前端)
   │       │
   └───┬───┘
       ↓
  Unified Patch

项目沿革：ccgx-workflow 由 ccg-workflow 从零 rewrite 而来——分叉点为 2026-05 的 v3.x 版本线。上游项目此后仍在独立维护、持续发版，两个项目各自演进。/ccg:* 命令面板对老用户手势兼容，但底层架构已完全替换。原项目 MIT 许可下的代码与版权完整保留，详见 LICENSE。 深度对比：docs/VS-CCG-WORKFLOW.zh-CN.md · 迁移指南：MIGRATION-FROM-CCG-WORKFLOW.md

核心特性

• 零配置模型路由 — 前端 → Gemini / 后端 → Codex，按 phase frontmatter 的 Type: 字段自动派发；路由在 init 时可配置
• 30 个 /ccg:* 斜杠命令 — 规划、执行、审查、自治长跑、异步任务三件套、OPSX 规范驱动、Agent Teams、Git 工具
• 7 个被动 hook — 状态栏、context 监控、会话记忆、卡环检测、skill 路由、stop 关卡、子 agent 上下文注入；安装后零配置
• 三档质量门 + Gates Taxonomy — --quality=fast|triple|debate 切换 Plan-Critic-Verify 深度；11 门 registry + 需求覆盖度检查 + advance/revise/escalate 裁决
• autonomous 原生 Workflow 编排 — roadmap 驱动的后台长跑，--resume 断点恢复；旧 wave 并行模式保留在 --legacy
• review --fix auto-retry 收敛环 — 修复 → 自动 re-review → 无 Critical 即 pass；escalate 是唯一询问用户的出口
• 任务持久化容器 — .context/tasks/<id>/task.json（冻结 schema v1）+ 派生 STATE.json 投影，状态栏直接展示。任务容器需经 task-store.cjs create 显式创建后 STATE 段才有内容（当前工作流不自动创建）
• team-exec 分波调度 — 任务级拓扑分波 + 文件交叉拆子波 + O_EXCL 状态锁 + 每波 cross-phase 回归门
• fresh-context subagent 协议 — phase-runner / code-fixer / debug-session-manager 把主线 context 压在 ≤15%，主线只接 ≤200 token 摘要
• OPSX 规范驱动 — 集成 OpenSpec (OPSX)，把模糊需求变成可验证约束
• plugin 优先 + 按模型降级 — codex/gemini plugin 装了走 plugin 直连（Channel A）；缺哪个模型只降级哪个到 Node shim CLI 路径（Channel B），绝非全有或全无

快速开始

前置条件

| 依赖 | 必需 | 说明 | |------|------|------| | Node.js 20+ | 是 | [email protected] 要求 Node ≥ 20 | | Claude Code CLI | 是 | 安装方法 | | codex 接入 | 二选一 | codex@openai-codex plugin（推荐）或 npm i -g @openai/codex | | gemini 接入 | 三选一 | gemini@gemini-ccgx fork plugin（推荐）或 上游 gemini@google-gemini + repatch 或 npm i -g @google/gemini-cli |

为什么是「选一」：ccgx-workflow 优先走 plugin（Claude Code 一键装、内置鉴权）。plugin 没装时，仅该模型降级到 ~/.claude/bin/codeagent-wrapper Node shim 启动独立 CLI。两条路都没装时，对应 /ccg:* 命令在调 codex/gemini 时会以 exit 127 退出并打印安装提示。

一键安装

npx ccgx-workflow

首次运行会提示选择语言（简体中文 / English）、API 提供方、MCP 工具，全部交互式完成。CLI 命令名仍为 ccg（保持老用户肌肉记忆）。

安装 Claude Code

npx ccgx-workflow menu  # 选择「安装 Claude Code」

支持 npm / homebrew / curl / powershell / cmd。

启用多模型协作（codex / gemini 接入）

codex — plugin（推荐）或 CLI

在 Claude Code 内执行：

/plugin install codex@openai-codex

或独立 CLI：

npm i -g @openai/codex
codex login

gemini — ccgx fork plugin（推荐）

gemini 的推荐路径是 ccgx 维护的 fork wzyxdwll/gemini-plugin-cc（插件标识 gemini@gemini-ccgx，v1.2.0；要求 Node.js ≥ 18.18 + Google 账号或 GEMINI_API_KEY）：

# 终端中执行
claude plugin marketplace add wzyxdwll/gemini-plugin-cc
claude plugin install gemini@gemini-ccgx

然后在 Claude Code 内执行 /reload-plugins 和 /gemini:setup。

fork 相对上游插件的价值：

• 全部已记录补丁已作为永久 commit 合入（P 系列——编号非连续、最高 P-21——加 W1/W2 与 I1/I2，含所有 Windows spawn 点的 windowsHide）——无需 repatch 步骤，plugin 更新也不会丢失修复
• gemini-batch.mjs 绕过 ACP — 用 stdin + --output-format json 驱动 gemini CLI batch 模式，完全跳过 ACP broker / named-pipe 传输；实测 trivial 任务从 5+ 分钟静默挂起降到 29 秒干净退出、零孤儿 MCP 子进程
• 双层超时 + Windows 进程树清杀 — --idle-timeout-ms（opt-in）+ 2 小时 wall-time 上限；taskkill /T /F 清理 cmd.exe → gemini.cmd → node 三层链
• ~/.gemini/.env 认证桥接 — 把 GEMINI_API_KEY 等带过 gemini-cli 0.42 的 folder-trust 门（未信任目录可用；opt-out：GEMINI_COMPANION_NO_ENV_BRIDGE）
• ACP 稳定性补丁 — broker watchdog、per-method 客户端超时、broker idle 自退、broker/ready 就绪握手
• --allowed-mcp-server-names 透传 — ACP 路径默认抑制 settings.json MCP 合并，省 30–60 秒 Windows 首次冷启动

备选路径：上游插件 + repatch

claude plugin marketplace add sakibsadmanshajib/gemini-plugin-cc
claude plugin install gemini@google-gemini

上游 v1.0.1 在 Windows 上有 8 处 spawn 缺 windowsHide: true（cmd 黑窗闪现、抢焦点、ACP broker ENOENT）。仅当使用上游插件时，安装后以及每次 plugin update 后（更新会覆盖 cache）需运行随包提供的 repatch 脚本：

# 脚本随 npm 包发布，位于 templates/scripts/repatch-gemini-plugin.mjs
# npm 全局安装时：
node "$(npm root -g)/ccgx-workflow/templates/scripts/repatch-gemini-plugin.mjs"

脚本幂等：已 patch 的打 [SKIP]，未 patch 的打 [APPLY]；完成后需重启 broker daemon（或 /plugin disable + /plugin enable）。根因与补丁细节见 .ccg-migration/PLUGIN-PATCHES.md。截至目前，上游尚未修复任何已记录问题。

CLI fallback

npm i -g @google/gemini-cli
gemini   # 首次交互式启动时完成 Google 账号认证；或设置 GEMINI_API_KEY

混搭与验证

检测是按模型独立的：可以 codex 走 plugin、gemini 走 CLI，反之亦然——缺哪个 plugin 只降级哪个模型到 Channel B。查看当前走哪条通道：

node ~/.claude/.ccg/scripts/check-plugins.cjs
# exit 0 = 双 plugin 已装（Channel A）
# exit 1 = 至少缺一个（缺失模型走 Channel B fallback）
# exit 2 = plugin registry 不可读（Channel B）

@ 后是 marketplace identifier。如果提示 marketplace 未配置，在 Claude Code 里执行 /help plugin，或参考 Claude Code plugin 官方文档。

命令清单

下表中 Codex / Gemini 为默认路由，均可在 init 时配置。

开发工作流

| 命令 | 说明 | 模型 | |------|------|------| | /ccg:workflow | 多模型协作开发工作流（研究→构思→计划→执行→优化→评审），智能路由前端→Gemini、后端→Codex | Codex + Gemini | | /ccg:plan | 多模型协作规划——上下文检索 + 双模型分析 → 生成 Step-by-step 实施计划 | Codex + Gemini | | /ccg:execute | 多模型协作执行——根据计划获取原型 → Claude 重构实施 → 多模型审计交付 | Codex + Gemini + Claude | | /ccg:codex-exec | Codex 全权执行计划——读取 /ccg:plan 产出的计划文件，Codex 承担 MCP 搜索 + 代码实现 + 测试，多模型审核 | Codex + 多模型审核 | | /ccg:autonomous | 跨 phase 自治长跑：roadmap → 原生 Workflow 串行编排（默认，后台运行 + 断点恢复），--legacy 降级 wave 并行 prompt 轮转 | phase-runner | | /ccg:context | 项目上下文管理：初始化 .context 目录、记录决策日志、压缩归档、查看历史 | Claude | | /ccg:enhance | 内置 Prompt 增强，将模糊需求转化为结构化任务描述 | Claude |

分析与质量

| 命令 | 说明 | 模型 | |------|------|------| | /ccg:analyze | 多模型技术分析（并行执行）：Codex 后端视角 + Gemini 前端视角，交叉验证后综合见解 | Codex + Gemini | | /ccg:debug | 多模型调试（manager + debugger 双层 fresh-context）：科学方法 hypothesis 链 + 持久 session + cap 3 升级 | debug-session-manager | | /ccg:optimize | 多模型性能优化：Codex 后端优化 + Gemini 前端优化 | Codex + Gemini | | /ccg:test | 多模型测试生成：智能路由 Codex 后端测试 / Gemini 前端测试 | 智能路由 | | /ccg:review | 多模型代码审查：无参数时自动审查 git diff，双模型交叉验证；--adversarial 加敌对审查；--fix 闭环修复 | Codex + Gemini + code-fixer | | /ccg:verify --gate=<change\|quality\|security\|module> | 统一校验关卡：按 --gate 路由到对应 skill，--all 等价 verify-work | Claude | | /ccg:verify-work | 会话式 UAT 工作流——UAT.md 状态文件 + cold-start smoke 自动注入 + 自动 diagnose-plan-fix 收敛环 | 编排 | | /ccg:debate | 原生多轮对辩原语：codex propose ↔ gemini challenge ↔ codex respond，cap N 轮或 challenger 自报无 critical 即停 | Codex + Gemini |

异步任务三件套

| 命令 | 说明 | |------|------| | /ccg:status [job-id] | 后台任务观测：列表 / 单查 / 阻塞等待 / dashboard / tail 流式 / 卡点检测 / 单 phase cancel | | /ccg:result <job-id> | 取后台任务最终结果：读取 .context/jobs/<id>/result.md，输出 ≤200 token 摘要 | | /ccg:cancel <job-id> | 中止活跃后台任务：先写 cancel.flag（cooperative）→ grace 5s → kill-tree 强制 |

OPSX 规范驱动

| 命令 | 说明 | |------|------| | /ccg:spec-init | 初始化 OpenSpec (OPSX) 环境 + 验证多模型 MCP 工具 | | /ccg:spec-research | 需求 → 约束集（并行探索 + OPSX 提案） | | /ccg:spec-plan | 多模型分析 → 消除歧义 → 零决策可执行计划 | | /ccg:spec-impl | 按规范执行 + 多模型协作 + 归档 | | /ccg:spec-review | 双模型交叉审查（独立工具，随时可用） |

Agent Teams

| 命令 | 说明 | |------|------| | /ccg:team | Agent Teams 8 阶段企业级工作流——7 角色全流程统一编排（含 research / plan / review 子命令路由） | | /ccg:team-exec | Agent Teams 并行实施——读取计划文件，spawn Builder teammates 并行写代码 |

前置：settings.json 启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。

Git 工具

| 命令 | 说明 | |------|------| | /ccg:commit | 智能 Git 提交：分析改动生成 Conventional Commit 信息，支持拆分建议 | | /ccg:rollback | 交互式 Git 回滚：安全回滚分支到历史版本，支持 reset/revert 模式 | | /ccg:clean-branches | 清理 Git 分支：安全清理已合并或过期分支，默认 dry-run 模式 | | /ccg:worktree | 管理 Git Worktree：在 ../.ccg/项目名/ 目录创建，支持 IDE 集成和内容迁移 |

项目初始化

| 命令 | 说明 | |------|------| | /ccg:init | 初始化项目 AI 上下文：生成根级与模块级 CLAUDE.md 索引 |

配置

目录结构

~/.claude/
├── commands/ccg/          # 30 个核心斜杠命令 + Skill Registry 自动生成命令
├── agents/ccg/            # 21 个子智能体
├── skills/ccg/            # 质量关卡 + 10 域知识 + impeccable + 编排
├── hooks/                 # 7 个被动 hook
│   ├── ccg-statusline.js          # 状态栏：model / context / git branch / session
│   ├── ccg-context-monitor.js     # PostToolUse：剩余 context ≤35% / ≤25% 告警
│   ├── ccg-session-state.cjs      # SessionStart：注入 ≤200 token 项目记忆摘要
│   ├── ccg-loop-detector.cjs      # UserPromptSubmit：连续近似重复提问（卡环）检测
│   ├── ccg-skill-router.cjs       # UserPromptSubmit：领域关键词 → skill 路径注入
│   ├── ccg-stop-gate.cjs          # Stop/SubagentStop：仍活跃后台 job 提醒
│   └── ccg-subagent-context.cjs   # PreToolUse(Task|Agent)：注入 phase spec，≤2048 字符
├── bin/codeagent-wrapper  # Channel B shim → 转发 invoke-model.mjs
└── .ccg/
    ├── config.toml
    ├── scripts/
    │   ├── invoke-model.mjs              # Channel B 降级实现（Node ESM）
    │   ├── ccgx-call-plugin.mjs          # Channel A spawn 安全层（杜绝 shell-escape）
    │   ├── check-plugins.cjs             # Channel A/B preflight 检测
    │   ├── ccg-phase-runner-launcher.mjs # /ccg:autonomous 受监督 launcher
    │   ├── spec-suggestion.cjs           # RFC-9 Spec Evolution 候选提取
    │   ├── task-store.cjs                # .context/tasks 容器 + STATE.json CLI
    │   ├── ccg-team-schedule.cjs         # team-exec 拓扑分波导出器
    │   └── ccg-state-lock.cjs            # O_EXCL 文件锁 CLI（merge-summary / locked-write）
    └── prompts/
        ├── claude/    # 6 个 Claude 专家提示词
        ├── codex/     # 6 个 Codex 专家提示词
        └── gemini/    # 7 个 Gemini 专家提示词

环境变量

~/.claude/settings.json 的 "env" 段。以下变量仅在 Channel B（wrapper / invoke-model.mjs 路径）生效：

| 变量 | 说明 | 默认 | 何时调整 | |------|------|------|----------| | CODEAGENT_POST_MESSAGE_DELAY | Codex 完成后等待秒数；非法值回退 5，上限 60 | 5 | Codex 进程挂起时设为 1 | | CODEX_TIMEOUT | 执行超时（秒） | 7200 | 长任务时增大 |

MCP

npx ccgx-workflow menu  # 选择「配置 MCP」

init 多选框提供的选项（默认勾选与 ccg init 一致）：

| 选项 | 默认 | 说明 | |------|------|------| | ace-tool | ✅ 勾选 | search_context 代码检索；检索 provider 优先级 1 | | fast-context | 不勾选 | AI 驱动语义搜索；优先级 2 | | context7 | ✅ 勾选 | 免费，库文档查询 | | grok-search | 不勾选 | 联网搜索，需 API Key（安装时询问 GROK_API_URL/GROK_API_KEY，可选 TAVILY/FIRECRAWL key） | | contextweaver | 不勾选 | 硅基流动嵌入检索，需 API Key；优先级 3 |

检索 provider 一个都不选时跳过 MCP 检索配置。

另有辅助工具 MCP（Playwright / DeepWiki / Exa）可随时通过 npx ccgx-workflow menu →「配置 MCP」→ 辅助工具安装。

升级 / 卸载

# 升级
npx ccgx-workflow@latest             # npx 用户
npm install -g ccgx-workflow@latest  # npm 全局用户

# 卸载
npx ccgx-workflow                    # 选「卸载」
npm uninstall -g ccgx-workflow       # npm 全局用户额外执行

FAQ

Codex CLI 进程不退出

--json 模式下部分 Codex CLI 版本（如 0.80.0）输出完成后不会自动退出。仅影响 Channel B（CLI fallback）。

修复：设置 CODEAGENT_POST_MESSAGE_DELAY=1。

我之前用 ccg-workflow，能直接用 ccgx-workflow 吗

可以。/ccg:* 命令面板完全兼容，.context/ 状态、.ccg/roadmap.md 全部兼容。详见 MIGRATION-FROM-CCG-WORKFLOW.md 与深度对比。

为什么 CLI 命令叫 ccg 不叫 ccgx

保留 ccg 是为了让老用户的 alias / 脚本 / 文档零成本迁移——/ccg:* 命令面板和 ccg CLI 都是肌肉记忆。包名 ccgx-workflow 用于消歧 npm 命名空间，CLI 名字仍是 ccg。

fork 插件（gemini@gemini-ccgx）和上游插件（gemini@google-gemini）选哪个

选 fork。所有已记录补丁（编号非连续的 P 系列、最高 P-21，加 W1/W2 与 I1/I2）已作为永久 commit 合入 fork，无需 repatch，plugin 更新也不会丢失修复；fork 还额外提供 gemini-batch.mjs 绕过 ACP、双层超时 + 进程树清杀、~/.gemini/.env 认证桥接。上游插件仍可用，但每次 plugin update 后必须重跑 repatch 脚本——且截至目前上游尚未修复任何已记录问题。细节见 .ccg-migration/PLUGIN-PATCHES.md。

贡献

欢迎 PR / issue。本项目 MIT 协议，提交即视为同意以 MIT 发布。

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Credits

ccgx-workflow 站在 ccg-workflow 之上，对原作者 fengshao1227 与上游贡献者致谢。

• ccg-workflow v1.x – v3.x 原项目（fengshao1227）
• gsd-build/get-shit-done — fresh-context subagent 协议、context monitor、code-fixer worktree 闭环、debug session manager 等多处架构灵感
• cexll/myclaude — codeagent-wrapper 灵感
• UfoMiao/zcf — Git 工具灵感
• GuDaStudio/skills — 路由设计

License

MIT — 详见 LICENSE（保留原作者 fengshao1227 与维护人 wangzy 双 copyright）

v2.5.0 | Issues | 与 ccg-workflow 对比 | 从 ccg-workflow 迁移