在 DSH（DeepSeek Harness）生态中，petween 插件负责动画的编排与调度。但宠物通常只是静态展示或简单的位移，缺乏交互感。petween-physics（包名 petween-physics）作为 petween 的附属插件，为宠物增加了物理引擎层。它将宠物视为受重力影响的实体，支持拖拽投掷、墙壁反弹、地面滑动与抓回等物理行为。
核心功能¶
该插件提供了一套完整的抛掷物理逻辑，核心能力如下：
- 拖拽投掷：在拖拽过程中，插件会在采样窗口内估算手速。松手瞬间，宠物会根据估算的速度起飞。
- 运动模拟：宠物受重力影响下坠，并在屏幕四壁反弹。物理引擎确保宠物始终在视口内运动。
- 碰撞反馈：碰壁时，插件可播放
squash（挤压变形）动画，或切换至特定的pose图片，并在保持一段时间后恢复。 - 地面逻辑：当反弹高度低于设定阈值时，宠物会转为地面滑动模式，受地面摩擦力减速，直至停稳。若松手速度过低，则直接停放不起飞。
- 交互控制：用户可以在飞行中随时抓回宠物。宠物落定后，位置会自动持久化保存；页面隐藏或会话结束时，宠物会立即落定。不处于飞行状态时，插件不占用位置控制权。
安装与启用¶
使用前需满足以下环境要求：
- 依赖主插件：必须先安装
petween（版本 ≥ 1.2.0）。 - 构建工具：Node.js 版本 ≥ 22.18，以及
pnpm。
安装步骤如下：
- 克隆仓库到本地：
git clone https://github.com/Traveritas/petween-physics.git
cd petween-physics
- 安装依赖并构建（仓库不含构建产物，安装前必须执行）：
pnpm install
pnpm run build
- 通过 DSH 注册插件（
link:指向本地克隆目录）：
dsh plugin --profile web add link:/path/to/petween-physics
- 重启
dsh web使配置生效。
配置与参数¶
所有物理参数均可在运行时通过设置卡片调整，并自动落盘。
设置卡片位置¶
打开 DSH 设置面板，在主插件 “Petween” 卡片之后，可找到 “Petween Physics” 卡片。
配置文件¶
配置文件存储在 ~/.dsh/petween-physics/config.json（即 $DSH_HOME/petween-physics/config.json）。从旧版本 dsh-motion-pet-physics 升级时，首次启动会自动将配置迁移至此目录。
主要参数¶
卡片内包含以下分组配置：
* 物理：重力加速度、弹性系数、水平空气阻尼、起掷倍率、落定速度阈值等。
* 碰壁动画：开关变形动画、选择动画 ID、是否打断当前动画。
* 碰壁切图：开关图片切换、选择 pose 槽位、保持时长。
* 落地滑动：最小反弹高度、地面摩擦力、滑动动画 ID。
* 碰撞箱：是否忽略透明像素、透明像素阈值。
* 高级：采样窗口、去抖时间、容差等。
卸载说明¶
卸载插件不会删除已注册的默认反弹动画（user:physics-bounce-pop），这些动画会保留在主插件 petween 的动画库中，由用户在主插件编辑器中管理。
工作原理¶
该插件采用双宿主架构：
- Host 侧：负责注册 HTTP API（
GET/PUT /api/petween-physics/config）、原子化写入配置文件，以及在服务可用时向主插件动画库注册默认动画。 - Client 侧：负责物理计算（半隐式欧拉积分）和交互逻辑。它通过
slots系统与主插件通信，订阅拖拽手势并申请位置控制权，计算反弹高度以决定是继续弹跳还是进入滑动模式。
开发与扩展¶
插件的源码结构清晰，分为 Host 和 Client 两个入口，便于维护。
开发命令¶
pnpm test # 运行测试
pnpm run typecheck # 类型检查
pnpm run build # 构建 lib/
双宿主形态¶
除 DSH Web 插件形态外，插件还支持 Petween Desktop 桌面伴生入口。这意味着插件可以在桌面端应用中复用相同的物理逻辑与服务接口。
