手机远程工作区 zetaluolang-cyber/deepseek-harness-phone-remote

DeepSeek Harness Phone Remote

别盯着智能体看。盯住它的脉搏。

一个安全、免安装 App 的 DeepSeek Harness 远程工作区。用手机通过 Tailscale（或局域网）访问真正的 Harness Web UI，管理文件和 工作区，还能借助 Agent Presence 随时瞄一眼智能体的状态——悬浮 Orb、任务板和通知。

- 🎈 Agent Presence —— 悬浮品牌 Orb（可拖到任意位置）：Needs You / Failed / Possibly Stalled / Running / Done / Idle / Disconnected，配一个任务板，以及针对需要你处理的事项的浏览器通知。
- 📁 文件和 工作区 —— 在任意已批准的文件夹里启动/恢复智能体；读写、上传、下载文件。
- ↔ 交接 —— 离开工位后，用手机继续同一个会话（sessions.open——绝不是新建一个替代会话）。
- 🔐 设备配对 —— 一次性验证码，每台设备独立凭据，可吊销。

本项目不替代 Harness UI。它把 Harness 本身变成一个远程工作环境：手机通过 Tailscale（或你的局域网）打开真正的 DeepSeek Harness Web UI，再由一个常驻插件补上浏览器在远程场景下够不着的缺口——经过认证的文件/工作区访问，以及 Agent Presence（Orb / 任务板 / 通知）。

[!WARNING]
设备配对只认证本插件的 /remfs 和受保护的 /pocket 操作。它不会给原生 Harness /api 加上登录认证。请把 tailnet/局域网的连通性视为对 Harness 控制面的访问权限；除非确有需要，否则关闭 walk-on-LAN，并把 Tailscale ACL 限制在可信设备上。

为什么

- Harness 绑定 127.0.0.1——这是刻意为之、合理的默认值。Harness 进程本身始终只监听回环地址；只有那些按需开启的转发器（Tailscale IP，以及启用时的局域网 IP）才会暴露选定的接口。
- 手机浏览器依然够不着回环地址，而 GUI 的目录选择器是仅限回环的特权方法——所以本插件补上一条安全通路（Tailscale + 局域网转发器）和一个文件系统/工作区桥接，正好填这两个缺口。
- 会话通常随页面一起消亡——本插件是一个常驻加载器入口，所以工作台每次打开页面都会自动加载，不需要每个会话手动「run」。

架构

flowchart LR
P[Phone / remote browser] -->|Tailscale HTTPS| S[tailscale serve]
P -->|Tailscale IP| T[TCP forwarder]
P -->|same Wi-Fi: LAN IP| L[LAN forwarder]
S --> H[DeepSeek Harness Web127.0.0.1:3080]
T --> H
L --> H
H --> R[/remfs RPC channeltrusted-host fence/]
R --> A[Device authenticationpairing + per-device credential]
A --> F[Filesystem capability layerallowlist + protected paths + realpath]
F --> W[(Approved workspace)]

三个互相独立的层：

1. 传输 —— 谁能够到这条通道：Tailscale 成员身份，或者你的局域网（forwarder 只绑定 Tailscale IP 和 LAN IP，绝不绑定 0.0.0.0）。
2. 应用 —— 谁可以使用它：设备配对 + 每设备凭据。
3. 能力 —— 它们可以触碰什么：允许列表 + 受保护路径。

trusted-host 和 tailnet 属于传输信任。它们不是身份认证。配对和文件系统能力层才是。

功能

- 一键引导部署 —— install.ps1 校验/升级 Node（^22.19 || >=24），安装缺失的 Node.js / Tailscale（winget），执行真正的一次性 Tailscale 设备登录，在 ~/.dsh/runtime 下安装私有 DSH 运行时（绝不使用临时的 npx 缓存），创建 web 配置档，安装插件，写入启动器，注册自动启动，然后启动并对 Harness 及插件路由做健康检查，最后打印 DONE。
- Walk-on-LAN（可选开启） —— 默认关闭。创建 %USERPROFILE%\.dsh\lan-on（或设置 DSH_REMFS_LAN=1）即可信任 LAN IP 并启动 LAN forwarder；在同一 Wi-Fi 下，手机就能跳过 Tailscale（http://192.168.x.x:3080）。/remfs 仍保持设备认证。开启它会扩大网络暴露面，所以这是一个需要明确做出的选择。
- 持久插件 —— loader 条目；host 通道在启动时注册，client 模块在每次页面加载时载入。刷新后无需重新运行。
- PC 置顶 Orb —— scripts/orb-widget.ps1（双击 scripts/start-orb-widget.cmd，部署到 ~/.dsh/launcher）：一个零依赖、逐像素 alpha 的 WinForms orb，悬浮在所有窗口之上，没有矩形底板。悬停可查看当前状态和任务标题；拖动使用原生合成器移动，动作平滑无闪烁（位置跨显示器保持）。状态感知的轨道火花、彗星拖尾、爆发和能量环为 orb 增添动效。点击可打开配套面板，显示当前任务、摘要、刷新/日志操作，以及一个 Open Harness 按钮。浏览器端没有重复的悬浮球；它的 Task Board 是普通的头部操作。轮询相同的任务 DTO（/remfs-presence.json）。
install.ps1 还会注册登录时自动启动（Startup 文件夹条目；单实例，所以自动启动和 .cmd 不会叠加 —— 从 Startup 文件夹移除 dsh-orb-widget.cmd 即可禁用）。
- 手机推送通知（页面关闭时） —— 可选开启的 Web Push 路径：手机注册同源 service worker（/remfs-sw.js），配对后使用 host 的 VAPID 密钥订阅。即使标签页关闭，host 也会推送 NEEDS_USER/FAILED（以及启用时的 DONE）状态转换。RFC 8291 加密从零实现（零依赖），并对照官方 RFC 测试向量验证。需要 HTTPS（Tailscale HTTPS 或 localhost）。参见 docs/presence-push.md。
- 设备配对与管理 —— 一次性配对码（10 分钟 TTL，单次使用）；列出 / 撤销 / 全部撤销设备；凭据仅以哈希形式存储。
- 移动优先工作台 — 新增 Session / Files 标签页、面包屑导航、预览 / 编辑 / 上传 / 下载、工作区徽章、Task Board 操作、自动折叠侧边栏、双语界面（EN/zh）。
- 由主机强制保护的路径，分两级：
- 硬拒绝——无论允许列表如何、无论你注册了哪个工作区，都永远无法访问：系统目录（Windows、System32、SysWOW64）以及凭据/密钥文件（.credentials.yaml、.ssh、.aws、.gnupg、.env、id_rsa、.pem …）。
- 软拒绝——默认阻止，但如果你在 PC 上刻意把工作区正好注册到那里，就可以访问：AppData、Program Files、ProgramData 以及私有数据目录（WeChat/WPS）。这些是隐私边界，不是凭据边界；注册这样的文件夹只是本地决定，只有 PC 用户本人能做，而且它永远不会解锁其下被硬拒绝的文件。

安全模型

- Tailscale ≠ 身份验证。 它证明的是你在哪个网络，而不是你是谁。设备配对才是应用边界。
- trusted-host ≠ 身份验证。 它是浏览器信任围栏（Host 头 + 跨站检查）。配对才是边界。
- Harness 进程始终只监听回环地址。 只有在显式转发器（Tailscale IP，以及选择启用 walk-on-LAN 时的 LAN IP）下，才会把 Web 服务暴露到网络接口上——这些转发器绑定的是具体地址，绝不会是 0.0.0.0。
- 配对只保护 /remfs，不保护 Harness 原生的 /api。 GUI 自己的 API 接口没有用户登录；请把网络边界（tailnet / LAN）收紧，并检查哪些设备能访问它。
- 文件系统允许列表是主要的文件权限边界。 远程客户端只能收窄*它；放宽（C:\、新磁盘）需要在 PC 上编辑 .remfs-roots.json。
- 路径逃逸有两道防线：带 ../UNC 的原始路径会被拒绝，并且规范化后的 realpath 必须留在允许列表内（符号链接/junction 逃逸会失败）。
- 远程写入有编码保护：上传或编辑非 UTF-8 文件（UTF-16 BOM、GBK/ANSI 字节序列）会被拒绝，而不是损坏它；编辑过的文件在写回时会保留 UTF-8 BOM 和主要换行风格（CRLF/LF）。
- presence 只读围栏是运维开关：默认情况下，Task Board 在浏览器信任围栏内无需认证即可工作；在 ~/.dsh/remfs-options.json 中设置 pocketStrict: true 后，每次浏览器 /pocket 调用都需要有效的设备凭据。桌面伴侣使用单独的 256 位本地只读 presence token；其 token 文件在远程被硬拒绝。
- 推送订阅仅限已配对设备：注册订阅需要有效的设备凭据；被撤销的设备会在一分钟内清除；任务标题/摘要只推送给已配对设备。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
append to %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml:
- insert:
- id: remfs-persistent
name: '@zetaluolang/remfs-persistent'
inject: [connection, fs, sandboxPolicy, workspaceRegistry]
restart dsh web

Windows 用户（一键）： 下载/解压仓库，然后双击 一键部署.cmd。需要联网。安装程序会处理 Node、Tailscale、项目自有的 DSH 运行时、配置档/插件设置、启动器、看门狗和首次启动。唯一需要你动手的环节是 Tailscale/UAC 提示。只有本地 Harness 和插件路由通过实时健康检查后，才会打印 DONE；因此打印出的手机 URL 可以直接打开。HTTPS 可能仍需在 Tailscale 管理控制台里启用一次证书。

悬浮 Orb 是安装完成后的日常界面，不是安装程序：它显示智能体健康状态，登录时自启；部署/修复仍保持事务化，并在 install.ps1 中可见。

手机上首次使用（配对）

1. 打开手机 URL（https://<pc-name>.<tailnet>.ts.net，或者启用 walk-on-LAN 且你在同一 Wi-Fi 下时用局域网 URL）。
2. 工作台会显示配对界面。
3. 在 PC 上，从 %USERPROFILE%\.dsh\remfs-pairing.txt（或 harness 日志）读取配对码。
4. 在手机上输入配对码 + 设备名 → 配对完成。凭据存在手机上；PC 只保存哈希。
5. 随时可在工作台 ⋯ → Devices 里吊销设备。

自愈看门狗

install.ps1 会注册一个任务计划程序任务（dsh_harness_watchdog，每 5 分钟一次，当前用户，隐藏窗口），运行 %USERPROFILE%\.dsh\launcher\watchdog.ps1。每次运行：

1. 验证 127.0.0.1:3080 确实由我们的 dsh 进程占用 —— 占用进程的命令行必须包含部署的 dsh bin 路径（看门狗复用启动器的 Get-OwnedHarnessPid 归属检查；绝不轻信一个裸的开放端口，因此无关的 localhost 服务不会被误认成 harness）。
2. 如果我们的 harness 已停止且端口空闲，就通过以下方式无头重启它 restart_harness_once.ps1（DSH_HEADLESS=1 —— 无浏览器、无对话框），并把每一步追加写入 %USERPROFILE%\.dsh\launcher\watchdog.log。
3. 如果占用端口的是外来进程，它只记录冲突然后退出——绝不会去杀掉或重启不属于自己的进程。

重新运行 install.ps1（或 一键部署.cmd）即可更新任务定义；健康状态下，看门狗每 5 分钟写一行日志报到。

威胁模型

我们防御：未认证的 RPC、远程放宽白名单、路径逃逸、静态凭据窃取、GUI 意外暴露到局域网/公网。

我们暂不防御：harness GUI 的 /api 本身没有用户登录（配对保护的是 /remfs，不是 GUI——请收紧网络边界）、主机被攻陷、Tailscale 账号被攻陷。详见 SECURITY.md。

故障排查

| 现象 | 处理 |
| 手机一直停在配对界面 | 从 %USERPROFILE%\.dsh\remfs-pairing.txt 读取配对码；配对码 10 分钟后过期——重启 harness 生成新的 |
| 设备被吊销 / 重新配对失败 | 配对码是一次性的；重启 harness 获取新码 |
| 手机收到 403 | 使用打印出来的 HTTPS/Tailscale/局域网 URL；GUI 必须在信任这些主机的情况下运行（一键部署已处理） |
| 局域网 URL 打不开 | 手机必须连同一个 Wi-Fi；重新运行启动器，让它检测当前局域网 IP |
| npm.ps1 被执行策略拦截 | 改用 npm.cmd，或执行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned |
| 刚发布后 npm view 返回 404 | CDN 边缘缓存——等一分钟，或带上 Cache-Control: no-cache 查询 |
| dsh plugin add 后插件一直不出现 | 你还得追加 loader 行，并重启 dsh web |
| PC 休眠 | keep_awake + 电源计划由部署处理；见 keep_awake.ps1 |
| Harness 反复挂掉 / 手机连不上 | 查看 %USERPROFILE%\.dsh\launcher\watchdog.log；重新运行 install.ps1 来（重新）注册看门狗任务 |
| Orb 组件显示 ? / "Disconnected" | harness 或转发器挂了——检查看门狗日志和 127.0.0.1:3080 |
| 推送开关置灰（"needs 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 横屏——侧边栏折叠、Task Board 操作、面板宽度、无溢出。见 docs/device-tests/。

路线图

- [x] Tailscale HTTPS + IP 访问，局域网直连
- [x] 持久化插件（不再每次会话运行）
- [x] 设备配对 + 凭据认证 + 吊销
- [x] 能力受限白名单 + 受保护路径 + 路径逃逸测试
- [x] 双语 UI、安全测试、CI
- [x] 启动时隔离损坏的演示会话 + 自愈看门狗
- [x] 会话大小提示 + 手机 UI 里的「建议归档」
- [x] 演示存在性行为测试（幂等添加、固定 cwd、仅清理演示）
- [x] 上传/编辑时的 UTF-8 编码保护 + 保留 BOM/换行
- [x] /pocket 严格模式（通过 ~/.dsh/remfs-options.json 选择启用）
- [x] Tailscale ACL 加固指南
- [x] 桌面快捷方式自动化（install.ps1）
- [x] PC 置顶 Orb 小组件（scripts/orb-widget.ps1，零依赖 WinForms）
- [x] 页面关闭时的手机 Web Push 通知（RFC 8291，按配对设备选择启用）
- [ ] 更多设备分辨率验证
- [ ] 向上游贡献（见下文）

License

MIT