# Telegram 远程消息通道 PRD

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 已按生产实现修订；真实 Bot 与模型完整链路待验收 |
| 版本 | 0.2 |
| 日期 | 2026-10-05 |
| 适用产品 | GoodBuddy 桌面端 |
| 首版范围 | 单 Bot、普通私聊、文字问答与工具任务、最终结果回复 |
| 接入方式 | 用户通过 BotFather 创建 Bot，GoodBuddy 使用 Bot API 长轮询 |

本文定义首版产品行为和验收标准，已按当前实现修订。验收表不代表已经通过测试；验证结果及剩余工作由[进度记录](./progress.md)维护，模块与协议细节见[技术设计](./technical-design.md)。

## 1. 用户问题与目标

用户离开电脑后，希望通过 Telegram 向 GoodBuddy 提问或发起任务，并在手机上收到结果。任务应使用桌面端已经配置的模型、Runtime 和工作目录，执行过程与对话历史仍可在 GoodBuddy 查看。

Telegram 沿用现有“通道项目 + 远程会话”结构，与微信 ClawBot、企业微信和钉钉并列。用户通过创建 Bot、填写凭据和配置允许访问的用户完成接入，无需自行部署消息中转服务。

首版完成以下使用流程：

1. 用户从 BotFather 获取 Token，在 GoodBuddy 完成连接配置。
2. 用户在 Telegram 私聊 Bot，连续问答或发起工具任务。
3. 用户收到结果，在桌面端查看相应会话与执行记录。
4. 连接中断、凭据失效或结果发送失败时，用户能够识别原因并恢复使用。

## 2. 范围与前提

### 2.1 首版范围

| 能力 | 首版要求 |
| --- | --- |
| Bot 数量 | 每个 GoodBuddy 用户配置一个 Telegram Bot |
| 会话类型 | 普通私聊；不同用户的会话相互隔离 |
| 输入 | 文字消息和受支持的命令 |
| 执行 | 复用渠道项目的处理后端、已启用能力和统一执行规则 |
| 输出 | 任务进行提示、最终文字结果、长回复分段 |
| 管理 | Token 保存和替换、用户 ID 白名单、连接测试、启停和状态展示 |
| 故障处理 | 临时断网重连、平台限流等待、已保存结果的有限重试 |

### 2.2 使用前提

用户拥有 Telegram 账号，并能通过官方 [BotFather](https://t.me/BotFather) 创建 Bot。运行 GoodBuddy 的电脑需要保持应用运行，并能访问 Telegram Bot API；休眠、退出和关机期间不处理新任务。

长轮询不要求公网 IP、域名或入站端口。同一 Bot 应专用于当前 GoodBuddy 实例；已有 webhook 或另一个程序持续轮询时，需要用户解决占用问题。

连接测试验证主进程实际使用的网络路径。若现有网络配置不能让通道访问 Telegram，应明确显示失败原因；浏览器能够访问 Telegram 不作为通道可用的证据。

### 2.3 非目标

- 群聊、超级群、频道、私聊话题及论坛话题。
- 多 Bot 同时运行、个人账号登录及聊天记录批量导入。
- 图片、文件、语音、视频、贴纸和媒体相册处理。
- webhook、自建 Bot API 服务和云端常驻中转服务。
- 逐 Token 流式展示、富消息排版和 Telegram 按钮审批。
- 主动群发、营销推送和联系人发现。
- 新增远程主机执行能力或修改现有 Runtime 权限模型。
- 崩溃后自动续跑执行任务，以及消息“恰好执行一次”的保证。

## 3. 首次配置流程

1. 用户在 GoodBuddy 远程通道设置中打开 Telegram 卡片，点击官方 BotFather 链接。
2. 用户在 BotFather 发送 `/newbot`，设置显示名称和符合 Telegram 要求的用户名，获得 Token。
3. 用户回到 GoodBuddy 填写 Token，执行“测试连接”。成功后显示 API 返回的 Bot 用户名和打开 Bot 的链接，不展示 Bot 显示名称。
4. 用户先保存凭据并以空白名单启用连接，卡片显示“尚未授权用户”。此时仅提供私聊帮助，不接受业务请求。
5. 用户在 Telegram 打开该 Bot，发送 `/start`，再发送 `/whoami` 获取自己的数字用户 ID。卡片说明必须由用户先发起私聊。
6. 用户将该 ID 填入 GoodBuddy 白名单并保存，随后发送普通文本，收到回复，并在 Telegram 项目中看到对应会话。

为避免要求用户把身份信息交给第三方查询 Bot，首版提供 `/whoami`：凭据有效、通道已启用时，私聊用户可查询自己的数字用户 ID。空白名单允许启动连接，但拒绝业务任务；设置页应显示“尚未授权用户”，并引导先启用、查询 ID，再填写白名单。

`/start` 和 `/whoami` 是通道内置帮助命令，不调用模型、不读取项目内容、不获得任务执行权限。未授权用户只能获得配置所需的有限帮助。

## 4. 功能需求

### FR-1 通道入口与项目

远程通道设置和项目选择器增加 Telegram，使用现有通道项目的创建与保留约定。未完成配置时仍可打开对应项目及设置，状态显示“未配置”。

用户可以从现有项目设置修改工作目录和处理后端。从通道卡片与项目入口查看同一配置时，内容保持一致。首次创建使用现有默认直连文本模型，不保存工作模式。

### FR-2 凭据管理

Token 使用现有加密凭据存储，保存后不在普通设置快照中返回明文。用户可以保留、替换或清除凭据；环境变量覆盖时配置只读。日志、连接错误和会话内容不得包含 Token 或含 Token 的完整请求地址。

替换 Token 前验证 Bot 身份，验证失败保留原配置与连接。若仍为同一个 Bot，继续使用原会话；若为另一个 Bot，新会话与旧 Bot 隔离，旧 Bot 的待发结果不得经新 Bot 发送。在设置页清除凭据并保存时同时停用通道，保留项目与历史。

### FR-3 连接测试

测试连接检查凭据、Bot 身份和已有 webhook，返回可理解的结果。测试操作不接收业务消息、不创建任务、不改变启用状态，也不启动第二个长轮询。

凭据有效不等于通道已经开始接收消息。界面区分“验证成功”和“已连接”。检测到 webhook 时，提示用户解除原有接入后重试，不自动删除第三方配置。

### FR-4 访问范围

以 Telegram 数字用户 ID 校验发送者，不以可修改的用户名或显示名授权。仅允许白名单内用户提交业务请求。空白名单拒绝业务请求，未授权消息不进入模型、Runtime 或业务会话上下文。

首版只处理普通私聊。群组、频道、话题消息以及缺少可识别发送者的消息不得触发任务。帮助查询仅限私聊，并作有限频率控制，避免无效请求持续产生回复。

白名单变更对后续任务接收生效；撤销用户不会自动撤销此前已授权运行的任务。需要停止正在运行的任务时，用户使用现有桌面取消入口或停用通道。

### FR-5 会话与连续上下文

同一 Bot 下同一普通私聊复用远程会话，不同用户和不同 Bot 的上下文隔离。会话归属 Telegram 项目，发送者以数字用户 ID 标识；首版不采集发送者显示名称。

同一会话按接收顺序处理业务消息。用户连续发送消息时，不得使后发请求抢用尚未完成的上一轮上下文。不同会话沿用现有通道并发限制。

### FR-6 执行范围

授权用户直接发送自然语言请求，使用项目后端与能力配置完成问答或工具任务，无需选择或切换工作模式。通道不提供模式选择器、默认模式设置或模式切换命令。

`/ask`、`/execute` 和 `/exec` 按现有统一执行规则作为普通正文保留，不剥离前缀、不切换权限；仅含旧命令的非空消息也按普通消息处理。帮助文案不再介绍这些前缀。

按[统一执行规则](../unified-execution/logic-design.md)使用已启用工具，不增加 Telegram 专属
逐工具审批。设置页显示默认工作目录和后端，并说明允许访问的用户可发起操作。
需要交互提问而当前后台 Runtime 无法继续的任务，应返回明确失败原因，不无限等待。

### FR-7 帮助与不支持的消息

`/start` 返回 Bot 用途、授权配置说明和基础用法；`/whoami` 仅返回当前发送者的数字用户 ID。上述命令不写入业务上下文。

除 `/start` 和 `/whoami` 外，授权用户发送的非空文字均按普通请求处理，包括带斜杠前缀的文字，不额外引入命令兼容规则。空白消息按现有输入规则拒绝。编辑历史消息不自动重新执行任务。

授权用户发送媒体时，提示“当前仅支持文字消息，请改用文字描述”。带说明文字的媒体首版同样提示不支持，不丢弃媒体后擅自执行说明文字。未授权媒体不触发处理。

### FR-8 任务反馈与回复

请求进入处理后，Telegram 侧显示输入状态或简短进行提示。该提示不表示任务完成，也不表示任务可以在应用崩溃后恢复。

任务完成后发送最终文字；失败时发送脱敏原因及必要的恢复建议。回复作为普通私聊消息发送，首版不引用原始消息。长文本以纯文本顺序分段，保留 Unicode 代理对，不启用 Markdown 解析。

首版不发送附件。若任务产生图片或文件，文字回复说明成果可在 GoodBuddy 中查看，不宣称附件已发送，也不向用户发送仅本机可访问的路径作为下载链接。

### FR-9 网络与发送失败

临时网络错误自动退避重连；平台限流按服务端要求等待，不忙循环请求。凭据失效、Bot 被封禁或持续轮询冲突显示明确状态与操作建议。

已生成并保存的结果沿用现有发件箱有限重试，发送失败与任务执行失败分别记录。补发回复不重新调用模型或重跑任务。用户阻止 Bot 等不可恢复错误应停止无效重试。

已有 webhook 或另一实例占用轮询时，已确认 Bot 身份且目标匹配的待发回复仍可发送；接收冲突本身不能永久终止这些回复。发送内部重试达到上限后，发件箱的下一次尝试仍须遵守最近一次 429 响应的等待时间，停用可取消等待。

同一驱动实例内且分段进度仍在缓存时，多段回复从未发送部分继续。进度不跨重启持久化，重启或缓存淘汰后补发可能重复已发送段落；网络中断造成平台接收结果不明时也可能重复。首版不承诺平台级发送幂等。

### FR-10 启停与历史保留

启用后建立连接；停用后停止拉取新消息，取消该通道正在处理和排队的任务，并停止活动发送重试。取消已产生的外部修改不自动回滚。

停用、清除凭据及连接失败不删除项目、会话、任务和已有成果。桌面端保留可查询的状态；停用期间不要求通过已关闭通道发送取消通知。

重新启用恢复收消息及符合当前 Bot 身份的结果补发，不自动重跑此前已取消或中断的业务任务。

### FR-11 离线消息与恢复边界

重新连接时处理 Telegram 仍保留、尚未确认的普通私聊消息，并重新执行白名单检查。正常重投的同一平台事件不得重复启动任务；用户主动重发文本属于新请求。

Telegram 待接收更新最多保留 24 小时，超过平台保留期的离线消息无法由 GoodBuddy 补回。首版不主动清空积压消息；因此重新启用后可能处理离线期间发送的工具请求，帮助说明中必须提示这一行为。

现有渠道在消息进入内存队列后确认接收，应用异常退出存在已确认消息未完成的窗口。首版沿用这一边界，不宣称崩溃后零丢失或自动续跑。用户应先在桌面查看任务记录与实际结果，再决定是否重新发送任务请求。

### FR-12 状态与诊断

设置页展示未配置、已停用、正在连接、已连接、已停止和连接失败。重连时显示正在连接，并附带错误原因与重连说明；没有独立的重连状态值。空白名单作为“尚未授权用户”的配置提示展示，不与网络状态混为一谈。

状态和错误推送只更新状态区域，不覆盖尚未保存的 Token 或白名单草稿。解决轮询冲突后可重新保存当前配置以启动连接；单独测试连接成功不改变接收状态。

接收正常而结果发送失败时，保留已连接状态并显示脱敏的发送错误。后续健康轮询不清除发送提示，投递成功后清除；接收也发生错误时优先展示接收原因，恢复后保留尚未清除的发送提示。

状态通过文字表达，不能只靠颜色。错误保留可操作原因，如 Token 无效、网络不可达、webhook 占用或另一实例正在轮询。测试成功、发送失败和模型失败使用各自准确文案，避免统一显示“连接失败”。

界面沿用 [UI-DESIGN.md](../../../UI-DESIGN.md) 的控件、通知、键盘和可访问性规则，不新增独立视觉体系。

## 5. 产品验收

以下场景均需记录实际结果。自动化验证可覆盖解析和异常分支；首用配置、真实手机收发及 Runtime 执行需要真实 Bot 联调，不能用模拟响应代替。

| 编号 | 关联需求 | 场景与通过标准 |
| --- | --- | --- |
| AC-01 | FR-1～3 | 新用户从官方 BotFather 创建 Bot，完成 Token 测试与保存；界面显示正确 Bot 身份，项目入口可用 |
| AC-02 | FR-4、7 | 空白名单启用后，私聊 `/whoami` 可获取本人 ID；普通文本不调用模型；加入白名单后可正常问答 |
| AC-03 | FR-2、3 | 通道运行时连续测试连接，不争抢轮询、不消费业务消息；无效 Token 与 webhook 占用分别提示 |
| AC-04 | FR-5 | 同一用户连续两轮对话保留上下文；两名授权用户的内容不相互进入上下文 |
| AC-05 | FR-6 | 普通请求可在专用测试目录完成一次无害工具任务；旧模式前缀作为正文保留，结果和活动可在桌面核对，无默认模式字段 |
| AC-06 | FR-4、7 | 未授权用户、群消息、话题消息和媒体不触发任务；授权媒体获得不支持提示；内置帮助命令不调用模型，其他斜杠前缀按正文保留，空白消息被拒绝 |
| AC-07 | FR-8 | 超过单条平台上限的回复按序完整展示，中文和表情字符完整；任务失败返回脱敏原因 |
| AC-08 | FR-8 | 生成文件的任务在 Telegram 中提示桌面查看成果，不出现“附件已发送”的错误表述 |
| AC-09 | FR-9、12 | 模拟短暂断网、429 和永久发送错误，分别重连、等待和停止无效重试；任务执行结果不被误记为执行失败 |
| AC-10 | FR-9 | 已保存结果发送失败后恢复连接可补发，补发不增加模型调用或再次执行任务；验证部分分段成功情形 |
| AC-11 | FR-2、10 | 停用通道后新消息不启动任务，当前与排队任务取消；启用时清除 Token 并保存会同时停用；项目、历史与成果保留；重新启用不重跑取消任务 |
| AC-12 | FR-2、5 | 同一 Bot 换 Token 保留会话；更换 Bot 后上下文隔离，旧待发结果不会由新 Bot 发出 |
| AC-13 | FR-4、11 | 重投同一更新不重复执行；离线后恢复可接收平台保留消息；已撤销用户的积压消息不执行 |
| AC-14 | FR-2、12 | 设置快照、日志及错误不泄漏 Token；凭据轮换、网络错误和 Runtime 错误均可定位；连接错误及重连状态推送保留未保存的 Token 和白名单草稿 |
| AC-15 | FR-1、10 | 新增 Telegram 后微信、企业微信和钉钉的设置、启停与历史读取保持原行为 |
| AC-16 | FR-9、10 | 有已保存回复等待重试时停用通道，确认重试停止；重新启用后补发该 Bot 的结果，任务执行次数不增加 |
| AC-17 | FR-11 | 在专用测试任务执行期间异常退出应用，重启后不自动重跑该中断任务；已有任务记录可查询，不把未取得的完成结果显示为成功；帮助说明保留人工核对后重发的限制 |

功能完成以设置页到真实 Telegram 回复的生产路径可用为准。联调记录包含应用版本、操作系统、Runtime 类型、场景编号、预期与实际结果；不记录 Token。首版不设未经测量的响应时间指标，联调记录消息接收至首次反馈的耗时，并将平台网络延迟与模型执行耗时分开。

## 6. 依赖、限制与后续评估

通道项目、工作目录、Runtime 选择和授权语义复用[现有远程消息通道约定](../wechat-channel/prd.md)。Telegram 的外部网络可达性、Bot 状态和平台限额影响收发，连接测试无法证明后续每次任务或文件生成都能成功。

生产驱动使用 Electron 网络栈和系统代理。停用、去重、发件箱与状态推送的实现见[技术设计](./technical-design.md)，实际覆盖与未完成验证见[进度记录](./progress.md)。没有测量数据时，不宣称性能提升或性能预算通过。

持久化入站后再确认仍属于后续可靠性评估，首版采用 FR-11 的限制；若后续要求已接收任务跨崩溃恢复，再依据实际故障与业务需求评估存储和执行恢复成本。

| 后续方向 | 进入设计前需明确的内容 |
| --- | --- |
| 图片和文件 | 支持格式、大小、说明文字与附件组合、上传下载失败反馈 |
| 群组与话题 | 提及规则、会话隔离、结果可见范围以及话题内回复 |
| 流式与富消息 | Telegram 展示能力、更新频率、限流与最终消息一致性 |
| 多 Bot | 设置入口、项目归属与账号级结果发送 |
| 远程交互提问 | 当前 Runtime 如何暂停、恢复和取消，与现有授权语义如何一致 |

## 7. 参考资料

- [Telegram BotFather 创建与管理文档](https://core.telegram.org/bots/features#botfather)
- [Telegram Bot API：getUpdates](https://core.telegram.org/bots/api#getupdates)
- [Telegram Bot API：getMe](https://core.telegram.org/bots/api#getme)
- [Telegram Bot API：getWebhookInfo](https://core.telegram.org/bots/api#getwebhookinfo)
- [Telegram Bot API：sendMessage](https://core.telegram.org/bots/api#sendmessage)
- [Telegram Bot API：ResponseParameters](https://core.telegram.org/bots/api#responseparameters)

平台接口依据 2026-10-04 查阅的官方文档；实现与联调时需再次核对限制。