前言¶

在 DSH 里做网页上传、微信发文件、或让桌面软件走「打开」流程时，智能体往往已经能点按钮、能打字，却进不了系统自带的文件选择器。程序化触发 <input>.click() 也不会弹出那个 Win32 对话框。dsh-file-handover（递文件）针对的就是这一段：在调用方先点开上传/打开之后，把绝对路径填进原生对话框、读回校验、再点确认，且每一步都留下可核对的回执。

这是什么¶

• 仓库：7gzgn/dsh-file-handover
• 维护者：7gzgn
• 分类：工作流（社区目录 SkillHub 插件页）
• 当前版本（package.json）：0.2.1，MIT 许可证
• 定位：Hand a local file to any program’s file picker —— 目标路径必须显式给出，不猜对话框、不自动替你点「上传」。

宿主侧 Node 负责参数校验与起子进程；真正操作 GUI 的是包内 lib/handover.ps1（UI Automation + EnumWindows）。仅支持 Windows，且只认窗口类 #32770 的系统原生文件对话框。

核心功能：五步，每步可回读¶

失败时会把见过的候选窗口和每次读回的实际值一并返回，便于排错。可选 dryRun 只探测结构、不填不点；可用 expectTitle 显式按标题过滤（默认不按标题过滤）。

多选（v0.2.0 起）：paths 数组最多 12 个，按 "a" "b" "c" 格式填入并逐个回读，少一个即失败。

安装与启用¶

市场收录后，在 DSH 里搜索 dsh-file-handover 安装。手动安装（摘自 README）：

New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-file-handover" -Target "D:\dsh\projects\dsh-file-handover"
# profile 的 package.json：dependencies 加 "dsh-file-handover": "link:D:/dsh/projects/dsh-file-handover"
# 并把 "dsh-file-handover" 加进 dsh.profile.bundles（漏了不加载）→ 重启 DSH

安装前请自行查看仓库源码与 MIT 许可证。插件以当前 DSH 进程权限运行，只会操作你指定的绝对路径，并在已选中的对话框内点确认按钮。

package.json 中声明与 DSH 0.2.0-rc.2、0.2.1-rc.2 兼容；需要 Node >=18，peer 依赖 @deepseek-ai/cordis 等。

典型用法¶

DSH 工具¶

在智能体侧调用工具（对话框需由你先点开）：

handover_file  path=<绝对路径>
handover_file  paths=[<绝对路径>, <绝对路径>, ...]
handover_file  path=... [timeoutSec] [dryRun] [expectTitle] [maxAttempts] [click]

网页上传常见配合：

1. 用浏览器工具真实点击页面的「上传/选择文件」；
2. 调用 handover_file（单文件 path，多文件 paths）；
3. 用浏览器工具回读页面，确认文件名或大小。

命令行¶

dsh-file-handover handover --path "D:\videos\a.mp4"
dsh-file-handover probe    --path "D:\videos\a.mp4"
dsh-file-handover handover --path "D:\a.mp4" --expect-title "Open" --no-click

退出码：0 已交付 / 1 未完成 / 2 用法错误。

适用场景与注意¶

适合：任何「先弹出系统打开/保存框、再选本地文件」的流程——网页上传、即时通讯发文件、Photoshop 打开等，且你能先触发对话框。

不适合：自绘文件选择器、非 Windows 环境；插件不负责第一次点开对话框的动作。

限制（README 已知项）：每次调用会起 PowerShell 子进程（数百毫秒到数秒）；只认 #32770 原生框；handover.ps1 刻意全 ASCII，避免无 BOM UTF-8 在 Windows PowerShell 下按 GBK 解析导致按标题匹配静默失效。

本地自测（不碰真实 GUI）：

node test/smoke.mjs

结尾¶

dsh-file-handover 补的是 GUI 自动化里「选文件」这一环：路径显式、填入选剪贴板、读回校验、失败带现场。需要细节与更新请以仓库为准。

• 社区目录：https://www.skillhub.cn/plugins/7gzgn/dsh-file-handover
• GitHub：https://github.com/7gzgn/dsh-file-handover