@researai/deepscientist 1.5.14 → 1.5.15

package/docs/en/16_TELEGRAM_CONNECTOR_GUIDE.md

@@ -0,0 +1,134 @@
+# 16 Telegram Connector Guide
+
+Use this guide when you want DeepScientist to continue a quest through Telegram.
+
+Telegram in the current open-source runtime uses the built-in polling path:
+
+- no public webhook is required
+- the main credential is the BotFather token
+- direct messages can auto-bind to the latest active quest when enabled
+
+## 1. What Telegram support includes
+
+DeepScientist currently supports Telegram through:
+
+- `TelegramPollingService` for inbound polling
+- `GenericRelayChannel` for bindings, inbox/outbox, targets, and runtime status
+- `TelegramConnectorBridge` for direct outbound sends through the Bot API
+
+This means Telegram already fits the same quest-binding model as the other connector surfaces.
+
+## 2. Recommended setup path
+
+1. Open BotFather.
+2. Run `/newbot`.
+3. Save the generated bot token.
+4. Open `Settings > Connectors > Telegram`.
+5. Enable Telegram.
+6. Keep `transport: polling`.
+7. Fill `bot_token`.
+8. Save the connector.
+9. Send one real private message such as `/start` or `/help` to the bot.
+10. Return to DeepScientist and verify that the runtime has discovered the target conversation.
+
+## 3. Important config fields
+
+Main fields:
+
+- `enabled`
+- `transport`
+- `bot_name`
+- `bot_token`
+- `command_prefix`
+- `require_mention_in_groups`
+- `dm_policy`
+- `allow_from`
+- `group_policy`
+- `group_allow_from`
+- `groups`
+- `auto_bind_dm_to_active_quest`
+
+For the full field reference, see [01 Settings Reference](./01_SETTINGS_REFERENCE.md).
+
+## 4. Binding model
+
+Telegram conversations are normalized into quest-aware connector ids like:
+
+- `telegram:direct:<chat_id>`
+- `telegram:group:<chat_id>`
+
+DeepScientist binds quests to those normalized conversation ids, not to transient webhook state.
+
+Important rules:
+
+- one quest keeps local access plus at most one external connector target
+- direct messages can auto-follow the latest active quest when auto-bind is enabled
+- bindings can be changed later from the project settings page
+
+## 5. Group chat behavior
+
+By default:
+
+- Telegram direct messages are allowed
+- group behavior depends on `group_policy`
+- if `require_mention_in_groups` is `true`, the bot only reacts when explicitly mentioned or when a command is used
+
+This is the recommended default for larger shared groups.
+
+## 6. Outbound delivery
+
+Telegram outbound delivery currently focuses on text-first quest updates:
+
+- progress
+- milestone summaries
+- binding notices
+- structured quest replies
+
+The current bridge uses `sendMessage` through the Bot API.
+
+## 7. Troubleshooting
+
+### Telegram does not appear in Settings
+
+Telegram may be hidden by the system connector gate. Confirm that:
+
+- `config.connectors.system_enabled.telegram` is `true`
+
+### Validation says credentials are missing
+
+Check that:
+
+- `bot_token` is filled
+- or `bot_token_env` points at a real environment variable
+
+### The bot receives no messages
+
+Check that:
+
+- the bot token is correct
+- the bot was started from Telegram at least once
+- `transport` is still `polling`
+- no stale public webhook is intercepting updates
+
+### Group messages do not trigger the bot
+
+Check:
+
+- `group_policy`
+- `groups`
+- `group_allow_from`
+- `require_mention_in_groups`
+
+### The quest does not continue from Telegram
+
+Check that:
+
+- the conversation is bound to the intended quest
+- or `auto_bind_dm_to_active_quest` is enabled for direct-message pairing
+
+## 8. Related docs
+
+- [01 Settings Reference](./01_SETTINGS_REFERENCE.md)
+- [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md)
+- [09 Doctor](./09_DOCTOR.md)
+- [13 Core Architecture Guide](./13_CORE_ARCHITECTURE_GUIDE.md)

package/docs/en/17_WHATSAPP_CONNECTOR_GUIDE.md

@@ -0,0 +1,126 @@
+# 17 WhatsApp Connector Guide
+
+Use this guide when you want DeepScientist to continue a quest through WhatsApp.
+
+The current open-source runtime prefers the local-session path for WhatsApp:
+
+- no public webhook is required for the recommended path
+- the local auth/session state stays on your machine
+- direct messages can auto-bind to the latest active quest when enabled
+
+## 1. What WhatsApp support includes
+
+DeepScientist currently supports WhatsApp through:
+
+- `WhatsAppLocalSessionService` for local session sync and inbound ingestion
+- `GenericRelayChannel` for bindings, inbox/outbox, targets, and runtime status
+- `WhatsAppConnectorBridge` for outbound delivery
+
+For the recommended path, outbound delivery is queued into the local-session outbox and handled by the local sidecar/session runtime.
+
+## 2. Recommended setup path
+
+1. Open `Settings > Connectors > WhatsApp`.
+2. Enable WhatsApp.
+3. Keep `transport: local_session`.
+4. Keep or choose a writable `session_dir`.
+5. Save the connector.
+6. Complete the local login flow for the WhatsApp session.
+7. Send one real message from WhatsApp.
+8. Return to DeepScientist and verify that the target conversation has been discovered.
+
+## 3. Important config fields
+
+Main fields:
+
+- `enabled`
+- `transport`
+- `bot_name`
+- `auth_method`
+- `session_dir`
+- `command_prefix`
+- `dm_policy`
+- `allow_from`
+- `group_policy`
+- `group_allow_from`
+- `groups`
+- `auto_bind_dm_to_active_quest`
+
+For the full field reference, see [01 Settings Reference](./01_SETTINGS_REFERENCE.md).
+
+## 4. Binding model
+
+WhatsApp conversations are normalized into quest-aware connector ids like:
+
+- `whatsapp:direct:<jid>`
+- `whatsapp:group:<jid>`
+
+DeepScientist binds quests to those normalized conversation ids instead of transient browser/session state.
+
+Important rules:
+
+- one quest keeps local access plus at most one external connector target
+- direct messages can auto-follow the latest active quest when auto-bind is enabled
+- bindings can be changed later from the project settings page
+
+## 5. Local-session runtime behavior
+
+The current open-source path is local-session oriented:
+
+- runtime status is mirrored into DeepScientist under connector logs
+- inbound messages are drained from the local session inbox
+- outbound messages are queued into the local session outbox
+
+This keeps the recommended WhatsApp path local-first.
+
+## 6. Group behavior
+
+By default:
+
+- direct messages can pair with the active quest
+- group behavior depends on `group_policy`
+- group allowlists can be enforced through `groups` and `group_allow_from`
+
+## 7. Troubleshooting
+
+### WhatsApp does not appear in Settings
+
+WhatsApp may be hidden by the system connector gate. Confirm that:
+
+- `config.connectors.system_enabled.whatsapp` is `true`
+
+### Validation says the connector is not ready
+
+Check that:
+
+- `transport` is `local_session`
+- `session_dir` points to a writable path
+
+### No discovered targets appear
+
+Check that:
+
+- the local login/session flow has completed
+- at least one real inbound message has reached the local session inbox
+
+### The quest does not continue from WhatsApp
+
+Check that:
+
+- the conversation is bound to the intended quest
+- or `auto_bind_dm_to_active_quest` is enabled for direct-message pairing
+
+### Outbound messages do not arrive
+
+Check that:
+
+- the local-session sidecar or local session processor is running
+- the local session outbox is being drained
+- the target JID is correct
+
+## 8. Related docs
+
+- [01 Settings Reference](./01_SETTINGS_REFERENCE.md)
+- [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md)
+- [09 Doctor](./09_DOCTOR.md)
+- [13 Core Architecture Guide](./13_CORE_ARCHITECTURE_GUIDE.md)

package/docs/en/18_FEISHU_CONNECTOR_GUIDE.md

@@ -0,0 +1,136 @@
+# 18 Feishu Connector Guide
+
+Use this guide when you want DeepScientist to continue a quest through Feishu / Lark.
+
+The current open-source runtime prefers the built-in long-connection path:
+
+- no public event callback is required for the recommended setup
+- the main credentials are `app_id` and `app_secret`
+- direct messages can auto-bind to the latest active quest when enabled
+
+## 1. What Feishu support includes
+
+DeepScientist currently supports Feishu through:
+
+- `FeishuLongConnectionService` for inbound long-connection delivery
+- `GenericRelayChannel` for bindings, inbox/outbox, targets, and runtime status
+- `FeishuConnectorBridge` for direct outbound sends
+
+This means Feishu already fits the same quest-binding model as the other connector surfaces.
+
+## 2. Recommended setup path
+
+1. Open the Feishu / Lark developer platform.
+2. Create an app.
+3. Save `app_id` and `app_secret`.
+4. Open `Settings > Connectors > Feishu`.
+5. Enable Feishu.
+6. Keep `transport: long_connection`.
+7. Fill `app_id` and `app_secret`.
+8. Save the connector.
+9. Send one real message to the bot.
+10. Return to DeepScientist and confirm that the target conversation has been discovered.
+
+## 3. Important config fields
+
+Main fields:
+
+- `enabled`
+- `transport`
+- `bot_name`
+- `app_id`
+- `app_secret`
+- `api_base_url`
+- `command_prefix`
+- `dm_policy`
+- `allow_from`
+- `group_policy`
+- `group_allow_from`
+- `groups`
+- `require_mention_in_groups`
+- `auto_bind_dm_to_active_quest`
+
+For the full field reference, see [01 Settings Reference](./01_SETTINGS_REFERENCE.md).
+
+## 4. Binding model
+
+Feishu conversations are normalized into quest-aware connector ids like:
+
+- `feishu:direct:<chat_id>`
+- `feishu:group:<chat_id>`
+
+DeepScientist binds quests to those normalized conversation ids, not to transient callback payloads.
+
+Important rules:
+
+- one quest keeps local access plus at most one external connector target
+- direct messages can auto-follow the latest active quest when auto-bind is enabled
+- bindings can be changed later from the project settings page
+
+## 5. Group behavior
+
+By default:
+
+- direct messages are allowed
+- group behavior depends on `group_policy`
+- if `require_mention_in_groups` is `true`, the bot only reacts when explicitly mentioned or when a command is used
+
+This is the recommended default for larger shared workspaces.
+
+## 6. Outbound delivery
+
+Feishu outbound delivery currently focuses on text-first quest updates:
+
+- progress
+- milestone summaries
+- binding notices
+- structured quest replies
+
+The current bridge delivers through the Feishu Open Platform messaging API.
+
+## 7. Troubleshooting
+
+### Feishu does not appear in Settings
+
+Feishu may be hidden by the system connector gate. Confirm that:
+
+- `config.connectors.system_enabled.feishu` is `true`
+
+### Validation says credentials are missing
+
+Check that:
+
+- `app_id` is filled
+- `app_secret` is filled
+- or `app_secret_env` points at a real environment variable
+
+### No discovered targets appear
+
+Check that:
+
+- the app credentials are correct
+- the bot has received at least one real inbound message
+- `transport` is still `long_connection`
+
+### Group messages do not trigger the bot
+
+Check:
+
+- `group_policy`
+- `groups`
+- `group_allow_from`
+- `require_mention_in_groups`
+
+### The quest does not continue from Feishu
+
+Check that:
+
+- the conversation is bound to the intended quest
+- or `auto_bind_dm_to_active_quest` is enabled for direct-message pairing
+
+## 8. Related docs
+
+- [01 Settings Reference](./01_SETTINGS_REFERENCE.md)
+- [02 Start Research Guide](./02_START_RESEARCH_GUIDE.md)
+- [09 Doctor](./09_DOCTOR.md)
+- [13 Core Architecture Guide](./13_CORE_ARCHITECTURE_GUIDE.md)

package/docs/en/README.md

@@ -50,6 +50,12 @@ This page is the shortest path to the right document.
 
 ## If you want to collaborate through external surfaces
 
+- [16 Telegram Connector Guide](./16_TELEGRAM_CONNECTOR_GUIDE.md)
+  Bind Telegram through the built-in polling runtime and continue quests from bot chats.
+- [17 WhatsApp Connector Guide](./17_WHATSAPP_CONNECTOR_GUIDE.md)
+  Bind WhatsApp through the local-session runtime and continue quests from local chat sessions.
+- [18 Feishu Connector Guide](./18_FEISHU_CONNECTOR_GUIDE.md)
+  Bind Feishu through the built-in long-connection runtime and continue quests from bot chats.
 - [10 Weixin Connector Guide](./10_WEIXIN_CONNECTOR_GUIDE.md)
   Bind personal WeChat through DeepScientist's built-in QR login and iLink runtime.
 - [03 QQ Connector Guide](./03_QQ_CONNECTOR_GUIDE.md)

package/docs/zh/00_QUICK_START.md

@@ -13,7 +13,7 @@
 
 本文中的截图直接使用当前在线页面 `deepscientist.cc:20999` 作为示例。你本地运行后的页面 `127.0.0.1:20999` 通常会与它保持一致或非常接近。
 
-当前平台支持：DeepScientist 目前仅支持 Linux 和 macOS，当前版本暂不支持 Windows。
+当前平台支持：DeepScientist 目前完整支持 Linux 和 macOS。原生 Windows 支持目前仍处于实验阶段；如果你希望获得最接近 Linux 的终端行为，仍然建议优先使用 WSL2。
 
 ## 安全建议：先隔离，再启动
 
@@ -60,7 +60,7 @@
 
 ## 1. 先安装 Node.js，再安装 DeepScientist
 
-DeepScientist 目前仅支持 Linux 和 macOS。
+DeepScientist 目前完整支持 Linux 和 macOS。原生 Windows 支持目前仍处于实验阶段；如果你希望获得更接近 Linux 的 shell 行为，仍然建议优先使用 WSL2。
 
 在安装 DeepScientist 本身之前，请先从 Node.js 官方页面安装 Node.js：
 

package/docs/zh/01_SETTINGS_REFERENCE.md

@@ -409,8 +409,8 @@ codex:
   profile: ""
   model: gpt-5.4
   model_reasoning_effort: xhigh
-  approval_policy: on-request
-  sandbox_mode: workspace-write
+  approval_policy: never
+  sandbox_mode: danger-full-access
   retry_on_failure: true
   retry_max_attempts: 5
   retry_initial_backoff_sec: 1.0
@@ -488,19 +488,35 @@ claude:
 **`approval_policy`**
 
 - 类型：`string`
-- 默认值：`on-request`
+- 默认值：`never`
 - 页面标签：`Approval policy`
 - 允许值：`never`、`on-failure`、`on-request`、`untrusted`
 - 作用：控制高权限动作如何申请许可。
+- 运行说明：launcher 现在默认以 YOLO 模式启动 Codex。若要临时关闭，可显式传 `ds --yolo false`，这会恢复到 `approval_policy=on-request` 与 `sandbox_mode=workspace-write`。
 
 **`sandbox_mode`**
 
 - 类型：`string`
-- 默认值：`workspace-write`
+- 默认值：`danger-full-access`
 - 页面标签：`Sandbox mode`
 - 允许值：`read-only`、`workspace-write`、`danger-full-access`
 - 作用：控制 runner 的文件系统/进程访问权限。
 
+**`env`**
+
+- 类型：`mapping<string, string>`
+- 默认值：`{}`
+- 页面入口：
+  - 全局设置：可在 `runners` 结构化表单中直接编辑 `env`
+  - 项目设置：`Project settings -> Codex environment`
+- 项目设置行为：
+  - 点击 `Add` 新增一行环境变量
+  - 默认会显示 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY`
+  - 修改后不会自动保存，需要手动点击 `Save env vars`
+  - 空值会被忽略，不会注入到 Codex 进程
+- 作用：DeepScientist 启动 Codex run 时，额外传入给 Codex 的环境变量。
+- 常见用途：需要 API Key 或自定义 Base URL 的 provider-backed Codex 配置。
+
 **`retry_on_failure`**
 
 - 类型：`boolean`

package/docs/zh/03_QQ_CONNECTOR_GUIDE.md

@@ -20,6 +20,7 @@
 - 在 QQ 中使用 `/new`、`/use latest`、`/status` 等命令
 - 在 `Settings` 页面看到自动检测到的 `openid`
 - 从 `Settings` 页面执行非破坏性的连接测试
+- 当 QQ 绑定到 quest 时，在每次主实验完成后自动收到按指标生成的时间线图片
 
 ### 部署前检查清单
 
@@ -221,6 +222,24 @@ QQ readiness is healthy, but no OpenID has been learned yet. Save credentials, t
 - 再次点击“发送测试消息”时，不再提示 target 为空
 - 如果当前已经有最新项目，普通文本会自动进入该项目；如果还没有项目，则优先返回帮助信息
 
+## 5.3 主实验指标图自动推送
+
+当 QQ 是当前 quest 的绑定连接器时，DeepScientist 现在会在每次主实验完成后自动发送指标时间线图片。
+
+当前行为：
+
+- 每个指标生成一张图
+- 如果 baseline 存在该指标，会画一条横向虚线作为 baseline 参考线
+- 系统会自动判断该指标是“越高越好”还是“越低越好”
+- 超过 baseline 的点会额外标星
+- 最新点使用莫兰迪深红色填充
+- 较早的点使用莫兰迪深蓝色填充
+- 如果指标有多个，DeepScientist 会按顺序发送，并在相邻两张图之间间隔约 2 秒
+
+这些图来自 quest 本地生成的文件，并会作为 QQ 原生图片自动发送。
+
+如果你想关闭这项自动推送，可以在 QQ 连接器配置中关闭 `auto_send_main_experiment_png`。
+
 ### 5.2 报错提示速查
 
 | 提示 | 代表什么 | 应该怎么做 |

package/docs/zh/10_WEIXIN_CONNECTOR_GUIDE.md

@@ -27,6 +27,7 @@ DeepScientist 已经内置了微信 iLink 运行时，因此你不需要再额
 - 把入站附件复制到当前 quest 的 `userfiles/weixin/...`
 - 把文本回复发回同一个微信上下文
 - 在 agent 提供真实本地文件时，发送微信原生图片、视频、文件
+- 当微信绑定到 quest 时，在每次主实验完成后自动发送按指标生成的时间线图片
 
 入站媒体不会只留在临时缓存里，而是会被复制进 quest。本地落盘路径形态如下：
 
@@ -94,7 +95,10 @@ DeepScientist 已经内置了微信 iLink 运行时，因此你不需要再额
 - 入站图片、视频、文件会被下载并复制进 quest 本地 `userfiles/weixin/...`
 - 纯媒体消息不会再被直接丢弃
 - 出站文本会沿用运行时维护的 `context_token`
+- 如果微信 `context_token` 缺失或过期，低优先级出站更新会先进入排队，而不是直接丢失
+- 下一次新的微信入站刷新会话后，DeepScientist 只会回放最近 `5` 条排队更新，并且每条之间固定间隔 `2` 秒
 - 出站图片、视频、文件在 agent 提供真实本地文件路径时可以正常发送
+- 出站主实验指标图会自动作为微信原生图片发送
 
 ![Quest 本地多媒体流转](../images/weixin/weixin-quest-media-flow.svg)
 
@@ -116,6 +120,22 @@ userfiles/...
 
 而不是默认依赖一个任意的外链。
 
+## 5.1 主实验指标图自动推送
+
+当微信是当前 quest 的绑定连接器时，DeepScientist 现在会在每次主实验完成后自动发送指标时间线图片。
+
+当前行为：
+
+- 每个指标生成一张图
+- 如果 baseline 存在该指标，会画一条横向虚线作为 baseline 参考线
+- 系统会自动判断该指标是“越高越好”还是“越低越好”
+- 超过 baseline 的点会额外标星
+- 最新点使用莫兰迪深红色填充
+- 较早的点使用莫兰迪深蓝色填充
+- 如果指标有多个，DeepScientist 会按顺序发送，并在相邻两张图之间间隔约 2 秒
+
+这些图来自 quest 本地生成的文件，并会作为微信原生图片自动发送到当前绑定会话。
+
 ## 6. 常见问题
 
 ### 二维码一直在等待

package/docs/zh/14_PROMPT_SKILLS_AND_MCP_GUIDE.md

@@ -100,6 +100,7 @@ DeepScientist 不是靠一份静态大 prompt 工作的。
 - 不要过早结束 quest
 - Web、TUI、connector 属于同一个 quest
 - 用户可见的汇报风格
+- baseline 提交与确认的纪律：如果源 baseline 暴露了多指标或多 variant，就要保留完整比较面，而不是只留下一个 headline scalar
 
 如果你发现 agent 在所有场景里行为都不对，`system.md` 一定是首要检查点之一。
 
@@ -113,6 +114,7 @@ DeepScientist 不是靠一份静态大 prompt 工作的。
 - 排队中的用户消息必须优先确认和处理
 - `blocking` 只该用于真实用户决策
 - 进展汇报应该简洁且可读
+- 真正发给用户的交互消息应保持完整；系统会单独生成短预览，所以 agent 不应该自己把 connector 回复截成 `...` / `…`
 
 如果模型经常在长任务里“断线”或者不会接住用户后续消息，这个文件非常关键。