在 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 桌面伴生入口。這意味着插件可以在桌面端應用中複用相同的物理邏輯與服務接口。
