Mantis

​

目标

• 使用用户看到的相同传输形态，从 GitHub issue 或 PR 中复现缺陷。
• 在应用修复之前，针对基线 ref 捕获 before 工件。
• 在应用修复之后，针对候选 ref 捕获 after 工件。
• 尽可能使用确定性 oracle，例如 Discord REST reaction 读取或频道转录检查。
• 当缺陷具有可见 UI 表现时捕获截图。
• 既可从 agent 控制的 CLI 在本地运行，也可从 GitHub 远程运行。
• 在登录、浏览器自动化或 provider 认证卡住时，保留足够的机器状态以便通过 VNC 救援。
• 当运行被阻塞、需要人工 VNC 帮助或完成时，向运营者 Discord 频道发布简洁状态。

​

非目标

• Mantis 不是单元测试的替代品。Mantis 运行在理解修复之后，通常应转化为更小的回归测试。
• Mantis 不是常规的快速 CI 门禁。它更慢，使用真实凭据，仅用于直播环境很重要的缺陷。
• Mantis 不应在正常操作中依赖人工。手动 VNC 是救援路径，而不是正常路径。
• Mantis 不会在工件、日志、截图、Markdown 报告或 PR 评论中存储原始密钥。

​

所有权

• OpenClaw 负责场景运行时、传输适配器、证据 schema，以及 pnpm openclaw qa mantis 下的本地 CLI。
• QA Lab 负责实时传输 harness 组件、浏览器捕获辅助工具和工件写入器。
• Crabbox 在需要远程 VM 时负责预热 Linux 机器。
• GitHub Actions 负责远程工作流入口和工件保留。
• ClawSweeper 负责 GitHub 评论路由：解析维护者命令、调度工作流，并发布最终 PR 评论。
• 当场景需要 agentic 设置、调试或卡住状态报告时，OpenClaw agents 通过 Codex 驱动 Mantis。

​

命令形式

pnpm openclaw qa mantis discord-smoke \
  --output-dir .artifacts/qa-e2e/mantis/discord-smoke

pnpm openclaw qa mantis run \
  --transport discord \
  --scenario discord-status-reactions-tool-only \
  --baseline origin/main \
  --candidate HEAD \
  --output-dir .artifacts/qa-e2e/mantis/local-discord-status-reactions

pnpm openclaw qa mantis run \
  --transport discord \
  --scenario discord-thread-reply-filepath-attachment \
  --baseline <bug-ref> \
  --candidate <fix-ref> \
  --output-dir .artifacts/qa-e2e/mantis/local-discord-thread-attachment

pnpm openclaw qa mantis desktop-browser-smoke \
  --output-dir .artifacts/qa-e2e/mantis/desktop-browser

• --lease-id <cbx_...> 或 OPENCLAW_MANTIS_CRABBOX_LEASE_ID 复用一个已预热的 desktop。
• --browser-url <url> 更改可见浏览器打开的页面。
• --html-file <path> 在可见浏览器中渲染仓库本地 HTML 工件。Mantis 使用它通过真实的 Crabbox desktop 捕获生成的 Discord 状态 reaction 时间线。
• --browser-profile-dir <remote-path> 复用远程 Chrome user-data-dir，以便持久化的 Mantis desktop 在多次运行之间保持登录状态。可用于长期存在的 Discord Web viewer profile。
• --browser-profile-archive-env <name> 在启动浏览器前，从指定环境变量中恢复一个 base64 编码的 .tgz Chrome user-data-dir 归档。可用于 Discord Web 这类已登录 witness。默认环境变量是 OPENCLAW_MANTIS_BROWSER_PROFILE_TGZ_B64。
• --video-duration <seconds> 控制 MP4 捕获时长。对于需要时间稳定下来的慢速已登录 web 应用，使用更长时长。
• --keep-lease 或 OPENCLAW_MANTIS_KEEP_VM=1 会在成功时保持新创建的 passing lease 打开，以便进行 VNC 检查。若运行失败且已创建 lease，则默认保留 lease，以便操作员可以重新连接。
• --class、--idle-timeout 和 --ttl 用于调整机器规格和 lease 生命周期。

pnpm openclaw qa mantis slack-desktop-smoke \
  --output-dir .artifacts/qa-e2e/mantis/slack-desktop \
  --gateway-setup \
  --scenario slack-canary \
  --keep-lease

• OPENCLAW_QA_SLACK_CHANNEL_ID
• OPENCLAW_QA_SLACK_DRIVER_BOT_TOKEN
• OPENCLAW_QA_SLACK_SUT_BOT_TOKEN
• OPENCLAW_QA_SLACK_SUT_APP_TOKEN
• 用于远程 model 线路的 OPENCLAW_LIVE_OPENAI_KEY。如果本地只设置了 OPENAI_API_KEY，Mantis 会在调用 Crabbox 之前将其映射为 OPENCLAW_LIVE_OPENAI_KEY， 以便 Crabbox 的 OPENCLAW_* 环境变量转发将其带入 VM。

• --lease-id <cbx_...> 重新在一台操作员已通过 VNC 登录过 Slack Web 的机器上运行。
• --gateway-setup 在 VM 中启动一个持久的 OpenClaw Slack gateway，而不仅仅是运行 bot-to-bot QA 线路。
• --keep-lease 在成功后保持 gateway VM 打开以供 VNC 检查；--no-keep-lease 会在收集工件后将其停止。
• --slack-url <url> 打开指定的 Slack Web URL。若未提供，Mantis 会在 SUT bot token 可用时，根据 Slack auth.test 推导出 https://app.slack.com/client/<team>/<channel>。
• --slack-channel-id <id> 控制 gateway setup 使用的 Slack channel allowlist。
• OPENCLAW_MANTIS_SLACK_BROWSER_PROFILE_DIR 控制 VM 内持久化的 Chrome profile。默认值为 $HOME/.config/openclaw-mantis/slack-chrome-profile，因此手动的 Slack Web 登录会在同一 lease 的重复运行之间保留。
• --credential-source convex --credential-role ci 使用共享凭据池，而不是直接使用 Slack 环境 token。
• --provider-mode、--model、--alt-model 和 --fast 会透传到 Slack live 线路。

• baseline_ref：预期复现仅队列行为的 ref。
• candidate_ref：预期展示 queued -> thinking -> done 的 ref。

pnpm openclaw qa mantis telegram-desktop-builder \
  --credential-source convex \
  --credential-role maintainer \
  --keep-lease

• --lease-id <cbx_...> 在操作员已经登录 Telegram Desktop 的 VM 上重新运行。
• --telegram-profile-archive-env <name> 从该环境变量读取 base64 编码的 .tgz Telegram Desktop profile 归档，并在启动前恢复它。
• --telegram-profile-dir <remote-path> 控制远程 Telegram Desktop profile 目录。默认值为 $HOME/.local/share/TelegramDesktop。
• --no-gateway-setup 会安装并打开 Telegram Desktop，但不配置 OpenClaw。
• --credential-source convex --credential-role ci 使用共享凭据 broker，而不是直接使用 Telegram 环境 token。

{
  "schemaVersion": 1,
  "id": "discord-status-reactions",
  "title": "Mantis Discord Status Reactions QA",
  "summary": "用于 PR 评论的人类可读顶部摘要。",
  "scenario": "discord-status-reactions-tool-only",
  "comparison": {
    "baseline": { "sha": "...", "status": "fail", "expected": "queued-only" },
    "candidate": { "sha": "...", "status": "pass", "expected": "queued -> thinking -> done" },
    "pass": true
  },
  "artifacts": [
    {
      "kind": "timeline",
      "lane": "baseline",
      "label": "Baseline queued-only",
      "path": "baseline/timeline.png",
      "targetPath": "baseline.png",
      "alt": "Baseline Discord timeline",
      "width": 420
    }
  ]
}

• timeline：确定性的场景截图，通常是 before/after。
• desktopScreenshot：VNC/browser desktop 截图。
• motionPreview：从桌面录制生成的内联动画 GIF。
• motionClip：去除静态前导和尾段的 motion-trimmed MP4。
• fullVideo：用于深入检查的完整 MP4 录制。
• metadata：JSON/log sidecar。
• report：Markdown 报告。

• MANTIS_ARTIFACT_R2_ACCESS_KEY_ID
• MANTIS_ARTIFACT_R2_SECRET_ACCESS_KEY
• MANTIS_ARTIFACT_R2_BUCKET
• MANTIS_ARTIFACT_R2_ENDPOINT
• MANTIS_ARTIFACT_R2_REGION
• MANTIS_ARTIFACT_R2_PUBLIC_BASE_URL

@openclaw-mantis discord status reactions

@openclaw-mantis discord status reactions baseline=origin/main candidate=HEAD

@openclaw-mantis telegram
@openclaw-mantis telegram scenario=telegram-status-command
@openclaw-mantis telegram scenarios=telegram-status-command,telegram-mentioned-message-reply

@clawsweeper mantis discord discord-status-reactions-tool-only
@clawsweeper verify e2e discord

​

运行生命周期

1. 获取凭据。
2. 分配或复用一台虚拟机（VM）。
3. 当场景需要 UI 证据时，准备桌面/浏览器配置文件。
4. 为基线 ref 准备一个干净的检出版本。
5. 仅安装该场景所需的依赖并执行构建。
6. 启动一个带有隔离状态目录的子 OpenClaw Gateway。
7. 配置实时传输、provider、模型和浏览器配置文件。
8. 运行场景并捕获基线证据。
9. 停止 gateway 并保留日志。
10. 在同一台 VM 上准备 candidate ref。
11. 运行相同的场景并捕获 candidate 证据。
12. 比较 oracle 结果和视觉证据。
13. 写入 Markdown、JSON、日志、截图，以及可选的 trace 工件。
14. 上传 GitHub Actions artifacts。
15. 发布一条简洁的 PR 或 Discord 状态消息。

• 复现了缺陷：基线按预期方式失败。
• harness 失败：环境设置、凭据、Discord API、浏览器或 provider 在 bug oracle 具有意义之前失败。

​

Discord 最小可行产品

• 它在 Discord 中以触发消息上的 reaction 形式可见。
• 它通过 Discord 消息 reaction 状态具有很强的 REST oracle。
• 它会涉及真实的 OpenClaw Gateway、Discord bot 认证、消息分发、源回复投递模式、状态 reaction 状态以及模型轮次生命周期。
• 它足够聚焦，能够确保第一个实现足够严谨。

id: discord-status-reactions-tool-only
transport: discord
baseline:
  expect:
    reproduced: true
candidate:
  expect:
    fixed: true
config:
  messages:
    ackReaction: "👀"
    ackReactionScope: "group-mentions"
    groupChat:
      visibleReplies: "message_tool"
    statusReactions:
      enabled: true
      timing:
        debounceMs: 0
discord:
  requireMention: true
  notifyChannel: operator-notify
evidence:
  rest:
    messageReactions: true
  browser:
    screenshotMessageRow: true

pnpm openclaw qa discord \
  --scenario discord-status-reactions-tool-only \
  --provider-mode live-frontier \
  --model openai/gpt-5.4 \
  --alt-model openai/gpt-5.4 \
  --fast \
  --output-dir .artifacts/qa-e2e/mantis/discord-status-reactions-candidate

​

现有 QA 组件

• pnpm openclaw qa discord 已经运行了一个带 driver 和 SUT bots 的 live Discord 通道。
• live transport runner 已经在 .artifacts/qa-e2e/ 下写入报告和 observed-message 工件。
• Convex credential lease 已经为共享的 live transport 凭据提供了独占访问。
• 浏览器控制服务已经支持截图、snapshot、headless managed profiles 和远程 CDP profiles。
• QA Lab 已经拥有用于 transport 形态测试的 debugger UI 和 bus。

​

证据模型

.artifacts/qa-e2e/mantis/<run-id>/
  mantis-report.md
  mantis-summary.json
  baseline/
    summary.json
    discord-message.json
    screenshot-message-row.png
    gateway-debug/
  candidate/
    summary.json
    discord-message.json
    screenshot-message-row.png
    gateway-debug/
  comparison.json
  run.log

• 已测试的 refs 和 SHAs
• 传输和场景 id
• 机器 provider 和机器 id 或 lease id
• 不包含密钥值的凭据来源
• 基线结果
• candidate 结果
• 缺陷是否在基线上复现
• candidate 是否修复了它
• 工件路径
• 已净化的设置或清理问题

​

浏览器和 VNC

• 无头自动化：CI 的默认模式。Chrome 启用 CDP 运行，并且 Playwright 或 OpenClaw 浏览器控制会捕获截图。
• VNC 救援：当登录、MFA、Discord 反自动化， 或可视化调试需要人工介入时，在同一台 VM 上启用。

• 运行 id
• 场景 id
• 机器提供商
• 产物目录
• 如可用，VNC 或 noVNC 连接说明
• 简短的阻塞文本

​

机器

• Linux，安装带桌面能力的 Chrome 或 Chromium
• 用于浏览器自动化的 CDP 访问
• 用于救援的 VNC 或 noVNC
• Node 22 和 pnpm
• OpenClaw 检出和依赖缓存
• 使用 Playwright 时的 Playwright Chromium 浏览器缓存
• 足够的 CPU 和内存，用于一个 OpenClaw Gateway、一个浏览器和一次模型运行
• 可出站访问 Discord、GitHub、模型提供商以及凭据代理

​

密钥

• OPENCLAW_QA_DISCORD_MANTIS_BOT_TOKEN
• OPENCLAW_QA_DISCORD_DRIVER_BOT_TOKEN
• OPENCLAW_QA_DISCORD_SUT_BOT_TOKEN
• OPENCLAW_QA_DISCORD_GUILD_ID
• OPENCLAW_QA_DISCORD_CHANNEL_ID
• OPENCLAW_QA_DISCORD_NOTIFY_CHANNEL_ID
• OPENCLAW_QA_REDACT_PUBLIC_METADATA=1 用于公开的 GitHub 产物上传
• OPENCLAW_QA_CONVEX_SITE_URL
• OPENCLAW_QA_CONVEX_SECRET_CI
• OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR
• OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR_TOKEN

• Discord bot token
• 提供商 API key
• 浏览器 cookie
• 认证配置文件内容
• VNC 密码
• 原始凭据载荷

​

GitHub 工件和 PR 评论

Mantis Discord 状态反应 QA

摘要：Mantis 重新运行了所报告的 Discord 状态反应 bug，分别针对已知的
错误基线和候选修复进行验证。基线复现了该 bug，而候选方案展示了预期的 queued -> thinking -> done 序列。

- 场景：`discord-status-reactions-tool-only`
- 运行：<workflow run link>
- 产物：<artifact link>
- 基线：`<status>` at `<sha>`
- 候选：`<status>` at `<sha>`

| 基线                | 候选                |
| ------------------- | ------------------- |
| <inline screenshot> | <inline screenshot> |

​

私有部署说明

​

添加场景

• id 和标题
• 传输方式
• 所需凭据
• 基线 ref 策略
• 候选 ref 策略
• OpenClaw 配置补丁
• 设置步骤
• 刺激
• 期望的基线 oracle
• 期望的候选 oracle
• 视觉捕获目标
• 超时预算
• 清理步骤

• 对于 reaction 类 bug，使用 Discord reaction 状态
• 对于 threading 类 bug，使用 Discord 消息引用
• 对于 Slack bug，使用 Slack thread ts 和 reaction API 状态
• 对于 email bug，使用 email message id 和 headers
• 当 UI 是唯一可靠可观测项时，使用浏览器截图

​

Provider 扩展

• Slack：reactions、threads、应用提及、模态框、文件上传。
• Email：使用 gog 进行 Gmail 认证和消息线程化，当 connector 不够用时。
• WhatsApp：QR 登录、重新识别、消息投递、媒体、reactions。
• Telegram：群组提及门控、命令、reactions（如可用）。
• Matrix：加密房间、线程或回复关系、重启恢复。

​

未决问题

• 当现有的 Mantis bot 被重用时，哪个 Discord bot 应该作为 driver，哪个应该作为 SUT？
• 首个阶段里，observer 浏览器登录应使用真人 Discord 账号、测试账号，还是仅使用 bot 可读的 REST 证据？
• GitHub 应该将 Mantis 用于 PR 的 artifacts 保留多久？
• ClawSweeper 应该何时自动推荐 Mantis，而不是等待维护者命令？
• 对于公开 PR，上传前是否应先对截图进行脱敏或裁剪？