Klavis SDK 升级全流程解析基于 Fern 的 openapi.json 驱动代码生成与 PyPI/NPM 发布管线【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavisKlavis 仓库的fern/目录是整个 SDK 体系的单一事实来源本文以 fern/README.md 中描述的 SDK 升级三步流程为主线结合 fern/generators.yml、fern/overrides.yml 与 SDK 发布工作流 等仓库证据讲清楚如何从一份 OpenAPI 规范出发自动生成并发布 Python 与 TypeScript 双语言 SDK。读完本文你将掌握 Klavis SDK 的完整升级链路规范更新、PR 合并、GitHub Actions 手动触发发布以及 Fern 生成器的关键配置项各自影响 SDK 的哪一部分。一、SDK 升级的官方三步流程fern/README.md 定义了 Klavis SDK 升级的标准操作全文共三步更新 openapi.json 文件将最新的 API 规范写入openapi.json提交 PR 并合并把变更合并到 main 分支去 GitHub Actions 手动触发发布点击Publish Python SDK和Publish TypeScript SDK工作流填写新版本号流水线会自动生成并发布新版本 SDK。整个流程的核心思想是API 规范OpenAPI先行SDK 代码零手写。开发者只需要维护规范文件Python SDK 与 TypeScript SDK 的接口定义、类型、客户端方法全部由 Fern 生成器从规范推导而来。下面逐步拆解每一步在仓库中的落地形式。二、第一步更新 API 规范文件规范文件的位置与引用方式fern/generators.yml声明了生成器的输入规范api: specs: - openapi: ../docs/api-reference/openapi.json overrides: overrides.yml origin: https://api.klavis.ai/openapi.json见 fern/generators.ymlopenapi: ../docs/api-reference/openapi.json本地仓库中的规范文件实际位于 docs/api-reference/openapi.json。该文件是一份 OpenAPI 3.1.0 规范标题为 Klavis AI声明了 US 与 EU 两套生产 API 服务器overrides: overrides.yml指定类型重命名与 SDK 方法命名覆盖规则见 fern/overrides.ymlorigin生产环境规范的远端地址用于在线同步下文工作流部分会用到。如何更新规范仓库提供了一条半自动的同步路径。.github/workflows/sync-openapi.yml 定义了名为Sync OpenAPI Specs的手动触发工作流其核心步骤为- name: Update API with Fern uses: fern-api/sync-openapiv2 with: update_from_source: true token: ${{ secrets.OPENAPI_SYNC_TOKEN }} branch: update-api auto_merge: false add_timestamp: true该工作流会从origin地址拉取线上最新 API 规范写入update-api分支并自动追加时间戳且auto_merge: false——即不会自动合并必须走人工审查。这正对应 README 三步流程中的第二步规范更新以 PR 形式进入 main 分支保证 API 变更经过评审后才进入 SDK 生成链路。从源码结构看规范文件本身覆盖了三类接口域与 SDK 最终暴露的模块一一对应MCP 服务如/mcp-server/call-tool、/mcp-server/list-tools、OAuth 授权如/oauth/slack/authorize等数十个服务的 authorize 端点、以及各类型沙箱的initialize/dump端点。三、第二步提交 PR 并合并到 main 分支README 明确要求规范变更通过 PR 合并至 main。从仓库的 CI 结构可以推断这一设计的意图发布工作流见下节以main分支上的fern/目录和docs/api-reference/openapi.json为输入PR 合并是规范冻结的动作sync-openapi.yml的auto_merge: false配置保证了任何规范变更无论是人工编辑还是从远端同步都必须经过一次代码评审fern/README.md 中的顺序设计先合并规范、后触发发布意味着发布时点与 main 分支上的规范版本严格一致避免规范与 SDK 版本错位。这一步没有任何代码逻辑其价值在于把 OpenAPI 文件变成受版本控制、受评审约束的发布契约。四、第三步GitHub Actions 手动触发 SDK 发布README 中的第三步对应仓库里两个workflow_dispatch手动触发的工作流。Publish Python SDK.github/workflows/python-sdk-release.yml 的完整执行链路为name: Publish Python SDK on: workflow_dispatch: inputs: version: description: The version of the Python SDK that you would like to release required: true type: string执行步骤依次是检出代码actions/checkoutv4要求contents: write权限以打 tag全局安装 Fern CLInpm install -g fern-api执行发布命令注入FERN_TOKEN与PYPI_TOKEN两个 secretfern generate --group python-sdk --version ${{ inputs.version }} --log-level debug见 python-sdk-release.yml使用softprops/action-gh-releasev1创建 GitHub Releasetag 为python-v${{ inputs.version }}自动基于上次 tag 以来的 commit 生成 release notes。命令中的--group python-sdk精确指向generators.yml中定义的python-sdk生成组--version即 README 所说的specify new version。Publish TypeScript SDK.github/workflows/typescript-sdk-release.yml 与 Python 版几乎同构差异仅在执行fern generate --group ts-sdk --version ${{ inputs.version }}见 typescript-sdk-release.yml注入FERN_TOKEN与NPM_TOKENGitHub Release 的 tag 前缀为ts-v${{ inputs.version }}。两条工作流的命名Publish Python SDK/Publish TypeScript SDK正是 README 第三步在 GitHub Actions 界面上看到的按钮名称。五、generators.yml 深度解析SDK 长什么样由这里决定全局生成设置api.specs.settingsfern/generators.yml的settings段见 fern/generators.yml控制规范到 SDK 类型的全局翻译规则配置项取值作用title-as-schema-nametrue用 schema 的 title 作为类型名使生成的类名更贴近 API 语义type-dates-as-stringstrue日期字段统一生成为字符串类型避免跨语言日期库差异object-query-parametersfalse查询参数不包装成对象idiomatic-request-namesfalse请求体类型名保持规范原名respect-nullable-schemasfalse不强制按规范的 nullable 标注生成可空类型wrap-references-to-nullable-in-optionaltrue指向可空 schema 的引用包装为 Optionalcoerce-optional-schemas-to-nullabletrue可选 schema 归一化为可空类型inline-path-parametersfalse路径参数保持独立不内联进方法签名结构coerce-enums-to-literalstrue枚举转换为字面量联合类型这些布尔开关共同决定了生成 SDK 中类型可空性、命名风格等手感层面的行为升级规范时如果某次 API 变更引入了新的可空字段这些设置会影响新字段在 SDK 中的呈现方式。python-sdk 生成组python-sdk: generators: - name: fernapi/fern-python-sdk version: 4.32.2 output: location: pypi package-name: klavis token: ${PYPI_TOKEN} config: client_class_name: Klavis pydantic_config: enum_type: python_enums metadata: package-description: Open Source MCP Integration for AI applications license: Apache-2.0 smart-casing: true见 fern/generators.yml关键事实产物发布到 PyPI包名klavis与 docs/sdk/python.mdx 中pip install klavis的安装方式一致客户端类名固定为Klavis即文档示例里klavis_client Klavis(api_key...)的入口枚举使用 Python 原生Enumenum_type: python_enums因此from klavis.types import McpServerName中的McpServerName.YOUTUBE是标准枚举成员发布凭据来自环境变量${PYPI_TOKEN}与发布工作流中注入的 secret 名称相互印证。ts-sdk 生成组ts-sdk: generators: - name: fernapi/fern-typescript-node-sdk version: 1.7.0 output: location: npm package-name: klavis token: ${NPM_TOKEN} config: namespaceExport: Klavis allowCustomFetcher: true skipResponseValidation: true includeApiReference: true noSerdeLayer: true extraDevDependencies: msw: 2.11.2见 fern/generators.yml产物发布到 npm包名同样为klavis与 docs/sdk/typescript.mdx 及 README.md 中import { KlavisClient, McpServerName } from klavis的用法对应namespaceExport: Klavis提供命名空间导出noSerdeLayer: true关闭序列化层skipResponseValidation: true跳过响应校验allowCustomFetcher: true允许调用方注入自定义 fetch 实现mswMock Service Worker作为额外 dev 依赖被写进产物供生成代码的测试使用。六、overrides.yml让生成结果符合 SDK 命名约束OpenAPI 规范中的原始命名带连字符的 schema 名、大量同构端点直接生成会得到不可用的 SDK 代码fern/overrides.yml 共 636 行通过x-fern-*注解做了三类修正1. FastAPI 变体类型改名FastAPI 会为响应模型生成-Input/-Output两个 schema 变体overrides 将它们统一改名为合法驼峰标识符components: schemas: # Fix duplicate type names from FastAPI -Input/-Output schema variants AirtableData-Input: x-fern-type-name: AirtableDataInput AirtableData-Output: x-fern-type-name: AirtableDataOutput见 fern/overrides.yml同类映射覆盖 Slack、Notion、GitHub 等数十个服务的数据类型2. 枚举值大写化McpServerName枚举的显示名如 GitHub、YouTube被映射为大写枚举成员McpServerName: x-fern-enum: GitHub: name: GITHUB YouTube: name: YOUTUBE见 fern/overrides.yml这解释了 SDK 文档中McpServerName.YOUTUBE这类全大写成员的由来。3. 端点归组与方法重命名overrides 的paths段见 fern/overrides.yml把 REST 端点整理成 SDK 的分组方法POST /mcp-server/call-tool→mcp_server.call_toolsPOST /mcp-server/list-tools→mcp_server.list_toolsGET /mcp-server/tools/{serverName}→mcp_server.get_tools每个/oauth/{service}/authorize端点归入oauth组并重命名为authorize_{service}如authorize_gmail、authorize_slack各沙箱的{service}/{sandbox_id}/initialize与dump端点分别重命名为initialize_{service}_sandbox/dump_{service}_sandbox文件中的注释写明 all 35 sandbox types need unique method names——即靠重命名解决 35 种沙箱端点生成的方法名冲突问题。从源码结构看正是这些x-fern-sdk-group-name/x-fern-sdk-method-name注解使得generators.yml生成的 SDK 呈现出klavis_client.mcp_server.call_tools(...)、klavis_client.oauth.authorize_gmail(...)这类层级清晰的调用结构与 docs/api-reference/sandbox 等 API 参考文档的分组保持一致。七、发布后的验证路径一次成功升级后可以在仓库内通过以下路径验证 SDK 与规范的对应关系Python 安装与调用示例docs/sdk/python.mdxpip install klavis含 OpenAI function calling 的完整示例TypeScript 安装与调用示例docs/sdk/typescript.mdx规范原文docs/api-reference/openapi.jsonFern 全局配置fern/fern.config.json组织名klavis、版本3.5.0。八、小结一次完整升级的操作清单把 README 的三步落到具体动作在 GitHub Actions 手动运行Sync OpenAPI Specs或在本地编辑 docs/api-reference/openapi.json 并同步 fern/overrides.yml 中的命名修正确认 diff 无误将变更以 PR 形式合并到 main 分支分别手动触发Publish Python SDK与Publish TypeScript SDK在version输入框填入目标版本号流水线会自动执行fern generate --group python-sdk|ts-sdk把新版本推送到 PyPI / npm并创建python-v{version}/ts-v{version}的 GitHub Release。需要说明的前提触发发布工作流依赖仓库维护者配置的FERN_TOKEN、PYPI_TOKEN、NPM_TOKEN、OPENAPI_SYNC_TOKEN等 secrets该操作属于仓库维护者权限对于普通贡献者而言可验证与可参与的环节集中在规范文件的 PR 修改与 overrides 规则的补充上。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考