@researai/deepscientist 1.5.17 → 1.6.0

package/docs/en/33_WORKSPACE_EXPLORER_QA.md

@@ -0,0 +1,121 @@
+# Workspace Explorer Q&A
+
+This page explains a common surprise: a file or folder is visible in the terminal, but it does not appear in the Web Explorer or Search panel.
+
+## 1. Is Explorer the same as the local quest root?
+
+Not always.
+
+The desktop `FILES` view shows the backend's active workspace root, not always `<home>/quests/<id>`. The active root resolves in this order:
+
+1. `current_workspace_root` in `.ds/research_state.json`
+2. `research_head_worktree_root` in `.ds/research_state.json`
+3. the quest root
+
+During an analysis or paper branch, the active root may be:
+
+```text
+<quest_root>/.ds/worktrees/<branch-worktree-name>
+```
+
+If you manually create a folder in the quest root while Explorer is pointed at a worktree, the folder may not appear in Explorer.
+
+## 2. Which paths are hidden?
+
+The desktop `FILES` view recursively lists the active workspace root, but skips:
+
+- `.git`
+- `.ds/worktrees` when the active root is the quest root
+- `__pycache__`
+- `.pytest_cache`
+
+If the active workspace root itself is a `.ds/worktrees/<name>` directory, Explorer treats that worktree as the root and shows its contents.
+
+Mobile uses a smaller profile and may hide or truncate `.ds`, `artifacts`, `tmp`, `userfiles`, and deep directories.
+
+## 3. What is the difference between `FILES`, `SCOPE`, and `SNAPSHOT`?
+
+- `FILES`: live tree for the current active workspace root.
+- `SCOPE`: files related to the selected graph node, stage, diff, or reveal target.
+- `SNAPSHOT`: a read-only git revision or commit view.
+
+To check whether a terminal-created file is visible, switch to `FILES` and refresh.
+
+## 4. Will a terminal-created folder appear automatically?
+
+No. DeepScientist does not currently watch the local filesystem.
+
+After creating files manually:
+
+1. Make sure they are under the current active workspace root.
+2. Switch Explorer to `FILES`.
+3. Click refresh or reload the page.
+
+Empty folders can appear in Explorer, but Search usually cannot find empty folders because it mainly scans file paths and readable text content.
+
+## 5. Why can Search miss something?
+
+Search scans files under the active workspace root. It does not search every worktree at once.
+
+It also skips large files, binary files, and Explorer-filtered paths. Use plain text queries such as:
+
+```text
+run_probe
+experiments/analysis
+```
+
+Do not use shell glob syntax for normal searches. Older frontend code wrapped queries as `*term*`; newer code tolerates that legacy shape, but plain keywords are preferred.
+
+## 6. How do I check what Explorer is looking at?
+
+Use the Explorer API:
+
+```bash
+curl -s "http://127.0.0.1:<port>/api/quests/<quest_id>/explorer" | jq -r '.quest_root'
+```
+
+Or inspect the research state:
+
+```bash
+cat <quest_root>/.ds/research_state.json
+```
+
+Check:
+
+- `current_workspace_root`
+- `research_head_worktree_root`
+- `paper_parent_worktree_root`
+- `analysis_parent_worktree_root`
+
+If your terminal `pwd` differs from the Explorer API's `quest_root`, it is normal for Web Explorer not to show that file.
+
+## 7. How should I hand files to the agent?
+
+The most reliable option is to ask the agent to write them in the current active worktree:
+
+```text
+Create experiments/analysis/... under the current active worktree,
+write the scripts, results, and report there, then record the artifact and update PLAN/CHECKLIST.
+```
+
+Files created through Web upload, new file, or editor save also go through backend APIs and are written to the active workspace root.
+
+## 8. Does writing a file mean it is in Git?
+
+No.
+
+A file created inside a git worktree appears in that worktree's `git status`, often as untracked. It enters Git history only after:
+
+- `git add` / `git commit`
+- or a DeepScientist artifact / checkpoint flow records it
+
+Also note that a `.ds/worktrees/<name>` worktree has its own git status; it may not appear in the quest root's `git status`.
+
+## 9. Recommended checklist
+
+1. Switch Web Explorer to `FILES`.
+2. Refresh Explorer.
+3. Check `.quest_root` from the Explorer API.
+4. Compare that path with terminal `pwd`.
+5. If the file is in another worktree, ask the agent to merge or copy it into the current active worktree.
+6. If it should persist, ask the agent to record an artifact or checkpoint.

package/docs/en/91_DEVELOPMENT.md

@@ -67,6 +67,33 @@ npm --prefix src/tui install
 npm --prefix src/tui run build
 ```
 
+Run the TUI with route/render diagnostics:
+
+```bash
+ds --tui --debug --debug-log /tmp/deepscientist_tui_debug.jsonl
+```
+
+Use this when validating command routing, config editor behavior, or Web/TUI parity. Debug JSONL must stay redacted for config editor buffers and secret-like fields; if a TUI change adds a new input surface, add or update an E2E assertion for that redaction boundary.
+
+Run Web Settings with the browser debug inspector:
+
+```text
+/settings/connector/qq?debug=1
+```
+
+or:
+
+```js
+localStorage.setItem('deepscientist.debug', '1')
+localStorage.setItem('deepscientist.debug.log', '1')
+```
+
+The Web inspector must stay hidden unless debug is enabled. It must not include raw config document content or secret-like structured config fields in the snapshot. Focused regression check:
+
+```bash
+cd src/ui && E2E_BASE_URL=http://127.0.0.1:21888/ui npx playwright test e2e/web-debug.spec.ts --project=chromium
+```
+
 ## Test Commands
 
 Quick Python test run:
@@ -92,6 +119,8 @@ Before publishing or cutting a release, verify:
 3. `npm pack --dry-run --ignore-scripts` succeeds.
 4. README and linked docs match the current runtime behavior.
 5. Any new config, route, or quest-state fields have matching tests.
+6. Any TUI command or surface change updates the debug snapshot mapping and keeps `--debug-log` free of raw secrets.
+7. Confirm any new bundled third-party material has an explicit provenance note and license-compatible release path.
 
 ## Managed Runtime Tools
 

package/docs/en/99_ACKNOWLEDGEMENTS.md

@@ -6,29 +6,34 @@ DeepScientist was shaped by many prior systems, open-source efforts, and researc
 
 We especially thank the following projects for their ideas, research direction, and systems inspiration:
 
-- The AI Scientist
-- The AI Scientist v2
-- AlphaEvolve
-- OpenEvolve
-- EvoScientist
-- Orchestra-Research
-- Orchestra-Research/AI-Research-SKILLs
-- Overleaf / overleaf/overleaf
-- Monaco Editor / microsoft/monaco-editor
-- Novel / steven-tey/novel
-
-These projects have been important references for thinking about automated research, open-ended exploration, evolutionary search, experiment organization, long-horizon research agents, collaborative LaTeX editing workflows, browser-based code editing experiences, and rich notebook-style writing interactions.
+- [The AI Scientist](https://github.com/SakanaAI/AI-Scientist)
+- [The AI Scientist v2](https://github.com/SakanaAI/AI-Scientist-v2)
+- [AlphaEvolve](https://deepmind.google/blog/alphaevolve-a-gemini-powered-coding-agent-for-designing-advanced-algorithms/)
+- [OpenEvolve](https://github.com/algorithmicsuperintelligence/openevolve)
+- [EvoScientist](https://github.com/EvoScientist/EvoScientist)
+- [AutoSOTA](https://github.com/tsinghua-fib-lab/AutoSOTA)
+- [Orchestra-Research](https://www.orchestra-research.com/)
+- [Orchestra-Research/AI-Research-SKILLs](https://github.com/Orchestra-Research/AI-Research-SKILLs)
+- [Overleaf / overleaf/overleaf](https://github.com/overleaf/overleaf)
+- [Monaco Editor / microsoft/monaco-editor](https://github.com/microsoft/monaco-editor)
+- [Novel / steven-tey/novel](https://github.com/steven-tey/novel)
+- [paper-plot-skills / Trae1ounG/paper-plot-skills](https://github.com/Trae1ounG/paper-plot-skills)
+- [nature-skills / Yuan1z0825/nature-skills](https://github.com/Yuan1z0825/nature-skills)
+- [FermiLink / TaoELi/FermiLink](https://github.com/TaoELi/FermiLink)
+
+These projects have been important references for thinking about automated research, open-ended exploration, evolutionary search, experiment organization, long-horizon research agents, collaborative LaTeX editing workflows, browser-based code editing experiences, rich notebook-style writing interactions, paper-figure generation and polish workflows, Nature-style scientific writing, data, figure, and presentation skills, and autonomous scientific simulation / package-knowledge workflows.
 
 ## Personal acknowledgements
 
 We also sincerely thank the following researchers, collaborators, and supporters:
 
-- Shichen Li
-- Guangsheng Bao
-- Fuchen Shen
-- Wenyang Gao
-- Luodan Zhang
-- Junshu Pan
-- Panzhong Lu
+- [Shichen Li](https://www.google.com/search?q=%22Shichen+Li%22)
+- [Siqi Wen](https://www.google.com/search?q=%22Siqi+Wen%22)
+- [Guangsheng Bao](https://www.google.com/search?q=%22Guangsheng+Bao%22)
+- [Fuchen Shen](https://www.google.com/search?q=%22Fuchen+Shen%22)
+- [Wenyang Gao](https://www.google.com/search?q=%22Wenyang+Gao%22)
+- [Luodan Zhang](https://www.google.com/search?q=%22Luodan+Zhang%22)
+- [Junshu Pan](https://www.google.com/search?q=%22Junshu+Pan%22)
+- [Panzhong Lu](https://www.google.com/search?q=%22Panzhong+Lu%22)
 
 We are grateful to all of the above projects and individuals.

package/docs/en/README.md

@@ -28,20 +28,37 @@ AI Scientist and AutoFigure projects worth exploring alongside DeepScientist:
 
 This page is the shortest path to the right document.
 
+Built-in runners today:
+
+- `codex`
+- `claude`
+- `kimi`
+- `opencode`
+
 ## If you are new
 
 - [00 Quick Start](./00_QUICK_START.md)
-  Start here if you want to install DeepScientist, launch it locally, and create your first project.
+  Start here if you want to install DeepScientist, choose between Codex / Claude Code / Kimi Code / OpenCode, launch it locally, and create your first project.
 - [20 Workspace Modes Guide](./20_WORKSPACE_MODES_GUIDE.md)
   Read this if you want to choose correctly between Copilot and Autonomous before creating a project.
-- [19 Local Browser Auth](./19_LOCAL_BROWSER_AUTH.md)
+- [31 Local Browser Auth](./31_LOCAL_BROWSER_AUTH.md)
   Read this if you want to understand the local password prompt, where to find the password, and how to disable it.
+- [32 Windows + WSL2 Deployment Guide](./32_WINDOWS_WSL2_DEPLOYMENT_GUIDE.md)
+  Read this if you are on Windows and want the recommended WSL2-based deployment path instead of guessing the environment setup.
 - [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.
+  Read this if your main surface is the terminal and you want one end-to-end path through `ds --tui`, quests, connectors, cross-surface work, and TUI debug snapshots.
 - [15 Codex Provider Setup](./15_CODEX_PROVIDER_SETUP.md)
-  Read this when you want to run DeepScientist through MiniMax, GLM, Volcengine Ark, Alibaba Bailian Coding Plan, or another Codex profile.
+  Read this when you want to run DeepScientist through OpenAI, Ollama, MiniMax, GLM, Volcengine Ark, Alibaba Bailian Coding Plan, or another Codex profile. Gemini through Codex is an advanced experiment; OpenCode is usually the better Gemini route.
+- [24 Claude Code Setup](./24_CLAUDE_CODE_PROVIDER_SETUP.md)
+  Read this when Claude Code already works on your machine and you want DeepScientist to reuse it directly, or when you want to use Ollama through its Anthropic-compatible API.
+- [27 Kimi Code Setup](./27_KIMI_CODE_PROVIDER_SETUP.md)
+  Read this when the official Kimi Code CLI already works on your machine and you want DeepScientist to use it as a separate builtin runner.
+- [25 OpenCode Setup](./25_OPENCODE_PROVIDER_SETUP.md)
+  Read this when OpenCode already works on your machine and you want DeepScientist to reuse its provider/model configuration, especially for Gemini or Ollama.
 - [21 Local Model Backends Guide](./21_LOCAL_MODEL_BACKENDS_GUIDE.md)
-  Read this if you want to run DeepScientist through local OpenAI-compatible backends such as vLLM, Ollama, or SGLang.
+  Read this if you want to run DeepScientist through local model backends such as vLLM, Ollama, or SGLang and need to choose between Codex, Claude Code, and OpenCode.
+- [26 Citation And Attribution](./26_CITATION_AND_ATTRIBUTION.md)
+  Read this if DeepScientist materially helped a paper or report and you want the preferred citation, acknowledgment wording, and attribution boundary.
 - [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)
@@ -54,14 +71,22 @@ This page is the shortest path to the right document.
 - [20 Workspace Modes Guide](./20_WORKSPACE_MODES_GUIDE.md)
   Use this when the main question is not “how do I fill the form?” but “should this project start as Copilot or Autonomous?”.
 - [01 Settings Reference](./01_SETTINGS_REFERENCE.md)
-  Use this when you need to configure runners, connectors, runtime defaults, or home paths.
+  Use this when DeepScientist is already running and you want to configure runtime defaults, models, connectors, baselines, DeepXiv, extensions, or MCP from the visual Settings page before touching raw YAML.
+- [30 Settings Control Center Guide](./30_SETTINGS_CONTROL_CENTER_GUIDE.md)
+  Use this when the question is not configuration but runtime supervision: summary, hardware, diagnostics, errors, logs, quests, repairs, controllers, stats, or search.
 - [11 License And Risk Notice](./11_LICENSE_AND_RISK.md)
   Read this first if you care about the license boundary, server safety, fabricated outputs, connector leakage, and public exposure risk.
+- [26 Citation And Attribution](./26_CITATION_AND_ATTRIBUTION.md)
+  Use this when the question is not runtime risk but how to cite or acknowledge DeepScientist fairly in research outputs.
 
 ## If you want to collaborate through external surfaces
 
 - [16 Telegram Connector Guide](./16_TELEGRAM_CONNECTOR_GUIDE.md)
   Bind Telegram through the built-in polling runtime and continue quests from bot chats.
+- [28 Discord Connector Guide](./28_DISCORD_CONNECTOR_GUIDE.md)
+  Configure the built-in Discord gateway connector from the Settings page and keep the workflow visual-first.
+- [29 Slack Connector Guide](./29_SLACK_CONNECTOR_GUIDE.md)
+  Configure the built-in Slack Socket Mode connector from the Settings page after launch.
 - [17 WhatsApp Connector Guide](./17_WHATSAPP_CONNECTOR_GUIDE.md)
   Bind WhatsApp through the local-session runtime and continue quests from local chat sessions.
 - [18 Feishu Connector Guide](./18_FEISHU_CONNECTOR_GUIDE.md)
@@ -90,14 +115,26 @@ This page is the shortest path to the right document.
 
 - [09 Doctor](./09_DOCTOR.md)
   Start here for diagnostics and common runtime problems.
+- [33 Workspace Explorer Q&A](./33_WORKSPACE_EXPLORER_QA.md)
+  Check this when files or folders exist in the terminal but do not appear in Web Explorer or Search; it explains active worktrees, `FILES` / `SCOPE`, refresh behavior, and Git status boundaries.
+- [30 Settings Control Center Guide](./30_SETTINGS_CONTROL_CENTER_GUIDE.md)
+  Use this when you want the operator view of summary, hardware, diagnostics, errors, logs, quests, repairs, controllers, stats, and search.
 - [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.
+- [24 Claude Code Setup](./24_CLAUDE_CODE_PROVIDER_SETUP.md)
+  Check this if the problem is likely in your Claude Code login, config directory, permission mode, or Anthropic-compatible gateway setup.
+- [27 Kimi Code Setup](./27_KIMI_CODE_PROVIDER_SETUP.md)
+  Check this if the problem is likely in your Kimi Code login, `~/.kimi` home, agent selection, or `--yolo` / thinking configuration.
+- [25 OpenCode Setup](./25_OPENCODE_PROVIDER_SETUP.md)
+  Check this if the problem is likely in your OpenCode provider login, config file, model selection, agent, or variant setup.
 - [21 Local Model Backends Guide](./21_LOCAL_MODEL_BACKENDS_GUIDE.md)
   Check this if the problem is specifically about local OpenAI-compatible backends and whether they support `/v1/responses`.
 - [01 Settings Reference](./01_SETTINGS_REFERENCE.md)
   Check this if the problem is likely caused by config, credentials, or connector setup.
 
 ## If you are developing DeepScientist
+- [23 BenchStore GitHub Releases Spec](./23_BENCHSTORE_GITHUB_RELEASES_SPEC.md)
+  Read this when you want to publish BenchStore benchmark source packages on GitHub Releases and make the frontend Download flow work for users.
 
 - [90 Architecture](./90_ARCHITECTURE.md)
   High-level system contracts and repository structure.
@@ -109,5 +146,5 @@ This page is the shortest path to the right document.
 Welcome to join the WeChat group for discussion.
 
 <p align="center">
-  <img src="../../assets/readme/wechat4.jpg" alt="DeepScientist WeChat group" width="360" />
+  <img src="../../assets/readme/wechat6.jpg" alt="DeepScientist WeChat group" width="360" />
 </p>

package/docs/zh/00_QUICK_START.md

@@ -36,9 +36,11 @@
 建议你先准备好这些：
 
 - 安装好 Node.js `>=18.18` 和 npm `>=9`；请优先参考官方页面安装：https://nodejs.org/en/download
-- 一条已经可用的 Codex 路径：
-  - 默认 OpenAI 登录路径：`codex login`（或直接运行 `codex`）
-  - provider-backed 路径：一个已经可用的 Codex profile，例如 `minimax`、`glm`、`ark`、`bailian`
+- 一条已经可用的 runner 路径：
+  - `codex` 应先在你的 shell 里直接可用
+  - `claude` 应先在你的 shell 里直接可用
+  - `kimi` 应先在你的 shell 里直接可用
+  - `opencode` 应先在你的 shell 里直接可用
 - 模型或 API 凭证
 - 如果任务比较重，准备好 GPU 或远程服务器
 - 如果你要长期运行，优先准备 Docker 或其他隔离环境，并准备一个非 root 账号专门启动 DeepScientist
@@ -47,7 +49,7 @@
 
 如果你还在选择合适的 Coding Plan / 订阅方案，可以先看这些官方页面：
 
-- 如果你只是想先有一个简单直接的推荐起点，优先从 GPT-5.4 + `xhigh` reasoning effort 开始；如果你更偏向 Google 路线，可以使用 Gemini 3 Pro，对应模型名 `gemini-3-pro-preview`。
+- 如果你只是想先有一个简单直接的推荐起点，优先从 Codex + OpenAI 登录路径开始。想用 Gemini 时，不要直接在 DeepScientist 里填一个模型名就开始试；先按 [25 OpenCode 配置指南](./25_OPENCODE_PROVIDER_SETUP.md) 把 OpenCode + Gemini 跑通。
 - ChatGPT 定价：https://openai.com/chatgpt/pricing/
 - ChatGPT Plus 帮助页：https://help.openai.com/en/articles/6950777-what-is-chatgpt-plus%3F.eps
 - MiniMax Coding Plan：https://platform.minimaxi.com/docs/guides/pricing-codingplan
@@ -57,9 +59,14 @@
 
 如果你要通过阿里百炼使用 Qwen，请只使用百炼 **Coding Plan** endpoint。普通百炼 / DashScope 平台的 Qwen API，不在当前 Codex-backed DeepScientist 支持范围内。
 
-如果你准备使用 provider-backed 的 Codex profile，而不是默认 OpenAI 登录流，请继续看：
+如果你只是想先走最稳的一条，优先从 Codex 开始。
+
+第一次正式启动前，请先看和自己 runner 对应的那篇配置文档：
 
 - [15 Codex Provider 配置](./15_CODEX_PROVIDER_SETUP.md)
+- [24 Claude Code 配置指南](./24_CLAUDE_CODE_PROVIDER_SETUP.md)
+- [27 Kimi Code 配置指南](./27_KIMI_CODE_PROVIDER_SETUP.md)
+- [25 OpenCode 配置指南](./25_OPENCODE_PROVIDER_SETUP.md)
 
 ## 1. 先安装 Node.js，再安装 DeepScientist
 
@@ -82,7 +89,19 @@ npm install -g @researai/deepscientist
 
 这一步会把 `ds` 命令安装到你的机器上。
 
-DeepScientist 依赖一个可用的 Codex CLI。它会优先使用你机器上已经可用的 `codex`，只有在本机找不到时才回退到 npm 包内置的依赖。如果安装完成后 `codex` 仍然不可用，请显式修复：
+DeepScientist 现在内建四条 runner 路径：
+
+- `codex`
+- `claude`
+- `kimi`
+- `opencode`
+
+安装相关有一个很重要的差异：
+
+- DeepScientist 会优先使用你机器上已有的 runner CLI；只有存在兼容的 package-local binary 时，才回退到 npm 包里的 helper。
+- 对 `claude`、`kimi` 和 `opencode`，DeepScientist 不会替你完成认证；这些路径都应该先让 CLI 本身跑通，再交给 DeepScientist 复用。
+
+如果安装完成后 `codex` 仍然不可用，请显式修复：
 
 ```bash
 npm install -g @openai/codex
@@ -105,11 +124,11 @@ ds latex install-runtime
 
 这一步会安装一个轻量级 TinyTeX 运行时。
 
-## 2. 第一次运行 `ds` 前，先完成 Codex 配置
+## 2. 第一次运行 `ds` 前，先完成你要使用的 runner 配置
 
-这里有两条路径，二选一即可。
+如果你还没决定，优先从 `codex` 开始。
 
-### 2.1 默认 OpenAI 登录路径
+### 2.1 Codex：默认 OpenAI 登录路径
 
 运行：
 
@@ -131,7 +150,7 @@ codex
 ds doctor
 ```
 
-### 2.2 provider-backed 的 Codex profile 路径
+### 2.2 Codex：provider-backed 的 profile 路径
 
 如果你已经在 MiniMax、GLM、火山方舟、阿里百炼 Coding Plan 或其他 provider 上配置了一个命名的 Codex profile，请先在终端里确认这个 profile 本身可用：
 
@@ -177,6 +196,50 @@ MiniMax 额外说明：
 - 如果你还希望终端里的 `codex --profile <name>` 也直接可用，再在 `~/.codex/config.toml` 顶层补上 `model_provider = "minimax"`，以及对应的顶层 `model`，例如 `MiniMax-M2.7` 或 `MiniMax-M2.5`
 - 当 DeepScientist 检测到旧版 Codex CLI 不支持 `xhigh` 时，会自动把它降级成 `high`
 
+### 2.3 Claude Code 路径
+
+这条路径适合你本机里的 `claude` 已经能直接工作时使用。
+
+最短验证路径是：
+
+```bash
+claude --version
+claude -p "Reply with exactly HELLO." --output-format json --tools ""
+ds doctor --runner claude
+```
+
+确认通过后，再用 Claude Code 启动 DeepScientist：
+
+```bash
+ds --runner claude
+```
+
+如果你要看完整顺序、配置映射和网关说明，继续读：
+
+- [24 Claude Code 配置指南](./24_CLAUDE_CODE_PROVIDER_SETUP.md)
+
+### 2.4 OpenCode 路径
+
+这条路径适合你本机里的 `opencode` 已经能直接工作时使用。
+
+最短验证路径是：
+
+```bash
+opencode --version
+opencode run --format json --pure "Reply with exactly HELLO"
+ds doctor --runner opencode
+```
+
+确认通过后，再用 OpenCode 启动 DeepScientist：
+
+```bash
+ds --runner opencode
+```
+
+如果你要看完整顺序、配置映射和 provider 说明，继续读：
+
+- [25 OpenCode 配置指南](./25_OPENCODE_PROVIDER_SETUP.md)
+
 ## 3. 启动本地运行时
 
 运行：
@@ -187,6 +250,15 @@ ds
 
 这会启动本地 daemon 和网页工作区。
 
+如果你希望这一轮直接用非默认 runner，可以显式加上 `--runner`：
+
+```bash
+ds --runner claude
+ds --runner opencode
+```
+
+如果目标 runner 已经通过 `ds doctor`，且你准备长期使用它，后面再去 `~/DeepScientist/config/config.yaml` 或 Settings 页面把 `config.default_runner` 切过去。
+
 再次强调：
 
 - 推荐优先在 Docker 或其他隔离环境里运行
@@ -209,9 +281,10 @@ ds --here
 
 重要提醒：
 
-- 如果你是通过 `ds --here` 或显式的 `--home <path>` 启动 DeepScientist，后续像 `ds --status`、`ds --stop` 这样的管理命令，也应该使用同一个 DeepScientist home
+- 现在如果你是在某个目录里用 `ds --here` 启动，后续直接在同一目录执行 `ds --status`、`ds --stop`、`ds --restart`，launcher 通常会优先识别当前目录下的 `./DeepScientist`
+- 如果你是通过显式的 `--home <path>`，或者机器上同时存在多个 DeepScientist home，仍然建议后续管理命令继续显式使用同一个 home
 - 如果你是通过 `DEEPSCIENTIST_HOME` 或 `DS_HOME` 环境变量固定 home，只要后续命令继续使用同一个环境变量配置，也可以
-- 否则 CLI 可能会回退到默认的 `~/DeepScientist`，从而把一个实际上可访问的 daemon 误判成“不是当前 home 下的受管 daemon”
+- 当存在多个非默认 home 时，显式指定 `--home` 仍然是最稳妥的做法
 
 例如，当你使用的是非默认 home 时，应这样执行：
 
@@ -271,7 +344,7 @@ ds --port 21000
 - 复现官方的 Mandela-Effect baseline
 - 保持原论文的任务定义与评测协议
 - 研究在混合正确 / 错误社会信号下，如何实现更强的 truth-preserving collaboration
-- 使用两个本地推理端点提高吞吐量
+- 在这个参考示例里，使用两个本地推理端点提高吞吐量
 
 点击 `Start Research` / `Start Experiment`，然后选择 `Autonomous Mode`，再进入下面这条标准创建流程。
 
@@ -333,12 +406,14 @@ https://arxiv.org/abs/2602.00428
 
 把下面内容粘贴到 `Runtime constraints`：
 
+下面这段只是教程参考，不是 DeepScientist 的默认端点配置。粘贴前请把端点、API key 和模型名替换成你自己的真实运行时。
+
 ```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.
+- Use two OpenAI-compatible inference endpoints for throughput:
+  - `http://127.0.0.1:<port-a>/v1`
+  - `http://127.0.0.1:<port-b>/v1`
+- Use your actual API key `<YOUR_API_KEY>` and model `<YOUR_MODEL>` 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.