RangeKing/dsh-whale-buddy

🐋 dsh-whale-buddy

一个由物理驱动、感知状态的伙伴，让 DeepSeek 鲸鱼在 DeepSeek Harness Web 中活灵活现。

[!NOTE]
独立社区项目：dsh-whale-buddy 是一个独立开源插件。它不是 DeepSeek 的官方产品，与 DeepSeek 无关联、未获其赞助或认可。鲸鱼标志归 DeepSeek 所有；请参阅 THIRD_PARTY_NOTICES.md。

🌟 概述

dsh-whale-buddy 为 DeepSeek Harness Web (DSH) 增添了一个活泼、响应灵敏的伙伴，以视觉方式映射 AI 的实时推理、工具调用和执行状态。

它基于确定性的弹簧物理引擎构建，在每轮对话开始时从模拟水面跃出，在活动状态标签旁平静游动，并佩戴代表当前任务的动态情境道具——同时完整保留官方 DeepSeek 标志的精确矢量几何形状。

✨ 主要特性

- 🌊 程序化跃出与水面模拟
在每轮对话开始时从模拟水面跃出，产生生动的涟漪、飞溅动态，以及强烈的存在感。

- 🐋 会呼吸的鲜活伙伴
不只是一个静态标志——鲸鱼会平稳呼吸、随机眨眼，并根据游动速度自然地倾斜朝向。

- 🎯 全生命周期任务与状态感知
即时映射思考、流式响应、工具执行、文件读取/编辑、上下文压缩和用户交互状态，并配有清晰的状态标签和定制的单色矢量道具。

- 🧷 双重无缝界面
- 内联状态鲸鱼：直接嵌入对话状态行中，零布局偏移或视觉抖动。
- 鲸鱼停靠坞：一个时尚的、锚定在右边缘的浮动胶囊按钮，可垂直拖动，并能平滑展开为完整的伙伴面板。

- 🎨 原生视觉集成
从 DSH 界面自动采样排版渐变色标，完美适配深色和浅色主题，且不修改官方 logo 路径。

- ♿ 一流的无障碍支持
完全遵循 prefers-reduced-motion: reduce。立即呈现稳定的静态姿态，提供即时面板切换，并消除背景帧循环开销。

🖥️ 产品界面

1. 内联状态鲸鱼

当对话轮次开始时，内联鲸鱼会从程序化海洋中完成一次精心设计的跃出，随后轻松地游弋在状态标签旁。它会用清晰、描述性的任务名称（深度求索中…、正在作答…、读取文件中…、执行命令中… 等）更新 DSH 的状态文本，并携带相应的任务道具。

- 零布局偏移：采用计算得出的负向溢出（fitToMark()），使跃出弧线干净地溢出，而不会移动周围的聊天布局。
- 原生墨色采样：在挂载时动态提取 DSH 的渐变色标，与深色和浅色模式和谐统一。

2. 鲸鱼停靠栏与伴侣面板

鲸鱼停靠栏附着在视口右边缘，提供持久、低调的伴侣存在感。

- 垂直轨道拖拽：使用指针垂直拖拽折叠按钮，或聚焦后使用 Arrow Up / Arrow Down / Home / End。位置在窗口缩放时按比例保持。
- 连续表面扩展：向内展开为紧凑的伴侣面板，包含实时预览、状态检查器和快捷开关。
- 流畅关闭：通过关闭按钮、Escape 或点击外部优雅关闭。

🎭 状态与手势矩阵

| 状态 | 状态标签（中文） | 情境道具 | 姿态与行为 |
| :--- | :--- | :--- | :--- |
| idle | — | 可抛掷的球（停留 9 秒后） | 放松游弋，轻微漂移，从容的手势 |
| thinking | 深度求索中… | 脉动的圆点 | 专注姿态，更快的追逐弹簧，轻微低头 |
| responding | 正在作答… | 呼吸的对话气泡 | 稳定向前巡航 |
| working | 执行命令中… | 铰接式扳手 | 轻快、有目的性的移动 |
| working · reading | 读取文件中… | 流动的文件流 | 文件在船体下方水平流动 |
| working · editing | 编辑文件中… | 素描铅笔 | 动态笔触节奏，稳定漂移 |
| working · searching| 搜索中… | 扫掠的放大镜 | 好奇的扫描动作 |
| compacting | 压缩上下文中… | 无（身体变形） | 弹性垂直压缩与回弹 |
| waiting | 等待你的确认… | 倾斜的问号 | 抬头悬停，近乎静止 |
| error | 出错了 | 红色警报感叹号 | 紧急微颤，瞬间红色强调 |

[!TIP]
所有道具均为插件创作的矢量元素，绘制在 logo 轮廓之外，确保 DeepSeek 的官方几何形状保持 100% 原样。

📦 安装

dsh-whale-buddy 作为标准 DeepSeek Harness Web 插件安装。

1. 在 Web 配置中注册

将插件添加到你的 DSH web 配置中：

// ~/.dsh/profiles/web/package.json
{
"dependencies": {
"dsh-whale-buddy": "link:/path/to/dsh-whale-buddy"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-whale-buddy"
]
}
}
}

2. 构建插件

npm ci
npm run build

环境要求： DeepSeek Harness 0.1.5-rc.2 或兼容版本（需要 shell.overlay 和 conversation.input.overlay 扩展槽位）。

⚙️ 配置

可直接从 Whale Dock 面板配置偏好设置，或通过 localStorage 进行设置：

| localStorage 键 | 可接受的值 | 默认值 | 描述 |
| :--- | :--- | :--- | :--- |
| dsh-whale-buddy.enabled | 1 / 0 | 1 | 全局总开关 |
| dsh-whale-buddy.inlineEnabled | 1 / 0 | 1 | 启用/禁用内联状态鲸鱼 |
| dsh-whale-buddy.dockEnabled | 1 / 0 | 1 | 启用/禁用 Whale Dock |
| dsh-whale-buddy.size | 18 – 36 | 26 | 内联鲸鱼显示尺寸（px） |
| dsh-whale-buddy.motion | full / subtle / static | full | 运动配置强度 |
| dsh-whale-buddy.dockTop | 0.0 – 1.0 | 0.5 | 归一化垂直轨道位置 |

🔬 技术实现与深入解析

1. 物理驱动的运动核心
- 120 Hz 固定步长积分：使用固定步长子步结合临界阻尼谐振弹簧来计算运动学方程，确保在不同显示刷新率下保持相同的运动节奏。
- 33 节点耦合波浪模拟：使用 33 个相互连接的离散谐振弹簧对海面进行建模，真实模拟表面凹陷、流体回弹和双向波纹传播。
- 亚像素精度：所有轨迹缩放和行程振幅均以 CSS 像素尺寸而非相对矢量坐标计算，确保在任何显示缩放因子下都能呈现锐利的视觉效果。

2. 非破坏性 DOM 锚定与零重排
- 引用标识跟踪：通过 role="status" 一次性挂接到 DSH 状态元素，然后通过引用标识跟踪 DOM 节点，以消除文本变化期间的递归重新匹配循环。
- 负溢出预留空间（fitToMark()）：通过负边距偏移视觉预留空间，将宿主布局盒稳定限制在 26 px，而不会触发文档重排。
- 干净的生命周期拆除：在卸载或会话切换时，自动分离所有 MutationObserver、动画帧循环，并恢复 DSH 的原始 DOM 状态。

3. 响应式状态派生与防抖
- 响应式快照观察：直接评估 DSH 快照信号，以识别流式状态、工具队列和阻塞用户交互事件。
- 700 ms 最小驻留窗口：实现有意的保持阈值，以防止微秒级工具调用导致视觉闪烁。
- 脉冲式错误追踪：通过检测状态增量事件而非读取锁存的错误字符串来识别错误发生，防止过时的警告永久残留。

4. 零依赖与绝对矢量保真
- 零外部运行时依赖；引擎数学与渲染例程与 UI 框架完全解耦。
- DeepSeek 官方矢量路径在 SVG 亮度蒙版内以未修改的刚体形式渲染，坐标变形为 0。

🏗️ 架构与项目布局

src/
├── index.ts                     # 插件入口点
├── client/
│   ├── index.ts                 # DSH 插槽注册
│   ├── config.ts                # 经 Schema 校验的配置
│   ├── locales.ts               # 双语文案定义
│   ├── integration/
│   │   ├── dsh.ts               # DSH 插槽的 React 桥接
│   │   ├── thinking-state.ts    # 语义状态求值器
│   │   └── status-anchor.ts     # 安全、非破坏性的 DOM 状态行注入器
│   ├── state/
│   │   └── whale-state.ts       # 共享响应式状态存储
│   ├── whale/                   # 独立物理与运动核心
│   │   ├── geometry.ts          # 未修改的 DeepSeek 矢量标记路径
│   │   ├── types.ts             # 姿态与运动学接口
│   │   ├── spring.ts            # 固定步长弹簧积分器
│   │   ├── leap.ts              # 解析式跃出轨迹模型
│   │   ├── water.ts             # 33 节点耦合谐波弹簧波浪模型
│   │   ├── props.ts             # 上下文道具定义与调度器
│   │   ├── renderer-svg.ts      # 硬件加速 SVG 渲染器
│   │   └── view.ts              # RAF 生命周期控制器
│   └── surfaces/
│       ├── inline-status.ts     # 内联状态表面控制器
│       ├── whale-dock.ts        # 停靠触发表面
│       ├── dock-panel.ts        # 伴随面板表面
│       └── dock-drag.ts         # 基于物理的拖放控制器
└── styles/
└── plugin-css.ts            # 作用域组件样式与 CSS 变量

🛠️ 开发与验证

该项目包含一套广泛的自动化测试套件，用于验证物理收敛性、DOM 安全性与打包完整性：

对 TypeScript 源码进行类型检查
npm run typecheck

构建生产打包产物
npm run build

运行完整测试套件（针对生产打包产物的 138 项测试）
npm run verify

启动可视化交互演示沙盒
npm run demo        # 打开 http://localhost:4173/demo/index.html

捕获可视化产物与展示录制
npm run shots       # 无头截图生成
npm run film        # 录制展示动画视频

🧩 兼容性与优雅降级

- 已验证宿主：@deepseek-ai/dsh@0.1.5-rc.1，客户端包为 0.1.5-rc.2。
- 优雅降级：如果未来的 DSH 更新更改了内部槽位名称或改变了状态行标记，插件会静默失败，而不会中断对话流程。
- 动态主题适配：自动适配 DSH --dsw-alias-* CSS 变量，并由高对比度独立回退主题提供支持。

🙏 致谢

- 实现传承：dsh-thought-buddy（BSD-3-Clause），提供了宿主/客户端打包架构、固定步长弹簧时序模型以及打包验证策略。
- 交互灵感：dsh-notch（MIT），提供了边缘锚定连续表面的概念。
- 商标声明：鲸鱼标志是 DeepSeek 的知识产权，取自 deepseek-harness（FishLogo.tsx），坐标零改动。

📄 许可证

BSD-3-Clause © 2026 dsh-whale-buddy 贡献者。