@fanchao8609/agent_brain_sync 1.20.1 → 1.21.0

package/README.md

@@ -117,6 +117,12 @@ 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 db rebuild                            # 扫所有登记项目 → 建图数据库（~/.abs/graph.db）
+abs db search <词>                        # 走库检索：FTS 拿种子 + 亮度扩散，L1 铁律恒在最前
+abs db status                             # 库体检：七层分布 / 悬挂链接 / 已入库项目
+abs db add                                # 把当前项目登记进 ~/.abs/projects.json
+abs summon [--mark|--status]              # 会话总结托底：列出未总结 / 有更新的会话（不写盘）
 abs resolve <页名或id>                    # 反查页面路径（页改名后 id 不变）
 abs supersede <页名> [--by <新页>]        # 标记经验已失效（不删文件，保留历史；query 默认不再返回）
 abs status                                # 当前项目 + 图谱概要

package/bin/abs.js

@@ -3,6 +3,9 @@
 // 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 { cmdDbRebuild, cmdDbSearch, cmdDbStatus, addProject } from '../src/brain/db-cmd.js';
+import { cmdCapture } from '../src/brain/capture.js';
+import { cmdSummon } from '../src/brain/summon-cmd.js';
 import { setUser, getUser, userConfigPath } from '../src/userconfig.js';
 import { runInstall, runUninstall } from '../src/install.js';
 import { readFileSync } from 'node:fs';
@@ -101,6 +104,13 @@ const FLAG_SPEC = {
   'session': { type: 'string' },
   'payload': { type: 'string' },
   'tags': { type: 'string' },
+  // db search 用：最多返回几页（亮度排序后的截断）。未声明会被静默吞成 true。
+  'limit': { type: 'string' },
+  // capture 用：1-7 的层号。未声明会被静默吞成 true。
+  'layer': { type: 'string' },
+  // summon 用：布尔开关。未声明会被静默吞成 true（--mark 会变成真值即生效，但 --status 同理）。
+  'mark': { type: 'boolean' },
+  'status': { type: 'boolean' },
   'port': { type: 'string' },
   // note 的触发条件（何时该读这条经验）—— 供 load 的相关页推荐匹配。
   'when': { type: 'string' },
@@ -198,6 +208,10 @@ function parseArgv(args) {
     all: !!values.all,
     payload: values.payload,
     tags: values.tags,
+    limit: values.limit === undefined ? undefined : Number(values.limit),
+    layer: values.layer,
+    mark: !!values.mark,
+    status: !!values.status,
     title: values.title,
     desc: values.desc,
     help: !!values.help,
@@ -231,8 +245,11 @@ const usage = `abs — 跨会话记忆工具（.brain/ 图谱）
   todo                       任务看板 (add/note/state/done/archive)
   index | log | status       索引 / 流水 / 概要
   note <经验> [--tags a,b]   经验暂存 → sources/
+  capture [--layer 1-7] "…"  按七层判定落点后直接写入 (不传=L4)
+  summon [--mark|--status]   会话总结托底: 列出未总结/有更新的会话 (不写盘)
   concept <slug> --title …   建概念页骨架
   query <词…> [--all]       检索知识页 (多词 OR)
+  db rebuild|search|status   图数据库: 建库 / 亮度搜索 / 体检
   resolve <页名…>            反查页面路径
   supersede <页名> [--by 页] 标经验已失效
   review [--accept 页…|--reject 页…]  待确认页队列 (draft 升 active/否决)
@@ -512,6 +529,14 @@ async function main() {
         console.log(await cmdTask({ dir: opts.dir, action, id, section: opts.section, note: opts.note, as: opts.as, session: opts.session }));
         break;
       }
+      case 'summon': {
+        console.log(await cmdSummon({ dir: opts.dir, mark: !!opts.mark, full: !!opts.full, status: !!opts.status, limit: Number(opts.limit) || 15 }));
+        break;
+      }
+      case 'capture': {
+        console.log(await cmdCapture({ dir: opts.dir, text: opts._.join(' '), layer: opts.layer, tags: opts.tags, title: opts.title }));
+        break;
+      }
       case 'note': {
         console.log(await cmdNote({ dir: opts.dir, text: opts._.join(' '), tags: opts.tags, when: opts.when, impact: opts.impact, type: opts.type }));
         break;
@@ -550,6 +575,20 @@ async function main() {
         console.log(await cmdRule({ dir: opts.dir, action: isAdd ? 'add' : 'list', text: rest3.join(' ') }));
         break;
       }
+      case 'db': {
+        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 === 'status') { console.log(await cmdDbStatus()); break; }
+        if (sub === 'add') {
+          const r = await addProject(opts.dir || process.cwd());
+          console.log(`✓ 已登记项目: ${r}\n  建库: abs db rebuild`);
+          break;
+        }
+        console.log('用法: abs db rebuild | search <词> | status | add [--dir <项目根>]');
+        break;
+      }
       case 'query': {
         console.log(await cmdQuery({ dir: opts.dir, terms: opts._, includeSuperseded: opts.all }));
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanchao8609/agent_brain_sync",
-  "version": "1.20.1",
+  "version": "1.21.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,8 @@ description: "USE FOR abs / agent-brain-sync 跨会话记忆与任务续接。
 abs load                          # 开机读状态
 abs query <词>                    # 检索；abs resolve <页名> 反查路径
 abs todo add <id> --note "做什么"   # 登记；note/memo/state/done 见「进行中」
-abs note "经验" [--tags a,b]      # 暂存经验
+abs capture [--layer 1-7] "…"    # 按七层判定落点后直接写入（不传=L4）
+abs note "经验" [--tags a,b]      # 暂存经验（一律 L7 混沌层）
 abs concept <slug> --title "…"    # 建概念页骨架
 abs rule add "一句话"             # 加 Rules；abs lint 体检；abs init 建图谱
 ```
@@ -93,6 +94,24 @@ abs rule add "一句话"             # 加 Rules；abs lint 体检；abs init
 3. **读命中页**：`abs query <词>` → `abs resolve <页名或id>` 拿路径，**只读命中那几页**，绝不通读 `.brain/`；多文件汇总交 `ctx_execute` 在沙箱处理，只打印结论。
 4. **续 todo**：把顶部未完成项当当前任务开做；有新任务而 todo 没有 → `abs todo add <id> --note 做什么` 再动工。
 
+## 按七层总结（总结前必读）
+
+七层不是分类好看，是**检索权重不同**：L1 永不衰减，L7 几乎不参与。所以总结时必须先判层，判完直接落到位 —— 一律塞 sources/ 会让 44% 的知识按错误的权重参与检索。
+
+| 层 | 判据 | 落点 | 怎么落 |
+|---|---|---|---|
+| L1 铁律 | 违反就必须停下 | index 的 `## Rules` | `abs capture --layer 1`（≤42 字、禁链接） |
+| L2 规则 | 这个项目要遵守的做法 | `concepts/` + `layer: 2` | `abs capture --layer 2` |
+| L3 工具 | 某工具怎么用、有什么坑 | `concepts/` + `layer: 3` | `abs capture --layer 3` |
+| L4 认知 | 踩坑的根因与解法 | `concepts/` + `layer: 4` | `abs capture "…"`（默认） |
+| L5 会话 | 这次做了什么 | `log.md` / `sessions/` | `abs log` / `abs todo done` |
+| L6 断点 | 双链词 | 不立页，机器自动抽 | 不接手写 |
+| L7 混沌 | 还没想清的碎片 | `sources/` | `abs capture --layer 7` |
+
+判据不明时用 L4 —— 但**知道是工具经验就写 L3**：实测算过，本仓 52 页 concepts 里 23 页其实是 L3。
+
+`abs capture` 之后跑 `abs db rebuild` 让图数据库收录，否则检索拿不到它。
+
 ## 进行中：什么时候动它
 
 todo 是随改随写的活看板，和 git commit 同反射。
@@ -104,7 +123,7 @@ todo 是随改随写的活看板，和 git commit 同反射。
 | 被打断 / 干到一半 | `note` + 改到哪个文件哪一步 | 任务下追加一条子项（**一句话**） |
 | 干活中随手记多句发现 | `memo` + 原文 | `sessions/` 当日笔记，**不上看板** |
 | 子任务做完 | `done` + note 结语 + as 落地\|否决\|仅方案 | Done |
-| 总结出经验/坑/规律 | `abs_note` text + tags | `sources/` |
+| 总结出经验/坑/规律 | `abs capture --layer N`（先按上表判层） | 按层落到位 |
 
 **四个落点的区别**：
 

package/src/brain/capture.js

@@ -0,0 +1,170 @@
+// src/brain/capture.js — 按七层判定落点的统一总结入口。
+//
+// 为何需要它（2026-11-01 实测）：七层建好了，但总结这个动作还是老的一根管道 ——
+//   `abs note` 一律进 sources/（L7），`abs concept` 一律进 concepts/（L4），
+//   `abs rule` 一律进 ## Rules（L1）。落点由**命令**写死，不由**内容**决定。
+//   结果是 52 页 concepts 里 23 页（44%）其实是工具经验，全按 L4 的 0.6 衰减算 ——
+//   分层在检索权重上的作用被抹平了。
+//
+// 本命令让判层发生在「总结时」，判完直接落到位，不留二次分拣。
+// 沿用 note.js 的两条既有约定：整条相等才算重复（不是子串）、tmp+rename 原子落盘。
+
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { requireBrain, brainPath } from '../index.js';
+import { requireUser, atTag } from '../userconfig.js';
+import { today } from '../todo.js';
+import { registerInIndex } from '../note.js';
+import { cmdLog } from '../note.js';
+import { clip, slugOf } from '../text.js';
+import { LAYERS, layerOf, DEFAULT_LAYER } from './layers.js';
+import { autoIndex } from './db-cmd.js';
+
+/** 层 → 落点目录。L1/L6 不立页，由下面的分支单独处理。 */
+const LAYER_DIR = {
+  2: 'concepts',
+  3: 'concepts',
+  4: 'concepts',
+  5: 'sessions',
+  7: 'sources',
+};
+
+/** 判据表：输入时就看得到，不用记。 */
+export function layerGuide() {
+  const rows = [
+    ['1', '铁律', '违反就必须停下的事', 'abs capture --layer 1 "…"'],
+    ['2', '规则', '这个项目要遵守的做法', 'abs capture --layer 2 "…"'],
+    ['3', '工具', '某工具怎么用、有什么坑', 'abs capture --layer 3 "…"'],
+    ['4', '认知', '踩坑的根因与解法（默认）', 'abs capture "…"'],
+    ['5', '会话', '这次会话做了什么', 'abs log / abs todo done'],
+    ['6', '断点', '双链词，机器自动抽，不用手写', '（无）'],
+    ['7', '混沌', '还没想清的碎片', 'abs capture --layer 7 "…"'],
+  ];
+  return [
+    '按七层判定这一句该落在哪：',
+    '',
+    '层  名称   判据                        命令',
+    ...rows.map(([id, name, when, cmd]) => `L${id}  ${name}   ${when.padEnd(26)} ${cmd}`),
+    '',
+    '不传 --layer 时默认 L4（认知）。',
+    'L1 走铁律门槛（≤42 字、禁链接）；L6 是机器自动抽的双链词，不接手动。',
+  ].join('\n');
+}
+
+export async function cmdCapture({ dir, text, layer, tags, title }) {
+  const clean = String(text || '').trim();
+  const layerArg = String(layer || '').trim();
+
+  if (!clean) {
+    return [
+      '用法: abs capture [--layer 1-7] "一句话" [--tags a,b] [--title "页标题"]',
+      '',
+      layerGuide(),
+    ].join('\n');
+  }
+
+  // 层号校验：非法直接拒，不静默当默认层（否则记错层没人知道）
+  let L = DEFAULT_LAYER;
+  if (layerArg) {
+    const n = Number(layerArg);
+    if (!Number.isInteger(n) || !layerOf(n)) {
+      return `✗ --layer 非法（读到 "${layerArg}"）。只能是 1-7 的整数。\n\n${layerGuide()}`;
+    }
+    L = n;
+  }
+
+  // L6 是机器自动抽的双链词，不接受手动写入 —— 手写会让断点词表失真
+  if (L === 6) {
+    return '✗ L6 断点层是机器从双链里自动抽的词，不接手写。\n  想加索引词：在页面正文写 [[词]]，abs db rebuild 时会自动收录。';
+  }
+
+  // L1 铁律：复用 cmdRule 的门槛（≤42 字、禁链接），不另起一套
+  if (L === 1) {
+    const { cmdRule } = await import('./rules.js');
+    const r = await cmdRule({ dir, action: 'add', text: clean });
+    return r;
+  }
+
+  let root;
+  try {
+    root = await requireBrain(dir || process.cwd());
+  } catch {
+    return '未找到 .brain/ 图谱。先在项目根运行: abs init';
+  }
+  const who = await requireUser();
+  const { ensurePersonPage } = await import('../note.js');
+  await ensurePersonPage(root, who);
+
+  const dirName = LAYER_DIR[L];
+  if (!dirName) return `✗ L${L} 没有对应目录（这层不立页）。`;
+
+  const targetDir = brainPath(root, dirName);
+  await fs.mkdir(targetDir, { recursive: true });
+
+  // 幂等：整条相等才算重复（子串判据会把「新经验恰好是旧经验的子串」丢掉）
+  const titleLine = `TITLE: ${clean}`;
+  for (const f of (await fs.readdir(targetDir).catch(() => [])).filter((x) => x.endsWith('.md'))) {
+    const body = await fs.readFile(join(targetDir, f), 'utf8').catch(() => '');
+    if (body.split('\n').some((l) => l.trim() === titleLine)) {
+      return `• 已落过同文本 → ${dirName}/${f} (跳过重复)`;
+    }
+  }
+
+  const head = String(title || '').trim() || clip(clean, 80);
+  const tagList = String(tags || '').split(',').map((t) => t.trim()).filter(Boolean);
+  const meta = layerOf(L);
+  const slugSrc = slugOf(clean);
+  const file = `${today()}-${slugSrc || 'capture'}.md`;
+
+  const body = [
+    '---',
+    `tags: [${['concept', ...tagList].join(', ')}]`,
+    `layer: ${L}`,
+    `author: ${who}`,
+    `updated: ${today()}`,
+    'status: draft',
+    '---',
+    '',
+    `# ${meta.name}：${head}`,
+    '',
+    `TITLE: ${clean}`,
+    '',
+    '## 记录',
+    `- ${clean}`,
+    '',
+    // 「验证」是本仓硬要求（lint 的 NO-TAIL）：没尾巴的经验只能被相信、不能被验证。
+    // 占位注释不算内容（hasTail 明确跳过 <!-- -->），所以这里给的是**可填的实际位置**，
+    // 而不是一句注释就交差 —— 那会让新页天生就带 NO-TAIL。
+    '## 验证',
+    '- 做完怎么确认：跑什么命令 / 看什么信号 / 按什么判据',
+    '',
+    '## 关联连接',
+    `- ${atTag(who)} — 本页沉淀者`,
+    '（挂相关页双链，别留孤岛；本页无人链入时 lint 会报 NO-INBOUND）',
+    '',
+  ].join('\n');
+
+  // tmp + rename 原子落盘（并发读不会读到半写文件）
+  const dst = join(targetDir, file);
+  const tmp = join(targetDir, `.${file}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`);
+  await fs.writeFile(tmp, body, 'utf8');
+  await fs.rename(tmp, dst);
+
+  const slug = file.replace(/\.md$/, '');
+  const section = dirName === 'concepts' ? 'Concepts' : dirName === 'sessions' ? 'Sessions' : 'Sources';
+  await registerInIndex(root, section, slug, head);
+  await cmdLog({ dir: root, title: clean, kind: 'note' });
+
+  // 落盘即入库 —— 否则用户以为记下了，检索却空手而归（静默失效）。
+  // autoIndex 永不抛错也不阻塞：库坏了只是检索旧一点，不能让记笔记失败。
+  const idx = await autoIndex();
+
+  return [
+    `✓ 已落入 L${L} ${meta.name}层 → ${dirName}/${file}`,
+    `  ${clip(clean, 60)} ${atTag(who)}`,
+    `  该层衰减 ${meta.decay}（${meta.note}）`,
+    idx.ok ? '  已同步入库，abs db search 可查到' : `  （未入库：${idx.reason}）`,
+  ].join('\n');
+}
+
+export { LAYERS };

package/src/brain/db-cmd.js

@@ -0,0 +1,244 @@
+// src/brain/db-cmd.js — `abs db` 命令族：建库 / 搜索 / 状态。
+//
+// 这是「触发搜索先搜 SQLite」的入口。分工：
+//   abs query <词>   —— 旧的 markdown 直扫，保留不动（唯一被验证过的路径）
+//   abs db search <词> —— 走库：FTS 拿种子 → 亮度扩散，带 L1 铁律
+import { promises as fs } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { findBrainRoot, brainPath } from '../index.js';
+import { openDb, rebuild, search, illuminate, rulesOf, stats, ensureDbDir, dbPath } from './db.js';
+import { LAYERS } from './layers.js';
+
+const PAGE_DIRS = ['concepts', 'entities', 'sources', 'syntheses', 'sessions'];
+const FLAT_FILES = ['index.md', 'todo.md', 'log.md'];
+
+/** 扫一个项目的 .brain/ → 页面数组（含 index/todo/log 三份平铺文件）。 */
+async function scanProject(root, project) {
+  const out = [];
+  for (const d of PAGE_DIRS) {
+    const p = brainPath(root, d);
+    let files;
+    try { files = await fs.readdir(p); } catch { continue; }
+    for (const f of files) {
+      if (!f.endsWith('.md') || f.startsWith('_')) continue;
+      const full = join(p, f);
+      try {
+        const [body, st] = await Promise.all([fs.readFile(full, 'utf8'), fs.stat(full)]);
+        out.push({ project, dir: d, slug: f.replace(/\.md$/, ''), body, mtime: st.mtimeMs });
+      } catch { /* 读不到就跳过，不阻断整库 */ }
+    }
+  }
+  // 用户要求：todo / index / log 也进库。dir 为空串表示"根目录平铺文件"。
+  for (const f of FLAT_FILES) {
+    try {
+      const full = brainPath(root, f);
+      const [body, st] = await Promise.all([fs.readFile(full, 'utf8'), fs.stat(full)]);
+      out.push({ project, dir: '', slug: f.replace(/\.md$/, ''), body, mtime: st.mtimeMs });
+    } catch { /* 不存在 */ }
+  }
+  return out;
+}
+
+/** 项目登记表。~/.abs/projects.json：一行一个项目根路径。
+ * 用登记表而不是自动发现 —— 自动扫根目录会误收无关项目，且用户项目未必在一处。 */
+function projectsFile() {
+  // 坑（2026-11-01 实测）：曾写 join(dbPath(), '../../projects.json') —— 那是把
+  // graph.db 当**目录**往上退两级，实际落到 ~/projects.json（家目录），不在 ~/.abs/。
+  // 判据：配置与库同目录，用户找得到、备份得走一起。
+  return process.env.ABS_PROJECTS || join(dirname(dbPath()), 'projects.json');
+}
+
+async function readProjects() {
+  try {
+    const t = await fs.readFile(projectsFile(), 'utf8');
+    const j = JSON.parse(t);
+    return Array.isArray(j.projects) ? j.projects : [];
+  } catch {
+    return [];
+  }
+}
+
+/** 登记一个项目（幂等）。 */
+export async function addProject(dir) {
+  const root = resolve(dir);
+  const p = projectsFile();
+  const list = await readProjects();
+  if (!list.includes(root)) list.push(root);
+  await fs.mkdir(join(p, '..'), { recursive: true });
+  await fs.writeFile(p, JSON.stringify({ projects: list }, null, 2) + '\n');
+  return root;
+}
+
+/** `abs db rebuild` —— 扫所有登记项目，全量重建库。 */
+export async function cmdDbRebuild({ dir } = {}) {
+  const registered = await readProjects();
+  // 当前目录即使没登记也纳入（用户就地跑 rebuild 应生效）
+  const here = dir ? resolve(dir) : await findBrainRoot(process.cwd());
+  const roots = [...new Set([...registered, ...(here ? [here] : [])])];
+
+  if (!roots.length) {
+    return '✗ 没有可入的项目。先在项目根跑: abs db add   或  abs db rebuild';
+  }
+
+  const pages = [];
+  const used = [];
+  for (const root of roots) {
+    const found = await findBrainRoot(root);
+    if (!found) continue;                       // 登记了但目录没了 → 跳过，不报错
+    const project = found.split('/').filter(Boolean).pop() || 'unknown';
+    pages.push(...await scanProject(found, project));
+    used.push(`${project} (${found})`);
+  }
+  if (!pages.length) return '✗ 登记的项目都没有 .brain/ 图谱，无可入库内容。';
+
+  const path = dbPath();
+  await ensureDbDir(path);
+  const h = openDb(path);
+  try {
+    const st = rebuild(h, pages);
+    const lines = [
+      `✓ 已重建 ${path}`,
+      `  项目 ${used.length}: ${used.join(', ')}`,
+      `  节点 ${st.nodes} | 边 ${st.edges} | 悬挂 ${st.dangling} | 断点词 ${st.anchors} | 铁律 ${st.rules}`,
+    ];
+    if (st.dangling) {
+      lines.push('', `⚠ ${st.dangling} 条链接指向不存在的页（abs db status 可查）`);
+    }
+    return lines.join('\n');
+  } finally {
+    h.close();
+  }
+}
+
+/** `abs db search <词>` —— 走库搜索：FTS 种子 → 亮度扩散。 */
+export async function cmdDbSearch({ query, limit = 8 } = {}) {
+  const q = String(query || '').trim();
+  if (!q) return '用法: abs db search <词>';
+
+  const path = dbPath();
+  const exists = await fs.stat(path).then(() => true).catch(() => false);
+  if (!exists) return `✗ 库还没建（${path}）。先跑: abs db rebuild`;
+
+  const h = openDb(path);
+  try {
+    // L1 铁律永远先出 —— 「不可逾越」的代码保证，不靠读到文本才遵守
+    const project = process.env.ABS_PROJECT
+      || (await findBrainRoot(process.cwd()) || '').split('/').filter(Boolean).pop()
+      || '';
+    const rules = rulesOf(h, project);
+
+    const seeds = search(h, q, { limit: 12 });
+    const lit = illuminate(h, seeds, { limit });
+
+    const out = [`db search [${q}] → 种子 ${seeds.length} 条，亮起 ${lit.length} 页`];
+    if (rules.length) {
+      out.push('', `--- L1 铁律 ${rules.length} 条（任何检索先出）---`);
+      for (const r of rules) out.push(`- ${r}`);
+    }
+    if (!lit.length) {
+      out.push('', '（无命中。库可能是旧的：abs db rebuild 重扫）');
+      return out.join('\n');
+    }
+    out.push('', '--- 按亮度排序 ---');
+    for (const p of lit) {
+      const bar = '█'.repeat(Math.max(1, Math.round(Math.min(p.bright, 3) / 3 * 12)));
+      const where = [p.project, p.dir, p.slug].filter(Boolean).join('/');
+      const tag = p.from === 'spread' ? ' ↝' : '';
+      out.push(`${bar} ${p.bright.toFixed(2)} L${p.layer} ${where}${tag}`);
+    }
+    out.push('', '（L1 铁律恒在最前；↝ 表示由邻居扩散点亮，非直接命中）');
+    return out.join('\n');
+  } finally {
+    h.close();
+  }
+}
+
+/** `abs db status` —— 库的体检：计数、按层分布、项目列表、悬挂链接。 */
+export async function cmdDbStatus() {
+  const path = dbPath();
+  const exists = await fs.stat(path).then(() => true).catch(() => false);
+  if (!exists) return `库不存在: ${path}\n  先跑: abs db rebuild`;
+
+  const h = openDb(path);
+  try {
+    const s = stats(h);
+    const out = [
+      `📀 库: ${path}`,
+      `节点 ${s.nodes} | 边 ${s.edges} | 悬挂链接 ${s.dangling} | 断点词 ${s.anchors} | 铁律 ${s.rules}`,
+      '',
+      '--- 七层分布 ---',
+    ];
+    const byId = new Map(s.byLayer.map((r) => [r.layer, r.c]));
+    for (const l of LAYERS) {
+      const c = byId.get(l.id) ?? 0;
+      if (l.id === 1) {
+        out.push(`L1 ${l.name.padEnd(4)} ${String(s.rules).padStart(4)} 条（Rules 区，不立页）`);
+        continue;
+      }
+      if (l.id === 6) {
+        out.push(`L6 ${l.name.padEnd(4)} ${String(s.anchors).padStart(4)} 词（双链词，不立页）`);
+        continue;
+      }
+      out.push(`L${l.id} ${l.name.padEnd(4)} ${String(c).padStart(4)} 页`);
+    }
+    const dangling = h.db.prepare('SELECT raw FROM edges WHERE dst = 0 ORDER BY raw').all();
+    if (dangling.length) {
+      out.push('', `--- 悬挂链接 ${dangling.length} 条（目标页不存在）---`);
+      for (const d of dangling.slice(0, 10)) out.push(`  [[${d.raw}]]`);
+      if (dangling.length > 10) out.push(`  …另有 ${dangling.length - 10} 条`);
+    }
+    const projects = h.db.prepare("SELECT DISTINCT project FROM nodes WHERE project != '' ORDER BY project").all();
+    if (projects.length) {
+      out.push('', `--- 已入库项目 ${projects.length} 个 ---`);
+      for (const p of projects) out.push(`  ${p.project}`);
+    }
+    return out.join('\n');
+  } finally {
+    h.close();
+  }
+}
+
+export { scanProject };
+
+/**
+ * 静默自动入库：写入类命令（capture / note / concept）收尾时调。
+ *
+ * 为何要它（2026-11-01 实测）：capture 落盘后不重建，检索就查不到刚写的东西 ——
+ * 用户以为记下了，检索却空手而归，是静默失效。实测全量重建只要 0.07 秒（93 节点
+ * 2 个项目），比做增量同步的复杂度便宜得多，故一律全量。
+ *
+ * 边界（关键）：
+ *   · 永不抛错、永不阻塞主流程 —— 库坏了只是检索旧一点，不能让记笔记失败。
+ *   · 库从没建过时不自动创建：那是用户没打算用库，静默建一个 ~/.abs/graph.db
+ *     属于「没让做的事自己加戏」。只有库已存在才刷新。
+ * @returns {Promise<{ok:boolean, reason?:string}>}
+ */
+export async function autoIndex() {
+  try {
+    const path = dbPath();
+    const exists = await fs.stat(path).then(() => true).catch(() => false);
+    if (!exists) return { ok: false, reason: '库未建（跑 abs db rebuild 建）' };
+    await cmdDbRebuildQuiet();
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, reason: e?.message || '重建失败' };
+  }
+}
+
+/** cmdDbRebuild 的静默版：只重建，不返回给人看的文案。 */
+async function cmdDbRebuildQuiet() {
+  const registered = await readProjects();
+  const here = await findBrainRoot(process.cwd());
+  const roots = [...new Set([...registered, ...(here ? [here] : [])])];
+  if (!roots.length) return;
+  const pages = [];
+  for (const root of roots) {
+    const found = await findBrainRoot(root);
+    if (!found) continue;
+    const project = found.split('/').filter(Boolean).pop() || 'unknown';
+    pages.push(...await scanProject(found, project));
+  }
+  if (!pages.length) return;
+  const h = openDb(dbPath());
+  try { rebuild(h, pages); } finally { h.close(); }
+}