dsh-theme-holo 0.0.0-stage → 1.0.8

package/CHANGELOG.md

@@ -0,0 +1,1091 @@
+# 更新记录
+
+## 1.0.8 — 2026-11-14
+
+### 变更
+
+- **npm 包瘦身：35.6 MB → 约 21 MB（−14.4 MB）。**
+
+  1.0.7 的包里混进了三类不该发布的东西：
+
+  | 混进来的 | 体积 | 为什么不该发 |
+  |---|---|---|
+  | `tavern/lesson/assets/` | 12.4 MB / 186 文件 | 酒馆素材的设计是「点下载酒馆才拉」，而且它只是**半套** —— `tavern/assets/holo.glb` 并不在包里，所以用户照样要下载，下载下来的 12.4 MB 与包里**完全重复** |
+  | `素材/` 里的原件与设计稿 | 1.9 MB | `holo.png`（未修白边）、`竖版封面.png`、`横板封面.jpg`、`logo.png`、`小麦.png`、`图标.jpg`、`赫萝疑惑.wav` —— `.gitignore` 明确排除的加工中间产物 |
+  | `素材/文字/`、`素材/文字浮雕/` | 0.1 MB | 字体切图，不参与渲染 |
+
+  根因：`files` 里写的是**目录名**（`tavern/lesson`、`素材`），npm 对目录是**递归全收**，
+  而 `.gitignore` 的排除对 `files` 已包含的路径**不生效**。
+
+  现在 `files` 改成精确列：`tavern/lesson` 拆成 `index.html` + `favicon.svg` + `js` + `css`，
+  `素材` 拆成三个运行时文件 + `动画/`。顺带把 `tavern/lesson/_test_stage_full.html`
+  这个测试页面也排除掉了。
+
+- **README 的版本徽章从 1.0.6 修正为 1.0.8**（它此前一直落后于实际版本）。
+
+## 1.0.7 — 2026-11-14
+
+### 新增
+
+- **会话头像：给会话双方各配一张头像，消息像好友聊天一样左右分列。**
+  设置卡片新增「会话头像」一节 —— 总开关 + 「我」/「赫萝」各一个上传按钮（带预览）+
+  助手头像间隔滑块。不导入图就画内置默认头像（你的那侧是人像，她那侧是**一穗麦子**）；
+  关掉开关，会话立刻逐字节回到原样（节点、行标记、html 属性全部撤掉）。
+
+  **宿主半**新增 `/holo-avatar/<side>` 路由族：`GET`/`HEAD` 取图、`POST` 导入 raw body、
+  `DELETE` 清除。只认 `user` / `ai` 两个 side（路径段当白名单查 ⇒ 路径穿越不可能），
+  MIME 白名单 JPG/PNG/WebP，单张上限 8 MB，原子落盘（`.tmp` + rename）。
+
+  图落在 **`~/.dsh-theme-holo/avatars/`，不在插件目录**：赫萝原有的资源全部随包发布、
+  由版本管理，而头像是用户自己导入的 —— npm 更新会重装插件目录，放里面等于每次升级
+  把用户的图一起清掉。
+
+  **浏览器半是纯 DOM 装饰**：给三类消息行（`user` / `steering` / `assistant-step`）补一张脸，
+  把行改成两列 grid，左右由 CSS 列决定。**不注册 `conversation.chat.node` 的渲染器** ——
+  注册同名 key 是**替换**官方消息卡片，等于把宿主的卡片整个接过来养，升级一次崩一次。
+
+  外观频率：用户侧连续消息只显示第一张；助手侧每回合第一张 + 每「助手头像间隔」条
+  可见流条目再露一次（默认 6，范围 1–30），长回合不会「一张脸滚出屏幕后整页再没有」。
+
+  导入走**裁切取景弹窗**（与 wallpaper-engine 原版同一套交互）：选好图先弹一个方形
+  取景框，**拖动平移 + 滚轮或滑块缩放**，框里那一块按原图分辨率裁出来，再缩到 512px 上传。
+  `zoom = 1` 时短边刚好铺满（再小会露白），平移边界是「图不能露出空白」。
+  「取消」= 什么都没发生（不上传、不改设置）。
+
+  几何只有一份实现（`avatarCropGeometry`）：弹窗渲染与真正裁切都读它 ——
+  「屏上看到的那一块」与「切出来那一块」因此必然逐像素对应，不会因为两处各算一遍而漂。
+
+  拖动期间走命令式 DOM（`applyCropLive`），松手才收敛进 React 状态：拖一次是上百个
+  `pointermove`，每个都整卡重渲染会把拖动拖成幻灯片。
+
+- **`_test_avatar.mjs`（112 项断言）**：路由族真跑（POST/GET/HEAD/DELETE、415/413/405/400、
+  换图即清兄弟、两侧互不干扰、收尾注销），加浏览器半 × 宿主半的跨文件对账
+  （路由前缀、side 名单、开关属性与 CSS 门控同名、四个设置键、三种 kind、dispose 路径、
+  裁切链的函数与几何口径）。落盘目录在 import 前指向临时 HOME，**绝不碰真实用户头像**。
+
+- **赫萝的黄昏酒馆：改成了「插件完全不带、点了才下」。**
+  此前是「代码随插件走、素材按需下载」，现在**整个 `tavern/` 都不进包**——
+  `package.json` 的 `files` 不再包含 `tavern/lesson` 与 `tavern/vendor`。
+  装完插件体积**不增加**，用户在设置卡片点「下载酒馆（约 4.9 MB）」才拉取。
+
+  **素材独立成一个仓库**：[`1015677515/holo-tavern-assets`](https://github.com/1015677515/holo-tavern-assets)，
+  Release `v1.0.0` 挂 `tavern-assets.tar.gz`（4.91 MB，62 个文件）。
+  素材与插件版本解耦，改素材不必发插件版本。
+
+  **下载由 host 侧完成**，不是浏览器：浏览器拿到的字节存不进插件目录
+  （前端没有文件系统权限）；host 有 `node:fs`，能直接写进 `tavern/`，
+  静态路由立刻就能服务这些文件。新增端点 `POST /holo-tavern-install`。
+
+  **为什么打包用 tar.gz 而不是 zip**：Node 标准库有 `zlib`（gunzip），
+  但没有 zip 解析器。tar 格式简单、能手工稳妥解析，本插件因此保持零第三方依赖。
+  解包逻辑抽在 `tavern-kit/tar.mjs`，带 zip-slip 防护（拒 `..`、绝对路径、
+  NUL 字节、不在 `tavern/` 下的条目）。
+
+- **`scripts/pack-tavern.mjs`**：改完 `tavern/` 后一键重新打包并上传 Release。
+  `node scripts/pack-tavern.mjs --upload`。不传 `--upload` 就只出包。
+
+### 性能
+
+- **会话头像改成「只装饰可见行」**（`IntersectionObserver`，2026-11-09）。
+
+  此前 `sync()` 一次性走全文档：`querySelectorAll` 拿到所有消息行，然后**逐行**
+  `createElement` + `insertBefore` + 改两列 grid，最后再全文档算一次分组。
+  代价与会话长度成正比 —— 打开一个几百条消息的会话，就是几百次 DOM 插入和
+  相应布局重算，全部落在**同一个同步任务**里。用户反馈的「整页点不动、窗口
+  能拖但内容不刷新」正是这种秒级主线程占用的表现（渲染进程主线程被占死，
+  合成器还活着 ⇒ 能拖窗口、拖了不重绘、点击排不上队）。
+
+  现在：`watchAll()` 只做 N 次 `observe()`（不碰 DOM 结构），真正建节点的只有
+  进入视口的那几十行；`rootMargin: '240px 0px'` 是为了滚到跟前时脸已经在那儿，
+  不会看到「突然冒出来」。
+
+  ⚠ **分组逻辑必须一起改**：原来 `applyGrouping` 用「这行有没有头像节点」判断
+  要不要跳过，改成按需装饰之后视口外的行全都没有节点 —— 那样会让「连续同侧」
+  断在错误位置（用户侧第二条已装饰、第一条未装饰时，第二条会被误判成段首而
+  多贴一张脸）。现在分组**只按行算**（`data-chat-flow-kind`），节点只决定
+  「结论写在哪」：没节点时把 `cont` 结论暂存到 `data-holo-avatar-cont-pending`，
+  `decorateRow` 建节点时照抄并抹掉。
+
+  没有 `IntersectionObserver` 的环境（老浏览器 / 无头沙箱）退回**全量装饰**，
+  慢但不缺功能 —— 宁可慢，也不要「什么都不显示」。
+
+  新插入的行也不再立即装饰：只登记给观察器，下一帧由它按可见性决定。
+
+  测试从 112 项加到 **130 项**（新增 18 项钉住这套结构：sweep 必须彻底退场、
+  分组不许再看节点、stop 必须清全部登记行、缺 IO 必须降级）。
+
+### 修复
+
+- **【严重】主题自己的 9 个素材文件从来没进过仓库**（2026-11-13 补）。
+
+  `cbc2cd1`（「素材搬到独立仓库 holo-tavern-assets」）把 `素材/` 下那 9 个
+  「路径被双重转义」的条目一起删掉了 —— 但**删掉之后没有用正确路径重做**，
+  而 `holo-tavern-assets` 里只有 `tavern/` 子树，不包含主题自己的 `素材/`。
+
+  后果只在**别人机器上**出现：`package.json` 的 `files` 里写着 `素材`，可仓库里是空的
+  ⇒ 装完插件后 `/holo-theme/link/` 与 `/holo-theme/anime/` 全 404 ⇒
+  **右栏待机动画六段全不显示、鲸鱼联动的角色图找不到**。开发机上素材一直躺在本地，
+  所以这个问题藏了很久。
+
+  现在按 UTF-8 原字节路径重新入库 9 个文件（3 个 png/wav + 6 个 webm，共 13.8 MB）。
+
+- **待机画面的透明点击层吃掉了顶栏按钮**（照 PR #2 的方案重做，保留 `holo` 命名）。
+
+  原先铺一个 `fixed` + `pointer-events:auto` 的透明块在画面上，矩形内所有点击都被它
+  吃掉 —— 右栏自己的标签栏与分屏 / 全屏 / 关闭按钮都在它下面，按不动。当时靠
+  「顶部内缩 70px」避开，那是回避症状：右栏换内容就复发，而且那 70px 里的她跟着点不到。
+
+  改成**坐标矩形 + document 捕获监听**，并忽略任何交互元素（`button` / `input` /
+  `[role=button]` / 本插件自己的浮层）⇒ 宿主的控件永远赢，点空白处才算点她。
+  另外补了两个守卫：拖选文字之后的 click 不算、modal 打开时不算。
+
+  代价：交互元素是**硬编码白名单**，宿主换控件要跟着补。但原先那个 70px 同样是硬编码，
+  且脆弱得多。
+
+- **全屏右栏时待机画面不退下**。全屏时右栏铺在整个会话上，那里清 fill 会让会话从起始页
+  透出来、608px 的画面变成中间一条被裁的窄条。现在 `gateOpen()` 里认
+  `data-sidebar-right-panel="fullscreen"`，全屏一律退下。
+
+- **探头赫萝换页后停在旧位置**。原先靠 0.9 秒的 `setInterval` 慢慢纠正，短会话里就是
+  一整秒的错位。改成「找不到输入框时盯住 DOM」（`MutationObserver`），输入框一出现就
+  在下一帧归位；回调第一句早退（有输入框时什么都不做），所以流式输出期间只是一次布尔判断。
+
+- **拖动侧栏 / 输入框会误触发她的语音**。指针抬起处可能正好落在她身上，浏览器接着派发
+  一次 click。加 `pressedHere` 标志：由她自己的 `pointerdown` 置位、被任何别处的
+  `pointerdown` 清零（document 捕获阶段先于她的监听），只有真正按在她身上开始的点击才算。
+
+- **字幕气泡没贴在触发它的控件旁边**，以及**对话框 / 全屏时照样浮在上面**。
+
+  气泡现在有三级落点：她在屏幕上 ⇒ 右肩；她不在 / 被关掉 ⇒ 贴着触发控件（控件在左半边
+  就放右侧，否则放它下方，下方装不下就放上方）；都没有 ⇒ 窗口顶部中央。
+  `announce()` 多带一个 `from`（元素或 rect），鲸鱼 / 便笺 / 待机画面三个来源各自传进来。
+
+  新增 `onChatPage()` 闸门：右栏全屏、有可见 dialog、她开着但不可见 —— 三种情况一律不出，
+  已经挂着的那条也随切页收起。
+
+- **档案卡与账号那一行对不齐**。原先写死 `272x153` / `left 10` / `bottom 74`，在宽窗口或
+  英文界面下左右缘、宽度、与菜单的间距全对不上。现在每次显示都量账号行：
+  宽 = 行宽（不小于 208）、高 = 宽 × 9:16、底边 = 行顶 + 6px，头像跟着上移 38px。
+  同时把「账号菜单」的 `aria-label` 补上英文 `Account menu`，并统一到一个常量
+  `ACCOUNT_ROW`（原先三处各写一遍，英文界面下有一半失效）。
+  菜单已展开时不再弹卡片（那会盖住菜单第一项）。
+
+- **tar 解包的静默丢文件。** 初版解析器直接对 size 字段调 `trim()`，
+  但 tar 的每个字段都以 NUL 结尾，`parseInt("00001868424\0", 8)` 会在 NUL 处停下、
+  读成 `1`。后果是「包解开了，但只出 1 个文件、其余全丢」，且不报错。
+  现在先剥 NUL 再解析，并有 `_test_tar.mjs`（33 项断言）用真实包守住：
+  断言条目数必须是 62、`holo.glb` 必须是 1,868,424 B、glb/wav/webp 的文件头正确。
+
+### 说明
+
+- 未下载素材时，「前往黄昏酒馆」保持**禁用**，不会打开一个空白舞台。
+- 已知边界：宿主是否允许插件运行时往自身目录写文件，**尚未实机验证**。
+  若被沙箱拦下，下载会返回 500 并如实报错，不会假装成功。
+
+### 测试
+
+- `_test_tar.mjs` 新增 33 项断言（解真实包 + 路径安全 6 例）。
+- 酒馆侧另有一套：`_test_voice`（90）、`_test_stage_v2`（53）、
+  `_test_stage_reentry`（24）、`_test_cart`（14）等，合计 500+ 项。
+
+  **本版是骨架**：下载分支还没接真实地址（Release 附件尚未上传），
+  点了会如实说明「还没上传」，不伪造进度、不假装成功。
+- **`/holo-tavern/` 静态路由**。与前三条路由不同，这条**不是逐文件白名单**
+  ——酒馆有 25+ 文件且会随场景变动，逐个列举不现实。改为**目录级白名单**：
+  只放行 `tavern/lesson`、`tavern/vendor`、`tavern/assets` 三棵子树，
+  仍然经过 `resolveIn` 做穿越防护，另加 `TAVERN_DENY` 挡住压缩备份目录
+  （`_png_backup`）、点文件与 `..`。裸路径 `/holo-tavern` 与
+  `/holo-tavern/` 都落到 `lesson/index.html`。
+
+### 变更
+
+- **`MIME` 表补全**：原先只有图片/音视频/woff2，缺 `.html`、`.js`、`.css`、
+  `.json`、`.glb`、`.woff`、`.ttf`。酒馆是完整的网页应用，缺这几项会让
+  `index.html` 以 `application/octet-stream` 下发、浏览器直接下载而不是渲染。
+  补全后 `index.html` 是 `text/html; charset=utf-8`，`holo.glb` 是
+  `model/gltf-binary`。
+
+### 测试
+
+- 新增三套，共 **80 项断言**：
+  - `tavern_entry_test`（22 项）：入口结构、按钮文案、未装时禁用「前往」、
+    **骨架阶段不伪造下载成功**、状态不存双份。
+  - `tavern_route_test`（38 项）：`tavernAllowed` 的放行与拦截边界——
+    11 条该放行、15 条该挡住（穿越、备份、点文件、非允许目录）。
+  - `tavern_e2e_test`（20 项）：**真起 HTTP 服务**打请求，验证 6 个资源
+    返回 200、4 类穿越返回 404、POST 返回 405。
+    穿越用例必须用 `http.request` 发原始 path —— `fetch()` 会在发出前把
+    `/holo-tavern/../client.js` 规范化成 `/client.js`，那样测不到 handler。
+
+## 1.0.6 — 2026-10-27
+
+### 新增
+
+- **羊皮纸便笺（记录板）**：右下角一枚麦穗环徽章，点开是一张能打字、能粘图的便笺。
+  文字存 `localStorage`（400ms 防抖），**粘贴的图片存 IndexedDB**——图片体积大，
+  `localStorage` 装不下几张就超限。徽章可拖、面板可拖可调大小。
+  整棵子树走 `data-holo-planner*` 而不给 id：深色模式那条隐藏规则按 `[id^="holo-"]` 匹配，
+  用 id 会被一起收掉。面板刻意用 `role="region"` 而非 `dialog`：探头的状态机把任何
+  `[role=dialog]` 当作弹窗打开而让位，用 `dialog` 会让探头在便笺开着时永远缩着。
+- **便笺的第二个入口**：设置里「简化写字板按钮」开启后，徽章隐藏，改在顶部工具条
+  「提示词」左边放一个「写字板」按钮。按钮挂在与 ErrorNotes 同一个 slot
+  （`conversation.session.header.utilities`），`order: 20` 小于它的 `30`，所以排在左边。
+- **语音与翻译气泡**：九条台词接到按钮、探头、挂件、便笺徽章与待机画面，每条都在探头
+  右上角浮出中文译文。按钮类滞留「音频时长 + 3 秒」，触发类滞留「固定时长 + 3 秒」，
+  点气泡立即消失。新增七条语音素材（H013/H053/H112/H182/H193/H203 与 H015 之外的切片）。
+- **点右栏待机画面里的立绘应答一句**（H013）。热区取画面宽度的 608×1080 比例、上部 62%，
+  是一块固定位置的矩形，**不按角色轮廓描**——六段待机动画可替换、她站的位置各不相同，
+  描轮廓在多数片子上会判错。
+- **气泡跟着探头走**：显示期间每帧重算锚点，拖她、她倾斜或点头时气泡都跟着。
+
+### 修复
+
+- **打开图片后，点右上角 ✕ 反而播了赫萝的语音。** 图片预览是 `ImageLightbox`——
+  `createPortal` 到 `<body>` 的**文档级浮层**（`role="dialog" aria-modal="true"`），
+  它**不替换右栏开始页**。待机画面的点击热区浮在内容之上又只按「开始页在不在」判断，
+  于是盖住浮层、把 ✕ 的点击吃掉了。现在热区在文档出现
+  `[role="dialog"]` / `[aria-modal="true"]` 时立即隐藏，点击时再兜底确认一次。
+  判断**只认 dialog 与 aria-modal**，刻意不查 `role="menu"` / `role="listbox"`：
+  下拉打开时她本就该能点，查了会无谓让路。
+- **点立绘有声音、没字幕气泡。** `createScene` 的签名改成了 `createScene(announce)`，
+  但 apply 里的调用点没跟着传参，`announce` 是 `undefined` 被类型判断挡掉。
+  现在传一个惰性闭包——该 effect 注册早于 voice-cue effect，直接传当时还是 `null`。
+- **记表板压在探头之上**：记录板容器 `z-index` 由 `2147482810` 提到 `2147482998`。
+- **侧栏「新会话」折叠时点不到。** 折叠态只有图标、没有可见文字，按文本匹配会失效；
+  新增 `ariaLabels` 字段并按 `aria-label` 回退匹配。「打开侧边栏」的 `aria-label`
+  实际是「打开右侧边栏」，与提示文字不同，两条都登记。
+- **开始页的快捷卡片点不动，一点就播语音。** 待机画面的点击热区浮在内容之上，
+  高度按「栏宽 × 1080/608 × 62%」算，与卡片位置无关：底边正好压在
+  「工作区文件」「新建终端」等按钮上，点击被热区吃掉，落到 `onHit` 播了 H013。
+  因为高度跟着**栏宽**走，窗口一宽一窄，被吞掉的卡片数量还会变。
+  现在每次 `place()` 都实时读第一张 `[data-sidebar-right-guide-entry]` 的顶边，
+  把热区底边卡在它上方 6px：卡片恢复可点，热区也随卡片位置动态伸缩
+  （开始页的卡片是垂直居中的，窗口高度一变它们就整体移动，所以必须实时量）。
+  没有卡片时仍按原来的 62% 走；栏高不够时高度归零而非负值。
+
+### 其它
+
+- `index.js` 白名单由 18 项增至 27 项（`assets/` 18、`素材/` 3、`素材/动画/` 6）。
+- **翻译气泡改羊皮纸板样式**：气泡从「径向高光 + 158° 渐变 + 双层外环 + 指向尾巴 +
+  圆角 9」改为「纸色填充 + 上下齿边 + 两端麦穗 + 圆角 6」，与宣传片字幕板一致。
+  纯 CSS，未动结构与台词逻辑。
+- 测试：`scene_test` 70 → 92、`voice_bubble_test` 42 → 73、`planner_test` 57 → 88、
+  `src_integrity_test` 10 → 18（新增「签名与调用点一致」护栏，专防改了签名漏改调用点，
+  上面第二条 bug 正是这一类，原先两套测试都查不到）。
+
+## 1.0.5 — 2026-10-25
+
+### 新增
+
+- **`screenshots.json`**：为插件市场声明四张展示图（整页概览、六组待机动画拼图、开场动画
+  末帧、侧栏麦田特写）。市场规则要求截图声明在插件自己的仓库里，路径相对、不能以 `/` 开头、
+  不能含 `..`；不声明则市场会从 README 自动抽图。之后换图只要推仓库，不用再提 PR。
+- **`assets/icon-market.jpg`（256×256）**：插件市场卡片图标。原来的 `assets/icon.jpg` 只有
+  64×64，市场按约 96px 显示会被放大发糊。源图没有更高清的版本，这里是 4 倍 Lanczos 上采样
+  加轻量锐化（半径 2、强度 80%），不新增细节，只是把硬边磨顺。`package.json` 的 `icon`
+  字段同步指向新文件。
+
+### 修复
+
+- **README 有两处声明与代码不符，已改正。** 横幅 alt 文本和设计原则第 2 条原先写「装饰性
+  组件**全部可以单独关掉**」，但设置页实际只有六个开关（开场动画、偷看的她、探头语音、
+  黑夜模式、右栏待机动画、浮动字标显隐）；**动态档案卡、日志标签、侧栏麦田**三项没有开关。
+  现在如实写明哪六项可关、哪三项常驻以及常驻的原因（纯展示层、不拦截点击、不占布局）。
+  中英双语同时改。这一条会被插件市场的人工评审对着代码逐条核，夸大是打回的主要原因。
+
+## 1.0.4 — 2026-10-25
+
+### 新增
+
+- **右侧待机动画多了「关闭动画」选项。** 设置页那一栏现在有七项：前六项仍是六段动画的
+  文件名，最后一项 `关闭动画` 是关掉的开关。选中后右侧栏开始页不再显示待机画面，进入
+  开始页时连视频都不加载（不占解码器），也不用重启 —— 选回任意一段立即恢复。
+
+### 修复
+
+- **「关闭动画」原本只能单向。** `scene-change` 的监听原先注册在图层入场时，一旦关掉，
+  图层被撤、监听随之下线，再选回某个动画就没有人接手，必须重启才生效。现在监听挂在图层
+  的整个生命周期上，关闭与恢复都可以当场来回切。
+
+## 1.0.3 — 2026-10-26
+
+### 修复
+
+- **`LICENSE` 被 GitHub 识别成 `NOASSERTION`。** 原因不是缺少许可证，而是 MIT 正文前
+  插了一段「适用范围（Scope）」把标准模板切断，GitHub 的 licensee 模板比对失败，于是
+  落到 `NOASSERTION`。现在 `LICENSE` 恢复为纯 MIT 模板（21 行），GitHub 徽章会显示
+  `MIT license`，依赖图与合规扫描也能正确归类；那段适用范围挪到独立的 `NOTICE.md`。
+  法律效力原本就与 MIT 一致，变的只是机器可识别性。
+
+### 新增
+
+- **`INSTALL.md`**：环境要求表、三种安装方式（`github:` 应用内安装 / 本地 `link:` +
+  `mklink /J`（含 Linux、macOS 的 `ln -s`）/ ZIP 解压）、装好之后的样子、自检：确认装对了
+  （三处特征 + 两种典型失败模式）、卸载（含清理 `localStorage` 与挂件目录）、常见问题。
+- **README「界面预览」节**：一张 1600×862 的真实运行截图（余额、今日消耗、账号名已打码），
+  下附 5 行「位置 → 看到什么」对照表。
+- **README「环境要求」节**：DSH `>=0.2.0-rc.1 <0.3.0-0`、Node `>=22`、三平台、约 16 MB、
+  无第三方依赖、安装需联网运行时不需要，并附 `package.json` 的 `engines` / `compatibility` 片段。
+- **README「出处声明」节**：本项目由 [holoiallo](https://github.com/holoiallo) 最初创立，
+  [1015677515](https://github.com/1015677515) 完善更新，由 DeepSeek Harness 的 AI 智能体
+  协助开发；素材来自网络二创，仅供学习交流。中英双语。
+- **README「相关链接」节**：INSTALL / CHANGELOG / NOTICE / Issues / Releases。
+- **README 英文节**（精简版）：Preview、Features 十一条、Requirements、Install、Credits、Links。
+  不做全文双语，只做一份能读懂「这是什么、怎么装」的摘要。
+- **`NOTICE.md`**：中英双语说明 MIT 只覆盖源代码，不覆盖 `assets/` 与 `素材/` 的音视频图像；
+  素材不主张权利、有异议提出即移除、不得商用。
+- **配图 `docs/gui-overview.png`**（1600×862）。
+
+### 变更
+
+- **`package.json`**：版本 `1.0.2` → `1.0.3`；`files` 补入 `INSTALL.md`、`NOTICE.md`（现 12 项）；
+  `engines` 增加 `"dsh": ">=0.2.0-rc.1 <0.3.0-0"`；新增 `dsh.compatibility`（含 `dshReleases`
+  逐版本兼容表，写法与 `dsh-cost-meter` 等官方插件一致）。
+- **README 安装节重写**：从 60 行压到 20 行，先给 `github:1015677515/dsh-theme-holo` 一行安装，
+  再指向 `INSTALL.md`；`github:` 这条标了【未验证】，解析失败请回退本地安装。
+- **README 目录表**补入界面预览、环境要求、出处声明、相关链接、English 五条。
+
+### 说明
+
+- 本轮**没有**增加「它会动你的哪些文件」节与「运行时验证记录」表——按决定暂时跳过。
+
+## 1.0.2 — 2026-10-25
+
+### 文档
+
+- **README 首屏换成主题配色的横幅图。** GitHub 会剥掉 README 里所有 `style` 与 `color`
+  （渲染器跑 `github/html-pipeline` 的消毒白名单，里面没有 `style`），页面底色与文字颜色
+  改不了，能承载配色的只有图片。因此首屏改为一张 1800×600 的横幅：米黄 `#FBF7EF` 底、
+  深米色 `#DCC9A8` 双线圆角外框、logo、金色 `#A2701F` 分隔线、三行正文。只做浅色一版。
+- 目录改用两列表格（章节 / 功能详解的十个小节），并注明表格底色由 GitHub 主题决定。
+- 新增配图 `docs/readme-banner.png`。
+- 新增 FAQ「README 页面的底色和文字颜色，为什么不能也做成主题色？」，附消毒器实测对照表。
+- 修正版本徽章（1.0.1 → 1.0.2），与 `package.json` 对齐。
+
+## 1.0.1 — 2026-10-25
+
+### 修复
+
+- **首次安装不再落在黑夜模式。** DSH 的外观偏好出厂值是「跟随系统」，系统为深色的机器一装好
+  就解析成深色，再叠上「星夜麦田」，容易被误读成「装了插件就被切成黑夜模式」。现在插件在
+  **首次运行**时若发现宿主已解析为深色，会通过主题服务把外观偏好改回 `light` 一次，并把
+  `localStorage['dsh-theme-holo.dark-defaulted']` 置为 `1` 落闩；此后不再干预，只有设置卡片里的
+  开关能重新打开深色。本来就是浅色的机器不受影响。
+- 宿主没有 theme 服务时，退化为摘掉 `body[data-ds-dark-theme]`（仅本次会话有效）。
+
+### 文档
+
+- **README「这是什么」重写**：顶部依次是 logo 与 75% 透明度的小麦图；首段改为
+  「本插件为 DeepSeek Harness 的《狼与香辛料（狼と香辛料）》主题插件……」的正式表述。
+- 概览表：「浏览器半体积」改为「插件大小」（约 17 MB，其中两个脚本合计约 193 KB）；
+  素材改为按图片 32 张 + 视频 6 组计数；配色一行标注「开发中，测试功能」；
+  删掉「110 个别名 token 各一套」这类实现细节。
+- 新增配图目录 `docs/`（不参与运行时）：`intro-final.webp`（开场动画末帧，1920×1080）、
+  `scene-grid.png`（六段右栏待机动画各取一帧拼成一条）、`wheat-75.png`（75% 透明的小麦）。
+  `package.json` 的 `files` 同步收录。
+- 设置卡片的「黑夜模式」小节新增提示：**黑夜模式未完全做好适配，请谨慎打开。**
+- README 新增 FAQ「安装后自动变成了黑夜模式？」，说明成因（DSH 默认跟随系统）与自查两步。
+
+## 1.0.0 — 2026-10-24
+
+**首个公开发布版本。** 版本号重新从 1.0.0 起算——此前的 1.1.0～1.13.2 是本机内部迭代，
+功能已全部并入本版，旧记录保留在下方供追溯。
+
+### 配色
+
+- **浅色「麦秋晨光」**：羊皮纸底、暖棕文字、麦金点缀，全局重绘 DSH 的调色板 token。
+- **深色「星夜麦田」**：夜色底、暖金高光，默认关闭，在插件设置里切换。
+- 两套都只在**对应主题模式**下生效；切到没做过的那一侧时回退到出厂配色，不会出现
+  半深半浅的混搭。
+
+### 装饰
+
+- **开场动画（12 秒）**：canvas 实时渲染，不是视频；可按设置关闭，也可只在首次启动播放。
+- **浮动字标**：可拖动，位置记忆在本地。
+- **偷看的她**：贴在输入框上沿的探头立绘，可左右拖动且不出界、待机自动下沉、点击出声，
+  也可整只关闭。
+- **动态档案卡**、**日志标签分类**：档案卡随数据变化，日志标签按类别上色。
+- **侧栏脚下的麦田**：独立浮动层，宽度随侧栏自适应，高度到账号行中线。
+- **插件详情页横幅**：仅本插件详情页可见，随内容滚动。
+- **右栏待机画面**：仅在右栏自己的开始页显示，六段动画可在设置里切换，左右边缘做渐隐 +
+  模糊过渡。
+
+### 联动
+
+- **小鲸鱼挂件联动**：与 `dsh-whale-widget` 同时安装时，可一键导入「赫萝」「赫萝Q版」
+  两个可替换角色与一条替换语音，操作幂等。
+
+### 安全
+
+- **三条静态资源路由全部改为确切文件名白名单**。此前是整目录放行，`素材/` 下未修白边的
+  原件、封面草稿、字形切图都会跟着可访问。现在只送出 `index.js` 里 `ALLOW` 表列出的文件，
+  其余一律 404，子目录不可达，路径穿越仍被拦截。
+
+### 工程
+
+- 依赖零第三方包，只用 Node 内置模块与 `react`（由宿主注入）。
+- `node --check` 与四套自测脚本全绿。
+
+### 文档修正
+
+- **待机画面「糊」的归因写错了插件**。此前 README 与旧版变更记录把雾化归到「小鲸鱼挂件」，
+  还把两个不同的包名混成一个（`dsh-whale-widget` 与 `dsh-plugin-wallpaper-engine`）。
+  实际雾化来自 **wallpaper 插件（`dsh-plugin-wallpaper-engine`）的液态玻璃 / 磨砂效果**，
+  它的 `backdrop-filter: blur()` 会把背后的待机动画一起糊掉。判断与解法：把 wallpaper 插件的
+  **雾化强度调低**（或关掉液态玻璃），糊度随之下降。`dsh-whale-widget` 只管角色与语音，
+  不碰背景滤镜。README 三处与旧版变更记录中的相关表述已一并更正。
+
+---
+
+以下为公开发布之前的内部迭代记录，保留供追溯。
+
+## 1.13.2 — 2026-10-24
+
+按试用要求，把待机画面左右边缘从「纯透明度渐隐」换成**两侧各 10% 区域做模糊**，渐隐边界同步收到 10%。
+
+### 调整
+
+- **新增模糊覆盖层 `.holo-scene-blur`**：`backdrop-filter: blur(14px)`，靠 mask 只保留左右各
+  10%，中间保持清晰；4%→10% 一段让模糊渐入，清晰/模糊之间不出现硬接缝。该层直接压在
+  `<video>` 上方，`backdrop-filter` 采样的就是画面本身。
+- **为什么不是直接给视频加 `filter: blur()`**：filter 函数没有「按位置变化的强度」，整体
+  `blur()` 会把整张画面糊掉。要只糊两侧，只能用覆盖层 + `backdrop-filter` + mask 限制范围。
+- **横向透明度渐隐 18% → 10%**：与模糊带共用一条边界，两个效果不会错位。
+
+### 测试
+
+- `scene_test.mjs`：18% 断言改为 10%，新增两条模糊层断言（存在性 + mask 范围）。全套
+  **61 通过 / 0 失败**。
+
+## 1.13.1 — 2026-10-24
+
+修好待机画面**左右边缘没有渐隐、看着像一刀切**的问题，并把渐变带加宽到左右各 18%。
+
+### 修复
+
+- **渐变带落在空白里**：切片（`.holo-scene-clip`）宽度原先直接取右栏宽度，而画面固定 608px
+  居中。右栏比 608px 宽时，画面两侧各剩一条空白，横向遮罩的渐变带（切片宽度的百分比）就整条
+  落在空白处，画面自己的边缘仍是硬边。实测截图：可见画面恰好 608 CSS px，边缘在 6px 内从
+  奶油色直接跳到满强度格纹。
+- **切片改为收到画面宽度并重新居中**：`place()` 现在取 `min(栏宽, 608)`，`left` 按差值补一半。
+  切片边缘与可见边缘重新是同一条线，渐变带必然压在画面上，右栏多宽都不会落空
+  （`client.js` 的 `SCENE_PLATE_WIDTH` 与 `place()`）。
+
+### 调整
+
+- 横向渐变带 12% → **18%**（需求下限是左右各 10%，留出观感余量），端点仍为 50% 不透明。
+
+### 测试
+
+- `scene_test.mjs` 新增三条断言：宽栏（900px）时切片收到 608px、切片在栏内重新居中、
+  左右各 18% 渐隐到 50%。全套 **59 通过 / 0 失败**。
+
+## 1.13.0 — 2026-10-24
+
+右栏待机画面从**单片**扩成**六片可选**，左右边缘渐变到 50%，素材改从 `素材/动画/` 走新路由送出。
+
+### 新增
+
+- **六段待机动画，设置页可切**：`素材/动画/` 下 `赫萝抱臂`、`赫萝开心`（默认）、`缪莉开心1`、
+  `缪莉开心2`、`赫萝叉腰`、`缪莉挥手`，各 608×1080 VP9。选项名**就是文件名**，同名覆盖即可
+  换片。选择存 `localStorage['dsh-theme-holo.scene-name']`，切换时设置页写存储并派发
+  `dsh-theme-holo:scene-change`，待机层复用同一个 `<video>` 换 `src`（不重建，避免闪一下）。
+- **宿主新增第三条路由** `/holo-theme/anime/` → `素材/动画/`，与 assets / link 两条共用
+  同一个 `serveFile()`（GET/HEAD、Range/206、ETag/304、穿越拦截、405）。
+- **左右边缘 50% 渐变**：遮罩写在**切片**上（`mask-image: linear-gradient(90deg, rgba(0,0,0,.5) 0, #000 12%, #000 88%, rgba(0,0,0,.5) 100%)`），
+  不是写在视频上——608px 的片子比栏宽，超出部分被 `overflow: hidden` 裁掉，遮罩若在视频上
+  会跟着被裁走。
+
+### 变更
+
+- **画面从 1.6 倍上采样改成 1:1**：旧素材是 1024×576 塞进 1638×922 的盒子；新素材本身就是
+  608×1080 竖裁，盒子也改成 608×1080、`left: calc(50% - 304px)` 居中，不再缩放。README 里
+  「糊」的那段随之改写：现在没有上采样，雾化只可能来自 wallpaper 插件的液态玻璃。
+- **镜像改成按片判定**：`SCENE_CSS_MIRRORED = ['赫萝抱臂', '赫萝开心']`。这两片是 1.12.0 之前
+  切的，磁盘上没烘镜像，靠 CSS `.is-mirrored` 翻；新四片在切分时已 `hflip`，再翻会翻回去。
+  原来的全局 `transform: scaleX(-1)` 与 `mirrorOrigin()` 一并移除。
+- **清理两个不再被引用的 `assets/` 文件**：`assets/scene.webm`（换片前的单片待机画面）与
+  `assets/cover.jpg`（横幅的未压缩原件）已删除，`assets/` 减 2.35 MB。副本都留在 `素材/` 里：
+  `素材/动画/赫萝开心.webm` 与 `素材/横板封面.jpg`。注意前者与 `assets/scene.webm` **并非
+  逐字节相同**——两者帧数据一致，只有容器头 16 字节不同（EBML 段信息里的时间戳/封装器字段）；
+  后者与 `assets/cover.jpg` 才是 sha256 完全相同。
+- `.gitignore` 补 `_*/`（临时备份 / 回滚目录不再进仓库），README 的版本号修正为 1.13.0。
+
+### 测试
+
+- 新增 `smoke_anime.mjs`：六片各取一遍（200 / `video/webm` / 字节一致）+ HEAD / Range 206 /
+  404 / 穿越 404 / POST 405，全过。
+- `scene_test.mjs` 补 3 条：默认片带 `.is-mirrored`、镜像清单只含两片旧片、进入与切换两条
+  路径都调 `applyMirror`（56 项全绿）。`render_test.mjs` 补 8 条选择器测试（六选项、默认值、
+  切换写存储并广播、非法值回落），25 项全绿。其余四套（slot / wheat / peek_drag）无回归。
+
+## 1.12.0 — 2026-10-24
+
+右栏待机画面**左右镜像**；README 记下「模糊来自 wallpaper 插件雾化」这个结论。
+
+### 变更
+
+- **待机画面镜像**：`.holo-scene-img` 加 `transform: scaleX(-1)`。翻转原点不取 1638px
+  大盒子的中心，而是由 `mirrorOrigin()` 写成**可见切片**的中心
+  （`transform-origin: <20 + 切片宽/2>px 50%`）——绕盒子中心翻会把画面上另一块区域移进
+  切片，看着像换了张图；绕切片中心翻才是「同一块画面，左右对调」。
+  切片宽度变化（右栏拖宽、窗口缩放）时跟随重算。
+- **README 补两处**：第九节新增「它看起来糊，通常不是它自己的问题」——1024×576 的素材在
+  1638×922 盒子里本身约 1.6 倍上采样，但把「软」变成「糊」的是**wallpaper 插件
+  （`dsh-plugin-wallpaper-engine`）的液态玻璃 `backdrop-filter: blur()`**，它会把背面的
+  待机动画一起雾化；本插件对该 `<video>` 只有
+  `opacity` / `object-fit` / `mask-image` / 色相 `filter` / `mix-blend-mode`，没有 `blur()`。
+  第十七节「已知边界」表同步加一行，并给了判断方法与可选解法。
+- 测试：`scene_test.mjs` 增加一条断言「镜像原点钉在切片中心（154px 50%）」，51 项全绿。
+
+## 1.11.0 — 2026-10-24
+
+待机画面从**左边栏**改到**右侧栏**，并且只在右栏自己的开始页亮。
+
+### 变更
+
+- **挂载位置改为右栏**：`createScene()` 现在测 `[data-sidebar-right-panel]` 的矩形，切片左边缘
+  对齐栏的左边缘、宽度等于栏宽。之前测的是 `[class*="sidebarCol"]`，那是左边栏。
+- **开始页改认右栏自己的 guide**：亮不亮由三个宿主属性一起决定——栏在
+  （`[data-sidebar-right-panel]`）、栏是展开的（`data-sidebar-right-open`）、栏自己的开始页在
+  （`[data-sidebar-right-guide]`）。原来的 `[data-phase="hero"]` / `[data-content-phase="hero"]`
+  量的是**主对话区**，和右栏那一列没有关系，所以之前那版在右栏里永远不会亮。
+- **只认可见的那一个面板**：一个会话一份面板，被搁置的会话节点还留在文档里（带 `hidden`），
+  所以查面板和开始页都先筛「没有 `hidden`、没有 `aria-hidden="true"`、`getClientRects()` 非空」。
+- **scrim 渐变方向翻转 180°**：画面移到右侧后，要融进对话的是它的**左**边缘、要压暗的是贴窗口的
+  **右**边缘，所以 `90deg` 改成 `270deg`，深浅两套都改。
+- `MutationObserver` 的 `attributeFilter` 从 `data-phase` / `data-content-phase` 换成
+  `data-sidebar-right-open` / `data-sidebar-right-panel` / `data-sidebar-right-tab`。
+- 注释与 README 第九节同步改写：宿主侧的三个清填充对象变成右栏面板、栏内铺满的大盒子、列的
+  祖先链。
+
+## 1.10.2 — 2026-10-24
+
+出厂默认改成**当前实际停放的位置**，并把 1.9.3 删掉的不透明度滑块加回来。
+
+### 新增
+
+- **不透明度滑块回来了**：设置页「更改 logo 位置」下面多一条 10%–100% 的滑块，出厂 50%。
+  拖动即时生效，松手即存进 `dsh-theme-holo.logo-place` 的 `alpha` 字段（0–1 的小数）。
+  上下限由 `clampLogoAlpha()` 统一夹取，滑块、存储、程序调用三条路都过它。
+
+### 变更
+
+- **出厂默认改用实测的停放位置**：`LOGO_DEFAULT` 从 `751.2 / 37 / 75px` 那组换算值换成
+  `0.4234375 / 0.029219507595191253 / 0.17314453125` 三个裸比例。这三个数是从应用自己的
+  localStorage 记录里读回来的，不是按参考视口再算一遍——所以「恢复默认位置」等于「回到你
+  上次把它放在哪」，中间没有取整。在 2048×1152 视口下这对应 `(867.2, 33.66)`、高 75px。
+- **不透明度从 CSS 死数改成运行时值**：`[data-holo-logo] img` 规则里的 `opacity: .5` 删掉，
+  改由 `paint()` 写 `img.style.opacity`（`client.js:2985`）。同一个数字只留一处真值来源，
+  滑块和首帧不会各说各话。
+- **`logoState` 多一个 `alpha` 字段**，`loadLogoPlace()` / `saveLogoPlace()` / `resetLogoPlace()`
+  一并带上；「恢复默认位置」现在恢复四项（位置、大小、不透明度、显隐）。
+
+### 不变
+
+- 挂载点仍是 `document.body`，`z-index: 2`，`pointer-events: none`。
+- 不透明度仍写在 `img` 上而不是整层上：编辑态那圈细线框、右下角小方块、坐标徽标保持全不透明。
+- 深色模式仍不单独压低它，那条 `.84` 的覆盖规则保持删除状态。
+
+### 说明
+
+1.9.3 删滑块的理由是「拖一下就可能把字标弄丢」。那个问题的真正成因不在滑块本身：当时字标挂在
+会话标题栏里，而打开插件设置页会让宿主换掉 `renderSlot("main", …, { entryKey: activePanelId })`
+的 entry、整棵会话连同标题栏被卸载，字标跟着进垃圾堆。1.10.1 把字标退回 `body` 之后这个机制
+已经不存在，滑块可以安全地加回来——何况它的下限是 10%，退一万步也还找得到。
+
+## 1.10.1 — 2026-10-24
+
+字标的挂载点**退回 `document.body`**，`z-index` 回到 `2`。1.9.0 那套「塞进会话标题栏当水印」
+整条撤掉。
+
+### 变更
+
+- **挂载点从会话标题栏退回 `document.body`。** 1.9.0 把字标挂进 `.Dc7zOa_header` 并加
+  `isolation: isolate`，让它垫在标题栏文字与图标下面。代价有两个：字标出不了标题栏（超出的
+  部分跟着标题栏一起绘制，被正文盖住），以及每次打开插件设置页（那是一个 main panel，宿主用
+  `renderSlot("main", {}, { entryKey: activePanelId })` 换 entry）整棵会话连同标题栏被卸载，
+  字标得靠常驻 `MutationObserver` 才能回来。退回 `body` 之后这两个问题都不存在。
+- **锁定态 `z-index` 从 `-1` 回到 `2`。** 挂在 `body` 上时 `-1` 会被宿主那个不透明的
+  `.BynINW_frame` 整个吞掉（1.8.0 已经踩过一次）；`0` 与 `auto` 同趟按文档序画，而插件在宿主
+  渲染外框之前就挂上了，会反过来被外框盖住。`2` 压得过外框，又低于宿主自己浮起来的控件
+  （缩放手柄 `11`、leading seat `15`、overlay 层 `20`、popover 六位数）。
+- **`[data-holo-logo-host] { position: relative; isolation: isolate }` 整条规则删除。**
+  这是给标题栏挂载点造的堆叠上下文，挂回 `body` 之后没有宿主元素需要它。
+- effect 名从 `theme-holo: wordmark in the header` 改回 `theme-holo: floating wordmark`，
+  内部删掉 `findHeader()`、`mounted()` 与 `MutationObserver`，只剩
+  `document.body.appendChild(layer.root)`。
+
+### 不变
+
+- 存储仍是四个字段 `{ xPct, yPct, wPct, hidden }`，键还是 `dsh-theme-holo.logo-place`；
+  坐标本来就是视口百分比，换挂载点不需要迁移。
+- 出厂位置 `751.2 / 2048`、高 75px（1.9.4 左移过 10%），`LOGO_REF` 仍 2048×1152。
+- 固定五成不透明度（`[data-holo-logo] img { opacity: .5 }`）照旧，滑块仍然没有。
+- 设置页的编辑、实时读数、恢复默认位置、关闭 logo 全部保留。
+
+### 已知取舍
+
+- 字标重新浮在 GUI 之上，停在别的东西上面时会盖住它。出路是把图拖走，或者在设置里「关闭
+  logo」——这是选了「可自由摆放的一层图」这一版之后接受的代价，不是缺陷。
+- 真实浏览器里的拖拽手感与观感**没有在本机验证**（bsk daemon 起不来），只用 headless harness
+  覆盖了逻辑：126 项断言全过。
+
+## 1.10.0 — 2026-10-24
+
+**侧栏待机画面回来了，但只在开始页亮。** 源包那段 `scene.webm` 重新随包发布，深浅两套调色
+各配一份。
+
+### 新增
+
+- `assets/scene.webm`（493,782 B，1024×576）重新随包发布，走既有 `/holo-theme/assets/` 路由，
+  `index.js` 不用改——路由是目录级的，加文件即生效。
+- `createScene()`：把视频垫到侧栏列后面。`#holo-scene` 是 `position: fixed; inset: 0;
+  z-index: -1; pointer-events: none` 的一层，内部 `.holo-scene-clip` 的宽度由 JS 写成侧栏列的
+  实际像素宽，`overflow: hidden` 负责裁——所以侧栏一折叠，看到的就是同一条远景被裁窄，
+  而不是被压缩变形。
+- 视频盒子固定 **1638×922**（`left: -20px; top: 4px`），**不随窗口缩放**。素材是 1024×576 的
+  横幅远景，要的是它的左切片；跟随缩放会让她在每个窗口尺寸下都不一样大。
+- 双层氛围：浅色走 `mix-blend-mode: multiply` 把画面印进羊皮纸，深色压 `opacity: .94` 再叠
+  scrim 与 veil 两层；顶部 58% / 78% / 底部三档渐隐。
+
+### 关键机制
+
+- **只在 hero 页亮。** 认宿主自己写的 `[data-phase="hero"]` 与 `[data-content-phase="hero"]`
+  两个属性，`MutationObserver` 监听属性变化与子树增删，回调 `requestAnimationFrame` 节流。
+- **亮着时清宿主底色。** 视频在 `z-index: -1`，比 `.BynINW_frame` 与侧栏列自己的不透明背景
+  都靠后，所以 `createScene()` 会给侧栏列、列内每个直接子元素、列的父元素三处**内联**加
+  `background-color: transparent !important`，并打上 `data-holo-scene-fill="cleared"`；收盘面
+  时逐条 `removeProperty` 还原。只碰这三个已知节点，不做全文档扫描。
+- **不亮时不吃资源。** 切片宽度写 `0px`、容器 `display: none`，`<video>` 从文档摘掉、
+  `src` 丢空，解码器随之释放。侧栏折叠会换掉列节点，所以亮着的时候有一个 1.2 秒兜底复查。
+
+### 修掉的坑
+
+- `place()` 首次调用时列宽还没量到，`clipWidth` 写成 `0px` 后就再也没机会重算，待机画面会
+  一直看不见。现在 `sync()` 里列宽有效时总会回写，测试也把这个断言补上了。
+
+## 1.9.4 — 2026-10-24
+
+字标的出厂位置**往左挪了 10% 的视口宽度**。
+
+### 变更
+
+- `LOGO_DEFAULT.xPct` 从 `956 / 2048` 改成 `751.2 / 2048`——差 204.8px，即 2048 宽参考视口的
+  10%。纵向的 37px 和 75px 高度一个字没动，`LOGO_REF` 仍是 2048×1152。
+- 只有「恢复默认位置」和**没有本地记录**的人会看到新位置。已经拖动过并写进
+  `localStorage['dsh-theme-holo.logo-place']` 的机器沿用自己存的值，要看到新默认得点一次
+  「恢复默认位置」。
+
+### 不变
+
+- 存储仍是四个字段 `{ xPct, yPct, wPct, hidden }`，挂载点、`z-index: -1`、固定五成不透明度
+  全部照旧。这是一次纯粹的常量调整。
+
+## 1.9.3 — 2026-10-24
+
+字标的不透明度**改成固定的五成，滑块删掉**。
+
+### 移除
+
+- **「更改 logo 位置」那一组的透明度滑块和百分比读数整条删掉。**
+  它换来的自由度不值那个代价：这是少数几个「一拖就可能把东西弄丢」的控件——上一版刚修完
+  「调完透明度字标就不见了」，而那个 bug 只是让问题更容易撞上的一个引信。字标本来就是垫在
+  界面下面的水印，安静是它的本分。
+- `LOGO_ALPHA_DEFAULT`、`LOGO_ALPHA_RANGE`、`clampLogoAlpha()`、`setLogoAlpha()`、
+  卡片里的 `logoAlpha` 状态与 `changeLogoAlpha()` 随之删除，模块状态里的 `alpha` 字段一并去掉。
+
+### 变更
+
+- 不透明度现在只有**一处**声明：浮动字标那段 CSS 里 `[data-holo-logo] img` 的 `opacity: .5`。
+  仍然写在 `img` 上而不是整层上，所以编辑态的细线框、缩放手柄、坐标徽标保持全不透明。
+- 字标存储从五个字段变成四个：`{ xPct, yPct, wPct, hidden }`。
+  **旧记录里的 `alpha` 字段在读的时候直接忽略，下次保存时不再写回。**
+  不给它做兼容是有意的：那个字段正是「字标被拖到几乎看不见」的来源。
+- 「恢复默认位置」现在恢复位置、大小、显隐三项（原先还包括不透明度）。
+
+### 不变
+
+- 挂载点仍是会话标题栏，定位仍是 `position: fixed` + 视口百分比，`isolation: isolate` 与
+  锁定态 `z-index: -1` 照旧，已有的位置记录不需要迁移。
+
+## 1.9.2 — 2026-10-24
+
+修掉一个真 bug：**在设置页里调完字标不透明度，回到会话，字标不见了**。
+
+### 修复
+
+- **字标的观察器不再是一次性的，改成常驻重挂。**
+  宿主外壳用 `renderSlot("main", {}, { entryKey: activePanelId ?? "conversation" })` 决定中央
+  区域画什么，而插件设置页本身就是一个 main panel。打开设置页 = 中央区域换 entry = 会话整个
+  卸载，标题栏跟着没了。字标是标题栏的子节点，于是跟着那棵已经脱离文档的子树一起走；而当时的
+  `MutationObserver` 在第一次挂上之后就把自己 `disconnect()` 了，没有任何东西会再把它挂到
+  **新**标题栏上，所以它一直不见，直到刷新页面。
+  现在回调里先做一次很便宜的判断（`root.isConnected`，没有这个属性就沿 `parentNode` 走到
+  `body` 为止），确认字标真的不在文档里才去重新找宿主。流式输出那种每帧都在动 DOM 的场景
+  因此不会被拖慢——绝大多数回调只读一个属性就返回。
+- **重新挂载时复用同一个图层对象**（`appendChild` 会把它从旧父节点搬过来），监听、位置、
+  大小、不透明度、显隐全都留着，不重建、不重读存储。
+- **找标题栏改成按类名前缀配对。** `titleRow` 这个类名在宿主里不唯一（会话标题栏之外，
+  插件管理页的卡片、发现页、终端引导各有一个），裸的
+  `document.querySelector('[class*="titleRow"]')` 可能抓到别的页面。现在先取
+  `querySelectorAll` 的全部结果，再要求 `Xxxx_titleRow` 的父元素带 `Xxxx_header`；配不上
+  才退回「父元素类名含 `_header` 的任意一个」。
+- **换宿主时把旧宿主上的标记清掉。** `attachTo()` 现在会检查 `root.parentNode`，如果与
+  新宿主不同就 `removeAttribute('data-holo-logo-host')`，避免标记残留在已经没人用的元素上。
+
+### 不变
+
+- 挂载点仍是会话标题栏（`titleRow` 的父元素），定位仍是 `position: fixed` + 视口百分比，
+  存储的五个字段（`xPct` / `yPct` / `wPct` / `alpha` / `hidden`）一个都没动，
+  已有 localStorage 不需要迁移。
+- `[data-holo-logo-host]` 的 `isolation: isolate` 与锁定态 `z-index: -1` 照旧。
+
+### 已知代价
+
+- 观察器的回调在宿主每次改 DOM 时都会跑一次。子树范围是整个文档，但判断只有一次属性读取，
+  按理会很快（这一点没有在真实页面里量过，属未验证）。如果以后发现流式输出变卡，
+  第一个该怀疑的就是这里。
+
+## 1.9.1 — 2026-10-24
+
+侧栏脚下的麦田终于看得见了：从「塞进宿主侧栏里的子节点」改成独立浮动层。
+
+### 修复
+
+- **麦田图层改挂 `<body>`，用 `position: fixed` 定位**（与字标同一套路），不再往宿主侧栏
+  元素里插子节点。
+  之前它是侧栏列（或其内层 div）的子节点，需要「爬出」宿主绘制的那层不透明背景
+  （`--dsw-specific-sidebar-fill`）。给宿主元素补 `isolation: isolate` 的写法在真实壳里
+  没兜住，而且往非自有元素上写布局属性本来也不是对的路子。浮动层画在根堆叠上下文里，
+  只需压过 `.BynINW_frame` 一层，`z-index: 1` 就够了。
+- **不再往宿主侧栏元素上写任何样式**：`[class*="sidebarCol"]` 与
+  `[class*="sidebarCol"] > div:first-child` 那两条 `position`/`isolation` 规则已删除。
+- 位置改为每次测量后写入视口像素：`left`、`width`、`bottom`（窗口底到侧栏底的距离）、
+  `height`。侧栏不在窗口左下角时也贴得住，窗口缩放、侧栏折叠、页面滚动都会重测。
+- 侧栏节点被换掉（折叠再展开）时自动重新绑定 `ResizeObserver`，每 2 秒兜底复查一次。
+
+### 新增
+
+- **插件详情页顶部横幅**：`[data-plugin-detail="dsh-theme-holo"]::before` 用的是
+  `assets/cover.webp`（1920×620，205,082 B）。浓度已烤进 WebP 的 alpha 通道——CSS `opacity`
+  会把边框一起淡掉，背景图自身又没有透明度旋钮。`assets/cover.jpg` 是未压缩原件，不进路由。
+
+### 不变
+
+- 高度仍只量不推：顶部钉在账号行中线，宽度变化不影响高度。
+- 75% 整体不透明度、两侧与上边缘的淡出、横向平铺、`pointer-events: none` 全部照旧。
+
+### 已知代价
+
+- 浮动层在 `.BynINW_frame` 之上，所以麦穗会压在账号行下半部分**之上**。
+  靠素材本身化解：`wheat.png` 顶部 0–20% 有 93.8% 完全透明，跨过名字的那条带上只有
+  少量穗尖，且已被遮罩降到 40%。账号行仍可点击（`pointer-events: none`）。
+
+## 1.9.0 — 2026-10-24
+
+字标改挂到会话标题栏里，终于落在标题栏文字与按钮的下面，不再挡住它们。
+
+### 变更
+
+- **字标挂载点从 `document.body` 换成会话标题栏**（`[class*="titleRow"]` 的父元素）。
+  它原来是 `<body>` 的直接子节点，和宿主整块 GUI 的外框 `.BynINW_frame` 是兄弟；外框的
+  `z-index` 是 `auto`，所以字标那个 `2` 把整个外框——连同里面所有文字和图标——压在了下面。
+  这就是「logo 挡住省略号按钮」那张截图的原因：子元素的层级出不了父级的堆叠上下文，
+  在标题栏内部再怎么调都没用，得换挂载点。
+- **锁定态 `z-index` 回到 `-1`**，同时新增一条 `[data-holo-logo-host] { position: relative;
+  isolation: isolate }` 给标题栏元素造堆叠上下文。在这个上下文里负 z-index 画在
+  「元素自身背景之后、in-flow 子项之前」，所以字标落在标题栏文字之下；而标题栏自身不画背景
+  （不透明底在更外层的 `.Dc7zOa_root` 上），字标又能透过它看见。机制与侧栏脚下的麦田一致。
+- effect 名从 `theme-holo: floating wordmark` 改为 `theme-holo: wordmark in the header`。
+- 宿主在插件之后才渲染标题栏，所以改用 `MutationObserver` 等 `[class*="titleRow"]` 出现，
+  挂上即 `disconnect()`；拆卸时把 `data-holo-logo-host` 属性原样还回去。
+
+### 不变
+
+- 存储的坐标含义没变：仍是 `position: fixed` + 视口百分比，已有的
+  `dsh-theme-holo.logo-place`（含 `xPct`/`yPct`/`wPct`/`alpha`/`hidden`）不需要迁移。
+- 设置页的编辑、读数、恢复默认、关闭 logo、不透明度滑块全部照旧。
+
+### 已知代价
+
+- 字标出不了标题栏。`position: fixed` 让它仍按视口坐标定位，但既然它是标题栏的子节点，
+  超出标题栏的部分就跟着标题栏一起绘制、排在正文之前，于是被正文文字盖住而不是盖住正文。
+  想保留全屏自由摆放只能改用「挂进 `.BynINW_frame` 内部」的方案，那要另外处理视口偏移和
+  `overflow: hidden` 裁剪。
+
+## 1.8.0 — 2026-10-24
+
+字标可以在插件设置里整个关掉，锁定态的层级也重新定了。
+
+### 新增
+
+- **「关闭 logo」按钮**：插件设置「更改 logo 位置」一节里，「更改 logo 位置」与
+  「恢复默认位置」之间多一个开关，点一下整个字标消失，再点一下回来。
+- **显隐进存储**：`localStorage['dsh-theme-holo.logo-place']` 多一个 `hidden` 字段，
+  位置、大小、不透明度、显隐四项共用一个键。
+
+### 变更
+
+- **锁定态 `z-index` 从 `-1` 改回 `2`**（`2` 在 1.9.0 又被推翻，见那一条：问题从来不是这个数，
+  而是字标挂在了 `body` 上；换挂载点之后 `-1` 才是对的）。`-1` 是个 bug：负 z-index 在「低于 in-flow 内容」
+  那一趟里绘制，而宿主的外框元素（`position: relative` + 不透明底色）正好压在那趟前面，
+  字标整个消失。`0` 也不行——`0` 与 `auto` 同一趟、按文档序绘制，本层由插件加载时就挂上、
+  外框由 React 在 boot 之后才挂，谁后挂谁赢，于是会被重新埋掉。一个小的正数把绘制顺序和
+  「谁先挂」解耦。`2` 仍低于所有宿主控件（缩放手柄 11、主位 15、浮层 20、弹出层六位数）。
+- 「恢复默认位置」现在同时恢复位置、大小、不透明度、显隐四个值。
+- 隐藏中「更改 logo 位置」按钮禁用，状态行改文案为「已关闭：logo 隐藏中，不显示也不影响任何点击。」
+
+### 设计
+
+- 隐藏用 `display: none` 而不是 `opacity: 0`：看不见的字标不该还能接点击，也不该留在
+  无障碍树里。
+- 隐藏**不动位置**，再打开就回到刚才停的地方，关一次不会丢掉调好的位置。
+- 隐藏会一并退出编辑模式：看不见的东西没法拖，设置页也不该继续显示一个隐形字标的坐标。
+- 保证不拦点击的始终是 `pointer-events: none`，不是 `z-index`——这两个数是两件事。
+
+## 1.7.0 — 2026-10-23
+
+侧边栏脚下长出一片麦田。
+
+### 新增
+
+- **侧栏麦田**：`#holo-wheat` 挂在侧栏列最底部，`assets/wheat.png` 横向平铺，
+  整体 75% 不透明度，两侧与上边缘淡出到 30%。高度锚在「账号菜单」行的垂直中线，
+  宽度跟随侧栏，麦秆比例不变。
+- 图源 `素材/小麦.png` 经左右镜像拼成 904×146 的无缝片：原图右缘 alpha 均值 69.47、
+  左缘 94.24，直接 `repeat-x` 会有一道接缝；镜像后四列对齐。
+
+### 设计
+
+- 给宿主侧栏列加了 `position: relative; isolation: isolate`——负 z-index 子元素要有
+  独立堆叠上下文才压得住列背景、又不盖住行文字。这是本插件唯一改动宿主元素样式的地方。
+- 两个方向的淡出分在父子两层各用一个 `mask-image`，避开 `mask-composite` 的兼容差异。
+- 边缘值不单独写死：mask 淡出到 `0.4`，与整体的 `0.75` 相乘得 30%。调整体浓度只动
+  `opacity` 一行，边缘按比例跟随。
+- 高度由 `ResizeObserver` 跟随侧栏、窗口缩放与会话列表挤压，不轮询；
+  找不到账号行时退回列高 18%，并夹在 `[24px, 列高]`。
+- 深色下沿用 `[id^="holo-"]` 收起规则，麦田不出现。
+
+## 1.6.0 — 2026-10-23
+
+字标锁定后沉到界面之下当水印，并给了它一个不透明度滑块。
+
+### 新增
+
+- **锁定态沉底**：`[data-holo-logo]` 的 `z-index` 从 `2147482800` 改成 `-1`。字标不再浮在
+  文字上面，而是垫在所有宿主元素下面，面板、卡片、提示文字都盖在它上面，不再遮挡界面
+  内容。编辑态仍升回 `2147482800`，否则水印在面板底下抓不到。（**`-1` 在 1.8.0 已推翻**，
+  见那一条：它会让字标被宿主的不透明外框整个吞掉。）
+- **不透明度滑块**：插件设置「更改 logo 位置」一节里加一条 10%–100% 的滑块，拖动即时
+  生效、松手即写入 `localStorage['dsh-theme-holo.logo-place']` 的 `alpha` 字段（不新开
+  存储键）。出厂值 `LOGO_ALPHA_DEFAULT = 0.92`，下限 10% 是为了拖到底也还找得见。
+
+### 变更
+
+- 删掉深色模式的 `[data-holo-logo] img { opacity: .84 }` 覆盖规则。两个不透明度来源会
+  打架，现在只留滑块一个真值来源。
+- 删掉编辑态的 `img { opacity: 1 }`，改为统一由 JS 把 `alpha` 写在 `img` 上——写整层会
+  让编辑线框和坐标徽标一起变淡。
+- 「恢复默认位置」现在同时恢复位置、大小和 `alpha` 三个值。
+
+### 设计
+
+- `clampLogoAlpha` 对非数字回落到默认值、对越界值夹到 `[0.1, 1]`，手改存储记录也藏不掉
+  字标。
+- `setLogoAlpha` 写入后走 `notifyLogo()`，设置页读数与图层同一个真值来源，不会出现滑块
+  停在一个图层没去的位置。
+
+## 1.5.0 — 2026-10-23
+
+字标从标题栏槽位改成一层可自己拖的浮动图片，位置与大小都归用户。
+
+### 新增
+
+- **「更改 logo 位置」编辑模式**：插件设置页最下面一节，点下去字标出现一圈细线框、右下角
+  缩放方块和实时坐标读数，拖完点「完成调整（固定下来）」写进
+  `localStorage['dsh-theme-holo.logo-place']`；`Esc` 同效退出。
+- **「恢复默认位置」**：回到代码里的 `LOGO_DEFAULT` 常量。
+- **比例坐标存储**：存 `{ xPct, yPct, wPct }` 三个视口分数，渲染用 `vw` / `vh`，
+  窗口缩放和最大化自动等比跟随，不需要 `resize` 监听。
+
+### 变更
+
+- 字标**不再注册** `conversation.session.header.actions` 槽位，改为 `document.body` 上的
+  `position: fixed` 浮动层，由 `ctx.effect(…, 'theme-holo: floating wordmark')` 挂载。
+- 尺寸不再由宿主的容器单位和 flex 盒决定（那条路插件改不动、也无法在本机验证），
+  改由 `LOGO_W_RANGE`（视口宽度的 5%–55%）夹取。
+- 出厂默认改成实测值：2560×1440 最大化、125% 缩放（2048×1152 CSS）下 `(956, 37)`、
+  高 75px，取代原先 1600×1000 视口上的估值。
+
+### 设计
+
+- 空闲时图层 `pointer-events: none` 且不挂任何监听，绝不会拦到下方 GUI 的点击；
+  只有编辑模式才接受输入。
+- 拖动时先 `setPointerCapture`，指针移出图层也不会丢事件；`pointercancel` 与
+  `pointerup` 走同一条收尾路径，中断的拖动不会留下悬挂状态。
+- 加载时对越界和损坏的存储值做夹取与回退，且**只夹内存不回写**——读取不产生写入。
+
+## 1.4.0 — 2026-10-24
+
+把「狼与香辛料」字标挂到会话标题栏右侧，随面板宽度自适应。
+
+### 新增
+
+- **会话标题栏字标**：`conversation.session.header.actions` 槽位注册，`id` 为
+  `dsh-theme-holo#logo`，`order: 100` —— 排在原生 chip 之后（智能体团队 -20、
+  预设 -10、子代理 10、任务 20），不会挤掉任何真实控件。
+- **素材 `assets/logo.png`**：591×125 透明 PNG，从 `素材/logo.png`（640×360）裁掉
+  四周留白（alpha 边界 `(4, 86, 587, 203)` + 4px 内边距），45,916 B。
+
+### 设计
+
+- 尺寸用 `height: clamp(15px, 2.4cqw, 30px)`：会话标题栏本身声明了
+  `container-type: inline-size`，所以字标量的是面板宽度而不是视口宽度——侧栏展开时
+  收一点、收起时涨回去。`clamp` 前面另写了一条 `height: 22px` 兜底，避免浏览器
+  不解析容器单位时退回素材固有高度 125px 把标题栏撑开。
+- 选择器用 `[data-holo-logo]` 而不是 `#holo-logo`：深色模式那条
+  `[id^="holo-"] { display: none }` 会把装饰性元素整体收起，而字标是品牌标识，
+  两套配色下都该在。
+- 深色下只把 `opacity` 从 `.92` 降到 `.84`，不加 `filter` —— 字标是白字深描边，
+  提亮反而会把描边冲淡。
+
+## 1.3.0 — 2026-10-24
+
+把深色配色加回来，并给探头、开场动画各配一个开关。
+
+### 新增
+
+- **深色配色「星夜麦田」**：110 个别名 token 的深色值全部从原包恢复，注入在
+  `html body[data-ds-dark-theme]` 作用域。浅色规则仍全部锁在
+  `html body:not([data-ds-dark-theme])`，两套互不干扰。默认关闭——装好就是浅色
+  「麦秋晨光」，不动用户的外观偏好。
+- **插件设置里的「黑夜模式」开关**：按钮写的是主题服务的 `setTheme('dark'|'light')`，
+  也就是「设置 → 外观」用的同一条偏好字段（`preference`），两处是同一个状态。
+  宿主没有 theme 服务时回退为直接切 `body[data-ds-dark-theme]`。
+- **插件设置里的「探头的赫萝」开关**：按钮文案 `不启用探头的赫萝` / `启用探头的赫萝`。
+  关闭后输入框边上的探头不再出现，选择记在 `localStorage` 的
+  `dsh-theme-holo.peek-off`，由 `html[data-holo-peek="off"]` 隐藏 `#holo-peek`。
+
+### 调整
+
+- 开场动画那对按钮文案统一为 `关闭开场动画` / `开启开场动画`，与小节标题「开场动画」对齐。
+
+## 1.2.0 — 2026-10-23
+
+设置入口挪到「包详情页」，并修掉偷看的她在大弹窗旁被半透明化的问题。
+
+### 新增
+
+- **包详情页的设置区块**：`plugins.bundle.config` 槽位注册，key 用包名 `dsh-theme-holo`。
+  以前只在插件行页（`plugins.row.config`，key `dsh-theme-holo#theme-holo`）注册，
+  从插件列表点进包详情页时看不到任何配置项——现在两处都有。
+  依据：DSH 插件管理页源码里 `configured: ledger.bundles.has(openPkg.name)`，
+  只有 `plugins.bundle.config` 里存在同名 key，包详情页才渲染配置区。
+- **一键导入联动内容**：按钮文案改为 `一键导入联动内容`，下面补一行说明会导入
+  角色图「赫萝」「赫萝Q版」+ 语音组「赫萝震惊」，已存在的条目跳过不重复添加。
+- **导入后的「刷新页面」按钮**：小鲸鱼挂件只在页面加载时读一次 `roles.json`
+  （前端 `loadRoles()` 只有一个调用点），所以导入成功后角色不会立刻出现在它的
+  「角色」列表里，容易被误判成导入失败。现在卡片会多一个 `刷新页面` 按钮和一行
+  说明，把这一步讲明白。
+
+### 修复
+
+- **片头在工作过程中反复重播**：客户端加载器热替换插件的方式是「失效模块 → 重跑
+  factory → 重新 apply」，页面并不刷新（`dsh-client-modules` 的 `reload(id, rev)`）。
+  片头原本在 `apply` 里无条件创建，于是**每次改动 `client.js` 都会重播一遍 12 秒**。
+  现在用 `window.__dshThemeHoloBootShown` 做页面级去重：同一页面生命周期内只放一次，
+  真实页面加载时该标记自然重置，所以「启动时播一次」的语义不变。
+- **片头「跳过动画」按钮点不动**：这个按钮原本被 `document` 捕获阶段监听器排除在外，
+  只靠自己的 `click` 监听器结束片头。宿主若在捕获阶段 `stopPropagation`，click 就
+  永远送不到按钮——表现为「点按钮没反应，点屏幕别处却能跳过」。现在除音效开关外，
+  点任何地方（含按钮）都走同一条 `skip` 路径，`finish` 幂等，重复触发无害。
+- **片头结构样式不再依赖明暗模式**：`#holo-boot` 的定位/层级/`pointer-events`、
+  canvas 铺满、两个按钮的 `pointer-events: auto` 与 `z-index` 改为不限定
+  `body:not([data-ds-dark-theme])`，避免深色模式下按钮被 1920×1080 的 canvas
+  挤到视口外点不到。
+- **偷看的她不再半透明**：有对话框/菜单打开时，原本把她的不透明度压到 `0.35`
+  （半透明幽灵状），现在直接 `0`（完全隐藏），并在不透明度低于 `0.05` 时设
+  `pointer-events: none`，避免看不见还能点到。
+
+## 1.1.1 — 2026-10-23
+
+界面文案汉化、插件图标、以及一个关掉片头的开关。
+
+### 新增
+
+- **插件图标**：`package.json` 加 `icon: "assets/icon.jpg"`，图标是 64×64 的赫萝成就图
+  （原图在 `素材/图标.jpg` 留一份）。DSH 从清单读相对路径、自己转 data URL，
+  不走本插件的路由。
+- **片头跳过按钮**：片头右下角原本只有一行英文提示 `CLICK TO SKIP`，现在换成可点的
+  `跳过动画` 按钮（和点画面任意处等效）。
+- **彻底关掉片头**：插件行页新增「开场动画」区块，按钮 `跳过开机动画` / `恢复开机动画`，
+  存在 `localStorage['dsh-theme-holo.skip-boot']`。关掉后连 canvas 都不建。
+
+### 变更
+
+- **描述改中文**：`package.json` 的 `description` 换成中文，并新增
+  `locale/zh.json` + `locale/en.json`，让插件列表里的标题显示「赫萝主题」而不是包名。
+
+## 1.1.0 — 2026-10-23
+
+与「小鲸鱼挂件」（`dsh-whale-widget`）联动。
+
+### 新增
+
+- **联动内容**：把两个可替换角色「赫萝」「赫萝Q版」和一条语音「赫萝震惊」装进挂件。
+  素材取自 `素材/`（`holo-clean.png`、`holo-Q-clean.png`、`赫萝语音.WAV`），
+  由宿主新增的前缀路由 `/holo-theme/link/` 送出——不在仓库里存第二份副本。
+- **首次安装弹窗**：片头播完、且检测到挂件时弹一次羊皮纸风格对话框，说明会装什么，
+  可「装进去」或「以后再说」。选择记在 `localStorage['dsh-theme-holo.whale-link-prompted']`，
+  之后不再弹。
+- **设置入口**：插件行页（插件 → 已安装 → 赫萝主题）里有一个「赫萝 × 小鲸鱼联动」区块，
+  显示当前状态并提供安装/重试按钮——给当初选了「以后再说」或先装主题后装挂件的人留的后路。
+- **幂等**：按名字比对，已有的一律不动，只补缺的。挂件没装时按钮显示「未检测到小鲸鱼挂件」，
+  不报错。
+
+### 说明
+
+- 素材读取用浏览器端 `fetch()` 走同源路由，再转 data URL 交给挂件的上传接口；
+  全程不需要用户手动传图。
+- 挂件自身路由受宿主鉴权保护，因此联动只在浏览器里生效（CLI 侧无法代劳）。
+
+## 1.0.0 — 2026-10-23
+
+从「赫萝主题-安装包」里的 `dsh-theme-holo@0.1.0` 重制为正规 DSH 插件。
+
+### 结构
+
+- **拆包**：源包是 4 个文件、浏览器半为 1.6 MB 单文件；本版拆成 `package.json`（清单）、
+  `index.js`（宿主半）、`client.js`（浏览器半）、`assets/`（素材）、`cordis.patch.yml`（bundle 补丁）。
+- **素材外置**：五件素材原先以 base64 内联在 `client.js` 里（约 1.5 MB）。本版把 4 件落成
+  `assets/` 下的真实文件，由宿主注册的前缀路由 `/holo-theme/assets/` 送出，支持 ETag / 304、
+  Range / 206、HEAD，并拒绝目录穿越。`client.js` 因此降到约 78 KB。
+- **安装形态**：改为标准插件——profile 的 `dependencies` 一行 `link:` + `bundles` 一行，
+  不再依赖手工 junction 与用户补丁。
+
+### 移除
+
+- **侧栏背景动画**：`scene.webm`（待机动画，482 KB）连同 `createScene()` 整段移除，
+  侧栏回到干净的纸色。
+- **深色配色「星夜麦田」**：整套深色令牌移除。切到深色时本插件退出，交回 Harness 出厂深色。
+
+### 修复
+
+- **`createProfileCard()` 缺失**：重写时该函数被漏掉，但 `apply()` 仍在调用它，会导致插件
+  挂载时抛 `ReferenceError`。已补回（并去掉原实现里两个未使用的变量）。
+- **片头注释失实**：`apply()` 里写着「~2.5 s」，实际是 12 秒。已改正。
+- **日志标签词表可读性**：`createLogTags()` 的 `KINDS` 原用 `\uXXXX` 转义，已改为直接写中文。
+- **浅色作用域误用深色调色板**：重写时把深色方案的色值套进了 `:not([data-ds-dark-theme])` 作用域，
+  导致弹出菜单 / 下拉 / 弹窗 / 提示条是近黑色面板、代码块是深褐底、五个日志标签色偏亮发灰。
+  已全部改回羊皮纸浅色值（面板 `rgba(255,252,245,.985)`、代码块 `#F4EBD9`、行内码 `#7A4E12`、
+  标签 `#7C6C4F / #8A6428 / #A9661F / #8E4A40 / #7C6248`），并补回被漏掉的
+  `#holo-profile-card` 羊皮纸孪生规则（4 条），使档案卡不再沿用深色内联样式。
+
+### 保留
+
+- 12 秒 canvas 实时渲染片头（含音轨开关与 `#boot-hold` 定格）。
+- 偷看的她：完整状态机（露出 / 倾角 / 让位 / 点头）、金线、麦粒、苹果彩蛋、打瞌睡。
+- 动态档案卡。
+- 日志标签分类（思考 / 读取 / 图片 / 搜索 / 运行命令 / 工具调用 / 写入 / 编辑）。
+- 麦穗、纸纹、菜单 / 弹窗 / 代码块 / 滚动条 / 选中 / 焦点等全套次级界面细节。