桌面看板娘 xkk6663/dsh-live2d-mao

Mao-pet · DSH 专用 Live2D 桌宠

把 DeepSeek Harness 的工作状态，变成一只住在你桌面上的 Live2D 看板娘。

她不是贴图，是会呼吸、会看你、会跟着 DSH 干活动起来的桌宠。

主界面展示

右下角就是她。你在 DSH 里敲需求，她在旁边 思考中 → 执行工具 → 完成，头顶徽标实时告诉你「DSH 现在在干嘛」。

🎯 为什么选这只

市面上的桌宠大多停在「有个立绘在屏幕上飘」。这只的不同在于——它真的知道 DSH 在干什么。

| | 常见桌宠 | Mao-pet |
| 状态粒度 | 「思考 / 工作」两三态 | 12 态，细到「正在用哪个工具」 |
| 状态来源 | 定时器 / 假的循环 | DSH 真实事件（会话日志 + 插件事件），跟着轮次走 |
| 需要 API Key？ | 有的要填 key 才能用 | 完全不需要，只读本机日志，不碰云端 |
| 回复正文 | 塞进小气泡，几秒就被冲掉 | 独立流式横条：逐 token、可换行、可滚动看历史 |
| 拿到工具信息 | 一般不知道 | 气泡直接说「正在用 read 干活…」 |
| DSH 专属性 | 跨 Agent 通用，适配浅 | 只为 DSH 做，12 态、审批态、子会话都是 DSH 原生概念 |

装完不用配任何东西：DSH 跑起来 → 桌宠就开始跟着动。没有账号、没有 key、没有云端往返。

✨ 核心亮点

| | 能力 | 说明 |
| 🎭 | 真 · Live2D | PixiJS + Cubism 4 骨骼动画，不是 GIF/序列帧。待机呼吸、眨眼、视线跟随、动作表情全部实时驱动 |
| 🐳 | 8 款内置形象 | DSH 专用（大肥鱼、DeepSeek娘）+ Live2D 官方免费 6 款，开箱即用；也支持导入自己的模型 |
| 🎨 | 自定义动作与表情 | 每个模型可逐槽位绑定动作/表情（思考、观察、聆听、开心、害羞…），DSH 的工作状态会真实驱动它们 |
| 👀 | 视线跟随鼠标 | 她的眼睛一直跟着你的光标走，转头、侧目都是真的骨骼动画 |
| 📡 | DSH 工作状态实时显示 | 12 态语义总线：规划 / 思考中 / 执行工具 / 回复中 / 聆听中 / 说话中 / 待确认 / 完成 / 出错 / 暂停 / 待机 / 在线 |
| 💬 | 工具状态气泡 | 「正在用 read 干活…」——她亲口告诉你 DSH 正在调什么工具 |
| 📜 | 流式横条 | DSH 的回答逐字铺在一条可拖动、可拉伸、可换肤的横条上，单行滚动 / 多行可翻历史 |
| 🖱️ | 拖动交互反馈 | 拖拽带惯性滑行、按压有 Q 弹 + 音效，还能锁定位置、Shift 防误拖 |
| 🔊 | 7 类事件音效 | 按压 / 松开 / 切换 / 任务结束 / 提问 / 授权 / 异常，内置小黄鸭、Minecraft 经验球等原版音效，可逐事件换片段 |
| 🎚️ | 不透明度可调 | 10%~100% 任意调，摸鱼时让她淡一点 |

📸 功能展示

1️⃣ DSH 工作状态实时显示

她在 DSH 里干活时，桌宠头顶会实时显示当前阶段——这是同类桌宠里最细的粒度（多数只有「思考/工作」两态）。

执行工具中徽标「DSH · 思考中」+ 气泡「正在用 read 干活…」
完成徽标变绿「DSH · 完成」，一轮干完

完整 12 态（徽标颜色可在 DSH 面板逐项自定义）：

| 阶段 | 含义 | 桌宠表现 |
| planning | 规划 | 思考动画 + 徽标 |
| thinking | 思考中 | 思考动画 + 徽标 |
| executing_tool | 执行工具 | 观察动作 + 徽标 |
| streaming | 回复中 | 回应动画 + 横条逐字输出 |
| waiting_input | 聆听中 | 聆听动作 + 徽标 |
| voice | 说话中 | 说话口型（预留态） |
| awaiting_approval | 待确认 | 回应动作 + 徽标 |
| complete / error / paused / idle / heartbeat | 完成 / 出错 / 暂停 / 待机 / 在线 | 待机动画，无徽标 |

2️⃣ Live2D 形象与自定义

内置模型

- DSH 专用模型（金色标识）：大肥鱼、DeepSeek娘 —— 为这个项目定制的形象
- Live2D 官方免费模型：Hiyori / Haru / Mao / Mark / Rice / Wanko
- 点卡片即切换形象，写穿服务端持久化（重启、轮询都不会弹回）
- 支持导入自己的 Live2D 模型目录

3️⃣ 自定义动作与表情

动作与表情

每个模型可独立配置 6 类情绪 × 动作/表情：

- 表情槽位：自然 / 开心 / 认真 / 温柔 / 担心 / 害羞 → 任选模型自带表情
- 动作槽位：思考 / 观察 / 聆听 / 说话 / 触碰 / 待机 → 任选模型自带动作
- 绑好后，DSH 的工作状态会真实驱动它们：executing_tool 播放你配的「观察动作」、waiting_input 播放「聆听动作」
- 每个槽位带试听按钮，点一下就知道效果

4️⃣ 拖动交互与反馈

| 交互 | 效果 |
| 拖动 | 跟手移动，松手后按速度惯性滑行、阻尼停稳 |
| 按压 | 角色 Q 弹一下 + 按压音效（小黄鸭） |
| 松开 | 回落音效，构成「咔哒」手感 |
| 锁定位置 | 拖不动，但点击互动照常（防误碰） |
| SHIFT 拖动 | 必须按住 Shift 才拖得动（防误拖） |
| 不透明度 | 10%~100%，右键菜单实时调 |
| 视线跟随 | 眼睛一直跟着鼠标 |

🥚 小彩蛋：点她有概率触发一张隐藏的随机图片（素材库里看不到的那几张）。
点得越久越容易撞上——具体是什么，自己点出来看吧。

5️⃣ 流式横条

DSH 的回答不走气泡，走一条独立的横条：

- 逐 token 铺开，按上游原始节奏（不是整段弹出）
- 文字按宽度自动换行往下递增，超出可见行数后右侧竖条可滚动看历史，最新始终在最底
- 可左右拉伸（无限长）、可拖动、可换肤（8 款）、可关闭
- 内置代码着色（ path/to/file ）、Markdown 粗体与标题

🚀 快速上手

环境要求

- Windows 10 / 11 x64
- PowerShell 7（pwsh，推荐）—— 系统自带的 5.1 也能跑（脚本已带 UTF-8 BOM，中文不会乱码）
- Python 3.10+
- Node.js 18+
- DeepSeek Harness（DSH） —— 桌宠是给它做「脸」的，没有 DSH 就只能看形象

安装

1. 克隆
git clone <本仓库地址> Mao-dsh-pet
cd Mao-dsh-pet

2. 装依赖（Python venv + Node + Electron + 运行时目录权限，交互式） pwsh -NoProfile -ExecutionPolicy Bypass -File 安装依赖.ps1

安装脚本的第 4 步会做一件跟"能启动"直接相关的事：

| 做的事 | 为什么 |
| 创建 pet-data\ / pet-data\pet-instance\ / pet-data\Live2D桌宠\Chromium\ | Electron 的单实例锁（SingletonLock）必须有可写目录，否则 Error code: 3 主进程秒退 |
| 给这几个目录关闭继承并重建 ACL（当前用户/SYSTEM/管理员全控，Everyone 修改） | 让权限自包含，不再依赖机器上恰好存在某条历史遗留规则 |
| 真写一个探针文件再删掉 | 目录存在 ≠ 能写（受限令牌下 mkdir 会 Error 5），不验证等于没做 |

这一步失败也不会让桌宠起不来：main.js 会按项目内 pet-data → %LOCALAPPDATA%\Mao-pet → %TEMP%\mao-pet-runtime 自动降级，并在全部不可写时弹窗给出修复命令（不再静默秒退）。
技术细节与排查过程见 docs/项目独立性-技术分析.md。

.env 是可选的

后端会读 私人AI日记系统\backend\.env，没有这个文件也能启动（全部走默认值）。
需要接大模型 / 联网搜索时再复制模板填 key：

Copy-Item 私人AI日记系统\backend\.env.example 私人AI日记系统\backend\.env

配置 DSH 接入

复制模板、改一下自己的路径即可：

Copy-Item 私人AI日记系统\dsh_config.example.json 私人AI日记系统\dsh_config.json

编辑 dsh_config.json：

{
"enabled": true,
"sessions_root": "C:\\Users\\<你的用户名>\\.dsh\\sessions", "workspace": "", // 留空 = 跟随本项目目录 "session_id": "", // 留空 = 自动选活跃会话 "node_path": "" // 留空 = 自动探测 node } 💡 dsh_config.json 含本机路径，已 gitignore 不入库。不配这个文件，DSH 会显示「未启用」。

启动

一键启动（后端 + 桌宠） pwsh -NoProfile -ExecutionPolicy Bypass -File start_mio.ps1

或一键重启（改了代码之后用；改了 Electron 外壳要加 -ForcePet） pwsh -NoProfile -ExecutionPolicy Bypass -File restart_mio.ps1 -ForcePet

启动后：

1. 桌宠出现在桌面（默认右下角）
2. 右键桌宠 → 「打开 Mio」→ 进管理窗
3. 左侧导航 「DSH」 → 看实时状态面板
4. 去 DSH 里发一条需求 → 桌宠立刻开始「思考中 → 执行工具 → 完成」

安装插件（可选，推荐）

没有插件时，桌宠通过日志边车读 DSH 会话日志（有 1~2 秒延迟）；装上插件后，走实时事件流（即时、更细的功能状态）。

从 npm 装（推荐，一条命令）
dsh plugin --profile web add dsh-live2d-mao

桌面客户端用 desktop profile
dsh plugin --profile desktop add dsh-live2d-mao

插件跑在 DSH 进程内，推送时复用 DSH 的身份——桌宠上只会看到一个 DSH，不会多出第二个名字。

🖱️ 右键菜单速查

| 菜单项 | 作用 |
| 打开/关闭对话窗口 | 桌宠自己的对话横条（走 /api/companion/chat） |
| 更换形象 | 打开形象图库，点卡片即切换 |
| 调整大小 | 弹滑块面板，实时缩放 |
| 调整不透明度 | 弹滑块面板，10%~100% 实时变透明 |
| 隐藏/显示说话气泡 | 工具状态气泡的独立开关 |
| 隐藏/显示流式提示 | 流式横条的独立开关 |
| 隐藏/显示状态徽标 | 头顶徽标开关 |
| 打开 Mio | 打开管理窗 |
| 关闭桌宠 | 退出 |

三条通路（说话气泡 / 流式横条 / 状态徽标）相互独立，各自开关互不影响。

🎛️ 设置页速查

管理窗 → 「设置」：

| Tab | 内容 |
| 资料 | 头像、名称 |
| 桌宠 | 大小/缩放/垂直偏移、跟随鼠标、置顶、穿透、气泡开关、交互打磨（锁定位置 / SHIFT 拖动 / 拖拽惯性）、模型自动更换 |
| 语音 | 语音相关（当前 DSH 无 TTS，为预留） |
| 主题 | 横条（默认宽度 / 显示行数 / 8 款皮肤）+ 气泡与互动（气泡皮肤 / 点击序列 / 图片素材库 / 7 类音效） |

音效可在「主题 → 音效事件」里逐行选择：默认音效 / 内置合成音 / 内置片段（小黄鸭、Minecraft 经验球…）/ 自己上传的片段，选中即可试听。

🏗️ 技术架构（一句话版）

DSH 会话事件 ──┬─→ 日志边车（读会话日志，兜底路径） └─→ dsh-live2d-mao 插件（DSH 进程内，实时路径） ↓ 12 态状态总线（FastAPI） ↓ WebSocket ─→ Electron 桌宠窗口（Live2D 渲染）

- 桌宠无状态：它只认总线上的标准 phase，不认识 DSH
- 三条独立通路：agent_phase（动画/徽标）/ agent_stream（流式横条）/ agent_bubble（工具状态气泡）
- 插件只推事件：插件跑在 ELECTRON_RUN_AS_NODE=1 子进程里，没有窗口能力，只负责"把 DSH 在干什么"推出去

详细设计见 SRC-MAP-源码地图.md 与 AGENTS.md。

🧩 插件分层（谁在哪一层、谁发布到哪）

本仓库涉及四个容易混淆的层次，各自的归属与发布位如下：

| 层 | 是什么 | 代码位置 | 发布位 |
| 桌宠主体 | Electron 壳 + Live2D 渲染端 + FastAPI 后端 + 内置插件市场（pet / market 等 builtin） | 本仓库 澪Agent应用/ + 私人AI日记系统/ | 桌宠安装包（打包发布.ps1） |
| dsh 插件 | dsh-live2d-mao 连接器（Cordis，只推事件） | 本仓库 packages/dsh-live2d-mao/ | npm + dsh-market（本仓库唯一的 dsh 发布物，含 lib/ 连接器与市场截图，不含任何业务插件） |
| 内置插件 | 随主体预装、走同一份清单加载（数据/插件市场.json） | 本仓库 dist/plugins/* | 只随桌宠安装包，不进 npm |
| 大肥鱼插件 | 云端 AstrBot 多模态对话（界面 + 后端） | 独立仓库 mao-plugin-feiyu | Mao 插件市场按需安装（拆分中，过渡期 builtin） |

两条铁律：① 界面随插件走——插件页的 UI 属于插件，不依赖主体内嵌页面；② 插件之间零依赖——每个插件只声明自己、只调主体公开接口。

📚 文档导航

| 文档 | 用途 |
| AGENTS.md | ★ 工程纪律权威：三条架构红线（机器守卫）/ 变更纪律 / D1~D5 裁决 / 提交前门禁 |
| SRC-MAP-源码地图.md | ★ 改哪块看哪份：界面导航 / 后端导航 / 修改守则 |
| docs/SKILL-发布与版本迭代.md | ★ 发版必读：门禁检查 / 版本号同步 / npm 发布 / 实机验证 / 市场上架全流程 + 故障速查 |
| docs/后续开发方向.md | 待办清单、明确不做的事、已知技术债 |
| docs/竞品对标-dsh-pet-indesktop.md | 与 dsh-pet-indesktop / whale 的能力对比 |
| docs/DSH专用化阉割记录.md | 项目演进记录（做了什么、为什么、怎么验） |

❓ 常见问题

桌宠没出现 / 起来又秒退

按这三条依次排查（都是踩过的真实坑）：

1. 环境变量 ELECTRON_RUN_AS_NODE=1 —— 从某些宿主环境启动会继承它，让 electron 退化成 node 模式。start_mio.ps1 / restart_mio.ps1 已自动清理。
2. pet-data/pet-instance 目录不可写 —— Chromium 单实例锁创建失败。脚本已自动回落到 Mao 主仓库的 pet-instance。
3. Electron 工作目录错了 —— 会加载到别的仓库的 main.js。脚本已固定指向本仓库。

用 restart_mio.ps1 -ForcePet 重启最稳。详见 docs/DSH专用化阉割记录.md §7.4。

DSH 面板显示「未启用」/「离线」

- 「未启用」→ 缺 私人AI日记系统/dsh_config.json，照上文「配置 DSH 接入」建一个
- 「离线」→ DSH 没在跑，或 sessions_root 路径不对

改了代码不生效

- 改 dist/core-inject / kernel / plugins / live2d-pet（手写层）：直接改 + 升对应 ?v= 版本号 + 刷新窗口
- 改 澪Agent应用/src（Vue 源码）：npm run build:dist 重建
- 改 live2d-desktop/main.js（Electron 外壳）：必须 restart_mio.ps1 -ForcePet 整个重启
- 管理窗里的用户偏好不存 localStorage（每次打开会清），一律存后端 settings

桌宠挡住了别的窗口怎么办

右键 → 「调整不透明度」调低，或「隐藏状态徽标」。鼠标穿透是自动的：只有落在模型/横条上才可交互，其余区域直接穿透。

📄 许可与致谢

代码：MIT。

Live2D 模型素材

版权归各自作者。本项目内置两个 DSH 专用模型，来源与许可如下：

| 模型 | 作者 | 许可与注意事项 |
| 大肥鱼 | B 站 @Mao绒绒家园（UID 431301506） | 免费公皮（视频 BV1yep465EQz），非官方二创、非商业用途，禁止盗用与出售 |
| DS 鲸鱼娘 | B 站 @氵六青（VTube Studio 模型） | CC BY-NC-SA 4.0（署名 · 非商业 · 相同方式共享）。角色版权链：上善无形（鲸鱼娘角色原作，原创 OC「溟月」）→ ZipZipPipe（DeepSeek 女仆二创）→ 氵六青（本模型）。经作者授权转载开源，但基础版权未解除，商业使用需分别取得三人授权 |
| Hiyori / Haru / Mao / Mark / Rice / Wanko | Live2D 官方 | 免费示例模型 |

项目由来与致谢

本项目不是从零写的。它的来源链是三段：

ochiru520/Mio 原始上游：Electron + Vue SPA + FastAPI 桌宠 │ 魔改 ▼ xkk6663/Mao 跨 Agent 平台桌宠（统一 12 phase 状态总线 + 多适配器） │ DSH 专用化 + 阉割 ▼ xkk6663/dsh-live2d-mao 本项目：只做 DSH 的 Live2D 桌宠

🙏 ochiru520/Mio —— 原始上游。整个桌宠本体（Electron 外壳 + Vue SPA 管理窗 + FastAPI 后端 + Live2D 渲染管线）源自 Mio。
没有它就没有这一脉。Mio 是通用的跨 Agent 桌宠平台，本项目是在其基础上做的 DSH 特化分支。

🙏 xkk6663/Mao —— 直接上游。在 Mio 基础上改造出的跨 Agent 平台桌宠版本（统一 12 phase 状态总线、小智/DSH/Octop 多适配器、Agent 管理页与状态徽标）。
本仓库从 Mao 的 v4.1 基线 fork 出来，阉割掉非 DSH 的插件与能力，专用化为纯 DSH 桌宠。

🙏 @Mao绒绒家园（B站 UID 431301506）提供「大肥鱼」免费公皮，让这只桌宠有了灵魂。

🙏 @氵六青（B站）制作「DS 鲸鱼娘」模型并授权开源分发；角色原作 上善无形、DeepSeek 女仆二创 ZipZipPipe。

🙏 A8Chann/dsh-pet-live2d —— 在「把 Live2D 桌宠接进 DSH」这件事给了我们思路参考，它也是 DS 鲸鱼娘模型的分发渠道。本项目与它是两套独立实现：它把 Web GUI 内嵌，我们的插件只推事件，外加独立的 Electron 桌宠窗口。

内置音效片段：来源见 docs/后续开发方向.md 技术债一节。

Mao-pet · 为 DeepSeek Harness 而生的 Live2D 桌宠