DSH Pet
以鲸鱼娘的像素形象，把 DeepSeek Harness 的 Agent 状态带到 macOS 桌面
随时查看任务、接收提醒、发送消息
鲸鱼娘桌宠：应用实际导出的透明背景待机预览
macOS 14+ · SwiftUI 原生应用 · 需要 DeepSeek Harness（DSH）运行
⬇️ 安装 DSH Pet
这是什么？
DSH Pet 是 DeepSeek Harness 的 macOS 桌面伴侣。它默认以鲸鱼娘的形象显示 Agent 状态：
待机、思考、等待授权或回答、完成和失败都有对应动作。你可以把桌宠拖到屏幕任意位置，
通过状态气泡和任务卡片了解进度，也能直接从桌面向 Harness 发送消息；浏览器最小化后仍可使用。
鲸鱼娘沿用原始造型与动作，支持状态切换、待机时双击挥手和左右拖拽奔跑。可在设置面板中调整形象、大小与交互方式。
项目组成
- DSH Pet.app：以鲸鱼娘为默认形象的 macOS 桌宠应用，提供状态气泡、任务卡片与消息输入
- DSH Pet 桥接插件（包名
@sundusk/dsh-pet）：订阅 Agent 会话事件，提供 HTTP/状态 Socket 兼容接口和用户级命令 Socket；无 Harness Web UI、无设置项
旧名称和数据位置保留必要的兼容处理。安装脚本会清理旧版 MoodBall.app。
当前桌面 App 版本为 v0.8.1，桥接插件版本为 v0.8.2。DSH-Pet.app.zip 安装包可从 GitHub Releases 下载；安装脚本也会自动获取最新发布的安装包。
一切配置都在 app 的设置面板里完成。新版设置面板包含六个页面：「桌宠外观」「交互与提醒」「快捷键」「宠物管理」「Harness 连接」和「关于与更新」。
鲸鱼娘动作
鲸鱼娘会随任务状态切换动作，支持待机、思考、等待操作、完成、失败、挥手，以及左右拖拽奔跑。
查看鲸鱼娘原始动作图集
应用实际使用的鲸鱼娘动作图集，包含待机、奔跑、交互与任务状态动画
🚀 安装
先运行 DeepSeek Harness
DSH Pet 需要 macOS 14+ 和正在运行的 DeepSeek Harness。按官方中文 README选择一种 Web 启动方式：
安装 Node.js 后，直接通过 npm 运行：
npx @deepseek-ai/dsh web
或安装 pnpm，从官方源码构建并运行：
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
两种方式默认在 http://127.0.0.1:3080 打开 Web UI。已有 DeepSeek Harness 桌面版的用户也可以继续使用桌面版；其插件安装步骤见下文。加载新版 bridge 后，再从 DSH Pet 的「Harness 连接」页检测连接。
安装 DSH Pet（推荐）
另开一个终端执行：
git clone --depth 1 https://github.com/sundusk/dsh-pet.git
cd dsh-pet
bash install.sh
安装脚本会：
- 检测当前正在运行的 Harness，并识别桌面版、NPM/NPX 版或源码版
- 源码版在实际源码根目录执行
pnpm dsh；NPM/NPX 版执行对应的 dsh 或 npx @deepseek-ai/dsh CLI
- CLI 版在目标 Harness 的
web profile 中检测/安装状态插件；桌面版通过应用内「插件」页面安装
- 下载最新 Release 中的
DSH Pet.app；如果当前目录已有 dist/DSH Pet.app，则优先使用本地构建产物
- 优先安装到
/Applications，无权限时自动回退到 ~/Applications 并启动；安装后只保留一个 DSH Pet.app，旧版 MoodBall.app 和重复构建副本会移入废纸篓
安装脚本只需要执行一次。若插件刚安装而当前 Harness 正在运行，脚本仍会继续安装并启动
DSH Pet.app；请在当前任务完成后重启一次 DeepSeek Harness 让插件加载，无需再次运行安装脚本。
如果 Harness 当前没有运行，DSH Pet 会先显示“未连接”，启动 Harness 后自动连接。
安装器不会自动停止或重启正在运行的 Harness，也不会把状态接口暂时不可达直接判断为“插件未安装”。
如果同时存在多个源码版 Harness 且当前都未运行，会要求选择目标；不会静默把插件装进错误的仓库。
源码版也可以显式指定：
DSH_SOURCE_ROOT="$HOME/Projects/deepseek-harness" bash install.sh
安装器会复用当前环境或已识别 Harness 的 DSH_HOME，并将最近使用的 Harness 类型、源码路径和 profile
记录在 ~/Library/Application Support/DSH Pet/config.json，供下一次安装使用；首次使用时也会读取旧位置的配置。
如需自行构建，请先安装 Xcode 命令行工具，在本仓库运行 DSH_PET_SKIP_OPEN=1 bash make-app.sh，再运行 bash install.sh。
桌面版使用独立的 desktop profile。已有桌面版的「插件」页面流程仍有效：请在桌面版「插件」页面安装并启用 github:sundusk/dsh-pet，再重启桌面版让插件加载。官方内置 CLI 需先完成初始化，并退出桌面版后才可管理该 desktop profile；NPM/NPX CLI 不能管理桌面版 profile。安装器检测到桌面版时不会把插件误装到 web profile。DSH Pet 使用本地 Socket 接收桌面版状态；桌面版晚启动或重启后会自动重连。
手动安装桥接插件
如果只安装了应用、需要单独补装插件，请根据 Harness 的启动方式执行对应命令，然后重启 Harness：
# 通过 npx 运行 Harness
npx @deepseek-ai/dsh plugin --profile web add github:sundusk/dsh-pet
# 已安装全局 dsh 命令
dsh plugin --profile web add github:sundusk/dsh-pet
# 从源码运行 Harness：先进入 deepseek-harness 源码根目录
pnpm dsh plugin --profile web add github:sundusk/dsh-pet
桌面版仍请使用其「插件」页面；官方内置 CLI 只有在完成初始化并退出桌面版后，才可管理 desktop profile；NPM/NPX CLI 只针对 web profile。加载新版 bridge 后，再回到 DSH Pet 的「Harness 连接」页重新检测。
如果已安装旧包 @sundusk/dsh-moodball-status，请在对应 Harness 中移除旧包，再按上面的方式安装新版并重启 Harness。桌面版请在「插件」页面操作；源码版或 CLI 版可使用相应的 dsh plugin --profile web remove @sundusk/dsh-moodball-status 命令。
✨ 使用
安装并启动后，桌面上没有任何窗口——它是个纯菜单栏应用（不占 Dock、不抢焦点）：
菜单栏右侧出现状态图标，桌面右下角出现鲸鱼娘（或你选择的其他皮肤）。
以后怎么打开？
- 访达 → 应用程序（或 ~/Applications）：找到「DSH Pet」，双击
- 终端：
open -a "DSH Pet"
菜单栏图标功能
菜单栏采用 DeepSeek Harness 官方 FishLogo 的单色轮廓，自动适配深浅背景。悬停可查看当前状态，展开菜单可查看状态文字与状态色点。素材来源与许可随 App 一同附在 ThirdPartyNotices.txt 中。
| 菜单项 | 功能 |
|---|
| 状态文字 | 当前连接状态、状态名与桥接方式（如「已连接 · 工具调用 · 本地桥接」） |
| 隐藏 / 显示宠物 | 隐藏或显示桌宠及其操作栏 |
| 设置… | 打开设置面板 |
| 退出 | 退出 app（不影响 DSH 本体） |
鲸鱼娘交互
- 拖动：按住鲸鱼娘拖动，她会朝拖动方向奔跑，并记住停留位置
- 双击：待机时鲸鱼娘会挥手
- 锁定位置（设置面板 → 交互与提醒）开启后不可拖拽，仍可双击
第一阶段：快捷入口
- 默认按 Option+Space，可在「设置 → 快捷键」重新录入组合键或关闭。快捷键冲突时 DSH Pet 不会抢占其他应用，并会在设置面板提示。
- 「设置 → 快捷键」的“菜单快捷键”区域可分别修改或关闭输入消息、新建会话、选择工作区、打开 Harness、显示/隐藏宠物和打开设置的菜单快捷键；默认使用不冲突的
⌘ 组合键。
- 快捷键会显示并聚焦输入框；输入框已打开时重复按下不会关闭、不清空草稿。按 Esc 收起输入框，中文输入法选字时 Enter 仍只确认候选文字。
- 菜单栏“隐藏/显示宠物”同时控制桌宠及其操作栏。点击穿透设为“永远点击穿透”时，仍可通过全局快捷键唤起输入框。
向 Harness 发送消息
宠物下方的短横条会在鼠标靠近时变成笔记按钮。点击后展开原生输入框：
- 先在「Harness 连接」页选择目标，再选择该 Harness 已注册的工作区；DSH Pet 会记住当前目标。
- Enter 发送，Shift+Enter 换行；中文输入法选字时 Enter 只确认候选文字。
- 第一条消息创建 DSH Pet 专用会话，后续消息沿用同一会话；执行中、等待授权或等待回答时暂时不能继续发送。
- “新建会话”只解除当前绑定，不会删除或停止旧 Harness 任务；“打开 Harness”进入当前选定 Harness 的首页。
- 命令插件不可用时仍可显示旧版状态，但输入功能会明确禁用；草稿不会被静默丢弃。
第二阶段：多任务卡片与提醒
-
待机时保留宠物下方的短横线；鼠标靠近后展开底部功能栏，从左到右分别是输入消息、当前任务和最近任务。
-
当前工作区的普通 Harness 会话会显示为任务卡片，子 Agent 不单列。多任务默认只显示排序第一项，箭头展开纵向列表，最多直接显示四张，超出部分在卡片区域内滚动。
-
排序优先级为等待操作、失败未读、完成未读、运行中、其他最近更新任务。点击卡片查看详情并标记已读；“继续此会话”才会切换输入目标，当前草稿不为空时会先阻止切换。
-
任务标题、状态图标和更新时间优先来自 Harness；标题服务不可用时使用工作目录和会话 ID 后缀回退。未读位置由 DSH Pet 本地保存，首次加载不会把历史任务批量标成未读，重连后会继续使用已读位置。
-
精确打开会话仍未发现可由插件调用的官方外部深链，因此详情提供“打开 Harness”和“复制会话 ID”。
第三阶段：截图附件
- 在输入框内直接粘贴剪贴板图片，或点击回形针菜单选择“框选截图”；框选期间桌宠和快捷控件会暂时隐藏，完成或取消后恢复。
- 图片先保存在 DSH Pet 的私有草稿目录并显示缩略图，可移除；提交失败会保留文字和图片，并提供重试。只有 Harness 确认接收后才清理应用私有副本。
- 支持图片单独发送，也支持图片随文字发送。数量、单张大小和总大小使用当前 Harness 部署返回的限制，不写死默认值。
- DSH Pet 将图片交给官方
sessionController.prompt 附件入口，由 Harness 校验当前模型的图像能力并持久化；不会把本机临时文件路径作为消息内容，也不会删除 Harness 已保存的附件。
鲸鱼娘外观
设置面板 →「桌宠外观」可调整宠物形象、大小、状态气泡与发光，修改即时生效。
首次安装默认显示鲸鱼娘；之后会记住你选择的宠物。
内置「鲸鱼娘Q版」，可在「桌宠外观」直接选择。素材来自 Codex 同名宠物包，保留原始透明图集与帧序：空闲用待机，思考与工具调用用专注思考，授权与抉择用等待用户，完成用跳跃庆祝，失败用低落动作；双击挥手、左右拖拽奔跑也沿用原动作，共使用 51 帧。审阅与 16 向视线帧保留在图集中，暂未接入交互。
鲸鱼娘的悬浮窗口按精灵和光晕收紧；状态气泡出现时才向上扩展，精灵之外的透明区域不会触发展开操作栏。
状态预览与导出
「设置 → 桌宠外观 → 效果预览」可切换状态；点击“放大 / 导出…”可预览鲸鱼娘的全部状态，
选择是否包含状态文字，并通过保存面板导出 512×512 透明背景 PNG。预览中的宠物和状态选择不会改变实际桌宠或任务。
导入 Codex 宠物
「设置 → 宠物管理」位于快捷键下方。点击“导入宠物”，选择包含 pet.json 的文件夹，预览后确认导入，再点击“使用”切换桌宠。已导入宠物也会出现在「桌宠外观」的选择列表中。
- 支持 Codex v2 本地宠物包：
spriteVersionNumber: 2，图集为透明 PNG 或 WebP，尺寸为 1536×2288（8×11，每格 192×208），不超过 20 MiB。
- 可以从
~/.codex/pets 选择已有宠物目录；不需要运行 Codex。宠物的任务动作由当前 Harness 状态驱动。
- 导入只复制清单与图集到
~/Library/Application Support/DSH Pet/Pets，不会执行包内代码，也不会修改原始目录。重复图集不会覆盖已有宠物。
- 导入不会自动改变正在使用的桌宠；选择会自动保存。删除当前宠物会回退到鲸鱼娘，删除只影响 DSH Pet 副本。
- “刷新”重新读取 App 保存的副本；修改原始 Codex 宠物不会自动更新已导入副本。暂不支持 ZIP 或 v1 图集。
状态气泡与发光的颜色
状态颜色用于鲸鱼娘的提示气泡，以及开启“桌宠发光”后的光晕。
| 状态 | 默认颜色 |
|---|
| 空闲 | 蓝色 |
| 正在思考中 | 绿色 |
| 工具调用 | 紫色 |
| 等待你的授权 | 黄色 |
| 做出你的抉择 | 粉色 |
| 搞定啦 | 青色 |
| 出错了 | 红色 |
| 停止 / 中断 | 黑色 |
| 未连接 / 插件未装 | 灰色 |
可在「设置 → 桌宠外观 → 状态配色」自定义颜色。
状态桥接与设置面板
「Harness 连接」页会显示当前可发现的 Harness 实例，并统一选择状态与消息目标。只有一个实例时 DSH Pet 自动使用它；两个实例同时启动时，首次需要用户选择。目标确定后，另一个实例出现不会触发自动切换。
新版 bridge 为每个运行实例提供同源的状态与命令通道，菜单、任务卡片和快捷键等打开入口都会跟随当前选定的 Harness。新版 bridge 必须先在目标 Harness 中加载，App 才能读取实例检测元信息；仅更新 DSH Pet App 不足以完成识别。
旧版 bridge 没有来源身份时，DSH Pet 保留只读状态兼容，连接页显示「来源未知」，默认禁用发送并提示升级插件；旧版状态兼容不保证消息与状态来自同一 Harness。DSH Pet 不会启动、停止、升级或修改 Harness，也不模拟 Web UI。
菜单栏 →「设置…」包含六个页面：「桌宠外观」「交互与提醒」「快捷键」「宠物管理」「Harness 连接」和「关于与更新」。可在其中调整桌宠、交互行为、快捷入口、当前 Harness 目标和版本信息，修改立即生效。
「关于与更新」页只检查 GitHub Releases 是否有新版本，有则提供「前往下载」链接，不自动安装。
卸载
git clone --depth 1 https://github.com/sundusk/dsh-pet.git
cd dsh-pet
bash uninstall.sh
脚本会退出并移除 DSH Pet.app 与旧版 MoodBall.app（检查 ~/Applications 和 /Applications），
并询问是否同时移除 DSH Pet 桥接插件（移除后重启 dsh web 生效）。
常见问题
- 鲸鱼娘显示未连接？ 先确认目标 Harness 正在运行，并确认新版 bridge 已在目标 Harness 中加载；仅更新 DSH Pet App 不足以完成实例检测。
- 「设置 → 插件」里怎么没有 DSH Pet 插件卡片？ 这是正常的——桥接插件没有任何设置项
（所有配置都在 app 的设置面板里），所以不显示配置卡片。可在「设置 → 插件 → 插件列表」
中查看它（状态为「已挂载」）。
🔧 开发
# DSH Pet 桥接插件：构建到 lib/
pnpm install
pnpm build
# app：构建 dist/DSH Pet.app（含鲸鱼娘图集）并启动
bash make-app.sh
📄 License
本项目采用 MIT License 发布。
