# deepseek-pet

> 为 DeepSeek Harness Web 注入 Live2D 风格的桌宠伴侣：跟随任务状态、上下文占用、活跃会话切换表情与气泡，支持拖动缩放和动作组配置。

## Metadata

- Author: [@keleus](https://github.com/keleus)
- Repo: <https://github.com/keleus/deepseek-pet.git>
- GitHub: [keleus/deepseek-pet](https://github.com/keleus/deepseek-pet)
- Stars: 34
- Language: JavaScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `deepseek-harness`, `deepseek-harness-plugin`, `dsh-plugin`
- Forks: 4
- Open Issues: 1
- Last push: 2026-08-21T02:37:11.000Z
- Added: 2026-08-19T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:keleus/deepseek-pet
```

## Wiki

## 一句话定位
为 DeepSeek Harness Web 注入一只 Live2D 风格的桌宠角色：它跟随当前任务、工具调用、上下文占用、并发会话和挂机时长自动切换表情与气泡，支持拖动缩放和"动作图片"自定义。

## 核心能力
- 在网页右下角渲染完整的角色图（不拆部件，避免表情错位），思考、回答、编码、网络搜索、子代理、完成和失败等场景切换对应表情
- 角色头顶等宽气泡轮播状态短句，并以单行横向打字机效果同步最新回复/思考输出；空闲无活动时气泡 10 秒后自动隐藏
- 角色下方展示聚焦会话（含亮边标记）和最多 7 个并发执行会话，超过 3 个会自动层叠收起，超过 7 个显示"+N 个会话"
- 上下文达到 62% 时切换到"还可以再吃一点"（干饭组图），82% 时切到"上下文吃饱了"；发图片输入时切到"看不见"蒙眼状态
- 根据本地时间显示早 / 中 / 下午 / 晚上问候；空闲 10 分钟显示"肚子饿了"，30 分钟"抱着枕头犯困"，1 小时"已经睡着了"
- 拖动角色改位置、悬停滚轮缩放（65%~140%）、单击触发状态短句、双击或"−"按钮最小化为右下角静止图标；位置和尺寸会自动记住
- 设置面板新增"桌宠设置"页：可切换"默认"和"页面置顶"两种展示模式，可按动作组勾选启用 / 停用具体图片，每组至少保留一张
- 遵循 `prefers-reduced-motion` 与窄屏断点（≤760px），所有动画可在系统偏好下被显著弱化

## 技术实现
- **语言**: JavaScript / JSX（React 18）
- **关键依赖**: React 18（peerDependency，宿主注入）、esbuild 0.25.8（仅构建期）；运行时依赖仅为宿主提供的 cordis / dsh-client-runtime / dsh-client-ui-layout / dsh-client-ui-slots
- **架构模式**: 双半区 cordis bundle：`src/host/index.js` 是空 host 半区（`apply()` 无副作用），所有可见行为在 `src/client/index.jsx` 的 browser 半区：通过 `ctx.slots.inject('shell.overlay', …)` 注册桌宠组件（order=90）+ 通过 `ctx.slots.inject('settings.section', …)` 注册设置页；订阅 `slots` 和 `sessions` 两个运行时能力
- **入口文件**: 客户端入口 `src/client/index.jsx`，核心组件 `src/client/DeepSeekPet.jsx`，设置页 `src/client/DeepSeekPetSettings.jsx`；构建产物 `lib/index.js`（host 半区）+ `lib/client.js`（client 半区，约 1.5 MB，内嵌全部 base64 WebP 图片）
- **资源管线**: `scripts/build_assets.py`（Python 3 + Pillow 处理源图 → 透明 WebP）+ `scripts/embed-assets.mjs`（把 WebP 转 base64 写回 `src/client/assets.generated.js`，再由 esbuild 打进 `lib/client.js`）；不依赖任何网络资源

## 适用场景
- 长时间跑模型任务（多轮推理、长代码生成、批量工具调用）时希望有个陪伴感反馈、不再盯着进度条发呆的用户；
- 同时管理多个并发会话（>3 个）的用户，需要直观看到哪个在跑、哪个等交互、哪个聚焦；
- 关注无障碍体验、需要 `prefers-reduced-motion` 自动降级动画的桌面用户。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH 宿主 | 未在 `dsh.engines` 声明 | peerDependencies 全部为 `*`，实际由 `dsh.client.inject` 强约束需注入 `@deepseek-ai/dsh-client-runtime` 与 `@deepseek-ai/dsh-client-ui-layout` |
| Node.js | `>=22.19` | package.json `engines.node`；用户运行时无需 Node，仅从源码构建时需要 |
| 平台 | 仅 Web 浏览器 | `dsh.client.platform: "web"`；host 半区为空壳，不参与后端逻辑 |
| 原生模块 | 无 | 纯 React 18 + 嵌入 WebP，无 node-pty / sqlite 等 native 依赖 |
| React | `^18.2.0` | peerDependency，由 DSH Web 宿主注入 |
| Python 3 + Pillow | （仅自构建） | 修改源图后需重跑 `npm run assets`，发布版本已嵌入图片无需此步骤 |

## 安装方式
```bash
dsh plugin --profile web add github:keleus/deepseek-pet
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 展示模式 | 下拉（默认 / 页面置顶） | 控制桌宠在页面里的层级：默认跟随应用界面层；页面置顶固定在视口右下角并悬浮在所有内容（含弹窗）之上 | 默认 |
| 动作图片 · 待机 | 多选（默认待机 / 放松 / 开心 / 得意） | 无任务时按累计时长稳定轮换的图片池，每组至少保留一张 | 全选 |
| 动作图片 · 思考 | 多选（认真思考 / 桌前工作 / 从容思考 / 有点困惑 / 压力思考 / 认真扒饭 / 举起饭碗） | 分析、推理和疑问较多时使用 | 全选 |
| 动作图片 · 执行工具 | 多选（桌前编码 / 检查内容 / 认真核对 / 认真扒饭 / 举起饭碗） | 写代码、读文件、搜索和运行工具时与白米饭动作交替 | 全选 |
| 动作图片 · 回复 | 多选（敲字回复 / 整理答案 / 核对回答） | 组织和输出回答时使用 | 全选 |
| 动作图片 · 任务成功 | 多选（开心完成 / 满意收工 / 桌前完成） | 会话成功结束后短暂展示 | 开心完成 + 满意收工 |
| 动作图片 · 等待交互 | 多选（耐心等待 / 继续等待 / 边想边等 / 等得生气 / 等困了） | 等待确认或回答时，随等待时间变化 | 全选 |
| 动作图片 · 错误与道歉 | 多选（震惊 / 道歉 / 难过 / 桌前扶额） | 工具失败、任务失败或收到纠正时使用 | 全选 |
| 动作图片 · 干饭 | 多选（举起饭碗 / 认真扒饭） | 上下文增长到需要"补充能量"时使用 | 全选 |

> 桌宠的位置、缩放、最后活动时间等运行时状态自动写入浏览器 localStorage，无需手动配置；以上"配置项"均通过 DSH 设置面板的"桌宠设置"页修改。

## 常见问题

**Q: 桌宠会影响页面性能吗？**

A: 影响很小。所有 28 个表情图 + 3 个帧图以 base64 WebP 直接嵌入 `lib/client.js`（约 1.5 MB），加载后无外部网络请求；运行时只渲染当前激活的那张图片（其他 `opacity:0`），DOM 始终在但开销可忽略。浏览器 DevTools 里能看到一长串 `<img>` 但实际绘制很轻。

**Q: 能不能换一只完全不同的角色形象？**

A: 不能直接换。本插件的 28 个完整角色图（不拆部件）与状态映射在 `src/client/assets/`、`src/client/pet-state.js`、`src/client/pet-presentation.js` 里硬绑定，源码里没有"换肤"或"加载外部 pet.json"的入口；如需自定义形象需 fork 仓库替换源图后自行构建并本地安装。

**Q: 我发的图片桌宠为什么说"看不见"？**

A: 不是 bug。DeepSeek 模型本身不支持视觉输入，所以插件检测到最近一次人类输入含有图片附件时，主动把桌宠切到"蒙眼"表情并显示"图片暂时看不见"，作为给用户的视觉提示。`src/client/pet-state.js:81-91` 是源头。

**Q: 设置里的"页面置顶"会打开新窗口吗？**

A: 不会。两种展示模式都是纯页面内呈现：默认在 DSH 的 shell 界面层渲染，页面置顶则通过 React `createPortal` 把桌宠挂到 `document.body` 并用 `position:fixed` 定位到视口右下角。无论哪种模式都不会 `window.open`，所有浏览器表现一致。`src/client/DeepSeekPet.jsx:482-486` + `src/client/styles.js:29`。

**Q: 多会话并行时桌宠会不会乱？**

A: 不会。聚焦会话用亮边横条标记，正在执行的会话向下排列；超过 3 个并发执行会话时进入"忙疯了"状态并在"工作"和"白米饭"两组图片之间交替；超过 7 个时下方会话列表底部显示"还有 N 个会话"摘要。

**Q: 怎么禁用某张表情图（比如不想看到"哭脸"）？**

A: 打开 DSH 设置面板 → "桌宠设置" → 滚到"动作图片"区，在对应动作组里取消勾选即可，每组至少保留一张；点"恢复默认"可一键还原所有动作组的图片池。

**Q: 卸载插件后我的偏好还在吗？**

A: localStorage 里的偏好（位置、缩放、最后活动、展示模式、动作图片启用集合）不会随插件卸载被清，重装后可立即接上；但因为这些键以 `deepseek-pet:` 为前缀，如果之后没有任何 deepseek-pet 相关代码运行，它们就只是孤立键，不会影响其他功能。

## 上手难度
入门 — 安装即用，设置面板里只有展示模式 + 动作图片勾选两组可见选项；所有运行时状态（位置 / 尺寸 / 滚动文案）都是默认开箱即用，无需阅读文档。

## 已知问题与限制
- 检测到图片输入时强制显示"图片暂时看不见"蒙眼状态（DeepSeek 模型本身不支持视觉输入，并非插件 bug）
- runningSessions 下方面板仅渲染前 7 个并发执行会话，超出部分以"+N 个会话"折叠摘要；超过 3 个时自动层叠收起但不影响总数计数
- 自定义角色形象需要 fork 仓库替换 `src/client/assets/` 下的源图后自行构建，运行时没有"加载外部 pet.json"或皮肤切换入口
- 重新构建需要 Python 3 + Pillow（`npm run assets`），不是纯 npm 工作流；发布版本已嵌入图片，普通用户无需此步骤
- 图片资源全部以 base64 WebP 嵌入 `lib/client.js`，单文件约 1.5 MB，首次加载会比普通插件略慢，但加载后无外部图片请求

---

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