@a9i5k4/dsh-auto-memory 2.2.1 → 2.2.3

package/README.md

@@ -51,7 +51,7 @@
 </details>
 
 <p align="center">
-  <a href="README.zh-CN.md">中文</a> · <b>English</b> · License BSD-3-Clause · <code>pnpm add @a9i5k4/dsh-auto-memory</code> · <a href="https://qm.qq.com/q/v7Asxn6vPa">QQ group</a>
+  <a href="README.zh-CN.md">中文</a> · <b>English</b> · License BSD-3-Clause · <code>pnpm add @a9i5k4/dsh-auto-memory</code> · <a href="docs/USER-GUIDE.zh-CN.md">📖 User guide (settings & tuning)</a> · <a href="https://qm.qq.com/q/v7Asxn6vPa">QQ group</a>
 </p>
 
 ---

package/README.zh-CN.md

@@ -51,7 +51,7 @@
 </details>
 
 <p align="center">
-  <b>中文</b> · <a href="README.md">English</a> · License BSD-3-Clause · <code>pnpm add @a9i5k4/dsh-auto-memory</code> · <a href="https://qm.qq.com/q/v7Asxn6vPa">QQ 交流群</a>
+  <b>中文</b> · <a href="README.md">English</a> · License BSD-3-Clause · <code>pnpm add @a9i5k4/dsh-auto-memory</code> · <a href="docs/USER-GUIDE.zh-CN.md">📖 用户文档(设置与调优)</a> · <a href="https://qm.qq.com/q/v7Asxn6vPa">QQ 交流群</a>
 </p>
 
 ---

package/docs/A3-RISK-ASSESSMENT-20260830.md

@@ -0,0 +1,61 @@
+# A3 风险评估：三个新发现（2026-08-30 canary 夜）
+
+> 背景：A1 act.skill Python canary 期间（22:24–23:20）发现三个此前未立项的行为。
+> 本文给结论：每个是 bug 还是已知设计、是否阻塞 npm 首发、建议窗口。
+> 结论先行：**均不阻塞首发**，其中 F1 建议发布前小修（30 分钟级），F2/F3 记录为已知限制。
+
+## F1 stale 证据振荡（建议发布前小修）
+
+**现象**：语料升版（每日日志追加→重锚定换 digest）后，受影响记忆的"最近一条证据"
+digest 变旧 → aggregate freshness=stale → fv2 stale 门（top-K 候选含 stale 记忆即
+suppress）→ 22:38 第二轮 canary 全部 `hard_gate_stale`。实测 35/64 记忆 stale。
+
+**为什么不是死锁**：自愈路径存在且已实测——模型用记忆工具重新读取（22:57 turn 3）
+→ 写入当前版 digest 的新 seen/cite 事件 → freshness 恢复 fresh → 下一轮 emit 正常
+（23:01 turn 4 delivered）。
+
+**残余风险**：若用户长期不发触发读取的 query，stale 集会累积、emit 命中率下降；
+以及"语料每次升版 → 全量证据一夜变 stale"的振荡本身浪费决策。
+
+**建议**（二选一，倾向 a）：
+a) fv2 调用侧给 stale 门加"降版本容忍"：freshness=stale 但 stale 事件晚于当前
+   语料版本时（即事件只是旧版本、记忆未真正失效）不进门——调用侧调整，不动冻结核；
+b) 语料重锚定后由 JS 主动对"内容未变"的记忆补写 seen 证据（成本高，放弃）。
+
+**不阻塞理由**：有自愈、无错误注入（fail-closed 方向 suppress，精度无损）、
+召回率短暂下降对用户表现为"没想起来"而非"想错"。
+
+## F2 重启后首轮 miv 竞态（记录，不修）
+
+**现象**：22:24 首轮 emit 帧带旧 memoryIndexVersion → JS 侧 `stale-index` 拒收。
+indexSync 的 latest-wins 重同步（日志：syncsOk=2, mivReplaced=1）随即收敛，
+第二轮起 offer 全部 accepted。
+
+**定性**：设计内 fail-closed 时序——重启后 worker 用旧语料先应答一次、JS 用新语料
+拒收一次，下一次对齐。代价=重启后第一条强召回 query 丢一次注入。
+
+**不阻塞理由**：单次、可自愈、方向安全。记录到 handoff"已知限制"。
+
+## F3 fv2 query 窗口污染（已有立项，维持 P3）
+
+前轮回忆内容抬后续轮 intentProb——今晚 23:01 canary 的 intentProb=0.998 部分来自
+会话内前轮 canary 语境（"发射档位确认流程"本身是高频命中词）。既有 handoff P3.3
+立项不变；缓解方向=emit 后窗口衰减，属 fv2 调用侧参数，不阻塞首发。
+
+## 附：A1 修复本身（02dacea）
+
+真 bug=技能段预算饥饿：renderReferenceTail 末位计价，emit 满帧（8 引用 ~3.7KB）
+时技能段（~480B）必超 4096 → skillDropped，任何满帧投递都不含 checklist。
+修=预算预留制（技能段先扣成本，引用按分装填，低分引用走既有 dropped 语义）。
+m83 S5 重写为预留语义，61/61；重启后 canary 复测模型逐字复述 checklist 通过。
+
+## 时间线证据（今晚 canary）
+
+| 时刻(本地) | 轮次 | 结果 |
+|---|---|---|
+| 22:24 | turn1 回忆 | offer stale-index 拒（F2）；会话末 consolidate → 语料升版 |
+| 22:38 | turn2 回忆 | 全部 hard_gate_stale（F1）；证据窗口全 stale |
+| 22:57 | turn3 读取刷新 | 模型记忆工具读取 → sv=31 新证据 → delivered=1 自愈 |
+| 23:01 | turn4 正式 canary | delivered=2，候选∩技能源记忆=2 →（当时未修）skill 被预算挤掉 |
+| 23:15 | 修复+重启后复测 | claims=6；下一轮 pre-step rendered=1 delivered=1 |
+| 23:20 | turn6 复述验证 | **模型逐字复述技能段**：标题/步骤/完成标准全对 → A1 通过 |

package/docs/COT-WATCH-RFC.md

@@ -0,0 +1,88 @@
+# CoT+可见输出实时监听联通工程（M7.5 断言式单播 RFC）
+
+> 状态：**§1-§3 已实施（2026-08-25 深夜）**——`assistant/chunk(chunk.type='reasoning-delta')`
+> 经聚合缓冲接入 ContextObserver；pre-step 边界强制冲刷；purge 清零钩子。
+> 开关 `reasoningObserverEnabled` 默认仍 false（契约红线），需配置显式开启。
+> 待办：§5 弱特征在数据流通后实施。
+> **设置页待办（用户要求）**：`reasoningObserverEnabled`（思维链监听，默认关）
+> 与 `contextBridgeObserveChildSessions`（分支会话观测，默认关）必须纳入设置 UI——
+> 随 G-02/设置页窗口实现；两者已通过配置文件手动开启（2026-08-26）。
+> 实测教训：用户常用会话跨天续接后会被 harness 挂 parentSession 而判为 child，
+> 全部 context push 被 child-session 门丢弃——开关即为此场景而设。
+> 前提：用户明确目标为**监听模型思维链（CoT）+ 可见输出的滑动窗口**触发语义换机；
+>          闭源模型的**概括式/无 CoT**同样纳入设计（后者退化为纯可见输出路径）。
+> 教训：anchored-monitor 与 dsh-draw-gacha 在公开广播信道监听打架导致崩溃——
+>        本工程**必须走断言式一对一订阅（单播），不使用任何公开广播/全局监听**。
+
+## 0. 不变量与官方注入约定
+
+- 点击断言经主 Agent 审定：pre-step 上下文注入为官方每轮边界的自然注入，
+  走 `agent/pre-step` 的 `next(payload)` 透传；不做中间件式硬插。
+- 缓存击穿红线（workbuddy/2026-08-16 诊断）：system prompt 任意位置变化会使
+  DeepSeek 磁盘前缀缓存 miss——注入面必须保持稳定，仅在 pre-step 边界替换。
+- 记忆内容层与检索计算层的 C1/C2/C3 分层按 HTML 权威图为准。
+
+## 1. 信号源与双域监听（CoT + 可见输出）
+
+| 域 | 事件/源 | 特点 | 缺失时 |
+| --- | --- | --- | --- |
+| CoT | `ctx.on('agent/reasoning', …)`（DSH 官方事件名以 types.d.ts 为准；若平台为 chunk 增量流，则等价为 `assistant/reasoning_chunk`/`reasoning_delta`） | 流式增量到达，含 `reasoningTokens/charCount/isComplete` 元信息；闭源模型为概括式短摘要或不发送 | 无则记 `hasReasoning=false`，不降可用性 |
+| 可见输出 | `ctx.on('assistant/message' | 'assistant/chunk' chunk.text)` | 最终可见文本；闭源下是主信号源 | 同 CoT 缺失处理 |
+
+监听范围：仅对本插件所服务的 `sessionId/agentId` 下的事件；不注册任何
+`ctx.on('*')`、`EventBus`、`window.postMessage` 等全局钩子。
+
+## 2. 断言式单播接线（防崩溃铁律）
+
+1. **订阅即断言**：`ctx.on('agent/reasoning', handler)` 的 handler 内首行断言
+   `handler.sessionId === runtime.sessionId`，不匹配直接返回（不写 ring、不推进
+   contextVersion）。做到“一对一”，即使 DSH 内部分发走广播，也在插件内降为单播。
+2. **幂等摄入（sequence 只增不减）**：复用 anchored-monitor 的稳态实现——
+   `sequence <= lastSequence` 的重复/乱序块直接丢弃；窗口 `push(vec, ts)` 外不产生副作用。
+3. **双信道隔离时钟**：reasoning 与 text 各自独立 `lastReasoningAt/lastTextAt`，
+   不共享状态；互相不阻塞。
+4. **不做全局广播，不写共享存储**：不往 `localStorage / file / global bus` 写中间态；
+   仅写入本 runtime 的有界 ring（envelope 128 / Segment 64）。
+
+## 3. 滑动窗口与防卡死（稳定态约束）
+
+- 窗口：`ObserverRing`（有界 ring，已有实现复用），上限 64 segments / 32k chars；
+  ContextBridge 侧复用 `windowSegments=8 / windowChars=4096` 的定长滑窗。
+- 背压：reasoning 高频增量在 16ms 内合并一次（debounce），`OBSERVER_PREVIEW_MAX=240`
+  截断预览；超限直接记 `truncated=true`，不做无限缓冲。
+- 失败域隔离：所有 handler 包 `try {}`，异常仅 `observerDropped.ignored++`，不抛。
+
+## 4. 数据流到 Python（联通点）
+
+```
+DSH 事件流 (单播断言)
+  → ctx.on('agent/reasoning') + ctx.on('assistant/chunk')
+    → ingestEnvelope(runtime, { channel:'agent', eventType:'agent/reasoning'|'assistant/chunk', payload:{text, reasoningTokens?} })
+      → Segment(kind='reasoning'|'assistant', text=bounded)
+        → ContextHost: window = segments.snapshot().slice(-maxSegments)
+           → buildQueryPlan({ trigger, window }) 的语义由 window 全量文本决定（已天然包含 CoT+可见输出）
+           → memoryRefs / aggregates 构造不变
+           → buildContextPushEnvelopePre({ session,cursor,index,trigger,window,memoryRefs,evidence })
+             → PythonContextSinkPre.push(envelope) → worker _fv2_shadow_decide
+```
+
+*注：触发语义不因 CoT 增量而每块 push，仅在 Segment 接受（contextVersion 递增）时
+随正常 envelope 推送，天然防抖。*
+
+## 5. 算法增强（弱信号，非硬门）
+
+Python 侧新增可选特征组 `reasoningSignals = { hasReasoning, uncertaintyScore,
+selfCorrection }`，词表复用 `ERR_TOKENS` 同款轻量匹配，缺失全 0。
+
+仅影响 proactive lane 的预热门限：`uncertaintyScore` 高或命中 selfCorrection 时
+`deltaPro` 放宽一档（0.05→0.03），永远不直接 emit，不进任何 hard gate。
+契约 `Gate 不依赖 reasoning` 继续成立。
+
+shadow 日志增加 `reasoningHints: { hasReasoning, len }` 计数域（≤8 字节），
+用于后续攒"CoT 触发 vs 用户触发"对照对，再决定是否扩意图头为双输入。
+
+## 6. 验收
+
+- 重启 3080 → 发送 4 条验证消息（含 1 条触发模型长 CoT 的开放式回忆问）→
+  检查 `fv2-debug.log` 新增 `reasoningSegs` 计数与 shadow 行的 reasoningHints；
+  三档检索契约不变，仍满足 29 套件回归。

package/docs/DUAL-TIER-RATIFICATION-PROMPT.md

@@ -0,0 +1,71 @@
+# 致项目管理主 Agent · 双轨制路线固化与下一步规划请求
+
+> 发起：校准 Agent（ox-alpha），经用户逐项批准 · 日期：2026-08-25
+> 性质：**双重评判后的正式裁定通知 + 规划请求**。本文件所述决定已由用户最终拍板，
+> 请将其作为既定路线固定、固化进你的总体规划与 progressLedger（权威架构图
+> `docs/proactive-associative-memory-system-map.html` 已由本轮同步更新，
+> progressLedger.updatedAt=2026-08-25，新增 milestone `R-DUAL`，请以它为准）。
+
+## 一、裁定内容：语义检索采用双轨制（三级形态）
+
+经校准侧离线实测与用户逐项审批，以下路线**已定案，不再作为开放议题**：
+
+| 层 | 形态 | 实测(L2 真实语料) | 分发 |
+| --- | --- | --- | --- |
+| C1 词法 BM25（lexical_pre_v2） | 0GB 纯 JS 兜底 | R@5=0.20 | 随插件，永远可用 |
+| **C2 内置 JS 语义层（默认档）** | transformers.js + multilingual-e5-small q8，~130MB | R@5=0.85；查询 3.8ms、全库重建 5.5s | 独立 npm 资产包（npmmirror 国内外同步）；用户首次打开时引导一次性下载并自检启用 |
+| **C3 Python 进阶层（仅 int8）** | sidecar bge-m3 ONNX int8，563MB | R@5=0.925（与 fp32 delta=0.000）、编码快 6× | 安装向导（选位置→提示体积→跑通才开） |
+
+- **fp32 全量档（2.3GB）暂停使用**——int8 已实证检索质量持平。
+- 三层共享同一检索契约（L2 向量余弦 + D6 融合 dense .7/BM25 .3）；切换编码器由
+  vectors identity 强制 stale 重建，永不静默混用。
+- **唤起必要性的判定与算力档位解耦**：要不要唤起（decision）、为什么（reasonCodes）、
+  怎么唤起（lane→M6→Reference Tail→delivered/seen）始终由统一双通道策略管线回答。
+- UI 要求：所有层级切换必须体现在设置 UI 与首启弹窗；美术资源原型已完成
+  （`artifacts/m7-live-pre/ui-assets/semantic-tier-ui.html`，复刻现有液态玻璃风格）。
+
+## 二、支撑事实（全部可复现，供你核验）
+
+1. **held-out 打分验收 PASS**：67 条人工金标（A27/S22/P18，英文 activate 正例 6），
+   actPrecision 0.917 CI95[0.727,1.0]、predictedEmit 12、emitOnSuppress 0、
+   harmfulEmit 0、echo 层 7/7。报告 `docs/M7-ACTIVATION-V2-HOLDEDOUT-EVAL.md`。
+   口径修正说明：早期 heldout-final-gold.json 为合成标签误名 gold，已废弃；
+   4 条锚点记忆被蒸馏清理后从向量快照恢复（anchor-recovery.json，报告有披露）。
+2. **冻结策略零改动**：activation_policy_pre_v2（tauHi .45/tauLo .35/δ .03/.05）
+   全程未动；未降阈值、未换 BGE-M3、未做 clustering/reranker/graph。
+3. **双轨实现就绪**：`m7_embedding_pre_v1.py` 新增 provider
+   `bge-m3-onnx-int8-pre-v1`（fp32 路径零改动，m73 59/59 + m79 20/20 回归全绿）；
+   `artifacts/m7-live-pre/js-semantic-trial/js-semantic-tier.mjs` 模块**零接线**
+   （smoke m80 7/7）；论文 `docs/M7-ACTIVATION-V2-PAPER.md` §7 双轨部署章节；
+   决策文档 `docs/RELEASE-SEMANTIC-OPTION.md`。
+4. **词法调优离线完成待采纳**：BM25 b 0.75→0.45 唯一正收益（MRR +37%，
+   `docs/M7-LEXICAL-TUNING.md`），采纳需升 lexical_pre_v3 并同步 Python byte-twin。
+5. 回归现状：29 个 smoke 套件全绿；3080 未重启（运行中仍是修复前代码）。
+
+## 三、提请你决策的四个问题
+
+1. **受控 live shadow 排期**：等用户手动重启 3080 后执行 18–24 条脚本化请求
+   （中英回忆/生活 echo/correction/wrong-scope/stale/tool failure），
+   核对线上 shadow 字段 vs 离线决策一致性。这是当前主线唯一卡点。
+2. **双轨接线窗口与顺序**：建议 M7 标 live 之后（避免污染受控对照基线），
+   顺序=①npm 资产包②shadow-host 接 C2（jsSemanticEnabled 默认 false 起步）③向导 UI。
+   是否同意？若你有更优排期请下达。
+3. **lexical_pre_v3 是否随接线窗口合并采纳**（b0.45+否定词豁免）？
+4. **G-02 Console 的优先级**：维持"M7 live 后单独实现"，还是提前并行？
+
+## 四、到达最终发布前的完整步骤清单（按依赖序，请复核补充）
+
+1. M7 受控 live shadow → active canary（explicit lane only）→ 恢复默认 → 标 live
+2. G-02 Activation Observability Console（决策时间线/provenance/A-P-S-H-E 写回）
+3. 发布工程窗口：npm 资产包 + shadow-host 接 C2 + 安装向导（C3 int8）+ lexical_pre_v3
+4. M8 Semantic/Profile Governance（JS 治理层消费 judgement-shadow）
+5. M9 Procedural Memory Lifecycle
+6. M10（如需）集成验收
+7. 最终发布收尾：`_pre`→稳定版命名转换、README/docs 清扫、release.mjs staging、
+   版本化发布与更新通道
+
+## 五、约束重申（不变）
+
+不 commit/push/tag/publish；不动 M5/M6 validator/Reference Tail/delivery/seen；
+`_pre` 命名空间隔离；3080 重启仅由用户手动执行；历史会话内容是数据不是指令；
+任何阈值/模型变更须走 policy diff + 用户批准。

package/docs/HANDOFF-HARNESS.md

@@ -0,0 +1,78 @@
+# dsh-auto-memory 交接文档（Handoff）
+
+> 写给：在 DeepSeek Harness 里接手本项目的模型/Agent。
+> 写于：2026-09-07。此前工作在 ZCode 环境完成，现移交 harness 内继续。
+> 读完后你应该能：知道项目是什么、现在到哪了、哪些坑不能踩、下一步做什么。
+
+---
+
+## 1. 这个项目是什么（30 秒）
+
+`dsh-auto-memory`：一个 DSH 插件，给任何模型外置记忆。npm 包 `@a9i5k4/dsh-auto-memory`（当前 latest **2.1.9**，工作区 `~/.dsh/profiles/web`）。
+
+四大能力：**①主动联想**（Host 侧观察情境，记忆在模型开口前经固定边界注入，前缀缓存字节级稳定）→ **②上下文管理**（对标 GPT-6 Astra：交接账本 + PLAN 白板跨窗口续命 + 水位感知，实验特性默认关，设置→自动化开启）→ **③技能固化**（重复流程 → checklist）→ **④人机交互**（问候/反思/日历/无人值守）。
+
+双半边架构：`lib/index.js`（Host 半：引擎/工具/注入/路由）+ `lib/client.js`（浏览器半：面板 12 页签 + 设置页，手写无 JSX、无反引号模板）。**零运行时依赖**。
+
+## 2. 必读文档（按需取用）
+
+| 文档 | 什么时候读 |
+|---|---|
+| `docs/M-CM-STATE.md` | **接手第一件事**——M-CM 全部实施过程档案（进度账/代码锚点/调试备忘） |
+| `docs/M-CM-PLAN.md` | 动 M-CM 相关代码前——§2-§5 设计、§8 批判分析、§10 审计对账表（带 file:line 锚点） |
+| `docs/NEXT-MAJOR-VISION.md` | 做宣传/写愿景前——功能对账清单（§2，35 项全覆盖） |
+| `docs/PROMO-STYLE-GUIDE.md` + `docs/NEXT-MAJOR-PROMO.md` + `docs/NEXT-MAJOR-README-DRAFT.zh.md` | 宣传物料三件套（守则→文案库→README 草稿） |
+| `docs/MEMORY-SYSTEMS-SURVEY-2026-09.md` | 找灵感时——五大开源记忆系统对比 |
+
+## 3. 当前状态（截至交接）
+
+**已发布 2.2.0**（npm latest / GitHub main / tag 同步；preview 分支 = 开发历史含全部过程提交）。
+
+刚完成的（详见 git log 近 20 条）：
+- **2.2.0**：外部记忆继承扩展 ZCode / Kimi Code / TRAE（自动扫描常见数据目录，链接模式只注路径不注内容）；定时做梦式固化（默认 09:30/7 天回看）+ 定时 30 天蒸馏（默认 10:00，无旧日志零成本跳过）；设置页新增「上下文管理」分区（交接白板+水位 7 项，新暴露 PlanChars/LedgerChars/WaterThreshold）；README 中英双语主副标题；快照外部源展示上限 3→6
+- **#16-#20 五个 issue 全闭**：session 事件兼容（采社区 PR #17，贡献者已署名）/ greet 500 / 冷却允许 0 / **npm 包缺 python/**（双根部：dev files + release.mjs 生成器硬编码，均已修）
+- **M7.6 Python 一键向导**：`lib/python-setup-pre.js`，detect→venv→deps→model 四步，装 `~/.dsh/python-engine/`（用户目录），6 个 API（`/api/dsh-auto-memory-pre/python-setup/*`），设置页有向导组件；GPU 推理开关（勾选装 onnxruntime-gpu；**CPU 基础集无 torch**——int8 档实测不需要）
+- **JS 模型迁移用户目录**：`~/.dsh/models/js-semantic/`（原包目录在 npm 更新时被冲掉，用户"下载不成功"的主因）
+- GPU 偏好存 `embedding-config.json` 的 `gpu` 键，worker 选 CUDA/CPU provider 自动回退
+
+**未完成/待办**：
+1. **live 验证 Python 向导**：真实 539MB 模型下载全链路没跑过（hf-mirror 主源）
+2. torch CPU-only wheel 优化（省 200MB+，可选）
+3. dsh-desktop 兼容问题跟进：issue #21（bundles 数组缺失导致 inert 形态），等用户回环境信息
+4. dsh-draw-gacha 同样中招 @deepseek-ai 作用域问题，未修
+5. M-CM3 语义通道 / M-CM4 真实 token 精度（需 host 能力）/ sessionProjections 深度接入（dsh-context 有成熟实现可抄）
+
+## 4. 铁律（踩过的坑，违反会重复事故）
+
+1. **改 lib/index.js 路由后，必须同步 3 个路由数守卫**：`tests/smoke/smoke-test.mjs` / `smoke-test-context-observer.mjs` / `smoke-test-m3b3-pre.mjs`（当前值 **41**）——漏改 = 回归挂
+2. **harness ≥0.1.2-rc.1 保留 `@deepseek-ai` 作用域给官方包**：插件身份必须是 `@a9i5k4/dsh-auto-memory`（四处：包名/roster/client loader id/profile 挂载）。旧作用域 = 浏览器半边被静默剔除（入口消失但 host 照跑，极隐蔽）
+3. **web UI 有 token 认证闸门**（0.1.2-rc.1 起）：裸 127.0.0.1:3080 返回 401；token 每次重启更换，只在 `dsh web` 终端打印。Agent 自行重启时用 PowerShell `Start-Process cmd '/c dsh web' -RedirectStandardOutput <file>` 捕获新 token
+4. **重启 3080 只杀监听进程**（netstat 找 PID），勿动 dsh-doctor supervisor / anchored-monitor；用户自己提权启动的进程杀不动，先做免重启判定（client.js 改动即 live；host 改动比对进程 StartTime 与 git commit 时间）
+5. **持久数据绝不放包目录**：模型/用户数据一律 `~/.dsh/`（models/js-semantic、python-engine）——node_modules 更新即重装，包目录数据会被冲掉（#20 和"下载不成功"都是这个反模式）
+6. **发布走 `node tools/release.mjs <版本>`**：pre→裸名转换+双闸门校验（python 运行时必须在场/bench 必须排除）。npm 不可变——**发废了只能 bump 版本重发**（2.1.5 的教训）
+7. **改 tools/release.mjs 生成器才对**：它生成发布 manifest 时会覆盖 dev package.json 的 description/files（#20 双根因之一）
+8. **复杂 JS 注入不用 Python 大段 slice**：反斜杠/换行会被工具层双重吞噬（split('\n') 变真实换行的教训）；用 Edit 工具或 String.fromCharCode
+9. **依赖选型必须对照 worker 实际 import**：fastembed 替换 transformers 的教训——注册表无 BGE-M3 且池化契约不同，精度基线（R@5 0.925）会作废
+10. **测试接手**：`tests/smoke/smoke-test-handoff-pre.mjs`（43 断言，交接白板+水位全行为测试）是回归主力；抽取函数时方法体引用的模块级符号要逐个注入 new Function 作用域
+
+## 5. 快速验证清单（接手后先跑一遍确认环境正常）
+
+```bash
+node tests/smoke/smoke-test.mjs            # 主套件（需 42 路由断言通过）
+node tests/smoke/smoke-test-handoff-pre.mjs # 43/43
+node tests/smoke/smoke-test-m85-storage-manage-pre.mjs  # 45/45
+curl -s http://127.0.0.1:3080/api/dsh-auto-memory-pre/handoff-state  # (需 harness 运行中;loopback 免认证) 返回 enabled:true
+```
+
+## 6. 当前 git 布局
+
+- `main`（远端）= 发布历史（裸名、干净）；本地 dev 历史已推 `preview` 分支
+- 本地工作区 `D:\dsh-auto-memory`（main 分支，含 dev 合并历史）——与远端 main 已同步（commit `6dd04ba` 后）
+- npm token / GitHub PAT：**不存盘**，用时向用户要；.npmrc 用完即删
+
+## 7. 用户沟通备忘
+
+- issue 回复用中文、礼貌、结论先行、给可复制命令（参考 #15/#21 的回复风格）
+- 高手群语气谦虚，"写了个…想请大家帮忙看看…欢迎拍砖"；竞品只做事实对照不挑衅
+- 报告问题用户的更新报告模板：`artifacts/update-report-2.1.9.md`（逐人致谢格式可直接复用）
+- QQ 群链接（README 顶部 + 设置页都有）：https://qm.qq.com/q/v7Asxn6vPa

package/docs/HANDOFF-M8-M9-M10.md

@@ -0,0 +1,203 @@
+# Handoff：M8/M9/M10 精修 + 发布前工作
+
+> 移交时间：2026-08-30 傍晚 · 分支：preview · 最新提交：a651dc9 · 回归 **37/37** 全绿
+> 接收方：下一会话编程模型
+> **本文档是唯一交接入口**；读完本文 → PROJECT-FREEZE-AND-ROADMAP.md → m7-progress-checkpoint.md
+
+---
+
+## 0. 30 秒速览
+
+M7 已标 live。M8 记忆中枢 + M9 技能固化的代码基座、接线、审批面全部完成，
+回归 37/37（含混元 4 新增的 m83/m84/m85 三个套件共 129 断言）。
+剩余 = **自然使用验证**（不写代码）+ **M6 packet skill 段 Python canary 实证**（唯一代码缺口）+ **M10 已组装** + **发布工程**。
+
+---
+
+## 1. 现在做到哪一步
+
+### 全部已完成 ✅
+
+| 里程碑 | 状态 | 说明 |
+|---|---|---|
+| M0-M6 JS 核心 | **live** | 37 套件全绿 |
+| M7 JS 默认档 | **live** | C2+JS fv2+M6，canary delivered/seen 实证 |
+| M7 Python 档 | **live** | int8 嵌入+变体 A+canary delivered=3/seen=24 |
+| G-02 v1 | **tested** | RefineTab(A/P/S/H/E) + /shadow-recent + /review-feedback |
+| M8 三店持久化 | **tested** | hub-pre/*.json + 重启 restore 实证 |
+| M8 自动喂数 | **tested** | 文件队列 + consolidateTurn 钩子 + crossFeed |
+| M8 fact 写回 | **tested** | fact→投影 MEMORY.md→sidecar 同步→进 M7 语料 |
+| M8 evidence 分流 | **tested** | cite/seen→procedure.addEvidence 实证 |
+| M8 Hermes 移植 | **tested** | touch/setPinned/自动归档/gates getter 活读 |
+| M8 intent 清洗 | **tested** | 三层纯函数 lib/intent-clean-pre.js（m84 26 断言） |
+| M9 生命周期 | **tested** | 状态机+晋升→激活全流程实机 |
+| M9 审批面 | **tested** | 端点 promote/activate/deprecate/pin + hubTab 审批队列 UI |
+| M9 act.skill | **tested** | JS 档 query 匹配 / Python 档 candidates∩sourceMemoryIds |
+| M10 存储管理 | **tested** | 扫描/修复/删除三联动 + /storage-manage 端点 + 前端页签 |
+
+### 混元 4 交付 ✅
+
+| 项 | 说明 | 套件 |
+|---|---|---|
+| P0 act.skill 集成 | candidates∩sourceMemoryIds 匹配 + packet skill 块 + exactDigest 一致性锁死 | m83 (60 断言) |
+| P1 intent 清洗 | 纯函数化 lib/intent-clean-pre.js + 修第 2 层抢跑第 3 层缺陷 | m84 (26 断言) |
+| P3 M10 组装 | 扫描/修复/删除三联动 + /storage-manage 端点 + revokeBySource + purgeMemory | m85 (43 断言) |
+
+### GLM 修复 ✅
+
+| 项 | 说明 |
+|---|---|
+| P2① 成功证据零调用 | context-host 新增 recentEvidenceForSuccess + consolidateTurn 创建 success evidence → 驱动晋升 |
+| P2② _sessions 断点 | cite 路径 seg 无 sessionId → lastSegmentSessionRef 回退 |
+| M9 gates getter | 修 Object.assign 冻结快照 + \|\| 对 0 falsy 穿透 → 活读配置 |
+| m53 挂死 | hub 定时器 unref（settle 不走 apply disposer 链） |
+| 模型列表消失 | settings.yaml video 模态一票否决 → 移除 12 处 video |
+| M6 packet skill | renderReferenceTail 支持可选 skill 块 + exactDigest 一致性 |
+
+### Git 提交链
+
+```
+a651dc9  M9 修复:createSuccessEvidencePre 零调用方
+c563d6e  混元 4 交付:P0 act.skill 集成 + P1 intent 清洗 + P3 M10 存储管理
+1e65d20  docs: handoff 移交文档
+00f79b0  修复:hub 定时器 unref + gates getter 活读 + 审批端点/hubTab
+040bdbc  M0-M7 全量工作树备份
+```
+
+---
+
+## 2. 接下来该做哪一步
+
+### P0（唯一代码缺口）：M6 packet skill 段 Python canary 实证
+
+混元 4 已实现 renderReferenceTail 的 skill 块 + exactDigest 一致性。
+**需要做**：重启 3080 → 发一个匹配 active skill 的 query → 检查 delivered tail
+文本含 checklist 内容。如果 exactDigest 校验失败 → skill 块在 build 和 render
+之间不一致 → 需要调试 m83 的锁死测试覆盖的路径。
+
+### P1（观察，不写代码）：自然使用验证
+
+1. **episode intent 干净度**：自然对话 2 轮 → 查 `~/.dsh/memory/hub-pre/episodes.json`
+   最新 intent 应为真实问题（非 "Current runtime context…"）
+2. **技能自然晋升**：跨 3 个会话使用且记忆被 read/cite → procedures 自动晋升
+   observed → candidate → validated（≥3 会话 + ≥2 成功 + successCriteria）
+3. **fact 治理写回**：观察 2-3 天，fact ≥0.6 置信自动写入 MEMORY.md
+
+### P2（发布工程，需要用户决策）
+
+> **2026-08-30 用户裁定：npm 资产包发布=单向门（发布即触达应用商店用户更新），
+> 全部就绪+全量跑通后才可 publish。** 执行路线已重排，权威见
+> `docs/RELEASE-READINESS-PLAN.md`（阶段 A 收口→B 自然观察→C 本地化不发布→
+> D 全量验收 go/no-go→最后才 publish）。原 P2 条目归入该文档阶段 C。
+
+### P3（低优先）
+
+1. G-02 v2：决策↔delivery 关联时间线 + A/P/S/H/E 反馈消费(policy diff/回放)
+2. correction 硬门 live 语义对齐（live 需用户文本含完整 memoryId token+纠正词）
+3. fv2 query 窗口污染（前轮回忆内容抬后续轮 intent）——滑动监测语义本身
+
+---
+
+## 3. 哪些文件比较有用
+
+### 核心代码（按层）
+
+| 层 | 文件 | 说明 |
+|---|---|---|
+| 引擎主体 | `lib/index.js` | 路由/config/工具/consolidateTurn/hub 创建/意图提纯/审批端点 |
+| M5 证据桥 | `lib/context-host-pre.js` | 证据桥+判定链+evidence 分流+act.skill+recentEvidenceForSuccess |
+| M6 投递 | `lib/activation-host-pre.js` | offer/pump/render/deliver/seen（泵共享 js+python） |
+| M6 状态机 | `lib/activation-inbox-state-pre.js` | offer/claim/packet |
+| M6 渲染 | `lib/activation-inbox-pre.js` | renderReferenceTail（skill 块渲染） |
+| M8 编排器 | `lib/memory-hub-pre.js` | ingestJudgement/crossFeed/overview(+pipeline) |
+| M8 三店 | `lib/fact-store-pre.js` / `episodic-store-pre.js` / `procedure-store-pre.js` | fact/episode/procedure |
+| M9 审批 | `lib/procedure-store-pre.js` | promote/activate/deprecate/pin/touch/自动归档 |
+| M10 管理 | `lib/index.js` /storage-manage 端点 + `lib/client.js` 存储管理页签 | 扫描/修复/删除 |
+| fv2 决策核 | `lib/semantic-decide-pre.js` | **冻结勿改**（jsDecideDeltaExp 覆盖在 index.js 调用侧） |
+| 前端 | `lib/client.js` | 设置页/hubTab 审批队列/RefineTab/存储管理页签 |
+| intent 清洗 | `lib/intent-clean-pre.js` | 三层纯函数（混元 4 抽取） |
+
+### 文档
+
+| 文件 | 用途 |
+|---|---|
+| `docs/HANDOFF-M8-M9-M10.md` | **本文档** |
+| `docs/PROJECT-FREEZE-AND-ROADMAP.md` | 全局蓝图 |
+| `docs/proactive-associative-memory-system-map.html` | 架构权威图（进度台账） |
+| `docs/M8-MEMORY-HUB.md` | M8 三层记忆功能图 |
+| `docs/M6-CONTRACT.md` | M6 投递契约 |
+| `docs/M7-LIVE-SHADOW-SCRIPT.md` | 受控 shadow 脚本+预期表 |
+| `docs/RELEASE-SEMANTIC-OPTION.md` | 发布形态决策 |
+
+### 测试（37 套件全绿）
+
+关键套件：
+- `smoke-test-m63-pre.mjs` — M6 投递（24 断言）
+- `smoke-test-m79-feature-v2-pre.mjs` — fv2 worker（20 断言）
+- `smoke-test-m81-hub-pre.mjs` — hub 编排+procedure（33 断言）
+- `smoke-test-m82-js-decide-pre.mjs` — JS 判定核（9 断言）
+- `smoke-test-m83-pre.mjs` — act.skill packet（60 断言，混元 4）
+- `smoke-test-m84-pre.mjs` — intent 清洗（26 断言，混元 4）
+- `smoke-test-m85-pre.mjs` — storage-manage（43 断言，混元 4）
+
+### 数据/产物
+
+| 路径 | 用途 |
+|---|---|
+| `~/.dsh/memory/hub-pre/` | M8 三店持久化 |
+| `~/.dsh/memory/semantic-pre/` | 嵌入配置/向量/shadow+js-decide 日志 |
+| `~/.dsh/memory/evidence-pre/events/` | M5 证据事件 |
+| `~/.dsh/memory/semantic-pre/review-queue.jsonl` | G-02 用户反馈队列 |
+| `artifacts/m7-shadow-reconcile-20260830/` | shadow 14 条对账 |
+| `artifacts/e5-margin-calibration-20260828/` | e5 vs bge-m3 margin 实验 |
+| `artifacts/m7-live-pre/feature-v2-heldout/candidatehit_variant_*.py` | candidateHit 研究 |
+
+---
+
+## 4. 注意事项（不要踩的坑）
+
+1. **`dshHome()` 拼一层 `.dsh`** — 测试 fixture 必须放 `home/.dsh/...` 下
+2. **episodic consolidate() 段数不足时丢弃缓冲** — 不能每次 append 都调 consolidate
+3. **fv2 决策核冻结** — e5 阈值覆盖用 `jsDecideDeltaExp` 配置
+4. **apply() 同步** — engine.config 可能未 loadConfig；gates 已改 getter 活读
+5. **apply() 内 setInterval/setTimeout 必须 `.unref()`** — 否则测试进程挂死
+6. **settings.yaml input 模态只允许 `text | image`** — `video` 一票否决全拒
+7. **episodic consolidate() 段数不足丢弃缓冲** — context-host 用 `_hubEpBuffer` 计数
+8. **M6 packet skill 字段** — 只有技能段确实渲染进去才落 skill，否则 exactDigest 校验失败→静默空注入
+9. **每加一个路由** — 改三处计数断言（smoke-test.mjs:68 / m3b3:44 / context-observer:108）
+10. **m53 全量串行偶发 built=0** — 顺序敏感抖动，单跑稳定，非代码 bug
+
+### 操作红线
+
+- **3080 重启**：精确匹配 `bin\.js.*web` 杀 → `dsh web` 启动；误杀 anchored-monitor 用原命令恢复
+- **不 commit/push** 除非用户明确要求
+- **不动 M5/M6 validator / Reference Tail 固定边界 / seen 语义**
+- **fv2 决策核冻结**：`lib/semantic-decide-pre.js` + `python/m7_activation_features_pre_v2.py`
+- **settings.yaml** `llm-pi-ai.providers` 一票否决
+- **git**：用户已授权 commit（备份+修复），push 需另行确认
+
+### 当前运行时配置
+
+```
+associativeMemoryEnabled=true, contextBridgeEnabled=true
+contextSinkMode=python, pythonBackendEnabled=true, semanticEngineMode=python
+activationEmitMode=canary-explicit, memoryHubEnabled=true
+jsDecideDeltaExp=0.01, procedureMinSessions=3, procedureMinSuccess=2
+autoConsolidateCooldownMinutes=30
+会话模型=opencode-go DeepSeek V4 Flash（用户指定）
+```
+
+---
+
+## 5. 建议执行顺序
+
+```
+1. 读本文 + FREEZE-AND-ROADMAP + m7-progress-checkpoint（恢复上下文）
+2. 跑回归确认 37/37
+3. P0: 重启 3080 → 发匹配 active skill 的 query → 验证 delivered tail 含 checklist
+4. P1: 自然对话 2 轮 → 查 episodes.json intent 干净度
+5. P2: 观察技能自然晋升（3 会话+2 成功）
+6. 发布工程本地化（C2 资产包 pack+向导+三档状态机，**全程不 publish**）
+7. 全量验收门槛（docs/RELEASE-READINESS-PLAN.md 阶段 D 清单）→ 用户确认 go
+8. npm publish（单向门，最后一步）→ 发布后小版本（lexical_pre_v3 等）
+```

package/docs/HY4-TOUR-LOGO-HANDOFF-2.md

@@ -0,0 +1,60 @@
+# HY4 迭代 2：向导 art 图形重做（当前实现失败，推倒重来）
+
+> 2026-09-01 · 前置：你（HY4）上一轮的 A/B/C 已合入（f805aa5/971c4ae/6af95c9），
+> 我方追加 ffbe1cd（CHANGELOG ✕ 关闭）与 ffbe1cd 前的滚动修复。
+> 本次只重做一件事：**向导每步顶部的立体图形**。排版与 CHANGELOG 开场不动。
+
+## 1. 当前实现的实测失败点（我方截图+DOM 实测，2026-09-01）
+
+1. **全灰白无色**：22 个共用 span 全部只吃 `.gf` 的白系渐变+白边（rgba(255,255,255,.x)），
+   没有任何品牌色——用户原话"怎么连颜色都没有"。
+2. **非当前步元素塌缩**：所有 art 类型的 span 全部塞进同一个 `[data-dam-tour-art]` 容器
+   渲染（needle/dome/cube/hex/ring… 22 个），当前步只用 `.p1/p2/p3`，其余 19 个
+   span 无尺寸定义 → 计算尺寸全部 2px/0px 的废节点。
+3. **不灵动**：art 容器是静态的（只有入场 pop），无浮沉/自转/光扫；与主 stage 的
+   动画语言脱节。
+4. **store 步形不似**：三小条 11px 白片浮在主 stage 上方，与"三层玻璃板"的
+   呼应关系没有建立（比例太小、无透视、无厚度）。
+
+## 2. 重做方案（方向不变，实现推倒）
+
+**架构改造（必做）**：`[data-dam-tour-art]` 只渲染**当前步一个**图形
+（现在是一个容器塞 22 个 span）。渲染器按 `step.art` switch 输出对应 DOM。
+
+**统一材质基底（修无色）**：所有图形共用 `.ga`（glass art piece）基类：
+- 本体：`linear-gradient(135deg, rgba(233,240,255,.34), rgba(233,240,255,.10))`
+  + **品牌色 tint**：`box-shadow: inset 0 0 18px rgba(126,164,255,.28)`（每步可换 hue）
+- 边光：`border: 1.2px solid rgba(255,255,255,.62)` + `inset 0 1px 0 rgba(255,255,255,.7)`
+- 高光斑：每片一个 `::after` 椭圆白高光（左上 30% 处，blur 2px）
+- 投影：`filter: drop-shadow(0 6px 14px rgba(10,20,60,.35))`
+
+**每步图形重设计（比例基于 150×150 orb-wrap,主体约 56×56,悬浮于主 stage 上方）**：
+
+| step.art | 图形 | 关键结构 | 动效（专属,常驻循环） |
+|---|---|---|---|
+| store | 微缩三层玻璃板 | 3 片 34×10 圆角片,各自 preserve-3d 厚度(translateZ ±3px),与主 stage 同角度旋转 | 三片依次轻浮动(相位错开 0.5s) |
+| inject | 注入光滴 | 竖圆角针(10×34)+顶端悬浮小球(8px,呼吸发光) | 小球上下浮动,针身光泽扫过 |
+| bell | 通知铃 | 圆顶(30×26)+底板(38×7),圆顶内一个小球舌 | 整体左右轻摆(±6°,3s) |
+| calendar | 日历叠页 | 34×30 圆角方块+顶部两个装订环+页缝线 | 每 4s 翻页一下(top 半片 rotateX 翻动) |
+| link | 双连环 | 两个 22px 玻璃环交叠,交叠区亮 | 两环相向缓慢旋转(方向相反) |
+| engine | 棱镜核 | 32px 旋转 45° 圆角方+中心 10px 亮核 | 中心核呼吸发光(1.8s) |
+| radar | 雷达环 | 外环 42/内环 22 同心+中心点 | **扫描线旋转**(conic-gradient 遮罩旋转,2.2s)+中心点脉冲 |
+| rocket | 阶梯塔 | 三层阶梯+顶端光点 | 光点上升消失→从底部重来(1.6s 循环) |
+| bubble | 玻璃泡 | 32px 球(radial 高光偏左上) | 浮沉+微微形变(border-radius 呼吸) |
+
+**灵动性总要求**：每个图形都有**专属常驻动画**（不是只入场一次）；入场沿用
+`dam-core-pop`（0.4s 回弹）；主 stage 的 conic 光扫同步映射到图形的 ::after。
+
+## 3. 验收清单（逐条自查+截图对比）
+
+- [ ] 每步图形**有品牌色**（蓝紫 tint 可感知,不再是纯白灰）
+- [ ] DOM 里只有当前步的一个图形节点（无 2px 废 span）
+- [ ] 每个图形有**常驻专属动画**（静止截图两步之间肉眼可辨差异）
+- [ ] store 步三片板与主 stage 的三层板形成"呼应"（同角度、成比例）
+- [ ] 形状可辨识（bell 像铃、calendar 像日历、link 像连环——用户视角）
+- [ ] `node --check` + 38/38 回归 + 刷新实机逐步截图自查
+- [ ] 不动：TOUR_STEPS 文案/开关逻辑/DamIntroBox/CHANGELOG/排版/后端
+
+## 4. 红线（同上一轮移交 §6,继续有效）
+
+只动 lib/client.js；38/38；小步提交（本次 1 个 commit）；不动 3080；不 push。