Agent Skills
返回列表
本地文件句柄

本地文件句柄

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @user_f1b049da/rin20265373。

技能介绍

日常Web应用中,让用户处理本地文件时,要么只能选文件后一次性下载修改,没法写回原路径;要么绕过授权静默读写磁盘,既不安全也不符合浏览器沙箱规则。本技能解决的就是这种「既想反复操作同一本地文件,又必须让用户明确授权」的问题。

核心能力与工作流程

技能基于浏览器的File System Access API,通过fileOpen和fileSave接口实现本地文件句柄的读写。核心规则包括:必须由用户点击按钮的手势触发授权,禁止静默读写磁盘;文本默认采用UTF-8编码,大文件读取前会先提示体积;浏览器不支持File System Access API时,自动回退到传统文件选择或下载方式。
具体步骤分为四步:先引入browser-fs-access库;然后制作「打开本地文件」和「保存/另存为」两个按钮,打开后展示文件名;接着在不支持该API的环境中验证,确保仍能通过回退方式选出文件或下载;最后区分纯下载场景——无文件句柄的一次性下载应使用file-saver,而非本技能。

关键约束与适用边界

技能明确不能声称绕过浏览器沙箱访问任意路径,若用户未授权则直接失败并给出友好提示;禁止后台轮询扫描用户磁盘,也不允许要求用户关闭安全设置来实现「万能读写」。实现中标注为小四原创的要点,是与「一键下载」类工具的核心区别——本技能走用户授权的文件句柄,支持反复读同一文件或在浏览器支持时写回原路径。

使用场景

  • 前端工程师开发配置工具时,需要让用户选择本地 JSON 配置文件,修改后点击保存按钮将内容写回原路径。
  • CRM 系统用户需要打开本地的草稿备份文件进行编辑,完成后使用另存为功能将修改后的文档覆盖原文件。
  • 网页应用支持用户导入本地文本进行解析,当浏览器不支持句柄 API 时,自动降级为传统的文件选择对话框。
  • 开发者构建离线编辑器,要求用户必须通过点击按钮触发授权,才能读取本地大文本文件并提示文件体积。

适合人员

  • 需要在 Web 端提供本地文件编辑与覆盖保存功能的前端开发者,希望符合浏览器安全规范并兼容老旧浏览器。
  • 经常在浏览器中处理客户草稿和本地备份的 CRM 系统用户,需要能够直接打开本地文件并修改后保存回去。
  • 开发依赖本地配置文件且要求严格用户授权的离线 Web 工具工程师,希望避免静默读写磁盘带来的安全风险。
  • 需要在不同浏览器环境中测试文件上传下载兼容性的测试工程师,关注 API 不支持时的回退方案是否正常。