精灵桌宠 Luv061211/dsh-pet

🐾 dsh-pet — 适用于 DeepSeek Harness 的可自定义桌宠

项目插图，展示鲸鱼、猫和机器人作为自定义宠物示例

DeepSeek Harness 的可自定义桌宠系统。 导入自己的精灵图角色和动画定义，让宠物随 Agent 活动变化；它既能在 DSH 设置页中管理，也能在支持的 Electron 桌面壳中显示为透明、可拖拽的 companion 窗口。

内置的 DeepSeek Whale（小鲸鱼） 和可复制的社区示例 Nailong 都只是示例宠物，不是系统边界。dsh-pet 保存宠物、尺寸和显示状态，校验本地宠物包，并将同一份宠物目录提供给 Web、桌面 companion 和可选终端宿主。

你可以做什么

- 使用自己的角色：导入带 pet.json 与 WebP 精灵图的本地宠物包，而不是只能使用内置鲸鱼。
- 感知 Agent 状态：宠物显示来自 DSH 会话投影的 ready、running、waiting 和 blocked 等人类可见状态。
- 在 Web 或桌面中使用：设置页管理选择、尺寸、唤醒和刷新；支持的 Electron 壳还能打开透明桌面 companion。
- 安全地管理本地资源：宿主校验清单、路径、图片几何和资源限制；宠物资源与偏好只留在本地。
- 不增加模型成本：宠物是展示功能，不会加入模型输入、工具定义或 KV cache。

安装

需要 Node.js ^22.19.0 或 >=24，以及 npm 已发布的 DeepSeek Harness 0.1.1-rc.2。普通用户只需要安装一个 bundle：

npm install --global @deepseek-ai/dsh@0.1.1-rc.2
dsh plugin --profile web add @luv1211/dsh-pet-desktop@0.1.1-rc.3
dsh web

启动后打开 设置 → Pet，选择或唤醒宠物。@luv1211/dsh-pet-desktop 会按正确顺序组合其余运行时组件；普通用户不需要分别安装内部包。

若系统提示找不到 dsh，关闭并重新打开终端后再试。也可以不进行全局安装：

npm exec --yes --package=@deepseek-ai/dsh@0.1.1-rc.2 -- dsh plugin --profile web add @luv1211/dsh-pet-desktop@0.1.1-rc.3
npm exec --yes --package=@deepseek-ai/dsh@0.1.1-rc.2 -- dsh web

创建自己的宠物

一个宠物包就是包含 pet.json 与其引用 WebP 精灵图的本地目录。精灵图使用 192×208 像素单元、8 列网格，并支持标准 9 行或 v2 11 行 atlas。通过设置页刷新或原生导入功能发现宠物包；不合格的资源不会发布到目录中。

从 宠物包入门 开始，查看最小清单、文件布局，以及 DeepSeek Whale 与 Nailong 两个示例。

想分享自己的角色、请求功能、报告兼容性问题或帮助改进文档，请阅读 贡献指南 与 社区宠物页。

项目组成

| 使用场景 | 包或目录 | 职责 |
| 一键安装入口 | @luv1211/dsh-pet-desktop | Bundle，按顺序组合宠物服务、命令和 Web UI |
| 宠物系统 | @luv1211/dsh-pet | 偏好、已校验目录、活动读模型和同源 API |
| 自定义包格式 | @luv1211/dsh-pet-compat | 精灵图、动画和兼容值 |
| DSH 控制界面 | @luv1211/dsh-client-ui-pet | 设置、选择、刷新、导入和 /pet 命令展示 |
| 桌面 companion | @luv1211/dsh-desktop-companion 与 desktop/ | 注册并承载可拖拽透明窗口 |
| 终端宿主 | @luv1211/dsh-pet-tui | 可选的 Kitty/Sixel 与文本回退呈现 |

兼容性与限制

- 本版本面向 npm 已发布的 DeepSeek Harness 0.1.1-rc.2；上游 0.1.2-alpha.1 不是本版本的兼容目标。
- 透明置顶桌面窗口需要带 companion bridge 的 Electron 壳；浏览器会保留宠物选择、活动和唤醒控制，但不会创建系统窗口。
- 外部文件系统改动不会自动监视。目录会在启动、导入、替换或设置页刷新时更新。

完整的发布修复与验证范围见 0.1.1-rc.3 更新说明。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm release:verify

一个可定制的 DeepSeek Harness 桌面宠物系统。 自带基于精灵图的角色和动画元数据，让它反映智能体活动，并通过 DSH Web UI 或（在可用时）一个透明可拖拽的 Electron 伴侣窗口进行管理。

内置的 DeepSeek Whale 和可复制的社区示例 Nailong 是示例宠物，而非该系统的极限。dsh-pet 会持久化宠物选择、大小和可见性；验证本地宠物包；并将同一目录提供给 Web、桌面伴侣和可选的终端宿主。

你可以做什么

- 使用你自己的角色 —— 导入带有 pet.json 和 WebP 精灵图集的本地宠物包，而不局限于内置的鲸鱼。
- 反映智能体活动 —— 宠物根据 DSH 会话投影渲染面向用户的就绪、运行、等待和阻塞活动。
- 使用 Web 或桌面呈现 —— 在设置中管理选择、大小、唤醒状态和刷新；受支持的 Electron 外壳可以打开一个透明桌面伴侣。
- 确保本地资产安全 —— 宿主会验证清单、路径、图像几何和资源限制；宠物资产和偏好设置保留在本地。
- 不增加模型成本 —— 宠物仅用于呈现，不贡献任何模型输入、工具定义或 KV 缓存状态。

安装

需要 Node.js ^22.19.0 或 >=24，以及 npm 发布的 DeepSeek Harness 0.1.1-rc.2。大多数用户安装一个捆绑包：

npm install --global @deepseek-ai/dsh@0.1.1-rc.2
dsh plugin --profile web add @luv1211/dsh-pet-desktop@0.1.1-rc.3
dsh web

启动后打开 设置 → 宠物 以选择或唤醒宠物。@luv1211/dsh-pet-desktop 会按所需顺序安装并组合其余运行时包；最终用户无需单独安装这些内部包。

创建你自己的宠物

宠物包是一个本地目录，包含 pet.json 及其指定的 WebP 图集。图集使用 8 列网格中的 192×208 像素单元格；系统接受标准的 9 行图集和 v2 的 11 行图集。设置页面可以刷新目录，原生宿主可以提供导入功能；无效资源永远不会进入已发布的目录。

从 创建宠物包 开始，了解最小清单、目录布局，以及 DeepSeek Whale 和 Nailong 示例。

要分享角色、请求功能、报告兼容性结果或改进文档，请阅读 贡献指南 和 社区宠物。

项目地图

| 使用场景 | 包或目录 | 职责 |
| 一键安装 | @luv1211/dsh-pet-desktop | 按顺序组合宠物服务、命令和 Web UI 的捆绑包 |
| 宠物系统 | @luv1211/dsh-pet | 偏好设置、经过验证的宠物目录、活动读取模型和同源 API |
| 自定义包格式 | @luv1211/dsh-pet-compat | 精灵图、动画和兼容性值 |
| DSH 控件 | @luv1211/dsh-client-ui-pet | 设置、选择、刷新、导入和 /pet 命令展示 |
| 桌面伴侣 | @luv1211/dsh-desktop-companion 和 desktop/ | 注册并承载可拖拽的透明窗口 |
| 终端宿主 | @luv1211/dsh-pet-tui | 可选的 Kitty/Sixel 输出，并带有文本回退方案 |

兼容性与限制

- 此版本面向 npm 发布的 DeepSeek Harness 0.1.1-rc.2；上游 0.1.2-alpha.1 不是此版本的兼容目标。
- 置顶透明窗口需要带有伴侣桥接的 Electron shell。浏览器会话保留目录、活动和唤醒控件，但不会创建系统窗口。
- 不会监视外部目录更改。目录会在启动时、导入或替换后，或从设置页面刷新。

阅读 0.1.1-rc.3 发布说明 了解修复范围和验证覆盖情况。

开发

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm release:verify

许可证

MIT — DeepSeek Harness 的衍生作品。