← 返回 Docs CenterLive

technical

API 合同

当前已经落地的 workflow、Profiles、Targets API、run-preview 合同，以及后续 Auth、Settlement 的预留接口位。

Audience

开发者 / 集成者

Updated

2026-03-24

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
  • GET /api/profiles
  • POST /api/profiles
  • GET /api/profiles/:profileId
  • GET /api/targets
  • POST /api/targets
  • GET /api/targets/:targetId

当前接口语义

staging 上的 workflow、Profiles、Targets API 已接 cloudflare-d1，本机默认仍保留 local dev file store 回退。

页面与 API 合同已经稳定，下一步只需要继续把本机链路和执行链路收口到 D1-first，不需要改接口地址。

run-preview 当前合同

  • 返回 workflowId、generatedAt、estimatedCredits、aiReadiness、steps、aiRuntime、reviewGate 与 resultGate
  • 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 测试条件

已预留但未实现

  • GET /api/runs/:id
  • GET /api/usage
  • Auth / RBAC / Billing API
  • Developer Supply / Settlement API