@fanchao8609/agent_brain_sync 1.8.7 → 1.8.9

package/bin/abs.js

@@ -73,6 +73,9 @@ const FLAG_SPEC = {
   'as': { type: 'string' },
   'payload': { type: 'string' },
   'tags': { type: 'string' },
+  'port': { type: 'string' },
+  // note 的触发条件（何时该读这条经验）—— 供 load 的相关页推荐匹配。
+  'when': { type: 'string' },
   // concept 骨架用: 不在 FLAG_SPEC 里的 `--title` 会被静默当布尔 true（见 parseArgv 注释），
   // 于是 `--title "一句话"` 的正文会进位置参数 → 必须在这声明。
   'title': { type: 'string' },
@@ -175,46 +178,53 @@ function parseArgv(args) {
 }
 const usage = `abs — agent-brain-sync 记忆工具
 
-读:
+快速开始:
+  abs init                     在项目里建 .brain/ 图谱
+  abs load                     看当前状态 (每次开工先跑这个)
+  abs todo add X --note "做什么"    登记一个任务
+  abs note "经验一句话"          随手记一条经验 → sources/
+
+以上四条覆盖日常使用的 90%。
+
+读写:
   abs load                   开机读状态 (index/todo/log)
   abs todo                   任务看板 Todo / Done（未完成的都在这，行首带状态）
   abs index                  图谱索引 index.md
   abs log                    流水 log.md
   abs status                 当前项目 + 图谱概要
-
-写:
+  abs serve [--port 7777]    在浏览器里浏览 .brain/（只读，仅本机）
   abs todo add     <id> [--note ..] [--section ..]  登记任务 (start 同义)
-  abs todo note    <id> --note "断点/进度"   实时落 ↳ 断点 行
+  abs todo note    <id> --note "断点/进度"   实时落 ↳ 断点 行（建议前缀: 验证: / 边界: / 阻塞:）
   abs todo state   <id> --note "进行中|讨论中|滞留中"    改状态标记（原地，不搬区）
   abs todo done    <id> [--as 落地|否决|仅方案]    完成；结语标明到底"做成了没有"
                                默认 落地。否决=评估后不做(含做了又撤)；仅方案=只设计过
                                不加结语或结语失真会让下一个会话把"想过"当成"做完了"。
   abs log "完成 X：…"         记一行工作成果 (无参=查看)
-  abs note "经验一句话" [--tags 坑,docker]    经验实时暂存 → sources/
+  abs note "经验" [--tags 坑,docker] [--when "何时该读"]   经验实时暂存 → sources/
   abs concept <slug> --title "标题" [--tags a,b] [--desc "index 描述"]
                             建概念页骨架（头/中/尾四段位置）。只给结构不给内容
 
-维护:
+检索与维护:
   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 天; 任一天有未完成则整天不归档)
   abs lint                   图谱体检 (死链/孤岛/超尺寸/堆积)
   abs rule                   列出 index.md 的 ## Rules 硬规则
-  abs rule add "一句话"      追加一条硬规则 (只放违反会丢数据/静默失效级的；展开写概念页)
+  abs rule add "一句话"      追加一条硬规则 (只放违反会丢数据/静默失效级的)
+  abs todo archive [--keep-days N] [--dry-run]
+                            归档 Done 区旧日期组 → sessions/<日期>-todo归档.md
+
+安装与配置 (一次性):
+  abs install [--agent <宿主>]   安装 MCP+hook+skill (宿主: cl​aude-code/co​dex/op​encode/pi)
+  abs uninstall [--agent <...>]  卸载
+  abs update                 升级到最新版并刷新四宿主 hook/skill
   abs config [show]          查看使用者姓名 (标记作者用)
   abs config set user <名字> 设置使用者姓名 → ~/.abs/config.json
-                             未设置时写操作(todo/log/note)会报错要求先设置
-                             临时覆盖: ABS_USER=<名字> abs ...
+                             未设置时写操作会报错要求先设置 (临时: ABS_USER=<名字> abs ...)
   abs init [--repair]        建 .brain/ 图谱; 结构不完整时报明细, --repair 只补缺不覆盖
-  abs install [--agent <宿主>]   安装 MCP+hook+skill (宿主: claude-code/codex/opencode/pi)
-  abs uninstall [--agent <...>]  卸载
-  abs update                 升级到最新版并刷新四宿主 hook/skill
   abs --version              显示当前版本
   abs help                   本帮助
 
@@ -356,6 +366,25 @@ async function main() {
         rejectExtra(opts._, 'abs status');
         console.log(await cmdStatus({ dir: opts.dir }));
         break;
+      // abs serve —— 把 .brain/ 挂成只读网页（浏览器无法自己列目录，所以必须有服务端）
+      case 'serve': {
+        rejectExtra(opts._, 'abs serve');
+        const { serve } = await import('../src/serve.js');
+        const { requireBrain, brainPath } = await import('../src/index.js');
+        // 坑(2026-09-16 实测): requireBrain 返回的是【项目根】, .brain/ 在它下面 ——
+        // 直接把项目根当服务根会扫到 node_modules。必须走 brainPath()。
+        const root = brainPath(await requireBrain(opts.dir || process.cwd()));
+        const port = opts.port ? Number(opts.port) : 7777;
+        const { url, server } = await serve({ root, port });
+        console.log(`📖 abs serve → ${url}`);
+        console.log(`   根: ${root}`);
+        console.log('   (只读，仅本机可访；Ctrl+C 停止)');
+        if (opts.open !== false) runCmd('open', [url]);
+        // 不断开进程：服务要活着才有用
+        await new Promise(() => {});
+        server.unref();
+        break;
+      }
       // abs todo —— 无子命令=看板；带子命令=任务写操作
       case 'todo': {
         const [sub, id, ...rest2] = opts._;
@@ -386,7 +415,7 @@ async function main() {
         break;
       }
       case 'note': {
-        console.log(await cmdNote({ dir: opts.dir, text: opts._.join(' '), tags: opts.tags }));
+        console.log(await cmdNote({ dir: opts.dir, text: opts._.join(' '), tags: opts.tags, when: opts.when }));
         break;
       }
       case 'concept': {
@@ -461,7 +490,15 @@ async function main() {
       default: throw new Error(`未知命令: ${cmd}\n\n${usage}`);
     }
   } catch (e) {
-    console.error(String(e && e.message ? e.message : e));
+    // 带码的错（AbsError）：首行印 [CODE]，fallback 另起一行。
+    // 为何：hook/脚本需要机器可读的分支依据（借 Anneal 的 templateRefusal 惯例）。
+    // 无码的错照旧只印 message —— 不能把内部堆栈当错误码泄给使用人。
+    if (e && e.code) {
+      console.error(`[${e.code}] ${e.message}`);
+      if (e.fallback) console.error(`  → ${e.fallback}`);
+    } else {
+      console.error(String(e && e.message ? e.message : e));
+    }
     process.exit(1);
   }
 }

package/hooks/abs.opencode.ts

@@ -54,12 +54,9 @@ const server = async ({ client, directory }) => {
 
 
   const TEARDOWN_MSG =
-    "[abs 收尾提醒] 本会话改过文件但 .brain/ 今天还没有记录。请立即走收尾循环：\n" +
-    "1) 跑 abs load 看 Todo 还有哪些未完成；\n" +
-    "2) 实际做完漏登记的 abs todo done <id>，做到一半的 abs todo note <id> --note \"断点\"；\n" +
-    "3) 值得留的经验 abs note \"...\"（宁少勿滥，能从代码 grep 到的不记）；\n" +
-    "4) abs log \"完成 X：...\" 记一行工作成果，新页同步进 index。\n" +
-    "简洁执行，不要复述本条提醒。若本次确实没有可沉淀产出，直接回一句\"无可沉淀\"即可。"
+    "[abs] 本会话改过文件，.brain/ 今日无记录。\n" +
+    "这条是信息不是命令：该沉淀就沉淀，没有可沉淀的直接回一句「无可沉淀」，不用凑。\n" +
+    "需要时：abs todo / abs todo done <id> / abs note \"...\" / abs log \"...\""
 
   // 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/

package/hooks/abs.pi.ts

@@ -176,13 +176,10 @@ export default function absPiHook(pi: ExtensionAPI): void {
     const notes = sessionNotes.splice(0, sessionNotes.length)
     try {
       pi.sendUserMessage(
-        "[abs 收尾提醒] 本会话改过文件但 .brain/ 今天还没有记录。请立即走收尾循环：\n" +
-        "1) 跑 abs load 看 Todo 还有哪些未完成；\n" +
-        "2) 实际做完漏登记的 abs todo done <id>，做到一半的 abs todo note <id> --note \"断点\"；\n" +
-        "3) 值得留的经验 abs note \"...\"（宁少勿滥，能从代码 grep 到的不记）；\n" +
-        "4) abs log \"完成 X：...\" 记一行工作成果，新页同步进 index。\n" +
-        notesBlock(notes) +
-        "简洁执行，不要复述本条提醒。若本次确实没有可沉淀产出，直接回一句\"无可沉淀\"即可。",
+        "[abs] 本会话改过文件，.brain/ 今日无记录。\n" +
+        "这条是信息不是命令：该沉淀就沉淀，没有可沉淀的直接回一句「无可沉淀」，不用凑。\n" +
+        "需要时：abs todo / abs todo done <id> / abs note \"...\" / abs log \"...\"" +
+        notesBlock(notes),
         { deliverAs: "followUp" },
       )
     } catch {}

package/hooks/event.sh

@@ -38,6 +38,14 @@ fi
   MARK="$MARK_DIR/abs-hook-${FINGER}-${STAMP}.mark"
   [ -e "$MARK" ] && exit 0
   : > "$MARK" 2>/dev/null
+  # mark 只增不减: STAMP 是分钟级 → 每分钟一批, 永不回收。实测堆了 361 个。
+  # 幂等窗口只 60s, 非本分钟的 mark 不可能再命中 → 清掉。
+  # 注意: 同一分钟内不同 payload 有不同 FINGER, 它们各自合法 —— 只按 STAMP 清, 不按 FINGER。
+  for old in "$MARK_DIR"/abs-hook-*.mark; do
+    [ -e "$old" ] || continue
+    case "$old" in *-"$STAMP".mark) continue ;; esac
+    rm -f "$old" 2>/dev/null
+  done
 
   # 定位项目由 CLI 完成 (向上找 .brain/, 代码写死); 找不到图谱则静默放弃。
   # 纪律: hook 事件只进技术日志 (~/.abs/log/), 不进图谱 log.md (那是活动流水, 不收琐碎请求)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fanchao8609/agent_brain_sync",
-  "version": "1.8.7",
+  "version": "1.8.9",
   "description": "agent-brain-sync: 跨会话 AI 编码记忆 — hook 纯触发 + CLI/MCP 读写 .brain markdown 图谱, 防并发写保护。",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,7 @@
   "scripts": {
     "abs": "node bin/abs.js",
     "mcp": "node bin/mcp.js",
-    "test": "node --test 'test/*.test.js'",
+    "test": "node --test 'test/*.test.js' 'skill/**/*.test.js'",
     "prepack": "node -e \"require('fs').chmodSync('bin/abs.js',0o755);require('fs').chmodSync('bin/mcp.js',0o755)\"",
     "pack:check": "npm pack --dry-run"
   }

package/skill/abs-agent-brain-sync/SKILL.md

@@ -1,10 +1,32 @@
 ---
 name: abs-agent-brain-sync
-description: abs (agent-brain-sync) 跨会话 AI 编码记忆与任务续接。开场续接状态(abs load/MCP abs_load)，干活中任务/经验实时落盘(abs_task/abs_note)，每轮结束走收尾循环(读todo→判未登记→沉淀→更新index/log)。解决会话无状态：经验/进度/坑碎片化、重开失忆。遇 bug 排查时配合挂载 bug-hunter skill。
+description: abs (agent-brain-sync) 跨会话 AI 编码记忆与任务续接。开场续接状态(abs load/MCP abs_load)，干活中任务/经验实时落盘(abs_task/abs_note)，需要收尾时才走收尾循环。解决会话无状态：经验/进度/坑碎片化、重开失忆。遇 bug 排查时配合挂载 bug-hunter skill。
 ---
 
 # abs — 跨会话记忆 (agent-brain-sync)
 
+## 最高优先：触发总则（凌驾本文所有流程）
+
+**关键词不是触发器，意图才是。**
+
+句子里出现 abs 词（收尾/todo/沉淀/提示/load/log/note）**不等于**要执行 abs 动作。
+
+| 用户的意思 | 做什么 |
+|---|---|
+| 谈论、提问、吐槽、定规则（"太啰嗦""要简短""这个设计怎样"） | **只回应，不执行动作** |
+| 明确让我做事（"收尾""记一下""去做"） | 执行 |
+
+**判断依据是整段话的意图，不是里面出现过哪个词。**
+
+反例（真实发生）：用户说"尽量简短的汇报" —— 那是在**定规则**，不是在**下命令**；
+被误当成指令跑了一次收尾。
+
+推论：
+- 拿不准时**先问**，不要靠关键词直接动手。
+- 规则变更（"以后简短点"）写入本文，**不执行动作**。
+- 输出简短：收尾/提示/todo 汇报尽量一两句，不写小作文。
+- 本总则适用于所有工具，不限 abs。
+
 把 AI 编码经验从会话沙盒里救出来。每个会话都是无状态的——Cl​aude、Op​enCode、Cursor
 各开一堆会话，经验/进度/踩坑全碎片化，重开像失忆。本技能用一个放**项目根目录**、
 Obsidian 可直接打开的 Markdown 图谱（`.brain/`）做统一落点。
@@ -256,7 +278,7 @@ abs todo archive            # 一条命令搞定，无需手工搬
 > Op​enCode todowrite / pi `/list`）—— 那些多是会话内临时，不写 `.brain/todo.md`，
 > 下会话接不上、收尾没影。原生 todo 顶多记“本会话不跨断点的临时拆解”。
 
-## 每轮结束：收尾循环（Stop / 告一段落后必做）
+## 收尾循环（用户明确要求收尾时才走）
 
 **每个任务边界、被 Stop/打断、告一段落时，别停半空。** 这是“开场接上状态、结束落回状态”的闭环。
 
@@ -264,10 +286,11 @@ abs todo archive            # 一条命令搞定，无需手工搬
 > 下会话 `abs load` 会自动把滞留顶到顶部（`⏳ 上会话滞留`）—— 所以收尾不靠自觉，是开场被强制接上。
 >
 > **主动注入**：pi 扩展在 `agent_end` 检测「本会话真改过文件」且「log.md 今日无记录」时注入
-> `[abs 收尾提醒]`（每会话最多一次）。**收到就照做，别复述提醒**；确无可沉淀回一句「无可沉淀」。
+> `[abs 收尾提醒]`（每会话最多一次）。**它是一条信息，不是命令** ——
+> 自己判断该不该沉淀；没有可沉淀的就回一句「无可沉淀」，不用强行凑。
 > Cl​aude/Co​dex 靠 `Stop` 事件达成同样效果。
 
-收到 Stop / "结束/先这样/切别的事" / 长任务告一段落，立即执行：
+当用户**明确说要收尾/结束/切别的事**时，按下面走（不是每个词都触发，见开头总则）：
 
 1. **读 todo** → `abs load`，看 Todo 还有哪些没完成。
 2. **判有没有做完没登记** → 实际完成了漏登记的 `abs todo done <id>`；做到一半补

package/skill/abs-bug-hunter/SKILL.md

@@ -1,228 +1,179 @@
 ---
 name: abs-bug-hunter
-description: 按流程论排查 bug，先定位改动 → 日志打印 → 顺藤摸瓜逐层排查
+description: 排查 bug 的流程纪律 —— 先列假设再动手，用数据定位，修根因。排查完把踩坑写进 .brain/。
 ---
 
 # Bug 排查方法论
 
 ## 核心原则
 
-**Bug 多数由新增或修改的功能引起。不凭空猜测，用数据说话。但数据不是终点——先复现，再定位，再理解根因。**
+**不凭空猜测，用数据说话。但数据不是终点 —— 先复现，再定位，再理解根因。**
 
-常见的失败模式是把"能复现的问题"当成"已定位的 bug"，跳过理解直接下结论。定位到错误位置 ≠ 找到根因。改对症状而不改根因，换一批数据又会复发。
+最常见的失败：把"能复现"当成"已定位"。定位到出错的**位置** ≠ 找到**根因**。
+改症状不改根因，换一批数据就复发。
 
-## 排查流程
+## 第 -1 步：列假设（不能跳过）
 
-### 第 -1 步：列假设 —— 方向错了怎么办（不能跳过）
+**触发**：用户报了症状（"打不开""报错了""不对"），但没给一手错误信息。
 
-**触发**：用户报了症状（“打不开”“报错了”“不对”），但没给一手错误信息。
+**这一步在"复现"之前**，因为拿不到报错时，"先复现"会逼你造假。
 
-**最大坑（真实案例）**：只有一个假设时，它要么被证实要么思路断掉 —— 于是**自己造一个输入**去测：
-编了个接口名 `app.init` → curl 测出 404 → “我测出来的，是事实” → 推出“nginx 没配 PATH_INFO”
-→ 用户纠正后**重跑同一实验、得到同一 404** → 坚信自己没错。
+### 自造证据 —— 最毒的一类错误
 
-> 假证据最毒之处：**下游全程都是真的**（404 真、命令真跑过）。唯一假的那环
-> （输入名）在最上游，且已消失在过程里 → 所以“再验证一次”救不了，
-> 他会重跑同假输入得同真输出。
-> 下面第 0 步“先复现”在拿不到报错时反而会逼出造假 —— 所以本步在它之前。
+**真实案例**：只有一个假设时，它要么被证实要么思路断掉 —— 于是自己造一个输入去测：
 
-1. **开局列 ≥2 个假设**（代码层 / 配置层 / 构建产物 / 缓存 / 第三方后台）。
+```
+编了个接口名 app.init → curl 测出 404 → "我测出来的，是事实"
+→ 推出"nginx 没配 PATH_INFO"
+→ 用户纠正后，重跑同一实验、得到同一 404 → 坚信自己没错
+```
+
+**为什么最毒**：下游全程都是真的（404 真、命令真跑过）。唯一假的那环在**最上游**，
+且已消失在过程里 → 所以"再验证一次"救不了，重跑同假输入得同真输出。
+
+### 所以
+
+1. **开局列 ≥2 个假设**（代码 / 配置 / 构建产物 / 缓存 / 第三方）。
    只列一个 = 逼自己去证实它 = 造证据的动力。
 2. **每个假设配反证条件**：什么现象出现就认它错。
-   > 例：“假设 nginx 没配 PATH_INFO；反证条件：用**从代码里读到的真实接口名**
-   > 测出也是 404 → 接口本身不存在，与 nginx 无关 → 弃此假设。”
-   > 反证条件里写明“真实接口名”，`app.init` 这种编造的就自动不能用了。
+   反证条件里要写明**能从代码里读到的真实名字**，编造的自动不能用。
 3. **卡住两轮就换假设**，不是在同一假设上加细节。
-4. **领域外的先声明无取证能力**（构建产物在不在 / 缓存 / 微信等第三方后台行为），
+4. **领域外的先声明无取证能力**（构建产物在不在 / 缓存 / 第三方后台行为），
    要用户提供事实，**不要脑补**。
 
 **结论所依据的每个具体名字（接口/字段/报错文本/路径）必须指得出处（文件:行）。**
-指不出的，只能标“推测”二字，**不得当证据用**。
+指不出的只能标"推测"，**不得当证据用**。
 
 > **为什么多假设能防造假**：单假设必须被证实，否则思路断 → 有动机造。
-> 多假设下，“支持了 A” 不等于 “就是 A”（B/C/D 还没排除）→ **假证据推不出结论，造它就没意义了**。
+> 多假设下，"支持了 A" ≠ "就是 A"（B/C/D 还没排除）→ 假证据推不出结论，造它就没意义。
+
+## 第 0 步：复现
 
-### 第 0 步：复现 — 先让 Bug 稳定出现
+没有稳定复现，后面全是猜。
 
-没有稳定复现，后面全是猜。先确定：
 - 复现的必要条件是什么？哪个输入/操作/环境触发？
-- 是 100% 复现，还是偶发？偶发问题先找触发模式（特定数据、特定时机、特定顺序）。
-- 日志里有没有现成的错误栈？错误信息 + 行号是最便宜的定位入口。
+- 100% 复现还是偶发？偶发先找触发模式（特定数据/时机/顺序）。
+- 有现成错误栈吗？**错误信息 + 行号是最便宜的定位入口。**
 
-**给 Bug 起个名字**（一句话描述 + 触发条件）。排查卡住时，回去核对是否还在同一个 Bug 上。
+**给 Bug 起个名字**（一句话描述 + 触发条件）。卡住时回来核对是否还在同一个 Bug 上。
 
-### 第一步：定位范围 — 改动了什么
+## 第一步：定位范围 —— 改动了什么
 
-Bug 不会凭空出现。先查最近的代码改动：
+Bug 不会凭空出现。先查最近的改动：
 
 ```bash
-git diff HEAD~3 --stat          # 看改了哪些文件
-git log --oneline -5            # 看最近提交
-git diff <commit> -- <file>     # 看具体改了什么
-git log -p -S '可疑字段/函数名'  # 谁改过这段代码
-git blame <file> -L <行号,行号>  # 定位到具体某行是谁写的
+git diff HEAD~3 --stat           # 改了哪些文件
+git log -p -S '可疑字段/函数名'   # 谁改过这段
+git blame <file> -L <行号,行号>   # 定位到具体某行
 ```
 
-问自己：
-- 这次新增/修改了什么功能？
-- 改动涉及哪些文件？
-- 哪个改动最可能影响到出问题的地方？
-
-**不要排查无关代码，把精力集中在改动范围。**
+问自己：这次新增/修改了什么？涉及哪些文件？哪个最可能影响出问题的地方？
 
-### 第二步：日志打印 — 让数据说话
+**别排查无关代码。**
 
-不要猜，打印出来看。根据技术栈选择打印方式：
+## 第二步：让数据说话
 
-| 技术栈 | 打印方式 | 日志位置 |
-|--------|----------|----------|
-| PHP (ThinkPHP) | `\think\Log::error($data)` 或 `trace($data)` | `runtime/log/` |
-| PHP (Laravel) | `Log::info($data)` 或 `logger($data)` | `storage/logs/` |
-| Vue / JS | `console.log(data)` | 浏览器控制台 |
-| Node.js | `console.log(data)` 或 `logger.debug(data)` | 终端 / 日志文件 |
-| SQL | `\think\Db::getLastSql()` 或开启 SQL 日志 | runtime/log 或控制台 |
+不猜，打印出来看。
 
-**打印要打印关键数据，不要只打印 "到了这里"，要打印实际的变量值。**
+- **打印关键数据，不要只打印"到了这里"** —— 要打印实际的变量值、类型、入参出参。
+- **二分法**：在可疑链路上隔几层插日志，先跑一遍看哪段有数据、哪段没有，
+  范围砍半再往里加。比一次打满所有层更快收敛。
+- **带唯一前缀**（如 `[BUG-01]`）：日志里 grep 一次看到全链路顺序。
+- 怀疑并发/时序时，打时间戳与调用来源。
 
-```php
-// ❌ 没用
-\Log::error('进入方法');
+## 第三步：顺藤摸瓜
 
-// ✅ 有用 — 打印入参、中间态、出参
-\Log::error('goods detail', ['id' => $id, 'goods' => $goods, 'type' => gettype($goods)]);
-```
-
-**二分法打印**：在可疑链路上隔几层就插一个日志点，先跑一遍看哪段有数据、哪段没数据，把范围砍半，再往里面加日志。比一次打满所有层更快收敛。
-
-**加分技巧**：
-- 给每个日志点带唯一前缀（如 `[BUG-01]`、`[BUG-02]`），日志里 grep 一次就能看到全链路顺序。
-- 打印耗时和调用来源：怀疑并发/时序时，打上时间戳与 `debug_backtrace()` 或请求 ID。
-
-### 第三步：顺藤摸瓜 — 按调用链逐层排查
+从用户操作出发，沿调用链一层层往下：入口 → 路由 → 中间件 → 业务层 → 数据层 → 存储。
 
-从用户操作出发，沿着调用链一层层往下查：
-
-```
-用户操作（点击/请求）
-  → 路由（routes / pages.json / url）
-    → 门面/中间件（facade / middleware）
-      → 控制器（controller）
-        → 服务层（service）
-          → 模型（model）
-            → 数据库（SQL）
-```
+**每一层打印关键数据，找到数据从正确变为错误的那一层 —— bug 就在那一层。**
 
-每一层都打印关键数据，确认数据在哪一层开始出错：
+## 第四步：找根因，不只修症状
 
-```php
-// 控制器 — 打印接收到的参数
-\Log::error('controller input', ['params' => $params]);
+修复前回答：
 
-// 服务层 — 打印处理中的数据
-\Log::error('service process', ['data' => $data, 'result' => $result]);
+- 为什么数据在这一层变错了？**逻辑错误**（判断写反/取错字段）、
+  **类型错误**（null/数组/对象混用）、还是**数据本身脏**（上游写入时就错）？
+- 根因若在上游，这里 patch 只是挡一下 —— 应该去修上游，或在入口统一兜底。
 
-// 模型 — 打印查询结果
-\Log::error('model query', ['sql' => $this->getLastSql(), 'result' => $result]);
-```
+**修一层，不改所有调用点**：如果多个地方调用同一函数，只在出问题的调用点打补丁，
+其他调用点照样坏。**在共享函数里修一次，是所有调用点的最小修复。**
 
-**找到数据从正确变为错误的那一层，bug 就在那一层。**
+## 第五步：验证修复
 
-### 第四步：找到根因，不只修症状
+不要凭空验证。**先拿第 0 步的复现条件重跑，必须看到它失败** ——
+没失败就说明你修好了但没复现过，或者复现条件记错了。
+不先看到 fail，就无法区分"修好了"和"根本没坏过"。
+改完再看它变 pass，三层都要过：
 
-改对症状 = 换一批数据又复发。修复前回答：
-- 为什么数据在这一层变错了？是**逻辑错误**（判断写反/字段取错），**类型错误**（null/数组/对象混用），还是**数据本身脏**（上游写入时就错了）？
-- 根因若在上游（写入方/历史数据），这里 patch 只是挡一下，应该去修上游或在入口统一兜底。
+| 层 | 查什么 |
+|---|---|
+| **修好了** | 复现路径不再报错，输出正确 |
+| **没修坏** | 相关正常路径仍正常（回归） |
+| **边界还在** | 边缘输入（空值/超大值/并发/重复提交）没引入新洞 |
 
-**修一层，不改所有调用点**：如果多个地方都调用同一函数，只在出问题的那个调用点打补丁，其他调用点照样坏。在共享函数里修一次，是所有调用点的最小修复。
+确认无误后再删调试日志。
 
-### 第五步：验证修复 — 逐行打印确认
+## 排查完：写进 .brain/
 
-修复 bug 后，不要凭空验证。**先拿第 0 步的复现条件重跑**，确认错误消失、结果正确，再用打印验证每一步符合预期：
+**这一步是 `abs-` 前缀的意义 —— 排查的结论不写下来，下个会话会重踩同一个坑。**
 
-```php
-// 修复后验证
-\Log::error('step1: fetch', ['data' => $data]);
-$data = transform($data);
-\Log::error('step2: transform', ['data' => $data]);
-$result = save($data);
-\Log::error('step3: save', ['result' => $result]);
+```bash
+abs note "一句话结论" --when "什么时候该看这条"
 ```
 
-验证包括三层：
-- **修好了**：复现路径不再报错，输出正确。
-- **没修坏**：相关正常路径仍正常（回归）。
-- **边界还在**：尝试边缘输入（空值、超大值、并发、重复提交），确认修复没引入新洞。
-
-确认无误后，再删除调试日志。
-
-## 实战示例
-
-**场景：** 商品详情页报 `Call to a member function toArray() on array`
-
-**第 0 步：复现**
-- 访问 `/shopro/goods/goods/detail/id/31` 稳定复现
-- 日志：`[error] 致命错误: Call to a member function toArray() on array [/var/www/html/.../GoodsMemberPrice.php:50]`
-
-**第一步：定位范围**
-- 最近新增了会员系统，改了 Goods 控制器和新增了 GoodsMemberPrice 模型
-- 怀疑新增代码有问题
+值得写的（**能从代码 grep 到的不写**）：
 
-**第二步：查看日志**
-- 日志直接告诉出错文件和行号
+| 写什么 | 例 |
+|---|---|
+| **假象的根因** | "报错位置是 A，真因在 B 的写入侧" |
+| **判据** | "统计硬切率 >30% 即确诊，别去调 prompt" |
+| **反直觉处** | "慢的不是读写，是 node 启动" |
+| **排查路径** | "先查写入侧，别先怪模型" |
 
-**第三步：顺藤摸瓜**
-- 路由：`/shopro/goods/goods/detail/id/31`
-- 控制器：`Goods::detail()` → 调用了 `GoodsMemberPriceModel::getByGoods()`
-- 模型：`getByGoods()` 第50行 `select()->toArray()` → `select()` 返回数组，不是 Collection
+不值得写的：报错原文（日志里有）、修好的代码（git 里有）、通用常识。
 
-**第四步：找根因**
-- 为什么 id=31 出错而别的正常？查数据：31 这件商品有会员价记录 → 触发 `select()` 返回多行场景。可能是 `find()`/`select()` 返回值混用的历史问题。若只是个别记录脏，应清理数据或给方法加统一返回类型。
+**如果是反复踩的坑**，排查结束后提成硬规则：
 
-**第五步：修复验证**
-```php
-// 修复前
-return self::where('goods_id', $goodsId)->select()->toArray();
-
-// 修复后
-$result = self::where('goods_id', $goodsId)->select();
-return $result instanceof \think\Collection ? $result->toArray() : (array)$result;
+```bash
+abs rule add "靠提醒才能工作的功能，该删不该补"
 ```
-- 重跑 id=31（不再报错）+ 跑一个无会员价记录的 id（确认没回归）
 
 ## 常见陷阱
 
 | 陷阱 | 正确做法 |
 |------|----------|
-| 凭经验猜测 bug 位置 | 先复现 + 看日志/打印，用数据定位 |
-| 只看代码不运行 | 打印实际运行时的数据 |
-| 一次改很多地方再测试 | 改一处、验证一处 |
-| 修症状不修根因 | 追问"为什么这层数据变了"，确认根因 |
-| 只验证出错的路径 | 重跑复现 + 回归正常路径 + 边界输入 |
-| 忘记删除调试代码 | 修复确认后清理所有 `console.log` / `\Log::error` |
-| 只在本地验证 | 确认服务器代码是否同步部署，数据是否一致 |
-| 排查卡住还硬扛 | 回去核对第 0 步的 Bug 描述，确认是否在同一个问题上；必要时换数据/换触发角度重看 |
-| 偶发当成必然 | 偶发先找触发模式，别用单个样本下结论 |
-
-## 兜底：卡住时做什么
-
-排查 >20 分钟没进展，不硬扛，回到流程检查：
-1. **Bug 描述还准吗？** 是否有新的观察改变了问题定义。
-2. **复现还稳定吗？** 换一个触发样本还出现吗。
-3. **有没有漏看的日志？** grep 全量日志（不只最近的），可能早期就报过错。
-4. **改动范围查全了吗？** 只看 HEAD~3 可能漏了分支合并、配置文件、部署差异。
-5. **要不要跟同事确认？** 这条功能最近谁改的、改动意图是什么，可能一句话点醒。
-6. **向上游看一层。** 数据/配置来源方是否也变了，不只是消费方的问题。
-
-## 收尾：给结论要明确，不要模糊
+| 凭经验猜位置 | 先复现 + 看日志/打印 |
+| 只看代码不运行 | 打印运行时的实际数据 |
+| 一次改很多地方再测 | 改一处、验证一处 |
+| 修症状不修根因 | 追问"为什么这层数据变了" |
+| 只验证出错路径 | 复现 + 回归 + 边界 |
+| 忘记删调试代码 | 确认后清理所有打印 |
+| 只在本地验证 | 确认部署的代码/数据一致 |
+| 偶发当成必然 | 先找触发模式，别用单样本下结论 |
+| 排查完不落盘 | 提一条 `abs note`，反复踩的提 `abs rule` |
+
+## 兜底：卡住时
+
+排查 >20 分钟没进展，不硬扛，回流程检查：
+
+1. **Bug 描述还准吗？** 新观察是否改变了问题定义。
+2. **复现还稳定吗？** 换个触发样本还出现吗。
+3. **漏看日志了吗？** grep 全量（不只最近的），可能早期就报过错。
+4. **改动范围查全了吗？** 只看 HEAD~3 会漏分支合并、配置、部署差异。
+5. **要不要问人？** 这条功能最近谁改的、意图是什么，可能一句话点醒。
+6. **向上游看一层。** 来源方是否也变了，不只是消费方的问题。
+
+## 收尾：结论要明确
 
 **不许**："可能是 X，也可能是 Y，建议排查一下" —— 这是把判断推回给用户。
 
-**必须**：明确给出
-1. **当前结论**（是什么 / 或者"未定位"）
+**必须**给出：
+
+1. **当前结论**（是什么 / 或"未定位"）
 2. **置信度与依据**（哪来的证据 / 还是只是推测）
-3. **下一步具体动作**（跑什么命令、看什么输出、要用户提供什么）
+3. **下一步具体动作**（跑什么、看什么、要用户提供什么）
 
-"未定位"是合法输出，但必须配一句"**需要你提供 X**"（具体到要什么都），
+"未定位"是合法输出，但必须配一句"**需要你提供 X**"（具体到要什么），
 不能只说"无法确定"就结束。
 
-> 与第 -1 步同一根因：模糊化是逃避判断。要么给结论 + 依据，要么明确索取证据。
+> 与第 -1 步同一根因：**模糊化是逃避判断。** 要么给结论 + 依据，要么明确索取证据。

package/src/index.js

@@ -26,13 +26,32 @@ export function brainPath(brainRoot, ...rel) {
   return join(brainRoot, BRAIN_DIR, ...rel);
 }
 
+/**
+ * 带错误码的错（CLI/MCP 同源）。
+ *
+ * 为何要码（2026-09-16 借 Anneal 的 templateRefusal）：
+ *   MCP 侧早就有 code（err(msg,{code,fallback})，5 种），CLI 侧全是自然语言句子。
+ *   于是 hook/脚本无法区分「该静默」与「该报警」——只能靠抓字符串，改文案就碎。
+ *   约定：所有可预期的失败都带 code；调用方按码分支，不看文案。
+ * 命名：大写下划线（与 MCP 侧一致）。
+ */
+export class AbsError extends Error {
+  constructor(code, message, fallback) {
+    super(message);
+    this.name = 'AbsError';
+    this.code = code;
+    this.fallback = fallback || null;
+  }
+}
+
 /** 断言 .brain/ 存在，否则抛错（宁可失败不落错项目）。 */
 export async function requireBrain(startDir) {
   const root = await findBrainRoot(startDir);
   if (!root) {
-    throw new Error(
-      `abs: 目录 ${resolve(startDir)} 下没有 .brain/ 图谱（不向上搜索）。\n` +
-      `  请在该目录运行: abs init`
+    throw new AbsError(
+      'NO_BRAIN',
+      `abs: 目录 ${resolve(startDir)} 下没有 .brain/ 图谱（不向上搜索）。`,
+      '请在该目录运行: abs init'
     );
   }
   return root;