sage-mem 1.5.3 → 1.6.1

package/README.md

@@ -80,6 +80,15 @@ Most memory schemes take the "SQLite + a long-running worker" route: once memori
 
 The UI also carries four more capabilities (all of them optional): the memory management page, type and tag filtering, the memory star map, and audit & archiving.
 
+The memory management page's file list also has an **Open memory folder** button: it opens the
+memory directory in the system file manager (Explorer / Finder / the Linux file manager) through a
+detached host-side process and returns without waiting for the window.
+
+While the memory directory is empty, the empty state carries a **Create index skeleton** button: one
+click writes a starter `MEMORY.md` (index format plus the four memory categories). When `MEMORY.md`
+already exists it only says so and changes nothing; it uses the existing reserved-file read/write
+calls rather than a new remote.
+
 ## Quick Start
 
 Requires **DSH `0.1.2-rc.1` or higher** (see [Compatibility](#compatibility)) and **Node.js `>= 18`**.

package/README.zh.md

@@ -82,6 +82,13 @@ sage-mem 补上这一层，做法是：**把该记住的事写成一张张卡片
 
 界面上还有四块能力（都可以不用）：记忆管理页、类型与标签筛选、记忆星图、体检与归档。
 
+记忆管理页的「文件列表」头部还有一个「打开记忆文件夹」按钮：用系统文件管理器打开当前记忆目录
+（Windows Explorer / macOS Finder / Linux 文件管理器）。host 侧起一个 detached 进程就返回，不等窗口。
+
+记忆目录还是空的时候，空态里有一个「建立索引骨架」按钮：一键写入 `MEMORY.md` 的引导文件
+（索引格式 + 四类记忆说明）。**已经存在 `MEMORY.md` 时只提示、不覆盖**；它不走新的 remote，
+用的是原有的保留名读取 / 写入接口。
+
 ## 快速开始
 
 需要 **DSH `0.1.2-rc.1` 或更高**（见[兼容性](#兼容性)）、**Node.js `>= 18`**。

package/lib/client.js

@@ -1727,6 +1727,16 @@ const StarmapRuntime = (function (require, _react) {
 					result: { mode: "strict", typeSymbol: "sage-mem/types#AuditReport", schema: objCodec, create: () => objCodec },
 					sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
 				},
+				{
+					id: "sage-mem#memory/openMemoryDir",
+					service: "memory",
+					namespace: "memory",
+					method: "openMemoryDir",
+					invocation: { kind: "direct" },
+					parameters: [],
+					result: { mode: "strict", typeSymbol: "sage-mem/types#OpenFolderResult", schema: objCodec, create: () => objCodec },
+					sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+				},
 				{
 					id: "sage-mem#memory/checkUpdate",
 					service: "memory",
@@ -2174,7 +2184,7 @@ const StarmapRuntime = (function (require, _react) {
 			".smem-empty{display:flex;flex-direction:column;align-items:flex-start;gap:8px;}",
 			".smem-tabs-sep{width:1px;align-self:stretch;margin:6px 2px;background:var(--dsw-alias-border-l2);}",
 			// 窄窗口（≤420px）：头部带与筛选条各让一行，卡片动作允许换行、分隔符隐藏。
-			"@media (max-width:420px){.smem-root{gap:10px;}.smem-head{gap:6px;}.smem-card-title{min-width:0;word-break:break-word;}.smem-actions{flex-wrap:wrap;}.smem-actions-sep{display:none;}.smem-num{width:56px;}.smem-search{min-width:100px;}}",
+			"@media (max-width:420px){.smem-root{gap:10px;}.smem-head{gap:6px;}.smem-head-actions{flex-wrap:wrap;}.smem-card-title{min-width:0;word-break:break-word;}.smem-actions{flex-wrap:wrap;}.smem-actions-sep{display:none;}.smem-num{width:56px;}.smem-search{min-width:100px;}}",
 			// ── 底部一行仓库链接（引流，不抢视线）──
 			".smem-star{display:flex;align-items:center;justify-content:flex-end;gap:8px;flex-wrap:wrap;font-size:12px;color:var(--dsw-alias-label-tertiary,#8b93a1);padding:2px 2px 0;}",
 			".smem-star-link{color:var(--dsw-alias-brand-primary,#4d76e6);text-decoration:underline;}",
@@ -3745,7 +3755,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 		// 只负责「按状态/筛选把卡片摆出来 + 四种空态」；状态、筛选语义、动作回调全部由 Section 传。
 		// 抽出的判据：它是 Section 里最大的一块纯渲染，而卡片组件（Card / ArchivedCard）本来就在 50 共享层。
 		function FilesView(props) {
-			const { loading, totalCount, openAdd, 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, 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) {
@@ -3755,6 +3765,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				filesView = h("div", { className: "smem-empty", key: "empty" }, [
 					h("div", { key: "t" }, "还没有记忆文件。对话中值得记住的事会写到这里，也可以手动写入。"),
 					h("button", { type: "button", className: "smem-btn smem-btn-primary", key: "add", onClick: openAdd }, "+ 添加记忆"),
+					h("button", { type: "button", className: "smem-btn", key: "idx", title: "写入一份 MEMORY.md 索引骨架（已有索引不会覆盖）", onClick: createIndexSkeleton }, "建立索引骨架"),
 				]);
 			} else if (statusFilter === "archived" && archiveItems.length === 0) {
 				filesView = h("div", { className: "smem-empty", key: "empty" }, [
@@ -4116,6 +4127,67 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				setFormFm(null); setFormBaseType(""); setFormTags("");
 			}
 
+			// 空记忆库时「建立索引骨架」写进去的引导文件。它只是给人看的起点：
+			// 索引本来就是手写维护的，这里不猜用户有什么记忆、也不生成假条目。
+			const INDEX_SKELETON = [
+				"# 记忆索引",
+				"",
+				"> 这是 sage-mem 的记忆索引骨架：每条记忆一行，链接到同目录下的一个 Markdown 文件。",
+				"> 索引由人（或 agent）手写维护，不是自动生成的；改写前建议先备份。",
+				"",
+				"## 活动记忆",
+				"",
+				"<!-- 一条记忆一行：「- [标题](文件名.md) — 一句话描述」 -->",
+				"",
+				"## 四类记忆",
+				"",
+				"- `user_*`：关于用户的事实与偏好",
+				"- `feedback_*`：用户给的工作方式指导",
+				"- `project_*`：进行中的工作与状态",
+				"- `reference_*`：外部信息在哪找",
+				"",
+			].join("\n");
+
+			function createIndexSkeleton() {
+				setError(null);
+				setNotice("");
+				if (!remote || typeof remote.readRaw !== "function" || typeof remote.writeRaw !== "function") {
+					setError("宿主侧还没有 readRaw / writeRaw 接口（插件版本较旧）");
+					return;
+				}
+				setBusy(true);
+				// 先读再写：**已有索引绝不覆盖**。readRaw 对不存在的文件会 reject，正好当探针。
+				remote.readRaw("MEMORY.md").then(function () {
+					setBusy(false);
+					setNotice("MEMORY.md 已经存在，没有改动它。");
+				}, function () {
+					return remote.writeRaw("MEMORY.md", INDEX_SKELETON).then(function (res) {
+						const out = unwrap(res);
+						setBusy(false);
+						if (out && out.ok === false) { setError(out.error || "建立索引骨架失败"); return; }
+						setNotice("已建立 MEMORY.md 索引骨架。");
+						load();
+					});
+				}).catch(function (e) {
+					setBusy(false);
+					setError(String((e && e.message) || e));
+				});
+			}
+
+			function openMemoryFolder() {
+				setError(null);
+				if (!remote || typeof remote.openMemoryDir !== "function") {
+					setError("宿主侧还没有 openMemoryDir 接口（插件版本较旧）");
+					return;
+				}
+				remote.openMemoryDir()
+					.then(function (res) {
+						const result = unwrap(res);
+						if (result && result.ok === false) setError(result.error || "打开记忆目录失败");
+					})
+					.catch(function (e) { setError(String((e && e.message) || e)); });
+			}
+
 			function openEdit(file) {
 				setError(null);
 				setBusy(true);
@@ -4573,7 +4645,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			// 「文件列表」这一屏：状态筛选决定看哪一批，灰色卡片与留痕块自带「退役」语义。
 			// banner 只在**专门看归档**时出现，切到全部时不重复说一遍。
 			const filesView = h(FilesView, {
-				loading: loading, totalCount: totalCount, openAdd: openAdd,
+				loading: loading, totalCount: totalCount, openAdd: openAdd, createIndexSkeleton: createIndexSkeleton,
 				statusFilter: statusFilter, setStatusFilter: setStatusFilter,
 				items: items, archiveItems: archiveItems, filtered: filtered,
 				setTypeFilter: setTypeFilter, setTagFilter: setTagFilter, setQuery: setQuery,
@@ -4632,6 +4704,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 					// 也推到最右，看起来像"跑出格子了"）。
 					h("span", { className: "smem-head-spacer", key: "sp" }),
 					h("span", { className: "smem-head-actions", key: "act" }, tab === "files" ? [
+						h("button", { type: "button", className: "smem-btn", key: "open", disabled: busy || !dirOk, title: "在系统文件管理器里打开记忆目录", onClick: openMemoryFolder }, "打开记忆文件夹"),
 						h("button", { type: "button", className: "smem-btn", key: "refresh", disabled: busy || loading, onClick: load }, "刷新"),
 						h("button", { type: "button", className: "smem-btn smem-btn-primary", key: "add", onClick: openAdd }, "+ 添加记忆"),
 					] : null),

package/lib/index.js

@@ -27,6 +27,7 @@ import { archiveMemory, deleteArchivedMemory, restoreMemory } from './memory/arc
 import { flushAccess, pickArchiveCandidates, readAccessLedger } from './memory/access.js'
 import { warnLog, writeFileAtomic } from './memory/util.js'
 import { readLockSet, setLocked as setLockedImpl } from './memory/lock.js'
+import { openMemoryFolder } from './memory/open-folder.js'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
@@ -360,6 +361,16 @@ export class MemoryGateway extends TypertRemoteService {
     return auditMemoryDir(MEMORY_DIR)
   }
 
+  /**
+   * 用系统文件管理器打开记忆目录（设置页「打开记忆文件夹」）。
+   *
+   * host 侧起一个 detached 进程就返回，不等待窗口出现；路径是插件自己的记忆目录，
+   * 不接受界面传入，避免把「打开任意路径」变成一个能力。
+   */
+  async openMemoryDir() {
+    return openMemoryFolder(MEMORY_DIR)
+  }
+
   /**
    * 自动归档候选 + 当前策略与阈值（面板「执行归档」前先看清单）。
    *
@@ -558,6 +569,7 @@ markRemote(MemoryGateway, 'readArchived', 'readArchived')
 markRemote(MemoryGateway, 'writeArchived', 'writeArchived')
 markRemote(MemoryGateway, 'deleteArchived', 'deleteArchived')
 markRemote(MemoryGateway, 'audit', 'audit')
+markRemote(MemoryGateway, 'openMemoryDir', 'openMemoryDir')
 markRemote(MemoryGateway, 'checkUpdate', 'checkUpdate')
 markRemote(MemoryGateway, 'setLocked', 'setLocked')
 markRemote(MemoryGateway, 'archiveCandidates', 'archiveCandidates')

package/lib/memory/open-folder.js

@@ -0,0 +1,57 @@
+/**
+ * 打开记忆目录（设置页「打开记忆文件夹」按钮的 host 侧实现）。
+ *
+ * 为什么放在 host 侧：浏览器不能起进程；而 DSH 的 `open-in-app` 路由属于界面内部接口，
+ * 老版本 DSH 不一定有。这里只依赖 `node:child_process`，三条命令覆盖三个平台：
+ *   - Windows  → `explorer.exe <dir>`
+ *   - macOS    → `open <dir>`
+ *   - 其它     → `xdg-open <dir>`
+ *
+ * 进程是**一次性、detached** 的：不等待退出（Explorer / Finder 是常驻进程，等它等于
+ * 永不返回），也不持有 stdio。这条路径不改变插件「无 worker / 无端口 / 无常驻进程」的性质。
+ *
+ * 返回 `{ ok, error? }`，不抛：设置页按 ok 显示错误。`spawn` 的 'error' 事件是异步的，
+ * 调用方拿不到，所以这里只挂一个空处理器，避免「命令不存在」变成未捕获异常 ——
+ * 返回值表达的是「已发起」，不是「窗口已经出现」。
+ */
+import { spawn } from 'node:child_process'
+
+/**
+ * 平台 → 打开目录的命令与参数（纯函数，测试直接钉它）。
+ * @param {string} platform — `process.platform` 的取值
+ * @param {string} dir — 绝对路径
+ * @returns {{command: string, args: string[]}}
+ */
+export function folderOpenCommand(platform, dir) {
+  if (typeof dir !== 'string' || dir.length === 0) throw new Error('sage-mem: memory directory is unknown')
+  if (platform === 'win32') return { command: 'explorer.exe', args: [dir] }
+  if (platform === 'darwin') return { command: 'open', args: [dir] }
+  return { command: 'xdg-open', args: [dir] }
+}
+
+/**
+ * 发起「打开目录」，立即返回。
+ * @param {string} dir — 记忆目录绝对路径
+ * @param {{platform?: string, spawn?: Function}} [options] — 测试注入点
+ * @returns {{ok: boolean, error?: string}}
+ */
+export function openMemoryFolder(dir, options = {}) {
+  const platform = options.platform || process.platform
+  const spawnImpl = options.spawn || spawn
+
+  let plan
+  try {
+    plan = folderOpenCommand(platform, dir)
+  } catch (error) {
+    return { ok: false, error: String(error?.message ?? error) }
+  }
+
+  try {
+    const child = spawnImpl(plan.command, plan.args, { detached: true, stdio: 'ignore', windowsHide: true })
+    child.on?.('error', () => {})
+    child.unref?.()
+    return { ok: true }
+  } catch (error) {
+    return { ok: false, error: `sage-mem: cannot open ${dir}: ${error?.message ?? error}` }
+  }
+}

package/lib/typert.host.js

@@ -181,6 +181,12 @@ const auditReportSchema = z.object({
 	'problems': z.number().readonly(),
 }).readonly()
 
+/** 「打开记忆目录」的结果：成功只有 ok，失败带原因。 */
+const openFolderResultSchema = z.object({
+	'ok': z.boolean().readonly(),
+	'error': z.string().readonly().optional(),
+}).readonly()
+
 const archiveCandidateSchema = z.object({
 	'file': z.string().readonly(),
 	'type': z.string().readonly(),
@@ -616,6 +622,16 @@ export const TYPERT = {
 			result: { mode: 'strict', typeSymbol: 'sage-mem/types#AuditReport', schema: auditReportSchema, create: () => auditReportSchema },
 			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
 		},
+		{
+			id: 'sage-mem#memory/openMemoryDir',
+			service: 'memory',
+			namespace: 'memory',
+			method: 'openMemoryDir',
+			invocation: { kind: 'direct' },
+			parameters: [],
+			result: { mode: 'strict', typeSymbol: 'sage-mem/types#OpenFolderResult', schema: openFolderResultSchema, create: () => openFolderResultSchema },
+			sourceLocation: { "file": "lib/index.js", "line": 1, "column": 1 },
+		},
 		{
 			// 面板进入时静默查一次；只有「有新版本」才在界面上提醒。
 			id: 'sage-mem#memory/checkUpdate',

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.5.3",
+  "version": "1.6.1",
   "type": "module",
   "main": "lib/index.js",
   "exports": {