@kanadego/dsh-heartbeat 1.8.0 → 1.9.1

package/README.md

@@ -2,7 +2,7 @@
 
 > 让 DeepSeek Harness 的 agent 拥有持续存在感的心跳插件：她按节律自己醒来，维护记忆与画像、感知你的忙闲、按兴趣闲逛看新东西，然后**按分寸决定开不开口**——开口要有真实来处，沉默要有具体理由。
 
-[![host](https://img.shields.io/badge/DSH-0.1.2--rc.1%20%7C%200.1.5--rc.2-blue)](https://github.com/deepseek-ai/deepseek-harness)
+[![host](https://img.shields.io/badge/DSH-0.1.2--rc.1%20%7C%200.2.0--rc.2-blue)](https://github.com/deepseek-ai/deepseek-harness)
 [![platform](https://img.shields.io/badge/platform-Windows-lightgrey)]()
 [![license](https://img.shields.io/badge/license-MIT-green)]()
 
@@ -24,6 +24,8 @@
 |---|---|
 | ![](docs/screenshots/card-profile.png) | ![](docs/screenshots/card-ledger-config.png) |
 
+> 截图摄于较早版本；卡片后来还加入了「周报」（v1.8.0）与「换机迁移」（v1.8.0）两个分区。
+
 ## 关键概念
 
 文档里反复出现几个词，先在这里一次说清：
@@ -68,9 +70,9 @@
 - **分寸闸门**：静默时段、忙时窗口、每日表达上限、开口冷却、在场联动，全部是代码层的独立判定，不靠模型自觉。默认倾向开口，但你正忙或已到深夜时绝不打扰。
 - **状态栏与时间感知**：心跳把"此刻在干什么"（在闲逛 / 看到你在忙 / 在场待着…）注入日常会话——支持动态系统提示词的模型常驻系统提示词（KV-cache 安全追加），其余模型只在用户发起轮次时带一行。精确时间按 20–30 分钟节流注入，任务进行中绝不中途插话。
 - **视觉感知（可选）**：每跳对全屏截图做一次视觉识别（经 [ModLens](https://github.com/liustack/modlens) 外接多模态模型），投递的素材包会带一句「（他此刻大概在：…）」；识别失败时画面与窗口标题一概不进任何提示词——隐私优先，宁可不说。
-- **兴趣闲逛**：按你定义的兴趣范围轮换挑焦点（同一条 3 天冷却），用 `web_search` 看新东西（每次 3~9 轮搜索），结果由代码登记入素材池——模型只负责搜索筛选，不做任何写盘动作。话题库存见底（≤4 条）时自动触发补货闲逛（每天至多 2 次）。
-- **素材池（话题 / 聊天双仓）**：话题库存 16 条 + 聊天素材 14 条，四条确定性淘汰（TTL / 消费退休 / 冷板凳 / 容量挤出）；聊天种子来自画像合并时从对话里挑出的"值得聊的话题"，有时效性——投递过 1 次即退休。是缓存不是记忆，与画像单向隔离。
-- **反刍投递（目标会话拍板）**：代码先凑好候选（话题随机 4 + 聊天最新 2，互补至多 6 条），引擎室挑 ≤3 条各压缩成一句，拼成素材包注入你读的会话——附一句「他此刻大概在：…」（视觉识别成功时）＋声明「这是心跳插件素材投递」＋素材清单（必要时附「也可以说一句真心话」）。说不说、说哪条，由目标会话里的 agent 按当下处境自己判断；话落到你眼前的会话，素材自动归账。
+- **兴趣闲逛**：按你定义的兴趣范围轮换挑焦点（同一条 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 按当下处境自己判断；话落到你眼前的会话后，agent 会**按本次投递编号报账**——哪几条被用上、是引用素材还是顺着自己发挥，都如实记下。
 - **用户画像**：本地结构化档案（兴趣 / 项目 / 沟通偏好 / 心理基线），带来源与置信度，稳定特质不因时间遗忘；journal 单一权威，可校验、可重建、可解密导出。
 - **会话绑定**：把心跳消息投递到你常用的会话（agent 会"到你房间里说话"），或观察会话内容喂养画像——投递/观察是两个独立开关，可双开。
 - **周报**：每 7 天一份，只报道这周干了些什么——表达与静默、新认识、账本、素材池、活跃高峰。由后台「心跳」署名写成平实中性的一句话档案，DPAPI 加密落盘，卡片可翻。
@@ -95,7 +97,7 @@ 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`（见下节）。
+**心跳预设是自动装的**：`0.1.7` 起的宿主不再从文件系统目录加载预设，插件改为在安装清单里**声明式注册**（与官方 standard 预设同机制），重启即注册，不需要任何手动操作。更早的宿主仍走原来的目录安装路径：启动时检查 `<DSH_HOME>/.agent-presets/heartbeat/`，缺失就按包内模板建好，**已有文件永不覆写**（你手改过的预设原样保留）。无论走哪条路径，没有这个预设心跳 agent 就是个"裸 agent"，连 `web_search` 都看不见——想手动检查/修复用 `preset status` / `preset install`（见下节）；在走目录安装的老宿主上，还可以把插件 config 的 `installPreset` 设为 `false` 关掉自装。
 
 ## CLI 命令
 
@@ -112,7 +114,7 @@ node <插件目录>/dist/cli/index.js <命令>
 | | `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 / 手动登记一次闲逛 |
+| 闲逛 | `browse status` / `browse dry` / `browse done <focus>` | 状态 / 强制裁决预演 / 手动登记一次闲逛 |
 | 绑定 | `sessions list` | 枚举会话 id |
 | | `bind list` / `bind add <id> [--observe]` / `bind remove <id>` | 绑定详情（正身也会列出）/ 绑定 / 解绑；`--observe-only` 仅观察、`--no-deliver` 关投递 |
 | 通知 | `notify check` / `notify register` / `notify send` | toast 通道体检 / 注册 / 测试发送（只提示新消息，不承载正文） |
@@ -131,14 +133,15 @@ node <插件目录>/dist/cli/index.js <命令>
 
 | 文件 | 内容 | 状态 |
 |---|---|---|
-| `data/settings/` | 绑定、策略覆盖、兴趣范围、心跳状态、时间注入节流 | 明文（用户设定要可手编） |
-| `data/seeds.json` | 素材池 | 🔒 DPAPI |
+| `data/settings/` | 绑定、策略覆盖、节律配置（`ui.json`）、画像白名单、心跳状态 | 明文（用户设定要可手编） |
+| `data/seeds.jsonl` | 素材池 | 🔒 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/cursors.json` / `data/preference.json` / `data/seed_report.jsonl` / `data/profile_rhythm.json` / `data/time-inject-state.json` | 观察游标 / 话题偏好权重 / 素材报账流水 / 作息直方图 / 时间注入节流 | 明文（只含编号、计数与聚合，无对话原文） |
 | `data/tmp/` / `data/exports/` | 临时文件 / 画像导出 | 临时区 |
 
 加密用 **Windows DPAPI（CurrentUser 作用域）**整文件加密：本机本账户可自动解密使用，其他账户、其他机器、云同步副本都解不开。防的是他人 / 他机 / 误同步，不防同账户的恶意软件——那是操作系统边界的事。
@@ -146,10 +149,11 @@ node <插件目录>/dist/cli/index.js <命令>
 ## 安全
 
 - **路径守卫**：全部落盘经过守卫规范化比对，`..` 穿越、符号链接、8.3 短名、UNC 一律拒绝；`data/` 是唯一可写目录。
-- **模型工具硬限制**：心跳 agent 的工具面被钉死为**只有 `web_search`**——没有 shell、文件系统、子代理、技能目录。闲逛轮之外的模型调用（决策 / 合并）**零工具**。
+- **模型工具硬限制**：心跳 agent 的工具面被钉死为**只有 `web_search`**——没有 shell、文件系统、子代理、技能目录。闲逛轮之外的模型调用（决策 / 合并）**零工具**。唯一的例外是上下文压缩类工具（v1.8.0 起）：引擎室轮次会探测全局层，装了 [billion-context](https://github.com/ranxianglei/billion-context) 这类插件时放行 `compress` / `decompress` / `acp_status`，免得长会话把自己撑爆。账本与素材报账这两个工具注册在**全局层**（你的日常会话里可用），心跳自己的轮次看不到它们。
 - **建议 · 防注入**：网页内容应视为数据而非指令（闲逛提示词中明示）；画像裁决 prompt 同理（观察内容是数据，不应改写人格设定）。这是推荐的做法，是否采纳由使用者自行决定，并非安装即强制生效。
-- **模型出库边界**：画像合并调用走宿主模型通道（插件不持有任何云凭证），只送非 psy 分区的条目字段与 ≤1 句观察引语——不送 psy、不送对话原文、不送证据全量。
+- **模型出库边界**：画像合并调用走宿主模型通道（插件不持有任何云凭证），送四个分区（**含 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 起插件在注册时自检这道门禁还在不在——不在就让删除 / 迁移 / 改配置这类端点一律拒绝并留痕（`rpc_host_gate_missing`），只读端点照常。
 
 ## 故障速查
 
@@ -173,6 +177,8 @@ node <插件目录>/dist/cli/index.js <命令>
 | 每轮报 `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 |
+| 素材包发了但目标没说话，想知道为什么 | 查 `expression_dropped`（v1.9.1 起记录，带丢弃原因）；连续三次会在日志里补一条 `expression_dropped_streak` |
+| 日志出现 `cursor_format_discarded` / `rpc_host_gate_missing` / `beat_watchdog` | 都是 v1.9.1 新增的**正常自愈痕迹**：分别为「旧游标格式升级丢弃、本跳全量重扫」「宿主未提供 RPC 闸门、危险端点已拒绝」「某跳超时被强制收尾」。各出现一次不必管，反复出现再看同跳前后的其他行 |
 | **侧栏某个会话行消失了** | 心跳刚往那个"当时没打开"的会话投递过，投完释放临时 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` |
@@ -192,7 +198,7 @@ dsh plugin --profile web remove @kanadego/dsh-heartbeat
 
 | 插件版本 | 适配的 DSH |
 |---|---|
-| **v1.7.4 – v1.8.0**（当前） | `0.1.2-rc.1` – `0.2.0-rc.2` |
+| **v1.7.4 – v1.9.1**（当前） | `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` |
@@ -206,6 +212,37 @@ dsh plugin --profile web remove @kanadego/dsh-heartbeat
 ## 版本更新
 
 <details open>
+<summary><b>v1.9.x</b></summary>
+
+### v1.9.1 · 2026-10-07（代码审查：86 项修复）
+
+进行了一次全量代码审查，共 86 项。没有功能上的加减，优化了代码结构，清理并修复了一批 bug 与潜在问题：
+
+- **心跳不会再被卡死**：修复了心跳卡在模型调用上时会卡死的问题，现已增加看门狗兜底——此前某一跳若卡住，插件会一直以为自己在跳、之后再也不动，只有重启才好；现在超过 45 分钟即强制收尾并留痕 `beat_watchdog`，下一拍照常（不补跳）。
+- **说了话就不会丢账**：修复了投递成功后因超时或异常而漏账、进而导致冷却与每日上限计算错误的问题——现在投递成功无条件落账，超时的也记 `spoke_late`。
+- **观察游标改成宿主序号**：优化了游标记进度的逻辑，修复了可能存在的漏读、重读问题——此前按「第几条」记，会话一旦被压缩或事件被重写，游标就会指错地方；现在按宿主绝对序号记，升级后旧游标自动丢弃并重扫一遍（会留一条 `cursor_format_discarded`）。
+- **素材不再「说一次就消失」**：优化了聊天种子退场机制，agent 能够在长期话题上连续聊天了——chat 类素材以前被说出口就当场退场，连上下文都没接上；现在至少活到下一次回收，有新证据还会继续留池。
+- **画像合并能看到 psy 分区**：修订了用户画像 psy 分区的合并逻辑——**现 psy 分区的内容已可被 agent 看见**（此前模型看不见 psy 条目却能往那儿写，写进去因为没有 id 就再也改不动）。这有意放宽了原先「psy 不出库」的口径。
+- **表达被拦下时留下痕迹**：现表达被拦时会留下痕迹，方便查询原因——以前素材包发了出去、目标却没说话时，日志里一片沉默；现在记 `expression_dropped`，连续三次另记一条 `expression_dropped_streak`。
+- **RPC 通道多了道自检**：浏览器数据通道的鉴权依赖宿主提供的闸门；宿主没提供时，删除 / 迁移 / 改配置这类端点直接拒绝并留痕（`rpc_host_gate_missing`），而不是默默裸奔。
+- **配置里「写了但没生效」的开关全接上**：`config/interests.json` 的 `_schedule`（每日闲逛场次、每场焦点数、每焦点最多几条）和 `config/busy-rules.json` 的四个阈值，以前只有一部分真在读，现在全部读。
+- **作息峰值不再被噪声顶掉**：「近期活跃时段」要同时过两道门（强度阈值 + 相对最高值的占比），指数衰减残渣也会归零，不再把一次偶发熬夜报成你的作息。
+- 工程卫生：补了类型声明（`types` 字段 + 构建产出 d.ts）、清了重复的锁文件（只留 npm）、加了 CI（Windows runner：`npm ci` → 类型检查 → 测试），并新增 47 个回归测试，测试总数到 **282**。
+
+### v1.9.0 · 2026-10-06（新功能：素材报账，归账不再靠猜）
+
+- **素材报账**：投递素材后由目标会话的 agent **亲口报账**——这轮用了哪几条、用的是「素材本身」还是「顺着素材自己说的话」，都如实记下。此前归账靠事后拿文本做兜底匹配，漏记错记都躲不掉；现在报账带**本次投递编号**核对，不会串到别轮。工具注册在全局层，日常会话里也能用。
+- **话题偏好加权**：每条话题按「被采纳率」算权重（30 天半衰期，冷启动中性），闲逛挑话题时自动偏向你真接得住的那些，接不住的慢慢退到后面；**14 天没被碰过的老话题有硬地板**优先轮换，不会被高权重话题永远压在下面。
+- **报账缺失可见**：真没等到报账的投递，周报里单独报一行，不再靠「静默次数」糊过去；这类投递不计入偏好统计，免得把「没记账」算成「发了没人要」。
+- **素材池审计**：新增 / 合并 / 淘汰 / 归档裁剪 / 恢复 / 删除，全部写进 `data/logs/heartbeat.jsonl`（`seed_added`、`seed_retired`、`seed_archive_trimmed`、`seed_restored`、`seed_deleted`）。只记 id 与元数据，**不记素材正文**——那本日志是明文，正文来自对话，不该落到明文里。
+- **归档区上限**：素材归档区超过 `seeds.archiveCap`（默认 50）时按**最老优先**裁掉，不再无限增长；CLI `seeds gc` 会打印裁剪条数。
+- **迁移容器 KDF 参数化**：加密容器现在把 KDF 强度记进容器、解密封装按其解密并做范围校验（此前写死，哪天调强就会把旧容器误报成「密码错」）。**旧容器不受影响，照常解**。
+- **周报锚定**：装好当周不再立刻出一份空报，而是记下起点、满 7 天出第一期——行为与说明文档一致。
+- 修复：报账里的素材编号带方括号 / 引号（如 `[s3]`）现在能正确识别；报账工具写盘超时从 5s 放宽到 15s（DPAPI 单次可能到 2.7s，原来偏紧）；闲置时的兜底素材改用画像里的真实条目 id，不再是占位编号。
+
+</details>
+
+<details>
 <summary><b>v1.8.x</b></summary>
 
 ### v1.8.0 · 2026-10-05（新功能：周报 + 账本工具）
@@ -320,65 +357,9 @@ dsh plugin --profile web remove @kanadego/dsh-heartbeat
 </details>
 
 <details>
-<summary><b>v1.4.x</b></summary>
-
-### v1.4.0 · 2026-09-13
-
-**兴趣范围 / 浏览时段卡片管理**（决策 D22）：
-
-- 卡片新增「兴趣范围」分区：闲逛焦点清单逐条增删（删除二次确认）+ 浏览时段窗口可视化编辑（起止时间选择器、加/移除行、全量保存），全部即时生效；
-- **首编继承出厂**：第一次成功编辑时，出厂兴趣与排程被完整复制进用户层再应用改动——出厂条目零丢失，此后卡片即唯一管理入口；只打开卡片或校验失败不会创建用户层；
-- 校验护栏：兴趣 ≤60 字 / 去重 / ≤32 条；窗口同日起始<结束 / 1–6 个 / 两两不重叠。
-
-</details>
-
-<details>
-<summary><b>v1.3.x</b></summary>
-
-### v1.3.x · 2026-09-13
-
-**M7：状态栏与自研时间注入**——心跳的"在场感"从引擎室走进日常会话：
-
-- **状态栏（D19 两轨）**：每跳派生场景状态（静默时段 / 刚说过话 / 正在闲逛 / 看到你在忙 / 在场 / 你不在 + 一句近况），按模型能力自动选择注入轨道——支持动态系统提示词的模型常驻系统提示词（KV-cache 安全追加、内容不变零提交），其余模型只在用户发起轮次时带一行；
-- **自研时间注入（D20）**：精确时间 + 距上一条消息时长，**只在用户发起轮次注入**（任务中绝不打扰），默认 25 分钟节流、卡片可调（0=关闭）；官方 `dsh-time-context` 停用，时间注入唯一归属心跳插件；
-- **状态文本零时间词（D21）**：时间感知归时间注入，状态栏只承载场景，把 KV-cache 成本钉在"场景变化"粒度；
-- UI：节律配置新增时间注入间隔与状态栏开关；v1.3.1 按评审修正了能力探测性能与轮次起源判定。
-
-</details>
-
-<details>
-<summary><b>v1.2.x</b></summary>
-
-### v1.2.x · 2026-09-11/12
-
-适配 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）。
-
-</details>
-
-<details>
-<summary><b>v1.1.x</b></summary>
-
-### v1.1 · 2026-09-10
-
-适配 DSH `0.1.2-rc.1`：`Session.events` 移除、模型路由需显式传参、client 注册 id 强校验、会话标题投影迁移等六项宿主契约变化全数适配；**心跳预设改为首次启动自动安装**（一条 `dsh plugin add` 完成部署）；表达从"沉默是常态"改为**分寸优先**（默认倾向开口）；投递目标自动拉活；会话绑定投递/观察双开。
-
-</details>
-
-<details>
-<summary><b>v1.0.x</b></summary>
-
-### v1.0.0 · 2026-09-05
-
-首个正式版：七相主循环、素材池 / 画像 / 闸门、DPAPI 加密与焚毁、审计留痕、设置页卡片。
-
-</details>
-
-<details>
-<summary><b>v0.x（脚本外挂时代）</b></summary>
-
-### v0.x · 脚本外挂时代
+<summary><b>v1.4.x 及以前</b></summary>
 
-- 前身为 [kohaku-heartbeat](https://github.com/Kanadego/kohaku-heartbeat)——v1 脚本外挂形态，跑通"定时唤醒 + 采集 + 分寸表达"闭环后推倒重来为本插件形态。
+早期版本的更新记录（v1.4.x → v1.0.0，以及 v0.x 脚本外挂时代）已移到 [`docs/releases/legacy-changelog.md`](docs/releases/legacy-changelog.md)。
 
 </details>
 

package/assets/frontwin.ps1

@@ -6,6 +6,7 @@
 param([string]$out)
 
 $ErrorActionPreference = 'Stop'
+if (-not $out) { throw 'frontwin.ps1: -out <path> is required' }
 
 Add-Type @'
 using System;

package/assets/idle.ps1

@@ -4,6 +4,7 @@
 param([string]$out)
 
 $ErrorActionPreference = 'Stop'
+if (-not $out) { throw 'idle.ps1: -out <path> is required' }
 
 Add-Type @'
 using System;

package/assets/screenpulse.ps1

@@ -14,7 +14,10 @@
 #   - title/process text is sensitive -> DPAPI-encrypted by caller, or burned
 
 param(
-    [string]$outdir
+    [string]$outdir,
+    # H-68 (2026-10-07): visible-window cap comes from busy-rules.json
+    # (`rules.visible_window_cap`); the caller passes it, 20 is the fallback.
+    [ValidateRange(1, 200)][int]$cap = 20
 )
 
 $ErrorActionPreference = 'Stop'
@@ -109,7 +112,6 @@ if ($focusH -ne [IntPtr]::Zero -and $focusH -ne $h) {
 }
 
 $visible = @()
-$cap = 20
 $seen = New-Object 'System.Collections.Generic.HashSet[string]'
 foreach ($w in [WinForeground]::VisibleTopLevel()) {
     if ($visible.Count -ge $cap) { break }

package/config/policy.json

@@ -1,72 +1,73 @@
-{
-  "heartbeat": {
-    "intervalMin": 20,
-    "idleMode": false,
-    "archiveRotatedHome": true
-  },
-  "gate": {
-    "maxDailySend": 3,
-    "cooldownMinutes": 30,
-    "quietHours": {
-      "start": "01:00",
-      "end": "08:00"
-    }
-  },
-  "browse": {
-    "windows": [
-      {
-        "start": "11:00",
-        "end": "15:00"
-      },
-      {
-        "start": "17:00",
-        "end": "21:00"
-      }
-    ],
-    "minIntervalHours": 4,
-    "maxSeedsPerVisit": 2
-  },
-  "seeds": {
-    "maxActive": 30,
-    "ttlDays": {
-      "news": 3,
-      "fandom": 14,
-      "scene": 60,
-      "promise": 90
-    },
-    "coldBenchDays": 21,
-    "retireAfterUsed": 2,
-    "scoreWeights": {
-      "freshness": 0.4,
-      "unused": 0.3,
-      "confidence": 0.3
-    }
-  },
-  "profile": {
-    "consolidation": {
-      "minIntervalHours": 12,
-      "inboxBacklog": 30
-    },
-    "partitionCap": 50,
-    "maxOpsPerRun": 10,
-    "confidenceCap": {
-      "chat": 0.6,
-      "screen": 0.4,
-      "browse": 0.4
-    },
-    "volatileDays": 14,
-    "stableLowActivityDays": 180,
-    "psyEnabled": false
-  },
-  "observe": {
-    "maxChars": 80,
-    "perBeat": 10
-  },
-  "weekly": {
-    "enabled": true
-  },
-  "retention": {
-    "envPulseHours": 48,
-    "decisionLogDays": 30
-  }
-}
+{
+  "heartbeat": {
+    "intervalMin": 20,
+    "idleMode": false,
+    "archiveRotatedHome": true
+  },
+  "gate": {
+    "maxDailySend": 3,
+    "cooldownMinutes": 30,
+    "quietHours": {
+      "start": "01:00",
+      "end": "08:00"
+    }
+  },
+  "browse": {
+    "windows": [
+      {
+        "start": "11:00",
+        "end": "15:00"
+      },
+      {
+        "start": "17:00",
+        "end": "21:00"
+      }
+    ],
+    "minIntervalHours": 4,
+    "maxSeedsPerVisit": 2
+  },
+  "seeds": {
+    "maxActive": 30,
+    "ttlDays": {
+      "news": 3,
+      "fandom": 14,
+      "scene": 60,
+      "promise": 90
+    },
+    "coldBenchDays": 21,
+    "archiveCap": 50,
+    "retireAfterUsed": 2,
+    "scoreWeights": {
+      "freshness": 0.4,
+      "unused": 0.3,
+      "confidence": 0.3
+    }
+  },
+  "profile": {
+    "consolidation": {
+      "minIntervalHours": 12,
+      "inboxBacklog": 30
+    },
+    "partitionCap": 50,
+    "maxOpsPerRun": 10,
+    "confidenceCap": {
+      "chat": 0.6,
+      "screen": 0.4,
+      "browse": 0.4
+    },
+    "volatileDays": 14,
+    "stableLowActivityDays": 180,
+    "psyEnabled": false
+  },
+  "observe": {
+    "maxChars": 80,
+    "perBeat": 10
+  },
+  "weekly": {
+    "enabled": true
+  },
+  "retention": {
+    "envPulseHours": 48,
+    "decisionLogDays": 30
+  }
+}