# DSH Pets

**适用于 DeepSeek Harness 的跨平台桌面宠物插件。**

[English](README.md) | [简体中文](README_zh.md)

DSH Pets 通过动态角色、预录制语音和可操作的通知，将正在运行的 AI Agent 会话呈现在桌面上。你可以快速了解多个任务的状态、一键切换到指定会话，并在任务完成或需要人工操作时收到提醒，无须反复查看 DSH Web 页面。

> **项目状态：早期开发。** 本文介绍目标功能与开发计划；列为规划的功能**不代表已经实现**。项目计划参考并继承 [zuodazuoqiang001/dsh-pet](https://github.com/zuodazuoqiang001/dsh-pet) 的实现基础，该上游项目是面向 Windows 的 DSH 桌宠插件。

## 核心功能

产品围绕四个模块设计：

| 模块 | 规划能力 |
| --- | --- |
| **会话管理（Session Management）** | 展示正在运行的 DSH 顶层会话、快速切换会话；在任务完成、失败及等待授权时提醒，并保留未读通知。 |
| **角色系统（Character System）** | Spine 角色与精灵图桌宠、模型身份与角色绑定、Agent 状态到动作和表情的映射。 |
| **语音系统（Voice System）** | 根据事件播放**预录制的固定语音**，支持角色专属语音包、音量、静音、防重复播报和可选口型同步。 |
| **桌面交互（Desktop Interaction）** | 透明悬浮窗口、拖拽和位置记忆、系统托盘、鼠标穿透、免打扰模式及基础性能设置。 |

**两项不可妥协的核心指标：**

1. **快速切换正在运行的会话：** 从桌宠会话列表或气泡直接进入指定 DSH 会话。
2. **可靠的任务完成提醒：** 任务结束后主动提醒，并能直接定位到对应会话。

角色动画和语音负责增强角色表现。即使关闭动画、静音或模型加载失败，会话切换和提醒功能也必须正常工作。

## 交互示例

- **正在执行：** 角色进入工作动画，气泡展示当前运行中的会话。
- **等待授权：** 角色播放提醒动作，点击气泡即可进入需要处理的会话。
- **任务完成：** 播放完成动画及可选的预录制台词，通知在用户查看前仍可追溯。
- **空闲：** 使用轻量的呼吸、眨眼或待机动作，尽量减少对桌面工作的干扰。
- **多个 Agent 并发：** 对通知排队或合并，避免多个角色同时发声。

计划允许按模型系列（如 DeepSeek、Claude、GPT）分配角色，也允许用户手动覆盖。会话仍通过**会话 ID** 唯一识别，即使会话使用的模型发生变化也不影响定位。

## 计划采用的技术架构

```text
DeepSeek Harness（DSH Web / Cordis 插件）
  ├─ Agent 与会话状态采集
  ├─ 任务完成、失败、等待授权事件
  └─ 会话定位与跳转
                 │
                 │ 本机受限通信
                 ▼
Electron 桌面客户端（主进程）
  ├─ 连接管理、通知管理、会话管理
  ├─ 桌面窗口、系统托盘、平台适配
  └─ React + TypeScript 界面
       ├─ 会话气泡、通知历史
       ├─ Spine 渲染器（主角色格式）
       ├─ 静态图降级（无 GPU / 低耗模式）
       └─ 预录制语音播放、可选口型同步
```

**目标平台：** Windows、Linux、macOS。首个桌面验收环境计划采用 **Ubuntu 24.04 Desktop + DSH Web**，再逐步完善 Windows 与 macOS 的测试。Linux 的 X11/XWayland 与原生 Wayland 对全局定位、窗口置顶和焦点切换存在不同限制，具体支持范围以实测结果为准。

### 角色资产

每个角色是一个自包含目录，只有一个契约文件。默认角色随安装包发布；其余角色按需下载到用户数据目录，同名时用户目录优先于内置副本。

```text
assets/characters/                 # 内置，只读
  index.json                       # 可下载角色索引（版本、sha256、下载地址）
  deepseek/                        # 唯一随包发布的角色
    manifest.json
    LICENSE
    preview.webp
    spine/                         # Spine 骨骼、图集与贴图
    voice/
      index.json                   # 语音索引：本包全部事件与台词
      <event>/<id>.ogg             # 每条台词一个文件，如 task_completed/task_completed_01.ogg

~/.dsh/pets/characters/<id>/       # 下载而来，可写，优先于内置副本
```

`manifest.json` 是唯一契约，运行时**不靠约定文件名**猜资源。它声明 Spine 入口与缩放、锚点，Agent 状态到动画的映射（`idle`、`working`、`attention`、`done`、`failed`），语音索引的位置（`voice.index`），以及无 GPU 加速时使用的静态图降级。**事件集合由语音索引定义，不在 manifest 里枚举**：内置包当前 48 条台词 / 34 个事件，每条台词的地址是 `voice/<event>/<id>.ogg`。语音包不自带版本号，角色版本统一由 manifest 的 `version` 表达（美术、动画、音频一起走）；完全没有语音索引的包，所有事件保持静音。

以上是**已确定的目标结构**：内置包的素材已按此布局落盘，但运行时语音播放尚未实现。语音由开发者**提前录制或生成**，随角色资源包发布。运行过程中**不要求实时 TTS 推理**，无需强制接入语音 API，也无需将会话正文发送给语音服务。

角色立绘、骨骼动画和配音可以在开发阶段利用第三方工具离线制作；这些资产生产工具不随 DSH Pets 运行时一起安装。

## 开发路线图

### v0.1 — 可实际使用的桌面伙伴

- [ ] DSH 插件连接与可靠的会话级状态追踪
- [ ] 运行中会话气泡/列表及一键会话切换
- [ ] 完成、失败、等待授权提醒与事件去重
- [ ] 未读通知历史及断线重连状态处理
- [ ] 跨平台桌面悬浮窗口与系统托盘基础能力
- [ ] Spine 角色渲染与静态图降级
- [ ] 预录制语音、静音和播报冷却机制
- [ ] 拖拽、位置记忆及基础免打扰设置
- [ ] Ubuntu 24.04 端到端验收

### 后续迭代

- [ ] 模型到角色的自动映射、角色资源管理界面与按需下载
- [ ] 更自然的口型同步及轻量待机互动
- [ ] 桌面边缘吸附/隐藏和可配置鼠标穿透
- [ ] 节能模式与低帧率运行
- [ ] 完善 Windows、macOS、X11、Wayland 的兼容性测试

路线图将根据实际开发进度和平台测试情况调整。

## 安装

**目前尚未提供经过验证的跨平台稳定版本。** 可安装版本发布后，将在这里补充安装命令、适配的 DSH 版本及系统要求。上游 Windows 版 `dsh-pet` 的安装方式不应直接视为本项目的安装说明。

### 当前插件形态（开发中）

本仓已经可以按 Host-only Cordis bundle 安装：`package.json` 声明 `dsh.bundle.patch`，`cordis.patch.yml` 激活入口，`index.js` 把随包分发的 `skills/<name>/SKILL.md` 注册成 Agent 技能。因此角色制作技能 `three-view-parts` 会直接出现在技能目录里，不需要再拷进 `.agents/skills`。

```bash
# 把当前 checkout 链接进 profile（以 web 为例）
dsh plugin --profile web add /path/to/dsh-pets

# 安装后重启 Harness 激活 bundle；技能会出现在会话技能目录里，可直接按名字加载
# 卸载
dsh plugin --profile web remove dsh-pets
```

当前阶段插件只负责注册技能；桌宠窗口、会话跟踪、语音播放与系统托盘仍按上面的路线图推进。

## 可靠性、隐私与资源占用

重点遵循以下设计原则：

- 优先依据明确的任务生命周期事件判断结果；**连接中断不等于任务成功完成**。
- 完成事件去重，保存未读消息，并在 DSH 支持的范围内于重连后恢复状态。
- 角色渲染、音频或 GPU 加速不可用时，仍保留会话切换和通知功能。
- 默认使用本地受限通信，避免无鉴权地暴露桌宠控制接口；远程连接需单独做好安全配置。
- 默认不朗读代码、密钥和完整会话内容；固定语音只负责播报预定义的**状态提示**。
- 提供静音、免打扰、低资源占用等设置，适合长期桌面常驻。

以上是**工程目标**，并非功能完成声明或安全审计结论。

## 开发与贡献

项目仍处于早期开发阶段，欢迎通过 Issues 提交建议、不同操作系统下的兼容性反馈及可复现的缺陷。新增功能优先服从两个核心场景：**运行中会话快速切换**和**可靠的任务完成提醒**。

## 来源与许可证

本项目采用**分离授权**：源代码 MIT，角色美术 CC BY-NC-SA 4.0。完整条款以根目录 [LICENSE](LICENSE) 为准。

### 项目代码：MIT

DSH Pets 计划基于 [zuodazuoqiang001/dsh-pet](https://github.com/zuodazuoqiang001/dsh-pet)（MIT）逐步扩展为跨平台桌宠。源代码、脚本与文档采用 MIT，复用上游代码时保留原有版权与许可证声明。**MIT 授权不覆盖 `assets/characters/`。**

### 角色包：CC BY-NC-SA 4.0，禁止商用

内置的 `deepseek` 角色包基于社区同人素材，采用 **知识共享 署名-非商业性使用-相同方式共享 4.0 国际** 许可（[CC BY-NC-SA 4.0 中文说明](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-hans)），依据原作者本人发布的[版权声明](https://www.bilibili.com/opus/1247156596114456581)。有三点必须注意：

1. **署名链必须完整**：鲸鱼娘原型设计者 上善无形 / 上善，DeepSeek 拟人化二次设计者 ZipZipPipe（[作者主页](https://space.bilibili.com/4168597)），本项目负责衍生制作与整理。三环均须保留，省略任何一环都构成许可违约。
2. **免费分发不等于可以商业使用**：在 GitHub Release、npm 上免费发布符合非商业用途，但**不构成、也不转授任何商业使用权**。任何人不得据此将角色包或其演绎用于商业产品、付费服务或营利性分发。
3. **不能替其他角色或第三方素材授予你没有的权利**：每个角色、贴图与音频资产的原始授权都需单独确认，未确认的一律不收录（原因见 `ATTRIBUTION.md`）；第三方资产保留其各自许可，本项目不代为授权。

- 使用与再分发要求：保留署名、标明修改内容、遵守非商业限制、以**相同许可**发布衍生贡献。
- 每个角色包都在自己的目录内附 `LICENSE` 与 `ATTRIBUTION.md`——详见 [assets/characters/deepseek/LICENSE](assets/characters/deepseek/LICENSE) 与 [ATTRIBUTION.md](assets/characters/deepseek/ATTRIBUTION.md)，其中也列明了**刻意未收录**的素材。
- **下架与更正**：权利人若认为素材使用不妥，请在 [Issue](https://github.com/bloodarea/dsh-pets/issues) 中指明文件路径与可核实的出处，核实后立即移除。CC 许可一经授予不可撤销，因此这是"停止分发"的承诺，而不是修改许可条款。
- 角色包仅以模型系列为主题，**不代表任何厂商官方**。

### 商标

DeepSeek、Claude、GPT、Kimi、Qwen 等名称与商标归各自权利人所有。本项目与上述厂商不存在隶属、合作或背书关系。

### Spine 运行时

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

---

**DSH Pets** — 让 AI Agent 会话有一个随时可见、随时可操作的桌面入口。