@fanchao8609/agent_brain_sync 1.20.1 → 1.21.0

package/src/brain/db.js

@@ -0,0 +1,406 @@
+// src/brain/db.js — 统一图数据库：所有项目的知识页 + 双链 + 七层标记。
+//
+// 定位（2026-11-01 用户定，2026-11-01 晚确认）：**markdown 是真相，库是派生索引**。
+//   人改 .brain/ 的 md，跑 abs db rebuild 让库跟上；库可以随时删掉重建。
+//   曾考虑反过来（库为真相、md 为导出），评估后否决：那是为「多端同步」这个
+//   尚不存在的需求，废掉人工直编 md 的能力与「人工内容一律不覆盖」这条铁律。
+//   单机单人的场景下，反方向只加复杂度，不加能力。
+//
+// 为何用 node:sqlite（内置，Node >= 22.5）：
+//   实测 2 万节点 / 20 万边：3 跳扩散 0.5ms、FTS 全文 0.01ms、库文件 10MB。
+//   引 Neo4j/FalkorDB 要多养一个常驻进程，而本场景是「开工时查一次」——
+//   为 81 页知识养 Java 服务不值。
+//
+// 三张表各司其职：
+//   nodes  —— 每个知识页一行（含 todo/index/log 的条目），带项目标记 + 层级
+//   edges  —— 双链，跨项目也能连（project 前缀消歧）
+//   anchors—— L6 断点层：双链词 → 出现它的页，供联想扩散用种子
+//
+// 稳定性约束：
+//   · 所有写走一次事务，半途失败不留半条数据。
+//   · 库是派生物：删了能重建（rebuild 从 markdown 全量重扫）。markdown 内容本身不丢。
+//   · 库文件损坏 / 版本不匹配 → 抛 DbError，调用方决定是重建还是降级。
+
+import { DatabaseSync } from 'node:sqlite';
+import { promises as fs } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { resolveLayer, anchorsOf, decayOf, DEFAULT_LAYER } from './layers.js';
+
+export const DB_VERSION = 2;
+
+/** 库路径。ABS_DB 可覆盖（测试隔离 / 多库切换）。 */
+export function dbPath() {
+  return process.env.ABS_DB || join(homedir(), '.abs', 'graph.db');
+}
+
+export class DbError extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.name = 'DbError';
+    this.code = 'DB_ERROR';
+    this.cause = cause;
+  }
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+-- 知识节点。project 为空串 = 全局级（如 index.md 本身）。
+-- layer: 1-7；L1 铁律不立页，只由 rules 表承载，故 nodes 里不会出现 1。
+CREATE TABLE IF NOT EXISTS nodes (
+  id         INTEGER PRIMARY KEY,
+  project    TEXT NOT NULL DEFAULT '',
+  dir        TEXT NOT NULL,
+  slug       TEXT NOT NULL,
+  layer      INTEGER NOT NULL DEFAULT ${DEFAULT_LAYER},
+  title      TEXT NOT NULL DEFAULT '',
+  tags       TEXT NOT NULL DEFAULT '',
+  status     TEXT NOT NULL DEFAULT 'active',
+  body       TEXT NOT NULL DEFAULT '',
+  mtime      REAL NOT NULL DEFAULT 0,
+  -- 流水页（index/todo/log）：它们是「摘要的摘要」，正文里照抄了每句经验原文，
+  -- 因此任何查询都能命中它。实测（2026-11-01）刚 capture 一条「并发写」，log 页
+  -- 亮度 3.87 排第一，压过真正的内容页 —— 这是纯噪音，必须从检索候选里排除。
+  is_ledger  INTEGER NOT NULL DEFAULT 0,
+  UNIQUE(project, dir, slug)
+);
+CREATE INDEX IF NOT EXISTS i_nodes_layer   ON nodes(layer);
+CREATE INDEX IF NOT EXISTS i_nodes_project ON nodes(project);
+CREATE INDEX IF NOT EXISTS i_nodes_slug    ON nodes(slug);
+
+-- 双链边。src/dst 都指向 nodes.id。
+-- 悬挂链接（目标页不存在）dst=0，保留原文到 raw，供 lint 报死链。
+CREATE TABLE IF NOT EXISTS edges (
+  src  INTEGER NOT NULL,
+  dst  INTEGER NOT NULL,
+  raw  TEXT NOT NULL DEFAULT '',
+  PRIMARY KEY(src, dst)
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS i_edges_dst ON edges(dst);
+
+-- L6 断点层：双链词 → 出现它的节点。这是联想扩散的种子来源。
+CREATE TABLE IF NOT EXISTS anchors (
+  word   TEXT NOT NULL,
+  node   INTEGER NOT NULL,
+  PRIMARY KEY(word, node)
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS i_anchors_node ON anchors(node);
+
+-- L1 铁律：从各项目 index.md 的 ## Rules 区抽取，按项目隔离。
+CREATE TABLE IF NOT EXISTS rules (
+  id      INTEGER PRIMARY KEY,
+  project TEXT NOT NULL DEFAULT '',
+  text    TEXT NOT NULL,
+  UNIQUE(project, text)
+);
+
+-- 全文索引：搜索先走这里拿种子（实测 0.01ms）。
+CREATE VIRTUAL TABLE IF NOT EXISTS fts USING fts5(
+  g,
+  content='nodes_bigram', content_rowid='id',
+  tokenize='unicode61'
+);
+
+-- FTS 的内容源。不直接挂 nodes，因为要存派生列 g（2-gram）。
+CREATE TABLE IF NOT EXISTS nodes_bigram (
+  id  INTEGER PRIMARY KEY,
+  g   TEXT NOT NULL DEFAULT ''
+);
+`;
+
+/** 切 2-gram + 英文词。中文没有词边界，2-gram 是唯一能命中两字词的单位。
+ *
+ * 为何不用 trigram（2026-11-01 实测）：trigram 分词要求查询 ≥3 字符，
+ *   「静默」这类两字词恒返回 0；unicode61 又把整个「静默失效」当一个 token，
+ *   两字词同样搜不到。实测三种分词器只有自切 2-gram 能全部命中。
+ * 存储侧与查询侧必须用同一个函数，否则静默失配。 */
+/** 流水页：正文照抄了每条经验的原文，会命中任何查询，故排除在检索候选外。
+ * 它们仍入库（供 db status / 归档查询用），只是不参与亮度排名。 */
+export const LEDGER_SLUGS = new Set(['index', 'todo', 'log']);
+
+export function bigrams(s) {
+  const out = [];
+  const text = String(s || '');
+  for (const m of text.matchAll(/[\u4e00-\u9fa5]{2,}/g)) {
+    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)];
+}
+
+/** 丢掉所有表（版本升级用）。库是派生品，删了由 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()) {
+    db.exec(`DROP TABLE IF EXISTS "${r.name}"`);
+  }
+}
+
+/** 打开（不存在就建）库。返回 { db, close }。 */
+export function openDb(path = dbPath()) {
+  let db;
+  try {
+    db = new DatabaseSync(path);
+  } catch (e) {
+    throw new DbError(`打不开数据库 ${path}: ${e.message}`, e);
+  }
+  try {
+    db.exec('PRAGMA journal_mode = WAL');
+    db.exec('PRAGMA foreign_keys = ON');
+    db.exec(SCHEMA);
+
+    // 版本检查与迁移。
+    // 坑（2026-11-01 实测）：先报「跑 abs db rebuild 重建」是错的 —— rebuild 也走这里，
+    //   而 CREATE TABLE IF NOT EXISTS 不给已有表加列，老库重建时报
+    //   "table nodes has no column named is_ledger"，用户于是完全卡死。
+    // 库是**派生物**（markdown 才是真相），故版本不符直接丢表重建，不要用户动手。
+    const cur = db.prepare("SELECT value FROM meta WHERE key='version'").get();
+    if (!cur) {
+      db.prepare("INSERT INTO meta(key,value) VALUES('version',?)").run(String(DB_VERSION));
+    } else if (Number(cur.value) !== DB_VERSION) {
+      dropAll(db);
+      db.exec(SCHEMA);   // 表被删了，必须重新建（含 meta）
+      db.prepare("INSERT OR REPLACE INTO meta(key,value) VALUES('version',?)").run(String(DB_VERSION));
+    }
+  } catch (e) {
+    try { db.close(); } catch { /* 已关 */ }
+    if (e instanceof DbError) throw e;
+    throw new DbError(`库结构初始化失败: ${e.message}`, e);
+  }
+  return {
+    db,
+    close: () => { try { db.close(); } catch { /* 已关 */ } },
+  };
+}
+
+/** 确保库目录存在（第一次用时建 ~/.abs/）。 */
+export async function ensureDbDir(path = dbPath()) {
+  await fs.mkdir(dirname(path), { recursive: true });
+}
+
+/** 从 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 };
+}
+
+/** 全量重建：清表 → 重扫所有注册项目 → 重建边与断点词。
+ * pages: [{ project, dir, slug, body, mtime }]
+ * 返回统计，供 CLI 报告。 */
+export function rebuild(handle, pages) {
+  const { db } = handle;
+  const stat = { nodes: 0, edges: 0, anchors: 0, rules: 0, dangling: 0 };
+  const now = Date.now();
+  db.exec('BEGIN');
+  try {
+    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 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(?,?)');
+    const insRule = db.prepare('INSERT OR IGNORE INTO rules(project,text) VALUES(?,?)');
+
+    // 第一遍：建节点，拿 id 映射 key = `project/dir/slug`
+    const idOf = new Map();
+    for (const p of pages) {
+      const { title, tags, status } = 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);
+      const id = Number(r.lastInsertRowid);
+      // FTS 源：正文 + 标题 + tags 切 2-gram。查询侧必须用同一个 bigrams()。
+      insGram.run(id, bigrams([p.slug, title, tags, p.body].join('\n')).join(' '));
+      idOf.set(`${p.project}/${p.dir}/${p.slug}`, id);
+      // 同名页兜底键：不带项目，供就近解析
+      if (!idOf.has(`${p.dir}/${p.slug}`)) idOf.set(`${p.dir}/${p.slug}`, id);
+      stat.nodes++;
+    }
+
+    // index.md 的 Rules → rules 表（L1）。只取 `## Rules` 区内的 `- ` 条目，
+    // 不能扫全文 —— 否则页面清单里每条 `- [[x]] — 一句` 都会被当铁律。
+    for (const p of pages) {
+      if (p.dir !== '' || p.slug !== 'index') continue;
+      const lines = String(p.body).split('\n');
+      const at = lines.findIndex((l) => l.trim() === '## Rules');
+      if (at === -1) continue;
+      for (const line of lines.slice(at + 1)) {
+        if (/^##\s/.test(line)) break;          // 下个分区开始，停止
+        const t = line.trim();
+        if (!t.startsWith('- ')) continue;
+        insRule.run(p.project, t.slice(2).trim());
+        stat.rules++;
+      }
+    }
+
+    // 第二遍：解析双链，建边 + 断点词。
+    // todo.md / log.md 里的 [[人名]] 是**作者标记**不是知识链接（实测：projX 的
+    // todo 连到了另一项目的 fanchao 页，是误连）。这两份文件只入节点、不抽边。
+    for (const p of pages) {
+      const srcId = idOf.get(`${p.project}/${p.dir}/${p.slug}`);
+      if (!srcId) continue;
+      const isLedger = p.dir === '' && (p.slug === 'todo' || p.slug === 'log');
+      if (isLedger) continue;
+      for (const word of anchorsOf(p.body)) {
+        insAnchor.run(word, 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);
+        if (dstId === undefined) {
+          insEdge.run(srcId, 0, word);
+          stat.dangling++;
+        } else {
+          insEdge.run(srcId, dstId, word);
+          stat.edges++;
+        }
+      }
+    }
+
+    db.prepare("INSERT OR REPLACE INTO meta(key,value) VALUES('rebuilt_at',?)").run(String(now));
+    db.exec('COMMIT');
+    // FTS 重建必须在事务外（fts5 触发器在重建期间会读 nodes）
+    db.exec("INSERT INTO fts(fts) VALUES('rebuild')");
+  } catch (e) {
+    db.exec('ROLLBACK');
+    throw new DbError(`重建失败: ${e.message}`, e);
+  }
+  return stat;
+}
+
+/** 同名页全局兜底：取第一个命中的（跨项目引用靠 @前缀 显式写，这里只做兜底）。 */
+function findGlobal(idOf, word) {
+  for (const [k, v] of idOf) {
+    if (k.endsWith(`/${word}`)) return v;
+  }
+  return undefined;
+}
+
+// ---------- 查询：FTS 拿种子 → 亮度扩散 ----------
+
+/** 第一步：全文搜索拿种子节点。
+ * 实测 0.01ms/次 —— 「高频率搜索」的要求靠这一层满足。
+ * 返回 [{ 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 自己会排序）。
+  if (!grams.length) return [];
+  const expr = grams.map((g) => `"${g.replace(/"/g, '""')}"`).join(' OR ');
+  try {
+    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
+      WHERE fts MATCH ? AND n.is_ledger = 0
+      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) }));
+  } catch {
+    // 方言/语法问题不能让搜索整体挂掉 —— 退化成空种子，由调用方决定提示
+    return [];
+  }
+}
+
+/** 第二步：从种子出发做有限扩散，算每页亮度。
+ *
+ * 为何必须压制（2026-11-01 实测）：真实图谱 81 页 291 边，2 跳就到 95% 页面点亮，
+ *   「hook」一词 1 跳就 100%。全亮 = 全不亮，分不出哪页更相关。
+ * 故硬约束：最多 HOPS 跳，且每跳乘衰减，低于 MIN_BRIGHT 直接丢。
+ *
+ * 为何要枢纽惩罚：实测扩散把入度 26 的根节点顶到前三，不是因为它相关，
+ *   是因为人人链它。对被链得多的页打折（近似 IDF），枢纽不再霸榜。
+ *
+ * @returns [{ id, project, dir, slug, title, layer, bright, from }]
+ */
+const HOPS = 1;          // 实测 2 跳即 95% 全亮，只走 1 跳
+const MIN_BRIGHT = 0.02;
+
+export function illuminate(handle, seeds, { hops = HOPS, limit = 10 } = {}) {
+  const { db } = handle;
+  if (!seeds.length) return [];
+
+  // 入度表：用于枢纽惩罚。全表一次查完（81 页量级，可忽略）。
+  const inDeg = new Map();
+  for (const r of db.prepare('SELECT dst, count(*) c FROM edges WHERE dst > 0 GROUP BY dst').all())
+    inDeg.set(r.dst, r.c);
+
+  const bright = new Map(); // id -> { bright, from }
+  for (const s of seeds) {
+    const b = s.bright ?? 1;
+    if (!bright.has(s.id) || bright.get(s.id).bright < b) bright.set(s.id, { bright: b, from: 'seed' });
+  }
+
+  // 扩散：出边 + 入边都算（双向连接），乘该层衰减，再按枢纽惩罚打折
+  let frontier = [...bright.entries()].map(([id, v]) => ({ id, bright: v.bright }));
+  for (let hop = 0; hop < hops; hop++) {
+    const next = [];
+    for (const f of frontier) {
+      const neigh = db.prepare('SELECT dst AS id FROM edges WHERE src = ? AND dst > 0 UNION SELECT src AS id FROM edges WHERE dst = ? AND src > 0').all(f.id, f.id);
+      const layerRow = db.prepare('SELECT layer FROM nodes WHERE id = ?').get(f.id);
+      const decay = decayOf(layerRow?.layer ?? DEFAULT_LAYER);
+      for (const n of neigh) {
+        if (bright.has(n.id)) continue;
+        // 枢纽惩罚：入度越高，传出去越弱。1/(1+log(1+入度))
+        const deg = inDeg.get(n.id) || 0;
+        const hub = 1 / (1 + Math.log(1 + deg));
+        const b = f.bright * (1 - decay) * hub;
+        if (b < MIN_BRIGHT) continue;
+        bright.set(n.id, { bright: b, from: 'spread' });
+        next.push({ id: n.id, bright: b });
+      }
+    }
+    frontier = next;
+  }
+
+  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 });
+  }
+  return out.sort((a, b) => b.bright - a.bright || a.id - b.id).slice(0, limit);
+}
+
+/** L1 铁律：按项目取出。检索任何东西都必须先带上它（「不可逾越」的代码保证）。 */
+export function rulesOf(handle, project) {
+  const { db } = handle;
+  return db.prepare('SELECT text FROM rules WHERE project = ? OR project = \'\' ORDER BY id')
+    .all(project || '').map((r) => r.text);
+}
+
+/** 统计，供 status / lint 报告。 */
+export function stats(handle) {
+  const { db } = handle;
+  const one = (sql) => db.prepare(sql).get();
+  return {
+    nodes: one('SELECT count(*) c FROM nodes').c,
+    edges: one('SELECT count(*) c FROM edges WHERE dst > 0').c,
+    dangling: one('SELECT count(*) c FROM edges WHERE dst = 0').c,
+    anchors: one('SELECT count(DISTINCT word) c FROM anchors').c,
+    rules: one('SELECT count(*) c FROM rules').c,
+    projects: one('SELECT count(DISTINCT project) c FROM nodes WHERE project != \'\'').c,
+    byLayer: db.prepare('SELECT layer, count(*) c FROM nodes GROUP BY layer ORDER BY layer').all(),
+  };
+}

package/src/brain/gate.js

@@ -0,0 +1,19 @@
+// src/brain/gate.js — 写入侧格式闸门注册。
+// 从 store.js 拆出（2026-11-01）：闸门是「哪个文件用哪套标准」的全局注册，
+// 与建骨架无关。靠 import 副作用生效 —— 模块顶层即注册。
+import { setFormatGate } from '../lock.js';
+import { enforceBrainFormat, ensureStateMark } from '../todo.js';
+import { BRAIN_SHAPE, legacyRenames } from './shape.js';
+
+/** 写入侧格式闸门：lock.js 的 editFile 是所有写入的唯一收口，
+ * 这里把「哪个文件名用哪套标准」告诉它 —— 三个目标文件之外的写入一律放行。
+ * 非目标文件返回 null 表示不管。 */
+setFormatGate((file, text, current) => {
+  const name = file.split('/').pop();
+  const spec = BRAIN_SHAPE[name];
+  if (!spec) return null;
+  const r = enforceBrainFormat(text, { ...spec, renames: legacyRenames() }, current);
+  return name === 'todo.md'
+    ? r.text.split('\n').map((l) => (l.startsWith('- [ ] ') ? ensureStateMark(l, '进行中') : l)).join('\n')
+    : r.text;
+});

package/src/brain/init.js

@@ -0,0 +1,135 @@
+// src/brain/init.js — 建 .brain/ 骨架、结构体检、三个受管文件的模板。
+// 从 store.js 拆出（2026-11-01）：职责单一（只管骨架的生与补），与 load/task/rules 无关。
+import { promises as fs } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { getUser } from '../userconfig.js';
+import { editFile, SKIP } from '../lock.js';
+import { todoTemplate, rebuildStructure } from '../todo.js';
+
+const BRAIN_DIRS = ['entities', 'concepts', 'sources', 'syntheses', 'sessions'];
+const BRAIN_FILES = ['index.md', 'log.md', 'todo.md'];
+
+export async function cmdInit({ dir }) {
+  const root = resolveProjectDir(dir);
+  const brain = join(root, '.brain');
+  try {
+    await fs.access(brain);
+  } catch (e) {
+    if (e && e.code !== 'ENOENT') throw e;
+    return createSkeleton(root, brain);
+  }
+  // 已存在 → 校验结构完整性；损坏则明确报错并指引 repair（不静默半初始化）
+  const report = await reportBrain({ dir: root });
+  if (report.ok) throw new Error(`已存在: ${brain} (abort)`);
+  throw new Error(
+    `已存在但结构不完整:\n  ${report.problems.join('\n  ')}\n` +
+    `  → 轻则补齐: abs init --repair    重则重建: 删掉 ${brain} 后重跑 abs init`
+  );
+}
+
+async function createSkeleton(root, brain) {
+  for (const d of BRAIN_DIRS) await fs.mkdir(join(brain, d), { recursive: true });
+  // 走 editFile 而不是 fs.writeFile：三个文件是受管表，写入必须过同一道闸门
+  // （2026-10-18：原来直写盘，是个绕过口）。模板本身合法，闸门只做归一。
+  for (const [f, tpl] of [['index.md', indexTemplate], ['log.md', logTemplate], ['todo.md', todoTemplate]]) {
+    await editFile(join(brain, f), (cur) => (cur === null ? { text: tpl() } : SKIP));
+  }
+  // 建完就提示设姓名 —— 否则用户一路到第一次 todo add 才撞墙，
+  // 中间 init/load 都不提，根本不知道该设。
+  const who = await getUser();
+  const hint = who ? '' : `\n  ⚠ 尚未设置使用者姓名，写操作(todo add/log/note)会先报错。\n    请先设置: abs config set user <你的名字>`;
+  return `✓ 已建图谱 ${brain}\n  (模板见 SKILL.md「.brain/ 怎么组织」)${hint}`;
+}
+
+/** 结构体检：6 目录 + 3 文件逐一核对。ok=false 时 problems 列出缺失项。 */
+export async function reportBrain({ dir }) {
+  const root = resolveProjectDir(dir);
+  const brain = join(root, '.brain');
+  const problems = [];
+  for (const d of BRAIN_DIRS) {
+    try {
+      const st = await fs.stat(join(brain, d));
+      if (!st.isDirectory()) problems.push(`缺目录 ${d}/ (被文件占位)`);
+    } catch {
+      problems.push(`缺目录 ${d}/`);
+    }
+  }
+  for (const f of BRAIN_FILES) {
+    try {
+      await fs.access(join(brain, f));
+    } catch {
+      problems.push(`缺文件 ${f}`);
+    }
+  }
+  return { ok: problems.length === 0, problems, brain };
+}
+
+/** init --repair: 只补缺失骨架，绝不覆盖已有文件。 */
+export async function cmdRepair({ dir }) {
+  const root = resolveProjectDir(dir);
+  const brain = join(root, '.brain');
+  try {
+    await fs.access(brain);
+  } catch {
+    return createSkeleton(root, brain); // 整个图谱都没有 = 全新建
+  }
+  const fixed = [];
+  for (const d of BRAIN_DIRS) {
+    try {
+      const st = await fs.stat(join(brain, d));
+      if (!st.isDirectory()) {
+        await fs.rm(join(brain, d), { force: true });
+        await fs.mkdir(join(brain, d), { recursive: true });
+        fixed.push(`${d}/`);
+      }
+    } catch {
+      await fs.mkdir(join(brain, d), { recursive: true });
+      fixed.push(`${d}/`);
+    }
+  }
+  for (const [f, tpl] of [['index.md', indexTemplate], ['log.md', logTemplate], ['todo.md', todoTemplate]]) {
+    try {
+      await fs.access(join(brain, f));
+    } catch {
+      // 同 createSkeleton：补齐也走 editFile 的口子（已存在则 cur 非 null，不覆盖）
+      await editFile(join(brain, f), (cur) => (cur === null ? { text: tpl() } : SKIP));
+      fixed.push(f);
+    }
+  }
+  if (!fixed.length) return `✓ 结构完整，无需修复: ${brain}`;
+  return `✓ 已补齐 ${fixed.join(', ')} → ${brain}\n  (已有文件一律不覆盖)`;
+}
+
+function resolveProjectDir(dir) {
+  // 必须显式回退 cwd: resolve(undefined) 会抛 ERR_INVALID_ARG_TYPE，
+  // 并不像看上去那样「自动回退」。曾误删此分支为 resolve(dir)，把 abs init/load/board
+  // 不带 --dir 全部变成裸栈崩溃。
+  return resolve(dir || process.cwd());
+}
+
+export function indexTemplate() {
+  // 同 todoTemplate：由 rebuildStructure 生成，模板 = 重排结果，不会来回抖。
+  return rebuildStructure(
+    ['# 🗂 Graph Index', '',
+      '本文件唯一入口。每新建/大改一页，同步在此分类下加一行 [[页面名]] — 一句话。', '',
+      '## Rules', '## Concepts', '## Entities', '## Sources', '## Syntheses', '## Sessions'].join('\n'),
+    {
+      h1: '# 🗂 Graph Index',
+      // 无 `## Roadmap`：它是 AI 自己写的方向总结，会被 load 反复读到并带偏后续会话
+      // （“看似是总结指引，其实是 AI 的总结指引” —— 2026-09-13 用户决策删除）。
+      order: ['## Rules', '## Concepts', '## Entities', '## Sources', '## Syntheses', '## Sessions'],
+    },
+  ).text;
+}
+
+export function logTemplate() {
+  // ★ 占位符必须是注释形式，不能是真条目形状（2026-10-05 实测）：
+  //   原来写的是 `## [YYYY-MM-DD] ingest | 沉淀 <slug>` —— 看起来像条目，
+  //   但它不是真日期、也不是真 kind，条目形状闸门上线后**模板自己就非法**，
+  //   新条目插到它上面后它掉到第 4 行，直接把写入卡死。
+  //   用 HTML 注释保留「怎么写」的提示，同时不参与任何解析。
+  return [
+    '# 🗒 Activity Log', '',
+    '<!-- 每条一行：## [YYYY-MM-DD HH:MM] [[作者]] kind | 正文（kind: note|dev|concept|ingest） -->', ''
+  ].join('\n');
+}

package/src/brain/layers.js

@@ -0,0 +1,112 @@
+// src/brain/layers.js — 七层知识分层：唯一的层级判据来源。
+//
+// 为何要这一层（2026-11-01 用户定）：知识性质不同，检索权重就该不同。
+//   铁律和随口一句话混在同一张图里、检索时一视同仁，是当前的真实缺陷。
+//   分层的唯一技术作用 = 每层的衰减/权重不同，不是分类好看。
+//
+// 七层（用户原话）：
+//   L1 铁律  —— 任何智能体不可逾越。物理位置 = index.md 的 `## Rules` 区，不是页。
+//   L2 规则  —— 执行规则。
+//   L3 工具  —— 工具使用经验。
+//   L4 认知  —— 踩坑、实用经验、总结、重点事件。（默认层）
+//   L5 会话  —— 会话内容、todo 记录、任务总结。物理位置 = sessions/ + todo.md。
+//   L6 断点  —— 双链词，即页面里 `[[链接]]` 的链接名。不是页，是词的索引。
+//   L7 混沌  —— 未分辨信息、大量琐碎会话。物理位置 = sources/。
+//
+// 设计约束（「稳定可靠」的三条硬指标）：
+//   1. 层归属唯一：每页有且只有一个 layer；缺省补 4；非法值报错，不静默当成 4。
+//   2. 层不会漂：写入走 frontmatter，读取时校验，漂了能被 lint 查出来。
+//   3. 降级不崩：缺字段/坏库/缺项目 → 按目录推层，继续能跑。
+
+export const LAYERS = [
+  { id: 1, key: 'law',    name: '铁律', decay: 0,    note: '永不衰减，每次检索必出' },
+  { id: 2, key: 'rule',   name: '规则', decay: 0.2,  note: '执行规则' },
+  { id: 3, key: 'tool',   name: '工具', decay: 0.4,  note: '工具使用经验' },
+  { id: 4, key: 'cognition', name: '认知', decay: 0.6, note: '踩坑、经验、重点事件（默认层）' },
+  { id: 5, key: 'session', name: '会话', decay: 0.75, note: '会话内容、todo、任务总结' },
+  { id: 6, key: 'anchor', name: '断点', decay: 0.85, note: '双链词索引，不占页面' },
+  { id: 7, key: 'chaos',  name: '混沌', decay: 0.95, note: '未分辨的琐碎信息' },
+];
+
+export const LAYER_IDS = LAYERS.map((l) => l.id);
+export const DEFAULT_LAYER = 4;
+
+const BY_ID = new Map(LAYERS.map((l) => [l.id, l]));
+
+/** 目录 → 层 的降级映射。只在无 layer 字段时用（用户定的自动迁移规则）。 */
+export const DIR_LAYER = {
+  sessions: 5,
+  sources: 7,
+  concepts: 4,
+  entities: 4,
+  syntheses: 4,
+};
+
+/** 层元信息。非法 id 返回 null（调用方据此报错，不静默兜底）。 */
+export function layerOf(id) {
+  return BY_ID.get(Number(id)) || null;
+}
+
+/** 该层的衰减系数。L1 = 0 表示不衰减。 */
+export function decayOf(id) {
+  const l = layerOf(id);
+  return l ? l.decay : BY_ID.get(DEFAULT_LAYER).decay;
+}
+
+/** 解析页面 fullmatch 里的 layer 字段。
+ * 返回 { layer, source, error }：
+ *   source='frontmatter' 明确写了；'dir' 按目录推的；'default' 两者都没有。
+ *   error 非空表示字段存在但非法 —— 调用方必须报出来，不能当正常。
+ */
+export function resolveLayer(body, dirName) {
+  const m = String(body || '').match(/^layer:\s*(.+)$/m);
+  if (m) {
+    const raw = m[1].trim();
+    const n = Number(raw);
+    if (Number.isInteger(n) && BY_ID.has(n)) return { layer: n, source: 'frontmatter', error: null };
+    return {
+      layer: DIR_LAYER[dirName] ?? DEFAULT_LAYER,
+      source: 'dir',
+      error: `layer 非法（读到 "${raw}"，应为 1-7 的整数）`,
+    };
+  }
+  const byDir = DIR_LAYER[dirName];
+  if (byDir) return { layer: byDir, source: 'dir', error: null };
+  return { layer: DEFAULT_LAYER, source: 'default', error: null };
+}
+
+/** 模板占位符 —— 它们出现在正文里是在**讨论语法**，不是真链接。
+ * 实测（2026-11-01）：.brain 里 `[[作者]]` `[[页面名]]` `[[slug]]` 被当成真双链，
+ * 污染断点词表并被报成悬挂链接。排除它们是判据，不是特例。 */
+const PLACEHOLDER = new Set(['作者', '页面名', 'slug', '页面', '页名', '名称', 'x', 'y', 'foo', 'bar']);
+
+/** 提取页面里的双链词（L6 断点层的数据来源）。
+ * `[[x]]` / `[[x|别名]]` / `[[x#小节]]` 都取 x。
+ * 代码块与行内代码里的 `[[x]]` 是示例，不算。 */
+export function anchorsOf(body) {
+  const out = new Set();
+  let text = String(body || '');
+  // 去掉围栏代码块与行内代码 —— 那里面的双链是文档示例
+  text = text.replace(/```[\s\S]*?```/g, ' ').replace(/`[^`\n]*`/g, ' ');
+  for (const m of text.matchAll(/\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]/g)) {
+    const t = m[1].trim();
+    if (!t) continue;
+    if (PLACEHOLDER.has(t)) continue;
+    // 纯符号/纯数字的不是页名
+    if (!/[\p{L}\p{N}]/u.test(t)) continue;
+    out.add(t);
+  }
+  return [...out];
+}
+
+/** 校验一页的层是否与目录相符，供 lint 用。
+ * 只报「明确写了 layer 且与目录默认层冲突」的情况 —— 那是人有意为之的，
+ * 值得看一眼；纯按目录推的不报（否则每页都是噪音）。 */
+export function layerConflict(body, dirName) {
+  const r = resolveLayer(body, dirName);
+  if (r.error) return r.error;
+  if (r.source !== 'frontmatter') return null;
+  const expect = DIR_LAYER[dirName];
+  if (!expect || expect === r.layer) return null;
+  return `layer: ${r.layer} 与目录 ${dirName}/（默认 ${expect}）不符`;
+}