codingsamss/cc-codex-review

CC-Codex 协作讨论 Skill

通过 CodexMCP 实现 Claude Code 与 Codex 的话题驱动协作讨论工具。支持自由话题、Battle Loop 辩论机制和跨会话连续性。

本 Skill 为薄触发层，负责命令路由、初始化和上下文收集。Battle Loop 执行逻辑委托给 codex-battle-agent。

触发条件

命令触发

• /cc-codex-review <topic> - 启动新话题讨论
• /cc-codex-review 继续 - 继续当前话题
• /cc-codex-review 结束 - 结束话题并输出制品
• /cc-codex-review 状态 - 查看状态
• /cc-codex-review 重置 - 重置 session_id（保留 summary，需用户确认）

自然语言触发

• "让 codex 看看这个方案" / "跟 codex 讨论一下" -> 启动新话题
• "继续刚才的讨论" / "接着聊" -> 继续当前话题
• "讨论结束了" / "可以了" -> 结束话题
• "审查状态" / "当前讨论进度" -> 查看状态
• "重置会话" / "重新开始" -> 重置

前置依赖

• CodexMCP 已安装为 MCP Server（名称: codex）
• 提供 codex 工具，支持 prompt、SESSION_ID、sandbox、return_all_messages 参数
• 约定：topic 元数据使用 session_id 字段存储；调用 Codex MCP 续接时由 Agent 映射为 SESSION_ID
• Python 3.8+（运行 topic-manager.py）

通用配置

TOPIC_MANAGER=~/.claude/skills/cc-codex-review/scripts/topic-manager.py
DATA_DIR=.cc-codex
MAX_ROUNDS_LIGHT=1
MAX_ROUNDS_DEEP=5

审查模式

| 模式 | MAX_ROUNDS | 触发条件 | |------|-----------|---------| | 轻量审查（默认） | 1 | 默认模式，或用户说"审查/review/看看/检查" | | 深度讨论 | 5 | 用户明确表达深度意图（见下方关键词） |

深度讨论触发关键词

用户消息中包含以下任一关键词/模式时，使用深度讨论模式：

• 明确要求多轮："深度讨论"、"深入讨论"、"仔细讨论"、"详细讨论"、"多轮"、"battle"、"deep review"
• 强烈程度词："反复推敲"、"好好讨论"、"认真审查"、"彻底审查"
• 用户通过参数指定：--deep 或 --rounds N

--rounds N 参数

用户可通过 --rounds N 手动指定轮次（1-10），覆盖默认值。例如：

• /cc-codex-review 审查这个方案 --rounds 3 -> max_rounds=3

不匹配以上任何条件时，一律使用轻量审查（max_rounds=1）。

话题类型与制品映射

| 话题类型 | 说明 | 制品文件名 | |----------|------|-----------| | code-implementation | 代码实现方案讨论 | changes.md | | architecture-design | 架构设计讨论 | plan.md | | bug-analysis | Bug 分析讨论 | analysis.md | | technical-decision | 技术决策讨论 | decision.md | | open-discussion | 开放讨论 | memo.md |

话题分类规则

Claude Code 根据用户话题内容自动分类：

• 涉及具体代码修改、实现步骤 -> code-implementation
• 涉及系统设计、模块划分、技术选型 -> architecture-design
• 涉及 bug 排查、错误分析 -> bug-analysis
• 涉及技术方案选择、权衡 -> technical-decision
• 其他 / 不确定 -> open-discussion

不确定时询问用户确认。 用户可通过参数手动指定类型：/cc-codex-review <topic> --type architecture-design

命令路由

1. /cc-codex-review <topic> -> 执行「讨论启动流程」
2. /cc-codex-review 继续 -> 执行「继续讨论流程」
3. /cc-codex-review 结束 -> 执行「结束讨论流程」
4. /cc-codex-review 状态 -> 执行 python3 "$TOPIC_MANAGER" status "$PWD" 并格式化展示
5. /cc-codex-review 重置 -> 需用户确认后，将 session_id 设为 null（保留 summary.md）

新会话初始化流程

每次 Claude Code 新会话启动、用户触发 /cc-codex-review 相关命令时，先执行初始化：

1. auto-cleanup: python3 "$TOPIC_MANAGER" auto-cleanup "$PWD" 120
2. 检测活跃话题: python3 "$TOPIC_MANAGER" topic-read "$PWD"
3. 如果有活跃话题:
   - 告知用户："检测到未完成的话题: [标题]（第 N/5 轮）"
   - 提示用户选择：继续讨论 / 结束话题 / 放弃并开始新话题
4. 如果无活跃话题: 正常进入命令处理

讨论启动流程（/cc-codex-review <topic>）

Step 1: 创建话题

# Claude Code 自动分类话题类型（或用户指定）
python3 "$TOPIC_MANAGER" topic-create "$PWD" "<话题标题>" "<类型>"

从返回的 JSON 中提取 topic_id。

Step 2: 收集上下文

• 读取项目背景：先查 $PWD/CLAUDE.md，再查 $PWD/.claude/CLAUDE.md
• 根据话题类型收集相关素材：
  • code-implementation: git diff、相关源码
  • architecture-design: 现有架构描述、相关文档
  • bug-analysis: 错误日志、相关代码
  • technical-decision: 备选方案描述
  • open-discussion: 用户提供的素材

Step 3: 写入 context-bundle.md

将收集到的所有上下文写入一个文件，供 Agent 读取：

路径：$PWD/.cc-codex/topics/<topic_id>/context-bundle.md

# Context Bundle

## 话题
<话题标题和描述>

## 项目背景
<从 CLAUDE.md 提取的信息摘要>

## 讨论素材
<收集到的上下文内容>

Step 4: 构造参数并 spawn Agent

根据审查模式确定 max_rounds：

• 轻量审查: max_rounds = MAX_ROUNDS_LIGHT (1)
• 深度讨论: max_rounds = MAX_ROUNDS_DEEP (5)，或用户通过 --rounds N 指定的值

调用 Task tool:
  subagent_type: codex-battle-agent
  description: "CC-Codex Battle Loop"
  mode: bypassPermissions
  prompt: |
    执行 CC-Codex Battle Loop。配置如下：

    ```json
    {
      "mode": "NEW",
      "topic_id": "<topic_id>",
      "topic_title": "<话题标题>",
      "topic_type": "<话题类型>",
      "session_id": null,
      "workdir": "<$PWD>",
      "max_rounds": <根据审查模式确定: 1 或 5 或用户指定值>,
      "current_round": 1,
      "context_bundle_path": ".cc-codex/topics/<topic_id>/context-bundle.md",
      "artifact_type": "<根据话题类型映射的制品文件名>",
      "debug": false
    }
    ```

    context-bundle 路径: .cc-codex/topics/<topic_id>/context-bundle.md

Step 5: 接收结果并完成

1. 解析 Agent 返回的 JSON 结果
2. 完成话题：python3 "$TOPIC_MANAGER" topic-complete "$PWD"
3. 如果话题有 output_dir，将制品从 artifacts/ 复制到用户指定目录
4. 向用户展示结论（见下方展示格式）

跨会话恢复策略

• 主路径：使用保存的 session_id 恢复 Codex 会话（CONTINUE 模式）
• 备路径：session_id 失效时，基于 summary.md 重建上下文（REBUILD 模式）
• 模式判断由 Skill 层完成，执行由 Agent 层负责
• 续接参数规范：Skill 仅传递 session_id 给 Agent；Agent 调用 MCP 时必须使用 SESSION_ID

继续讨论流程（/cc-codex-review 继续）

Step 1: 读取活跃话题

python3 "$TOPIC_MANAGER" topic-read "$PWD"

如果无活跃话题，提示用户先创建。

Step 2: 判断恢复模式

• 如果有 session_id -> 模式为 CONTINUE
• 如果无 session_id（或之前标记为失效） -> 模式为 REBUILD

Step 3: 准备 context-bundle.md

• CONTINUE 模式：将已有的 summary.md 内容写入 context-bundle.md 作为上下文提示（Codex 仍通过 session_id 保有完整历史，此文件仅供 Agent 参考）
• REBUILD 模式：将 summary.md 完整内容写入 context-bundle.md 作为从零重建讨论上下文的唯一信息源（旧 session 已失效）

Step 4: spawn Agent

调用 Task tool:
  subagent_type: codex-battle-agent
  description: "CC-Codex Battle Loop"
  mode: bypassPermissions
  prompt: |
    执行 CC-Codex Battle Loop。配置如下：

    ```json
    {
      "mode": "CONTINUE 或 REBUILD",
      "topic_id": "<topic_id>",
      "topic_title": "<话题标题>",
      "topic_type": "<话题类型>",
      "session_id": "<session_id 或 null>",
      "workdir": "<$PWD>",
      "max_rounds": <根据审查模式确定: 沿用原话题的模式>,
      "current_round": <当前轮次>,
      "context_bundle_path": ".cc-codex/topics/<topic_id>/context-bundle.md",
      "artifact_type": "<制品文件名>",
      "debug": false
    }
    ```

    context-bundle 路径: .cc-codex/topics/<topic_id>/context-bundle.md

Step 5: 接收结果并完成

同「讨论启动流程 Step 5」。

结束讨论流程（/cc-codex-review 结束）

1. 读取活跃话题元数据和 summary.md
2. 如果 Battle Loop 尚未自然结束（仍有未决项）：
   • 基于 summary.md 中记录的共识清单，直接生成制品文件
   • 写入 $PWD/.cc-codex/topics/<topic_id>/artifacts/<制品文件>
3. 如果有 output_dir，复制到用户指定目录
4. 完成话题：python3 "$TOPIC_MANAGER" topic-complete "$PWD"
5. 向用户报告结论

结果展示格式

Agent 返回结果后，向用户展示：

## CC-Codex 讨论结论

**话题**: <话题标题>
**类型**: <话题类型>
**轮次**: <final_round>/<max_rounds>
**结论**: <conclusion>

### 达成共识
- <consensus_items 列表>

### 待处理项（如有）
- <pending_items 列表>

### 制品
- 路径: <artifact_path>

如果 status 为 error，展示错误信息并提示用户可选操作。

Battle 过程的中间产物（summary.md 更新等）不主动展示给用户，除非用户主动查询。

Debug 模式

用户说 "debug 模式" / "查看交互过程" / "显示完整对话" 时，在 spawn Agent 的 JSON 参数中将 debug 设为 true。Agent 会将 Codex 调用的 return_all_messages 设为 true，返回完整对话历史。

用户交互说明

• Battle Loop 由 Agent 执行，执行期间用户无法中途干预
• 用户可通过 MAX_ROUNDS（默认 5）控制最大轮次
• 如需提前终止正在进行的讨论，等 Agent 返回后使用 /cc-codex-review 结束 基于已有 summary 生成制品
• Agent 执行完毕后，Skill 层统一向用户展示结论摘要

制品输出规则

两步发布策略：

1. 先写入内部目录（单一真源）： $PWD/.cc-codex/topics/<topic_id>/artifacts/<制品文件> （topic_id 从 topic-read 返回值获取，制品文件名由话题类型决定，见映射表）

2. 用户指定目录时，成功后发布到外部：

   • 话题创建时或结束时，用户可指定 output_dir
   • 指定后通过 topic-update 保存: python3 "$TOPIC_MANAGER" topic-update "$PWD" output_dir "<路径>"
   • 结束时将制品从 artifacts/ 复制到用户指定目录

异常处理

CodexMCP 不可用

如果 codex 工具不可用，所有命令将报错并提示安装：

claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp

Agent 返回 error

• 展示 error 信息给用户
• 提示可选操作：重试 / 手动处理 / 放弃话题

topic-manager.py 调用失败

• 检查 Python 3 是否可用
• 检查脚本路径是否正确
• 展示 stderr 错误信息

话题目录损坏

• meta.json 损坏：读取 summary.md 解析基本信息（标题、类型、轮次），调用 topic-create 重建话题
• summary.md 丢失：从 meta.json 读取元数据，用 Write 工具重建空的 summary.md 模板
• 这些恢复逻辑由 Skill 层（Claude Code）执行，topic-manager.py 本身不提供自动修复

预算耗尽

• 当 Agent 返回 error: "budget_exhausted" 时
• 保存当前进展（Agent 已在退出前更新 summary.md）
• 完成话题：python3 "$TOPIC_MANAGER" topic-complete "$PWD"
• 告知用户讨论因预算耗尽而终止，可用 /cc-codex-review 继续 恢复

.gitignore 提示

首次运行时，检查项目 .gitignore 是否包含 .cc-codex/，如果没有则提示用户添加：

# CC-Codex 协作讨论运行时数据
.cc-codex/