# deepseek-harness-desktop

> A whale girl pet placed in the bottom-right corner of the DSH Web interface. Its animations change based on conversation activity. Players can feed it after completing rounds to accumulate affection.

## Metadata

- Author: [@ningbainb](https://github.com/ningbainb)
- Repo: <https://github.com/ningbainb/deepseek-harness-desktop.git>
- GitHub: [ningbainb/deepseek-harness-desktop](https://github.com/ningbainb/deepseek-harness-desktop)
- Stars: 156
- Language: TypeScript
- License: [BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)
- Homepage: <https://ningbainb.github.io/deepseek-harness-desktop/>
- Topics: `ai-agent`, `ai-coding-assistant`, `codex`, `deepseek`, `deepseek-harness`, `desktop-app`, `dsh`, `dsh-plugin`, `electron`, `electron-app`, `gui`, `open-source`, `plugin-system`, `plugins`, `remote-access`, `skills`, `ssh-client`, `windows`, `windows-desktop`
- Forks: 5
- Open Issues: 6
- Last push: 2026-08-20T05:29:52.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-pet
```

## Wiki

## 一句话定位
在 DSH Web 界面右下角放一只鲸鱼娘陪伴你工作：模型思考时她在游动，完成回合可喂小鱼干让她长大，从「幼鲸」一路进阶到「深海羁绊」。

## 核心能力
- 跟随会话活动自动切换动画：模型思考时她跑动、使用工具时她向右移动、整理回复时进入复盘、完成回合时跳起庆祝、失败时定格在失败动作
- 完成回合亲密度自动 +1，4 级进阶：幼鲸（0 点）→ 伙伴（25 点）→ 挚友（50 点）→ 深海羁绊（80 点，100 点封顶）
- 点击鲸鱼娘摸头，弹出短句反馈并 +1 亲密度（10 秒冷却）
- 悬浮面板「喂食」消耗 1 条小鱼干并 +5 亲密度（30 秒冷却）
- 拖动鲸鱼娘到任意位置，松手自动保存位置
- 改名后召唤按钮自动同步为「召唤{新名字}」
- 隐藏后输入区出现「召唤{名字}」按钮，一键回归

## 技术实现
- **语言**: TypeScript（ESM，浏览器半区 + 宿主半区单包）
- **关键依赖**: `@deepseek-ai/cordis`（cordis 插件框架）、`@deepseek-ai/dsh-session`（会话事件类型）、`@deepseek-ai/dsh-host-webserver`（HTTP 路由注册）、`react`/`react-dom`（鲸鱼娘浮层渲染）
- **架构模式**: 官方 cordis bundle 形态，`dsh.bundle.patch` 在 Web 插件清单中插入 `pet` 行；宿主半区注册服务并暴露 `/api/pet/*` JSON API + `/pet/whale/*` 素材路由，浏览器半区通过 fetch 轮询 + portal 渲染全局浮层
- **入口文件**: `packages/dsh-pet/src/index.ts`（宿主半区入口）；浏览器半区入口 `packages/dsh-pet/src/client/index.ts`

## 适用场景
你希望 DSH 不只是冷冰冰的工具界面，而有一点点陪伴感。适合需要长时间盯着模型思考的工作场景（长生成、批量任务、多会话切换），既能看到当前进度（动画/气泡），又能在等待时玩一下喂食、攒亲密度、给宠物起个名字。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH 版本 | 0.1.0-rc.7+ | 依赖 `@deepseek-ai/*` peer/dev 依赖 0.1.0-rc.7 系列 |
| Node | >=22.19.0 | 包内 `engines.node` 声明 `^22.19.0 || >=24.0.0` |
| React | ^18.2.0 | peerDependencies 声明，宿主已自带 |
| 平台 | 跨平台 | 宿主半区使用 Node `fs`（`pet.json` 原子写入），浏览器半区走浏览器 Web 平台 |

## 安装方式
```bash
dsh plugin --profile web add github:ningbainb/deepseek-harness-desktop/packages/dsh-pet
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 启用宠物 | 开关 | 关闭后鲸鱼娘完全隐藏并停止轮询；可重新打开 | 开 |
| 显示宠物 | 开关 | 关闭后隐藏，可从输入区召唤按钮一键回归 | 开 |
| 大小（px） | 数字 | 精灵单元高度，范围 32–512 | 160 |
| 距右侧（px） | 数字 | 视口右边缘的水平内缩距离 | 24 |
| 距底部（px） | 数字 | 视口底边的垂直内缩距离 | 20 |
| 名字 | 文本 | 鲸鱼娘显示名，1–20 个字符 | 鲸鱼娘 |

## 常见问题
**Q: 鲸鱼娘会在所有界面出现吗？**

A: 会出现。插件把浮层挂在 `document.body` 上，跳出新对话窗口或没有任何会话时也显示，不会因为会话切换而消失。

**Q: 不点击宠物也会得到亲密度吗？**

A: 会。模型每完成一个回合亲密度自动 +1，4 级进阶：幼鲸 → 伙伴 → 挚友 → 深海羁绊（100 点封顶）。

**Q: 为什么点击宠物没有反应？**

A: 10 秒内重复点击会被冷却拒绝，宠物会显示「摸过头啦，让鲸鱼娘歇口气～」。

**Q: 喂食需要消耗什么？**

A: 每次喂食消耗 1 条小鱼干，亲密度 +5；小鱼干每完成 3 个工作回合 +1 条，每 30 分钟闲置 +1 条，上限 20 条。

**Q: 数据存在哪里？**

A: 写入 `$DSH_HOME/pet.json`（默认 `~/.dsh/pet.json`），原子写入，损坏文件下次启动会回落到默认状态。

**Q: 看不到鲸鱼娘怎么办？**

A: 首先在设置页「宠物」卡片确保「启用宠物」和「显示宠物」开关打开；其次在专业设置直接编辑 `~/.dsh/settings.yaml` 加入 `pet` 命名空间；最后可重启 `dsh web` 重载插件。

**Q: 拖动位置会被保存吗？**

A: 会。松手后位置通过设置通道持久化，下次打开仍在原处。

**Q: 能换名字吗？**

A: 悬浮面板点「改名」输入 1–20 个字符的新名字，会同步到召唤按钮文案和持久化文件。

## 上手难度
入门 — 仅需一条安装命令即可在 Web 界面右下角看到鲸鱼娘；进阶用法（改名、设置布局、修改持久化）走设置页或编辑 `~/.dsh/pet.json`，无需编程。

## 已知问题与限制
- 浏览器半区使用 2 秒一次的轮询从宿主拉取状态；如果宿主进程刚启动或断连，鲸鱼娘会短暂显示「鲸鱼娘迷路了（连接失败）」，下次轮询恢复后会自愈
- 宿主仅写出 5 个 API 端点和 2 个素材端点（`spritesheet.webp` + `pet.json`），自定义动效需替换 `assets/whale/spritesheet.webp` 后同步更新 `pet.json` 的 `frames` 字段与 `src/client/spritesheet.ts` 的 `TRACKS` 帧时长
- 旧版 `activity/status` 事件作为兼容输入仍被监听，但 5 秒内重复的旧式 done 不会重复发放回合奖励（避免旧+新两路事件叠加双计）
- 设置命名空间未在 `dsh-host-apiproxy` 的 `WEB_SETTINGS_NAMESPACES` 白名单中时，设置页会显示「未暴露」提示；可手动编辑 `~/.dsh/settings.yaml` 或找运维把 `pet` 加入白名单
- 旧版资源经历 issue #48（用 session-scoped slot 挂载导致新对话界面看不到宠物），当前实现已切到 `document.body` 全局 React root

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [deepseek-harness-desktop](https://deepseek-plugin.org/plugins/ningbainb/deepseek-harness-desktop/packages/dsh-pet)
Wiki generated by AI (model: `MiniMax-M3`)