一个 API 同步工作流提示词：后端改接口，前端自动对类型

# 在这个项目里搭一套 OpenAPI spec 同步工作流

我要一套后端 spec 工作流：一个脚本，把线上 OpenAPI spec 和本地快照对比，写一份前端导向的变更报告；再加一个 /api-sync 斜杠命令，把报告变成分阶段计划。

开始前先从仓库里把下面这些填上（问不到再问我）：
- Spec 来源：自己找，见 Part 0。别问我 URL，先找。
- 快照路径：api-spec/openapi.yaml
- 报告路径：api-spec/CHANGES.md
- 要交叉引用的源码根目录：src/
- 响应校验库：zod
- 快照进 git 吗：yaml 进 gitignore，CHANGES.md 提交

先读这个仓库：包管理器、脚本约定、API 调用和响应 schema 怎么写，匹配它的风格。不要编路径，grep 找真实路径。

## Part 0 — 先找 spec

先做这一步，告诉我你找到了什么。不要猜 URL，找不到再问我。

1. 文档：README.md、CLAUDE.md、AGENTS.md、CONTRIBUTING.md、docs/、.github/、.cursor/rules/、*.http/*.rest、wiki。
   用这个命令搜：
   grep -rniE 'swagger|openapi|api-?docs|redoc|/v3/api-docs' --include='*.md' --include='*.mdx' --include='*.txt' --include='*.http' --include='*.rest' . | grep -v node_modules

   注意：Swagger UI 链接是 HTML 页，不是 spec，要推导出机器可读 URL。
   文档 URL 可能过期，用 curl 确认它能答。

2. 仓库里已有的 spec 文件：
   find . -path ./node_modules -prune -o -iregex '.*(swagger|openapi|api-docs).*\.(ya?ml|json)' -print
   git ls-files | grep -iE 'swagger|openapi|api-docs'
   也看 node_modules/.cache/、.next/cache/、dist/、build/、coverage/，以及 gitignore 的 api/、api-spec/、docs/、schemas/。

3. 生成器配置：
   grep -rniE 'openapi|swagger|api-docs' --include='*.json' --include='*.ts' --include='*.js' --include='*.mjs' --include='*.yaml' --include='*.yml' --include='.env*' --include='Makefile' --include='*.sh' -l . | grep -v node_modules
   重点找：openapi-typescript / orval.config.* / kubb.config.* / swagger-typescript-api / @hey-api/openapi-ts 配置、package.json 里 openapi 相关的 npm 脚本、.env* 的 API base URL、docker-compose 服务 URL、CI 步骤。

4. 从 API base URL 推导。只找到 base URL 的话，探这些常规路径：FastAPI /openapi.json、Spring /v3/api-docs(+.yaml)、ASP.NET /swagger/v1/swagger.json、NestJS /api-json、Rails /api-docs/v1/swagger.yaml，加 /openapi.yaml 和 /swagger.json。
   curl -sS -o /dev/null -w '%{http_code} %{content_type} %{url_effective}\n' <BASE>/openapi.json
   报告哪些有响应。都要 auth 就直说，别把 token 写进脚本。

5. 都不行：问我，并告诉我你排除了什么。

如果 spec 不能通过 HTTP 访问：
把来源设计成单一 SPEC_SOURCE，可以是 URL、本地路径或 shell 命令，按这个顺序解析：--to <file> → OPENAPI_URL 环境变量 → 你发现的默认值。下游的 diff、报告、快照都不变。

## Part 1 — scripts/sync-api.mjs

一个依赖极少的 Node ESM 脚本（唯一新依赖是 js-yaml，用仓库的包管理器）。

用法：
node scripts/sync-api.mjs fetch → 对比快照 → 写报告 + 覆盖快照
node scripts/sync-api.mjs --check → 只对比，快照不动，漂移则 exit 1（CI 友好）
node scripts/sync-api.mjs --from <file> → 对比 <file> 而不是快照
node scripts/sync-api.mjs --to <file> → 把 <file> 当“远端”，不抓取（离线）
node scripts/sync-api.mjs --json → 额外把原始 diff 打到 stdout

在 package.json 加 "sync:api": "node scripts/sync-api.mjs"

如果还没有快照：把抓到的 spec 写成快照，打印“seeded — 后端发版后再跑才能看到 diff”，exit 0。绝不要把整个 API 报成“新增”。

要 diff 什么：
把 paths 铺平成 "GET /a/b" → 操作映射，操作和 components.schemas 分开对比。

操作：
- 新增 / 删除 / 变更
- 参数：新增（标记 required）、required↔optional 翻转、枚举值增删——按 in:name 或 ref:Name 做 key，不要按数组索引
- 请求体和成功响应 schema：$ref 名变了报重命名；inline 的 diff 属性
- 新增/删除的非 2xx 状态码
- 安全需求变更、新 deprecated 标记

Schema：
- 属性新增（标 required）/ 删除 / 改类型
- 枚举值增删（schema 上和每个属性上，含 items.enum）
- required↔optional 翻转

两个让报告值得存在的点：

1. 从响应描述里提取 error_code。机器错误码通常只写在每个非 2xx 响应的 description 文本里，所以一个新分支在 schema 级 diff 里看起来“什么都没变”。按上下文解析：括号里的 token、error_code 式描述后的 token、任何出现在某个 schema 的 error_code 枚举里的 snake_case token。不要过滤掉和字段名/枚举值撞的 token——那些碰撞正是最重要的码。报新增的码；对不再被文档化的码，grep 源码里 "that_code"，说哪个文件在分支它——那就是死分支。

2. 把每个变更和实际代码交叉引用。用 git ls-files --cached --others --exclude-standard <src root> 加载所有源文件（含未跟踪），然后：
   - 路径的调用点：把路径参数变成单段通配符，要求匹配以引号/反引号/? 结尾
   - Schema 镜像：找持有响应校验镜像的文件——匹配 fooBarSchema，加上裸 PascalCase 名（只在 schemas.ts 里）
   - 新操作的路径已经在 src/ 里被引用：加“⚠️ path 已引用——检查 method”备注

报告格式（api-spec/CHANGES.md）：
头部写生成日期、baseline 标签、spec info.version、前后操作和 schema 数量；再加一个小表；然后按顺序：
- ## 🔴 Removed operations — 如果我们调用就 breaking（带调用点）
- ## 🟠 Changed operations（嵌套 bullet + 调用点）
- ## 🟢 New operations，按路径区域分组
- ## 🔴 Removed schemas（带镜像文件）
- ## 🟠 Changed schemas — 镜像的排前面加粗带镜像文件
- ## 🟢 New schemas（一行逗号分隔）

没变更就写“No changes since the last snapshot.”，顶部写“do not edit by hand”。

## Part 2 — .claude/commands/api-sync.md

一个斜杠命令（/api-sync [scope]，scope 可选，也接受 implement），跑这个工作流。Frontmatter 写 description + argument-hint。

步骤：
1. Diff：跑 npm run sync:api，读 api-spec/CHANGES.md
2. 把每一项分类：Breaking(P0) · Silently wrong(P0) · Now-incomplete(P1) · Un-mocks a screen(P1) · Extends a screen(P2) · Net-new feature(P3) · Backend-only(drop)。不要跳项，实在没地方放就列为 open question。
3. 写计划：ROADMAP.md 里加一个带日期的 section，按优先级排序，分阶段独立发布
4. 在聊天里回报

## Part 3 — 接进去

- 加 gitignore 条目
- CLAUDE.md 加一节 Backend-change workflow
- 跑一次脚本，初始化快照，给我看第一份报告