dsh-private-remote

私人远程 · dsh-private-remote

一个供个人使用的 DeepSeek Harness 远程连接插件。它把另一台电脑上的官方 Harness Host 接到当前官方 Desktop 里：工作区、会话历史、模型请求、工具执行、审批和提问 仍然由远端 Host 管理，界面仍然使用官方现有的会话界面，而不是另做一个网页或只显示 连接状态的面板。

• 包名：dsh-private-remote
• 界面名称：私人远程
• 版本：0.1.0（协议 1）
• 已验证的 Harness：0.2.1-rc.3
• 仓库：
• 当前状态：已构建、已安装到本机官方 Desktop 的 desktop profile，并完成本机双实例

联调；真实 Windows + macOS 双机尚未验证（见“验证状态”）。

一、它做什么

同一套代码按配置承担两种角色：

角色 · 运行位置 · 作用 client · 你正在看的官方 Desktop · 保留官方界面；把本机 Gateway 的普通 /api 调用和 /api/remote.mux 流统一切换到已配对的远端 Host；提供“私人远程”面板和状态显示。 host · 另一台电脑上的 Harness · 在私网/Tailscale IP 上另开一个认证桥，只转发白名单内的官方会话、工作区、审批和提问接口；不复制会话数据库，不重写 Agent 循环。

连上远端后：

• 官方侧栏、会话列表、历史、输入框、流式回复、停止按钮、审批卡片和提问卡片仍然由

官方 UI 渲染。

• 所有模型请求、工具执行、项目文件和权威会话记录都在远端 Host 上发生。
• 客户端页面顶部/底部和会话标题旁会显示当前 Host、工作区和连接状态。
• 远端断开时，提交会被拒绝并显示“远端已断开”，不会悄悄改在本机执行。
• 点“切换回本机”后，官方 UI 恢复读取本机的工作区和会话；Host 上正在跑的任务不会

被取消。

二、不做什么

第一版明确不包含：

• 公共账号平台、自建打洞/中继服务、手机 App；
• 远程桌面、独立浏览器页面、PWA 或 dsh web 访问说明；
• 文件同步、文件预览、远程终端、模型/插件设置页面；
• 多活动远端 Host 同时切换（同一时刻只保留一个）；
• 把 Host 的模型 API Key 复制到客户端；
• 自动批准工具调用，或绕过官方审批/提问流程。

三、工作方式（一页）

官方 Desktop（客户端机器）                         远端 Harness Host（另一台机器）
┌──────────────────────────────┐                  ┌──────────────────────────────┐
│ 官方会话 UI                  │                  │ 官方会话 UI（本地使用）      │
│   │ /api、/api/remote.mux    │                  │                              │
│   ▼                          │                  │                              │
│ 本机 Typert Gateway          │                  │ 本机 Typert Gateway          │
│   │ Gateway switch（插件）   │   加密 HTTP/SSE  │   ▲                          │
│   ▼                          │  ──────────────► │   │ BridgeServer（插件）     │
│ 本机 BridgeClient ───────────┼──────────────────┼───┘ 只转发白名单端点        │
│ 控制通道 /private-remote     │                  │ 独立端口，绑定私网/Tailscale │
└──────────────────────────────┘                  └──────────────────────────────┘

客户端不是“改一个 URL”：普通 RPC、WebSocket 流、事件流、认证、会话选择都经过同一个 已认证桥；远端工作区/会话/缓存以 Host 身份隔离。实现细节见 docs/ARCHITECTURE.md。

四、安装

4.1 本机（已完成的安装）

当前这台 macOS 上的官方 Desktop 使用 desktop profile。插件已经以本地链接方式安装：

~/.dsh/profiles/desktop/package.json
  dsh.profile.bundles: [..., "dsh-private-remote"]
  dependencies: { "dsh-private-remote": "link:/Users/wangqiyuan/Documents/git/dsh-private-remote/bundle" }

安装动作本身走官方插件的 bundle 机制；没有修改官方安装目录，也没有分叉官方客户端。 本仓库重新构建后，bundle/ 是链接目标；Host 侧的代码需要重启 Harness 才会重新加载， 客户端 UI 在刷新页面后加载新的 client.js。

手动安装（任意 profile）可用官方 CLI：

dsh plugin --profile <profile> add /绝对路径/dsh-private-remote/bundle

或在当前 Desktop 里用插件管理器的 install_bundle 指向 bundle/ 目录。desktop profile 由 Electron 独占启动，不能直接用 dsh --profile desktop 启动；安装/管理请走 官方插件管理器或 dsh plugin。

4.2 Windows Host

1. 先按 4.3 或 4.4 在 Windows 上安装插件（Release 资产或 GitHub 仓库地址，不需要复制源码目录）。
2. 在 profile 的 cordis.patch.yml 增加 Host 配置（bindHost 改成该机的 Tailscale IP）：

- id: private-remote
  config:
    role: host
    bindHost: 100.68.241.8
    port: 47821
    label: Windows 工作站

1. 重启 Harness。打开“私人远程”面板，应看到“监听中”、监听地址和配对令牌。
2. Windows 防火墙只放行 Tailscale 私网到 TCP 47821（示例，管理员 PowerShell）：

New-NetFirewallRule -DisplayName "DSH Private Remote" `
  -Direction Inbound -Protocol TCP -LocalPort 47821 `
  -RemoteAddress 100.64.0.0/10 -Action Allow -Profile Private

不要绑定 0.0.0.0，也不要把端口映射到公网。插件的配置校验只接受回环、RFC1918、 Tailscale 100.64/10、IPv6 私网或 *.ts.net 这类私网地址。

4.3 从 GitHub Release 直接安装（Windows / 任意机器）

仓库与发布页：

发布资产：dsh-private-remote-0.1.0.tgz

Windows 上先正常打开一次官方 Desktop，让 desktop profile 初始化，然后完全退出 Desktop（不是最小化），在 PowerShell 中执行：

dsh plugin --profile desktop add `
  https://github.com/MikyWang/dsh-private-remote/releases/download/v0.1.0/dsh-private-remote-0.1.0.tgz

dsh 不在 PATH 时，换成官方 Desktop 自带的 CLI 完整路径。也可以从仓库根目录运行：

powershell -ExecutionPolicy Bypass -File .\install.ps1

安装完成后重新打开 Desktop，打开“私人远程”。macOS/Linux 把同一 URL 交给 dsh plugin --profile add 即可。desktop profile 必须由 Desktop 初始化过， 并且安装时 Desktop 要完全退出；这是官方 CLI 的限制。

发布资产就是 bundle/ 的 npm pack 结果；安装时不需要构建，也不需要 npm 账号。

如果要从源码安装：

git clone https://github.com/MikyWang/dsh-private-remote.git
cd dsh-private-remote
npm run build
dsh plugin --profile <profile> add "$PWD/bundle"

4.4 在官方“添加插件”对话框里直接添加

仓库根目录现在就是合法的 DSH bundle（package.json 含 dsh.bundle 和 dsh.client）， 所以可以直接使用官方 Desktop 的 插件 → 添加插件 对话框：

输入：https://github.com/MikyWang/dsh-private-remote
安装源：npm 官方源（默认）

点“安装”。插件管理器会把仓库作为 profile 层安装；安装完成后重启/刷新 Desktop， 侧栏出现“私人远程”。如果对话框更愿意接收本地目录，也可以填本仓库的绝对路径。 如果 GitHub 地址安装受网络影响失败，回退到 4.3 的 Release 资产 URL。

五、连接

5.1 网络

推荐并按当前设计采用 Tailscale IP 绑定：

1. 两台机器安装 Tailscale，登录同一个 tailnet。
2. Host 上执行 tailscale ip -4，得到 100.x.y.z。
3. 把该地址填入 Host profile 的 bindHost，重启 Harness。
4. 客户端面板填 http://100.x.y.z:47821；令牌从 Host 面板的“显示令牌”复制。
5. Host 面板确认“已连接设备”出现客户端；客户端面板确认模式为“远程”、显示 Host 名称和

平台。

如果已有可用的 SSH 隧道，也可以把远端桥的 loopback 端口转发到客户端本机，再填 http://127.0.0.1:47821；第一版不额外实现多套传输方案。

5.2 客户端操作

1. 打开官方侧栏的“私人远程”（中文界面；英文界面显示 Private Remote）。
2. 填远端地址、配对令牌、可选显示标签。
3. “测试连接”只做握手和兼容性检查；“进入远程”会切换 Gateway 并刷新页面。
4. 刷新后官方侧栏显示远端工作区；点工作区，官方会话列表和历史来自远端 Host。
5. 在官方输入框发送消息；流式回复、工具状态、停止、审批和提问都在官方会话界面里完成。
6. 右上角状态胶囊和会话标题旁的胶囊显示当前 Host/工作区/在线状态。
7. “断开连接”保留远端模式但标记离线，拒绝继续提交；“重新连接”需要内存中的令牌，

重新认证并重新读取状态。

1. “切换回本机”删除配对和本机持久化的 URL/标签，恢复本机数据；Host 任务不取消。

5.3 Host 操作

Host 面板显示监听地址、设备名、平台、版本、配对令牌和已连接设备：

• “显示令牌 / 复制”：令牌是机密，不要截图或发到聊天里。
• “轮换令牌”：立即断开所有客户端，旧令牌失效。
• “断开所有客户端”：只断开连接，不取消 Host 上正在跑的任务。
• “删除令牌并停止 Host 桥”：删除官方凭据中的令牌并停止桥，需重启才会生成新令牌。

六、安全模型（摘要）

• 私网不等于认证：桥有自己的应用层认证。握手使用共享令牌的 HMAC 双向证明，

令牌本身从不传输；随后用 HKDF-SHA256 派生双向密钥，AES-256-GCM 加密每个帧， 64 位序号 + 滑动窗口拒绝重放/旧帧。

• 客户端先验证 Host：Host 先出示 serverProof，客户端确认后才发送自己的证明，

避免把凭据送给冒充的端点。

• 只转发白名单端点：不提供任意 ctx.invoke、服务反射、终端、凭据、插件管理或

通用工具远程入口。白名单见 docs/SECURITY.md。

• 审批/提问沿用官方流程：转发官方 $events 瀑布事件，答案通过 $events/result

回到同一个 clientId + eventId；不默认自动批准。

• 凭据：Host 令牌保存在官方 credentials 服务（引用名

private_remote_host_token）；客户端令牌只在 Host 进程内存中，不写配置文件或 localStorage。客户端磁盘只保存远端 URL 和显示标签（$DSH_HOME/private-remote/client.json）。

• 日志：不记录业务负载、令牌、cookie 或模型 Key；只记录控制动作名、连接设备名、

平台和错误码。

• 已知边界：客户端重启后必须重新输入令牌；没有按设备单独吊销（只能轮换全部或断开

全部）；没有独立审计日志；HTTP 只允许私网/Tailscale，公网地址必须 HTTPS；Tailscale 本身提供 WireGuard 传输加密。

完整威胁模型和“为什么可以创建 owner 等价 Peer”的说明见 docs/SECURITY.md。

七、验证状态

已实现并验证

• npm run check：语法、静态规则、秘密扫描通过。
• npm test：30 个单元测试全部通过。
• npm run build / npm run verify：生成并校验 23 个文件的 bundle。
• npm run test:e2e：本机两个隔离 Harness 实例（Host + Client）跑通：

远端工作区基线、会话列表/历史、新建会话、发送/流式回复、停止、审批、提问、 断开后拒绝本地回退、显式切回本机。