mesalogo
56ebd40bd8
Remove Ask/Execute modes and general product tool approvals so requests use the selected runtime, enabled capabilities, and execution account permissions. Migrate retired application metadata while preserving user content. Retire the Results page while retaining conversation images and stored artifacts. Add local and remote workspace file imports, timestamps and sorting, improve image discovery and saving, and refine workspace navigation and supervision responsiveness. Include the accompanying web-search changes, tests, probes, and product documentation. Remote imports require an updated Agent. Existing artifacts are not automatically copied into project directories. Validation evidence and outstanding failures remain documented in feature progress files; no full test suite or real-model calls were rerun for this commit. Release note: Run requests without switching work modes, import files into a selected local or remote workspace folder, sort workspace files by date, and keep using conversation images after removal of the Results page.
218 lines
17 KiB
Markdown
218 lines
17 KiB
Markdown
# Telegram 远程消息通道 PRD
|
||
|
||
## 文档信息
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 状态 | 草案，待评审；Telegram 通道尚未实现 |
|
||
| 版本 | 0.1 |
|
||
| 日期 | 2026-10-04 |
|
||
| 适用产品 | GoodBuddy 桌面端 |
|
||
| 首版范围 | 单 Bot、普通私聊、文字问答与工具任务、最终结果回复 |
|
||
| 接入方式 | 用户通过 BotFather 创建 Bot，GoodBuddy 使用 Bot API 长轮询 |
|
||
|
||
本文定义拟交付的产品行为。验收表描述未来交付标准，不代表已经通过测试。BotFather 接入方向来自本次讨论；范围取舍和异常行为是本草案提出的方案。
|
||
|
||
## 1. 用户问题与目标
|
||
|
||
用户离开电脑后，希望通过 Telegram 向 GoodBuddy 提问或发起任务，并在手机上收到结果。任务应使用桌面端已经配置的模型、Runtime 和工作目录，执行过程与对话历史仍可在 GoodBuddy 查看。
|
||
|
||
当前远程消息通道已有微信 ClawBot、企业微信和钉钉，尚无 Telegram 入口。新增通道应沿用现有“通道项目 + 远程会话”结构，让用户通过创建 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，执行“测试连接”。成功后显示 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 的上下文隔离。会话显示来源和发送者名称；名称不可用时使用用户 ID 作为可识别的回退信息。名称变化不产生新身份。
|
||
|
||
同一会话按接收顺序处理业务消息。用户连续发送消息时，不得使后发请求抢用尚未完成的上一轮上下文。不同会话沿用现有通道并发限制。
|
||
|
||
### FR-6 执行范围
|
||
|
||
普通文本使用项目后端与能力配置；`/ask`、`/execute` 和 `/exec` 沿用现有渠道的退役规则，
|
||
作为普通正文保留，不切换权限。仅含旧命令的非空消息也按普通消息处理。
|
||
|
||
按[统一执行规则](../unified-execution/logic-design.md)使用已启用工具，不增加 Telegram 专属
|
||
逐工具审批。设置页显示默认工作目录和后端，并说明允许访问的用户可发起操作。
|
||
需要交互提问而当前后台 Runtime 无法继续的任务，应返回明确失败原因，不无限等待。
|
||
|
||
### FR-7 帮助与不支持的消息
|
||
|
||
`/start` 返回 Bot 用途、授权配置说明和基础用法；`/whoami` 仅返回当前发送者的数字用户 ID。上述命令不写入业务上下文。
|
||
|
||
授权用户发送未知斜杠命令时，返回支持的命令列表，不将其当成执行请求。编辑历史消息不自动重新执行任务。
|
||
|
||
授权用户发送媒体时，提示“当前仅支持文字消息，请改用文字描述”。带说明文字的媒体首版同样提示不支持，不丢弃媒体后擅自执行说明文字。未授权媒体不触发处理。
|
||
|
||
### FR-8 任务反馈与回复
|
||
|
||
请求进入处理后，Telegram 侧显示输入状态或简短进行提示。该提示不表示任务完成，也不表示任务可以在应用崩溃后恢复。
|
||
|
||
任务完成后发送最终文字；失败时发送脱敏原因及必要的恢复建议。回复尽量关联原始消息；原消息不可引用时仍应尝试发送结果。长文本按平台上限顺序分段，不破坏 Unicode 字符，不因 Markdown 转义问题造成整条回复失败。
|
||
|
||
首版不发送附件。若任务产生图片或文件，文字回复说明成果可在 GoodBuddy 中查看，不宣称附件已发送，也不向用户发送仅本机可访问的路径作为下载链接。
|
||
|
||
### FR-9 网络与发送失败
|
||
|
||
临时网络错误自动退避重连；平台限流按服务端要求等待，不忙循环请求。凭据失效、Bot 被封禁或持续轮询冲突显示明确状态与操作建议。
|
||
|
||
已生成并保存的结果沿用现有发件箱有限重试，发送失败与任务执行失败分别记录。补发回复不重新调用模型或重跑任务。用户阻止 Bot 等不可恢复错误应停止无效重试。
|
||
|
||
多段回复部分成功后，应尽量从未发送部分继续。网络中断导致无法确定平台是否收到某段时，允许重试出现重复段落，首版不承诺平台级发送幂等。
|
||
|
||
### FR-10 启停与历史保留
|
||
|
||
启用后建立连接；停用后停止拉取新消息，取消该通道正在处理和排队的任务，并停止活动发送重试。取消已产生的外部修改不自动回滚。
|
||
|
||
停用、清除凭据及连接失败不删除项目、会话、任务和已有成果。桌面端保留可查询的状态；停用期间不要求通过已关闭通道发送取消通知。
|
||
|
||
重新启用恢复收消息及符合当前 Bot 身份的结果补发，不自动重跑此前已取消或中断的业务任务。
|
||
|
||
### FR-11 离线消息与恢复边界
|
||
|
||
重新连接时处理 Telegram 仍保留、尚未确认的普通私聊消息，并重新执行白名单检查。正常重投的同一平台事件不得重复启动任务；用户主动重发文本属于新请求。
|
||
|
||
Telegram 待接收更新最多保留 24 小时，超过平台保留期的离线消息无法由 GoodBuddy 补回。首版不主动清空积压消息；因此重新启用后可能处理离线期间发送的工具请求，帮助说明中必须提示这一行为。
|
||
|
||
现有渠道在消息进入内存队列后确认接收，应用异常退出存在已确认消息未完成的窗口。首版沿用这一边界，不宣称崩溃后零丢失或自动续跑。用户应先在桌面查看任务记录与实际结果，再决定是否重新发送任务请求。
|
||
|
||
### FR-12 状态与诊断
|
||
|
||
设置页区分未配置、已停用、正在连接、已连接、正在重连和连接失败。空白名单作为“尚未授权用户”的配置提示展示，不与网络状态混为一谈。
|
||
|
||
状态通过文字表达，不能只靠颜色。错误保留可操作原因，如 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-10 | 停用通道后新消息不启动任务，当前与排队任务取消；历史与成果保留；重新启用不重跑取消任务 |
|
||
| AC-12 | FR-2、5 | 同一 Bot 换 Token 保留会话；更换 Bot 后上下文隔离，旧待发结果不会由新 Bot 发出 |
|
||
| AC-13 | FR-4、11 | 重投同一更新不重复执行；离线后恢复可接收平台保留消息；已撤销用户的积压消息不执行 |
|
||
| AC-14 | FR-2、12 | 设置快照、日志及错误不泄漏 Token；凭据轮换、网络错误和 Runtime 错误均可定位 |
|
||
| 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 状态和平台限额影响收发，连接测试无法证明后续每次任务或文件生成都能成功。
|
||
|
||
开发前需核对主进程网络与代理路径，以及现有通道停用、去重和发件箱行为是否满足本文要求。差异应在对应技术设计中解决并关联 FR 编号，不能只增加设置入口后宣称完成。本文不规定新增 SDK、数据库表或通用恢复框架。
|
||
|
||
前期讨论提出过“持久化入站后再确认”的方案。本草案将其列为后续可靠性评估，首版采用 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 查阅的官方文档；实现与联调时需再次核对限制。
|