前言¶
在 DeepSeek Harness（DSH）裏寫提示、等模型回覆時，界面往往是靜態的：你知道 AI 在忙，但視覺反饋有限。社區插件 dsh-pet-lucky 把一隻會動的 3D 虎皮鸚鵡「Lucky」掛在 Web UI 右下角，並根據你是否在打字、消息是否已發出、答案是否到達來切換待機、走路、奔跑和飛行動作。下面介紹它是什麼、怎麼裝、日常怎麼用，以及 3D 不可用時的兜底行爲。
這是什麼¶
dsh-pet-lucky（倉庫 don2ccc/dsh-pet-lucky）由維護者 don2ccc 發佈，在 SkillHub 插件目錄 中歸類爲 趣味換裝。簡介寫明：以作者家虎皮鸚鵡 Lucky 命名，是一隻面向 DeepSeek Harness Web UI 的 3D 桌面寵物。插件在客戶端側運行（package.json 中 dsh.client.platform 爲 web，immediately: true），不依賴 ESP32 等外部硬件。
核心功能¶
經過上面的步驟理解定位後，可以把能力與交互分開看。
與 Harness 狀態聯動的動作¶
鸚鵡會隨你在界面裏的行爲切換動畫（剪輯之間約 0.26 秒交叉淡入淡出，非硬切）：
| 你在做什麼 | 它在做什麼 |
|---|---|
| 沒有操作 | Idle (folded wings) 收翅站立，輕輕呼吸晃動 |
| 在輸入框打字 | Walk (folded wings) 走 |
| 消息已發出、AI 在幹活 | Run (folded wings) 跑 |
| 把它拖起來 / 答案到達 | Fly 張開翅膀飛 |
相機爲 3/4 視角（方位 44°、俯角 12°）；飛行時會輕微拉遠，避免翅膀被裁切。
桌面寵物式交互¶
- 可拖動位置。
- 單擊可聽一句臺詞；右鍵可觸發「播報」。
- 約 4 分鐘無操作會打瞌睡；窗口切走再回來會有歡迎行爲。
3D 與 2D 兜底¶
- 正常路徑使用 WebGL 2 渲染 GLTF 模型（內聯 three.js r147）；模型帶骨骼，實際使用 4 段動畫（收翅待機、收翅走、收翅跑、飛）。
- 首次顯示需聯網：從 Polyfork CDN 下載約 6.1 MB 模型，之後緩存在 IndexedDB，不再重複下載。
- 若 WebGL 不可用或模型下載失敗，會自動退回內聯的 2D 立繪（base64 WebP），界面不會空白，也不會拖垮主 UI。
安裝與啓用¶
先做環境確認，再安裝插件。
環境要求¶
- 使用 DeepSeek Harness 的 Web UI（桌面版或
dsh web）。 - 顯卡需支持 WebGL 2（README 說明 2015 年之後多數集顯/獨顯可滿足）。
- 首次展示 3D 模型時需要網絡，用於拉取 CDN 資源。
安裝命令¶
命令行安裝（與 README 原文一致）：
dsh plugin add github:don2ccc/dsh-pet-lucky
也可使用完整 GitHub 地址：
dsh plugin add https://github.com/don2ccc/dsh-pet-lucky
不用命令行時：設置 → 插件 → 添加插件，在輸入框填入 github:don2ccc/dsh-pet-lucky。
裝完後須 完全退出 DeepSeek Harness 再重新打開（插件在啓動時加載，熱更新不生效），鸚鵡會出現在右下角。
卸載：
dsh plugin remove dsh-pet-lucky
典型用法¶
安裝並重啓後，無需額外配置即可使用：在右下角觀察鸚鵡隨打字與回覆節奏變化即可。
改臺詞與顯示名字¶
所有可見文案在倉庫 tools/3d/lines.json，含中文、英文兩套字段：名字、點擊臺詞、打字碎碎念、喚醒/完成/重連/播報等。新增 line9、line10 等鍵會被自動發現，無需改業務代碼。
若要從源碼改文案並寫回構建產物，README 給出的流程爲：
git clone https://github.com/don2ccc/dsh-pet-lucky
cd dsh-pet-lucky
# 編輯 tools/3d/lines.json
python tools/3d/apply_lines.py # 寫回 client.js，自動備份並校驗
dsh plugin add /absolute/path/to/dsh-pet-lucky # 用本地目錄替換線上版本
再重啓應用。注意：line1..line8 與 chatter1..chatter8 爲必填，缺任一項時 apply_lines.py 會拒絕寫入。
想調整動作快慢、機位、狀態映射，可編輯 client.js 中的 CLIP_SPEED、CAMERA、const sceneState 等常量；說明見 tools/3d/README.md。改源碼後可用 python tools/3d/build3d.py 重新生成 client.js。
適用場景與注意¶
適合誰：長期在 DSH Web UI 裏對話、希望用輕量視覺反饋感知「空閒 / 輸入中 / 模型工作中 / 回答到達」的開發者或個人用戶。
權限與信任：插件隨當前 DSH 進程在瀏覽器環境中執行前端邏輯；安裝前建議閱讀倉庫源碼與 MIT 許可證（package.json 標註版本 1.0.0，作者 don2ccc）。社區目錄 SkillHub 爲獨立生態站點，與 DeepSeek / 幻方無官方從屬關係；DSH 本身奉行「一切皆插件」，本文介紹的是社區貢獻而非官方內置功能。
排查提示：
- 裝了沒反應：確認是否完整重啓而非僅刷新頁面。
- 變成不動 2D 圖：3D 路徑未走通；可向
localStorage鍵名dsh-pet:trace查看加載日誌（WebGL、下載、渲染哪一步失敗），提 issue 時可附上。 - 首幀等待一兩秒：首次下載模型屬正常現象。
3D 模型致謝：Cove Parrot by Polyfork，CC BY 4.0；渲染棧爲 three.js r147（MIT）。完整第三方聲明見倉庫 THIRD-PARTY-NOTICES.md。
結尾¶
dsh-pet-lucky 把狀態機式的動畫和可拖動的桌寵交互疊在 DSH Web UI 上，並在 WebGL 或 CDN 不可用時退回 2D，適合作爲寫 Harness 時的伴生小部件。目錄頁：https://www.skillhub.cn/plugins/don2ccc/dsh-pet-lucky；源碼與安裝說明：https://github.com/don2ccc/dsh-pet-lucky。
