API 参考 / sync

项目级增量变更流（需求 / 子任务 / 缺陷）

GET /api/v1/sync/changes · listSyncChanges

「只拉变过的」项目级读面：把需求（requirement）、子任务（work_item）、缺陷（bug） 三类对象按 updatedAt 合成一条变更流，供 Agent 插件把线上单据刷成本地索引 （Room | 单号 | 标题 | 状态 | 更新时间）。服务器不记任何客户端状态。

用法：首次不带 updatedSince 走全量——覆盖的对象集合与 GET /requirements?view=summary + GET /work-items 翻到底一致（只回未删除对象），记录永远只有下面八个字段、不含正文； 之后把上次响应的 serverTime 原样当 updatedSince 传回，只拿 updatedAt 严格晚于它的 记录（不用本机时钟）。updatedSince 恰好等于某条 updatedAt 时该条不返回；毫秒级差异会返回。

墓碑：带 updatedSince 时，保留期（30 天）内被软删的对象以墓碑返回——deletedAt 非空， 其余字段是删除时刻的快照；客户端据此把它从本地索引里删掉。全量模式不回墓碑。 updatedSince 早于 serverTime − 30 天 返回 410（urn:gameflow:problem:sync-watermark-expired）， 客户端改走全量。

分页：nextCursor 非空则带上它继续拉，其余参数（updatedSince / types / roomId） 必须原样带上——游标绑定这三样，换了参数返回 422；翻页期间每一页的 serverTime 都是 第一页取样的值，拿任何一页的都安全。翻到 nextCursor 为空即拿全。

可见性：需要 view_project；三类对象分别按「需求」（requirement / work_item）与 「缺陷」（bug）模块的 read 等级过滤——读不了的那一类整类不出现，不返回 403（与 /search 同口径）。调用方自己声明 Accept-Encoding: gzip 才拿到压缩正文。

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

参数

updatedSince
string —— 时间水位，ISO 8601 / RFC 3339（建议 UTC 毫秒，如 `2026-09-10T02:00:00.000Z`； 带时区偏移也接受，按 UTC 比较）。只返回 `updatedAt` **严格晚于**它的记录，含墓碑。 省略 = 全量（不含墓碑）。不是合法时间戳返回 `422`；早于保留期返回 `410`。
types
string —— 逗号分隔的对象类型：`requirement`、`work_item`、`bug`。省略 = 全部三类。 未知类型返回 `422`，不静默忽略。
roomId
string —— 按需求室收窄（UUID）。⚠️ 收窄后只能看到「现在在这个室里」的对象——被移出该室的对象 不会再出现在它的增量里；要维护完整索引请按项目拉、在本地按 `roomId` 分组。 非 UUID 返回 `422`。
limit
integer —— 每页条数，默认 100，上限 250（与其它列表端点一致；更大的值被压到 250）。
cursor
string —— 上一页返回的 opaque `nextCursor`；绑定本轮的 `updatedSince` / `types` / `roomId`， 参数变化、伪造或损坏返回 `422`。

响应字段 · 200

items（必填）
SyncChange[]
items[].type（必填）
enum；取值：requirement / work_item / bug
items[].id（必填）
string
items[].displayKey（必填）
string
items[].roomId（必填）
string
items[].title（必填）
string
items[].status（必填）
string
items[].updatedAt（必填）
string
items[].deletedAt（必填）
string
nextCursor（必填）
string
serverTime（必填）
string

错误

请求示例（curl）

curl -X GET "https://你的项目.workflow.games/api/v1/sync/changes?updatedSince=…&types=…" \
  -H "Authorization: Bearer wfp_…"

响应示例

HTTP/1.1 200
{
  "items": [
    {
      "type": "requirement",
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "displayKey": "示例文本",
      "roomId": "018f3c2e-0000-7000-8000-000000000000",
      "title": "示例标题",
      "status": "示例文本",
      "updatedAt": "2026-08-01",
      "deletedAt": "示例文本"
    }
  ],
  "nextCursor": "示例文本",
  "serverTime": "示例文本"
}

合同真值：OpenAPI 3.1（0.1.0）。

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

Workflow 正在加载…