API 参考 / ai

排期传播 AI 只读解释

POST /api/v1/ai/schedule/explanation · explainSchedulePropagation

使用当前 Schedule Snapshot dry-run 传播结果、里程碑、版本窗口与 owner load 生成解释；不应用传播、不写库。

鉴权：项目 API Token（Authorization: Bearer wfp_…）。详见 Agent 接入。

请求体

workItemId（必填）: string
startOn: string
dueOn: string

响应字段 · 200

enabled（必填）: boolean
sections（必填）: AIExplanationSection[]
sections[].kind（必填）: enum；取值：summary / suggestion / risk
sections[].title（必填）: string
sections[].body（必填）: string
sourceRefs（必填）: AISourceRef[]
sourceRefs[].type（必填）: enum；取值：requirement / work_item / changeset / event / schedule / propagation / milestone / release_window / owner_load
sourceRefs[].id（必填）: string
sourceRefs[].label（必填）: string

错误

403：Problem 错误响应
422：Problem 错误响应

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/ai/schedule/explanation" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"workItemId":"018f3c2e-0000-7000-8000-000000000000","startOn":"2026-08-01","dueOn":"2026-08-01"}'

响应示例

HTTP/1.1 200
{
  "enabled": true,
  "sections": [
    {
      "kind": "summary",
      "title": "示例标题",
      "body": "示例文本"
    }
  ],
  "sourceRefs": [
    {
      "type": "requirement",
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "label": "示例文本"
    }
  ]
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引