AI Agent、MCP 与 Runner

CueCast 可以通过 MCP 接入 Codex 等 AI 编程工具。AI Agent 负责分析代码改动、查找用例和发起执行；CueCast Chrome 扩展作为有头浏览器 Runner，在真实页面完成回放或录制；执行结果仍保存到 CueCast，便于团队查看和追溯。

AI 编程工具 → CueCast MCP → CueCast 服务 → Chrome 扩展 Runner → 目标页面
                                      ↘ 执行结果与报告

使用前准备

• 至少有一个可访问的项目。
• 已安装最新版 CueCast Chrome 扩展。
• Chrome、扩展和已登录 CueCast 的中台页面保持运行。
• 本机已安装 Node.js 18 或更高版本。
• 创建 API Token；普通成员需要联系组织管理员安全获取 Token。

Runner 与发起请求的 API Token 必须属于同一组织。当前提供的是有头浏览器扩展 Runner，不会自动唤醒已关闭的电脑或 Chrome。

三步接入 AI Agent

1. 创建 API Token

组织 Owner 或 Admin 进入「设置 → API Token」，点击「创建 Token」。建议：

• 保留 test:read、run:create、run:read、report:read 四项权限。
• 只允许操作一个项目时，选择对应的项目范围。
• 根据使用周期设置过期日期，不再使用时及时撤销。

Token 明文只在创建后展示一次。请在关闭弹窗前保存，并通过安全方式交给需要配置 MCP 的人员；不要把 Token 写进代码、提交到 Git 或粘贴到公开对话中。

权限、项目范围、调用示例、轮换和撤销方式详见 API Token。

2. 让 AI 完成安装

在 API Token 页面点击「MCP / Skill 使用指南」，进入「AI Agent」页面，复制第二步的安装指令并发送给 Codex。AI 会按照当前 CueCast 环境提供的在线说明：

1. 下载并配置 CueCast MCP。
2. 安装 cuecast-regression Skill。
3. 在确实需要时单独向你索取 API Token。
4. 将 Token 写入用户级 MCP 配置，而不是项目仓库。
5. 验证 MCP 是否可以连接 CueCast。

安装完成后，按 AI 的提示重新连接或重启 MCP 客户端，使新配置生效。

3. 发送使用指令

「AI Agent」页面提供三类可直接复制的指令：

• 分析当前分支的代码改动，匹配并运行关联回归用例。
• 查看当前项目的全部用例及状态。
• 执行指定分组下的用例并汇总结果。

Token 可以访问多个项目时，AI 会根据当前仓库配置和任务上下文选择；仍有多个合理候选时，应先向你确认项目。

MCP 可以做什么

能力	说明
查询资产	查询项目、分组、测试用例和执行计划；用例中的敏感值保持脱敏。
执行与报告	运行单条用例或执行计划，查询进度、取消任务并读取持久化报告。
自动真实录制	创建录制会话，让扩展在真实页面执行经确认的语义操作并保存为 CueCast 用例。

执行请求支持幂等键。同一 Token 使用相同幂等键和相同参数重试时会返回原任务，避免因网络不确定而重复产生业务操作；相同键对应不同参数会被拒绝。

执行超时怎么计算

调用方式	默认超时	计算范围
运行一条用例	600 秒	本次单用例任务。超长用例可显式设置，最长 3600 秒。
运行一个执行计划	3600 秒	整个计划共用，包括登录准备和计划内所有用例；不是每条用例各 3600 秒。
自动录制	900 秒	Runner 开始录制后的活动时间；可设置为 300–3600 秒。

需要长期维护的多用例回归建议使用执行计划。

默认情况下 MCP 会等待任务进入终态并返回已保存的报告。异步场景可以只提交任务，再按 Run ID 查询状态。超时同时约束服务端任务时限和本次 MCP 同步等待窗口。

扩展 Runner 的工作方式

登录 CueCast 中台后，扩展会注册当前浏览器设备，并定期领取同组织的单用例、执行计划或录制任务。任务可能短暂显示为「排队中」；领取后会进入「执行中」。

Runner 执行单用例时沿用中台手动执行的窗口和视口配置。执行计划会：

1. 按计划配置处理登录准备。
2. 按保存顺序执行各业务用例。
3. 遵循「全部执行」或「失败即停止」策略。
4. 保存逐用例结果和计划汇总报告。

计划中的多条用例共用一个计划超时。含无痕用例的计划仍受中台的登录会话复用限制。

用 AI 做代码变更回归

cuecast-regression Skill 将回归拆成三个独立阶段：

1. 分析与执行：读取本地代码改动，提炼受影响的 Web 场景，匹配并运行已有 CueCast 用例，返回执行结果和覆盖缺口。
2. 规划缺失用例：只有你确认需要规划后，AI 才会给出完整的前置条件、操作、测试数据和断言。
3. 自动录制：只有你再次确认完整方案后，AI 才会启动真实页面录制。新用例保存后还应独立回放通过，才能视为验证完成。

规划确认不等于授权录制。可能创建、修改或删除真实业务数据的步骤，应在录制方案中明确说明。

自动真实录制的范围

自动录制复用现有 CueCast 录制器：AI 提交语义操作计划，扩展通过浏览器原生点击和输入操作真实元素，录制器继续生成定位信息、上下文和步骤截图。计划支持常规点击、输入和文本断言；遇到元素歧义或页面状态不符时，AI 可以读取精简页面快照后继续处理。

当前限制：

• 单次语义计划最多 30 个操作。
• 适合主页面中的常规导航、按钮和表单。
• iframe、文件上传、复杂拖拽、键盘组合、视觉观察和需要人工登录介入的流程暂不适合自动录制。
• 敏感输入应标记为敏感值；密码控件继续遵循 CueCast 的密码脱敏规则。
• 保存录制只代表用例资产已创建，不代表回放已经通过。

常见问题

提示没有可用 Runner

确认 Chrome 正在运行、CueCast 扩展已启用、中台仍保持登录，并且登录组织与 API Token 所属组织一致。刷新一次 CueCast 页面后，再让 AI 检查 Runner 状态。

任务长时间排队或变成已超时

Runner 会定期领取任务，因此排队可能有短暂延迟。如果扩展在排队后离线、任务超过总时限或执行租约失效，任务会进入明确的终态。系统不会自动重放已经开始的任务，以免重复提交真实业务操作。

MCP 已安装但 AI 看不到工具

重新连接或重启 MCP 客户端，并确认用户级配置中的 API 地址和 Token 对应当前 CueCast 环境。若 Token 已过期或被撤销，请创建新 Token 后更新配置。

执行完成后，可以在执行历史中按来源选择 MCP，集中查看用例和计划结果。