@researai/deepscientist 1.5.9 → 1.5.12

package/docs/zh/02_START_RESEARCH_GUIDE.md

@@ -16,6 +16,92 @@
 3. 绑定一个可选的可复用 baseline
 4. 持久化 `startup_contract`，供后续 prompt builder 持续读取
 
+## 实战示例：整理后的 quest 025 启动输入
+
+理解这个弹窗最快的方法，不是先背字段定义，而是先看一个真实例子。
+
+下面这个例子来自 quest `025` 的真实启动输入，但我做了必要的整理，让它更适合公开文档和第一次填写时参考。这个任务的目标是：
+
+- 复现官方的 Mandela-Effect baseline
+- 保持原论文任务与评测协议
+- 研究在混合正确 / 错误社会信号下，如何实现更强的 truth-preserving collaboration
+- 使用两个本地 OpenAI-compatible 端点提高吞吐量
+
+### 当前前端里先填的短字段
+
+| 弹窗字段 | 示例值 | 为什么这样填 |
+|---|---|---|
+| `Project title` | `Mandela-Effect Reproduction and Truth-Preserving Collaboration` | 标题清楚，后面在卡片、工作区和搜索里都好认 |
+| `Project ID` | 留空，或者填 `025` | 想自动编号就留空；只有你明确要固定编号时才手动填写 |
+| `Connector delivery` | 第一次建议 `Local only`，如果 QQ 已配置也可以选一个目标 | 当前前端对每个 quest 最多只允许绑定一个外部 connector 目标 |
+| `Reusable baseline` | 第一次可留空；如果官方 baseline 已经导入 registry，就直接选它 | 一旦选中，自动推导的 `baseline_mode` 会变成 `existing` |
+| `Research paper` | `On` | 让项目保持分析和论文式产出在范围内 |
+| `Research intensity` | `Balanced` | 先把 baseline 立稳，再探索一个合理方向 |
+| `Decision mode` | `Autonomous` | 普通路线选择默认自己推进，不把常规决策丢回给用户 |
+| `Launch mode` | `Standard` | 按默认科研主线启动 |
+| `Language` | `English` | 默认用英文组织 kickoff prompt 和用户侧产物 |
+
+### 同一个例子里的长文本字段
+
+`Primary research request`
+
+```text
+Please reproduce the official Mandela-Effect repository and paper, then study how to improve truth-preserving collaboration under mixed correct and incorrect social signals.
+
+The core research question is: how can a multi-agent system remain factually robust under social influence while still learning from correct peers?
+
+Keep the task definition and evaluation protocol aligned with the original work. Focus on prompt-based or system-level methods that improve truth preservation without simply refusing all social information.
+```
+
+`Baseline links`
+
+```text
+https://github.com/bluedream02/Mandela-Effect
+```
+
+`Reference papers / repos`
+
+```text
+https://arxiv.org/abs/2602.00428
+```
+
+`Runtime constraints`
+
+```text
+- Keep the task definition and evaluation protocol aligned with the official baseline unless a change is explicitly justified.
+- Use two OpenAI-compatible local inference endpoints for throughput:
+  - `http://127.0.0.1:8004/v1`
+  - `http://127.0.0.1:8008/v1`
+- Use API key `1234` and model `/model/gpt-oss-120b` on both endpoints.
+- Keep generation settings close to the baseline unless a justified adjustment is required.
+- Implement asynchronous execution, automatic retry on request failure, and resumable scripts.
+- Split requests across both endpoints so throughput stays high without overloading the service.
+- Record failed, degraded, or inconclusive runs honestly instead of hiding them.
+```
+
+`Goals`
+
+```text
+1. Restore and verify the official Mandela-Effect baseline as a trustworthy starting point.
+2. Measure key metrics and failure modes on the designated `gpt-oss-120b` setup.
+3. Propose at least one literature-grounded direction for stronger truth-preserving collaboration.
+4. Produce experiment and analysis artifacts that are strong enough to support paper writing.
+```
+
+### 这个例子在前端里会自动推导出什么
+
+如果 `Reusable baseline` 留空，且 `Research intensity` 选择 `Balanced`，当前前端会自动推导：
+
+- `scope = baseline_plus_direction`
+- `baseline_mode = restore_from_url`
+- `resource_policy = balanced`
+- `time_budget_hours = 24`
+- `git_strategy = semantic_head_plus_controlled_integration`
+
+如果你已经选中了一个可复用 baseline，那么只会有一项不同：
+
+- `baseline_mode = existing`
+
 ## 当前前端数据模型
 
 ### `StartResearchTemplate`
@@ -29,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
@@ -83,6 +177,12 @@ type StartResearchContractFields = {
   title,
   goal: compiled_prompt,
   quest_id,
+  requested_connector_bindings: [
+    {
+      connector,
+      conversation_id
+    }
+  ],
   requested_baseline_ref: {
     baseline_id,
     variant_id
@@ -95,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,
@@ -104,6 +207,7 @@ type StartResearchContractFields = {
     objectives: string[],
     baseline_urls: string[],
     paper_urls: string[],
+    review_materials: string[],
     entry_state_summary,
     review_summary,
     custom_brief,
@@ -138,6 +242,26 @@ type StartResearchContractFields = {
 
 - 声明后续 kickoff 和交流默认偏好的语言。
 
+### Connector 投递
+
+**`requested_connector_bindings`**
+
+- 这是创建项目时随请求一起提交的字段，但不在 `startup_contract` 里面。
+- 当前前端对每个 quest 最多只允许一个外部 connector 目标。
+- 典型结构如下：
+
+```ts
+[
+  {
+    connector: 'qq',
+    conversation_id: 'qq:private:openid-123'
+  }
+]
+```
+
+- 如果你保持项目仅本地运行，这个数组就是空的。
+- 如果你选中的那个目标已经绑定在别的 quest 上，当前项目创建时会把旧绑定替换掉。
+
 ### Baseline 与参考资料
 
 **`baseline_id`**
@@ -153,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[]`。
 
 ### 约束与目标
@@ -213,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`**
 
 - 用自然语言概括当前已经存在什么。
@@ -275,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`
@@ -374,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",
@@ -387,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."
@@ -397,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` 不只影响第一轮，还会影响后续路由判断。
 
 ## 修改检查清单

package/docs/zh/04_LINGZHU_CONNECTOR_GUIDE.md

@@ -1,230 +1,99 @@
-# 04 Lingzhu 连接器指南：如何配置 Lingzhu
+# 04 Lingzhu 连接器指南：把 Rokid Glasses 绑定到 DeepScientist
 
-本文说明如何在 `Settings > Connectors > Lingzhu` 中完成 Lingzhu 伴生端点配置。
+Lingzhu 现在是一个极简的一步式绑定流程。
 
-适用范围：
+DeepScientist 会直接在自己的 daemon / Web 端口上提供 Lingzhu 兼容路由：
 
-- 仅包含配置教程
-- 面向 OpenClaw 兼容的 Lingzhu bridge 参数
-- 本地健康检查与 SSE 冒烟测试
-- 说明需要把哪些值填回 Lingzhu 平台
+- `GET /metis/agent/api/health`
+- `POST /metis/agent/api/sse`
 
-本文不展开讨论云部署架构。你只需要：
+真实设备要想接入，Rokid 平台里填写的地址必须就是外部可以访问到的 DeepScientist 公网地址，不能是 `127.0.0.1`、`localhost` 或私网地址。
 
-- 一个已经跑起来的 OpenClaw gateway
-- 一个眼镜端可访问的公网 IP 或公网域名
+参考：
 
-参考来源：
+- Rokid 开发者论坛：https://forum.rokid.com/post/detail/2831
+- Rokid 智能体平台：https://agent-develop.rokid.com/space
 
-- Rokid 论坛配置页面：https://forum.rokid.com/post/detail/2831
-- 仓库内置 bridge 目录：`assets/connectors/lingzhu/openclaw-bridge`
-- 仓库内置 OpenClaw 配置模板：`assets/connectors/lingzhu/openclaw.lingzhu.config.template.json`
+## 1. 绑定前提
 
-## 1. DeepScientist 现在会自动提供什么
+先确认：
 
-Lingzhu 设置卡会自动生成并校验：
+- DeepScientist 已正常启动
+- 你当前打开的 DeepScientist 网页地址就是最终对外可访问的公网地址
+- 如果当前网页地址是本地地址或私网地址，Lingzhu 不应直接保存
 
-- 本地 health URL
-- 本地 SSE URL
-- 公网 SSE URL
-- `auth_ak`
-- OpenClaw 配置片段
-- 本地探测 `curl`
+## 2. 页面里现在保留什么
 
-当前随包 bridge 还额外做了三件事：
+`Settings > Connectors > Lingzhu` 现在只保留必要内容：
 
-- 在模型真正开始生成前，先自动发送一条可见的“已收到”回执
-- 保留 SSE 注释心跳
-- 在上游长时间静默时补发轻量可见进度心跳
+- 一个 `Add Lingzhu (Rokid Glasses)` 入口
+- Rokid 平台创建表单截图
+- 自动生成的可复制字段
+- 中文绑定指引
+- 保存按钮
 
-需要明确的是：
+不再要求你先手动改 host、port、agent、OpenClaw 配置片段或额外调试步骤。
 
-- Lingzhu 在 DeepScientist 里被视为 companion endpoint
-- 它不是像 QQ 那样的完整双向聊天 connector
+## 3. 点击后会自动生成什么
 
-## 2. 开始前请先确认
+点击 `Add Lingzhu (Rokid Glasses)` 后，弹窗会自动显示这些值，并且每一项都可以直接复制：
 
-建议先确认下面几项：
+- 自定义智能体ID
+- 自定义智能体url
+- 自定义智能体AK
+- 智能体名称
+- 类别
+- 功能介绍
+- 开场白
+- 入参类型
+- 图标 PNG 地址
 
-- DeepScientist 已成功安装并运行
-- 本地 OpenClaw gateway 已启动
-- 你知道 OpenClaw HTTP gateway 的端口，通常是 `18789`
-- 你已经有公网 IP 或公网域名
+其中：
 
-重要提醒：
+- `Custom agent URL` 会自动生成成 `https://<你的公网地址>/metis/agent/api/sse`
+- `AK` 会自动随机生成，并在保存后长期复用，不会每次都变
+- logo 使用 DeepScientist 的 PNG 资源，方便直接上传到 Rokid
 
-- `127.0.0.1` 只能用于本地健康检查
-- Lingzhu 设备侧必须访问公网地址
+![Rokid 平台创建三方智能体](../images/lingzhu/rokid-agent-platform-create.png)
 
-## 3. 打开设置页
+## 4. 用户怎么做
 
-打开：
+在 Rokid 平台：
 
-- `Settings > Connectors > Lingzhu`
+1. 打开 `项目开发 -> 三方智能体 -> 创建`
+2. 选择“自定义智能体”
+3. 把弹窗里自动生成的字段逐项复制过去
+4. 图标上传 DeepScientist PNG logo
+5. Rokid 表单填写完成后，回到 DeepScientist 点击保存
 
-页面会分成几块：
+保存完成后，Lingzhu 绑定就算完成。
 
-- 网关端点
-- 鉴权与身份
-- 自动生成值
-- 探测与校验
-- 高级调试
+## 5. 后续怎么用
 
-![Lingzhu 设置概览](../images/lingzhu/lingzhu-settings-overview.svg)
+眼镜侧后续只需要请求：
 
-## 4. 先填写端点
+- `POST /metis/agent/api/sse`
 
-推荐值如下：
+并带上：
 
-| 字段 | 推荐值 | 说明 |
-| --- | --- | --- |
-| `Enabled` | `true` | 开启 companion 配置 |
-| `Transport` | `openclaw_sse` | 固定值，不要改 |
-| `Local host` | `127.0.0.1` | 只用于本地探测 |
-| `Gateway port` | `18789` | 与 OpenClaw gateway 保持一致 |
-| `Public base URL` | `http://<公网IP>:18789` | 必须是眼镜端真正能访问到的地址 |
+- `Authorization: Bearer <保存后的AK>`
 
-如果你不确定本地端点应该怎么填，可以直接点击：
+使用规则：
 
-- `Use local defaults`
+- 新任务必须以 `我现在的任务是 ...` 开头
+- 只有这个前缀后面的正文才会被当成新的 DeepScientist 任务
+- 如果只是想继续拿中间进展，不要重复这个前缀，直接说 `找DeepScientist` 或 `继续`
 
-## 5. 生成 AK 和身份值
+## 6. 常见问题
 
-建议如下：
+### 为什么不能用 `127.0.0.1`
 
-| 字段 | 推荐值 |
-| --- | --- |
-| `Auth AK` | 点击 `Generate AK` 自动生成 |
-| `Agent ID` | `main` |
-| `Lingzhu system prompt` | 可选 |
+因为 Rokid 平台和外部设备访问不到你的本地回环地址。Lingzhu 只应该注册公网地址。
 
-需要保证下面两处完全一致：
+### 为什么要自动生成 `AK`
 
-- OpenClaw Lingzhu 插件配置
-- Lingzhu 平台配置
+因为 `AK` 本质上就是这个外部接入口的 Bearer 密钥。系统生成并持久化，比手填更稳定，也更不容易出错。
 
-也就是：
+### 保存后还需要再手动配很多参数吗
 
-- `auth_ak`
-- `agent_id`
-
-## 6. 使用自动生成值
-
-DeepScientist 会直接展示你需要复制的内容：
-
-- 本地 health URL
-- 本地 SSE URL
-- 公网 SSE URL
-- OpenClaw 配置片段
-- 探测 curl
-
-其中真正要填回 Lingzhu 平台的是：
-
-- 公网 SSE URL
-- AK
-
-![Lingzhu 平台填写值](../images/lingzhu/lingzhu-platform-values.svg)
-
-## 7. 更新 OpenClaw
-
-你可以直接使用：
-
-- 设置页里自动生成的配置片段
-- 或仓库内置模板 `assets/connectors/lingzhu/openclaw.lingzhu.config.template.json`
-
-内置 bridge 的安装命令为：
-
-```bash
-openclaw plugins install ./assets/connectors/lingzhu/openclaw-bridge
-```
-
-至少应确保 OpenClaw 开启：
-
-```json
-{
-  "gateway": {
-    "port": 18789,
-    "http": {
-      "endpoints": {
-        "chatCompletions": {
-          "enabled": true
-        }
-      }
-    }
-  }
-}
-```
-
-DeepScientist 也会自动把完整的 Lingzhu 插件配置片段生成出来：
-
-![OpenClaw 配置片段](../images/lingzhu/lingzhu-openclaw-config.svg)
-
-## 8. 执行本地探测
-
-保存参数后，点击：
-
-- `Run Lingzhu probe`
-
-DeepScientist 会依次执行：
-
-1. `GET /metis/agent/api/health`
-2. `POST /metis/agent/api/sse`
-
-理想结果：
-
-- `Connection = reachable`
-- `Auth = ready`
-- 探测结果没有报错
-
-## 9. 需要填回 Lingzhu 平台的值
-
-只需要填：
-
-- `Public SSE URL`
-- `Auth AK`
-
-不要填：
-
-- `127.0.0.1`
-- 任意本地机器名
-
-## 10. 常见失败原因
-
-### Health 显示 offline
-
-通常说明：
-
-- OpenClaw 没启动
-- `gateway_port` 填错
-- `local_host` 填错
-
-### SSE probe 失败
-
-通常说明：
-
-- `auth_ak` 不一致
-- Lingzhu SSE 路径没有暴露出来
-- OpenClaw 的 `chatCompletions.enabled` 还没打开
-
-### 本地探测通过，但设备仍无法接入
-
-通常说明：
-
-- `Public base URL` 不是公网可达地址
-- 防火墙或反向代理还没有放行端口
-
-## 11. 说明
-
-这块配置保持 registry-first：
-
-- Lingzhu 仍然落在 `connectors.yaml`
-- 自动生成值来自同一份 structured config
-- 校验、测试、前端渲染都消费同一条 connector 记录
-
-对于长任务，更稳妥的实际策略是：
-
-- 先由 bridge 自动回执
-- 在上游静默阶段由 bridge 补发可见进度心跳
-- 通过 `per_user` 会话连续保持多轮上下文
-
-这会明显改善兼容性，但仍不能消除 Lingzhu 平台单次请求超时的硬限制。
+不需要。Lingzhu 现在的目标就是让用户只看到必要字段，复制过去，然后保存完成。

package/docs/zh/09_DOCTOR.md

@@ -10,21 +10,43 @@
    npm install -g @researai/deepscientist
    ```
 
-2. 先直接尝试启动：
+2. 先确保 Codex 自己已经可用：
+
+   默认 OpenAI 路径：
+
+   ```bash
+   codex --login
+   ```
+
+   provider-backed profile 路径：
+
+   ```bash
+   codex --profile minimax
+   ```
+
+   如果 `codex` 缺失，请显式修复：
+
+   ```bash
+   npm install -g @openai/codex
+   ```
+
+   如果你的 Codex CLI 版本没有 `--login`，就运行 `codex` 并在交互式界面里完成认证。
+
+3. 先直接尝试启动：
 
    ```bash
    ds
    ```
 
-3. 如果启动失败，或者看起来不正常，再运行：
+4. 如果启动失败，或者看起来不正常，再运行：
 
    ```bash
    ds doctor
    ```
 
-4. 从上到下阅读诊断结果，优先修复失败项。
+5. 从上到下阅读诊断结果，优先修复失败项。
 
-5. 修完后重新运行 `ds doctor`，直到检查通过，再运行 `ds`。
+6. 修完后重新运行 `ds doctor`，直到检查通过，再运行 `ds`。
 
 ## `ds doctor` 会检查什么
 
@@ -49,16 +71,57 @@
 npm install -g @researai/deepscientist
 ```
 
+如果装完以后 `codex` 仍然不可用，请显式安装：
+
+```bash
+npm install -g @openai/codex
+```
+
 ### 已安装 Codex，但还没有登录
 
 运行：
 
 ```bash
-codex
+codex --login
 ```
 
+如果你的 Codex CLI 版本没有 `--login`，就运行 `codex` 并在交互式界面里完成认证。
+
 先完成一次登录，再重新执行 `ds doctor`。
 
+### Codex profile 在终端里可用，但 DeepScientist 还是失败
+
+请显式让 DeepScientist 使用同一个 profile：
+
+```bash
+ds doctor --codex-profile minimax
+ds --codex-profile minimax
+```
+
+把这里的 `minimax` 换成你的真实 profile 名，例如 `m27`、`glm`、`ark`、`bailian`。
+
+同时检查：
+
+- 启动 DeepScientist 的这个 shell 中，provider API key 仍然可见
+- 该 profile 指向的是 provider 的 Coding Plan endpoint，而不是普通通用 API endpoint
+- 如果模型应该由 profile 自己决定，请在 `~/DeepScientist/config/runners.yaml` 中使用 `model: inherit`
+
+### 当前配置的 Codex 模型不可用
+
+DeepScientist 会在启动前强制做一次真实的 Codex hello 探测。当前版本里，这个探测会先使用：
+
+```text
+~/DeepScientist/config/runners.yaml
+```
+
+里配置的 runner 模型，默认值是 `gpt-5.4`。如果你的 Codex 账号或本地 CLI 配置不能访问这个模型，DeepScientist 现在会自动重试当前 Codex 默认模型，并把后续运行持久化为 `model: inherit`。如果你仍然想指定某个具体模型，再手动改配置并重新执行：
+
+```bash
+ds doctor
+```
+
+对于 provider-backed 的 Codex profile，通常建议直接使用 `model: inherit`。
+
 ### 没有安装 `uv`
 
 正常情况下，第一次运行 `ds` 会自动在本地安装 `uv`。如果自动安装失败，再手动执行：