API 参考 / support

客服气泡收件：提交 Bug 反馈或产品需求（无鉴权）

POST /api/v1/support/tickets · createSupportTicket

公开收件端点（multipart/form-data）：官网访客与登录用户经客服气泡提交 Bug 反馈（type=bug） 或产品需求（type=feature）。提交只落平台收件箱（support_intake），不创建任何业务对象 （B-00113 / 决策 D6）——此前它在未登录状态下直接往支持项目里建真实缺陷 / 需求，任何匿名 脚本都能污染 PM 真值。是否成为正式单由运营在后台审核后经 adminConvertSupportIntake 决定。 请求带会话 cookie 时，服务端从已验证会话解析 canonical userId 与注册邮箱 随收件记录留存，并忽略请求体的 contact；伪造的 contact 不能覆盖登录身份。 匿名提交才使用可选 contact，若填写必须是合法邮箱形态，否则 422（B-00357）。 客户端一旦携带会话 cookie，失效会话返回 401，身份存储查询失败返回 500； 两者都不得降级为匿名成功收件。

附件本体真存（B-00251）：files ≤5 个、单个 ≤25MiB，本体落对象存储，元数据（含 id） 记在收件记录上，超管经 adminDownloadSupportIntakeAttachment 取本体。响应的 attachmentsStored 是已落存储的数量。此前只登记文件名、本体直接丢弃，而界面全程 没有一个字说明——用户以为截图交上去了。 匿名可写对象存储的安全边界：① 类型按扩展名白名单判定，不信客户端 Content-Type； 与项目附件消费同一份生成策略，.md / .html / .js 只按不可信源码保存并强制下载， .svg、可执行文件与其他脚本类型仍拒绝；② 声明大小先拒、读取时再按上限实读复核，防谎报 size；③ 存储键由服务端生成，绝不用用户文件名拼，文件名只经消毒后用于展示；④ 沿用 下面两道按 IP 的反滥用闸，附件不额外开豁免。 对象存储未配置时，带附件的提交整单返回 503（可不带附件重试）——不做「存不下就退回 只记文件名」的降级，那正是本条缺陷本身。不带附件的提交不受影响。 错误码分工（B-00260）：请求不是 multipart/form-data → 415；multipart 解析失败 （边界损坏等）→ 400；请求体总大小超服务端上限 → 413；字段 / 附件不合规 → 422。 反滥用两道闸（B-00253）：洪泛闸按客户端 IP 对每一次请求计数（不论成败）； 收件额度只由成功收件消费——校验退回、未开通、服务端出错都会退还，填错不再扣额度。 任一闸超限返回 429，且必带 Retry-After（秒）与写明等待时长的中文 detail。 支持功能未启用时返回 503（这不是请求有问题，是这个部署未开通收件）。

source=agent 是同一公开收件链路上的受控渠道标签，不提供身份或权限。Agent 提交必须带 本次报告的随机 UUID idempotencyKey、userConfirmed=true、插件版本与受控宿主信息； 缺少确认或命中 token、Cookie、配置正文、邮箱、私钥、完整 HTTP 请求体等敏感内容时返回 422。相同 key 与相同规范化 payload 返回同一 sup_* 回执并标记 idempotentReplay=true； 相同 key 配不同 payload 返回 409 idempotency_conflict。幂等重放仍计入洪泛闸，但不重复 保存附件，也不消耗成功收件额度。来源标签不改变限流、审核、转单目标或任何权限。

公开端点，无需鉴权。

请求体

type（必填）
enum；取值：bug / feature
title（必填）
string
module
string
severity
enum；取值：blocker / major / minor
description
string
role
string
contact
string
source
enum；取值：human / agent
idempotencyKey
string
userConfirmed
boolean —— source=agent 时必须为 true，仅表示插件已完成本次显式确认，不构成授权
pluginVersion
string
hostType
enum；取值：codex / claude_code
hostVersion
string
operationId
string —— 可选，仅允许公开 OpenAPI operationId
traceId
string —— 可选，仅允许 ProblemDetails traceId
reproduction
string —— 可选，用户主动提供且已经脱敏的最小复现；禁止完整请求体
files
file[]

响应字段 · 202

id（必填）
string —— 收件编号，供用户跟进引用
type（必填）
enum；取值：bug / feature
status（必填）
enum —— 收件恒从待审核起步；取值：pending
attachmentsStored（必填）
integer
idempotentReplay
boolean

错误

请求示例（curl）

curl -X POST "https://workflow.games/api/v1/support/tickets" \
  -F "type=bug" \
  -F "title=示例标题" \
  -F "module=示例文本" \
  -F "severity=blocker" \
  -F "description=一段描述文字" \
  -F "role=示例文本" \
  -F "contact=示例文本" \
  -F "source=human" \
  -F "idempotencyKey=示例文本" \
  -F "userConfirmed=true" \
  -F "pluginVersion=示例文本" \
  -F "hostType=codex" \
  -F "hostVersion=示例文本" \
  -F "operationId=018f3c2e-0000-7000-8000-000000000000" \
  -F "traceId=018f3c2e-0000-7000-8000-000000000000" \
  -F "reproduction=示例文本" \
  -F "files=@截图.png"

响应示例

HTTP/1.1 202
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "type": "bug",
  "status": "pending",
  "attachmentsStored": 1
}

合同真值：OpenAPI 3.1（0.1.0）。

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

Workflow 正在加载…