# @deepseekstudio/dsh-deepseek-pet 中文文档

规范地址：https://npmcn.com/package/%40deepseekstudio/dsh-deepseek-pet/

版本：0\.2\.14
npm 元数据更新时间：2026-10-07T09:29:08.789Z
中文译文更新时间：2026-11-13T05:15:35.478Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deepseekstudio/dsh-deepseek-pet
原文对照：https://npmcn.com/package/%40deepseekstudio/dsh-deepseek-pet/?lang=original
项目主页：https://github.com/Yoshino-JF/dsh-deepseek-pet#readme
源码仓库：https://github.com/Yoshino-JF/dsh-deepseek-pet

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：31.9 MB，73 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/dsh-tools \*
- 首次发布：2026-10-04T17:03:21.495Z
- 最新版本发布：2026-10-07T09:29:08.400Z
- 近 30 天下载量：2226（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

DeepSeek 桌宠：把「DSH 账户余额 + 蓝鲸女仆桌宠」连起来。宿主端查询余额、通过 127.0.0.1 回环接口喂给桌面悬浮窗，并提供 pet\_balance / pet\_control 两个模型工具。

## 安装

```sh
npm install @deepseekstudio/dsh-deepseek-pet
```

也可以使用：`pnpm add @deepseekstudio/dsh-deepseek-pet`、`yarn add @deepseekstudio/dsh-deepseek-pet`、`bun add @deepseekstudio/dsh-deepseek-pet`

## README

# DeepSeek 桌宠 · DSH 插件（宿主端）

把 DeepSeek 账户余额喂给桌面上的蓝鲸女仆桌宠，并提供两个模型工具。

-   **桌宠本体**：`D:\DeepSeek\deepseek-pet`（独立原生程序，WPF 透明置顶窗）
-   **本插件**：只做三件事 —— 用 DSH 凭据查余额、在 `127.0.0.1` 上开一个只读状态接口、起停桌宠进程

```
DSH 宿主插件  ──HTTP(127.0.0.1:47831/state)──▶  桌宠窗口
   │ 持 DEEPSEEK_API_KEY                         │ 只拿到余额数字
   └─ ctx.credentials.resolve()                  └─ 每 5 秒取一次
```

## 安装

```
plugin_manager install_bundle  D:\DeepSeek\deepseek-pet-plugin
```

首次安装即为新 bundle，**热生效**；此后修改 `index.js` 再装会返回 `restart-required`（同包替换需要重启 DSH 才会加载新的 JS 世代）。

## 配置（profile 的 `cordis.patch.yml` → `dsh-pet` 行）

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| `port` | `47831` | 状态接口端口，只监听 `127.0.0.1` |
| `petPath` | `D:\DeepSeek\deepseek-pet\build\DeepSeekPet.exe` | 桌宠程序路径 |
| `credential` | `DEEPSEEK_API_KEY` | 用哪条 DSH 凭据查余额（不写死密钥） |
| `apiBase` | `https://api.deepseek.com` | 余额接口前缀 |
| `refreshSeconds` | `60` | 缓存/刷新周期（秒） |
| `lowBalance` | `10` | 低于该值桌宠切「担心」表情、徽章变红 |
| `autoStart` | `true` | 宿主启动 3 秒后自动叫起桌宠 |
| `startDelayMs` | `3000` | 自动启动延迟，避开宿主 boot 期 |
| `stopOnUnload` | `false` | 卸载插件时是否顺手关掉桌宠（默认留着） |

## 桌宠版本与新增功能

当前包内桌宠本体为 **v0.2.12**（`pet/DeepSeekPet.exe`）。近几版新增的可见功能：

| 版本 | 新增 |
| --- | --- |
| 0.2.12 | 右键「**游戏屏大小**」五档 + 悬停屏上滚轮无级调（50%–200%）；屏到她之间的距离与投影光柱随屏等比；新增「**过渡速度**」五档（默认 320ms）；余额徽章与对话框自适应不再被裁 |
| 0.2.11 | 帧率跟屏刷新（原来是 9/20 FPS）；新增「**性能档位**」（自动 / 30 / 60 / 120） |

逐版细节见 `pet-src/DEVLOG.md`，本版发布说明见 `RELEASE-NOTES-v0.2.12.md`。

## 长轮询与「干活事件」（v0.0.2）

-   桌宠用 `GET /state?wait=25` 长轮询：插件把请求挂起最多 25 秒，**有事件立刻返回**（实测反应 < 100ms），没有事件则超时返回一次心跳。
-   插件监听两个宿主事件来判断"用户主动开始干活"： `agent/inbox/inserted`（用户消息进入 inbox）→ 10 秒内 `agent/status` 变为 `running`。 自动续跑 / 子代理 / 定时任务没有这条用户消息，因此**不会**触发桌宠的"被吓一跳"演出。
-   事件类型：`work-start`、`work-end`、`balance`（余额变化）、`message`（留言）、`quit`（软退出）。

## 开发与验收：不重启 DSH 也能测

插件改了 JS 之后，同包替换要重启 DSH 才生效。`dev-mock-server.mjs` 用**完全相同的协议**顶替插件：

```bat
node dev-mock-server.mjs 47835
DeepSeekPet.exe --url http://127.0.0.1:47835/state --screen on

curl "http://127.0.0.1:47835/dev/event?kind=work-start"   :: 模拟"用户开始干活"→ 桌宠被吓一跳
curl "http://127.0.0.1:47835/dev/event?kind=work-end"
curl "http://127.0.0.1:47835/say?text=hello"
```

## 工具

| 工具 | 参数 | 作用 |
| --- | --- | --- |
| `pet_balance` | `fresh?` | 读余额；`fresh=true` 跳过 60 秒缓存 |
| `pet_control` | `action`（start/stop/status/refresh/say/hide/show）、`text?` | 起停桌宠、立即刷新、让桌宠弹一句话 |

## 接口

| 路径 | 说明 |
| --- | --- |
| `GET /health` | `{ok:true}` |
| `GET /state?pid=<桌宠pid>` | 桌宠拉取的状态（余额+留言），**先回缓存再后台补数据** |
| `GET /say?text=...` | 让桌宠说一句话（也可以由别的脚本调用） |
| `GET /refresh` | 触发一次强制刷新 |

## 安全

-   API Key 只在宿主进程内使用，**不进日志、不下发**；桌宠只收到余额数字与货币。
-   状态接口只监听回环地址，且是只读的（`/say`、`/refresh` 也只影响桌宠显示）。

## 常见问题

### @deepseekstudio/dsh-deepseek-pet 是什么？

DeepSeek 桌宠：把「DSH 账户余额 \+ 蓝鲸女仆桌宠」连起来。宿主端查询余额、通过 127\.0\.0\.1 回环接口喂给桌面悬浮窗，并提供 pet\_balance / pet\_control 两个模型工具。

### 如何安装 @deepseekstudio/dsh-deepseek-pet？

在项目目录运行 npm install @deepseekstudio/dsh-deepseek-pet，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/dsh-tools（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @deepseekstudio/dsh-deepseek-pet 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/deepseekstudio\_\_dsh-deepseek-pet 是否存在。

### @deepseekstudio/dsh-deepseek-pet 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @deepseekstudio/dsh-deepseek-pet 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @deepseekstudio/dsh-deepseek-pet 可以商用吗？

@deepseekstudio/dsh-deepseek-pet 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @deepseekstudio/dsh-deepseek-pet 的下载量有多少？

根据 npm 官方下载统计，@deepseekstudio/dsh-deepseek-pet 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,226 次，日均约 74 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deepseekstudio/dsh-deepseek-pet 还在维护吗？

最新版本 0\.2\.14 发布于 2026/10/07（1 个月前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/10/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。