DSH 桌宠（Rust 版）

⚠️ 因为穷鲸组织的 GitHub Actions 账单额度问题无法运行，所以请自行构建。

DeepSeek Harness 桌面宠物鲸鱼，Rust 原生实现，三端支持（Windows / macOS / Linux）。

原 Electron 版见 ../dsh-pet/。本版本用纯 Rust 重写，目标体积 < 10MB（原 ~100MB）。

功能

• 🐋 5 态鲸鱼：offline > attention > working > done > idle
• ⚡ 双 SSE 实时推送（events.mux + events.host）+ 2s 轮询兜底
• 🎨 HD 像素画鲸鱼（80×58 网格）+ 喷水水滴动画 + zzz/spark 叠层
• 💬 状态气泡（多会话聚合列表，可滚动，popIn 动画）
• 🔔 状态提示音（attention / done，custom/ 可覆盖）
• 🖼️ 透明置顶悬浮窗 + 系统托盘 + 拖拽 + 大小调节
• ⚙️ 内嵌设置面板（双击鲸鱼打开）：声音开关、DSH 地址编辑、热切换
• 📦 custom/sprites.json 素材包 + custom/*.m4a|mp3 自定义音效
• 🔒 对 DSH 零侵入（纯只读 HTTP/SSE）

操作指南

鲸鱼交互

| 操作 | 效果 | |------|------| | 单击鲸鱼 | 延迟 250ms 后打开 DSH GUI（浏览器） | | 双击鲸鱼 | 打开内嵌设置面板（取消单击） | | 按住鲸鱼拖拽 | 移动桌宠窗口位置 | | 滚轮（气泡上） | 滚动会话列表 |

单击有 250ms 延迟是为了区分双击。双击时单击会被自动取消，不会误打开 GUI。

设置面板

双击鲸鱼打开设置面板，面板替换状态气泡显示（鲸鱼动画继续）：

┌───────────────────────────────┐
│ 设置                      ×   │
│                               │
│ 声音提醒              [ON/OFF] │
│                               │
│ DSH 地址                       │
│ ┌───────────────────────────┐ │
│ │ http://127.0.0.1:3080│    │ │
│ └───────────────────────────┘ │
└───────────────────────────────┘

声音提醒开关：点击立即切换并持久化，与托盘菜单同步。

DSH 地址输入框：

| 操作 | 效果 | |------|------| | 点击输入框 | 获得焦点，可编辑文本 | | 输入字符 | 实时显示（支持中文 IME） | | Enter | 提交地址 → 热切换网络连接 | | Esc | 恢复原值并失焦（不关闭面板） | | 点击输入框外 | 提交地址并失焦 | | ← / → | 移动光标 | | Home / End | 跳到行首 / 行尾 | | Backspace | 删除光标前字符 | | Delete | 删除光标后字符 | | Ctrl+A | 全选 | | Ctrl+C / Ctrl+X | 复制 / 剪切选中文本 | | Ctrl+V | 粘贴剪贴板内容 | | Ctrl+Z | 撤销上次编辑 |

地址必须以 http:// 或 https:// 开头，否则提交时恢复原值。 提交有效地址后，RPC 轮询和双 SSE 连接会立即用新地址重建（热切换），无需重启。 输入框支持中文输入法（IME），预编辑文本会带下划线显示。

关闭设置：点击右上角 × 或按 Esc（输入框无焦点时）。

系统托盘

| 菜单项 | 效果 | |--------|------| | 打开 DSH GUI | 在浏览器打开 DSH | | 隐藏/显示气泡 | 切换状态气泡可见性 | | 状态提示音 | 勾选框，切换声音并持久化 | | 测试提示音 | 播放 done 音效 | | 放大 / 缩小 / 重置 | 调节鲸鱼大小（50%–110%，默认 67%） | | 退出桌宠 | 保存配置并退出 |

窗口位置

• 拖拽鲸鱼可移动窗口，位置自动保存。
• 下次启动恢复上次位置；首次启动定位到屏幕右下角。

构建

# 开发
cargo build

# Release
cargo build --release

# 测试
cargo test --all

# Lint
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check

运行

# 默认连接 http://127.0.0.1:3080
cargo run --release

# 指定 DSH URL（优先于配置文件）
DSH_PET_URL=http://localhost:3080 cargo run --release

# 截图自检（5 状态 × 3 时间点 → PNG）
cargo run --release -- --shot .shots

DSH 地址优先级：环境变量 DSH_PET_URL > 配置文件 > 默认值 http://127.0.0.1:3080。 运行时通过设置面板修改的地址会保存到配置文件，下次启动自动使用。

配置文件

配置文件路径：

| 平台 | 路径 | |------|------| | Windows | %APPDATA%\dsh\pet\config.json | | macOS | ~/Library/Application Support/dsh/pet/config.json | | Linux | ~/.config/dsh/pet/config.json |

{
  "scale": 0.67,
  "bubble_visible": true,
  "sound_on": true,
  "endpoint": "http://127.0.0.1:3080",
  "window_x": 2268,
  "window_y": 1084
}

字段均可省略，缺省时使用默认值。旧版配置文件（无 endpoint 字段）自动兼容。

自定义素材

在可执行文件同目录下创建 custom/ 文件夹：

custom/
├── sprites.json   # 覆盖像素素材（palette + sprites）
├── attention.m4a  # 或 .mp3/.wav/.ogg
└── done.m4a

sprites.json 格式见 assets/sprites/whale-sprites-hd.json。

架构

crates/
├── dsh-pet-core/   # 状态机、RPC、SSE、配置、素材包（纯逻辑，可独立测试）
├── dsh-pet-ui/     # 窗口、渲染器、输入、emoji 图集（winit + tiny-skia + softbuffer）
└── dsh-pet-app/    # 主入口、异步任务、音频、托盘、平台适配

渲染管线

┌──────────────────────────────────────────┐
│         tiny-skia Pixmap (合成面)         │
│  ┌────────────────────────────────────┐  │
│  │ 气泡：圆角矩形 + 阴影 + 文本 + 尾巴 │  │
│  └────────────────────────────────────┘  │
│  ┌────────────────────────────────────┐  │
│  │ 鲸鱼：80×58 sprite blit + bob 偏移  │  │
│  │ + 水滴动画 + zzz/spark 文字叠层     │  │
│  └────────────────────────────────────┘  │
└──────────────────┬───────────────────────┘
                   │ pixmap.data() → &[u32]
                   ▼
            softbuffer::present()

平台支持

| 平台 | 状态 | 备注 | |---|---|---| | Windows | ✅ 完整 | DWM per-pixel alpha 透明窗 | | macOS | ✅ 完整 | NSWindow 透明 + Dock 隐藏 | | Linux (X11) | ✅ 完整 | 透明窗 + 置顶 + skip-taskbar | | Linux (Wayland) | ⚠️ 降级 | 不置顶、不跨全屏；建议用 XWayland |

Linux GNOME 托盘

GNOME 默认无系统托盘，需安装 AppIndicator and KStatusNotifierItem Support 扩展。托盘创建失败时，右键鲸鱼本体仍可访问菜单。

字体

运行时探测系统 CJK 字体：

• Windows: Microsoft YaHei / SimHei
• macOS: PingFang SC / Heiti SC
• Linux: Noto Sans CJK SC / WenQuanYi Micro Hei

v1 偏离 spec：未内嵌 Noto Sans CJK 子集（需 HarfBuzz subsetting 工具链）。 如系统无 CJK 字体，启动时会 panic 并给出安装指引。

测试

• dsh-pet-core 单元测试：状态机 5 态转换、TTL 过期、SSE 帧解析
• SSE 重连集成测试（wiremock）：覆盖正常关闭、部分帧、非 JSON、无空格 data:、HTTP 5xx、取消等 6 case
• --shot 截图回归：5 状态 × 3 时间点 → PNG 像素 diff

License

MIT