前言¶

在 DeepSeek Harness 裏跑長期任務時，常見做法是定時讓 Agent 自己「看一眼」有沒有新情況。這樣要麼浪費 token，要麼把對話拉得很長。若把檢查邏輯寫成獨立腳本，又缺少一個穩定、可配置的調度層，把「無事」和「有事」分開處理。

dsh-watch-kit-plugin（維護者 rokyaria，GitHub 倉庫 rokyaria/dsh-watch-kit-plugin）是面向 DSH 的常駐巡檢插件（當前資料版本 v0.3.1）：按配置的間隔運行 checker；checker 僅在需要處理時於 stdout 輸出 notify: true，插件才把消息投遞到綁定的會話；其餘輪次不產生對話、不消耗 LLM token。運行時狀態落在 SQLite，watch 列表來自用戶級 $DSH_HOME（默認 ~/.dsh）下 watch/ 目錄中的 JSON 配置。

這是什麼¶

一句話：它是 DSH 內的 watch 調度器與事件喚醒層，不是 OS 通知、系統 cron 或獨立 daemon。

去重、重試、以及「只在變化時提醒」由 checker 自行維護狀態；checker 以當前用戶身份執行，權限與普通 shell 相同，安裝前應閱讀源碼與 MIT 許可證。

核心功能¶

配置與生效路徑¶

watch 配置爲單文件 JSON，默認路徑爲 <dshHome>/watch/watches.json。編輯後必須由用戶本人在會話輸入框發送 /watch-reload 纔會同步進數據庫；Agent 不能代發該 slash command。首次安裝後不會自動導入配置文件，必須手動執行一次 /watch-reload。

數據庫默認 <dshHome>/watch/watch.db。整份 watches.json 一起校驗：任一條目非法則 reload 返回錯誤，數據庫不變；文件中刪除的 watch 軟刪除，重新出現即恢復。

watches.json 字段¶

頂層結構爲 {"watches": [...]}。每個 watch 主要字段如下（與 README 一致）：

checker 契約¶

插件按 checker 數組 spawn 進程，設置環境變量 WATCH_ID、WATCH_INTERVAL、WATCH_TIMEOUT。stdout 必須是合法 JSON 對象；只認 stdout，退出碼不參與「是否通知」的語義。

有事件時輸出：

{"notify": true, "message": "摘要說明"}

無事時輸出：

{"notify": false}

stdout 是喚醒信號，不是大數據通道：正文或大結果應寫入文件，message 裏放摘要與路徑。默認 stdout 上限 64KiB，超限按 invalid_json 處理。最小示例如 README 中的 bash 腳本：檢測目錄是否有待處理文件，有則 notify: true。

隨包 mailbox 擴展（可選）¶

extension/mailbox/ 提供 Python 3.9+ 郵箱 checker（標準庫、無第三方依賴），在 watches.json 中用 preset: "mailbox"，無需手寫 checker 路徑。需單獨準備 mail.env、allowlist 等；默認不通知任何人，必須配置 per-account allowlist；授權碼不能寫進 watches.json。細節見倉庫內 extension/mailbox/README.md 與 skills/watch-mailbox/SKILL.md。

運行上限（可選）¶

併發檢查數、stdout/stderr/message 字節上限、運行記錄保留天數等，通過 profile 的 cordis.patch.yml 覆蓋插件 Config 中的 limits 與 pollIntervalMs，不能按單條 watch 單獨配置。修改 patch 後需 DSH 重新加載插件；watches.json 的變更仍只走 /watch-reload。

安裝與啓用¶

安裝入口分三種，具體可複製步驟、驗證清單與故障排查見倉庫根目錄 install.md：

1. 方式 A：Web 側邊欄「插件」頁（適合普通 Web 用戶、少折騰）。
2. 方式 B：已開 Creator 預設且具備 plugin_manager 時，由 Agent 按 install.md 代裝（會涉及 danger-full-access 或審批）。
3. 方式 C：插件頁不可用且沒有 plugin_manager 時，按 install.md 手動兜底；若有受管 profile 僅插件頁異常，可切 Creator 用方式 B。

資料中未給出統一的 dsh plugin add … 一行命令，請勿憑倉庫名自行拼接。插件要求 Node.js >= 24.0.0、DSH ^0.2.1-rc.3（見 package.json）。

安裝完成後，在 ~/.dsh/watch/watches.json 寫好 watch，用戶發送 /watch-reload。有事件時會收到 [WATCH 通知]；需要統計時可讓 Agent 調用 watch_runs，查可用會話 id 用 watch_sessions。

典型用法¶

自定義 checker¶

1、新建配置文件（路徑可隨 DSH_HOME 變化，以下爲默認）：

{
  "watches": [
    {
      "id": "mail-inbox",
      "checker": ["bash", "/abs/path/check-mail.sh"],
      "cwd": "/abs/path",
      "interval": 60,
      "timeout": 30,
      "enabled": true
    }
  ]
}

2、在 DSH 輸入框發送 /watch-reload。

3、之後約每 60 秒運行一次 checker（調度器默認 10 秒輪詢到期項）；當 stdout 爲 {"notify":true,"message":"…"} 時，綁定會話收到一條 [WATCH 通知]。

mailbox preset 模板¶

啓用前將 enabled 改爲 true 並準備好 env 與 allowlist 文件，再 /watch-reload：

{
  "id": "mailbox-account-1",
  "preset": "mailbox",
  "enabled": false,
  "mailbox": {
    "envFile": "/absolute/path/to/mail.env",
    "stateDir": "~/.dsh/mailbox",
    "allowAccountFile": "/absolute/path/to/allow-accounts.json",
    "remindAfterMinutes": 30,
    "maxNotify": 20,
    "folder": "INBOX",
    "python": "python3"
  },
  "interval": 60,
  "timeout": 60
}

適用場景與注意¶

適合：需要在 DSH 會話內被動響應外部變化（郵件、構建產物、隊列文件等），且希望檢查邏輯與 Agent 對話解耦、無事零 token 的場景。

不適合：替代系統級 cron 或跨機器統一調度；也不提供 OS 級沙箱——checker 與 DSH 同用戶權限，應對不可信輸入時在 checker 或業務層自行防護。

多實例可共享 DB 以降低重複執行概率，但不保證跨實例通知去重。社區目錄頁 skillhub.cn 上的插件條目 與 GitHub 倉庫由社區維護，與 DeepSeek / 幻方無官方從屬關係；分類爲工作流類插件。

結尾¶

dsh-watch-kit-plugin 把「定時檢查」和「喚醒 Agent」拆成兩層：SQLite 記調度與運行事實，checker 用極簡 JSON 決定是否打擾會話。配置集中在 watches.json，一次 /watch-reload 生效；需要郵箱場景時可選用隨包 mailbox preset。

• 目錄頁：https://www.skillhub.cn/plugins/rokyaria/dsh-watch-kit-plugin
• 源碼與文檔：https://github.com/rokyaria/dsh-watch-kit-plugin