@TestFox000

dsh-deepseek-peak-whale

Name: dsh-deepseek-peak-whale
Availability: InStock
Author: TestFox000

会说话的小鲸鱼娘

Stars: 0
Language: JavaScript
Created: Oct 6, 2026
Updated: Oct 6, 2026

Fun

GitHub repo

Introduction

dsh-deepseek-peak-whale 🐋

在DeepSeek Harness里养一只鲸鱼娘：她告诉你 DeepSeek 现在是不是半价，侧栏挂着余额 · 今日费用，平时在窗口底部自由走动、坐下、打盹、眼睛跟着你鼠标转，还能拎起来拖、甩出去、摸头顺毛；写完提示词把她拖到输入框上松手，她替你优化好再写回。

侧栏状态条 + 详情浮层（浅色/深色 · 简洁版/详细版）：

桌宠（落地 → 念台词 → 拖拽互动）：

桌宠演示：小鲸鱼念出「现在是谷时，半价～」

两个挂载点：

位置	内容
侧栏底部（账号位上方）	价格状态条：谷时/峰时、距切换倒计时、余额 · 今日费用；点击弹出完整价格表 + 账户卡片
全屏浮层	鲸鱼娘桌宠：自由漫游、互动把玩、按峰谷念台词

（侧栏展开时）  [🐋]  谷时 · 半价                      距峰时 109小时
                         余额 $12.34 · 赠 $1.00 · 今日 $0.0421   ← 第二行：账户钱包
（侧栏收起成图标轨道时）  [🐋]
（点击状态条后）  完整价格表 / 下次切换时刻 / 账户余额与今日费用 / 规则依据与数据来源
（会话里）      /price  峰谷时段与价格表      /balance 余额 + 今日费用

（界面上）      🐋  ← 在窗口底部自由走动，偶尔坐下 / 打盹 / 转圈
                 💬「放假的 token 是打折的～」   ← 台词按当前峰谷换，说话时嘴会动
（鼠标扫过她）  顺毛：累积划动 320px → 呼噜 + 爱心 / 害羞
（点一下）      戳她 → 随机表情（睡觉时会被戳醒，还会吓一跳）
（按住拖动）    揪住后颈拎起来 → 拖动 → 松手按速度抛出，落地太快会摔晕
（你打字时）    无论她在哪，只要挡在文本框前就走开（最近的一侧，远了就跑）
（拖到文本框上）提示词写完把她拖上去松手 → 优化后写回；
                期间她头顶冒气泡「正在优化提示词中…」，完成后弹出 √/× 撤销对话框
                （30 秒未选自动收起；拖动时气泡跟着她走，期间依旧可以互动）
（右键）        换个姿势 / 摸摸头 / 念句价格 / 回家 / 安静一会儿 / 自由活动

谷时（半价）：边框转绿，她念的也是「半价 / 便宜 / 打折」那一组台词。
峰时（全价）：边框转琥珀色，台词换成「省着点花」「等半价再跑？」。
点击弹出详情浮层：顶部开关切简洁版 / 详细版——简洁版只有余额、今日费用、当前档与持续时间；详细版是完整价格表（两个模型 × 三项价目，当前档高亮）、下次切换时刻、账户余额与今日费用、规则依据与数据来源。
账户钱包：余额来自 DeepSeek 账户接口；今日费用由本机会话日志按官方牌价估算（见「账户钱包」）。
设置页（设置 → 插件 → 小鲸鱼）：详情页默认模式、提示词优化开关、使用说明；设置即时生效并保存在 $DSH_HOME/peak-whale/settings.json（API key 永远不离开本机）。

形象出处

鲸鱼娘不是本仓库的原创形象，桌宠运行时也不是手写的——它们来自开源项目 Pal-AI-Lab/Coopanion 的**「DeepSeek 大肥鱼」**： B 站 DeepSeek 二创里的蓝发鲸鱼女仆（角色原设「溟月」），上游作者把它做成了 Coo 的另一个身体。


形式	不是 Live2D 模型（上游没有 `.moc3`），而是作者自研的 Live2D 式分件模型：WebGL2 渲染，25 个部件挂在变形器链上，自带走跑跳坐睡、拎起抛出物理、十几种表情、说话口型、头发裙摆尾巴的弹簧晃动
上游项目	Pal-AI-Lab/Coopanion
本仓库的改动	只用 `tools/vendor_pet.mjs` 把三个上游模块拼接、内联进浏览器半身（贴图转 data URI）；`vendor/` 下的上游源文件一字未改，上游 LICENSE 原样保留
代码许可	上游代码与贴图为 AGPL-3.0-or-later（Copyright (C) Pal-AI-Lab），因此本仓库整体按 AGPL-3.0-or-later 发布，详见「六、许可与再分发」
⚠️ 商标	围裙上含各家厂商商标图形；商标归各自权利人所有，不因本仓库的代码许可而被授予——再分发（含商用）前请自行确认形象与商标的合规使用

「这套形象是怎么被装进插件的」（拼接方式、为什么不引 ESM/不起服务器、踩过的坑）见文末**「桌宠运行时是怎么来的」**。

安装

环境要求：DeepSeek Harness（dsh）桌面端或 Web 端，其插件运行时提供 sidebar.footer.action / shell.overlay / settings.plugins.tab 三个 Web 槽位； Node.js（仅构建与测试需要）。

# 1) 克隆到本机插件目录并构建自检（整仓约 6 MB，含 AGPL 要求的 vendor/ 源文件）
git clone https://github.com/OWNER/dsh-deepseek-peak-whale.git "$env:USERPROFILE\.dsh\local-packages\dsh-deepseek-peak-whale"
cd "$env:USERPROFILE\.dsh\local-packages\dsh-deepseek-peak-whale"
npm run build && npm test    # 重新生成 client.js + 跑五套测试，应全部通过

// 2) 在 profile 的 package.json（必须 UTF-8 无 BOM）里登记两处
//    默认位置：C:\Users\<你>\.dsh\profiles\desktop\package.json
{
  "dependencies": {
    "dsh-deepseek-peak-whale": "file:C:/Users/<你>/.dsh/local-packages/dsh-deepseek-peak-whale"
  },
  "dsh": { "profile": { "bundles": [
    /* …既有 bundles… */
    "dsh-deepseek-peak-whale"
  ] } }
}

重启 DSH ——侧栏底部出现小鲸鱼，零配置即可用。

只有「提示词优化」需要填你自己的 API key（设置 → 插件 → 小鲸鱼；保存即生效，key 永不离开本机）。
不要再把 peak-whale 写进 profile 的 cordis.patch.yml：被 dsh.profile.bundles 引用的包会自动应用自带 patch，两处都写会报 duplicate loader entry id: peak-whale。
更新已安装副本、重启后路由掉线等踩坑，见下文**「二、安装细节与更新踩坑」**。
发布前自检与推送步骤见 RELEASING.md。

一、权威依据

价格与时段全部来自官方文档，没有猜测：

Off-peak rates are half of the peak rates. Peak hours are 01:00 - 04:00 and 06:00 - 10:00 UTC, Monday through Friday, excluding Chinese public holidays. All other hours are off-peak, including weekends and Chinese public holidays in full.

—— https://api-docs.deepseek.com/quick_start/pricing

换算成北京时间：

	时段
峰时	周一至周五 09:00–12:00、14:00–18:00（且非法定节假日）
谷时	其余全部时段；周末与节假日整天都算谷时，价格为峰时的一半

价格（美元 / 100 万 tokens）：

模型	输入·命中 (谷/峰)	输入·未命中 (谷/峰)	输出 (谷/峰)
`deepseek-flash` (V4.1-Flash)	0.003 / 0.006	0.15 / 0.30	0.60 / 1.20
`deepseek-v4-pro` (V4-Pro-0813)	0.022 / 0.044	0.66 / 1.32	1.98 / 3.96

节假日表内置国务院办公厅《关于 2026 年部分节假日安排的通知》（国办发明电〔2025〕7 号）：元旦 1/1–1/3、春节 2/15–2/23、清明 4/4–4/6、劳动节 5/1–5/5、端午 6/19–6/21、中秋 9/25–9/27、国庆 10/1–10/7。

关于调休上班的周六/周日：官方明确「周末整天都算谷时」，所以 5/9、10/10 这类调休上班日仍按谷时处理。本插件据此只判断「周末」与「法定节假日」，不处理调休上班日。

二、安装细节与更新踩坑

一般按上文「安装」用 local-packages + file: 依赖即可；本节讲另一种「复制进 profile node_modules」的做法，以及更新已安装副本时的血泪经验。

DSH 桌面端的 profile 由应用专管（dsh --profile desktop 会被拒绝），采用真实目录方式安装，不能用 link: / junction：

$profile = "$env:USERPROFILE\.dsh\profiles\desktop"
$dest    = "$profile\node_modules\dsh-deepseek-peak-whale"

# 1) 复制发布文件（不要复制 test/ 与 build.mjs）
New-Item -ItemType Directory -Path $dest -Force | Out-Null
Copy-Item index.js, client.js, package.json, cordis.patch.yml, icon.png, README.md $dest -Force
Copy-Item src "$dest\src" -Recurse -Force

⚠️ 更新已安装的副本，有三条血泪经验（2026-10-06 一次更新里全踩了）：

① 先看清 $dest 到底是哪个目录。 如果 profile 的 package.json 里写的是 "dsh-deepseek-peak-whale": "file:C:/…/.dsh/local-packages/dsh-deepseek-peak-whale"，那 pnpm 会拿 local-packages 那份来重装 node_modules——只改 node_modules 迟早被覆盖回去（症状：src/optimize.js 忽然「缺失」→ index.js import 失败 → 路由全没）。 两个目录都要同步，以 local-packages 为准。

② 用「写临时文件 → 原子改名」，别直接覆盖正在被读的文件：
Copy-Item index.js "$dest\index.js.new" -Force
Move-Item "$dest\index.js.new" "$dest\index.js" -Force   # 单次 rename，读到的永远是完整文件
③ 改了 Host 半身的代码，必须重启应用。 宿主进程里 ESM 模块是缓存的：同一个路径再次 import 拿到的是首次加载的那份，所以「改文件 + 触发重挂」只会用旧代码重新注册一遍（症状：新加的路由永远 405/404，而老路由照常工作）。浏览器半身不受影响——client.js 每次刷新页面都会重新取。

④ 重启后路由又没了？ 那是开机竞态：应用启动时 webServer 服务可能还没就绪，apply 里的 ctx.get('webServer') 会静默拿到 undefined 然后跳过注册（症状：每次重启后全 404，手动摘掉/挂回 bundle 又好了）。已修：接线走「立即试一次 + 2s→5s→15s→60s→120s→300s 指数退避重试」，服务就绪后自动补挂，路由与命令各自独立重试，重挂前先撤掉自己上一批（幂等）。

⑤ 自启修好了，余额却没了？ 那是同一个开机竞态的第二种形态（2026-10-06）。 deepseekAccount 服务在挂载那一刻还没注册，而老写法把「此刻拿不到」当成了「永远没有」：createAccountReader(serviceOf('deepseekAccount'), {}) 只抓一次服务本体，reader 从此恒返回 unavailable（症状：自启生效后余额永久消失，载荷里 account.status 恒为 unavailable；以前手动开关插件＝晚注册，恰好躲过）。已修：改成传解析函数 () => serviceOf('deepseekAccount')，每次读取重新解析；且 unavailable 结果不进缓存，下一次轮询自己就恢复。 规矩：服务一律「用时再取」，绝不在 apply 里存服务本体（客户端取 layout 也是同一个坑，见 v0.4.5）。

想在不重启的情况下把掉线的路由重新挂上（模块本身没问题时），可以把 bundle 行摘掉再挂回去，应用的 reconcile 会重新挂载 entry：
# 从 package.json 的 dsh.profile.bundles 里删掉本插件 → 等几秒 → 再加回去
出现「路由 404 但插件显示已启用」时，按上面各条依次排查。

在 $profile\package.json 里加两处（package.json 必须是 UTF-8 无 BOM）：

{
  "dependencies": { "dsh-deepseek-peak-whale": "0.4.6" },
  "dsh": { "profile": { "bundles": [
      /* …既有 bundles… */
      "dsh-deepseek-peak-whale"
  ] } }
}

不要再往 profile 的 cordis.patch.yml 里加条目——被 dsh.profile.bundles 引用的包，它自带的 cordis.patch.yml 会自动生效；两处都写会报 duplicate loader entry id: peak-whale。

装好后 DSH 会热加载浏览器半身；若没出现，重启应用。

要用「提示词优化」得先填 key：首次启动会自动生成配置模板 $DSH_HOME/peak-whale/settings.json（未设置 $DSH_HOME 时即 ~/.dsh/…），把 DeepSeek API key 填进 deepseekApiKey 就能用了——保存即生效，不用重启。余额、当日费用、价格表这三项不需要 key。

三、使用

状态条：侧栏底部、账号位上方（挂载在 sidebar.footer.action，order: -10），每秒刷新倒计时；侧栏收起成 56px 图标轨道时只显示鲸鱼头。展开态是两行：上行「时段 · 倒计时」，下行「余额 · 今日费用」，中间一条细分隔线； 没拿到数据时第二行整行不渲染——宁可保持原样，也不在侧栏底部挂一句「账户数据不可用」。
点击状态条：弹出详情浮层（价格表、账户卡片、下次切换、依据与来源），点浮层外关闭；打开时会立刻刷新一次余额。
悬停：title 提示里有完整的一句话摘要（含余额与今日费用）。
命令：会话里输入 /price 打印峰谷报告，/balance 打印余额 + 今日费用的纯文本版（都由 Host 半身提供）。

账户钱包（余额 + 当日费用）

位置	显示
状态条第二行	`余额 $12.34 · 今日 $0.0042`（未登录 → `账户未登录 · 今日 …`；取不到 → 整行不显示，原因写在浮层里）
详情浮层的账户卡片	账户状态、每个钱包的余额、赠送余额、今日费用（日期 + 金额，单独一段并放大）、按哪一档计价、请求次数与 token 分解、充值 / 官方用量入口、估算声明
`/balance` 命令	同上内容的纯文本版

余额由 Host 半身调 DSH 自己的 deepseekAccount.getBalance()（Platform 账户接口）取得，带 45 秒服务端缓存——多个标签页共用一次查询；未登录只读状态、不打余额接口。

今日费用完全在本机算，不联网：

Host 监听 session/event（会话的持久化事件流），从 assistant/message、assistant/attempt 里取 provider 报告的 token 用量（request/header 负责记住当前路由，llm/retry-started 负责重试语义）；
折算规则与 DSH 内置的 tokenUsage 投影逐字对齐（同 turn/step 的重复样本不改账、重试叠加、替换按 delta 调整），所以它和界面里那颗用量甜甜圈不会各说各话；
按事发那一刻的峰/谷档与官方牌价计价（缓存命中/未命中/写缓存/输出四个桶分开算），记进北京时间的当日格子；
落盘到 $DSH_HOME/peak-whale/wallet.<profile>.json（合并写 + 临时文件 rename，损坏时留 .corrupt-<时间戳> 备份再从空账继续），重启不丢当天的账。

浏览器侧同源 fetch GET /dsh-deepseek-peak-whale/api/wallet?locale=…（Host 不发 CORS 头、响应 no-store），60 秒轮询一次。拉取失败时保留上一份数据，而不是把界面清空；连第一份都还没拿到时，状态条整行不显示，说明写在浮层里，而且按状态码分人话：

失败原因	浮层里的说法
404（Host 半身还是旧代码）	「要重启一次 DSH 才会出现——Host 侧的新半身还没加载；之后每分钟自动刷新」
其余（断网、服务缺席、500）	「暂时取不到，每分钟会自动重试」

布局本身用截图验收（node tools/strip_preview.mjs → assets/strip-preview.html → 无头 Edge 截到 assets/strip-preview.png），覆盖浅色/深色、有数据、未加载、未登录四种状态；价格表四列都是不换行的数字，浮层宽度下限（≥400px）已写成断言，防止「输出」那列再次被挤出卡片。

v0.4.0 的版式约定（按使用反馈改的，改了就别退回去）：

浮层顶部不再摆模式开关——简洁版 / 详细版只在「设置 → 插件 → 小鲸鱼」里切；
浮层钉死尺寸（width:420px; max-height:452px，量自简洁版实测卡片），详细版超出部分 在卡片内滚动，不再把浮层撑成一整屏；
详细版底部有一个吸底的「设置」按钮，点了走 layout.selectPanel('plugins') 跳内置「插件」设置面板（我们的 tab 就在那一页）；拿不到 layout 服务时安静失败，绝不抛错；
卡片是亚克力（backdrop-filter: blur(18px) saturate(1.5) + 半透明底色）， @supports not (backdrop-filter…) 退回不透明底色；
卡片里那行免责小字与「想看完整价格表…」的指路文案已移除（完整说明移到设置页的帮助页）。

这是估算，不是账单：按官方牌价计价，看不到赠送余额抵扣、议价折扣，也不代表 Platform 后台的记账口径。界面与 /balance 都会写明这一点。

鲸鱼娘桌宠

挂在 shell.overlay（官方定义：全屏浮层、在所有列之上、本身就是点击穿透的）。整层也是 pointer-events: none，只有跟着她身体走的命中区（.pw-hitbox，约 148×145 px）开回指针事件——所以除了她身上那一小块，你点任何按钮都不受影响。

行为	触发	说明
自由活动	常驻	在窗口底部来回走 / 跑、坐下、睡觉、转圈、张望——全由上游 `roam: 'free'` 驱动
视线跟随	鼠标移动	眼睛跟着光标转（头上的呆毛和刘海位移最大，后发反向）
顺毛	鼠标在她身上划动累积 320px	呼噜声 + 爱心；睡着时摸会冒爱心，醒着则随机「喜欢 / 害羞」
戳一下	点一下（<400ms）	随机表情（开心/眨眼/惊讶/喜欢/生气）；睡觉或坐着时会被戳醒，还会吓一跳
揪起来	按住并拖动 >6px	揪后颈拎起，拖动时朝向与拖拽方向联动
抛出去	松手	按松手瞬间的速度抛飞；速度 >700 有破风声，落地冲击 >1000 会摔晕
入场	挂载时	从窗口顶部掉下来落到地面（`enter: 'drop'`）
打字回避	在任何文本框里打字 / 把焦点点进文本框	无论她在屏幕哪个位置，只要挡在文本框前就让开到框外最近的一侧；距离 >160px 直接跑过去
投递（优化提示词）	写完提示词后把她拖到输入框上松手	就地放下（不抛飞）→ 读原文 → 调 `deepseek-v4-pro`（`reasoning_effort: max`）改写 → 写回 → 浮出「撤销优化」；随后她主动让开

这些物理与反应全部来自上游 pet-core（pointerDown/Move/Up、onEvent('touch')），本插件只负责把浏览器事件转发进去，并把命中区贴到她身上。

打字回避（你打字时她会走开）

用的是上游公开的 ctl.walkTo() + ctl.holdRoam()，没有改 vendor 代码：

认出「正在打字」：在文档上捕获 keydown / input / focusin / focusout，目标或当前焦点是 input / textarea / contenteditable 就记下来。判定是宽限期（最后一次按键后 3 秒）或焦点仍留在文本框里—— 光标还停在框里时你随时会接着写，她得一直在外面等着；
算回避区：文本框矩形横向外扩 40px（别压住输入框旁边的按钮）、上沿 24px、下沿 72px（下面还有工具行）；
每帧判定一次（layout() 存下的身体矩形直接用，不多做布局读取）：不挡路就什么都不做；挡路才 walkTo，目标取框外最近的一侧，距离超过 160px 改成跑（走只有 78px/s，你一句话打完她还没让开）；
打字期间持续 holdRoam(0.5)：上游的自由漫游（decide()）被按住，不会把她重新派回文本框前，她让开后就待在原地；
只在目标真的变了才重新下令（容差 16px）——每帧重复 walkTo 会把步态重置成原地踏步，她反而走不动。窗口太窄、两侧都塞不下时返回 null，与其在框里来回蹭，不如下次再试。

判定全部收在 isEditable / editableZone / rectsOverlap / escapeTargetX / escapePlan / typingActive 这几个纯函数里（不碰全局，视口坐标）， bundle.test.mjs 逐个断言；监听器的挂载与摘除也有断言（helpers.mjs 的 document 桩会记账，React 桩新增了 __unmount() 来跑 effect 清理）。

提示词优化（把她拖到文本框上）

用法：提示词写完之后 → 揪住她拖到输入框上 → 松手。她不会被抛出去 （pet-core 自带的 dropAt() 正是「就地放下、no throw」，所以还是没改 vendor）：

认出文本框（聚焦的 → 最近打字的 → 页面上最大的那个，textarea / contenteditable 都认）；
读出正文 → POST /dsh-deepseek-peak-whale/api/optimize 给 Host；
Host 用你自己的 API key 调一次 deepseek-v4-pro + reasoning_effort: max，系统提示词写死「不改变原意、不增删任务、只输出正文」，Host 再剥掉模型爱加的代码块与客套话；
写回文本框（走原型上的原生 setter + 派发 input，React 受控输入才认账），浮出一颗胶囊：「提示词已优化 [撤销优化]」；
她念一句「优化好了，不满意可以撤销～」，随后主动走出文本框区域 ——复用打字回避那道门，只是由 api.avoidUntil 打开。

撤销（不想要了就撤）：

入口	说明
胶囊上的「撤销优化」	一键把原稿一字不差写回去
右键菜单 → 撤销提示词优化	胶囊被你改字或 30 秒超时收掉之后，从这里照样能撤
自动失效	你改过文本框内容后，撤销自己收起——绝不能拿旧稿盖掉你的新输入

配置：$DSH_HOME/peak-whale/settings.json（首次启动自动创建；保存即生效，不用重启 ——每次拖拽都会重新读一遍文件）。

字段	默认	说明
`deepseekApiKey`	`""`	你的 DeepSeek API key。留空时拖一次会得到「把 key 填进 …」的提示
`model`	`deepseek-v4-pro`	与本插件价格表同一档
`reasoningEffort`	`max`	留空即不发这个字段（有的账户不认它；400 报错里会直接告诉你改哪儿）
`baseUrl`	`https://api.deepseek.com`
`timeoutMs`	`120000`	max 思考就是慢；到点必然返回（内部另有一道不依赖 `abort()` 的兜底超时）
`maxInputChars`	`12000`	超长直接拒绝，不白花钱

兜底：环境变量 DEEPSEEK_API_KEY（文件优先）。key 只在 Host 进程里读—— 不进插件代码、不进日志、不进浏览器 bundle。

⚠️ 这次调用走的是你自己的 DeepSeek API 账户，按 token 计费，与侧栏那条「今日费用」无关（账本只折算会话日志里 provider 报告的用量， Host 自己发的请求不在其中）。同一段原文 5 分钟内不重复扣费。

台词与气泡

每 75–150 秒她会自己念一句，其中约 3/4 是当前峰谷的价格台词 （谷时说「半价 / 便宜 / 打折」类，峰时换「省着点花 / 等半价再跑？」类，节假日与周末各有专门的一组）。台词逐字揭示，每揭示一个字就调一次 ctl.talk()，所以嘴会跟着动；气泡位置每帧从 ctl.anchor()（头顶）取，她走动时气泡跟着走。

首次开口在挂载后约 9 秒。想立刻听一句：右键 →「念句价格」。

右键小菜单

菜单项	作用
换个姿势	随机做一个动作（跳 / 小跳 / 张望 / 转身 / 点头 / 摇头 / 转圈 / 坐下 / 睡觉 / 晕 …）
摸摸头	触发「喜欢」表情并 +1 互动（上游把顺毛做成了划动累积，这里给个一键入口）
念句价格	立刻念一句当前峰谷的台词
回家	走回出生点（`ctl.walkTo`）
安静一会儿	关掉自由漫游并坐下（`setRoam('off')`）
自由活动	恢复自由漫游（`setRoam('free')`）

菜单顶部显示 亲密度 Lv.N · 互动 M 次。点空白处关闭。

⚠️ 踩坑记录：.pw-roam 是 pointer-events: none（为了不挡住界面），菜单作为它的子元素会继承 none——表现是"菜单能弹出来但一个都点不动"。必须在 .pw-menu-backdrop 上显式写 pointer-events: auto。这条已经写成断言进了 bundle.test.mjs，防止以后被改回去。

亲密度

她身上发生的每一次互动（拎起 / 放下 / 抛出 / 戳 / 摸 / 摔晕）都算一次，存在 localStorage 的 dsh-peak-whale.affinity.v1 里，跨会话累积，每 5 次升一级（上限 Lv.10），升级时会专门念一句。

读写都包了 try/catch：隐私模式、配额满、JSON 损坏一律回落到 0，存不上不影响使用。 loadAffinity(storage) / saveAffinity(storage, pets) 把 storage 作为参数传入而不是直接用全局，所以这两条路径也有单测覆盖。

音效

上游自带 Web Audio 合成音效（呼噜、戳、拎起、破风、说话嘟囔、睡觉打呼）， 必须有用户手势之后才会响（浏览器策略），所以第一次点她之后才出声。想彻底静音：把 localStorage 的 dsh-peak-whale.sound.v1 设为 'off'。

四、开发

src/peak.js               ★ 定价逻辑唯一事实来源（Host 直接 import）
                            也提供 costUsd / formatMoney / formatTokens 等两端共用的口径
src/wallet.js             ★ 当日用量账本（Host 专用）：折算 session/event、按日计价、持久化
src/optimize.js           ★ 提示词优化器（Host 专用）：settings、请求体、输出收敛、超时与缓存
vendor/                   ★ 上游桌宠运行时（rig.js / figure.js / pet-core.js / model.json
                            + tex/ 25 张部件贴图 + feat/ 25 张五官贴图 + icon.png）
vendor/pet-runtime.js       由 tools/vendor_pet.mjs 拼成的自包含脚本（构建产物）
vendor/LICENSE-Coopanion-AGPL-3.0.txt   上游许可证
tools/vendor_pet.mjs      拼接运行时：剥 import/export、贴图转 data URI、守卫校验
tools/pet_preview.mjs     直接跑运行时的验证页（不经过 React）
tools/pet_harness.mjs     在真实浏览器里跑 client.js 本体（极简 React 垫片 + 虚拟时钟）
tools/strip_preview.mjs   状态条 + 账户卡片的可视化验收页（渲染成静态 HTML → 无头截图）
client.template.js        浏览器半身模板（组件接线、台词、菜单、账户钱包、打字回避、优化气泡、设置页 tab、插槽注册）
build.mjs                 注入 src/peak.js + vendor/pet-runtime.js → 生成 client.js（写盘前先过语法闸门）
client.js                 构建产物，勿手改（约 1.9MB，体积几乎全是贴图）
index.js                  Host 半身：/price、/balance、wallet + optimize + settings 路由、记账监听

本地调试闭环（先跑这个，再上真机）：

  node test/run-all.mjs     五套全量：定价 / 账本 / 优化器（假 fetch 不花钱）/ bundle 形态（握手、
                            三挂载点、气泡状态机、CSS 回归闸门）/ 浏览器核心 parity
  node tools/strip_preview.mjs   详情浮层（简洁/详细两版）渲染成静态 HTML → 无头截图肉眼验收
  node tools/pet_harness.mjs     client.js 在极简 React 垫片里冒烟
  node tools/verify_live.mjs     真机一键验收：wallet/settings 路由、uiMode 往返、开关拦截、
                            方法限定、空文本零成本（写操作全部恢复原值，零残留）。
                            退出码 2 = 应用还没重启（settings 404），重启后重跑即为最终验收。
                            提示：改过 Host 半身后必须重启应用再跑它，否则旧模块缓存会让
                            settings 恒 404（见「更新已安装副本」第 ③ 条）。
  GET  /dsh-deepseek-peak-whale/api/diag    开机自启问题的现场证据：浏览器半身把
                            「脚本执行 → 工厂物化 → apply → 每次挂载尝试」打点到这里
                            （最多 60 条）。重启后小鲸鱼不出现时先看它：
                            完全没有条目 = bundle 没被执行（组合/投递层问题）；
                            只有 script-executed = 客户端 entry 没被创建、或 factory 没物化；
                            有 apply-start + mount-failed = 挂载时机问题（detail 里写着
                            当时 ctx 的 get/inject/effect/slots 各自能不能用）。
                            打点只在开机、inject 回调与失败重试时发，量很小；POST 同源、有界、失败静默。

契约红线（改代码前默念一遍）：
  Host：`export function apply(ctx)` + `export const name`；软依赖一律 `ctx.get()` 拿不到就少一个功能、
        绝不抛错；路由走 `ctx.inject(['webServer'], host => host.effect(…))`（与内置 dsh-plugin 同契约：
        服务就绪才回调、热重载自动重挂）；无 inject 的环境退回 `ctx.get()` + 指数退避重试；
        每条路由独立 try/catch，重挂前先撤旧注册。
  Client：`exports.apply` + `exports.inject = ['slots']`；插槽注册 = `slots.inject(name, () => slots.register({name,id,order,label}, 组件))`；
        设置页 tab 走 `settings.plugins.tab` 槽位（与 dsh-client-ui-settings-plugin-inventory 同契约）。
        **清单红线：`dsh.client.inject` 必须是空数组 `[]`，且只与 `immediately: true` 搭配**
        （与 dsh-our-free-model / dsh-dzrobot-ssh 同款）。2026-10-06 真机实测：把它写成
        `["@deepseek-ai/dsh-client-ui-slots"]` 后，**整个 bundle 的组合层会静默失败**——
        loader 里 `include:peak-whale` 直接消失，Host 路由与浏览器半身**一起**不挂载，
        症状 = 重启后小鲸鱼完全不见、去插件页开关一下插件才恢复；且删掉 profile patch 里的
        `- id: peak-whale` 那行、或改 apply 逻辑都救不回来，唯一解就是把这个字段清空。
        等 slots 是**客户端半身自己的事**：apply 里「立即试一次 → `ctx.inject(['slots'], …)`
        → 退避重试兜底」，三条路共用 mounted 闸门防重复注册（bundle 测试 3c 盯着）。
        **可选步骤红线：apply 里任何「锦上添花」的一步（装样式、抓 layout）都必须各自
        try 住 —— 一步抛异常会顺着 apply 冒走，把三个挂载点一起带走。**
        2026-10-06 16:52 开机信标实测：`/api/diag` 只有 script-executed →
        factory-materialized → apply-start，既没有 mounted 也没有 mount-failed，
        说明 apply 在中间抛了、被外层 catch 静默吞掉。凶手是开机瞬间 layout 还没注册时的
        `ctx.layout` 属性访问（服务缺失会抛）——异常一旦冒出去，价格条 / 鲸鱼娘 / 设置页 tab
        **一个都挂不上**；去插件页关掉再打开就好，因为那时 layout 已就绪。
        现在：`pwStep(name, fn)` 逐步隔离 + 每步打点（`step-threw` / `apply-threw`），
        layout 改成**点击时按需解析**（`resolveLayout()`：`ctx.get('layout')` 与 `ctx.layout`
        两条路各自 try、空结果不缓存），外层 catch 也补上了 `apply-threw` 打点。
        回归测试 3d 用「恶意 ctx」（get 抛 + layout 属性访问抛 + effect 抛）钉死这条线。
  安全：API key 只在 Host；settings 路由的回读对象只有 {uiMode, optimizeEnabled, apiKeyConfigured}；
        POST 白名单校验 + 原子写盘；HTTP 同源、不发 CORS。
  性能：余额 45s 缓存 + 客户端 60s 轮询；气泡/倒计时全部走 rAF 直改 DOM，不进 React 状态。
cordis.patch.yml          插入 id: peak-whale 这一行
test/                     五个测试 + 运行器（自带能重渲染的迷你 React 桩）

为什么要有构建步骤：浏览器半身必须是自包含的手写 bundle（DSH 不为插件跑打包器，页面也没有文件系统、更不能顺手起个服务器），而判定逻辑要和 Host 端同源、桌宠运行时和贴图要和 vendor/ 里的源文件同源。与其手抄，不如构建时注入同一份源文件。

桌宠运行时是怎么来的

形象来自 Pal-AI-Lab/Coopanion 的「DeepSeek 大肥鱼」——B 站 DeepSeek 二创里的蓝发鲸鱼女仆，做成了 Coo 的另一个身体。

它不是 Live2D 模型（仓库里没有 .moc3），而是作者自研的 Live2D 式分件模型：

rig.js：一个小型 WebGL2 渲染器。每个部件是一张贴图铺在网格上，网格点逐帧经过 变形器链（rot 绕枢轴转 / 缩放 / 平移，warp 在矩形上加位移场）。画布挂在宠物 SVG 组里的 <foreignObject> 中。
figure.js：模型本体。25 个部件（后发、刘海、裙摆、尾巴、两只鲸鳍、呆毛、手臂、两条腿、脸、头饰、蝴蝶结……）各有弹簧；眼睛/嘴/腮红每帧画进一张脸部贴图。
pet-core.js：桌宠控制器。走跑跳坐睡、拎起抛出物理、十几种表情、说话口型、视线跟随、自由漫游、音效合成，全在这里。

这比自己做一套骨架划算得多：我们自己那版「剪纸木偶」（切三层 + CSS 变换）能做的只有头部与头发的独立摆动，而它自带完整的物理与表情系统。所以这一版把之前的自绘方案整个换掉了——assets/whale-chan.*、tools/cutout.py、tools/rig_layers.py 都已删除。

拼接方式（`tools/vendor_pet.mjs`）

三个模块都是 ESM，而 DSH 的浏览器半身是手写 factory（非模块），import / import.meta 在里面是语法错误；三个模块的顶层名字也会互相冲突。所以构建时：

剥掉 export 前缀和唯一的 import（figure.js 需要 createRig，改为在它自己的 IIFE 里 var createRig = rig.createRig;）；
把 import.meta.url 换成字符串（只有一处默认参数）；
三个模块各包一层 IIFE，顶层名字互不干扰；
model.json 原样注入为 PET_MODEL；
按 model.json 的 parts 与 feat 推导出贴图清单（与上游 loadScheme 的规则逐字一致），把 50 张 PNG 转成 PET_TEX 的 data URI。

守卫：拼完仍出现行首 import/export、贴图缺失、PNG 魔数不对、或 vendor 里存在未被引用的贴图 —— 任一发生直接抛错，绝不产出「能在浏览器里静默坏掉」的产物。

为什么不引 ESM 也不要服务器

上游的 examples/whale/serve.mjs 需要一个本地 HTTP 服务器才能跑（ESM + 相对路径贴图）。插件里不能这么干：DSH 的插件页面没有文件系统访问，也不该为了一个桌宠去起服务、占端口、处理 CORS。所以运行时和贴图都内联成 data URI—— 代价是 client.js 约 1.8MB（其中 1.6MB 是贴图 base64），换来的是零外部依赖。

⚠️ 三个踩过的坑： ① 贴图必须是 data URI：跨源图片喂给 WebGL 会污染画布，texImage2D 直接抛错。 ② 无头截图模式里 rAF 会被饿死：只跑到 4 帧就不动了，看起来像"模型卡在掉落中途"。所以 tools/pet_harness.mjs 把 requestAnimationFrame 换成手动虚拟时钟逐步推进。 ③ 不能用轮询定时器等就绪：一堆 setTimeout 会把 --virtual-time-budget 瞬间烧光，贴图解码反而轮不上。改成由组件自己的首次 commit 触发检查。

验证方式

node tools/vendor_pet.mjs      # 拼运行时（改 vendor/ 后要重跑）
node build.mjs                 # 注入 client.js（写盘前会先编译一次做语法闸门）
node test/run-all.mjs          # 静态断言 + 结构断言 + 降级行为
node tools/pet_preview.mjs     # 生成"直接跑运行时"的验证页
node tools/pet_harness.mjs     # 生成"真实浏览器跑 client.js"的验证页
node tools/strip_preview.mjs   # 生成"状态条 + 账户卡片"的可视化验收页

两个验证页都用无头 Edge 截图肉眼验收：

& 'D:\SoftWare(x86)\Microsoft\Edge\Application\msedge.exe' --headless --disable-gpu `
  "--screenshot=$env:TEMP\pet.png" --window-size=1120,620 --hide-scrollbars `
  --virtual-time-budget=25000 'file:///D:/.../dsh-deepseek-peak-whale/assets/pet-harness.html'

pet-harness.mjs 里的检查是真实浏览器行为，不是模拟： data URI 贴图能否喂进 WebGL、画布能不能显示、命中区是否每帧贴合她的身体（容差 2px）、真实 PointerEvent 打上去能否进入拖动与抛出、台词计时到了气泡是否出现在头顶，以及打字回避：把一个 420px 的文本框正好摆在她身上 → 聚焦并发一个 keydown → 逐帧推进到她的身体完全离开文本框区域（横向 ±40px 的缝），否则直接 FAIL。诊断首行打印 build=<client.js 的 mtime 指纹>——截图或抓 DOM 时能证明这份页面加载的是哪一版产物。验证图：assets/pet-harness-typing.png（她已经站在框外，右下那个红框就是「输入框」）。

优化链路也在真实浏览器里跑（harness 把 /api/optimize mock 掉，不联网、不花钱）：把原文填进文本框 → 用真实 PointerEvent 把她从屏幕另一头拖上去 → 松手 → 断言「文本框被换成优化结果 + pill=done undo=true」→ 调 undoOptimize() → 断言「原稿一字不差写回、撤销态清空」→ 再逐帧等她主动走出文本框区域。实际输出：

打字回避: x 807 → 464（117 帧） 已离开文本框区域
投递: pill=done undo=true 文本=已换
撤销: 原稿已写回
投递后让开: 61 帧, 她 x=455 框 x=658
气泡: 出现过=true text="撤销了，还是你原来那版～"
完成: errs=0

这条例子真在浏览器里抓到过一次「差 6px 没出去」：她的包围盒随走姿晃动，按规划那一刻的半宽算「刚好贴边」，走到位时又会压回区里。修法是给目标加 24px 余量（AVOID_CLEARANCE），单元测试与 harness 各钉了一遍。

node build.mjs        # 重新生成 client.js
node test/run-all.mjs # 跑全部测试

测试覆盖五件事：

peak.test.mjs — 官方规则的不变量（谷价恰为峰价一半）、窗口边界、节假日/周末/调休、边界求解不抖动。
wallet.test.mjs — 余额与当日费用这条链路：记账语义与 DSH tokenUsage 投影逐桶一致（用一份独立写出来的参照实现比对：同 turn/step 不改账、重试叠加、替换按 delta）；非 DeepSeek 路由不入账、坏事件不抛；账本写盘 → 重开读回 → 坏账本留 .corrupt 备份；金额/token 格式；余额读取器的 TTL 缓存、未登录不打余额接口、服务缺席降级；载荷与报告文案；HTTP 路由的 200 / 405 / 序列化失败 500；以及 apply() 的整条接线（/price + /balance + wallet 路由 + optimize 路由 + session/event 监听，服务全缺时也不抛；没配 key 时优化路由回 200 + 一句能照做的话）。
optimize.test.mjs — 提示词优化器（全程假 fetch，不联网不花钱）：配置读取（文件优先 / 环境变量兜底 / 坏 JSON 回落）、模板只创建不覆盖、请求体（model + reasoning_effort、留空就不发这个键）、 输出收敛（剥掉整段代码块与客套话，但正文里带代码时一个字都不能丢）、 401/402/404/429/400 的中文翻译（400 提到 reasoning 时顺手给出改哪儿）、没配 key / 空文本 / 超长 / 上游失败 / 网络错误 / 模型空返回 / 超时兜底 （故意用一个不理会 signal、永不 settle 的上游，没有内部 guard 就会把整套测试挂死）、以及同一段原文 5 分钟内只扣一次费、并发只打一次上游。
bundle.test.mjs — 浏览器握手、导出的是插件而非手写 factory、两个挂载点注册正确、样式注入一次、两种状态下价格条都能渲染且文案正确； 账户钱包（默认无数据时不显示第二行、注入载荷后第二行与账户卡片都渲染出余额与当日费用、窄轨态一个字都不显示、未登录/取不到的文案、测试桩没有 location 时绝不发请求）； 桌宠运行时与贴图真的被内联（PET 的三个 API、PET_MODEL 的 25 个部件、 PET_TEX 恰好 50 张且抽查能解出 PNG 魔数、清单与 model.json 严格一致）；组件结构（舞台里只有 shadow / pet / fx 三个空元素，DOM 由 pet-core 独占写入）与优雅降级（没有 WebGL / Image 的环境里只告警不抛，data-ready 保持 0）；亲密度纯函数（等级、上限、坏数据与抛异常的 storage）、台词随峰谷变化； 打字回避（哪些元素算文本框、回避区怎么外扩、不挡路不动 / 挡路必落在框外、就近选边、窗口太窄不硬挤、「正在打字」的宽限与焦点判定、以及监听器挂载即记账、卸载必摘除）； 优化胶囊（成功态渲染 + 点撤销把原稿写回并清态、失败态整句原因 + 「知道了」、右键菜单里的撤销入口也能写回；投递区判定 ±16px、读写文本框必须派发 input、用户改过字就自动失效）；右键菜单的六项文案、逐个点击都不崩、点空白关闭；以及三条关键 CSS 断言（命中区 / 菜单 / 优化胶囊都必须显式 pointer-events:auto）。
parity.test.mjs — 逐点比对「浏览器内联核心」与 src/peak.js （国庆前后 10 天每 7 分钟、整年每 6 小时、节假日整年逐日）。

为了能断言行为结果（而不只是"没抛错"），test/helpers.mjs 里的 React 桩带 hook 槽位、能真正重渲染，还给带 ref 的元素塞了 DOM 桩，且 effect 在 render 返回之后才跑（与真实 React 的提交语义一致）—— 否则组件在 body 里读 ref.current 只会拿到 null，初始化路径永远走不到。

真正吃重的验证在真实浏览器里：tools/pet_harness.mjs 用极简 React 垫片把 client.js 本体挂起来，用真实 PointerEvent 走一遍落地 → 命中区贴合 → 揪起拖动 → 抛出落地 → 开口说话，并截图肉眼验收。

五、已知边界（请知悉）

价格是硬编码的。官方调价后需改 src/peak.js 的 MODELS 与 PRICING_AS_OF 并重新构建。插件不联网抓价，因此不会因为网络问题显示错价，但也不会自动跟进调价。
节假日表只到 2026 年。跨年后必须更新 HOLIDAYS，否则元旦至春节前会把假期误判为高峰日。改动处已注释标注。
判定使用北京时间（固定 UTC+8，中国自 1991 年起无夏令时），与本机时区无关。
峰的判定以「周一到周五且非法定节假日且在两个 UTC 窗口内」为准；官方未对「调休上班的周末」单独说明，本插件按官方「周末整天算谷时」的字面处理。
她会在窗口底部到处走，可能挡住一小块界面。挡住的范围就是她的身体（约 148×145 px），拖走或者等她走开即可；除此之外整层点击穿透。
client.js 约 1.8MB，其中 1.6MB 是 50 张贴图的 base64。这是"零外部依赖"的代价：不引 ESM、不起本地服务器、不读文件系统，全部内联。
只带了默认配色（DeepSeek 原版蓝）。上游还有 8 套厂商配色（Harness 纯黑、ChatGPT、 Claude、Gemini、千问、Kimi、MiniMax），要换配色需要把对应 vendor/schemes/<id>/ 的贴图也内联进来（会在 PET_TEX 里再加约 1.2MB）。上游的 figure.setScheme() 本身可用，只是插件没做切换入口。
今日费用只统计本插件加载之后发生的请求，装上插件那天的前半段不补账。 DSH 不在跑就不会产生用量，所以此后每个自然日都是完整的；账本按天落盘，重启不清零。
只统计 DeepSeek 路由（resolveModel 判不出型号的直接不入账）：别的厂商不走 DeepSeek 钱包，按本表计价只会算出一个没有账户对应的数字。拿不准的 DeepSeek 型号按 Flash 牌价计。
费用是估算不是账单：按官方牌价计，看不到赠送余额抵扣与议价折扣；写缓存按普通输入计（官方只公布命中折扣，官方账单亦如此处理）。与 DSH 内置的 tokenUsage 投影同口径，因此不会和用量甜甜圈打架。
余额要联网：由 Host 调 Platform 账户接口，45 秒缓存；未登录只读状态不打余额接口。浏览器侧拉取失败时保留上一份数据，第一次就失败则显示「账户数据不可用」，不会把已经显示的余额清空。余额接口与账本路由都是同源限定（Host 不发 CORS 头）。
账本落在 $DSH_HOME/peak-whale/wallet.<profile>.json（按 profile 分文件，免得桌面与 web 两个进程互相覆盖）。写盘失败只告警一次，当日费用继续在内存里跑；文件损坏会留一份 .corrupt-<时间戳> 备份再从空账继续。
提示词优化用的是你自己的 API key，走 DeepSeek 的 /chat/completions， 按 token 计费，因此不计入侧栏的「今日费用」（账本只折算会话日志）。 key 放在 $DSH_HOME/peak-whale/settings.json（或环境变量 DEEPSEEK_API_KEY），只在 Host 进程里读——不进插件代码、不进日志、不进浏览器 bundle。
reasoning_effort: max 可能不被你的账户接受（上游回 HTTP 400）。报错里会直说，把 settings.json 的 reasoningEffort 留空即可退回默认思考强度。 model 同理（404 会提示改哪个字段）。
max 思考很慢：默认超时 120 秒，到点必然返回——内部有一道不依赖 abort() 的兜底计时器，上游再卡也悬不住。同一段原文 5 分钟内只扣一次费。
撤销只有一层（优化前的原稿），而且你一旦改过文本框内容就自动失效—— 绝不会拿旧稿盖掉你的新输入。成功胶囊 30 秒后自收，右键菜单里仍可撤。
投递判定是文本框矩形 ±16px：拖到框外（哪怕只差 20px）仍然是普通抛掷，不会触发优化；判定用的是「聚焦的 → 最近打字的 → 页面上最大的那个文本框」，多光标/选区这类复杂编辑器不在支持范围内。
上游代码是 AGPL-3.0-or-later，形象与贴图是上游作者用 ChatGPT 生成/编辑的（角色原设「溟月」，DeepSeek 女仆二创；围裙上有各家商标图形）。因此本仓库整体按 AGPL-3.0-or-later 发布，详见「许可与再分发」。

六、许可与再分发

本仓库整体按 GNU AGPL v3.0-or-later 发布。

部分	来源	许可
`index.js`、`src/`、`client.template.js`、`build.mjs`、`test/`、`tools/`	本仓库自有代码	AGPL-3.0-or-later（原按 MIT 编写，为整仓合规统一改为 AGPL）
`vendor/`（运行时、25 个部件、50 张贴图、`model.json`）	Pal-AI-Lab/Coopanion	AGPL-3.0-or-later，Copyright (C) Pal-AI-Lab
`client.js`	构建产物，内联上述 vendor 内容	因内联而整体受 AGPL 约束

上游 LICENSE 原样保留在 vendor/LICENSE-Coopanion-AGPL-3.0.txt， vendor/ 未作任何修改。
AGPL 的实际要求：本仓库已提供全部对应源码（含 vendor/ 源文件与 client.js），从源码复现 client.js 只需 npm run build。
人物形象与商标：鲸鱼娘形象设定与贴图为上游作者创作，围裙含各家商标图形。商标权利归各自权利人所有，不因本仓库的代码许可而被授予。再分发（含商用）前请自行确认形象与商标的合规使用方式。
本插件仅是第三方作品，与 DeepSeek、Pal-AI-Lab 及商标权利人无隶属关系。