@researai/deepscientist 1.5.11 → 1.5.13

package/docs/en/15_CODEX_PROVIDER_SETUP.md

@@ -0,0 +1,382 @@
+# 15 Codex Provider Setup
+
+DeepScientist does not implement separate provider adapters for MiniMax, GLM, Volcengine Ark, or Alibaba Bailian.
+
+Instead, it reuses the same Codex CLI setup that already works in your terminal.
+
+The recommended order is always:
+
+1. make Codex itself work first
+2. confirm `codex` or `codex --profile <name>` works in a terminal
+3. run `ds doctor`
+4. run `ds` or `ds --codex-profile <name>`
+
+## Three supported patterns
+
+### 1. Default OpenAI login path
+
+Use this when your Codex CLI works through the standard OpenAI login flow.
+
+```bash
+codex --login
+ds doctor
+ds
+```
+
+### 2. One-off provider profile
+
+Use this when you already have a named Codex profile such as `m27`, `glm`, `ark`, or `bailian`.
+
+```bash
+codex --profile m27
+ds doctor --codex-profile m27
+ds --codex-profile m27
+```
+
+If you need one specific Codex binary for this run, use:
+
+```bash
+ds doctor --codex /absolute/path/to/codex --codex-profile m27
+ds --codex /absolute/path/to/codex --codex-profile m27
+```
+
+This is the simplest path. You do not need to edit `runners.yaml` just to try one provider-backed session.
+
+### 3. Persistent provider profile
+
+Use this when you want DeepScientist to keep using the same profile by default.
+
+```yaml
+codex:
+  enabled: true
+  binary: codex
+  config_dir: ~/.codex
+  profile: minimax
+  model: inherit
+  model_reasoning_effort: xhigh
+  approval_policy: on-request
+  sandbox_mode: workspace-write
+```
+
+Important:
+
+- keep `model: inherit` for provider-backed Codex profiles unless you are certain the provider accepts the explicit model id you plan to send
+- DeepScientist will reuse the same `~/.codex/config.toml` and environment that your terminal Codex already uses
+
+## Provider matrix
+
+| Provider | Official docs | Codex login needed | What DeepScientist should use |
+|---|---|---|---|
+| OpenAI | use the normal Codex setup | Yes | no profile; run `ds` |
+| MiniMax | [MiniMax Codex CLI](https://platform.minimaxi.com/docs/coding-plan/codex-cli) | No | your Codex profile, for example `ds --codex-profile m27` |
+| GLM | [GLM Coding Plan: Other Tools](https://docs.bigmodel.cn/cn/coding-plan/tool/others) | No | a Codex profile that targets the GLM coding endpoint |
+| Volcengine Ark | [Ark Coding Plan Overview](https://www.volcengine.com/docs/82379/1925114?lang=zh) | No | a Codex profile that targets the Ark coding endpoint |
+| Alibaba Bailian | [Bailian Coding Plan: Other Tools](https://help.aliyun.com/zh/model-studio/other-tools-coding-plan) | No | a Codex profile that targets the Bailian coding endpoint |
+
+## OpenAI
+
+### What to prepare
+
+- a normal Codex CLI install
+- a successful `codex --login` or `codex` interactive first-run setup
+
+### DeepScientist commands
+
+```bash
+ds doctor
+ds
+```
+
+### Persistent runner config
+
+```yaml
+codex:
+  enabled: true
+  binary: codex
+  config_dir: ~/.codex
+  profile: ""
+  model: gpt-5.4
+```
+
+## MiniMax
+
+MiniMax is the clearest profile-based case. Its official Codex CLI guide configures a custom Codex provider and sets `requires_openai_auth = false`.
+
+Official doc:
+
+- <https://platform.minimaxi.com/docs/coding-plan/codex-cli>
+
+### Verified compatibility note
+
+Checked against MiniMax's current Codex CLI doc and local compatibility validation on 2026-03-25:
+
+- MiniMax's Codex CLI page currently recommends `@openai/codex@0.57.0`
+- the Coding Plan endpoint to use is `https://api.minimaxi.com/v1`
+- MiniMax's official page uses `m21` as the profile name, but that profile name is only a local alias; this repo uses `m27` consistently in examples
+- the `codex-MiniMax-*` model names shown on MiniMax's page did not pass reliably through Codex CLI in local testing with the provided key
+- the locally verified working path was `MiniMax-M2.7` + `m27` + `model: inherit` + Codex CLI `0.57.0`
+- the current `@openai/codex` latest release still does not line up cleanly with MiniMax's current guide
+
+If you want the most reproducible DeepScientist + MiniMax path today, use Codex CLI `0.57.0`.
+
+### What to prepare
+
+- Codex CLI `0.57.0`
+- a MiniMax `Coding Plan Key`
+- `MINIMAX_API_KEY` available in the shell that starts Codex and DeepScientist
+- the current shell cleared of `OPENAI_API_KEY` and `OPENAI_BASE_URL`
+- a working Codex profile in `~/.codex/config.toml`
+
+### Install Codex CLI `0.57.0`
+
+The simplest path is to pin the global Codex install:
+
+```bash
+npm install -g @openai/codex@0.57.0
+codex --version
+```
+
+Expected output:
+
+```text
+codex-cli 0.57.0
+```
+
+If you want to keep another Codex version elsewhere, create a small wrapper script and point `runners.codex.binary` at that absolute path.
+
+### Codex-side setup
+
+Use `https://api.minimaxi.com/v1`, not `https://api.minimax.io/v1`.
+
+MiniMax's doc requires clearing the OpenAI environment variables first:
+
+```bash
+unset OPENAI_API_KEY
+unset OPENAI_BASE_URL
+export MINIMAX_API_KEY="..."
+```
+
+MiniMax's official page uses `m21` as the example profile name. Since the profile name is only a local alias, this repo rewrites that example to `m27`.
+
+The important difference is the model name:
+
+- MiniMax's page currently shows `codex-MiniMax-M2.5`
+- in local testing, direct MiniMax API calls worked with `MiniMax-M2.7`
+- with the same key, `codex-MiniMax-M2.5` and `codex-MiniMax-M2.7` both failed through Codex CLI
+
+So the config below is the currently recommended DeepScientist working configuration:
+
+```toml
+[model_providers.minimax]
+name = "MiniMax Chat Completions API"
+base_url = "https://api.minimaxi.com/v1"
+env_key = "MINIMAX_API_KEY"
+wire_api = "chat"
+requires_openai_auth = false
+request_max_retries = 4
+stream_max_retries = 10
+stream_idle_timeout_ms = 300000
+
+[profiles.m27]
+model = "MiniMax-M2.7"
+model_provider = "minimax"
+```
+
+What DeepScientist supports now:
+
+- if you use this profile-only MiniMax config with Codex CLI `0.57.0`, DeepScientist automatically promotes the selected profile's `model_provider` and `model` to the top level inside its probe/runtime copy of `.codex/config.toml`
+- this means DeepScientist can start even when plain terminal `codex --profile m27` still fails on that exact profile-only shape
+
+If you want plain terminal `codex --profile <name>` to work too, use the explicit top-level compatibility form instead:
+
+```toml
+model = "MiniMax-M2.7"
+model_provider = "minimax"
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+
+[model_providers.minimax]
+name = "MiniMax Chat Completions API"
+base_url = "https://api.minimaxi.com/v1"
+env_key = "MINIMAX_API_KEY"
+wire_api = "chat"
+requires_openai_auth = false
+request_max_retries = 4
+stream_max_retries = 10
+stream_idle_timeout_ms = 300000
+
+[profiles.m27]
+model = "MiniMax-M2.7"
+model_provider = "minimax"
+```
+
+Then:
+
+```bash
+codex --profile m27
+```
+
+### DeepScientist commands
+
+```bash
+ds doctor --codex-profile m27
+ds --codex-profile m27
+```
+
+### Persistent runner config
+
+```yaml
+codex:
+  enabled: true
+  binary: /tmp/codex057-wrapper
+  config_dir: ~/.codex
+  profile: m27
+  model: inherit
+  model_reasoning_effort: high
+```
+
+If you already pinned your global `codex` binary to `0.57.0`, you can set `binary: codex` instead. The absolute wrapper path here is only to make the version choice explicit.
+
+If you do not want to persist that path in `runners.yaml`, you can keep `binary: codex` there and launch ad hoc with:
+
+```bash
+ds --codex /absolute/path/to/codex --codex-profile m27
+```
+
+DeepScientist now does two MiniMax-specific compatibility steps for the `0.57.0` path:
+
+- it downgrades `xhigh` to `high` automatically when the Codex CLI does not support `xhigh`
+- it auto-adapts MiniMax's profile-only `model_provider` / `model` shape inside the temporary DeepScientist Codex home when needed
+
+## GLM
+
+GLM documents the Coding Plan as an OpenAI-compatible coding endpoint rather than a dedicated Codex login flow.
+
+Official docs:
+
+- <https://docs.bigmodel.cn/cn/coding-plan/tool/others>
+- <https://docs.bigmodel.cn/cn/coding-plan/faq>
+
+### Official provider values
+
+- Base URL: `https://open.bigmodel.cn/api/coding/paas/v4`
+- API key: your GLM Coding Plan key
+- Model: `GLM-4.7` for the documented path, or `GLM-5` where supported
+
+### Recommended Codex adaptation
+
+GLM does not currently publish a separate Codex CLI page in the same style as MiniMax. The practical DeepScientist path is:
+
+1. create a Codex profile in `~/.codex/config.toml` that points to the GLM coding endpoint above
+2. make sure `codex --profile glm` works in a terminal first
+3. run DeepScientist with the same profile
+
+### DeepScientist commands
+
+```bash
+ds doctor --codex-profile glm
+ds --codex-profile glm
+```
+
+### Persistent runner config
+
+```yaml
+codex:
+  enabled: true
+  binary: codex
+  config_dir: ~/.codex
+  profile: glm
+  model: inherit
+```
+
+## Volcengine Ark
+
+Volcengine Ark explicitly lists Codex CLI as a supported coding tool.
+
+Official doc:
+
+- <https://www.volcengine.com/docs/82379/1925114?lang=zh>
+
+### Official provider values
+
+- OpenAI-compatible Base URL: `https://ark.cn-beijing.volces.com/api/coding/v3`
+- Supported coding models: `doubao-seed-code-preview-latest`, `ark-code-latest`
+- Use the Coding Plan key and the exact Coding Plan endpoint
+
+### Recommended Codex adaptation
+
+Create a Codex profile that targets the Ark coding endpoint and test it directly first:
+
+```bash
+codex --profile ark
+```
+
+Then start DeepScientist with the same profile:
+
+```bash
+ds doctor --codex-profile ark
+ds --codex-profile ark
+```
+
+### Persistent runner config
+
+```yaml
+codex:
+  enabled: true
+  binary: codex
+  config_dir: ~/.codex
+  profile: ark
+  model: inherit
+```
+
+## Alibaba Bailian
+
+Bailian documents Coding Plan as an OpenAI-compatible coding endpoint. It requires the Coding Plan-specific key and endpoint, not the generic platform endpoint.
+
+Official docs:
+
+- <https://help.aliyun.com/zh/model-studio/other-tools-coding-plan>
+- <https://help.aliyun.com/zh/model-studio/coding-plan-faq>
+
+### Official provider values
+
+- OpenAI-compatible Base URL: `https://coding.dashscope.aliyuncs.com/v1`
+- API key: Coding Plan-specific key, typically `sk-sp-...`
+- Model: choose a Coding Plan-supported model from the current Bailian overview
+
+### Recommended Codex adaptation
+
+Create a Codex profile that points to the Bailian Coding Plan endpoint and test it directly first:
+
+```bash
+codex --profile bailian
+```
+
+Then start DeepScientist with the same profile:
+
+```bash
+ds doctor --codex-profile bailian
+ds --codex-profile bailian
+```
+
+### Persistent runner config
+
+```yaml
+codex:
+  enabled: true
+  binary: codex
+  config_dir: ~/.codex
+  profile: bailian
+  model: inherit
+```
+
+## Troubleshooting checklist
+
+If a provider-backed profile still fails in DeepScientist:
+
+1. run `codex --profile <name>` manually first
+2. confirm the provider API key is present in the same shell
+3. confirm the provider-specific Base URL is the Coding Plan endpoint, not the generic API endpoint
+4. keep DeepScientist runner `model: inherit` unless you need an explicit override
+5. run `ds doctor --codex-profile <name>`
+6. only after that run `ds --codex-profile <name>`

package/docs/en/README.md

@@ -30,6 +30,8 @@ This page is the shortest path to the right document.
 
 - [00 Quick Start](./00_QUICK_START.md)
   Start here if you want to install DeepScientist, launch it locally, and create your first project.
+- [15 Codex Provider Setup](./15_CODEX_PROVIDER_SETUP.md)
+  Read this when you want to run DeepScientist through MiniMax, GLM, Volcengine Ark, Alibaba Bailian, or another Codex profile.
 - [12 Guided Workflow Tour](./12_GUIDED_WORKFLOW_TOUR.md)
   Follow the real product flow from landing page to workspace, step by step.
 - [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md)
@@ -68,6 +70,8 @@ This page is the shortest path to the right document.
 
 - [09 Doctor](./09_DOCTOR.md)
   Start here for diagnostics and common runtime problems.
+- [15 Codex Provider Setup](./15_CODEX_PROVIDER_SETUP.md)
+  Check this if the problem is likely in your Codex profile, provider endpoint, API key, or model configuration.
 - [01 Settings Reference](./01_SETTINGS_REFERENCE.md)
   Check this if the problem is likely caused by config, credentials, or connector setup.
 

package/docs/zh/00_QUICK_START.md

@@ -36,7 +36,9 @@
 建议你先准备好这些：
 
 - 安装好 Node.js `>=18.18` 和 npm `>=9`；请优先参考官方页面安装：https://nodejs.org/en/download
-- 一个已经完成认证的 Codex CLI；第一次运行 `ds` 前，请先执行 `codex --login`（或 `codex`）并完成认证
+- 一条已经可用的 Codex 路径：
+  - 默认 OpenAI 登录路径：`codex --login`（或 `codex`）
+  - provider-backed 路径：一个已经可用的 Codex profile，例如 `minimax`、`glm`、`ark`、`bailian`
 - 模型或 API 凭证
 - 如果任务比较重，准备好 GPU 或远程服务器
 - 如果你要长期运行，优先准备 Docker 或其他隔离环境，并准备一个非 root 账号专门启动 DeepScientist
@@ -52,6 +54,10 @@
 - 阿里百炼 Coding Plan：https://help.aliyun.com/zh/model-studio/coding-plan
 - 火山引擎 Ark Coding Plan：https://www.volcengine.com/docs/82379/1925115?lang=zh
 
+如果你准备使用 provider-backed 的 Codex profile，而不是默认 OpenAI 登录流，请继续看：
+
+- [15 Codex Provider 配置](./15_CODEX_PROVIDER_SETUP.md)
+
 ## 1. 先安装 Node.js，再安装 DeepScientist
 
 DeepScientist 目前仅支持 Linux 和 macOS。
@@ -73,7 +79,7 @@ npm install -g @researai/deepscientist
 
 这一步会把 `ds` 命令安装到你的机器上。
 
-DeepScientist 依赖一个可用的 Codex CLI。npm 包会尽量把随包的 Codex 依赖一起装好，但如果安装完成后 `codex` 仍然不可用，请显式修复：
+DeepScientist 依赖一个可用的 Codex CLI。它会优先使用你机器上已经可用的 `codex`，只有在本机找不到时才回退到 npm 包内置的依赖。如果安装完成后 `codex` 仍然不可用，请显式修复：
 
 ```bash
 npm install -g @openai/codex
@@ -89,6 +95,10 @@ ds latex install-runtime
 
 ## 2. 第一次运行 `ds` 前，先完成 Codex 配置
 
+这里有两条路径，二选一即可。
+
+### 2.1 默认 OpenAI 登录路径
+
 运行：
 
 ```bash
@@ -109,7 +119,48 @@ codex
 ds doctor
 ```
 
-DeepScientist 会在启动前强制做一次真实的 Codex hello 探测。当前版本里，这个探测会先尝试 `~/DeepScientist/config/runners.yaml` 中配置的 runner 模型，默认是 `gpt-5.4`。如果你的 Codex 账号或本地 CLI 配置不能访问它，DeepScientist 会自动回退到当前 Codex 默认模型，并把后续运行持久化为 `model: inherit`。
+### 2.2 provider-backed 的 Codex profile 路径
+
+如果你已经在 MiniMax、GLM、火山方舟、阿里百炼或其他 provider 上配置了一个命名的 Codex profile，请先在终端里确认这个 profile 本身可用：
+
+```bash
+codex --profile m27
+```
+
+然后用同一个 profile 去跑 DeepScientist：
+
+```bash
+ds doctor --codex-profile m27
+```
+
+之后启动：
+
+```bash
+ds --codex-profile m27
+```
+
+如果你这一轮还想强制指定某一个 Codex 可执行文件，也可以一起加上 `--codex`：
+
+```bash
+ds doctor --codex /absolute/path/to/codex --codex-profile m27
+ds --codex /absolute/path/to/codex --codex-profile m27
+```
+
+这里的 `m27` 是本仓库统一使用的 MiniMax profile 示例名。MiniMax 官方页面当前示例名是 `m21`，但 profile 名只是本地别名；如果你自己用了别的名字，就把命令里的名字一起改掉。
+
+DeepScientist 会在启动前强制做一次真实的 Codex hello 探测。默认情况下，`~/DeepScientist/config/runners.yaml` 里的 runner 模型还是 `gpt-5.4`。如果你的 profile 希望模型由 profile 自己决定，请把 `runners.yaml` 里的 `model` 改成 `inherit`；或者直接使用 `--codex-profile <name>`，让这一轮启动自动继承 profile 对应的模型。
+
+MiniMax 额外说明：
+
+- 如果当前最新版 `@openai/codex` 和 MiniMax 走不通，直接安装 `npm install -g @openai/codex@0.57.0`
+- 先创建 MiniMax `Coding Plan Key`
+- 在当前 shell 里先执行 `unset OPENAI_API_KEY` 和 `unset OPENAI_BASE_URL`
+- 使用 `https://api.minimaxi.com/v1`
+- MiniMax 官方 Codex CLI 页面当前给出的 `codex-MiniMax-*` 模型名，在本地用提供的 key 实测并不能稳定通过 Codex CLI
+- 当前本地实测可用的模型名是 `MiniMax-M2.7`
+- DeepScientist 现在可以在 probe 和运行时自动适配 MiniMax profile-only 的 `model_provider` / `model` 配置形态
+- 如果你还希望终端里的 `codex --profile <name>` 也直接可用，再在 `~/.codex/config.toml` 顶层补上 `model_provider = "minimax"` 和 `model = "MiniMax-M2.7"`
+- 当 DeepScientist 检测到旧版 Codex CLI 不支持 `xhigh` 时，会自动把它降级成 `high`
 
 ## 3. 启动本地运行时
 

package/docs/zh/01_SETTINGS_REFERENCE.md

@@ -406,6 +406,7 @@ codex:
   enabled: true
   binary: codex
   config_dir: ~/.codex
+  profile: ""
   model: gpt-5.4
   model_reasoning_effort: xhigh
   approval_policy: on-request
@@ -443,6 +444,8 @@ claude:
 - 页面标签：`Binary`
 - 作用：启动 runner 时使用的命令名或绝对路径。
 - `Test` 行为：检查该二进制是否在 `PATH` 上。
+- `codex` 的解析顺序：环境变量覆盖、显式路径、本机 `PATH`、最后才是 bundled fallback。
+- 临时使用说明：你也可以直接用 `ds --codex /absolute/path/to/codex` 临时覆盖这里的设置。
 - 首次使用说明：DeepScientist 不会替你完成 Codex 认证。第一次运行 `ds` 前，必须先确保 `codex --login`（或 `codex`）已经成功完成。
 - 修复说明：如果执行 `npm install -g @researai/deepscientist` 之后 bundled Codex 依赖仍然缺失，请显式安装 `npm install -g @openai/codex`。
 
@@ -453,6 +456,16 @@ claude:
 - 页面标签：`Config directory`
 - 作用：runner 的全局配置目录，通常存放认证和全局配置。
 
+**`profile`**
+
+- 类型：`string`
+- 默认值：`""`
+- 页面标签：`Codex profile`
+- 作用：可选的 Codex profile 名称，会直接透传为 `codex --profile <name>`。
+- 当你的 Codex CLI 已经配置成 MiniMax、GLM、火山方舟、阿里百炼或其他 provider-backed 路径时，就在这里填写。
+- 临时使用说明：如果你不想持久化写配置，也可以保持这里为空，直接使用 `ds --codex-profile <name>` 启动。
+- 组合使用说明：如果你还想临时指定 Codex 可执行文件，也可以组合成 `ds --codex /absolute/path/to/codex --codex-profile <name>`。
+
 **`model`**
 
 - 类型：`string`
@@ -460,6 +473,7 @@ claude:
 - 页面标签：`Default model`
 - 作用：项目和单次请求没有覆盖时的默认模型。
 - 启动说明：DeepScientist 的 Codex 就绪探测会优先使用这里配置的模型。如果你的 Codex 账号无法访问它，DeepScientist 会自动回退到当前 Codex 默认模型，并持久化为 `model: inherit`。
+- provider-profile 说明：当 `profile` 已设置时，通常推荐使用 `model: inherit`，让 Codex profile 自己决定 provider 侧模型。
 
 **`model_reasoning_effort`**
 
@@ -469,6 +483,7 @@ claude:
 - 允许值：`""`、`minimal`、`low`、`medium`、`high`、`xhigh`
 - 作用：默认推理强度。
 - 推荐：当前仓库的 Codex 默认就是 `xhigh`。
+- 兼容性说明：当 DeepScientist 检测到 Codex CLI 低于 `0.63.0` 时，会在启动探测和实际 runner 命令里自动把 `xhigh` 降级成 `high`。这也覆盖了 MiniMax 当前推荐的 `@openai/codex@0.57.0` 路径。
 
 **`approval_policy`**
 

package/docs/zh/02_START_RESEARCH_GUIDE.md

@@ -115,13 +115,21 @@ type StartResearchTemplate = {
   baseline_variant_id: string
   baseline_urls: string
   paper_urls: string
+  review_materials: string
   runtime_constraints: string
   objectives: string
   need_research_paper: boolean
   research_intensity: 'light' | 'balanced' | 'sprint'
   decision_policy: 'autonomous' | 'user_gated'
   launch_mode: 'standard' | 'custom'
-  custom_profile: 'continue_existing_state' | 'revision_rebuttal' | 'freeform'
+  custom_profile: 'continue_existing_state' | 'review_audit' | 'revision_rebuttal' | 'freeform'
+  review_followup_policy: 'audit_only' | 'auto_execute_followups' | 'user_gated_followups'
+  baseline_execution_policy:
+    | 'auto'
+    | 'must_reproduce_or_verify'
+    | 'reuse_existing_only'
+    | 'skip_unless_blocking'
+  manuscript_edit_mode: 'none' | 'copy_ready_text' | 'latex_required'
   entry_state_summary: string
   review_summary: string
   custom_brief: string
@@ -187,6 +195,9 @@ type StartResearchContractFields = {
     decision_policy,
     launch_mode,
     custom_profile,
+    review_followup_policy,
+    baseline_execution_policy,
+    manuscript_edit_mode,
     scope,
     baseline_mode,
     resource_policy,
@@ -196,6 +207,7 @@ type StartResearchContractFields = {
     objectives: string[],
     baseline_urls: string[],
     paper_urls: string[],
+    review_materials: string[],
     entry_state_summary,
     review_summary,
     custom_brief,
@@ -265,11 +277,19 @@ type StartResearchContractFields = {
 **`baseline_urls`**
 
 - 当没有 registry baseline 时，作为恢复 baseline 的候选来源。
+- 可以填写网络链接，也可以直接填写绝对本地文件 / 文件夹路径。
 - 提交时转成 `string[]`。
 
 **`paper_urls`**
 
-- 论文、代码仓库、benchmark、leaderboard 等参考资料。
+- 论文、代码仓库、benchmark、leaderboard、manuscript 路径等参考资料。
+- 可以填写网络链接，也可以直接填写绝对本地文件 / 文件夹路径。
+- 提交时转成 `string[]`。
+
+**`review_materials`**
+
+- 主要用于 `review_audit` 或 `revision_rebuttal`。
+- 每行填写一个 URL，或一个绝对本地文件 / 文件夹路径，用于 reviewer comments、decision letter、meta-review 或 revision packet。
 - 提交时转成 `string[]`。
 
 ### 约束与目标
@@ -325,12 +345,49 @@ type StartResearchContractFields = {
 - `continue_existing_state`
   - 先审计已有 baseline、结果、草稿或混合资产
   - prompt builder 会显式引导 agent 优先打开 `intake-audit`
+- `review_audit`
+  - 这是一个对现有 draft / paper package 做独立 skeptical 审计的任务
+  - prompt builder 会显式引导 agent 优先打开 `review`
 - `revision_rebuttal`
   - 这是一个审稿回复、revision、rebuttal 类型任务
   - prompt builder 会显式引导 agent 优先打开 `rebuttal`
 - `freeform`
+  - 这是“其它”入口
   - 以自定义 brief 为主，尽量少做额外假设
 
+**`baseline_execution_policy`**
+
+- 仅在 `launch_mode = custom` 时有意义。
+- `auto`
+  - 让启动合同和当前证据自己决定
+- `must_reproduce_or_verify`
+  - 在 reviewer-linked 的后续工作之前，先验证或恢复 rebuttal 关键依赖的 baseline / comparator
+- `reuse_existing_only`
+  - 默认信任当前 baseline / 结果，除非它们明显不一致或不可用
+- `skip_unless_blocking`
+  - 默认跳过 baseline 重跑，只有当某个 review / rebuttal 条目明确依赖缺失 comparator 时才补跑
+
+**`review_followup_policy`**
+
+- 主要用于 `review_audit`。
+- `audit_only`
+  - 只完成审计产物和路由建议
+- `auto_execute_followups`
+  - 审计后自动继续进入合理的实验和论文修改
+- `user_gated_followups`
+  - 先完成审计，再在昂贵后续动作前等待你的批准
+
+**`manuscript_edit_mode`**
+
+- 主要用于 `review_audit` 和 `revision_rebuttal`。
+- `none`
+  - 只输出规划产物
+- `copy_ready_text`
+  - 输出 section-level 的可直接粘贴修改文本
+- `latex_required`
+  - 优先把提供的 LaTeX 树当作写作表面，并输出 LaTeX-ready 的替换文本
+  - 如果选择这个模式，最好同时通过本地路径 / 文件夹输入提供 LaTeX 源目录
+
 **`entry_state_summary`**
 
 - 用自然语言概括当前已经存在什么。
@@ -387,6 +444,9 @@ type StartResearchContractFields = {
 - `custom + continue_existing_state`
   - 告诉 agent 先整理和信任排序已有资产
   - 明确优先 `intake-audit`
+- `custom + review_audit`
+  - 告诉 agent 当前 draft / paper 状态就是主动合同
+  - 明确优先 `review`
 - `custom + revision_rebuttal`
   - 告诉 agent 先理解 reviewer comments 和当前论文状态
   - 明确优先 `rebuttal`
@@ -486,6 +546,9 @@ type StartResearchContractFields = {
     "decision_policy": "user_gated",
     "launch_mode": "custom",
     "custom_profile": "revision_rebuttal",
+    "review_followup_policy": "audit_only",
+    "baseline_execution_policy": "skip_unless_blocking",
+    "manuscript_edit_mode": "latex_required",
     "scope": "baseline_plus_direction",
     "baseline_mode": "restore_from_url",
     "resource_policy": "balanced",
@@ -499,6 +562,9 @@ type StartResearchContractFields = {
     ],
     "baseline_urls": [],
     "paper_urls": [],
+    "review_materials": [
+      "/absolute/path/to/review-comments.md"
+    ],
     "entry_state_summary": "A draft and previous experiment outputs already exist.",
     "review_summary": "Reviewers asked for one stronger ablation, one extra baseline, and a clearer limitation paragraph.",
     "custom_brief": "Treat the current manuscript and review packet as the active contract."
@@ -509,7 +575,7 @@ type StartResearchContractFields = {
 ## 运行时意义
 
 - `startup_contract` 是项目的持久状态，不只是 UI 临时字段。
-- 后续 prompt builder 还会继续读取 `launch_mode`、`custom_profile`、`entry_state_summary`、`review_summary`、`custom_brief`。
+- 后续 prompt builder 还会继续读取 `launch_mode`、`custom_profile`、`review_followup_policy`、`baseline_execution_policy`、`manuscript_edit_mode`、`entry_state_summary`、`review_summary`、`review_materials`、`custom_brief`。
 - 所以 `Start Research` 不只影响第一轮，还会影响后续路由判断。
 
 ## 修改检查清单