CraftKit/plugins/dev/skills/prepare-api/SKILL.md

name, description

name	description
prepare-api	对照前端需求或设计与现有 API 契约，整理接口清单、字段映射、类型转换、缺失项和联调风险。适用于前后端对接准备与契约差异分析；设计新 HTTP API、实现请求代码、运行接口调试或修改页面文案不应触发。

API 对接准备

把前端需要的数据与可验证 API 契约对应起来，明确差异而不编造接口或直接修改代码。

工作流

1. 按 契约来源 确认 API 文档、服务端源码、生成规范或用户材料的范围、版本和可信度。
2. 读取前端需求、页面设计或相关代码，提取用户可见含义、字段、动作和状态。
3. 按 映射规则 建立接口、请求、响应和双向类型转换映射。
4. 分别列出已匹配、未匹配、冲突、缺失接口和需要后端或产品确认的事项。
5. 按 评审清单 检查错误、分页、精度、时间、空值、权限和兼容风险。
6. 默认在对话中输出；用户要求保存时读取 .craftkit/project.json 的 documents 配置，过程映射使用 workRoot，共享映射使用 designRoot。

写入后在 workRoot/<task>/task.json 登记本次过程或共享文档；已有记录时保守合并，只更新本任务拥有的文件。登记结构遵循 knowledge:document-output 的生命周期规则，不修改项目级默认配置。

边界

• API 文档不能反向覆盖已经确认的页面文案、业务含义和交互要求。
• 不预设请求客户端、响应包裹、分页字段、枚举结构、上传或工作流接口。
• 不因名称相似自动匹配字段；不确定项必须保留证据和待确认状态。
• 本 Skill 不设计新 API、不发起真实请求、不生成正式请求代码，也不修改前后端实现。