【开源缝合】CCG: Claude Code 编排三 CLI 协作

Claude Code 主导 + Codex CLI + Gemini CLI + Claude CLI 协作工作流系统

最新版本 v1.3.3：修复 Windows PATH 配置安全问题

---

🎉 最新更新

v1.3.3 - Windows PATH 配置安全修复 🔒

• ✅ 安全修复：Windows PATH 配置改用安全追加方法，避免 setx 1024 字符限制
• ✅ 新方法：使用 PowerShell [System.Environment]::GetEnvironmentVariable 先读取后追加
• ✅ 重复检测：自动检查路径是否已存在，避免重复添加
• ✅ 无字符限制：支持超长 PATH（最大 32767 字符）
• ✅ 向下兼容：不影响现有用户配置

v1.3.2 - MCP 配置缺失修复 (2026-01-05)

• ✅ 关键修复：安装后 ~/.ccg/config.toml 现在包含完整的 [mcp] 配置部分
• ✅ 类型安全：添加 CcgConfig.mcp TypeScript 接口定义
• ✅ 默认配置：createDefaultConfig 自动生成完整 MCP 配置
• ✅ 配置版本：配置文件版本号从 1.0.0 升级到 1.3.2

v1.3.1 - 命令模板修正 (2026-01-05)

• ✅ 说明修正：澄清 auggie 也支持 Prompt 增强功能（需按教程配置）
• ✅ 模板更新：修正 /ccg:dev 和 /ccg:enhance 命令的提示信息
• ✅ 配置说明：prompt_enhance_auggie = "" 改为"留空表示未配置，按教程配置后填入工具名"
• ✅ 用户体验：提供配置教程链接，不再误导用户认为 auggie 不支持 Prompt 增强

v1.3.0 - MCP 动态选择系统 ⭐

• ✅ 多 MCP 支持：安装时可选 ace-tool（开箱即用Prompt增强+代码检索）或 auggie（官方原版，代码检索+可选Prompt增强）
• ✅ 交互式选择：友好的 MCP 选择界面，对比功能差异，支持跳过安装
• ✅ 配置驱动：生成 ~/.ccg/config.toml，记录工具映射和参数名
• ✅ 自包含模板：命令模板减少 50% 提示词长度，直接读取配置无需外部文档
• ✅ 完全兼容：12个命令模板（dev, code, frontend, backend, review, analyze, enhance 等）支持动态 MCP 工具调用
• ✅ 灵活配置：auggie 可通过配置支持 Prompt 增强（参考 配置教程）

v1.2.3 - 安装体验优化

• ✅ 二进制验证：安装后自动验证 codeagent-wrapper 可用性
• ✅ 错误显示：安装失败时显示详细错误信息和解决方案
• ✅ 文档清理：删除过时提示，优化用户体验

v1.2.0 - ROLE_FILE 动态注入 ⭐

• ✅ 真正的动态注入：codeagent-wrapper 自动识别 ROLE_FILE: 指令
• ✅ 0 token 消耗：Claude 无需先用 Read 工具读取提示词文件
• ✅ 自动化管理：一行 ROLE_FILE: 搞定，无需手动粘贴
• ✅ 完整日志：注入过程可追溯（文件路径、大小）

v1.1.3 - PATH 自动配置

• ✅ Mac/Linux：自动添加到 .zshrc / .bashrc
• ✅ Windows：详细手动配置指南 + PowerShell 一键命令
• ✅ 智能检测：避免重复配置
• ✅ 开箱即用：安装后直接可用 codeagent-wrapper

v1.1.0 - 智能更新系统

• ✅ 一键更新：npx ccg-workflow 选择"更新工作流"
• ✅ 自动版本检测：自动对比当前版本与 npm 最新版本
• ✅ 增量更新：仅更新命令模板和提示词，保留用户配置
• ✅ 强制修复：支持强制重装，修复损坏的文件
• ✅ 零权限：无需 sudo，无需全局安装

v1.0.0 - npm 首次发布

• ✅ 从 Python 脚本重构为 TypeScript + unbuild 构建系统
• ✅ 发布到 npm: npx ccg-workflow 一键安装
• ✅ 交互式配置菜单（初始化/更新/卸载）
• ✅ 三 CLI 协作：Claude + Codex + Gemini
• ✅ 18个专家提示词：Codex 6个 + Gemini 6个 + Claude 6个
• ✅ 配置文件从 config.json 迁移到 ~/.ccg/config.toml
• ✅ 支持 smart/parallel/sequential 三种协作模式

---

架构说明

Claude Code 主导的三 CLI 协作模式

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code CLI (主导)                    │
│                  编排、决策、代码实施                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  Codex CLI  │  │ Gemini CLI  │  │ Claude CLI  │        │
│  │  (后端原型) │  │  (前端原型) │  │  (全栈整合) │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│                                                             │
│  通过 codeagent-wrapper 调用，返回 Unified Diff Patch      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

关键特性：

• Claude Code 是主对话，负责编排整个工作流、做最终决策、实施代码
• Codex/Gemini/Claude 子进程 通过 codeagent-wrapper 调用，生成原型代码
• 零写入权限：子进程只能返回 Unified Diff Patch，不能直接修改文件
• 脏原型处理：子进程输出视为"脏原型"，需经 Claude Code 重构为生产级代码

---

核心特性

特性	描述
Claude Code 主导	Claude Code CLI 作为编排者，Codex/Gemini/Claude 子进程协作
三 CLI 协作	同时调用 Codex CLI + Gemini CLI + Claude CLI 进行交叉验证
智能路由	前端任务 → Gemini，后端任务 → Codex，全栈整合 → Claude
MCP 动态选择	安装时可选 ace-tool / auggie，命令模板自动适配，支持 Prompt 增强（ace-tool）或纯代码检索（auggie）
6阶段工作流	Prompt增强 → 上下文检索 → 三 CLI 分析 → 原型生成 → 代码实施 → 审计交付
18个专家提示词	Codex 6个 + Gemini 6个 + Claude 6个角色
交互式安装	npx 一键运行，图形化配置界面
跨平台	支持 macOS、Linux、Windows

---

快速开始

方式一：npx 直接运行（推荐）

# 交互式配置安装
npx ccg-workflow

方式二：全局安装

npm install -g ccg-workflow
ccg

方式三：源码安装

git clone https://github.com/fengshao1227/ccg-workflow.git
cd ccg-workflow/skills-v2
pnpm install && pnpm build
pnpm start

前置要求

• Node.js 18+
• Claude Code CLI
• Codex CLI / Gemini CLI（可选，用于多模型协作）

---

交互式菜单

运行后会显示交互式菜单：

  CCG - Claude + Codex + Gemini
  Multi-Model Collaboration System

? CCG 主菜单
❯ ➜ 初始化 CCG 配置
  ➜ 更新工作流
  ➜ 卸载 CCG
  ? 帮助
  ✕ 退出

首次安装

选择 "初始化 CCG 配置" 进行首次安装，会引导你：

1. 选择语言（中文/English）
2. 选择 MCP 代码检索工具：✨ NEW
   • [1] ace-tool（推荐新手）：开箱即用，自动配置 Prompt 增强 + 代码检索
   • [2] auggie（官方原版）：代码检索 + 可选 Prompt 增强（需额外配置，查看教程）
   • [0] 跳过：稍后手动配置
3. 配置前端模型（Gemini/Codex/Claude）
4. 配置后端模型（Codex/Gemini/Claude）
5. 选择协作模式（并行/智能/顺序）
6. 选择要安装的工作流

更新到最新版

选择 "更新工作流"，系统将：

1. 🔍 检查 npm 最新版本
2. 📊 显示当前版本 vs 最新版本对比
3. 📥 自动更新所有命令模板和提示词
4. ✅ 保留用户配置和自定义内容

特性：

• ✅ 自动检测版本，有更新时提示
• ✅ 已是最新版本时，可选择"强制重装"修复损坏文件
• ✅ 无需 sudo 权限
• ✅ 无需卸载重装

---

使用

# 完整的多模型开发工作流（含 Prompt 增强）
/ccg:dev "实现用户认证功能"

# 智能路由代码生成
/ccg:code "添加用户注册表单"

# UltraThink 调试
/ccg:debug "登录接口返回 500 错误"

# 多模型测试生成
/ccg:test "为用户服务添加单元测试"

# 质量门控修复（90%+ 通过）
/ccg:bugfix "密码重置邮件发送失败"

# 深度分析
/ccg:think "评估微服务拆分方案"

# 性能优化
/ccg:optimize "优化首页加载速度"

# 前端任务 → Gemini
/ccg:frontend "创建登录表单组件"

# 后端任务 → Codex
/ccg:backend "实现 JWT 认证中间件"

# 双模型代码审查（无参数自动审查 git diff）
/ccg:review

# 双模型分析
/ccg:analyze "这个架构有什么问题？"

# 单独使用 Prompt 增强
/ccg:enhance "实现用户认证功能"

# Git 智能提交
/ccg:commit --emoji

# 交互式回滚
/ccg:rollback --branch main --target v1.0.0

# 清理已合并分支
/ccg:clean-branches --dry-run

# 创建 Worktree 并用 IDE 打开
/ccg:worktree add feature-ui -o

# 初始化项目 AI 上下文
/ccg:init "我的项目"

---

命令列表

开发工作流

命令	用途	CLI 路由
/ccg:dev	完整6阶段开发工作流（含Prompt增强）	ace-tool + Codex + Gemini + Claude
/ccg:code	三 CLI 代码生成（智能路由）	前端→Gemini / 后端→Codex / 整合→Claude
/ccg:debug	UltraThink 三 CLI 调试	Codex + Gemini + Claude 并行诊断
/ccg:test	三 CLI 测试生成	Codex 后端 + Gemini 前端 + Claude 集成
/ccg:bugfix	质量门控修复（90%+ 通过）	三 CLI 交叉验证
/ccg:think	深度分析	三 CLI 并行分析
/ccg:optimize	性能优化	Codex 后端 + Gemini 前端 + Claude 全栈
/ccg:frontend	前端/UI/样式任务	Gemini + Claude 整合
/ccg:backend	后端/逻辑/算法任务	Codex + Claude 整合
/ccg:review	代码审查（无参数自动审查 git diff）	Codex + Gemini + Claude
/ccg:analyze	技术分析	Codex + Gemini + Claude
/ccg:enhance	Prompt 增强	ace-tool MCP

Git 工具

命令	用途
/ccg:commit	智能 commit：分析改动、生成 conventional commit 信息、支持 emoji
/ccg:rollback	交互式回滚：列分支、列版本、二次确认后执行 reset/revert
/ccg:clean-branches	清理分支：安全查找并清理已合并或过期的分支
/ccg:worktree	Worktree 管理：在 ../.ccg/项目名/ 下创建，支持 IDE 集成

项目初始化

命令	用途
/ccg:init	初始化项目 AI 上下文，生成根级与模块级 CLAUDE.md 索引

---

工作流程

┌─────────────────────────────────────────────────────────────┐
│                      /ccg:dev 工作流                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Phase 0: Prompt 增强 (ace-tool prompt-enhancer)            │
│      ↓                                                      │
│  Phase 1: 上下文检索 (ace-tool codebase-retrieval)          │
│      ↓                                                      │
│  Phase 2: 三 CLI 分析 (Codex ∥ Gemini ∥ Claude) ← 并行     │
│      ↓                                                      │
│  Phase 3: 三 CLI 原型生成                                    │
│      ├── 前端任务 → Gemini CLI                              │
│      ├── 后端任务 → Codex CLI                               │
│      └── 全栈整合 → Claude CLI                              │
│      ↓                                                      │
│  Phase 4: 代码实施 (Claude Code 交叉验证后重构)             │
│      ↓                                                      │
│  Phase 5: 审计交付 (Codex ∥ Gemini ∥ Claude) ← 并行审查    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

安装目录结构

安装后会在 ~/.claude/ 和 ~/.ccg/ 下创建：

~/.claude/
├── commands/ccg/           # 斜杠命令
│   ├── _config.md          # 共享配置
│   ├── dev.md              # /ccg:dev 完整工作流
│   ├── code.md             # /ccg:code 多模型代码生成
│   ├── frontend.md         # /ccg:frontend 前端任务
│   ├── backend.md          # /ccg:backend 后端任务
│   └── ...                 # 其他命令
└── prompts/ccg/            # 角色提示词
    ├── codex/
    │   ├── architect.md    # 后端架构师
    │   ├── analyzer.md     # 技术分析师
    │   ├── debugger.md     # 调试专家
    │   ├── tester.md       # 测试工程师
    │   ├── reviewer.md     # 代码审查员
    │   └── optimizer.md    # 性能优化专家
    ├── gemini/
    │   ├── frontend.md     # 前端开发专家
    │   └── ...
    └── claude/
        └── ...

~/.ccg/
└── config.toml             # CCG 配置文件

---

配置文件

配置文件位于 ~/.ccg/config.toml：

[general]
version = "1.3.1"
language = "zh-CN"

[mcp]
provider = "ace-tool"  # ace-tool | auggie | none
setup_url = "https://linux.do/t/topic/1280612"

[mcp.tools]
# 工具名称映射（配置驱动，命令模板自动适配）
code_search_ace = "mcp__ace-tool__search_context"
code_search_auggie = "mcp__auggie-mcp__codebase-retrieval"
prompt_enhance_ace = "mcp__ace-tool__enhance_prompt"
prompt_enhance_auggie = ""  # 留空表示未配置，按教程配置后填入工具名

# 参数名映射
query_param_ace = "query"
query_param_auggie = "information_request"

[routing]
mode = "smart"  # smart | parallel | sequential

[routing.frontend]
models = ["gemini", "codex", "claude"]
primary = "gemini"
strategy = "parallel"

[routing.backend]
models = ["codex", "gemini", "claude"]
primary = "codex"
strategy = "parallel"

[routing.review]
models = ["codex", "gemini", "claude"]
strategy = "parallel"

---

更新

更新到最新版本

# 运行 CCG 菜单
npx ccg-workflow

# 选择 "更新工作流"

系统会自动：

1. 检查 npm 最新版本
2. 对比当前版本与最新版本
3. 更新所有命令模板（~/.claude/commands/ccg/）
4. 更新所有角色提示词（~/.claude/prompts/ccg/）
5. 保留用户配置（~/.ccg/config.toml）

强制修复损坏文件

如果已是最新版本但文件损坏，可选择"强制重新安装"：

npx ccg-workflow
# 选择 "更新工作流"
# 当提示"已是最新版本"时
# 选择 Yes 进行强制重装

---

卸载

# 交互式卸载
npx ccg-workflow
# 选择 "卸载 CCG"

或手动删除：

rm -rf ~/.claude/commands/ccg
rm -rf ~/.claude/prompts/ccg
rm -rf ~/.ccg

---

开发

# 克隆仓库
git clone https://github.com/fengshao1227/ccg-workflow.git
cd ccg-workflow/skills-v2

# 安装依赖
pnpm install

# 开发模式
pnpm dev

# 构建
pnpm build

# 本地测试
pnpm start

# 类型检查
pnpm typecheck

# 代码检查
pnpm lint

---

调用语法

HEREDOC 语法（推荐）：

codeagent-wrapper --backend <codex|gemini|claude> - [工作目录] <<'EOF'
<任务内容>
EOF

简单任务：

codeagent-wrapper --backend codex "简单任务" [工作目录]

恢复会话：

codeagent-wrapper --backend codex resume <session_id> - <<'EOF'
<后续任务>
EOF

---

并行执行

使用 Claude Code 的 run_in_background: true 参数实现非阻塞并行：

# 启动后台任务（非阻塞）
Bash(run_in_background=true): codeagent-wrapper --backend codex ...
Bash(run_in_background=true): codeagent-wrapper --backend gemini ...

# 获取结果
TaskOutput: task_id=<task_id>

---

安全机制

• 零写入权限：Codex/Gemini 对文件系统无写入权限
• Unified Diff：所有外部模型输出必须为 Unified Diff Patch 格式
• 脏原型处理：外部模型输出视为"脏原型"，需经 Claude 重构
• 自动备份：Patch Auggie MCP 时自动备份原文件

---

CLI 分工

CLI	擅长领域	使用场景
Claude Code	编排、决策、代码实施	工作流控制、最终代码重构、交付
Gemini CLI	前端、UI/UX、视觉设计	CSS、React、Vue 组件原型
Codex CLI	后端、算法、调试	API、业务逻辑、性能优化原型
Claude CLI	全栈整合、交叉验证	契约设计、原型整合
ace-tool	代码检索、Prompt 增强	上下文获取、需求优化

---

专家系统提示词

调用外部 CLI 时动态注入相应的角色设定，确保输出质量和一致性。

18个角色文件

Codex CLI 角色（6个）：

• prompts/codex/architect.md - 后端架构师
• prompts/codex/analyzer.md - 技术分析师
• prompts/codex/debugger.md - 调试专家
• prompts/codex/tester.md - 测试工程师
• prompts/codex/reviewer.md - 代码审查员
• prompts/codex/optimizer.md - 性能优化专家

Gemini CLI 角色（6个）：

• prompts/gemini/frontend.md - 前端开发专家
• prompts/gemini/analyzer.md - 设计分析师
• prompts/gemini/debugger.md - UI调试专家
• prompts/gemini/tester.md - 前端测试工程师
• prompts/gemini/reviewer.md - UI审查员
• prompts/gemini/optimizer.md - 前端性能优化专家

Claude CLI 角色（6个）：

• prompts/claude/architect.md - 全栈架构师
• prompts/claude/analyzer.md - 综合分析师
• prompts/claude/debugger.md - 全栈调试专家
• prompts/claude/tester.md - 集成测试工程师
• prompts/claude/reviewer.md - 代码质量审查员
• prompts/claude/optimizer.md - 全栈性能优化专家

角色文件结构

每个命令根据任务类型注入不同的角色提示词：

命令	Codex 角色	Gemini 角色	Claude 角色
/ccg:code, /ccg:backend	architect.md	-	architect.md
/ccg:frontend	-	frontend.md	architect.md
/ccg:analyze, /ccg:think, /ccg:dev	analyzer.md	analyzer.md	analyzer.md
/ccg:debug	debugger.md	debugger.md	debugger.md
/ccg:test	tester.md	tester.md	tester.md
/ccg:review, /ccg:bugfix	reviewer.md	reviewer.md	reviewer.md
/ccg:optimize	optimizer.md	optimizer.md	optimizer.md

动态角色注入

命令执行时，将角色文件内容注入到 <ROLE> 标签中：

codeagent-wrapper --backend codex - $PROJECT_DIR <<'EOF'
<ROLE>
# 读取 prompts/codex/architect.md 的内容并注入
</ROLE>

<TASK>
实现后端逻辑: <任务描述>

Context:
<相关代码>
</TASK>

OUTPUT: Unified Diff Patch ONLY.
EOF

完整提示词文件

• Codex CLI 角色: prompts/codex/ 目录下的 6 个文件
• Gemini CLI 角色: prompts/gemini/ 目录下的 6 个文件
• Claude CLI 角色: prompts/claude/ 目录下的 6 个文件

---

常见问题

Q: codex 总是思考太久超时该怎么办？

问题描述：在使用 /ccg:dev 等命令时，Codex 后端思考时间过长，导致超时。

解决方案：

• 参考社区讨论：linux.do - Codex 超时问题解决方案

常见优化方法：

• 减少任务复杂度，拆分为更小的子任务
• 调整 Codex CLI 的超时配置
• 使用 --backend gemini 切换到 Gemini 后端测试

Q: 如何更新到最新版本？

一键更新，无需卸载重装：

npx ccg-workflow
# 选择 "更新工作流"

更新会自动：

• 检测 npm 最新版本
• 增量更新命令模板和提示词
• 保留用户配置和 MCP 设置

Q: MCP 动态选择系统是什么？

v1.3.0 核心特性：安装时可以选择：

• ace-tool（第三方）：开箱即用，包含 Prompt 增强 + 代码检索
• auggie（官方）：代码检索 + 可选 Prompt 增强（需配置）

命令模板会根据配置自动适配对应的 MCP 工具调用。

Q: codeagent-wrapper 是什么？

来自 cexll/myclaude 的 Go 工具，封装了多 CLI 调用：

• 支持 --backend codex/gemini/claude 切换
• 会话管理（SESSION_ID）
• ROLE_FILE 动态注入
• 自动安装到 ~/.claude/bin/

更多问题？

查看完整 Q&A：POST_DRAFT.md 包含 11 个常见问题的详细解答。

---

📄 许可证

本项目采用 MIT License 开源协议。

Copyright (c) 2025 fengshao1227

---

致谢

• cexll/myclaude - codeagent-wrapper 多后端调用工具的 Go 代码来源，以及 /ccg:code、/ccg:debug、/ccg:test、/ccg:bugfix、/ccg:think、/ccg:optimize 命令的设计参考
• UfoMiao/zcf - Git 工具（commit、rollback、clean-branches、worktree）和项目初始化（init）命令来源
• GudaStudio/skills - 智能路由（前端→Gemini、后端→Codex）的设计理念
• ace-tool MCP - @mistripple 的 ace-tool 轻量级代码检索和 Prompt 增强方案