petween
Petween — DSH Web UI 动态宠物：智能体宠物的动画中间件（Host + Client 双端插件）
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:Traveritas/petween#1c6a8dc390c584395e81977990fe7cd4750b4657
Petween 以 petween 发布，当前版本为 1.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
正在加载相关插件…
DeepSeek Harness（DSH）Web UI 的宠物插件 —— 一个纸片动画风格的智能体宠物动画中间件。
note:插件是纯vibe出来的，如有不足，欢迎来改进❤
你只需要准备少量静态角色图（如 idle.webp / thinking.webp / happy.webp），插件的程序化 Motion Engine 会自动生成漫画感的状态切换动画（squash & stretch）与循环动画（Bounce / Sway / Breathing），并跟随 Agent 的真实运行状态自动切换姿势。
prefers-reduced-motionAnimationDefinition 数据，经同一个 Timeline Compiler / Scheduler 执行（WAAPI），无专用分支——自定义动画格式见 docs/motion-format.mdflip 翻面petween 与 client 侧 petween/client 两个 cordis 服务——动画库注册、舞台快照订阅、位置驱动租约、pose 通道、指针/拖拽/动画三类观察事件流，「提供能力、不做策略」；首个消费示例：petween-physics（拖拽甩出 + 碰壁反弹 + 地面滑动）独立全页编辑器（宠物预设、六状态过渡与循环动画、锚点调整、实时预览与动画库）：
| 设置卡片 | 宠物特写 |
|---|---|
| 设置卡片 | 宠物特写 |
示例角色为社区流行的「DeepSeek 女仆鲸鱼娘」：角色原型「溟月」由 上善无形 创作，女仆装版本由 ZipZipPipe 二次设计，依 CC BY-NC-SA 4.0 授权使用。
要求：已安装 DSH（@deepseek-ai/dsh，在 0.1.0-rc.7 上实测）、Node ≥ 20 与 pnpm。
尚未发布到 npm（dsh plugin add petween 暂不可用），从 GitHub 克隆安装：
git clone https://github.com/Traveritas/petween.git
cd petween
pnpm install
pnpm run build # 产出 lib/（仓库不含构建产物，安装前必须构建）
dsh plugin --profile web add link:/path/to/petween # link: 后指向你克隆的目录
重启 dsh web 生效。
dsh plugin --profile web update petween # 升级
dsh plugin --profile web remove petween # 卸载
卸载只移除插件本身；你的配置与图片保留在 $DSH_HOME/petween/（默认为 ~/.dsh/petween/），需要彻底删除时手动移除该目录即可。
从 dsh-motion-pet ≤ 1.1.0 升级：首次启动会自动把 $DSH_HOME/motion-pet/ 迁移为 $DSH_HOME/petween/（目录重命名；跨盘/被占用导致重命名失败时改为复制，并保留旧目录作备份）。
附属插件配套升级：1.2.0 起 cordis 服务名由 motion-pet / motion-pet/client 更名为 petween / petween/client，且不提供旧名 alias。附属插件必须改用新服务名（petween-physics 需 ≥ 0.2.0）；仍在注入旧服务名的旧版附属插件不会加载、也不会报错，请一并升级。
打开 DSH Web UI → 设置 → Petween 卡片：可快速启用/停用宠物、调整整体缩放，并查看图片导入进度。点击卡片上的「打开完整编辑器 →」（或浏览器直接访问 /petween-editor/）会在新标签页打开独立编辑器页面：
也可以直接访问 http://127.0.0.1:3080/petween-editor/（端口以你的 DSH web 配置为准）。
想快速试手感而不碰真实配置：构建后直接双击 preview/index.html 打开独立预览页（无需 DSH，随上面的克隆构建流程一并生成），还支持贴入自定义 AnimationDefinition JSON 即注册即播。
| 视觉状态 | 触发 | 默认表现 |
|---|---|---|
| 待机 idle | Agent 空闲 | 缓慢摇摆 + 呼吸 |
| 活跃 active | 生成中 / 跑工具（thinking/coding/command/working 统一为活跃，不频繁换图） | 思考：摇摆 + 随机弹跳；工作：紧凑 bounce + 呼吸 |
| 等待 waiting | 等你批准权限 / 回答问题 | 更慢的摇摆 + 弱呼吸 |
| 成功 success | 一轮任务完成 | Celebrate 进入动画，短暂停留（默认 1600ms）后回待机 |
| 错误 error | 出错 / 中断 | Deflate 进入动画，停留（默认 1800ms）后回待机 |
点击宠物会轻轻弹一下（不改变状态）。拖动宠物会记住位置；窗口缩小时宠物会被拉回视口内。
0.1.0-rc.7（本仓库开发/验收版本；插件 API 若变化以 docs/implementation-notes.md 记录为准）pnpm install
pnpm run build # tsc -b && tsdown → lib/index.js（host）、lib/client.js、lib/editor.js（独立编辑器页）、preview/preview.js
pnpm vitest run # 测试（tests/，800+ 用例）
pnpm run typecheck # 双工程类型检查
改代码后重新 pnpm run build，重启 dsh web 生效（纯 client 改动刷新页面即可）。
x-petween-expected-revision 头即可获得乐观并发控制（版本过期返回 409 REVISION_MISMATCH）MIT。例外：docs/images/ 下的示例截图包含「DeepSeek 女仆鲸鱼娘」角色形象（原型「溟月」by 上善无形，女仆装设计 by ZipZipPipe，CC BY-NC-SA 4.0），仅作演示用途，不随本项目的 MIT 许可发布。