start-new-sdk-project

用途

start-new-sdk-project 是用于从 OpenAPI 规范生成新 SDK 的主要技能。当用户需要创建 SDK、生成 SDK、新建 SDK 项目，或进行首次 Speakeasy 设置且尚无 .speakeasy/workflow.yaml 时，应使用此技能。

主要能力

该技能的核心是使用 speakeasy quickstart 命令初始化新的 SDK 项目。它会创建 SDK 以及必需的 .speakeasy/workflow.yaml 配置文件。支持的目标语言包括：TypeScript、Python、Go、Java、C#、PHP、Ruby、Kotlin、Terraform。

OpenAPI 规范来源支持三种类型：本地文件路径（如 ./api/openapi.yaml）、HTTP(S) URL（如 https://api.example.com/openapi.json）、以及 Speakeasy 工作区中管理的注册表源（如 my-api、my-api@latest、acme/prod/my-api@v2）。注册表源可通过 speakeasy pull --list --format json 查看。

使用方式

命令格式：

speakeasy quickstart --skip-interactive --output console -s <schema> -t <target> -n <name> -p <package-name>

主要标志：

--skip-interactive：自动化环境必需，跳过所有提示
--schema / -s：OpenAPI 规范来源
--target / -t：目标语言
--name / -n：PascalCase 格式的 SDK 名称（如 MyCompanySDK）
--package-name / -p：包名（语言变体自动推断）
--out-dir / -o：输出目录（默认当前目录）
--output：输出格式，summary、console 或 mermaid，自动化时使用 console
--init-git：初始化 git 仓库（非交互模式下省略则跳过）

示例：

从本地 OpenAPI 文件

speakeasy quickstart --skip-interactive --output console
-s ./api/openapi.yaml
-t typescript
-n "AcmeSDK"
-p "acme-sdk"

从 URL

speakeasy quickstart --skip-interactive --output console
-s "https://api.example.com/openapi.json"
-t python
-n "AcmeSDK"
-p "acme-sdk"

从注册表源

speakeasy quickstart --skip-interactive --output console
-s "my-api@latest"
-t go
-n "AcmeSDK"
-p "acme-sdk"

自定义输出目录并初始化 git

speakeasy quickstart --skip-interactive --output console
-s ./api/openapi.yaml
-t python
-n "AcmeSDK"
-p "acme-sdk"
-o ./sdks/python
--init-git

前置条件：交互式认证运行 speakeasy auth login，或为非交互环境（CI/CD、自动化）设置环境变量 export SPEAKEASY_API_KEY="<your-api-key>"。

适用场景

从 OpenAPI 规范生成任意 SDK（TypeScript、Python、Go、Java 等）
启动全新的 SDK 项目
尚无 .speakeasy/workflow.yaml 时
首次 Speakeasy 设置
用户提及“generate SDK”“TypeScript SDK”“Python SDK”“Go SDK”“create SDK”“new SDK”等

限制与注意事项

不要在新项目中使用 speakeasy generate sdk。该低级命令只生成代码，不创建 .speakeasy/workflow.yaml。缺少 workflow 文件将失去：通过 speakeasy run 的可复现构建、多目标 SDK 生成、CI/CD 集成、版本跟踪与升级路径。

在自动化环境中不要跳过 --skip-interactive，否则命令会挂起等待用户输入。在自动化环境中不要省略 --output console，需要结构化输出以验证成功。

quickstart 与 generate sdk 对比：speakeasy quickstart 创建 workflow.yaml，用于新项目，应始终使用；speakeasy generate sdk 不创建 workflow.yaml，仅用于一次性生成（罕见、高级用途）。

后续步骤

在输出目录中查看生成的 SDK
在 .speakeasy/workflow.yaml 中添加更多目标以支持多语言
规范或配置变更后运行 speakeasy run 重新生成

常用 CLI 命令

speakeasy quickstart ...：初始化新 SDK 项目
speakeasy run -y --output console：从 workflow 重新生成 SDK
speakeasy lint openapi --non-interactive -s spec.yaml：验证 OpenAPI 规范
speakeasy auth login：与 Speakeasy 认证
speakeasy pull --list --format json：列出注册表源

故障排除

Workflow already exists：.speakeasy/workflow.yaml 已存在，改为运行 speakeasy run 重新生成现有 SDK
Unauthorized：缺少或无效 API 密钥，运行 speakeasy auth login 或设置 SPEAKEASY_API_KEY
Schema not found：路径、URL 或源名称无效，验证路径存在或使用 speakeasy pull --list 查看源

技能介绍

用途