LobeHub 飞书/Lark Bot 端到端测试指南：用 agent-testing-bot 在 macOS 上做真实客户端自动验收

LobeHub 飞书/Lark Bot 端到端测试指南用 agent-testing-bot 在 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/lobehubLobeHub 是一个把 AI Agent 组织成 7×24 团队运行的产品其中飞书中国大陆/Lark海外版是 Agent 对外输出的重要 Bot 消息通道。要证明Agent 能在飞书/Lark 里被真实用户找到、收到消息、并正确回复仅靠 Web/CLI 表面验证是不够的——唯一可靠的方式是驱动真实的 macOS 原生客户端完成一次端到端收发。本文以仓库内.agents/skills/agent-testing-bot/lark/index.md这份技能文档为主线系统讲解如何在 macOS 上通过osascriptAppleScript自动化驱动 Lark/飞书客户端激活应用、用 CmdK 快速搜索定位会话、粘贴发送测试消息、再用系统级截图留存回复证据并把证据接入 LobeHub 的 acceptance 验收与报告管线。读完你将掌握一套可复制、可落地的Bot 通道真机验收脚本方法论以及国内/海外双命名飞书vsLark、CJK 中文输入、屏幕录制权限等关键坑的规避方案。这套技能解决的问题Bot 通道为什么必须真机端到端验证在 LobeHub 的验收体系中不同的变更范围对应不同的验证表面。.agents/skills/agent-testing-bot/SKILL.md中给出了明确的分工判断变更范围验证表面原因Bot 通道Discord / WeChat / Lark / QQ / …通过 osascript/bridge 驱动原生 App这是唯一能端到端真实跑通该通道的方式也就是说当被测行为落在某个 Bot 消息通道上时只有驱动真实客户端才能验证用户在聊天软件里真的能召唤 Agent 并收到回复这一用户体验。CLI / Web / Electron 的变更则走通用 acceptance 技能的其他表面不适用本方案。agent-testing-bot 技能扩展了通用 acceptance 技能两者在同一仓库内相邻安装并不替代其核心流程。验收仍遵循同样的三段式流程PLAN步骤 0–2→ EXECUTE步骤 3–6→ FINISH步骤 7以及同一套报告 发布管线result.json→report-init.sh→lh acceptance run ingest … --source agent-testing。验收的通用规则目标锚定、动态日志、阶段一审批门、报告格式、teardown见 .agents/skills/acceptance/SKILL.mdLobeHub 专属的环境 / 鉴权 / 探针适配则记录在 .agents/acceptance/PROJECT.md 中。每个平台目录下都有一份index.md激活、导航、发送消息、验证的证据片段和一个test-平台-bot.sh驱动脚本。本篇文章聚焦其中 Lark/飞书 平台指南.agents/skills/agent-testing-bot/lark/index.md驱动脚本.agents/skills/agent-testing-bot/lark/test-lark-bot.sh背景补充LobeHub 与 Lark 的通道集成本身创建企业自建应用、配置权限、WebSocket/Webhook 双模式接入等不在本文范围属于产品接入侧本文只讨论已经接入后如何自动化验收 Bot。若需了解通道接入可参考 Lark 通道接入文档 与 飞书通道接入文档。一次典型验收的完整工作流在 Lark/飞书 上验证一个 Bot本质是四步激活应用 → 导航到目标会话 → 发送消息 → 等待并截图验证回复下面按 lark/index.md 的核心片段逐步拆解。激活与导航唤醒应用并通过 CmdK 定位会话Lark以及国内版飞书是 macOS 原生应用自动化前首先要把它切到前台。由于同一应用在不同地区/语言环境下进程名不同海外版叫Lark中国大陆版叫飞书官方写法先用osascript尝试激活Lark失败则回退激活飞书——脚本因此能做到双命名自动探测# Activate Lark (auto-detects Lark or 飞书) osascript -e tell application Lark to activate 2 /dev/null \ || osascript -e tell application 飞书 to activate sleep 1 # Quick Switcher / Search (CmdK) osascript -e tell application System Events to keystroke k using command down sleep 0.5 osascript -e set the clipboard to bot-testing tell application System Events keystroke v using command down delay 1.5 key code 36 -- Enter end tell sleep 2这段脚本有三个值得注意的设计点用CmdK唤起快捷搜索/快速切换器。飞书/Lark 的 Quick Switcher 与 Discord、Slack 一致同属 CmdK 家族输入会话名后回车即进入第一个匹配会话。会话名可能是中文先写进剪贴板再以CmdV粘贴而不是用keystroke逐字符敲入。原因见下文 osascript 共享模式keystroke会把非 ASCII 文本弄乱而剪贴板粘贴对 CJK 完全友好。每个 UI 动作之间都有sleep/delay。原生应用处理 UI 事件需要时间没有间隔的连续注入会丢失事件。发送消息到 Bot剪贴板粘贴 Enter导航完成、输入框聚焦后同样的剪贴板→粘贴→回车手法用于发送正文。消息内容可能包含中文甚至提及语法如MyBot所以仍走剪贴板通道osascript -e set the clipboard to MyBot help me with this task tell application System Events keystroke v using command down delay 0.3 key code 36 -- Enter end tell 注意注释点Enter 默认即发送飞书/Lark 无需额外组合键key code 36是硬件键盘码与键盘布局无关比 keystroke 字符串 \n 更可靠。验证回复等待 系统级截图发送后给 Agent 留出推理与回复时间再用 macOS 的screencapture截取整个屏幕作为证据sleep 10 screencapture /tmp/lark-bot-response.png这里sleep 10是默认的等待窗口——如果 Agent 处理较慢例如带工具调用或检索的复杂任务可以把等待时间放大到 30s、60s。产物 PNG 由验收方用视觉读取Read 工具来确认回复确实到达了真实客户端。从散装命令到驱动脚本test-lark-bot.sh上面四条命令每一步都要手敲显然不可复用。因此技能把整套流程封装成了带参数契约的 bash 驱动脚本 test-lark-bot.sh。统一调用契约在 agent-testing-bot 技能内每个基于 osascript 的平台脚本共享同一套接口见 SKILL.md./$PLATFORM/test-$PLATFORM-bot.sh $CHANNEL_OR_CONTACT $MESSAGE [$WAIT_SECONDS] [$SCREENSHOT_PATH]对 Lark/飞书展开即为./.agents/skills/agent-testing-bot/lark/test-lark-bot.sh bot-testing MyBot hello ./.agents/skills/agent-testing-bot/lark/test-lark-bot.sh bot-testing Help me with this 30 ./.agents/skills/agent-testing-bot/lark/test-lark-bot.sh MyBot /ask Tell me a joke 60 /tmp/my-lark-test.png参数语义与脚本头注释一致参数含义默认值chat第 1 个必填要搜索并进入的会话/联系人名用于 CmdK 搜索无message第 2 个必填发送给 Bot 的消息正文无[wait_seconds]第 3 个可选等待 Bot 回复的时间10[screenshot_path]第 4 个可选结果截图输出路径/tmp/lark-bot-test.png脚本内部以set -euo pipefail严格模式运行并通过${1:?Usage: ...}对必填参数做了缺参即报错的保护。核心实现逻辑脚本最关键的一段是应用名自动探测——它顺序询问两个名字只有两者都不存在才报错退出# Detect app name — Lark or 飞书 APP if osascript -e tell application Lark to name /dev/null; then APPLark elif osascript -e tell application 飞书 to name /dev/null; then APP飞书 else echo [error] Lark/飞书 app not found. Install Lark or 飞书. exit 1 fi随后按既定顺序执行osascript ... to activate激活应用 → 发送CmdK唤起 Quick Switcher →把会话名写剪贴板后CmdV粘贴此处支持中文会话名→ 延迟 1.5s 后key code 36回车选中第一个结果 → 等待 2s 让会话加载 →再把消息正文写剪贴板粘贴并回车发送→sleep $WAIT等待回复 → 调用截图工具留存证据echo [$APP] Capturing screenshot... $SCRIPT_DIR/../../../acceptance/scripts/capture-app-window.sh $APP $SCREENSHOT注意最后一步驱动脚本不直接全屏截图而是委托给 .agents/acceptance/scripts/capture-app-window.sh后者通过 Swift CGWindowList按进程名kCGWindowOwnerName找到目标 App 的窗口 ID要求窗口层kCGWindowLayer 0且尺寸 200×200再用screencapture -l windowID -x只截取该窗口若找不到窗口则回退全屏截图。这比整屏截图更聚焦、证据更干净。osascript 共享模式与前置条件Lark 只是 agent-testing-bot 技能中的一族所有 osascript 平台共享同一套通用 macOS 自动化资产——.agents/acceptance/references/osascript.md。理解它才能安全地扩展或排障。常用原语速查操作命令片段激活应用osascript -e tell application AppName to activate逐字符输入短文本osascript -e tell application System Events to keystroke Hello world按回车osascript -e tell application System Events to key code 36按 Tab / Esckey code 48/key code 53剪贴板粘贴长/非 ASCII 文本先set the clipboard to …再keystroke v using command down快捷键keystroke k using command downCmdK等可加多修饰键截图screencapture /tmp/x.png全屏/-i区域/-l $WINDOW_ID指定窗口为什么 CJK 一定要走剪贴板共享文档的 Gotchas 直接点明两个易错点keystroke对长文本慢——超过约 20 个字符就应改用剪贴板粘贴CmdVkeystroke会弄坏非 ASCII 字符——CJK、emoji、特殊符号一律走剪贴板。这与 lark/index.md 中Always use clipboard paste for CJK characters的专项提示完全一致也是飞书/Lark 这类中文重度场景最容易踩的坑。前置条件辅助功能Accessibility权限System Events自动化要求驱动方 App终端 / iTerm / Agent 宿主在系统设置 → 隐私与安全性 → 辅助功能中拥有访问权限首次运行会弹窗申请需手动放行。另外被驱动的原生 AppLark/飞书本身必须已启动并完成登录——脚本只负责驱动不负责登录。屏幕录制门禁避免产出一张全黑截图Bot 通道证据走的是操作系统级screencapture经 capture-app-window.sh不是 CDP。而 macOS 系统截图在两种情况下会产出完全全黑的图片驱动 App 缺少屏幕录制Screen Recording / TCC权限显示器处于睡眠 / 锁屏 / 屏保状态权限正常但没有可亮的画面。全黑产物极易被误判为真实捕获因此每次 Bot 类截屏前都应先跑门禁脚本 .agents/acceptance/scripts/check-screen-recording.sh./.agents/acceptance/scripts/check-screen-recording.sh # exit 0 OS capture will work ./.agents/acceptance/scripts/check-screen-recording.sh --json # 机器可读输出该脚本的退出码语义从源码注释可直接确认退出码含义处理建议0OS 截屏可用权限已授予且抓到非黑帧非 macOS 平台也返回 0OS 捕获不适用改用 CDP 证据直接继续3屏幕录制权限未授予到 系统设置 → 隐私与安全性 → 屏幕录制 打开对应 App然后彻底退出并重启该 AppTCC 仅在重新启动后生效4权限正常但抓到全黑帧唤醒/解锁显示器、退出屏保或重启刚授权但未重启的 App 后重跑2无法判定缺少 screencapture/工具链手动核对系统设置中的屏幕录制授权实现上它做了两层探测先用CGPreflightScreenCaptureAccess()无弹窗检查 TCC 权限缺 clang 时回退swift再真实截一帧并缩小为 16×16 的 BMP、用 Python 找最亮像素——最亮通道值 12/255 即判定整屏接近全黑。门禁之外还要保证整个捕获会话期间显示器不熄屏。官方推荐的姿势是在整轮测试期间保持唤醒caffeinate -dimsu # 全程保持显示器唤醒结束后 kill这条约束也解释了技能的一个硬性边界Bot 通道是 macOS-only 的无法在无头环境/云端运行。把截图变成合格验收证据接入 acceptance 报告管线能截到图只是第一步。在 LobeHub 的验收体系里证据必须进入报告管线才算数。agent-testing-bot 沿用了 acceptance 技能的发布流程见 .agents/skills/acceptance/SKILL.md 与 PROCESS.mdresult.json assets/截图 → report-init.sh 汇总 → lh acceptance run ingest … --source agent-testing有两个验收硬规则在 Bot 通道测试中尤其相关程序性门禁永远不能充当验收检查项。单测/集成测试/类型检查/lint/构建通过都不能作为 check——它们只能作为一行叙述。Bot 截图要证明的是用户体验层面的结果用户在飞书/Lark 中 Bot 后真的收到了符合预期的回复。截图 视觉读取正是把程序跑过了升级为人可验收的证据形态。轮次round不可变。发布后的轮次是永久记录代码变更后的复验必须开新轮次而不是在旧轮次里重复提交。截图证据的具体收集入口有两个层级驱动脚本默认走capture-app-window.sh做单窗口捕获若想手动截取交互式区域或指定窗口可使用 osascript 参考文档中的screencapture变体-i区域选择、-l windowID指定窗口。为获取某 App 窗口 ID可执行osascript -e tell application System Events tell process AppName get id of window 1 end tell end tell 若需更长时长的动态过程如 Bot 回复期间的屏幕录制而非单帧技能还提供了通用录制工具链 .agents/acceptance/references/record-app-screen.md。Lark 特有注意点与平台对照回到 lark/index.md 末尾总结的专项注意点应用名随地区变化国际版为Lark中国大陆版为飞书——脚本自动探测因此两个版本的用户可共用同一脚本导航用CmdK快捷搜索与 Discord/Slack 一致而非 Telegram/微信/QQ 的CmdFEnter 默认发送消息中文CJK一律走剪贴板粘贴。各平台的 Quick Switcher 差异在 SKILL.md 的平台表中一目了然平台指南Quick SwitcherDiscorddiscord/index.mdCmdKSlackslack/index.mdCmdKTelegramtelegram/index.mdCmdFWeChat / 微信wechat/index.mdCmdFLark / 飞书lark/index.mdCmdKQQqq/index.mdCmdFiMessageimessage/index.mdbridge不走 osascriptiMessage 是唯一例外它不通过 osascript而是走 BlueBubbles bridge因此异步任务分发路径、截图前的 TCC 门禁等处理上与其他平台略有差异。排障清单Bot 验收常见问题一览把以上要点收敛成一份可直接对照的排障清单截图全黑且 exit 0 却失败先跑check-screen-recording.shexit 3 补 TCC 屏幕录制权限并完全重启 Appexit 4 唤醒/解锁显示器并caffeinate -dimsu防熄屏。MyBot或中文消息变成乱码确认走的是剪贴板粘贴而非keystrokekeystroke对非 ASCII 不可靠。找不到会话/选错会话检查 CmdK 后是否给了足够延迟脚本用 delay 1.5s sleep 2s回车选中的是第一个结果会话名需足够精确。App 未激活 / 脚本报 app not found确认本地安装的是Lark还是飞书命名、已登录脚本对两者顺序探测均失败才退出。等待时间不足导致截图无回复把第三个参数wait_seconds从默认 10 放大到 30/60直到 Agent 完成推理。辅助功能权限问题导致 keystroke 无响应在 系统设置 → 隐私与安全性 → 辅助功能 中放行驱动终端。截图窗口不对/太大capture-app-window.sh 要求进程名与 Activity Monitor 中一致如Lark/飞书且按层 0、大于 200×200规则筛窗匹配失败会回退全屏。遵循以上流程即可把飞书/Lark 里 Bot 能否正常对话从手工点按变为可重复、可留证、可汇入 acceptance 报告管线的 macOS 自动化验收为 LobeHub 各消息通道的持续质量保障提供坚实证据。【免费下载链接】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），仅供参考