LobeHub Telegram 机器人端到端测试指南：基于 osascript 的 macOS 桌面自动化实践
【免费下载链接】lobehub🤯 LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub
本文围绕 LobeHub 仓库中
.agents/skills/agent-testing-bot/telegram/这一机器人渠道端到端验收技能展开。LobeHub 需要把 AI Agent 接入 Telegram、Discord、Slack、微信等真实聊天渠道进行验证，而这些原生 App 无法用 CDP 驱动，只能通过 macOS 的 AppleScript /osascript完成激活、导航、发消息与截图取证。读完本文，你将掌握在真实 Telegram 桌面端中定位机器人会话、发送长短消息、抓取回复截图、可选使用 Telegram Bot HTTP API 做程序化补充验证的完整方法，并理解其背后共享的 macOS 自动化模式、录制前置门槛与驱动脚本契约。
一、背景：为什么需要“Telegram 机器人测试”这份技能
LobeHub 的核心定位是「Chief Agent Operator」，将你的 Agent 组织成 7×24 小时运行的 AI 团队，而 Telegram 正是这类智能体对外提供服务的消息渠道之一（见仓库文档 docs/usage/channels/telegram.mdx，它描述了如何通过 BotFather 创建机器人并把 LobeHub Agent 连接为 Telegram 渠道）。当改动涉及机器人渠道行为时，唯一能端到端验证真实渠道的方式，就是驱动真实的原生客户端去收发消息。
在仓库中，这由 .agents/skills/agent-testing-bot/SKILL.md 定义：它是一个**扩展（extend）**通用acceptance技能的 LobeHub 项目级技能，将验收流程延伸到机器人渠道这一“surface”。其触发词包括test bot、bot test、test in telegram、test in wechat等。整体仍遵循同一套三阶段流程：
PLAN (Steps 0–2) → EXECUTE (Steps 3–6) → FINISH (Step 7)以及相同的报告与发布管道（result.json→report-init.sh→lh acceptance run ingest … --source agent-testing）。
每个渠道目录都遵循同一套目录契约：一个index.md（含激活、导航、发消息、验证片段）外加一个test-<platform>-bot.sh驱动脚本。Telegram 对应的正是本篇核心文档 index.md 与 test-telegram-bot.sh。
关键前置认知：Telegram 渠道测试是 macOS 专属、无法在无头/云环境运行。因为这类 surface 依赖操作系统级截屏（screencapture，而非 CDP）与原生 macOS App，一旦屏幕录制（TCC）权限缺失或显示器休眠/锁屏/进入屏保，截屏会整张变黑。运行前必须通过录制门槛检查：
./.agents/acceptance/scripts/check-screen-recording.sh # exit 0 = OS capture will work并在整个采集期间用caffeinate -dimsu &（结束后 kill）保持显示器唤醒。
二、环境准备与运行前提
在把任何osascript片段跑起来之前，需要满足以下条件（见 test-telegram-bot.sh 头部注释与共享参考 osascript.md 的 Gotchas 部分）：
- macOS 系统（Telegram 机器人测试不适用于无头环境）；
- Telegram 桌面客户端已安装并登录，且目标机器人已存在于会话列表中；
- 辅助功能（Accessibility）权限：驱动方（Terminal / iTerm / Agent 宿主）需在 系统设置 > 隐私与安全性 > 辅助功能 中被授予访问权限，否则
System Events自动化会被拒绝——首次运行会弹出授权请求； - 屏幕录制权限与屏幕唤醒：OS 级截屏需要 Screen Recording 权限，且显示器不能被锁定/休眠/屏保。
App 名称兼容性细节：Telegram 桌面端在不同安装方式下进程名可能是
Telegram或Telegram Desktop。因此驱动脚本会先探测真实名称（见下文“驱动脚本”），而文档示例统一以Telegram作为 App name / Process name 展示。
三、激活与导航：进入指定机器人的会话
Telegram 桌面端没有像 Discord/Slack 那样的Cmd+K快速切换器，其搜索快捷键是Cmd+F（也可直接点击搜索框）。进入某个机器人会话的标准流程如下（对应 index.md 的 Activate & Navigate 小节）：
# 1. 激活 Telegram 到前台 osascript -e 'tell application "Telegram" to activate' sleep 1 # 2. 用 Cmd+F 打开搜索，输入机器人名，回车选中第一个结果 osascript -e ' tell application "System Events" keystroke "f" using command down delay 0.5 keystroke "MyTestBot" delay 1 key code 36 -- Enter to select end tell ' sleep 2执行中的三个要点：
key code 36是硬件键码的“回车”：无论键盘布局如何都有效（这在共享参考 osascript.md 中被专门强调）。同理，Tab 是key code 48，Esc 是key code 53。- 每个动作之间要加
delay：App 处理 UI 事件需要时间，典型的节奏是搜索后等 0.8–2 秒、回车后再等 2 秒让会话切换完成。 - 更稳妥的导航：正式驱动脚本在
Cmd+F之前会先按一次Escape（key code 53）以清空上一次搜索遗留的输入状态，避免把旧关键词拼进新的搜索词里。
四、发送消息：短消息键入与长消息剪贴板粘贴
4.1 发送短消息（/start等）
导航进入机器人会话后，输入框即获得焦点，此时可以直接键入命令并回车：
osascript -e ' tell application "System Events" keystroke "/start" delay 0.3 key code 36 end tell '这是发起对话最常用的方式——Telegram 机器人通常通过/start初始化会话。
4.2 发送长消息（务必走剪贴板粘贴）
对于长文本、CJK 中文、emoji 或含特殊字符的消息，不要用keystroke逐字符键入。共享参考 osascript.md 明确指出：keystroke对超过约 20 个字符的长文本很慢，且会破坏非 ASCII 字符。正确做法是把内容写入系统剪贴板，再模拟Cmd+V粘贴（对应文档 “Send Long Message” 小节）：
osascript -e ' tell application "Telegram" to activate delay 0.5 set the clipboard to "Tell me about quantum computing in detail" tell application "System Events" keystroke "v" using command down delay 0.3 key code 36 end tell '该“设置剪贴板 → Cmd+V → 回车”的组合是整套 osascript 自动化里最核心的输入模式：它既快又能保证任意字符的完整性。
五、验证回复：等待与截图取证
消息发出后，需要给机器人留出推理与回复的时间，然后通过操作系统级截屏固定证据：
sleep 10 screencapture /tmp/telegram-bot-response.png截图之后，配合视觉模型（Agent 的Read工具）对画面内容做校验即可。这里值得注意（对应 SKILL.md 的 “Screen-recording gate” 与 capture-app-window.sh）：
- 机器人渠道的证据采集走
capture-app-window.sh而不是 CDP，因此屏幕录制权限缺失、显示器休眠、锁屏或处于屏保时，截屏会完全变黑——所以在任何机器人截图前都要先跑check-screen-recording.sh门槛，并通过caffeinate -dimsu &保持屏幕常亮； - 更精确的做法是截取特定 App 窗口而非全屏。脚本先用 Swift +
CGWindowListCopyWindowInfo按进程名找到layer == 0、宽高大于 200 的主窗口 ID，再执行screencapture -l "$WINDOW_ID" -x；若找不到窗口则回退为全屏截取。
六、Telegram Bot HTTP API：免 UI 的程序化补充验证
UI 自动化之外，index.md 还提供了一条纯程序化替代路径——用官方 Bot API 直接向机器人会话推送消息或拉取更新，适用于验证 webhook/回复逻辑而不必操作界面：
# 以机器人身份向会话发送消息（测试 webhook / 回复链路） curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \ -d "chat_id=$CHAT_ID&text=test message" # 拉取最近更新 curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?limit=5" | jq .两条命令分别依赖$TELEGRAM_BOT_TOKEN与$CHAT_ID两个环境变量——前者来自 BotFather 发放的机器人令牌，后者是需要提前确定的会话/用户标识。把这条路径与 UI 自动化结合，可以构成“UI 侧验证端到端体验 + API 侧快速探测/断言”的互补组合。需要说明的是：本文档与仓库不涉及 token 的注册获取细节，该令牌的创建过程在 LobeHub 渠道接入文档 docs/usage/channels/telegram.mdx 中有完整说明。
七、一键驱动脚本：test-telegram-bot.sh
文档最后给出的test-telegram-bot.sh把上述所有步骤封装成一行命令。其完整签名与注释在脚本文件 test-telegram-bot.sh 中，遵循所有 osascript 渠道平台共享的统一接口契约：
./$PLATFORM/test-$PLATFORM-bot.sh $CHANNEL_OR_CONTACT $MESSAGE [$WAIT_SECONDS] [$SCREENSHOT_PATH]对应到 Telegram 的实际调用示例：
./.agents/skills/agent-testing-bot/telegram/test-telegram-bot.sh "MyTestBot" "/start" ./.agents/skills/agent-testing-bot/telegram/test-telegram-bot.sh "MyTestBot" "Hello bot" 30 ./.agents/skills/agent-testing-bot/telegram/test-telegram-bot.sh "GPTBot" "/ask What is AI?" 60 /tmp/my-test.png四个位置参数分别是：<bot_or_chat>（要搜索的机器人用户名或会话名）、<message>（要发送的消息内容）、<wait_seconds>（等待回复秒数，默认 10）、<screenshot_path>（截图输出路径，默认/tmp/telegram-bot-test.png）。
脚本内部完整复现了上文讲解的全部模式，值得逐段理解其工程化细节（脚本启用set -euo pipefail严格模式）：
- 探测 App 名称：依次询问
Telegram与Telegram Desktop哪个能响应，找不到则输出[error] Telegram app not found.并以退出码 1 结束； - 激活：
osascript -e "tell application \"$APP\" to activate"，随后sleep 1； - 搜索导航：先
key code 53（Escape）清除残留状态，再keystroke "f" using command down打开搜索、延迟后键入$BOT（通过"'"$BOT"'"方式安全地把 shell 变量嵌入 AppleScript 字符串）、等待后用回车选择首个结果； - 发送消息：同样走“剪贴板写入
$MESSAGE→Cmd+V→ 回车”的长文本安全路径； - 等待回复：
sleep "$WAIT"； - 截图取证：调用上层通用技能提供的窗口截图脚本
"$SCRIPT_DIR/../../../acceptance/scripts/capture-app-window.sh" "$APP" "$SCREENSHOT"——即只截取 Telegram 窗口并带有屏幕录制黑屏前置检查。
这与文档 SKILL.md 中“每个脚本激活 App、导航到频道/联系人、发送消息、等待、并经由capture-app-window.sh截取结果窗口”的驱动契约描述完全一致。
八、常见坑位与质量建议（macOS 自动化通用经验）
以下要点从共享参考 osascript.md 中提炼，同样适用于 Telegram 渠道测试：
| 现象 | 原因 | 对策 |
|---|---|---|
System Events自动化失败 | 驱动 App 未获辅助功能权限 | 在 系统设置 > 隐私与安全性 > 辅助功能 中授权后重试 |
| 长文本键入异常 / 非 ASCII 乱码 | keystroke对长文与 CJK/emoji 不可靠 | 超过约 20 字符一律改用“剪贴板 +Cmd+V” |
| 截屏整张全黑 | 屏幕录制权限缺失，或屏幕休眠/锁屏/屏保 | 先跑check-screen-recording.sh，再用caffeinate -dimsu &保活 |
| 键盘布局不同导致按键错乱 | 字符按键依赖布局 | 优先用硬件键码：Enter=36、Tab=48、Esc=53 |
entire contents极慢 | 无障碍读取整棵 UI 树开销大 | 复杂界面改用截图 + 视觉工具验证 |
结语
Telegram 机器人测试是 LobeHubagent-testing-bot技能中复用度极高的一个渠道，其模式与同技能下 Discord（Cmd+K快速切换）、Slack（Cmd+K）、微信/Lark/QQ 等渠道共享，核心无非是「激活 → 快捷键导航 → 剪贴板粘贴输入 → 等待 → 窗口截图」五步。开发者若需将这套方法平移到新的机器人平台，可参考仓库的 add-new-bot-platform.mdx 扩展文档，并始终牢记本文强调的两个硬性前提：辅助功能/屏幕录制权限就绪，以及显示器全程保持唤醒。
进一步可研读的仓库文件：
- 机器人渠道总技能与平台矩阵：.agents/skills/agent-testing-bot/SKILL.md
- 共享 macOS 自动化模式与坑位清单：.agents/acceptance/references/osascript.md
- 驱动脚本实现：.agents/skills/agent-testing-bot/telegram/test-telegram-bot.sh
- 窗口截图与黑屏门槛：.agents/acceptance/scripts/capture-app-window.sh 与 .agents/acceptance/scripts/check-screen-recording.sh
- Telegram 渠道接入说明：docs/usage/channels/telegram.mdx
【免费下载链接】lobehub🤯 LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
