@stardustlc/dsh-dream 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.5.1（2026-09-29）
+
+- **修复两个已发布缺陷**（0.5.0 起）：① 日记文件开头有 UTF-8 BOM 时整份日记被读空；② 心境聚合用普通对象做映射，`__proto__` 键被吞、`constructor` 等键会把计数变成字符串（`"function Object()…1"`）。现在 BOM 会被剥离，聚合用无原型对象后返回普通副本，并新增 `skippedLines` 让坏行可诊断。
+- **检索策略修正（R1/R3/R4/R5）**：`dream_context` 默认不注入候选（`candidate-hold`）与无证据条目（`no-evidence`）；`applicability.versions` 只在包名被识别时参与判定，版本不满足记 `version-mismatch`；预算改为按排名整条装入、遇第一条放不下即停（`budget-stop`，`rankInversionCount` 恒 0），条件与例外永不截断；`RetrievedLesson` 增加 `revision`（`dream_review` 的 `expectedRevision` 因此可达），`dream_learn.evidence` 改为可选。
+- **证据纪律（R2′）**：任何 `verification:"read"` 的证据让经验初始即为 `usable`；其中用户明确纠正记 `review{decision:accepted, actor:user}`，其余 read 记 `unreviewed`；只有 `claimed` 证据或无证据才停在 `candidate`。SKILL.md 同时写明「只有真的读到来源才能标 read，自我判断一律 claimed」，防止模型自称 read 自我提权。
+- **存储可诊断与前向兼容（R6/R7）**：`stats()` 拆分 `orphanEvents` / `firstReplayedEventId` / `unsupportedVersions`（与 `badLines` 分开）并给出 `replayMode`；`index.json` 增加 checkpoint（偏移 + 前缀哈希 + 末事件 id，校验不符回退全量回放），截断不再静默丢实体；`validateLesson(value, options?)` 支持 `accept`/`migrate` 与 `LESSON_MIGRATIONS` 占位；事件增加 `requestHash`（同幂等键不同内容 → `duplicate` 错误而非静默返回旧快照）；新增只读 `diagnose()`；文件锁增加 `bootId` 与心跳，超限给可操作错误而不静默抢占。
+- **面板**：经验卡显示适用条件与例外；`truncated` 或存在坏行时显示提示行并注明 `events.jsonl` 未被改动。
+- **验收**：L1 七场景断言（S1/S5 命中、S2/S3/S4/S6/S7 零注入、`rankInversionCount=0`）**9/9**；证据纪律 5/5；旧行为基线 4/4（旧日记与既有六工具输出只增不减、只读零写入）；全量 **204 项 / 203 通过 / 1 默认跳过**（并发压测需 `DSH_DREAM_STRESS=1`，8 进程 × 8 次实测不丢）；`tsc`、`node --check lib/client.js`、官方加载器回归通过。
+- **已知限制（未达标，下一批修）**：读/写路径在知识库增长时仍是 O(历史)——50k 条证据时单次读操作数百毫秒、逐条追加呈二次增长。checkpoint 已能避免"截断丢实体"，但尚未把读路径变成增量。本版**不承诺大知识库下的性能**；下一批计划 `evidenceKeys` 常数时间去重与索引增量更新。
 ## 0.5.0（2026-09-29）
 
 - **从「反思」升级为「有来源的经验」**：新增 `dream_learn`（提交候选经验 + 证据，校验 / 脱敏 / 去重 / 按项目或全局范围保存）、`dream_context`（任务前取回少量适用经验，只读，默认 5 条 / 3000 字符，硬上限 20 条 / 20000 字符）、`dream_review`（采纳 / 驳回 / 标记过期 / 标记冲突 / 补充证据，强制 `expectedRevision`）。六个既有工具行为不变，输出字段只增不减。

package/README.en.md

@@ -8,13 +8,18 @@
 
 - **Fixes a Desktop boot failure**: the front-end module id now matches the scoped package name (it used to register as `dsh-dream`, so the host retried the bundle and threw `duplicate factory registration`, ending in `1 entry did not activate`). No journal or config migration.
 
+## 0.5.1 update (2026-09-29)
+
+- **Fixes**: a leading UTF-8 BOM used to hide the whole journal; mood keys such as `__proto__`/`constructor` corrupted counts. **Retrieval discipline**: candidates and evidence-free lessons are not injected by default, version checks need package context, and the budget packs by rank. **Evidence discipline**: lessons backed by read evidence start usable; model-claimed only stays candidate.
+- 204 tests (203 passing, 1 opt-in concurrency stress test skipped); L1 acceptance 9/9. Known limit: reads/writes still grow with history on very large libraries.
+
 ## 0.5.0 update (2026-09-29)
 
 - **Three new tools**: `dream_learn` (submit an evidence-backed candidate lesson), `dream_context` (retrieve a few applicable lessons before a task; read-only; 5 items / 3000 characters by default) and `dream_review` (accept / reject / mark stale or disputed / attach evidence; every mutation requires a revision).
 - **New data directory `<journalDir>/knowledge/`**: `events.jsonl` is the authoritative append-only log, `evidence.jsonl` appends evidence, and `index.json` is a disposable derived index. The old `dreams.jsonl` stays read-compatible and is never rewritten.
 - **Masking and scope guarantees**: every new write path runs through `mask.ts` when `maskSecrets` is on; evidence stores only masked one-line summaries plus locators — never hidden reasoning, system prompts, tool arguments or result bodies. Lessons are scoped to a project or global; with an unknown project `dream_context` returns global lessons only and never scans across projects.
 - **Compatibility**: the old journal and the six existing tools (dream_digest / dream_save / dream_journal / dream_recall / dream_bridge / dream_health) keep their behaviour and output fields only grow. No migration is required and no old data is rewritten.
-- **New read-only "Lessons" block** in the panel: state (candidate / usable / disputed / stale / rejected), applicability, scope, evidence summary and last-validated time. Candidates and disputed lessons are visually distinct, and an empty knowledge store has its own empty state. The panel still has no write actions.
+- **New read-only "Lessons" block** in the panel: state (candidate / usable / disputed / stale / rejected), applicability, scope, applicability details (package / versions / platform) and exceptions (only when non-empty), evidence summary and last-validated time. Candidates and disputed lessons are visually distinct, and an empty knowledge store has its own empty state. When the event log is truncated or has bad lines the block shows a notice and says events.jsonl was left untouched. The panel still has no write actions.
 
 ## 0.4.0 update (2026-09-29)
 
@@ -26,7 +31,7 @@ Humans consolidate memories by replaying the day during sleep — dsh-dream give
 
 ## Compatibility
 
-Validation host: Harness `0.2.0-rc.1` built from official sources (commit `407e65c8`) with Node `24.16.0` on 2026-09-29. At 0.4.1 all 112 plugin tests passed in an isolated environment and all 18 plugins mounted together; M1 currently has 169 tests passing (knowledge store / retrieval / host schema contracts for the three new tools / zero-write and masking cases for the read-only route). The plugin registers 9 tools (the 6 original tools plus M1's dream_learn / dream_context / dream_review) and the `dream-protocol` skill, with tool schemas and health-check contracts passing. The 18-plugin joint load will be re-run with the new front end before the M1 release. No live ports or external services were exercised in this round; the panel is reachable on loopback only.
+Validation host: Harness `0.2.0-rc.1` built from official sources (commit `407e65c8`) with Node `24.16.0` on 2026-09-29. The 18-plugin joint load was re-run before the 0.5.0 release: contracts `ok`, **99 tools / 35 skills**, no failing plugins (`suite-0.2.6-compat.json`), with this plugin passing 204/169 tests in that run (the 0.4.1 baseline of 112 also passed). The plugin registers 9 tools (the 6 original tools plus M1's dream_learn / dream_context / dream_review) and the `dream-protocol` skill, with tool schemas and health-check contracts passing. No live ports or external services were exercised in this round; the panel is reachable on loopback only.
 
 Reads v0/v1/v2/v3/v4 plaintext JSONL and multi-frame zstd, legacy packed chunks and embedded streams. Only the newest canonical file is selected per session. PTC child calls retain tool names without double counting; system prompts, reasoning, tool arguments and result bodies are excluded.
 
@@ -55,7 +60,7 @@ Once installed, DSH's **Settings →「梦境日记」(Dream journal)** grows a
 - **Data file**: the panel renders the journal itself — ~/.dsh/.dsh-dream/dreams.jsonl by default ($DSH_HOME/.dsh-dream/dreams.jsonl; an explicit journalDir wins). The storage format is unchanged: one JSON object per line, safe to remove or read with dream_journal.
 - **Privacy**: the panel performs no second-pass masking — masking only happens when a dream is written (maskSecrets), and the panel shows exactly what is already in the file. It does not upload, export or make any network request. The privacy mode at the top blurs reflections and lessons in one click, but it is a display-layer effect only (the DOM still holds plaintext), not encryption. Review the journal before sharing your screen or the JSONL.
 - **Before the first dream**: the panel shows an empty state pointing you to ask the agent to「做个梦」; a single dream renders as one card, with neither the mood strip nor the lessons board left empty and no misleading charts.
-- **Lessons block (M1)**: a read-only "Lessons" block shows each technical lesson's state (candidate / usable / disputed / stale / rejected), applicability, scope, evidence summary and last-validated time. Candidates and disputed lessons get distinct colours and borders, and the empty state is separate from the dream empty state. Data comes from the read-only GET /_dsh/dsh-dream/knowledge route (loopback only; non-GET → 405, non-local Host → 403). There are no accept / edit / delete buttons — use `dream_review` to review.
+- **Lessons block (M1)**: a read-only "Lessons" block shows each technical lesson's state (candidate / usable / disputed / stale / rejected), applicability, scope, applicability details and exceptions (exceptions render only when non-empty), evidence summary and last-validated time. Candidates and disputed lessons get distinct colours and borders, and the empty state is separate from the dream empty state. When the event log is truncated or has bad lines, a notice appears saying events.jsonl was left untouched. Data comes from the read-only GET /_dsh/dsh-dream/knowledge route (loopback only; non-GET → 405, non-local Host → 403). There are no accept / edit / delete buttons — use `dream_review` to review.
 - **Roadmap**: record bridge status via a sidecar (which lessons were written into which AGENTS.md, and when). Not in this release — v1 reads no AGENTS.md and adds no state file.
 
 ## Tools
@@ -68,8 +73,8 @@ Once installed, DSH's **Settings →「梦境日记」(Dream journal)** grows a
 | `dream_recall` | Keyword search across the journal | `query` required |
 | `dream_bridge` | Merge top lessons into AGENTS.md (idempotent marker block) — dreams become long-term memory | `path` required |
 | `dream_health` | Self-check: sessions dir / dream count / config summary | — |
-| `dream_learn` | Submit a candidate technical lesson with evidence (validate / mask / dedupe / scope; evidence-free input stays a candidate) | `kind`, `title`, `action`, `when`, `evidence` required |
-| `dream_context` | Retrieve a few applicable lessons before a task (read-only) | `query` required; `projectId` / `workspaceRoot` / `limit` / `maxChars` / `packageVersion` optional |
+| `dream_learn` | Submit a candidate technical lesson with evidence (validate / mask / dedupe / scope; evidence-free input stays a candidate) | `kind`, `title`, `action`, `when` required; `evidence` optional (defaults to `[]`) |
+| `dream_context` | Retrieve a few applicable lessons before a task (read-only; candidates are held out by default) | `query` required; `projectId` / `workspaceRoot` / `limit` / `maxChars` / `packageName` / `packageVersion` / `includeCandidates` optional |
 | `dream_review` | Review and transition state: accept / reject / mark stale / mark disputed / attach evidence | `action`, `lessonId`, `expectedRevision` required |
 
 `dream_bridge` merges the most frequent dream lessons into a target `AGENTS.md` behind idempotent marker blocks; `dream_journal` also reports mood distribution and top lessons.
@@ -80,8 +85,8 @@ The bundled `dream-protocol` skill teaches the agent when and how to dream (and
 
 The dream journal holds subjective reflections; technical lessons that should be reused go to `<journalDir>/knowledge/`:
 
-- **Candidate → evidence → review**: `dream_learn` stores "when / action / exceptions / scope" together with evidence as a candidate. `verification: read` means the original record was actually read; `claimed` only means the model asserts it (it does not count toward independent support). Use `dream_review` to accept, reject, mark stale or disputed, or attach new evidence — every mutation carries `expectedRevision` and stale writes are rejected.
-- **Budgeted retrieval**: `dream_context` returns at most 5 items / 3000 characters by default (hard caps 20 items / 20000 characters). Conditions and exceptions are never truncated: if an item does not fit, it is omitted whole. Usable lessons outrank candidates; rejected, stale and unresolved disputed lessons are not injected into tasks by default.
+- **Candidate → evidence → review**: `dream_learn` stores "when / action / exceptions / scope" together with evidence as a candidate. `verification: read` means the original record was actually read; `claimed` only means the model asserts it (it does not count toward independent support). Use `dream_review` to accept, reject, mark stale or disputed, or attach new evidence — every mutation carries `expectedRevision` and stale writes are rejected. When the evidence is `kind: "user-correction"` with `verification: "read"`, the lesson starts as `usable` and `review` records `actor: "user"` / `decision: "accepted"` — a user decision outranks model inference; all other evidence starts as `candidate`, and claimed evidence neither counts toward independent support nor overrides a user correction.
+- **Budgeted retrieval**: `dream_context` returns at most 5 items / 3000 characters by default (hard caps 20 items / 20000 characters). Items are packed whole by rank and packing stops at the first item that does not fit (`skipped: budget-stop`); `title / when / action / exceptions` are never truncated, and no half item is ever returned. Candidates and evidence-free non-usable items are held out of task advice by default (`includeCandidates: false`, reported as `candidate-hold` / `no-evidence`); pass `includeCandidates: true` only when explicitly reviewing candidates, and note that candidates rank after usable lessons and must not be treated as verified. Rejected, stale and unresolved disputed lessons are not injected; `applicability.versions` only counts when the package is identified (explicit `packageName` or a package name in the query).
 - **Frequency is not reliability**: resubmitting the same evidence is idempotent; never grind counts by calling `dream_save` / `dream_learn` repeatedly. Repeated occurrences within one session count as a single independent source.
 - **Recoverable storage**: `events.jsonl` is the authoritative append-only event log, `evidence.jsonl` appends evidence and `index.json` is a disposable derived index. Rebuilding the index deletes no source files. When the directory does not exist, the read route returns an empty result and never creates anything.
 - **Removing it**: delete `<journalDir>/knowledge/` to clear lesson memory. The old `dreams.jsonl` journal is unaffected, and older plugin versions can still read it.

package/README.md

@@ -6,13 +6,18 @@
 
 - **修复 Desktop 启动失败**：前端模块注册 ID 现与 scoped 包名一致（此前注册成 `dsh-dream`，宿主会重试加载并抛 `duplicate factory registration`，导致 `1 entry did not activate`）。日记数据与配置不变，无迁移。
 
+## 0.5.1 更新（2026-09-29）
+
+- **修复**：日记 BOM 导致读空、心境键（`__proto__`/`constructor`）污染计数；**检索纪律**：候选与无证据经验默认不注入、版本判定需要包名上下文、预算按排名整条装入；**证据纪律**：读到来源（read）即为可用，模型自我判断（claimed）停在候选。
+- 全量 **204 项 / 203 通过 / 1 默认跳过**；L1 七场景断言 9/9。已知限制：知识库很大时读/写仍随历史线性增长，本版不承诺大库性能。
+
 ## 0.5.0 更新（2026-09-29）
 
 - **新增三个工具**：`dream_learn`（提交带证据的候选经验）、`dream_context`（任务前按项目 / 版本取回少量适用经验，只读，默认最多 5 条、3000 字符）、`dream_review`（采纳 / 驳回 / 标记过期或冲突 / 补充证据，强制携带 revision）。
 - **新数据目录 `<journalDir>/knowledge/`**：`events.jsonl` 是权威追加日志，`evidence.jsonl` 追加证据，`index.json` 是可丢弃重建的派生索引。旧日记 `dreams.jsonl` 仍只读兼容、永不重写。
 - **脱敏与范围承诺**：所有新写盘路径在 `maskSecrets` 开启时先过 `mask.ts`；证据只保存已脱敏摘要和定位信息，不保存隐藏推理、系统提示、工具参数 / 结果正文。经验按项目或全局范围保存，未知当前项目时 `dream_context` 只返回全局经验，绝不跨项目扫描。
 - **兼容性**：旧日记与六个既有工具（dream_digest / dream_save / dream_journal / dream_recall / dream_bridge / dream_health）行为不变、输出字段只增不减；升级不需要迁移，也不会改写旧数据。
-- **只读面板新增「经验」区块**：展示状态（候选 / 可用 / 有冲突 / 待复核 / 已驳回）、适用条件、范围、证据摘要与最近核验时间；候选与有冲突有明确视觉区分，没有经验时是独立空态。面板仍然没有任何写操作。
+- **只读面板新增「经验」区块**：展示状态（候选 / 可用 / 有冲突 / 待复核 / 已驳回）、适用条件、范围、适用（package / versions / platform）与例外、证据摘要与最近核验时间；候选与有冲突有明确视觉区分，没有经验时是独立空态；知识日志被截断或有坏行时显示「events.jsonl 未改动」提示。面板仍然没有任何写操作。
 
 ## 0.4.0 更新（2026-09-29）
 
@@ -26,7 +31,7 @@
 
 ## 兼容性
 
-验证宿主：官方源码构建的 Harness `0.2.0-rc.1`（commit `407e65c8`）+ Node `24.16.0`（2026-09-29）。0.4.1 时 112 项插件测试在隔离环境全部通过，18 个插件共同加载验证通过；0.5.0 共 169 项测试全部通过（新增知识存储 / 检索 / 三个新工具的宿主 schema 契约 / 只读路由零写盘与脱敏用例），本插件注册 9 个工具（6 个既有工具 + M1 的 dream_learn / dream_context / dream_review）与 `dream-protocol` 技能，工具 schema 与健康检查契约通过。18 插件在 M1 发布前会随新版前端再复验一次。本轮未启用真实端口与外部服务；面板仅在本机回环地址下可达。
+验证宿主：官方源码构建的 Harness `0.2.0-rc.1`（commit `407e65c8`）+ Node `24.16.0`（2026-09-29）。18 插件同载复验已在 0.5.0 发布前完成：契约 `ok`、共 **99 个工具 / 35 个技能**、无失败插件（`suite-0.2.6-compat.json`），当次本插件 169/169 项测试通过（0.4.1 基线 112 项同样全过）。本插件注册 9 个工具（6 个既有工具 + M1 的 dream_learn / dream_context / dream_review）与 `dream-protocol` 技能，工具 schema 与健康检查契约通过。本轮未启用真实端口与外部服务；面板仅在本机回环地址下可达。
 
 支持 v0/v1/v2/v3/v4 的普通 JSONL 与多帧 zstd、旧 packed-chunk 行及内嵌 stream；升级留下多代文件时只读取每个会话的最新规范文件。PTC 子工具调用保留工具名且不重复计数，不提取系统提示、推理、工具参数或结果正文。
 
@@ -62,7 +67,7 @@ dsh plugin --profile web remove @stardustlc/dsh-dream
 - **数据文件**：面板读的就是梦境日记本身，默认 ~/.dsh/.dsh-dream/dreams.jsonl（$DSH_HOME/.dsh-dream/dreams.jsonl；配置了 journalDir 时以配置为准）。存储格式不变，仍是每行一条 JSON 的 JSONL，可直接删除或用 dream_journal 读取。
 - **隐私**：面板不做二次脱敏——脱敏只发生在入梦写盘时（maskSecrets），面板原样显示文件里已有的内容。它不上传、不导出、不发起任何网络请求；顶部「隐私模式」可一键模糊正文与教训，但它只是浏览器里的显示效果（DOM 中仍是明文），不是加密。共享屏幕或转发 dreams.jsonl 前请自行确认内容。
 - **还没有梦时**：面板显示空态，提示对 agent 说「做个梦」——它会回放最近的会话、反思之后把第一条梦写进这里；只有一场梦时按单条卡片展示，心境方块与教训榜都不留空、不画失真图表。
-- **经验区块（M1）**：面板下方的只读「经验」区块显示技术经验的状态（候选 / 可用 / 有冲突 / 待复核 / 已驳回）、适用条件、范围、证据摘要与最近核验时间，候选与冲突有独立配色和边框，空态与梦境空态分开。数据来自只读路由 GET /_dsh/dsh-dream/knowledge（仅回环地址可达；非 GET → 405，非本机 Host → 403），没有采纳 / 编辑 / 删除按钮；审阅请用 dream_review。
+- **经验区块（M1）**：面板下方的只读「经验」区块显示技术经验的状态（候选 / 可用 / 有冲突 / 待复核 / 已驳回）、适用条件、范围、适用与例外（exceptions 非空才显示）、证据摘要与最近核验时间，候选与冲突有独立配色和边框，空态与梦境空态分开。知识日志被截断（truncated）或有坏行（badLines）时显示一行提示，并注明 events.jsonl 未改动。数据来自只读路由 GET /_dsh/dsh-dream/knowledge（仅回环地址可达；非 GET → 405，非本机 Host → 403），没有采纳 / 编辑 / 删除按钮；审阅请用 dream_review。
 - **后续计划**：用 sidecar 记录桥接状态（哪些教训、何时写进了哪个 AGENTS.md）。本轮不做——v1 不读取 AGENTS.md，也不新增任何状态文件。
 
 ## 工具一览
@@ -75,8 +80,8 @@ dsh plugin --profile web remove @stardustlc/dsh-dream
 | `dream_recall` | 忆梦：关键词检索梦境 | `query` 必填 |
 | `dream_bridge` | 渡梦：把高频教训幂等合并进 AGENTS.md，梦变成长期记忆 | `path` 必填；`maxLessons` 可选 |
 | `dream_health` | 自检：会话目录/梦境计数/配置汇总 | 无 |
-| `dream_learn` | 提交候选技术经验及证据（校验 / 脱敏 / 去重 / 按范围保存；无证据只能留在候选） | `kind`、`title`、`action`、`when`、`evidence` 必填 |
-| `dream_context` | 任务前取回少量适用经验（只读） | `query` 必填；`projectId` / `workspaceRoot` / `limit` / `maxChars` / `packageVersion` 可选 |
+| `dream_learn` | 提交候选技术经验及证据（校验 / 脱敏 / 去重 / 按范围保存；无证据只能留在候选） | `kind`、`title`、`action`、`when` 必填；`evidence` 可选（缺省 `[]`） |
+| `dream_context` | 任务前取回少量适用经验（只读；候选默认不注入） | `query` 必填；`projectId` / `workspaceRoot` / `limit` / `maxChars` / `packageName` / `packageVersion` / `includeCandidates` 可选 |
 | `dream_review` | 审阅与状态流转：采纳 / 驳回 / 标记过期 / 标记冲突 / 补充证据 | `action`、`lessonId`、`expectedRevision` 必填 |
 
 ### 示例
@@ -103,8 +108,8 @@ dream_review { action: "accept", lessonId: "lesson-…", expectedRevision: 1 }
 
 梦境日记是主观感悟；真正要复用的技术经验走 `<journalDir>/knowledge/`：
 
-- **候选 → 证据 → 审阅**：`dream_learn` 把「何时 / 做什么 / 例外 / 范围」和证据一起保存为 candidate；`verification: read` 表示读到原记录，`claimed` 只表示模型声称（不计入独立支持数）。用户采纳、驳回、标记过期或冲突用 `dream_review`，所有修改都要带 `expectedRevision`，过期写入会被拒绝。
-- **取回有预算**：`dream_context` 默认最多返回 5 条、3000 字符（硬上限 20 条 / 20000 字符）；条件与例外不会被截断，放不下就整条不返回。可用经验优先于候选；已驳回、已过期和冲突未解决的默认不注入任务。
+- **候选 → 证据 → 审阅**：`dream_learn` 把「何时 / 做什么 / 例外 / 范围」和证据一起保存为 candidate；`verification: read` 表示读到原记录，`claimed` 只表示模型声称（不计入独立支持数）。用户采纳、驳回、标记过期或冲突用 `dream_review`，所有修改都要带 `expectedRevision`，过期写入会被拒绝。当证据为 `kind: "user-correction"` 且已读到原文（`verification: "read"`）时，该经验初始状态直接是 `usable`，`review` 记 `actor: "user"`、`decision: "accepted"`——用户决定优先于模型推测；其余证据一律从 candidate 起，claimed 不计独立支持、也不能覆盖用户纠正。
+- **取回有预算**：`dream_context` 默认最多返回 5 条、3000 字符（硬上限 20 条 / 20000 字符）；按排名整条装入，遇到第一条放不下就停止（`skipped: budget-stop`），`title / when / action / exceptions` 永不截断，绝不返回半条。候选与无独立证据的非 usable 条目默认不注入（`includeCandidates: false`，记 `candidate-hold` / `no-evidence`）；显式 `includeCandidates: true` 可在审阅候选时看到，且候选排在可用经验之后——未经审阅不得当作已证实结论。已驳回、已过期和冲突未解决的不注入；`applicability.versions` 只在包名被识别（显式 `packageName` 或 query 中出现包名）时参与判定。
 - **频率不是可靠性**：同一条证据重复提交是幂等的；不要在同一个会话里反复 `dream_save` / `dream_learn` 刷次数。同一个会话中重复出现的教训只算一次独立来源。
 - **存储可恢复**：`events.jsonl` 是权威事件日志（追加写），`evidence.jsonl` 追加证据，`index.json` 是可丢弃重建的派生索引；重建索引不删除任何原文件。目录不存在时读取接口返回空结果，不会为了读而创建目录。
 - **删除新数据**：直接删除 `<journalDir>/knowledge/` 即清空经验记忆；这不会影响 `dreams.jsonl` 里的旧日记，旧版本插件也仍能读取旧日记。

package/lib/client.js

@@ -6,7 +6,8 @@
 // 教训榜、按时间倒序的梦卡片；再只读展示 M1 的技术经验（<journalDir>/knowledge/）。
 // 数据来自插件自己的同源只读路由 GET /_dsh/dsh-dream/journal 与
 // GET /_dsh/dsh-dream/knowledge（由 src/index.ts 挂载）；前端不缓存业务数据，刷新即见。
-// 经验区块只展示状态 / 条件 / 范围 / 证据摘要 / 最近核验，不展示权重、向量或原始 JSON。
+// 经验区块只展示状态 / 条件 / 范围 / 适用与例外 / 证据摘要 / 最近核验；日志截断或坏行会明确提示，
+// 不展示权重、向量或原始 JSON。
 // 隐私纪律：面板只读，不写文件、不上传；「隐私模式」只做显示层模糊，DOM 仍是明文。
 window.__ModuleLoader__.load({ id: "@stardustlc/dsh-dream", factory: (require) => {
 var module = { exports: {} }; var exports = module.exports;
@@ -224,10 +225,30 @@ function trimmedText(value) {
   return typeof value === "string" ? value.trim() : "";
 }
 
+/** applicability 数组 → 紧凑适用串（package + versions / platform）；坏形状跳过，空数组给 ""。 */
+function applicabilityTextOf(value) {
+  if (!Array.isArray(value)) return "";
+  const parts = [];
+  for (const raw of value) {
+    if (raw === null || typeof raw !== "object") continue;
+    const pkg = trimmedText(raw.package);
+    const versions = trimmedText(raw.versions);
+    const platform = trimmedText(raw.platform);
+    const main = pkg !== "" ? (versions !== "" ? pkg + " " + versions : pkg) : versions;
+    const bits = [];
+    if (main !== "") bits.push(main);
+    if (platform !== "") bits.push("平台 " + platform);
+    if (bits.length > 0) parts.push(bits.join(" · "));
+  }
+  if (parts.length === 0) return "";
+  if (parts.length > 4) return parts.slice(0, 4).join("；") + "；等 " + String(parts.length) + " 条适用范围";
+  return parts.join("；");
+}
+
 /**
- * 经验视图模型：只投影展示所需字段（title / when / state / scopeLabel /
- * evidenceSummary / lastValidatedAt），不碰权重、向量、原始 JSON。
- * limit 只截断渲染行数，byState 仍按全量统计。
+ * 经验视图模型：只投影展示所需字段（title / when / applicability / exceptions /
+ * state / scopeLabel / evidenceSummary / lastValidatedAt），不碰权重、向量、原始 JSON。
+ * limit 只截断渲染行数，byState 仍按全量统计；truncated / badLines 原样带给提示行。
  */
 function normalizeKnowledge(value, now, limit) {
   const source = value !== null && typeof value === "object" ? value : {};
@@ -249,6 +270,10 @@ function normalizeKnowledge(value, now, limit) {
       id: trimmedText(raw.id),
       title: title !== "" ? title : action,
       when: trimmedText(raw.when),
+      applicability: applicabilityTextOf(raw.applicability),
+      exceptions: Array.isArray(raw.exceptions)
+        ? raw.exceptions.filter((item) => typeof item === "string" && item.trim() !== "").map((item) => item.trim()).slice(0, 10)
+        : [],
       state: state,
       stateLabel: lessonStateLabel(state),
       stateClass: lessonStateClass(state),
@@ -263,11 +288,13 @@ function normalizeKnowledge(value, now, limit) {
   }
   const total = typeof statsSource.lessons === "number" && statsSource.lessons >= 0 ? statsSource.lessons : rawLessons.length;
   const evidenceTotal = typeof statsSource.evidence === "number" && statsSource.evidence >= 0 ? statsSource.evidence : 0;
+  const badLinesRaw = statsSource.badLines;
+  const badLines = typeof badLinesRaw === "number" && Number.isFinite(badLinesRaw) && badLinesRaw > 0 ? Math.floor(badLinesRaw) : 0;
   return {
     rows: rows,
     total: total,
     shown: rows.length,
-    stats: { lessons: total, evidence: evidenceTotal, byState: byState },
+    stats: { lessons: total, evidence: evidenceTotal, byState: byState, truncated: statsSource.truncated === true, badLines: badLines },
   };
 }
 
@@ -287,6 +314,18 @@ function knowledgeCountText(stats) {
   return parts.join(" · ");
 }
 
+/** 截断 / 坏行提示：无问题时给 ""；确保面板不静默展示不完整的经验集。 */
+function knowledgeNoticeText(stats) {
+  const source = stats !== null && typeof stats === "object" ? stats : {};
+  const truncated = source.truncated === true;
+  const badLines = typeof source.badLines === "number" && Number.isFinite(source.badLines) && source.badLines > 0 ? Math.floor(source.badLines) : 0;
+  if (truncated !== true && badLines === 0) return "";
+  const parts = [];
+  if (truncated === true) parts.push("日志过大，仅回放最近一段事件");
+  if (badLines > 0) parts.push("有 " + String(badLines) + " 行损坏已跳过");
+  return parts.join("；") + "；events.jsonl 未改动。";
+}
+
 /** 经验区块的独立空态：与「还没有梦境日记」分开，说明经验从哪来。 */
 function knowledgeEmptyState() {
   return {
@@ -642,6 +681,8 @@ function KnowledgeRow(props) {
     ]),
     h("div", { className: "dshd-kbody", key: "body" }, [
       h("div", { key: "when" }, "何时用：" + (row.when !== "" ? row.when : "未标注适用条件")),
+      row.applicability !== "" ? h("div", { key: "applicability", title: row.applicability }, "适用：" + row.applicability) : null,
+      row.exceptions.length > 0 ? h("div", { key: "exceptions", title: row.exceptions.join("；") }, "例外：" + row.exceptions.join("；")) : null,
       h("div", { key: "evidence" }, "证据：" + row.evidenceSummary),
     ]),
   ]);
@@ -649,6 +690,8 @@ function KnowledgeRow(props) {
 
 function KnowledgeCard(props) {
   const vm = props.vm;
+  const notice = knowledgeNoticeText(vm === null || vm === undefined ? null : vm.stats);
+  const noticeNode = notice === "" ? null : h("div", { className: "dshd-knotice", key: "notice", role: "status" }, notice);
   const head = function (extra) {
     return h("div", { className: "dshd-khead", key: "head" }, [
       h("h4", { key: "t" }, "经验"),
@@ -667,6 +710,7 @@ function KnowledgeCard(props) {
     const empty = knowledgeEmptyState();
     return h("section", { className: "dshd-card dshd-kcard" }, [
       h("h4", { key: "t" }, "经验"),
+      noticeNode,
       h("div", { className: "dshd-kempty", key: "e" }, [
         h("div", { className: "dshd-kempty-title", key: "t2" }, empty.title),
         h("p", { className: "dshd-kempty-body", key: "b" }, empty.body),
@@ -678,13 +722,14 @@ function KnowledgeCard(props) {
     head(props.loading === true
       ? h("span", { className: "dshd-hint", key: "loading" }, "加载中…")
       : h("span", { className: "dshd-hint", key: "count" }, knowledgeCountText(vm.stats))),
+    noticeNode,
     h("div", { className: "dshd-krows", key: "rows" }, vm.rows.map(function (row, index) {
       return h(KnowledgeRow, { key: row.id !== "" ? row.id : "k" + String(index), row: row, privacy: props.privacy === true });
     })),
     vm.shown < vm.total
       ? h("div", { className: "dshd-note", key: "more" }, "只显示最近 " + String(vm.shown) + " / " + String(vm.total) + " 条经验。")
       : null,
-    h("div", { className: "dshd-note", key: "note" }, "只读展示：候选默认不注入任务；采纳、驳回或标记冲突请用 dream_review。"),
+    h("div", { className: "dshd-note", key: "note" }, "只读展示：候选可被检索到，但默认不注入任务建议、且排在可用经验之后；未经审阅不得当作已证实结论。采纳、驳回或标记冲突请用 dream_review。"),
   ]);
 }
 
@@ -1118,6 +1163,7 @@ const CSS = [
   ".dshd-kempty{padding:14px 10px;text-align:center;color:var(--dsw-alias-label-tertiary,#6b7280)}",
   ".dshd-kempty-title{color:var(--dsw-alias-label-primary,#111);font-weight:600;font-size:13px;margin-bottom:4px}",
   ".dshd-kempty-body{margin:0 auto 5px;max-width:460px;font-size:12px}",
+  ".dshd-knotice{font-size:11px;color:var(--dsw-alias-label-primary,#111);background:color-mix(in srgb,var(--dsw-alias-state-warn-primary,#f59e0b) 14%,transparent);border-radius:8px;padding:5px 8px;margin-bottom:7px}",
   ".dshd-privacy .dshd-kbody{filter:blur(4px)}",
   ".dshd-privacy .dshd-knowledge.dshd-peek .dshd-kbody{filter:none}"
 ].join("");
@@ -1165,6 +1211,8 @@ exports.__internals = {
   fetchKnowledge: fetchKnowledge,
   normalizeKnowledge: normalizeKnowledge,
   normalizeLessonState: normalizeLessonState,
+  applicabilityTextOf: applicabilityTextOf,
+  knowledgeNoticeText: knowledgeNoticeText,
   lessonStateLabel: lessonStateLabel,
   lessonStateClass: lessonStateClass,
   knowledgeCountText: knowledgeCountText,

package/lib/journal.d.ts

@@ -9,6 +9,19 @@ export interface DreamEntry {
 export declare function journalFile(journalDir: string): string;
 /** 追加一条梦；返回落盘后的条目。 */
 export declare function saveDream(journalDir: string, reflection: string, lessons: string[], mood: string): DreamEntry;
+/** 读取结果：梦境 + 被跳过的行数（坏 JSON 或不是梦境记录）。 */
+export interface DreamReadResult {
+    dreams: DreamEntry[];
+    skippedLines: number;
+}
+/**
+ * 倒序读取梦境并**报告**跳过了多少行。
+ *
+ * 两个健壮性要求（评审实测发现）：
+ * - 文件开头的 UTF-8 BOM 必须剥离，否则第一行解析失败会让整份日记读空；
+ * - 坏行跳过要可计数，不能静默——调用方（dream_health / 只读路由）可以透出。
+ */
+export declare function readDreamsDetailed(journalDir: string, limit: number): DreamReadResult;
 /** 倒序读取梦境（新梦在前）；损坏行跳过。 */
 export declare function readDreams(journalDir: string, limit: number): DreamEntry[];
 /** 教训榜的一行：次数与最近一次出现时间（lastAt 缺失时是空串，绝不为 null）。 */
@@ -22,6 +35,8 @@ export interface DreamStats {
     total: number;
     moods: Record<string, number>;
     topLessons: LessonStat[];
+    /** 解析时跳过的行数（坏 JSON 或不是梦境记录）；0 表示全部可读。 */
+    skippedLines: number;
 }
 /**
  * 统计梦境（基于全量日记）。

package/lib/journal.js

@@ -26,18 +26,27 @@ export function saveDream(journalDir, reflection, lessons, mood) {
 }
 /** 需要读全量日记时的上限：检索与统计共用，避免两处上限漂移。 */
 const FULL_SCAN_LIMIT = 100000;
-/** 倒序读取梦境（新梦在前）；损坏行跳过。 */
-export function readDreams(journalDir, limit) {
+/**
+ * 倒序读取梦境并**报告**跳过了多少行。
+ *
+ * 两个健壮性要求（评审实测发现）：
+ * - 文件开头的 UTF-8 BOM 必须剥离，否则第一行解析失败会让整份日记读空；
+ * - 坏行跳过要可计数，不能静默——调用方（dream_health / 只读路由）可以透出。
+ */
+export function readDreamsDetailed(journalDir, limit) {
     const file = journalFile(journalDir);
     if (!existsSync(file))
-        return [];
-    const lines = readFileSync(file, 'utf8').split('\n').filter((line) => line.trim() !== '');
-    const out = [];
+        return { dreams: [], skippedLines: 0 };
+    // 开头 BOM 不参与解析（Windows 记事本等工具会写入）。
+    const text = readFileSync(file, 'utf8').replace(/^\uFEFF/, '');
+    const lines = text.split('\n').filter((line) => line.trim() !== '');
+    const dreams = [];
+    let skippedLines = 0;
     for (const line of lines) {
         try {
             const rec = JSON.parse(line);
             if (typeof rec.reflection === 'string') {
-                out.push({
+                dreams.push({
                     id: String(rec.id ?? ''),
                     at: String(rec.at ?? ''),
                     reflection: rec.reflection,
@@ -45,10 +54,18 @@ export function readDreams(journalDir, limit) {
                     mood: typeof rec.mood === 'string' ? rec.mood : '',
                 });
             }
+            else
+                skippedLines += 1;
+        }
+        catch {
+            skippedLines += 1;
         }
-        catch { /* 损坏行跳过 */ }
     }
-    return out.reverse().slice(0, limit);
+    return { dreams: dreams.reverse().slice(0, limit), skippedLines };
+}
+/** 倒序读取梦境（新梦在前）；损坏行跳过。 */
+export function readDreams(journalDir, limit) {
+    return readDreamsDetailed(journalDir, limit).dreams;
 }
 /**
  * 统计梦境（基于全量日记）。
@@ -58,8 +75,10 @@ export function readDreams(journalDir, limit) {
  * 大小写，不再二次 flatMap（否则同一条教训的三个数值会来自不同的扫描）。
  */
 export function dreamStats(journalDir) {
-    const dreams = readDreams(journalDir, FULL_SCAN_LIMIT);
-    const moods = {};
+    const { dreams, skippedLines } = readDreamsDetailed(journalDir, FULL_SCAN_LIMIT);
+    // 无原型对象：心境是用户可控文本，'__proto__' / 'constructor' 这类键
+    // 在普通对象上会被原型吞掉或把计数变成字符串（评审实测）。
+    const moods = Object.create(null);
     const lessons = new Map();
     for (const dream of dreams) {
         const mood = dream.mood !== '' ? dream.mood : '平静';
@@ -78,7 +97,9 @@ export function dreamStats(journalDir) {
     const topLessons = [...lessons.values()]
         .sort((a, b) => b.count - a.count || b.lastAt.localeCompare(a.lastAt))
         .slice(0, 10);
-    return { total: dreams.length, moods, topLessons };
+    // 对外给普通对象副本：内部用无原型对象防键污染，但消费方（deepStrictEqual / 原型判断）
+    // 期望的是普通对象。展开赋值走 CreateDataProperty，不会触发 __proto__ setter。
+    return { total: dreams.length, moods: { ...moods }, topLessons, skippedLines };
 }
 /** 关键词检索梦境（不区分大小写，命中 reflection/lessons；扫描全量，上限见 FULL_SCAN_LIMIT）。 */
 export function searchDreams(journalDir, query, limit) {

package/lib/knowledge-store.d.ts

@@ -11,6 +11,10 @@ export interface KnowledgeStoreOptions {
     lockTimeoutMs?: number;
     /** 锁年龄超过该毫秒数且 pid 不存活才允许接管；默认 30000。 */
     lockStaleMs?: number;
+    /** 锁硬上限：超过且心跳停滞时给可操作错误、不静默抢占；默认 600000（10 分钟）。 */
+    lockHardLimitMs?: number;
+    /** 心跳刷新间隔毫秒；默认 5000。长回放/压缩也会按行数主动 touch。 */
+    lockHeartbeatMs?: number;
 }
 /**
  * 经验知识存储。无文件时所有读取方法安全返回空，写入方法在首次写入时自建目录。
@@ -25,6 +29,9 @@ export declare class KnowledgeStore {
     private readonly maxReplayEvents;
     private readonly lockTimeoutMs;
     private readonly lockStaleMs;
+    private readonly lockHardLimitMs;
+    private readonly lockHeartbeatMs;
+    private lastIndexError?;
     constructor(knowledgeDir: string, options?: KnowledgeStoreOptions);
     /** 全部经验，按 updatedAt 降序（同刻按 id 稳定排序）。 */
     listLessons(): Lesson[];
@@ -38,22 +45,23 @@ export declare class KnowledgeStore {
         created: boolean;
     };
     /**
-     * 创建候选经验。同 idempotencyKey 幂等；同指纹（文本 + 范围相同）确定性合并，
+     * 创建候选经验。同 idempotencyKey + 同 requestHash 幂等；同指纹（文本 + 范围相同）确定性合并，
      * 只把新证据并入已有经验，不新增经验。
+     * R2′：有 read 证据 → 初始 usable（含 user-correction read 时 review=accepted/user）；只有 claimed 或无证据 → candidate。
      */
     createLesson(input: LessonInput, idempotencyKey: string): {
         lesson: Lesson;
         created: boolean;
     };
-    /** 按 patch 更新经验；revision 不符抛 KnowledgeError('revision') 且不写。 */
+    /** 按 patch 更新经验；revision 不符抛 KnowledgeError('revision')（details 带 currentRevision）且不写。 */
     updateLesson(id: string, patch: Partial<Lesson>, expectedRevision: number, idempotencyKey: string): Lesson;
     /** 审阅经验：accepted → usable，rejected → rejected，unreviewed → candidate。 */
     reviewLesson(id: string, decision: ReviewDecision, expectedRevision: number, idempotencyKey: string, actor?: string): Lesson;
     /** 状态迁移；不允许的迁移抛 KnowledgeError('invalid') 且不写。 */
     applyTransition(id: string, to: LessonState, expectedRevision: number, idempotencyKey: string): Lesson;
-    /** 从事件重建派生索引；不删除、不改写 events.jsonl / evidence.jsonl。 */
+    /** 从事件完整重建派生索引与 checkpoint；不删除、不改写 events.jsonl / evidence.jsonl。 */
     rebuildIndex(): void;
-    /** 统计。truncated=true 表示回放被 MAX_REPLAY_EVENTS 截断（不静默）。 */
+    /** 统计。truncated=true 表示事件总量超过有界回放上限（不静默）；快照模式下实体已折叠进 checkpoint。 */
     stats(): {
         lessons: number;
         evidence: number;
@@ -61,15 +69,88 @@ export declare class KnowledgeStore {
         byState: Record<LessonState, number>;
         truncated: boolean;
         badLines: number;
+        orphanEvents: number;
+        unsupportedVersions: number;
+        firstReplayedEventId?: string;
+        replayMode: 'full' | 'snapshot+tail';
+        replayedEvents: number;
+        skippedEvents: number;
+    };
+    /** 只读诊断：锁、文件、计数与最近一次派生索引写失败；绝不获取锁、绝不写盘。 */
+    diagnose(): {
+        writable: boolean;
+        lock: {
+            present: boolean;
+            ageMs?: number;
+            pid?: number;
+            alive?: boolean;
+            bootId?: string;
+            stale: boolean;
+        };
+        files: {
+            dir: string;
+            events: {
+                path: string;
+                exists: boolean;
+                bytes: number;
+            };
+            evidence: {
+                path: string;
+                exists: boolean;
+                bytes: number;
+            };
+            index: {
+                path: string;
+                exists: boolean;
+                bytes: number;
+                generatedAt?: string;
+            };
+        };
+        counts: {
+            lessons: number;
+            evidence: number;
+            events: number;
+            badLines: number;
+            orphanEvents: number;
+            unsupportedVersions: number;
+            truncated: boolean;
+            byState: Record<LessonState, number>;
+        };
+        lastIndexError?: {
+            message: string;
+            at: string;
+        };
     };
     private ensureDir;
     private withLock;
-    /** 有界读取 JSONL：只保留最后 maxReplayEvents 条非空行，并报告总行数与截断。 */
+    private fileInfo;
+    private hashRequest;
+    private hashablePatch;
+    private cleanPatch;
+    private assertSameRequest;
+    /**
+     * 恢复"首次结果"：
+     * - 尾部回放产生的 entry 自带快照，直接返回；
+     * - checkpoint 里的 entry 只有 lessonId/requestHash，则做一次有针对性的完整扫描，
+     *   在命中该幂等键的那一刻取快照；失败再退回当前实体（best effort）。
+     */
+    private resolveIdempotentLesson;
+    private replayUntilIdempotencyKey;
+    /** 顺序读取 JSONL 的非空行；每 TOUCH_EVERY_LINES 行调用一次 touch（长回放锁心跳）。 */
+    private forEachLine;
+    /** 有界读取：只保留最后 maxReplayEvents 条非空行，并报告总行数与是否截断。 */
     private readBoundedLines;
-    /** 只回放事件流。 */
+    /** 快照 + 尾部增量（checkpoint 有效时）；否则有界全量回放。 */
     private loadEvents;
+    private loadEventsBounded;
+    /** 无界完整回放（显式压缩 / 写路径发现截断或状态不完整时使用）。 */
+    private loadAllUnbounded;
     /** 事件流 + evidence.jsonl（两条路径都留痕，按 id 合并去重）。 */
     private loadAll;
+    /** 写路径：状态不完整、证据疑似缺失或截断未折叠时，自动做一次完整回放。 */
+    private loadCompleteState;
+    private hasMissingEvidenceRefs;
+    private mergeEvidenceFile;
     private applyEventLine;
     private appendEvent;
     private appendLine;
@@ -80,8 +161,12 @@ export declare class KnowledgeStore {
     private appendLessonUpdate;
     private maskLesson;
     private maskEvidence;
+    private hashPrefix;
+    private readLastLineId;
+    private tryLoadCheckpoint;
+    private buildCheckpoint;
     private buildIndexPayload;
-    /** 自动更新派生索引：失败降级（权威事件已落盘），不推翻调用结果。 */
+    /** 自动更新派生索引：失败降级（权威事件已落盘），记录 lastIndexError 供 diagnose()。 */
     private writeIndex;
     private writeIndexStrict;
 }