liuooo/octo-openapi-dev-skill/octo-api

Octo API skill

设计 endpoint 时按工作流写 Go struct + swag 注释，跑 make openapi-check 校验，错误按提示修。详细规则按需读 references/api-spec.md。

1. 实现 / 修改 / 审查 endpoint 工作流

接到 "加 / 改 / 审查 X 接口" 都按这套顺序 8 步走。详细规则在 references/api-spec.md 各章节，按步骤遇到决策点时读（R 编号速查表在该文件开头）。修改场景 = 同步跑 §2 的 breaking 识别。

审查场景按下面格式输出（逐维度对照 + R 编号 + 实测）：

结尾附 make openapi-check（改动场景另加 openapi-diff）的实测结果，不要只凭目测下结论。

1.1 解析需求

示例（贯穿 1.2-1.7）：用户说"删除 matter 接口" → 资源 = matter，动作 = delete，调用方 = Bot/User，鉴权 = Bearer，非状态机 → REST DELETE

1.2-1.7 决策示例（接续示例）

1.8 本地校验

make openapi-check
# coverage → verify (gen + drift) → lint

跑通后业务代码跟 swag 自动生成的 spec 文件一起进 git。若启用 CI（可选增强，见 references/adoption.md），PR 自动跑全套 6 个 job。

失败处理：

• 环境 / 前置问题：openapi-gen 每次自动跑 doctor 自检（也可单独 make openapi-doctor），按报错提示走 references/adoption.md 对应步骤 —— 不需要 AI 手动探测环境
• coverage 失败：handler 缺 @Router 注释（按 api-spec.md E 章节模板补）
• verify 失败：spec 没重生，跑 make openapi-gen
• lint 失败：spectral 报具体规则 ID + 位置，按错误信息修
• 改了现有 endpoint：另跑 make openapi-diff 看 breaking change（详见下面 2 章）

2. 修改 endpoint + breaking 识别

根据改动范围对应不同路径：

识别 breaking change

修改 endpoint 后必跑 make openapi-diff（默认对比 origin/main），oasdiff 按 OpenAPI 语义自动分类每个改动：

• 🔴 error 严重度 = breaking → 命令 exit 1，CI 阻断
• 🟡 warning / 🟢 info = non-breaking → 通过

AI 看到 🔴 输出时主动提示用户：

本次修改 oasdiff 报告 N 个 breaking change：[转述 oasdiff error 列表]

建议：(a) 走 Deprecate 流程（见 api-spec.md H）/ (b) 暴露新版本 endpoint / (c) 跟 octo-cli 等客户端对齐后再合并。

3. AI 工作元规约

接 endpoint 任务时除工作流外的元行为约束：

• 引用规则编号说明设计依据（"按 R6 资源段要复数所以用 /matters"）—— 让用户能追溯
• 遇决策点先读 `references/api-spec.md` 对应章节再下结论 —— 不要凭印象
• 不发明"规范没说的" —— 不确定的让 make openapi-check 报错指出，而非编规则
• handler 业务实现不规定 —— 本 skill 只管 API 形态（URL / schema / 错误码 / swag），实现交给开发者