---

这是什么

一只角色，两种存在方式：

	页面内桌宠	系统全局桌宠
形态	注册进 shell.overlay 插槽的悬浮层	透明、置顶、鼠标穿透的 Electron 窗口
覆盖范围	harness 窗口内	整个桌面，浮在其他应用之上
状态来源	useSessions 快照	插件 Host 半边的回环桥（SSE 实时推送）
适用	Web GUI、官方桌面端	想让角色待在屏幕上、不占 harness 窗口时

两边共用同一个角色引擎，所以是同一只角色，不是两套实现。

它做三件事：

• 看着 harness：从真实 Host 事件推出「思考中 / 调用工具 / 搁置 / 完成 / 报错」，用动作、徽标和气泡同时表达；
• 替你下指令：点一下角色弹出气泡，把话送进选中的会话，支持排队与插话两种投递模式；
• 不碍事：窗口默认整窗鼠标穿透，只在光标真正落在角色身上时才接管点击。

状态绑定

状态全部来自 harness 的真实事件，没有轮询私有接口：

相位	触发	桌宠表现
thinking	agent/status → running	快速上下浮动、张嘴
tool	session/event tool/call	气泡显示正在调用哪个工具
done	turn/end completed	跳一下，绿色徽标
error	turn/end 非 completed、agent/error	抖动，红色徽标 + 原因
waiting	running 但 45 秒无事件	几乎静止、呼吸变慢、黄色徽标
idle	其余	常态呼吸 + 随机眨眼

waiting（搁置）是刻意做成“看起来就不一样”的：忙是动的，卡住是静的。完整的事件映射与可调窗口见 docs/ARCHITECTURE.md。

快速开始

环境要求

• Node.js ≥ 20
• 已安装 DeepSeek Harness（dsh 在 PATH 上）
• 系统全局桌宠需要 Electron，随 pnpm install 装好

1. 页面内桌宠

git clone https://github.com/br0ny4/dsh-live2d-pet.git
cd dsh-live2d-pet
pnpm install
pnpm build

dsh plugin --profile web add ./packages/dsh-live2d-pet

重启 dsh 后，界面右下角出现桌宠。卸载：

dsh plugin --profile web remove dsh-live2d-pet

2. 系统全局桌宠

cd packages/dsh-pet-shell
pnpm start

外壳的接入策略是自动选：先找已经在跑的 harness（也就是你正在用的那个），找到就直接接上去，状态与指令都通到那些会话；找不到才自己起一个 dsh web --port 0。

npx electron . --attach-only        # 只接入，不自己起 harness
npx electron . --dsh /path/to/dsh   # 指定 dsh 可执行文件
npx electron . --profile web        # 指定 profile
npx electron . --dev                # 详细日志

托盘菜单提供连接状态、重新连接、开关桌宠、打开 Harness 界面。

交互

操作	结果
单击角色	打开 / 收起指令气泡
拖动角色	移到桌面任意位置
移动鼠标	角色的眼睛跟着光标
⌘/Ctrl + Enter	直接发送
气泡里的模式按钮	在「排队」（排在当前回合之后）与「插话」（打断正在执行的回合）之间切换

角色

自带两个，也接受你自己的：

DeepSeek 鲸鱼娘（默认，网格形变 + 真眨眼）	咕咕嘎嘎（帧动画图集）

在指令气泡的「角色」下拉框里切换。要用自己的三视图：

node scripts/character.mjs add --from ~/我的角色.png --id my-character --name "我的角色"

白底三视图和已抠好的透明 PNG 都吃，会自动抠图、自动绑骨，并输出一张骨架叠图供你核对（推导不准时可以写 rig.overrides.json 局部修正）。完整说明见 docs/CHARACTERS.md。

它是怎么动起来的

角色是一张扁平立绘，渲染器把它当作可形变网格——骨架用椭圆区域标出头发、呆毛、鳍、裙摆、躯干、双眼、嘴，每个网格顶点按覆盖它的区域权重位移。在此之上还有一层行为：

行为	表现
情绪	思考 / 执行 / 搁置 / 完成 / 报错各自不同的体态
打盹	长时间待命后闭眼、呼吸变慢、飘出 z
戳一下	点角色它会跳一下并冒感叹号
拖动	移动窗口时下半身滞后于身体
视线	眼睛跟随光标；没人理它时自己东张西望
徽记	完成冒星、报错冒汗滴，都是矢量绘制，不依赖素材

真 Live2D 模型是更好的答案，本项目也生产了一个：resources/live2d/models/whale-maid/ 里有完整的 Cubism 4 模型族（.moc3 + .model3.json + .cdi3.json + physics3.json + 6 秒循环待机与眨眼/点头/摇头动作 + 4096² 图集 + 可二次编辑的 .cmo3），由 live2d-pipeline/ 从分层 PSD 经 psd2live 自动绑骨导出。

目前插件渲染的仍是网格形变，Cubism 渲染后端尚未接入。渲染后端只需要满足四个方法，换后端不用动 UI：

createCharacter(canvas, { rig, sprite }) -> {
  setMood(mood), setTalking(bool), setPointer(x, y, active), dispose()
}

也可以直接使用官方免费样例模型：pnpm assets:live2d 会从 Live2D 官方渠道下载 Cubism Core 与 8 个样例模型（Hiyori、Haru、Mao、Mark、Natori、Ren、Rice、Wanko）。这些素材不入库，理由见许可。

仓库结构

packages/
  dsh-live2d-pet/            插件包（可发布到 npm）
    lib/index.js               Host 半边：事件订阅 + 回环桥 + 发现文件
    src/client/pet.js          页面内桌宠：悬浮层 + 指令气泡
    src/client/engine.js       WebGL 网格形变渲染器
    test/bridge.test.mjs       Host 半边自测（34 项）
    build.mjs                  esbuild → 内联样式表与立绘
  dsh-pet-shell/             系统桌面外壳（Electron，不发布）
    src/main/index.js          窗口 / 托盘 / 接入策略
    src/main/bridge.js         发现文件 + SSE 客户端
    src/main/harness.js        查找 dsh、拉起 harness、等桥就绪
    src/renderer/pet.js        全局桌宠 UI + 逐像素命中测试
    test/smoke.mjs             端到端冒烟（9 项）
scripts/
  character.mjs             角色 CLI：list / build / add（自带三视图导入）
  lib/matte.mjs             抠图：白纸参考稿与透明图两条路
  lib/rig.mjs               自动绑骨：轮廓、双眼、喙/嘴、躯干、鳍、脚
  fetch-live2d-assets.mjs   抓取 Cubism Core 与官方样例模型
  fetch-gugu-assets.mjs     抓取咕咕嘎嘎帧动画图集并生成来源说明
  make-doc-images.mjs       合成 README 用图
  live2d-*.sh               psd2live 构建与运行
docs/
  ARCHITECTURE.md            两层结构、桥协议、状态派生、渲染取舍
  CHARACTERS.md              角色来源、自定义导入、骨架修正
  VERSIONING.md              版本管理计划
resources/
  characters/whale-maid/     内置角色：立绘、骨架、原画
  characters/gugu/           内置角色：帧动画图集（含 PROVENANCE.md）
  live2d/models/whale-maid/  自产的 Cubism 4 模型
live2d-pipeline/             分层 PSD → .moc3 的生产流水线（独立 README）

开发

pnpm install
pnpm build                   # 构建插件客户端 bundle 与外壳渲染进程 bundle

# 角色
pnpm characters              # 列出全部角色
pnpm characters:build        # 重建立绘与桌宠小图（保留既有骨架）
pnpm characters:rerig        # 重新推导骨架，再核对 debug-overlay.png
node scripts/character.mjs add --from <图> --id <名>   # 导入自己的角色

# Live2D 官方素材
pnpm assets:live2d           # 下载 Cubism Core + 官方样例模型
pnpm assets:live2d:list      # 列出可下载的样例模型

改了插件源码后，重新 pnpm build 并重启 dsh 即可。开发外壳时可以用 test/mock-bridge.mjs 起一个假 harness，不必真的跑一遍：

DSH_HOME=/tmp/pet-dev node packages/dsh-pet-shell/test/mock-bridge.mjs &
DSH_HOME=/tmp/pet-dev npx electron packages/dsh-pet-shell --attach-only --dev

测试

pnpm test              # 全部 100 项断言
pnpm test:bridge       # Host 桥 43 项
pnpm test:harness      # 真 harness 端到端 11 项（无 dsh 时自动跳过）
pnpm test:shell        # 外壳端到端 13 项
pnpm test:harness      # 真 harness 端到端 11 项
pnpm test:failover     # 路由故障切换 9 项
pnpm test:model        # 模型结构 23 项

test:shell 是真正的集成测试：它拉起一个只实现三条路由的假 harness，再把真的 Electron 外壳跑起来接上去，校验接入日志、零渲染错误、角色加载、截图的尺寸与格式。它唯一判断不了的是角色好不好看——那需要人眼看 PNG（加 --keep-shot 会保留截图路径）。

渲染进程的错误会直接判定测试失败。这条规则不是装饰：徽记层曾经因为「WebGL 画布拿不到 2D 上下文」每帧抛异常，而界面看起来完全正常，正是这条断言把它抓出来的。

文档

文档	内容
docs/ARCHITECTURE.md	两层结构的由来、harness 接入点、状态派生、桥协议规格、渲染取舍
docs/CHARACTERS.md	角色来源、导入自己的三视图、骨架修正、角色查找顺序
docs/VERSIONING.md	版本号规则、桥协议版本、兼容性矩阵、发布流程、分支策略
CHANGELOG.md	变更记录
live2d-pipeline/README.md	分层 PSD → .moc3 的完整生产流程与复现命令
packages/dsh-live2d-pet/README.md	插件包的使用与打包细节

兼容性

插件版本	最低 DSH	宿主	说明
0.1.x	0.1.5-rc.2	Web GUI、官方桌面端	首个可用版本

DeepSeek Harness 目前处于预发布（0.1.5-rc.2），客户端插件 API 没有兼容承诺。若 harness 升级导致 dsh.client.inject 依赖项或插槽契约变化，插件会发 minor 版本并在上表标注新的最低版本。详见 docs/VERSIONING.md。

已知限制

这份清单是如实的，不是待办宣传：

• 默认角色是网格形变，不是真 Live2D。.moc3 已产出并通过 23 项结构校验，但渲染后端尚未接入。
• 模型只在中性姿态下验证过像素级正确。分层 PSD 重新合成与源图逐像素相等（max|Δ| = 0），但眨眼、口型、物理在真实渲染器里的表现尚未目视确认。
• PSD 的语义标签有一部分是启发式近似。原画没有真正的分层信息，头发前后、头饰、尾鳍、额头的切分来自几何与颜色规则；其中“发丝搭在深蓝衣服上”那一处最弱，中性姿态看不出，让这些部件单独形变时会露馅。
• 原画没有眉毛（被刘海完全遮住）。要做眉毛动画需要先补画。
• 换角色需要重新构建：立绘与骨架在构建时内联进 bundle。
• 官方桌面端尚未发布安装包。官方仓库里已有 apps/desktop，但 npm 上还没有包、也没有安装包。插件本身在官方桌面端里能跑（同一套客户端运行时），系统全局悬浮窗口那部分要等它放出窗口 API。

许可

MIT。

本仓库不包含以下第三方素材，它们由 pnpm assets:live2d 按机器从官方渠道抓取：

• Live2D Cubism Core 与官方样例模型（Hiyori、Haru、Mao、Mark、Natori、Ren、Rice、Wanko）是株式会社 Live2D 的专有素材。按 Live2D 的许可，它们可以随应用分发，但不能作为独立文件再分发——所以由脚本按机器获取，不入库。
• DeepSeek Harness（@deepseek-ai/*）作为依赖使用，不在此仓库内。

resources/live2d/models/whale-maid/ 是本项目自己的产出（由本仓库的角色立绘经 psd2live 生成），随仓库分发。

角色立绘的来源

「DeepSeek 鲸鱼娘 / 大肥鱼」与「咕咕嘎嘎」都是社区二创角色，不是本项目的原创作品，也不代表任何官方授权或认可。

resources/characters/whale-maid/ 下的立绘来自第三方项目，按其许可随仓库分发：

作者	YunYueSama
仓库	https://github.com/YunYueSama/codex-deepseek-pet
许可	大肥鱼项目署名许可 1.0（全文）

许可允许使用、修改、分享与商用，条件是保留署名、保留完整许可文本、并说明修改内容 —— 三者都记录在 LICENSE-ASSET.md（由 scripts/fetch-whale-maid-art.mjs 生成，随素材一起更新）。

**「咕咕嘎嘎」**的情况更要如实说明：形象基础是《明日方舟：终末地》的「管理员」二创企鹅，底层 IP 属 Hypergryph；定义性图片的 B 站创作者已完成著作权登记，字节跳动也登记了美术形象著作权——三方主张并存，任何人都无法给出干净授权。素材取自无许可证的帧动画图集仓库，按项目所有者的明确决定使用；PROVENANCE.md 记录了全部事实，分发时请保留。

旧版内置角色「企鹅 Pip」已按所有者要求移除（可在 git 历史中找回）。

_{项目地址：https://github.com/br0ny4/dsh-live2d-pet}