前言¶
DeepSeek Harness（DSH）採用插件化架構，智能體在後臺執行任務時，開發者容易忽略任務進度或異常。zzx-dear/dsh-capybara-notify 插件通過桌面通知中心解決這一問題。它將告警、會話狀態和插件推薦集成在一個名爲「水豚祕書」的系統中，通過桌面寵物「嚕嚕」提供可視化的交互反饋。插件本身零配額，所有 API 調用消耗的是 DSH 本身的額度。
核心功能¶
該插件提供以下能力：
- 告警 API：提供
POST /api/secretary/notify接口，任何腳本或任務看板都可以向寵物投遞告警，觸發氣泡提示和提示音。 - 收件箱：告警數據持久化存儲在
$DSH_HOME/secretary/inbox.jsonl，可通過/queue接口讀取最近 50 條歷史記錄。 - 會話智能提醒：監聽 DSH 會話事件，根據狀態彈出提示。任務回合完成顯示「任務完成」；等待確認顯示「需要你確認：理由」；回合被阻塞顯示「等待繼續」。
- 桌面寵物：macOS 下提供透明置頂的小窗，支持點擊穿透、拖拽定位、位置記憶和開機自啓託管。
- 巡檢腳本：內置磁盤、HTTP 和進程存活巡檢的模板腳本，超閾值時自動通知。
- 每日插件推薦：從社區市場篩選高口碑插件，每天推送 3 款未安裝的推薦。
安裝與啓用¶
- 安裝插件本體：使用官方命令添加插件。安裝後需要重啓 DSH Web 服務（
dsh web）。
dsh plugin --profile <你的profile> add "github:zzx-dear/dsh-capybara-notify"
- 測試功能：使用提供的測試腳本驗證寵物是否能正常響應。
bash /path/to/dsh-capybara-notify/checks/notify.sh -t "測試" -b "嚕嚕在聽" -l info
桌面寵物（macOS）¶
桌面寵物功能僅在 macOS 上可用（基於 pywebview/WebKit 透明置頂窗）。Linux 和 Windows 用戶仍可使用插件 API，但需配合其他 dsh-pet 兼容前端。
- 安裝寵物：運行安裝腳本，腳本會創建虛擬環境並註冊 launchd 服務（開機自啓 + 崩潰自愈）。
bash /path/to/dsh-capybara-notify/pet/install_pet.sh
- 隱藏網頁內置寵物：如果網頁 GUI 中也顯示寵物，可通過 API 隱藏網頁端的寵物，只保留桌面端。
curl -X POST http://127.0.0.1:3080/api/pet/set-visible -H 'content-type: application/json' -d '{"visible": false}'
- 自定義寵物形象：寵物素材來自 Codex Pet 生態。將圖集和
pet.json放入~/.codex/pets/<id>/，並設置環境變量LULU_PET_ID=<id>。
每日插件推薦（macOS）¶
如果需要自動獲取每日插件推薦，可以設置 launchd 定時任務。
- 創建 plist 文件：創建配置文件，設置每天 09:00 執行推薦檢查。
mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.lulu.plugin-check.plist <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key><string>com.lulu.plugin-check</string>
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>$(pwd)/checks/check_plugins.sh</string>
</array>
<key>StartCalendarInterval</key>
<dict><key>Hour</key><integer>9</integer><key>Minute</key><integer>0</integer></dict>
<key>StandardOutPath</key><string>/tmp/lulu-plugin-check.out.log</string>
<key>StandardErrorPath</key><string>/tmp/lulu-plugin-check.err.log</string>
</dict>
</plist>
EOF
- 啓動服務：加載配置。
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.lulu.plugin-check.plist
API 使用¶
插件提供 REST API 供外部腳本調用。
- 投遞告警：
POST /api/secretary/notify
{ "title": "磁盤告警", "body": "根分區已用 92%", "level": "info" }
*限制：標題 ≤ 60 字，正文 ≤ 500 字。氣泡顯示僅支持標題 ≤ 22 字、正文 ≤ 22 字。*
-
讀取收件箱：
GET /api/secretary/queue
返回最近 50 條告警列表。 -
健康檢查：
GET /api/secretary/health
返回服務狀態和收件箱路徑。
巡檢腳本示例¶
使用插件自帶的巡檢腳本模板。
# 投遞一條告警
bash /path/to/dsh-capybara-notify/checks/notify.sh -t "標題" -b "正文" -l info
# 支持 stdin 輸入正文
echo "hi" | bash /path/to/dsh-capybara-notify/checks/notify.sh -t "來自管道"
# HTTP 站點巡檢（不可達才通知）
bash /path/to/dsh-capybara-notify/checks/check_http.sh https://example.com
# 磁盤巡檢（超過閾值才通知）
bash /path/to/dsh-capybara-notify/checks/check_disk.sh 90
# 進程巡檢（進程不存在才通知）
bash /path/to/dsh-capybara-notify/checks/check_process.sh dsh
會話智能提醒¶
該功能基於 DSH 的會話事件自動觸發。
- 任務完成：回合結束時彈出「任務完成」，級別爲 info。
- 需要確認：沙箱升級或批准等需要用戶介入時，彈出「需要你確認：理由」，級別爲 warning。
- 等待繼續：回合被阻塞等待輸入時，彈出「等待繼續」，級別爲 warning。
注意：子代理的回合不會觸發提醒，只響主會話。關閉提醒可通過環境變量SECRETARY_SESSION_ALERTS=0實現。
任務看板聯動¶
在任務看板（如 dsh-task-board）中，可以直接調用巡檢腳本。如果腳本檢測到異常，會自動向寵物投遞告警，無需人工干預。
環境變量¶
| 變量名 | 默認值 | 說明 |
|---|---|---|
SECRETARY_SESSION_ALERTS |
開 | 設爲 0 關閉會話智能提醒 |
SECRETARY_PET_FIBERS |
pet |
寵物服務的 fiber 名 |
SECRETARY_API |
http://127.0.0.1:3080/api/secretary/notify |
notify.sh 的投遞地址 |
DSH_WEB_URL |
http://127.0.0.1:3080 |
桌面寵物的反代地址 |
LULU_SCALE |
0.40 |
寵物縮放比例 |
LULU_PET_ID |
capybara-ruru |
寵物 ID |
LULU_X / LULU_Y |
右下角 | 初始位置 |
已知限制¶
- 平臺限制：桌面寵物僅支持 macOS（pywebview/WebKit 透明置頂窗）。Linux 和 Windows 可使用插件 API，但需要自行集成前端。
- 依賴瀏覽器：任務看板 cron 需要瀏覽器標籤頁處於打開狀態，否則任務會被跳過。
- API 額度消耗：每次觸發巡檢腳本或每日推薦任務都會消耗 API 額度，插件本身不佔用額外配額。
總結¶
zzx-dear/dsh-capybara-notify 是一個實用的 DSH 插件，它通過桌面通知和寵物形象，解決了智能體後臺運行時的信息反饋問題。適合需要頻繁監控任務狀態、進行巡檢或希望獲得每日推薦的開發者。安裝前請確認源碼與許可證符合需求。
