dsh-wisp 0.6.0

package/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 dsh-wisp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------
+
+THIS LICENCE COVERS THE CODE ONLY.
+
+The character artwork under assets/ — and the same images inlined as base64
+inside lib/client.js — is licensed separately, under CC BY-NC-SA 4.0.
+Read NOTICE.md before redistributing either part.
+
+"DeepSeek" and related marks belong to their respective owners. This is an
+unofficial fan project and is not affiliated with or endorsed by DeepSeek.

package/NOTICE.md

@@ -0,0 +1,151 @@
+# NOTICE — 来源、署名与许可
+
+本插件包含**两部分不同来源的内容**，适用**不同许可**。分享或再分发前请读完。
+
+---
+
+## 1. 代码
+
+`lib/`、`cordis.patch.yml`、`build.mjs`、`verify-wisp.mjs` 等全部源码。
+
+**许可：MIT**
+
+---
+
+## 2. 角色形象与图片
+
+`assets/` 下的四个精灵图（`idle` / `happy` / `sleepy` / `work`），以及内嵌在
+`lib/client.js` 里的同源 base64 数据。
+
+### 这是什么
+
+DeepSeek 娘是 **DeepSeek 社区共同创作的拟人化同人形象**，
+不是 DeepSeek 官方角色，也没有任何官方设定集。
+
+社区对其形象的公认描述（引自一个公开的社区桌宠项目）：
+
+> 「可爱温柔、工作认真，失败时有点慌张，以鲸尾表达情绪的**蓝发鲸鱼女仆**。」
+
+本插件使用的四张图**全部由 AI 生成，且全部生成于本项目自己名下的 TapTap Maker 工程**
+（`孤屿`，`assets/image/`）。制作过程分两步：
+
+1. 初版由 AI 生成（683×1024）；
+2. 此后每一次改版——提升分辨率到 2048×3072、更换服装——都是**在上一版自己生成的图上、
+   用 Maker 的图生图（改图）接口重绘**的。生成时使用 4K 渲染分辨率，即细节是在 4K 下
+   重新合成后缩放到 2048×3072，而不是把小图放大。
+
+**关键一点：底图始终是本项目自己生成的图，不是任何第三方插画。** 因此这些图片
+**不构成对任何现有插画作品的复制、描摹或改图**；本插件作者也未曾以他人作品作为输入。
+
+### 图片生成规则（硬性）
+
+**只用文生图，一条图只放一个角色，且必须自己做抠图。**
+
+1. **禁用 `edit_image`**（改图接口）及任何"以现有图片为生成底图"的方式；**禁用 `reference_images`**。
+   形象只能靠提示词锚定。采用 `model: "gpt"`、`resolution: "4K"`、`target_size: "2048x3072"`。
+2. **一条图里只放一个角色**：提示词必须写明「画面中只有一个角色」，禁止拼图、多视图、三视图、分镜。
+3. **不要用服务端的透明背景**（`transparent: false`）。改在**纯绿幕**上出图，再用本地
+   `keyout` 抠图。原因见下。
+
+#### 为什么必须自己做抠图
+
+服务端的自动透明背景**会把不该抠的抠掉**：角色是深蓝/浅蓝/白配色，浅蓝渐变的**发梢**与**鲸尾**
+最接近浅色底，于是被当成背景切掉 —— 表现是"生成结果变成了短发、鲸尾消失"，极易误判成模型跑形。
+
+实测：同一批提示词，走服务端透明背景时四张全部丢失发梢与鲸尾；改成绿幕 + 本地绿幕抠图后，
+只有 0.43%–0.53% 的边缘像素需要做半透明处理，**发丝一根没丢，鲸尾完整**。
+
+#### 画风措辞的坑
+
+写「高质量二次元插画」会明显把模型推向**韩系半写实**（头发变短、体型成熟化、加胸部），角色设定随之
+崩掉。必须写成「干净的动漫赛璐璐上色，平涂色块加简单明暗，日系动画角色设定图风格，人物为少女体型，
+不要写实、不要韩系半写实、不要成熟化」。
+
+
+
+### 关键声明
+
+- **非官方**：本插件与 DeepSeek（深度求索）官方无任何关系，未获其授权、认可或赞助。
+  名称中出现的 "DeepSeek" 仅用于**说明所模仿的对象**。
+- **同人性质**：角色属于社区同人创作范畴。若权利人提出异议，应停止分发图片部分。
+- **AI 生成**：图片由 AI 生成，可能包含不准确或非预期的细节；按「现状」提供，不作任何保证。
+- **无所有权主张**：本插件作者**不对该角色形象主张任何权利**。此处不授予你任何
+  你原本不拥有的权利。
+
+### 图片许可
+
+**CC BY-NC-SA 4.0**（署名—非商业性使用—相同方式共享）
+
+- **署名**：需注明「角色形象源自 DeepSeek 社区同人创作，图片由 AI 生成」并链回本项目
+- **非商业**：不得用于商业用途
+- **相同方式共享**：再分发图片须沿用同一许可
+
+之所以不把图片一并放进 MIT：MIT 是代码许可，作者并无权用它替图片授权。
+
+---
+
+## 3. 署名建议
+
+再分发时，请在你的 README 或关于页保留类似文字：
+
+> dsh-wisp —— DeepSeek Harness 的 DeepSeek娘桌宠插件。
+> 角色形象「DeepSeek娘」源自 DeepSeek 社区同人创作，非官方角色。
+> 插件内图片由 AI 依据社区公认特征生成（CC BY-NC-SA 4.0），代码以 MIT 许可发布。
+> 本项目与 DeepSeek 官方无关。
+
+---
+
+## 4. 构建陷阱（给维护者）
+
+### 4.1 占位符不能出现在注释里
+
+`build.mjs` 把四张图注入 `lib/client.template.js` 时，占位符**绝不能出现在注释里**。
+
+曾经踩过的坑：占位符写成 `/*__SPRITES__*/{}`，替换后残留 `/*`，**整个注入的对象变成块注释**，`SPRITES` 静默求值为 `{}`，图片源变成 `undefined` —— 表现是插件"挂载成功"但显示碎图。这个 bug 极难从症状反推。
+
+现在 `build.mjs` 有四道防线：
+
+1. 占位符必须**恰好出现一次**，替换后不得残留
+2. **真的去求值** `const SPRITES = {…}`，确认四个 key 都是 `data:image/` 开头，否则拒绝写出文件
+3. 产物**不得调用被陷阱的全局**（`setTimeout` / `setInterval` / `clearTimeout` / `clearInterval` / `fetch` / `require`）——在客户端半包里这些是抛异常的形参，调用即崩，而打包器不会报
+4. `const VERSION` 必须与 `package.json` 的 `version` 一致
+
+`verify-wisp.mjs` 另有两道**回归守卫**：断言 `img.src` 是 `blob:` 而不是 `data:` URI；并把六个被陷阱的全局以抛异常的形式注入后**真跑一遍**。
+
+### 4.2 为什么用 Blob 而不是直接给 data URI
+
+初版直接把 base64 data URI 赋给 `img.src`。插件加载正常、DOM 正确、光晕也渲染了，**但精灵图显示为碎图**。内嵌字节经校验无误（RIFF/WEBP magic，256x384 RGBA），所以问题在于本页面拒绝 `data:` 作为图片源——该界面通过自定义 `dsh-app://` 协议提供服务，会拦截资源加载。
+
+因此现在把 base64 解码为 `Blob` 再取 object URL；拆解时 `revokeObjectURL` 释放。
+
+**并且要连缓存键一起删。** blob 缓存是**模块级**的（模块只被 import 一次），而挂载是**每次 `apply` 一次**。只 revoke 不删键，下一次挂载就会拿到已吊销的 URL —— 又变成碎图，而且只在"HMR 重挂 / 重复行"这类路径上出现。
+
+### 4.3 时间基准必须只有一个
+
+`(window.performance && performance.now) ? performance.now() : Date.now()` 看着无害，实际混用了两个引用：判定条件读 `window.performance`，取值读裸全局 `performance`。在页面里两者是同一个对象，但在自带 `window` 的壳里可能不是 —— 于是**截止时间用一个时间基准计算、用另一个比较，所有定时器永不触发**：她不会睡着、不会庆祝、气泡不会消失，而控制台一行错误都没有。
+
+现在只经 `window.performance` 读取。`verify-wisp.mjs` 的虚拟时钟会把这个混用直接暴露成一条失败。
+
+### 4.4 反应轮询是唯一按秒发生的成本
+
+忙碌判定与输入框检测跑在一个 1.2 s 的定时器上，只要应用开着就一直跑，所以它的形状必须便宜。在真实 Chromium（10k 节点会话记录，headless CPU 光栅，即最不利的一档）实测每次 tick：
+
+| 写法 | 每次成本 |
+|---|---|
+| `querySelectorAll('[data-composer-input],[contenteditable="true"],textarea')` | 0.33 ms（40k 节点 1.42 ms），每次 tick 全文档收集 |
+| 4 条精确 `button[aria-label="…"]` | 0.45 ms（1.86 ms），空手而归也要走 4 遍 —— 而空闲是常态 |
+| **2 条子串 `button[aria-label*="…"]`** | **0.27 ms（1.10 ms）**，且能匹配没见过的翻译 |
+
+再加上"输入框元素只解析一次后缓存"，整个 tick 从 **1.27 ms 降到 0.44 ms**，每秒的 `querySelectorAll` 调用数从 1 变成 **0**。`verify-wisp.mjs` 把这三件事都钉成了断言：已解析的输入框不得每 tick 重查、一次 tick 不得收集 NodeList、无输入框时每 tick 最多一次探测。
+
+顺带一条渲染侧的教训：`will-change: transform` 不要常驻 —— 它为一个几乎不发生的事件（拖动）永久保留一个合成层；现在只在真的拖动期间挂上。
+
+---
+
+## 5. 参考
+
+- 萌娘百科「DeepSeek娘」：https://mzh.moegirl.org.cn/DeepSeek%E5%A8%98
+- 社区桌宠项目（`pet.json` 中的角色描述）：https://github.com/xpy12367/codex-pet-DeepSeek-girl
+
+上述链接仅作为**形象来源的说明**，其中的内容版权归各自作者所有。
+

package/README.md

@@ -0,0 +1,285 @@
+# dsh-wisp
+
+DeepSeek Harness Web 界面的浮动陪伴插件：**DeepSeek娘** 桌宠。
+
+**当前版本 `0.6.0`** · 零依赖 · 单文件客户端半包（精灵图内嵌为 data URI）
+
+> 非官方插件，与 DeepSeek（深度求索）官方无关。角色形象与图片许可见 [NOTICE.md](NOTICE.md)。
+
+---
+
+## 它做什么
+
+| 行为 | 触发条件 |
+|---|---|
+| 漂浮与呼吸 | 常驻（`prefers-reduced-motion` 下停止） |
+| `idle` 青色 | 默认 |
+| `alert` 琥珀色 | Agent 正在跑（出现「停止生成」按钮）**或** 输入框里有字 |
+| `happy` 粉色 | 戳她一下 / 双击 / **一轮跑完** |
+| `sleep` 灰色冒 `z` | 静置 `sleepAfterMs`（默认 90 秒）；任意输入唤醒 |
+| 拖动 | 按住本体拖动，带边界约束；**松手即记住位置**，下次刷新回到原处 |
+| 说话 | 挂载问候、点击、睡着、醒来、跑完各有一组台词 |
+
+外层 `pointer-events:none`，只有本体可点 —— 它不会挡住你对应用的操作。
+
+---
+
+## 文件结构
+
+```
+dsh-wisp-plugin/
+├── package.json          dsh.bundle.patch + dsh.client.platform，零依赖
+├── cordis.patch.yml      插入一行 host 入口（指向 dsh-wisp，绝不能是 dsh-wisp/client）
+├── lib/
+│   ├── index.js          host 半包：刻意为空的 ES 模块
+│   ├── client.template.js  浏览器半包源码（唯一需要编辑的文件）
+│   └── client.js         由 build.mjs 生成，勿手改
+├── assets/               四张 256x384 透明 WebP（idle / happy / sleepy / work）
+├── build.mjs             注入精灵图 + 三道构建防线
+├── verify-wisp.mjs       预检：两套契约 + 真实执行
+├── NOTICE.md             角色来源与许可
+└── README.md             本文件
+```
+
+## 构建与预检
+
+```bash
+node build.mjs        # 把 assets/*.webp 注入 lib/client.template.js → lib/client.js
+node verify-wisp.mjs  # 预检；exit 0 = 两半包都符合契约
+```
+
+**改了 `client.template.js` 就必须重新 `build.mjs`** —— `client.js` 是生成物。
+
+`build.mjs` 现在有四道防线，任何一道失败都拒绝写出文件：
+
+1. 占位符 `__SPRITES_LITERAL__` 必须恰好出现一次，且替换后不得残留；
+2. 注入后的 `SPRITES` 表要**真的被求值**，四个 key 都必须是 `data:image/` 开头；
+3. 产物**不得调用被陷阱的全局**（`setTimeout` / `setInterval` / `clearTimeout` / `clearInterval` / `fetch` / `require`）；
+4. `const VERSION` 必须与 `package.json` 的 `version` 一致（防止版本漂移）。
+
+`verify-wisp.mjs` 在真实契约下执行浏览器半包：六个被陷阱的全局以**抛异常**的形式注入，虚拟时钟同时驱动两条调度路径，假 DOM / Blob / localStorage（含"抛异常的存储"这一档）齐全。当前 **98 项全 PASS，exit 0**。
+
+---
+
+## 改形象（素材流水线）
+
+**形象的唯一权威来源是 [tools/CHARACTER-PROMPT.md](tools/CHARACTER-PROMPT.md)** —— 逐字复用的提示词母版 + 四张姿态 + 完整生成参数。改形象 = 改那个文件、重新出图、再跑一条命令。
+
+```bash
+# 1. 按 tools/CHARACTER-PROMPT.md 的参数与提示词，为四个情绪各出一张【绿幕】图，存成 <mood>.png
+# 2. 绿幕 → 抠图 → 四档素材，一步到位（任何一张抠图异常都会以非 0 退出）
+node tools/assets.mjs --from <绿幕母版目录>
+# 3. 打进客户端半包
+node build.mjs --tier=hi     # hi 档 = 2048x3072，与母版同尺寸，仅重新编码
+# 4. 预检
+node verify-wisp.mjs
+```
+
+三条硬约束（实测依据见 CHARACTER-PROMPT.md 与 NOTICE.md）：
+
+1. **不要用服务端的透明背景。** 它会把浅蓝渐变的发梢与鲸尾当背景切掉，表现成"模型跑形"，几乎无法从结果反推。出绿幕、自己抠图 —— 只有 0.4%–0.7% 的边缘像素需要处理，发丝一根不丢。
+2. **不要传参考图。** 形象靠提示词锚定；一条提示词只放一个角色。
+3. **画风别写"高质量二次元插画"这种笼统说法**，它会推向韩系半写实并崩掉设定。
+
+---
+
+## 性能
+
+一切数字都是在真实 Chromium 里量的（合成 10k 节点会话记录，headless、CPU 光栅，即**最不利**的一档）。可复现的探针脚本在 `F:\deepseek对话\_perf\`。
+
+### 稳态
+
+| 指标 | 数值 |
+|---|---|
+| 动画帧使用量 | **0**（走 `timer` 服务，根本不挂帧循环） |
+| 定时器 | 1 个 `interval`（反应轮询）+ 3 个 `timeout` |
+| 反应轮询成本 | **0.44 ms / 次**（每 1.2 s 一次 ≈ 0.04% 单核） |
+| 每帧平均间隔 | 无插件 4.202 ms vs 挂载后 4.207 ms（4 次重复，交替测量） |
+| 每秒 DOM 查询 | `querySelector` 1 次；`querySelectorAll` **0 次** |
+
+前三个数字来自"每次都重新全量查一遍"的老实现时是：`querySelectorAll` 每次都调、1.27 ms/次。现在把输入框元素**解析一次后缓存**（仅在它离开文档时重新解析），忙碌判定从 4 条精确选择器改成 2 条子串选择器 —— 后者还能顺带匹配没见过的语言标签。
+
+### 一次性成本
+
+- **挂载瞬间**有一次约 15–50 ms 的卡顿（headless CPU 光栅下）。来源是注入样式表触发的整篇样式重算 + 首次模糊光栅化，不是稳态开销；预热 1.5 s 后测 6 s，**没有任何一帧超过 20 ms**。
+- 4 张精灵图共 134 KB base64，挂载时只解码用到的 1 张，其余在 1.5 s 后预热。
+
+### 已知的、没修的
+
+- **rAF 兜底路径**在没有 `timer` 服务的壳里，只要还有任务待触发就会保持帧循环（拿不到 `setTimeout`，没有别的唤醒源）。真实 DSH 壳不走这条路 —— `window.__wisp.clock` 若不是 `timer-service` 就是它。
+- 常驻的呼吸动画在 headless CPU 光栅下会让偶发单帧变长（4 次重复里最差 37 ms，平均值不受影响）。GPU 合成的真实窗口里这类 `filter` 通常不花钱。`prefers-reduced-motion` 会关掉全部动画。
+
+---
+
+## 配置
+
+配置写在 profile 的 bundle patch 里（`~/.dsh/profiles/<profile>/cordis.patch.yml`，或本包 `cordis.patch.yml` 的 `insert` 行上），作为 `apply(ctx, config)` 的第二个参数。**全部可选，全部会被夹到合法区间**——写错只会退化成默认值，不会做出一个找不到或点不动的桌宠。
+
+| 键 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `right` | number | `26` | 距右边缘 px（仅首次落位；拖动过之后以记忆位置为准） |
+| `bottom` | number | `46` | 距下边缘 px |
+| `size` | number | `4` | 缩放，限制 `0.4–8`；默认绘制 560×840 CSS px |
+| `sleepAfterMs` | number | `90000` | 静置多久打盹，限制 `5000–3600000` |
+| `reactions` | boolean | `true` | 是否跟随 Agent 忙碌 / 输入框内容变情绪 |
+| `persist` | boolean | `true` | 是否跨刷新记住位置 |
+| `celebrate` | boolean | `true` | 一轮跑完是否庆祝一下 |
+| `celebrateAfterMs` | number | `2500` | 只庆祝跑够这么久的轮次（避免每次小工具调用都跳） |
+| `happyMs` | number | `1100` | 高兴状态持续多久 |
+| `chatterMs` | number | `0` | `>0` 时按此间隔随机说句话；`0` = 安静 |
+| `wander` | boolean | `true` | 空闲时自己小幅踱步 |
+| `wanderMs` | number | `45000` | 多久考虑溜达一次，限制 `5000–3600000` |
+| `wanderRange` | number | `260` | 单次溜达最远距离 px，限制 `0–2000` |
+
+例：
+
+```yaml
+- id: wisp
+  name: "dsh-wisp"
+  config:
+    bottom: 90
+    size: 1.2
+    chatterMs: 300000
+```
+
+### 运行时 API
+
+页面 Console 里 `window.__wisp` 可用：
+
+```js
+window.__wisp.say('你好')                 // 说一句
+window.__wisp.mood('happy')               // idle | alert | happy | sleep
+window.__wisp.configure({ size: 1.5 })    // 部分更新，其余键保持不动
+window.__wisp.move(200, 300)
+window.__wisp.position                     // { x, y }
+window.__wisp.resetPosition()              // 清掉记忆位置，回到右下角
+window.__wisp.clock                        // 'timer-service' | 'animation-frame'
+window.__wisp.destroy()
+```
+
+`window.__wisp.clock` 直接告诉你这台机器走了哪条调度路径，排查时先看它。
+
+---
+
+## 平台契约（踩过的坑都在这）
+
+### 1. 两个文件、两套契约
+
+宿主 **import** `cordis.patch.yml` 里 `name:` 指向的包 —— 必须是合法 ESM，即 `lib/index.js`。
+浏览器半包是**经典脚本**，由 `package.json` 的 `exports["./client"]` 定位、`/plugins` 路由投递，自己调用 `window.__ModuleLoader__.load({ id, factory })` 注册。
+
+**patch 那一行写成 `dsh-wisp/client` 会导致 `failed to import`** ——宿主无法 import 经典脚本。
+
+### 2. 六个全局是抛异常的陷阱
+
+`setTimeout` / `setInterval` / `clearTimeout` / `clearInterval` / `fetch` / `require` 在客户端半包里被**抛异常的形参**遮蔽。所有时序因此来自 Client `timer` 服务：
+
+```js
+ctx.get('timer').timeout(fn, ms)   // → disposer
+ctx.get('timer').interval(fn, ms)  // → disposer
+```
+
+`timer` 服务取不到时（老壳 / 无头壳）退回 `requestAnimationFrame` 截止时间表，**且只在有任务待触发时才挂帧**——原来那种常驻 60fps 帧循环会让桌面进程每秒白醒 60 次。
+
+`ctx.get('theme')` 与 `ctx.on('theme/change')` 用来跟随明暗；`body[data-ds-dark-theme]` 是兜底（这是壳真的会写的属性）。
+
+### 3. 精灵图必须走 `blob:`，不能直接给 `data:`
+
+初版把 base64 data URI 直接赋给 `img.src`：插件"挂载成功"、DOM 正确、光晕正常，**图是碎的**。字节经校验无误，是这个壳拒绝 `data:` 作图片源。现在解码成 `Blob` 再取 object URL，拆解时 `revokeObjectURL` 释放，**并把缓存条目一起删掉**——blob 缓存是模块级的，而挂载是每次 apply 一次，只 revoke 不删键会让下一次挂载拿到已吊销的 URL，又变成碎图。
+
+### 4. 一次性实例
+
+`apply` 会先销毁已存在的 `window.__wisp`。HMR 重挂、重复行、以及注入版残留都会走到这条路径，否则会叠出第二只。
+
+### 5. 反应信号取自 DOM 事实
+
+- 忙碌：`button[aria-label*="停止"],button[aria-label*="Stop"]` —— 壳自己的「正在跑」按钮（zh 标签是"停止生成"，en 是 "Stop generating"）。用子串而不是枚举精确标签，是因为标签会被翻译，而且实测 2 条子串选择器比 4 条精确选择器便宜 40%，覆盖反而更宽；
+- 输入框有字：`[data-composer-input]`（依次回退到 `textarea`、`[contenteditable="true"]`）——**解析一次后缓存**，只在元素离开文档时重新解析。
+
+两者都是壳为自家用户渲染的东西，比内部服务契约更抗版本升级。
+
+---
+
+## 安装
+
+**从 npm 装（推荐）** —— 这是**唯一不需要访问 GitHub** 的方式。在「添加插件」对话框里，把**安装源**设为 **中国大陆镜像源**（`registry.npmmirror.com`），然后填**包名**：
+
+```
+dsh-wisp
+```
+
+**从 GitHub 装** —— 需要能访问 github.com：
+
+```
+plugin_manager install_bundle  https://github.com/969246694/dsh-wisp
+```
+
+**从本地路径装** —— 桌面版 profile 归 Electron 独占管理，`dsh plugin --profile desktop` 会被拒绝，所以走 GUI：**插件管理页 → 添加插件 → 填本目录绝对路径**。本地路径安装不下载任何包。
+
+> **为什么镜像源只对 npm 那条路有用**：GitHub 地址被归类为 **git 规格**，由 `git` 拉取，**完全绕过 npm**——「安装源」那个设置对它无效。
+
+装完**刷新页面**（`Ctrl+Shift+R`）即可拿到浏览器半包——`/plugins` 路由的 `rev` 由文件 `mtime` 驱动，必然变化。宿主半包（`lib/index.js`）的改动才需要完全退出托盘进程重启。
+
+### 装好后这样验
+
+- [ ] 右下角出现发光桌宠
+- [ ] Console 有 `[wisp] mounted — DeepSeek娘 v0.5.0 (timers: …)`，且括号里是 `timer-service`
+- [ ] 打字 → 变琥珀色；清空 → 回青色
+- [ ] 让她跑一轮 → 结束时会庆祝一下
+- [ ] 拖到别处 → 硬刷新 → **还在原处**
+- [ ] `window.__wisp` 存在
+
+---
+
+## 变更
+
+### 0.6.0
+
+- **新增"自己踱步"**：空闲且 agent 不在跑时，她会每隔 `wanderMs` 考虑溜达一次，走到 `wanderRange` 以内的随机位置 —— 用 CSS 过渡**滑行**过去而不是瞬移；被拖拽、睡着、忙碌时一律不动。**踱步不写入记忆位置**：记忆的是"你把她放在哪"，不然刷新后她会出现在一个你没选过的位置
+- **新增右键归位**：她放大到 560×840 之后很容易被拖到看不见的地方，而"恢复位置"原先只能开 Console —— 现在右键她本体即可回到右下角默认位
+- 被拖放后会随机说一句（35% 概率）
+- 预检增至 108 项（踱步范围/滑行类名/不覆盖记忆位置/睡着不动/右键归位/关掉就不动）
+
+### 0.5.0
+
+- **素材流水线收进插件**（`tools/`）：`CHARACTER-PROMPT.md` 成为形象的唯一权威来源（逐字复用提示词 + 四姿态 + 生成参数），`assets.mjs` 一条命令完成「绿幕 → 抠图 → 四档素材」，任何一张抠图异常都会以非 0 退出而不是悄悄混进包里；`keyout.mjs` 可单独抠一张调试
+- **情绪切换改为交叉淡入淡出**：原来直接换 `src`，观感像闪一下；现在旧精灵保留独立图层淡出后再移除
+- **每个情绪有自己的动作**：happy 改成 1.15s 小跳，alert 呼吸加快到 4.6s，sleep 仍是 9s 慢呼吸
+- 预检增至 98 项（新增交叉淡入淡出的两层/回收断言）
+
+### 0.4.0 – 0.4.4
+
+- 尺寸从 140×210 放大到 560×840（`size: 4`，上限提到 8）
+- **修复 `transform` 位移写错导致的"挪不动"**：位移是原点无关的，之前按"重心原点"补了半格导致绘制位置与命中区错开半个身位；同时补上行内关键样式，避免样式表未生效时把她所在的层变成文档流元素、把页面撑出滚动条（实测旧行为可达 3292px）
+- 抠图质量：弃用服务端透明背景，改绿幕 + 本地抠图（发梢与鲸尾不再被切掉）
+- 形象更新：深蓝超长双马尾 + 鲸鱼鳍耳饰 + 单薄性感女仆装 + 商业级高精度二次元画风
+
+### 0.3.1
+
+- **反应轮询成本降到 1/3**（实测 1.27 ms → 0.44 ms 每次）：输入框元素改为**解析一次后缓存**，不再每次全量 `querySelectorAll`（现在每秒 0 次 NodeList 收集）；忙碌判定由 4 条精确选择器改为 2 条子串选择器（顺带覆盖未预见的语言标签）
+- **去掉常驻 `will-change: transform`**：只在真的拖动期间挂合成提示，不再为几乎不发生的事件常驻一个合成层
+- `paint()` 不再每次重写永不变化的 `transform-origin`
+- 新增 3 项预检守卫：已解析的输入框不得每帧重查、一次 tick 不得收集 NodeList、无输入框时每 tick 最多一次探测
+
+### 0.3.0
+
+- **调度改用 Client `timer` 服务**，rAF 降级为兜底且只在有待触发任务时挂帧 —— 去掉常驻帧循环与每次 `pointermove` 重建定时器的开销
+- **修复 `nowMs` 混用两个时钟源**：`window.performance && performance.now()` 在壳自带 `window` 的场景下会用两个时间基准算/比截止时间，导致**任何定时器都永不触发**；现在只经 `window.performance` 读取
+- **修复重挂载碎图**：blob 缓存改为吊销时一并清键（模块级缓存 × 每次 apply 挂载的交叉 bug）
+- 新增：位置记忆、跑完庆祝、`configure()` 部分更新、`resetPosition()`、`clock` / `position` / `currentMood` 只读查询
+- 新增：`theme` 服务订阅，气泡与文字改用 `--dsw-alias-*` 主题 token（带手调兜底）
+- 新增：忙碌判定改用壳真实的「停止生成」按钮标签
+- 加固：配置区间夹取（坏配置退化为默认值而非 NaN 几何）、`document.body` 未就绪时有限重试、存储不可用（不透明源）时优雅降级
+- `build.mjs` 增加陷阱全局与版本漂移两道防线；`verify-wisp.mjs` 重写为六陷阱注入 + 虚拟时钟双路径驱动
+
+### 0.2.1
+
+- 精灵图内嵌；blob URL 修复碎图；`ctx.effect` 拆除钩子
+
+### 0.2.0
+
+- host 半包清空为零依赖；patch 指向 host 半包（修 `failed to import`）
+
+### 0.1.0
+
+- 初版（纯 DOM 注入版）