@kira905/dsh-memory-toolkit 0.0.0-stage → 0.1.1

package/memory-engine/lib/doc-scan.mjs

@@ -0,0 +1,271 @@
+// 记忆引擎 v2 · 离线层 —— 文档扫描面 + 结构解析 + 粒度切分（方案 §3.2）
+//
+// 口径（逐条照方案，勿自行发挥）：
+//   · 扫描面 = `<docsRoot>/**/*.md`（默认 `<cwd>/docs`）
+//   · **排除** = `变更流水/`、`管家报告/`、`坑库/`、`_archive`（流水类噪音大且频繁变更）
+//   · `path` 列 = **相对 `dshRoot` 的路径**
+//   · 粒度：短文档（<2 万字）1 条；长文档按 `##` 小节聚合 **2~5 条**；长文档多条以 `path#§N` 作主键
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** docs 根（可注入；不写死机器名，方案 §4 宿主迁移契约）。 */
+export const DEFAULT_DOCS_ROOT = path.join(process.cwd(), 'docs');
+/** `path` 列的前缀锚（默认 = 当前工作目录）。 */
+export const DEFAULT_DSH_ROOT = process.cwd();
+
+/** 排除目录名（按路径"目录段"匹配，不按子串——否则 `_archive` 会误伤文件名）。 */
+export const EXCLUDE_DIRS = ['变更流水', '管家报告', '坑库', '_archive'];
+
+/** 长/短文档分界（方案 §3.2：短文档 < 2 万字 1 条）。 */
+export const LONG_DOC_CHARS = 20000;
+/** 长文档分条数区间（方案 §3.2：2~5 条）。 */
+export const MIN_LONG_ROWS = 2;
+export const MAX_LONG_ROWS = 5;
+/** 每条摘要上限（方案 §3.2：≤500 字）。 */
+export const SUMMARY_MAX_CHARS = 500;
+
+/**
+ * 首期 10 篇「最常用文档」——判据出处：`docs\文档总索引.md` §一「最常用的 15 份」**人工段**，
+ * 取该表前 10 条（1→10，顺序即优先级）。**不是随手挑的**：这一节由主人与本鱼共同维护，
+ * 是新会话的高频入口清单；首期先索引这 10 篇试水（方案 §3.2「中间态」+ §10 T2 全量触发器）。
+ * ⚠️ 全量 270+ 篇**不在本卡范围**（属 §10 T2 触发器事项，需主人拍）。
+ */
+export const FIRST_BATCH = [
+  'docs/主人使用手册.md',
+  'docs/DSH目录规范.md',
+  'docs/开发顺序统筹-20260914.md',
+  'docs/大管家-主人视角-一页纸-20260913.md',
+  'docs/大管家-开关矩阵与放行判据-20260913.md',
+  'docs/插件升级决策表.md',
+  'docs/插件魔改维护清单.md',
+  'docs/升级方案-2026-09-10.md',
+  'docs/自愈与回滚-验收缺口与整改方案-20260911.md',
+  'docs/gitee备份使用说明.md',
+];
+
+/** 首期清单的判据出处（写进 state 与交付报告，避免"这 10 篇哪来的"无处可查）。 */
+export const FIRST_BATCH_SOURCE = 'docs/文档总索引.md §一「最常用的 15 份」（人工段）前 10 条';
+
+/** 统一 `/` 分隔（Windows 反斜杠一律归一；`path` 列口径）。 */
+export function toPosix(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+/** 相对 `dshRoot` 的 path 口径（扫描面在 docs 下 ⇒ 结果以 `docs/` 开头）。 */
+export function toRelPath(absPath, dshRoot = DEFAULT_DSH_ROOT) {
+  return toPosix(path.relative(dshRoot, absPath));
+}
+
+/** 是否落在排除面内（只看**目录段**；顶层文件永不被排除）。 */
+export function isExcludedRel(relPath) {
+  const parts = toPosix(relPath).split('/');
+  const dirs = parts.slice(0, -1); // 去掉文件名
+  return dirs.some((d) => EXCLUDE_DIRS.includes(d));
+}
+
+/**
+ * 递归扫描扫描面（只读；不做 mtime 过滤——过滤交给差分逻辑）。
+ * @param {string} docsRoot
+ * @param {{dshRoot?:string, maxFiles?:number}} [opts]
+ * @returns {Array<{rel:string, abs:string, mtime:number, size:number}>}
+ */
+export function scanDocs(docsRoot = DEFAULT_DOCS_ROOT, opts = {}) {
+  const dshRoot = opts.dshRoot ?? DEFAULT_DSH_ROOT;
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return; // 目录不可读 → 跳过（fail-open，不打断别的扫描）
+    }
+    for (const e of entries) {
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (EXCLUDE_DIRS.includes(e.name)) continue; // 目录整棵排除
+        walk(abs);
+      } else if (e.isFile() && /\.md$/i.test(e.name)) {
+        let st;
+        try {
+          st = fs.statSync(abs);
+        } catch {
+          continue;
+        }
+        const rel = toRelPath(abs, dshRoot);
+        if (isExcludedRel(rel)) continue;
+        out.push({ rel, abs, mtime: Math.trunc(st.mtimeMs), size: st.size });
+      }
+    }
+  };
+  walk(docsRoot);
+  out.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+  return opts.maxFiles ? out.slice(0, opts.maxFiles) : out;
+}
+
+/** 读文档并算字符数（用于粒度判定与摘要生成）。 */
+export function readDoc(absPath) {
+  const text = fs.readFileSync(absPath, 'utf8');
+  return { text, chars: text.length };
+}
+
+// ---------------------------------------------------------------- 结构解析
+
+/** 去掉 markdown 内联标记（摘要里不要出现 `**`/反引号/链接语法）。 */
+export function stripMd(s) {
+  return String(s)
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`([^`]*)`/g, '$1')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/\*\*([^*]*)\*\*/g, '$1')
+    .replace(/(^|\s)[*_](\S[^*_]*)[*_]/g, '$1$2')
+    .replace(/^\s*>\s?/gm, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** 取首句（中文句读 + 英文句点；上限 maxChars 字，超长按字截断）。
+ *  ⚠️ 刻意**不含分号**：中文文档里分号常切出"主人 = 用户"这种半截短语，反而没信息量。 */
+export function firstSentence(text, maxChars = 80) {
+  const t = stripMd(text);
+  if (!t) return '';
+  const m = /^(.{4,}?[。！？!?]|.{4,}?\.\s|.{4,})/.exec(t);
+  let s = (m ? m[1] : t).trim();
+  s = s.replace(/[。！？!?]\s*$/, '').trim();
+  if (s.length > maxChars) s = `${s.slice(0, maxChars - 1)}…`;
+  return s;
+}
+
+/** 引言/章节的头几行里，这类"模板头 / 元信息"不算正文（否则每篇索引条都长一个样）。 */
+const META_LINE_RE = /^(?:\s*[>|])|^(?:维护人|创建|最近更新|最后更新|最后修订|更新时间|文件位置|路径口径|版本)\s*[:：]/;
+
+/**
+ * 取一节的正文首段（**跳过引用块 / 表格 / 标题 / 代码块**，去掉列表符号）。
+ * 为什么需要它：文档头部普遍是 `> ↑本主题总纲见 …` 这类模板引用块，
+ * 直接取首句会让所有索引条的"说明"完全雷同（实测），对召回毫无区分度。
+ */
+export function pickParagraph(body, maxChars = 400) {
+  const buf = [];
+  for (const raw of String(body ?? '').split(/\r?\n/)) {
+    const l = raw.trim();
+    if (!l) {
+      if (buf.length) break; // 段落结束
+      continue;
+    }
+    if (/^```/.test(l)) break;
+    if (/^#{1,6}\s/.test(l)) continue;
+    if (/^[-*_]{3,}$/.test(l)) continue; // 分隔线（--- / *** / ___）不是正文
+    if (META_LINE_RE.test(l) && !buf.length) continue; // 元信息/引用块：跳过继续找真正文
+    if (/^[>|]/.test(l)) continue;
+    if (/^[-*+]\s/.test(l)) {
+      if (buf.length) break;
+      buf.push(l.replace(/^[-*+]\s+/, ''));
+    } else {
+      buf.push(l);
+    }
+    if (buf.join(' ').length > maxChars) break;
+  }
+  return buf.join(' ').trim();
+}
+
+/** 章节标题瘦身（摘要里每节只留辨识度最高的前 28 字）。 */
+export function shortTitle(t, maxChars = 28) {
+  const s = stripMd(t);
+  return s.length > maxChars ? `${s.slice(0, maxChars - 1)}…` : s;
+}
+
+/**
+ * 解析 markdown 结构：`#` 标题、引言段、`##` 小节（含其下三级及正文）。
+ * 只认 `##`（方案 §3.2「按 `##` 小节聚合」）；`###` 归入所属 `##`。
+ * @returns {{title:string, intro:string, sections:Array<{title:string,chars:number,body:string}>}}
+ */
+export function parseStructure(text) {
+  const lines = String(text).split(/\r?\n/);
+  let title = '';
+  let introStart = 0;
+  let i = 0;
+  // 首个 H1 = 文档标题
+  for (; i < lines.length; i += 1) {
+    const m = /^#\s+(.+?)\s*$/.exec(lines[i]);
+    if (m) {
+      title = stripMd(m[1]);
+      introStart = i + 1;
+      break;
+    }
+  }
+  if (!title) {
+    // 无 H1：用第一行非空文本兜底（摘要头不至于空）
+    const firstLine = lines.find((l) => l.trim());
+    title = firstSentence(firstLine || '', 60);
+    introStart = 0;
+  }
+  const sections = [];
+  let introLines = [];
+  let cur = null;
+  for (let j = introStart; j < lines.length; j += 1) {
+    const line = lines[j];
+    const m2 = /^##\s+(.+?)\s*$/.exec(line);
+    if (m2) {
+      if (cur) sections.push(cur);
+      cur = { title: stripMd(m2[1]), body: [] };
+      continue;
+    }
+    if (cur) cur.body.push(line);
+    else introLines.push(line);
+  }
+  if (cur) sections.push(cur);
+  const normalized = sections.map((s) => {
+    const body = s.body.join('\n').trim();
+    return { title: s.title, chars: s.title.length + body.length, body };
+  });
+  return { title, intro: introLines.join('\n').trim(), sections: normalized };
+}
+
+/** 目标分条数：2 万字内 1 条；超出按字符规模升到 2~5 条，且不超过 `##` 小节数。 */
+export function planRowCount(chars, sectionCount) {
+  if (chars < LONG_DOC_CHARS) return 1;
+  const bySize = Math.round(chars / LONG_DOC_CHARS) + 1;
+  const target = Math.max(MIN_LONG_ROWS, Math.min(MAX_LONG_ROWS, bySize));
+  if (sectionCount < MIN_LONG_ROWS) return 1; // 没有可聚合的小节 ⇒ 只能 1 条
+  return Math.min(target, sectionCount);
+}
+
+/** 按 section **个数**均分（确定性、可复现；组数恰为 k）。 */
+export function splitSections(sections, k) {
+  const n = sections.length;
+  if (k <= 1 || n <= 1) return [sections];
+  const base = Math.floor(n / k);
+  const rem = n % k;
+  const groups = [];
+  let idx = 0;
+  for (let g = 0; g < k; g += 1) {
+    const take = base + (g < rem ? 1 : 0);
+    if (take === 0) continue;
+    groups.push(sections.slice(idx, idx + take));
+    idx += take;
+  }
+  if (idx < n) groups[groups.length - 1] = groups[groups.length - 1].concat(sections.slice(idx));
+  return groups;
+}
+
+/**
+ * 把一篇文档切成索引条计划。
+ * @param {{rel:string, chars:number, structure:ReturnType<typeof parseStructure>}} doc
+ * @returns {Array<{key:string, index:number, total:number, sections:Array, intro:string}>}
+ */
+export function planRows(doc) {
+  const { rel, chars, structure } = doc;
+  const k = planRowCount(chars, structure.sections.length);
+  if (k <= 1) {
+    return [{ key: rel, index: 0, total: 1, sections: structure.sections, intro: structure.intro }];
+  }
+  const groups = splitSections(structure.sections, k);
+  return groups.map((sections, i) => ({
+    key: `${rel}#§${i + 1}`,
+    index: i,
+    total: groups.length,
+    sections,
+    // 文档引言只在第 1 段带（避免 2~5 条里重复同一段话）
+    intro: i === 0 ? structure.intro : '',
+  }));
+}

package/memory-engine/lib/doc-summarize.mjs

@@ -0,0 +1,305 @@
+// 记忆引擎 v2 · 离线层 —— 索引条摘要生成（方案 §3.2 粒度 + §3.5 成本闸）
+//
+// 两条通路，**默认 rule（确定性抽取式，零外部调用）**：
+//   · `rule`  —— 从文档结构直接抽取（标题 + 关键章节 + 各节首句）。零成本、零外发、
+//     可复现（同一文档两次生成逐字节相同）⇒ 满足本卡「重建到与首跑一致」与「幂等」两条验收。
+//   · `llm`   —— 便宜模型批量润色（方案 §3.2 原语句「摘要生成：便宜模型批量（一次性成本）」）。
+//     **输入是压缩视图（骨架 + 各节首段截断），不是全文** ⇒ token 可控；受 §3.5 同一成本闸
+//     （调用 ≤20 次/日、token ≤150K/日、超限即停 + 日报一行）。
+// ⚠️ 家人相关数据不进第三方（方案 §3.5/§3.6 订正注：按 D2 从严读）——见 `assertNoFamilyContent`。
+import fs from 'node:fs';
+import { textHash } from './hashes.mjs';
+import { SUMMARY_MAX_CHARS, firstSentence, pickParagraph, shortTitle, stripMd } from './doc-scan.mjs';
+
+/** §3.5 成本闸（与提炼 job 同一上限；先定，实测后调）。 */
+export const LLM_LIMITS = { callsPerDay: 20, tokensPerDay: 150000 };
+
+/** 压缩视图上限（喂 LLM 的骨架文本；不是全文）。 */
+export const LLM_VIEW_MAX_CHARS = 4000;
+/** 单节在压缩视图里的截断长度。 */
+export const LLM_SECTION_PREVIEW_CHARS = 220;
+
+/** 规则摘要的片段预算（合计 ≤ SUMMARY_MAX_CHARS）。 */
+const BUDGET = {
+  head: 90,
+  chapters: 170,
+  points: 240,
+};
+
+// ---------------------------------------------------------------- 成本闸
+
+/** 当日成本台账的空态。 */
+export function emptyCost(date) {
+  return { date, calls: 0, tokens: 0 };
+}
+
+/** 跨日重置（口径：按**本机本地日期**分段）。 */
+export function rolloverCost(cost, date) {
+  if (!cost || cost.date !== date) return emptyCost(date);
+  return { date: cost.date, calls: Number(cost.calls) || 0, tokens: Number(cost.tokens) || 0 };
+}
+
+/**
+ * 成本闸判定（超限即停，不重试——方案 §3.5）。
+ * @returns {{allowed:boolean, reason:string}}
+ */
+export function checkCostGate(cost, limits = LLM_LIMITS) {
+  if (Number(cost?.calls) >= limits.callsPerDay) {
+    return { allowed: false, reason: `调用次数达上限 ${limits.callsPerDay}/日` };
+  }
+  if (Number(cost?.tokens) >= limits.tokensPerDay) {
+    return { allowed: false, reason: `token 达上限 ${limits.tokensPerDay}/日` };
+  }
+  return { allowed: true, reason: '' };
+}
+
+// ---------------------------------------------------------------- 规则摘要（默认）
+
+/** 摘要片段拼装：按预算装，装不下就丢尾（保证 ≤500 字且截断可预期）。 */
+function joinWithin(parts, maxChars) {
+  let out = '';
+  for (const p of parts) {
+    if (!p) continue;
+    const next = out ? `${out}${p}` : p;
+    if (next.length > maxChars) return out || next.slice(0, maxChars);
+    out = next;
+  }
+  return out;
+}
+
+/**
+ * 抽取式摘要（确定性：同一输入两次调用逐字节相同）。
+ * @param {{rel:string, structure:{title:string,intro:string,sections:Array}}} doc
+ * @param {{key:string,index:number,total:number,sections:Array, intro:string}} row
+ */
+export function buildRuleSummary(doc, row) {
+  const title = doc.structure.title || doc.rel;
+  const head =
+    row.total > 1
+      ? `【${title}】（第 ${row.index + 1}/${row.total} 段）`
+      : `【${title}】`;
+
+  const introLine = row.intro ? firstSentence(pickParagraph(row.intro, 300), 110) : '';
+  const chapters = row.sections.map((s) => shortTitle(s.title)).filter(Boolean);
+  const chapterLine = chapters.length ? `关键章节：${chapters.join('、')}` : '';
+
+  // 要点：每节首句（上限 5 条，每条 ≤70 字）
+  const points = [];
+  for (const s of row.sections) {
+    if (points.length >= 5) break;
+    const p = firstSentence(pickParagraph(s.body, 260), 70);
+    if (p) points.push(`${shortTitle(s.title, 20)}：${p}`);
+  }
+
+  const parts = [head];
+  if (introLine) parts.push(`说明：${introLine}`);
+  if (chapterLine) parts.push(chapterLine);
+  let summary = joinWithin(parts, BUDGET.head + BUDGET.chapters + 40).trim();
+  // 要点：**逐条装**——预算是硬的，但装不下只丢尾，绝不因为"整段超限"把要点全删
+  //（实测踩过：6 个长章节名吃掉 142 字后，原先的整段装法直接 return，索引条里一条要点都没有）
+  const remain = SUMMARY_MAX_CHARS - summary.length - 5;
+  if (points.length && remain > 30) {
+    let acc = '';
+    for (const p of points) {
+      const piece = `${acc ? '；' : ''}· ${p}`;
+      if (acc.length + piece.length > remain) break;
+      acc += piece;
+    }
+    if (acc) summary += ` 要点：${acc}`;
+  }
+  if (summary.length > SUMMARY_MAX_CHARS) summary = `${summary.slice(0, SUMMARY_MAX_CHARS - 1)}…`;
+  return summary.replace(/】(说明|关键章节|要点)：/g, '】 $1：');
+}
+
+// ---------------------------------------------------------------- LLM 通路（可选）
+
+/** 家族/隐私哨兵：输入里出现这些标记 ⇒ 停手申报（D2 从严读）。 */
+export const FAMILY_SENTINELS = ['家人档', '家人投喂', '家庭成员'];
+
+/**
+ * 压缩视图（喂 LLM 的输入）：标题 + 引言截断 + 各节标题 + 各节首段截断。
+ * **绝不送全文**（token 闸的物理前提）。
+ */
+export function buildLlmView(doc, { maxChars = LLM_VIEW_MAX_CHARS, previewChars = LLM_SECTION_PREVIEW_CHARS } = {}) {
+  const { title, intro, sections } = doc.structure;
+  const lines = [`文档：${doc.rel}`, `标题：${title}`];
+  const introS = firstSentence(pickParagraph(intro, 600), 300);
+  if (introS) lines.push(`引言：${introS}`);
+  lines.push('章节：');
+  for (const s of sections) {
+    const prev = firstSentence(pickParagraph(s.body, previewChars * 2), previewChars);
+    lines.push(`- ${s.title}${prev ? `：${prev}` : ''}`);
+  }
+  const text = lines.join('\n');
+  return text.length > maxChars ? `${text.slice(0, maxChars)}\n…[截断]` : text;
+}
+
+/** 压缩视图里的家人哨兵扫描（命中的路径名单；非空 ⇒ 调用方必须停手申报）。 */
+export function assertNoFamilyContent(doc) {
+  const hay = `${doc.rel}\n${doc.structure.title}\n${doc.structure.intro}\n${doc.structure.sections
+    .map((s) => `${s.title}\n${s.body}`)
+    .join('\n')}`;
+  return FAMILY_SENTINELS.filter((k) => hay.includes(k));
+}
+
+/** 提示词（要求 JSON 输出，逐条 ≤500 字）。 */
+export function buildLlmPrompt(doc, rows) {
+  const view = buildLlmView(doc);
+  const ask = rows
+    .map((r) => `  {"index": ${r.index}, "summary": "…"}`)
+    .join(',\n');
+  return [
+    '你在为一个本地文档索引库生成检索摘要。只输出 JSON，不要解释、不要代码块围栏。',
+    `文档路径：${doc.rel}`,
+    `要求：为下面 ${rows.length} 个分段各写一条中文摘要，每条 ≤500 字，必须包含：这段覆盖的关键章节名 + 这些章节讲什么。`,
+    '不要复述整篇文档；不要编造未出现的内容；不要输出 markdown 标题记号。',
+    `输出格式：{"rows": [\n${ask}\n]}`,
+    '',
+    '=== 文档骨架（压缩视图，非全文）===',
+    view,
+  ].join('\n');
+}
+
+/** 从模型回复里稳健地抽出 JSON（容忍 ```json 围栏与前后废话）。 */
+export function parseLlmRows(raw) {
+  const s = String(raw ?? '');
+  const fence = /```(?:json)?\s*([\s\S]*?)```/i.exec(s);
+  const body = fence ? fence[1] : s;
+  const start = body.indexOf('{');
+  const end = body.lastIndexOf('}');
+  if (start < 0 || end <= start) throw new Error('模型输出里找不到 JSON 对象');
+  const obj = JSON.parse(body.slice(start, end + 1));
+  const rows = Array.isArray(obj?.rows) ? obj.rows : null;
+  if (!rows) throw new Error('模型输出缺 rows 数组');
+  return rows.map((r) => ({ index: Number(r.index), summary: stripMd(String(r.summary ?? '')) }));
+}
+
+/** 读凭证（`DEEPSEEK_API_KEY` 环境变量 > `~/.dsh/.credentials.yaml` 的简单解析；不打印密钥）。 */
+export function resolveApiKey({ env = process.env, credentialsFile } = {}) {
+  if (env.DEEPSEEK_API_KEY && String(env.DEEPSEEK_API_KEY).trim()) return String(env.DEEPSEEK_API_KEY).trim();
+  if (!credentialsFile) return null;
+  try {
+    const txt = fs.readFileSync(credentialsFile, 'utf8');
+    const m = /DEEPSEEK_API_KEY\s*:\s*["']?([^"'\r\n]+)["']?/.exec(txt);
+    return m ? m[1].trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 调一次便宜模型（一篇文档一次调用）；返回 { ok, rows, tokens, model, error }。
+ * `deps.fetch` 可注入 ⇒ 单测零网络。
+ */
+export async function callLlmOnce({ doc, rows, llm, deps = {} }) {
+  const doFetch = deps.fetch ?? globalThis.fetch;
+  const key = llm.apiKey;
+  if (!key) return { ok: false, error: '缺少 DEEPSEEK_API_KEY（凭证文件或环境变量）', rows: [], tokens: 0 };
+  const prompt = buildLlmPrompt(doc, rows);
+  let res;
+  try {
+    res = await doFetch(`${llm.baseUrl.replace(/\/$/, '')}/chat/completions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
+      body: JSON.stringify({
+        model: llm.model,
+        messages: [{ role: 'user', content: prompt }],
+        temperature: 0.2,
+        stream: false,
+      }),
+      signal: deps.signal,
+    });
+  } catch (e) {
+    return { ok: false, error: `请求失败：${String((e && e.message) || e)}`, rows: [], tokens: 0 };
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch (e) {
+    return { ok: false, error: `响应非 JSON（HTTP ${res.status}）`, rows: [], tokens: 0 };
+  }
+  if (!res.ok) {
+    const msg = body?.error?.message || body?.message || `HTTP ${res.status}`;
+    return { ok: false, error: `模型报错：${msg}`, rows: [], tokens: 0 };
+  }
+  const raw = body?.choices?.[0]?.message?.content ?? '';
+  const usage = body?.usage ?? {};
+  const tokens = Number(usage.total_tokens ?? 0) || estimateTokens(prompt) + estimateTokens(raw);
+  try {
+    const parsed = parseLlmRows(raw);
+    return { ok: true, rows: parsed, tokens, model: body?.model ?? llm.model, usage };
+  } catch (e) {
+    return { ok: false, error: `解析失败：${String((e && e.message) || e)}`, rows: [], tokens, raw: String(raw).slice(0, 200) };
+  }
+}
+
+/** token 估算（模型未返回 usage 时的兜底记账；中文按 1 字 ≈ 1 token 保守估）。 */
+export function estimateTokens(text) {
+  return Math.ceil(String(text ?? '').length);
+}
+
+/**
+ * 为一批文档计划生成摘要（逐篇调用；受成本闸约束）。
+ * @returns {Promise<{byKey:Map<string,{summary:string,textHash:string}>, cost:object,
+ *   calls:number, tokens:number, stopped:string|null, failures:Array, skippedForFamily:string[]}>}
+ */
+export async function summarizeAll({ docs, plans, mode = 'rule', cost, llm = null, deps = {}, date = '' }) {
+  const byKey = new Map();
+  const failures = [];
+  const skippedForFamily = [];
+  let calls = 0;
+  let tokens = 0;
+  let stopped = null;
+  let working = rolloverCost(cost, date);
+
+  for (const doc of docs) {
+    const rows = plans.get(doc.rel) ?? [];
+    if (mode !== 'llm') {
+      for (const r of rows) {
+        const summary = buildRuleSummary(doc, r);
+        byKey.set(r.key, { summary, textHash: textHash(summary) });
+      }
+      continue;
+    }
+    // LLM 通路：先过家人哨兵（D2 从严读），再过成本闸
+    const family = assertNoFamilyContent(doc);
+    if (family.length) {
+      skippedForFamily.push(doc.rel);
+      failures.push({ path: doc.rel, error: `家人相关标记命中（${family.join('/')}）⇒ 按 D2 从严读不送第三方，改用规则摘要` });
+      for (const r of rows) {
+        const summary = buildRuleSummary(doc, r);
+        byKey.set(r.key, { summary, textHash: textHash(summary) });
+      }
+      continue;
+    }
+    const gate = checkCostGate(working, LLM_LIMITS);
+    if (!gate.allowed) {
+      stopped = gate.reason;
+      break; // 超限即停（不重试）
+    }
+    const res = await callLlmOnce({ doc, rows, llm, deps });
+    calls += 1;
+    tokens += Number(res.tokens) || 0;
+    working = { date, calls: working.calls + 1, tokens: working.tokens + (Number(res.tokens) || 0) };
+    if (!res.ok) {
+      failures.push({ path: doc.rel, error: res.error });
+      for (const r of rows) {
+        const summary = buildRuleSummary(doc, r); // 失败降级到规则摘要（不报错给主人）
+        byKey.set(r.key, { summary, textHash: textHash(summary) });
+      }
+      continue;
+    }
+    for (const r of rows) {
+      const hit = res.rows.find((x) => x.index === r.index);
+      const summary = clampSummary(hit?.summary || buildRuleSummary(doc, r));
+      byKey.set(r.key, { summary, textHash: textHash(summary) });
+    }
+  }
+  return { byKey, cost: working, calls, tokens, stopped, failures, skippedForFamily };
+}
+
+/** 摘要长度闸（≤500 字；超长按字截断）。 */
+export function clampSummary(s) {
+  const t = String(s ?? '').trim();
+  return t.length > SUMMARY_MAX_CHARS ? `${t.slice(0, SUMMARY_MAX_CHARS - 1)}…` : t;
+}