@researai/deepscientist 1.5.13 → 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

@@ -30,6 +30,8 @@ This page is the shortest path to the right document.
 
 - [00 Quick Start](./00_QUICK_START.md)
   Start here if you want to install DeepScientist, launch it locally, and create your first project.
+- [05 TUI Guide](./05_TUI_GUIDE.md)
+  Read this if your main surface is the terminal and you want one end-to-end path through `ds --tui`, quests, connectors, and cross-surface work.
 - [15 Codex Provider Setup](./15_CODEX_PROVIDER_SETUP.md)
   Read this when you want to run DeepScientist through MiniMax, GLM, Volcengine Ark, Alibaba Bailian, or another Codex profile.
 - [12 Guided Workflow Tour](./12_GUIDED_WORKFLOW_TOUR.md)
@@ -48,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 报错提示速查
 
 | 提示 | 代表什么 | 应该怎么做 |