创建工作项

POST /api/v1/work-items · createWorkItem

创建当前项目工作项；actor 与 project 只来自 session/Host 上下文。

鉴权模块按结果态 type 判定：type=bug 要求 bugs 模块 >= edit，其余（含默认 task）要求 subtasks >= edit。二选一而非叠加——只有缺陷权的角色建得出缺陷、建不出子任务，反之亦然。

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

参数

Idempotency-Key: string —— 幂等键（建议用 UUID，最长 255 字符）。重复提交同键且请求体一致时返回首次创建的结果（200）而不新建对象；请求体不一致返回 409。有效期 24 小时。

请求体

requirementId: string
severity: enum；取值：blocker / major / minor
resolution: enum；取值：fixed / wontfix / cannot_reproduce / duplicate
roomId: string
parentId: string
title（必填）: string
description: string
type: enum；取值：task / dev / qa / bug
status: string
priority: enum；取值：P0 / P1 / P2 / P3
ownerId: string
role: string
startOn: string
dueOn: string
estimateDays: integer
sortOrder: integer
customFields: object
reason: string

响应字段 · 201

id（必填）: string
displayKey（必填）: string
requirementId（必填）: string
roomId（必填）: string
severity: enum；取值：blocker / major / minor
resolution: enum；取值：fixed / wontfix / cannot_reproduce / duplicate
parentId: string
title（必填）: string
description: string
type（必填）: enum；取值：task / dev / qa / bug
availableTransitions: WorkItemTransition[]
availableTransitions[].toStateKey（必填）: string
availableTransitions[].name（必填）: string
availableTransitions[].allowed（必填）: boolean
availableTransitions[].blockedReason: string
availableTransitions[].guardCode: enum；取值：permission / missing_field / separation_of_duties / slot_empty / not_slot_member / not_visited / unknown
availableTransitions[].requireReason: boolean
availableTransitions[].href（必填）: string
availableTransitions[].method（必填）: string
status（必填）: string
priority（必填）: enum；取值：P0 / P1 / P2 / P3
ownerId（必填）: string
creatorId（必填）: string
role（必填）: string
startOn（必填）: string
dueOn（必填）: string
estimateDays（必填）: integer
progress（必填）: integer
sortOrder（必填）: integer
customFields: object
workflowVersionId（必填）: string
activeSlotKey（必填）: string
activeUserId（必填）: string
lastActorId: string
stateEnteredAt（必填）: string
slots: object
createdAt（必填）: string
updatedAt（必填）: string

响应字段 · 200

id（必填）: string
displayKey（必填）: string
requirementId（必填）: string
roomId（必填）: string
severity: enum；取值：blocker / major / minor
resolution: enum；取值：fixed / wontfix / cannot_reproduce / duplicate
parentId: string
title（必填）: string
description: string
type（必填）: enum；取值：task / dev / qa / bug
availableTransitions: WorkItemTransition[]
availableTransitions[].toStateKey（必填）: string
availableTransitions[].name（必填）: string
availableTransitions[].allowed（必填）: boolean
availableTransitions[].blockedReason: string
availableTransitions[].guardCode: enum；取值：permission / missing_field / separation_of_duties / slot_empty / not_slot_member / not_visited / unknown
availableTransitions[].requireReason: boolean
availableTransitions[].href（必填）: string
availableTransitions[].method（必填）: string
status（必填）: string
priority（必填）: enum；取值：P0 / P1 / P2 / P3
ownerId（必填）: string
creatorId（必填）: string
role（必填）: string
startOn（必填）: string
dueOn（必填）: string
estimateDays（必填）: integer
progress（必填）: integer
sortOrder（必填）: integer
customFields: object
workflowVersionId（必填）: string
activeSlotKey（必填）: string
activeUserId（必填）: string
lastActorId: string
stateEnteredAt（必填）: string
slots: object
createdAt（必填）: string
updatedAt（必填）: string

错误

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

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/work-items" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"title":"示例标题","requirementId":"018f3c2e-0000-7000-8000-000000000000","severity":"blocker"}'

响应示例

HTTP/1.1 201
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "displayKey": "示例文本",
  "requirementId": "018f3c2e-0000-7000-8000-000000000000",
  "roomId": "018f3c2e-0000-7000-8000-000000000000",
  "title": "示例标题",
  "type": "task",
  "status": "示例文本",
  "priority": "P0",
  "ownerId": "018f3c2e-0000-7000-8000-000000000000",
  "creatorId": "018f3c2e-0000-7000-8000-000000000000",
  "role": "示例文本",
  "startOn": "2026-08-01",
  "dueOn": "2026-08-01",
  "estimateDays": 1,
  "progress": 1,
  "sortOrder": 1,
  "workflowVersionId": "018f3c2e-0000-7000-8000-000000000000",
  "activeSlotKey": "示例文本",
  "activeUserId": "018f3c2e-0000-7000-8000-000000000000",
  "stateEnteredAt": "示例文本",
  "createdAt": "示例文本",
  "updatedAt": "2026-08-01"
}

合同真值：OpenAPI 3.1（0.1.0）。

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