前言¶
在 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
