前言¶
在 DeepSeek Harness（DSH）裏跑智能體時，主窗口往往被終端、編輯器或瀏覽器擋住，很難一眼看出當前項目是否在跑、是否在等審批。社區裏也有在 DSH 窗口內嵌桌寵的做法，但會佔用界面空間。下面介紹維護者 7AAAAAH 發佈的 dsh-pet-gujiguji：一隻只在桌面上浮動的鳥形桌寵，隨 Host 寫入的狀態顯示任務氣泡，且不在 dsh 窗口內再渲染第二隻寵物。
這是什麼¶
GujiGuji 是面向 DSH 的輕量桌面伴侶，README 描述爲「a lightweight Codex-style desktop pet for DeepSeek Harness」。插件分類在社區目錄中爲「趣味換裝」；核心用途是：跨顯示器懸浮、僅在 agent 工作時展示當前項目與活動，並與 DSH 的 running / waiting / failed / idle 信號對齊。
核心功能¶
狀態與任務氣泡¶
Host 根據會話與事件映射桌寵行與標籤（資料中的 Status mapping）：
| 來源信號 | 寵物狀態 | 氣泡標籤 |
|---|---|---|
任意 agent 爲 running，或會話存在未關閉的 turn |
running |
Running |
存在打開的 approval/request |
waiting |
Waiting |
4 秒內出現 agent/error |
failed |
Failed |
| 其他 | idle |
無氣泡 |
空閒時不顯示氣泡，也不顯示 “idle” 文案。Codex 風格的任務氣泡固定爲 284×65，長活動文本橫向滾動。
交互與物理¶
- 可在 Windows 虛擬桌面上拖動到各顯示器；鬆手後自然下落，快速甩動可在有界速度、重力、撞牆、地面摩擦與短暫着地 squash 下投擲。
- 超過點擊閾值拖動會進入可見的起飛週期；空中時任務氣泡暫時隱藏，落地後恢復。
- 空閒時每 30–75 秒隨機手勢（可調 15–150 秒），且避免連續重複同一手勢。
- 單擊：隨機 head tilt、head stretch、spread wings 或 side-wing wave，起止均爲站立姿。
- 雙擊：切換 dsh 窗口顯隱；若任務氣泡已最小化，同一雙擊可恢復；並播放隨機 head tilt 或 head stretch。
- 右鍵：設置或隱藏桌寵。
- dsh 一輪 成功結束 後桌寵輕跳兩下；失敗、中斷、token 上限結束不觸發。
顯示與設置¶
- 寵物與氣泡按顯示器工作區避讓邊緣，不跨雙屏邊界；邊距隨當前姿勢而非始終按最寬翼展預留。
- 設置項包括：大小、透明度、投擲力度、空閒間隔、位置鎖定、減少動效；行爲頁可恢復默認右下角位置。
- 精靈幀對齊統一腳線；翼展手勢使用完整源圖，生成器不單獨裁切或旋轉單翼。
架構要點¶
- DSH Host 寫入
desktop/state.json；desktop/pet-window.pyw輪詢並用 tkinter + Pillow 渲染獨立桌面窗口。 - Host 可啓動桌寵，但桌寵進程可在 Host 重啓後仍存活；
desktop/setup-startup.ps1可安裝登錄快捷方式獨立啓動。 - 啓動器優先使用最新的打包
desktop/dsh-pet-gujiguji-<version>.exe，Windows 用戶可無 Python 運行；若無 exe，需 Pillow 與 tkinter，Python 解析順序爲DSH_PET_PYTHON、pyw.exe、pythonw.exe、py.exe、python.exe。 - 用戶設置從
desktop/default-settings.json種子化到 AppData，升級插件不覆蓋個人偏好。 client.js爲兼容墊片，有意不在 dsh 窗口內註冊寵物。
從較早版本升級時，會自動從 dsh-light-feather 或 dsh-mint-budgie 遷移位置與設置。
安裝與啓用¶
DSH 生態裏插件通過社區目錄或 npm 包安裝；當前僅支持 Windows。
1、在 DSH 插件市場搜索 dsh-pet-gujiguji 安裝，然後重啓 dsh。
2、或安裝公開 npm 包（desktop profile）：
dsh plugin --profile desktop add dsh-pet-gujiguji
安裝後重啓 dsh。
若走 Python 路徑而非 exe，需安裝 Pillow：
py -m pip install Pillow
資料中 package.json 標明插件版本 0.8.6、許可證 MIT、Node >=20。
典型用法¶
安裝並重啓 dsh 後，Host 會橋接桌面進程；桌寵浮在其它窗口之上，agent 工作時看氣泡即可知 Running / Waiting / Failed。日常操作：
- 拖動擺放位置；需要專注時可右鍵隱藏。
- 雙擊快速顯隱 DSH 主窗口。
- 右鍵打開設置，按顯示器與動效偏好調節大小、透明度、投擲與空閒間隔。
禁用方式：從當前 profile 的 package.json 裏 dsh.profile.bundles 移除 dsh-pet-gujiguji，再重啓 dsh。
適用場景與注意¶
適合在 Windows 上長期使用 DSH、希望桌面層反饋 agent 狀態、又不想讓 dsh 窗口內再嵌一層寵物的開發者。
安裝前建議閱讀 GitHub 倉庫 源碼與 MIT 許可證。插件隨當前 dsh 進程權限運行，桌面 overlay 與開機腳本會啓動獨立進程，使用前請確認環境與安全策略。社區插件目錄 SkillHub 條目 與 GitHub 無 DeepSeek / 幻方官方從屬關係，僅爲社區分發渠道。
物理拖拽/投擲與後續規劃見倉庫內中文文檔 docs/DEVELOPMENT-PLAN.zh.md。
結尾¶
dsh-pet-gujiguji 把 Codex 式桌面桌寵接到 DSH Host 狀態上：獨立窗口、任務氣泡與手勢反饋，而不佔用 dsh 內嵌 UI。需要安裝命令與行爲細節時，以 README 爲準。
- 社區目錄：https://www.skillhub.cn/plugins/7AAAAAH/dsh-pet-gujiguji
- GitHub：https://github.com/7AAAAAH/dsh-pet-gujiguji
