桌面宠物 zuoyunlai/dsh-pet-plugin

dsh-pet

一个小伙伴，住在 DSH web UI 的右下角：它会待在那儿，也会随机冒出来，会说话（带语音）、走路、跳舞、害羞或生气，还带一个小输入框，你可以跟它聊天。五个照片级写实人设，各有各的脾气。

范围：这只宠物只活在 DSH 窗口里（挂载到框架的 overlay 插槽）。它无法浮在其他应用之上——那需要单独的 Electron 外壳，而不是插件。

一览

- 语言：界面文案、人设标语和聊天系统提示词跟随浏览器界面语言——已提供 en / zh / es / pt / hi（locale/.json，命名空间 pet；按 DSH 插槽约定，插槽以 locale: 'pet' 注册）。每个人设还附带一套英文台词包，所以非中文界面听到的是英文台词。

- 挂载点：shell.overlay（宠物本体，一个可点击穿透的图层）和 conversation.input.right（输入框旁边的入口按钮）。
- 私密聊天：你在小框里输入的内容永远不会进入你的会话。宿主端暴露 POST /dsh-pet/chat，用一次性的 ctx.llm.stream() 调用作答（不建会话，不写会话日志）。默认：deepseek-account / deepseek-flash；服务商、模型、maxTokens 和 temperature 都是插件配置。
- 图标：icon.svg（玫瑰剪影）和输入框按钮共用同一路径。
- 设置面板：分组排列（外观 / 语音 / 显示 / 动作 / 特效），自定义下拉框（原生 弹层是系统白底，深色主题下看不清）和自定义开关；面板相对宠物定位（在她上方，没空间时在她左侧），并在页头下方收进视口内。
- 五个人设（照片级写实，同一套光照；五个各带 5 种表情：默认 / 开心 / 害羞 / 生气 / 困倦）：薇（紫罗兰）、绯（绯红）、靛（靛蓝）、雪（银白），外加鲸鱼娘（蔚蓝）——一位鲸鳍女仆，表情集在 1.23.0 加入，有专属的走路 / 跳舞 / 发夹动作。表情切换用交叉淡入（180 ms），不是硬切。
- 动作序列：人设可以声明 actions: { dance: [...], hair: [...], walk: [...] }；每组 3–6 帧（3 帧组每帧 340 ms，6 帧组每帧 230 ms；蔚蓝只带视频片段，没有帧组）。四个原版人设都有跳舞 / 甩发 / 走路，各自贴合角色风格；较新的人设可以改用视频片段（VP9 + alpha），片段本身的长度决定动作持续多久。
- 添加素材：把透明 PNG 放进 assets/，在 PERSONAS 里引用（image，或 images: { mood: 'file.png' }）。由 /dsh-pet/assets/ 提供（只接受图片和 webm 视频扩展名，只接受文件名）。tools/make-pet-image.py 会去掉绿幕背景（首选），不行再退回渐变抠像。

行为

| 能力 | 做法 |
| 常驻 / 随机 | 在面板里切换；随机模式会在活跃时段内按每小时概率抽取 |
| 活跃时段 | 起止时间，支持跨午夜（22:00 → 03:00） |
| 主动台词 | 按心情分组的台词包，气泡 + 语音 |
| 语音 | 可选：宿主只要有任意 python 带 edge-tts，/dsh-pet/tts 就合成语音（带缓存），/dsh-pet/tts/status 探测可用性；否则回退到系统 speechSynthesis。插件本身零运行时依赖 |
| 小输入框 | 默认隐藏；鼠标悬停在角色上时滑出（1.22.0 起，从角色移到输入框上不会收起）。在设置里关掉「仅悬停」即可固定。消息只发给宠物；一次性模型调用，不写入任何 DSH 会话 |
| 心情 | idle / walk / dance / shy / angry / sleep / talk / happy |
| 拖拽 | 放下后有 60% 概率说一句 drag 台词；五个人格都有（1.24.0 完成），五种语言 |
| 内心独白 | 低频（7%）灰色旁白——只是想法，从不出声；仅限声明了 lines.aside 的人格；五个都有（1.24.0） |
| 视线 | 瞳孔跟随鼠标（只用 CSS 变量，不触发重渲染） |
| 特效 | 墨水 / 彩纸 / 云 / 雾（可擦除）/ 炸弹 + 屏幕裂纹 |
| 事件钩子 | 一轮对话超过 4 s 后撒彩纸；工具调用失败后出现云 |
| 脾气 | 每个人格有各自的权重表，决定它更常做什么 |
| 隐藏 | 面板里的「隐藏 1 小时」 |

安装（本地，不走 registry）

已发布到 npm，包名 dsh-pet-plugin；也可以直接从文件夹安装。

from the registry (after publish)
dsh plugin --profile desktop add dsh-pet-plugin

from a local checkout: quit DSH first, then
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 # or double-click install.cmd

先退出 DSH（配置档的 package.json 被 HMR 监听）。脚本会把 "dsh-pet-plugin": "file:<this dir>" 加进配置档，注册 bundle，运行 pnpm install，然后回读四项事实。update.cmd 只刷新文件，DSH 运行时执行也安全。想要更甜美的神经语音：

pip install edge-tts # any python the host can find
export DSH_PET_PYTHON=/path/to/python # only if auto-discovery misses it

验证

node --check client.js
node tests/smoke.mjs # fake window + React stub, renders every persona/mood
host routes need the harness packages, so run them from the installed copy:
cd <profile>/node_modules/dsh-pet-plugin && node --test tests/host.test.mjs
node <dsh-plugin-guide>/bin/dsh-plugin-dev.js check --cwd . --strict
node <dsh-plugin-guide>/bin/dsh-plugin-dev.js verify --cwd .

自定义

- 客户端 bundle 是生成出来的：改 src/.js，再运行 node build.mjs，它会把各部分拼成 client.js（DSH 唯一加载的文件）。绝不要直接编辑手动改 client.js —— npm test 会先重新构建，再跑冒烟测试。
- 角色、台词和脾气：pets/<id>/pack.json —— images（五种表情）、actions（dance / hair / walk，每个 3–6 帧）、voice、temper，以及 lines / linesEn 台词包。
- UI 文案：改 locale/.json 里的 pet 命名空间，然后跑 node build.mjs —— 字典在构建时注入，所以 locale 文件是唯一事实来源。新增语言：先跑 node tools/gen-locales.cjs 生成骨架，再翻译。
- 情绪和动画：在 src/70-style.js 里加关键帧，在 src/96-overlay.js 里按 mood 映射 class。
- 动作片段：资源包可以带 clips: { dance: "pet-x-dance.webm" } —— 一段带 alpha 通道的 VP9 WebM。片段高度分档（1.25.0）：舞台片段 960（从 2K 母版单代重新导出，供 4K 显示器上放大的 dance 用），四个原版的 hair/walk 768（从 768 母版原生导出），其余 640；普通片段约 5.167s，舞台片段约 10.125s。tools/assets-manifest.cjs 记录尺寸、时长、编码、像素格式、alpha 模式、字节大小和 SHA-256；资源测试会校验这些值，并限制总量不超过 20 MB。播放该动作时，宠物渲染一个循环 ，不再逐帧翻静态图 —— 这是拿到真正 24 fps 动态的唯一办法。
- 美术资源：把透明 WebP 丢进 assets/，在 pets/<id>/pack.json 里引用，然后跑 node build.mjs（它会重新生成 src/30-personas.js）。/dsh-pet/assets/ 路由只提供白名单内的图片和 webm 视频扩展名。

运行时扩展（1.21.0）

- 不重新构建也能加自定义角色包：把 $DSH_HOME/dsh-pet/pets/<id>/pack.json 放进去（资源放在旁边；license 是内置资源包的发布门槛 —— 用户资源包在运行时不做 license 检查）—— 宿主启动时扫描它，与内置的五个合并，并通过 /dsh-pet/pets/<id>/… 提供（realpath 包含校验 + 扩展名白名单 + 413 超限）。资源包必须满足渲染契约，否则在加载时整体拒绝（fail-closed，宿主日志里一条警告）：name + clips、image（SVG 角色则需完整的 colors 表），以及 —— 当存在 voice / temper 时 —— voice.pitch / voice.rate 为有限数值、temper 为 mood → 正数。客户端通过 GET /dsh-pet/personas 拉取列表，取不到时回退到内置表。
- 台词覆盖：$DSH_HOME/dsh-pet/voice.json ——
{"<personaId>|": {"lines|linesEn|linesEs|linesPt|linesHi": {"<mood>": ["…≤300 chars, ≤200 lines"]}}}。
按情绪合并，任何格式错误的部分都警告并丢弃；文件损坏则忽略并警告，绝不崩溃。
- 让宠物说话：POST /dsh-pet/announce {"text": "…"}（≤300 字符，限速 30 次/分）。轮询 /dsh-pet/ping 获取 phase（working|tool|review|done，15s 新鲜度）和 announce（seq 守卫）——智能体工作时，phase 驱动走路、理毛等微动作。
- 宿主侧状态：GET/POST /dsh-pet/state。两端都带 updatedAt（最新者胜出，所以旧的宿主快照永远无法回滚本地的新改动）；每次设置或历史变更后，客户端会防抖 500 ms 再 POST。历史存为 {role, content} 对象——旧的 "[object Object]" 字符串会被丢弃并迁移，而不是写回。设置键在宿主侧有白名单（≤64 项，历史 ≤200 条 × 8000 字符）。
- 静默自动闲聊：设置 statusBubbles: "auto" | "off" 可关闭心情、问候、空闲气泡；点击、拖拽和 announce 仍会说话。
- 许可：每个资源包都声明 license；第三方声明放在 THIRD_PARTY_NOTICES.md；资源测试对两者都做强制校验。

安全模型

- 宿主路由有三重门禁，都不绑定固定端口或域名：Host 必须是回环地址、宿主自身的 origin，或列在 allowedHosts 插件配置里（用于反向代理 / 局域网部署）；请求带 Origin 时，必须与该 Host 同源，或为桌面外壳（dsh-app://app、dsh-app://shell）；请求带 Sec-Fetch-Site 时，必须是 same-origin 或 none。三者都不发的非浏览器客户端会被放行——这是本地 HTTP 端点的有意限制，见下文。
- 语音合成是 POST 端点，返回音频字节；没有可喂给 的 GET URL，所以页面（或其他本地进程）无法通过把元素指向它来让宿主合成任何内容。
- 合成语音缓存在系统临时目录，带大小上限，每次合成后都会重新检查；写入走随机临时名 + rename，预先埋好的符号链接无法把写入重定向到别处。
- 页面发来的任何内容（设置、聊天历史、persona id）都当作数据处理：校验、限制长度，绝不作为指令或标记插值。
- 神经语音会把朗读文本发到 Microsoft 的 edge-tts 端点。关掉它（或干脆不安装 edge-tts）即可保持全本地；面板上会说明这一点。

已知限制

- 宿主版本：基于 dsh 0.2.1-alpha.2 构建并测试。它需要 webServer 服务和 shell.overlay / conversation.input.right 插槽，这些是 0.2 代 API——在 0.1.x 宿主上能安装但永远不会挂载（控制台会有一行提示）。package.json 里的 engines.dsh 只是声明：安装器不强制执行，插件也刻意不声明 @deepseek-ai/dsh-* 的 peer 范围，所以版本不匹配永远不会阻止安装。

- 神经语音需要宿主 python 装有 edge_tts；否则使用系统 SAPI 语音。
- 浏览器在首次用户手势前会阻止自动播放——点一下页面即可。
- 设置存在 localStorage。调试句柄（globalThis.__dshPet）默认关闭，除非在 localStorage 里设置 dsh-pet.debug=1，或者追加 ?petdebug=1。
- 宠物无法浮在其他应用之上（仅限 overlay 槽位）。