sage-mem 1.6.4 → 1.7.0

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `1.6.4`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
+**Current release: `1.7.0`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.
@@ -389,7 +389,7 @@ The two things are moved **differently**, spelled out:
 | `SAGE_MEM_MAX_BASELINE` | `8` (1–50) | number of `baseline` slots |
 | `SAGE_MEM_STALE_DAYS` | `1` (0–365) | threshold for marking a heading 「保存于 N 天前」(saved N days ago); 0 = mark every one |
 | `SAGE_MEM_TASK_ID` | empty | scope of task checkpoints; empty falls back to the session id |
-| `SAGE_MEM_DEBUG` | off | debug logging |
+| `SAGE_MEM_DEBUG` | off | debug logging; when on, the panel's **工具 ▾ → 注入调试** shows the last 8 injection attempts (read-only, never written to disk) |
 
 Value semantics: **out-of-range values are clamped to the boundary, illegal values (including pure whitespace) fall back to the default.**
 
@@ -482,7 +482,7 @@ Version-by-version compatibility record:
 | 0.2.0-rc.2 | compatible |
 | 0.2.1-rc.1 | compatible |
 
-**How to read `compatible`.** It means this plugin's codec and manifest contract has been checked against that host generation (code-level comparison plus the unit/contract suite), **not** that an end-to-end probe was run on that exact host build. The table is a declaration; how each claim was checked is summarized here. Real-host probes so far: `headless` (2026-10-15) and `web` (2026-10-16); the `desktop` profile has **not** been probed yet (see [release-checklist.md](https://github.com/gezi-wen/sage-mem/blob/main/docs/release-checklist.md) §4b). CI runs only on Ubuntu + Node 24 against the `0.2.0-rc.1` peer generation; `engines.node` still declares `>=18`, but Node 18 is not part of the CI matrix.
+**How to read `compatible`.** It means this plugin's codec and manifest contract has been checked against that host generation (code-level comparison plus the unit/contract suite), **not** that an end-to-end probe was run on that exact host build. The table is a declaration; how each claim was checked is summarized here. Real-host probes so far: `headless` (2026-10-15) and `web` (2026-10-16); the `desktop` profile has **not** been probed yet (see [release-checklist.md](https://github.com/gezi-wen/sage-mem/blob/main/docs/release-checklist.md) §4b). CI runs on Ubuntu against **Node 18.x / 20.x / 24.x** with the `0.2.0-rc.1` peer generation; macOS and Windows are not CI-covered, and there is no desktop-host probe yet.
 
 Two points worth spelling out:
 

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`1.6.4`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`1.7.0`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。
@@ -389,7 +389,7 @@ sage-mem 给记忆目录的写入加了**版本守卫**：写入前记下当前
 | `SAGE_MEM_MAX_BASELINE` | `8`（1–50） | `baseline` 名额 |
 | `SAGE_MEM_STALE_DAYS` | `1`（0–365） | 标题标「保存于 N 天前」的门槛；0 = 每条都标 |
 | `SAGE_MEM_TASK_ID` | 空 | 任务检查点的作用域；空则回落会话 id |
-| `SAGE_MEM_DEBUG` | 关 | 调试日志 |
+| `SAGE_MEM_DEBUG` | 关 | 调试日志；打开后面板「工具 ▾ → 注入调试」显示最近 8 次注入的账（只读、不落盘） |
 
 取值语义：**越界夹到边界，非法值（含纯空格）回落默认。**
 
@@ -484,7 +484,7 @@ sage-mem 是纯 DSH 插件，用 `package.json` 的 **`engines.dsh`** 声明宿
 | 0.2.0-rc.2 | compatible |
 | 0.2.1-rc.1 | compatible |
 
-**`compatible` 怎么读**：它表示本插件的 codec / manifest 契约在该宿主代上核对过（代码层比对 + 单元/契约测试），**不表示**在那个确切宿主构建上跑过端到端探针。这张表是声明，核对方式总结在下面。真实宿主探针目前只跑过 `headless`（2026-10-15）与 `web`（2026-10-16）；`desktop` profile **还没跑过**（见 [release-checklist.md](https://github.com/gezi-wen/sage-mem/blob/main/docs/release-checklist.md) §4b）。CI 只在 Ubuntu + Node 24 上、对着 `0.2.0-rc.1` 一代 peer 跑；`engines.node` 仍声明 `>=18`，但 Node 18 不在 CI 矩阵里。
+**`compatible` 怎么读**：它表示本插件的 codec / manifest 契约在该宿主代上核对过（代码层比对 + 单元/契约测试），**不表示**在那个确切宿主构建上跑过端到端探针。这张表是声明，核对方式总结在下面。真实宿主探针目前只跑过 `headless`（2026-10-15）与 `web`（2026-10-16）；`desktop` profile **还没跑过**（见 [release-checklist.md](https://github.com/gezi-wen/sage-mem/blob/main/docs/release-checklist.md) §4b）。CI 在 Ubuntu 上覆盖 **Node 18.x / 20.x / 24.x**，peer 钉 `0.2.0-rc.1` 一代；macOS 与 Windows 没有 CI 覆盖，desktop 宿主探针也还没有。
 
 两点值得说明：
 

package/lib/client.js

@@ -1818,6 +1818,19 @@ const StarmapRuntime = (function (require, _react) {
 					result: { mode: "strict", typeSymbol: "sage-mem/types#RawWriteResult", schema: objCodec, create: () => objCodec },
 					sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
 				},
+				{
+					// 1.7.0：最近几次注入的账。**宽松 codec**（与 audit / 设置那批同一套理由）：
+					// 面板只按字段取值、缺失就降级显示，host 将来加字段不该让整条调用报错。
+					// 每一条记录的字段口径见 lib/recall/debug.js 的 makeDebug 注释。
+					id: "sage-mem#memory/recallDebug",
+					service: "memory",
+					namespace: "memory",
+					method: "recallDebug",
+					invocation: { kind: "direct" },
+					parameters: [],
+					result: { mode: "strict", typeSymbol: "sage-mem/types#RecallDebug", schema: objCodec, create: () => objCodec },
+					sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+				},
 				{
 					id: "sage-mem#starmap/listStars",
 					service: "starmap",
@@ -2053,6 +2066,24 @@ const StarmapRuntime = (function (require, _react) {
 			".smem-drawer-item:hover{background:var(--dsw-alias-bg-layer-2);}",
 			'.smem-drawer-item[data-on="1"]{background:var(--dsw-alias-bg-layer-2);font-weight:600;}',
 			".smem-drawer-item .smem-status{margin-left:auto;}",
+			// ── 注入调试面板（1.7.0）──
+			// 只读账目：时间/会话/结论一行，问题一行，两组得分表，字节与预算一行。
+			// 颜色**只用宿主变量**（主题两档都要能读）；没有一处在硬编码背景上反色。
+			".smem-dbg-head{display:flex;align-items:center;gap:8px;flex-wrap:wrap;}",
+			".smem-dbg-time{font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-secondary);font-size:12px;}",
+			".smem-dbg-sess{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11.5px;color:var(--dsw-alias-label-secondary);}",
+			".smem-dbg-out{font-size:12px;font-weight:600;}",
+			".smem-dbg-ok{color:var(--dsw-alias-brand-primary,#4d76e6);}",
+			".smem-dbg-warn{color:var(--dsw-alias-state-warn-primary,#d97706);}",
+			".smem-dbg-dim{color:var(--dsw-alias-label-secondary);}",
+			".smem-dbg-query{font-size:12.5px;color:var(--dsw-alias-label-primary);white-space:pre-wrap;overflow-wrap:anywhere;}",
+			".smem-dbg-row{display:flex;gap:8px;align-items:flex-start;font-size:12px;}",
+			".smem-dbg-scores{display:flex;flex-wrap:wrap;gap:4px 10px;}",
+			".smem-dbg-score{display:inline-flex;gap:4px;align-items:baseline;}",
+			".smem-dbg-file{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11.5px;overflow-wrap:anywhere;}",
+			".smem-dbg-num{font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-secondary);font-size:11.5px;}",
+			".smem-dbg-hist{display:flex;flex-direction:column;gap:2px;border-top:1px solid var(--dsw-alias-border-l2);padding-top:6px;}",
+			".smem-dbg-hist-row{display:flex;gap:8px;align-items:baseline;font-size:11.5px;}",
 			".smem-status--bad{color:var(--dsw-alias-state-error-primary,#dc2626);font-weight:600;}",
 			// 头部带：三个 tab 共用的一条「我在哪 + 现在什么状态 + 主操作」。
 			".smem-head-job{font-size:12.5px;font-weight:600;}",
@@ -2658,6 +2689,99 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			? h("button", { type: "button", className: "smem-btn", key: "close", onClick: props.onClose }, "收起")
 			: null);
 
+		/**
+		 * 「注入调试」面板（1.7.0）。
+		 *
+		 * 只读：没有「清空 / 重跑」按钮 —— 账是注入链在 `SAGE_MEM_DEBUG=1` 时自动记的，
+		 * 人能做的是看，以及点「刷新」再取一次。入口只在开关打开时出现（宿主告诉我们）。
+		 *
+		 * 每一条记录的口径写在 `lib/recall/debug.js` 的 makeDebug 注释里；这里只负责把
+		 * 「为什么这一步没注入」翻译成人话 —— 那是这个面板存在的唯一理由。**尤其是
+		 * `empty + deduped`**：每轮多步里它占大多数，不解释就会被当成「插件坏了」。
+		 */
+		function RecallDebugPanel(props) {
+			const data = props.data || {};
+			const recs = Array.isArray(data.records) ? data.records : [];
+			const latest = recs.length ? recs[0] : null;
+			const pad = (n) => (n < 10 ? "0" + n : String(n));
+			function clock(ms) {
+				if (typeof ms !== "number") return "";
+				const d = new Date(ms);
+				return pad(d.getHours()) + ":" + pad(d.getMinutes()) + ":" + pad(d.getSeconds());
+			}
+			function outcomeText(r) {
+				if (!r) return "";
+				if (r.outcome === "injected") return "本步注入 " + (Array.isArray(r.injected) ? r.injected.length : 0) + " 条正文";
+				if (r.outcome === "card-only") return "正文没进，只发了状态卡";
+				return r.deduped ? "同题已注入过，本步去重" : "本步没有可注入的内容";
+			}
+			function outcomeClass(r) {
+				if (!r) return "";
+				if (r.outcome === "injected") return " smem-dbg-ok";
+				if (r.outcome === "card-only") return " smem-dbg-warn";
+				return " smem-dbg-dim";
+			}
+			function scoreRows(list, emptyText) {
+				const arr = Array.isArray(list) ? list : [];
+				if (!arr.length) return h("span", { className: "smem-muted", key: "none" }, emptyText || "无");
+				return h("div", { className: "smem-dbg-scores", key: "s" }, arr.map(function (x, i) {
+					return h("span", { className: "smem-dbg-score", key: String((x && x.file) || i) + "-" + i }, [
+						h("span", { className: "smem-dbg-file", key: "f" }, String((x && x.file) || "?")),
+						h("span", { className: "smem-dbg-num", key: "n" }, x && typeof x.score === "number" ? String(x.score) : "?"),
+					]);
+				}));
+			}
+			const injected = latest && Array.isArray(latest.injected) ? latest.injected : [];
+			const histogram = recs.slice(1).map(function (r, i) {
+				return h("div", { className: "smem-dbg-hist-row", key: "h" + i }, [
+					h("span", { className: "smem-dbg-time", key: "t" }, clock(r.at)),
+					h("span", { className: "smem-dbg-out" + outcomeClass(r), key: "o" }, outcomeText(r)),
+					h("span", { className: "smem-muted", key: "n" }, String(r.chars || 0) + " 字节"),
+				]);
+			});
+			return h("div", { className: "smem-tool-panel smem-tool-panel--cap", key: "recall-debug" }, [
+				h("div", { className: "smem-tool-head", key: "head" }, [
+					h("span", { className: "smem-tool-title", key: "t" }, "注入调试"),
+					h("span", { className: "smem-muted", key: "s" }, "SAGE_MEM_DEBUG=1 · 最近 " + String(recs.length) + " 次"),
+					h("button", { type: "button", className: "smem-btn", key: "again", disabled: props.busy, onClick: props.onReload }, props.busy ? "读取中…" : "刷新"),
+					toolClose(props),
+				]),
+				!latest
+					? h("div", { className: "smem-empty", key: "empty" }, "开关已开，但还没有一次注入 —— 开一轮对话再回来看。")
+					: h("div", { key: "body" }, [
+							h("div", { className: "smem-dbg-head", key: "meta" }, [
+								h("span", { className: "smem-dbg-time", key: "t" }, clock(latest.at)),
+								h("span", { className: "smem-dbg-sess", key: "sid" }, String(latest.sessionId || "").slice(0, 8)),
+								h("span", { className: "smem-dbg-out" + outcomeClass(latest), key: "o" }, outcomeText(latest)),
+							]),
+							h("div", { className: "smem-dbg-query", key: "q" }, "问题：" + (String(latest.query || "").trim() || "（无）")),
+							h("div", { className: "smem-muted", key: "stat" },
+								"扫了 " + String(latest.scanned || 0) + " 条 · 摘要命中 " + String(latest.hits || 0) +
+								" · 正文命中 " + String(Array.isArray(latest.body) ? latest.body.length : 0) +
+								" · baseline " + String(latest.baseline || 0)),
+							h("div", { className: "smem-dbg-row", key: "sum" }, [h("span", { className: "smem-label", key: "l" }, "摘要得分"), scoreRows(latest.scores)]),
+							h("div", { className: "smem-dbg-row", key: "body" }, [h("span", { className: "smem-label", key: "l" }, "正文命中"), scoreRows(latest.body)]),
+							h("div", { className: "smem-dbg-row", key: "inj" }, [
+								h("span", { className: "smem-label", key: "l" }, "实际注入"),
+								injected.length
+									? h("span", { className: "smem-dbg-scores", key: "v" }, injected.map(function (f) {
+										return h("span", { className: "smem-dbg-file", key: String(f) }, String(f));
+									}))
+									: h("span", { className: "smem-muted", key: "v" }, "无"),
+							]),
+							h("div", { className: "smem-muted", key: "bytes" },
+								"正文字节 " + String(latest.chars || 0) + "（本代累计 " + String(latest.sessionChars || 0) + "）" +
+								" · 状态卡 " + (latest.cardChars ? String(latest.cardChars) + " 字节" : "未发") +
+								" · 预算挡掉 " + String(latest.skippedByBudget || 0) + " 条"),
+							h("div", { className: "smem-ar-hint", key: "hint" },
+								"注入每走一步都会尝试一次；同题同命中集不会重复注入 —— 所以「空」多半是去重生效，不是坏了。"),
+							histogram.length
+								? h("div", { className: "smem-dbg-hist", key: "hist" }, histogram)
+								: null,
+						]),
+			]);
+		}
+
 		/**
 		 * 稳定的 remote 引用。
 		 *
@@ -4051,6 +4175,15 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			const rawBusy = sRawBusy[0], setRawBusy = sRawBusy[1];
 			const sRawLoading = react.useState(false);
 			const rawLoading = sRawLoading[0], setRawLoading = sRawLoading[1];
+			// ── 注入调试（1.7.0）──
+			// 入口**只在 SAGE_MEM_DEBUG=1 时出现**：挂载时问宿主一次（enabled 由宿主每次现读
+			// 环境变量），关着就什么都不显示、抽屉里也不多一项。
+			const sDbgOn = react.useState(false);
+			const dbgOn = sDbgOn[0], setDbgOn = sDbgOn[1];
+			const sDbg = react.useState(null);
+			const dbg = sDbg[0], setDbg = sDbg[1];
+			const sDbgBusy = react.useState(false);
+			const dbgBusy = sDbgBusy[0], setDbgBusy = sDbgBusy[1];
 			// renderSlot：shell 会经 props 传进来（见 80-apply 的 children 声明），
 			// 但本插件改用并列 tab 渲染星图，不再调用它 —— 声明保留给 shell，这里不取。
 
@@ -4086,6 +4219,9 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				// 头部带的两个徽标要有数据才立得住：体检（只读扫描）与待重启项。
 				runAudit();
 				loadSettings();
+				// 1.7.0：只读问一次「调试开关开着吗」—— 关着时抽屉里不会多出「注入调试」。
+				// 这是唯一一处为调试视图多付的调用（一次本地只读 remote，不碰磁盘）。
+				loadRecallDebug();
 				/**
 				 * 更新检查：**静默**跑，失败一律不打扰 ——
 				 * 网络不通、被 GitHub 限流、仓库还没建 release，都不该在面板上冒一条红。
@@ -4112,7 +4248,26 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			react.useEffect(function () {
 				if (!drawer) return undefined;
 				if (typeof document === "undefined" || !document.addEventListener) return undefined;
-				function onOutside() { setDrawer(false); }
+				/**
+				 * ⚠️ **必须放过「抽屉内部」的点击**（2026-10-24 真机实测的 bug）。
+				 *
+				 * 打开抽屉的那一次点击，会在这个 effect 挂上监听之后**继续冒泡到 document**。
+				 * DevTools 里记到的顺序：`DOC:工具 ▾@911408 → 弹层 ADD@911410 → REMOVE@911412`
+				 * —— 弹层活了 2 毫秒就关掉自己，按钮连变色都来不及，用户看到的是
+				 * 「点了完全没反应」。
+				 *
+				 * 为什么测试没抓到：测试点按钮是直接调 `onClick`，不经过真实的事件冒泡，
+				 * 所以「同一次点击既开又关」这条路径在假环境里根本不存在。
+				 *
+				 * 判据用 `closest("[data-smem-drawer]")` 而不是比 DOM 引用：按钮与弹层条目
+				 * 都在带这个属性的 span 里，text / svg 子节点也照样命中；也不依赖事件对象
+				 * 上别的字段（测试喂一个只有 closest 的 target 就能复现）。
+				 */
+				function onOutside(e) {
+					const t = e && e.target;
+					if (t && typeof t.closest === "function" && t.closest("[data-smem-drawer]")) return;
+					setDrawer(false);
+				}
 				function onKey(e) { if (e && (e.key === "Escape" || e.keyCode === 27)) setDrawer(false); }
 				document.addEventListener("click", onOutside);
 				document.addEventListener("keydown", onKey);
@@ -4456,6 +4611,27 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 					.catch(function (e) { setError(String((e && e.message) || e)); });
 			}
 
+			/**
+			 * 拉一次注入调试账（1.7.0）。
+			 *
+			 * 返回值同时决定入口出不出现：`enabled === false` 时「工具」抽屉里不渲染
+			 * 「注入调试」这一项 —— 这是路线图「关掉调试开关时界面不出现」的落地方式。
+			 *
+			 * 旧宿主没有 recallDebug → 什么都不做、不报错（与 openMemoryDir / readRaw 同一套降级）。
+			 */
+			function loadRecallDebug() {
+				if (!remote || typeof remote.recallDebug !== "function") return;
+				setDbgBusy(true);
+				remote.recallDebug()
+					.then(function (r) {
+						const d = unwrap(r) || {};
+						setDbgOn(d.enabled === true);
+						setDbg(d);
+					})
+					.catch(function () { setDbgOn(false); })
+					.then(function () { setDbgBusy(false); });
+			}
+
 			/**
 			 * 打开 / 收起一个工具面板。数据只在第一次打开时拉；已经拉过就复用
 			 * （「刷新」「重新体检」是显式动作，别替用户反复扫目录）。
@@ -4466,6 +4642,8 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				setError(null);
 				if (next === "candidates" && !cand) loadCandidates();
 				if (next === "raw" && !settings) loadSettings();
+				// 调试账每次都重新取：它记的是「最近几次」，多一步就多一条 —— 缓存没有意义。
+				if (next === "debug") loadRecallDebug();
 			}
 
 			/**
@@ -4729,13 +4907,15 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				tab === "files" ? h("div", { className: "smem-toolbar", key: "bar" }, [
 					h("input", { className: "smem-search", key: "q", value: query, placeholder: "搜索文件名 / 描述 / 类型 / 标签…", onChange: function (e) { setQuery(e.target.value); } }),
 					// 工具抽屉：关着时这里只有一个按钮，零占位；面板一次只开一个。
-					h("span", { className: "smem-drawer", key: "drawer" }, [
+					// `data-smem-drawer` 是「点外部关闭」的排除标记：这一整块里的点击
+					// 都算「抽屉内部」，包括开抽屉的那一次点击本身（见上面 effect 的长注释）。
+					h("span", { className: "smem-drawer", key: "drawer", "data-smem-drawer": "1" }, [
 						h("button", {
 							type: "button", key: "btn",
 							className: "smem-btn" + (drawer ? " smem-btn-primary" : ""),
 							"aria-expanded": drawer ? "true" : "false",
 							"aria-haspopup": "menu",
-							title: "归档候选 / 保留名编辑",
+							title: "归档候选 / 保留名编辑" + (dbgOn ? " / 注入调试" : ""),
 							onClick: function () { setDrawer(!drawer); },
 						}, "工具 ▾"),
 						drawer ? h("div", { className: "smem-drawer-pop", key: "pop" }, [
@@ -4750,6 +4930,12 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 								"data-on": tool === "raw" ? "1" : "0",
 								onClick: function () { toggleTool("raw"); setDrawer(false); },
 							}, ["保留名编辑", h("span", { className: "smem-status", key: "s" }, settings && settings.reserved ? (settings.reserved.length + " 个") : "")]),
+							// 1.7.0：只在调试开关打开时出现（关着时抽屉仍是两项，界面零变化）
+							dbgOn ? h("button", {
+								type: "button", className: "smem-drawer-item", key: "d",
+								"data-on": tool === "debug" ? "1" : "0",
+								onClick: function () { toggleTool("debug"); setDrawer(false); },
+							}, ["注入调试", h("span", { className: "smem-status", key: "s" }, dbg && Array.isArray(dbg.records) ? (dbg.records.length + " 次") : "")]) : null,
 						]) : null,
 					]),
 				]) : null,
@@ -4801,6 +4987,16 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 							onClose: function () { setRawName(null); setRawText(""); setRawIsNew(false); },
 						})
 					: null,
+				// 1.7.0：注入调试。只读面板；数据在打开那一刻现取（最近 8 次），
+				// 「刷新」是显式动作 —— 与体检 / 候选同一条交互约定。
+				tab === "files" && tool === "debug"
+					? h(RecallDebugPanel, {
+							data: dbg,
+							busy: dbgBusy,
+							onReload: loadRecallDebug,
+							onClose: function () { setTool(null); },
+						})
+					: null,
 				// 三排筛选：状态 / 类型 / 标签。组内 OR、组间 AND，再与搜索框 AND。
 				tab === "files" && totalCount
 					? h(FilterBar, {

package/lib/index.js

@@ -33,7 +33,7 @@ import { mkdir, unlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { checkUpdate as checkUpdateImpl } from './update.js'
 import { autodreamConfigSnapshot, clampInt, MAX_RAW_BYTES, pendingLimits, rawName, readReservedFile, readSettingsFile, RESERVED_FILE, SETTINGS_FILE } from './settings.js'
-import { createRecallInjector, createSessionInjectState } from './recall/index.js'
+import { createRecallInjector, createSessionInjectState, readRecallDebug } from './recall/index.js'
 import { mountAutodream, mountMemoryTools, mountObserve, mountWriteGate } from './assembly/index.js'
 
 /**
@@ -92,6 +92,17 @@ export class MemoryGateway extends TypertRemoteService {
     return await checkUpdateImpl()
   }
 
+  /**
+   * 最近几次注入尝试的账（1.7.0 面板「工具 → 注入调试」的唯一数据源）。
+   *
+   * **只读、不落盘**：数据是注入链在 `SAGE_MEM_DEBUG=1` 时记进进程内存的环形缓冲
+   * （见 `lib/recall/debug.js`）；开关关着时返回 `{ enabled: false, records: [] }`，
+   * 面板据此不显示入口。不提供「清空 / 修改」能力 —— 一份账记下来就是那一刻的事实。
+   */
+  async recallDebug() {
+    return readRecallDebug()
+  }
+
   /** 列出 memory 目录全部记忆文件（文件名 + 类型 + 描述 + 大小 + 自定义标签 + 是否锁定）。 */
   async listFiles() {
     const [files, locked] = await Promise.all([scanMemoryFiles(this.ctx, ''), readLockSet(MEMORY_DIR)])
@@ -577,6 +588,8 @@ markRemote(MemoryGateway, 'getSettings', 'getSettings')
 markRemote(MemoryGateway, 'setSettings', 'setSettings')
 markRemote(MemoryGateway, 'readRaw', 'readRaw')
 markRemote(MemoryGateway, 'writeRaw', 'writeRaw')
+// 1.7.0：注入调试账（只读；开关关着时返回 { enabled: false, records: [] }）
+markRemote(MemoryGateway, 'recallDebug', 'recallDebug')
 
 /**
  * 记忆星图（宿主侧）—— 只读扫描记忆目录，把每条记忆解析成一颗「星」。

package/lib/memory/open-folder.js

@@ -10,6 +10,11 @@
  * 进程是**一次性、detached** 的：不等待退出（Explorer / Finder 是常驻进程，等它等于
  * 永不返回），也不持有 stdio。这条路径不改变插件「无 worker / 无端口 / 无常驻进程」的性质。
  *
+ * ⚠️ **绝对不要传 `windowsHide: true`**（2026-10-24 实测，A/B 对照）：它在 Windows 上
+ * 映射成 CREATE_NO_WINDOW，而 `explorer.exe` 是 GUI 进程 —— 传了之后进程起来了、
+ * 退出码也正常，**但那个文件夹窗口被藏起来**，用户体验就是「点了没反应」。去掉它，
+ * 同一份代码窗口正常弹出。原先那句「Windows 不闪窗」是错的：explorer 本来就没有控制台窗口。
+ *
  * 返回 `{ ok, error? }`，不抛：设置页按 ok 显示错误。`spawn` 的 'error' 事件是异步的，
  * 调用方拿不到，所以这里只挂一个空处理器，避免「命令不存在」变成未捕获异常 ——
  * 返回值表达的是「已发起」，不是「窗口已经出现」。
@@ -47,7 +52,9 @@ export function openMemoryFolder(dir, options = {}) {
   }
 
   try {
-    const child = spawnImpl(plan.command, plan.args, { detached: true, stdio: 'ignore', windowsHide: true })
+    // 注意：**没有 windowsHide**。它是 Windows 上「文件夹窗口不出现」的元凶（见文末头注）；
+    // `stdio: 'ignore'` 已经保证了不持有管道、不弹控制台。
+    const child = spawnImpl(plan.command, plan.args, { detached: true, stdio: 'ignore' })
     child.on?.('error', () => {})
     child.unref?.()
     return { ok: true }

package/lib/recall/debug.js

@@ -1,18 +1,34 @@
 /**
- * 注入链的调试出口（1.2.0 从 `lib/index.js` 原样搬出）。
+ * 注入链的调试出口（1.2.0 从 `lib/index.js` 原样搬出；1.7.0 起兼作面板的数据源）。
  *
- * `SAGE_MEM_DEBUG=1` 才出声的一行结构化 JSON：候选数 / 命中数 / 逐条得分 /
- * 入选与真注入的文件名 / 注入字符数 / 被会话预算挡掉几条。它回答的是
- * 「这条记忆为什么没被召回」——一个光看上下文永远查不出的问题。
+ * `SAGE_MEM_DEBUG=1` 才出声的一行结构化 JSON，并把同一份 payload 记进进程内的
+ * 环形缓冲，供面板「工具 → 注入调试」读。它回答的是「这条记忆为什么没被召回」
+ * ——一个光看上下文永远查不出的问题。
  *
- * ⚠️ **不开时零输出、零额外开销**：每个调用点都先 `if (debugEnabled())`，
- * 不成立时连 payload 对象都不会被构造出来。
+ * ⚠️ **不开时零输出、零开销**：每个调用点都先 `if (debugEnabled())`，
+ * 不成立时连 payload 对象都不会被构造出来，更不会进缓冲。
+ *
+ * ⚠️ **绝不落盘**：缓冲只在进程内存里（最多 `MAX_DEBUG_RECORDS` 条），重启即空。
+ * 调试信息不是记忆，不该写进用户的记忆目录或状态目录 —— 1.7.0 的验收里有一条
+ * 「跑完注入后记忆目录/状态目录逐字节不变」在盯着这件事。
  *
  * 为什么开关是**每次现读**而不是模块级常量：原来是常量，靠「测试里用 query 重载
  * `lib/index.js` 重新求值」来切换；1.2.0 把它拆成独立模块后，重载 index.js 不会重载
  * 它，常量就永远停在旧值（`test/access-test.mjs` 第 4 组当场变红）。现读一次环境变量
  * 的成本可以忽略，而它换来了「运行时也能打开调试」这个更诚实的行为。
  */
+
+/** 面板里最多看几次注入尝试。每步 assemble 都会尝试一次，8 条约等于一轮多步。 */
+export const MAX_DEBUG_RECORDS = 8
+
+/**
+ * 最近几次注入尝试（**旧 → 新**）。
+ *
+ * 模块级单例：一个进程一个插件事例，环形缓冲天然是全局的。记录里带 sessionId，
+ * 多会话混在一起时面板按时间倒序展示。
+ */
+const records = []
+
 export function debugEnabled() {
   return process.env.SAGE_MEM_DEBUG === '1'
 }
@@ -21,3 +37,36 @@ export function debugRecall(payload) {
   if (!debugEnabled()) return
   console.log(`[sage-mem] recall ${JSON.stringify(payload)}`)
 }
+
+/**
+ * 记一次注入尝试（调用点已确认 `debugEnabled()` 成立）。
+ *
+ * ⚠️ 存**副本**：payload 里的数组是现构造的，但调用方之后若再改它们，
+ * 面板读到的就不该跟着变 —— 一份账记下来就是那一刻的事实。
+ */
+export function recordInjection(payload) {
+  records.push(JSON.parse(JSON.stringify(payload)))
+  if (records.length > MAX_DEBUG_RECORDS) {
+    records.splice(0, records.length - MAX_DEBUG_RECORDS)
+  }
+}
+
+/**
+ * 面板读口：`{ enabled, records }`，**最新在前**。
+ *
+ * 关着开关时也返回 `{ enabled: false, records: [] }`（缓冲里本来就不该有东西）；
+ * 面板据此决定「工具」抽屉里出不出现「注入调试」这一项。
+ */
+export function readRecallDebug() {
+  // 深拷贝：调用方（面板 / 测试）拿到的必须是一份**独立的账** —— 改它不该改到内部
+  // 缓冲（浅拷贝只拷数组，记录对象还是同一批引用，`records[0].query = …` 会污染）。
+  return {
+    enabled: debugEnabled(),
+    records: records.slice().reverse().map((r) => JSON.parse(JSON.stringify(r))),
+  }
+}
+
+/** 测试专用：清空缓冲（跨用例隔离；生产路径没有任何地方调它）。 */
+export function resetRecallDebug() {
+  records.length = 0
+}

package/lib/recall/index.js

@@ -12,4 +12,4 @@ export { createRecallInjector } from './injector.js'
 export { dedupeByFile, selectRecall } from './select.js'
 export { buildCandidates, composeDelivery, composeStatus } from './compose.js'
 export { composeRecallText } from './text.js'
-export { debugEnabled, debugRecall } from './debug.js'
+export { debugEnabled, debugRecall, readRecallDebug } from './debug.js'

package/lib/recall/injector.js

@@ -19,10 +19,10 @@ import { extractText } from '../memory/retrieval.js'
 import { scanMemoryFiles } from '../memory/scan.js'
 import { readCheckpoint } from '../memory/checkpoint.js'
 import { warnLog } from '../memory/util.js'
-import { selectRecall } from './select.js'
+import { selectRecall, dedupeByFile } from './select.js'
 import { buildCandidates, composeDelivery, composeStatus } from './compose.js'
 import { composeRecallText } from './text.js'
-import { debugEnabled, debugRecall } from './debug.js'
+import { debugEnabled, debugRecall, recordInjection } from './debug.js'
 
 /**
  * @param {object} deps
@@ -116,16 +116,49 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
       })
       const { cardBody, cardPart } = status
 
+      // ── 调试账（1.7.0）────────────────────────────────────────────────
+      // 控制台一行 JSON 与面板「工具 → 注入调试」共用这一份 payload。
+      // **只在开关打开时才构造 payload**：关着的时候 makeDebug 返回 null，payload
+      // 与缓冲记录都不会被建出来（零开销）；debugEnabled() 每次现读，与 debug.js 同一条。
+      //
+      // 口径（面板上照此措辞，别让人误读）：
+      //   - `chars` = **这一步**真进正文的字节（不含状态卡、不含历史累计）；
+      //   - `sessionChars` = 本代累计正文字节（预算账）；
+      //   - `cardChars` = 这一步发出去的状态卡字节（没发就是 0）；
+      //   - `deduped` = 同题同命中集刚注过，这一步没重复追加 —— 面板上要解释成
+      //     「不是坏了，是去重生效」，否则每轮多步里大部分账看着都是空的。
+      const debugOn = debugEnabled()
+      const makeDebug = debugOn
+        ? (outcome) => ({
+            at: nowMs,
+            sessionId,
+            query: typeof text === 'string' ? text.slice(0, 160) : '',
+            outcome,
+            deduped,
+            baseline: baselineTaken,
+            scanned: files.length,
+            hits: relevant.length,
+            scores: relevant.map(f => ({ file: f.file, score: Number(f.score.toFixed(4)) })),
+            body: dedupeByFile(bodyRanked).slice(0, 5).map(h => ({ file: h.file, score: Number((h.score ?? 0).toFixed(4)) })),
+            picked: picked.map(f => f.file),
+            injected: injectedFiles,
+            chars: Math.max(0, contentBytes - st.contentBytes),
+            sessionChars: contentBytes,
+            cardChars: cardPart ? Buffer.byteLength(cardPart, 'utf8') : 0,
+            skippedByBudget: skippedForBudget,
+            card: cardPart ? 'sent' : (status.cardText ? 'deduped-or-over-budget' : 'none'),
+          })
+        : () => null
+      const emitDebug = (payload) => {
+        if (!payload) return
+        debugRecall(payload)
+        recordInjection(payload)
+      }
+
       // 正文与卡都没有 → 一个字都不注。注意这与旧行为不同：旧行为「正文池满」就到此为止，
       // 现在只要卡池还有额度就会发出卡（说清范围、缺口与下一步动作）。
       if (parts.length === 0 && !cardPart) {
-        if (debugEnabled()) {
-          debugRecall({
-            scanned: files.length, hits: relevant.length,
-            scores: relevant.map(f => [f.file, Number(f.score.toFixed(4))]),
-            picked: picked.map(f => f.file), injected: [], chars: contentBytes, skippedByBudget: skippedForBudget,
-          })
-        }
+        emitDebug(makeDebug('empty'))
         return assembled
       }
 
@@ -142,18 +175,7 @@ export function createRecallInjector({ ctx, state, tools, taskIdOf }) {
         baselineDone: st.baselineDone || baselineTaken > 0,
       })
 
-      if (debugEnabled()) {
-        debugRecall({
-          scanned: files.length,
-          hits: relevant.length,
-          scores: relevant.map(f => [f.file, Number(f.score.toFixed(4))]),
-          picked: picked.map(f => f.file),
-          injected: injectedFiles,
-          chars: contentBytes,
-          skippedByBudget: skippedForBudget,
-          card: cardPart ? 'sent' : (status.cardText ? 'deduped-or-over-budget' : 'none'),
-        })
-      }
+      emitDebug(makeDebug(parts.length > 0 ? 'injected' : 'card-only'))
 
       const recallText = composeRecallText({
         parts,

package/lib/typert.host.js

@@ -264,6 +264,27 @@ const rawWriteResultSchema = z.object({
 // fileContentSchema，别把两者混用。
 const rawFileContentSchema = z.string().max(MAX_RAW_BYTES)
 
+// ── 注入调试账（1.7.0）─────────────────────────────────────────────────────
+// 这份形状就是 `lib/recall/debug.js` 里 payload 的**逐字段**镜像。strict 会剥掉
+// 未声明的字段，所以面板要看的每一样都必须写在这里 —— 少写一个，界面上就是
+// 一个永远 undefined 的格子（与 R01 漏四个配置字段同一类错误）。
+// 写法比相邻 schema 紧凑（一行多字段）：本文件已有 ≤900 行的结构守卫
+// （test/structure-test.mjs），加一条 remote 不能把文件顶爆。
+const recallDebugScoreSchema = z.object({ 'file': z.string().readonly(), 'score': z.number().readonly() }).readonly()
+const recallDebugRecordSchema = z.object({
+	'at': z.number().readonly(), 'sessionId': z.string().readonly(), 'query': z.string().readonly(),
+	// injected | card-only | empty：这一步到底注进去了什么
+	'outcome': z.string().readonly(), 'deduped': z.boolean().readonly(), 'baseline': z.number().readonly(),
+	'scanned': z.number().readonly(), 'hits': z.number().readonly(),
+	'scores': z.array(recallDebugScoreSchema).readonly(), 'body': z.array(recallDebugScoreSchema).readonly(),
+	'picked': z.array(z.string()).readonly(), 'injected': z.array(z.string()).readonly(),
+	// chars = 这一步正文；sessionChars = 本代累计；cardChars = 这一步的卡
+	'chars': z.number().readonly(), 'sessionChars': z.number().readonly(), 'cardChars': z.number().readonly(),
+	'skippedByBudget': z.number().readonly(), 'card': z.string().readonly(),
+}).readonly()
+// 开关关着时 records 是空数组、enabled 是 false —— 面板据此不显示入口。
+const recallDebugResultSchema = z.object({ 'enabled': z.boolean().readonly(), 'records': z.array(recallDebugRecordSchema).readonly() }).readonly()
+
 // ── autodream（夜间记忆整理）───────────────────────────────────────────────
 // 配置的每一项都可写；lastResult 是一个「成功/失败两条分支共用」的结构，
 // 所以除了三个必有字段外全是 optional —— 用 strict 校验两种形态的并集，
@@ -716,6 +737,17 @@ export const TYPERT = {
 			result: { mode: 'strict', typeSymbol: 'sage-mem/types#RawWriteResult', schema: rawWriteResultSchema, create: () => rawWriteResultSchema },
 			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
 		},
+		{
+			// 1.7.0：最近几次注入的账（只读；关着 SAGE_MEM_DEBUG 时 enabled=false）。
+			id: 'sage-mem#memory/recallDebug',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'recallDebug',
+			invocation: { kind: 'direct' },
+			parameters: [],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#RecallDebug', schema: recallDebugResultSchema, create: () => recallDebugResultSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
 		{
 			id: 'sage-mem#starmap/listStars',
 			service: 'starmap',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "1.6.4",
+  "version": "1.7.0",
   "type": "module",
   "main": "lib/index.js",
   "exports": {