zen-gitsync 2.17.23 → 2.17.25

package/src/config.js

@@ -98,6 +98,19 @@ export function normalizeNotifyOnTaskDone(value) {
   return typeof value === 'boolean' ? value : null;
 }
 
+/**
+ * 规范化「任务完成提示音」开关。语义与 normalizeNotifyOnTaskDone 完全一致
+ * （只收布尔值，`'false'` 这种字符串不当真值用 —— 理由同上）。
+ *
+ * 为什么和总开关分开成两个键：有人要"发系统通知但别出声"（开会 / 图书馆 / 夜里），
+ * 也有人反过来只要"叮"一声、不想要通知卡片和权限询问。合成一个开关两边都别扭。
+ * 从属关系在消费端：总开关关着时整个提示链路都不走，提示音自然也不会响
+ * （见 useTaskNotifier.announce 的调用点）。
+ */
+export function normalizeNotifySoundOnTaskDone(value) {
+  return typeof value === 'boolean' ? value : null;
+}
+
 // 默认配置
 const defaultConfig = {
   defaultCommitMessage: "submit",
@@ -153,6 +166,11 @@ const defaultConfig = {
   // 默认关等于大部分人永远不知道有它；浏览器通知权限在页面内首次点击时自动申请
   // （见 App.vue 的 onUserGestureForNotifyPermission），所以默认开不会静默失效。
   notifyOnTaskDone: true,
+  // 任务完成提示音（全局，默认开）：跑完 / 出错误各响一声，主动停止不响。
+  // 从属于上面的 notifyOnTaskDone —— 总开关关着时整条提示链路都不走，声音也不会响。
+  // 单独一个键是为了"要通知但别出声"和"要声音但不要通知卡片"这两种人都能配。
+  // 音源是 CC0 资源（src/ui/client/public/sounds/），见同目录 CREDITS.txt。
+  notifySoundOnTaskDone: true,
   // UI 状态（跨项目共享，存到顶层 ui 对象）
   // 之前散落在 localStorage，因随机端口启动而失效，迁到文件持久化
   ui: {
@@ -474,7 +492,9 @@ async function loadConfig() {
       aiMaxToolIterations: normalizeAiMaxToolIterations(raw.aiMaxToolIterations)
         ?? defaultConfig.aiMaxToolIterations,
       taskExecutor: normalizeTaskExecutor(raw.taskExecutor) ?? defaultConfig.taskExecutor,
-      notifyOnTaskDone: normalizeNotifyOnTaskDone(raw.notifyOnTaskDone) ?? defaultConfig.notifyOnTaskDone
+      notifyOnTaskDone: normalizeNotifyOnTaskDone(raw.notifyOnTaskDone) ?? defaultConfig.notifyOnTaskDone,
+      notifySoundOnTaskDone: normalizeNotifySoundOnTaskDone(raw.notifySoundOnTaskDone)
+        ?? defaultConfig.notifySoundOnTaskDone
     };
   }
 
@@ -494,7 +514,9 @@ async function loadConfig() {
       ?? defaultConfig.aiMaxToolIterations,
     taskExecutor: normalizeTaskExecutor(raw?.taskExecutor) ?? defaultConfig.taskExecutor,
     // 同 taskExecutor：全局配置，始终取顶层，防止被项目配置里的旧值覆盖
-    notifyOnTaskDone: normalizeNotifyOnTaskDone(raw?.notifyOnTaskDone) ?? defaultConfig.notifyOnTaskDone
+    notifyOnTaskDone: normalizeNotifyOnTaskDone(raw?.notifyOnTaskDone) ?? defaultConfig.notifyOnTaskDone,
+    notifySoundOnTaskDone: normalizeNotifySoundOnTaskDone(raw?.notifySoundOnTaskDone)
+      ?? defaultConfig.notifySoundOnTaskDone
   };
 }
 
@@ -542,7 +564,7 @@ async function saveConfig(config) {
 
   // 分离全局设置和项目设置
   // models / ui 也是全局配置（跨项目共享），和 theme/locale 一样存到顶层
-  const { theme, locale, models, ui, aiMaxToolIterations, taskExecutor, notifyOnTaskDone, ...projectConfig } = config;
+  const { theme, locale, models, ui, aiMaxToolIterations, taskExecutor, notifyOnTaskDone, notifySoundOnTaskDone, ...projectConfig } = config;
 
   // 保存全局设置到根级别
   if (theme !== undefined) {
@@ -572,6 +594,10 @@ async function saveConfig(config) {
   if (normalizedNotify !== null) {
     raw.notifyOnTaskDone = normalizedNotify;
   }
+  const normalizedNotifySound = normalizeNotifySoundOnTaskDone(notifySoundOnTaskDone);
+  if (normalizedNotifySound !== null) {
+    raw.notifySoundOnTaskDone = normalizedNotifySound;
+  }
 
   // 写入当前项目配置（在 defaultConfig 基础上合并，但不清空顶层其它键）
   const existingProjectConfig = (raw.projects[key] && typeof raw.projects[key] === 'object') ? raw.projects[key] : {};
@@ -771,6 +797,11 @@ export default {
   TASK_EXECUTORS,
   // 任务执行结束提示开关规范化(同上)
   normalizeNotifyOnTaskDone,
+  // 任务完成提示音开关规范化(同上)。⚠️ 新增规范化函数务必同步加进这个对象字面量 ——
+  // server 侧 `import config from '../../config.js'` 拿的是**这个默认导出对象**，
+  // 只在下面 `export {}` 里命名导出是不够的：漏加会变成 undefined 调用 → 路由 500，
+  // 而且因为有 try/catch 兜底，前端只会看到"保存失败"，不知道是哪个函数缺了。
+  normalizeNotifySoundOnTaskDone,
 };
 
 // 命名导出 — 用于测试与外部复用

package/src/memory/library.js

@@ -0,0 +1,273 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// 记忆库的**浏览 / 删除**能力。store.js 只管"写的时候路径对不对"，
+// 这里管"界面看到什么、能删什么"。
+//
+// ── 身份是怎么表达的 ────────────────────────────────────────────────
+// 记忆条目的定位是 `{ scope, file }`：
+//   scope = `'global'`                    → `MEMORY_DIR/GLOBAL.md`
+//   scope = `'global-index'`              → `MEMORY_DIR/INDEX.md`
+//   scope = 任意 slug                     → `MEMORY_DIR/projects/<slug>/lessons/<file>`
+// **前端永远只传 scope + file 两个字符串，不传绝对路径** ——
+// 这是本文件最重要的安全设计：路径由服务端从 scope 重新拼，
+// 前端传什么都只能落到"某个 slug 下的某个 lessons/*.md"，
+// 不存在拼出 `~/.claude/settings.json` 的可能。
+// （对比 mindmap.js：那边让前端传 path，所以得靠 validatePath + pathGuard 双重拦；
+//   这里是结构性防��� —— 越界参数压根不参与路径拼接。）
+//
+// ⚠️ 因此下面所有对 `scope` / `file` 的合法性检查都**不是可选的加固**，
+// 而是这条安全边界的组成部分。改这个文件时别把它们当冗余删掉。
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { MEMORY_DIR, MEMORY_GLOBAL_FILE, MEMORY_INDEX_FILE, MEMORY_PROJECTS_DIR } from '../paths.js';
+
+/** 单条正文的大小上限：超过就不给读（界面也渲染不动） */
+export const ENTRY_MAX_BYTES = 64 * 1024;
+
+/** 列表条目数上限：避免一个 slug 下堆了上千文件时把响应撑爆 */
+export const LIST_MAX_ENTRIES = 500;
+
+/** scope 的两种特殊值（其余都当 slug 处理） */
+export const SCOPE_GLOBAL = 'global';
+export const SCOPE_GLOBAL_INDEX = 'global-index';
+
+const LESSON_EXT = '.md';
+
+/** slug 形状：可读部分 + 6 位十六进制哈希。**必须严格校验**（见文件头） */
+const SLUG_RE = /^[a-z0-9_][a-z0-9_-]{0,120}-[0-9a-f]{6}$/;
+
+/** lesson 文件名：kebab-case，不允许点号/斜杠/上跳（`.` 与 `..` 靠这条挡掉） */
+const FILE_RE = /^[a-z0-9][a-z0-9._-]{0,79}\.md$/i;
+
+export function isValidScope(scope) {
+  return scope === SCOPE_GLOBAL || scope === SCOPE_GLOBAL_INDEX || (typeof scope === 'string' && SLUG_RE.test(scope));
+}
+
+export function isValidFile(file) {
+  return typeof file === 'string' && FILE_RE.test(file);
+}
+
+/**
+ * `{scope,file}` → 绝对路径。**不合法就返回空串**（调用方决定报什么错）。
+ *
+ * 注意它只可能落在三处：全局正文、全局索引、某 slug 的 lessons/ 下。
+ * 别的路径**在这个函数里无法被构造出来**。
+ */
+export function resolveEntryPath(scope, file) {
+  if (!isValidScope(scope) || !isValidFile(file)) return '';
+  // ⚠️ 这里必须用 endsWith 而不是 ===：全局两篇是**固定文件名**（GLOBAL.md / INDEX.md），
+  // 但 isValidFile 只保证"是个合法的 .md 文件名"，不保证叫这两个名字。
+  // 写 === '.md' 会让所有全局条目一律解析失败（第一版就是这么写错的，测出来的）。
+  if (scope === SCOPE_GLOBAL) return file.toLowerCase() === 'global.md' ? MEMORY_GLOBAL_FILE : '';
+  if (scope === SCOPE_GLOBAL_INDEX) return file.toLowerCase() === 'index.md' ? MEMORY_INDEX_FILE : '';
+  return path.join(MEMORY_PROJECTS_DIR, scope, 'lessons', file);
+}
+
+async function statOrNull(p) {
+  try { return await fs.stat(p); } catch { return null; }
+}
+
+/**
+ * 列出一个 scope 下的条目。
+ *
+ * @param {string} scope  'global' | 'global-index' | <slug>
+ * @returns {Promise<Array<{file, title, size, mtime, indexed: boolean, summary: string}>>}
+ *          mtime 倒序（最新在前），与 ExecutionLogManager 的列表口径一致。
+ */
+export async function listEntries(scope) {
+  if (scope === SCOPE_GLOBAL || scope === SCOPE_GLOBAL_INDEX) {
+    const abs = scope === SCOPE_GLOBAL ? MEMORY_GLOBAL_FILE : MEMORY_INDEX_FILE;
+    const st = await statOrNull(abs);
+    if (!st || !st.isFile()) return [];
+    return [{
+      file: path.basename(abs),
+      title: scope === SCOPE_GLOBAL ? 'GLOBAL.md' : 'INDEX.md',
+      size: st.size,
+      mtime: st.mtimeMs,
+      // 全局两篇是"索引本身"，条目字段不适用
+      indexed: true,
+      summary: '',
+    }];
+  }
+
+  if (!isValidScope(scope)) return [];
+  const dir = path.join(MEMORY_PROJECTS_DIR, scope, 'lessons');
+  let names;
+  try {
+    names = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  // 索引里出现过的文件名 → 这条经验是有索引的（没索引的属于"孤儿"，界面要标出来）
+  const indexed = await readIndexedFiles(scope);
+
+  const out = [];
+  for (const e of names) {
+    if (!e.isFile()) continue;
+    if (e.name.startsWith('.')) continue;
+    if (!isValidFile(e.name)) continue;
+    if (out.length >= LIST_MAX_ENTRIES) break;
+    const st = await statOrNull(path.join(dir, e.name));
+    if (!st) continue;
+    out.push({
+      file: e.name,
+      title: e.name.slice(0, -LESSON_EXT.length),
+      size: st.size,
+      mtime: st.mtimeMs,
+      indexed: indexed.has(e.name),
+      summary: '',
+    });
+  }
+  out.sort((a, b) => b.mtime - a.mtime);
+  return out;
+}
+
+/** 从项目 INDEX.md 里抽出被索引到的 lesson 文件名集合。解析失败时返回空集。 */
+async function readIndexedFiles(scope) {
+  const set = new Set();
+  try {
+    const text = await fs.readFile(path.join(MEMORY_PROJECTS_DIR, scope, 'INDEX.md'), 'utf8');
+    for (const m of text.matchAll(/\((lessons\/[^)]+)\)/g)) {
+      const name = m[1].slice('lessons/'.length);
+      if (isValidFile(name)) set.add(name);
+    }
+  } catch { /* 索引读不到就当作"都没有索引"，界面会提示补索引 */ }
+  return set;
+}
+
+/** 从 INDEX.md 的一行里取出标题与摘要，供界面直接显示（省得读正文） */
+export function parseIndexLine(line) {
+  const m = /^\s*-\s*\[([^\]]+)\]\([^)]+\)\s*(?:[—-]\s*(.*))?$/.exec(line);
+  if (!m) return null;
+  return { title: m[1].trim(), summary: (m[2] || '').trim() };
+}
+
+/**
+ * 列出全部 scope（给界面的项目切换器用）。
+ *
+ * slug → 展示名：优先用项目 INDEX.md 头里记的仓库路径（那才是人能认出的东西），
+ * 退化时显示 slug 本体。**绝不在这里暴露绝对路径之外的东西** ——
+ * 仓库路径本来就存在 INDEX.md 里，是给用户看的，不是秘密。
+ */
+export async function listScopes() {
+  const out = [];
+  for (const [scope, label] of [[SCOPE_GLOBAL, 'GLOBAL'], [SCOPE_GLOBAL_INDEX, 'INDEX']]) {
+    const st = await statOrNull(scope === SCOPE_GLOBAL ? MEMORY_GLOBAL_FILE : MEMORY_INDEX_FILE);
+    if (st && st.isFile()) out.push({ scope, label, repoPath: '', count: 1, mtime: st.mtimeMs });
+  }
+
+  let names = [];
+  try { names = await fs.readdir(MEMORY_PROJECTS_DIR, { withFileTypes: true }); } catch { names = []; }
+
+  for (const e of names) {
+    if (!e.isDirectory() || !isValidScope(e.name)) continue;
+    const entries = await listEntries(e.name);
+    const idx = path.join(MEMORY_PROJECTS_DIR, e.name, 'INDEX.md');
+    let repoPath = '';
+    try {
+      const m = /^>\s*仓库：\s*`(.+?)`/m.exec(await fs.readFile(idx, 'utf8'));
+      if (m) repoPath = m[1];
+    } catch { /* 头没写就退化显示 slug */ }
+    out.push({
+      scope: e.name,
+      label: repoPath || e.name,
+      repoPath,
+      count: entries.length,
+      mtime: entries.length ? entries[0].mtime : 0,
+    });
+  }
+  // 最新的在前；全局两篇永远排最上（它们是"所有项目都适用"的那部分）
+  out.sort((a, b) => (a.scope === SCOPE_GLOBAL || a.scope === SCOPE_GLOBAL_INDEX ? -1 : 1)
+    - (b.scope === SCOPE_GLOBAL || b.scope === SCOPE_GLOBAL_INDEX ? -1 : 1) || b.mtime - a.mtime);
+  return out;
+}
+
+/** 读一条正文；不存在返回 {missing:true}，过大返回 {tooLarge:true}。都**不抛错**。 */
+export async function readEntry(scope, file) {
+  const abs = resolveEntryPath(scope, file);
+  if (!abs) return { error: 'invalid' };
+  let st;
+  try { st = await fs.stat(abs); } catch { return { missing: true }; }
+  if (!st.isFile()) return { missing: true };
+  if (st.size > ENTRY_MAX_BYTES) return { tooLarge: true, size: st.size };
+  try {
+    return { content: await fs.readFile(abs, 'utf8'), size: st.size, mtime: st.mtimeMs };
+  } catch {
+    return { missing: true };
+  }
+}
+
+/**
+ * 删一条。
+ *
+ * ⚠️ 删 lesson 会**连带删掉它在 INDEX.md 里的那一行** —— 留着就是一条指向
+ * 死链的索引（Agent 命中它会去读一个不存在的文件）。这是"删除"语义完整的
+ * 一部分，不是副作用。`archive/` 里的同名文件不动。
+ *
+ * @returns {Promise<{removed: boolean, indexLineRemoved: boolean, alreadyGone: boolean}>}
+ */
+export async function deleteEntry(scope, file) {
+  const abs = resolveEntryPath(scope, file);
+  if (!abs) return { error: 'invalid' };
+
+  let alreadyGone = false;
+  try {
+    await fs.unlink(abs);
+  } catch (err) {
+    if (err.code === 'ENOENT') alreadyGone = true;   // 幂等：本来就没有也算成功
+    else throw err;
+  }
+
+  let indexLineRemoved = false;
+  if (isValidScope(scope) && scope !== SCOPE_GLOBAL && scope !== SCOPE_GLOBAL_INDEX) {
+    indexLineRemoved = await removeIndexLine(scope, file);
+  }
+  return { removed: !alreadyGone, indexLineRemoved, alreadyGone };
+}
+
+/** 从项目 INDEX.md 里删掉指向某个 lesson 的那一行。读不到/没这行都算无事发生。 */
+async function removeIndexLine(scope, file) {
+  const idx = path.join(MEMORY_PROJECTS_DIR, scope, 'INDEX.md');
+  let text;
+  try { text = await fs.readFile(idx, 'utf8'); } catch { return false; }
+  const needle = `(lessons/${file})`;
+  if (!text.includes(needle)) return false;
+  // 逐行过滤而不是 replace：needle 只在行首的链接形态里出现，
+  // 行级过滤天然不会误伤正文里恰好提到同一路径的段落。
+  const kept = text.split(/\r?\n/).filter((l) => !l.includes(needle));
+  if (kept.length === text.split(/\r?\n/).length) return false;
+  await writeTextAtomic(idx, kept.join('\n'));
+  return true;
+}
+
+/** 原子写：tmp + rename。直接 writeFile 会和读者（正在渲染的面板）撞出半截内容。 */
+async function writeTextAtomic(file, content) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    await fs.writeFile(tmp, content, 'utf8');
+    await fs.rename(tmp, file);
+  } catch (err) {
+    await fs.unlink(tmp).catch(() => {});
+    throw err;
+  }
+}
+
+/** 记忆库是否已就位（目录在不在） */
+export async function memoryDirExists() {
+  const st = await statOrNull(MEMORY_DIR);
+  return !!(st && st.isDirectory());
+}

package/src/memory/library.test.js

@@ -0,0 +1,187 @@
+// library.js 的单测。
+//
+// ⚠️ paths.js 在**模块加载时**由 os.homedir() 求值，USERPROFILE/HOME 必须
+// 在 import 之前改（Windows 上还要删 HOMEDRIVE/HOMEPATH），否则会写进用户真实的
+// ~/.zen-gitsync/memory。
+import os from 'node:os';
+import path from 'node:path';
+import fsp from 'node:fs/promises';
+import { test, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+
+const SANDBOX = await fsp.mkdtemp(path.join(os.tmpdir(), 'zen-memory-lib-'));
+for (const k of ['HOMEDRIVE', 'HOMEPATH']) delete process.env[k];
+process.env.USERPROFILE = SANDBOX;
+process.env.HOME = SANDBOX;
+
+const { MEMORY_DIR } = await import('../paths.js');
+const lib = await import('./library.js');
+const { projectSlug } = await import('./store.js');
+
+after(() => fsp.rm(SANDBOX, { recursive: true, force: true }));
+
+const SLUG = projectSlug('C:\\ws\\zen-gitsync');
+const PROJ_DIR = path.join(MEMORY_DIR, 'projects', SLUG);
+
+/** 铺一个最小可用的库：全局两篇 + 一个项目里两条有索引 + 一条孤儿经验 */
+async function seed() {
+  await fsp.mkdir(path.join(PROJ_DIR, 'lessons'), { recursive: true });
+  await fsp.writeFile(path.join(MEMORY_DIR, 'INDEX.md'), '# 记忆索引 · 全局\n', 'utf8');
+  await fsp.writeFile(path.join(MEMORY_DIR, 'GLOBAL.md'), '# 跨项目经验\n', 'utf8');
+  await fsp.writeFile(
+    path.join(PROJ_DIR, 'INDEX.md'),
+    '# 记忆索引 · 本项目\n\n## 主题\n- [双落盘路径](lessons/jobs-persistence.md) — jobs.json 只在终态 flush\n- [探针假绿](lessons/probe.md) — 别信恒真断言\n',
+    'utf8'
+  );
+  await fsp.writeFile(path.join(PROJ_DIR, 'lessons', 'jobs-persistence.md'), '# 双落盘路径\n\n内容\n', 'utf8');
+  await fsp.writeFile(path.join(PROJ_DIR, 'lessons', 'probe.md'), '# 探针假绿\n\n内容\n', 'utf8');
+  // 一条**没有索引行**的孤儿经验：界面上要能标出来
+  await fsp.writeFile(path.join(PROJ_DIR, 'lessons', 'orphan.md'), '# 孤儿\n', 'utf8');
+}
+
+beforeEach(seed);
+
+// ── 形状校验：这是本文件的安全边界，不是可选加固 ─────────────────────
+test('isValidScope：只认两种特殊值与「可读部分+6位哈希」', () => {
+  assert.equal(lib.isValidScope('global'), true);
+  assert.equal(lib.isValidScope('global-index'), true);
+  assert.equal(lib.isValidScope(SLUG), true);
+  assert.equal(lib.isValidScope(SLUG.replace(/-[0-9a-f]{6}$/, '')), false, '缺哈希后缀');
+  assert.equal(lib.isValidScope(SLUG.replace(/-[0-9a-f]{6}$/, '-ZZZZZZ')), false, '哈希必须十六进制');
+  assert.equal(lib.isValidScope(''), false);
+  assert.equal(lib.isValidScope(null), false);
+  assert.equal(lib.isValidScope('../..'), false);
+  assert.equal(lib.isValidScope('a/../b-abcdef'), false);
+});
+
+test('isValidFile：kebab 文件名 + .md，挡掉 . 与 ..', () => {
+  assert.equal(lib.isValidFile('jobs-persistence.md'), true);
+  assert.equal(lib.isValidFile('a_b-c.1.md'), true);
+  assert.equal(lib.isValidFile('..'), false);
+  assert.equal(lib.isValidFile('../evil.md'), false);
+  assert.equal(lib.isValidFile('a/b.md'), false);
+  assert.equal(lib.isValidFile('a\\b.md'), false);
+  assert.equal(lib.isValidFile('evil.txt'), false);
+  assert.equal(lib.isValidFile('.hidden.md'), false);
+  assert.equal(lib.isValidFile(''), false);
+  assert.equal(lib.isValidFile('x'.repeat(200) + '.md'), false);
+});
+
+// ── ⚠️ 越界：拼不出 MEMORY_DIR 之外的任何路径 ────────────────────────
+test('⚠️ resolveEntryPath：非法入参一律返回空串（结构性防越界）', () => {
+  const evil = [
+    ['../../.claude/settings.json', 'settings.json'],
+    ['global', '../config.json'],
+    [SLUG, '../../../config.json'],
+    [SLUG, '../../../../.ssh/id_rsa'],
+  ];
+  for (const [scope, file] of evil) {
+    assert.equal(lib.resolveEntryPath(scope, file), '', `${scope}/${file} 不该解析出路径`);
+  }
+});
+
+test('resolveEntryPath：合法入参只落在三处', () => {
+  assert.equal(lib.resolveEntryPath('global', 'GLOBAL.md'), path.join(MEMORY_DIR, 'GLOBAL.md'));
+  assert.equal(lib.resolveEntryPath('global-index', 'INDEX.md'), path.join(MEMORY_DIR, 'INDEX.md'));
+  assert.equal(
+    lib.resolveEntryPath(SLUG, 'probe.md'),
+    path.join(MEMORY_DIR, 'projects', SLUG, 'lessons', 'probe.md')
+  );
+  // global 只认 GLOBAL.md 本体，别的文件名不给
+  assert.equal(lib.resolveEntryPath('global', 'INDEX.md'), '');
+});
+
+test('⚠️ resolveEntryPath 的产物必须在 MEMORY_DIR 之内（回归守卫）', () => {
+  for (const scope of ['global', 'global-index', SLUG]) {
+    for (const file of ['a.md', 'probe.md', 'UPPER.MD']) {
+      const abs = lib.resolveEntryPath(scope, file);
+      if (!abs) continue;
+      const rel = path.relative(MEMORY_DIR, abs);
+      assert.ok(rel && !rel.startsWith('..') && !path.isAbsolute(rel),
+        `${abs} 逃出了 MEMORY_DIR`);
+    }
+  }
+});
+
+// ── 列表 ────────────────────────────────────────────────────────────
+test('listEntries：列出 lessons 并标出哪些有索引', async () => {
+  const list = await lib.listEntries(SLUG);
+  const byName = Object.fromEntries(list.map(e => [e.file, e]));
+  assert.equal(list.length, 3);
+  assert.equal(byName['jobs-persistence.md'].indexed, true);
+  assert.equal(byName['probe.md'].indexed, true);
+  assert.equal(byName['orphan.md'].indexed, false, '没有索引行的要标出来');
+  assert.equal(byName['jobs-persistence.md'].title, 'jobs-persistence');
+});
+
+test('listEntries：slug 不存在 / 非法时返回空数组而不是抛错', async () => {
+  assert.deepEqual(await lib.listEntries('no-such-slug-abcdef'), []);
+  assert.deepEqual(await lib.listEntries('../evil'), []);
+});
+
+test('listScopes：全局两篇 + 项目，且项目带仓库路径', async () => {
+  const scopes = await lib.listScopes();
+  const s = scopes.find(x => x.scope === SLUG);
+  assert.ok(s, '项目 scope 应在列表里');
+  assert.equal(s.count, 3);
+  const labels = scopes.map(x => x.scope);
+  assert.ok(labels.includes('global'));
+  assert.ok(labels.includes('global-index'));
+  assert.ok(['global', 'global-index'].includes(scopes[0].scope), '全局两篇永远排最上');
+});
+
+test('parseIndexLine：从索引行里取出标题与摘要', () => {
+  assert.deepEqual(lib.parseIndexLine('- [双落盘路径](lessons/x.md) — 只在终态 flush'),
+    { title: '双落盘路径', summary: '只在终态 flush' });
+  assert.deepEqual(lib.parseIndexLine('- [探针](lessons/y.md)'), { title: '探针', summary: '' });
+  assert.equal(lib.parseIndexLine('## 主题'), null);
+  assert.equal(lib.parseIndexLine('随便一行'), null);
+});
+
+// ── 读 ──────────────────────────────────────────────────────────────
+test('readEntry：正常读 / 不存在 / 超大 / 非法', async () => {
+  const ok = await lib.readEntry(SLUG, 'probe.md');
+  assert.match(ok.content, /探针假绿/);
+  assert.equal((await lib.readEntry(SLUG, 'nope.md')).missing, true);
+  assert.equal((await lib.readEntry('../evil', 'x.md')).error, 'invalid');
+});
+
+// ── 删：连带清索引行（不留死链）──────────────────────────────────
+test('deleteEntry：删文件并连带删掉 INDEX.md 里那一行', async () => {
+  const r = await lib.deleteEntry(SLUG, 'probe.md');
+  assert.equal(r.removed, true);
+  assert.equal(r.indexLineRemoved, true);
+  await assert.rejects(fsp.access(path.join(PROJ_DIR, 'lessons', 'probe.md')));
+  const idx = await fsp.readFile(path.join(PROJ_DIR, 'INDEX.md'), 'utf8');
+  assert.ok(!idx.includes('probe.md'), '索引行必须一起删 —— 留着就是死链');
+  assert.ok(idx.includes('jobs-persistence.md'), '别的行不能被误伤');
+});
+
+test('deleteEntry：重复删是幂等的（alreadyGone）', async () => {
+  await lib.deleteEntry(SLUG, 'probe.md');
+  const again = await lib.deleteEntry(SLUG, 'probe.md');
+  assert.equal(again.alreadyGone, true);
+  assert.equal(again.removed, false);
+});
+
+test('deleteEntry：非法入参不删任何东西', async () => {
+  for (const [scope, file] of [['../evil', 'x.md'], [SLUG, '../../../config.json'], [SLUG, '..']]) {
+    const r = await lib.deleteEntry(scope, file);
+    assert.equal(r.error, 'invalid', `${scope}/${file} 应被拒`);
+  }
+  assert.ok((await lib.listEntries(SLUG)).length >= 3, '种子文件不该被动过');
+});
+
+test('deleteEntry：删孤儿（无索引行）不算失败，indexLineRemoved=false', async () => {
+  const r = await lib.deleteEntry(SLUG, 'orphan.md');
+  assert.equal(r.removed, true);
+  assert.equal(r.indexLineRemoved, false, '本来就没索引行可删');
+});
+
+test('deleteEntry 不碰 archive/ 里的同名文件', async () => {
+  await fsp.mkdir(path.join(PROJ_DIR, 'archive'), { recursive: true });
+  const archived = path.join(PROJ_DIR, 'archive', 'probe.md');
+  await fsp.writeFile(archived, '历史', 'utf8');
+  await lib.deleteEntry(SLUG, 'probe.md');
+  assert.equal(await fsp.readFile(archived, 'utf8'), '历史', 'archive 是冻结历史，不该被动');
+});