前言¶

跑 DSH 的人大多遇到過同一個問題：agent 一跑就是幾分鐘甚至更久，你切到別的窗口乾活，回來第一件事是確認它現在是在跑、在等審批，還是已經報錯停了。目前的辦法只有切回 Web GUI 盯着輸出，或者翻日誌。

silverhand-dsh-pet 換了個思路：把狀態顯示交給一隻桌面寵物。它在 DSH Web GUI 右下角常駐，agent 空閒時呼吸、幹活時工作、出錯時鬧脾氣，你瞥一眼角落就知道 agent 的狀態。下面介紹這個插件的具體功能、安裝步驟和排查方法。

這是什麼¶

silverhand-dsh-pet 是一個標準的 DSH 插件包，作者是 Qiao-NEYC，代碼以 MIT 許可發佈。它在 DSH Web GUI 的 shell.overlay 層渲染一個名叫 Silverhand 的角色（帶銀色義肢的賽博朋克僱傭兵形象），固定在窗口右下角，由 DSH host 事件驅動，隨 agent 狀態做出反應。

素材原樣遷移自 Codex pet 格式（spritesheet.webp + pet.json），圖集爲 8×9、單元格 192×208，沒有重新設計。

核心功能¶

• 在 DSH Web GUI 的 shell.overlay 層渲染，固定於右下角；默認點擊穿透，只有寵物本體可交互，不影響其他操作。
• 由 DSH host 事件驅動，狀態映射如下：
• idle / running：來自 agent/status
• review：來自 tools/result
• failed：來自 agent/error
• waving：來自 agent/created 與 agent/session-start
• jumping：一個 turn 結束（running → idle）時觸發
• waiting：approval/request 打開期間
• 可拖動移動，寵物朝拖動方向行走。
• 懸停顯示當前狀態；單擊（無位移）使其跳躍。

安裝與啓用¶

這是標準的 DSH 插件包，README 給出兩種安裝方式，推薦從 GitHub 安裝。

1、編輯 ~/.dsh/profiles/<profile>/package.json，把它加進 dependencies 和 dsh.profile.bundles：

{
  "dependencies": {
    "silverhand-dsh-pet": "github:Qiao-NEYC/silverhand-dsh-pet"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "...your existing bundles...",
        "silverhand-dsh-pet"
      ]
    }
  }
}

2、在 profile 目錄運行 pnpm install（或者讓 DSH 桌面應用在啓動時安裝）。

3、重啓 DSH，寵物會出現在右下角。

另一種方式是 npm 安裝：先運行 npm i silverhand-dsh-pet，再把 "silverhand-dsh-pet" 加入 dsh.profile.bundles。注意 README 把這條路標註爲 Once published，即 npm 包發佈後方可使用，目前推薦用上面的 GitHub 依賴方式。

插件的 peerDependencies 爲 react ^18.2.0、@deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-client-runtime ^0.1.0-rc.6、@deepseek-ai/dsh-client-ui-layout ^0.1.0-rc.6、@deepseek-ai/dsh-client-ui-slots ^0.1.0-rc.6。如果遇到寵物圖像空白或缺失，先確認使用的包版本爲 1.0.1 及以上（當前版本爲 1.0.2）——從 1.0.1 起 client bundle 顯式聲明瞭佈局依賴，保證註冊前 shell.overlay 已可用。

工作原理¶

一個 DSH 插件是拆成兩半的 Cordis 插件，這個項目也一樣：

• Host 半（lib/index.js）運行在 DSH 的 Node 進程裏。它通過 import.meta.url 從自己的 assets/ 目錄讀取圖集（無論包裝在哪裏都能找到），並註冊兩個同源 HTTP 路由：
• GET /silverhand-pet/spritesheet.webp：精靈圖集
• GET /silverhand-pet/state：從 agent 事件推導出的狀態，返回 { "state": "..." }
• Client 半（lib/client.js）運行在瀏覽器裏。它註冊進 shell.overlay，每 300ms 輪詢一次 /silverhand-pet/state，並從 /silverhand-pet/spritesheet.webp 播放對應圖集行的動畫。

兩半之間只靠普通的同源 HTTP 路由通信，沒有額外的通道。

配置與排查¶

插件沒有獨立配置項，所有可調參數都是兩半代碼頂部的常量：

• lib/index.js：ROUTE_SPRITE / ROUTE_STATE，以及事件監聽器裏各狀態的瞬態時長。
• lib/client.js：ANIMS（每行動畫的行號、幀數、節奏）、STATE_ANIM（狀態到動畫的映射）、PET_W / PET_H（顯示尺寸）和 CSS 塊（位置、陰影、懸停樣式）。

排查寵物圖像空白或缺失時，按下面的順序檢查：

1、確認包版本不低於 1.0.1。
2、Client 會探測 /silverhand-pet/spritesheet.webp，如果 Host 半沒有正常提供圖集，瀏覽器控制檯會記錄路由錯誤。出現 404 或 500 表示 host 包未激活，需要重裝 bundle 並重啓 DSH。
3、狀態切換時動畫幀會重置，避免過期的幀序號在切回六幀的 idle 或 waiting 行時選中空白單元——這是內置的保護邏輯，不是故障。
4、如果寵物容器存在但透明，打開瀏覽器 Network 面板檢查 sprite 路由：正常響應應爲 image/webp、體積約 1 MB。

倉庫還帶了三個開發輔助腳本，前兩個需要 Python 3 以及 Pillow、numpy：

# 重新生成 docs/demo.gif
python scripts/make_demo_gif.py

# 輸出每行不透明單元格數量與相鄰幀差異
python scripts/analyze_frames.py

# 渲染帶標註的 contact sheet（完整版 + 放大的易混淆行）
python scripts/contact_sheet.py

適用場景與注意¶

適合兩類人：一是長期把 DSH 放在後臺、需要不切窗口就能看到 agent 狀態的使用者；二是想學習 DSH 插件兩半結構（host + client、同源 HTTP 通信、shell.overlay 註冊）的開發者，這個包體量小、結構清晰，可以當參考實現讀。

安裝前有兩點務必注意：

1、插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證。代碼部分是 MIT 許可；但 sprite 素材（Silverhand 形象）的許可未在倉庫中聲明，素材遷移自本地 Codex pet 目錄（~/.codex/pets/silverhand/），README 明確要求：在公開發布這個倉庫之前，需自行確認你持有（或已取得）sprite 與 Silverhand 形象的再分發權。個人本地使用前也建議自行評估。
2、另外，社區插件目錄是獨立站點，與 DeepSeek / 幻方沒有官方從屬關係，安裝任何第三方插件時都以源碼爲準。

結尾¶

silverhand-dsh-pet 解決的是一個很小的痛點：不用盯着窗口也能知道 agent 在幹什麼。它實現乾淨——兩個 HTTP 路由加一個 300ms 輪詢的客戶端，事件到狀態的映射一目瞭然，既是小玩具，也是一份可以照着寫的 DSH 插件樣例。

• 目錄頁：https://www.skillhub.cn/plugins/Qiao-NEYC/silverhand-dsh-pet
• GitHub：https://github.com/Qiao-NEYC/silverhand-dsh-pet