dsh-lan-access

一个 DeepSeek Harness（DSH）Web 客户端插件：在浏览器处于非安全上下文（典型场景：通过明文 HTTP 访问局域网 IP，例如 http://192.168.1.20:3080）时，为缺失的 crypto.randomUUID() 打补丁，从而恢复 Web GUI 的完整功能。

纯客户端插件，不改动任何 DSH 核心包，随 ~/.dsh 配置持久化。

背景

现象

dsh web 服务启动后：

• 在本机访问 http://127.0.0.1:3080，一切正常。
• 在同局域网其他设备访问 http://<局域网IP>:3080，页面能打开，但功能全废：看不到会话、看不到工作区、选不了工作区、模型列表加载不出来。

根因

浏览器的 Web Crypto 只在安全上下文（secure context）里暴露 crypto.randomUUID()。安全上下文包括 HTTPS、localhost、127.0.0.1，但不包括明文 HTTP 访问局域网 IP。

DSH 的客户端连接包 @deepseek-ai/dsh-client-connection 在 mintRpcId() 里直接调用 crypto.randomUUID() 来给每个 /api RPC 请求生成关联 ID。在非安全上下文下，crypto.randomUUID 是 undefined，于是：

1. 每个 /api unary RPC 在真正发出 fetch 之前就抛出 TypeError: crypto.randomUUID is not a function；
2. 连接握手（host.describe）失败，循环进入重连；
3. 承载会话/工作区/模型列表数据的请求与 WebSocket 全部无法建立；
4. 最终表现为“静态页面能渲染（那些请求不走 RPC），但所有数据区空白”。

为什么用插件而不是改核心包

DSH 本身有 randomUuid()（基于 crypto.getRandomValues，非安全上下文同样可用），但 mintRpcId() 没用它。改核心包需要动 /opt/homebrew/lib/node_modules/... 下的文件，且升级/重装即失效。用一个客户端插件在页面启动早期补齐 crypto.randomUUID，副作用最小、随配置持久、易于迁移。

工作原理

插件的 package.json 声明：

"dsh": {
  "client": {
    "platform": "web",
    "immediately": true
  }
}

immediately: true 让该插件进入 boot 图的“立即层”。客户端插件的 apply()（其中 client-runtime 会调用 connection.start() → mintRpcId()）通过 cordis 的 fiber 微任务调度执行；而本插件的补丁在 factory 顶层（模块 materialize 阶段）同步执行，必然早于任何 apply()。因此即使它在配置树里排在 connection/client-runtime 之后，补丁也一定先生效。

lib/client.js 的 factory 顶层：

if (typeof crypto !== "undefined" && typeof crypto.randomUUID !== "function") {
  crypto.randomUUID = function () { /* 基于 crypto.getRandomValues 的 RFC 4122 v4 实现 */ };
}

仅在缺失时覆盖——HTTPS / localhost 访问时 crypto.randomUUID 已存在，行为完全不变。

目录结构

dsh-lan-access/
├── package.json      # 声明 dsh.client（platform: web, immediately: true）与 exports["./client"]
├── lib/
│   ├── index.js      # host 侧空实现（本插件无 host 行为）
│   └── client.js     # 浏览器侧 bundle：factory 顶层打 randomUUID 补丁
├── README.md         # 本文件（中文）
└── README.en.md      # 英文版

安装

以 DSH home 为 ~/.dsh、web profile 为 ~/.dsh/profiles/web 为例。

1. 放置插件

mkdir -p ~/.dsh/plugins/dsh-lan-access
cp -R dsh-lan-access/ ~/.dsh/plugins/

2. 在 profile 里建立链接

编辑 ~/.dsh/profiles/web/package.json，在 dependencies 里新增：

"dsh-lan-access": "link:../../plugins/dsh-lan-access"

3. 注册进配置树

编辑 ~/.dsh/profiles/web/cordis.patch.yml，在某个 insert: 块里新增（建议放在其他客户端插件之前）：

- insert:
    - id: lan-access
      name: dsh-lan-access

4. 安装依赖并重启

cd ~/.dsh/profiles/web
pnpm install
# 重启 dsh web（Ctrl+C 后重新执行 dsh web）

重启后，局域网设备访问启动时打印的 LAN 地址（http://<局域网IP>:3080），工作区与会话即可正常加载。

验证

在本机与局域网设备上分别打开页面，确认：

• 本机 http://127.0.0.1:3080：行为与安装前一致（crypto.randomUUID 原生存在，插件不干预）。
• 局域网设备 http://<局域网IP>:3080：会话列表、工作区、模型选择均正常。

也可在局域网设备浏览器控制台执行：

({ secure: window.isSecureContext, randomUUID: typeof crypto.randomUUID })
// 期望：{ secure: false, randomUUID: "function" }

randomUUID 为 "function" 即补丁已生效。

安全提示

• 0.0.0.0 绑定 + 无认证 = 同网段任何设备都能驱动 agent 执行 shell 命令。DSH 的浏览器信任围栏（trustedHosts）是防 DNS 重绑定/跨站，不是鉴权层。仅在可信局域网内开启局域网访问。
• 本插件只补 crypto.randomUUID，不涉及任何信任围栏或鉴权逻辑的放宽。

License

MIT