heyapi

Hey API

当工作涉及 Hey API / @hey-api/openapi-ts 时使用此技能：从 OpenAPI 生成 TypeScript 客户端、配置插件、接入 HTTP 客户端、验证器、TanStack Query 产物，或重新生成 API 层。

工作流

1. 修改代码前，先检查本地 Hey API 的情况：
   • @hey-api/openapi-ts 的软件包版本（最新稳定版为 0.99.0；忽略 next 快照构建）、@hey-api/vite-plugin、客户端软件包、验证器（zod / valibot）和 TanStack Query。
   • 配置文件：openapi-ts.config.ts（或 .js / .mjs / .cjs）以及任何 Vite 插件集成。
   • 规范输入：本地路径、远程 URL、注册表简写（hey-api/...、scalar:...、readme:...）或内联对象。
   • 输出文件夹内容（*.gen.ts、client/、core/），以及使用方是从 index.ts 还是特定生成文件导入。
   • 运行时接线：client.setConfig、runtimeConfigPath / createClientConfig、身份验证、拦截器、按调用覆盖 client。
2. 当用户要求了解最新行为、无法确定已安装的版本，或工作涉及迁移、插件 API 或 Node/运行时要求时，刷新文档。从 source-map.md 开始。
3. 安装、CLI、defineConfig、输入/输出、多任务配置和 Vite，请参考 setup-config.md。
4. HTTP 客户端、SDK 形态、身份验证、拦截器、throwOnError 和使用生成函数，请参考 clients-sdk.md。
5. Zod/Valibot、TanStack Query、转换器/验证器和 Web 框架插件，请参考 plugins-validators.md。
6. 输出布局、入口导出和破坏性变更检查，请参考 output-migration.md。
7. 按照现有项目风格实现：
   • 优先重新生成，而不是手动编辑 *.gen.ts 或打包生成的 client/ / core/ 脚手架。
   • 只组合应用所需的插件；默认已生成 TypeScript + SDK（Fetch）。
   • 除非项目有意跟踪一个版本范围，否则将 @hey-api/openapi-ts 固定到确切版本。
   • 添加脚本时，命令示例优先使用 bun / bunx。

判断

• 将 OpenAPI 规范视为契约。应修复规范或从规范重新生成；不要通过本地编辑生成文件来掩盖偏差。
• 将输出文件夹视为依赖项。下次代码生成时，其中的更改会被擦除。
• 默认客户端是 Fetch（@hey-api/client-fetch）。仅当运行时需要时才选择 Axios、Ky、Next.js、Nuxt、OFetch 或 Angular。
• 除非在 client 插件（而非 SDK 插件）上启用了 throwOnError，否则 SDK 响应通常为 { data, error }。
• 仅在确实需要运行时验证或转换时，才启用 SDK 的 validator / transformer；这会产生成本并引入验证器插件。
• 对于 React Query，优先将生成的 *Options() / *Mutation() 辅助函数展开传入 useQuery / useMutation，而不是手动重新封装 SDK 调用。
• 监视模式支持远程 URL 输入；不要假定本地文件监视可用。
• 需要 Node.js >= 22.18.0（自 v0.98 起；v0.96–v0.97 需要 >= 22.13.0）。自 v0.91 起，软件包仅支持 ESM。
• Python 代码生成尚未达到生产就绪状态；此技能应聚焦于 TypeScript @hey-api/openapi-ts。

验证

优先使用仓库现有的检查。对于有实际影响的 Hey API 工作，请执行相关子集：

• 使用项目的 openapi-ts 脚本重新生成，并确认生成输出符合干净差异策略。
• 对 SDK 函数、查询选项和 Zod/Valibot 架构的使用方进行类型检查。
• 冒烟测试一条成功路径和一条错误路径（data 与 error，或启用 throwOnError 后抛出的错误）。
• 针对真实或模拟端点，确认 baseUrl / baseURL（因客户端而异）、身份验证和拦截器。
• 升级后，合并前阅读所跨越版本的 迁移指南。