quaner1234-cmd/DSH-THEME-KAMI

dsh-kami-theme

Kami 风格（纸媒 / editorial）DeepSeek Harness WebUI 主题。

打开 DSH 后，你会觉得是在一张安静、克制的纸张上工作：暖羊皮纸画布、
墨蓝强调色、衬线正文与标题、发丝线边框、克制的阴影——而不是又一个
SaaS 聊天界面或 Claude / Anthropic 仿制皮肤。

视觉语言直接蒸馏自 tw93/Kami（MIT）；
工程结构与 DSH 官方 theme/plugin 接口完全兼容，遵循社区已验证的
dsh-skin-market /
awesome-dsh-plugin 生态惯例。

Kami light
Kami dark

视觉要点（与 Kami 的对应）

| Kami token（来源 skills/kami/references/tokens.json） | 本主题用法 |
| --- | --- |
| --parchment #f5f4ed / --ivory #faf9f5 | 画布底色 / 抬升表面（会话、菜单、浮层） |
| --brand #1B365D / --brand-light #2D5A8A | 主强调色 ink blue：主按钮、链接、选中态；另有 4 个低饱和辅助色仅用于状态（见「深色模式的色彩层级」） |
| --near-black #141413 → --olive #504e49 暖灰梯 | 正文 → 次要 → 三级文字（二级 --dark-warm #3d3d3a） |
| --border / --line 发丝线 | 全界面边框与分隔线（暖灰而非冷灰） |
| Kami 的 --sans: var(--serif) 规则 | 全界面 serif-led：正文、标题、甚至 UI 控件全部衬线（Latin Charter、中文宋体），仅代码保持等宽 |
| --breaking-bg #f0e0d8 + --breaking-fg #8b4513 | 警告色 |
| 不超过两种阴影的"耳语阴影" | 浮层、弹窗、toast |

Kami 本身没有深色模式；本主题的深色「夜纸」是一种原创改编
（暖黑画布 + 钢蓝墨），遵循同样的编排规则，跟随 DSH 原生
浅色 / 深色 / 跟随系统 偏好自动切换。

状态层：一眼可辨的 idle / running / disabled

状态识别靠形状 + 填充 + 描边三层同时变化，而不是只改颜色深浅；
三态在任何一档外观下都不需要思考就能区分。

| 发送键状态 | 浅色填充 | 浅色图形 | 深色填充 | 深色图形 | 区分手段 |
| --- | --- | --- | --- | --- | --- |
| disabled（未输入） | 透明（中空） | #a5a294 | #212220 | #787568 | 只有 1px 发丝环，无投影、无实底 |
| idle（可发送） | #1B365D 实底 | #faf9f5 | #3a6ea8 实底 | #f5f2e8 | 实心填充 + 1px 微投影，唯一「有重量」的一态 |
| running（生成中） | #e6edea | #2f5b54 | #1f2b28 | #8fc3b9 | 图案变为停止方块 + 1.5px 描边 + 呼吸光晕 |

- 关键约束：三态图形与自身填充的对比度分别为 idle 11.51:1 / running 6.44:1 /
disabled 2.32:1（浅色）、4.72:1 / 7.44:1 / 3.75:1（深色）。disabled 永远
是最弱的一档（WCAG 1.4.3 豁免禁用控件），running 靠中空 + 描边 + 动效与
idle 的实底拉开，因此不存在「浅蓝被误读为 disabled」的歧义。
- 浅色 hover 更深（#1B365D → #12283f）、深色 hover 更亮（#3a6ea8 → #4a7eba）：
两种模式都朝「与画布对比更强」的方向走，所以 hover 反馈的方向始终一致。
- 动效只有 @keyframes kami-send-live（描边 + 光晕呼吸），并在
prefers-reduced-motion: reduce 下完全关闭。

当前预设（「创造模式」所在位置）的激活态

模型/模式选择器是 composer 里的胶囊按钮。折叠→展开→展开时 hover 三级：

| 状态 | 填充 | 描边 | 文字 / 图标 |
| --- | --- | --- | --- |
| 折叠 | #eae8dd | #dcd9cb 发丝 | 图标墨蓝，chevron 保持安静（#6b6a64） |
| 展开（当前生效） | #e4ecf6 墨蓝薄染 | #1B365D 1px 墨蓝环 | 标签 / 图标 / chevron 全部转为墨蓝 |
| 展开 + hover | #d6e3f2 再深一档 | 墨蓝环保持 | 全部保持墨蓝 |

这一组变化是「当前模式」最明确的表达：颜色、描边、chevron 三者同时收敛到墨蓝。
深色对应值为 #242520 / #243546 / #2c4055，环与文字为 #7ea6da / #8fb1e0。

同一套「墨蓝薄染 + 墨蓝环 + 墨蓝文字」也用于当前选中的预设卡片
（设置里的 active 卡片）与已选中的菜单项，所以「选中」在全界面只有一种语言。

限制：CSS 无法单独定位「创造模式」这一个预设。胶囊按钮只暴露
title 与 aria-expanded，标签是 span 里的纯文本节点，没有 preset-id
属性。因此激活态表达的是「当前预设是哪一个」（谁当前生效谁被点亮），
而不是给某个特定模式写死一套配色——在插件边界内这是唯一诚实的做法。

深色模式的色彩层级：五个低饱和辅助色

深色原本几乎只有暖灰 + 钢蓝，状态之间只能靠明度区分。现在引入五个同明度带
的辅助色，靠色相而不是响度分隔——这就是「少量辅助色」不会变成
彩色 UI 的原因：

| 角色 | 浅色 | 深色 | 深色对画布对比度 | 用途 |
| --- | --- | --- | --- | --- |
| ink 墨蓝 | #1B365D | #8fb1e0 | 7.86:1 | 强调、选中、当前生效 |
| live 松石 | #2f5b54 | #8fc3b9 | 8.80:1 | 运行中 / 进行中（唯一的“活着”信号） |
| sage 苔绿 | #4c6432 | #9cbb7c | 8.09:1 | success |
| brass 黄铜 | #8b4513 | #dcab6b | 8.31:1 | warning |
| clay 陶土 | #b3402e | #e1916f | 6.99:1 | error |

- 五个角色在深色画布上都落在 7–9:1 这一窄带内，差异来自色相与彩度，
所以任何一色都不会比别的更“吵”。
- 辅助色只用于状态：selected（ink 薄染）、hover（ink 低透明 wash）、
running（live）、success / warning / error（sage / brass / clay）。
正文、标题、边框仍是暖灰梯——Kami 的克制没有让步。
- 深色表面层次同步抬升一档，让 hover / selected 真的“看得见”：
specific-bubble #20293a → #22303f、sidebar-nav-item-active #20293a → #243546、
sidebar-nav-item-hover α.08 → α.11、button-ghost-active-hover #2a3a4d → #2f4459。
- 状态色单一来源：每档外观各有 6 个 --dsw-alias-state- / label- token
改为指向 var(--kami-)，不再各自写死十六进制，避免浅深两套调色板各自漂移。

兼容版本

- 目标运行时：dsh web 0.1.0-rc.6 或更新（社区插件市场的最低门槛）。
- 已在 0.1.2-alpha.5 上实测，并在 0.1.5-rc.1 上复验（见下方验证记录）。
- 依赖：无。不打包任何字体文件；全部使用系统字体 / 操作系统自带中文字体栈。

安装

方式一：dsh plugin CLI（推荐）

从本仓库（GitHub 安装需要提交 / 发布后路径）
dsh plugin --profile web add "github:quaner1234-cmd/DSH-THEME-KAMI"

发布到 npm 之后（占位命令，名称以实际发布为准）
dsh plugin --profile web add dsh-kami-theme

方式二：本地开发安装

dsh plugin --profile web add "file:/path/to/DSH-THEME-KAMI"

方式三：插件市场

本主题在 awesome-dsh-plugin / dsh-skin-market 收录后，可在
设置 → 插件市场 → Themes 中一键安装、一键切换（主题之间互斥）。

安装后刷新页面或重启 dsh web 生效。

启用 / 关闭 / 卸载

生效时机：本主题与 DSH 的所有插件一致——roster（插件清单）在
dsh web 启动时组装。运行期间修改启用状态，需要重启 dsh web
或刷新页面（刷新只对新 bundle 版本生效；改变 disabled 需要重启服务）。
运行时退出（插件被停用/卸载时的清理）由 ctx.effect disposer 保证：
立刻移除 data-dsh-kami 属性与唯一的  标签，逐像素还原。

- 启用：安装即默认启用（patch 行已插入 roster）。若曾显式关闭，把
cordis.patch.yml 中对应行的 disabled: true 移除，然后重启 dsh web。
- 临时关闭（不卸载）：在已安装包的 cordis.patch.yml（或
~/.dsh/profiles//cordis.patch.yml，若该 profile 自带 patch）
中给对应行加 disabled: true，然后重启 dsh web：

已安装包：~/.dsh/profiles/web/node_modules/dsh-kami-theme/cordis.patch.yml
- insert:
- id: dsh-kami-theme
name: 'dsh-kami-theme'
disabled: true

- 卸载：

dsh plugin --profile web remove dsh-kami-theme

该命令移除依赖、并从 dsh.profile.bundles 中摘除本包名，然后重启生效。
本主题没有任何全局副作用：不写 localStorage / profile 配置 / 其它目录，
卸载后仓库外零残留（唯一足迹就是 profile 依赖、bundles 条目与该包目录，
全部由以上命令清理）。

- 恢复原始界面：本主题不修改任何 DSH 源码、不修改框架 token 定义，
只通过挂在 body[data-dsh-kami] 属性上的追加 CSS 覆盖 token 值。
插件卸载 / 关闭时，ctx.effect 的 disposer 会移除该属性与唯一的
标签，逐像素恢复原生外观，不留任何污染（无 JS 内联样式残留）。

工作方式（工程说明）

- 纯浏览器端主题：lib/index.js 为主机半段（刻意 inert，无任何文件 / 网络
/ 服务权限），lib/client.js 为浏览器半段。
- 遵循 DSH 官方 bundle 契约：window.__ModuleLoader__.load({ id, factory })，
无需构建步骤；package.json 声明 dsh.bundle.patch 与 dsh.client.platform: "web"。
- 通过 body[data-ds-dark-theme]（由 @deepseek-ai/dsh-client-ui-theme
的 ThemePresenter 维护）自动跟随原生浅色 / 深色 / 跟随系统偏好。
- 级联契约：DSH 每次切换外观都会重新追加自己的 token 样式表，文档顺序
不可依赖。本主题每条规则都以 html body[data-dsh-kami] 前缀提升优先级，
两个调色板块互斥（浅色用 :not([data-ds-dark-theme]) 限定），在优先级
层面永远压过框架的 body[data-ds-dark-theme]，并且浅色值永远不会漏进深色。
- 在不修改框架的前提下，覆盖的是同一套 --dsw-alias- / --dsw-specific-
/ --dsw-font- 设计 token；对选择器（代码块发丝线、选区、标题字距、
链接下划线）仅做 attribute 作用域下的元素级微调，类名片段（如
md-code-block）均为尽力而为——若未来版本改名，规则自动停止匹配，
不影响任何布局与功能。

已知限制

- roster 生效需重启：与 DSH 所有插件一致，启用状态（disabled: true）
与卸载在服务启动时组装生效；运行期间改配置需要重启 dsh web。
- 衬线字形有限：Charter 只有 Regular/Bold 两档（400/700），500 会渲染为
400。标题层级依赖字号级差 + 负字距 + 字距而非字重；小标题（h4+）用
600 承担。中文衬线经系统栈回退到宋体（Songti/Source Han/SimSun），不打包
任何字体。
- 「深度求索中…」流光保留 DSH 原生的渐变文字动效（background-clip:text
+ 扫光），只是把色板换成墨蓝；浅色下扫光高光段对比度较低（约 1.2:1），
这是原组件的装饰性设计，正文文字主色 11:1，不影响阅读。
- DSH 大量圆角由组件级 CSS 决定（--dsl- 局部变量等），token 层无法以
不碰源码的方式统一收窄；本主题保留 DSH 默认圆角，但通过发丝线、留白与
衬线字让整体观感保持 Kami 的「平、细、静」。
- Kami 原始仓库没有深色模式与完整的成功/错误色板；本主题为 DSH 必要状态
（错误、警告、成功）提供了暖色系的克制配色，保证对比度与可辨别性，但
这些并不声称是 Kami 原文。
- 状态层依赖类名片段与结构特征：发送键的 idle / running 之分靠
:has(> svg > rect)（停止方块 = running）与 [class="_primary"]，
预设胶囊靠 [class="_seat"] / [class="_chevron"]，running 标记靠
[class="_markBusy"] / [class="_glyphProgress"]。这些片段与结构已在本
版本实测确认；若未来 DSH 改变图标结构或类名，对应规则会自动停止匹配并
回落到原生外观，不会误伤其它元素，也不需要改布局。
- 浅色下 hover / selected 的填充差本身很小（胶囊底 #eae8dd 对画布
1.11:1，墨蓝薄染对胶囊底 1.03:1），这是浅底色的物理限制。因此浅色的选中与
hover 表达主要靠描边与墨蓝文字（墨蓝于薄染底 10.18:1），而不是靠填充深浅。
- 「创造模式」无法被 CSS 单独定位（见上文限制框）：胶囊按钮没有 preset-id
属性，激活态只能表达"当前预设"。若将来 DSH 暴露该属性，可在此加一条规则。
- 若未来 DSH 前端大面积重构 token 名，本主题会像社区其他皮肤一样随版本
跟进（token 覆盖天然有向后兼容的降级空间）。

验证记录

在真实运行中的 DSH WebUI 中实测（2026-09-10，先在 0.1.2-alpha.5，后又在用户升级的 0.1.5-rc.1 上复验）：

- 浅色：正文 #141413 于 #f5f4ed 画布，对比度 16.72:1；全页对比度
扫描 0 个违规（含错误/警告/成功状态、代码、选中态、hover 态）。
- 深色：正文 #e8e6dc 于 #1a1b17 画布，对比度 13.84:1；全页扫描
0 个违规；「深度求索中…」流光两端 7.86:1 / 15.65:1。
- 衬线落地：--dsw-font-family 一处翻转使全页文本节点（2048 个）进入
Charter/宋体；几何对比显示零布局回归（无截断、无溢出、无换行变化）。
- 浅/深回环：经设置 UI 在 浅色→深色→浅色 间切换后逐 token 复查，暖色
梯形与墨蓝在所有模式下保持，无冷色回漏。
- better-sidebar 适配：其覆盖式面板（absolute + z-index）的几何在
有无本主题时完全一致（A/B 实测）——<768px 窄窗口下插件按自身移动端逻辑
使用 width:100vw 全宽，属插件设计而非主题回归；主题负责表面层次：
bg-layer-1 从与画布同色改为 Kami ivory（浅 #faf9f5 / 深 #21221d），
面板与对话区有清晰分界 + 发丝线边缘。
- 截图证据：assets/preview-{light,dark}.png（README 顶部）、
assets/verify/01-boot.png ~ 09（设置页、代码块、浅/深 better-sidebar 面板、
状态层对照图 08-states-{light,dark}.png）；量化审计
assets/verify/audit-final-{light,dark}.json、
assets/verify/audit-state-layer.json。

状态层复验（2026-09-10，0.1.5-rc.1）

同一台真实运行的 dsh web，三种互相独立的取证方式：

1. 计算样式探针：把线上节点克隆进合成作用域，逐态读取 getComputedStyle；
:hover 用 CDP CSS.forcePseudoState 强制施加，不依赖命中测试。
真实生产按钮另外直接在空/有输入两种 composer 下实测（transform:
translateY(-2px) 等原生规则原样保留）。
2. 像素取证：对每个状态单独裁图，用直方图取主色，确认画出来的颜色与
计算样式一致。浅色实底 #1b365d 占 53.7%、图形 #faf9f5 26.7%；
深色实底 #3a6ea8 53.7%、图形 #f5f2e8 3.0%；disabled 两者都是中空。
3. 静态回归证明：把 lib/client.js 渲染成 CSS 后与上一提交逐 token 对比——
浅色 132 个 token 变了 31 个、深色 134 个变了 45 个，其中能着色文字的 token
没有一个损失对比度（唯一变值的是深色 state-success-primary，
#9cb97c → #9cbb7c，对比度 7.95 → 8.09，是把成功色并入单一来源时的取整），
其余全部是填充 / 描边 / 分隔面。

- 状态层共 26 项对比度断言 × 2 档外观 = 52 项，0 失败
（阈值：文字 4.5:1、大字号与图形对象 3:1、禁用态豁免但必须是最弱的一档）。
- 全页文字扫描：浅色 34 个文本节点 / 深色 34 个，0 违规；正文对比度
16.72:1（浅）/ 13.84:1（深），与上一轮基线逐位相同。
- CSS 体积 22,183 → 28,054 字节（状态层 +25 个 --kami- token、50 条声明）；
渲染后花括号平衡、无未声明引用、无未被引用的 token。
- 实测定位：本站 dsh web 0.1.5-rc.1；主题样式表在页内 28,054 字节，
浅/深切换后逐 token 复查无冷色回漏。

选择器作用域核查（每个 [class=…] 片段都查了归属包）

状态层用的是 CSS-module 类名片段，所以逐个片段在所有 DSH bundle 里做了
唯一性 / 归属扫描，确认它只能命中预期组件：

| 片段 | 命中数 | 归属 | 结论 |
| --- | --- | --- | --- |
| _seat / _seatIcon / _seatLabel | 3 | dsh-client-ui-agent-preset | 同一组件族，正是预设胶囊 |
| _cardActive / _cardName | 2 | dsh-client-ui-agent-preset | 正是「当前使用」的预设卡片（不是别处的卡片） |
| _markBusy / _markActive | 2 | dsh-client-ui-chat | 会话内的 running 标记 |
| _glyphProgress | 1 | dsh-client-ui-chat | 运行中字形 |
| _selectedFill | 1 | dsh-web-frontend | 全前端仅此一处，零歧义 |
| _chevron | 4 | model-selection / web-frontend / 预设胶囊 | 另有 _chevronOpen / _chevronHover；规则限定在 [data-composer-seat] button[aria-expanded="true"] 内，只会命中胶囊自己的 chevron |
| _pending | 10 | 仅 1 个是 CSS 类 | 其余 9 个（_pendingPlan / _pendingRow / _pendingWrites …）都是 JS 字段名，不是 DOM 类名；真实匹配只有 composer 的 _pending |
| _primary | 3 | 另有 _primaryButton | _primaryButton 属 settings-models 设置页，不可能出现在 [data-composer-seat] 内 |

所有规则同时被 [data-composer-seat]（composer 作用域）与
html body[data-dsh-kami]（主题作用域）双重限定，因此即使类名片段在别处
碰撞，也不会漏到主题作用域之外的组件上。

设计来源与许可证

- 视觉来源：tw93/Kami，MIT License。
设计 token 的完整读取与引用：docs/kami-design-token-report.md。
- DSH 主题生态工程调研（dsh-skin-market 逐条引用）：docs/dsh-skin-ecosystem-engineering-report.md。
- 本主题代码：MIT License（见 LICENSE）。
- 声明：本仓库不包含、不重新分发任何字体文件。中文衬线依赖系统字体
（如 macOS 宋体 / 苹方、Windows 宋体 / 微软雅黑、Linux Noto Serif CJK）；
不包含 TsangerJinKai02 或其他任何不由 MIT 许可的字体。
- 若引用、改编 Kami 的其他 MIT 代码，均按 MIT 要求保留版权与许可说明。

提交 DSH Skin Market

dsh-skin-market 收录采用「一个 PR、一个 YAML」流程（详见
docs/dsh-skin-ecosystem-engineering-report.md）：

registry/skins/quaner1234-cmd__DSH-THEME-KAMI.yml
url: https://github.com/quaner1234-cmd/DSH-THEME-KAMI

CI 会自动水合 package / commit / loader 行 / 截图并重新生成 catalog。