运行记录

查询文档运行的历史记录。

源码: apps/backend/src/routes/runs.ts

GET /runs

查询项目下的运行记录列表。

认证方式

JWT Token（仅支持 JWT，combinedAuth）

请求参数

Query 参数

参数	类型	必填	默认值	说明
`projectId`	string	是	-	项目 UUID
`documentId`	string	否	-	文档 UUID，按文档筛选
`deploymentId`	string	否	-	部署 UUID，按部署筛选
`sourceType`	string	否	-	来源类型：`editor`、`api_key`、`schedule`
`page`	number	否	`1`	页码（最小 1）
`pageSize`	number	否	`20`	每页数量（最大 100）

响应格式

状态码: 200

json

{
  "runs": [
    {
      "id": "uuid",
      "owner_user_id": "uuid",
      "project_id": "uuid",
      "document_id": "uuid",
      "deployment_id": "uuid",
      "source_type": "editor",
      "triggered_by_user_id": "uuid",
      "api_key_id": null,
      "status": "success",
      "data": {
        "inputs": {},
        "globalCtx": [...],
        "duration": 1234,
        "completedBlocks": 3,
        "timedOut": false
      },
      "created_at": "2026-03-07T12:00:00.000Z",
      "updated_at": "2026-03-07T12:00:01.234Z",
      "deleted_at": null,
      "api_key": {
        "team": { "name": "我的团队" }
      },
      "deployment": {
        "version_major": 1,
        "version_minor": 2
      }
    }
  ],
  "total": 100,
  "page": 1,
  "pageSize": 20
}

字段	类型	说明
`runs`	RunRecord[]	运行记录数组（含关联的 api_key 和 deployment 信息）
`total`	number	总记录数
`page`	number	当前页码
`pageSize`	number	每页数量

记录按 created_at 降序排列。

请求示例

bash

# 查询项目所有运行记录
curl -H "Authorization: Bearer YOUR_JWT" \
  "https://block2-api.wainao.chat/runs?projectId=PROJECT_UUID"

# 按来源类型筛选
curl -H "Authorization: Bearer YOUR_JWT" \
  "https://block2-api.wainao.chat/runs?projectId=PROJECT_UUID&sourceType=api_key&page=1&pageSize=10"

错误码

状态码	错误	说明
400	`projectId is required`	缺少 projectId
400	`Invalid sourceType: xxx`	sourceType 无效
403	`仅支持 JWT 认证`	使用了非 JWT 认证
403	`无权访问该项目`	非项目所有者且非团队成员
404	`项目不存在`	项目不存在或已删除

GET /runs/:runId

获取单条运行记录详情。

认证方式

JWT Token（仅支持 JWT，combinedAuth）

请求参数

Path 参数

参数	类型	必填	说明
`runId`	string	是	运行记录 UUID

Query 参数

参数	类型	必填	说明
`trace`	string	否	传 `skip` 进入「骨架秒开」模式：后端不重建 `globalCtx`，并从响应中剥离旧 run 已持久化的 `data.globalCtx`（大 JSON），只返回基础字段。追踪明细改由 `GET /runs/:runId/globalctx-events?format=timeline` 按需拉取。不传时行为不变（向后兼容）。仅影响响应，不改数据库。

响应格式

状态码: 200

返回完整的运行记录对象。除关联的 api_key、deployment 外，详情接口还会组装：

triggered_by_user：用 triggered_by_user_id 二次查 profiles 得到的展示名（profiles 外键已删除，无法 JOIN）。
project.team：项目所属团队名，用于组织名兜底（editor/schedule/oauth 触发的 run 无 api_key 时使用）。

json

{
  "id": "uuid",
  "owner_user_id": "uuid",
  "project_id": "uuid",
  "document_id": "uuid",
  "deployment_id": "uuid",
  "source_type": "api_key",
  "triggered_by_user_id": "uuid",
  "api_key_id": "uuid",
  "status": "success",
  "data": {
    "inputs": { "text": "hello" },
    "globalCtx": [...],
    "duration": 2345,
    "completedBlocks": 5,
    "timedOut": false
  },
  "created_at": "2026-03-07T12:00:00.000Z",
  "triggered_by_user": { "display_name": "张三" },
  "api_key": { "team": { "name": "我的团队" } },
  "project": { "team": { "name": "我的团队" } },
  "deployment": { "version_major": 1, "version_minor": 0 }
}

trace=skip 模式下，响应中的 data 不含 globalCtx，其余基础字段照常返回。

错误码

状态码	错误	说明
403	`仅支持 JWT 认证`	使用了非 JWT 认证
403	`无权访问该运行记录`	非项目所有者且非团队成员
404	`运行记录不存在`	记录不存在或已删除
404	`项目不存在`	记录关联的项目不存在

补充端点

本节补充 plans/need-update-api.md 中尚未覆盖到 docs-site 的接口。端点标题保持严格的 METHOD /path 格式，便于后台文档覆盖率服务识别。

POST /runs

创建一次运行记录或提交新的运行请求。

认证：JWT Bearer Token 或 API Key（combinedAuth）。请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回任务触发结果、运行状态或同步摘要；长任务可能只表示已入队。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /runs/:runId/cancel

取消正在执行的运行。

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`runId`	运行记录 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回任务触发结果、运行状态或同步摘要；长任务可能只表示已入队。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

GET /runs/:runId/events

读取指定运行的事件流历史。

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`runId`	运行记录 ID

请求：无请求体。Query 参数用于分页、过滤、搜索或状态筛选；未传时按后端默认排序与分页返回。

响应：成功时返回目标资源详情、状态或配置对象。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

GET /runs/:runId/globalctx-events

读取指定运行的 global context 事件历史。

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`runId`	运行记录 ID

Query 参数

参数	类型	必填	说明
`sinceSequence`	number	否	断点续读：仅返回 `sequence` 严格大于该值的事件
`limit`	number	否	单次返回事件数上限。默认 `200`，最大 `500`（超出会被夹到 `500`）。issue #561 紧急止血新增
`format`	string	否	传 `timeline` 时，后端复用 hydrate 规则直接返回 `GlobalCtxRecord[]`（喂前端甘特图/追踪面板）；不传时返回原始热表事件（向后兼容）
`includeOutput`	boolean	否	仅在 `format=timeline` 下生效。默认（或 `false`）只返回时间摘要（`blockName`/`blockType`/`startedAt`/`completedAt`），剥离可能很大的 `block_complete.output`（`block_error` 的小体量 error 摘要仍保留）；传 `true` 才带完整 output

请求：无请求体。

响应：

默认（无 format）：{ events, maxSequence, truncated, oversizedFirstEvent }，events 为原始热表事件。
format=timeline：{ globalCtx, maxSequence, truncated, oversizedFirstEvent }，globalCtx 为 hydrate 后的 GlobalCtxRecord[]。旧 run（热表无事件）回退读 runs.data.globalCtx，并同样按 includeOutput 契约裁剪 output。

字节上限保护（issue #561 紧急止血新增）：

服务端累计响应字节，超过 2MB 后截断剩余事件（按 sequence ASC 优先保留前序事件）。响应字段：

truncated: boolean — 本页是否因字节上限截断。true 时客户端应用 maxSequence 作为 sinceSequence 继续拉下一批。
oversizedFirstEvent: boolean — 首条事件本身就超过 2MB。此时仍强制返回该事件避免 cursor 死循环，但客户端应当感知到本页含异常大事件，必要时降级渲染。该字段仅在历史超大 run（PR-1 时代的 200MB 级 payload）上才会出现，后续主体改造（plan v5 §4.3 blob 外置）落地后将不再触发。

常见错误：400 参数非法（如 sinceSequence 非非负整数），401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

POST /runs/:runId/resume

恢复被 Ask、人工确认或中断流程暂停的运行。

认证：JWT Bearer Token 或 API Key（combinedAuth）。 路径参数

参数	说明
`runId`	运行记录 ID

请求：请求体为 JSON，包含创建、提交、安装、发布或业务动作所需字段。

响应：成功时返回任务触发结果、运行状态或同步摘要；长任务可能只表示已入队。

常见错误：400 参数非法，401 未认证，403 权限不足，404 资源不存在；服务端或上游异常返回 500。

运行记录 ​

GET /runs ​

认证方式 ​

请求参数 ​

Query 参数 ​

响应格式 ​

请求示例 ​

错误码 ​

GET /runs/:runId ​

认证方式 ​

请求参数 ​

Path 参数 ​

Query 参数 ​

响应格式 ​

错误码 ​

补充端点 ​

POST /runs ​

POST /runs/:runId/cancel ​

GET /runs/:runId/events ​

GET /runs/:runId/globalctx-events ​

POST /runs/:runId/resume ​

运行记录

GET /runs

认证方式

请求参数

Query 参数

响应格式

请求示例

错误码

GET /runs/:runId

认证方式

请求参数

Path 参数

Query 参数

响应格式

错误码

补充端点

POST /runs

POST /runs/:runId/cancel

GET /runs/:runId/events

GET /runs/:runId/globalctx-events

POST /runs/:runId/resume