@a9i5k4/dsh-auto-memory 2.2.2 → 2.2.3

package/docs/R2-POLICY-PLUMBING-BLUEPRINT.md

@@ -0,0 +1,99 @@
+# R2：JS Policy Plumbing 实施蓝图（2026-08-26 用户批准启动）
+
+> 状态：**规划阶段**——用户已确认 R2 启动（「既然现在基本都OK了，那我们就往R2往上走着」），
+> 本文是设计基线。**尚未动代码**；待用户终裁范围/默认值后实施。
+> 权威范围：docs/M7-ACTIVATION-V2-HANDOFF.md §第二轮（PII 三档硬过滤 / cross-workspace relay /
+> append-only policy registry / 文件审批队列写回）；与第一轮（Python feature v2）不得混合。
+
+## 0. 用户裁定（本轮核心，完整结构必须保留）
+
+**「跨工作区 → 让用户选择是 A 还是 S」**
+- 前半句 = 适用场景：跨工作区样本（命中当前工作区之外的记忆）。
+- 后半句 = 处理方式：由用户开关决定 Activate 还是 Suppress（per-case）。
+- 出处：heldout 批次 hd-048/049 rawChoice 原文「跨工作区让用户选择是A还是S。」（deferred）；
+  label-review 批次 cal-0036/0037/0055/0058 = P（advisory，「反正做后注入是建议性的」）；
+  hd-021/023 用户 override suppress→activate（宽松立场）。
+
+## 0b. 用户对 R2 默认值的两条修订意见（2026-08-26，原文钉住，实施时必须遵守）
+
+**① 隐私/PII 与 relay 的最终决定权在用户，不在默认值。**
+「密钥、证件号这一类的数据，进不进语料库肯定还是要由用户来决断的。用户觉得自己的隐私可以进本地库，那就让他写进去；如果用户觉得不进本地库，那就不进。cross workspace relay 这个也是同理。」
+→ 含义：PII 三档过滤的「high 剔除」不是硬规则，而是**每类敏感数据一个用户可决断的开关**（默认可给保守值，但用户可逐项放行/禁止进本地语料库）；relay 同理（off/advisory 只是初始值，最终由用户逐条/逐类决断）。R2 必须把「用户决断权」设计成显式可配置项，而非写死的策略。
+
+**② append-only policy registry 需与分层记忆机制协调，并前瞻存储管理。**
+「append-only policy registry，我觉得可能还要跟着我后面提到的记忆机制——即 3 层记忆、长期记忆（memory）等多次分层记忆的相关内容来协调。当然，我觉得在本项目中，这个记忆机制确实是可以实现 append only，但是同时，这个存储空间可能会有一定的挑战，所以后续的这些存储管理功能可能也需要去做一些工作。」
+→ 含义：(a) registry 不能孤立设计——它与 M8/M9 的 3 层记忆（working/short-term/长期）/ 用户画像 / 长期记忆的分层体系耦合，未来这些层也要 append-only 留痕；(b) append-only 在本地可行，但**无限增长有存储成本**——R2 就要为「存储管理」（保留策略/合并/压缩/归档/迁移）预留机制，不能只做无限追加。R2 的 registry 设计需与分层记忆模型对齐，并含存储治理。
+
+## 1. R2 四大件（按 HANDOFF 顺序）
+
+### 1a. PII 三档硬过滤（index_sync / context_push 前置）
+- 三档：`high`（凭据/密钥/证件号）/ `medium`（手机号/邮箱/地址）/ `low`（姓名/昵称）。
+- **2026-08-26 修订（用户决断权）**：三档不是「high 一律剔除」的硬规则，而是**每档一个用户开关**：
+  `allowInCorpus: true/false`（用户认为隐私可以进本地库就放行，否则不进）。默认给保守值（high=false /
+  medium=false / low=true），但用户在设置里可逐档决断；放行后该档内容可进语料库，但 context_push 前
+  仍带 piiClass 标记（advisory 注入时降级）。
+- JS 权威层实现（index-sync-pre 投影前 / context-host 组装前）；Python 只读显式下发的 piiClass 字段，
+  缺失即 fail closed（沿用现有 features.piiClass='unknown' 通道）。
+- 分类器：冻结词典+正则（不引入模型），先覆盖 zh 常见模式；全部命中需过黄金样本验收。
+- 边界：PII 决断只影响「自动唤起」，不拦截「显式 memory_recall」；用户手动检索自己的记忆不受限。
+
+### 1b. cross-workspace relay（用户开关）
+- 设置项（semantic 分组）：`crossWorkspaceRecall: 'off' | 'advisory'`（默认 off，用户可一键开；
+  **2026-08-26 修订：最终决定权在用户——off/advisory 只是初始值，用户可逐条/逐类决断 A 或 S**）。
+- 语义：off = 现状（当前工作区库内检索，跨工作区候选直接 dropped）；advisory = 跨工作区候选并入排名，
+  但 **level 降为 hint 且标记 advisoryOnly**，注入用建议性语气，「仅供参考」不打断当前任务；命中跨工作区
+  记忆时，决策行输出 `requiresCrossWorkspaceRelay: true`。
+- 候选来源：Python dense_search 当前按 workspaceKey 过滤 → relay 开启时放宽为「当前工作区 ∪ 全工作区
+  User 级记忆 ∪ 显式允许的 Workspace 级记忆」，但**注入侧仍由 JS 门控**（身份/PII/抑制名单）。
+- 与 hd-048/049 的呼应：开启后这类「跨工作区但用户想知道的」从 suppress 变为可选注入；per-case
+  仍可走精修面板 A/P/S 覆盖。
+
+### 1c. append-only policy registry（**2026-08-26 修订：与分层记忆协调 + 前瞻存储管理**）
+- 位置：`~/.dsh/memory/policies-registry/` 或沿用 `python/policies/` 的 append-only 模式（决策记录已有
+  先例：decision-record-*.json）。每条记录：parentPolicyVersion + diff + goldDigest + runId + createdAt +
+  生效范围。目标是任何策略变更可追溯、可回滚。
+- **与 M8/M9 分层记忆协调**：registry 不能孤立设计——未来 3 层记忆（working/short-term/长期记忆）、
+  用户画像、长期记忆都会有自己的策略与生命周期；registry 的 schema 需预留「分层/来源」维度，
+  使各层记忆的策略变更共享同一 append-only 留痕机制（parent 链可跨层追溯）。
+- **存储治理（用户明确要求前瞻）**：append-only 在本地可行，但无限增长有存储成本。R2 需为存储管理
+  预留机制：保留策略（按层/按类型 TTL 或体积上限）、可重建派生物标记（如聚合/索引可重建，原始事件
+  可归档）、压缩/合并（对可归并的决策记录做有损合并，保留 diff 摘要与 goldDigest）、归档/迁移（旧记录
+  移冷存）。**明确不删原始策略变更**（append-only 语义），但通过归档/合并控制热体积。
+
+### 1d. 文件审批队列写回
+- 已有基础：`POST /api/dsh-auto-memory-pre/review-feedback` append 到
+  `~/.dsh/memory/semantic-pre/review-queue.jsonl`（append-only，A/P/S/H/E 落盘）。
+- R2 补：审批队列消费端——用户确认某条后写回「策略覆盖」（per-memoryId 允许/禁止自动唤起），
+  写入 append-only 覆盖表；fv2 决策读覆盖表（JS 前置层），与现有抑制名单同路径。
+- **与用户决断权一致**：覆盖表即用户逐条决断的落点；relay/PII 的逐档决断也落这里。
+
+### 1e. 项目文档总览（用户可读的功能/指导入口；2026-08-26 用户要求）
+
+- **需求原文**：「这个项目已经越来越复杂了，结束后一定要在设置里加上项目文档的内容，让用户能够看到所有的功能和指导。」
+- 形态：设置页新增「项目文档/关于」入口（区别于现有 settings 分组的只读说明），以可滚动、可搜索的卡片/章节列出**全部功能与指导**——当前生效的检索档位/资产状态、M0-M7 各里程碑做什么、语义引擎安装与切换、跨工作区与 PII 决断开关、精修面板 A/P/S/H/E 用法、R2/未来分层记忆路线、常见问题与安全说明（记忆不出电脑等）。
+- 内容源：从 docs/ 下的权威文档（PROJECT-FREEZE-AND-ROADMAP、各 M*-CONTRACT、R2 蓝图等）提取**面向用户的语言**（非实现细节），维护成一份随插件发布的 `docs-user` 数据（结构化为 section:title/content 便于 client.js 渲染）。
+- 时机：**发布工程窗口**实现（与 npm 资产包、安装向导一起），但需求本身现在定稿；R2 实施时一并规划数据源与渲染接入点。
+
+## 2. 依赖与顺序
+
+1. 1a（PII 过滤）必须最先——它是 relay 的合法性前提（跨工作区先保证不带 PII）。
+2. 1b（relay）依赖 1a + 现有 workspaceRef 过滤链改造。
+3. 1c（registry）是发布工程地基，可与 1a 并行。
+4. 1d（审批写回）依赖 1b 的 advisory 通道 + 精修面板（已有）。
+
+**不动的**：M5/M6 validator/Reference Tail/seen；fv2 阈值策略工件（configHash 不变）；
+worker 的 requiresRelayFlag 由 JS 下发真实值替代硬编码 False。
+
+## 3. 验收要点（R2 完成门）
+- PII：构造三档黄金样本，index_sync 前后断言 high 被剔除、medium 被标记、low 可入候选。
+- relay：开/关两态下，跨工作区候选的决策行 requiresCrossWorkspaceRelay 与 level/advisoryOnly 符合预期；
+  开关一键生效（设置页）。
+- registry：变更记录 append-only、可追溯 parent+diff+goldDigest。
+- 审批写回：review-queue 消费 → 覆盖表 → fv2 决策读覆盖表（一条 A 覆盖生效）。
+
+## 4. 待用户终裁
+- ~~PII 三档分类器~~ → **已定**：冻结词典+正则（零模型成本）。
+- ~~relay 默认值~~ → **已定方向**：off 为安全初始值，但最终决定权在用户（逐档/逐条可决断）。
+- ~~registry 位置~~ → 倾向沿用 python/policies 的 append-only 模式；与分层记忆协调后定。
+- ~~审批写回粒度~~ → 倾向 per-memoryId；与用户逐条决断一致。
+- **新增待定**：PII/relay 的用户决断开关放设置页哪个分组；存储治理的保留/归档阈值初始值。

package/docs/RELEASE-READINESS-PLAN.md

@@ -0,0 +1,91 @@
+# 发布就绪规划（npm 发布 = 最后的单向门）
+
+> 裁定时间：2026-08-30 · 依据：用户明确「资产包对接应用商店，一发布用户即可更新；
+> 一切就绪且功能实验正常，全量跑通之后才能上 NPM」。
+> 本文取代 HANDOFF-M8-M9-M10.md §2 的 P2 发布工程排序，作为发布前的执行路线权威。
+> 关系：HANDOFF §2 的 P0/P1/P3 条目仍然有效，本文只重排**顺序与门槛**。
+
+## 0. 核心原则
+
+1. **npm publish 是单向门**：发布即触达用户更新，不可撤回 → 永远放最后一步，
+   且必须用户亲自确认 go 才执行。
+2. **发布前一切工作都在本地**：构建、打包、模拟首启、E2E 全部不碰 npm registry
+   （`npm pack` 可以，`npm publish` 不行）。
+3. **算法变更不赶首发**：lexical_pre_v3（b0.45）是算法+byte-twin 双侧变更，
+   独立窗口原则 → 首发带 lexical_pre_v2，v3 留作发布后小版本。
+
+## 1. 阶段路线
+
+### 阶段 A — 功能收口（代码窗口）✅ 2026-08-30/31 完成
+
+| # | 任务 | 状态 |
+|---|---|---|
+| A1 | act.skill Python canary | ✅ 技能段预算饥饿 bug 修复（renderReferenceTail 预留制）+ 重启 canary 模型逐字复述 checklist（02dacea）；途中发现 F1 stale 证据振荡/F2 miv 首轮竞态 |
+| A2 | G-02 v2 | ✅ 决策↔投递时间线（delivery 徽标+skill 标志）+ review-feedback GET（队列汇总+政策提示 hints）；端点+面板实测（f6f59bf） |
+| A3 | 风险评估 | ✅ docs/A3-RISK-ASSESSMENT-20260830.md：三者均不阻塞首发；F1 建议发布前小修（f2f0665） |
+
+### 阶段 A 原表（2026-08-30 规划时）— 已全部完成,留档
+
+| # | 任务 | 依据 |
+|---|---|---|
+| A1 | **P0 act.skill Python canary 实证**：重启 3080 → 匹配 active skill 的 query → delivered tail 含 checklist（exactDigest 不一致则修 m83 覆盖路径） | handoff §2 P0，唯一代码缺口 |
+| A2 | **G-02 v2**：决策↔delivery 关联时间线 + A/P/S/H/E 反馈消费（policy diff/回放） | 提前做——它是阶段 D 验收的观测工具 |
+| A3 | **fv2 query 窗口污染**：先评估是否首发阻塞项（默认裁定：不阻塞，记为已知限制；若验收发现实际误召回则升级） | handoff §2 P3.3 |
+
+### 阶段 B — 自然使用观察（不改代码，2–3 天窗口）⏸ 用户裁定延后（自动化方案待定）
+
+| # | 任务 | 通过标准 |
+|---|---|---|
+| B1 | episode intent 干净度 | 最新 episodes intent = 真实问题，非 "Current runtime context…" |
+| B2 | 技能自然晋升 | 跨 3 会话 + ≥2 成功 → observed→candidate→validated 自动走通 |
+| B3 | fact 治理写回 | fact ≥0.6 置信自动写入 MEMORY.md，无误写噪音 |
+| B4 | margin 校准观察 | canary 两档共有 margin 偏小议题：记录误触发/漏触发实例 |
+
+观察窗期间允许的唯一改动 = A2 的 G-02 v2 可观测性（不改决策行为）。
+
+### 阶段 C — 发布工程本地化（全程不发布）✅ 2026-08-31 完成
+
+| # | 任务 | 状态 |
+|---|---|---|
+| C1 | C2 资产包构建 | ✅ `artifacts/release-c2-asset-pack/`：tgz 78.4MB + BUILD-RECORD(SHA256 双核+解包回验全 MATCH)，manifest 与 `lib/semantic-js-pre.js` 冻结表逐字节一致；**未 publish**（21f3a3b） |
+| C2 | 首启下载向导 | ✅ 代码本就完备（五文件 SHA256+双镜像+原子落位下载器、引导卡）；本轮补 F2 首启向导弹窗（modelDownload kind，立即安装/稍后双选）+ F3 最小推理自检（384 维+模长≈1，失败整体 degraded 回 C1）（d03b59c）；实机验证向导渲染/ready 分支/触发条件 |
+| C3 | 设置页三档状态机 | ✅ c1/c2/c3 档位解析+切换 stale 重建既有；本轮补 G 条款「建库中」状态（jsSemantic.embedding → UI）（d03b59c） |
+| C4 | fresh-install 本地 E2E | ✅ smoke-test-c4-fresh-install-pre.mjs 8/8：干净 DSH_HOME + tgz 经 npm i 落位隔离 node_modules + 真实 e5 推理自检 + C2 稠密排序语义命中(0.785) + 词法保底（72003b2） |
+| C5 | 版本冻结准备 | ✅ 全量回归 38/38（新增 c4 套件）；本文档+台账同步（本提交） |
+
+| # | 任务 | 要点 |
+|---|---|---|
+| C1 | C2 资产包构建 | `@deepseek-ai/dsh-auto-memory-model-e5small-q8`：`npm pack` 产 tgz + SHA256 manifest + 双镜像地址配置（npmmirror+官方），**不 publish** |
+| C2 | 首启下载向导 | 弹窗确认→下载（进度/取消）→SHA256 校验→推理自检→后台建索引→原子切换；**无断点续传**（双镜像+校验兜底），UI 如实标注体积 ~130MB |
+| C3 | 设置页三档状态机 | 实际 c1/c2/c3（非"七态"）：词法 0GB / JS 语义 130MB / Python 563MB；切换即判 stale 重建 |
+| C4 | fresh-install 本地 E2E | 干净 home 模拟首启：装插件→向导下载→三档切换→全链 canary；**JS-only（无 Python）独立可跑** + Python 档独立可跑 |
+| C5 | 版本冻结准备 | policy 注册表/文档/架构图 progressLedger 同步；资产包版本号与主包兼容矩阵 |
+
+### 阶段 D — 全量验收（发布门槛，go/no-go）⏸ 等待阶段 B 观察窗后启动
+
+**验收清单（全部勾完才进 D6）**：
+
+- [ ] D1 回归全绿：全部 smoke 套件（38，含 c4 fresh-install）串行通过（C5 已预验 38/38，验收时复跑）
+- [ ] D2 E2E：C4 的 fresh-install 三档切换 + 双轨独立性实证（基础形态 c4 套件已覆盖；验收时补三档切换实机）
+- [ ] D3 观察窗回看：B1–B4 全部通过标准达成，有据可查（artifacts/ 留档）；含 F1 stale 振荡小修后的自然表现
+- [ ] D4 **发布默认值裁定**（需用户逐项确认，当前是实验值不能原样出厂）：
+  - 激活发射档默认（现 canary-explicit 是实验档；用户包默认建议 explicit-only）
+  - memoryHubEnabled 首装默认值
+  - procedureMinSessions/MinSuccess、jsDecideDeltaExp 出厂值
+  - 隐私面：PII 投影/scope 默认策略复核（JS 权威层不变量）
+- [ ] D5 发布物冻结：git tag 候选提交、CHANGELOG、资产包 SHA256 复核、
+      架构图 progressLedger 标 R-RELEASE
+- [ ] **D6 用户最终确认 go → npm publish（单向门）**
+
+### 发布后（小版本迭代，不再走 D 全流程）
+
+lexical_pre_v3（b0.45+否定词豁免+Python byte-twin 同步+重校准）→ int8 档资产包 →
+G-02 后续/correction 硬门对齐 → 各自独立窗口走小版本。
+
+## 2. 风险与红线（不变）
+
+- 3080 重启 = 杀 `bin\.js.*web` → `dsh web`（用户已授权自动重启测试）
+- 不 push；不动 M5/M6 validator / Reference Tail / seen / fv2 冻结核
+- settings.yaml `llm-pi-ai.providers` 一票否决；input 模态只允许 text|image
+- 每加路由改三处计数断言（smoke-test.mjs:68 / m3b3:44 / context-observer:108）
+- 资产包首发后**不可 yank**：C1 的 SHA256 manifest 与实际 tgz 必须在 D5 复核一致

package/docs/RELEASE-SEMANTIC-OPTION.md

@@ -0,0 +1,181 @@
+# 发布决策：语义增强的可选安装（Semantic Setup Option）
+
+> 2026-08-25 用户裁定 · 归属：M7 live 之后的"最终发布"工程阶段 · 状态：已定方向，待排期
+
+## 用户裁定的安装形态
+
+"自动唤起"作为**可选功能**放进设置界面：
+
+1. 设置中提供开关（默认关）；
+2. 打开后进入安装向导：**用户自选安装/下载位置**，明确提示**约需 2GB 空间**
+   （venv + torch CPU + BGE-M3 模型，见下方体积矩阵）；
+3. 下载与自检（health/embedding 视图 ready）**全部跑通后才真正开启**该功能；
+   任一步失败则保持关闭并回退纯 JS 词法链路（lexical_pre_v2，G8/H9 已断言
+   Python 缺失时结果逐项不变）。
+
+配套事实（已核实）：npm 包 `files=['lib','cordis.patch.yml']` 不含 python/；
+`pythonBackendEnabled` 默认 false + assoc∧inbox∧pythonBackend 三重门；
+SidecarClient spawn 失败 → circuit breaker → 结构化 unavailable → 词法回退。
+
+## 体积方案矩阵（基于 docs/M7-EMBEDDING-BENCHMARK.md 实测）
+
+| 方案 | 下载体积 | 质量(L2) | 延迟 | 结论 |
+| --- | --- | --- | --- | --- |
+| **bge-m3 fp32（现行冻结 D1）** | ~2.3GB | R@5 **0.925** / MRR 0.793，跨语言 20/20 | p50 129ms | 默认方案：效果冠军 |
+| qwen3-emb-0.6B | ~1.2GB | R@5 0.825 / MRR 0.693 | p95≈500ms 压线，RSS 3.3–4.7GB | 不换：省一半盘却损质量且更吃内存 |
+| multilingual-e5-large | ~2.3GB | 跨语言 0.60 已淘汰 | — | 否决先例 |
+| bge-m3 int8/ONNX 量化 | ~0.6–0.9GB（估） | 未验证（通常损失 <1%，须实测） | 待测 | **post-live 评估项**：需 onnx 导出 + 全量 benchmark 重验 + policy/configHash 重冻结 |
+| 小模型（<500MB 单/多语） | <0.5GB | 未测；e5 家族中文跨语有前科，风险高 | — | 仅在量化失败后再议 |
+| 纯词法（不开语义增强） | 0GB | 即当前基础层 | 零 | 两级产品的下级，长期存在 |
+| 云端 embedding API | 0GB | 取决于服务 | 网络 RTT | 违背本地记忆隐私前提，否决 |
+
+## 结论
+
+- 安装向导按 **~2.3GB** 如实标注；不为体积换掉效果冠军（qwen3 与 e5 的教训
+  都在 benchmark 报告里）。
+- "量化到 ~1GB 以内"列为 M7 live 后的独立评估项（含完整回归重验），若达标可
+  在向导中作为"精简下载"选项提供，而非替换默认。
+- 相关路线：M7 live → G-02 控制台 → M8/M9 → 本项 + 最终发布。
+
+---
+
+## 2026-08-25 补充：两项全网调研结论（已完成，待实测验证）
+
+### A. bge-m3 量化版（Python 进阶层瘦身）——✅ 有现成产物，≤600MB 达成
+
+| 项 | 结论 |
+| --- | --- |
+| **首选** | `Xenova/bge-m3` 的 `onnx/model_int8.onnx` = **542MB**（+tokenizer ≈563MB 总下载）。HF transformers.js 作者维护、76k 月下载、2026-02 仍在更新；quantize_config 确认为 ORT 标准 per_channel 动态 int8 |
+| 质量证据 | 唯一用户反馈称 int8 与 fp32 打平（轶事级）；**全行业无公开 fp32-vs-int8 对照表** → 我们的 L2 R@5=0.925 基准复验即最终裁决；建议同时记录 fp32/int8 向量余弦均值（>0.99 绿灯） |
+| 备选降级梯子 | GPUStack GGUF Q8_0 605MB → Xenova fp16 1081MB（略超线）→ optimum 自导出 avx512_vnni（⚠️ 社区教训：自导出曾掉 4–6 点，须核对 reduce_range/per_channel） |
+| 关键风险 | CLS 池化必须自己切（`last_hidden_state[:,0]` + L2 归一）；GGUF 默认 mean 池化会静默毁掉检索质量；sparse/ColBERT 头不在任何 ONNX 导出里 |
+| 否决项 | OpenVINO（无官方产物）、GGUF ≤Q6（零精度证据）、jina-v3（CC-BY-NC 非商用） |
+
+执行路径：下 Xenova int8 → Python ORT/sentence-transformers 加载 → 复跑 L2 基准
+→ 通过则以"精简下载"进安装向导。9700X（Zen4/5 AVX-512 VNNI）硬件适配。
+
+### B. 纯 JS 标准语义层（普通版 npm 即用）——✅ 可行，载体 transformers.js
+
+| 项 | 结论 |
+| --- | --- |
+| 运行时 | `@huggingface/transformers` v4（onnxruntime-node 预编译二进制，Windows x64 免编译直装；**锁版本**）。fastembed-js 上游已归档不用；tfjs USE 停滞不用；无需 ANN 库（几千条精确余弦毫秒级） |
+| **主推模型** | `Xenova/multilingual-e5-small` q8 = **118MB**（总 ~130MB）：最成熟（15 万下载）、MIT。必须实现 e5 前缀约定 query:/passage:，max seq 512 ⚠️ 风险：e5 家族在我们 L1 测试有前科（large 版跨语言 0.60 被淘汰）——small 必须先过我们自己的 L2 基准 |
+| **第一替补** | `Xenova/jina-embeddings-v2-base-zh` int8 = **161MB**：已发表 C-MTEB 强数字（T2Retrieval nDCG@10 80.6 / MMarco 78.0）、官方"中英混输无偏"设计、8192 ctx（长笔记友好） |
+| 中间档（stretch） | `Xenova/bge-m3` int8 ≈560MB 可在**纯 JS** 跑与 Python 同源模型（dense-only）——可作高级用户的"免 Python 准 sidecar"或交叉验证工具 |
+| 分发模式 | 首启按需拉取 + 本地缓存 = 业界标准（fastembed/transformers.js 先例一致），与我们已裁定的安装向导天然吻合；postinstall 静默下载是被社区视为恶习的做法，不做 |
+| 待办 | **离线实测裁决**：用我们的 L2 语料对 e5-small-q8 / jina-v2-zh-int8 / bge-small-zh 各跑一遍 R@5/MRR/nDCG/negHit（复用 lexical-tuning 评测管线思路），数字说话后再定标准层选型；预期显著高于词法 0.20，能否过 0.5 未知 |
+
+### 双轨（实为三级）产品形态定稿
+
+1. **基础层**（0GB）：lexical BM25 词法检索——现状，人人可用；
+2. **标准语义层**（~130MB，纯 Node）：transformers.js + 小模型 ONNX q8，
+   npm 装完引导一次小下载即可启用；
+3. **进阶层**（563MB 精简 / 2.3GB 完整，Python sidecar）：bge-m3 int8 或 fp32，
+   安装向导可选，效果冠军。
+层级间共享同一套 D6 hybrid 融合与激活策略接口；具体选型以 L2 离线实测为准。
+
+---
+
+## 2026-08-25 补充②：两级候选均已实测验证 ✅
+
+### C. JS 标准语义层实测（transformers.js 3.7.6 + multilingual-e5-small q8）
+
+环境：Windows x64 / Node 24 / onnxruntime-node 预编译二进制，模型本地离线加载。
+评测：L2 真实语料（251 episodes / 40 手写查询，e5 query:/passage: 前缀约定，
+mean pooling，512 token 截断）。产物在 artifacts/m7-live-pre/js-semantic-trial/。
+
+| 层 | R@1 | R@5 | MRR | nDCG@10 | negHit@5 |
+| --- | --- | --- | --- | --- | --- |
+| 词法 BM25（基础层） | 0.05 | 0.20 | 0.129 | 0.140 | 0.075 |
+| **JS e5-small q8（118MB）** | **0.60** | **0.850** | **0.703** | **0.760** | 0.225 |
+| Python bge-m3 fp32（进阶层） | — | 0.925 | 0.793* | 0.837* | — |
+
+\* fp32 行为 M7-2 生产口径（para-512 分块聚合）；JS 行为整篇截断口径，跨表对比仅供参考。
+性能：模型加载 679ms；文档编码 21.8ms/条（全库 251 条 5.5s）；查询 3.8ms/条。
+已知取舍：hard-negative 双子对的区分力弱于大模型（negHit5 0.225 vs 词法 0.075）。
+
+### D. Python 进阶层 int8 精简版实测（Xenova/bge-m3 model_int8.onnx, 542MB）
+
+同口径 head-to-head（整篇 512 截断协议，两侧同一代码路径；bge-m3 无前缀约定）：
+
+| 后端 | R@1 | R@5 | MRR | nDCG@10 | negHit5 | 全量编码 |
+| --- | --- | --- | --- | --- | --- | --- |
+| **int8 (onnxruntime)** | 0.675 | **0.925** | 0.772 | 0.807 | 0.200 | **44s** |
+| fp32 (torch) | 0.675 | **0.925** | 0.779 | 0.819 | 0.225 | 262s |
+
+- **R@5 delta = 0.000**：检索质量与 fp32 完全持平；MRR/nDCG 差异为噪声级。
+- 向量余弦 int8-vs-fp32 mean 0.9748（<0.99 但检索零损失，动态 int8 正常区间）。
+- 编码提速 ~6×；查询延迟 p50 16ms / p95 19ms（batch=1，Zen4 CPU）。
+- 产物：python/bench/models-xenova-bge-m3-int8/ + smoke_bge_m3_int8.py +
+  l2_bench_int8_vs_fp32.py（bench venv 已加 onnxruntime 1.23.2）。
+
+### E. npm 分发方案（用户裁定方向：国内国外统一源）
+
+| 层 | 分发方式 | 说明 |
+| --- | --- | --- |
+| JS 语义层模型（118MB 单文件） | **首选：独立 npm 资产包**（如 `@deepseek-ai/dsh-auto-memory-model-e5small-q8`） | npmmirror 自动同步 → 国内 `npm i` 即得，无需任何运行时下载；插件以 `env.localModelPath` 指 node_modules 内路径离线加载。npm 大资产包有成熟先例（@imgly/*-data 等） |
+| 同上兜底 | HF CDN 直连 / jsdelivr / GitHub Releases 多通道 | transformers.js 原生首启拉取路径；向导中作"在线获取"备选 |
+| bge-m3 int8（542MB） | GitHub Releases / 对象存储多通道，向导内让用户选线路 | 单 tarball 过大不宜进 npm；沿用已裁定的安装向导（选位置→提示体积→跑通才开） |
+
+### 三层最终状态（2026-08-25 用户最终裁定）
+
+| 层 | 体积 | R@5(同口径) | 裁定 |
+| --- | --- | --- | --- |
+| 词法 BM25 | 0GB | 0.20 | 基础回退层（lexical_pre_v3 调优窗口另计） |
+| **JS e5-small q8** | ~130MB | 0.85 | **默认语义层**：npm 安装后首次打开时引导一次性下载并自检启用 |
+| Python bge-m3 **int8** | ~563MB | 0.925（=fp32） | 进阶层唯一形态（安装向导可选）；**fp32 2.3GB 暂不使用** |
+
+裁定要点：①标准层走 npm 资产包分发，用户打开功能时同步下载一次即可长期离线使用；
+②Python 端只预备 int8 量化版（实测与 fp32 检索持平且快 6×），fp32 全量下载暂缓；
+③工程接线时机由主 Agent 排期——检索路由属 R1 收口冻结区，建议受控 live shadow
+完成后再切默认，避免污染对照基线。
+
+
+---
+
+## 2026-08-25 补充③：主 Agent 产品与工程规范（纠正版已采纳，固化）
+
+> 主 Agent 首轮曾误将 C1 定位为默认路径，经用户纠正后以下述规范为准：
+> **C2=默认主路径，C1=永久保底（仅模型未下载/加载失败/离线/低资源时的可用性保障），C3=高级可选**。
+
+### F. 产品行为规范（首启序列）
+
+1. 插件首次启动先以 C1 运行，页面与对话立即可用；
+2. 自动弹出一次 C2 安装向导（说明 ~130MB、用途、缓存位置、隐私边界）——弹窗必须出现，
+   但下载须用户明确确认：「立即安装」/「稍后」双选；稍后继续 C1 并在设置保留入口；
+3. 确认后后台下载资产 → **SHA-256 + 版本 + 维度 + 最小推理自检** → 通过则自动设为
+   默认语义层并后台构建向量索引；
+4. 建库期间继续使用 C1 不阻塞对话；C2 ready 后**原子切换**；
+5. 断点续传；失败显示原因并继续使用 C1；
+6. C3 只在「高级语义引擎」设置中出现，不自动下载、不自动覆盖 C2。
+
+### G. 设置页规范
+
+- 折叠组「语义检索引擎」：状态机 `未下载/下载中/校验中/建库中/就绪/损坏/更新可用`；
+  展示模型版本、资产大小、缓存位置、最近校验时间、向量数量、索引版本；
+  操作按钮 `安装/暂停/继续/重新校验/重建索引/卸载`。
+- 追加项（2026-08-25）：`reasoningObserverEnabled`（模型思维链监听，默认关、需显式开启）
+  与三级模式选择并列进入设置 UI；详见 docs/COT-WATCH-RFC.md。
+- **模式选择（segmented control，默认 auto 而非裸 C2）**：
+  `自动（推荐）`=C2 ready 则 C2 否则 C1｜`仅词法`=始终 C1｜`内置语义`=C2 失败回退 C1｜
+  `高级 Python`=C3 失败先回退 C2 再回退 C1。
+
+### H. 三层统一候选契约（在原字段上扩展）
+
+`memoryId/anchorId/scope/sourceRef/sourceVersion/fileDigest/recordDigest/score/
+method/rank` + 新增 **`engineTier`（C1|C2|C3）与 `modelIdentity`**。
+切换比较键：`provider+model+revision+dimension+normalization+configHash`
+不一致即 stale 重建。**C2/C3 的向量、索引、配置分别存放**——退出高级模式不得破坏 C2。
+
+### I. 下载与更新安全清单
+
+固定资产清单（模型 revision/许可/SHA-256）；临时文件下载校验后原子替换；
+禁止执行模型包内脚本（只加载固定 ONNX/权重/tokenizer）；更新失败保留旧健康版本；
+UI 显示实际下载源（直连/镜像）；卸载只删 derived 资产，不碰 Markdown/MemoryId/evidence。
+
+### J. 排期裁定（主 Agent 确认）
+
+M7 Feature v2 收尾不被 C2 打断；正式接入候选排序等 M7 live。发布工程窗口内部顺序：
+`C2 Asset Manager + Download Wizard → C2 embedding/index adapter → fallback/router
+(C2↔C1↔C3) → G-02 可视化与设置页`。允许并行预研：资产管理器与假模型适配器
+（fake model adapter，不影响激活算法归因）。