deepseek-harness
deepseek-ai
DeepSeek Harness: Everything is a Plugin.
PROJECT TOPICS
PROJECT README
让 DeepSeek Harness 的 agent 拥有持续存在感的心跳插件:她按节律自己醒来,维护记忆与画像、感知你的忙闲、按兴趣闲逛看新东西,然后按分寸决定开不开口——开口要有真实来处,沉默要有具体理由。
全部能力都收在 DSH 设置页的心跳卡片里,日常使用零命令行:
| 心跳状态 | 会话绑定 |
|---|---|
![]() |
![]() |
| 素材池 | 兴趣范围 |
|---|---|
![]() |
![]() |
| 用户画像(只读) | 账本 · 节律配置 · 状态栏 |
|---|---|
![]() |
![]() |
文档里反复出现几个词,先在这里一次说清:
| 词 | 意思 |
|---|---|
| 心跳 | 本插件的核心动作——不用你开口,agent 按固定节律自己「醒一次」:做维护、感知环境、决定要不要说话。醒一次叫一跳,默认 20 分钟一跳。 |
| 宿主 | 运行插件的那个程序,即 DSH 本体。心跳是挂在宿主里的插件——模型通道、会话、工具这些能力都由宿主提供。 |
| 客户端 | 宿主里负责界面的那一侧(Web 界面或者 DSH desktop)。设置页的心跳卡片属于客户端;卡片显示不出来,通常是客户端插件没加载成功,与心跳本体无关。 |
| 相 | 一跳内部的一个阶段。主循环共七相——维护 → 采集 → 闲逛 → 闸门 → Digest → 反刍备料 → 投递,最后统一由留痕收尾。每相结束都会在审计日志留一条 phase_done,所以「这一跳停在哪」可以直接查。 |
| 引擎室 | 跑心跳内部轮次的那个 agent,和你在会话里对话的 agent 是分开的。它只负责采集、反刍、备料,不直接跟你说话;真正开口的是你读的那个会话里的 agent。 |
| 心跳正身 | 心跳自己专用的一个会话,同时也是它的决策现场——每跳的推理轮次都在这里发生。它在会话列表里和普通会话长得一样,日常不用去动它(CLI 的 sessions list 会把它单独标出来)。 |
| 闸门 | 决定「这一跳能不能开口」的纯代码判定层,依次看:静默时段 → 你是不是在忙 → 你在不在场 → 今天说够没有 → 距上次开口够久没。全不通过就安静,并在日志里写下具体原因。它也是省 token 的关键——判「别说」时,后面的模型调用根本不发生。 |
| 观察 | 投递的反向动作——把绑定的会话里你新说的话收进画像收件箱,作为了解你的证据。它发生在采集相:只取当时有活 agent 的绑定会话、每跳最多 10 条、每条只留第一句(≤80 字),插件自己注入的消息会被跳过。 |
| 反刍 | 投递之前的备料步骤:引擎室从素材池挑出最值得说的几条,各压缩成一句话(不带理由、不排序)。名字取自反刍动物把食物嚼细再咽。 |
| 投递 | 把备好的素材包送进你某个会话的动作。把心跳绑定到常用会话,agent 就会「到你那个房间里说话」。 |
插件的一切都围绕一次心跳展开:不用你开口,agent 按固定节律自己醒过来,走完一轮判断,再决定要不要说话。整体链路:
定时器:默认 20 分钟一跳
│
▼
① 维护 ── 清素材池 / 滚动日志 / 判断该不该合并画像
② 采集 ── 全屏截图(加密落盘)+ 忙闲判定 + 前台窗口类别
╰─ 观察:把绑定会话里你新说的话收进画像收件箱
②′ 闲逛 ── 条件触发:agent 自己按兴趣焦点用 web_search 看新东西
③ 闸门 ── 纯代码判定:静默窗 / 忙时 / 在场 / 每日上限 / 冷却
╰─ 判「别说」→ 本跳到此为止,一个 token 都不花
④ Digest ── 拼出「此刻状态」:画像 + 时间 + 素材池 + 待办
⑤ 反刍 ── 引擎室从素材池挑 ≤3 条,各压成一句话(备料)
⑥ 投递 ── 拼成素材包,送进你指定投递的那个会话
⑦ 留痕 ── 写审计日志 + 账本(真正开口了才计数)
│
▼
你读的那个会话 ── 那里的 agent 按当下处境,决定说不说、说哪条
web_search 看新东西(每次 3~9 轮搜索),结果由代码登记入素材池——模型只负责搜索筛选,不做任何写盘动作。话题库存见底(≤4 条)时自动触发补货闲逛(每天至多 2 次)。dsh plugin --profile web add @kanadego/dsh-heartbeat
dsh plugin --profile web add file:D:/path/to/dsh-heartbeat
重启 DSH 即生效——插件自动创建专用心跳会话并按节律运行,之后日常无需任何操作。
心跳预设是自动装的:插件首次启动时检查 <DSH_HOME>/.agent-presets/heartbeat/,缺失就按包内模板建好,已有文件永不覆写(你手改过的预设原样保留)。没有这个预设,心跳 agent 是个"裸 agent",连 web_search 都看不见。不想要这个行为,把插件 config 的 installPreset 设为 false;想手动检查/修复用 preset status / preset install(见下节)。
设置页卡片覆盖日常操作;CLI 面向高级用法与脚本场景:
node <插件目录>/dist/cli/index.js <命令>
| 分组 | 命令 | 说明 |
|---|---|---|
| 总览 | status |
工作区路径 + 策略摘要(今日 cap / 冷却 / 静默窗) |
| 素材池 | seeds add <text> [--tag t] [--topic x] [--confidence n] |
手写一条种子 |
seeds list [--archived] / seeds surface <id> / seeds archive <id> |
列表 / 计一次曝光 / 归档 | |
seeds gc / seeds stats |
跑确定性淘汰 / 池子状态 JSON | |
| 账本 | ledger add <text> / ledger list [--pending] / ledger done <id\|子串> / ledger open |
待办登记 / 查询 / 勾掉 / 编辑器打开 |
| 闲逛 | browse status / browse dry / browse watch / browse done <focus> |
状态 / 强制裁决预演 / 立即查 watchlist / 手动登记一次闲逛 |
| 绑定 | sessions list |
枚举会话 id |
bind list / bind add <id> [--observe] / bind remove <id> |
绑定详情(正身也会列出)/ 绑定 / 解绑;--observe-only 仅观察、--no-deliver 关投递 |
|
| 通知 | notify check / notify register / notify send |
toast 通道体检 / 注册 / 测试发送(只提示新消息,不承载正文) |
| 画像 | profile list [--all] / profile export |
当前有效(含过期)/ 解密导出 Markdown |
profile verify / profile rebuild [--check] / profile wipe |
journal 重放比对(只报不修)/ 重建(可先干跑)/ 清空(要 --yes) |
|
profile snapshot [--force] |
折叠 journal 为快照 + 归档分片(维护相到阈值也会自动做) | |
| 周报 | weekly list / weekly show [file] |
列出已生成的周报 / 打印某期(默认最新一期) |
| 迁移 | migrate export [file] / migrate import <file> |
打包记忆文件为口令加密容器(口令走 stdin 两行)/ 在新机器恢复(stdin 一行);卡片「换机迁移」分区同功能 |
| 日志 | logs cleanup [--dry-run] |
立即执行日志保留策略 |
| 预设 | preset status / preset install [--force] |
装没装、与模板是否一致 / 补装(--force 还原成模板) |
| 焚毁 | burn [--yes] [--all] |
预演(默认)→ 执行;运行时数据覆写 x3 后删除,设置保留(--all 连设置归零) |
所有运行数据都在插件的 data/ 目录(唯一可写位置,路径守卫强制),卸载或重装都不会丢:
| 文件 | 内容 | 状态 |
|---|---|---|
data/settings/ |
绑定、策略覆盖、兴趣范围、心跳状态、时间注入节流 | 明文(用户设定要可手编) |
data/seeds.json |
素材池 | 🔒 DPAPI |
data/profile.* |
画像三件套(journal / 物化视图 / 收件箱) | 🔒 DPAPI |
data/sent.json / data/browse.json / data/screen.* |
表达记录 / 浏览流状态 / 屏幕快照 | 🔒 DPAPI |
data/ledger.md |
账本(agent 的待办与话题来源,可直接手编) | 明文 |
data/profile_snapshot.json / data/profile_journal.archive-*.jsonl |
画像快照基点 / journal 归档分片 | 🔒 快照 DPAPI / 分片明文 |
data/weekly/ |
周报(每 7 天一份,含画像/账本摘录) | 🔒 DPAPI |
data/envpulse.jsonl / data/logs/heartbeat.jsonl |
作息聚合 / 审计日志(不含敏感原文) | 明文,按保留策略滚动清理 |
data/tmp/ / data/exports/ |
临时文件 / 画像导出 | 临时区 |
加密用 Windows DPAPI(CurrentUser 作用域)整文件加密:本机本账户可自动解密使用,其他账户、其他机器、云同步副本都解不开。防的是他人 / 他机 / 误同步,不防同账户的恶意软件——那是操作系统边界的事。
.. 穿越、符号链接、8.3 短名、UNC 一律拒绝;data/ 是唯一可写目录。web_search——没有 shell、文件系统、子代理、技能目录。闲逛轮之外的模型调用(决策 / 合并)零工具。账本与素材报账这两个工具注册在全局层(你的日常会话里可用),心跳自己的轮次看不到它们。burn(预演)→ burn --yes(运行时数据覆写 x3 后删除,用户设置保留)→ burn --all(连设置归零)。第一现场永远是 data/logs/heartbeat.jsonl(每跳留痕,silent 必带原因)。高频症状速查:
| 症状 | 原因与处理 |
|---|---|
| 完全没有心跳(无任何日志行) | 插件没装入:确认 node_modules 里插件存在、启动无 "Failed to load plugins" 横幅;plugin_init 缺失 = apply 没跑 |
| 一直沉默 | 先看 silent 行的 reason:夜间静默窗 = 正常;白天 = cap 满 / 冷却未过 / 忙时窗口 / token-saver(见下条) |
审计出现 silent reason=token-saver、心跳整跳不动 |
节省 token 模式开着,且你已离开(闲置 ≥30 分钟)或锁屏——这是设计行为,回来自动恢复,不是坏了。不想要就关掉那个开关 |
| psy 分区一直空、画像只在其他分区增长 | psy 开关默认关闭:开着时画像合并才收 psy 条目。在设置卡里打开即可 |
闲逛永远秒结束、tool_policy 报 unknown global tool "web_search" |
预设没挂上(裸 agent):preset status → preset install,装好后 tool_policy 行应是 preset=mounted(heartbeat) restrict=ok |
| 设置页整块没有心跳卡片(数据照常写) | client 注册 id 与包名不一致被宿主静默剔除:三处必须严格等于包名,改完重启。若确认 id 没问题,看下一条 |
卡片整块消失 / 节律配置保存不了(0.1.7 宿主) |
旧版插件撞上 0.1.7 的接口换代(设置接口变更 + 客户端服务被删):升级到 v1.7.0 并重启;v1.7.0 已按三代接口自动适配 |
卡片分区报 加载失败: … HTTP 405 |
RPC 路由没注册成功:审计里应出现 rpc_registered route=/api/heartbeat,没有 = dist 未同步,重装/同步后重启 |
节律配置保存不生效、重启后回默认(0.1.5 宿主) |
v1.5.x 的已知问题(dsh-settings 包缺失 + 0.1.5 API 变更):升级到 v1.6.0 并重启;0.1.7 宿主的同类症状见上面「卡片整块消失」那条 |
投递没带「他此刻大概在:…」、审计有 screen_vision ok:false |
视觉识别失败:error 字段带 ModLens 具体报错;常见为 provider 未配置或网络超时。识别失败时画面/标题按隐私设计不进提示词,心跳其余功能不受影响 |
| 结果显示「心跳异常(decision: whenIdle timeout)」 | 反刍轮超时(240s 内没等到模型回话)。v1.6.0 起不再整跳报错:记 decision_deferred、本跳按沉默处理、素材自动留到下一跳。若反复出现,看该行 reason 与 ModLens 画面描述是否诱发跑题 |
每跳 beat_error: … reading 'length' |
宿主移除了 Session.events——插件版本与宿主不匹配,对照〈版本兼容〉换版本 |
引擎室轮次整轮失败、报 format v4 message requires a producer-owned source kind |
0.1.7 的会话日志(V4)拒绝旧版通用的消息来源标记——同样是版本不匹配:升级到 v1.7.0(改用自有来源标记) |
每轮报 prompt variable "{{model}}" has no value |
agent 没有模型路由(审计 model 字段为 (none))——同样是版本不匹配症状 |
素材投递偶尔不成功、spoke_failed: non-Chinese output discarded |
目标会话 agent 收到素材包后回合以工具调用收尾,末行是 </tool_calls>(纯英文)被旧判定误拦。v1.5 起已修:跳过工具收尾标签、取最后一个含中文的行;整段无中文才拒。升级后重启即可 |
有 spoke 但会话里没出现这句话 |
投递目标当时没活 agent 且拉不起来:查 deliver_target_* 系列行;再查绑定 deliver 是否为 true |
| 侧栏某个会话行消失了 | 心跳刚往那个"当时没打开"的会话投递过,投完释放临时 agent 的正常副作用——刷新页面即回,内容零损失 |
升级 0.1.5 后旧会话打不开(unexpected member … / header version must be 3) |
会话格式 v3 迁移问题:前者用 scripts/repair-v0-members.mjs(预检→修复,自动备份);后者首次访问会自动迁移,属正常 |
升级 0.1.7 后会话目录里多出 .v4 文件 |
会话格式 V4 迁移的正常结果:首次访问该会话时转换,原 .v3 文件保留不删。注意这是单向的,降级回旧宿主可能读不了——升级前备份 ~/.dsh/sessions |
| 画像疑似损坏 | profile verify(只报不修)→ profile rebuild --check(看 diff)→ profile rebuild(真重建) |
完整事件字典、宿主契约备忘与更多症状见 DESIGN.md §7。
dsh plugin --profile web remove @kanadego/dsh-heartbeat
卸载只拆插件本体(包、挂载行、注册项,无残留引用);data/ 用户数据默认保留在插件目录,重装后记忆原样回来。想连数据一起删,手动删除 data/ 目录或先用 burn --all 焚毁敏感内容。
| 插件版本 | 适配的 DSH |
|---|---|
| v1.7.4 – v1.9.0(当前) | 0.1.2-rc.1 – 0.2.0-rc.2 |
| v1.7.2 – v1.7.3 | 0.1.2-rc.1 – 0.2.0-rc.1 |
| v1.7.0 – v1.7.1 | 0.1.2-rc.1 – 0.1.7-rc.2 |
| v1.2.x – v1.6.4 | 0.1.2-rc.1 – 0.1.5-rc.2 |
| v1.1 | 0.1.2-rc.1 |
| v1.0 | ≤ 0.1.1-rc.2 |
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。
data/logs/heartbeat.jsonl(seed_added、seed_retired、seed_archive_trimmed、seed_restored、seed_deleted)。只记 id 与元数据,不记素材正文——那本日志是明文,正文来自对话,不该落到明文里。seeds.archiveCap(默认 50)时按最老优先裁掉,不再无限增长;CLI seeds gc 会打印裁剪条数。[s3])现在能正确识别;报账工具写盘超时从 5s 放宽到 15s(DPAPI 单次可能到 2.7s,原来偏紧);闲置时的兜底素材改用画像里的真实条目 id,不再是占位编号。data/ledger.md)。条目被勾掉时日期改记完成日。profile snapshot 可手动触发。compress 等工具,引擎室白名单现在会探测全局层,compress/decompress/acp_status 存在即放行(search_context 因与 dsh-acp 同名工具的历史冲突不自动放行);config extraTools 可手工追加。bili 需装在心跳所在 profile。observe.maxChars)。修复了引擎室会话上下文涨过模型的上下文窗口后导致合并、反刍、投递全部失败,且宿主的自动压缩也救不了的bug。现在心跳会自动轮换引擎室会话:事件数超阈值、或某轮因上下文溢出失败时,自动新建一个干净的引擎室会话接替,旧会话原样留在会话列表里(画像、账本、素材池都在插件数据目录,不受影响)。
另外:设置卡「会话绑定」的会话列表现在自动隐藏已归档和子代理会话。
修复心跳正在跑时 DSH 关不掉的问题——此前桌面端更新若恰逢一跳在跑,宿主等心跳结束等不到,更新会报「未能安全停止任务」。现在收到关闭信号,心跳会立刻停下手里这一跳,不再拖住宿主。
0.2.0-rc.1)声明适配 0.2.0-rc.1,无行为改动。
修掉升级 0.1.7 后心跳预设静默失效的问题:0.1.7 起宿主不再从文件系统用户目录加载 agent 预设,旧的安装方式失效,症状是审计出现 preset_install skipped-no-root、界面报 Unknown agent preset: heartbeat、闲逛轮报 tools.restrict unknown web_search——预设没挂上,心跳 agent 成了"裸 agent",连 web_search 都看不见。
改为在插件的安装清单里声明式注册预设(与官方 standard 预设同机制),重启即注册,「心跳模式」重新出现在 Agent 预设页。0.1.5 及更早的宿主仍走原来的文件安装路径,两边都不断。
web_search(不抓正文);无 persona 行——部署人格与心跳提示词已足够,不能被 "You are a coding agent" 盖掉。~/.dsh/.agent-presets 下那份是你手改过的,它不再生效。0.1.7-rc.2(实机验收通过)data/settings/ui.json)< 宿主 patch 覆盖。⚠️ v1.6.3 有 bug,请升级到 v1.6.4。
修复:设置卡「闲着模式」开关的渲染语法错误——该语法错误会让脚本加载的客户端 bundle 无法注册,Web 界面报「Failed to load plugins」而无法进入。v1.6.4 修复此错误,设置卡可正常渲染,功能与 v1.6.3 一致。
v1.6.3 的更新内容(并入本版本)——闲着模式(默认关闭):当素材池为空、而用户打开了「闲着模式」开关时,心跳改用本跳画像 digest 的话题切面兜底,仍走原有投递链路主动搭话(每日上限、静默时段等闸门照常生效)。未开启时维持原来的「空池即沉默」。
heartbeat.idleMode(默认 false),可在设置卡「节律配置」里切换,保存即时生效。补丁:画像合并(consolidation)白名单修复——画像从出生就空的问题根因在 buildConsolidationPrompt 从没把 profile-schema.json 的分区白名单传给裁决模型:引擎室凭直觉自创分区(如 background/relation/preference)全被 partition not in schema 拒绝,导致增量几乎 100% 被拒、画像长期为空。本次:
cursors.json#<时间戳> 而非带 chat# 前缀。acg/hardware/audio/writing/life、heartbeat/dsh/zcode、interaction/boundary、background/social 等 topic)。profile rebuild 写明文 profile.json 的问题(改回 DPAPI 加密写)。补丁:反刍轮超时降级——决策轮(反刍)在 240s 预算内没等到模型回话时,不再把整跳记成异常:改为记 decision_deferred 审计、best-effort 取消孤儿轮次、本跳按沉默处理,素材自动留到下一跳(与表达轮 spoke_deferred 同一语义)。同时在反刍提示词里钉死一条纪律:画面与窗口只用于写「他此刻大概在:」,即使画面出现想查的内容也不发起搜索、不调用工具。
素材闭环——截图→视觉识别→引擎室总结→投递→聊天→观察沉淀→consolidation 生成聊天种子→素材池→反刍投递,全链路打通:
topic(话题库存)/ chat(聊天长出)两类,分池上限 16 + 14;聊天种子有时效性——投递过 1 次即退休(话题类仍是 2 次)。data/settings/vision.json 可覆盖),不再受 ModLens 默认链探测干扰。0.1.5 下节律配置失效:v1.5.x 起在 0.1.5 宿主上 UI 保存不生效、重启回默认(dsh-settings 包缺失 + 其 0.1.5 API 变更双重原因)。现已适配两代 API 并把依赖归位——0.1.5 用户务必升级。元数据补全,无行为改动——只影响安装与生态对接:
package.json 补 repository / homepage / bugs / keywords,npm 包与 GitHub 仓库正式关联;@deepseek-ai/dsh-settings 改以 peerDependencies 声明(此前只在 devDependencies,靠宿主环境碰巧解析到);移除两个从未被代码引用的 dependencies;screenshots.json:插件市场详情页按声明顺序展示设置页卡片截图。反刍/投递改版——说不说的决定权从引擎室交给目标会话里的 agent,引擎室只备料:
no material)。non-Chinese output discarded——目标会话 agent 收到素材包后爱调工具时,末行落在收尾标签上被误拦。v1.5 起跳过工具收尾标签、取最后一个含中文的行,整段无中文才拒。兴趣范围 / 浏览时段卡片管理(决策 D22):
M7:状态栏与自研时间注入——心跳的"在场感"从引擎室走进日常会话:
dsh-time-context 停用,时间注入唯一归属心跳插件;适配 DSH 0.1.5-rc.2:诊断兼容 assistant/attempt 事件形态(C19)、会话格式 v3 迁移适配(C20)、新增旧会话修复工具 repair-v0-members.mjs;v1.2.1 修复 0.1.5 下卡片 RPC 整体报 405(自定义通道在严格服务解析下不可用,迁移为 /api 精确路由,C21)。
适配 DSH 0.1.2-rc.1:Session.events 移除、模型路由需显式传参、client 注册 id 强校验、会话标题投影迁移等六项宿主契约变化全数适配;心跳预设改为首次启动自动安装(一条 dsh plugin add 完成部署);表达从"沉默是常态"改为分寸优先(默认倾向开口);投递目标自动拉活;会话绑定投递/观察双开。
首个正式版:七相主循环、素材池 / 画像 / 闸门、DPAPI 加密与焚毁、审计留痕、设置页卡片。
CLASSIFICATION EVIDENCE
系统优先读取 GitHub Topics,再与站内分类词典和词根规则比对。当前命中: 无有效分类标签。