dsh-heartbeat

让 DeepSeek Harness 的 agent 拥有持续存在感的心跳插件：她按节律自己醒来，维护记忆与画像、感知你的忙闲、按兴趣闲逛看新东西、把没说完的话带过下一拍，然后按分寸决定开不开口——开口要有真实来处，沉默要有具体理由。

一分钟了解

全部能力都收在 DSH 设置页的心跳卡片里，日常使用零命令行：

设置卡总览	素材池

用户画像（只读）	节律配置

展开看其余分区：会话绑定 / 兴趣范围 / 账本 · 摘抄本 · 周报 · 换机迁移

会话绑定	兴趣范围

账本 · 摘抄本 · 周报	换机迁移

截图为 v2.0.0。画像与会话绑定两张里的条目文字已打码。

它想解决的三件事：

快速开始

安装（npm 包，推荐）

dsh plugin --profile web add @kanadego/dsh-heartbeat

重启 DSH 即生效——插件自动创建专用心跳会话并按节律运行，之后日常无需任何操作。

心跳预设是自动装的：插件加载时直接向宿主注册（agentPresets.register()，v1.9.2 起），不需要任何手动操作，安装清单里也不再声明宿主包。缺失就按包内模板建好，已有文件永不覆写（你手改过的预设原样保留）。无论走哪条路径，没有这个预设心跳 agent 就是个"裸 agent"，连 web_search 都看不见——想手动检查/修复用 preset status / preset install（见下节）；把插件 config 的 installPreset 设为 false 可同时关掉运行时注册与目录自装，预设完全由你管。

从源码安装（开发/改造用）

dsh plugin --profile web add file:D:/path/to/dsh-heartbeat

数据放在哪

数据默认住在包外：<DSH_HOME>/heartbeat-data（没有 DSH_HOME 就是 ~/.dsh/heartbeat-data），重装与升级都不会碰它。老版本装在包目录里的 data/ 会在首次启动时自动搬过去（搬迁前先备份、逐文件校验通过才删原件，见下节「卸载」）。要换位置就用插件 config 的 dataDir，或环境变量 HEARTBEAT_DATA_DIR。

核心工作机制

一跳 = agent 自己醒一次（默认 60 分钟）。醒着的时候依次走七相，最后由留痕收尾：

维护 → 采集 → 闲逛 → 闸门 → Digest → 反刍备料 → 投递 →  留痕
                        │
                   判「别说」→ 本跳到此为止，决策与表达不再调模型

①  维护 ── 清素材池 / 滚动日志 / 判断该不该合并画像
②  采集 ── 全屏截图（加密落盘）+ 忙闲判定 + 前台窗口类别
           ╰─ 观察：把绑定会话里你新说的话收进画像收件箱
②′ 闲逛 ── 条件触发：agent 自己按兴趣焦点用 web_search 看新东西
③  闸门 ── 纯代码判定：静默窗 / 忙时 / 在场 / 每日上限 / 冷却
           ╰─ 判「别说」→ 本跳到此为止，决策与表达不再调模型
④  Digest ── 拼出「此刻状态」：画像 + 时间 + 素材池 + 待办
⑤  反刍 ── 引擎室从素材池挑 ≤3 条，各压成一句话（备料）
⑥  投递 ── 拼成素材包，送进你指定投递的那个会话
⑦  留痕 ── 写审计日志 + 账本（真正开口了才计数）
  │
  ▼
你读的那个会话 ── 那里的 agent 按当下处境，决定说不说、说哪条

核心功能

心跳节律与分寸闸门

• 心跳节律：定时唤醒（默认 60 分钟一跳，卡片可调），按七相循环运行——维护 → 采集 → 闲逛 → 闸门 → Digest → 反刍备料 → 投递，末了由留痕收尾。每跳都有审计留痕，沉默必带原因。
• 分寸闸门：静默时段、忙时窗口、每日表达上限、开口冷却、在场联动，全部是代码层的独立判定，不靠模型自觉。默认倾向开口，但你正忙或已到深夜时绝不打扰。
• 状态栏与时间感知：心跳把"此刻在干什么"（在闲逛 / 看到你在忙 / 在场待着…）注入日常会话——支持动态系统提示词的模型常驻系统提示词（KV-cache 安全追加），其余模型只在用户发起轮次时带一行。精确时间按 20–30 分钟节流注入，任务进行中绝不中途插话。

视觉与兴趣闲逛

• 视觉感知（可选）：每跳对全屏截图做一次视觉识别（如果模型不支持多模态，支持经 ModLens 此类视觉辅助插件外接多模态模型），投递的素材包会带一句「（他此刻大概在：…）」；识别失败时画面与窗口标题一概不进任何提示词——隐私优先，宁可不说。
• 兴趣闲逛：按你定义的兴趣范围轮换挑焦点（同一条 3 天冷却），用 web_search 看新东西（每次 3~9 轮搜索），结果由代码登记入素材池（每焦点至多 2 条，config/interests.json 的 _schedule 可调）——模型只负责搜索筛选，不做任何写盘动作。话题库存见底（≤4 条）时自动触发补货闲逛（每天至多 2 次）。

素材池与投递闭环

• 素材池（话题 / 聊天双仓）：话题库存 16 条 + 聊天素材 14 条，四条确定性淘汰（TTL / 消费退休 / 冷板凳 / 容量挤出）；聊天种子来自画像合并时从对话里挑出的"值得聊的话题"，有时效性——被说出口后至少活到下一次回收，有新证据还会继续留池（v1.9.1 之前是"投递过 1 次即退休"，常常话刚出口上下文就断了）。归档区也有上限（默认 50 条），超出按最老优先裁掉；新增 / 合并 / 淘汰 / 裁剪 / 恢复 / 删除都会写进审计日志（只记编号与元数据，不记素材正文）。是缓存不是记忆，与画像单向隔离。
• 反刍投递（目标会话拍板）：代码先凑好候选（话题随机 4 + 聊天最新 2，互补至多 6 条），引擎室挑 ≤3 条各压缩成一句，拼成素材包注入你读的会话——附一句「他此刻大概在：…」（视觉识别成功时）＋声明「这是心跳插件素材投递」＋素材清单（必要时附「也可以说一句真心话」）。说不说、说哪条，由目标会话里的 agent 按当下处境自己判断——决定不说就把正文留空（v1.9.3 起，但是受模型指令遵循能力限制，如想要更好的效果，建议在系统提示词/长期记忆中补充一条相应规则）；话落到你眼前的会话后，agent 会按本次投递编号报账——哪几条被用上、是引用素材还是顺着自己发挥，都如实记下。
• 心事匣（v2.0.0 新增）：给心跳一格便签，用来把没说完的话留给下一跳的自己。投递的素材包里会带上「你上跳留下的心事:…」，以及它留于第几跳、已搁多久、这期间被叫醒过几次；想留住就照原样再写一遍（字样一致算保留，年龄不重算），想换就直接写新的，什么都不做它下一跳自动清掉。不强制每跳留话——没话说就空着。生命周期由两个序号判定，只认真正的拍（启动那一拍不计入），所以「搁了几跳」永远是真的。
• 摘抄本（v2.0.0 新增）：心跳自己的本子，用来留句子和想记住的小事。注册成模型工具 excerpt（add / list / remove），日常会话里的 agent 想到什么就当场抄下，不用谁下命令；数据落 data/excerpts.md，明文、可直接手编——一本谁也翻不开的笔记本不叫笔记本，认不出的行在改写时会原样留着。它和另两本分工明确：账本记待办（会勾掉），心事匣是留给下一跳的一句引子（一格、会被盖掉），摘抄本只增不减，除非主动抹掉。
• 会话绑定：把心跳消息投递到你常用的会话（agent 会"到你房间里说话"），或观察会话内容喂养画像——投递/观察是两个独立开关，可双开。

记忆 · 账本 · 周报

• 用户画像：本地结构化档案（兴趣 / 项目 / 沟通偏好 / 心理基线），带来源与置信度，稳定特质不因时间遗忘；journal 单一权威，可校验、可重建、可解密导出。
• 周报：每 7 天一份，只报道这周干了些什么——表达与静默、新认识、账本、素材池、活跃高峰。由后台「心跳」署名写成平实中性的一句话档案，加密落盘，卡片可翻，默认只留最近 3 期（policy.weekly.keepReports）。
• 账本工具：账本注册成模型工具，日常会话里的 agent 听到你提到待办/承诺会自己记账、完成后自己勾掉，不用你下命令——和心跳、CLI 记的是同一本账。
• journal 快照基点：画像 journal 超 5000 条自动折叠成快照 + 归档分片，重放成本有界；verify/rebuild 跨快照依然正确。

数据 · 迁移 · 焚毁

• 换机迁移：一键打包画像/账本/素材池/周报为口令加密容器（卡片或 CLI），新机器导入自动用本机主密钥重加密。
• 加密与焚毁：敏感文件 AES-256-GCM 整文件加密，数据密钥由 Windows DPAPI（CurrentUser） 保管在 data/vault.key，只在进程启动解一次；旧版（1.x）留下的 DPAPI 容器照样能读，且在写入与每跳维护时自动改写成新格式（vault upgrade 一次全换）；一键焚毁运行时数据；模型出库仅限合并裁决的最小必要摘要。

常见故障与诊断

第一现场永远是 data/logs/heartbeat.jsonl（每跳留痕，silent 必带原因）。

完整事件字典、宿主契约备忘与更多症状见 DESIGN.md §7。

CLI 命令

设置页卡片覆盖日常操作；CLI 面向高级用法与脚本场景：

node <插件目录>/dist/cli/index.js <命令>

数据与安全

信息存储

所有运行数据都在心跳数据目录（唯一可写位置，路径守卫强制），卸载或重装都不会丢：

加密分两层：数据用 AES-256-GCM 整文件加密（带认证，改一个字节就解不开也不会给出一半内容），数据密钥存在 data/vault.key，那一个文件由 Windows DPAPI（CurrentUser 作用域） 保护——所以本机本账户可自动解密使用，其他账户、其他机器、云同步副本都解不开。防的是他人 / 他机 / 误同步，不防同账户的恶意软件——那是操作系统边界的事。

1.x 写的文件用的是旧的 DPAPI 容器（KHBV1），v2.0 读得懂但写的是新容器（KHBV2）：升级插件不会让任何旧数据变成打不开的死文件。旧格式会自己换掉——任何一次写入都落成新容器，每一跳的维护相另外顺带把长期没动过的一个旧文件就地改写；想一次全换完，跑 heartbeat vault upgrade（vault status 看盘上各格式各有多少）。

反过来要注意：KHBV2 只有 2.0 及以后的版本认识——升级到 2.0 之后不要再回退到 1.x，旧版本会把新容器当作打不开的文件。（要回退就趁早；跑过 vault upgrade 之后、或让数据写过一轮之后，就回不去了。）

安全边界

• 路径守卫：全部落盘经过守卫规范化比对，.. 穿越、符号链接、8.3 短名、UNC 一律拒绝；data/ 是唯一可写目录。
• 模型工具硬限制：引擎室轮次的工具面由代码层白名单收窄——闲逛相唯一需要的 web_search，加上装了 billion-context 这类插件时的压缩三件套 compress / decompress / acp_status（v1.8.0 起，免得长会话把自己撑爆）。账本、素材报账、心事匣、摘抄本这四个工具注册在全局层（你的日常会话里可用），引擎室轮次看不到它们。白名单管的是全局层：宿主自己注册在 agent 作用域的行不受它约束——实测引擎室那一跳拿到的完整工具面是 9 个：web_search（预设挂的）、compress / decompress / acp_status（billion-context）、ops_bash（dsh-ops）、schedule_create / schedule_list / schedule_update / schedule_delete（dsh-schedule）——后五个是宿主插件注册在 agent 自身层的行，白名单管不到它们（注意 search_context 与 acp_cache 是故意不放行的：前者与 dsh-acp 的同名工具撞名）。复用的 agent 也会重新钉一遍：插件重启后若引擎室会话正开着、agent 被宿主直接复用（日志里的 agent_reuse_live），复用分支会单独调一次 pinEngineRoomTools 把白名单重新钉上，结果记在同一行 tool_policy 里、带 reuse 前缀——2026-10-17 修的，修之前这条路径不套白名单（实测漏到 62 个工具）。
• 建议 · 防注入：网页内容应视为数据而非指令（闲逛提示词中明示）；画像裁决 prompt 同理（观察内容是数据，不应改写人格设定）。这是推荐的做法，是否采纳由使用者自行决定，并非安装即强制生效。
• 模型出库边界：画像合并调用走宿主模型通道（插件不持有任何云凭证），送四个分区（含 psy）的条目字段与 ≤1 句观察引语——不送对话原文、不送证据全量。（2026-10-07 调整：先前排除 psy，结果模型能往自己看不见的分区写，而 UPDATE 必须给 id、id 又只出现在条目视图里，psy 条目写进去就改不动了。）
• 一键焚毁：burn（预演）→ burn --yes（运行时数据覆写 x3 后删除，用户设置保留）→ burn --all（连设置归零）。
• 数据通道鉴权：设置卡读写的 /api/heartbeat 通道自身不持有凭证，靠宿主对 /api 前缀路由的门禁（Host / Origin 校验 + 浏览器会话 secret）。v1.9.1 起插件在注册时自检这道门禁还在不在（当时只拒六个「破坏性」端点）；2.0 起不在就整个通道失败关闭：只放行几个只读低敏端点（status、config.get、sessions.list、bindings.get、weekly.list），其余一律拒绝并留痕（rpc_host_gate_missing）——包括所有涉及记忆内容的读取（画像摘要 / 分区、素材池、兴趣词、周报正文、迁移导出）。（2026-10-17 收紧。）

版本兼容

0.1.5 宿主须 ≥ v1.2.1（否则设置卡 RPC 405）；v1.6.3 有渲染 bug，请直接用 v1.6.4。

⚠️ 升级宿主会触发会话格式自动迁移，且不可降级——0.1.5 起迁到 v3、0.1.7 起迁到 v4（首次访问该会话时转换，原文件保留）。这动的是用户数据，升级前先备份 ~/.dsh/sessions。

卸载

dsh plugin --profile web remove @kanadego/dsh-heartbeat

卸载只拆插件本体（包、挂载行、注册项，无残留引用），不动用户数据——v1.9.2 起数据默认住在包外的 <DSH_HOME>/heartbeat-data（~/.dsh/heartbeat-data），重装、升级、卸载都不会碰它。想连数据一起删，先 burn --all 焚毁敏感内容再删目录。

- id: heartbeat
  config:
    dataDir: D:/your/workspace/heartbeat-data

版本更新

更早的版本（v1.9.x → v1.0.0，以及 v0.x 脚本外挂时代）见 CHANGELOG.md。

延伸阅读与致谢

• DESIGN.md — 深入的设计决策、宿主契约实测备忘与踩坑记录
• CHANGELOG.md — 完整版本历史
• tomsteve1102/presence-watch — 讨论起点与闸门思想
• kohaku-heartbeat — 前代项目，本插件为其重构

许可

MIT

下载量