@researai/deepscientist 1.5.14 → 1.5.16

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

@@ -56,6 +56,14 @@ DeepScientist 不是靠一份静态大 prompt 工作的。
 - `SKILL.md`：定义各个阶段的执行纪律
 - `mcp/server.py`：定义内建工具面
 
+受管 quest-local prompt 镜像：
+
+- DeepScientist 仍然会优先读取 `quest_root/.codex/prompts/` 下存在的 prompt 片段。
+- 但这棵树现在是“自动维护的受管副本”，不再默认视为永久手工 fork。
+- 每次真实 runner turn 开始前，DeepScientist 都会把当前 active quest-local prompt 树与仓库 `src/prompts/` 做比较；只要仓库源变了，或者 quest 本地副本漂移了，就会刷新 active 副本。
+- 刷新之前，旧的 active prompt 树会先备份到 `quest_root/.codex/prompt_versions/<backup_id>/`。
+- 所以默认情况下，旧 quest 也会吃到最新 prompt 合同；如果你需要回放历史 prompt，再显式选择某个备份版本。
+
 ## 3. 一轮 prompt 是怎么组装的
 
 当前运行时大致按下面顺序组装 turn prompt：
@@ -72,11 +80,12 @@ DeepScientist 不是靠一份静态大 prompt 工作的。
 10. research delivery policy
 11. paper and evidence snapshot
 12. 如果是 retry turn，则加入 retry recovery packet
-13. interaction style
-14. priority memory for this turn
-15. recent conversation window
-16. current turn attachments
-17. current user message
+13. 如果是 auto-continue turn，则加入 resume context spine
+14. interaction style
+15. priority memory for this turn
+16. recent conversation window
+17. current turn attachments
+18. current user message
 
 这个顺序不是随便排的。
 
@@ -100,6 +109,7 @@ DeepScientist 不是靠一份静态大 prompt 工作的。
 - 不要过早结束 quest
 - Web、TUI、connector 属于同一个 quest
 - 用户可见的汇报风格
+- baseline 提交与确认的纪律：如果源 baseline 暴露了多指标或多 variant，就要保留完整比较面，而不是只留下一个 headline scalar
 
 如果你发现 agent 在所有场景里行为都不对，`system.md` 一定是首要检查点之一。
 
@@ -113,6 +123,7 @@ DeepScientist 不是靠一份静态大 prompt 工作的。
 - 排队中的用户消息必须优先确认和处理
 - `blocking` 只该用于真实用户决策
 - 进展汇报应该简洁且可读
+- 真正发给用户的交互消息应保持完整；系统会单独生成短预览，所以 agent 不应该自己把 connector 回复截成 `...` / `…`
 
 如果模型经常在长任务里“断线”或者不会接住用户后续消息，这个文件非常关键。
 
@@ -208,6 +219,16 @@ builder 会直接把这些 quest 文件读进 prompt：
 - `src/deepscientist/prompts/builder.py`
 - 当前 quest 所处的 stage skill
 
+它现在还明确承载了 continuation 的模式分叉：
+
+- `workspace_mode = copilot`
+  - 以当前请求为单位提供帮助
+  - 做完这一小段之后，通常停驻，等待下一条用户消息或 `/resume`
+- `workspace_mode = autonomous`
+  - 默认继续往前推进
+  - 如果真实长任务还没跑起来，就继续用接下来的 turns 做准备、启动或耐久决策
+  - 一旦真实长任务已经在跑，后台 auto-continue 就切成低频巡检
+
 ### 4.8 Interaction style
 
 这个 block 决定这轮该怎么“说话”。
@@ -227,7 +248,27 @@ builder 会直接把这些 quest 文件读进 prompt：
 - 写作阶段
 - 等待用户决策的阶段
 
-### 4.9 Priority memory
+它现在也编码了 auto-continue 的节奏分叉：
+
+- autonomous 下，如果还在准备 / 启动真实长任务，可以较快地连续推进
+- 如果真实外部长任务已经在跑，则默认切成低频检查，默认大约每 `240` 秒一轮
+- copilot 模式则通常在当前请求单元完成后停驻，不继续自动扩展
+
+### 4.9 Resume context spine
+
+现在在 auto-continue turn 中，prompt 会额外注入一个紧凑的 resume spine，避免模型只凭一个 stage 名称硬续。
+
+里面包括：
+
+- 最近一条持久化用户消息
+- 最近一条 assistant checkpoint
+- 最近一条 run result 摘要
+- 少量最近 memory cues
+- 当前 `bash_exec` 状态，包括是否有长时间 shell 会话正在运行
+
+这也是为什么 auto-continue 能更贴着“最新用户意图 + 最新检查点”继续，而不是漂回泛泛的 stage narration。
+
+### 4.10 Priority memory
 
 DeepScientist 不是随机往 prompt 里塞 memory 的。
 
@@ -244,22 +285,33 @@ DeepScientist 不是随机往 prompt 里塞 memory 的。
 
 agent 不应该在每一轮都看到完全同一批 memory。
 
-## 5. 哪些 prompt 可以本地覆盖
+## 5. 本地 active prompt 与历史版本
 
-当前支持按 quest 在下面路径覆盖 prompt 片段：
+当前 quest 的 active prompt 树仍在这些路径下：
 
 - `.codex/prompts/system.md`
 - `.codex/prompts/contracts/shared_interaction.md`
 - `.codex/prompts/connectors/<connector>.md`
 
-也就是说：
+仓库默认 prompt 仍然在 `src/prompts/`。
+
+但现在有一个关键变化：
+
+- `.codex/prompts/` 不应再理解为长期手工维护的 override 树。
+- 每次真实运行前，DeepScientist 都会把 active quest-local copy 修回当前仓库 prompt 真相。
+- 所以如果你手工改了 active copy，这种改动会在下次运行时被视为漂移：先备份，再替换。
+- 历史 prompt 会保存在 `.codex/prompt_versions/<backup_id>/`。
+
+如果你确实想让某个 quest 临时按旧 prompt 跑，启动时优先传正式版本号即可：
+
+- `ds daemon --prompt-version <official_version>`
+- `ds run --prompt-version <official_version> ...`
 
-- 仓库默认 prompt 在 `src/prompts/`
-- quest 私有覆盖在 `.codex/prompts/`
+DeepScientist 会把它解析成“该正式版本号下最新的一份 prompt 备份”。如果你想精确回放某一次具体备份，而不是该版本下最新的一份，也仍然可以直接传备份目录名。
 
-只有当某个 quest 确实需要局部特殊合同，才建议这样覆盖。
+如果只是想继续使用当前受管 active prompt，就用 `latest`。
 
-如果这个改动应该影响整个产品，就不该做 quest-local override，而应该直接改仓库默认 prompt。
+如果这个改动应该影响正常未来行为，就不该只改 quest-local active copy，而应该直接改仓库默认 prompt。
 
 ## 6. Skills 是怎么分层的
 

package/docs/zh/15_CODEX_PROVIDER_SETUP.md

@@ -62,7 +62,7 @@ codex:
 
 - 对 provider-backed 的 Codex profile，建议优先使用 `model: inherit`
 - 除非你非常确定该 provider 接受你要显式传入的模型名，否则不要再额外硬写一个模型
-- DeepScientist 会复用你终端里同一个 `~/.codex/config.toml` 与环境变量
+- DeepScientist 现在会在 `.ds/codex-home` 下启动一个隔离的运行时 home，但会先继承你配置的 `~/.codex` 里的 auth、config、skills、agents 与 prompts
 
 ## Provider 一览
 
@@ -109,13 +109,13 @@ MiniMax 是最典型的 profile 模式。它的官方 Codex CLI 文档直接给
 
 ### 已验证的兼容性说明
 
-按 2026-03-25 对 MiniMax 官方 Codex CLI 页面和本地兼容性测试的核对结果：
+按 2026-04-04 对 MiniMax 官方 Codex CLI 页面和本地兼容性测试的核对结果：
 
 - MiniMax 官方 Codex CLI 页面当前建议使用 `@openai/codex@0.57.0`
 - MiniMax 当前应使用的 Coding Plan endpoint 是 `https://api.minimaxi.com/v1`
 - MiniMax 官方页面示例 profile 名是 `m21`，但 profile 名本身只是本地别名；本仓库统一用 `m27` 作为示例名
 - MiniMax 官方页面当前给出的 `codex-MiniMax-*` 模型名，在本地使用你提供的 key 实测并不能稳定通过 Codex CLI
-- 本地实测能稳定跑通的组合是 `MiniMax-M2.7` + `m27` + `model: inherit` + Codex CLI `0.57.0`
+- 本地实测 DeepScientist 可稳定跑通的组合包括 `MiniMax-M2.7` + `m27` + Codex CLI `0.57.0`，以及 `MiniMax-M2.5` + `m25` + Codex CLI `0.57.0`
 - 当前最新版 `@openai/codex` 和 MiniMax 官方文档并不能稳定直接对齐
 
 如果你现在要走最稳的 DeepScientist + MiniMax 路径，建议直接使用 Codex CLI `0.57.0`。
@@ -125,7 +125,7 @@ MiniMax 是最典型的 profile 模式。它的官方 Codex CLI 文档直接给
 - 已安装 Codex CLI `0.57.0`
 - 已创建 MiniMax `Coding Plan Key`
 - 在启动 Codex 和 DeepScientist 的 shell 中可见的 `MINIMAX_API_KEY`
-- 当前 shell 已清理 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`
+- 如果你要单独在终端里验证 `codex --profile <name>`，当前 shell 需要先清理 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`
 - `~/.codex/config.toml` 中已经配置好的 Codex profile
 
 ### 安装 Codex CLI `0.57.0`
@@ -145,6 +145,8 @@ codex-cli 0.57.0
 
 如果你还想保留另一个 Codex 版本，也可以单独写一个 wrapper 脚本，再把 `runners.codex.binary` 指向那个绝对路径。
 
+现在如果 DeepScientist 在启动时检测到 MiniMax profile，但当前 `codex` 版本不是 `0.57.0`，在交互式终端里会主动提示是否自动安装 `@openai/codex@0.57.0`。
+
 ### Codex 侧配置
 
 请使用 `https://api.minimaxi.com/v1`，不要用 `https://api.minimax.io/v1`。
@@ -157,15 +159,19 @@ unset OPENAI_BASE_URL
 export MINIMAX_API_KEY="..."
 ```
 
+如果你是在终端里单独验证 `codex --profile <name>`，就按上面的方式处理。
+如果你走的是 DeepScientist 路径，那么当所选 provider 明确写了 `requires_openai_auth = false` 时，DeepScientist 现在会在 startup probe 和真实 runner 执行时自动剥离 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`。
+
 MiniMax 官方页面示例 profile 名是 `m21`。由于 profile 名只是本地别名，本仓库统一改写成 `m27`。
 
 先说明差异：
 
 - 官方页面当前展示的是 `codex-MiniMax-M2.5`
-- 但本地实测里，直接请求 MiniMax API 能稳定跑通的是 `MiniMax-M2.7`
-- 同一把 key 下，`codex-MiniMax-M2.5` / `codex-MiniMax-M2.7` 通过 Codex CLI 都会失败
+- 但本地实测里，直接请求 MiniMax API 能稳定跑通的是 `MiniMax-M2.7` 和 `MiniMax-M2.5`
+- 可复现的 DeepScientist 路径是：`MiniMax-M2.7` 配 `m27`，以及 `MiniMax-M2.5` 配 `m25`
+- 对 `m25` 这条路径，请使用 `MiniMax-M2.5`，不要写成 `codex-MiniMax-M2.5`
 
-因此，下面给的是当前 DeepScientist 推荐的可运行配置：
+因此，下面给的是当前 DeepScientist 推荐配置：
 
 ```toml
 [model_providers.minimax]
@@ -183,9 +189,19 @@ model = "MiniMax-M2.7"
 model_provider = "minimax"
 ```
 
+如果你想走同样的 DeepScientist 路径但使用 `m25`，保持上面的 provider 配置不变，再把 profile 写成：
+
+```toml
+[profiles.m25]
+model = "MiniMax-M2.5"
+model_provider = "minimax"
+```
+
 DeepScientist 现在对它的支持方式是：
 
-- 如果你使用的是这类 profile-only MiniMax 配置，再配合 Codex CLI `0.57.0`，DeepScientist 会在自己的 probe / 运行时临时 `.codex/config.toml` 里，把所选 profile 的 `model_provider` 和 `model` 自动提升到顶层
+- 如果你使用的是这类 profile-only MiniMax 配置，再配合 Codex CLI `0.57.0`，DeepScientist 会在自己的 probe / 运行时临时 `config.toml` 副本里，把所选 profile 的 `model_provider` 和 `model` 自动提升到顶层
+- 对 provider-backed 的 MiniMax profile，DeepScientist 会强制使用 `model: inherit`，避免再被硬编码的 OpenAI 模型覆盖
+- 当 `requires_openai_auth = false` 时，DeepScientist 会自动移除冲突的 `OPENAI_API_KEY` 和 `OPENAI_BASE_URL`
 - 这意味着即使终端里原样执行 `codex --profile m27` 还会失败，DeepScientist 也可以先兼容跑起来
 
 如果你还希望终端里的 `codex --profile <name>` 也直接可用，请使用显式顶层兼容写法：
@@ -248,6 +264,7 @@ DeepScientist 现在会为 MiniMax 的 `0.57.0` 路径额外做两层兼容：
 
 - 当检测到旧版 Codex CLI 不支持 `xhigh` 时，自动把 `xhigh` 降级成 `high`
 - 当检测到 MiniMax 使用 profile-only 的 `model_provider` / `model` 配置形态时，在临时 DeepScientist Codex home 里自动补齐顶层字段
+- 当 provider 明确声明 `requires_openai_auth = false` 时，自动移除冲突的 `OPENAI_*` 认证环境变量
 
 ## GLM
 

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)