@researai/deepscientist 1.5.1 → 1.5.3

package/docs/zh/01_SETTINGS_REFERENCE.md

@@ -92,9 +92,9 @@ acp:
 - 类型：`string`
 - 默认值：安装时的 DeepScientist 主目录，通常为 `~/DeepScientist`
 - 页面标签：`Home path`
-- 作用：这是配置、quests、memory、plugins、logs、cache 的根路径。
+- 作用：这是配置、项目、memory、plugins、logs、cache 的根路径。
 - 何时修改：仅在你明确使用自定义安装目录时修改。
-- 注意事项：这不是单个 quest 路径，而是整个 DeepScientist 的运行时根目录。
+- 注意事项：这不是单个项目路径，而是整个 DeepScientist 的运行时根目录。
 
 **`default_runner`**
 
@@ -102,7 +102,7 @@ acp:
 - 默认值：`codex`
 - 允许值：当前页面预设为 `codex`、`claude`
 - 页面标签：`Default runner`
-- 作用：当 quest 没有单独覆盖 runner 时，默认走这里指定的 runner。
+- 作用：当项目没有单独覆盖 runner 时，默认走这里指定的 runner。
 - 何时修改：只有在你真的接通并启用了其他 runner 时才需要改。
 - 注意事项：当前仓库的真实主路径仍然是 `codex`；`claude` 仍是预留位。
 
@@ -122,17 +122,17 @@ acp:
 - 类型：`boolean`
 - 默认值：`true`
 - 页面标签：`Restore sessions on start`
-- 作用：daemon 启动时尝试恢复之前的 quest 会话状态。
+- 作用：daemon 启动时尝试恢复之前的项目会话状态。
 - 何时关闭：你希望每次启动都从干净的运行时状态进入。
 
 **`daemon.max_concurrent_quests`**
 
 - 类型：`number`
 - 默认值：`1`
-- 页面标签：`Max concurrent quests`
-- 作用：限制同时活跃的 quest 数量。
+- 页面标签：`Max concurrent projects`
+- 作用：限制同时活跃的项目数量。
 - 推荐值：大多数情况下保持 `1`。
-- 风险：并发 quest 越多，资源竞争、连接器串扰和观察复杂度越高。
+- 风险：并发项目越多，资源竞争、连接器串扰和观察复杂度越高。
 
 **`daemon.ack_timeout_ms`**
 
@@ -212,7 +212,7 @@ acp:
 - 类型：`boolean`
 - 默认值：`true`
 - 页面标签：`Auto-checkpoint`
-- 作用：quest 过程中自动做 Git 检查点。
+- 作用：项目过程中自动做 Git 检查点。
 - 何时关闭：你完全希望手动控制提交节奏。
 
 **`git.auto_push`**
@@ -263,15 +263,15 @@ acp:
 
 - 类型：`boolean`
 - 默认值：`true`
-- 页面标签：`Sync quest skills on create`
-- 作用：创建 quest 时，把技能镜像到 quest 本地 `.codex/skills` / `.claude/agents`。
+- 页面标签：`Sync project skills on create`
+- 作用：创建项目时，把技能镜像到项目本地 `.codex/skills` / `.claude/agents`。
 
 **`skills.sync_quest_on_open`**
 
 - 类型：`boolean`
 - 默认值：`true`
-- 页面标签：`Sync quest skills on open`
-- 作用：打开已有 quest 时刷新本地技能镜像。
+- 页面标签：`Sync project skills on open`
+- 作用：打开已有项目时刷新本地技能镜像。
 
 ### Connector policy
 
@@ -296,7 +296,7 @@ acp:
 - 类型：`boolean`
 - 默认值：`true`
 - 页面标签：`Enable direct chat`
-- 作用：允许 connector 私聊直接驱动 quest。
+- 作用：允许 connector 私聊直接驱动项目。
 
 ### Cloud link
 
@@ -385,7 +385,7 @@ acp:
 
 ### 摘要
 
-`runners.yaml` 定义 quest 实际由哪个 runner 执行，以及 runner 的模型默认值、审批策略、沙箱策略和失败重试策略。在当前开源版本中：
+`runners.yaml` 定义项目实际由哪个 runner 执行，以及 runner 的模型默认值、审批策略、沙箱策略和失败重试策略。在当前开源版本中：
 
 - `codex`：主路径，默认启用。
 - `claude`：TODO / 预留条目，默认禁用，暂时不能运行。
@@ -447,7 +447,7 @@ claude:
 - 类型：`string`
 - 默认值：`codex=gpt-5.4`，`claude=inherit`
 - 页面标签：`Default model`
-- 作用：quest 和单次请求没有覆盖时的默认模型。
+- 作用：项目和单次请求没有覆盖时的默认模型。
 
 **`model_reasoning_effort`**
 
@@ -539,7 +539,7 @@ claude:
 - 第一版部署一般保持 `codex.enabled: true`、`claude.enabled: false`。
 - 当前版本不要把 `default_runner` 从 `codex` 改走。
 - 如果你不希望任何自动审批，才把 `approval_policy` 调成更严格模式。
-- 如果 quest 经常需要长时间工具调用，不要随意把 `mcp_tool_timeout_sec` 改小。
+- 如果项目经常需要长时间工具调用，不要随意把 `mcp_tool_timeout_sec` 改小。
 
 ## `connectors.yaml`
 
@@ -549,7 +549,7 @@ claude:
 
 - 优先使用无需公网回调的原生传输路径。
 - legacy webhook / relay 字段只作为兼容或兜底。
-- 所有连接器最终都属于同一个 quest 交互系统，而不是各自独立的一套消息逻辑。
+- 所有连接器最终都属于同一个项目交互系统，而不是各自独立的一套消息逻辑。
 
 ### 顶层路由字段
 
@@ -602,7 +602,7 @@ claude:
 
 - 类型：`boolean`
 - 默认值：大多数 connector 为 `true`
-- 作用：私聊默认自动跟随当前活跃 quest。
+- 作用：私聊默认自动跟随当前活跃项目。
 
 ### `telegram`
 
@@ -902,7 +902,7 @@ legacy Meta Cloud 字段：
 
 - 类型：`boolean`
 - 默认值：`true`
-- 作用：QQ 私聊默认跟随最新活跃 quest。
+- 作用：QQ 私聊默认跟随最新活跃项目。
 
 ### QQ 里程碑媒体策略
 
@@ -1000,7 +1000,7 @@ allow_unsigned: false
 
 ### 摘要
 
-这个文件管理外部 MCP 服务。它不控制内置 `memory`、`artifact`、`bash_exec`，也不保存 quest 内部工具调用历史。
+这个文件管理外部 MCP 服务。它不控制内置 `memory`、`artifact`、`bash_exec`，也不保存项目内部工具调用历史。
 
 ### 结构
 
@@ -1023,7 +1023,7 @@ servers:
 
 - 类型：`boolean`
 - 默认值：新卡片默认为 `false`
-- 作用：只有启用的外部 MCP 才会暴露给 quest 或 runner。
+- 作用：只有启用的外部 MCP 才会暴露给项目或 runner。
 
 **`servers.<server_id>.transport`**
 

package/docs/zh/02_START_RESEARCH_GUIDE.md

@@ -9,10 +9,10 @@
 
 ## 这个弹窗实际做什么
 
-`Start Research` 不只是“新建 quest 表单”，它同时完成四件事：
+`Start Research` 不只是“新建项目表单”，它同时完成四件事：
 
 1. 收集结构化启动上下文
-2. 把这些上下文编译成 quest 的第一条 kickoff prompt
+2. 把这些上下文编译成项目的第一条 kickoff prompt
 3. 绑定一个可选的可复用 baseline
 4. 持久化 `startup_contract`，供后续 prompt builder 持续读取
 
@@ -113,17 +113,17 @@ type StartResearchContractFields = {
 
 ## 字段说明
 
-### Quest 基本身份
+### 项目基本身份
 
 **`title`**
 
-- Quest 的人类可读标题。
+- 项目的人类可读标题。
 - 用于卡片和工作区标题。
 - 不要求与 `quest_id` 一致。
 
 **`quest_id`**
 
-- Quest 的稳定标识，也是目录名。
+- 项目的稳定标识，保存在 `quest_id` 中，同时也是目录名。
 - 默认由 runtime 提供下一个顺序编号。
 - 允许用户手动覆盖。
 
@@ -256,17 +256,17 @@ type StartResearchContractFields = {
 
 `compileStartResearchPrompt(...)` 会生成一段可读 kickoff prompt，包含：
 
-- quest bootstrap
-- primary research request
-- research goals
-- baseline context
-- reference papers / repositories
-- operational constraints
-- research delivery mode
-- decision handling mode
-- launch mode
-- research contract
-- mandatory working rules
+- 项目启动上下文
+- 核心研究请求
+- 研究目标
+- baseline 上下文
+- 参考论文 / 仓库
+- 运行约束
+- 研究交付模式
+- 决策处理模式
+- 启动模式
+- 研究合同
+- 必须遵守的工作规则
 
 其中自定义启动会被明确写出来：
 
@@ -327,8 +327,8 @@ type StartResearchContractFields = {
 
 ```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": {
@@ -396,7 +396,7 @@ type StartResearchContractFields = {
 
 ## 运行时意义
 
-- `startup_contract` 是 quest 的持久状态，不只是 UI 临时字段。
+- `startup_contract` 是项目的持久状态，不只是 UI 临时字段。
 - 后续 prompt builder 还会继续读取 `launch_mode`、`custom_profile`、`entry_state_summary`、`review_summary`、`custom_brief`。
 - 所以 `Start Research` 不只影响第一轮，还会影响后续路由判断。
 

package/docs/zh/03_QQ_CONNECTOR_GUIDE.md

@@ -16,7 +16,7 @@
 完成本文档后，你应该可以做到：
 
 - 用 QQ 私聊 DeepScientist
-- 让 QQ 自动绑定到当前最新 quest
+- 让 QQ 自动绑定到当前最新项目
 - 在 QQ 中使用 `/new`、`/use latest`、`/status` 等命令
 - 在 `Settings` 页面看到自动检测到的 `openid`
 - 从 `Settings` 页面执行非破坏性的连接测试
@@ -219,7 +219,7 @@ QQ readiness is healthy, but no OpenID has been learned yet. Save credentials, t
 - `Settings > Connectors > QQ` 中的 `Detected OpenID` 不再为空
 - `Snapshot` 里出现已经发现的目标会话，且绑定目标不是空
 - 再次点击“发送测试消息”时，不再提示 target 为空
-- 如果当前已经有最新 quest，普通文本会自动进入该 quest；如果还没有 quest，则优先返回帮助信息
+- 如果当前已经有最新项目，普通文本会自动进入该项目；如果还没有项目，则优先返回帮助信息
 
 ### 5.2 报错提示速查
 
@@ -239,17 +239,17 @@ QQ readiness is healthy, but no OpenID has been learned yet. Save credentials, t
 | 命令 | 作用 |
 | --- | --- |
 | `/help` | 查看帮助 |
-| `/projects` 或 `/list` | 查看 quest 列表 |
-| `/use <quest_id>` | 绑定指定 quest |
-| `/use latest` | 绑定最新 quest |
-| `/new <goal>` | 新建 quest 并把当前 QQ 会话绑定过去 |
-| `/status` | 查看当前 quest 状态 |
+| `/projects` 或 `/list` | 查看项目列表 |
+| `/use <quest_id>` | 绑定指定项目 |
+| `/use latest` | 绑定最新项目 |
+| `/new <goal>` | 新建项目并把当前 QQ 会话绑定过去 |
+| `/status` | 查看当前项目状态 |
 
 日常沟通建议：
 
-- 如果已经有最新 quest，普通文本通常会继续那个 quest
-- 如果还没有 quest，优先发送 `/new <goal>`
-- 如果你想切换到另一个 quest，显式发送 `/use <quest_id>`
+- 如果已经有最新项目，普通文本通常会继续那个项目
+- 如果还没有项目，优先发送 `/new <goal>`
+- 如果你想切换到另一个项目，显式发送 `/use <quest_id>`
 
 ## 7. 最容易踩坑的地方
 

package/docs/zh/05_TUI_GUIDE.md

@@ -9,7 +9,7 @@
 在当前仓库目录中：
 
 ```bash
-pip install -e .
+uv sync
 npm install
 ```
 

package/docs/zh/09_DOCTOR.md

@@ -4,10 +4,10 @@
 
 ## 推荐使用流程
 
-1. 先安装 DeepScientist 和 Codex：
+1. 先安装 DeepScientist：
 
    ```bash
-   npm install -g @openai/codex @researai/deepscientist
+   npm install -g @researai/deepscientist
    ```
 
 2. 先直接尝试启动：
@@ -30,6 +30,7 @@
 
 - 本地 Python 运行时是否健康
 - `~/DeepScientist` 是否存在且可写
+- `uv` 是否可用，以便管理本地 Python 运行时
 - `git` 是否安装并完成基本配置
 - 必需配置文件是否有效
 - 当前开源版本是否仍然使用 `codex` 作为可运行 runner
@@ -42,10 +43,10 @@
 
 ### 没有安装 Codex
 
-运行：
+重新安装 DeepScientist，让随包的 Codex 依赖一起装好：
 
 ```bash
-npm install -g @openai/codex
+npm install -g @researai/deepscientist
 ```
 
 ### 已安装 Codex，但还没有登录
@@ -58,6 +59,20 @@ codex
 
 先完成一次登录，再重新执行 `ds doctor`。
 
+### 没有安装 `uv`
+
+正常情况下，第一次运行 `ds` 会自动在本地安装 `uv`。如果自动安装失败，再手动执行：
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+如果你在 Windows PowerShell：
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
 ### 本地论文 PDF 编译暂时不可用
 
 如果你希望直接在 DeepScientist 里本地编译论文，可以安装一个轻量级 TinyTeX `pdflatex` 运行时：
@@ -86,6 +101,33 @@ ds --stop
 
 里的 `ui.port`。
 
+也可以直接临时换一个端口启动：
+
+```bash
+ds --port 21000
+```
+
+### 当前激活的是 Python `3.10` 或更低版本
+
+如果你已经在使用 conda，而当前环境过旧，请先激活正确环境：
+
+```bash
+conda activate ds311
+python3 --version
+which python3
+ds
+```
+
+或者新建一个可用环境：
+
+```bash
+conda create -n ds311 python=3.11 -y
+conda activate ds311
+ds
+```
+
+如果你不手动切换，`ds` 也可以在 DeepScientist home 下自动准备受管的 `uv` + Python 运行时。
+
 ### Git 用户身份没有配置
 
 运行：

package/install.sh

@@ -233,10 +233,8 @@ copy_source_tree() {
       --exclude='./node_modules' \
       --exclude='./ui' \
       --exclude='./src/ui/node_modules' \
-      --exclude='./src/ui/dist' \
       --exclude='./src/ui/lib/node_modules' \
       --exclude='./src/tui/node_modules' \
-      --exclude='./src/tui/dist' \
       --exclude='./src/deepscientist.egg-info' \
       . | tar -C "$target" -xf -
   else
@@ -252,16 +250,18 @@ prune_tree() {
     "$target/node_modules" \
     "$target/ui" \
     "$target/src/ui/node_modules" \
-    "$target/src/ui/dist" \
     "$target/src/ui/lib/node_modules" \
     "$target/src/tui/node_modules" \
-    "$target/src/tui/dist" \
     "$target/src/deepscientist.egg-info"
   find "$target" -type d -name '__pycache__' -prune -exec rm -rf {} +
   find "$target" -type f \( -name '*.pyc' -o -name '*.pyo' \) -delete
 }
 
 build_ui() {
+  if should_use_prebuilt_bundle "$1/src/ui" "$1/src/ui/dist" "index.html" "${DEEPSCIENTIST_FORCE_UI_BUILD:-}"; then
+    print_step "Using up-to-date web UI bundle from source tree"
+    return
+  fi
   print_step "Building web UI in install tree"
   npm --prefix "$1/src/ui" install --include=dev --no-audit --no-fund
   npm --prefix "$1/src/ui" run build
@@ -274,12 +274,125 @@ install_root_runtime() {
 }
 
 build_tui() {
+  local tui_entry=""
+  if [ -f "$1/src/tui/dist/index.js" ]; then
+    tui_entry="index.js"
+  elif [ -f "$1/src/tui/dist/index.cjs" ]; then
+    tui_entry="index.cjs"
+  elif [ -d "$1/src/tui/dist/components" ]; then
+    tui_entry="components"
+  fi
+  if [ -n "$tui_entry" ] && should_use_prebuilt_bundle "$1/src/tui" "$1/src/tui/dist" "$tui_entry" "${DEEPSCIENTIST_FORCE_TUI_BUILD:-}"; then
+    print_step "Using up-to-date TUI bundle from source tree"
+    return
+  fi
   print_step "Building TUI in install tree"
   npm --prefix "$1/src/tui" install --include=dev --no-audit --no-fund
   npm --prefix "$1/src/tui" run build
   npm --prefix "$1/src/tui" prune --omit=dev --no-audit --no-fund
 }
 
+truthy_env() {
+  case "$(printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]')" in
+    1|true|yes|on)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+should_use_prebuilt_bundle() {
+  local source_root="$1"
+  local dist_root="$2"
+  local dist_entry="$3"
+  local force_value="${4:-}"
+
+  if truthy_env "$force_value"; then
+    return 1
+  fi
+
+  if [ ! -e "$dist_root/$dist_entry" ]; then
+    return 1
+  fi
+
+  local freshness_output=""
+  if command -v python3 >/dev/null 2>&1; then
+    freshness_output="$(python3 - "$source_root" "$dist_root" <<'PY'
+from pathlib import Path
+import sys
+
+source_root = Path(sys.argv[1])
+dist_root = Path(sys.argv[2])
+ignore_names = {"dist", "node_modules", ".git", "__pycache__"}
+
+if not source_root.exists() or not dist_root.exists():
+    print("stale")
+    raise SystemExit(0)
+
+def iter_files(root: Path):
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if any(part in ignore_names for part in path.relative_to(root).parts):
+            continue
+        yield path
+
+source_mtime = 0.0
+for path in iter_files(source_root):
+    source_mtime = max(source_mtime, path.stat().st_mtime)
+
+dist_mtime = 0.0
+for path in dist_root.rglob("*"):
+    if not path.is_file():
+        continue
+    dist_mtime = max(dist_mtime, path.stat().st_mtime)
+
+print("fresh" if dist_mtime >= source_mtime else "stale")
+PY
+)"
+  elif command -v python >/dev/null 2>&1; then
+    freshness_output="$(python - "$source_root" "$dist_root" <<'PY'
+from pathlib import Path
+import sys
+
+source_root = Path(sys.argv[1])
+dist_root = Path(sys.argv[2])
+ignore_names = {"dist", "node_modules", ".git", "__pycache__"}
+
+if not source_root.exists() or not dist_root.exists():
+    print("stale")
+    raise SystemExit(0)
+
+def iter_files(root: Path):
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if any(part in ignore_names for part in path.relative_to(root).parts):
+            continue
+        yield path
+
+source_mtime = 0.0
+for path in iter_files(source_root):
+    source_mtime = max(source_mtime, path.stat().st_mtime)
+
+dist_mtime = 0.0
+for path in dist_root.rglob("*"):
+    if not path.is_file():
+        continue
+    dist_mtime = max(dist_mtime, path.stat().st_mtime)
+
+print("fresh" if dist_mtime >= source_mtime else "stale")
+PY
+)"
+  else
+    return 1
+  fi
+
+  [ "$freshness_output" = "fresh" ]
+}
+
 write_install_wrappers() {
   local target="$1"
   mkdir -p "$target/bin"
@@ -288,6 +401,10 @@ write_install_wrappers() {
 #!/usr/bin/env bash
 set -euo pipefail
 SCRIPT_DIR="\$(cd "\$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+HOME_DIR="\$(cd "\$SCRIPT_DIR/../.." && pwd)"
+if [ -z "\${DEEPSCIENTIST_HOME:-}" ]; then
+  export DEEPSCIENTIST_HOME="\$HOME_DIR"
+fi
 NODE_BIN="\${DEEPSCIENTIST_NODE:-node}"
 exec "\$NODE_BIN" "\$SCRIPT_DIR/ds.js" "\$@"
 EOF
@@ -304,6 +421,9 @@ write_global_wrapper() {
   cat >"$target_path" <<EOF
 #!/usr/bin/env bash
 set -euo pipefail
+if [ -z "\${DEEPSCIENTIST_HOME:-}" ]; then
+  export DEEPSCIENTIST_HOME="$BASE_DIR"
+fi
 exec "$INSTALL_DIR/bin/$command_name" "\$@"
 EOF
   chmod +x "$target_path"
@@ -311,10 +431,6 @@ EOF
 
 require_command node
 require_command npm
-if ! command -v python3 >/dev/null 2>&1 && ! command -v python >/dev/null 2>&1; then
-  echo "Python 3 is required to run DeepScientist." >&2
-  exit 1
-fi
 
 SOURCE_ROOT_RESOLVED="$(resolve_path "$SOURCE_ROOT")"
 INSTALL_DIR_RESOLVED="$(resolve_path "$INSTALL_DIR")"
@@ -356,6 +472,7 @@ printf 'Run: %s\n' "$BIN_DIR/ds"
 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 [ "$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.1",
+  "version": "1.5.3",
   "description": "Local-first research operating system with a Python runtime and npm launcher",
   "license": "MIT",
   "files": [
@@ -9,6 +9,7 @@
     "docs/en/",
     "docs/zh/",
     "install.sh",
+    "uv.lock",
     "assets/branding/",
     "assets/connectors/",
     "bin/",

package/pyproject.toml

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

package/src/deepscientist/__init__.py

@@ -1,3 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version as _package_version
+
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
+try:
+    __version__ = _package_version("deepscientist")
+except PackageNotFoundError:  # pragma: no cover - source checkout fallback
+    __version__ = "1.5.3"