dsh-whale-buddy
适用于 DeepSeek Harness Web 的一条静静游动的 DeepSeek 鲸鱼：内嵌式思考鲸鱼和右侧边缘的 Whale Dock。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:RangeKing/dsh-whale-buddy#8ff8ebf56c727763e926aa9969e829a245cc84b6Whale Buddy 以 dsh-whale-buddy 发布，当前版本为 0.2.2。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
A physics-driven, state-aware companion that brings the DeepSeek whale to life in DeepSeek Harness Web.
[!NOTE] Independent Community Project:
dsh-whale-buddyis an independent open-source plugin. It is not an official DeepSeek product and is not affiliated with, sponsored by, or endorsed by DeepSeek. The whale mark belongs to DeepSeek; see THIRD_PARTY_NOTICES.md.
dsh-whale-buddy enriches DeepSeek Harness Web (DSH) with a lively, responsive companion that visually mirrors the AI's real-time reasoning, tool calls, and execution states.
Built on a deterministic spring physics engine, the whale breaches through simulated water when a turn begins, swims calmly alongside the active status label, and wears dynamic contextual props representing current tasks—all while preserving the exact vector geometry of the official DeepSeek mark.
🌊 Procedural Breach & Water Simulation
Breaches out of simulated water at the start of every turn, creating lively ripples, splash dynamics, and an engaging sense of presence.
🐋 Living Breathing Companion
Not just a static mark—the whale breathes steadily, blinks stochastically, and tilts its heading organically according to swimming velocity.
🎯 Full-Lifecycle Task & State Awareness
Instantly mirrors thinking, streaming responses, tool execution, file reading/editing, context compaction, and user interaction states with clear status labels and bespoke monochrome vector props.
🧷 Dual Seamless Surfaces
🎨 Native Visual Integration
Automatically samples typography gradient color stops from the DSH interface, adapting flawlessly to dark and light themes without modifying official logo paths.
♿ First-Class Accessibility
Fully respects prefers-reduced-motion: reduce. Immediately presents stable static poses, offers instant panel toggling, and eliminates background frame loop overhead.
When a conversation turn begins, the inline whale executes an authored breach out of a procedural sea, settling into an effortless swim beside the status label. It updates DSH's status text with clear, descriptive task names (深度求索中…, 正在作答…, 读取文件中…, 执行命令中…, etc.) and carries an appropriate task prop.
fitToMark()) so the breach arc overflows cleanly without shifting surrounding chat layout.读取文件中，用时12秒), so DSH's own clock keeps ticking.Attached to the right edge of the viewport, the Whale Dock provides a persistent, low-profile companion presence.
Arrow Up / Arrow Down / Home / End. Position persists proportionally across window resizes.Escape, or outside clicks.| State | Status Label (zh) | Contextual Prop | Posture & Behavior |
|---|---|---|---|
idle | — | Tossable ball (after 9s dwell) | Relaxed swim, subtle drift, unhurried gestures |
thinking | 深度求索中… | Pulsing dots | Attentive posture, faster chase spring, slight nose dip |
responding | 正在作答… | Breathing speech bubble | Steady forward cruise |
working | 执行命令中… | Articulated wrench | Brisk, purposeful movement |
working · reading | 读取文件中… | Flowing file stream | Files stream horizontally beneath the hull |
working · editing | 编辑文件中… | Sketching pencil | Dynamic stroke cadence with steady drift |
working · searching | 搜索中… | Sweeping magnifier | Inquisitive scanning motions |
compacting | 压缩上下文中… | None (Body deformation) | Elastic vertical compression and rebound |
waiting | 等待你的确认… | Tilted question mark | Nose-up hover, near stillness |
error | 出错了 | Red alert exclamation | Urgent micro-shake with instant red accent |
[!TIP] All props are plugin-authored vector elements drawn outside the logo silhouette, ensuring DeepSeek's official geometry remains 100% pristine.
dsh-whale-buddy installs as a standard DeepSeek Harness Web plugin.
Add the plugin to your DSH web profile configuration:
// ~/.dsh/profiles/web/package.json
{
"dependencies": {
"dsh-whale-buddy": "^0.2.1"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-whale-buddy"
]
}
}
}
cd ~/.dsh/profiles/web
npm install dsh-whale-buddy@0.2.1
Environment Requirement: DeepSeek Harness 0.1.5-rc.2 through 0.1.7-rc.1 (requires the shell.overlay and conversation.input.overlay extension slots; the classic row also uses conversation.input.dock).
The Dock shows the current state and three settings: inline whale, classic status row, and motion. It follows DSH’s light and dark themes. The Dock, its expanded preview, and the session whale share the same task and state-change timing. Turning off the inline whale disables the classic-row control while preserving its preference.
Additional preferences are available through localStorage:
localStorage Key | Accepted Values | Default | Description |
|---|---|---|---|
dsh-whale-buddy.enabled | 1 / 0 | 1 | Global master toggle |
dsh-whale-buddy.inlineEnabled | 1 / 0 | 1 | Enable/disable inline status whale |
dsh-whale-buddy.classicStatus | 1 / 0 | 0 | Draw DSH 0.1.5's blue "Deep diving..." row above the composer (DSH 0.1.7+) |
dsh-whale-buddy.dockEnabled | 1 / 0 | 1 | Enable/disable Whale Dock |
dsh-whale-buddy.size | 18 – 36 | 26 | Inline whale display size (px) |
dsh-whale-buddy.motion | full / subtle / static | full | Motion profile intensity |
dsh-whale-buddy.dockTop | 0.0 – 1.0 | 0.5 | Normalized vertical track position |
role="status", then tracks the DOM node by reference identity to eliminate recursive re-matching loops during text changes. On DSH 0.1.7 the role="status" element is a hidden announcement; the anchor follows it to the [data-turn-process] header right after it, and never writes into the announcement itself.fitToMark()): Offsets visual headroom through negative margins, keeping the host layout box clamped at a stable 26 px without triggering document reflows.src/
├── index.ts # Plugin entry point
├── client/
│ ├── index.ts # DSH slot registrations
│ ├── config.ts # Schema-validated configuration
│ ├── locales.ts # Bilingual copy definitions
│ ├── integration/
│ │ ├── dsh.ts # React bridge for DSH slots
│ │ ├── thinking-state.ts # Semantic state evaluator
│ │ └── status-anchor.ts # Safe, non-destructive DOM status-line injector
│ ├── state/
│ │ └── whale-state.ts # Shared reactive state store
│ ├── whale/ # Standalone physics & motion core
│ │ ├── geometry.ts # Unmodified DeepSeek vector mark paths
│ │ ├── types.ts # Pose and kinematic interfaces
│ │ ├── spring.ts # Fixed-step spring integrator
│ │ ├── leap.ts # Analytical breach trajectory model
│ │ ├── water.ts # 33-node coupled harmonic spring wave model
│ │ ├── props.ts # Contextual prop definitions & scheduler
│ │ ├── renderer-svg.ts # Hardware-accelerated SVG renderer
│ │ └── view.ts # RAF lifecycle controller
│ └── surfaces/
│ ├── inline-status.ts # Inline status surface controller
│ ├── whale-dock.ts # Dock trigger surface
│ ├── dock-panel.ts # Companion panel surface
│ └── dock-drag.ts # Physics-based drag-and-drop controller
└── styles/
└── plugin-css.ts # Scoped component styles & CSS variables
The project includes an extensive automated test suite verifying physical convergence, DOM safety, and bundle integrity:
# Type check TypeScript sources
npm run typecheck
# Build production bundle
npm run build
# Run complete test suite (138 tests against production bundle)
npm run verify
# Launch visual interactive demo sandbox
npm run demo # Open http://localhost:4173/demo/index.html
# Capture visual artifacts and showcase recordings
npm run shots # Headless screenshot generation
npm run film # Record showcase animation video
@deepseek-ai/dsh@0.1.5-rc.1 with client packages at 0.1.5-rc.2 (measured in the running app); client packages at 0.1.7-rc.1 (types, and markup read from the published ui-chat / ui-conversation bundles — not yet run against a live 0.1.7 app).useSessionPendingInteraction is gone (the waiting state now reads useSessionStatus), and the session list no longer names the current session, so the Dock takes its state from the session-scoped entry instead. Both are handled per host, so 0.1.5 keeps working.--dsw-alias-* CSS variables, backed by high-contrast standalone fallback themes.@deepseek-ai/dsh-client-ui-chat, MIT, © DeepSeek), using DSH's own design tokens.FishLogo.tsx) with zero coordinate alterations.BSD-3-Clause © 2026 dsh-whale-buddy contributors.