@a9i5k4/dsh-auto-memory 2.2.6 → 2.3.0

package/docs/PROMPT-SET-STRICT.md

@@ -0,0 +1,389 @@
+# 模块化 Prompt 集（严谨集成版）
+
+> 写于 2026-09-09，基于 v2.2.6 实测代码。
+> **本文件替代** `PROMPT-PACK-LAYERED-RECALL.md` 的 prompt 正文部分；该文 §0 的 OpenViking 联网核实结论仍然有效，本文直接引用不再重复。
+> 全局背景见 [INTEGRATION-ANALYSIS.md](INTEGRATION-ANALYSIS.md)（本地架构解读 + 四仓库评估）。
+> **已完成**：T1（`lib/l0-extract-pre.js`）、G1/G3（接续指令文案）。
+
+---
+
+## 通用前置约束（每一段 prompt 都必须遵守，投喂时一并附上）
+
+### 1. 搜索优先原则（违反即打回）
+
+1. **动手前必须先搜索定位**。禁止凭 prompt 描述臆造文件路径、函数名、字段名。
+2. 必用手段：`Grep`（正则）、`Glob`、`Read`。每个要改动的符号都要**实际 grep 到并记下真实行号**。
+3. prompt 中给出的行号是**上一次观测值，可能已漂移**，必须先重新定位再动手；若行号对不上，以实际搜索结果为准并在回报中说明。
+4. **引用规范**：回报中每一处改动必须写成 `文件路径:行号 — 原内容 → 新内容`。
+
+### 2. 禁止事项
+
+- **不得臆造 API**：任何调用的函数、字段、配置项，必须先在仓库中 grep 到定义处。搜不到就**停下回报**。
+- **不得整文件重写**：一律最小 diff。禁止"顺手重构""统一风格""优化命名"。
+- **不得引入新依赖**：项目 `dependencies` 为空（零运行时依赖承诺）。
+- **不得改 API 签名**：既有导出函数的参数列表不得变更（可用可选参数扩展）。
+- **不得删除既有测试断言**。
+- 涉及 OpenViking（AGPLv3）：**不得复制、翻译、逐行改写其源码**，只可参考公开文档算法思路。
+
+### 3. 集成位置正确性论证（回报必写）
+
+每处改动必须说明：
+- **为什么选这个位置**（上游数据来源、下游消费者分别是谁，用 grep 到的调用链证明）
+- **上下游影响**（哪些函数/模块会受影响，列出调用点行号）
+- **回滚方式**（精确到命令或操作）
+
+### 4. 无法定位时
+
+**立即停止并回报**，格式：
+```
+停止原因：未能定位 <符号/文件>
+已尝试：<搜索词 1>、<搜索词 2>、<路径>
+需要：<澄清问题>
+```
+**禁止猜测、禁止"应该是"**。
+
+### 5. 自检清单模板（每段完成后逐项执行并贴结果）
+
+```bash
+cd D:\dsh-auto-memory
+
+# ① 编译
+node --check <改动涉及的每个 lib/*.js>
+
+# ② 测试（必跑，数字不得下降）
+node tests/smoke/smoke-test-l0-extract-pre.mjs       # 基线 18
+node tests/smoke/smoke-test-handoff-pre.mjs          # 基线 51
+node tests/smoke/smoke-test-continue-chain-pre.mjs   # 基线 58
+node tests/smoke/smoke-test-water-step-pre.mjs       # 基线 12
+node tests/smoke/smoke-test-autocont-host-pre.mjs    # 基线 29
+
+# ③ 接口一致性（grep 校验，不得出现孤儿调用/断链）
+grep -rn "<新增/改动的符号>" lib/ | head -20
+
+# ④ 改动范围
+git status --short
+git diff --stat
+```
+
+### 6. 项目事实速查（已核实，可直接引用）
+
+| 项 | 值 |
+|---|---|
+| 根 | `D:\dsh-auto-memory`（pre 线） |
+| 版本 / 协议 | 2.2.6 / BSD-3-Clause |
+| 依赖 | peer `@deepseek-ai/cordis ^4.0.1`；optional `@huggingface/transformers ^3.7.6`；**dependencies 为空** |
+| 约定 | 新增模块一律 `lib/xxx-pre.js`（纯函数、零 IO、IO 注入） |
+| 编码 | UTF-8 无 BOM；仓库 CRLF；`*-pre.js` 与 `*.js` 成对存在 |
+| 五条不变量 | I1 前缀缓存字节稳定 / I2 不替 host 决定压缩 / I3 凭证永不进提示词 / I4 绝不阻塞接续 / I5 水位测量在 pre-step |
+
+---
+
+# A 篇 · 常规改造（按依赖顺序，彼此独立可单独投喂）
+
+依赖关系：**P1 → P2 → P3 → P4**（主链串行）；**P5 → P6**（接续链，可与主链并行）；**P7** 无依赖随时可做。
+
+---
+
+## 【P1】L0 向量索引与增量更新
+
+**目标**：为 T1 产出的 L0 建立向量索引，供语义检索使用。参照 OpenViking「Vector Index 只存 URI+向量+元数据，不含文件内容」（来源见 PROMPT-PACK §0.5）。
+
+**涉及功能模块**：新增 `lib/l0-index-pre.js`；消费 `lib/l0-extract-pre.js`；参考 `lib/memory-index-pre.js`（既有索引范式）。
+
+**验收标准**：
+1. 177 条真实记忆全量建索引，每条 `{id, vector, l0, source, l0Hash, updatedAt}`，**零丢失**
+2. 增量：改一条 → 仅重算该条（可断言"重算条数"）
+3. 失效条目可移除
+4. 索引缺失/非法 → fail-soft 回退，**不阻塞任何调用方**
+5. 新增 smoke 全绿；既有五套基线不下降
+
+**需先检索的仓库路径与符号关键词**：
+- 路径：`lib/l0-extract-pre.js`、`lib/memory-index-pre.js`、`lib/semantic-js-pre.js`、`lib/m4-corpus-pre.js`
+- 关键词：`buildL0IndexPre`、`extractL0Pre`、`MemoryFileIndex`、`createJsSemanticEnginePre`、`JS_SEMANTIC_ENGINE_VERSION`、`memoryIndexVersion`、`sourceVersion`、`recordDigest`
+- 必须先确认：① `buildL0IndexPre` 的返回字段 ② C2 引擎的创建函数名与 embedding 调用方式（含 `query:`/`passage:` 前缀如何传）③ 既有索引落在哪个目录
+
+**改动边界**：
+- ✅ 允许新增：`lib/l0-index-pre.js`、`tests/smoke/smoke-test-l0-index-pre.mjs`
+- ❌ 禁止修改：`lib/l0-extract-pre.js`（T1 已锁定）、`lib/index.js`、`lib/semantic-js-pre.js`、任何既有 `.js`
+- ❌ 禁止：引入依赖、在索引中存原文
+
+**完成自检**：按 §5 模板（本段 `node --check lib/l0-index-pre.js`）。
+
+**回滚**：删除新增两个文件即可（本段不接线，零残留）。
+
+---
+
+## 【P2】语义臂接入 recall
+
+**目标**：`memory_recall` 当前为纯词法（工具描述自述"关键词匹配"）。接入语义臂，**输入用 L0 而非全文**（全文会超 e5 512 token 上限被截断）。
+
+**涉及功能模块**：`lib/index.js` 的 `recall()` 实现与 `memory_recall_pre` 工具定义；`lib/semantic-js-pre.js`（C2）；`lib/shadow-retrieval-pre.js`（词法臂）。
+
+**验收标准**：
+1. 主题性查询（"发布踩坑"）能召回词法不重合但语义相关的记忆
+2. **词法臂必须保留并继续打全文**（错误码/变量名/路径在 L0 里没有）
+3. 语义引擎不可用 → fail-soft 退回纯词法，**不报错、不阻塞**
+4. `recall(query, limit, agent, scope)` **签名不变**
+5. 五套基线不下降
+
+**需先检索的仓库路径与符号关键词**：
+- 路径：`lib/index.js`、`lib/semantic-js-pre.js`、`lib/shadow-retrieval-pre.js`、`lib/context-host-pre.js`
+- 关键词：`async recall(`、`defineTool('memory_recall_pre'`、`engine.recall(`、`lexicalSearch`、`buildQueryPlan`、`D6_FUSION_WEIGHTS_PRE_V1`、`fuseD6Pre`、`SHADOW_GATE_POLICY_PRE_V1`
+- 必须先确认：① `recall()` 真实行号与完整函数体 ② 当前召回走的是 `lexicalSearch` 还是别的函数 ③ C2 引擎实例在 `index.js` 中如何持有（字段名）④ 是否已有 `scope='sessions'` 走 host 的分支
+
+**改动边界**：
+- ✅ 允许修改：`lib/index.js` 中 `recall()` 函数体内部（最小 diff）
+- ❌ 禁止修改：`recall()` 签名、`defineTool` 的参数 schema 既有字段（只能新增可选字段）、`lib/semantic-js-pre.js`、`lib/shadow-retrieval-pre.js`、激活决策层
+- ❌ 禁止：把全文送进 embedding
+
+**集成位置正确性**：必须说明为何改在 `recall()` 内部而非工具定义处；列出 `recall()` 的所有调用点行号。
+
+**回滚**：`git checkout lib/index.js`（本段改动仅限该文件）。
+
+---
+
+## 【P3】融合层改造（rank-space + 绝对分数决策）
+
+**目标**：修复 `fuseD6Pre` 的 minmax 归一化三宗罪：① 分数随候选集漂移 ② 矮子里拔将军 ③ 候选 ≤1 时退化为常数 0.5（排序失效）。本项目核心是"是否注入"的决策，依赖分数与阈值比较，**相对量会腐蚀决策基础**。
+
+**涉及功能模块**：`lib/semantic-js-pre.js` 的 `fuseD6Pre`。
+
+**验收标准**：
+1. 决策用**绝对分数 + 校准阈值**，排序用融合分数——两者解耦
+2. 候选 < 3 时不退化（新增断言）
+3. 提供 **rank-space** 融合：`score = Σ 1/(k + rank/divisor)`，**k=60**
+4. 保留原始分数供审计
+
+**需先检索的仓库路径与符号关键词**：
+- 路径：`lib/semantic-js-pre.js`、`lib/shadow-retrieval-pre.js`、`lib/context-bridge-pre.js`
+- 关键词：`fuseD6Pre`、`D6_FUSION_WEIGHTS_PRE_V1`、`normArm`、`flat`、`reciprocal_rank_fusion`、`rrf`
+- 必须先确认：① `fuseD6Pre` 的所有调用点 ② 现有返回值结构被谁消费（哪些字段不能删）③ 是否已有 RRF 实现
+
+**改动边界**：
+- ✅ 允许：在 `lib/semantic-js-pre.js` **新增**融合函数（并存），由配置/参数切换；或新增 `lib/recall-fusion-pre.js`
+- ❌ **禁止删除或改写 `fuseD6Pre` 既有行为**（并存优先，避免破坏调用方）
+- ❌ **禁止 score-space 加权 RRF**：Hindsight issue #3956 实测——k=60 时动态范围仅 5.9 倍，加权会让排序退化为字典序，recall@20 从 **0.97 崩到 0.40**
+- ❌ 禁止照搬 OpenViking 的 `α=0.5` 父分数传播（本地无深目录树；若实现须映射为「工作区/日志文件/主题块」三级父且默认关闭）
+
+**回滚**：新增文件则删除；若改了 `semantic-js-pre.js` 则 `git checkout` 该文件。
+
+---
+
+## 【P4】recall 返回 L0 + 按需展开
+
+**目标**：recall 当前返回整条原文（平均 814 字符）。改为默认返回 L0 列表，按需按 id 展开原文（对齐 OpenViking 渐进式加载：L0 已在结果中，`is_leaf` 决定取 L1/L2）。
+
+**涉及功能模块**：`lib/index.js` 的 `recall()` 返回结构；可能复用 `memory_read` 或新增展开入口。
+
+**验收标准**：
+1. 默认返回 L0 列表（每条 ~93 字符），含 `id/score/match_reason`
+2. 提供按 `mem_xxx` 展开原文的入口
+3. 5 条场景：约 4070 字符 → 约 590 字符
+4. 展开不串条；旧调用方式（不传新参数）行为不变
+5. 五套基线不下降
+
+**需先检索的仓库路径与符号关键词**：
+- 路径：`lib/index.js`、`lib/memory-index-pre.js`
+- 关键词：`async recall(`、`memory_read`、`readTextSafe`、`byteStart`、`byteEnd`、`recordDigest`、`locator`
+- 必须先确认：① 现有是否已能按 id 定位到字节区间（若能则复用，不要新造）② `recall()` 返回字符串还是对象
+
+**改动边界**：
+- ✅ 允许：`lib/index.js` 的 `recall()` 返回组装部分
+- ❌ 禁止：改变静态纪律层注入内容（I1）；删除既有返回字段
+- ❌ 禁止修改：`lib/memory-index-pre.js`
+
+**回滚**：`git checkout lib/index.js`。
+
+---
+
+## 【P5】接续锚点表注入
+
+**目标**：`buildContinueCarry()` 当前机械截断（白板 3000 / 账本 8000 / 总 18000）。G1/G3 已改指令为"按需取用"，但**没有锚点表可供下钻**。本段用 T1 的 L0 抽取生成锚点表。
+
+**涉及功能模块**：`lib/index.js` 的 `buildContinueCarry()`。
+
+**验收标准**：
+1. 注入含锚点表（每条 ~20–30 token），材料仍可达
+2. **字节稳定**：相同输入两次注入内容 hash 一致
+3. 锚点生成失败 → fail-soft 回退现有平铺，**绝不阻塞接续**
+4. **不引入新的 LLM 轮次**（纯解析），满足 0.75 早于官方 0.80 的时序
+5. handoff 51 / continue-chain 58 不下降
+
+**需先检索的仓库路径与符号关键词**：
+- 路径：`lib/index.js`
+- 关键词：`buildContinueCarry`、`carryText`、`slice(0, 3000)`、`slice(0, 8000)`、`slice(0, 18000)`、`truncateHead`、`stripSensitiveSections`、`snapshotPlanTitle`、`snapshotHandoffTitle`
+- 必须先确认：① `buildContinueCarry` 的真实行号与返回字段 ② 三处截断的准确位置 ③ `carryText` 被谁消费（下游）
+
+**改动边界**：
+- ✅ 允许：`buildContinueCarry()` 内部（最小 diff）
+- ❌ 禁止：新增 LLM 调用；让注入内容随查询/任务动态变化；改动静态纪律层
+- ❌ 禁止修改：`refreshRitualPrompt()`（那是 P6/P7 范围）
+
+**回滚**：`git checkout lib/index.js`。
+
+---
+
+## 【P6】账本权重化截断
+
+**目标**：`ledger.slice(0, 8000)` 是位置截断。实测账本**段内异质**——「已试方案与失败原因」段里三条全是**成功解法**；「进度与下一步」混了已完成项、真待办、元指令。按位置截可能把高价值段整体截掉。
+
+**涉及功能模块**：`lib/index.js`（解析 + 权重分配），解析部分建议抽成 `lib/handoff-anchor-pre.js` 纯函数。
+
+**验收标准**：
+1. 正确解析四段：`## 任务状态` / `## 目标` / `## 已试方案与失败原因` / `## 进度与下一步`
+2. 权重：失败原因 .35 ＞ 下一步 .30 ＞ 目标 .20 ＞ 任务状态 .15
+3. 预算不足时**从最低权重段开始截**
+4. 纯函数 + fixture 锁定解析与排序
+
+**需先检索的仓库路径与符号关键词**：
+- 路径：`lib/index.js`、`docs/M-CM7-HANDOFF-LAYERED-RETRIEVAL.md`
+- 关键词：`readLatestHandoff`、`## 任务状态`、`## 已试方案与失败原因`、`handoffLedgerChars`、`handoffPlanChars`、`writeHandoffLedger`
+- 必须先确认：① 四段标题的**确切字符串**（含空格/全半角）② 是否存在 `handoffLedgerChars` 等配置项（若有则复用，勿硬编码）
+
+**改动边界**：
+- ✅ 允许新增：`lib/handoff-anchor-pre.js`、`tests/smoke/smoke-test-handoff-anchor-pre.mjs`
+- ✅ 允许：`buildContinueCarry()` 中调用新解析函数替换 `slice(0,8000)`
+- ❌ 禁止：删除任何原文（只影响注入，不动文件）；把"成功解法"误标为"失败原因"
+
+**回滚**：`git checkout lib/index.js` + 删除新增文件。
+
+---
+
+## 【P7】写入侧缺陷修复
+
+**目标**：两个独立小缺陷 ① 账本标题重复（最近 6 个中 3 个含两个 `# 交接账本` 标题行、时间戳不一致，解析会取到错的）② `PLAN.md` 退化成日志（并列堆积 2.2.5/2.2.6 状态与历史踩坑，无老化）。
+
+**涉及功能模块**：`memory_note_pre` 的 `kind=handoff` 分支；白板归档（复用既有 PLAN archive 机制）。
+
+**验收标准**：
+1. 追加写入前检测已存在标题则跳过（或解析取最后一个标题，二选一并断言）
+2. 白板区分「当前状态」与「历史」，历史移入 `handoff/archive/`
+3. 不丢失任何既有内容
+4. 五套基线不下降
+
+**需先检索的仓库路径与符号关键词**：
+- 路径：`lib/index.js`、`lib/memory-writer-pre.js`
+- 关键词：`writeHandoffLedger`、`writePlanSnapshot`、`kind`、`handoff`、`plan`、`archive`、`PLAN-`、`MemoryDocumentWriter`、`sanitizeForWrite`
+- 必须先确认：① 账本写入函数的真实名字与行号 ② 标题是在写入函数里拼的还是 LLM 生成的 ③ 既有 PLAN 归档函数
+
+**改动边界**：
+- ✅ 允许：`lib/index.js` 中账本/白板写入函数（最小 diff）
+- ❌ 禁止：删除用户已有账本/白板内容；改动注入预算；绕过 `sanitizeForWrite`（I3）
+
+**回滚**：`git checkout lib/index.js`；文件层面改动需说明是否可回滚（建议先备份 `~/.dsh/memory`）。
+
+---
+
+# B 篇 · M8 记忆系统（单独成篇，调研前置）
+
+> **流程**：先投喂 **M8-R** → 产出调研报告 → **经你确认** → 才生成 M8 改造 prompt。
+> 本篇严格遵守搜索—转写—精准集成约束。
+
+---
+
+## 【M8-R】M8 记忆系统调研（前置，阻塞后续）
+
+**目标（本段只调研，不改代码）**：回溯「原记忆系统参考 Hermes、架构极不成熟」这一结论，核实现有 M8 三层实现的真实数据流、存储结构与调用点，给出替代架构的方案对比与选型理由。**产出报告，等待确认。**
+
+### 调研任务
+
+**任务 1 · 回溯原始结论与架构细节**
+- 检索路径：`docs/`（尤其 `PROACTIVE-*`、`M8-MEMORY-HUB.md`、`HANDOFF-M8-M9-M10.md`、`PROJECT-FREEZE-AND-ROADMAP.md`、`proactive-associative-memory-*.md/html`）
+- 关键词：`Hermes`、`三层记忆`、`episodic`、`semantic`、`procedural`、`procedural memory`、`记忆中枢`、`M-02`、`M-03`、`M-04`、`元代码`
+- 要求：引用**具体文件与行号**说明——① 当初判定"参考 Hermes"的依据 ② "架构极不成熟"具体指什么（分类边界？转化条件？存取策略？）③ 原设计的目标形态
+
+**任务 2 · 梳理现有实现的数据流与存储结构**
+- 检索路径：`lib/fact-store-pre.js`、`lib/episodic-store-pre.js`、`lib/procedure-store-pre.js`、`lib/memory-hub-pre.js`、`lib/memory-index-pre.js`、`lib/memory-writer-pre.js`、`lib/index.js`、`lib/m7-index-sync-host-pre.py?`（应为 `.js`）、`python/worker_semantic_pre_v1.py`
+- 关键词：`createFactStorePre`、`createEpisodicStorePre`、`createProcedureStorePre`、`createMemoryHubPre`、`ingestJudgementRows`、`evidenceFor`、`append(`、`consolidate(`、`promote`、`judgement-shadow`、`episodic_candidate`、`semantic_candidate`、`profile_candidate`、`procedure_candidate`、`KIND_TO_LAYER_PRE_V1`
+- 要求：画出并写清——
+  1. **数据流**：对话段 →（哪段代码）→ episode → consolidate → candidate →（哪段代码）→ fact / procedure
+  2. **存储结构**：三层各存什么字段、有无持久化（落到哪个文件/目录）、是否仅内存
+  3. **调用点**：`index.js` 中三层 store 的实例化位置、消费位置、以及 Python sidecar 与 JS 侧的分工边界
+  4. **证据系统**：`evidenceFor` 六类计数由谁写入（grep 写入点）
+
+**任务 3 · 替代长期记忆架构方案对比与选型**
+- 至少三套候选，每套写：核心数据结构、冲突处理、巩固机制、对现有代码的改动量、风险
+- 候选建议（可增补）：
+  - A. **保留三层，补强语义**（沿用 fact/episodic/procedure，补时间三价 + 巩固规则 + 趋势分类）
+  - B. **改为认识论分层**（借鉴 Hindsight：事实证据 / 推断观察 / 行为指令，按可推导性与可变性划分）
+  - C. **双层 + 投影**（原始事件流 append-only + 由事件重算的投影视图，投影可丢弃重建）
+- 选型理由必须基于**任务 2 的真实代码**，不得泛泛而谈
+
+### 交付物（报告格式）
+
+```
+# M8 调研报告
+## 1. 原始结论回溯（含文件:行号引用）
+## 2. 现有实现数据流 / 存储结构 / 调用点（含文件:行号 + 调用链）
+## 3. 问题清单（现有实现的确切缺陷，每条附代码证据）
+## 4. 候选架构对比（表格）
+## 5. 选型建议与理由（含改动量估算、风险）
+## 6. 待你确认的开放问题
+```
+
+### 改动边界
+
+- ❌ **本段禁止修改任何文件**。`git status` 必须保持投喂前状态。
+- ✅ 允许只读搜索与阅读。
+
+### 停止条件
+
+若任务 1 的"参考 Hermes""架构极不成熟"在 `docs/` 中**检索不到明确出处**，立即停止并回报：
+
+```
+停止原因：未能定位「参考 Hermes / 架构极不成熟」的文档出处
+已尝试：<关键词列表>、<检索路径>
+需要：请确认该结论的原始来源（哪个文档/哪次对话），或允许以代码现状为准重新评估
+```
+
+**禁止猜测、禁止把"我推测这里不成熟"当证据。**
+
+### 自检清单（本段）
+
+```bash
+git status --short        # 必须与投喂前一致（无任何改动）
+# 报告中每一条结论都必须能给出 文件:行号
+```
+
+---
+
+## 【M8-1 …】M8 改造 prompt
+
+**状态：待 M8-R 报告经你确认后生成。**
+
+届时将按确认的架构方案拆解为独立的 M8-1、M8-2…，每段同样遵守：
+- 先搜索定位（路径 + 符号关键词 + 真实行号）
+- 最小 diff、禁整文件重写
+- 明确允许/禁止修改文件
+- 集成位置正确性论证 + 上下游影响 + 回滚方式
+- 五套 smoke 基线不下降
+- 无法定位即停止回报
+
+---
+
+## 附：执行顺序建议
+
+```
+批次 1（并行，互不干扰）
+  ├─ P1  L0 索引          （新增文件，不接线）
+  ├─ P5  接续锚点表        （改 index.js 单一函数）
+  ├─ P7  写入侧修复        （改 index.js 写入函数）
+  └─ M8-R 调研            （只读，产出报告待确认）
+
+批次 2（依赖 P1）
+  └─ P2 语义臂接入 recall
+
+批次 3（依赖 P2）
+  └─ P3 融合层改造
+
+批次 4（依赖 P3）
+  └─ P4 返回 L0 + 展开
+
+批次 5（依赖 P5）
+  └─ P6 账本权重截断
+
+批次 6（依赖 M8-R 确认）
+  └─ M8-1 … 按确认方案展开
+```
+
+**冲突提示**：P2/P3/P4 与 P5/P6 都会改 `lib/index.js`。若同一批次并行执行，必须**串行投喂并逐段 `git diff` 确认**，避免同文件改动互相覆盖。

package/docs/RELEASE-GO-NOGO.md

@@ -0,0 +1,82 @@
+# 发版 Go / No-Go · 快速验证方案（2026-09-09 23:24）
+
+> 结论：**今天/明天可发**。原先计划的「跑一周分布观察」是**权重标定**用的（P10），**不是发布正确性**用的——正确性可以加速验证，不必等自然数据。
+
+## 0. 为什么不用等一周
+
+| 关注点 | 一周观察在解决什么 | 发布正确性是否已具备 |
+|---|---|---|
+| success / correction 分布 | **标定** `IMPORTANCE_WEIGHTS`（P10） | ✅ 已实证：P9a 26 断言（真实 host 实例 + DSH_HOME 注入磁盘投影 JSONL）、P9d 13 断言（含"修复前同夹具返回 0、修复后 2 条"的回归证明） |
+| importance 只有半条腿 | 让 `success+reuse` 项有数据 | ⚠️ 但不构成发布阻塞：当前 importance∈[0.30,0.65] 由 `distinctSessions`（跨会话重现度）驱动，**是可用信号，且比"此前没有 importance"更优** |
+| M8 默认启用 | — | ✅ live 验证已过（端点 200、三层落盘、restore） |
+| 回归 | — | ✅ 八套基线全绿（见 §2） |
+
+**判据**：新能力是**渐进增强**，最差情况也只是回到"没有 importance"的旧状态，**不会比现状更差** ⇒ 不构成发布阻塞。
+
+## 1. 唯一硬阻塞：工作区未提交
+
+```
+M lib/index.js            (+11/-5) 子代理超时兜底 + localAgent 兼容（DSH 0.1.2）
+M lib/python-setup-pre.js (+16/-4) issue #27 bge-m3 仓库名（HF 401）+ #28 tokenizer 补拉
+```
+
+`tools/release.mjs` 的 DEV 源**就是工作区**，脏工作区会直接进包且无法回溯。
+
+**处理**：这两个都是真实 bug 修复（建议带上）→ 先 commit；若不属于本次发布范围 → `git stash push -u` 后再发。
+
+## 2. 快速验证清单（1–2 小时，非一周）
+
+### A. 静态（已跑，全绿，可复用）
+
+| 套件 | 基线 | 状态 |
+|---|---|---|
+| p9a correction 归因 | 26 | ✅ |
+| p9d recentEvidenceForSuccess ts | 13 | ✅ |
+| memory-importance | 18 | ✅ |
+| p4 L0 返回 | 34 | ✅ |
+| p8 RRF 接线 | 14 | ✅ |
+| evidence-agg | 14 | ✅ |
+| handoff | 51 | ✅ |
+| continue-chain | 58 | ✅ |
+
+### B. live 冒烟（15–30 分钟，建议全做；时间紧则至少做 B3）
+
+- [ ] **B1** 重启 dsh web，设置页「记忆中枢」可见、三栏有内容或正确空态
+- [ ] **B2** `GET /api/dsh-auto-memory-pre/memory-hub` 返回 200 + overview
+- [ ] **B3** ⭐ **P8 语义臂实证**（排序行为变更，最关键）：
+      用 `memory_recall_pre` 查一个**与记忆词法不重合但语义相关**的查询（如记忆里写"npm 发布报 ENEEDAUTH"，查"发布凭证问题"），
+      确认能召回 ⇒ 证明 RRF 融合生效、语义臂不是摆设。
+      若召回失败且 `legacy` 开关切回后正常 → 立即回报，**暂缓发版**。
+- [ ] **B4** correction 端到端：对 AI 说一句命中纠正词典的话（如"不对，你记错了"），检查当日 events 是否新增 `"kind":"correction"`
+- [ ] **B5** success（可选，自然触发概率低）：临时调小 `autoConsolidateCooldownMinutes` → 先 read 一条记忆 → 触发一次 consolidation → 看是否落 `"kind":"success"`。
+      若不方便，**接受 P9d 的 G1 断言作为功能实证**，跳过。
+
+### C. 发布
+
+```bash
+cd D:/dsh-auto-memory
+git status --short      # 必须干净（或只剩未跟踪的 artifacts/ 之类）
+git diff --stat         # 确认最小改动
+node tools/release.mjs 2.2.7
+```
+
+> 发版前确认 `package.json` 版本未被手工改过（当前 2.2.6，release.mjs 会自动回写）。
+
+## 3. 发布措辞建议（避免过度承诺）
+
+- ✅ 可写：「记忆检索支持分层语义召回」「记忆重要性权重（跨会话重现度）」「修正 evidence 时间戳与 correction 归因缺陷」
+- ❌ 不要写：「按有用性排序」「被纠正的记忆会自动降权」——`success`/`reuse` 尚无真实数据，`correction` 刚修复，语义虽已实现但**未经真实分布验证**
+
+## 4. 发布后（不阻塞）
+
+1. 跑一周真实分布：success / correction / reuse 的实际量级
+2. 对照 P9 的「理想触发场景清单」（correction 应达 cite 的 0.5–2%，success 应达 read+cite 的 1–5%）
+3. 若不达标 → 独立小段放宽窗口（success 语义变更需裁决）
+4. P10 定标：`IMPORTANCE_WEIGHTS` 升版本 + `w` 系数
+5. reuse（P9c）继续延后，与 success 合并为「有用性信号补全」
+
+## 5. No-Go 条件（触发即暂缓）
+
+- B3 语义查询召回失败，且 `legacy` 下正常 ⇒ P8 排序有回归
+- 工作区无法清理干净
+- 任一基线数字下降

package/docs/ROADMAP.md

@@ -0,0 +1,162 @@
+# 分层语义唤回 · 总规划（ROADMAP）
+
+> 写于 2026-09-08，基于 **v2.2.6** 源码 + 177 条真实记忆实测。
+> **本文档是唯一入口**：S1（科学性）/ S2（深度吸收）/ S3（目标架构）/ M-CM7（交接分层）/ CONTINUITY-FLOW（流程轴）的全部可执行结论收敛于此；细节仍可回查各原文。
+> 用户 9 月待办 ①②③④⑤ 已并入（② 与 M-CM7 合并为同一项目）。
+
+---
+
+## 1. 现状（实测，非推测）
+
+### 1.1 数据事实
+
+| 项 | 实测值 | 出处 |
+|---|---|---|
+| 记忆条目总数 | **177** 条（`<!-- memory:mem_xxx -->` 锚点数） | `~/.dsh/memory` 扫描 |
+| 文件总字符 | 503,304 | 同上 |
+| 日志条目平均长度 | **814 字符**（中位 463） | 148 条样本 |
+| 最长条目 | **11,046 字符** | 同上 |
+| **首句平均长度（L0 估算）** | **118 字符** | 同上 |
+| **压缩比** | **6.9 : 1** | 814 ÷ 118 |
+
+### 1.2 实现事实
+
+| # | 现状 | 位置 | 问题 |
+|---|---|---|---|
+| F1 | `memory_recall` 是**纯词法关键词匹配**，语义引擎完全没接 | `index.js:6302` 工具描述明写"关键词匹配" | 语义能力闲置 |
+| F2 | 语义引擎（C2 e5-small q8 / C3 bge-m3）**只用于主动联想注入** | `semantic-js-pre.js` | recall 与接续无语义 |
+| F3 | 返回**整条原文**（平均 814 字符） | recall 现状 | token 浪费 |
+| F4 | **长条目超模型上限**：11,046 字符远超 e5-small 的 512 token，全文 embedding 会**被截断丢尾部** | 模型约束 | 全文语义检索有损 |
+| F5 | 接续材料四层**平铺** + 指令要求"先读完" | `index.js:2158`（G1 已改）、`:2159` | 分层被架空 |
+| F6 | 各层与总预算为**位置截断**（白板 3000 / 账本 8000 / 总 18000） | `:2161` `:2162` `:2183` | 高权重段可能被整段截掉 |
+| F7 | 无 L0/L1 sidecar | — | 无"廉价地图" |
+| F8 | 接续第3层强制 `read` 全量转写 | `:2168`（G3 已改） | 最大开销点 |
+| F9 | 账本**标题重复**（6 个中 3 个）+ 段内异质 | 实际产物 | 解析会拿到错时间戳 |
+| F10 | `scope=sessions` 走 host 的 `sessionQuery`，关键词级，**插件侧无法语义化** | host 限制 | 需自建索引（M-CM3 残余） |
+
+### 1.3 已完成（本次）
+
+| 改动 | 位置 | 状态 |
+|---|---|---|
+| G1 首条指令"先读完"→"按需取用" | `index.js:2158` | ✅ 已改，58/58 + 51/51 全绿 |
+| G3 第3层"接续前必须先 read"→"不必通读" | `index.js:2168` | ✅ 已改，同上 |
+
+---
+
+## 2. 目标
+
+### 2.1 OpenViking 模式（公开 README / 论文 VikingMem 描述，非源码）
+
+1. 每条内容**写入时**生成三层：L0 摘要 ~100 tok → L1 概览 ~2k tok → L2 原文
+2. **目录自身也带 L0/L1**（`.abstract` / `.overview`）——读内容前先判断该目录是否值得进
+3. 检索是**逐层收敛**：先在 L0 层锁定范围 → 下钻 L1 → 最后读 L2
+
+**本质**：把成本从**读时**移到**写时**；先便宜地缩小范围，再昂贵地读细节。
+
+### 2.2 映射到本项目
+
+| OpenViking | 本项目对应 | 现状 |
+|---|---|---|
+| L0 摘要 | 主题块标题 / 条目首句（118 字符） | ❌ 未抽取 |
+| L1 概览 | 段落要点 | ❌ 未分层 |
+| L2 原文 | 现有整条记忆（814 字符） | ✅ 已有 |
+| 目录 L0/L1 | 工作区 / 日志文件 / 主题块 | 部分（`## 主题块` 仅覆盖 1/3） |
+| 逐层收敛检索 | L0 语义臂 + 全文词法臂 → 融合 → 按需展开 | ❌ 现在是单臂直通 |
+| 锚点 ID | `<!-- memory:mem_xxx -->` | ✅ **已有，不用新造** |
+
+### 2.3 目标通路（带你的实测数字）
+
+```
+查询「npm publish 令牌怎么配」
+   ├─ L0 语义臂（新增）：177 条 × 118 字符 → 抓主题「发布踩坑」
+   └─ 全文词法臂（保留）：177 条 × 814 字符 → 抓「npm_ViUqqR」
+              ↓ 融合
+   返回 L0 列表：5 条 ≈ 590 字符（现状同场景 ≈ 4070 字符，降 ~85%）
+              ↓ 模型判断需要细节
+   按 mem_xxx 展开 1-2 条原文（锚点 ID 已存在）
+```
+
+**关键**：词法臂**必须保留**并继续打全文——错误码、变量名、文件路径在 L0 里没有，只用 L0 会漏召回。
+
+---
+
+## 3. 路径（分阶段，可执行）
+
+### 阶段 0 · 地基（无它则后面免谈）
+
+| # | 事项 | 改哪里 | 具体做什么 | 验收 | 依赖 | 工作量 |
+|---|---|---|---|---|---|---|
+| **T1** | L0 抽取纯函数 | 新建 `lib/l0-extract-pre.js` | 三级 fallback：① `## 主题块` 标题 ② 条目首句（到 `。：；\n`）③ 前 N 字兜底。纯函数、零 IO、IO 注入 | 177 条解析成功率 ≥99%；平均 L0 ≈118 字符；fixture 锁定 | — | 小 |
+| **T2** | L0 向量索引 | 新建或接 `index-sync-pre.js` | 写入时增量更新 L0 向量；存量一次性回填（编码 ~15k token，比全文 ~100k 快约 7 倍） | 索引一致性；增量正确；冷启动耗时 | T1 | 中 |
+| **T3** | 访问 telemetry（④） | 待定 | 记录每条记忆被 read 次数/最近时间 → 供 importance 权重 | 计数正确 | — | 小（**可后补**） |
+
+> T3 不必等：importance 可先用**规则版**（类型 / 时间 / 是否含命令），telemetry 后续做增量。
+
+### 阶段 1 · recall 改造
+
+| # | 事项 | 改哪里 | 具体做什么 | 验收 | 依赖 | 工作量 |
+|---|---|---|---|---|---|---|
+| **T4** | 语义臂接入 recall | `index.js:6302` 附近 | 把 C2（e5-small q8）接进 `memory_recall`，输入改为 **L0 而非全文** | 主题性查询召回提升 | T1/T2 | 中 |
+| **T5** | 双臂融合 | 复用 `fuseD6Pre` 或新建 | L0 语义臂 ∥ 全文词法臂 → 融合排序。**注意**：若将来引多臂，须用 rank-space boost，不可用 score-space 加权（S2 §2.1，加权 RRF 曾致 recall@20 从 0.97 崩到 0.40） | 融合后不劣于单臂最佳 | T4 | 中 |
+| **T6** | 返回 L0 + 按需展开 | recall 返回结构 | 默认返回 L0 列表；模型按 `mem_xxx` 展开原文 | 返回 token 降 ~85%；展开正确 | T5 | 中 |
+
+### 阶段 2 · 接续改造
+
+| # | 事项 | 改哪里 | 具体做什么 | 验收 | 依赖 | 工作量 |
+|---|---|---|---|---|---|---|
+| **T7** | 锚点表注入 | `buildContinueCarry` `index.js:2126` | 用 T1 的 L0 抽取，生成接续锚点表注入新窗口，**替换**现有机械截断 | 注入字节稳定（前缀缓存不破）；token 账本对比 | T1 | 中 |
+| **T8** | 账本权重化截断 | `index.js:2162` | 四段解析 + 权重：失败原因 .35 > 下一步 .30 > 目标 .20 > 状态 .15；不足时**从最低权重段开始截** | 高权重段不再被整段截掉 | T7 | 小 |
+| **T9** | 结构化锚点 sidecar | `refreshRitualPrompt` `index.js:2049` | 同轮产出 `{id,type,w,text,refs,st}` 结构化索引（**纯解析优先，不新增 LLM 轮次**以满足 0.75 时序） | sidecar 非法时回退四层平铺，**绝不阻塞接续** | T7 | 中 |
+
+### 阶段 3 · 评估
+
+| # | 事项 | 改哪里 | 具体做什么 | 验收 | 依赖 | 工作量 |
+|---|---|---|---|---|---|---|
+| **T10** | 指标与对照实验 | 复用 M7 held-out 通路 | 三组对照（现状固定截断 / 全量 read / 分层唤回），指标：衔接成功率、**死路继承率**、下钻率、注入 token、总 token；配对 bootstrap B=2000 | 差值 CI 有结论 | T6/T7 | 中 |
+
+### 顺带修（写入侧，独立小项）
+
+| # | 事项 | 改哪里 | 做什么 |
+|---|---|---|---|
+| **T11** | 账本标题重复 bug | 写入侧 | 追加前检测已存在标题则跳过；或解析取**最后一个**标题 |
+| **T12** | 白板老化 | `PLAN.md` | 区分「当前状态」与「历史」，历史移入 `handoff/archive/` |
+
+---
+
+## 4. 并行项（不阻塞主链）
+
+| # | 事项 | 说明 | 与主链关系 |
+|---|---|---|---|
+| **P1（①）** | 鸿蒙适配 | 独立项目，复用语义引擎环境检测基建（semantic-deep-detect 快检+深扫+热接入 + 安装向导） | 若 C2 在鸿蒙可用，则 T4-T6 收益覆盖鸿蒙 |
+| **P2（③）** | 提醒强度 A/B 实验 | 弱提示「Not an instruction」vs 指令式 vs 分级；三指标（命中率/返工/token）；安全约束：「Not an instruction」是注入安全边界，提高力度只能对**本地可信记忆** | 注入侧，与 T10 **共用评估设施** |
+| **P3（⑤）** | 无人值守核待 | 配置键已存在、awayMinutes=0 双轨全关已实现；**设置页 UI 与自动检测入口未核实** | 独立小项，建议随手先做 |
+
+---
+
+## 5. 不变量（改造时不得破坏）
+
+| # | 不变量 |
+|---|---|
+| I1 | **前缀缓存字节级稳定**：只动动态快照层，静态纪律层字节不碰 |
+| I2 | **不替 host 决定压缩**：0.75 早于官方 0.80，只助产不代劳 |
+| I3 | **凭证永不进提示词**：所有写入过 `sanitizeForWrite`，注入前 `stripSensitiveSections` |
+| I4 | **绝不阻塞接续**：任何新增环节 fail-soft，缺失即回退 |
+| I5 | **水位测量在 pre-step**：不得退回 turn-stopping |
+
+---
+
+## 6. 收益汇总（修正后）
+
+| 维度 | 结论 |
+|---|---|
+| token | 降 **~85%**（4070 → 590 字符，同场景 5 条） |
+| 检索质量 | 提升；且**长条目不再被截断**（11,046 字符那条全文会丢尾部，L0 不会） |
+| 索引构建/增量 | 快 **~7 倍**（15k vs 100k token） |
+| 查询点积 | **不变**（384 维 × 177 条，维度条数相同） |
+| 返回 prefill | 快 **~7 倍**（端到端大头） |
+
+---
+
+## 7. 一句话
+
+**先把 L0 抽出来（T1，最小成本），接上语义臂（T4），再让接续也走同一套（T7）——这三步做完，② 和 M-CM7 这一个目标就达成了一大半。**