DSH远控宿主插件（`@dsh-remote/plugin`）

在手机上远程操作 DeepSeek Harness（DSH）：下发指令、看流式输出、审批工具调用、回答问题，并让主机在任务跑完前保持唤醒。

载荷级端到端加密：中继从头到尾只见 base64(nonce ‖ secretbox)——不是"我们不查"，而是密钥在协议层的依赖图上就不可达（中继的构建产物里没有任何密码学实现，有测试锁住）。

安装

dsh plugin --profile web add @dsh-remote/plugin

桌面端把 --profile web 换成 --profile desktop。装完必须重启 Harness —— HMR 只热更 cordis.patch.yml 的配置，不会重新 import dist；浏览器面还要刷新页面才拉得到新的 client.cjs。不重启的表现是"改了的代码没生效"。

配一次中继与主机 token 见下面的教程。从源码构建（开发者）见第 2 步。

这是四仓里的主推库：装上它 + 一台中继 + 官方小程序，就能在手机上看着 DSH 干活并随时插话。

角色	仓	说明
宿主插件（本仓）	`dsh-remote/plugin`	跑在 DSH 进程里：配对、中继、会话与命令、审批转发、状态栏 pill
官方小程序	`dsh-remote/client`	微信小程序：扫码配对 / 会话列表 / 对话 / 审批 / 提问
中继	`dsh-remote/relay`	零知识 WebSocket 中继，单文件产物，可自托管
协议层	`dsh-remote/protocol`	帧与载荷 schema、E2E crypto、配对 URI。纯函数、零 I/O

官方小程序：黑鲸远控

黑鲸远控小程序码

微信扫上面这张码（或直接搜小程序名 黑鲸远控）即可打开官方客户端。

打开即用，无需安装：不装 App、不注册账号。
配对只需扫一次主机状态栏那颗 pill 给出的二维码，之后每次连都是自动的。
自建中继的用户注意：配对二维码里的地址来自主机侧配置（serverUrl），小程序只管扫，不需要手填任何地址。

教程

1. 前置

一台跑着 DeepSeek Harness 的机器（本仓要装进它的 profile）。
一台中继（生产实例已提供；自托管见 dsh-remote/relay 的 SELF-HOSTING）。
一个主机 token：中继与插件必须逐字一致（openssl rand -hex 32 生成）。把它放进中继的 DRC_HOST_TOKEN，插件侧只给变量名（见第 3 步）。

2. 装插件

用户路径（从 npm 装，推荐）：

dsh plugin --profile web add @dsh-remote/plugin

dsh plugin 转发的就是 pnpm —— 它把 @dsh-remote/plugin 写进 profile 的依赖并安装。桌面端换成 --profile desktop。装完必须重启 Harness（理由见顶部「安装」一节）。

开发者路径（从本仓源码装）：

pnpm install
pnpm build          # 产出两半：dist/bundle/index.js（宿主侧）+ client.cjs（浏览器面）
node scripts/install-to-profile.mjs

装进 ~/.dsh/profiles/desktop；其他 profile 用 DSH_PROFILE=… 指定。脚本只拷产物、不跑 pnpm add——profile 里不需要 node_modules。

⚠️ 两条路不要混用：install-to-profile.mjs 装出来的是软链时它会拒绝运行，而 dsh plugin add 装的是 npm 包。同一个 profile 里先后用过两条路，表现是 "文件都在、插件不加载"——三个名字（包名 / bundles 条目 / insert.name）必须一致。

3. 配一次

插件在 profile 里注册为一个 bundle（名字 dsh-remote-control——这是有意的稳定标识，路由前缀与数据目录都跟着它）。在 ~/.dsh/profiles/desktop/cordis.patch.yml 里补上配置：

plugins:
  - id: dsh-remote-control
    name: dsh-remote-control
    config:
      enabled: true
      serverUrl: ws://127.0.0.1:8787 # 自建中继填 wss://你的域名
      hostTokenEnv: DRC_HOST_TOKEN # 从环境变量读，别把 token 写进这个文件
      hostLabel: my-mac # 会显示在小程序顶部
      approvalTimeoutSec: 180 # 审批等不到回答的时限
      listingRefreshSec: 15

重启 Harness 后，状态栏会出现一颗 pill：未配对时点开直接就是二维码页。用「黑鲸远控」扫它 → 配对完成。配对码一次性，服务端权威寿命默认 120 秒。

配对入口只有那颗 pill。/drc 命令与右栏自动弹码已在 2026-10-03 整条删除—— 照着旧文档去找它们会扑空。

4. 用

小程序里：会话列表点开会话 → 输入框下发指令 → 流式输出实时回显 → 主机要审批 / 提问时手机上直接答。任务跑完前主机保持唤醒（防休眠由插件发命令，可配空闲多久释放）。

5. 排错

第一入口永远是状态快照：

cat ~/.dsh/dsh-remote-control/status.json

四个关键字段：

字段	看什么
`relay`	`online` / `connecting` / `offline`
`relayProblem`	连不上时的具体原因（token 不一致、地址错、中继没起…）
`carrier`	`services`=真内核 / `mock`=内存替身 / `none`=配置或载体有问题
`pill`	六条路由的软探测：`registered` / `webServer=none` / `disabled` / `miniprogramCode=ok

pill 不是 registered ⇒ 这台主机配不了对（配对入口只有它）。此时看 problems 里有没有 warn:pill，原因在那条 pill 探针里。

pill 背后的六条同域路由（改状态的那两条要带自定义头——那是同源判据，不是装饰；第六条是官方小程序那张静态码，只读、可缓存，与带 PSK 的 /pairing.png 是两件东西）：

# 设置页那张静态小程序码（只读；200 + image/jpeg，或图不在包里时 204）
curl -sI http://127.0.0.1:
/plugins/dsh-remote-control/miniprogram.jpg

# 状态（只读；Host 必须环回）
curl -s http://127.0.0.1:
/plugins/dsh-remote-control/status

# 触发发码（幂等；跨站会先触发 CORS 预检而被拦下）
curl -X POST -H 'x-drc-pair: 1' \
  http://127.0.0.1:
/plugins/dsh-remote-control/pairing/new

设计上的三条硬线

零知识：插件配置里只有 hostTokenEnv（变量名），没有 token 明文；中继经手的载荷是密封记录，密钥只经二维码过一次网络。
凭据落盘一律 0600：status.json、配对密钥簿（conversations-.json，含每个会话的 PSK）、宿主身份文件、附件目录都走同一个落盘端口； win32 上 chmod 只切只读位时会显式告警，而不是假装生效。
审批必须真的过 waterfall：只有参与宿主 approval/request 才能到达手机；没有手机在线时交还桌面 UI。approval/asked|decided 是审计事件，不能当应答通道用。

开发

pnpm install
pnpm typecheck      # 两个编译面：宿主侧（NodeNext）与浏览器半（DOM lib）
pnpm format:check   # ⚠️ 排在 test 之前，release workflow 也是这个顺序
pnpm test           # 543 条判据

改完跑一遍 node scripts/install-to-profile.mjs + 重启 Harness 再验。

许可

MIT

安装

说明文档

DSH远控宿主插件（@dsh-remote/plugin）

安装