工作流与运行记录

说明 Numora 对外 API 开发者预览版中的 workflow list、dispatch、run status、run logs 与执行模型。

范围

本页定义对外 API 应如何暴露 workflow 执行与运行历史。

内容包括：

workflow 列表
手动 dispatch
run status 与派生 outcome
节点级执行日志
retry 与执行建议

对外 Workflow 模型

对外 workflow surface 应刻意保持精简。

当前 developer preview 已提供：

GET /v1/workflows
POST /v1/workflows/{id}/dispatch
GET /v1/runs/{id}
GET /v1/runs/{id}/logs

当前 app 内部实际上已经有更丰富的 workflow 路由，但对外契约的第一版应先暴露稳定的 workflow metadata 与 execution state。

获取 Workflow 列表

GET /v1/workflows

建议响应：

{
  "data": [
    {
      "id": "wf_01jpx8t0v5lg1sq3wy6c5c7h2x",
      "name": "Reviewed Invoice Push",
      "status": "active",
      "version": 7,
      "binding_count": 1,
      "updated_at": "2026-03-21T16:00:00.000Z"
    }
  ]
}

建议公开字段：

id
name
status
version
binding_count
updated_at

对外 workflow 资源默认不应直接暴露完整 definition JSON、connection snapshot 或 editor 专用 metadata。

Dispatch Workflow

POST /v1/workflows/{id}/dispatch

这个接口用于为指定 document 创建一次新的 run。

当前 developer preview 已支持该接口，第一版只支持 execution_mode=queued，并默认使用 workflow 的 default binding。

建议请求体：

{
  "document_id": "doc_01jpwq4q9m7q4q2k8dax1x1q5n",
  "execution_mode": "queued"
}

建议响应体：

{
  "run_id": "run_01jpx91kby4k7saz7y2qf1k2nm",
  "workflow_id": "wf_01jpx8t0v5lg1sq3wy6c5c7h2x",
  "status": "queued",
  "execution_mode": "queued"
}

说明：

客户端应默认把 dispatch 视为异步操作
对外 API 第一版只返回 202 Accepted，不会在请求内 inline 执行
如果需要 retry，最稳妥的公开模型是重新创建一个新的 run，而不是原地修改已结束的 run

Run Status

run 资源建议支持以下生命周期状态：

queued
running
success
failed
cancelled

当前 app 已经真实使用 queued / running，并且会 claim queued runs 执行，同时也会把 lease 过期的 running runs 恢复为 failed。

派生 Delivery Outcome

仅靠 run status 往往不足以支持运维排查。

当前 app 已经会根据 node log 派生出更高层的 delivery outcome。对外 run 资源也应直接暴露这层摘要。

建议 outcome 值：

queued
failed
wrote
no_write
completed

建议含义：

wrote：至少有一个 write node 成功执行
no_write：run 成功结束，但没有发生实际下游写入
completed：run 成功结束，但没有产生“写入型”结果摘要

获取 Run 详情

GET /v1/runs/{id}

建议响应：

{
  "id": "run_01jpx91kby4k7saz7y2qf1k2nm",
  "workflow_id": "wf_01jpx8t0v5lg1sq3wy6c5c7h2x",
  "document_id": "doc_01jpwq4q9m7q4q2k8dax1x1q5n",
  "status": "success",
  "delivery_outcome": "wrote",
  "delivery_outcome_reason": "dataverse_add_row created 1 row(s)",
  "created_at": "2026-03-21T16:02:00.000Z",
  "started_at": "2026-03-21T16:02:01.000Z",
  "finished_at": "2026-03-21T16:02:04.000Z",
  "error_summary": null
}

建议公开详情字段：

id
workflow_id
document_id
status
delivery_outcome
delivery_outcome_reason
created_at
started_at
finished_at
error_summary

当前内部 run 记录还保存了 definitionSnapshot、connectionSnapshot、triggerEventSnapshot、context 与 nodeLog。这些字段对审计和执行都很有价值，但不应该全部直接塞进默认的公开 run 响应里。

获取 Run Logs

GET /v1/runs/{id}/logs

当前 developer preview 已提供节点级 run logs。

建议响应：

{
  "data": [
    {
      "node_id": "node_ocr_confirmed",
      "node_type": "load_ocr_confirmed_data",
      "status": "success",
      "attempts": 1,
      "duration_ms": 42,
      "started_at": "2026-03-21T16:02:01.000Z",
      "finished_at": "2026-03-21T16:02:01.042Z",
      "output": "loaded reviewed OCR data"
    },
    {
      "node_id": "node_write",
      "node_type": "dataverse_add_row",
      "status": "success",
      "attempts": 1,
      "duration_ms": 261,
      "started_at": "2026-03-21T16:02:03.000Z",
      "finished_at": "2026-03-21T16:02:03.261Z",
      "output": "dataverse_add_row created 1 row(s)"
    }
  ]
}

建议日志字段：

node_id
node_type
status
attempts
duration_ms
started_at
finished_at
output
error
error_code

当前 app 已经把 node log 存在 run record 上，并且会对 output / error 做截断保存。对外 API 则更适合把日志拆成独立 endpoint。

执行行为

当前 app 已经是真正的 queued-run 模型：

新 run 初始状态是 queued
worker 或 cron claim 之后进入 running
lease 超时会把陈旧 run 恢复为 failed
手动 dispatch 在某些情况下会尝试 inline 执行，以便更快返回结果

因此，对外文档应明确：

不要假设 dispatch 返回时 run 已经完成
应通过 GET /v1/runs/{id} 轮询，或改用 webhook
即使某些预览环境偶尔 inline 完成，也不能把它当作唯一行为模式

Retry 与 Dry Run 建议

retry 建议这样建模：

retry 应创建一个新的 run，而不是覆盖旧 run
新 run 可以引用同一个 workflow 和同一个 document，但必须拥有新的 run id

当前 app 还支持 node dry run 和 path dry run 这类内部调试能力。它们对产品 UI 和运维排障有价值，但在公开执行契约稳定之前，更适合继续留在内部能力层。

工作流与运行记录

范围

对外 Workflow 模型

获取 Workflow 列表

Dispatch Workflow

Run Status

派生 Delivery Outcome

获取 Run 详情

获取 Run Logs

执行行为

Retry 与 Dry Run 建议

相关页面

On this page