dsh-appearance

DSH 外观协调器：在 DSH 设置中新增「外观」页，统一管理外观类插件。

功能

• 设置侧边栏新增「外观」，位于 通用 与 模型 之间。
• 外观插件通过 appearance.manager 服务注册；「外观」页为每个已注册模块渲染一张卡片： 启用/停止开关、状态徽标、参数开关（由模块声明的 settingsSchema 驱动，说明文字为 悬浮提示）。
• 每个模块三项通用检查（对任意数量的外观插件生效，输入是各模块内嵌的鲸选清单 v1.1 字段）：
  • 冲突：loader id / 挂载点 / 设置命名空间跨模块重复、deps 依赖未注册；
  • 危险：声明的能力（network/telemetry/permissions）+ 鲸选体检管道的代码扫描 裁决（security.verdict）；
  • 性能：perf 声明的轮询周期、内存估算、GPU/显存、常驻定时器数。
• 浏览器端不重复扫描代码：裁决由鲸选 check-plugin 管道（Node 侧）给出，本页只呈现。
• 未安装任何外观插件时，页面显示空状态。

安装

npm 方式：

dsh plugin add dsh-appearance

手动方式：把 dsh-appearance 加入 web profile 的 dsh.profile.bundles，安装依赖后重启 dsh web。

注意：不要在 ~/.dsh/profiles/web/cordis.patch.yml 里重复插入 id 为 appearance 的行 （loader 会拒绝启动，duplicate loader entry id）。

使用

打开 设置 → 外观。

• 开关与参数由各外观插件自行声明。
• 检查结果供参考，不影响插件运行。

为外观插件作者

在你的客户端插件 apply 中：

const manager = ctx.get('appearance.manager')
if (manager !== undefined) {
  ctx.effect(() => manager.register({
    id: 'your-module',
    name: '模块名',
    // 内嵌鲸选清单（whalepicks.json v1.1 字段）——全部体检的输入
    whalepicks: {
      patches: { insertIds: ['your-module'], namespaces: [], slots: ['slot.name'] },
      capabilities: { network: false, telemetry: false, permissions: [] },
      deps: [],
      perf: { polls: {}, memoryEstimateMB: 2, gpu: false, timers: 0 },
      security: { verdict: 'passed', scanBy: 'whalepicks check-plugin' },
    },
    // 参数开关（desc 只作悬浮提示，不占版面）
    settingsSchema: [{ key: 'foo', kind: 'switch', title: '开关', desc: '悬浮说明' }],
    getState: () => state,
    setState: (patch) => { /* merge + persist + notify */ },
    // 可选：实时界面占用——返回当前挂载的根元素，管理页每 2s 统计其 DOM 子树
    // 节点数（性能行的「界面节点 N 个（实时）」）；不提供则不显示该行
    roots: () => [rootEl],
  }))
}

文案双语：name/title/desc/placeholder 支持 { key } 走模块自己的 locale 词典 （纯字符串仍直显，仅作兼容）。状态建议持久化到 localStorage（见 dsh-statusbar）， rc.6 的 web 设置网关只对白名单命名空间开放。

卸载

从 profile 移除包并重启，即完全卸载。「外观」页随之消失。

鲸选范式

本仓库是鲸选范式（spec/PARADIGM.md）的「服务提供者」范例：settings.section 槽位 + appearance.manager 服务 + 模块自述描述符契约；宿主半区为空实现（browser-only）。

• 鲸选范式：https://github.com/LeeKai233/dsh-whale-picks/blob/main/spec/PARADIGM.md
• 迁移指南：https://github.com/LeeKai233/dsh-whale-picks/blob/main/docs/migrate-to-paradigm.md

仓库结构

• src/client：浏览器端源码。
• src/index.ts：Node 端入口（空实现——browser-only）。
• lib/client.js：构建产物。
• whalepicks.json：鲸选清单。
• tests：单元测试。

开发

pnpm install
pnpm bundle
pnpm test