@researai/deepscientist 1.5.12 → 1.5.14

package/docs/en/15_CODEX_PROVIDER_SETUP.md

@@ -25,12 +25,19 @@ ds
 
 ### 2. One-off provider profile
 
-Use this when you already have a named Codex profile such as `minimax`, `glm`, `ark`, or `bailian`.
+Use this when you already have a named Codex profile such as `m27`, `glm`, `ark`, or `bailian`.
 
 ```bash
-codex --profile minimax
-ds doctor --codex-profile minimax
-ds --codex-profile minimax
+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.
@@ -61,7 +68,7 @@ Important:
 | 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` |
+| 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 |
@@ -99,15 +106,65 @@ 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 installed
+- 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
 
-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`.
+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]
@@ -120,23 +177,50 @@ request_max_retries = 4
 stream_max_retries = 10
 stream_idle_timeout_ms = 300000
 
-[profiles.minimax]
-model = "codex-MiniMax-M2.5"
+[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
-export MINIMAX_API_KEY="..."
-codex --profile minimax
+codex --profile m27
 ```
 
 ### DeepScientist commands
 
 ```bash
-ds doctor --codex-profile minimax
-ds --codex-profile minimax
+ds doctor --codex-profile m27
+ds --codex-profile m27
 ```
 
 ### Persistent runner config
@@ -144,12 +228,26 @@ ds --codex-profile minimax
 ```yaml
 codex:
   enabled: true
-  binary: codex
+  binary: /tmp/codex057-wrapper
   config_dir: ~/.codex
-  profile: minimax
+  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.

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.
+- [05 TUI Guide](./05_TUI_GUIDE.md)
+  Read this if your main surface is the terminal and you want one end-to-end path through `ds --tui`, quests, connectors, and cross-surface work.
 - [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)

package/docs/zh/00_QUICK_START.md

@@ -79,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
@@ -124,25 +124,44 @@ ds doctor
 如果你已经在 MiniMax、GLM、火山方舟、阿里百炼或其他 provider 上配置了一个命名的 Codex profile，请先在终端里确认这个 profile 本身可用：
 
 ```bash
-codex --profile minimax
+codex --profile m27
 ```
 
 然后用同一个 profile 去跑 DeepScientist：
 
 ```bash
-ds doctor --codex-profile minimax
+ds doctor --codex-profile m27
 ```
 
 之后启动：
 
 ```bash
-ds --codex-profile minimax
+ds --codex-profile m27
 ```
 
-把这里的 `minimax` 替换成你真实的 profile 名，例如 `m27`、`glm`、`ark`、`bailian`。
+如果你这一轮还想强制指定某一个 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

@@ -444,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`。
 
@@ -462,6 +464,7 @@ claude:
 - 作用：可选的 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`**
 
@@ -480,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`**