前言¶
在 DeepSeek Harness（DSH）裏，agent 通常由用戶消息觸發。你不問，它一般也不會主動開口。對於長時間運行、等待外部事件，或者用戶暫時離開的會話，這種模式容易讓人錯過進展、風險和卡點。
下面介紹的 dsh-plugin-heartbeat 是一個 DSH 插件，用來給 agent 加一個定時喚醒機制。它讓 agent 在空閒或任務間隙按設定節奏主動說一句：有進展說進展，有風險說風險，沒有內容就簡短說明。
這是什麼¶
dsh-plugin-heartbeat 由 LittleBlackTong 維護，採用 MIT 許可證。它是一個 Host 平面的 Cordis 插件，監聽 agent/created 事件，併爲每個 root agent 掛一條獨立定時器。
它通過 agent.followup() 注入一條合成 user 消息，消息來源標記爲 source.kind === 'plugin'。這個機制用於讓 agent 主動彙報狀態，而不是讓它自行開啓新任務。
核心能力¶
定時喚醒¶
插件按設定週期喚醒 agent。agent 空閒時，會立即開始新一輪；agent 忙時，消息進入隊列，等當前輪結束再處理。連續忙時，隊列中只保留一條待處理，不堆積。
退避與硬停¶
心跳間隔支持退避：初始爲 10 分鐘，如果沒有真人回覆，後續間隔按 [base, 2×base, 3×base] 增加。
連續 pauseAfterMissed 拍沒有真人回覆時，插件會硬停定時器。用戶下一條消息到達後，心跳再復活。
投遞前壓縮¶
支持 compactBeforeBeat。開啓時，插件會在投遞心跳前把歷史壓縮成 checkpoint 摘要，減少每拍注入的上下文量。
頻控與展示¶
支持 maxBeatsPerHour，爲 60 分鐘窗口設置心跳上限。
注入的心跳消息在對話流裏渲染爲摺疊的 context 小行，不是一整塊用戶氣泡。
安裝與啓用¶
安裝命令如下：
dsh plugin --profile <profile> add dsh-plugin-heartbeat
安裝後重啓 DSH 生效。插件運行依賴：
@deepseek-ai/cordis ^4.0.1
@deepseek-ai/schemastery ^3.18.1
Node >=18
插件以當前 DSH 進程權限運行。安裝前建議先檢查源碼和 MIT 許可證，再決定是否加入自己的 profile。
運行期配置走 <dshHome>/heartbeat.json。如果覆蓋 composition 鍵，例如 prompt，使用不帶 insert 的 id 覆蓋條目。
不要往 profile 的 cordis.patch.yml 裏手寫：
- insert:
id: dsh-heartbeat
這可能導致 duplicate loader entry id "dsh-heartbeat"，進而啓動失敗。
典型用法¶
安裝並重啓 DSH 後，可以進入設置 → 心跳 Heartbeat 面板，調整頻率、開關和暫停閾值，保存後立即應用，無需重啓。
如果只想改默認提示詞，可以用 composition 覆蓋 prompt。示例如下：
- id: dsh-heartbeat
config:
prompt: |
當前時間 {{time}}。
彙報進展、風險或卡點；沒有內容就簡短說明。
總長不超過 5 句。
上面的 {{time}} 會被替換爲當前時間。該示例只用到已確認的模板變量和不超過 5 句的限制。
使用邊界¶
下面幾點在使用時需要注意：
- 心跳只在 DSH 進程活着時存在；DSH 應用關閉後停止。
- 每個會話（root agent）各自一條定時器；子 agent 不掛心跳。
- 心跳不打斷正在執行的任務；任務結束後會補一句。
- 默認提示詞要求 agent 別自作主張開新活，心跳定位是彙報，不是新任務。
- 硬停前已經排隊的一條心跳，會在當前輪結束時被消費；此後不會再產生新拍。
- 與
dsh-plugin-memory零依賴；同時安裝時，兩者消息在同一個 inbox 隊列裏排隊。 - 插件宿主自建
GET/POST /api/heartbeat/config路由，設置面板直連該路由。
結尾¶
dsh-plugin-heartbeat 的價值很簡單：把“用戶問，agent 答”變成“agent 在冷場時主動說一句”。它適合需要長時間運行 agent、希望獲取狀態更新的 DSH 用戶和開發者。
社區目錄頁：
https://www.skillhub.cn/plugins/LittleBlackTong/dsh-plugin-heartbeat
GitHub 倉庫：
https://github.com/LittleBlackTong/dsh-plugin-heartbeat
