deer-flow/docs/superpowers/specs/2026-06-12-telegram-streaming-design.md

# Telegram 流式输出设计

日期：2026-06-12
分支：`feat/telegram-streaming`
状态：已与用户确认

## 背景与目标

Telegram 通道目前完全不流式：`ChannelManager._handle_chat()` 走 `client.runs.wait()` 阻塞路径，agent 跑完后一次性 `send_message` 发出最终文本。用户先看到 "Working on it..."，然后长时间无反馈。

目标：让 Telegram 与飞书行为一致——通过编辑同一条消息的方式流式展示所有 AI 文本增量（manager 现有流式管线产出的累积文本），最终以 `is_final=True` 的完整结果收尾。

## 方案选型

- **方案 A（采纳）**：channel 侧自适配。只改 `telegram.py` + `CHANNEL_CAPABILITIES` 一行，Telegram 通道自己做编辑节流与限速容错。不触碰飞书/微信/钉钉共享的 manager 流式代码路径。
- 方案 B（否决）：manager 支持 per-channel `stream_min_interval` 节流。语义更统一，但改动共享路径，回归面大。

## 改动 1 — `backend/app/channels/manager.py`

`CHANNEL_CAPABILITIES["telegram"]["supports_streaming"]` 由 `False` 改为 `True`。

生效后 manager 自动走 `_handle_streaming_chat()`：
- 持续向 bus 发布 `is_final=False` 的 `OutboundMessage`（全量累积文本，manager 级节流 0.35s）；
- 流结束（或出错）时必发一条 `is_final=True` 的完整结果（含 artifacts/attachments）。

无其他 manager 改动。

## 改动 2 — `backend/app/channels/telegram.py`

### 流式状态

- 新增 `self._stream_messages: dict[str, dict]`，key 为 `f"{chat_id}:{thread_ts}"`（`thread_ts` 是触发本轮对话的用户消息 id，inbound/outbound 全程透传）。
- value 记录：`message_id`（正在被编辑的 bot 消息）、`last_edit_at`（节流时间戳）、`last_text`（已渲染文本，用于跳过无变化编辑）。

### 占位消息复用

`_send_running_reply()` 发出的 "Working on it..." 消息记录其 `message_id` 并登记到 `_stream_messages`。第一条流式更新直接编辑该占位消息。

### `send()` 按 `is_final` 分流

**`is_final=False`（流式更新）：**
1. 节流：距同 key 上次成功编辑 < 1.0 秒（群聊 `chat_id` 为负数时为 3.0 秒，因 Telegram 群有 20 条/分钟上限）→ 直接丢弃本次更新（安全：每条更新都是全量文本，final 必达兜底）。
2. 文本与 `last_text` 相同 → 跳过。
3. 已登记流式消息 → `edit_message_text`；未登记（占位发送失败等）→ `send_message` 新建并登记。
4. 文本 > 4096 字符 → 截断到 4095 并以 `…` 结尾后再编辑。

**`is_final=True`（最终结果）：**
1. 文本 ≤ 4096：对登记的流式消息做最终一次 `edit_message_text`。
2. 文本 > 4096：第一段（4096 内）编辑流式消息，剩余按 4096 分段 `send_message` 补发。
3. 清理该 key 的 `_stream_messages` 状态；用最后一条消息 id 更新 `_last_bot_message[chat_id]`（保持现有 threaded-reply 行为）。
4. 无登记流式消息时退回现行 `send_message` 逻辑（含现有 3 次重试）。注意：命令回复与 `_send_error` 错误回复带有匹配的 `thread_ts` 且占位消息已登记，因此同样走「编辑占位消息」路径（有意的 UX 改进），而非直发新消息。

### 错误处理

- `telegram.error.RetryAfter`(429)：丢弃本次流式更新，不重试不等待（下次更新自带全量文本）；final 路径遇 429 则按 `retry_after` 等待后重试，保证最终结果送达。
- `BadRequest: message is not modified`：静默忽略（final 文本与最后一帧相同时必然出现）。
- 其他编辑失败（如消息被用户删除）：回退 `send_message` 发新消息并更新登记。

### 不变项

- 纯文本发送，不引入 `parse_mode`（无 Markdown 解析失败风险）。
- `send_file()` 附件流程不动；attachments 仅随 final 消息到达，时序不变。
- 非流式直发（无登记状态的 `is_final=True`）行为与现状完全一致。

## 测试

新增 Telegram 流式用例（参照 `tests/test_channels.py` 中飞书流式用例的 fake-bot 模式）：

1. 多条 `is_final=False`：首条编辑占位消息，后续继续编辑同一 `message_id`。
2. 1 秒内密集更新被节流丢弃；final 仍完整送达。
3. final 超 4096：首段编辑 + 余段分段补发，`_last_bot_message` 指向最后一段。
4. `message is not modified` 被静默忽略，不计为失败。
5. 占位消息缺失时首条流式更新退化为 `send_message` 新建。
6. 无流式状态的 `is_final=True` 直发路径行为不变（回归保护）。

## 风险

- Telegram 对单 chat 的编辑限速较严（约 1 次/秒）。1s channel 侧节流 + 429 丢帧策略是飞书 0.35s 间隔在 Telegram 上的等价物；最坏情况是中间帧丢失，最终完整性由 `is_final=True` 保证。
- 群聊多话题并发：key 含 `thread_ts`，不同话题的流式互不串扰。