mesalogo
b90ff50f2a
Load Supervisor graphs only when opened, preserve source details on demand, reuse indexed story digests and window selection lists without losing keyboard or focus behavior. Route heavy UI reads through the existing worker, batch scoped queries and construct each publication snapshot once. Keep remote cancellation responsive during model-route cleanup, remove late routes and retain reported usage after response-cap cancellation. Preserve Telegram pending replies through polling conflicts, show delivery errors and honor the final rate-limit cooldown. Schema 62 adds lookup indexes without rewriting user content; older clients cannot open upgraded data. Large review publication still blocks Main and remains documented follow-up work. Record the future storage-service direction without performing the architecture migration. Validation: exact staged code passed isolated full tests (6212 passed, 87 skipped), typecheck and lint. Three-round source performance comparisons, SQLite migration equivalence, native Electron interaction checks and current-source Linux x64 Host validation completed; eight external text-model requests. Release note: Supervisor opens reviews without loading the entire graph, keeps long selection lists responsive and preserves details and keyboard navigation. Remote cancellation and Telegram reply recovery are more reliable; remote fixes require an Agent build containing this change.
18 KiB
Telegram 远程消息通道 PRD
文档信息
| 项目 | 内容 |
|---|---|
| 状态 | 已按生产实现修订；真实 Bot 与模型完整链路待验收 |
| 版本 | 0.2 |
| 日期 | 2026-10-05 |
| 适用产品 | GoodBuddy 桌面端 |
| 首版范围 | 单 Bot、普通私聊、文字问答与工具任务、最终结果回复 |
| 接入方式 | 用户通过 BotFather 创建 Bot，GoodBuddy 使用 Bot API 长轮询 |
本文定义首版产品行为和验收标准，已按当前实现修订。验收表不代表已经通过测试；验证结果及剩余工作由进度记录维护，模块与协议细节见技术设计。
1. 用户问题与目标
用户离开电脑后，希望通过 Telegram 向 GoodBuddy 提问或发起任务，并在手机上收到结果。任务应使用桌面端已经配置的模型、Runtime 和工作目录，执行过程与对话历史仍可在 GoodBuddy 查看。
Telegram 沿用现有“通道项目 + 远程会话”结构，与微信 ClawBot、企业微信和钉钉并列。用户通过创建 Bot、填写凭据和配置允许访问的用户完成接入，无需自行部署消息中转服务。
首版完成以下使用流程：
- 用户从 BotFather 获取 Token，在 GoodBuddy 完成连接配置。
- 用户在 Telegram 私聊 Bot，连续问答或发起工具任务。
- 用户收到结果，在桌面端查看相应会话与执行记录。
- 连接中断、凭据失效或结果发送失败时，用户能够识别原因并恢复使用。
2. 范围与前提
2.1 首版范围
| 能力 | 首版要求 |
|---|---|
| Bot 数量 | 每个 GoodBuddy 用户配置一个 Telegram Bot |
| 会话类型 | 普通私聊；不同用户的会话相互隔离 |
| 输入 | 文字消息和受支持的命令 |
| 执行 | 复用渠道项目的处理后端、已启用能力和统一执行规则 |
| 输出 | 任务进行提示、最终文字结果、长回复分段 |
| 管理 | Token 保存和替换、用户 ID 白名单、连接测试、启停和状态展示 |
| 故障处理 | 临时断网重连、平台限流等待、已保存结果的有限重试 |
2.2 使用前提
用户拥有 Telegram 账号，并能通过官方 BotFather 创建 Bot。运行 GoodBuddy 的电脑需要保持应用运行，并能访问 Telegram Bot API；休眠、退出和关机期间不处理新任务。
长轮询不要求公网 IP、域名或入站端口。同一 Bot 应专用于当前 GoodBuddy 实例；已有 webhook 或另一个程序持续轮询时，需要用户解决占用问题。
连接测试验证主进程实际使用的网络路径。若现有网络配置不能让通道访问 Telegram，应明确显示失败原因；浏览器能够访问 Telegram 不作为通道可用的证据。
2.3 非目标
- 群聊、超级群、频道、私聊话题及论坛话题。
- 多 Bot 同时运行、个人账号登录及聊天记录批量导入。
- 图片、文件、语音、视频、贴纸和媒体相册处理。
- webhook、自建 Bot API 服务和云端常驻中转服务。
- 逐 Token 流式展示、富消息排版和 Telegram 按钮审批。
- 主动群发、营销推送和联系人发现。
- 新增远程主机执行能力或修改现有 Runtime 权限模型。
- 崩溃后自动续跑执行任务，以及消息“恰好执行一次”的保证。
3. 首次配置流程
- 用户在 GoodBuddy 远程通道设置中打开 Telegram 卡片，点击官方 BotFather 链接。
- 用户在 BotFather 发送
/newbot，设置显示名称和符合 Telegram 要求的用户名，获得 Token。 - 用户回到 GoodBuddy 填写 Token，执行“测试连接”。成功后显示 API 返回的 Bot 用户名和打开 Bot 的链接，不展示 Bot 显示名称。
- 用户先保存凭据并以空白名单启用连接，卡片显示“尚未授权用户”。此时仅提供私聊帮助，不接受业务请求。
- 用户在 Telegram 打开该 Bot，发送
/start，再发送/whoami获取自己的数字用户 ID。卡片说明必须由用户先发起私聊。 - 用户将该 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 按现有统一执行规则作为普通正文保留，不剥离前缀、不切换权限；仅含旧命令的非空消息也按普通消息处理。帮助文案不再介绍这些前缀。
按统一执行规则使用已启用工具，不增加 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 的控件、通知、键盘和可访问性规则，不新增独立视觉体系。
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 选择和授权语义复用现有远程消息通道约定。Telegram 的外部网络可达性、Bot 状态和平台限额影响收发，连接测试无法证明后续每次任务或文件生成都能成功。
生产驱动使用 Electron 网络栈和系统代理。停用、去重、发件箱与状态推送的实现见技术设计，实际覆盖与未完成验证见进度记录。没有测量数据时，不宣称性能提升或性能预算通过。
持久化入站后再确认仍属于后续可靠性评估，首版采用 FR-11 的限制；若后续要求已接收任务跨崩溃恢复，再依据实际故障与业务需求评估存储和执行恢复成本。
| 后续方向 | 进入设计前需明确的内容 |
|---|---|
| 图片和文件 | 支持格式、大小、说明文字与附件组合、上传下载失败反馈 |
| 群组与话题 | 提及规则、会话隔离、结果可见范围以及话题内回复 |
| 流式与富消息 | Telegram 展示能力、更新频率、限流与最终消息一致性 |
| 多 Bot | 设置入口、项目归属与账号级结果发送 |
| 远程交互提问 | 当前 Runtime 如何暂停、恢复和取消，与现有授权语义如何一致 |
7. 参考资料
- Telegram BotFather 创建与管理文档
- Telegram Bot API：getUpdates
- Telegram Bot API：getMe
- Telegram Bot API：getWebhookInfo
- Telegram Bot API：sendMessage
- Telegram Bot API：ResponseParameters
平台接口依据 2026-10-04 查阅的官方文档；实现与联调时需再次核对限制。