@fanchao8609/agent_brain_sync 1.22.0 → 1.24.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

@@ -2,7 +2,7 @@
 // bin/abs.js — abs CLI 入口。
 // abs <cmd> [args]
 // 命令: init / board / status / load / task / install / uninstall / help
-import { cmdInit, cmdStatus, cmdLoad, cmdTask, cmdLog, cmdQuery, cmdLint, cmdNote, cmdConcept, cmdShow, cmdRepair, cmdWrapup, cmdRule, cmdTeardownCheck, cmdTodoArchive, cmdResolve, cmdSupersede, cmdReview } from '../src/store.js';
+import { cmdInit, cmdStatus, cmdLoad, cmdRecall, cmdTask, cmdLog, cmdQuery, cmdLint, cmdNote, cmdConcept, cmdShow, cmdRepair, cmdWrapup, cmdRule, cmdTeardownCheck, cmdTodoArchive, cmdResolve, cmdSupersede, cmdReview } from '../src/store.js';
 import { cmdDbRebuild, cmdDbSearch, cmdDbStatus, cmdDbEvolve, addProject } from '../src/brain/db-cmd.js';
 import { cmdCapture } from '../src/brain/capture.js';
 import { cmdSummon } from '../src/brain/summon-cmd.js';
@@ -135,6 +135,8 @@ const FLAG_SPEC = {
   'by': { type: 'string' },
   'all': { type: 'boolean' },
   'keep-days': { type: 'string' },
+  // db evolve 用：多少天没动且无人链算 stale。未声明会被静默吞成 true（同 keep-days 坑）。
+  'stale-days': { type: 'string' },
   'help': { type: 'boolean' },
   'dry-run': { type: 'boolean' },
   'full': { type: 'boolean' },
@@ -145,7 +147,7 @@ const FLAG_SPEC = {
 };
 
 /** 已被"规范键"接管的 raw flag：不再原样漏出（见 parseArgv 返回处的白名单注释）。 */
-const KNOWN_RAW = new Set(['keep-days', 'dry-run', 'no-mcp', 'no-skill']);
+const KNOWN_RAW = new Set(['keep-days', 'stale-days', 'dry-run', 'no-mcp', 'no-skill']);
 
 function parseArgv(args) {
   // 坑: parseArgs 会把**任何** `-` 开头的 token 当选项，连正文一起吃：
@@ -210,6 +212,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,
@@ -219,6 +222,7 @@ function parseArgv(args) {
     repair: !!values.repair,
     full: !!values.full,
     keepDays: values['keep-days'],
+    staleDays: values['stale-days'],
     dryRun: !!values['dry-run'],
     mcp: !values['no-mcp'],
     skill: !values['no-skill'],
@@ -238,6 +242,7 @@ const usage = `abs — 跨会话记忆工具（.brain/ 图谱）
   abs todo add X --note "做什么"      登记任务 (done/state/note 管后续)
   abs note "经验一句话"               随手记经验; abs log "完成 X" 记成果
   abs query <词…>                   检索 .brain/; abs todo 看任务板
+  abs recall [词…]                  卡住时主动取相关页（不给词就按当前处境推）
 
 全部命令 (细节: abs <命令> --help):
   init [--repair]            建图谱 (当前目录)
@@ -362,6 +367,18 @@ const subUsage = {
     '参数:',
     '  --all    连 superseded(已失效)页一起返回',
   ].join('\n'),
+  recall: [
+    'abs recall — 卡住时主动取相关页（不需先想到检索词）',
+    '',
+    '用法:',
+    '  abs recall [词1 词2 …] [--limit N]',
+    '',
+    '不给词时，从当前处境推：活跃 todo 的关键词 + 最近改过的文件名。',
+    '给了词就只用你给的词，不混处境词。',
+    '',
+    '与 load 的区别: load 只在开工跑一次；recall 随时可跑（卡住/换方向时）。',
+    '与 query 的区别: query 枚全图命中；recall 只给按亮度亮的几页。',
+  ].join('\n'),
   config: [
     'abs config — 使用者姓名（写操作的作者标记）',
     '',
@@ -456,6 +473,11 @@ async function main() {
         rejectExtra(opts._, 'abs load');
         console.log(await cmdLoad({ dir: opts.dir }));
         break;
+      case 'recall': {
+        const limit = Number(opts.limit) > 0 ? Number(opts.limit) : 5;
+        console.log(await cmdRecall({ dir: opts.dir, terms: opts._, limit }));
+        break;
+      }
       case 'index':
         rejectExtra(opts._, 'abs index');
         console.log(await cmdShow({ dir: opts.dir, view: 'index' }));
@@ -534,7 +556,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,9 +601,9 @@ 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 === 'evolve') { console.log(await cmdDbEvolve({ staleDays: Number(opts.staleDays) || 90 })); break; }
         if (sub === 'add') {
           const r = await addProject(opts.dir || process.cwd());
           console.log(`✓ 已登记项目: ${r}\n  建库: abs db rebuild`);

package/bin/mcp.js

@@ -11,7 +11,7 @@ import { appendFile, mkdir } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { findBrainRoot, absLogDir } from '../src/index.js';
+import { findBrainRoot, absLogDir, AbsError } from '../src/index.js';
 import { cmdBoard, cmdLoad, cmdStatus, cmdTask, cmdQuery, cmdLint, cmdNote, cmdConcept, cmdWrapup, cmdRule, cmdResolve, cmdSupersede } from '../src/store.js';
 
 // ---------- 技术日志: MCP 请求跟踪（调试用, 与图谱 log.md 完全分开） ----------
@@ -40,6 +40,12 @@ function withTrace(name, handler) {
       return r;
     } catch (e) {
       await tlog(`tool=${name} cwd=${args?.cwd || '-'} args=${argBrief} → THROW ${Date.now() - t0}ms | ${String(e?.message || e).slice(0, 200)}`);
+      // 带 code 的 AbsError（如 requireUser 的 NO_USER）必须走 err() 结构化返回，
+      // 保留 code + fallback 自救指引 —— 裸 rethrow 只带 message，LLM 拿到后
+      // 不知道下一步跑什么（与 CLI 侧 `[CODE] + → fallback` 的既有行为不一致）。
+      if (e instanceof AbsError) {
+        return err(e.message, { code: e.code, fallback: e.fallback || undefined });
+      }
       throw e;
     }
   };

package/hooks/abs.pi.ts

@@ -231,6 +231,10 @@ const TODO_GUIDELINES = [
   // ⑦ 文档精简九条（用户 2026-10-22 定，原文见 skill 的「文档精简」一节）：
   // 管每一行写进 .brain 的文字；与上面六条行为规则不重叠，故不合并。
   'Every line you write into .brain/ (todo rows, log rows, knowledge pages, session snapshots) must pass the nine-bullet doc-slimming rule in the abs skill: only what serves the topic (drop the rest), no unverified summaries, ordered and layered, plain declarative wording (no rhetorical questions, no guessing), no duplication (cite the other doc instead), terse prohibitions, nothing the user did not ask for, plain Chinese.',
+  // ⑧ 有疑惑先查记忆（用户 2026-11-03 定）：主动搜索不是等报错才应激，
+  //   而是「心里形成关键词/有疑问的那一刻」自己查。上面七条只讲了登记，
+  //   没讲「记下来的东西怎么取」——实测一场会话从头到尾没查过一次记忆。
+  'When a doubt forms about something the project has likely dealt with before (a design choice, a past bug, a convention), run `abs recall <关键词>` (or `abs query <词>` for wider matches) BEFORE acting on the assumption. Do not wait for an error or for the user to remind you — asking the memory is your own decision, made the moment the question arises.',
 ]
 
 /** 当前项目是否有 .brain 图谱 —— 有才加指引（没图谱的项目里这指引是噪音）。

package/package.json

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

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

@@ -5,6 +5,23 @@ description: "USE FOR abs / agent-brain-sync 跨会话记忆与任务续接。
 
 # abs — 跨会话记忆 (agent-brain-sync)
 
+## 你有知识库，随时都能查
+
+`.brain/` 是**你自己的跨会话记忆库**：踩过的坑、做过的决定、验证过的做法都在里面。
+
+**查它是你的决定，不是别人提醒你才做。** 干活中一旦心里形成关键词、对某件事有疑问（这个坑以前踩过吗？这个约定是谁定的？），那一刻就主动查，**不要等报错、不要等用户提醒、不要等开工那一秒**。
+
+怎么查：
+
+```bash
+abs recall <关键词>     # 有疑问时用：按亮度出最相关的几页（不给词就从当前处境推）
+ab query <词>           # 想拿更全：多词 OR，枚举全图命中
+db search <词>          # 更高级：种子扩散亮起相关页，先出铁律
+abs resolve <页名>      # 拿到页名后反查路径，只读那一页
+```
+
+查完只读命中那几页，**绝不通读 `.brain/`**。答用 `[[页面名]]` 标来源。
+
 ## 触发器
 
 **关键词不是触发器，意图才是。**句子里出现 todo / 沉淀 / load / note 这些词，若是谈论、提问、定规则，只回应不执行。
@@ -19,7 +36,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 +127,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

@@ -54,7 +54,21 @@ export function uniqueProjectNames(roots) {
         for (const [r, v] of cand) out.set(r, v);
         break;
       }
-      if (depth === 4) for (const [r, v] of cand) out.set(r, v);  // 兜底：认了
+      if (depth === 4) {
+        // 深度到 4 仍重名（如 ~/a/x/软件/.agents 与 ~/b/y/软件/.agents 共享 4 层尾路径）：
+        // 不能「认了」直接塞 —— 那会让两个项目拿到同一个项目名，rebuild 撞
+        // UNIQUE(project,dir,slug) 约束整体崩溃（正是本函数要避免的场景）。
+        // 给仍碰撞的条目追加序号（-2/-3…），保证互不重名且可读。
+        const byVal = new Map();
+        for (const [r, v] of cand) {
+          if (!byVal.has(v)) { byVal.set(v, []); }
+          byVal.get(v).push(r);
+        }
+        for (const [v, rs] of byVal) {
+          if (rs.length === 1) { out.set(rs[0], v); continue; }
+          rs.forEach((r, i) => out.set(r, `${v}-${i + 2}`));
+        }
+      }
     }
   }
   return out;
@@ -176,7 +190,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 +218,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 +242,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);
@@ -240,6 +322,107 @@ async function queryHintSection(root, todo) {
   return queryHint(root, todo);
 }
 
+/**
+ * recall：卡住时主动取「跟当前处境相关的几页」，不需要先想到检索词。
+ *
+ * 为何要它（2026-11-03 实测）：hotPages 只挂在 load 上，于是只有开工那一刻会送页。
+ *   实测一场完整会话从头到尾没调过一次 abs —— 不是检索不准（命中确实准），
+ *   而是「要人先想到发起查询」这一步天然被跳过。一个出口只开一次，就等于没开。
+ *
+ * 与 hotPages 的分工：hotPages 是开机首屏（自动、固定 3 页）；
+ *   recall 是随时可调（agent 卡住/换方向时自己跑），且能补词。
+ *   两者共用 contextKeywords + 亮度搜索，不各算一套。
+ *
+ * 词从哪来：
+ *   - 传了词 → 用它（这时它就是个带上下文的搜索，仍会补处境词）
+ *   - 没传词 → 纯靠处境（活跃 todo 的关键词 + 最近改过的文件）
+ * 全部凭空无词 → 说清楚缺什么，不返回空列表充数。
+ *
+ * @param {{dir?:string, terms?:string[], limit?:number}} opts
+ */
+export async function cmdRecall({ dir, terms, limit = 5 } = {}) {
+  const given = (terms || []).flatMap((t) => String(t).trim().split(/\s+/)).filter(Boolean);
+  let root;
+  try {
+    root = await requireBrain(dir || process.cwd());
+  } catch {
+    return '未找到 .brain/ 图谱（无记忆可查）。先在项目根运行: abs init';
+  }
+  const todo = await readTodo(root).catch(() => '');
+  let kws = [];
+  let files = [];
+  try {
+    ({ kws, files } = await contextKeywords(root, todo));
+  } catch {
+    // 拔词失败不该拦住整个 recall
+  }
+  // 手动传的词优先级最高：用户/agent 已经想清楚要什么，就别把处境词混进去稀释
+  const words = given.length ? given : kws.slice(0, 5);
+  if (!words.length) {
+    return 'recall: 无从判断当前处境（todo 空、近期无改动、也没给词）。\n'
+      + '→ 直接给词: abs recall <词1> <词2>；或先 abs todo add 把在干的事登记上。';
+  }
+  try {
+    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 'recall: 图数据库还没建（亮度检索需要它）。先跑: abs db rebuild';
+
+    const project = String(root).split('/').filter(Boolean).pop() || '';
+    const h = openDb(dbPath());
+    let lit;
+    try {
+      const seeds = new Map();
+      // 整串先查（实测：`db search "并发 锁"` 能出 file-write-locking，
+      // 而逐词分开查的种子表里根本没它 —— 2-gram 索引对整串和单词的切法不同，
+      // 拆开就把最有用的命中拆没了。所以整串优先，再用逐词兜底补漏。
+      const whole = given.length ? words.join(' ') : words.join(' ');
+      for (const s of search(h, whole, { limit: 12 })) seeds.set(s.id, s);
+      for (const w of words) {
+        for (const s of search(h, w, { limit: 6 })) {
+          const prev = seeds.get(s.id);
+          if (!prev || s.bright > prev.bright) seeds.set(s.id, s);
+        }
+      }
+      if (!seeds.size) {
+        return `recall [${words.join(', ')}]: 库里没搜到相关页。\n`
+          + '→ 换个说法: abs recall <别的词>；看图谱全貌: abs query <词>。';
+      }
+      // 流水页降权（2026-11-03 实测）：不加时前 5 位里挤进 2 页 sessions/log-*，
+      // 还被排到第一，把 file-write-locking 这种真经验页顶下去。
+      // 与 query 用同一套判据（lint.js 的 isTerminal），不另造。只降权不剔除。
+      const isFlow = (r) => r.dir === 'sources' || (r.dir === 'sessions' && /^log-/.test(r.slug));
+      lit = illuminate(h, [...seeds.values()], { limit: limit * 8 })
+        .filter((r) => r.project === project)
+        .sort((a, b) => (b.bright - (isFlow(b) ? 1 : 0)) - (a.bright - (isFlow(a) ? 1 : 0)))
+        .slice(0, limit);
+    } finally {
+      h.close();
+    }
+    if (!lit.length) {
+      return `recall [${words.join(', ')}]: 搜到了种子，但本项目的页没有亮起来。\n`
+        + '→ 试试 abs query <词> 看全图命中。';
+    }
+    const rows = [`recall [${words.join(', ')}] → ${lit.length} 页（按亮度；看全文: abs resolve <页名>）`];
+    if (!given.length) {
+      const why = [
+        files.length ? `近期改动 ${files.length} 个文件` : '',
+        todo ? '活跃 todo' : '',
+      ].filter(Boolean).join(' + ');
+      if (why) rows.push(`  处境: ${why}`);
+    }
+    rows.push('');
+    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) : '';
+      rows.push(`  ${r.bright.toFixed(2)} L${r.layer} [[${r.slug}]]${about ? ' — ' + about : ''}`);
+    }
+    return rows.join('\n');
+  } catch (e) {
+    return `recall 失败: ${e instanceof Error ? e.message : String(e)}`;
+  }
+}
+
 /** sources 堆积提醒：返回 [标题行, ...内容行] 或 null。失败静默。 */
 async function sourcesCountSection(root) {
   const nsrc = await countSources(root);

package/src/brain/maintain.js

@@ -57,38 +57,45 @@ export async function cmdTodoArchive({ dir, keepDays = 3, dryRun = false } = {})
     return `[dry-run] 将归档 ${plan.archived.length} 天 / ${plan.count} 条（每天一个文件）\n  ${brief}${why}`;
   }
 
-  // 1) 归档目标 = 当天的会话快照文件（log-<日期>.md），写进其「任务归档」段。
+  // 1) todo.md：锁内重算（拿最新内容，避免与并发 done 互相覆盖），
+  //    todo 是权威 —— 会话页/ index 都跟随它，不反向。
+  //    先写 todo 再写会话页：todo 写失败（闸门拒绝/SKIP）时会话页不写，
+  //    避免「会话页已写、看板没动」的两边不一致（原顺序相反，且会话页裸写绕过锁）。
+  let archivedFinal = [];
+  await editFile(todoP, (cur) => {
+    // 坑（2026-10-05 实测抓到）: 这里漏传 maxLines → 锁内重算的 archived 为空 →
+    // 返回 SKIP → 磁盘上的 todo.md 一个字没动（而 sessions/ 归档页已经写了，
+    // 两边不一致）。**同参数的每个调用点都要一起改**。
+    const p2 = archiveDoneInText(cur ?? '', { keepDays: days, from: today(), maxLines: TODO_MAX_LINES });
+    if (!p2.archived.length) return SKIP;
+    archivedFinal = p2.archived;   // 锁内算出的权威清单，后续写会话页/index 用它
+    return { text: p2.text };
+  });
+  if (!archivedFinal.length) {
+    return `（todo 锁内重算无归档项，已跳过）${why}`;
+  }
+
+  // 2) 归档目标 = 当天的会话快照文件（log-<日期>.md），写进其「任务归档」段。
   //    为何合一（2026-09-15 用户定）: 归档与会话快照是**同一天的记录**，分两个文件查着要开两处。
   //    边界: ① 文件不存在→建只有归档段的页（那天可能没写快照）
   //          ② 文件已存在（含 AI 手写快照）→ 只替换归档段，段外逐字保留
   //    （硬规则「已存在的人工内容一律不覆盖」由 upsertArchiveSection 保证）。
+  //    走 editFile 锁（2026-11-03 审查修复）：append 语义必须与 setMemo 同一路数，
+  //    裸 readFile+tmp+rename 会让并发 archive 互相覆盖，丢一批归档任务行。
   const sessDir = brainPath(root, 'sessions');
-  for (const g of plan.archived) {
+  await fs.mkdir(sessDir, { recursive: true });
+  for (const g of archivedFinal) {
     const pageP = join(sessDir, `${g.slug}.md`);
-    let page = null;
-    try { page = await fs.readFile(pageP, 'utf8'); } catch { /* 首次 */ }
-    const nextPage = upsertArchiveSection(page, g);
-    const tmp = join(sessDir, `.${g.slug}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`);
-    await fs.writeFile(tmp, nextPage, 'utf8');
-    await fs.rename(tmp, pageP);
+    await editFile(pageP, (cur) => ({ text: upsertArchiveSection(cur, g) }));
   }
 
-  // 2) todo.md：锁内重算（拿最新内容，避免与并发 done 互相覆盖）
-  await editFile(todoP, (cur) => {
-    // 坑（2026-10-05 实测抓到）: 这里漏传 maxLines → 锁内重算的 archived 为空 →
-    // 返回 SKIP → 磁盘上的 todo.md 一个字没动（而 sessions/ 归档页已经写了，
-    // 两边不一致："说归档了但看板没变"）。**同参数的每个调用点都要一起改**。
-    const p2 = archiveDoneInText(cur ?? '', { keepDays: days, from: today(), maxLines: TODO_MAX_LINES });
-    return p2.archived.length ? { text: p2.text } : SKIP;
-  });
-
   // 3) index 登记（每个日期页一行，幂等）
   // 坑（2026-09-15 修）: 原先把归档页登记到 `## Sources` 区 —— 但它们在 sessions/ 里，
   // 旧数据实测就是错位的（09-10/09-12 两条曾键在 Sources 段，人工才发现）。现改登 `## Sessions`。
   const iP = brainPath(root, 'index.md');
   await editFile(iP, (index) => {
     if (!index) return SKIP;
-    const missing = plan.archived.filter((g) => !index.includes(`[[${g.slug}]]`));
+    const missing = archivedFinal.filter((g) => !index.includes(`[[${g.slug}]]`));
     if (!missing.length) return SKIP;
     const sIdx = index.indexOf('## Sessions');
     if (sIdx === -1) return SKIP;
@@ -100,8 +107,10 @@ export async function cmdTodoArchive({ dir, keepDays = 3, dryRun = false } = {})
     return { text: next };
   });
 
-  const files = plan.archived.map((g) => `sessions/${g.slug}.md`).join('\n  ');
-  return `✓ 已归档 ${plan.archived.length} 天 / ${plan.count} 条\n  ${brief}\n  → ${files}${why}`;
+  const files = archivedFinal.map((g) => `sessions/${g.slug}.md`).join('\n  ');
+  const count = archivedFinal.reduce((n, g) => n + g.count, 0);
+  const briefFinal = archivedFinal.map((g) => `${g.date}(${g.count})`).join(' ');
+  return `✓ 已归档 ${archivedFinal.length} 天 / ${count} 条\n  ${briefFinal}\n  → ${files}${why}`;
 }
 
 /**

package/src/query.js

@@ -53,7 +53,7 @@ export async function cmdQuery({ dir, terms, includeSuperseded }) {
           continue;
         }
         hits.push({
-          full, slug, matched: rank.matched, kind: rank.kind, fuzzyScore: rank.score, via: rank.via,
+          full, slug, dir: d, matched: rank.matched, kind: rank.kind, fuzzyScore: rank.score, via: rank.via,
           author: au ? au[1].trim() : '',
           id: idOfPage(body, slug),
           status: st,
@@ -68,11 +68,18 @@ export async function cmdQuery({ dir, terms, includeSuperseded }) {
   // 坑(2026-09-16 实测): 不加区分时查 file-write-locking 返回 26 页（几乎全图）——
   //   连字符词的 2-gram 太通用，模糊命中把无关页也拉进来。
   //   规则：只要有任何精确命中，模糊命中的就不排在前面（但也不丢弃，单列一段）。
+  // 流水页降权（2026-11-02 实测）：查「并发 写 锁」时前 10 位里挤进 4 页
+  // sessions/log-*，内容页被顶下去。流水页只是「那天做了什么」的草稿记录，
+  // 正文里碰巧出现检索词不代表它是这条经验所在。判据沿用 lint.js 的
+  // isTerminal（sources/ 与 sessions/log-*），不另造一套。
+  // 只降权不剔除：真要查某天的流水，它仍在结果里，只是排到内容页之后。
+  const isFlow = (h) => h.dir === 'sources' || (h.dir === 'sessions' && /^log-/.test(h.slug));
+  const rankBy = (h) => h.fuzzyScore - (isFlow(h) ? 20 : 0);
   const exactHits = hits.filter((h) => !h.hidden && h.kind === 'exact')
-    .map((h) => ({ ...h, score: h.fuzzyScore }))
+    .map((h) => ({ ...h, score: rankBy(h) }))
     .sort((a, b) => b.score - a.score);
   const fuzzyHits = hits.filter((h) => !h.hidden && h.kind === 'fuzzy')
-    .map((h) => ({ ...h, score: h.fuzzyScore }))
+    .map((h) => ({ ...h, score: rankBy(h) }))
     .sort((a, b) => b.score - a.score);
   // 有精确命中 → 模糊全藏起来（但不静默：告知数量 + 怎么看）
   const fuzzySuppressed = exactHits.length > 0 && fuzzyHits.length > 0;

package/src/store.js

@@ -19,7 +19,7 @@ export { BRAIN_SHAPE, LEGACY_MARKS, checkBrainShape } from './brain/shape.js';
 import './brain/gate.js';
 
 // ---- 只读呈现 ----
-export { cmdBoard, cmdStatus, cmdLoad, cmdShow, extractBlocks } from './brain/load.js';
+export { cmdBoard, cmdStatus, cmdLoad, cmdShow, cmdRecall, extractBlocks } from './brain/load.js';
 
 // ---- Rules ----
 export { RULES_HEADING, RULES_MAX, RULE_BODY_MAX, readRules, cmdRule } from './brain/rules.js';