OpenAPI 说明

机器可读契约：仓库根 openapi/openapi.yaml（OpenAPI 3.1）。

• 由 raw/capabilities.json 经 scripts/build-openapi.py 生成，含全部 72 路由（method + path）
• 每个 operation 带 x-requires-max / x-requires-confirm（与总览表一致；upload 的 confirm 走 query confirm=1，其余为 JSON confirm:true；false 即无门、发即执行，见危险端点纪律）
• GET /status 标 security: []（免鉴权）；其余默认 bearerAuth
• 通用 401/403/422 语义已写入每个 operation；ApiError schema 见 components.schemas
• x-bridge 记录 bridgeApiVersion/routeCount/apiFingerprint/guideVersion/guideHash/presets/anchorModes

本站如何渲染它

本站用 fumadocs-openapi 把它变成虚拟页面（无需落盘 MDX）：

• lib/openapi.ts 用 createOpenAPI({ input: ['./openapi/openapi.yaml'] }) 加载；
• lib/source.ts 用 openapi.staticSource({ groupBy: 'tag' }) 按 Tag 生成 12 组页面，挂到侧边栏「交互式 API」分组；
• components/api-page.tsx 用 createOpenAPIPage() 渲染：参数/请求体/响应 Schema、多语言代码示例、API Playground。

Try-it 说明

交互页的 Playground（Try-it）是 fumadocs-openapi 原生能力：参数/请求体表单、 auth（Bearer）输入、发送与响应展示。token 在本机浏览器 localStorage 里， 由 fumadocs 自己存取，无需手填进文档。

重新生成

python3 scripts/build-openapi.py

输入为 raw/capabilities.json，输出覆写 openapi/openapi.yaml。 运行时升级后：重拉 /capabilities 快照 → 重跑脚本 → 重构建本站（npm run build），对照 apiFingerprint/guideHash 写 changelog。