Telegram CrabBox 端到端验证技能

一、技能概述

该技能适用于 Telegram PR 审查或 Bug 复现的场景，目标是在真实的 Telegram 用户会话中验证行为，并提供可视化的证据（如录屏 GIF）。它通过 Crabbox 远程桌面运行一个 Telegram Desktop 实例，由 Convex 租赁一个共享的 burner 测试账号，Agent 可以像真实用户一样发送消息、执行命令，并录制整个操作过程。

核心原则：不使用个人账号，不将凭证添加到仓库、提示词或产物包中。

二、核心功能

1. 启动会话（Start）

从 OpenClaw 仓库和待测试的分支启动一个持久的 Crabbox 会话：

proof_cmd="${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}"
"$proof_cmd" start \
  --tdlib-url http://artifacts.openclaw.ai/tdlib-v1.8.0-linux-x64.tgz \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review

该命令会：

• 从 Convex 租赁专属的 telegram-user 凭证

• 恢复 TDLib 和 Telegram Desktop，使用同一用户账号登录

• 从当前 checkout 启动一个模拟的 OpenClaw Telegram SUT（待测系统）

• 在可见的 Linux 桌面中选择配置的 Telegram 聊天

• 以 24fps 开始桌面录制

2. 确定性复现（Mock Response）

对于需要确定性视觉复现的场景，可以将模拟的模型回复写入文件并传递给 start：

"$proof_cmd" start \
  --mock-response-file .artifacts/qa-e2e/telegram-user-crabbox/reply.txt \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review

3. 测试中的操作命令

会话启动后，Agent 可以执行以下操作：

查看消息（view）：通过消息 ID 直接打开群组/话题：

"$proof_cmd" view \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --message-id <id>

此命令直接使用 tg://privatepost，而非 xdg-open，并将 Telegram 窗口调整为 650x1000，便于后续裁剪聊天面板。

发送消息（send）：以真实 Telegram 用户身份发送消息：

"$proof_cmd" send \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --text /status

远程命令（run）：在 Crabbox 上执行任意命令：

"$proof_cmd" run \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  -- bash -lc 'source /tmp/openclaw-telegram-user-crabbox/env.sh && python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py transcript --limit 20 --json'

截图（screenshot）：捕获当前桌面，不结束会话：

"$proof_cmd" screenshot \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json

状态检查（status）：检查租赁状态并获取 WebVNC 连接命令：

"$proof_cmd" status \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json

4. 常用用户驱动命令（User-Driver Commands）

在 Crabbox 上，可以通过 user-driver.py 执行以下操作：

5. 结束会话（Finish）

测试完成后，结束会话并生成产物：

"$proof_cmd" finish \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --preview-crop telegram-window

finish 会：

• 停止录制

• 创建经过运动修剪（motion-trimmed）的 MP4/GIF 产物

• 捕获最终截图和日志

• 释放 Convex 凭证

• 停止本地 SUT 和 Crabbox 租赁

6. 发布证据（Publish）

将证据产物发布到 PR：

"$proof_cmd" publish \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --pr <number> \
  --summary 'Telegram real-user Crabbox session motion GIF'

默认只发布 GIF，不发布日志。除非需要，否则不使用 --full-artifacts。

7. 快速冒烟测试（Quick Smoke）

对于一次性快速检查：

proof_cmd="${OPENCLAW_TELEGRAM_USER_PROOF_CMD:-openclaw-telegram-user-crabbox-proof}" "$proof_cmd" --text /status

这是 start / send / finish 的快捷方式。对于需要多次尝试的 PR 审查或 Issue 复现，推荐使用持久的 held session。

三、主要用途

1. PR 审查中的 Telegram 行为验证
   当 Bot-to-Bot 测试不足以说明问题时，通过真实用户会话验证 Telegram 交互行为并提供可视证据。

2. Bug 复现
   在可控的 Crabbox 环境中复现 Telegram 相关的 Bug，录制完整的操作过程。

3. Before/After 对比证明
   在 main 分支和 PR head 上各运行一次会话，生成对比 GIF，用于 PR 中的可视化对比。

4. Slash 命令和 Bot 交互测试
   通过真实用户发送 /status 等斜杠命令，验证 Bot 的响应行为。

5. 确定性视觉回归测试
   使用 --mock-response-file 固定模型回复，确保每次运行的可视化结果一致。

四、重要原则

1. 不使用个人账号：所有测试使用 Convex 租赁的共享 burner 账号

2. 凭证不出现在仓库、提示词或产物包中

3. Agent 可以保持会话活跃数分钟：用于多次尝试、使用 WebVNC 观察、检查记录，直到行为被理解

4. View 命令不按 Escape：Escape 会关闭选中的聊天

5. 底部行为关键：深度链接到最新消息会让 Telegram 固定在底部，后续消息会实时出现在录制中

6. 发布时只附有用的产物：默认只发布 GIF，不发布日志、凭证、TDLib 数据库或原始会话存档

7. 异常后清理：如果会话文件存在且凭证可能仍被租赁，先用 finish 清理后再重试