@researai/deepscientist 1.5.11 → 1.5.12

package/docs/en/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
@@ -179,6 +187,9 @@ The dialog submits:
     decision_policy,
     launch_mode,
     custom_profile,
+    review_followup_policy,
+    baseline_execution_policy,
+    manuscript_edit_mode,
     scope,
     baseline_mode,
     resource_policy,
@@ -188,6 +199,7 @@ The dialog submits:
     objectives: string[],
     baseline_urls: string[],
     paper_urls: string[],
+    review_materials: string[],
     entry_state_summary,
     review_summary,
     custom_brief,
@@ -256,12 +268,18 @@ The dialog submits:
 
 **`baseline_urls`**
 
-- Fallback source links when there is no registered reusable baseline.
+- Fallback source links or absolute local file/folder paths when there is no registered reusable baseline.
 - Submitted as `string[]`.
 
 **`paper_urls`**
 
-- Papers, repos, benchmarks, or leaderboards that shape early scouting.
+- Papers, repos, manuscripts, benchmarks, leaderboards, or absolute local file/folder paths that shape early scouting or writing work.
+- Submitted as `string[]`.
+
+**`review_materials`**
+
+- Only meaningful for `review_audit` or `revision_rebuttal`.
+- Use one URL or one absolute local file/folder path per line for reviewer comments, decision letters, meta-review notes, or revision packets.
 - Submitted as `string[]`.
 
 ### Constraints and objectives
@@ -317,12 +335,49 @@ Only meaningful when `launch_mode = custom`.
 - `continue_existing_state`
   - start by auditing existing baselines, results, drafts, or mixed project assets
   - prompt builder should steer the agent toward `intake-audit`
+- `review_audit`
+  - start from a substantial draft or paper package that needs an independent skeptical audit
+  - prompt builder should steer the agent toward `review`
 - `revision_rebuttal`
   - start from reviewer comments, revision packets, or a rebuttal task
   - prompt builder should steer the agent toward `rebuttal`
 - `freeform`
+  - use this as the “Other” path
   - follow a custom brief with minimal forced workflow assumptions
 
+**`baseline_execution_policy`**
+
+- Only meaningful when `launch_mode = custom`.
+- `auto`
+  - let the startup contract and current evidence decide
+- `must_reproduce_or_verify`
+  - verify or recover the rebuttal-critical baseline/comparator before reviewer-linked follow-up work
+- `reuse_existing_only`
+  - trust the current baseline/results unless they are inconsistent or unusable
+- `skip_unless_blocking`
+  - skip baseline reruns unless a named review/rebuttal item truly depends on a missing comparator
+
+**`review_followup_policy`**
+
+- Mainly meaningful for `review_audit`.
+- `audit_only`
+  - stop after the audit artifacts and route recommendation
+- `auto_execute_followups`
+  - continue automatically into the justified experiments and manuscript deltas after the audit
+- `user_gated_followups`
+  - finish the audit first, then ask for approval before expensive follow-up work
+
+**`manuscript_edit_mode`**
+
+- Mainly meaningful for `review_audit` and `revision_rebuttal`.
+- `none`
+  - planning artifacts only
+- `copy_ready_text`
+  - produce section-level revision text that is ready to paste into the manuscript
+- `latex_required`
+  - prefer the provided LaTeX tree as the writing surface and produce LaTeX-ready replacement text
+  - if you choose this mode, it is best to provide the LaTeX source tree via local path / folder input
+
 **`entry_state_summary`**
 
 - Plain-language summary of what already exists.
@@ -378,6 +433,9 @@ Custom launch behavior is explicit:
 - `custom + continue_existing_state`
   - tells the agent to audit and normalize existing assets first
   - explicitly prefers `intake-audit`
+- `custom + review_audit`
+  - tells the agent that the current draft/paper state is the active contract
+  - explicitly prefers `review`
 - `custom + revision_rebuttal`
   - tells the agent to interpret reviewer comments and current paper state first
   - explicitly prefers `rebuttal`
@@ -477,6 +535,9 @@ Custom launch behavior is explicit:
     "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",
@@ -490,6 +551,9 @@ Custom launch behavior is explicit:
     ],
     "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."
@@ -500,7 +564,7 @@ Custom launch behavior is explicit:
 ## Operational implications
 
 - The startup contract is durable project state, not only UI state.
-- Prompt building later reads `launch_mode`, `custom_profile`, and related summaries again.
+- Prompt building later reads `launch_mode`, `custom_profile`, `review_followup_policy`, `baseline_execution_policy`, `manuscript_edit_mode`, `entry_state_summary`, `review_summary`, `review_materials`, and `custom_brief` again.
 - This means `Start Research` shapes not just the first turn, but later routing decisions too.
 
 ## Validation checklist

package/docs/en/09_DOCTOR.md

@@ -10,20 +10,26 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
    npm install -g @researai/deepscientist
    ```
 
-2. Make sure Codex is installed and authenticated:
+2. Make sure Codex itself is working first:
+
+   Default OpenAI path:
 
    ```bash
    codex --login
    ```
 
+   Provider-backed profile path:
+
+   ```bash
+   codex --profile minimax
+   ```
+
    If `codex` is missing, repair it explicitly with:
 
    ```bash
    npm install -g @openai/codex
    ```
 
-   If your Codex CLI version does not expose `--login`, run `codex` and finish the interactive setup there.
-
 3. Try to start DeepScientist:
 
    ```bash
@@ -81,6 +87,23 @@ If your Codex CLI version does not expose `--login`, run `codex` and finish the
 
 Finish login once, then rerun `ds doctor`.
 
+### Codex profile works in the terminal, but DeepScientist still fails
+
+Run DeepScientist with the same profile explicitly:
+
+```bash
+ds doctor --codex-profile minimax
+ds --codex-profile minimax
+```
+
+Replace `minimax` with your real profile name such as `m27`, `glm`, `ark`, or `bailian`.
+
+Also check:
+
+- the same shell still exports the provider API key
+- the profile points at the provider's Coding Plan endpoint, not the generic API endpoint
+- `~/DeepScientist/config/runners.yaml` uses `model: inherit` if the provider expects the model to come from the profile itself
+
 ### The configured Codex model is unavailable
 
 DeepScientist blocks startup until Codex passes a real startup hello probe. In the current release, that probe first uses the runner model configured in:
@@ -95,6 +118,8 @@ The default is `gpt-5.4`. If your Codex account or CLI config cannot access that
 ds doctor
 ```
 
+For provider-backed Codex profiles, `model: inherit` is usually the right default.
+
 ### `uv` is missing
 
 Normally `ds` will bootstrap a local `uv` automatically. If that bootstrap fails, install it manually:

package/docs/en/12_GUIDED_WORKFLOW_TOUR.md

@@ -118,12 +118,12 @@ Good pattern:
 
 Use these fields to reduce ambiguity before the first round starts.
 
-Put repositories in `Baseline links` when:
+Put repositories or absolute local file/folder paths in `Baseline links` when:
 
 - the quest should restore a known repo
 - the baseline must come from a specific official implementation
 
-Put papers or important external references in `Reference papers / repos` when:
+Put papers, manuscript paths, or important external references in `Paper / reference sources` when:
 
 - the task is defined by a paper
 - the expected protocol comes from prior work
@@ -131,6 +131,9 @@ Put papers or important external references in `Reference papers / repos` when:
 
 If you already know the baseline and paper, do not hide them in the main request. Put them in the dedicated fields.
 
+These reference fields are not web-only.
+You can use network links, absolute local file paths, or absolute local folder paths.
+
 ### 4.5 Reusable baseline
 
 Use this only when you already imported a trusted reusable baseline into the registry.
@@ -177,6 +180,22 @@ Why these defaults are usually correct:
 - `Standard` keeps the workflow on the ordinary path
 - `Research paper = On` keeps analysis and writing in scope
 
+If you switch `Launch mode` to `Custom`, choose the custom task type explicitly:
+
+- `Continue existing state`
+  - for reuse-first work on an existing quest state
+- `Review`
+  - for an independent skeptical audit of a substantial draft or paper package
+- `Rebuttal / revision`
+  - for reviewer-driven work where comments must be mapped into experiments, manuscript deltas, and a response letter
+- `Other / freeform`
+  - for everything else that does not fit the standard custom types
+
+If you choose `Review`, also decide:
+
+- whether the system should stop after the audit or continue automatically into follow-up experiments and manuscript updates
+- whether manuscript-facing output should be ordinary copy-ready text or LaTeX-ready text
+
 ### 4.8 Runtime constraints
 
 Use this field for hard rules, not wishes.

package/docs/en/15_CODEX_PROVIDER_SETUP.md

@@ -0,0 +1,284 @@
+# 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 `minimax`, `glm`, `ark`, or `bailian`.
+
+```bash
+codex --profile minimax
+ds doctor --codex-profile minimax
+ds --codex-profile minimax
+```
+
+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 minimax` |
+| 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>
+
+### What to prepare
+
+- Codex CLI installed
+- `MINIMAX_API_KEY` available in the shell that starts Codex and DeepScientist
+- a working Codex profile in `~/.codex/config.toml`
+
+### Codex-side setup
+
+MiniMax's official page provides a real Codex custom-provider example. The profile name is yours to choose. Use `minimax` below as an example; if you already created `m27`, keep using `m27`.
+
+```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.minimax]
+model = "codex-MiniMax-M2.5"
+model_provider = "minimax"
+```
+
+Then:
+
+```bash
+export MINIMAX_API_KEY="..."
+codex --profile minimax
+```
+
+### DeepScientist commands
+
+```bash
+ds doctor --codex-profile minimax
+ds --codex-profile minimax
+```
+
+### Persistent runner config
+
+```yaml
+codex:
+  enabled: true
+  binary: codex
+  config_dir: ~/.codex
+  profile: minimax
+  model: inherit
+```
+
+## 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。
@@ -89,6 +95,10 @@ ds latex install-runtime
 
 ## 2. 第一次运行 `ds` 前，先完成 Codex 配置
 
+这里有两条路径，二选一即可。
+
+### 2.1 默认 OpenAI 登录路径
+
 运行：
 
 ```bash
@@ -109,7 +119,29 @@ 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 minimax
+```
+
+然后用同一个 profile 去跑 DeepScientist：
+
+```bash
+ds doctor --codex-profile minimax
+```
+
+之后启动：
+
+```bash
+ds --codex-profile minimax
+```
+
+把这里的 `minimax` 替换成你真实的 profile 名，例如 `m27`、`glm`、`ark`、`bailian`。
+
+DeepScientist 会在启动前强制做一次真实的 Codex hello 探测。默认情况下，`~/DeepScientist/config/runners.yaml` 里的 runner 模型还是 `gpt-5.4`。如果你的 profile 希望模型由 profile 自己决定，请把 `runners.yaml` 里的 `model` 改成 `inherit`；或者直接使用 `--codex-profile <name>`，让这一轮启动自动继承 profile 对应的模型。
 
 ## 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
@@ -453,6 +454,15 @@ claude:
 - 页面标签：`Config directory`
 - 作用：runner 的全局配置目录，通常存放认证和全局配置。
 
+**`profile`**
+
+- 类型：`string`
+- 默认值：`""`
+- 页面标签：`Codex profile`
+- 作用：可选的 Codex profile 名称，会直接透传为 `codex --profile <name>`。
+- 当你的 Codex CLI 已经配置成 MiniMax、GLM、火山方舟、阿里百炼或其他 provider-backed 路径时，就在这里填写。
+- 临时使用说明：如果你不想持久化写配置，也可以保持这里为空，直接使用 `ds --codex-profile <name>` 启动。
+
 **`model`**
 
 - 类型：`string`
@@ -460,6 +470,7 @@ claude:
 - 页面标签：`Default model`
 - 作用：项目和单次请求没有覆盖时的默认模型。
 - 启动说明：DeepScientist 的 Codex 就绪探测会优先使用这里配置的模型。如果你的 Codex 账号无法访问它，DeepScientist 会自动回退到当前 Codex 默认模型，并持久化为 `model: inherit`。
+- provider-profile 说明：当 `profile` 已设置时，通常推荐使用 `model: inherit`，让 Codex profile 自己决定 provider 侧模型。
 
 **`model_reasoning_effort`**