sage-mem 0.7.2 → 0.9.0

package/lib/autodream/util.js

@@ -0,0 +1,112 @@
+/**
+ * autodream —— 通用小工具：数值收敛、时间戳、runId、安全文件名、JSON 读、
+ * 快照枚举、会话计数与增量描述。
+ */
+
+import { randomUUID } from 'node:crypto'
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export const clampNum = (v, lo, hi, dflt) => (Number.isFinite(v) ? Math.max(lo, Math.min(hi, v)) : dflt)
+
+/** 本地时间戳，给文件名用。 */
+export function stampCompact(ms) {
+  const d = new Date(ms)
+  const p = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`
+}
+
+/** 本地时间戳，给人看。 */
+export function stampHuman(ms) {
+  const d = new Date(ms)
+  const p = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`
+}
+
+/**
+ * 运行 id：`YYYYMMDD-HHmmss-<4 位>`。
+ *
+ * 加后缀是因为**同一秒里跑第二趟**在手动连点时真会发生，而 runId 同时是
+ * 快照目录名、运行记录目录名和报告文件名——撞一次就是三个地方互相覆盖。
+ */
+export function newRunId(ms) {
+  return `${stampCompact(ms)}-${randomUUID().replace(/-/g, '').slice(0, 4)}`
+}
+
+/** 文件名/目录名的白名单校验（快照 id、运行 id、报告名都走这里，别让路径穿越进来）。 */
+export function safeName(raw) {
+  const s = String(raw ?? '').trim()
+  if (!s || s.includes('/') || s.includes('\\') || s.includes('..')) return null
+  if (!/^[\w.-]+$/.test(s)) return null
+  return s
+}
+
+/** 读一个 JSON，读不到/解析失败都返回 null（配置与清单文件损坏不该拖死流程）。 */
+export async function readJson(file) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/** 快照里实际躺着哪些 .md（清单不可信时以目录为准）。 */
+export async function snapshotEntries(dir) {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+  return entries.filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md')).map((e) => e.name)
+}
+
+/**
+ * 精简版 chunk 组装器。
+ *
+ * 只保留 autodream 用得上的两种块，并**自己实现而不是依赖宿主内部包** ——
+ * 依赖漂移时挂的是「整个插件加载不了」这种级别的故障，而这里需要的逻辑只有三十行。
+ *
+ * 两条必须保证的行为：
+ *   - delta-only 协议（没有 block-start/block-end）也要能组装
+ *   - `finish.kind === 'max-tokens'` 时**丢掉 tool-call 块**：被截断的调用参数
+ *     是不完整的 JSON，拿去执行等于凭半句话动手
+
+/** 数一下 `$DSH_HOME/sessions` 下 mtime 晚于 sinceMs 的会话（只看文件时间，不解压）。 */
+export async function countSessionsSince(root, sinceMs) {
+  if (!root) return 0
+  let n = 0
+  let projects
+  try {
+    projects = await readdir(root, { withFileTypes: true })
+  } catch {
+    return 0
+  }
+  for (const p of projects) {
+    if (!p.isDirectory()) continue
+    const projPath = join(root, p.name)
+    let sessions
+    try {
+      sessions = await readdir(projPath, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const s of sessions) {
+      if (!s.isDirectory()) continue
+      const file = join(projPath, s.name, 'session.v4.jsonl.zstd')
+      try {
+        const info = await stat(file)
+        if (info.mtimeMs >= sinceMs) n++
+      } catch {
+        // 目录里没有这个文件：不是每一代格式都叫这个名字，跳过即可。
+      }
+    }
+  }
+  return n
+}
+
+/** 人读的字节差：`12.0KB → 10.0KB（-2.0KB）`。 */
+export function formatDelta(before, after) {
+  const kb = (n) => `${(n / 1024).toFixed(1)}KB`
+  const d = after.bytes - before.bytes
+  const sign = d > 0 ? '+' : ''
+  return `${kb(before.bytes)} → ${kb(after.bytes)}（${sign}${(d / 1024).toFixed(1)}KB）`
+}
+
+/** 操作类型的中文名（声明表格里给人看）。 */
+export const OP_LABEL = { create: '新建', update: '改写', archive: '归档' }

package/lib/autodream-audit.js

@@ -1,229 +1,270 @@
-/**
- * sage-mem autodream — 记忆目录审计（七查）。
- *
- * 审计清单内置在 host 侧，让 autodream 每次跑完都能自证
- * 没把记忆改坏（七项，外加「读不动」单列一类）：
- *   1. 索引悬空 —— MEMORY.md 指向不存在的文件
- *   2. 漏索引   —— 存在但没进索引的记忆文件
- *   3. type 与前缀不一致（分类看 type，前缀骗不了它）
- *   4. CRLF     —— 「某个 Windows 编辑器碰过」的可疑信号
- *   5. 双链断链 —— [[目标]] 找不到对应文件或 frontmatter name
- *   6. 未加引号值里的「空格+#」—— 会被 YAML 当注释吞掉，解析不报错但描述残缺
- *
- * **纯只读**：不修任何东西。修哪条、怎么修，由 autodream agent 或人决定。
- *
- * 这一份解析是 sage-mem 宿主侧 parseFrontmatter 的同源精简版，故意不共用：
- * 那边带着一长串历史坑的注释与行为（baseline、type 回落），审计只读不写，
- * 重复二十行换零回归风险是划算的。
- */
-
-import { readdir, readFile } from 'node:fs/promises'
-import { join } from 'node:path'
-
-/** 索引文件名。它本身不是一条记忆，是索引。 */
-const INDEX_FILE = 'MEMORY.md'
-
-/**
- * 非记忆条目：不是四类记忆、也不该套「type 与前缀一致」这条规则。
- *
- * session-log.md 是追加型流水，逐会话的账本而不是一条记忆；
- * 它没有 `user_/feedback_/project_/reference_` 前缀，扫进来只会白白读一大坨
- * 再报一条假问题（2026-09-27 实测：报出 `session-log.md type=reference`）。
- * 同理 MEMORY.md 是索引本身，只作为链接来源读，不作为被审对象。
- */
-const NON_ENTRY_FILES = new Set(['session-log.md'])
-
-/** YAML 行形态：`key: value`（顶层键，不含缩进的嵌套行）。 */
-const YAML_LEAF_RE = /^[A-Za-z0-9_.-]+:\s*(.*)$/
-
-/**
- * 极简 frontmatter 解析，读法与 宿主侧一致：
- * 顶层 `type:` 优先，没有才下钻 `metadata.type:`。
- * @param {string} content — 文件全文
- * @returns {{name: string, description: string, type: string, hasFrontmatter: boolean}}
- */
-export function parseFrontmatterLite(content) {
-  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
-  if (!m) return { name: '', description: '', type: '', hasFrontmatter: false }
-  const body = m[1]
-  const grab = (key) => {
-    const hit = body.match(new RegExp(`^${key}:[ \\t]*(.+?)[ \\t\\r]*$`, 'm'))
-    return hit ? hit[1].replace(/^["']|["']$/g, '').trim() : ''
-  }
-  const nested = body.match(/^metadata:\s*\r?\n(?:\s+[^\r\n]+\r?\n)*?\s+type:\s*(\S+)/m)
-  const type = grab('type') || (nested ? nested[1] : '')
-  return {
-    name: grab('name'),
-    description: grab('description'),
-    type: String(type).trim(),
-    hasFrontmatter: true,
-  }
-}
-
-/**
- * 抽 MEMORY.md 里的相对链接目标（`](file.md)` / `](file.md#L12)`）。
- * @param {string} indexText
- * @returns {string[]} 去重后的文件名列表
- */
-export function indexTargets(indexText) {
-  const out = new Set()
-  for (const m of indexText.matchAll(/\]\(([^)]+\.md)(?:#[^)]*)?\)/g)) {
-    const raw = m[1].trim()
-    // 跳过外链与子目录路径：索引只指根目录下的记忆文件。
-    if (/^[a-z]+:\/\//i.test(raw) || raw.includes('/') || raw.includes('\\')) continue
-    out.add(raw)
-  }
-  return [...out]
-}
-
-/**
- * 扫一个目录下的记忆文件（不含子目录 —— 归档区就该扫不到）。
- * @param {string} dir
- * @returns {Promise<{files: string[], indexText: string}>}
- */
-async function readDirSnapshot(dir) {
-  let entries
-  entries = await readdir(dir, { withFileTypes: true })
-  const all = entries
-    .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
-    .map((e) => e.name)
-  const files = all.filter((f) => !NON_ENTRY_FILES.has(f.toLowerCase()))
-  let indexText = ''
-  try {
-    indexText = await readFile(join(dir, INDEX_FILE), 'utf8')
-  } catch (err) {
-    if (err?.code !== 'ENOENT') throw err
-  }
-  return { files, all, skipped: all.length - files.length, indexText }
-}
-
-/**
- * 七查主入口。
- * @param {string} dir — 记忆根目录
- * @returns {Promise<object>} 结构化审计结果（problems 是六项之和）
- */
-export async function auditMemoryDir(dir) {
-  const { files, all, skipped, indexText } = await readDirSnapshot(dir)
-  const entries = files.filter((f) => f !== INDEX_FILE)
-
-  const targets = indexTargets(indexText)
-  const targetSet = new Set(targets.map((t) => t.toLowerCase()))
-  // 悬空判定用 `all`（含 session-log.md）：索引万一真引用了它，那是索引的问题，
-  // 不该因为「审计不检查 session-log」而被顺手放过。
-  const allSet = new Set(all.map((f) => f.toLowerCase()))
-
-  const dangling = targets.filter((t) => !allSet.has(t.toLowerCase()))
-  const unlisted = entries.filter((f) => !targetSet.has(f.toLowerCase()))
-
-  const typeMismatch = []
-  const crlf = []
-  const hashHazards = []
-  const brokenLinks = []
-  const noFrontmatter = []
-  const linkKeys = new Set()
-
-  const contents = new Map()
-  /**
-   * 读不动的文件（权限、被占用、编码坏）。
-   *
-   * **绝不抛**：`run()` 把「运行前审计」当作开工前置，裸抛一个 EPERM 会让
-   * 「有个文件读不了」升级成「自动整理整个停摆」，而且报出来的是宿主内部的原文。
-   * 它们单列一类，**不参与**后面每一项检查 —— 免得被戴上「没 frontmatter」「CRLF」的帽子
-   */
-  const unreadable = []
-  for (const f of files) {
-    try {
-      contents.set(f, await readFile(join(dir, f), 'utf8'))
-    } catch {
-      unreadable.push(f)
-    }
-  }
-  const readable = files.filter((f) => contents.has(f))
-  for (const f of readable) {
-    const meta = parseFrontmatterLite(contents.get(f))
-    if (meta.name) linkKeys.add(meta.name.trim())
-  }
-  for (const f of readable) linkKeys.add(f)
-  for (const f of readable) linkKeys.add(f.replace(/\.md$/, ''))
-
-  for (const f of readable) {
-    const raw = contents.get(f)
-    if (raw.includes('\r')) crlf.push(f)
-    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)
-    if (!fmMatch) {
-      noFrontmatter.push(f)
-    } else {
-      const meta = parseFrontmatterLite(raw)
-      const prefix = f.split('_')[0]
-      const effective = meta.type || 'reference'
-      if (effective !== prefix) {
-        typeMismatch.push({ file: f, type: meta.type || '(缺失)', prefix, effective })
-      }
-      for (const line of fmMatch[1].split(/\r?\n/)) {
-        const mv = line.match(YAML_LEAF_RE)
-        if (mv && !/^["']/.test(mv[1]) && / #/.test(mv[1])) {
-          hashHazards.push({ file: f, line: line.trim().slice(0, 100) })
-        }
-      }
-    }
-    for (const m of raw.matchAll(/\[\[([^\]]+)\]\]/g)) {
-      const target = m[1].trim()
-      if (!linkKeys.has(target)) brokenLinks.push({ file: f, target })
-    }
-  }
-
-  const problems =
-    dangling.length +
-    unlisted.length +
-    typeMismatch.length +
-    crlf.length +
-    brokenLinks.length +
-    hashHazards.length +
-    noFrontmatter.length +
-    unreadable.length
-
-  return {
-    dir,
-    fileCount: entries.length,
-    skipped,
-    indexEntries: targets.length,
-    dangling: dangling.map((file) => ({ file })),
-    unlisted: unlisted.map((file) => ({ file })),
-    typeMismatch,
-    crlf: crlf.map((file) => ({ file })),
-    brokenLinks,
-    hashHazards,
-    noFrontmatter: noFrontmatter.map((file) => ({ file })),
-    unreadable: unreadable.map((file) => ({ file })),
-    problems,
-  }
-}
-
-/**
- * 把审计结果压成给模型看的短文本（autodream 工具返回值 / 报告附录都用它）。
- * @param {object} report — auditMemoryDir 的返回值
- * @param {number} [limit] — 每个分项最多列几条
- * @returns {string}
- */
-export function formatAudit(report, limit = 12) {
-  const lines = [
-    `扫描 ${report.fileCount} 个记忆文件 · 索引 ${report.indexEntries} 条 · 问题合计 ${report.problems}`,
-  ]
-  const section = (title, rows, render) => {
-    if (!rows.length) return
-    lines.push(`${title} (${rows.length})`)
-    for (const r of rows.slice(0, limit)) lines.push(`  - ${render(r)}`)
-    if (rows.length > limit) lines.push(`  … 另有 ${rows.length - limit} 条`)
-  }
-  section('索引悬空', report.dangling, (r) => r.file)
-  section('漏索引', report.unlisted, (r) => r.file)
-  section('type 与前缀不一致', report.typeMismatch, (r) => `${r.file} type=${r.type} 前缀=${r.prefix}`)
-  section('CRLF', report.crlf, (r) => r.file)
-  section('双链断链', report.brokenLinks, (r) => `${r.file} -> [[${r.target}]]`)
-  section('未加引号的「空格+#」', report.hashHazards, (r) => `${r.file} :: ${r.line}`)
-  section('无 frontmatter', report.noFrontmatter, (r) => r.file)
-  // 读不动的单列，且排最后：它不是「这条记忆写错了」，是「我没读到它」——
-  // 别让模型以为去改改 frontmatter 就能好。
-  section('读不动（权限/占用/编码，不参与上面各项检查）', report.unreadable ?? [], (r) => r.file)
-  return lines.join('\n')
-}
+/**
+ * sage-mem autodream — 记忆目录审计（七查）。
+ *
+ * 审计清单内置在 host 侧，让 autodream 每次跑完都能自证
+ * 没把记忆改坏（七项，外加「读不动」单列一类）：
+ *   1. 索引悬空 —— MEMORY.md 指向不存在的文件
+ *   2. 漏索引   —— 存在但没进索引的记忆文件
+ *   3. type 与前缀不一致（分类看 type，前缀骗不了它）
+ *   4. CRLF     —— 「某个 Windows 编辑器碰过」的可疑信号
+ *   5. 双链断链 —— [[目标]] 找不到对应文件或 frontmatter name
+ *   6. 未加引号值里的「空格+#」—— 会被 YAML 当注释吞掉，解析不报错但描述残缺
+ *
+ * **归档区（`archive/`）不是审计对象**，只贡献「名字池」：正文里指向已归档记忆的
+ * `[[链接]]` 单列成 `archivedLinks`（提示），**不计入 problems** —— 归档是「静默失效
+ * 且可回退」，不是删除。不这么分，归档越多假红灯越多。
+ *
+ * **纯只读**：不修任何东西。修哪条、怎么修，由 autodream agent 或人决定。
+ *
+ * 这一份解析是 sage-mem 宿主侧 parseFrontmatter 的同源精简版，故意不共用：
+ * 那边带着一长串历史坑的注释与行为（baseline、type 回落），审计只读不写，
+ * 重复二十行换零回归风险是划算的。
+ */
+
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** 索引文件名。它本身不是一条记忆，是索引。 */
+const INDEX_FILE = 'MEMORY.md'
+
+/**
+ * 非记忆条目：不是四类记忆、也不该套「type 与前缀一致」这条规则。
+ *
+ * session-log.md 是追加型流水，逐会话的账本而不是一条记忆；
+ * 它没有 `user_/feedback_/project_/reference_` 前缀，扫进来只会白白读一大坨
+ * 再报一条假问题（实测：报出 `session-log.md type=reference`）。
+ * 同理 MEMORY.md 是索引本身，只作为链接来源读，不作为被审对象。
+ */
+const NON_ENTRY_FILES = new Set(['session-log.md'])
+
+/** 归档区目录名（与 autodream-tools.js 的 ARCHIVE_DIR、宿主侧 memory/scan.js 同名）。 */
+const ARCHIVE_DIR = 'archive'
+
+/** YAML 行形态：`key: value`（顶层键，不含缩进的嵌套行）。 */
+const YAML_LEAF_RE = /^[A-Za-z0-9_.-]+:\s*(.*)$/
+
+/**
+ * 极简 frontmatter 解析，读法与 宿主侧一致：
+ * 顶层 `type:` 优先，没有才下钻 `metadata.type:`。
+ * @param {string} content — 文件全文
+ * @returns {{name: string, description: string, type: string, hasFrontmatter: boolean}}
+ */
+export function parseFrontmatterLite(content) {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!m) return { name: '', description: '', type: '', hasFrontmatter: false }
+  const body = m[1]
+  const grab = (key) => {
+    const hit = body.match(new RegExp(`^${key}:[ \\t]*(.+?)[ \\t\\r]*$`, 'm'))
+    return hit ? hit[1].replace(/^["']|["']$/g, '').trim() : ''
+  }
+  const nested = body.match(/^metadata:\s*\r?\n(?:\s+[^\r\n]+\r?\n)*?\s+type:\s*(\S+)/m)
+  const type = grab('type') || (nested ? nested[1] : '')
+  return {
+    name: grab('name'),
+    description: grab('description'),
+    type: String(type).trim(),
+    hasFrontmatter: true,
+  }
+}
+
+/**
+ * 抽 MEMORY.md 里的相对链接目标（`](file.md)` / `](file.md#L12)`）。
+ * @param {string} indexText
+ * @returns {string[]} 去重后的文件名列表
+ */
+export function indexTargets(indexText) {
+  const out = new Set()
+  for (const m of indexText.matchAll(/\]\(([^)]+\.md)(?:#[^)]*)?\)/g)) {
+    const raw = m[1].trim()
+    // 跳过外链与子目录路径：索引只指根目录下的记忆文件。
+    if (/^[a-z]+:\/\//i.test(raw) || raw.includes('/') || raw.includes('\\')) continue
+    out.add(raw)
+  }
+  return [...out]
+}
+
+/**
+ * 扫一个目录下的记忆文件（不含子目录 —— 归档区就该扫不到），
+ * 外加归档区的**名字池**（只有名字，不做检查）。
+ * @param {string} dir
+ * @returns {Promise<{files: string[], all: string[], skipped: number, indexText: string, archiveKeys: Set<string>, archiveCount: number}>}
+ */
+async function readDirSnapshot(dir) {
+  let entries
+  entries = await readdir(dir, { withFileTypes: true })
+  const all = entries
+    .filter((e) => e.isFile() && e.name.toLowerCase().endsWith('.md'))
+    .map((e) => e.name)
+  const files = all.filter((f) => !NON_ENTRY_FILES.has(f.toLowerCase()))
+  let indexText = ''
+  try {
+    indexText = await readFile(join(dir, INDEX_FILE), 'utf8')
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err
+  }
+  // 归档区：文件名、去掉 .md 的名字、以及 frontmatter 里的 `name`。
+  // 内容读不动只少一个名字，绝不让整场审计失败 —— 归档区本来就不是被审对象。
+  const archiveKeys = new Set()
+  let archiveCount = 0
+  try {
+    const archived = await readdir(join(dir, ARCHIVE_DIR), { withFileTypes: true })
+    for (const e of archived) {
+      if (!e.isFile() || !e.name.toLowerCase().endsWith('.md')) continue
+      archiveCount++
+      archiveKeys.add(e.name)
+      archiveKeys.add(e.name.replace(/\.md$/i, ''))
+      try {
+        const meta = parseFrontmatterLite(await readFile(join(dir, ARCHIVE_DIR, e.name), 'utf8'))
+        if (meta.name) archiveKeys.add(meta.name.trim())
+      } catch {
+        /* 读不动：名字池少一条而已 */
+      }
+    }
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err
+  }
+  return { files, all, skipped: all.length - files.length, indexText, archiveKeys, archiveCount }
+}
+
+/**
+ * 七查主入口。
+ * @param {string} dir — 记忆根目录
+ * @returns {Promise<object>} 结构化审计结果（problems 是六项之和）
+ */
+export async function auditMemoryDir(dir) {
+  const { files, all, skipped, indexText, archiveKeys, archiveCount } = await readDirSnapshot(dir)
+  const entries = files.filter((f) => f !== INDEX_FILE)
+
+  const targets = indexTargets(indexText)
+  const targetSet = new Set(targets.map((t) => t.toLowerCase()))
+  // 悬空判定用 `all`（含 session-log.md）：索引万一真引用了它，那是索引的问题，
+  // 不该因为「审计不检查 session-log」而被顺手放过。
+  const allSet = new Set(all.map((f) => f.toLowerCase()))
+
+  const dangling = targets.filter((t) => !allSet.has(t.toLowerCase()))
+  const unlisted = entries.filter((f) => !targetSet.has(f.toLowerCase()))
+
+  const typeMismatch = []
+  const crlf = []
+  const hashHazards = []
+  const brokenLinks = []
+  const archivedLinks = []
+  const noFrontmatter = []
+  const linkKeys = new Set()
+
+  const contents = new Map()
+  /**
+   * 读不动的文件（权限、被占用、编码坏）。
+   *
+   * **绝不抛**：`run()` 把「运行前审计」当作开工前置，裸抛一个 EPERM 会让
+   * 「有个文件读不了」升级成「自动整理整个停摆」，而且报出来的是宿主内部的原文。
+   * 它们单列一类，**不参与**后面每一项检查 —— 免得被戴上「没 frontmatter」「CRLF」的帽子
+   */
+  const unreadable = []
+  for (const f of files) {
+    try {
+      contents.set(f, await readFile(join(dir, f), 'utf8'))
+    } catch {
+      unreadable.push(f)
+    }
+  }
+  const readable = files.filter((f) => contents.has(f))
+  for (const f of readable) {
+    const meta = parseFrontmatterLite(contents.get(f))
+    if (meta.name) linkKeys.add(meta.name.trim())
+  }
+  for (const f of readable) linkKeys.add(f)
+  for (const f of readable) linkKeys.add(f.replace(/\.md$/, ''))
+
+  for (const f of readable) {
+    const raw = contents.get(f)
+    if (raw.includes('\r')) crlf.push(f)
+    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+    if (!fmMatch) {
+      noFrontmatter.push(f)
+    } else {
+      const meta = parseFrontmatterLite(raw)
+      const prefix = f.split('_')[0]
+      const effective = meta.type || 'reference'
+      if (effective !== prefix) {
+        typeMismatch.push({ file: f, type: meta.type || '(缺失)', prefix, effective })
+      }
+      for (const line of fmMatch[1].split(/\r?\n/)) {
+        const mv = line.match(YAML_LEAF_RE)
+        if (mv && !/^["']/.test(mv[1]) && / #/.test(mv[1])) {
+          hashHazards.push({ file: f, line: line.trim().slice(0, 100) })
+        }
+      }
+    }
+    for (const m of raw.matchAll(/\[\[([^\]]+)\]\]/g)) {
+      const target = m[1].trim()
+      if (linkKeys.has(target)) continue
+      // 指向归档区的链接：单列提示、不计问题 —— 归档不是删除，目标还在库里躺着。
+      if (archiveKeys.has(target)) {
+        archivedLinks.push({ file: f, target })
+        continue
+      }
+      brokenLinks.push({ file: f, target })
+    }
+  }
+
+  const problems =
+    dangling.length +
+    unlisted.length +
+    typeMismatch.length +
+    crlf.length +
+    brokenLinks.length +
+    hashHazards.length +
+    noFrontmatter.length +
+    unreadable.length
+
+  return {
+    dir,
+    fileCount: entries.length,
+    skipped,
+    archivedCount: archiveCount,
+    indexEntries: targets.length,
+    dangling: dangling.map((file) => ({ file })),
+    unlisted: unlisted.map((file) => ({ file })),
+    typeMismatch,
+    crlf: crlf.map((file) => ({ file })),
+    brokenLinks,
+    // 指向归档的链接是提示，**不进 problems**（见文件头那段）。
+    archivedLinks,
+    hashHazards,
+    noFrontmatter: noFrontmatter.map((file) => ({ file })),
+    unreadable: unreadable.map((file) => ({ file })),
+    problems,
+  }
+}
+
+/**
+ * 把审计结果压成给模型看的短文本（autodream 工具返回值 / 报告附录都用它）。
+ * @param {object} report — auditMemoryDir 的返回值
+ * @param {number} [limit] — 每个分项最多列几条
+ * @returns {string}
+ */
+export function formatAudit(report, limit = 12) {
+  const lines = [
+    `扫描 ${report.fileCount} 个记忆文件 · 索引 ${report.indexEntries} 条 · 问题合计 ${report.problems}`,
+  ]
+  const section = (title, rows, render) => {
+    if (!rows.length) return
+    lines.push(`${title} (${rows.length})`)
+    for (const r of rows.slice(0, limit)) lines.push(`  - ${render(r)}`)
+    if (rows.length > limit) lines.push(`  … 另有 ${rows.length - limit} 条`)
+  }
+  section('索引悬空', report.dangling, (r) => r.file)
+  section('漏索引', report.unlisted, (r) => r.file)
+  section('type 与前缀不一致', report.typeMismatch, (r) => `${r.file} type=${r.type} 前缀=${r.prefix}`)
+  section('CRLF', report.crlf, (r) => r.file)
+  section('双链断链', report.brokenLinks, (r) => `${r.file} -> [[${r.target}]]`)
+  // 指向归档单列且写明「不计问题」：否则模型会去「修」一条本来正确的链接。
+  section('指向已归档（提示，不计入问题）', report.archivedLinks ?? [], (r) => `${r.file} -> [[${r.target}]]`)
+  section('未加引号的「空格+#」', report.hashHazards, (r) => `${r.file} :: ${r.line}`)
+  section('无 frontmatter', report.noFrontmatter, (r) => r.file)
+  // 读不动的单列，且排最后：它不是「这条记忆写错了」，是「我没读到它」——
+  // 别让模型以为去改改 frontmatter 就能好。
+  section('读不动（权限/占用/编码，不参与上面各项检查）', report.unreadable ?? [], (r) => r.file)
+  return lines.join('\n')
+}