@researai/deepscientist 1.5.16 → 1.6.0

package/docs/zh/26_CITATION_AND_ATTRIBUTION.md

@@ -0,0 +1,102 @@
+# 26 引用与致谢说明
+
+这篇文档只说明一件事：我们希望大家如何引用和致谢 DeepScientist。
+
+这里的语气是刻意温和的：
+
+- 这是对学术归因的强烈请求
+- 不是对软件许可证的额外限制
+- 也不是法律意见
+
+## 简短版本
+
+如果 DeepScientist 对论文、报告、benchmark write-up 或公开研究产物产生了实质性帮助，我们强烈建议你：
+
+1. 引用 DeepScientist 论文
+2. 诚实披露有意义的 AI assistance
+3. 不要把 AI 生成或 AI 模拟出的结果伪装成纯人工、纯真实实验结果
+
+如果你只是把 DeepScientist 当成一个很轻量的启动器、文件浏览器或终端外壳在用，通常没有必要强行引用。
+
+## 我们强烈建议引用的场景
+
+当 DeepScientist 对以下环节产生了实质性贡献时，建议引用：
+
+- 研究规划或任务拆解
+- baseline 恢复与实验编排
+- 文献筛选、论文分析或结构化阅读
+- 结果分析、整合或写作支持
+- 图表、草稿或 rebuttal 准备
+
+一个很实用的判断方式是：
+
+- 如果 DeepScientist 对研究产物的内容、速度或完成方式产生了明显影响，就建议引用
+
+## 通常不需要引用的场景
+
+如果 DeepScientist 只是被用作：
+
+- 本地启动器
+- 终端便利层
+- 通用代码 / 文件浏览器
+- 没有实质研究贡献的一次性操作工具
+
+通常不需要引用。
+
+## 推荐引用方式
+
+论文链接：
+
+- `https://openreview.net/forum?id=cZFgsLq8Gs`
+
+BibTeX：
+
+```bibtex
+@inproceedings{
+weng2026deepscientist,
+title={DeepScientist: Advancing Frontier-Pushing Scientific Findings Progressively},
+author={Yixuan Weng and Minjun Zhu and Qiujie Xie and QiYao Sun and Zhen Lin and Sifan Liu and Yue Zhang},
+booktitle={The Fourteenth International Conference on Learning Representations},
+year={2026},
+url={https://openreview.net/forum?id=cZFgsLq8Gs}
+}
+```
+
+## 建议致谢模板
+
+如果 DeepScientist 对项目产生了实质性帮助，通常一段简短致谢就够了，例如：
+
+```text
+We used DeepScientist to assist parts of the research workflow, including selected planning, implementation, experiment orchestration, analysis, and/or writing support. Final judgments, claims, and reported real experimental results remain the responsibility of the human authors.
+```
+
+你可以根据投稿 venue 的规范自行缩短或改写。
+
+## 关于 AI assistance 披露
+
+如果 DeepScientist 对下列内容有明显贡献，我们强烈建议披露：
+
+- 写作
+- 编码
+- 实验搭建
+- 结果解释
+- 图表生成
+- 文献整理
+
+这里不要求夸大 AI 的作用，只需要让读者知道它在哪些关键环节确实参与了。
+
+## 这不是许可证附加条件
+
+这份引用说明不会改变仓库当前的软件许可证。
+
+尤其是：
+
+- 它不是新的 license condition
+- 忘记引用不会让你的软件使用权自动失效
+- 它是一份社区归因与学术礼仪层面的请求，不是软件使用门槛
+
+## 相关文件
+
+- [../../CITATION.cff](../../CITATION.cff)
+- [../../TRADEMARK.md](../../TRADEMARK.md)
+- [11 协议与风险说明](./11_LICENSE_AND_RISK.md)

package/docs/zh/27_KIMI_CODE_PROVIDER_SETUP.md

@@ -0,0 +1,51 @@
+# Kimi Code Provider 配置指南
+
+当你希望 DeepScientist 通过官方 `kimi` CLI 运行，并且把它作为一个独立 builtin runner 使用时，使用这份文档；不要再把 Kimi 混在 Claude 路径里。
+
+## DeepScientist 的前提假设
+
+- 已安装官方 `kimi` CLI，并且在启动 DeepScientist 的同一个 shell 里执行 `kimi --version` 能成功。
+- 已经至少执行过一次 `kimi login`，或者手动启动过 `kimi` 完成首次登录。
+- 全局 Kimi home 默认位于 `~/.kimi/`。
+
+## 推荐的 `runners.yaml` 配置
+
+```yaml
+kimi:
+  enabled: true
+  binary: kimi
+  config_dir: ~/.kimi
+  model: inherit
+  agent: ""
+  thinking: false
+  yolo: true
+```
+
+## DeepScientist 的运行方式
+
+- DeepScientist 会把你配置的 `~/.kimi` 复制到 quest 隔离运行目录 `.ds/kimi-home/.kimi`。
+- quest 内的技能会同步到 `.kimi/skills`。
+- 内置 MCP 会通过生成的 `.kimi/mcp.json` 注入进去。
+- prompt 通过 stdin 发送，所以长 prompt 不会再撞到 argv 长度限制。
+
+## 切换前的验证步骤
+
+1. 手动运行 `kimi --print --input-format text --output-format stream-json --yolo`。
+2. 输入一个简单提示，例如 `Reply with exactly HELLO.`。
+3. 运行 `ds doctor`，确认 `Kimi Code CLI` 的 startup probe 通过。
+4. 只有在这些都正常后，再把 `config.default_runner` 切到 `kimi`。
+- `mcp_tool_timeout_ms`：如果预计会有长时间 `bash_exec` 等 MCP 调用，保持较大的超时值
+
+## 推荐的 `runners.yaml` 结构
+
+```yaml
+kimi:
+  enabled: true
+  binary: kimi
+  config_dir: ~/.kimi
+  model: inherit
+  agent: ""
+  thinking: false
+  yolo: true
+  mcp_tool_timeout_ms: 172800000
+```

package/docs/zh/{19_LOCAL_BROWSER_AUTH.md → 31_LOCAL_BROWSER_AUTH.md}

@@ -1,4 +1,4 @@
-# 本地浏览器密码说明
+# 31 本地浏览器密码说明
 
 DeepScientist 现在可以为本地 Web 工作区按需开启一层 16 位随机密码保护。
 

package/docs/zh/32_WINDOWS_WSL2_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,264 @@
+# 32 Windows + WSL2 部署指南
+
+本指南适用于 Windows 10/11 用户，通过 WSL2 在本地部署 DeepScientist，并使用阿里百炼 Coding Plan 作为模型后端。步骤覆盖 WSL2 安装、迁移到 D 盘、npm 免 `sudo` 配置、DeepScientist 与固定版本 Codex CLI 安装，以及常见问题排查。
+
+## 适用环境
+
+- Windows 10/11，版本 `2004+`，内部版本 `19041+`
+- 阿里百炼 Coding Plan API Key，形如 `sk-sp-...`
+- 稳定网络；如遇 GitHub 或 astral 下载失败，可准备代理或镜像
+
+本指南已在 Windows 10 22H2 + WSL2 Ubuntu 22.04 LTS 上手动验证。
+
+## 1. 安装 WSL2 并迁移到 D 盘
+
+### 1.1 启用 WSL 相关功能
+
+以管理员身份打开 PowerShell，执行：
+
+```powershell
+dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
+dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
+```
+
+### 1.2 重启系统
+
+执行上述命令后，先重启 Windows。
+
+### 1.3 安装 WSL2 内核更新包
+
+从微软官方链接下载安装：
+
+- https://aka.ms/wsl2kernel
+
+通常文件名类似 `wsl.2.6.3.0.x64.msi`。下载安装后双击运行。
+
+### 1.4 设置 WSL2 为默认版本
+
+```powershell
+wsl --set-default-version 2
+```
+
+### 1.5 安装 Ubuntu 并迁移到 D 盘
+
+如果当前 WSL 版本不支持直接使用 `--location` 指定安装路径，可以采用“导出再导入”的通用方式：
+
+```powershell
+# 1. 先临时安装到默认位置
+wsl --install -d Ubuntu
+
+# 2. 第一次启动 Ubuntu，完成用户名和密码初始化
+
+# 3. 导出并迁移到 D 盘
+wsl --export Ubuntu D:\WSL\Ubuntu.tar
+wsl --unregister Ubuntu
+mkdir D:\WSL\Ubuntu
+wsl --import Ubuntu D:\WSL\Ubuntu D:\WSL\Ubuntu.tar --version 2
+
+# 4. 设置默认用户（把 <your_username> 换成初始化时的用户名）
+ubuntu config --default-user <your_username>
+
+# 5. 清理导出文件
+del D:\WSL\Ubuntu.tar
+```
+
+验证：
+
+```powershell
+wsl -l -v
+```
+
+确认 Ubuntu 的版本为 `2`，并且 `D:\WSL\Ubuntu\ext4.vhdx` 已生成。
+
+## 2. 进入 WSL，准备基础环境
+
+进入 Ubuntu：
+
+```powershell
+wsl -d Ubuntu
+```
+
+更新系统并安装基础工具：
+
+```bash
+sudo apt update && sudo apt upgrade -y
+sudo apt install -y curl git
+```
+
+## 3. 把 npm 全局路径配置到用户目录
+
+这样可以避免全局安装时使用 `sudo`：
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+```
+
+## 4. 安装 DeepScientist 和固定版本 Codex CLI
+
+```bash
+npm install -g @researai/deepscientist
+npm install -g @openai/codex@0.57.0
+```
+
+验证：
+
+```bash
+codex --version
+ds --version
+```
+
+其中 `codex --version` 应显示 `0.57.0`。
+
+## 5. 配置阿里百炼 Coding Plan
+
+### 5.1 设置 API Key
+
+编辑 `~/.bashrc`：
+
+```bash
+nano ~/.bashrc
+```
+
+添加：
+
+```bash
+export OPENAI_API_KEY="sk-sp-你的真实API密钥"
+```
+
+然后执行：
+
+```bash
+source ~/.bashrc
+```
+
+### 5.2 创建 Codex 配置文件
+
+```bash
+mkdir -p ~/.codex
+cat > ~/.codex/config.toml << 'EOF'
+model = "qwen3.5-plus"
+model_provider = "Model_Studio_Coding_Plan"
+
+[model_providers.Model_Studio_Coding_Plan]
+name = "Model_Studio_Coding_Plan"
+base_url = "https://coding.dashscope.aliyuncs.com/v1"
+env_key = "OPENAI_API_KEY"
+wire_api = "chat"
+
+[profiles.bailian]
+model = "qwen3.5-plus"
+model_provider = "Model_Studio_Coding_Plan"
+EOF
+```
+
+### 5.3 测试 Codex 配置
+
+```bash
+codex --profile bailian
+```
+
+在提示符后输入一条简单消息，例如 `你好`，确认可以收到回复，再用 `exit` 退出。
+
+## 6. 安装 uv
+
+DeepScientist 的 Python 运行时依赖 `uv`：
+
+```bash
+curl -LsSf https://github.com/astral-sh/uv/releases/latest/download/uv-installer.sh | sh
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+uv --version
+```
+
+## 7. 运行诊断并启动 DeepScientist
+
+### 7.1 运行诊断
+
+```bash
+ds doctor --codex-profile bailian
+```
+
+大部分检查项应为 `[ok]`。`[warn]` 里常见的是 Git 用户名或 LaTeX 运行时未配置，这些通常不阻止基本启动。
+
+### 7.2 启动服务
+
+```bash
+mkdir -p ~/my_research && cd ~/my_research
+ds --here --codex-profile bailian
+```
+
+成功后终端会显示本地 Web 地址，例如：
+
+```text
+Local web UI: http://127.0.0.1:20999
+```
+
+### 7.3 在 Windows 浏览器里访问
+
+直接在 Windows 浏览器中打开：
+
+- http://127.0.0.1:20999
+
+然后点击 `Start Research` 开始使用。
+
+## 8. 停止服务
+
+在 WSL 终端中按 `Ctrl+C`，或执行：
+
+```bash
+ds --stop
+```
+
+## 9. 常见问题
+
+| 现象 | 处理方式 |
+|---|---|
+| `wsl --import` 报 `HCS_E_HYPERV_NOT_INSTALLED` | 在 BIOS 中开启虚拟化，并执行 `bcdedit /set hypervisorlaunchtype auto` 后重启 |
+| `npm install -g` 权限错误 | 确认已把 npm 全局路径配置到用户目录 |
+| `ds doctor` 提示 Codex 版本不兼容 | 确认安装的是 `@openai/codex@0.57.0` |
+| Codex 可用但 DeepScientist 启动失败 | 确认启动时带了 `--codex-profile bailian` |
+| `wire_api = "chat"` 弃用警告 | 目前可忽略；未来待上游兼容后可切到 `responses` |
+| `uv` 下载失败 | 配置代理，或尝试 `pip install uv --user` 作为替代 |
+
+## 10. 可选优化
+
+- 配置 Git 用户信息：
+
+  ```bash
+  git config --global user.name "Your Name"
+  git config --global user.email "you@example.com"
+  ```
+
+- 安装 LaTeX 运行时：
+
+  ```bash
+  sudo apt install -y texlive-latex-base texlive-latex-recommended texlive-fonts-recommended texlive-bibtex-extra
+  ```
+
+  或使用 DeepScientist 内置运行时：
+
+  ```bash
+  ds latex install-runtime
+  ```
+
+- 若你想让某个项目默认使用 `bailian` profile，可以在项目目录下调整对应 runner 配置。
+
+## 验证说明
+
+本指南基于以下环境手动验证：
+
+- Windows 10 22H2
+- WSL2 Ubuntu 22.04.5 LTS
+- Node.js 20.x
+- npm 10.8.2
+- Codex CLI 0.57.0
+- DeepScientist 1.6.0
+- 阿里百炼 Coding Plan（`qwen3.5-plus`）
+
+如果后续项目版本、Codex 版本或阿里百炼 API 兼容方式发生变化，请以最新官方文档为准，并优先复查：
+
+- [15_CODEX_PROVIDER_SETUP.md](./15_CODEX_PROVIDER_SETUP.md)
+- [09_DOCTOR.md](./09_DOCTOR.md)

package/docs/zh/33_WORKSPACE_EXPLORER_QA.md

@@ -0,0 +1,127 @@
+# Workspace Explorer Q&A
+
+这篇解释一个常见困惑：终端里能看到某些文件或文件夹，但 Web 左侧 Explorer 或 Search 看不到。
+
+## 1. Explorer 是否等于本地 quest 根目录？
+
+不完全等于。
+
+Explorer 的 `FILES` 视图展示的是后端当前认为的 active workspace root，而不是永远展示 `<home>/quests/<id>` 根目录。active workspace root 的优先级是：
+
+1. `.ds/research_state.json` 里的 `current_workspace_root`
+2. `.ds/research_state.json` 里的 `research_head_worktree_root`
+3. quest 根目录
+
+所以同一个 quest 在不同阶段可能会看到不同目录。例如 agent 正在 analysis 或 paper 分支工作时，active workspace root 可能是：
+
+```text
+<quest_root>/.ds/worktrees/<branch-worktree-name>
+```
+
+这时你在 `<quest_root>` 根目录手动新建的文件夹，不一定会出现在 Explorer 里。
+
+## 2. 哪些文件夹会被 Explorer 跳过？
+
+桌面端 `FILES` 视图会递归展示 active workspace root 下的真实文件和文件夹，但会跳过：
+
+- `.git`
+- 当 active root 是 quest 根目录时，`.ds/worktrees`
+- `__pycache__`
+- `.pytest_cache`
+
+注意：如果 active workspace root 本身就是某个 `.ds/worktrees/<name>`，Explorer 会把这个 worktree 当作根目录展示；它不会因为绝对路径包含 `.ds/worktrees` 就隐藏整个 active worktree。
+
+移动端会额外简化文件树，常见隐藏或截断项包括 `.ds`、`artifacts`、`tmp`、`userfiles` 和较深层目录。
+
+## 3. `FILES`、`SCOPE`、`SNAPSHOT` 有什么区别？
+
+- `FILES`：当前 active workspace root 的实时文件树。
+- `SCOPE`：当前图节点、阶段、diff 或被 reveal 的文件范围，不代表完整文件树。
+- `SNAPSHOT`：某个 git revision / commit 的只读快照，也不代表当前磁盘最新状态。
+
+如果你想确认终端里新建的文件是否进入 Web 文件树，先切到 `FILES`，再点击刷新。
+
+## 4. 手动在终端新建文件夹，Explorer 会自动出现吗？
+
+不会自动出现。DeepScientist 当前没有监听本地文件系统变化。
+
+手动创建后需要：
+
+1. 确认你写入的是当前 active workspace root。
+2. 在 Explorer 里切到 `FILES`。
+3. 点击刷新按钮，或刷新页面。
+
+空文件夹可以在 Explorer 里显示，但 Search 通常搜不到空文件夹，因为 Search 主要扫描文件路径和可读文本内容。
+
+## 5. Search 为什么有时搜不到？
+
+Search 搜的是 active workspace root 下的文件，不是所有 worktree 的全集。
+
+Search 还会跳过过大的文件、二进制文件和被 Explorer 过滤掉的路径。它适合查文件名、路径和文本内容，不适合证明某个空目录是否存在。
+
+普通查询应直接输入文本，例如：
+
+```text
+run_probe
+experiments/analysis
+```
+
+不要把普通查询写成 shell glob。旧版前端曾经把普通查询包装成 `*term*`，这会让后端按字面量搜索 `*term*`。新版已兼容这种旧格式，但推荐直接输入关键词。
+
+## 6. 如何确认当前 Explorer 看的到底是哪一个目录？
+
+可以直接查 API：
+
+```bash
+curl -s "http://127.0.0.1:<port>/api/quests/<quest_id>/explorer" | jq -r '.quest_root'
+```
+
+也可以看 research state：
+
+```bash
+cat <quest_root>/.ds/research_state.json
+```
+
+重点看：
+
+- `current_workspace_root`
+- `research_head_worktree_root`
+- `paper_parent_worktree_root`
+- `analysis_parent_worktree_root`
+
+如果你终端里的 `pwd` 和 Explorer API 返回的 `quest_root` 不一致，Web 里看不到该文件通常是正常行为。
+
+## 7. 我应该怎么把文件交给 agent 或加入研究流程？
+
+推荐两种方式。
+
+第一，让 agent 在当前 active worktree 写文件：
+
+```text
+请在当前 active worktree 下创建 experiments/analysis/...，
+把脚本、结果和报告都写入该目录，并记录 artifact / 更新 PLAN 和 CHECKLIST。
+```
+
+这样文件更容易被 Explorer、artifact、Canvas 和后续 agent 轮次识别。
+
+第二，通过 Web 的新建文件、上传或编辑器保存。这样会通过后端 API 写入当前 Explorer 对应的 active workspace root。
+
+## 8. 写入文件是否等于进入 Git？
+
+不等于。
+
+只要文件在 git worktree 里创建，它会出现在该 worktree 的 `git status` 中，通常是 untracked。真正进入 Git 历史需要：
+
+- `git add` / `git commit`
+- 或 DeepScientist 的 artifact / checkpoint 流程完成对应记录
+
+同时要注意，`.ds/worktrees/<name>` 下的 git 状态属于那个 worktree，不一定体现在 quest 根目录的 `git status` 里。
+
+## 9. 推荐排查顺序
+
+1. 在 Web Explorer 切到 `FILES`。
+2. 点击刷新。
+3. 用 Explorer API 确认 `.quest_root`。
+4. 在终端 `pwd`，确认手动写入目录是否等于 API 返回目录。
+5. 如果写在另一个 worktree，切换流程或让 agent 把文件合并/复制到当前 active worktree。
+6. 如果要长期保留，要求 agent 记录 artifact 或做 checkpoint。

package/docs/zh/99_ACKNOWLEDGEMENTS.md

@@ -6,29 +6,33 @@ DeepScientist 的构思、架构设计与实现过程中，受到了许多优秀
 
 特别感谢以下项目为 DeepScientist 提供的重要启发、参考与研究背景：
 
-- 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
-
-这些项目在自动化科研、开放式探索、进化式搜索、实验组织、智能研究代理、协作式 LaTeX 编辑工作流、浏览器端代码编辑体验，以及富文本 notebook 式写作交互等方向上的探索，为 DeepScientist 的设计提供了重要参照。
+- [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)
+
+这些项目在自动化科研、开放式探索、进化式搜索、实验组织、智能研究代理、协作式 LaTeX 编辑工作流、浏览器端代码编辑体验、富文本 notebook 式写作交互、论文图表生成与润色，以及 Nature 风格科研写作、数据、图表和展示技能等方向上的探索，为 DeepScientist 的设计提供了重要参照。
 
 ## 个人致谢
 
 同时，特别感谢以下老师和同学的支持、讨论、启发与贡献：
 
-- 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)
 
 谨向以上项目与个人致以感谢。