regenerate-sdk

regenerate-sdk 是一个用于重新生成 SDK 的技能，属于 speakeasy-api/sdk-generation-skills 技能集。当 OpenAPI 规范发生变化、需要重新构建 SDK 时使用。

用途

该技能使用 speakeasy run 命令执行工作流并重新生成 SDK。适用于以下情况：OpenAPI 规范已更新；工作流或 overlay 配置发生变更；需要使用最新 Speakeasy 版本重新生成；用户说出 "regenerate SDK"、"run speakeasy"、"spec changed" 等触发词时。

主要能力

运行所有已配置的目标以重新生成 SDK
仅运行指定的目标（target）
使用指定的源（source）运行
提供 AI 友好的输出模式，便于在 AI 代理或 CI/CD 环境中使用
输出生成的 SDK 代码（位于输出目录）以及生成日志（成功/失败详情）

使用方式

前置条件

workflow.yaml：必须存在于 .speakeasy/workflow.yaml
OpenAPI 规范：按工作流中的配置提供
认证：通过 speakeasy auth login 或 SPEAKEASY_API_KEY 环境变量完成

对于非交互式环境（CI/CD、AI 代理），需设置：

export SPEAKEASY_API_KEY="<your-api-key>"

命令

运行所有已配置的目标

speakeasy run

仅运行指定目标

speakeasy run -t <target-name>

使用指定源运行

speakeasy run -s <source-name>

AI 友好输出模式

speakeasy run --output console

使用时机

更新 OpenAPI 规范之后
修改 workflow.yaml 之后
更改 overlays 之后
使用最新 Speakeasy 版本重新生成时

示例工作流

.speakeasy/workflow.yaml

workflowVersion: 1.0.0 speakeasyVersion: latest sources: my-api: inputs: - location: ./openapi.yaml targets: typescript-sdk: target: typescript source: my-api output: ./sdk/typescript

AI 友好输出

对于输出量较大的命令，可通过管道传给 grep 或 tail 以减少上下文：

speakeasy run --output console 2>&1 | tail -50

适用场景

在 OpenAPI 规范更新后重新生成 SDK
在修改 workflow.yaml 或 overlays 后重新生成
在 CI/CD 或 AI 代理环境中以非交互方式重新生成 SDK
需要使用最新 Speakeasy 版本重新生成 SDK

限制与注意事项

如果近期有变更，不要在没有先检查规范有效性的情况下运行
不要忽略生成警告——它们可能表明 SDK 质量问题
不要在未理解其用途的情况下删除 .speakeasy/ 目录

故障排查

如果 speakeasy run 失败，请检查：

OpenAPI 规范是否有效？运行 speakeasy lint openapi --non-interactive -s <spec>
源路径是否存在？检查 workflow.yaml 中的 inputs.location
是否存在阻塞性验证错误？参见 diagnose-generation-failure 技能

技能介绍

用途