@fanchao8609/agent_brain_sync 1.7.9 → 1.8.1

package/README.md

@@ -69,7 +69,9 @@ abs todo done    TASK-1
 
 abs note "一句话经验" --tags 坑,docker    # 经验暂存 → sources/
 abs log "完成 X"                          # 记一行流水；abs log 无参 = 查看
-abs query <词>                            # 检索图谱（多词 OR）
+abs query <词>                            # 检索图谱（多词 OR）；已被推翻的经验默认隐藏（--all 可看）
+abs resolve <页名或id>                    # 反查页面路径（页改名后 id 不变）
+abs supersede <页名> [--by <新页>]        # 标记经验已失效（不删文件，保留历史；query 默认不再返回）
 abs status                                # 当前项目 + 图谱概要
 abs lint                                  # 体检：死链/孤岛/超尺寸/堆积
 abs rule                                  # 列出 index.md 的 ## Rules 硬规则

package/bin/abs.js

@@ -2,7 +2,7 @@
 // bin/abs.js — abs CLI 入口。
 // abs <cmd> [args]
 // 命令: init / board / status / load / task / install / uninstall / help
-import { cmdInit, cmdStatus, cmdLoad, cmdTask, cmdLog, cmdQuery, cmdLint, cmdNote, cmdShow, cmdRepair, cmdWrapup, cmdRule, cmdTeardownCheck, cmdTodoArchive } from '../src/store.js';
+import { cmdInit, cmdStatus, cmdLoad, cmdTask, cmdLog, cmdQuery, cmdLint, cmdNote, cmdShow, cmdRepair, cmdWrapup, cmdRule, cmdTeardownCheck, cmdTodoArchive, cmdResolve, cmdSupersede } from '../src/store.js';
 import { setUser, getUser, userConfigPath } from '../src/userconfig.js';
 import { runInstall, runUninstall } from '../src/install.js';
 import { readFileSync } from 'node:fs';
@@ -74,6 +74,8 @@ const FLAG_SPEC = {
   'payload': { type: 'string' },
   'tags': { type: 'string' },
   'state': { type: 'string' },
+  'by': { type: 'string' },
+  'all': { type: 'boolean' },
   'keep-days': { type: 'string' },
   'help': { type: 'boolean' },
   'dry-run': { type: 'boolean' },
@@ -144,6 +146,8 @@ function parseArgv(args) {
     note: values.note,
     as: values.as,
     state: values.state,
+    by: values.by,
+    all: !!values.all,
     payload: values.payload,
     tags: values.tags,
     help: !!values.help,
@@ -183,7 +187,12 @@ const usage = `abs — agent-brain-sync 记忆工具
   abs note "经验一句话" [--tags 坑,docker]    经验实时暂存 → sources/
 
 维护:
-  abs query <词1> [词2 …]    检索 .brain/ 知识页 (多词 OR)
+  abs query <词1> [词2 …] [--all]
+                            检索 .brain/ 知识页 (多词 OR)；superseded 默认隐藏
+  abs resolve <id-or-slug> [更多…]
+                            按 id/页面名反查路径 (页改名后 id 不变，仍能找回)
+  abs supersede <页名> [--by <取代它的页>]
+                            标记一条经验已失效 (不删文件；query/load 默认不再展示)
   abs todo archive [--keep-days N] [--dry-run]
                             归档 Done 区旧日期组 → sessions/<日期>-todo归档.md
                             (默认保留近 3 天; 任一天有未完成则整天不归档)
@@ -400,7 +409,15 @@ async function main() {
         break;
       }
       case 'query': {
-        console.log(await cmdQuery({ dir: opts.dir, terms: opts._ }));
+        console.log(await cmdQuery({ dir: opts.dir, terms: opts._, includeSuperseded: opts.all }));
+        break;
+      }
+      case 'supersede': {
+        console.log(await cmdSupersede({ dir: opts.dir, refs: opts._, by: opts.by }));
+        break;
+      }
+      case 'resolve': {
+        console.log(await cmdResolve({ dir: opts.dir, refs: opts._ }));
         break;
       }
       case 'lint': {

package/bin/mcp.js

@@ -12,7 +12,7 @@ import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { findBrainRoot, absLogDir } from '../src/index.js';
-import { cmdBoard, cmdLoad, cmdStatus, cmdTask, cmdQuery, cmdLint, cmdNote, cmdWrapup, cmdRule } from '../src/store.js';
+import { cmdBoard, cmdLoad, cmdStatus, cmdTask, cmdQuery, cmdLint, cmdNote, cmdWrapup, cmdRule, cmdResolve, cmdSupersede } from '../src/store.js';
 
 // ---------- 技术日志: MCP 请求跟踪（调试用, 与图谱 log.md 完全分开） ----------
 // 落 ~/.abs/log/mcp.log: 每次工具调用一行 [时间] tool cwd 参数摘要 → 耗时/结果摘要。
@@ -66,7 +66,12 @@ function tool(name, description, schema, handler) {
   server.tool(name, description, schema, withTrace(name, handler));
 }
 
-// 工具面（narrow on purpose — 只暴露读/查/记状态，不做深提炼）
+// 工具面（narrow on purpose — 只暴露读/查/记状态，不做深提炼）。
+// 分级标注（借 OpenContext 的 P0/P1/P2 惯例）：P0=每次开机必调；P1=干活中按需；P2=诊断/收尾。
+// 后来人（和 AI）照这个顺序调，别一上来就 lint。
+//   P0  abs_resolve_project / abs_load
+//   P1  abs_board / abs_task / abs_query / abs_note / abs_resolve
+//   P2  abs_status / abs_rule / abs_lint / abs_wrapup
 tool(
   'abs_resolve_project',
   '定位当前项目的 .brain 图谱根（只认给定目录本身的 .brain/，不向上搜索）。多项目隔离的唯一入口。',
@@ -74,7 +79,10 @@ tool(
   async ({ cwd }) => {
     const root = await findBrainRoot(cwd || process.cwd());
     if (!root) {
-      return { content: [{ type: 'text', text: `未找到 .brain/（${cwd} 下没有，不向上搜索）。先在该目录运行: abs init` }] };
+      return err(`目录 ${cwd} 下没有 .brain/ 图谱（不向上搜索）。`, {
+        code: 'NO_BRAIN',
+        fallback: '先在该目录运行: abs init',
+      });
     }
     return { content: [{ type: 'text', text: root }] };
   }
@@ -86,7 +94,7 @@ tool(
   { cwd: z.string().describe('项目根目录（.brain/ 所在处）') },
   async ({ cwd }) => {
     const root = await findBrainRoot(cwd || process.cwd());
-    if (!root) return err('未找到 .brain/，先 abs init');
+    if (!root) return errNoBrain(cwd || process.cwd());
     return { content: [{ type: 'text', text: await cmdBoard({ dir: root }) }] };
   }
 );
@@ -97,7 +105,7 @@ tool(
   { cwd: z.string().describe('项目根目录（.brain/ 所在处）') },
   async ({ cwd }) => {
     const root = await findBrainRoot(cwd || process.cwd());
-    if (!root) return err('未找到 .brain/，先 abs init');
+    if (!root) return errNoBrain(cwd || process.cwd());
     return { content: [{ type: 'text', text: await cmdLoad({ dir: root }) }] };
   }
 );
@@ -113,20 +121,59 @@ tool(
   },
   async ({ action, id, cwd, note }) => {
     const root = await findBrainRoot(cwd || process.cwd());
-    if (!root) return err('未找到 .brain/，先 abs init');
+    if (!root) return errNoBrain(cwd || process.cwd());
     // add 是 start 的别名（与 CLI `abs todo add` 对齐）
     const act = action === 'add' ? 'start' : action;
     return { content: [{ type: 'text', text: await cmdTask({ dir: root, action: act, id, note }) }] };
   }
 );
 
+tool(
+  'abs_resolve',
+  '按页面 id（或页面名 slug）反查文件路径。页改名后 id 不变，引用请用返回的路径/id。',
+  {
+    cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
+    refs: z.array(z.string()).min(1).describe('页面 id 或页面名，如 "file-write-locking"'),
+  },
+  async ({ cwd, refs }) => {
+    const root = await findBrainRoot(cwd || process.cwd());
+    if (!root) return errNoBrain(cwd || process.cwd());
+    const text = await cmdResolve({ dir: root, refs });
+    // 全部未命中才算错 —— 部分命中时整体标 isError 会让 Agent 以为调用失败，
+    // 把已经拿到的正确路径丢掉（实测：1 中 1 不中 → 整个结果被当错）。
+    if (/✗/.test(text) && !/✓/.test(text)) {
+      return err(text, { code: 'NOT_FOUND', fallback: 'abs query <词> 全文搜，或直接读 index.md' });
+    }
+    return { content: [{ type: 'text', text }] };
+  }
+);
+
+tool(
+  'abs_supersede',
+  '标记一条经验/知识页已失效（被推翻），不删文件、保留历史。之后 abs_query 默认不再返回它。核实后发现仍有效可手动把 status 改回 active。',
+  {
+    cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
+    refs: z.array(z.string()).min(1).describe('页名或 id，如 "old-approach"'),
+    by: z.string().optional().describe('取代它的页名（可选；给了则必须已存在）'),
+  },
+  async ({ cwd, refs, by }) => {
+    const root = await findBrainRoot(cwd || process.cwd());
+    if (!root) return errNoBrain(cwd || process.cwd());
+    const text = await cmdSupersede({ dir: root, refs, by });
+    if (/✗/.test(text) && !/✓/.test(text)) {
+      return err(text, { code: 'NOT_FOUND', fallback: '用 abs_query <词> 找到正确的页名后重试' });
+    }
+    return { content: [{ type: 'text', text }] };
+  }
+);
+
 tool(
   'abs_status',
   '当前项目 + 图谱概要（各类页数）。',
   { cwd: z.string().describe('项目根目录（.brain/ 所在处）') },
   async ({ cwd }) => {
     const root = await findBrainRoot(cwd || process.cwd());
-    if (!root) return err('未找到 .brain/，先 abs init');
+    if (!root) return errNoBrain(cwd || process.cwd());
     return { content: [{ type: 'text', text: await cmdStatus({ dir: root }) }] };
   }
 );
@@ -134,11 +181,20 @@ tool(
 tool(
   'abs_query',
   '检索当前项目 .brain/ 知识页（多词 OR）：以前踩过什么坑、哪页记了 X。',
-  { cwd: z.string().describe('项目根目录（.brain/ 所在处）'), terms: z.array(z.string()).min(1).describe('检索词') },
-  async ({ cwd, terms }) => {
+  { cwd: z.string().describe('项目根目录（.brain/ 所在处）'), terms: z.array(z.string()).min(1).describe('检索词'), include_superseded: z.boolean().optional().describe('true=连已标记失效的经验一起返回（默认隐藏）') },
+  async ({ cwd, terms, include_superseded }) => {
     const root = await findBrainRoot(cwd || process.cwd());
-    if (!root) return err('未找到 .brain/，先 abs init');
-    return { content: [{ type: 'text', text: await cmdQuery({ dir: root, terms }) }] };
+    if (!root) return errNoBrain(cwd || process.cwd());
+    const text = await cmdQuery({ dir: root, terms, includeSuperseded: include_superseded });
+    // 无命中时给逃生口：query 是全文匹配，猜的词不对就换词/看全貌，别以为图谱是空的。
+    // 收口在这里（不散在 store.js）—— CLI 侧是一行提示，MCP 侧需要可自救的结构。
+    if (/无命中/.test(text)) {
+      return err(text, {
+        code: 'NO_MATCH',
+        fallback: '换更具体的词重试（支持多个词 OR）；或读 .brain/index.md 看完整清单',
+      });
+    }
+    return { content: [{ type: 'text', text }] };
   }
 );
 
@@ -152,7 +208,7 @@ tool(
   },
   async ({ cwd, action, text }) => {
     const root = await findBrainRoot(cwd || process.cwd());
-    if (!root) return err('未找到 .brain/，先 abs init');
+    if (!root) return errNoBrain(cwd || process.cwd());
     return { content: [{ type: 'text', text: await cmdRule({ dir: root, action: action || 'list', text }) }] };
   }
 );
@@ -163,8 +219,14 @@ tool(
   { cwd: z.string().describe('项目根目录（.brain/ 所在处）') },
   async ({ cwd }) => {
     const root = await findBrainRoot(cwd || process.cwd());
-    if (!root) return err('未找到 .brain/，先 abs init');
-    return { content: [{ type: 'text', text: await cmdLint({ dir: root }) }] };
+    if (!root) return errNoBrain(cwd || process.cwd());
+    const text = await cmdLint({ dir: root });
+    // lint 报的是「哪不对」，得补一句「下一步怎么办」，否则 Agent 只能把问题复述给用户。
+    const fallback = /无问题|0 个问题|健康/.test(text)
+      ? null
+      : '按条目里的文件名/H1 直接改；死链可删或改指向；index 漏列用 abs_rule 同区手工补一行';
+    if (!fallback) return { content: [{ type: 'text', text }] };
+    return err(text, { code: 'LINT_ISSUES', fallback });
   }
 );
 
@@ -178,7 +240,7 @@ tool(
   },
   async ({ cwd, text, tags }) => {
     const root = await findBrainRoot(cwd || process.cwd());
-    if (!root) return err('未找到 .brain/，先 abs init');
+    if (!root) return errNoBrain(cwd || process.cwd());
     return { content: [{ type: 'text', text: await cmdNote({ dir: root, text, tags }) }] };
   }
 );
@@ -189,13 +251,31 @@ tool(
   { cwd: z.string().describe('项目根目录（.brain/ 所在处）') },
   async ({ cwd }) => {
     const root = await findBrainRoot(cwd || process.cwd());
-    if (!root) return err('未找到 .brain/，先 abs init');
+    if (!root) return errNoBrain(cwd || process.cwd());
     return { content: [{ type: 'text', text: await cmdWrapup({ dir: root }) }] };
   }
 );
 
-function err(msg) {
-  return { content: [{ type: 'text', text: msg }], isError: true };
+// 错误带逃生口：Agent 收到错要能自救，而不是回来问人。
+// 借 OpenContext 的做法——错误里直接给「退一步怎么做」，且带结构化 code 供程序判分支。
+// 判据：凡 isError 的返回，调用方读完应知道下一步跑什么命令。
+function err(msg, { code, fallback } = {}) {
+  const body = [
+    code ? `[${code}] ${msg}` : msg,
+    fallback ? `→ ${fallback}` : null,
+  ].filter(Boolean).join('\n');
+  const res = { content: [{ type: 'text', text: body }], isError: true };
+  // 结构化字段：MCP 客户端可读 structuredContent 判分支（code=NO_BRAIN 等）
+  if (code) res.structuredContent = { error: code, message: msg, fallback: fallback || null };
+  return res;
+}
+
+/** 无图谱专用：所有工具共用同一条自救路径，收口在这里（改一处即全改）。 */
+function errNoBrain(cwd) {
+  return err(`目录 ${cwd} 下没有 .brain/ 图谱（不向上搜索）。`, {
+    code: 'NO_BRAIN',
+    fallback: `先在该目录运行: abs init  （或在含图谱的目录重调本工具）`,
+  });
 }
 
 await server.connect(new StdioServerTransport());

package/hooks/abs.opencode.ts

@@ -4,17 +4,24 @@
  * 纪律: hook 事件只进技术日志, 不进图谱 log.md (log.md 只收工作成果沉淀, 与 event.sh 同纪律)。
  * Op​encode 事件: session.created / session.idle / session.deleted (idle = 每轮结束, 对应 pi 的 agent_end)。
  * 收尾注入: session.idle 且本会话真改过文件 + .brain 今日无记录 → promptAsync 推 agent 走收尾循环。
+ *
+ * 登记注入 (2026-09-15 用户定): 写文件 = 任务开始的机械信号。
+ *   旧设计只在 idle(轮末) 提醒收尾 —— 那时用户已想结束, AI 只想收尾不想登记。
+ *   故 tool.execute.after 检测到**项目文件**写入即注入登记提示(不等 idle):
+ *     · 频繁没关系 —— 每次写都提醒(用户明确要求)
+ *     · 判据 = 整个项目, 但**排除 .brain/ 自身**(写图谱是记录行为, 不是任务)
+ *     · 文案明说「纯讨论可跳过」—— 不逼 AI 造任务
  */
 import { appendFile, mkdir, readFile, stat } from "node:fs/promises"
 import { homedir } from "node:os"
 import { join, dirname } from "node:path"
-
 const server = async ({ client, directory }) => {
   // 本会话是否真改过文件 (由 tool.execute.after 观测)
   let wroteFiles = false
   let nudged = false
   let idleSeen = false
-
+  // 当前 session id（由事件里拿）—— 收尾注入需要它找到会话。
+  let currentSessionID = ""
   async function logHook(evt) {
     try {
       const dir = process.env.ABS_LOG_DIR || join(homedir(), ".abs", "log")
@@ -45,6 +52,7 @@ const server = async ({ client, directory }) => {
     } catch { return false }
   }
 
+
   const TEARDOWN_MSG =
     "[abs 收尾提醒] 本会话改过文件但 .brain/ 今天还没有记录。请立即走收尾循环：\n" +
     "1) 跑 abs load 看 Todo 还有哪些未完成；\n" +
@@ -56,19 +64,23 @@ const server = async ({ client, directory }) => {
   // bash 里只跑查询类命令不算改文件 (与 pi 侧 READONLY_CMD 同义, 但生成代码里要写进模板串)
   const READONLY_CMD = /^\s*(ls|cat|grep|rg|find|head|tail|wc|git\s+(status|log|diff|show|branch)|pwd|which|echo|node\s+-v|npm\s+(ls|view)|curl)\b/
 
+
+
+
   return {
     // 观测真实写操作: write/edit/patch 类工具成功即标记。
     // 坑: 曾漏掉 bash —— op​encode 里很多修改是经 bash(heredoc/sed) 完成的, 纯 bash 会话
     //     永远不置位 wroteFiles, 于是收尾提醒静默不发。与 pi 侧 WRITE_TOOLS 保持一致。
     "tool.execute.after": async ({ tool, args }) => {
       const t = String(tool || "").toLowerCase()
+      const a = args || {}
       if (["write", "edit", "patch", "multiedit", "apply_patch"].includes(t)) {
         wroteFiles = true
         return
       }
       // bash 里只有非只读命令算改文件(ls/cat/git status 之类不算)
       if (t === "bash") {
-        const cmd = String((args && (args.command || args.cmd)) || "")
+        const cmd = String(a.command || a.cmd || "")
         if (cmd && !READONLY_CMD.test(cmd)) wroteFiles = true
       }
     },
@@ -78,9 +90,14 @@ const server = async ({ client, directory }) => {
       if (!type) return
       if (type === "session.created" || type === "session.deleted") {
         await logHook(type)
+        // session.created / idle 等事件带 sessionID —— 存下来供 tool.execute.after 用
+        const sid = event.properties && event.properties.sessionID
+        if (sid) currentSessionID = String(sid)
         return
       }
       if (type !== "session.idle") return // idle = 每轮结束, 不记日志(太吵), 只做收尾判定
+      const sid0 = event.properties && event.properties.sessionID
+      if (sid0) currentSessionID = String(sid0)
       const cwd = directory || process.cwd()
       const brain = await findBrain(cwd)
       // 可观测性: 首次 idle 无条件留一行痕(否则无法区分“事件没触发”与“被守卫拦下”)

package/hooks/abs.pi.ts

@@ -12,6 +12,11 @@
  *     - before_agent_start (用户发话 = 天然话题边界) → 记用户原话
  *     - turn_end (每轮结束) → 记改过哪些文件
  *   累积在**内存**(下方 sessionNotes), 收尾时拼进注入提示 —— **不落盘**。
+ *
+ * 已删除（2026-09-15）：曾加过一个「写文件即任务开始 → 每轮注入登记提醒」的功能。
+ *   已发布到 1.8.0 后用户实报「pi 里一直报 Follow-up」，判 C 整个删掉。
+ *   教训：每次改文件就往对话里插一句话，本身就是设计错误，不是频率问题 ——
+ *   改守卫（从每轮一次改成每会话一次）治不了它。别再加回来。
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
 import { appendFile, mkdir, readFile, stat } from "node:fs/promises"
@@ -109,6 +114,7 @@ async function loggedToday(brain: string): Promise<boolean> {
   } catch { return false }
 }
 
+
 export default function absPiHook(pi: ExtensionAPI): void {
   // 收尾注入的节流状态。声明在**外层** + 在 session_start 里重置：
   // 否则同一进程的第二个会话会继承上一个会话的 true，永久不再提醒
@@ -116,7 +122,7 @@ export default function absPiHook(pi: ExtensionAPI): void {
   let teardownNudged = false
   let agentEndSeen = false
 
-  pi.on("session_start", () => {
+  pi.on("session_start", (event: any, _ctx: any) => {
     teardownNudged = false
     agentEndSeen = false
     return logHook("session_start").catch(() => {})
@@ -144,6 +150,7 @@ export default function absPiHook(pi: ExtensionAPI): void {
     }
     if (files.size) addNote("tool", [...files].join(", "))
   })
+
   // 收尾注入: 每个会话最多一次, 避免反复打扰。
   pi.on("agent_end", async (event: any, ctx: any) => {
     if (teardownNudged) return

package/package.json

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

package/skill/SKILL.md

@@ -20,6 +20,7 @@ abs todo                     # 看板（Done 折成计数；明细 abs todo --fu
 abs index / abs log          # 完整 index.md / log.md
 abs status                   # 当前项目 + 图谱概要
 abs query <词1> [词2 …]      # 检索 .brain/ 知识页（多词 OR）
+abs resolve <页名或id>       # 反查页面路径（改名后 id 不变）
 abs lint                     # 图谱体检（死链/悬挂/超限/堆积/未提炼/Rules 超限）
 
 # 写
@@ -170,9 +171,13 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
    - 快照里的任务现在真做完了 → `abs todo done <id>`（done 后下次 load 滞留自动消失）；
    - 还没做完 → `abs todo note <id> --note "接到哪/改到哪个文件"` 补断点（别空手续接）。
    滞留没清完就不算接上了状态——这是「任务做完没进 Done」的根治动作。
-3. **读命中页**：按关键词在 index 定位 → 读对应 concepts/entities 全文。
+3. **读命中页**：`abs query <词>` 检索（多词 OR）→ 拿到页名后读那几个文件。
+   ```bash
+   abs query <词>                  # 全文检索，只回命中几页
+   abs resolve <页名或id>          # 反查文件路径（页改过名时用 id 能找回）
+   ```
    > ⚠️ **绝不通读 `.brain/`**（29 页就约 11 万 token，全读塞满窗口）。
-   > 要状态→`abs load`；要主题→`abs query <词>`（只回命中几页）；要某页→只读那页。
+   > 要状态→`abs load`；要主题→`abs query <词>`；要完整页清单→`abs index`（或直接读 `.brain/index.md`）；要某页→`abs resolve` 拿到路径后**只读那一页**。
    > 汇总多文件时用 `ctx_execute` 类工具在沙箱里处理，**只打印结论**。
 4. **续 todo**：默认续 todo 分支 → 把顶部未完成项当当前任务开做。
 5. **登记新任务**：有明确新任务而 todo 没有 → `abs todo add <id> --note 做什么` 再动工。
@@ -241,6 +246,9 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 
 1. **暂存线索**：`abs note`（或建 `sources/YYYY-MM-DD-slug.md`）记做了什么、改哪些文件、验证命令。
 2. **抽规律**：值得留的 → `concepts/<kebab-slug>.md`：触发场景/❌表现/🛠根因+解法+验证。挂双链。
+   **同时检查：旧页里有没有被本次推翻的说法？** 有 → `abs supersede <旧页> --by <新页>`
+   （别删页；删了会让下个会话重踩同一个坑、重新记一遍）。核实过的新页把 `status` 改成 `active`
+   （`abs note` 落的页默认是 `draft`）。
 3. **沉淀实体**：碰了重要未记录的事物 → `entities/<TitleCase>.md`。
 4. **对账 todo**：做完的归位 Done（标结语+日期），做一半的补断点，卡住的改 `[滞留中]`。
 5. **综合(可选)**：推进了选型/取舍 → `syntheses/`。
@@ -253,10 +261,28 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 
 ## 知识页格式
 
-统一 frontmatter：`tags / author / updated / status`（`status: draft`，或 `reviewed` = 冲突已裁决）。
+统一 frontmatter：`tags / author / updated / status`。
 `tags` 首标签 ∈ `entity|concept|source|synthesis|session-log`。`author` 与 `entities/<name>.md` 同名。
 
+**`status` 三个值（生命周期，别写别的）：**
+
+| 值 | 含义 | 读取侧行为 |
+|---|---|---|
+| `active` | 当前有效（**缺字段默认就是它**，存量页无需改） | 正常展示 |
+| `draft` | 待核实（`abs note` 新落的经验默认这个） | 展示但标注 `[draft 未核实]` |
+| `superseded` | **已被推翻，别再依据它** | `query` 默认隐藏（计数据告知） |
+
+**推翻一条经验**（不要删文件！）：
+```bash
+abs supersede <页名> --by <取代它的新页>   # 不写 --by 也行 = 单纯弃用，无替代
+```
+→ 把 `status` 改成 `superseded` 并写 `superseded-by`。**历史必须留**：删了会让下个会话重踩同一个坑、重新记一遍。
+→ 核实后发现仍有效：把 `status` 改回 `active`（一行，可反悔）。
+→ 拒写悬空引用：`--by` 指向不存在的页会直接拒绝。
+
 - **每页必须有 `## 关联连接`**，用 `[[页面名]]` 链相关页 —— 严禁孤岛页。
+  **链路解释写在 `—` 后面**（如 `[[hook-throttle-alignment]] — 节流判据要对齐「真收尾」`），
+  这样 AI 不点开就知道该不该跟进；只写链点不写解释，等于没链。
 - **命名即链接**：`[[Docker]]` → `entities/Docker.md`；`[[docker-prisma-429]]` → `concepts/`。不建别名层。
 - **知识冲突**：不静默覆盖，加 `## 知识冲突` 两版都留、标来源时间，交人工裁决。
 - 概念页骨架：`触发场景 / ❌表现(贴报错) / 🛠解法(根因+修复+验证命令) / 关联连接`。
@@ -265,9 +291,12 @@ Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已
 
 - `abs query <词>` 检索（多词 OR）→ 读命中页 → 答用 `[[页面名]]` 标来源。
   **代码问题（符号在哪/谁调用）不在 .brain，直接读源码**；.brain 只答"踩过什么坑/上次做到哪"。
-- `abs lint` 体检：死链/孤岛/**悬挂页**/缺 frontmatter/模板残留/超尺寸/sources 堆积/**超龄未提炼**/index 漏列/Rules 超限。
+  已被推翻的经验默认不返回（`--all` 可看）—— 但若你确实需要拿旧结论对照，记得它已被推翻。
+- `abs lint` 体检：死链/孤岛/**悬挂页**/缺 frontmatter/模板残留/超尺寸/sources 堆积/**超龄未提炼**/index 漏列/Rules 超限/**取代者悬空**/**draft 超龄**。
   - `NO-INBOUND`：有出边但无人 `[[链接]]` 到你 = 挂在图上没人接（孤岛检查只抓"零出零入"）。
   - `SOURCE-UNDISTILLED`：source 超 7 天仍未链到任何 concept = 暂存了没归位。
+  - `SUPERSEDED-DANGLING`：`superseded-by` 指向的页不存在（删页后忘同步）。
+  - `DRAFT-STALE`：concepts 等长期停在 `draft` = 既没核实也没推翻，核实/推翻后各改一行。
 
 ## 三层分工
 

package/src/store.js

@@ -430,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 '';
@@ -794,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/ 全部知识页';
@@ -824,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) {
@@ -883,6 +1058,7 @@ export async function cmdNote({ dir, text, tags }) {
   const body = [
     '---',
     `tags: [${fmTags}]`,
+    `id: ${file.replace(/\.md$/, '')}`,
     `author: ${who}`,
     `updated: ${today()}`,
     'status: draft',
@@ -924,6 +1100,7 @@ export async function ensurePersonPage(root, name) {
   const body = [
     '---',
     'tags: [entity, person]',
+    `id: ${nm}`,
     `author: ${nm}`,
     `updated: ${today()}`,
     'status: draft',
@@ -1002,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]]` —— 模板没填
@@ -1064,6 +1254,32 @@ 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 清单的膨胀根因）。
   {
@@ -1144,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 = '';
@@ -1178,6 +1397,8 @@ 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),
       });
     }
   }