@fanchao8609/agent_brain_sync 1.22.0 → 1.23.0

package/README.md

@@ -120,9 +120,9 @@ abs todo done    TASK-1
 abs note "一句话经验" --tags 坑,docker    # 经验暂存 → sources/
 abs log "完成 X"                          # 记一行流水；abs log 无参 = 查看
 abs query <词>                            # 检索图谱（多词 OR）；已被推翻的经验默认隐藏（--all 可看）
-abs capture [--layer 1-7] "一句话"        # 按七层判层后直接落到位（不传 = L4 认知）
+abs capture [--layer 1-7] [--kind …] "一句话"  # 按七层判层后落到位（--kind: gotcha|decision|tradeoff|howto）
 abs db rebuild                            # 扫所有登记项目 → 建图数据库（~/.abs/graph.db）
-abs db search <词>                        # 走库检索：FTS 拿种子 + 亮度扩散，L1 铁律恒在最前
+abs db search <词> [--full]              # 走库检索：默认只给摘要+token 成本，--full 才附正文
 abs db status                             # 库体检：七层分布 / 悬挂链接 / 已入库项目
 abs db add                                # 把当前项目登记进 ~/.abs/projects.json
 abs db evolve                             # 知识进化体检：被推翻/断链/主题堆积/僵化页

package/bin/abs.js

@@ -210,6 +210,7 @@ function parseArgv(args) {
     tags: values.tags,
     limit: values.limit === undefined ? undefined : Number(values.limit),
     layer: values.layer,
+    kind: values.kind,
     mark: !!values.mark,
     status: !!values.status,
     title: values.title,
@@ -534,7 +535,7 @@ async function main() {
         break;
       }
       case 'capture': {
-        console.log(await cmdCapture({ dir: opts.dir, text: opts._.join(' '), layer: opts.layer, tags: opts.tags, title: opts.title }));
+        console.log(await cmdCapture({ dir: opts.dir, text: opts._.join(' '), layer: opts.layer, tags: opts.tags, title: opts.title, kind: opts.kind }));
         break;
       }
       case 'note': {
@@ -579,7 +580,7 @@ async function main() {
         const sub = opts._[0];
         const rest = opts._.slice(1);
         if (sub === 'rebuild') { console.log(await cmdDbRebuild({ dir: opts.dir })); break; }
-        if (sub === 'search') { console.log(await cmdDbSearch({ query: rest.join(' '), limit: Number(opts.limit) || 8 })); break; }
+        if (sub === 'search') { console.log(await cmdDbSearch({ query: rest.join(' '), limit: Number(opts.limit) || 8, full: !!opts.full })); break; }
         if (sub === 'status') { console.log(await cmdDbStatus()); break; }
         if (sub === 'evolve') { console.log(await cmdDbEvolve({ staleDays: Number(opts['stale-days']) || 90 })); break; }
         if (sub === 'add') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanchao8609/agent_brain_sync",
-  "version": "1.22.0",
+  "version": "1.23.0",
   "description": "agent-brain-sync: 跨会话 AI 编码记忆 — hook 纯触发 + CLI/MCP 读写 .brain markdown 图谱, 防并发写保护。",
   "type": "module",
   "license": "MIT",

package/skill/abs-agent-brain-sync/SKILL.md

@@ -19,7 +19,7 @@ description: "USE FOR abs / agent-brain-sync 跨会话记忆与任务续接。
 abs load                          # 开机读状态
 abs query <词>                    # 检索；abs resolve <页名> 反查路径
 abs todo add <id> --note "做什么"   # 登记；note/memo/state/done 见「进行中」
-abs capture [--layer 1-7] "…"    # 按七层判定落点后直接写入（不传=L4）
+abs capture [--layer 1-7] [--kind …] "…"   # 按七层判定落点后写入（--kind 分作用）
 abs note "经验" [--tags a,b]      # 暂存经验（一律 L7 混沌层）
 abs concept <slug> --title "…"    # 建概念页骨架
 abs rule add "一句话"             # 加 Rules；abs lint 体检；abs init 建图谱
@@ -110,6 +110,18 @@ abs rule add "一句话"             # 加 Rules；abs lint 体检；abs init
 
 判据不明时用 L4 —— 但**知道是工具经验就写 L3**：实测算过，本仓 52 页 concepts 里 23 页其实是 L3。
 
+**`--kind` 是另一条正交轴**（借 cl​aude-mem 的 observation 类型）：`layer` 说「什么性质」，`kind` 说「起什么作用」。
+
+| kind | 含义 | 何时用 |
+|---|---|---|
+| `gotcha` | 关键坑 | 踩了会白干、想不到的那种 |
+| `decision` | 决策 | 记「当时为什么这么选」 |
+| `tradeoff` | 权衡 | A 好但 B 也有理，最后选了哪个 |
+| `howto` | 做法 | 这类事该怎么做 |
+
+不传就不写（旧页留空，不强制补）。实测只有 `gotcha` 能靠 tags/标题机械识别，
+另三类判据在内容里 —— 别拿关键词瞎猜。
+
 `abs capture` 之后跑 `abs db rebuild` 让图数据库收录，否则检索拿不到它。
 
 ## 进行中：什么时候动它

package/src/brain/capture.js

@@ -52,13 +52,13 @@ export function layerGuide() {
   ].join('\n');
 }
 
-export async function cmdCapture({ dir, text, layer, tags, title }) {
+export async function cmdCapture({ dir, text, layer, tags, title, kind }) {
   const clean = String(text || '').trim();
   const layerArg = String(layer || '').trim();
 
   if (!clean) {
     return [
-      '用法: abs capture [--layer 1-7] "一句话" [--tags a,b] [--title "页标题"]',
+      '用法: abs capture [--layer 1-7] [--kind gotcha|decision|tradeoff|howto] "一句话" [--tags a,b] [--title "页标题"]',
       '',
       layerGuide(),
     ].join('\n');
@@ -86,6 +86,16 @@ export async function cmdCapture({ dir, text, layer, tags, title }) {
     return r;
   }
 
+  // 作用分档（2026-11-02 借 clo​ude-mem）：gotcha 坑 / decision 决策 / tradeoff 权衡 / howto 做法。
+  // 与 layer 正交：layer 说「这是什么性质的知识」，kind 说「它起什么作用」。
+  const KIND = {
+    gotcha: '坑', decision: '决策', tradeoff: '权衡', howto: '做法',
+  };
+  const kindArg = String(kind || '').trim().toLowerCase();
+  if (kindArg && !KIND[kindArg]) {
+    return `✗ --kind 只认 ${Object.keys(KIND).join(' / ')}（收到 "${kind}"）`;
+  }
+
   let root;
   try {
     root = await requireBrain(dir || process.cwd());
@@ -121,6 +131,7 @@ export async function cmdCapture({ dir, text, layer, tags, title }) {
     '---',
     `tags: [${['concept', ...tagList].join(', ')}]`,
     `layer: ${L}`,
+    ...(kindArg ? [`kind: ${kindArg}`] : []),
     `author: ${who}`,
     `updated: ${today()}`,
     'status: draft',

package/src/brain/db-cmd.js

@@ -176,7 +176,7 @@ export async function cmdDbRebuild({ dir } = {}) {
 }
 
 /** `abs db search <词>` —— 走库搜索：FTS 种子 → 亮度扩散。 */
-export async function cmdDbSearch({ query, limit = 8 } = {}) {
+export async function cmdDbSearch({ query, limit = 8, full = false } = {}) {
   const q = String(query || '').trim();
   if (!q) return '用法: abs db search <词>';
 
@@ -204,6 +204,20 @@ export async function cmdDbSearch({ query, limit = 8 } = {}) {
         : '（无命中。库可能是旧的：abs db rebuild 重扫）');
       return out.join('\n');
     }
+    // --full：显式要求时才读正文。默认不给 —— 这是索引优先的核心。
+    // 实测（2026-11-02）：ABS 单页平均 824 token，8 页全带就是 6600 token，
+    // 而真正被用上的往往只有 1-2 页。让「看全文」成为一个显式动作。
+    const bodies = new Map();
+    if (full) {
+      const root = await findBrainRoot(process.cwd());
+      if (root) {
+        for (const p of lit) {
+          const body = await fs.readFile(brainPath(root, p.dir, `${p.slug}.md`), 'utf8').catch(() => '');
+          if (body) bodies.set(p.id, body);
+        }
+      }
+    }
+
     out.push('', '--- 按亮度排序 ---');
     for (const p of lit) {
       // 亮度现在是 0.3~1.0（不再是早期可能到 165 万的异常值），
@@ -214,9 +228,22 @@ export async function cmdDbSearch({ query, limit = 8 } = {}) {
       // 跨项目的结果要显式标出来 —— 用户得知道「这条是别的项目的经验」，
       // 否则会以为是自己项目的结论（判据、上下文都可能不同）。
       const other = project && p.project && p.project !== project ? '  [跨项目]' : '';
-      out.push(`${bar} ${p.bright.toFixed(2)} L${p.layer} ${where}${tag}${other}`);
+      // 索引优先：给摘要 + 取全文成本，让「要不要看全文」成为一个可算的决定。
+      const about = p.digest ? `\n            ${p.digest}` : '';
+      const cost = p.tokens ? `  ~${p.tokens}tok` : '';
+      // 作用分档（gotcha/decision/tradeoff/howto）—— 同层里「哪种更该先看」的线索
+      const KIND_ICON = { gotcha: '🔴坑', decision: '🟤决策', tradeoff: '⚖️权衡', howto: '🔵做法' };
+      const kind = p.kind && KIND_ICON[p.kind] ? `  ${KIND_ICON[p.kind]}` : '';
+      out.push(`${bar} ${p.bright.toFixed(2)} L${p.layer} ${where}${tag}${other}${kind}${cost}${about}`);
+      if (full && bodies.has(p.id)) {
+        // 正文缩进显示，便于与索引行区分
+        const body = bodies.get(p.id).replace(/^---[\s\S]*?---\n/, '');   // 去掉 frontmatter
+        out.push(...body.split('\n').slice(0, 60).map((l) => `      │ ${l}`));
+        if (body.split('\n').length > 60) out.push('      │ …（已截断，用 abs resolve 看全文）');
+      }
     }
     out.push('', '（L1 铁律恒在最前；↝ 表示由邻居扩散点亮，非直接命中）');
+    out.push('（只给摘要与成本；要看全文: abs db search <词> --full  或  abs resolve <页名>）');
     if (project) {
       out.push(`（铁律只显示本项目 "${project}" 的 —— 别的项目的铁律不外借）`);
     }

package/src/brain/db.js

@@ -28,7 +28,7 @@ import { unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolveLayer, anchorsOf, decayOf, DEFAULT_LAYER } from './layers.js';
 
-export const DB_VERSION = 3;
+export const DB_VERSION = 4;
 
 /** 库路径。ABS_DB 可覆盖（测试隔离 / 多库切换）。 */
 export function dbPath() {
@@ -78,6 +78,15 @@ CREATE TABLE IF NOT EXISTS nodes (
   -- 被谁推翻」。原来这关系只存在于 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);
@@ -238,6 +247,37 @@ 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 || '');
@@ -245,7 +285,8 @@ function metaOf(body) {
   const tags = (t.match(/^tags:\s*(.+)$/m) || [])[1]?.replace(/^\[|\]$/g, '').trim() || '';
   const st = (t.match(/^status:\s*(.+)$/m) || [])[1]?.trim() || 'active';
   const sup = (t.match(/^superseded-by:\s*(.+)$/m) || [])[1]?.trim() || '';
-  return { title, tags, status: st, supersededBy: sup };
+  const kind = (t.match(/^kind:\s*(.+)$/m) || [])[1]?.trim() || '';
+  return { title, tags, status: st, supersededBy: sup, kind };
 }
 
 /** 全量重建：清表 → 重扫所有注册项目 → 重建边与断点词。
@@ -260,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,superseded_by)
-      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(?,?)');
@@ -270,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, supersededBy } = 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, supersededBy);
+        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(' '));
@@ -423,7 +464,7 @@ export function search(handle, query, { limit = 20 } = {}) {
   try {
     // 取 g 列才能数命中数；多取一些候选，过滤后仍可能不够 limit
     const rows = db.prepare(`
-      SELECT n.id, n.project, n.dir, n.slug, n.title, n.layer,
+      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
@@ -462,29 +503,33 @@ export function search(handle, query, { limit = 20 } = {}) {
     //   档位由加权覆盖率决定（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 };
-    }).sort((a, b) => {
+    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 不参与排序（铁律不立页，单独在最前输出）。
-      const wa = layerWeight(a.layer);
-      const wb = layerWeight(b.layer);
-      const sa = wa * a.bright;
-      const sb = wb * b.bright;
-      return (sb - sa) || (b.bright - a.bright) || (a.id - b.id);
-    });
+      .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 [];
@@ -546,8 +591,14 @@ export function illuminate(handle, seeds, { hops = HOPS, limit = 10 } = {}) {
   for (const [id, v] of bright) {
     // 扩散出口也要排除 superseded —— 入口（search）排了，出口不排就绕过去：
     // 实测旧结论页自己不出现在种子里，却被邻居扩散点亮（亮度 0.24 带 ↝）。
-    const n = db.prepare("SELECT id,project,dir,slug,title,layer FROM nodes WHERE id = ? AND is_ledger = 0 AND status != 'superseded'").get(id);
-    if (n) out.push({ ...n, bright: v.bright, from: v.from });
+    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) });
+    }
   }
   // 排序口径必须与 search 一致：层优先，同层再比亮度。
   // 坑（2026-11-02 实测）：原来这里只按 bright 排，把 search 已经排好的层序冲掉了 ——

package/src/brain/evolve.js

@@ -22,12 +22,20 @@ export function evolveSignals(handle, { staleDays = 90, now = Date.now() } = {})
   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. 被推翻的
+  // 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 danglingSupersede = superseded.filter((r) => {
-    if (!r.superseded_by) return true;                    // 标了推翻但没指向谁
-    return !all.some((x) => x.slug === r.superseded_by && x.project === r.project);
-  });
+  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 里的**业务标签**归类。
   //
@@ -60,7 +68,7 @@ export function evolveSignals(handle, { staleDays = 90, now = Date.now() } = {})
 
   return {
     total: all.length,
-    superseded, danglingSupersede,
+    superseded, replaced, retired, danglingSupersede,
     piled, sinkOnly, stale,
     byId, inbound, outbound,
   };
@@ -79,16 +87,20 @@ export function renderEvolve(sig, { sample = 5, staleDays = 90 } = {}) {
   out.push('');
 
   // 好消息放前面：推翻说明知识在更新
-  if (sig.superseded.length) {
-    out.push(`✓ 已推翻 ${sig.superseded.length} 页（知识在更新，不是坏事）`);
-    out.push(...trunc(sig.superseded, (r) => `    ${r.slug} → ${r.superseded_by || '(未指向)'}`));
+  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(`⚠ ${sig.danglingSupersede.length} 页写了取代者但目标页不存在（历史断了）`);
     out.push(...trunc(sig.danglingSupersede, (r) => `    ${r.slug}`));
     out.push('  修: abs supersede <旧页> --by <新页>');
     out.push('');

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);

package/src/brain/load.js

@@ -5,7 +5,7 @@ import { brainPath, requireBrain } from '../index.js';
 import { getUser, placeholderWarn } from '../userconfig.js';
 import { boardText, readTodo, collapseDone } from '../todo.js';
 import { strandedFor } from '../wrapup.js';
-import { keywords, recentFiles, topicStrength } from '../relevant.js';
+import { keywords, recentFiles, topicStrength, digest } from '../relevant.js';
 import { readIfExists, recentLogLines } from '../text.js';
 import { listPages } from '../lint.js';
 import { SOURCES_MAX } from '../lint.js';
@@ -136,6 +136,12 @@ export async function cmdLoad({ dir }) {
     const rel = await queryHintSection(root, todo);
     if (rel) sections.push('', rel);
   } catch { /* 提示失败不影响 load */ }
+  // 最相关几页（2026-11-02）：queryHint 给「该查什么词」，这里给「该读哪几页」。
+  // 放最后 —— 它是「再深入一层」的东西，前面先给状态与待办。
+  try {
+    const hot = await hotPagesSection(root, todo);
+    if (hot) sections.push('', hot);
+  } catch { /* 同上，失败静默 */ }
   // sources 堆积提醒：与「滞留」同构 —— 放在每次开工必经的顶部，而不是等人跑 lint。
   // 只数目录条目（不读文件），零成本。提炼仍手工：这里只负责送达，不替判断。
   try {
@@ -174,6 +180,94 @@ export function extractBlocks(todoText) {
   return out;
 }
 
+/** 从「活跃 todo + 最近改动的文件」推出当前上下文的关键词。
+ *
+ * 抽成公共函数（2026-11-02）：queryHint（给查询词）与 hotPages（给正文）
+ * 都要用，两处各算一遍必然漂移。
+ *
+ * 已剔掉任务行的结构记号：`- [ ] [状态] <id> [[作者]] —` 里只有「—」后面是真内容。
+ * 实测教训（2026-09-17）：不剔的话 `<id>` 与 `[[作者]]` 会进入词表，
+ * 而作者名恰好有自己的 entities/<作者>.md 页 → 命中页名 → 提出「查你自己的名字」。
+ */
+async function contextKeywords(root, todoText) {
+  const active = String(todoText || '')
+    .split('\n')
+    .filter((l) => /^\s*-\s*\[\s*\]/.test(l))
+    .map((l) => l.replace(/^\s*-\s*\[\s*\]\s*(?:\[[^\]]*\]\s*)?(?:\S+\s*)?/, '').replace(/\[\[[^\]]*\]\]/g, ' '))
+    .join(' ');
+  const files = await recentFiles(root, { n: 5 }).catch(() => []);
+  const src = [active, files.map((f) => f.name).join(' ')].filter(Boolean).join(' ');
+  return { kws: keywords(src), files };
+}
+
+/**
+ * 开机带出「当前上下文最相关的几页」—— 只给页名 + 一句话摘要，不贴正文。
+ *
+ * 与 queryHint 的分工（2026-11-02 用户定）：
+ *   queryHint 给「该查什么词」，本函数给「该读哪几页」。两者都只是**送达线索**，
+ *   不替代 query / db search，也不贴正文。
+ *
+ * 为何不贴正文：既有判据是「自动带出正文会让 query 更没人用，且无法按需求变化调整词」。
+ *   只给页名 + 摘要把选择权留给人：想看再 abs resolve / 读文件。
+ *
+ * 输入是环境事实（活跃 todo 的关键词 + 最近改过的文件），不需要人先想到搜索词 ——
+ *   这正是不依赖「主动查询」的那条路。
+ *
+ * 降级：库不存在 / 库坏了 / 任何异常 → 返回空串，不影响 load。
+ *
+ * @param {string} root 项目根
+ * @param {string} todoText
+ * @param {number} limit 最多几页
+ */
+export async function hotPagesSection(root, todoText, { limit = 3 } = {}) {
+  try {
+    const { kws } = await contextKeywords(root, todoText);
+    if (!kws.length) return '';
+    const { openDb, search, illuminate, dbPath } = await import('./db.js');
+    const { promises: fsp } = await import('node:fs');
+    const exists = await fsp.stat(dbPath()).then(() => true).catch(() => false);
+    if (!exists) return '';   // 库没建 → 静默跳过（不是错误）
+
+    // 项目名要与入库时一致 —— 铁律按项目隔离，读错项目就是串味
+    const project = String(root).split('/').filter(Boolean).pop() || '';
+    const h = openDb(dbPath());
+    try {
+      // 用几个强词合并成一组种子：逐个查再按 id 去重取最高亮度
+      const seeds = new Map();
+      for (const kw of kws.slice(0, 5)) {
+        for (const s of search(h, kw, { limit: 6 })) {
+          const prev = seeds.get(s.id);
+          if (!prev || s.bright > prev.bright) seeds.set(s.id, s);
+        }
+      }
+      if (!seeds.size) return '';
+      const lit = illuminate(h, [...seeds.values()], { limit: limit + 6 })
+        // 只留本项目的页：跨项目的经验可以查，但不该在开机首屏默认塞进来
+        .filter((r) => r.project === project)
+        // 再按**纯亮度**重排 —— illuminate 用的是「层权重 × 亮度」，
+        // 那是为了让知识页压过流水页（搜索场景对）；但开机首屏要看的是
+        // 「跟我现在干的事最贴的」，不是「层级最高的」。
+        // 实测：不重排时 L3 的 0.925 会排在 L4 的 1.000 前面 —— 读起来反直觉。
+        .sort((a, b) => b.bright - a.bright)
+        .slice(0, limit);
+      if (!lit.length) return '';
+
+      const rows = ['--- 当前最相关（按亮度，纯线索不贴正文；要看用 abs resolve <页名>）---'];
+      for (const r of lit) {
+        const one = await fsp.readFile(brainPath(root, r.dir, `${r.slug}.md`), 'utf8').catch(() => '');
+        const about = one ? digest(one, 80) : '';
+        const tag = r.from === 'spread' ? ' ↝' : '';
+        rows.push(`  ${r.bright.toFixed(2)} L${r.layer} [[${r.slug}]]${tag}${about ? ' — ' + about : ''}`);
+      }
+      return rows.join('\n');
+    } finally {
+      h.close();
+    }
+  } catch {
+    return '';   // 任何异常都不该弄坏 load
+  }
+}
+
 /**
  * 开工提示：直接给出该查的几个词，降低发起 query 的成本。
  *
@@ -195,19 +289,7 @@ export function extractBlocks(todoText) {
  * @param {{name:string,body:string}[]} [pages] 已读好的页（省一次磁盘扫描）
  */
 async function queryHint(root, todoText, pages) {
-  const active = String(todoText || '')
-    .split('\n')
-    .filter((l) => /^\s*-\s*\[\s*\]/.test(l))
-    // 剔掉任务行的结构记号再分词：`- [ ] [状态] <id> [[作者]] —` 里只有「—」后面是真内容。
-    // 实测教训（2026-09-17）：不剔的话 `<id>` 与 `[[作者]]` 会进入词表，
-    // 而作者名恰好有自己的 entities/<作者>.md 页 → 命中**页名** → 强度 1 过了门槛，
-    // 于是提示语变成「查一下你自己的名字」。建议查作者页不是“别重踩的经验”。
-    // 用 task 行自身的形状剥（与 idOfTaskLine 同源），不维护人名/任务名黑名单。
-    .map((l) => l.replace(/^\s*-\s*\[\s*\]\s*(?:\[[^\]]*\]\s*)?(?:\S+\s*)?/, '').replace(/\[\[[^\]]*\]\]/g, ' '))
-    .join(' ');
-  const files = await recentFiles(root, { n: 5 }).catch(() => []);
-  const src = [active, files.map((f) => f.name).join(' ')].filter(Boolean).join(' ');
-  const kws = keywords(src);
+  const { kws, files } = await contextKeywords(root, todoText);
   if (!kws.length) return '';
   const all = pages || await listPages(brainPath(root)).catch(() => []);
   const strength = topicStrength(all.map((p) => ({ name: p.slug, body: p.body })), kws);