root/goodbuddy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add Telegram private messaging channel

Browse Source 
Connect a user-created Telegram bot to channel projects with encrypted credentials, numeric sender allowlists, unified execution and text replies. Use Electron networking for system proxy support, with polling recovery, cancellable delivery retries and live status updates.

Add schema 61 channel support, lifecycle regression tests, Electron integration probes and feature documentation. Require the performance principles in AGENTS.md and record three alternating baseline/current Main benchmark rounds.

Validation: typecheck, lint and diff checks passed. Full suite: 6087 passed, 87 skipped, one intermittent inline-help Electron failure that passed unchanged in isolation. Real Bot plus model acceptance remains pending; the local TLS proxy probe is opt-in.

Release note: 新增 Telegram 私聊通道，可配置 Bot Token 和用户白名单，通过通道项目处理文字请求并回复结果。支持系统代理、断线重连和停用取消；真实 Bot 与模型的完整联调仍待完成。
This commit is contained in:
mesalogo
2026-10-05 02:42:28 +08:00
parent 78afec7775
commit cf598121b1
56 changed files with 4144 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/telegram-channel/prd.md
+24 -21
View File
@@ -4,20 +4,20 @@
| 项目 | 内容 |
| --- | --- |
| 状态 | 草案，待评审；Telegram 通道尚未实现 |
| 版本 | 0.1 |
| 日期 | 2026-10-04 |
| 状态 | 已按生产实现修订；真实 Bot 与模型完整链路待验收 |
| 版本 | 0.2 |
| 日期 | 2026-10-05 |
| 适用产品 | GoodBuddy 桌面端 |
| 首版范围 | 单 Bot、普通私聊、文字问答与工具任务、最终结果回复 |
| 接入方式 | 用户通过 BotFather 创建 Bot，GoodBuddy 使用 Bot API 长轮询 |
本文定义拟交付的产品行为。验收表描述未来交付标准，不代表已经通过测试。BotFather 接入方向来自本次讨论；范围取舍和异常行为是本草案提出的方案。
本文定义首版产品行为和验收标准，已按当前实现修订。验收表不代表已经通过测试；验证结果及剩余工作由[进度记录](./progress.md)维护，模块与协议细节见[技术设计](./technical-design.md)。
## 1. 用户问题与目标
用户离开电脑后，希望通过 Telegram 向 GoodBuddy 提问或发起任务，并在手机上收到结果。任务应使用桌面端已经配置的模型、Runtime 和工作目录，执行过程与对话历史仍可在 GoodBuddy 查看。
当前远程消息通道已有微信 ClawBot、企业微信和钉钉，尚无 Telegram 入口。新增通道应沿用现有“通道项目 + 远程会话”结构，让用户通过创建 Bot、填写凭据和配置允许访问的用户完成接入，无需自行部署消息中转服务。
Telegram 沿用现有“通道项目 + 远程会话”结构，与微信 ClawBot、企业微信和钉钉并列。用户通过创建 Bot、填写凭据和配置允许访问的用户完成接入，无需自行部署消息中转服务。
首版完成以下使用流程：
@@ -35,7 +35,7 @@
| Bot 数量 | 每个 GoodBuddy 用户配置一个 Telegram Bot |
| 会话类型 | 普通私聊；不同用户的会话相互隔离 |
| 输入 | 文字消息和受支持的命令 |
| 执行 | 复用渠道项目的处理后端和统一执行规则，无产品模式 |
| 执行 | 复用渠道项目的处理后端、已启用能力和统一执行规则 |
| 输出 | 任务进行提示、最终文字结果、长回复分段 |
| 管理 | Token 保存和替换、用户 ID 白名单、连接测试、启停和状态展示 |
| 故障处理 | 临时断网重连、平台限流等待、已保存结果的有限重试 |
@@ -63,7 +63,7 @@
1. 用户在 GoodBuddy 远程通道设置中打开 Telegram 卡片，点击官方 BotFather 链接。
2. 用户在 BotFather 发送 `/newbot`，设置显示名称和符合 Telegram 要求的用户名，获得 Token。
3. 用户回到 GoodBuddy 填写 Token，执行“测试连接”。成功后显示 Bot 名称、用户名和打开 Bot 的链接。
3. 用户回到 GoodBuddy 填写 Token，执行“测试连接”。成功后显示 API 返回的 Bot 用户名和打开 Bot 的链接，不展示 Bot 显示名称。
4. 用户先保存凭据并以空白名单启用连接，卡片显示“尚未授权用户”。此时仅提供私聊帮助，不接受业务请求。
5. 用户在 Telegram 打开该 Bot，发送 `/start`，再发送 `/whoami` 获取自己的数字用户 ID。卡片说明必须由用户先发起私聊。
6. 用户将该 ID 填入 GoodBuddy 白名单并保存，随后发送普通文本，收到回复，并在 Telegram 项目中看到对应会话。
@@ -82,9 +82,9 @@
### FR-2 凭据管理
Token 使用现有加密凭据存储，保存后不在普通设置快照中返回明文。用户可以保留、替换或清除凭据。日志、连接错误和会话内容不得包含 Token 或含 Token 的完整请求地址。
Token 使用现有加密凭据存储，保存后不在普通设置快照中返回明文。用户可以保留、替换或清除凭据；环境变量覆盖时配置只读。日志、连接错误和会话内容不得包含 Token 或含 Token 的完整请求地址。
替换 Token 前验证 Bot 身份。若仍为同一个 Bot，继续使用原会话；若为另一个 Bot，新会话与旧 Bot 隔离，旧 Bot 的待发结果不得经新 Bot 发送。清除凭据停止连接，保留项目与历史。
替换 Token 前验证 Bot 身份，验证失败保留原配置与连接。若仍为同一个 Bot，继续使用原会话；若为另一个 Bot，新会话与旧 Bot 隔离，旧 Bot 的待发结果不得经新 Bot 发送。在设置页清除凭据并保存时同时停用通道，保留项目与历史。
### FR-3 连接测试
@@ -102,14 +102,15 @@ Token 使用现有加密凭据存储，保存后不在普通设置快照中返
### FR-5 会话与连续上下文
同一 Bot 下同一普通私聊复用远程会话，不同用户和不同 Bot 的上下文隔离。会话显示来源和发送者名称；名称不可用时使用用户 ID 作为可识别的回退信息。名称变化不产生新身份。
同一 Bot 下同一普通私聊复用远程会话，不同用户和不同 Bot 的上下文隔离。会话归属 Telegram 项目，发送者以数字用户 ID 标识；首版不采集发送者显示名称。
同一会话按接收顺序处理业务消息。用户连续发送消息时，不得使后发请求抢用尚未完成的上一轮上下文。不同会话沿用现有通道并发限制。
### FR-6 执行范围
普通文本使用项目后端与能力配置；`/ask`、`/execute` 和 `/exec` 沿用现有渠道的退役规则，
作为普通正文保留，不切换权限。仅含旧命令的非空消息也按普通消息处理。
授权用户直接发送自然语言请求，使用项目后端与能力配置完成问答或工具任务，无需选择或切换工作模式。通道不提供模式选择器、默认模式设置或模式切换命令。
`/ask`、`/execute` 和 `/exec` 按现有统一执行规则作为普通正文保留，不剥离前缀、不切换权限；仅含旧命令的非空消息也按普通消息处理。帮助文案不再介绍这些前缀。
按[统一执行规则](../unified-execution/logic-design.md)使用已启用工具，不增加 Telegram 专属
逐工具审批。设置页显示默认工作目录和后端，并说明允许访问的用户可发起操作。
@@ -119,7 +120,7 @@ Token 使用现有加密凭据存储，保存后不在普通设置快照中返
`/start` 返回 Bot 用途、授权配置说明和基础用法；`/whoami` 仅返回当前发送者的数字用户 ID。上述命令不写入业务上下文。
授权用户发送未知斜杠命令时，返回支持的命令列表，不将其当成执行请求。编辑历史消息不自动重新执行任务。
除 `/start` 和 `/whoami` 外，授权用户发送的非空文字均按普通请求处理，包括带斜杠前缀的文字，不额外引入命令兼容规则。空白消息按现有输入规则拒绝。编辑历史消息不自动重新执行任务。
授权用户发送媒体时，提示“当前仅支持文字消息，请改用文字描述”。带说明文字的媒体首版同样提示不支持，不丢弃媒体后擅自执行说明文字。未授权媒体不触发处理。
@@ -127,7 +128,7 @@ Token 使用现有加密凭据存储，保存后不在普通设置快照中返
请求进入处理后，Telegram 侧显示输入状态或简短进行提示。该提示不表示任务完成，也不表示任务可以在应用崩溃后恢复。
任务完成后发送最终文字；失败时发送脱敏原因及必要的恢复建议。回复尽量关联原始消息；原消息不可引用时仍应尝试发送结果。长文本按平台上限顺序分段，不破坏 Unicode 字符，不因 Markdown 转义问题造成整条回复失败。
任务完成后发送最终文字；失败时发送脱敏原因及必要的恢复建议。回复作为普通私聊消息发送，首版不引用原始消息。长文本以纯文本顺序分段，保留 Unicode 代理对，不启用 Markdown 解析。
首版不发送附件。若任务产生图片或文件，文字回复说明成果可在 GoodBuddy 中查看，不宣称附件已发送，也不向用户发送仅本机可访问的路径作为下载链接。
@@ -137,7 +138,7 @@ Token 使用现有加密凭据存储，保存后不在普通设置快照中返
已生成并保存的结果沿用现有发件箱有限重试，发送失败与任务执行失败分别记录。补发回复不重新调用模型或重跑任务。用户阻止 Bot 等不可恢复错误应停止无效重试。
多段回复部分成功后，应尽量从未发送部分继续。网络中断导致无法确定平台是否收到某段时，允许重试出现重复段落，首版不承诺平台级发送幂等。
同一驱动实例内且分段进度仍在缓存时，多段回复从未发送部分继续。进度不跨重启持久化，重启或缓存淘汰后补发可能重复已发送段落；网络中断造成平台接收结果不明时也可能重复。首版不承诺平台级发送幂等。
### FR-10 启停与历史保留
@@ -157,7 +158,9 @@ Telegram 待接收更新最多保留 24 小时，超过平台保留期的离线
### FR-12 状态与诊断
设置页区分未配置、已停用、正在连接、已连接、正在重连和连接失败。空白名单作为“尚未授权用户”的配置提示展示，不与网络状态混为一谈。
设置页展示未配置、已停用、正在连接、已连接、已停止和连接失败。重连时显示正在连接，并附带错误原因与重连说明；没有独立的重连状态值。空白名单作为“尚未授权用户”的配置提示展示，不与网络状态混为一谈。
状态和错误推送只更新状态区域，不覆盖尚未保存的 Token 或白名单草稿。解决轮询冲突后可重新保存当前配置以启动连接；单独测试连接成功不改变接收状态。
状态通过文字表达，不能只靠颜色。错误保留可操作原因，如 Token 无效、网络不可达、webhook 占用或另一实例正在轮询。测试成功、发送失败和模型失败使用各自准确文案，避免统一显示“连接失败”。
@@ -174,15 +177,15 @@ Telegram 待接收更新最多保留 24 小时，超过平台保留期的离线
| AC-03 | FR-2、3 | 通道运行时连续测试连接，不争抢轮询、不消费业务消息；无效 Token 与 webhook 占用分别提示 |
| AC-04 | FR-5 | 同一用户连续两轮对话保留上下文；两名授权用户的内容不相互进入上下文 |
| AC-05 | FR-6 | 普通请求可在专用测试目录完成一次无害工具任务；旧模式前缀作为正文保留，结果和活动可在桌面核对，无默认模式字段 |
| AC-06 | FR-4、7 | 未授权用户、群消息、话题消息和媒体不触发任务；授权媒体、未知命令和空命令获得准确提示 |
| 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-10 | 停用通道后新消息不启动任务，当前与排队任务取消；历史与成果保留；重新启用不重跑取消任务 |
| 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 错误均可定位 |
| AC-14 | FR-2、12 | 设置快照、日志及错误不泄漏 Token；凭据轮换、网络错误和 Runtime 错误均可定位；连接错误及重连状态推送保留未保存的 Token 和白名单草稿 |
| AC-15 | FR-1、10 | 新增 Telegram 后微信、企业微信和钉钉的设置、启停与历史读取保持原行为 |
| AC-16 | FR-9、10 | 有已保存回复等待重试时停用通道，确认重试停止；重新启用后补发该 Bot 的结果，任务执行次数不增加 |
| AC-17 | FR-11 | 在专用测试任务执行期间异常退出应用，重启后不自动重跑该中断任务；已有任务记录可查询，不把未取得的完成结果显示为成功；帮助说明保留人工核对后重发的限制 |
@@ -193,9 +196,9 @@ Telegram 待接收更新最多保留 24 小时，超过平台保留期的离线
通道项目、工作目录、Runtime 选择和授权语义复用[现有远程消息通道约定](../wechat-channel/prd.md)。Telegram 的外部网络可达性、Bot 状态和平台限额影响收发，连接测试无法证明后续每次任务或文件生成都能成功。
开发前需核对主进程网络与代理路径，以及现有通道停用、去重和发件箱行为是否满足本文要求。差异应在对应技术设计中解决并关联 FR 编号，不能只增加设置入口后宣称完成。本文不规定新增 SDK、数据库表或通用恢复框架。
生产驱动使用 Electron 网络栈和系统代理。停用、去重、发件箱与状态推送的实现见[技术设计](./technical-design.md)，实际覆盖与未完成验证见[进度记录](./progress.md)。没有测量数据时，不宣称性能提升或性能预算通过。
前期讨论提出过“持久化入站后再确认”的方案。本草案将其列为后续可靠性评估，首版采用 FR-11 的明确限制；若后续要求已接收任务跨崩溃恢复，再依据实际故障与业务需求评估存储和执行恢复成本。
持久化入站后再确认仍属于后续可靠性评估，首版采用 FR-11 的限制；若后续要求已接收任务跨崩溃恢复，再依据实际故障与业务需求评估存储和执行恢复成本。
| 后续方向 | 进入设计前需明确的内容 |
| --- | --- |