dsh-whale-maid
适用于 DeepSeek Harness 的鲸鱼女孩桌面宠物：十二种精灵动画、工作状态联动、成长、成就和天气伙伴。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:lov0vo/dsh-whale-maid#d3f77231faa4370acb3491fb4a20d53908873543
Whale Maid 以 dsh-whale-maid 发布，当前版本为 2.3.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
把 DeepSeek 插件市场页面右下角那只鲸鱼女仆完整提取出来，做成 DSH（DeepSeek Harness）的桌面宠物插件。
不是一张静态图片：10 组精灵图集 + JS 状态机，眨眼、欢呼、吃东西、玩耍、思考、入睡、醒来、左右漫步、拖动摇摆全部保留。
从 1.1.0 起，她还会跟着你的工作状态变姿势、记心情与好感、每天签到、解锁成就、在你久坐或深夜时主动说一句——这些是在原版提取之上新增的陪伴层，原有动作与交互一个没改。
预览：idle / joy / sleep / walk 四个姿态
idle（含随机眨眼）、joy、eat、play、welcome、drag（拖拽摇摆）、think（浮动 + 问号）、work（敲全息面板）、sad（垂头丧气）、sleep（打呼噜）、wake、walk（乒乓漫步）localStorage，重开仍在原处--dsw-alias-*），深色/浅色主题都自适应设置 → 鲸鱼女仆，可调显示形态、尺寸、动画速度、气泡停留时长、气泡打字机、气泡语言，以及问候/漫步/睡眠开关设置 → 鲸鱼女仆 → 显示形态 里切换。
悬浮（默认）：原来的自由摆放，可拖动、会自己散步。底栏：贴在输入框上方、靠右对齐，96px。侧边：挂在聊天栏右缘、略高于中线，72px。迷你：56px 小号版，菜单按钮同步缩小，仍可拖动。自动：有输入框时按「底栏」摆放，没有输入框（例如设置页）时回到悬浮。display:none，是它最常见的「宠物不见了」反馈。size 仍然优先于形态默认值。think 姿态并在宠物左侧冒出状态小标签（如「工具在跑…」「搞定啦」）。工作期会说话，收尾会欢呼或安慰；关掉对话视图后仍在跑的任务用宽限期兜住，不会一秒三变。localStorage。心情随工作与互动涨落，饱食随时间下降。动作：drag / think / work / sad 原本只有一帧（靠 CSS 整图运动假装在动），现在各补成 3 帧——用原图按「缩放 1.00→1.02、上下 2px、旋转 ±1°」生成的伪帧，锚点固定在脚底中心，所以角色是在呼吸而不是在飘。十二个状态全部有逐帧动画，没有为动画新生成任何美术。
天气陪伴（工程部分）：
geocoding-api.open-meteo.com 把城市名转经纬度，api.open-meteo.com 取当前天气；fetch 单向拉取，无账号、不上传任何本地数据（只把城市名/坐标发给你请求的那个公开接口）。天气陪伴（体感部分）：
joy、多云/雾 → think、雨/雪/雷 → sad（撑伞、缩脖子、发抖、流汗这四种专属姿态需要新美术，暂缓，见下）；☔ / ❄），晴天撒阳光星屑，不新增气泡；城市：先试系统定位（8 秒超时），失败则用设置里的城市名（默认 北京）。两条路径都可用，城市随时可改。
1.3.0 暂缓项（都需要新美术，按约定本轮不生成）：
| 项 | 卡在哪一步 |
|---|---|
| 雨 → 撑伞 | 需要 rain-umbrella 立绘 |
| 雪 → 缩脖子 | 需要 snow-hunch 立绘 |
| 雷 → 害怕 | 需要 thunder-scared 立绘 |
| 冷/热 → 发抖/流汗 | 需要 cold-shiver / hot-sweat 立绘 |
| 19 个新姿态的静态立绘 | 已生成 2/31（success、celebrate），其余待生成 |
以上暂时用现有姿态（sad / think / joy）代偿，等美术补齐后再替换。
这一版把「四批计划」里所有不需要新美术的项做完了，外加存档导出/导入。
| 项 | 做了什么 |
|---|---|
engines.dsh | package.json 声明 ">=0.2.1-rc.1"，装到过旧的宿主上会提前报错，而不是在渲染时神秘失败 |
| CI | .github/workflows/ci.yml：Node 20/22/24 上 node build.mjs + 构建产物一致性检查 + node --test |
| 无障碍 | 宠物可 Tab 聚焦；Enter/Space 打招呼；Alt+↑↓←→ 每次移动 16px 并持久化位置；:focus-visible 有描边 |
| 心情分层 | 由 2 档扩到 5 档（moodLow / moodLowMid / moodMid / moodHighMid / moodHigh），moodTier() 返回 0–4 |
| 成就 | 41 → 55 条（等级、连续签到、台词、陪伴时长、天气、错误率等） |
| 工作期光晕 | 工作相位时在精灵下方加一层呼吸光晕（.dwm-glow），prefers-reduced-motion 下关闭 |
| 台词 | 546 → 600 条（每语言），新增心情 5 档与更多工作/关怀分支 |
| 唤回入口 | 宠物隐藏后右下角留一个 🐋 按钮，点一下回来（hidden 开关） |
| locale 服务 | locale/zh.json / locale/en.json 改为 gettext 风格（键=中文原文，43 条），设置面板文案可被翻译 |
| 结构快照测试 | test/snapshots/pet-tree.txt 记录浮层元素树；另有「源码里用到的每个 dwm- 类都必须有 CSS 规则」检查 |
| 存档导出/导入 | 设置面板「存档」区块：导出 JSON / 导入 / 清空，覆盖全部 dsh-whale-maid:* 键 |
测试数 28 → 34，全部通过。client.js 约 3.1 MB。
ReferenceError 并导致整个浮层槽位被卸载。已把别名提升到模块作用域，并加了静态回归测试。.dwm-pop 改为按内容宽度布局（上限 250px）。idle。typewriter，默认开启，设置面板可关）。1.1.0 里工作状态是「借图」实现的：工具在跑时借 play（举球），失败时借 drag（拖拽摇摆）。语义对不上，所以 1.2.0 补了两张专属姿态，其余十张原样保留：
work（敲全息面板）：工具运行中（preparing / running）与「正在执行」相位显示。双手抬在胸前敲一块半透明浅蓝全息面板，头微低、视线落在面板上、眉心微蹙，带 float 呼吸浮动。sad（垂头丧气）：工具报错、任务失败、心情触底时显示。垂肩、双手在身前交叠、头略低并微微侧倾、上眼睑下垂、眉心内侧上挑、嘴角下撇，太阳穴旁一滴汗。tool → work、failure → sad；成功相位继续用 joy（语义本来就对）。会话结束时不再播放 drag，改为播放 sad。dwmPlaySequence 把姿态写进 dsh-whale-maid:state 事件，只是没人渲染。这两张图的画风、配色、2.5 头身比例、线宽、脚底基线与原有十张完全对齐（角色高 225px、脚底贴 y=256、水平中心 x=128），可以直接换用你自己的角色图，见「换成你自己的角色」。
DSH 桌面端的插件分两半：index.js（Host 半边，空实现，只为让 Loader 挂载包）和 client.js（浏览器半边，宠物本体）。安装即「让 profile 挂上这个 bundle」。
plugin_manager 工具）action: install_bundle
target: <本仓库的绝对路径>
C:\Users\Administrator\.dsh\plugins\dsh-whale-maid（目录名要与 package.json 的 name 一致）。package.json（C:\Users\Administrator\.dsh\profiles\desktop\package.json）：
dependencies 里加 "dsh-whale-maid": "file:C:/Users/Administrator/.dsh/plugins/dsh-whale-maid"dsh.profile.bundles 数组里加 "dsh-whale-maid"node_modules 里（复制目录，或在该 profile 下跑一次 pnpm install）。Ctrl+R）。profile 的 dsh.profile.patchReload 为 live 时，改 client.js 后刷新即生效，不用重启应用。二选一：
dsh.profile.bundles列表和cordis.patch.yml的insert是两条并行的挂载路径。同时用会让同一个 row id 被挂两次，出现两只宠物。手工安装时只选其中一种。
dsh.profile.bundles 移除 dsh-whale-maid（或在该 bundle 的 patch 行上加 disabled: true），重载窗口。plugins\dsh-whale-maid 与 profile 的 node_modules\dsh-whale-maid，再清掉 package.json 里的依赖项。| 操作 | 效果 |
|---|---|
| 单击 | 随机说一句问候，展开「喂食 / 玩耍」菜单 |
| 按住拖动 | 跟着指针走，身体按指针相对位置倾斜（最多 ±10°），松手落位并记忆 |
| 喂食（🐟） | 冒爱心，播放吃东西动画；feeds % 5 === 0 时触发里程碑台词 |
| 玩耍（🎮） | 冒爱心，播放抛接球动画 |
点空白 / Esc | 关闭菜单 |
| 长时间不操作 | 60 秒后趴下睡觉；点击会先播「醒来」再「欢呼」 |
| 点不同部位 | 9 个命中区各自的台词 + 粒子（心 / 闪光 / 音符），见下方「部位互动台词」 |
| 1.2 秒内连点三次 | 三连击庆祝（星星 + 爱心 + 专属台词） |
宠物会自己走动，所以位置不总是右下角——这是原始行为。
可点击区按立绘量过，共 9 个。命中矩形写在 src/zones.js 的 DWM_ZONES 里，坐标归一化到精灵帧（0–1），所以宠物放大缩小都点得准；列表从上到下先命中先返回，窄部位排在包住它的大块之前。一个矩形都没命中时回落到 belly。
区 id | 部位 | 矩形数 | 台词库（新 + 原） |
|---|---|---|---|
horn | 呆毛 | 1 | patHorn + patHead |
ear | 鳍耳 | 2（左右） | patEar + patHead |
face | 脸 | 1 | patFace + patHead |
head | 头 / 头发 | 3（发饰带 + 两侧长发） | patHeadPart + patHead |
waist | 腰（腰带） | 1 | patWaist + patBelly |
hand | 手 | 2（左右） | patHand + patBelly |
belly | 围裙 / 腹 | 1（默认区） | patBellyPart + patBelly |
feet | 脚 | 1 | patFeet + patBelly |
tail | 鲸尾 | 1 | patTailPart + patTail |
台词库分三处，互不覆盖：
src/lines-parts.js（DWM_LINES_PARTS，9 个库，每库 14 条中文 + 6 条英文，合计 180 条）；patHead / patBelly / patTail 仍留在 src/lines.js，一句没删；src/lines-parts.js 末尾把新库 concat 进 DWM_LINES，所以是追加，不是替换；src/zones.js 的 DWM_ZONE_BANK，值现在是数组，由 dwmPickLineFrom(banks, language) 把几个库并成一个池子随机抽，并避开上一次抽到的那条。口径：鲸鱼女仆对主人说话，可以 teasing、可以暧昧，但不写露骨内容；每句最多一个 emoji，中文台词不带 emoji（与原版一致）。
设置页：设置（Ctrl+,）→ 左侧「鲸鱼女仆」。改动即时生效，存在 localStorage['dsh-whale-maid:options']。
| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
size | number | null | null | 像素尺寸 24–320；null = 响应式（桌面 110px，窄屏 72px） |
speed | number | 1 | 动画与漫步速度倍率 0.2–3 |
bubbleDuration | number | 4500 | 气泡停留毫秒数 1000–10000 |
typewriter | boolean | true | 气泡文字逐字显示（false = 整句直接出现） |
city | string | '北京' | 定位失败时用于查天气的城市名（1.3.0） |
mode | 'float' | 'bar' | 'side' | 'mini' | 'auto' | 'float' | 显示形态（2.3.0）；底栏 96px、侧边 72px、迷你 56px，显式 size 优先 |
language | 'auto' | 'zh' | 'en' | 'auto' | 气泡文案语言，auto 跟随界面 |
greeting | boolean | true | 首次打开是否主动打招呼 |
walk | boolean | true | 是否允许随机漫步 |
sleep | boolean | true | 是否允许空闲入睡 |
greetings | string[] | null | null | 自定义问候语池，null 用内置文案 |
设置页：设置（Ctrl+,）→ 左侧「鲸鱼女仆」。存在 localStorage['dsh-whale-maid:companion']。
| 键 | 类型 | 默认 | 说明 |
|---|---|---|---|
workLink | boolean | true | 是否跟随工作状态换姿态（关掉后她只做原版的 idle 生活） |
workHold | number | 6000 | 切走对话视图后的宽限毫秒数，避免后台任务被误判结束 |
workSpeech | 'chatty' | 'quiet' | 'off' | 'chatty' | 工作期说话频率：话痨 15–40s / 安静 90–240s / 不说 |
idleChat | boolean | true | 是否 5–8 分钟主动闲聊一次 |
care | boolean | true | 主动关怀（久坐 / 卡住 / 深夜 / 饿了 / 回来） |
chip | boolean | true | 是否显示宠物左侧的状态小标签 |
zones | boolean | true | 是否启用分区点击反应 |
achievements | boolean | true | 是否记录成就与成长日记 |
lateNight | boolean | true | 深夜（23:00–5:59）是否安静一点 |
这些开关只影响陪伴层。关掉全部开关后，宠物的行为与 1.0.0 完全一致。
1.4.0 追加四个方法：
exportSave() → 返回存档 JSON 字符串（{ schema: "dsh-whale-maid/save", version: 1, data: {...} }）importSave(text) → { ok: true } 或 { ok: false, reason: "not-json" | "wrong-schema" | "wrong-version" }clearSave() → 清空本插件全部存档键moodTier() → 当前心情档位 0–4渲染进程里可用 window.dshWhaleMaid：
dshWhaleMaid.getOptions() // 当前配置
dshWhaleMaid.setOptions({ speed: 1.5 }) // 合并写入并广播
dshWhaleMaid.say('自定义台词') // 让宠物说一句
dshWhaleMaid.resetPosition() // 回到右下角
dshWhaleMaid.feeds() // 已投喂数量
dshWhaleMaid.forget() // 清空全部存储（位置/投喂/配置/成长/陪伴开关）
1.1.0 追加（原有方法签名一个未改）：
dshWhaleMaid.companion() // 陪伴开关快照
dshWhaleMaid.setCompanion({ chip: false }) // 改开关
dshWhaleMaid.growth() // 等级/心情/饱食/好感/任务/成就/日记快照
dshWhaleMaid.signin() // 今日签到（已签返回 null）
dshWhaleMaid.claimQuest(0) // 领取第 1 个已完成任务
dshWhaleMaid.resetGrowth() // 清空成长数据
dshWhaleMaid.work() // 工作状态探测器当前判断
dshWhaleMaid.scanNow() // 立刻重扫一次 DOM（排查用）
dshWhaleMaid.diagnose() // 上面全部 + 当前姿态/帧，一次性 dump
dshWhaleMaid.zoneAt(0.85, 0.7) // 归一化坐标落在哪个区（'tail'）
dshWhaleMaid.probe('今天写了好多代码') // 这句话会被判成什么话题 / 命中哪个关键词
dshWhaleMaid.chip('工具在跑…', 'work', 3000)// 手动弹一个状态小标签
dshWhaleMaid.fx('star', 6) // 手动撒粒子：heart / star / sparkle / note
dshWhaleMaid.pose('joy', 1500) // 强制某个姿态（hold=true 则一直保持）
1.3.0 追加：
dshWhaleMaid.weather() // 缓存的天气记录（无则 null）
dshWhaleMaid.refreshWeather() // 立刻重新拉一次（同面板按钮）
dshWhaleMaid.setCity('上海') // 改备用城市并立即刷新
2.3.0 追加：
dshWhaleMaid.modes() // 形态清单 + 锚点选择器 + 纯函数几何计算（可在无 DOM 环境断言）
参考插件按「姿态名」组织立绘，本插件按「状态」组织精灵表。为了让两边能对上，下表把 27 个姿态逐一映射到本插件的图片来源。
| 姿态 | 图片来源 | 说明 |
|---|---|---|
idle | 精灵表 idle.png | 3 帧待机 |
waiting | src/sprites/poses/waiting.png | 独立立绘 |
thinking | 精灵表 think.png | 3 帧（伪帧）+ 浮动 |
tool | 精灵表 work.png | 3 帧（伪帧）+ 浮动 |
success | poses/success.png | 独立立绘（早前借 joy） |
failure | 精灵表 sad.png | 3 帧（伪帧） |
curious / teasing / afk / blush / angry / star | poses/<名字>.png | 独立立绘 |
eat | 精灵表 eat.png | 3 帧 |
celebrate | poses/celebrate.png | 独立立绘（早前借 joy） |
sleep | 精灵表 sleep.png | 2 帧 |
greet | 精灵表 welcome.png | 2 帧 |
night / wink / bold / abstract / sweep | poses/<名字>.png | 独立立绘 |
workSlack / workRam / coolShades / workPat / balanceLow | poses/<名字>.png | 独立立绘 |
hidden | —— | 参考插件里是 null，本插件用 hidden 开关 + 🐋 唤回按钮实现 |
src/sprites/poses/里的 19 张已生成、抠图、归一化到与精灵帧完全相同的规格（角色高 225px、脚底贴y=256、x=128居中），并由src/pose-map.js的「场合 → 姿态」映射表接进状态机（详见下文「场合 → 姿态映射」）。每个文件现在是 768×256 的三格横排，循环播放方式见「立绘的 3 帧循环」。
| 状态 | 精灵图 | 帧数 | fps | 播放方式 | 触发 |
|---|---|---|---|---|---|
idle | idle.png | 3 | 2 | blink（随机眨眼） | 默认待机 |
joy | joy.png | 2 | 5 | loop | 点击、动作收尾 |
eat | eat.png | 3 | 8 | loop | 喂食 |
play | play.png | 3 | 4 | loop | 玩耍 |
welcome | welcome.png | 2 | 3 | loop | 首次问候 |
drag | drag.png | 3 | 5 | loop + tilt | 拖动中（1.3.0 起 3 帧伪帧） |
think | think.png | 3 | 2 | loop + float | 空闲思考（1.3.0 起 3 帧伪帧） |
work | work.png | 3 | 2 | loop + float | 工具运行中（1.2.0 加姿态，1.3.0 起 3 帧） |
sad | sad.png | 3 | 2 | loop | 工具报错 / 任务失败（1.2.0 加姿态，1.3.0 起 3 帧） |
wink | 眨眼 | 1 | 2 | loop | |
sleep | sleep.png | 2 | 1 | loop | 空闲 60s |
wake | wake.png | 2 | 3 | once | 睡眠中被点击 |
walk | walk.png | 3 | 6 | ping-pong | 随机漫步 |
src/sprites/poses/ 里的 19 张姿势立绘不再是单张静止图：每个文件现在是 768×256 的横排三格，每格 256×256，与原精灵帧同规格。
drag / think / work / sad 已经用过的伪帧配方：缩放 1.00 → 1.02、纵向偏移 0 → −2px、旋转 −1° → +1°，锚点固定在脚底中心，所以脚不会飘。_tmp/whale-gen/pseudo_poses.py（不随包发布）；2.1.0 起这 19 张已改成逐帧真重绘，那条伪帧配方只留作历史。现在的管线在仓库里：tools/art/，见 tools/art/README.md。@keyframes dwm-pose-cycle 以 background-size: 300% 100% 把 background-position 依次走到 0% → 50% → 100%，每轮 0.9 s，再与原有的 dwm-portrait-float 浮动叠加。prefers-reduced-motion 下整段动画关掉，并钉在第 0 帧。dwmPortraitShow（src/runtime.js）现在建的是带背景图的 div[data-dwm-portrait]，不再是 <img>；该层 pointer-events: none、z-index: 60，不会吃掉点击或拖动。dsh-whale-maid/
├── index.js Host 半边：空 apply，只为让 Loader 挂载并暴露 dsh.client
├── client.js 浏览器产物（约 313 KiB，由 build.mjs 生成，勿手改）
├── cordis.patch.yml 手工安装用的 insert 行
├── package.json 清单：exports / files / dsh.bundle / dsh.client
├── build.mjs 构建脚本：校验 PNG 尺寸 → 复制到 assets/ → 拼 client.js
├── tools/
│ ├── art/ 美术管线（生图 → 抠图 → 拼表 → 修帧序 → 质检），见 tools/art/README.md
│ └── asset-qc.mjs 资源质检，`npm run qc` 调它
├── src/
│ ├── care.js 13 KB
│ ├── fx.js 3 KB
│ ├── growth.js 25 KB
│ ├── lines-mood.js 3 KB
│ ├── lines-more.js 37 KB
│ ├── lines-parts.js 9 KB
│ ├── lines-weather.js 5 KB
│ ├── lines.js 21 KB
│ ├── locale-table.js 10 KB
│ ├── panel.js 19 KB
│ ├── pet.css 23 KB
│ ├── pet.js 42 KB
│ ├── plugin.js 8 KB
│ ├── portable.js 4 KB
│ ├── pose-map.js 3 KB
│ ├── preview.js 3 KB
│ ├── runtime.js 15 KB
│ ├── settings.js 7 KB
│ ├── signals.js 15 KB
│ ├── weather-ui.js 4 KB
│ ├── weather.js 18 KB
│ ├── zones.js 7 KB
├── assets/preview.png README 预览图（由精灵图合成，非界面截图）
├── CHANGELOG.md
├── LICENSE MIT（仅代码）
└── README.md
node build.mjs
产物写入 client.js。构建时会校验每张精灵图的像素尺寸是否等于 帧数 × 256，尺寸不符直接失败——防止放错图导致画面错位。
build.mjs 按固定顺序把 src/ 下的脚本拼进同一个闭包（runtime → lines → lines-more → lines-mood → lines-weather → lines-parts → growth → fx → portable → pose-map → preview → pet → settings → panel → weather → weather-ui → locale-table → signals → care → zones → plugin），所以它们之间可以直接互相调用函数声明，但不能写 import / export（构建会直接报错）。
node --test test/companion.test.mjs
测试不是 mock 组件，而是把真实的 client.js 载进一个 stub DOM（window / document / localStorage / MutationObserver / requestAnimationFrame + React stub），跑真实的 apply(ctx)，再通过公开 API 驱动。覆盖：三个 slot 注册、样式注入与清理、1.0.0 API 默认值不变、陪伴开关持久化、成长快照形状、签到幂等、任务领取门禁、工作状态机（含宽限期与错误基线）、forget 清键、所有 effect 的 disposer 不抛。
npm run qc # 等价于 node tools/asset-qc.mjs，零依赖，CI 在 node build.mjs 之后跑
六项检查，任一失败即退出码 1：帧表——每张精灵图是否等于 build.mjs 里 SHEETS 声明的 帧数 × 256，少文件或多出未声明的图都算错；立绘——poses/*.png 是否都是 768×256，pose-map.js 要用的姿态有没有图或可用的回退动作；墨迹——每帧是否贴底（y≥254）且水平居中（128±12），帧高差 ≤2px（手绘原稿 ≤4px）；绿幕——有没有残留的 chroma-key 绿像素（每帧上限 4）；独立性——相邻帧剪影 IoU 是否过高（同一张图冒充动画，>0.985）或过低（画串了，<0.30）；一致性——assets/ 是否与 src/sprites/ 逐字节相同，防止改了图忘记重新构建。
src/sprites/ 里的帧不是手绘的：由 tools/art/ 下的一套脚本从绿幕生图抠出来、归一化、拼表。管线顺序、归一化契约、质量闸门和授权说明都在 tools/art/README.md。
最短路径（python 换成你的解释器，Windows 上可能不在 PATH 里）：
# 1. 改 tools/art/jobs.example.json（或另写一份），先看计划：不联网、不写盘
python tools/art/gen.py tools/art/jobs.example.json --dry-run
# 2. 真跑：提交 → 轮询 → 抠图 → 拼表
python tools/art/gen.py tools/art/jobs.example.json
# 3. 修帧序与点击配准表，再质检
python tools/art/fix_anim.py --dry-run && python tools/art/fix_anim.py
python tools/art/qc_look.py && python tools/art/audit_assets.py
# 4. 重新构建
node build.mjs
只有 gen.py 需要联网与密钥（DSH_CREDENTIALS 或 --credentials）；不想调生图模型的话，自己画好 256×256 的帧交给 compose_frames.py 和 fix_anim.py 就行。注意 fix_anim.py 会改写 src/zones.js 里的 DWM_HIT_REG 块，跑完看一眼 git diff。
1.1.0 的陪伴层是参考 Sutera-Diffusus/dsh-whale-musume 的功能行为做的，仅此而已：
| 项目 | 情况 |
|---|---|
| 参考了什么 | 功能清单与交互范式：忙闲联动、心情/好感/饱食、每日任务、签到、成就、分区点击、主动关怀、话题闲聊 |
| 没参考什么 | 它的代码、立绘、台词、数值表。台词全部为本仓库原创撰写，立绘仍是原站那 10 组精灵图 |
| 没有照搬的能力 | 五种形态切换（悬浮/侧栏/底栏/迷你）、拖拽惯性物理、TTS 播报、天气陪伴、三个小游戏、跨端存档迁移——见下方「未纳入的功能」 |
| 素材授权 | 参考插件是 MIT，但其立绘不适用；本仓库不引入它的任何素材，故不受其影响 |
| 功能 | 为什么不加 |
|---|---|
| 五种形态切换（悬浮/侧栏/底栏/迷你/自动） | 要改 shell.overlay 的定位模型与现有拖拽落位逻辑，属于改既有行为，超出「只增不改」的边界 |
| 拖拽惯性物理、边缘抓住 | 同上，会重写现有 pointer 三件套 |
| TTS 播报 | 依赖第三方 dsh-xiaomi-tts 插件，装了才有声音；无依赖原则下不做 |
| 天气陪伴（Open-Meteo） | 需要联网请求，与「零网络」冲突 |
| 三个小游戏 | 需要新美术与计分 UI，工作量与素材风险都大 |
| 跨端存档迁移 | 与「只写本机 localStorage」的隐私口径冲突 |
| 唤回入口（关掉后留 🐋 按钮） | 需要新增浮层常驻按钮，属于新 UI 面，留待后续 |
针对「动作和设计稿不一致 / 热区点不到 / 播放时尺寸跳 / 幅度过大 / CI 一直红」做的五项修复。
| 问题 | 原因 | 处理 |
|---|---|---|
| 姿势立绘服装不一致 | 三张表在各自姿势参考下重绘，袜子被画成深蓝 / 近白 / 裸腿 | 9 帧全部从设计帧重新生成，袜子颜色写成硬约束 |
| 播放时尺寸跳 | 同表各帧高度不一（最大差 8px） | 按表内最高帧统一，只做 ≤20% 缩放；≤2px 的差保持原样 |
| 热区点不到 | 配准表缺 wink#1/wink#2，且数值量自旧伪帧 | 按当前 13 张动作表 + 19 张姿势表逐帧重算（88 行），改用 alpha 质心配准 |
| 未命中乱归因 | 兜底固定成 belly | 改为几何最近的矩形 |
| 动作幅度过大 | drag 5fps 且叠 tilt、立绘 0.9s 一轮 | drag 2fps 去 tilt、play 3fps、wink 1.5fps、立绘 1.4s |
| CI 一直失败 | 仓库里的 bundle 带 CRLF，Linux 重建是 LF | build.mjs 读源时统一换行 + 产物校验无 CR |
动作表与姿势表的逐帧几何（高度、底边、质心、绿边像素）由 _tmp/whale-gen/ 下的脚本核对；配色核对脚本 qc_look.py 以「绝对矩形 + 用 8 张原始表标定容差」的方式筛查，它是筛查工具不是判据：坐姿、侧视这类姿势会让腿部矩形落在裙子上，最终以目视为准。
13 张动作精灵表全部为 3 帧真实重绘（sleep / joy / eat / play / welcome / wake / walk 保留原版帧数），19 张姿势立绘也全部换成 3 帧独立绘制。此前 drag / think / work / sad 是「单帧 + 程序化微动」、19 个姿势是「同一张图缩放/位移/旋转」的伪帧，现已全部替换。
帧独立性可用 tools/art/verify_frames.py 复核：相邻帧轮廓 IoU 越高越像伪帧，真实重绘一般在 0.5–0.95。
| 差异 | 原因 |
|---|---|
精灵图走宿主只读路由 /api/dsh-whale-maid/assets，不内联进 client.js | 渲染进程是 sandbox，nodeIntegration: false，读不了磁盘；原站靠站点静态目录，插件里改由宿主半边 index.js 注册路由提供，client.js 因此只有约 313 KiB |
样式变量桥接到 --dsw-alias-* | 原站用站点自己的 CSS 变量；插件内改用 DSH 主题 token，并保留原值作兜底 |
所有选择器加 .dwm-root 前缀 | 宿主 shell 有 button[attr] 这类特异性 0,1,1 的规则，会压过单类选择器，导致菜单按钮变形 |
高光层用当前帧做 mask-image | 原站浅色页面下 #ffffff42 高光几乎不可见，深色主题下会变成一个浅色圆角方块 |
| 新增设置页分区 | 原站没有可调项；这里把尺寸/速度/语言暴露出来 |
| 新增陪伴层（1.1.0） | 原站只有基础桌宠行为；陪伴层是新增，全部可关，关掉后与原版一致 |
角色美术不属于本仓库，也不在 MIT 许可范围内。
/pet/whale-girl/{idle,joy,eat,play,welcome,drag,think,sleep,wake,walk}.png，单帧 256×256，横向排列src/sprites/*.png 或 assets/preview.png 用于商业用途、二次分发、周边制作或再授权；src/sprites/ 下的全部素材。删除后插件代码仍可运行，只需换成你自己的同名精灵图。index.js、build.mjs、src/*.js、src/pet.css、client.js 等代码部分以 MIT 发布，见 LICENSE。MIT 仅覆盖代码，不覆盖 src/sprites/ 与 assets/preview.png 中的角色美术。
idle / joy / eat / play / welcome / drag / think / work / sad / sleep / wake / walk），单帧 256×256，文件名与 src/sprites/ 现有文件一致；build.mjs 的 SHEETS 表与 src/pet.js 的 ANIM 表（frames 字段）；node build.mjs 重新生成 client.js。locale 表是静态生成的：locale/*.json 由源码里的 label(中文, English) 对生成，改了文案要重新生成一次，否则翻译表会和界面不同步。
姿态按场合轮换：src/pose-map.js 把 36 条场景规则映射到姿势立绘，未命中时回落到 12 张精灵表的动作态，所以并不是每个场景都会换立绘。
天气陪伴需要联网（Open-Meteo）。请求失败时沿用上次结果，超过 6 小时就不再提天气；完全离线时宠物其余功能不受影响。
天气台词只有中文（英文界面会回退到中文，不会留空）。
天气专属姿态（撑伞/缩脖子/发抖/流汗）与 19 个新姿态立绘暂缓，当前用现有姿态代偿。
宠物渲染在 shell.overlay 层（z-index: 20，自成层叠上下文），DSH 的弹窗与吐司会盖住它，这是宿主层级决定的。
拖到屏幕边缘时会被夹回视口内（留 12px 边距），窗口缩小时也会被夹取。
client.js 约 313 KiB；精灵图与姿势图（3.4 MB）通过 /api/dsh-whale-maid/assets 由宿主提供，不再内联进包。
系统开启「减少动态效果」时，帧动画与摇摆会自动停用，只保留静态姿态。
工作状态联动依赖宿主 DOM 契约（1.1.0）。探测器读的是 [data-chat-running]、[data-tool][data-state]、[data-variant="think"] 这些属性；宿主改版后可能失效。失效时的表现是「她不再跟着工作换姿态」，其余功能不受影响——用 dshWhaleMaid.scanNow() 一看就知道是不是探测不到。探测器只读 DOM，不发请求、不碰 host 总线。
探测间隔 1.5 秒（MutationObserver 去抖），所以姿态切换有最多 1.5 秒延迟，这是刻意的：轮询太密会让长会话掉帧。
成长数据只存在本机 localStorage，换机器/清缓存就没了，也没有云端同步。
台词是按话题随机挑的，不读对话内容原文——只做关键词与话题的粗分类，不做语义理解。
分区命中矩形是按 idle 第 0 帧量的，但每个姿势都重画了角色，位置会有几个像素的漂移：src/zones.js 里带一张 33 行的配准表（状态#帧 → [缩放, dx, dy]），点击时先把坐标映射回参考帧再判定，所以换姿势后仍然准。极端姿势（例如 drag 侧身）的边缘部位仍可能落到隔壁区。
松手压扁是 320 ms 的一次性动画，连续快速松手不会重新播放。
本机到 github.com 的 HTTP/2 连接会被中间设备重置，git push 会随机失败并报：
fatal: unable to access 'https://github.com/lov0vo/dsh-whale-maid.git/':
TLS connect error: error:0A000126:SSL routines::unexpected eof while reading
这不是仓库问题，而且失败时提交可能已经落地，所以不能只看 git push 的返回值。仓库已做两件事：
.git/config，克隆后需重设一次）：http.version=HTTP/1.1、http.postBuffer=524288000、http.lowSpeedLimit=1000、http.lowSpeedTime=60。scripts/push.mjs：构建 → 测试 → 同步两处安装目录 → 提交 → 带退避重试地推送 main 与 tag → 用 ls-remote 回读校验远端 SHA 与 tag，校验不通过直接非零退出。node scripts/push.mjs -m "fix: something" # 提交并推送（含构建与测试）
node scripts/push.mjs --no-build # 只推送已提交的内容
npm run push -m "…" # 同上，走 package.json scripts
推送后用 git ls-remote origin main 与 git ls-remote --tags origin 复核，两者都应与本地一致。
精灵表与姿势立绘不再内联进 client.js。构建时 build.mjs 把它们复制到 assets/，插件宿主半边 index.js 注册只读路由 /api/dsh-whale-maid/assets：
GET / HEAD，其余返回 405；safeResolve）、MIME 表、Content-Length、Cache-Control: public, max-age=3600、弱 ETag + 304；warn，不会让插件行挂掉（此时宠物会没有贴图）。client.js 因此从 4.89 MB 降到 264 KB，图片总量 3.4 MB 放在 assets/，随包发布。
locale/zh.json 与 locale/en.json 现在是 81 个扁平键（settings.* 19 个、panel.* 60 个、meta.* 2 个）。运行时由 src/locale-table.js 的 dwmT(key, zh, en) 查表；缺键时回落到传入的中英文，所以新增语言只需加一个 JSON 表。
dwmSpeak(message, tone, priority) 支持 normal < state < important。状态提示用 state，关怀与里程碑用 important，普通闲聊用 normal——高优先级未过期时不会被低优先级顶掉。
轮询 3 s 一次，切回标签页立即重扫。「运行标记消失但文档隐藏、或设置页已挂载」判为保持而不是结束，workHold 仍是最终兜底，避免切到设置页就把进行中的回合误判为结束。
src/pose-map.js 定义了 36 条场景规则（会话、工作、互动、心情、关怀、天气、节日），每条映射到一个姿势立绘；另有 15 条回落表指定「该姿势没有图时播哪个动作态」。已接入工作相位（thinking / tool / long / success / failure）与关怀时刻（久坐 / 卡住 / 回来 / 深夜 / 饥饿 / 心情）。当前 12 个上下文里有 5 个命中真立绘（success / afk / curious / night / star），其余回落原动作态，既有转场行为不变。
node scripts/release.mjs patch|minor|major 会依次完成版本号、构建、测试、同步两处安装目录、git commit、git tag。