@fanchao8609/agent_brain_sync 1.9.2 → 1.9.3

package/hooks/abs.pi.ts

@@ -115,16 +115,38 @@ async function loggedToday(brain: string): Promise<boolean> {
 }
 
 
+/** 收尾注入的节流状态。
+ *
+ * 为何在**模块级**而不在 absPiHook() 里（2026-09-17 实测）：扩展会被重复注册
+ * （session_start 11 分钟内触发 8 次），每次注册都新建一份闭包 → flag 不共享 →
+ * 实测同会话 5 分钟注入 6 次。模块级状态在同一进程内只有一份，注册多少次都共享。
+ *
+ * teardownNudged  = 本会话已注入过（终态，session_start 才重置）
+ * teardownInFlight = 正在判定中（抢在 await 之前置位，堵住并发重入）
+ * agentEndSeen    = 本会话已留过 seen 痕（可观测性，同样每会话一次）
+ */
+let teardownNudged = false
+let teardownInFlight = false
+let agentEndSeen = false
+
+/** 会话边界重置节流（session_start 与注册时都调）。
+ *  不重置 → 同进程第二个会话继承 true 永久静默（2026-09-13 实测过的坑）。 */
+function resetThrottle(): void {
+  teardownNudged = false
+  teardownInFlight = false
+  agentEndSeen = false
+}
+
 export default function absPiHook(pi: ExtensionAPI): void {
-  // 收尾注入的节流状态。声明在**外层** + 在 session_start 里重置：
-  // 否则同一进程的第二个会话会继承上一个会话的 true，永久不再提醒
-  // （2026-09-13 实测：同一天多个会话时后半场全部静默）。
-  let teardownNudged = false
-  let agentEndSeen = false
+  // 收尾注入的节流状态。故意声明在**模块级**（不在被反复调用的工厂函数里），
+  // 因为**扩展会被重复注册**：实测 session_start 在 11 分钟内触发 8 次
+  // （2026-09-17 00:07:58 一口气 3 次）。注册几份就得到几份独立闭包，
+  // 各自的 flag 彼此看不见 → “每会话一次”变成“每实例一次” → 实测同会话 5 分钟注入 6 次。
+  // 模块级状态在同一进程内共享，注册多少次都只有一份。
+  resetThrottle()
 
   pi.on("session_start", (event: any, _ctx: any) => {
-    teardownNudged = false
-    agentEndSeen = false
+    resetThrottle()
     return logHook("session_start").catch(() => {})
   })
 
@@ -152,8 +174,18 @@ export default function absPiHook(pi: ExtensionAPI): void {
   })
 
   // 收尾注入: 每个会话最多一次, 避免反复打扰。
+  //
+  // 坑（2026-09-17 实测定根因）：原实现是「先检查 flag → 若干 await → 才置位」，
+  // 而 agent_end **每轮 run 结束都触发**（官方 docs/extensions.md:569：它不等于会话结束，
+  // Pi 之后还可能继续跑 follow-up）。并发的多次调用因此**全部先通过 `if (nudged) return`**，
+  // 之后才各自置位 → 一起注入。实测同会话 5 分钟内注入 6 次，全日志 55 次。
+  // 修法：进函数**第一个动作**就抢占（置位在任何 await 之前），失败再把标志放回。
+  // 这样“检查+设置”之间没有让出点，并发调用只有一个能赢。
   pi.on("agent_end", async (event: any, ctx: any) => {
-    if (teardownNudged) return
+    if (teardownNudged || teardownInFlight) return
+    teardownInFlight = true
+    // 从这里往下任何提前 return 都必须解除 in-flight（否则本次会话永久不再提醒）。
+    const release = () => { teardownInFlight = false }
     const cwd = (ctx && ctx.cwd) || process.cwd()
     const brain = await findBrain(cwd)
     // 可观测性: 本会话首次 agent_end 无条件留一行痕。
@@ -163,14 +195,15 @@ export default function absPiHook(pi: ExtensionAPI): void {
       // 带上 cwd 与命中的 brain —— 否则事后无法解释“为何这条 nudge 会出现”
       await logHook(`agent_end:seen cwd=${cwd} brain=${brain || 'none'}`).catch(() => {})
     }
-    if (!brain) return // 无图谱=不在这项目沉淀, 不打扰
-    if (!hasWriteWork(event?.messages ? collectToolResults(event.messages) : [])) return
+    if (!brain) return release() // 无图谱=不在这项目沉淀, 不打扰
+    if (!hasWriteWork(event?.messages ? collectToolResults(event.messages) : [])) return release()
     // 今日已收尾 → 只在**本会话还没真正干事**时才静默。
     // 旧行为：今天 log 有一行就整天闭口 —— 于是收尾之后的产出全部没人提醒。
     // 注意不能用 sessionNotes.length 当判据：用户每说一句话就会 push 一条，
     // 那会让 nudge 每轮都触发（噪音）。判据保持「今天已收尾」但配合下面的笔记消费。
-    if (await loggedToday(brain)) return
+    if (await loggedToday(brain)) return release()
     teardownNudged = true
+    teardownInFlight = false
     await logHook("agent_end:teardown-nudge").catch(() => {})
     // 素材交给 AI 后清空：同一会话再触发时不该重复喂旧料。
     const notes = sessionNotes.splice(0, sessionNotes.length)

package/hooks/event.sh

@@ -31,19 +31,36 @@ fi
 (
   # 幂等: 同一 payload 指纹在 60s 内只落一行 (防重复触发)。
   # mark 目录可经 ABS_MARK_DIR 覆盖(默认 /tmp)——测试注入沙盒目录隔离, 避免与真实/并发残留互扰。
+  #
+  # 坑（2026-09-17 实测定根因）：原实现把 mark 名钉在 STAMP=$(date +%Y%m%d%H%M)（分钟级）上，
+  # 而文档/测试约定的是【60s 窗口】。两者不等价：两次调用只要**跨过分钟边界**，
+  # STAMP 不同 → mark 路径不同 → [ -e ] 不命中 → 各写一行，实际窗口最坏缩到 1 秒。
+  # 实测复现（同 payload、STAMP 从 2359 跳到 0000）→ 落 2 行，违反 60s 承诺。
+  # 也是 test/hook.test.js「同一 payload 60s 内幂等」偶发失败的真因（不是测试写得不好）。
+  #
+  # 修法：mark 名**只含指纹**（与时间无关），幂等判据改看**写在 mark 里的时间戳**。
+  # 为何不靠 find -newermt：BSD find(macOS) 不认 `@epoch` 格式（实测报
+  #   `Can't parse date/time: @1789619554`）→ 守卫恒不命中 → 幂等彻底失效。
+  # 也不用 -mmin：只能到分钟级，正是原 bug 的同类误差。
+  # 把时间戳写进文件、用 shell 纯数字比 —— 不依赖任何平台工具的日期解析。
   FINGER=$(printf '%s' "$PAYLOAD" | cksum | cut -d' ' -f1)
-  STAMP=$(date +%Y%m%d%H%M)
   MARK_DIR="${ABS_MARK_DIR:-/tmp}"
   mkdir -p "$MARK_DIR" 2>/dev/null
-  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。
+  MARK="$MARK_DIR/abs-hook-${FINGER}.mark"
+  NOW=$(date +%s)
+  PREV=$(cat "$MARK" 2>/dev/null)
+  case "$PREV" in ''|*[!0-9]*) PREV=0 ;; esac
+  # 60s 内已记过 → 幂等退出。窗口是真 60 秒，与分钟边界无关。
+  [ "$PREV" -gt 0 ] && [ "$((NOW - PREV))" -lt 60 ] && exit 0
+  printf '%s\n' "$NOW" > "$MARK" 2>/dev/null
+  # 清理: 只删**超龄**(>60s)的 mark。
+  # 不按分钟批量删 —— 那会在跨分钟时误删刚写的 mark（旧 bug 的帮凶）。
   for old in "$MARK_DIR"/abs-hook-*.mark; do
     [ -e "$old" ] || continue
-    case "$old" in *-"$STAMP".mark) continue ;; esac
+    [ "$old" = "$MARK" ] && continue
+    OV=$(cat "$old" 2>/dev/null)
+    case "$OV" in ''|*[!0-9]*) OV=0 ;; esac
+    [ "$OV" -gt 0 ] && [ "$((NOW - OV))" -lt 60 ] && continue
     rm -f "$old" 2>/dev/null
   done
 

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: abs-agent-brain-sync
-description: abs (agent-brain-sync) 跨会话 AI 编码记忆与任务续接。开场续接状态(abs load/MCP abs_load)，干活中任务/经验实时落盘(abs_task/abs_note)，需要收尾时才走收尾循环。解决会话无状态：经验/进度/坑碎片化、重开失忆。遇 bug 排查时配合挂载 bug-hunter skill。
+description: abs (agent-brain-sync) 跨会话 AI 编码记忆与任务续接。开场续接状态(abs load/MCP abs_load)，干活中任务/经验实时落盘(abs_task/abs_note)，需要收尾时才走收尾循环。解决会话无状态：经验/进度/坑碎片化、重开失忆。
 ---
 
 # abs — 跨会话记忆 (agent-brain-sync)
@@ -389,6 +389,3 @@ abs supersede <页名> --by <取代它的新页>   # 不写 --by 也行 = 单纯
 - 只读写 `.brain/` 与目标代码，不动全局配置（一次性接入除外）。
 - 只写真实发生的事实；遵守容量纪律，宁缺毋滥。
 - 双链/frontmatter/index 必须自洽 —— 坏链 = 掰断接力棒。
-- **排查 bug 时挂载 `bug-hunter` skill**（随 abs 一并安装，安装名为 `abs-bug-hunter`，位于 ~/.pi/agent/skills/abs-bug-hunter/ 等宿主对应目录）：
-  完整排查流程（列假设 → 复现 → 定位改动 → 打印 → 顺藤摸瓜 → 根因 → 验证）
-  与「给结论要明确」都在那份里。**排查方法不写在本文件**（两份维护必漂）。

package/src/relevant.js

@@ -159,6 +159,22 @@ function ngrams(s) {
   return out;
 }
 
+/** 是否走 2-gram 模糊兜底。
+ *
+ * 只对【含中文】的查询词生效（2026-09-17 实测根因）。
+ * 为何要这道门：字符 2-gram 是给中文设计的（"并发写"→"互斥"），中文 gram 有区分度；
+ * 英文没有 —— "relevant" 的 7 个 gram(re,el,ev,va,an,nt) 在**任意**英文页里都存在，
+ * ratio 恒为 1.0，稳过 FUZZY_MIN=0.6 → 每页都命中。
+ * 实测（44 页图谱）：query relevant → 30 命中全是 fuzzy score=10，而 "relevant" 在
+ * 页面里出现 0 次；query store → 42/44 命中。这些命中是巧合子串，不是相关。
+ * 收紧后同一图谱：relevant 30→0、store 42→16（剩下的 16 是真子串命中）。
+ * 反证该门不误伤：20 个真实中文查询（并发写/静默失效/陈旧路径…）实测 fuzzy 命中全为 0，
+ * 全走精确路径 —— 收紧后逐字不变。
+ */
+export function hasCJK(s) {
+  return /[\u4e00-\u9fa5]/.test(String(s || ''));
+}
+
 /** 模糊门槛 + 最小 gram 数（见 rankPage 注释） */
 export const FUZZY_MIN = 0.6;
 // 查询词去重后的 gram 数必须≥4：否则 "zzzz不存在" 只剩 [不存,存在] 两个 gram，
@@ -209,12 +225,44 @@ export function rankPage(body, pageName, queryWords) {
     }
     return { kind: 'exact', matched: exact, score, overlap, ratio, via };
   }
-  const qGramCount = new Set(queryWords.flatMap((w) => ngrams(String(w).toLowerCase()))).size;
-  if (qGramCount >= FUZZY_MIN_GRAMS && ratio >= FUZZY_MIN)
+  const fuzzyWords = queryWords.filter(hasCJK);
+  const qGramCount = new Set(fuzzyWords.flatMap((w) => ngrams(String(w).toLowerCase()))).size;
+  if (fuzzyWords.length && qGramCount >= FUZZY_MIN_GRAMS && ratio >= FUZZY_MIN)
     return { kind: 'fuzzy', matched: [], score: ratio * 10, overlap, ratio, via: { tag: [], title: [], body: [] } };
   return null;
 }
 
+/**
+ * 给候选词按「主题级强度」打分，供 hint 挑词用。
+ *
+ * 为何需要（2026-09-17 实测）：hint 原取词是 `keywords()` 保序 + `slice(0,2)` ——
+ * 拿的是**最前面**的两个词，没有任何质量信号。而 todo 行以
+ * `- [ ] [进行中] <任务id> [[作者]] — 描述` 开头，于是任务 id 和作者名
+ * 稳定占据前两位，提示语变成 `abs query queryhint-noise tester 进行`。
+ * 实测这三个词的强度全为 0~1（noise 0 命中 / 进行 1 命中），等于没提示。
+ *
+ * 尺子 = tag / 页名级命中数（rankPage 的 via.tag / via.title）。
+ * 为何不用「正文命中数」：正文子串命中在 44 页图谱上随口一词就有十几页
+ * （实测 store 16、覆盖 18），不区分好坏；tag/页名是人工提炼的主题信号。
+ * 实测分离度：hook 6 / todo 4 / lock 2  vs  queryhint-noise 0 / 进行 0。
+ *
+ * @param {{name:string,body:string}[]} pages
+ * @param {string[]} words
+ * @returns {Map<string, number>} 词 → 主题级命中数
+ */
+export function topicStrength(pages, words) {
+  const out = new Map();
+  for (const w of words) {
+    let n = 0;
+    for (const p of pages) {
+      const r = rankPage(p.body, p.name, [w]);
+      if (r && (r.via.tag.length || r.via.title.length)) n++;
+    }
+    out.set(w, n);
+  }
+  return out;
+}
+
 /** 取页正文的摘要：优先 frontmatter 的 description，退化到首个非标题行。 */
 export function digest(body, maxLen = 200) {
   const lines = String(body || '').split('\n');

package/src/store.js

@@ -7,7 +7,7 @@ import { requireUser, atTag, getUser } from './userconfig.js';
 import { stripStateMark, ensureStateMark, normalizeTodo, addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, setStateMark, TASK_STATES, insertDoneGrouped, idOfTaskLine, archiveDoneInText, upsertArchiveSection, DONE_KINDS, withDoneKind, doneKindOf, doneDateOf, collapseDone, SEC, rebuildStructure } from './todo.js';
 import { editFile, SKIP } from './lock.js';
 import { appendWrapup, strandedFor } from './wrapup.js';
-import { keywords, pickRelevant, renderRelevant, recentFiles, rankPage } from './relevant.js';
+import { keywords, pickRelevant, renderRelevant, recentFiles, rankPage, topicStrength } from './relevant.js';
 
 // ---------- init: 建 .brain/ 骨架 ----------
 const BRAIN_DIRS = ['entities', 'concepts', 'sources', 'syntheses', 'sessions'];
@@ -400,19 +400,40 @@ export function extractBlocks(todoText) {
  * 且无法按需求变化调整词。正确做法是把词准备好，查询仍由调用方发。
  *
  * 词从两个环境事实推：活跃 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) {
+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);
-  // 只取 3 个：英文词优先（中文 2-gram 单看无意义）
-  const en = kws.filter((k) => /^[a-z][a-z0-9_-]+$/.test(k));
-  const zh = kws.filter((k) => !/^[a-z][a-z0-9_-]+$/.test(k));
+  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 = [

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

@@ -1,179 +0,0 @@
----
-name: abs-bug-hunter
-description: 排查 bug 的流程纪律 —— 先列假设再动手，用数据定位，修根因。排查完把踩坑写进 .brain/。
----
-
-# Bug 排查方法论
-
-## 核心原则
-
-**不凭空猜测，用数据说话。但数据不是终点 —— 先复现，再定位，再理解根因。**
-
-最常见的失败：把"能复现"当成"已定位"。定位到出错的**位置** ≠ 找到**根因**。
-改症状不改根因，换一批数据就复发。
-
-## 第 -1 步：列假设（不能跳过）
-
-**触发**：用户报了症状（"打不开""报错了""不对"），但没给一手错误信息。
-
-**这一步在"复现"之前**，因为拿不到报错时，"先复现"会逼你造假。
-
-### 自造证据 —— 最毒的一类错误
-
-**真实案例**：只有一个假设时，它要么被证实要么思路断掉 —— 于是自己造一个输入去测：
-
-```
-编了个接口名 app.init → curl 测出 404 → "我测出来的，是事实"
-→ 推出"nginx 没配 PATH_INFO"
-→ 用户纠正后，重跑同一实验、得到同一 404 → 坚信自己没错
-```
-
-**为什么最毒**：下游全程都是真的（404 真、命令真跑过）。唯一假的那环在**最上游**，
-且已消失在过程里 → 所以"再验证一次"救不了，重跑同假输入得同真输出。
-
-### 所以
-
-1. **开局列 ≥2 个假设**（代码 / 配置 / 构建产物 / 缓存 / 第三方）。
-   只列一个 = 逼自己去证实它 = 造证据的动力。
-2. **每个假设配反证条件**：什么现象出现就认它错。
-   反证条件里要写明**能从代码里读到的真实名字**，编造的自动不能用。
-3. **卡住两轮就换假设**，不是在同一假设上加细节。
-4. **领域外的先声明无取证能力**（构建产物在不在 / 缓存 / 第三方后台行为），
-   要用户提供事实，**不要脑补**。
-
-**结论所依据的每个具体名字（接口/字段/报错文本/路径）必须指得出处（文件:行）。**
-指不出的只能标"推测"，**不得当证据用**。
-
-> **为什么多假设能防造假**：单假设必须被证实，否则思路断 → 有动机造。
-> 多假设下，"支持了 A" ≠ "就是 A"（B/C/D 还没排除）→ 假证据推不出结论，造它就没意义。
-
-## 第 0 步：复现
-
-没有稳定复现，后面全是猜。
-
-- 复现的必要条件是什么？哪个输入/操作/环境触发？
-- 100% 复现还是偶发？偶发先找触发模式（特定数据/时机/顺序）。
-- 有现成错误栈吗？**错误信息 + 行号是最便宜的定位入口。**
-
-**给 Bug 起个名字**（一句话描述 + 触发条件）。卡住时回来核对是否还在同一个 Bug 上。
-
-## 第一步：定位范围 —— 改动了什么
-
-Bug 不会凭空出现。先查最近的改动：
-
-```bash
-git diff HEAD~3 --stat           # 改了哪些文件
-git log -p -S '可疑字段/函数名'   # 谁改过这段
-git blame <file> -L <行号,行号>   # 定位到具体某行
-```
-
-问自己：这次新增/修改了什么？涉及哪些文件？哪个最可能影响出问题的地方？
-
-**别排查无关代码。**
-
-## 第二步：让数据说话
-
-不猜，打印出来看。
-
-- **打印关键数据，不要只打印"到了这里"** —— 要打印实际的变量值、类型、入参出参。
-- **二分法**：在可疑链路上隔几层插日志，先跑一遍看哪段有数据、哪段没有，
-  范围砍半再往里加。比一次打满所有层更快收敛。
-- **带唯一前缀**（如 `[BUG-01]`）：日志里 grep 一次看到全链路顺序。
-- 怀疑并发/时序时，打时间戳与调用来源。
-
-## 第三步：顺藤摸瓜
-
-从用户操作出发，沿调用链一层层往下：入口 → 路由 → 中间件 → 业务层 → 数据层 → 存储。
-
-**每一层打印关键数据，找到数据从正确变为错误的那一层 —— bug 就在那一层。**
-
-## 第四步：找根因，不只修症状
-
-修复前回答：
-
-- 为什么数据在这一层变错了？**逻辑错误**（判断写反/取错字段）、
-  **类型错误**（null/数组/对象混用）、还是**数据本身脏**（上游写入时就错）？
-- 根因若在上游，这里 patch 只是挡一下 —— 应该去修上游，或在入口统一兜底。
-
-**修一层，不改所有调用点**：如果多个地方调用同一函数，只在出问题的调用点打补丁，
-其他调用点照样坏。**在共享函数里修一次，是所有调用点的最小修复。**
-
-## 第五步：验证修复
-
-不要凭空验证。**先拿第 0 步的复现条件重跑，必须看到它失败** ——
-没失败就说明你修好了但没复现过，或者复现条件记错了。
-不先看到 fail，就无法区分"修好了"和"根本没坏过"。
-改完再看它变 pass，三层都要过：
-
-| 层 | 查什么 |
-|---|---|
-| **修好了** | 复现路径不再报错，输出正确 |
-| **没修坏** | 相关正常路径仍正常（回归） |
-| **边界还在** | 边缘输入（空值/超大值/并发/重复提交）没引入新洞 |
-
-确认无误后再删调试日志。
-
-## 排查完：写进 .brain/
-
-**这一步是 `abs-` 前缀的意义 —— 排查的结论不写下来，下个会话会重踩同一个坑。**
-
-```bash
-abs note "一句话结论" --when "什么时候该看这条"
-```
-
-值得写的（**能从代码 grep 到的不写**）：
-
-| 写什么 | 例 |
-|---|---|
-| **假象的根因** | "报错位置是 A，真因在 B 的写入侧" |
-| **判据** | "统计硬切率 >30% 即确诊，别去调 prompt" |
-| **反直觉处** | "慢的不是读写，是 node 启动" |
-| **排查路径** | "先查写入侧，别先怪模型" |
-
-不值得写的：报错原文（日志里有）、修好的代码（git 里有）、通用常识。
-
-**如果是反复踩的坑**，排查结束后提成硬规则：
-
-```bash
-abs rule add "靠提醒才能工作的功能，该删不该补"
-```
-
-## 常见陷阱
-
-| 陷阱 | 正确做法 |
-|------|----------|
-| 凭经验猜位置 | 先复现 + 看日志/打印 |
-| 只看代码不运行 | 打印运行时的实际数据 |
-| 一次改很多地方再测 | 改一处、验证一处 |
-| 修症状不修根因 | 追问"为什么这层数据变了" |
-| 只验证出错路径 | 复现 + 回归 + 边界 |
-| 忘记删调试代码 | 确认后清理所有打印 |
-| 只在本地验证 | 确认部署的代码/数据一致 |
-| 偶发当成必然 | 先找触发模式，别用单样本下结论 |
-| 排查完不落盘 | 提一条 `abs note`，反复踩的提 `abs rule` |
-
-## 兜底：卡住时
-
-排查 >20 分钟没进展，不硬扛，回流程检查：
-
-1. **Bug 描述还准吗？** 新观察是否改变了问题定义。
-2. **复现还稳定吗？** 换个触发样本还出现吗。
-3. **漏看日志了吗？** grep 全量（不只最近的），可能早期就报过错。
-4. **改动范围查全了吗？** 只看 HEAD~3 会漏分支合并、配置、部署差异。
-5. **要不要问人？** 这条功能最近谁改的、意图是什么，可能一句话点醒。
-6. **向上游看一层。** 来源方是否也变了，不只是消费方的问题。
-
-## 收尾：结论要明确
-
-**不许**："可能是 X，也可能是 Y，建议排查一下" —— 这是把判断推回给用户。
-
-**必须**给出：
-
-1. **当前结论**（是什么 / 或"未定位"）
-2. **置信度与依据**（哪来的证据 / 还是只是推测）
-3. **下一步具体动作**（跑什么、看什么、要用户提供什么）
-
-"未定位"是合法输出，但必须配一句"**需要你提供 X**"（具体到要什么），
-不能只说"无法确定"就结束。
-
-> 与第 -1 步同一根因：**模糊化是逃避判断。** 要么给结论 + 依据，要么明确索取证据。