dsh-background-by-model 0.5.3 → 0.5.4

package/README.zh.md

@@ -11,7 +11,7 @@
 
 一个 **DeepSeek Harness** 外观插件，核心是一份**有序的模型规则列表**：每条规则自带壁纸、主题色、布局模式、取景、透明度与模糊度，切换模型即切换背景。
 
-> **v0.3.0 是破坏性更新**：视频背景、生成式背景与全局主题色均已被移除。详见[从 0.2.x 升级](#从-02x-升级)。
+> **v0.3.0 是破坏性更新**：视频背景、生成式背景与全局主题色均已被移除。详见 [CHANGELOG.zh.md 的 v0.3.0 条目](./CHANGELOG.zh.md#v030)。
 
 ---
 
@@ -79,7 +79,7 @@
 - **外观随规则走** — 壁纸、主题色、布局模式、取景、透明度与模糊度都是每条规则自己的属性；除「界面」页外没有任何全局外观项。
 - **导入 / 导出** — 一键把**每一条规则连同它的图片**导出为 `dsh-background-by-model-theme.json`（版本 3，图片以 base64 内联），可随时导入还原。
 - **文件持久化** — 所有设置与图片保存到文件系统 `~/.dsh/.dsh-background-by-model-data/`，不依赖 `localStorage`。
-- **自动迁移** — 旧版单壁纸配置在首次读取时自动升级，详见[从 0.2.x 升级](#从-02x-升级)。
+- **自动迁移** — 旧版单壁纸配置在首次读取时自动升级，详见 [CHANGELOG.zh.md 的 v0.3.0 条目](./CHANGELOG.zh.md#v030)。
 - **中英双语** — 完整的中英文界面，自动跟随语言设置。
 - **主题守护** — 宿主重置主题后自动重新激活自定义主题。
 
@@ -111,7 +111,7 @@
 
 原先的 **「色彩」** 选项卡已删除——主题色改为每条规则自己的属性；原 **「背景」** 选项卡已改造成 **「模型背景」**。
 
-## 存储位置与迁移
+## 存储位置
 
 数据目录：`~/.dsh/.dsh-background-by-model-data/`（Windows：`C:\Users\<你>\.dsh\.dsh-background-by-model-data\`）
 
@@ -120,16 +120,6 @@
 | `theme-config.json` | 规则列表 + 全局「界面」设置 |
 | `modelbg-<slot>` | 每条规则的图片，保存为原始字节，无扩展名 |
 
-### 从 0.2.x 升级
-
-v0.3.0 **移除**了三项功能：
-
-- **视频背景** — 不再支持。
-- **生成式背景** — 网格渐变（mesh）、Shader、几何图案（pattern）均已移除。
-- **全局主题色** — 改为每条规则自带。
-
-除此之外升级是自动且无损的：首次读取时，如果发现旧格式配置（没有 `rules` 数组），插件会把旧的单张 `wallpaper.jpg` 变成**规则 1**，匹配串留空（即纯兜底），并继承旧的主题色、布局模式、透明度、模糊与取景；同时清理旧版遗留的视频文件。老用户升级后外观保持不变——只有想按模型区分背景时，才需要自己再加规则。
-
 ## 安装
 
 ### 方式一：npm 安装（推荐）
@@ -182,12 +172,6 @@ pnpm run typecheck
 
 `pnpm test` 会构建并做类型检查（`tsdown && tsc -p tsconfig.json`）。
 
-## 兼容性
-
-- **dsh `>=0.1.7-rc.2`** — 在 `peerDependencies`（所有 `@deepseek-ai/dsh-*` 条目）中声明，并在 `engines.dsh` 中同步。宿主会用自身运行时版本校验这些 peer，因此更旧的宿主会直接按名字报出「不兼容」，而不是静默运行。
-- **[`dsh web`](https://github.com/deepseek-ai/deepseek-harness)** — 同时兼容 npm 发布版与新版源码构建。插件会自动检测宿主携带的客户端模块表（新版 `@deepseek-ai/dsh-client-store` 或旧版 `@deepseek-ai/dsh-client-runtime`），并在运行时据此解析 `defineStore`。
-- **[deepseek-harness-desktop](https://github.com/anywhere-labs/deepseek-harness-desktop)** — 支持
-
 ## 常见问题
 
 **所有模型看起来都一样，为什么？**
@@ -216,6 +200,14 @@ pnpm run typecheck
 
 ## 近期优化
 
+> 这里只列最近两个版本；更早的版本（v0.5.0 及以前）见 [CHANGELOG.zh.md](./CHANGELOG.zh.md)。
+
+### v0.5.4
+
+- **填充上的文字改读宿主的「色块墨色」，不再用 `brand-text`** — 跟随系统主题时，布局模式的选中胶囊、「+ 新增规则」按钮和设置页的品牌方块，底色取自宿主自己的 `--dsw-alias-brand-primary`，而它**不是品牌色、是对比墨色**：宿主浅色档近黑（`#0f1115`），深色档近白（`#f9fafb`）。它们的文字读的是 `--dsw-alias-brand-text`，而宿主在两档里都把它定义成与底色**完全相同**的值、自己的 CSS 从不使用。于是在深色系统上就成了有底色却没有文字的方块 —— 白底主按钮、白底选中胶囊、白底图标块（实测正好 `#f9fafb`），只有插件自己持有一套调色板时才看得见。四处现在统一读 `--dsw-alias-label-primary-inverted`，也就是宿主自己画在品牌/对比色块上的墨色：浅色档 `#fff`，深色档 `#353638`。
+- **开关打开态的圆点是同一个毛病的小号版本** — 硬编码 `#fff` 画在 `--dsw-alias-brand-primary` 轨道上，而深色档那条轨道本身就是白的。
+- **插件自建的深色调色板是同一问题的镜像** — 那一档的品牌填充故意保持 50% 以上亮度，而**宿主自己的主按钮**用来写标签的 `--dsw-alias-label-primary-foreground`（画在 `--dsw-alias-button-primary-fill` 上）被写死成白色。现在它随填充亮度翻转（与 `brand-text` 共用一条判定），浅色分支也补上了 `label-primary-inverted`，让插件的调色板自己成对，而不是继承宿主当前恰好所处的档位。
+
 ### v0.5.3
 
 - **一次只用一个调色板：清空主题色不再留下上一次的皮肤** — 设置弹窗里那三段重定向（`--dsw-alias-bg-layer-*` → 插件私有变量）**没有宿主回退**，轨迹页与三栏的内联背景同理，而它们只在 teardown 时才清理。于是把主题色切回「系统主题」后会留下「深色界面 + 浅色弹窗、白底白字」。现在这些表面由一个调色板来源统一驱动：有主题色时用规则自己的令牌，没有时**读取宿主自己的令牌**再套上你的透明度，切换时一并交还；无回退的重定向用 `html[data-dab-themed]` 门控，只有变量确实写了才生效。
@@ -225,86 +217,6 @@ pnpm run typecheck
 - **令牌指纹只在样式表写入成功后记账** — 写入抛错时不再把指纹提前记下，避免界面卡在旧调色板上直到另一个 key 变化。
 - **`package.json` 描述里的乱码破折号修正**（它直接显示在 npm 页面上）。
 
-### v0.5.0
-
-- **宿主自检整块删掉了。** 连同它的一切：设置页的 **「宿主自检」** 选项卡、约定表（`src/host-contracts.ts`）、浏览器探测（`src/client/judge.ts`）、安装目录扫描（`src/host-scan.ts`）、`hostCheck` RPC、`pnpm scan` 脚本以及它的测试。插件只留下它真正做的事：规则、壁纸、界面透明度与模糊。
-- **`0.5.1` 与 `0.5.2` 的内容与 `0.5.0` 完全相同。** 这两个号是发布端的噪音：第一次 `npm publish` 返回的是 HTTP 202，版本要几分钟后才出现在 registry 上，被误当成失败又发了两遍。三个版本都在线上、代码逐字节一致（12 个文件），当时 `latest` 指向 `0.5.2`。装哪个都行；想按标签点名就固定 `0.5.2`。
-
-### v0.4.5
-
-- **`optionalWhen` 终于按它名字的意思工作了** — 这个字段的文档写着「只有当这块界面在屏幕上时才检查」，但探测实现的是**反过来的**：锚点**不在** DOM 里时反而报 *未观察*，锚点**在**时才会去报失效。于是三条停靠约定里的两条、以及两条对话视图约定，全都在检查错误的状态 —— 这就是健康的停靠栏会报出「停靠空位 失效 / no element matches `[data-dockkit-empty]`」的原因。现在这个辅助函数把锚点当作**正向断言**来读，并且把所有锚点改名成它们真正的含义（`dockHasTab`、`dockHasNoTab`、`chatHasMessages`、`paneFloated` …），这样「用缺席来命名」的锚点再也不可能悄悄把检查反过来。四个测试把由此得到的状态表两个方向都钉住了。
-- **关于消息列的约定不再对着「还没有任何消息」的会话开火** — `[data-chat-flow]` 只在会话**有消息**时才渲染，所以它不在，恰恰是全新会话（宿主的 `data-content-phase="hero"` 首屏）和轨迹页的正常状态。原来的锚点是「对话滚动区存在」，而这三个状态下它都存在，于是检查在首屏和**轨迹页**都报了「属性改名」—— 也就是面板上你看到的第二个失效。现在锚点改用 `[data-chat-turn]`，宿主给每条消息行打的标记，这是唯一「恰好只在消息列该存在时存在」的东西。实测：首屏 → 消息列 0 / 消息行 0；发一条消息后 → 1 / 4；轨迹页 → 0 / 0。
-- **`visible` —— 「存在」和「在屏幕上」不是同一个问题** — 标记了 `visible: true` 的选择器检查现在要求元素真的在屏幕上，于是宿主用 `visibility:hidden` 停放在一边的元素，无法满足一条关于「用户正在看的界面」的约定。停靠空位**故意不标记**：宿主在开合 tab 时一直把它渲染着并隐藏，去问它可不可见，就是在问一个宿主两个方向都在用的状态。
-- **再写死一条锚点规则** — 锚点必须命名「这个属性**预期出现**的状态」，绝不能是恰好同时出现的邻居。这个功能里四次「误报失效」全都是同一个错误：界面明明挂着、宿主行为也对，只是**没有任何东西**能让那个属性落上去。
-
-### v0.4.4
-
-- **停靠相关的约定不再拿「样式表问题」去问 JS 属性** — `dockkit.content` 与 `dockkit.float` 原本是 `rule` 检查（「宿主样式表里有没有提到这个字面量」）。但这两个属性都是宿主从 **JavaScript** 打上去的：`data-dockkit-content` 只在**有 tab** 的停靠页宿主上，`data-dockkit-float` 只在用户真的把面板浮动起来时；宿主从来没为它们写过任何 CSS 规则。所以那个问题无论宿主健不健康都只会回答「没有」。现在两条都改成**存在性**检查，分别用宿主自己的 tab 标记（`data-dockkit-tab`）和浮动态做守卫，于是「没开 tab 的停靠」会报成 *未观察*，而不是「属性改名」。`dockkit.empty`（宿主在「有 tab」时用来替换空位的那个座位）同样改成存在性检查。已在真实宿主上验证：没开 tab 时 `data-dockkit-tab`/`data-dockkit-content` 都不存在；点一下停靠栏的 `+`，两者同时出现（tab 0→1、content 0→1、empty 1→0），此时检查会给出结论而不是跳过。
-- **锚点不再依赖组合符** — 「有 tab」的锚点最初写成 `[data-dockkit-strip-tabs] > *`，这种写法 DOM 替身回答不了，也让夹具和浏览器悄悄产生分歧。现在改成一个普通属性选择器。
-
-### v0.4.3
-
-- **「宿主自检」不再虚报故障** — 它第一次在健康的 0.1.7 上实跑，28 条约定报了 **9 条失效**（7 个令牌「不再声明」、2 个属性「消失」）。**全部是探测读错了地方，宿主一条都没坏**：设计令牌发布在 `body{--dsw-…}` 上，探测却去问 `getComputedStyle(document.documentElement)`；而 `data-plugin` —— 宿主自己的 CSS 模块在**每一个** `<style>` 上都写它 —— 被我当成了「这是插件自己的样式表」，于是检查跳过了整个宿主主题，再把令牌报成改名。两处都已修正，并且各配了会让它复发的测试：令牌读取的宿主元素成了 `ProbeEnv` 的显式成员；识别自己的样式表改用一个只由本插件写入的标记（`data-dab-side`），且用 `getAttribute` 而不是 `dataset` —— `dataset` 只暴露驼峰键，按带连字符的名字去索引它，在夹具里能通过、在浏览器里静默返回空。
-- **`rule` 检查现在会说明自己查的是哪一侧** — 一条令牌约定其实断言了两件不同的事：宿主是否仍**声明**这个名字，以及它是否仍**解析出值**。前者只能从宿主的规则回答，后者只能从实时级联回答；而唯一一条「另一半是本插件自己样式表」的（`.dab-card`）现在显式标为 `side: 'own'`，不再和宿主规则混为一谈。所有被重新发出的令牌都同时带上这两项检查，于是「改名」会被报成改名，而不是「值为空」。
-- **可读但没提到目标的宿主样式表算失效，不算盲区** — 旧逻辑只问「有没有任意一张表可读」，于是一张能读、却什么也没提到的宿主表会让所有令牌检查都通过。现在可读性按侧分别跟踪。
-
-### v0.4.2
-
-- **新增「宿主自检」页 —— 插件现在能说清哪里坏了，而不只是坏掉** — 一个给别人界面做样式的插件，依赖的全是自己不拥有的东西：宿主的会话与模型服务、挂毛玻璃的那些元素、以及被重新发出的设计令牌。这些在 dsh 版本之间随时可能改名，而 0.1.7 那三次故障**全都是静默的** —— 什么都没抛错，界面只是不再跟随设置。现在 设置 → **宿主自检** 会逐条对当前构建做检查（实时 DOM、宿主自己的样式表、Cordis 服务），并给出：是否成立、失效时界面上是什么样子、依赖的字面量、本该由哪个宿主文件定义、以及本插件哪个文件在读取它。**复制诊断报告** 会把两侧结果合并成一份 markdown，直接贴进 issue。仅仅是「当前不在屏幕上」的情况（设置弹窗打开时的对话页、还没开过文件时的右侧栏）会报成 *未观察*，绝不算故障。
-- **同一张表还能离线查，不需要浏览器** — `pnpm scan`（`scripts/host-contract-scan.mjs`）直接扫已安装的 dsh 包，某个约定目标一消失就以非零码退出；所以 `npm i -g @deepseek-ai/dsh@latest` 之后、还没打开界面之前，就能先红一次。它同时打印找到的宿主版本以及是否满足本插件的下限。
-- **一张约定表，三处消费** — `src/host-contracts.ts` 把每个接触点只声明一次，浏览器探测、离线扫描与测试都读它，所以新加的选择器不可能被「本该发现它变化」的检查漏掉。`pnpm test` 覆盖这张表、探测逻辑（对着一个按宿主 DOM 形状写的夹具）、界面样式表与版本下限。
-- **约定断裂不再只留在日志里没人看** — 启动 2.5 秒后，只要有约定失效，浏览器控制台会逐条打印：字面量、本插件读取它的文件、本应由哪个宿主文件定义。
-
-### v0.4.1
-
-- **右侧面板不再糊出一块常驻磨砂板** — dsh 0.1.7 不再自己绘制文件预览面板：容器变成了滑动/全屏视口，整场会话都以全宽挂载，折叠只是把 dock 用 `transform` + `visibility` 滑出去（从不 `display:none`）。于是这个容器上的背景加 backdrop-filter 在面板折叠时照样盖住右半屏——就是那块磨砂板。现在卡片只画宿主真正在画的元素（dock 的 tab host：`[data-dockkit-content]`、`[data-dockkit-empty]`），跟着宿主自己的开合与滑动过渡走；旧的容器选择器留在 `:has()` 守卫后面以兼容老宿主，backdrop-filter 只在 `[data-sidebar-right-open]` 时生效，折叠态绝不走滤镜。
-- **切换模型重新能切背景** — 0.1.7 的 `sessions.list` 快照不再发布 `current`，插件无法得知当前在屏的是哪个会话：拿不到会话 id → 没有 `modelSelection` 投影 → 模型文本为空 → 所有模型都退到规则 1。现在会话 id 先取宿主自己的 `uiSession.current.key`，老字段 `list.current` 与带 `retainedBy.mainView` 的行作为兜底，三跳都是可选的（`uiSession` 挂载晚也能解析）。换模型仍是即时的：它走的是该会话 `modelSelection` 投影的订阅，而不是轮询。
-- **菜单分组标题不再是白道** — 0.1.7 把菜单面拆成了两个 token：共享的 `MenuSurface` 材质画新的 `--dsw-menu-surface-fill`，其他浮层画 `--dsw-specific-menu`，而宿主把后者别名到前者。插件只重新发射了后者，于是模型选择菜单的面板还是宿主玻璃，吸顶的分组标题却变成了插件近乎不透明的调色板色。现在两个 token 由同一个表达式生成、读同一个插件变量，卡片滑块让它们一起变化，别名也不会再被打断。
-- **卡片滑块的标签改名** — 它同时管菜单与卡片，中文标签从「对话框中选项面板」改为「卡片与菜单面板」，英文从 `Cards & panels` 改为 `Cards & menus`。
-- **声明宿主抬到 `0.1.7-rc.2`** — 所有 `@deepseek-ai/dsh-*` peer 与 `engines.dsh` 现在都要求 0.1.7-rc.2 及以后。宿主的兼容性校验会用自身运行时版本比对（带 `includePrerelease`），因此更旧的宿主会按名字报出插件不兼容，而不是静默运行。代码里的版本兜底逻辑未改动。
-
-### v0.4.0
-
-- **取色改用「显示器看到的亮度」** — 亮暗带此前按 HSV 明度（max 通道）取平均，它把每个饱和像素都算成亮：纯蓝 `v = 1.0`，而 Rec.709 luma 只有 `0.072`。于是深色但饱和的壁纸被判进亮色带，在暗画面上配出一套浅色界面。现在改为平均 Rec.709 luma——与壁纸判定的同一套度量。
-- **选图即上色** — 选图或换图后自动为规则取主题色（全局开关，默认开）。它**只补空**：你手动选过的颜色（或刻意清空的）绝不会被覆盖；由于解码是异步的，回来时会再确认一次，期间你手选的色优先。
-- **匹配试跑卡取代「当前生效」卡片** — 原状态卡回答的是「现在生效什么」，且会在切换之间留旧值；试跑卡把同一个问题提前一步回答。输入任意模型名（未输入时自动跟随检测到的模型），即时显示会命中哪条规则，或提示走兜底。状态卡里那几句它表达不了的诊断——比如读到的只是**宿主默认**而非本会话模型、会话服务还没就绪——作为提示保留在卡片里，所以坏掉的链路依旧不会伪装成一次正常读取。
-- **配置** — 新增的持久化字段只有一个（`autoExtract`），落在共享 schema 一处，两半边的净化行为因此完全一致。
-
-### v0.3.3
-
-- **配置结构只声明一份，两半边共用** — node 半边（落盘前净化）与浏览器半边（UI 自己读同一份文件）此前各写一遍结构：键表在两侧合计 6 处、默认值两套，于是只在一边声明的字段会被另一边的净化静默丢掉——滑块当次有效、`writeConfig` 写下的配置里没有它、刷新即回默认。0.3.2 的 `blurs.rightbar` / `rightbarOpacity` 正是这么丢的。现在类型、键表、默认值与纯净化函数都收在 `src/schema.ts` 一处、两半边共同 import，两侧跑的是**同一份**净化代码，界面与磁盘的取值不可能再不一致。
-- **未知字段会被点名** — node 半边净化写入时，对任何「共用结构里未声明」的字段打一次警告（`ignoring unknown config field "blurs.produced" (declared in one half only?)`），这类不同步会出现在宿主日志里，而不是安静地吞掉一个设置项。0.3 之前的旧顶层字段除外（迁移会消费它们）。
-- **行为不变** — 默认值、夹取范围、迁移结果与落盘文件与此前逐字节一致，本次只消除重复声明。
-
-### v0.3.2
-
-- **「文件预览侧栏」卡片** — 点开文件后从右侧滑出的那一栏现在有自己的透明度与模糊度滑块。它此前的唯一表面就是 `--dsw-alias-bg-base`，也就是「主背景」滑块改写的那个令牌，所以它一直是主背景的第二份拷贝、无法单独调节。新卡片的透明度**默认跟随「主背景」**（首次拖动后才由自己接管），因此升级后外观零变化；模糊则叠加在主背景模糊之上。面板关闭时只是滑出屏幕，这张卡片不会带来任何副作用。
-- **宿主侧配置保留新字段** — `theme-config.json` 新增 `rightbarOpacity` 与 `blurs.rightbar`；缺字段（旧配置）一律按「跟随主背景」处理，导入旧配置文件同样如此。
-
-### v0.3.1
-
-- **文档与截图更新** — 截图换成当前的三选项卡界面：同一份配置在 DeepSeek 与 Kimi 下的两种外观，外加单条规则的编辑器。旧的七张图（还带着已删除的「色彩」选项卡与旧「背景」页）已删除，图片体积从 3.6 MB 降到 220 KB。
-- **npm 包内附截图** — `example_img/` 现在包含在发布包里，npm 页面上的 README 不再有裂图。
-- **素材致谢** — 示例壁纸素材来源于 bilibili [ZipZipPipe](https://space.bilibili.com/4168597)。
-
-### v0.3.0
-
-- **模型规则取代单张全局壁纸** — 背景改由有序规则列表驱动，每条规则用匹配串比对当前会话的模型名来选中（先命中者胜，规则 1 兜底）；匹配串会同时比对 provider、模型 id 与显示名三者。
-- **外观从全局下放到每条规则** — 壁纸、主题色、布局模式、取景、背景透明度与背景模糊都成为规则自身的属性，不同模型可以有完全不同的外观。
-- **设置选项卡重构** — 现在是 **「界面」**（全局）、**「模型背景」**（规则列表）与 **「配置」**（导入/导出）；**「色彩」** 选项卡随全局主题色一并删除，原 **「背景」** 选项卡改造成 **「模型背景」**。
-- **实时状态提示** — 「模型背景」页会显示当前模型及其命中的规则（例如「当前模型 deepseek-flash → 命中 · 规则 1」），检测不到时给出提示。
-- **导出格式 v3** — `dsh-background-by-model-theme.json` 现在包含全部规则配置**以及**每条规则的图片（base64 内联）。
-- **破坏性移除** — 视频背景、生成式背景（网格渐变 / Shader / 几何图案）与全局主题色均已移除。
-- **旧配置自动迁移** — 0.3.0 之前的配置会变成匹配串留空的规则 1 并继承旧外观，旧版遗留的视频文件会被清理。
-- **切换更顺，并带淡入淡出** — 壁纸改用 object URL 绘制，同一张图只解码一次，不再每次切换重新解码；规则切换现在是 320 ms 交叉淡入（新图在旧图上方淡入，底层始终保持不透明，中途不会发亮）。同时移除了拖动滑块时的低清壁纸降级：它会在每次壁纸变化时对整张大图额外解码并缩放，而且它换上的低清图下一帧就被重新覆盖、实际并未生效。
-- **修复“切换模型没反应”** — 三处叠加：① 旧实现读取的 `ctx.modelDirectories` 在插件上下文里不可见（它注册在 ui-model-selection 自己的作用域），于是悄悄退回了宿主全局默认模型；② 本插件的客户端 bundle **早于** `api-session-controller` 加载，`ctx.get('sessions')` 在 `apply()` 时通常还不存在，旧代码在这一步直接放弃、永不重试（这是“完全没反应”的直接原因）；③ 状态行拿一个全局默认值冒充了本会话模型。现在改读**本会话自己的持久化模型选择**（`ctx.sessions.binding(id).session.projections.faceOf('modelSelection')`，即模型选择器读的同一份值），以 400 ms 间隔等待 `sessions` 服务出现（最多 2 分钟），带 1.5 秒兜底轮询与会话切换重绑定；只拿到宿主默认值时标注 **宿主默认**，并且状态行会指出是哪一环失败（未挂载 / 无当前会话 / 无投影投影为空）。
-
-### v0.2.4
-
-- **修复 dsh 0.1.5 持久化失效** — 主题/背景图的 RPC 通道改为在插件自身 `webServer` 作用域内直接注册为 prefix 路由（保留 Host/Origin 鉴权围墙），不再经由 `connection.rpc.handle`（其 effect 绑定到 connection 服务上下文，导致部分 0.1.5 宿主挂载失败）。此前请求落到 SPA 兜底并返回 405、从未写入磁盘的设置，现可正常持久化（0.1.2 与 0.1.5 均已验证）。
-- **声明宿主版本兼容** — 新增 `engines.dsh: ">=0.1.2-rc.1"`，声明插件所支持的 DeepSeek Harness 宿主版本范围。
-- **修复深色徽章令牌（issue #9）** — 深色预设下 `*-tertiary` 徽章表面（轨迹工具/上下文徽章、连接胶囊、计划 chip）与背景色过于接近，浅色标签文字不可读；现已对齐原生深色 800/900 阶令牌，亮色文字落在正确深色徽章上。
-
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/chart?repos=HarmlessFunny/dsh-background-by-model&type=timeline&legend=bottom-right)](https://www.star-history.com/?repos=HarmlessFunny%2Fdsh-background-by-model&type=timeline&legend=bottom-right)

package/lib/client.js

@@ -731,6 +731,7 @@ window.__ModuleLoader__.load({
 			const l = (d) => Math.max(0, Math.min(1, lit + d));
 			const hsl = (hh, ss, ll) => `hsl(${Math.round(hh)},${Math.round(ss * 100)}%,${Math.round(ll * 100)}%)`;
 			const rgba = (hh, ss, ll, a) => `hsla(${Math.round(hh)},${Math.round(ss * 100)}%,${Math.round(ll * 100)}%,${a})`;
+			const onBrand = l(.2) > .6 ? "#000" : "#fff";
 			if (dark) {
 				const menuFill = hsl(h(0), s(0), l(.08));
 				return {
@@ -756,11 +757,11 @@ window.__ModuleLoader__.load({
 						"--dsw-alias-label-dimmed": "rgba(255,255,255,0.35)",
 						"--dsw-alias-label-quaternary": "rgba(255,255,255,0.25)",
 						"--dsw-alias-label-primary-dimmed": "rgba(255,255,255,0.92)",
-						"--dsw-alias-label-primary-foreground": hsl(0, 0, 1),
+						"--dsw-alias-label-primary-foreground": onBrand,
 						"--dsw-alias-label-primary-inverted": hsl(h(0), s(.08), Math.min(l(.06), .16)),
 						"--dsw-alias-label-primary-bluish": hsl(0, 0, 1),
 						"--dsw-alias-brand-primary": hsl(h(0), s(.1), Math.max(l(.2), .5)),
-						"--dsw-alias-brand-text": l(.2) > .6 ? "#000" : "#fff",
+						"--dsw-alias-brand-text": onBrand,
 						"--dsw-alias-button-primary-fill": hsl(h(0), s(.1), Math.max(l(.2), .5)),
 						"--dsw-alias-button-primary-hover": hsl(h(0), s(.1), Math.max(l(.28), .58)),
 						"--dsw-alias-button-primary-dimmed": hsl(h(0), s(0), l(.07)),
@@ -836,6 +837,7 @@ window.__ModuleLoader__.load({
 					"--dsw-alias-label-caption": "rgba(0,0,0,0.5)",
 					"--dsw-alias-label-dimmed": "rgba(0,0,0,0.35)",
 					"--dsw-alias-label-quaternary": "rgba(0,0,0,0.25)",
+					"--dsw-alias-label-primary-inverted": "#fff",
 					"--dsw-alias-brand-primary": hsl(h(0), s(.05), Math.min(l(-.18), .45)),
 					"--dsw-alias-brand-text": "#fff",
 					"--dsw-alias-button-primary-hover": hsl(h(0), s(.05), Math.min(l(-.12), .5)),
@@ -1071,7 +1073,7 @@ window.__ModuleLoader__.load({
 .dab-shell{display:grid;grid-template-columns:158px minmax(0,1fr);gap:26px;align-items:start;padding-bottom:8px;width:100%;max-width:980px;margin:0 auto}
 .dab-nav{position:sticky;top:0;display:flex;flex-direction:column;gap:18px}
 .dab-brand{display:flex;align-items:center;gap:10px;padding:2px 6px}
-.dab-brand-tile{width:30px;height:30px;flex:none;border-radius:9px;display:grid;place-items:center;color:var(--dsw-alias-brand-text);background:var(--dsw-alias-brand-primary);box-shadow:0 4px 14px -4px var(--dsw-alias-brand-primary)}
+.dab-brand-tile{width:30px;height:30px;flex:none;border-radius:9px;display:grid;place-items:center;color:var(--dsw-alias-label-primary-inverted);background:var(--dsw-alias-brand-primary);box-shadow:0 4px 14px -4px var(--dsw-alias-brand-primary)}
 .dab-brand-name{font-size:13px;font-weight:650;letter-spacing:.01em;line-height:1.25}
 .dab-brand-tag{font-size:9px;letter-spacing:.16em;font-weight:600;color:var(--dsw-alias-label-quaternary,var(--dsw-alias-label-tertiary));text-transform:uppercase}
 .dab-nav-list{position:relative;display:flex;flex-direction:column;gap:4px}
@@ -1131,11 +1133,23 @@ window.__ModuleLoader__.load({
 .dab-swatch-lg:hover{transform:scale(1.02)}
 
 /* ── buttons & chips ─────────────────────────────────────────────────────── */
+/* Text/icon painted ON --dsw-alias-brand-primary reads
+ * --dsw-alias-label-primary-inverted, never --dsw-alias-brand-text. The host's
+ * brand-primary is a CONTRAST ink, not a hue: black in its light scheme and
+ * near-white (#f9fafb) in its dark one, with brand-text equal to it in BOTH
+ * (and unused by the host's own CSS). Following the system theme therefore made
+ * every brand-filled control a filled box with an invisible label — a white
+ * primary button and a white active chip on a dark dialog. It was only ever
+ * readable while the plugin owned the palette and generated its own brand pair.
+ * label-primary-inverted is the host's answer for ink on a brand/contrast fill
+ * (its sidebar build badge paints exactly this pair) and it flips with the
+ * scheme: #fff on the light scheme's black fill, #353638 on the dark scheme's
+ * white one. */
 .dab-btn{display:inline-flex;align-items:center;justify-content:center;gap:7px;height:34px;padding:0 14px;border-radius:10px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-button-elevated-fill);color:var(--dsw-alias-label-primary);font-size:12.5px;font-weight:550;cursor:pointer;transition:transform .18s ease,box-shadow .18s ease,border-color .18s ease,opacity .18s ease,background .18s ease}
 .dab-btn:hover:not(:disabled){transform:translateY(-1px);box-shadow:0 5px 14px -6px rgba(0,0,0,.32)}
 .dab-btn:active:not(:disabled){transform:translateY(0) scale(.97);box-shadow:none}
 .dab-btn:disabled{opacity:.5;cursor:not-allowed}
-.dab-btn-primary{background:var(--dsw-alias-brand-primary);color:var(--dsw-alias-brand-text);border-color:transparent}
+.dab-btn-primary{background:var(--dsw-alias-brand-primary);color:var(--dsw-alias-label-primary-inverted);border-color:transparent}
 .dab-btn-danger{color:var(--dsw-alias-state-error-primary)}
 .dab-btn-ghost{background:transparent;border-color:transparent;color:var(--dsw-alias-label-secondary,var(--dsw-alias-label-tertiary))}
 .dab-btn-ghost:hover:not(:disabled){background:var(--dsw-alias-bg-layer-2);box-shadow:none}
@@ -1143,7 +1157,7 @@ window.__ModuleLoader__.load({
 .dab-chip-row{display:flex;flex-wrap:wrap;gap:8px}
 .dab-chip{height:30px;padding:0 14px;border-radius:99px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-secondary,var(--dsw-alias-label-tertiary));font-size:12px;cursor:pointer;display:inline-flex;align-items:center;gap:6px;transition:all .22s ease}
 .dab-chip:hover{border-color:var(--dsw-alias-brand-primary);color:var(--dsw-alias-label-primary)}
-.dab-chip.is-active{background:var(--dsw-alias-brand-primary);color:var(--dsw-alias-brand-text);border-color:transparent}
+.dab-chip.is-active{background:var(--dsw-alias-brand-primary);color:var(--dsw-alias-label-primary-inverted);border-color:transparent}
 
 /* ── sliders ─────────────────────────────────────────────────────────────── */
 .dab-slider-block{display:flex;flex-direction:column;gap:6px}
@@ -1174,7 +1188,7 @@ window.__ModuleLoader__.load({
 .dab-toggle{position:relative;width:42px;height:24px;flex:none;border-radius:99px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-2);cursor:pointer;padding:0;transition:background .28s ease,border-color .28s ease}
 .dab-toggle-knob{position:absolute;top:2.5px;left:2.5px;width:17px;height:17px;border-radius:50%;background:var(--dsw-alias-label-secondary,#999);box-shadow:0 1px 3px rgba(0,0,0,.3);transition:transform .28s cubic-bezier(.22,1,.36,1),background .28s ease}
 .dab-toggle.is-on{background:var(--dsw-alias-brand-primary);border-color:var(--dsw-alias-brand-primary)}
-.dab-toggle.is-on .dab-toggle-knob{transform:translateX(18px);background:#fff}
+.dab-toggle.is-on .dab-toggle-knob{transform:translateX(18px);background:var(--dsw-alias-label-primary-inverted)}
 
 /* ── background preview hero ─────────────────────────────────────────────── */
 .dab-hero{position:relative;border-radius:16px;overflow:hidden;aspect-ratio:16/9;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l2)}
@@ -1212,7 +1226,7 @@ window.__ModuleLoader__.load({
 .dab-overlay-hint{color:rgba(255,255,255,.62);font-size:12px}
 .dab-modal-card{animation:dab-zoom-in .3s cubic-bezier(.22,1,.36,1) both;max-width:calc(100vw - 40px);max-height:calc(100vh - 120px);overflow:auto}
 .dab-overlay .dab-btn{background:rgba(255,255,255,.94);color:#14161a;border-color:transparent}
-.dab-overlay .dab-btn-primary{background:var(--dsw-alias-brand-primary);color:var(--dsw-alias-brand-text)}
+.dab-overlay .dab-btn-primary{background:var(--dsw-alias-brand-primary);color:var(--dsw-alias-label-primary-inverted)}
 .dab-crash{display:flex;flex-direction:column;gap:10px;align-items:center;padding:28px 18px;border:1px solid var(--dsw-alias-border-l2);border-radius:16px}
 .dab-crash-title{font-size:15px;font-weight:650}
 .dab-crash-desc{font-size:12px;color:var(--dsw-alias-label-tertiary);text-align:center;line-height:1.5}