深入 @composio/core：Composio TypeScript SDK 核心包的范围、开发命令与工程规范

深入 composio/coreComposio TypeScript SDK 核心包的范围、开发命令与工程规范【免费下载链接】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/packages/core/AGENTS.md 为骨架结合composio/core包的真实源码Composio 主类、模型层、provider、工具链与 JSON Schema/Zod 转换管线展开。读者将掌握该核心包在 monorepo 中的职责边界、核心类与模块布局、本地开发与验证命令以及贯穿整个 SDK 的边界解析铁律用 zod 解析、让 z.infer 类型向下游流动及其背后的实现原理。无论你是要在这个包上做功能开发、排查问题还是理解其设计本文都能作为一份可检索、可引用的开发指南。一、包边界composio/core拥有什么ts/packages/core/AGENTS.md的第一节 Scope 明确划定了这个包的领地composio/core拥有主Composio类、模型models、provider、服务services、类型types、工具函数utilities以及生成的集成表面generated integration surfaces。结合仓库结构见 ts/packages/core可以看到这套边界在文件系统上的实际落点主类src/composio.ts ——Composio类SDK 的初始化入口与全局配置中心模型层src/models ——Tools、Toolkits、Triggers、AuthConfigs、ConnectedAccounts、Sessions、Files、MCP、Experimental、ToolRouterSession、RemoteFile等Provider 层src/provider ——BaseProvider、OpenAIProvider、ComposioProvider服务层src/services —— 内部服务internal、Pusher 实时通道、遥测telemetry类型与工具函数src/types、src/utils生成表面pack/generated由构建管线生成属勿手改区域。从包管理角度该包以composio/core为名发布见 ts/packages/core/package.json当前版本 0.18.1peerDependencies要求zod 3.25.76 5运行时依赖composio/clientAPI 客户端、composio/json-schema-to-zod、openai、pusher-js等。安装方式即常规 npm 包安装npm install composio/core二、架构速览Composio 主类与模块布局2.1Composio构造与配置项Composio构造函数在 src/composio.ts 中完成三件事解析配置API Key / Base URL、初始化 API 客户端与全部核心模型、接入遥测与版本检查。ComposioConfigsrc/composio.ts支持的关键配置项如下配置项类型 / 默认值说明apiKeystring \| nullComposio API Key默认从COMPOSIO_API_KEY或用户数据文件读取baseURLstring \| nullAPI 基础地址默认指向生产后端providerTProvider工具 provider 适配器默认OpenAIProviderallowTrackingboolean默认true是否允许遥测上报dangerouslyAllowAutoUploadDownloadFilesboolean默认false是否在工具执行期间自动上传/下载文件sensitiveFileUploadProtectionboolean默认true本地文件路径是否走敏感路径黑名单如.ssh、.aws、.envfileUploadPathDenySegmentsstring[]追加到内置黑名单的敏感路径段fileUploadDirsstring[] \| false自动上传的本地目录白名单默认~/.composio/tempfileDownloadDirstring下载文件落盘目录默认home/.composio/fileshoststringSDK 所在宿主服务名用于遥测标识defaultHeadersComposioRequestHeaders追加到所有 API 请求的请求头disableVersionCheckboolean默认false是否跳过 SDK 版本检查toolkitVersionsToolkitVersionParamtoolkit 版本固定策略默认latest其中apiKey/baseURL的解析优先级在 src/utils/sdk.ts 中写得很清楚显式配置 环境变量COMPOSIO_BASE_URL/COMPOSIO_API_KEY 用户数据文件 默认值两者均缺失时抛出ComposioNoAPIKeyError。toolkit 版本则遵循用户字符串 环境变量COMPOSIO_TOOLKIT_VERSION_TOOLKIT与用户对象合并 latest的优先级src/utils/sdk.ts例如COMPOSIO_TOOLKIT_VERSION_GITHUB20250902_002.2 模型层会话优先的面向用户 API构造器会挂载一组模型实例src/composio.tscomposio.tools/composio.toolkits—— 列出、获取、执行工具与 toolkit 元数据composio.sessions—— 创建与复用会话composio.create/composio.use是其别名绑定见 src/composio.tscomposio.toolRouter是旧名仅作向后兼容保留composio.triggers—— Webhook 触发器与事件订阅composio.authConfigs/composio.connectedAccounts—— 认证配置与已连接账户管理composio.files—— 文件上传/下载composio.mcp—— 已废弃的独立 MCP 服务管理新代码应改用composio.create(userId, { mcp: true })获取会话级 MCP 端点composio.experimental—— 实验性 API 命名空间。包级导出在 src/index.ts 中统一收敛既包括类与类型Composio、OpenAIProvider、Sessions、AuthScheme、各types也包括一批纯函数工具dereferenceJsonSchema、jsonSchemaToZodSchema、toStrictJsonSchema、omitNullToolArguments、normalizeToolArguments、敏感文件路径守卫assertSafeFileUploadPath、远程响应读取限制readResponseBodyWithLimit等以及错误类型ValidationError、JsonSchemaToZodError、JsonSchemaRefResolutionError等。三、本地开发命令如何构建、测试与类型检查AGENTS.md 的 Commands 节给出的命令需在仓库根目录执行除非包内命令更精确pnpm --filter composio/core test # 只跑核心包测试 pnpm --filter composio/core typecheck # 只做核心包类型检查 pnpm typecheck # 全工作区类型检查 pnpm test # 全工作区测试从 ts/packages/core/package.json 的 scripts 可以看到包内实现testvitest run测试用例集中在 ts/packages/core/test按AuthConfigs、connectedAccounts、models、provider、tools、utils、types等分目录组织typechecktsc --noEmit --skipLibCheck之后还会对 type-tests 做一次tsc -p tsconfig.type-tests.json即包含.test-d.ts类型级测试buildpnpm exec tsdown打包为 ESM/类型声明见publishConfig中的dist/index.mjs与dist/index.d.mtsgenerate:docstsx scripts/generate-docs.ts从源码生成 SDK 文档。遵循 ts/AGENTS.md 的建议改动时应先跑聚焦的包级测试再做全工作区测试避免用全量测试拖慢迭代。四、工程规范核心包的五条开发红线AGENTS.md 的 Rules 节定义了composio/core的代码准入标准逐条结合源码展开公共 API 的变更必须带类型且带文档typed and documented。这与ComposioConfig中每个字段都带 JSDoc 注释含example、default的做法一致参见 src/composio.ts。作为被 1000 工具链下游引用的公共包类型即契约。行为变更必须补充回归测试。仓库中大量.test.ts即为此服务例如 strict JSON Schema 的语料级回归 test/utils/jsonSchema.strict.corpus.test.ts 与 test/utils/jsonSchema.test.ts。不手改生成客户端代码。生成表面集中在ts/packages/core/pack/generated以及构建产物根目录 AGENTS.md 明确将其列入 Generated And Vendored Paths 禁区改动会被再生成覆盖。改动共享概念前先检查 Python 端 parity。tools、toolkits、sessions、auth configs、connected accounts 在 TypeScript 与 Python SDK 间必须行为一致仓库为此提供了python/tests/test_cross_sdk_compatibility.py以及核心包内的 provider 契约测试 test/providers/refContract.test.ts。边界解析铁律详见下一节。五、边界解析铁律zod 是唯一入口断言不是验证这是 AGENTS.md 中技术含量最高的一条规则原文值得完整引用Parse untyped or external data (API payloads, JSON,unknown) at the boundary with zod schemas and letz.infertypes flow downstream. Never hand-roll structural guards (x in obj/typeofchains) or cast parsed JSON withas— an assertion is not validation.即凡是在边界处解析无类型/外部数据API 载荷、JSON、unknown必须用 zod schema 解析并让z.infer推导出的类型向下游流动严禁手写结构守卫或as强转——断言不是验证。5.1 为什么这条规则是核心包的生命线composio/core的输入几乎全部来自运行时边界Composio API 返回的工具 schema、用户传入的自定义工具、Webhook 载荷、远端文件内容。这些数据在编译期都是unknown。若用手写x in obj/typeof链做结构判断或直接as断言等于把运行时数据是否真的符合类型这件事押在运气上——一旦字段缺失或类型不符错误会在几百行之外以诡异的形式爆发。zod 则把校验收敛到边界处失败即抛出携带精确路径与修复提示的ValidationError。实现证据在 src/errors/ValidationErrors.tsValidationError包装ZodError把每个 issue 格式化为[code] path - message并注入possibleFixes对最常见的invalid_type还会生成期望 X实际收到 Y的人性化消息。错误码体系VALIDATION_ERROR、JSON_SCHEMA_TO_ZOD_ERROR、JSON_SCHEMA_REF_RESOLUTION_ERROR也在此定义。5.2 从 JSON Schema 到 Zod双向转换管线核心包维护了一条完整的 schema 转换管线全部围绕 zod 展开JSON Schema → Zodsrc/utils/jsonSchema.ts 的jsonSchemaToZodSchema(jsonSchema, { strict })将工具参数 schema 转成 zod schemastrict: true时先经removeNonRequiredProperties剔除非必填属性并强制additionalProperties: false。转换失败抛出JsonSchemaToZodError并把具体属性路径带进错误信息。Zod → JSON Schemasrc/utils/zodSchema.ts 的zodSchemaToJsonSchema同时兼容 Zod v4_def.type为字符串字面量与 v3 兼容层统一序列化.default()、.transform()、.pipe()语义——这正是同一规则在两个运行时下行为一致的典型体现。5.3 深度防御$ref解析与严格模式在 src/utils/jsonSchema.ts 中还有一批围绕 schema 边界的防御性工具均可作为 zod 解析的预处理dereferenceJsonSchemaL176-L286内联内部$ref#/$defs/...外部http(s)引用保持原样并打 warn 日志防 SSRF/本地文件泄露的审计信号内置MAX_REF_CHAIN_DEPTH100、MAX_NODE_DEPTH512深度上限环引用用{ type: object, additionalProperties: true }哨兵截断无法解析时默认抛JsonSchemaRefResolutionError也可传{ onUnresolved: sentinel }做宽容降级针对上游 API 发出的悬空$ref见代码注释中的 issue 引用。ensureObjectTypeOnProperties为带properties却缺type: object的节点补上类型——OpenAI 容忍省略但 Gemini 严格校验 OpenAPI 3.0 会直接拒绝。toStrictJsonSchema为 OpenAI structured outputs 的strict: true归一化 schema——所有属性进required并放宽为可空、additionalProperties: false、oneOf转anyOf、剥离default/examples无法无损表达的构造allOf、prefixItems、自由格式对象等如实上报到unsupported而非悄悄改写。每次改写都记录path reason上限 50 条、totalChanges保留真实计数。omitNullToolArguments配合严格模式把模型为省略语义发出的null参数在调用工具前剔除且只剔除 schema 不接受null的键——可空字段的显式null清空该值语义会被保留。这与toStrictJsonSchema的source字段配对使用构成严格输出 → 参数净化 → 工具调用的完整闭环。所有这些函数都从 src/index.ts 对外导出因此边界用 zod 解析不仅是一条开发守则更是一套开箱即用的公共工具集。六、技能路由与工作流定位AGENTS.md 的 Skill Routing 节把开发任务映射到三个技能域typescript-sdkcomposio/core的功能开发、共享包行为、生成 SDK 表面与 modifierstypescript-testingVitest 测试、类型检查、包构建、示例与运行时 E2E 验证cross-sdk-parity需要与 Python SDK 或生成客户端契约对齐的行为改动。这一划分与根目录 AGENTS.md 的技能树保持一致也和仓库实际的包结构吻合provider 适配器独立成包ts/packages/providersCLI 基于 Effect其边界解析约定为effect/Schema见 ts/AGENTS.md而composio/core统一采用 zod。开发者在进入子树前应先读最近的嵌套 AGENTS.md根目录 AGENTS.md 的 First Steps 第一条这正是本指南存在的意义。七、快速上手与进一步阅读结合 ts/packages/core/README.md拿到COMPOSIO_API_KEY后最小可用示例为import { Composio } from composio/core; const composio new Composio({ apiKey: process.env.COMPOSIO_API_KEY }); // 每个会话都绑定到你的一个终端用户 const session await composio.create(user_123); const tools await session.tools(); // 默认返回 OpenAI function-calling 格式 // 多轮对话持久化 sessionId用 use() 复用 const resumed await composio.use(session.sessionId);会话默认只暴露少量元工具动态发现、认证、执行避免把上百条工具定义塞进上下文session.tools({ modifySchema, beforeExecute, afterExecute })支持 modifiers 变换 schema 与拦截执行。更完整的实践可继续阅读包文档与配置说明ts/packages/core/README.md主类与全部配置项ts/packages/core/src/composio.ts边界解析与 schema 管线ts/packages/core/src/utils/jsonSchema.ts、ts/packages/core/src/utils/zodSchema.ts错误体系ts/packages/core/src/errors/ValidationErrors.ts测试与回归样本ts/packages/core/test/utils/jsonSchema.strict.test.ts、ts/packages/core/test/providers/refContract.test.ts上层工作区规范ts/AGENTS.md、根目录 AGENTS.md一句话总结本文composio/core是 Composio TypeScript SDK 的心脏它用类型化 文档化的公共 API、回归测试兜底、生成表面不可手改、跨 SDK parity 对齐、zod 统一边界解析五条规范把让 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），仅供参考