DeepSeek Harness Remote

DeepSeek Harness 的安全远程访问层与手机 Companion。

本项目不是"把 3080 端口开放到局域网"的小插件，而是在远程世界与 Harness localhost 信任域之间建立一个新的、明确的、可审计的 Remote Access Security Layer（详见 docs/ 四份规格文档与 docs/HANDOVER.md 交接文档）。

功能总览

版本	能力
V1	安全局域网：扫码配对 + 设备身份 + 签名认证 + Remote Gateway + 手机 Web UI
V2	公网 Relay：PC 主动出站 Tunnel + 端到端加密（E2EE）+ 公网配对 + 多电脑路由
V2.5	手机端对标网页端：模型选择、排队发送/队列管理、批准（允许/拒绝）、Agent 提问、任务进度（轮次/步骤/token 速度）、会话统计
V2.6	会话管理：新建会话（工作区+预设）、搜索、重命名、归档、todo 任务列表、Agent 预设
V3	P2P 基础：Signaling 服务端 + werift WebRTC 选型 + TransportOrchestrator 骨架

手机端能力（对标网页端）

• 会话：列表（持久化会话恢复）/ 详情 / 分页加载 / 搜索 / 新建（选工作区+预设）/ 重命名 / 归档
• 对话：消息标签（user/assistant/tool）、长内容折叠展开、实时事件流、双向通信
• 交互：模型选择器（三级弹层）、推理等级切换、排队发送提示 + 队列管理（打断/删除）、工具批准卡片（允许/拒绝）、Agent 提问卡片（选项/多选/自定义）、todo 任务卡片
• 状态：进度面板（轮次/步骤/当前工具/token 速度）、会话统计、连接状态条
• 传输：LAN（HTTPS 签名）+ 公网 Relay（E2EE WSS）无感切换

目录结构

docs/                        四份规格文档 + compatibility.md（上游版本锁定）+ HANDOVER.md（交接）
packages/
  protocol/                  协议层：DTO / 常量 / 错误码 / Canonical / SAS / Pairing / Transport（零依赖）
  e2ee/                      E2EE：ECDH/HKDF/AES-GCM，Node + 浏览器双实现（格式互通）
  remote-host/               Host 插件：Gateway / Pairing / Auth / Policy / Adapter / Admin API / Relay / P2P
    assets/mobile/           手机 Web UI（原生 ES Modules，无构建）
  remote-client/             PC 设置 UI（Client Plugin，settings.section「远程访问」）
  bundle/                    Harness Bundle（cordis.patch.yml 组合层）
apps/
  relay-server/              公网 Relay 服务器（独立服务，不依赖 Harness）
scripts/
  pack.mjs                   打包脚本（产出可安装 tarball，含中文路径修复）
  e2e-real.mjs               真实环境 LAN 端到端验证
  e2e-relay-real.mjs         真实环境 Relay 端到端验证（11 步）
  phone-sim-real.mjs         手机模拟（LAN/Relay 配对 + E2EE 全链路）
  admin-cli.mjs              Admin 签名 CLI（配对创建/批准/Relay 管理）
  admin-takeover.mjs         本机信任模式 Admin 密钥接管（开发用）
  mobile-dev-proxy.mjs       手机 UI 开发代理（本机 http 模拟手机环境）
  spike-p2p-node.mjs         V3 WebRTC spike（werift 双端 DataChannel）

快速开始

1. 启动服务（三件套）

# 终端 1：Relay 服务器（V2 公网能力；只用局域网可跳过）
$env:RELAY_PORT=3090; node apps/relay-server/lib/index.js

# 终端 2：dsh（加载 @dshr 插件，Gateway 3180 + Relay 自动连接）
dsh web

# 终端 3（可选，开发调试）：手机 UI 本机代理
node scripts/mobile-dev-proxy.mjs 192.168.0.203:3180 8080
# 浏览器打开 http://127.0.0.1:8080 即手机界面（localhost 是 Secure Context，Web Crypto 可用）

若 PC 面板 Relay 状态显示"错误：无法连接 Relay 服务器"——说明 relay-server 未启动，按上面终端 1 启动即可。

2. 配对手机

• 局域网：PC 设置 → 远程访问 →「添加手机（生成二维码）」→ 手机扫 https://<LAN IP>:3180/pair#...（自签证书需点"继续访问"）
• 公网：PC 设置 → 远程访问 →「互联网远程访问（Relay）」→ 开启 →「添加公网设备（Relay 二维码）」→ 手机打开 /pair#v=1&h=...（无需同一 Wi-Fi）

3. 公网部署（Relay 服务器）

relay-server 是自包含服务：一个地址同时提供手机页面（/、/pair 配对落地页）+ 全部 API（/v1/*），不需要数据库/Redis/额外 Web 服务器。

# 服务器上：只需 Node.js，克隆仓库后
cd apps/relay-server && npm install   # 安装 ws 依赖
RELAY_PORT=443 node lib/index.js      # 或由 Caddy/Nginx 反代到内部端口

需要	说明
一台公网服务器	任意云服务器，仅需 Node.js
域名 + TLS（推荐）	手机 Web Crypto 需要 HTTPS（Secure Context）；可用 Caddy 自动签发
防火墙放行 443	手机与 PC 都连 wss://域名:443

然后把 PC 端 cordis.patch.yml 的 relayServerUrl 改成公网地址：

- id: dshr-remote-host
  config:
    relayEnabled: true
    relayServerUrl: 'https://relay.example.com'   # 改为你的域名

重启 dsh 后，PC 生成的 Relay 配对二维码前缀即变为公网地址，手机在任何网络扫码即可配对。

4. 使用

手机端：我的电脑 → 在线主机 → 会话列表/详情；会话内可选模型、发消息（运行中自动排队）、批准工具、回答问题、查看任务进度。

开发命令

# 构建（按依赖顺序）
node node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/bin/tsc -p packages/protocol/tsconfig.json
node .../tsc -p packages/e2ee/tsconfig.json
node .../tsc -p packages/remote-host/tsconfig.json
node .../tsc -p apps/relay-server/tsconfig.json

# 测试（各包目录，共 120 项）
node --test --experimental-test-isolation=none "test/*.test.ts"

# 打包 + 安装到用户 profile（HANDOVER §7.4 有完整流程）
node scripts/pack.mjs
# 复制 dist-packages/*.tgz 到 C:\Users\<user>\.dsh\profiles\web\ 后：
pnpm add "./dshr-bundle-0.1.0.tgz" --force   # 或手动解包（见 HANDOVER §7.4）

真实环境验证

# LAN 全流程（bootstrap → 配对 → 批准 → 签名访问）
node scripts/e2e-real.mjs <bootstrapSecret>

# Relay 全流程（11 步，需先启动 relay-server）
node scripts/e2e-relay-real.mjs <bootstrapSecret>

# 手机模拟（配合 PC 浏览器批准）
node scripts/phone-sim-real.mjs "<配对链接>" [--verify-relay http://127.0.0.1:3090]

安全模型（核心铁律）

1. Harness 3080 保持 127.0.0.1，绝不开放 0.0.0.0
2. Remote Gateway 自建 server，绑定具体 LAN IP，/api 一律 404
3. 所有 Remote Action 经 RemotePolicy，未知一律 DENY（Fail Closed）
4. Relay Server 只搬密文，不保存 Session/私钥，不理解 Harness 业务
5. E2EE ≠ Authorization：设备签名 + Host Identity + Policy 同时存在
6. Host Identity 改变 → Fail Closed 强制重配对
7. 写请求带 operationId；断线不自动重发

已知限制 / 注意事项

• 自签证书：tls.mode=auto 每次重启重新生成证书，手机首次访问需"继续访问"
• agent-presets scope bug（本环境）：dsh 重启后对未激活持久化会话的某些 RPC（模型/重命名/新建）受上游限制，手机端已做降级（直连 agent、事件收集模型、友好错误提示）；网页端打开会话后即恢复正常
• 第三方插件报错：控制台 /api/pet/state 404 等来自 @linxin666 第三方插件，与 Remote 无关
• 完整安装/卸载/升级流程与坑位见 docs/HANDOVER.md