# dsh-pet

[English](README.md) | 中文

面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的社区 DeepSeek Pet 插件。它让 DeepSeek 小鲸鱼固定显示在 Web 视口中原地游泳，跟随当前会话生命周期，并展开紧凑的 API 统计面板。

![DeepSeek Pet 在 DSH Web 应用中展开会话统计](docs/assets/deepseek-pet-intro.png)

![DeepSeek Snake 在 DSH Web 应用中的小游戏界面](docs/assets/deepseek-pet-snake.png)

## 提供的能力

- 固定在视口中的 overlay 和原地游泳鲸鱼；使用帧大小的 atlas 视口逐帧切换，并加入 1px 垂直起伏，不会水平移动或旋转。
- 当前会话的待机、运行、等待、失败和完成状态，并提供英文与简体中文词典。
- 点击打开面板，显示当前聊天标题、最近一次 provider／model 身份，以及 `sessionStats`、`tokenUsage` 和 `contextPressure` projection 提供的 API 统计。
- 主指针拖动、抓取点跟随、8px 视口边距、浏览器本地位置持久化和视口约束。
- 展开面板会选择空间更大的一侧，与所有视口边缘碰撞；视口高度不足时只在卡片内部滚动。
- 根级 overlay 在没有当前会话时仍保持显示；会话数据通过桥接进入全局宠物，不会为每个会话重复渲染一只鲸鱼。
- Host 命令 `/pet` 和 `/pet-game`：可以从 DSH 正常命令输入中切换全局宠物和小游戏。
- 宠物主题的贪吃蛇小游戏：小鲸鱼作为蛇头，得分方块使用多彩玻璃高亮；支持方向键／WASD、空格、连续按两次空格、Escape 和重新开始。每局打开后先倒计时 3 秒再自动开始，并保存浏览器本地个人最佳分数，且只在结算时写入。10 分以内优先把得分方块放在中心 8×8 区域，之后在棋盘内广泛随机并降低最外圈偏置。游戏以贴着宠物的非模态毛玻璃悬浮卡片呈现，移动间隔从 240ms 起步，分数越高越平滑地加速，并与视口边缘碰撞。
- 使用 Codex v2 8×11 sprite atlas，并将 WebP 资源内嵌到 client bundle。

## 集成状态

本仓库是 Web 客户端包 `@deepseek-ai/dsh-client-ui-pet` 的源码发布。该包向 DSH Web composition 提供浏览器 entry；它目前还不是独立的 `dsh.bundle`。

当前构建和测试依赖匹配的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) checkout，因为本包使用 DSH workspace 依赖和 TypeScript project references。在该 checkout 中，将本目录放到 `packages/client/ui-pet`，保留下面的 Web patch 行，并从 monorepo 根目录运行聚焦检查：

```yaml
- id: ui-pet
  name: '@deepseek-ai/dsh-client-ui-pet'
```

```sh
rsync -a --exclude .git --exclude lib --exclude node_modules /path/to/dsh-pet/ packages/client/ui-pet/
pnpm install
pnpm exec vitest run packages/client/ui-pet/tests
pnpm exec tsc -p packages/client/ui-pet/tsconfig.json --noEmit
pnpm --filter @deepseek-ai/dsh-client-ui-pet bundle
```

直接执行 `dsh plugin --profile <name> add github:Vulcan626/dsh-pet` 激活被有意暂缓。本包没有声明 `dsh.bundle`，当前 `workspace:^` 引用也不是 Git 安装所需的自包含依赖。官方 DSH [插件发布指南](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/develop/basic/publish.md) 说明了公开 Git 包在支持这种安装方式前需要自包含的 `prepare` 构建或预构建产物。

## 运行时和统计

宠物通过 runtime 标准 hooks 读取选中的会话，并把可视 overlay 保持在 root scope。存在对应 projection 时优先使用 durable whole-log 计数和 provider 计费桶；没有 projection 的 fixture 或部署会把可见 conversation window 折叠成展示回退，不发起 RPC，也不创建第二份用量账本。

缓存命中率为 `cacheReadTokens / (uncachedInputTokens + cacheReadTokens + cacheWriteTokens)`。上下文占用使用 `projectedTokens`，缺失时回退到 `pressureTokens`。插件不会发送模型请求，也不会增加模型可见内容。

## 命令与小游戏

`/pet` 切换浏览器级 overlay；`/pet-game` 切换贴着宠物的贪吃蛇悬浮卡片，开启时会自动唤醒宠物。统计面板中的「开始小游戏」按钮也可以打开它。每局打开后先倒计时 3 秒再自动开始；空格暂停／继续，连续按两次空格重开。游戏从 240ms 移动间隔开始，并随分数按温和指数曲线提升；10 分以内的得分方块偏向中心区域，之后广泛随机并降低边缘集中。多彩玻璃得分方块和游戏卡片会跟随宠物并与视口边缘碰撞，不会覆盖整个工作区。正在进行的棋盘只保存在当前浏览器内存，页面隐藏时会暂停；个人最佳会跨刷新保留，只在最后结算时写入，不会在标签页之间同步，也不会进入模型上下文。

## 开发说明

源码由宿主插件和 `src/client/` 下的浏览器 entry 组成。聚焦 React 和纯规则测试覆盖状态推导、统计折叠、用量计算、sprite 选择、拖动、视口约束、面板边缘碰撞、命令控制、倒计时、连续空格重开、个人最佳存储、彩色得分方块、分数分段落点、结算时更新和 Snake 移动。生成的 `lib/`、`node_modules/`、临时文件、环境文件和 macOS 元数据均被排除在仓库之外。

## 官方生态建议

上游[贡献指南](https://github.com/deepseek-ai/deepseek-harness/blob/master/CONTRIBUTING.zh.md) 当前建议社区通过共享插件、指南、博客和答疑参与生态建设，同时官方仓库暂不接受外部 pull request。发布相关包时添加 `dsh-plugin` topic，方便其他 DSH 用户发现。

## Release note 和 TODO

- [CHANGELOG.md](CHANGELOG.md) 记录当前公开源码版本。
- [TODO.md](TODO.md) 列出后续打包、安装、无障碍和统计能力里程碑。

## 许可证

MIT，见 [LICENSE](LICENSE)。