dsh-panel — 面板宿主（Panel Host）

一句话：把「每个插件各写一套前端」收敛成「每个插件提交一份声明」的前端宿主——一个 URL（http://127.0.0.1:3080/panel/）、一套外壳、一张注册表；贡献方只提供视图规格（ViewSpec）+ 动作表（Action ABI），宿主负责渲染、派发、审计、实测健康与降级。

为什么值得用：自研前端散落各处时，没有人能回答「谁在什么时候对哪个页面做了什么」——安全机制不可观测就等于不存在。本插件把「渲染 / 派发 / 审计 / 实测健康」四件事收进一个宿主：贡献方声明即 effect（插件卸载面板立刻消失，无幽灵），未知动作零副作用，破坏性动作要二次确认，触及「须请示三类」的动作宿主直接拒绝并转请示通道。而且它零官方 client 依赖——官方前端坏了，面板照常可用。

能力

宿主职责：托管外壳与静态资源 · 维护注册表（含实测健康）· 把贡献方的 view() 渲染成视图规格 · 按动作 ABI 派发并每次落一条审计 · 施加超时与降级。

接入契约（消费方视角；完整签名见 docs/semantic.md §4）：

// 必须用 ctx.inject 等待宿主（不得用 ctx.get('panel') 一次性探测——加载顺序会让它拿到 undefined 且永不重试）
ctx.inject(['panel'], (panelCtx) => {
  panelCtx.panel.register({
    id: 'my-panel',                 // 全局唯一 [a-z0-9-]+，重复注册 fail-loud
    title: '我的面板',
    order: 100,                     // 导航排序（小→前）
    icon: 'plug',                   // 宿主图标白名单键（非自由 SVG）
    description: '一句话用途',       // 自检面板展示
    view: async (params) => ViewSpec,
    actions: { /* 动作表 */ },
    style: { accent: '#f472b6' },   // 可选：自带视觉（宿主只认 token，不认自由 CSS）
  })                                // 返回 disposer；注册即 effect
})

HTTP 面（全部 JSON 响应统一信封 {ok, ...}）：

内置面板（宿主自带，随宿主注册）：

降级语义：贡献方 view() 抛错 → 该面板显示错误原文，外壳与其余面板不受影响；view() 超过 viewTimeoutMs → 标记超时；未知 panelId/actionId → 400/404 且零副作用（但仍写一条审计）。

快速开始

1) 装依赖：

"dsh-panel": "link:<工作区>/self-plugins/dsh-panel"

2) 挂组合（零配置可用；下列项按需覆盖）：

- id: panel
  name: dsh-panel
  config:
    defaultProfile: web

3) 30 秒验证：

curl -s http://127.0.0.1:3080/api/panel/registry | head -c 300
# 期望：{"ok":true,"host":{"version":"0.4.0","startedAt":"…"},"panels":[…5 个面板…]}
curl -s http://127.0.0.1:3080/api/panel/selfcheck
# 期望：ok:true + 各贡献健康度实测 + 宿主版本

浏览器打开 http://127.0.0.1:3080/panel/ → 期望左侧导航 5 项、点任意一项能出内容（而非空壳或 404）。

配置

落盘与自证（出问题时先看这里）

审计轨：每次派发写一行到 <DSH_HOME>/panel/audit.jsonl（写盘吞错不反噬派发）：

{"at":"2026-09-13T09:41:30.712Z","panelId":"taskboard","actionId":"claim","level":"write",
 "paramsDigest":"83b51b5ad28488cd","outcome":"ok","durationMs":1,"message":"已认领 t-2a6731ae（claimed，负责人 alice）"}

本机实测（2026-09-14）：audit.jsonl 4 行，末行即上例。

一条命令答五问（本插件是生态里的正面样板——五问全可答）：

tail -3 "$DSH_HOME/panel/audit.jsonl"; curl -s http://127.0.0.1:3080/api/panel/registry
# ① 线上跑的是哪个构建 → registry 的 host.version + host.startedAt（实测 0.4.0 / 2026-09-14T07:06:07Z）
# ② 谁发起 / 投给谁   → audit 的 panelId + actionId + at
# ③ 断在哪一段        → audit 的 outcome（ok/denied/error）+ message；view 断点看 view 响应的 degraded
# ④ 结果质量          → /api/panel/selfcheck 的实测健康 + 该面板是否 degraded
# ⑤ 耗时与预算        → audit 的 durationMs（动作）与 view 响应的 durationMs（视图，对照 viewTimeoutMs=2000）

生效判据与回退

生效判据（三选一，按可靠性排序）：

1. 行为级：GET /api/panel/registry 返回 ok:true 且 panels 为你预期的数量（本机 5 个）+ host.version 与 package.json 一致；
2. 页面级：浏览器打开 /panel/ 能切到任意面板并看到内容（截图复核，别只看接口——单测全绿时缺陷仍可能只在视觉层暴露）；
3. 生态级：plugin_boot_status（dsh-plugin-bootreport）的 liveNow 含本插件。

注意：重新构建 ≠ 生效——产物 mtime 新只证明「构建过」，进程启动时间晚于产物 mtime 才算「在跑它」。本插件构建含两步（tsc + copy-assets.mjs，客户端另有 bundle-client.mjs），只跑 tsc 会得到一个没有外壳资源的宿主。

回退（三档）：

• 组合级：preset 给 panel 行加 disabled: true → 面板整体下线，官方 Web GUI 完全不受影响（本插件从不修改官方界面）；
• 源码级：git -C self-plugins/dsh-panel revert <commit> → 重新构建（含 assets/client）→ 预检 → 哨兵重启；
• 数据级：audit.jsonl 可随时删除（纯审计，无业务状态）；贡献方数据不归宿主，宿主从不持久化它们。

测试

npm test        # = node --test "tests/*.test.mjs"

51 例离线测试（8 个文件）：

无网络依赖：视图/动作/审计全在离线夹具上断言（临时目录 + 桩贡献方）。

设计要点

• 注册即 effect，卸载即消失：面板身份是合成级契约——宿主不持久化贡献方数据，插件禁用后面板立刻从注册表消失，绝不出现「幽灵面板」。
• 重复 id 必须 fail-loud：第二个同 id 注册抛错而不是覆盖——撞车 = 配置错误，静默覆盖会让「谁在渲染」变成不可知的谜。
• 必须用 ctx.inject(['panel'], …) 等待宿主，不得 ctx.get('panel')：加载顺序会让一次性探测拿到 undefined 且永不重试，表现为「插件健康但面板 404」——这是实践踩出来的接入纪律。
• 只读可宽容，写入必须苛刻：板面解析失败时拒绝写入（写前写后字节相同），否则空板会覆盖真实数据；读取时坏行跳过并计数即可。
• 审批门优先于确认门：触及「须请示三类」（删数据/动凭据/动核心引擎）的动作，即使调用方带了 confirm:true 也拒绝派发（requires-approval）——宿主不得成为绕过主体性铁律的通道。
• 审计是安全机制的可观测面：被拦下的动作也写行（denied），并且参数只落摘要（paramsDigest）不落原文——记录了「做过什么」又不制造新的泄露面。
• 零官方 client 依赖：外壳是自包含资源（本机实测 lib/assets/shell.html 79,729 字节，/panel/ 一次返回 72,949 字符、cache-control: no-store），构建期才需要 Node 脚本——官方前端坏了面板照常可用，代价是自带一套资源与构建步骤。

相关文档

License

MIT © jonah791

本插件属于我的数字生命爱丽丝（alice-digital-life）的 DSH 自研插件生态。