@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/docs/internal/TELEMETRY-EFFECT-REPORT-DESIGN-20260918.md

@@ -0,0 +1,146 @@
+# 用户端「效果统计与回传」设计（2026-09-18 立项稿）
+
+> 状态：**设计定稿，实现后置**（排在「Surface 前端重构之后、S 层之前」）
+> 用户原话：「我希望把这个统计功能扩展一下，也给用户们装上，让用户收集一下这个插件的效果，
+> 比如有效性。用户可以选择是否通过 GitHub 或者通过 QQ 群发给我」
+
+---
+
+## 0. 一句话
+
+**把已有的观测面（degrade 台账 + 配额探针 + tier0Meta）派生成一份「效果报告」，
+用户在本地看一眼、自己决定要不要发回来。插件永远不主动联网。**
+
+---
+
+## 1. 三条硬红线（不可协商）
+
+| # | 红线 | 理由 |
+|---|---|---|
+| **R1** | **插件自身绝不发起网络请求** | 这是**记忆插件**，数据面本身就是隐私面。回传只能是"用户手动搬运"，不能是"插件悄悄上报" |
+| **R2** | **报告只含聚合量，绝不含内容** | 禁止出现：记忆正文、文件路径、查询词、会话 ID、模型名、分钟级时间戳。只允许：计数 / 比例 / **分桶** / 布尔 / schema 版本 |
+| **R3** | **发送永远是显式动作** | 本地生成报告 = 随时可做（纯派生，无副作用）；**发出去** = 用户点按钮/复制粘贴，且事先能看到全文 |
+
+> **为什么这么严**：本仓已发布 npm 3.0.0，有真实用户与年下载量。
+> 普通插件的遥测泄漏是"行为数据"，记忆插件的遥测泄漏是**用户自己写下的东西**。量级不同。
+
+---
+
+## 2. 与既有观测面的关系（守 S10.4）
+
+**不新建状态源** —— 报告是**纯函数派生**，数据全部来自已经存在的东西：
+
+| 数据 | 来源 | 现状 |
+|---|---|---|
+| 降级频次/种类 | `degrade-pre/latest.json` 的 degrade 段 | ✅ R1–R3 已有 |
+| 配额判定四档、各层丢弃率 | 同文件的 `quota` 段 | ✅ R4 第 2 批已有 |
+| 注入侧 items/candidates/dropped/perLayer/tokens | `tier0Meta` | ✅ 已有 |
+| 配置开关 | 配置快照，**只取布尔/枚举，不取值** | ✅ 已有 |
+| 召回层分布、compaction 原因分布 | — | ⚠️ **需新增少量计数器** |
+
+### 2.1 唯一的新增状态（有界计数器）
+
+为回答「有效性」必须有的、目前**没有**的计数：
+
+```
+recall:      calls / withHits / emptyRate / layerMix{结论层,流水层,其他}
+injection:   tokensPerTurn(均值) / droppedPerTurn(均值) / perLayerDropRate
+compaction:  count / reasons{成功,no-removable,still-over-capacity} / recoveredChars
+scale:       daysInstalled / sessions / entries / logLines   ← 全部**分桶**
+```
+
+全部落进**同一个有界计数器对象**（复用 `lib/degrade-pre.js`，与 `quota` 并列），
+仍不新建文件、不新建配置键。**`layerMix` 是重点**：它直接回答
+「R4-B 的分层展示有没有让结论层真的浮出来」。
+
+---
+
+## 3. 报告形态
+
+```jsonc
+{
+  "reportSchemaVersion": "am_effect_report_v1",   // 必需：作者要能解析异构报告
+  "generatedAt": "2026-09-18",                     // ★ 只到天
+  "plugin": { "version": "3.1.0", "dshVersion": "x.y.z" },  // 版本必需，否则无法归因
+
+  "scale": {                    // ★ 全部分桶，绝不给精确值（防指纹）
+    "daysInstalled": "30-90",
+    "sessions": "50-200",
+    "entries": "100-500",
+    "logLines": "500-2000"
+  },
+
+  "features": {                 // 只有布尔/枚举，没有具体数值
+    "boardMode": "graph",
+    "handoffEnabled": true,
+    "semanticEngine": "js",
+    "pythonBackendEnabled": false
+  },
+
+  "effectiveness": {
+    "recall":     { "calls": 412, "withHits": 380, "emptyRate": 0.078,
+                    "layerMix": { "project": 0.31, "log": 0.52, "whiteboard": 0.09, "other": 0.08 } },
+    "injection":  { "tokensPerTurnAvg": 812, "droppedPerTurnAvg": 3.4,
+                    "perLayerDropRate": { "log": 0.61, "reflection": 0.12 } },
+    "compaction": { "count": 7, "reasons": { "ok": 6, "no-removable": 1 }, "recoveredChars": 18240 }
+  },
+
+  "health": {
+    "degradeCounts": { "semantic-arm": 2, "tier0-catalog": 0 },
+    "quotaVerdict": "balanced",
+    "degradedArms": ["c3(python)→c2(js)"]
+  },
+
+  "userReport": {               // ★★ 主观部分 —— 这才是「有效性」的核心
+    "rating": null,             // 1–5，默认空，用户填
+    "helpedMost": "",           // 自由文本，默认空
+    "broke": ""                 // 遇到的问题，默认空
+  }
+}
+```
+
+**关键设计**：`userReport` **默认全空**。有效性由**用户说**，不由插件猜 ——
+插件只提供客观事实（计数、分布、健康度），主观评价留给填写。
+这也顺带避免了"用行为指标冒充有效性"的构念效度问题。
+
+---
+
+## 4. 两条回传通道
+
+### 4.1 GitHub
+- 面板按钮「生成报告」→ 展示全文 → 「复制并打开 Issue」
+- 打开预填 URL：
+  `https://github.com/Aik358/dsh-auto-memory/issues/new?title=<enc>&body=<enc>`
+- **本机凭据只有 `pull: true` 权限**，所以这条路**只能由用户点** —— 与设计天然一致。
+
+### 4.2 QQ 群
+- 同一份文本，前面附一段可删的说明模板，用户复制后自行粘贴。
+
+### 4.3 附带：AI 侧工具
+提供 `memory_telemetry_report`（无参）——用户对 AI 说「生成效果报告」即可产出，
+比翻面板更顺手；输出与面板完全同源（同一派生函数），**不做第二套渲染**（沿用 M1 的纪律）。
+
+---
+
+## 5. 为什么建议「设计现在写、实现最后做」
+
+1. **UI 要长在 `lib/client.js` 上，而你正要重构 Surface 前端** —— 今晚做按钮，重构后大概率返工。
+2. **隐私面需要冷静设计** —— 凌晨赶工最容易漏字段；这条红线漏一次就无法挽回。
+3. **依赖今晚的收尾** —— 要统计的「层分布」「compaction 原因分布」正是 R4/G3 正在改的地方，
+   等它们定稿，计数器不用改两遍。
+4. **设计文档现在写成本≈0**，且能把今天的讨论结论固定下来不丢。
+
+→ **落位：Surface 前端重构之后、S 层之前**（正好是用户说的「万事俱备」那一刻）。
+
+---
+
+## 6. ⚠️ 若这批数据将来用于毕业论文，须额外注意
+
+用户论文方向与本系统强相关（`docs/internal/THESIS-OUTLINE-20260918.md`）。
+**真实用户效果数据对论文极有价值**（正好补上"无对外 baseline / 无真实用户数据"的缺口），
+但因此**同意文本的措辞就变成研究伦理问题**，不是产品文案问题：
+
+- 报告页需明确写：数据用于什么、谁会看到、是否匿名、能否撤回
+- 分桶设计本身是良好的去标识化，但 `userReport` 的自由文本**可能含个人信息**
+  → 该字段必须由用户**逐字确认**后再发，且提示"请勿填写隐私内容"
+- 若要做正式研究，需要走伦理审查（见论文缺口分析的"伦理许可"项）

package/docs/internal/THESIS-GAP-ANALYSIS-20260918.md

@@ -0,0 +1,89 @@
+# 毕业论文方向缺口分析 · dsh-auto-memory / dsh-anchored-monitor
+
+> 日期：2026-09-18 ｜ 视角：语言科学与数据分析（主修）+ 人工智能与数据分析（第二专业）
+> 结论摘要：代码与工程严谨度已经够用；缺口集中在**研究问题学术化、外部对照、消融、时间维度、测量工具信度**五处。
+
+## 一、可当论文资产直接用的部分（已具备）
+
+| 资产 | 现状证据 | 论文中的角色 |
+| --- | --- | --- |
+| 可运行系统 | lib/ 120 文件，`lib/index.js` 10389 行；npm `@a9i5k4/dsh-auto-memory` v3.0.0 已发布 | Method / System 章节；部署真实性 |
+| 真实用户外部效度 | 年下载 10,900；GitHub `Aik358/dsh-auto-memory` | 区别于"玩具原型"的说服力 |
+| 统计纪律雏形 | M7：69 条人工金标 held-out、pairId 聚类 bootstrap B=2000、预注册式冻结计划、零重调参 | 统计章节的骨架 |
+| 参照系统语料 | `.research/` cognee / Memori / supermemory；`.research-mirix/MIRIX-main` | Related Work 与 baseline 来源 |
+| 锚定线理论雏形 | `E:\dsh_dynamic_adjust\project_feasibility_report.md`（620 行）：三波段 spec 0-0.19 / mixed 0.2-0.49 / react 0.5-1.0、相变、路径承诺、措辞实验 | **最适合当论文主轴**：这是唯一有可证伪理论味的部分 |
+| 纵向日志基础设施 | 锚定监控 JSONL 事件流、每日工作日志、会话转写 | 时间维度实验的数据来源 |
+
+## 二、缺口清单（按评审最可能扣分的顺序）
+
+### 缺口 1 · 研究问题仍是工程目标，不是可证伪假设
+"记忆不断线""跨窗口续命"是产品目标。论文需要 RQ / H0 / H1 + 自变量·因变量·控制变量表 + 什么结果会推翻假设。
+
+### 缺口 2 · 没有对外可比的 baseline
+现有指标全部是自比（3.0 vs 2.5.3）。缺：与 ≥2 个公开系统（Mem0 / cognee / MIRIX / 无记忆裸模型）在同一任务集上的对照，并报告效应量而非仅 p 值。
+
+### 缺口 3 · 没有消融实验
+分层（Tier-0/1/2）、唤回、沉淀、白板、账本是一整套，无法归因到组件。优势是开关已全部在配置里，可直接跑 one-at-a-time 或 2^k 设计。
+
+### 缺口 4 · 没有时间维度 / 纵向曲线
+单轮或单会话测量测不到记忆系统的核心价值。缺：跨会话、跨天、上下文窗口填充过程中的纵向曲线（≥2 周、≥N 会话）。JSONL 已在写，但从未被当成数据集分析。
+
+### 缺口 5 · 测量工具本身没有被验证（语言科学的主场）
+we / let's / let me 目前是正则词频计数——没有标注一致性、没有信度报告、没有反例验证、没有词表敏感性分析。
+缺：人工标注子集 + Krippendorff α 或 Cohen κ + 词表扰动实验。
+**这一条是把"波段"从经验阈值升级为经构念效度检验的测量工具的关键**，也正是语言科学训练最能发挥的地方。
+
+### 缺口 6 · 统计推断不完整
+已有 bootstrap CI，但缺：多重比较校正（Holm/BH）、效应量（Cliff's δ / Cohen's d）、正式预注册登记、失败案例定性分析。
+
+### 缺口 7 · 伦理与合规
+- 若含人类被试（问卷 / 可用性测试）→ 需要伦理审查（IRB/HREC）批件；
+- 若只用自用日志 → 必须写明数据来源、脱敏方式、LLM 使用声明；
+- 第三方仓库许可必须逐个核对（cognee / MIRIX / Memori / supermemory 的 license 决定能否作为 baseline 分发）。
+
+### 缺口 8 · 学术写作要件
+Related Work 目前是散装仓库而非系统综述；缺论文骨架（Intro / Related Work / Method / Experiments / Results / Discussion / Limitations / Ethics Statement）与可复现 artifact 包（代码 + 数据 + 一键复现脚本）。
+
+## 三、三个候选研究问题（按两个专业的契合度排序）
+
+### RQ-A（推荐主轴）· 思维链语域指纹的构念效度与预测力
+- H1：人称/施事标记（we 型 vs let me 型）构成稳定语域，而非随机波动。
+- H2：语域可预测任务结果，且时间上先于结果（需时序检验，排除"高分导致 we"的反向解释）。
+- 方法：会话语料 → 人工标注 → 词频与句法特征 → 变点检测 / 分段 → 预测建模（交叉验证）。
+- 契合：语言科学（语域、语用、人称指称、指称链）+ 数据分析（变点检测、混合效应模型、交叉验证）。
+
+### RQ-B · 记忆注入措辞的言语行为效应
+- 假设：指令类措辞（命令式）与断言/建议类措辞（参考式）对模型行为改变率存在显著差异。
+- 设计：自变量 = 措辞类型（3 水平：命令 / 建议 / 中性陈述）；因变量 = 行为改变率、命中率、返工次数、token 成本；拉丁方平衡顺序；混合效应模型。
+- 已有基础：2026-09-08 记录的 A/B 分级实验设计（弱提示 vs 明确指令式）。
+- 契合：语用学（Searle 言语行为理论）+ 实验设计统计。
+
+### RQ-C（最保守，创新性最低）· 分层记忆注入的成本-收益曲线
+- 假设：注入预算是边际收益递减的，存在最优点。
+- 方法：扫描注入预算参数，画 quality–token 曲线。
+
+## 四、时间线（对齐已有课程节点）
+
+| 时间 | 动作 |
+| --- | --- |
+| 10 月上旬 | 定 RQ 与导师；写 1 页预注册（假设、判据、止损线） |
+| 10–11 月 | 数据采集启动：锚定监控与自用日志持续累积；适配 2 个公开 baseline |
+| 12–1 月 | 消融 + baseline 跑完；人工标注子集完成，出信度报告 |
+| 2 月 | 分析、作图、写作主体 |
+| 3 月 | 修订、artifact 打包、提交 |
+
+## 五、验收口径（"够了"的定义）
+
+1. 有一个可证伪假设，且写明什么结果会推翻它；
+2. ≥2 个外部 baseline 的同任务集对照；
+3. 一张消融表（逐组件增益）；
+4. 一份标注信度报告（α 或 κ）；
+5. 有效应量与置信区间，不只 p 值；
+6. 一键复现的 artifact（代码 + 数据 + 脚本）。
+
+## 六、最小下一步（本周可执行）
+
+1. 把 `project_feasibility_report.md` 1.5 节的措辞实验扩写成 RQ-B 的正式假设与变量表；
+2. 从现有会话 JSONL 中抽 200 条 reasoning 块，人工标注 we / let me 与"是否计划式"，算一次 κ；
+3. 核 cognee / MIRIX / Memori / supermemory 的 license，确定哪个能当 baseline。
+

package/docs/internal/THESIS-OUTLINE-20260918.md

@@ -0,0 +1,147 @@
+# 毕业论文总纲 · 资料 / 实验设计 / 论文大纲
+
+> 2026-09-18 ｜ 主线：思维链语域指纹（三波段）的构念效度、因果操纵与预测力
+> 数据底座：`E:\dsh_dynamic_adjust\anchored-monitor\demo-data\experiment.jsonl`（35.1 MB，另有 50.0 MB 备份）
+> 编制依据：本地已有学术资产（M7 两篇论文稿）+ 锚定线实验平台 + 外部文献检索
+
+---
+
+## 第一部分 · 资料清单（Related Work 骨架）
+
+### 簇 A｜记忆系统与记忆评测基准（提供 baseline 与任务集）
+| 文献/资产 | 位置 | 用法 |
+| --- | --- | --- |
+| LongMemEval（ICLR 2025，xiaowu0162/LongMemEval） | 外部 | 长时交互记忆基准，可直接借用其任务类型与评分协议，作为外部任务集 |
+| MIRIX（arXiv 2507.07957；本地 `.research-mirix/MIRIX-main`） | 本地已克隆 | 多智能体记忆架构，含 `evals/` 目录，可作为对照系统 |
+| cognee / Memori / supermemory | 本地 `.research/`（仅 .git，需完整检出） | 三个开源记忆实现，候选 baseline |
+| MemGPT / Mem0 / SimpleMem / AriadneMem | 外部 | 主流记忆架构谱系，Related Work 的骨架与数字对照来源 |
+| What Do Memory Benchmarks Actually Measure? | 外部（HF blog） | **方法论批判**：直接支撑本论文「基准测的不是存储」这一立论，务必精读 |
+| Long-Term Memory Security Survey（ar5iv 2604.16548） | 外部 | 记忆生命周期治理视角，可用于 Discussion |
+
+### 簇 B｜提示措辞与语用效应（本论文的干预实验理论来源）
+| 文献 | 位置 | 用法 |
+| --- | --- | --- |
+| The language of prompting（arXiv 2311.01967） | 外部 | 系统研究提示的语言学属性，是「措辞 → 效果」这一路的直接先例 |
+| Carrot or Stick? Reconciling Contradictory Findings on Prompt Tone Effects | 外部 | **矛盾发现综述**：说明语气效应不稳定，正是本论文做严格操纵实验的理由 |
+| 礼貌/粗鲁提示效应（宾大相关报道） | 外部 | 提供「措辞影响准确率」的公众叙事与反例，需找到原始论文核验 |
+| 本地锚定措辞实验（E1/E1.5/E2，见 feasibility report §1.5） | 本地 | 命令式 vs 中性/建议式 → we/let me 翻转的**一手预实验证据** |
+
+### 簇 C｜思维链的语言学分析（本论文的测量工具理论来源）
+| 文献 | 位置 | 用法 |
+| --- | --- | --- |
+| Robust Pronoun Fidelity with English LLMs（ar5iv 2404.03134） | 外部 | 代词使用与忠实性的关系，是「人称标记作为测量对象」的方法学先例 |
+| Understanding Aha Moments（ar5iv 2504.02956） | 外部 | 从语言模式识别推理转折点，方法上同类（用语词特征定位认知状态切换） |
+| CoT faithfulness 相关综述 | 待补 | 论证「思维链文本本身是可研究对象」，回应「只是装饰」的质疑 |
+
+### 簇 D｜本地已有学术资产（可直接复用，勿重复造）
+| 资产 | 规模 | 复用方式 |
+| --- | --- | --- |
+| `docs/M7-RESEARCH-PAPER.md` | 43.5 KB | 嵌入检索选型研究，含 RQ1–4、L1/L2 语料构建、效度威胁章节——**章节结构与写法可直接借鉴** |
+| `docs/M7-ACTIVATION-V2-PAPER.md` | 26.3 KB | 激活策略研究，含回声陷阱发现、金标演进、消融与证伪、跨语言迁移 |
+| `docs/M7-BENCHMARK-PLAN.md`、`M7-TASK-DISPATCH.md`、`M7-LABEL-REVIEW-REPORT.md` | 4–12 KB | 基准方案、任务派发、标注复核流程——标注信度的现成流程模板 |
+| `E:\dsh_dynamic_adjust\project_feasibility_report.md` | 620 行 | 锚定线完整技术叙事（含三波段、相变、路径承诺、措辞实验） |
+
+> ⚠️ 待核验项：以上外部条目的作者名、年份、卷期需在正式引用前逐条核（本清单只保证「存在且相关」，不保证书目字段准确）。
+
+---
+
+## 第二部分 · 实验设计（三个实验，观测 → 操纵 → 预测）
+
+### 共同测量口径（先冻结，全篇不再改）
+- 测量量：`persona_ratio = count("let me") / (count(positive) + count("let me"))`，滑动窗口 20 块。
+- 词典：正向 we / let's / we'll / we need / our；负向仅 let me；i will / i'll / i need 归中性（2026-08-17 校正，锚定线已落地）。
+- 波段：ratio < 0.2 → spec；0.2 ≤ ratio < 0.5 → mixed；ratio ≥ 0.5 → react。
+- 数据源：`E:\dsh_dynamic_adjust\anchored-monitor\demo-data\experiment.jsonl`（35.1 MB）+ `events.jsonl`，以及 `~/.dsh/sessions/{sessionId}/events.jsonl` 的真实会话流。
+
+> ⚠️ **开工前必须验证的前提**：`experiment.jsonl` 首行为 `{"type":"block_received",...}`，仅含 `textLength` 无正文。需先确认文件内是否存在携带 reasoning 正文的行类型（`events.jsonl` 的 `reasoning_block` 行确有 `text` 字段）。**若 35 MB 实验数据不含正文，E1 语料必须改从会话原始 JSONL 重建**——这是全部实验的前置阻塞项，第一天就要查清。
+
+### E1｜观测研究：语域指纹的构念效度（回答 RQ1）
+- **问题**：三波段是否对应可被人类标注者识别的、稳定的语域差异？还是正则词频的人为切分？
+- **材料**：从语料随机抽 300 个 reasoning 块（分层抽样：三波段各 100）。
+- **标注**：两位标注者独立判断「该段是集体规划式 / 行动者式 / 无法判断」，双盲于 ratio 值；先标 30 条试点校准标注手册，再标剩余。
+- **信度**：Cohen κ（二分）或 Krippendorff α（三分等级）；判据 **κ ≥ 0.61**。
+- **稳健性**：词表扰动（增删 ±1 个词、改权重 ±20%）后波段归属变化率；目标 **< 10%** 翻转。
+- **效度证据**：波段 × 标注类别的混淆矩阵、与 ratio 值的 ROC。
+- **产出**：一张构念效度证据图 + 一份标注手册（附录）。
+
+### E2｜操纵实验：措辞的因果效应（回答 RQ2）
+- **设计**：3（措辞）× 2（注入时机）被试内设计，任务是重复测量单位。
+  - 措辞：命令式（"read first and follow them"）/ 建议式（"reading the index is recommended"）/ 中性陈述（"an index exists"）。
+  - 时机：首轮 system prompt / 会话中途注入。
+- **因变量**：主=措辞注入后 5 个块的 persona_ratio 变化 Δ；次=任务正确率、工具调用数、返工次数、token 成本。
+- **刺激材料**：≥20 个等难度任务（可取自 Project2），每条件 × 任务 × 3 次重复。
+- **分析**：线性混合效应模型（固定效应=措辞、时机、交互；随机截距=任务、会话），Holm 校正，报效应量与 95% CI。
+- **先验依据**：feasibility report §1.5 的 E1/E1.5/E2 三轮预实验（命令式 → we 消失出现 3 个 let me；中性/建议式 → we 保持）。
+- **止损线**：若三水平无显著差异 → 保留 E1 作为主结果，E2 降级为探索性分析写入附录。
+
+### E3｜预测研究：波段是否领先于结果（回答 RQ3）
+- **问题**：波段先于任务结果（预测性），还是结果反过来改变波段（反向因果）？
+- **设计**：对每个任务单元取结果**之前**的窗口特征（ratio 均值 / 斜率 / mixed 停留时长），预测该任务单元的结果。
+- **分析**：时间滞后互相关（lag 从 -10 到 +10）、Granger 因果检验、以及仅用「前置窗口」特征的交叉验证分类（session 分组，防泄漏）。
+- **判据**：前置于结果的 lag 相关显著，且反向 lag 弱于正向 → 支持方向性。
+- **对照**：与零模型（仅用任务类型、块长度、会话位置预测）比较增量 AUC。
+
+### 伦理与合规（开工即办）
+- 数据为本人自用日志 → 写明来源、脱敏（去除绝对路径、会话 ID 哈希化）、LLM 使用声明。
+- 人工标注者若含他人 → 需知情同意说明；若仅本人 → 需报告单标注者的信度局限。
+- API 成本：E2 的 3×2×20×3 = 360 次运行，需先估 token 预算并设上限。
+- 第三方 baseline 的 license 需逐个核对后方可分发或复现。
+
+- **止损线**：三项主要判据任一未达 → 收缩论文范围（见第四部分风险表）。
+
+---
+
+## 第三部分 · 论文大纲（章节级）
+
+**题名（工作稿）**：思维链语域的三波段模型——大模型推理轨迹中的人称标记、构念效度与结果预测
+
+1. **引言**（1.5 页）
+   1.1 现象：同一模型同一任务，分数差异可达 8 分
+   1.2 从工程预设到科学问题：措辞是否是可操纵的自变量
+   1.3 贡献三条：① 人格语域的构念效度证据 ② 措辞的因果操纵结果 ③ 波段的时序预测力
+   1.4 论文结构
+2. **相关工作**（2.5 页）
+   2.1 记忆系统与记忆评测（LongMemEval / MemGPT / Mem0 / MIRIX）——说明本文不评记忆质量，而评**思维轨迹的语域**
+   2.2 提示措辞与语用效应（language of prompting；语气效应的矛盾发现）
+   2.3 思维链的语言学分析（代词忠实性、aha moment 检测）
+   2.4 研究空白：三波段模型从未被构念效度检验，也从未被因果操纵验证
+3. **数据与方法**（3 页）
+   3.1 语料：来源、规模、抽取与脱敏
+   3.2 测量：词典、窗口、ratio 与波段定义（冻结版本号 + 哈希）
+   3.3 标注方案与信度估计
+   3.4 统计模型：混合效应模型、bootstrap、多重比较校正
+   3.5 可复现：脚本、种子、环境
+4. **实验一：构念效度**（2.5 页）——结果表 + 混淆矩阵 + 词表扰动稳健性
+5. **实验二：措辞的因果效应**（3 页）——主效应与交互、森林图、失败案例分析
+6. **实验三：时序预测与方向性**（2 页）——滞后相关、Granger、增量 AUC
+7. **讨论**（2 页）
+   7.1 三波段是语域，不是一个分数
+   7.2 对提示工程的实践含义（建议式优于命令式）
+   7.3 对记忆系统设计的含义（注入措辞也是接口设计）
+   7.4 与"语气效应矛盾发现"的对账
+8. **效度威胁与局限**（1 页）——单模型家族、单语言（英语为主）、正则测量的上限、自用数据的样本偏倚
+9. **结论与未来工作**（0.5 页）
+10. **附录**——标注手册、全部提示词模板、完整结果表、复现脚本清单
+
+**字数目标**：正文 6000–8000 词 + 附录。
+
+---
+
+## 第四部分 · 风险表与收缩路径
+
+| 风险 | 概率 | 影响 | 应对 |
+| --- | --- | --- | --- |
+| experiment.jsonl 无正文（前置阻塞） | 中 | 高 | 改从会话原始 JSONL 重建语料；第一天验证 |
+| 标注信度 κ < 0.61 | 中 | 高 | 改标注手册、合并为二分标注、或把 E1 降为描述性 |
+| E2 无显著差异 | 中 | 中 | E1 升为主结果，E2 转探索性附录 |
+| 波段是连续量而非相变 | 中 | 中 | 改为连续测量论文（更保守但仍成立） |
+| 样本量不足（会话数少） | 中 | 中 | 先跑 power analysis；不足则做被试内重复测量 |
+| 伦理/导师不认可用自用数据 | 低 | 高 | 提前与导师确认；备选是公开任务集上的受控实验 |
+
+---
+
+## 第五部分 · 立即执行的三步（本周）
+
+1. **验数据**：跑一次解析脚本，确认 `experiment.jsonl` 与真实会话 JSONL 中 reasoning 正文的可得性与块数量，产出「语料可得性报告」。
+2. **验信度**：抽 30 条 reasoning 块，定标注手册，标一遍，算第一版 κ。
+3. **定题**：把本大纲压缩成 1 页预注册（假设、判据、止损线、样本量），交导师确认。

package/docs/internal/THREE-LAYER-CONTRACT.md

@@ -0,0 +1,219 @@
+# 三层检索契约（Tier-0 / Tier-1 / Tier-2）v2
+
+> 2026-09-14 定稿（v2 重整：补 RAG 管线要素、用实测数据定预算）。
+> 背景：三层 OpenViking 式架构**验收"以为过了、实际没过"**——只验了声明项，没验能力可达。
+> 本文件是施工与验收的**唯一依据**。相关：`ROADMAP.md`（主线）、`TODO-GRAPH.html`（P0-② 阶段门）、`MEMORY-MUTATION-AND-INDEX-DESIGN.md`（索引侧）。
+
+---
+
+# 第一部分 · 三层安排（Arrangement）
+
+## 1.1 为什么是三层
+
+三层的本质是**把"要不要用"和"内容是什么"分开**：上层负责**判断与缩窄**（便宜、常驻、永远在场），下层负责**给出证据**（贵、按需、可溯源）。因此判定顺序是"上层先出 → 搜索空间缩窄 → 才下探"，而不是把三层一起灌进上下文。
+
+## 1.2 三层总表
+
+| 维度 | **Tier-0 · 目录（指引层）** | **Tier-1 · 摘要（候选层）** | **Tier-2 · 原文块（证据层）** |
+| --- | --- | --- | --- |
+| 回答的问题 | 要不要用某条记忆？ | 该下探哪一条？ | 原文到底怎么说的？ |
+| 输入 | 项目笔记 + 用户级记忆 + 当日日志的**结论行** + 白板 | 语料记录（日志 / 反思 / 笔记 / 用户记忆 / 白板） | 命中记录的 chunk（`chunkId = hash(记忆ID, 内容摘要, 序号)`） |
+| 产出 | 每条 **1 行**：`标题 · 一句结论 · layer · status · 日期` | 每条 1 段摘要（≤`L1` 字符）+ `id` + 得分 + 匹配原因 | 命中块原文 + `文件:行号` + `digest` |
+| 常驻性 | **每轮都注入**（不依赖命中） | 命中后按需（top-`K`） | 需要证据时下探 |
+| 预算 | ≤ `B0` = **800 token** | ≤ `L1` = **140 字符** × `K` = **8** | ≤ `B2` = **2400 字符** / 次 |
+| 失效方式 | 陈旧即被上游覆盖（无状态） | 状态过滤（`superseded`/`retracted`） | 随快照版本（`miv`）失效 |
+
+## 1.3 数据流
+
+```
+源文件（日志 / 反思 / 笔记 / 用户记忆 / 白板）
+   │  ①抽取：标题 → 首句 → 截断（三级降级）      ← Tier-1 的产出
+   ├──────────────► Tier-1 摘要（≤140 字符/条）
+   │  ②分块：chunkId = hash(记忆ID, 内容摘要, 序号)  ← Tier-2 的存储单位
+   ├──────────────► Tier-2 原文块（≤1500 字符，实测）
+   │  ③目录：从"当前认知"里抽 1 行/条              ← Tier-0 的产出
+   └──────────────► Tier-0 目录（≤800 token，常驻）
+
+检索时：Tier-0 先出 → 缩窄 → 命中不足才下探 Tier-1 → 需要证据才取 Tier-2
+```
+
+---
+
+# 第二部分 · 每层的要素清单
+
+## 2.1 Tier-0（目录）要素
+
+| 要素 | 要求 |
+| --- | --- |
+| 内容来源 | **只取"当前认知"**：项目笔记 / 用户记忆 / 白板的标题与结论行；**禁止原始转储** |
+| 每行字段 | `标题`、`一句结论`、`layer`、`status`、`日期`（+ 内部 `id` 供下探） |
+| 优先级 | `project > whiteboard > user > log`；同层按日期倒序（超预算时按此裁剪） |
+| **per-layer 配额（必须有）** | 纯严格优先级会让 `project` **吃满预算**——真实语料实测：project 77 块把 800 token 全占，`whiteboard`/`user`/`log` **一条都进不来**，于是"分层"退化成单层。**规定：`project ≤ 60%·B0`；`whiteboard`、`user` 各**保底 10%**；剩余额度再按优先级填充** |
+| 刷新时机 | 每轮或笔记变更后重建；重建**必须廉价**（纯文本处理，不涉嵌入） |
+| 状态位 | 带 `status`；被 `superseded`/`retracted` 的**不出现在目录**（I5） |
+| 降级 | 目录为空/来源缺失 → 输出显式提示，不静默给空（I7） |
+
+## 2.2 Tier-1（摘要层）要素 —— 第二层要做好的事
+
+| # | 要素 | 说明与要求 | 现状 |
+| --- | --- | --- | --- |
+| 1 | **抽取规则** | 标题 → 首句 → 截断（三级降级），保证**任何记录都有摘要** | ✅ 已有（`l0-extract-pre.js`） |
+| 2 | **必须保留"判定信息"** | 摘要里要留下**结论句**（例："已拍板 X""根因是 Y"）；只留主题词等于没用 | ❌ 缺（决策句常被截掉） |
+| 3 | **长度上限** | ≤`L1`=140 字符；超限按"信息密度"裁，不是简单截断 | ⚠️ 现约 93 字符，无规则 |
+| 4 | **层级与状态** | 每条带 `layer`（五值）与 `status`（三值） | ❌ 缺（C1 在做） |
+| 5 | **得分与匹配原因** | 返回 `词法×n / 语义×score` 与命中词，便于调参与解释 | ✅ 已有 |
+| 6 | **多路融合** | 词法 + 语义 → RRF 融合；任一路不可用要标注（I7） | ⚠️ 语义臂会静默消失 |
+| 7 | **同源去重 / 合并** | 同一文件多个块命中 → 合并为一条显示，避免刷屏占预算 | ❌ 缺 |
+| 8 | **排序体现当前认知** | 笔记/结论优先于历史日志；被替代项降权或过滤 | ❌ 缺（现为纯 top-K） |
+
+## 2.3 Tier-2（原文块）要素 —— 第三层要做好的事
+
+| # | 要素 | 说明与要求 | 现状 |
+| --- | --- | --- | --- |
+| 1 | **分块粒度** | 按**记录/小节**切（现有 `chunkOrdinal/chunkCount`）；实测 p50=418、p90=1186 字符 | ✅ 已有 |
+| 2 | **块边界与重叠** | 边界不切断结论句；跨块语义断裂处应有**少量重叠**（或把结论句并入首块） | ❌ 未见重叠 |
+| 3 | **块元数据** | `chunkId`、`memoryId`、`sourceRef`、`recordDigest`、`chunkOrdinal/Count` | ✅ 已有（15 字段） |
+| 4 | **按块取，不取整篇** | 只回命中块（I3）；长文档禁止整篇灌入 | ⚠️ 契约新定 |
+| 5 | **可溯源** | 返回 `文件:行号` + `digest`，便于核验与回滚 | ✅ expand 已返回 |
+| 6 | **超长块处理** | 单块 > `B2` 时：先截结论句 + 尾注"（已截断，全文 N 字符）"，不静默丢 | ❌ 缺 |
+| 7 | **保真** | 原文不改写、不摘要（引用必须逐字） | ✅ |
+| 8 | **编码与 BOM** | 读回时剥离 BOM，保持 UTF-8 | ⚠️ 需断言 |
+
+---
+
+# 第三部分 · 一条好 RAG 管线的关键部件（对照表）
+
+| # | 部件 | 我们要做到什么 | 现状 |
+| --- | --- | --- | --- |
+| 1 | **分块（Chunking）** | 语义完整、带元数据、必要时重叠 | ✅ 主体已有；重叠缺 |
+| 2 | **嵌入（Embedding）** | 引擎身份入键（模型/维度/归一化）；换引擎=全量重建 | ⚠️ OR 双引擎要写清切换语义 |
+| 3 | **索引（Index）** | 向量 + 词法双路；**缓存键=chunkId**（内容寻址） | ❌ 现按整份语料哈希（P0-④） |
+| 4 | **查询理解** | 多键提取、时间意图（"最近/上次"） | ⚠️ 部分 |
+| 5 | **召回与融合** | 词法 + 语义 RRF；分数可解释 | ✅ 融合已有；语义臂不稳 |
+| 6 | **重排（Rerank）** | 现在靠融合排序；有需求再上轻量重排 | ⚠️ 够用 |
+| 7 | **过滤与权限** | `layer`/`status` 过滤、来源白名单、**检索+注入双层** | ❌ 缺（C1/C2） |
+| 8 | **上下文组装** | 预算分配、排序（相关性 vs 时序）、去重、provenance 标注 | ❌ 缺（C5） |
+| 9 | **可溯源（Grounding）** | 每条注入带出处（文件+行号+digest） | ✅ 部分 |
+| 10 | **评估（Evaluation）** | ground truth 集 + 指标（命中率/答案可达率/噪声比/token） | ⚠️ 只有词法基线 |
+| 11 | **容错与降级** | 跳过+计数+quarantine；未就绪显式标注（I7）；fail-open | ❌ 现在 fail-closed 且静默 |
+| 12 | **新鲜度与增量** | 写后防抖触发、快照 epoch、差量同步 | ❌ 缺（P0-④c/④e） |
+
+---
+
+# 第四部分 · 预算（Budget）：要，而且要算出来
+
+## 4.1 结论先说
+
+**需要预算，并且它必须是三层一起核对过的总量。** 三层若同时全给，会直接顶穿注入预算——这不是理论，是实测：
+
+```
+Tier-0 800 token(≈1600 字符) + Tier-1 8×140(=1120 字符) + Tier-2 2400 字符
+= 5120 字符，而注入预算 injectBudgetChars = 8000 字符（**可配置项**；见 SPEC §0.2）
+→ 三层仍不同时给：本契约规定"逐层下探"，与预算是否宽裕无关
+```
+
+**所以本契约规定：三层不是"同时给"，而是"逐层下探"**（见 §5 闸门）。默认只给 Tier-0；命中不足才给 Tier-1；要证据才给 Tier-2。
+
+## 4.2 预算的实测依据（E2，2026-09-14 重启后复跑）
+
+来源：`~/.dsh/memory/semantic-pre/derived-corpus.json`（重启后重建，**34 条记录**，字段含 `text`）：
+
+| 指标 | 实测值 |
+| --- | --- |
+| 单条原文长度 | 最小 **144** ／ p50 **760** ／ p90 **1196** ／ p99 **1692** ／ 最大 **1692** 字符 |
+| 合计 | 24,254 字符（均值 713） |
+| 超过 1000 字符 | 7 条（20.6%） |
+| 超过 2000 / 5000 / 10000 字符 | **0 / 0 / 0 条** |
+
+**对账（证明"语料 text 长度"这个代理指标可信）**：抽 2 条真实 `expand` 与语料长度比对 —— `mem_d55f8e8e`：expand 报 **1499 字符** ↔ 语料 1499 ✅；`mem_5a7f779a`：expand 报 **1403 字符** ↔ 语料 1403 ✅。
+
+## 4.3 由此定出的预算（初值）
+
+| 参数 | 取值 | 依据 |
+| --- | --- | --- |
+| `B2`（Tier-2 单次） | **2400 字符**（≈1200 token） | E2 实测 max=1692；语料仍在增长（条均 713），留 ~42% 余量；超出者按 §2.3-6 截断（截结论句 + 标注"已截断，全文 N 字符"） |
+| `L1`（Tier-1 每条） | **140 字符**（≈70 token） | 原文 p50=760 → 压到 ~1/5 保留事实；现摘要约 93 字符偏短、缺结论句 |
+| `K`（Tier-1 条数） | **8** | 8×140=1120 字符 ≈ 560 token，占注入预算 ~1/4 |
+| `B0`（Tier-0 常驻） | **800 token**（≈1200 字符） | 占注入预算约 1/4；目录"每条 1 行"约 12 字 → 可容纳 ~30 条当前认知 |
+| 总量上限 | 逐层下探，**不同时给**；单轮注入总长 ≤ `injectBudgetChars`（默认 8000） | §4.1 的实测校验 |
+
+> **口径（与 SPEC §0.2 一致，别再当矛盾）**：Tier-0 常驻有两层门 —— `tier0MaxTokens` **默认 400**（**可配置项**），硬上限 `B0` = **800 token**；属「默认值 vs 上限」之别。
+
+## 4.4 中间"概览层"要不要？——**本数据下不需要**
+
+OpenViking 是 L0(~100 token) → L1(~2k) → L2(原文)。我们的实测是：**原文本身 p90 只有 1196 字符、max 1692**，L0(140 字符) 直接跳到原文块（≤2400）**跨度可接受**。
+判定规则（写进契约，可复测）：**当出现单块 > 5000 字符的源（如整篇 PLAN.md、超长日志）时，才需要"概览层"或更细的分块**；当前 **0 条**命中该条件（最近复核：34 条，max 1692）。
+
+## 4.5 预算不是拍脑袋（校准流程）
+
+1. 跑 **E1**（预算—召回曲线）：扫 `L1 ∈ {60, 90, 140, 220, 400}`、`B0 ∈ {200, 400, 800, 1600}`，记录命中率与**答案可达率**；
+2. 跑 **E3**（直接灌 vs 逐层）：三策略的正确率 / token / 噪声比；
+3. **选值规则：在满足"答案可达率 ≥ 0.9"的前提下取最小预算**（膝盖点）；
+4. 校准结果回写本表，并同步 `TODO-GRAPH.html` 的 P1-⑯。
+
+## 4.6 token 计量口径（不统一，I1 就无法验证）
+
+仓库既有 `estimateSessionTokens = ceil(chars/4)+4`（`lib/index.js:2471`）**对 CJK 低估 2–4 倍**，直接拿它当预算门会**静默突破 I1**。
+
+- **契约规定：预算门取 `max(ceil(chars/2), 仓库口径)`**（保守值恒 ≥ 仓库值）；
+- C4 的 Tier-0 模块已按此实现并锁进测试；`estimateMode:'repo'` 可复算仓库口径对照；
+- 换算：`B0 = 800 token` ≈ **1600 字符**目录容量。
+
+---
+
+# 第五部分 · 递进闸门
+
+```
+默认（常态）：只注入 Tier-0（≤ B0 = 800 token）
+  ↓ 当（Tier-0 命中 < 2 条）或（问题含「为什么 / 怎么 / 具体 / 复现」语义）时
+下探 Tier-1：top-K（K=8，每条 ≤ L1 = 140 字符）
+  ↓ 当（需要引用 / 行号 / 复现命令 / 判定"原文怎么说"）时
+下探 Tier-2：取该条的命中块（≤ B2 = 2400 字符）
+```
+
+- 允许**升层**（下层命中不足→回上层重选），**禁止**一次性三层全灌；
+- 阈值（2 条 / 8 条 / 140 字符）为初值，由 E1/E3 校准。
+
+---
+
+# 第六部分 · 不变量（违反即回归）
+
+- **I1** Tier-0 常驻且 ≤ `B0`；**I2** Tier-1 每条 ≤ `L1`、条数 ≤ `K`；**I3** Tier-2 按块且 ≤ `B2`；
+- **I4** 每层条目必须带 `layer` + `status`；
+- **I5**【**2026-09-19 R4-A 修正**】非 `current` 的条目在**检索侧「返回但标记」**、**注入侧「继续过滤」**；
+  > **修正依据（用户两次裁定）**：
+  > ① 「**返回但标记是正确的**」——作废条目对该 AI 是**有用信息**（「别用这条，看新的」比「查不到」更有价值）；
+  > ② **`retracted` 也不过滤**：「**并不是挡，我感觉是备注**。因为比如说你之前踩过 3 次的那个坑，
+  >    如果你不记住这个教训的话，你还会再踩。」
+  > ⇒ 原措辞「**两处都被过滤**」已作废：**检索侧改为三态一律返回 + 标记**（`isRetrievablePre`，
+  >    只对未知值 fail-closed）；**注入侧维持过滤**（`isCurrentPre`，常驻 800 token 不装过时条目）。
+  > **两处判据不同是有意为之**，不是漏改。
+  > 呈现：`superseded` ⇒ `⚠已作废（已被 mem_<32hex> 取代）`；`retracted` ⇒ `⚠已撤回（原因：<reason>；更正见 mem_<32hex>）`。
+  > **`retracted` 不是垃圾，它是教训**——这是本修正的核心。
+- **I6** 三层来自同一份快照（同一 `miv`），混版视为错误；
+- **I7** 索引未就绪 / 语义臂不可用**必须显式降级标注**（例：`[语义索引未就绪 · 已降级为词法]`），禁止静默丢弃注入。
+
+`layer` ∈ { `user` | `project` | `log` | `reflection` | `whiteboard` }；`status` ∈ { `current` | `superseded` | `retracted` }。
+
+---
+
+# 第七部分 · 施工清单与验收
+
+| # | 改动 | 文件 | 状态 |
+| --- | --- | --- | --- |
+| **C1** | 抽取层补 `layer` + `status` | `lib/l0-extract-pre.js` | ✅ **完成**（+100/−2；`classifyLayerPre`/`L0_LAYERS`/`L0_STATUSES`/`L0_DEFAULT_LAYER`；21 断言绿） |
+| **C2** | 召回返回带 `layer/status` + **检索侧过滤**（I5） | `lib/index.js` | ✅ **完成**（l0Mode 与语义臂两处；导出 `isCurrentPre`；21 断言绿；p2 回归已修复） |
+| **C4** | Tier-0 目录生成器（每条 1 行，≤ `B0`，按优先级 + 配额裁剪） | 新 `lib/tier0-catalog-pre.js` | ✅ **完成**（33 断言绿；真实语料 788 token ≤ 800；**配额已随 C5 落地**：`allocateTier0QuotaPre` 为 opt-in，关闭时逐字节保持旧行为） |
+| **C3** | 接线 `l0-index-pre.js`（L0 自己的向量索引，增量；**需显式落 layer/status 两列**） | `lib/l0-index-pre.js` + 新 `lib/l0-index-sync-pre.js` + `lib/index.js` | ✅ **完成**（模块侧显式落两列并把层/状态计入索引身份；接线经 `createL0IndexSyncPre` 的 `update({layer})` 显式传层；**按层各一份**索引文件；开关 `l0IndexEnabled` **默认开**（用户 2026-09-14 裁定）、5 分钟节流、全 fail-soft；**待宿主重启复核**） |
+| **C5** | 注入层改造：Tier-0 常驻 + 按闸门下探 + **per-layer 配额** + 降级标注（I7） | 新 `lib/tier-layer-inject-pre.js` + `lib/index.js` + `lib/context-host-pre.js` + `lib/activation-host-pre.js` | ✅ **完成**（83 断言绿 + 5 处定向变异报红；**入口更正：每轮 `<memory_system>` 块由 `renderMemoryDynamic` 产出，`injectionText` 是零引用死代码**；`index-not-ready` 由静默丢弃改为降级仍注入；**待宿主重启复核**） |
+| **C6** | 验收套件（每条能力一个**能失败**的断言） | `tests/smoke/smoke-test-three-layer-pre.mjs` | ✅ **完成**（**122 断言**：Tier-0 预算 19 / layer+status 27 / supersede 双层 14 / expand 回归 9 / 源文件损坏降级 11 / C3 接线 32 / C7 回归 10；7 处定向变异全部报红） |
+| **C7** | 注入侧可见性：块内 `Score: 0.xx (rank n/m)` + reason 串带 `intent/dense/margin`（P1-⑮） | `lib/activation-inbox-pre.js` + `lib/context-host-pre.js` + `python/worker_semantic_pre_v1.py` | ✅ **完成**（29 断言绿：分值在、降序排名、乱序必重排、预算计入、无分省略；**待宿主重启后在真实注入里复核**） |
+
+**验收判据（"真过"的定义）**：
+1. Tier-0 常驻且 ≤ `B0`，内容为"当前认知"而非原始转储；
+2. L0 列表**每条**带 `layer` + `status`；
+3. 造一条被 supersede 的记忆 → 断言它在**结果与注入**两处都不出现，但审计视图可见；
+4. 造一条命中 → 断言 `expand` 取回原文（**已通，作为回归钉子**）；
+5. **故意破坏一个源文件** → 断言检索仍返回词法命中 + 明确降级标注（不是整条失败）；
+6. 上列每条都在 `tests/smoke/` 有对应套件，且**故意改坏实现时确实会红**。
+7. **注入侧看得见相似度**（C7）：注入块每条带 `Score: 0.xx (rank n/m)`，块序按分值严格降序；分值非法整行省略（不写 NaN）；这几行的字节计入预算（不得静默超预算）。