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 那样的CmdK快速切换器其搜索快捷键是CmdF也可直接点击搜索框。进入某个机器人会话的标准流程如下对应 index.md 的 Activate Navigate 小节# 1. 激活 Telegram 到前台 osascript -e tell application Telegram to activate sleep 1 # 2. 用 CmdF 打开搜索输入机器人名回车选中第一个结果 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 48Esc 是key code 53。每个动作之间要加delayApp 处理 UI 事件需要时间典型的节奏是搜索后等 0.8–2 秒、回车后再等 2 秒让会话切换完成。更稳妥的导航正式驱动脚本在CmdF之前会先按一次Escapekey 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 字符。正确做法是把内容写入系统剪贴板再模拟CmdV粘贴对应文档 “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 该“设置剪贴板 → CmdV → 回车”的组合是整套 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_IDtexttest message # 拉取最近更新 curl -s https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?limit5 | 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 53Escape清除残留状态再keystroke f using command down打开搜索、延迟后键入$BOT通过$BOT方式安全地把 shell 变量嵌入 AppleScript 字符串、等待后用回车选择首个结果发送消息同样走“剪贴板写入$MESSAGE→CmdV→ 回车”的长文本安全路径等待回复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 字符一律改用“剪贴板 CmdV”截屏整张全黑屏幕录制权限缺失或屏幕休眠/锁屏/屏保先跑check-screen-recording.sh再用caffeinate -dimsu 保活键盘布局不同导致按键错乱字符按键依赖布局优先用硬件键码Enter36、Tab48、Esc53entire contents极慢无障碍读取整棵 UI 树开销大复杂界面改用截图 视觉工具验证结语Telegram 机器人测试是 LobeHubagent-testing-bot技能中复用度极高的一个渠道其模式与同技能下 DiscordCmdK快速切换、SlackCmdK、微信/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.shTelegram 渠道接入说明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），仅供参考