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/composiots/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首先划定了 Scopets/包含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/coreSDK 主体随包附带 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-buildersexamples/按功能与框架组织的可运行示例e2e-tests/Node、Deno、Cloudflare Workers、CLI 四种运行时下的端到端测试docs/工作区 SDK 文档API 笔记与内部指南scripts/构建、校验与脚手架脚本。理解了工作区的边界下一步就是“该用哪个技能来做这件事”——这正是ts/AGENTS.md的核心价值之一。技能路由按任务选最小的技能仓库采用“技能树”机制ts/AGENTS.md给出了 TypeScript 工作区内的路由规则原则是使用最小相关的技能技能适用场景typescript-sdkcomposio/core、共享的 TypeScript 包行为、生成的 SDK 表面、modifierstypescript-providersts/packages/providers/下的所有包typescript-testingVitest、类型检查、包构建、示例或运行时 E2E 测试选择cli-command/cli-e2ets/packages/cli/与ts/e2e-tests/cli/cli-release第一方 CLI 的 beta 构建、稳定版提升、发布校验或恢复这些技能确实存在于仓库的.agents/skills/目录typescript-sdk/、typescript-providers/、typescript-testing/、cli-command/、cli-e2e/、cli-release/等均在列且根 AGENTS.md 将其视为“canonical local skill tree”。值得注意的是路由的“粒度”SDK 与 CLI 分别路由到不同的技能是因为二者技术栈与发布流程截然不同SDK 用 zod、走 ChangesetsCLI 用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 lintpnpm 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 的--filtere2e-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_VERSION22.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 与包级测试一样可声明、可复用。四条硬性规则什么不能碰、什么时候该记 changesetts/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 包加 changesetChangesets 是 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/Schemats/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、共享包用 zodCLI 用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 testCI 阻断强制校验。换言之这条规则在仓库中不是建议而是被 lint 与 CI 强制执行的设计约束。实战要点小结在ts/工作区做一次改动完整的合规路径是按上文“技能路由”选定最小技能并读取最近的嵌套AGENTS.md根 AGENTS.md 的 First Steps 明确要求先读嵌套指南再改子树从仓库根目录运行pnpm build:packages、pnpm typecheck、pnpm lint:packages做基础校验优先跑聚焦的包级测试pnpm test涉及跨运行时行为再按需跑pnpm test:e2e:{node,deno,cloudflare,cli}不碰ts/vendor/与任何 generated 输出若改动涉及已发布 TypeScript 包新增 changeset若涉及 CLI直接更新 ts/packages/cli/CHANGELOG.md且绝不为其添加 changeset边界数据一律用 zodSDK 侧或effect/SchemaCLI 侧解码杜绝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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/composiots/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首先划定了 Scopets/包含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/coreSDK 主体随包附带 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-buildersexamples/按功能与框架组织的可运行示例e2e-tests/Node、Deno、Cloudflare Workers、CLI 四种运行时下的端到端测试docs/工作区 SDK 文档API 笔记与内部指南scripts/构建、校验与脚手架脚本。理解了工作区的边界下一步就是“该用哪个技能来做这件事”——这正是ts/AGENTS.md的核心价值之一。技能路由按任务选最小的技能仓库采用“技能树”机制ts/AGENTS.md给出了 TypeScript 工作区内的路由规则原则是使用最小相关的技能技能适用场景typescript-sdkcomposio/core、共享的 TypeScript 包行为、生成的 SDK 表面、modifierstypescript-providersts/packages/providers/下的所有包typescript-testingVitest、类型检查、包构建、示例或运行时 E2E 测试选择cli-command/cli-e2ets/packages/cli/与ts/e2e-tests/cli/cli-release第一方 CLI 的 beta 构建、稳定版提升、发布校验或恢复这些技能确实存在于仓库的.agents/skills/目录typescript-sdk/、typescript-providers/、typescript-testing/、cli-command/、cli-e2e/、cli-release/等均在列且根 AGENTS.md 将其视为“canonical local skill tree”。值得注意的是路由的“粒度”SDK 与 CLI 分别路由到不同的技能是因为二者技术栈与发布流程截然不同SDK 用 zod、走 ChangesetsCLI 用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 lintpnpm 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 的--filtere2e-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_VERSION22.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 与包级测试一样可声明、可复用。四条硬性规则什么不能碰、什么时候该记 changesetts/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 包加 changesetChangesets 是 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/Schemats/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、共享包用 zodCLI 用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 testCI 阻断强制校验。换言之这条规则在仓库中不是建议而是被 lint 与 CI 强制执行的设计约束。实战要点小结在ts/工作区做一次改动完整的合规路径是按上文“技能路由”选定最小技能并读取最近的嵌套AGENTS.md根 AGENTS.md 的 First Steps 明确要求先读嵌套指南再改子树从仓库根目录运行pnpm build:packages、pnpm typecheck、pnpm lint:packages做基础校验优先跑聚焦的包级测试pnpm test涉及跨运行时行为再按需跑pnpm test:e2e:{node,deno,cloudflare,cli}不碰ts/vendor/与任何 generated 输出若改动涉及已发布 TypeScript 包新增 changeset若涉及 CLI直接更新 ts/packages/cli/CHANGELOG.md且绝不为其添加 changeset边界数据一律用 zodSDK 侧或effect/SchemaCLI 侧解码杜绝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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考