# 双壳适配说明

本插件要改外壳布局（壁纸纱层、观测台浮层、气泡重绘），所以必须**稳定地
找到外壳元素**。本机实测发现：**桌面端与网页端跑的是两套不同的壳**，类名哈希
完全不同。这份文档记录核实结果与应对策略，避免以后重新踩坑。

---

## 一、两套壳的实测差异

| 维度 | 桌面端（本机实际运行） | 网页端 |
|---|---|---|
| 版本 | `0.2.0-rc.2` | `0.1.0-rc.7` |
| 来源 | `app.asar` 内自带 | profile 的 `node_modules` |
| AppFrame 类名 | `BynINW_frame` / `_sidebarCol` / `_centerCol` / **`_rightbarCol`** | `pI_x6G_frame` / `_sidebarCol` / `_centerCol` / **`_detailsCol`** |
| 右栏折叠属性 | `data-rightbar-collapsed` | `data-details-collapsed` |
| `shell.overlay` | 有（`[data-shell-overlay]`） | 有 |
| `shell.leading` | 有渲染方（`[data-shell-leading]`，仅 macOS） | 只声明、**无渲染方** |
| `sidebar.brand.mark` / `conversation.hero.brand.mark` | **有渲染方**（带 `FishLogo` fallback） | 只声明、无渲染方 |
| 桌面专属包 | `dsh-client-ui-sidebar-browser` / `-right` / `-files` / `-terminal` / `-documentpreview` | 无 |
| `data-*` 语义锚点 | **456 个** | 139 个 |

### 怎么确认的

```powershell
# 1. 桌面端的壳在 app.asar 里
python -c "..."   # 解析 asar header，列出 /dsh/node_modules/@deepseek-ai/*

# 2. 关键判据：类名哈希
#    app.asar 内:     BynINW ✓   pI_x6G ✗   rightbarCol ✓   detailsCol ✗
#    node_modules 内: BynINW ✗   pI_x6G ✓   rightbarCol ✗   detailsCol ✓
```

**哈希由 CSS 内容决定**，所以同一份源码编译出的哈希是稳定的 —— `pI_x6G` 在
profile 的 `node_modules` 与 `app.asar` 之外的位置一致，但两套壳的 CSS 不同，
哈希就不同。这也意味着**不能把哈希写进代码**。

### 这个发现修正了什么

- 我原先记录的 `_rightbarCol` 在**桌面端有效**、在**网页端失效**；
- 参考实现 Mornye 用的 `detailsCol` 在**网页端有效**、在**桌面端失效**。

双方各错一半。所以右栏选择器必须两个都写。

---

## 二、三层定位策略

按可靠性从高到低，三层同时用，互为兜底。

### 第 1 层：语义 `data-*` 锚点（最稳）

桌面壳暴露 **456 个** `data-*`，都是外壳给 React 组件打的语义标记，跨版本稳定：

| 锚点 | 用途 |
|---|---|
| `[data-rightbar-col]` | 右栏列 |
| `[data-shell-overlay]` | 浮动层（观测台浮层挂这里） |
| `[data-chat-flow-kind]` | 聊天行类型（`user` / `assistant-step` / `tool-call` / `turn-tail` / `turn-error`） |
| `[data-composer-card]` / `[data-composer-seat]` | 输入框卡片与座位 |
| `[data-composer-stats]` | 统计行（轮次/步数/缓存命中） |
| `[data-sidebar-collapsed]` | 侧栏折叠 |
| `[data-streaming="true"]` / `[data-state="running"]` | 运行中标记 |
| `[data-window-drag]` | 窗口拖拽区 |

**优先用这些**，不碰类名。

### 第 2 层：`data-plugin-css` 反查哈希（次稳）

外壳为每个 CSS Module 插入一个样式标签：

```html
<style data-plugin-css="@deepseek-ai/dsh-client-ui-layout/AppFrame.module.css"
       data-plugin="@deepseek-ai/dsh-client-ui-layout">
  .BynINW_frame{...} .BynINW_sidebarCol{...} ...
</style>
```

标签的 `textContent` 里就是该模块**当前生效**的真实类名。从中正则提取即可，
不用猜哈希。这一招学自 [Mornye-Observation-Skin](https://github.com/is-limo/Mornye-Observation-Skin)。

```js
const tag = document.querySelector('style[data-plugin-css$="/AppFrame.module.css"]')
const text = tag.textContent.replace(/\\([0-9a-f]{1,6})\s?|\\(.)/gi, (_, hex, ch) =>
  hex ? String.fromCodePoint(Math.min(parseInt(hex, 16), 0x10ffff)) : ch)  // 反转义
const cls = text.match(/\.([\w-]+_sidebarCol)(?=[\s{.:\[>,#])/)?.[1]   // -> "BynINW_sidebarCol"
```

**两个必须处理的坑**：

1. **转义类名** —— 以数字开头的类名在 CSS 里写作 `\37 yHdaG_row`，必须先反转义
   （`QueueDock.module.css` 就有）。不处理会匹配失败。
2. **标签可能还不存在** —— 插件可能先于外壳渲染。此时返回 `null`，下次再试，
   **不要抛错**。

### 第 3 层：`[class*="_后缀"]` 兜底

语义后缀（`_sidebarCol`）比哈希前缀稳定，两套壳都命中。样式表里用这一条，
保证**首帧**（JS 还没跑）就有正确样式。右栏两个后缀都要写：

```css
[class*="_rightbarCol"],   /* 桌面端 */
[class*="_detailsCol"]     /* 网页端 */
```

---

## 三、打标：把定位结果固化下来

定位到元素后，客户端给它们打上**本插件自己的** `data-zf-*`：

| 属性 | 打在 |
|---|---|
| `data-zf-frame` | AppFrame 外框 |
| `data-zf-sidebar` / `data-zf-center` / `data-zf-rightbar` | 三列 |
| `data-zf-rail="on"\|"off"` | body（观测台浮层显隐） |
| `data-zf-avatar` | body（头像气泡开关） |
| `data-zf-session-state` | body（会话状态，驱动状态点颜色） |

CSS 优先认这些属性。好处：**外壳换版本、换哈希时，只要定位逻辑能自愈，
样式表一个字都不用改。**

### 生命周期要点

- **幂等**：已有该属性就跳过（`mark()` 返回 `false`）。
- **可还原**：`tagged: Map<node, Set<attr>>` 记录「谁被打了什么」，卸载时逐条
  移除。不做记录就只能 `querySelectorAll` 盲删，会误伤别人打的属性。
- **清理断开节点**：React 卸载子树后，打标会跟着元素一起消失，但 `Map` 里的
  引用还在 —— 会泄漏。所以每次 `refresh()` 先 `prune()` 掉 `!isConnected` 的。

### 观察器要收窄

```js
observer.observe(document.documentElement, {
  subtree: true, childList: true, attributes: true,
  attributeFilter: [
    'data-rightbar-collapsed', 'data-details-collapsed',
    'data-sidebar-collapsed', 'data-ds-dark-theme',
    'data-chat-flow-kind', 'data-streaming', 'data-state', 'hidden'
  ]
})
```

**必须给 `attributeFilter`**：聊天区在流式输出时每帧都在变 DOM，不收窄的话
观察器每帧触发一次，白白烧 CPU。

---

## 四、顶栏已移除（历史教训：定位基准要选确定的）

曾经的顶栏设计（现**已整体删除**，原因见下）只留下两条仍然有效的结论。

**背景**：Windows 桌面壳给 frame 加了标题栏带：

```css
[data-windows-titlebar] .BynINW_frame{
  padding-top: var(--dsh-windows-titlebar-height);   /* 40px */
}
[data-windows-titlebar] .BynINW_frame::before{
  content:""; height: var(--dsh-windows-titlebar-height);
  background: var(--dsw-specific-sidebar-fill);
  -webkit-app-region: drag;                          /* 窗口拖拽区 */
}
```

**为什么删掉顶栏**：用户实测反馈两条 —— ① 它 `position:fixed` 浮在中栏上方，
**压住了会话标题那一行**（截图可见标题被切掉半边）；② 它显示的信息全是冗余
（头像在侧栏品牌位与助手消息旁都有，预设与会话状态在观测台里都有）。
右栏观测台因此改为**顶格**显示（`top:0`，仅 Windows 下让开 40px 标题栏）。

### 留下的有效结论

1. **不要给顶栏类控件放按钮** —— Windows 标题栏那条 40px 带子被系统占满
   （左 0–40px 窗口图标、48px 起「应用/编辑」菜单 Shadow DOM `z-index:1100`、
   右侧 ~138px 窗口按钮）。任何浮在那里的东西都会与原生 chrome 抢位置。
2. **定位基准选「确定的坐标系」**：`shell.overlay` 是 AppFrame（`display:grid`）
   的子元素，三个列与它都**没写 `grid-area`**（依赖自动放置），且 frame 在
   Windows 下有 `padding-top`。观测台浮层因此用 `position:fixed` 相对**视口**
   定位，Windows 下自己加 `--dsh-windows-titlebar-height` —— 用一点手工补偿
   换来不随壳布局变化的确定基准。
   > 教训：位置问题要用 `getBoundingClientRect` 实测（`/diag` 的 `geom` 字段），
   > 不要靠截图量像素反推 —— 我曾据此推断「overlay 被挤到第二行」，实测
   > overlay 就在 `{0,0}`，推断是错的。

---

## 五、观测台进官方右栏的两种方式（为什么不用 `openRightbar` 抢轨道）

桌面壳的 `ctx.layout` 服务提供：

```
selectPanel(panelId) / toggleSidebar() / openRightbar(track, fullscreen) / closeRightbar()
```

`openRightbar` 打开的是**原生右栏**（`rightbar` 插槽），由文件预览、终端、
文档预览等插件共用。**整块抢走这个 `single` 插槽**会与它们直接冲突。

本插件的分层策略（两阶段实现后的现状）：

1. **首选：注册自己的标签页**（`sidebarRightTabs` 两阶段注册 + `openTab`）
   —— 走官方 `sidebar.right.pane.tab` 扩展席位（`priority:'extension'` 不抢
   builtin），观测台成为原生右栏里**并列的一个 tab**：不占额外轨道、随原生
   一起开合、可拖拽调宽。打开时机严格「仅在面板已展开时」，不代用户展开。
2. **兜底：`shell.overlay` 浮层** —— 右栏收起时贴右侧显示；官方服务缺失
   （Web 端无 `dsh-client-ui-sidebar-right`）时自动接管。
3. 两路径由 `railOwner()` **单点裁决**，判定依据是 `tabMounted`（真的挂着
   内容）而非注册状态 —— 注册 ≠ 打开，这是实测踩过的坑。
4. 视口 < 1180px 时浮层隐藏（同 Mornye 断点），避免挤压中栏。

---

## 六、`shell.leading` 是死插槽（网页端）

`shell.leading` 的用途是「macOS 上侧栏收起时，在左上角放重新展开控件」。桌面壳
渲染它，但**仅在 `html[data-platform='darwin']` 且侧栏收起时**：

```js
const leadingMounted = darwin && sidebarCollapsed
```

网页端更是**只声明、无渲染方** —— 注册进去等于石沉大海。所以本插件不用它。

同理，网页端的 `sidebar.brand.mark` / `conversation.hero.brand.mark` 也只声明不
渲染。注册了在网页端不会有副作用（不会报错），在桌面端才显示 —— 这正是我们
要的，所以不需要按平台分支。

---

## 七、宿主模块缓存（改代码不生效的原因）

**这是最容易误判为「代码写错了」的坑。**

桌面端是**两个进程**：Electron 主进程 `spawn` 一个独立的 Node 宿主进程。插件
的 Host 半边跑在那个 Node 进程里。

Node 的 ESM 模块按**解析后的路径**缓存。`plugin_manager` 的
`set_plugin(enabled=false)` → `enabled=true` 只会：

- 卸载插件（跑 `ctx.effect` 的清理函数）；
- 重新 `apply()` —— 用的是**已经 import 过的模块对象**。

它**不会**重新 `import('./index.js')` 或 `./src/palette.js`。所以：

| 改了什么 | disable/enable 够不够 |
|---|---|
| `client.js` | ✅ 够（浏览器半边走 mtime/size 派生的 revision，HMR 会重载） |
| `index.js` / `src/*.js` | ❌ **必须重启 DSH** |

### 怎么确认跑的是哪一版

`tools/deploy.ps1` 会在部署时把 `index.js` 里的 `'__ZF_BUILD__'` 占位符替换成
时间戳。探活即可判断：

```powershell
Invoke-WebRequest http://127.0.0.1:19387/api/zhuang-fangyi/themes | % Content
# {"build":"20261005-123748", ...}
```

- `build` 是刚部署的时间戳 → 跑的是新代码；
- `build` 是旧时间戳或**字段缺失** → 宿主还在跑旧模块，需要重启 DSH。

这个标记就是为了把「代码写错了」和「进程没重载」区分开 —— 实测时我一度以为
配色改动没生效，实际是宿主缓存。

---

## 八、桌面端 `tapIndex` 不执行（壁纸/观测台/气泡重绘全部失效的根因）

**这是最隐蔽、代价最大的一个坑，值得单独一节。**

宿主用 `tapIndex` 往 `index.html` 的 `</head>` 前注入首帧样式：

```js
ctx.inject(['webServer'], scoped => {
  scoped.effect(() => server.tapIndex(tap), 'zhuang-fangyi: first-paint tokens')
})
```

它在 **Web 端有效**，但在**桌面端从来不会执行**。原因在 `app.asar` 的
`dsh-app://` 协议处理器：

```js
protocol.handle(SCHEME, (request) => {
  const url = new URL(request.url)
  if (url.hostname === "app") {
    if (url.pathname === "/" || url.pathname === "/index.html" || ...)
      return serveWebDocument(request,
        join(resources.dsh, "node_modules", "@deepseek-ai", "dsh-web-frontend", "dist"))
    ...
  }
})

function serveWebDocument(request, root) {
  body = await readFile(target)                    // ← 直接从磁盘读
  const content = body.toString().replace("<head>",
    "<head><script>globalThis.__DSH_BOOT_READY__ = Promise.withResolvers()</script>")
  // ↑ 只注入这一个脚本，完全不经过 Host 的 HTTP 服务
  return new Response(content, ...)
}
```

也就是说，桌面渲染进程**直接从磁盘读 `index.html`**，绕过了 Host 的
webServer —— 所以 `tapIndex` 注册的回调根本没机会跑。

### 症状

`structureStyle()` / `structureCss()` 的全部 CSS（壁纸、纱层、观测台、气泡重绘）
**一个字都不会出现**。但 token 是由浏览器半边 `overrideTokens` 独立生效的，所以看起来
「**只改了配色**」—— 这正是最初那条反馈的真正原因。不是壁纸被纱遮住了，是
壁纸的 CSS 压根不存在。

### 修法

两条路都走，**同一份 CSS、两种形态**：

| 路径 | 适用 | 形态 | 机制 |
|---|---|---|---|
| `bootStyle()` → `tapIndex` | Web 端 | `structureStyle()`（**带 `<style>` 标签**） | 服务端注入 HTML，首帧即生效（无闪烁） |
| `/api/zhuang-fangyi/style.css` → 客户端 `ensureStyle()` | **两端都走** | `structureCss()`（**纯 CSS**） | 客户端 `fetch` 后自建 `<style id="zf-style">` 插进 head |

桌面端只有第二条路，所以它是**桌面端唯一的 CSS 来源**。Web 端两条都走：
`tapIndex` 保证首帧不闪，客户端那条是幂等兜底。

### ⚠️ 为什么两条路的形态必须分开（实测踩过，代价极大）

客户端插样式表用的是：

```js
el.textContent = css      // el 是客户端自建的 <style id="zf-style">
```

如果 `/style.css` 发出去的内容**自带 `<style id="zf-boot-css">` 与 `</style>`**
（即直接复用 `structureStyle()` 的产物），浏览器会把 `<style id=...>` 当成
**CSS 文本**解析 —— 非法起始 token → 进入错误恢复 → **紧随其后的 `html{}`
规则块被整块丢弃**。

症状极具迷惑性：

| 观察 | 原因 |
|---|---|
| 纱色 `--zf-veil` 正常 | 它是 JS **行内**写的字面 rgba，不依赖样式表 |
| `--zf-art-src` 计算值为空 | 行内写的是 `var(--zf-art-<id>)`，而被引用变量定义在**被丢掉的 `html{}` 块**里 → 整条属性失效 |
| `.zf-rail` 等规则正常 | 它们在文件后半段，错误恢复后能照常解析 |
| 结论 | **壁纸怎么都出不来**，而观测台样式看着完全正常 |

所以：`structureCss()` 是**唯一**的 CSS 来源，`structureStyle()` 只是给它套上
标签供 `tapIndex` 用。有专门的回归测试断言「`/style.css` 的形态必须是纯 CSS」。

### ⚠️ 更正：`tapIndex` 不是唯一的口子 —— `webserver/index-inject` 才是给插件用的

我一度据此推断「桌面端改不了首帧、插件碰不到开机卡片」，**这个结论是错的**。
参考实现 [dsh-550c-boot](https://github.com/yannicksong0106/dsh-550c-boot) 证明
官方另留了一条**给插件的公开注入通道**：

```js
ctx.on('webserver/index-inject', table => {
  table.push({ kind: 'style',  text: '...' })
  table.push({ kind: 'script', placement: 'head', text: '...' })
})
```

行类型（源码实测）：`global` / `style` / `script` / `script-src` / `html` / `meta`。
两个载体都会应用这张表，且**都在内核建开机卡片之前**：

| 载体 | 应用方式 |
|---|---|
| Web | 渲染进 `index.html` 的 `<head>`，早于 shell 的 module script |
| 桌面 | 在 settle `__DSH_BOOT_READY__` **之前逐行应用**：`script` 行走 `createElement` 所以会执行 |

**三者的区别要分清**：

| 通道 | 桌面端是否执行 | 时机 |
|---|---|---|
| `tapIndex` | ❌ 从不执行（`dsh-app://` 直读磁盘） | — |
| `webserver/index-inject` | ✅ 执行（载体逐行应用） | **内核建卡片之前** |
| 客户端插件（`shell.overlay`） | ✅ | 卡片移除之后（实测晚 271ms） |

实测时序（参考项目用 CDP 从导航开始计时）：开机卡片 67ms 出现 → 客户端遮罩
338ms 挂上 → 卡片 517ms 移除。**中间 271ms 是客户端怎么调 z-index 都盖不住的** ——
所以「盖住官方开机卡片」这件事**只能**走 `index-inject`。

本插件因此用它注入首帧（`#zf-first-frame` 纯色遮罩 + 把 `[data-dsh-boot]` 按成
`visibility:hidden`），并由客户端在立绘挂载时调 `window.__zfFirstFrame.end()`
**同一帧交接**。首帧脚本自带自保撤离（卡片消失 / 12s 超时），客户端出问题也不会挡住界面。

### 连带教训

1. **不要假设「宿主能改 HTML」就等于「两端都能」** —— 桌面端有独立的资源加载
   路径（`dsh-app://` 协议 + `app.asar`）。
   **但也别因此推断「插件改不了」** —— 先找官方有没有留通道
   （`webserver/index-inject` 就是），再看参考实现怎么做。
   我在这条上误判过一次，代价是白做了一版「等 boot 退场再接住」的方案。
2. **样式表加载失败不能阻断启动**：`ensureStyle()` 的失败只 `console.warn`，
   配色仍由 token 层生效（已有测试覆盖）。
3. **客户端不要重复实现 CSS**：走 `/style.css` 取宿主同一份产物，避免两处分叉。
4. **同源产物给不同消费者时，形态要分开**：`textContent` 要纯 CSS，
   注入 HTML 要带标签 —— 别指望一个字符串同时满足两边。

---

## 九、纱层之上还有一层不透明底（右栏 dockkit pane）

**症状**（用户反馈）：「开始页背景还是黑色的」「tab 条背景也还是黑色的」。

**误判方向**：先怀疑纱没写上去 / 变量没生效。实际是**纱在下面，上面还压着
一层不透明底** —— 中栏透出壁纸了，右栏整片仍黑。

**壳源码实测**（`dsh-web-frontend/dist/assets/index-*.css`，dockkit 模块）：

```css
._tabHost_6nhg2_162:not(._float_6nhg2_156),
._emptyTabHost_6nhg2_143{ background: var(--dsw-alias-bg-base) }
```

而 JS 里 **tabHost 就是 pane 本身**：

```js
className: ue(ve.tabHost, x ? ve.float : ve.pane)
children : [ tabHostHeader(含 tab 条), tabHostBody(含页面内容) ]
```

被反馈的两个元素**自己都没有 `background`**（壳 CSS 实测）：
`.unKlVG_guide`（开始页容器）与 `._tabStrip_6nhg2_237`（tab 条）的规则里
都没有背景声明 —— 黑色 100% 来自 pane 的 `bg-base`，它盖住了我们画在
`rightbarCol` 上的纱。

**修法**：壁纸开启时让 docked pane 透明，露出下面**已有**的那层纱 ——
用与中栏同一个 `--zf-veil`，所以可见度天然一致、滑杆一起跟随：

```css
body[data-zf-wallpaper] [data-dockkit-pane],      /* 语义锚点：docked pane */
body[data-zf-wallpaper] [data-dockkit-empty],     /* 空 pane */
body[data-zf-wallpaper] [class*="_tabHost"]:not([class*="_float"]),  /* 后缀兜底 */
body[data-zf-wallpaper] [class*="_emptyTabHost"]{ background:transparent !important }
```

这里**只写 `transparent`，不再涂一遍纱** —— 纱已经在 `rightbarCol` 上，
涂两次会比中栏深一档。

**三处刻意的「不碰」**：

- 浮窗 pane（`data-dockkit-float`）保持官方 `bg-layer-2` 不透明底 ——
  弹出窗口需要实体感（官方规则里那个 `:not(._float_)` 就是这个意思）；
- 官方拖拽停靠时的 `_dockScrim_`（`bg-base` 72% + blur）不动；
- active tab 的选中色 chip（`--dsw-alias-markdown-tag`）保留 —— 它是状态指示，
  透明掉就看不出当前在哪一页；
- 开始页的入口卡片（`.unKlVG_entry`，官方 `bg-layer-1`）保留不透明 ——
  它是按钮，压不住字就不好用了。

**锚点为什么用语义属性**：`data-dockkit-pane` 只在 pane **有标签页**时才渲染
（源码里是 `!x && w ? a.id : undefined`），所以必须再补一层类名后缀兜底；
空 pane 的属性是 `data-dockkit-empty`（打在 `_emptyTabHost_` 上）。

### 同一类的第二个面：左栏（会话列表）

用户接着贴了左栏整棵 DOM 说「这个地方也变成透明的」。壳源码实测：

```css
.BynINW_sidebarCol{ background:var(--dsw-specific-sidebar-fill); … }
._2H3hWW_root    { background:var(--dsw-specific-sidebar-fill); … }  ← 内层又铺一层
[data-platform=darwin] ._2H3hWW_root{ background:0 0 }               ← 只有 macOS 透明
```

列与内层是**两层同色不透明底**；macOS 那条 `0 0` 恰好证明结构是「列铺面、
内层透明」，官方只是没给 Windows 写后一半。

修法与右栏不同，**更省事也更稳**：不去点名内层组件，而是**在列上把
`--dsw-specific-sidebar-fill` 置为透明**（自定义属性按最近祖先解析）：

```css
body[data-zf-wallpaper] [class*="_sidebarCol"]{
  --dsw-specific-sidebar-fill:transparent !important;   /* 内层组件的底跟着透明 */
  background:var(--zf-veil-sidebar) !important;         /* 列上仍是那层纱 */
}
```

| 做法 | 依赖类名哈希 | 首帧 | 内层再多包一层 |
|---|---|---|---|
| 点名内层组件 | 要 —— 而它的本地名是 `root`，写 `[class*="_root"]` 会误伤一大片 | 要等客户端打标 | 漏 |
| **在列上改 token** | **不要** | **纯 CSS，首帧生效** | **一起透明** |

⚠️ 加 `!important`：外壳 presenter 会把 token 写成**行内样式**，而 token 的作用域
在这里是「列及其子树」，不是全局 —— Windows 原生标题栏那条探针读的是同一个
token，它是 `body` 的子元素，**两者互不影响**。

顺带一处：会话列表底部的渐隐官方是「透明 → `--dsw-specific-sidebar-fill`」，
token 置透明后这条会整条失效（透明渐到透明），列表底部变成硬切 —— 所以单独把
它改成渐到同一层纱色。

### 同一类的第三个面：输入区那条「座位」渐变

用户贴了输入区整棵 DOM 说「这里的黑色渐变背景也给去掉」。壳源码实测
（`@deepseek-ai/dsh-client-ui-conversation/lib/client.js` 里内联的 CSS）：

```css
.Dc7zOa_composerSeat{ z-index:7; position:sticky; bottom:0;
  background: linear-gradient(180deg,
    color-mix(in srgb, var(--dsw-alias-bg-base) 0%, transparent) 0px,
    var(--dsw-alias-bg-base) 36px) }
/* 实际生效的是带状态祖先的两条： */
.Dc7zOa_root[data-phase=active] .Dc7zOa_composerSeat,
.Dc7zOa_embeddedBody[data-content-phase=active] .Dc7zOa_composerSeat{ … 同上 … }
```

官方用意是好的：输入条坐在一个 sticky/absolute 的「座位」上，消息从它底下滚过去，
渐到不透明底色能让文字消失在输入区上方。**但壁纸模式下 `bg-base` 是主题的不透明
底色** —— 于是那里成了一条黑色渐变带。

处理同上：壁纸开启时把它置透明（`[class*="_composerSeat"]`，本地名是该模块专有的，
比哈希稳；两条官方规则都带 `!important`，我们靠选择器权重 + `!important` 压过）。
代价如实记下：座位不再遮滚动中的文字，消息会显示到输入卡上沿 —— 卡片本身不透明，
所以只在它上方那圈留白里看得到。

> 这类问题的**共同信号**：某个区域「和别处不一样地黑」。三个面（右栏 pane、
> 左栏内层、输入区座位）都是同一种病 —— 壳在纱之上又铺了一层不透明底，而它的
> 用意（层次、渐隐、可读性）在**不透明配色**下成立，在壁纸下不成立。

### 连带教训

**「让某块透明」= 找出所有压在它上面的不透明层，而不是给最外层加 alpha。**
多层叠加时 alpha 会连乘（第八节那个「两层各 0.83 只剩 0.69」是同一个坑的
另一种形态）；正确做法是**只保留一层纱**，把它上面每一个不透明底逐个摘掉。

判断依据不能靠猜：要从壳源码里读出**谁声明了 `background`**。这次的路径是
`rg` 直接扫 `app.asar` 里的 CSS —— 桌面壳是打包的 asar，里面的文本**未压缩**，
`rg -a -o '\.[^{}]*_6nhg2_[^{}]*\{[^}]*\}' app.asar` 就能把整个 dockkit 模块的
规则一条不落捞出来。这比在浏览器里逐层 DV 快得多，也准得多。

---

## 十、透明度只有一个来源：观测栏不再自己算一档

用户：「观测栏的透明度跟随全局，不要单独设置」。

先把事实摆清 —— **设置里本来就没有**观测栏的透明度（只有 `rail` 开关与
`railWidth` 宽度）。问题在实现层：观测栏走自己的一套 —— 私有变量
`--zf-rail-veil` + 私有底色 `--dsw-alias-bg-layer-1` + 私有兜底 62%。

它的**数值**确实来自同一个滑杆（`keep = 1 - 背景不透明度`），但它是在中栏那层纱
**之上又涂一层**：

| 滑杆 | 中栏那层纱 | 观测栏再叠一层 | 实际观感 |
|---|---|---|---|
| 14%（默认） | 0.86 | 0.86 | **0.98** —— 几乎全实 |
| 90% | 0.10 | 0.10 | **约 0.19** —— 仍比别处实 |

**数值同源 ≠ 观感同源。** 修法：观测栏背景**透明**，什么都不涂 —— 露出的就是
它下面中栏那层纱，所见即全局那一档，结构上不可能再不一致。分隔交给 `border-left`。

`backdrop-filter` 保留：它**不改变透明度**（纱是一层纯色，模糊它还是那个色），
只把壁纸细节糊掉，是高档位下小字号的可读性保险。私有变量与 62% 兜底一并删除
（CSS 一处、客户端两处写入 + 一处清理，全都删干净，并有断言锁住「一个字都不剩」）。

### 连带教训

**「跟随全局」的判据不是「引用了同一个变量」，而是「最终画出来的那一层是谁」。**
引用同一个 `keep` 只说明数值同源；只要它还在别人已经涂过的层上再涂一次，
观感就一定不同 —— 这又是 alpha 连乘的同一个坑（第八、九节）。

写测试时也要跟着换判据：原先「观测台与侧栏在每一档都同步」是拿**两个 alpha 相等**
来证的，现在观测栏恒为 0，等号不再成立 —— 正确的判据是「观测栏自身 alpha 恒 0，
透过去看到的那层等于全局那一档」。断言不改，测试就会变成**用旧契约给新实现判分**。

---

## 十一、变量「声明在哪一层」决定优先级（shiki token 色踩过）

要让某个 `--dsw-*` / `--shiki-*` 变量在我们的主题里生效，**写在哪一层**是有讲究的
—— 自定义属性按**最近祖先**解析，不看选择器权重的绝对值。

外壳实测（两层各一套，明暗分开）：

```css
:root{ --shiki-token-keyword:#d6336c; --shiki-token-string:#2f9e44; … }      /* 亮色 */
body[data-ds-dark-theme]{ --shiki-token-keyword:#faa2c1; --shiki-token-string:#69db7c; … }  /* 暗色 */
```

于是「写 `html` 行内」这种看起来最稳的做法，在暗色下**会被 `body` 那条压回去**：

| 写在哪 | 亮色 | 暗色 |
|---|---|---|
| `html` 行内 | ✓ 生效 | ✗ 被 `body[data-ds-dark-theme]` 压回外壳默认色 |
| **`body` 行内** | ✓ 生效 | ✓ 生效（行内样式优先于普通样式表规则） |

**判据**：外壳在**哪一层**声明过这组变量，我们就写在**同一层**（或更近的祖先）上。
同类还有侧栏的 `--dsw-specific-sidebar-fill`（在 `body` 上与列上各有一份，我们
在**列**上改，作用域正好只覆盖侧栏子树）。

两种写法都在真实引擎里量过：写 body → `rgb(18, 52, 86)`（我们的值）；
写 html → `rgb(250, 162, 193)`（外壳暗色粉）。用例 73 有这两条实测断言。

### 第二个实例：阅读宽度（B7）

外壳把 `--dsh-chat-content-width` 声明在 `[data-conversation-content]` **自己**身上，
而且它自己还会往那个元素写行内 `--dsh-chat-user-width`：

```css
.Dc7zOa_body{ --dsh-chat-content-width:
  var(--dsh-chat-user-width, clamp(680px, calc(列宽 * .64), 920px)) }
```

于是规则更狠一层：**元素自己的声明赢过任何继承值** —— 写 `html` / `body` 完全
无效，只能写在那个元素本身上（客户端 `el.style.setProperty(…, 'important')`）。
「标准」档 = 移除声明，把外壳自己的宽度手柄一起还回去。

顺带一条实测结论：**行内声明即使不带 `!important` 也已经赢过外壳那条样式表规则**
（行内 > 作者样式表）。我们仍然加 `!important`，是防外壳哪天把它也改成行内写。
这类「预期与实测不符」的地方，用例 74 里都按实测值断言（第一版按想象写了
「不加 important 会被压回」，跑出来才知道是错的）。

---

## 十二、读数的权威来源：为什么不再只读 DOM（C11）

观测台那六项读数原本全靠解析 DOM 文字（`readStats` / `readSessionState`）。那套东西
在本次迭代里连续栽过三次，而且**每次都是同一个病**：

| 症状 | 真实原因 |
|---|---|
| 右栏「开始」页/tab 条整片黑 | 读错了层（壳在纱之上又铺了一层） |
| 左栏不跟随壁纸 | 同上 |
| 输入区一条黑色渐变带 | 同上 |

DOM 抓取的命就是这样：外壳一升级、一加层，读数就悄悄失效（**不报错，只是数字不对**）。
所以改成订阅宿主事件 —— 它们是 `emit` 模式（观察用、不参与决策链）、契约稳定，
而且**权威**（外壳自己也是从这些事件算出来的）。

```
宿主事件 → src/sessionState.js（纯 reducer，白名单折叠）
        → GET /api/zhuang-fangyi/stream?session=<id>（SSE）
        → 客户端 EventSource → 新鲜就用；否则逐字段/整条回退 DOM
```

### 传输为什么是 SSE（而不是 WebSocket）

`webServer.register` 的 handler 拿到的是 **Node 原生** `req` / `res`
（`IncomingMessage` / `ServerResponse`，实测契约），所以直接 `res.write()` 就能推流 ——
不需要 `registerUpgrade`（WebSocket），也**不需要新权限**（复用 `web:http-route`，
清单里一个字都不用改，自检也不需要豁免）。

响应头里 `cache-control: no-transform` + `x-accel-buffering: no` 是给中间层看的：
不这么写，某些代理会攒够一批才吐，表现就像「SSE 不动」。

### 三条设计取舍

1. **字段级回退**，而不是「要么全宿主、要么全 DOM」：`cacheHit` / `rate` / `context.used`
   宿主可能给不出（provider 没报缓存、上下文窗口未知）—— 那几格用 DOM 的，其余照旧用
   宿主的。两条路各自最强的地方都用上，且降级是逐格的、不是断崖式的。
2. **新鲜度阈值 10s**：超时没帧就当作不可用（回退 DOM），**不显示陈旧数字** ——
   界面上一半新一半旧比全旧更糟。
3. **一次快照绝不建 tracker**：`?once=1` 走独立的折叠路径。第一版复用了
   `trackerFor()`，于是每次快照都留下一个永不回收的 tracker，之后每条
   `session/event` 都往里折叠 —— 正是「空闲零成本」要避免的。**这条是被测试抓到的**
   （`once=1 不留下 tracker` 断言），不是靠 review。

### 隐私边界是断言级的

事件的载荷里带消息正文、工具参数、流式文本，而 `buildPayload` **逐字段写出**、
绝不 `...spread` 事件对象。用例 76 里有一条断言直接盯**字段集**：

```js
Object.keys(payload).join(',') === 'v,session,live,rev,state,turns,steps,usage,' +
  'tokensTotal,cacheHit,rate,context,model,turnStartedAt,source'
```

想加一个会泄漏内容的字段，这条就会红 —— 比「记得不要泄漏」可靠。

---

## 十三、明暗切换为什么要走完整 `applySettings`（C13）

给「浅色用青、深色用墨青金」时发现的一个**既有半生效状态**：

```js
// 改之前 —— 只同步了壁纸
ctx.on('theme/change', () => {
  syncSchemeWallpaper(state.settings, state.themeRoles, theme, state.wallpaperMeta)
})
```

`syncSchemeWallpaper` 只管壁纸与代码高亮 token；**配色 token 层、材质深度
（`data-zf-depth`）、壁纸推荐标记都不会更新**。所以外壳切明暗时，壁纸换了、
配色没换 —— 在没有分档预设时这只是「材质没跟着换」，一旦启用分档就变成
「预设根本没换」，问题才暴露出来。

修法：分档启用时走完整的 `applySettings()`。

### 两个必须处理的结构性约束

**① 跟随系统时，单一预设表达不了「浅色 A / 深色 B」。**
`ctx.theme.overrideTokens` 只接受 `{token: {light, dark}}` —— 它没有「按明暗选
不同来源」的概念。所以只能在**值**这一层拼：

```js
out[name] = { light: lightPresetOv[name].light, dark: darkPresetOv[name].dark }
```

固定明暗那条路反而简单：`setTheme('<preset>-<scheme>')`，预设 id 本来就按
`<preset>-<scheme>` 注册好了，不需要新增注册项。

**② `setTheme` 会再 emit `theme/change` → 递归。**
`applySettings` 在固定明暗下调 `theme.setTheme(id)`，外壳的 setTheme 会 emit
`theme/change`，于是又进 `applySettings`。闸门必须**在调用之前**置位：

```js
if (state.applying) return
state.applying = true
try { applySettingsInner(s) } finally { state.applying = false }
```

第一版把置位写在**事件回调**里 —— 那样只是「回调里再进不来」，
`applySettings` 自身照样被重入。这类「看着像有闸门」的写法，只有把递归路径
真正走一遍才会露馅。

### 「不分档」路径必须逐字节不变

默认 `presetLight` / `presetDark` 都是 `null`（跟随主预设），所以：

- `presetForScheme` 恒等于 `settings.preset`；
- `composeSchemeOverrides` 在两个预设相同时**返回原表引用**（不复制）——
  有断言盯着这一点，否则「不分档」会被悄悄换成一条新路径。

**默认值不能是某个具体预设**：老设置文件没有这两个键，若默认成具体值，
升级瞬间所有用户的明暗分档就被打开了（表现为「切明暗时配色突然变了」）。

### 客户端不能 `import src/`，所以有两份实现

浏览器半边是自包含 bundle（`window.__ModuleLoader__`），
`presetForScheme` / `hasSchemePresets` / `ROTATE_MS` 都有一份本地副本。
防漂移的办法是**断言两侧同结果**（同一组输入跑两遍比相等），
而不是「记得改两处」。

---

## 十四、平台专有设置要按平台门控（标题栏跟随）

「标题栏跟随」只对 **Windows 桌面端**有意义：它改的是原生标题栏条带的颜色，
依赖桌面壳 preload 注入的 `data-windows-titlebar`（见第一节的载体差异表）。

但它原先在**所有平台**都显示 —— macOS 与网页端上就是一个**没有任何作用的开关**：
拨了不动、也没有报错，用户只会以为坏了。

修法：按 `hasWindowsTitlebar()` 门控这一行的渲染。

两个要点：

1. **只隐藏 UI，不动设置值**。用户在 Windows 上设过 `titlebarFollow=false`，
   换到 macOS 时那行不显示，但值必须保留 —— 切回 Windows 立即生效。
   若顺手把值也归一化掉，就成了「换个平台设置被偷偷改了」。
2. **判据必须与诊断共用同一个函数**。原先 `/diag` 里是内联的
   `document.documentElement.hasAttribute('data-windows-titlebar')`，
   若界面另写一份判断，两边可能不一致，出现「诊断说没有、界面却显示」这种
   自相矛盾的状态（这个项目在别处踩过同类问题）。现在两处都调
   `hasWindowsTitlebar()`。

> 一般原则：**平台专有的设置项要么门控，要么在 UI 上写明「仅 Windows」**。
> 一个拨了没反应的开关比没有这个开关更糟 —— 用户无法区分「没生效」与「坏了」。

---

## 十五、自定义背景为什么不能放进 `art/`（v7）

自定义背景（用户上传的图）有三个「看起来都行、其实都不行」的落点：

| 落点 | 为什么不行 |
|---|---|
| 插件目录里（如 `art/`） | `tools/deploy.ps1` 是**先删旧目录再复制**（防 `Copy-Item -Recurse` 嵌套出 `art\art\`）→ 每次重新部署都会把用户上传的图抹掉 |
| 复用 `/art/` 路由 | `artWhitelist()` 在**模块加载时**从 `BACKGROUNDS` 派生一次。自定义图是运行时增删的，加不进那张静态集合 |
| 复用 `--zf-art-<id>` 变量 | 变量表由 `structureCss()` **静态生成**（遍历 `BACKGROUNDS`）。自定义图没有固定 URL（文件名上传时才生成），写不出变量 |

所以最终是三条各自独立的设计：

1. **存储**在 `$DSH_HOME/zhuang-fangyi/backgrounds/` —— 与 `settings.json` 同级，
   `install.ps1` / `uninstall.ps1` / `deploy.ps1` 都不碰。
2. **独立路由** `/api/zhuang-fangyi/backgrounds/*`（仍在同一前缀内 → **不新增权限**），
   每次请求重新核对目录内容当白名单。
3. 客户端 `artSrcOf()` 分两路：内置图写 `var(--zf-art-…)`，自定义图写 `url(...)`。

### 一个容易漏的地方：垫底层

竖图用 `contain` 时，两侧由**同图重模糊**的 `::after` 垫底补上，它引用
`--zf-art-backdrop`。原先那行是重新拼 `var(--zf-art-${artId})` —— 自定义图没有
这个变量，垫底会变成空，**竖图两侧留黑**。改成**复用算好的 `artSrc`**：

```js
root.style.setProperty('--zf-art-backdrop',
  !tiled && fit === 'contain' ? artSrc : 'none')
```

### 上传接口是唯一的写入面

往里塞什么，之后就会被当图片服务出去。所以边界必须都在宿主侧，而且**逐层独立**：

- **格式按字节魔数判**（`content-type` 是调用方自报的，扩展名同理，都不可信）；
- **尺寸要解析得出来**（解析不出就拒绝 —— 存下来只会是一张「亮不出来」的图）；
- **大小两道防线**（`content-length` 预检 + 流式累计，长度可能缺失或撒谎）；
- **文件名由宿主生成**（客户端传 `../../etc/passwd` 不会被当成路径）；
- **服务时 `path.basename` + 目录白名单**双重校验。

> **超限时不要 `req.destroy()`**：那会在响应写出去之前把 socket 拆掉，客户端
> 拿到的是「连接被重置」而不是我们构造的 413 —— 把「图太大，换一张」变成了
> 「插件好像坏了」。要 `req.resume()` 读完丢弃，留出写响应的机会。
> 这条是**端到端测试**（真 HTTP 打进去）发现的，静态断言看不出来。

---

## 十六、回归测试覆盖

`tools/test-client.mjs` 里有专门的用例：

- 反查桌面壳（`BynINW` + `rightbarCol`）与网页壳（`pI_x6G` + `detailsCol`）类名；
- 转义类名（`\37 yHdaG_row` → `7yHdaG_row`）；
- 样式标签缺失时返回 `null` 且不抛；
- 打标幂等、可还原、断开节点被清理；
- 会话状态判定（`idle` / `ready` / `stopped` / `done` / `error`）与运行耗时迁移；
- 统计行解析（轮/步/缓存/tok per s/token 总量/上下文占比，含缺失回落）；
- 原生右栏展开时让位（两套壳的折叠属性都测）；
- v2 设置项生效与夹取；
- 插槽注册与卸载注销；
- 观察器建立、`attributeFilter` 已收窄、卸载后断开；
- **客户端注入皮肤样式表**（`/style.css` 被取、`<style id="zf-style">` 插入、
  卸载后移除、重复调用不重复插）；
- **样式表失败时降级**（500 不阻断启动，配色/主题/壁纸/设置页仍生效）；
- **样式表缺失时观测台返回 `null`**（防裸渲染：CSS 缺失时 `<img>` 会按原始尺寸铺开，
  看起来像「一张巨大的脸盖住界面」—— 实测踩过）；
- **`/style.css` 必须是纯 CSS**（带 `<style>` 标签会让浏览器把紧随的 `html{}` 块
  整块丢弃，`--zf-art-*` 全失效 → 壁纸画不出来。这是**壁纸长期不可见的真正根因**）；
- **壁纸渲染五环探针**（属性 → 间接引用 → 被引用变量 → `::before` 计算值 → 上层透明），
  桩 DOM 提供 `getComputedStyle`，桩 CSS 用真实 `structureStyle()` 产物；
- **竖图 contain + 模糊垫底**（清单契约、竖图/横图分流、平铺优先、清单缺失回落、
  深色垫底切 `-dark`）；
- **官方右栏标签页三路径**（服务可用/不可用/注册抛错）、guide 条目、
  两阶段注册与 disposer 释放、`railOwner` 的双条件裁决（`tabMounted` **且**
  `nativeRightbarOpen`）、仅展开时 `openTab` 的幂等与不打扰；
- **`styleReady` 变更必须 `emit()`**（否则观测栏永不渲染，实测事故回归）；
- **头像无描边 + `corner-shape:round`**（外壳全局超椭圆圆角会把 `border-radius:50%`
  渲染成圆角方形）；
- **折叠互补双取反**（虚拟列表 `height:0` 不被 `min-height` 顶开）；
- **设置焦点同步 `resyncSettings`**、`resetToDefaults` 真恢复默认、opacity 上限对齐；
- **设置 v3**（`accentHue` / `motion`）：v2→v3 无损迁移、色相归一化（360→0、-30→330、
  非法→preset）、改 `accentHue` 触发重取 `/themes` 并重注册、`motion` 打 `data-zf-motion`、
  静止模式不写全局 `*{transition:none}`（不越权）；
- **风格预设**：八套预设的明度极差（浅色 ≥0.03、深色 ≥0.002）、色度差异化、
  `borderAlpha` 改变边框 token、`textSoft` 幅度受控、`PRESET_STYLES` 契约、
  **圆角禁令**（spec 无 radius / 不发射 `--dsw-radius-` / 源码不出现该前缀）；
- **alias 覆盖率**：≥118 个（旧版 77）、11 个状态色齐备、
  **状态色语义可辨识**（成功绿区 90–175°、警告琥珀区 25–60°、错误红区）、
  diff 保持「增绿删红」、白名单与发射集合一致；
- **折叠的三种形态**（三轮才修全，每轮一类）：
  ① `:empty` —— 行本身空；
  ② `:has(>[data-slot=…]:empty)` —— 子节点空；
  ③ `[data-turn-process-hidden]` —— **整段过程**折叠；
  ④ `[data-chat-group-part="reasoning"]` —— **单行内**折叠（推理组）。
  第 ③ 与第 ④ 是两回事：前者由过程控制器决定，后者由该行自己的
  `aria-expanded` 决定。而 `groupPart` 的 `undefined` 与 `"response"`
  **同等对待**（外壳源码），所以判据必须用
  `:not([data-chat-group-part="reasoning"])` 而非正向匹配 `response`；
- **会话读数：宿主事件 → SSE**（C11）：reducer 全字段（轮/步/用量/缓存率/总量/
  上下文/工具计数/回合开始时刻）与状态枚举映射（idle/ready/running/tool/stopped/
  done/error）、`rateOf` 滑窗、`contextUsedOf` 缺失回落与夹取；**隐私白名单**
  （喂带正文/工具参数的事件，断言序列化结果里一个字都没有 + 字段集写死）；
  传输（假 res）：SSE 响应头、`retry`/`hello`/首帧 `state`、200ms 合并成一帧、
  心跳 `: ping`、断开即回收 tracker、非活跃会话回 `hello(live:false)`+`unavailable`、
  `once=1` 回同形 JSON 且**不留 tracker**、停用关掉所有流；
- **diff 行可读性**（用户截图「修改的代码看不到了」）：底色必须是不透明实色
  （半透明时对比度没法静态算）、与代码底可辨 1.18–1.45、增删不同色、行上文字
  ≥ 6:1；并**记录官方那对搭配**（同色系字配同色系底）多数不达标 —— 按集合断言，
  不要求每一组都不达标（`wine/dark` 恰好达标）；CSS 用语义锚点
  `[data-code-block-content]` + `_add_`/`_del_` 定位，并断言**没有**猜错的
  `[class*="code-diff"]`；真实引擎实测增删行文字都变成前景色；
- **客户端消费与回退**（C11）：`formatTokens`（含「最大单位是 M，与外壳统计条一致」）、
  `formatStats` 逐格回退（宿主给全 / 全给不出 / 混合三种）、会话 id 读法、无
  EventSource 时记 `no-eventsource` 并留在 DOM、按 id 连流、重复 refresh 不重复连、
  10s 陈旧判定、关闭后清空来源；接线断言（`statsSource` 两态、回合开始时刻驱动计时、
  `/diag` 报来源与流状态、卸载关流、`once=1` 退路存在）；
- **阅读宽度**（B7）：设置版本 4→5 无损迁移（老文件补默认值、已有字段保留）、
  三档白名单与非法值回落、客户端两份常量与宿主一致、按
  `[data-conversation-content]` 定位、行内 + `important` 写法、`auto` 是「移除属性」
  而不是写值、停用交还、`refresh` 里补写；行为单测（紧凑/宽松/auto/容器不存在不抛）；
  真实引擎实测三条对照：行内 → 我方 760px、不加 important 实测也赢、
  不干预时仍是外壳那句 `clamp(...)`（自定义属性的计算值是替换后的**原文**，
  不会算成 px —— 第一版按 768px 断言，误报）；
- **逐图取景**（B8）：清单 `focus` 必须是合法 `x% y%`（0–100）、明暗两版一致、
  生成器会写出该字段；`artPosition` 优先级逐条钉死（平铺 > 用户选「靠右」> focus >
  竖图 `center 22%` > `center`，空白串按没有处理、两侧空格去掉）；
  真实引擎实测合成层的 `background-position` 就是清单里的值；
- **选中色 / 输入光标**（B4 / B5）：`::selection` 用 `color-mix` 兑强调色且文字保持
  `label-primary`、`caret-color` 用强调色本体、只设在能输入的地方、`forced-colors`
  下交还系统；门控是 `body[data-zf-theme]`（**不是** `data-zf-glow` —— 那个是微光
  装饰开关），客户端两处停用路径都要撤这个标记；真实引擎实测光标色 `rgb(122,162,247)`
  与关掉主题后跟随文字色，并确认 `::selection` 规则确实被引擎解析；
- **换壁纸交叉淡入**（B6）：**显式 z-index 链** 垫底 -3 ＜ 当前图 -2 ＜ 上一张 -1
  （第一版把临时层放在当前图下面，淡出完全不可见 —— 结构断言还全绿，教训是
  「顺序要靠数值，不靠树序」）、临时层 240ms 淡出且铺满同区域、`[data-zf-art-out]`
  即 `opacity:0`、系统 reduced-motion 第二道保险；单测时序（真实 client.js：无旧图不建层、
  有旧图抄计算快照、`fire()` 打标记、`transitionend` 后**移除元素**）、两条换图路径都
  先比较新旧值、420ms 兜底收尾、卸载时摘掉淡到一半的层；真实引擎实测层级/时长/两态 opacity；
- **代码高亮跟随预设**（B9）：token 键与外壳真实的 9 个一致、每条都过 4.5:1 门禁
  （最低实测 4.57）、覆盖率 ≥6/9 且关键字/字符串/注释三件套齐全、色相覆盖真的改变
  关键字色、payload 键名是 `shiki`（**不能叫 `code`** —— 色阶里 `code` 是代码块底色，
  实测撞过）、共享色阶不被污染、客户端写在 **body** 行内且停用即清；真实引擎实测
  「写 body 生效 / 写 html 被外壳暗色压回」两版；
- **观测栏透明度跟随全局**（用户「不要单独设置」）：`.zf-rail` 背景必须是
  `transparent`、CSS 与客户端**都不再出现** `--zf-rail-veil`、私有 62% 兜底已删；
  真实引擎实测三档（14/45/90）观测栏自身 alpha 恒为 0，透过去看到的纱分别
  ≈0.86/0.55/0.10 且与侧栏同档，模糊仍在；
- **左栏内层底**（用户「这个地方也变成透明的」）：`--dsw-specific-sidebar-fill`
  在侧栏列上被置透明且带 `!important`、只在壁纸模式生效、**不出现**
  `[class*="_root"]` 这类模糊兜底、列上仍是纱、底部渐隐改为渐到纱色；真实引擎
  实测（照抄壳的两条规则；**测试页的 id 不能叫 `root`** —— 插件 CSS 里那条
  `#root > *` 会把它压成 `none`，白查过一轮）内层 alpha=0、列是纱、渐隐终点是
  纱色，关掉壁纸两者都回到官方填充色；
- **输入区座位渐变**（用户「这里的黑色渐变背景也给去掉」）：按本地名
  `_composerSeat` 定位、只在壁纸模式生效；真实引擎实测（照抄壳的两条带状态
  祖先的规则）壁纸开启时 `background-image` 为 `none` 且底色透明，关掉壁纸
  官方那条渐变照旧；
- **右栏 dockkit pane 透明**（用户「开始页 / tab 条还是黑的」）：语义锚点
  `data-dockkit-pane` / `data-dockkit-empty` + 类名后缀兜底、**只写 transparent
  不重复涂纱**、浮窗不被误伤；真实引擎实测（照抄壳的官方规则，两条都抄 ——
  `_tabHost_:not(_float_)` 与 `_float_` 自己那条）pane/条/开始页容器 alpha=0，
  浮窗 `bg-layer-2` 与入口卡片仍不透明，关掉壁纸回到官方 `bg-base`；
- **真实引擎实测**：用 Edge headless 读 `getComputedStyle` 的计算值
  （无 Edge 的环境真实跳过，不失败）—— 只看 CSS 文本证明不了引擎会算出什么；
- **材质深度**：flat/deep 规则存在、用同选择器 `body,body *` + `!important`
  （外壳特异性高）、描边色引用外壳变量而非硬编码、`presetDepth` 映射与属性写入；
- **排版**：每档字体规则同时覆盖 `html` 与 `body`（实测只写 body 时复合 token 不换）、
  字号规则带 `!important`（压过 presenter 的行内值）、字体栈以通用族结尾 + 含中文回退 +
  不含 `url()`、档位归一化、客户端与宿主档位一致、不碰 `--dsw-font-mono`；
- **无障碍**：`prefers-reduced-transparency` 撤壁纸 + 三列回不透明底（选择器逐条对应
  纱层规则）、`forced-colors` 撤壁纸与立绘、**不**实现 `prefers-contrast`（外壳 0 处支持）、
  偏好不修改用户设置；
- **本地化**：DICT 中英键集合一致、无空值、英文里无残留中文（漏翻检测）、
  插槽注册带 `locale: NS`；
- **发行清单**：`tools/check-manifest.mjs` 双向校验（声明的权限必须找得到代码证据、
  不该声明的权限必须找不到证据）、`install.adapter` 必须是 `profile-bundle`、
  `capability.invocation` 必须含可执行选择器、零安装期脚本、零运行时依赖。

跑：`node tools/test-client.mjs`（本地 1136 项 / 无 Edge 的环境约 1070 项 —— 真实引擎那
13 组会真实跳过并打印 `SKIP`，不是断言 Edge 存在）。

---

## 十七、设置页页签化：借鉴了官方，但刻意没照抄（0.9.0）

### 问题的真实形状

7 组 24 行平铺在一页里约 1900px，而面板内容列只有约 720px：

```
800px 面板 − 188px 导航 − 48px 内边距 = 564px 宽 × 约 720px 高
```

（来源：外壳 `SettingsRoot.module.css` 的 `.panel{width:800px}`、`.nav{width:188px}`、
`.options{padding:0 24px 24px}`。）

**这不是分组分得不好，是没有分层。** 0.6.0 把「装饰组堆 10 行」的语义问题
理顺了，却没解决「一屏放不下」——两件事都叫「设置页很乱」，但根因不同。

### 从官方 `@deepseek-ai/dsh-client-ui-settings-models` 读到的

实测源码（`app.asar` 内联 CSS 模块）用的是「**卡片列表** + 官方行规格 +
说明折叠（`.helpButton` 藏长说明）」。本轮**只取两点**：

| 取用 | 说明 |
|---|---|
| 分层 | 顶部页签，一次只渲染一页 |
| 局部重置 | 官方 `.reset`（无边框 12px 文字按钮）的语义 → 每页「恢复本页」 |

**明确不做的**：卡片容器（有页签再套一层是重复分层）、逐项照抄官方
Button/Switch/Segmented/Input 的数值、ⓘ 折叠说明（换页签后每页只剩 5–8 行，
说明常显也放得下）。

> 一般原则：**参考别人的做法 ≠ 复制别人的做法。** 抄之前先问「这条约束在
> 我们的场景下还成立吗」—— 官方的卡片列表是为「插件自己的配置页」设计的，
> 我们这里是整个插件 24 项设置的总入口，层级已经由页签给足了。

### 三条不可回退的约束

1. **UI 态不进浏览器本地存储**。`tools/check-manifest.mjs` 的
   `FORBIDDEN_EVIDENCE` 把 `browser:local-storage` 列为**禁止权限**，且
   对 `client.js` 做的是**纯文本扫描**——连注释里都不许出现那个词。
   页签与壁纸展开态因此只能放模块级 `state`（同一会话内保留，重开面板仍在
   原地）。写进 `settings.json` 更脏：那是用户设置文件，不该混界面状态。

2. **每页行数上限由 `SETTINGS_TABS[].max` 强制**，合计必须仍是 24。
   「这一页塞不进了一屏」会**直接让测试失败**，而不是等用户发现要滚。

3. **壁纸预览走全尺寸 URL，网格才走 `art/thumbs/`**。96×60 用缩略图会糊。
   副作用：设置页默认状态下 `/art/thumbs/` 命中数为 **0**，断言必须先切到
   「背景」页并展开再数。

### 测试侧踩到的两个坑（都会伪装成「功能没生效」）

1. **`component({})` 返回元素树，不是渲染结果。** 函数组件在树里只是
   `{type: fn, props}`，输出要等 React 真正渲染。0.8.0 之前不影响断言
   （设置页的 `img` 都作为实参提前算好），引入页签后页签按钮在
   `Segmented` **内部**生成——只看原始树会得到「一个 tab 都没有」的假阴性。
   `renderDeep` 就是为此加的。

2. **桩的 `createElement` 把 children 放在元素上**（`{type, props, children}`），
   真实 React 放在 `props.children`。渲染器**两处都要照顾到**：只认后者会
   清空整棵树；只把子节点放进 `node.children` 则 `Row` / `Slider` 收不到
   内容，表现为所有断言拿到 0 个节点。

   另外深度上限别设太紧：它同时数宿主元素与函数组件（后者多消耗一层），
   背景页预览 `<img>` 实测在第 **13** 层。设成 12 时它被**静默丢掉**。


---

## 十八、如何加一套预设（0.11.0 起的实际流程）

加预设的触点**只剩一处手写**：`src/palette.js` 的 `PRESET_SPECS`。其余全部派生。

### 步骤

1. **在 `PRESET_SPECS` 里加一项**，字段含义见该文件顶部注释。必填：

   | 字段 | 说明 |
   |---|---|
   | `label` | 中文显示名（客户端下拉用，**生成器会读它**） |
   | `style` | 风格短名（如「自然沉稳」，显示在预设下拉里） |
   | `hue` / `hueDark` | 表面与文字色相（取自官方素材量化） |
   | `chroma` / `chromaDark` | 色度 0..255 —— **必须与已有套拉开**，见下方陷阱 |
   | `surfaceShift` / `surfaceShiftDark` | 表面明度基调偏移（百分点） |
   | `textSoft` | 文字对比倾向（true = 柔和） |
   | `borderAlpha` | 边框不透明度基调 |
   | `defaultBackground` | 配套壁纸 id（必须在 `wallpaperCatalog` 里存在） |
   | `combo` | 一键推荐组合的 `backgroundOpacity` / `fontFamily` / `contentWidth` |
   | `accent` / `accentLight` | 深色 / 浅色档强调色（**`accentLight` 必须压深到能当链接**） |

2. **在 `tools/gen-wallpapers.mjs` 的 `PRESET_EN` 里加一行英文名**。
   漏了生成器会直接报错（`预设 X 在生成器的 PRESET_EN 里缺英文名`），不会静默。

3. **重跑生成器**：`node tools/gen-wallpapers.mjs`
   它会把 `PRESETS` 与 `PRESET_LABELS` 两份副本写进 `client.js` 的标记块。

4. **跑检查**：`npm test`（= 语法 + 对比度 + 生成器一致性 + 无头测试 + 清单）。

### 为什么不需要改别的地方

`PRESET_STYLES`、`PRESET_COMBOS`、`themeDefinitions`、`contrast.js` 的循环、
测试里的 `themes` / `overrides` 桩数据，**全部从 `PRESET_IDS` 派生**。
0.11.0 之前它们当中有几处是手写的，加一套预设会静默漏改 ——
实测「只改 `PRESET_SPECS`」后只有 **1 条**断言失败（现已改为派生）。

### 陷阱

- **色度不能都取同一个值**。0.6.0 的教训：四套预设 `chroma` 全是 5/6 时，
  切预设 ≈ 只换了强调色，背景几乎不动。新套必须至少在
  **色相 / 色度 / 明度基调**三个维度之一与每一套拉开。
  验收看 `contrast.js` 的极差报告：浅色 ≥0.03、深色 ≥0.002。
- **`accentLight` 要比 `accent` 明显更深**。它同时当链接（压在较亮的
  表面上要 ≥4.5:1）与焦点环（≥3:1）。黄绿、香槟金、冰白青这类高亮度色
  尤其要压得狠 —— 直接照抄 `accent` 会跌破门禁，`contrast.js` 会拦。
- **色相接近不等于观感相同**。`sand`(5°) 与 `wine`(2°)、`frost`(160°) 与
  `burst`(156°) 色相都只差几度，但色度（2 vs 7、3 vs 8）与明度基调相反，
  观感差异明显。**色相不是唯一维度**。
- **`defaultBackground` 必须真实存在**，`contrast.js` 会核对
  「组合壁纸与推荐壁纸一致」。