dsh-k-on-pet

dsh-k-on-pet

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

特性

• 五名角色：平泽唯 / 秋山澪 / 田井中律 / 琴吹䌷 / 中野梓，可单选或全开
• 任意方位行走：朝任意角度走（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 profile（桌面端或 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 profile，把命令里的 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

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