Composio 仓库工作流指南：分支策略、目录布局与工具链规范

本指南基于 Composio SDK 仓库的官方工作流文档（repository-workflow.md）整理而成，面向需要在多包（monorepo）内提交代码、发布 SDK 或维护文档的开发者与 AI 编码 Agent。读完本文，你将掌握该仓库的分支与 PR 约定、各目录职责划分、基于 mise 的工具链管理、Changesets 发布规则，以及生成文件与 vendor 文件的边界约束，从而在贡献代码时避免常见的流程性错误。

分支与 PR 工作流

Composio 采用单活跃基线分支的协作模型，所有常规开发围绕 next 分支展开：

• 默认活跃基线：next，它是当前 SDK v3 开发的主干线。
• 创建特性分支：除非用户明确指定其他基线，否则一律从 origin/next 检出新分支，而不是从本地过期的 next 或 main 分支派生。
• PR 目标分支：SDK 与文档相关工作统一把 PR 合并目标指向 next。

这套约定在仓库根目录的 AGENTS.md 中也有呼应："Branch new work from next and target PRs at next unless the user says otherwise"。从仓库结构看，next 分支同时承载 ts/（TypeScript SDK）与 python/（Python SDK）两条产品线以及 docs/ 文档站的变更，因此任何横跨多包的工作都应该先确认当前基线与目标分支，避免把跨包改动散落在不同 PR 中。

仓库布局：六块核心区域

仓库采用 pnpm workspace 组织的 monorepo 结构（见根目录 package.json 的 workspaces 字段），顶层目录职责划分如下：

目录	职责
ts/	TypeScript SDK、providers 适配器、Effect 架构的 CLI、示例代码与运行时 E2E 测试
python/	Python SDK、providers、pytest 测试、nox 会话与发布脚本
docs/	Fumadocs 文档站、生成的 API/toolkit 数据、changelog 与文档自动化
.agents/skills/	官方维护的本地技能树（canonical local skill tree）
docs/agent-guidance/	面向文档 Agent 的中立上下文与工作流提示
docs/decisions/	中立的文档决策记录与计划

其中 .agents/skills/ 是仓库独有的 Agent 协作设施：它按领域拆分了 18 个技能，例如 repo-guidance、cli-release、cross-sdk-parity、python-testing 等。每个技能目录下都有 SKILL.md 描述文件与 references/ 引用文档，本文所依据的 repository-workflow.md 正是 repo-guidance 技能的引用文档，用于在多包改动、发布元数据、生成文件或分支/PR 流程相关任务前提供规范。

需要留意的是 AGENTS.md 的补充说明：.claude/skills 只是 .agents/skills 的兼容性软链接（symlink），不应作为独立副本被修改；同时任何子树操作前应先阅读最近的嵌套 AGENTS.md。

工具链与常用命令

统一工具链：mise

仓库不依赖系统自带的 Node/Python，而是通过 mise 管理全部运行时版本。根目录 mise.toml 是工具链版本的"单一事实来源"（single source of truth），覆盖 Node、Bun、Deno、pnpm、Python 与 uv：

[tools]
"npm:pnpm" = "11.8.0"
node = "24.17.0"
deno = "2.6.7"
python = "3.12"
uv = "0.8.19"

其中 pnpm 通过 mise 的 npm backend 固定版本，不由 Corepack 管理（Node.js v25 起不再分发 Corepack）；Bun 则通过不可变 npm 平台包安装。CI 环境下精确版本从 mise.lock 读取。首次进入开发环境时执行：

mise install

pnpm run test:toolchain（对应 test/mise-bun-pin.test.ts）会校验声明的 Bun 修订版本与已安装二进制是否一致，防止工具链漂移。

根目录 pnpm 命令

以下命令在仓库根目录执行，全部映射到根 package.json 的 scripts 中：

pnpm install          # 安装 workspace 依赖
pnpm build            # turbo 全量构建
pnpm build:packages   # 仅构建 ts/packages/** 下的包
pnpm lint             # oxlint 检查（覆盖 ts/ 与 test/）
pnpm typecheck        # turbo 对 ts/packages/** 执行类型检查
pnpm test             # 工具链 + install-sh + 发布流程 + provider 兼容 + 包测试 + 示例验证
pnpm test:e2e         # 运行时 E2E（Docker runtime）
pnpm test:e2e:cli     # CLI E2E
pnpm validate:agent-skills   # 校验技能树格式与路由

从源码看，pnpm test 是一个组合命令：依次运行 test:toolchain、test:install-sh（执行 test/install-sh-release-resolution.test.sh 等 shell 测试）、test:release-workflow、test:provider-compatibility、turbo test 与 test:examples，因此在提交跨包改动前跑一次 pnpm test 即可覆盖绝大多数回归面。lint 与格式化还通过 husky + lint-staged 在提交阶段自动执行（见 package.json 的 lint-staged 配置：TypeScript 走 oxlint --fix，Python 走 ruff check --fix 与 ruff format）。

Python 侧 make 命令

Python 相关命令统一在 python/ 目录下执行，入口是 python/Makefile：

make env                 # 创建并同步虚拟环境（uv venv + uv sync + 安装 providers + pip install -e .）
source .venv/bin/activate
make fmt                 # nox -s fmt：Ruff import 修复与格式化
make chk                 # nox -s chk：Ruff check + mypy
make tst                 # nox -s tst：pytest 测试套件
make snt                 # nox -s snt：sanity 测试
make build               # 构建 sdist/wheel 及全部 provider 包

make env 的实现细节值得注意（见 python/Makefile）：它会用 uv 以 Python 3.12 创建名为 composio 的 venv，随后依次执行 uv sync、uv sync --dev、make provider（逐个安装 providers 下的包）与 uv pip install -e .。如果已经处于虚拟环境中，则只执行同步而不重复创建。此外 Makefile 还提供了友好别名：make format ≡ make fmt、make check ≡ make chk、make test ≡ make tst、make sanity ≡ make snt。各 nox 会话（fmt、chk、fix、type_inference、tst、tst_autogen、snt）的定义可参考 python/noxfile.py 及 python-testing 技能引用。

Changesets 变更集规则

TypeScript 包的版本发布走 Changesets 流程（根目录脚本 changeset / changeset:version / changeset:release，见 package.json），规则如下：

1. 何时添加：只有改动影响已发布的 TypeScript 包时才需要添加 changeset。
2. CLI 包例外：@composio/cli 与 @composio/cli-local-tools 被 Changesets 明确忽略（ignored），永远不要在 changeset 中指向这两个包；CLI 的 beta 构建与稳定版晋升统一走 cli-release 技能（见 .agents/skills/cli-release/references/release-workflow.md）。
3. 免 changeset 场景：仓库指引（repo guidance）、纯文档、纯测试或纯校验类改动无需 changeset，除非涉及发布元数据变更。

这与 AGENTS.md 的说明一致："Documentation-only and agent-guidance-only changes do not need a changeset"。仓库还提供 pnpm validate:changesets（ts/scripts/validate-changesets.mjs）来校验 changeset 的合法性，提交前可运行。

生成文件与 vendor 文件边界

仓库对"谁拥有哪些文件"有严格约定，违反会被覆盖或破坏只读引用：

• ts/vendor/ 只读：该目录是从 Effect 与 Clack 等上游仓库引入的 git submodule 快照，仅作参考，禁止手改；改动既会被覆盖，也会破坏与上游的 diff 对比能力。
• 生成输出归生成器所有：例如 ts/packages/core/generated/、ts/packages/core/pack/generated/ 等由 composio generate 或构建管线产出的 SDK 表面，以及锁文件 pnpm-lock.yaml、uv.lock、**/bun.lock——锁文件只能通过包管理器命令更新，不能手工编辑（详见 AGENTS.md 的 Generated And Vendored Paths 一节）。
• 生成的客户端升级要"先验证再改 pin"：当升级由代码生成器产出的客户端版本时，必须先确认目标版本已经发布、包版本能正确解析，然后再更新 pin。从 AGENTS.md 看，这类 bump 是手动流程，且跨 TypeScript/Python 的客户端行为对齐属于 cross-sdk-parity 技能的管辖范围。

提交前的快速检查清单

综合以上规范，一次合规的仓库改动应依次确认：

1. 从 origin/next 创建特性分支，PR 目标为 next；
2. 确认改动落在正确的目录（ts/、python/、docs/ 等），跨包改动提前阅读对应子树的 AGENTS.md；
3. 用 mise install 对齐工具链，按所在语言分别执行 pnpm ... 或 make ... 命令完成构建、lint、类型检查与测试；
4. 若影响已发布 TypeScript 包，添加 changeset（但绝不指向被忽略的 CLI 包）；纯文档/测试/校验改动无需 changeset；
5. 不触碰 ts/vendor/ 与任何生成文件；升级生成客户端前先验证版本可解析。

遵循上述约定，无论是人工开发者还是 AI 编码 Agent，都能在 Composio 这个跨 TypeScript、Python 与文档站的大型 monorepo 中稳定、可复现地提交与发布代码。