/docs/CODEX_GEMINI_REVIEW_GUIDE_CN.md

Codex + Gemini 审稿人指南

使用：

• Codex 作为主执行者
• Gemini 作为审稿人
• 本地 gemini-review MCP bridge 作为传输层
• direct Gemini API 作为默认 reviewer backend

这份指南是对上游 skills/skills-codex/ 的叠加方案，不是替换。

架构

• 基础 skill 集：skills/skills-codex/
• 审稿覆盖层：skills/skills-codex-gemini-review/
• 审稿 bridge：mcp-servers/gemini-review/

安装顺序很重要：

1. 先安装 skills/skills-codex/*
2. 再安装 skills/skills-codex-gemini-review/*
3. 最后注册 gemini-review MCP

安装

git clone https://github.com/wanshuiyin/Auto-claude-code-research-in-sleep.git
cd Auto-claude-code-research-in-sleep

mkdir -p ~/.codex/skills
cp -a skills/skills-codex/* ~/.codex/skills/
cp -a skills/skills-codex-gemini-review/* ~/.codex/skills/

mkdir -p ~/.codex/mcp-servers/gemini-review
cp mcp-servers/gemini-review/server.py ~/.codex/mcp-servers/gemini-review/server.py
cp mcp-servers/gemini-review/README.md ~/.codex/mcp-servers/gemini-review/README.md
codex mcp add gemini-review --env GEMINI_REVIEW_BACKEND=api -- python3 ~/.codex/mcp-servers/gemini-review/server.py

推荐凭证文件：

mkdir -p ~/.gemini
cat > ~/.gemini/.env <<'EOF'
GEMINI_API_KEY="your-key"
EOF
chmod 600 ~/.gemini/.env

如果存在，bridge 会自动加载 ~/.gemini/.env。

为什么默认走 direct API

• 这条路径的目标是：最大化复用原始 ARIS 的 reviewer-aware skills，同时最少改 skill。
• gemini-review bridge 保留了与 Claude-review overlay 相同的 review / review_reply / review_start / review_reply_start / review_status 契约。
• 直接走 Gemini API 可以去掉本地 CLI 这一跳，让 reviewer 路径更接近 ARIS 里已有的 API 型集成方式。

接入边界说明

• Google AI Studio / Gemini API 在支持地区提供免费层；这不要求你先订阅 Gemini Advanced / Google One AI Premium。
• 免费层可用模型、速率限制和配额会变化，不应把某个固定额度或旧模型示例写成长期承诺。
• 免费层下的 prompt / response 处理条款与付费层不同；如果涉及敏感数据，必须先核对官方当前条款。
• 官方入口与定价说明：
  • API key / AI Studio：https://aistudio.google.com/apikey
  • Gemini API 定价与免费层：https://ai.google.dev/gemini-api/docs/pricing

可选 CLI fallback

这份指南的预期路径是 direct API。
如果你明确想切到 Gemini CLI，可改成：

codex mcp remove gemini-review
codex mcp add gemini-review --env GEMINI_REVIEW_BACKEND=cli -- python3 ~/.codex/mcp-servers/gemini-review/server.py

但这不是本指南的主路径。

验证

1. 检查 MCP 是否注册成功：

codex mcp list

2. 检查本地 Gemini 凭证文件是否存在：

test -f ~/.gemini/.env && echo "Gemini env file found"

3. 在你的项目里启动 Codex：

codex -C /path/to/your/project

排障

如果默认 API 模型在你当前的免费层时间窗口里返回临时 429，不要改 bridge 结构，只需要覆盖 reviewer model：

codex mcp remove gemini-review
codex mcp add gemini-review --env GEMINI_REVIEW_BACKEND=api --env GEMINI_REVIEW_MODEL=gemini-flash-latest -- python3 ~/.codex/mcp-servers/gemini-review/server.py

这不会改变 ARIS 的 reviewer 契约，也不会改变 skill overlay 的组织方式，只是让同一个本地 gemini-review bridge 在底层改用另一个 Gemini API 模型。

验证结果摘要

这条路径做了两层验证：

• 全量 overlay 覆盖检查：skills/skills-codex-gemini-review/ 覆盖的 15 个预定义 reviewer-aware Codex skill 都逐一核对过，确认已经指向 gemini-review，不再依赖旧的 reviewer transport。
• bridge 运行时验证：本地 gemini-review MCP bridge 实测覆盖了：
  • review
  • review_reply
  • review_start
  • review_reply_start
  • review_status
  • 基于本地图像的 imagePaths 多模态审查
• 代表性 Codex 侧 smoke test：我们在一个私有、未公开的研究仓库上实跑了这套 overlay，确认真实的 Codex 执行能够进入 Gemini reviewer 路径，覆盖了研究审稿、idea 生成、论文规划这几类代表性工作流。

已经验证通过的点：

• direct API 审稿可以返回有效 reviewer 文本
• 异步 review job 可以完成，并可通过 review_status 恢复状态
• 带 thread 状态的 follow-up review 可以继续多轮对话
• imagePaths 本地图像审查可用
• 已实跑的 Codex skill 路径能够正确加载 Gemini overlay，并发出真实的 gemini-review tool call

测试中的实际观察：

• Gemini 免费层对这条 reviewer 路径是可用的，但如果在很短时间内集中压测，仍然可能出现临时 429
• 速率限制表现和具体模型有关；当前 API 模型面应以 AI Studio / ListModels 为准，而不是沿用旧配额表里的模型示例
• 在同一套环境上的后续重试中，把 GEMINI_REVIEW_MODEL 覆盖为 gemini-flash-latest 后，direct API bridge 已成功跑通同步 review、异步 review_start -> review_status 以及带 thread 的 review_reply_start -> review_status
• 这类 429 更像是短时间 burst limit，而不是集成本身失效
• 对超长 prompt，宿主侧 MCP tool timeout 仍可能先于同步调用返回，所以长审稿默认仍推荐 review_start / review_reply_start + review_status

这也是为什么 bridge 同时暴露同步和异步工具，而 reviewer-aware skill overlay 默认优先走异步流程。

会覆盖哪些 skill

这个 overlay 会替换预定义的 reviewer-aware Codex skills：

• idea-creator
• idea-discovery
• idea-discovery-robot
• research-review
• novelty-check
• research-refine
• auto-review-loop
• grant-proposal
• paper-plan
• paper-figure
• paper-poster-html
• paper-slides
• paper-write
• paper-writing
• auto-paper-improvement-loop

其它能力仍然来自上游 skills/skills-codex/。

核心 8 个 vs 运行态 15 个

这条路径有两种都成立的描述方式：

• 核心 8 个：和现有 Claude-review 路径一一对齐的 reviewer overlay 核心集合
• 运行态 15 个：当前安装后的 Codex skill 集里，实际切到 Gemini reviewer 的完整 reviewer-aware 技能面

其中 核心 8 个 是：

• research-review
• novelty-check
• research-refine
• auto-review-loop
• paper-plan
• paper-figure
• paper-write
• auto-paper-improvement-loop

这 8 个最直接对应早先 Claude-review overlay 的组织方式和 reviewer 契约。

另外扩展进去的 7 个 reviewer-aware 技能是：

• idea-creator
• idea-discovery
• idea-discovery-robot
• grant-proposal
• paper-writing
• paper-slides
• paper-poster-html

所以更准确的理解是：

• 核心机制 仍然沿用和 Claude 路径相同的 8-skill overlay 形状
• 运行态 reviewer 覆盖面 则已经扩展到 15 个 skill

这也解释了为什么 diff 更大，但并不意味着 reviewer 契约本身被改乱了。

直接消费者 vs wrapper

这 15 个 skill 里又可以分成两类：

• 12 个直接消费者：自己会直接调用 mcp__gemini-review__review_start / review_reply_start / review_status
  • research-review
  • novelty-check
  • research-refine
  • auto-review-loop
  • paper-plan
  • paper-figure
  • paper-write
  • auto-paper-improvement-loop
  • idea-creator
  • grant-proposal
  • paper-slides
  • paper-poster-html
• 3 个 wrapper：主要负责串联下游 reviewer-aware 子 skill，并向下传递 REVIEWER_MODEL=gemini-review
  • idea-discovery
  • idea-discovery-robot
  • paper-writing

这层分类对验收很重要：不需要把 15 条工作流都完整跑到底，才能证明 reviewer transport 是通的。对于 PR 验收，更合理的做法是：全量结构检查 + bridge 运行时验证 + 少量直接消费者 / wrapper 的代表性 smoke test 组合验证。

异步 reviewer 流程

对于长论文 / 长项目审稿，使用：

• review_start
• review_reply_start
• review_status

原因：即便走 direct API，超长同步 reviewer 调用仍然可能撞上宿主侧的 MCP timeout。保留异步 review* 流程，才能在不改原有 reviewer-aware skill 行为的前提下继续复用它们。

项目配置

这条路径不需要额外的项目配置文件。

• 继续使用你现有的 CLAUDE.md
• 保持现有项目布局
• 只切换安装的 Codex skill 文件和 MCP 注册

维护原则

让这条路径保持足够窄：

• 基础能力继续复用 skills/skills-codex/*
• 只在 skills/skills-codex-gemini-review/* 里覆盖 reviewer-aware skills
• 让 mcp-servers/gemini-review/server.py 只聚焦 review* 兼容契约
• 如果某个 skill 需要审查 poster PNG，就通过 direct Gemini API backend 传 imagePaths，而不是再发明第二套 bridge