@researai/deepscientist 1.5.14 → 1.5.15

package/docs/zh/16_TELEGRAM_CONNECTOR_GUIDE.md

@@ -0,0 +1,134 @@
+# 16 Telegram Connector 指南
+
+当你希望通过 Telegram 继续推进 DeepScientist quest 时，请阅读这份指南。
+
+当前开源版本中的 Telegram 连接方式使用内置 polling 路径：
+
+- 不需要公网 webhook
+- 核心凭据是 BotFather token
+- 如果启用自动绑定，私聊可以自动跟随最新活跃 quest
+
+## 1. Telegram 支持包含什么
+
+当前 Telegram connector 由以下部分组成：
+
+- `TelegramPollingService`：负责入站轮询
+- `GenericRelayChannel`：负责绑定、inbox/outbox、target 与运行时状态
+- `TelegramConnectorBridge`：负责通过 Bot API 直接出站发送
+
+这意味着 Telegram 已经接入了和其他 connector 一致的 quest 绑定模型。
+
+## 2. 推荐配置路径
+
+1. 打开 BotFather。
+2. 执行 `/newbot`。
+3. 保存生成的 bot token。
+4. 打开 `Settings > Connectors > Telegram`。
+5. 启用 Telegram。
+6. 保持 `transport: polling`。
+7. 填写 `bot_token`。
+8. 保存连接器配置。
+9. 从 Telegram 给 bot 发送一条真实私聊，例如 `/start` 或 `/help`。
+10. 回到 DeepScientist，确认运行时已经发现这个 target conversation。
+
+## 3. 关键配置字段
+
+主要字段包括：
+
+- `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`
+
+完整字段说明请参考 [01 设置参考](./01_SETTINGS_REFERENCE.md)。
+
+## 4. 绑定模型
+
+Telegram 会话会被规范化成 quest-aware connector id，例如：
+
+- `telegram:direct:<chat_id>`
+- `telegram:group:<chat_id>`
+
+DeepScientist 绑定的是这个规范化后的 conversation id，而不是临时 webhook 状态。
+
+重要规则：
+
+- 一个 quest 会保留本地访问，并且最多只绑定 1 个外部 connector target
+- 如果启用了自动绑定，Telegram 私聊可以自动跟随最新活跃 quest
+- 之后也可以在项目设置页修改绑定
+
+## 5. 群聊行为
+
+默认情况下：
+
+- Telegram 私聊允许直接触发
+- 群聊行为由 `group_policy` 控制
+- 如果 `require_mention_in_groups` 为 `true`，机器人只有在被明确 mention，或收到命令时才会响应
+
+这也是更适合多人群聊的推荐默认值。
+
+## 6. 出站投递
+
+当前 Telegram connector 主要聚焦于 text-first 的 quest 更新：
+
+- 进度
+- 里程碑摘要
+- 绑定通知
+- 结构化 quest 回复
+
+当前 bridge 使用 Telegram Bot API 的 `sendMessage` 发送。
+
+## 7. 常见问题排查
+
+### 设置页里看不到 Telegram
+
+Telegram 可能被 system connector gate 隐藏了。请确认：
+
+- `config.connectors.system_enabled.telegram` 为 `true`
+
+### 校验提示缺少凭据
+
+请检查：
+
+- `bot_token` 是否已填写
+- 或 `bot_token_env` 是否指向真实存在的环境变量
+
+### 机器人收不到消息
+
+请检查：
+
+- bot token 是否正确
+- 是否至少从 Telegram 端先和 bot 交互过一次
+- `transport` 是否仍然是 `polling`
+- 是否存在旧的 webhook 抢占了更新流
+
+### 群聊里 bot 不响应
+
+请检查：
+
+- `group_policy`
+- `groups`
+- `group_allow_from`
+- `require_mention_in_groups`
+
+### Telegram 里无法继续已有 quest
+
+请检查：
+
+- 当前会话是否已经绑定到目标 quest
+- 或 `auto_bind_dm_to_active_quest` 是否已经启用
+
+## 8. 相关文档
+
+- [01 设置参考](./01_SETTINGS_REFERENCE.md)
+- [02 Start Research 参考](./02_START_RESEARCH_GUIDE.md)
+- [09 启动诊断](./09_DOCTOR.md)
+- [13 核心架构说明](./13_CORE_ARCHITECTURE_GUIDE.md)

package/docs/zh/17_WHATSAPP_CONNECTOR_GUIDE.md

@@ -0,0 +1,126 @@
+# 17 WhatsApp Connector 指南
+
+当你希望通过 WhatsApp 继续推进 DeepScientist quest 时，请阅读这份指南。
+
+当前开源版本里的 WhatsApp 推荐路径使用本地 local-session 方案：
+
+- 不需要公网 webhook
+- 本地认证 / 会话状态保存在你自己的机器上
+- 如果启用自动绑定，私聊可以自动跟随最新活跃 quest
+
+## 1. WhatsApp 支持包含什么
+
+当前 WhatsApp connector 由以下部分组成：
+
+- `WhatsAppLocalSessionService`：负责本地会话同步与入站接入
+- `GenericRelayChannel`：负责 bindings、inbox/outbox、targets 与运行时状态
+- `WhatsAppConnectorBridge`：负责出站投递
+
+在推荐路径下，出站消息会先写入 local-session outbox，再由本地 session / sidecar 处理。
+
+## 2. 推荐配置路径
+
+1. 打开 `Settings > Connectors > WhatsApp`。
+2. 启用 WhatsApp。
+3. 保持 `transport: local_session`。
+4. 保持默认或指定一个可写的 `session_dir`。
+5. 保存连接器配置。
+6. 完成本地 WhatsApp 会话登录流程。
+7. 从 WhatsApp 发送一条真实消息。
+8. 回到 DeepScientist，确认目标会话已经被自动发现。
+
+## 3. 关键配置字段
+
+主要字段包括：
+
+- `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`
+
+完整字段说明请参考 [01 设置参考](./01_SETTINGS_REFERENCE.md)。
+
+## 4. 绑定模型
+
+WhatsApp 会话会被规范化成 quest-aware connector id，例如：
+
+- `whatsapp:direct:<jid>`
+- `whatsapp:group:<jid>`
+
+DeepScientist 绑定的是这个规范化后的 conversation id，而不是临时浏览器状态或短期 session 状态。
+
+重要规则：
+
+- 一个 quest 会保留本地访问，并且最多只绑定 1 个外部 connector target
+- 如果启用了自动绑定，WhatsApp 私聊可以自动跟随最新活跃 quest
+- 之后也可以在项目设置页修改绑定
+
+## 5. local-session 运行方式
+
+当前开源版本里的 WhatsApp 路径是 local-session 导向的：
+
+- 运行时状态会镜像写入 DeepScientist 的 connector 日志目录
+- 入站消息会从本地 session inbox 中被消费
+- 出站消息会被写入本地 session outbox
+
+这也符合 DeepScientist 的本地优先设计。
+
+## 6. 群聊行为
+
+默认情况下：
+
+- 私聊可以和活跃 quest 自动配对
+- 群聊行为由 `group_policy` 控制
+- 也可以通过 `groups` 与 `group_allow_from` 强制使用白名单
+
+## 7. 常见问题排查
+
+### 设置页里看不到 WhatsApp
+
+WhatsApp 可能被 system connector gate 隐藏了。请确认：
+
+- `config.connectors.system_enabled.whatsapp` 为 `true`
+
+### 校验提示连接器未就绪
+
+请检查：
+
+- `transport` 是否为 `local_session`
+- `session_dir` 是否指向可写目录
+
+### 没有自动发现目标会话
+
+请检查：
+
+- 本地登录 / 配对流程是否已经完成
+- 是否至少有一条真实入站消息进入 local session inbox
+
+### 无法从 WhatsApp 继续已有 quest
+
+请检查：
+
+- 当前会话是否已经绑定到目标 quest
+- 或 `auto_bind_dm_to_active_quest` 是否已经启用
+
+### 出站消息没有送达
+
+请检查：
+
+- 本地 session sidecar / processor 是否正在运行
+- 本地 session outbox 是否正在被消费
+- 目标 JID 是否正确
+
+## 8. 相关文档
+
+- [01 设置参考](./01_SETTINGS_REFERENCE.md)
+- [02 Start Research 参考](./02_START_RESEARCH_GUIDE.md)
+- [09 启动诊断](./09_DOCTOR.md)
+- [13 核心架构说明](./13_CORE_ARCHITECTURE_GUIDE.md)

package/docs/zh/18_FEISHU_CONNECTOR_GUIDE.md

@@ -0,0 +1,136 @@
+# 18 Feishu Connector 指南
+
+当你希望通过 Feishu / Lark 继续推进 DeepScientist quest 时，请阅读这份指南。
+
+当前开源版本中的 Feishu 推荐路径使用内置 long-connection 方案：
+
+- 不需要公网 event callback
+- 核心凭据是 `app_id` 和 `app_secret`
+- 如果启用自动绑定，私聊可以自动跟随最新活跃 quest
+
+## 1. Feishu 支持包含什么
+
+当前 Feishu connector 由以下部分组成：
+
+- `FeishuLongConnectionService`：负责 long-connection 入站接收
+- `GenericRelayChannel`：负责 bindings、inbox/outbox、targets 与运行时状态
+- `FeishuConnectorBridge`：负责直接出站发送
+
+这意味着 Feishu 已经接入了和其他 connector 一致的 quest 绑定模型。
+
+## 2. 推荐配置路径
+
+1. 打开 Feishu / Lark 开发者平台。
+2. 创建应用。
+3. 保存 `app_id` 和 `app_secret`。
+4. 打开 `Settings > Connectors > Feishu`。
+5. 启用 Feishu。
+6. 保持 `transport: long_connection`。
+7. 填写 `app_id` 与 `app_secret`。
+8. 保存连接器配置。
+9. 给 bot 发送一条真实消息。
+10. 回到 DeepScientist，确认目标会话已经被自动发现。
+
+## 3. 关键配置字段
+
+主要字段包括：
+
+- `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`
+
+完整字段说明请参考 [01 设置参考](./01_SETTINGS_REFERENCE.md)。
+
+## 4. 绑定模型
+
+Feishu 会话会被规范化成 quest-aware connector id，例如：
+
+- `feishu:direct:<chat_id>`
+- `feishu:group:<chat_id>`
+
+DeepScientist 绑定的是这个规范化后的 conversation id，而不是临时 callback payload。
+
+重要规则：
+
+- 一个 quest 会保留本地访问，并且最多只绑定 1 个外部 connector target
+- 如果启用了自动绑定，Feishu 私聊可以自动跟随最新活跃 quest
+- 之后也可以在项目设置页修改绑定
+
+## 5. 群聊行为
+
+默认情况下：
+
+- 私聊允许直接触发
+- 群聊行为由 `group_policy` 控制
+- 如果 `require_mention_in_groups` 为 `true`，机器人只有在被明确 mention，或收到命令时才会响应
+
+这也是更适合多人协作群的推荐默认值。
+
+## 6. 出站投递
+
+当前 Feishu connector 主要聚焦于 text-first 的 quest 更新：
+
+- 进度
+- 里程碑摘要
+- 绑定通知
+- 结构化 quest 回复
+
+当前 bridge 使用 Feishu Open Platform 的消息接口发送。
+
+## 7. 常见问题排查
+
+### 设置页里看不到 Feishu
+
+Feishu 可能被 system connector gate 隐藏了。请确认：
+
+- `config.connectors.system_enabled.feishu` 为 `true`
+
+### 校验提示缺少凭据
+
+请检查：
+
+- `app_id` 是否已填写
+- `app_secret` 是否已填写
+- 或 `app_secret_env` 是否指向真实存在的环境变量
+
+### 没有自动发现目标会话
+
+请检查：
+
+- 应用凭据是否正确
+- bot 是否已经收到至少一条真实入站消息
+- `transport` 是否仍然是 `long_connection`
+
+### 群聊里 bot 不响应
+
+请检查：
+
+- `group_policy`
+- `groups`
+- `group_allow_from`
+- `require_mention_in_groups`
+
+### 无法从 Feishu 继续已有 quest
+
+请检查：
+
+- 当前会话是否已经绑定到目标 quest
+- 或 `auto_bind_dm_to_active_quest` 是否已经启用
+
+## 8. 相关文档
+
+- [01 设置参考](./01_SETTINGS_REFERENCE.md)
+- [02 Start Research 参考](./02_START_RESEARCH_GUIDE.md)
+- [09 启动诊断](./09_DOCTOR.md)
+- [13 核心架构说明](./13_CORE_ARCHITECTURE_GUIDE.md)

package/docs/zh/README.md

@@ -96,6 +96,12 @@ DeepScientist 灵活且易于使用，支持：
 
 ## 如果你想通过外部协作面继续推进
 
+- [16 Telegram Connector 指南](./16_TELEGRAM_CONNECTOR_GUIDE.md)
+  通过内置 polling 运行时绑定 Telegram，并从 bot 会话继续推进 quest。
+- [17 WhatsApp Connector 指南](./17_WHATSAPP_CONNECTOR_GUIDE.md)
+  通过本地 local-session 运行时绑定 WhatsApp，并从本地聊天会话继续推进 quest。
+- [18 Feishu Connector 指南](./18_FEISHU_CONNECTOR_GUIDE.md)
+  通过内置 long-connection 运行时绑定 Feishu，并从 bot 会话继续推进 quest。
 - [10 微信连接器指南](./10_WEIXIN_CONNECTOR_GUIDE.md)
   适合通过 DeepScientist 内置扫码流程，把个人微信直接绑定进来。
 - [03 QQ 连接器指南](./03_QQ_CONNECTOR_GUIDE.md)

package/install.sh

@@ -230,6 +230,7 @@ copy_source_tree() {
     tar -C "$SOURCE_ROOT" -cf - \
       --exclude='./.git' \
       --exclude='./.pytest_cache' \
+      --exclude='./build' \
       --exclude='./node_modules' \
       --exclude='./ui' \
       --exclude='./src/ui/node_modules' \
@@ -247,6 +248,7 @@ prune_tree() {
   rm -rf \
     "$target/.git" \
     "$target/.pytest_cache" \
+    "$target/build" \
     "$target/node_modules" \
     "$target/ui" \
     "$target/src/ui/node_modules" \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@researai/deepscientist",
-  "version": "1.5.14",
+  "version": "1.5.15",
   "description": "DeepScientist is not just a fully open-source autonomous scientific discovery system. It is also a research map that keeps growing from every round.",
   "license": "Apache-2.0",
   "files": [

package/pyproject.toml

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

package/src/deepscientist/__init__.py

@@ -5,4 +5,4 @@ __all__ = ["__version__"]
 try:
     __version__ = _package_version("deepscientist")
 except PackageNotFoundError:  # pragma: no cover - source checkout fallback
-    __version__ = "1.5.14"
+    __version__ = "1.5.15"