dsh-pet-in-frame

DeepSeek Harness (DSH) 的插件生態支持開發者通過插件擴展 Web 界面的功能。在 Web 界面操作智能體時，代理的內部狀態（如思考、搜索、運行命令）往往難以直觀感知。dsh-pet-in-frame 是一個插件，它將一個桌面寵物懸浮在 Web GUI 的角落，並跟隨智能體的狀態切換姿態。

這是一個單包插件，由 HarmlessFunny 維護。它將代理的生命週期狀態映射爲可視化的動畫或靜態圖片，解決了 Web 界面反饋抽象、難以實時監控工具調用進度的問題。

核心功能¶

該插件通過監聽代理的生命週期事件來控制寵物姿態。

• 狀態響應：寵物會根據智能體當前的動作切換姿態，包括 think（思考）、search（搜索）、learn（學習）、read（閱讀）、bash（命令行）、edit（編輯）、plan（規劃）、ask（提問）、subagent（子代理）、cordis（服務調用）、permission（權限）、error（錯誤）、idle（空閒）和 sleep（睡眠）。
• 子代理隔離與指示器：只有主代理的活動會驅動寵物的姿態。當子代理運行時，寵物圖像內部會顯示一個徽章指示器。來自子代理的工具調用或錯誤事件不會影響主代理的狀態。
• 命令徽章：當主代理運行前臺 bash 或 pwsh 工具時，寵物切換至命令姿態，並在圖像內固定顯示對應的徽章（如 bash_comp 或 pwsh_comp）。
• 後臺作業跟蹤：支持對後臺運行的 bash 或 pwsh 命令進行作業跟蹤。命令成功、失敗或退出時，寵物會根據狀態更新顯示。
• 交互與性能：客戶端每 250 毫秒輪詢一次狀態，姿態切換延遲約 0.25 秒。支持拖拽（帶視口限制）、懸停縮放（100-320px）、點擊查看氣泡、隱藏和恢復。支持熱重載，修改圖片或 manifest.json 後約 3-4 秒內生效。
• 無構建步驟：基於純 JavaScript 實現，無需額外構建配置。

安裝與啓用¶

安裝前需確保已運行 dsh web profile，且系統中有 pnpm。

安裝命令：

dsh plugin --profile web add dsh-pet-in-frame

安裝完成後，必須重啓 dsh web 進程，新的插件條目纔會加載。插件的 cordis.patch.yml 會自動插入加載行，無需手動編輯 cordis.yml。

配置與使用¶

資源目錄配置¶

圖片資源默認位於插件包的 assets/ 目錄。也可通過環境變量 DSH_PET_ASSETS 或加載器的 config.assetsDir 指定其他路徑。

約定模式（零配置）¶

將圖片文件放置在 assets/ 目錄下，文件名需與動作名一致（擴展名支持 png/jpg/jpeg/gif/webp/svg）。

assets/
├── default.png   # 空閒時的默認姿態
├── think.png     # 思考狀態
├── search.png    # 搜索或閱讀狀態
├── bash.png      # 命令執行狀態（可選）

Manifest 配置（顯式控制）¶

若需更精細的控制或幀動畫，可創建 manifest.json：

{
  "default": "default.png",
  "think": { "imgs": ["think1.png", "think2.png"], "delay": 1000 },
  "sleep": { "imgs": ["sleep1.png", "sleep2.png"], "delay": 500 },
  "bash": "bash.png"
}

注意事項¶

• 後臺作業跟蹤：若要支持後臺命令的作業跟蹤，需要加載器實現 ctx.jobs.onJobDone 接口。
• 權限：插件以當前 dsh 進程的權限運行，使用前請檢查源碼與許可證（MIT）。
• 子代理行爲：Shell 調用若發生在子代理內部，不會觸發命令徽章；只有主代理的工具調用纔會驅動寵物姿態。

總結¶

dsh-pet-in-frame 通過簡單的靜態圖片或幀動畫，爲 DSH 的 Web 界面提供了直觀的代理狀態反饋。它通過約定優於配置的方式降低了使用門檻，同時支持熱重載和豐富的交互，適合需要在開發過程中實時監控智能體行爲的場景。

• GitHub 倉庫
• DSH 生態目錄