ccgx-workflow 2.4.1 → 2.5.0

package/README.zh-CN.md

@@ -5,30 +5,15 @@
 [![npm version](https://img.shields.io/npm/v/ccgx-workflow.svg)](https://www.npmjs.com/package/ccgx-workflow)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Compatible-green.svg)](https://claude.ai/code)
-[![Tests](https://img.shields.io/badge/Tests-1309%20passed-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/Tests-1772%20passed-brightgreen.svg)]()
 
 简体中文 | [English](./README.md)
 
 </div>
 
-> **项目沿革**
->
-> `ccgx-workflow` 由 [`ccg-workflow`](https://www.npmjs.com/package/ccg-workflow) v3.x
-> 深度 rewrite 而来。原项目在 2026-05 后停止更新且作者主页失联，社区用户
-> 依赖的多模型协作工作流面临断维风险。本项目从 v4.0 起完全重新设计：
-> fresh-context subagent 协议、Plan-Critic-Verify 三档质量门、OS 级三层
-> 进程隔离、broker tx_id 防漂移、8 处 plugin patch 与一键 repatch 脚本。
->
-> `/ccg:*` 命令面板对老用户**手势兼容**，但底层架构已完全不同。
-> 原项目 MIT 许可下的代码与版权完整保留，详见 [LICENSE](./LICENSE)。
-
----
-
 ## 这是什么
 
-Claude Code 编排 Codex（后端）+ Gemini（前端）的多模型协作开发系统。前端任务自动路由 Gemini，后端任务自动路由 Codex，Claude 负责编排决策与代码审核。
-
-外部模型**无写入权限**——它们只返回 patch，由 Claude 审核后落地。
+Claude Code 编排 Codex（后端）+ Gemini（前端）的多模型协作开发系统。前端任务自动路由 Gemini，后端任务自动路由 Codex，Claude 负责编排决策与代码审核。外部模型**无写入权限**——它们只返回 patch，由 Claude 审核后落地。
 
 ```
 Claude Code (编排)
@@ -43,15 +28,24 @@ Codex   Gemini
   Unified Patch
 ```
 
+> **项目沿革**：`ccgx-workflow` 由 [`ccg-workflow`](https://www.npmjs.com/package/ccg-workflow) 从零 rewrite 而来——分叉点为 2026-05 的 v3.x 版本线。上游项目此后仍在独立维护、持续发版，两个项目各自演进。`/ccg:*` 命令面板对老用户手势兼容，但底层架构已完全替换。原项目 MIT 许可下的代码与版权完整保留，详见 [LICENSE](./LICENSE)。
+> 深度对比：[docs/VS-CCG-WORKFLOW.zh-CN.md](./docs/VS-CCG-WORKFLOW.zh-CN.md) · 迁移指南：[MIGRATION-FROM-CCG-WORKFLOW.md](./MIGRATION-FROM-CCG-WORKFLOW.md)
+
+---
+
 ## 核心特性
 
-- **零配置模型路由** — 前端 → Gemini / 后端 → Codex，按 phase frontmatter 的 `Type:` 字段自动派发，无需手动切换
-- **~30 个 `/ccg:*` 斜杠命令** — 从规划到执行、Git 工作流到代码审查、自治长跑、异步任务三件套
-- **三档质量门** — `--quality=fast|triple|debate` 单一开关切换 Plan-Critic-Verify 协作深度
+- **零配置模型路由** — 前端 → 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 摘要
-- **OS 级三层进程隔离** — `Bash(claude -p --agent ccg/phase-runner)` 替代主进程内 sidechain，治理主进程 RSS 泄漏
-- **OPSX 规范驱动** — 集成 [OPSX](https://github.com/fission-ai/opsx)，把模糊需求变成可验证约束，让 AI 没法自由发挥
-- **plugin 优先 + wrapper fallback** — codex/gemini 官方 plugin 装了走 plugin spawn，没装回退 `codeagent-wrapper`
+- **OPSX 规范驱动** — 集成 [OpenSpec (OPSX)](https://github.com/Fission-AI/OpenSpec)，把模糊需求变成可验证约束
+- **plugin 优先 + 按模型降级** — codex/gemini plugin 装了走 plugin 直连（Channel A）；缺哪个模型只降级哪个到 Node shim CLI 路径（Channel B），绝非全有或全无
 
 ---
 
@@ -63,14 +57,10 @@ Codex   Gemini
 |------|------|------|
 | **Node.js 20+** | 是 | `ora@9.x` 要求 Node ≥ 20 |
 | **Claude Code CLI** | 是 | [安装方法](#安装-claude-code) |
-| **jq** | 是 | 自动授权 Hook 依赖（[安装方法](#安装-jq)） |
 | **codex 接入** | **二选一** | `codex@openai-codex` plugin（推荐）**或** `npm i -g @openai/codex` |
-| **gemini 接入** | **二选一** | `gemini@google-gemini` plugin（推荐）**或** `npm i -g @google/gemini-cli` |
+| **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` shim 启动独立 CLI。两条路
-> **任一**没装的，对应 `/ccg:*` 命令在调 codex/gemini 时会以 exit 127 退出并打印
-> 安装提示。
+> **为什么是「选一」**：ccgx-workflow 优先走 plugin（Claude Code 一键装、内置鉴权）。plugin 没装时，仅该模型降级到 `~/.claude/bin/codeagent-wrapper` Node shim 启动独立 CLI。两条路**都**没装时，对应 `/ccg:*` 命令在调 codex/gemini 时会以 exit 127 退出并打印安装提示。
 
 ### 一键安装
 
@@ -80,22 +70,6 @@ npx ccgx-workflow
 
 首次运行会提示选择语言（简体中文 / English）、API 提供方、MCP 工具，全部交互式完成。CLI 命令名仍为 `ccg`（保持老用户肌肉记忆）。
 
-### 安装 jq
-
-```bash
-# macOS
-brew install jq
-
-# Linux (Debian/Ubuntu)
-sudo apt install jq
-
-# Linux (RHEL/CentOS)
-sudo yum install jq
-
-# Windows
-choco install jq   # 或: scoop install jq
-```
-
 ### 安装 Claude Code
 
 ```bash
@@ -108,267 +82,134 @@ npx ccgx-workflow menu  # 选择「安装 Claude Code」
 
 ## 启用多模型协作（codex / gemini 接入）
 
-ccgx-workflow 需要 codex + gemini 接入，每个走 **两条路之一**：
-
-### 路径 A — Claude Code plugin（推荐）
+### codex — plugin（推荐）或 CLI
 
 在 Claude Code 内执行：
 
 ```
 /plugin install codex@openai-codex
-/plugin install gemini@google-gemini
 ```
 
-一键安装，鉴权由 Claude Code 接管。模板直接 spawn plugin agent
-（`Agent(codex:codex-rescue)` / `Agent(gemini:gemini-rescue)`），不经过 shim。
-
-### 路径 B — 独立 CLI fallback
+或独立 CLI：
 
 ```bash
-# codex CLI
 npm i -g @openai/codex
 codex login
-
-# gemini CLI
-npm i -g @google/gemini-cli
-gemini auth login
 ```
 
-plugin 没装时，模板通过 `~/.claude/bin/codeagent-wrapper`（一个调 `codex` /
-`gemini` 的 Node shim）落地。鉴权 key 自己配。
-
-### 混搭
-
-可以 codex 走 plugin、gemini 走 CLI，反之亦然。ccgx-workflow 每次调用独立检测，
-按可用路径择优。
+### gemini — ccgx fork plugin（推荐）
 
-`@` 后是 marketplace identifier。如果提示 marketplace 未配置，在 Claude Code 里执行 `/help plugin` 查看本地 marketplace 管理命令，或参考 [Claude Code plugin 官方文档](https://docs.claude.com/en/docs/claude-code/plugins)。
-
-> 上游 plugin 仓库地址（用于排错 / 提 issue）：
-> - **codex**: `openai-codex` marketplace（Claude Code 官方）
-> - **gemini**: [sakibsadmanshajib/gemini-plugin-cc](https://github.com/sakibsadmanshajib/gemini-plugin-cc)
-
-### 验证安装
+gemini 的推荐路径是 ccgx 维护的 fork [`wzyxdwll/gemini-plugin-cc`](https://github.com/wzyxdwll/gemini-plugin-cc)（插件标识 `gemini@gemini-ccgx`，v1.2.0；要求 Node.js ≥ 18.18 + Google 账号或 `GEMINI_API_KEY`）：
 
 ```bash
-ls ~/.claude/plugins/cache/openai-codex/codex/
-ls ~/.claude/plugins/cache/google-gemini/gemini/
-# 应能看到版本目录（如 1.0.4 / 1.0.1）
+# 终端中执行
+claude plugin marketplace add wzyxdwll/gemini-plugin-cc
+claude plugin install gemini@gemini-ccgx
 ```
 
-### ⚠️ Gemini plugin Windows 已知问题（强烈建议 patch）
+然后在 Claude Code 内执行 `/reload-plugins` 和 `/gemini:setup`。
 
-`gemini@google-gemini` v1.0.1 在 Windows 上有 **8 处 spawn 缺 `windowsHide: true`** 的 bug，会导致：
+fork 相对上游插件的价值：
 
-- 调用时短暂闪现 cmd 黑窗、抢应用焦点（高频）
-- 底层 ACP broker spawn `gemini.cmd` 时 ENOENT 报错（被 plugin 错误处理路径序列化为 `[object Object]`）
-- broker daemon 启动 / `gemini --version` 健康检查 / `taskkill` / `where gemini` 等环节都会闪框
+- **全部已记录补丁已作为永久 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 首次冷启动
 
-**ccgx-workflow 内置一键 repatch 脚本**（幂等，可重复运行）：
+#### 备选路径：上游插件 + repatch
 
 ```bash
-node ~/.claude/.ccg/scripts/repatch-gemini-plugin.mjs
+claude plugin marketplace add sakibsadmanshajib/gemini-plugin-cc
+claude plugin install gemini@google-gemini
 ```
 
-脚本行为：
-1. 自动定位 plugin 版本目录
-2. 检查每处 patch 状态（probe 字符串匹配）
-3. 已 patch 的 [SKIP]，未 patch 的 [APPLY]
-4. 完成后提示重启 broker daemon 命令
-
-⚠️ **重要**：每次 `claude plugin update gemini@google-gemini` 后 plugin update 会覆盖 cache，**必须重跑 patch 脚本**。
+上游 v1.0.1 在 Windows 上有 **8 处 spawn 缺 `windowsHide: true`**（cmd 黑窗闪现、抢焦点、ACP broker ENOENT）。仅当使用上游插件时，安装后**以及每次 plugin update 后**（更新会覆盖 cache）需运行随包提供的 repatch 脚本：
 
-⚠️ **patch 后重启 broker daemon**（旧 daemon 仍跑未 patch 代码）：
-
-```powershell
-# Windows PowerShell
-Get-CimInstance Win32_Process -Filter "Name='node.exe'" |
-  Where-Object { $_.CommandLine -match 'acp-broker' } |
-  ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
+```bash
+# 脚本随 npm 包发布，位于 templates/scripts/repatch-gemini-plugin.mjs
+# npm 全局安装时：
+node "$(npm root -g)/ccgx-workflow/templates/scripts/repatch-gemini-plugin.mjs"
 ```
 
-或简单点：`/plugin disable gemini@google-gemini` 然后 `/plugin enable gemini@google-gemini`。
+脚本幂等：已 patch 的打 `[SKIP]`，未 patch 的打 `[APPLY]`；完成后需重启 broker daemon（或 `/plugin disable` + `/plugin enable`）。根因与补丁细节见 [`.ccg-migration/PLUGIN-PATCHES.md`](./.ccg-migration/PLUGIN-PATCHES.md)。截至目前，上游尚未修复任何已记录问题。
 
-8 处 bug 的根因 + 临时 patch + 永久路径全部归档在 [`.ccg-migration/PLUGIN-PATCHES.md`](./.ccg-migration/PLUGIN-PATCHES.md)。上游 PR 准备中，合并后此 patch 自动失效。
+#### CLI fallback
 
----
-
-## 与 ccg-workflow 的关系
-
-ccgx-workflow **不是 fork**——上游 `ccg-workflow` 公开版本截止在 v3.x，2026-05 后停更；本项目的 v1.0 是基于 v3.x 之上从零重新设计的独立产品（内部经历约 3 天 / 92 commit / 1141 个新测试的密集迭代后定稿）。
-
-### 新增功能与特性
+```bash
+npm i -g @google/gemini-cli
+gemini   # 首次交互式启动时完成 Google 账号认证；或设置 GEMINI_API_KEY
+```
 
-#### 🆕 新增命令（vs v3.x）
+### 混搭与验证
 
-| 命令 | 说明 |
-|------|------|
-| `/ccg:debate` | **多轮辩论原语**——codex propose ↔ gemini challenge ↔ codex respond，cap N 轮，schema 硬校验 retry protocol |
-| `/ccg:status [job-id]` | **异步任务三件套之一**——dashboard 模式聚合多 phase 进度 / `--wait --timeout-ms` 阻塞 / `--tail` 流式 + 3 类卡点警告 |
-| `/ccg:status --cancel <phase-id>` | 单 phase cooperative cancel + grace + kill-tree 强杀（Windows `taskkill /T /F` + POSIX `setsid` 进程组） |
-| `/ccg:result <job-id>` | 取最终 verdict / summary / artifacts，主线接 ≤200 token 摘要 |
-| `/ccg:cancel <job-id>` | 中止活跃 job，写 `cancel.flag` cooperative → 5s grace → kill-tree |
-| `/ccg:verify --gate=<name>` | **统一 verify 入口**——合并 v3.x 的 `verify-{change,quality,security,module}` 4 个独立命令，加 `--gate=all` 自动多门串联 |
-| `/ccg:verify-work` | **会话式 UAT + cold-start smoke 注入**——UAT.md 跨 `/clear` 持久 frontmatter + git diff 扫 server/db/migrations 自动注入冷启动测试 |
-
-#### 🚀 增强命令（vs v3.x）
-
-| 命令 | v3.x | ccgx-workflow |
-|------|------|---------------|
-| `/ccg:autonomous` | 串行 phase | **wave 拓扑分波并行** + cascade skip + max-concurrent batching；`--quality=fast/triple/debate` 三档质量门 + per-phase frontmatter override |
-| `/ccg:review` | 双模型审查 | 加 `--fix --auto` worktree 隔离闭环修复（4 步事务清理：merge/remove/branch -D/rm sentinel） |
-| `/ccg:debug` | 单步诊断 | manager + debugger **双层 fresh-context**——多轮 falsifiable hypothesis + 持久 session 在 `.context/debug/<slug>.md` |
-| `/ccg:team` | 4 独立命令 | 8 阶段统一工作流（research→plan→exec→review→fix→integrate）+ 7 角色自动编排 + Evaluator-Optimizer 反馈环（最多 2 轮自动修复 Critical） |
-
-#### 🤖 新增 Agent（vs v3.x 的 7 个）
-
-**fresh-context 协议组**（4 个，主线只接 ≤200 token 摘要）：
-
-| Agent | 职责 |
-|-------|------|
-| `phase-runner` | 自治长跑 phase 实施者——`Bash(claude -p --agent ccg/phase-runner)` 启 OS 级子进程，stream-json 流式输出落 `.context/jobs/<id>/progress.jsonl` |
-| `code-fixer` | review --fix 闭环修复——git worktree 隔离 + 3 层 verification + 原子 commit |
-| `debug-session-manager` | debug 多轮编排——隔离 context 跑 hypothesis 调试循环，主线接 ≤200 token 摘要 |
-| `debugger` | 科学方法 hypothesis 构造——受 manager 调度的纯诊断 specialist |
-
-**specialist 矩阵**（8 个，role × layer 2D 分发）：
-
-| Agent | 职责 |
-|-------|------|
-| `assumptions-analyzer` | 假设审问官——强制 first-principles，列无证据推断 + 证据缺口 |
-| `pattern-mapper` | 模式映射——实施前扫描代码库现有模式，给 builder "照抄哪里"的精确锚点 |
-| `plan-checker` | 计划核验——5 维度强校验 GSD 高 ROI 子集 + max-3-loop 收敛环；BLOCKER 退回 planner |
-| `nyquist-auditor` | 深度审计——专攻边界、并发竞争、错误传播链、资源泄漏 |
-| `verifier` | 交付核验——逐条对照需求清单，输出 PASS/FAIL/PARTIAL 矩阵 + Level 4 数据流（FLOWING/STATIC/DISCONNECTED/HOLLOW_PROP） |
-| `integration-checker` | 跨模块接口契约——找格式漂移 / 调用方未更新 / 孤立导出 |
-| `framework-selector` | 技术选型评审——现状 vs 提案对比，强制验证现状不能解决才能进 |
-| `eval-auditor` | 评估闭环审计——抽样 / 对照 / 指标博弈 / 结论可证伪性审计 |
-
-加上 v3.x 已有的 7 个核心 agent（planner / ui-ux-designer / init-architect / get-current-datetime / team-architect / team-qa / team-reviewer），ccgx-workflow 共 **19 个 subagent**。
-
-#### 🔧 新增机制 / 基础设施
-
-| 机制 | 说明 |
-|------|------|
-| **三档质量门** | `--quality=fast`（2 wave / impl + verify）/ `triple`（4 wave / plan + critic + impl + verify，默认）/ `debate`（7 wave / + 3 round propose-challenge-respond，cap 3） |
-| **wave 拓扑调度** | Kahn 拓扑分波 + cascade skip + max-concurrent batching，墙钟压缩 30-40%，`--sequential` opt-out |
-| **OS 级三层进程隔离** | 主 claude.exe → `Bash(claude -p)` 子进程 → 可选 plugin 进程组；治理 v3.x 主进程 RSS 泄漏（uni-iam 实测撞 23GB → ccgx 设计目标 < 8GB） |
-| **broker tx_id 防漂移** | 每次 spawn 注入 `CCG_BROKER_TX_ID` (crypto.randomUUID)，broker.log 8 字段强 schema；100k spawn 0 碰撞 / 2k concurrent 0 misattribution（实测） |
-| **`context_budget` frontmatter 硬约束** | 4 主编排器声明 `context_budget: orchestrator-15`，禁止 slurp builder stdout |
-| **`.context/<phase>/{CONTEXT,SUMMARY}.md`** | phase-scoped 状态机，主线只读 frontmatter（< 200 tokens/phase） |
-| **`.context/codebase/` 七文件契约** | codebase-mapper agent 4 路并行扫描产出（STACK/INTEGRATIONS/ARCHITECTURE/STRUCTURE/CONVENTIONS/TESTING/CONCERNS） |
-| **silent fallback 治理** | verify wave Bash 直调（架构性消除）+ debate retry protocol schema 硬校验（4 类违规枚举：parse-failed / insufficient-attempts / missing-reason / silent-success） |
-| **scope reduction detection** | plan-checker 维度 7b——识别 "v1 / 简化 / 静态先 / 后续连接" 关键词 + 与原始需求 80% 重叠匹配，BLOCKER 拦截 |
-| **commit-msg-review git hook** | opt-in pre-commit-msg hook，3 启发式（文件名 ⊆ staged / phase tag ↔ staged paths / 操作类型 ↔ diff） |
-| **ground-truth-sampler** | autonomous 启动时动态采样 plugin/skill/agent 列表写 `.context/ground-truth/latest.json`，phase-runner prompt 强约束必须 Read 之 |
-| **interface-auditor specialist** | autonomous verify wave triple/debate 档加 3rd spawn——5 检查清单 SSoT-violation / leftover / magic-string-vs-ground-truth / 未验证假设 / API drift |
-| **Gemini plugin Windows repatch** | `~/.claude/.ccg/scripts/repatch-gemini-plugin.mjs` 一键 patch 8 处 spawn bug，幂等可重跑 |
-| **fixtures 自动生成** | `scripts/regen-fixtures.ts` + `tests/fixtures/ground-truth/*.sample.json`，防 inline mock 偏离真实接口 |
-| **pipeline-check helper** | `pnpm pack` + tarball audit + 漏文件检测，防"templates 在 git 但 npm 包漏装"事故 |
-
-#### 📦 Skill 体系
-
-ccgx-workflow 沿用 v3.x 引入的 **Skill Registry**（SKILL.md frontmatter 驱动自动命令生成），技能体系为：
-
-- **质量关卡** 4 个：verify-{change, quality, security, module}（合并到 `/ccg:verify` 后仍可作 skill 单独触发）
-- **工具 skill** 6 个：gen-docs / health / map-codebase / extract-learnings / forensics / override-refusal
-- **域知识秘典** 10 大领域 ~21 个 SKILL.md（security / architecture / devops / ai / development / frontend-design 等，全 `user-invocable: false`，关键词路由触发自动 Read）
-- **Impeccable UI/UX 工具集** 20 个（adapt / animate / arrange / audit / bolder / clarify / colorize / critique / delight / distill / extract / harden / normalize / onboard / optimize / overdrive / polish / quieter / typeset 等，可选安装）
-- **scrapling**：网页抓取 skill，支持 Cloudflare / WAF 绕过
-- **orchestration/multi-agent**：多 agent 协作 SKILL
-
-合计 **47 个 SKILL.md** + 50 余个辅助 md = 100+ 技能文件。
-
-### 总览对比表
-
-下表是核心差异：
-
-| 维度 | 原版 `ccg-workflow` v3.x | `ccgx-workflow` v1.0 |
-|------|--------------------------|----------------------|
-| 维护状态 | 2026-05 起停更，作者主页失联 | 持续维护，接受 PR |
-| 主线 context 治理 | 无显式约束 | `context_budget` frontmatter 硬约束 + fresh-context subagent 协议 |
-| 多模型质量门 | 单一编排 | **三档可调** `--quality=fast/triple/debate` (Plan-Critic-Verify) |
-| 自治长跑 | 串行 phase | **wave 拓扑分波并行** + cascade skip + cap 调度 |
-| 进程隔离 | 主进程内 sidechain | **OS 级三层** (`Bash(claude -p)` 子进程 + plugin 进程组) |
-| broker 防漂移 | — | **broker tx_id** 加密签 + 8 字段强 schema |
-| Gemini Windows patch | 用户手动改 8 处源码 | **内置一键 repatch 脚本**，幂等可重跑 |
-| Silent fallback 治理 | — | verify wave Bash 直调 + debate retry protocol schema 硬校验 |
-| 测试规模 | 168 | **1309** |
-| 命令面板 | 35（含已弃用） | ~30（合并 + 收敛） |
-| Subagent | 7 | **19**（fresh-context 协议 4 个 + specialist 矩阵 8 个） |
-| 二进制依赖 | Go binary 16.3 MB | **Node 单文件 ~200 KB** |
-| 协议 | MIT | MIT（保留原作者署名 + 维护人双 copyright） |
-| `/ccg:*` 命令面板 | — | **完全兼容**，老用户零迁移成本 |
-
-### 老用户迁移
-
-详见 [MIGRATION-FROM-CCG-WORKFLOW.md](./MIGRATION-FROM-CCG-WORKFLOW.md)。一句话版：
+检测是**按模型独立**的：可以 codex 走 plugin、gemini 走 CLI，反之亦然——缺哪个 plugin 只降级哪个模型到 Channel B。查看当前走哪条通道：
 
 ```bash
-npm uninstall -g ccg-workflow            # 如有全局安装
-npx ccgx-workflow                        # 重新初始化
+node ~/.claude/.ccg/scripts/check-plugins.cjs
+# exit 0 = 双 plugin 已装（Channel A）
+# exit 1 = 至少缺一个（缺失模型走 Channel B fallback）
+# exit 2 = plugin registry 不可读（Channel B）
 ```
 
-`/ccg:*` 命令、`.context/` 状态、`.ccg/roadmap.md` 全部兼容，无需改代码或重建项目状态。
+`@` 后是 marketplace identifier。如果提示 marketplace 未配置，在 Claude Code 里执行 `/help plugin`，或参考 [Claude Code plugin 官方文档](https://docs.claude.com/en/docs/claude-code/plugins)。
 
 ---
 
 ## 命令清单
 
+下表中 `Codex` / `Gemini` 为默认路由，均可在 init 时配置。
+
 ### 开发工作流
 
 | 命令 | 说明 | 模型 |
 |------|------|------|
-| `/ccg:workflow` | 完整 6 阶段工作流（智能路由前端/后端） | Codex + Gemini |
-| `/ccg:plan` | 多模型协作规划（Phase 1-2） | Codex + Gemini |
-| `/ccg:execute` | 多模型协作执行（Phase 3-5） | Codex + Gemini + Claude |
-| `/ccg:codex-exec` | Codex 全权执行计划（plan → code → review） | Codex + 多模型审核 |
-| `/ccg:autonomous` | 跨 phase 自治长跑（`--quality=fast/triple/debate`） | phase-runner + Plan-Critic-Verify |
-| `/ccg:context` | 项目上下文管理（.context/ 初始化、日志、压缩、历史） | Claude |
-| `/ccg:enhance` | 内置 Prompt 增强 | Claude |
+| `/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 |
-| `/ccg:debug` | 问题诊断 + 修复（manager + debugger 双层 fresh-context） | debug-session-manager |
-| `/ccg:optimize` | 性能优化 | Codex + Gemini |
-| `/ccg:test` | 测试生成 | 智能路由 |
-| `/ccg:review` | 代码审查（自动 git diff + `--fix --auto` worktree 闭环修复） | Codex + Gemini + code-fixer |
-| `/ccg:verify --gate=<change\|quality\|security\|module\|all>` | 统一 verify 入口 | Claude |
-| `/ccg:verify-work` | 编排器 + 会话式 UAT + cold-start smoke | Claude |
-| `/ccg:debate` | 多轮 propose/challenge/respond 原语（cap N 轮） | Codex + Gemini |
+| `/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]` | 列表 / 单查 job（`--wait --timeout-ms` 阻塞；dashboard 模式聚合多 phase 进度） |
-| `/ccg:status --tail <job-id>` | stream-json 流式 + 单行覆盖 + 3 类卡点警告 |
-| `/ccg:status --cancel <phase-id>` | 单 phase cooperative cancel + grace + kill-tree |
-| `/ccg:result <job-id>` | 取最终 verdict / summary / artifacts |
-| `/ccg:cancel <job-id>` | 中止活跃 job |
+| `/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` | 初始化 OPSX 环境 |
-| `/ccg:spec-research` | 需求 → 约束集 |
-| `/ccg:spec-plan` | 约束 → 零决策可执行计划 |
-| `/ccg:spec-impl` | 按规范执行 + 归档 |
-| `/ccg:spec-review` | 双模型交叉审查 |
+| `/ccg:spec-init` | 初始化 OpenSpec (OPSX) 环境 + 验证多模型 MCP 工具 |
+| `/ccg:spec-research` | 需求 → 约束集（并行探索 + OPSX 提案） |
+| `/ccg:spec-plan` | 多模型分析 → 消除歧义 → 零决策可执行计划 |
+| `/ccg:spec-impl` | 按规范执行 + 多模型协作 + 归档 |
+| `/ccg:spec-review` | 双模型交叉审查（独立工具，随时可用） |
 
-### Agent Teams 并行实施
+### Agent Teams
 
 | 命令 | 说明 |
 |------|------|
-| `/ccg:team` | **统一工作流（推荐）** — 8 阶段 7 角色全流程 |
-| `/ccg:team research <args>` | 需求 → 约束（子命令） |
-| `/ccg:team plan <args>` | 约束 → 并行实施计划 |
-| `/ccg:team review [git-range]` | 双模型交叉审查 |
-| `/ccg:team-exec` | spawn Builder teammates 并行写代码 |
+| `/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`。
 
@@ -376,16 +217,16 @@ npx ccgx-workflow                        # 重新初始化
 
 | 命令 | 说明 |
 |------|------|
-| `/ccg:commit` | 智能 conventional commit |
-| `/ccg:rollback` | 交互式回滚 |
-| `/ccg:clean-branches` | 清理已合并分支 |
-| `/ccg:worktree` | Worktree 管理 |
+| `/ccg:commit` | 智能 Git 提交：分析改动生成 Conventional Commit 信息，支持拆分建议 |
+| `/ccg:rollback` | 交互式 Git 回滚：安全回滚分支到历史版本，支持 reset/revert 模式 |
+| `/ccg:clean-branches` | 清理 Git 分支：安全清理已合并或过期分支，默认 dry-run 模式 |
+| `/ccg:worktree` | 管理 Git Worktree：在 `../.ccg/项目名/` 目录创建，支持 IDE 集成和内容迁移 |
 
 ### 项目初始化
 
 | 命令 | 说明 |
 |------|------|
-| `/ccg:init` | 初始化项目 CLAUDE.md |
+| `/ccg:init` | 初始化项目 AI 上下文：生成根级与模块级 CLAUDE.md 索引 |
 
 ---
 
@@ -395,29 +236,43 @@ npx ccgx-workflow                        # 重新初始化
 
 ```
 ~/.claude/
-├── commands/ccg/       # ~30 斜杠命令
-├── agents/ccg/         # 19 子智能体
-├── skills/ccg/         # 质量关卡 + 10 域知识 + impeccable + 编排
-├── bin/codeagent-wrapper  # fallback 路径（plugin 未装时启用）
+├── 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/
-    │   └── repatch-gemini-plugin.mjs   # ⭐ 一键 patch
+    │   ├── 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/
-        ├── codex/      # 6 个 Codex 专家提示词
-        └── gemini/     # 7 个 Gemini 专家提示词
+        ├── claude/    # 6 个 Claude 专家提示词
+        ├── codex/     # 6 个 Codex 专家提示词
+        └── gemini/    # 7 个 Gemini 专家提示词
 ```
 
 ### 环境变量
 
-`~/.claude/settings.json` 的 `"env"` 段：
+`~/.claude/settings.json` 的 `"env"` 段。以下变量仅在 **Channel B**（wrapper / `invoke-model.mjs` 路径）生效：
 
 | 变量 | 说明 | 默认 | 何时调整 |
 |------|------|------|----------|
-| `CODEAGENT_POST_MESSAGE_DELAY` | Codex 完成后等待秒数 | `5` | Codex 进程挂起时设为 `1` |
-| `CODEX_TIMEOUT` | wrapper 执行超时（秒） | `7200` | 长任务时增大 |
-| `BASH_DEFAULT_TIMEOUT_MS` | Claude Code Bash 超时（ms） | `120000` | 命令超时时增大 |
-| `BASH_MAX_TIMEOUT_MS` | Claude Code Bash 最大超时（ms） | `600000` | 长 build 时增大 |
+| `CODEAGENT_POST_MESSAGE_DELAY` | Codex 完成后等待秒数；非法值回退 5，上限 60 | `5` | Codex 进程挂起时设为 `1` |
+| `CODEX_TIMEOUT` | 执行超时（秒） | `7200` | 长任务时增大 |
 
 ### MCP
 
@@ -425,12 +280,19 @@ npx ccgx-workflow                        # 重新初始化
 npx ccgx-workflow menu  # 选择「配置 MCP」
 ```
 
-**代码检索**（择一）：
-- **fast-context**（推荐）— Windsurf Fast Context，AI 驱动搜索，免索引
-- **ace-tool** — `search_context` 代码搜索（[官方](https://augmentcode.com/) / [第三方代理](https://acemcp.heroman.wtf/)）
-- **ContextWeaver** — 本地混合搜索，需要 SiliconFlow API Key（免费）
+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 检索配置。
 
-**可选**：Context7（自动安装，库文档）/ Playwright（浏览器自动化）/ DeepWiki / Exa。
+另有辅助工具 MCP（Playwright / DeepWiki / Exa）可随时通过 `npx ccgx-workflow menu` →「配置 MCP」→ 辅助工具安装。
 
 ---
 
@@ -450,23 +312,23 @@ npm uninstall -g ccgx-workflow       # npm 全局用户额外执行
 
 ## FAQ
 
-### Codex CLI 0.80.0 进程不退出
+### Codex CLI 进程不退出
 
-`--json` 模式下 Codex 输出完成后不会自动退出。
+`--json` 模式下部分 Codex CLI 版本（如 0.80.0）输出完成后不会自动退出。仅影响 Channel B（CLI fallback）。
 
-**修复**：`CODEAGENT_POST_MESSAGE_DELAY=1`。
+**修复**：设置 `CODEAGENT_POST_MESSAGE_DELAY=1`。
 
 ### 我之前用 ccg-workflow，能直接用 ccgx-workflow 吗
 
-可以。`/ccg:*` 命令面板完全兼容，`.context/` 状态、`.ccg/roadmap.md` 全部兼容。详见 [MIGRATION-FROM-CCG-WORKFLOW.md](./MIGRATION-FROM-CCG-WORKFLOW.md)。
+可以。`/ccg:*` 命令面板完全兼容，`.context/` 状态、`.ccg/roadmap.md` 全部兼容。详见 [MIGRATION-FROM-CCG-WORKFLOW.md](./MIGRATION-FROM-CCG-WORKFLOW.md) 与[深度对比](./docs/VS-CCG-WORKFLOW.zh-CN.md)。
 
 ### 为什么 CLI 命令叫 `ccg` 不叫 `ccgx`
 
 保留 `ccg` 是为了让老用户的 alias / 脚本 / 文档零成本迁移——`/ccg:*` 命令面板和 `ccg` CLI 都是肌肉记忆。包名 `ccgx-workflow` 用于消歧 npm 命名空间，CLI 名字仍是 `ccg`。
 
-### Gemini plugin patch 上游修了之后我怎么办
+### fork 插件（`gemini@gemini-ccgx`）和上游插件（`gemini@google-gemini`）选哪个
 
-ccgx-workflow 会持续跟踪上游 plugin 版本。修复合并到上游后，repatch 脚本会通过 probe 检测自动跳过已修复条目（[SKIP]），无副作用。届时也会发布 ccgx-workflow 版本注明"上游已修，patch 转 no-op"。
+选 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`](./.ccg-migration/PLUGIN-PATCHES.md)。
 
 ---
 
@@ -489,8 +351,8 @@ ccgx-workflow 站在 ccg-workflow 之上，对原作者 fengshao1227 与上游
 
 ## License
 
-MIT — 详见 [LICENSE](./LICENSE)（保留原作者 fengshao1227 与 fork 维护人 wangzy 双 copyright）
+MIT — 详见 [LICENSE](./LICENSE)（保留原作者 fengshao1227 与维护人 wangzy 双 copyright）
 
 ---
 
-v1.0.0 | [Issues](https://github.com/wzyxdwll/ccgx-workflow/issues) | [Migration from ccg-workflow](./MIGRATION-FROM-CCG-WORKFLOW.md)
+v2.5.0 | [Issues](https://github.com/wzyxdwll/ccgx-workflow/issues) | [与 ccg-workflow 对比](./docs/VS-CCG-WORKFLOW.zh-CN.md) | [从 ccg-workflow 迁移](./MIGRATION-FROM-CCG-WORKFLOW.md)

package/dist/chunks/version-build.mjs

@@ -1,3 +1,3 @@
-const BUILD_TIME_VERSION = "2.4.1";
+const BUILD_TIME_VERSION = "2.5.0";
 
 export { BUILD_TIME_VERSION };

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import cac from 'cac';
 import ansis from 'ansis';
-import { d as diagnoseMcpConfig, i as isWindows, r as readClaudeCodeConfig, f as fixWindowsMcpConfig, w as writeClaudeCodeConfig, a as readCcgConfig, b as initI18n, c as i18n, s as showMainMenu, e as init, g as configMcp, v as version } from './shared/ccgx-workflow.j1spUsik.mjs';
+import { d as diagnoseMcpConfig, i as isWindows, r as readClaudeCodeConfig, f as fixWindowsMcpConfig, w as writeClaudeCodeConfig, a as readCcgConfig, b as initI18n, c as i18n, s as showMainMenu, e as init, g as configMcp, v as version } from './shared/ccgx-workflow.CdHnJLak.mjs';
 import { execSync } from 'node:child_process';
 import 'inquirer';
 import 'ora';