zen-gitsync 2.17.24 → 2.17.26

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 是冻结历史，不该被动');
+});

package/src/memory/store.js

@@ -0,0 +1,199 @@
+// 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.
+//
+// 跨会话「记忆库」的读写层。
+//
+// ── 为什么是"索引 + 正文"两层 ─────────────────────────────────────────
+// 用户原话点破的那件事:「总结要尽可能简洁,或者用索引的方式,不然上下文会太长」。
+// 早期形态是单个 MEMORY.md 全文进上下文,越记越贵、越贵越没人看。所以:
+//
+//   INDEX.md   每条 ≤100 字,只有它进 prompt(见 memoryContext.js)
+//   lessons/   正文单条 ≤25 行,Agent 命中关键词才自己 read
+//   archive/   冻结历史,永不读
+//
+// ── 谁在写 ───────────────────────────────────────────────────────────
+// **Agent 自己**,不是服务端。服务端只在 prompt 里给一段指针,Agent 用它自己的
+// 文件工具去读索引、按需读正文、收尾时追加 lesson。理由:
+//   · Agent 才知道"这次踩的坑"是什么,服务端只有一堆 IO 事件;
+//   · 少一次 LLM 调用(服务端代写就得再起一轮模型,还猜不准该记什么);
+//   · Agent 写完立刻能自己验证路径对不对。
+// 服务端只保留两件事:目录不存在时铺种子、算 slug 告诉 Agent 写哪儿。
+//
+// ⚠️ 这个模块**只碰 MEMORY_DIR 下的路径**,一个字节都不写到用户工作区或
+// 第三方工具的配置目录(~/.claude、~/.codex 等)。Agent 按 prompt 里的
+// 指令去写那些文件时是它自己的选择,不是本产品替他改配置。
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { MEMORY_DIR, MEMORY_GLOBAL_FILE, MEMORY_INDEX_FILE, MEMORY_PROJECTS_DIR } from '../paths.js';
+
+/** 种子模板:随包发布,首次运行时铺进 MEMORY_DIR(见 templates.js) */
+import { MEMORY_SEED_FILES } from './templates.js';
+
+/**
+ * 仓库绝对路径 → 记忆库里的项目 slug。
+ *
+ * 形状：`<可读部分>-<路径哈希 6 位>`
+ *   `C:\workspace\github_workspace\xz333221\zen-gitsync`
+ *     → `c-workspace-github_workspace-xz333221-zen-gitsync-3f2a1b`
+ *
+ * ⚠️ **哈希是必须的，不是装饰**（2026-09-29 实测踩到）：
+ * 只做"小写 + 非 [a-z0-9_] 压成 -"的话，两个不同的中文路径会塌成同一个 slug ——
+ *   `C:\中文\项目` 与 `C:\中文\别的` → 都是 `c-`
+ * 于是两个仓库共用一份 lessons，A 项目的教训会被当成 B 项目的写进 prompt。
+ * 这类污染**不报错、不可见**，是记忆系统最坏的一类失效。
+ *
+ * 哈希前先把 `\` 归一成 `/` 再算：`C:\a\b` 与 `C:/a/b` 是同一个仓库的两个写法，
+ * 归一后才能算出同一个 slug（否则同仓库会裂成两份记忆）。
+ *
+ * ⚠️ 两条纪律(改这个函数前先读):
+ *   1. **纯函数,不碰文件系统** —— 单测要能直接钉住映射规则,不许夹带 stat。
+ *   2. **规则一改 = 全量历史记忆失联**（目录名变了）。所以要改必须同时带一份
+ *      重命名迁移;宁可永远不改规则也不要"顺手优化一下"。
+ *
+ * 保留 `_`(不下划线)是为了让 slug 读起来还认得出仓库名。
+ */
+export function projectSlug(repoPath) {
+  if (typeof repoPath !== 'string') return '';
+  const s = repoPath.trim();
+  if (!s) return '';
+  // 分隔符先归一,让同一个仓库的两种写法落到同一个 slug
+  const normalized = s.replace(/\\/g, '/').toLowerCase();
+  const readable = normalized
+    .replace(/[^a-z0-9_]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  // 哈希走归一后的路径:大小写与分隔符差异不该让同一个仓库裂成两份
+  const hash = createHash('sha1').update(normalized).digest('hex').slice(0, 6);
+  return `${readable || 'root'}-${hash}`;
+}
+
+/** 某仓库的项目目录绝对路径(不保证存在 —— 存在性由 ensureProjectDir 负责) */
+export function projectMemoryDir(repoPath) {
+  const slug = projectSlug(repoPath);
+  return slug ? path.join(MEMORY_PROJECTS_DIR, slug) : '';
+}
+
+/** 某仓库的项目索引绝对路径 */
+export function projectIndexFile(repoPath) {
+  const dir = projectMemoryDir(repoPath);
+  return dir ? path.join(dir, 'INDEX.md') : '';
+}
+
+/** 读一个文本文件;不存在返回 ''，读失败也返回 ''（记忆读不到不该影响任何事） */
+async function readTextOrEmpty(file) {
+  if (!file) return '';
+  try {
+    return await fsp.readFile(file, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 幂等铺种子:目录不存在时把 MEMORY_SEED_FILES 写进去。
+ *
+ * **已存在的文件一律不覆盖** —— 用户(和 Agent)可能在里面写过东西,
+ * 每次启动都重铺等于把记忆洗回出厂设置。
+ *
+ * @returns {Promise<{created: string[], existed: number}>} created = 实际新建的文件名
+ */
+export async function ensureMemoryStore() {
+  await fsp.mkdir(MEMORY_DIR, { recursive: true });
+  await fsp.mkdir(path.join(MEMORY_DIR, 'archive'), { recursive: true });
+
+  let existed = 0;
+  const created = [];
+  for (const [rel, content] of Object.entries(MEMORY_SEED_FILES)) {
+    const target = path.join(MEMORY_DIR, ...rel.split('/'));
+    try {
+      await fsp.access(target);
+      existed += 1;
+    } catch {
+      await fsp.mkdir(path.dirname(target), { recursive: true });
+      await fsp.writeFile(target, content, 'utf8');
+      created.push(rel);
+    }
+  }
+  return { created, existed };
+}
+
+/**
+ * 确保某仓库的项目目录存在,并返回它的索引路径。
+ * 索引不存在就铺一份**带 path 头**的骨架 —— 头里记着仓库绝对路径,
+ * 这样即便将来 slug 规则变了,人/Agent 还能从 INDEX.md 认回来。
+ *
+ * @returns {Promise<string>} 项目索引绝对路径；repoPath 非法时返回 ''
+ */
+export async function ensureProjectMemory(repoPath) {
+  const dir = projectMemoryDir(repoPath);
+  if (!dir) return '';
+  await fsp.mkdir(path.join(dir, 'lessons'), { recursive: true });
+  await fsp.mkdir(path.join(dir, 'archive'), { recursive: true });
+
+  const idx = path.join(dir, 'INDEX.md');
+  try {
+    await fsp.access(idx);
+  } catch {
+    await fsp.writeFile(idx, renderProjectIndexHeader(repoPath), 'utf8');
+  }
+  return idx;
+}
+
+/** 新项目索引的头部。抽成函数是为了单测能直接断言首行格式。 */
+export function renderProjectIndexHeader(repoPath) {
+  return [
+    '# 记忆索引 · 本项目',
+    '',
+    `> 仓库：\`${repoPath}\``,
+    '> 预算：≤40 条 / ≤6KB，**每条 ≤100 字**。**正文在 `lessons/`，只有命中本行才去 Read 对应文件。**',
+    '> 条目只写"先查什么 / 以后怎么做"，不写"我做了什么"。单条 >25 行 → 那是文档，踢去项目 `docs/`。',
+    '',
+    '## 主题',
+    '',
+  ].join('\n');
+}
+
+/** 全局索引内容（可能为空串） */
+export function readGlobalIndex() {
+  return readTextOrEmpty(MEMORY_INDEX_FILE);
+}
+
+/** 跨项目经验正文（可能为空串） */
+export function readGlobalMemory() {
+  return readTextOrEmpty(MEMORY_GLOBAL_FILE);
+}
+
+/** 某仓库的项目索引内容（可能为空串） */
+export function readProjectIndex(repoPath) {
+  return readTextOrEmpty(projectIndexFile(repoPath));
+}
+
+/**
+ * 记忆库是否"可用"。
+ *
+ * 判据刻意很弱:只要 MEMORY_DIR 存在就算可用。因为产品默认**不预填任何经验**,
+ * 一个只有种子文件、没有一条 lesson 的空库也该被指针照常指向 ——
+ * 否则第一次派发时 Agent 看不到"有个记忆库存在",永远写不出第一条。
+ * 首次写入的活由 ensureMemoryStore() 兜。
+ */
+export function memoryAvailable() {
+  try {
+    fs.accessSync(MEMORY_DIR);
+    return true;
+  } catch {
+    return false;
+  }
+}