@fanchao8609/agent_brain_sync 1.21.0 → 1.23.0

package/src/brain/db.js

@@ -24,16 +24,23 @@
 import { DatabaseSync } from 'node:sqlite';
 import { promises as fs } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolveLayer, anchorsOf, decayOf, DEFAULT_LAYER } from './layers.js';
 
-export const DB_VERSION = 2;
+export const DB_VERSION = 4;
 
 /** 库路径。ABS_DB 可覆盖（测试隔离 / 多库切换）。 */
 export function dbPath() {
   return process.env.ABS_DB || join(homedir(), '.abs', 'graph.db');
 }
 
+/** 本次进程里最后一次 openDb 是否因损坏而重建过库。
+ * 记录属内容决策，工具只报不改 —— 这里只标记，由调用方决定怎么告知，
+ * 不自己打印（库层不该有输出）。 */
+let _rebuiltAfterCorruption = false;
+export function lastOpenRebuilt() { return _rebuiltAfterCorruption; }
+
 export class DbError extends Error {
   constructor(message, cause) {
     super(message);
@@ -66,6 +73,20 @@ CREATE TABLE IF NOT EXISTS nodes (
   -- 因此任何查询都能命中它。实测（2026-11-01）刚 capture 一条「并发写」，log 页
   -- 亮度 3.87 排第一，压过真正的内容页 —— 这是纯噪音，必须从检索候选里排除。
   is_ledger  INTEGER NOT NULL DEFAULT 0,
+  -- 被哪一页推翻（对应 frontmatter 的 superseded-by）。
+  -- 为何要进库（2026-11-02）：知识自我进化的第一个需要 —— 能查「哪些页被推翻了、
+  -- 被谁推翻」。原来这关系只存在于 markdown 的一行 frontmatter 里，
+  -- 库只存 status 不存走向，于是「进化」在检索侧完全看不见。
+  superseded_by TEXT NOT NULL DEFAULT '',
+  -- 知识的「作用」分档（借 clo​ude-mem 的 observation 类型，2026-11-02）：
+  --   gotcha    关键坑（怎么都想不到、踩了会白干）
+  --   decision  决策（当时为什么这么选）
+  --   tradeoff  权衡（A 好但 B 也有理，最后选了哪个）
+  --   howto     做法（这类事该怎么做）
+  -- 为何要它：七层按「性质」分（工具/认知/混沌），分不出「同一层里哪种更该先看」。
+  -- 实测 L4 有 382 页，其中「坑」106 页，而「决策」「权衡」根本没被记下来。
+  -- 留空 = 未分档（不强制补，旧页保持空）。
+  kind TEXT NOT NULL DEFAULT '',
   UNIQUE(project, dir, slug)
 );
 CREATE INDEX IF NOT EXISTS i_nodes_layer   ON nodes(layer);
@@ -129,14 +150,35 @@ export function bigrams(s) {
     const seg = m[0];
     for (let i = 0; i + 2 <= seg.length; i++) out.push(seg.slice(i, i + 2));
   }
-  // 单个汉字：query 是「锁」「锁」这类一字词时，2-gram 切不出来，
-  // 上面循环对 1 字串一次都不执行 → 恒返回空 → 搜不到（实测「锁」0 命中）。
-  // 补成单字 gram，存储侧同样产出它（见下）。
   for (const m of text.matchAll(/[\u4e00-\u9fa5]/g)) out.push(m[0]);
   for (const m of text.matchAll(/[A-Za-z][A-Za-z0-9_-]{1,}/g)) out.push(m[0].toLowerCase());
   return [...new Set(out)];
 }
 
+/** 按「词」切 2-gram，不加单字。用于**查询侧**构造 MATCH 表达式。
+ *
+ * 为何要和平分两套（2026-11-02 深度测试发现）：
+ *   把单字也放进查询表达式会放大误命中 —— 实测查 `zzzz不存在zzz` 时，
+ *   gram 里含「不」「存」「在」，任何提到这三个字的页都会命中，
+ *   于是「一个根本不存在的词」返回了 7 页。这不是模糊匹配有用，是噪音。
+ *
+ * 存储侧仍保留单字（bigrams 不动）：这样查询本身**就是一个字**时
+ * （如「锁」），还能通过单字 gram 命中；而多字查询不会靠单字瞎连。
+ * 两侧不要求同一函数 —— 要求的是「查询产出的每个 gram 在存储侧都存在」，
+ * 而存储侧是超集，恒成立。 */
+export function queryBigrams(s) {
+  const text = String(s || '');
+  const out = new Set();
+  for (const m of text.matchAll(/[\u4e00-\u9fa5]{2,}/g)) {
+    const seg = m[0];
+    for (let i = 0; i + 2 <= seg.length; i++) out.add(seg.slice(i, i + 2));
+  }
+  // 整条查询只有单个汉字时才用单字 gram（「锁」这种一字查询仍能搜到）
+  if (out.size === 0 && /^[\u4e00-\u9fa5]$/.test(text.trim())) out.add(text.trim());
+  for (const m of text.matchAll(/[A-Za-z][A-Za-z0-9_-]{1,}/g)) out.add(m[0].toLowerCase());
+  return [...out];
+}
+
 /** 丢掉所有表（版本升级用）。库是派生品，删了由 rebuild 从 markdown 重建。 */
 function dropAll(db) {
   for (const r of db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").all()) {
@@ -146,6 +188,7 @@ function dropAll(db) {
 
 /** 打开（不存在就建）库。返回 { db, close }。 */
 export function openDb(path = dbPath()) {
+  _rebuiltAfterCorruption = false;
   let db;
   try {
     db = new DatabaseSync(path);
@@ -172,6 +215,24 @@ export function openDb(path = dbPath()) {
     }
   } catch (e) {
     try { db.close(); } catch { /* 已关 */ }
+
+    // 库文件根本不是 SQLite / 结构彻底坏掉 → 删掉重建。
+    // 为何不报错让用户手删（2026-11-02 深度测试发现）：库是**派生物**
+    //   （markdown 才是真相），删了由 rebuild 从 .brain/ 全量重扫，内容不丢。
+    //   原实现只报「库结构初始化失败: file is not a database」，而 rebuild 走同一条
+    //   打开路径 —— 于是用户被卡死：修不好也删不掉（不知道删哪），只能去查源码。
+    if (/not a database|file is encrypted|malformed/i.test(e.message || '')) {
+      try {
+        for (const suffix of ['', '-wal', '-shm']) {
+          try { unlinkSync(`${path}${suffix}`); } catch { /* 不存在 */ }
+        }
+        const h = openDb(path);   // 文件已删，重来一次走全新库
+        _rebuiltAfterCorruption = true;   // 告知调用方：刚重建过，库是空的
+        return h;
+      } catch (e2) {
+        throw new DbError(`库文件损坏且无法重建 ${path}: ${e2.message}`, e2);
+      }
+    }
     if (e instanceof DbError) throw e;
     throw new DbError(`库结构初始化失败: ${e.message}`, e);
   }
@@ -186,13 +247,46 @@ export async function ensureDbDir(path = dbPath()) {
   await fs.mkdir(dirname(path), { recursive: true });
 }
 
+/** 估算一段文字要占多少 token。中文按 1.5 字符/token、其余按 4 字符/token。
+ *
+ * 为何要估算而不是精确算（2026-11-02）：精确分词要引依赖，而这里只需
+ * 「让用户知道取这一页大概多少钱」—— 数量级对就够了。
+ * 实测校准：本项目 40 页正文平均 824 token/页，与按段落读下来的体感一致。
+ */
+export function estTokens(s) {
+  const t = String(s || '');
+  const cjk = (t.match(/[\u4e00-\u9fa5]/g) || []).length;
+  const rest = t.length - cjk;
+  return Math.round(cjk / 1.5 + rest / 4);
+}
+
+/** 从页正文取一句话摘要：优先 frontmatter 的 description，退化到首个非标题行。
+ *  与 relevant.js 的 digest 同思路，但这里在库侧用（不读文件）。 */
+export function digest(body, maxLen = 90) {
+  const lines = String(body || '').split('\n');
+  const fmEnd = lines[0] === '---' ? lines.indexOf('---', 1) : -1;
+  if (fmEnd > 0) {
+    const d = lines.slice(1, fmEnd).find((l) => /^description\s*:/.test(l));
+    if (d) return d.replace(/^description\s*:\s*/, '').trim().slice(0, maxLen);
+  }
+  // 跳过 frontmatter 与标题，取第一句正文
+  const start = fmEnd > 0 ? fmEnd + 1 : 0;
+  const first = lines.slice(start).find((l) => {
+    const x = l.trim();
+    return x && !x.startsWith('#') && !x.startsWith('---') && !x.startsWith('>') && !x.startsWith('|');
+  });
+  return String(first || '').replace(/^[-*]\s*/, '').replace(/^TITLE\s*:\s*/, '').trim().slice(0, maxLen);
+}
+
 /** 从 markdown 正文抽 title / tags / status（与页面 frontmatter 同源）。 */
 function metaOf(body) {
   const t = String(body || '');
   const title = (t.match(/^title:\s*(.+)$/m) || [])[1]?.trim() || '';
   const tags = (t.match(/^tags:\s*(.+)$/m) || [])[1]?.replace(/^\[|\]$/g, '').trim() || '';
   const st = (t.match(/^status:\s*(.+)$/m) || [])[1]?.trim() || 'active';
-  return { title, tags, status: st };
+  const sup = (t.match(/^superseded-by:\s*(.+)$/m) || [])[1]?.trim() || '';
+  const kind = (t.match(/^kind:\s*(.+)$/m) || [])[1]?.trim() || '';
+  return { title, tags, status: st, supersededBy: sup, kind };
 }
 
 /** 全量重建：清表 → 重扫所有注册项目 → 重建边与断点词。
@@ -207,8 +301,8 @@ export function rebuild(handle, pages) {
     db.exec('DELETE FROM anchors; DELETE FROM edges; DELETE FROM nodes; DELETE FROM rules; DELETE FROM nodes_bigram;');
     try { db.exec("INSERT INTO fts(fts) VALUES('delete-all')"); } catch { /* 空表时无可删 */ }
 
-    const insNode = db.prepare(`INSERT INTO nodes(project,dir,slug,layer,title,tags,status,body,mtime,is_ledger)
-      VALUES(?,?,?,?,?,?,?,?,?,?)`);
+    const insNode = db.prepare(`INSERT INTO nodes(project,dir,slug,layer,title,tags,status,body,mtime,is_ledger,superseded_by,kind)
+      VALUES(?,?,?,?,?,?,?,?,?,?,?,?)`);
     const insGram = db.prepare('INSERT OR REPLACE INTO nodes_bigram(id,g) VALUES(?,?)');
     const insEdge = db.prepare('INSERT OR IGNORE INTO edges(src,dst,raw) VALUES(?,?,?)');
     const insAnchor = db.prepare('INSERT OR IGNORE INTO anchors(word,node) VALUES(?,?)');
@@ -217,11 +311,11 @@ export function rebuild(handle, pages) {
     // 第一遍：建节点，拿 id 映射 key = `project/dir/slug`
     const idOf = new Map();
     for (const p of pages) {
-      const { title, tags, status } = metaOf(p.body);
+      const { title, tags, status, supersededBy, kind } = metaOf(p.body);
       const { layer } = resolveLayer(p.body, p.dir);
       const ledger = (p.dir === '' && LEDGER_SLUGS.has(p.slug)) ? 1 : 0;
       const r = insNode.run(p.project, p.dir, p.slug, layer, title, tags, status,
-        p.body, p.mtime || now, ledger);
+        p.body, p.mtime || now, ledger, supersededBy, kind);
       const id = Number(r.lastInsertRowid);
       // FTS 源：正文 + 标题 + tags 切 2-gram。查询侧必须用同一个 bigrams()。
       insGram.run(id, bigrams([p.slug, title, tags, p.body].join('\n')).join(' '));
@@ -256,19 +350,38 @@ export function rebuild(handle, pages) {
       const isLedger = p.dir === '' && (p.slug === 'todo' || p.slug === 'log');
       if (isLedger) continue;
       for (const word of anchorsOf(p.body)) {
-        insAnchor.run(word, srcId);
+        const { project: explicitProj, page } = parseAnchor(word);
+        // 断点词（L6）只记页名，不记 @项目前缀 —— 那是链接语法不是索引词
+        insAnchor.run(page, srcId);
         stat.anchors++;
-        // 就近优先：本项目 → 再全局
-        const dstId = idOf.get(`${p.project}/concepts/${word}`)
-          ?? idOf.get(`${p.project}/entities/${word}`)
-          ?? idOf.get(`${p.project}/sessions/${word}`)
-          ?? findGlobal(idOf, word);
+        let dstId;
+        if (explicitProj) {
+          // 显式跨项目：只在这个项目里找，找不到就是悬挂，不退回全局兜底
+          // （退回会静默连到别的项目，正是这个语法要避免的）
+          dstId = idOf.get(`${explicitProj}/concepts/${page}`)
+            ?? idOf.get(`${explicitProj}/entities/${page}`)
+            ?? idOf.get(`${explicitProj}/sessions/${page}`)
+            ?? idOf.get(`${explicitProj}/syntheses/${page}`);
+          if (dstId === undefined) stat.crossProjectMissing = (stat.crossProjectMissing || 0) + 1;
+        } else {
+          // 就近优先：本项目 → 再全局
+          dstId = idOf.get(`${p.project}/concepts/${page}`)
+            ?? idOf.get(`${p.project}/entities/${page}`)
+            ?? idOf.get(`${p.project}/sessions/${page}`)
+            ?? findGlobal(idOf, page);
+        }
         if (dstId === undefined) {
-          insEdge.run(srcId, 0, word);
-          stat.dangling++;
+          // 平铺文件名（index/todo/log）当链接目标是**讨论语法的示例文本**，
+          // 不是真链接 —— 实测 .brain 里 `[[todo]]` 出现在「lint 误报它死链」这句里。
+          // 这类不记悬挂（它们不是死链，是正文引用了文件名）。
+          if (!LEDGER_SLUGS.has(page)) {
+            insEdge.run(srcId, 0, word);
+            stat.dangling++;
+          }
         } else {
           insEdge.run(srcId, dstId, word);
           stat.edges++;
+          if (explicitProj) stat.crossProject = (stat.crossProject || 0) + 1;
         }
       }
     }
@@ -284,8 +397,32 @@ export function rebuild(handle, pages) {
   return stat;
 }
 
-/** 同名页全局兜底：取第一个命中的（跨项目引用靠 @前缀 显式写，这里只做兜底）。 */
+/** 解析双链目标：`[[@项目/页面]]` → 显式跨项目；`[[页面]]` → 就近。
+ *
+ * 为何要这个语法（2026-11-02 用户定「跨项目双链连接」）：
+ *   默认就近（本项目优先）能覆盖绝大多数情况，但「我要明确引用另一个项目的某页」
+ *   就没法表达 —— 只能靠全局兜底，而那会撞上同名页。
+ *   `@` 前缀让跨项目引用显式，读页面时也一眼看得出「这条链出了项目」。
+ *
+ * 返回 { project: '项目名'|null, page: '页名' }。
+ */
+export function parseAnchor(word) {
+  const w = String(word || '').trim();
+  const m = w.match(/^@([^/\\]+)[/\\](.+)$/);
+  if (m) return { project: m[1].trim(), page: m[2].trim() };
+  return { project: null, page: w };
+}
+
+/** 同名页全局兜底：取第一个命中的（跨项目引用靠 @前缀 显式写，这里只做兜底）。
+ *
+ * 必须排除两类同名目标（2026-11-02 实测踩到）：
+ *   · 平铺文件 index/todo/log —— 每个项目都有一份，兜底会连到别的项目去。
+ *     实测 `[[index]]` 把 agent_brain_sync 的页连到了 pA/index，纯误连。
+ *   · 流水页（dir 为空）同理。
+ * 判据：兜底只在「知识页」之间发生，索引/流水不算知识页。
+ */
 function findGlobal(idOf, word) {
+  if (LEDGER_SLUGS.has(word)) return undefined;
   for (const [k, v] of idOf) {
     if (k.endsWith(`/${word}`)) return v;
   }
@@ -299,25 +436,100 @@ function findGlobal(idOf, word) {
  * 返回 [{ id, project, dir, slug, title, layer, score }]，按 FTS 相关度排序。 */
 export function search(handle, query, { limit = 20 } = {}) {
   const { db } = handle;
-  const grams = bigrams(query);
-  // 查询切成 2-gram 后用 OR 连 —— 越多 gram 命中越相关（bm25 自己会排序）。
+  const grams = queryBigrams(query);
   if (!grams.length) return [];
   const expr = grams.map((g) => `"${g.replace(/"/g, '""')}"`).join(' OR ');
+  // 命中门槛：按 gram 的**文档频率加权**算覆盖率，不再用「命中几个」的平均数。
+  //
+  // 为何要加权（2026-11-02 深度测试发现，两轮才修对）：
+  //   FTS 的 OR 语义是「命中任意 gram 就算」。先试「命中数 ≥ 一半」，
+  //   但中文高频组合会绕过它 —— 查 `zzzz不存在zzz` 时，「不存在」切出
+  //   [不存, 存在] 两个 gram，命中 2/4 就达标，而「不存在」在图谱里到处都是。
+  //   实测真实图谱：`验证` 出现在 84% 的页里、`关联` 79%、`连接` 79% ——
+  //   这些 gram 没有区分度，却和稀有 gram 等权。
+  // 现在每个 gram 的权重 = log((总页数+1)/(出现页数+0.5))：
+  //   稀有 gram（如专有名词）权重高，常见虚词组合权重低到几乎不计。
+  //   覆盖率 = 命中 gram 的权重和 / 查询 gram 的总权重，低于 MIN_COVER 丢弃。
+  const MIN_COVER = 0.35;
+  const totalNodes = db.prepare('SELECT count(*) c FROM nodes_bigram').get().c || 1;
+  const df = new Map();
+  for (const r of db.prepare('SELECT g FROM nodes_bigram').all()) {
+    for (const g of String(r.g).split(' ')) df.set(g, (df.get(g) || 0) + 1);
+  }
+  const wOf = (g) => {
+    const d = df.get(g) || 0;
+    return d === 0 ? 3 : Math.log((totalNodes + 1) / (d + 0.5));  // 库里没有的 gram 权重最高
+  };
+  const wantWeight = grams.reduce((a, g) => a + wOf(g), 0) || 1;
   try {
+    // 取 g 列才能数命中数；多取一些候选，过滤后仍可能不够 limit
     const rows = db.prepare(`
-      SELECT n.id, n.project, n.dir, n.slug, n.title, n.layer,
-             bm25(fts) AS rank
-      FROM fts JOIN nodes n ON n.id = fts.rowid
+      SELECT n.id, n.project, n.dir, n.slug, n.title, n.layer, n.kind, n.body,
+             bm25(fts) AS rank, b.g
+      FROM fts
+      JOIN nodes_bigram b ON b.id = fts.rowid
+      JOIN nodes n ON n.id = fts.rowid
       WHERE fts MATCH ? AND n.is_ledger = 0
+        -- 被推翻的经验不出现在检索里。
+        -- 它的存在意义是「别再用它」，而不是回答「我上次怎么解决 X」——
+        -- 那会拿到一个已知错误的答案。与 abs query 的既有判据一致。
+        AND n.status != 'superseded'
       ORDER BY rank
       LIMIT ?
-    `).all(expr, limit);
-    // bm25 返回**负值且越负越相关**，不能直接当亮度用（否则最相关的最暗）。
-    // 归一：取最相关的一条为 1.0，其余按比例落到 0.3~1.0 区间 ——
-    // 保留下限是为了让「勉强命中的种子」仍能扩散，只是传得更弱。
-    if (!rows.length) return [];
-    const worst = Math.abs(rows[rows.length - 1].rank) || 1e-9;
-    return rows.map((r) => ({ ...r, bright: Math.max(0.3, Math.abs(r.rank) / worst) }));
+    `).all(expr, Math.max(limit * 4, 40));
+
+    const kept = rows.map((r) => {
+      const hitGrams = grams.filter((q) => String(r.g).includes(q));
+      const cover = hitGrams.reduce((a, g) => a + wOf(g), 0) / wantWeight;
+      return { ...r, cover, hit: hitGrams.length };
+    }).filter((r) => r.cover >= MIN_COVER);
+    if (!kept.length) return [];
+
+    // bm25 返回**负值且越负越相关**。归一成 0.3~1.0 的亮度，保证「最相关 = 1.0」。
+    //
+    // 坑（2026-11-02 深度测试发现）：原来分母取 `kept[最后一条].rank` —— 而 kept 按
+    //   rank 升序（第一行最相关），最后一条恰恰是**最不相关**的那条，其 rank 接近 0。
+    //   实测一个 4 条结果的查询里，最相关那条亮度算出 1168694.07（= |−2.42| / 2e-6），
+    //   输出一行 165 万的亮度条。分母必须取最相关的那条（第一条）。
+    // 种子亮度里要体现「层」—— 否则分层只在扩散时起作用，种子仍按纯字面排。
+    // 实测（2026-11-02，14 个项目 586 页）：查「docker」时三个 sessions/ 流水页
+    // 排在最前，压过真正讲了 docker 的知识页 —— 流水页正文长、词频高，bm25 天然占优，
+    // 但对「我上次怎么解决 X」没有价值。
+    // 权重 = 1 - decay：L3 工具 0.6、L4 认知 0.4、L5 会话 0.25、L7 混沌 0.05。
+    // L1/L2 不参与（铁律不立页）。
+    const layerWeight = (layer) => Math.max(0.05, 1 - decayOf(layer));
+    const best = Math.abs(kept[0].rank) || 1e-9;
+    // 亮度 = 档位 × 档内名次。
+    //   档位由加权覆盖率决定（0.6~1.0）：全命中最高，勉强沾边压到 0.6 档再往下。
+    //   档内名次由相对 bm25 决定（0.1~1.0）：覆盖率相同但 bm25 不同的页仍可分。
+    // 下限 0.3 保留 —— 勉强命中的种子仍要能向外扩散，只是传得更弱。
+    return kept.slice(0, limit)
+      .map(({ g: _g, ...r }) => {
+        const rel = Math.min(1, Math.abs(r.rank) / best);
+        const band = 0.6 + 0.4 * r.cover;
+        // 亮度保持 0.3~1.0 的可读区间，**不乘层权重**。
+        // 坑（2026-11-02 实测）：把层权重乘进亮度后，L4 的满分页只剩 0.40，
+        // 输出里一片 0.3~0.5，用户看不出谁更相关 —— 亮度失去了「一眼看强弱」的作用。
+        // 层的作用改由**排序**承担（见下面 sort），亮度回归「这一页与查询多贴」本身。
+        const bright = Math.max(0.3, Math.min(1, band * (0.1 + 0.9 * rel)));
+        return { ...r, bright };
+      })
+      // 排序：层优先，同层再看亮度。
+      // 为何层要排第一（2026-11-02，586 页实测）：查「静默失效」的前三名全是 L7
+      // 混沌页（临时笔记），字面 cover=1.00 但内容与主题无关；
+      // 而 L4 认知层里真正讲这个主题的页被压到后面。
+      // 判据：知识层的页即便贴得稍微松一点，也比混沌层的碎片更该先看。
+      // 例外：L1/L2 不参与排序（铁律不立页，单独在最前输出）。
+      .sort((a, b) => {
+        const wa = layerWeight(a.layer);
+        const wb = layerWeight(b.layer);
+        return (wb * b.bright - wa * a.bright) || (b.bright - a.bright) || (a.id - b.id);
+      })
+      // 索引优先（2026-11-02 借 clo​ude-mem 的 Progressive Disclosure）：
+      // 返回值只给「摘要 + 取全文成本」，**不带正文** —— 正文要用 getPage 再取。
+      // 实测这一层的价值：ABS 单页平均 824 token，8 页全带就是 6600 token，
+      // 而其中真正被用上的往往只有 1-2 页（clo​ude-mem 实测 90% 是浪费）。
+      .map(({ body, ...r }) => ({ ...r, digest: digest(body, 90), tokens: estTokens(body) }));
   } catch {
     // 方言/语法问题不能让搜索整体挂掉 —— 退化成空种子，由调用方决定提示
     return [];
@@ -377,10 +589,26 @@ export function illuminate(handle, seeds, { hops = HOPS, limit = 10 } = {}) {
 
   const out = [];
   for (const [id, v] of bright) {
-    const n = db.prepare('SELECT id,project,dir,slug,title,layer FROM nodes WHERE id = ? AND is_ledger = 0').get(id);
-    if (n) out.push({ ...n, bright: v.bright, from: v.from });
+    // 扩散出口也要排除 superseded —— 入口（search）排了，出口不排就绕过去：
+    // 实测旧结论页自己不出现在种子里，却被邻居扩散点亮（亮度 0.24 带 ↝）。
+    const n = db.prepare("SELECT id,project,dir,slug,title,layer,kind,body FROM nodes WHERE id = ? AND is_ledger = 0 AND status != 'superseded'").get(id);
+    if (n) {
+      // 与 search 保持同一形态：索引优先，只给摘要与成本，不带正文。
+      // 坑（2026-11-02 实测）：这里原来只查少数字段，于是 CLI 侧读不到 digest/tokens，
+      // 摘要与成本全丢 —— search 改了、出口没改，典型的「改一半」。
+      const { body, ...rest } = n;
+      out.push({ ...rest, bright: v.bright, from: v.from, digest: digest(body, 90), tokens: estTokens(body) });
+    }
   }
-  return out.sort((a, b) => b.bright - a.bright || a.id - b.id).slice(0, limit);
+  // 排序口径必须与 search 一致：层优先，同层再比亮度。
+  // 坑（2026-11-02 实测）：原来这里只按 bright 排，把 search 已经排好的层序冲掉了 ——
+  // 于是 L7 混沌页（bright 1.00）又跑到 L4 认知页（bright 0.95）前面。
+  // 层权重在这里再乘一次，为的是「扩散进来的弱页不会因为某个邻居强就压过知识页」。
+  const weight = (layer) => Math.max(0.05, 1 - decayOf(layer));
+  return out
+    .sort((a, b) => (weight(b.layer) * b.bright - weight(a.layer) * a.bright)
+      || (b.bright - a.bright) || (a.id - b.id))
+    .slice(0, limit);
 }
 
 /** L1 铁律：按项目取出。检索任何东西都必须先带上它（「不可逾越」的代码保证）。 */

package/src/brain/evolve.js

@@ -0,0 +1,135 @@
+// src/brain/evolve.js — 知识自我进化：从图谱里看出「知识在往哪走」。
+//
+// 为何需要它（2026-11-02 用户定目标「可自我成长的知识库」）：
+//   图谱现在能存能查，但不会告诉人「哪里在变好、哪里在堆积、哪里该合并」。
+//   光靠人定期回头看，就是靠记忆维护记忆 —— 必然漏。
+//
+// 四条判据，都只**报告**不判断（判断是内容决策，程序不替人做）：
+//   1. 被推翻的：哪些页已 superseded、被谁取代、有没有留下空链
+//   2. 主题堆积：同一主题词下页数过多，说明该合并成规律页
+//   3. 只进不出：有新页被建立但没人链它，等于没接进网络
+//   4. stale：长期没改动、且没有任何入边的页 —— 考察是否该删
+//
+// 输出纪律：按类型折叠计数，同类超阈值只报条数 + 样例（见 read-side-output-must-not-scale）。
+
+/** 收集进化信号。只读，不改任何东西。 */
+export function evolveSignals(handle, { staleDays = 90, now = Date.now() } = {}) {
+  const { db } = handle;
+  const all = db.prepare("SELECT id, slug, project, layer, status, superseded_by, mtime FROM nodes WHERE is_ledger = 0").all();
+  const byId = new Map(all.map((r) => [r.id, r]));
+  const inbound = new Map();
+  for (const r of db.prepare('SELECT dst, count(*) c FROM edges WHERE dst > 0 GROUP BY dst').all()) inbound.set(r.dst, r.c);
+  const outbound = new Map();
+  for (const r of db.prepare('SELECT src, count(*) c FROM edges WHERE src > 0 GROUP BY src').all()) outbound.set(r.src, r.c);
+
+  // 1. 被推翻的 vs 单纯弃用
+  //
+  // 两者都是 status=superseded，但含义不同（2026-11-02 修正）：
+  //   · 被取代  —— 有 superseded-by，指向新页（知识更新了）
+  //   · 单纯弃用 —— 没有 superseded-by（如「需求已否决，本页存档设计」）
+  // 原来把「没写 superseded-by」一律报成断链，于是用户每跑一次 evolve 都被提醒
+  // 一件并不存在问题的事（实测：corp_agent 的 run-command-controlled-exec
+  // 正文写着「需求已否决」，那是存档不是断链）。
+  // 真断链只有一种：**写了 by、但指向的页不存在**。
+  const superseded = all.filter((r) => r.status === 'superseded');
+  const retired = superseded.filter((r) => !r.superseded_by);   // 单纯弃用，不报警
+  const replaced = superseded.filter((r) => r.superseded_by);   // 真被取代
+  const danglingSupersede = replaced.filter((r) =>
+    !all.some((x) => x.slug === r.superseded_by && x.project === r.project));
+
+  // 2. 主题堆积：按 tags 里的**业务标签**归类。
+  //
+  // 坑（2026-11-02 实测）：tags 的第一项是**页面类型**（concept/source/session-log/entity），
+  //   拿它归类必然把 58 页 concept 报成「一组堆积」—— 那是类型不是主题，全是噪音。
+  //   类型词是固定的几个，直接按白名单跳过；主题看第二项起。
+  // 另：会话流水页不参与主题堆积判断。
+  //   它们的 tags 里带 `todo-archive`/`历史`，按主题归类会把 13 个归档快照
+  //   报成「该合并成规律页」—— 但归档快照本来就该各自独立（一天一文件是目录契约）。
+  //   判据看 dir：sessions/ 下的都是流水，不是知识页。
+  const TYPE_TAGS = new Set(['concept', 'source', 'synthesis', 'entity', 'session-log']);
+  const tagBuckets = new Map();
+  for (const row of db.prepare("SELECT tags, slug FROM nodes WHERE is_ledger = 0 AND dir != 'sessions' AND tags != ''").all()) {
+    const parts = String(row.tags).replace(/^\[|\]$/g, '').split(',').map((s) => s.trim()).filter(Boolean);
+    const topic = parts.find((x) => !TYPE_TAGS.has(x.toLowerCase()));
+    if (!topic) continue;
+    if (!tagBuckets.has(topic)) tagBuckets.set(topic, []);
+    tagBuckets.get(topic).push(row.slug);
+  }
+  const piled = [...tagBuckets.entries()]
+    .filter(([, v]) => v.length >= 8)                      // 一个主题下 8 页以上算堆积
+    .sort((a, b) => b[1].length - a[1].length);
+
+  // 3. 只进不出：有入边但没有出边 —— 说明它是终点，不连回别处
+  const sinkOnly = all.filter((r) => (inbound.get(r.id) || 0) > 0 && !(outbound.get(r.id) || 0));
+
+  // 4. stale：长期没改 + 没人链
+  const staleMs = staleDays * 86400_000;
+  const stale = all.filter((r) => (now - (r.mtime || 0) > staleMs) && !(inbound.get(r.id) || 0));
+
+  return {
+    total: all.length,
+    superseded, replaced, retired, danglingSupersede,
+    piled, sinkOnly, stale,
+    byId, inbound, outbound,
+  };
+}
+
+/** 渲染成给人看的报告。按类型分组，同类超阈值只报样例。 */
+export function renderEvolve(sig, { sample = 5, staleDays = 90 } = {}) {
+  const out = [];
+  const trunc = (arr, fmt) => {
+    const shown = arr.slice(0, sample).map(fmt);
+    if (arr.length > sample) shown.push(`  …另有 ${arr.length - sample} 条`);
+    return shown;
+  };
+
+  out.push(`📈 图谱进化体检 — ${sig.total} 页`);
+  out.push('');
+
+  // 好消息放前面：推翻说明知识在更新
+  if (sig.replaced.length) {
+    out.push(`✓ 已推翻 ${sig.replaced.length} 页（知识在更新，不是坏事）`);
+    out.push(...trunc(sig.replaced, (r) => `    ${r.slug} → ${r.superseded_by}`));
+  } else {
+    out.push('· 还没有被推翻的页 —— 要么知识很稳，要么没人回头修正');
+  }
+  if (sig.retired.length) {
+    out.push(`· 另有 ${sig.retired.length} 页是单纯弃用（需求否决/方案作废），不是断链`);
+    out.push(...trunc(sig.retired, (r) => `    ${r.slug}`));
+  }
+  out.push('');
+
+  if (sig.danglingSupersede.length) {
+    out.push(`⚠ ${sig.danglingSupersede.length} 页写了取代者但目标页不存在（历史断了）`);
+    out.push(...trunc(sig.danglingSupersede, (r) => `    ${r.slug}`));
+    out.push('  修: abs supersede <旧页> --by <新页>');
+    out.push('');
+  }
+
+  if (sig.piled.length) {
+    out.push(`⚠ 主题堆积 ${sig.piled.length} 组（同一主题下页数多，考虑合并成规律页）`);
+    out.push(...trunc(sig.piled, ([tag, list]) => `    ${tag}: ${list.length} 页`));
+    out.push('');
+  }
+
+  if (sig.sinkOnly.length) {
+    out.push(`· 只被链、不链别人 ${sig.sinkOnly.length} 页（是终点，不回连——若它其实是枢纽，该补出链）`);
+    out.push(...trunc(sig.sinkOnly, (r) => `    ${r.slug}  (入 ${sig.inbound.get(r.id)})`));
+    out.push('');
+  }
+
+  if (sig.stale.length) {
+    out.push(`· ${staleDays} 天没动且无人链 ${sig.stale.length} 页（可能该删或该接进网络）`);
+    out.push(...trunc(sig.stale, (r) => {
+      const days = Math.round((Date.now() - r.mtime) / 86400_000);
+      return `    ${r.slug}  (${days} 天前)`;
+    }));
+    out.push('');
+  }
+
+  const issues = sig.danglingSupersede.length + sig.piled.length + sig.stale.length;
+  out.push(issues === 0
+    ? '✓ 没有需要立刻处理的进化问题'
+    : `共 ${issues} 处待处理。这只是体检，改不改由你判断 —— 程序不替人做内容决策。`);
+  return out.join('\n');
+}

package/src/brain/layers.js

@@ -78,7 +78,21 @@ export function resolveLayer(body, dirName) {
 /** 模板占位符 —— 它们出现在正文里是在**讨论语法**，不是真链接。
  * 实测（2026-11-01）：.brain 里 `[[作者]]` `[[页面名]]` `[[slug]]` 被当成真双链，
  * 污染断点词表并被报成悬挂链接。排除它们是判据，不是特例。 */
-const PLACEHOLDER = new Set(['作者', '页面名', 'slug', '页面', '页名', '名称', 'x', 'y', 'foo', 'bar']);
+const PLACEHOLDER = new Set([
+  '作者', '页面名', 'slug', '页面', '页名', '名称', 'x', 'y', 'foo', 'bar',
+  // 讨论「双链 vs wiki」时提到的词（2026-11-02 实测：log-2026-09-17 里
+  // 「抽词前剥掉 [[wiki]]」是指令，不是链接到某个 wiki 页）
+  'wiki',
+]);
+
+/** 占位符形状：`[[TOOLS:...]]`、`[[A...B]]`、`[[前缀:xxx]]` 这类。
+ * 它们是「描述语法时写的方括号」，不是真链接。
+ * 判据（2026-11-02）：含省略号，或含冒号且冒号前是纯大写字母（像常量/枚举写法）。 */
+function isPlaceholderShape(t) {
+  if (/[.．]{2,}|\.\.\.|…/.test(t)) return true;          // 省略号
+  if (/^[A-Z_]+[：:]/.test(t)) return true;                 // TOOLS:xxx 这类
+  return false;
+}
 
 /** 提取页面里的双链词（L6 断点层的数据来源）。
  * `[[x]]` / `[[x|别名]]` / `[[x#小节]]` 都取 x。
@@ -92,6 +106,7 @@ export function anchorsOf(body) {
     const t = m[1].trim();
     if (!t) continue;
     if (PLACEHOLDER.has(t)) continue;
+    if (isPlaceholderShape(t)) continue;
     // 纯符号/纯数字的不是页名
     if (!/[\p{L}\p{N}]/u.test(t)) continue;
     out.add(t);