Composio 仓库导航指南：SDK Monorepo 布局、分支工作流与 Agent Skills 维护规范

本指南围绕 Composio SDK 仓库内的 .agents/skills/repo-guidance 技能及其参考文档展开，讲解如何在跨越多个包的场景下快速定位代码归属、遵循分支与 PR 规范、管理 changeset，以及理解生成文件边界与共享维护规则。读完本文，你将掌握 Composio monorepo 的标准工作流，并能借助仓库内置的验证脚本保证改动符合仓库约定。

一、repo-guidance 技能是什么

repo-guidance 是 Composio SDK 仓库维护的一套本地 Agent Skill，用于帮助开发者在整个 monorepo 中定位工作方向。其入口定义见 .agents/skills/repo-guidance/SKILL.md，内容非常精简，核心职责由 frontmatter 声明：

• 适用时机：当任务跨越多个包、需要决定代码归属、准备 PR，或用户询问的是仓库约定（而非某个具体 SDK 实现）时使用；
• 使用方式：当任务涉及多个包、发布元数据、生成文件或分支/PR 工作流时，先阅读参考文档 .agents/skills/repo-guidance/references/repository-workflow.md 再动手改文件。

这种"入口极短、细节下沉"的设计并非偶然：仓库的 skill 格式规范（见 .agents/skills/skill-maintenance/references/skill-format.md）明确要求 SKILL.md 保持精简，将详细示例、命令配方和包级说明放入一级 references/*.md，且每个引用都必须直接从 SKILL.md 链接出来，避免嵌套引用链。

二、分支与 PR 工作流

参考文档 repository-workflow.md 确立了清晰的分支约定：

• 默认活动基线分支是 next；
• 除非用户另行指定，功能分支一律从 origin/next 创建；
• SDK 与文档相关工作，PR 一律以 next 为合并目标。

这套约定与仓库整体"主分支合入即触发构建"的节奏呼应。以 CLI 发布为例，.agents/skills/cli-release/SKILL.md 中明确"对 next 的合并若触及 CLI 路径即视为一次 beta 构建"，可见 next 承担着集成分支与发布前验证的双重角色。

三、Monorepo 目录布局

仓库采用 pnpm workspace 组织的 monorepo，工作区声明见根目录 package.json。参考文档给出了顶层布局的权威划分：

目录	职责
ts/	TypeScript SDK、providers、CLI、examples，以及运行时 E2E 测试
python/	Python SDK、providers、测试、nox sessions 与发布脚本
docs/	Fumadocs 站点、生成的 API/toolkit 数据、changelog 与文档自动化
.agents/skills/	仓库本地规范技能树（canonical）
docs/agent-guidance/	面向文档 Agent 的中性上下文与工作流提示词
docs/decisions/	中性的文档决策与计划记录

从源码结构可以进一步印证：TypeScript 包全部位于 ts/packages/ 下，包括 core、experimental、slim、cli、cli-keyring、cli-local-tools、ts-builders、json-schema-to-effect-schema、json-schema-to-zod 以及 providers/* 通配的多框架适配包；Python SDK 则集中在 python/composio/ 与 python/providers/。

四、统一工具链：mise 与根目录命令

仓库通过 mise.toml 统一管理 Node、Bun、Deno、pnpm、Python 与 uv 的版本，pnpm 由 mise 的 npm 后端托管（不再依赖 Corepack）。使用 mise install 即可装齐整套工具链；mise.lock 则供 CI 读取精确版本。

根目录常用命令（均定义于 package.json 的 scripts 字段）：

pnpm install
pnpm build
pnpm build:packages
pnpm lint
pnpm typecheck
pnpm test
pnpm test:e2e
pnpm test:e2e:cli
pnpm validate:agent-skills

其中 test 是聚合命令，会依次执行 test:toolchain（校验 mise 与 Bun 版本锁定，见 test/mise-bun-pin.test.ts）、test:install-sh（installer 脚本测试）、test:release-workflow、test:provider-compatibility，再通过 turbo 跑所有包的测试与 examples 校验。build:packages 使用 turbo 过滤 ./ts/packages/** 完成全量构建。

Python 侧命令需在 python/ 目录下运行，目标定义于 python/Makefile：

make env
source .venv/bin/activate
make fmt
make chk
make tst
make snt
make build

五、Changesets 规则

参考文档明确规定了 changeset 的使用边界：

• 变更发布到 npm 的 TypeScript 包时，必须添加 changeset；
• @composio/cli 与 @composio/cli-local-tools 被 Changesets 忽略，绝不能在 changeset 中指定它们——这类包的 beta 构建与稳定版本提升应走 cli-release 技能（见 .agents/skills/cli-release/SKILL.md）；
• 纯仓库指引、纯文档、纯测试或纯验证类改动，除非发布元数据有变化，否则无需添加 changeset。

根目录还提供 changeset、changeset:version、changeset:release 等脚本（package.json），并在 pnpm test 聚合中通过 ts/scripts/validate-changesets.mjs 校验格式。

六、生成文件与供应商代码边界

参考文档对"谁可以改什么"划定了硬边界：

• ts/vendor/ 不得编辑：该目录树是只读参考；
• 生成产物归生成器所有：保持"由生成器产出"的单一所有权原则；
• 生成客户端升级：在更新版本锁定前，必须先确认包版本能够解析。

这一原则在 Python 侧同样成立：python/noxfile.py、python/config/ 中的 ruff/mypy 配置以及 python/scripts/ 下的脚本（如 generate-docs.py）共同构成生成与校验闭环，改动 SDK 客户端时需同步维护对应的生成与锁定文件。

七、Agent Skills 技能树的组织与验证

.agents/skills/ 是仓库本地技能树的唯一权威（canonical）来源，当前共包含 18 个技能，如 repo-guidance、python-sdk、typescript-sdk、cli-release、skill-maintenance 等，完整清单见验证脚本 ts/scripts/validate-agent-skills.mjs 中的 expectedSkills 数组。每个技能目录必须满足：

• 包含带 YAML frontmatter 的 SKILL.md（name 与 description 两个键，name 必须与目录名一致，且只允许小写字母、数字和连字符）；
• 必须有一级 references/ 目录存放 markdown 参考文档，且 SKILL.md 必须直接链接到每个引用文件；
• 每个技能在 AGENTS.md 的治理清单中有对应条目。

.claude/skills 是 .agents/skills 的兼容符号链接（../.agents/skills），不允许维护并行的手工副本。

技能树有两条验证链路：

pnpm validate:agent-skills
pnpm validate:skill-routing

validate:agent-skills（ts/scripts/validate-agent-skills.mjs）逐项检查：frontmatter 键是否合法、name 是否与目录匹配、描述是否含触发边界关键词 Use、SKILL.md 行数是否控制在 80 行内、引用文件是否为一级 markdown 且被链接、.claude/skills 符号链接目标是否正确、必备的嵌套指引文件是否存在，并扫描技能文档中出现的 pnpm/bun run/make/nox -s 命令是否真实存在于 package.json、docs/package.json、python/Makefile 与 python/noxfile.py。这意味着写进技能文档的命令必须可执行、可验证，文档与代码库之间不存在漂移空间。

validate:skill-routing（ts/scripts/test-skill-routing.mjs）则是一个确定性的路由冒烟测试：为每个技能预置一个代表性任务探针（probe），用探针中的特征短语对每个技能的 description 做不区分大小写的子串打分，断言期望技能是唯一最高分；同时要求每个技能至少有一个探针，保证路由覆盖与技能分类同步演化。例如 repo-guidance 的探针任务就是"在 monorepo 中导航并准备带 changeset 的 PR"，特征短语包括 monorepo、repo layout、changesets、generated-file boundaries。

八、实践建议

• 改多个包之前：先读 repository-workflow.md，确认改动落在哪个顶层目录、是否触及生成文件或发布元数据；
• 改技能树时：遵循 skill-format.md 的结构要求，并跑 pnpm validate:agent-skills && pnpm validate:skill-routing；
• 发布 CLI 时：切勿给被忽略的 CLI 包添加 changeset，统一走 cli-release 技能的 beta→stable 路径（.agents/skills/cli-release/SKILL.md）；
• 保持命令可验证：在文档或技能中写入任何 pnpm/make/nox 命令前，确认其真实存在于对应脚本或 Makefile 中，否则 validate:agent-skills 会直接报错。

这套"简洁入口 + 下沉参考 + 脚本化验证"的仓库治理模式，让 Composio 在 TS 与 Python 双 SDK、多 provider、CLI 与文档站点并存的复杂 monorepo 中，依然能保证代码归属清晰、发布路径单一、文档命令永远真实可用。