@researai/deepscientist 1.5.1 → 1.5.2

package/docs/en/00_QUICK_START.md

@@ -1,22 +1,22 @@
-# 00 Quick Start: Launch DeepScientist and Run Your First Quest
+# 00 Quick Start: Launch DeepScientist and Run Your First Project
 
-This is the fastest way to go from installation to a running quest.
+This is the fastest way to go from installation to a running project.
 
 You will do four things:
 
 1. install DeepScientist
 2. start the local runtime
-3. create a new quest from the home page
-4. reopen old quests from the quest list
+3. create a new project from the home page
+4. reopen old projects from the project list
 
 The screenshots in this guide use the current live web UI at `deepscientist.cc:20999` as an example. Your local UI at `127.0.0.1:20999` should look the same or very close.
 
 ## 1. Install
 
-Install Codex and DeepScientist globally:
+Install DeepScientist globally:
 
 ```bash
-npm install -g @openai/codex @researai/deepscientist
+npm install -g @researai/deepscientist
 ```
 
 If you plan to compile LaTeX locally later, you can also install the lightweight PDF runtime:
@@ -33,6 +33,12 @@ Start the local daemon and web workspace:
 ds
 ```
 
+DeepScientist now uses `uv` to manage a locked local Python runtime. If a conda environment is active and already provides Python `>=3.11`, `ds` will prefer that environment automatically. Otherwise `uv` will provision a managed Python under the DeepScientist home.
+
+If `uv` is missing on your machine, `ds` will bootstrap a local copy automatically during the first start. The npm package also ships with the Codex CLI dependency, so you do not need a separate `npm install -g @openai/codex`. You may still need to run `codex` once later to finish login.
+
+By default, the DeepScientist home is `~/DeepScientist` on macOS and Linux, and `%USERPROFILE%\\DeepScientist` on Windows. You can override it with `ds --home <path>`.
+
 By default, the web UI is served at:
 
 ```text
@@ -41,6 +47,18 @@ http://127.0.0.1:20999
 
 If the browser does not open automatically, paste that address into your browser manually.
 
+If you want another port:
+
+```bash
+ds --port 21000
+```
+
+If you want the web UI to bind on all interfaces:
+
+```bash
+ds --host 0.0.0.0 --port 21000
+```
+
 ## 3. Understand the Home Page
 
 When DeepScientist starts, open the home page at `/`.
@@ -49,22 +67,22 @@ When DeepScientist starts, open the home page at `/`.
 
 The home page is intentionally simple. The two main entry buttons are:
 
-- `Start Research`: create a new quest and launch a new research run
-- `List Quest`: reopen an existing quest
+- `Start Research`: create a new project and launch a new research run
+- `Open Project`: reopen an existing project
 
 If you are using DeepScientist for the first time, start with `Start Research`.
 
-## 4. Create a New Quest With Start Research
+## 4. Create a New Project With Start Research
 
 Click `Start Research` to open the launch dialog.
 
 ![Start Research dialog](../images/quickstart/01-start-research.png)
 
-This dialog creates a new quest repository and writes the startup contract for the agent.
+This dialog creates a new project repository and writes the startup contract for the agent.
 
 The most important fields are:
 
-- `Quest ID`: usually auto-generated in sequence such as `00`, `01`, `02`
+- `Project ID`: usually auto-generated in sequence such as `00`, `01`, `02`
 - `Primary request` / research goal: the actual scientific task you want the agent to work on
 - `Reuse Baseline`: optional; choose an existing baseline if you want to continue from an earlier result
 - `Research intensity`: how aggressive the run should be
@@ -81,29 +99,29 @@ For a first test, keep it simple:
 
 Then click the final `Start Research` action in the dialog.
 
-## 5. Reopen an Existing Quest With List Quest
+## 5. Reopen an Existing Project With Open Project
 
-Click `List Quest` on the home page to open the existing quest list.
+Click `Open Project` on the home page to open the existing project list.
 
-![List Quest dialog](../images/quickstart/02-list-quest.png)
+![Open Project dialog](../images/quickstart/02-list-quest.png)
 
 Use this dialog when you want to:
 
-- reopen a quest that is already running or already finished
-- search by quest title or quest id
+- reopen a project that is already running or already finished
+- search by project title or project id
 - jump back into a previous workspace quickly
 
-Each row corresponds to one quest repository. Click a quest card to open it.
+Each row corresponds to one project repository. Click a project card to open it.
 
-## 6. What Happens After Opening a Quest
+## 6. What Happens After Opening a Project
 
-After you create or open a quest, DeepScientist takes you to the workspace page for that quest.
+After you create or open a project, DeepScientist takes you to the workspace page for that project.
 
 Inside the workspace, the usual flow is:
 
 1. watch agent progress in Copilot / Studio
 2. inspect files, notes, and generated artifacts
-3. use Canvas to understand the current quest graph and stage progress
+3. use Canvas to understand the current project graph and stage progress
 4. stop the run only when you intentionally want to interrupt it
 
 ## 7. Useful Runtime Commands

package/docs/en/01_SETTINGS_REFERENCE.md

@@ -92,9 +92,9 @@ acp:
 - Type: `string`
 - Default: the installed DeepScientist home, usually `~/DeepScientist`
 - UI label: `Home path`
-- Meaning: root directory for config, quests, memory, plugins, logs, and cache.
+- Meaning: root directory for config, projects, memory, plugins, logs, and cache.
 - When to change: only when you intentionally installed DeepScientist somewhere else.
-- Notes: this is not a single quest path; it is the runtime root.
+- Notes: this is not a single project path; it is the runtime root.
 
 **`default_runner`**
 
@@ -102,7 +102,7 @@ acp:
 - Default: `codex`
 - Allowed values: currently `codex`, `claude`
 - UI label: `Default runner`
-- Meaning: runner used when a quest does not override it.
+- Meaning: runner used when a project does not override it.
 - Notes: in the current branch, `codex` is the primary path and `claude` remains a reserved slot.
 
 **`default_locale`**
@@ -120,15 +120,15 @@ acp:
 - Type: `boolean`
 - Default: `true`
 - UI label: `Restore sessions on start`
-- Meaning: restore previous quest sessions when the daemon starts.
+- Meaning: restore previous project sessions when the daemon starts.
 
 **`daemon.max_concurrent_quests`**
 
 - Type: `number`
 - Default: `1`
-- UI label: `Max concurrent quests`
-- Meaning: upper bound on how many quests may run at the same time.
-- Recommendation: keep `1` unless you intentionally want parallel quest execution.
+- UI label: `Max concurrent projects`
+- Meaning: upper bound on how many projects may run at the same time.
+- Recommendation: keep `1` unless you intentionally want parallel project execution.
 
 **`daemon.ack_timeout_ms`**
 
@@ -202,7 +202,7 @@ acp:
 - Type: `boolean`
 - Default: `true`
 - UI label: `Auto-checkpoint`
-- Meaning: create Git checkpoints automatically during quest progress.
+- Meaning: create Git checkpoints automatically during project progress.
 
 **`git.auto_push`**
 
@@ -252,15 +252,15 @@ Palette selection is no longer exposed in `Settings` or `config.yaml`.
 
 - Type: `boolean`
 - Default: `true`
-- UI label: `Sync quest skills on create`
-- Meaning: mirror skills into quest-local runner homes when a quest is created.
+- UI label: `Sync project skills on create`
+- Meaning: mirror skills into project-local runner homes when a project is created.
 
 **`skills.sync_quest_on_open`**
 
 - Type: `boolean`
 - Default: `true`
-- UI label: `Sync quest skills on open`
-- Meaning: refresh quest-local skill mirrors when an existing quest is opened.
+- UI label: `Sync project skills on open`
+- Meaning: refresh project-local skill mirrors when an existing project is opened.
 
 ### Connector policy
 
@@ -271,7 +271,7 @@ These fields are global connector behaviors, not per-platform credentials.
 - Type: `boolean`
 - Default: `true`
 - UI label: `Auto-ack incoming messages`
-- Meaning: send a short acknowledgment before the full quest response completes.
+- Meaning: send a short acknowledgment before the full project response completes.
 
 **`connectors.milestone_push`**
 
@@ -285,7 +285,7 @@ These fields are global connector behaviors, not per-platform credentials.
 - Type: `boolean`
 - Default: `true`
 - UI label: `Enable direct chat`
-- Meaning: allow connectors to continue quests from direct messages.
+- Meaning: allow connectors to continue projects from direct messages.
 
 ### Cloud link
 
@@ -371,7 +371,7 @@ These settings are compatibility knobs for ACP-style external consumers.
 
 ### Summary
 
-`runners.yaml` defines which runner executes quests and what its default model, approval policy, sandbox, and retry behavior should be. In the current open-source release:
+`runners.yaml` defines which runner executes projects and what its default model, approval policy, sandbox, and retry behavior should be. In the current open-source release:
 
 - `codex`: primary path, enabled by default
 - `claude`: TODO / reserved slot, disabled by default, not runnable yet
@@ -433,7 +433,7 @@ claude:
 - Type: `string`
 - Default: `codex=gpt-5.4`, `claude=inherit`
 - UI label: `Default model`
-- Meaning: default model used when a quest does not override it.
+- Meaning: default model used when a project does not override it.
 
 **`model_reasoning_effort`**
 
@@ -534,7 +534,7 @@ Current design rules:
 
 - prefer no-public-callback transports
 - keep webhook / relay fields only as legacy or fallback paths
-- treat connectors as alternate quest control surfaces, not disconnected notification bots
+- treat connectors as alternate project control surfaces, not disconnected notification bots
 
 ### Top-level routing
 
@@ -586,7 +586,7 @@ These fields appear across multiple connectors:
 
 - Type: `boolean`
 - Default: usually `true`
-- Meaning: direct messages automatically follow the current active quest.
+- Meaning: direct messages automatically follow the current active project.
 
 ### `telegram`
 
@@ -969,7 +969,7 @@ allow_unsigned: false
 
 ### Summary
 
-This file configures external MCP servers. It does not configure built-in `memory`, `artifact`, or `bash_exec`, and it does not store quest-local MCP state.
+This file configures external MCP servers. It does not configure built-in `memory`, `artifact`, or `bash_exec`, and it does not store project-local MCP state.
 
 ### Schema
 
@@ -992,7 +992,7 @@ servers:
 
 - Type: `boolean`
 - Default: new cards start as `false`
-- Meaning: only enabled external MCP servers are exposed to quests or runners.
+- Meaning: only enabled external MCP servers are exposed to projects or runners.
 
 **`servers.<server_id>.transport`**
 

package/docs/en/02_START_RESEARCH_GUIDE.md

@@ -9,10 +9,10 @@ Implementation sources:
 
 ## What the dialog does
 
-`Start Research` is not only a “new quest” form. It does four things together:
+`Start Research` is not only a “new project” form. It does four things together:
 
 1. collects structured kickoff context
-2. compiles that context into the first quest prompt
+2. compiles that context into the first project prompt
 3. binds an optional reusable baseline
 4. persists a structured `startup_contract` for later prompt building
 
@@ -105,17 +105,17 @@ The dialog submits:
 
 ## Field reference
 
-### Core quest identity
+### Core project identity
 
 **`title`**
 
-- Human-readable quest title.
+- Human-readable project title.
 - Used in cards and workspace headers.
 - Does not need to equal `quest_id`.
 
 **`quest_id`**
 
-- Stable quest identifier and directory name.
+- Stable project identifier stored in `quest_id` and used as the directory name.
 - By default the runtime suggests the next sequential id.
 - Manual override is allowed.
 
@@ -166,7 +166,7 @@ The dialog submits:
 
 **`need_research_paper`**
 
-- `true`: the quest should keep going through analysis and writing readiness.
+- `true`: the project should keep going through analysis and writing readiness.
 - `false`: optimize for the strongest justified algorithmic result and avoid default paper routing.
 
 ### High-level control knobs
@@ -203,7 +203,7 @@ This is the main public knob for round depth.
 Only meaningful when `launch_mode = custom`.
 
 - `continue_existing_state`
-  - start by auditing existing baselines, results, drafts, or mixed quest assets
+  - start by auditing existing baselines, results, drafts, or mixed project assets
   - prompt builder should steer the agent toward `intake-audit`
 - `revision_rebuttal`
   - start from reviewer comments, revision packets, or a rebuttal task
@@ -247,7 +247,7 @@ Override rule:
 
 `compileStartResearchPrompt(...)` writes a human-readable kickoff prompt containing:
 
-- quest bootstrap
+- project bootstrap
 - primary research request
 - research goals
 - baseline context
@@ -318,8 +318,8 @@ Custom launch behavior is explicit:
 
 ```json
 {
-  "title": "Continue retrieval quest",
-  "goal": "Continue the existing retrieval quest and decide whether a fresh main run is still needed.",
+  "title": "Continue retrieval project",
+  "goal": "Continue the existing retrieval project and decide whether a fresh main run is still needed.",
   "quest_id": "013",
   "requested_baseline_ref": null,
   "startup_contract": {
@@ -387,7 +387,7 @@ Custom launch behavior is explicit:
 
 ## Operational implications
 
-- The startup contract is durable quest state, not only UI state.
+- The startup contract is durable project state, not only UI state.
 - Prompt building later reads `launch_mode`, `custom_profile`, and related summaries again.
 - This means `Start Research` shapes not just the first turn, but later routing decisions too.
 

package/docs/en/03_QQ_CONNECTOR_GUIDE.md

@@ -16,7 +16,7 @@ If you previously followed an OpenClaw or NanoClaw article, note the key differe
 After finishing this guide, you should be able to:
 
 - chat with DeepScientist from QQ private messages
-- let QQ auto-bind to the latest active quest
+- let QQ auto-bind to the latest active project
 - use `/new`, `/use latest`, `/status`, and related commands from QQ
 - see the detected `openid` in the `Settings` page
 - run safe readiness checks and send probes from the `Settings` page
@@ -219,7 +219,7 @@ When the connector is fully working, you should usually see all of these:
 - `Detected OpenID` is no longer empty in `Settings > Connectors > QQ`
 - the `Snapshot` panel shows a discovered target and the bound target is no longer empty
 - clicking `Send probe` again no longer reports an empty delivery target
-- if a latest quest already exists, plain text continues that quest automatically; if no quest exists yet, the bot returns help instead
+- if a latest project already exists, plain text continues that project automatically; if no project exists yet, the bot returns help instead
 
 ### 5.2 Error quick decoder
 
@@ -239,17 +239,17 @@ Common commands:
 | Command | Meaning |
 | --- | --- |
 | `/help` | Show help |
-| `/projects` or `/list` | List quests |
-| `/use <quest_id>` | Bind a specific quest |
-| `/use latest` | Bind the newest quest |
-| `/new <goal>` | Create a new quest and bind the current QQ conversation |
-| `/status` | Show the current quest status |
+| `/projects` or `/list` | List projects |
+| `/use <quest_id>` | Bind a specific project |
+| `/use latest` | Bind the newest project |
+| `/new <goal>` | Create a new project and bind the current QQ conversation |
+| `/status` | Show the current project status |
 
 Recommended usage:
 
-- if a latest quest already exists, plain text usually continues that quest
-- if there is no quest yet, start with `/new <goal>`
-- if you want to switch to another quest, send `/use <quest_id>` explicitly
+- if a latest project already exists, plain text usually continues that project
+- if there is no project yet, start with `/new <goal>`
+- if you want to switch to another project, send `/use <quest_id>` explicitly
 
 ## 7. Most common mistakes
 

package/docs/en/05_TUI_GUIDE.md

@@ -9,7 +9,7 @@ For the current runtime control flow, prompt/skill execution model, MCP surface,
 Use the current workspace install:
 
 ```bash
-pip install -e .
+uv sync
 npm install
 ```
 

package/docs/en/09_DOCTOR.md

@@ -4,10 +4,10 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
 
 ## Recommended flow
 
-1. Install DeepScientist and Codex:
+1. Install DeepScientist:
 
    ```bash
-   npm install -g @openai/codex @researai/deepscientist
+   npm install -g @researai/deepscientist
    ```
 
 2. Try to start DeepScientist:
@@ -30,6 +30,7 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
 
 - local Python runtime health
 - whether `~/DeepScientist` exists and is writable
+- whether `uv` is available to manage the local Python runtime
 - whether `git` is installed and configured
 - whether required config files are valid
 - whether the current release is still using `codex` as the runnable runner
@@ -42,10 +43,10 @@ Use `ds doctor` when DeepScientist does not start cleanly after installation.
 
 ### Codex is missing
 
-Run:
+Run the package install again so the bundled Codex dependency is present:
 
 ```bash
-npm install -g @openai/codex
+npm install -g @researai/deepscientist
 ```
 
 ### Codex is installed but not logged in
@@ -58,6 +59,20 @@ codex
 
 Finish login once, then rerun `ds doctor`.
 
+### `uv` is missing
+
+Normally `ds` will bootstrap a local `uv` automatically. If that bootstrap fails, install it manually:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+On Windows PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
 ### Local paper PDF compilation is unavailable
 
 DeepScientist can compile papers without a full TeX Live install if you add a lightweight TinyTeX runtime:
@@ -84,6 +99,35 @@ If another service already uses the port, change `ui.port` in:
 ~/DeepScientist/config/config.yaml
 ```
 
+Or start on another port directly:
+
+```bash
+ds --port 21000
+```
+
+### Python `3.10` or older is active
+
+DeepScientist still prefers the active conda environment when it already satisfies Python `>=3.11`.
+
+If your current conda environment is too old, either activate a newer one:
+
+```bash
+conda activate ds311
+python3 --version
+which python3
+ds
+```
+
+Or create a suitable one:
+
+```bash
+conda create -n ds311 python=3.11 -y
+conda activate ds311
+ds
+```
+
+If you do nothing, `ds` can still bootstrap a managed `uv` + Python runtime automatically under the DeepScientist home.
+
 ### Git user identity is missing
 
 Run:

package/docs/en/90_ARCHITECTURE.md

@@ -42,7 +42,7 @@ The normal user path is:
 
 1. `npm install -g @researai/deepscientist`
 2. run `ds`
-3. `bin/ds.js` ensures the local Python runtime is ready under `~/DeepScientist/runtime/venv`
+3. `bin/ds.js` ensures a locked uv-managed Python runtime is ready under `~/DeepScientist/runtime/python-env`
 4. the launcher starts the Python daemon
 5. the daemon serves the web workspace and shared API surface
 6. the TUI and web UI both consume the same daemon contracts
@@ -57,7 +57,9 @@ Key directories:
 
 - `runtime/`
   - launcher-managed runtime state
-  - Python venv
+  - uv-managed Python environment
+  - uv-managed Python installs
+  - uv cache
   - built bundle helpers
   - managed local tool installs under `runtime/tools/`
 - `config/`

package/docs/zh/00_QUICK_START.md

@@ -1,22 +1,22 @@
-# 00 快速开始：启动 DeepScientist 并运行第一个 Quest
+# 00 快速开始：启动 DeepScientist 并运行第一个项目
 
-这份文档面向第一次使用 DeepScientist 的用户，目标是让你从安装直接走到“成功启动并跑起来一个 quest”。
+这份文档面向第一次使用 DeepScientist 的用户，目标是让你从安装直接走到“成功启动并跑起来一个项目”。
 
 你只需要完成四步：
 
 1. 安装 DeepScientist
 2. 启动本地运行时
-3. 在首页创建一个新 quest
-4. 从 quest 列表重新打开已有任务
+3. 在首页创建一个新项目
+4. 从项目列表重新打开已有任务
 
 本文中的截图直接使用当前在线页面 `deepscientist.cc:20999` 作为示例。你本地运行后的页面 `127.0.0.1:20999` 通常会与它保持一致或非常接近。
 
 ## 1. 安装
 
-先全局安装 Codex 和 DeepScientist：
+全局安装 DeepScientist：
 
 ```bash
-npm install -g @openai/codex @researai/deepscientist
+npm install -g @researai/deepscientist
 ```
 
 如果你后续还要在本地编译论文 PDF，也可以顺手安装轻量级 LaTeX 运行时：
@@ -33,6 +33,12 @@ ds latex install-runtime
 ds
 ```
 
+DeepScientist 现在使用 `uv` 管理锁定的本地 Python 运行时。如果你已经激活了 conda 环境，且其中的 Python 满足 `>=3.11`，`ds` 会优先使用它；否则 `uv` 会自动在 DeepScientist home 下准备受管 Python。
+
+如果你的机器上还没有 `uv`，第一次运行 `ds` 时会自动在本地安装一份。npm 包本身也已经带上了 Codex CLI 依赖，因此不需要再单独执行 `npm install -g @openai/codex`；但你后续仍然可能需要手动运行一次 `codex` 完成登录。
+
+默认情况下，DeepScientist home 在 macOS / Linux 上是 `~/DeepScientist`，在 Windows 上是 `%USERPROFILE%\\DeepScientist`。如果你希望放到别的路径，可以直接使用 `ds --home <path>`。
+
 默认情况下，网页会运行在：
 
 ```text
@@ -41,6 +47,18 @@ http://127.0.0.1:20999
 
 如果浏览器没有自动打开，就手动访问这个地址。
 
+如果你想改端口，可以直接运行：
+
+```bash
+ds --port 21000
+```
+
+如果你希望绑定到所有网卡地址：
+
+```bash
+ds --host 0.0.0.0 --port 21000
+```
+
 ## 3. 认识首页
 
 启动完成后，先打开 `/` 首页。
@@ -49,12 +67,12 @@ http://127.0.0.1:20999
 
 首页故意做得很简单，核心只有两个按钮：
 
-- `Start Research`：创建一个新的 quest，并立刻启动新的研究任务
-- `List Quest`：打开已有 quest 列表，重新进入已经存在的任务
+- `Start Research`：创建一个新的项目，并立刻启动新的研究任务
+- `打开项目`：打开已有项目列表，重新进入已经存在的任务
 
 如果你是第一次使用，建议先从 `Start Research` 开始。
 
-## 4. 使用 Start Research 创建新 Quest
+## 4. 使用 Start Research 创建新项目
 
 点击 `Start Research`，会弹出启动表单。
 
@@ -64,7 +82,7 @@ http://127.0.0.1:20999
 
 最重要的字段是：
 
-- `Quest ID`：通常会自动按顺序生成，例如 `00`、`01`、`02`
+- `项目 ID`：通常会自动按顺序生成，例如 `00`、`01`、`02`
 - `Primary request` / 研究目标：你真正希望 agent 完成的科研任务
 - `Reuse Baseline`：可选；如果你要复用已有 baseline，就在这里选择
 - `Research intensity`：本次研究的投入强度
@@ -81,29 +99,29 @@ http://127.0.0.1:20999
 
 最后点击弹窗底部的 `Start Research` 即可正式启动。
 
-## 5. 使用 List Quest 打开已有任务
+## 5. 使用“打开项目”重新进入已有任务
 
-点击首页上的 `List Quest`，会打开 quest 列表。
+点击首页上的 `打开项目`，会打开项目列表。
 
-![List Quest 弹窗](../images/quickstart/02-list-quest.png)
+![打开项目 弹窗](../images/quickstart/02-list-quest.png)
 
 这个列表适合以下场景：
 
-- 重新进入一个已经在运行中的 quest
-- 打开一个以前已经完成或已经创建过的 quest
-- 按 quest 标题或 quest id 搜索目标任务
+- 重新进入一个已经在运行中的项目
+- 打开一个以前已经完成或已经创建过的项目
+- 按项目标题或项目 ID 搜索目标任务
 
-列表中的每一行都对应一个 quest 仓库。点击对应卡片即可进入该 quest 的工作区。
+列表中的每一行都对应一个项目仓库。点击对应卡片即可进入该项目的工作区。
 
-## 6. 打开 Quest 之后会发生什么
+## 6. 打开项目之后会发生什么
 
-创建或打开 quest 后，DeepScientist 会进入这个 quest 的工作区页面。
+创建或打开项目后，DeepScientist 会进入这个项目的工作区页面。
 
 通常你会在里面做这些事情：
 
 1. 在 Copilot / Studio 中观察 agent 的实时进展
 2. 查看文件、笔记和生成出来的 artifact
-3. 在 Canvas 中理解当前 quest 的图结构与阶段进展
+3. 在 Canvas 中理解当前项目的图结构与阶段进展
 4. 只有在你明确想中断时，才主动停止任务
 
 ## 7. 常用运行命令