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 fixturesgolden-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/webhookTS 侧ts/packages/core/test/fixtures/webhook。这正是公共契约对比在代码层面的落地能被自动比对的数据一律交给测试守护。三、第二步升级生成客户端版本Generated Client BumpsComposio 双端 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版本约束。当前仓库为精确 pincomposio-client1.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.tomlsetup.py→uv lock --upgrade-package→ 导入冒烟的顺序遵守命名约定TS 用 camelCase、Python 用 snake_case仅生成客户端要求处保留 wire 名跑最小验证导入检查 / 类型检查 / 测试配对优先必要时使用 harness/parity.mjs 做 trace 级比较并以 python/tests/test_cross_sdk_compatibility.py 守护双端共享数据的一致性。这套流程的价值在于把双语言对齐从口头承诺变成可执行、可自动验证的工程纪律公共契约有清单、版本升级有双端步骤、命名有约定、结果有测试兜底。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 fixturesgolden-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/webhookTS 侧ts/packages/core/test/fixtures/webhook。这正是公共契约对比在代码层面的落地能被自动比对的数据一律交给测试守护。三、第二步升级生成客户端版本Generated Client BumpsComposio 双端 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版本约束。当前仓库为精确 pincomposio-client1.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.tomlsetup.py→uv lock --upgrade-package→ 导入冒烟的顺序遵守命名约定TS 用 camelCase、Python 用 snake_case仅生成客户端要求处保留 wire 名跑最小验证导入检查 / 类型检查 / 测试配对优先必要时使用 harness/parity.mjs 做 trace 级比较并以 python/tests/test_cross_sdk_compatibility.py 守护双端共享数据的一致性。这套流程的价值在于把双语言对齐从口头承诺变成可执行、可自动验证的工程纪律公共契约有清单、版本升级有双端步骤、命名有约定、结果有测试兜底。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考