# DSH 桌宠（DeepSeek Harness 桌面伴侣）产品说明

> 版本：v0.1.0 ｜ 形态：独立桌面应用（Electron）｜ 平台：macOS（当前验证）

## 一、产品概述

**DSH 桌宠**是一只悬浮在桌面上的 DeepSeek 小鲸鱼，实时反映 DeepSeek Harness（DSH）的会话状态——**工作中、需要你确认、任务完成待查看、空闲、离线**。它让用户在切到其他软件工作时，也能"瞥一眼"就知道 agent 当前的进展和需求，对于“需要确认”和“完成待查看”两个重要节点，还有专属语音提示，把"任务状态"从需要主动查看的页面，变成桌面上一眼可读的实时信号。

### 状态模型（5 态，按紧迫度排序）

| 状态 | 鲸鱼表现 | 触发条件 |
|---|---|---|
| 🔴 需要确认 | 瞪大眼 + 眉毛 + o 嘴，气泡列出所有待确认项，语音提示 | 任一会话触发权限审批（approval/requested）或提问（question/requested） |
| 🔵 工作中 | 专注半眯眼 + 喷水（双侧水花 + 水滴动画），气泡按会话粒度列出所有运行中会话 | 任一会话 running |
| 🟢 完成待查看 | 开心眯眼 ^^ + 星星，气泡列出完成项，语音提示 | 会话由运行转空闲（120 秒窗口） |
| 💤 空闲 | 闭眼睡觉 + zzz | 无运行、无待确认 |
| 😵 离线 | 灰度 + X 眼，自动重试 | DSH GUI 不可达 |

### 状态信号来源（全部只读，对 DSH 零写入）

- **轮询** `POST /api/session.list`（2 秒）——会话标题、running、todos 基线
- **WebSocket `/api/events.mux`**——审批/提问/队列推送（断线自动重连，服务端重放未决项）
- **WebSocket `/api/events.host`**——running 状态翻转**即时推送**（状态毫秒级响应）

优先级：`offline > attention > working > done > idle`。

## 二、核心优势

### 1. 离屏状态感知——不打开 DSH，也能"看见"它
独立桌面悬浮窗，置顶于所有应用之上、跨全屏可见。用户切到浏览器、IDE、文档里工作时，鲸鱼依然在桌面角落实时反映 DSH 的动态——把"任务状态"从需要主动查看的页面，变成**余光即得的实时信号**。这是桌宠区别于任何页面内组件的根本价值：**状态感知不依赖你打开了 DSH**。

### 2. 人工介入零遗漏——"需要确认"最高优先级
DSH 任务中需要人工介入的节点（权限审批、提问）最容易因离开页面而错过。桌宠为这类状态提供**最高优先级**呈现：鲸鱼瞪眼警示 + 气泡逐条列出待确认项 + 专属提示音，确保任何需要你的节点都能第一时间被发现。

### 3. 毫秒级实时性
双 WebSocket 通道（审批/提问推送 + 会话运行状态翻转推送）配合轮询兜底：会话开始/结束干活、审批/提问到达均即时呈现，状态变化毫秒级响应，无感知延迟。

### 4. 跨会话聚合，一目了然
多会话并行时，气泡按**会话粒度**逐行列出每个会话标题，数量再多也可滚动查看；状态按紧迫度统一排序（需要确认 > 工作中 > 完成待查看 > 空闲），多任务场景信息密度清晰可控。

### 5. 低打扰设计
只有状态**真正变化**时才动画/发声，同一状态下的轮询刷新保持静默——它会在你需要知道的时候提醒，而不是持续刷存在感。

### 6. 对 DSH 零侵入、纯只读
只消费 DSH 的 HTTP/WebSocket 接口，不写入任何数据、不改动任何配置；独立进程运行，卸载即消失。与任意 DSH 版本共存，无版本耦合。

### 7. 形象与行为可定制
- **HD 像素画鲸鱼**：素材由品牌参考图直接像素化生成，忠实于品牌形象
- **大小调节**：50%–110% 任意缩放（默认 67%）
- **状态音效**：审批音 / 完成音，可开关、可替换自定义音效文件（AAC）
- **气泡**：显示/隐藏随时切换
- **交互细节**：像素级点击热区（鲸鱼本体才响应）、喷水时动态间距、置顶悬浮、不占 Dock、拖拽定位

## 三、使用流程

### 1. 安装与启动
```bash
cd dsh-pet
pnpm install     # 安装依赖（Electron）
pnpm start       # 启动桌宠，鲸鱼出现在屏幕右下角
```
> 可选：`DSH_PET_URL=http://127.0.0.1:3080` 指定 DSH GUI 地址（默认 3080）。

### 2. 状态认知
启动后鲸鱼默认显示"空闲/工作中"，对照上文 5 态表格即可读取状态；气泡内会写明是哪些会话、需要什么操作。

### 3. 基本交互
| 操作 | 行为 |
|---|---|
| 单击鲸鱼/气泡 | 打开 DSH GUI（默认系统浏览器；可切换为桌宠窗口并自动直达第一个会话） |
| 按住拖拽 | 移动位置（任意停靠） |
| 右键鲸鱼/气泡本体（或托盘图标） | 菜单：打开 GUI、隐藏气泡、状态提示音开关、大小调节、打开方式、退出 |
| 滚轮（气泡内） | 多会话列表滚动查看 |

### 4. 个性化配置
- **鲸鱼大小**：放大/缩小/重置（50%–110%，右键菜单操作）
- **音效**：右键菜单开关；替换 `app/sounds/attention.m4a`、`done.m4a` 可自定义提示音（AAC 编码）
- **气泡**：可隐藏，仅保留鲸鱼表情

### 5. 状态 → 用户动作
- 看到 🔴 需要确认 → 回 GUI 处理审批/提问
- 听到完成音/看到 🎉 → 回 GUI 查看结果
- 鲸鱼睡觉 💤 → 无任务，可安心休息

## 四、待优化点

### 功能完善
1. **审批/提问的"气泡内直达处理"**：当前点击只打开 GUI，尚未在气泡内直接提供"允许/拒绝"按钮（DSH 的 `POST /api/respond` 接口已就绪，可作为下一步）
2. **浏览器深链直达会话**：DSH GUI 暂不支持 URL 深链，系统浏览器打开后停在首页（已有桌宠窗口模式可自动直达；如需浏览器直达，需给 GUI 增加深链支持）
3. **更多音效场景**：目前仅"需要确认/完成"两种音效，可扩展（工作中开始、错误、长时间无响应等）与自定义音效库
4. **会话标题长文本**：超长标题尚未做省略号截断，多会话时靠滚动查看

### 体验打磨
5. **窗口自适应内容**：鲸鱼缩小时窗口顶部留有透明空白，可改为窗口贴合内容高度
6. **开机自启 / 常驻管理**：未提供登录自启、单实例重启等便利项
7. **审批事件的更多上下文**：气泡内显示审批工具、原因等细节可进一步丰富

### 工程与发布
8. **跨平台**：当前在 macOS 验证，Windows/Linux 的透明窗口、托盘、音效等需适配测试
9. **安装体积**：依赖 Electron（约 100MB+），可评估打包瘦身（如只打包所需 Chromium 组件）
10. **素材维护**：像素素材由外部生成（参考图像素化），后续迭代需建立素材版本管理
11. **无自动更新机制**：发布后需提供更新通道或版本分发方案

## 五、发布结构（面向社区发布）

桌宠是**独立 Electron 桌面应用**，通过 HTTP/WebSocket 只读接口与 DSH 通信，不依赖 DSH 插件体系——发布时作为"桌面伴侣工具"独立分发，与 DSH 内核零耦合。

### 5.1 发布仓库结构

```
dsh-pet/                      ← 发布仓库根
├── README.md                 ← 对外首页：一句话定位 + 截图/演示 + 安装 + 使用
├── LICENSE                   ← 开源许可证（发布前补齐，建议 MIT/BSD-3-Clause）
├── CHANGELOG.md              ← 版本变更记录
├── 产品说明.md                ← 本文档（完整产品说明）
├── package.json              ← 版本号 + 启动/构建脚本
├── main.js / preload.js      ← Electron 主进程与 IPC 桥
├── app/                      ← 渲染层（HTML/CSS/JS + 像素素材 + 音效）
├── docs/                     ← 截图、演示 GIF（README 引用）
└── scripts/                  ← 自检脚本（verify_pixel_src.py 等）
```

### 5.2 发布资产清单（发布前补齐）

| 资产 | 说明 | 状态 |
|---|---|---|
| LICENSE | 开源许可证 | 待补齐 |
| 应用图标 | 鲸鱼 ICON（.icns/.png，菜单栏 + 安装包） | 待补齐 |
| 截图/演示 GIF | 5 态展示、交互演示 | 待补齐 |
| README 首页 | 定位、截图、安装、使用、常见问题 | 已有骨架，需整理 |
| 打包产物 | macOS `.dmg`/`.app`（electron-builder 或 pkg） | 待打包 |
| 版本规范 | `v0.1.0` 起步，配 CHANGELOG | 待建立 |

### 5.3 发布步骤

1. **补齐资产**：LICENSE、图标、截图、README 首页
2. **打包分发**：产出 macOS 安装包（`pnpm pack` / electron-builder），注明系统要求
3. **建仓**：公开源为 `FlytoMAYDAY80/dsh-pet`（原 `dsh-external/dsh-pet`，随 DSH 发布转个人账号公开），补好仓库描述与 Topics
4. **注册索引**：经 `hub` 收录（`catalog.json` 自动生成），分类到 **community（社区）**，tags 建议 `desktop`、`pet`、`notify`
5. **长期维护**：CHANGELOG 跟进、issue/PR 通道、更新机制评估

### 5.4 后续可选：插件化适配

若社区后续提供"桌面应用型插件"的挂载机制（如 registry 支持外部进程插件），可将桌宠窗口能力适配为插件入口，使用户通过 `dsh registry install` 一键安装。当前无此机制前，以独立应用形态发布即可。

## 六、素材定制指南（零代码）

桌宠素材全部**文件驱动**，无需改任何代码即可定制。把文件放到 `custom/` 目录，启动时自动加载并覆盖内置素材（目录内有 `README.md` 详细说明）。

### 6.1 定制音效

```
custom/attention.m4a   ← 覆盖"需要确认"音效（AAC 编码，建议 ≤1 秒）
custom/done.m4a        ← 覆盖"任务完成"音效
```

缺失时自动回退内置音效。也可直接替换 `app/sounds/` 下的同名文件。

### 6.2 定制配色（最简单）

在 `custom/` 放一个 `sprites.json`，只写 `palette` 字段即可全局换色：

```json
{
  "palette": {
    "b": "#546AF5",   // 身体主色（全鲸鱼身体）
    "B": "#2E46D0",   // 尾巴/深色
    "w": "#FFFFFF",   // 眼白
    "K": "#0F1B4D",   // 瞳孔
    "P": "#FF9EBB",   // 腮红
    "R": "#8FB0FF"    // 喷水
  }
}
```

改一个颜色值 → 重启 → 全鲸鱼对应部位变色。

### 6.3 定制图案（换形象）

`sprites.json` 的 `sprites` 字段是 6 个状态（default/working/attention/done/idle/offline）的像素网格，每个状态 58 行 × 80 字符（每字符一个像素，`.` 透明）。**推荐用脚本从参考图生成**：

```bash
# 准备一张白底参考图（如 PNG/JPG）
python3 scripts/ref_to_sprites.py <你的参考图路径>
# 自动生成 custom/sprites.json（投票降采样 + 6 状态表情）
```

也可复制 `pixel-src-hd/whale-sprites-hd.json` 手工微调网格。

### 6.4 恢复默认

删除 `custom/` 下不需要的文件即可回到内置素材。

> 完整格式说明见 `custom/README.md`；素材机制对 DSH 零侵入，仅影响桌宠自身显示。

---

*本文档随产品迭代更新。联系方式/仓库地址待补充。*