用 Momentic mo CLI 驱动云端自主 QA…

当需要通过 Momentic 的 mo CLI 启动、跟进、控制云端自主 QA 代理 Mo 来测试 Web 应用、导出报告或修复其发现的缺陷时使用。

适用场景

解决思路

1. 运行 `mo version` 检查版本；若失败或提示更新，阅读 Installation 参考文档。
2. 假设认证已配置；若操作命令报认证错误，阅读 Authentication 参考文档。
3. 使用对话中隐含的目标；若不清楚，询问用户要测试什么。对本地或私有目标，阅读 Tunneling 参考文档并保留其 `tunnel_id`；对公开目标，使用其精确 URL。
4. 编写 QA brief 作为完整输入，包含：1) Target URL（含变更影响的精确路径和查询参数）；2) Expected behavior（用产品语言说明改了什么、现在应如何表现）；3) Sign-in instructions（登录方式和测试账号）；4) Test data rules（Mo 可创建什么、不可触碰什么）；5) Out-of-bounds actions（删除、支付、邮件、生产数据、批量操作等破坏性动作；若 brief 邀请，Mo 可能执行破坏性动作）；6) Acceptance criteria（判定通过或失败的检查项）。用用户请求、任务规格和仓库上下文填充 brief，陈述合理假设；当缺失信息实质改变范围或需要你没有的凭据/权限时询问。
5. 在调用 CLI 前写好 brief，然后作为单个带引号参数传入：`brief=$(cat <<'EOF' ... EOF)`，再执行 `session_json=$(mo start "$brief")`，用 `jq -r .sessionId` 和 `jq -r .webUrl` 提取 `session_id` 和 `web_url`。启动会提前返回，必须保留这两个值：后续命令都需要 `session_id`，用户可通过 `web_url` 观看或加入。
6. 仅在需要时使用启动设置：`--tunnel "$tunnel_id"` 连接已配置隧道；`--momentic-mode` 使用更智能的 Momentic 浏览器工具（省略则用更快的 Playwright MCP）；`--max-concurrency <count>` 限制并发子代理（默认省略，仅当用户在会话开始前指定限制时传入）。这些设置在会话启动时选定。
7. 并发数无法在已有会话上更改。较低值可减少并行模型和浏览器负载，有助于 Mo 遇到提供商速率限制或压垮本地目标服务器时。若发生这两种情况，停止当前会话并以较低的 `--max-concurrency` 启动新会话；不要在已启动的聊天中发送较低限制来修复。
8. 用 `mo status "$session_id"` 轮询活动会话的状态、web URL、缺陷和测试用例计数；需要最新消息或发现摘要时加 `--full`。在总结 QA 结果或调查缺陷前，阅读 Reports 参考文档以下载并检查详细发现和复现视频。报告缺陷前，检查产品或 brief 的预期行为是否已过时。
9. 需要等待输出或获取转录和待处理输入时使用 `read`，优先使用 30-60 秒的有界读取以保持调用方响应：`mo read "$session_id" --from start --timeout 45s --json`。用 `--from start` 可靠轮询，它会重放可见转录，自动化时需去重消息。重复直到出现预期助手回复且 `state` 为 `idle`、`waitingOnUser` 或 `stopped`。`timedOut: true` 表示 Mo 仍在工作。若存在 `pendingInput`，用 `send` 回答。
10. 不要在 `start` 或 `send` 后依赖 `--from latest`：它只捕获读取开始后产生的输出，快速回合可能完成并返回无消息。超时接受 `0`、毫秒、秒或分钟，如 `500ms`、`45s`、`4m`，最大 `290s`。
11. `status.state` 是共享 UI 状态：`ready` 或 `sleeping` 表示无代理运行；`needs_you` 表示需要输入。`read.state` 描述可见回合，可能在子代理仍在工作时完成。消费完成的 QA 报告前使用 `status` 和 `report --require-idle`。
12. 跟进或回答时优先使用 `--wait` 以便直接返回下一个注意边界：`mo send --session-id "$session_id" --wait 45s 'Use the staging account and continue'`。若 Mo 正在工作，`send` 会停止活动回合、中断进行中的工具工作，并从保存的历史开始新回合；它不会引导实时回合。仅当意图是中断时才发送。不带 `--wait` 时，成功仅表示消息被接受；用 `read` 确认新的助手回复。
13. 仅停止活动回合：`mo stop "$session_id"`。等待几秒传播，然后用 `read --from start --timeout 0 --json` 验证状态为 `stopped`。停止不会删除会话，已运行的子代理可能独立完成。传 `--subagents` 可同时停止运行中或并发排队的子代理而不关闭其对话。
14. 完成的会话应离开活动列表时归档：`mo archive "$session_id"`。归档会停止活动工作。在 Web UI 中取消归档前，后续 `send` 调用会被拒绝；CLI 没有取消归档命令。
15. 传输文件：`upload` 需要已有会话并打印权威沙箱路径。将该返回路径发给 Mo；本地路径在其托管机器内无意义。示例：`remote_path=$(mo upload --session-id "$session_id" ./fixture.csv fixture.csv)`，然后 `mo send --session-id "$session_id" "Use the sandbox file at $remote_path."`。下载：`mkdir -p .momentic-artifacts` 后 `mo download --session-id "$session_id" --output .momentic-artifacts "$remote_path"`。若 `--output` 指定目录，需先创建；不存在的输出路径会被当作目标文件名。不带 `--output` 时，下载使用 `MOMENTIC_ARTIFACTS_DIR`，然后是 `<current-directory>/.momentic-artifacts`。
16. 运行 `mo <command> --help` 查看精确选项。全局 `--log-level` 接受 `debug`、`info`、`warn` 或 `error`。命令参考：`mo version` 打印已安装版本、检查最新发布并在不同时建议更新；`mo upgrade` 更新到最新发布；`mo start <message>` 启动会话，选项 `--tunnel`、`--momentic-mode`、`--max-concurrency`；`mo send <message> --session-id <id>` 中断活动工作或开始回合，`--wait` 返回下一个注意边界；`mo read <session-id>` 读取转录和可见状态，选项 `--from`、`--timeout`、`--json`；`mo status <session-id>` 读取状态、web URL、缺陷/测试用例计数，`--full` 添加最新消息和发现；`mo report <session-id>` 导出完整发现和复现视频，`--require-idle` 拒绝不完整快照；`mo stop <session-id>` 停止活动回合，`--subagents` 同时停止活动子代理而不关闭它们；`mo archive <session-id>` 停止并归档会话，取消归档仅限 Web；`mo upload <source> [destination] --session-id <id>` 上传一个文件并打印其沙箱路径；`mo download <source> --session-id <id>` 下载沙箱路径，`--output` 选择本地目标；`mo tunnel start <address...>` 启动本地/私有访问，`--foreground` 保持附着，见 Tunneling 参考文档；`mo tunnel list` 列出本机由 Mo 启动的隧道；`mo tunnel stop <tunnel-id>` 停止隧道并撤销访问。
17. 当用户要求修复 QA 发现的缺陷时，同时阅读 Repair loop 参考文档并继续诊断、修复和验证；否则运行 QA 而不更改应用代码。

适用边界 · 注意事项

• 未安装或无法运行 mo CLI、未配置 Momentic 认证时。
• 目标需要本地/私有访问但未配置隧道时。
• 用户未指定测试目标且无法从对话推断时。