# 开发日志 / Development Log

`dsh-yizi-themes` 的开发过程记录：关键决策、踩坑与原理。按时间倒序。

> **版本号说明**：下面标注 v0.5.5–v0.6.5 的条目，是 0.5.4 之后同一轮改造期间的**本地测试迭代**（每验证一步就加一个号）。它们从未对外发布，最终统一发布为 **v0.5.6**，见 [CHANGELOG](../CHANGELOG.md)。日志保留当时的编号以忠实记录排查过程。

---

## 2026-10-28 · v0.6.5：一个未声明的变量炸掉了整张样式表（用户报"样式全变、控件变形、logo 变形、主题点不动"）

### 怎么找到的：答案是"看不见"

连续两轮修复都没命中，因为**真实错误从未进入任何日志文件**：

- 桌面应用的崩溃日志只捕获 renderer 的 **error 级 console**；
- cordis 在 fiber 失败时走的是**它自己的 logger**（`vendor/cordis/src/fiber.ts:661` 的 `ctx.logger.error(reason)`）。

于是我做了 v0.6.4：把每个 apply 阶段的 `ok:<阶段>` / `FAIL:<阶段>: <错误>` 面包屑写进 **localStorage**，未预期异常记 `FATAL: <堆栈>`。这一招的关键是——**即使页面根本起不来，记录也已经落在磁盘上**，事后可以从 Electron 的 LevelDB 里读出来。

重启后应用起来了、控制模块也回来了，但样式全崩。读 LevelDB 拿到：

```
apply:entered → stage:sheet-start → FAIL:emit sheets: inkL is not defined
→ 品牌座位 / 头部控件 / 浮动控件 / core 注册 / 主题状态采纳 / 行字典 / 行注册 / 观察器 全部 ok
```

### 根因：两处错误叠加

1. `deriveDarkPalette()` 在"中性墨描边"分支引用 `inkL`，**但该函数从未声明它**（亮色版 `deriveLightPalette` 声明了）。用户把自定义主题的"高级调色 → 描边"设成**中性墨**，三元表达式才真的去取它 → `ReferenceError`。
2. 更要命的是失败的位置：`refreshSheets()` 原本**整张表拼好再一次性赋值**。`customThemesCss()` 抛错 ⇒ 赋值从未发生 ⇒ **基础表也没写进去**。19 个预设主题的样式、设置行的布局 CSS、品牌/logo 覆盖规则全部消失，浏览器退回默认排版。

**四个症状（样式全变、控件变形、logo 变形、主题点不动）是同一个根因。** 这也解释了"为什么之前好好的"：0.6.1 时描边是默认的品牌色，不走该分支；改成中性墨之后，每次启动都炸在同一行。

### 修复

1. 补 `inkL` 声明（与亮色版同一套 clamp）。
2. **发射分块隔离**：基础表永远先写，自定义主题单独 try/catch——坏掉的主题只能丢掉自己那一段。
3. 保留 bootlog（限制最近 60 条）作为常驻自诊断。

### 沉淀

- **别让"整体赋值"成为单点故障**：多个独立产物（基础表 / 自定义块）必须分别构建并分别兜底，否则一个坏输入会让全部输出消失。
- **esbuild 不做类型检查**：未声明标识符可以一路打包发版。`tsc --noEmit` 只用于查 `TS2304`（未声明标识符）这类致命问题也值得加进构建。
- **日志路由也是可观测性**：第三方 logger 会把关键错误从 console 里带走。写一条**落盘**的轨迹（localStorage）比在 console 里大海捞针可靠得多——而且它在启动失败时依然有效。

---

## 2026-10-28 · v0.6.3：apply 抛异常 = 整个应用拒绝启动——插件必须"炸不死宿主"（用户报"启动失败 + 控制模块全消失"）

### 事故链条

用户重启后：`web boot: 1 entry did not activate` / `dsh-yizi-themes: failed`，应用启动中止；禁用插件才恢复；手动启用后主题控制模块全部不见。

读 rc.3 `packages/client/web/src/boot-client.ts` 的 `assertEntriesActive`：fiber 状态非 active 即视为启动失败。`apply()`（及其**立即执行**的 effect）一抛异常，fiber 就是 failed。

### 定位方法：用真实 SlotCore 做最小复现

之前所有 jsdom 复现都用桩 slots，恰好把真实校验全绕过了——**唯一没被真实覆盖的服务就是本次的凶器**。改用真实 `packages/client/ui-slots/src/index.ts` 的 `SlotCore`（零运行时依赖，可直接打包）加一层忠实的最小 slots 服务（声明表 + inject 观察者），跑四种组合：

| 场景 | 结果 |
|---|---|
| 单次 apply，槽先声明（boot 顺序） | 0 错误，行 1 份、品牌座位 1 份 |
| 单次 apply，槽后声明 | 0 错误，同上 |
| **双次 apply，槽先声明** | `single slot "sidebar.brand.mark" already has a registration at priority -100` |
| **双次 apply，槽后声明** | `list slot "settings.general.item" already has an entry with id "yizi-appearance"` |

**结论**：单次 apply 干净；第二次 apply 才会撞注册。品牌座位注册在 apply 早期（第 260 行）、行注册在尾部（第 426 行）——**一次 throw 直接吞掉后面的行注册**，"启动失败"与"控制模块消失"是同一根因的两个症状。

### 修复：guarded 阶段 + 幂等注册

- `apply` 内每个阶段 `guarded(label, run)`：失败只记录，不外抛。
- 品牌三座位 + 两处行注册：已被占用 → 告警并跳过（返回空 disposer），第二次 apply 无害。
- `push`/`sync` 改为函数声明（提升），订阅回调内再包 try/catch，消除早触发 TDZ。

实测（真实 SlotCore）：单次 0 错误；双次 0 错误，行/座位各保留 1 份。

### 沉淀

- **第三方插件对宿主的契约是"永不抛"**：一个外观插件没有资格让整个客户端启动失败。启动审计是零容忍的。
- **桩服务会隐藏真实校验**：本次若不是把真实 `SlotCore` 接进来，永远只能猜。最贵的服务最该用真的。
- 幂等注册顺带覆盖了真实场景：HMR 热重载、组合重载、重复装载。

---

## 2026-10-28 · v0.6.2：内联样式遮蔽——自定义主题「全黑没生效」的真正根因（用户报"海之蓝没有一点蓝"）

### 踩坑：三层"看起来都对"，级联层输了

用户报应用自定义主题后 UI 全黑无主题色，且添加/删除/保存均无即时反馈。诊断走了大弯路：

1. **怀疑响应链**。通读 cordis `effect`（vendor 源码确认 "execute runs immediately"）、ui-renderer 的 `standardKit/storeOf/observableHook`、store 引擎（sync flush、revision 单调）——静态层全对。
2. **headless 实证**。esbuild 打包 vendor cordis + dsh-client-store 源码 + 插件 themes-store，复刻 `ctx.effect(() => themesStore.subscribe(...))` 接线：监听触发、store 通知、主题数组全部到位——链路正常。
3. **jsdom 实车**。用 `new Function` 加载**真实 dist/client.js**（模块加载器 shim + React 18.3.1 + store 源码别名打包），伪造 slots/locale/theme 服务，走完整用户流（填名称、选色、点添加、点删除）：**sheet 更新 ✓、store 通知 ✓、网格与列表在下一帧 flush 后正确出现新主题 ✓**。响应链在真实 bundle + 真实 React 下也没有问题。

### 真根因：rc.3 ThemePresenter 的内联 token

读 `git show dsh-v0.2.1-rc.3:packages/client/ui-layout/src/client/theme-presenter.ts`：核心把**活动主题的全部 token 以 `body.style.setProperty` 写成内联样式**。CSS 级联里内联样式压过一切普通类选择器——`body.theme-custom-x { --vars }` 永远输给上一主题的内联 token。于是应用自定义主题后外观纹丝不动（用户停在旧主题的暗色观感上，"没有一点蓝，都是黑色的"）；添加/删除/保存的"无反馈"本质是**外观从不变化，反馈无从观察**。

**修复**：`customThemeCss` 每条声明加 `!important`（author-important 是唯一高于内联的层叠来源）。类挂上即赢、类移除即还（核心主题的内联 token 原样保留），不需要清写 presenter 的 DOM。

### 方法论沉淀

- **工作树 ≠ 运行版本**：harness 检出在 alpha.1 分支，app 跑 rc.3——框架层源码必须 `git show dsh-v0.2.1-rc.3:<path>` 核对（本次两者恰好一致，但不能靠运气）。
- **"响应式坏了"先验证级联**：样式不生效时，先查最终计算值的输赢（谁的选择器/层叠来源在起作用），再查状态链。这次三层状态链全对，输的是 CSS。
- **jsdom 实车可复刻 Electron 插件环境**：真实 bundle + 模块表 shim + 真实 React + 真实 store，比 mock 组件测试多抓住了整个接线层；受控输入要用 `el.value=` 直写（React value tracker 拦截 prototype setter 路径）。

---

## 2026-10-28 · v0.6.1：派生引擎 v3——预设语法五声部（用户问"三个颜色够吗"）

### 方法：先把 19 套预设拆成"独立设计决策"，再决定暴露几个输入

用户问三输入是否太少。正确顺序不是直接加输入框，而是先回答"**做一套和预设同水准的主题，到底需要几个独立决策**"。逐套对读 7 套个性迥异的主题（academic/typewriter/vaporwave/morandi/matrix/minimal/palace），答案收敛到 **5 个**：品牌、墨色（第二色相）、明暗底色相分族、描边声部、语义融合。最有价值的发现是**墨色是独立于品牌的第二色相**（学术紫墨 306° vs 品牌蓝 263°；vaporwave 紫墨 vs 粉品牌），以及**亮底跟品牌、暗底跟墨**（vaporwave 亮粉暗紫）——这两条此前完全没进派生模型。

### 两个实现层教训

- **OKLCH 色相环 ≠ HSL 色相环**：第一版墨色分支按 HSL 直觉写（粉≈330°），实测 vaporwave 粉在 OKLCH 里是 **345°**，分支根本没触发。修正前先跑测量脚本（#ff6ec7→345、#b5372a→30、#008a2e→147），并发现**学术墨 = 学术蓝 + 43°** 这个可写死的精确漂移量。
- **语义融合的守门条件是"饱和度+色距"双门槛**：单看色距会误伤（typewriter 暗金 C 只有 0.104，色相 84° 离红锚 25° 有 69°，但单色距规则在别的暖色上仍可能误融合）——加 C>0.14 饱和度门槛后，palace/matrix/vaporwave 正确融合、typewriter 正确豁免，无一行特判。

产品形态上取的平衡：基础流程仍是**一键**（只选主题色，墨色自动 = 蓝品牌 +43° 漂紫），预设手工调的另外三个自由度进「高级调色」折叠区（墨色+自动复位、底色浓度三档、描边声部两档），第五个（语义融合）做成自动规则不设输入。

---

## 2026-10-28 · v0.6.0：Theme Studio 自定义主题 + mock 卡片预览 + 排版跟字号

### 字号轴：核心自己的设置行也是固定 px，插件跟"delta"而不是跟"设置值"

用户反馈诊断文字偏大，怀疑插件没读字号设置。查实：核心 0.2.1 的字号轴写 `--dsh-content-font-size`（10–22px 默认 14）到 body 内联，`gradient-shadow-text.css` 派生 `--dsh-content-font-delta`（设置−14）推全 UI 阶梯；但 **ui-settings-general 自己的模块 CSS 也是写死 14/12/13px**——设置面板的 chrome 本来就不跟轴，跟轴的是会话内容/气泡/Markdown。插件行此前沿用固定 px，用户调小字号后自然显得偏大。修法取中：行内排版全部改 `calc(原px + var(--dsh-content-font-delta, 0px))`——默认 14 时 delta=0 逐像素等于旧值（零回归），调小时整行同步缩，0px 回退保老核心。教训：**"跟随设置"跟的是派生 delta，不是设置值本身**；带 fallback 的 calc 让新旧行为在默认点精确重合。

### 派生引擎 v2：RGB 混色换 OKLCH 按角色推导（用户实测反馈"不好看"）

0.6.0 首发的 mix 引擎被用户否了：RGB 线性插值两个致命伤——(1) 饱和色与白/黑的中点发灰发闷（红 accent 的次级文字混出脏粉）；(2) "多浅"和"多艳"耦合在一个插值系数里，无法表达"表面要淡但文字要沉"。重写为 **OKLCH（Ottosson 参考矩阵，sRGB↔OKLab 手写往返 ~60 行）按角色配方推导**：表面层只承 accent 色相、chroma 钳到 ≤0.035（永不出腻粉底）；文字亮度阶梯（0.26→0.76）与 accent 鲜艳度**解耦**（textC = clamp(C×0.55, 0.02, 0.13)，霓虹 accent 也出沉静次级文字）；品牌色明度钳制（亮 0.40–0.62 / 暗 0.62–0.85）让粉黄霓虹自动压深、深海军自动提亮；灰 accent（C<0.02）色相不可靠，回落 265° 中性蓝。验证方式：把 academic 的 #002fa7 喂进引擎，esbuild 临时打包跑 node 对表——暗色品牌 #487ff4 / 次级文字 #5e7fc0 / layer-2 #eff4ff，与手调的 #5a7ce3 / #5a7ce3 / #edf2ff 同族。教训：**配色派生的正解不是"更像目标色的插值"，而是把设计师的角色分工（中性表面 / 解耦文字 / 唯一饱和的品牌声部）编码成感知空间里的钳制区间**。

### 自定义主题：别发明派生配方，反推内置主题的配色关系

Theme Studio 的核心风险是"自动生成的配色难看"。做法是把 `academic` 亮/暗两块的 62 变量当成**关系式**而非数值表来反推：暗色品牌 = accent + 42% 白（#002fa7 → #5a7ce3 逐位一致，验证通过）；亮色层阶梯 = 底色向 accent 7%/13% 混入；边框 = accent 的 .10–.28 alpha 阶；滚动条 = 20%–42% 混入。全部用 JS 小型 mix 函数在生成时算成**字面色值**（不用 CSS color-mix 输出），与内置 sheet 同构产出 `body.theme-custom-*` 两块——brand-overrides 的别名级联自动补全其余令牌，这是"同构复用"而非"另起炉灶"。暗色语义色（error/success/warn）保持内置的固定红绿琥珀，不从主题色派生——语义色不该随品牌漂移。

### 两个工程小点

- `themes-store` 的 `all()` 必须返回**缓存快照**（set 时重建）——`useSyncExternalStore` 的 getSnapshot 若每次返回新数组会无限重渲染。
- HeaderControls 里那份手抄的 19 主题列表是 0.4.x 时代的重复源，0.6.0 借 themesStore 一并消灭；`/theme` 命令的 options 是"每次打开现答"，自定义主题无需重注册命令。

---

## 2026-10-28 · v0.5.5：`/theme` 斜杠命令 + 运行时自检（两个纯官方面的新功能）

### cordis 的 `ctx.inject(['service'], cb)` 是可选服务的安全挂载点

给插件接 `/theme` 命令前最大的顾虑：老核心/异构核心没有 `commandUi` 服务时，注入声明会不会拖垮整个插件激活（引导是全有或全无）。读了 `vendor/cordis/src/fiber.ts` 才放心：`ctx.inject(deps, cb)` 会 spawn 一个**独立的子 fiber**，状态机里有专门的 `PENDING — waiting for required services` 态——必需服务永不出现，子 fiber 就永远 PENDING、回调永不执行，**外层插件照常 ACTIVE**。结论：想让插件吃"可能不存在的核心服务"，一律走 `ctx.inject` 子 fiber，绝不要把服务名加进插件顶层的 `inject = [...]`（那里缺失才会挂）。虽然核实过 ui-commands 从 `v0.1.2-alpha.1`（最早支持代）就存在，防御仍是免费的。

### CommandContribution 的文案是"每次开菜单现问"的

`label()` / `description()` / `searchLabels()` 都是回调、每次候选合成时现调——所以文案必须从绑定的 translate 闭包现读，不能在注册时捕获字符串，否则换语言要等重注册。`options(session, signal)` 同理，每次打开现答，插件借此返回实时主题状态（`active` 行即弹层高亮落点）。

### Doctor 的令牌覆盖扫描：把审计做成面板

COMPAT-0.2.1-rc.3.md 那次 381 个 `var()` 引用求差集是纯手工；0.5.5 把它变成 `document.styleSheets` 上的在线扫描：插件自己的 `<style>` 用 `ownerNode` 身份跳过（不能按 id 查 styleSheets）、嵌套规则（`CSSMediaRule` 等）递归、每个 sheet 单独 try/catch（跨域 sheet 会 throw）。"全仓未定义"令牌 = 核心引用 − 核心定义 − 插件定义——这类令牌现在渲染为回退色，是天然的补全覆盖点清单。检查按需运行，不挂渲染热路径。

---

## 2026-10-26 · v0.5.2：0.2.1-rc.3 兼容确认 + 全量令牌覆盖审计

### 「深度求索中，用时…」没主题化？先查装的版本

用户反馈运行态文字仍是官方蓝。第一嫌疑是 0.5.1 的别名映射没打通，实际一查应用内安装目录（`~/.dsh/profiles/desktop/node_modules/dsh-yizi-themes`），**装的还是 0.5.0**（dist 构建 10/13）——0.5.1 修的映射根本不在跑的代码里。教训：**排查"没生效"先对比"仓库源码 vs 应用内 dist"**，别先怀疑映射链。

映射链本身核对无误：`.running` 在元素级把 `--dsw-alias-label-shimmer` 重指到 `--dsw-alias-label-deep-diving-shimmer`，但那是**转指**不是阻断——body 上的插件映射沿继承链仍可达；`TextShimmer` 的底色走 `--dsw-alias-label-deep-diving`，高光走 shimmer 色，0.5.1 三个都映射了。

### 全量令牌审计：381 个 var() 引用求差集

这次不做"抽查"，把 rc.3 全部客户端 CSS 的 `var(--…)` 引用（381 个）与插件定义的变量（84 个）求差集，剔掉指标类（radius/font/shadow）和核心内部推导项后逐个映射 UI 表面。真发现：

- **`--dsw-alias-link` 从没被任何主题覆盖**——链接一直是官方蓝（6 个包在用）。
- **`--dsw-static-deepseek-400/450/500` 被组件绕过 alias 直接消费**（Toast 动作、FileTypeIcon 默认墨色）。在 body 级重映射 static 反而是干净解法：static 只被 DeepSeek 蓝系消费，ANSI/语义色用的是独立的 `blue-*`/`neutral-*` 色阶，不会误伤。
- **一批"声明未定义"令牌**（`bg-l1/l2`、`bg-layer-4`、`fill-*`、`label-quaternary`、`separator-primary`）：核心消费但全仓无定义，渲染成透明/neutral fallback——给它们映射到主题层级是"上色"而不是"改色"，观感从"破"到"齐"。
- **元素级钉死的三处**（ContextMeter 分段 tints、HoverCard 底、TrajectoryTable 渐变）：body 值够不着；HoverCard/Trajectory 无稳定钩子维持不覆盖，ContextMeter 用 CSS-module 哈希保留源类名的特性 `[class*="colorMessages"]` 补上。
- **抓到自己 0.5.1 的映射 bug**：`toast-label` 派生自 `label-primary-inverted`，但 Toast 表面两种模式都是深色（核心注释明说 always-dark），该令牌暗色下是深灰 → 暗色 Toast 文字对比度约 2:1。改回核心同语义的恒亮白。

### 桌面版 CLI 的坑：host-commands 里的 dsh.cmd 是陈旧安装路径

`%APPDATA%\DSH Desktop\host-commands\desktop\bin\dsh.cmd` 硬编码 `D:\Program Files\DSH Desktop\...`（旧安装位置），直接调用报"找不到路径"。当前版的正确启动器在 `resources\runtime\cli\bin\dsh.cmd`：`ELECTRON_RUN_AS_NODE=1` + `<exe> --expose-internals resources\app.asar\dsh\node_modules\@deepseek-ai\dsh-desktop-host\lib\cli.js`。注意 stale 那份指向的 `app.asar\lib\desktop-cli.js` 在本代已不存在（CLI 挪进了 `dsh-desktop-host` 包）。

---

## 2026-10-22 · v0.5.1：适配 0.2.1-rc.2 + 新会话浮动菜单定位

### 新会话页：浮层与「打开侧边栏」按钮重叠

0.2.1 的空会话头虽然隐藏了标题行（`hideChrome`），但**照常渲染 `conversation.session.header.corner` 座位**——右栏展开按钮（`@deepseek-ai/dsh-client-ui-sidebar-right` 的 `ExpandButton`）就坐在那里。插件给浮动主题菜单定的是 `right: 28px`，和这个按钮踩在同一块区域。

修法不是写死按钮尺寸，而是**量**：`place()` 每次 `sync()` 用 `getBoundingClientRect()` 取 `[data-conversation-header-corner]` 的实时位置，把浮层 `right` 抬到该座位左侧 8px（座位为空时回落到 28px），并监听 `resize`。这样窗口宽度、header 内边距（`padding: 10px 28px 0 20px`）、`margin-right: -16px` 之类的变化都能自动跟随。教训：**fixed 浮层要避开"会渲染但不可见"的兄弟座位**。

### 侧边栏一展开，浮层又压到右栏上

第一版只避让 corner 座位，用户第二次反馈：把右栏拉开后，浮层位置没变，却盖住了右栏内容。原因是右栏 `@deepseek-ai/dsh-client-ui-sidebar-right` 的面板：

```css
.OUqwTW_panel{position:absolute;top:0;bottom:0;right:0;width:<width>px}
.OUqwTW_panel[data-sidebar-right-open] [data-dockkit-host=dock]{visibility:visible;transform:none}
```

- 面板**折叠时就已经占着最终宽度**（`position:absolute`），只是内容用 `transform:translateX(--dsh-sidebar-width)` 滑到屏幕外；
- 展开时 `ExpandButton` 按设计「shown 时不渲染」→ corner 座位变空 → 浮层回落到 `28px`，正好落在面板的顶部 chrome（折叠 / 全屏按钮）和内容上。

于是把「右上角障碍物」统一成一个集合：corner 座位 + `[data-sidebar-right-open]` 面板，取**最左边界**作为锚点，浮层放在它左侧 8px。

**触发器的坑**：展开只切换面板上的**属性**，没有节点插入、宽度也不变 → 原来的 body `childList` 观察器和 `ResizeObserver` 都不会被触发（这也解释了用户看到的"位置没变"）。三个触发器都得有：

1. `window resize`（窗口变化）；
2. 面板上的 `ResizeObserver`（拖拽改宽，只改内联 style，无 DOM 节点变化）；
3. 只过滤 `data-sidebar-right-open` / `data-sidebar-right-panel` 的 `MutationObserver`（展开 / 折叠 / 全屏切换）。

右栏全屏（`data-sidebar-right-panel=fullscreen`，宽 100vw）时左侧没有可放位置，浮层直接隐藏；折叠或退出全屏后由 2/3 号触发器恢复。另外 `place()` 加了 `heroVisible` 守卫，避免 hero 已消失后 ResizeObserver 回调把它重新显示出来。

### 「打开侧边栏」按钮所在座位的槽位语义复核

`renderOutletContent` 对 single 槽的逻辑（`dsh-client-ui-renderer`）：

```js
const entry = host.entriesOfSlot(slotKey)[0]
if (!entry) return entries.length > 0 ? deadCell() : <Fragment>{fallback}</Fragment>
```

即：**没有 entry 时才渲染 fallback；entry 存在但全部失效时渲染 `data-slot-error` 死格**，不会回退。这解释了为什么插件「始终注册 hero 槽」会把官方悬停动画鱼永久顶掉——`fallback: <HeroFish/>` 永远不渲染。0.5.1 改为跟随 `brandStore.logo` 动态注册/注销。

### 一个坑：CSS 源文件改了，bundle 里仍是旧的

`brand-overrides.css` 只是**源文件**；`src/client/index.ts` 实际 import 的是 `brand-overrides.ts`（由 `scripts/gen-themes.mjs` 把 CSS 转成模板字符串的生成物）。只改 CSS 再 `node prepare.mjs`，构建**不会**重新生成 `.ts`，产物里的规则仍是旧的（本次差点把 P2-2/P2-3 漏掉，靠 grep 产物里 `has(svg[` 才发现）。

正确姿势：

```bash
node scripts/gen-themes.mjs <cssDir> <outFile> src/client/brand-overrides.css brand-overrides src/client/brand-overrides.ts
node prepare.mjs
```

注意第 2 个参数 `outFile` 若指向 `src/client/themes.ts` 且 `cssDir` 传错（例如传了空目录），**会把 themes.ts 覆盖成空壳**——本次误传 `src/client/themes`（那是空目录）就中招了，靠 `git checkout -- src/client/themes.ts` 恢复。主题 CSS 的源在 `patch/packages/client/ui-theme/src/styles/themes/*.css`。

### 0.2.1 主题侧变化

- 运行态文字扫光改用 `TextShimmer` 原语，扫光色是 `--dsw-alias-label-shimmer`（不再是 `[role=status][aria-live]` 上的 `background-image`，0.2.1 的 status 元素已不带 `aria-live`）；`--dsh-state-ongoing` 在整个 0.2.1 里没有定义。
- `--dsw-alias-settings-card-fill/-stroke`、`--dsw-alias-label-deep-diving(-shimmer)`、`--dsw-alias-menu-icon`、`--dsw-alias-turn-trigger-*` 等新 token 用 `body[class*="theme-"]` 从各主题已有令牌派生即可，`var()` 在同元素上解析，亮/暗自动跟随，`default` 主题不挂 class 保持核心原值。`bg-mask-*`（中性黑/白透明遮罩）与 `file-diff-*`（语义绿/红）**故意不主题化**。

---

## 2026-10-12 · v0.5.0：适配 0.2.0-rc.2（修复桌面版装后起不来）

### 现象与第一现场

用户报「装了这个插件，DeepSeek Harness Desktop 就启动不了」。桌面版崩溃日志（`%APPDATA%\@deepseek-ai\dsh-desktop\logs\crash-*-web-boot.log`）给出确切答案：

```
Error: web boot: 1 entry did not activate
dsh-yizi-themes: import failed: client-modules: require("@deepseek-ai/dsh-client-runtime/client")
  missed the module table — not a platform seed word, not a materialized module, and no registered package factory
```

关键认识：**桌面版的 web 引导是全有或全无**——只要有 entry 激活失败，整个客户端引导中止，表现为应用打不开。所以一个"少了个依赖"的插件足以让桌面版黑屏。

### 定位：模块表（PLATFORM_MODULES）才是客户端插件的"依赖清单"

`dsh-client-modules` 里有一张硬编码的种子表，客户端 bundle 的 `require()` 只在这张表 + 已物化模块 + 已注册工厂里找。0.2.0-rc.2 的表：

```
react, react/jsx-runtime, react-dom, react-dom/client,
@deepseek-ai/cordis, @deepseek-ai/dsh-client-store,
@deepseek-ai/dsh-client-ui-slots, -ui-primitives, -ui-dockkit
```

**`@deepseek-ai/dsh-client-runtime` 已整包删除**（它就是被 `dsh-client-store` 取代的那个）。表外的 `require()` 直接抛错；而 `dsh.client.inject` / `external` 里的陌生名字**只是被静默忽略**（不会给出任何警告），所以 `inject` 写错比 `require` 写错更隐蔽。

审计要点（可写成脚本）：把构建产物里所有 `require("...")` 的模块名抓出来，逐个对照种子表；只要有一个不在表内，桌面版就会启动失败。

### 第二层：`settingsScope` 没了，`ui-theme` schema 也窄了

顺手比对 `0.2.0-rc.2` 的 `ui-theme`：schema 只剩 `{ preference, fontSize }`——`customBrand`、风格主题字段都没有；服务 `ctx.settingsScope` 已被 `ctx.configForms` 取代，`setThemeId` 也随 `dsh-client-runtime` 一起消失。旧代码此时是"双层不兼容"：即使修掉 import，品牌设置仍会写失败（表现为能输入、刷新即丢）。

本插件的应对（延续既有设计）：**明暗偏好走核心 `ctx.theme`**（本代仍有 `preference`），**风格主题与自定义品牌由插件自管**——主题是 `localStorage` + `body.theme-<id>`（早就是这样），品牌文档改为 `localStorage`（`dsh-yizi-themes:brand`），写入即推进内存 store 并重绘。附带好处：品牌不再受任何设置传输层变更影响，也不再需要"在途写入计数"那套防抖（0.3.1 为 IME 跳字打的补丁随之退休）。

### 验证方法：隔离 DSH_HOME + 独立 profile + headless 断言

不能拿用户正在用的 desktop profile 做实验（会话本身就跑在里面）。做法：

1. 造一个临时 `DSH_HOME`（`.../yizi-verify/dshhome`），里面放一个 `yizitest` profile：`dsh.profile.bundles` = base + web-app + `dsh-yizi-themes`，依赖指向本地 tgz；
2. `dsh --profile yizitest --port 34567 --no-open` 起服务（**注意：`web` 不能当位置参数传**，它只接受 app flags，传了会报 `too many arguments`）；
3. `puppeteer-core` 连本机 Chrome，抓 `pageerror` / `console` / 4xx 请求，断言：样式已注入、槽位产物在 DOM、交互后 localStorage 与 `body.theme-*` 正确、刷新后保持。

第一轮探针就抓到两个静态审计看不见的问题（见下）。

### 坑 1：`IconDarkOutline16` 在本代已改名 → React #130

本代 icon 集把尺寸后缀 `<Name>16` 改成笔画档位 `<Name>Regular` / `<Name>Medium`。具名导入一个不存在的导出**不会报错**，只是 `undefined`；React 渲染到它才抛 `Minified React error #130`（element type is invalid）。静态审计（"require 的模块都在表内"）完全看不出这个。

修复思路不是"改成新名字"了事，而是**不再硬绑名字**：新增 `primitives-compat.ts`，用命名空间导入 + 候选名列表解析（新名优先、旧名兜底），解析不到就省略该图形。Harness 再改一次名字也不会整块崩。

### 坑 2：和官方品牌插件抢同一个 single 槽位

探针里出现：
```
single slot "sidebar.brand.mark" already has a registration at priority 0 (registered by dsh-yizi-themes)
```
读 `ui-slots` 核心才明白：**single 槽位不允许同优先级的第二个占用者**，且报错文案里的 "registered by X" 指的是**已有占用者**，不是本次注册者（一开始被误导，以为是自己的回调跑了两次）。用计数器（在 `apply()` 与每个 `inject` 回调里埋 `window.__yizi.*++`）证实：`applies=1 / ic=1 / name=1 / hero=1`——自己只注册了一次，那么"已有占用者"就是自己，本次失败的注册者是别人：标准构建**始终**组合 `@deepseek-ai/dsh-client-ui-brand-official`，它注册同样的席位。

再看渲染器：`spec.kind === "single"` 时取 `host.entriesOfSlot(key)[0]`，而排序是按 priority 升序——即**最低优先级渲染**（正是报错文案 "lowest renders" 的含义）。因此本插件以 `priority: -100` 注册：既不与官方撞优先级（不再报错），又确定性地由本插件渲染生效。

> 排查心得：报错文案里的 "registered by" 是**已存在者**。先怀疑"我注册了两次"，用计数器排除后，正确答案是"另有第三方注册了同一席位"。

### 结果

隔离 profile 全绿：启动即激活、侧边栏/hero 品牌与浮动控制条渲染、设置→外观 20 张主题卡 + 自定义品牌输入、切主题与改品牌都即时生效且刷新后保持、控制台零错误、零失败请求。用户正在使用的 desktop profile 全程未被改动（插件始终不在其 `dsh.profile.bundles` 中，桌面版因此仍能启动）。

---

## 2026-08-28 · v0.4.0：适配新版 Harness（移除 client-runtime 包）

### 现象

Harness 升级到 dsh-v0.1.2-alpha.1 后，web 启动报：
`failed to import loader entry 80bfc56c (dsh-yizi-themes): client-modules: require("@deepseek-ai/dsh-client-runtime/client") missed the module table`。

### 根因：官方删除了 `@deepseek-ai/dsh-client-runtime` 包

- Harness 提交 `be531688f3 refactor(client): migrate consumers and remove Runtime`（2026-08-23）把客户端运行时拆解：
  - `defineStore` / `EngineStoreHandle` → 迁入 `@deepseek-ai/dsh-client-store`（同名同签名，`packages/client/store`）；
  - `ClientContext` 类型 → 迁回 `@deepseek-ai/cordis`；
  - 从 `packages/bundle/web-app/cordis.patch.yml` 的 client-modules 表删除 `client-runtime` 行。
- 插件的 `dsh.client.inject` 仍声明 `@deepseek-ai/dsh-client-runtime`，web 前端构建 client-modules 表时没有这个包 → `require` 落到模块表外 → 加载失败。
- 教训：**第三方插件对 Harness 客户端 API 的每个依赖都是"官方扩展面"的候选**——依赖被官方重新组织时，插件要么随官方迁移，要么锁定旧 Harness 版本。

### 修复：迁移到新基线

- `src/client/settings-store.ts`：`import { defineStore, type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client'` → `from '@deepseek-ai/dsh-client-store'`（API 完全一致，零行为变化）。
- `src/client/index.ts`：`ClientContext` 改从 `@deepseek-ai/cordis` 导入（官方 ui-theme 同款写法）。
- `package.json`：inject 列表、peer/dev deps 里 runtime → store。store 是平台基线（`packages/client/web/src/platform.ts` 的 `PLATFORM_MODULES`），官方规范要求放 devDependencies，不进 peerDependencies。
- `prepare.mjs`：browser bundle 的 `external` / `noExternal` 列表同步迁移（此前 runtime 是 external=模块表提供，store 同为表内基线）。

### 验证

- 重新 `prepare.mjs` 构建 → 新 `dist/client.js` 零 runtime 引用、含 `dsh-client-store`。
- `npm pack` → 新 tgz，`dsh plugin remove` + `add` 重装。
- 重启 `dsh web`：插件正常加载，主题切换与自定义品牌可用，服务端日志无错误。
- 浏览器实测：`/plugins/dsh-yizi-themes/client.js` 含 `dsh-client-store`、不含 `dsh-client-runtime`。

### 兼容性边界

- **0.4.0 只适配 dsh-v0.1.2-alpha.1+**（依赖已删除的 runtime 无法在旧版跑）；0.3.x 仍适用于旧版 Harness（rc.8）。

---

## 2026-08-21 · v0.3.1：修复设置输入框 IME 跳字（拼音半路被提交）

### 现象

品牌字样 / 徽章字样 / 新会话标题三个文本框输入中文时，拼音打到一半字母就被提交成实字（"跳字"）。Logo、品牌映射等所有文本输入同样受影响。

### 根因：受控输入框 × 异步写入回声

- 输入框是受控组件：`value` = 行 store 的 `customBrand`，`onChange` → `setCustomBrand` → 每次按键**同步**更新 store（这没问题），但同时发起**异步** `settingsScope.set` 持久化。
- 关键：每次异步写入落定时，设置镜像 `acceptView` 会发布一次快照 → `settingsScope.subscribe` 回调触发 → `readSettings()` 重新读出**刚刚落定的那次写入**的值 → push 进行 store。
- 快速连续输入（IME 拼音组合尤其密集）时，落定的写入值**滞后**于用户当前光标的值 → store 被回填成过期值 → React 把输入框 DOM 强制设回旧值 → 浏览器把进行中的拼音组合**冲掉/提前提交** → 字母"进去了"。
- 也就是说：问题不在"同步 push"（值一致时 React 不会碰 DOM），而在"异步回声把过期值推回来"。

### 修复：在途写入计数（pendingBrandWrites）

- `setCustomBrand` 每次写入前 `pendingBrandWrites += 1`，落定（resolve/reject）后 `-1`；
- `settingsScope.subscribe` 回调在 `pendingBrandWrites > 0` 时**跳过重新采纳**——只做初始加载、外部变更、以及所有写入落定后的采纳。
- 输入路径从此不再有"过期值回填"，IME 组合全程不被打断；所有既有行为（每键实时预览、每键持久化、外部变更采纳）不变。
- 时序细节：写入落定时 `acceptView` **同步**触发订阅回调，此时 `pendingBrandWrites` 尚未递减（`.finally` 在整条 set() promise 落定后才跑），所以该次采纳恰好被跳过；最后的写入落定后 store 里已是用户最新值，无需再采纳。

---

## 2026-08-21 · v0.3.0：适配 rc.8 品牌槽位（升级免疫）

### rc.8 把侧边栏品牌从"单个 SVG"改成了"槽位组合"

- rc.5 侧边栏品牌 = 一个 `BrandWordmark` SVG（`viewBox="0 0 182 24"`，内含鱼形 + "DEEPSEEK" 字样路径 + "HARNESS" 徽章底板）。插件旧版用该 viewBox 指纹定位并注入自定义字样/徽章，靠 MutationObserver 反复应用。
- rc.8 重构为：`button.brand > span.brandIdentity > (span.brandMark [槽 `sidebar.brand.mark`，fallback FishLogo 24] + span.brandName [槽 `sidebar.brand.name`，fallback "DSH Local Build" + commit])`；rail 也是 `span.railMark [槽 `sidebar.brand.mark`]`；hero 则是 `span.fishHitbox [槽 `conversation.hero.brand.mark`，fallback FishLogo 34]` + `span.headlineText`。
- 结论：`182 24` SVG 从侧边栏消失 → 旧版"左上角字样/徽章"定位失效；hero 鱼标 viewBox 仍在 → 自定义 logo 能显示，但整块 DOM 注入在新结构下与槽位渲染冲突，欢迎语也随之失效。

### 方案：注册官方品牌槽位（升级免疫）

- **为什么选槽位**：`sidebar.brand.mark` / `sidebar.brand.name` / `conversation.hero.brand.mark` 是 Harness 为"部署品牌"设计的扩展面（`ui-brand-official` 在 official 构建里正是这么干的）。注册它们 = 官方支持的定制方式，不依赖内部 DOM/哈希类名，**升级只要保留槽位契约就继续工作**。
- **响应式**：新增 `brand-store`（`useSyncExternalStore` 数据源），设置面板改 Logo/字样/徽章时槽位组件实时重渲染。
- **单一槽位必须"占位"**：读 `scoped-slots.tsx` 发现 single 槽位注册后即使返回 null 也不会 fallback 到 shell 的 fallback——所以 mark 槽位在未设 logo 时自行渲染 `FishLogo`（保持默认观感），name 槽位始终渲染 "DEEPSEEK + HARNESS"（恢复 rc.5 的官方观感，rc.8 标准构建默认是 "DSH Local Build" 占位）。
- **hero 欢迎语没有槽位**：`t('hero.headline')` 是 locale 字符串，且 `locale.register` 对已占用的 conversation 命名空间会抛 "already has locale"，无法覆盖。保留 DOM 文本写入，但定位锚点改成**我们自己渲染的 `[data-yizi-hero-mark]`**（其父的 slot 锚点 div → fishHitbox span → nextElementSibling = 标题），不再依赖核心鱼标 viewBox。
- **旧版兜底 + 启动竞态**：无槽位的 rc.5 仍走原 viewBox 注入；槽位激活时 `markModernBrandPath()` 后立即 `cleanupLegacyBrandDom()`（清掉竞态期间产生的旧注入产物，避免重复 logo）。
- **FloatingControls 联动**：新会话浮动按钮的 hero 检测从"鱼标 viewBox"改为同时认 `[data-yizi-hero-mark]`。

### 构建

- `prepare.mjs` 原来硬编码 `C:/Users/Administrator/deepseek-harness/node_modules/tsdown/...`（原作者机器路径），本机为 `E:/mycode/deepseek-harness` → 改为按 `$DSH_HARNESS` → 已知检出路径查找，找不到报错并给指引。

---

## 2026-08-16 · v0.2.4：品牌色真正跟随 + 品牌映射按下

### 品牌色覆盖表为什么一直没生效

- 用户反馈"Deep diving…"执行状态没跟随主题色。排查发现：注入的 `brand-overrides.css` 用的选择器是 **CSS-Module 字面类名**（`.turnStatus`、`.dsw-yizi-theme-enabled` 前缀等），但应用内类名是构建哈希的（如 `Md3f7G_turnStatus`），且 `dsw-yizi-theme-enabled` 这个启用类**从来没有任何代码添加**——整份表在干净 Harness 上是死代码。
- 机器 1 之所以"生效"，是因为其核心 CSS Module 被早期 patch 直接改过（工作区残留）。
- **教训**：插件注入的 CSS 必须锚定**稳定 DOM 钩子**（data 属性 / role / SVG viewBox 指纹），不能依赖哈希类名。
- 重写后选择器：`[data-chat-flow=""] [role="status"][aria-live="polite"]`（执行状态）、`[data-state="ongoing"]`（状态点）、`span:has(> svg[viewBox…][width=34])`（hero 鱼标+标题）、`button:has(> svg[viewBox="0 0 182 24"])`（侧边栏品牌）、`button:has(> svg[…][width=24])`（收起 rail）。

### 品牌映射功能按下（默认禁用）

- 用户反馈：开启映射后整个界面（设置面板标签、输入框）的 DeepSeek 相关词全被替换，打字都会被改写——这不是功能初衷。
- 反思结论：**基于关键词的全局替换在任何作用域都站不住**——UI 文案是固定说明、输入是用户真实内容、提示词不能骗模型、输出替换会误导用户（问 DeepSeek 答出来的却是别的品牌）。
- 处理：默认禁用（默认值本就是 false），并加**可编辑元素保护**（永不改写 input/textarea/contenteditable 内的文本）；待明确语义后再另行设计。

---

## 2026-08-16 · v0.2.1–v0.2.3：兼容干净 Harness

### 真相澄清：风格主题本就不在官方源码里

- 此前一直以为"风格主题"是 Harness 官方功能，直到在第二台机器（干净源码 / npm 发布的 rc.5）上测试：换主题报 `runtime.setThemeId is not a function`。
- 用户指正后确认：**`setThemeId` / `theme` 设置字段 / 主题注册表 / `body.theme-<id>` 切换，是早期 v1 patch 方案给核心加的**，官方源码没有；机器 1 能用是因为还残留着 patch。
- 结论：插件不能依赖核心的这套 API，必须自己实现。

### 风格主题后端（theme-backend.ts）

- 统一抽象，自动探测核心能力：
  - **核心路径**（有 `setThemeId`，如打过 patch / 含该特性的构建）：读写走核心，持久化到 `settings.yaml`，class 由核心 presenter 切换；
  - **插件路径**（干净 Harness）：主题 id 存 `localStorage`（`dsh-yizi-themes:themeId`），自行切换 `body.theme-<id>`，本地事件发射器通知刷新；明暗仍走核心 preference。
- `getTheme` 快照做了身份缓存（useSyncExternalStore 要求快照稳定）。
- jsdom 18 项测试覆盖两条路径：持久化、class 应用/切换/清除、通知、快照稳定、preference 联动、reassert。

### 0.2.2 回归：设置行消失

- 症状：头部主题切换正常，但设置 → 通用 的外观设置项整体消失。
- 报错：`ReferenceError: setThemeId is not defined at injected(...)`。
- 根因：重构后端时漏改 `injected()`，仍引用已不存在的裸变量 `setThemeId`（tsdown 不做类型检查，运行时才炸）。
- 教训：**给构建补了 tsc 类型检查**（`tsconfig.json`），还顺手修掉 3 个潜在类型错误（`ThemeDefinition` 导入源、`defaultEntry` 缺 `desc`、主题下拉渲染不存在的 `desc`）。

### 0.2.3：设置面板去重

- 用户反馈设置面板出现两组相同的外观（原生 + 插件各一组明暗模式块）。
- 删除插件外观行里重复的明暗模式块，直接从"主题"网格开始（原生行或右上角切换已覆盖明暗）。

---

## 2026-08-16 · v0.2.0 收尾

### 品牌自定义闭环

- **持久化打通的关键发现**：设置一直写不进去，排查到根因不在插件，而在 Harness 的 api-proxy —— `packages/host/apiproxy/src/api-proxy.ts` 用**硬编码白名单**决定浏览器可读写哪些 settings 命名空间（`locale` / `permission` / `ui-conversation` / `ui-theme` 等）。"新增一个 Settings 注册并不会让它可远程读写"是刻意设计（源码注释明说 plugin 自暴露是 deferred work）。按"不改 Harness 源码"的约束，最终方案是把自定义品牌数据写入**核心 `ui-theme` 命名空间的 `customBrand` 字段**（schema 本来就带该字段，只是 core 界面从未使用），用 `decode` 把 `{preference, theme, customBrand}` 窄化为品牌部分。
- **输入框不可编辑的真相**：受控输入框读行 store，而 store 只在 `theme/change` 时同步；命名空间未注册又让每次写 RPC 被拒 → 值永远弹回。修复 = host 端不再注册自己的命名空间，客户端写入白名单内的 `ui-theme`，且每次编辑后立即把新值推进 store。

### React 安全 DOM 注入（最重要的教训）

- **事故**：侧边栏折叠后重新展开 → 整个侧边栏空白。
- **根因**：此前用 `element.replaceWith(...)` 直接替换 React 渲染的节点。React 的 fiber 仍持有原节点引用，折叠时整个按钮卸载没事，展开时 React 要逐个 `removeChild` 已被摘除的节点 → `NotFoundError` → React 提交阶段崩溃。
- **铁律**：**绝不摘除/移动/删除 React 管理的 DOM 节点**。现在的模式：
  1. 用内联 `style.display='none'` 隐藏原节点（这些组件从不传 style prop，React 不会改回去）；
  2. 把自己的节点作为**兄弟**插入原节点之后（React 不管理它创建的节点，卸载时随子树消失）；
  3. **孤儿清理**：原节点被 React 移除后，下一轮自动清掉遗留兄弟；重新挂载后自动收敛。
  4. 按目标做内容签名，配置变更时只重建自己的节点（幂等、不抖动）。

### 新会话浮动控件

- 会话头在 blank 态整体隐藏，槽位按钮随之消失；hero 态又没有可用的顶栏槽位。
- 方案：第二个 React root（`react-dom/client`，平台模块表内），`position:fixed` 右上角，渲染同一个 `HeaderControls`；用 **hero 鱼标是否存在于 DOM** 作为"空白新会话"信号控制显隐（hero 存在 ⇔ 头部隐藏 ⇔ 显示浮动按钮；进入会话后 hero 卸载 ⇔ 隐藏，让位给槽位按钮，两组永不共存）。

### 其他

- 主题按钮图标：平台图标集（62 个）无调色板类图标，自绘 `PaletteIcon`（16×16、`currentColor` 单色、描边调色盘 + 4 个颜料点）。
- hero 图标复用 logo 设置，删除独立 heroIcon 字段（类型、默认值、UI、文案全链路清理）。
- Logo 输入框下加主题色替换提示（浅色小字）。

---

## 2026-08-16 · v0.1.0 初始构建

### 从 patch 覆盖 → 标准 Cordis 插件

- 早期方案是 `patch/` 覆盖 Harness 源码 + 安装脚本（`install.sh` / `install.ps1` / `MANIFEST.json`），第三方评审建议不要改 Harness 包源码，转为标准 Cordis 插件。
- 插件 = host（Node 半区 `dist/index.js`）+ 浏览器半区（`dist/client.js`）。
- **浏览器 bundle 的三明治封装**（对齐官方 clientBundle 预设）：
  ```
  banner: window.__ModuleLoader__.load({ id: 'dsh-yizi-themes', factory: (require) => {
  intro:  var module = { exports: {} }; var exports = module.exports;
  footer: return module.exports; } });
  ```
- **平台模块表**（`packages/client/web/src/platform.ts`）：client bundle 的 `require()` 只能落在表内（react / react-dom / primitives / runtime / slots …），否则 loader 报 "missed the module table"。为此移除了 clsx，自写 `cx()`。
- **pack 陷阱**：`pnpm pack` 对 workspace 协议报错，用 `npm pack`（产出正确的 `package/dist/` 布局）。
- **同版本 tgz 陷阱**：同版本 tgz 内容变了再 `add`，pnpm 报 `Already up to date` 不更新 —— 必须 `remove` 后再 `add`（升版本号则单次 `add` 即可）。
- 头部按钮：注册到 `conversation.session.header.actions` 后发现它在标题旁（左侧），而会话日志按钮在 `header.utilities`（最右）——槽位是两套，最终改到 utilities。
- 明暗切换单向：接入 `useSyncExternalStore` + `theme/change` 订阅后双向可用。

### 主题机制

- 19 个主题以 `body.theme-<id>` 的 `--dsw-alias-*` 覆盖注入（`src/client/themes.ts` 由 `scripts/gen-themes.mjs` 从 CSS 生成 TS 字符串），与 core 注册的主题 id 一一对应。
- 明暗双套由 `body[data-ds-dark-theme]` 切换。

---

## 踩坑清单（速查）

| 现象 | 根因 | 解法 |
|---|---|---|
| 设置不持久化 / 输入框不可编辑 | api-proxy 白名单外命名空间被拒 | 写入核心 `ui-theme.customBrand` |
| 侧边栏折叠后展开空白 | replaceWith 摘除 React 节点 → removeChild 崩溃 | 隐藏原节点 + 兄弟插入 + 孤儿清理 |
| 同版本 add 不更新 | pnpm 认为依赖已满足 | remove → add，或升版本号 |
| client bundle 报 requires 超出平台表 | 依赖了表外模块（如 clsx） | 内联或自实现 |
| `exports is not defined` | client bundle 缺 `intro` 三明治 | 补 intro 声明 |
| locale 命名空间冲突 | 与 core 共用 `settings.theme` | 改用 `yizi.theme` |