Composio SDK 贡献完全指南：monorepo 工具链、Provider 开发与发布流程实战

本文是 Composio SDK 开源仓库贡献指南（CONTRIBUTING.md）的深度解读。Composio 是一个为 AI Agent 提供 1000+ 工具集成、工具检索、上下文管理、认证与沙箱工作台的 SDK 项目，仓库以 monorepo 形式同时托管 TypeScript SDK、Python SDK、文档站点、示例与发布工具链。读完本文，你将掌握完整的本地开发环境搭建、仓库结构认知、双语言编码规范、Provider 扩展开发、测试与发布流程，并理解这些流程在仓库源码与配置文件中的落地方式。

一、开发环境搭建：以 mise 为单一事实来源

Composio 的本地开发与 CI 使用 mise.toml 锁定全部工具链版本，该文件被明确指定为本地开发与 CI 的 "source of truth"（单一事实来源）。

1.1 预置工具版本

根据 mise.toml 的实际内容，当前仓库锁定如下版本：

工具	版本	说明
Node.js	24.17.0	根包 devEngines 同时约束为 >=24.17.0 <25（见 package.json）
pnpm	11.8.0	通过 mise 的 npm 后端安装，不依赖 Corepack
Bun	1.4.1+4661e494f	由 mise 直接安装 npm 平台二进制包（@oven/bun-*），并按平台校验 checksum
Deno	2.6.7	用于 E2E 运行时测试
Python	3.12	Python SDK 的虚拟环境由 uv venv --seed --prompt composio --python 3.12 创建
uv	0.8.19	Python 包管理与虚拟环境工具

注意：CONTRIBUTING.md 正文中写到的 Bun 版本为 1.3.10，但当前仓库 mise.toml 已将其升级为 1.4.1+4661e494f 并通过 [tools.bun.platforms] 按 macOS/Linux 的 arm64/x64 分别声明下载 URL 与 sha512 checksum。这正是"以 mise.toml 为准"的体现——版本若有出入，一律以 mise.toml 与 mise.lock 为准。根目录 pnpm run test:toolchain（即 bun run test/mise-bun-pin.test.ts）会校验已安装的 Bun 版本与声明是否一致。

此外，mise.toml 设置了 min_version = "2026.8.15"、lockfile = true 与 locked = true，并将 {{config_root}}/node_modules/.bin 注入 PATH，确保仓库内的本地命令优先使用工作区内的二进制。

1.2 安装步骤

# 1. 克隆仓库（先 fork 到自己的账号下）
git clone https://github.com/YOUR_USERNAME/composio.git
cd composio

# 2. 安装锁定版本的整套工具链
mise install

# 3. 安装依赖（pnpm workspace）
pnpm install

# 4. 构建全部包（底层为 turbo build）
pnpm build

# 5. 运行测试
pnpm test

从根目录 package.json 可以看到，pnpm test 并非单一测试命令，而是依次执行工具链校验、安装脚本测试、发布流程测试、Provider 兼容性测试、各 TypeScript 包测试以及示例校验的组合命令：

"test": "pnpm run test:toolchain && pnpm run test:install-sh && pnpm run test:release-workflow && pnpm run test:provider-compatibility && turbo test --filter=./ts/packages/** --filter=!@e2e-tests/* && pnpm run test:examples"

二、仓库结构总览：双语言 monorepo

Composio 仓库采用 pnpm workspace + turbo 的 monorepo 布局，根目录 package.json 的 workspaces 字段显式声明了 TypeScript 包集合（ts/packages/core、ts/packages/experimental、ts/packages/slim、ts/packages/cli、ts/packages/cli-keyring、ts/packages/cli-local-tools、ts/packages/json-schema-to-zod、ts/packages/json-schema-to-effect-schema、ts/packages/ts-builders、ts/packages/providers/*）。

composio/
├── ts/                        # TypeScript SDK workspace
│   ├── packages/
│   │   ├── core/              # 核心 SDK 包 (@composio/core)
│   │   ├── cli/               # CLI 二进制与命令实现
│   │   ├── cli-keyring/       # CLI 的密钥环辅助
│   │   ├── cli-local-tools/   # CLI 的本地工具支持
│   │   ├── providers/         # AI 框架 Provider 适配层
│   │   ├── json-schema-to-zod/ # JSON Schema 转换工具
│   │   └── ts-builders/       # TypeScript 构建辅助
│   ├── e2e-tests/             # 运行时与 CLI 端到端测试
│   ├── examples/              # TypeScript 示例
│   └── scripts/               # 构建与维护脚本
├── python/                    # Python SDK
│   ├── composio/              # 主 Python 包
│   ├── providers/             # Python Provider 适配层
│   ├── tests/                 # pytest 测试套件
│   ├── scripts/               # 开发与发布脚本
│   └── docs/                  # 发布说明与流程文档
├── docs/                      # 文档站点
├── test/                      # 根级发布/安装脚本测试
└── .github/                   # GitHub Actions 与共享 CI 动作

各工作区的内部协作规则可参考 ts/AGENTS.md 与 python/AGENTS.md，这两份文件明确划分了 TypeScript 与 Python 的职责边界、命令入口与安全约束。

三、常用开发命令

3.1 根目录 TypeScript 命令

CONTRIBUTING.md 给出了一组面向日常开发的命令，与根目录 package.json 中的 scripts 一一对应：

# 构建所有包（turbo build）
pnpm build

# 仅构建 TypeScript 包
pnpm build:packages

# 代码检查（oxlint）
pnpm lint

# 自动修复可修复的 lint 问题
pnpm lint:fix

# 格式化支持的文件（prettier）
pnpm format

# 创建新的 TypeScript Provider
pnpm create:provider <provider-name> [--agentic]

# 创建新的 TypeScript 示例
pnpm create:example <example-name>

# 检查 peer 依赖
pnpm check:peer-deps

# 更新 peer 依赖
pnpm update:peer-deps

其中 pnpm create:provider 与 pnpm create:example 分别对应 bash ts/scripts/create-provider.sh 与 bash ts/scripts/create-example.sh；check:peer-deps 与 update:peer-deps 则对应 tsx ts/scripts/check-peer-deps.ts 与 tsx ts/scripts/update-peer-deps.ts（见 package.json）。

3.2 死代码检测（Dead Code CI）

仓库在每次 PR 上运行 "Dead Code" CI 工作流，用于报告疑似孤立代码，结果写入运行摘要，但不会让构建失败。本地复现同一套检查：

# TypeScript：未使用的文件、导出、类型与依赖（配置见 knip.json）
pnpm dlx knip@5

# Python：未使用的函数、类与变量（vulture；白名单见 python/config/vulture_allowlist.py）
cd python && make dead-code

# GitHub Actions：孤立的可复用工作流与 composite action
bash .github/scripts/check-orphan-ci.sh

这些工具存在误报（公共 API 表面、动态导入、import-map 目标等），因此结果仅作参考：删除前需确认该发现确实未被引用，并在 knip.json 或 python/config/vulture_allowlist.py 中登记确认的误报。

以 python/config/vulture_allowlist.py 为例，它通过"裸引用"（bare reference）的方式标记确认的误报符号，例如 SessionAttachResponseExperimental 等仅通过 __all__ 与 TYPE_CHECKING 重导出、因而被 vulture 误判为未使用的符号。这印证了死代码检测"advisory（咨询性）"的定位。

四、编码规范

4.1 TypeScript

1. 遵循所编辑包内的既有风格；
2. 新增 TypeScript SDK 代码必须使用 TypeScript；
3. 公共 API 优先使用命名导出（named exports），除非该包本地模式另有约定；
4. 公共 API 变更必须带有类型并补充 TSDoc 文档；
5. 新行为与 bug 修复需补充针对性测试；
6. 通过仓库脚本使用 Oxlint 与 Prettier；
7. 生成或 vendored 代码不要手工修改，除非该包明确拥有该产物。

从 ts/AGENTS.md 还可看到更细的规则：不要编辑 ts/vendor/（只读子模块）；仅在发布 TypeScript 包变更时添加 changeset；@composio/cli 与 @composio/cli-local-tools 永不添加 changeset（CLI 说明记录在 ts/packages/cli/CHANGELOG.md）。值得注意的还有其数据解析原则：在边界处用 schema 解析未类型化的外部数据——SDK 包内用 zod，CLI 包内用 effect/Schema，禁止手写 'x' in obj / typeof 链式守卫或用 as 强转解析后的 JSON。

4.2 Python

1. 遵循 python/ 下既有的 Python SDK 布局；
2. 通过 Python make 目标使用 Ruff 进行格式化与 lint；
3. Provider 相关改动必须放在对应的 python/providers/* 包内；
4. 行为变更需补充 pytest 覆盖。

python/AGENTS.md 还补充了一条关键的安全约束：API 响应的每个字段都是不可信输入，SDK 的威胁模型假设后端可能被攻破或连接被 MITM，第三方 toolkit 可能返回任意内容。当不可信的目录组件（如 slug、ID）参与构造文件系统路径时，必须使用 composio.utils.safe_path.secure_join(root, *components)；对不可信文件名使用 secure_basename_join(base, filename, root=root)。两条规则：一是锚定必须基于常量（不能用不可信输入参与构建的目录作为校验基准），二是在触碰文件系统之前完成校验。tests/test_path_join_guardrail.py 会强制约束任何右侧不是字面量或模块常量的路径拼接必须登记在案。

4.3 错误处理

1. 使用所编辑包内既有的错误类与结果形态；
2. 错误消息需包含足以定位失败操作的上下文；
3. 除非调用方有明确的 fallback 路径，否则不要吞掉错误。

五、文档要求

当变更影响公共行为、安装流程、示例、环境变量、发布步骤或 Provider 用法时，必须同步更新文档。

文档站点相关的改动，需先阅读 docs/CLAUDE.md。该文件是 Claude Code 兼容垫片，实际指引位于 docs/AGENTS.md（文档站点指南）、docs/agent-guidance/（docs-agent 上下文）与 docs/decisions/（中立决策记录）。

包级文档通常应包含：

1. 简短包描述；
2. 安装说明；
3. 使用示例；
4. 公共 API 说明；
5. 相关的环境变量或认证要求；
6. 相关的 Provider 限制或流式（streaming）细节。

六、Pull Request 流程

1. 从目标基线分支创建分支。多数活跃的 SDK 与文档工作以 next 为基线：

   git checkout next
   git pull origin next
   git checkout -b feature/your-feature-name
   

2. 做出与 issue 或功能范围匹配的聚焦变更；

3. 为行为变更添加或更新测试；

4. 用户可见行为变更时更新文档；

5. 为影响已发布 TypeScript 包的变更添加 changeset：

   pnpm changeset
   

   根级纯文档变更（例如修改本文档）无需 changeset；

6. 开 PR 前在本地运行最小且充分的验证命令；

7. 推送分支并针对正确的基线分支打开 PR。

changeset 相关脚本在 package.json 中均有对应：changeset（创建）、changeset:version（统一版本）、changeset:release（发布，底层为 bash ts/scripts/changeset-release.sh），另有 changeset:pre-enter / changeset:pre-exit 管理预发布模式，以及 validate:changesets（node ts/scripts/validate-changesets.mjs）校验 changeset 合法性。

七、创建新 Provider

Provider 是 Composio 连接各类 AI 框架（Anthropic、OpenAI、LangChain、CrewAI、Gemini 等）的适配层，仓库同时维护 TypeScript 与 Python 两套 Provider 实现（分别位于 ts/packages/providers 与 python/providers）。

7.1 TypeScript Provider

使用脚手架脚本：

pnpm create:provider my-provider [--agentic]

随后：

1. 实现必需的 Provider 方法；
2. 在 Provider 包下添加测试；
3. 当 Provider 存在用户可见的配置细节时，补充示例或文档；
4. 运行包测试与相关构建检查。

--agentic 参数会生成面向 agentic（智能体自主调用）场景的 Provider 骨架。

7.2 Python Provider

在 python/ 目录下使用 make 目标：

cd python
make create-provider name=my-provider

对于 agentic Provider：

cd python
make create-provider name=my-provider agentic=true

从 python/Makefile 的 create-provider 目标可以看到其完整参数支持：name 必填，agentic=true 追加 --agentic，output=<directory> 追加 --output-dir，最终执行 bash scripts/create-provider.sh。完成后添加 Provider 测试并运行相关 Python 检查。

八、测试指南

8.1 TypeScript SDK

# 根级 TypeScript 测试套件
pnpm test

# 全部 TypeScript 端到端测试
pnpm test:e2e

# 按运行时拆分
pnpm test:e2e:node
pnpm test:e2e:deno
pnpm test:e2e:cli
pnpm test:e2e:cloudflare

# 打开 Vitest UI
pnpm test:ui

从根目录 package.json 可知，E2E 测试通过 turbo 按过滤器运行：test:e2e:node 对应 @e2e-tests/node-*，test:e2e:deno 对应 @e2e-tests/deno-*，test:e2e:cli 对应 @e2e-tests/cli-*，还有 test:e2e:install（@e2e-tests/cli-install）与 test:e2e:cloudflare（@e2e-tests/cf-*）。测试实现位于 ts/e2e-tests，覆盖 CLI、Node/Deno/Cloudflare 等运行时。

8.2 Python SDK

cd python
make env                 # 创建并同步开发环境（uv venv + uv sync + 安装 providers）
source .venv/bin/activate

make fmt                 # nox -s fmt（Ruff 格式化）
make chk                 # nox -s chk（Ruff lint + mypy 等检查）
make tst                 # nox -s tst（pytest）
make snt                 # nox -s snt（sanity 健全性检查）

也可以直接用 uv 运行聚焦的 pytest：

uv run pytest tests/test_sdk.py -v

python/Makefile 中 make env 的完整行为是：若当前不在虚拟环境中，则用 uv venv --seed --prompt composio --python 3.12 创建环境，随后 uv sync、uv sync --dev、安装全部 provider 包并 uv pip install -e .；若已在虚拟环境中则仅同步并本地安装。此外还提供了 make type_inference（nox 的 type_inference session）用于多框架类型推断测试，以及 fmt/chk/snt/tst 的友好别名 format/check/sanity/test。

8.3 文档站点

cd docs
bun install
bun run build
bun run lint:links

完整的文档工作流以 docs/CLAUDE.md 为准（实际指南位于 docs/AGENTS.md）。

九、发布流程

只有维护者（maintainers）可以发布版本。仓库区分 TypeScript/CLI 与 Python 两套发布体系。

9.1 TypeScript 包与 CLI

TypeScript 包与 CLI 的发布细节详见 ts/docs/internal/release.md，根级命令为：

pnpm changeset           # 创建 changeset
pnpm changeset:version   # 汇总版本号
pnpm changeset:release   # 发布

关键机制（来自 ts/docs/internal/release.md）：

• CLI 二进制与 npm 发布分离：@composio/cli 被标记为 private，不通过 Changesets 发布到 npm；CLI 二进制由 .github/workflows/build-cli-binaries.yml 构建并作为 GitHub Release 资产发布，install.sh 与 composio upgrade 从 Releases 下载二进制，composio upgrade --beta 解析最新 CLI 预发布版本；
• Beta 发布：Changesets 自动生成的发布 PR（Release: update version）被打开或更新时，工作流读取 ts/packages/cli/package.json 的版本，发布形如 @composio/cli@<version>-beta.<pr-number> 的预发布 tag，并挂载构建产物；
• 稳定发布：手动触发 "Build CLI Binaries" 工作流，输入已存在的 beta tag，工作流校验该 beta 发布存在且为预发布后，检出对应 commit 重新构建，发布为 @composio/cli@<version> 稳定版。稳定版升级刻意以既有 beta 发布为门槛，确保发布的稳定二进制始终对应经过测试的 beta 产物；
• 自动化发布触发条件：代码合入 main 分支或手动触发 GitHub Actions "TS SDK Release" 工作流；需在仓库设置中配置 NPM_TOKEN 与 CI_BOT_TOKEN 密钥，且所有变更必须通过 Changesets 记录、全部质量检查通过。

9.2 Python 包

Python 包的发布细节详见 python/docs/release.md，流程从 python/ 工作区处理：

1. 决定要发布的包；
2. 运行 python scripts/bump.py；
3. 脚本会逐个提示各包的下一个版本，选择 next version 或对指定包跳过；
4. 创建发布 PR；
5. 合并并发布 GitHub release。

python/docs/release.md 特别提醒：由于开发活跃于 next 分支，创建 GitHub release 时应只选择该分支；开发期间应选择 pre 创建 release-candidate。根级构建命令 make build 会先执行 clean-build（清理 dist/、build/ 及所有 provider 的产物），再逐一构建主包与每个 provider 包。

十、问题与支持

• 加入 Discord 社区（见仓库 README 中的链接）；
• 查阅官方文档站点；
• 在 GitHub 仓库提交 issue。

十一、贡献条款

向 Composio SDK 提交贡献即表示同意贡献内容以 ISC License 授权。仓库根目录的 LICENSE 为完整许可文本。

结语

Composio 的贡献体系围绕"统一工具链 + 双语言规范 + 自动化发布"三条主线设计：mise.toml 锁定全链路工具版本，package.json 与 python/Makefile 提供对称的开发命令矩阵，Changesets 与 bump.py 分别驱动 TypeScript/CLI 与 Python 的版本发布。对希望深入 Agent 工具链开发的贡献者而言，最直接的路径是从 pnpm create:provider 或 make create-provider 起步，在新增 Provider 的过程中完整走一遍"写代码 → 补测试 → 更新文档 → 提交 PR"的标准流程。