dsh-localsend

中文 | English

局域网文件/文件夹传输 + 浏览器下载链接分享：让 DeepSeek Harness 通过对话，把文件（或自动打包成 zip 的文件夹）发送到同一局域网内运行 LocalSend 的机器，或生成浏览器下载链接（接收方无需安装任何软件）。

零配置、无凭据、无第三方运行时依赖、无任何硬编码路径 —— 自动探测本机网卡子网、自动取主机名作为发送方别名，装好即用。包含 host 工具（agent 调用）与浏览器设置卡片（界面配置）。

当前版本：0.5.0。兼容 DeepSeek Harness 0.1.x 与 0.2.0-rc.1（peer 范围 >=0.1.0-rc.6 <1.0.0）；Node.js ≥ 22.19；支持 Windows / macOS / Linux。

原理

LocalSend 模式（localsend_send_files）

LocalSend 没有官方 CLI，但每台 LocalSend 接收端都是一个标准 HTTP(S) 服务（默认 TCP 53317，自签名证书），遵循公开协议 LocalSend Protocol v2。本插件实现发送端：

1. 发现目标：在活动子网内用 GET /api/localsend/v2/info 探测（只读），按别名或 IP 匹配；
2. 协商：POST /api/localsend/v2/prepare-upload 提交元信息（文件名/大小/类型/sha256）—— 接收端弹窗让用户接受；
3. 上传：POST /api/localsend/v2/upload 发送原始字节，接收端按 sha256 校验。

目录无需先手动打包：插件内置零依赖 zip 写入器，自动把文件夹打成 <文件夹名>.zip 再发送，发送结束即清理临时包。

分享模式（localsend_share）

接收方无需安装任何软件。插件在本机启动临时 HTTP 服务器，生成一次性下载链接：

1. 目录自动打包成 zip；小文件（≤64 MB）计算 sha256 校验；
2. 生成带随机 token 的 URL —— 接收方用任意浏览器打开即可下载；
3. 所有文件下载完成或链接到期后，服务器自动关闭。

支持可选密码保护（HTTP Basic Auth）和可配置端口/有效期。

SMB 推送模式（localsend_smb_push）

接收方无需装任何软件时，把文件/文件夹经 SMB 文件共享自动推送到目标机器的指定目录：target（IP/主机名）+ share（共享名）+ destDir（共享下子目录，可空 = 共享根）+ files；username/password 可选（匿名 = 来宾登录）。目录自动打包成 zip 再复制。前提：接收方预先开一个共享文件夹并给发送方写权限。这是「无软件 + 指定 IP + 指定落盘目录 + 全自动」诉求的唯一可行通道（LocalSend 通道强制接收方装 App，浏览器链接通道无法指定落盘目录）。

目标机档案（推荐用法）：在设置卡片里为每台目标机建一条档案（档案名 / 目标 IP / 共享名 / 共享下子目录 / 账户 / 密码），之后调用只需 profile="书房台式机" + files —— 其余参数由档案提供，任何显式参数按字段覆盖档案。于是「把本机目录推到指定机器桌面」从「每次重填 5 个参数」变成「配一次 + 一条命令」；落到桌面即 share="C$" + destDir="Users\<用户名>\Desktop"（C$ 是 Windows 默认就存在的管理共享）。

边界说明：档案只保存「通道怎么走」，不会凭空造出通道。接收方仍需一次性开好一条访问通道——管理共享 C$ 默认就在（若目标机账户是微软账户且非内置 Administrator，需改一次注册表 LocalAccountTokenFilterPolicy=1），或自建共享并给发送方写权限。此后每次推送接收方零操作。

功能

• 五件工具：
  • localsend_list_devices — 扫描局域网，列出 LocalSend 设备（ip / 别名 / 协议版本 / 设备类型）；可选 subnet（CIDR）限定网段；
  • localsend_send_files — 把文件/文件夹发给指定目标（别名自动解析或 IP）；目录自动打包；阻塞等待接收端接受后上传，返回逐文件结果；
  • localsend_share — 生成临时 LAN HTTP 下载链接，接收方用浏览器打开即可下载，无需安装任何软件；支持密码保护；下载完自动关服务器；输出为结构化对象（含 url / 每文件 size / 总大小 / 有效期 / 是否密码 / 日志）；
  • localsend_send_plugin — 把一个 DSH 插件目录打包成自包含分发 zip（排除 node_modules/.git，内含 dsh-plugin.manifest.json 清单 + INSTALL.md 安装卡），经临时 HTTP 链接分享；接收方只要浏览器就能拿到，无需安装 LocalSend 或任何软件，解压后按 INSTALL.md 一条命令装入。plugin 参数支持绝对目录路径或已安装插件名（只读地在 ~/.dsh/profiles/*/node_modules 下解析，分发 dsh-localsend 自身只需 plugin="dsh-localsend"）；
  • localsend_smb_push — 见上方「SMB 推送模式」。
• 文件与文件夹混发：同一列表里可同时给文件和目录，目录各自打成 zip 发送。
• GUI 配置卡片：「设置 → 插件配置」中的「LocalSend 局域网传输」卡片，可编辑别名/端口/各类超时/单文件上限/分享端口/有效期/密码，并可增删目标机档案（含凭据），保存即生效（新会话的工具调用生效）。
• 健壮性：别名重名/模糊匹配有提示；错误码（403 拒绝、409 繁忙、429 限流、422 校验失败等）映射为可读文案；失败自动取消会话；跳过符号链接与空目录；单文件/单包上限默认 1 GiB（可配置）。
• 安全默认：仅局域网；扫描只读；发送方别名默认主机名；接收端人工「接受」即授权闸门；自签 HTTPS + sha256 端到端校验；分享链接为一次性（随机 token）。
• 开箱即用/可分发：无构建步骤（index.js/client.js 即产物）、无本机路径残留，支持 dsh plugin 安装、npm pack 或手动 link。

安装

推荐：DSH 管理安装（已发布 GitHub）

dsh plugin --profile web add git+https://github.com/huangfuren/dsh-localsend.git#v0.5.0

#v0.5.0 固定到该发布版本；去掉后缀则跟随 main 分支最新提交。安装后重启 DSH：新会话出现五个工具，GUI 刷新后「设置 → 插件配置」出现卡片。

本地/离线安装

1. 把 dsh-localsend 目录放到你的插件目录（如 dsh-plugin\）；
2. 在 profile 的 package.json 的 dependencies 加 "dsh-localsend": "file:<路径>"（或 link:<绝对路径>），并在 dsh.profile.bundles 加入 dsh-localsend；
3. 或对目录执行 npm pack，在 profile 目录 npm/pnpm install <dsh-localsend-0.5.0.tgz>（需联网解析 peer）；
4. 重启 DSH。

配置（GUI 卡片 / settings 命名空间 localsend）

键	默认	说明
alias	自动（主机名）	接收端看到的发送方别名
port	53317	目标 LocalSend 端口
scanTimeoutMs	1500	单 IP 探测超时（ms）
acceptTimeoutMs	240000	等待接收端接受（ms）
uploadTimeoutMs	120000	单文件上传超时（ms）
maxFileBytes	1073741824 (1 GiB)	单文件/单 zip 包大小上限（bytes）
sharePort	0	分享服务监听端口（0 = 随机）
shareExpiresIn	3600	分享链接有效期（秒），0 = 不过期
sharePassword	""	分享下载密码（空 = 无密码）
smbProfiles	[]	目标机档案数组，每项 {name, host, share, destDir, username, password}；配一次后 localsend_smb_push 只需 profile="名"（凭据明文存储，见「安全约定」）
dshProfileDir	~/.dsh	按名解析已安装插件时的 DSH 主目录（只读）

全部可留默认；留空即用内置默认值。

使用示例

LocalSend 模式

把 D:\资料\报告 文件夹打包发给 黄夫人 把 C:\tmp\a.pdf 和 D:\photos 发给 192.168.1.50

工具会自动：解析目标（别名精确/模糊匹配或 IP）→（目录则打 zip）→ 在接收端发起接受确认 → 上传 → 反馈逐文件结果。若接收端未开自动接收，需有人在其 LocalSend 上点「接受」。

分享模式

把 D:\资料\报告.pdf 分享给同事 生成一个下载链接，密码是 1234

工具会自动生成临时 HTTP 下载链接，接收方用浏览器打开即可下载，无需安装任何软件。

SMB 推送

把 D:\打包\bundle 推到 10.0.0.30 的「共享文件夹」下的 dsh-sync 目录 把 D:\打包\bundle 推到「书房台式机」的桌面

工具会打包目录并自动复制到目标共享的指定目录，无需接收方点「接受」，前提是接收方已开共享并给发送方写权限。第二条走的是目标机档案：先在设置卡片里把「书房台式机」配成 C$ + Users\<用户名>\Desktop，之后每次只说一句话即可。

安全约定

• 仅限同一局域网；扫描不越出本机活动子网、不跨网关。
• 探测只读（info）；发送必须是「用户明确点名的目标 + 用户明确点名的文件/文件夹」。
• 接收端默认需人工点「接受」（或目标机已开自动接收）；协议无共享密钥，弹窗即授权闸门。
• 发送端只持有文件内容，不读取、不存储任何凭据；接收端返回一律视为不可信数据。
• 例外——SMB 目标机档案：若你在设置卡片里配置了档案，档案中的凭据（含密码）以明文保存在本机 DSH settings 文件里，并随该文件被同步/备份而流转。这是为「自己的多台机器之间推送」设计的取舍，请勿在共享账号或多人共用的机器上启用。
• 局域网传输为自签 HTTPS；sha256 校验失败（HTTP 422）会明确报错。
• 分享链接为一次性随机 token；下载完成后自动关闭服务器；可选密码保护。

开发与测试

npm run check   # node --check 全部入口
npm test        # 单测 + 本地 mock 接收端端到端（zip 打包、上传、422 校验失败、cancel），不联网
npm run verify

测试覆盖：zip 写入/解析回读、CRC-32、目录打包与清理、mock 端到端「目录 → 自动 zip → 上传」、sha256 不匹配 422、取消会话、SMB 的 UNC 拼接与 net use/robocopy 参数（含「目标只出现一次」的回归用例）、目标机档案解析（findProfile 查找/报错、mergeProfile 的「显式参数覆盖档案」）。

兼容性说明

• peer 范围取宽松区间（>=0.1.0-rc.6 <1.0.0），dsh 0.1.x 线与 0.2.0-rc.1 均可解析；
• 已对照 host 的 ctx.tools/systemPrompt/settings 与 client 的 keyed slot 与 dsh.client.inject 核对；
• 超出范围未认证。

发布

• 仓库：https://github.com/huangfuren/dsh-localsend
• 发版流程建议：通过全部测试（npm run verify）→ npm pack → 打 GitHub tag 与 Release（附 tarball）。

License

MIT