@researai/deepscientist 1.5.0 → 1.5.1

package/docs/en/91_DEVELOPMENT.md

@@ -0,0 +1,195 @@
+# 91 Development Guide: Maintainer Workflow and Repository Guide
+
+This guide is for maintainers and contributors working inside the repository.
+
+For architecture, read [90_ARCHITECTURE.md](90_ARCHITECTURE.md) first.
+
+## Local Prerequisites
+
+Recommended baseline:
+
+- Node.js `>=18.18`
+- npm `>=9`
+- Python `>=3.11`
+- Git on `PATH`
+
+Optional local toolchains:
+
+- Codex CLI for the runnable agent path
+- TinyTeX or another LaTeX distribution if you want local PDF compilation
+
+## Common Local Flows
+
+### Install into a separate local runtime tree
+
+```bash
+bash install.sh
+```
+
+### Install plus a managed TinyTeX runtime
+
+```bash
+bash install.sh --with-tinytex
+```
+
+### Start the product
+
+```bash
+ds
+```
+
+### Check local health
+
+```bash
+ds doctor
+```
+
+### Check or install the managed LaTeX runtime
+
+```bash
+ds latex status
+ds latex install-runtime
+```
+
+## Build Commands
+
+Build the web UI:
+
+```bash
+npm --prefix src/ui install
+npm --prefix src/ui run build
+```
+
+Build the TUI:
+
+```bash
+npm --prefix src/tui install
+npm --prefix src/tui run build
+```
+
+## Test Commands
+
+Quick Python test run:
+
+```bash
+pytest
+```
+
+Useful focused checks:
+
+```bash
+python3 -m compileall src/deepscientist
+node -c bin/ds.js
+npm pack --dry-run --ignore-scripts
+```
+
+## Release-Oriented Checks
+
+Before publishing or cutting a release, verify:
+
+1. Python tests pass.
+2. Web and TUI bundles build cleanly.
+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.
+
+## Managed Runtime Tools
+
+Managed local tools live under `src/deepscientist/runtime_tools/`.
+
+The goal is to keep optional local helper runtimes consistent and easy to extend.
+
+### Current structure
+
+- `models.py`
+  - provider protocol and shared types
+- `registry.py`
+  - registration and lookup
+- `builtins.py`
+  - built-in registrations
+- `service.py`
+  - high-level access for runtime code
+- `tinytex.py`
+  - TinyTeX adapter
+
+### Registration flow
+
+Every managed tool should follow the same pattern:
+
+1. Add a provider module under `src/deepscientist/runtime_tools/`.
+2. Expose a provider object with:
+   - `tool_name`
+   - `status()`
+   - `install()`
+   - `resolve_binary(binary)`
+3. Register it in `runtime_tools/builtins.py`.
+4. Access it through `RuntimeToolService`, not by scattering direct imports across the repo.
+5. Document it if it changes user-visible install or troubleshooting behavior.
+
+### Minimal provider example
+
+```python
+from pathlib import Path
+
+
+class ExampleRuntimeTool:
+    tool_name = "example"
+
+    def __init__(self, home: Path) -> None:
+        self.home = home
+
+    def status(self) -> dict:
+        return {"ok": True, "summary": "Example tool is healthy."}
+
+    def install(self) -> dict:
+        return {"ok": True, "changed": False, "summary": "Nothing to install."}
+
+    def resolve_binary(self, binary: str) -> dict:
+        return {"binary": binary, "path": None, "source": None, "root": None, "bin_dir": None}
+```
+
+Register it in `runtime_tools/builtins.py`:
+
+```python
+from .registry import register_runtime_tool
+from .example import ExampleRuntimeTool
+
+
+def register_builtin_runtime_tools(*, home=None) -> None:
+    register_runtime_tool("example", lambda **kwargs: ExampleRuntimeTool(kwargs["home"]))
+```
+
+Use it from runtime code:
+
+```python
+from deepscientist.runtime_tools import RuntimeToolService
+
+
+service = RuntimeToolService(home)
+status = service.status("example")
+match = service.resolve_binary("example-binary", preferred_tools=("example",))
+```
+
+### Rules for adding a new managed tool
+
+- keep the tool optional unless it is absolutely required for the core product
+- do not add a public MCP namespace for it
+- do not wire it directly into unrelated modules when `RuntimeToolService` is enough
+- prefer install locations under `~/DeepScientist/runtime/tools/`
+- keep clear source reporting such as `tinytex` versus `path`
+- add tests for registration, status, and binary resolution
+
+## Documentation Rules
+
+When behavior changes:
+
+- update user docs in `docs/en/` and `docs/zh/` if the user-facing workflow changed
+- update `90_ARCHITECTURE.md` if subsystem structure or ownership changed
+- update this file if development or registration workflow changed
+
+## Repository Hygiene
+
+- do not commit `node_modules/`, build output, caches, or local secrets
+- do not commit workstation-specific absolute paths
+- keep changes coherent and narrowly scoped
+- prefer current runtime behavior and tests over stale comments or deleted historical docs

package/docs/en/99_ACKNOWLEDGEMENTS.md

@@ -0,0 +1,29 @@
+# 99 Acknowledgements: Credits and Thanks
+
+DeepScientist was shaped by many prior systems, open-source efforts, and research discussions. We would like to express sincere thanks to the projects and individuals who inspired, informed, or supported this work.
+
+## Project acknowledgements
+
+We especially thank the following projects for their ideas, research direction, and systems inspiration:
+
+- The AI Scientist
+- The AI Scientist v2
+- AlphaEvolve
+- OpenEvolve
+- EvoScientist
+
+These projects have been important references for thinking about automated research, open-ended exploration, evolutionary search, experiment organization, and long-horizon research agents.
+
+## 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
+
+We are grateful to all of the above projects and individuals.

package/docs/zh/00_QUICK_START.md

@@ -0,0 +1,134 @@
+# 00 快速开始：启动 DeepScientist 并运行第一个 Quest
+
+这份文档面向第一次使用 DeepScientist 的用户，目标是让你从安装直接走到“成功启动并跑起来一个 quest”。
+
+你只需要完成四步：
+
+1. 安装 DeepScientist
+2. 启动本地运行时
+3. 在首页创建一个新 quest
+4. 从 quest 列表重新打开已有任务
+
+本文中的截图直接使用当前在线页面 `deepscientist.cc:20999` 作为示例。你本地运行后的页面 `127.0.0.1:20999` 通常会与它保持一致或非常接近。
+
+## 1. 安装
+
+先全局安装 Codex 和 DeepScientist：
+
+```bash
+npm install -g @openai/codex @researai/deepscientist
+```
+
+如果你后续还要在本地编译论文 PDF，也可以顺手安装轻量级 LaTeX 运行时：
+
+```bash
+ds latex install-runtime
+```
+
+## 2. 启动 DeepScientist
+
+启动本地 daemon 与 Web 工作区：
+
+```bash
+ds
+```
+
+默认情况下，网页会运行在：
+
+```text
+http://127.0.0.1:20999
+```
+
+如果浏览器没有自动打开，就手动访问这个地址。
+
+## 3. 认识首页
+
+启动完成后，先打开 `/` 首页。
+
+![DeepScientist 首页](../images/quickstart/00-home.png)
+
+首页故意做得很简单，核心只有两个按钮：
+
+- `Start Research`：创建一个新的 quest，并立刻启动新的研究任务
+- `List Quest`：打开已有 quest 列表，重新进入已经存在的任务
+
+如果你是第一次使用，建议先从 `Start Research` 开始。
+
+## 4. 使用 Start Research 创建新 Quest
+
+点击 `Start Research`，会弹出启动表单。
+
+![Start Research 弹窗](../images/quickstart/01-start-research.png)
+
+这个弹窗不只是“新建任务”，它还会为 agent 写入本次研究的启动合同。
+
+最重要的字段是：
+
+- `Quest ID`：通常会自动按顺序生成，例如 `00`、`01`、`02`
+- `Primary request` / 研究目标：你真正希望 agent 完成的科研任务
+- `Reuse Baseline`：可选；如果你要复用已有 baseline，就在这里选择
+- `Research intensity`：本次研究的投入强度
+- `Decision mode`：`Autonomous` 表示除非真的需要审批，否则 agent 默认持续自主推进
+- `Research paper`：是否要求本次任务同时产出论文式结果
+- `Language`：本次运行希望使用的用户侧语言
+
+第一次测试时，建议你这样填写：
+
+- 写一个清晰、单一的研究问题
+- 如果还没有 baseline，就先留空
+- 强度选择 `Balanced` 或 `Sprint`
+- 决策模式保持 `Autonomous`
+
+最后点击弹窗底部的 `Start Research` 即可正式启动。
+
+## 5. 使用 List Quest 打开已有任务
+
+点击首页上的 `List Quest`，会打开 quest 列表。
+
+![List Quest 弹窗](../images/quickstart/02-list-quest.png)
+
+这个列表适合以下场景：
+
+- 重新进入一个已经在运行中的 quest
+- 打开一个以前已经完成或已经创建过的 quest
+- 按 quest 标题或 quest id 搜索目标任务
+
+列表中的每一行都对应一个 quest 仓库。点击对应卡片即可进入该 quest 的工作区。
+
+## 6. 打开 Quest 之后会发生什么
+
+创建或打开 quest 后，DeepScientist 会进入这个 quest 的工作区页面。
+
+通常你会在里面做这些事情：
+
+1. 在 Copilot / Studio 中观察 agent 的实时进展
+2. 查看文件、笔记和生成出来的 artifact
+3. 在 Canvas 中理解当前 quest 的图结构与阶段进展
+4. 只有在你明确想中断时，才主动停止任务
+
+## 7. 常用运行命令
+
+查看当前状态：
+
+```bash
+ds --status
+```
+
+停止当前本地 daemon：
+
+```bash
+ds --stop
+```
+
+如果启动异常或环境有问题，运行诊断：
+
+```bash
+ds doctor
+```
+
+## 8. 下一步该看什么
+
+- [01 设置参考：如何配置 DeepScientist](./01_SETTINGS_REFERENCE.md)
+- [02 Start Research 参考：如何填写科研启动合同](./02_START_RESEARCH_GUIDE.md)
+- [03 QQ 连接器指南：如何用 QQ 与 DeepScientist 沟通](./03_QQ_CONNECTOR_GUIDE.md)
+- [05 TUI 使用指南：如何使用终端界面](./05_TUI_GUIDE.md)