fix: Windows 兼容性 - 改用 run_in_background 参数 (v1.7.1)

**问题**： - Windows Git Bash 不支持 heredoc + `&` 后台进程语法 - 用户在调用 workflow 时触发语法错误 **修复**： - 所有命令模板改用 Bash 工具的 `run_in_background: true` 参数 - 统一使用不同的 EOF 标记（EOF_CODEX, EOF_GEMINI）避免冲突 - 更新关键规则说明，移除 shell `&` 符号的说明 **影响范围**： - templates/commands/workflow.md - templates/commands/analyze.md - templates/commands/debug.md - templates/commands/optimize.md - templates/commands/review.md - templates/commands/test.md - skills-v2/CLAUDE.md - package.json (v1.7.0 → v1.7.1) **测试验证**： - macOS 现有功能不受影响 - Windows Git Bash 语法错误已解决
2026-01-08 16:26:28 +08:00
1 parent 3f6fa128cb
commit ea9f436ef4
@@ -2,12 +2,18 @@

 > [根目录](../CLAUDE.md) > **skills-v2**

-**Last Updated**: 2026-01-08 (v1.7.0)
+**Last Updated**: 2026-01-08 (v1.7.1)

 ---

 ## 变更记录 (Changelog)

+### 2026-01-08 (v1.7.1)
+- 🐛 **修复 Windows 兼容性问题**：修改所有命令模板中的后台进程调用语法
+- 📝 **语法改进**：使用 Claude Code 的 `run_in_background: true` 参数替代 shell 的 `&` 符号
+- ✅ **跨平台支持**：修复 Windows Git Bash 的 heredoc + 后台进程语法错误
+- 📋 **涉及文件**：workflow.md, analyze.md, debug.md, optimize.md, review.md, test.md
+
 ### 2026-01-08 (v1.7.0)
 - 🎯 **大幅简化安装流程**：只需配置 MCP（可选），无需选择语言/模型/命令
 - 🔧 **固定模型路由**：Gemini (前端) + Codex (后端)，不再支持自定义
@@ -1,6 +1,6 @@
 {
  "name": "ccg-workflow",
-  "version": "1.7.0",
+  "version": "1.7.1",
  "description": "Claude-Codex-Gemini 多模型协作系统 - 智能路由多模型开发工作流",
  "type": "module",
  "packageManager": "pnpm@10.17.1",
@@ -55,26 +55,42 @@ EOF
 **并行调用两个模型**：

 **执行步骤**：
-1. 在**同一个 Bash 调用**中启动两个后台进程（不加 wait，立即返回）：
-```bash
-codeagent-wrapper --backend codex - $PWD <<'EOF' &
+1. 使用 **Bash 工具的 `run_in_background: true` 参数**启动两个后台进程：
+
+**Codex 分析进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend codex - \"$PWD\" <<'EOF_CODEX'
 ROLE_FILE: ~/.claude/.ccg/prompts/codex/analyzer.md
 <TASK>
 分析需求: $ARGUMENTS
 Context: <阶段1检索到的上下文>
 </TASK>
 OUTPUT: 技术可行性、架构影响、性能考量
-EOF
+EOF_CODEX",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Codex 技术分析"
+})
+```

-codeagent-wrapper --backend gemini - $PWD <<'EOF' &
+**Gemini 分析进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend gemini - \"$PWD\" <<'EOF_GEMINI'
 ROLE_FILE: ~/.claude/.ccg/prompts/gemini/analyzer.md
 <TASK>
 分析需求: $ARGUMENTS
 Context: <阶段1检索到的上下文>
 </TASK>
 OUTPUT: UI/UX 影响、用户体验、视觉设计考量
-EOF
+EOF_GEMINI",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Gemini UI 分析"
+})
 ```
+
 2. 使用 `TaskOutput` 监控并获取 2 个模型的分析结果。

 **⚠️ 强制规则：必须等待 TaskOutput 返回两个模型的完整结果后才能进入下一阶段，禁止跳过或提前继续！**
@@ -129,6 +145,6 @@ EOF
 ## 关键规则

 1. **仅分析不修改** – 本命令不执行任何代码变更
-2. **使用后台进程 `&` + `TaskOutput` 获取结果**
+2. **使用 Bash 工具的 `run_in_background: true` 参数 + `TaskOutput` 获取结果**
 3. **必须等待所有模型返回完整结果后才能进入下一阶段**，禁止跳过或提前继续
 4. **信任规则** – 后端以 Codex 为准，前端以 Gemini 为准
@@ -56,10 +56,12 @@ EOF
 **并行调用 Codex + Gemini**：

 **执行步骤**：
-1. 在**同一个 Bash 调用**中启动两个后台进程（不加 wait，立即返回）：
-```bash
-# Codex 后端诊断
-~/.claude/bin/codeagent-wrapper --backend codex - "$PWD" <<'EOF' &
+1. 使用 **Bash 工具的 `run_in_background: true` 参数**启动两个后台进程：
+
+**Codex 诊断进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend codex - \"$PWD\" <<'EOF_CODEX'
 角色：后端调试专家

 问题：$ARGUMENTS
@@ -68,10 +70,17 @@ EOF
 1. 分析逻辑错误、数据流、异常处理
 2. 检查 API、数据库、服务间通信
 3. 输出诊断假设（按可能性排序）
-EOF
+EOF_CODEX",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Codex 后端诊断"
+})
+```

-# Gemini 前端诊断
-~/.claude/bin/codeagent-wrapper --backend gemini - "$PWD" <<'EOF' &
+**Gemini 诊断进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend gemini - \"$PWD\" <<'EOF_GEMINI'
 角色：前端调试专家

 问题：$ARGUMENTS
@@ -80,8 +89,13 @@ EOF
 1. 分析 UI 渲染、状态管理、事件绑定
 2. 检查组件生命周期、样式冲突
 3. 输出诊断假设（按可能性排序）
-EOF
+EOF_GEMINI",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Gemini 前端诊断"
+})
 ```
+
 2. 使用 `TaskOutput` 监控并获取 2 个模型的诊断结果。

 **⚠️ 强制规则：必须等待 TaskOutput 返回两个模型的完整结果后才能进入下一阶段，禁止跳过或提前继续！**
@@ -131,7 +145,7 @@ EOF
 ## 关键规则

 1. **heredoc 语法** – 外部模型调用必须使用 heredoc
-2. **使用后台进程 `&` + `TaskOutput` 获取结果**
+2. **使用 Bash 工具的 `run_in_background: true` 参数 + `TaskOutput` 获取结果**
 3. **必须等待所有模型返回完整结果后才能进入下一阶段**，禁止跳过或提前继续
 4. **用户确认** – 修复前必须获得确认
 5. **信任规则** – 后端问题以 Codex 为准，前端问题以 Gemini 为准
@@ -60,10 +60,12 @@ EOF
 **并行调用两个模型**：

 **执行步骤**：
-1. 在**同一个 Bash 调用**中启动两个后台进程（不加 wait，立即返回）：
-```bash
-# Codex：后端性能分析
-~/.claude/bin/codeagent-wrapper --backend codex - $PWD <<'EOF' &
+1. 使用 **Bash 工具的 `run_in_background: true` 参数**启动两个后台进程：
+
+**Codex 性能分析进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend codex - \"$PWD\" <<'EOF_CODEX'
 [角色] 你是后端性能优化专家

 [任务] 分析以下代码的后端性能问题：
@@ -73,10 +75,17 @@ $ARGUMENTS
 1. 性能瓶颈列表（按严重程度排序）
 2. 每个问题的优化方案（含代码 Diff）
 3. 预期收益评估
-EOF
+EOF_CODEX",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Codex 后端性能分析"
+})
+```

-# Gemini：前端性能分析
-~/.claude/bin/codeagent-wrapper --backend gemini - $PWD <<'EOF' &
+**Gemini 性能分析进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend gemini - \"$PWD\" <<'EOF_GEMINI'
 [角色] 你是前端性能优化专家

 [任务] 分析以下代码的前端性能问题：
@@ -86,8 +95,13 @@ $ARGUMENTS
 1. Core Web Vitals 问题列表
 2. 每个问题的优化方案（含代码 Diff）
 3. 预期收益评估
-EOF
+EOF_GEMINI",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Gemini 前端性能分析"
+})
 ```
+
 2. 使用 `TaskOutput` 监控并获取 2 个模型的分析结果。

 **⚠️ 强制规则：必须等待 TaskOutput 返回两个模型的完整结果后才能进入下一阶段，禁止跳过或提前继续！**
@@ -138,4 +152,5 @@ EOF
 2. **性价比优先** – 高影响 + 低难度优先
 3. **不破坏功能** – 优化不能引入 bug
 4. **信任规则** – 后端以 Codex 为准，前端以 Gemini 为准
-5. **必须等待所有模型返回** – 禁止提前进入下一步
+5. **使用 Bash 工具的 `run_in_background: true` 参数 + `TaskOutput` 获取结果**
+6. **必须等待所有模型返回** – 禁止提前进入下一步
@@ -52,10 +52,12 @@ git status --short
 **并行调用两个模型**：

 **执行步骤**：
-1. 在**同一个 Bash 调用**中启动两个后台进程（不加 wait，立即返回）：
-```bash
-# Codex 后端审查
-~/.claude/bin/codeagent-wrapper --backend codex - "$PWD" <<'EOF' &
+1. 使用 **Bash 工具的 `run_in_background: true` 参数**启动两个后台进程：
+
+**Codex 审查进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend codex - \"$PWD\" <<'EOF_CODEX'
 [角色] 后端代码审查专家
 [任务] 审查以下代码变更

@@ -70,10 +72,17 @@ git status --short

 ## 输出格式
 按 Critical/Major/Minor/Suggestion 分类列出问题
-EOF
+EOF_CODEX",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Codex 后端代码审查"
+})
+```

-# Gemini 前端审查
-~/.claude/bin/codeagent-wrapper --backend gemini - "$PWD" <<'EOF' &
+**Gemini 审查进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend gemini - \"$PWD\" <<'EOF_GEMINI'
 [角色] 前端代码审查专家
 [任务] 审查以下代码变更

@@ -88,8 +97,13 @@ EOF

 ## 输出格式
 按 Critical/Major/Minor/Suggestion 分类列出问题
-EOF
+EOF_GEMINI",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Gemini 前端代码审查"
+})
 ```
+
 2. 使用 `TaskOutput` 监控并获取 2 个模型的审查结果。

 **⚠️ 强制规则：必须等待 TaskOutput 返回两个模型的完整结果后才能进入下一阶段，禁止跳过或提前继续！**
@@ -131,4 +145,5 @@ EOF
 1. **无参数 = 审查 git diff** – 自动获取当前变更
 2. **heredoc 语法** – 必须使用 `<<'EOF'` 传递多行任务
 3. **双模型交叉验证** – 后端问题以 Codex 为准，前端问题以 Gemini 为准
-4. **必须等待所有模型返回** – 禁止提前进入下一步
+4. **使用 Bash 工具的 `run_in_background: true` 参数 + `TaskOutput` 获取结果**
+5. **必须等待所有模型返回** – 禁止提前进入下一步
@@ -63,10 +63,12 @@ EOF
 **全栈代码并行调用**：

 **执行步骤**：
-1. 在**同一个 Bash 调用**中启动两个后台进程（不加 wait，立即返回）：
-```bash
-# Codex 后端测试调用
-~/.claude/bin/codeagent-wrapper --backend codex - $PWD <<'EOF' &
+1. 使用 **Bash 工具的 `run_in_background: true` 参数**启动两个后台进程：
+
+**Codex 测试生成进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend codex - \"$PWD\" <<'EOF_CODEX'
 你是后端测试专家，角色提示词见 ~/.claude/.ccg/prompts/codex/tester.md

 任务：为以下代码生成单元测试
@@ -76,10 +78,17 @@ EOF
 1. 使用项目现有测试框架
 2. 覆盖正常路径、边界条件、异常处理
 3. 输出完整测试代码
-EOF
+EOF_CODEX",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Codex 后端测试生成"
+})
+```

-# Gemini 前端测试调用
-~/.claude/bin/codeagent-wrapper --backend gemini - $PWD <<'EOF' &
+**Gemini 测试生成进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend gemini - \"$PWD\" <<'EOF_GEMINI'
 你是前端测试专家，角色提示词见 ~/.claude/.ccg/prompts/gemini/tester.md

 任务：为以下组件生成测试
@@ -89,8 +98,13 @@ EOF
 1. 使用项目现有测试框架
 2. 测试渲染、交互、状态变化
 3. 输出完整测试代码
-EOF
+EOF_GEMINI",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Gemini 前端测试生成"
+})
 ```
+
 2. 使用 `TaskOutput` 监控并获取 2 个模型的测试代码。

 **⚠️ 强制规则：必须等待 TaskOutput 返回两个模型的完整结果后才能进入下一阶段，禁止跳过或提前继续！**
@@ -145,4 +159,5 @@ EOF
 1. **测试行为，不测试实现** – 关注输入输出
 2. **智能路由** – 后端测试用 Codex，前端测试用 Gemini
 3. **复用现有模式** – 遵循项目已有的测试风格
-4. **必须等待所有模型返回** – 禁止提前进入下一步
+4. **使用 Bash 工具的 `run_in_background: true` 参数 + `TaskOutput` 获取结果**
+5. **必须等待所有模型返回** – 禁止提前进入下一步
@@ -66,26 +66,42 @@ description: '多模型协作开发工作流（研究→构思→计划→执行
 2. **Gemini 分析**：`~/.claude/.ccg/prompts/gemini/analyzer.md`

 **执行步骤**：
-1. 在**同一个 Bash 调用**中启动两个后台进程（不加 wait，立即返回）：
-```bash
-codeagent-wrapper --backend codex - $PWD <<'EOF' &
+1. 使用 **Bash 工具的 `run_in_background: true` 参数**启动两个后台进程：
+
+**Codex 分析进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend codex - \"$PWD\" <<'EOF_CODEX'
 ROLE_FILE: ~/.claude/.ccg/prompts/codex/analyzer.md
 <TASK>
 分析需求: <任务描述>
 Context: <项目上下文>
 </TASK>
 OUTPUT: 技术可行性、推荐方案、风险点
-EOF
+EOF_CODEX",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Codex 技术分析"
+})
+```

-codeagent-wrapper --backend gemini - $PWD <<'EOF' &
+**Gemini 分析进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend gemini - \"$PWD\" <<'EOF_GEMINI'
 ROLE_FILE: ~/.claude/.ccg/prompts/gemini/analyzer.md
 <TASK>
 分析需求: <任务描述>
 Context: <项目上下文>
 </TASK>
 OUTPUT: UI可行性、推荐方案、用户体验
-EOF
+EOF_GEMINI",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Gemini UI 分析"
+})
 ```
+
 2. 使用 `TaskOutput` 监控并获取 2 个后台进程的输出结果

 **⚠️ 强制规则：必须等待 TaskOutput 返回两个模型的完整结果后才能进入下一阶段，禁止跳过或提前继续！**
@@ -98,30 +114,45 @@ EOF

 `[模式：计划]` - 多模型协作规划：

-**并行调用 Codex 和 Gemini 进行架构规划**（使用后台进程 `&`）：
+**并行调用 Codex 和 Gemini 进行架构规划**：

 1. **Codex 规划**：`~/.claude/.ccg/prompts/codex/architect.md`
 2. **Gemini 规划**：`~/.claude/.ccg/prompts/gemini/architect.md`

-调用示例：
-```bash
-codeagent-wrapper --backend codex - $PWD <<'EOF' &
+调用示例（使用 `run_in_background: true`）：
+
+**Codex 规划进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend codex - \"$PWD\" <<'EOF_CODEX'
 ROLE_FILE: ~/.claude/.ccg/prompts/codex/architect.md
 <TASK>
 规划需求: <任务描述>
 Context: <项目上下文>
 </TASK>
 OUTPUT: 后端架构规划
-EOF
+EOF_CODEX",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Codex 后端架构规划"
+})
+```

-codeagent-wrapper --backend gemini - $PWD <<'EOF' &
+**Gemini 规划进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend gemini - \"$PWD\" <<'EOF_GEMINI'
 ROLE_FILE: ~/.claude/.ccg/prompts/gemini/architect.md
 <TASK>
 规划需求: <任务描述>
 Context: <项目上下文>
 </TASK>
 OUTPUT: 前端架构规划
-EOF
+EOF_GEMINI",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Gemini 前端架构规划"
+})
 ```

 使用 `TaskOutput` 获取 2 个模型的规划结果。
@@ -146,30 +177,45 @@ EOF

 `[模式：优化]` - 多模型并行审查：

-**并行调用 Codex 和 Gemini 进行代码审查**（使用后台进程 `&`）：
+**并行调用 Codex 和 Gemini 进行代码审查**：

 1. **Codex 审查**：`~/.claude/.ccg/prompts/codex/reviewer.md`
 2. **Gemini 审查**：`~/.claude/.ccg/prompts/gemini/reviewer.md`

-调用示例：
-```bash
-codeagent-wrapper --backend codex - $PWD <<'EOF' &
+调用示例（使用 `run_in_background: true`）：
+
+**Codex 审查进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend codex - \"$PWD\" <<'EOF_CODEX'
 ROLE_FILE: ~/.claude/.ccg/prompts/codex/reviewer.md
 <TASK>
 审查代码: <实施的代码变更>
 关注点: 安全性、性能、错误处理
 </TASK>
 OUTPUT: 审查意见
-EOF
+EOF_CODEX",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Codex 代码审查"
+})
+```

-codeagent-wrapper --backend gemini - $PWD <<'EOF' &
+**Gemini 审查进程**：
+```
+Bash({
+  command: "~/.claude/bin/codeagent-wrapper --backend gemini - \"$PWD\" <<'EOF_GEMINI'
 ROLE_FILE: ~/.claude/.ccg/prompts/gemini/reviewer.md
 <TASK>
 审查代码: <实施的代码变更>
 关注点: 可访问性、设计一致性、用户体验
 </TASK>
 OUTPUT: 审查意见
-EOF
+EOF_GEMINI",
+  run_in_background: true,
+  timeout: 600000,
+  description: "Gemini 代码审查"
+})
 ```

 使用 `TaskOutput` 获取 2 个模型的审查结果。
@@ -192,7 +238,7 @@ EOF
 ## 关键规则

 1. 阶段顺序不可跳过（除非用户明确指令）
-2. **多模型调用必须使用后台进程 `&` + `TaskOutput` 获取结果**
+2. **多模型调用必须使用 Bash 工具的 `run_in_background: true` 参数 + `TaskOutput` 获取结果**
 3. **必须等待所有模型返回完整结果后才能进入下一阶段**，禁止跳过或提前继续
 4. 外部模型对文件系统**零写入权限**，所有修改由 Claude 执行
 5. 评分 <7 分或用户未批准时**强制停止**