dsh-ui-tuner

Web UI tuner 插件：在 设置 → 界面调整 面板与 侧边栏「界面调整」胶囊 + 编辑模式 中，调整 dsh web 界面上各类元素的位置与外观。配置保存在本机 host 设置文档（.dsh 用户设置，跨浏览器、跨会话生效）。

• 类型：web 客户端插件（host 半部注册 ui-tuner settings 命名空间 + GET/PUT /plugins/dsh-ui-tuner/config.json 持久化路由）
• 版本：0.1.0（v0.1 范围见下）
• 依赖说明：见 PLAN.zh.md（规划文档）与 lib/manifests/README.md（选择器清单）。

功能

设置面板（设置 → 界面调整，settings.section）

| 分组 | 内容 | 实现层 | | --- | --- | --- | | 布局 | 侧栏/详情栏宽度滑条（0=默认）、窄屏自动折叠 | L3（CSS 覆盖，启用时隐藏原生拖拽手柄） | | 颜色 · 浅色 / 深色 | 13 个设计令牌色板（品牌/侧栏/背景/文字/状态），深色分支独立；取色用插件自绘色板弹层（渐变色板+色相滑条+快捷色+HEX，钳制在设置对话框内） | L2（body 内联令牌覆盖，跟随 data-ds-dark-theme 重放） | | 字体 | 界面字体、等宽字体（系统/预设/自定义） | L2 | | 几何（实验性） | 圆角半径 0–24、密度 0.8–1.2（间距缩放） | L3（manifest 门控） | | 元素显隐（实验性） | header/logoRow/newSession/workspacesRegion/composerStack + 底部条目 | L3 | | 预设 | 紧凑 / 宽屏 / 暖色深色 / 高对比（叠加 diff，可清除） | 组合 | | 动作 | 恢复默认、导出 JSON、导入 JSON | — |

即改即生效（自动保存，无需「保存」按钮）。持久化：host 路由（~/.dsh/plugins/dsh-ui-tuner/config.json，跨浏览器，dsh-todo-list 同款模式）为主，localStorage 为离线缓存；原因：dsh-host-apiproxy 对 web 客户端设置了命名空间白名单（WEB_SETTINGS_NAMESPACES），插件自有命名空间即使注册也会被 settings-not-exposed 拒绝。面板顶部显示同步状态。实验性功能（几何/显隐/栏宽/排序）由「选择器探针」激活——探针命中内置清单的稳定 shell 类名即启用（boot rev 是插件图 hash，会随插件增减变化，不作为匹配键）；未命中时黄条降级禁用，颜色/字体仍可用。

编辑模式（侧边栏胶囊「界面调整」）

• 进入后页面出现悬浮引导条与蓝色虚线区：
  • 区内排序：拖拽 footer/header 动作区条目徽标换位（预览态，点「应用」落库）
  • 显隐：点 🁢 隐藏条目（低优先级 shadowing 隐藏，可恢复）
  • 栏宽：拖三栏边缘，实时角标；「撤销」放弃预览，「应用」写入配置
  • 退出 = 应用并退出：未「应用」的预览调整（显隐/排序/栏宽）在退出时自动落库，然后自动刷新页面——调整不会丢
• 点「应用」/「退出」/再次点胶囊收起框架后自动刷新页面：先等待 host 写队列（含边距/尺寸等实时提交的 PUT）全部落盘后再 reload——否则刷新会中止在途写入，导致最后一次调整（如边距 +12）在重启后还原（已复现并修复的竞态）；刷新保证其它插件不被浮层残留干扰、功能干净重载。
• 右下角**「恢复默认 UI」药丸**：只要有任何可重置内容（配置覆盖，或编辑模式中尚未应用的预览调整）就常驻显示——编辑模式中、退出后都能看到；点击立即全部恢复默认（含放弃未应用的预览）。
• 编辑模式浮层的重锚定是节流轮询（约 5 次/秒）+ resize 监听，不做每帧强制布局/重渲染——避免抢占主线程导致其它固定 UI（如待办面板）滚动抖动/输入失灵。

诚实边界：跨区搬移（把底部胶囊拖到头部）不支持——条目仍渲染在原生插槽内；宽度覆盖启用后原生拖拽手柄隐藏；圆角/密度只作用于清单列出的目标。

安装 / 升级 / 回滚

安装（首次）

1. 把本目录接入 web profile（仓库惯例）。**重要：node_modules/dsh-ui-tuner 必须始终是指向本目录的符号链接。若某次 pnpm install 把它替换成了实体目录副本，运行中加载的 bundle 将冻结在副本内容（改源码不生效）——检测：ls -l ~/.dsh/profiles/web/node_modules/dsh-ui-tuner 应为 -> /home/hp400g5/plugin_dev/dsh-ui-tuner；若不是，rm -rf ~/.dsh/profiles/web/node_modules/dsh-ui-tuner && ln -s /home/hp400g5/plugin_dev/dsh-ui-tuner ~/.dsh/profiles/web/node_modules/dsh-ui-tuner，然后硬刷新页面。接线：
   • ~/.dsh/profiles/web/package.json 的 dependencies 加 "dsh-ui-tuner": "link:/home/hp400g5/plugin_dev/dsh-ui-tuner"；
   • ~/.dsh/profiles/web/node_modules/dsh-ui-tuner 符号链接到本目录；
   • ~/.dsh/profiles/web/cordis.patch.yml 追加 - insert:\n - id: ui-tuner\n name: 'dsh-ui-tuner'。
2. 重启 dsh web（loader 不热加载 host 清单），刷新页面。
3. 验证：curl http://127.0.0.1:3080/ | grep ui-tuner；侧边栏出现胶囊；设置页出现「界面调整」。

仓库 dsh-config/profiles/web/ 已同步同款改动（版本化源头）；lib/manifests/targets.24290140a405.json 为选择器清单记录。

升级（代码更新）

实测刷新流程（dsh 0.1.0-rc.6 + dsh plugin CLI）：dsh plugin --profile web add file:… 只转发 pnpm，file: 依赖会在 ~/.dsh/profiles/web/node_modules/dsh-ui-tuner 物化为实体目录副本（冻结拷贝，非符号链接），CLI 也不改写 cordis.patch.yml 的 insert。因此改代码后必须：

cd ~/.dsh/profiles/web
dsh plugin --profile web remove dsh-ui-tuner
dsh plugin --profile web add file:/home/hp400g5/plugin_dev/dsh-ui-tuner

刷新页面即可（客户端 bundle 每次请求重新注入；host 侧 lib/index.js 变化需重启 dsh-web.service）。检测拷贝是否最新：md5sum ~/.dsh/profiles/web/node_modules/dsh-ui-tuner/lib/client.js /home/hp400g5/plugin_dev/dsh-ui-tuner/lib/client.js。

dsh 升级

见 lib/manifests/README.md —— 重新采集清单、更新 MANIFESTS 内嵌常量；未更新前实验性功能自动降级。

回滚

• 设置面板「恢复默认」（应用器清空 → 零注入）；编辑模式「撤销/重置」。
• 卸载：移除 patch insert + package.json 依赖 + 符号链接 → 重启 → 刷新；验证无 dsh-ui-tuner 的 <style> 残留。

验证

• node test/smoke-unit.mjs —— 无浏览器单元冒烟（bundle 结构、配置归一、manifest 解析、令牌应用、CSS 规则生成）。
• test/smoke-checklist.zh.md —— 手工冒烟清单（接线/加载、L2、L3、编辑模式全路径、降级、卸载零残留）。

已知限制（v0.1）

• 跨区搬移不支持；原生拖拽手柄在宽度覆盖时隐藏；圆角/密度仅覆盖清单列出的目标。
• toast/tooltip 微调、设置面板自身外观、host 侧 settings.yaml/CLI 配置维度 → v0.2。
• 配置不随个人账号同步，仅存本机（随实例快照备份可迁移）；host 命名空间不可用时暂存于当前浏览器 localStorage。
• 实验性功能依赖 shell 类名清单（探针激活）；dsh 升级后需按 lib/manifests/README.md 更新。

文件

lib/index.js            host 半部：ui-tuner settings 命名空间（Config 即配置契约）
lib/client.js           浏览器 bundle：面板/胶囊/编辑模式 + L2 令牌与应用器 + L3 清单应用器 + shadowing
lib/types/              类型声明
lib/manifests/          <rev>.collected.json（机器采集）/ targets.<rev>.json（人工清单记录）/ README
scripts/collect-manifest.mjs  清单采集脚本（dsh 升级后用）
test/smoke-unit.mjs     无头单元冒烟
test/smoke-checklist.zh.md   手工冒烟清单
PLAN.zh.md              规划文档（交互设计/实现路径/维护）