前言¶
在 DeepSeek Harness（DSH）里跑智能体时，对话里的 ask_user_question、风险审批和任务进度往往落在 Web 界面或系统通知里，和桌面工作流是分开的。若你希望在 Windows 桌面上有一个始终置顶、可穿透点击的窗口，同时把上述交互接到同一块 UI 上，cobaltions/dsh-pet-madoka 是针对这一场景的 DSH 插件：Electron 透明桌宠 + Live2D 立绘（需自备模型），并在宿主侧接管提问、审批与 todos 投影。
下面按定位、能力、安装与素材导入、典型用法和注意事项说明。
这是什么¶
dsh-pet-Madoka（npm 包名 dsh-pet-madoka，当前版本 1.0.0）由 cobaltions 维护，归类为社区目录中的「趣味换装」。代码基于 bestlike093/dsh-cyrene-balance 的 dsh-cyrene-pet（MIT）改造：形象与台词换成鹿目圆主题，并增加大小控制、游戏语音与气泡降频等能力。
插件在 DSH desktop profile 下加载宿主半（lib/index.js）并拉起独立 Electron 桌宠进程（pet/），通过 %USERPROFILE%\.dsh\storages\madoka-pet\ 下的存储与 DSH webServer 上的 /madoka-pet/* 接口半通信。
核心功能¶
桌宠窗口与 Live2D¶
- 透明无边框置顶窗口；非立绘区域点击穿透；可拖拽移动，松手贴边，位置与大小可记忆。
- Live2D（Cubism 3/4，
.moc3）：表情、动作、眨眼、呼吸、视线跟随。 - 右键菜单、托盘菜单与设置浮层：状态面板、气泡模式、缩放 65%–180%（设置表亦写 60%–180%）、语音档、气泡间隔。
- 卡片模式：不加载立绘，仅保留审批 / 提问小卡片。
状态与气泡¶
- 状态面板：CPU、内存、GPU、网速、电量、DeepSeek 余额、今日消费、额度。
- 周期气泡默认约 1 分钟一条，可调 30 秒 / 2 分钟 / 5 分钟或关闭。
- 游戏语音（可选，需自备语音包）：点击按概率播放，右键「说句话」必播；状态栏上方显示中文字幕条。
与 DSH 工作流对接¶
- 接管对话提问：
ask_user_question的题目逐题出现在桌宠上，答完后一次性交回（四种模式，可在设置中配置处理方式）。 - 接管风险审批：对
approval/request提供「允许一次 / 拒绝」。 - 任务进程：读取
todos投影，长按立绘播报进度。
余额¶
设置页可填 API Key 与余额提醒阈值、今日额度；优先使用设置中的 Key，其次环境变量 DEEPSEEK_API_KEY 与 DSH 凭据服务；若均未配置，可走 DSH 账号登录态（deepseekAccount.getBalance()）。
安装与启用¶
官方 README 给出的方式是从本地源码目录安装（需 Node.js >= 18）：
git clone https://github.com/cobaltions/dsh-pet-madoka.git
dsh plugin --profile desktop add "<仓库目录>"
装好后重启 DSH，或在插件管理中重新加载；桌面上会出现桌宠窗口。
平台限制：README 明确只支持 Windows——透明置顶、点击穿透与贴边行为依赖 Windows 窗口特性。
插件以当前 DSH 进程权限运行；安装前请自行审阅 GitHub 仓库 源码与 MIT 许可证。桌宠会启动独立 Electron 进程，首次启动可能将 DSH 自带的 Electron 运行时复制或链接到 ~/.dsh/storages/madoka-pet/runtime/。
导入模型与语音（必做才能看到立绘）¶
仓库不包含 Live2D 模型、贴图与语音（著作权原因，见 NOTICE.md）。需使用你合法获得的 Live2DViewerEX 工坊包或任意 Cubism 3 模型，按 tools/IMPORT-ASSETS.md 解包后执行：
python tools/import-model.py --src "<解包目录>" --out "pet/assets/live2d/madokatv"
python tools/import-voices.py --src "<解包目录>" --out "pet/assets/voice"
未导入模型时，桌宠仍可运行：状态面板、气泡、审批与提问卡片可用，只是不显示立绘。导入完成后，右键 →「设置」→「重启桌宠」即可加载小圆形象。自行导入的素材仅限个人使用，请勿再分发或商用。
典型用法与设置¶
- 完成 desktop profile 插件安装并重启 DSH，确认桌宠窗口与托盘可用。
- 按需运行上述
import-model.py/import-voices.py，再重启桌宠。 - 在桌宠右键或设置浮层中调整：昵称、缩放、气泡字号/形状/不透明度、气泡间隔、语音档、状态栏显示与详细度、提问与审批处理方式、自动换姿势间隔、音效音量等（完整分组见 README「设置一览」）。
- 智能体触发
ask_user_question或审批请求时，在桌宠 UI 上作答或点选；需要进度口述时长按立绘。 - 若只需轻量交互，可在设置中启用卡片模式，跳过 Live2D 加载。
宿主侧 HTTP 端点包括：/madoka-pet/state、/madoka-pet/control、/madoka-pet/balance、/madoka-pet/hud、/madoka-pet/asset/:name（由插件在 webServer 暴露）。
适用场景与注意¶
适合：在 Windows 上使用 DSH desktop，希望桌面置顶桌宠统一承载 Live2D 展示、系统状态、DeepSeek 余额，并把 Agent 提问、风险审批与任务 todos 从浏览器里挪到桌面的开发者。
注意：
- 仅 Windows；Linux / macOS 不在 README 支持范围内。
- 素材需自备，插件不对角色形象授权；与 DeepSeek、Live2D Inc.、Magica Quartet / Aniplex 等无隶属或合作关系，使用风险自负。
- 社区目录 SkillHub 插件页 为独立站点，与 DeepSeek / 幻方无官方从属关系；安装与审码仍以 GitHub 仓库为准。
结尾¶
dsh-pet-Madoka 把 DSH 的提问、审批与任务进度接到透明 Live2D 桌宠上，并附带状态面板与可选语音字幕；代码 MIT 开源，模型与语音需按文档自行导入。
- 目录页：https://www.skillhub.cn/plugins/cobaltions/dsh-pet-madoka
- 仓库：https://github.com/cobaltions/dsh-pet-madoka
