← 返回 Docs CenterLive

technical

API 合同

当前控制平面 API 已统一到 ok / meta / data / error 返回包装，并把 run lifecycle、failure evidence、endpoint inventory、target detail 与 store adapter 边界一起收口进代码。

Audience

开发者 / 集成者

Updated

2026-03-30

Source

docs/api-contracts.zh-CN.md

当前已落地

  • GET /api/workflows
  • POST /api/workflows
  • GET /api/workflows/:workflowId
  • PUT /api/workflows/:workflowId
  • POST /api/workflows/:workflowId/run-preview
  • POST /api/workflows/:workflowId/accept-run
  • GET /api/runs/:runId
  • GET /api/runs/:runId/evidence/:evidenceId
  • POST /api/runs/:runId/pickup
  • POST /api/runs/:runId/fail
  • POST /api/runs/:runId/retry
  • POST /api/runs/:runId/complete
  • GET /api/profiles
  • POST /api/profiles
  • GET /api/profiles/:profileId
  • PUT /api/profiles/:profileId
  • GET /api/targets
  • POST /api/targets
  • GET /api/targets/:targetId

当前统一包装

当前 workflow、Profiles、Targets、run-preview 与 accept-run 已统一使用 ok / meta / data / error 控制平面返回包装。

workflow 前端 client 当前也会给 create / save / preview / accept-run 默认带上 actor email，便于在完整登录系统落地前保持合同与 staging proof 一致。

src/lib/platform/api-contract.ts 现在已经同时维护 request 类型、response 类型与 controlPlaneEndpointInventory，不再只靠文档里的 body 示例同步接口真相。

workflow-canvas 当前也开始通过共享的 workflow client 消费 list / detail / save / preview / accept 与 registry readiness，不再在组件里散落 request 细节。

Profiles 页面当前也开始通过共享的 registry client 消费 list / detail / create / update 合同，Targets 页面开始消费 list / detail / create 合同，不再在组件里散落 request 细节。

Runs workbench 当前也开始通过共享的 runs client 消费 list / detail / pickup / fail / retry / complete 合同，不再在组件里散落直接 fetch 与 envelope 判断。

唯一明确的例外是 GET /api/runs/:runId/evidence/:evidenceId：它成功时直接返回原始 evidence body 与 content-type，用来承接 R2 中的失败证据读取。

workflow-canvas 当前还会预加载 target detail 合同，用 active schema / field templates / review 字段驱动 Autofill 推荐映射。

query / route param 当前也开始通过共享 helper 收口，前端 control-plane client 会保留 error.code / details，便于页面只消费稳定错误语义。

workflow / registry store 当前也开始通过 src/lib/server/store-contracts.ts 暴露显式 adapter 合同，service 与 route 不再直接判断 local 或 D1 分支。

meta 当前会带 source、requestId 与 generatedAt，用来服务 staging smoke、后续 run ledger、usage 与审计排查。

route handler 当前开始只保留 HTTP 与响应包装职责，具体业务动作正在往 workflow-service / registry-service 收口。

Runs / Usage 已开始走 D1 优先的 GET API 读取链路，Team 继续保留 scaffold 入口，用于承接后续真实成员与权限数据。

当前 request 合同

  • POST /api/workflows 使用 WorkflowCreateRequest
  • PUT /api/workflows/:workflowId 使用 WorkflowSaveRequest
  • POST /api/workflows/:workflowId/run-preview 使用 WorkflowPreviewRequest
  • POST /api/workflows/:workflowId/accept-run 使用 WorkflowAcceptRequest
  • POST /api/runs/:runId/pickup 使用 RunPickupRequest
  • POST /api/runs/:runId/fail 使用 RunFailRequest
  • POST /api/runs/:runId/retry 使用 RunRetryRequest
  • POST /api/profiles 使用 ProfileCreateRequest
  • PUT /api/profiles/:profileId 使用 ProfileUpdateRequest
  • POST /api/targets 使用 TargetCreateRequest

当前 data 语义

  • GET /api/workflows 返回 data.workflows，详情与保存返回 data.workflow
  • GET /api/profiles 返回 data.profiles，创建、详情与更新返回 data.profile
  • GET /api/targets 返回 data.targets，创建返回 data.target，target detail 额外返回 schemaVersions、active schema / field templates / review fields
  • POST /api/workflows/:workflowId/run-preview 返回 data.preview
  • POST /api/workflows/:workflowId/accept-run 返回 data.run
  • GET /api/runs/:runId 返回 data.run，并继续带 latestAttempt、retry、executorReceipt、terminalResult、executorArtifacts 与持久化后的 failure evidence metadata
  • POST /api/runs/:runId/fail 返回 data.run，并把 failure detail、retry summary 与 durable evidence summary 一起暴露出来
  • GET /api/runs/:runId/evidence/:evidenceId 成功时直接返回原始 evidence body，不走 envelope
  • POST /api/runs/:runId/complete 返回 data.run
  • GET /api/runs 返回 data.records、data.stats 与 data.filterOptions
  • GET /api/usage 返回 data.entries、data.snapshot 与 data.filterOptions
  • GET /api/team 返回 data.members、data.stats 与 data.filterOptions

当前 store adapter 边界

  • src/lib/server/store-contracts.ts 当前已经定义 WorkflowStoreAdapter 与 RegistryStoreAdapter
  • workflow-store.ts 当前默认要求 cloudflare-d1，只有显式设置 TOOLPLANE_ENABLE_WORKFLOW_LOCAL_FALLBACK=1 时才允许回退到 local-dev-file-store
  • registry-store.ts 当前已把 profiles 与 targets 的 adapter 选择拆开：profiles 默认要求 cloudflare-d1，只有显式设置 TOOLPLANE_ENABLE_PROFILE_LOCAL_FALLBACK=1 时才允许回退；targets 现在也默认要求 cloudflare-d1，只有显式设置 TOOLPLANE_ENABLE_TARGET_LOCAL_FALLBACK=1 时才允许回退
  • route handler、service 与前端共享 client 继续只消费 list / detail / create / save / accept / complete 这些稳定方法，不感知底层存储来源
  • 模块三把 D1 切成主持久化时，默认只需要替换 adapter 选择与实现，不需要重改页面路由、service 边界或响应 envelope

当前 Day 7 验证路径

  • scripts/module2-api-shape-lock.mjs 当前会锁定 workflow create / workflow save / profiles / targets / runs detail / runComplete / team invite / team activate 的 actor 错误语义与 D1-backed 写路径合同
  • Windows 本机现在可先跑 d1:migrate:local:windows 与 d1:seed:local:windows，再启动本地服务并执行 verify:module2:contracts:local
  • 这一步的目标是把 API 形状锁住，而不是只验证页面能打开

run-preview 当前合同

  • run-preview 现在会返回 executionBoundary 与 creditBoundary，用来同时明确执行边界与 credit gate。
  • data.preview 会带 workflowId、generatedAt、estimatedCredits、aiReadiness、steps、aiRuntime、reviewGate、resultGate 与 creditBoundary
  • Autofill fieldCandidates 会带上 aiPrompt、maxLength、provider、model、promptVersion、schemaVersion、usedFallback 与 fallbackReason
  • 支持可选 reviewDecisions request body，允许前端把 approve / reject 决策带回 run-preview
  • Review steps 会带上 reviewItems，说明哪些字段与策略门禁需要人工确认，并回传当前 decision
  • Review / Result steps 会带上 gateStatus 与 gateSummary，用来驱动结构化门禁展示
  • 未配置 provider 或请求失败时，预演会明确回退到 local-template，并把原因写回结果
  • aiReadiness 会给出 status、missingFields、canUseProvider 与 recommendation，用来判断是否已具备半真实 provider 测试条件

accept-run 当前合同

  • 只有当 resultGate 为 ready 或 not_required 时，当前预演才能被接受为真实 queued run
  • POST /api/workflows/:workflowId/accept-run 会返回 runId、reservedCredits、remainingBalance、usageEventId 与 summary
  • accept-run 现在也会返回 executionBoundary 与 creditBoundary，明确说明 queued run、run steps 快照、reserved credits、wallet 扣减与 testing-consumes-credits 规则是在 accept 阶段一起生效的。
  • 同一个 idempotencyKey 如果对应 run 已经进入 terminal 状态，accept-run 会诚实返回 accepted，而不是重复创建新 run
  • 支持可选 idempotencyKey，用来避免重复验收或重复点击时无限新增 run 与重复预留 credits
  • D1-backed workflow path 上当前会把 accepted run 写入 workflow_runs、workflow_run_steps、credit_transactions 与 credit_wallets

complete-run 当前合同

  • POST /api/runs/:runId/complete 当前用于把 queued run 推进到 accepted terminal 状态
  • 调用后会回写 workflow_runs、workflow_run_steps、credit_consumed 与 run.completed 审计事件，并把 actor_user_id 回写为当前 actor
  • complete-run 现在会返回 executionBoundary 与 creditBoundary，明确说明 terminal 阶段只做 reservation settlement，不会再次扣减 wallet balance。
  • 当前 credit_consumed 的语义是把已预留 credits 结算为已消费，不会再次扣减 wallet balance
  • 如果 run 已经是 accepted，则会返回 alreadyCompleted=true，便于 staging 验收脚本幂等重复执行

run detail 当前合同

  • GET /api/runs/:runId 当前会返回 run 本体、step payload、run-scoped ledger entries 与 audit trail
  • run detail 现在会返回 executionBoundary 与 creditBoundary，run step payload 里也会显式带出 preview_only / queued_run / terminal_run 阶段标记。
  • 这个 detail contract 让后续真实执行器只需要补写 receipt 和 result payload，而不必重做 Runs 工作台结构
  • workflow 当前默认走 D1-backed path；只有显式打开 fallback env 时才会回到本地文件，但 envelope 结构保持一致

当前错误码

  • invalid_payload
  • workflow_not_found
  • workflow_run_not_found
  • workflow_run_invalid_state
  • workflow_run_gate_not_ready
  • workflow_run_retry_blocked
  • workflow_run_evidence_not_found
  • workflow_evidence_bucket_unavailable
  • workflow_store_d1_required
  • profile_store_d1_required
  • target_store_d1_required
  • actor_identity_required
  • profile_not_found
  • target_not_found
  • insufficient_credits
  • profile_name_required
  • target_name_required
  • target_base_url_required

已预留但未实现

  • GET /api/usage/:entryId
  • GET /api/team/:memberId
  • 真正的浏览器执行器消费 queued run，并把 pickup 从控制面模拟提升成真实 runner 回写
  • 真实 screenshot binary evidence
  • Auth / RBAC / Billing API
  • Developer Supply / Settlement API