sp replay：回放计划

AI 代理何时使用： 发起回放计划并跟踪进度。失败用例和差异见 replay case 和 replay diff。

概要

基于已录制的用例，创建、跟踪进度、停止和重跑回放计划。

子命令

子命令	说明
run	创建回放计划（POST /api/createPlan）
status <planId>	轮询进度（GET /api/progress）
statistics <planId> --app <appId>	回放计划的汇总行，含各类用例数
report <planId> --app <appId>	回放计划的统计报告
stop <planId>	停止计划
rerun <planId>	重跑计划

用例列表、差异和元数据见 replay case 和 replay diff。

参数（run）

参数	API 字段	说明
--app	appId	应用 ID（必填）
--env	targetEnv	回放目标的 base URL（必填），不是环境别名。必须带 http:// 或 https:// 和主机名，如 http://travel-ota:8080。CLI 会拒绝 staging、dev 这类值。
--suite	—	回放哪一类用例。设为 Pinned 时只回放手动固化的用例。AutoPinned 不可选。
--from	caseSourceFrom	滚动选取的起始时间（时长如 -24h，或 RFC3339）。--suite Pinned 时忽略。
--to	caseSourceTo	滚动选取的结束时间（默认：现在）。--suite Pinned 时忽略。
--limit	caseCountLimit	最大用例数
--name	planName	显示名
--operation	operationIds	可重复；按接口过滤
--enable-mock	enableMock	回放时 Mock（默认 true）
--no-mock	enableMock	关闭 Mock（enableMock=false；覆盖 --enable-mock）
--allow-empty	—	窗口内没有录制用例时也创建滚动计划（默认 false）。固化用例为空时，--suite Pinned 仍会失败。
--watch	—	run 时：创建计划后轮询到结束；status 时：轮询已有计划

示例

sp record case list --app my-app --since -24h --json   # 先确认有用例
sp replay run --app my-app --env http://travel-ota:8080 --from -24h --enable-mock --json
sp replay run --app my-app --env http://travel-ota:8080 --suite Pinned --watch --json
sp replay run --app my-app --env http://travel-ota:8080 --from -24h --no-mock --watch --json
sp replay status plan-xyz --watch --json
sp replay stop plan-xyz --json
sp replay rerun plan-xyz --json

用例选择

默认选择方式是滚动：从 --from/--to 时间窗里选用例（不带这两个参数时，默认窗口是最近 24 小时）。

--suite Pinned 回放该应用手动固化的全部用例。它不是时间窗查询，所以 --from 和 --to 会被忽略。用例超出滚动时间窗后仍可回放。自动管理的 AutoPinned 用例不包含在内。

sp replay run \
  --app my-app \
  --env http://travel-ota:8080 \
  --suite Pinned \
  --watch \
  --json

预检（run，滚动计划）

在 POST /api/createPlan 之前，CLI 会用相同的 --app、--from、--to 窗口先查一次 POST /api/storage/replay/query/replayCase。如果没有入口用例且没带 --allow-empty：

{
  "ok": false,
  "command": "replay run",
  "error": {
    "code": "NO_RECORDED_CASES",
    "message": "no recorded cases for app …; run the app with the agent and send traffic first, or use --allow-empty"
  }
}

--suite Pinned 时，CLI 改为检查有没有手动固化的用例。为空则以 NO_PINNED_CASES 失败；--allow-empty 不能跳过这个安全检查。

JSON 输出（run）

{
  "ok": true,
  "command": "replay run",
  "data": {
    "planId": "plan-xyz",
    "result": 1,
    "desc": "success"
  }
}

JSON 输出（run --watch）

带 --json 时，stdout 是按行分隔的封装：

1. 一条计划创建成功的封装（command：replay run）。
2. 一条或多条进度封装（command：replay status）。
3. 最后一条进度封装的 data 里带 "finished": true。

JSON 输出（status）

{
  "ok": true,
  "command": "replay status",
  "data": {
    "percent": 42,
    "lastUpdateTime": "2026-06-27 10:00:05"
  }
}

status 原样返回调度服务的进度：percent 和 lastUpdateTime，没有计划状态。带 --watch 时每轮查询输出一条这样的信封，最后一条加上 "finished": true；run --watch 的最后一条也可能是这个计划的统计行（同样带 "finished": true）。10 分钟后计划仍未结束时，以 API_ERROR 结束（退出码 1）。

JSON 输出（stop）

{
  "ok": true,
  "command": "replay stop",
  "data": {
    "result": 1,
    "desc": "success"
  }
}

statistics 和 report

两个命令都要同时给回放计划 ID 和 --app：

sp replay statistics <planId> --app <appId> --json
sp replay report <planId> --app <appId> --json

statistics 按应用和回放计划 ID 查这个计划的统计行，查不到时报 no statistics for plan <planId>。report 原样返回后端对这个计划的统计报告。

流水线用来判断能否发版的结论（findings.state）来自 Open API，不是这两个命令。

JSON 输出（rerun）

{
  "ok": true,
  "command": "replay rerun",
  "data": {
    "planId": "plan-xyz-rerun",
    "result": 1,
    "desc": "success"
  }
}

REST 接口对照

子命令	方法	路径
run	POST	/api/createPlan
run（webhook 风格）	GET	/api/createPlan?appId=…（CLI 不建议用；请用 POST）
status	GET	/api/progress?planId=
stop	GET	/api/stopPlan?planId=
rerun	POST	/api/reRunPlan
statistics	POST	/api/report/queryPlanStatistics
report	POST	/api/report/queryPlanStatistic

run 的请求体：BuildReplayPlanRequest（schedule 模块）。

响应封装：CommonResponse（result、desc、data）。

相关文档

• replay case
• replay diff
• 诊断回放失败