donwww/dsh-client-ui-skin-manager

@dsh-external/dsh-client-ui-skin-manager

一个用于 DSH Web GUI 的皮肤管理器：它向 DSH 设置对话框添加一个皮肤 / Skins 页面，列出当前配置文件中已安装的皮肤，让你选择要激活的皮肤，并一键在原版 UI 和皮肤之间切换整个界面。它不渲染任何浮动覆盖层，因此绝不会遮挡 shell 自身的控件，并且即使另一个 agent 按文档方式安装皮肤，它也能正常工作。

安装管理器

1. 将此包复制到配置文件的插件目录中：

/profiles/web/node_modules/@dsh-external/dsh-client-ui-skin-manager/

（当启动器能够访问 pnpm 时，dsh plugin --profile web add  也可以使用；直接复制则不需要包管理器。）
2. 接入它——要么运行捆绑的安装程序，要么自己添加该行：

node "/dsh-client-ui-skin-manager/install.mjs"

$DSH_HOME/cordis.patch.yml
- insert:
- id: ui-skin-manager
name: '@dsh-external/dsh-client-ui-skin-manager'

3. 重启 DSH（或者如果它已经在运行，只需刷新页面），然后打开
设置 → 皮肤。如果没有安装任何皮肤，页面会说明这一点并提供原版 UI。

已针对 DSH 0.1.5-rc.1 以及 0.1.5-rc.2 Web 客户端包
（dsh-client-ui-renderer、dsh-client-locale、dsh-client-ui-settings）进行测试。
另请参阅 AGENT-INSTALL.md：一份可交给被要求安装皮肤的 AI
助手的简明指南。

它的功能

- 发现——扫描配置文件的 node_modules，查找暴露 skin.json 的包
（@scope/name/skin.json 或 name/skin.json），容忍 UTF-8
BOM，并忽略其他所有内容，包括它自身。
- 选择——将选择持久化到
$DSH_HOME/profiles//data/dsh-client-ui-skin-manager/settings.json。
- 实时切换——立即将选择应用到正在运行的加载器
（对皮肤包的每个条目执行 entry.update({ disabled })）。禁用一个
条目会移除皮肤的两部分：其客户端模块会离开所服务的页面，其宿主路由会被释放。无需重启 DSH。
- 无重复挂载——组合树尚未挂载的皮肤会被报告为
未接入（同时选择会被持久化），而不是在旁路创建：受管理的块已经携带其插入项，因此如果在这里创建第二个条目，一旦该插入项生效，就会导致该包被挂载两次。
- 两层接线——管理器自身的行和一个标记块位于
HOME 层（$DSH_HOME/cordis.patch.yml）；配置文件层
（profiles//cordis.patch.yml）留给用户和其他
安装程序。HOME 层在配置文件层之后应用，因此：
- 另一个 agent 在配置文件层接入的皮肤会被采纳——管理器只覆盖其启用状态，因此组合树对每个皮肤恰好保留一个条目，并且启用/禁用决定仍然有效；
- 一个重写 profile 层的 agent 无法删除管理器本身。
- 设置页面 —— 通过 shell 的插槽系统贡献一个 settings.section 页面（“皮肤” / “Skins”），并通过 ctx.locale 进行本地化。
- 原版 UI —— “原版 UI”会禁用每一行皮肤，留下未改动的界面（皮肤设置仍保留在磁盘上，重新启用后便会恢复）。

使用它

打开 设置 → 皮肤（Settings → Skins）。该页面是一个单选列表——没有模式按钮，没有需要记住的操作：

| 行 | 点击后的效果 |
|---|---|
| 原版 UI（第一行） | 禁用所有皮肤 → 原版界面 |
| 一个皮肤行 | 使该皮肤成为活动皮肤；其他所有皮肤均被禁用 |

因此，任意数量的已安装皮肤都只需一次点击即可切换，当前选择始终以填充的单选按钮显示（外加一个 使用中 徽章，标记在加载器报告为生效的那一行上）。

每个皮肤行显示其预览图、名称、作者和标语，以及一个徽章：使用中（已生效）、待生效（已写入，加载器仍在切换）或 未接入（尚无加载器行）。页面会等待宿主报告新的生效状态，然后重新加载页面一次——皮肤的客户端部分只能通过一次全新的页面加载来加载或卸载；切换通常在一秒内完成。

安装另一个皮肤（包括由另一个 agent 安装）

以下任一方式均可，且都不需要重新配置管理器：

1. 仅包 —— 将包放入 profiles//node_modules/@scope/name/（或 dsh plugin --profile web add ），或者直接运行 tools/install-skin.mjs 。管理器会在下一次请求时发现它，将其插入自己的块中，它便会出现在选择器中；在加载器挂载该插入之前，该行显示为 未接入，重启一次 DSH 即可使其生效。
2. 包加补丁行 —— 大多数皮肤 README 记录的步骤（在 PROFILE 层中 - insert: - id: ui-skin-x / name: '@dsh-external/...'）。管理器会检测到该行，采用它（无论它使用什么 id），并且只写入启用/禁用覆盖。它绝不会插入第二份副本。
3. 作为 bundle（dsh.profile.bundles）—— 皮肤自身的 cordis.patch.yml 插入会从 bundle 层应用；管理器以相同方式采用它。

为较旧 dsh 构建编写的皮肤，其宿主部分通过 return ctx.webServer.register(...) 注册路由，无法被干净地重新启用（先前的路由永远不会被释放）：对每个皮肤运行一次 tools/patch-skin-dispose.mjs 。

布局

| 路径 | 作用 |
|---|---|
| lib/index.js | 宿主部分：发现、持久化、/api/dsh-skin-manager/state、/api/dsh-skin-manager/preview、运行时切换、层迁移、托管块写入器、bundle 重新哈希 |
| lib/client.js | 浏览器部分：设置 → 皮肤页面（React，不导入组件库） |
| install.mjs | 将包复制进来并拥有 HOME 层；--dry-run 打印两个层，--files-only 跳过补丁层（在旧构建仍在运行时使用） |
| tools/install-skin.mjs | 一键皮肤安装器（GitHub URL、owner/repo 或本地目录） |
| tools/patch-skin-dispose.mjs | 用于旧皮肤宿主半部分的兼容垫片 |
| tools/refresh-served-bundle.mjs | 在运行中的 harness 上重新哈希浏览器包（无需重启） |
| AGENT-INSTALL.md | 交给另一个 AI 助手的最小安装指南 |
| test/compose.test.mjs | 通过真实 harness composer 进行的发现 + 接线计划 + 托管块测试，包括外部接线场景 |
| test/routes.test.mjs | 使用伪造的 req/res 和伪造加载器进行的 HTTP 表面测试 |
| test/client.test.mjs | 浏览器半部分测试：设置注册、渲染列表、点击路径 |
| test/e2e-live.mjs | 端到端驱动一个运行中的实例（需要其端口 + 启动令牌） |

使用 node test/.test.mjs 运行测试。

更新插件本身

harness 会缓存每个包的浏览器包，并将导入的宿主模块保留在 Node 的 ESM 缓存中。宿主半部分在每次挂载时都会重新哈希自己的包，因此随重启（或任何重新挂载）而来的更新会被自动拾取；要在不重启的情况下刷新正在运行的 harness，请运行 tools/refresh-served-bundle.mjs（它会通过受监视的补丁层短暂禁用并重新启用管理器的加载器条目，并通过宿主挂载标记验证重新挂载）。已更改的宿主半部分仍然需要重启，因为正在运行的进程会保留它已经导入的模块。

注意事项与限制

- 两条路由都仅限回环；浏览器通过现有的已认证页面会话访问它们。
- 管理器拥有其两个标记之间的块以及它自己的插入行。标记只会写入 HOME 层；旧构建遗留在 profile 层中的块会在下次挂载时迁移。
- 手动添加在标记块内部的皮肤行会被覆盖——请通过安装包（或在块旁边添加一行）来添加皮肤，然后使用设置页面。
- 发现过程只遍历一层 node_modules（加上 @scope/）；嵌套的或 .dsh-module-fallback 副本不会被扫描。
- 未安装皮肤时，页面会说明这一点并报告模式为 vanilla。
- 页面每次切换都会重新加载一次：皮肤的客户端半部分随页面的启动负载一起传递，因此无法在已加载的标签页中添加或移除它。

故障排除

dsh 拒绝启动：overlay …/cordis.patch.yml must be a top-level YAML array of loader patch entries

该补丁层只包含注释，YAML 会将其解析为 null 而不是空数组。0.4.1 之前的版本在将管理器自身的接线迁移到 home 层时，可能会让 profile 层处于这种状态，随后下一次启动会在任何插件加载之前失败。
无需启动 dsh 即可修复它（这正是该工具的要点——卡住的安装无法启动 harness）：

node "/dsh-client-ui-skin-manager/tools/repair-patch-layer.mjs" --all

--dry-run 会先报告它将更改的内容。从 0.4.1 起，此包中的每个写入器都会让其输出经过同一保证，因此不再可能生成仅含注释的层（该回归由 test/compose.test.mjs 覆盖，它使用 harness 自带的补丁加载器检查写入的文件）。

某个皮肤行显示 未接入，切换没有任何效果

组合树尚未挂载该皮肤的条目。该选择已持久化在受管块中；重启一次 dsh，该行即可使用。（管理器有意不自行创建该条目——参见“No double mounts”。）