Skip to content

feat(bsk): add secure, session-scoped file upload and download | 支持安全、会话级的文件上传与下载 - #123

Draft
Ljy-0827 wants to merge 7 commits into
mainfrom
feat/upload-download
Draft

feat(bsk): add secure, session-scoped file upload and download | 支持安全、会话级的文件上传与下载#123
Ljy-0827 wants to merge 7 commits into
mainfrom
feat/upload-download

Conversation

@Ljy-0827

@Ljy-0827 Ljy-0827 commented Aug 21, 2026

Copy link
Copy Markdown
Collaborator

现存问题

BrowserSkill 缺少可靠的原生文件传输能力:

  • 上传会进入系统文件选择流程,无法用于无人值守工作流。
  • 下载保存在 Agent Window 的隔离 Chrome profile 中,调用方无法直接取得文件。
  • Canvas/base64 等替代方案受分辨率、文件类型和跨域策略限制。
  • 文件传输缺少明确的策略边界、目标约束、结果状态和生命周期管理。
  • 浏览器事件可能缺失、乱序或超时,容易造成误认领、盲目重试或无法判断操作是否已经生效。

解决方案

本 PR 新增会话级 uploaddownload 命令,并明确划分策略与机制边界:

  • Agent/harness 决定是否允许传输,以及选择哪个上传文件或下载目标路径。
  • BrowserSkill 不判断文件内容是否敏感,只负责强制执行会话、标签页、网页目标、路径 capability、大小和生命周期约束。

上传

上传文件由 CLI 读取,通过本地 daemon 的私有暂存区传递给扩展。扩展不会获得用户原始绝对路径,只能使用 daemon 为当前会话解析出的受限暂存路径。

扩展只解析一次指定网页目标,并使用同一目标完成事务准备和点击,避免页面变化导致目标或 frame 不一致。

点击前,扩展会建立一次性上传事务并拦截原生文件选择窗口。文件输入既可以通过精确的浏览器 chooser 事件定位,也可以通过绑定到目标所属 document 的独立 DOM probe 定位,因此不再依赖单一事件是否送达。确认唯一文件输入后,通过浏览器能力设置暂存文件。

事务结束后会撤销 chooser interception、DOM 监听和临时对象。若浏览器不支持所需能力,或网页使用无法自动处理的非 input picker,系统会在可确定的阶段立即返回结构化错误,并引导 Agent 降级到 request-help

暂存目录按传输随机隔离,仅保留经过校验的原始 basename。上传进入浏览器事务后,暂存生命周期归当前 session 管理,并保留到会话结束,以支持稍后才读取附件的表单。

下载

下载操作绑定到调用方指定的网页目标,并将浏览器下载意图与 chrome.downloads 候选进行唯一关联。两类事件可以按任意顺序到达;只有标签页、frame、URL 和文件名均匹配的唯一候选才会被认领。

BrowserSkill 不会枚举、认领或取消无关下载。出现多个匹配候选时会安全失败,而不是选择其中一个继续执行。

浏览器将文件下载到 daemon 为本次操作签发的相对目录 capability。daemon 随后验证实际路径、符号链接、文件类型和大小,确认文件没有逃逸传输边界后,再导入私有暂存并交由 CLI 写入调用方指定的目标路径。

下载默认不会覆盖已有文件。启用 --overwrite 时也通过原子替换提交,不会先删除原文件。已认领下载在失败或取消时会进行补偿清理;无法确认清理结果时会明确返回未知状态。

结果状态与取消

文件传输错误包含:

  • effect_state:区分未产生效果、已经提交和结果未知。
  • phase:标识失败发生在准备、触发、归属、提交或清理阶段。
  • cleanup_state:标识补偿清理是否失败。

传输超时后,daemon 会主动向扩展发送取消,并在有界时间内等待事务完成补偿,而不是立即遗弃仍在运行的浏览器操作。

已确认的成功不会被晚到的取消覆盖;结果未知时不会被错误转换成普通失败,从而避免 Agent 对可能已经生效的上传或下载进行盲目重试。

安全与生命周期

所有文件传输都绑定当前 session 和 Agent Window,使用不可猜测的传输标识,并受到文件数量和大小限制。

上传文件名必须是安全的单一路径组件,拒绝绝对路径和路径穿越。暂存目录及文件使用收紧的本地权限,用户原始绝对路径不会传递给扩展或作为传输结果返回。

daemon 只会清理由其签发并完成验证的浏览器文件 capability,不会根据网页返回的任意路径删除本地文件。

会话停止、浏览器断开或 daemon 重启时会清理其管理的遗留暂存,避免文件长期保留。

验证

已在 Chrome 151 完成端到端验证;其他 Chromium 版本通过能力检测处理,不满足所需浏览器能力时返回结构化错误并引导降级。其他 Chromium 版本通过能力检测处理;缺少所需浏览器能力时,会在点击前或可确定阶段返回结构化错误并引导降级。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature Request: 支持文件上传和下载命令 (DOM.setFileInputFiles / Page.setDownloadBehavior)

1 participant