Composio Cloudflare Workers 文件能力边界dangerouslyAllowAutoUploadDownloadFiles 配置与 edge runtime 错误处理实战【免费下载链接】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导读在 Cloudflare Workersworkerd 运行时等 Edge 环境中Composio 的自动文件上传/下载能力默认是关闭的——这是由运行时条件决定的设计约束而非配置遗漏。本文以仓库中的 E2E 测试包 cf-workers-files 为线索完整剖析composio/core在 Edge runtime 下的文件操作行为composio.files.upload()/download()为何必然抛错、FileToolModifier.workerd.ts如何通过条件导入被加载、dangerouslyAllowAutoUploadDownloadFiles默认值与显式配置的差异以及如何在 Worker 中正确初始化 Composio 并写出可验证的端到端测试。读完本文你将掌握在 Cloudflare Workers 上安全集成 Composio 的完整姿势并能复现该 E2E 测试包的验证思路。背景为什么 Edge runtime 需要特殊的文件策略Composio SDK 的自动文件处理依赖 Node.js 专有 API如node:crypto、node:fs这类 API 在 Cloudflare Workers 的 workerd 运行时中不可用。因此composio/core通过 package.json 中的条件导出conditional exports按运行时环境切换不同的实现文件见 ts/packages/core/package.json#file_tool_modifierworkerd / edge-light 解析到 FileToolModifier.workerd.tsnode 与默认环境解析到 FileToolModifier.node.ts#filesworkerd / edge-light 解析到 Files.workerd.tsnode 环境解析到Files.node.ts#config_defaults同样按运行时区分默认配置见 ConfigDefaults.workerd.ts。这套按运行时切换实现的机制意味着同样的new Composio({...})代码在不同 JS 运行时下会获得不同的文件能力。理解这一点是后续所有排查工作的前提。核心事实workerd 运行时下默认配置即关闭自动文件处理在 Cloudflare Workersworkerd runtime中dangerouslyAllowAutoUploadDownloadFiles默认值为false该默认值定义于 ConfigDefaults.workerd.ts。因此你可以不做任何特殊配置直接初始化import { Composio } from composio/core; const composio new Composio({ apiKey: your-key, }); // 在 workerd 运行时中 dangerouslyAllowAutoUploadDownloadFiles 默认为 falseSDK 构造函数在 composio.ts 中通过空值合并??回退到CONFIG_DEFAULTS.dangerouslyAllowAutoUploadDownloadFiles从而保证未显式传参时也能得到确定的行为。对应地Node 环境的默认配置同样为false见 ConfigDefaults.node.ts也就是说自动文件处理在所有运行时都是显式开启opt-in的。两条错误路径Files API 抛错与 FileToolModifier 抛错在 Edge runtime 下文件相关操作存在两条独立的报错路径E2E 测试包分别对它们进行了验证。路径一composio.files.upload() / download() 直接抛错Files.workerd.ts 通过 Proxy 机制实现任何方法调用都抛错构造函数返回一个Proxy其get拦截器对除constructor、Symbol.toStringTag外的任何属性访问都返回一个直接抛错的函数。因此await composio.files.upload({ file: https://example.com/test.pdf, toolSlug: test-tool, toolkitSlug: test-toolkit, }); // 抛出File operations (upload/download) are not supported in Cloudflare Workers or Edge runtimes. // These operations require Node.js-specific APIs (e.g., node:crypto, node:fs) that are not // available in this environment. Please use a Node.js runtime for file operations. await composio.files.download({ s3Url: https://s3.example.com/test.pdf, toolSlug: test-tool, mimeType: application/pdf, }); // 抛出同样的错误注意这两个错误在发起任何网络请求之前就会抛出因此运行此类测试时使用一个 dummy API key 也完全可行——这是 README 中明确说明的实践要点。路径二显式开启自动上传后tools.execute() 经 FileToolModifier 抛错如果你在 Cloudflare Workers 中显式设置dangerouslyAllowAutoUploadDownloadFiles: true并执行一个带文件属性的工具那么执行管线中会命中 workerd 版本的 FileToolModifier.workerd.ts。该实现保留了两个关键方法modifyToolSchema()与 Node 版本共享 FileToolModifier.utils.neutral.ts 中的transformProperties会为file_uploadable属性附加format: pathfileUploadModifier()与fileDownloadModifier()直接抛出UNSUPPORTED_MESSAGE。实际抛出的错误信息为File upload/download modifiers are not available on edge runtimes yet. Please set dangerouslyAllowAutoUploadDownloadFiles: false (or unset it; it defaults to false) or run Composio in another JS runtime (Node.js / Bun).从调用链上看Tools.execute()在正式执行前会经过applyBeforeExecuteModifiers()→applyFileUploadModifiers()见 Tools.ts其中this.autoUploadDownloadFiles为true时才会实例化FileToolModifier并调用其fileUploadModifier。在 workerd 运行时下这个实例来自条件导入#file_tool_modifier见 Tools.ts因此必然命中抛错逻辑。最佳实践对于 Edge runtime请使用默认配置或显式声明关闭自动文件处理const composio new Composio({ apiKey: your-key, dangerouslyAllowAutoUploadDownloadFiles: false, // workerd 下的默认值 });需要明确在此配置下文件的上传/下载操作不会被自动处理。若你的工具调用涉及文件参数需要自行通过composio.files.upload()手动暂存staging文件并传递{ name, mimetype, s3key }描述符——而由于 Edge runtime 下files.upload()本身也会抛错这意味着在 Cloudflare Workers 上使用文件型工具目前是不可行的需要迁移到 Node.js / Bun 运行时。附带行为关闭自动上传时对空文件值的 schema 感知处理值得补充的是即便关闭了自动上传applyFileUploadModifiers()的 else 分支仍会执行一项 schema 感知的清理当工具输入中存在file_uploadable属性且参数值为空字符串时会通过dropEmptyFileUploads()实现于 FileToolModifier.utils.neutral.ts将对应键从参数中剔除。原因在于空字符串不是合法的已暂存描述符直接发送会被后端拒绝对应 issue #4233。同时 SDK 会对每个工具 slug 输出一次性警告日志提示你选择手动暂存或开启带白名单的自动上传。E2E 测试包解剖如何验证 Edge runtime 文件行为该测试包位于 ts/e2e-tests/runtimes/cloudflare/cf-workers-files是一个基于 Hono Wrangler 的测试 Worker目录结构如下cf-workers-files/ ├── src/index.ts # Hono 测试 Worker暴露 4 个测试端点 ├── test/files.spec.ts # vitest cloudflare/vitest-pool-workers 测试用例 ├── wrangler.jsonc # Worker 配置compatibility_date: 2025-01-10 ├── vitest.config.mts # 注入 COMPOSIO_API_KEY / COMPOSIO_BASE_URL 绑定 ├── .env.example # COMPOSIO_API_KEYyour-key └── package.json测试端点端点描述GET /列出所有可用的测试端点GET /test/files/upload验证files.upload()抛出预期错误GET /test/files/download验证files.download()抛出预期错误GET /test/auto-upload-disabled验证显式dangerouslyAllowAutoUploadDownloadFiles: false时 Composio 正常初始化GET /test/default-config验证默认配置不显式设置时 Composio 正常初始化各端点的实现位于 src/index.ts/test/files/upload与/test/files/download在 try 中调用文件操作若调用未抛错则以 500 返回应当抛错但未抛错的失败信息否则在 catch 中返回错误信息/test/auto-upload-disabled与/test/default-config成功初始化后返回hasProvider、hasTools、hasFiles三个能力探测字段验证 SDK 在关闭自动文件处理时其余能力完整可用。测试用例test/files.spec.ts 使用cloudflare/vitest-pool-workers在真实 workerd 环境中运行覆盖 6 个断言场景GET /返回端点清单snapshot 断言files.upload()抛出包含not supported in Cloudflare Workers的错误files.download()抛出同样错误核心用例在dangerouslyAllowAutoUploadDownloadFiles: true下通过vi.spyOn(composio.tools, getRawComposioToolBySlug)模拟返回一个带file_uploadable: true输入属性的 fixture 工具再驱动真实的composio.tools.execute()管线断言最终rejects.toThrow(not available on edge runtimes)。该用例直接验证了 workerd 版本的FileToolModifier被正确加载并生效且不需要依赖远程工具注册表或网络显式关闭自动文件处理时初始化成功provider/tools/files均存在默认配置下初始化成功。运行方式从包目录运行pnpm test:e2e或从 monorepo 根目录按包过滤运行pnpm --filter e2e-tests/cf-workers-files test:e2e:cloudflare环境变量将.env.example复制为.env并配置 API keyCOMPOSIO_API_KEYyour-composio-api-key文件操作类测试使用 dummy key 即可错误在 API 调用前抛出vitest.config.mts 会在未设置时回退到test-key并默认COMPOSIO_BASE_URL为https://backend.composio.dev。本地联调可运行pnpm devwrangler dev手动访问上述端点或使用pnpm cf-typegenwrangler types生成 Worker 类型声明。与 Node 运行时的能力对比同一份代码两种行为为帮助你理解差异根源下表对比了 workerd 与 Node 运行时下文件相关实现的差异依据仓库源码能力点workerd / edge-lightNode.js / Bunfiles.upload()/files.download()任何方法调用即抛错Proxy 实现Files.workerd.ts完整实现支持本地路径 / URL /File对象暂存到 S3FileToolModifier.fileUploadModifier()直接抛出UNSUPPORTED_MESSAGEFileToolModifier.workerd.ts基于walkFileUploadableLeaves递归暂存文件、支持beforeFileUpload钩子、路径白名单与敏感路径保护FileToolModifier.node.tsFileToolModifier.fileDownloadModifier()直接抛出UNSUPPORTED_MESSAGE基于hydrateDownloads递归下载 S3 文件并返回{ uri, file_downloaded, s3url, mimeType }FileToolModifier.node.tsdangerouslyAllowAutoUploadDownloadFiles默认值falseConfigDefaults.workerd.tsfalseConfigDefaults.node.tsschema 变换modifyToolSchema仅做format: path标注不涉及文件系统额外执行$ref解引用dereferenceJsonSchema后再变换从源码结构可以推断Node 版本的 modifier 是功能完整的实现而 workerd 版本是行为占位它保留了 schema 变换能力为 Agent 提供统一的 schema 视图但把一切涉及文件系统的实际操作上传/下载都拦截为明确的错误提示。这种显式失败而非静默降级的设计是为了让开发者第一时间发现环境不匹配而不是在不知不觉中丢失文件数据。常见错误速查在 Cloudflare Workers 中集成 Composio 时你可能遇到的典型错误与对策如下场景错误信息片段对策调用composio.files.upload()File operations (upload/download) are not supported in Cloudflare Workers or Edge runtimes.文件操作需要 Node 专有 API迁移到 Node.js / Bun 运行时调用composio.files.download()同上同上开启自动上传后执行文件型工具File upload/download modifiers are not available on edge runtimes yet.将dangerouslyAllowAutoUploadDownloadFiles设为false或保持默认或在 Node.js / Bun 运行时运行关闭自动上传后传入空文件值后端参数校验错误若未剔除SDK 会自动剔除空字符串键dropEmptyFileUploads无需手工处理小结Cloudflare Workers 上的 Composio 文件能力边界可以概括为一句话Edge runtime 下自动文件处理默认关闭且不可用SDK 通过运行时条件导入 显式抛错的设计保证失败可见、行为可预期。通过 cf-workers-files 这个 E2E 测试包你可以一键复现全部四条行为路径upload 抛错、download 抛错、显式关闭可初始化、默认配置可初始化并验证FileToolModifier.workerd.ts的正确加载。若你的 Agent 工作负载需要文件上传/下载能力请优先选择 Node.js / Bun 运行时若必须运行在 Workers 上则保持默认配置并绕开文件型工具。【免费下载链接】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），仅供参考