API 参考 / requirements

需求列表

GET /api/v1/requirements · listRequirements

返回当前项目的需求列表，支持 cursor 分页；当前项目由 Host/session 上下文解析。

摘要视图（view=summary）：列表默认下发每条需求的完整 description， 而正文常年承载完整执行提示词（每条可达 10 KB 量级），于是「翻一页列表」要拖走 整页正文。实测 ?limit=250 单次响应 295 KB（gzip 66 KB）——而列表 UI 与 Agent 的检索场景都只看标题、状态、负责人这些摘要字段。 view=summary 只裁掉 description 一个字段，体积按项目正文长度可降一个数量级； 需要正文时按 UUID 打开单条 GET /requirements/{requirementId} 取， 与 /search 一贯的「列表给摘要、详情给正文」口径一致。

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

参数

roomId
string —— 按需求室（room_id）过滤，回答"这个需求室收纳了哪些需求"。缺省返回全部需求（含未归属室的）。
view
string —— 响应视图。`full`（缺省）= 与此前行为完全一致，含 `description`； `summary` = 裁掉 `description`，其余字段不变。 未知取值返回 422，不静默回落 `full`——把 `sumary` 拼错却拿到一份带正文的响应， 比直接报错难查得多（与 `getScheduleSnapshot` 的 `sections` 同一口径）。
limit
integer
cursor
string

响应字段 · 200

items（必填）
Requirement[]
items[].id（必填）
string
items[].displayKey（必填）
string
items[].title（必填）
string
items[].description
string
items[].roomId（必填）
string
items[].status（必填）
string
items[].priority（必填）
enum；取值：P0 / P1 / P2 / P3
items[].risk（必填）
enum；取值：high / medium / low
items[].ownerId（必填）
string
items[].creatorId（必填）
string
items[].module（必填）
string
items[].category（必填）
string
items[].releaseWindowId（必填）
string
items[].startOn（必填）
string
items[].targetOn（必填）
string
items[].progress（必填）
integer
items[].estimateDays（必填）
integer
items[].stateEnteredAt（必填）
string
items[].createdAt（必填）
string
items[].updatedAt（必填）
string
nextCursor（必填）
string
view（必填）
enum；取值：full / summary

错误

请求示例（curl）

curl -X GET "https://你的项目.workflow.games/api/v1/requirements?roomId=…&view=…" \
  -H "Authorization: Bearer wfp_…"

响应示例

HTTP/1.1 200
{
  "items": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "displayKey": "示例文本",
      "title": "示例标题",
      "roomId": "018f3c2e-0000-7000-8000-000000000000",
      "status": "示例文本",
      "priority": "P0",
      "risk": "high",
      "ownerId": "018f3c2e-0000-7000-8000-000000000000",
      "creatorId": "018f3c2e-0000-7000-8000-000000000000",
      "module": "示例文本",
      "category": "示例文本",
      "releaseWindowId": "018f3c2e-0000-7000-8000-000000000000",
      "startOn": "2026-08-01",
      "targetOn": "2026-08-01",
      "progress": 1,
      "estimateDays": 1,
      "stateEnteredAt": "示例文本",
      "createdAt": "示例文本",
      "updatedAt": "2026-08-01"
    }
  ],
  "nextCursor": "示例文本",
  "view": "full"
}

合同真值：OpenAPI 3.1（0.1.0）。

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

Workflow 正在加载…