前言¶
用 DeepSeek Harness（DSH）跑智能体任务时，任务状态多在浏览器或桌面客户端里。窗口最小化或切到其他应用后，不容易一眼看到当前是在思考、等授权还是已经失败。社区项目 dsh-mac-pet 把同一套状态接到 macOS 桌面上：原生桌宠展示动作与气泡，菜单栏提供入口，并可通过桥接插件与正在运行的 Harness 会话同步。下面按「项目是什么 → 能做什么 → 怎么装 → 日常怎么用 → 注意点」说明。
这是什么¶
dsh-mac-pet 是 DSH 的 macOS 桌面伴侣，维护者为 sundusk。它由两部分组成：
- DSH Pet.app：默认以鲸鱼娘像素形象显示 Agent 状态，提供状态气泡、任务卡片与消息输入；要求 macOS 14+，且需要本机有正在运行的 DeepSeek Harness。
- 桥接插件（npm 包名
dsh-mac-pet）：订阅 Agent 会话事件，提供 HTTP/状态 Socket、用户级命令 Socket，以及「安装桌宠」引导与会话跳转；无插件侧设置项，应用内设置面板完成连接与外观等配置。
桌面 App 与桥接插件共用版本号（当前仓库 package.json 为 0.9.5）。已发布的 DSH-Pet.app.zip 可从 GitHub Releases 获取；安装脚本也会拉取最新 Release。
在 SkillHub 目录中该条目分类为客户端，简介为：DSH Pet — macOS desktop companion and dsh-mac-pet bridge plugin for DeepSeek Harness。
核心功能¶
状态与桌宠¶
鲸鱼娘（或你在设置里选择的皮肤）会随任务状态切换动作，包括待机、思考、等待操作、完成、失败、挥手，以及左右拖拽时的奔跑。状态气泡与可选「桌宠发光」使用可配置配色（空闲、思考、工具调用、等待授权、抉择、完成、失败、停止、未连接等均有默认色，可在「桌宠外观 → 状态配色」修改）。
多任务时，状态气泡可进入「气泡卡组」：总览页显示任务数与最高优先级动作，再按任务分页展示当前动作；双击宠物或任务气泡可唤起对应 Harness 并打开该会话（依赖已加载的桥接插件）。
消息与任务¶
桌宠下方功能栏支持向 Harness 发送消息：需在「Harness 连接」页选择目标实例与工作区；Enter 发送，Shift+Enter 换行。第一条消息会创建 DSH Pet 专用会话，后续沿用同一会话。执行中、等待授权或等待回答时暂时不能继续发送。
已注册工作区的普通 Harness 会话会以任务卡片展示（含工作区标注）；支持排序、已读/未读、最近任务历史，以及从任务详情「打开此会话」。输入框内 @ 可引用工作目录文件/目录，$ 可选择当前会话允许调用的技能。
桥接插件在 Harness 侧做的事¶
插件向 DSH 注册客户端注入（@deepseek-ai/dsh-client-ui-workspace），用于侧栏「安装桌宠」等引导。它不替代 Harness 本体权限：与所有 DSH 插件一样，以当前 dsh 进程的权限与网络策略运行；安装前建议在 GitHub 仓库阅读源码与许可证（README 未在已抓取片段中单独列出许可证字段，以仓库根目录为准）。
安装与启用¶
先运行 DeepSeek Harness¶
DSH Pet 依赖本机已启动的 Harness。常见 Web 方式之一：
npx @deepseek-ai/dsh web
默认在 http://127.0.0.1:3080 打开 Web UI。已有 Harness 桌面版的用户可继续使用桌面版；加载桥接插件后，在 DSH Pet 的「Harness 连接」页检测连接。
安装桌宠应用（推荐流程）¶
若已在 Harness「插件」页安装并启用 dsh-mac-pet，可从侧栏「安装桌宠」进入下载与安装引导。也可在单独终端执行仓库提供的安装脚本（脚本会识别桌面版、NPM/NPX 或源码版 Harness，并下载/安装 DSH Pet.app）：
git clone --depth 1 https://github.com/sundusk/dsh-mac-pet.git
cd dsh-mac-pet
bash install.sh
安装脚本只需执行一次。若插件刚装好而 Harness 仍在运行，脚本仍可继续安装并启动 App；请在当前任务结束后重启一次 Harness 以加载插件，无需再次运行安装脚本。源码版 Harness 可显式指定路径，例如：
DSH_SOURCE_ROOT="$HOME/Projects/deepseek-harness" bash install.sh
手动安装桥接插件¶
若只装了 App、需单独补装插件，按你的 Harness 启动方式执行对应命令后重启 Harness：
# 通过 npx 运行 Harness
npx @deepseek-ai/dsh plugin --profile web add dsh-mac-pet
# 已安装全局 dsh 命令
dsh plugin --profile web add dsh-mac-pet
# 从源码运行 Harness：先进入 deepseek-harness 源码根目录
pnpm dsh plugin --profile web add dsh-mac-pet
Harness 桌面版请在应用内「插件」页搜索并启用 dsh-mac-pet（使用 desktop profile；NPM/NPX CLI 不能管理桌面版 profile）。安装器检测到桌面版时不会把插件误装到 web profile。
典型用法¶
- 安装并启动 DSH Pet（访达 → 应用程序中的「DSH Pet」，或
open -a "DSH Pet"）。它是纯菜单栏应用：菜单栏右侧有状态图标，桌宠默认在桌面一角。 - 在 App「Harness 连接」页选择目标 Harness 并检查连接；在输入区域选择工作区后发送消息或查看任务卡片。
- 默认 Option+Space 可聚焦消息输入框（可在「设置 → 快捷键」修改或关闭）。菜单栏菜单可隐藏/显示宠物、打开设置或退出（退出不影响 DSH 本体）。
- 待机时双击鲸鱼娘可挥手；在「交互与提醒」可开启锁定位置以禁止拖拽。
- 需要换皮肤时：「桌宠外观」调整大小与气泡；「宠物管理」可导入符合 Codex v2 规范的本地宠物包（含
pet.json的文件夹），导入副本位于~/Library/Application Support/DSH Pet/Pets。
当前版本输入框未提供图片粘贴或截图附件入口；桥接协议虽保留图片附件能力，但不能从当前输入界面使用。
适用场景与注意¶
适合谁：长期在 macOS 14+ 上用 DSH 做智能体开发或日常任务、希望不盯着浏览器也能看到 Agent 状态，并从桌面快速发消息或跳转会话的用户。
环境：仅 macOS；必须与本机 Harness 同机协作。多实例、多源码目录并存时，安装脚本会要求选择目标，避免把插件装进错误仓库。
安全与信任：插件与 App 均来自社区仓库 sundusk/dsh-mac-pet。启用前请自行审阅代码与发布包；社区目录 SkillHub 条目 与 DeepSeek / 幻方无官方从属关系，DSH 生态理念是「一切皆插件」，安装来源以你信任的目录或 GitHub 为准。
Harness 重启、插件更新后，若跳转会话等行为有变，按 README 说明更新并重新加载桥接插件后再在 DSH Pet 中「重新检测」连接。
结尾¶
dsh-mac-pet 把 Harness 的会话状态与命令通道接到 macOS 桌面：桌宠 + 桥接插件一体，减少「任务跑到哪了」的信息断层。查阅维护说明与版本发布见 GitHub：https://github.com/sundusk/dsh-mac-pet；目录索引见：https://www.skillhub.cn/plugins/sundusk/dsh-mac-pet。
