前言¶

DeepSeek Harness（DSH）把智能體能力拆成可安裝的插件：會話裏能調用的工具、設置頁、HTTP 接口都可以掛在同一套 profile 上。若你希望角色不只在聊天窗口裏出現，而是常駐桌面、能說話、能抬眼點頭換表情，通常要自己拼 Electron 浮窗、動作引擎和 AI 回調。dsh-live2d-pet 把 鯨語 jingyu-live2d-agent 的舞臺裁成透明桌寵外殼，並向 DSH 註冊一組工具，讓模型驅動氣泡與動作。模型自備：插件包不含 Live2D 模型文件；示例「大肥魚」公皮禁止重新分發，需按原作者許可自行放置 .moc3 與 model3.json。

這是什麼¶

維護者 11454zaw，社區目錄分類爲「趣味換裝」。當前版本 0.2.0（MIT，僅覆蓋本倉庫代碼）。插件不打包鯨語源碼，也不打包模型；分工是：鯨語負責渲染、動作編譯、物理與口型；本插件負責 Electron 外殼、氣泡與聊天文件、把動作計劃 POST 給鯨語，並提供四個 DSH 工具與設置頁。

核心功能¶

DSH 工具¶

裝完並重啓 DSH 後，工具列表會出現：

• live2d_pet_status：外殼是否在跑、舞臺是否通、模型名稱等
• live2d_pet_say：顯示一句氣泡（默認停留 9 秒，可在配置裏改）
• live2d_pet_perform：組合語義動作（抬眼、點頭、搖頭、偏頭、笑、眨眼、表情、手勢），可帶臺詞
• live2d_pet_restart：重啓外殼

設置頁（設置 → 桌寵）¶

無需開終端即可調整外觀與行爲：窗口寬度 260–900 px、不透明度 0.25–1、本機頭像路徑、視線跟隨、待機開關與間隔（最短 8–300 秒、隨機範圍）、氣泡停留 1–60 秒、九個待機動作白名單（全不勾等於全開）。啓動相關項包括鯨語舞臺地址、Electron 路徑、.ps1/.cmd 啓動腳本、開機自啓。頁面還提供 23 個表情、3 套手勢與常用組合的動作試玩，以及「說一句」輸入框。保存並套用會寫配置、寫 shell/pet-settings.json 並重啓外殼（舞臺不動）。

HTTP 接口¶

均要求本機同源並通過 DSH 信任柵欄：GET /api/live2d-pet/status；POST 的 /start、/restart、/config、/apply、/perform、/say（0.2.0 起新增 /config、/apply、/perform、/say，舊路由仍保留）。

桌寵外殼交互¶

透明浮窗、置頂、無任務欄圖標；拖左上角頭像移動，點擊可收起爲 84×84 圓頭像。右鍵可切換置頂、鼠標穿透、預設大小、位置、打開完整工作臺等。快捷鍵含 Ctrl+Alt+L 穿透、Ctrl+Alt+T 置頂、Ctrl+Alt+-/= 縮放、Ctrl+Alt+H 收起。氣泡讀 $DSH_HOME/live2d-pet/shell/say.txt；聊天面板使用 chat.jsonl 與 stats.json。

安裝與啓用¶

前置條件¶

1. 鯨語按自身 README 啓動，http://127.0.0.1:61942/ 可訪問且模型能顯示。
2. Electron：DSH 桌面版自帶 $DSH_HOME/electron/electron.exe，或在配置裏用 electron 字段指向本機可執行文件。
3. DSH ≥ 0.2.0-rc.2（作者在 0.2.1-rc.5 上測過）；Node ≥ 20.18；profile 支持 desktop 與 web（桌寵外殼以 desktop 場景爲主）。

安裝命令¶

下面命令來自倉庫 README，請按你的路徑替換本地目錄：

# 本地目錄
dsh plugin --profile desktop add file:/path/to/dsh-live2d-pet

# 或者從 npm（發佈後）
dsh plugin --profile desktop add dsh-live2d-pet

安裝後重啓 DSH。插件以當前 DSH 進程權限運行，安裝前建議閱讀源碼與 LICENSE，並確認鯨語與模型各自的許可條款。

主配置¶

首次加載會在 $DSH_HOME/live2d-pet/config.json 建目錄；缺省示例：

{
  "stageUrl": "http://127.0.0.1:61942",
  "electron": "",
  "launchScript": "",
  "autoStart": false,
  "avatar": "",
  "width": 435,
  "opacity": 1,
  "follow": true,
  "idleEnabled": true,
  "idleMinMs": 22000,
  "idleSpreadMs": 45000,
  "idleActions": [],
  "bubbleHoldMs": 9000
}

stageUrl 爲鯨語地址；launchScript 在設置頁點「全部拉起」時先執行；idleActions 空數組表示允許全部待機動作。外殼另維護 shell/pet-window.json（位置、置頂、穿透）與 shell/pet-settings.json（設置頁寫入、供外殼讀取）。

典型用法¶

1. 按前置條件拉起鯨語與模型，安裝插件並重啓 DSH。
2. 打開 設置 → 桌寵，確認舞臺在線後點「全部拉起」或「只重啓寵物窗」；需要一鍵連舞臺時配置 launchScript。
3. 在會話中讓智能體調用 live2d_pet_say 或 live2d_pet_perform，或在設置頁動作區點試玩、在「說一句」框輸入文字。
4. 改外觀或待機節奏後點 保存並套用；僅持久化不重啓外殼時用 只保存。

動作能力取決於模型與舞臺開放的語義動作、23 個表情名與三套手勢（舉手 hand_on_chest、豎手指 point、狗尾草 grass）；不能任意播放未開放的 motion 文件。

適用場景與注意¶

適合已在 DSH desktop profile 上跑智能體、並希望桌面 Live2D 與工具聯動的開發者或個人使用者。社區插件目錄 SkillHub 上的 dsh-live2d-pet 與 DeepSeek / 幻方無官方從屬關係，安裝來源以你信任的倉庫或 npm 包爲準。

務必知曉的邊界：

• 不含實時回話器：倉庫內 realtime.mjs 未打進插件，需自行對接或等待後續版本。
• 改插件 JS 須重啓 DSH；熱重載不覆蓋插件自身代碼。
• DSH 會話環境帶 ELECTRON_RUN_AS_NODE=1，插件啓動外殼時會清除；手工啓動外殼時需自行處理。
• Cubism SDK、鯨語與模型版權各自獨立，MIT 只覆蓋本插件倉庫。

結尾¶

dsh-live2d-pet 把鯨語舞臺裁成桌面透明浮窗，並用 DSH 工具與設置頁把「說話、表演、重啓、狀態查詢」接到同一套 Harness 裏；模型與舞臺仍由你本地準備與授權。詳情與更新見 GitHub：11454zaw/dsh-live2d-pet，目錄頁見 SkillHub 插件頁。