前言¶
用 DSH 做智能体开发时，会话进度本身是看不见的：回合数、工具调用次数、连续使用记录，都埋在 Host 侧的事件流里。想给这些数据加一层可视反馈，常见做法要么把状态塞回模型上下文，要么把数据送到远端服务，前者浪费 token，后者有隐私代价。
dsh-whale-companion 走了另一条路：插件只在 Host 侧观察已提交的会话事件元数据，不读内容、不连网络，把「潮汐、远征、收藏」这套进度体系渲染成一只可拖动的桌面鲸鱼。下面介绍它的定位、功能、安装方式和实现边界。
这是什么¶
dsh-whale-companion 是一个 local-first 的 DSH 鲸鱼世界插件，由 LeemanCheung 维护，许可证为 MIT。在目录里它被归入「趣味换装」类。一句话定位：隐私安全的会话元数据，变成一只可拖动的桌面鲸鱼伴侣，附带 20 个可解锁鲸鱼精灵、可见潮汐、个人海湾（cove）、非惩罚性远征，以及 opt-in、仅本地的鲸鱼圈卡片。
版本 2.6.0 针对 DSH 0.1.2-rc.1，保留了既有的名称、外观、位置、进度、收藏、房间预设与 ImageGen 物种图鉴。
对模型侧，它不添加任何 prompt、工具、消息、token 用量或 KV-cache 内容；只在 Host 观察已提交的会话事件元数据，并暴露浏览器 UI。
核心功能¶
可拖动的桌面鲸鱼¶
插件提供一只运行在 shell.overlay 上的鲸鱼，支持指针拖拽、键盘移动、边缘吸附，位置持久化时会做视口安全校正。整份 UI 共享一个 5 秒本地刷新周期。新的潮汐时刻出现在有界的可见气泡里，只有里程碑会通知读屏器。
20 个鲸鱼精灵与 XP 体系¶
20 个可解锁鲸鱼精灵随 Ocean Levels 1–100 逐步解锁，每个精灵把自身故事和可见潮汐响应映射到一类安全事件，不改变模型行为。
XP 规则是明确的：
- 每回合 10 XP（只有
user/message计为回合） - 每个工具结果 5 XP
- 每次会话开始 20 XP
等级由 XP 推导，连续记录使用 UTC 会话开始日期，缺勤不扣减进度或收藏。
潮汐、收藏与远征¶
潮汐时刻由 live-only 的 session/created、user/message、tool/result 元数据驱动，且是有界的。重复的工具结果仍计入既有 XP，但无法刷潮汐时刻、收藏品或远征进度。
Whale Home 页面提供七天海洋日志、当前鲸鱼故事节点、cove 可视化预览，以及一份基于真实字段的 Privacy Ledger。另有潮汐时间线、本地 PNG 明信片导出、24 项收藏品目录、8 个固定房间槽位、3 套房间预设，以及一套非惩罚性远征。6 套 cove 主题调整背景、界面强调色和环境光，鲸鱼美术保留自身配色；12 个成就全部包含。
分享：漂流瓶与鲸鱼圈卡片¶
访客漂流瓶是隔离的只读房间预览，不会合并或覆盖接收者的进度。
鲸鱼圈卡片是 opt-in 的、仅基于本地文件的交换：只包含预设别名、物种、皮肤、粗粒度活跃分桶和共鸣星，没有账号、网络、排行、自由文本、提示词摘录、任务名或工具数据。
呈现模式与动画¶
安静、标准、活泼三种呈现模式存于浏览器本地偏好，系统 reduced-motion 始终优先，存储被拒绝时安全回退且不影响进度。
2.6.0 带来一段 2.4 秒的墨鲸跃出动画：96 帧、40 fps，原生 WebP 采用 25ms 均匀帧间隔。系统或产品内 reduced-motion 开启时切换为对应 PNG 静帧，且不替换原有的 Dive/Classic 状态动画。
安装与启用¶
安装到 DSH Web profile：
dsh plugin --profile web add github:LeemanCheung/dsh-whale-companion
安装后重启现有 DSH Web 进程并刷新页面即可看到鲸鱼。
开发验证与美术管线¶
如果要自己构建或验证，在仓库根目录执行：
corepack pnpm typecheck
corepack pnpm verify:minke
corepack pnpm test
corepack pnpm build
corepack pnpm pack:check
美术管线需要先装依赖：
python -m pip install -r requirements-art.txt
管线固定于 Python 3.12、NumPy 2.3.3、Pillow 12.3.0。corepack pnpm art:minke 重建透明 sprite，corepack pnpm art:species 规范化仓库内置的 20 物种 ImageGen 图鉴。视觉快照基线在 Ubuntu CI 维护，其他平台仍运行交互、动效、reduced-motion 和窄布局断言，但不生成 RC 截图基线。生产客户端内嵌这些栅格资产，不含运行时矢量鲸鱼绘制。
隐私与实现边界¶
这是这个插件最值得写清楚的部分：
- Host 只读取 session id、事件序号、事件类型和时间戳，从不读取、存储、导出或渲染提示词、助手输出、代码、路径、工具参数或工具结果。
- 内存回执摘要使用不离开 Host 进程的 HMAC 密钥；持久化回执窗口上限 4,096 条，只防近期重复投递，不防跨 Host 重启的永久重放。备份刻意不含回执摘要、session id 或事件数据。
- 后台写入失败不会中断 DSH 会话，可能只丢失该次进度更新，后续更新仍被接受；显式的用户保存仍会报告失败。
- 文本导入在 JSON 解析前统一限制 512 KiB；持久化写入全部做 schema 校验。
- 进度存于单一 DSH 存储后端，不跨设备同步。
- overlay 每 5 秒轮询一次，原因是当前 host Remote 事件允许列表没有包内鲸鱼状态推送路由。
- 鲸鱼圈卡片刻意只支持本地导入/导出；要做托管社区，需要另行拥有、鉴权并审核的传输提供方。
适用场景与注意¶
适合的读者：在 DSH Web 环境里长期工作、想要一份本地优先的进度可视化，同时不希望插件触碰提示词内容、不给模型增加任何开销的人。它也适合作为「Host 侧只观察元数据」这类插件形态的参考实现。
注意以下几点：
1、该插件以当前 dsh 进程的权限运行，安装前建议先阅读仓库源码与 LICENSE（MIT）确认可接受。
2、进度不做跨设备同步，换机器不会带走进度。
3、回执机制防的是近期重复投递，不是跨重启的永久重放，这一点 README 写得很明确。
结尾¶
dsh-whale-companion 展示了一种克制的插件形态：只用事件元数据、全部计算和存储留在本地、对模型零开销，把日常会话变成一个可积累的鲸鱼世界。如果你在做 DSH 插件或想给工作环境加点趣味，值得一试。
- 目录页：https://www.skillhub.cn/plugins/LeemanCheung/dsh-whale-companion
- GitHub：https://github.com/LeemanCheung/dsh-whale-companion
