Dsh-Client-UI-Custom

![Awesome DSH Plugin](https://beancookie.github.io/awesome-dsh-plugin)

[中文](#中文) · [English](#english)

</div>

---

中文

简介

Dsh-client-ui-custom 是一个纯前端插件，它为用户提供了浮动历史记录条、用户消息md渲染、外观调试、插件市场、快捷键和用量统计功能。

修改了通用设置项 —— 在「设置 → 通用」里新增了历史记录条（位置、数量）和用户消息 Markdown 渲染开关；
修改了插件项 —— 在「设置 → 插件」里新增了「插件市场」；
新增了三个设置页 —— 「外观」「快捷键」「用量统计」。

所有功能默认关闭，不配置时保持与原生界面一致，全程零 shell 改动。

宣传视频

▶ 点击观看插件宣传视频（B 站）

功能选择（按需安装）

插件由六个相互独立的功能模块组成：appearance（外观）、shortcuts（快捷键）、 usage（用量统计）、history（历史记录条）、markdown（用户消息 Markdown 渲染）、marketplace（插件市场）。可在插件配置里用 features 白名单选择要安装的功能：

- id: ui-custom
  name: '@ha-na-bi/dsh-client-ui-custom'
  config:
    features: [shortcuts, usage]   # 只安装「快捷键」+「用量统计」

features 缺省或为空时，六个功能全部启用。

---

设置改动一览

位置	类型	内容
设置 → 外观	新增页面	主题定制，包括壁纸、玻璃、强调色、表面不透明度、字体与质感
设置 → 快捷键	新增页面	自定义快捷键，包括新建对话、切换模型、思考强度等
设置 → 应用用量	新增页面	用量统计，使用四窗口聚合、趋势图，展示会话用量排行
设置 → 通用	修改原有页	新增浮动历史条（可调节位置，数量）、用户消息 Markdown 渲染开关
设置 → 插件	修改原有页	新增「插件市场」，收录第三方插件目录

---

外观（设置 → 外观）

外观设置提供给用户极大的自定义空间，用户可根据自己需求选择背景、玻璃档位、强调色（可自动从背景取色）、各表面不透明度、色调渐变、暗色遮罩、字体与字号、主题色滚动条与内嵌晕影，并可把 ui-theme 的主题偏好（浅色 / 深色 / 跟随系统）合并进本栏。改动通过 ui-custom settings 命名空间保存并即时生效（主题实时重渲染，无需重启）。

预览—— 主题定制支持小窗预览。

也支持全屏预览，按 F2 即可退出。

预设（Preset） —— 插件内置了六种预设，每个预设都有独立的风格（预设可独立生效，你自己的 wallpaper 仍会叠加在它之下）：

id	名称	风格
`ink-teal`	Ink Teal 黛青	青玉色渐变，静谧沉稳
`ink-blue`	Ink Blue 黛蓝	黛蓝渐变，深邃克制的蓝
`dusty-rose`	Dusty Rose 藕荷	藕荷色渐变，温润柔和的粉
`apricot-gold`	Apricot Gold 杏金	杏金色渐变，温雅低调的金
`mist-gray`	Mist Gray 雾灰	雾灰色渐变，清冷安静的灰蓝
`ink-violet`	Ink Violet 墨紫	墨紫色渐变，沉静神秘

更多美术选择后续会扩展进这份列表 —— 见 src/client/presets.ts。

玻璃档位 —— glass 是透明度的开关；显式设置 wallpaperBlur 时总是优先于档位的默认半径：

档位	模糊	饱和度	气质
`off`	0px	1.0	不透明，无玻璃
`light`	6px	1.15	轻微玻璃
`frosted`	14px	1.25	强毛玻璃（默认）
`mica`	22px	1.1	柔和静态质感，保留壁纸色相

主题配置项 —— 所有字段均可选；显式配置永远优先于预设：

键	类型	默认值	含义
`preset`	string	`''`	预设 id（见上表）；`''` = 不使用预设
`wallpaper`	string	`''`	壁纸 URL/路径（Web 可访问）；空字符串 = 插件保持关闭
`wallpaperBlur`	number 0–60	玻璃档位默认	`#root` 模糊半径（px）；显式值优先于玻璃档位
`glass`	enum	`frosted`	`off` / `light` / `frosted` / `mica`（见玻璃档位表）
`accent`	string	`#4176e6`	强调色，整套 deepseek 色阶由它派生
`autoAccent`	boolean	`false`	从壁纸自动派生强调色（成功后覆盖 `accent`）
`surfaceOpacity`	number 0–100	`100`	主表面不透明度（聊天/细节列）
`sidebarOpacity`	number 0–100	`100`	侧栏不透明度
`chatSurfaceOpacity`	number 0–100	`100`	聊天列不透明度（经 `--dsw-chat-surface`）
`inputOpacity`	number 0–100	`100`	输入框不透明度
`codeBlockOpacity`	number 0–100	`100`	代码块/行内代码不透明度
`darkSurfaceOpacity`	number 0–100	`surfaceOpacity`	暗色模式表面不透明度（独立档位）
`gradient`	string	`''`	亮色模式下叠加在壁纸上的渐变；空 = 无
`darkScrim`	number 0–100	`0`	暗色模式下壁纸上的遮罩强度
`fontFamily`	string	`''`	字体栈覆盖；空 = 主题默认
`scrollbarAccent`	boolean	`false`	滚动条使用强调色
`vignette`	boolean	`false`	应用根节点的柔和内嵌晕影
`customCss`	string	`''`	原样追加的自定义 CSS（逃生舱）
`customVars`	object	`{}`	额外写到 `<html>` 上的 CSS 自定义属性（逃生舱）

完整示例：

config:
  preset: 'ink-teal'
  wallpaper: 'https://example.com/wall.jpg'
  glass: 'mica'              # 或 wallpaperBlur: 8 自定义半径
  autoAccent: true           # 强调色由壁纸自动派生
  chatSurfaceOpacity: 70
  customCss: |
    .some-hashed-class { border-radius: 16px; }
  customVars:
    '--my-accent-soft': 'rgb(255 127 178 / 0.3)'

---

快捷键（设置 → 快捷键）

新增的设置页，提供可自定义的键位绑定。值存在 ui-custom settings 命名空间里，运行时的修改无需重启即可生效（loader 配置作为组合层 base，「恢复默认」会回到 loader 默认值）。

动作	作用
`newConversation`	新建对话（与侧栏「新建会话」按钮一致）
`switchModel`	循环切换到会话目录中的下一个模型（循环；新模型使用自身默认思考强度）
`cycleThinking`	循环切换当前模型的思考强度（off → … → max，循环）
`sendMessage`	输入框发送手势（默认 `Enter`）
`newline`	输入框换行手势（默认 `Shift+Enter`）
`usagePanel`	呼出应用用量面板（默认未绑定，可在设置中开启，如 `Mod+Alt+U`）
`defaultWorkspace`	`newConversation` 打开的目标工作区（空 = 当前/最近）
`modelShortcuts`	一对一模型直达：每个组合键跳到指定模型（combo / provider / model）

实例：

config:
  shortcuts:
    newConversation: 'Mod+Alt+N'
    switchModel: 'Mod+Alt+M'
    cycleThinking: 'Mod+Alt+T'

习惯 Enter 换行？把发送改为 Mod+Enter、换行改为 Enter 即可（两个手势同时命中时发送优先）：

config:
  shortcuts:
    sendMessage: 'Mod+Enter'
    newline: 'Enter'

模型动作走与内置模型选择器相同的 session.models / session.selectModel RPC，输入区的模型显示会自动同步；被寻址的子代理会话会被跳过（与 UI 一致）。不带 Mod 的组合键在输入框聚焦时不会触发，避免劫持正常打字。

---

用量统计（设置 → 应用用量）

用量统计页会统计展示各会话的用量总和（token-meter + session-stats），用户可自选时间跨度（当前年内到最近三天）。页面展示 总 / 输入 / 输出 Token、缓存命中、使用时长、会话数与步数，并带用量趋势图与会话排行。会话列表行已携带 Host 计算好的投影基线，无需额外 RPC。

面板可通过快捷键在任何界面呼出。

---

通用设置项的改动

在「设置 → 通用设置」里新增内容：

浮动历史条（位置 / 数量） —— 记录某段会话的历史内容：

位置：left / right / off（默认 off，关闭时不显示）；
数量：显示最近多少回合（默认 10，0 = 全部）；
点击某段历史条目即可平滑滚动到对应消息，条目来自已挂载的会话快照，纯 DOM 跳转，无额外 RPC；
支持悬挂：在消息操作行（复制/分支之间）可选择将某段会话悬挂到历史条上，

置顶回合忽略数量限制、始终显示并带有强调色边框）。

用户消息 Markdown 渲染 —— 默认关闭；开启后你自己的消息按 Markdown 渲染（标题、列表、代码块、@子代理 / @技能 引用等），关闭时与原生纯文本外观一致。

---

插件项的改动

在「设置 → 插件」里新增第三个 tab 「插件市场」，通过调用Github API 发现带有dsh-plugin topic的项目，为用户提供第三方 DSH 插件目录。

---

安装

1. 确保构建会包含该包（pnpm run build:lib:client）。 2. 在 Web profile 的补丁层加入浏览器 roster 行 —— ~/.dsh/profiles/web/cordis.patch.yml（或你 profile 中对应的 dsh.client roster）：

- id: ui-custom
  name: '@ha-na-bi/dsh-client-ui-custom'
  config:
    preset: 'ink-teal'        # 选择预设；下面任意字段会覆盖它
    wallpaper: '/my-wall.jpg'
    wallpaperBlur: 14

3. 重启 dsh web。

自行构建时需注意：设置页要能加载，ui-custom 命名空间必须在 Web 客户端的设置暴露白名单里（packages/host/apiproxy/src/api-proxy.ts 的 WEB_SETTINGS_NAMESPACES）——本检出已加入。

---

工作原理

浏览器半区先解析 preset（presets.ts），按 DEFAULTS ← 预设 ← 配置

合并并对每个字段做钳制（config.ts），再把 --dsu-* 自定义属性写到 <html>（apply.ts）。runner 会把 roster 行的 config 作为 apply(ctx, config) 的第二个参数传入。

样式表（custom.module.css）消费这些变量，用比主题表更高优先级的选择器

在 body / body[data-ds-dark-theme] 上重新声明主题 token，插件总是赢得级联，且不修改任何插件或 shell 源码。

毛玻璃给 #root 加 backdrop-filter，半透明表面透过它显示壁纸。
聊天列旋钮依赖 ConversationRoot 读取

var(--dsw-chat-surface, var(--dsw-alias-bg-base)) —— 一行完全向后兼容的回退写法（没有该 token 的原生 Harness 行为与之前完全一致），见 packages/client/ui-conversation。

框架结构：

packages/client/ui-custom/
├── src/client/
│   ├── index.ts          # 插件入口：解析预设 → 规范化 → 应用
│   ├── config.ts         # CustomThemeConfig、DEFAULTS、normalizeConfig（类型收窄+钳制）
│   ├── presets.ts        # ThemePreset 注册表 —— 美术选择的扩展面
│   ├── apply.ts          # config → DOM：--dsu-* 变量、customCss、customVars
│   ├── custom.module.css # 消费 --dsu-* 变量的 token 覆盖
│   └── …                 # 其余功能子目录（appearance/ settings/ usage/ marketplace/ history/ pin/ markdown/）
├── tests/                # 配置管线单元测试
└── README.md             # 本文档（中文 / English 双语）

注意事项

profile 的 cordis.patch.yml 改动需要重启 dsh web 才生效。
壁纸必须能被浏览器访问（例如放在 Web 服务静态根目录下，或外部 URL）。
插件自带的设置页（外观、快捷键、用量统计等）修改实时生效、无需重启；

通过内置「插件配置」页直接编辑 loader 层配置暂不支持（待 ui-settings-plugins 的 schema）。

---

English

Overview

Dsh-client-ui-custom is a pure front-end plugin that provides a floating history strip, user-message Markdown rendering, appearance customization, a plugin marketplace, keyboard shortcuts, and usage statistics.

Adds to General settings — new rows under Settings → General for the

floating history strip (position / count) and the user-message Markdown rendering toggle;

Adds to Plugin settings — a new "Plugin Marketplace" under Settings → Plugins;
Adds three new settings pages — Appearance, Shortcuts, and Usage statistics.

All features are off by default; without configuration the UI stays identical to stock, with zero shell modifications.

Feature selection (install on demand)

The plugin is composed of six independent feature modules: appearance, shortcuts, usage (usage statistics), history (history strip), markdown (user-message Markdown rendering), and marketplace (plugin marketplace). Use the features whitelist in the plugin config to choose which to install:

- id: ui-custom
  name: '@ha-na-bi/dsh-client-ui-custom'
  config:
    features: [shortcuts, usage]   # install only shortcuts + usage stats

When features is absent or empty, all six features are enabled.

---

Settings at a glance

Where	Kind	What
Settings → Appearance	new page	custom theming: wallpaper, glass, accent, surface opacity, fonts & texture
Settings → Shortcuts	new page	custom keybindings: new conversation, model switch, thinking effort, direct model jumps, etc.
Settings → App Usage	new page	usage stats: aggregated over a selectable time span, with a trend chart and session ranking
Settings → General	added rows	floating history strip (adjustable position / count), user-message Markdown toggle
Settings → Plugins	added tab	"Plugin Marketplace": third-party plugin catalog

---

Appearance (Settings → Appearance)

Appearance offers a large customization space: you can choose the wallpaper, glass level, accent color (optionally auto-derived from the wallpaper), per-surface opacities, tone gradient, dark scrim, fonts & scale, accent scrollbar and an inset vignette, and merge the ui-theme theme preference (light / dark / system) into this section. Changes save through the ui-custom settings namespace and apply immediately (the theme re-renders live, no restart).

Preview — the theme supports a mini-window preview.

Fullscreen preview is also supported — press F2 to exit.

Presets — the plugin ships six built-in presets, each with its own distinct style (a preset works standalone, and your own wallpaper still layers under it):

id	name	look
`ink-teal`	Ink Teal 黛青	jade-green gradient, quiet and steady
`ink-blue`	Ink Blue 黛蓝	deep blue gradient, restrained and profound
`dusty-rose`	Dusty Rose 藕荷	dusty-rose gradient, warm and gentle pink
`apricot-gold`	Apricot Gold 杏金	elegant, understated warm gold
`mist-gray`	Mist Gray 雾灰	cool, quiet gray-blue mist
`ink-violet`	Ink Violet 墨紫	deep violet, serene and mysterious

More art choices will extend this list — see src/client/presets.ts.

Glass levels — glass is the translucency switch; an explicit wallpaperBlur always overrides the level's default radius:

Level	Blur	Saturation	Vibe
`off`	0px	1.0	opaque, no glass
`light`	6px	1.15	subtle glass
`frosted`	14px	1.25	strong frosted glass (default)
`mica`	22px	1.1	soft static texture, keeps the wallpaper's hues

Theme config keys — every field is optional; explicit values always win over the preset:

Key	Type	Default	Meaning
`preset`	string	`''`	Preset id (see the table above); `''` = no preset
`wallpaper`	string	`''`	Wallpaper URL/path (web-reachable); empty string keeps the plugin off
`wallpaperBlur`	number 0–60	glass default	Blur radius (px) on `#root`; an explicit value overrides the glass level
`glass`	enum	`frosted`	`off` / `light` / `frosted` / `mica` (see the glass-level table)
`accent`	string	`#4176e6`	Accent color; the whole deepseek ramp is derived from it
`autoAccent`	boolean	`false`	Derive the accent from the wallpaper automatically (overrides `accent` on success)
`surfaceOpacity`	number 0–100	`100`	Main surface opacity (chat/details columns)
`sidebarOpacity`	number 0–100	`100`	Sidebar opacity
`chatSurfaceOpacity`	number 0–100	`100`	Chat column opacity (via `--dsw-chat-surface`)
`inputOpacity`	number 0–100	`100`	Composer input opacity
`codeBlockOpacity`	number 0–100	`100`	Code block / inline code opacity
`darkSurfaceOpacity`	number 0–100	`surfaceOpacity`	Dark-mode surface opacity (independent knob)
`gradient`	string	`''`	Light-theme gradient layered over the wallpaper; empty = none
`darkScrim`	number 0–100	`0`	Dark-theme scrim strength over the wallpaper
`fontFamily`	string	`''`	Font stack override; empty = theme default
`scrollbarAccent`	boolean	`false`	Tint the scrollbar with the accent color
`vignette`	boolean	`false`	Soft inset vignette on the app root
`customCss`	string	`''`	Raw custom CSS appended verbatim (escape hatch)
`customVars`	object	`{}`	Extra CSS custom properties written onto `<html>` (escape hatch)

Full example:

config:
  preset: 'ink-teal'
  wallpaper: 'https://example.com/wall.jpg'
  glass: 'mica'              # or wallpaperBlur: 8 for a custom radius
  autoAccent: true           # accent derived from the wallpaper
  chatSurfaceOpacity: 70
  customCss: |
    .some-hashed-class { border-radius: 16px; }
  customVars:
    '--my-accent-soft': 'rgb(255 127 178 / 0.3)'

---

Shortcuts (Settings → Shortcuts)

A new settings page with customizable keybindings. Values live in the ui-custom settings namespace, so runtime changes apply immediately without a restart (the loader config acts as the composition base, and Reset reverts to the loader defaults).

Action	What it does
`newConversation`	Start a new conversation (same as the sidebar's New Session button)
`switchModel`	Cycle to the next model in the session's catalog (wraps; the new model starts at its own default reasoning effort)
`cycleThinking`	Cycle the current model's reasoning effort (off → … → max, wraps)
`sendMessage`	Composer send gesture (default: `Enter`)
`newline`	Composer newline gesture (default: `Shift+Enter`)
`usagePanel`	Pop the app-usage panel (unbound by default — enable it in Settings, e.g. `Mod+Alt+U`)
`defaultWorkspace`	The workspace where `newConversation` opens (empty = current/recent)
`modelShortcuts`	One-to-one model jumps: each combo goes straight to a specific model (combo / provider / model)

Example:

config:
  shortcuts:
    newConversation: 'Mod+Alt+N'
    switchModel: 'Mod+Alt+M'
    cycleThinking: 'Mod+Alt+T'

Used to Enter for newlines? Set send to Mod+Enter and newline to Enter (when both gestures hit at once, send wins):

config:
  shortcuts:
    sendMessage: 'Mod+Enter'
    newline: 'Enter'

Model actions go through the same session.models / session.selectModel RPCs as the built-in model selector, so the model shown in the composer stays in sync; addressed subagent sessions are skipped (same as the UI). Combos without Mod do not fire while an input is focused, so they never hijack normal typing.

---

Usage statistics (Settings → App Usage)

The usage-statistics page aggregates each session's total usage (token-meter + session-stats) over a user-selectable time span, from the current year down to the last three days. It shows total / input / output tokens, cache hits, usage time, and session & step counts, together with a usage trend chart and a session ranking. The session list rows already carry the host-computed projection baseline, so no extra RPCs are needed.

The panel can be popped up from any screen via a shortcut.

---

General settings additions

New additions under Settings → General:

Floating history strip (position / count) — records the history of a conversation:

Position: left / right / off (default off — hidden when off);
Count: how many recent turns to show (default 10, 0 = all);
Clicking an entry smooth-scrolls to the matching message; entries come from

the mounted session snapshot, so jumping is a pure DOM operation — no extra RPCs;

Pinning is supported: from the message action row (between copy and

branch) you can pin a turn onto the strip; pinned turns ignore the count limit, always show, and carry an accent-colored border.

User-message Markdown rendering — off by default; when enabled your own messages render as Markdown (headings, lists, code blocks, @subagent / @skill references, …); when off, they look the same as stock plain text.

---

Plugin settings additions

A third tab, "Plugin Marketplace", is added under Settings → Plugins: it calls the GitHub API to discover projects tagged with the dsh-plugin topic, providing a catalog of third-party DSH plugins.

---

Install

1. Make sure the package is included in your build (pnpm run build:lib:client). 2. Add a browser-roster row to your web profile's patch layer — ~/.dsh/profiles/web/cordis.patch.yml (or the corresponding dsh.client roster in your profile):

- id: ui-custom
  name: '@ha-na-bi/dsh-client-ui-custom'
  config:
    preset: 'ink-teal'        # pick a preset; any field below overrides it
    wallpaper: '/my-wall.jpg'
    wallpaperBlur: 14

3. Restart dsh web.

Self-builders: for the settings pages to load, the ui-custom namespace must be in the web client's settings exposure allowlist (WEB_SETTINGS_NAMESPACES in packages/host/apiproxy/src/api-proxy.ts) — it is already in this checkout.

---

How it works

The browser half first resolves preset (presets.ts), merges

DEFAULTS ← preset ← config and clamps every field (config.ts), then writes the --dsu-* custom properties onto <html> (apply.ts). The runner passes the roster row's config to apply(ctx, config) as the second argument.

The stylesheet (custom.module.css) consumes these variables and re-declares

the theme tokens on body / body[data-ds-dark-theme] with selectors that out-specify the theme sheets, so the plugin always wins the cascade — no plugin or shell source is modified.

Frosted glass adds backdrop-filter to #root, and translucent surfaces

show the wallpaper through it.

The chat-column knob relies on ConversationRoot reading

var(--dsw-chat-surface, var(--dsw-alias-bg-base)) — a one-line, fully backwards-compatible fallback (stock Harness behavior without the token is exactly as before). See packages/client/ui-conversation.

Framework layout:

packages/client/ui-custom/
├── src/client/
│   ├── index.ts          # plugin entry: resolve preset → normalize → apply
│   ├── config.ts         # CustomThemeConfig, DEFAULTS, normalizeConfig (type narrowing + clamping)
│   ├── presets.ts        # Them

…

来源信息

安装

检查来源文件