@stardustlc/dsh-dream 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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`）。六个既有工具行为不变，输出字段只增不减。
+- **新数据目录 `<journalDir>/knowledge/`**：`events.jsonl` 权威追加日志、`evidence.jsonl` 追加证据、`index.json` 可丢弃重建的派生索引；写入使用短期文件锁与幂等键。`dreams.jsonl` 永不重写，旧日记继续按原格式读取。
+- **证据纪律**：证据只保存脱敏摘要与定位信息；`verification: read` 与 `claimed` 分开，claimed 不计入独立支持数；同一证据重复提交幂等，不增加独立来源。所有新写盘路径在 `maskSecrets` 开启时先过 `mask.ts`。
+- **范围与预算**：经验按 `projectId` / `workspaceRoot` / `global` 过滤，未知当前项目时 `dream_context` 只返回全局经验；条件与例外不被截断，预算放不下就整条不返回；已驳回、已过期、冲突未解决的默认不注入任务。
+- **只读面板新增「经验」区块**：展示 title / when / state / scopeLabel / evidenceSummary / lastValidatedAt；候选与有冲突的视觉区分明确，空态独立；只读路由新增 GET /_dsh/dsh-dream/knowledge（返回脱敏后的 `{ lessons, evidence, stats }`，沿用回环 Host / 405 / 403 / 错误信封），面板仍无任何写操作。
+- **技能与文档**：`dream-protocol` 技能区分「第一人称感悟」与「技术经验」，流程改为取回上下文 → 执行真实任务 → 收尾提候选（附证据）→ 必要时 dream_review，并写清预算、禁止靠反复 `dream_save` 刷次数、禁止把主观反思升级成 AGENTS.md 指令；README 中英文新增 M1 章节。
+- **测试**：112 → 169 项全部通过（新增知识存储 / 检索 / 三个新工具的宿主 schema 契约 / 只读知识路由零写盘与脱敏 / 面板经验区块纯函数用例）；`tsc`、`node --check lib/client.js` 与官方加载器回归（冷加载 / 缓存 / invalidate 重载）均通过。真实桌面 / Web 目视验收仍待 M1 发布前完成。
+- 本版为 M1 首个发布版本。真实桌面 / Web 目视验收（经验区块配色与空态、窄窗、125%/150% 缩放、深浅色）与 18 插件同载冷启动复验**尚未完成**，完成后单独记录结论。
+
 ## 0.4.1（2026-09-29）
 
 - **修复 Desktop 启动失败**：前端 bundle 的模块注册 ID 与 scoped 包名不一致（注册成 `dsh-dream`，而包名是 `@stardustlc/dsh-dream`），宿主会重试加载并抛 `client-modules: duplicate factory registration for "dsh-dream"`，导致 `web boot: 1 entry did not activate`。现统一为完整包身份。

package/README.en.md

@@ -8,6 +8,19 @@
 
 - **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, 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)
 
 Adds a read-only dream-journal panel: open **Settings →「梦境日记」(Dream journal)** to see totals, mood distribution, the lessons board and a card timeline, with keyword search. Long reflections fold automatically and a one-click privacy blur is available. The panel is read-only and the storage format is unchanged — no migration needed.
@@ -18,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. All 112 plugin tests pass in an isolated environment; the plugin registers 6 tools and the `dream-protocol` skill inside a host where all 18 plugins mount together, 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.
+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.
 
@@ -47,6 +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, 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
@@ -59,18 +73,31 @@ 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` 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.
 
 The bundled `dream-protocol` skill teaches the agent when and how to dream (and the journaling discipline: patterns only, never secrets).
 
+## Lesson memory (M1)
+
+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. 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.
+
 ## Privacy (on by default)
 
-Dream material is masked before journaling: sk keys, GitHub/Groq/Slack tokens, AWS keys, JWTs, `password/token/api_key` assignments and long high-entropy strings become `[masked·type]`. Disable with `maskSecrets: false`.
+Dream material is masked before journaling: sk keys, GitHub/Groq/Slack tokens, AWS keys, JWTs, `password/token/api_key` assignments and long high-entropy strings become `[masked·type]`. In M1 the lesson / evidence / error / bridge write paths also run through `mask.ts` when `maskSecrets` is on, and text returned by the read-only panel route is masked again. Disable with `maskSecrets: false`.
 
 ## Permissions & data
 
-Read-only access to the sessions directory; appends JSONL to the journal directory; no network calls. Session content may be sensitive — the protocol forbids secrets in dreams, but the journal is plaintext: review before sharing.
+Read-only access to the sessions directory; appends JSONL to the journal directory plus lessons/evidence under `journalDir/knowledge/`; no network calls. Session content may be sensitive — the protocol forbids secrets in dreams, but the journal is plaintext: review before sharing.
 
 ## Development
 

package/README.md

@@ -6,6 +6,19 @@
 
 - **修复 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）
 
 新增只读梦境日记可视化面板：打开「设置 → 梦境日记」即可查看梦境总数、心境分布、教训榜与卡片式时间线，并可按关键词搜索；正文超长自动折叠，可一键开启隐私模糊。面板只读，存储格式不变、无需迁移。
@@ -18,7 +31,7 @@
 
 ## 兼容性
 
-验证宿主：官方源码构建的 Harness `0.2.0-rc.1`（commit `407e65c8`）+ Node `24.16.0`（2026-09-29）。112 项插件测试在隔离环境全部通过；同一个宿主里 18 个插件共同加载，本插件注册 6 个工具与 `dream-protocol` 技能，工具 schema 与健康检查契约通过。本轮未启用真实端口与外部服务；面板仅在本机回环地址下可达。
+验证宿主：官方源码构建的 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 子工具调用保留工具名且不重复计数，不提取系统提示、推理、工具参数或结果正文。
 
@@ -54,6 +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）**：面板下方的只读「经验」区块显示技术经验的状态（候选 / 可用 / 有冲突 / 待复核 / 已驳回）、适用条件、范围、适用与例外（exceptions 非空才显示）、证据摘要与最近核验时间，候选与冲突有独立配色和边框，空态与梦境空态分开。知识日志被截断（truncated）或有坏行（badLines）时显示一行提示，并注明 events.jsonl 未改动。数据来自只读路由 GET /_dsh/dsh-dream/knowledge（仅回环地址可达；非 GET → 405，非本机 Host → 403），没有采纳 / 编辑 / 删除按钮；审阅请用 dream_review。
 - **后续计划**：用 sidecar 记录桥接状态（哪些教训、何时写进了哪个 AGENTS.md）。本轮不做——v1 不读取 AGENTS.md，也不新增任何状态文件。
 
 ## 工具一览
@@ -66,6 +80,9 @@ 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` / `packageName` / `packageVersion` / `includeCandidates` 可选 |
+| `dream_review` | 审阅与状态流转：采纳 / 驳回 / 标记过期 / 标记冲突 / 补充证据 | `action`、`lessonId`、`expectedRevision` 必填 |
 
 ### 示例
 
@@ -74,6 +91,9 @@ dream_digest { maxSessions: 5, mode: 'brief' }
 dream_save { reflection: "用户反复遇到输入法问题，偏好先自查再重启", lessons: ["先问是否重启过应用"], mood: "平静" }
 dream_recall { query: "输入法" }
 dream_bridge { path: "AGENTS.md", maxLessons: 10 }
+dream_context { query: "SMTP 取消投递", projectId: "mailer", packageVersion: "9.0.5" }
+dream_learn { kind: "pitfall", title: "池化发送中 close() 不保证终止投递", action: "取消后验证当前连接确实关闭", when: "使用 Nodemailer 9.0.5 池化发送并处理 AbortSignal 时", evidence: [{ kind: "local-artifact", summary: "本机 SMTP 复现：取消后服务器仍收到正文", verification: "read" }] }
+dream_review { action: "accept", lessonId: "lesson-…", expectedRevision: 1 }
 ```
 
 ## 渡梦：让梦变成长期记忆
@@ -84,6 +104,16 @@ dream_bridge { path: "AGENTS.md", maxLessons: 10 }
 
 插件附带 `dream-protocol` 技能，教 agent 何时做梦（开场/收尾/距上次做梦超一天）、做梦三步（入梦→解梦→记梦）与记梦纪律（只沉淀规律不复述流水账、密钥隐私不入梦、存疑要标注）。
 
+## 经验记忆（M1）
+
+梦境日记是主观感悟；真正要复用的技术经验走 `<journalDir>/knowledge/`：
+
+- **候选 → 证据 → 审阅**：`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` 里的旧日记，旧版本插件也仍能读取旧日记。
+
 ## 配置
 
 在你自己的 profile 的 `cordis.patch.yml` 里覆盖本插件行（缺省时用默认值也能加载）：
@@ -102,12 +132,12 @@ dream_bridge { path: "AGENTS.md", maxLessons: 10 }
 
 ## 隐私保护（默认开启）
 
-梦原料入梦前自动脱敏：sk 密钥、GitHub/Groq/Slack 令牌、AWS 密钥、JWT、`password/token/api_key` 赋值、超长高熵串都会被打成 `[已脱敏·类型]`。不需要时可在配置里设 `maskSecrets: false`。
+梦原料入梦前自动脱敏：sk 密钥、GitHub/Groq/Slack 令牌、AWS 密钥、JWT、`password/token/api_key` 赋值、超长高熵串都会被打成 `[已脱敏·类型]`。M1 的经验 / 证据 / 错误 / 桥接写盘路径在 `maskSecrets` 开启时同样先过 `mask.ts`，面板只读路由返回的文本也会再做一次脱敏。不需要时可在配置里设 `maskSecrets: false`。
 
 ## 权限与数据
 
 - 只读访问会话目录（`~/.dsh/sessions`），不修改任何会话文件；
-- 梦境日记以 JSONL 追加写入 `journalDir`；
+- 梦境日记以 JSONL 追加写入 `journalDir`；经验与证据追加写入 `journalDir/knowledge/`（events.jsonl / evidence.jsonl，index.json 可重建）；
 - 不发起任何网络请求；
 - 会话内容可能包含敏感信息——做梦协议明确禁止把密钥/隐私写入梦境，但梦境日记本身是明文存储，请自行评估。