@researai/deepscientist 1.5.0 → 1.5.2

package/AGENTS.md

@@ -28,9 +28,12 @@ The target is a focused core runtime, not a large platform.
 Start with the files that actually exist in this checkout:
 
 - `README.md`
+- `docs/en/ARCHITECTURE.md`
+- `docs/en/DEVELOPMENT.md`
 - `docs/en/TUI_USAGE.md`
 - `docs/en/SETTINGS_REFERENCE.md`
 - `src/deepscientist/`
+- `src/deepscientist/runtime_tools/`
 - `src/prompts/`
 - `src/skills/`
 - `src/ui/src/`
@@ -81,6 +84,7 @@ Prefer small registries for:
 - channels
 - connector bridges
 - skill discovery
+- managed local runtime tools
 - optional plugin adapters
 
 Prefer `register_*()`, `get_*()`, and `list_*()` APIs over large dispatch branches.
@@ -119,6 +123,7 @@ Important runtime entry points:
 - API handlers: `src/deepscientist/daemon/api/handlers.py`
 - prompt builder: `src/deepscientist/prompts/builder.py`
 - system prompt: `src/prompts/system.md`
+- managed local tools: `src/deepscientist/runtime_tools/`
 
 ## Runtime Layout
 
@@ -185,6 +190,9 @@ If you add or rename a stage skill:
 
 - Keep public docs clear and task-oriented.
 - Prefer English and Chinese user docs under `docs/en/` and `docs/zh/`.
+- Maintainer-facing source-of-truth docs live in:
+  - `docs/en/ARCHITECTURE.md`
+  - `docs/en/DEVELOPMENT.md`
 - Keep docs names stable when they are linked from the UI.
 - If a document is implementation planning rather than user guidance, keep it out of `docs/`.
 
@@ -218,6 +226,13 @@ If you add or rename a stage skill:
 - User-facing delivery belongs in channels.
 - Provider adaptation belongs in bridges.
 
+### Managed local runtime tools
+
+- Keep optional local tool installs behind `src/deepscientist/runtime_tools/`.
+- Register new tools through the runtime tool registry instead of scattering ad hoc install logic.
+- Reuse `RuntimeToolService` for status, install, and binary resolution.
+- Document user-visible install or troubleshooting changes in docs.
+
 ### UI and TUI
 
 - Preserve the shared contract between the two clients.
@@ -259,6 +274,17 @@ When changing connectors:
 - update `src/deepscientist/bridges/`
 - update connector tests
 
+When changing managed local tools:
+
+- update `src/deepscientist/runtime_tools/`
+- update the concrete tool adapter such as `src/deepscientist/tinytex.py` if needed
+- update any callers in CLI, doctor, or runtime services
+- update maintainer docs:
+  - `docs/en/ARCHITECTURE.md`
+  - `docs/en/DEVELOPMENT.md`
+- update user docs if install or troubleshooting changes are user-visible
+- update or add tests for registration, status, install, and binary resolution
+
 When changing API surface used by web and TUI:
 
 - update `src/deepscientist/daemon/api/router.py`

package/README.md

@@ -6,210 +6,96 @@
 
 <p align="center">
   Local-first research operating system with a Python runtime, an npm launcher,
-  one-quest-one-repository state, and shared web plus TUI control surfaces.
+  one quest per Git repository, and shared web plus TUI surfaces.
 </p>
 
-<p align="center">
-  <a href="docs/en/TUI_USAGE.md">English Docs</a>
-  ·
-  <a href="docs/zh/TUI_USAGE.md">中文文档</a>
-  ·
-  <a href="CONTRIBUTING.md">Contributing</a>
-</p>
-
-## What DeepScientist is
-
-DeepScientist is designed for long-running research quests that need durable state,
-repeatable artifacts, Git-backed history, and a local copilot workspace.
-
-Core product shape:
+## Install
 
-- one quest = one Git repository
-- Python is the authoritative runtime
-- npm is the normal install and launch path
-- both web UI and TUI talk to the same daemon API
-- only three built-in MCP namespaces are public:
-  - `memory`
-  - `artifact`
-  - `bash_exec`
-- prompts plus skills define most workflow behavior
-
-## Installation
-
-### Published npm package
-
-The public npm package should be installed with the lowercase scoped name:
+Install DeepScientist:
 
 ```bash
 npm install -g @researai/deepscientist
 ```
 
-Then start DeepScientist:
-
-```bash
-ds --web
-```
-
-Useful launcher commands:
-
-```bash
-ds --web
-ds --tui
-ds --both
-ds --stop
-ds --restart
-```
-
-Notes:
-
-- the daemon binds `0.0.0.0:20999` by default
-- the browser is opened through `http://127.0.0.1:20999`
-- the first startup bootstraps `~/DeepScientist/runtime/venv`
-- the launcher also verifies that the `codex` runtime is available before starting
-
-### From a source checkout
-
-For local development from this repository:
+## Start
 
 ```bash
-bash install.sh
 ds
 ```
 
-## Requirements
-
-- Node.js `>=18.18`
-- npm `>=9`
-- Python `>=3.11`
-- Git on `PATH`
-- access to the `codex` CLI used by the runtime
+DeepScientist starts the local web workspace at `http://127.0.0.1:20999` by default.
 
-Optional:
+On first start, `ds` will:
 
-- a local LaTeX toolchain is only needed when you want to compile paper PDFs locally
+- bootstrap a local `uv` runtime manager automatically if your machine does not already have one
+- use the bundled Codex CLI that ships with the npm package
+- still require you to complete Codex login once if your account is not ready yet
 
-## Quick Start
-
-1. Install the package or run `bash install.sh` from source.
-2. Start the web UI with `ds --web` or both surfaces with `ds --both`.
-3. Open the local workspace at `http://127.0.0.1:20999`.
-4. Create a quest from the home page or from the CLI:
+If you want another port:
 
 ```bash
-ds new "reproduce the baseline and test one stronger idea"
+ds --port 21000
 ```
 
-5. Stop the local runtime when needed:
+If you want to bind on all interfaces:
 
 ```bash
-ds --stop
-```
-
-## Runtime Layout
-
-Default runtime data lives under:
-
-```text
-~/DeepScientist/
-  config/
-  memory/
-  plugins/
-  quests/
-  logs/
-  cache/
-  runtime/
+ds --host 0.0.0.0 --port 21000
 ```
 
-Every quest is stored under `~/DeepScientist/quests/<quest_id>/` and remains a standalone Git repository.
-
-## Documentation
-
-### English
-
-- [TUI Usage](docs/en/TUI_USAGE.md)
-- [Settings Reference](docs/en/SETTINGS_REFERENCE.md)
-- [Runtime Flow and Canvas](docs/en/RUNTIME_FLOW_AND_CANVAS.md)
-- [Start Research Contract Reference](docs/en/START_RESEARCH_CONTRACT_REFERENCE.md)
-- [QQ Connector Guide](docs/en/QQ_CONNECTOR_GUIDE.md)
-- [MCP Semantics and Memory Protocol](docs/en/MCP_MEMORY_PROTOCOL.md)
-- [Figure Style Guide](docs/en/FIGURE_STYLE_GUIDE.md)
-- [Acknowledgements](docs/en/ACKNOWLEDGEMENTS.md)
-
-### Chinese
-
-- [TUI 使用说明](docs/zh/TUI_USAGE.md)
-- [设置页参考](docs/zh/SETTINGS_REFERENCE.md)
-- [运行流与 Canvas](docs/zh/RUNTIME_FLOW_AND_CANVAS.md)
-- [Start Research 合同参考](docs/zh/START_RESEARCH_CONTRACT_REFERENCE.md)
-- [QQ Connector 指南](docs/zh/QQ_CONNECTOR_GUIDE.md)
-- [MCP 与 Memory 协议](docs/zh/MCP_MEMORY_PROTOCOL.md)
-- [图表风格指南](docs/zh/FIGURE_STYLE_GUIDE.md)
-- [致谢](docs/zh/ACKNOWLEDGEMENTS.md)
+DeepScientist now uses `uv` to manage a locked local Python runtime. If a conda environment is active and already provides Python `>=3.11`, `ds` prefers it automatically; otherwise it bootstraps a managed `uv` + Python toolchain under `~/DeepScientist/runtime/`.
 
-## Repository Layout
+The default DeepScientist home is:
 
-Main code and assets live here:
+- macOS / Linux: `~/DeepScientist`
+- Windows: `%USERPROFILE%\\DeepScientist`
 
-- `bin/`
-- `assets/`
-- `docs/`
-- `src/deepscientist/`
-- `src/prompts/`
-- `src/skills/`
-- `src/ui/`
-- `src/tui/`
-- `tests/`
+Use `ds --home <path>` if you want to place the runtime somewhere else.
 
-Important entry points:
-
-- launcher: `bin/ds.js`
-- Python CLI: `src/deepscientist/cli.py`
-- daemon: `src/deepscientist/daemon/app.py`
-- MCP server: `src/deepscientist/mcp/server.py`
-- prompt builder: `src/deepscientist/prompts/builder.py`
-- system prompt: `src/prompts/system.md`
-
-## Development
-
-Install UI dependencies and build the web bundle:
+## Troubleshooting
 
 ```bash
-npm --prefix src/ui install
-npm --prefix src/ui run build
+ds doctor
 ```
 
-Build the TUI bundle:
+`ds docker` is also accepted as a compatibility alias, but `ds doctor` is the documented command.
+
+## Local PDF Compile
 
 ```bash
-npm --prefix src/tui install
-npm --prefix src/tui run build
+ds latex install-runtime
 ```
 
-Run tests:
+This installs a lightweight TinyTeX `pdflatex` runtime for local paper compilation.
 
-```bash
-pytest
-```
+## QQ Connector
 
-Verify npm packaging before publishing:
+- [Quick Start (English)](docs/en/00_QUICK_START.md)
+- [快速开始（中文）](docs/zh/00_QUICK_START.md)
+- [QQ Connector Guide (English)](docs/en/03_QQ_CONNECTOR_GUIDE.md)
+- [QQ Connector Guide (中文)](docs/zh/03_QQ_CONNECTOR_GUIDE.md)
 
-```bash
-npm pack --dry-run
-```
+## Maintainers
 
-## Open-Source Hygiene
+- [Architecture](docs/en/90_ARCHITECTURE.md)
+- [Development Guide](docs/en/91_DEVELOPMENT.md)
 
-This repository should not commit local machine artifacts such as:
+## Citation
 
-- `node_modules/`
-- `dist/` build output
-- `__pycache__/`
-- `.pytest_cache/`
-- `.turbo/`
-- local absolute workstation paths in docs or repo guidance
+This project is currently contributed by Yixuan Weng, Shichen Li, Weixu Zhao, Minjun Zhu. If you find our work valuable, please cite:
 
-User-facing documentation belongs in `docs/en/` and `docs/zh/`.
-Internal planning notes and temporary implementation checklists should not be kept there.
+本项目当前由 Yixuan Weng、Shichen Li、Weixu Zhao、Minjun Zhu 共同贡献。如果你觉得我们的工作有价值，请引用：
+
+```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}
+}
+```
 
 ## License
 

package/assets/connectors/lingzhu/openclaw-bridge/README.md

@@ -0,0 +1,124 @@
+# OpenClaw Lingzhu
+
+面向 Rokid/乐奇眼镜场景的 `Lingzhu <-> OpenClaw` 桥接插件。
+
+本目录已随 DeepScientist 一起打包，可直接从当前仓库安装。
+
+## 安装
+
+```bash
+# 在 DeepScientist 仓库根目录下安装
+openclaw plugins install ./assets/connectors/lingzhu/openclaw-bridge
+
+# 或以开发模式链接安装
+openclaw plugins install --link ./assets/connectors/lingzhu/openclaw-bridge
+```
+
+## 配置
+
+在 `openclaw.json` 或 `moltbot.json` 中加入：
+
+```json5
+{
+  "gateway": {
+    "http": {
+      "endpoints": {
+        "chatCompletions": {
+          "enabled": true
+        }
+      }
+    }
+  },
+  "plugins": {
+    "entries": {
+      "lingzhu": {
+        "enabled": true,
+        "config": {
+          "authAk": "",
+          "agentId": "main",
+          "includeMetadata": true,
+          "requestTimeoutMs": 60000,
+          "sessionMode": "per_user",
+          "sessionNamespace": "lingzhu",
+          "defaultNavigationMode": "0",
+          "enableFollowUp": true,
+          "followUpMaxCount": 3,
+          "maxImageBytes": 5242880,
+          "systemPrompt": "你是部署在 Rokid 眼镜上的智能助手。",
+          "autoReceiptAck": true,
+          "visibleProgressHeartbeat": true,
+          "visibleProgressHeartbeatSec": 10,
+          "debugLogging": true,
+          "debugLogPayloads": false,
+          "debugLogDir": "",
+          "enableExperimentalNativeActions": true
+        }
+      }
+    }
+  }
+}
+```
+
+## CLI
+
+```bash
+openclaw lingzhu info
+openclaw lingzhu status
+openclaw lingzhu curl
+openclaw lingzhu capabilities
+openclaw lingzhu logpath
+openclaw lingzhu doctor
+openclaw lingzhu cache-cleanup
+```
+
+## 健康检查
+
+```bash
+curl http://127.0.0.1:18789/metis/agent/api/health
+```
+
+## 调试日志
+
+启用 `debugLogging` 后，桥接日志默认写入插件目录下的 `logs/`：
+
+- `logs/lingzhu-YYYY-MM-DD.log`
+
+联调时建议先这样配置：
+
+- `debugLogging: true`
+- `debugLogPayloads: false`
+
+只有在需要精确排查协议载荷时，再临时改为：
+
+- `debugLogPayloads: true`
+
+## 长时间兼容策略
+
+这份 bridge 默认采用更稳妥的 Lingzhu 兼容策略：
+
+- `autoReceiptAck: true`
+  - 请求进入后立即发一条可见回执，避免眼镜端等待模型首 token 时像“没收到”
+- `visibleProgressHeartbeat: true`
+  - 长时间无正文输出时，补发轻量可见进度帧，而不仅仅是 SSE 注释心跳
+- `visibleProgressHeartbeatSec: 10`
+  - 控制可见进度帧最短间隔，避免过于频繁刷屏
+
+这会明显改善实际体验，但仍不能消除灵珠平台单次 SSE 请求的时长限制。
+
+## 实验性原生动作
+
+启用 `enableExperimentalNativeActions` 后，会额外向模型暴露这些实验动作：
+
+- `send_notification`
+- `send_toast`
+- `speak_tts`
+- `start_video_record`
+- `stop_video_record`
+- `open_custom_view`
+
+这些动作是否被灵珠平台或眼镜端真实识别，仍需真机联调验证。
+
+## 额外工具
+
+- `openclaw lingzhu doctor`: 输出当前桥接自检结果，适合部署后快速核对配置。
+- `openclaw lingzhu cache-cleanup`: 清理 24 小时前的图片缓存，避免联调过程中缓存目录持续膨胀。

package/assets/connectors/lingzhu/openclaw-bridge/index.ts

@@ -0,0 +1,162 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { lingzhuConfigSchema, resolveLingzhuConfig, generateAuthAk } from "./src/config.js";
+import { createHttpHandler } from "./src/http-handler.js";
+import { registerLingzhuCli } from "./src/cli.js";
+import { createLingzhuTools } from "./src/lingzhu-tools.js";
+import type { LingzhuConfig } from "./src/types.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const AK_FILE = path.join(__dirname, "../.lingzhu.ak"); // 存储在插件根目录
+
+// 插件状态
+let pluginConfig: LingzhuConfig = {};
+let activeAuthAk = "";
+let gatewayPort = 18789;
+
+function maskSecret(secret: string): string {
+  if (!secret) {
+    return "(empty)";
+  }
+
+  if (secret.length <= 8) {
+    return "*".repeat(secret.length);
+  }
+
+  return `${secret.slice(0, 4)}${"*".repeat(secret.length - 8)}${secret.slice(-4)}`;
+}
+
+/**
+ * 灵珠平台接入插件
+ */
+const lingzhuPlugin = {
+  id: "lingzhu",
+  name: "Lingzhu Bridge",
+  description: "灵珠平台 <-> OpenClaw 协议转换桥梁",
+  configSchema: lingzhuConfigSchema,
+
+  register(api: any) {
+    const logger = api.logger;
+
+    // 获取并解析配置
+    const rawConfig = api.config?.plugins?.entries?.lingzhu?.config;
+    pluginConfig = resolveLingzhuConfig(rawConfig);
+    // 生成或使用已有 AK
+    if (pluginConfig.authAk) {
+      activeAuthAk = pluginConfig.authAk;
+    } else {
+      // 尝试从本地文件读取
+      if (fs.existsSync(AK_FILE)) {
+        try {
+          activeAuthAk = fs.readFileSync(AK_FILE, "utf-8").trim();
+          logger.info("[Lingzhu] 已从本地记录加载 AK");
+        } catch (e) {
+          logger.warn(`[Lingzhu] 读取本地 AK 文件失败: ${e}`);
+        }
+      }
+
+      // 如果还是没有，则生成并保存
+      if (!activeAuthAk) {
+        activeAuthAk = generateAuthAk();
+        try {
+          fs.writeFileSync(AK_FILE, activeAuthAk, "utf-8");
+          logger.info("[Lingzhu] 已自动生成并持久化 AK");
+        } catch (e) {
+          logger.warn(`[Lingzhu] 持久化 AK 文件失败: ${e}`);
+        }
+      }
+    }
+
+    // 获取 Gateway 端口
+    gatewayPort = api.config?.gateway?.port ?? 18789;
+
+    // 配置/状态获取函数
+    const getConfig = () => pluginConfig;
+    const getRuntimeState = () => ({
+      config: pluginConfig,
+      authAk: activeAuthAk,
+      gatewayPort,
+      chatCompletionsEnabled: api.config?.gateway?.http?.endpoints?.chatCompletions?.enabled === true,
+    });
+
+    // 1. 注册 HTTP 路由
+    if (typeof api.registerHttpRoute === "function") {
+      const httpHandler = createHttpHandler(api, getRuntimeState);
+      api.registerHttpRoute({
+        path: "/metis/agent/api/sse",
+        handler: httpHandler,
+        auth: "plugin" as const,
+        match: "exact" as const,
+      });
+      api.registerHttpRoute({
+        path: "/metis/agent/api/health",
+        handler: httpHandler,
+        auth: "plugin" as const,
+        match: "exact" as const,
+      });
+      logger.info("[Lingzhu] 已注册 HTTP 路由: /metis/agent/api/sse, /metis/agent/api/health");
+    } else if (typeof api.registerHttpHandler === "function") {
+      api.registerHttpHandler(createHttpHandler(api, getRuntimeState));
+      logger.info("[Lingzhu] 已注册 HTTP 端点: POST /metis/agent/api/sse");
+    }
+
+    // 2. 注册灵珠设备工具
+    logger.info(`[Lingzhu] 检查 registerTool API: ${typeof api.registerTool}`);
+    if (pluginConfig.enabled === false) {
+      logger.info("[Lingzhu] 插件已禁用，跳过设备工具注册");
+    } else if (typeof api.registerTool === "function") {
+      const tools = createLingzhuTools(pluginConfig.enableExperimentalNativeActions === true);
+      logger.info(`[Lingzhu] 准备注册 ${tools.length} 个工具`);
+      for (const tool of tools) {
+        try {
+          api.registerTool(tool, { optional: false });
+          logger.info(`[Lingzhu] 已注册工具: ${tool.name}`);
+        } catch (e) {
+          logger.error(`[Lingzhu] 注册工具失败: ${tool.name}, 错误: ${e}`);
+        }
+      }
+    } else {
+      logger.warn("[Lingzhu] registerTool API 不可用，无法注册设备工具");
+    }
+
+    // 3. 注册 CLI 命令
+    if (typeof api.registerCli === "function") {
+      api.registerCli(
+        (ctx: any) => registerLingzhuCli(ctx, getRuntimeState),
+        { commands: ["lingzhu"] }
+      );
+    }
+
+    // 4. 注册后台服务
+    if (typeof api.registerService === "function") {
+      api.registerService({
+        id: "lingzhu-bridge",
+        start: () => {
+          if (pluginConfig.enabled === false) {
+            logger.info("[Lingzhu] 插件已禁用");
+            return;
+          }
+
+          const url = `http://127.0.0.1:${gatewayPort}/metis/agent/api/sse`;
+
+          console.log("");
+          console.log("╔═══════════════════════════════════════════════════════════════════════╗");
+          console.log("║                    Lingzhu Bridge 已启动                              ║");
+          console.log("╠═══════════════════════════════════════════════════════════════════════╣");
+          console.log(`║  SSE 接口:  ${url.padEnd(56)}║`);
+          console.log(`║  鉴权 AK:   ${maskSecret(activeAuthAk).padEnd(56)}║`);
+          console.log("╚═══════════════════════════════════════════════════════════════════════╝");
+          console.log("");
+
+          logger.info(`[Lingzhu] Bridge 已启动，端点: ${url}`);
+        },
+        stop: () => {
+          logger.info("[Lingzhu] Bridge 已停止");
+        },
+      });
+    }
+  },
+};
+
+export default lingzhuPlugin;