@a9i5k4/dsh-auto-memory 2.2.2 → 2.2.3

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

@@ -0,0 +1,100 @@
+# HY4 移交：欢迎向导 Logo 动态化 + 排版优化 + CHANGELOG 开场序列
+
+> 移交时间：2026-08-31 · 分支 preview · 最新提交 b18ec38 · 回归 38/38
+> 接收方：HY4（无图像输出能力，全部用 HTML/CSS/JS 在 lib/client.js 里实现）
+> 设计美学已定稿，**不要改风格方向**，只做实现与打磨。
+
+## 0. 目标（三件事）
+
+1. **向导 Logo 动态化**：把首启欢迎向导顶部的"emoji+圆圈"占位，升级为**纯 CSS 绘制的三层磨砂玻璃板堆叠 Logo**（动态 UI），并给每个向导步骤做差异化的动画变体。
+2. **向导排版打磨**：标题/正文/开关卡/按钮的层级、间距、字重、对齐整体优化。
+3. **CHANGELOG 开场序列**：更新弹窗打开时先播放一段 Logo 动画——**出现（组装）→ 展开 → 消散 → CHANGELOG 内容浮现**——然后才显示更新文字。
+
+## 1. 视觉基准（必读）
+
+**参考图（你可以直接用 Read 工具查看）**：
+`C:\Users\JH Z\.zcode\cli\image-cache\sess_0b2cadc8-5721-45df-aa42-141f25c2f627\image-29f869ddd0141834297e324a8c0b2176.png`
+
+若读不到，文字描述如下——这是定稿美学，所有实现以它为准：
+
+- **主体**：三片圆角方形磨砂玻璃板，等距垂直堆叠（像三层托盘），等轴测视角（绕 Z 轴约 45°+俯视约 55°，即 `rotateX(~55deg) rotateZ(~45deg)` 的观感）
+- **玻璃质感**：近无色的乳白磨砂玻璃，半透明（能微透背后），**边缘可见的厚度**（顶边一条亮白 Fresnel 边光，底边稍暗形成厚度感），圆角很大（约为边长 22%），边光干净但不发光——是"厚亚克力板的自然白边"，绝无霓虹描边
+- **背后**：三四团**失焦的蓝紫 bokeh 光斑**（#4D6BFE 蓝、#9B7EFF 紫，大的柔圆，blur 很重），左上/右/下各一团——透过玻璃能隐约看到糊掉的光斑（这是"磨砂"成立的关键）
+- **背景**：深藏青 #0B0F1A（在向导里即卡片深色底），中央微亮
+- **整体**：安静、高级、有触感；高光是**糊开的宽光**（matte satin），不是镜面锐线
+
+色板令牌（向导 CSS 已有，直接用）：`--dam-accent #2456C4→#7EA4FF`、面板深底 `rgba(24,26,32,.9)`、白色高光系 `rgba(255,255,255,.x)`。
+
+## 2. 现状代码定位（全部在 lib/client.js）
+
+- **向导步骤数据**：`var TOUR_STEPS = [`（约 2388 行起）——每步 `{ core: '🫧' /*emoji*/, kicker, title, text, toggles?/dl?/externalScan?/final? }`
+- **向导渲染**：`DialogHost()` 内 `dialogState.kind === 'welcomeTour'` 分支；orb 结构：
+  - `[data-dam-tour-orb-wrap]`（150×150, perspective）→ `[data-dam-tour-orb]`（形变圆球,要被替换）→ `[data-dam-tour-orb-core]`（emoji,要被替换/重定位）
+- **向导 CSS**：顶部 `var CSS = [` 数组中 `[data-dam-tour-*]` 段（搜索 `dam-tour-orb`）；已有可复用动画：`@property --dam-orb-a`（conic 高光扫过角度）、`dam-orb-float`（浮沉）、`dam-tour-swap`（切页滑入）
+- **更新弹窗**：DialogHost 内 `dialogState.kind === 'update'` 分支（CHANGELOG 卡片）；小卡样式变量 `overlay/box/head/sub` 同函数内
+- **引擎步/外部扫描/开关**：已实现且实测通过，**逻辑不要动**，只可调样式
+
+## 3. 任务 A：CSS 三层玻璃板 Logo（核心交付）
+
+在 orb 容器里用纯 CSS 绘制（无图片、无 emoji 主体）：
+
+**结构建议**（可自行优化，保持 `data-dam-tour-orb-wrap` 外层标签与 150×150 尺寸）：
+```
+orb-wrap（perspective 容器,背景放射微光）
+  ├─ bokeh ×3-4（position:absolute, radial-gradient 圆斑, filter:blur(18px), 各自缓慢漂移动画）
+  └─ slab-stage（transform-style:preserve-3d; rotateX(55deg) rotateZ(45deg)）
+       ├─ slab ×3（86×86 圆角方块,各 translateZ 间距 ~22px）
+```
+
+**每片 slab 的质感要点**（对照参考图逐条）：
+- 主体：`linear-gradient(135deg, rgba(255,255,255,.16), rgba(255,255,255,.05))` + 大圆角（radius ~26%）+ `backdrop-filter: blur(6px)`（透出 bokeh 的关键）
+- 厚度：`::before` 同形状在 Z 轴负方向偏移 6-8px（或多层 box-shadow 叠出侧壁），颜色比顶面暗一档的乳白
+- Fresnel 边光：`border: 1.5px solid rgba(255,255,255,.55)` + `inset 0 1px 0 rgba(255,255,255,.65)`（顶缘最亮）
+- 磨砂内部：`inset 0 0 24px rgba(255,255,255,.14)`（奶白雾感）；**严禁** box-shadow 用饱和蓝紫发光
+- 投影：整 stage 下方 `0 24px 48px rgba(4,8,20,.45)` 柔影
+
+**动画**：
+- **入场**（每次切步触发，替换现有 `dam-tour-swap` 对 body 的作用——orb 保持常驻,只做轻微重排）：三片板自上而下依次落下（translateY(-26px)+scale(.85)+opacity 0 → 归位），间隔 160ms，`cubic-bezier(.2,.9,.3,1.15)` 回弹；bokeh 随后 0.4s 淡入
+- **循环**：整 stage 缓慢浮沉 ±5px（4.5s ease-in-out infinite，三片相位微错开产生"呼吸层叠"）；复用 conic 高光扫过（把现有 `--dam-orb-a` 机制搬到最上片 slab 的 `::after`）
+- **每步差异化**（简单方案即可）：`TOUR_STEPS[].core` 的 emoji 不再当主体，改为**小的玻璃徽章**吸附在堆叠体右上/中央（像 app 角标），徽章随步切换 + 一次 pop 入场；或让各步的 bokeh 色相/数量微变——两种都行，你选一种做统一
+- **降级**：`@media (prefers-reduced-motion: reduce)` 全部动画静止只保留静态构图；emoji 兜底（CSS 不可用时）不需要——CSS 必然可用
+
+## 4. 任务 B：向导排版打磨（审美权限在你，约束如下）
+
+- 目标：标题-正文字阶更清晰（title 21px→可调）、开关卡与正文间距、kicker 字距、按钮行呼吸感
+- 保持：整体 620px 中央悬浮窗、液态玻璃语言、`data-dam-*` 属性名（校验/测试引用）、中文两行内不换行破相
+- 逐屏检查：开关步（最多 2 卡）、外部扫描步（7 卡滚动,注意 max-height 与滚动条样式）、完成步（徽章+五行指引,注意左对齐块与居中标题的过渡）
+
+## 5. 任务 C：CHANGELOG 开场序列
+
+更新弹窗（`kind === 'update'`）打开时的四段动画，全部在现有小卡内实现（可在卡顶部临时扩一个 ~150px 的舞台区）：
+
+1. **出现/组装**（0-0.7s）：任务 A 的三层玻璃板 Logo 缩小版在此依次落下组装
+2. **展开**（0.7-1.1s）：三片板短暂散开（间距拉大 + 轻微旋转）再收回——"揭示"感
+3. **消散**（1.1-1.5s）：整体 blur+scale(1.06)+opacity → 0，舞台区高度收合
+4. **内容浮现**（1.4s 起）：CHANGELOG 标题与文字淡入上移
+
+实现要求：
+- 用 CSS animation-delay 编排单次时间线；**点击任意处立即跳到内容**（加 `data-skip` 类终止动画）；总时长 ≤1.8s
+- 内容 DOM 始终在（无障碍/防闪烁），只是视觉上延迟显示
+- 首次（`first` kind）与 `notice` 卡**不加**此序列，只有 update 卡要
+- 性能：动画元素控制在 ~10 个节点内；结束后移除 will-change
+
+## 6. 红线（违反任何一条都算失败）
+
+1. `lib/client.js` 之外的文件一律不动（除非你发现必要,先在 PR 说明）
+2. 不改任何后端/配置键/`data-dam-*` 现有属性名与函数名（`TOUR_STEPS` 各字段 key 保留,`core` 字段可改语义但保留字段）
+3. 不动：fv2 决策核、M5/M6 validator、后端路由、38 个 smoke-test*.mjs 的期望
+4. 每?完成一步：`node --check lib/client.js` 必须过；最终跑全量 `for t in smoke-test*.mjs; do node "$t" >/dev/null 2>&1 || echo FAIL $t; done` 必须 0 FAIL（38 套件,偶尔 m53 串行抖动,单跑复确认即可）
+5. commit 已授权（用户明确要求），push 仍需确认；小步提交（A/B/C 各一个 commit）
+6. 3080 由用户自己管理——**不要启停 3080**，改完代码告诉用户刷新页面即可（client bundle 按请求读盘）
+7. 你的环境没有真实用户的 ~/.dsh 数据依赖——不要读写 `~/.dsh`（测试套件自己隔离）
+
+## 7. 验收标准（用户视角）
+
+- 打开欢迎向导：顶部是会动的三层玻璃板 Logo（不是 emoji+圆圈），切步时板层重排+徽章切换,观感贴近参考图
+- 整个向导排版比现在更精致（对照实机截图自查）
+- 触发更新弹窗：先看到 Logo 组装→展开→消散,然后 CHANGELOG 浮现,点击可跳过
+- 38/38 回归全绿,语法检查通过,2-3 个 commit 落库
+
+——以上。完成后向用户汇报改了哪些区块与动画时序即可。

package/docs/ISSUE-REPLY-UNATTENDED.md

@@ -0,0 +1,31 @@
+# Issue 反馈（roadmap-aligned，2026-08-26）
+
+感谢你详细的 issue——这正是我们 roadmap 里无人值守场景的核心诉求。以下是已落地/计划的对齐：
+
+## 已实现（本次发布）
+
+**1. 独立「无人值守模式」开关（默认关）**
+设置 → 自动化 → 无人值守模式。开启后：
+- 不再注入欢迎回来指令、行为指令、暂离/回归提示、日历提醒
+- 只注入纯事实记忆（最近日志/反思/笔记摘要）
+- 这解决了你观察到的「每轮回复以 Welcome back! 开头」——该指令完全剥离
+
+**2. 工作区锁定（修复路径漂移）**
+无人值守模式下，插件锁定当前工作区：即使子代理/工具改变了 cwd，也沿用已锁定路径，不再「context flips to unrelated path」。你的 ToolCallError 循环（edit requires reading first）正是由此消除。
+
+**3. 自动检测（roadmap 承诺的 auto-detection entry）**
+新增「夜间/非工作时间自动托管」开关（默认关）：本地时间处于非工作时间窗（默认 22:00-08:00，可配置）时自动进入无人值守模式；手动开关优先。自动托管任务运行时也会触发（钩子已预留）。
+
+**4. 注入预算可调 + 已调低默认**
+记忆快照注入预算（`injectBudgetChars`）默认从 2400 → 1600 字符，设置页可调。快照「变化才追加」由框架去重保证，不每轮膨胀。
+
+## 路线图（后续发布）
+
+- **新记忆插入机制**：从「整块注入」改为「可召回」——记忆进入上下文即使模型不主动调用；该机制自带开关（避免影响托管运行的注意力）。
+- **独立开关持续扩展**：所有非核心功能（问候/日历/暂离/拟人化）将逐个拆成独立 toggle，而非一揽子。
+
+## 说明
+- 无人值守模式是**纯事实注入**：只保留对任务有用的记忆内容，剔除所有社交性/行为性指令。
+- 与你的「托管模式」判断可联动：模型侧判断托管时，可驱动该开关（钩子已预留）。
+
+如果你还有具体场景（如特定时间窗、托管任务触发条件），欢迎补充——我们会按此迭代。

package/docs/K3-LANDING-HANDOFF.md

@@ -0,0 +1,76 @@
+# K3 交接：宣传网页制作（v0.1.30 创新点+全部素材）
+
+> 2026-09-01 · 交付方：K3（前端能力最强，用户亲自督导，质量要求最高）
+> 产物：`docs/landing/index.html`（单文件、零依赖、响应式、中英双语切换）
+> **本文件自包含**——读完这一份 + 两份引用文档即可开工，无需追问上下文。
+
+## 0. 项目一句话与灵魂（写进 Hero，不可弱化）
+
+dsh-auto-memory 是 DeepSeek Harness Web GUI 的**主动联想记忆插件**。
+
+**人无我有的灵魂**（源自 docs/proactive-associative-memory-system-map.html 开篇）：
+「让记忆在**模型没有主动调用**时，也能被当前情境唤回。」
+
+市面所有记忆方案（MCP memory、MemGPT 类）都依赖模型"记得去查"——调工具、发请求，忘了调记忆就等于不存在。本插件是 **Host 侧主动联想中间件**：持续观察对话情境与运行事件，相关记忆在模型开口之前就被检索、决策、并经固定边界注入下一环节。
+
+三个配套的独有工程点：
+1. **固定边界注入**：已发出的请求不可原地改写，注入只影响下一 step/turn——DeepSeek 前缀缓存永不失效（字节级稳定提示词）
+2. **证据闭环**：open/read≠citation；每次激活决策带完整证据链，「唤起回顾」页可复核打分（A/P/S/H/E）
+3. **权限分立**：语义层（何时想起什么）与治理层（身份/授权/时序/投递）分立，记忆治理永远在 JS 权威层
+
+**文案主基调**：不直白说"人无我有"，用"记忆不靠调用，自己被唤回""不用吩咐，她自己记得"这类表达体现。
+
+## 1. 视觉方向
+
+- **美术与创意完全由 K3 自由发挥**（角色/配色/版式/动效/叙事全不设限）——用户明确放权
+- 需要参考的是架构图 `docs/proactive-associative-memory-system-map.html` 的**内容本身**：模块划分、数据流（观察→检索决策→固定边界投递→证据闭环）、三层记忆/技能渐进激活/治理如何协作——网页把同样的故事讲出来，视觉形式由 K3 定
+- 产品既有观感（可感受，不必模仿）：深色液态玻璃质感、蓝紫主色 #4D6BFE→#9B7EFF
+- 角色资产：`docs/banner.jpg` 有官方拟人形象（蓝发蓝眼动漫少女，水彩风）；banner 系列生图 prompt 在 `artifacts/logo/BANNER-SERIES-PROMPTS.md`（如需新图可参考）
+
+## 2. 页面结构大纲（12 节功能全覆盖，禁止省略）
+
+详细大纲在 `docs/LANDING-OUTLINE.md`。速记版：
+
+1. **Hero**：主标题+灵魂句（"不用吩咐，她自己记得"）+安装 CTA（`pnpm add @a9i5k4/dsh-auto-memory`，点击复制）+GitHub 链接
+2. **数据流一图流**：观察→检索决策→固定边界投递→证据闭环（源自架构图叙事）
+3. **功能全景**（每节都要有，配截图）：
+   - 主动联想（零指令，首节）
+   - 自动沉淀（每轮子代理静默写日志，闲聊跳过，预算+自动压缩）
+   - 欢迎向导 v0.1.30（分步介绍+每项当场开关+引擎检测/下载/自检内联+外部来源扫描；tour-*.png×4）
+   - 唤起与技能固化（observed→candidate→validated→active 晋升，90 天归档+置顶；回顾打分）
+   - 无人值守模式（手动+夜间自动托管 22:00-08:00；零寒暄零行为指令，源自 Issue#10）
+   - AI 问候与每日反思（时段问候/暂离 >1h 欢迎回来/每日结构化反思）
+   - 智能检索+工作区全景（跨层关键词检索标注来源；工作区关系图）
+   - 日历（AI 从对话抓 deadline 自动入历，未完成注入后续会话提醒；四象限+日时间轴）
+   - 外部记忆继承（WorkBuddy/CodeBuddy/Claude Code/Codex 扫描导入，纯路径指针不复制）
+   - 记忆卫生（写入门禁：GBK 乱码 34 特征/复读/重复行/外部画像 JSON/base64 拦截；调试中心脏 token 扫描；凭证永不进提示词）
+   - 记忆生命周期（30 天蒸馏：只提炼长期价值进笔记，原文归档 archive；**边界**：procedure skills 与两级笔记不在蒸馏范围，归档原文不在常规检索扫描内；memory_consolidate 发散固化）
+   - 工程内核（零运行时依赖/前缀缓存友好/限额 AI ≤8 次/天/集中式存储/可选 Python sidecar 失败回退词法）
+4. **界面速览**：7 张截图网格（docs/screenshots/panel-overview.png / panel-hub.png / panel-refine.png / tour-welcome.png / tour-toggles.png / tour-external.png / tour-core.png），相对路径引用
+5. **快速开始**：三步安装+AI 时代安装法（可复制文本框）+更新方式
+6. **配置示例**：`~/.dsh/dsh-auto-memory.json` 关键键（unattendedMode/unattendedAuto/unattendedAutoHours/memoryHubEnabled/externalSources 等）
+7. **社区致谢**：@ProperSAMA（PR#12 面板可读性+防遮挡）、@nkh0472（Issue#10 无人值守反馈）
+8. **页脚**：GitHub / npm `@a9i5k4/dsh-auto-memory` / BSD-3-Clause / 隐私句「记忆存在你自己的机器上」
+
+## 3. v0.1.30 大更新（CHANGELOG 已定稿，可引用其表述）
+
+- ★ 欢迎向导（功能开关+引擎内联）
+- ★ Office/Fluent 式液态玻璃应用图标族（每步一彩一动效）
+- ★ CHANGELOG 开场动画（Logo 组装→展开→消散→内容浮现）
+- ★ 无人值守就绪
+- PR#12 双修复（@ProperSAMA）、弹窗关闭修复、唤起回顾时间线
+
+## 4. 交付要求
+
+- 单 HTML 文件、零外部依赖（字体/库全内联或不用）、桌面+移动响应式
+- 中英双语切换（右上角切换器，默认中文）
+- 截图相对路径 `../screenshots/*.png`（产物在 docs/landing/ 下）
+- 不改仓库其他文件；完成后用浏览器截图桌面+移动两种宽度自检
+- 完成后汇报：改动文件、设计要点、自检截图
+
+## 5. 用户偏好备忘
+
+- 语言：中文交流
+- 审美要求高（"价格不菲，给我做好了"）——值得花功夫打磨动效与排版细节
+- 用户欣赏：架构图 HTML 的信息设计水准；向导的玻璃图标族已获认可（"改得还可以"）
+- 避免：emoji 堆砌（README 已清零）；营销空话；省略功能

package/docs/LANDING-OUTLINE.md

@@ -0,0 +1,85 @@
+# dsh-auto-memory 宣传网页大纲（LANDING-OUTLINE）
+
+> 交付方：混元 4 · 产物：`docs/landing/index.html`（单文件、零依赖、响应式、中英双语切换）
+> **美术与创意完全由你自由发挥**——角色、配色、版式、动效、叙事方式都不设限。
+> 需要参考的是 `docs/proactive-associative-memory-system-map.html` 的**内容本身**：
+> 它把插件划分成哪些模块、数据怎么流动、三层记忆/检索/投递/治理怎么协作——
+> 网页的叙事结构应讲出同样的故事，但用什么视觉形式讲，由你决定。
+> 内容素材：README.md / README.zh-CN.md（双语全文）、docs/screenshots/（7 张实机图）。
+> 铁律：覆盖本大纲全部功能点；不省略、不虚增；截图相对路径引用；不改仓库其他文件。
+
+## 0. 全局设计语言
+
+- 深色底 #0B0F1A；主渐变 #4D6BFE→#9B7EFF；磨砂玻璃卡片（backdrop-filter blur + 白边光 + 内辉光）
+- 字体：system-ui 栈；标题字重 700-750；正文 1.6-1.7 行高
+- 动效：进入视口渐显上浮（IntersectionObserver）；卡片 hover 抬升；克制不闪烁
+- 语言切换：右上角 中/EN 切换，`<html lang>` 与全部文案随之切换（默认中文）
+
+## 1. Hero（首屏）
+
+- 主标题：dsh-auto-memory —— 让 AI 真正记得你 / An AI that actually remembers
+- 副标：DeepSeek Harness 的联想记忆与人性化交互插件：三层记忆、每轮自动沉淀、主动提醒、欢迎向导、无人值守
+- CTA 双按钮：安装命令（点击复制 `pnpm add @a9i5k4/dsh-auto-memory`）/ GitHub
+- 背景：三层玻璃板 Logo 放大虚化悬浮（呼应品牌）；可放 docs/screenshots/tour-welcome.png 作侧图
+
+## 2. 数据流（核心原理一图流，源自架构图）
+
+按架构图 A/B/C 三段做成三张横向卡片+箭头连接：
+1. 观察：监听对话/工具事件 → 记忆锚定（M3）
+2. 检索决策：三层检索（词法保底/内置语义/Python BGE-M3）→ 两车道决策（该不该打断、注入什么）
+3. 投递闭环：固定边界注入（前缀缓存友好）→ delivered/seen 证据 → 唤起回顾可打分
+每张卡一句人话解释；底部注明"决策全程可复核，记忆治理永远在 JS 权威层"
+
+## 3. 功能全景（逐节，禁止省略）
+
+### 3.1 三层记忆体系
+表格：用户级 MEMORY.md / 项目笔记 / 每日日志 / 每日反思——位置+内容；注入策略（静态纪律进 system prompt 保缓存；动态记忆只注入最近 1 天，其余按需 recall；凭证永不进提示词）
+
+### 3.2 自动沉淀（记忆自己写自己）
+每轮结束子代理静默评估；主题分组写日志；长期决策升格项目笔记；跨项目规则升格用户级；闲聊跳过；失败重试+心跳；每日预算+AI 自动压缩（超限不拒写）
+
+### 3.3 欢迎向导（v0.1.30 大更新，配 tour-*.png 截图×4）
+分步介绍全部功能；每项当场开关立即生效；Office/Fluent 式彩色玻璃图标族+专属动效；语义引擎检测/下载/自检内联；外部记忆实时扫描逐源勾选；一次性触达（老用户升级自动播放）；设置页可重看
+
+### 3.4 唤起与技能固化（配 panel-refine.png）
+联想检测→下一环节注入；技能 checklist 自动附上；跨会话验证晋升（observed→candidate→validated→active）；90 天归档+置顶；唤起回顾页 A/P/S/H/E 打分+队列汇总+政策提示
+
+### 3.5 无人值守模式
+手动开关+夜间自动托管（22:00-08:00 可调）；托管期间零寒暄/零行为指令/日历静默/上下文稳定；面向长批处理（源自 Issue #10 社区反馈）
+
+### 3.6 AI 问候与每日反思
+时段问候（晨/午/晚提及当日要点）；暂离 >1h 回归自动开面板+欢迎回来；每日第一次会话呈现昨日结构化反思
+
+### 3.7 智能检索与工作区全景
+自然语言跨层检索（关键词级，标注来源）；跨工作区检索天然支持；工作区关系图（AI 归纳主题与关联，拖拽/缩放/点卡详情）
+
+### 3.8 日历 — AI 替你维护
+对话中识别 deadline/约定自动入日历；未完成注入后续会话提醒；四象限+日时间轴 07:00-22:00+地点/提醒字段
+
+### 3.9 外部记忆继承
+WorkBuddy/CodeBuddy/Claude Code/Codex 扫描发现；按源导入（纯路径指针不复制）；按源删除；导入侧+注入侧双重卫生闸门
+
+### 3.10 记忆卫生（生产级）
+写入门禁 sanitizeForWrite（GBK 乱码 34 特征/复读/重复行/外部画像 JSON/base64）；调试中心脏 token 扫描（按行区间只报位置）；写入上限与 60 行去重
+
+### 3.11 记忆生命周期
+30 天蒸馏（AI 提炼长期价值进笔记，原文归档 archive 不丢）；明确边界：procedure skills 与两级笔记不在蒸馏范围；归档原文不在常规检索扫描内（蒸馏要点随笔记常驻注入）；memory_consolidate 发散固化；预算自动压缩
+
+### 3.12 工程内核（信任背书）
+零运行时依赖；前缀缓存友好（字节级稳定提示词）；限额 AI（≤8 次/天）；集中式存储；可选 Python sidecar（BGE-M3 int8，失败自动回退词法）
+
+## 4. 界面速览
+
+网格卡片放 7 张截图（docs/screenshots/）：panel-overview / panel-hub / panel-refine / tour-welcome / tour-toggles / tour-external / tour-core；每张一句说明
+
+## 5. 快速开始
+
+三步安装（pnpm → bundles 数组 → 重启）；AI 时代安装法（可复制文本框，带复制按钮）；更新方式；系统要求（dsh web、Node 内建依赖即可跑、Python 档可选）
+
+## 6. 社区与链接
+
+Contributors：@ProperSAMA（PR#12）、@nkh0472（Issue#10）带链接；GitHub / npm / License BSD-3-Clause；欢迎 issue/PR 一句话
+
+## 7. 页脚
+
+极简：项目名 + GitHub + npm + 「记忆存在你自己的机器上」隐私一句

package/docs/M-CM-PLAN.md

@@ -0,0 +1,166 @@
+# M-CM 集成规划：上下文管理系统（对标 Codex history-notes / new_context）
+
+> 2026-09-06 源码级调查后产出。目标：把"上下文管理"有机接入现有 M1–M7 架构，而不是另起炉灶。
+> 功能事实对账以 [NEXT-MAJOR-VISION.md](NEXT-MAJOR-VISION.md) §2 为准；本文件是实施蓝图（路标非权威，实现以代码与测试为准）。
+
+---
+
+## 0. 情报摘要
+
+### 0.1 Codex 真实机制（openai/codex 源码证据，2026-09-06 抓取）
+
+`features.context_management.experimental_mode`（v0.153.0，2026-09-03，默认关）激活三件套：**token 预算上下文 + history notes + `new_context` 工具**。源码事实：
+
+- **笔记是服务端存储**：`codex-rs/ext/history-notes/src/backend.rs` 把 `alpha/notes/v2/write_file`、`append_to_file`、`search_contents`、`alpha/history/v2/search_contents` 全部 POST 到 OpenAI 后端（加密参数头 `x-openai-encrypted-tool-arguments`）。**笔记不在用户机器上。**
+- **门槛校验在源码里**：`extension.rs` 要求 `token_budget.use_history_notes_extension && provider.is_openai() && auth_uses_codex_backend()`——API-key 会话、自定义 provider 全部排除。
+- **窗口续命 = thread_hint 片段**：`ContextContributor` 在线程启动时调 `alpha/notes/v2/thread_hint`，取回 **≤4KB** 文本，以 `PromptSlot::ContextWindow` + 内容类型 `notes.thread_hint` 注入新窗口。超 4KB 直接判失败不注入。
+- **new_context 工具只有一行**：`handlers/new_context_window.rs` → `session.request_new_context_window()`，回执文案 "A new context window will start without summarizing conversation history."——**开新窗是 host 的领地，工具只是触发器**（与我们"插件只助产"的边界判断完全一致）。
+- **实现形态 = 扩展 + 四种 contributor**（thread lifecycle / config / context / tools）——OpenAI 自己也把这一层做成插件式扩展，验证了我们在 DSH 插件层做这件事的架构正确性。
+- 传统压缩仍在：`model_auto_compact_token_limit`（默认 200K 阈值）、`/compact`、`compact_prompt`；0.154.0-alpha 在 TUI 加"实时压缩状态"。
+
+### 0.2 Anthropic 路线（对照）
+
+[Memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool)（Agent 在本地 memory 目录 CRUD 文件）+ [Compaction](https://platform.claude.com/docs/en/build-with-claude/compaction)（2026-01 beta，API 级自动压缩）+ context editing。模式 = **有损压缩 + 无损旁路（文件笔记）双轨**。痛点：Claude Agent SDK 的压缩边界对调用方不可见（[SDK issue #772](https://github.com/anthropics/claude-agent-sdk-python/issues/772)）——印证"压缩预告事件"是行业缺口。
+
+### 0.3 Letta/MemGPT 路线（开源先例）
+
+OS 式记忆分层：core memory（上下文内的 self-edited memory blocks，"RAM"）vs archival memory（上下文外的外存，"磁盘"，按需检索拉入）——[Agent Memory](https://www.letta.com/blog/agent-memory/) / [Memory Blocks](https://www.letta.com/blog/memory-blocks/)。开源、本地、Agent 自编辑记忆——与本插件同宗，但其为独立框架，我们为宿主内插件。
+
+### 0.4 命名澄清（2026-09-06 boss 纠正）
+
+"Extra"是误传——boss 所指即 **Astra 本身**：GPT-6 Astra（2026-09-03 发布，9/4–9/5 铺开 Business/Pro）带来的**一套新的上下文机制**（中文媒体口径："上下文窗口填满时不再只靠压缩摘要，而是跨上下文窗口的笔记保留，可检索此前的需求/测试结果/工具输出"，另有 105 万 token 窗口、12.8 万最大输出）。机制挂 Astra 名下，Codex 侧配置键 `context_management.experimental_mode`，将成 Astra 默认。本文 §0.1 的源码级机制调查即该机制的实现细节。
+
+## 1. 对账：现有架构 vs 三家机制
+
+| 能力 | Codex | Anthropic | Letta | 本插件现状 |
+|---|---|---|---|---|
+| 任务态笔记 | 服务端 alpha/notes（厂商托管） | 本地 memory tool 文件 | core memory blocks | 四层记忆+治理式写回（本地已有；**缺任务态四段结构**） |
+| 新窗续命注入 | thread_hint ≤4KB 片段 | —（SDK 压缩黑盒） | core memory 常驻 | 固定边界注入动态快照（**已 live，缺 handoff 专用片段**） |
+| 归档可搜索 | 服务端 search_contents | context editing 清理 | archival+检索 | evidence store+词法/语义双臂（已 live）；**会话帧未索引** |
+| 开新窗 | new_context 工具触发 | 自动压缩 | 自动分层 | DSH host 领地（**未接**） |
+| 水位感知 | session/token_budget.rs | SDK 阈值 | 自动 | M2 ContextObserver 可投影（**未接**） |
+
+结论：四件套里**两件半已存在**，且两处比 Codex 强（本地所有权、语义双臂）。缺的是四件事——正是 M-CM1..4。
+
+## 2. M-CM1 四段式交接笔记（结构化 ledger）
+
+- **存储**：`workspaces/{workspace}/handoff/YYYY-MM-DD-HHMM-{slug}.md`。四段 schema：`## 任务状态` / `## 目标` / `## 已试方案与失败原因` / `## 进度与下一步`，头部 front-matter（workspace、触发原因、关联会话 id）。
+- **白板层（PLAN.md，2026-09-06 启发新增）**：模型随任务推进理解全貌后，用**人能理解的方式**重写 `workspaces/{ws}/handoff/PLAN.md`——整个项目的规划图（"白板"）；后续交接只在此快照上增改，每次重写旧版自动移入 `handoff/archive/PLAN-<ts>.md` 保留更改历史。与四段式 ledger 的关系=git 的树与提交日志：PLAN.md 是当前树，ledger 是 commit 历史。PLAN.md 注入优先级高于单篇 ledger。
+- **白板的用户面（HCI 联动，同日补）**：白板不只给模型——**用户（尤其探索中/思路混乱的用户）靠它实时看见自己**：做了什么（ledger 时间线）、走错了哪些路（"已试方案与失败原因"段）、改了哪些东西（PLAN 版本 diff）。这是外化认知/共享 grounding 工件：用户与 Agent 对照同一张图对齐。落点：①面板新增「白板」视图（PLAN 当前版+版本切换+ledger 时间线，复用 notes/logs 渲染管道）；②写入者与**回合末固化 prompt 同源同钩**（见上条——主模型每轮固化时一次产出两份：流水→日志/项目记忆，全貌增改→PLAN.md）；③与每日反思互补：反思是回顾（昨天），白板是并发（现在）。
+- **写入者三入口（2026-09-06 二次修正+代码锚定）**：①**回合末固化 prompt**——主大模型每轮对话结束时亲自把内容固化进项目记忆。代码锚点：GUIDANCE 尾注层（prompt order 10000，"完成实质性工作后必须调用"），层文案 builder≈`lib/index.js:2026`，`promptLayerOverrides` 可覆盖——PLAN 增改指令挂这层。②`memory_note` 工具显式写（M-CM2）——代码已有 append/replace 双模+8000/20 万字上限（`lib/index.js:4774`），PLAN.md 重写走 replace 模式零新增。③水位触发自动写（M-CM4）。**子代理层（晋升判断：每日→长期、画像内容）是另一层，不写白板**——它是 PLAN/ledger 的消费方。注：代码里 `autoConsolidate` 子代理（turn-stopping，`lib/index.js:128,1824`）也在写日志——两条写入路径并存，白板主挂 prompt 层，子代理里程碑为可选次级写入者。全部过 `sanitizeForWrite` 门禁（`lib/index.js:3970`）。
+- **生命周期**：最近一篇进入注入快照首位（见下）；90 天归档复用 Hermes 规则；**用户可直接读改**——这是与 Codex 服务端加密笔记的根本差异。
+- **注入（我们的 thread_hint）**：动态快照首位加"接续摘要"片段——handoff 最新一篇的压缩版（对齐 Codex 4KB 上限教训，设硬预算并给 evidence 引用），内容类型 `handoff.hint`，走既有 M6 固定边界，前缀缓存纪律不破。
+
+## 3. M-CM2 主动检索工具（2026-09-06 质询后修订：扩展现有工具面，不新增平行工具）
+
+> **质询记录**：`memory_note`/`memory_recall` 已存在（前者写项目笔记、后者 AI 扩展关键词的会话式检索）。原计划"新增两个同名工具"属冗余设计，工具面污染会让模型选择混乱。修订如下。
+
+**与现有工具的真实差异（三维度）**：
+1. **语料**：现有工具只能搜四层记忆（用户级/项目笔记/日志/反思）；handoff ledger（M-CM1）与会话帧归档（M-CM3）是**任何现有工具都摸不到的新地面**——尤其会话帧=记忆化之前的原始材料。
+2. **调用语义**：`memory_recall` 是重型路径（AI 扩展关键词→会话式回答），面向"回答问题"；Agent 在工作循环里自用需要**轻量直返**——它就是查询的发出者，不需要别人替它扩展关键词，要的是结构化命中（条目+引用+预算截断）。
+3. **归宿**：检索结果是 advisory 素材，进 M6 固定边界仍受治理——权限分立不因新工具改变。
+
+**修订后的落点（扩展现有工具，收敛工具数）**：
+- `memory_recall` 增 `scope` 参数：`notes|logs|reflections|handoff|sessions|all`（默认 `all`，行为向后兼容）；scope=handoff/sessions 时走轻量直返（不做 AI 扩展，直接 BM25/语义命中），返回带 evidence 引用（复用 M5 cite 规范）与硬预算截断（对齐 Codex 4KB 教训）。
+- `memory_note` 增 `kind: handoff` 参数：写四段式 ledger（§2 schema）；缺省行为不变（写项目笔记）。
+- 门控代理注册不变（CUA 先例；**ctx.get() 坑**规避）；**未命中必须可见**并进审计页（§8.4.3）。
+- 例外条款：若实测发现"轻量直返"与"会话式回答"在同工具内语义打架（参数爆炸/模型误用），再拆独立 `memory_search`——拆分是后备，不是起点。
+
+## 4. M-CM3 会话检索增强（2026-09-06 审计修正：host 已有关键词级检索，本项=升级非新建）
+
+> **审计修正**：原文"会话帧未索引"有误。host 自带 `sessionQuery.searchSessions`（`lib/index.js:4531` `ctx.get('sessionQuery')`，:2226 调用，limit≤10），`memory_recall_pre` 已覆盖"历史 DSH 会话全文检索（如部署启用）"——**关键词级**，GUIDANCE 自己声明了局限："外部会话检索为关键词级（非语义）"。
+
+- **真正的增量**：①**语义通道**——C2/BGE-M3 向量升档（词法兜底不变），补齐"非语义"短板；②**排序与 provenance**——命中带时间戳/会话 id/帧位置引用（现状仅文本段），统一 M5 cite 规范；③**handoff corpus 并入**（M-CM1 新地面）；④limit≤10 的预算策略与 evidence 引用按需深查。
+- 索引器（若 host sessionQuery 能力不足再建）：增量扫描→digest 去重→词法倒排+可选向量；凭证段过滤**先于**入索引；脏 token 拒入；元数据落 memoryRoot 独立目录可整体删除。
+- zstd 解压能力已就绪（`lib/index.js:50-51,2328`）。
+
+## 5. M-CM4 水位感知与压缩联动
+
+- 水位估计：M2 ContextObserver 已投影上下文——先做回合 token 估算的启发式 fill ratio；若 DSH 暴露真实 token 计数则直连。
+- 行为：fill ≥ 80% → 注入 advisory 尾注（"上下文将满，建议开新会话——交接笔记已就绪"）+ 自动写/刷新 handoff；无人值守模式下 advisory 静默（不打断批处理）。
+- 压缩预告事件：若 DSH host 有则订阅，压缩发生前自动落 handoff；若无 → **向 DSH 提 feature request**（Anthropic SDK #772 同款痛点=行业缺口，提案有据）。
+- 边界重申：开新窗/压缩是 host 领地，插件只提示与助产（与 Codex new_context 设计同理）。
+
+## 6. 差异化事实（宣传可直接引用，全部有源码/文档依据）
+
+1. **本地优先**：Codex 笔记在厂商侧加密存储；我们在用户盘上的纯 Markdown。
+2. **模型无关**：Codex 源码硬校验 ChatGPT backend；我们任何模型、任何 provider（含自定义代理）。
+3. **可读可改**：Codex thread_hint 服务端生成、只读；我们的 handoff 用户直接编辑。
+4. **检索更强**：词法/语义双臂 + 67 条人工金标（actPrecision 0.917、有害注入 0）。
+
+## 7. 排期与验收
+
+| 顺序 | 里程碑 | 依赖 | 验收 |
+|---|---|---|---|
+| 1 | M-CM1 交接笔记 | 无（纯插件侧） | schema+PLAN 白板层+三写入者+注入片段；smoke（真实函数抽取驱动）+ 复放 precision 不回退 |
+| 2 | M-CM2 检索扩展 | CM1 存储 | memory_recall scope 扩展+memory_note kind=handoff；门控代理 E2E：调用/回执/审计；检索复放 |
+| 3 | M-CM3 会话帧索引 | 双臂就绪 | 索引覆盖率+增量正确性；scope=sessions 复放召回 |
+| 4 | M-CM4 水位联动 | CM1 自动写 | 模拟水位→advisory+handoff 自动落盘；无人值守静默 |
+
+宣传联动：CM1+CM2 live 后，README「她怎么交接」占位章换实装说明，摘除三处"即将上线"标注（位置清单见记忆存档）。
+
+## 8. 批判性分析：理论依据、局限与设计修正（2026-09-06）
+
+### 8.1 机制还原——它不玄幻，是"压缩时点搬家"
+
+三种机制都是信息的投影，区别只在**投影时机与投影函数的输入**：
+
+| | 压缩（compaction） | 笔记（notes） | 检索（search） |
+|---|---|---|---|
+| 时机 | 事中，窗口将满时盲压 | 写入时（当时有全量上下文） | 读出时（带着未来查询） |
+| 输入 | 仅历史 | 历史+写作时的任务理解 | 查询本身 |
+| 损失 | 固定、不可追回 | 有损但经策展 | 对被查询的切片近似无损 |
+
+"不再压缩"是话术：hint 是摘要、笔记是写时压缩、检索结果是读时压缩。**压缩没有消失，是搬到了信息更充分的时点，且原始数据保底可查。** 查询分布不可知时，懒惰求值（检索）优于预计算（摘要）——但仅对"知道要找什么"的信息成立。
+
+### 8.2 两个诚实的"不能"
+
+1. **"切了比压缩保留得全"不无条件成立。** 对定向问题（"那个测试为什么失败"）检索完胜摘要；对弥散性知觉（"还有哪些没说但相关的"），一条好摘要可能优于空档案馆——**模型不知道自己不知道**：hint 没提 X、模型又没想到搜 X，X 就等于丢了，这点上甚至不如压缩（摘要可能顺嘴提过 X）。对策=双层：hint/四段式管弥散层，检索管定向层，缺一不可。
+2. **"能力一条直线"不存在。** 没有任何系统让单窗能力恒定；长程（如 Anthropic 1-2 天跑大项目）的真相是把**工作**做成可恢复，让多个窗口串联表现得像一条线：环境即状态（文件/git/测试），上下文只是工作集。已知配方：子代理隔离（每子任务新窗）+ 文件状态 + 压缩 + memory tool + 验证回路 + 为长程任务训练的模型（Anthropic 公开了 compaction/memory tool 文档，比 OpenAI 透明）。断线风险清单：冷启动缺默会状态、重议已决事项、hint 锚定偏差、笔记腐烂与矛盾累积、检索静默失败。
+
+### 8.3 Astra 机制的隐藏依赖（源码推断，批判点）
+
+- **笔记由 Agent 自觉书写**——质量押注在模型自编辑纪律上，"机制成功"与"模型够强"未解耦；弱模型同机制可能不如好压缩。
+- **hint 服务端生成、只读、≤4KB**——用户不可审计，超限直接不注入。
+- **仅 ChatGPT backend**——排除自定义 provider，等于只在自家受控栈内开闸。
+- 推论：它玄幻，部分因为把难度藏进了"模型够强+自家后端"两个前提里。**我们的机会=把质量从模型自觉中解耦**：host 侧触发（里程碑/水位）+ 固定 schema（弱模型也能填表）+ 本地可审计。
+
+### 8.4 设计修正（批判 → M-CM 决策）
+
+1. hint 不做黑盒：本地四段式 handoff，用户可读改（§2）——checklist 化对抗 unknown unknowns。
+2. 笔记不押模型自觉：三入口触发含 host 侧强制（里程碑判定+水位），固定 scaffold 填空（§2/§5）。
+3. 检索失败必须可见：memory_search 未命中也回报并进审计页——**静默失败是 handoff 路线的头号隐患**（§3）。
+4. 防笔记腐烂：handoff 带 supersede 语义（新交接标注取代旧交接），旧篇并入 30 天蒸馏泵（§2）。
+5. 防重议已决事项：注入片段含"目标与已决"段（四段式承担），advisory 口吻。
+6. 漂移自检（P2 可选）：新会话首轮 advisory 建议模型对照 handoff 复述当前计划——廉价 drift check，不做硬拦截。
+7. 期望管理：fill-ratio 是启发式，advisory-only；evidence 链与固定边界纪律不动摇。
+8. 宣传口径对齐：对外不承诺"比压缩更全"，承诺"该全的地方全（定向检索）、该连的地方连（结构化交接）、且全程你可审计"。
+
+## 9. 风险与开放问题
+
+- **子代理派生（2026-09-06 审计修正：机制已在插件手中）**：审计发现插件**已经能自产子代理**——`runSubagent(text, label, agent, timeoutMs)`（`lib/index.js:2922`），现役六个标签（auto-memory-compact / smart-kw / smart-ans / ws-map / summarize / greet），`_ownSubagents` WeakSet 防套娃（:673）。任务型子代理（水位高+任务可分解时派出）机制层面**已验证可行**，剩余工作是策略设计：①子代理产出自动沉淀为 handoff/PLAN 增改；②子代理注入策略适配（吃不吃记忆注入、吃哪层）；③"何时值得派"的 advisory。
+- **memoryRoot git 化（可选增强）**：历史保留当前用 archive 副本；若环境有系统 git 可对 memoryRoot 做轻量自动提交（零依赖约束→git 存在才启用，缺失降级副本）。
+- DSH 是否暴露 token 计数/压缩事件——**待验证**；无则 M-CM4 降级为启发式 + feature request。
+- 会话帧索引隐私边界：凭证段过滤必须先于索引器上线，顺序不可倒。
+- 工具返回的 token 预算：对齐 Codex 教训设硬上限（hint ≤4KB 的同款纪律），超出部分给 evidence 引用让模型按需 `memory_search` 深查。
+- 工具调用的用户可见性：复用唤起回顾审计页，避免"黑箱工具"观感。
+
+## 10. 回归项目审计对账表（2026-09-06，逐锚点核验 lib/index.js 等实现）
+
+| 规划锚点 | 代码锚点 | 判定 |
+|---|---|---|
+| 回合末固化 prompt（GUIDANCE 尾注层） | `lib/index.js:59-66`（order 10000 尾注）、`:2026`（层文案 builder）、`:161` promptLayerOverrides | ✓ 命中，白板挂点确认 |
+| memory_note append/replace 双模 + 8000/20 万上限 | `lib/index.js:4774` | ✓ 命中，PLAN.md 重写走 replace 零新增 |
+| memory_log 追加日志 | `lib/index.js:4755` | ✓ |
+| sanitizeForWrite 门禁 | `lib/index.js:3970` | ✓ |
+| 会话检索 | `:4531` `ctx.get('sessionQuery')`、`:2226` searchSessions、`:4846` 工具描述（含"历史 DSH 会话全文检索"） | ✗ 修正：已有关键词级检索，M-CM3 改定位为"升级"（语义通道+provenance） |
+| 子代理派生 | `:2922` runSubagent（6 个现役标签）、`:673` `_ownSubagents` 防套娃 | ✗ 修正：机制已在插件手中，任务型子代理可行性=已验证 |
+| M2 ContextObserver（水位挂点） | `:338`、`:725`（"只观察，不检索，不注入"） | ✓ |
+| 固定边界注入 | `:1936` renderMemoryDynamic、`:276/:289` 动态/静态分层 | ✓ |
+| zstd 会话帧解压 | `:50-51`、`:2328` | ✓ |
+| lexical_pre_v2 + C1/C2/C3 三层引擎 | `context-bridge-pre.js:487`、`context-host-pre.js:8`、client.js:175 | ✓ |
+| evidence store + M5 cite + M9 success evidence | `:1164`、`:3102-3131`、`:5074` | ✓ |
+| 晋升层（procedure 跨会话≥3 / 成功≥2 / 高风险批准） | `:239-255` | ✓ |
+| 自动沉淀子代理（turn-stopping+冷却/额度/寒暄阈值） | `:128-134`、`:4596`（延迟启动防与会话收尾竞争）、`:1824` | ✓ 与固化 prompt 双写入路径并存；术语按 boss 两层论 |
+
+审计结论：规划与项目对得上，两处误判（会话检索现状、子代理能力）已当场修正；无孤立概念。

package/docs/M-CM-STATE.md

@@ -0,0 +1,64 @@
+# M-CM 实施状态（免压缩过程档案）
+
+> 用途：M-CM 长任务的实施过程档案。压缩后恢复工作**先读本文件 + [M-CM-PLAN.md](M-CM-PLAN.md) §7 排期**，再看 git log 最近提交。
+> 规则：每完成一个可提交单元就更新本文件"进度账"并 commit（commits 已授权；push 待用户确认）。
+
+## 当前阶段
+
+**M-CM1 实施中**（2026-09-06 开工）。范围：四段式 ledger + PLAN.md 白板层 + 写入者①②（固化 prompt 层扩展 + memory_note kind 扩展）+ 注入片段 + 白板面板视图 + smoke 测试。
+
+## 进度账
+
+- [x] 规划与审计（M-CM-PLAN.md §0-§10，含回归审计对账表）
+- [x] 实施步骤 1：读代码锚点（memory_note handler、GUIDANCE/静态纪律层、renderMemoryDynamic、resolvePaths、_doRefresh 装载器、DEFAULT_PROMPT_LAYERS）
+- [x] 实施步骤 2：handoff 存储函数（writePlanSnapshot 归档/writeHandoffLedger 同秒 -b 后缀/readLatestHandoff 按 mtime）
+- [x] 实施步骤 3：memory_note_pre 增 kind: handoff|plan（同 sanitizeForWrite 门禁;plan 走 replace 归档;不走项目笔记预算）
+- [x] 实施步骤 4：renderMemoryStatic 增"交接与白板"纪律行（GUIDANCE 层不用动,静态层即固化纪律载体）
+- [x] 实施步骤 5：注入片段（动态快照首位:snapshotPlanTitle→snapshotHandoffTitle→日志段;stripSensitiveSections+truncateHead 硬预算;handoffEnabled=false 隐藏）
+- [x] 实施步骤 5.5：smoke-test-handoff-pre.mjs 22/22（G0 源码守卫/G1 时间戳/G2 白板归档/G3 账本最新篇/G4 注入行为);主套件+4 套 UI 回归全绿
+- [x] 实施步骤 6：配置键已加(handoffEnabled/handoffPlanChars/handoffLedgerChars);设置页行随白板视图一起做
+- [x] 实施步骤 7：面板「白板」视图（client.js PlanTab:当前全貌/版本切换/账本时间线,中英 i18n）+ handoff-state API（?file= 白名单限 handoff 目录）+ 路由守卫 34→35 ×3 文件
+- [x] 实施步骤 8：live 验证（2026-09-06 浏览器实测:记忆入口恢复/白板页签渲染种入的 PLAN 全貌+账本时间线/handoff-state API enabled:true;0.1.2-rc.1 兼容事故修复后全链路通）
+- [x] 实施步骤 8.5：M-CM2 已交付（memory_recall scope=all|handoff|sessions 三档路由+白板语料并入全量检索+设置页开关+smoke 30/30+live E2E）
+- [x] 实施步骤 9（部分）：M-CM4/M-CM5 已交付（commit:水位感知+交接助产）
+- [x] 精修轮（dsh-context 借鉴,commit:refine）：①水位计量升级官方 token-meter 公式(4 字符≈1 token+每消息 4,waterLevelWindowTokens=65536 默认)②compaction/summary|prune 事件感知(压缩后 0.5≤ratio 自动补写骨架,seq 去重)③骨架账本 v2=抽取性压缩(策展源:沉淀日志尾+反思摘要+笔记头,dedupe 限行——**测试抓出真 bug:join/dedupe 顺序颠倒致单字化,已修**)④白板注入改行边界截断(truncateLinesBounded)⑤advisory prompt 科学化(四段各≤5 行/失败项「方案→原因」/下一步带文件或命令)。参考=bowenliang123/dsh-context(README:index.js 1852 行/client.js 6892 行,官方 meter 移植+sessionProjections 投影注册表模式,后续 M-CM 深化可注册投影单元)——turn-stopping 测会话消息总字符→启发式水位;越阈每会话一次:动态快照 advisory（写账本/刷白板/建议开新窗/派子代理=M-CM5 指引）+自动系统骨架账本兜底;配置 4 键+设置页 3 项（中英）;smoke G6 35/35;重启上线+白板回归 OK
+- [x] 实施步骤 9.2：**水位窗口自动检测**（boss 指示"不能拍脑子"）——解析 settings.yaml 的 agent-default-model(provider+model)→对应模型 contextWindow（实测 deepseek-v4-flash=1000000）→检测失败回退 131072→waterLevelWindowTokens 手动覆盖优先+60s 缓存；handoff-state API 携带水位七字段；白板页签顶部**水位卡**（数值+比例条+来源+阈值说明,中英,浏览器实测渲染）；smoke 43/43
+- [x] 实施步骤 9.5：**2.1.0 已发布**（GitHub main c396d29+tag v2.1.0；npm latest @a9i5k4/dsh-auto-memory@2.1.0；npmmirror 同步已触发）——changelog 重构为双大版本叙事（2.1 交接白板+水位感知 / 1.3 主动联想记忆回顾），dispatch bigKey 切 2.1.0（G7 跨大版本断言过），实验特性出厂默认关闭（handoffEnabled=false），水位阈值设置项补齐（10-150%），README 双语交接章转实验性上线；boss 实例配置 handoffEnabled=true；live 验证：模拟升级路径弹出 2.1.0 卡（含实验说明+1.3 回顾），preview 分支已推
+- [ ] M-CM3 残余（后续增强）：会话语义通道（sessionQuery 词法已够用,语义升档视成本）;跨工作区白板语料（语义上存疑,缓）
+- [ ] M-CM4 精度升级（后续）：host 暴露真实 token 计数/压缩预告事件时,把启发式字符估计换成真实水位（向 DSH 提 feature request 的依据已记录）
+
+**M-CM2 已交付（1 commit）**：recall scope 三档路由（handoff/sessions 早返轻量直返）+ searchHandoffCorpus（PLAN+最新账本+归档三语料,limit 预算）+ searchSessionHistory（sessionQuery 抽取复用）+ listHandoffLedgers + 设置页 handoffEnabled 开关（自动化分组,中英）+ smoke G5 断言（30/30 总）+ live E2E（种数据→白板渲染→API 返回）。
+
+**⚡ 2026-09-06 harness 0.1.2-rc.1 兼容事故（已修复，身份迁移 commit）**：
+- 症状：harness 更新重启后记忆插件入口/设置全消失（其他 @a9i5k4/@linxin666 插件正常）。
+- 根因：**0.1.2-rc.1 把 `@deepseek-ai` 作用域保留给官方包——profile 解析的该作用域第三方 bundle（dsh-auto-memory、dsh-draw-gacha）被从浏览器组合加载（combo）剔除**；主机半边（webServer 注入路由）不受影响照常跑。诊断链：认证 token 每次重启更换（401 闸门）→ 大组合 URL 缺席 auto-memory → 直接路径 404（对所有人正常,新版只走 combo）→ 与 ark9canvas 逐字段对比清单无差异 → 按 package.json name 作用域排除。
+- 修复：插件身份统一迁到发布身份 **@a9i5k4/dsh-auto-memory**（package.json name / cordis.patch.yml name / client loader id ×2+tag.dataset）;release.mjs 的 @deepseek-ai→@a9i5k4 转换变恒等但校验（§377 要求含 @a9i5k4）仍过。profile 挂载改 `@a9i5k4/dsh-auto-memory: link:D:/dsh-auto-memory` + bundles 同步。
+- live 验证全过：记忆入口恢复/白板页签渲染（空态）/handoff-state API enabled:true。
+- **待办**：①dsh-draw-gacha（用户另一插件,@deepseek-ai 作用域）同样中招,需同样改名;②token 每次重启更换（0.1.2-rc.1 认证闸门）,URL 以 dsh web 终端打印为准;③旧 @deepseek-ai junction 在 profile node_modules 残留（inert,可忽略）。
+
+**测试调试备忘**：抽取函数时方法体引用的模块级符号（path/mkdir/writeFile/readdir/stat/existsSync/handoffStamp/nowHm）必须逐个注入 new Function 作用域;grab 用逐行扫描+(){} 混合配平（正则方案在 Bash 工具下反斜杠被吞）;CRLF 行尾注意。
+
+## 关键代码锚点（已审计确认）
+
+| 用途 | 锚点 |
+|---|---|
+| GUIDANCE 尾注层（order 10000） | lib/index.js:59-66；层文案 builder ≈:2026；promptLayerOverrides :161-163,1945 |
+| memory_note handler（append/replace 双模, 8000/20 万） | lib/index.js:4774 |
+| memory_log handler（2000/条） | lib/index.js:4755 |
+| sanitizeForWrite | lib/index.js:3970 |
+| renderMemoryDynamic 动态快照 | lib/index.js:1936（分层 :276/:289） |
+| sessionQuery（host 会话检索, 关键词级） | lib/index.js:4531, :2226 |
+| runSubagent/_ownSubagents | lib/index.js:2922 / :673 |
+| M2 ContextObserver | lib/index.js:338, :725 |
+| zstd 帧解压 | lib/index.js:50-51, :2328 |
+| autoConsolidate 子代理（turn-stopping） | lib/index.js:128-134, :4596, :1824 |
+| API 路由注册（handoff-state 要新增于此） | API map ≈:4531 区域（实施时定位） |
+
+## 设计速记（实现时遵守）
+
+- PLAN.md=replace 快照（旧版进 `handoff/archive/PLAN-<ts>.md`）；ledger=append-only 按时间戳文件
+- 注入预算：PLAN 头部 ≤1200 字符 + 最新 ledger ≤800 字符，硬截断+evidence 指引（"全文见 handoff/，可 memory_recall 深查"）
+- 前缀缓存纪律：只动动态快照层，静态纪律层字节不碰
+- 工具名写 _pre（发布转换转裸名）；GUIDANCE 文案追加控制在 ~3 句内
+- 门禁：所有写入过 sanitizeForWrite；密钥段规则不变
+- 术语：白板=PLAN.md；ledger=交接账本；两层论（固化 prompt 层 vs 子代理晋升层）