dsh-device-fleet 0.1.0-dev.11 → 0.1.0-dev.13

package/README.md

@@ -9,7 +9,7 @@ DeepSeek Harness 的设备联邦插件：把登录同一账号、且都安装本
 - ✅ **Host 插件 + 直调 MVP（代码完成、单测通过，待真实 DSH 安装联调）**：`fleet_list` / `fleet_tools` / `fleet_call` + `fleet_read` / `fleet_fetch` / `fleet_run`、Tool Policy、Execution Slot、审批 fail-closed
 - ✅ **审批收件箱逻辑层（dev.7）**：`fleet_approvals` / `fleet_approve` / `fleet_deny`，ask 档排队、超时 fail-closed、once/ttl 授权、`fleet_simulate_request` 本机演练；Client 审批面板待做
 - ✅ **Room 逻辑层（dev.8，单机模拟）**：`room_create` / `room_add_local` / `room_send` / `room_messages` / `room_status` / `room_task_*` / `room_close`；本地真实 agent 参与者、寻址唤醒、Room Board 串行交接；单机仿真验证通过
-- ✅ **审批面板 UI（dev.10）**：Host `/device-fleet/approvals` HTTP 数据面 + Client `shell.overlay` 浮动审批按钮/面板（允许一次/15 分钟/拒绝）；单测 14/14；刷新页面后可见
+- ✅ **审批面板 UI（dev.12，已验证）**：Host `/device-fleet/approvals` HTTP 数据面 + Client 入口在 Settings 上方、居中审批对话框（允许一次/15 分钟/拒绝）；用户点击「允许」后 Host 列表清空，端到端闭环
 - ⏳ 远程参与者传输、房间视图、插件重载 rehydrate、SSE 推送（下一步）
 
 ## 安装（开发版）

package/client.js

@@ -148,8 +148,8 @@ window.__ModuleLoader__.load({
 
     function Panel() {
       const current = useStore();
-      if (!current.open) return null;
       useEffect(() => {
+        if (!current.open) return undefined;
         const onKey = (event) => {
           if (event.key === 'Escape') {
             store.open = false;
@@ -158,7 +158,8 @@ window.__ModuleLoader__.load({
         };
         window.addEventListener('keydown', onKey);
         return () => window.removeEventListener('keydown', onKey);
-      }, []);
+      }, [current.open]);
+      if (!current.open) return null;
       return h(
         'div',
         {
@@ -212,6 +213,294 @@ window.__ModuleLoader__.load({
       );
     }
 
+    const cardStyle = {
+      border: '1px solid var(--dsw-alias-border, #3a3a3a)',
+      borderRadius: 10,
+      padding: 12,
+      background: 'var(--dsw-alias-surface-raised, #1f1f1f)',
+      marginBottom: 10,
+    };
+    const sectionTitle = { fontSize: 12, opacity: 0.65, textTransform: 'uppercase', letterSpacing: '.04em', marginBottom: 6 };
+    const pill = (text, tone) =>
+      h(
+        'span',
+        {
+          style: {
+            display: 'inline-block',
+            padding: '1px 7px',
+            borderRadius: 999,
+            fontSize: 11,
+            border: '1px solid ' + (tone === 'ok' ? 'var(--dsw-alias-accent, #2f6fed)' : 'var(--dsw-alias-border, #3a3a3a)'),
+            color: tone === 'ok' ? 'var(--dsw-alias-accent, #2f6fed)' : 'inherit',
+            opacity: tone === 'muted' ? 0.7 : 1,
+            marginRight: 6,
+          },
+        },
+        text,
+      );
+
+    const fmtTime = (value) => {
+      try {
+        return new Date(value).toLocaleTimeString();
+      } catch {
+        return '';
+      }
+    };
+
+    function FleetIcon({ size = 20, active = false }) {
+      return h(
+        'svg',
+        {
+          width: size,
+          height: size,
+          viewBox: '0 0 24 24',
+          fill: 'none',
+          stroke: 'currentColor',
+          strokeWidth: 1.8,
+          strokeLinecap: 'round',
+          'aria-hidden': true,
+          style: { opacity: active ? 1 : 0.75 },
+        },
+        h('circle', { cx: 12, cy: 12, r: 8.5 }),
+        h('ellipse', { cx: 12, cy: 12, rx: 3.6, ry: 8.5 }),
+        h('path', { d: 'M3.8 12h16.4' }),
+      );
+    }
+
+    function FleetConsole() {
+      const [tab, setTab] = useState('devices');
+      const [overview, setOverview] = useState(null);
+      const [rooms, setRooms] = useState([]);
+      const [selectedRoom, setSelectedRoom] = useState(null);
+      const [roomDetail, setRoomDetail] = useState(null);
+      const [error, setError] = useState('');
+
+      useEffect(() => {
+        let disposed = false;
+        const tick = async () => {
+          try {
+            const response = await fetch('/device-fleet/overview', { headers: { accept: 'application/json' } });
+            if (!response.ok) throw new Error('HTTP ' + response.status);
+            const data = await response.json();
+            if (!disposed) {
+              setOverview(data);
+              setRooms(Array.isArray(data.rooms) ? data.rooms : []);
+              setError('');
+            }
+          } catch (problem) {
+            if (!disposed) setError(String(problem.message ?? problem));
+          }
+        };
+        tick();
+        const timer = setInterval(tick, 3000);
+        return () => {
+          disposed = true;
+          clearInterval(timer);
+        };
+      }, []);
+
+      useEffect(() => {
+        if (!selectedRoom) {
+          setRoomDetail(null);
+          return undefined;
+        }
+        let disposed = false;
+        const load = async () => {
+          try {
+            const response = await fetch('/device-fleet/rooms/' + encodeURIComponent(selectedRoom), { headers: { accept: 'application/json' } });
+            if (!response.ok) throw new Error('HTTP ' + response.status);
+            const data = await response.json();
+            if (!disposed) setRoomDetail(data.room ?? null);
+          } catch {
+            if (!disposed) setRoomDetail(null);
+          }
+        };
+        load();
+        const timer = setInterval(load, 3000);
+        return () => {
+          disposed = true;
+          clearInterval(timer);
+        };
+      }, [selectedRoom]);
+
+      const decide = async (id, action, scope) => {
+        await fetch('/device-fleet/approvals/decide', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({ id, action, ...(scope ? { scope } : {}) }),
+        });
+        setOverview((current) => (current ? { ...current, approvals: (current.approvals ?? []).filter((item) => item.id !== id) } : current));
+      };
+
+      const tabs = [
+        ['devices', '设备'],
+        ['rooms', '房间'],
+        ['approvals', '审批'],
+      ];
+      const header = h(
+        'div',
+        { style: { display: 'flex', alignItems: 'center', gap: 12, flexWrap: 'wrap', marginBottom: 12 } },
+        h('strong', { style: { fontSize: 15 } }, '设备联邦'),
+        overview ? pill('本机 ' + (overview.name ?? '') + ' · ' + overview.pluginVersion, 'muted') : null,
+        h('span', { style: { flex: 1 } }),
+        ...tabs.map(([id, label]) =>
+          h(
+            'button',
+            {
+              key: id,
+              type: 'button',
+              onClick: () => setTab(id),
+              style: {
+                padding: '4px 10px',
+                borderRadius: 999,
+                border: '1px solid ' + (tab === id ? 'var(--dsw-alias-accent, #2f6fed)' : 'var(--dsw-alias-border, #3a3a3a)'),
+                background: tab === id ? 'var(--dsw-alias-accent, #2f6fed)' : 'transparent',
+                color: 'inherit',
+                cursor: 'pointer',
+                fontSize: 12,
+              },
+            },
+            label + (id === 'approvals' && (overview?.approvals?.length ?? 0) > 0 ? ' ' + overview.approvals.length : ''),
+          ),
+        ),
+      );
+
+      if (!overview) {
+        return h('div', { style: { padding: 16 } }, header, h('div', { style: { opacity: 0.7 } }, error ? '加载失败：' + error : '加载中…'));
+      }
+
+      let body = null;
+      if (tab === 'devices') {
+        const connected = new Set(Array.isArray(overview.connected) ? overview.connected : []);
+        body = h(
+          'div',
+          null,
+          h('div', { style: cardStyle },
+            h('div', { style: sectionTitle }, '本机'),
+            h('div', null, overview.name + ' · ' + overview.deviceId),
+            h('div', { style: { opacity: 0.75, fontSize: 12, marginTop: 4 } },
+              '直连 ' + (overview.direct ? overview.direct.host + ':' + overview.direct.port : '未监听') +
+              ' · relay ' + (overview.relay?.online ? '在线' : '离线') +
+              ' · 发现 ' + ((overview.discovery?.peers ?? []).length) + ' 个'),
+          ),
+          h('div', { style: cardStyle },
+            h('div', { style: sectionTitle }, 'Fleet 成员（' + (overview.roster?.length ?? 0) + ' 台已配对）'),
+            (overview.roster ?? []).length === 0
+              ? h('div', { style: { opacity: 0.7, fontSize: 12 } }, '还没有配对设备；在任一台设备上生成邀请码完成配对。')
+              : (overview.roster ?? []).map((member) =>
+                  h('div', { key: member.deviceId, style: { display: 'flex', gap: 8, alignItems: 'center', padding: '4px 0' } },
+                    h('span', { style: { flex: 1 } }, member.name + ' · ' + member.deviceId.slice(0, 8) + '…'),
+                    connected.has(member.deviceId) ? pill('在线', 'ok') : pill('离线', 'muted'),
+                  ),
+                ),
+          ),
+          (overview.peerHints ?? []).length > 0
+            ? h('div', { style: cardStyle },
+                h('div', { style: sectionTitle }, '回连地址'),
+                ...overview.peerHints.map((hint, index) =>
+                  h('div', { key: index, style: { fontSize: 12, fontFamily: 'ui-monospace, monospace', opacity: 0.8 } }, hint.host + ':' + hint.port),
+                ),
+              )
+            : null,
+        );
+      } else if (tab === 'rooms') {
+        body = h(
+          'div',
+          { style: { display: 'flex', gap: 14, alignItems: 'flex-start', flexWrap: 'wrap' } },
+          h('div', { style: { flex: '1 1 260px', minWidth: 240 } },
+            h('div', { style: sectionTitle }, '房间（' + rooms.length + '）'),
+            rooms.length === 0
+              ? h('div', { style: { opacity: 0.7, fontSize: 12 } }, '还没有房间。让 agent 在当前会话执行 room_create 升级为 Room Host。')
+              : rooms.map((room) =>
+                  h(
+                    'button',
+                    {
+                      key: room.roomId,
+                      type: 'button',
+                      onClick: () => setSelectedRoom(room.roomId === selectedRoom ? null : room.roomId),
+                      style: {
+                        ...cardStyle,
+                        display: 'block',
+                        width: '100%',
+                        textAlign: 'left',
+                        cursor: 'pointer',
+                        borderColor: selectedRoom === room.roomId ? 'var(--dsw-alias-accent, #2f6fed)' : undefined,
+                        marginBottom: 8,
+                      },
+                    },
+                    h('div', { style: { fontWeight: 600 } }, 'Room ' + room.roomId.slice(-8)),
+                    h('div', { style: { fontSize: 12, opacity: 0.7, marginTop: 3 } },
+                      room.members.length + ' 名成员 · ' + room.messageCount + ' 条消息 · ' + room.tasks + ' 个任务'),
+                  ),
+                ),
+          ),
+          h('div', { style: { flex: '2 1 420px', minWidth: 320 } }, selectedRoom ? renderRoomDetail(roomDetail) : h('div', { style: { opacity: 0.65, fontSize: 12 } }, '选择一个房间查看成员、时间线与看板。')),
+        );
+      } else {
+        const approvals = overview.approvals ?? [];
+        body = h(
+          'div',
+          { style: cardStyle },
+          h('div', { style: sectionTitle }, '待审批请求（' + approvals.length + '）'),
+          approvals.length === 0
+            ? h('div', { style: { opacity: 0.7, fontSize: 12 } }, '暂无待审批请求')
+            : approvals.map((item) =>
+                h('div', { key: item.id, style: { borderTop: '1px solid var(--dsw-alias-border, #333)', padding: '9px 0' } },
+                  h('div', { style: { fontWeight: 600 } }, (item.capability || 'tool') + (item.tool ? ' / ' + item.tool : '')),
+                  h('div', { style: { opacity: 0.75, fontSize: 12 } }, '来自 ' + item.fromDeviceId + ' · ' + Math.max(0, Math.round(item.expiresInMs / 1000)) + 's 后超时'),
+                  item.reason ? h('div', { style: { opacity: 0.7, fontSize: 12 } }, item.reason) : null,
+                  h('div', { style: { display: 'flex', gap: 6, marginTop: 5, flexWrap: 'wrap' } },
+                    smallButton('允许一次', () => decide(item.id, 'approve'), 'allow'),
+                    smallButton('允许 15 分钟', () => decide(item.id, 'approve', 'ttl'), 'allow'),
+                    smallButton('拒绝', () => decide(item.id, 'deny'), 'deny'),
+                  ),
+                ),
+              ),
+        );
+      }
+
+      return h('div', { style: { padding: '14px 16px', height: '100%', overflow: 'auto', boxSizing: 'border-box' } }, header, body);
+    }
+
+    function renderRoomDetail(detail) {
+      if (!detail) return h('div', { style: { opacity: 0.65, fontSize: 12 } }, '加载房间…');
+      return h(
+        'div',
+        null,
+        h('div', { style: cardStyle },
+          h('div', { style: sectionTitle }, '成员'),
+          ...detail.members.map((member) =>
+            h('div', { key: member.memberId, style: { padding: '3px 0', fontSize: 12 } },
+              pill(member.role, member.role === 'host' ? 'ok' : 'muted'),
+              member.name + ' · ' + member.memberId,
+            ),
+          ),
+        ),
+        h('div', { style: cardStyle },
+          h('div', { style: sectionTitle }, '看板（' + detail.tasks.length + '）'),
+          detail.tasks.length === 0
+            ? h('div', { style: { opacity: 0.7, fontSize: 12 } }, '暂无任务')
+            : detail.tasks.map((task) =>
+                h('div', { key: task.id, style: { padding: '4px 0', fontSize: 12 } },
+                  pill(task.status, task.status === 'done' ? 'ok' : 'muted'),
+                  task.title + ' · owner ' + task.owner + (task.dependsOn.length ? ' · deps ' + task.dependsOn.length : ''),
+                ),
+              ),
+        ),
+        h('div', { style: cardStyle },
+          h('div', { style: sectionTitle }, '时间线'),
+          detail.messages.length === 0
+            ? h('div', { style: { opacity: 0.7, fontSize: 12 } }, '暂无消息')
+            : detail.messages.map((message) =>
+                h('div', { key: message.id, style: { padding: '5px 0', borderTop: '1px solid var(--dsw-alias-border, #333)' } },
+                  h('div', { style: { fontSize: 11, opacity: 0.6 } }, '[' + fmtTime(message.createdAt) + '] ' + message.fromLabel + ' → ' + message.to.join(', ')),
+                  h('div', { style: { whiteSpace: 'pre-wrap', marginTop: 2 } }, message.text),
+                ),
+              ),
+        ),
+      );
+    }
+
     return {
       inject: ['slots'],
       apply(ctx) {
@@ -219,9 +508,15 @@ window.__ModuleLoader__.load({
         ctx.slots.inject('sidebar.footer.action', () =>
           ctx.slots.register({ name: 'sidebar.footer.action', id: 'fleet-approvals', order: 5, label: 'Fleet 审批' }, Trigger),
         );
-        ctx.slots.inject('shell.overlay', () =>
-          ctx.slots.register({ name: 'shell.overlay', id: 'fleet-approvals-panel', order: 10 }, Panel),
+        // shell.overlay is a root slot that exists from boot (the dev.10 build
+        // rendered from a direct registration); register directly so the dialog
+        // mounts even if the lazy inject callback never fires.
+        ctx.slots.register({ name: 'shell.overlay', id: 'fleet-approvals-panel', order: 10 }, Panel);
+        // Global Fleet console: sidebar icon + matching main panel.
+        ctx.slots.inject('sidebar.panellist', () =>
+          ctx.slots.register({ name: 'sidebar.panellist', id: 'fleet', order: 20, label: '设备联邦' }, FleetIcon),
         );
+        ctx.slots.register({ name: 'main', key: 'fleet' }, FleetConsole);
       },
     };
   },

package/docs/notes/approval-panel-ui.md

@@ -1,38 +1,38 @@
-# 审批面板 UI（dev.9 / dev.10）
+# 审批面板 UI（dev.9 → dev.12）
 
 ## Host 数据面
 
 `src/host/approval-web.js`：
 
-- `GET /device-fleet/approvals` → `{ approvals: [...] }`（来自 ApprovalInbox.list）；
+- `GET /device-fleet/approvals` → `{ approvals: [...] }`（ApprovalInbox.list）；
 - `POST /device-fleet/approvals/decide`，body `{ id, action: "approve"|"deny", scope?, reason? }` → 决策走 ApprovalInbox；
-- 仅注册在 DSH web 载体的本地监听上；决策仍受 ApprovalInbox 的超时/关闭/未知 id 约束；
-- 纯逻辑 `createApprovalApi` 与路由注册分离，便于单测；路由在插件卸载时 dispose。
+- 路由注册在插件 apply 中、卸载时 dispose；纯逻辑 `createApprovalApi` 与路由分离便于单测。
 
 ## Client 半
 
-`client.js`（闭包工厂，`window.__ModuleLoader__.load`，id = `dsh-device-fleet`）：
+`client.js`（闭包工厂，id = `dsh-device-fleet`）：
 
-- 注册 `shell.overlay`（root）列表项 `fleet-approvals`，右下角浮动按钮「Fleet 审批 (n)」；
-- 2.5s 轮询 `/device-fleet/approvals`，有请求时按钮高亮；点开面板显示来源设备/能力/工具/参数摘要/剩余超时；
-- 按钮：允许一次 / 允许 15 分钟（ttl）/ 拒绝，POST 到 decide 后从列表移除；
-- 使用 `--dsw-alias-*` token（带 fallback），不覆盖宿主根、不读其他插件 DOM。
+- **入口**：`sidebar.footer.action`（Settings 上方），显示 `🛰️ 审批`，有待审批时带数字并高亮；不再占用 `shell.overlay` 右下角，避免与任务列表 UI 重叠；
+- **面板**：`shell.overlay` 直接注册的居中模态对话框（遮罩、Esc/点遮罩/收起关闭）；
+- 2.5s 轮询 `/device-fleet/approvals`；按钮「允许一次 / 允许 15 分钟(ttl) / 拒绝」POST 到 decide；
+- 共享模块级 store + `ctx.effect` 启动/清理轮询；使用 `--dsw-alias-*` token（带 fallback）。
 
-`package.json` 增加 `dsh.client = { platform: web, immediately: true, inject: ["@deepseek-ai/dsh-client-runtime"] }` 与 `./client` 导出、`files` 包含 client.js。
+## 修复记录
 
-## 验证
+- dev.10：右下角浮动按钮可用，但会遮挡任务列表（用户截图确认）；
+- dev.11：入口迁到 sidebar footer；发现点击无反应；
+- dev.12：修复 `Panel` 的条件 Hook 顺序（关闭时提前 return，打开后才调 `useEffect`，导致 React 渲染报错）；同时把 `shell.overlay` 改回直接注册（dev.10 已验证可用路径）。
 
-- 单测：`approval HTTP API lists and decides requests, and registers two routes`（列表/决策/路由注册/GET handler）；
-- Host 单测总计 **14/14** 通过，网络层 9/9；
-- Host 路由注册：插件 dev.9/10 激活成功（无重复路由错误）；
-- Client 视觉：**未验证**（无浏览器控制；需要刷新页面加载 client bundle），`node --check client.js` 通过。
+## 端到端验证（已完成）
 
-## 使用
-
-刷新当前 Web 页面（F5）后，右下角应出现「Fleet 审批」浮动按钮。用 `fleet_simulate_request` 造一条请求即可看到面板内容；点击允许/拒绝后 Host 端 `fleet_approvals` 同步清空。
+1. 刷新页面后 Settings 上方出现「🛰️ 审批」；
+2. 点击后居中对话框正常打开并显示待审批条目（用户确认）；
+3. `fleet_simulate_request` 造请求 `dae59ce4-…`（run/pwsh，simulated-device-B）；
+4. 用户在面板点击「允许一次」；
+5. Host `fleet_approvals` 返回 `(no pending approvals)` → **UI → HTTP → ApprovalInbox 写回链路闭环**。
 
 ## 限制
 
-- 面板轮询而非推送，规模大时应换 SSE/事件；
-- 路由未额外鉴权（依赖 web 载体自身的本地/会话边界）；
-- 面板不含房间视图（下一版可加 Room 时间线/看板页）。
+- 轮询而非 SSE 推送；
+- 路由未额外鉴权（依赖 web 载体本地/会话边界）；
+- 面板暂无房间视图（时间线/看板页下一步）。

package/docs/notes/dev-release.md

@@ -39,19 +39,19 @@ dsh plugin --profile desktop add dsh-device-fleet@dev
 - 邀请里新增 `endpoints`（创建者的局域网/热点 IPv4 + direct 端口），加入方重启后自动向这些地址回连，绕开组播发现失败；
 - 新增 `fleet_status`（deviceId/直连端口/发现/连接/roster/hints）与 `fleet_connect(host, port)`（手动直连，成功后会从握手学到对端 deviceId）；
 - `fleet_list` 仍是本地视图；配对成功后双方 roster 会自动固定对端公钥。
-## 0.1.0-dev.10（稳定化）
+## 0.1.0-dev.12（稳定化）
 
 - 直连端口可固定（profile `direct.port`），插件重载不再换端口；
 - 连接断开后自动重试已知地址（不再只在启动时试一次）；
 - `fleet_connect` 手动地址会持久化到 `peer-hints.json`，重启后继续回连；
 - 新增 `fleet_delegate`（dev.5）：目标设备用 `SubagentProvider` + `delivery:'caller'` 跑 agent 并返回最终结果。
-## 0.1.0-dev.10（审批收件箱，逻辑层）
+## 0.1.0-dev.12（审批收件箱，逻辑层）
 
 - 新增 `ApprovalInbox`：ask 档请求排队、超时 fail-closed、approve（once/ttl）/deny、关闭时全部失败关闭；
 - 直调与委派的 ask 档改为等待本机收件箱结果（不再一律拒绝）；
 - 新工具：`fleet_approvals` / `fleet_approve` / `fleet_deny`；`fleet_simulate_request`（仅 `approvals.simulation: true`）用于本机无第二台设备时演练流程；
 - 审批面板（Client UI）与通知尚未实现，当前通过工具/后续 UI 应答。
-## 0.1.0-dev.10（Room 逻辑层，本机模拟）
+## 0.1.0-dev.12（Room 逻辑层，本机模拟）
 
 - `RoomService`：当前会话升级为 Room Host；本地模拟参与者（真实 DSH session/agent）；
 - 寻址消息：`room_send` 只唤醒被点名成员，Host 会话写权威 `room/message` 事件；
@@ -59,9 +59,15 @@ dsh plugin --profile desktop add dsh-device-fleet@dev
 - Room Board：`room_task_add/update/list`，`dependsOn` 串行交接（前置完成时唤醒下一个 owner），无依赖任务并行不受影响；
 - 工具：`room_create / room_add_local / room_remove_member / room_send / room_messages / room_status / room_task_* / room_close`；
 - 远程参与者传输与 Client UI 未做（下一步）。
-## 0.1.0-dev.10（审批面板 UI，第一版）
+## 0.1.0-dev.12（审批面板 UI，第一版）
 
 - Host 新增本地 HTTP 数据面：GET `/device-fleet/approvals`、POST `/device-fleet/approvals/decide`（仅本机 web 载体，决策仍走 ApprovalInbox）；
 - Client half：`client.js` 闭包工厂，注册 `shell.overlay` 浮动「Fleet 审批」按钮 + 面板，轮询待审批列表，支持允许一次 / 允许 15 分钟 / 拒绝；
 - package.json 增加 `dsh.client` 与 `./client` 导出；`files` 增加 client.js；
-- Client 视觉验证需要刷新页面；当前无浏览器控制，仅验证了 bundle 语法与 Host 路由注册。
+- Client 视觉验证需要刷新页面；当前无浏览器控制，仅验证了 bundle 语法与 Host 路由注册。
+## 0.1.0-dev.12（审批入口不遮挡）
+
+- 触发按钮从右下角浮动改为 `sidebar.footer.action`（设置旁边），不再遮挡任务列表/内容面板；
+- 审批 inbox 改为点击后居中的模态对话框（带遮罩，Esc/点遮罩关闭）；
+- 轮询在 Client apply 中启动并由 ctx.effect 清理；待审批数量作为按钮徽标；
+- 已实测：面板点击「允许」后 Host `fleet_approvals` 清空。

package/docs/notes/ui-surface-audit.md

@@ -0,0 +1,93 @@
+# UI 呈现缺口审计（2026-11-09）
+
+## 现状盘点
+
+当前插件已实现的 UI 只有**审批面板**（dev.12）：
+
+- 入口：`sidebar.footer.action` 的「🛰️ 审批」；
+- 内容：`shell.overlay` 居中对话框，待审批列表 + 允许一次/15 分钟/拒绝；
+- 数据：Host `/device-fleet/approvals`、`/device-fleet/approvals/decide`。
+
+其余**全部**依靠模型工具文本输出或 profile YAML 配置，没有任何可视化：
+
+| 设计要素 | 当前呈现方式 | 缺口 |
+|---|---|---|
+| 设备列表 / 在线状态 / 直连地址 / relay / 发现 | `fleet_status` 文本 | 无设备页，无法看设备拓扑与连接路径 |
+| 配对：邀请码、加入、手动地址、设备移除 | `fleet_invite`/`fleet_join`/`fleet_connect` 工具 | 无配对向导，邀请码需在聊天里传 |
+| 插件配置（deviceName/direct/discovery/relay/execution/policy/approvals/prompt） | profile `cordis.patch.yml` | 完全无 UI，改配置要手改 YAML + 重启 |
+| Room 列表 / 房间状态 | `room_status`、`room_messages` 文本 | 无房间列表/视图 |
+| Room 成员（设备 × agent、host/local/remote） | `room_status` JSON | 无成员可视化，看不出"不同设备不同 agent" |
+| Room 时间线（用户可见完整对话） | `room_messages` 文本 | 无时间线 UI，无消息流式更新 |
+| Room 发消息 / 点名 | `room_send` 工具 | 无输入框/@成员操作 |
+| Room Board（任务、owner、状态、依赖、交接） | `room_task_*` 文本 | 无看板视图 |
+| 房间策略（invite/join/maxMembers/boardWrite） | 创建参数 | 无查看/编辑 |
+| 审批历史 / TTL 授权管理 | 收件箱列表（仅 pending） | 无历史、无授权撤销 |
+| 委派（fleet_delegate） | 工具结果文本 | 无历史/运行状态/中断入口 |
+| 直调审计（谁调了哪台设备什么工具） | 会话轨迹里 | 无 Fleet 维度审计页 |
+| 首次配对引导 | 无 | 新设备没有任何向导 |
+| 错误/诊断 | `fleet_status` + 日志 | 无连接诊断页 |
+| 通知 | 无 | 新审批/新消息没有系统通知 |
+| 国际化 | 中文硬编码 | 未接 Client locale 服务 |
+| 多窗口/实时 | 审批 2.5s 轮询 | Room/设备状态无推送，多窗口不同步 |
+
+## 关键基础设施缺口（UI 之前必须先补）
+
+1. **Host 读模型 API 不足**：目前只有 approvals 两条路由；需要
+   - `GET /device-fleet/overview`：本机身份/版本/直连/relay/discovery/roster/connected/peerHints；
+   - `GET /device-fleet/rooms`、`GET /device-fleet/rooms/:id`：成员、策略、transcript、tasks；
+   - `GET /device-fleet/events`（SSE）或长轮询：状态变化推送。
+2. **配置写路径缺失**：Cordis config 来自 profile patch，运行时不可写。需要确定：
+   - 方案 A（推荐）：`$DSH_HOME/device-fleet/config-overrides.json` + apply 时合并，UI 写该文件；保存后提示"重载插件生效"（或调用 Host 重新加载）；
+   - 方案 B：直接改写 profile `cordis.patch.yml`（风险高：破坏注释/结构，需备份）。
+3. **Room 状态无持久化/rehydrate**：RoomService 是内存 Map，插件重载/DSH 重启后房间消失。UI 之前应先做基于 host session 事件的 rehydrate，否则"房间视图"打开是空的。
+4. **UI 操作的身份与授权**：UI 里的"发消息/改任务/关房"是以**用户**身份还是 host agent 身份？需要 Room 服务暴露 user 动作并校验房主/成员权限。
+5. **Slot/设计系统**：已确认可用的官方扩展点：
+   - `sidebar.panellist`（全局面板图标）+ `main`（keyed 主面板）→ Fleet 控制台；
+   - `settings.section`（设置页）或 `plugins.bundle.config`（插件配置页，key = 包名）→ 配置 UI；
+   - `shell.overlay` → 对话框/房间详情；
+   - `sidebar.footer.action` → 快捷入口（审批已用）。
+6. **多设备语义呈现**：房间成员需要 "设备（名称/在线/连接路径）× agent（session/角色）" 两级标签；当前 member 只有 `local:session-…`/`host:…` 字符串，远程成员还没有实体，需要先接远程参与者传输。
+
+## 建议的信息架构
+
+```
+侧栏
+├─ 全局面板图标「Fleet」 (sidebar.panellist: id=fleet)
+│   └─ main keyed "fleet" 主面板
+│        ├─ 设备 Tab：本机状态、roster、在线/离线、直连/relay、配对按钮、诊断
+│        ├─ 房间 Tab：房间列表 → 房间详情（成员树、时间线、看板、策略）
+│        └─ 审批 Tab：待审批 + 历史 + 授权管理
+├─ Settings 上方「🛰️ 审批」快捷入口（已实现）
+└─ Settings → 插件 → Device Fleet 配置页
+     (plugins.bundle.config key "dsh-device-fleet" 或 plugins.row.config "dsh-device-fleet#device-fleet")
+     分块：设备/网络 · 执行上下文 · 远端权限(Tool Policy) · 本地审批 · 高级
+```
+
+## 分阶段实施计划
+
+**Phase A：Fleet 控制台（只读）**
+- Host `/overview`、`/rooms`、`/rooms/:id` API；
+- `sidebar.panellist` + `main` 主面板，三个 Tab：设备 / 房间 / 审批（待审批 + 只读时间线/看板）；
+- 先解决 Room rehydrate，否则只读视图无内容。
+
+**Phase B：配置 UI**
+- `plugins.bundle.config` 注册配置页；
+- 字段分组 + 校验 + 当前值显示；
+- 保存走 overrides 文件（方案 A），保存后提示重载插件；policy 的 roots/tools 用列表编辑器。
+
+**Phase C：交互动作**
+- 房间：以用户身份发消息（点名选择成员）、看板任务增改/交接、关房、邀请/移除成员（权限校验）；
+- 设备：配对向导（邀请码生成/扫码式复制、手动地址连接、移除设备）；
+- 审批：历史列表 + ttl 授权撤销。
+
+**Phase D：体验与可靠性**
+- SSE/事件推送替代轮询，多窗口同步；
+- 通知（新审批/新房间消息）；
+- Client locale（zh/en），a11y，空状态/引导；
+- 插件重载 rehydrate、房间日志持久补发（ADR-0018）。
+
+## 需要你确认的决策
+
+1. 配置写路径：选 **overrides 文件（推荐）** 还是直接改 profile YAML？
+2. 房间 UI 动作的身份：以 **用户** 身份（推荐，符合 ADR-0007 用户发言与设备解耦）还是 host agent 身份？
+3. 先做 Phase A（控制台只读）还是先做 Phase B（配置页）？我建议按 A → B → C → D。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-device-fleet",
-  "version": "0.1.0-dev.11",
+  "version": "0.1.0-dev.13",
   "description": "DeepSeek Harness device fleet: enroll devices, direct-call remote tools, shared Rooms with lazy-woken agents, and delegated subagents across devices.",
   "type": "module",
   "main": "src/plugin/index.js",

package/src/host/index.js

@@ -6,5 +6,6 @@ export * from './direct-call.js'
 export * from './delegation.js'
 export * from './approval-inbox.js'
 export * from './approval-web.js'
+export * from './ui-web.js'
 export * from './room-service.js'
 export * from './tools.js'

package/src/host/room-service.js

@@ -4,8 +4,11 @@
 // addressed message, so addressing/wake/visibility and board handoff can be
 // exercised before the remote transport and the client UI exist.
 import { randomUUID } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
 
 const MAX_MESSAGE_CHARS = 20_000
+const STATE_VERSION = 1
 
 const DEFAULT_POLICY = Object.freeze({
   invite: 'members',
@@ -29,13 +32,85 @@ export class RoomService {
    * @param {object} options.sessionController ctx.sessionController
    * @param {(input: object) => object} [options.createUserMessage] dsh-llm helper
    * @param {(now?: number) => number} [options.now]
+   * @param {string} [options.stateFile] JSON file used to rehydrate rooms after a reload
    */
-  constructor({ sessionController, createUserMessage = null, now = Date.now } = {}) {
+  constructor({ sessionController, createUserMessage = null, now = Date.now, stateFile = null } = {}) {
     this.sessionController = sessionController
     this.createUserMessage = createUserMessage
     this.now = now
+    this.stateFile = stateFile
     /** @type {Map<string, any>} */
     this.rooms = new Map()
+    if (stateFile) this.load()
+  }
+
+  /** Rehydrate active rooms from the persisted snapshot (agents resolve lazily). */
+  load() {
+    if (!this.stateFile || !existsSync(this.stateFile)) return
+    try {
+      const data = JSON.parse(readFileSync(this.stateFile, 'utf8'))
+      if (!data || data.version !== STATE_VERSION || !Array.isArray(data.rooms)) return
+      for (const stored of data.rooms) {
+        if (!stored || typeof stored.roomId !== 'string' || !Array.isArray(stored.members)) continue
+        const members = new Map()
+        for (const member of stored.members) {
+          if (!member || typeof member.memberId !== 'string') continue
+          members.set(member.memberId, { ...member, agent: undefined })
+        }
+        if (!members.has(hostMemberId(stored.roomId))) continue
+        this.rooms.set(stored.roomId, {
+          roomId: stored.roomId,
+          createdAt: Number.isFinite(stored.createdAt) ? stored.createdAt : this.now(),
+          hostSessionId: typeof stored.hostSessionId === 'string' ? stored.hostSessionId : stored.roomId,
+          policy: { ...DEFAULT_POLICY, ...(stored.policy ?? {}) },
+          members,
+          messages: Array.isArray(stored.messages) ? stored.messages : [],
+          tasks: new Map((Array.isArray(stored.tasks) ? stored.tasks : []).map((task) => [task.id, task])),
+          closed: false,
+        })
+      }
+    } catch {
+      /* a corrupt snapshot is ignored; the host session log stays authoritative */
+    }
+  }
+
+  persist() {
+    if (!this.stateFile) return
+    try {
+      const snapshot = {
+        version: STATE_VERSION,
+        savedAt: this.now(),
+        rooms: [...this.rooms.values()].map((room) => ({
+          roomId: room.roomId,
+          createdAt: room.createdAt,
+          hostSessionId: room.hostSessionId,
+          policy: room.policy,
+          members: [...room.members.values()].map(({ agent, ...rest }) => rest),
+          messages: room.messages,
+          tasks: [...room.tasks.values()],
+        })),
+      }
+      mkdirSync(dirname(this.stateFile), { recursive: true })
+      const temporary = `${this.stateFile}.tmp`
+      writeFileSync(temporary, JSON.stringify(snapshot, null, 2), 'utf8')
+      renameSync(temporary, this.stateFile)
+    } catch {
+      /* persistence is best effort; the session log remains authoritative */
+    }
+  }
+
+  /** Resolve a live agent for a persisted member on demand. */
+  async ensureAgent(member) {
+    if (member?.agent) return true
+    if (!member?.sessionId || !this.sessionController?.resolveAgent) return false
+    try {
+      const resolved = await this.sessionController.resolveAgent(member.sessionId)
+      if (!resolved?.agent) return false
+      member.agent = resolved.agent
+      return true
+    } catch {
+      return false
+    }
   }
 
   async upgradeHost({ agent, policy = {} } = {}) {
@@ -169,7 +244,9 @@ export class RoomService {
 
   /** Wake one local participant by injecting the addressed message. */
   async wake(room, member, message) {
-    if (!member?.agent || typeof member.agent.followup !== 'function' || typeof this.createUserMessage !== 'function') return false
+    if (!member || typeof this.createUserMessage !== 'function') return false
+    if (!(await this.ensureAgent(member))) return false
+    if (typeof member.agent?.followup !== 'function') return false
     const senderLabel = message.from.kind === 'user' ? 'user' : (message.from.name ?? 'agent')
     const text = [
       `[Fleet Room ${room.roomId}] ${senderLabel} → you:`,
@@ -189,7 +266,14 @@ export class RoomService {
   async append(room, type, data) {
     const host = room.members.get(hostMemberId(room.hostSessionId))
     const session = host?.agent?.session
-    if (session?.append) await session.append(type, data)
+    if (session?.append) {
+      try {
+        await session.append(type, data)
+      } catch {
+        /* the snapshot below still records the room state */
+      }
+    }
+    this.persist()
   }
 
   // --------------------------------------------------------------- room tasks
@@ -303,6 +387,21 @@ export class RoomService {
     return this.summary(this.requireRoom(roomId))
   }
 
+  /** All active rooms (UI list). */
+  list() {
+    return [...this.rooms.values()].map((room) => this.summary(room))
+  }
+
+  /** One room plus its transcript and board (UI detail). */
+  detail(roomId, { limit = 100 } = {}) {
+    const room = this.requireRoom(roomId)
+    return {
+      ...this.summary(room),
+      messages: this.messages({ roomId, limit }),
+      tasks: this.listTasks(roomId),
+    }
+  }
+
   /** All open rooms (for cleanup and diagnostics). */
   openRooms() {
     return [...this.rooms.keys()]
@@ -313,6 +412,7 @@ export class RoomService {
     room.closed = true
     await this.append(room, 'room/closed', { roomId: room.roomId, reason, closedAt: this.now() })
     this.rooms.delete(room.roomId)
+    this.persist()
     return { roomId: room.roomId, closed: true, reason }
   }
 

package/src/host/ui-web.js

@@ -0,0 +1,78 @@
+// Read-model HTTP surface for the Fleet console (dev.13): device overview,
+// room list and room detail. The approval routes stay in approval-web.js.
+function json(res, status, value) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(value))
+}
+
+function pathOf(request) {
+  try {
+    return new URL(request.url ?? '/', 'http://local').pathname
+  } catch {
+    return '/'
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {object} options.webServer ctx.webServer
+ * @param {object} options.inbox ApprovalInbox
+ * @param {object} options.rooms RoomService
+ * @param {() => object} options.getOverview
+ * @returns {() => void} disposer
+ */
+export function registerUiRoutes({ webServer, inbox, rooms, getOverview, logger = null }) {
+  if (!webServer?.register || !rooms) return () => {}
+  const disposers = []
+  disposers.push(
+    webServer.register({
+      kind: 'exact',
+      path: '/device-fleet/overview',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return json(res, 405, { error: 'method not allowed' })
+        try {
+          json(res, 200, { ...getOverview(), approvals: inbox?.list?.() ?? [] })
+        } catch (error) {
+          logger?.warn?.(`[device-fleet] overview failed: ${String(error?.message ?? error)}`)
+          json(res, 500, { error: 'internal error' })
+        }
+      },
+    }),
+  )
+  disposers.push(
+    webServer.register({
+      kind: 'exact',
+      path: '/device-fleet/rooms',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return json(res, 405, { error: 'method not allowed' })
+        try {
+          json(res, 200, { rooms: rooms.list() })
+        } catch (error) {
+          json(res, 500, { error: String(error?.message ?? error) })
+        }
+      },
+    }),
+  )
+  disposers.push(
+    webServer.register({
+      kind: 'prefix',
+      path: '/device-fleet/rooms/',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return json(res, 405, { error: 'method not allowed' })
+        const path = pathOf(req)
+        const roomId = decodeURIComponent(path.slice('/device-fleet/rooms/'.length))
+        if (roomId === '') return json(res, 400, { error: 'room id is required' })
+        try {
+          json(res, 200, { room: rooms.detail(roomId, { limit: 100 }) })
+        } catch (error) {
+          json(res, error?.code === 'unknown-room' ? 404 : 500, { error: String(error?.message ?? error), code: error?.code ?? 'error' })
+        }
+      },
+    }),
+  )
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}

package/src/plugin/index.js

@@ -6,6 +6,7 @@
 // Room, Room Board, delegation and the UI land in later steps.
 import { readFileSync } from 'node:fs'
 import { networkInterfaces } from 'node:os'
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
@@ -17,6 +18,7 @@ import { DelegationHost } from '../host/delegation.js'
 import { ApprovalInbox } from '../host/approval-inbox.js'
 import { RoomService } from '../host/room-service.js'
 import { registerApprovalRoutes } from '../host/approval-web.js'
+import { registerUiRoutes } from '../host/ui-web.js'
 import { ExecutionSlot, DEFAULT_SHELL_TOOL } from '../host/execution-slot.js'
 import { ToolPolicy } from '../host/tool-policy.js'
 import { createFleetHandlers, createFleetToolDefinitions } from '../host/tools.js'
@@ -197,13 +199,30 @@ export function apply(ctx, config) {
     ? async () => ({ approved: true, scope: 'once' })
     : async (request) => inbox.request(request)
 
-  const rooms = new RoomService({ sessionController, createUserMessage })
+  const rooms = new RoomService({
+    sessionController,
+    createUserMessage,
+    stateFile: join(state.dataDir, 'rooms.json'),
+  })
 
   // Client approval panel data plane (dev.9). Optional service: host-only
   // deployments simply do not expose the panel routes.
   const webServer = service('webServer')
   if (webServer) {
     ctx.effect(() => registerApprovalRoutes({ webServer, inbox, logger }))
+    ctx.effect(() =>
+      registerUiRoutes({
+        webServer,
+        inbox,
+        rooms,
+        logger,
+        getOverview: () => ({
+          ...(node.status?.() ?? {}),
+          rooms: rooms.list(),
+          approvals: inbox.list(),
+        }),
+      }),
+    )
   }
   if (!sessionController) logger.warn?.('[device-fleet] sessionController unavailable: direct calls to stateful tools will fail')
   const slot = sessionController
@@ -369,9 +388,8 @@ export function apply(ctx, config) {
 
   ctx.effect(() => () => {
     inbox.close()
-    for (const roomId of rooms.openRooms()) {
-      void rooms.close({ roomId, reason: 'plugin unloaded' }).catch(() => {})
-    }
+    // Rooms are intentionally left open (and persisted) so a plugin reload can
+    // rehydrate them instead of destroying a running collaboration.
     void node.close()
   })