Composio 仓库 AI 编码代理指南：目录导航、技能路由、命令与发布流程全解

导读

AGENTS.md 是 Composio SDK v3 单仓库（monorepo）为 AI 编码代理（Codex、Claude Code、Cursor、pi.dev 等）准备的"上岗手册"：它规定了仓库布局、分支与 PR 流程、技能路由、生成文件边界、常用命令与发布规范，让代理在进入仓库的第一时间就能按项目约定行事。读完本文，你将掌握如何在这一多语言（TypeScript + Python）单仓库中安全导航、选择最小技能、避开生成文件红线、运行正确构建命令，并理解 Changesets 与 CLI 发布之间的边界。

仓库是什么：SDK v3 monorepo 的总体定位

Composio 是一个为 AI 代理提供 1000+ 预认证工具包、会话管理、认证、触发器和沙箱能力的开源项目。本仓库则是它的 SDK 单体仓库，产品代码主要分布在 ts/ 与 python/，文档站点位于 docs/（Fumadocs/Next.js 技术栈）。

AGENTS.md 开篇就给出了两条关键约定：

• 活跃基线分支是 next：新工作从 next 切出分支，PR 默认面向 next 合入，除非用户另有要求；
• 产物边界清晰：仓库内存在大量"生成物"（generated SDK surfaces）与"供应商快照"（vendored trees），这些文件不可手工编辑，详见下文"生成与供应商路径红线"。

这一约定与 ts/AGENTS.md、python/AGENTS.md、docs/AGENTS.md 中各自的说明保持一致，属于全仓库统一的协作基线。

进入仓库的五条守则

AGENTS.md 的 "First Steps" 部分定义了代理动工前的强制流程：

1. 先读最近的嵌套 AGENTS.md：编辑某个子树前，必须先阅读该子树下的本地指导文件（详见下文"本地指导文件"清单），因为不同子树有各自独立的规则；
2. 保留无关的脏工作：不得回退、删除或重新格式化请求范围之外的文件，避免代理的自动化操作破坏他人正在进行的工作；
3. 技能树单一来源：.agents/skills 是规范的本地技能树；.claude/skills 是兼容性符号链接（symlink），绝不能作为独立副本去编辑；
4. 不碰生成物与供应商树：详见 AGENTS.md 的 "Generated And Vendored Paths" 一节；
5. 命令必须核对：写出任何命令前，都要对照当前 package.json、Makefile、noxfile.py 或工作流文件验证，避免使用过时命令。

其中第 3 点可以在 .agents/skills/skill-maintenance/references/skill-format.md 中得到印证：该文件明确写道 ".agents/skills is canonical"、".claude/skills is a compatibility symlink"，并规定不得维护平行的手工编辑副本。

技能路由：用最小技能干最对的事

Composio 仓库维护了一套完整的本地 Agent Skills 树（位于 .agents/skills/），AGENTS.md 要求代理按任务类型选择最小相关的技能，而不是凭直觉猜测。完整路由清单如下：

技能	适用场景
repo-guidance	仓库布局、分支/PR 流程、changesets、生成文件或跨仓库维护
skill-maintenance	新增/修改本地技能、技能引用、兼容镜像或校验
bug-fixing	修复缺陷并选择回归测试
cross-sdk-parity	对齐 TypeScript 与 Python 行为、生成客户端升级、API 契约漂移
docs-decisions	文档站点工作、changelog、文档决策或文档自动化
good-docs-writing	以官方写作风格起草或修订文档
good-docs-audit	按官方风格审查现有文档并报告违规
eve	基于 eve 框架构建的持久化后端 AI 代理
typescript-sdk / typescript-testing / typescript-providers	TypeScript SDK/core/provider 工作
cli-command / cli-e2e	CLI 设计实现或 CLI 端到端测试
cli-release	一方 CLI beta 构建、稳定版升级、发布验证或恢复
python-sdk / python-testing / python-providers / python-release	Python SDK/provider/测试/发布工作

从 .agents/skills/ 目录结构看，每项技能都是一个独立目录，包含带 YAML frontmatter 的 SKILL.md 与一层 references/*.md 参考资料。例如 repo-guidance/SKILL.md 的 frontmatter 里就写明了触发边界：跨包工作、决定代码归属、准备 PR 或询问仓库约定时使用；skill-maintenance/SKILL.md 则限定"仅用于技能树维护、技能分类变化或 agent-guidance 校验工作"。

技能格式与校验规则在 skill-format.md 中有完整定义：

• name 必须与目录名一致，只允许小写字母、数字与连字符；
• description 必须包含触发边界，因为它是代理在加载正文前看到的唯一路由表面；
• SKILL.md 保持精简，详细示例与命令配方放在第一层 references/*.md，且每个引用都要直接从 SKILL.md 链接，避免嵌套引用链。

配套校验命令（见根 package.json 的 scripts）为：

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

validate:agent-skills（node ts/scripts/validate-agent-skills.mjs）检查 frontmatter、名称、引用链接、兼容符号链接状态与命令名；validate:skill-routing（node ts/scripts/test-skill-routing.mjs）则是一个确定性路由冒烟测试——为代表性任务断言期望技能按触发短语唯一命中，新增或重写技能 description 时必须同步新增/更新 probe，否则校验会失败。

仓库地图：核心目录逐层拆解

AGENTS.md 提供了一份精炼的顶层地图：

ts/                         TypeScript SDK workspace
  packages/core/            @composio/core
  packages/providers/       TypeScript provider adapters
  packages/cli/             Effect-based CLI
  e2e-tests/                Docker runtime and CLI E2E tests
python/                     Python SDK and provider packages
docs/                       Fumadocs documentation site
.agents/skills/             Canonical local agent skills
docs/agent-guidance/        Neutral docs-agent context and workflow instructions
docs/decisions/             Neutral docs decisions and ADR-style records

逐层补充说明：

• ts/（TypeScript 工作区）：pnpm workspace，包含 @composio/core（核心 SDK）、ts/packages/providers/（各框架 provider 适配器，如 OpenAI Agents、Anthropic、LangChain 等）、基于 Effect 的 CLI（ts/packages/cli/），以及 Docker 运行时与 CLI 的 E2E 测试（ts/e2e-tests/）。根 package.json 的 workspaces 字段列出了这些包的完整清单。
• python/（Python SDK）：核心 SDK 位于 python/composio/，provider 包在 python/providers/*，配套 nox sessions、发布脚本与文档。
• docs/（文档站点）：Fumadocs/Next.js 站点，包含生成式 API/toolkit 数据、changelog 与文档自动化脚本。
• .agents/skills/：本地技能树的唯一事实来源（canonical tree）。
• docs/agent-guidance/ 与 docs/decisions/：分别是"中性"的文档代理上下文/工作流提示，以及 ADR 风格的决策记录——注意它们与 .agents/skills 中偏向具体实现的技能树相分离。

生成与供应商路径红线

AGENTS.md 明确列出四类不可手工编辑的路径（会被 .gitattributes 标记为 linguist-generated/linguist-vendored，任何手工编辑都会被覆盖）：

1. ts/vendor/** —— Effect 与 Clack 的供应商只读快照（git submodules），仅供参考；
2. ts/packages/cli-local-tools/vendor/** —— 供应商化的本地工具源码（git submodules）；
3. ts/packages/core/generated/** 与 ts/packages/core/pack/generated/** —— 由 composio generate / 构建流水线产出的生成 SDK surface；
4. pnpm-lock.yaml、uv.lock、**/bun.lock —— 包管理器锁文件，只能通过运行包管理器本身来变更，绝不能手工改写。

ts/AGENTS.md 进一步强调 "Do not edit ts/vendor/; those submodules are read-only references"、"Keep generated outputs owned by their generator"，并在 ts/packages/core 的生成物上同样适用。

常用命令：两条工具链

TypeScript / pnpm（仓库根目录执行）

工具链固定：mise install 安装被钉住的工具链，pnpm 由 mise 管理而非 Corepack。核心命令：

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

对照根 package.json 的 scripts 可以核实：build 走 turbo build、build:packages 走 turbo build --filter=./ts/packages/**、typecheck 走 turbo typecheck --filter=./ts/packages/**，而 test 是一个组合脚本（toolchain → install-sh → release-workflow → provider-compatibility → turbo 包测试 → examples 校验）。ts/AGENTS.md 还补充了更细粒度的 E2E 目标：pnpm test:e2e:node、pnpm test:e2e:deno、pnpm test:e2e:cloudflare、pnpm test:e2e:cli。

Python / make（默认在 python/ 目录下执行）

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

python/AGENTS.md 对工具链做了补充：Ruff 负责格式化与 lint、mypy 负责类型检查、pytest 负责单测，并额外提供了 make type_inference 目标。Python 侧环境准备与 TS 侧不同，必须先 make env 再激活 .venv。

发布与包管理注意事项

AGENTS.md 的 "Release And Package Notes" 明确了发布边界，是代理在提交变更前必须核查的规则：

• TypeScript 包使用 Changesets 发布：只有已发布的 TypeScript 包发生变化时才需要添加 changeset；纯文档与 agent-guidance 变更不需要 changeset；
• CLI 两个包被 Changesets 排除：@composio/cli 与 @composio/cli-local-tools 被 .changeset/config.json 忽略，不得在 changeset 中引用它们；CLI 的 beta 构建与稳定版升级走 cli-release 技能，其变更记录写在 ts/packages/cli/CHANGELOG.md（见 ts/AGENTS.md）；
• Python 发布元数据位于 python/pyproject.toml、python/setup.py 与 uv.lock；当升级 composio-client 时，这三个文件必须一起更新（见 python/AGENTS.md）；
• 生成客户端的升级是手工流程：先确认目标版本已发布，再修改 pin，不能盲目推进。

本地指导文件：逐层的 AGENTS.md 体系

AGENTS.md 维护了一份"最近嵌套指导文件"索引，代理在编辑任何子树前都应先读取对应文件：

• TypeScript 工作区：ts/AGENTS.md
• 核心 SDK：ts/packages/core/AGENTS.md
• TypeScript providers：ts/packages/providers/AGENTS.md
• CLI：ts/packages/cli/AGENTS.md
• E2E 测试：ts/e2e-tests/AGENTS.md
• Python SDK：python/AGENTS.md
• Python providers：python/providers/AGENTS.md
• 文档：docs/AGENTS.md

这些嵌套文件承载了各自子树的硬性规则。例如 python/AGENTS.md 详细阐述了**信任边界（trust boundary）**模型：API 响应的每个字段（包括 slug、ID、文件名）都是不可信输入，当不可信目录组件进入文件系统路径时必须使用 composio.utils.safe_path.secure_join(root, *components)，不可信文件名则使用 secure_basename_join(base, filename, root=root)；两条强制规则是"锚定常量进行包含性校验"与"触碰文件系统前先校验"，并由 tests/test_path_join_guardrail.py 强制约束。而 docs/AGENTS.md 则规定了文档站点的专属规则：内部链接必须使用相对站点路径（如 /docs/...、/reference/...）、API 参考页与 toolkit 数据为生成物、changelog 条目必须带 title 与 date frontmatter 且日期格式为 YYYY-MM-DD、与外站交互优先使用 cURL，以及指向 dashboard.composio.dev 的链接必须携带 utm_source=docs 等追踪参数。

结语：让代理"读一遍就能干活"

AGENTS.md 的本质，是把一个大型多语言单仓库的隐性协作规则显式化：分支基线、技能路由、生成文件边界、命令核对、发布分级、嵌套指导文件六件事构成了代理在 Composio 仓库中的工作底盘。对开发者而言，这份文件同样是理解仓库结构的速查表——沿着 ts/、python/、docs/ 与 .agents/skills/ 四条主线，配合本文梳理的技能清单与命令矩阵，即可快速定位任意代码归属与对应的校验、发布流程；而对 AI 编码代理而言，遵循"先读嵌套 AGENTS.md、最小技能路由、不碰生成物、命令先核对"的四条纪律，就能在仓库中安全高效地完成从缺陷修复到跨 SDK 对齐的各种任务。