写一条交接纪要

POST /api/v1/handoffs · createHandoff

在一张需求 / 缺陷上留下一条 ≤200 字的交接摘要：做了什么、怎么交接、交接文档在哪。典型调用方是刚完成该单的 Agent，写在证据评论之后、状态流转之前。

agentLabel 是必填的发送者标签（如 client / game / server，标识是哪个仓库的 Agent），服务端不推断、不猜测，缺失即 422。它只是展示用的来源标签，不参与任何鉴权，也不构成一个身份——写入者仍是 token 背后的真人用户。

纪要 append-only：没有编辑与删除端点。写入时会把目标单当前的所属需求室、单号与标题快照进纪要；目标不在任何需求室时 roomId 为空且 mirrored=false，纪要照样存库，只是没有群可镜像。

目标单在当前项目内不存在返 422 handoff_target_not_found。

镜像到飞书群由后台投递异步完成，尽力而为：投递失败不影响本次写入是否成功，也不会回滚纪要。mirrored=true 只表示「写入时该室有生效中的群绑定，会去投」，不是「已送达」。

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

参数

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

请求体

targetType（必填）: enum；取值：requirement / work_item / bug
targetId（必填）: string
agentLabel（必填）: string
summary（必填）: string
handoffRef: string

响应字段 · 201

id（必填）: string
roomId: string
targetType（必填）: enum；取值：requirement / work_item / bug
targetId（必填）: string
targetDisplayKey（必填）: string
targetTitle（必填）: string
agentLabel（必填）: string
summary（必填）: string
handoffRef（必填）: string
createdBy（必填）: string
createdAt（必填）: string
mirrored（必填）: boolean

响应字段 · 200

id（必填）: string
roomId: string
targetType（必填）: enum；取值：requirement / work_item / bug
targetId（必填）: string
targetDisplayKey（必填）: string
targetTitle（必填）: string
agentLabel（必填）: string
summary（必填）: string
handoffRef（必填）: string
createdBy（必填）: string
createdAt（必填）: string
mirrored（必填）: boolean

错误

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

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/handoffs" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"targetType":"requirement","targetId":"018f3c2e-0000-7000-8000-000000000000","agentLabel":"示例文本","summary":"一段描述文字"}'

响应示例

HTTP/1.1 201
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "targetType": "requirement",
  "targetId": "018f3c2e-0000-7000-8000-000000000000",
  "targetDisplayKey": "示例文本",
  "targetTitle": "示例标题",
  "agentLabel": "示例文本",
  "summary": "一段描述文字",
  "handoffRef": "示例文本",
  "createdBy": "示例文本",
  "createdAt": "示例文本",
  "mirrored": true
}

合同真值：OpenAPI 3.1（0.1.0）。

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