文档列表

GET /api/v1/documents · listDocuments

返回当前项目文档列表；可按 requirementId 过滤。文档属于项目业务库对象，不从需求或排期临时派生。 cursor 分页（B-00084）：ORDER BY updated_at DESC, id，游标是 (updated_at, id) 的 keyset 定位。 requirementId 只是一维过滤参数，两条路径都产 nextCursor——「加了过滤就天然有界」是 B-00063 → B-00064 → B-00069 已证伪三次的假设。翻页口径：带 limit（服务端 clamp，最大 250）并跟着 nextCursor 翻到底；空 nextCursor 是唯一的结束信号，短页不是。游标是不可透明拼接的 token，原样回传，不得自行构造；伪造 / 损坏 / 跨端点串用的游标返回 422（不静默从头重来—— 静默重置会把调用方的真实 bug 藏成「数据莫名其妙重复了」）。

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

参数

requirementId: string
limit: integer
cursor: string

响应字段 · 200

items（必填）: Document[]
items[].id（必填）: string
items[].displayKey（必填）: string
items[].title（必填）: string
items[].body（必填）: string
items[].summary: string
items[].type（必填）: enum；取值：spec / note / release_plan / qa_plan / custom
items[].status（必填）: enum；取值：draft / in_review / published / archived
items[].ownerId（必填）: string
items[].requirementId: string
items[].externalUrl: string —— 外部知识库链接（如 GitHub 仓库 / 文件地址）。过渡形态：真实文档方向转外部 Git 知识库，本字段承载点击跳转的外链，body 仍是本地 Markdown 只读内容。
items[].createdAt（必填）: string
items[].updatedAt（必填）: string
nextCursor（必填）: string —— 下一页游标；空串 = 已到最后一页。**短页不是结束信号**——只读一页的调用方会静默丢掉 limit 之后的全部文档（B-00084 就是这个字段声明了 required 却从未被实现设置）。

错误

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

请求示例（curl）

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

响应示例

HTTP/1.1 200
{
  "items": [
    {
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "displayKey": "示例文本",
      "title": "示例标题",
      "body": "示例文本",
      "type": "spec",
      "status": "draft",
      "ownerId": "018f3c2e-0000-7000-8000-000000000000",
      "createdAt": "示例文本",
      "updatedAt": "2026-08-01"
    }
  ],
  "nextCursor": "示例文本"
}

合同真值：OpenAPI 3.1（0.1.0）。

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