dsh-zen-remote 2.3.11 → 2.4.1

package/src/wizard/routes.ts

@@ -142,7 +142,7 @@ export interface WizardHandlerOptions {
    * POST mints the pairing code, GET polls the session. Absent — a wiring
    * that predates GW-9 — and both answer 501 like the placeholders. */
   verify?: {
-    start: (input: { publicUrl: unknown; probeOnly?: boolean }) => Promise<VerificationStartResult>
+    start: (input: { publicUrl: unknown; probeOnly?: boolean; allowUnprobed?: boolean }) => Promise<VerificationStartResult>
     check: () => Promise<VerificationCheckResult>
   }
 }
@@ -207,9 +207,13 @@ export function createWizardHandler(options: WizardHandlerOptions): WizardHandle
       // because a forwarded request presents as same-origin (the gateway
       // rewrites Origin/Host); the marker is the identifying signal.
       if (req.headers['x-zen-remote-via'] !== undefined) {
+        const isEn = options.getConfig().values.lang === 'en'
         responseJson(res, 403, {
           ok: false,
-          error: { code: 'via-gateway', message: '配置引导只能在服务端本机操作' },
+          error: {
+            code: 'via-gateway',
+            message: isEn ? 'Setup wizard is only available on the server machine' : '配置引导只能在服务端本机操作',
+          },
         })
         return
       }
@@ -258,11 +262,14 @@ export function createWizardHandler(options: WizardHandlerOptions): WizardHandle
         // env / row values SHADOW the file layer the persister writes: a
         // write there would silently do nothing. Refuse honestly instead.
         if (resolved.source === 'env' || resolved.source === 'row') {
+          const isEn = options.getConfig().values.lang === 'en'
           responseJson(res, 409, {
             ok: false,
             error: {
               code: 'proxy-list-shadowed',
-              message: `trustedProxies 目前由${resolved.source === 'env' ? '环境变量' : '插件行配置'}提供，请先清掉那边的值再自动信任`,
+              message: isEn
+                ? `trustedProxies is currently provided by ${resolved.source === 'env' ? 'environment variables' : 'plugin row config'} — clear that value first`
+                : `trustedProxies 目前由${resolved.source === 'env' ? '环境变量' : '插件行配置'}提供，请先清掉那边的值再自动信任`,
             },
           })
           return
@@ -277,9 +284,13 @@ export function createWizardHandler(options: WizardHandlerOptions): WizardHandle
         // quick succession must not lose either IP.
         const landed = await trust.write(resolved.value, merged)
         if (landed === false) {
+          const isEn = options.getConfig().values.lang === 'en'
           responseJson(res, 409, {
             ok: false,
-            error: { code: 'trust-list-changed', message: '信任列表刚被其他操作修改，请刷新后重试' },
+            error: {
+              code: 'trust-list-changed',
+              message: isEn ? 'Trusted proxy list was just modified — refresh and retry' : '信任列表刚被其他操作修改，请刷新后重试',
+            },
           })
           return
         }
@@ -381,7 +392,14 @@ export function createWizardHandler(options: WizardHandlerOptions): WizardHandle
             : values.ingressDomain
           const domain = hostOf(rawDomain)
           if (domain === undefined) {
-            responseJson(res, 400, { ok: false, error: { code: 'no-domain', message: '保存一个有效的公开域名后再启动' } })
+            const isEn = values.lang === 'en'
+            responseJson(res, 400, {
+              ok: false,
+              error: {
+                code: 'no-domain',
+                message: isEn ? 'Save a valid public domain before starting' : '保存一个有效的公开域名后再启动',
+              },
+            })
             return
           }
           const rawPort = typeof body?.httpsPort === 'number' && Number.isSafeInteger(body.httpsPort) && body.httpsPort >= 1 && body.httpsPort <= 65535
@@ -497,6 +515,7 @@ export function createWizardHandler(options: WizardHandlerOptions): WizardHandle
         responseJson(res, 200, await verify.start({
           publicUrl: body.publicUrl,
           ...(body.probeOnly === true ? { probeOnly: true } : {}),
+          ...(body.allowUnprobed === true ? { allowUnprobed: true } : {}),
         }))
         return
       }

package/src/wizard/status.ts

@@ -72,13 +72,21 @@ export interface WizardForwardedSourceInput {
  * fields. Token presence is reported as booleans only; port as the gateway
  * child's ACTUAL listening port (it may differ from the configured one).
  */
+export interface WizardLanCandidate {
+  ip: string
+  kind: 'tailscale' | 'lan'
+  iface: string
+}
+
 export interface WizardRuntimeInput {
   cfTokenConfigured?: unknown
   tunnelTokenConfigured?: unknown
   caddyRunning?: unknown
   cloudflaredRunning?: unknown
   gatewayActualPort?: unknown
+  gatewayActualHost?: unknown
   lanAddress?: unknown
+  lanAddresses?: unknown
   lastHostProbe?: WizardRecordInput | null
   lastExternalVerification?: WizardRecordInput | null
   lastForwardedSource?: WizardForwardedSourceInput | null
@@ -109,7 +117,9 @@ export interface WizardStatus {
   caddyRunning: boolean
   cloudflaredRunning: boolean
   gatewayActualPort: number | null
+  gatewayActualHost?: string
   lanAddress?: string
+  lanAddresses?: WizardLanCandidate[]
   lastHostProbe: WizardStatusRecord | null
   lastExternalVerification: WizardStatusRecord | null
   lastForwardedSource: WizardStatusForwardedSource | null
@@ -154,6 +164,21 @@ function forwardedSourceOf(input: WizardForwardedSourceInput | null | undefined)
   return { ip, at }
 }
 
+function lanCandidatesOf(value: unknown): WizardLanCandidate[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const out: WizardLanCandidate[] = []
+  for (const item of value) {
+    if (item === null || typeof item !== 'object') continue
+    const ip = (item as { ip?: unknown }).ip
+    const kind = (item as { kind?: unknown }).kind
+    const iface = (item as { iface?: unknown }).iface
+    if (typeof ip !== 'string' || ip === '') continue
+    if (kind !== 'tailscale' && kind !== 'lan') continue
+    out.push({ ip, kind, iface: typeof iface === 'string' ? iface : '' })
+  }
+  return out.length > 0 ? out : undefined
+}
+
 /**
  * Build the sanitized wizard status. Both arguments are optional so a
  * composition can answer before anything is configured; the all-empty
@@ -161,6 +186,7 @@ function forwardedSourceOf(input: WizardForwardedSourceInput | null | undefined)
  * no tokens configured, no memories).
  */
 export function projectWizardStatus(declared: WizardDeclaredInput = {}, runtime: WizardRuntimeInput = {}): WizardStatus {
+  const lanAddresses = lanCandidatesOf(runtime.lanAddresses)
   return {
     ok: true,
     mode: modeOf(declared.ingressMode),
@@ -172,7 +198,9 @@ export function projectWizardStatus(declared: WizardDeclaredInput = {}, runtime:
     caddyRunning: runtime.caddyRunning === true,
     cloudflaredRunning: runtime.cloudflaredRunning === true,
     gatewayActualPort: portOf(runtime.gatewayActualPort),
+    ...(typeof runtime.gatewayActualHost === 'string' && runtime.gatewayActualHost !== '' ? { gatewayActualHost: runtime.gatewayActualHost } : {}),
     ...(typeof runtime.lanAddress === 'string' && runtime.lanAddress !== '' ? { lanAddress: runtime.lanAddress } : {}),
+    ...(lanAddresses !== undefined ? { lanAddresses } : {}),
     lastHostProbe: recordOf(runtime.lastHostProbe),
     lastExternalVerification: recordOf(runtime.lastExternalVerification),
     lastForwardedSource: forwardedSourceOf(runtime.lastForwardedSource),

package/src/wizard/verify.ts

@@ -54,7 +54,7 @@ export interface VerificationManagerOptions {
 }
 
 export type VerificationStartResult =
-  | { ok: true; pairingCode: string; publicUrl: string; expiresAt: number }
+  | { ok: true; pairingCode: string; desktopPairingCode?: string; publicUrl: string; expiresAt: number; probeWarning?: unknown }
   | {
     ok: false
     reason: 'no-public-url' | 'bad-public-url' | 'runtime-not-ready' | 'gateway-unreachable' | 'probe-failed' | 'pair-refused'
@@ -75,6 +75,7 @@ export type VerificationCheckResult =
 /** What the wizard reads off one gateway status answer. */
 interface GatewayStatusView {
   deviceIds: string[]
+  deviceRoles: Map<string, string>
   port: number | null
   lastWebClaim: { id: string; secure: boolean; at: number } | null
 }
@@ -105,7 +106,7 @@ interface VerificationSession {
 }
 
 export interface VerificationManager {
-  start(input: { publicUrl: unknown; probeOnly?: boolean }): Promise<VerificationStartResult>
+  start(input: { publicUrl: unknown; probeOnly?: boolean; allowUnprobed?: boolean }): Promise<VerificationStartResult>
   check(): Promise<VerificationCheckResult>
   /** Whether a verification session is open (the route surfaces it for the
    * UI's 「待外部验证」 state). */
@@ -140,10 +141,19 @@ export function createVerificationManager(options: VerificationManagerOptions):
     if (reply === null || reply.status < 200 || reply.status >= 300) return null
     const body = reply.body as { devices?: unknown; port?: unknown; lastWebClaim?: unknown }
     if (body === null || typeof body !== 'object') return null
-    const deviceIds: string[] = Array.isArray(body.devices)
-      ? body.devices.map((device) => (device !== null && typeof device === 'object' ? (device as { id?: unknown }).id : undefined))
-          .filter((id): id is string => typeof id === 'string')
-      : []
+    const deviceIds: string[] = []
+    const deviceRoles = new Map<string, string>()
+    if (Array.isArray(body.devices)) {
+      for (const device of body.devices) {
+        if (device === null || typeof device !== 'object') continue
+        const id = (device as { id?: unknown }).id
+        const role = (device as { role?: unknown }).role
+        if (typeof id === 'string') {
+          deviceIds.push(id)
+          if (typeof role === 'string') deviceRoles.set(id, role)
+        }
+      }
+    }
     const port = typeof body.port === 'number' ? body.port : null
     const claim = body.lastWebClaim
     const lastWebClaim = claim !== null && typeof claim === 'object'
@@ -153,11 +163,11 @@ export function createVerificationManager(options: VerificationManagerOptions):
           at: typeof (claim as { at?: unknown }).at === 'number' ? (claim as { at: number }).at : 0,
         }
       : null
-    return { deviceIds, port, lastWebClaim }
+    return { deviceIds, deviceRoles, port, lastWebClaim }
   }
 
   return {
-    async start({ publicUrl, probeOnly }) {
+    async start({ publicUrl, probeOnly, allowUnprobed }) {
       if (typeof publicUrl !== 'string' || publicUrl.trim() === '') return { ok: false, reason: 'no-public-url' }
       // Same admission as the probe: https anywhere, plain http only into
       // the private-network allowances. The URL the phone will open must
@@ -171,7 +181,8 @@ export function createVerificationManager(options: VerificationManagerOptions):
       if (statusBefore === null) return { ok: false, reason: 'gateway-unreachable' }
 
       const outcome = await (options.probe ?? probeHostPath)(normalized.url)
-      if (outcome.kind !== 'reached' || outcome.root !== 'gateway-pairing-page' || outcome.admin !== 'gateway-admin-403') {
+      const probeOk = outcome.kind === 'reached' && outcome.root === 'gateway-pairing-page' && outcome.admin === 'gateway-admin-403'
+      if (!probeOk && allowUnprobed !== true) {
         return { ok: false, reason: 'probe-failed', detail: outcome }
       }
 
@@ -180,7 +191,7 @@ export function createVerificationManager(options: VerificationManagerOptions):
       }
 
       const pair = await callGateway('POST', '/lan-gate/pair', { role: 'web' })
-      const pairBody = pair?.body as { ok?: unknown; code?: unknown; expiresAt?: unknown } | undefined
+      const pairBody = pair?.body as { ok?: unknown; code?: unknown; desktopCode?: unknown; expiresAt?: unknown } | undefined
       if (pair === null || pair.status < 200 || pair.status >= 300 || pairBody?.ok !== true || typeof pairBody.code !== 'string' || typeof pairBody.expiresAt !== 'number') {
         return { ok: false, reason: 'pair-refused', detail: pair === null ? null : pair.status }
       }
@@ -192,7 +203,14 @@ export function createVerificationManager(options: VerificationManagerOptions):
         knownDeviceIds: new Set(statusBefore.deviceIds),
         fingerprint: verificationFingerprint(options.getValues(), statusBefore.port),
       }
-      return { ok: true, pairingCode: session.code, publicUrl: session.publicUrl, expiresAt: session.expiresAt }
+      return {
+        ok: true,
+        pairingCode: session.code,
+        ...(typeof pairBody.desktopCode === 'string' && pairBody.desktopCode !== '' ? { desktopPairingCode: pairBody.desktopCode } : {}),
+        publicUrl: session.publicUrl,
+        expiresAt: session.expiresAt,
+        ...(probeOk ? {} : { probeWarning: outcome }),
+      }
     },
 
     async check() {
@@ -220,6 +238,10 @@ export function createVerificationManager(options: VerificationManagerOptions):
           if (isHttps && !claim.secure) return { result: 'cookie-insecure', deviceId }
           return { result: 'pass', deviceId, at: claim.at }
         }
+        if (status.deviceRoles.get(deviceId) === 'desktop-client') {
+          session = null
+          return { result: 'pass', deviceId, at: now() }
+        }
         // A claim record that has not surfaced (or names a different,
         // later claim): keep polling rather than bless an unverified cookie.
         return { result: 'pending' }

package/AGENTS.md

@@ -1,185 +0,0 @@
-# AGENTS.md — dsh-zen-remote
-
-单一 npm 包 `dsh-zen-remote`，DSH（DeepSeek Harness）的 bundle 插件。
-一个包里有两半代码，但**对用户是一个插件**：文档、安装说明、README 都不要
-再按「两个包」叙述（2026-08-17 由 monorepo 的 `packages/gateway` +
-`packages/mobile-ui` 合并而来，包名 `dsh-mobile-pwa` 与
-`@dsh-external/dsh-mobile-nav` 已作废）。
-
-## 目录
-
-| 路径 | 作用 |
-| --- | --- |
-| `package.json` | 单包声明：`dsh.bundle.patch` → `cordis.patch.yml`，`dsh.client` → `exports["./client"]` |
-| `cordis.patch.yml` | 组合层，**一行** insert（`dsh-zen-remote`），随包自带；网关与推送由主入口按角色加载，不再各占一行 |
-| `src/index.ts` → `lib/index.js` | 主入口（插件行 `dsh-zen-remote`）：读 `role`，host 就 `ctx.plugin()` 加载网关与推送子插件，并挂 host 路由（附件上传 / 客户端配置 / 分享导出 / 管理 / 子客户端 / 中继） |
-| `src/config.ts` | 配置模型：四层回退（env > 插件行 > `lan-gate.config.json` > 默认值）、loader 的 `Config` schema（全 volatile）、`resolveRole` |
-| `src/http.ts` | host 路由共用的 JSON 响应封装与同源 POST 门 |
-| `src/admin-routes.ts` | 设置页管理后端 `/_dsh/zen-remote/admin/*`：代调网关本机 API（配对 / 设备 / 测试推送）+ 共享开关 |
-| `src/client-routes.ts` | 子客户端路由 `/_dsh/zen-remote/client/*`：remote-status（两角色都挂，host 只应答这一条、其余 404）、配对代理、设置页诊断、plain-HTTP 转发 `client/http/*`（改动摘要 / diff）、`debug-report`（脱敏诊断报告，via 墙先于分派，CU-3） |
-| `src/client-pairing.ts` | 子客户端配对纯逻辑：服务端地址归一化（http 仅限内网段）、claim/探针结果分类 |
-| `src/share-store.ts` | 共享会话表（`~/.dsh/zen-remote-shares.json`，持久化，重启恢复），中继访问控制的事实来源 |
-| `src/activity.ts` | 会话活动统计 + 闲置休眠扫描（`idleHours`，运行中/等待中不计时） |
-| `src/share-ops.ts` | `agent/created` 的自动共享 / 分叉跟随 / busy 恢复 |
-| `src/share-export.ts` | 分享图路由 `GET /_dsh/mobile-nav/share-export`（完整日志折叠人类转写） |
-| `src/relay-server.ts` | 服务端中继路由 `/_dsh/zen-remote/relay/*`：ping / handshake / invoke / NDJSON stream / event-result / `v1/http`（改动摘要 / diff 的 plain-HTTP 直通，进程内交宿主 `/api` 共享 handler）/ `v1/upload`（远程会话附件字节转宿主暂存，返回回执）/ unshare |
-| `src/relay-access.ts` | 中继的按方法登记访问控制表（服务端那一张；`v1/http` 的按路由登记表也在这里） |
-| `src/relay-filter.ts` | 全局流与全局列表的输出过滤（`workspace/follow` / `session/control` / `session/list` / @ 引用候选行） |
-| `src/session-reference.ts` | 两端共用的 `dsh-session:` 引用编解码与「可注入文本」扫描规则（prompt content、排队消息 edit、`commands/execute` 全部字符串）：服务端照它校验、子客户端照它改写，同一份规则防两端漂移 |
-| `src/relay-client.ts` | 子客户端中继客户端：握手、接口指纹比对、退避重连、吊销识别 |
-| `src/intercept.ts` | 子客户端本机拦截：包装 `typertGateway`，远程会话调用改走中继、虚拟 id 改写、面板判定（客户端那张字段表也在这里） |
-| `src/intercept-shape.ts` | 被包装方法的形态检测，不符即拒绝安装远程拦截（本地行为不受影响） |
-| `src/plugin-bridge.ts` | 插件桥纯逻辑（PB-1）：桥接声明校验/规范化与 16 位摘要、`zenRemote` 注册表、两端比对 `compareBridges`；不 import DSH、不碰 I/O |
-| `src/plugin-loopback.ts` | 插件桥回环执行器（PB-3）：本机回环 GET 插件路由，token 换 cookie（401 重换一次），cookie 只存内存；https 仅对字面 127.0.0.1 放宽证书校验 |
-| `src/plugin-route-intercept.ts` | 子客户端改道（PB-4）：包装宿主 webServer 的 `match`，声明命中的虚拟 id 请求改走 `relay.pluginRequest`；未桥接一律统一 503（`x-zen-remote: unbridged`），绝不落本机插件 |
-| `src/plugin-adapter-core.ts` | 适配器框架核心（PB-11）：适配器路由/定位器的校验、三种定位（query/路径段/JSON 体）的「远程/本地/混合」判定与双向改写、适配器摘要与让位判定；纯逻辑，框架两半只 import 这里 |
-| `src/adapters/` | 适配器目录（PB-11）：`index.ts` 只导出 `ADAPTERS` 数组（本单为空，PB-12 加第一个），`types.ts` 放适配器作者接口，实现各占一个子目录；**除 `src/index.ts` 接线外任何文件不得 import 此目录**，适配器实现只可 import `types.ts` 与纯工具 |
-| `src/client-data/plugin-bridge.ts` | 设置页纯函数（PB-5）：桥接状态 → 文案键、整机数据同意表的切换（只动一键）；浏览器半边，不 import 主包 |
-| `src/fetch-route-intercept.ts` | 子客户端本机拦截的第二半：包装宿主连接服务 `fetchRoutes` 表的上传与导出两项——远程会话的非图片附件经 `relay/v1/upload` 流式转服务端（超限本地拒、失败回宿主自己的 200 失败信封）、虚拟 id 的导出后台 403（形态检测、懒装重试、卸载守卫） |
-| `src/virtual-id.ts` | `zr~<serverId>~<id>` 虚拟 id 算术（纯函数、零依赖；client-data 半边许可 import 它做 zr~ 判定，先例 remote-drop.ts / remote-status.ts） |
-| `src/log-ring.ts` | 诊断导出用内存日志环（CU-1）：上限 300 条、进程内不落盘；index.ts 两分支的 logWarn/logInfo 收口双写（ctx.logger + 环），生命周期事件（row apply/reload、网关 spawn/exit、relay online/offline、fetch-route 安装含 via）push 进环 |
-| `src/debug-report.ts` + `src/debug-redact.ts` | 诊断报告装配与脱敏器（CU-2，纯逻辑零 DSH import）：装配 getter 注入拼 `_meta/config/status/gateway/logs` 五板块、配置按字段名挑选（秘密构造性缺席）；脱敏器 URL 走**哨兵摘出-还原**（userinfo→`<token>@`、host→地址类型、端口与 path 保留、query 长值单独 token 化）、家目录折叠先于 token 趟；`scripts/check-debug-report.mjs` 真值表钉住全部形态（含哨兵伪造） |
-| `src/merge-streams.ts` | 三条全局流/列表的本地 + 远程合并状态机（侧边栏远程分组） |
-| `src/fingerprint.ts` | DSH 接口指纹：规范化描述符 → 分组 JSON Schema 哈希，供握手比对 |
-| `src/restart-fields.ts` / `restart-watcher.ts` | 需重启字段的指纹监测，变化即重载插件行 |
-| `src/client/**` → `lib/client.js` | 浏览器半边（同一插件行，经 `dsh.client` 发现）：app 外壳、slot、样式、设置区块（`settings/`）、共享与远程部件（`remote-*` / `Remote*`） |
-| `src/client-data/current-session.ts` + `src/client/current-session-report.ts` | 当前会话信号的浏览器上报（T62）：拦截层在后台进程读不到浏览器 localStorage，由浏览器端解析宿主选择存储、值变化时 POST 到 `client/current-session` 路由；纯函数（解析 + 变化判定）与上报循环分居两文件 |
-| `src/client-data/remote-group-expansion.ts` + `src/client/remote-group-expansion.ts` | 服务端分组展开状态的记忆与恢复（T64）：宿主 retainAccountKeys 每次加载都清掉 zr~ 分组的展开记录，浏览器端把宿主记录镜像进自己的存储键、宿主清掉后按记录（默认展开）点击行恢复；纯函数（规划 + 解析 + 上限淘汰）与 keeper 循环分居两文件 |
-| `lan-gate.mjs` | 网关子插件入口，由主入口按 host 角色加载（不再自己占插件行）：spawn 子进程，共享密钥只经它进子进程 |
-| `lib/lan-gate-server.cjs` | 网关本体（独立 Node 子进程，Node stdlib + `web-push`）：设备角色、标记头与共享密钥、desktop-client 只放行中继前缀 |
-| `dsh-push.mjs` | 推送子插件（与网关一起由主入口加载）：回合结束推送 + `push_notify` 工具 |
-| `pwa/**` | manifest / service worker / 注入脚本 / 手势 / 壳级 CSS / 图标 |
-| `test/*.test.cjs` | 网关侧测试（真子进程 + mock 上游）+ 中继端到端（`relay-e2e.test.cjs`）+ 纯逻辑导入测试 |
-| `scripts/check-*.mjs` | 界面侧自检（纯 `node:assert`，靠 Node ≥23.6 类型剥离直接 import `.ts`） |
-| `scripts/build-client.mjs` | client 打包器（内联相对模块 → `__ModuleLoader__.load({id:"dsh-zen-remote"})`） |
-| `docs/**` | 深度文档，见下 |
-
-## 命令
-
-```sh
-pnpm install
-pnpm build     # tsc host + tsc client + build-client.mjs → lib/（产物入库，改 src/ 必须重跑并提交 lib/）
-pnpm verify    # 两个 tsconfig 的 --noEmit 类型检查
-pnpm test      # 网关 node:test 用例 + 三个界面自检脚本 + 文档版本号一致性检查，一条命令全跑
-```
-
-**版本号**：两份 README（`README.md` 英文为主文档，`README.zh-CN.md` 中文）里的
-release 徽章和 profile 依赖示例由 `scripts/sync-doc-version.mjs` 按 `package.json`
-改写，挂在 `version` 生命周期脚本上——`npm version patch` 会把改好的两份 README
-带进同一个发版提交，不用手改
-（徽章曾经一路卡在 v1.0.0 到 1.0.2）。`pnpm test` 里的 `--check` 会在漏同步时
-把测试挂掉。文档里的锚点变了就更新那个脚本：找不到标记它直接非零退出，不会
-默默通过。
-
-**发版**：全部由 tag 驱动，本地只做一步。
-
-```sh
-npm version patch      # 改 package.json + 同步两份 README + 建 commit 和 v* tag
-git push --follow-tags # 推 tag 才是真正的触发器
-```
-
-推上去之后 `.github/workflows/publish.yml` 依次做：装依赖 → `pnpm build` →
-**`git diff --exit-code -- lib`**（入库产物必须与重新构建的结果一致，挡住
-「改了 src 忘了 build 就打 tag」）→ `pnpm verify` → `pnpm test` →
-tag 名与 `package.json` 版本一致性 → `pnpm publish`（npm Trusted Publishing，
-OIDC 无令牌，provenance 自动生成）→ **建 GitHub Release**。
-
-Release 那步刻意排在 npm 之后：它宣告的是「这个版本已经发出去了」，npm 失败就
-不该留下一个指向不存在版本的发布页。正文来源见下方 CHANGELOG 段（该版本的那一
-段 + 自上一版本以来的全部提交）；这一步可重入（先 `gh release view` 查在不在，
-在就跳过），重跑失败的 workflow 不会因为 Release 已存在而挂掉。checkout 带
-`fetch-depth: 0`（提交列表要全历史）。
-
-CHANGELOG（2026-11-02 起有 `CHANGELOG.md`）：只记用户可感知的变化，未发布段落
-攒着待发内容；**发版前**把「未发布」标题改成该版本号 + 日期，随 `npm version
-patch` 的 version commit 一起提交（脚本只同步 README 徽章，CHANGELOG 是手动步）。
-此前「提交信息就是 changelog、不另维护文件」的约定作废。GitHub Release 正文
-**就是 CHANGELOG 里该版本的那一段**（workflow 用同一条 awk 提取，缺段会在 npm
-发布前被守卫挡下），其下自动附「自上一版本以来的全部提交」（git log 现算，
-不再用 `--generate-notes`——它无法与 --notes-file 共存，且正文来源要可预测）。
-
-需要人工配置的只有一处：npmjs.com 的包设置里登记可信发布者
-`KyoMio/dsh-zen-remote` + 文件名 `publish.yml`。GitHub Release 那步用的是
-workflow 自带的 `GITHUB_TOKEN`，不需要额外密钥——但 job 的 `permissions` 里
-`contents` 必须是 `write`（原来是 `read`）。
-
-## 深度文档
-
-| 文件 | 内容 |
-| --- | --- |
-| [`docs/remote-access.md`](docs/remote-access.md) | 通道半边：反代配置（nginx/Caddy/Lucky）、设备角色与配对、环境变量表、管理 API、远程中继协议、推送、安全边界 |
-| [`docs/interface.md`](docs/interface.md) | 界面半边：断点策略、设置区块与远程部件、调试徽章、安全区体系、兼容插件清单 |
-
-
-## 合仓后仍然成立的硬约束
-
-- **网关是子进程**：`lan-gate.mjs` 只负责 spawn + 生命周期，永远不要把
-  `lib/lan-gate-server.cjs` import 进 DSH 进程。
-- **中继共享密钥不落地**：主入口每次 apply 现生成 `LAN_GATE_RELAY_SECRET`，
-  只经环境变量交给网关子进程（无条件覆盖、缺失即删除），中继路由逐请求
-  `timingSafeEqual` 校验。不允许由外部环境指定，也不要把它写进日志或状态文件。
-- **中继访问控制按方法登记，两张表同步**：新增远程方法必须同时登记
-  `src/relay-access.ts` 的 `RELAY_METHODS`（服务端，授权看登记的归属字段）
-  和 `src/intercept.ts` 的 `CLIENT_METHOD_FIELDS`（客户端，改写判定），
-  一致性由 `test/intercept.test.cjs` 的逐方法比对测试钉住。插件桥的授权另走一条：声明注册表 + 路径完全相等 + 会话共享（`src/plugin-route-intercept.ts` / relay 的 `/v1/plugin`），同样不扫描参数；
-  禁止「从参数里
-  通用扫描会话 id」的写法——DSH 会悄悄丢掉不认识的参数名，扫描会被诱饵
-  字段骗过；全局读（`session/list` 等）安全靠输出过滤，不靠输入判定。
-- **适配器必须可插拔**：`src/adapters/` 整个目录删掉后其余功能一字不改——
-  框架只消费 `src/plugin-adapter-core.ts`（在适配器目录之外），接线只有
-  `src/index.ts` 一处 import `./adapters/index`，`createRelayHandler` /
-  `installPluginRouteIntercept` / admin 列表的适配器参数全部缺省空；改
-  框架两半时不得新增对适配器目录的 import（`test/adapters-pluggable.test.cjs`
-  的静态扫描钉住）。适配器让位规则：插件自己登记的协作声明永远优先，
-  运行时逐请求核对注册表摘要。
-- **桌面端请求没有 `Origin`/`Sec-Fetch-Site`**：DSH 桌面端主进程把窗口请求
-  转发给本机后台前，自己校验过 `Origin: dsh-app://app`，然后删掉
-  `host` / `origin` / `cookie` / `sec-fetch-site`。所以 `src/http.ts` 的
-  `sameOriginPost` 对「两个头都缺」的请求是**放行**的（`admit` 顶在前面）；
-  别把它改成「缺 Origin 即拒绝」，那会把桌面端窗口里的所有变更请求挡掉。
-  真正要拒的是可辨认的跨站（`Sec-Fetch-Site: cross-site`、Origin 与 Host 不符）。
-- **volatile 字段在使用时现场读取**：`Config` 的每个字段都是 volatile——
-  loader 交给 `apply()` 的是 `{ get() }` 包装而不是值。任何读行配置的地方
-  都要走 `unwrapVolatile`（单字段）或 `resolveConfig`（整组），禁止在
-  apply 时拍快照存着用；`RESTART_FIELDS` 之外的字段（`serverName`、
-  `idleHours`、`serverUrl`、`deviceToken`、界面旋钮）改了不重载行，
-  不现场读就是永久拿到旧值。
-- **CSS 分工没变**：排版类规则在 `src/client/styles/`；`pwa/app.css` 只留壳级
-  规则（iOS 输入框防缩放、安全区滚动补偿、代码块横向滚动）。两边抢同一个元素
-  是历史事故的根源，加规则前先确认归属。
-- **`lib/` 是产物，不手改**：改 `src/` → `pnpm build` → 提交 `lib/`。**删 src 时必须手动 `git rm` 对应 lib 产物**：tsc 只增量写、从不清理已删源文件的旧产物，CI 的 `git diff --exit-code -- lib` 关卡对死产物全盲（2026-10-24 PR #34 吸收剥离踩过，靠对抗审查拦下）。
-- **桌面必须 no-op**：≥1024px 逐像素与未安装时一致。
-  是从真机事故里攒出来的，改相关代码前先读。
-- **首帧壳只能内联注入**：冷启动占位壳由网关 `injectBootShell` 写进第一帧
-  HTML（`BOOT_SHELL_*`），DSH 一往 `#root` 渲染就同步摘掉。壳的 CSS/标记/脚本
-  都是网关里的内联常量（不放进 `pwa/app.css` 或客户端样式），带 30s CSS 渐隐
-  兜底；移除脚本有真实 vm 用例（DCL / 晚渲染 / `#root` 缺失 / 保险丝）。不能
-  挪进客户端插件——那个 bundle 正是首帧要等的东西；不能引入额外请求；显式
-  `desktop` 设备不注入、≥1024px 由 CSS 隐藏。`test/gateway.test.cjs` 钉住。
-- **长缓存只给内容寻址 URL**：网关只给 `/assets/` 下**哈希形状**（8+ 位且含
-  数字或大小写混合，排除 `vendor-bootstrap.css` 这类普通词）、且响应不是 HTML
-  的文件补 `immutable`（上游已有缓存头时让上游说话）；service worker 只对同一
-  判定与 `?rev=<hex 构建修订>`（DSH 按 mtime/ctime/size 生成，且 DSH 自己已
-  按 immutable 提供）的插件批次缓存优先；响应类型必须与 URL 声明一致，
-  HTML/错误页不得存进资源缓存。给无哈希 URL 做长缓存就是重演 v2 的「新 DOM + 旧 CSS」事故。
-- **要藏宿主刚渲染出来的东西，别用 `requestAnimationFrame`**：React 在该帧的
-  rAF 阶段之后才提交 DOM，所以从 mutation 里排的 rAF 落在**下一帧**——中间那
-  一帧已经画到屏幕上，用户就看见闪。两个月内三次「晚一帧」的 bug（2026-08-18
-  回复要等回合结束才出现、08-22 工具调用行先显后折、08-25 issue #3 流式抖动）
-  都是这个根子。两条出路：能用选择器表达的交给样式表（`turn-fold.css.ts` 的
-  `BORN_FOLDED`，读宿主自己的 `data-chat-flow-kind` / `data-variant`，React
-  插入节点的同一次提交里就带着，第一帧就是隐藏的）；表达不了的放进
-  MutationObserver 回调里同步做（`turn-fold.ts` 的 `markWholeRows`）——回调是
-  微任务，跑在这一帧渲染更新之前，两个方向都不会晚。rAF 只留给能容忍晚一帧的
-  活（全量重扫、插 chip、改文案）。
-- **别用 `:has()` 写死宿主的 DOM 层数**：包裹层数不等于组件源码看上去的层数
-  ——槽位会额外套一层（真实是 `flowItem > seat > AssistantMarkdown root >
-  body > 块`，比组件自身结构多一层）。深度猜错的选择器**静默失效**：测试全绿、
-  控制台干净，只有拿真界面量才看得出来。需要结构判断就用 JS 遍历
-  （`foldsWholeRow` 那种沿父节点上溯的写法），不假设层数。
-- **同机联调必须用局域网 IP 连网关**：回环地址且无转发头的请求被网关判定为「本机直连」，不校验设备令牌——同一台机器上同时跑服务端与子客户端做开发测试时，`serverUrl` 要填局域网 IP 而不是 `127.0.0.1` / `localhost`。只影响这种同机开发测试，日常两台机器（子客户端经内网/公网地址连服务端）的使用不受影响。
-- **改了界面就去真界面上量**：`turn-fold` 这类规则用自建的静态页面验证会给出
-  假阳性（合成 DOM 猜不对宿主的包裹层）。打开 `127.0.0.1:3080` 读现有会话的
-  `getComputedStyle` 即可，**不要为了验证去建会话或发消息**（耗真实 token，见
-  工作区 AGENTS.md 的硬约束）。注意浏览器标签在后台时 rAF 不触发，chip 会是 0
-  个——那是观测假象，不是回归，截图把窗口唤到前台再看。

package/docs/adr/0001-plugin-bridge-forwards-plugin-routes.md

@@ -1,15 +0,0 @@
-# 插件桥转发插件自己的 HTTP 接口，主服务端以本机回环请求执行
-
-远程会话里要显示其他插件的面板时，插件桥不转发界面、也不定义统一的数据模型，而是把插件自己注册在 DSH webServer 上的接口请求，从子客户端改道到主服务端：子客户端在本机后台的路由查找处改道（覆盖 fetch、EventSource、iframe、Worker 等一切到达后台的 HTTP），主服务端校验会话共享后，以本机回环 HTTP 请求自己的插件接口。理由：面板界面两端同版本已经有，插件接口也已经存在，zen-remote 只需决定「请求在哪台机器执行」；回环请求让插件自己的鉴权与 handler 原样生效，不必伪造 node 的 req/res。
-
-## Considered Options
-
-- 包装浏览器的 `window.fetch`：漏掉 iframe、Worker、EventSource 发出的请求。
-- 主服务端进程内直接调插件 handler：插件 handler 是 node req/res 签名且自查 Host 与 cookie，伪造 IncomingMessage 比回环脆弱。
-- 定义统一的插件数据模型、让插件把数据推给 zen-remote：要求每个插件重写数据层，第三方插件无法接入。
-
-## Consequences
-
-- 协作插件只需登记接口清单，并在网址参数里带会话 id；不需要依赖 zen-remote 的代码。
-- 不配合的第三方插件只能由 zen-remote 内部按确切版本编写可移除的适配器，负责请求与响应里会话 id 的改写。
-- 子客户端的改道依赖宿主 webServer 的内部结构（路由查找方法、路由表），与 typertGateway、fetchRoutes 的包装同属「依赖 DSH 内部」的一类，需要形态检测。

package/docs/adr/0002-relay-emulates-websocket.md

@@ -1,8 +0,0 @@
-# 中继不引入 WebSocket，插件的 WebSocket 用流式响应加普通请求模拟
-
-插件桥要转发 better-sidebar 的两条 WebSocket（「文件变动」与「智能体打开文件」）时，沿用中继的既有约定「单次调用走普通 HTTP 请求、订阅走 NDJSON 流式响应、不自己实现 WebSocket」：子客户端后台在本机接住浏览器的 WebSocket，服务端→浏览器方向走一条中继流式响应，浏览器→服务端的指令逐条走普通请求；主服务端用 Node 自带的 WebSocket 客户端连本机插件。理由：这两条 WebSocket 几乎是单向的，上行只有偶发的小指令，模拟成本低；让 WebSocket 真正穿过网关，要改网关对桌面应用端的放行规则，并给中继新增一种双向通道。
-
-## Consequences
-
-- 若将来出现上行频繁或对延迟敏感的插件 WebSocket（如逐键交互），每条上行消息一次请求的模拟会成为瓶颈，届时应重新评估本决定。
-- 2.2 的落地实现（PB-10）与上文「Node 自带的 WebSocket 客户端连本机插件」的设想不同：最终是**字节隧道，帧不解析**。子客户端把浏览器的升级请求头与双向字节原样搬运——服务端→浏览器一条 NDJSON 流式响应，浏览器→服务端按序分块的普通请求；服务端用收到的头向本机插件**手写升级请求**，之后双向字节各自原样穿过，中继与网关全程不解析 WebSocket 帧，帧与关闭语义由两端真正的 WebSocket 端点处理。「每条上行消息一次请求」的瓶颈因此不成立：上行按 64 KiB 块流水，与消息边界无关；协议形状见 `docs/remote-access.md` 的「插件桥的 WebSocket 字节隧道」一节。