Composio 跨 SDK Parity 维护指南：让 TypeScript 与 Python SDK 行为始终对齐-二趣网

Composio 跨 SDK Parity 维护指南：让 TypeScript 与 Python SDK 行为始终对齐

【免费下载链接】composioComposio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio

导读

Composio 同时维护 TypeScript 与 Python 两套 SDK，它们共享同一套后端 API 契约与生成式客户端（generated client）。本文基于仓库 .agents/skills/cross-sdk-parity/SKILL.md 与其配套工作流文档 references/parity-workflow.md，系统讲解"跨 SDK 一致性（Cross-SDK Parity）"维护方法论：何时需要启用该技能、如何对比双端公共契约、如何同步升级生成客户端版本、遵循何种命名约定，以及如何用最小验证证明两端行为仍然一致。读完本文，你将掌握一套可直接复用的双语言 SDK 变更流程，适用于任何"一次改动同时影响 TS 与 Python"的开发场景。

一、什么是 Cross-SDK Parity，何时启用

Composio 的 SDK 分为 TypeScript 侧（ts/packages 下的core、cli、providers等包）与 Python 侧（python/composio），二者面向同一后端平台。用户在两端体验到的概念是等价的：工具、连接账户、认证配置、会话与 Tool Router 行为等。因此任何触及双端共享行为或生成客户端的改动，都需要保证两端"同步对齐"。

根据 SKILL.md 的定义，cross-sdk-parity技能在以下场景必须启用：

一次改动同时影响两个 SDK；
生成客户端（generated client）版本 pin 发生变动；
需要对比 TS / Python 行为差异；
后端 API 契约发生变化。

反之，仅涉及单语言内部实现、不暴露给另一端的改动，不需要启用该技能。这正是 SKILL.md 中"Use this skill when TypeScript and Python must stay aligned"的边界：它服务的是公共契约层，而非内部实现细节。

使用前，必须先阅读 references/parity-workflow.md，该文档定义了对比公共契约、升级生成客户端、命名与验证的完整执行步骤。

二、第一步：对比双端公共契约

parity-workflow 要求：在改动共享行为前，先逐项检查两个 SDK 中"用户感知上等价"的概念是否保持一致。对比清单包括以下七个维度：

对比维度	说明
Tools 与 Toolkits	工具名称、toolkit 分类、参数 schema 是否一致
Sessions 与 Tool Router 行为	会话生命周期、Tool Router 路由与文件挂载语义是否一致
Connected Accounts（连接账户）	账户建模、绑定关系、状态处理是否一致
Auth Configs（认证配置）	认证配置的字段语义与补丁行为是否一致
Provider Wrappers（供应商封装）	Anthropic、OpenAI、LangChain 等 provider 包装层的用法是否对齐
Error Shapes 与状态处理	错误结构、HTTP 状态码语义、异常类型是否对齐
Docs Examples 与 Changelog 文案	文档示例与更新日志描述不得与任一 SDK 的实际行为冲突

以错误结构为例，TypeScript 侧在 ts/packages/core/src/errors 中维护了ComposioError、SDKErrors、ToolErrors等错误类型层级；Python 侧对应 python/composio/exceptions.py。当后端调整错误契约时，两端错误类型必须同步演进，否则依赖错误形状做分支处理的用户代码会跨语言行为分裂。

仓库佐证：仓库用测试直接守护"双端数据一致"。测试文件 python/tests/test_cross_sdk_compatibility.py 中的TestCrossSDKFixtureCompatibility断言 TypeScript 与 Python 两端的 webhook fixtures（golden-signatures.json、v1-github-push.json、v2-github-push.json、v3-github-push.json）逐字节一致，并要求共享的 JSON Schema 转换语料object-cases.json在两个语言目录下保持字节级相同；python/tests/conftest.py 则给出了双端 fixtures 目录的对应关系（Python 侧python/tests/fixtures/webhook，TS 侧ts/packages/core/test/fixtures/webhook）。这正是"公共契约对比"在代码层面的落地：能被自动比对的数据，一律交给测试守护。

三、第二步：升级生成客户端版本（Generated Client Bumps）

Composio 双端 SDK 都依赖后端生成的客户端包，它们是底层 API 契约的直接载体。升级时两端各自有一套固定流程，绝不能只改一处。

TypeScript 侧

核实最新版本：执行npm view @composio/client version确认远端最新版本号。
更新目录 pin：将pnpm-workspace.yaml中catalog段的@composio/client条目更新为核实到的版本。以当前仓库为准，pnpm-workspace.yaml 中的 pin 为'@composio/client': 0.1.0-alpha.76，且该包被列入minimumReleaseAgeExclude，不受仓库 4320 分钟（3 天）发布冷却期的限制。
刷新锁文件：执行pnpm install --lockfile-only，仅更新 pnpm-lock.yaml 而不触碰node_modules。
为受影响包补 changeset：仓库使用 changesets 管理版本（见 ts/scripts/changeset-release.sh），任何受@composio/client版本变动影响的已发布包都要登记变更集。

Python 侧

核实最新版本：执行pip index versions composio-client确认远端可用版本。
更新 pyproject.toml：修改 python/pyproject.toml 中dependencies里的composio-client版本约束。当前仓库为精确 pin：composio-client==1.43.0。
更新 setup.py：同步修改 python/setup.py 中的install_requires，两处必须保持一致——python/AGENTS.md 明确要求：When bumping composio-client, update python/pyproject.toml, python/setup.py, and root uv.lock together。
刷新根锁文件：执行uv lock --upgrade-package composio-client，更新根目录 uv.lock。
依赖同步后做导入冒烟：执行uv run --package composio python -c "import composio"，验证 Python 包在真实依赖组合下可正常导入。

两个流程的核心纪律一致：版本号在清单文件（catalog pin / pyproject.toml / setup.py）与锁文件（pnpm-lock.yaml / uv.lock）中成对出现，必须成对更新。Python 侧尤其特殊——同一版本约束同时存在于pyproject.toml与setup.py两处，漏改其一就会造成构建源不一致。

四、命名约定：camelCase 与 snake_case 的分工

双端 SDK 面向同一后端，但公共 API 的命名必须遵循各语言生态惯例：

TypeScript 公共 API 使用 camelCase，例如 ts/packages/core/src/models/Sessions.ts 中的会话与 Tool Router 模型方法；
Python 公共 API 使用 snake_case，例如 python/composio/core 下的模型与工具方法；
仅在生成客户端要求时才保留后端 wire 名（wire names）。wire 名是后端传输层使用的原始字段名，双端生成客户端直接消费它们；一旦脱离生成客户端的约束，公共 API 就应回归各语言习惯命名。

这一约定保证了"用户在两端写出的代码各自符合母语习惯"，同时"底层数据与后端契约始终同构"。

五、验证：用最小检查证明双端行为未漂移

parity-workflow 明确强调：不要只依赖版本号升级本身来证明一致性。正确的做法是运行能证明"两个 SDK 仍然暴露预期行为"的最小检查组合——优先选择"导入检查 / 类型检查 / 测试"这样的配对，而不是仅靠 bump 版本。

在 Composio 仓库中，这一原则有三个层面的落地：

契约数据同步测试：python/tests/test_cross_sdk_compatibility.py 用参数化测试逐文件比对双端 fixtures 与 JSON Schema 语料，任何一个文件不同步都会让 CI 失败。
Python 导入冒烟：uv run --package composio python -c "import composio"在锁定依赖组合下验证包可导入、依赖无冲突。
Trace 级 parity 比较器：仓库在 harness/parity.mjs 提供了一个更深层的验证工具——比较 baseline 与 candidate 两轮运行产生的(method, path-template)追踪对集合是否完全相等，允许的差异需显式登记在 parity-variance.json 中；所有条目 parity 通过则退出码为 0，否则为 1。这从"运行时实际发出的请求"层面守护了双端行为一致，是对 SDK 静态契约对比的有力补充。

验证顺序的建议：先跑最小的导入/类型检查对（成本最低、能最快暴露依赖或类型漂移），再跑契约同步测试，最后在需要时运行 trace 级 parity 比较。

六、总结：跨 SDK 变更的标准动作清单

当一次改动同时影响 TypeScript 与 Python 时，按以下顺序执行即可保持双端对齐：

读工作流：先看 .agents/skills/cross-sdk-parity/references/parity-workflow.md；
对比契约：核对 Tools/Toolkits、Sessions 与 Tool Router、连接账户、认证配置、Provider 封装、错误形状、文档示例七个维度；
同步升级生成客户端：TS 侧按npm view→ catalog pin →pnpm install --lockfile-only→ changeset 的顺序；Python 侧按pip index versions→pyproject.toml+setup.py→uv lock --upgrade-package→ 导入冒烟的顺序；
遵守命名约定：TS 用 camelCase、Python 用 snake_case，仅生成客户端要求处保留 wire 名；
跑最小验证：导入检查 / 类型检查 / 测试配对优先，必要时使用 harness/parity.mjs 做 trace 级比较，并以 python/tests/test_cross_sdk_compatibility.py 守护双端共享数据的一致性。

这套流程的价值在于把"双语言对齐"从口头承诺变成可执行、可自动验证的工程纪律：公共契约有清单、版本升级有双端步骤、命名有约定、结果有测试兜底。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析