@kira905/dsh-memory-toolkit 0.1.2 → 0.2.0

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

@@ -1,108 +1,107 @@
-// 记忆引擎 v2 · 离线层 —— 文档扫描面 + 结构解析 + 粒度切分（方案 §3.2）
+// 离线层：文档扫描面 + markdown 结构解析 + 索引条切分（方案 §3.2）
 //
-// 口径（逐条照方案，勿自行发挥）：
-//   · 扫描面 = `<docsRoot>/**/*.md`（默认 `<cwd>/docs`）
-//   · **排除** = `变更流水/`、`管家报告/`、`坑库/`、`_archive`（流水类噪音大且频繁变更）
-//   · `path` 列 = **相对 `dshRoot` 的路径**
-//   · 粒度：短文档（<2 万字）1 条；长文档按 `##` 小节聚合 **2~5 条**；长文档多条以 `path#§N` 作主键
+// 口径（照方案，别自己发挥）：
+//   · 扫描面 = `<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 宿主迁移契约）。 */
+// docs 根（可注入；不写死机器名 —— 换宿主只改调用方）
 export const DEFAULT_DOCS_ROOT = path.join(process.cwd(), 'docs');
-/** `path` 列的前缀锚（默认 = 当前工作目录）。 */
+// `path` 列的前缀锚（缺省就是当前工作目录）
 export const DEFAULT_DSH_ROOT = process.cwd();
 
-/** 排除目录名（按路径"目录段"匹配，不按子串——否则 `_archive` 会误伤文件名）。 */
-export const EXCLUDE_DIRS = ['变更流水', '管家报告', '坑库', '_archive'];
+// 排除目录按「路径段」匹配，不按子串 —— 否则文件名里带这四个字会被误伤
+export const EXCLUDE_DIRS = '变更流水,管家报告,坑库,_archive'.split(',');
 
-/** 长/短文档分界（方案 §3.2：短文档 < 2 万字 1 条）。 */
+// 长/短文档分界：短文档不到 2 万字 ⇒ 1 条
 export const LONG_DOC_CHARS = 20000;
-/** 长文档分条数区间（方案 §3.2：2~5 条）。 */
+// 长文档分条区间 2~5
 export const MIN_LONG_ROWS = 2;
 export const MAX_LONG_ROWS = 5;
-/** 每条摘要上限（方案 §3.2：≤500 字）。 */
+// 每条摘要上限 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',
-];
+// 首期要索引的 10 篇常用文档：判据是文档总索引里「最常用的 15 份」那张人工表的头 10 条
+// （顺序即优先级，由主人与本鱼共同维护）。全量两百多篇不在这一批范围内。
+const FIRST_BATCH_TEXT = `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 = FIRST_BATCH_TEXT.split('\n').map((line) => line.trim()).filter(Boolean);
+
+// 首期清单的出处（写进 state 与报告，省得日后没人知道这 10 篇哪来的）
 export const FIRST_BATCH_SOURCE = 'docs/文档总索引.md §一「最常用的 15 份」（人工段）前 10 条';
 
-/** 统一 `/` 分隔（Windows 反斜杠一律归一；`path` 列口径）。 */
+/** 反斜杠一律归一成 `/`（`path` 列口径） */
 export function toPosix(p) {
   return String(p).replace(/\\/g, '/');
 }
 
-/** 相对 `dshRoot` 的 path 口径（扫描面在 docs 下 ⇒ 结果以 `docs/` 开头）。 */
+/** 相对 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));
+  const segs = toPosix(relPath).split('/');
+  segs.pop(); // 去掉文件名那一段
+  return segs.some((seg) => EXCLUDE_DIRS.includes(seg));
 }
 
 /**
- * 递归扫描扫描面（只读；不做 mtime 过滤——过滤交给差分逻辑）。
+ * 递归扫描扫描面（只读；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) => {
+  const collected = [];
+  const todo = [docsRoot];
+
+  while (todo.length > 0) {
+    const dir = todo.pop();
     let entries;
     try {
       entries = fs.readdirSync(dir, { withFileTypes: true });
     } catch {
-      return; // 目录不可读 → 跳过（fail-open，不打断别的扫描）
+      continue; // 目录读不动就跳过：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 });
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!EXCLUDE_DIRS.includes(entry.name)) todo.push(abs); // 整棵剪掉
+        continue;
+      }
+      if (!entry.isFile() || !/\.md$/i.test(entry.name)) continue;
+      let stat;
+      try {
+        stat = fs.statSync(abs);
+      } catch {
+        continue;
       }
+      const rel = toRelPath(abs, dshRoot);
+      if (isExcludedRel(rel)) continue;
+      collected.push({ rel, abs, mtime: Math.trunc(stat.mtimeMs), size: stat.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;
+  }
+
+  collected.sort((left, right) => (left.rel < right.rel ? -1 : left.rel > right.rel ? 1 : 0));
+  return opts.maxFiles ? collected.slice(0, opts.maxFiles) : collected;
 }
 
-/** 读文档并算字符数（用于粒度判定与摘要生成）。 */
+/** 读文档并算字符数（粒度判定与摘要生成都要它） */
 export function readDoc(absPath) {
   const text = fs.readFileSync(absPath, 'utf8');
   return { text, chars: text.length };
@@ -110,118 +109,138 @@ export function readDoc(absPath) {
 
 // ---------------------------------------------------------------- 结构解析
 
-/** 去掉 markdown 内联标记（摘要里不要出现 `**`/反引号/链接语法）。 */
+// 清洗流水线：顺序即语义（先去代码块，再去内联标记，最后压空白）
+const MD_CLEANUP = [
+  [/```[\s\S]*?```/g, ' '],
+  [/`([^`]*)`/g, '$1'],
+  [/!\[[^\]]*\]\([^)]*\)/g, ' '],
+  [/\[([^\]]*)\]\([^)]*\)/g, '$1'],
+  [/\*\*([^*]*)\*\*/g, '$1'],
+  [/(^|\s)[*_](\S[^*_]*)[*_]/g, '$1$2'],
+  [/^\s*>\s?/gm, ''],
+  [/\s+/g, ' '],
+];
+
+/** 去掉 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();
+  let text = String(s);
+  for (const [pattern, replacement] of MD_CLEANUP) text = text.replace(pattern, replacement);
+  return text.trim();
 }
 
-/** 取首句（中文句读 + 英文句点；上限 maxChars 字，超长按字截断）。
- *  ⚠️ 刻意**不含分号**：中文文档里分号常切出"主人 = 用户"这种半截短语，反而没信息量。 */
+// 首句候选：中文句读 / 英文句点后跟空白 / 实在没有就整段。
+// ⚠ 刻意不认分号：中文文档里分号常切出「主人 = 用户」这种半截短语，反而丢信息。
+const FIRST_SENTENCE_RE = /^(.{4,}?[。！？!?]|.{4,}?\.\s|.{4,})/;
+const TRAILING_STOP_RE = /[。！？!?]\s*$/;
+
+/** 取首句（上限 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 plain = stripMd(text);
+  if (!plain) return '';
+  const hit = FIRST_SENTENCE_RE.exec(plain);
+  let sentence = (hit ? hit[1] : plain).trim();
+  sentence = sentence.replace(TRAILING_STOP_RE, '').trim();
+  return sentence.length > maxChars ? `${sentence.slice(0, maxChars - 1)}…` : sentence;
 }
 
-/** 引言/章节的头几行里，这类"模板头 / 元信息"不算正文（否则每篇索引条都长一个样）。 */
-const META_LINE_RE = /^(?:\s*[>|])|^(?:维护人|创建|最近更新|最后更新|最后修订|更新时间|文件位置|路径口径|版本)\s*[:：]/;
+// 正文里这几类行不算正文：章节标题、分隔线、代码围栏、引用块/表格、以及模板头（维护人/更新日期…）
+const FENCE_LINE_RE = /^```/;
+const HEADING_LINE_RE = /^#{1,6}\s/;
+const RULE_LINE_RE = /^[-*_]{3,}$/;
+const QUOTE_LINE_RE = /^[>|]/;
+const BULLET_LINE_RE = /^[-*+]\s/;
+const META_PREFIX_RE = /^(?:维护人|创建|最近更新|最后更新|最后修订|更新时间|文件位置|路径口径|版本)\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; // 段落结束
+  const picked = [];
+  for (const rawLine of String(body ?? '').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) {
+      if (picked.length > 0) 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+/, ''));
+    if (FENCE_LINE_RE.test(line)) break;
+    if (HEADING_LINE_RE.test(line)) continue;
+    if (RULE_LINE_RE.test(line)) continue;
+    if (picked.length === 0 && META_PREFIX_RE.test(line)) continue; // 模板头/元信息：往后找真正文
+    if (QUOTE_LINE_RE.test(line)) continue;
+    if (BULLET_LINE_RE.test(line)) {
+      if (picked.length > 0) break;
+      picked.push(line.replace(/^[-*+]\s+/, ''));
     } else {
-      buf.push(l);
+      picked.push(line);
     }
-    if (buf.join(' ').length > maxChars) break;
+    if (picked.join(' ').length > maxChars) break;
   }
-  return buf.join(' ').trim();
+  return picked.join(' ').trim();
 }
 
-/** 章节标题瘦身（摘要里每节只留辨识度最高的前 28 字）。 */
+/** 章节标题瘦身（摘要里每节只留辨识度最高的前 maxChars 字） */
 export function shortTitle(t, maxChars = 28) {
-  const s = stripMd(t);
-  return s.length > maxChars ? `${s.slice(0, maxChars - 1)}…` : s;
+  const plain = stripMd(t);
+  return plain.length > maxChars ? `${plain.slice(0, maxChars - 1)}…` : plain;
 }
 
+const H1_RE = /^#\s+(.+?)\s*$/;
+const H2_RE = /^##\s+(.+?)\s*$/;
+
 /**
- * 解析 markdown 结构：`#` 标题、引言段、`##` 小节（含其下三级及正文）。
- * 只认 `##`（方案 §3.2「按 `##` 小节聚合」）；`###` 归入所属 `##`。
+ * 解析 markdown 结构：H1 标题、引言段、`##` 小节（其下的 `###` 归入所属小节）。
+ * 只认 `##`（方案：按 `##` 小节聚合）。
  * @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;
-    }
+  let title = '';
+  let introFrom = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    const hit = H1_RE.exec(lines[i]);
+    if (!hit) continue;
+    title = stripMd(hit[1]);
+    introFrom = i + 1;
+    break;
   }
   if (!title) {
-    // 无 H1：用第一行非空文本兜底（摘要头不至于空）
-    const firstLine = lines.find((l) => l.trim());
-    title = firstSentence(firstLine || '', 60);
-    introStart = 0;
+    // 没有 H1：拿第一行非空文本兜底，摘要头不至于开天窗
+    const headLine = lines.find((line) => line.trim());
+    title = firstSentence(headLine || '', 60);
+    introFrom = 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: [] };
+
+  const raw = [];
+  const introLines = [];
+  let openSection = null;
+  for (let i = introFrom; i < lines.length; i += 1) {
+    const line = lines[i];
+    const head = H2_RE.exec(line);
+    if (head) {
+      if (openSection) raw.push(openSection);
+      openSection = { title: stripMd(head[1]), body: [] };
       continue;
     }
-    if (cur) cur.body.push(line);
+    if (openSection) openSection.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 };
+  if (openSection) raw.push(openSection);
+
+  return {
+    title,
+    intro: introLines.join('\n').trim(),
+    sections: raw.map((section) => {
+      const bodyText = section.body.join('\n').trim();
+      return { title: section.title, chars: section.title.length + bodyText.length, body: bodyText };
+    }),
+  };
 }
 
-/** 目标分条数：2 万字内 1 条；超出按字符规模升到 2~5 条，且不超过 `##` 小节数。 */
+/** 目标分条数：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;
@@ -230,21 +249,24 @@ export function planRowCount(chars, sectionCount) {
   return Math.min(target, sectionCount);
 }
 
-/** 按 section **个数**均分（确定性、可复现；组数恰为 k）。 */
+/** 按 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 total = sections.length;
+  if (k <= 1 || total <= 1) return [sections];
+
+  const base = Math.floor(total / k);
+  const extra = total % k;
   const groups = [];
-  let idx = 0;
-  for (let g = 0; g < k; g += 1) {
-    const take = base + (g < rem ? 1 : 0);
+  let cursor = 0;
+  let group = 0;
+  while (group < k) {
+    const take = base + (group < extra ? 1 : 0);
+    group += 1;
     if (take === 0) continue;
-    groups.push(sections.slice(idx, idx + take));
-    idx += take;
+    groups.push(sections.slice(cursor, cursor + take));
+    cursor += take;
   }
-  if (idx < n) groups[groups.length - 1] = groups[groups.length - 1].concat(sections.slice(idx));
+  if (cursor < total) groups[groups.length - 1] = groups[groups.length - 1].concat(sections.slice(cursor));
   return groups;
 }
 
@@ -255,17 +277,17 @@ export function splitSections(sections, k) {
  */
 export function planRows(doc) {
   const { rel, chars, structure } = doc;
-  const k = planRowCount(chars, structure.sections.length);
-  if (k <= 1) {
+  const wanted = planRowCount(chars, structure.sections.length);
+  if (wanted <= 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) => ({
+  const groups = splitSections(structure.sections, wanted);
+  return groups.map((group, i) => ({
     key: `${rel}#§${i + 1}`,
     index: i,
     total: groups.length,
-    sections,
-    // 文档引言只在第 1 段带（避免 2~5 条里重复同一段话）
+    sections: group,
+    // 文档引言只挂在第 1 段（免得 2~5 条里重复同一段话）
     intro: i === 0 ? structure.intro : '',
   }));
 }