企业官网建设流程全解析

Composio 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 仓库中 Python SDK 的发布流程展开，完整梳理从「构建产物」到「composio-client 版本锁定」，再到「发布前验证」的完整链路。你将掌握make build的多包构建机制、bump.py的语义化版本提升交互、跨pyproject.toml/setup.py/uv.lock三处同步的客户端依赖更新方法，以及发布前的 import 与 nox 检查清单。所有命令均以当前仓库python/目录的真实实现为依据，可直接用于实际发布操作。

一、发布工作流总览

Composio 的 Python 侧发布流程在仓库中被抽象为「构建 → 版本提升 → 依赖锁定 → 验证」四个环节，其权威操作说明记录在 .agents/skills/python-release/references/release-workflow.md，配套的技能入口 .agents/skills/python-release/SKILL.md 明确要求：在修改 Python 发布元数据或生成的客户端版本锁定之前，必须先阅读该引用文档。

此外，python/docs/release.md 给出了从高层视角的发布步骤：确定要发布的包 → 运行python scripts/bump.py→ 按提示选择版本类型或跳过 → 创建发布 PR → 合并并发布 GitHub Release。它同时强调两条注意事项：开发活跃在next分支时，创建 GitHub Release 只能选择该分支；开发期间发布版本时，应选择pre以生成 release-candidate 版本。

二、构建：make build的多包产物收集

2.1 命令入口与前置条件

在环境就绪后，从python/目录执行：

make build

对应实现位于 python/Makefile：

build: clean-build @./.venv/bin/python -m build @set -e; for provider in $(PROVIDER_DIRS); do\ ./.venv/bin/python -m build $$provider;\ cp $$provider/dist/* dist/;\ done

2.2 三个阶段拆解

make build实际做三件事：

1. 先执行clean-build：清空dist/、build/以及所有 provider 包各自的dist/、build/产物（见 python/Makefile），保证每次构建从干净状态开始，避免陈旧产物混入发布。
2. 构建根包：通过./.venv/bin/python -m build构建根目录的composio主包（对应 python/pyproject.toml 中的[project]元数据）。
3. 逐个构建 provider 包并收集产物：PROVIDER_DIRS由 Makefile 动态推导（扫描providers/*/pyproject.toml），对每个 provider 执行python -m build后，将其dist/下的产物统一cp到根dist/。这样最终dist/中会汇聚根包与全部 provider 包的发行文件，便于统一上传。

从仓库现状看，python/providers/下存在 anthropic、autogen、claude_agent_sdk、crewai、gemini、google、google_adk、langchain、langgraph、llamaindex、openai、openai_agents 共 12 个 provider 包，每个都带有独立的pyproject.toml（例如 python/providers/openai/pyproject.toml），构建时会被一并收集。

三、版本提升：bump.py与make bump

3.1 两种入口

• 完整发布流程：python scripts/bump.py（对应 python/docs/release.md 的步骤 2）；
• 便捷封装：make bump，其定义为bump: clean-build+uv run python scripts/bump.py（见 python/Makefile），即先清理构建产物再执行版本提升。

3.2 交互式版本选择

bump.py 基于 click 与 semver 实现，脚本会扫描当前目录下所有pyproject.toml与setup.py（跳过.venv、venv、.nox、.tox、temp、node_modules、site-packages等目录），对每个包逐一提示版本提升类型：

脚本对-分隔的预发布标记（如rc后缀）做了专门处理：先剥离再解析，支持对已有 RC 版本继续提升。同时提供了--pre/--post/--patch/--minor/--major五个命令行选项（见 bump.py），可绕过交互提示直接指定提升类型，适合自动化流水线。

3.3 两种元数据文件的修改方式

• pyproject.toml：读取[project].name与[project].version，用新版本替换version = "..."（bump.py）；
• setup.py：解析setup(...)参数中的name与version，替换version="..."（bump.py）。注意：名为composio的主setup.py会被跳过，因为其版本由 pyproject.toml 主导（bump.py）。

当前仓库的根版本为0.21.1，可见于 python/pyproject.toml，provider 包与根包保持同版本（如 python/providers/openai/pyproject.toml）。

四、Client Pin Bumps：composio-client版本锁定

Composio SDK 的架构分为两层：上层的composio核心包，以及下层的composio-client（负责与 Composio 平台 API 通信的客户端）。发布composio时，通常需要同步更新其对composio-client的精确版本锁定（pin）。

4.1 先验证目标版本可解析

在提升composio-client锁定之前，必须先确认新版本已发布到 PyPI 且能被解析：

pip index versions composio-client

这一前置校验能避免把尚不存在的版本写入依赖声明。

4.2 三处锁定文件必须同步更新

composio-client的锁定散落在三处，更新时必须一起修改，保持完全一致：

从 uv.lock 的锁定条目可以看到，composio-client 1.43.0同时记录了 sdist 与py3-none-anywheel 的下载地址与 sha256 哈希，锁文件与元数据声明必须一致，否则uv sync会检测到漂移。

4.3 重新生成锁文件

三处文件更新完成后，在仓库根目录执行：

uv lock --upgrade-package composio-client

--upgrade-package仅针对composio-client这一个包重新解析并升级，而不会动其他依赖的锁定，从而把变更面控制在最小范围。执行完成后应检查 uv.lock 中的composio-client条目版本号已随之更新。

4.4 为什么是精确锁定

观察 python/pyproject.toml 的依赖声明可以发现一个规律：平台相关的基础依赖（pysher、pydantic、openai、jsonschema 等）大多使用>=的下限约束，而composio-client使用==精确锁定。这是因为客户端与平台 API 的契约耦合紧密，SDK 发布时必须以确定性版本与平台端行为对齐，避免下游用户解析到不兼容的客户端版本。setup.py中的 install_requires 与 pyproject.toml 保持一致，这也是「两处必须同步」的根本原因。

五、发布前验证：import 检查与 nox/Makefile 检查

5.1 快速 import 冒烟检查

依赖变更后，第一步是验证包能正常导入、依赖解析无误：

uv run --package composio python -c "import composio"

--package composio确保以composio包的工作区上下文运行，从而按锁定的依赖集解析。这一步能最快暴露依赖缺失、版本冲突或元数据错误（例如composio-client锁定版本在锁文件中不同步导致的解析失败）。

5.2 运行与本次变更相关的 nox/Makefile 检查

导入检查通过后，运行与本次变更相关的聚焦检查。当前仓库的检查面定义在 python/noxfile.py，常用会话包括：

例如，若本次变更仅涉及依赖锁定，优先跑make snt（import 与 SDK 初始化冒烟）即可快速获得信心；若同时改了 SDK 行为，则应跑make tst全量测试。各 Makefile 别名定义见 python/Makefile。

值得留意的是 noxfile.py 的依赖治理设计：类型桩与 provider 库（types-requests、crewai、langchain、llama-index 等）没有放进pyproject.toml的dev依赖组，而是由 nox 会话按需session.install，原因在文件注释中写得很清楚——provider 库会拖入冲突的传递依赖，破坏根包的解析稳定性。这种「锁文件只保留真正需要的依赖」的思路，同样适用于发布流程：验证环境与发布产物应当尽量贴近最终用户的可解析环境。

六、发布流程的完整执行顺序

综合 .agents/skills/python-release/references/release-workflow.md、python/docs/release.md 与源码实现，一次典型的 Python SDK 发布按以下顺序执行：

1. 准备环境：在python/下准备好虚拟环境（可用make env创建，见 python/Makefile）；
2. 确认要发布的包：决定根包与哪些 provider 包进入本次发布；
3. 提升版本：make bump或python scripts/bump.py，按提示为每个包选择 major/minor/patch/pre/post 或跳过；开发期间选择pre生成 RC 版本；
4. （如涉及）更新 client pin：pip index versions composio-client确认版本 → 同步修改 python/pyproject.toml、python/setup.py 与根 uv.lock → 在根目录执行uv lock --upgrade-package composio-client；
5. 构建：在python/下执行make build，产出并收集所有发行包到dist/；
6. 验证：uv run --package composio python -c "import composio"，再运行与变更相关的 nox/Makefile 检查（make snt/make chk/make tst等）；
7. 创建发布 PR 并合并：提交版本与锁定变更，创建发布 PR；合并后在next分支上创建 GitHub Release 完成发布。

通过这套「构建—提升—锁定—验证」的流程闭环，可以确保每个发布的 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