dsh-mesh-access 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# 更新日志
+
+## 1.0.0 — 改名（原名 dsh-phone-tunnel）
+
+插件和「手机」没关系：它做的是把组网地址上的请求转给本进程。所以改了名，顺便把定位放宽。
+
+- **包名 / 仓库名**：`dsh-phone-tunnel` → `dsh-mesh-access`（npm 上的旧名已 `deprecate`，仍可按旧名装到最后那版 0.1.5）；
+- 面板文案、「不只手机」章节、npm 描述、市场条目描述都改成「组网里的任何设备」；
+- API 路径 `/api/dsh-phone-tunnel/*` → `/api/dsh-mesh-access/*`；
+- 挂载 id `mesh` → `mesh-access`；
+- 命名空间变了，所以版本从 1.0.0 重新起（不是 0.1.6）。
+
+从 0.1.5 升级：先 `dsh plugin --profile web remove dsh-phone-tunnel`，再 `add dsh-mesh-access@1.0.0`，然后重启 `dsh web`。
+
+## 0.1.5
+
+- **把定位从「手机」放宽到「组网里的任何设备」**：手机、平板、另一台电脑、带图形界面的 NAS（DSM / QTS / TrueNAS Scale）、电视盒子，只要能连到组网 IP 就能打开，对方设备**不需要装任何东西**；
+- 面板文案跟着改：「手机地址」→「访问地址」，说明里写清「组网里的任何设备」；
+- npm 描述与市场条目描述同步放宽，关键词补 `nas` / `remote-desktop`。
+
+## 0.1.4
+
+- 面板的请求改成**可中止**（`AbortController`）：动作请求 20 秒、状态轮询 6 秒，超时就 abort，不会再把界面吊死；
+- 加了**看门狗**：按钮「处理中…」超过 22 秒会自动解除并提示，配合「刷新」按钮自愈；
+- 说明一下：这两个数字是给「进程正忙」留的余量 —— DSH 正在推流生成回答时，同一个 Node 进程处理面板请求会明显变慢，看起来像卡住。
+
+## 0.1.3
+
+- **修「点第二次就卡死」**：`start()` 原来会 `await server.close()`，而 `close()` 要等所有连接结束 —— DSH 的实时通道是长连接，于是永远等不到。现在同端口重复点击直接返回现状，并发的点击单飞；
+- 关闭改成「先拒绝新连接 → `closeAllConnections()` → 强制销毁自管 socket → 最多等 500ms」，不再阻塞；
+- 面板：反代运行时「③ 回到上面开端口」变「③ 端口已开」并禁用；动作请求加 20 秒超时兜底，不会再永远「处理中…」。
+
+## 0.1.2
+
+- 面板直接给出**带 token 的完整地址**（借用 `connection` 服务的 `authenticatedUrl()`），复制到手机点开即可，不必再去终端里找 token。
+- 「第一次用星空组网？」改成引导式三步按钮：注册 / 下载客户端 / 回到上面开端口。邀请链接只放在按钮的 `href` 里，不再把 URL 明文印在页面上。
+- `inject` 增加 `connection`；`proxy.urlPlain` 保留不带 token 的裸地址。
+
+## 0.1.1 — 2026-11-07
+
+文档语言调整，功能与 0.1.0 完全一致。
+
+- `README.md`、`INSTALL.md`、`CHANGELOG.md`、`docs/architecture.md` 改为**中文**（这个包主要面向中文用户）；
+  英文原文保留在 `README.en.md`、`INSTALL.en.md`，两个 README 开头互相跳转。
+- 修掉导航行被反引号包住、在 GitHub 上渲染成代码而点不动的问题。
+- 包的 `files` 白名单显式列出四个文档文件；构建产物 `*.tgz` 不再进仓库。
+
+## 0.1.0 — 2026-11-07
+
+第一个版本。已发布到 npm：`dsh-mesh-access@0.1.0`。
+
+- **宿主半边**：组网网卡探测（`192.168.*` 上的 `StarVPN`、`utun*`、`tap*`、`tun*`、`wg*`、`gpd*`、
+  `ppp*`、`ipsec*`）、进程内反代并改写 `Host`、WebSocket / upgrade 转发、
+  `GET /api/dsh-mesh-access/status`、`POST /api/dsh-mesh-access/proxy`。
+- **客户端半边**：`sidebar.panellist` + `main` 两个槽位的面板（状态、开/关端口、手机地址与复制、
+  首次使用星空组网的提示），每 5 秒轮询一次。
+- **没有构建步骤**：两边都是普通的 ESM / 浏览器 JS，所以发布出去的包就是源码本身。

package/INSTALL.en.md

@@ -0,0 +1,96 @@
+# Install
+
+[English](INSTALL.en.md) | [中文](INSTALL.md)
+
+## Requirement
+
+- DSH `>= 0.2.1-rc.2` (`dsh --version`)
+- Node `>= 22` (whatever DSH already runs on)
+- An initialized `web` profile (`~/.dsh/profiles/web` exists — DSH creates it on first `dsh web`)
+
+## From npm (one line)
+
+```bash
+dsh plugin --profile web add dsh-mesh-access
+```
+
+Current: `dsh-mesh-access@0.1.3` (published 2026-11-07).
+
+> If your machine points npm at a China mirror (`registry.npmmirror.com`), the mirror can lag
+> behind or serve a partially synced record, and pnpm then fails with
+> `numeric field was not a number: when getting size for package`. Add the registry explicitly:
+>
+> ```bash
+> dsh plugin --profile web add dsh-mesh-access@0.1.3 --registry=https://registry.npmjs.org
+> ```
+
+## From the release tarball (no npm account, any registry)
+
+```bash
+dsh plugin --profile web add \
+  https://github.com/SilverKurali/dsh-mesh-access/releases/latest/download/dsh-mesh-access.tgz
+```
+
+## From a local checkout
+
+```bash
+git clone https://github.com/SilverKurali/dsh-mesh-access
+dsh plugin --profile web add link:"$PWD/dsh-mesh-access"
+```
+
+`link:` installs the directory itself; pnpm prints a peer-resolution warning that is expected for
+link installs and harmless here (the plugin has no peer for `@deepseek-ai/dsh` beyond the host).
+
+## From a git URL
+
+```bash
+dsh plugin --profile web add git+https://github.com/SilverKurali/dsh-mesh-access.git
+```
+
+## Verify
+
+```bash
+# 1. the profile now lists the plugin
+grep -n 'dsh-mesh-access' ~/.dsh/profiles/web/package.json
+
+# 2. restart the profile, then ask the host directly
+curl -s http://127.0.0.1:3080/api/dsh-mesh-access/status | head -20
+```
+
+A healthy answer looks like:
+
+```json
+{
+  "ok": true,
+  "host": { "upstream": "127.0.0.1", "port": 3080 },
+  "mesh": [{ "iface": "StarVPN", "address": "192.168.188.1", "netmask": "255.255.255.0" }],
+  "proxy": { "running": false, "port": 3081, "url": null }
+}
+```
+
+Then open the **组网访问** panel and press *在组网地址上开端口*, or:
+
+```bash
+curl -s -X POST -H 'content-type: application/json' \
+     -d '{"action":"start","port":3081}' \
+     http://127.0.0.1:3080/api/dsh-mesh-access/proxy
+```
+
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-mesh-access
+```
+
+Nothing is written outside the profile directory and `~/.dsh`; there is no service, no autostart,
+no firewall rule. Stopping the proxy (or restarting the profile) closes the mesh port.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| `没找到组网网卡` | The mesh client is not connected, or the interface is named differently. Run `ip -br addr` / `ifconfig` and set `interfacePattern` to match, and check `addressPrefix`. |
+| Panel shows the proxy running but the phone times out | Something between the phone and this host drops it — on Linux check `firewall-cmd --zone=<mesh zone> --list-ports`, on Windows the inbound rule for the port. |
+| Phone gets the page but every API call fails | The page was opened on a stale token/cookie; open a fresh `?token=` URL once. |
+| `listen EADDRINUSE` | Another process owns the port (a previous `dsh web` or the kit's script). Stop it, or start this proxy on a different port. |
+| Port opens, phone sees `401` | Expected: no cookie yet. `?token=` once. |

package/INSTALL.md

@@ -0,0 +1,97 @@
+# 安装
+
+[中文](INSTALL.md) | [English](INSTALL.en.md)
+
+## 前置条件
+
+- DSH `>= 0.2.1-rc.2`（`dsh --version`）
+- Node `>= 22`（DSH 本身就在用的那个即可）
+- 已经初始化过 `web` profile（`~/.dsh/profiles/web` 存在 —— 第一次 `dsh web` 时 DSH 会创建）
+
+## 一、从 npm 装（一条命令）
+
+```bash
+dsh plugin --profile web add dsh-mesh-access
+```
+
+最新版：`dsh-mesh-access@0.1.3`（2026-11-07 发布）。
+
+> **国内镜像的坑**：如果你的 npm 指向 `registry.npmmirror.com`，镜像可能只同步了一半元数据，
+> pnpm 会报
+> `numeric field was not a number: when getting size for package`。
+> 这时显式给官方源：
+>
+> ```bash
+> dsh plugin --profile web add dsh-mesh-access@0.1.3 --registry=https://registry.npmjs.org
+> ```
+
+## 二、从 Release 的 tgz 装（不需要 npm 账号，任何镜像都行）
+
+```bash
+dsh plugin --profile web add \
+  https://github.com/SilverKurali/dsh-mesh-access/releases/latest/download/dsh-mesh-access.tgz
+```
+
+## 三、从本地检出装（改代码时用）
+
+```bash
+git clone https://github.com/SilverKurali/dsh-mesh-access
+dsh plugin --profile web add link:"$PWD/dsh-mesh-access"
+```
+
+`link:` 装的是目录本身。pnpm 会打印一条 peer 依赖解析的警告，`link:` 装法必然出现，
+这里无害（本插件对 `@deepseek-ai/dsh` 没有运行时依赖，只是声明了 peer）。
+
+## 四、从 git 地址装
+
+```bash
+dsh plugin --profile web add git+https://github.com/SilverKurali/dsh-mesh-access.git
+```
+
+## 验证
+
+```bash
+# 1. profile 里已经有这个插件
+grep -n 'dsh-mesh-access' ~/.dsh/profiles/web/package.json
+
+# 2. 重启 profile，然后直接问宿主
+curl -s http://127.0.0.1:3080/api/dsh-mesh-access/status | head -20
+```
+
+正常的样子：
+
+```json
+{
+  "ok": true,
+  "host": { "upstream": "127.0.0.1", "port": 3080 },
+  "mesh": [{ "iface": "StarVPN", "address": "192.168.188.1", "netmask": "255.255.255.0" }],
+  "proxy": { "running": false, "port": 3081, "url": null }
+}
+```
+
+然后打开**「组网访问」**面板点「在组网地址上开端口」，或者：
+
+```bash
+curl -s -X POST -H 'content-type: application/json' \
+     -d '{"action":"start","port":3081}' \
+     http://127.0.0.1:3080/api/dsh-mesh-access/proxy
+```
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-mesh-access
+```
+
+除了 profile 目录和 `~/.dsh` 之外什么都没写：没有系统服务、没有开机自启、没有防火墙规则。
+关掉反代（或重启 profile）组网端口就关了。
+
+## 故障排查
+
+| 现象 | 原因与处理 |
+|---|---|
+| 面板显示「没找到组网网卡」 | 组网客户端没连上，或者网卡名字不在默认正则里。用 `ip -br addr` 或 `ifconfig` 看真实名字，改配置里的 `interfacePattern`，并检查 `addressPrefix`。 |
+| 面板说反代在跑，但手机超时 | 手机到这台机器之间被拦了。Linux 上查 `firewall-cmd --zone=<组网域> --list-ports`，Windows 上查该端口的入站规则。 |
+| 手机能打开页面，但每个接口都失败 | 页面用的是过期 token/cookie。重新点一次带 `?token=` 的地址。 |
+| `listen EADDRINUSE` | 端口被别的进程占了（上一次的 `dsh web`，或者 kit 脚本起的实例）。先停掉它，或换个端口起反代。 |
+| 端口开了，手机看到 `401` | 正常：还没有 cookie。用带 `?token=` 的地址访问一次。 |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SilverKurali
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,115 @@
+# dsh-mesh-access
+
+Expose the **running** DeepSeek Harness web UI on a mesh/VPN interface — from inside the server,
+without a second instance, without SSH, without touching the router.
+
+[English](#what-it-does) | [中文](README.md)
+
+![The “组网访问” (mesh access) panel in the sidebar](assets/screenshot-1.png)
+
+## What it does
+
+`dsh web --host` binds exactly one concrete interface address, and it rejects wildcards. So a
+server that serves `127.0.0.1:3080` is invisible to your mesh, and a TAP (`StarVPN`) or `utun`
+interface created *after* boot is not where it listens.
+
+This plugin adds a mesh port **inside the running process**:
+
+```
+any device ──▶ 192.168.188.1:3081 ──▶ (plugin proxy) ──▶ 127.0.0.1:3080  (the same dsh you are using)
+```
+
+One instance. One session list. No `task-board ledger is already owned by …` warning, no
+half-synced state between two servers.
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-mesh-access
+```
+
+No npm / behind a China mirror? Use the release tarball:
+
+```bash
+dsh plugin --profile web add \
+  https://github.com/SilverKurali/dsh-mesh-access/releases/latest/download/dsh-mesh-access.tgz
+```
+
+From a checkout: `dsh plugin --profile web add link:/absolute/path/to/dsh-mesh-access`.
+Full matrix (npm / tarball / checkout / git URL), verification and troubleshooting: [INSTALL.en.md](INSTALL.en.md).
+
+Restart the profile. A **组网访问 / Mesh access** entry appears in the left rail:
+
+| Block | What it shows |
+|---|---|
+| 当前状态 | proxy state, DSH's own listen port, how many mesh interfaces were found |
+| 动作 | open the mesh port / close it / refresh |
+| 手机地址 | the URL to open on the phone, with a copy button |
+| 第一次用星空组网？ | the referral sign-up link and the member-account rule |
+
+## HTTP surface
+
+The panel is a view over two routes kept deliberately small:
+
+```
+GET  /api/dsh-mesh-access/status     → { host:{upstream,port}, interfaces[], mesh[], proxy{...}, referral }
+POST /api/dsh-mesh-access/proxy      → {action:'start'|'stop', port?}
+```
+
+`curl -s localhost:3090/api/dsh-mesh-access/status` is enough to debug without a browser.
+
+## Configuration
+
+Optional, written in the profile's patch layer; every key has a default:
+
+```yaml
+- id: mesh
+  name: dsh-mesh-access
+  config:
+    interfacePattern: '^(StarVPN|utun\d+|tap\d+|tun\d+|wg\d+|gpd\d+|ppp\d+|ipsec\d+)$'
+    addressPrefix: '192.168.'
+    proxyPort: 3081
+    upstream: 127.0.0.1
+```
+
+`addressPrefix` exists so a public address on a `tun*` interface is never mistaken for a mesh
+address.
+
+## Why the cookie survives
+
+A request with `?token=` answers `303` and sets `dsh-auth-*` (`HttpOnly`, `SameSite=Strict`,
+`Max-Age=2592000`). The cookie payload embeds the **authority it was issued for**, signed with a
+secret kept in a persistent credential record — not a per-process random — so it outlives a
+restart. The proxy rewrites `Host` to the upstream authority on every request, which keeps the
+baked-in authority equal to what the server expects, which is why the same cookie keeps working
+through the mesh port.
+
+Corollary: change the mesh IP or the port and you must open a fresh token URL once.
+
+## Limitations
+
+- It cannot move *its own* server's listener; a plugin runs inside a process that is already
+  listening. The mesh port is a proxy, not a second bind of the primary server.
+- Only IPv4 mesh addresses are considered.
+- Still requires the phone to reach the mesh address — the tunnel's own quality applies. On
+  StarVPN's relay path expect ~0.4 MB/s and occasional multi-second RTT spikes, which can stall a
+  long streaming answer; reload resumes it.
+
+## Not just phones
+
+The name says phone, the mechanism says otherwise: the plugin forwards requests that arrive on a
+mesh address to the port this process already serves. Anything that can open a web page on the
+mesh works — a phone or tablet, another Windows/macOS/Linux laptop, a NAS with a GUI
+(Synology DSM, QNAP QTS, TrueNAS Scale), even a TV stick's browser.
+
+Requirements are only: same mesh, a route to the mesh IP, and a browser. **Nothing** has to be
+installed on the other device, and no SSH is involved.
+
+## Companion
+
+The shell-script edition (Linux/macOS/Windows launchers that start a *second* dsh instance bound
+to the mesh IP, with firewall rules and QR codes) is
+[dsh-mesh-kit](https://github.com/SilverKurali/dsh-mesh-kit). Use this plugin when you want one
+instance; use that kit when DSH is not running yet, or on a machine without a Node plugin install.
+
+MIT.

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# dsh-mesh-access
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+把**正在运行**的 DeepSeek Harness 网页界面挂到组网网卡上 —— 在服务进程内部完成，
+不需要第二个实例，不需要 SSH，也不用碰路由器。
+
+[中文](#它做什么) | [English](README.en.md)
+
+![侧边栏里的「组网访问」面板](assets/screenshot-1.png)
+
+## 它做什么
+
+`dsh web --host` 只接受**一个具体的网卡地址**，并且拒绝通配。所以只监听 `127.0.0.1:3080` 的实例，
+组网里的手机、笔记本、另一台电脑、带图形界面的 NAS 都看不见；而开机之后才出现的 TAP（星空组网的 `StarVPN`）或 `utun` 网卡，也不在它启动时的那一份地址表里。
+
+这个插件在**已经在跑的那个进程内部**多开一个组网端口：
+
+```
+任何设备 ──▶ 192.168.188.1:3081 ──▶（插件反代）──▶ 127.0.0.1:3080（你正在用的这个 dsh）
+```
+
+一个实例、一份会话列表：不会出现 `task-board ledger is already owned by …`，也不会出现两台服务状态不同步。
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-mesh-access
+```
+
+不方便用 npm，或者你的 npm 指向国内镜像？用 Release 里的 tgz：
+
+```bash
+dsh plugin --profile web add \
+  https://github.com/SilverKurali/dsh-mesh-access/releases/latest/download/dsh-mesh-access.tgz
+```
+
+从本地目录装（改代码的人用这个）：
+
+```bash
+dsh plugin --profile web add link:/绝对路径/dsh-mesh-access
+```
+
+完整的四种装法、验证步骤、卸载与故障表见 [INSTALL.md](INSTALL.md)。
+
+装完重启 profile，左侧导航会多出**「组网访问」**：
+
+| 功能块 | 内容 |
+|---|---|
+| 当前状态 | 反代是否在跑、DSH 自己的监听端口、找到几张组网网卡 |
+| 动作 | 在组网地址上开端口 / 关闭 / 刷新 |
+| 访问地址 | 给组网内任何设备打开的地址（带 token，可直接复制） |
+| 第一次用星空组网？ | 邀请注册链接 + 成员账号规则 |
+
+## HTTP 接口
+
+面板只是两个接口的外壳，故意做得极小：
+
+```
+GET  /api/dsh-mesh-access/status   → { ok, host:{upstream,port}, interfaces[], mesh[], proxy{...}, referral }
+POST /api/dsh-mesh-access/proxy    → { action:'start' | 'stop', port? }
+```
+
+不开浏览器也能排查：
+
+```bash
+curl -s http://127.0.0.1:3080/api/dsh-mesh-access/status
+```
+
+## 配置（可选）
+
+写在 profile 的 patch 层里，每一项都有默认值：
+
+```yaml
+- id: mesh
+  name: dsh-mesh-access
+  config:
+    interfacePattern: '^(StarVPN|utun\d+|tap\d+|tun\d+|wg\d+|gpd\d+|ppp\d+|ipsec\d+)$'
+    addressPrefix: '192.168.'
+    proxyPort: 3081
+    upstream: 127.0.0.1
+```
+
+`addressPrefix` 的作用是别把 `tun*` 上的公网地址当成组网地址。
+
+## 为什么 cookie 能一直用
+
+带 `?token=` 的请求返回 `303` 并种下 `dsh-auth-*`（`HttpOnly`、`SameSite=Strict`、`Max-Age=2592000`，
+即 30 天）。cookie 载荷里写死了**签发时的 authority**：
+
+```json
+{"version":1,"authority":"192.168.188.1:3081","issuedAt":…,"expiresAt":…}
+```
+
+签名密钥存在**持久的凭据记录**里（不是每进程随机），所以重启也在。反代每次请求都把 `Host`
+改写成上游 authority，于是 cookie 里的 authority 与服务端期望的一致 —— 这就是换个端口访问还能继续用
+同一份 cookie 的原因。
+
+反过来也成立：**换了组网 IP 或端口，就得重新点一次 token 链接。**
+
+## 限制
+
+- 插件动不了**自己进程**的监听地址。组网端口是反代，不是把主服务再绑一次。
+- 只考虑 IPv4 组网地址。
+- 仍然依赖隧道本身的质量。星空组网走中继时实测单向约 0.4 MB/s，`[SN-RTT]` 会抖到几秒，
+  长回答可能中途停住，刷新一下能接回来。
+- 同一份 `~/.dsh` 只允许一个实例持有 task-board 锁；这是刻意的，本插件就是为避开它而存在。
+
+## 不只手机
+
+名字叫 phone，但插件本身跟“手机”没有关系 —— 它做的是**把组网地址上的请求转给本进程**。
+组网里任何能打开网页的设备都能用：
+
+| 设备 | 用法 |
+|---|---|
+| 手机 / 平板 | 浏览器打开那条带 token 的地址，可加到桌面当 App |
+| 另一台电脑（Win / macOS / Linux） | 同一个地址，直接开；不用装 DSH，也不用装这个插件 |
+| 带图形界面的 NAS（群晖 DSM、威联通 QTS、TrueNAS Scale 等） | NAS 上的浏览器打开即可 |
+| 电视盒子 / 平板上的浏览器 | 同理，只要能连到 `192.168.188.1` |
+
+条件是三条：它在**同一个星空组网**里、能路由到组网 IP、浏览器能发 HTTP。
+**不需要**在对方设备上装任何东西，也不需要 SSH。
+
+## 配套
+
+命令行版（在 DSH 还没启动、或者机器上没有 Node 插件环境时使用：
+起**第二个**实例绑到组网 IP，附带防火墙规则与二维码）：
+[dsh-mesh-kit](https://github.com/SilverKurali/dsh-mesh-kit)，支持 Linux / macOS / Windows。
+
+设计取舍与实测数据见 [docs/architecture.md](docs/architecture.md)。
+
+## 许可
+
+MIT。

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-mesh-access — bundle patch
+#
+# Mounts the mesh-access plugin into the web profile. Install with:
+#   dsh plugin --profile web add dsh-mesh-access
+#   dsh plugin --profile web add link:/absolute/path/to/dsh-mesh-access   # local dev
+- insert:
+    - id: mesh-access
+      name: dsh-mesh-access

package/docs/RELEASE.md

@@ -0,0 +1,63 @@
+# 发布清单
+
+每改一次代码，下面四块**必须一起动**，否则就会出现「npm 上是新版、Release 还是旧版、文档写着上上个版本」这种漂移。
+
+## 1. 版本号
+
+- `package.json` 的 `version`
+- `CHANGELOG.md` 顶部加一节
+- `INSTALL.md` / `INSTALL.en.md` 里出现的 `dsh-mesh-access@x.y.z` 命令
+- `README.md` / `README.en.md` 里若有版本号（能不带就不带，用 `dsh-mesh-access` 拉 latest）
+
+## 2. npm
+
+```bash
+npm publish --registry=https://registry.npmjs.org
+```
+
+⚠️ `+ dsh-mesh-access@x.y.z` 只代表**元数据**提交成功，tarball 可能还要几分钟才可下载。必须探到 200 才算发完：
+
+```bash
+curl -sI https://registry.npmjs.org/dsh-mesh-access/-/dsh-mesh-access-<版本>.tgz | head -1   # 期望 200
+```
+
+再看一眼 dist-tags 与 shasum 对不对：
+
+```bash
+curl -s https://registry.npmjs.org/dsh-mesh-access | python3 -c "import json,sys;d=json.load(sys.stdin);v=d['versions'][d['dist-tags']['latest']];print(d['dist-tags']['latest'], v['dist']['shasum'])"
+```
+
+2026-11-07 那次实测：404 持续了约 6 分钟才变 200。这期间 `npm install` 会报 `npm error 404`，看着像发布失败。
+
+## 3. GitHub Release
+
+```bash
+npm pack --registry=https://registry.npmjs.org
+mv dsh-mesh-access-<版本>.tgz dsh-mesh-access.tgz        # 附件名不带版本号
+git -c tag.gpgSign=false tag -a v<版本> -m "<摘要>"
+git -c http.version=HTTP/1.1 push origin refs/tags/v<版本>
+gh release create v<版本> dsh-mesh-access.tgz --title "v<版本> — <摘要>" --notes-file /tmp/rel-notes.md
+```
+
+附件名**必须不带版本号**，因为文档里用的是稳定地址
+`https://github.com/SilverKurali/dsh-mesh-access/releases/latest/download/dsh-mesh-access.tgz`。
+发完验一次：
+
+```bash
+curl -sIL .../releases/latest/download/dsh-mesh-access.tgz | grep -i '^HTTP'
+tar -xzOf dsh-mesh-access.tgz package/package.json | grep version
+```
+
+## 4. 装一次（别信代码，信安装）
+
+```bash
+rm -rf ~/.dsh/profiles/reltest && cp -a ~/.dsh/profiles/headless ~/.dsh/profiles/reltest
+dsh plugin --profile reltest add dsh-mesh-access@<版本> --registry=https://registry.npmjs.org
+# 起临时实例 → GET /api/dsh-mesh-access/status → POST proxy start → curl 期望 401
+rm -rf ~/.dsh/profiles/reltest
+```
+
+## 5. 市场条目
+
+`store/dsh-mesh-access.yml` 只在**分类、描述、图标、tarball 地址**变化时才需要改；`npm:` 键由 registry 自动采集，**不要手写**。
+提交给 `awesome-dsh-plugin` 的 PR 由仓库所有者本人开，AI 只备料。

package/docs/architecture.md

@@ -0,0 +1,91 @@
+# 设计说明
+
+## 约束一：`dsh web` 只绑一个地址
+
+```
+--host <host>   绑定地址：本机某张网卡上的一个具体 IPv4/IPv6 字面量；
+                通配地址会被拒绝
+```
+
+由此产生三个后果：
+
+- `0.0.0.0` **不是选项**，这是设计如此。用 socat/iptables 把它补回来不在范围内。
+- 开机时启动的服务，绑的是开机那一刻存在的地址。之后才注册的 TAP（`StarVPN`）不在那一份里。
+  在 Linux 上这件事曾经让**别的**守护进程连续几个月打印
+  `error: Bind to port 22 on 192.168.188.1 failed: Cannot assign requested address`，
+  而服务本身照样起来了、只是没有组网地址 —— 这正是 sshd 那个 guard 单元存在的原因，
+  也是这些脚本每次运行都重新解析网卡的原因。
+- 想在两个地址上可达，只有两条路：**两个进程**（拓扑 A）或者**一个进程加前面一层反代**（拓扑 B）。
+
+## 约束二：token / cookie 这道栅栏
+
+访问 `/` 时是这样判的：
+
+| 请求 | 响应 |
+|---|---|
+| `GET /` 无 cookie | `401 dsh web authentication required` |
+| `GET /?token=<t>` | `303 See Other`、`location: ./`、`set-cookie: dsh-auth-…` |
+| `GET /` 带该 cookie | `200` |
+| `/api/*`，`Host` 既不是服务器自己也不在 `--trusted-host` 里 | `403` |
+
+cookie 载荷里写死了**它是为哪个 authority 签发的**：
+
+```json
+{"version":1,"authority":"192.168.188.1:3081","issuedAt":…,"expiresAt":…}
+```
+
+并用 HMAC-SHA256 对一个存在**持久凭据记录**里的密钥签名（不是每进程随机），
+所以 cookie 能活过重启，而 token 不能。
+
+这一条直接决定了反代怎么做：**cookie 里的 authority 必须等于浏览器看到的 origin。**
+于是——
+
+- 反代**另一个**实例：把 `Host` 改写成上游（`--target`）；
+- 反代**同一个**实例：必须保留浏览器的 `Host`（`--keep-host`），并且实例本身要带
+  `--public-url http://<组网IP>:<端口>/ --trusted-host <组网IP>:<端口>` 启动。
+
+## 约束三：一个 home 目录只能有一份 ledger
+
+第二个 `dsh web` 指向同一个 `~/.dsh` 时能正常启动，但会报：
+
+```
+ui-task-board … Error: task-board ledger is already owned by process <pid>
+```
+
+其它一切正常。两个实例还共享 `~/.dsh/sessions/`，所以会话**列表**是共用的、而**进程状态**不是：
+同一个会话在两边同时打开就是自找麻烦。拓扑 A 里这是刻意的 —— 桌面那个实例是 DSH 自己拉起来的，
+没法简单搬家 —— 也正是拓扑 B 的主要理由。
+
+## 实测（中继路径，`path=SN`）
+
+```
+ping -c 40 -i 0.25 192.168.188.3
+40 packets transmitted, 40 received, 0% packet loss
+rtt min/avg/max/mdev = 57.540/66.685/78.079/4.580 ms
+
+# 单流，dd | nc 穿过隧道
+连续 20 秒约 400 KB/s，共 7.9 MB，无停顿
+
+# 同一时段的客户端日志
+[SN-RTT] Supernode 业务包往返偏慢: peerIP=192.168.188.3 rtt=1.054s path=SN
+[SN-RTT] … rtt=3.481s …
+[SN-RTT] … rtt=5.735s …
+```
+
+解读：隧道**能用**，但业务包 RTT 会抖到秒级，而 ICMP 一直很平。所以长连接（界面背后的 SSE / 长轮询）
+偶尔会卡住，刷新就能重建。这不是配置能解决的问题 —— 它就是中继本身。
+唯一的杠杆是打通直连（`transport=P2P` 加上可用的 STUN 路径）或者买「TCP 穿透」，
+而这取决于两张网络能不能互相看见。
+
+## 为什么当初先写脚本、后来又做成插件
+
+`dsh` 的 profile 就是一叠 npm 插件包（`dsh plugin --profile web add <包>`），所以这件事**确实**可以由插件来做。
+但脚本做的那几件事，插件永远做不到：
+
+- 自己挑网卡、把**服务进程的监听**（重新）绑上去 —— 地址是 `dsh web` 自己的启动参数；
+- 持有系统级的东西（systemd / launchd / Windows 防火墙规则）；
+- 在 DSH **没运行**的时候还在。
+
+而插件能做、并且严格优于脚本的，正是拓扑 B 的进程内版本：插件在自己的进程里开一个 `http` 服务绑到组网 IP，
+反代到 profile 本来就在服务的那个端口，于是手机和桌面共用同一个实例、没有外部零件。
+这就是现在这个包；`dsh-mesh-kit` 里的 `tools/mesh-proxy.mjs` 是同一套逻辑的原型。

package/icon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#4d8dff"/>
+      <stop offset="1" stop-color="#7b5cff"/>
+    </linearGradient>
+  </defs>
+  <rect x="2" y="2" width="60" height="60" rx="15" fill="url(#g)"/>
+  <g fill="none" stroke="#fff" stroke-width="3" stroke-linecap="round">
+    <circle cx="32" cy="32" r="17"/>
+    <path d="M15 32h34"/>
+    <path d="M32 15c6 6.5 6 27.5 0 34"/>
+    <path d="M32 15c-6 6.5-6 27.5 0 34"/>
+  </g>
+  <circle cx="32" cy="32" r="3.6" fill="#fff"/>
+</svg>

package/lib/client.js

@@ -0,0 +1,229 @@
+/**
+ * dsh-mesh-access —— 浏览器半边。
+ *
+ * 手写 loader 模块，不需要 TS / JSX / 打包器：DSH 的 client loader 只要求
+ * `window.__ModuleLoader__.load({ id, factory })` 里返回 `{ apply, inject }`。
+ * 组件用 react.createElement 拼，避免引入构建链。
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-mesh-access',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+
+    const react = require('react')
+    const h = react.createElement
+
+    const PANEL_ID = 'mesh'
+    const S = {
+      wrap: { padding: '24px 28px', maxWidth: 860, color: 'inherit', font: 'inherit' },
+      h1: { fontSize: 20, fontWeight: 600, margin: '0 0 4px' },
+      sub: { opacity: 0.62, fontSize: 13, margin: '0 0 20px' },
+      card: { border: '1px solid rgba(127,127,127,.28)', borderRadius: 12, padding: '16px 18px', marginBottom: 14 },
+      row: { display: 'flex', alignItems: 'center', gap: 10, flexWrap: 'wrap' },
+      label: { fontSize: 12, letterSpacing: '.02em', opacity: 0.55, textTransform: 'uppercase', marginBottom: 8 },
+      mono: { fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace', fontSize: 13 },
+      btn: { padding: '7px 14px', borderRadius: 8, border: '1px solid rgba(127,127,127,.4)', background: 'transparent', color: 'inherit', cursor: 'pointer', fontSize: 13 },
+      link: {
+    padding: '6px 14px',
+    borderRadius: 8,
+    background: 'transparent',
+    border: '1px solid var(--vscode-panel-border, #3a3f4b)',
+    color: 'var(--vscode-textLink-foreground, #6cb6ff)',
+    textDecoration: 'none',
+    fontSize: 13,
+    cursor: 'pointer',
+    display: 'inline-block',
+  },
+  btnPrimary: { padding: '7px 14px', borderRadius: 8, border: '1px solid rgba(127,127,127,.4)', background: 'rgba(127,127,127,.16)', color: 'inherit', cursor: 'pointer', fontSize: 13, fontWeight: 600 },
+      pill: (on) => ({ display: 'inline-flex', alignItems: 'center', gap: 6, fontSize: 12, padding: '3px 10px', borderRadius: 999, border: '1px solid rgba(127,127,127,.35)', opacity: on ? 1 : 0.6 }),
+      dot: (on) => ({ width: 7, height: 7, borderRadius: 999, background: on ? '#3fb950' : '#8b949e' }),
+      err: { color: '#f85149', fontSize: 13, marginTop: 8 },
+      hint: { fontSize: 12, opacity: 0.6, marginTop: 10, lineHeight: 1.6 },
+    }
+
+    /** 带硬超时的 fetch：超时就 abort，绝不让调用方永远挂着。
+     *  面板上「处理中…」卡死过一次（请求发出去了但响应没回来），
+     *  所以这里用 AbortController 兜底，而不是只 Promise.race。 */
+    const fetchJson = (url, options = {}, ms = 8000) => {
+      const ctrl = new AbortController()
+      const timer = setTimeout(() => ctrl.abort(), ms)
+      return fetch(url, { ...options, credentials: 'same-origin', signal: ctrl.signal })
+        .then((r) => r.json())
+        .finally(() => clearTimeout(timer))
+    }
+
+    const api = {
+      status: () => fetchJson('/api/dsh-mesh-access/status', {}, 6000),
+      action: (action, port) =>
+        fetchJson('/api/dsh-mesh-access/proxy', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ action, port }),
+        }, 20000),
+    }
+
+    function Icon() {
+      return h(
+        'svg',
+        { width: 18, height: 18, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.7, strokeLinecap: 'round' },
+        h('circle', { cx: 12, cy: 12, r: 9 }),
+        h('path', { d: 'M3 12h18M12 3c2.6 2.4 2.6 15.6 0 18M12 3c-2.6 2.4-2.6 15.6 0 18' }),
+      )
+    }
+
+    function Card({ title, children }) {
+      return h('div', { style: S.card }, h('div', { style: S.label }, title), children)
+    }
+
+    function Panel() {
+      const [state, setState] = react.useState(null)
+      const [busy, setBusy] = react.useState(false)
+      const [err, setErr] = react.useState(null)
+      const [copied, setCopied] = react.useState(false)
+
+      const refresh = react.useCallback(() => {
+        api
+          .status()
+          .then((s) => {
+            setState(s)
+            setErr(s && s.ok === false ? s.error ?? '未知错误' : null)
+          })
+          .catch((e) => setErr(String(e && e.message ? e.message : e)))
+      }, [])
+
+      react.useEffect(() => {
+        refresh()
+        const t = setInterval(refresh, 5000)
+        return () => clearInterval(t)
+      }, [refresh])
+
+      const run = (action) => {
+        setBusy(true)
+        setErr(null)
+        const started = Date.now()
+        const watch = setInterval(() => {
+          if (Date.now() - started < 22000) return
+          clearInterval(watch)
+          setBusy(false)
+          setErr('这次请求超过 22 秒没有回音，已自动解除；如果端口状态和预期不符，点一下「刷新」')
+        }, 1000)
+        api.action(action)
+          .then((s) => {
+            if (s && s.ok === false) setErr(s.error ?? '操作失败')
+            else setState(s)
+          })
+          .catch((e) => setErr(String(e && e.message ? e.message : e)))
+          .finally(() => {
+            clearInterval(watch)
+            setBusy(false)
+          })
+      }
+
+      const copy = (text) => {
+        const done = () => {
+          setCopied(true)
+          setTimeout(() => setCopied(false), 1600)
+        }
+        if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(text).then(done, () => {})
+        else done()
+      }
+
+      const mesh = (state && state.mesh) || []
+      const proxy = (state && state.proxy) || { running: false }
+      const host = (state && state.host) || {}
+      const url = proxy.url
+      const referral = (state && state.referral) || 'https://starvpn.cn/register.html?referralCode=Kurali'
+
+      return h(
+        'div',
+        { style: S.wrap },
+        h('div', { style: S.h1 }, '组网访问'),
+        h('div', { style: S.sub }, '把当前这个 DSH 实例搬到组网网卡上，组网内任意设备直接打开，不用第二个实例、不用 SSH。'),
+
+        h(
+          Card, { title: '当前状态' },
+          h('div', { style: S.row },
+            h('span', { style: S.pill(proxy.running) }, h('span', { style: S.dot(proxy.running) }), proxy.running ? '反代运行中' : '反代未启动'),
+            h('span', { style: S.pill(Boolean(host.port)) }, h('span', { style: S.dot(Boolean(host.port)) }), host.port ? 'DSH 监听 127.0.0.1:' + host.port : 'DSH 端口未知'),
+            h('span', { style: S.pill(mesh.length > 0) }, h('span', { style: S.dot(mesh.length > 0) }), mesh.length > 0 ? '组网网卡 ' + mesh.length + ' 个' : '未发现组网网卡'),
+          ),
+          h('div', { style: S.hint }, mesh.length > 0
+            ? '组网：' + mesh.map((m) => m.iface + ' → ' + m.address).join('，')
+            : '没找到 StarVPN / utun / tap / tun / wg 网卡上的 192.168.* 地址。先把星空组网（或 Tailscale / WireGuard）连上再刷新。'),
+        ),
+
+        h(
+          Card, { title: '动作' },
+          h('div', { style: S.row },
+            h('button', { style: S.btnPrimary, disabled: busy || proxy.running, onClick: () => run('start') }, busy ? '处理中…' : '在组网地址上开端口'),
+            h('button', { style: S.btn, disabled: busy || !proxy.running, onClick: () => run('stop') }, '关闭'),
+            h('button', { style: S.btn, disabled: busy, onClick: refresh }, '刷新'),
+          ),
+          err ? h('div', { style: S.err }, err) : null,
+          h('div', { style: S.hint },
+            '开端口 = 在组网 IP 上再监听一个端口（默认 3081），把你现在的请求转给本进程的 127.0.0.1:' + (host.port || '3080') + '。',
+            '组网里的任何设备因此都是同一个实例、同一份会话列表。',
+          ),
+        ),
+
+        url
+          ? h(
+              Card, { title: '访问地址' },
+              h('div', { style: S.row },
+                h('code', { style: { ...S.mono, wordBreak: 'break-all' } }, url),
+                h('button', { style: S.btn, onClick: () => copy(url) }, copied ? '已复制' : '复制'),
+              ),
+              h('div', { style: S.hint },
+                '这条地址已经带上本进程的 token，直接点开就能进；它会种下 30 天 cookie，之后裸地址也进得去。',
+                ' cookie 里的 authority 是发给这个地址的 —— 换端口或换 IP，回到这里重新复制一次。',
+              ),
+            )
+          : null,
+
+        h(
+          Card, { title: '第一次用星空组网？' },
+          h('div', { style: S.hint }, '三步走，不用记 IP，也不用改任何配置。'),
+          h('div', { style: S.row },
+            h('a', { href: referral, target: '_blank', rel: 'noopener noreferrer', style: S.link }, '① 注册星空组网'),
+            h('a', { href: 'https://doc.starvpn.cn/#/download', target: '_blank', rel: 'noopener noreferrer', style: S.link }, '② 下载并安装客户端'),
+            h('button', { style: S.btn, disabled: busy || !mesh.length || proxy.running, onClick: () => run('start') }, proxy.running ? '③ 端口已开' : '③ 回到上面开端口'),
+          ),
+          h('div', { style: S.hint },
+            '注册后进控制台「设备管理 → 成员列表」，给每台设备建一个成员账号（子账号），客户端用子账号登录。',
+            ' 同一个账号同时登两台会互相顶掉；虚拟 IP 属于成员账号，不是在客户端里手填的。',
+          ),
+        ),
+      )
+    }
+
+    function apply(ctx) {
+      const slots = ctx.slots
+      const disposers = []
+      try {
+        disposers.push(
+          slots.inject('sidebar.panellist', () =>
+            slots.register({ name: 'sidebar.panellist', id: PANEL_ID, order: 60, label: () => '组网访问' }, Icon),
+          ),
+        )
+        disposers.push(slots.inject('main', () => slots.register({ name: 'main', key: PANEL_ID }, Panel)))
+      } catch (error) {
+        console.warn('[dsh-mesh-access] 面板注册失败：', error)
+      }
+      ctx.effect(() => () => {
+        for (const dispose of disposers.splice(0)) {
+          try {
+            dispose()
+          } catch {
+            /* ignore */
+          }
+        }
+      }, 'dsh-mesh-access: ui')
+    }
+
+    exports.apply = apply
+    exports.inject = ['slots']
+    return module.exports
+  },
+})

package/lib/index.js

@@ -0,0 +1,305 @@
+/**
+ * dsh-mesh-access — 把运行中的 DSH Web 暴露到组网网卡上（进程内反代）。
+ *
+ * 为什么是插件：`dsh web --host` 只接受一个具体网卡地址，插件改不了自己进程的监听，
+ * 但插件可以在组网地址上再开一个监听，把请求转给自己进程已经在跑的那个端口 —— 
+ * 于是手机和电脑是同一个实例、同一份会话状态。
+ *
+ * 宿主侧只做三件事：
+ *   1. 找出组网网卡（StarVPN / utun* / tap* / tun* / wg* / gpd* / ppp*）上的 IPv4
+ *   2. GET /api/dsh-mesh-access/status   看状态
+ *   3. POST /api/dsh-mesh-access/proxy   启停反代（{action:'start'|'stop', port?}）
+ */
+import os from 'node:os'
+import http from 'node:http'
+import net from 'node:net'
+
+export const name = 'dsh-mesh-access'
+export const inject = ['webServer', 'connection']
+
+const REFERRAL = 'https://starvpn.cn/register.html?referralCode=Kurali'
+
+/** 可调项（写在 profile 的 cordis.patch.yml 里，缺省值如下；不引入 schema 依赖）：
+ *
+ *   - id: mesh
+ *     name: dsh-mesh-access
+ *     config:
+ *       interfacePattern: '^(StarVPN|utun\\d+|tap\\d+|tun\\d+|wg\\d+|gpd\\d+|ppp\\d+|ipsec\\d+)$'
+ *       addressPrefix: '192.168.'
+ *       proxyPort: 3081
+ *       upstream: 127.0.0.1
+ */
+
+const asText = (v, fallback) => (typeof v === 'string' && v.length > 0 ? v : fallback)
+const asPort = (v, fallback) => {
+  const n = Number(typeof v === 'object' && v !== null && 'value' in v ? v.value : v)
+  return Number.isInteger(n) && n > 0 && n < 65536 ? n : fallback
+}
+
+/** 找出组网候选地址。 */
+function findMesh(pattern, prefix) {
+  let re
+  try {
+    re = new RegExp(pattern)
+  } catch {
+    re = /^(StarVPN|utun\d+)$/
+  }
+  const found = []
+  for (const [iface, addrs] of Object.entries(os.networkInterfaces())) {
+    for (const a of addrs ?? []) {
+      const v4 = a.family === 'IPv4' || a.family === 4
+      if (!v4 || a.internal) continue
+      if (!re.test(iface)) continue
+      if (prefix && !a.address.startsWith(prefix)) continue
+      found.push({ iface, address: a.address, netmask: a.netmask })
+    }
+  }
+  return found
+}
+
+function json(res, code, body) {
+  const text = JSON.stringify(body, null, 2)
+  res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(text)
+}
+
+function readBody(req, limit = 8 * 1024) {
+  return new Promise((resolve) => {
+    let size = 0
+    const chunks = []
+    req.on('data', (c) => {
+      size += c.length
+      if (size > limit) return req.destroy()
+      chunks.push(c)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', () => resolve(''))
+  })
+}
+
+/**
+ * 进程内反代：监听组网地址，把请求转给本进程的 Web 服务器。
+ * Host 改写成上游 authority —— dsh 的 /api 信任栅栏比对的是 Host，
+ * 而 cookie 里的 authority 也按这个 Host 签发，两边一致才不会互相打架。
+ */
+function createProxy({ listenAddress, listenPort, upstream, upstreamPort }) {
+  const target = `${upstream}:${upstreamPort}`
+  const rewrite = (headers) => {
+    const h = { ...headers }
+    h.host = target
+    h['x-forwarded-host'] = headers.host ?? ''
+    h['x-forwarded-proto'] = 'http'
+    return h
+  }
+
+  const server = http.createServer((req, res) => {
+    const up = http.request(
+      { host: upstream, port: upstreamPort, method: req.method, path: req.url, headers: rewrite(req.headers) },
+      (r) => {
+        res.writeHead(r.statusCode ?? 502, r.headers)
+        r.pipe(res)
+      },
+    )
+    up.on('error', (err) => {
+      if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' })
+      res.end(`dsh-mesh-access: 上游不可达（${target}）：${err.message}\n`)
+    })
+    req.pipe(up)
+  })
+
+  // WebSocket / HTTP upgrade：裸 socket 双向转发（DSH 的实时通道靠它）
+  server.on('upgrade', (req, socket, head) => {
+    const up = net.connect(upstreamPort, upstream, () => {
+      const lines = [`${req.method} ${req.url} HTTP/1.1`]
+      for (const [k, v] of Object.entries(rewrite(req.headers))) {
+        if (v === undefined) continue
+        for (const one of Array.isArray(v) ? v : [v]) lines.push(`${k}: ${one}`)
+      }
+      up.write(lines.join('\r\n') + '\r\n\r\n')
+      if (head?.length) up.write(head)
+      up.pipe(socket)
+      socket.pipe(up)
+    })
+    const bye = () => {
+      up.destroy()
+      socket.destroy()
+    }
+    up.on('error', bye)
+    socket.on('error', bye)
+    up.on('close', bye)
+    socket.on('close', bye)
+  })
+
+  // 记下每一条连接：DSH 的实时通道是长连接，server.close() 会一直等它们，
+  // 所以关闭时必须能主动把 socket 干掉，否则 stop()/start() 会永久挂住。
+  const sockets = new Set()
+  server.on('connection', (socket) => {
+    sockets.add(socket)
+    socket.on('close', () => sockets.delete(socket))
+  })
+  server.killConnections = () => {
+    for (const socket of sockets) socket.destroy()
+    sockets.clear()
+  }
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(listenPort, listenAddress, () => {
+      server.removeListener('error', reject)
+      server.on('error', () => {})
+      resolve(server)
+    })
+  })
+}
+
+export function apply(ctx, config = {}) {
+  const cfg = {
+    interfacePattern: asText(config.interfacePattern, '^(StarVPN|utun\\d+|tap\\d+|tun\\d+|wg\\d+|gpd\\d+|ppp\\d+|ipsec\\d+)$'),
+    addressPrefix: typeof config.addressPrefix === 'string' ? config.addressPrefix : '192.168.',
+    proxyPort: asPort(config.proxyPort, 3081),
+    upstream: asText(config.upstream, '127.0.0.1'),
+  }
+
+  const state = { server: null, address: null, port: null, startedAt: null, error: null }
+
+  const upstreamPort = () => ctx.webServer?.port ?? null
+
+  /**
+   * 给组网地址补上本进程的 launch token。
+   * 插件拿不到 token 明文，但 connection 服务公开了 authenticatedUrl()，正是
+   * `dsh web` 打印地址时用的那一条，所以这里借用它，而不是自己造 token。
+   */
+  const signed = (baseUrl) => {
+    if (!baseUrl) return null
+    try {
+      return ctx.connection?.authenticatedUrl?.(baseUrl) ?? baseUrl
+    } catch {
+      return baseUrl
+    }
+  }
+  const snapshot = () => {
+    const mesh = findMesh(cfg.interfacePattern, cfg.addressPrefix)
+    const port = upstreamPort()
+    const running = Boolean(state.server)
+    const address = state.address ?? mesh[0]?.address ?? null
+    const listenPort = state.port ?? cfg.proxyPort
+    return {
+      ok: true,
+      now: Date.now(),
+      host: { upstream: cfg.upstream, port },
+      interfaces: Object.entries(os.networkInterfaces())
+        .flatMap(([iface, addrs]) => (addrs ?? []).filter((a) => (a.family === 'IPv4' || a.family === 4) && !a.internal).map((a) => ({ iface, address: a.address })))
+        .filter((x) => !cfg.addressPrefix || x.address.startsWith(cfg.addressPrefix)),
+      mesh,
+      proxy: {
+        running,
+        address,
+        port: listenPort,
+        target: port ? `${cfg.upstream}:${port}` : null,
+        url: running && address ? signed(`http://${address}:${listenPort}/`) : null,
+        urlPlain: running && address ? `http://${address}:${listenPort}/` : null,
+        startedAt: state.startedAt,
+        error: state.error,
+      },
+      referral: REFERRAL,
+    }
+  }
+
+  /** 关掉一个代理服务：先拒绝新连接，再强断旧连接，最多等 500ms，绝不挂死。 */
+  async function closeServer(server) {
+    if (!server) return
+    const closed = new Promise((resolve) => server.close(() => resolve()))
+    try {
+      server.closeAllConnections?.()
+      server.killConnections?.()
+    } catch {
+      /* 尽力而为 */
+    }
+    await Promise.race([closed, new Promise((resolve) => setTimeout(resolve, 500))])
+  }
+
+  async function start(port) {
+    const target = upstreamPort()
+    if (!target) return { ok: false, error: '上游端口未知：Web 服务器还没绑定？' }
+    const mesh = findMesh(cfg.interfacePattern, cfg.addressPrefix)
+    if (mesh.length === 0) {
+      return { ok: false, error: `没找到组网网卡（正则 ${cfg.interfacePattern}，前缀 ${cfg.addressPrefix || '不限'}）。先把星空/Tailscale/WireGuard 连上。` }
+    }
+    const listenPort = port ?? state.port ?? cfg.proxyPort
+    // 已经在这个端口上跑着，就直接返回现状 —— 重复点「开端口」不该重启监听，
+    // 否则会先关后开，中间那一刀很容易把手机上的长连接切死。
+    if (state.server && state.port === listenPort) return { ok: true, ...snapshot() }
+    if (starting) return starting
+    starting = run(listenPort, mesh, target)
+    try {
+      return await starting
+    } finally {
+      starting = null
+    }
+  }
+
+  let starting = null
+  async function run(listenPort, mesh, target) {
+    if (state.server) {
+      const old = state.server
+      state.server = null
+      await closeServer(old)
+    }
+    const address = mesh[0].address
+    try {
+      state.server = await createProxy({ listenAddress: address, listenPort, upstream: cfg.upstream, upstreamPort: target })
+      state.address = address
+      state.port = listenPort
+      state.startedAt = Date.now()
+      state.error = null
+      ctx.logger?.info?.(`dsh-mesh-access: ${address}:${listenPort} → ${cfg.upstream}:${target}`)
+      return { ok: true, ...snapshot() }
+    } catch (err) {
+      state.server = null
+      state.error = String(err?.message ?? err)
+      return { ok: false, error: state.error }
+    }
+  }
+
+  async function stop() {
+    const server = state.server
+    state.server = null
+    state.startedAt = null
+    if (!server) return { ok: true, ...snapshot() }
+    await closeServer(server)
+    state.error = null
+    return { ok: true, ...snapshot() }
+  }
+
+  ctx.effect(() => {
+    const routes = [
+      {
+        kind: 'exact',
+        path: '/api/dsh-mesh-access/status',
+        handler: (req, res) => json(res, 200, snapshot()),
+      },
+      {
+        kind: 'exact',
+        path: '/api/dsh-mesh-access/proxy',
+        handler: async (req, res) => {
+          if (req.method !== 'POST') return json(res, 405, { ok: false, error: 'POST only' })
+          let body = {}
+          try {
+            body = JSON.parse((await readBody(req)) || '{}')
+          } catch {
+            return json(res, 400, { ok: false, error: 'body 不是合法 JSON' })
+          }
+          const action = String(body.action ?? '')
+          if (action === 'start') return json(res, 200, await start(body.port ? Number(body.port) : undefined))
+          if (action === 'stop') return json(res, 200, await stop())
+          return json(res, 400, { ok: false, error: "action 只能是 'start' 或 'stop'" })
+        },
+      },
+    ]
+    const disposers = routes.map((route) => ctx.webServer.register(route))
+    return () => {
+      for (const d of disposers) d()
+      void stop()
+    }
+  }, 'dsh-mesh-access: routes + proxy')
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "dsh-mesh-access",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Expose the DSH web UI on a mesh/VPN interface (StarVPN, Tailscale, WireGuard tun) from inside the running server: in-process reverse proxy + status panel, so any device on the mesh — phone, laptop, NAS — opens it in a browser. No second instance.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "icon.svg",
+    "README.md",
+    "README.en.md",
+    "INSTALL.md",
+    "INSTALL.en.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs",
+    "screenshots.json",
+    "assets"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.2.1-rc.2"
+  },
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.2.1-rc.2"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ],
+      "platform": "web"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "mesh",
+    "vpn",
+    "starvpn",
+    "tailscale",
+    "wireguard",
+    "remote-access",
+    "reverse-proxy",
+    "nas",
+    "remote-desktop"
+  ],
+  "license": "MIT",
+  "icon": "icon.svg",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SilverKurali/dsh-mesh-access.git"
+  },
+  "homepage": "https://github.com/SilverKurali/dsh-mesh-access#readme",
+  "bugs": {
+    "url": "https://github.com/SilverKurali/dsh-mesh-access/issues"
+  }
+}

package/screenshots.json

@@ -0,0 +1,3 @@
+[
+  "assets/screenshot-1.png"
+]