前言¶
在 DSH Web UI 里加一个宠物，最常见的方式是贴一张静态图。这种方式能展示「有宠物」，但角色切换时往往是生硬跳帧，缺乏「情绪」和「反馈」。
Petween 是一个给 DSH Web UI 用的宠物动画中间件，维护者为 Traveritas。它的核心是把少量静态角色图变成漫画风格的动态表现：程序化生成的状态切换动画（squash & stretch）、循环动画（Bounce / Sway / Breathing），以及跟随 Agent 运行状态自动切换姿势的能力。
功能概览¶
Petween 的能力可以拆成几块：
-
少图驱动
- 至少一张姿势图即可工作。
- 预置六个状态槽位：待机、思考、工作、等待、成功、错误。每项可配独立图片；缺失时自动 fallback 到默认。 -
漫画式过渡与循环
- 内置 Comic Pop / Soft / Jelly / Jump / Snap / Celebrate / Deflate 等过渡预设，可调强度与时长。
- 每个状态可挂载循环动画：自定义循环 + Bounce（随机间隔）、Sway、Breathing。 -
Anchor 对齐与位置管理
- Anchor X/Y 标记角色「脚底中心」（默认 0.5 / 0.96），多张图对齐后切换姿势不会瞬移。
- 宠物可拖动、可缩放，位置持久化；并尊重prefers-reduced-motion。 -
Agent 状态联动
- 待机：Agent 空闲，缓慢摇摆 + 呼吸。
- 活跃：生成中 / 跑工具，思考时摇摆 + 随机弹跳，工作时紧凑 bounce + 呼吸。
- 等待：等待你批准权限 / 回答问题，更慢的摇摆 + 弱呼吸。
- 成功：任务完成，播放 Celebrate 动画，短暂停留后回待机。
- 错误：出错 / 中断，播放 Deflate 动画，停留后回待机。
- 点击宠物会轻轻弹一下（不改变状态）。 -
多宠物与预设
- 支持多宠物预设，每只独立保存姿势图、状态动画与整体缩放。
- 可快速切换、复制、重命名和删除。 -
Timeline 引擎与可视化编辑器
- 所有动画（内置与自定义）都是AnimationDefinition数据，通过统一的 Timeline Compiler / Scheduler（基于 Web Animations API）执行。
- 提供可视化时间轴编辑器，可管理自定义过渡/环境/互动动画，编辑轨道、关键帧、easing 与事件，并循环试播。 -
动画包与宠物包
- 动画包（Motion Pack）：自定义动画导出为单文件 JSON；导入时校验定义并自动规划 id 碰撞；包内挂载建议可在动画库一键应用到当前宠物。
- 宠物包（Pet Package）：将一只宠物连同图片、设定与挂载动画打包成 zip；导入时图片按内容哈希去重、动画碰撞改号、一步建宠并切换，并携带署名（角色/创作者/来源/许可）。 -
扩展服务
- 提供 host 侧petween与 client 侧petween/client两个 Cordis 服务，用于动画库注册、舞台快照订阅、位置驱动租约、pose 通道、指针/拖拽/动画三类观察事件流。
- 首个消费示例为 petween-physics：拖拽甩出 + 碰壁反弹 + 地面滑动。
安装与启用¶
前置要求：
- 已安装 DSH（
@deepseek-ai/dsh），在 0.1.0-rc.7 上实测。 - Node ≥ 22.18（构建工具链要求；插件运行时不受此限）。
- pnpm。
从 GitHub 克隆并构建：
git clone https://github.com/Traveritas/petween-dsh.git
cd petween
pnpm install
pnpm run build # 产出 lib/（仓库不含构建产物，安装前必须构建）
dsh plugin --profile web add link:/path/to/petween # link: 后指向你克隆的目录
重启 dsh web 生效。
典型用法¶
启用与基础设置
- 打开 DSH Web UI → 设置 → Petween 卡片。
- 可快速启用/停用宠物、调整整体缩放，并查看图片导入进度。
- 点击「打开完整编辑器 →」（或浏览器直接访问
/petween-editor/）会打开独立编辑器页面。
编辑器中的典型步骤
- 管理宠物：顶部「宠物」区可把当前配置保存为副本，或新建空白宠物；切换后下面所有面板都编辑当前宠物。
- 导入图片：在左侧选择状态（如「待机」），点击「更换图片」。支持 PNG / WebP / JPEG（JPEG 无透明背景，会提示）。推荐透明背景、近似正方形画布、角色完整的图片；不同姿势尽量保持角色视觉尺寸一致。
- 调 Anchor：Anchor X/Y 标记角色「脚底中心」（默认 0.5 / 0.96）。多张图的 Anchor 对齐后，切换姿势时角色不会瞬移。可用「图片缩放」微调大小。
- 调动画：每个状态可选进入过渡（Preset / 强度 / 时长）与循环动画（自定义循环动画 + Bounce / Sway / Breathing）；「全局」区设置默认过渡、整体缩放（0.3~4.0）、减少动态（跟随系统 / 总是 / 从不）、成功/失败停留时长。底部动画库可创建和编辑自定义时间轴动画。
- 实时预览：右侧预览区点击状态按钮即可模拟状态切换；改动即时进入预览；点击「保存修改」后写入当前宠物预设，主界面的宠物会在数秒内跟进。
独立预览（无 DSH）
构建后可直接双击 preview/index.html 打开独立预览页（无需 DSH），支持贴入自定义 AnimationDefinition JSON 即注册即播。
适用场景与注意¶
- 适合想给 DSH Web UI 增加角色反馈、用少量静态图做出漫画风格动态表现的场景。
- 插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证。
- 目前未发布到 npm，需从 GitHub 克隆并构建安装。
短结尾¶
Petween 用 WAAPI Timeline 引擎和可视化编辑器，把「几张图」变成「有情绪的宠物」，同时为后续扩展（如 petween-physics）预留了服务接口。如果你在 DSH Web UI 里需要一个有反馈的桌面宠物，Petween 是一个可以直接上手的工作流。
- 目录页：https://www.skillhub.cn/plugins/Traveritas/petween-dsh
- GitHub：https://github.com/Traveritas/petween-dsh
