zetaluolang-cyber/deepseek-harness-phone-remote

DeepSeek Harness Remote Workspace

Secure Remote Workspace & Filesystem Bridge for DeepSeek Harness.

你的 DeepSeek Harness,随处可用——原生 Web UI,经安全网络访问,配设备认证 RPC 与能力受限的文件系统。

本项目不替换 Harness 界面,而是把 Harness 本身变成可远程使用的工作环境:手机通过 Tailscale(或局域网)打开真正的 DeepSeek Harness Web UI,插件桥接浏览器无法远程完成的两种事——在任意文件夹开始/恢复 Agent 会话,以及读写、上传、下载 PC 文件。

[!WARNING]
设备配对只认证本插件的 /remfs 与受保护的 /pocket 操作,不会给原生 Harness /api 增加登录认证。请把 tailnet/局域网可达性视为 Harness 控制面权限;非必要不要开启 walk-on-LAN,并用 Tailscale ACL 只放行可信设备。

为什么

- Harness 只绑定 127.0.0.1——这是合理的安全默认。本项目保留它:GUI 绝不暴露给局域网/公网。
- 手机浏览器够不到 loopback,且 GUI 的目录选择器是仅本机的特权方法——本插件为此补齐安全通路(Tailscale + 局域网转发器)与文件/工作区桥。
- 普通会话随页面消失——本插件是持久化 loader 条目,每次打开页面自动加载,无需重新运行。

架构

flowchart LR
P[手机 / 远程浏览器] -->|Tailscale HTTPS| S[tailscale serve]
P -->|Tailscale IP| T[TCP 转发器]
P -->|同一 Wi-Fi:LAN IP| L[局域网转发器]
S --> H[DeepSeek Harness Web127.0.0.1:3080]
T --> H
L --> H
H --> R[/remfs RPC 通道trusted-host 围栏/]
R --> A[设备认证配对 + 每设备凭据]
A --> F[文件能力层白名单 + 保护路径 + realpath]
F --> W[(已批准工作区)]

三层独立信任:

1. 传输层——谁能到达通道:Tailscale 成员或你的局域网(转发器只绑 Tailscale IP 和 LAN IP,从不绑 0.0.0.0)。
2. 应用层——谁能使用:设备配对 + 每设备凭据。
3. 能力层——能碰什么:白名单 + 保护路径。

trusted-host 和 tailnet 是传输层信任,不是认证。认证是配对,文件边界是能力层。

功能

- 一键引导部署——install.ps1 校验/升级 Node(^22.19 || >=24)、自动装 Node.js/Tailscale、执行真正的 Tailscale 设备登录、把 DSH 独立安装到 ~/.dsh/runtime(不再依赖偶然存在的 npx 缓存)、创建 web profile、部署插件和启动器、注册自启，最后真实启动并验活 Harness 与插件路由，成功后才打印 DONE。
- Walk-on-LAN(默认关闭,可选开启)——在 %USERPROFILE%\.dsh\lan-on 创建标记文件(或设环境变量 DSH_REMFS_LAN=1)后,才会信任局域网 IP 并启动局域网转发器;同一 Wi-Fi 下手机可绕过 Tailscale 直连 http://192.168.x.x:3080,/remfs 依旧设备认证。开启会扩大网络暴露面,所以必须显式选择。
- 持久化插件——loader 条目;host 通道随启动注册,客户端模块随页面加载。
- PC 顶置桌面伴侣——scripts/orb-widget.ps1(双击 scripts/start-orb-widget.cmd,部署到 ~/.dsh/launcher):零依赖 WinForms 小球,始终置顶显示最高优先级的 Agent 状态,支持跨屏拖动并持久化位置。单击展开当前任务、摘要、刷新/日志和“打开 Harness”操作。网页不再重复显示悬浮球,任务板改为普通页头按钮。install.ps1 同时注册登录自启(原子单实例;删除 Startup 里的 dsh-orb-widget.cmd 即可关闭)。
- 手机推送通知(关页面也能收到)——可选的 Web Push 通道:手机注册同源 Service Worker(/remfs-sw.js),配对后订阅(使用 host 的 VAPID 公钥)。宿主在 NEEDS_USER/FAILED(及可选 DONE)状态变化时推送,标签页关闭也能收到。RFC 8291 加密为手写实现(零依赖),已与官方 RFC 测试向量逐字节对拍。需要 HTTPS(Tailscale HTTPS 或 localhost)。详见 docs/presence-push.md。
- 设备配对与管理——一次性配对码(10 分钟有效、仅一次);列出/吊销/吊销全部设备;凭据只存哈希。
- 手机工作台——新建会话/文件浏览双标签、面包屑、预览/编辑/上传/下载、工作区徽标、任务板按钮、侧栏自动收起、中英双语。
- host 层保护路径,分两级:
- 硬拦截——无论白名单如何、也无论你注册了什么工作区,都不可达:系统目录(Windows/System32/SysWOW64)与凭据/密钥文件(.credentials.yaml/.ssh/.aws/.gnupg/.env/id_rsa/.pem 等)。
- 软拦截——默认阻断,但你在本机把工作区精确注册到该目录时可达:AppData、Program Files、ProgramData 与隐私数据目录(微信/WPS)。它们是隐私边界而非凭据边界;注册这类目录是只有本机用户才能做的决定,且不会因此解锁其下的硬拦截文件。

安全模型

- Tailscale ≠ 认证:它只证明"在哪个网络",不证明"你是谁"。配对才是应用边界。
- trusted-host ≠ 认证:它只是浏览器信任围栏(Host 头 + 跨站检查)。配对才是边界。
- Harness 进程始终只绑 loopback:把 Web 服务暴露到网络接口的唯一途径是显式转发器(Tailscale IP,以及开启 walk-on-LAN 时的局域网 IP)——只绑具体地址,绝不绑 0.0.0.0。
- 配对只保护 /remfs,不保护原生 Harness /api:GUI 自身 API 没有用户登录;请收紧网络边界(tailnet / 局域网)并定期检查可达设备。
- 文件白名单是主要文件权限边界:远程客户端只能收窄*白名单;扩大(C:\、新盘符)必须在本机编辑 .remfs-roots.json。
- 路径逃逸双重防御:带 ../UNC 的原始路径直接拒绝;规范后的 realpath 必须落在白名单内(符号链接/junction 逃逸失败)。
- 远端写入有编码保护:上传/编辑非 UTF-8 文件(UTF-16 BOM、GBK/ANSI 字节)会被拒绝而不是写坏;编辑写回时保留原文件的 UTF-8 BOM 与换行风格(CRLF/LF)。
- presence 只读围栏是运维开关:默认任务板在浏览器信任围栏内免认证可用;在 ~/.dsh/remfs-options.json 设 pocketStrict: true 后,浏览器的所有 /pocket 调用都必须携带有效设备凭据。桌面伴侣使用独立的 256 位本机只读 presence 令牌,令牌文件属于远程文件硬拦截项。
- 推送订阅只属于已配对设备:注册订阅需要有效设备凭据;被吊销设备的订阅一分钟后清理;任务标题/摘要只推送给已配对设备。VAPID 密钥存于 ~/.dsh/remfs-push.json(绝不进仓库)。
- Tailscale ACL 建议硬化为仅手机可访问 443/3080——见 docs/tailscale-acls.md。
- 完整威胁模型见 SECURITY.md;升级前备份与验证清单见 docs/upgrade.md。

定位

本项目是 DeepSeek Harness 的安全远程工作区与文件系统桥:保留原生 Web UI,增加认证远程访问与能力受限的文件/工作区层。它不是 UI 替代品、皮肤或独立前端——生态中其他社区项目走那些方向,彼此互补而非竞争。

安装

高级用户(npm):

dsh plugin --profile web add @zetaluolang/remfs-persistent
在 %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml 追加:
- insert:
- id: remfs-persistent
name: '@zetaluolang/remfs-persistent'
inject: [connection, fs, sandboxPolicy, workspaceRegistry]
重启 dsh web

普通 Windows 用户(一键): 下载并解压仓库后，双击 一键部署.cmd。
安装过程需要联网；脚本会处理 Node、Tailscale、项目自管的 DSH runtime、
profile/插件、启动器、看门狗和首次启动。唯一有意保留的人工步骤是
Tailscale 登录/UAC。只有本机 Harness 与插件路由通过真实验活后才会打印
DONE，因此此时打印的手机地址已经可用。Tailscale HTTPS 证书可能仍需在
管理后台首次启用。

悬浮球是安装后的日常状态入口，不承担安装事务：它是没有黑色底卡的真透明
球体，鼠标悬停会显示当前状态和任务标题；拖动由 Windows 合成器原生接管，
避免闪烁和追手感。不同状态会触发环绕火花、拖尾、爆发粒子和旋转能量环；
单击仍可打开任务快捷面板。它随登录启动，部署和修复仍由有明确成功/失败
输出的 install.ps1 完成。

自愈看门狗

install.ps1 会注册一个计划任务(dsh_harness_watchdog,每 5 分钟、当前用户、隐藏窗口),运行 %USERPROFILE%\.dsh\launcher\watchdog.ps1。每次运行:

1. 校验 我们的 dsh 进程确实占有 127.0.0.1:3080——占有进程的命令行必须包含部署的 dsh bin 路径(看门狗复用启动器的 Get-OwnedHarnessPid 归属校验;绝不信任裸端口,绝不把无关的 localhost 服务当成 harness)。
2. 若我们的 harness 不在运行且端口空闲,则以无头方式(DSH_HEADLESS=1,不开浏览器、不弹窗)调用 restart_harness_once.ps1 拉起,并把每一步追加到 %USERPROFILE%\.dsh\launcher\watchdog.log。
3. 若端口被外来进程占用,则记录冲突并让位——绝不误杀、绝不覆盖重启不属于本项目的进程。

重跑 install.ps1(或 一键部署.cmd)即可更新任务定义;健康时看门狗每 5 分钟写一行日志。

手机首次使用(配对)

1. 打开手机地址(https://..ts.net,或同一 Wi-Fi 的 LAN 地址)。
2. 工作台显示配对界面。
3. 在电脑上读取配对码:%USERPROFILE%\.dsh\remfs-pairing.txt(或 harness 日志)。
4. 在手机上输入配对码 + 设备名 → 配对完成。凭据存手机,电脑只存哈希。
5. 随时可在工作台 ⋯ → 设备 里吊销设备。

威胁模型

防护:未认证 RPC、远程扩大白名单、路径逃逸、凭据落盘泄露、GUI 意外暴露到局域网/公网。

暂不防护:Harness GUI 的 /api 本身没有用户登录(配对保护 /remfs,不保护 GUI——请保持网络边界收紧)、宿主机被攻破、Tailscale 账号被攻破。详见 SECURITY.md。

常见问题

| 现象 | 处理 |
|---|---|
| 手机一直停在配对界面 | 读取 %USERPROFILE%\.dsh\remfs-pairing.txt;配对码 10 分钟过期——重启 harness 生成新的 |
| 设备被吊销/重新配对失败 | 配对码一次性;重启 harness 获取新码 |
| 手机 403 | 用打印的 HTTPS/Tailscale/LAN 地址;GUI 需把这些主机加入信任(一键部署自动完成) |
| LAN 地址不通 | 手机需在同一 Wi-Fi;重跑启动脚本让 LAN IP 重新检测 |
| npm.ps1 被执行策略拦截 | 用 npm.cmd,或 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned |
| 发布后 npm view 404 | CDN 缓存——等一分钟或用 Cache-Control: no-cache |
| dsh plugin add 后插件没出现 | 必须补 loader 行并重启 dsh web |
| 电脑睡眠 | 部署已处理 keep_awake + 电源计划,见 keep_awake.ps1 |
| harness 反复挂掉/手机连不上 | 查看 %USERPROFILE%\.dsh\launcher\watchdog.log;重跑 install.ps1(重新)注册看门狗任务 |
| 顶置球显示 ?/“Disconnected” | harness 或转发器挂了——查看门狗日志与 127.0.0.1:3080 |
| 推送开关置灰(“需 HTTPS”) | 用 Tailscale HTTPS 或 http://localhost:3080 打开 Harness;纯局域网 HTTP 无法注册 Service Worker——见 docs/presence-push.md |
| 关页面后收不到推送 | 见 docs/presence-push.md → 常见问题 |

实测设备

- OPPO Find X8 Ultra(真机)。
- 模拟矩阵:iPhone 16 Pro/SE、Pixel 8、Galaxy S24、Redmi Note、iPad Air、iPhone 横屏——侧栏收起、任务板按钮、面板宽度、无溢出均通过。见 docs/device-tests/。

Roadmap

- [x] Tailscale HTTPS/IP + walk-on-LAN
- [x] 持久化插件(免重新运行)
- [x] 设备配对 + 凭据认证 + 吊销
- [x] 能力受限白名单 + 保护路径 + 路径逃逸测试
- [x] 双语界面、安全测试、CI
- [x] 启动隔离损坏 demo 会话 + 自愈看门狗
- [x] 会话体积提示 + 手机端"建议归档"
- [x] demo-presence 行为测试(幂等 add、固定 cwd、只清理 demo)
- [x] 上传/编辑 UTF-8 编码保护 + BOM/换行保留
- [x] /pocket 严格模式(可选,~/.dsh/remfs-options.json)
- [x] Tailscale ACL 加固指南
- [x] 桌面快捷方式自动化(install.ps1)
- [x] PC 顶置悬浮球(scripts/orb-widget.ps1,零依赖 WinForms)
- [x] 手机 Web Push 通知(关页面也能收到,RFC 8291,按设备可选)
- [ ] 更多分辨率验证
- [ ] 上游贡献

License

MIT