@researai/deepscientist 1.5.9 → 1.5.11

package/docs/zh/02_START_RESEARCH_GUIDE.md

@@ -16,6 +16,92 @@
 3. 绑定一个可选的可复用 baseline
 4. 持久化 `startup_contract`，供后续 prompt builder 持续读取
 
+## 实战示例：整理后的 quest 025 启动输入
+
+理解这个弹窗最快的方法，不是先背字段定义，而是先看一个真实例子。
+
+下面这个例子来自 quest `025` 的真实启动输入，但我做了必要的整理，让它更适合公开文档和第一次填写时参考。这个任务的目标是：
+
+- 复现官方的 Mandela-Effect baseline
+- 保持原论文任务与评测协议
+- 研究在混合正确 / 错误社会信号下，如何实现更强的 truth-preserving collaboration
+- 使用两个本地 OpenAI-compatible 端点提高吞吐量
+
+### 当前前端里先填的短字段
+
+| 弹窗字段 | 示例值 | 为什么这样填 |
+|---|---|---|
+| `Project title` | `Mandela-Effect Reproduction and Truth-Preserving Collaboration` | 标题清楚，后面在卡片、工作区和搜索里都好认 |
+| `Project ID` | 留空，或者填 `025` | 想自动编号就留空；只有你明确要固定编号时才手动填写 |
+| `Connector delivery` | 第一次建议 `Local only`，如果 QQ 已配置也可以选一个目标 | 当前前端对每个 quest 最多只允许绑定一个外部 connector 目标 |
+| `Reusable baseline` | 第一次可留空；如果官方 baseline 已经导入 registry，就直接选它 | 一旦选中，自动推导的 `baseline_mode` 会变成 `existing` |
+| `Research paper` | `On` | 让项目保持分析和论文式产出在范围内 |
+| `Research intensity` | `Balanced` | 先把 baseline 立稳，再探索一个合理方向 |
+| `Decision mode` | `Autonomous` | 普通路线选择默认自己推进，不把常规决策丢回给用户 |
+| `Launch mode` | `Standard` | 按默认科研主线启动 |
+| `Language` | `English` | 默认用英文组织 kickoff prompt 和用户侧产物 |
+
+### 同一个例子里的长文本字段
+
+`Primary research request`
+
+```text
+Please reproduce the official Mandela-Effect repository and paper, then study how to improve truth-preserving collaboration under mixed correct and incorrect social signals.
+
+The core research question is: how can a multi-agent system remain factually robust under social influence while still learning from correct peers?
+
+Keep the task definition and evaluation protocol aligned with the original work. Focus on prompt-based or system-level methods that improve truth preservation without simply refusing all social information.
+```
+
+`Baseline links`
+
+```text
+https://github.com/bluedream02/Mandela-Effect
+```
+
+`Reference papers / repos`
+
+```text
+https://arxiv.org/abs/2602.00428
+```
+
+`Runtime constraints`
+
+```text
+- Keep the task definition and evaluation protocol aligned with the official baseline unless a change is explicitly justified.
+- Use two OpenAI-compatible local inference endpoints for throughput:
+  - `http://127.0.0.1:8004/v1`
+  - `http://127.0.0.1:8008/v1`
+- Use API key `1234` and model `/model/gpt-oss-120b` on both endpoints.
+- Keep generation settings close to the baseline unless a justified adjustment is required.
+- Implement asynchronous execution, automatic retry on request failure, and resumable scripts.
+- Split requests across both endpoints so throughput stays high without overloading the service.
+- Record failed, degraded, or inconclusive runs honestly instead of hiding them.
+```
+
+`Goals`
+
+```text
+1. Restore and verify the official Mandela-Effect baseline as a trustworthy starting point.
+2. Measure key metrics and failure modes on the designated `gpt-oss-120b` setup.
+3. Propose at least one literature-grounded direction for stronger truth-preserving collaboration.
+4. Produce experiment and analysis artifacts that are strong enough to support paper writing.
+```
+
+### 这个例子在前端里会自动推导出什么
+
+如果 `Reusable baseline` 留空，且 `Research intensity` 选择 `Balanced`，当前前端会自动推导：
+
+- `scope = baseline_plus_direction`
+- `baseline_mode = restore_from_url`
+- `resource_policy = balanced`
+- `time_budget_hours = 24`
+- `git_strategy = semantic_head_plus_controlled_integration`
+
+如果你已经选中了一个可复用 baseline，那么只会有一项不同：
+
+- `baseline_mode = existing`
+
 ## 当前前端数据模型
 
 ### `StartResearchTemplate`
@@ -83,6 +169,12 @@ type StartResearchContractFields = {
   title,
   goal: compiled_prompt,
   quest_id,
+  requested_connector_bindings: [
+    {
+      connector,
+      conversation_id
+    }
+  ],
   requested_baseline_ref: {
     baseline_id,
     variant_id
@@ -138,6 +230,26 @@ type StartResearchContractFields = {
 
 - 声明后续 kickoff 和交流默认偏好的语言。
 
+### Connector 投递
+
+**`requested_connector_bindings`**
+
+- 这是创建项目时随请求一起提交的字段，但不在 `startup_contract` 里面。
+- 当前前端对每个 quest 最多只允许一个外部 connector 目标。
+- 典型结构如下：
+
+```ts
+[
+  {
+    connector: 'qq',
+    conversation_id: 'qq:private:openid-123'
+  }
+]
+```
+
+- 如果你保持项目仅本地运行，这个数组就是空的。
+- 如果你选中的那个目标已经绑定在别的 quest 上，当前项目创建时会把旧绑定替换掉。
+
 ### Baseline 与参考资料
 
 **`baseline_id`**

package/docs/zh/04_LINGZHU_CONNECTOR_GUIDE.md

@@ -1,230 +1,99 @@
-# 04 Lingzhu 连接器指南：如何配置 Lingzhu
+# 04 Lingzhu 连接器指南：把 Rokid Glasses 绑定到 DeepScientist
 
-本文说明如何在 `Settings > Connectors > Lingzhu` 中完成 Lingzhu 伴生端点配置。
+Lingzhu 现在是一个极简的一步式绑定流程。
 
-适用范围：
+DeepScientist 会直接在自己的 daemon / Web 端口上提供 Lingzhu 兼容路由：
 
-- 仅包含配置教程
-- 面向 OpenClaw 兼容的 Lingzhu bridge 参数
-- 本地健康检查与 SSE 冒烟测试
-- 说明需要把哪些值填回 Lingzhu 平台
+- `GET /metis/agent/api/health`
+- `POST /metis/agent/api/sse`
 
-本文不展开讨论云部署架构。你只需要：
+真实设备要想接入，Rokid 平台里填写的地址必须就是外部可以访问到的 DeepScientist 公网地址，不能是 `127.0.0.1`、`localhost` 或私网地址。
 
-- 一个已经跑起来的 OpenClaw gateway
-- 一个眼镜端可访问的公网 IP 或公网域名
+参考：
 
-参考来源：
+- Rokid 开发者论坛：https://forum.rokid.com/post/detail/2831
+- Rokid 智能体平台：https://agent-develop.rokid.com/space
 
-- Rokid 论坛配置页面：https://forum.rokid.com/post/detail/2831
-- 仓库内置 bridge 目录：`assets/connectors/lingzhu/openclaw-bridge`
-- 仓库内置 OpenClaw 配置模板：`assets/connectors/lingzhu/openclaw.lingzhu.config.template.json`
+## 1. 绑定前提
 
-## 1. DeepScientist 现在会自动提供什么
+先确认：
 
-Lingzhu 设置卡会自动生成并校验：
+- DeepScientist 已正常启动
+- 你当前打开的 DeepScientist 网页地址就是最终对外可访问的公网地址
+- 如果当前网页地址是本地地址或私网地址，Lingzhu 不应直接保存
 
-- 本地 health URL
-- 本地 SSE URL
-- 公网 SSE URL
-- `auth_ak`
-- OpenClaw 配置片段
-- 本地探测 `curl`
+## 2. 页面里现在保留什么
 
-当前随包 bridge 还额外做了三件事：
+`Settings > Connectors > Lingzhu` 现在只保留必要内容：
 
-- 在模型真正开始生成前，先自动发送一条可见的“已收到”回执
-- 保留 SSE 注释心跳
-- 在上游长时间静默时补发轻量可见进度心跳
+- 一个 `Add Lingzhu (Rokid Glasses)` 入口
+- Rokid 平台创建表单截图
+- 自动生成的可复制字段
+- 中文绑定指引
+- 保存按钮
 
-需要明确的是：
+不再要求你先手动改 host、port、agent、OpenClaw 配置片段或额外调试步骤。
 
-- Lingzhu 在 DeepScientist 里被视为 companion endpoint
-- 它不是像 QQ 那样的完整双向聊天 connector
+## 3. 点击后会自动生成什么
 
-## 2. 开始前请先确认
+点击 `Add Lingzhu (Rokid Glasses)` 后，弹窗会自动显示这些值，并且每一项都可以直接复制：
 
-建议先确认下面几项：
+- 自定义智能体ID
+- 自定义智能体url
+- 自定义智能体AK
+- 智能体名称
+- 类别
+- 功能介绍
+- 开场白
+- 入参类型
+- 图标 PNG 地址
 
-- DeepScientist 已成功安装并运行
-- 本地 OpenClaw gateway 已启动
-- 你知道 OpenClaw HTTP gateway 的端口，通常是 `18789`
-- 你已经有公网 IP 或公网域名
+其中：
 
-重要提醒：
+- `Custom agent URL` 会自动生成成 `https://<你的公网地址>/metis/agent/api/sse`
+- `AK` 会自动随机生成，并在保存后长期复用，不会每次都变
+- logo 使用 DeepScientist 的 PNG 资源，方便直接上传到 Rokid
 
-- `127.0.0.1` 只能用于本地健康检查
-- Lingzhu 设备侧必须访问公网地址
+![Rokid 平台创建三方智能体](../images/lingzhu/rokid-agent-platform-create.png)
 
-## 3. 打开设置页
+## 4. 用户怎么做
 
-打开：
+在 Rokid 平台：
 
-- `Settings > Connectors > Lingzhu`
+1. 打开 `项目开发 -> 三方智能体 -> 创建`
+2. 选择“自定义智能体”
+3. 把弹窗里自动生成的字段逐项复制过去
+4. 图标上传 DeepScientist PNG logo
+5. Rokid 表单填写完成后，回到 DeepScientist 点击保存
 
-页面会分成几块：
+保存完成后，Lingzhu 绑定就算完成。
 
-- 网关端点
-- 鉴权与身份
-- 自动生成值
-- 探测与校验
-- 高级调试
+## 5. 后续怎么用
 
-![Lingzhu 设置概览](../images/lingzhu/lingzhu-settings-overview.svg)
+眼镜侧后续只需要请求：
 
-## 4. 先填写端点
+- `POST /metis/agent/api/sse`
 
-推荐值如下：
+并带上：
 
-| 字段 | 推荐值 | 说明 |
-| --- | --- | --- |
-| `Enabled` | `true` | 开启 companion 配置 |
-| `Transport` | `openclaw_sse` | 固定值，不要改 |
-| `Local host` | `127.0.0.1` | 只用于本地探测 |
-| `Gateway port` | `18789` | 与 OpenClaw gateway 保持一致 |
-| `Public base URL` | `http://<公网IP>:18789` | 必须是眼镜端真正能访问到的地址 |
+- `Authorization: Bearer <保存后的AK>`
 
-如果你不确定本地端点应该怎么填，可以直接点击：
+使用规则：
 
-- `Use local defaults`
+- 新任务必须以 `我现在的任务是 ...` 开头
+- 只有这个前缀后面的正文才会被当成新的 DeepScientist 任务
+- 如果只是想继续拿中间进展，不要重复这个前缀，直接说 `找DeepScientist` 或 `继续`
 
-## 5. 生成 AK 和身份值
+## 6. 常见问题
 
-建议如下：
+### 为什么不能用 `127.0.0.1`
 
-| 字段 | 推荐值 |
-| --- | --- |
-| `Auth AK` | 点击 `Generate AK` 自动生成 |
-| `Agent ID` | `main` |
-| `Lingzhu system prompt` | 可选 |
+因为 Rokid 平台和外部设备访问不到你的本地回环地址。Lingzhu 只应该注册公网地址。
 
-需要保证下面两处完全一致：
+### 为什么要自动生成 `AK`
 
-- OpenClaw Lingzhu 插件配置
-- Lingzhu 平台配置
+因为 `AK` 本质上就是这个外部接入口的 Bearer 密钥。系统生成并持久化，比手填更稳定，也更不容易出错。
 
-也就是：
+### 保存后还需要再手动配很多参数吗
 
-- `auth_ak`
-- `agent_id`
-
-## 6. 使用自动生成值
-
-DeepScientist 会直接展示你需要复制的内容：
-
-- 本地 health URL
-- 本地 SSE URL
-- 公网 SSE URL
-- OpenClaw 配置片段
-- 探测 curl
-
-其中真正要填回 Lingzhu 平台的是：
-
-- 公网 SSE URL
-- AK
-
-![Lingzhu 平台填写值](../images/lingzhu/lingzhu-platform-values.svg)
-
-## 7. 更新 OpenClaw
-
-你可以直接使用：
-
-- 设置页里自动生成的配置片段
-- 或仓库内置模板 `assets/connectors/lingzhu/openclaw.lingzhu.config.template.json`
-
-内置 bridge 的安装命令为：
-
-```bash
-openclaw plugins install ./assets/connectors/lingzhu/openclaw-bridge
-```
-
-至少应确保 OpenClaw 开启：
-
-```json
-{
-  "gateway": {
-    "port": 18789,
-    "http": {
-      "endpoints": {
-        "chatCompletions": {
-          "enabled": true
-        }
-      }
-    }
-  }
-}
-```
-
-DeepScientist 也会自动把完整的 Lingzhu 插件配置片段生成出来：
-
-![OpenClaw 配置片段](../images/lingzhu/lingzhu-openclaw-config.svg)
-
-## 8. 执行本地探测
-
-保存参数后，点击：
-
-- `Run Lingzhu probe`
-
-DeepScientist 会依次执行：
-
-1. `GET /metis/agent/api/health`
-2. `POST /metis/agent/api/sse`
-
-理想结果：
-
-- `Connection = reachable`
-- `Auth = ready`
-- 探测结果没有报错
-
-## 9. 需要填回 Lingzhu 平台的值
-
-只需要填：
-
-- `Public SSE URL`
-- `Auth AK`
-
-不要填：
-
-- `127.0.0.1`
-- 任意本地机器名
-
-## 10. 常见失败原因
-
-### Health 显示 offline
-
-通常说明：
-
-- OpenClaw 没启动
-- `gateway_port` 填错
-- `local_host` 填错
-
-### SSE probe 失败
-
-通常说明：
-
-- `auth_ak` 不一致
-- Lingzhu SSE 路径没有暴露出来
-- OpenClaw 的 `chatCompletions.enabled` 还没打开
-
-### 本地探测通过，但设备仍无法接入
-
-通常说明：
-
-- `Public base URL` 不是公网可达地址
-- 防火墙或反向代理还没有放行端口
-
-## 11. 说明
-
-这块配置保持 registry-first：
-
-- Lingzhu 仍然落在 `connectors.yaml`
-- 自动生成值来自同一份 structured config
-- 校验、测试、前端渲染都消费同一条 connector 记录
-
-对于长任务，更稳妥的实际策略是：
-
-- 先由 bridge 自动回执
-- 在上游静默阶段由 bridge 补发可见进度心跳
-- 通过 `per_user` 会话连续保持多轮上下文
-
-这会明显改善兼容性，但仍不能消除 Lingzhu 平台单次请求超时的硬限制。
+不需要。Lingzhu 现在的目标就是让用户只看到必要字段，复制过去，然后保存完成。

package/docs/zh/09_DOCTOR.md

@@ -10,21 +10,35 @@
    npm install -g @researai/deepscientist
    ```
 
-2. 先直接尝试启动：
+2. 先确保 Codex 已安装并完成认证：
+
+   ```bash
+   codex --login
+   ```
+
+   如果 `codex` 缺失，请显式修复：
+
+   ```bash
+   npm install -g @openai/codex
+   ```
+
+   如果你的 Codex CLI 版本没有 `--login`，就运行 `codex` 并在交互式界面里完成认证。
+
+3. 先直接尝试启动：
 
    ```bash
    ds
    ```
 
-3. 如果启动失败，或者看起来不正常，再运行：
+4. 如果启动失败，或者看起来不正常，再运行：
 
    ```bash
    ds doctor
    ```
 
-4. 从上到下阅读诊断结果，优先修复失败项。
+5. 从上到下阅读诊断结果，优先修复失败项。
 
-5. 修完后重新运行 `ds doctor`，直到检查通过，再运行 `ds`。
+6. 修完后重新运行 `ds doctor`，直到检查通过，再运行 `ds`。
 
 ## `ds doctor` 会检查什么
 
@@ -49,16 +63,38 @@
 npm install -g @researai/deepscientist
 ```
 
+如果装完以后 `codex` 仍然不可用，请显式安装：
+
+```bash
+npm install -g @openai/codex
+```
+
 ### 已安装 Codex，但还没有登录
 
 运行：
 
 ```bash
-codex
+codex --login
 ```
 
+如果你的 Codex CLI 版本没有 `--login`，就运行 `codex` 并在交互式界面里完成认证。
+
 先完成一次登录，再重新执行 `ds doctor`。
 
+### 当前配置的 Codex 模型不可用
+
+DeepScientist 会在启动前强制做一次真实的 Codex hello 探测。当前版本里，这个探测会先使用：
+
+```text
+~/DeepScientist/config/runners.yaml
+```
+
+里配置的 runner 模型，默认值是 `gpt-5.4`。如果你的 Codex 账号或本地 CLI 配置不能访问这个模型，DeepScientist 现在会自动重试当前 Codex 默认模型，并把后续运行持久化为 `model: inherit`。如果你仍然想指定某个具体模型，再手动改配置并重新执行：
+
+```bash
+ds doctor
+```
+
 ### 没有安装 `uv`
 
 正常情况下，第一次运行 `ds` 会自动在本地安装 `uv`。如果自动安装失败，再手动执行：

package/docs/zh/10_WEIXIN_CONNECTOR_GUIDE.md

@@ -0,0 +1,144 @@
+# 10 微信连接器指南：把个人微信绑定到 DeepScientist
+
+这篇文档只讲 DeepScientist 内置的微信连接器，不讲 OpenClaw 安装。
+
+DeepScientist 已经内置了微信 iLink 运行时，因此你不需要再额外执行：
+
+- `npx`
+- 单独安装 OpenClaw
+- 再起一个本地桥接程序
+- 配置公网 webhook
+
+真正需要的绑定动作只有这四步：
+
+1. 打开 `Settings > Connectors > WeChat`
+2. 点击 `绑定微信`
+3. 用微信扫码
+4. 在手机微信里确认登录
+
+确认完成后，DeepScientist 会自动保存微信 connector，并开始长轮询。
+
+## 1. 这个连接器现在能做什么
+
+绑定成功后，DeepScientist 现在可以：
+
+- 接收微信文本消息
+- 接收微信图片、视频、文件附件
+- 把入站附件复制到当前 quest 的 `userfiles/weixin/...`
+- 把文本回复发回同一个微信上下文
+- 在 agent 提供真实本地文件时，发送微信原生图片、视频、文件
+
+入站媒体不会只留在临时缓存里，而是会被复制进 quest。本地落盘路径形态如下：
+
+```text
+~/DeepScientist/quests/<quest_id>/userfiles/weixin/<message_batch>/
+```
+
+这意味着微信附件现在已经比较接近 QQ 的处理方式了：quest 能拿到真实、持久化的本地文件。
+
+![DeepScientist 微信绑定总览](../images/weixin/weixin-settings-bind.svg)
+
+## 2. 绑定前先确认
+
+开始前请先确认：
+
+- DeepScientist 的 daemon 和网页已经正常启动
+- 你可以打开 `Settings > Connectors > WeChat`
+- 手机上已经登录了一个真实的个人微信账号，准备用它扫码
+
+这张参考图只用于帮助你确认扫码时应使用已经登录目标微信账号的手机。真正的绑定动作仍然是在 DeepScientist 页面里弹出二维码后扫码完成，而不是去跑额外的 `npx` 工具。
+
+![微信客户端参考图](../images/weixin/weixin-plugin-entry.png)
+
+## 3. 从 Settings 页面直接绑定
+
+打开：
+
+- [Settings > Connectors > WeChat](/settings/connectors#connector-weixin)
+
+然后按顺序做：
+
+1. 点击 `绑定微信`
+2. 等待 DeepScientist 生成二维码
+3. 用微信扫码
+4. 在手机上确认登录
+
+这里有几个关键点：
+
+- 弹窗里只保留二维码这一张图，因为 DeepScientist 已经内置了完整的 iLink 登录流程
+- 绑定过程中不需要手填 `bot_token`
+- 二维码弹窗里不需要额外再点一次保存
+- 平台一旦返回 `bot_token` 和账号信息，DeepScientist 会自动持久化
+
+成功后，微信卡片里会显示：
+
+- `机器人账号`
+- `扫码账号`
+
+这两项就是当前保存下来的微信绑定信息。
+
+![二维码扫码确认流程](../images/weixin/weixin-qr-confirm.svg)
+
+## 4. 绑定后怎么验证文本和多媒体
+
+二维码登录成功后，建议按这个最短路径验证：
+
+1. 在 `Start Research` 或项目界面把 quest 绑定到微信 connector
+2. 从微信发一条文本、图片、视频或文件
+3. 等待 DeepScientist 把它接入到 quest
+4. 确认回复回到了同一条微信会话里
+
+当前行为是：
+
+- 入站文本会直接进入 quest，作为用户消息
+- 入站图片、视频、文件会被下载并复制进 quest 本地 `userfiles/weixin/...`
+- 纯媒体消息不会再被直接丢弃
+- 出站文本会沿用运行时维护的 `context_token`
+- 出站图片、视频、文件在 agent 提供真实本地文件路径时可以正常发送
+
+![Quest 本地多媒体流转](../images/weixin/weixin-quest-media-flow.svg)
+
+## 5. agent 发送微信多媒体时应怎么做
+
+对用户来说，规则其实很简单：
+
+- 只回文本时，正常回复即可
+- 要发微信原生图片、视频、文件时，agent 必须给出一个真实的 quest 本地文件
+
+所以 agent 最好优先使用这些目录中的真实文件：
+
+```text
+artifacts/...
+experiments/...
+paper/...
+userfiles/...
+```
+
+而不是默认依赖一个任意的外链。
+
+## 6. 常见问题
+
+### 二维码一直在等待
+
+优先检查：
+
+- 是否用的是你真正想绑定的那个微信账号扫码
+- 手机里是否已经完成“确认登录”
+- 等待期间 DeepScientist 是否持续在线
+
+如果二维码过期，DeepScientist 会自动刷新。
+
+### 为什么我只看到文本，没有看到入站多媒体
+
+请用真实图片、视频或文件重测一次。成功后，quest 目录里应该能看到：
+
+```text
+userfiles/weixin/<message_batch>/manifest.json
+```
+
+以及旁边被复制下来的实际媒体文件。
+
+## 7. 参考
+
+- 菜鸟教程个人微信接入说明：https://www.runoob.com/ai-agent/openclaw-weixin.html
+- 上游微信协议文档：https://github.com/hao-ji-xing/openclaw-weixin/blob/main/weixin-bot-api.md