nonmean/dsh-lan-access

dsh-lan-access

一个 DeepSeek Harness Web 插件，为 DSH 设置外壳（设置 → 通用）添加一个 LAN 访问 开关。它取代了手动修改 cordis.patch.yml 的 webserver 覆盖方式：

已在 DeepSeek Harness v0.1.7-alpha.2 上测试 —— 本插件已验证可在该 harness 版本上运行。

- 开启 —— Web GUI 绑定到 0.0.0.0，因此同一网络中的其他机器可以通过 http://:3080/?token=… 打开它。dsh web 启动时会为 LAN 地址打印完整 URL（带有每进程的 ?token= 启动令牌）—— 新的 LAN 浏览器需要在 URL 中带上该令牌才能通过认证。/api 信任围栏会实时更新，因此 LAN 机器上的浏览器可以完整使用（聊天、工具、工作区）。
- 关闭 —— GUI 重新绑定到 127.0.0.1（仅回环 —— 安全默认值）。

截图

从同一网络中的另一台机器打开的 DSH Web GUI
（http://192.168.0.101:3080）：

通过 LAN 打开的 DSH Web GUI

设置 → 通用中的 LAN 访问 开关，显示其他设备可以打开的地址：

设置 → 通用 LAN 访问开关

工作原理

| 部分 | 文件 | 作用 |
| --- | --- | --- |
| 宿主 | src/index.ts | 拥有插件本地的持久化标志（$DSH_HOME/lan-access.json）、受围栏保护的 /lan-access JSON 路由（GET 获取状态 / POST 设置状态）、绑定控制器，以及 lanAccess 绑定宿主服务。webserver 行中组合出的 host 表达式会读取该服务，因此每次 webserver（重新）启动 —— 启动、切换开关，或启动后重新应用用户补丁 —— 都会收敛到持久化的设置。仅当绑定不同时，切换开关才会重启 webserver fiber，使用 fiber.update(config, noSave)：no-save 路径会避免将组合后的树写入 cordis.yml，否则会触发 HMR 子树重载。 |
| 客户端 | src/client/ | 注册通用设置行（settings.general.item，顺序 15），带有原生复选框开关、LAN URL（主地址在前，显示所有活动网卡地址，复制按钮）、中英文文案，以及可容忍重启的轮询。 |

路由围栏接受回环地址或部署的可信授权方，这些信息从连接行解析后的配置中实时读取 —— 与 /api 网关使用相同的边界。跨站请求会被拒绝。

从 GitHub 安装

构建产物（lib/）已提交，因此安装无需构建步骤，也无需修改 DeepSeek Harness 检出目录：

从 GitHub 安装
dsh plugin --profile web add git+https://github.com/nonmean/dsh-lan-access.git

...或者克隆并安装本地检出（link: 可让你的重新构建保持生效）
git clone https://github.com/nonmean/dsh-lan-access.git
dsh plugin --profile web add link:/path/to/dsh-lan-access

重启 GUI
dsh web

安装会将 dsh-lan-access 追加到 dsh.profile.bundles；其
dsh.bundle.patch 会插入宿主行，并覆盖 webserver 行的
带有 lanAccess 服务表达式的 host。客户端那一半由 client-modules 扫描器自动拾取。核心功能无需修改 harness——开关、LAN 绑定以及实时的 /api 信任围栏都随插件一起发布。

本地开发——修改 src/ 后使用 pnpm build（或 npm run build）重新构建，然后重新安装/重启。仓库的 node_modules 镜像了 DSH profile 的包农场（TypeScript/tsdown 来自 harness 检出）。

从手动补丁迁移——从 profile 的 cordis.patch.yml（以及 bundle 补丁层）中移除任何 webserver 的 host: 0.0.0.0 覆盖，使插件成为绑定主机的唯一所有者。

使用

1. 打开 GUI，进入 Settings（侧边栏页脚）→ General。
2. 切换 局域网访问 / LAN access。
- 启用后会显示其他设备可以打开的唯一地址——拥有默认路由的接口的 IPv4（http://192.168.x.x:3080）——并带有一个复制按钮。
- 从另一台机器打开时，该地址必须包含浏览器会话的 ?token=…。dsh web 在启动时会打印回环地址和 LAN 地址的完整 URL（含 token）——复制 LAN 那个，例如 http://192.168.0.101:3080/?token=ICKD2317KYP…。该 token 是每进程的启动 token，用于换取会话 cookie；全新的 LAN 浏览器没有它就无法通过认证。
- Web 服务器会重启以重新绑定；该行会等待它完成并重新读取状态（重启过程中的网络错误不会被报告为失败）。
- 该插件还会在纯 HTTP 的 LAN 源上安装一个 crypto.randomUUID polyfill（该 Web API 仅存在于安全上下文中，而 DSH API 客户端用它来生成每个 RPC id——没有该 polyfill，远程浏览器会失败并报错 "crypto.randomUUID is not a function"）。
3. 该选择由插件持久化在 $DSH_HOME/lan-access.json 中（默认是 ~/.dsh/lan-access.json）：

{
"enabled": true
}

从 0.1.x 升级

完整升级需要两半（host + client）以及一次 dsh web 重启。host 那一半现在拥有自己的持久化，因此不再使用 harness 设置命名空间：

- 开关值已移至 $DSH_HOME/lan-access.json。~/.dsh/settings.yaml.imported 中旧的 lan-access: 部分不会被读取；升级后请切换一次开关。
- 重新安装（或重新构建 lib/），使 host 和 client 两半匹配；客户端 bundle 会一直缓存到下一次 dsh web。

远程 Settings 页面和工作区——无需修改 harness

插件所提供的一切都能从 LAN 浏览器正常工作，且对 DSH 检出零修改：

- 当前的 /api 网关信任所服务的 LAN 权威，因此配置平面（settings.、credentials.）可直接到达 host——Host/Origin 围栏允许 LAN 主机，而普通的浏览器会话认证会对其进行认证。Models 页面提供商目录，
插件配置卡片以及 Language/Appearance 行因此可以远程工作，无需额外跳转。
- 在非回环源上，客户端设置持久化会降级为内存模式（界面渲染为空）。浏览器 bundle 在运行时将
connection.isLoopback 扩展为“回环或所服务的 LAN 权威”。客户端入口注入 connection 并标记为
dsh.client.immediately，因此其 bundle 会被预取，其 apply 会在 connection 行提供句柄之后立即运行——早于任何设置界面（其等待 remote）读取
remote.$host.isLoopback。正是这种按 inject 顺序进行的扩展，使得在 LAN 页面上作用域保持在主机模式：没有它，早期绑定的界面会看到未打补丁的 isLoopback，其持久化会停留在内存模式——插件配置卡片不会渲染任何内容。
- crypto.randomUUID 在纯 HTTP LAN 源上不存在。 bundle 安装了一个基于 getRandomValues 的 polyfill（相同的 CSPRNG）。

本插件跟踪的 Harness API 变更

Harness 在 v0.1.7-alpha.1 中用基于 profile 的 Config 表单替换了其独立的、基于文件的设置提供程序：

- @deepseek-ai/dsh-settings 移除了 settings.register(ns, schema) /
SettingsScope（以及 dsh-settings-file 包），转而采用
SettingsForms，它投影每个插件条目的易变 Config。设置写入在 HMR 事务内运行（configEditor.edit →
hmr.runExclusive），该事务会协调整个 profile。由于本插件必须重启 Web 服务器才能更改绑定，将开关路由到该平面会在事务内重启服务器并污染其异步上下文。因此，本插件持久化自己的标志
（$DSH_HOME/lan-access.json）并直接重启 Web 服务器 fiber
（fiber.update(config, true)），从而避开 harness 设置平面。

更早之前，harness 在
0.1.0-rc.5 和 0.1.5-alpha.1 之间演进了设置/连接 API；插件也相应更新：

- @deepseek-ai/dsh-settings 移除了 settingsNamespace(ns) 辅助函数——
settings.register / .update / .replace / .mutate 现在接受原始命名空间字符串（在运行时以及通过编译时守卫进行验证）。
- 客户端 ConnectionHandle 不再携带 api 成员——远程方法通过
connection.rpc.call('/api', '/', …) 调用——因此插件不再修补 connection.api.settings. /
connection.api.credentials.。
- /api 网关不再将配置平面固定到回环：它现在信任所服务的 LAN 权威，因此设置/凭据 RPC 可以直接到达主机。因此，插件会提前扩展 connection.isLoopback
（通过 inject: ['connection'] 加上同步补丁），以在 LAN 页面上保持客户端设置持久化处于主机模式；远程 Settings 界面不再需要受围栏保护的 /lan-access/rpc
代理。
仅剩回环（硬编码在 harness 中，无法从插件修补）：host.pickDirectory / host.openPath（原生对话框和宿主文件打开）以及 llm.discoverModels（Models 页面的“discover”按钮）。工作区自身的添加/浏览流程不需要它们，聊天文件打开会路由到侧边栏编辑器。

调试辅助

宿主暴露了 GET /lan-access/diag（与其他路由一样受围栏保护），其中包含最新的浏览器启动报告：槽位注册计数、连接补丁是否处于活动状态，以及插件项槽位台账。在启动后的第一分钟内，浏览器还会每 2 秒轮询一次 Plugins 卡片自身注入的快照（available 标志）、槽位台账视图和声明的 spec——当 Settings 页面在远程机器上行为异常时，正是这些数据区分了“卡片消失”、“卡片被放弃”和“卡片存在但渲染为 null”。

可选：dsh-better-sidebar 兼容性补丁

dsh-better-sidebar 的信任围栏用错误的名称匹配连接行，并读取了原始的 !!js 配置，因此其面板（explorer / editor / terminal / git）只接受回环连接。仓库以 profile 级 pnpm 补丁的形式提供了修复（无需更改 harness）：

./scripts/install-patches.sh web

这会将 patches/dsh-better-sidebar.patch 复制到 profile 的 patches/ 目录中，在 pnpm-workspace.yaml 的 patchedDependencies 下注册它，并运行 pnpm install。

安全说明

- 默认是关闭（回环）。DSH 启动器本身拒绝 --host 0.0.0.0，原因相同：绑定所有接口会将 agent 的工具暴露到网络。仅在受信任的网络上启用它。
- 该开关只能通过受围栏保护的路由访问，从远程机器禁用会切断该机器的连接（预期行为——请在本地重新启用）。
- 该绑定在插件重载和补丁重新应用后仍然存在；完整进程重启会在启动时重新应用持久化的值。

开发

pnpm build        # tsdown: lib/index.js (host) + lib/client.js (browser bundle)
pnpm typecheck    # tsc --noEmit

客户端 bundle 是一个 __ModuleLoader__.load 闭包工厂产物（与 DSH monorepo 的 tsdown 客户端预设格式相同）；只有冻结的平台模块表词汇保持为外部依赖。更改客户端代码后，重新构建并重启 dsh web（客户端模块包的元数据缓存仅在重启时过期）。