Files

T

mesalogo cf598121b1 feat: add Telegram private messaging channel

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 与模型的完整联调仍待完成。

2026-10-05 02:42:28 +08:00

7.2 KiB

Raw Permalink Blame History

Telegram API 联调

用途与边界

run-live-probe.mjs 启动 Electron，运行 live-probe-main.ts，检查生产驱动及可选的 ChannelService 固定回复。telegram-probe.mjs 是独立 Node API 诊断脚本，没有接入 GoodBuddy 项目、会话、白名单、Runtime 或发件箱。

两类探针都不调用模型，成功不能代替真实 Bot 与模型完整链路验收。生产驱动使用 Electron net.fetch 和系统代理，没有引入 grammY 或 Telegraf；独立脚本使用 Node fetch。当前结果和 2026-10-04 历史记录统一见进度记录。本次生产实时探针未运行，原因是 TELEGRAM_BOT_TOKEN 不存在。

生产驱动探针

从仓库根目录运行，需要已安装项目依赖（Electron、esbuild）。启动器在临时目录构建生产源码，使用隔离的 Electron 用户目录，退出后清理。可用 --temp-parent PATH 指定已存在的临时父目录。

node "docs/features/telegram-channel/run-live-probe.mjs" --dry-run

--dry-run 只构建并检查语法，不启动 Electron，不发网络请求，不需要 Token。它不能证明代理路径可用。实时连接检查使用下面命令；隐藏输入仅放入进程环境，不写文件。

$telegramProbeSecret = Read-Host 'Telegram Bot Token' -AsSecureString
$env:TELEGRAM_BOT_TOKEN = [System.Net.NetworkCredential]::new('', $telegramProbeSecret).Password
try {
    node "docs/features/telegram-channel/run-live-probe.mjs"
} finally {
    Remove-Item Env:TELEGRAM_BOT_TOKEN -ErrorAction SilentlyContinue
    $telegramProbeSecret = $null
}

默认仅通过生产驱动执行 getMe / getWebhookInfo，不轮询、不发送。TELEGRAM_BOT_TOKEN 是探针输入，产品只读环境配置使用 GOODBUDDY_TELEGRAM_BOT_TOKEN，两者不能混用。

要验证固定回复，先停用该专用测试 Bot 的其他消费者，在普通私聊发送精确文本 /goodbuddy_test，再将上述运行命令替换为：

node "docs/features/telegram-channel/run-live-probe.mjs" --send-test

发送模式从首批最多 100 条积压中选择最近 24 小时内最新的合格私聊标记，临时授权该发送者，经生产驱动和 ChannelService 返回固定文字。网络适配层只把选中的事件交给驱动，其他事件不会触发帮助或任务；使用临时内存状态和固定 executor，不经过产品设置页、生产模型或持久化发件箱。

发送模式会启动生产轮询、设置 allowed_updates=['message'] 并可能推进 offset，因而可能确认或消费更早的积压。仅对专用空闲 Bot 使用；这与独立 Node 探针不推进 offset 的行为不同。无匹配标记时失败退出，不等待用户补发。

输出	含义
`PASS: production driver getMe/getWebhookInfo.`	生产驱动身份及 webhook 检查成功
`PASS: production driver and ChannelService delivered the test reply.`	固定回复 API 成功，仍需手机核对展示；未调用模型
`FAIL: no eligible marker...`	首批积压无合格标记，收发未验证
其他 `FAIL` 或非零退出	设置、构建、网络、停止或清理失败，不算通过

启动器只转发固定结果码，抑制可能包含 Token URL 的 Electron 输出，并强制 TLS 校验。成功退出要求对应检查完成且子进程正常退出。

独立 Node 探针

默认只调用 getMe 和 getWebhookInfo，不读取消息或发送回复。添加 --listen 后，在无 webhook 的情况下进行约 45 秒长轮询，仅对运行开始后收到的私聊 /goodbuddy_test 回复一条固定测试文字，然后退出。不处理其他消息、不调用模型、不下载附件。

脚本不推进更新 offset、不修改订阅类型、不删除 webhook。已读取的更新仍可能被后续消费者再次读取；请使用专用 Bot，避免与其他轮询进程同时运行。积压达到单批 100 条时停止测试，不主动确认或清空消息。固定回复发生网络结果不明时不自动重试。

运行方法

历史实测环境为 Windows、PowerShell 5.1、Node.js 24.21.0。以下命令从仓库根目录执行，Token 通过隐藏输入传入当前进程环境，不保存在文件中。不要把实际 Token 写进命令、文档或 Git。

$telegramProbeSecret = Read-Host 'Telegram Bot Token' -AsSecureString
$env:TELEGRAM_BOT_TOKEN = [System.Net.NetworkCredential]::new('', $telegramProbeSecret).Password
try {
    node --use-env-proxy "docs/features/telegram-channel/telegram-probe.mjs"
} finally {
    Remove-Item Env:TELEGRAM_BOT_TOKEN -ErrorAction SilentlyContinue
    $telegramProbeSecret = $null
}

--use-env-proxy 需要支持该选项的 Node 版本，脚本不会自动读取 Windows 系统代理。若机器依赖系统代理，先按下面方式将当前代理临时提供给 Node；这不会修改操作系统代理配置。结束后恢复原有环境值。

$telegramProbePreviousProxy = $env:HTTPS_PROXY
$telegramProbeProxy = [System.Net.WebRequest]::GetSystemWebProxy().GetProxy([Uri]'https://api.telegram.org')
if ($telegramProbeProxy.Host -ne 'api.telegram.org') {
    $env:HTTPS_PROXY = $telegramProbeProxy.AbsoluteUri
}
# 在此执行上面的凭据输入和测试命令。
$env:HTTPS_PROXY = $telegramProbePreviousProxy

测试真实收发时，将运行命令改为：

node --use-env-proxy "docs/features/telegram-channel/telegram-probe.mjs" --listen

看到提示后，在 Telegram 打开测试 Bot 的普通私聊，发送 /goodbuddy_test。脚本成功发送固定回复后输出 privateMessageRoundTrip 的 ok: true。用户还需在手机端确认实际收到回复。

如果已发送测试指令，使用 --pending 替代 --listen。脚本单次查询排队消息，选择最近一小时内最新的私聊 /goodbuddy_test 并回复，无需在监听窗口内发送。该选项同样不推进 offset，重复运行可能再次回复同一条指令，仅在需要复测时使用。

脚本强制开启 TLS 证书校验，不沿用外部环境中的关闭校验设置。输出仅包含检查结果、Bot 用户名、是否配置 webhook、积压数量和有界错误码；不打印 Token、完整请求地址、原始异常、消息正文或聊天 ID。

结果解释

输出或退出码	含义
退出码 0，默认检查	Bot 身份及 webhook 状态查询成功；未验证收发
退出码 0，`privateMessageRoundTrip` 成功	收到测试指令，发送回复 API 返回成功
退出码 2，`no_matching_message`	时间窗口内未收到符合条件的测试指令，收发待验证
退出码 1	网络、凭据、平台错误或测试条件不满足
`UND_ERR_CONNECT_TIMEOUT`	网络连接超时，优先检查当前进程的代理路径
API error 401	凭据无效或已撤销
API error 409	检查 webhook 或其他长轮询实例是否占用
API error 429	平台限流；脚本报告等待时间，不自动继续请求

日期化实测结果见进度记录。独立 Node 请求走通不能证明 Electron 生产网络路径走通；固定回复成功也不能证明模型或工具任务成功。

7.2 KiB Raw Permalink Blame History Unescape Escape