桌面宠物伴侣 bloodarea/dsh-pets

DSH Pets

DeepSeek Harness 的跨平台桌面宠物。

DSH Pets 把正在运行的 AI 智能体会话搬到桌面上：用动画角色呈现，按事件播放语音，并给出可操作的提醒。你可以随时盯住并行任务，一键跳到对应会话，知道智能体什么时候需要你——不用一直盯着 DSH Web 界面。

项目状态：早期开发中。 本 README 描述的是产品设想和开发里程碑。标为「计划中」的功能并不表示已经实现。本项目基于 zuodazuoqiang001/dsh-pet 的思路和代码，那是一个面向 DSH 的 Windows 桌面宠物插件。

功能概览

产品围绕四个模块组织：

| 模块 | 计划中的能力 |
| 会话管理 | 显示活跃的顶层 DSH 会话，快速切换到选中的会话，在任务完成、失败或请求审批时提醒。错过的提醒仍可查看。 |
| 角色系统 | 显示 Spine 角色或精灵图宠物，把角色与模型身份关联，将智能体状态映射为表情和动作。 |
| 语音系统 | 按事件播放预录语音，支持角色专属语音包、音量与静音控制、冷却时间，以及可选的唇形同步。 |
| 桌面交互 | 透明悬浮窗口、拖动与位置记忆、系统托盘、点击穿透、勿扰模式，以及基础性能设置。 |

两项不可妥协的能力：

1. 在运行中的会话之间快速切换，入口是桌面宠物的会话列表或气泡。
2. 可靠地收到任务完成提醒，并且能一键回到对应会话。

角色动画和语音让这些流程更有表现力，但绝不能妨碍会话控制和提醒正常工作。

使用体验

- 工作中： 角色对活跃智能体做出反应；会话气泡显示还有哪些任务在跑。
- 需要关注： 角色发出审批请求信号，并提供直达会话的快捷入口。
- 已完成： 播放动画，可选播放预录语音，播报结果；提醒会一直保留，直到你查看。
- 空闲： 角色回到细微的待机动作，不打扰桌面工作。
- 多个智能体： 提醒排队或合并，不会同时播放多条语音。

角色可以映射到模型家族（例如 DeepSeek、Claude 或 GPT），也支持手动覆盖。即使模型发生变化，会话仍以 session ID 标识。

计划架构

DeepSeek Harness (DSH Web / Cordis plugin)
├─ Session and agent status
├─ Task completion / failure / approval events
└─ Session focus and navigation
│
│ Local, restricted communication
▼
Electron 桌面伴侣（主进程） ├─ 连接 / 通知 / 会话控制器 ├─ 窗口、托盘、平台集成 └─ React + TypeScript UI ├─ 会话气泡与通知历史 ├─ Spine 渲染器（主角色格式） ├─ 静态图片回退（无 GPU / 精简模式） └─ 预录语音播放 + 可选口型同步

目标平台： Windows、Linux、macOS。首轮桌面验证计划在 Ubuntu 24.04 Desktop + DSH Web 上进行，随后补做 Windows 与 macOS 兼容性测试。Linux X11/XWayland 与原生 Wayland 在全局窗口定位、置顶行为、焦点上有不同限制；支持情况以实测为准，不做假设，并据此撰写文档。

角色资源

角色包是自包含目录，内含一份契约文件。内置默认包随包发布；其余角色包按需下载到用户数据目录，该目录优先于内置副本。

assets/characters/ # bundled, read-only
index.json # downloadable-pack index (version, sha256, url)
deepseek/ # the only pack shipped with the package
manifest.json
LICENSE
preview.webp
spine/ # Spine skeleton, atlas and textures
voice/
index.json # voice index: every event and line the pack can speak
<event>/<id>.ogg # one file per line, e.g. task_completed/task_completed_01.ogg

~/.dsh/pets/characters/<id>/ # downloaded, writable, overrides the bundled copy

manifest.json 就是契约，运行时从不猜文件名。它声明 Spine 入口及缩放、锚点，智能体状态 → 动画的映射（idle、working、attention、done、failed），语音索引的位置（voice.index），以及无 GPU 加速机器用的静态图片回退。事件集合由语音索引定义，不在 manifest 里逐一列举：内置包目前含 34 个事件、共 48 条语音，每条语音的路径为 voice/<event>/<id>.ogg。语音包不带自己的版本号——角色包 manifest.json 里的 version 同时覆盖美术、动画和音频。角色包也可以完全不带语音索引，此时所有事件静音。

这套布局是约定的目标：内置包已按此方式发布资源，但运行时语音播放尚未实现。语音在制作阶段提前录制或生成，随角色包一起发布。运行时不要求文本转语音生成，不强制使用 TTS API，也无需把会话文本发给语音服务商。

制作插画、骨骼动画或音频的工具可在资源制作阶段离线使用，不属于 DSH Pets 运行时。

路线图

v0.1 — 可用的桌面伴侣

- [ ] DSH 插件连接，按会话可靠跟踪状态
- [ ] 活跃会话气泡/列表，一键切换会话
- [ ] 完成、失败、审批提醒，带去重
- [ ] 错过/未读通知，安全重连行为
- [ ] 跨平台桌面窗口与托盘基础
- [ ] Spine 角色渲染，静态图片兜底
- [ ] 预录语音播放、静音、事件冷却
- [ ] 拖拽、记住位置、基础免打扰控制
- [ ] Ubuntu 24.04 端到端验证

后续改进

- [ ] 模型到角色的映射、角色包管理界面、按需下载角色包
- [ ] 更自然的嘴型同步与待机互动
- [ ] 边缘停靠、自动隐藏、可配置的鼠标穿透
- [ ] 省电 / 降帧模式
- [ ] 更广的 Windows、macOS、X11、Wayland 兼容覆盖

路线图仅供参考，会随实现与兼容性测试的推进而调整。

安装

目前还没有稳定的跨平台发布版本。 等有可安装的版本后，会在这里公布安装步骤和支持的 DSH 版本。请不要以为原来只支持 Windows 的 dsh-pet 安装说明适用于本项目。

可靠性、隐私与资源占用

设计优先级：

- 优先采用明确的任务生命周期信号；连接中断不能被误判为成功完成。
- 对完成事件去重，保留未读通知，在 DSH 支持的情况下重连后恢复可见状态。
- 角色渲染器、音频或 GPU 加速不可用时，控制功能仍要可用。
- 默认只在本地通信，限制对外暴露的控制端点；远程访问配置必须单独加固。
- 默认不朗读任务内容。预录语音只播报预设的状态消息，不播报任意代码、密钥或聊天内容。
- 为长时间桌面使用提供静音、免打扰和降低资源占用的选项。

这些是工程目标，不是安全审计，也不代表功能已经全部完成。

开发与贡献

项目处于早期阶段。欢迎提交 issue、平台相关的 bug 报告和可复现的测试用例。提新功能之前，请优先关注两个核心工作流：会话切换和可靠的完成通知。

署名与许可

本项目采用分项许可：源代码为 MIT，角色美术资源为 CC BY-NC-SA 4.0。以根目录的 LICENSE 为准。

项目代码：MIT

DSH Pets 计划从 zuodazuoqiang001/dsh-pet（MIT）演进而来。源代码、脚本和文档均为 MIT，复用的上游代码保留其原始版权与许可声明。MIT 授权不覆盖 assets/characters/。

角色包：CC BY-NC-SA 4.0，非商业

内置的 deepseek 包基于社区同人作品，按 Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International（CC BY-NC-SA 4.0）分发，遵循原作者的版权声明。三条规则：

1. 署名链必须完整。 鲸鱼娘原型出自上善无形 / 上善，DeepSeek 拟人化重绘出自 ZipZipPipe（作者主页），本项目负责衍生制作与打包。三方都必须署名；漏掉任一链接即违反许可。
2. 免费分发不等于商业授权。 在 GitHub Releases 或 npm 上免费发布，满足非商业要求，但不授予也不转让任何商业权利。任何人不得以此为由，把角色包或其衍生物放进商业产品、付费服务或营利性分发。
3. 我们无权授予自己不持有的权利。 每个角色、贴图、音频素材都需要各自核实过的上游授权；无法核实的素材一律排除，原因列在 ATTRIBUTION.md。第三方素材保留自己的许可——本项目不代其授予任何权利。

- 复用要求：保留署名、注明你的修改、仅限非商业使用，衍生贡献按同一 CC BY-NC-SA 4.0 发布。
- 每个包都在素材旁自带 LICENSE 和 ATTRIBUTION.md——完整来源链和刻意未收录的素材，见 assets/characters/deepseek/LICENSE 与 ATTRIBUTION.md。
- 下架：若权利人对任一收录素材有异议，请开 issue，附上文件路径和可核实的来源；核实后即移除该素材。CC 许可不可撤销，因此我们承诺的是停止分发，而非修改许可。
- 角色包以模型系列为主题，但不是官方品牌素材。

商标

DeepSeek、Claude、GPT、Kimi、Qwen 等名称与标识归各自所有者。本项目不暗示与上述任何一方存在关联或获得其背书。

Spine 运行时

Spine 运行时与导出的动画数据受 Esoteric Software 商业许可条款约束；发布前请确认适用条款。其他第三方 SDK 与素材保留各自许可。

DSH Pets——为你的 AI 智能体会话提供一个常驻桌面的小巧入口。