@fanchao8609/agent_brain_sync 1.7.8 → 1.8.0

package/src/store.js

@@ -4,7 +4,7 @@ import { promises as fs } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { requireBrain, brainPath, absLogDir, BRAIN_DIR } from './index.js';
 import { requireUser, atTag, getUser } from './userconfig.js';
-import { addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, moveBlocked, insertDoneGrouped, idOfTaskLine, archiveDoneInText, renderArchivePage, renderArchiveBody, DONE_KINDS, withDoneKind, doneKindOf, doneDateOf, collapseDone, SEC, rebuildStructure, topicTreeText, upsertTopicLine, TOPIC_STATES, TOPIC_CLOSED_STATES, parseTopicLine, topicTree, currentTopic, removeTopicLine, promoteTopic } from './todo.js';
+import { stripStateMark, ensureStateMark, normalizeTodo, addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, setStateMark, TASK_STATES, insertDoneGrouped, idOfTaskLine, archiveDoneInText, renderArchivePage, renderArchiveBody, DONE_KINDS, withDoneKind, doneKindOf, doneDateOf, collapseDone, SEC, rebuildStructure } from './todo.js';
 import { editFile, SKIP } from './lock.js';
 import { appendWrapup, strandedFor } from './wrapup.js';
 
@@ -133,10 +133,7 @@ export function logTemplate() {
 export const BRAIN_SHAPE = {
   'todo.md': {
     h1: '# 📋 Todo Board',
-    // 分区（话题树）置顶：讨论轨道先于执行轨道（见 TODO_SECTIONS 注释）
-    order: ['## Topics', '## Backlog', '## Today / In Progress', '## Blocked', '## Done'],
-    // 旧文件标题归一（已在 todo.js 的 LEGACY_SECTION_RENAMES 里给出，这里引用以免双源漂移）
-    renames: [['## Topic', '## Topics'], ['## 话题', '## Topics'], ['## 话题树', '## Topics'], ['## 分区', '## Topics']],
+    order: ['## Todo', '## Done'],
   },
   'log.md': {
     h1: '# 🗒 Activity Log',
@@ -156,6 +153,13 @@ export const LEGACY_MARKS = [
   ['# 操作日志', '# 🗒 Activity Log'],
   ['# 图谱索引', '# 🗂 Graph Index'],
   ['# Todo 看板', '# 📋 Todo Board'],
+  // 四区 → 两区（2026-09-13 用户定）。**这条路径是 load 走的**（rebuildStructure），
+  // 与 todo.js 的 LEGACY_SECTION_RENAMES（normalizeTodo 用）是两条独立迁移路径 ——
+  // 只改一处会导致另一条认不出旧区名，把它们当"非标准分区"原样留末尾（未完成任务
+  // 留在文件里但不再被当 TODO）。测试 'load 也要能迁移' 钉住这一点。
+  ['## Backlog', '## Todo'],
+  ['## Today / In Progress', '## Todo'],
+  ['## Blocked', '## Todo'],
   ['## Done（只留近期，旧的迁 log.md/快照）', '## Done'],
   ['### 归档', '### Archived'],
   ['### （未标日期）', '### Undated'],
@@ -207,9 +211,24 @@ export async function checkBrainShape(root) {
     let changed = [];
     await editFile(p, (cur) => {
       if (cur === null) return SKIP;
-      const r = spec.order.length
-        ? rebuildStructure(cur, { ...spec, renames: LEGACY_MARKS.filter(([o]) => o.startsWith('## ') || o.startsWith('### ')) })
-        : fixMarks(cur, spec);
+      let next2 = cur;
+      if (spec.order.length) {
+        // todo.md 的四区 → 两区迁移**必须先走 normalizeTodo**：只有它知道
+        // `## Blocked` 区的任务该标 [滞留中]（语义信息），而 rebuildStructure 只按
+        // renames 改标题、看不到来源分区，只能一律给 [进行中]。
+        // 2026-09-13 实测坑：cmdLoad 先跑 checkBrainShape、后跑 readTodo，于是
+        // normalizeTodo 的 [滞留中] 映射在 load 路径上永远走不到 → 卡住的任务
+        // 被静默标成进行中，两条路径语义不一致。
+        const srcText = file === 'todo.md' ? normalizeTodo(cur) : cur;
+        const r0 = rebuildStructure(srcText, { ...spec, renames: LEGACY_MARKS.filter(([o]) => o.startsWith('## ') || o.startsWith('### ')) });
+        // 兜底：仍无状态标记的未完成任务补默认值（新格式文件本就有标记，此处不触发）。
+        next2 = file === 'todo.md'
+          ? r0.text.split('\n').map((l) => (l.startsWith('- [ ] ') ? ensureStateMark(l, '进行中') : l)).join('\n')
+          : r0.text;
+      } else {
+        next2 = fixMarks(cur, spec).text;
+      }
+      const r = { text: next2, changed: next2 === cur ? [] : ['结构按标准重排'] };
       if (!r.changed.length) return SKIP;
       changed = r.changed;
       return { text: r.text };
@@ -252,29 +271,6 @@ async function listBrainFiles(root) {
 }
 
 // ---------- load: 开机读状态 ----------
-/// 从看板文本里剔掉 `## Topics` 区段（已由「当前话题」单独渲染）。
-/// 只删区标题到下一个 `## ` 之间；末尾多余空行一并收掉。
-export function stripTopics(text) {
-  const lines = String(text ?? '').split('\n');
-  const at = lines.findIndex((l) => l.trim() === `## ${SEC.topics}`);
-  if (at === -1) return text;
-  let end = at + 1;
-  while (end < lines.length && !/^## /.test(lines[end])) end++;
-  lines.splice(at, end - at);
-  return lines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
-}
-
-/** 「当前话题」一行文本 —— load 首屏用。只给最深的活话题 + 它的父链，
- * 让人（和 AI）一眼看到“此刻在哪条线上”，而不摄入整棵树。 */
-export function currentTopicText(text) {
-  const cur = currentTopic(text);
-  if (!cur) return '';
-  const byId = new Map(topicTree(text).map((n) => [n.id, n]));
-  const chain = [];
-  for (let n = cur; n; n = n.parent ? byId.get(n.parent) : null) chain.unshift(n);
-  return `⌖ ${chain.map((n) => `${n.id} ${n.title}`).join(' › ')}`;
-}
-
 export async function cmdLoad({ dir }) {
   const root = await requireBrain(dir || process.cwd());
   // 结构核对先跑：load 每回都要读这三个文件，顺手把它们形状摆正（缺分区）或提个醒（无头）。
@@ -310,15 +306,9 @@ export async function cmdLoad({ dir }) {
     ...(rulesSection(index) ? [rulesSection(index), ''] : []),
     collapseIndex(index) || '(index.md 为空)',
     '',
-    // 只打「当前话题」一行：整棵树会被 load 反复读并带偏会话（同 Roadmap 之病）。
-    // 全貌用 `abs topic` 主动查——它是查看命令，不进开机首屏。
-    ...(currentTopic(todo) ? ['--- 当前话题 (todo.md) ---', currentTopicText(todo), ''] : []),
-    // 开局三类（2026-09-13 用户澄清）：①正在讨论=上面 Topics ②待办/已开工/已收尾=
-    // 下面 Board（Done 区就是已结束，折叠只是显示形式——归档才管前几天）。
-    // 曾加过「今日已结束」单列段：多余，撤掉（Done 区已表达同一信息）。
+    // 两区制：Todo（未完成，行首带状态标记）+ Done。
     '--- Todo Board (todo.md) ---',
-    // 看板里剔掉 Topics 区：它已在上面用树形打印过，原样再贴一遍是纯冗余。
-    stripTopics(collapseDone(todo).text) || '(todo.md 为空)',
+    collapseDone(todo).text || '(todo.md 为空)',
     '\n（Done 已按日期折叠计数；明细: abs todo --full）',
     '',
     '--- 最近动作 (log.md, 最新 5 条) ---',
@@ -393,9 +383,16 @@ export async function cmdRule({ dir, action, text }) {
   }
   const clean = String(text || '').replace(/\s+/g, ' ').trim();
   if (!clean) return '用法: abs rule add "一句话硬规则"';
-  // 门槛：一句话说完。太长说明该写概念页，Rules 只放指针。
-  if (clean.length > 120) {
-    return `✗ 太长（${clean.length} 字符 > 120）—— Rules 只放一句话摘要，展开写成概念页，\n  这里改成短句 + [[页面名]] 链接。`;
+  // 门槛：**纪律不是记事本**。Rules 是最前面的项目铁律，每条必须一眼扫完。
+  // 2026-09-13 用户定：不带链接、不带解释、不写细节 —— 细节进概念页，Rules 只留结论。
+  // 宽严：中文一字信息量大，按 40 字算（≈ 英文 80 字符的量）。实测现有 12 条最长 56 字符。
+  if (clean.length > 42) {
+    return `✗ 太长（${clean.length} > 42）—— Rules 是纪律不是记事本：\n`
+      + `  每条要一眼扫完。细节/出处/例子 → 写进 concepts/ 概念页，这里只留一句话结论。`;
+  }
+  if (/\[\[|\]\]|https?:\/\//.test(clean)) {
+    return '✗ 不带链接 —— Rules 区会被反复全量打印，链接占位且让纪律读起来像索引。\n'
+      + '  要挂概念页，去概念页自己的「## 关联连接」里挂。';
   }
   let added = null;
   await editFile(p, (cur) => {
@@ -433,11 +430,164 @@ async function readFileOrNull(p) {
  * 最大的单体膨胀源（Done 已折叠，见 collapseDone）。
  *
  * 续接真正需要的只是「有哪些分区、各多少页」（据此知道去哪找），不需要每页写了什么 ——
- * 要那个用 `abs index`（或直接读 index.md / 按词 `abs query`）。
+ * 要那个用 `abs index`（完整原文件）或按词 `abs query`。
  *
  * `## Rules` 也已不在本函数输出——它由 rulesSection 在**上方**单独成段（需要正文）；
  * 这里再原样吐一遍 = 同一段硬规则在首屏出现两次（2026-09-13 实测发现）。
  * 曾另有 `## Roadmap`：AI 自己写的方向总结，会被反复读到并带偏会话，已删。 */
+// ---------- page id: 改名不改引用 ----------
+// 问题：`.brain` 内部引用靠 [[slug]]，而 slug 就是文件名 —— 改一次文件名，
+// 所有指向它的链接静默变成 DEAD-LINK，只能靠 lint 事后抓。
+// 解法（最小代价）：页面 frontmatter 写一行 `id:`，建页时冻结。
+//   • 不发明新编号：id 默认等于建页时的 slug（人可读、可手写、无需迁移）
+//   • 旧页无 id → 回退用 slug，因此存量 31 页零迁移
+//   • 改名后 slug 变而 id 不变 → lint 报 ID-DRIFT，提示改成谁
+// 为什么不上内容哈希/uuid：哈希一改内容就变（比文件名还不稳定），
+// uuid 不可读不可手写且要全量迁移。slug 就是最合适的 id，只要不再跟文件名跑。
+const ID_RE = /^id:\s*(.+)$/m;
+
+/** 读页面 id；无 id 行则回退 slug（存量页零迁移）。 */
+export function idOfPage(body, slug) {
+  const m = String(body || '').match(ID_RE);
+  return m ? m[1].trim() : slug;
+}
+
+/** 给存量页补 id（只在缺时写），落 frontmatter。返回 'added' | 'exists' | 'no-fm'。 */
+export async function backfillPageId(full, slug) {
+  const res = await editFile(full, (cur) => {
+    if (!cur || !cur.startsWith('---\n')) return SKIP;
+    if (ID_RE.test(cur.split('\n---')[0])) return SKIP; // 已有 id 不动
+    const end = cur.indexOf('\n---', 3);
+    if (end === -1) return SKIP;
+    return { text: `${cur.slice(0, end)}\nid: ${slug}${cur.slice(end)}` };
+  });
+  return res === SKIP ? 'exists' : 'added';
+}
+
+// ---------- page status: 经验/知识页的生命周期 ----------
+// 问题：经验写进去就永远躺在那里 —— 推翻时删不掉（skill 里写着"人工内容一律不覆盖"，
+// AI 不敢删）、读的时候又看不见（load 只给分区计数）→ 旧经验持续骗下一个会话。
+// 解法：给已有的 `status:` 字段（字段本来就存在，20 页在用）定死三个值：
+//   active      当前有效（缺字段的默认值 —— 存量 22 页零迁移）
+//   superseded  已被推翻，别再依据它 —— 配 superseded-by 指向取代它的页
+//   draft       待核实（abs note 新落的经验就是这个）
+// 关键：推翻 = 改一行 frontmatter，**不删文件不丢历史** —— AI 敢做，人也能反悔。
+// 为什么不用新字段/新目录：字段已存在且有存量值，重命名会另起一套双轨（同 OPTS-DOUBLE-KEYS 之病）。
+export const PAGE_STATUS = ['active', 'superseded', 'draft'];
+const STATUS_RE = /^status:\s*(\S+)\s*$/m;
+const SUPERSEDED_BY_RE = /^superseded-by:\s*(.+)$/m;
+
+/** 读页面 status；无字段或是未知值时当 active（存量页零迁移）。 */
+export function statusOfPage(body, frontmatter) {
+  const fm = frontmatter !== undefined
+    ? frontmatter
+    : (String(body || '').match(/^---\n([\s\S]*?)\n---/) || ['', ''])[1];
+  const m = String(fm).match(STATUS_RE);
+  const v = m ? m[1].trim() : '';
+  return PAGE_STATUS.includes(v) ? v : 'active';
+}
+
+/** 读 superseded-by（只在 status=superseded 时有意义）。无则空串。 */
+export function supersededByOf(body) {
+  const m = String(body || '').match(SUPERSEDED_BY_RE);
+  return m ? m[1].trim() : '';
+}
+
+// ---------- supersede: 标记一条经验被推翻（回退的写入端） ----------
+// 为什么是标记而不是删除：
+//   ① 删除后下一个会话会重新踩同一个坑并重新记一遍（历史本身是资产）
+//   ② AI 不敢删（人工内容不覆盖），但敢改一行 frontmatter
+//   ③ 反悔只需把 status 改回 active
+export async function cmdSupersede({ dir, refs, by }) {
+  const list = (refs || []).map((r) => String(r).trim()).filter(Boolean);
+  if (!list.length) return '用法: abs supersede <页名或id> [更多…] [--by <取代它的页>]  — 标记经验已失效（不删文件）';
+  let root;
+  try {
+    root = await requireBrain(dir || process.cwd());
+  } catch {
+    return `未找到 .brain/ 图谱。先在项目根运行: abs init`;
+  }
+  const byRef = String(by || '').trim();
+  // 取代者必须先存在 —— 否则写下一个永远悬空的引用（lint 会报，不如现在拒）。
+  if (byRef) {
+    const target = await resolvePage(root, byRef);
+    if (!target) return `✗ --by ${byRef}: 图谱里没有这页（先用 abs resolve 确认页名）`;
+  }
+  const out = [];
+  // 取代者 slug 在循环外解析一次（锁内 mutator 不能 await）
+  const bySlug = byRef ? (await resolvePage(root, byRef)).slug : '';
+  for (const r of list) {
+    const hit = await resolvePage(root, r);
+    if (!hit) { out.push(`✗ ${r}: 未找到（试 abs query <词> 或 abs index 看清单）`); continue; }
+    const res = await editFile(hit.full, (cur) => {
+      if (!cur || !cur.startsWith('---\n')) return SKIP;
+      const end = cur.indexOf('\n---', 3);
+      if (end === -1) return SKIP;
+      let fm = cur.slice(0, end);
+      // 幂等：已是 superseded 且 superseded-by 一致 → 不写盘
+      const curSt = statusOfPage('', fm);
+      const curBy = supersededByOf(cur);
+      if (curSt === 'superseded' && curBy === bySlug) return SKIP;
+      // 去掉旧的 superseded-by（不论换不换取代者，旧值都作废）
+      fm = fm.replace(/\nsuperseded-by:.*(?=\n|$)/g, '');
+      fm = STATUS_RE.test(fm)
+        ? fm.replace(STATUS_RE, 'status: superseded')
+        : `${fm}\nstatus: superseded`;
+      // superseded-by 用 slug（不是 id）：人直接能按名找页，lint 能直接比对文件名
+      if (bySlug) fm = `${fm}\nsuperseded-by: ${bySlug}`;
+      return { text: fm + cur.slice(end) };
+    });
+    out.push(res === SKIP
+      ? `= ${hit.slug}: 已是 superseded（无变化）`
+      : `✓ ${hit.slug} → superseded${byRef ? ` (被 [[${byRef}]] 取代)` : ''}`);
+  }
+  return out.join('\n');
+}
+
+/** 把 id（或 slug）解析为页面路径。命中返回 {slug, dir, full, id}，否则 null。 */
+export async function resolvePage(root, idOrSlug) {
+  const want = String(idOrSlug || '').trim();
+  if (!want) return null;
+  const vault = brainPath(root);
+  for (const d of PAGE_DIRS) {
+    const p = join(vault, d);
+    let files;
+    try { files = await fs.readdir(p); } catch { continue; }
+    for (const f of files) {
+      if (!f.endsWith('.md') || f.startsWith('_')) continue;
+      const slug = f.replace(/\.md$/, '');
+      const full = join(p, f);
+      // slug 直接命中就够快（绝大多数调用走这条），不命中才去读 frontmatter 比 id
+      if (slug === want) return { slug, dir: d, full, id: want };
+      const body = await fs.readFile(full, 'utf8').catch(() => '');
+      const id = idOfPage(body, slug);
+      if (id === want) return { slug, dir: d, full, id };
+    }
+  }
+  return null;
+}
+
+// ---------- resolve: id/slug → 页面路径（引用的反查端） ----------
+// 配合 frontmatter 的 id: 使用。页改名后 id 不变，靠本命令仍能找回来。
+export async function cmdResolve({ dir, refs }) {
+  const list = (refs || []).map((r) => String(r).trim()).filter(Boolean);
+  if (!list.length) return '用法: abs resolve <id-or-slug> [更多…]  — 按 id/页面名反查路径';
+  let root;
+  try {
+    root = await requireBrain(dir || process.cwd());
+  } catch {
+    return `未找到 .brain/ 图谱。先在项目根运行: abs init`;
+  }
+  const lines = [];
+  for (const r of list) {
+    const hit = await resolvePage(root, r);
+    lines.push(hit
+      ? `✓ ${r} → ${BRAIN_DIR}/${hit.dir}/${hit.slug}.md${hit.id !== hit.slug ? `  (id=${hit.id})` : ''}`
+      : `✗ ${r}: 未找到（试 abs index 看完整清单，或 abs query <词> 全文搜）`);
+  }
+  return lines.join('\n');
+}
+
 export function collapseIndex(text) {
   const s = String(text || '').trim();
   if (!s) return '';
@@ -605,7 +755,7 @@ export async function cmdTeardownCheck({ dir, payload }) {
       '0) 本机尚未设置使用者姓名 —— 先跑 abs config set user <你的名字>，否则下面 2/3/4 都会被拦下；',
     ]),
     '[abs 收尾提醒] 本会话改过文件但 .brain/ 今天还没有记录。请立即走收尾循环：',
-      '1) 跑 abs load 看 Today 还有哪些未完成；',
+      '1) 跑 abs load 看 Todo 还有哪些未完成；',
       '2) 实际做完漏登记的 abs todo done <id>，做到一半的 abs todo note <id> --note "断点"；',
       '3) 值得留的经验 abs note "..."（宁少勿滥，能从代码 grep 到的不记）；',
       '4) abs log "完成 X：..." 记一行工作成果，新页同步进 index。',
@@ -702,15 +852,29 @@ export async function cmdTask({ dir, action, id, section, note, as }) {
   const who = await requireUser();
   await ensurePersonPage(root, who); // 首次写操作即建人页（已存在不动）
   if (action === 'start') {
+    // 两区制：未完成一律进 Todo，行首带状态标记（默认 进行中）。
+    const st = section && TASK_STATES.includes(section) ? section : '进行中';
     const r = await upsertTask(root, {
-      section: section || 'Today / In Progress',
-      text: `${id} ${atTag(who)}${note ? ' — ' + note : ''} (认领 ${today()})`,
+      section: SEC.todo,
+      text: `[${st}] ${id} ${atTag(who)}${note ? ' — ' + note : ''} (认领 ${today()})`,
     });
-    return `✓ 任务${r.updated ? '更新(幂等)' : '登记'} → ${brainPath(root, 'todo.md')}\n  ${id} ${atTag(who)}${note ? ' — ' + note : ''}`;
+    return `✓ 任务${r.updated ? '更新(幂等)' : '登记'} → ${brainPath(root, 'todo.md')}\n  [${st}] ${id} ${atTag(who)}${note ? ' — ' + note : ''}`;
   }
-  if (action === 'blocked') {
-    const r = await moveBlocked(root, { id, reason: note });
-    return r.msg;
+  if (action === 'state') {
+    // 改状态标记（原地，不搬区）：进行中 / 讨论中 / 滞留中
+    if (!note) throw new Error(`✗ 用法: abs todo state <id> --note "${TASK_STATES.join('|')}"`);
+    if (!TASK_STATES.includes(note)) {
+      throw new Error(`✗ 状态只接受: ${TASK_STATES.join(' | ')}（收到 "${note}"）`);
+    }
+    const f = brainPath(root, 'todo.md');
+    let cc = [];
+    await editFile(f, (cur) => {
+      if (cur === null) return SKIP;
+      const r = setStateMark(cur, id, note);
+      cc = r.changed;
+      return r.changed.length ? { text: r.text } : SKIP;
+    });
+    return cc.length ? `✓ ${id} 状态 → [${note}]` : `(未找到含 "${id}" 的未完成任务行，或状态未变)`;
   }
   if (action === 'note') {
     if (!note) return '用法: abs todo note <id> --note "断点/进度"（实时落 ↳ 断点 行）';
@@ -741,7 +905,7 @@ async function markDone(file, id, kind = '落地') {
       if (!moved && idOfTaskLine(l) === wantId) {
         changed = true;
         const head = withDoneKind(
-          l.replace('- [ ]', '- [x]').replace(/\(认领[^)]*\)/, '') + ` (完成 ${today()})`,
+          stripStateMark(l).replace('- [ ]', '- [x]').replace(/\(认领[^)]*\)/, '') + ` (完成 ${today()})`,
           kind,
         );
         const bp = [];
@@ -783,7 +947,7 @@ export async function cmdShow({ dir, view, full }) {
 // ---------- query: 检索知识图谱（多词 OR，扫全 .md 页） ----------
 const KNOWN_SLUG_HINT = /模板残留|\[\[slug\]\]/;
 
-export async function cmdQuery({ dir, terms }) {
+export async function cmdQuery({ dir, terms, includeSuperseded }) {
   const words = (terms || []).map((w) => String(w).trim()).filter(Boolean);
   if (!words.length) {
     return '用法: abs query <词1> [词2 …]  — 多词 OR 检索 .brain/ 全部知识页';
@@ -813,20 +977,42 @@ export async function cmdQuery({ dir, terms }) {
         // 作者从本页 frontmatter 读（权威来源）。不在 index 行里重复 ——
         // index 行是覆盖式更新的，作者会从"创建者"漂成"最后改的人"。
         const au = body.match(/^author:\s*(.+)$/m);
+        const st = statusOfPage(body);
+        // 被推翻的经验默认不出现在检索结果里 —— 它的存在意义是"别再用它"，
+        // 而不是回答"我上次怎么解決 X"（那会拿到一个已知错误的答案）。
+        // 但它不是静默消失：计数里告知还有几条被隐藏（带 --all 能看）。
+        if (st === 'superseded' && !includeSuperseded) {
+          hits.push({ hidden: true, slug: f.replace(/\.md$/, '') });
+          continue;
+        }
         hits.push({
           full, slug: f.replace(/\.md$/, ''), matched,
           author: au ? au[1].trim() : '',
+          id: idOfPage(body, f.replace(/\.md$/, '')),
+          status: st,
+          supersededBy: supersededByOf(body),
           snippet: firstHitLine(body, words),
         });
       }
     }
   }
-  if (!hits.length) return `query [${words.join(', ')}]: 无命中。用 abs lint 看图谱健康；首次使用先 abs init。`;
-  const lines = hits.map((h) => {
+  const hidden = hits.filter((h) => h.hidden).length;
+  const shown = hits.filter((h) => !h.hidden);
+  if (!shown.length) {
+    const extra = hidden ? `（另外 ${hidden} 页已标记 superseded，用 abs query ${words.join(' ')} --all 查看）` : '';
+    return `query [${words.join(', ')}]: 无命中。${extra}用 abs lint 看图谱健康；首次使用先 abs init。`;
+  }
+  const lines = shown.map((h) => {
     const by = h.author ? `  @${h.author}` : '';
-    return `📄 ${h.slug}${by}  (命中: ${h.matched.join(', ')})\n    ${h.snippet}`;
+    // id 只在≠slug 时显示 —— 相同时再印一遗就是纯噪音（绝大多数页）。
+    // 目的：让 AI 拿到一个改名也不漂的引用句柄（abs resolve <id> 能反查回来）。
+    const id = h.id && h.id !== h.slug ? `  [id: ${h.id}]` : '';
+    // draft = 未经核实。不拦使用，但必须让 AI 知道这是它自己没验证过的。
+    const st = h.status === 'draft' ? '  [draft 未核实]' : '';
+    return `📄 ${h.slug}${by}${id}${st}  (命中: ${h.matched.join(', ')})\n    ${h.snippet}`;
   });
-  return [`query [${words.join(', ')}] → ${hits.length} 页:`, '', ...lines].join('\n');
+  const tail = hidden ? [``, `（${hidden} 页 superseded 已隐藏；--all 可看）`] : [];
+  return [`query [${words.join(', ')}] → ${shown.length} 页:`, '', ...lines, ...tail].join('\n');
 }
 
 function firstHitLine(body, words) {
@@ -872,6 +1058,7 @@ export async function cmdNote({ dir, text, tags }) {
   const body = [
     '---',
     `tags: [${fmTags}]`,
+    `id: ${file.replace(/\.md$/, '')}`,
     `author: ${who}`,
     `updated: ${today()}`,
     'status: draft',
@@ -913,6 +1100,7 @@ export async function ensurePersonPage(root, name) {
   const body = [
     '---',
     'tags: [entity, person]',
+    `id: ${nm}`,
     `author: ${nm}`,
     `updated: ${today()}`,
     'status: draft',
@@ -991,6 +1179,19 @@ export async function cmdLint({ dir }) {
 
   for (const pg of pages) {
     if (!pg.hasFrontmatter) issues.push(`NO-FRONTMATTER: ${pg.rel}`);
+    // ID-DRIFT: 页面写了 id 但已跟文件名(slug)不一致 = 改过名或改过 id。
+    // 不是错误（id 就是用来固定身份的），但必须提示：[[slug]] 形式的引用指向的是**文件名**，
+    // 改名后旧引用全变 DEAD-LINK；本检查让「静默断链」变成「一条可执行的提示」。
+    // 优先看「有没有别的页 id 指向旧名」→ 那才是真正的改名现场。
+    if (pg.hasFrontmatter) {
+      const id = idOfPage(pg.body, pg.slug);
+      // 反向查：有别的页声明 id = 本页 slug，说明本页是从那个 id 改名过来的。
+      // 这种才是「改名没同步引用」的真信号；单纯 id≠slug 也可能只是手写的 id。
+      if (id !== pg.slug) {
+        issues.push(`ID-DRIFT: ${pg.rel} (frontmatter id=${id} ≠ 文件名 ${pg.slug}；` +
+          `引用请用 [[${id}]] 或改回文件名)`);
+      }
+    }
     for (const ln of pg.links) {
       // 两类都不是真链接，只报 TEMPLATE-LINK（且不短路就会再报一次 DEAD-LINK，同一条报两遍）：
       //   ① 模板占位: `[[页面名]]` / `[[slug]]` / `[[Name]]` —— 模板没填
@@ -1053,18 +1254,44 @@ export async function cmdLint({ dir }) {
     }
   }
 
+  // SUPERSEDED-DANGLING: superseded 页声明的取代者也必须存在。
+  // 它跟 DEAD-LINK 同性质（指向不存在的页），但后果更重：
+  // 读者被引导去找一个不存在的"新版本"，比单纯断链更容易让人以为"没新页就是没替代"。
+  for (const pg of pages) {
+    if (pg.status !== 'superseded') continue;
+    if (!pg.supersededBy) continue; // 无取代者也是合法状态（就是弃用，没替代）
+    const by = pg.supersededBy.replace(/^\[\[|\]\]$/g, '').trim();
+    if (!names.has(by)) {
+      issues.push(`SUPERSEDED-DANGLING: ${pg.rel} (superseded-by: ${by} —— 该页不存在，删页后未同步)`);
+    }
+  }
+
+  // DRAFT-STALE: draft 停太久 = 既没核实也没被推翻，实质是写了没人看的堆积。
+  // 不报 sources（它们由 SOURCE-UNDISTILLED 管），只报 concepts/entities/syntheses ——
+  // 那些页是"应该已经被确认过"的长期资产，长期 draft 说明核实环节缺位。
+  for (const pg of pages) {
+    if (pg.status !== 'draft') continue;
+    if (pg.dir === 'sources') continue;
+    let ageMs = 0;
+    try { ageMs = Date.now() - (await fs.stat(join(root, pg.rel))).mtimeMs; } catch { continue; }
+    if (ageMs > DRAFT_STALE_DAYS * 86400 * 1000) {
+      const days = Math.floor(ageMs / 86400000);
+      issues.push(`DRAFT-STALE: ${pg.rel}（已 ${days} 天停在 draft；核实后改 status: active，推翻则 abs supersede）`);
+    }
+  }
+
   // Rules 区：它的价值在“少而重”，且不被折叠（load 每次都全量读）。
   // 无上限增长 = 把 load 又撑回去（同 Done / index 清单的膨胀根因）。
   {
     const idxTxt = await readFileOrNull(join(vault, 'index.md'));
     const { items, found } = readRules(idxTxt);
     if (found && items.length > RULES_MAX) {
-      issues.push(`RULES-PILED-UP: Rules 区 ${items.length} 条 > ${RULES_MAX}；把长条目提炼成概念页，这里只留一句 + 链接`);
+      issues.push(`RULES-PILED-UP: Rules 区 ${items.length} 条 > ${RULES_MAX}；把长条目提炼成概念页，这里只留一句话`);
     }
     // 该区是 load 必读的硬规则清单，条目却写得像段落 → 提醒改短句。
     const longOnes = items.filter((l) => l.trim().length > 160);
     if (longOnes.length) {
-      issues.push(`RULES-TOO-LONG: Rules 区 ${longOnes.length} 条超 160 字符（如 "${clip(longOnes[0].trim(), 40)}"）；展开写进概念页，这里只留短句 + [[链接]]`);
+      issues.push(`RULES-TOO-LONG: Rules 区 ${longOnes.length} 条超 160 字符（如 "${clip(longOnes[0].trim(), 40)}"）；展开写进概念页，这里只留一句话（不带链接）`);
     }
   }
 
@@ -1133,6 +1360,9 @@ const PAGE_MAX_BYTES = 8 * 1024;
 // source 页超龄未提炼的天数阈值（SOURCE-UNDISTILLED）。
 // 7 天 = 跨过至少一个完整工作周还没人提炼，基本等于被遗忘。
 const SOURCE_STALE_DAYS = 7;
+// draft 超龄阈值：新落的经验（abs note）默认 draft，指的是"还没核实过"。
+// 长期停在 draft = 既没被核实也没被推翻，属"写了没人看"的堆积 —— 不自动改，只报。
+const DRAFT_STALE_DAYS = 14;
 
 async function listPages(vault) {
   let indexText = '';
@@ -1167,79 +1397,10 @@ async function listPages(vault) {
         lines: body.split('\n').length,
         bytes: Buffer.byteLength(body, 'utf8'),
         indexed: indexText.includes(`[[${f.replace(/\.md$/, '')}]]`),
+        status: statusOfPage(body, fm ? fm[1] : ''),
+        supersededBy: supersededByOf(body),
       });
     }
   }
   return pages;
 }
-
-/** abs topic —— 分区（话题树）读写。
- * 两个关键修正（2026-09-13 实测踩坑）：
- *  ① `id` 参数可能是“"#1" 标题”合一串 —— 必须切开，否则整串被当作 id，
- *     upsert 找不到行 → 新插一行重复话题。
- *  ② 未给标题时必须**保留现有标题**（不能回退成 id）：
- *     `abs topic conclude "#1"` 曾把标题写成 `#1` 并丢掉结论。 */
-export async function cmdTopic({ dir, action, id, title, state, conclusion, full, clear }) {
-  const root = await requireBrain(dir || process.cwd());
-  const p = brainPath(root, 'todo.md');
-  if (!action || action === 'tree' || action === 'list') {
-    const text = await readTodo(root);
-    const t = topicTreeText(text);
-    return t || '（无话题。登记: abs topic new "#1 标题"）';
-  }
-  // 写操作：需姓名（与 todo 同守卫）；姓名同时写进话题行（[[name]]）
-  const who = await requireUser();
-  await ensureTodo(root);
-  // 拆 “#1 标题” → id / title（id 只取 # 开头的第一个 token）
-  let useId = id;
-  let useTitle = title;
-  if (useId && !/^#[\w.]+$/.test(useId)) {
-    const m = String(useId).match(/^(#[\w.]+)\s+(.*)$/);
-    if (m) { useId = m[1]; useTitle = (useTitle ? m[2] + ' ' + useTitle : m[2]).trim(); }
-  }
-  if (!useId) throw new Error(`✗ 缺 <id>\n  用法: abs topic ${action} "#1 标题" [--state 状态] [--note 结论]`);
-  if (!/^#[\w.]+$/.test(useId)) {
-    throw new Error(`✗ id 需以 # 开头（如 #1 / #2.1），收到 "${useId}"`);
-  }
-  const st = state || (action === 'reject' ? '已否决' : action === 'conclude' ? '已结论' : action === 'done' ? '已落地' : '进行中');
-  // `abs topic promote #N` —— 讨论成熟、要动手了 → 移进 Today（同 id 连续追踪）。
-  // 不是复制两份：话题变身任务，Topics 退位。
-  if (action === 'promote') {
-    if (!useId) throw new Error('✗ 缺 <id>\n  用法: abs topic promote "#1" [--to Today]');
-    const cur = await readTodo(root);
-    const section = state || SEC.today;   // --state 可指定目标分区（默认 Today）
-    const r = promoteTopic(cur, useId, section);
-    if (!r.changed.length) {
-      return `• 话题 ${useId} 未登记（或目标分区 ${section} 不存在），未动`;
-    }
-    await editFile(p, () => ({ text: r.text }));
-    return `✓ 话题 ${useId} 已移进 ${section}（同 id 连续追踪，不再是话题）`;
-  }
-  if (!TOPIC_STATES.includes(st)) {
-    throw new Error(`✗ --state 只接受: ${TOPIC_STATES.join(' | ')}（收到 "${st}"）`);
-  }
-  // 终止态不入 Topics 区（用户定：这里只放正在讨论的）。
-  // 不默默拒绝而是给明确出路：先把结论落 sources/，再从树上摘掉。
-  if (TOPIC_CLOSED_STATES.includes(st)) {
-    const cur = await readTodo(root);
-    const node = topicTree(cur).find((n) => n.id === useId);
-    if (node) {
-      await editFile(p, (c) => ({ text: removeTopicLine(c, useId) }));
-      return (
-        `✓ 话题 ${useId} [${st}] 已从 Topics 移出（终止态不留树上）\n` +
-        `  ⚠ 结论请用 \`abs note "..."\` 落 sources/，否则就丢了`
-      );
-    }
-    return `• 话题 ${useId} [${st}] 未登记（终止态不入 Topics 区）\n  ⚠ 结论请用 \`abs note "..."\` 落 sources/`;
-  }
-  const orig = await readTodo(root);
-  // 未给标题 → 沿用现有行（“只改状态”场景）
-  const existing = topicTree(orig).find((n) => n.id === useId);
-  const title2 = useTitle || existing?.title;
-  if (!title2) throw new Error(`✗ 话题 ${useId} 不存在，需给标题\n  用法: abs topic new "${useId} 标题"`);
-  const concl = conclusion !== undefined ? conclusion : existing?.conclusion;
-  const r = await editFile(p, (cur) => ({
-    text: upsertTopicLine(cur, { id: useId, title: title2, state: st, conclusion: concl, author: who }).text,
-  }));
-  return `✓ 话题 ${useId} [${st}] → ${p}\n  ${title2}${concl ? ' — ' + concl : ''}`;
-}