@a9i5k4/dsh-auto-memory 2.2.6 → 2.3.0

package/README.md

@@ -53,7 +53,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="docs/USER-GUIDE.zh-CN.md">📖 User guide (settings & tuning)</a> · <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.en.md">📖 User guide (settings & tuning)</a> · <a href="docs/USER-GUIDE.zh-CN.md">📖 用户文档</a> · <a href="https://qm.qq.com/q/v7Asxn6vPa">QQ group</a>
 </p>
 
 ---
@@ -82,7 +82,7 @@ Now we push this route to its last missing piece — when the context fills, she
 | **Everything is a switch** | Welcome tour + settings page, every feature individually toggleable (incl. unattended mode) |
 | **External memory inheritance** | Memories from WorkBuddy / CodeBuddy / Claude Code / Codex are scanned, importable, per-source managed |
 | **Production-grade hygiene** | Write gate (mojibake/stutter/JSON-injection blocking) + dirty-token scanner + credentials never enter prompts |
-| **Astra-style context management (experimental)** | A filling context no longer collapses into one summary — four-part handoff notes carry work across windows, full history stays searchable, the agent retrieves on demand (off by default; enable in Settings → Automation) |
+| **Astra-style context management** | A filling context no longer collapses into one summary — four-part handoff notes carry work across windows, full history stays searchable, the agent retrieves on demand (on by default, threshold 0.75) |
 | **Model-agnostic** | No vendor lock, no tier lock: any model on DSH works out of the box — lexical 0GB floor, built-in ~130MB semantic tier, advanced 563MB |
 | **Portable memory** | Everything lives on your own disk; memories scan in from other AI tools, every entry has an evidence chain — auditable, deletable. Memory belongs to you, not to any vendor |
 
@@ -104,9 +104,9 @@ Humans use memory two ways: deliberately retracing what was done before — and,
 
 Once a person learns to ride, they never replay the tutorial — muscle memory takes over, and the skill transfers to the next road on its own. She grows that kind of memory too: after watching your corrections a few times, or doing the same kind of thing again and again, a workflow crystallizes into a skill; next time something similar shows up, the checklist attaches itself — no one reminding. What was learned deliberately becomes something done casually — her procedural memory, the part you can review, pin, and watch grow in the Memory Hub tab.
 
-### The fourth · Handoff, not compression (in progress)
+### The fourth · Handoff, not compression
 
-When the context fills, she no longer burns the whole book for a one-line summary; she writes a four-part handoff note — state, goals, dead ends and why, progress and next step — closes this window, and opens the next. The full history stays archived and searchable; details can always be looked back up. The newest of the four, and the last piece of a complete memory — see [How she hands off](#how-she-hands-off-next-major--coming-soon).
+When the context fills, she no longer burns the whole book for a one-line summary; she writes a four-part handoff note — state, goals, dead ends and why, progress and next step — closes this window, and opens the next. The full history stays archived and searchable; details can always be looked back up. The newest of the four, and the last piece of a complete memory — see [How she hands off](#how-she-hands-off).
 
 ---
 
@@ -130,7 +130,7 @@ So we built it as an open plugin: no experimental gate, no subscription tier —
 
 **One route, two arrivals: it ships with a flagship; ours walks into your machine as a plugin.**
 
-*Handoff is experimental and off by default in this release — enable via Settings → Automation → Handoff whiteboard (see [How she hands off](#how-she-hands-off-experimental--off-by-default)).*
+*Handoff is on by default — threshold 0.75, just below the host's 0.80 auto-compaction line (see [How she hands off](#how-she-hands-off)).*
 
 ---
 
@@ -144,7 +144,7 @@ Friday, you ask casually: "Why do you remember this?" She shows you: which messa
 
 **She remembers, unbidden. And if you want her to forget — that's one sentence too.**
 
-> Handoff-related scenes require Settings → Automation → Handoff whiteboard (experimental).
+> Handoff-related scenes are on by default.
 
 ---
 
@@ -173,7 +173,7 @@ Then, periodically, she looks back: `memory_consolidate` reads recent logs and d
 
 Powers are separated too: what to recall belongs to the semantic decision layer; whether and when belongs to the identity/authorization/timing governance layer — every delivery carries an evidence chain. Every page she hands over has also passed inspection: injected content is neutralized for template variables at every exit — a plain `{{baseUrl}}` in a log can no longer brick an entire turn.
 
-Ask, and she answers: natural-language questions get expanded into keywords, every memory layer is scanned, and the reply is conversational with sources cited. `memory_recall` is cross-workspace by nature — other projects' logs, notes, and conclusions are one sentence away.
+Ask, and she answers: `memory_recall` returns a layered summary list first (each memory as a ~90-character digest with id, score and match reason), fused across lexical + semantic + time arms — ask for "last week's release trouble" and the memories from that window surface first; expand any id for the full text. Replies are conversational with sources cited. `memory_recall` is cross-workspace by nature — other projects' logs, notes, and conclusions are one sentence away.
 
 The panel's Workspace tab draws all of this as a mind map: workspaces at the center, memory topics as branches, dashed lines for cross-workspace shares; draggable, zoomable, click a card for details. **Your memory has a shape for the first time.**
 
@@ -199,9 +199,9 @@ Return after more than an hour away and the memory panel opens itself — a "wel
 
 ---
 
-## How she hands off (experimental · off by default)
+## How she hands off
 
-> **Experimental**: these capabilities ship in 2.1 but are disabled by default — enable via Settings → Automation → Handoff whiteboard. The window auto-follows the active model (settings.yaml contextWindow, e.g. 1M), or set it manually.
+> Handoff is on by default — the water-level threshold sits at 0.75, just below the host's 0.80 auto-compaction line. The window auto-follows the active model (settings.yaml contextWindow, e.g. 1M), or set it manually.
 
 When the context fills, she no longer burns the whole book for a one-line summary; she writes a **four-part handoff note** — task state, goals, approaches tried and why they failed, progress and next step — closes this window, and opens the next. What didn't fit in the notes is safe too: the full history of messages and tool outputs lands in a local archive, searchable anytime — no detail dies in the fire.
 
@@ -289,7 +289,13 @@ pnpm approve-builds
 pnpm add @huggingface/transformers
 ```
 
-Restart `dsh web` — the welcome tour's semantic-engine step auto-detects readiness (SHA256 verify + inference self-test). Lexical retrieval (0GB) always works as a fallback; skipping the engine only lowers recall precision.
+Restart `dsh web` — the welcome tour's semantic-engine step auto-detects readiness (SHA256 verify + inference self-test).
+
+Three retrieval tiers, switchable in Settings → Semantic engine:/n/n- **Lexical (C1, 0GB)** — the always-on floor, BM25 over full text.
+- **Built-in semantic (C2, ~130MB)** — the default, auto-downloaded on first launch. Recall is layered (L0 summaries + rank-space fusion), so long memories no longer get truncated by the model's token limit.
+- **Advanced Python (C3, ~563MB)** — BGE-M3, for power users; install it in the same settings step and it also serves `memory_recall`, not just proactive association.
+
+Retrieval is time-aware too: ask for "last week" or "three days ago" and the matching memories rise to the top. Lexical retrieval (0GB) always works as a fallback; skipping the engine only lowers recall precision.
 
 ### AI-era installation
 
@@ -446,6 +452,9 @@ Papers were authored by the autonomous engineering agent (ZCode / GLM); all conc
 
 - Memory files are plain-text Markdown; no secrets stored unless explicitly requested.
 - `memory_recall` session search depends on the deployed session-query index; without it, only local search works.
+- Advanced Python (C3) recall requires the BGE-M3 model installed in Settings → Semantic engine (~563MB).
+- Lexical search is a full scan without an inverted index; only matters once memories number in the thousands.
+- `autoConsolidateCooldownMinutes = 0` falls back to 30 (known quirk, to be addressed).
 - Plugin-set changes require a dsh restart.
 
 ---
@@ -478,3 +487,4 @@ AI agents are credited as authors of the research papers and parts of the implem
 - GitHub: https://github.com/Aik358/dsh-auto-memory
 - npm: `@a9i5k4/dsh-auto-memory`
 - License: BSD-3-Clause
+- Changelog: [CHANGELOG.md](./CHANGELOG.md)

package/README.zh-CN.md

@@ -53,7 +53,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="docs/USER-GUIDE.zh-CN.md">📖 用户文档(设置与调优)</a> · <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="docs/USER-GUIDE.en.md">📖 User guide (EN)</a> · <a href="https://qm.qq.com/q/v7Asxn6vPa">QQ 交流群</a>
 </p>
 
 ---
@@ -82,7 +82,7 @@ dsh-auto-memory 从第一天就不信这件事只能如此。她把记忆放在
 | **一切皆开关** | 欢迎向导+设置页双重入口，每个功能独立开关（含无人值守模式） |
 | **外部记忆继承** | WorkBuddy / CodeBuddy / Claude Code / Codex 的历史记忆可扫描、导入、按源管理 |
 | **生产级卫生** | 写入门禁（乱码/复读/JSON 注入拦截）+ 脏 token 扫描 + 凭证永不进提示词 |
-| **Astra 式上下文管理（实验性）** | 上下文将满不再压成一段摘要——四段式交接笔记跨窗口续命，全量历史归档可搜，Agent 按需检索（默认关闭，设置 → 自动化开启） |
+| **Astra 式上下文管理** | 上下文将满不再压成一段摘要——四段式交接笔记跨窗口续命，全量历史归档可搜，Agent 按需检索（默认开启，阈值 0.75） |
 | **模型无关** | 不锁厂商、不锁档位：DSH 上任何模型即装即得，词法 0GB 保底、内置语义 ~130MB、进阶 563MB |
 | **记忆可携带** | 全部存在你自己的盘上；跨 AI 工具扫描导入，每条有证据链、可审计、可删除——记忆属于你，不属于任何厂商 |
 
@@ -104,9 +104,9 @@ dsh-auto-memory 从第一天就不信这件事只能如此。她把记忆放在
 
 人学会骑自行车之后，就不再回忆教学步骤——肌肉记忆接管一切，知识自然迁移到下一段路。她也在长这样的记性：多次观察到你的纠正、或反复做着同样相似的事，流程就固化成技能；下次再遇到相似的事，不用谁提醒，清单自动附上。刻意学的，变成顺手的——这是她的 procedural memory，也是「记忆中枢」页签里你能审批、能置顶、能看着她成长的那部分。
 
-### 第四件 · 交接，而不是压缩（正在进行）
+### 第四件 · 交接，而不是压缩
 
-窗口将满时，她不再把整本书烧成一句读后感，而是写下四段式交接笔记——状态、目标、走过的弯路、下一步——合上这一页，翻开下一页；完整历史归档可搜，细节随时翻回去。这是四件心血里最新的一件，也是她完整记性的最后一块拼图——全文见[「她怎么交接」](#她怎么交接下一大版本--即将上线)。
+窗口将满时，她不再把整本书烧成一句读后感，而是写下四段式交接笔记——状态、目标、走过的弯路、下一步——合上这一页，翻开下一页；完整历史归档可搜，细节随时翻回去。这是四件心血里最新的一件，也是她完整记性的最后一块拼图——全文见[「她怎么交接」](#她怎么交接)。
 
 ---
 
@@ -130,7 +130,7 @@ dsh-auto-memory 从第一天就不信这件事只能如此。她把记忆放在
 
 **同一条路线，两种抵达：它随旗舰发布，我们随插件走进你的机器。**
 
-*交接能力为实验特性，本版本默认关闭——设置 → 自动化 → 交接白板 开启（见[「她怎么交接」](#她怎么交接实验性--默认关闭)）。*
+*交接默认开启——阈值 0.75，恰好压在宿主 0.80 自动压缩线之下（见[「她怎么交接」](#她怎么交接)）。*
 
 ---
 
@@ -144,7 +144,7 @@ dsh-auto-memory 从第一天就不信这件事只能如此。她把记忆放在
 
 **她记得，不必吩咐。你若要她忘，也只是一句话。**
 
-> 交接相关情节需在设置 → 自动化 → 交接白板 开启后体验（实验性）。
+> 交接相关情节默认开启，无需手动开启。
 
 ---
 
@@ -173,7 +173,7 @@ dsh-auto-memory 从第一天就不信这件事只能如此。她把记忆放在
 
 权限也分了家：想起什么归语义决策管，该不该、什么时候归身份与时序治理管——每一次投递都有证据链。她递来的每一页还都过了安检：注入内容在全部出口中和模板变量——日志里一个普通的 `{{baseUrl}}`，再也不会卡住一整轮对话。
 
-想主动问，随时开口：自然语言提问，她自动扩展关键词扫描全部记忆层，会话式回答、逐条标注来源。`memory_recall` 天然跨工作区——别的项目的日志、笔记、结论，同样一句可达。
+想主动问，随时开口：`memory_recall` 先返回分层摘要列表（每条记忆一个约 90 字的摘要，带 id、得分、匹配原因），词法 + 语义 + 时间三臂融合排序——问「上周的发布情况」，那一周的记忆就浮到前面；展开任意 id 即可取原文。会话式回答、逐条标注来源。`memory_recall` 天然跨工作区——别的项目的日志、笔记、结论，同样一句可达。
 
 面板「工作区」页签把这一切画成一张关系图：中心是工作区，分支是记忆主题，虚线是跨区共享；可拖拽、可缩放、点卡片看详情。**你的记忆第一次有了形状。**
 
@@ -199,9 +199,9 @@ dsh-auto-memory 从第一天就不信这件事只能如此。她把记忆放在
 
 ---
 
-## 她怎么交接（实验性 · 默认关闭）
+## 她怎么交接
 
-> **实验特性**：本节能力随 2.1 上线但默认关闭——设置 → 自动化 → 交接白板 开启后生效。窗口大小自动取自当前模型（settings.yaml 的 contextWindow，如 1M），也可手动覆盖。
+> 交接默认开启——水位阈值定在 0.75，恰好压在宿主 0.80 自动压缩线之下。窗口大小自动取自当前模型（settings.yaml 的 contextWindow，如 1M），也可手动覆盖。
 
 上下文将满时，她不再把整本书烧成一句读后感，而是写下**四段式交接笔记**——任务状态、目标、已试过的方案与失败原因、进度与下一步——合上这个窗口，翻开下一个。写不进笔记的也不怕：完整的历史消息与工具输出落进本地归档，随时可搜，细节不再死在火里。
 
@@ -289,7 +289,15 @@ pnpm approve-builds
 pnpm add @huggingface/transformers
 ```
 
-装完重启 `dsh web`，向导的语义引擎步会自动检测到就绪（SHA256 校验 + 推理自检）。词法检索 0GB 永远兜底，不装也能用（仅召回精度较低）。
+装完重启 `dsh web`，向导的语义引擎步会自动检测到就绪（SHA256 校验 + 推理自检）。
+
+三档检索引擎，在 设置 → 自动记忆引擎 里切换：
+
+- **词法（C1，0GB）** —— 永远在线的保底，对全文做 BM25。
+- **内置语义（C2，约 130MB）** —— 默认档，首次启动自动下载；检索是分层的（L0 摘要 + rank-space 融合），长记忆不再因模型 token 上限被截断。
+- **高级 Python（C3，约 563MB）** —— BGE-M3，面向深度用户；在同一设置步里安装后，`memory_recall` 同样会用到它（不只是主动联想）。
+
+检索还带时间感知：问「上周」或「三天前」，命中的记忆会浮到前面。词法检索 0GB 永远兜底，不装也能用（仅召回精度较低）。
 
 ### AI 时代安装法
 
@@ -446,6 +454,9 @@ DeepSeek Harness (Node, 127.0.0.1:3080)
 
 - 记忆文件为纯文本 Markdown；除非明确要求，不存储密钥
 - `memory_recall` 会话搜索依赖已部署的 session-query 索引，缺失时仅本地检索可用
+- 高级 Python（C3）召回需先在 设置 → 自动记忆引擎 安装 BGE-M3 模型（约 563MB）
+- 词法检索为全量扫描、无倒排索引，记忆上千条后才需优化
+- `autoConsolidateCooldownMinutes = 0` 会回退为 30（已知瑕疵，后续版本处理）
 - 插件增减需要重启 dsh 生效
 
 ---
@@ -478,3 +489,4 @@ AI Agent 作为研究论文作者与部分实现作者署名，全程在人类
 - GitHub: https://github.com/Aik358/dsh-auto-memory
 - npm: `@a9i5k4/dsh-auto-memory`
 - License: BSD-3-Clause
+- 更新日志：[CHANGELOG.md](./CHANGELOG.md)

package/docs/CONTINUITY-FLOW.md

@@ -0,0 +1,222 @@
+# 接续流程轴（Continuity Flow）
+
+> 写于 2026-09-08，基于 **v2.2.6** 源码（含本次 G1/G3 改动）。
+> 本文是**纵向时间轴**视角；[M-CM7-HANDOFF-LAYERED-RETRIEVAL.md](M-CM7-HANDOFF-LAYERED-RETRIEVAL.md) 是**横向分层**视角。两者互补。
+> 目标：把从"水位上涨"到"新窗口推进"的全链路，逐阶段列出实现、参数、失败模式与不变量，作为后续改造与验收的共同基准。
+
+---
+
+## 0. 流程总览
+
+| 阶段 | 名称 | 触发 | 实现入口 | 产物 |
+|---|---|---|---|---|
+| **S0** | 常态水位监测 | 每个 turn 的 pre-step | `checkWaterLevelAtStep()` `:1871` | 水位记录（`ratio` / `tokens` / `window`） |
+| **S1** | 阈值判定与确认 | `ratio ≥ 0.75` 且轮次边界 | `:1892` | 确认卡 / 宿主兜底倒计时 |
+| **S2** | 刷新仪式 | 确认通过或兜底到期 | `refreshRitualPrompt()` `:2049` | PLAN.md 重写 + 新账本 |
+| **S3** | 材料组装 | 仪式完成或超时 | `buildContinueCarry()` `:2126` | `carryText` + 转写包 |
+| **S4** | 建新会话 | 材料就绪 | `sessionController.create` | 新 sessionId + 工作区绑定 |
+| **S5** | 状态沿用 | 会话创建后 | `selectModel` | provider / model / reasoningEffort |
+| **S6** | 首轮注入 | 新会话首条 | `carryText` 作为 prompt | 新窗口上下文 |
+| **S7** | 按需取回 | 推进中 | `memory_recall_pre` / `read` | 细节补充 |
+
+---
+
+## 1. 逐阶段详解
+
+### S0 · 常态水位监测
+
+| 项 | 值 |
+|---|---|
+| 实现 | `checkWaterLevelAtStep(agent, minGapMs = 5000)` `:1871` |
+| 节流 | **5 秒**（`minGapMs = 5000`） |
+| 测量点 | **pre-step**（`c4912f4` 修正） |
+| 窗口来源 | 按**会话自身的模型**解析（`cc21f7f`），非默认模型；失败回退 `131072`，`waterLevelWindowTokens` 手动覆盖优先，60s 缓存 |
+| 计量 | 官方 token-meter 公式（4 字符 ≈ 1 token + 每消息 4） |
+| 输出 | `{ratio, tokens, window, source, model, threshold, at, live}` |
+| 会话粒度 | per-session（`a257277` / `4f97af0`，session id 规范化带 `session-` 前缀） |
+
+**为什么测量点必须是 pre-step**：官方自动压缩也在 pre-step 发生；若插件在 turn-stopping 才测，会被官方抢先（`c4912f4` 的核心修正）。
+
+**失败模式**：窗口解析失败 → 回退 131072（水位虚高，可能误触发）；计量异常 → `ratio` 可能 >1（`482201f` 已改为上报真实比例，不再 clamp 到 150%）。
+
+### S1 · 阈值判定与确认
+
+| 参数 | 默认值 | 位置 |
+|---|---|---|
+| `waterLevelThreshold` | **0.75** | `:229` |
+| `autoContinueThreshold` | **0.75** | `:237` |
+| `autoContinueConfirmSeconds` | **35** | `:239` |
+| `autoContinueCooldownMinutes` | **30** | `:245` |
+| `autoContinueEnabled` | `true` | `:235` |
+
+**触发条件**（`:1892-1893`）：
+1. `autoContinueEnabled !== false`
+2. `handoffEnabled !== false`
+3. `wl.ratio >= autoContinueThreshold`（0.75）
+4. **harness 权威 `running == false`**——轮次边界判定，取代旧"两轮水位持平"启发式
+
+**0.75 的设计理由**：官方自动压缩阈值为 **80%**，0.75 留出余量抢在其之前（commit `ca75808`）。
+
+**两条执行路径**：
+- **浏览器路径**：轮询 `auto-continue-state`（`:6533`）显示确认卡，用户 35 秒内同意/拒绝。
+- **宿主兜底路径**（`0107d73`，M-CM6-C）：浏览器被后台节流或关闭时，宿主侧心跳倒计时到期自动执行——建新会话不再依赖浏览器页面。
+
+**失败模式**：冷却期内（30 分钟）不重复触发；确认超时按配置处理；host 未暴露 token 计数时退化为启发式估计。
+
+### S2 · 刷新仪式（refreshRitual）
+
+| 参数 | 默认值 | 位置 |
+|---|---|---|
+| `autoContinueRefreshRitual` | `true` | `:241` |
+| `autoContinueRefreshTimeoutSeconds` | **90** | `:243` |
+
+**执行方式**：`client` 通过 `remote.session.prompt` 把指令发回**旧会话**（`:2047`）。
+
+**旧 AI 被要求做的事**（`:2050-2054`，本轮内只做这两件）：
+1. `memory_note_pre(kind=plan, …)` 重写 PLAN.md（项目白板最新全貌）
+2. `memory_note_pre(kind=handoff, …)` 写一篇四段式账本
+   - 四段：`## 任务状态` / `## 目标` / `## 已试方案与失败原因` / `## 进度与下一步`
+   - 每段 ≤5 行；下一步必须是**可直接执行的第一步**，带文件路径或命令
+3. 完成后只回复「已刷新」
+
+**超时**：90 秒未完成 → **fail-soft**，用现有材料继续接续。
+
+**已知缺陷**（见 M-CM7 §3.4）：
+- 账本标题重复（追加写入时重复写 `# 交接账本` 标题，实测 6 个中 3 个）
+- 段内异质：「已试方案与失败原因」实际混入**成功解法**；「进度与下一步」混入已完成项与元指令
+- 白板退化为日志，无老化
+
+### S3 · 材料组装（buildContinueCarry）
+
+**实现**：`index.js:2126-2192`。降级链：工作区白板/账本 → 全局最近账本（`findLatestGlobalHandoff`）→ 无材料则 `ok:false`。
+
+**四层材料**（`:2159`）：
+
+| 层 | 内容 | 截断 |
+|---|---|---|
+| 第0层 | 指令 + 白板 PLAN.md | `slice(0, 3000)` |
+| 第1层 | 交接账本（四段式，最新） | `slice(0, 8000)` |
+| 第2层 | 近期线程（最近 20 条） | 单条上限 700 字，保留角色与工具标记 |
+| 第3层 | 完整转写（按需 read） | 不内联，给路径 + 指引 |
+
+**总预算**：`carryText.slice(0, 18000)`（`:2183`）。
+
+**旧会话上下文包**（`buildPrevSessionPack()` `:2062`，M-CM6-B v2）：
+- 定位 `~/.dsh/sessions/<ws>/<sid>/session.jsonl[.zstd]`
+- **多帧 zstd 全量解压**（`zstdDecodeAllFrames`，单帧 API 只解 header）
+- 提取 `cwd` / `agentPreset` / `provider` / `model` / `reasoningEffort`（取自 `request/header` 的 `data.header.config`，与官方投影同源；`request/context` 仅回退）
+- 转写落盘 `handoff/prev-session-*.md`
+- **fail-soft**：任何环节失败返回部分字段
+
+**新鲜度标注**：白板与账本 mtime 比较，白板更旧时提示「以账本为准」（`:2152`）。
+
+**接续序号**：统计 `handoff/` 中已有 `prev-session-*.md` 数量 +1（`:2179`）。
+
+### S4 · 建新会话
+
+- `sessionController.create`，传 **`workspaceId`**（`resolveWorkspaceIdForSession`，`:2156`）——官方只有 `workspaceId` 分支会 `attachSession`；这是 `b99576b` 的关键修正
+- 会话标题编号：`接续#N · {wsBase}`（`bffe105`），便于区分新旧会话
+
+**已知坑**（`f475321`）：`session.create` 返回**裸 SessionId 字符串**而非对象，需健壮解析（string / sessionId / id / value / `{ok,value}`）。
+
+### S5 · 状态沿用
+
+- `selectModel` 恢复 `provider` / `model` / `reasoningEffort`（`b99576b`）
+- `create` 传 `agentPreset`（`bffe105`）
+- 前置条件：`session/prompt` 需带 `clientTimeZone`（IANA，经 `Intl` 获取），否则 host 拒绝（`6a94794`）
+- 插件全局配置（无人值守 / 水位 / 交接）自动继承
+
+**注意**：`agentPreset` 有 `code → ptc` 改名的历史包袱，旧会话需用户级兼容预设（`:2174` 已提示）。
+
+### S6 · 首轮注入
+
+`carryText` 作为新会话首条 prompt。
+
+**指令文案（本次 G1 改动，`:2158`）**：
+
+| | 文案 |
+|---|---|
+| 改前 | 请**先读完**下面的交接材料恢复上下文，然后直接继续推进… |
+| 改后 | **材料已分层，请按需取用而非通读**：先看第0层白板建立全局图景，再视需要看第1层账本（含已试方案与失败原因）与第2层近期线程；**第3层完整转写仅在前三层不足以推进时才 read**。恢复上下文后直接继续推进… |
+
+**第3层指引（本次 G3 改动，`:2168`）**：
+
+| | 文案 |
+|---|---|
+| 改前 | **接续前先用 read 工具读取该转写文件**，以完全理解旧会话的讨论、结论与未竟事项 |
+| 改后 | 完整转写已归档，**不必在接续前通读**：仅在第0-2层不足以推进时再 read；优先用 `memory_recall_pre(scope='sessions', query='关键词')` 定位片段，避免整篇读入 |
+
+**改动意图**：分层此前被"全读"指令架空——模型被要求通读就不会选择性取用。改后分层才真正生效。
+
+### S7 · 按需取回
+
+- `memory_recall_pre(scope='sessions' | 'handoff' | 'all', query=…)`：轻量直返，带 provenance 与预算截断
+- `read`：完整转写（仅在前述不足时）
+- `memory_recall_pre` 亦可跨 WorkBuddy / CodeBuddy / Claude Code / Codex / ZCode / Kimi Code / TRAE 检索
+
+---
+
+## 2. 关键不变量（Invariants）
+
+改造接续通路时，以下五条**不得破坏**：
+
+| # | 不变量 | 依据 |
+|---|---|---|
+| **I1** | **前缀缓存字节级稳定**：只动动态快照层，静态纪律层字节不碰 | 项目核心约束 |
+| **I2** | **不替 host 决定压缩**：只在 host 允许时点助产，开新窗是 host 领地 | M-CM-PLAN §5，与 Codex `new_context` 同边界 |
+| **I3** | **凭证永不进提示词**：所有写入过 `sanitizeForWrite`，注入前 `stripSensitiveSections` | README 承诺 |
+| **I4** | **绝不阻塞接续**：任何新增环节必须 fail-soft，缺失即回退 | S2/S3 均已有降级链 |
+| **I5** | **水位测量在 pre-step**：不得退回 turn-stopping，否则被官方压缩抢跑 | `c4912f4` |
+
+**对 M-CM7 的含义**：锚点 sidecar（G2′）若在 S2 同轮产出，不违反 I4（缺失回退四层平铺）；若改为异步产出，则需额外确认 S3 组装时不会因等待而阻塞。
+
+---
+
+## 3. 时序与预算约束
+
+| 约束 | 值 | 说明 |
+|---|---|---|
+| 水位阈值 | 0.75 | 官方压缩 0.80，留 0.05 余量 |
+| 确认倒计时 | 35 s | 无人操作 = 挂机 → 自动接续兜底 |
+| 刷新仪式超时 | 90 s | 超时用现有材料继续 |
+| 接续冷却 | 30 min | 防止连续触发 |
+| 水位检查节流 | 5 s | pre-step 不重复测 |
+| 材料总预算 | 18000 字符 | `carryText` |
+
+**关键时序链**：`水位 ≥0.75（pre-step） → 确认/兜底（≤35s） → 刷新仪式（≤90s） → 组装 → 建会话`。
+**必须整体早于官方 80% 压缩点**，否则助产失效——这是 0.75 而非 0.79 的原因。
+
+---
+
+## 4. 已知缺陷与改造落点
+
+| # | 缺陷 | 阶段 | 改造 | 状态 |
+|---|---|---|---|---|
+| 1 | 指令要求"先读完"，分层被架空 | S6 | G1 | ✅ 已改 |
+| 2 | "接续前必须先 read 转写"，强制全量读 | S6 | G3 | ✅ 已改 |
+| 3 | 各层与总预算为**位置截断**，高权重段可能被整体截掉 | S3 | G4 / G5 | 待做 |
+| 4 | 无锚点索引，模型不知有哪些可下钻项 | S3/S6 | G2′ | 待做（纯解析方案已作废） |
+| 5 | 账本**标题重复** | S2 | G2″ | 待做 |
+| 6 | 白板退化为日志，无老化 | S2 | G2″ | 待做 |
+| 7 | 段内异质，按段加权必错配 | S2/S3 | G2′（条目级） | 待做 |
+| 8 | 纯函数核心未抽出，缺 fixture 锁定 | S3 | G6 | 待做 |
+
+---
+
+## 5. 验收基线（本次改动后）
+
+| 检查 | 结果 |
+|---|---|
+| `node --check lib/index.js` | ✅ 通过 |
+| `smoke-test-continue-chain-pre` | ✅ **58 passed, 0 failed** |
+| `smoke-test-handoff-pre` | ✅ **pass=51 fail=0** |
+| BOM | 无 |
+| 行尾 | CRLF 保持 |
+
+**待补**：行为级断言——G1/G3 属文案改动，现有 smoke 无文案断言（已确认无依赖），建议后续为"carryText 不含强制全读措辞"补一条守卫断言，防止回退。
+
+---
+
+## 6. 一句话
+
+**这条流程轴的本质是：在 host 划定的压缩边界之前（0.75 < 0.80），用一次受控的"写—组装—注入"把上下文搬过窗口边界；分层是搬运的形态，而"按需取用"才是搬运能否省钱的关键。**