@fanchao8609/agent_brain_sync 1.20.1 → 1.22.0

package/src/brain/evolve.js

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

package/src/brain/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}）不符`;
+}

package/src/brain/load.js

@@ -0,0 +1,273 @@
+// src/brain/load.js — 开机读状态：board / status / load。都是只读呈现。
+// 从 store.js 拆出（2026-11-01）：与写命令分开，load 是开机第一入口，读起来要能一口气看完。
+import { promises as fs } from 'node:fs';
+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 { readIfExists, recentLogLines } from '../text.js';
+import { listPages } from '../lint.js';
+import { SOURCES_MAX } from '../lint.js';
+import { checkBrainShape } from './shape.js';
+import { rulesSection } from './rules.js';
+import { collapseIndex } from '../page.js';
+
+// ---------- board: 看板 ----------
+export async function cmdBoard({ dir, full }) {
+  const root = await requireBrain(dir || process.cwd());
+  return boardText(root, undefined, { full: !!full });
+}
+
+// ---------- status: 定位报告 + 图谱概要 ----------
+export async function cmdStatus({ dir }) {
+  const root = await requireBrain(dir || process.cwd());
+  const entries = await listBrainFiles(root);
+  return [
+    `📂 abs → 项目: ${root}`,
+    `图谱: ${brainPath(root)}`,
+    '',
+    entries.length ? entries.join('\n') : '(图谱为空)',
+  ].join('\n');
+}
+
+async function listBrainFiles(root) {
+  const out = [];
+  const dirs = ['concepts', 'entities', 'sources', 'syntheses', 'sessions'];
+  for (const d of dirs) {
+    const p = brainPath(root, d);
+    try {
+      const files = (await fs.readdir(p)).filter((f) => f.endsWith('.md'));
+      out.push(`${d}/: ${files.length} 页`);
+    } catch { out.push(`${d}/: 0 页`); }
+  }
+  return out;
+}
+
+// ---------- load: 开机读状态 ----------
+export async function cmdLoad({ dir }) {
+  const root = await requireBrain(dir || process.cwd());
+  // 结构核对先跑：load 每回都要读这三个文件，顺手把它们形状摆正（缺分区）或提个醒（无头）。
+  // 正常时完全静默、零字节，不增加 load 体积（load 已被压缩到 ~1.8k token）。
+  const shape = await checkBrainShape(root).catch(() => ({ fixed: [], warn: [] }));
+  const todo = await readTodo(root);
+  const index = await readIfExists(brainPath(root, 'index.md'));
+  const log = await readIfExists(brainPath(root, 'log.md'));
+  const stranded = await strandedFor(root);
+  const sections = [
+    `📂 abs → 项目: ${root}`,
+  ];
+  if (shape.fixed.length || shape.warn.length) {
+    const rows = [
+      ...shape.fixed.map((a) => `  ✓ 已补: ${a}`),
+      ...shape.warn.map((a) => `  ⚠ ${a}`),
+    ];
+    // 那句提示只适用于「标题非标准」：其他 warn（如格式不合规）说这句会误导。
+    if (shape.warn.some((a) => a.includes('标题非标准'))) {
+      rows.push('  （无头文件不自动改：结构可能整体脱轨，请手工对齐 .brain/ 模板）');
+    }
+    sections.push('--- 文件形状核对 ---', ...rows, '');
+  }
+  // 未设姓名/姓名是占位名时开场就提醒 —— load 是开机第一屏，不在这里提，
+  // 用户要撞到第一次写操作才知道（init/load 一路沉默）。
+  // 占位名（历史遗留 tester/foo）必须提：配置里有值 ≠ 名字是对的。
+  // 一次调用拿两者（placeholderWarn 内部也要 getUser）—— 原先分两次读盘（2026-10-03 审查）。
+  const who = await getUser();
+  const ph = who ? await placeholderWarn() : null;
+  if (!who) {
+    sections.push(
+      '⚠ 尚未设置使用者姓名（写操作会先报错）',
+      '→ abs config set user <你的名字>    (或临时: ABS_USER=<名字> abs ...)',
+      ''
+    );
+  } else if (ph) {
+    sections.push(
+      `⚠ 当前作者名是占位名 "${ph}" —— 之后所有项目的 todo/log 都会标它。`,
+      '→ abs config set user <你的真名>    (或临时: ABS_USER=<名字> abs ...)',
+      ''
+    );
+  }
+  sections.push(
+    // Rules 单独成段且放在最前（仅次于项目行/滞留）：它是硬规则，不是普通清单。
+    // 坑: 曾在 index 段内与页面清单平铺 —— AI 会当普通清单划过，而它每条都是付过代价的。
+    ...(rulesSection(index) ? [rulesSection(index), ''] : []),
+    collapseIndex(index) || '(index.md 为空)',
+    '',
+    // 两区制：Todo（未完成，行首带状态标记）+ Done。
+    '--- Todo Board (todo.md) ---',
+    collapseDone(todo).text || '(todo.md 为空)',
+    '\n（Done 已按日期折叠计数；明细: abs todo --full）',
+    '',
+    '--- 最近动作 (log.md, 最新 5 条) ---',
+    recentLogLines(log, 5) || '(log.md 为空)',
+  );
+  if (stranded.length) {
+    const rows = stranded.map((t) => {
+      const bp = t.bp.length ? `\n    ${t.bp.map((b) => (b.startsWith('[') ? `- ${b}` : `- [ ] ${b}`)).join('\n    ')}` : '';
+      return `  - ${t.body}${bp}`;
+    });
+    // 插在项目行之后、其它内容之前
+    sections.splice(
+      1, 0,
+      '⏳ 上会话滞留（未 done，先对账）',
+      rows.join('\n'),
+      '→ 完成: abs todo done <id>；未完: abs todo note <id> --note 子项',
+      ''
+    );
+  }
+  // 卡点提取（2026-09-16，定位 = 看板可见性）：
+  // 从 todo 里抽出带 `阻塞:` / `等待:` 的断点行，集中展示。
+  // 为何需要：断点行在任务下方，一屏扫过去看不出"哪些事在等人/等外部"。
+  // 只提取不求全 —— 只有明确写了前缀的才被抽出，没写的不猜。
+  const blocks = extractBlocks(todo);
+  if (blocks.length) {
+    const at = sections.findIndex((s) => String(s).startsWith('--- Rules'));
+    sections.splice(at === -1 ? 1 : at, 0,
+      `⛔ 卡点 ${blocks.length} 条（在等外部条件）`,
+      ...blocks.map((b) => `  - ${b.id}: ${b.why}`),
+      '');
+  }
+  // 相关页提示（2026-09-16）：实测 abs_query 几乎不被调用（MCP 日志 task 234 / note 54 / load 53 vs query 2）。
+  // 根因：load 只列目录 → 模型觉得"我记过了" → 真需要时靠印象。模型不知道自己不知道什么。
+  // 解法（用户定）：不替它查 —— 而是【把该查的词直接给出来】，降低发起查询的成本。
+  //   自动带出正文是错的方向：那会让 query 更没人用，且无法按需求变化调整词。
+  // 失败静默：这只是 additive 提示，出任何错都不应弄坏 load。
+  try {
+    const rel = await queryHintSection(root, todo);
+    if (rel) sections.push('', rel);
+  } catch { /* 提示失败不影响 load */ }
+  // sources 堆积提醒：与「滞留」同构 —— 放在每次开工必经的顶部，而不是等人跑 lint。
+  // 只数目录条目（不读文件），零成本。提炼仍手工：这里只负责送达，不替判断。
+  try {
+    const srcWarn = await sourcesCountSection(root);
+    if (srcWarn) {
+      const at = sections.findIndex((s) => String(s).startsWith('--- Rules'));
+      sections.splice(at === -1 ? 1 : at, 0, ...srcWarn);
+    }
+  } catch { /* 提醒失败不影响 load */ }
+  return sections.join('\n');
+}
+
+/**
+ * 从 todo 正文抽出"卡点"行，供 load 集中展示。
+ *
+ * 识别的前缀：`阻塞:` / `等待:` / `等 `（在断点/附属行里）。
+ * 为何只认前缀（不靠语义猜）：没写就是没写，猜出来的卡点比不报更坑。
+ *
+ * @returns {{id:string, why:string}[]}
+ */
+export function extractBlocks(todoText) {
+  const out = [];
+  let curId = null;
+  for (const line of String(todoText || '').split('\n')) {
+    // 任务行（未完成）：`- [ ] [状态] ID [[who]] — 描述`
+    const t = line.match(/^\s*-\s*\[\s*\]\s*(?:\[[^\]]*\]\s*)?(\S+)/);
+    if (t) { curId = t[1]; continue; }
+    // 完成行：不再跟踪
+    if (/^\s*-\s*\[x\]/.test(line)) { curId = null; continue; }
+    if (!curId) continue;
+    // 附属行（缩进子项）里找卡点前缀。
+    // 旧写法 `↳ 断点: 阻塞: …`（存量）也认 —— 保留一条前缀兼容，以免漏报历史卡点。
+    const m = line.match(/^\s*(?:↳\s*(?:断点|卡点)?[:：]\s*)?(?:阻塞|等待|等)[:：]\s*(.+)$/);
+    if (m && m[1].trim()) out.push({ id: curId, why: m[1].trim() });
+  }
+  return out;
+}
+
+/**
+ * 开工提示：直接给出该查的几个词，降低发起 query 的成本。
+ *
+ * 为何不是"替它查"（2026-09-16 用户定）：自动带出正文会让 query 更没人用，
+ * 且无法按需求变化调整词。正确做法是把词准备好，查询仍由调用方发。
+ *
+ * 词从两个环境事实推：活跃 todo 的关键词 + 最近改过的文件名。
+ *
+ * 挑词用【主题级强度】排序，不取词表前几个（2026-09-17 实测修正）：
+ *   原实现 `pick = [...en.slice(0,2), ...zh.slice(0,1)]` 取的是最前面的词，
+ *   而 todo 行以 `<任务id> [[作者]]` 开头 → 任务 id 与用户名稳占前两位，
+ *   实测输出 `abs query queryhint-noise tester 进行`（强度 0/1/0，全是废词）。
+ *   现按 topicStrength（tag/页名命中数）降序取，强度 0 的一律不提示
+ *   —— 命中不了任何页的词，建议去查它等于没建议。
+ * 失败静默：读页出错就当没有强词，退回不提示（不影响 load）。
+ *
+ * @param {string} root 项目根
+ * @param {string} 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);
+  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);
+  // 英文词优先（中文 2-gram 单看无意义，只做补充）；每组内按强度降序
+  const byStrength = (a, b) => (strength.get(b) || 0) - (strength.get(a) || 0) || a.localeCompare(b);
+  const en = kws.filter((k) => /^[a-z][a-z0-9_-]+$/.test(k)).sort(byStrength).filter((k) => strength.get(k) > 0);
+  const zh = kws.filter((k) => !/^[a-z][a-z0-9_-]+$/.test(k)).sort(byStrength).filter((k) => strength.get(k) > 0);
+  const pick = [...en.slice(0, 2), ...zh.slice(0, 1)].slice(0, 3);
+  if (!pick.length) return '';
+  const rows = [
+    '--- 开工前建议查一次（图谱里有相关经验，别重踩）---',
+    `  abs query ${pick.join(' ')}`,
+  ];
+  if (files.length) rows.push(`  （据最近改动: ${files.slice(0, 3).map((f) => f.name).join(', ')}）`);
+  return rows.join('\n');
+}
+
+/** 数 sources/ 下的 .md 文件数（只读目录，不解析内容）—— load 顶部提醒用。
+ *  坑: root 是【项目根】，图谱在 root/.brain/ 下 —— 必须走 brainPath，
+ *  直接用 join(root,'sources') 会 ENOENT 被 catch 吞成 0，成为又一个静默失效。 */
+async function countSources(root) {
+  try {
+    const files = await fs.readdir(brainPath(root, 'sources'));
+    return files.filter((f) => f.endsWith('.md') && !f.startsWith('_')).length;
+  } catch { return 0; }
+}
+
+/** queryHint 的 load 端封装：返回提示文本（含标题行），无强词则空串。失败静默。 */
+async function queryHintSection(root, todo) {
+  return queryHint(root, todo);
+}
+
+/** sources 堆积提醒：返回 [标题行, ...内容行] 或 null。失败静默。 */
+async function sourcesCountSection(root) {
+  const nsrc = await countSources(root);
+  if (nsrc <= SOURCES_MAX) return null;
+  return [
+    `♻ 待消化: sources/ 有 ${nsrc} 条 > ${SOURCES_MAX}（采集了没提炼）`,
+    '→ abs lint 看明细；提炼成 concepts/ 后删 source 并清引用',
+    '',
+  ];
+}
+
+// ---------- show: 查看 index/todo/log（只读面） ----------
+export async function cmdShow({ dir, view, full }) {
+  const v = String(view || '').toLowerCase();
+  if (!['todo', 'index', 'log'].includes(v)) {
+    return '用法: abs <todo|index|log>  — todo=看板(原 board), index=Graph Index, log=操作流水';
+  }
+  const root = await requireBrain(dir || process.cwd());
+  const p = brainPath(root, `${v === 'todo' ? 'todo' : v}.md`);
+  // todo 走 readTodo（含老格式惰性迁移写回）；index/log 直接读
+  let text;
+  try {
+    text = v === 'todo'
+      ? await readTodo(root)          // 迁移老格式 In Progress/Todo → B4
+      : (await fs.readFile(p, 'utf8')).trim();
+  } catch {
+    return `${v}.md 不存在于 ${brainPath(root)}。初始化/补齐: abs init --repair`;
+  }
+  if (!text) return `(${v}.md 为空)`;
+  return v === 'todo' ? boardText(root, text, { full: !!full }) : text;
+}