SuperAPI AI 工具集

export-download-debugging

编程与开发

查看项目

更新于 11-16 14:22

技能介绍

用途

Export Download Debugging 是一个面向导出/下载故障排查的技能,适用于导出或下载流程看似执行完成、却生成空文件、缺失文件或无法使用的文件的场景。它针对浏览器预览、iframe 截图和 Electron 外壳环境做了专门适配。

主要能力

核心原则

将“捕获”与“保存”分开。在调试目标保存路径之前,先证明导出载荷具有非零字节。0 KB 文件往往意味着原生文件选择器或宿主先创建了目标文件,随后写入失败或被阻止。

证据收集

  • 记录载荷类型、MIME 类型、字节长度、object URL 或 data URL 路径,以及抛出的错误名称与消息。
  • 检查浏览器控制台输出,以及 showSaveFilePicker、createWritable、<a download>、URL.createObjectURL 和 URL 撤销相关的应用日志。
  • 在 Electron 中检查 will-download 路径:文件名、MIME、文件扩展名、保存对话框过滤器、取消操作和最终文件大小。
  • 确认磁盘上实际下载文件的大小,以及它能否在普通图片查看器中打开。

修复顺序

  • 先准备并验证导出载荷;在字节可用之前禁用“保存”按钮。
  • 优先使用宿主最简单稳定的保存通道。若 showSaveFilePicker().createWritable() 失败、受沙箱限制或产生空文件,改用 <a download> 或 Electron 的下载管理器。
  • 避免在载荷就绪前打开原生选择器,以防宿主在后续写入失败时留下空的目标文件。
  • 对 PNG 降级方案,当 blob URL、撤销时机、CSP 或 iframe 沙箱存在疑问时,优先使用经验证非空的 data URL。
  • 在 Electron 中为导出的图片扩展名(.png、.jpg、.jpeg、.webp)添加明确的“另存为”过滤器,让用户能选择真实的图片目标路径。
  • 保持界面克制:格式选择、文件名/路径提示、清晰的进行中与错误状态,以及一个主保存操作。

验证

  • 为非空载荷准备、回退保存行为、文件扩展名/MIME 映射以及界面禁用/错误状态添加或更新测试。
  • 运行聚焦的导出测试,然后执行 pnpm --filter @open-design/web typecheck。
  • 若改动了 Electron 下载处理,还需运行 pnpm --filter @open-design/desktop typecheck。
  • 提交前运行 pnpm guard,检查暂存差异中是否有无关文件、生成产物和意外密钥,然后按仓库的 PR 质量门禁工作流走流程。

使用方式

该技能以排查流程的形式使用:先复现问题并收集上述证据,再按修复顺序逐项调整,最后通过测试与类型检查验证。资料未提供具体安装命令或调用接口。

适用场景

  • 浏览器预览中导出图片得到 0 KB 或空白文件。
  • iframe 截图后保存失败。
  • Electron 应用下载图片时文件缺失或无法打开。
  • File System Access API 在沙箱或权限受限环境下写入失败。

限制

资料仅描述排查与修复方法,未提供该技能的独立安装方式、收费模式或支持的平台范围,这些信息暂未提供。