语义 OpenAPI 设计
多平台 Agent Skill。细节按需读，勿把本文件写长：
| 文档 | 内容 |
|---|---|
| reference.md | 命名、styles、信封、错误码、完整文档生命周期、表格批量、校验 Schema |
| glossary/ | _common + 行业词表 |
| examples.md | 端到端示例 + 回归用例 T01–T15 |
| scripts/ | 预览：preview-swagger.ps1 / preview-swagger.sh（随包发布） |
| assets/ | swagger-ui.html 模板（预览时复制到工作区 openapi/） |
模式分流
| 用户信号 | 模式 | 产出 |
|---|---|---|
| 设计/生成 OpenAPI、语义→契约、写接口定义 | A | 完整 OpenAPI 文档（默认写入文件） |
| 校验 Schema、JSON Schema、校验说明、从 OpenAPI 导出 | B | JSON Schema + Markdown 说明 |
| 两者都要 / 「一并给出校验」 | A→B | 先完整契约再导出 |
| Excel / CSV / 粘贴表格批量接口（每行一条） | 表格→按行 A（可选 A→B） | 合并进同一完整文档 |
| 「只要片段」 | A 覆盖 | paths + schemas 片段（不强制落盘完整根） |
B 不重写契约（除非用户明确要求改 OpenAPI）。
完整文档 / 追加 / 预览：reference §完整文档与文件生命周期。
表格规则：reference §Excel/表格批量输入。
默认约定（未说明时采用）
| 项 | 默认 |
|---|---|
| OpenAPI | 3.1，完整文档（openapi + info + paths + 按需 components） |
| 落盘路径 | openapi/openapi.yaml（可指定；权威结果以文件为准） |
| 追加 | 已有文件则合并 paths/components/tags；同 path+method 禁止静默覆盖 |
| 路径静态段 | kebab-case（含用户给定路径，须转换） |
| 字段风格 | camelCase（可切 underscore） |
| 响应 | envelope { code, msg, data } |
业务 code |
0=成功，≠0=失败，编码 ABBCC（A=4/5） |
| 用户英文 | 保留词根，风格必转（对照写入交付说明） |
| 校验导出 | 分 request.params / request.body；载荷针对 envelope 的 data |
| 表格批量 | 按逻辑列映射；合并进同一完整文档；row=<n> 追溯；单行失败默认继续并汇总 |
| 预览 | 落盘后执行本 Skill 包内 scripts/preview-swagger.* 打开 Swagger UI（可跳过） |
完整表与触发用语见 reference。覆盖：「只要片段」「输出 JSON」「写入其他路径」「不要打开预览」等。
硬约束（评测失败点）
- 关键三件套：
path、method、成功响应结构。缺失时：追问，或交草案并标「待确认假设」——禁止当作最终契约 silently 拍板。 - 术语：查 glossary；禁拼音；实体前缀（
productName，不用裸name）。 - Styles：路径 kebab-case；字段 camelCase/underscore；用户英文/路径也转换，交付必含对照。
- 信封：默认 envelope；
code/msg/data固定短名；业务字段只在data内套用字段风格。错误体未指定时优先与成功对齐为code+msg。 - 完整文档生命周期：默认完整文档并落盘/追加；同 path+method 禁止静默覆盖；交付含文件路径；落盘后默认执行预览命令打开 Swagger UI（用户拒绝或无 GUI 则跳过并打印命令）。
- 表格批量：每行独立语义后合并进同一文件；标注行号；缺必填列且无法推断 → 记录失败、默认继续并汇总；禁止整表当一条未分行语义。
- 边界：不实现网关、代码生成、Mock、校验运行时、xlsx 解析库；不做多文件整站自动合并。越界请求说明边界并拉回契约/校验导出。
输入（自由文本或表格）
关键（缺则追问/标待确认）： path、method、成功响应结构。
常用可选： 入参/校验、领域、字段风格、响应模式（envelope/direct）、鉴权、错误码模块 BB、是否导出校验 Schema、只要片段、写入路径、JSON。
表格逻辑列： 模块名称（必填）、接口名称（可选）、接口描述（必填）、输入参数描述、输出内容描述。
流程
A → OpenAPI
- 分流意图（A / B / A→B / 表格 / 只要片段）；解析选项与目标文件路径。
- 澄清关键缺失；非关键默认并标注假设。表格：先映射列并按行组装语义块。
- 术语 → 词根（glossary）；再套 styles。reference §业务字段命名
- Styles → 路径 kebab；字段 camel/underscore。reference §Name styles
- 信封 / 错误码 → 默认 envelope；HTTP
responses+ 业务码表。reference §成功响应 · §双层错误码 - 映射校验关键字 → 组装完整文档（或片段）；
operationId默认 camelCase。 - 落盘 / 追加 → 写入或合并
openapi/openapi.yaml（或用户路径）；冲突则询问。 - 预览 → 除非用户拒绝：执行本 Skill 根目录下脚本（非工程根 scripts）：
- Windows：scripts/preview-swagger.ps1
- Unix：scripts/preview-swagger.sh
脚本会定位工作区openapi/openapi.yaml，从assets/swagger-ui.html同步预览页，后台起服务并打开浏览器；失败则打印手动命令。 - 交付（见下）。
B → 校验 Schema
输入：约定路径中的完整文档、本轮结果或用户粘贴的契约。
产出：JSON Schema（params/body，可选 data 载荷）+ 校验说明表。
规则：reference §OpenAPI→校验 Schema。$ref 默认内联；无法映射的约束写入说明。无内置校验运行时。
交付物（最小集）
A（默认）： 完整 OpenAPI 已写入目标文件 + 短说明（路径、假设/待确认、命名对照、错误码摘要）+ 已执行或已给出 Swagger 预览命令（URL / 停止方式）。
A（只要片段）： paths/schemas 片段 + 短说明（可不落盘完整根）。
表格批量： 同一完整文件；说明中按模块/row=<n>；文末失败行汇总（若有）。
B： request.params / request.body（及 envelope 时 data）JSON Schema + 校验说明表。
仅问术语时：只答字段名，不硬扩完整契约。
自检（交付前）
- [ ] 契约可解析；
$ref有效；path/method/成功体已定或已标待确认 - [ ] 路径 kebab-case；字段风格正确；用户英文已转换并有对照
- [ ] envelope 时
code/msg/data正确；code语义与 ABBCC/码表已声明 - [ ] 默认完整文档已落盘或已追加；同 path+method 未静默覆盖；已执行预览命令或已说明跳过原因/手动命令
- [ ] 若导出校验 Schema：与源 OpenAPI 一致；载荷针对
data；仅文档约束未丢弃 - [ ] 表格批量：行号可追溯、已合并进同一文件、失败行已汇总
- [ ] 未越界实现网关/代码/Mock/xlsx 解析器；B 未擅自重写契约
失败则修复或说明，禁止交付错误契约。
