memory-eternal 0.20.0 → 0.22.0

package/lib/vault.js

@@ -341,7 +341,7 @@ export async function listCards(root, { status, kind, agent, tag = '', limit, of
       rows.push(...db.prepare(`SELECT * FROM ${store.table} WHERE path IN (${ph})`).all(...paths))
     }
     const byPath = new Map(rows.map((r) => [r.path, rowToCard(r)]))
-    return page.map((r) => byPath.get(r.path)).filter(Boolean)
+    return attachRevisions(db, page.map((r) => byPath.get(r.path)).filter(Boolean))
   }
 
   const tail = Number.isInteger(limit) && limit > 0
@@ -355,7 +355,7 @@ export async function listCards(root, { status, kind, agent, tag = '', limit, of
     { kind, agent, tag, tail },
   )
   const finalArgs = Number.isInteger(limit) && limit > 0 ? [...args, limit, Math.max(0, offset | 0)] : args
-  return db.prepare(sql).all(...finalArgs).map(rowToCard)
+  return attachRevisions(db, db.prepare(sql).all(...finalArgs).map(rowToCard))
 }
 
 /** 计数（分页接口要用 total 判断还有没有下一页）。 */
@@ -464,12 +464,15 @@ export async function readCard(root, rel, { allowUnapproved = false } = {}) {
   }
   const status = String(row.status || '')
   const { text } = rowToMarkdown(row)
+  // 修改副本要带上「改的是哪张卡」，审核界面据此标注「修改」而不是「新卡」。
+  const rev = getRevision(db, rel)
+  const revision = rev ? { targetPath: rev.target_path, targetId: rev.target_id } : null
   const updates = db.prepare('SELECT content, created_at FROM card_updates WHERE card_id = ? ORDER BY created_at ASC').all(row.id)
   if (updates.length > 0) {
     const updateLines = updates.map((u) => `- ${u.created_at.slice(0, 10)}：${u.content}`)
-    return { path: rel, status, store: mainRow ? 'main' : 'quarantine', text: text + '\n## 更新记录\n\n' + updateLines.join('\n') + '\n' }
+    return { path: rel, status, store: mainRow ? 'main' : 'quarantine', text: text + '\n## 更新记录\n\n' + updateLines.join('\n') + '\n', ...(revision ? { revision } : {}) }
   }
-  return { path: rel, status, store: mainRow ? 'main' : 'quarantine', text }
+  return { path: rel, status, store: mainRow ? 'main' : 'quarantine', text, ...(revision ? { revision } : {}) }
 }
 
 /** 状态中文标签（错误信息与日志用）。 */
@@ -499,6 +502,11 @@ export async function deleteCard(root, rel, { permanent = false } = {}) {
         db.prepare('DELETE FROM card_updates WHERE card_id = ?').run(id)
         db.prepare('DELETE FROM feedback WHERE card_path = ?').run(rel)
       }
+      // 修改副本与原卡的关联也一起清掉：删原卡时，指向它的待审副本没有应用对象了
+      const revs = db.prepare('SELECT revision_path FROM card_revisions WHERE target_path = ?').all(rel)
+      for (const r of revs) db.prepare('DELETE FROM quarantine WHERE path = ?').run(r.revision_path)
+      db.prepare('DELETE FROM card_revisions WHERE target_path = ?').run(rel)
+      db.prepare('DELETE FROM card_revisions WHERE revision_path = ?').run(rel)
       db.prepare('DELETE FROM cards WHERE path = ?').run(rel)
       db.prepare('DELETE FROM quarantine WHERE path = ?').run(rel)
     })
@@ -522,6 +530,8 @@ export async function restoreCard(root, rel) {
   const db = getDb(root)
   const existing = db.prepare('SELECT status FROM quarantine WHERE path = ?').get(rel)
   if (!existing) throw new Error('卡片不在回收站/隔离区: ' + rel)
+  // 修改副本不能「恢复」成一张独立卡 —— 那会跟原卡重复。它只能被批准（覆盖原卡）或删除。
+  if (getRevision(db, rel)) throw new Error('这是知识卡的修改副本：请在审核中心「批准」以覆盖原卡，或直接删除')
   const r = moveCardBetweenStores(db, 'quarantine', 'cards', rel, { status: MAIN_STATUS, deletedAt: null })
   db.prepare('INSERT INTO audit_log (card_path, old_status, new_status, changed_by, reason) VALUES (?, ?, ?, ?, ?)').run(rel, existing.status, MAIN_STATUS, 'restore', '回收站恢复')
   return { ok: true, restored: true, ...r }
@@ -539,6 +549,12 @@ export async function setCardStatus(root, rel, status, { changedBy = 'system', r
   const existing = findCardRow(db, rel)
   if (!existing) throw new Error('卡片不存在: ' + rel)
 
+  // 审核制修改：待审副本被批准 = 用副本内容覆盖原卡（身份/状态/类型不变），副本随即消失。
+  if (target === MAIN_STATUS && existing.table === 'quarantine') {
+    const rev = getRevision(db, rel)
+    if (rev) return applyRevision(db, rel, rev, { changedBy, reason })
+  }
+
   if (target === MAIN_STATUS) {
     if (existing.table === 'cards') {
       db.prepare('UPDATE cards SET status = ?, updated_at = ? WHERE path = ?').run(target, new Date().toISOString(), rel)
@@ -702,6 +718,99 @@ export async function updateCardContent(root, rel, { title, tags, body, reason }
   return { ok: true, path: rel, store: found.table, updated: now }
 }
 
+// ── 审核制修改（agent 提交 → 人工审核 → 覆盖原卡）────────────────────────
+
+/** 查「待审副本 → 原卡」映射；不是修改副本时返回 null。 */
+function getRevision(db, revisionPath) {
+  return db.prepare('SELECT * FROM card_revisions WHERE revision_path = ?').get(revisionPath) || null
+}
+
+/** 给卡片对象挂上 revision 信息（审核中心据此标「修改」而不是「新卡」）。 */
+function attachRevisions(db, cards) {
+  if (!cards.length) return cards
+  const ph = cards.map(() => '?').join(',')
+  const rows = db.prepare(`SELECT revision_path, target_path, target_id FROM card_revisions WHERE revision_path IN (${ph})`).all(...cards.map((c) => c.path))
+  if (!rows.length) return cards
+  const byPath = new Map(rows.map((r) => [r.revision_path, r]))
+  const targets = [...new Set(rows.map((r) => r.target_path))]
+  const tph = targets.map(() => '?').join(',')
+  const titles = new Map(db.prepare(`SELECT path, title FROM cards WHERE path IN (${tph})`).all(...targets).map((r) => [r.path, r.title]))
+  return cards.map((c) => {
+    const r = byPath.get(c.path)
+    return r ? { ...c, revision: { targetPath: r.target_path, targetId: r.target_id, targetTitle: titles.get(r.target_path) || '' } } : c
+  })
+}
+
+/**
+ * 提交一张「审核制修改」：把已批准的卡片复制一份到隔离区（status=pending），
+ * 内容用调用方给的新标题/标签/正文。**这里绝不改原卡** —— 只有审核通过（setCardStatus）
+ * 才会用副本覆盖原卡。agent 走 /card/revise 或 MCP memory_revise，只能到这一步。
+ *
+ * 同一张卡已有待审修改时就地更新，避免审核队列里堆一串同一张卡的副本。
+ */
+export async function reviseCard(root, { target, title, tags, body, reason = '', source = '', submittedBy = '' } = {}) {
+  const db = getDb(root)
+  const rel = String(target || '').trim()
+  if (!rel) throw new Error('缺少要修改的卡片 path')
+  const found = findCardRow(db, rel)
+  if (!found) throw new Error('原卡片不存在: ' + rel)
+  if (found.table !== 'cards') throw new Error('只能修改已审核通过的卡片（当前状态：' + found.row.status + '）')
+  const targetRow = found.row
+  // 已有待审修改时，未传的字段沿用副本当前值（否则第二次提交会把上次的改动抹掉）
+  const pending = db.prepare('SELECT q.* FROM card_revisions r JOIN quarantine q ON q.path = r.revision_path WHERE r.target_path = ? AND q.status = ?').get(rel, 'pending')
+  const baseRow = pending || targetRow
+  const nextTitle = title === undefined ? baseRow.title : String(title).trim()
+  const nextTags = tags === undefined ? normalizeTags(baseRow.tags) : normalizeTags(tags)
+  const nextBody = body === undefined ? String(baseRow.body).trim() : String(body).trim()
+  if (!nextTitle) throw new Error('标题不能为空')
+  if (!nextBody) throw new Error('正文不能为空')
+  const now = new Date().toISOString()
+  if (pending) {
+    db.prepare('UPDATE quarantine SET title = ?, tags = ?, body = ?, summary = ?, updated_at = ?, reason = ? WHERE path = ?')
+      .run(nextTitle, JSON.stringify(nextTags), nextBody, nextBody.slice(0, 200), now, reason || pending.reason || '', pending.path)
+    db.prepare('UPDATE card_revisions SET updated_at = ? WHERE revision_path = ?').run(now, pending.path)
+    return { ok: true, path: pending.path, target: rel, targetId: targetRow.id, reused: true, status: 'pending' }
+  }
+  // 副本放在独立目录 99-Revisions/：不与任何 kind 根目录冲突，也永远不会被当成新卡批准进主库
+  const base = `99-Revisions/${safeSlug(targetRow.title || 'card')}`
+  let revisionPath = `${base}.md`
+  let i = 2
+  while (pathTaken(db, revisionPath)) { revisionPath = `${base}-${i}.md`; i++ }
+  const id = nextCardId(db)
+  db.prepare(`
+    INSERT INTO quarantine
+      (id, path, kind, title, tags, body, summary, status, source, submitted_by, severity, reason, created_at, updated_at, quarantined_at, quarantine_reason)
+    VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, 'info', ?, ?, ?, datetime('now'), '修改待审')
+  `).run(id, revisionPath, targetRow.kind, nextTitle, JSON.stringify(nextTags), nextBody, nextBody.slice(0, 200), source, submittedBy, reason || ('修改知识卡：' + rel), now, now)
+  db.prepare('INSERT INTO card_revisions (revision_path, target_path, target_id, created_at, updated_at) VALUES (?, ?, ?, ?, ?)').run(revisionPath, rel, targetRow.id, now, now)
+  db.prepare('INSERT INTO audit_log (card_path, old_status, new_status, changed_by, reason) VALUES (?, ?, ?, ?, ?)').run(revisionPath, null, 'pending', submittedBy || 'agent', '提交修改：' + rel)
+  return { ok: true, path: revisionPath, target: rel, targetId: targetRow.id, reused: false, status: 'pending' }
+}
+
+/**
+ * 审核通过修改副本：用副本内容覆盖原卡，副本及其映射一起消失。
+ * 只改内容（标题 / 标签 / 正文 / 摘要 + updated_at）；状态、类型、来源、创建时间仍属原卡。
+ */
+function applyRevision(db, revisionPath, rev, { changedBy = 'user', reason = '' } = {}) {
+  return inTransaction(db, () => {
+    const revRow = db.prepare('SELECT * FROM quarantine WHERE path = ?').get(revisionPath)
+    if (!revRow) throw new Error('修改副本不存在: ' + revisionPath)
+    const target = db.prepare('SELECT * FROM cards WHERE path = ?').get(rev.target_path)
+    if (!target) throw new Error('原卡片已不存在（可能已被删除）：' + rev.target_path)
+    const now = new Date().toISOString()
+    const tags = normalizeTags(revRow.tags)
+    db.prepare('UPDATE cards SET title = ?, tags = ?, body = ?, summary = ?, updated_at = ? WHERE path = ?')
+      .run(revRow.title, JSON.stringify(tags), revRow.body, String(revRow.body).trim().slice(0, 200), now, rev.target_path)
+    db.prepare('INSERT INTO card_updates (card_id, content, created_at) VALUES (?, ?, ?)')
+      .run(target.id, '经审核修改：' + (reason || ('由 ' + (revRow.submitted_by || 'agent') + ' 提交，' + changedBy + ' 批准')), now)
+    db.prepare('DELETE FROM quarantine WHERE path = ?').run(revisionPath)
+    db.prepare('DELETE FROM card_revisions WHERE revision_path = ?').run(revisionPath)
+    db.prepare('INSERT INTO audit_log (card_path, old_status, new_status, changed_by, reason) VALUES (?, ?, ?, ?, ?)')
+      .run(rev.target_path, MAIN_STATUS, MAIN_STATUS, changedBy, '应用修改（来源 ' + revisionPath + '）')
+    return { ok: true, status: MAIN_STATUS, store: 'cards', applied: true, path: rev.target_path, revisionPath, updated: now }
+  })
+}
+
 /** 合并多张卡为一张。 */
 export async function mergeCards(root, paths) {
   const list = (Array.isArray(paths) ? paths : []).map((p) => String(p || '').trim()).filter(Boolean)
@@ -1100,6 +1209,673 @@ export async function graphAll(roots) {
   return { nodes, edges }
 }
 
+// ---- 星球分层视图：按层请求的规划（纯函数，可单测）--------------------------------
+//
+// 为什么需要：2049 张卡一次性返回 nodes+edges（实测 2049 节点 / 10106 条边），
+// 前端也一次性渲染全部节点 —— 首屏是一团墨点，既看不清也点不准，10k 时更不可能。
+// 现在改成「一层一层看」：
+//   · 根层按 kind 折叠：某类 >200 张 → 一颗带环大星球；≤200 张 → 逐颗小星球；
+//     根层图元 >500 时把「最小的 kind」依次并进「其他」桶（每并一个类，图元数减少 size-1）；
+//   · 进入某类 / 某个语义簇后：集合 ≤1000 张直接铺卡片；>1000 张按语义簇（标签优先）
+//     拆成 ≤20 颗大星球，逐级下钻（每个大星球仍 >1000 时继续按同样规则拆）；
+//   · 语义聚类没有有效信号（标签太散/没有标签）时回退：按权重（更新时间）等分 ≤20 块。
+//
+// 「这一层显示什么」全部是 planGraphLevel 这组纯函数算出来的：路由层只负责读库 + 缓存，
+// 于是 10k 规模的分层规则能在单测里穷举，不必真的点进浏览器。
+export const LEVEL_MAX_ITEMS = 1000 // 单层图元上限（再多就分簇）
+export const ROOT_BIG_KIND_MIN = 200 // 某类 >200 张 → 一颗大星球（严格大于）
+export const ROOT_MAX_ITEMS = 500 // 根层图元上限（超出 → 最小 kind 合并「其他」）
+export const MAX_CLUSTERS = 20 // 一层最多几颗语义簇大星球
+export const CLUSTER_TARGET_SIZE = 250 // 语义簇目标体量（决定分几簇）
+export const LEVEL_EDGE_LIMIT = 2400 // 单层边上限（与 payload 红线一起兜住传输量）
+export const PLANET_EDGE_LIMIT = 1200 // 星球层聚合边上限（共享标签关系网，卡片折叠后仍保留「连线」视觉）
+export const LEVEL_PAYLOAD_LIMIT = 1024 * 1024 // 单次层响应 payload 上限：1MB
+
+const LEVEL_KIND_LABELS = {
+  core: '核心记忆', skill: '技能', project: '项目', knowledge: '知识', content: '内容',
+  prompt: '提示词', business: '业务', tool: '工具', mistake: '教训', other: '其他',
+}
+const LEVEL_KIND_KEYS = {
+  core: 'kindCore', skill: 'kindSkill', project: 'kindProject', knowledge: 'kindKnowledge',
+  content: 'kindContent', prompt: 'kindPrompt', business: 'kindBusiness', tool: 'kindTool',
+  mistake: 'kindMistake', other: 'graphOther',
+}
+
+/**
+ * 分层请求的错误分类：调用方（lib/api.js）按 code 决定 HTTP 状态。
+ *   LEVEL_PATH  —— 路径写错（客户端可纠正）→ 400 + 原文案
+ *   LEVEL_STALE —— 语义簇已变化（卡片增删导致）→ 400 + 提示返回上一层
+ * 其余异常一律视为「未知内部错误」→ 500 + 通用文案（细节只进日志）。
+ */
+export const LEVEL_ERR_PATH = 'LEVEL_PATH'
+export const LEVEL_ERR_STALE = 'LEVEL_STALE'
+
+function levelPathError(message) {
+  const err = new Error(message)
+  err.code = LEVEL_ERR_PATH
+  return err
+}
+
+function levelStaleError(message) {
+  const err = new Error(message)
+  err.code = LEVEL_ERR_STALE
+  return err
+}
+
+/**
+ * 解析层级路径字符串（客户端 → 宿主的唯一寻址方式）。段之间用 `/` 分隔：
+ *   k:<kind>            某一类（如 k:project）
+ *   k:<kind1>,<kind2>   合并桶（如 k:content,mistake,skill → 「其他」）
+ *   t:<tag>[#n]         按标签聚出来的语义簇（n = 大标签拆片序号）
+ *   g:<n>               按权重等分出来的兜底块
+ * 非法段直接抛错（调用方转成 400 + 明确文案），不做「猜一个」的兜底。
+ */
+export function parseLevelPath(pathStr) {
+  const raw = String(pathStr == null ? '' : pathStr).trim()
+  if (!raw) return []
+  return raw.split('/').filter(Boolean).map((seg) => {
+    if (seg.startsWith('k:')) {
+      const kinds = seg.slice(2).split(',').map((s) => s.trim()).filter(Boolean)
+      if (!kinds.length) throw levelPathError('层级路径缺少 kind：' + seg)
+      return { type: 'kind', id: seg, kinds }
+    }
+    if (seg.startsWith('t:') || seg.startsWith('g:')) return { type: 'cluster', id: seg }
+    throw levelPathError('无法识别的层级路径段：' + seg)
+  })
+}
+
+/** 把段数组拼回路径字符串（客户端面包屑用它返回上层）。 */
+export function encodeLevelPath(segments) {
+  return (Array.isArray(segments) ? segments : []).map((s) => (typeof s === 'string' ? s : s && s.id)).filter(Boolean).join('/')
+}
+
+function levelCardItem(card) {
+  return {
+    type: 'card',
+    id: String(card.id || card.path || ''),
+    label: String(card.title || card.id || ''),
+    kind: card.kind || 'other',
+    updated: card.updated || '',
+    tags: Array.isArray(card.tags) ? card.tags.slice(0, 8) : [],
+  }
+}
+
+function levelPlanetItem({ id, kind, kinds, label, labelKey, count, by }) {
+  return {
+    type: 'planet',
+    id,
+    kind: kind || 'other',
+    kinds: Array.isArray(kinds) && kinds.length > 1 ? kinds.slice() : null,
+    label: label || '',
+    labelKey: labelKey || '',
+    count: Math.max(0, Math.floor(Number(count) || 0)),
+    by: by || 'kind',
+  }
+}
+
+/** 根层：按 kind 折叠 + 超限合并「其他」。纯函数，返回这一层的图元。 */
+export function planRootLevel(cards, opts = {}) {
+  const bigMin = opts.bigKindMin === undefined ? ROOT_BIG_KIND_MIN : opts.bigKindMin
+  const rootMax = opts.rootMaxItems === undefined ? ROOT_MAX_ITEMS : opts.rootMaxItems
+  const groups = new Map()
+  for (const c of Array.isArray(cards) ? cards : []) {
+    const kind = c.kind || 'other'
+    const g = groups.get(kind)
+    if (g) g.cards.push(c)
+    else groups.set(kind, { kind, cards: [c] })
+  }
+  const bigGroups = []
+  const smallGroups = []
+  for (const g of groups.values()) (g.cards.length > bigMin ? bigGroups : smallGroups).push(g)
+  // 先算账（不在数组里反复删除）：大类占 1 个图元，小类逐颗展开占 size 个
+  let total = bigGroups.length
+  for (const g of smallGroups) total += g.cards.length
+  const merged = []
+  const mergedSet = new Set()
+  let mergedCount = 0
+  const queue = smallGroups
+    .map((g) => ({ kind: g.kind, size: g.cards.length }))
+    .sort((a, b) => a.size - b.size || String(a.kind).localeCompare(String(b.kind)))
+  while (total > rootMax && queue.length) {
+    const g = queue.shift()
+    merged.push(g.kind)
+    mergedSet.add(g.kind)
+    mergedCount += g.size
+    // 这一类原来占 size 个图元（逐颗小星球）；并进「其他」后：
+    //   少掉 size 个，同时「其他」桶自己第一次出现时占 1 个 —— 所以净减少 size，首次再 +1
+    total -= g.size
+    if (merged.length === 1) total += 1
+  }
+  // 保险（>500 个「大 kind」，实盘不会出现）：除最大的一类外全部并成一颗
+  if (total > rootMax) {
+    const bigLeft = bigGroups.filter((g) => !mergedSet.has(g.kind))
+    if (bigLeft.length > 1) {
+      const sorted = bigLeft.slice().sort((a, b) => a.cards.length - b.cards.length || String(a.kind).localeCompare(String(b.kind)))
+      const keep = sorted[sorted.length - 1]
+      for (const g of sorted) {
+        if (g === keep) continue
+        merged.push(g.kind)
+        mergedSet.add(g.kind)
+        mergedCount += g.cards.length
+      }
+      total = 1 + (mergedCount ? 1 : 0)
+    }
+  }
+  const items = []
+  for (const g of bigGroups) {
+    if (mergedSet.has(g.kind)) continue
+    items.push(levelPlanetItem({
+      id: 'k:' + g.kind, kind: g.kind, label: LEVEL_KIND_LABELS[g.kind] || g.kind,
+      labelKey: LEVEL_KIND_KEYS[g.kind] || 'kindKnowledge', count: g.cards.length, by: 'kind',
+    }))
+  }
+  for (const g of smallGroups) {
+    if (mergedSet.has(g.kind)) continue
+    for (const c of g.cards) items.push(levelCardItem(c))
+  }
+  if (merged.length) {
+    items.push(levelPlanetItem({
+      id: 'k:' + merged.slice().sort().join(','), kinds: merged.slice().sort(), kind: 'other',
+      label: '其他', labelKey: 'graphOther', count: mergedCount, by: 'merged',
+    }))
+  }
+  return {
+    mode: 'root',
+    total: Array.isArray(cards) ? cards.length : 0,
+    items,
+    unit: 'root',
+    bigKinds: bigGroups.filter((g) => !mergedSet.has(g.kind)).map((g) => g.kind),
+    mergedKinds: merged.slice(),
+    rootLimit: rootMax,
+    bigKindMin: bigMin,
+  }
+}
+
+function cardWeight(card) {
+  const t = Number(card && (card.mtime || Date.parse(card.updated || '') || 0))
+  return Number.isFinite(t) ? t : 0
+}
+
+function pickClusterKind(cards) {
+  const counts = new Map()
+  for (const c of cards) counts.set(c.kind || 'other', (counts.get(c.kind || 'other') || 0) + 1)
+  let best = 'other'
+  let n = -1
+  for (const [k, v] of counts) if (v > n || (v === n && String(k) < String(best))) { best = k; n = v }
+  return best
+}
+
+/**
+ * 语义簇：标签优先，标签没有有效信号时按权重（更新时间）等分。
+ * 返回的簇 id 是**确定性**的（同一份卡片集合必定得到同样的 id），所以下钻时能原样复算。
+ * @param {Array<object>} cards
+ * @param {{maxClusters?:number, targetSize?:number}} opts
+ * @returns {Array<{id:string,label:string,kind:string,count:number,cards:Array<object>,by:string}>}
+ */
+export function planClusters(cards, opts = {}) {
+  const list = Array.isArray(cards) ? cards : []
+  const n = list.length
+  if (!n) return []
+  const maxClusters = Math.max(2, Math.floor(opts.maxClusters || MAX_CLUSTERS))
+  const target = Math.max(1, Math.floor(opts.targetSize || CLUSTER_TARGET_SIZE))
+  const wanted = Math.min(maxClusters, Math.max(2, Math.ceil(n / target)))
+  const cap = Math.max(1, Math.ceil(n / wanted))
+  const ordered = list.slice().sort((a, b) => cardWeight(b) - cardWeight(a) || String(a.id || '').localeCompare(String(b.id || '')))
+  const tagCount = new Map()
+  for (const c of ordered) for (const t of Array.isArray(c.tags) ? c.tags : []) tagCount.set(t, (tagCount.get(t) || 0) + 1)
+  const tags = [...tagCount.entries()]
+    .filter(([, cnt]) => cnt >= 2)
+    .sort((a, b) => b[1] - a[1] || String(a[0]).localeCompare(String(b[0])))
+  // 语义信号门槛：最强的标签至少覆盖 2%（且 ≥3 张），否则「按标签分簇」只是把噪声切成小块
+  const signal = tags.length > 0 && tags[0][1] >= Math.max(3, Math.ceil(n * 0.02))
+  const clusters = []
+  const assigned = new Set()
+  if (signal) {
+    // 给「没标签的卡」预留至少 1 个名额，否则它们会被标签簇挤掉
+    const untagged = ordered.filter((c) => !(Array.isArray(c.tags) && c.tags.length)).length
+    const tagBudget = Math.max(1, wanted - (untagged > 0 ? 1 : 0))
+    for (const [tag] of tags) {
+      if (clusters.length >= tagBudget) break
+      const members = ordered.filter((c) => !assigned.has(c.id) && Array.isArray(c.tags) && c.tags.includes(tag))
+      if (members.length < 2) continue
+      for (let i = 0; i < members.length && clusters.length < tagBudget; i += cap) {
+        const part = members.slice(i, i + cap)
+        // 名额守恒：拿这一簇之后，剩下的卡还必须有地方放（每块 ≤ cap）。
+        // 少了这一步，「最热的几个标签」会把 20 个名额吃光，剩下的卡最后挤成一颗巨球。
+        const restAfter = n - assigned.size - part.length
+        const slotsNeededAfter = Math.ceil(restAfter / cap)
+        if (clusters.length + 1 + slotsNeededAfter > wanted) break
+        for (const c of part) assigned.add(c.id)
+        const partNo = i / cap + 1
+        clusters.push({
+          id: partNo === 1 ? 't:' + tag : 't:' + tag + '#' + partNo,
+          label: partNo === 1 ? '#' + tag : '#' + tag + ' · ' + partNo,
+          kind: pickClusterKind(part),
+          count: part.length,
+          cards: part,
+          by: 'tag',
+        })
+      }
+    }
+  }
+  // 剩下没被标签覆盖的卡：按权重等分成 ≤ 剩余名额 的若干块
+  const rest = ordered.filter((c) => !assigned.has(c.id))
+  if (rest.length) {
+    const slots = Math.max(1, Math.min(maxClusters - clusters.length, Math.ceil(rest.length / cap)))
+    const chunk = Math.ceil(rest.length / slots)
+    for (let i = 0; i < rest.length; i += chunk) {
+      const part = rest.slice(i, i + chunk)
+      clusters.push({
+        id: 'g:' + (clusters.length + 1),
+        label: signal ? '其他卡片' : '第 ' + (clusters.length + 1) + ' 组',
+        kind: pickClusterKind(part),
+        count: part.length,
+        cards: part,
+        by: 'weight',
+      })
+    }
+  }
+  // 保险（标签拆片把名额用超时）：合并「最小的两颗」，不把某一颗喂成吞掉全库的巨兽
+  while (clusters.length > maxClusters) {
+    let i1 = 0
+    for (let i = 1; i < clusters.length; i++) if (clusters[i].count < clusters[i1].count) i1 = i
+    let i2 = i1 === 0 ? 1 : 0
+    for (let i = 0; i < clusters.length; i++) if (i !== i1 && clusters[i].count < clusters[i2].count) i2 = i
+    const a = Math.min(i1, i2)
+    const b = Math.max(i1, i2)
+    clusters[b].cards = clusters[b].cards.concat(clusters[a].cards)
+    clusters[b].count += clusters[a].count
+    clusters.splice(a, 1)
+  }
+  return clusters
+}
+
+/**
+ * 星球层（根层 / 语义簇层）的聚合连线：按「共享标签」给可见图元连边。
+ * 大星球用它成员卡片的标签并集参与，所以即使卡片被折叠，关系网也不会消失 ——
+ * 这是旧版图谱最核心的视觉，星球层不能没有。纯函数，便于单测。
+ * @param {Array<object>} items 本层图元（planet/card）
+ * @param {{tagSets?:Map<string,Set<string>>, excludes?:Map<string,string>, limit?:number, maxPerNode?:number}} opts
+ */
+export function planetLevelEdges(items, opts = {}) {
+  const limit = Math.max(0, Math.floor(opts.limit === undefined ? PLANET_EDGE_LIMIT : opts.limit))
+  const maxPerNode = Math.max(1, Math.floor(opts.maxPerNode || 8))
+  const tagSets = opts.tagSets || new Map()
+  const excludes = opts.excludes || new Map()
+  const list = (Array.isArray(items) ? items : []).filter((it) => it && it.id)
+  const scored = []
+  for (let i = 0; i < list.length; i++) {
+    const a = list[i]
+    const sa = tagSets.get(a.id)
+    if (!sa || !sa.size) continue
+    for (let j = i + 1; j < list.length; j++) {
+      const b = list[j]
+      const sb = tagSets.get(b.id)
+      if (!sb || !sb.size) continue
+      const exA = excludes.get(a.id)
+      const exB = excludes.get(b.id)
+      let score = 0
+      let shared = ''
+      for (const t of sa) {
+        if (t === exA || t === exB) continue
+        if (sb.has(t)) { score += 1; if (!shared) shared = t }
+      }
+      if (score > 0) scored.push({ a: a.id, b: b.id, score, tag: shared })
+    }
+  }
+  // 分数高的先连；每个图元最多 maxPerNode 条，避免少数热标签把整层连成毛线球
+  scored.sort((x, y) => y.score - x.score || String(x.a).localeCompare(String(y.a)) || String(x.b).localeCompare(String(y.b)))
+  const deg = new Map()
+  const seen = new Set()
+  const edges = []
+  for (const s of scored) {
+    const da = deg.get(s.a) || 0
+    const db = deg.get(s.b) || 0
+    if (da >= maxPerNode || db >= maxPerNode) continue
+    const key = s.a < s.b ? s.a + '\u0000' + s.b : s.b + '\u0000' + s.a
+    if (seen.has(key)) continue
+    seen.add(key)
+    deg.set(s.a, da + 1)
+    deg.set(s.b, db + 1)
+    edges.push({ source: s.a, target: s.b, type: 'tag', tag: s.tag, weight: s.score })
+    if (edges.length >= limit) break
+  }
+  return edges
+}
+
+/** 层内边：共享标签 TopK 连边（与全量图谱同一语义，只是限流到 LEVEL_EDGE_LIMIT 条）。 */
+export function levelEdges(items, opts = {}) {
+  const limit = Math.max(0, Math.floor(opts.limit === undefined ? LEVEL_EDGE_LIMIT : opts.limit))
+  const perTag = Math.max(2, Math.floor(opts.perTag || 6))
+  const byTag = new Map()
+  for (const it of Array.isArray(items) ? items : []) {
+    if (!it || it.type !== 'card') continue
+    for (const t of Array.isArray(it.tags) ? it.tags : []) {
+      const arr = byTag.get(t)
+      if (arr) arr.push(it.id)
+      else byTag.set(t, [it.id])
+    }
+  }
+  const seen = new Set()
+  const edges = []
+  for (const [tag, ids] of byTag) {
+    if (ids.length < 2) continue
+    const k = Math.min(perTag, ids.length)
+    for (let i = 0; i < k; i++) {
+      for (let j = i + 1; j < k; j++) {
+        const a = String(ids[i])
+        const b = String(ids[j])
+        const key = a < b ? a + '\u0000' + b : b + '\u0000' + a
+        if (seen.has(key)) continue
+        seen.add(key)
+        edges.push({ source: ids[i], target: ids[j], type: 'tag', tag })
+        if (edges.length >= limit) return edges
+      }
+    }
+  }
+  return edges
+}
+
+/**
+ * 算出「这一层该显示什么」。纯函数：传入全部卡片 + 路径段，返回图元、面包屑、统计。
+ * @param {Array<{id:string,title:string,kind:string,tags:string[],updated:string,mtime?:number}>} cards
+ * @param {Array<string|{type:string,id:string,kinds?:string[]}>} segments
+ * @param {{maxItems?:number,rootMaxItems?:number,bigKindMin?:number,maxClusters?:number,targetSize?:number,edgeLimit?:number}} opts
+ */
+export function planGraphLevel(cards, segments = [], opts = {}) {
+  const all = Array.isArray(cards) ? cards : []
+  const maxItems = Math.max(1, Math.floor(opts.maxItems || LEVEL_MAX_ITEMS))
+  const parsed = (Array.isArray(segments) ? segments : []).map((s) => (typeof s === 'string' ? parseLevelPath(s)[0] : s)).filter(Boolean)
+  let scope = all
+  const crumbs = [{ id: '', label: '全部', labelKey: 'graphAllCrumb', path: '', kinds: null, count: all.length }]
+  for (const seg of parsed) {
+    const prev = crumbs[crumbs.length - 1]
+    const nextPath = prev.path ? prev.path + '/' + seg.id : seg.id
+    if (seg.type === 'kind') {
+      scope = scope.filter((c) => seg.kinds.includes(c.kind || 'other'))
+      const single = seg.kinds.length === 1
+      crumbs.push({
+        id: seg.id,
+        label: single ? (LEVEL_KIND_LABELS[seg.kinds[0]] || seg.kinds[0]) : '其他',
+        labelKey: single ? (LEVEL_KIND_KEYS[seg.kinds[0]] || 'kindKnowledge') : 'graphOther',
+        path: nextPath,
+        kinds: seg.kinds,
+        count: scope.length,
+      })
+    } else {
+      const clusters = planClusters(scope, { maxClusters: opts.maxClusters, targetSize: opts.targetSize })
+      const hit = clusters.find((cl) => cl.id === seg.id)
+      // 卡片集合变了（新增/删除）→ 旧簇 id 失效：明确报错，让客户端回到上一层重取，而不是显示空层
+      if (!hit) throw levelStaleError('语义簇已变化，请返回上一层重试：' + seg.id)
+      scope = hit.cards
+      crumbs.push({ id: seg.id, label: hit.label, labelKey: '', path: nextPath, kinds: null, count: scope.length })
+    }
+  }
+  const levelId = parsed.map((s) => s.id).join('/')
+  let level
+  let clusterList = null
+  if (!parsed.length) {
+    const root = planRootLevel(all, opts)
+    level = { id: '', ...root }
+  } else if (scope.length <= maxItems) {
+    level = {
+      id: levelId,
+      mode: 'cards',
+      total: scope.length,
+      unit: 'card',
+      items: scope.map((c) => levelCardItem(c)),
+    }
+  } else {
+    clusterList = planClusters(scope, { maxClusters: opts.maxClusters, targetSize: opts.targetSize })
+    level = {
+      id: levelId,
+      mode: 'clusters',
+      total: scope.length,
+      unit: 'cluster',
+      items: clusterList.map((cl) => levelPlanetItem({
+        // 图元 id 就是路径段（t:tag / g:1）：下钻时原样拼进 path，宿主按同一份集合复算即可
+        id: cl.id, kind: cl.kind, label: cl.label, labelKey: '', count: cl.count, by: cl.by,
+      })),
+      clusterIds: clusterList.map((cl) => cl.id),
+    }
+  }
+  // 连线是旧版图谱的核心视觉，星球层也不能省：用「共享标签」把可见图元连起来。
+  // 大星球的标签取它成员卡片的并集；语义簇层排除「簇名本身的标签」，否则同源簇会全部两两相连。
+  let edges
+  if (level.mode === 'cards') {
+    edges = levelEdges(level.items, { limit: opts.edgeLimit })
+  } else {
+    const tagSets = new Map()
+    const excludes = new Map()
+    if (level.mode === 'root') {
+      const byKind = new Map()
+      for (const c of all) {
+        const k = c.kind || 'other'
+        const arr = byKind.get(k)
+        if (arr) arr.push(c)
+        else byKind.set(k, [c])
+      }
+      for (const it of level.items) {
+        if (it.type === 'card') {
+          tagSets.set(it.id, new Set(Array.isArray(it.tags) ? it.tags : []))
+        } else {
+          const kinds = Array.isArray(it.kinds) && it.kinds.length ? it.kinds : [String(it.id).slice(2)]
+          const set = new Set()
+          for (const k of kinds) for (const c of byKind.get(k) || []) for (const t of c.tags || []) set.add(t)
+          tagSets.set(it.id, set)
+        }
+      }
+    } else {
+      for (const it of level.items) {
+        const cl = clusterList && clusterList.find((x) => x.id === it.id)
+        const set = new Set()
+        for (const c of (cl ? cl.cards : [])) for (const t of c.tags || []) set.add(t)
+        tagSets.set(it.id, set)
+        const m = String(it.id).match(/^t:([^#]+)/)
+        if (m) excludes.set(it.id, m[1])
+      }
+    }
+    edges = planetLevelEdges(level.items, { tagSets, excludes, limit: opts.planetEdgeLimit })
+  }
+  return {
+    path: levelId,
+    crumbs,
+    level: { ...level, edges },
+    stats: {
+      items: level.items.length,
+      edges: edges.length,
+      total: all.length,
+      scope: scope.length,
+      maxItems,
+      rootLimit: opts.rootMaxItems === undefined ? ROOT_MAX_ITEMS : opts.rootMaxItems,
+      maxClusters: opts.maxClusters === undefined ? MAX_CLUSTERS : opts.maxClusters,
+    },
+  }
+}
+
+// 分层接口的缓存：按（库 + 指纹 + 路径）失效，不是 TTL —— 任何写卡都会改变指纹。
+// 上界是双重的（条数 + 字节）：单层响应最大 1MB，只按条数限（48 条）最坏也要 ~48MB，
+// 热缓存不该这么吃内存。超预算时从最久未用的那条开始淘汰。
+export const LEVEL_CACHE_MAX = 48
+export const LEVEL_CACHE_MAX_BYTES = 16 * 1024 * 1024
+export const LEVEL_CARDS_CACHE_MAX_ROOTS = 8
+const levelCache = new Map() // cacheKey -> { payload, bytes }
+const levelCardsCache = new Map() // root -> { fp, cards }
+let levelCacheBytes = 0
+// 生效中的上界：生产恒为上面的常量；单测用 setLevelCacheLimits() 临时收紧来验证淘汰逻辑。
+let levelLimitEntries = LEVEL_CACHE_MAX
+let levelLimitBytes = LEVEL_CACHE_MAX_BYTES
+
+/** 测试/诊断用：清空分层缓存（不影响图谱主缓存，也不动上界）。 */
+export function resetLevelCache() {
+  levelCache.clear()
+  levelCardsCache.clear()
+  levelCacheBytes = 0
+}
+
+/**
+ * 只读缓存账本：条数与字节数都必须有界（回归测试直接断言它）。
+ * @returns {{levelEntries:number, levelBytes:number, levelMaxEntries:number, levelMaxBytes:number, cardsRoots:number, cardsMaxRoots:number}}
+ */
+export function levelCacheStats() {
+  return {
+    levelEntries: levelCache.size,
+    levelBytes: levelCacheBytes,
+    levelMaxEntries: levelLimitEntries,
+    levelMaxBytes: levelLimitBytes,
+    cardsRoots: levelCardsCache.size,
+    cardsMaxRoots: LEVEL_CARDS_CACHE_MAX_ROOTS,
+  }
+}
+
+/**
+ * 测试/诊断用：临时调整缓存上界（生产默认 48 条 / 16MB；传 0/缺省表示恢复默认）。
+ * 用来在单测里用很小的预算验证「字节上限会触发淘汰」，不必真的灌满 16MB。
+ * @returns 生效后的上界
+ */
+export function setLevelCacheLimits(opts = {}) {
+  const max = Math.floor(Number(opts.maxEntries))
+  const maxBytes = Math.floor(Number(opts.maxBytes))
+  levelLimitEntries = Number.isFinite(max) && max > 0 ? max : LEVEL_CACHE_MAX
+  levelLimitBytes = Number.isFinite(maxBytes) && maxBytes > 0 ? maxBytes : LEVEL_CACHE_MAX_BYTES
+  while (levelCache.size > levelLimitEntries) evictOldestLevelCache()
+  while (levelCacheBytes > levelLimitBytes && levelCache.size > 0) evictOldestLevelCache()
+  return { maxEntries: levelLimitEntries, maxBytes: levelLimitBytes }
+}
+
+function evictOldestLevelCache() {
+  const oldest = levelCache.keys().next().value
+  if (oldest === undefined) return
+  const rec = levelCache.get(oldest)
+  levelCache.delete(oldest)
+  if (rec) levelCacheBytes -= rec.bytes
+}
+
+function levelCacheGet(key) {
+  const hit = levelCache.get(key)
+  if (!hit) return null
+  // LRU：Map 的插入序就是淘汰序，命中即刷新热度
+  levelCache.delete(key)
+  levelCache.set(key, hit)
+  return hit
+}
+
+function levelCacheSet(key, payload, bytes) {
+  const prev = levelCache.get(key)
+  if (prev) {
+    levelCacheBytes -= prev.bytes
+    levelCache.delete(key)
+  }
+  levelCache.set(key, { payload, bytes })
+  levelCacheBytes += bytes
+  // 条数上限 / 字节上限：从最久未用的那条开始淘汰
+  while (levelCacheBytes > levelLimitBytes && levelCache.size > 1) evictOldestLevelCache()
+  while (levelCache.size > levelLimitEntries) evictOldestLevelCache()
+  // 单条本身就超预算：连它也不留（本次响应照常返回）—— 保证字节账永远有界
+  if (levelCacheBytes > levelLimitBytes) {
+    const rec = levelCache.get(key)
+    if (rec) {
+      levelCache.delete(key)
+      levelCacheBytes -= rec.bytes
+    }
+  }
+}
+
+function readLevelCards(db) {
+  // 只取分层需要的列（不读 body）：10k 卡时整表扫描仍是个位数毫秒
+  const rows = db.prepare('SELECT path, kind, title, tags, updated_at FROM cards').all()
+  return rows.map((r) => ({
+    id: r.path,
+    path: r.path,
+    title: r.title || '',
+    kind: r.kind || 'other',
+    tags: normalizeTags(r.tags),
+    updated: r.updated_at || '',
+    mtime: new Date(r.updated_at || 0).getTime() || 0,
+  }))
+}
+
+function levelCardsFor(roots) {
+  const entries = []
+  for (const r of roots) {
+    const db = getDb(r.root)
+    const fp = graphFingerprint(db)
+    // 与 graphCache 同款：键是**库根**，命中后再比对指纹。
+    // 旧实现把指纹拼进 key —— 每写一张卡指纹就变，于是每次写卡都白留一整份全库卡片
+    // （10k 卡时是几 MB/次），长期运行等于慢性泄漏。
+    let entry = levelCardsCache.get(r.root)
+    if (!entry || entry.fp !== fp) {
+      entry = { fp, cards: readLevelCards(db) }
+      levelCardsCache.delete(r.root)
+      levelCardsCache.set(r.root, entry)
+      while (levelCardsCache.size > LEVEL_CARDS_CACHE_MAX_ROOTS) {
+        const oldest = levelCardsCache.keys().next().value
+        levelCardsCache.delete(oldest)
+      }
+    } else {
+      // LRU：同一个库刚用过，挪到队尾
+      levelCardsCache.delete(r.root)
+      levelCardsCache.set(r.root, entry)
+    }
+    entries.push({ name: r.name || '', fp, cards: entry.cards })
+  }
+  const fingerprint = entries.map((e) => (e.name || '') + ':' + e.fp).join('|')
+  const cards = []
+  const seen = new Set()
+  for (const e of entries) {
+    const pref = e.name ? e.name + '::' : ''
+    for (const c of e.cards) {
+      const id = pref + c.id
+      if (seen.has(id)) continue
+      seen.add(id)
+      cards.push(pref ? { ...c, id, path: id } : c)
+    }
+  }
+  return { fingerprint, cards }
+}
+
+/**
+ * 分层图谱：一次只返回「一层」的图元（≤1000）与层内边，客户端按层请求。
+ * 与 graph() 的关系：graph() 仍是全量图（导出/诊断/兼容旧客户端），分层视图只走这里。
+ * @param {string} root 当前库根
+ * @param {{path?:string, roots?:Array<{name:string,root:string}>, plan?:object}} opts
+ * @returns {Promise<{ok:true, path:string, crumbs:Array, level:object, stats:object}>}
+ */
+export async function graphLevel(root, opts = {}) {
+  const started = Date.now()
+  const pathStr = String(opts.path == null ? '' : opts.path).trim()
+  const roots = Array.isArray(opts.roots) && opts.roots.length ? opts.roots : [{ name: '', root }]
+  const segments = parseLevelPath(pathStr) // 非法路径直接抛（调用方转 400）
+  const { fingerprint, cards } = levelCardsFor(roots)
+  const cacheKey = fingerprint + '\u0000' + pathStr
+  const hit = levelCacheGet(cacheKey)
+  if (hit) return { ...hit.payload, stats: { ...hit.payload.stats, cached: true, ms: Date.now() - started } }
+  const plan = planGraphLevel(cards, segments, opts.plan || {})
+  // payload 守卫：先砍边；极端情况下（图元本身过大）如实标记 truncated，绝不静默假装没事
+  let bytes = Buffer.byteLength(JSON.stringify({ ok: true, ...plan }))
+  let edgesTrimmed = false
+  while (bytes > LEVEL_PAYLOAD_LIMIT && plan.level.edges.length > 0) {
+    plan.level.edges.length = Math.floor(plan.level.edges.length / 2)
+    edgesTrimmed = true
+    bytes = Buffer.byteLength(JSON.stringify({ ok: true, ...plan }))
+  }
+  const payload = {
+    ok: true,
+    ...plan,
+    stats: {
+      ...plan.stats,
+      edges: plan.level.edges.length,
+      edgesTrimmed,
+      bytes,
+      ms: Date.now() - started,
+      cached: false,
+      payloadLimit: LEVEL_PAYLOAD_LIMIT,
+    },
+  }
+  levelCacheSet(cacheKey, payload, bytes)
+  return payload
+}
+
 /** 跨库聚合检索。 */
 export async function searchAll(roots, query, opts = {}) {
   const out = []