dsh-ui-harmonizer

dsh plugin --profile web add dsh-ui-harmonizer

---

description: "统一 Harness 界面语言，并为社区插件做针对性适配，附只读兼容性审计。"

---

<p align="right"><a href="README.md">English</a> · <b>简体中文</b></p>

<p align="center">

<img src="docs/icon/app-icon-dark.svg" alt="dsh-ui-harmonizer" width="104" height="104">

</p>

<h1 align="center">DSH UI Harmonizer</h1>

<p align="center">

<strong>DeepSeek Harness 打造的界面规范化与协调层</strong><br>

规范化官方界面 · 协调每个插件 · 设置页自动规范器 · 界面定制（宽度、字体、侧栏开合平顺）</p>

<p align="center">

<img src="https://img.shields.io/npm/v/dsh-ui-harmonizer?style=flat&label=latest%20release&color=4D6BFE" alt="Latest release">

<img src="https://img.shields.io/npm/dt/dsh-ui-harmonizer?style=flat&label=total%20downloads&color=4D6BFE" alt="Total downloads">

<a href="https://github.com/Physicolor/dsh-ui-harmonizer/stargazers"><img src="https://img.shields.io/github/stars/Physicolor/dsh-ui-harmonizer?style=flat&label=%E2%98%85&color=08C" alt="GitHub stars"></a>

<img src="https://img.shields.io/badge/license-MIT-2EA44F?style=flat" alt="MIT License">

<img src="https://img.shields.io/badge/DSH%200.1.x-4493F8?style=flat-square" alt="Supported: DeepSeek Harness 0.1.x">

</p>

---

<p align="center">

<sub>属于 <b>DSH Design System</b> —— 本仓库是运行时的那一半。<br>

它执行的规范在 <a href="https://physicolor.github.io/dsh-design-resources/">Physicolor/dsh-design-resources</a>。</sub>

</p>

**一句话 你装了一DSH 插件，界面却风格割裂？DSH UI Harmonizer 用CSS 覆盖 + 运行DOM 协调**」把它们拉回官方设计语言—*不破坏任何插件源码、卸载即还原、零模型开销**

DSH UI Harmonizer 是一纯浏览器端（client-onlyDSH bundle 插件。它不新增模型工具、不改写会话日志，只通过官方 settings.section / settings.general.item 槽位--dsw-* 语义令牌体系调整界面

---

当前功能

🎨 官方 UI 规范

能力 · 说明

顶部栏单行化 · 对话/轨迹选择器移入标题行，header 收成单行

按钮胶囊家族 · Session log、组件、toggle 按钮统一32px 胶囊

右侧栏贴边圆角矩 · better-sidebar 面板覆盖式布局，header 不动

设置页头统一 · 标题 18/600 + 描述 13px + hairline 收尾

原生 title 悬浮提示统一 · title 属性改用官方深色气泡渲染，替代系统默认提示样式

♻️ 插件视觉协调

协调对象 · 做法

dsh-better-sidebar · toggle 按钮胶囊化、面板背景统一、布局协调、平滑过渡动

dsh-widgets · 统计胶囊同族、header utilities 对齐

dsh-context · 其「上下文」视图会隐藏输入框座位，而组件栏正挂在这个座位里，整个组件区域随之消失；组件栏开启时把座位恢复为裁切 + 零高度，仪表盘保住整列、组件栏照常绘制。其「上下文洞察」仪表盘（shell.overlay）把框架层级交还回来：遮罩打开期间把该出口的 z-20 层叠上下文抬到 z-21 页眉之上（此前遮罩在页眉和挂在 body 上的组件放大层面前失效），彩色 ContextIcon 在两个 chrome 位置统一解析为 currentColor，仪表盘内的激活药丸不再使用深色主题的近白主色填充。仪表盘本身随后改穿设置窗口的外壳：--dsw-radius-panel 圆角、bg-layer-2 底色、--dsw-elevation-prominent 投影且不再描边，标题行采用对话框配方（顶部 22px / 两侧 24px 内边距、16px/24px 500 标题、28px 圆形关闭位），内容列自窗口顶端下移 54px、四周 24px 内边距，内部卡片统一到官方卡片 recipe（20px 圆角、12px 14px 内边距、10px 卡片列表间距）—— 见 docs/dialog-window-style.md

@omdsh-dev/dsh-genui · render_ui 面板与工具卡片：宽度跟随「对话列最大宽度」（--enhancer-content-width，如 840px）而非冒泡到整列；修复折叠flex-nowrap 长标题撑宽根因并统一 11px/16px 内边距；banner/steps 等横贯块16px 左右间距规范（不向外扩盒）；svg/pre/canvas/img/mermaid 全部限宽护栏

第三方设置页 · 自动补标题、删多余图标、统一间距格式

🧹 设置页自动规范器

任何第三方插件往 settings.section 加页面时，若没有严格按官方规范设计，插件会自动修正：

自动检查项 · 修正方式

缺页面标 · 注入 18/600 标题（取导航项名或已知映射）

标题旁多余图 · 移除标题logo，保留纯文字

标题/描述贴太 · 统一 4px 间距 + hairline 收尾

字号/格式不统一 · 标题 18/600、描13/20 + border-bottom

🎛界面定制

设置 → 通用设置中的"界面定制"块：对话宽度、markdown 字号、工作区字号、UI 字体、侧栏开合平顺均可实时调节。「侧栏开合平顺」（默认开）让右侧栏开合不再逐帧重排整个界面：轨道一步到位，位移改由正文列与输入框胶囊上的 cover 承担，两者都不触发强制布局；关闭后恢复官方原始缓动。

---

工作原理

插件按作用对象分层，而不是按文件类型堆放 —— 它同时协调两件事：(a) DSH 本体自身的界面规范，(b) 装在同一台机器上的各个社区插件。每个源文件只属于四层之一：

层 · 回答什么 · 例子

core/ · 与 DSH、与任何插件都无关的基础设施 · 状态模型与持久化、Harmony Contract、i18n、DOM/React 小工具

harness/ · 针对 DSH 本体的规范化与修补 · 官方控件 recipe 复刻、设置页表头规范器、对话宽度通道、列轨道动画兜底、菜单宽度、样式表守护、原生 title 气泡、圆角卡片

plugins/<包名>/ · 只服务于某一个社区插件 · commandcode-provider 文本归一、dsh-widgets 组件栏让位与手柄重锚、dsh-better-sidebar 面板、dsh-genui 宽度卫生

self/ · 插件自己画的界面 · 设置 → 通用 的五行、字体选择器、Harmony Doctor 页

样式表按同一划分拆成 29 个 .module.css 分片，入口只有一个（src/client/styles/index.ts），它的 import 顺序就是层叠顺序。

其余约束不变：

• 零模型开销：host（node）半是 no-op，全部改动发生在浏览器半；
• 官方设计令牌：所有样式走 --dsw-* 语义令牌，自动跟随明暗主题；
• 两条注入通道：静态规则（CSS Modules）+ 动态 <style data-plugin> 标签；
• 可逆清理：每个 ctx.effect 都返回 disposer，卸载后不留残留 —— 包括被搬迁过的 DOM 节点和被改写的第三方文案；
• Slot 接入：settings.general.item / settings.section / shell.overlay。

护栏都在 scripts/：tools/css-baseline.mjs（编译后样式表的字节不变式）、verify-frame-track.cjs（列轨道动画 + 侧栏平顺）、verify-rapid-toggle.cjs（联按回归：连续点击后不得残留内联样式、不得遗留 cover、轨道不得漂移）、verify/settings-page.cjs（设置页信号）、probes/harness/*（选择器与网络体检）。

---

安装

# 通过 npm（插件市场）
dsh plugin --profile web add dsh-ui-harmonizer

# 本地开发（link 方式dsh plugin --profile web add link:D:/dsh-home/plugins/dsh-ui-harmonizer

安装*硬刷新浏览器**（Ctrl+Shift+R），设置 通用设置 看到"界面定制"块

---

开

pnpm install
pnpm run build      # tsdown 构建 lib/
pnpm run check      # 类型检+ 构建

• peerDependencies：@deepseek-ai/dsh-client-ui-slots、dsh-client-runtime（由 DSH web profile 提供）；
• client 插件：cordis.patch.yml 插入 ui-enhancer 行，浏览器半dsh.client 声明
• 修改后需同步：npx tsdown 重建 同步profiles/web/node_modules/dsh-ui-harmonizer/lib/ 硬刷新浏览器

---

兼容

• DeepSeek Harness 0.1.0-rc.6 及兼容的后续 0.1.x
• 通过官方 slot 接入，与 better-sidebar、dsh-widgets、dshmarket 等插件按 slot 顺序共处
• 已知协调对象：dsh-better-sidebar、dsh-widgets、dsh-context、dsh-notification、dshmarket
• 卸载/禁用后页面完全恢复默认，无残留

---

路线

• 阶段一 · 官方 UI 规范化（进行中）：继续修复官方界面中未完善的部分；
• 阶段二 · 插件兼容协调（进行中）：检测并修复插件间的布局/样式冲突；
• 阶段三 · 统一视觉风格（进行中）：可选的视觉风格层——已落地 title 悬浮提示统一，待续：间距密度、更多圆角与动效统一；
• 液态玻璃探索：规范化的终点是降低认知成本——统一的标题与提示消除的是「风格切换」的微疲劳；材质层统一更进一步：用一致的物理隐喻暗示层级与可交互性，让整个页面形成单一心理模型，减少视觉与认知负担。边界：只在语义 token / CSS 层实验——设置开关可选、大面积 backdrop 表面至多两处（控制 GPU 开销）、尊重减弱透明动效偏好、不支持时回退到现行实底样式、绝不触碰插件源码，且以可读性不降为底线；
• 阶段四 · 生态共建：沉淀为可扩展的规则注册机制。

---

变更日志

v0.9.1 — 侧栏开合平顺、顶栏徽章让位、设置页表头收成一套骨架；删除圆角卡片

按车主决定以 patch 发布：这一版带新行为，严格按语义化应为 minor。它同时删掉了 0.9.0 里的一个可选视觉层，所以那一条写成"删除"，而不是让它悄悄消失。

新增 —— 右侧栏开合不再逐帧重排整个界面（「侧栏开合平顺」，默认开）

• 🔍 先量后改：产品在 _frame 上用缓动过渡 grid-template-columns，而它是布局属性——中栏轨道 300ms 内从 1427px 走到 659px，每一帧都重排整个框架（产品自己的 ResizeObserver 被唤醒 27 次，左侧栏开合只有 10 次），而合成器与 GPU 线程全程空闲。逐帧采集还抓到别的元凶：_scrollBody 的 `

…(truncated)