Composio TypeScript 工作区协作规范详解：读懂 `ts/AGENTS.md`，掌握 SDK、CLI 与 E2E 测试的开发守则

Composio TypeScript 工作区协作规范详解：读懂ts/AGENTS.md，掌握 SDK、CLI 与 E2E 测试的开发守则

【免费下载链接】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

ts/AGENTS.md是 Composio 仓库中面向 AI 编码代理（Codex、Claude Code、Cursor 等）的 TypeScript 工作区指南，它定义了ts/目录的边界、技能路由、常用命令与四条硬性协作规则。本文以该文档为主线，结合仓库根部的package.json、.changeset/config.json、ts/README.md、ts/e2e-tests/README.md 与 ts/packages/cli/AGENTS.md 等源码级证据，展开讲解如何在 TypeScript SDK、Provider 适配器、CLI 与运行时 E2E 测试之间正确地做贡献，读完即可按规范独立完成一次包级改动、测试与变更记录提交流程。

工作区范围：ts/里到底装了什么

ts/AGENTS.md首先划定了 Scope：ts/包含TypeScript SDK 包、示例（examples）、CLI 以及运行时 E2E 测试。这与仓库根 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

进一步看 ts/README.md 的 Layout 段落，工作区由五类内容构成：

• packages/：发布与内部包。对外发布的有@composio/core（SDK 主体，随包附带 TypeScript 源码与 SDK 文档，便于编码代理直接检视）、@composio/slim（同一 API 的轻量版）、composioCLI 二进制、@composio/*各 Provider 适配器（OpenAI、Anthropic、Vercel AI SDK、LangChain 等）、@composio/experimental与@composio/json-schema-to-zod；内部（不发布）包包括支撑 CLI 的cli-keyring、cli-local-tools以及负责生成 TypeScript 源码的ts-builders；
• examples/：按功能与框架组织的可运行示例；
• e2e-tests/：Node、Deno、Cloudflare Workers、CLI 四种运行时下的端到端测试；
• docs/：工作区 SDK 文档（API 笔记与内部指南）；
• scripts/：构建、校验与脚手架脚本。

理解了工作区的边界，下一步就是“该用哪个技能来做这件事”——这正是ts/AGENTS.md的核心价值之一。

技能路由：按任务选最小的技能

仓库采用“技能树”机制，ts/AGENTS.md给出了 TypeScript 工作区内的路由规则，原则是使用最小相关的技能：

这些技能确实存在于仓库的.agents/skills/目录（typescript-sdk/、typescript-providers/、typescript-testing/、cli-command/、cli-e2e/、cli-release/等均在列），且根 AGENTS.md 将其视为“canonical local skill tree”。值得注意的是路由的“粒度”：SDK 与 CLI 分别路由到不同的技能，是因为二者技术栈与发布流程截然不同（SDK 用 zod、走 Changesets；CLI 用effect/Schema、不走 Changesets），这在后文会详细展开。

核心命令矩阵：从仓库根目录运行

ts/AGENTS.md给出的命令全部从仓库根目录运行：

pnpm build:packages pnpm typecheck pnpm lint:packages pnpm test pnpm test:e2e:node pnpm test:e2e:deno pnpm test:e2e:cloudflare pnpm test:e2e:cli

对照根 package.json 的 scripts 定义，可以精确理解每条命令的底层语义：

• pnpm build:packages→turbo build --filter=./ts/packages/**：只构建ts/packages下的包，是 TypeScript 工作区的主构建入口；
• pnpm typecheck→turbo typecheck --filter=./ts/packages/**：对所有 TS 包做类型检查；
• pnpm lint:packages→oxlint ts/packages：仅对ts/packages跑 oxlint（而非全仓库的pnpm lint）；
• pnpm test→ 依次执行test:toolchain、test:install-sh、test:release-workflow、test:provider-compatibility、turbo test --filter=./ts/packages/** --filter=!@e2e-tests/*与test:examples，即包级单元测试 + 示例校验，但不包含 E2E；
• 四个test:e2e:*脚本则通过 turbo 的--filter='@e2e-tests/node-*'、'@e2e-tests/deno-*'、'@e2e-tests/cf-*'、'@e2e-tests/cli-*'分别挑选对应运行时的工作区。

一个关键分工值得强调：pnpm test与 E2E 是分离的两层。ts/AGENTS.md建议“优先做聚焦的包级测试，再跑宽泛的工作区测试”，正对应了pnpm test（快、无需凭据）与pnpm test:e2e:*（慢、需要 Docker 与 API 凭据）的定位差异。

运行时 E2E 测试体系：四类运行时各司其职

E2E 命令的背后是 ts/e2e-tests/README.md 描述的完整测试矩阵：

• runtimes/node/：Node.js 运行时测试，覆盖 CJS/ESM 互操作（如cjs-basic、esm-basic）、json-schema-to-zod的 Zod v3/v4 双版本、@composio/mastraTool Router、Tool Router 会话文件（list/upload/download/delete）、session.toolkits()游标分页、TypeScriptmoduleResolution: nodenext等；
• runtimes/deno/：通过npm:说明符验证 ESM 兼容性；
• runtimes/cloudflare/：Cloudflare Workers 基础、文件处理与 AI SDK Tool Router 集成；
• cli/：在 scratch 容器中测试composio version、whoami、toolkits list/info/search等命令。

测试在 Docker 中由bun test驱动，Node/Deno/CLI 版本可通过环境变量覆盖（如COMPOSIO_E2E_NODE_VERSION=22.22.3 pnpm test:e2e:node），每个套件还会生成结构化DEBUG.log便于排障。新增测试的范式是：新建目录 → 声明@e2e-tests/<runtime>-<name>包 → 写e2e.test.ts，通过e2e(import.meta.url, { versions, env, defineTests })内联配置，fixture 运行结果用expect(result.exitCode).toBe(0)断言。这套约定保证了 E2E 与包级测试一样可声明、可复用。

四条硬性规则：什么不能碰、什么时候该记 changeset

ts/AGENTS.md的 Rules 部分是协作红线的核心，逐条解读如下：

1.ts/vendor/只读，不得编辑

ts/vendor/是只读参考子模块（Effect 与 Clack 的源码快照，git submodule），真正依赖来自 npm。根 AGENTS.md 补充说明：ts/vendor/**与ts/packages/cli-local-tools/vendor/**均以linguist-vendored标记，手工编辑会被后续同步覆盖。实际开发中，ts/vendor/的角色是源码级参考——例如 ts/packages/cli/AGENTS.md 明确列出ts/vendor/effect/packages/effect/src/、ts/vendor/effect/packages/cli/src/、ts/vendor/clack/packages/prompts/src/等作为理解 Effect 运行时与 Clack 提示 UI 的参考来源。

2. 生成产物归属生成器

ts/packages/core/generated/**与ts/packages/core/pack/generated/**是composio generate或构建流水线产出的 SDK 表面，手工修改必然被覆盖。正确做法是改生成器（CLI 的src/generation/流水线或@composio/ts-builders），再重新生成。

3. 只为已发布的 TypeScript 包加 changeset

Changesets 是 TypeScript 包发布机制（根 AGENTS.md 明示 TypeScript 包发布走 Changesets，且.changeset/config.json的baseBranch为next）。规则是：只有改动了已发布的 TypeScript 包才新增 changeset；纯文档或 agent-guidance 改动不需要。

4. CLI 包被 Changesets 忽略，改记 CHANGELOG.md

.changeset/config.json的第 17 行给出了决定性证据：

"ignore": ["@composio/cli", "@composio/cli-local-tools"]

因此永远不要为@composio/cli或@composio/cli-local-tools添加 changeset——否则会卡死 TypeScript SDK 发布动作。CLI 的人读变更记录应直接写进 ts/packages/cli/CHANGELOG.md。这与 ts/packages/cli/AGENTS.md 的 Release Workflow 完全呼应：@composio/cli的稳定版通过promote-stable工作流从已验证的 beta 提升，package.json版本只是开发哨兵，不构成二进制发布依据；CLI 的发布走cli-release技能与.github/workflows/build-cli-binaries.yml。

深度剖析：schema 边界解析策略（zod vs effect/Schema）

ts/AGENTS.md的最后一条规则最富技术含量，值得展开：

Parse untyped or external data (API payloads, JSON,unknown) at the boundary with schemas and let inferred types flow downstream: zod in SDK packages (@composio/core, providers, shared packages),effect/Schemaints/packages/cli/. Never hand-roll structural guards ('x' in obj/typeofchains) or cast parsed JSON withas.

这条规则包含三层意思：

第一，把unknown、JSON、API 响应视作信任边界，在边界处用 schema 解码。根 package.json 中zod位于根 devDependencies，且@composio/json-schema-to-zod包的存在表明 JSON Schema → zod 的转换是 SDK 的正式能力。让 schema 推断出的类型向下游自然流动，比手工维护类型断言更可靠。

第二，按包技术栈选择 schema 工具：SDK 包（@composio/core、providers、共享包）用 zod；CLI 用effect/Schema。ts/packages/cli/AGENTS.md 进一步解释：CLI 构建在 Effect.ts 生态上，其src/models/就是“Effect Schema 定义 +fromJSON/toJSON帮助函数（JSONTransformSchema()）”，因此effect/Schema是 CLI 的 schema 工具，不要在 CLI 引入 zod，反之 SDK 侧则遵循 zod 约定。

第三，禁止手写结构守卫与as强转。'x' in obj/typeof链式判断不是 schema 的替代品，as断言更不是校验——CLI 侧还明确规定“treatunknown, JSON, persisted state, and API payloads as trust boundaries. Decode them witheffect/Schemaor narrow them withPredicate”。这与 CLI 的“Effect Boundary Policy”一脉相承：所有平台访问都经 Effect 服务（Path、FileSystem、NodeOs、Command、effect/Config），同步易错操作（JSON.parse、new URL）用Either.try加Data.TaggedError，并由pnpm run validate:boundaries（属于pnpm test，CI 阻断）强制校验。换言之，这条规则在仓库中不是建议，而是被 lint 与 CI 强制执行的设计约束。

实战要点小结

在ts/工作区做一次改动，完整的合规路径是：

1. 按上文“技能路由”选定最小技能，并读取最近的嵌套AGENTS.md（根 AGENTS.md 的 First Steps 明确要求先读嵌套指南再改子树）；
2. 从仓库根目录运行pnpm build:packages、pnpm typecheck、pnpm lint:packages做基础校验；
3. 优先跑聚焦的包级测试（pnpm test），涉及跨运行时行为再按需跑pnpm test:e2e:{node,deno,cloudflare,cli}；
4. 不碰ts/vendor/与任何 generated 输出；
5. 若改动涉及已发布 TypeScript 包，新增 changeset；若涉及 CLI，直接更新 ts/packages/cli/CHANGELOG.md，且绝不为其添加 changeset；
6. 边界数据一律用 zod（SDK 侧）或effect/Schema（CLI 侧）解码，杜绝as与手写结构守卫。

ts/AGENTS.md虽然篇幅精炼，却浓缩了 Composio TypeScript 工作区“结构、路由、命令、红线”四要素，配合仓库内的 ts/README.md、ts/e2e-tests/README.md 与 ts/packages/cli/AGENTS.md 等嵌套指南，构成了一个可被 Agent 与人类开发者共同遵循的自洽协作体系。

【免费下载链接】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