dsh-pet-remielle

一句话定位

在 DSH（DeepSeek Harness）网页里养一只蕾米埃尔（Remielle）动画桌宠，它会实时跟随你的会话阶段切换贴纸、显示状态气泡；可选地把桌宠"请"出网页，飘在 Windows 桌面最上层作为透明置顶悬浮窗。

核心能力

• 跟随 DSH 真实会话事件切换贴纸：思考、输出、调用工具、等待确认、出错等阶段对应不同的 GIF 动画
• 在桌宠上方显示状态气泡，包含项目名、阶段、待办进度（已完成 x/y）
• 多 Session 同时运行时按"等待确认 > 错误 > 工作 > 思考 > 空闲"优先级展示最需要关注的会话
• 内置多宠物注册表，可启用 / 禁用 / 重命名 / 切换当前展示的桌宠形象
• 通过 SSE 实时推送状态，断线自动重连，必要时轮询兜底
• 可选的桌面悬浮窗（Windows x64）：Electron 透明置顶窗口，双击画画的作品图弹在屏幕右上角独立小窗
• 插件内置版本检查与一键更新，跨 CN 网络有 HTTP 代理回退
• 设置页提供多标签页（外观 / 行为 / 桌面悬浮 / 更新 / 反馈）

技术实现

• 语言: JavaScript（Node ESM，浏览器端也是 JS）
• 关键依赖: @deepseek-ai/schemastery（设置配置 schema）、@deepseek-ai/cordis（DSH 插件宿主）、@deepseek-ai/dsh-client-ui-settings-plugins（客户端 UI 注入点）
• 架构模式: Cordis 插件宿主，监听 session/event + session/disposed 全局事件总线，经纯函数 PetReducer 归约成结构化消息，再通过 webServer 的 loopback HTTP 端点（/config /state /stream /pets /assets /pet-view /desktop /check /update /info）暴露给浏览器端；客户端代码通过构建脚本注入版本号后打包成 lib/client.js
• 入口文件: src/index.js（宿主端，导出 name / apply / Config）；浏览器端入口为构建产物 lib/client.js

适用场景

DSH 长时间跑任务时，想不盯着网页也能感知到进展 —— 看一眼屏幕角落的桌宠贴纸就知道 AI 是还在想、卡住了、还是要你确认。同时给 DSH 网页/桌面增加一点陪伴感，适合喜欢赛璐璐/二次元风格桌宠、又不想装独立桌面宠物软件的用户。

前置依赖与兼容性

安装方式

dsh plugin --profile web add dsh-pet-remielle

配置项

常见问题

Q: 安装后桌宠不显示怎么办？

A: 默认就是启用状态。如果设置里把"启用桌宠"关掉了，重新打开即可；或在 DSH 网页右上角的设置 → 蕾米埃尔桌宠中重新勾选启用。

Q: 桌面悬浮窗和页面内桌宠有什么区别？

A: 桌面悬浮窗是独立的透明置顶窗口（仅 Windows x64，需 Electron 运行时），双击画画的"作品图"会弹在屏幕右上角独立小窗；页面内桌宠则是嵌在 DSH 网页里，跨平台可用。

Q: 桌面悬浮模式第一次开启会下载什么？

A: 会下载约 200MB 的 Electron 运行时（仅 win32-x64），下载前会弹出确认提示；下载失败会自动回落到页面内展示，不影响其他功能。

Q: 子 Agent 的状态也会被桌宠反映吗？

A: 默认不反映。需要在设置里勾选"允许子 Agent 抢占宠物状态"（includeSubagents）才会把子 Agent 纳入状态汇总。

Q: 旧版本为什么不能直接更新？

A: 0.3.0 之前的包名发生过变更（0.2.0 之前是 @dsh-external/dsh-client-ui-pet-remielle，0.2.0–0.3.0 是 dsh-pet-remielle），直接覆盖升级会触发加载报错；需要先卸载旧版再装新版。

Q: 怎么换桌宠形象？

A: 把 6 张命名为 01.gif–06.gif 的贴纸（以及可选的 pics/01.png 等作品图）放进 assets/pets/<id>/ 目录，然后到设置 → 宠物管理 → 外观中启用并设为当前宠物。

Q: 状态气泡的"项目 · 已完成 x/y · 阶段"显示什么？

A: 来自 DSH 会话的实时事件：项目名取自 session header 或工作目录名；进度统计当前待办列表的完成条数；阶段由工具类型（搜索/编辑/测试/命令）映射。

Q: macOS / Linux 上能用哪些功能？

A: 页面内桌宠、SSE 推送、多宠物切换、双击画画、所有设置项都可用；只是桌面悬浮窗不提供，会自动回落页面内展示。

上手难度

入门 — 安装即用，默认配置就能看到桌宠；只需在 DSH 网页里跑过一次会话就能理解贴纸和气泡的含义。

已知问题与限制

• package.json 声明 os: ["win32"]、cpu: ["x64"]，意味着某些 dsh 安装形态可能不会在非 Windows / 非 x64 环境加载本插件；页面内桌宠本身可跨平台运行，受限于该声明。
• 桌面悬浮模式首次开启需联网下载约 200MB 的 Electron 运行时；离线 / 沙箱环境需提前把 Electron win32-x64 解压到 vendor/electron-win32-x64/，或设置 DSH_PET_ELECTRON 环境变量指向已存在的 electron.exe。
• 版本低于 0.3.0 的安装无法增量更新（包名发生过两次变更），必须先卸载旧版再装新版；插件内的"一键更新"按钮对低版本会给出卸载重装指引而不会直接覆盖。
• 桌面悬浮窗仅支持 Windows x64；macOS / Linux 上开启 desktopMode 不会报错，但仅会保持页面内桌宠，不会真的拉起独立窗口。

由 DSH 真实会话事件驱动的多宠物网页桌宠：桌宠实时跟随 DeepSeek Harness 的任务进展，以贴纸动画 + 状态气泡呈现。

• 多宠物注册表 + 状态气泡（项目 / 阶段 / 待办 / 进度实时汇报）
• SSE 实时推送 + 可选的桌面悬浮窗（随包 Electron，透明置顶）
• 双击画画联动：粗笔刷揭示作品图（绘制中 → 得意中 → 淡出）
• 一键版本检查 + 增量更新
• 设置面板：宠物管理（多标签页）、插件配置卡片

兼容 DeepSeek Harness（含其分支）的 web profile；桌面悬浮模式默认关闭，可按需开启。

---

特性一览

---

贴纸（mood）→ 状态映射

多 Session 同时运行时按 等待确认 > 错误 > 工作 > 思考 > 空闲 展示最需要关注的顶层任务；子 Agent 默认忽略（可在设置开启）。

宠物定义约定

assets/pets/<id>/01.gif  绘制中（输出/画画）
assets/pets/<id>/02.gif  摸鱼中（工具/错误）
assets/pets/<id>/03.gif  得意中（完成/互动）
assets/pets/<id>/04.gif  思考中
assets/pets/<id>/05.gif  等待中
assets/pets/<id>/06.gif  待机中

可选扩展（不影响完整性校验）：

assets/pets/<id>/07.gif           额外贴纸槽位
assets/pets/<id>/pet-manifest.json  每贴纸对齐偏移 + 作品图数量
assets/pets/<id>/pics/<n>.png      作品图（双击宠物随机弹出，n 从 1 起）

id 只能含字母、数字、下划线、连字符。内置宠物：蕾米埃尔（remielle，素材版权见 NOTICE）。

---

安装

适用于 DSH / DeepSeek Harness（含 Fairy 等基于 DSH 的分支）的 web profile。

# 方式一：npm 注册表（推荐，可一键增量更新）
dsh plugin --profile web add dsh-pet-remielle

# 方式二：GitHub 仓库（构建安装，无版本校验）
dsh plugin --profile web add github:Gin-7/dsh-pet-remielle

# 方式三：本地目录（开发调试，link 安装）
dsh plugin --profile web add D:\path\to\dsh-pet-remielle

# 方式四：GitHub Release tgz
dsh plugin --profile web add "C:\Users\you\Downloads\dsh-pet-remielle-<version>.tgz"

插件行 id：dsh-pet-remielle。卸载即复原，无残留。

---

更新

插件内置「宠物管理 → 更新」页 + 右下角更新气泡：检查 GitHub 最新版本，发现新版可一键更新。

说明：0.3.0 之前存在包名/行 id 变更（0.2.0 之前为 @dsh-external/dsh-client-ui-pet-remielle，0.2.0–0.3.0 为 dsh-pet-remielle）。直接 git pull/pnpm update 无法跨过该变更，所以低于 0.3.0 必须先卸载旧版再重装新版（否则会出现 loaded without registering … via __ModuleLoader__.load 之类的加载报错）。命令如下：

# 按实际安装的旧行 id 卸载（以下两条按需执行）
dsh plugin --profile web remove @dsh-external/dsh-client-ui-pet-remielle   # 0.2.0 及之前
dsh plugin --profile web remove dsh-pet-remielle                            # 0.2.0 – 0.3.0

# 重新安装最新版（npm 或 GitHub 均可）
dsh plugin --profile web add dsh-pet-remielle
# 或： dsh plugin --profile web add github:Gin-7/dsh-pet-remielle

在「设置 → 宠物管理 → 更新」中，低于 0.3.0 的版本点击「一键更新」也会给出同样的卸载/重装指引，不会直接覆盖升级。

---

桌面悬浮模式（可选）

desktopMode 默认关闭。开启后使用 Electron 运行时拉起透明、置顶、无边框的独立窗口显示宠物。

• 窗口支持拖动（位置自动记忆）、滚轮缩放、双击画画、右键菜单。
• 双击画画：作品显示在桌面右上角的独立小窗，粗笔刷沿对角来回揭示，完成后「得意中→淡出」。
• 右键菜单：切换网页模式、锁定、气泡开关、角色大小、画画等。
• 关闭/切换后自动回到页面内；随 DSH host 退出自动关闭。

Electron 运行时来源（按顺序探测）：DSH_PET_ELECTRON 环境变量 → vendor/electron-win32-x64/（本目录不进 Git）→ 系统已安装的 Electron → 均无则仅页面内展示。

首次运行：若开启桌面悬浮模式但本机找不到 Electron 运行时，会提示下载并安装（需你确认，因 Electron 运行时约 200MB）；下载失败则自动回落页面内展示，不会影响其他功能。也可手动把任一 Electron win32-x64 发行包解压到 vendor/electron-win32-x64/，或设置 DSH_PET_ELECTRON 指向现有 electron.exe。

平台能力

---

使用

• 点击桌宠：切换随机贴纸心情。
• 双击桌宠：进入画画动画，绘制完成后在屏幕（右上角）弹出作品图，随后淡出。
• 右键桌宠（页面内）：角色大小 / 锁定位置 / 显示气泡 / 桌面悬浮模式 / 重置位置 / 暂停动画。
• 右键桌宠（桌面窗）：角色大小 / 锁定位置 / 显示气泡 / 画画 / 切换到网页模式。
• 滚轮：调整角色大小。
• 页面内宠物菜单也可反向拉起桌面窗。

---

配置（设置 → 插件 → 蕾米埃尔桌宠）

其余外观/行为项（角色大小、透明度、锁定、气泡、桌面悬浮、暂停、隐藏……）统一放在「设置 → 宠物管理」与右键菜单中管理，不再重复展示在插件配置卡片里。

设置 → 宠物管理

宠物注册表独立标签页，含多个子页：外观 / 行为 / 桌面悬浮 / 更新 / 反馈。

• 启用/禁用宠物、设为当前、改名、添加新宠物。
• 「更新」：显示当前版本，检查更新、一键更新、查看升级说明。
• 「反馈」：显示桌宠版本号，提交 Bug / 功能建议。

---

开发

npm install
node scripts/build-client.mjs    # 构建 lib/client.js（版本号从 package.json 注入）
npm test                          # node --test 单测
npm run check                     # 语法检查

目录结构

src/
├── index.js          # 宿主：配置、事件接线、config/state/pets/assets/desktop 端点、自更新路由
├── self-update.js    # 版本检查 + 一键更新（GitHub 直连 + HTTP 代理回退；git pull / pnpm update）
├── pet-reducer.js    # 纯状态机：会话事件 → state/pulse/task（可单测）
├── protocol.js       # 类型化协议：PetState / PetMood / PetMessageKind
├── pets.js           # 宠物注册表：目录发现/合并/校验（可单测）
├── status-copy.js    # 蕾米埃尔风格状态文案（可整体替换）
├── desktop-window.js # 桌面模式：Electron 发现 + 窗口进程管理（可单测）
├── pet-window.js     # 桌面模式：Electron main（透明置顶窗口 + 屏幕右上角作品窗）
├── pet-view.html     # 桌面模式：宠物窗口页面（GIF + 气泡 + SSE + 画画）
└── client.core.js    # 浏览器端：宠物 UI + 设置（构建时包装）
lib/client.js         # 构建产物（版本号注入，安装即用）
assets/pets/remielle/ # 蕾米埃尔素材（GIF + 作品图）
scripts/build-client.mjs
test/                 # node --test

发布到 npm

npm login
pnpm version patch    # 升版本
pnpm pack --dry-run   # 检查发布内容（不含 node_modules / vendor）
pnpm publish

发布内容由 files 字段限定：src/、lib/client.js、assets/、scripts/、test/、cordis.patch.yml、NOTICE、README.md。vendor/（Electron 运行时）不发布，桌面模式按需下载。

---

许可与素材版权

代码以 MIT 许可分发；蕾米埃尔形象与 GIF/作品素材版权归米哈游（HoYoverse）所有， 禁止商业使用与再分发素材。详见 NOTICE。