@researai/deepscientist 1.5.15 → 1.5.17

package/docs/zh/21_LOCAL_MODEL_BACKENDS_GUIDE.md

@@ -0,0 +1,281 @@
+# 21 本地模型后端指南：vLLM、Ollama 与 SGLang
+
+这篇文档说明如何通过 Codex，把 DeepScientist 接到本地 OpenAI-compatible 模型后端。
+
+最关键的一点只有一句话：
+
+- 当前 Codex CLI 要求 `wire_api = "responses"`
+- 只有 `/v1/chat/completions` 能工作还不够
+- 在期待 `ds` 或 `ds doctor` 成功之前，必须先验证 `/v1/responses`
+
+同时还有一个现实 fallback：
+
+- 如果你的后端只有 chat 接口，仍然有机会通过 **Codex CLI `0.57.0`** 跑通
+- 这条旧路径通常需要使用顶层 `model_provider` / `model`，并把 `wire_api` 设为 `chat`
+- DeepScientist 现在会在 Codex 启动探测阶段自动检查这一点；只要发现当前生效 provider 使用的是 `wire_api = "chat"`，就会要求 `codex-cli 0.57.0` 才继续
+
+## 1. DeepScientist 实际依赖的是什么
+
+DeepScientist 并不会直接和 vLLM、Ollama、SGLang 通信。
+
+它真正依赖的是：
+
+- `codex`
+- 然后由 `codex` 去调用你在 `~/.codex/config.toml` 里配置的 provider profile
+
+所以真实兼容链路是：
+
+1. 你的本地模型后端
+2. Codex profile
+3. Codex 启动探测
+4. DeepScientist runner
+
+如果第 2 步或第 3 步过不了，DeepScientist 就无法正常启动 Codex runner。
+
+## 2. 当前 Codex 必须知道的限制
+
+在当前 Codex CLI 中：
+
+- 支持 `wire_api = "responses"`
+- 不再接受 `wire_api = "chat"`
+
+这意味着：
+
+- `vLLM`：如果 OpenAI-compatible server 暴露了 `/v1/responses`，这是当前最推荐的路径
+- `Ollama`：只有在你的版本真的支持 `/v1/responses` 时才建议使用
+- `SGLang`：如果你的部署只有 `/v1/chat/completions` 能工作，那么它和最新版 Codex runner 不兼容
+
+## 2.1 支持程度总览
+
+| 后端 | `/v1/chat/completions` | `/v1/responses` | 最新版 Codex | `0.57.0` 回退路径 |
+|---|---|---|---|---|
+| vLLM | 支持 | 支持 | 支持 | 通常不需要 |
+| Ollama | 支持 | 取决于版本 | 只有 `/v1/responses` 正常时才支持 | 如果只有 chat，可以尝试 |
+| SGLang | 支持 | 经常缺失或不完整 | chat-only 时不支持 | 可以尝试回退到 `0.57.0` |
+
+## 3. 先直接测试后端
+
+在动 DeepScientist 之前，先直接验证后端。
+
+### 第一步：列模型
+
+```bash
+curl http://127.0.0.1:8004/v1/models \
+  -H "Authorization: Bearer 1234"
+```
+
+你需要从这里拿到一个真实模型名，例如：
+
+```text
+/model/gpt-oss-120b
+```
+
+### 第二步：测试 chat completions
+
+```bash
+curl http://127.0.0.1:8004/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer 1234" \
+  -d '{
+    "model": "/model/gpt-oss-120b",
+    "messages": [
+      { "role": "user", "content": "Reply with exactly HELLO." }
+    ]
+  }'
+```
+
+如果这一步成功，说明后端至少具备 OpenAI chat-compatible 能力。
+
+### 第三步：测试 Responses API
+
+```bash
+curl http://127.0.0.1:8004/v1/responses \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer 1234" \
+  -d '{
+    "model": "/model/gpt-oss-120b",
+    "input": "Reply with exactly HELLO."
+  }'
+```
+
+这一步才是决定性检查。
+
+如果 `/v1/responses` 失败，最新版 Codex CLI 就不能正常使用这个后端 profile。
+
+## 4. 我们在这台服务器上的实际观察
+
+我们已经测试了本机的 `http://127.0.0.1:8004/v1`。
+
+结果是：
+
+- `GET /v1/models` 成功
+- `POST /v1/chat/completions` 成功
+- `POST /v1/responses` 返回 `500 Internal Server Error`
+- `/v1/models` 返回里显示 `owned_by: "sglang"`
+
+所以这条 `8004` 服务当前更像一个 chat-compatible 的 SGLang 风格后端，而不是一个对最新版 Codex 友好的 Responses 后端。
+
+这意味着：
+
+- 它可以响应原始 chat 请求
+- 但它目前不能直接给最新版 Codex runner 使用
+- 因而 DeepScientist 也不能通过正常 Codex 路径使用它
+
+我们还额外做了旧版 Codex 对照测试：
+
+- 最新版 Codex + `wire_api = "responses"`：失败
+- Codex `0.57.0` + 顶层 `model_provider` / `model` + `wire_api = "chat"`：成功
+
+所以对这台机器上的 `8004` 来说：
+
+- **最新版 Codex 路径**：不通
+- **Codex `0.57.0` 回退路径**：可行
+
+## 5. 给本地 Responses 后端配置 Codex profile
+
+如果你的后端真的支持 `/v1/responses`，可以写成这样：
+
+```toml
+[model_providers.local_vllm]
+name = "local_vllm"
+base_url = "http://127.0.0.1:8004/v1"
+env_key = "LOCAL_API_KEY"
+wire_api = "responses"
+requires_openai_auth = false
+
+[profiles.local_vllm]
+model = "/model/gpt-oss-120b"
+model_provider = "local_vllm"
+```
+
+然后先直接测试 Codex：
+
+```bash
+export LOCAL_API_KEY=1234
+codex exec --profile local_vllm --json --cd /tmp --skip-git-repo-check - <<'EOF'
+Reply with exactly HELLO.
+EOF
+```
+
+如果这一步过不了，就先不要继续尝试 DeepScientist。
+
+## 5.1 只支持 chat 时，回退到 Codex `0.57.0`
+
+如果你的后端只有 `/v1/chat/completions`，可以尝试这条回退路径：
+
+1. 安装 Codex `0.57.0`
+2. 使用 `wire_api = "chat"`
+3. 把 `model_provider` 和 `model` 写到顶层
+
+示例：
+
+```toml
+model = "/model/gpt-oss-120b"
+model_provider = "localchat"
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+
+[model_providers.localchat]
+name = "localchat"
+base_url = "http://127.0.0.1:8004/v1"
+env_key = "LOCAL_API_KEY"
+wire_api = "chat"
+requires_openai_auth = false
+```
+
+然后直接测试：
+
+```bash
+export LOCAL_API_KEY=1234
+codex exec --json --cd /tmp --skip-git-repo-check - <<'EOF'
+Reply with exactly HELLO.
+EOF
+```
+
+如果这条旧版 Codex 路径能通过，DeepScientist 通常也可以沿用同样的 runner binary 和 provider 思路。
+
+## 6. Codex 成功后，再测试 DeepScientist
+
+只有当上面的 `codex exec` 能通过时，再继续：
+
+```bash
+ds doctor --codex-profile local_vllm
+ds --codex-profile local_vllm
+```
+
+这里推荐使用 `ds doctor`。
+
+`ds docker` 只是 `ds doctor` 的历史别名，不是 Docker 部署命令。
+
+如果你想持久化配置：
+
+```yaml
+codex:
+  enabled: true
+  binary: codex
+  config_dir: ~/.codex
+  profile: local_vllm
+  model: inherit
+  model_reasoning_effort: high
+  approval_policy: never
+  sandbox_mode: danger-full-access
+```
+
+## 7. 后端兼容性结论
+
+### vLLM
+
+推荐。
+
+满足下面三个条件时，是当前最稳妥的本地路径：
+
+- `/v1/models` 正常
+- `/v1/responses` 正常
+- 模型名稳定可见
+
+### Ollama
+
+条件支持。
+
+只有在下面条件满足时才建议使用：
+
+- 当前 Ollama 版本真的暴露了 `/v1/responses`
+- 目标模型可以通过该接口稳定工作
+
+如果只有 chat-completions 兼容，不足以支持最新版 Codex，但仍然可以尝试 `0.57.0` 这条旧版 Codex 路径。
+
+### SGLang
+
+要特别小心。
+
+如果你的 SGLang 部署表现是：
+
+- `/v1/chat/completions` 正常
+- `/v1/responses` 失败
+
+那么它当前就和最新版 Codex runner 不兼容。
+
+如果你必须使用这类后端，现实可行的 fallback 就是回退到 Codex `0.57.0` 并使用 `wire_api = "chat"`。
+
+## 8. 如果你现在只有 chat-completions
+
+如果你的后端只有 `/v1/chat/completions`，当前有三种现实选择：
+
+1. 切到支持 Responses 的 vLLM
+2. 升级到真正支持 `/v1/responses` 的 Ollama
+3. 回退到 Codex `0.57.0` 并使用 `wire_api = "chat"`
+4. 在后端前面加一层 Responses-compatible 代理
+
+这里的问题本质上是 Codex CLI 的当前要求，不是 DeepScientist 单独某个配置写错了。
+
+## 9. 推荐的实际顺序
+
+每次都按这个顺序来：
+
+1. 先测 `/v1/models`
+2. 再测 `/v1/responses`
+3. 再测 `codex exec --profile <name>`
+4. 再测 `ds doctor --codex-profile <name>`
+5. 最后再启动 `ds --codex-profile <name>`
+
+如果第 2 步失败，就先停在那里。不要期待最新版 Codex 路径下的 DeepScientist 可以正常工作。

package/docs/zh/README.md

@@ -4,6 +4,8 @@ DeepScientist 不仅仅是一个可长期运行的自动化科学发现系统，
 
 2 分钟安装，2 分钟配置微信，2 分钟启动。极快、方便、易用。
 
+现在本地 Web 默认不启用浏览器访问密码。如果你希望某次启动启用 16 位本地访问密码，可以使用 `ds --auth true`；启用后，`ds` 会在终端里打印这次启动的密码，第一次成功进入后浏览器会持久化这次本地登录。
+
 它也是一种工作坊式协作环境：可以长期自主推进，也允许你随时接管、协作、改代码、自己跑终端，亦或者用 Notion 式方式记录笔记、计划与协作内容。
 
 DeepScientist 灵活且易于使用，支持：
@@ -76,10 +78,16 @@ DeepScientist 灵活且易于使用，支持：
 
 - [00 快速开始](./00_QUICK_START.md)
   从安装、启动，到创建第一个项目，先看这一篇。
+- [20 工作区模式指南](./20_WORKSPACE_MODES_GUIDE.md)
+  如果你最纠结的是“应该选 Copilot 还是全自动”，先看这篇。
+- [19 本地浏览器密码说明](./19_LOCAL_BROWSER_AUTH.md)
+  如果你想弄清楚密码弹窗是什么、密码去哪里看、怎样关闭这一层本地保护，先看这篇。
 - [05 TUI 端到端指南](./05_TUI_GUIDE.md)
   如果你主要在服务器或终端里工作，这篇会带你从 `ds --tui` 一路走到 quest、connector 和跨端协作跑通。
 - [15 Codex Provider 配置](./15_CODEX_PROVIDER_SETUP.md)
-  如果你准备通过 MiniMax、GLM、火山方舟、阿里百炼或其他 Codex profile 来运行 DeepScientist，先看这一篇。
+  如果你准备通过 MiniMax、GLM、火山方舟、阿里百炼 Coding Plan 或其他 Codex profile 来运行 DeepScientist，先看这一篇。
+- [21 本地模型后端指南](./21_LOCAL_MODEL_BACKENDS_GUIDE.md)
+  如果你想通过 vLLM、Ollama、SGLang 等本地 OpenAI-compatible 后端运行 DeepScientist，先看这一篇。
 - [12 引导式工作流教程](./12_GUIDED_WORKFLOW_TOUR.md)
   按真实产品流程，逐步理解从首页到工作区应该怎么使用。
 - [02 Start Research 参考](./02_START_RESEARCH_GUIDE.md)
@@ -89,6 +97,8 @@ DeepScientist 灵活且易于使用，支持：
 
 - [02 Start Research 参考](./02_START_RESEARCH_GUIDE.md)
   解释当前前端字段、自动推导合同字段，以及实际可照抄的例子。
+- [20 工作区模式指南](./20_WORKSPACE_MODES_GUIDE.md)
+  如果你已经知道怎么填表，但还不确定项目应该从 Copilot 还是全自动启动，先看这篇。
 - [01 设置参考](./01_SETTINGS_REFERENCE.md)
   当你需要配置 runner、connector、运行时默认值或主目录路径时，看这一篇。
 - [11 协议与风险说明](./11_LICENSE_AND_RISK.md)
@@ -119,6 +129,8 @@ DeepScientist 灵活且易于使用，支持：
   说明 daemon、工作区、canvas 和 connector 视图之间的关系。
 - [07 Memory 与 MCP](./07_MEMORY_AND_MCP.md)
   说明 memory、artifact 和内置 MCP 的行为。
+- [19 External Controller 指南](./19_EXTERNAL_CONTROLLER_GUIDE.md)
+  说明如何在不改 core runtime 的前提下，基于 mailbox 和 `quest_control` 构建可选的外层治理控制器。
 
 ## 如果你遇到了问题
 
@@ -126,6 +138,8 @@ DeepScientist 灵活且易于使用，支持：
   启动诊断、排查常见运行问题，先看这篇。
 - [15 Codex Provider 配置](./15_CODEX_PROVIDER_SETUP.md)
   如果问题更像出在 Codex profile、provider endpoint、API key 或模型配置上，优先看这篇。
+- [21 本地模型后端指南](./21_LOCAL_MODEL_BACKENDS_GUIDE.md)
+  如果问题具体出在本地 OpenAI-compatible 后端以及 `/v1/responses` 支持上，优先看这篇。
 - [01 设置参考](./01_SETTINGS_REFERENCE.md)
   如果问题可能和配置、凭据或 connector 有关，再查这篇。
 
@@ -134,4 +148,12 @@ DeepScientist 灵活且易于使用，支持：
 - [90 Architecture](../en/90_ARCHITECTURE.md)
   说明系统级约束、核心契约和仓库结构。
 - [91 Development](../en/91_DEVELOPMENT.md)
-  面向维护者的开发工作流和实现说明。
+  面向维护者的开发工作流、实现说明，以及新增 MCP 工具、skills、connector 的具体清单。
+
+## 社群交流
+
+欢迎加群讨论。
+
+<p align="center">
+  <img src="../../assets/readme/wechat4.jpg" alt="DeepScientist 微信群" width="360" />
+</p>

package/install.sh

@@ -112,10 +112,6 @@ else
   INSTALL_DIR="$BASE_DIR/cli"
 fi
 
-if [ "$DIR_SET" -eq 1 ] && [ "$BIN_DIR_SET" -eq 0 ] && [ -z "$ENV_BIN_DIR" ]; then
-  BIN_DIR="$BASE_DIR/bin"
-fi
-
 print_step() {
   printf '[install] %s\n' "$1"
 }
@@ -431,6 +427,47 @@ EOF
   chmod +x "$target_path"
 }
 
+record_install_index() {
+  node - "$BASE_DIR" "$INSTALL_DIR" "$BIN_DIR" <<'NODE'
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const home = path.resolve(process.argv[2] || '');
+const installDir = path.resolve(process.argv[3] || '');
+const binDir = path.resolve(process.argv[4] || '');
+const indexPath = path.join(os.homedir(), '.deepscientist', 'install-index.json');
+const wrapperPaths = ['ds', 'ds-cli', 'research', 'resear'].map((name) => path.join(binDir, name));
+const entry = {
+  home,
+  install_mode: 'install-local',
+  install_dir: installDir,
+  package_root: installDir,
+  launcher_path: path.join(installDir, 'bin', 'ds.js'),
+  wrapper_paths: wrapperPaths,
+  updated_at: new Date().toISOString(),
+  created_at: new Date().toISOString(),
+};
+let installs = [];
+try {
+  const payload = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+  installs = Array.isArray(payload?.installs) ? payload.installs : [];
+} catch {}
+const sameEntry = (item) =>
+  String(item?.home || '') === home
+  && String(item?.install_dir || '') === installDir
+  && String(item?.install_mode || '') === 'install-local';
+const existing = installs.find((item) => sameEntry(item));
+if (existing && existing.created_at) {
+  entry.created_at = existing.created_at;
+}
+installs = installs.filter((item) => !sameEntry(item));
+installs.push(entry);
+fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+fs.writeFileSync(indexPath, `${JSON.stringify({ installs }, null, 2)}\n`, 'utf8');
+NODE
+}
+
 require_command node
 require_command npm
 
@@ -466,6 +503,7 @@ write_global_wrapper "$BIN_DIR/ds" "ds"
 write_global_wrapper "$BIN_DIR/ds-cli" "ds-cli"
 write_global_wrapper "$BIN_DIR/research" "research"
 write_global_wrapper "$BIN_DIR/resear" "resear"
+record_install_index
 
 print_step "Install complete"
 printf 'Install dir: %s\n' "$INSTALL_DIR"
@@ -475,6 +513,10 @@ printf 'Start web workspace: %s\n' "$BIN_DIR/ds --web"
 printf 'Default start: %s\n' "$BIN_DIR/ds"
 printf 'When `ds` starts, it prints the local Web URL and opens it automatically when supported.\n'
 printf 'If `uv` is missing, the first `ds` start will bootstrap a local copy automatically under the DeepScientist home.\n'
+if [ "$DIR_SET" -eq 1 ] && [ "$BIN_DIR_SET" -eq 0 ] && [ -z "$ENV_BIN_DIR" ]; then
+  printf 'Custom install dir detected; launcher wrappers were still refreshed in the default global bin dir: %s\n' "$BIN_DIR"
+  printf 'If you prefer install-local wrappers instead, rerun with: --bin-dir %s/bin\n' "$BASE_DIR"
+fi
 if [ "$WITH_TINYTEX" -eq 1 ]; then
   print_step "Installing TinyTeX pdflatex runtime"
   "$INSTALL_DIR/bin/ds" latex install-runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@researai/deepscientist",
-  "version": "1.5.15",
+  "version": "1.5.17",
   "description": "DeepScientist is not just a fully open-source autonomous scientific discovery system. It is also a research map that keeps growing from every round.",
   "license": "Apache-2.0",
   "files": [
@@ -47,6 +47,7 @@
     "ds": "node ./bin/ds.js",
     "start": "node ./bin/ds.js daemon",
     "install:local": "bash ./install.sh",
+    "preuninstall": "node ./bin/ds.js uninstall --yes --origin npm",
     "ui:install": "npm --prefix src/ui install",
     "ui:dev": "npm --prefix src/ui run dev",
     "ui:build": "npm --prefix src/ui run build",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepscientist"
-version = "1.5.15"
+version = "1.5.17"
 description = "DeepScientist Core skeleton"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/deepscientist/__init__.py

@@ -5,4 +5,4 @@ __all__ = ["__version__"]
 try:
     __version__ = _package_version("deepscientist")
 except PackageNotFoundError:  # pragma: no cover - source checkout fallback
-    __version__ = "1.5.15"
+    __version__ = "1.5.17"

package/src/deepscientist/acp/envelope.py

@@ -182,6 +182,8 @@ def build_session_update(
             "content": event.get("text"),
             "run_id": event.get("run_id"),
             "skill_id": event.get("skill_id"),
+            "stream_id": event.get("stream_id"),
+            "message_id": event.get("message_id"),
             "stream": True,
         }
     elif event_type == "runner.agent_message":
@@ -192,6 +194,8 @@ def build_session_update(
             "content": event.get("text"),
             "run_id": event.get("run_id"),
             "skill_id": event.get("skill_id"),
+            "stream_id": event.get("stream_id"),
+            "message_id": event.get("message_id"),
             "stream": False,
         }
     elif event_type == "runner.reasoning":
@@ -202,6 +206,8 @@ def build_session_update(
             "content": event.get("text"),
             "run_id": event.get("run_id"),
             "skill_id": event.get("skill_id"),
+            "stream_id": event.get("stream_id"),
+            "message_id": event.get("message_id"),
             "stream": False,
         }
     elif event_type == "runner.turn_start":