dsh-heartbeat

dsh-heartbeat

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

一分钟了解

装好之后，全部能力都收在插件管理页的心跳面板里，日常使用零命令行：

心跳状态	会话绑定

素材池	用户画像（只读）

展开看其余分区：兴趣范围 / 周报 / 节律 · 专注模式 · 换机迁移

兴趣范围	周报

设置页把节律、专注模式、换机迁移、账本与摘抄本入口收在一起：

截图为 v2.1.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。

平台支持

Windows 上全部功能可用。v2.1.0 起 Linux / macOS 也能跑起来：心跳循环、表达与投递、时间注入、心事匣 / 账本 / 摘抄本、素材池、周报、设置面板与 RPC 通道都照常；依赖 PowerShell 的那几项——截屏、空闲检测、锁屏检测、前台窗口探测、桌面通知——在这两个平台上不可用，插件会直接按「探针失败」降级，不会卡住某一跳。代价是忙闲判定缺席：静默时段、每日上限、开口冷却照常生效，但「他大概在忙」这类窗口判断不会触发。

数据不跨平台搬家：data/vault.key 在 Windows 上由 DPAPI 保护，在 Linux / macOS 上是一份权限 0600 的密钥文件，两边互不相认。换平台就是重新开一份数据目录。

核心工作机制

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

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

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

核心功能

心跳节律与分寸闸门

• 心跳节律：定时唤醒（默认 60 分钟一跳，卡片可调），按七相循环运行——维护 → 采集 → 闲逛 → 闸门 → Digest → 反刍备料 → 投递，末了由留痕收尾。每跳都有审计留痕，沉默必带原因。
• 节律随机化（v2.1.0）：每跳的实际间隔在基准值上浮动 ±20%（policy.heartbeat.intervalJitterPct，0–50，设 0 即关闭），不再踩准整点报时。启动那一跳固定 15 秒后、不参与抖动，约每跳不同的落点让心跳不显得机械。
• 专注模式（v2.1.0）：需要安静时一键暂停心跳 N 分钟（1–1440），不碰配置、到时自动恢复；暂停期间不跳、不发消息、不计每日额度，状态栏显示「专注模式 · 至 HH:MM」。设置卡与 CLI（focus <分钟>）同一份暂停状态，暂停落 data/focus.json，重启后照样有效。
• 分寸闸门：静默时段、忙时窗口、每日表达上限、开口冷却、在场联动，全部是代码层的独立判定，不靠模型自觉。默认倾向开口，但你正忙或已到深夜时绝不打扰。
• 状态栏与时间感知：心跳把"此刻在干什么"（在闲逛 / 看到你在忙 / 在场待着…）注入日常会话——支持动态系统提示词的模型常驻系统提示词（KV-cache 安全追加），其余模型只在用户发起轮次时带一行。精确时间按 20–30 分钟节流注入，任务进行中绝不中途插话；子代理会话一律不注入（v2.1.0）——分身不该看见本体的时间账。

视觉与兴趣闲逛

• 视觉感知（可选）：每跳对全屏截图做一次视觉识别（如果模型不支持多模态，支持经 ModLens 此类视觉辅助插件外接多模态模型），投递的素材包会带一句「（他此刻大概在：…）」；识别失败时画面与窗口标题一概不进任何提示词——隐私优先，宁可不说。
• 兴趣闲逛：按你定义的兴趣范围轮换挑焦点（同一条 3 天冷却），用 web_search 看新东西（每次 3~9 轮搜索），结果由代码登记入素材池（每焦点至多 4 条，config/interests.json 的 max_seeds_per_focus 可调）——模型只负责搜索筛选，不做任何写盘动作。入库前查重（v2.1.0）：完全相同的网址、归一化后同名的条目、以及与近 30 天归档高度相似（标题相似度 >0.85）的一律丢弃，同一个话题不会被反复捡回来。话题库存见底（≤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（Linux / macOS 上是权限 0600 的原始密钥文件），只在进程启动解一次；旧版（1.x）留下的 DPAPI 容器照样能读，且在写入与每跳维护时自动改写成新格式（vault upgrade 一次全换）；一键焚毁运行时数据；模型出库仅限合并裁决的最小必要摘要。

Web 面板

心跳的日常操作都集中在 DSH 的插件管理页：插件管理 → dsh-heartbeat → 配置，打开即见面板。面板按 tab 分页，一个 tab 管一件事：

几点使用说明：

• 设置按「节律 / 时间与状态栏 / 表达 / 专注模式」分组，每组一句人话说明管什么，每个参数旁标着「多久生效」：改心跳间隔保存后立即重排节律，其余参数保存后从下一跳开始生效——都不用重启。
• 专注模式是独立开关：填分钟数、点按钮即刻暂停或恢复心跳，到点自动恢复，不参与「保存」。
• 换机迁移的导入是危险操作：会用迁移包覆盖本机的心跳数据（被替换的文件自动备份）。第一次点只亮起确认提示，再点一次「确认导入」才真正执行；改了文件路径或口令，确认态会退回。
• 周报默认收起正文，点日期选期、点「展开查看报告正文」阅读。
• 状态页是六格速览：上次心跳 / 插件版本 / 今日表达（带进度条，满额转黄）/ 时间注入 / 上次结果 / 此刻动态，右上角徽章一眼看出是在正常节律、专注模式还是静默。
• 面板就是普通网页组件：改完 client.js 刷新页面即可看到新样子，不需要重启 DSH。

常见故障与诊断

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

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

CLI 命令

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

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

数据与安全

信息存储

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

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

Linux / macOS 上没有 DPAPI：data/vault.key 里就是那 32 字节密钥本身，靠文件权限（0600，只有运行插件的账户能读）守着——防的是「别人翻到这份数据」和「误同步」，防不住已经拿到你这个账户的同机进程，比 Windows 少一层系统钥匙串。也正因为两端密钥互不相认，数据目录不跨平台搬家：Windows 写的密钥到 Linux 解不开，heartbeat vault status 会如实报出来。

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

版本更新

v2.0.x 及更早的更新记录已移至 CHANGELOG.md（README 这里只保留当前大版本 v2.1.x，插件市场的「更新内容」读的就是这一节）。

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

延伸阅读与致谢

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

许可

MIT

下载量