@mzzsfy/dsh-tunnel 0.1.0 → 0.1.2

package/README.md

@@ -24,16 +24,20 @@
 ## 使用
 
 - ai 通道: 会话内直接让 ai 开隧道 `tunnel_open`(name, targetPort, entry?, wsPaths?) / `tunnel_list` / `tunnel_close`; 「允许 ai 使用」开关(默认开)关闭即向 ai 注销三件工具, 看板与 REST 管理不受影响
-- GUI 通道: 侧边栏「穿透隧道」面板手动添加/删除/复制访问地址(与 ai 同表); 设置卡两枚开关——「允许 ai 使用隧道工具」与「看板移入 better-sidebar 侧边栏」(设置 > 插件页 / 0.1.7+ 插件管理页包详情)
+- GUI 通道: 侧边栏「穿透隧道」面板手动添加/删除/复制访问地址(与 ai 同表); 设置卡两枚开关——「允许 ai 使用隧道工具」与「看板移入 better-sidebar 侧边栏」(设置 > 插件页 / 0.1.7+ 插件管理页包详情);数据与偏好变更经公共 WS 总线 `@mzzsfy/dsh-tunnel` 插件通道推送;host/client 在 `apply(ctx)` 调用 `setupCommonTools(ctx)`,以 `ctx.fiber.entry.options.name` 的完整 npm 包名绑定通道,组件捕获所属 ctx 的 bus，卸载可提前退订；ctx 卸载释放连接持有与全部订阅
 - 设置面: legacy(≤0.1.6) 设置 > 插件页独立配置节; 0.1.7+ Config volatile 字段自动配置节(connectTimeoutMs / aiTools / sidebarTab 均支持原地热更, dataDir 为环境路径不进 UI)。`connectTimeoutMs`(响应头等待超时, 改动即时生效, 无需重启)
 - 持久化 `~/.dsh/dsh-tunnel/tunnels.json`(随 `DSH_HOME`), 重启自动恢复; 目标拒连 502, 响应头等待超时(默认 10s, 头到即解除, SSE 不受影响)504
-- REST: `/api/tunnel/tunnels`(GET/POST/DELETE `/api/tunnel/tunnels/:name`) + `/api/tunnel/status` + `/api/tunnel/ui-settings`(PATCH: aiTools / sidebarTab), 与 GUI/ai 同一入口
+- REST: `/api/tunnel/tunnels`(GET/POST/DELETE `/api/tunnel/tunnels/:name`) + `/api/tunnel/status` + `/api/tunnel/ui-settings`(POST: aiTools / sidebarTab), 与 GUI/ai 同一入口
 
 ## 验证
 
-- `node --test "test/*.test.mjs"`: 36 场景 + 8 api 用例 + 11 ai 开关注册面 + 12 守卫断言(mock webServer + 真实 http/net 端到端)
+- `node --test "test/*.test.mjs"`: 37 场景 + 8 api 用例 + 11 ai 开关注册面 + 11 守卫断言 + client 端 8 用例(id 守卫 + 总线生命周期;mock webServer + 真实 http/net 端到端)
 - `node scripts/compat/tunnel-fullchain.mjs`: 隔离 dsh 实例全链路(真实激活/恢复/分发面七项探针)
 
 ## 设计文档
 
 `docs/调研-路径穿透插件.md`(「方案设计」两节为本包实施规格, 含已知限制); `docs/设计-隧道GUI.md`(GUI/设置/侧边栏注入实施规格)。
+
+## dsh 版本兼容
+
+按仓库动态窗口验证(scripts/compat/window.mjs),不预置任何固定版本槽:主测 = 渠道 dist-tag 最新 rc,完全适配口径;基线 = npm latest,不崩溃底线口径;主测与基线同版时收敛单槽。兼容面以窗口实测为准,不逐版本承诺。逐轮实测结论见 `docs/兼容性测试/逐包测试进度.md` 与本包 `兼容性测试.md`。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-tunnel",
   "description": "路径穿透隧道:在 dsh 宿主进程内把 /p/<name> 反向代理到本地 TCP 端口(HTTP strip 转发 + 声明式 WS upgrade + 3xx Location 单头改写),支持 <name>.* 子域名全路径透传(任意 WS 路径);GUI 看板手动管理隧道,设置页独立配置节与侧边栏注入开关;向 ai 注册 tunnel_open/tunnel_list/tunnel_close 工具且「允许 ai 使用」可开关(关闭即注销);代理逻辑全在插件进程内,不引入 nginx/caddy 等外部反代",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "main": "src/index.js",
   "exports": {
@@ -14,11 +14,21 @@
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "platform": "web"
+      "platform": "web",
+      "external": [
+        "@mzzsfy/dsh-common-tools/client"
+      ]
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.2.0-rc.1": "unknown",
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-alpha.1": "unknown"
+      }
     }
   },
   "scripts": {
-    "test": "node --test \"test/*.test.mjs\"",
+    "test": "node --experimental-test-module-mocks --import ./test/_mocks.common-tools.mjs --test \"test/*.test.mjs\"",
     "npmPublish": "npm publish --access public --provenance=false --registry=https://registry.npmjs.org"
   },
   "license": "MIT",
@@ -29,6 +39,9 @@
   "engines": {
     "node": ">=22"
   },
+  "dependencies": {
+    "@mzzsfy/dsh-common-tools": "^0.2.0"
+  },
   "peerDependencies": {
     "@deepseek-ai/schemastery": ">=3.18.0",
     "@deepseek-ai/dsh-tools": ">=0.1.5-rc.2"

package/src/client.js

@@ -9,8 +9,6 @@ const PANEL_ID = 'tunnel'
 const PANEL_LABEL = '穿透隧道'
 const TAB_ID = 'tunnel:board'
 const TAB_ORDER = 47
-const REFRESH_INTERVAL_MS = 30 * 1000
-const PREF_POLL_MS = 5 * 1000
 const COPY_FLASH_MS = 1200
 const PORT_MIN = 1
 const PORT_MAX = 65535
@@ -48,25 +46,25 @@ async function copyText(text) {
 /* SBUILD-BEGIN */
 const STYLE = `
 /* 组件令牌层(形制对齐 dsh-im / cron-board):宿主 dsw-alias 定义在 body 作用域, tu- 令牌必须在 body 声明才能解析到主题值;
-   fallback 取浅色中性, 深色主题由令牌接管, fallback 只兜裸宿主 */
+   直接引用宿主语义别名, 禁止字面 fallback(暗色主题漏色, 规范见 DEVELOPMENT/plugin-ui-design.md) */
 body{
---tu-bg:var(--dsw-alias-bg-layer-1,#ffffff);
---tu-bg-sub:var(--dsw-alias-bg-layer-2,#f7f8fa);
---tu-bg-muted:var(--dsw-alias-bg-module-platform,#f2f3f5);
---tu-border:var(--dsw-alias-border-l2,#e5e6eb);
---tu-border-strong:var(--dsw-alias-border-l3,#dfe1e5);
---tu-text:var(--dsw-alias-label-primary,#1f2329);
---tu-text-sub:var(--dsw-alias-label-secondary,#646a73);
---tu-text-dim:var(--dsw-alias-label-tertiary,#8f959e);
---tu-accent:#1677ff;
---tu-accent-deep:#0958d9;
---tu-accent-wash:#eaf3ff;
---tu-danger:var(--dsw-alias-state-error-primary,#d54941);
---tu-ok:var(--dsw-alias-state-success-primary,#20a162);
---tu-hover:var(--dsw-alias-interactive-bg-hover,#f7f8fa);
---tu-mask:var(--dsw-alias-bg-mask-1,rgba(31,35,41,.5));
---tu-shadow:0 1px 2px rgb(31 35 41 / 4%);
---tu-radius-sm:6px;--tu-radius-md:8px;--tu-radius-lg:14px;
+--tu-bg:var(--dsw-alias-bg-layer-1);
+--tu-bg-sub:var(--dsw-alias-bg-layer-2);
+--tu-bg-muted:var(--dsw-alias-bg-module-platform);
+--tu-border:var(--dsw-alias-border-l2);
+--tu-border-strong:var(--dsw-alias-border-l3);
+--tu-text:var(--dsw-alias-label-primary);
+--tu-text-sub:var(--dsw-alias-label-secondary);
+--tu-text-dim:var(--dsw-alias-label-tertiary);
+--tu-accent:var(--dsw-alias-brand-primary);
+--tu-accent-deep:var(--dsw-alias-button-primary-hover);
+--tu-accent-wash:color-mix(in srgb, var(--dsw-alias-brand-primary) 12%, transparent);
+--tu-danger:var(--dsw-alias-state-error-primary);
+--tu-ok:var(--dsw-alias-state-success-primary);
+--tu-hover:var(--dsw-alias-interactive-bg-hover);
+--tu-mask:var(--dsw-alias-bg-mask-1);
+--tu-shadow:0 1px 2px color-mix(in srgb, var(--dsw-alias-label-primary) 4%, transparent);
+--tu-radius-sm:6px;--tu-radius-md:8px;--tu-radius-lg:12px;
 --tu-space-2:6px;--tu-space-3:8px;--tu-space-4:10px;--tu-space-5:12px;--tu-space-6:18px;
 --tu-font-sm:12px;--tu-font-md:13px;--tu-font-lg:15px;
 --tu-control-h:30px;
@@ -76,21 +74,21 @@ body{
 .tu-toolbar{display:flex;align-items:center;gap:var(--tu-space-3);flex-wrap:wrap}
 .tu-spacer{flex:1}
 .tu-button{min-height:var(--tu-control-h);display:inline-flex;align-items:center;justify-content:center;gap:7px;border:1px solid var(--tu-border-strong);border-radius:var(--tu-radius-md);padding:0 13px;font:inherit;font-size:var(--tu-font-md);font-weight:560;background:var(--tu-bg);color:var(--tu-text);cursor:pointer;transition:border-color .15s,background .15s,color .15s}
-.tu-button:hover:not(:disabled){border-color:#aeb3bb;background:var(--tu-hover)}
+.tu-button:hover:not(:disabled){border-color:var(--tu-border-strong);background:var(--tu-hover)}
 .tu-button:disabled{cursor:not-allowed;opacity:.55}
-.tu-button--primary{background:var(--tu-accent);border-color:var(--tu-accent);color:#fff}
+.tu-button--primary{background:var(--tu-accent);border-color:var(--tu-accent);color:var(--dsw-alias-bg-base)}
 .tu-button--primary:hover:not(:disabled){background:var(--tu-accent-deep);border-color:var(--tu-accent-deep)}
 .tu-button--danger{color:var(--tu-danger)}
-.tu-button--danger:hover:not(:disabled){border-color:var(--tu-danger);background:var(--tu-danger);color:#fff}
+.tu-button--danger:hover:not(:disabled){border-color:var(--tu-danger);background:var(--tu-danger);color:var(--dsw-alias-bg-base)}
 .tu-button--sm{min-height:28px;padding:0 10px;font-size:var(--tu-font-sm)}
-.tu-button:focus-visible,.tu-icon:focus-visible{outline:2px solid color-mix(in srgb, var(--tu-accent) 70%, white);outline-offset:2px}
+.tu-button:focus-visible,.tu-icon:focus-visible{outline:2px solid color-mix(in srgb, var(--tu-accent) 70%, var(--dsw-alias-bg-base));outline-offset:2px}
 .tu-meta{font-size:var(--tu-font-sm);color:var(--tu-text-sub)}
 .tu-rows{display:flex;flex-direction:column;gap:var(--tu-space-1);font-size:var(--tu-font-md)}
 .tu-row{display:flex;align-items:center;gap:var(--tu-space-3);border:1px solid var(--tu-border);border-radius:var(--tu-radius-md);padding:var(--tu-space-2) var(--tu-space-4);flex-wrap:wrap;transition:background .15s,border-color .15s}
 .tu-row:hover{background:var(--tu-hover)}
 .tu-name{font-size:14px;font-weight:600;color:var(--tu-text)}
 .tu-badge{min-height:22px;display:inline-flex;align-items:center;padding:0 9px;border-radius:999px;color:var(--tu-text-sub);background:var(--tu-bg-muted);font-size:var(--tu-font-sm);white-space:nowrap}
-.tu-code{font-family:ui-monospace,SFMono-Regular,monospace;font-size:var(--tu-font-sm);color:var(--tu-text-dim);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:100%}
+.tu-code{font-family:var(--ds-font-family-code);font-size:var(--tu-font-sm);color:var(--tu-text-dim);white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:100%}
 .tu-link{border:none;background:transparent;padding:0;font:inherit;cursor:pointer;color:var(--tu-accent);text-decoration:underline;text-underline-offset:3px}
 .tu-link:hover{color:var(--tu-accent-deep)}
 .tu-actions{display:flex;align-items:center;gap:var(--tu-space-2);margin-left:auto}
@@ -100,11 +98,11 @@ body{
 .tu-error{font-size:var(--tu-font-sm);color:var(--tu-danger);background:var(--tu-bg-sub);border-left:3px solid var(--tu-danger);border-radius:var(--tu-radius-sm);padding:var(--tu-space-2) var(--tu-space-3)}
 .tu-switch{position:relative;display:inline-flex;align-items:center;cursor:pointer;gap:var(--tu-space-2)}
 .tu-switch input[type="checkbox"] { position:absolute;opacity:0;width:1px;height:1px }
-.tu-switch__track{width:30px;height:17px;border-radius:999px;background:#aeb3bb;position:relative;transition:background .15s;flex:none}
-.tu-switch__thumb{position:absolute;top:2px;left:2px;width:13px;height:13px;border-radius:50%;background:#fff;transition:left .15s;box-shadow:0 1px 2px rgba(0,0,0,.3)}
+.tu-switch__track{width:30px;height:17px;border-radius:999px;background:var(--tu-border-strong);position:relative;transition:background .15s;flex:none}
+.tu-switch__thumb{position:absolute;top:2px;left:2px;width:13px;height:13px;border-radius:50%;background:var(--dsw-alias-bg-base);transition:left .15s;box-shadow:0 1px 2px color-mix(in srgb, var(--dsw-alias-label-primary) 30%, transparent)}
 .tu-switch input[type="checkbox"]:checked + .tu-switch__track{background:var(--tu-accent)}
 .tu-switch input[type="checkbox"]:checked + .tu-switch__track .tu-switch__thumb{left:15px}
-.tu-switch input[type="checkbox"]:focus-visible + .tu-switch__track{outline:2px solid color-mix(in srgb, var(--tu-accent) 70%, white);outline-offset:1px}
+.tu-switch input[type="checkbox"]:focus-visible + .tu-switch__track{outline:2px solid color-mix(in srgb, var(--tu-accent) 70%, var(--dsw-alias-bg-base));outline-offset:1px}
 .tu-switch input[type="checkbox"]:disabled + .tu-switch__track{opacity:.4;cursor:not-allowed}
 .tu-switch:not(:has(input[type="checkbox"]:disabled)):hover .tu-switch__track{background:var(--tu-accent-deep);opacity:.85}
 .tu-switch input[type="checkbox"]:checked:not(:disabled) + .tu-switch__track:hover{background:var(--tu-accent-deep)}
@@ -126,7 +124,7 @@ body{
 .tu-pc__rowLabel{flex:1;min-width:0}
 .tu-pc__hint{margin:0;font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary)}
 .tu-modal-mask{position:fixed;inset:0;background:var(--tu-mask);display:flex;align-items:center;justify-content:center;z-index:60;animation:tu-fade-in .16s ease-out}
-.tu-modal{background:var(--tu-bg);color:var(--tu-text);border-radius:var(--tu-radius-lg);padding:var(--tu-space-6);max-width:520px;width:min(520px,94vw);max-height:90vh;overflow:auto;display:flex;flex-direction:column;gap:14px;box-shadow:0 12px 40px rgb(31 35 41 / 18%);animation:tu-pop-in .2s ease-out}
+.tu-modal{background:var(--tu-bg);color:var(--tu-text);border-radius:var(--tu-radius-lg);padding:var(--tu-space-6);max-width:520px;width:min(520px,94vw);max-height:90vh;overflow:auto;display:flex;flex-direction:column;gap:14px;box-shadow:var(--dsw-shadow-lv3);animation:tu-pop-in .2s ease-out}
 @keyframes tu-fade-in{from{opacity:0}to{opacity:1}}
 @keyframes tu-pop-in{from{opacity:0;transform:translateY(8px) scale(.98)}to{opacity:1;transform:none}}
 @media (prefers-reduced-motion: reduce){.tu-modal-mask,.tu-modal{animation:none}.tu-row,.tu-button,.tu-icon,.tu-switch__track,.tu-pc,.tu-pc__chevron{transition:none}}
@@ -136,9 +134,9 @@ body{
 .tu-seg{display:inline-flex;gap:2px;background:var(--tu-bg-muted);border-radius:8px;padding:2px;width:fit-content}
 .tu-seg__opt{border:none;background:transparent;border-radius:6px;padding:5px 11px;font:inherit;font-size:var(--tu-font-sm);font-weight:520;color:var(--tu-text-sub);cursor:pointer;line-height:1.2;white-space:nowrap;transition:background .15s,color .15s}
 .tu-seg__opt:hover{color:var(--tu-text)}
-.tu-seg__opt--on{background:var(--tu-accent);color:#fff;font-weight:560}
-.tu-seg__opt--on:hover{color:#fff}
-.tu-seg__opt:focus-visible{outline:2px solid color-mix(in srgb, var(--tu-accent) 70%, white);outline-offset:1px}
+.tu-seg__opt--on{background:var(--tu-accent);color:var(--dsw-alias-bg-base);font-weight:560}
+.tu-seg__opt--on:hover{color:var(--dsw-alias-bg-base)}
+.tu-seg__opt:focus-visible{outline:2px solid color-mix(in srgb, var(--tu-accent) 70%, var(--dsw-alias-bg-base));outline-offset:1px}
 .tu-grid{display:grid;grid-template-columns:1fr 1fr;gap:var(--tu-space-3) var(--tu-space-4)}
 .tu-field{display:flex;flex-direction:column;gap:4px;font-size:var(--tu-font-sm);min-width:0;color:var(--tu-text-sub)}
 .tu-field--wide{grid-column:1 / -1}
@@ -171,9 +169,12 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
   function factory(require) {
     let React = null
     let ReactDOMClient = null
+    let tools = null
     try {
       React = require('react')
       ReactDOMClient = require('react-dom/client')
+      // 公共工具库:bus 订阅是数据刷新唯一通道,缺失即整面板禁用(无轮询回退)
+      tools = require('@mzzsfy/dsh-common-tools/client')
     } catch {
       return noopFactory()
     }
@@ -324,26 +325,28 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
             disabled: busy || !nameOk || !portOk, onClick: submit }, '创建')))
     }
 
-    function TunnelPanel() {
+    function TunnelPanel({ bus }) {
       const [rows, setRows] = useState(null)
       const [error, setError] = useState('')
       const [showAdd, setShowAdd] = useState(false)
       const [busyName, setBusyName] = useState('')
-      const [reloadFlag, setReloadFlag] = useState(0)
-      const reload = useCallback(() => setReloadFlag((flag) => flag + 1), [])
+      const refreshRef = useRef(() => {})
+      const reload = useCallback(() => refreshRef.current(), [])
       useEffect(() => {
         let alive = true
         const load = async () => {
           const listOutcome = await request('GET', '/tunnels')
           if (!alive) return
-          // 成功即清错误: 瞬态失败(如插件重载期轮询)恢复后错误条不滞留
+          // 成功即清错误: 瞬态失败(如插件重载期刷新)恢复后错误条不滞留
           if (listOutcome.ok) { setRows(listOutcome.data.items); setError('') }
           else setError(listOutcome.error)
         }
-        load()
-        const timer = setInterval(load, REFRESH_INTERVAL_MS)
-        return () => { alive = false; clearInterval(timer) }
-      }, [reloadFlag])
+        // 数据刷新唯一通道:订阅推送总线(首连 onReset 即首拉,消息到达刷新)
+        const snapshot = tools.createSnapshotRefresh(load)
+        refreshRef.current = snapshot.refresh
+        const unsubscribe = bus.subscribe(snapshot.refresh, { onReset: snapshot.refresh })
+        return () => { alive = false; refreshRef.current = () => {}; snapshot.dispose(); unsubscribe() }
+      }, [bus])
       const remove = async (row) => {
         if (!window.confirm('删除隧道 ' + row.name + '?')) return
         setBusyName(row.name)
@@ -384,13 +387,13 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
         h('path', { d: 'm10.5 10.5 3 3' }))
     }
 
-    function registerMainPanel(ctx) {
+    function registerMainPanel(ctx, bus) {
       return ctx.effect(() => {
         const injectDisposers = []
         injectDisposers.push(ctx.slots.inject('main', () => ctx.slots.register({
           name: 'main',
           key: PANEL_ID,
-        }, () => h('div', { className: 'tu-main' }, h(TunnelPanel)))))
+        }, () => h('div', { className: 'tu-main' }, h(TunnelPanel, { bus })))))
         injectDisposers.push(ctx.slots.inject('sidebar.panellist', () => ctx.slots.register({
           name: 'sidebar.panellist',
           id: PANEL_ID,
@@ -402,7 +405,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
 
     // better-sidebar tab:注册即单实例(single);只注册不主动打开,
     // 打开由用户从侧边栏目录手动进入
-    function registerBoardTab(ctx, service) {
+    function registerBoardTab(ctx, service, bus) {
       return ctx.effect(() => {
         return service.registerTab({
           id: TAB_ID,
@@ -410,7 +413,7 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
           icon: (size) => h(PanelIcon, { size }),
           order: TAB_ORDER,
           single: true,
-          component: (props) => h('div', { className: 'tu-main' }, h(TunnelPanel)),
+          component: (props) => h('div', { className: 'tu-main' }, h(TunnelPanel, { bus })),
         })
       }, 'dsh-tunnel sidebar tab')
     }
@@ -480,13 +483,14 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
       // slots 供面板与设置卡片挂载(缺失则 fiber 未激活, 即干净禁用)
       inject: ['slots'],
       apply(ctx) {
+        const bus = tools.setupCommonTools(ctx)
         ensureStyle(document)
         // 挂载权交给用户:默认注册全局面板;偏好开启且侧边栏服务在场才移入扩展槽
         let currentSidebar = ctx.get('betterSidebar')
         let sidebarTabOn = false
         let tabDisposer = null
         let panelDisposer = null
-        const attachBoardTab = (sidebar) => registerBoardTab(ctx, sidebar)
+        const attachBoardTab = (sidebar) => registerBoardTab(ctx, sidebar, bus)
         const applyPref = () => {
           const wantTab = sidebarTabOn && currentSidebar !== undefined
           if (wantTab && tabDisposer === null) {
@@ -496,11 +500,14 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
             tabDisposer()
             tabDisposer = null
           }
-          if (!wantTab && panelDisposer === null) panelDisposer = registerMainPanel(ctx)
+          if (!wantTab && panelDisposer === null) panelDisposer = registerMainPanel(ctx, bus)
         }
-        const prefWatch = setInterval(async () => {
+        // 偏好仲裁数据源:订阅总线刷新(ui-settings 变更即 publish),不再周期轮询
+        let prefAlive = true
+        const syncPref = async () => {
           try {
             const outcome = await request('GET', '/status')
+            if (!prefAlive) return
             const next = outcome.ok && outcome.data && outcome.data.ui ? outcome.data.ui.sidebarTab === true : false
             if (next !== sidebarTabOn) {
               const previous = sidebarTabOn
@@ -508,15 +515,19 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
               try {
                 applyPref()
               } catch (error) {
-                // 形态切换失败回滚偏好, 下轮轮询重试, 避免入口消失后卡死
+                // 形态切换失败回滚偏好, 下轮事件重试, 避免入口消失后卡死
                 sidebarTabOn = previous
                 console.warn('[dsh-tunnel] 看板形态切换失败:', error)
               }
             }
-          } catch { /* 轮询失败保形态不变, 下轮重试 */ }
-        }, PREF_POLL_MS)
+          } catch { /* 刷新失败保形态不变, 下轮事件重试 */ }
+        }
+        const prefRefresh = tools.createSnapshotRefresh(syncPref)
+        const unsubscribePref = bus.subscribe(prefRefresh.refresh, { onReset: prefRefresh.refresh })
         ctx.effect(() => () => {
-          clearInterval(prefWatch)
+          prefAlive = false
+          prefRefresh.dispose()
+          unsubscribePref()
           if (tabDisposer) tabDisposer()
           if (panelDisposer) panelDisposer()
         }, 'dsh-tunnel mount arbitration')

package/src/index.js

@@ -13,10 +13,13 @@ import { join } from 'node:path'
 import z from '@deepseek-ai/schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 
+import { setupCommonTools, createChangeNotifier } from '@mzzsfy/dsh-common-tools/host'
 import { createApi, MESSAGES, ROUTE_PREFIX as API_PREFIX } from './api.mjs'
 
 export const name = 'dsh-tunnel'
 
+// 推送总线:变更通知统一走公共依赖 common-tools(webServer 形状到位即激活,
+// 客户端轮询已废除不留双路径);插件卸载时总线按在场消费方自动收尾
 export const inject = ['webServer']
 
 const PATH_PREFIX = '/p/'
@@ -280,6 +283,9 @@ function saveStore(dataDir, rows) {
 
 export function apply(ctx, config) {
   const webServer = ctx.webServer
+  const bus = setupCommonTools(ctx)
+  const changes = createChangeNotifier(() => bus.publish())
+  ctx.effect(() => () => changes.dispose(), '通知变更合并')
 
   // 形状守卫: 宿主形态漂移时干净禁用并告警, 绝不破坏宿主
   const shapeOk = webServer.exact instanceof Map
@@ -392,6 +398,7 @@ export function apply(ctx, config) {
         subdomains.set(record.name, record)
         tunnels.set(record.name, record)
         persist()
+        changes.refresh()
         return { ok: true, name: record.name, entry, host: `${record.name}.localhost`, port: webServer.port }
       }
       let disposeRoutes
@@ -402,6 +409,7 @@ export function apply(ctx, config) {
       }
       tunnels.set(record.name, { ...record, disposeRoutes })
       persist()
+      changes.refresh()
       return { ok: true, name: record.name, entry, path: PATH_PREFIX + record.name, port: webServer.port }
     },
     list() {
@@ -424,6 +432,7 @@ export function apply(ctx, config) {
       subdomains.delete(args.name)
       tunnels.delete(args.name)
       persist()
+      changes.refresh()
       return { ok: true, removed: true }
     },
     disposeAll() {
@@ -656,6 +665,7 @@ export function apply(ctx, config) {
     if (Object.keys(patch).length === 0) throw new Error(uiBooleanError(UI_PREF_KEYS))
     if (!(await persistPatch(patch))) return { ok: false, error: SETTINGS_UNAVAILABLE }
     applyPreferences()
+    changes.refresh()
     return { ok: true, ui: readUi() }
   }
 

package/test/_mocks.common-tools.mjs

@@ -0,0 +1,20 @@
+// common-tools host 桩(经 --import 预载,先于被测模块实例化拦截 ESM):
+// publish 记入 busStub.published(断言点零改);onPresence 注册即报 0,
+// busStub.presence 供测试手动驱动连接计数
+import { mock } from 'node:test'
+
+export const busStub = { published: [], presence: new Set() }
+export function resetBusStub() {
+  busStub.published = []
+  busStub.presence = new Set()
+}
+
+mock.module('@mzzsfy/dsh-common-tools/host', {
+  namedExports: {
+    createChangeNotifier: refresh => ({ refresh, dispose() {} }),
+    setupCommonTools: () => ({
+      publish: (payload = null) => busStub.published.push(payload),
+      onPresence(fn) { busStub.presence.add(fn); fn(0); return () => busStub.presence.delete(fn) },
+    }),
+  },
+})

package/test/ai-switch.test.mjs

@@ -8,6 +8,8 @@ import { mkdtempSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
+import { busStub, resetBusStub } from './_mocks.common-tools.mjs'
+
 const TOOL_NAMES = ['tunnel_open', 'tunnel_list', 'tunnel_close']
 
 class MockWebServer {
@@ -56,6 +58,9 @@ function createCtx({ tools, settings, configEditor, fiber } = {}) {
     if (typeof disposer === 'function') effectDisposers.push(disposer)
     return disposer
   }
+  // 总线 publish 桩:桥接到最近 createCtx 的 published 供断言
+  resetBusStub()
+  const published = busStub.published
   const ctx = {
     webServer: undefined,
     fiber,
@@ -68,7 +73,7 @@ function createCtx({ tools, settings, configEditor, fiber } = {}) {
     effect: runEffect,
     inject(names, cb) { cb({ tools, settings, effect: runEffect }) },
   }
-  return { ctx, events, effectDisposers }
+  return { ctx, events, effectDisposers, published }
 }
 
 // legacy mock settings: 与 tunnel.test.mjs 同款语义(内存存储 + watch 登记 + 手动触发)

package/test/client-bus-lifecycle.test.mjs

@@ -0,0 +1,146 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+const source = readFileSync(new URL('../src/client.js', import.meta.url), 'utf8')
+const PKG = '@mzzsfy/dsh-tunnel'
+const flush = () => new Promise(resolve => setImmediate(resolve))
+
+function fixture(sidebarTab) {
+  let definition, pendingEffects
+  const owners = new Map(), requests = [], clocks = new Set()
+  const window = { __ModuleLoader__: { load: value => { definition = value } } }
+  const document = { getElementById: () => ({}) }
+  const react = {
+    createElement: (type, props, ...children) => ({ type, props: { ...props, children } }),
+    useState: value => [typeof value === 'function' ? value() : value, () => {}],
+    useRef: value => ({ current: value }),
+    useCallback: fn => fn,
+    useEffect: fn => pendingEffects.push(fn),
+  }
+  const tools = { createSnapshotRefresh: refresh => ({ refresh, dispose() {} }), setupCommonTools(ctx) {
+    assert.equal(ctx.fiber.entry.options.name, PKG)
+    const owner = { active: true, subscriptions: new Set() }
+    owners.set(ctx, owner)
+    ctx.effect(() => () => { owner.active = false; owner.subscriptions.clear() })
+    return { subscribe(listener, { onReset } = {}) {
+      assert.ok(owner.active, '不能订阅已卸载的 ctx')
+      const subscription = { listener, onReset }
+      owner.subscriptions.add(subscription)
+      return () => owner.subscriptions.delete(subscription)
+    } }
+  } }
+  const fetch = async path => {
+    requests.push(path)
+    return { ok: true, json: async () => ({ items: [], ui: { sidebarTab } }) }
+  }
+  new Function('window', 'document', 'fetch', 'setInterval', 'clearInterval', source)(
+    window, document, fetch,
+    fn => { clocks.add(fn); return fn }, fn => clocks.delete(fn))
+  const plugin = definition.factory(name => {
+    if (name === 'react') return react
+    if (name === 'react-dom/client') return {}
+    assert.equal(name, '@mzzsfy/dsh-common-tools/client')
+    return tools
+  })
+  function activate() {
+    const cleanups = [], entries = new Set(), tabs = new Set()
+    const service = { registerTab(tab) { tabs.add(tab); return () => tabs.delete(tab) } }
+    const ctx = {
+      fiber: { entry: { options: { name: PKG } } },
+      get: name => name === 'betterSidebar' ? service : undefined,
+      inject() {},
+      effect(fn) {
+        const cleanup = fn()
+        let active = true
+        const dispose = () => { if (active) { active = false; cleanup?.() } }
+        cleanups.push(dispose)
+        return dispose
+      },
+      slots: {
+        inject(name, fn) { return name === 'main' || name === 'sidebar.panellist' ? fn() : () => {} },
+        register(options, component) {
+          const entry = { ...options, component }
+          entries.add(entry)
+          return () => entries.delete(entry)
+        },
+      },
+    }
+    plugin.apply(ctx)
+    return {
+      get subscriptions() { return owners.get(ctx).subscriptions },
+      reset() { for (const item of [...this.subscriptions]) item.onReset?.() },
+      emit() { for (const item of [...this.subscriptions]) item.listener(null) },
+      mount() {
+        const component = sidebarTab ? [...tabs][0]?.component : [...entries].find(item => item.name === 'main')?.component
+        assert.equal(typeof component, 'function', '面板应已注册')
+        pendingEffects = []
+        const render = node => {
+          if (Array.isArray(node)) return node.forEach(render)
+          if (!node || typeof node !== 'object') return
+          if (typeof node.type === 'function') render(node.type(node.props))
+          else render(node.props.children)
+        }
+        render(component({ visible: true }))
+        const disposers = pendingEffects.map(effect => effect()).filter(value => typeof value === 'function')
+        return () => { for (const dispose of disposers.splice(0).reverse()) dispose() }
+      },
+      dispose() { for (const dispose of [...cleanups].reverse()) dispose() },
+      get registrations() { return entries.size + tabs.size },
+    }
+  }
+  return { activate, requests, clocks }
+}
+
+for (const sidebarTab of [false, true]) {
+  const surface = sidebarTab ? '侧栏' : '主面板'
+  for (const survivorIndex of [0, 1]) {
+    test(`Given 同 factory 的 A/B 已注册${surface} When 卸载 ${survivorIndex === 0 ? 'B' : 'A'} 后挂载存活面板 Then 仍用自己的租约订阅和刷新`, async () => {
+      const f = fixture(sidebarTab), instances = [f.activate(), f.activate()]
+      for (const instance of instances) instance.reset()
+      await flush()
+      const survivor = instances[survivorIndex], removed = instances[1 - survivorIndex]
+      removed.dispose()
+      assert.equal(removed.subscriptions.size, 0)
+      assert.equal(removed.registrations, 0)
+      const unmount = survivor.mount()
+      assert.equal(survivor.subscriptions.size, 2)
+      const before = f.requests.length
+      survivor.reset()
+      await flush()
+      assert.equal(f.requests.length - before, 2)
+      const afterReset = f.requests.length
+      survivor.emit()
+      await flush()
+      assert.equal(f.requests.length - afterReset, 2)
+      unmount()
+      assert.equal(survivor.subscriptions.size, 1, '组件卸载仅清自己的数据订阅')
+      const unmountAgain = survivor.mount()
+      assert.equal(survivor.subscriptions.size, 2)
+      survivor.dispose()
+      assert.equal(survivor.subscriptions.size, 0)
+      unmountAgain()
+      survivor.dispose()
+      assert.equal(f.clocks.size, 0)
+    })
+  }
+
+  test(`Given A/B 的${surface}都已挂载 When 卸载 A Then 只清 A 的订阅并保留 B 的组件订阅`, async () => {
+    const f = fixture(sidebarTab), a = f.activate(), b = f.activate()
+    a.reset(); b.reset()
+    await flush()
+    const unmountA = a.mount(), unmountB = b.mount()
+    assert.equal(a.subscriptions.size, 2)
+    assert.equal(b.subscriptions.size, 2)
+    a.dispose()
+    assert.equal(a.subscriptions.size, 0)
+    assert.equal(b.subscriptions.size, 2)
+    unmountA()
+    assert.equal(b.subscriptions.size, 2)
+    unmountB()
+    assert.equal(b.subscriptions.size, 1)
+    b.dispose()
+    assert.equal(b.subscriptions.size, 0)
+    assert.equal(f.clocks.size, 0)
+  })
+}

package/test/switch-guard.test.mjs

@@ -1,5 +1,5 @@
 // 开关样式守卫 BDD:裸 checkbox/裸 input 状态选择器会静默损坏 UI 或误伤同 label 的文本输入,
-// 属无报错的 UI 退化, 静态断言锁死 tu-switch 结构(参照 cb-switch/mce-switch 同款守卫)。
+// 属无报错的 UI 退化, 静态断言锁死 tu-switch 结构(参照 cb-switch/tn-switch 同款守卫)。
 import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'

package/test/tunnel.test.mjs

@@ -10,6 +10,8 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { once } from 'node:events'
 
+import { busStub, resetBusStub } from './_mocks.common-tools.mjs'
+
 const DEFAULT_CONNECT_TIMEOUT = 10 * 1000
 const PORT_MAX = 65535
 
@@ -51,6 +53,9 @@ function createCtx(webServer, tools = undefined, settings = undefined) {
     if (typeof disposer === 'function') effectDisposers.push(disposer)
     return disposer
   }
+  // 总线 publish 桩:桥接到最近 createCtx 的 published 供断言
+  resetBusStub()
+  const published = busStub.published
   const ctx = {
     webServer,
     get: () => undefined,
@@ -60,7 +65,7 @@ function createCtx(webServer, tools = undefined, settings = undefined) {
       cb({ tools: toolsService, settings, effect: runEffect })
     },
   }
-  return { ctx, toolsService, effectDisposers }
+  return { ctx, toolsService, effectDisposers, published }
 }
 
 // mock settings 服务: 内存存储 + watch 回调登记, 测试手动触发模拟设置页写入
@@ -92,7 +97,7 @@ process.on('exit', () => {
 
 async function applyPlugin(webServer, options = {}) {
   const { apply } = await import('../src/index.js')
-  const { ctx, toolsService, effectDisposers } = createCtx(webServer, undefined, options.settings)
+  const { ctx, toolsService, effectDisposers, published } = createCtx(webServer, undefined, options.settings)
   const dataDir = options.dataDir ?? defaultDataDir()
   const config = { connectTimeoutMs: options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT, dataDir }
   const warnings = []
@@ -110,7 +115,7 @@ async function applyPlugin(webServer, options = {}) {
     dispose()
     for (const disposer of effectDisposers.reverse()) disposer()
   }
-  return { webServer, tools, dataDir, warnings, dispose: disposeAll, ctx }
+  return { webServer, tools, dataDir, warnings, dispose: disposeAll, ctx, published }
 }
 
 function toolOf(plugin, name) {
@@ -262,6 +267,17 @@ test('场景2 open: Given 合法参数与 wsPaths Then prefix 路由与两形态
   assert.deepEqual(persisted.map((row) => row.name), ['app'])
 })
 
+test('场景2b 总线通知: Given 增删与偏好写路径 Then publish() 契约', async (t) => {
+  const plugin = await applyPlugin(new MockWebServer())
+  assert.deepEqual(plugin.published, [], '装载期无变更不发布')
+  await open(plugin, { name: 'app', targetPort: PORT_MAX - 1 })
+  await open(plugin, { name: 'app2', targetPort: PORT_MAX - 2, wsPaths: [] })
+  await close(plugin, 'app')
+  const published = plugin.published
+  assert.equal(published.length, 3, 'open 两次 + close 一次')
+  for (const payload of published) assert.equal(payload, null)
+})
+
 test('场景3 校验: Given 非法名或越界端口 Then 拒收且不注册不落盘', async (t) => {
   const plugin = await applyPlugin(new MockWebServer())
   for (const args of [{ name: 'App', targetPort: 80 }, { name: 'a.b', targetPort: 80 }, { name: 'ok', targetPort: 0 }, { name: 'ok', targetPort: PORT_MAX + 1 }]) {