@twinsearth/dsh-master 3.2.8 → 3.2.9

package/README.md

@@ -1,9 +1,12 @@
 # dsh-Master（房主）
 
 > 与瓮城 **dsh-Fang** 并行的主 Agent 插件。  
-> 当前版本：`3.2.8`（审计修复发布线；tag / GitHub Release / NPM public）。
+> 当前版本：`3.2.9`（面板交互修复线；tag / GitHub Release / NPM public）。
 > 仓库：https://github.com/TwinsEarth/dsh-Master
 
+[![DSH 0.2.2-rc.1](https://img.shields.io/badge/DSH-0.2.2--rc.1-4D6BFE?style=flat)](https://github.com/deepseek-ai/deepseek-harness)
+[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
+
 ## 这是什么
 
 dsh-Master 不接管瓮城的「母体 / 原身 / 分身」生命周期；它是一块**并列的主插件**，
@@ -84,7 +87,8 @@ dsh plugin add <package>  # 加载 dist-host/dist-worker
 
 ## 状态
 
+- 3.2.9 发布线：房主面板改注册到 `shell.overlay` 常驻浮层——点击面板之外不收起、侧栏「房主」按钮二次点击收起、正文独立滚动；新增无浏览器 hook 运行时行为测试（开关、无 outside-click 监听、滚动容器、SSE 失败不卸载面板）。
 - 3.2.8 发布线：与瓮城通过 fang-master contract 1.0 互联（local/http/file/legacy 四级保底）；GitHub Release + NPM public。
 - 当前工作树完成新一轮审计修复：工具名/死循环阈值、Router 鉴权与生命周期、真实路由分流、契约幂等与超时、PR 护栏与交付、飞书加密、长 Shell 后台作业、成本实测接线、PJM 派生契约。
-- 验收：`npm run check` / `npm run build` / `npm test` 全绿；真实双 Host/fork 落库、工具写读、SSE、回写、配额与桥清理断言通过。详见复盘文档。
-- 后续修复尚未发布，也未安装到用户主 profile；发布仍需明确指令。
+- 验收：`npm run check` / `npm run build` / `npm test` 全绿（188/188）；真实双 Host/fork 落库、工具写读、SSE、回写、配额与桥清理断言通过。详见复盘文档。
+- 发布不等于安装：本流程不修改任何用户 profile（当前 desktop profile 仍为 3.2.8，升级需另行授权）。

package/client.js

@@ -2,11 +2,18 @@
 // Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
 
 /**
- * Dsh-Master（房主）Web Client：侧栏「房主」入口 + 只读状态抽屉。
+ * Dsh-Master（房主）Web Client：侧栏「房主」入口 + 只读状态面板。
  *
  * 只做观察面板（3.2.0 架构骨架）：展示角色、三个子插件的激活状态、与瓮城的
  * 服务协作状态。数据来自 core 的只读路由 `/dsh-master/api/status`。
  * 不写任何业务状态，不接管宿主根节点。
+ *
+ * 面板与按钮分离（3.2.9）：按钮注册在 `sidebar.footer.action`，面板注册在
+ * `shell.overlay`（DSH 的整框浮层，位于所有列与滚动容器之外，且本身
+ * click-through）。两者通过模块级 store 共享「是否展开」：
+ * - 点击页面其他位置不会关闭面板（浮层没有 outside-click 收回逻辑）；
+ * - 再次点击「房主」按钮由 `togglePanel()` 收起；
+ * - 面板固定 viewport 高度，正文 `overflow-y: auto`，长内容可滚动查看。
  */
 window.__ModuleLoader__.load({
   id: '@twinsearth/dsh-master',
@@ -21,12 +28,22 @@ window.__ModuleLoader__.load({
         boxShadow: '-16px 0 40px rgba(16,17,20,.16)', display: 'flex', flexDirection: 'column',
         fontFamily: '-apple-system,BlinkMacSystemFont,"Segoe UI","Microsoft YaHei",sans-serif',
         fontSize: 13, color: '#1D1D1F',
+        // shell.overlay 整层是 click-through：面板自己opt-in接收指针事件，
+        // 面板之外的点击穿透到下面的应用，不会触发任何收回。
+        pointerEvents: 'auto',
+      },
+      head: {
+        flex: '0 0 auto', display: 'flex', alignItems: 'center', gap: 8, padding: '14px 16px',
+        borderBottom: '1px solid rgba(16,17,20,.08)',
       },
-      head: { display: 'flex', alignItems: 'center', gap: 8, padding: '14px 16px', borderBottom: '1px solid rgba(16,17,20,.08)' },
       title: { fontSize: 14, fontWeight: 700 },
       sub: { fontSize: 11.5, color: '#86868B' },
       close: { marginLeft: 'auto', width: 28, height: 28, borderRadius: 8, border: '1px solid rgba(16,17,20,.12)', background: '#fff', color: '#5F6368', cursor: 'pointer' },
-      body: { flex: 1, overflowY: 'auto', padding: '12px 14px 18px', display: 'flex', flexDirection: 'column', gap: 10 },
+      body: {
+        flex: '1 1 auto', minHeight: 0, overflowY: 'auto', overscrollBehavior: 'contain',
+        scrollbarGutter: 'stable', scrollbarWidth: 'thin',
+        padding: '12px 14px 18px', display: 'flex', flexDirection: 'column', gap: 10,
+      },
       card: { border: '1px solid rgba(16,17,20,.1)', borderRadius: 12, padding: '10px 11px', background: '#FAFAFC', display: 'flex', flexDirection: 'column', gap: 4 },
       row: { display: 'flex', alignItems: 'center', gap: 6, flexWrap: 'wrap' },
       name: { fontSize: 13, fontWeight: 600 },
@@ -40,7 +57,37 @@ window.__ModuleLoader__.load({
         borderRadius: 8, border: '1px solid rgba(16,17,20,.12)', background: '#fff', color: '#1D1D1F',
         cursor: 'pointer', fontSize: 12.5, fontWeight: 600, fontFamily: 'inherit',
       },
-      banner: { position: 'fixed', top: 0, right: 0, bottom: 0, left: 0, zIndex: 2147482799, background: 'rgba(18,19,22,.18)' },
+      fabOpen: {
+        display: 'inline-flex', alignItems: 'center', gap: 6, height: 28, padding: '0 9px',
+        borderRadius: 8, border: '1px solid rgba(16,17,20,.24)', background: '#F2F2F5', color: '#1D1D1F',
+        cursor: 'pointer', fontSize: 12.5, fontWeight: 600, fontFamily: 'inherit',
+      },
+    }
+
+    /**
+     * 面板展开状态：按钮（sidebar.footer.action）与面板（shell.overlay）是两个
+     * 独立注册的组件，状态必须放在模块级 store 里，不能放在任一组件内部。
+     */
+    const panelState = { open: false }
+    const panelListeners = new Set()
+    const getPanelOpen = () => panelState.open
+    const setPanelOpen = (next) => {
+      const value = Boolean(next)
+      if (panelState.open === value) return
+      panelState.open = value
+      for (const listener of panelListeners) {
+        try { listener() } catch { /* 订阅者异常不影响其他订阅者 */ }
+      }
+    }
+    const togglePanel = () => setPanelOpen(!panelState.open)
+    const subscribePanel = (listener) => {
+      panelListeners.add(listener)
+      return () => { panelListeners.delete(listener) }
+    }
+    function usePanelOpen() {
+      const [open, setOpen] = React.useState(getPanelOpen)
+      React.useEffect(() => subscribePanel(() => setOpen(getPanelOpen())), [])
+      return open
     }
 
     const tag = (text, color) => h('span', { style: { ...S.tag, ...(color ? { color, background: 'rgba(16,17,20,.05)' } : {}) } }, text)
@@ -194,7 +241,7 @@ window.__ModuleLoader__.load({
       )
     }
 
-    function MasterPanel({ onClose }) {
+    function MasterPanel() {
       const [status, setStatus] = React.useState(null)
       const [error, setError] = React.useState('')
 
@@ -217,35 +264,51 @@ window.__ModuleLoader__.load({
       }, [])
 
       const items = status && Array.isArray(status.subplugins) ? status.subplugins : []
-      return h('div', null,
-        h('div', { style: S.fab, role: 'presentation' }),
-        h('aside', { style: S.panel, 'aria-label': '房主状态' },
-          h('div', { style: S.head },
-            h('span', { style: S.title }, '房主 · dsh-Master'),
-            h('span', { style: S.sub }, status ? `${status.version} · ${status.role}` : '读取中'),
-            h('button', { type: 'button', style: S.close, title: '关闭', onClick: onClose }, '×')),
-          h('div', { style: S.body },
-            error ? h('div', { style: S.error }, error) : null,
-            status ? h('div', { style: S.card },
-              h('div', { style: S.row }, h('span', { style: S.name }, '主 Agent 控制面'), tag('与瓮城并行')),
-              h('div', { style: S.desc }, '角色：' + status.role + ' · 版本：' + status.version),
-              h('div', { style: S.desc }, '运行：' + Math.max(1, Math.round((status.uptimeMs || 0) / 60000)) + ' 分钟'),
-            ) : null,
-            ...items.map((item) => h(SubpluginCard, { key: item.id, item })),
-            h(FangCard, { cooperation: status && status.cooperation }),
-            h(LiveFeed),
-            h('div', { style: S.desc }, '3.2.7：真实流式（SSE）+ token 轮换/审计 + Worker 并发配额 + 宿主 adapter；未发布。'),
-          )),
-      )
+      return h('aside', { style: S.panel, id: 'dsh-master-panel', 'aria-label': '房主状态' },
+        h('div', { style: S.head },
+          h('span', { style: S.title }, '房主 · dsh-Master'),
+          h('span', { style: S.sub }, status ? `${status.version} · ${status.role}` : '读取中'),
+          h('button', {
+            type: 'button',
+            style: S.close,
+            title: '收起面板',
+            'aria-label': '收起房主面板',
+            onClick: () => setPanelOpen(false),
+          }, '×')),
+        h('div', { style: S.body },
+          error ? h('div', { style: S.error }, error) : null,
+          status ? h('div', { style: S.card },
+            h('div', { style: S.row }, h('span', { style: S.name }, '主 Agent 控制面'), tag('与瓮城并行')),
+            h('div', { style: S.desc }, '角色：' + status.role + ' · 版本：' + status.version),
+            h('div', { style: S.desc }, '运行：' + Math.max(1, Math.round((status.uptimeMs || 0) / 60000)) + ' 分钟'),
+          ) : null,
+          ...items.map((item) => h(SubpluginCard, { key: item.id, item })),
+          h(FangCard, { cooperation: status && status.cooperation }),
+          h(LiveFeed),
+          h('div', { style: S.desc }, '3.2.9：面板常驻（点面板外不收起、按钮二次点击收起、长内容可滚动）；实时流（SSE）+ token 轮换/审计 + Worker 并发配额。'),
+        ))
     }
 
-    /** sidebar.footer.action 槽：一个「房主」按钮，点击打开状态抽屉。 */
+    /** shell.overlay：整框浮层里的面板本体；关闭时不渲染任何节点。 */
+    function MasterOverlay() {
+      const open = usePanelOpen()
+      return open ? h(MasterPanel) : null
+    }
+
+    /**
+     * sidebar.footer.action 槽：一个「房主」按钮。
+     * 再点一次收起面板（之前只 setOpen(true)，面板打开后按钮无法关闭）。
+     */
     function MasterSeat() {
-      const [open, setOpen] = React.useState(false)
-      return h('div', null,
-        h('button', { type: 'button', style: S.fab, title: '房主 · 主 Agent 控制面', onClick: () => setOpen(true) }, '◈ 房主'),
-        open ? h(MasterPanel, { onClose: () => setOpen(false) }) : null,
-      )
+      const open = usePanelOpen()
+      return h('button', {
+        type: 'button',
+        style: open ? S.fabOpen : S.fab,
+        title: open ? '房主 · 点击收起控制面' : '房主 · 主 Agent 控制面',
+        'aria-expanded': open ? 'true' : 'false',
+        'aria-controls': 'dsh-master-panel',
+        onClick: () => togglePanel(),
+      }, '◈ 房主')
     }
 
     return {
@@ -257,6 +320,14 @@ window.__ModuleLoader__.load({
           order: 79,
           label: '房主',
         }, MasterSeat))
+        // 面板放在 shell.overlay：位于所有列与滚动容器之外，且整层 click-through，
+        // 因此不会随侧栏（或宿主弹层）卸载，点击面板外也不会收回。
+        ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+          name: 'shell.overlay',
+          id: 'dsh-master-panel',
+          order: 78,
+          label: '房主面板',
+        }, MasterOverlay))
       },
     }
   },

package/dist-host/kernel.js

@@ -7,7 +7,7 @@
  * 与瓮城 dsh-Fang 的协作只走 DSH 服务键，不 import fang 代码。
  */
 import crypto from 'node:crypto';
-export const MASTER_VERSION = '3.2.8';
+export const MASTER_VERSION = '3.2.9';
 export const FANG_CONTRACT_MIN = '3.1.14';
 export const SERVICE = Object.freeze({
     master: 'dshMaster',

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
-# dsh-Master 架构（3.2.8）
+# dsh-Master 架构（3.2.9）
 
-> 当前实现基线为 3.2.8；本文保留设计演进记录。最新实机证据与剩余限制见 `REVIEW-v3.2.7.md`。
+> 当前实现基线为 3.2.9；本文保留设计演进记录。最新实机证据与剩余限制见 `REVIEW-v3.2.7.md`。
 
 ## 1. 为什么是“并行主插件”
 

package/docs/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 3.2.9（2026-11-12，tag / GitHub Release / NPM public）
+
+**主题：房主面板交互修复（常驻 / 可收起 / 可滚动）+ 客户端行为测试。**
+
+- 面板常驻：面板从 `sidebar.footer.action` 单元格移到 `shell.overlay` 整框浮层（位于所有列与宿主滚动容器之外，整层 click-through，面板自行 opt-in 指针事件），不再随侧栏或宿主弹层卸载；插件不注册任何 window/document 监听，因此点击面板之外不会收起。
+- 按钮收起：侧栏「房主」按钮由 `setOpen(true)` 改为 `togglePanel()`，二次点击收起；按钮补 `aria-expanded` / `aria-controls` 与展开态样式。
+- 面板滚动：`aside` 固定 viewport 高度，正文成为独立滚动容器（`flex: 1 1 auto; min-height: 0; overflow-y: auto; overscroll-behavior: contain; scrollbar-gutter: stable`），长内容不再被裁切。
+- 状态共享：按钮与面板是两个独立注册的组件，展开态放在模块级 store（订阅 + `useState` 同步），不依赖任一组件生命周期。
+- 测试：新增 `test/client-panel.test.mjs`，用最小 hook 运行时（`node:vm` + 假 React/槽位）真实渲染组件，断言开关、无 outside-click 监听、滚动容器样式，以及 SSE token 405 时面板不卸载；全量 188/188 通过。
+- 顺带把面板底部过期的版本说明从 3.2.7 更新到 3.2.9。
+- 已知限制（非本版范围）：mother 角色下 Router 子插件按角色门禁禁用，`/superagent/stream-token` 路由不存在，DSH 未匹配路由对 POST 回 405，面板因此显示「实时流 token 获取失败（HTTP 405）」；这是角色门禁的预期表现，本版未改文案。
+
 ## 3.2.8（2026-11-12，tag / GitHub Release / NPM public）
 
 **主题：真实双 Host/fork 验收驱动的安全、生命周期、契约与 UI 收口。**

package/docs/RELEASE-v3.2.8.md

@@ -0,0 +1,27 @@
+# dsh-Master v3.2.8 发布门禁
+
+日期：2026-11-12。
+
+## 内容
+
+本版将 v3.2.7 后的全面审计修复正式发布：Worker/工具、Router 生命周期与鉴权、契约幂等与文件桥清理、PR 交付护栏与接线、飞书加密、长 Shell 后台作业、HarnessMM 实测接线、PJM 派生契约、UI token 轮换与测试基础设施。
+
+完整证据见 `REVIEW-v3.2.7.md` 与 `SMOKE-3.2.7.md`。
+
+## 发布前实测
+
+```text
+npm run check       0 error
+npm run build       0 error（dist-host + dist-worker）
+npm test            185 / 185 pass / 0 fail
+npm run test:clean  185 / 185 pass / 0 fail（不使用 --test-force-exit）
+```
+
+## 三方发布目标
+
+- `main`：发布提交；
+- `v3.2.8`：annotated tag；
+- GitHub Release：tarball + sha256 + manifest；
+- NPM：`@twinsearth/dsh-master@3.2.8`，`access=public`。
+
+发布不等同于安装：本流程不修改任何用户 profile。

package/docs/RELEASE-v3.2.9.md

@@ -0,0 +1,29 @@
+# dsh-Master v3.2.9 发布门禁
+
+日期：2026-11-12。
+
+## 内容
+
+本版只修房主面板的三项交互：面板常驻（点击面板之外不收起）、侧栏「房主」按钮二次点击收起、面板正文可滚动。面板从侧栏单元格改注册到 `shell.overlay` 整框浮层，展开态由模块级 store 共享，按钮与面板互不依赖对方生命周期。新增无浏览器行为测试 `test/client-panel.test.mjs`（最小 hook 运行时真实渲染注册组件）。
+
+## 发布前实测
+
+```text
+npm run check       0 error
+npm run build       0 error（dist-host + dist-worker）
+npm test            188 / 188 pass / 0 fail
+npm run test:clean  188 / 188 pass / 0 fail（不使用 --test-force-exit）
+```
+
+## 三方发布目标
+
+- `main`：发布提交；
+- `v3.2.9`：annotated tag；
+- GitHub Release：tarball + sha256 + manifest；
+- NPM：`@twinsearth/dsh-master@3.2.9`，`access=public`。
+
+发布不等同于安装：本流程不修改任何用户 profile（desktop profile 仍停在 3.2.8，升级需另行授权）。
+
+## 已知限制
+
+mother 角色下 Router 子插件按角色门禁禁用，`/superagent/stream-token` 不存在，DSH 未匹配路由对 POST 返回 405，面板显示「实时流 token 获取失败（HTTP 405）」。这是角色门禁的预期表现，本版未改文案。

package/docs/ROADMAP.md

@@ -1,7 +1,7 @@
 # 路线图：3.2.0 → 3.4.0
 
 > 版本线：`3.2.0 – 3.2.9`（1 个大版本 + 9 个小版本），随后 3.3.0、3.4.0。  
-> 本文保留版本演进记录；当前基线为 `3.2.8`。
+> 本文保留版本演进记录；当前基线为 `3.2.9`。
 > 最新测试/实机状态与尚未完成的范围见 `REVIEW-v3.2.7.md`，下列旧版本待办不得再理解为当前状态。
 
 ## 三条主线

package/docs/SECURITY.md

@@ -1,4 +1,4 @@
-# 安全边界（3.2.8）
+# 安全边界（3.2.9）
 
 > 最新变化：worker-events 读取需 UI/匹配 worker token；旧 token 轮换 fail-closed；契约与 PR 网络调用全部有超时；DSH 同路径路由合并分流；飞书加密事件支持 AES-256-CBC。实机证据见 `REVIEW-v3.2.7.md`。
 

package/docs/SUPERAGENT.md

@@ -1,8 +1,8 @@
-# SuperAgent（v3.2.8）
+# SuperAgent（v3.2.9）
 
 > 把“用户从多窗口注意力调度中解放出来”的架构跃迁：**Router（常驻控制面）** 与
 > **Worker（隔离执行体）** 分离，Ticket/Mandate 约束授权，渐进式信任控制自动接单。
-> 3.2.8 为审计修复发布线。历史限制与实机证据见 `REVIEW-v3.2.7.md`。
+> 3.2.9 为面板交互修复发布线。历史限制与实机证据见 `REVIEW-v3.2.7.md`。
 
 ## 1. 双层结构
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twinsearth/dsh-master",
-  "version": "3.2.8",
+  "version": "3.2.9",
   "private": false,
   "publishConfig": {
     "access": "public"

package/src/kernel.ts

@@ -10,7 +10,7 @@
 
 import crypto from 'node:crypto'
 
-export const MASTER_VERSION = '3.2.8'
+export const MASTER_VERSION = '3.2.9'
 export const FANG_CONTRACT_MIN = '3.1.14'
 
 export const SERVICE = Object.freeze({