API 参考 / search

项目级全局搜索

GET /api/v1/search · searchProject

项目内跨对象搜索：识别 R-/B-/T-/RM-/MS-/DOC- 等 displayKey 前缀做精确定位， 否则通过 PostgreSQL 搜索投影按标题、摘要或正文召回。结果以稳定 cursor 分页的全局排序 items 返回，并同时保留 groups 供旧消费者迁移。严格走当前项目 RLS 与调用者 moduleAccess， 绝不跨项目或跨权限返回结果；完整正文只在打开对象后按 UUID 获取。

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

参数

q（必填）
string —— 搜索词。displayKey（如 R-00001 / B-00001 / T-00001 / RM-00001）精确定位，其余按标题、摘要或正文召回。
types
string —— 逗号分隔的对象类型过滤；可选 requirement、bug、work_item、room、document、milestone。
scope
string —— 匹配范围，默认 mixed；title 只搜标题/单号，body 只搜摘要/正文。
status
string —— 逗号分隔的状态过滤。状态值沿用项目自定义工作流，服务端不猜测固定词表。
roomId
string —— 按需求室收窄（UUID）。只覆盖需求与工作项/缺陷——文档与里程碑在数据模型里没有需求室归属（表上没有该列），传了 roomId 就一定不返回这两类；要连文档一起查请改用 requirementId 或 types。
requirementId
string —— 按父需求收窄（UUID）。只返回归属该需求的对象（工作项 / 缺陷 / 文档）。
labelIds
string —— 逗号分隔的标签 id 过滤（UUID），最多 20 个。命中任一给定标签即算命中（OR 语义）；非 UUID 或超过 20 个返回 422。
cursor
string —— 上一页返回的 opaque cursor；绑定 indexVersion，版本切换后返回 422。
limit
integer —— 每页条数，默认 20，上限 50。

响应字段 · 200

query（必填）
string
items（必填）
SearchResultItem[]
items[].type（必填）
enum；取值：requirement / bug / work_item / room / document / milestone
items[].id（必填）
string
items[].displayKey（必填）
string
items[].title（必填）
string
items[].snippet（必填）
string —— 安全截断片段，不含完整正文或未授权内容。
items[].matchedField（必填）
enum；取值：displayKey / title / body
items[].status（必填）
string
items[].roomId
string
items[].requirementId
string
items[].updatedAt（必填）
string
items[].score（必填）
number
items[].deepLink（必填）
string —— 前端可直接跳转的项目内深链路径（如 /requirements/{uuid}）。
nextCursor（必填）
string
indexVersion（必填）
integer
metadata（必填）
SearchMetadata
metadata.types（必填）
string[]
metadata.scope（必填）
enum；取值：title / body / mixed
metadata.status
string[]
metadata.indexVersion（必填）
integer
groups
SearchResultGroup[]
groups[].type（必填）
enum；取值：requirement / bug / work_item / room / document / milestone
groups[].items（必填）
SearchResultItem[]
groups[].items[].type（必填）
enum；取值：requirement / bug / work_item / room / document / milestone
groups[].items[].id（必填）
string
groups[].items[].displayKey（必填）
string
groups[].items[].title（必填）
string
groups[].items[].snippet（必填）
string —— 安全截断片段，不含完整正文或未授权内容。
groups[].items[].matchedField（必填）
enum；取值：displayKey / title / body
groups[].items[].status（必填）
string
groups[].items[].roomId
string
groups[].items[].requirementId
string
groups[].items[].updatedAt（必填）
string
groups[].items[].score（必填）
number
groups[].items[].deepLink（必填）
string —— 前端可直接跳转的项目内深链路径（如 /requirements/{uuid}）。

错误

请求示例（curl）

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

响应示例

HTTP/1.1 200
{
  "query": "示例文本",
  "items": [
    {
      "type": "requirement",
      "id": "018f3c2e-0000-7000-8000-000000000000",
      "displayKey": "示例文本",
      "title": "示例标题",
      "snippet": "示例文本",
      "matchedField": "displayKey",
      "status": "示例文本",
      "updatedAt": "2026-08-01",
      "score": 1,
      "deepLink": "https://example.com"
    }
  ],
  "nextCursor": "示例文本",
  "indexVersion": 1,
  "metadata": {
    "types": [
      "示例文本"
    ],
    "scope": "title",
    "indexVersion": 1
  }
}

合同真值：OpenAPI 3.1（0.1.0）。

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

Workflow 正在加载…