API 参考 / work-items

工作项列表

GET /api/v1/work-items · listWorkItems

返回当前项目工作项列表；可按需求、负责人、待办人、需求室和自定义字段过滤。

每一条路径都是 cursor 分页的，带过滤维度的也一样（B-00084）：传 limit（服务端 clamp， 上限 250）并跟着 nextCursor 翻到底。nextCursor 为空是唯一的「翻完了」信号——短页不是。 只读一页的调用方会静默丢掉 limit 之后的全部条目。全部过滤维度都在 DB 层、截断之前生效， 所以 limit 与游标都作用在过滤后的子集上。游标是不透明 token：原样回传，不要自己拼； 损坏 / 过期的游标返回 422，不会静默从头重来。

行级模块可见性：本端点返回「子任务 + 缺陷」混合集合，两类分别由 subtasks 与 bugs 模块等级授权（缺陷即 type=bug 的工作项，没有独立端点）。两者之一到 read 即可调用； 没到 read 的那一类整类不会出现在结果里（不占 limit 名额）。两类都到不了 read → 403。

随列表下发可用流转（includeTransitions，B-00296）：缺陷看板/列表此前每张卡各发一次 GET /work-items/{id}/transitions，默认视图一打开就是上百个并发请求（实测单请求 0.4–1.7 s、 响应体 81 字节，典型 N+1）。传 includeTransitions=true 让本端点在同一次响应里带上每条的 availableTransitions，把 1 + N 个请求压成 1 个。 服务端按 (type, workflowVersionId, status) 去重后再算出边——同状态的卡片共用一次计算， 不是循环调 N 次。

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

参数

includeTransitions
boolean —— true 时每条 WorkItem 带上 `availableTransitions`（当前可用状态出边，与 `GET /work-items/{id}/transitions` 同一算法、同一 guard 求值）。默认 false： 既有调用方响应体一字不变。
requirementId
string
ownerId
string —— 按负责人（owner_id）过滤，回答"指派给某人的工作项有哪些"（T5.1）。支撑中央面「我的工作台」 跨项目聚合：对每个项目在其 TenantTx/RLS 内按当前用户 id 过滤。与 requirementId 同时给定时取交集。
activeUserId
string —— 按待办人（active_user_id）过滤（M2 运行面）：回答"当前轮到谁处理的工作项有哪些"。 active_user_id 由工作流路由 post-action 写入，与 ownerId 独立——owner 是负责人，activeUser 是当前激活槽的待办人（可能不同）。与 ownerId / requirementId 同时给定时取交集。
customField
string —— 按缺陷自定义字段过滤（T3.4）：与 customValue 配对使用，只保留 custom_fields[customField] == customValue 的工作项（后端 JSONB 文本相等匹配）。仅对 type=bug 有意义；不配 customValue 时忽略。
customValue
string —— 见 customField，自定义字段过滤的目标值（字符串比较）。
roomId
string —— 按需求室（room_id）过滤，回答"这个需求室收纳了哪些缺陷/工作项"。与其它过滤维度同时给定时取交集。
limit
integer
cursor
string

响应字段 · 200

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

错误

请求示例（curl）

curl -X GET "https://你的项目.workflow.games/api/v1/work-items?includeTransitions=…&requirementId=…" \
  -H "Authorization: Bearer wfp_…"

响应示例

HTTP/1.1 200
{
  "items": [
    {
      "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"
    }
  ],
  "nextCursor": "示例文本"
}

合同真值：OpenAPI 3.1（0.1.0）。

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

Workflow 正在加载…