sage-mem 2.1.20 → 2.1.22

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.20`** — 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: `2.1.22`** — 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.

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.
 
-**当前发布版本：`2.1.20`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.22`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/client.js

@@ -61,6 +61,148 @@ window.__ModuleLoader__.load({
 			return "rgba(" + ((n >> 16) & 255) + "," + ((n >> 8) & 255) + "," + (n & 255) + "," + a.toFixed(3) + ")";
 		}
 
+		// ── 陈旧宿主（2.1.22 / issue #10）────────────────────────────────
+		//
+		// `@deepseek-ai/dsh-typert-loader` 把每个包的 TYPERT manifest **按包名缓存、
+		// 进程内不失效**（它的头注原文：Package verdicts and imported manifests are
+		// cached per package name and never expire）。于是「开着 DSH 装上新版 sage-mem」
+		// 之后，宿主进程里仍然是升级前的 strict descriptor（2.1.1 的 writeFile 只有
+		// name/content 两个 wire 字段），而浏览器这边是从磁盘现取的新客户端分片 ——
+		// 第三参 opts 会在宿主**执行之前**被网关挡掉：
+		//
+		//   gateway/arguments-invalid: args fields do not match the descriptor:
+		//   unexpected "opts"
+		//
+		// 真正要清掉的是宿主进程里那份旧 manifest（彻底退出 DSH，含托盘常驻进程；
+		// 只关窗口不够）。但用户不该被卡在这里：写操作按旧协议降级重试。
+
+		/**
+		 * 只认「旧 strict descriptor 不认第三参」这一种结构化失败。
+		 *
+		 * ⚠️ 两种形态都要认（2026-11-01 真机抓到）：网关的失败既可能被**拒绝**（reject），
+		 * 也可能作为 remote 的**返回值** `{ok:false, error}` 回来 —— 后者是 api-gateway
+		 * 的 RemoteResult 语义，sage-mem 面板的其它写路径也一直在读 `r.ok === false`。
+		 * 只判 rejection 的话，真实环境里这条降级根本不会触发（第一版就踩了）。
+		 *
+		 * 判据同时看 code 与文案：同一个 `gateway/arguments-invalid` 也可能是在拒别的
+		 * 字段，甚至别的调用方传错参数 —— 那些都必须原样抛出，不能拿兼容降级去吞。
+		 * @returns 出问题的那个 error 对象，或 null。
+		 */
+		function staleHostWriteCause(value) {
+			const candidate = value && value.ok === false && value.error ? value.error : value;
+			if (!candidate) return null;
+			const code = typeof candidate.code === "string" ? candidate.code : "";
+			const message = String(candidate.message || candidate);
+			if (code !== "gateway/arguments-invalid" && !/gateway\/arguments-invalid/.test(message)) return null;
+			return /unexpected\s+["']?opts["']?/i.test(message) ? candidate : null;
+		}
+
+		/** 布尔版判据（面板/测试可读）。 */
+		function isStaleHostWriteError(value) {
+			return staleHostWriteCause(value) !== null;
+		}
+
+		/**
+		 * 只认「文件不存在」这一种读失败（宿主 readFile / readRaw 的 ENOENT 文案）。
+		 *
+		 * 陈旧宿主降级里的 create 探针必须用它：读失败也可能是权限 / IO 错误，
+		 * 那种情况下**不能**把目标当成「不存在」去覆盖写（2.1.10 / Q10 的教训）。
+		 */
+		function isNotFoundError(error) {
+			return /ENOENT|no such file|not exist/i.test(String((error && error.message) || error));
+		}
+
+		/**
+		 * 「目标是否已存在」探针（陈旧宿主创建降级用）。
+		 *
+		 * ⚠️ 两种返回形态都要认（2026-11-01 真机抓到）：宿主方法抛出的错误经 api-gateway
+		 * 可能变成**返回值** `{ok:false, error}`（RemoteResult 语义），也可能仍是 rejection。
+		 * 只处理 rejection 会把「文件不存在」误判成「已存在」—— 那会让新建永远报撞名。
+		 *
+		 * @returns Promise<boolean>：true=已存在；false=明确的 not-found；
+		 *          其它读失败（权限 / IO / 网关）抛出来，由调用方决定不降级。
+		 */
+		function probeRemoteExists(remote, method, arg) {
+			const call = new Promise(function (resolve) {
+				const fn = remote && remote[method];
+				if (typeof fn !== "function") throw new Error("sage-mem: host has no " + method);
+				resolve(fn.call(remote, arg));
+			});
+			const classify = function (error) {
+				if (isNotFoundError(error)) return false;
+				throw error;
+			};
+			return call.then(function (result) {
+				if (result && result.ok === false && result.error) return classify(result.error);
+				return true;
+			}, classify);
+		}
+
+		/**
+		 * 写调用 + 陈旧宿主降级。
+		 *
+		 * @param remote  宿主 remote 代理
+		 * @param method  写方法名（writeFile / writeRaw / writeArchived）
+		 * @param args    位置参数（不含 opts）
+		 * @param opts    写协议第三参；undefined 表示旧调用方，直接按旧协议写
+		 * @param probeExists 仅 create 语义用：探测目标是否已存在的函数（Promise<boolean>）。
+		 *       陈旧宿主没有 create 语义，**没有探针就不降级** —— 宁可这次写失败，也不拿走
+		 *       条件覆盖写去顶创建。
+		 * @returns Promise<{result, degraded}>；degraded=true 表示这次按旧协议写入，
+		 *          expectedRevision 的版本校验没有生效，界面必须把这件事告诉用户。
+		 */
+		function writeWithFallback(remote, method, args, opts, probeExists) {
+			function send(extraOpts) {
+				return new Promise(function (resolve) {
+					const fn = remote && remote[method];
+					if (typeof fn !== "function") throw new Error("sage-mem: host has no " + method);
+					// ⚠️ 第三个**位置参数**必须保留（哪怕值是 undefined）：客户端 remote 代理按
+					// 客户端描述符校验位置参数个数（三个写方法都声明了 3 个），少传一个会当场报
+					// 「client api: memory/writeFile expected 3 argument(s), got 2」—— 降级根本没
+					// 走到网关。undefined 在 JSON 里自然缺席，宿主旧接口只看到 name/content，
+					// 正好就是旧协议（2026-11-01 真机抓到）。
+					resolve(fn.apply(remote, args.concat([extraOpts])));
+				});
+			}
+			function degraded(result) { return { result: result, degraded: true }; }
+			/** 降级重试；返回 null 表示「这次不该降级」，由调用方把原始失败原样交出去。 */
+			function recover() {
+				if (opts && opts.create === true) {
+					// 降级不是无条件的：旧宿主没有 create 语义，先探一次存在性。
+					if (typeof probeExists !== "function") return null;
+					return Promise.resolve().then(probeExists).then(function (exists) {
+						if (exists) {
+							return degraded({
+								ok: false,
+								code: "already_exists",
+								error: t("error.staleHostExists", { file: String(args[0]) }),
+							});
+						}
+						return send(undefined).then(degraded);
+					});
+				}
+				return send(undefined).then(degraded);
+			}
+			if (opts === undefined) {
+				return send(undefined).then(function (result) { return { result: result, degraded: false }; });
+			}
+			function onStale(original) {
+				const recovered = recover();
+				if (recovered === null) throw staleHostWriteCause(original) || original;
+				return recovered;
+			}
+			return send(opts).then(
+				function (result) {
+					if (!isStaleHostWriteError(result)) return { result: result, degraded: false };
+					return onStale(result);
+				},
+				function (error) {
+					if (!isStaleHostWriteError(error)) throw error;
+					return onStale(error);
+				},
+			);
+		}
+
 		// ── 类型词表（唯一定义） ──
 		// 文件列表的排序 / 筛选 / 徽章、星图的 kind 标签与配色，全部从这里取。
 		const TYPE_ORDER = ["user", "feedback", "project", "reference"];
@@ -2808,6 +2950,20 @@ const StarmapRuntime = (function (require, _react) {
 			}, props.label);
 		}
 
+		/**
+		 * 活动卡片「展开态」的合并（Q16，2.1.21）。
+		 *
+		 * 为什么是个纯函数：连续点两张卡（或同一帧里点两次）时，事件回调手里那个
+		 * `expanded` 可能还是上一帧的快照 —— 拿快照拼新对象会把另一笔改动覆盖掉。
+		 * 所以 Section 走**函数式 setState**，把「怎么合并」收敛到这里：
+		 * 只翻转目标文件那一条，其余原样保留。测试也直接喂 prev 来验这条语义。
+		 */
+		function mergeExpanded(prev, file) {
+			const next = Object.assign({}, prev);
+			next[file] = !(prev && prev[file]);
+			return next;
+		}
+
 		function Card(props) {
 			const item = props.item;
 			const meta = TYPE_META[item.type] || TYPE_META.reference;
@@ -3874,11 +4030,13 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			"error.saveRejected": "保存被拒绝",
 			"error.skeletonFailed": "建立索引骨架失败",
 			"error.openDirFailed": "打开记忆目录失败",
+			"error.staleHostExists": "同名文件已经存在：{file} —— 宿主还停在升级前的 sage-mem（旧写协议没有 create 语义），已拒绝，没有覆盖它",
 			"notice.indexExists": "MEMORY.md 已经存在，没有改动它。",
 			"notice.indexCreated": "已建立 MEMORY.md 索引骨架。",
 			"notice.updated": "已更新 {file}",
 			"notice.saved": "已保存 {file}",
 			"notice.rawNew": "已新建 {file}",
+			"notice.staleHostWrite": "已按旧协议写入 {file} —— 宿主仍停着升级前的 sage-mem（DSH 没有完全退出），本次未做版本校验；彻底退出 DSH（含托盘）后重开即可恢复",
 			"notice.deleted": "已删除 {file}",
 			"notice.archived": "已归档 {file} —— 它现在在「已归档」视图里，随时可以恢复",
 			"notice.batchPartial": "已归档 {done} 条，{failed} 条没成功：{files}",
@@ -4355,11 +4513,13 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			"error.saveRejected": "Save rejected",
 			"error.skeletonFailed": "Failed to create the index skeleton",
 			"error.openDirFailed": "Failed to open the memory directory",
+			"error.staleHostExists": "A file with this name already exists: {file} — the host is still on the pre-upgrade sage-mem (the old write protocol has no create semantics), so it was refused and nothing was overwritten",
 			"notice.indexExists": "MEMORY.md already exists; it was left unchanged.",
 			"notice.indexCreated": "MEMORY.md index skeleton created.",
 			"notice.updated": "Updated {file}",
 			"notice.saved": "Saved {file}",
 			"notice.rawNew": "Created {file}",
+			"notice.staleHostWrite": "Wrote {file} with the legacy protocol — the host still runs the pre-upgrade sage-mem (DSH did not fully exit), so this write skipped the version check; fully quit DSH (including the tray) and reopen to restore",
 			"notice.deleted": "Deleted {file}",
 			"notice.archived": "Archived {file} — it is now under the Archived view and can be restored at any time",
 			"notice.batchPartial": "Archived {done}, {failed} failed: {files}",
@@ -5640,7 +5800,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 		// 只负责「按状态/筛选把卡片摆出来 + 四种空态」；状态、筛选语义、动作回调全部由 Section 传。
 		// 抽出的判据：它是 Section 里最大的一块纯渲染，而卡片组件（Card / ArchivedCard）本来就在 50 共享层。
 		function FilesView(props) {
-			const { loading, totalCount, openAdd, createIndexSkeleton, statusFilter, setStatusFilter, items, archiveItems, filtered, setTypeFilter, setTagFilter, setQuery, busy, restoring, archDelete, archEdit, archLoad, archSaving, archText, setArchText, openArchEdit, saveArchEdit, cancelArchEdit, restoreFile, setArchDelete, setArchEdit, deleteArchivedFile, expanded, deleting, archiving, archiveReason, setArchiveReason, setArchiving, setDeleting, confirmArchive, toggleLock, openEdit, confirmDelete } = props;
+			const { loading, totalCount, openAdd, createIndexSkeleton, statusFilter, setStatusFilter, items, archiveItems, filtered, setTypeFilter, setTagFilter, setQuery, busy, restoring, archDelete, archEdit, archLoad, archSaving, archText, setArchText, openArchEdit, saveArchEdit, cancelArchEdit, restoreFile, setArchDelete, setArchEdit, deleteArchivedFile, expanded, onToggleExpanded, deleting, archiving, archiveReason, setArchiveReason, setArchiving, setDeleting, confirmArchive, toggleLock, openEdit, confirmDelete } = props;
 			let filesView;
 			if (loading && totalCount === 0) {
 				filesView = h("div", { className: "smem-skeleton", key: "loading", "data-loading": "1" }, [0, 1, 2].map(function (i) {
@@ -5704,11 +5864,10 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 						onCancelArchive: function () { setArchiving(null); setArchiveReason(""); },
 						onConfirmArchive: confirmArchive,
 						onToggleLock: toggleLock,
-						onToggle: function (file) {
-							const nx = {};
-							nx[file] = !expanded[file];
-							setExpanded(Object.assign({}, expanded, nx));
-						},
+						// 展开 / 收起是**业务回调**（Q16）：卡片只上报「点了哪张」，
+						// 合并逻辑归 Section。旧版这里引用旧 Section 闭包里的 `setExpanded` ——
+						// 拆件后它不在本函数作用域，点击即 ReferenceError: setExpanded is not defined。
+						onToggle: onToggleExpanded,
 						onEdit: openEdit,
 						onAskDelete: function (file) { setDeleting(file); setArchiving(null); },
 						onCancelDelete: function () { setDeleting(null); },
@@ -5828,6 +5987,12 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			const query = sQuery[0], setQuery = sQuery[1];
 			const sExpanded = react.useState({});
 			const expanded = sExpanded[0], setExpanded = sExpanded[1];
+			// Q16：卡片「展开 / 收起」是业务回调（FilesView 只上报点了哪张卡）。
+			// 必须走**函数式** setState：事件里捕获的 expanded 可能是上一帧快照，
+			// 直接 Object.assign({}, expanded, …) 会把连续点击的上一笔改动覆盖掉。
+			function onToggleExpanded(file) {
+				setExpanded(function (prev) { return mergeExpanded(prev, file); });
+			}
 			const sDeleting = react.useState(null);
 			const deleting = sDeleting[0], setDeleting = sDeleting[1];
 			const sFormOpen = react.useState(false);
@@ -6110,12 +6275,18 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				// 服务端负责「全新安装、memory 目录还不存在」时先建父目录；
 				// 已有索引 → 明确回 already_exists（逐字节不动）。绝不再「先读一次、读失败就当
 				// 可以覆盖」—— 读失败也可能是权限错误，而那正是会顶掉一份真索引的路。
-				remote.writeRaw("MEMORY.md", INDEX_SKELETON, { create: true }).then(function (res) {
-					const out = unwrap(res);
+				// 2.1.22（issue #10）：陈旧宿主没有 create 语义，降级前先探一次存在性。
+				// 探针只认「明确的 not-found」；读失败（权限 / IO）一律不降级 —— 否则会把一份
+				// 读不到的真索引当成「不存在」顶掉（2.1.10 / Q10 的教训）。
+				const probeIndexExists = function () {
+					return probeRemoteExists(remote, "readRaw", "MEMORY.md");
+				};
+				writeWithFallback(remote, "writeRaw", ["MEMORY.md", INDEX_SKELETON], { create: true }, probeIndexExists).then(function (out) {
+					const res = unwrap(out.result);
 					setBusy(false);
-					if (out && out.code === "already_exists") { setNotice(t("notice.indexExists")); return; }
-					if (out && out.ok === false) { setError(out.error || t("error.skeletonFailed")); return; }
-					setNotice(t("notice.indexCreated"));
+					if (res && res.code === "already_exists") { setNotice(t("notice.indexExists")); return; }
+					if (res && res.ok === false) { setError(res.error || t("error.skeletonFailed")); return; }
+					setNotice(out.degraded ? t("notice.staleHostWrite", { file: "MEMORY.md" }) : t("notice.indexCreated"));
 					load();
 				}).catch(function (e) {
 					setBusy(false);
@@ -6206,17 +6377,26 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				}
 				// 2.1.2（Q02）：编辑已有文件时交回读到的 revision（盘上变了 → 宿主拒绝）；
 				// 新建走 createIfAbsent —— 撞上同名文件是**明确报已存在**，绝不覆盖入口。
+				const wasEditing = Boolean(editingFile);
 				const writeOpts = editingFile
 					? (formRevision ? { expectedRevision: formRevision } : undefined)
 					: { create: true };
-				remote.writeFile(safeName, content, writeOpts)
-					.then(function (r) {
+				// 2.1.22（issue #10）：宿主若还停在升级前的旧 manifest，先按旧协议降级一次；
+				// 新建语义在旧宿主上没有对应参数，降级前必须探存在性（绝不覆盖已有文件）。
+				const probeTarget = wasEditing ? null : function () {
+					return probeRemoteExists(remote, "readFile", safeName);
+				};
+				writeWithFallback(remote, "writeFile", [safeName, content], writeOpts, probeTarget)
+					.then(function (out) {
 						// host 侧对保留名 / 非字符串内容 / 超限一律返回 { ok: false, error }，不再抛异常。
 						// 冲突看**结构化 code**（stale_revision / already_exists），不解析文案：
 						// 编辑框不关、草稿原地保留，由用户看过最新内容后自己决定重新应用 —— 绝不自动重试覆盖。
+						const r = out.result;
 						if (r && r.ok === false) { setError(r.error || t("error.writeRejected")); return; }
 						closeForm();
-						setNotice(t(editingFile ? "notice.updated" : "notice.saved", { file: safeName }));
+						setNotice(out.degraded
+							? t("notice.staleHostWrite", { file: safeName })
+							: t(wasEditing ? "notice.updated" : "notice.saved", { file: safeName }));
 						load();
 					})
 					.catch(function (e) { setError(String((e && e.message) || e)); })
@@ -6375,12 +6555,16 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				// 原样交回：不 trim、不补 frontmatter、不做任何「智能」处理。
 				// 2.1.2（Q02）：带上读到的 revision；归档件在别处被改过 → 宿主回 stale_revision，
 				// 编辑框与文本原地保留（不自动重试覆盖）。
+				// 2.1.22（issue #10）：陈旧宿主按旧协议降级（没有 create 语义，这里本来也没有）。
 				const writeOpts = archRevision ? { expectedRevision: archRevision } : undefined;
-				remote.writeArchived(file, archText, writeOpts)
-					.then(function (r) {
+				writeWithFallback(remote, "writeArchived", [file, archText], writeOpts)
+					.then(function (out) {
+						const r = out.result;
 						if (r && r.ok === false) { setError(r.error || t("error.saveRejected")); return; }
 						setArchEdit(null);
-						setNotice(t("notice.saved", { file: file }));
+						setNotice(out.degraded
+							? t("notice.staleHostWrite", { file: file })
+							: t("notice.saved", { file: file }));
 						load();
 					})
 					.catch(function (e) { setError(String((e && e.message) || e)); })
@@ -6733,13 +6917,21 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				// 原样交回：不 trim、不补 frontmatter、不做任何「智能」处理。
 				// 2.1.2（Q02）：新建走 createIfAbsent（撞名明确失败、不覆盖）；编辑带读到的 revision
 				// （盘上变了 → stale_revision，文本原地保留，绝不自动重试覆盖）。
+				// 2.1.22（issue #10）：陈旧宿主按旧协议降级；新建语义要先探存在性，绝不覆盖。
+				const wasNew = Boolean(rawIsNew);
 				const writeOpts = rawIsNew
 					? { create: true }
 					: (rawRevision ? { expectedRevision: rawRevision } : undefined);
-				remote.writeRaw(name, rawText, writeOpts)
-					.then(function (r) {
+				const probeRaw = wasNew ? function () {
+					return probeRemoteExists(remote, "readRaw", name);
+				} : null;
+				writeWithFallback(remote, "writeRaw", [name, rawText], writeOpts, probeRaw)
+					.then(function (out) {
+						const r = out.result;
 						if (r && r.ok === false) { setError(r.error || t("error.saveRejected")); return; }
-						setNotice(t(rawIsNew ? "notice.rawNew" : "notice.saved", { file: name }));
+						setNotice(out.degraded
+							? t("notice.staleHostWrite", { file: name })
+							: t(wasNew ? "notice.rawNew" : "notice.saved", { file: name }));
 						setRawIsNew(false);
 						// 保存成功后把版本换成刚写下的那一版，连续保存不用重读
 						if (r && typeof r.revision === "string") setRawRevision(r.revision);
@@ -6840,7 +7032,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				archText: archText, setArchText: setArchText,
 				openArchEdit: openArchEdit, saveArchEdit: saveArchEdit, cancelArchEdit: cancelArchEdit,
 				restoreFile: restoreFile, setArchDelete: setArchDelete, setArchEdit: setArchEdit, deleteArchivedFile: deleteArchivedFile,
-				expanded: expanded, deleting: deleting, archiving: archiving,
+				expanded: expanded, onToggleExpanded: onToggleExpanded, deleting: deleting, archiving: archiving,
 				archiveReason: archiveReason, setArchiveReason: setArchiveReason,
 				setArchiving: setArchiving, setDeleting: setDeleting,
 				confirmArchive: confirmArchive, toggleLock: toggleLock,

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": "2.1.20",
+  "version": "2.1.22",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",