@twinsearth/dsh-master 3.2.8 → 3.2.10

package/README.md

@@ -1,9 +1,15 @@
 # dsh-Master（房主）
 
 > 与瓮城 **dsh-Fang** 并行的主 Agent 插件。  
-> 当前版本：`3.2.8`（审计修复发布线；tag / GitHub Release / NPM public）。
+> 当前版本：`3.2.10`（角色矩阵放宽线；tag / GitHub Release / NPM public）。
 > 仓库：https://github.com/TwinsEarth/dsh-Master
 
+[![CI](https://github.com/TwinsEarth/dsh-Master/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TwinsEarth/dsh-Master/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@twinsearth/dsh-master?style=flat&label=npm&color=4D6BFE)](https://www.npmjs.com/package/@twinsearth/dsh-master)
+[![license](https://img.shields.io/badge/license-AGPL--3.0--or--later-4D6BFE?style=flat)](https://github.com/TwinsEarth/dsh-Master/blob/main/LICENSE)
+[![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 不接管瓮城的「母体 / 原身 / 分身」生命周期；它是一块**并列的主插件**，
@@ -13,8 +19,8 @@ dsh-Master 不接管瓮城的「母体 / 原身 / 分身」生命周期；它是
 DSH Host
 ├── 瓮城 bundle (dsh-Fang)                    房主 bundle (dsh-Master)
 │   mirror / essence / derived                core（主 Agent 控制面）
-│   fangForker / fangDecisionCenter  ◄──────  ├── superagent-router   （essence）
-│   fangSessionCatalog                       ├── superagent-worker   （fork）
+│   fangForker / fangDecisionCenter  ◄──────  ├── superagent-router   （essence/mother）
+│   fangSessionCatalog                       ├── superagent-worker   （fork/essence）
 │                                            ├── cost-optimizer       （fork）
 │                                            └── dual-manager         （mother/essence）
 └── 协作只走服务键；任一方向失败一律 fail-closed，不本地降级执行
@@ -24,9 +30,9 @@ DSH Host
 
 | 子插件 | 行 id | 允许角色 | 路线图 | 已交付 |
 |---|---|---|---|---|
-| SuperAgent Router | `master-superagent-router` | **essence only** | 3.2.1/3.2.3 | Webhook/Ticket/Mandate、渐进信任、本地或母体桥派发、Worker 实时事件、回写 |
-| SuperAgent Worker | `master-superagent-worker` | **fork only** | 3.2.1 | Ticket 上下文、Mandate 守卫 |
-| Worker Agent Loop | `master-superagent-loop` | **fork only** | 3.2.3 | tsc 编译 preset；有 Ticket 自动跑多轮工具循环并流式回传 |
+| SuperAgent Router | `master-superagent-router` | **essence / mother** | 3.2.1/3.2.3 | Webhook/Ticket/Mandate、渐进信任、本地或母体桥派发、Worker 实时事件、回写 |
+| SuperAgent Worker | `master-superagent-worker` | **fork / essence** | 3.2.1 | Ticket 上下文、Mandate 守卫 |
+| Worker Agent Loop | `master-superagent-loop` | **fork / essence** | 3.2.3 | tsc 编译 preset；有 Ticket 自动跑多轮工具循环并流式回传 |
 | 成本优化 HarnessMM | `master-cost-optimizer` | **fork only** | 3.3.0 | observe 层：token 估算、实测记录 |
 | 双主管 PM + PJM | `master-dual-manager` | **mother / essence** | 3.4.0 | PRD/计划/调度/决策中心澄清 |
 
@@ -84,7 +90,35 @@ dsh plugin add <package>  # 加载 dist-host/dist-worker
 
 ## 状态
 
+- 3.2.10 发布线：角色矩阵放宽——Router 进入母体（essence/mother），Worker 与 Worker Agent Loop 进入原身（fork/essence）；母体仍不接纳执行体，fork 仍不注册 Router。
+- 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，升级需另行授权）。
+
+## 依赖、权限与兼容
+
+- **外部依赖**：与瓮城 **dsh-Fang ≥ 3.1.14** 同宿主协作，通过 `fangForker` / `fangDecisionCenter` / `fangSessionCatalog` / `fangSessionBridge` 服务键派发与回收；瓮城不在线时子插件 **fail-closed**，不在本地降级执行。
+- **安装产物**：npm 运行时依赖为空；无 `preinstall` / `install` / `postinstall` / `prepare` 生命周期脚本；安装只写目标 profile 的 bundle 层。
+- **权限与边界**：Host 侧只注册受控 HTTP 路由（status / stream-token / worker-events / stream / session / webhook），worker-events POST 需要 ticket 匹配的 worker token；Worker 工具受 Mandate 作用域、Shell 白名单与工作区 jail 约束；Web Client 只读（面板不写宿主状态）。
+- **默认状态**：SuperAgent 默认 **observe**，不会自动接单；Router 仅 essence、Worker/成本仅 fork、双主管仅 mother/essence，角色不匹配时该行明确报 `role-not-allowed`。
+- **兼容**：`engines.dsh: >=0.2.2-rc.1 <0.3.0-0`（实测基线 DSH 0.2.2-rc.1、Node.js 26）。
+
+## CI
+
+`.github/workflows/ci.yml` 在 `push main`、Pull Request 与手动触发时运行：
+
+```text
+npm ci
+npm run check        # client.js 语法 + host/worker 类型检查
+npm run build        # dist-host + dist-worker
+npm test             # 全量测试
+```
+
+矩阵：Node 24 / 26（ubuntu），另加 Node 26（windows，覆盖平台相关用例）。
+
+## 许可证
+
+本项目以 [GNU Affero General Public License v3.0 or later](LICENSE) 发布。
+`LICENSE-CORE` 是同一许可文本的副本，随核心源码一起分发。

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.10：角色矩阵放宽（Router→essence/mother，Worker/Loop→fork/essence）；面板常驻、按钮二次点击收起、正文可滚动；实时流（SSE）+ token 轮换/审计。'),
+        ))
     }
 
-    /** 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.10';
 export const FANG_CONTRACT_MIN = '3.1.14';
 export const SERVICE = Object.freeze({
     master: 'dshMaster',
@@ -33,16 +33,17 @@ export const ROW = Object.freeze({
 });
 export const ROLE = Object.freeze({ mother: 'mother', essence: 'essence', fork: 'fork' });
 /**
- * 角色矩阵（v3.2.3）：
- *   * Router 常驻原身（essence）：只评估/建票/派发，不执行代码；母体不接纳。
- *   * Worker 是研究原型，只在 fork：编译后的 Worker preset 行 master-superagent-loop 也只 fork。
- *   * 成本优化 fork；双主管 mother/essence。
+ * 角色矩阵（3.2.10）：
+ *   * Router 在 essence 与 mother 激活：只评估/建票/派发，不执行代码；fork 不注册。
+ *   * Worker / Worker Agent Loop 在 fork 与 essence 激活：原身可直接执行工单，
+ *     分身仍是默认执行体；mother 不执行。
+ *   * 成本优化仍只 fork；双主管 mother/essence。
  */
 export const ROLE_MATRIX = Object.freeze({
     'master-core': Object.freeze(Object.values(ROLE)),
-    'master-superagent-router': Object.freeze([ROLE.essence]),
-    'master-superagent-worker': Object.freeze([ROLE.fork]),
-    'master-superagent-loop': Object.freeze([ROLE.fork]),
+    'master-superagent-router': Object.freeze([ROLE.essence, ROLE.mother]),
+    'master-superagent-worker': Object.freeze([ROLE.fork, ROLE.essence]),
+    'master-superagent-loop': Object.freeze([ROLE.fork, ROLE.essence]),
     'master-cost-optimizer': Object.freeze([ROLE.fork]),
     'master-dual-manager': Object.freeze([ROLE.mother, ROLE.essence]),
 });
@@ -50,17 +51,17 @@ export const SUBPLUGIN_CATALOG = Object.freeze([
     Object.freeze({
         id: 'superagent-router', row: ROW.superagentRouter, name: '超级智能体 Router', nameEn: 'SuperAgent Router',
         roles: ROLE_MATRIX[ROW.superagentRouter], roadmap: '3.2.1',
-        description: '常驻原身：Webhook → 评估 → Ticket/Mandate → 派发；不执行代码改动。',
+        description: '常驻原身/母体：Webhook → 评估 → Ticket/Mandate → 派发；不执行代码改动。',
     }),
     Object.freeze({
         id: 'superagent-worker', row: ROW.superagentWorker, name: '超级智能体 Worker', nameEn: 'SuperAgent Worker',
         roles: ROLE_MATRIX[ROW.superagentWorker], roadmap: '3.2.1',
-        description: '每个工单一个隔离分身：在 Mandate 作用域内执行；研究原型，仅 fork。',
+        description: '每个工单一个隔离执行体：在 Mandate 作用域内执行；fork 与 essence 可用。',
     }),
     Object.freeze({
         id: 'superagent-loop', row: ROW.superagentLoop, name: 'Worker Agent Loop', nameEn: 'SuperAgent Worker Loop',
         roles: ROLE_MATRIX[ROW.superagentLoop], roadmap: '3.2.3',
-        description: '编译后的 Worker preset：有 Ticket 的 fork 自动跑多轮工具循环并流式回传。',
+        description: '编译后的 Worker preset：有 Ticket 的在 fork/essence 自动跑多轮工具循环并流式回传。',
     }),
     Object.freeze({
         id: 'cost-optimizer', row: ROW.cost, name: '成本优化', nameEn: 'HarnessMM',

package/dist-host/plugins/superagent-router.js

@@ -328,7 +328,7 @@ export function apply(ctx, config = {}) {
         id: 'superagent-router',
         name: 'dsh-master-superagent-router',
         capabilities: ['webhook-ingest', 'trust-eval', 'ticket-mandate', 'worker-dispatch', 'worker-stream', 'writeback'],
-        description: 'SuperAgent Router（仅原身；只派发不执行）',
+        description: 'SuperAgent Router（原身/母体；只派发不执行）',
     });
     // HTTP：Webhook 入口 + Worker 实时事件 + 只读状态。
     try {

package/dist-host/plugins/superagent-worker.js

@@ -67,7 +67,7 @@ export function apply(ctx, config = {}) {
         id: 'superagent-worker',
         name: 'dsh-master-superagent-worker',
         capabilities: ['ticket-context', 'mandate-scope-guard', 'worker-prompt', 'long-task-plan'],
-        description: restored.ok ? 'SuperAgent Worker 已恢复工单（仅 fork）' : 'SuperAgent Worker 待工单（仅 fork）',
+        description: restored.ok ? 'SuperAgent Worker 已恢复工单（fork/essence）' : 'SuperAgent Worker 待工单（fork/essence）',
     });
     return service;
 }

package/dist-host/superagent/router.js

@@ -4,7 +4,7 @@
 /**
  * SuperAgent Router（v3.2.1）：事件 → 评估 → Ticket/Mandate → 派发 Worker。
  *
- * Router 常驻原身（essence），**不执行代码改动**：所有执行体通过 dispatching
+ * Router 在 essence/mother 常驻，**不执行代码改动**：所有执行体通过 dispatching
  * 适配器交给瓮城 fangForker.spawn（分身），本模块不做文件/进程操作。
  * 纯核心逻辑（评估/建票）在 trust.mjs；本模块只做编排、去重、持久化与审计。
  */

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
-# dsh-Master 架构（3.2.8）
+# dsh-Master 架构（3.2.10）
 
-> 当前实现基线为 3.2.8；本文保留设计演进记录。最新实机证据与剩余限制见 `REVIEW-v3.2.7.md`。
+> 当前实现基线为 3.2.10；本文保留设计演进记录。最新实机证据与剩余限制见 `REVIEW-v3.2.7.md`。
 
 ## 1. 为什么是“并行主插件”
 
@@ -44,17 +44,17 @@
 | 行 | mother | essence（原身/元宝运行态） | fork（分身） |
 |---|---|---|---|
 | `master-core` | ✅ | ✅ | ✅ |
-| `master-superagent-router` | ❌ | ✅ | ❌ |
-| `master-superagent-worker` | ❌ | ❌ | ✅ |
-| `master-superagent-loop` | ❌ | ❌ | ✅ |
+| `master-superagent-router` | ✅ | ✅ | ❌ |
+| `master-superagent-worker` | ❌ | ✅ | ✅ |
+| `master-superagent-loop` | ❌ | ✅ | ✅ |
 | `master-cost-optimizer` | ❌ | ❌ | ✅ |
 | `master-dual-manager` | ✅ | ✅ | ❌ |
 
-- Router 是纯控制面（评估/建票/派发），不执行任何代码改动，因此可以常驻原身；
-- Worker 是研究原型，**只在 fork**，用物理隔离兜底其不稳定性；
-- 母体（mother）不接纳任何 SuperAgent 行；
-- 3.2.0 的“SuperAgent 整体仅 fork”在 3.2.1 被 Router/Worker 拆分取代，底线是
-  “原型 Worker 绝不进入母体/元主”（见 `docs/SECURITY.md`）。
+- Router 是纯控制面（评估/建票/派发），不执行任何代码改动，因此可在原身与母体常驻；
+- Worker / Worker Agent Loop 在 fork 与 essence 激活：分身仍是默认执行体，原身可直接执行工单；
+- 母体（mother）不接纳 Worker/Loop 执行体（只有 Router 与双主管）；
+- 3.2.10 起按用户要求放宽：Router 进入母体、Worker/Loop 进入原身；底线仍是
+  “执行体绝不进入母体”，fork 依旧不注册 Router（见 `docs/SECURITY.md`）。
 
 ## 3. 与瓮城的服务契约
 
@@ -104,7 +104,7 @@
 
 ## 6. 3.2.3-dev 的边界
 
-- Worker preset 已 tsc 构建到 `dist-worker/` 并接入 bundle 行（fork only，有 Ticket 自动跑）；
+- Worker preset 已 tsc 构建到 `dist-worker/` 并接入 bundle 行（fork/essence，有 Ticket 自动跑）；
 - Router 两种派发：本地 `fangForker.spawn`（母体/测试）或 HTTP 母体桥
   `POST /dsh-master/api/bridge/spawn`（Bearer bridgeToken，仅透传 DSH_MASTER_* env）；
 - Worker→Router 实时事件：per-ticket token POST `/dsh-master/api/superagent/worker-events`，

package/docs/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 3.2.10（2026-11-12，tag / GitHub Release / NPM public）
+
+**主题：按实测反馈放宽角色矩阵（Router 进入母体、Worker / Worker Agent Loop 进入原身）。**
+
+- 角色矩阵：`master-superagent-router` 由 essence-only 改为 **essence / mother**；`master-superagent-worker` 与 `master-superagent-loop` 由 fork-only 改为 **fork / essence**；`master-cost-optimizer` 仍 fork-only，`master-dual-manager` 仍 mother / essence。
+- 子插件描述与面板文案同步：Router「原身/母体」、Worker「fork/essence」、Loop「fork/essence 有票自动循环」。
+- 文档回归：`ARCHITECTURE.md` 角色矩阵与安全说明、`SECURITY.md` 强制表、`SUPERAGENT.md` 分层表与防线表、`WORKER-AGENT-LOOP.md`、README 子插件表/状态段。
+- 测试跟进：kernel 矩阵与 `roleAllowed`、core 逐角色 status、package-contract 结构断言、client 面板 stub 版本。
+- 未覆盖部分（如实记录）：瓮城分身 profile 里并未安装本 bundle（forker 的 `forkSeed` 不含 `@twinsearth/dsh-master`），因此“分身 web 自动激活”还需要把包加进 `forkSeed`（activate）或装进分身 profile —— 属瓮城配置，需另行授权。
+
+## 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.10.md

@@ -0,0 +1,32 @@
+# dsh-Master v3.2.10 发布门禁
+
+日期：2026-11-12。
+
+## 内容
+
+本版按实机反馈放宽角色矩阵：`master-superagent-router` 由 essence-only 改为 **essence / mother**；`master-superagent-worker` 与 `master-superagent-loop` 由 fork-only 改为 **fork / essence**；`master-cost-optimizer` 仍 fork-only，`master-dual-manager` 仍 mother / essence。
+
+母体仍不接纳 Worker/Loop 执行体，fork 仍不注册 Router；面板、子插件描述与角色文档同步。测试按新矩阵逐角色断言。
+
+## 发布前实测
+
+```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.10`：annotated tag；
+- GitHub Release：tarball + sha256 + manifest；
+- NPM：`@twinsearth/dsh-master@3.2.10`，`access=public`。
+
+发布不等同于安装：本流程不修改任何用户 profile（desktop / 瓮城运行态仍停在旧版，升级需另行授权）。
+
+## 已知限制
+
+- 瓮城分身的 profile 未安装本 bundle（forker 的 `forkSeed` 不含 `@twinsearth/dsh-master`），因此“分身 web 里 Worker/Loop 自动激活”仍需把包加进 `forkSeed`（activate）或装进分身 profile——属瓮城配置。
+- 矩阵放宽只改变激活范围，不改变各自的安全边界：Router 仍只派发不执行，执行体仍在 Mandate 作用域内运行。

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,14 +1,14 @@
 # 路线图：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.0 – 3.2.10`（1 个大版本 + 10 个小版本），随后 3.3.0、3.4.0。  
+> 本文保留版本演进记录；当前基线为 `3.2.10`。
 > 最新测试/实机状态与尚未完成的范围见 `REVIEW-v3.2.7.md`，下列旧版本待办不得再理解为当前状态。
 
 ## 三条主线
 
 | 版本 | 主题 | 核心组件 | 定位 |
 |---|---|---|---|
-| **3.2.0–3.2.9** | 主动性：从被动响应到主动巡航 | SuperAgent（Router/Worker） | 原身控制面 + 分身执行体的双层结构 |
+| **3.2.0–3.2.10** | 主动性：从被动响应到主动巡航 | SuperAgent（Router/Worker） | 原身控制面 + 分身执行体的双层结构 |
 | **3.3.0** | 经济性：车间成本控制器 | HarnessMM | 分身的 Token 效率优化器；EGD/GDR/CCS |
 | **3.4.0** | 组织性：人机协同制度化 | PM + PJM | 母体/元主内的元 Agent，调度分身集群 |
 

package/docs/SECURITY.md

@@ -1,4 +1,4 @@
-# 安全边界（3.2.8）
+# 安全边界（3.2.10）
 
 > 最新变化：worker-events 读取需 UI/匹配 worker token；旧 token 轮换 fail-closed；契约与 PR 网络调用全部有超时；DSH 同路径路由合并分流；飞书加密事件支持 AES-256-CBC。实机证据见 `REVIEW-v3.2.7.md`。
 
@@ -59,14 +59,14 @@
 
 | 子插件 | 允许角色 | 强制位置 |
 |---|---|---|
-| SuperAgent Router | **essence only** | `superagent-router.mjs` apply 开头 `roleAllowed(ROW_ID, role)`；母体/fork 不注册服务 |
-| SuperAgent Worker | **fork only** | `superagent-worker.mjs` 同上；母体/元主不注册 |
-| 成本优化 | **fork only** | `cost-optimizer.mjs` 同上 |
-| 双主管 | **mother / essence** | `dual-manager.mjs` 同上 |
-
-- 母体（mother）不接纳任何 SuperAgent 行；
-- Router 是控制面：不读文件、不跑命令、不改代码；所有执行体必须在 fork Worker 中；
-- Worker 是官方研究原型：物理隔离是底线，**绝不**在母体/元主启用；
+| SuperAgent Router | **essence / mother** | `superagent-router.ts` apply 开头 `roleAllowed(ROW_ID, role)`；fork 不注册服务 |
+| SuperAgent Worker | **fork / essence** | `superagent-worker.ts` 同上；母体不注册 |
+| 成本优化 | **fork only** | `cost-optimizer.ts` 同上 |
+| 双主管 | **mother / essence** | `dual-manager.ts` 同上 |
+
+- 母体（mother）只接纳 Router 与双主管，不接纳 Worker/Loop 执行体；
+- Router 是控制面：不读文件、不跑命令、不改代码；执行体在 fork Worker 或原身（3.2.10 起）中运行；
+- Worker 的物理隔离仍是默认执行路径，**绝不**在母体启用；
 - 测试逐角色断言（mother/essence/fork）服务是否存在。
 
 ## 2. 外部输入不可信

package/docs/SUPERAGENT.md

@@ -1,8 +1,8 @@
-# SuperAgent（v3.2.8）
+# SuperAgent（v3.2.10）
 
 > 把“用户从多窗口注意力调度中解放出来”的架构跃迁：**Router（常驻控制面）** 与
 > **Worker（隔离执行体）** 分离，Ticket/Mandate 约束授权，渐进式信任控制自动接单。
-> 3.2.8 为审计修复发布线。历史限制与实机证据见 `REVIEW-v3.2.7.md`。
+> 3.2.10 为角色矩阵放宽线（Router 进入母体、Worker/Loop 进入原身）。历史限制与实机证据见 `REVIEW-v3.2.7.md`。
 
 ## 1. 双层结构
 
@@ -27,8 +27,8 @@
 | 层 | 瓮城物理层 | 本仓库实现 | 角色 |
 |---|---|---|---|
 | 事件源 | 外部环境 | `src/superagent/github.mjs`、`feishu.mjs` | 被动入口 |
-| Router | 原身（安全盘） | `src/plugins/superagent-router.mjs` + `src/superagent/router.mjs` | **essence only** |
-| Worker | 分身（隔离 VM） | `src/plugins/superagent-worker.mjs` + `worker.mjs` | **fork only** |
+| Router | 原身（安全盘）/ 母体 | `src/plugins/superagent-router.ts` + `src/superagent/router.ts` | **essence / mother** |
+| Worker | 分身（隔离 VM）/ 原身 | `src/plugins/superagent-worker.ts` + `worker/` | **fork / essence** |
 | 持久化 | 会话仓 | `ticket-store.mjs`（`<dataDir>/superagent-tickets.json`） | Router 侧 |
 | 派发 | DerivedManager | `dispatch.mjs` → `fangForker.spawn({env})` | Router 侧 |
 
@@ -117,7 +117,7 @@ fangForker.spawn({
 |---|---|
 | 外部输入不可信 | 验签/Token → 归一化 → Gate；payload 永远当不可信文本 |
 | Mandate 防越权 | 不可变 Ticket；Worker 精确 scope 校验，越权退回 Router |
-| 物理隔离 | Worker 只在 fork；Router essence-only；母体不接纳任何 SuperAgent 行 |
+| 物理隔离 | Worker 默认在 fork；3.2.10 起也可在 essence；Router 在 essence/mother；母体不接纳执行体 |
 | 长任务不阻塞 | `exec_shell_in_vm` 超过 5s 返回后台 job id，`vm_job_result` 查询真实终态与输出 |
 | 失败不假装成功 | dispatch 失败 → Ticket= failed、decision=unavailable，错误码原样返回 |
 | 去重 | 事件 id 最近 500 条 FIFO（重复事件不刷新顺序）；契约幂等键随 envelope 传递 |

package/docs/WORKER-AGENT-LOOP.md

@@ -131,7 +131,7 @@ apply(ctx) // 监听 superagent:worker:start；也可直接 runWorker(ticket, de
 - **PR**：`create_pr` 工具可接真实 GitHub 客户端（`DSH_MASTER_GITHUB_TOKEN/REPO`），需要先把分支 push 到远端；
 - 回写默认关闭，失败只告警，不改变 Ticket 终态；token 不入日志/状态。
 
-- Worker preset 已用 tsc 构建到 `dist-worker/` 并接入 bundle 行 `master-superagent-loop`（fork only）；
+- Worker preset 已用 tsc 构建到 `dist-worker/` 并接入 bundle 行 `master-superagent-loop`（fork/essence）；
 - Router 生成的 per-ticket token 通过 HTTP POST 把事件实时回传 Router；前端 SSE/WS 转发待 3.2.4；
 - 回写（webhook / GitHub Issue 评论）默认关闭，按宿主配置启用；失败只告警；
 - 跨进程派发桥需要宿主配置 `bridgeToken`（母体）与 `motherUrl/motherToken`（原身），默认关闭；

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "@twinsearth/dsh-master",
-  "version": "3.2.8",
+  "version": "3.2.10",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TwinsEarth/dsh-Master.git"
+  },
+  "homepage": "https://github.com/TwinsEarth/dsh-Master#readme",
+  "bugs": {
+    "url": "https://github.com/TwinsEarth/dsh-Master/issues"
+  },
+  "engines": {
+    "dsh": ">=0.2.2-rc.1 <0.3.0-0"
+  },
   "description": "Dsh-Master（房主）：与瓮城 dsh-Fang 并行的主 Agent 插件，托管 SuperAgent Router/Worker、HarnessMM、PM+PJM。",
   "keywords": [
     "dsh",
@@ -51,8 +63,8 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test --test-force-exit test/",
-    "test:clean": "node --test --test-concurrency=1 test/",
+    "test": "node --test --test-force-exit \"test/**/*.test.mjs\" \"test/**/*.test.ts\"",
+    "test:clean": "node --test --test-concurrency=1 \"test/**/*.test.mjs\" \"test/**/*.test.ts\"",
     "test:worker": "node --test --test-force-exit test/worker-agent-loop.test.ts test/worker-tools.test.ts test/worker-llm-http.test.ts test/worker-sink-http.test.ts",
     "typecheck:worker": "tsc -p tsconfig.worker.json",
     "build:worker": "tsc -p tsconfig.worker.build.json",

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.10'
 export const FANG_CONTRACT_MIN = '3.1.14'
 
 export const SERVICE = Object.freeze({
@@ -41,16 +41,17 @@ export const ROW = Object.freeze({
 export const ROLE = Object.freeze({ mother: 'mother', essence: 'essence', fork: 'fork' })
 
 /**
- * 角色矩阵（v3.2.3）：
- *   * Router 常驻原身（essence）：只评估/建票/派发，不执行代码；母体不接纳。
- *   * Worker 是研究原型，只在 fork：编译后的 Worker preset 行 master-superagent-loop 也只 fork。
- *   * 成本优化 fork；双主管 mother/essence。
+ * 角色矩阵（3.2.10）：
+ *   * Router 在 essence 与 mother 激活：只评估/建票/派发，不执行代码；fork 不注册。
+ *   * Worker / Worker Agent Loop 在 fork 与 essence 激活：原身可直接执行工单，
+ *     分身仍是默认执行体；mother 不执行。
+ *   * 成本优化仍只 fork；双主管 mother/essence。
  */
 export const ROLE_MATRIX = Object.freeze({
   'master-core': Object.freeze(Object.values(ROLE)),
-  'master-superagent-router': Object.freeze([ROLE.essence]),
-  'master-superagent-worker': Object.freeze([ROLE.fork]),
-  'master-superagent-loop': Object.freeze([ROLE.fork]),
+  'master-superagent-router': Object.freeze([ROLE.essence, ROLE.mother]),
+  'master-superagent-worker': Object.freeze([ROLE.fork, ROLE.essence]),
+  'master-superagent-loop': Object.freeze([ROLE.fork, ROLE.essence]),
   'master-cost-optimizer': Object.freeze([ROLE.fork]),
   'master-dual-manager': Object.freeze([ROLE.mother, ROLE.essence]),
 })
@@ -59,17 +60,17 @@ export const SUBPLUGIN_CATALOG = Object.freeze([
   Object.freeze({
     id: 'superagent-router', row: ROW.superagentRouter, name: '超级智能体 Router', nameEn: 'SuperAgent Router',
     roles: ROLE_MATRIX[ROW.superagentRouter], roadmap: '3.2.1',
-    description: '常驻原身：Webhook → 评估 → Ticket/Mandate → 派发；不执行代码改动。',
+    description: '常驻原身/母体：Webhook → 评估 → Ticket/Mandate → 派发；不执行代码改动。',
   }),
   Object.freeze({
     id: 'superagent-worker', row: ROW.superagentWorker, name: '超级智能体 Worker', nameEn: 'SuperAgent Worker',
     roles: ROLE_MATRIX[ROW.superagentWorker], roadmap: '3.2.1',
-    description: '每个工单一个隔离分身：在 Mandate 作用域内执行；研究原型，仅 fork。',
+    description: '每个工单一个隔离执行体：在 Mandate 作用域内执行；fork 与 essence 可用。',
   }),
   Object.freeze({
     id: 'superagent-loop', row: ROW.superagentLoop, name: 'Worker Agent Loop', nameEn: 'SuperAgent Worker Loop',
     roles: ROLE_MATRIX[ROW.superagentLoop], roadmap: '3.2.3',
-    description: '编译后的 Worker preset：有 Ticket 的 fork 自动跑多轮工具循环并流式回传。',
+    description: '编译后的 Worker preset：有 Ticket 的在 fork/essence 自动跑多轮工具循环并流式回传。',
   }),
   Object.freeze({
     id: 'cost-optimizer', row: ROW.cost, name: '成本优化', nameEn: 'HarnessMM',

package/src/plugins/superagent-router.ts

@@ -323,7 +323,7 @@ export function apply(ctx, config = {}) {
     id: 'superagent-router',
     name: 'dsh-master-superagent-router',
     capabilities: ['webhook-ingest', 'trust-eval', 'ticket-mandate', 'worker-dispatch', 'worker-stream', 'writeback'],
-    description: 'SuperAgent Router（仅原身；只派发不执行）',
+    description: 'SuperAgent Router（原身/母体；只派发不执行）',
   })
 
   // HTTP：Webhook 入口 + Worker 实时事件 + 只读状态。

package/src/plugins/superagent-worker.ts

@@ -79,7 +79,7 @@ export function apply(ctx, config = {}) {
     id: 'superagent-worker',
     name: 'dsh-master-superagent-worker',
     capabilities: ['ticket-context', 'mandate-scope-guard', 'worker-prompt', 'long-task-plan'],
-    description: restored.ok ? 'SuperAgent Worker 已恢复工单（仅 fork）' : 'SuperAgent Worker 待工单（仅 fork）',
+    description: restored.ok ? 'SuperAgent Worker 已恢复工单（fork/essence）' : 'SuperAgent Worker 待工单（fork/essence）',
   })
   return service
 }

package/src/superagent/router.ts

@@ -5,7 +5,7 @@
 /**
  * SuperAgent Router（v3.2.1）：事件 → 评估 → Ticket/Mandate → 派发 Worker。
  *
- * Router 常驻原身（essence），**不执行代码改动**：所有执行体通过 dispatching
+ * Router 在 essence/mother 常驻，**不执行代码改动**：所有执行体通过 dispatching
  * 适配器交给瓮城 fangForker.spawn（分身），本模块不做文件/进程操作。
  * 纯核心逻辑（评估/建票）在 trust.mjs；本模块只做编排、去重、持久化与审计。
  */