轻音桌宠 sunjay-lee/dsh-k-on-pet

dsh-k-on-pet

把《K-ON! 轻音少女》的五位角色挂进 DeepSeek Harness 的 Web 界面：任意方位走动、出界回绕、待机/单击/双击各有动作，茶桌可以拖动，角色在外溜达久了会自己走回座位。

在 DSH 里

特性

- 五名角色：平泽唯 / 秋山澪 / 田井中律 / 琴吹䌷 / 中野梓，可单选或全开
- 任意方位行走：朝任意角度走（96 px/s，1.5× 下约 144 px/s），四边都能出界回绕（往下走没了从上面下来）
- 待机：每个角色自己的原地动作；待机 2.5–6.5 秒后开始走动，单次 160–560 px
- 单击：随机播该角色的反应动作 3 秒，气泡显示正在播放的那条语音的中文
- 双击：跳舞，跳完回待机，1.5–3.5 秒后自己走起来
- 拖拽 / 甩出：拎起、抛物线、落地弹跳，位置自动记忆
- 茶桌：默认停在输入框上方，可拖动、可固定；把角色拖到桌上会自动入座；右键茶桌可锁定位置、全员入座/离座
- 自动回位：角色在外溜达超过设定时长，会自己走到座位坐下（0–30 分钟可调，0 = 关闭）
- 语音与字幕：点击/双击播放原版语音，气泡同步显示该条语音的中文（137 条逐条转写校对）
- 关怀提醒：每 50 分钟提醒喝水/起身；闲置 4 分钟打瞌睡
- 不挡操作：只有宠物本体接收指针事件，其余区域点击穿透
- 本地存储：偏好存在浏览器 localStorage，支持导出/导入 JSON

预览

安装

要求：DSH 0.2.x 的 Web 配置档（桌面端或 dsh web）。

dsh plugin --profile web add github:sunjay-lee/dsh-k-on-pet

装完把 "dsh-k-on-pet" 加进 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles，重启 DSH。
桌面端用的是 desktop 配置档，把命令里的 web 换成 desktop。

动作行与 actions 字段

图集从原程序解码后统一为 96×96 网格（琴吹䌷、中野梓的原始帧宽不同，已做居中裁切），每个角色用哪一行动作写在 assets/characters/<id>/meta.json 的 actions 里：

{
"actions": {
"idle": 6, "walkLeft": 5, "walkRight": 4,
"click": [3, 1], "dance": 0, "sleep": 1, "held": 2
}
}

- walkLeft / walkRight：原版左右各有一套步态，按行进方向切换，不做运行时镜像
- click：数组，单击时随机取一个
- 想调整某个角色的动作，只改这一个字段即可；scripts/check.mjs 会校验行号是否越界、该行是否真的有有效帧

设置

设置 → K-ON! 桌宠：

| 分组 | 项 | 说明 |
| 显示角色 | 五人开关 / 全部显示 / 全部隐藏 | 可同时显示，各自独立坐标 |
| 桌子 | 显示桌子 | 茶桌开关；关掉同时清空座位 |
| | 自动回位 | 0–30 分钟；在外超过这个时长会自己走回座位，0 = 不回位 |
| 外观与行为 | 大小 / 行走动画 FPS / 其他动画 FPS / 语音 / 随机闲聊 / 溜达 / 朝向反转 / 关怀提醒 | 见上文 |
| | 行走动画 FPS | 2–24；只控制迈步动画，移动速度仍由「行走速度」单独控制 |
| | 其他动画 FPS | 2–24；控制待机、点击、拖拽、睡眠等非行走动画 |
| 备份与恢复 | 导出 / 导入 | 偏好存为 JSON，可跨浏览器迁移 |
| 位置与重置 | 初始化 / 重置所有位置 / 恢复默认设置 | 清空坐标与运行状态 |

右键角色：隐藏这只 / 回到右下角。右键茶桌：固定位置 / 全员入座 / 全员离座 / 恢复默认位置。

工作原理

- 宿主半（lib/index.js）：把 assets/ 挂到只读路由 /dsh-k-on-pet/*，GET/HEAD，做了目录穿越防护，不读写工作区、不联网。
- 浏览器半（lib/client.js）：通过 shell.overlay 挂浮层、settings.section 挂设置页；每个角色一块 Canvas，所有角色共享一条 requestAnimationFrame 时间线。
- 纯逻辑（src/core.cjs）：走路规划、出界回绕、抛物线物理、设置归一化、动画帧推进，可在 Node 里直接单测。

开发

npm run build # 重建 lib/client.js（改完 src/ 必须跑）
npm run check # 静态自检：清单、素材、动作行、构建同步
npm run test:unit # 纯逻辑单测（25 项）
npm test # build + check + 单测
npm run test:smoke # 可选：无头 Chrome 冒烟测试（需要 CHROME_BIN）

改了 src/ 却忘了 npm run build，DSH 读到的还是旧的 lib/client.js —— 自检会直接报错。

兼容性

| 项 | 说明 |
| DSH | 0.2.0-rc.1 / 0.2.0-rc.2 / 0.2.1-rc.2 |
| profile | web（桌面端或浏览器） |
| 平台 | Canvas 2D、WebAudio、Pointer Events、localStorage |
| 不适用 | TUI / headless profile |

已知限制

- 角色只朝左右两套步态，斜走/上下走时按水平分量选边，接近竖直时沿用上一次朝向
- 回位是直线走，不做寻路，可能贴着桌边穿过
- 动作行与语音仍是随机配对：字幕保证与语音一致，但不保证与动作一致
- 拟声/笑声/含糊音节无法精确转写，字幕用近义文本代替

版权

- 代码：MIT，见 LICENSE
- 角色图像、语音、茶桌：不属于 MIT，详见 THIRD_PARTY_NOTICES.md

本项目是非官方同人作品，与京都动画、芳文社、原作者及原版程序作者均无关联。