sage-mem 0.7.2 → 0.9.0

package/lib/autodream/rollback.js

@@ -0,0 +1,221 @@
+/**
+ * autodream —— 回滚与留痕（引擎方法体）。
+ *
+ * 本文件里的函数都是 `AutodreamEngine` 的方法体：`engine.js` 里保留同名同签名的方法，
+ * 用 `xxxMod.name.call(this, …)` 转发进来 —— 所以函数体里的 `this` 就是引擎实例，
+ * 与拆分前完全一致，没有引入任何模块级可变状态。
+ */
+
+import { REPORT_DIR } from './config.js'
+import { readJson, safeName, snapshotEntries, stampCompact, stampHuman } from './util.js'
+import { randomUUID } from 'node:crypto'
+import { copyFile, mkdir, readdir, rename, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** 读回滚留痕（面板也许要显示「最近谁退回过」）。 */
+export async function listRollbacks(limit = 20) {
+  const all = await readJson(this.rollbacksPath)
+  const list = Array.isArray(all) ? all : []
+  return list.slice(-limit).reverse()
+}
+
+/** 追加一条回滚留痕。 */
+export async function appendRollback(entry) {
+  const all = await readJson(this.rollbacksPath)
+  const list = Array.isArray(all) ? all : []
+  list.push(entry)
+  await mkdir(this.home, { recursive: true })
+  await writeFile(this.rollbacksPath, JSON.stringify(list.slice(-200), null, 2), 'utf8')
+}
+
+/** 把运行记录标成「已被回滚」。 */
+export async function markRunRolledBack(runId, at) {
+  const id = safeName(runId)
+  if (!id) return
+  const file = join(this.runsRoot, id, 'manifest.json')
+  const m = await readJson(file)
+  if (!m) return
+  m.rolledBackAt = at
+  m.rolledBackAtHuman = stampHuman(at)
+  await writeFile(file, JSON.stringify(m, null, 2), 'utf8')
+}
+
+/**
+ * 把记忆目录退回到某个回滚点。
+ *
+ * 四步顺序不可变（见 contract §5）：
+ *   ① 保护快照 —— 回滚本身也可能滚错，所以回滚前先把「现在」存下来
+ *   ② 恢复 —— `all` 整目录；`files` 只动该次运行动过的文件
+ *   ③ 留痕 —— 报告 + `rollbacks.json`
+ *   ④ 回写运行记录
+ *
+ * **全程不删文件**：回滚中「不该存在」的文件一律移进 `archive/`（人工可捞回）。
+ * memory 目录没有版本控制也没有回收站，`unlink` 不该出现在这条路径上。
+ *
+ * @param {{snapshotId:string, scope?:'files'|'all'}} opts
+ */
+export async function rollback(opts = {}) {
+  const snapshotId = safeName(opts?.snapshotId)
+  const scope = opts?.scope === 'all' ? 'all' : 'files'
+  if (!snapshotId) return { ok: false, error: '快照 id 不合法' }
+  if (this.running) return { ok: false, error: '正在整理中，等它跑完再回滚' }
+
+  const snapDir = await this.resolveSnapshotDir(snapshotId)
+  if (!snapDir) return { ok: false, error: `找不到回滚点：${snapshotId}` }
+
+  await this.load()
+  if (!(await this.acquireLock())) return { ok: false, error: '拿不到锁（另一趟整理正在跑？）' }
+  const startedAt = Date.now()
+  const stamp = stampCompact(startedAt)
+  try {
+    const manifest = await readJson(join(snapDir, 'MANIFEST.json'))
+    const runId = manifest?.runId ?? null
+
+    // 文件级回滚要知道「这次动过哪几个文件」——那信息在运行记录里，不在快照里。
+    let runManifest = null
+    if (scope === 'files') {
+      if (!runId) return { ok: false, error: '这份回滚点没有绑定运行记录（旧版快照），只能选「整目录恢复」' }
+      runManifest = await readJson(join(this.runsRoot, runId, 'manifest.json'))
+      if (!runManifest) return { ok: false, error: `找不到回滚点 ${snapshotId} 对应的运行记录，只能选「整目录恢复」` }
+    }
+
+    // ① 保护快照
+    this.phase = '回滚前保护快照'
+    // 带随机后缀：秒级时间戳会撞（同一秒内连点两次回滚是真实用法），
+    // 而撞车的后果是**覆盖掉上一次的保护快照**——那等于把「回滚也能退」这条承诺吃掉。
+    const protectionId = `pre-rollback-${stamp}-${randomUUID().replace(/-/g, '').slice(0, 4)}`
+    const protection = await this.snapshot(protectionId, 'pre-rollback')
+
+    // ② 恢复
+    this.phase = '恢复文件'
+    const snapNames = await snapshotEntries(snapDir)
+    const snapSet = new Set(snapNames)
+    const current = (await readdir(this.memoryDir, { withFileTypes: true }).catch(() => []))
+      .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
+      .map((e) => e.name)
+
+    const restored = []
+    const parked = []
+    const skipped = []
+    const archiveDir = join(this.memoryDir, 'archive')
+    await mkdir(archiveDir, { recursive: true })
+
+    /** 移进 archive/（不删）。同名冲突就跳过并记账，绝不覆盖。 */
+    const park = async (name, why) => {
+      const target = join(archiveDir, name)
+      const clash = await stat(target).catch(() => null)
+      if (clash) {
+        skipped.push(`${name}（本想${why}，但 archive/ 里已有同名文件）`)
+        return false
+      }
+      await rename(join(this.memoryDir, name), target)
+      parked.push(`${name}（${why}）`)
+      return true
+    }
+
+    if (scope === 'all') {
+      for (const name of snapNames) {
+        try {
+          await copyFile(join(snapDir, name), join(this.memoryDir, name))
+          restored.push(name)
+        } catch (err) {
+          skipped.push(`${name}（写回失败：${err?.message ?? err}）`)
+        }
+      }
+      // 快照之后新建的文件：整目录回滚要让它退场，但不能删——移进 archive/。
+      for (const name of current) {
+        if (!snapSet.has(name)) await park(name, '快照里没有，整目录回滚需退场')
+      }
+    } else {
+      for (const c of runManifest.changes ?? []) {
+        const name = c.file
+        if (c.op === 'update') {
+          if (snapSet.has(name)) {
+            try {
+              await copyFile(join(snapDir, name), join(this.memoryDir, name))
+              restored.push(name)
+            } catch (err) {
+              skipped.push(`${name}（写回失败：${err?.message ?? err}）`)
+            }
+          } else {
+            skipped.push(`${name}（回滚点里没有这一版，可能已被别的整理改过）`)
+          }
+        } else if (c.op === 'create') {
+          if (current.includes(name)) await park(name, '本次整理新建，回滚即退场')
+        } else if (c.op === 'archive') {
+          // 归档 = 从顶层移进 archive/；回滚就是把它移回来。
+          const src = join(archiveDir, name)
+          const exists = await stat(src).catch(() => null)
+          const atTop = await stat(join(this.memoryDir, name)).catch(() => null)
+          if (!exists) skipped.push(`${name}（archive/ 里找不到，可能已人工处理过）`)
+          else if (atTop) skipped.push(`${name}（顶层已有同名文件，不覆盖）`)
+          else {
+            await rename(src, join(this.memoryDir, name))
+            restored.push(name)
+          }
+        }
+      }
+    }
+
+    // ③ 留痕
+    this.phase = '写回滚报告'
+    const reportName = `${stamp}-rollback.md`
+    const lines = [
+      `# Autodream 回滚报告 · ${stampHuman(startedAt)}`,
+      '',
+      `- 回滚目标：\`${snapshotId}\`${runId ? `（运行 \`${runId}\`）` : '（旧版快照）'}`,
+      `- 范围：${scope === 'all' ? '整目录恢复到该时点' : '只恢复该次运行动过的文件'}`,
+      `- 回滚前保护快照：\`${protection.id}\`（${protection.count} 个文件）—— 滚错了还能再退回来`,
+      '',
+      '## 写回的文件',
+      '',
+      restored.length ? restored.map((f) => `- \`${f}\``).join('\n') : '- （没有文件被写回）',
+      '',
+      '## 移进 archive/ 的文件（没有删除）',
+      '',
+      parked.length ? parked.map((f) => `- ${f}`).join('\n') : '- （没有）',
+      '',
+    ]
+    if (skipped.length) {
+      lines.push('## 跳过', '', ...skipped.map((f) => `- ${f}`), '')
+    }
+    const reportDir = join(this.memoryDir, REPORT_DIR)
+    await mkdir(reportDir, { recursive: true })
+    await writeFile(join(reportDir, reportName), lines.join('\n'), 'utf8')
+
+    const entry = {
+      at: startedAt,
+      atHuman: stampHuman(startedAt),
+      snapshotId,
+      scope,
+      runId,
+      restored: restored.length,
+      parked: parked.length,
+      skipped: skipped.length,
+      protection: protection.id,
+      report: reportName,
+    }
+    await this.appendRollback(entry)
+    // ④ 回写运行记录
+    if (runId) await this.markRunRolledBack(runId, startedAt)
+
+    this.phase = ''
+    return {
+      ok: true,
+      restored: restored.length,
+      parked: parked.length,
+      skipped: skipped.length,
+      protection: protection.id,
+      report: reportName,
+    }
+  } catch (err) {
+    const message = err?.message ?? String(err)
+    this.log('warn', `回滚失败：${message}`)
+    this.phase = ''
+    return { ok: false, error: message }
+  } finally {
+    await this.releaseLock()
+  }
+}
+
+// ────────────────────────────── 主流程 ──────────────────────────────

package/lib/autodream/settings.js

@@ -0,0 +1,289 @@
+/**
+ * autodream —— 配置与状态（引擎方法体）。
+ *
+ * 本文件里的函数都是 `AutodreamEngine` 的方法体：`engine.js` 里保留同名同签名的方法，
+ * 用 `xxxMod.name.call(this, …)` 转发进来 —— 所以函数体里的 `this` 就是引擎实例，
+ * 与拆分前完全一致，没有引入任何模块级可变状态。
+ */
+
+import { CONFIG_VERSION, DEFAULT_CONFIG, LEGACY_STATE_FILE } from './config.js'
+import { clampNum, readJson } from './util.js'
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises'
+
+/**
+ * 读配置 + 状态（同一个文件）。缺失或损坏都回落到默认值，绝不让它拖死插件加载。
+ *
+ * **改名迁移**：新文件 `<stateRoot>/autodream.json` 不存在而旧文件 `<stateRoot>/dream.json`
+ * 存在时，读旧文件、把配置搬到新文件，**旧文件原样留着不删**（用户手改过的东西，
+ * 插件没有替用户清理的资格；留着也让人能对照）。迁移只发生一次。
+ */
+export async function load() {
+  if (this._configLoaded) return this.state
+  let parsed = await readJson(this.configPath)
+  let migratedFrom = ''
+  if (!parsed) {
+    const legacy = await readJson(this.legacyConfigPath)
+    if (legacy && typeof legacy === 'object') {
+      parsed = legacy
+      migratedFrom = LEGACY_STATE_FILE
+    }
+  }
+  if (parsed && typeof parsed === 'object') {
+    this.state = {
+      version: CONFIG_VERSION,
+      config: { ...DEFAULT_CONFIG, ...(parsed.config ?? {}) },
+      lastRunAt: Number(parsed.lastRunAt) || 0,
+      lastResult: parsed.lastResult ?? null,
+      retryAfter: Number(parsed.retryAfter) || 0,
+    }
+  } else {
+    this.state = { version: CONFIG_VERSION, config: { ...DEFAULT_CONFIG }, lastRunAt: 0, lastResult: null, retryAfter: 0 }
+  }
+  this._configLoaded = true
+  if (migratedFrom) {
+    this.log('warn', `读到旧版配置 ${this.legacyConfigPath}，已迁移到 ${this.configPath}（旧文件保留不动）`)
+    await this.persist().catch((err) => this.log('warn', `迁移落盘失败（本次仍按内存里的配置跑）：${err?.message ?? err}`))
+  }
+  return this.state
+}
+
+/** 落盘。写入是原子的（临时文件 + rename），半截文件不会留在盘上。 */
+export async function persist() {
+  await mkdir(this.stateRoot, { recursive: true })
+  const tmp = `${this.configPath}.${process.pid}.tmp`
+  try {
+    await writeFile(tmp, JSON.stringify(this.state, null, 2), 'utf8')
+    await rename(tmp, this.configPath)
+  } finally {
+    // rename 成功后 tmp 已不存在（ENOENT），失败时清掉不留垃圾。
+    await rm(tmp, { force: true }).catch(() => {})
+  }
+}
+
+/** 给 UI 的完整配置（含有效模型路线与门控快照）。 */
+export async function getConfig() {
+  await this.load()
+  const route = this.resolveRoute(this.state.config)
+  return {
+    config: { ...this.state.config },
+    route,
+    lastRunAt: this.state.lastRunAt,
+    lastResult: this.state.lastResult,
+    paths: { memoryDir: this.memoryDir, configPath: this.configPath, stateRoot: this.stateRoot, home: this.home },
+    defaults: { ...DEFAULT_CONFIG },
+  }
+}
+
+/** 改配置。逐项做类型与范围收敛——UI 传什么进来都不该写出一份坏配置。 */
+export async function setConfig(patch) {
+  await this.load()
+  const p = patch && typeof patch === 'object' ? patch : {}
+  const c = { ...this.state.config }
+  if (typeof p.enabled === 'boolean') c.enabled = p.enabled
+  if (p.trigger === 'auto' || p.trigger === 'manual') c.trigger = p.trigger
+  if (typeof p.apply === 'boolean') c.apply = p.apply
+  if (p.source === 'memory' || p.source === 'memory+sessions') c.source = p.source
+  if (p.rollbackScope === 'files' || p.rollbackScope === 'all') c.rollbackScope = p.rollbackScope
+  // 归档策略三档：与上面 trigger / rollbackScope 同一套写法 —— 非法值不写入，保留原值。
+  if (p.autoArchive === 'off' || p.autoArchive === 'report' || p.autoArchive === 'auto') c.autoArchive = p.autoArchive
+  if (p.minHours !== undefined) c.minHours = clampNum(Number(p.minHours), 1, 720, DEFAULT_CONFIG.minHours)
+  if (p.minSessions !== undefined) c.minSessions = Math.round(clampNum(Number(p.minSessions), 1, 200, DEFAULT_CONFIG.minSessions))
+  if (p.maxSteps !== undefined) c.maxSteps = Math.round(clampNum(Number(p.maxSteps), 1, 80, DEFAULT_CONFIG.maxSteps))
+  if (p.maxSnapshotKeep !== undefined)
+    c.maxSnapshotKeep = Math.round(clampNum(Number(p.maxSnapshotKeep), 1, 50, DEFAULT_CONFIG.maxSnapshotKeep))
+  if (typeof p.provider === 'string') c.provider = p.provider.trim().slice(0, 120)
+  if (typeof p.model === 'string') c.model = p.model.trim().slice(0, 160)
+  this.state.config = c
+  await this.persist()
+  return await this.getConfig()
+}
+
+/** 当前会话默认模型路线（取不到就是 null）。 */
+export function defaultSelection() {
+  try {
+    const sel = this.svc('agentDefaultModel')?.currentSelection?.()
+    const provider = String(sel?.provider ?? '').trim()
+    const model = String(sel?.model ?? '').trim()
+    if (!provider || !model) return null
+    return { provider, model }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 解析这一趟该用哪条模型路线。
+ *
+ * 三条语义必须分得清（否则「我明明选了模型它怎么还用别的」这类问题查不出来）：
+ *   - `source:'config'`  用户显式指定 → **指定了就只认它**，解析不出来宁可报错也不回落
+ *   - `source:'default'` 配置留空 → 用当前会话默认模型
+ *   - `source:'none'`    两条都拿不到 → `error` 里写清原因
+ * 永远返回对象，不抛异常；UI 两种形状都要能读（见 contract）。
+ */
+export function resolveRoute(config) {
+  const p = String(config?.provider ?? '').trim()
+  const m = String(config?.model ?? '').trim()
+  const explicit = !!(p && m)
+  // 只填了一半：这是配置错误，不是「跟随默认」。说清楚，别猜。
+  if (!explicit && (p || m)) {
+    return {
+      provider: p,
+      model: m,
+      fromDefault: false,
+      source: 'none',
+      error: `配置里只填了 ${p ? 'provider' : 'model'}，必须成对填；两项都清空则跟随当前会话默认模型`,
+    }
+  }
+  if (explicit) return { provider: p, model: m, fromDefault: false, source: 'config', error: null }
+  const def = this.defaultSelection()
+  if (def) return { provider: def.provider, model: def.model, fromDefault: true, source: 'default', error: null }
+  return {
+    provider: '',
+    model: '',
+    fromDefault: false,
+    source: 'none',
+    error: '配置里没写 provider/model，也拿不到当前会话默认模型',
+  }
+}
+
+/**
+ * 可选的模型路线清单。
+ *
+ * 数据源是宿主的 **`llm` 服务**（`listProviders()` + 逐 provider 的 `listModels()`），
+ * 三个「看起来更顺手但会出错」的替代都被排除了：
+ *   - `agentDefaultModel` 只有当前那一条，不是目录；
+ *   - 面向子代理的模型选择策略会**按白名单过滤 provider**，拿它当全量目录会漏；
+ *   - `sessionController.modelCatalog()` 依赖会话控制器挂载，而整理是后台任务。
+ *
+ * 单个 provider 取模型失败**不拖垮整表**（宿主自己的目录也是这么处理的）——
+ * 一条渠道的 key 过期不该让整个下拉框变空。
+ */
+export async function listModels() {
+  const routes = []
+  let catalogAvailable = false
+  let note = ''
+  const llm = this.svc('llm')
+  if (!llm || typeof llm.listProviders !== 'function') {
+    note = 'llm 服务不可用，取不到模型目录，请手填 provider 与 model'
+  } else {
+    let providers = []
+    try {
+      providers = llm.listProviders() ?? []
+    } catch (err) {
+      note = `读取 provider 列表失败：${err?.message ?? err}`
+    }
+    for (const p of providers) {
+      const pid = String(p?.id ?? '').trim()
+      if (!pid) continue
+      const pName = String(p?.name ?? pid).trim()
+      let models = []
+      try {
+        // 同步返回数组或 Promise 都收（不同宿主版本两种都有）。
+        models = (await llm.listModels(pid)) ?? []
+      } catch {
+        // 单个 provider 挂了不记 note：那是常态，不是整表故障。
+        models = []
+      }
+      for (const m of models) {
+        const mid = String(m?.id ?? '').trim()
+        if (!mid) continue
+        const mName = String(m?.name ?? mid).trim()
+        routes.push({ provider: pid, model: mid, label: `${pName} / ${mName}`, isDefault: false })
+      }
+    }
+    catalogAvailable = routes.length > 0
+  }
+  const def = this.defaultSelection()
+  if (def) {
+    const hit = routes.find((r) => r.provider === def.provider && r.model === def.model)
+    if (hit) hit.isDefault = true
+    else {
+      // 当前默认模型可能来自一个 listModels 拿不到东西的 provider（见下面「空目录放行」）。
+      // 把它补进来，否则下拉框会显示「跟随默认」但目录里找不到它。
+      routes.unshift({
+        provider: def.provider,
+        model: def.model,
+        label: `${def.provider} / ${def.model}`,
+        isDefault: true,
+      })
+      catalogAvailable = true
+    }
+  }
+  if (!catalogAvailable && !note) note = '宿主没有可枚举的模型目录，请手填 provider 与 model'
+  routes.sort((a, b) => `${a.provider}/${a.model}`.localeCompare(`${b.provider}/${b.model}`))
+  return { routes, defaultRoute: def, catalogAvailable, note }
+}
+
+/**
+ * 运行前判「这条路线在宿主里存在吗」。
+ *
+ * 运行前先做一次**纯本地的存在性校验**（只比对宿主已注册的 provider / model 目录，
+ * 不发任何模型请求）—— 这正是「运行前就报错，别跑到一半才失败」要的东西。
+ *
+ * 两个已知陷阱，都刻意避开：
+ *   - **空目录放行**：某些适配器的 `listModels` 恒返回 `[]`。
+ *     若把「目录为空」当「模型不存在」，会把明明能用的路线毙掉 → 返回 `ok:true, checked:false`。
+ *   - **不做「查模型元数据」式的存在性判断**：有的适配器对未知模型不报错，
+ *     而是合成一份假元数据（`name === id`），拿它校验等于永远通过。
+ *
+ * @returns {Promise<{ok:boolean, checked:boolean, reason:string}>}
+ */
+export async function checkRouteAvailable(provider, model) {
+  const llm = this.svc('llm')
+  if (!llm || typeof llm.listProviders !== 'function') {
+    return { ok: true, checked: false, reason: 'llm 服务不可用，跳过存在性校验' }
+  }
+  let providers = []
+  try {
+    providers = llm.listProviders() ?? []
+  } catch (err) {
+    return { ok: true, checked: false, reason: `读取 provider 列表失败（${err?.message ?? err}），跳过校验` }
+  }
+  const ids = providers.map((p) => String(p?.id ?? '')).filter(Boolean)
+  if (!ids.includes(provider)) {
+    return { ok: false, checked: true, reason: `宿主没有名为 ${provider} 的 provider（已注册：${ids.join('、') || '（无）'}）` }
+  }
+  let models = []
+  try {
+    models = (await llm.listModels(provider)) ?? []
+  } catch (err) {
+    return { ok: false, checked: true, reason: `读取 ${provider} 的模型目录失败：${err?.message ?? err}` }
+  }
+  if (!models.length) {
+    return { ok: true, checked: false, reason: `${provider} 的模型目录为空，无法判断该模型是否存在（放行）` }
+  }
+  if (!models.some((m) => String(m?.id ?? '') === model)) {
+    const names = models.map((m) => String(m?.id ?? '')).filter(Boolean)
+    return {
+      ok: false,
+      checked: true,
+      reason: `${provider} 的目录里没有模型 ${model}（可选：${names.slice(0, 8).join('、')}${names.length > 8 ? '…' : ''}）`,
+    }
+  }
+  return { ok: true, checked: true, reason: '' }
+}
+
+/** 当前状态快照，供设置面板轮询。 */
+export async function status() {
+  await this.load()
+  const cfg = this.state.config
+  const lastAt = this.state.lastRunAt
+  const hoursSince = lastAt ? (Date.now() - lastAt) / 3600000 : null
+  return {
+    running: this.running,
+    phase: this.phase,
+    startedAt: this.startedAt,
+    runId: this.runId,
+    steps: this.stepLog,
+    config: { ...cfg },
+    route: this.resolveRoute(cfg),
+    lastRunAt: lastAt,
+    hoursSince,
+    lastResult: this.state.lastResult,
+    retryAfter: this.state.retryAfter,
+    gate: cfg.enabled && cfg.trigger === 'auto' ? { minHours: cfg.minHours, minSessions: cfg.minSessions } : null,
+    paths: { memoryDir: this.memoryDir, configPath: this.configPath, stateRoot: this.stateRoot, home: this.home },
+  }
+}
+
+// ────────────────────────────── 门控 ──────────────────────────────

package/lib/autodream/snapshot.js

@@ -0,0 +1,142 @@
+/**
+ * autodream —— 回滚点（快照）：建立、修剪、定位、列出（引擎方法体）。
+ *
+ * 本文件里的函数都是 `AutodreamEngine` 的方法体：`engine.js` 里保留同名同签名的方法，
+ * 用 `xxxMod.name.call(this, …)` 转发进来 —— 所以函数体里的 `this` 就是引擎实例，
+ * 与拆分前完全一致，没有引入任何模块级可变状态。
+ */
+
+import { DEFAULT_CONFIG, PRE_ROLLBACK_KEEP } from './config.js'
+import { readJson, safeName, snapshotEntries, stampHuman } from './util.js'
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * 把 memory 目录顶层的 markdown 整体快照一份，作为**回滚点**。
+ *
+ * 只快照顶层 `.md`：`archive/` 子目录是退役区（不需要每次跟着复制），
+ * `autodream/` 是报告区（自己就是产物）。
+ *
+ * 每条都记 sha256：回滚后「是不是真的回到了那一版」靠它判等——只看体积在 markdown 里太容易骗人。
+ *
+ * @param {string} id — 快照 id（apply 运行就是 runId；保护快照用 `pre-rollback-<时间戳>`）
+ * @param {'run'|'pre-rollback'} kind
+ * @returns {Promise<{id:string, dir:string, count:number, expected:number, failed:string[], files:Array<{name:string,bytes:number,sha256:string}>}>}
+ */
+export async function snapshot(id, kind = 'run') {
+  const dir = join(this.snapshotRoot, id)
+  await mkdir(this.snapshotRoot, { recursive: true })
+  // **故意不用 recursive**：快照 id 撞车必须是硬错误，不能静默覆盖一份已有的回滚点。
+  // 实测踩到 —— 同一秒里连着两次回滚，`pre-rollback-<秒级时间戳>` 撞车，
+  // 第二次的保护快照把第一次的覆盖成「回滚后」的状态，于是「退回到保护点」等于什么都没退。
+  try {
+    await mkdir(dir)
+  } catch (err) {
+    if (err?.code === 'EEXIST') throw new Error(`回滚点 id 撞车：${id} 已存在，拒绝覆盖已有的回滚点`)
+    throw err
+  }
+  const entries = await readdir(this.memoryDir, { withFileTypes: true }).catch(() => [])
+  const files = entries.filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
+  const recorded = []
+  /** 没存下来的文件。**不是「警告一下就继续」**：调用方要拿它决定是否中止。 */
+  const failed = []
+  for (const f of files) {
+    try {
+      const buf = await readFile(join(this.memoryDir, f.name))
+      await writeFile(join(dir, f.name), buf)
+      recorded.push({ name: f.name, bytes: buf.length, sha256: createHash('sha256').update(buf).digest('hex') })
+    } catch (err) {
+      failed.push(f.name)
+      this.log('warn', `快照 ${f.name} 失败：${err?.message ?? err}`)
+    }
+  }
+  const manifest = {
+    schema: 1,
+    id,
+    kind,
+    runId: kind === 'run' ? id : null,
+    createdAt: Date.now(),
+    createdAtHuman: stampHuman(Date.now()),
+    files: recorded,
+    fileCount: recorded.length,
+    failed,
+  }
+  await writeFile(join(dir, 'MANIFEST.json'), JSON.stringify(manifest, null, 2), 'utf8')
+  await this.pruneSnapshots()
+  return { id, dir, count: recorded.length, expected: files.length, failed, files: recorded }
+}
+
+/**
+ * 淘汰旧回滚点。
+ *
+ * **两类分开数**：普通运行的快照按 `maxSnapshotKeep`；「回滚前保护快照」
+ * 另给一个额度（`PRE_ROLLBACK_KEEP`）—— 保护快照的唯一用途就是「刚回滚完发现滚错了」，
+ * 被普通运行的快照轮转挤掉等于没有。旧版目录（`<stateRoot>/snapshots/`）只读，不参与淘汰。
+ */
+export async function pruneSnapshots() {
+  const keep = Math.max(1, this.state.config.maxSnapshotKeep || DEFAULT_CONFIG.maxSnapshotKeep)
+  const entries = await readdir(this.snapshotRoot, { withFileTypes: true }).catch(() => [])
+  const dirs = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort()
+  const preRollback = dirs.filter((n) => n.startsWith('pre-rollback-'))
+  const runs = dirs.filter((n) => !n.startsWith('pre-rollback-'))
+  for (const name of runs.slice(0, Math.max(0, runs.length - keep))) {
+    await rm(join(this.snapshotRoot, name), { recursive: true, force: true }).catch(() => {})
+  }
+  for (const name of preRollback.slice(0, Math.max(0, preRollback.length - PRE_ROLLBACK_KEEP))) {
+    await rm(join(this.snapshotRoot, name), { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+/** 快照目录的真实位置：先找新版，再找旧版；都没有返回 null。 */
+export async function resolveSnapshotDir(id) {
+  const name = safeName(id)
+  if (!name) return null
+  for (const root of [this.snapshotRoot, this.legacySnapshotRoot]) {
+    const dir = join(root, name)
+    const info = await stat(dir).catch(() => null)
+    if (info?.isDirectory()) return dir
+  }
+  return null
+}
+
+/**
+ * 列出所有回滚点（新版 + 旧版目录都列）。
+ *
+ * 「可回退到哪一份」是给人看的，所以：旧版快照标 `legacy:true`、保护快照标 `kind`，
+ * 让界面能说清「这一份是哪来的」。
+ */
+export async function listSnapshots() {
+  const out = []
+  for (const [root, legacy] of [
+    [this.snapshotRoot, false],
+    [this.legacySnapshotRoot, true],
+  ]) {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => [])
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      const dir = join(root, e.name)
+      const manifest = await readJson(join(dir, 'MANIFEST.json'))
+      const names = await snapshotEntries(dir)
+      out.push({
+        name: e.name,
+        at: manifest?.createdAt ?? 0,
+        atHuman: manifest?.createdAtHuman ?? e.name,
+        files: Array.isArray(manifest?.files)
+          ? manifest.files.length
+          : typeof manifest?.files === 'number'
+            ? manifest.files
+            : names.length,
+        path: dir,
+        runId: manifest?.runId ?? (manifest?.kind === 'run' ? e.name : null),
+        kind: manifest?.kind ?? (legacy ? 'legacy' : 'run'),
+        legacy,
+      })
+    }
+  }
+  // 新的在前（名字里带时间戳，字典序即时间序）。
+  out.sort((a, b) => b.name.localeCompare(a.name))
+  return out
+}
+
+// ────────────────────────────── LLM 循环 ──────────────────────────────