Skybridge 文件处理指南useFiles 与 useDownload 实现文件上传、下载与打开的完整教程【免费下载链接】skybridgeSkybridge is a full-stack TypeScript framework for MCP Apps and ChatGPT Apps. Type-safe. React-powered. Platform-agnostic.项目地址: https://gitcode.com/gh_mirrors/skybr/skybridge本文带你快速上手Skybridge一个面向 MCP Apps 与 ChatGPT Apps 的全栈 TypeScript 框架中的两个文件处理 HookuseFiles与useDownload。它们分别解决文件如何进应用上传、选择文件和文件如何出应用保存到用户设备两大核心问题让你在对话式应用中轻松实现文件上传、下载与打开。为什么 MCP Apps 需要专门的文件处理 HookMCP Apps 的界面View运行在沙箱 iframe中与普通网页不同 无法直接访问用户磁盘 传统的a download、URL.createObjectURL等下载方式被拦截 拿不到文件字节只能拿到文件引用Skybridge 通过宿主ChatGPT、Claude 等开放的桥接能力把这套差异封装成两个简洁的 React Hook你只需几行代码即可完成文件流转Hook方向支持宿主核心能力useFiles文件进应用ChatGPT上传本地文件、从 ChatGPT 文件库选文件、解析下载链接useDownload文件出应用Claude把应用生成的内容保存到用户设备useFiles三步搞定文件上传与选择useFiles返回三个函数源码见 use-files.ts分别对应传文件进来的三条路径1️⃣ upload上传本地文件把用户从设备选中的File交给宿主存储返回文件元信息FileMetadata含fileId、fileName、mimeType。注意宿主只给你引用不给字节——这是安全设计也简化了传输。import { useFiles } from skybridge/web; const { upload } useFiles(); const meta await upload(file); // meta.fileId 即为持久句柄2️⃣ selectFiles从 ChatGPT 文件库选文件打开 ChatGPT 原生的文件库选择器用户可挑选历史对话中已上传的文件授权给应用返回一个FileMetadata数组用户取消时为空数组。3️⃣ getDownloadUrl把引用换成下载链接fileId是持久的钥匙而download_url是临时缓存链接、会过期。因此最佳实践是把fileId存进状态需要时再用getDownloadUrl按需换取新链接const { downloadUrl } await getDownloadUrl({ fileId: meta.fileId }); 小提示Hook 返回的是 camelCase 字段fileId而传给工具的 FileRef 需要 snake_case 的file_id 必填的download_url构建时要手动映射一下。useDownload一键把生成的文件保存到用户设备Claude 端没有文件存储唯一能做的出向操作就是让 View 把内容交还给宿主由宿主确认后写入用户磁盘。useDownload直接返回一个download函数源码见 use-download.ts。两种内容载体内联资源resource文件内容直接随请求携带文本用text字段二进制用 base64 的blob字段资源链接resource_link只给一个 URL由宿主自己去拉取Claude 暂不支持此类型文件名由uri的最后一段决定例如file:///receipt.csv会建议保存为receipt.csv。import { useDownload } from skybridge/web; const download useDownload(); const exportCsv async () { const csv items.map((i) ${i.label},${i.amount}).join(\n); const { isError } await download({ contents: [{ type: resource, resource: { uri: file:///receipt.csv, mimeType: text/csv, text: csv }, }], }); if (isError) console.warn(用户取消或宿主不支持下载); };三个关键细节⏰ 返回值中的isError为true表示用户取消或宿主拒绝真正的失败超时、断连则会让 Promise 抛错️ 必须在用户点击等交互中触发挂载时自动下载会被宿主拒绝 一次可传多个contents批量保存多个文件实战案例聊天里压缩文件并下载官方示例 chatgpt-files 完整演示了useFiles的闭环用户拖拽或从文件库选择一个文件 → 应用调用zip-file工具压缩 → 返回压缩包引用 → 用户点击下载。核心流程只有四步完整代码见 zip-file.tsxupload(picked)上传设备文件拿到fileIdgetDownloadUrl({ fileId })换取临时下载链接组装成FileReffile_iddownload_url调用工具工具返回新的file_id再次getDownloadUrl打开下载服务端工具则用openai/fileParams声明文件入参宿主会自动把用户附件路由进来示例见 server.ts。开发过程中还可以用 Skybridge 自带的 DevTools 面板在本地调试 View 与工具调用平台兼容性速查能力ChatGPTClaudeuseFilesupload / selectFiles / getDownloadUrl✅❌ 抛出异常FileRef文件参数工具入参/出参✅❌useDownload保存文件到设备视宿主能力✅仅内联资源⚠️ 记住一句话ChatGPT 有文件仓库可以双向搬运文件Claude 只有出口。跨平台应用应做好能力检测与降级比如文件库不可用时回退到本地上传。延伸阅读useFiles API 参考useDownload API 参考文件处理指南Handle FilesFileRef 文件引用类型useCallTool把上传的文件转发给工具useOpenExternal在应用外打开链接掌握useFiles与useDownload之后你的 MCP App 就具备了完整的文件处理能力——用户上传的票据能被工具解析应用生成的报表也能一键落盘。结合 create-skybridge 模板 快速起步几分钟就能搭出属于你的文件处理应用 【免费下载链接】skybridgeSkybridge is a full-stack TypeScript framework for MCP Apps and ChatGPT Apps. Type-safe. React-powered. Platform-agnostic.项目地址: https://gitcode.com/gh_mirrors/skybr/skybridge创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考