🐋 Whale pet

一个 DeepSeek 蓝色鲸鱼宠物插件,住在 Harness Web UI 右下角。

• 动效 — 空闲时轻轻浮动;工作时游动加快、气泡上升、光晕和虚线工作环一起跟随鲸鱼上下浮动。
• 状态 — 实时显示 Harness 是否在工作,以及正在处理哪个会话。
• 音效 — 工作完成时播放 assets/tone.wav;失败时播放该音色的下行合成版本;开始工作时轻响一声。
• 权限提醒 — 需要授权(approval/asked)时播放固定的紧急高 / 低双音警报,不受当前完成音色影响;只响一次,不连续重响;同一批多个请求只响一次,全部处理完后新的请求才会再次提示;静音时仍保留与鲸鱼同色的蓝色光晕和面板提示。
• 用量与花费 — 点击鲸鱼展开面板,显示当前主视图会话的 token 分解(缓存命中 / 未命中 / 缓存写入 / 输出),并在同一张 Token 构成表中按忙时/闲时分列显示每个桶的 token 与费用,表内合计行再把忙时/闲时的 token 总量与费用各自汇总;按 DeepSeek 官方 CNY/USD 价目内置的费率与每个请求发生的峰/谷时段估算金额、会话年龄(含空闲)与已记录交互耗时、账户余额、今日跨会话用量/费用(按 Host 按日账本,覆盖正在运行的会话),以及可展开的近 30 天每日 token 与费用(含成功的 Search/Fetch 按次费用),并显示请求总数/今日请求数(模型 / 搜索 / 抓取)。同一会话混用 deepseek-flash / deepseek-v4-pro 时,每个模型用自己的费率计价,不再把全部 token 套在一个模型上。合计 = 忙时 + 闲时;历史上没有时段记录的 token 归入忙时(保守估算),不存在第三个“未分时段”状态。token 总量取浏览器完整会话投影,交互明细为主机启动后记录。
• 交互记录 — 每条记录含提示词、回复摘要、工具 / 轮次 / 步骤计数、耗时与费用;点击任意记录可跳转到对应的会话窗口(Enter / Space 同样可用)。
• 干净的本体 — 宠物只保留鲸鱼本身,不显示交互计数气泡;记录仍可在面板里查看。
• 上下文面板 — 面板里有当前会话的窗口占用、系统提示 / 工具 schema / 消息构成条、压缩计数与缓存命中率,并可直接跳到 dsh-context 的上下文洞察页;悬停鲸鱼也会显示占用百分比。

上下文面板与 dsh-context

面板的 Context 卡片显示主视图当前会话的窗口占用,不是花费最多的那个会话(子代理可能比父会话花得更多)。

来源	提供什么
contextPressure / contextBreakdown(Harness 官方 token-meter 投影)	占用比例、窗口大小、系统 / 工具 / 消息三段构成。与输入框旁的上下文环同源。
contextTimeline(dsh-context 投影)	更细的构成、模型名、压缩 / prune / 轮次 / 步骤计数,以及面板底部的 上下文洞察 Context Insights 跳转。

• 占用 < 80% 蓝色,80% 起琥珀色,90% 起红色;面板同时给出「接近自动压缩」提醒。
• 宠物本体不再画外圈 / 背景:上下文只出现在面板和悬停提示里,避免圆环遮挡鲸鱼尾巴或把右下角弄脏。
• 没有装 dsh-context 也能用:面板和构成仍由官方投影驱动,只是不显示洞察跳转按钮。
• 装了 dsh-context 时,点「上下文洞察」会调用公开的 layout.selectPanel('dsh-context') 打开它的 Context Insights 页;找不到该面板时按钮不会渲染。

本次上下文集成的实现、缺陷分析与验证记录见 ANALYSIS.md。

性能

• 状态轮询是自适应的:工作或面板打开时 1.5 s,空闲 5 s,页面隐藏 20 s;重新可见、窗口获得焦点、打开面板时立即补一次。
• 面板打开期间每 1.2 s 重读一次内存中的会话投影;打开瞬间会调用一次 refreshProjections(必要时重试一次)补载冷投影。
• 上下文面板读取的是会话投影的内存快照,不写会话、不发遥测。

换音效

完成音是一份文件,不是代码。 直接替换即可:

plugin/assets/tone.wav

支持 .wav / .mp3 / .ogg / .m4a / .aac / .flac / .webm(改名成 tone.wav 之外的扩展名后,同步改 plugin/client.js 里的 TONE_URL 常量)。

• 建议 0.3–1.5 秒、峰值接近但不超过 1.0,否则会被削波
• 改了资源要重启 DSH(主机端只在加载时读取一次,之后从内存提供)
• 若资源缺失或无法解码,自动回退到合成音效,不会静音

面板里的音色选择

下拉框的 5 个选项播放的确实是不同的声音:

选项	完成音来源
明亮铃音 Bright（音频文件）	assets/tone.wav
柔和木琴 Soft	实时合成
木质马林巴 Marimba	实时合成
轻点提示 Click	实时合成
长尾钟声 Bell	实时合成

每个音色用 source 字段声明完成音走哪条路:'asset' 播文件,'synth' 实时合成。 失败与开始提示音始终是合成的(资源里只有成功音),会跟随所选音色。

想只保留一种声音,把 DEFAULT_TONE 改成对应名字即可;其余选项仍留在下拉框里。

安装

需要 DeepSeek Harness 0.2.0-rc.2(已验证版本)。

通过 Plugin Manager 安装,路径必须是绝对路径:

install_bundle  target: <绝对路径>/dsh-whale-pet/package

也支持 tarball(本地或 HTTP)与 git 仓库:

install_bundle  target: C:\path\to\dsh-whale-pet.tgz
install_bundle  target: https://example.com/dsh-whale-pet.tgz

install_bundle 会自己完成 profile 的包安装与 bundle 启用。不要手改 profile 的 package.json / cordis.patch.yml,也不要在 profile 目录里跑 pnpm。

启用与确认

• Config.listConfigs name=dsh-whale-pet → 应有一条 include:pet-whale
• Slots.listSubTree root=shell.overlay → 占用者 pet-whale,active: true
• GET /pet-whale/state → {"ok":true,"version":6,…}

改动后如何生效

改了什么	需要做什么
client.js(界面)	刷新页面(必要时 Ctrl+Shift+R 绕过缓存)
index.js(主机端)	重启 DSH

原因:加载器每个进程世代只 import 一次 ES 模块,禁用/启用 bundle 只是复用缓存, 不会重新读取 index.js。

1.4.0 新增 Host 半侧的峰/谷 token 分桶（snapshot v5），因此升级后需要重启一次 DSH；之后的纯界面改动仍只需刷新页面。重启前的历史用量没有 Host 时段分桶，会归入忙时（保守估算），不会出现“未分时段”状态。

1.4.7 起 Host 会把已结算的 tokens / periods 持久化到 <DSH_PROFILE_DIR>/storages/pet-whale/periods.json，DSH 重启后恢复；因此这一版升级仍需重启一次 DSH。重启前已经丢掉的历史时段无法追回，重启后新结算的时段会保留。

1.4.10 起交互 records 也写入同一个文件，Host 启动时恢复，所以“今日用量/费用”在当天重启后不再清零（仍受 80 条记录窗口限制）。

1.5.1 修正了 1.5.0 的费率表：1.5.0 用的是过期的 models.dev 快照（输出 0.28 vs 0.60），所有请求都被低估约 35%。1.5.1 改回官方 CNY/USD 价目，纯 client.js 改动，刷新页面即可，不需要重启 DSH。审计过程与逐请求对账见工作区的 BILLING-AUDIT.md。

1.6.0 修复审计里剩下的三类口径问题：内置 2026 年法定节假日（节假日按低谷，不再一律当高峰）、按每条请求的实际模型分别计价（flash / v4-pro 混用不再错约 3 倍）、Today 改用 Host 按日账本（覆盖所有会话和正在运行的回合，不再只靠 80 条记录）。计费基准统一为 DeepSeek 官方规定（峰谷 + 节假日）；LiteLLM 网关按官方结算，插件不另设网关价。Host 快照升到 version: 6，持久化文件升到 v2（自动兼容 v1），因此升级后需要重启一次 DSH；纯界面改动仍只需刷新页面。

1.7.0 增加忙时/闲时合计（在 Token 构成表内显示），并把 Host 按日账本从 8 天扩到 30 天，快照 version: 7 顶层返回 history，面板可展开查看最近 30 天每天的 token 与费用。客户端还会把 history 缓存到 localStorage，Host 重启期间已缓存的日期仍可显示；但需要重启一次 DSH 才会生成 Host 的 30 天历史，升级前的 8 天数据保留，更早的数据无法补回。

1.7.2 按 2026-11-02 的官方价目复核：模型 token 费率、峰谷时段和节假日口径与当前表一致，无需改价。Search / Fetch 从 2026-11-01 起按成功请求收费（CNY ¥5 / 1,000 次、USD $0.75 / 1,000 次）；1.8.0 起 Host 记录成功的 web_search / web_fetch 工具结果并持久化，费用计入总合计、Today 和近 30 天，快照升到 version: 8，需要重启一次 DSH。1.8.1 在面板增加 请求总数 Total requests 和 今日请求 Today requests，分别列出模型 / 搜索 / 抓取次数；一次工具调用含多个查询时仍按一次计，属于估算。

1.9.0 修复 Host 在真实进程里写不了 profile periods.json 的问题：写文件时会同时在会话 cwd 下写 .dsh-pet-whale/periods.json，启动后取到 cwd 时优先加载较新的回退文件。工作区属于 workspace-write 可写范围，因此 periods / fees / records 可以跨重启保留；仍需重启一次 DSH 加载新的 Host 代码。

依赖情况

没有任何运行时依赖,也没有 import。 不需要 node_modules、不需要构建步骤:

• 主机端只用 Node 内置能力,不 import 任何 @deepseek-ai/* 包(这也是它能从裸 link: 目录加载的原因)。
• 浏览器端是手写的 window.__ModuleLoader__.load({...}) 格式,Web shell 本来就 消费这种格式;React 从浏览器模块表里取。

安装方式决定了后续行为:

• 从目录安装 → profile 里建立 link:,指向你的文件夹,之后改动立即生效。
• 从 tarball 安装 → 复制一份,版本被冻结。分发时用 tarball。

运行环境要求

• profile 必须提供 webServer(随 Web 组合自带),否则面板拿不到数据。
• deepseekAccount 为可选:有它才显示账户余额;没有它其余功能照常,余额行不出现。
• dsh-context 为可选增强:有它才有更细的构成、压缩计数与洞察页跳转;没有它时面板仍由官方 contextPressure / contextBreakdown 投影驱动。
• 面板样式使用 --dsw-alias-* 主题 token 与固定 DeepSeek 蓝 #4d6bfe,自动适配明暗主题。

说明

鲸鱼轮廓取自官方 Harness 品牌标的几何数据(FISH_LOGO_PATH),以便宠物与产品 视觉一致;该美术资源版权归 DeepSeek 所有,本包不主张任何权利。详见 LICENSE。

完整的设计说明、实现取舍与验证方式见仓库根目录的 DESIGN.md。