前言¶
DeepSeek Harness (DSH) 提供了 Web 界面來管理智能體。開發過程中，觀察 Agent 狀態的運行和完成有助於調試和體驗。DSH 的理念是“一切皆插件”，這意味着開發者可以添加自定義組件。Kun Like 桌寵是一個靜態 Bundle 插件，將動態精靈動畫集成到 DSH 的 Web 界面中。
插件介紹¶
Kun Like 桌寵由 GangLongYu 維護，遵循 MIT 許可證。它通過在 DSH Web 界面右下角渲染精靈動畫，將 Agent 的抽象狀態轉化爲可視化的角色動作。插件不再依賴本地絕對路徑素材，而是通過靜態 Bundle 自動裝配。
核心能力¶
- 9 種精靈動畫：沿用 8 列 × 9 行、每格 192 × 208 的素材契約。
- 狀態感知：監聽
agent/status，並以agents.list()輪詢兜底，感知運行和完成狀態。 - 狀態映射：結合
tools/execute、approval/request、agent/request-error顯示工作、等待和失敗狀態。 - 系統音效：任務完成時由 Host 播放系統提示音；Windows、macOS、Linux 均有對應實現。
- 交互功能：桌寵可拖動；點擊會揮手並播放互動語音。
- 調試工具：提供
kun_pet_debug工具以及/kun-pet/state調試接口。
狀態與動作對應¶
| Agent 狀態 | 桌寵動作 | 氣泡文案 |
|---|---|---|
| 工具執行中 | 專注幹活 | 努力工作中… |
| 回合運行但沒有工具執行 | 思考 | 思考中… |
| 等待回覆或審批 | 期待 | 在等你回覆哦~ |
| 請求出錯 | 難過 | 嗚…出錯了 (._.) |
| 回合完成 | 揮手/跳躍並播放提示音 | 完成啦！你幹嘛~哎喲 |
| 空閒 | 呼吸待機 | 休息中~ 有事叫我 |
安裝與啓用¶
使用官方 CLI 安裝插件到 web profile。
npx @deepseek-ai/dsh plugin --profile web add github:GangLongYu/dsh-kun-like-pet
npx @deepseek-ai/dsh web
安裝完成後，打開終端輸出中的 Web 地址，桌寵應顯示在右下角。Host 提供自檢接口用於驗證：
- http://127.0.0.1:3080/kun-pet/state
- http://127.0.0.1:3080/kun-pet/spritesheet.webp
- http://127.0.0.1:3080/kun-pet/voice.mp3
如果 3080 端口被佔用，DSH 會自動使用其他端口，請以啓動日誌爲準。
本地開發¶
若需修改源碼，克隆倉庫後按步驟構建。
1、克隆倉庫並安裝依賴：
git clone https://github.com/GangLongYu/dsh-kun-like-pet.git
cd dsh-kun-like-pet
npm ci
2、構建產物並測試：
npm run build
npm test
3、安裝到 DSH：
npx @deepseek-ai/dsh plugin --profile web add .
npx @deepseek-ai/dsh web
修改 plugin/src/ 後必須重新執行 npm run build，並把更新後的 plugin/lib/ 一併提交。
環境要求與注意事項¶
- Node.js：需要 22.19 或更高版本。
- DeepSeek Harness：建議 0.1.0-rc.6。DSH 仍處於開發預覽階段，升級後若 API 有破壞性變化，請先運行本倉庫測試。
- 音效依賴：
- Linux：依賴可用的
ffplay。 - Windows：使用 WPF
MediaPlayer。 - macOS：使用
afplay。 - 素材授權：代碼使用 MIT License，但
assets/中的素材（圖像、語音）爲粉絲二創，不隨代碼許可自動獲得商業使用授權。 - 權限：插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證。
技術細節¶
插件採用 Host/Client 分離架構。
- Host (
plugin/lib/index.js)：負責事件監聽（如tools/execute）、狀態輪詢、音效播放以及/kun-pet/state路由。 - Client (
plugin/lib/client.js)：通過shell.overlay注入 React 組件，實現桌寵渲染、拖動和點擊交互。
目錄結構包含 cordis.patch.yml 用於 profile 安裝補丁，以及 assets/ 目錄存放精靈圖和語音文件。
