Skip to content

Latest commit

 

History

History
424 lines (270 loc) · 23.7 KB

orchestration.md

File metadata and controls

424 lines (270 loc) · 23.7 KB

编排、运行与调度 API

认证和通用状态码见 README。

SOP(Workflow)

WorkflowDefinition 主要字段:

{
  "id":"wf-dev",
  "name":"研发 SOP",
  "version":1,
  "revision":0,
  "status":"draft",
  "owner":"platform",
  "tags":["研发"],
  "description":"...",
  "sandboxProfileId":"sandbox-go",
  "nodes":[{"id":"implement","name":"实现","type":"agent","agentId":"agent-dev","maxAttempts":2,"maxReworks":1,"position":{"x":0,"y":0}}],
  "edges":[{"id":"e1","source":"implement","target":"review","when":"success"}]
}

节点类型为 agent|script|approval。脚本节点通过 scriptLanguage(shell|python)和 script 配置;Agent 节点只引用角色定义,任务说明写在角色的 prompt(一段自由文本)上;运行时引擎用角色名称、产物契约、门禁和重试策略把它包成节点任务书。节点可配置制品契约、失败/重试策略和画布位置。角色的 CLI 与 GET /api/executors 的内置目录一致。旧的 command 节点在保存时会迁移为 shell 脚本节点。

GET /api/workflows

返回全部 WorkflowDefinition[],200,不分页。

返回值包含两类 SOP:项目里存储的 SOP,以及 generic_templates 表中的通用模板(payload 带 generic: true,projectId 为空)。通用模板与项目无关,所有项目都能看到;普通用户只读,复制到项目后才能编辑。运行时按和自定义 SOP 相同的流程解析节点与角色。通用模板通过 requirements 声明运行依赖(例如 gongfeng-git-token、gongfeng-mcp、tapd-mcp),Studio 会在复制前做依赖预检。需要人工把关时可在复制后自行添加审批节点。

PUT /api/workflows

按 id 保存。id 和 sandboxProfileId 必填;version=0 时改为 1。成功 200 返回保存后的 SOP;revision 冲突返回 409,其他校验/存储错误 400。id 命中通用模板时返回 409(通用模板只读)。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" -X PUT \
  -H 'Content-Type: application/json' \
  -d '{"id":"wf-dev","name":"研发 SOP","version":1,"status":"draft","sandboxProfileId":"sandbox-go","nodes":[],"edges":[]}' \
  "$AGENTFLOW_URL/api/workflows"

GET /api/workflows/{id}

成功 200 返回完整 SOP(含通用模板);不存在 404。

DELETE /api/workflows/{id}

成功 204,无响应体。有 running|waiting run,或仍被未关闭 Issue 绑定时返回 409;不存在 404;其他删除错误 400。通用模板返回 409(只读)。

revision

  • GET /api/workflows/{id}/revisions:200 DefinitionRevision[]。
  • GET /api/workflows/{id}/revisions/{revisionId}:200 DefinitionRevision;revision 不存在或不属于该 SOP 时 404。
  • POST /api/workflows/{id}/revisions/{revisionId}/restore:恢复并 200 返回 SOP;失败通常 400。

以上接口在 SOP 本身不存在时先返回 404。

POST /api/workflows/{id}/publish

无请求体。设置 status=published,version 加一,成功 200 返回 SOP;不存在 404;保存失败 400。

POST /api/workflows/{id}/clone

请求:

{"id":"wf-dev-copy","name":"研发 SOP 副本","owner":"u-1","projectId":"alpha"}

id、name 必填。副本固定为 draft、version=1、revision=0,成功 201;字段/存储错误 400,源 SOP 不存在 404。

源 SOP 是通用模板时,复制会同时把模板引用的角色创建到 projectId 指定的项目(已存在的同名角色直接复用),并把节点上的 agentId 重写到本项目角色,因此复制出的 SOP 可直接运行;此时 projectId 必填,缺失返回 400。模板声明的 requirements 会保留在副本上,Studio 继续据此提示依赖(例如发起 MR 节点需要工蜂 Git Token / 工蜂 MCP)。

运行

对话工作区使用 kind=workspace,仅作为沙箱与文件生命周期记录,不执行 SOP 节点,不占用 SOP 配额。环境取用户在高级设置中的选择,否则由 Main Bot 打开工作区时选择(默认 generic-docker),创建后冻结;详见 对话工作区。旧角色协作写入口已移除,历史记录可继续查看。

run 状态通常为 running|waiting|succeeded|failed|cancelled。响应中的 nodes 是 node id 到 NodeRun 的映射;还包含 usage、toolCalls、artifact 元数据、时间和 revision。

ownerInstanceId、leaseUntil、executionGeneration、workspaceHost、workspaceRoot、sandboxId 是内部 lease/执行定位信息。客户端可忽略这些字段,不应据此实现实例接管或沙箱生命周期操作。

GET /api/runs

返回全部 run 摘要数组,200,不分页。摘要省略 artifacts 内容、遥测、日志、事件和 workflow snapshot,截断 input/错误,并省略已完成节点的大输出。

可传 projectId 限定项目,responsible=me 只返回当前登录用户负责执行或关联需求责任人为当前用户的任务;responsible=me 未登录时返回 401。两项筛选可以组合。

POST /api/runs

直接启动 SOP:

{"workflowId":"wf-dev","input":"实现审计日志","projectId":"platform"}

projectId 可选,但给出时必须存在。成功 201 返回新 run;执行被禁用 403;工作流/参数/引擎错误通常 400。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" -X POST \
  -H 'Content-Type: application/json' \
  -d '{"workflowId":"wf-dev","input":"实现审计日志","projectId":"platform"}' \
  "$AGENTFLOW_URL/api/runs"

该接口只启动长任务,不等待完成。保存为 Issue 的工作优先使用 Issue dispatch,以建立 task/issue 关联。

GET /api/runs/{runId}

成功 200 返回 run 详情;不存在 404。详情:

  • artifact 只返回元数据,不返回 content;
  • telemetry/logs 不内嵌,应使用独立接口;
  • workflow snapshot 会移除节点 script(以及兼容字段 command);
  • events 最多返回最近 80 条;部分输出文本会截断。

DELETE /api/runs/{runId}

成功 200 {"status":"deleted"};不存在或不能删除通常 400。当前处理器本身不额外检查运行状态,约束由存储层决定。

GET /api/runs/{runId}/preview/download

下载已归档的完整静态站点,返回 200 application/zip,文件名为 preview-{runId}.zip。ZIP 根目录是构建产物目录的内容,保留 HTML、JS、CSS、图片等文件及其相对路径;不包含在线预览注入的会话脚本或后端地址。工作区清理后仍可下载,不会重新构建。

沿用运行 API 的认证要求,无需预览会话。不存在的运行、预览或静态包返回 404,尚未就绪返回 409,已过期或删除返回 410。下载不延长预览保留期限,支持 HTTP Range 请求。

SSE 实时运行

GET /api/runs/{runId}/stream?after={seq}&logsAfter={seq}

成功响应 200 text/event-stream。after 是已消费的遥测 sequence,logsAfter 是日志 sequence;无效/缺省按 0。每个更新事件:

id: 12
event: run
data: {"run":{...},"telemetryDelta":[...],"logDelta":[...]}
  • id 为 run revision。
  • run 是实时详情,但不含 events、遥测/日志正文,input 和节点文本会截断。
  • 每次 telemetryDelta、logDelta 最多保留最新 80 条。
  • 空闲时每 15 秒发送注释心跳 : heartbeat。
  • run 不存在或订阅失败返回 404;服务器不支持 flush 返回 500。
  • 客户端断开即取消订阅;服务端关闭更新通道时流结束。当前不解析 Last-Event-ID,重连必须显式传 sequence。
curl -N -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" \
  "$AGENTFLOW_URL/api/runs/run-1/stream?after=0&logsAfter=0"

日志、遥测与下载

游标分页

GET /api/runs/{runId}/logs 和 /telemetry 共用 sequence 游标:

  • limit:默认 100,最大 200;小于等于 0 也按 100。
  • after=N:正向读取 sequence>N。
  • before=N:向前读取 sequence<N;未传 after/before 时返回最新一页。
  • 同时传入时 after 优先。
  • 返回始终按 sequence 升序。
  • nextAfter 是本页最后一条 sequence,适合增量刷新;nextBefore 是第一条,适合向前翻页;hasMore 表示当前方向还有数据;sequence 是 run 当前总序号。

GET /api/runs/{runId}/logs

参数:nodeId、after、before、limit。成功 200:

{"runId":"run-1","sequence":321,"logs":[{"id":"log-1","sequence":201,"timestamp":"...","level":"info","stream":"stdout","body":"...","source":{},"context":{}}],"nextAfter":201,"nextBefore":201,"hasMore":false}

响应中 log body 最长 2000 字节;不存在 404,查询错误通常 400。

GET /api/runs/{runId}/telemetry

参数:nodeId、adapter、after、before、limit。adapter 可为 all/空、hooks、otel、live 或具体 adapter 名。成功 200:

{"runId":"run-1","sequence":120,"events":[{"id":"ev-1","sequence":101,"category":"tool","name":"tool.call","message":"...","source":{"adapter":"live","protocol":"..."}}],"nextAfter":101,"nextBefore":101,"hasMore":false}

公共响应会裁剪 message,移除 attributes、metrics、tool/modelOperation 详情,并精简 source/context。不存在 404,查询错误通常 400。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" \
  "$AGENTFLOW_URL/api/runs/run-1/logs?nodeId=implement&before=500&limit=100"

GET /api/runs/{runId}/logs.txt?nodeId={nodeId}

下载 worker 日志,200 text/plain; charset=utf-8,响应头:

Content-Disposition: attachment; filename="run-1-worker-logs.txt"

省略 nodeId 下载所有节点。最多导出 20,000 条,格式为头部注释以及时间、节点、stream、正文。run 不存在 404;导出失败通常 400。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" -OJ \
  "$AGENTFLOW_URL/api/runs/run-1/logs.txt"

GET /api/runs/{runId}/artifacts/{artifactId}

返回制品原始文本内容,200。Content-Type 为记录的 media type 加 charset=utf-8,Content-Disposition: inline,并以 SHA-256 设置 ETag。text/markdown、application/json 分别使用 .md、.json 文件名,其他类型使用 .txt。制品不存在返回 404。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" -OJ \
  "$AGENTFLOW_URL/api/runs/run-1/artifacts/artifact-1"

人工动作

以下接口成功均返回 200 {"ok":true};run/node/状态错误通常 400。与 Issue 关联且执行被关闭/交付锁定的 run,在 approve、pass、reject、retry 时返回 409。

POST /api/runs/{runId}/approve

{"nodeId":"approval"}

批准等待中的节点。

POST /api/runs/{runId}/pass

{"nodeId":"phpunit-full"}

将已失败的脚本节点视为通过并继续下游,不重新执行该节点。用于 onFailure=fail 停下来之后,或打回返工到达最大轮次后,避免硬脚本一直卡住。Agent / AI 节点不能手动通过,应走 /retry 并附带补充上下文。

POST /api/runs/{runId}/reject

{"nodeId":"approval","targetId":"implement","reason":"缺少回归测试"}

拒绝并按 targetId/工作流策略回退。

POST /api/runs/{runId}/retry

{"nodeId":"implement","reason":"修复失败测试"}

重试节点。网页调用时使用 Prefer: respond-async,把工作区恢复和节点重跑分开:

  • 工作区需要恢复时,返回 202 {"workspaceRestore":{"status":"restoring","startedAt":"..."},"retryAfterMs":1000}。恢复在后台继续,页面断开不会释放恢复任务的租约;同一 Run 的其他请求复用该恢复任务。
  • 轮询 GET /api/runs/{runId}/workspace/restore,返回 idle|restoring|ready|failed,失败时包含 error。该接口仅项目成员可读。
  • ready 后重新提交原来的重跑请求;只有 200 {"ok":true} 表示重跑已启动。可携带 expected:{"status":"succeeded","attempt":11,"reworkCount":0},避免恢复期间节点已变化时重跑过期尝试。

页面关闭后只继续已经受理的工作区恢复;再次进入页面可查看恢复状态,再明确发起节点重跑。POST /api/runs/{runId}/resume 和 POST /api/runs/{runId}/workspace/restore 同样支持 Prefer: respond-async。不带此请求头的调用保持同步语义。

POST /api/runs/{runId}/decline-retry

{"nodeId":"implement"}

拒绝引擎建议的重试。

POST /api/runs/{runId}/cancel

无需请求字段;可使用空 JSON {}。取消 run。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" -X POST \
  -H 'Content-Type: application/json' -d '{"nodeId":"approval"}' \
  "$AGENTFLOW_URL/api/runs/run-1/approve"

Run 评测

只评测终态 run(succeeded|failed|cancelled)。使用当前登录用户的 CodeBuddy Key 和助手模型目录,不自动触发。

POST /api/runs/{runId}/eval

请求 { "model": "default" },model 可选。成功 202 返回评测记录(status=running)。进行中的 run 返回 409;未登录 401;未配置个人 CodeBuddy Key 400。

GET /api/runs/{runId}/eval

最新一次评测。尚无记录时 200 且 status 为空。

GET /api/runs/{runId}/evals

最近最多 10 次评测。

GET /api/runs/{runId}/eval/stream

SSE:thought / done / error。

POST /api/runs/{runId}/eval/apply

请求 { "evalId":"eval-1", "recommendationIds":["rec-1"] }。把用户确认的建议合并进当前 SOP 或角色,不改这次 run 的冻结 snapshot。通用只读模板会先克隆到项目再改。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" -X POST \
  -H 'Content-Type: application/json' -d '{"model":"default"}' \
  "$AGENTFLOW_URL/api/runs/run-1/eval"

指标与分析

GET /api/workflow-metrics

返回全部 WorkflowMetrics[],200。每项含运行数、各状态计数、闭环/成功/返工率、平均耗时、token/tool/artifact 汇总、最近运行和节点指标。

GET /api/analytics

查询参数:

  • projectId、workflowId:可选过滤;
  • userId、issueSource:按责任人或需求来源(local、gongfeng、tapd)过滤;
  • scope=overview:返回用量页所需的轻量聚合,跳过交付扫描;
  • grain:趋势粒度,可选 day、week、month、all(按月聚合全部历史);
  • from、to:可选 RFC 3339 时间;无效值返回 400。

成功 200 返回 AnalyticsSnapshot:filter、summary、trend、按 workflow/agent/executor/model/node 的 breakdown、failures、coverage、deliveries 和 delivery。demo 提供平均 Token、工具成功率、平均人工干预和自动完成率;runTraces 提供 TAPD/Issue → workflow_task_id → run_id → trace_id 的下钻索引,原始事件继续通过 Run telemetry 分页接口读取。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" \
  "$AGENTFLOW_URL/api/analytics?projectId=platform&from=2026-09-01T00%3A00%3A00Z"

GET /api/observability/spec

返回运行时支持的公共观测规范说明对象,200。这是能力描述,不是数据摄取端点;内部 /api/otel/v1/traces 不属于公共 API。

定时任务

ScheduleJob 分两类,由 skipDispatch 区分,不能写在同一条任务里。

触发任务(skipDispatch=false)字段包括 id、name、enabled、projectId、workflowId / useIssueWorkflow、intervalSec 或 cron、最近执行结果和时间戳。到点扫描本项目未运行需求,做基线门禁再派发 SOP;仓库集成分支冲突会把任务标成 waiting 并带上 blockers,暂停自动派发;对齐 Agent 会自动解决冲突并合入基线。

触发任务可选 maxDispatch,配置每次最多成功触发的需求数,取值为 1–10;不配置(或为 0)时默认为 10,旧任务同样适用。自动执行和「立即运行」共用此上限;已有任务、基线阻塞或派发时被跳过的需求不占用名额,其余需求留待后续执行。lastPulled 仍记录所有匹配候选数,lastDispatched 记录本次实际成功触发数。AI 定时任务不使用此配置。

AI 定时任务(skipDispatch=true)字段包括 id、name、enabled、projectId、assistantPrompt、assistantModel、ownerUserId 以及 intervalSec 或 cron。触发后以保存人的身份开启一轮完全权限对话,使用任务的提示词。模型目录通过 GET /api/assistant/models?schedule=1 读取。

AI 定时任务固定使用自动执行模式,不受 Studio 对话审批模式影响,平台写入无需逐次人工确认。

AI 定时任务没有单独的时长上限:这一轮和普通对话一样,在 CLI 结束或有人从会话页停止时结束;工具网关跟这一轮一起结束。本实例已有定时任务运行时,到点的 cron 会被跳过,不排队、不在当前任务结束后补跑;等待下一个 cron 时间。手动运行仍返回 409。

GET /api/schedule-jobs

返回全部 ScheduleJob[],200,不分页。

POST|PUT /api/schedule-jobs

新建或按 id 更新,两种方法语义相同。name 必填。调度为 intervalSec(常用间隔)或 5 段 cron(东八区)。AI 定时任务需要 assistantPrompt 或共享任务版本。触发任务需要 workflowId,可选 useIssueWorkflow。更新时若请求未带 blockers,沿用触发任务的基线暂停状态。

服务端把 runAsUserId 绑定到本次保存的登录用户。Codex 和 Claude Code 优先使用该用户默认个人执行机器上的「账号登录」,需要 Runner 0.10.2 或以上及已启用的 CLI。默认机器离线或未启用账号登录时,以该用户的个人 API Key 在云端执行任务指定的 CLI 和模型。Key 缺失或执行失败时,任务记录具体原因。CodeBuddy 缺少个人 Key 时使用平台共享 Key,只能选择管理员允许的模型。模型为空或 default 时取共享 Key 的默认模型。没有执行身份的旧任务依次尝试项目 Owner、独立任务记录的 Owner 的个人凭据,最后尝试平台共享 Key。

缺少凭据的保存返回 400。没有凭据的项目成员也可以停用执行配置未变的任务,服务端在行锁内重新核对项目和执行配置,然后仅将 enabled 改为 false。若并发修改使核对失败,返回 409。

AI 定时任务的 sessionMode 为空时每次执行新开一个会话,fixed 时始终在同一个会话里继续;每次新开时用 sessionKeep 设置保留最近多少个会话(10 / 50 / 100,-1 不限,不传默认 50,其他值 400),每次执行结束后删除更早的会话,执行记录不受影响。

id 为空时生成;projectId 默认 platform;intervalSec<30 时重置为 300。更新若不提供 lastRunAt 会保留已有最近运行字段。成功 200 返回 job;校验/存储错误 400。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name":"自动修线上单","enabled":true,"projectId":"platform","workflowId":"wf-dev","useIssueWorkflow":true,"intervalSec":3600}' \
  "$AGENTFLOW_URL/api/schedule-jobs"

DELETE /api/schedule-jobs/{id}

成功 200 {"ok":true};不存在/删除失败通常 400。

POST /api/schedule-jobs/{id}/run

在服务端启动一次 job,202 返回 lastStatus=running 的 ScheduleJob。这次 HTTP 调用不等待扫描、AI 提示词或派发完成;关闭浏览器或断开 MCP 客户端都不会取消。用 GET /api/schedule-jobs 轮询,直到 lastStatus 变为 success / failed / waiting。被派发的 SOP 仍作为独立长任务运行。

  • 当前实例 AGENTFLOW_SCHEDULER_ENABLED=false 时返回 409。
  • 已有定时任务正在本实例运行时返回 409。
  • job 不存在时通常 400。
  • 启动后的失败写在 job 的 lastStatus / lastError,不通过这次 POST 的 HTTP 状态码返回。
curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" -X POST \
  "$AGENTFLOW_URL/api/schedule-jobs/job-1/run"

POST /api/schedule-jobs/{id}/enabled

启用或停用 job 的定时调度,请求体 {"enabled": true|false},200 返回更新后的 ScheduleJob。只改 enabled:提示词、执行身份(runAsUserId)和会话模式保持不变;正在运行的那次执行不会被中断。需要该项目的写权限(只读成员 403),job 不存在 404,缺少 enabled 时 400。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" -X POST -H 'Content-Type: application/json' \
  -d '{"enabled":false}' "$AGENTFLOW_URL/api/schedule-jobs/job-1/enabled"

GET /api/schedule-job-executions

返回执行记录 ScheduleJobExecution[],按开始时间倒序。每次运行(定时触发或手动运行)对应一条记录,包含 status(running / success / failed / waiting)、error、durationMs、候选与派发数、AI 回复摘要,以及派发出的 runs[](issueId、runId)。每个 job 保留最近 200 条,删除 job 时一并删除。AI 执行带 sessionId。执行记录比会话保留得久(会话按 sessionKeep 和保留期限清理,也可能被手动删除),因此列表在每次读取时检查会话是否还在:已不存在时返回 sessionGone: true。这个字段只在读取时计算,不会写入记录;进行中的执行不做标记。

每次执行认领时生成 32 位十六进制 traceId,同时写入 job 的 lastTraceId 和这次执行的所有调度日志(schedule job <id> trace=<traceId>: …),可以按它在服务端日志里检索失败原因。平台工具 schedule_job_executions_list(/mcp 与 Studio 助手均可用)对应这个接口,把复制的 Trace ID 贴给助手时,助手会按 query.traceId 查询这次执行。服务重启时,重启前仍为 running 的执行记为 failed(「上次运行中断(服务重启)」)。

查询参数:projectId、jobId、status、traceId、limit(默认 100,最大 500)。只返回调用方可读的 job 的记录;jobId 指向无权读取的 job 时返回 403。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" \
  "$AGENTFLOW_URL/api/schedule-job-executions?projectId=platform&status=failed"

GET /api/schedule-job-executions/dashboard

执行记录看板的一页,筛选、计数、分页都在服务端完成。参数:projectId(必填)、jobId、status、since(RFC 3339,只看此后开始的执行)、q(不区分大小写,匹配任务名、任务 ID、Trace ID、错误、AI 回复和派发的运行)、offset、limit(默认 20,最多 100)。返回:

  • items:当前页的执行记录,按开始时间倒序,字段同上(含 sessionGone);
  • total:符合筛选条件的记录数;
  • overview.current / overview.previous:最近 7×24 小时(含当前小时)与再往前 7×24 小时的 total、finished、success、failed、running、avgMs,只随 jobId 变化。已结束的执行来自按小时累计的统计表 schedule_job_execution_stats(保留 30 天,删除任务时一并删除),不受每个任务只保留 200 条记录的影响;进行中的执行从记录里数;
  • records:该项目保留的记录总数;recentFailed:该项目最近 7 天的失败次数(标签角标用)。

缺 projectId 或 since 格式不对返回 400;jobId 属于无权访问的项目返回 403。统计表从部署后开始累计,部署前的执行不计入概览。

curl -u "$AGENTFLOW_USER:$AGENTFLOW_PASS" \
  "$AGENTFLOW_URL/api/schedule-job-executions/dashboard?projectId=platform&status=failed&offset=0&limit=20"

定时派发会冻结集成分支上下文,并避免同一需求重复执行。需求是否澄清过不影响派发。Worker signals、实例 lease 和沙箱回收属于内部机制,不是调度公共 API。