手机照片快传 apherchin/dsh-photo2dsh-by-lan

dsh-photo2dsh-by-lan

手机拍照 → 局域网 → 这台 PC 的文件夹 → Agent 直接可读。

手机端用系统自带能力（iPad/iPhone「快捷指令」、Android「HTTP Shortcuts」）一键把照片 POST 到 PC；插件负责接收、落盘到你自己指定的目录、弹 Windows 通知。不需要云、不需要飞书/微信、不需要装手机 App。

配置界面就在 DSH 侧栏 插件（Plugins）→ 本包页面里。

亮点

- 手机一键 —— iOS 快捷指令或 Android HTTP Shortcuts 直接 POST 照片，手机侧不用装任何 App。
- 落地目录你说了算 —— 在插件面板里改；照片立刻出现在那个目录。
- Agent 直接可读 —— 落地目录就是普通目录，DSH 的 Agent 可以立刻读取/分析。
- 到达即通知 —— 每张照片弹一条 Windows 通知（可点击跳回）。
- 不依赖云、不用 IM、不装手机 App、不改 app.asar。
- 可选 token 闸门 —— 默认关闭；关闭时以"局域网"为信任边界（见第 6 节）。
- 离线验证台 —— 50 条断言，含我们真机上踩过的每一种故障。

1. 安装

方式 A：按包名（推荐，可迁移）

dsh plugin --profile desktop add dsh-photo2dsh-by-lan

dsh plugin 会自动把本 bundle 记进 profile 的 dsh.profile.bundles，不需要手工编辑 profile 文件。

方式 B：从本地源码装

dsh plugin --profile desktop add file:D:\path\to\dsh-photo2dsh-by-lan

⚠️ 两种方式只选一种。若 profile 里已经有指向本插件绝对路径的 insert 行，再按包名装一次会出现两行同名 entry。

装完之后：给端口放行一次防火墙

这是唯一需要管理员权限的步骤。默认端口 8787：

netsh advfirewall firewall add rule name="DSH Photo2DSH" dir=in action=allow protocol=TCP localport=8787 profile=any

撤销：

netsh advfirewall firewall delete rule name="DSH Photo2DSH"

⚠️ profile=any 不能省。省略 Profile= 字段才是"对所有网络类别生效"；若只写 profile=public 而你的网络被 Windows 判成"专用"，入站包会被静默丢弃，手机端表现为"服务器已停止响应"（超时），极难定位。这是本项目实测踩过的坑。

顺带一提：别指望借用系统已有的放行端口。实测全机唯一"不限程序 + 不限类别"的 TCP 端口被 http.sys 独占（EACCES），抢不过来。

装完重启 DSH（客户端半边需要重新装配）。

2. 在插件面板里配置

侧栏 插件（Plugins） → 本包页面 → 配置卡片：

| 配置项 | 说明 |
| 落地目录 | 照片落在哪里。会在此目录下自动建 <日期>\ 子目录 |
| 端口 | 默认 8787。改完要给新端口重新放行防火墙 |
| 单文件上限（MB） | 默认 64 |
| 收到照片后弹 Windows 通知 | 默认开 |
| 每张照片写一张元数据卡（.json） | 默认开。嫌目录里文件翻倍就关掉——见 §4 |
| 只接受局域网来源 | 默认开。非私网地址的上传一律 403；关掉 token 时它是唯一来源闸门 |
| 要求 token | 默认开，强烈建议保持开启（理由见下） |
| 手机要连的 IP | 默认「自动」：枚举本机网卡、跳过 Hyper-V/VMware/WSL 等虚拟网卡、优先 192.168 网段。选错可手动指定 |
| 手机端要填的地址 | 只读，点「复制」直接拷走 |
| token | 只读 |

为什么落地目录建议填"当前会话工作区内的目录"：DSH 的文件沙箱在 workspace-write 下只允许写工作区。
落在工作区外，宿主仍能写（插件用的是原生 fs），但 Agent 用工具读它可能受限。

3. 手机端配置

iPad / iPhone（快捷指令）—— 四步，第 3 步最容易漏

1. 新建快捷指令，加 「选择照片」（或「拍摄照片」）。
2. 加 「转换图像」 → 「转换为」选 JPEG、质量 80%。
- 不加这步也能用，但实测同一张 8MP 图会从 ~1.5 MB 变成 ~12 MB（快捷指令按无损 PNG 递送）。
3. 加 「获取 URL 内容」：
- URL 填配置卡片里复制的那串（形如 http://192.168.x.x:8787/u/<token>）；
- 点「显示更多」→ 方法 POST → 请求体 文件；
- ⚠️ 把「文件」栏的值改指「转换后的图像」 —— 漏这步就继续发原图，转换动作等于白加；
- 最后加一个 「快速查看」 看返回。
4. 运行。返回是中文短句，一眼能看懂：

✅ 照片已收到

格式：JPEG（1.63 MB）文件：20261003232612-4d2b993e-image.jpg 时间：2026-10-03 23:26:12

已存入 PC 的收件箱文件夹

首次访问局域网时 iPadOS 会弹「允许访问本地网络设备」——必须允许。
这与防火墙无关，是 iOS 独立的一道闸；拒绝后请求会被系统直接掐断。

想让相册里"只传我想传的那几张"：快捷指令 ⓘ → 打开「在分享表单中显示」→ 接收类型勾「图像」，之后在照片 App 里选图 → 分享 → 本快捷指令。

Android（HTTP Shortcuts）

同一个 URL、同样的 POST + 文件体即可。协议两端完全一致，不另设。

4. 数据怎么落

<你配置的目录>\
└─ 2026-10-03\
├─ 20261003232612-4d2b993e-image.jpg ← 本地时间戳-内容哈希前8位-清洗后的原名 └─ 20261003232612-4d2b993e-image.json ← sidecar：原名/备注/时间/字节数/sha256/格式/来源

- 文件名带内容哈希前 8 位，所以肉眼就能核对两张图是否同一张。
- 同秒同名不会互相覆盖：落盘用 link()，目标已存在就自动追加 -1、-2。
（rename 会静默覆盖——实测同一秒发多张 image.jpg 会只剩一张且毫无提示，这条是专门修的。）
- 只认魔术字节，不信任 Content-Type：实测快捷指令送来时头写 image/jpeg、字节却是 PNG。
- 那张 .json 是可关的。它记的是文件名给不出来的东西：哪台设备发的、原始文件名、备注、sha256、嗅探所得格式。
嫌目录里文件翻倍，就在面板里取消勾选「每张照片写一张元数据卡」——之后目录里只剩照片本身。
这些元数据即使在开关打开时也不会影响照片落盘成功（写元数据失败只记日志）。

5. 故障排查

| 现象 | 原因 | 处理 |
| 手机显示"服务器已停止响应"（超时） | 入站包被防火墙静默丢弃 | 按第 1 节加防火墙规则；必须带 profile=any |
| 返回 ❌ 上传失败：地址里缺少正确的 token | URL 少了 /u/<token> 这一段 | 从配置卡片重新复制完整地址 |
| 返回 ❌ 这不是一张能识别的图片 | 发出去的确实不是图片字节 | 检查快捷指令里「文件」栏是否真的选上了图像变量 |
| 返回里写着"仍是 PNG" | 「转换图像」没接到「文件」栏 | 见第 3 节第 3 步 |
| 面板里看不到本包页面 | 那一行 Loader 被关闭了，或 profile 未重启 | 官方契约：客户端半边挂在"说明符恰为包名"的那一行上，关掉那一行卡片就一起消失 |
| 端口启动失败 | 端口被别的程序占用 | 面板里换一个端口，并给新端口放行防火墙 |

日志：$DSH_HOME\photo2dsh-by-lan.log　配置：$DSH_HOME\photo2dsh-by-lan.json

6. 安全边界

默认配置（requireToken: true + lanOnly: true）：

- 只监听局域网（0.0.0.0:<port>），不放公网。
- token 走 URL 路径，128 bit 随机、首次启动自动生成并持久化（这就是"可迁移"——换台机器不用手配）。
- 401 不会回显正确的 token：那等于把它送给任何打错地址的人。
- 设置页（GET /）只对 127.0.0.1 开放：它含 token，不能让局域网随便看。
- /health 不含 token（uploadUrl 里也含 token，所以被一并剥掉）。

不想用 token？可以，但两道闸门要一起上

在面板里把 「要求 token」关掉 即可（地址就变回 http://<IP>:<port>/，快捷指令里更好填）。但另外两道得在：

| 闸门 | 挡什么 | 默认 |
| 只接受局域网来源（lanOnly） | 非私网地址（公网）的上传一律 403 | ✅ 开 |
| 拒跨源 Origin | 网页跳板：你浏览的恶意网页借你的浏览器 POST 过来 | ✅ 永远生效，无开关 |

⚠️ 第二道不能省，也不能用第一道代替。 网页跳板走的是你自己的浏览器，服务端看到的来源是 127.0.0.1 —— 在"局域网/私网"的定义里完全合法。只有 Origin 头能识别它：浏览器跨源请求一定带 Origin，而 iOS 快捷指令这类原生客户端根本不带。

关掉 token 后仍然成立的保护（与 token 无关）：路径清洗（防目录穿越）、只收图片（415）、体积上限（413）、落盘用 link() 防覆盖。
也就是说最坏情况是"局域网里的设备往你的收件箱灌垃圾图片"，不可能写到别的目录、不可能覆盖已有文件、不可能放可执行内容。

仍然建议：只在自有可信网络（家里/办公室）里关。咖啡馆、酒店、合租的 Wi-Fi 别关。

7. 已知限制

- 仅 Windows（通知走 Windows PowerShell 5.1 的 WinRT；package.json 已声明 os: ["win32"]）。
- 通知横幅上的应用名显示为 Windows PowerShell。要显示成自己的名字需要往 HKCU\Software\Classes\AppUserModelId 注册 AUMID。
- 不做：云中转 / 飞书微信通道 / 界面里的照片浏览器 / 自动把消息注入会话 / 自动清理。
- 卸载时不会删除你已收到的照片（那是你的数据）。

8. 开发

离线验证台（50 条，含全部真机故障复现用例）
node test/photo2dsh.test.mjs

架构：

| 文件 | 职责 |
| core.mjs | 纯逻辑（命名/白名单/魔术字节/配置文档解析），无 I/O，可离线测 |
| receiver.mjs | 宽容的原始 TCP 接收（不用 node:http，理由见文件头注释） |
| store.mjs | link() 原子落盘 + sidecar |
| notify.mjs + scripts/toast.ps1 | Windows Toast（PS 5.1；脚本纯 ASCII 以绕开 BOM 坑） |
| index.mjs | 宿主接线：配置分层、receiver 生命周期、/api/photo2dsh-by-lan.config 路由 |
| client.js | 客户端半边：注册进官方槽位 plugins.bundle.config 的配置卡片 |