@fanchao8609/agent_brain_sync 1.9.8 → 1.10.0

package/hooks/abs.pi.ts

@@ -10,10 +10,10 @@
  * 已删除（2026-09-18）：收尾注入本身（agent_end + sendUserMessage deliverAs=followUp）。
  *   实报「每次干活干一会出来, 任务就中断了」。两次同一个根因：
  *   **往对话里插一句话本身就是设计错误，不是频率问题** —— 改守卫(每轮→每会话)治不了它。
- *   别再加回来。素材锚点(before_agent_start/turn_end)随注入一起删除, 已无消费方。
+ *   别再加回来（指 sendUserMessage 注入；静态 system prompt 内容不在此列，见下方 todo 指引）。
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
-import { appendFile, mkdir, stat } from "node:fs/promises"
+import { appendFile, mkdir, readFile, stat } from "node:fs/promises"
 import { homedir } from "node:os"
 import { join } from "node:path"
 import { spawn } from "node:child_process"
@@ -57,21 +57,550 @@ async function findBrain(cwd: string): Promise<string | null> {
  */
 let agentEndSeen = false
 
+/** “刚才调的是 todo 工具”标记 —— 由 tool_call 置位、tool_execution_end 消费。
+ * 同样在模块级，理由同上（闭包 flag 在重复注册时不共享）。 */
+let pendingTodoTool = false
+
 /** 会话边界重置埋点状态。
  *  不重置 → 同进程第二个会话继承 true 永久不留痕（2026-09-13 实测过的坑）。 */
 function resetThrottle(): void {
   agentEndSeen = false
+  pendingTodoTool = false
+}
+
+// ---------------------------------------------------------------------------
+// todo 及时性验证（2026-10-03）：静态 system prompt 指引
+// ---------------------------------------------------------------------------
+// 待验证假设：abs 的 todo「不及时」不是工具问题，是**触发机制**问题 ——
+// `abs_task` 的指引只存在于工具 description 里，模型常忽略；而 pi 原生工具的
+// `promptGuidelines` 会进 system prompt 的 Guidelines 段，每轮都在。
+//
+// 与历史两次失败做法的**分界线**（必须守住）：
+//   删掉的两次都是 `sendUserMessage(deliverAs:"followUp")` —— **往对话里插话**，
+//   抢走一个 turn、打断用户。本次是**静态 prompt 内容**：不新增消息、不抢 turn、
+//   不产生任何对话条目，只是连同其它 Guidelines 一起渲染进 system prompt。
+//   若将来要扩展，也绝不能退化成插话。
+//
+// 关掉即设 ABS_TODO_GUIDE=0。
+// 工具名写 `abs_task`（不带 mcp__abs__ 前缀）—— 2026-10-03 审查发现：MCP 默认
+// exposure=codemode，模型侧看到的就叫 abs_task；写错名字等于让模型去找不存在的工具。
+const TODO_GUIDELINES = [
+  'Use `abs_task` to track multi-step work **before** you start it, not after: on the first file edit of a task, call action "start" with a short id.',
+  'Mark a task "done" immediately when it finishes — never batch completions at the end of a session.',
+  'Before starting a task, record the checkpoint with action "note" (which file, which step) so a later session can resume.',
+]
+
+/** 当前项目是否有 .brain 图谱 —— 有才加指引（没图谱的项目里这指引是噪音）。
+ *
+ * 为何不用工具名判断（2026-10-03 两次实测都错）：
+ *   ① event.systemPromptOptions.selectedTools 在 handler 里是**基线值**，真实表要等
+ *      handler 之后（agent-session.js:1573）才回填 → 实测 tools=31 无 abs。
+ *   ② 改用 pi.getActiveTools() 仍为假 —— MCP 默认 exposure=codemode，工具**本就
+ *      不进 active 工具表**（且 pi 的 MCP 是懒连接，实测提示 "lazy: from cache, not
+ *      connected yet"）。
+ * 结论：判断「abs 能不能用」不该看工具注册表，直接看**项目有没有 .brain/**。 */
+async function hasBrain(cwd: string): Promise<boolean> {
+  try {
+    const st = await stat(join(cwd || process.cwd(), '.brain'))
+    return st.isDirectory()
+  } catch {
+    return false
+  }
+}
+
+function injectTodoGuidelines(options: any): boolean {
+  if (String(process.env.ABS_TODO_GUIDE || '') === '0') return false
+  const list: string[] = options.promptGuidelines || (options.promptGuidelines = [])
+  for (const g of TODO_GUIDELINES) {
+    if (!list.includes(g)) list.push(g)
+  }
+  return true
+}
+
+// ---------------------------------------------------------------------------
+// todo 面板（2026-10-03）：把 .brain/todo.md 的未完成任务显示在编辑器上方
+// ---------------------------------------------------------------------------
+// 纯展示层：只读 todo.md，不写任何东西。数据源就是 abs 自己的看板 —— 不做第二套状态。
+// 与 rpiv-todo 的区别：那个把状态存会话 transcript（跨会话丢失），我们用磁盘文件（可续接）。
+// 关掉即设 ABS_TODO_PANEL=0。
+const PANEL_KEY = "abs-todo-panel"
+const PANEL_MAX_ROWS = 10
+
+// 标题后缀昵称池（2026-10-03 用户提供）—— 每次**启动会话**随机抽一条，会话内保持不变。
+// 不能每帧随机（panel 每帧都重渲染，那样会疯狂闪烁）。
+const USER_NICKNAMES = [
+  '🛌 昼伏夜出型',
+  '😴 沾枕头就醒',
+  '🌙 熬夜当修仙',
+  '⏰ 闹钟十连败',
+  '🧟 永远睡不醒',
+  '☕ 靠咖啡续命',
+  '🧋 靠奶茶续命',
+  '🍚 干饭第一名',
+  '🥘 吃辣只敢微辣',
+  '🍳 炸厨房常客',
+  '🥗 间歇性减肥',
+  '🍜 深夜爱放毒',
+  '🧊 冰镇式养生',
+  '⌨️ 键盘上摸鱼',
+  '🐟 划水大师',
+  '💻 复制粘贴大师',
+  '🚽 带薪上厕所',
+  '🕕 到点就跑',
+  '📅 明天再说吧',
+  '🐷 坚决不加班',
+  '😇 表面在微笑',
+  '🤯 内心已掀桌',
+  '💸 月月过路财神',
+  '🏦 隐形负翁',
+  '🤑 转发锦鲤求暴富',
+  '📉 钱包越来越瘦',
+  '🛒 购物车首富',
+  '📱 网上冲浪选手',
+  '🛸 意念回复专家',
+  '📞 电话一响就慌',
+  '🙈 已读绝不回',
+  '🤝 只管埋头夹菜',
+  '📝 收藏从不用',
+  '📚 学了就忘',
+  '🧠 记忆力七秒',
+  '🔋 1%才去充电',
+  '🛍️ 拆快递狂魔',
+  '🧳 云旅游专家',
+  '🏋️ 办卡只去洗澡',
+  '🚶 步数常年垫底',
+  '💇 秃飞猛进',
+  '🏴‍☠️ 飞翔荷兰人',
+  '🐌 蜗牛速度选手',
+  '🦥 躺平专业户',
+  '🎮 打完这把就睡',
+  '🍿 吃瓜第一线',
+  '🔍 搜索两小时',
+  '🧩 爱钻牛角尖',
+  '💤 梦里也在编程',
+  '🚀 明早一定做',
+  '🧘 边熬夜边养生',
+  '📺 刷剧不眨眼',
+  '🎧 单曲循环中',
+  // ── 职场抱怨（2026-10-03 第二批）──
+  '🫠 靠不住选手',
+  '🧯 专业背锅侠',
+  '🪑 会议室钉子户',
+  '📎 工具人本人',
+  '🫥 存在感为零',
+  '🥄 打杂一把好手',
+  '🧮 人形Excel',
+  '📋 需求搬运工',
+  '🔧 万能补丁匠',
+  '🗣️ 会议两小时',
+  '💬 一言不合拉会',
+  '📊 对齐一整天',
+  '🌀 讨论没结论',
+  '🎯 追需求成瘾',
+  '📝 纪要孤儿',
+  '🔥 排期永远紧',
+  '⏳ 催到怀疑人生',
+  '🌃 下班天已黑',
+  '📆 周末待命',
+  '🚨 临时插需求',
+  '🧨 上线前改需求',
+  '📈 汇报全靠编',
+  '🎤 PPT大师',
+  '🤡 背锅第一名',
+  '🫡 收到马上办',
+  '🙃 领导说得对',
+  '👏 掌声最热烈',
+  '🏓 甩锅乒乓球',
+  '🙋 不背锅侠',
+  '📮 抄送战斗机',
+  '🧊 已读不回群',
+  '🔕 消息免打扰',
+  '🪫 电量剩5%',
+  '🧓 入行即养老',
+  '🫩 心力耗尽',
+  '😮‍💨 叹气专业户',
+  '🪦 激情已入土',
+  '📤 简历常年挂着',
+  '🧳 随时准备跑路',
+  '💼 骑驴找马中',
+  '🪙 谈薪谈不动',
+  '🥲 涨薪等明年',
+  // ── 自嘲（2026-10-03 第三批）──
+  '🎲 编程全靠蒙',
+  '🙏 AI救我狗命',
+  '🐛 Bug制造机',
+  '🔮 玄学调参',
+  '📿 面向祈祷编程',
+  '🩹 补丁摞补丁',
+  '🤞 能跑就行',
+  '🗿 代码能跑别动',
+  '🎰 随机数人生',
+  '🧙 咒语背诵者',
+  '📖 文档从不看',
+  '⌨️ 只会复制粘贴',
+  '🫠 菜得安详',
+  '🥹 菜狗本狗',
+  '🐣 刚会写Hello',
+  '🧸 删库跑路预备',
+  '🪫 脑子已关机',
+  '🫥 假装很忙',
+  '🎭 专业演技派',
+  '🃏 气氛组组长',
+  '🧊 情绪稳定到麻木',
+  '🐟 摸鱼终身成就',
+  '🛋️ 沙发项目经理',
+  '📺 带薪看视频',
+  '🍵 带薪养生',
+  '💤 工位睡神',
+  '⏳ 明日复明日',
+  '🗓️ 周报最后写',
+  '📉 进度条倒退',
+  '🕳️ 坑是自己挖的',
+  '🧨 技术债主',
+  '💀 穷得响叮当',
+  '📵 社交电池耗尽',
+  '🍼 成年巨婴',
+  '🪞 镜子前叹气',
+  '🧦 袜子不成对',
+  '🥲 笑着活下去',
+]
+
+/** 本会话的昵称 —— 模块级（扩展重复注册时闭包变量不共享，同 agentEndSeen 的坑）。
+ * 空串 = 未抽（或 ABS_TODO_NICK=0 关掉）。 */
+let sessionNickname = ''
+
+/** 抽一条昵称。传 rnd 便于测试注入；默认 Math.random。关掉：ABS_TODO_NICK=0。 */
+export function pickNickname(rnd: () => number = Math.random): string {
+  if (String(process.env.ABS_TODO_NICK || '') === '0') return ''
+  const i = Math.min(USER_NICKNAMES.length - 1, Math.floor(rnd() * USER_NICKNAMES.length))
+  return USER_NICKNAMES[Math.max(0, i)]
+}
+
+/** 解析 todo.md 的 ## Todo 区 —— 只收未完成行（- [ ]），Done 区不计。
+ *
+ * who 不为空时只收“我的任务”：行内有 [[who]] 的，或**完全没标作者**的
+ * （老任务/手写的没标，漏掉比多显示更糟）。标了别人的则不收。
+ *
+ * 断点行（缩进的 ↳）归属到它上一条任务，不单独成条。 */
+export function parseOpenTasks(md: string, max = PANEL_MAX_ROWS, who = ''): {
+  total: number
+  rows: { state: string; id: string; desc: string; note: string }[]
+  hidden: number
+} {
+  // 两阶段：先无过滤地按序解析（断点归属需要“上一条”是原文里真正的前一条），
+  // 再按作者过滤。若边解析边过滤，被滤掉的条目下方的断点会挂到它上面那一条
+  // —— 实测：别人任务的断点会显示在我的任务下面（2026-10-03 审查发现）。
+  type Row = { state: string; id: string; desc: string; note: string; authors: string[] }
+  const parsed: Row[] = []
+  let inTodo = false
+  for (const raw of String(md || '').split('\n')) {
+    const line = raw.trimEnd()
+    if (/^##\s+Todo\s*$/.test(line)) { inTodo = true; continue }
+    if (/^##\s+/.test(line)) { inTodo = false; continue }
+    if (!inTodo) continue
+    // 断点行：`  ↳ 断点: …`（缩进）→ 挂到上一条任务
+    const note = line.match(/^\s+↳\s*断点:\s*(.*)$/)
+    if (note) {
+      const last = parsed[parsed.length - 1]
+      if (last && !last.note) last.note = note[1].trim()
+      continue
+    }
+    // `- [ ] [状态] <id> …`；状态标记可能缺省
+    const m = line.match(/^-\s+\[\s\]\s+(?:\[([^\]]+)\]\s+)?(\S+)\s*(.*)$/)
+    if (!m) continue
+    const state = m[1] || '进行中'
+    const id = m[2]
+    const body = m[3] || ''
+    const authors = [...body.matchAll(/\[\[([^\]]+)\]\]/g)].map((x) => x[1])
+    // 剥掉作者标记（面板上碍眼且无信息量），再取 `—` 后正文
+    const desc = body
+      .replace(/\[\[[^\]]+\]\]/g, '')
+      .replace(/^\s*—\s*/, '')
+      .replace(/\s*\(认领\s*\d{4}-\d{2}-\d{2}\)\s*$/, '')
+      .trim()
+    parsed.push({ state, id, desc, note: '', authors })
+  }
+  const mine = who
+    ? parsed.filter((r) => r.authors.length === 0 || r.authors.includes(who))
+    : parsed
+  const rows = mine.map(({ state, id, desc, note }) => ({ state, id, desc, note }))
+  return { total: rows.length, rows: rows.slice(0, max), hidden: Math.max(0, rows.length - max) }
+}
+
+/** 当前使用者名（读 ~/.abs/config.json 的 user，ABS_USER 环境变量优先）。
+ * 读不到返回空串 —— 那时不做作者过滤（宁可全显示，也别因配置缺失而面板空白）。 */
+async function currentUser(): Promise<string> {
+  const env = String(process.env.ABS_USER || '').trim()
+  if (env) return env
+  try {
+    const dir = process.env.ABS_CONFIG_DIR || join(homedir(), '.abs')
+    const raw = await readFile(join(dir, 'config.json'), 'utf8')
+    const u = JSON.parse(raw).user
+    return typeof u === 'string' ? u.trim() : ''
+  } catch {
+    return ''
+  }
+}
+
+/** 按显示宽度截断（自己实现，不 import @earendil-works/pi-tui）。
+ *
+ * 为何不直接用 pi-tui 的 truncateToWidth（2026-10-03 实测）：那是 pi 内部 alias，
+ * 裸包名只在 pi 的 jiti loader 下能解析 —— 测试环境用原生 node 加载扩展会
+ * ERR_MODULE_NOT_FOUND（实测挂了 6 个测试）。依赖宿主内部 alias 太脆。
+ *
+ * 宽度规则：CJK/全角记 2 列，其余记 1 列。足够让面板不溢出（不能处理 emoji ZWJ 序列，
+ * 但面板里没有—— todo 内容是任务名与说明）。 */
+function dispWidth(s: string): number {
+  let w = 0
+  let i = 0
+  while (i < s.length) {
+    const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i))
+    if (m) { i += m[0].length; continue }
+    const cp = s.codePointAt(i) || 0
+    const ch = String.fromCodePoint(cp)
+    i += ch.length
+    // 常见全角/CJK 区间（足以覆盖中文任务名）
+    const wide =
+      (cp >= 0x1100 && cp <= 0x115f) ||
+      (cp >= 0x2e80 && cp <= 0xa4cf) ||
+      (cp >= 0xac00 && cp <= 0xd7a3) ||
+      (cp >= 0xf900 && cp <= 0xfaff) ||
+      (cp >= 0xfe30 && cp <= 0xfe6f) ||
+      (cp >= 0xff00 && cp <= 0xff60) ||
+      (cp >= 0xffe0 && cp <= 0xffe6) ||
+      (cp >= 0x1f300 && cp <= 0x1f64f) ||
+      (cp >= 0x1f900 && cp <= 0x1f9ff)
+    w += wide ? 2 : 1
+  }
+  return w
+}
+
+/** 去掉 ANSI 转义序列（\x1b[...m 等），否则宽度计算会把颜色码也算进去。 */
+function stripAnsi(s: string): string {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1b\[[0-9;]*m/g, '')
+}
+
+/** 控宽截断：超宽则尾部换省略号（省略号算 1 列）。
+ *
+ * 注意：入参可能含 ANSI 颜色码（我们的 head 就是 fg() 拼的）。颜色码占 0 列，
+ * 必须先剥掉再量宽 —— 否则每行都会被误判超宽而截断。
+ * 截断后不再恢复颜色（该行尾会失去颜色，但省略号前的内容色仍在）—— 可接受，
+ * 因为只有超长行才会走到这里。 */
+function clipToWidth(s: string, width: number): string {
+  if (width <= 0) return ''
+  if (dispWidth(stripAnsi(s)) <= width) return s
+  const keep = width - 1
+  let out = ''
+  let w = 0
+  let i = 0
+  // 逐字符扫描，遇到 ANSI 序列原样跳过（不计宽）
+  while (i < s.length) {
+    const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i))
+    if (m) { out += m[0]; i += m[0].length; continue }
+    const cp = s.codePointAt(i) || 0
+    const ch = String.fromCodePoint(cp)
+    i += ch.length
+    const cw = dispWidth(ch)
+    if (w + cw > keep) break
+    out += ch
+    w += cw
+  }
+  return out + '…'
+}
+// ---------------------------------------------------------------------------
+// “进行中”行的迷你动画（2026-10-03 用户需求）：三个小符号依次由空心变实心。
+// 帧宽固定 3 列 —— 宽度不变才不会让面板每帧抖动（这也是不用 ⠋⠙⠹ 那种 spinner 的原因：
+// 那个只闪一个符，用户明确要的是“三个点依次点亮”）。
+// 平铺 6 帧：亮→全亮→退回（呼吸感），而不是全亮后硬跳回全空。
+const TODO_ANIM_FRAMES = ['○○○', '●○○', '●●○', '●●●', '●●○', '●○○']
+const TODO_ANIM_MS = 250
+
+/** 动画相位（每 tick +1）。模块级 —— 同 agentEndSeen，闭包 flag 在重复注册时不共享。 */
+let animPhase = 0
+let animTimer: ReturnType<typeof setInterval> | undefined
+
+/** 启动/保持动画定时器。重复调用不会叠加（已存在则不动）。
+ * getTui 是为了每 tick 拿**当前**的 tui 引用 —— widget 可能因刷新被重建，
+ * 持旧的引用会调到一个已被丢弃的 renderer。 */
+function startAnimTimer(getTui: () => any): void {
+  if (animTimer) return
+  animTimer = setInterval(() => {
+    animPhase++
+    try { getTui()?.requestRender?.() } catch {}
+  }, TODO_ANIM_MS)
+  // 别阻止进程退出（扩展是宿主进程的一分子，定时器不该吊住事件循环）
+  ;(animTimer as any)?.unref?.()
+}
+
+function stopAnimTimer(): void {
+  if (animTimer) { clearInterval(animTimer); animTimer = undefined }
+}
+
+/** 取当前动画帧（phase 每 tick +1，由定时器驱动）。非进行中的行不传 phase（不显示）。 */
+export function todoAnimFrame(phase: number): string {
+  const n = TODO_ANIM_FRAMES.length
+  const i = ((Math.floor(phase) % n) + n) % n
+  return TODO_ANIM_FRAMES[i]
+}
+
+export function renderPanelLines(
+  data: { total: number; rows: { state: string; id: string; desc: string; note: string }[]; hidden: number },
+  who: string,
+  width: number,
+  fg: (color: string, s: string) => string,
+  animPhase = -1,
+  nickname = '',
+): string[] {
+  if (data.total === 0) return []
+  const colorOf = (state: string): string => (state === '滞留中' ? 'muted' : state === '讨论中' ? 'dim' : 'accent')
+  const lines: string[] = []
+  // 上描边：一条深灰横线，把面板与上方内容分开。
+  // 留 1 列余量 —— 终端对“恰好占满宽度”的行有时会折行（各终端行为不一致）。
+  lines.push(fg('dim', '─'.repeat(Math.max(0, width - 1))))
+  // 昵称附在作者名后（会话内固定，启动时随机抽）。
+  const whoPart = who ? who + (nickname ? ` · ${nickname}` : '') : nickname
+  const title = whoPart ? `📋 todo (${data.total}) — ${whoPart}` : `📋 todo (${data.total})`
+  lines.push(clipToWidth(fg('accent', title), width))
+
+  const lastIdx = data.rows.length - 1
+  data.rows.forEach((t, i) => {
+    // `└─` 只给最后一条 —— 不管它有没有断点。
+    // （2026-10-03 审查修正：原条件 `i === lastIdx && !t.note` 会让“末条带断点”时
+    //  全篇没有 └─ 收尾，断点行的 │ 又延伸到视觉底部，看起来像列表被截断。）
+    const isLast = i === lastIdx
+    const branch = isLast ? '└─' : '├─'
+    // 进行中的行带一个小动画（其余行不加，避免满屏都在跳）
+    const anim = t.state === '进行中' && animPhase >= 0 ? ' ' + fg('accent', todoAnimFrame(animPhase)) : ''
+    const head = `${fg('dim', branch)} ${fg(colorOf(t.state), `[${t.state}]`)} ${fg('text', t.id)}${anim}`
+    const desc = t.desc ? ` ${fg('dim', '—')} ${fg('muted', t.desc)}` : ''
+    lines.push(clipToWidth(head + desc, width))
+    if (t.note) {
+      // 断点行：挂在父任务下。末条时用空格对齐（└─ 下方无续）；否则用 │ 延伸。
+      const cont = isLast ? '  ' : fg('dim', '│ ')
+      lines.push(clipToWidth(`${cont} ${fg('dim', '↳ ' + t.note)}`, width))
+    }
+  })
+
+  if (data.hidden > 0) lines.push(clipToWidth(fg('dim', `  +${data.hidden} more`), width))
+  return lines
+}
+async function refreshTodoPanel(ui: any, cwd: string): Promise<void> {
+  if (String(process.env.ABS_TODO_PANEL || '') === '0') return
+  if (!ui || typeof ui.setWidget !== 'function') return
+  try {
+    if (!(await hasBrain(cwd))) { ui.setWidget(PANEL_KEY, undefined); stopAnimTimer(); return }
+    const md = await readFile(join(cwd, '.brain', 'todo.md'), 'utf8')
+    const who = await currentUser()
+    const data = parseOpenTasks(md, PANEL_MAX_ROWS, who)
+    if (data.total === 0) { ui.setWidget(PANEL_KEY, undefined); stopAnimTimer(); return }
+    // factory 形式：render(width) 每帧拿真实宽度 → 按宽度截断，不再断字。
+    // 动画：phase 存在模块级，render 时读当前值；定时器只在本帧重绘，不重建 widget。
+    let tuiRef: any = null
+    ui.setWidget(
+      PANEL_KEY,
+      (tui: any, theme: any) => {
+        tuiRef = tui
+        return {
+          render: (width: number) =>
+            renderPanelLines(
+              data,
+              who,
+              width,
+              (c: string, s: string) => theme.fg(c, s),
+              animPhase,
+              sessionNickname,
+            ),
+          invalidate: () => {},
+        }
+      },
+      { placement: 'aboveEditor' },
+    )
+    // 只在真有“进行中”任务时跑定时器 —— 否则白刷 CPU（无动画可播）。
+    const needAnim = data.rows.some((t) => t.state === '进行中')
+    if (needAnim) startAnimTimer(() => tuiRef)
+    else stopAnimTimer()
+  } catch {
+    try { ui.setWidget(PANEL_KEY, undefined) } catch {}
+    stopAnimTimer()
+  }
 }
 
 export default function absPiHook(pi: ExtensionAPI): void {
   // 埋点状态同上，故意声明在**模块级**（不在被反复调用的工厂函数里）。
   resetThrottle()
 
-  pi.on("session_start", (event: any, _ctx: any) => {
+  pi.on("session_start", (event: any, ctx: any) => {
     resetThrottle()
+    // 本会话的随机昵称 —— 在这里抽一次（不是每帧抽，否则面板会疯狂闪）。
+    // 每次 session_start（startup/reload/new/resume/fork）重抽 → “每次打开 pi 都是随机的”。
+    sessionNickname = pickNickname()
+    logHook(`session_start nickname=${sessionNickname || '(off)'}`).catch(() => {})
+    // 启动/重载时就画出面板（reason=startup|reload|new|resume|fork）。
+    // 时序：pi 在 session_start 时已给 ctx.ui（无 UI 时是 noOp，调了不报错），
+    // 但设 setWidget 需真的 TUI —— 故用 hasUI 挡一下并留痕，便于判定“没显示”的原因。
+    const cwd = (ctx && ctx.cwd) || process.cwd()
+    if (ctx && ctx.hasUI) {
+      refreshTodoPanel(ctx.ui, cwd)
+        .then(() => logHook(`session_start panel drawn reason=${event?.reason}`).catch(() => {}))
+        .catch(() => logHook(`session_start panel error reason=${event?.reason}`).catch(() => {}))
+    } else {
+      logHook(`session_start panel skipped no_ui reason=${event?.reason}`).catch(() => {})
+    }
     return logHook("session_start").catch(() => {})
   })
 
+  // 面板实时刷新（两事件配合）—— 为何不能只用其中一个：
+  //   实测（2026-10-03）MCP 工具在 tool_execution_end 里的 toolName 是代理入口名
+  //   `mcp__abs`，**不是子工具名**，且该事件不带 args → 无法从它分辨是不是 abs_task。
+  //   而 tool_call 带 input，能从里面认出目标工具，但它在**执行前**触发（此刻 todo.md 还没变）。
+  // 故：tool_call 认出“刚才调的是 todo 工具”→ 置标记；tool_execution_end 看到标记就刷 → 清标记。
+  // 始终保留 turn_end 兜底（实测每条 assistant 消息都触发，约 4 秒一次）。
+  // 标记在模块级（重复注册时闭包 flag 不共享 —— 见 agentEndSeen 的注解）。
+  pi.on("tool_call", (event: any) => {
+    const name = String(event?.toolName || '')
+    const input = event?.input || {}
+    // 两种形态：① MCP 代理入口 mcp__abs + input.tool=abs_task；② 直接工具名 abs_task
+    const target = String(input?.tool ?? input?.name ?? '')
+    if (/abs_(task|board)/.test(name) || /abs_(task|board)/.test(target)) {
+      pendingTodoTool = true
+      logHook(`tool_call todo_tool name=${name} target=${target || '-'}`).catch(() => {})
+    }
+  })
+
+  pi.on("tool_execution_end", (_event: any, ctx: any) => {
+    if (!pendingTodoTool) return
+    pendingTodoTool = false
+    logHook(`tool_execution_end panel refresh after todo tool`).catch(() => {})
+    refreshTodoPanel(ctx?.ui, (ctx && ctx.cwd) || process.cwd()).catch(() => {})
+  })
+
+  pi.on("turn_end", (_event: any, ctx: any) => {
+    const cwd = (ctx && ctx.cwd) || process.cwd()
+    logHook(`turn_end panel refresh cwd=${cwd}`).catch(() => {})
+    refreshTodoPanel(ctx?.ui, cwd).catch(() => {})
+  })
+
+  // todo 及时性验证（2026-10-03）：往 system prompt 的 Guidelines 段追加静态条目。
+  // 不新增消息、不抢 turn、不产生对话条目 —— 与删掉的两次注入做法本质不同（见文件头）。
+  // 留一行日志：否则「有没有生效」只能凭感觉，无法验证。
+  pi.on("before_agent_start", (event: any, ctx: any) => {
+    const cwd = (ctx && ctx.cwd) || process.cwd()
+    // 异步 handler：pi 会 await（emitBeforeAgentStart 是 await 的），故可以查盘。
+    return (async () => {
+      try {
+        if (!(await hasBrain(cwd))) {
+          logHook(`before_agent_start todo_guide=off reason=no_brain`).catch(() => {})
+          return
+        }
+        const ok = injectTodoGuidelines(event?.systemPromptOptions)
+        logHook(`before_agent_start todo_guide=${ok ? 'on' : 'off'} cwd=${cwd}`).catch(() => {})
+      } catch (e: any) {
+        logHook(`before_agent_start error=${e?.message || 'unknown'}`).catch(() => {})
+      }
+    })()
+  })
+
   // 收尾注入已停用（2026-09-18）：sendUserMessage(deliverAs:"followUp") 会在每轮
   // agent_end 抢一个 follow-up turn，用户实报「每次干活干一会出来, 任务就中断了」。
   //
@@ -88,6 +617,7 @@ export default function absPiHook(pi: ExtensionAPI): void {
   })
 
   pi.on("session_shutdown", (_e: any, ctx: any) => {
+    stopAnimTimer() // 面板没了，动画定时器必须一起停（否则残留定时器白刷已丢弃的 tui）
     snapshotWrapup((ctx && ctx.cwd) || process.cwd())
     logHook("session_shutdown").catch(() => {})
   })

package/package.json

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

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

@@ -1,413 +1,185 @@
 ---
 name: abs-agent-brain-sync
-description: abs (agent-brain-sync) 跨会话 AI 编码记忆与任务续接。开场续接状态(abs load/MCP abs_load)，干活中任务/经验实时落盘(abs_task/abs_note)，需要收尾时才走收尾循环。解决会话无状态：经验/进度/坑碎片化、重开失忆。
+description: abs (agent-brain-sync) 跨会话记忆与任务续接。适用于「开工续接状态」「沉淀会话收获」「任务登记不丢」「经验落成知识页」「图谱体检」等任务。
 ---
 
 # abs — 跨会话记忆 (agent-brain-sync)
 
 ## 最高优先：触发总则（凌驾本文所有流程）
 
-**关键词不是触发器，意图才是。**
+**关键词不是触发器，意图才是。**句子里出现 abs 词（收尾/todo/沉淀/load/log/note）不等于要执行 abs 动作：谈论、提问、吐槽、定规则（"太啰嗦""这个设计怎样"）**只回应，不执行动作**；明确让我做事才执行。
 
-句子里出现 abs 词（收尾/todo/沉淀/提示/load/log/note）**不等于**要执行 abs 动作。
+- 拿不准时**先问**。规则变更（"以后简短点"）写入本文，不执行动作。
+- 输出简短：收尾/提示/todo 汇报一两句。本总则适用于所有工具。
 
-| 用户的意思 | 做什么 |
-|---|---|
-| 谈论、提问、吐槽、定规则（"太啰嗦""要简短""这个设计怎样"） | **只回应，不执行动作** |
-| 明确让我做事（"收尾""记一下""去做"） | 执行 |
-
-**判断依据是整段话的意图，不是里面出现过哪个词。**
-
-反例（真实发生）：用户说"尽量简短的汇报" —— 那是在**定规则**，不是在**下命令**；
-被误当成指令跑了一次收尾。
+## 命令速查
 
-推论：
-- 拿不准时**先问**，不要靠关键词直接动手。
-- 规则变更（"以后简短点"）写入本文，**不执行动作**。
-- 输出简短：收尾/提示/todo 汇报尽量一两句，不写小作文。
-- 本总则适用于所有工具，不限 abs。
-
-把 AI 编码经验从会话沙盒里救出来。每个会话都是无状态的——Cl​aude、Op​enCode、Cursor
-各开一堆会话，经验/进度/踩坑全碎片化，重开像失忆。本技能用一个放**项目根目录**、
-Obsidian 可直接打开的 Markdown 图谱（`.brain/`）做统一落点。
-**骨架/任务/暂存/检索/体检走 abs 工具（不手工建骨架、不手工登记任务）；深提炼（把暂存经验
-写成 concept/entity 页）必须手工——那是判断力，abs 不替你判断什么值得沉淀。**
-
-## CLI 命令速查（`abs`，完整帮助：`abs help`）
+完整帮助：`abs help`。agent 读写优先走 MCP（`abs_load`/`abs_task`/`abs_note`/`abs_query`/`abs_lint`/`abs_rule`）比 bash 跑 CLI 快；`abs wrapup` / `abs teardown-check` 是 hook 内部命令。
+分工：hook 自动记技术日志到 `~/.abs/log/`（不用管）；CLI/MCP 实时落盘；**skill 负责深提炼 + 收尾 + 修 index**。
 
 ```bash
-# 读
-abs load                     # 开机读状态（Rules + 图谱计数 + todo + 最新 log）
-abs todo                     # 看板（Done 折成计数；明细 abs todo --full）
-abs index / abs log          # 完整 index.md / log.md
-abs status                   # 当前项目 + 图谱概要
-abs query <词1> [词2 …]      # 检索 .brain/ 知识页（多词 OR）
-abs resolve <页名或id>       # 反查页面路径（改名后 id 不变）
-abs lint                     # 图谱体检（死链/悬挂/超限/堆积/未提炼/Rules 超限）
-
-# 写
-abs todo add <id> --note "做什么"              # 登记任务（start 同义）
-abs todo note <id> --note "断点/进度"           # 实时落 ↳ 断点 行
-abs todo state <id> --note "进行中|讨论中|滞留中"  # 改状态标记（原地）
-abs todo done <id> [--as 落地|否决|仅方案]      # 完成（默认 落地）
-abs log "完成 X：…"                            # 记一行工作成果（无参=查看）
-abs note "经验一句话" [--tags 坑,docker]        # 经验实时暂存 → sources/
-abs concept <slug> --title "标题" [--tags a,b]  # 建概念页骨架（头/中/尾，只给结构不给内容）
-abs rule [add "一句话"]                        # 读写 index.md 的 ## Rules 硬规则
-
-# 维护
-abs todo archive [--keep-days N] [--dry-run]   # 归档 Done 旧日期组 → sessions/
-abs init [--repair]                            # 建图谱；--repair 只补缺不覆盖
-abs config [set user <名字>]                   # 使用者姓名（写操作需先设）
+abs load                          # 开机读状态；abs query <词> 检索；abs resolve <页名> 反查路径
+abs todo add <id> --note "做什么"   # 登记（note 补断点 / state 改标记 / done 完成）；abs log "完成 X" 记成果
+abs note "经验" [--tags a,b]       # 暂存经验；abs concept <slug> --title "…" 建概念页骨架
+abs rule [add "一句话"]           # 读写 ## Rules；abs lint 体检；abs todo archive 归档；abs init 建图谱
 ```
 
-> **agent 读写优先走 MCP**（`abs_load`/`abs_task`/`abs_note`/`abs_query`/`abs_lint`/
-> `abs_rule`）—— 常驻 ~2ms，比 bash 跑 CLI（每次起 node 进程 27ms）快一个量级。
-> CLI 留给「人手动查看」。`abs wrapup` / `abs teardown-check` 是 hook 内部命令，不需手动调。
-
 ## 触发总入口（每次命中技能，第一步先走这里）
 
-技能被触发（用户问话、开新会话、或说 `abs ...`）时，**第一步永远是下面这条链**，
-然后再看用户真正要什么：
+技能被触发时第一步走这条链，再看用户要什么：
 
-1. **找图谱**：只看**当前目录**是否含 `.brain/`（一个项目一个 `.brain/`）。
-   **不向上搜索**：向上爬会从子目录甚至 vault 一路命中家目录 `~/.brain` 的无关图谱，
-   静默把项目挂错地方。所以必须 cd 到项目根再跑，子目录不会自动归属。
-2. **没有？按意图决定建档与否**：
-   - 用户意图是**沉淀**（收尾/「把这次记下来」）或**即将开工的长期任务**（会跨会话，
-     用词如「帮我做 X / 开工 / 继续开发 / 修 X」）→ **先建档**：`abs init`。别在没图谱时就开写。
-   - 用户是**闲聊 / 一次性问句 / 明说不要建档 / 目录只读** → **不建档**，当普通会话处理，
-     避免在无关项目乱落文件。
-3. **有/刚建好？分析用户意图**，分流：
+1. **找图谱**：只看**当前目录**是否含 `.brain/`。不许向上搜索（会命中 `~/.brain` 的无关图谱，把项目静默挂错），必须 cd 到项目根。
+2. **没有？按意图定建档**：意图是**沉淀**或**即将开工的长期任务**（"帮我做 X / 开工 / 修 X"）→ **先 `abs init`**，别在没图谱时就开写；**闲聊 / 一次性问句 / 明说不要建档 / 只读目录** → 不建档，当普通会话处理。
+3. **有/刚建好？分流**：
 
 | 用户意图 | 走哪 |
 |---|---|
-| 总结经验 / 结束了 / "把这次记下来" | 收尾 Teardown（沉淀） |
+| 总结经验 / 结束了 / "把这次记下来" | 收尾循环（沉淀） |
 | 查询坑 / "我上次怎么解决 X" | `abs query` 检索 |
-| 体检图谱 / `abs lint` | `abs lint` 跑体检 |
-| 开新任务 / 继续开发 / "帮我做 X" | 开场 Init Sync（续接）；**新需求先走下面的受理协议** |
-| 报 bug / 要求加功能 | **受理协议**：先方案 → 再登记 → 问开工（下一节） |
+| 体检图谱 / `abs lint` | `abs lint` |
+| 开新任务 / 继续开发 / "帮我做 X" | 开场 Init Sync（续接）；新需求先走受理协议 |
+| 报 bug / 要求加功能 | **受理协议**：先方案 → 再登记 → 问开工 |
 | 意图不明 / 默认 | **续 todo**：读未完成项开工续做 |
 
-**主心骨**：意图不明且项目有 `.brain/` 时，默认**续 todo**——任何情况下先接上未完成工作，
-不是停在闲聊。
+**主心骨**：意图不明且项目有 `.brain/` 时，默认**续 todo**。
 
 ## 新需求受理协议（bug / 新功能：先方案 → 再登记 → 问开工）
 
-用户报 bug 或要求加功能时，**先别动代码**。三步：
+用户报 bug 或要求加功能时先别动代码，三步：
 
-1. **总结方案**（一屏内，给用户过目）
-   - 需求的准确复述；不确定就写明假设，别猜着做
-   - bug → 根因；功能 → 做法。**有证据给证据，没查到就直说"未定位"**
-   - 要改哪些文件、怎么验证（跑什么、看什么）
-2. **登记 todo**：`abs todo add <id> --note "<一句话需求+关键约束>"`
-   方案里的关键结论（根因/取舍）再 `abs todo note <id> --note ...` 落到断点。
+1. **总结方案**（一屏内，给用户过目）：准确复述需求（不确定就写明假设）；bug 给根因、功能给做法；要改哪些文件、怎么验证。
+2. **登记 todo**：`abs todo add <id> --note "<需求+关键约束>"`；根因/取舍用 `abs todo note <id>` 落到断点。
 3. **问是否开工**：明确问一句，**等确认再改代码**。
 
-**例外（可直接开工，但回复里须说明援引哪一条）**
-- 用户已说"开工 / 直接做 / 修它" —— 那就是授权
-- 一行级修字、纯查询、纯收尾沉淀 —— 无方案可言
-- 同一需求已登记且用户确认过 —— 接着做即可
-
-> 为什么：方案先过目能省掉整轮返工；登记让跨会话可续；"问开工"把决定权留在用户手里。
-> **这不是拖延** —— 总结方案本身就是工作，做完再问。
-## 图谱定位
-
-`.brain/` 放**项目根**，一个项目一份。所有命令只认**当前目录**的 `.brain/`（在项目根运行，不传路径）。
-**不向子目录归属，也不向上搜索**（上爬会命中 `~/.brain`，把无关项目静默挂错）。宁可报错也不猜。
-`abs status` 显示当前定位。
-
-## `.brain/` 怎么组织（每个文件/分区做什么、怎么用）
-
-骨架由 `abs init` 生成（`--repair` 只补缺不覆盖）。
-
-### `index.md` —— 图谱入口
-
-| 分区 | 放什么 | 怎么用 |
-|---|---|---|
-| `## Rules` | 本项目铁律 | 见下（load 里**原样全量**输出，不折） |
-| `## Concepts` `## Entities` `## Sources` `## Syntheses` `## Sessions` | 各类页的清单 | 每页一行 `- [[slug]] — 一句话`（`abs note`/建归档页会自动登记），load 里折成计数 |
-
-**`## Rules` 区**：铁律清单，`abs load` 每次都全量读（代码里明确不折它）。
-- 一句一条，**不带链接**（链接去概念页自己的「## 关联连接」挂），不展开。
-- 只有「违反会丢数据 / 静默失效 / 白干活」级才进 —— 普通经验进 `concepts/`。
-- 读写：`abs rule` / `abs rule add "一句话"`（>42 字符被拒；也不接受 `[[链接]]`/URL）；`abs lint` 超 30 条会报。
-
-### `log.md` —— 工作成果流水
-
-倒序一行摘要（`abs log "完成 X：…"`）。**只记成果，不收工具动作流水**（那在 `~/.abs/log/`）。
-load 只展示最新 5 条、每条按语义边界收口。
-
-### `todo.md` —— 活看板（进度唯一真源）
-
-**只有两区**（2026-09-13 精简）：未完成的一切都进 `## Todo`，状态用**行首标记**表达。
-
-| 分区 | 放什么 |
-|---|---|
-| `## Todo` | 未完成的一切。行首 `[进行中]` / `[讨论中]` / `[滞留中]`（`abs todo state`） |
-| `## Done` | 已完成，**必须带结语 `【落地/否决/仅方案】` + `(完成 YYYY-MM-DD)`** |
-
-行形态：`- [ ] [进行中] <id> [[name]] — 说明 (认领 YYYY-MM-DD)`
+**例外（可直接开工，回复里须说明援引哪一条）**：用户已说"开工/直接做/修它"；一行级修字、纯查询、纯收尾沉淀；同一需求已登记且用户确认过。
 
-`abs todo done <id>` 会勾选并归位到 Done 的日期组顶部，断点（`↳` 行）随迁；
-Done 区由 `abs wrapup` 在会话结束时自动把「超 3 天且整天都已完成」的组迁进
-**当天会话快照的 `## 📦 任务归档` 段**（`sessions/log-<日期>.md`）—— 归档不另建文件
-（任一天有未完成则整天不迁）。**什么时候动它见「进行中」一节。**
+`.brain/` 放项目根，一个项目一份；所有命令只认当前目录的 `.brain/`，不向上搜索。`abs status` 显示当前定位。
 
-### `entities/` `concepts/` `sources/` `syntheses/` `sessions/`
+## `.brain/` 怎么组织
 
-| 目录 | 放什么 | 命名 |
-|---|---|---|
-| `entities/` | 具名的**事物**（能说"它是什么"） | `Docker.md` |
-| `concepts/` | 可复用的**规律/坑**（能说"这么做就避坑"） | `docker-prisma-429.md` |
-| `sources/` | 实时经验**暂存**（`abs note` 自动落） | `YYYY-MM-DD-slug.md` |
-| `syntheses/` | **横向**选型/架构取舍（跨多个 entity/concept 的判断） | `synthesis-slug.md` |
-| `sessions/` | 会话快照（含 `## 🪝 Next Session Hook`）+ 当日任务归档段 | **`log-YYYY-MM-DD.md`** |
-
-归类拿不准时**默认 `concepts/`**。
-
-### `sessions/` 命名契约：一天一个文件（硬规则）
+`.brain/` 文件结构（`abs init` 生成，`--repair` 只补缺不覆盖）：
 
-**一天只允许一个文件，且只能叫 `log-<日期>.md`。** 该日的一切都放进它：
+文件结构（全部在 `.brain/` 下）：
 
 ```
-log-2026-09-08.md
-  ├─ 会话快照正文（AI 手写：做了什么/怎么定位/结论）
-  ├─ ## 关联连接
-  ├─ ## 🪝 Next Session Hook（强制）
-  └─ ## 📦 任务归档（`abs todo archive` 自动写，机器生成勿手改）
+/ .brain/
+  index.md  log.md  todo.md
+  entities/  concepts/  sources/  syntheses/  sessions/
 ```
 
-**为什么定死**（实测 codebuddy 项目乱成这样，2026-09-15）：同一天曾出现 **5 个文件**：
-`2026-09-07-init-brain.md` / `-todo-md-archive.md` / `-todo归档.md` / `-ui-fixes.md` / `log-2026-09-07.md`，
-且五份的 `tags` 各不相同（`source` / `source,archive` / `todo-archive` / `source,session-log` / `session-log`）。
-同一天的记录散在多处，查一次要开五个文件。
-
-**✅ 归档的正规做法**（用户 2026-09-15 定为标准，以后都这么干）：
-
-```bash
-abs todo archive            # 一条命令搞定，无需手工搬
-```
+| 位置 | 放什么 | 硬约束 |
+|---|---|---|
+| `index.md` `## Rules` | 本项目铁律 | 一句一条，不带链接；只有「违反会丢数据/静默失效/白干活」级才进（普通经验进 `concepts/`）；>42 字符或含链接/URL 被拒 |
+| `index.md` 清单区 | 各类页清单 | 每页一行 `- [[slug]] — 一句话` |
+| `log.md` | 成果流水，倒序一行 | 只记成果，不收工具动作流水（那在 `~/.abs/log/`） |
+| `todo.md` | 活看板，只有 `## Todo` + `## Done` | 未完成用行首标记 `[进行中]`/`[讨论中]`/`[滞留中]`；Done 必带 `【落地/否决/仅方案】` + `(完成 YYYY-MM-DD)` |
+| `entities/` | 具名事物（"它是什么"） | `Docker.md` |
+| `concepts/` | 可复用规律/坑（"这么做就避坑"） | `docker-prisma-429.md`；归类拿不准时默认这里 |
+| `sources/` | 经验暂存（`abs note` 自动落） | `YYYY-MM-DD-slug.md`；是暂存，不是归档 |
+| `syntheses/` | 横向选型/架构取舍 | `synthesis-slug.md` |
+| `sessions/` | 会话快照 + 当日归档段 | **一天只允许一个文件，只能叫 `log-<日期>.md`** |
 
-它自动把过期日期组写进 `sessions/log-<那天>.md` 的 `## 📦 任务归档` 段：
-- 该日**已有快照** → 只替换归档段，**段外的手写内容逐字保留**（不覆盖人工内容）
-- 该日**没有快照** → 建一个只有归档段的 `log-<日期>.md`（那天本来就只有任务记录）
-- 同日二次归档 → 段内追加，不重复建段
+`todo.md` 行形态：`- [ ] [进行中] <id> [[认领人]] — 说明 (认领 YYYY-MM-DD)`（`[[认领人]]` = 使用者名，非任务名）。`abs todo done <id>` 勾选并归位到 Done 日期组顶部，断点（`↳` 行）随迁；超 3 天且整天完成的组由 `abs wrapup` 迁进当天快照的归档段。
 
-**结论：归档这件事不需要「方法」，只需要跑那条命令。**下面的禁令是给**手写**用的
-（手写时才可能犯错）。
+**`sessions/` 一天一个文件**（多主题多写几个 `##` 段，不许拆文件），含快照正文（AI 手写）+ `## 关联连接` + `## 🪝 Next Session Hook`（强制）+ `## 📦 任务归档`（机器写，勿手改）。归档唯一动作 `abs todo archive`：已有快照只替换归档段（段外内容逐字保留），没快照则建一个只有归档段的文件，同日二次归档段内追加。
 
-**四条禁令**（每条都有实测反例）：
-1. **不要**再把归档单独建文件（`<日期>-todo归档.md`）——归档已有专门的坑位段，`abs todo archive` 会写进去。
-   存量旧页不必手改（lint 不报），但新归档不再产生它。
-2. **不要**在 `sessions/` 放 `tags: [source]` 的页——暂存页属 `sources/`。
-   当天做的一组工作不是「暂存线索」，而是**当天的快照正文**：直接写进 `log-<日期>.md`。
-3. **不要**一天拆多个快照（`log-<日期>-<主题>.md`）——多主题就多写几个 `##` 段。
-4. **不要**手工搬大文件进来当归档（如把仓库根 `todo.md` 全文倒进 `sessions/`）——
-   那要么进 `sources/`，要么摘出规律进 `concepts/`；全文属外部产物，用指针就行。
+`abs lint` 兜底：死链 / 孤岛 / 悬挂页 / 缺 frontmatter / 超限 / sources 堆积 / 超龄未提炼 / index 漏列 / Rules 超限 / 缺尾。
 
 ### 容量纪律（写任何页之前过四关）
 
-图谱贵在**精**不在全，不过关就不写或压缩：
-1. **再命中**：下会话不知道这条会踩同坑/重做同决定？会→存，不会→不存。代码能 grep 到的一律不记。
-2. **单页上限**：`entities/concepts/syntheses` 单页 <150 行且 <8KB，超了拆或外链。
-3. **sources 是暂存**：提炼成规律后删/归档，并清掉指向它的引用（防死链）。
-4. **能不能用一行链接代替新增整页**？
+不过关就不写或压缩：① **再命中** —— 下会话不知道这条会踩同坑/重做同决定？不会就不存，代码能 grep 到的一律不记。② **单页上限** —— `entities/concepts/syntheses` 单页 <150 行且 <8KB，超了拆或外链。③ **sources 是暂存** —— 提炼成规律后删/归档，并清引用（防死链）。④ 能不能用一行链接代替新增整页？
 
-`abs lint` 兜底：死链/孤岛/**悬挂页(NO-INBOUND)**/缺 frontmatter/超限/sources 堆积/**超龄未提炼(SOURCE-UNDISTILLED)**/index 漏列/Rules 超限/**缺尾(NO-TAIL，concept 页没有「做完怎么确认」)**。
 ## 开场：Init Sync（开工 / 默认续 todo）
 
-图谱已存在；收到第一个核心开发指令**之前**走这条链载入上下文：
-
-1. **读状态**：`abs load`（或 MCP `abs_load`）读 index 的 Rules + 图谱计数 + todo 看板 + 最近 log。
-   > **开工前先看 `## Rules`** —— 那是本项目踩过坑后定下的硬规则，每条都是曾经付过代价的。
-   > 违反的代价一般是丢数据/静默失效/白干活，而它就在 load 输出里，没有理由不看。
-   >
-   > **load 输出是折叠过的，不是全量。** 两个无上限增长的区块在读取侧收口：
-   > - **Done 区** → 按日期计数（曾占 load 输出 68.8%，长历史项目上单次 load 吃掉 40% 上下文）
-   > - **index 页面清单** → 各分区只给页数（concept 清单占 load 输出 64%，隨图谱线性增长）
-   > - 「最近动作」每条按语义边界收口到 220 字符
-   >
-   > **`## Rules` 区原样保留** —— 那是 load 要传达的状态本身（代码里明确不折）。
-   > 要全量明细：`abs todo --full` / `abs index`，或直接读 `.brain/` 文件、
-   > `.brain/sessions/log-<日期>.md`（含 `## 📦 任务归档` 段）。
-2. **对账滞留（强制，别跳过）**：若 `abs load` 顶部出现 `⏳ 上会话滞留`，说明上会话有任务做完/做到一半就断了。**先收尾再开工**：
-   - 快照里的任务现在真做完了 → `abs todo done <id>`（done 后下次 load 滞留自动消失）；
-   - 还没做完 → `abs todo note <id> --note "接到哪/改到哪个文件"` 补断点（别空手续接）。
-   滞留没清完就不算接上了状态——这是「任务做完没进 Done」的根治动作。
-3. **读命中页**：`abs query <词>` 检索（多词 OR）→ 拿到页名后读那几个文件。
-   ```bash
-   abs query <词>                  # 全文检索，只回命中几页
-   abs resolve <页名或id>          # 反查文件路径（页改过名时用 id 能找回）
-   ```
-   > ⚠️ **绝不通读 `.brain/`**（29 页就约 11 万 token，全读塞满窗口）。
-   > 要状态→`abs load`；要主题→`abs query <词>`；要完整页清单→`abs index`（或直接读 `.brain/index.md`）；要某页→`abs resolve` 拿到路径后**只读那一页**。
-   > 汇总多文件时用 `ctx_execute` 类工具在沙箱里处理，**只打印结论**。
-4. **续 todo**：默认续 todo 分支 → 把顶部未完成项当当前任务开做。
-5. **登记新任务**：有明确新任务而 todo 没有 → `abs todo add <id> --note 做什么` 再动工。
-
-## 进行中：什么时候动它（最重要的节）
-
-**todo 不是收尾仪式，是随改随写的活看板。** 每个任务边界立即更新，与 git commit 同反射。
-
-**看板只有两区**：`## Todo`（未完成的一切）+ `## Done`（已完成）。
-未完成的状态用**行首标记**表达：`[进行中]` `[讨论中]` `[滞留中]`。
-
-| 时机 | 动作 | 落到哪 |
-|---|---|---|
-| 认领新任务 / 聊出一个话题 | `abs_task {action:start, id:"T-1", note:"做什么"}` | Todo `[进行中]` |
-| 只在讨论、还没动手 | `abs_task {action:state, id:"T-1", note:"讨论中"}` | 原地改标记 |
-| 卡住了/等人等数据 | `abs_task {action:state, id:"T-1", note:"滞留中"}` | 原地改标记 |
-| 被打断/干到一半 | `abs_task {action:note, id:"T-1", note:"改到哪个文件/到哪步"}` | 原地 ↳断点 |
-| 子任务做完 | `abs_task {action:done, id:"T-1", note:"结语文字", as:"落地|否决|仅方案"}` | Done（as 默认 落地；做了又撤用否决，只设计过用仅方案，别让假【落地】污染看板） |
-| 总结出经验/坑/规律 | `abs_note {text:"一句话", tags:"坑,docker"}` | sources/ |
-
-> **为什么只有两区**（2026-09-13 实测）：跨 4 个项目，Backlog/Today 常年 **0 条**，而 log.md
-> 有 120 条。根因是 AI 的工作方式「一口气做完」——任务从开始到完成都在同一会话内走完，
-> 中间那个「挂到进行时分区」的动作既来不及也不需要。**进行时分区是符合直觉但不符合实际
-> 工作流的抽象**，故删掉，状态改用行首标记。
-
-**核心：事件发生的那一刻就落，别攒到收尾。** 动作一变，扫一眼属于哪行，调对应工具。
+收到第一个核心开发指令**之前**走这条链载入上下文：
 
-### 唯一会让看板失灵的动作：先动手、后登记（2026-09-18 实测）
+1. **读状态**：`abs load`（MCP `abs_load`）读 Rules + 图谱计数 + todo + 最近 log。**开工前先看 `## Rules`**。load 输出是折叠的（Done 按日期计数、清单只给页数）；全量明细用 `abs todo --full` / `abs index`。
+2. **对账滞留（强制，别跳过）**：若顶部出现 `⏳ 上会话滞留`，说明上会话任务断了，先收尾再开工 —— 真做完的 `abs todo done <id>`；没做完的 `abs todo note <id> --note "接到哪/改到哪个文件"` 补断点。
+3. **读命中页**：`abs query <词>` → `abs resolve <页名或id>` 拿路径后**只读命中那几页**。**绝不通读 `.brain/`**；汇总多文件用 `ctx_execute` 类工具在沙箱里处理，只打印结论。
+4. **续 todo**：把顶部未完成项当当前任务开做；有明确新任务而 todo 没有 → `abs todo add <id> --note 做什么` 再动工。
 
-上面那张表是**状态变化**驱动的，缺一个**开工前**的触发器 —— 实测的失效路径是：接到任务
-→ 立刻去读代码/改文件（因为觉得「还没开始做，没什么可登的」）→ 一口气做完 → 只在收尾
-补一条 done。结果：**看板在被看的时候（会话下半场、别的会话接手）永远是空的**，
-跨会话续接丢锚点。用户原话：「todo 登记不及时，总是空的」。
+## 进行中：什么时候动它
 
-**硬规则（与 git commit 同反射，不是收尾仪式）：**
+**todo 是随改随写的活看板，同 git commit 同反射。**
 
-1. **开工前先登记** —— 认领任何需要动文件/跑命令的任务，**第一步是 `abs_task {action:start}`
-   （或 `abs todo add <id> --note 做什么`）**，然后才去读第一个文件。任务名想不到就先起个
-   粗糙的（`fix-hook-nudge`、`T-DEPLOY`）—— 名字可以事后改，**未登记的开工补不回来**。
-2. **一段活儿干完立刻 done** —— 不是等整个需求收尾。子任务做完就 `abs_task {action:done, id, note:"结语"}`，
-   下一个子任务开工前再 start。**宁可拆成 5 条小的，别攒成 1 条大的。**
-3. **动手超过两三轮还没登记 = 已经在失控的路上** —— 立刻补 `start`，别等下一轮。
+| 时机 | `abs_task` action | 落到哪 |
+|---|---|---|
+| 认领新任务 / 聊出一个话题 | `start` + note 做什么 | Todo `[进行中]` |
+| 只在讨论、还没动手 | `state` + note 讨论中 | 原地改标记 |
+| 卡住了/等人等数据 | `state` + note 滞留中 | 原地改标记 |
+| 被打断/干到一半 | `note` + 改到哪个文件/到哪步 | 原地 ↳断点 |
+| 子任务做完 | `done` + note 结语 + as 落地\|否决\|仅方案 | Done（别让假【落地】污染看板） |
+| 总结出经验/坑/规律 | 改用 `abs_note` text + tags | sources/ |
 
-> 反面样本（本次实测全过程）：整个会话改了 4 个文件、跑了 10 次 bash，
-> `.brain/` 今日**零 todo 记录**，直到收尾注入才补。用户看板全程是空的。
-> 代价不是「记录少了」，而是**用户中途想看进度时看不到** —— 活看板的价值就在中途。
+**硬规则（开工前触发器，别被状态表漏掉）：**
 
-**经验刚冒出来就落**：`abs note "一句话经验" --tags 坑,docker` → 暂存 `sources/`（幂等去重）。宁少勿滥。
+1. **开工前先登记** —— 认领任何要动文件/跑命令的任务，**第一步是 `abs_task` action=start**，然后才读第一个文件。名字想不到就先起粗糙的（`fix-hook-nudge`）—— 名字可事后改，**未登记的开工补不回来**。
+2. **一段活儿干完立刻 done** —— 不是等整个需求收尾。宁可拆成 5 条小的，别攒成 1 条大的。
+3. **动手超过两三轮还没登记 = 已在失控路上** —— 立刻补 `start`。
 
-> **写操作走 MCP（`abs_task`/`abs_note`），别用 bash 跑 CLI** —— MCP 常驻 ~2ms，
-> CLI 每次起 node 进程 27ms。（[[perf-fixed-overhead]]）
->
-> **跨会话任务只用 abs todo，别用宿主原生 todo**（Cl​aude TodoWrite / co​dex todo-list /
-> Op​enCode todowrite / pi `/list`）—— 那些多是会话内临时，不写 `.brain/todo.md`，
-> 下会话接不上、收尾没影。原生 todo 顶多记“本会话不跨断点的临时拆解”。
+**经验刚冒出来就落**：`abs_note` 暂存 `sources/`（幂等去重），宁少勿滥。
+**跨会话任务只用 abs todo，别用宿主原生 todo**（TodoWrite / todo-list / `/list`）—— 那些是会话内临时，不写 `.brain/todo.md`，下会话接不上。
 
 ## 收尾循环（用户明确要求收尾时才走）
 
-**每个任务边界、被 Stop/打断、告一段落时，别停半空。** 这是“开场接上状态、结束落回状态”的闭环。
+用户**明确说要收尾/结束/切别的事**时按下面走（不是每个词都触发，见开头总则）：
 
-> Stop 时 hook 把「未完成任务 + 断点」快照进 `~/.abs/log/wrapup.log`（`abs wrapup`，机械幂等），
-> 下会话 `abs load` 会自动把滞留顶到顶部（`⏳ 上会话滞留`）—— 所以收尾不靠自觉，是开场被强制接上。
->
-> **不再主动注入**（2026-09-18）：pi 扩展曾在 `agent_end` 往对话里推一条 `[abs 收尾提醒]`
-> （Claude/Co​dex 靠 `Stop` 事件、op​encode 靠 `session.idle` 达成同样效果）。
-> 已全部删除：用户实报「每次干活干一会就出来, 任务就中断了」。**主动往对话里插一个 turn
-> 就是打断，不是频率问题** —— 每轮弹、每会话弹都还是打断。收尾靠**你自己在该收尾时走**，
-> 以及 `wrapup.log` + `abs load` 的机制兵底（开场强制接上滞留任务）。
-> 挂钩只在 `~/.abs/log/hooks.log` 留痕，不再往对话里说话。
+1. **读 todo** → `abs load`，看 Todo 还有哪些没完成。
+2. **对账** → 漏登记的 `abs todo done <id>`；做一半补 `abs todo note <id> --note 断点`；卡住的 `abs todo state <id> --note 滞留中`。别让干完的事还留在 Todo。
+3. **沉淀经验（该沉淀才沉淀）** → 值得记的坑/可复用技巧 → `abs note` 暂存；值得深提炼的按 Teardown 走。
+4. **判教训够不够格进 Rules（别跳过）** → 是否「违反会丢数据/静默失效/白干活」级？
+   - **够格 → 提议，不直写**：输出一行 `[Rules 提议] <一句话>` 问用户要不要加，确认后才 `abs rule add "<一句话>"`（短句，不带链接/解释）。
+   - 不够格 → 不提，普通经验留在概念页。
+   **为什么单列**：Rules 是唯一每次 load 全量送达的通道，概念页只在关键词命中时出现；够格不加 = 下次不送达。
+5. **更新 index/log/todo** → 新页同步进 index；`abs log "完成 X：..."` 记一行成果；跑 `abs lint` 确认自洽。
 
-当用户**明确说要收尾/结束/切别的事**时，按下面走（不是每个词都触发，见开头总则）：
+**完成标准**：看板反映真实状态（Done 无滞留半成品）、该沉淀已落、够格的教训已提议进 Rules、index/log/todo 与事实一致。
 
-1. **读 todo** → `abs load`，看 Todo 还有哪些没完成。
-2. **判有没有做完没登记** → 实际完成了漏登记的 `abs todo done <id>`；做到一半补
-   `abs todo note <id> --note 断点`；卡住的 `abs todo state <id> --note 滞留中`。别让干完的事还留在 Todo。
-3. **沉淀经验（该沉淀才沉淀）** → 踩了值得记的坑/有可复用技巧/跨会话判断 → `abs note`
-   暂存；值得深提炼的（规律/坑/决策）按 Teardown 走完整流程。
-4. **判本次教训够不够格进 Rules（别跳过）** → 过一遍：这条是否**「违反会丢数据/静默失效/白干活」**级？
-   - **够格 → 提议，不直写**：输出一行 `[Rules 提议] <一句话>` 并问用户要不要加，得到确认才
-     `abs rule add "<一句话>"`（短句，不带链接/解释；链接去概念页挂）。
-   - 不够格 → 不提。普通经验留在概念页，别进 Rules（否则长成第二份概念库）。
-   > **为什么单列一步**：Rules 是全系统**唯一每次 load 全量送达**的通道（代码里明确不折），
-   > 而概念页只在关键词命中时出现。**够格却不加 = 这条教训下次不会送达。**
-   > 实测坑（2026-09-15）：原先把这动作塞在第 4 步里当附属从句，结果 14 条 Rule 中 13 条
-   > 来自两次人工注入，机制本身长期 0 新增 —— 同类坑反复发作（静默失效 5 次）。
-   > 详见 concepts/learning-loop-collect-distill-deliver.md。
-   > **别改成 lint 报警**：那是「靠提醒才能工作的功能」，已被本仓硬规则否定。
-5. **更新 index/log/todo** → 新页同步进 index；`log.md` 倒序记一行**工作成果**摘要
-   （`abs log "完成 X：..."`，不是工具动作）；todo 对账。
-   跑 `abs lint` 确认自洽。
-
-**完成标准**：看板反映真实状态（Done 无滞留半成品）、该沉淀已落、**够格的教训已提议进 Rules**、index/log/todo 与事实一致。
+Stop 时 hook 把「未完成任务 + 断点」快照进 `~/.abs/log/wrapup.log`，下会话 `abs load` 自动把滞留顶到顶部。**不主动往对话里插收尾提醒** —— 插一个 turn 就是打断（挂钩只在 `~/.abs/log/hooks.log` 留痕）。
 
 ## 收尾：Teardown Sync（深提炼，工具不替判断）
 
 任务告一段落/结束前，把**真实发生**写回图谱。只写做过/跑过/测过的事实，禁止脑补。按序：
 
-1. **暂存线索**：`abs note`（或建 `sources/YYYY-MM-DD-slug.md`）记做了什么、改哪些文件、验证命令。
-2. **抽规律**：值得留的 → **用 `abs concept <slug> --title "…"` 建页**（自动带好四段骨架
-   并登记 index），再填内容。手写也行，但**四段位置别缺** —— 尤其末尾的「验证」段：
-   **没尾巴的经验只能被「相信」，不能被「验证」**（`abs lint` 会报 NO-TAIL）。
-   **判断仍归你**：这条值不值得留、该新建还是并入已有页 —— `abs concept` 只给结构，不替判断。
-   **同时检查：旧页里有没有被本次推翻的说法？** 有 → `abs supersede <旧页> --by <新页>`
-   （别删页；删了会让下个会话重踩同一个坑、重新记一遍）。核实过的新页把 `status` 改成 `active`
-   （`abs note` 落的页默认是 `draft`）。
-3. **沉淀实体**：碰了重要未记录的事物 → `entities/<TitleCase>.md`。
-4. **对账 todo**：做完的归位 Done（标结语+日期），做一半的补断点，卡住的改 `[滞留中]`。
-5. **综合(可选)**：推进了选型/取舍 → `syntheses/`。
-6. **收拢 sources**：提炼成规律的删 source，**同步清指向它的引用**（防死链）。
-7. **修 index + 记 log**：新页同步 index；**过 Rules 门槛的规律加一行到 `## Rules`**；
-   `log.md` 倒序记一行摘要。
-8. **留接力棒**：`sessions/log-YYYY-MM-DD.md`，强制写 `## 🪝 Next Session Hook`。
-
-**完成标准**：每条过了容量纪律的知识一处落点；index 与事实一致；sessions 有带 Hook 快照。
+1. **暂存线索**：`abs note` 记做了什么、改哪些文件、验证命令。
+2. **抽规律**：值得留的 → `abs concept <slug> --title "…"` 建页（自动带四段骨架）再填内容。四段别缺，尤其末尾「验证」段（`abs lint` 报 NO-TAIL）。**判断仍归你**：值不值得留、新建还是并入已有页；核实过的把 `status` 改 `active`。
+3. **查推翻**：旧页有被本次推翻的说法 → `abs supersede <旧页> --by <新页>`（别删页）。
+4. **沉淀实体 / 综合**：重要未记录的事物 → `entities/<TitleCase>.md`；选型/取舍 → `syntheses/`。
+5. **收拢 sources**：提炼成规律的删 source，**同步清指向它的引用**（防死链）。
+6. **修 index + 记 log**：新页同步 index；过 Rules 门槛的规律加一行到 `## Rules`。
+7. **留接力棒**：`sessions/log-YYYY-MM-DD.md` 强制写 `## 🪝 Next Session Hook`。
 
 ## 知识页格式
 
-统一 frontmatter：`tags / author / updated / status`。
-`tags` 首标签 ∈ `entity|concept|source|synthesis|session-log`。`author` 与 `entities/<name>.md` 同名。
+统一 frontmatter：`tags / author / updated / status`。`tags` 首标签 ∈ `entity|concept|source|synthesis|session-log`；`author` 与 `entities/<name>.md` 同名。
 
-**`status` 三个值（生命周期，别写别的）：**
-
-| 值 | 含义 | 读取侧行为 |
-|---|---|---|
-| `active` | 当前有效（**缺字段默认就是它**，存量页无需改） | 正常展示 |
-| `draft` | 待核实（`abs note` 新落的经验默认这个） | 展示但标注 `[draft 未核实]` |
-| `superseded` | **已被推翻，别再依据它** | `query` 默认隐藏（计数据告知） |
+**`status` 三个值（别写别的）**：`active` 当前有效（缺字段默认就是它，正常展示）；`draft` 待核实（`abs note` 默认落这个，展示但标 `[draft 未核实]`）；`superseded` 已被推翻，别再依据（`query` 默认隐藏）。
 
-**推翻一条经验**（不要删文件！）：
-```bash
-abs supersede <页名> --by <取代它的新页>   # 不写 --by 也行 = 单纯弃用，无替代
-```
-→ 把 `status` 改成 `superseded` 并写 `superseded-by`。**历史必须留**：删了会让下个会话重踩同一个坑、重新记一遍。
-→ 核实后发现仍有效：把 `status` 改回 `active`（一行，可反悔）。
-→ 拒写悬空引用：`--by` 指向不存在的页会直接拒绝。
+推翻一条经验用 `abs supersede <页名> --by <新页>`（改 `status` 为 `superseded` 并写 `superseded-by`；不写 `--by` = 单纯弃用）。历史必须留；核实后仍有效就把 `status` 改回 `active`。`--by` 指向不存在的页会被拒。
 
-- **每页必须有 `## 关联连接`**，用 `[[页面名]]` 链相关页 —— 严禁孤岛页。
-  **链路解释写在 `—` 后面**（如 `[[hook-throttle-alignment]] — 节流判据要对齐「真收尾」`），
-  这样 AI 不点开就知道该不该跟进；只写链点不写解释，等于没链。
+- **每页必须有 `## 关联连接`**，用 `[[页面名]]` 链相关页，严禁孤岛页。链路解释写在 `—` 后面（`[[hook-throttle-alignment]] — 节流判据要对齐「真收尾」`），只写链点等于没链。
 - **命名即链接**：`[[Docker]]` → `entities/Docker.md`；`[[docker-prisma-429]]` → `concepts/`。不建别名层。
 - **知识冲突**：不静默覆盖，加 `## 知识冲突` 两版都留、标来源时间，交人工裁决。
 - 概念页骨架：`触发场景 / ❌表现(贴报错) / 🛠解法(根因+修复+验证命令) / 关联连接`。
 
 ## 维护：query / lint
 
-- `abs query <词>` 检索（多词 OR）→ 读命中页 → 答用 `[[页面名]]` 标来源。
-  **代码问题（符号在哪/谁调用）不在 .brain，直接读源码**；.brain 只答"踩过什么坑/上次做到哪"。
-  已被推翻的经验默认不返回（`--all` 可看）—— 但若你确实需要拿旧结论对照，记得它已被推翻。
-- `abs lint` 体检：死链/孤岛/**悬挂页**/缺 frontmatter/模板残留/超尺寸/sources 堆积/**超龄未提炼**/index 漏列/Rules 超限/**取代者悬空**/**draft 超龄**。
-  - `NO-INBOUND`：有出边但无人 `[[链接]]` 到你 = 挂在图上没人接（孤岛检查只抓"零出零入"）。
-  - `SOURCE-UNDISTILLED`：source 超 7 天仍未链到任何 concept = 暂存了没归位。
-  - `SUPERSEDED-DANGLING`：`superseded-by` 指向的页不存在（删页后忘同步）。
-  - `DRAFT-STALE`：concepts 等长期停在 `draft` = 既没核实也没推翻，核实/推翻后各改一行。
+- `abs query <词>` → 读命中页 → 答用 `[[页面名]]` 标来源。**代码问题（符号在哪/谁调用）不在 .brain，直接读源码**；已推翻经验默认不返回（`--all` 可看）。
+- `abs lint` 报错码：`NO-INBOUND` 有出边无人链接 / `SOURCE-UNDISTILLED` source 超 7 天未链 concept / `SUPERSEDED-DANGLING` superseded-by 页不存在 / `DRAFT-STALE` 停在 draft / `NO-TAIL` 缺「做完怎么确认」段。
 
-## 三层分工
+## ⛔ 禁止做
 
-| 层 | 干什么 |
-|---|---|
-| **hook（机械）** | 自动记技术日志到 `~/.abs/log/`，你不用管 |
-| **CLI/MCP（实时）** | 任务/经验实时落盘：`abs todo …`、`abs note` |
-| **skill（自觉）** | **深提炼**（sources→concepts）+ 收尾 + 修 index —— 工具不替你判断 |
-
-骨架/任务/暂存/检索/体检走工具；**深提炼手工写**（那是判断力）。改完跑 `abs lint`。
+1. **禁止手工建骨架 / 手工登记任务** —— 用 `abs init` / `abs todo add`。
+2. **禁止由关键词直接触发动作**（"简短""收尾"等词出现在定规则的句子里时只回应，不执行）—— 拿不准先问。
+3. **禁止通读 `.brain/`** —— 要状态用 `abs load`，要主题用 `abs query`，要单页用 `abs resolve` 后只读那页。
+4. **禁止删知识页来表达"已失效"** —— 用 `abs supersede <旧页> --by <新页>`。
+5. **禁止归档单独建文件 / 一天拆多个快照 / 手工搬大文件** —— 用 `abs todo archive`；一天只有一个 `log-<日期>.md`；大文件进 `sources/` 或摘出规律进 `concepts/`。
+6. **禁止编造没跑过的验证结论** —— 只写做过/跑过/测过的事实；不清楚就写"未定位"。
+7. **禁止直写 Rules** —— 够格的先输出 `[Rules 提议]` 问用户，确认后才 `abs rule add`。
+8. **禁止用宿主原生 todo 承载跨会话任务** —— 用 `abs_task`，原生 todo 只记本会话临时拆解。
 
 ## 自我约束
 
-- 只读写 `.brain/` 与目标代码，不动全局配置（一次性接入除外）。
-- 只写真实发生的事实；遵守容量纪律，宁缺毋滥。
+- 只读写 `.brain/` 与目标代码，不动全局配置（一次性接入除外）。只写真实发生的事实，遵守容量纪律。
 - 双链/frontmatter/index 必须自洽 —— 坏链 = 掰断接力棒。
+

package/src/store.js

@@ -3,7 +3,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 { requireUser, atTag, getUser, placeholderWarn } 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';
@@ -300,14 +300,24 @@ export async function cmdLoad({ dir }) {
     if (shape.warn.length) rows.push('  （无头文件不自动改：结构可能整体脱轨，请手工对齐 .brain/ 模板）');
     sections.push('--- 文件形状核对 ---', ...rows, '');
   }
-  // 未设姓名时开场就提醒 —— load 是开机第一屏，不在这里提，
+  // 未设姓名/姓名是占位名时开场就提醒 —— load 是开机第一屏，不在这里提，
   // 用户要撞到第一次写操作才知道（init/load 一路沉默）。
-  if (!(await getUser())) {
+  // 占位名（历史遗留 tester/foo）必须提：配置里有值 ≠ 名字是对的。
+  // 一次调用拿两者（placeholderWarn 内部也要 getUser）—— 原先分两次读盘（2026-10-03 审查）。
+  const who = await getUser();
+  const ph = who ? await placeholderWarn() : null;
+  if (!who) {
     sections.push(
       '⚠ 尚未设置使用者姓名（写操作会先报错）',
       '→ abs config set user <你的名字>    (或临时: ABS_USER=<名字> abs ...)',
       ''
     );
+  } else if (ph) {
+    sections.push(
+      `⚠ 当前作者名是占位名 "${ph}" —— 之后所有项目的 todo/log 都会标它。`,
+      '→ abs config set user <你的真名>    (或临时: ABS_USER=<名字> abs ...)',
+      ''
+    );
   }
   sections.push(
     // Rules 单独成段且放在最前（仅次于项目行/滞留）：它是硬规则，不是普通清单。

package/src/userconfig.js

@@ -30,6 +30,34 @@ export async function getUser() {
   }
 }
 
+/** 占位名黑名单：这些名字没有任何正当理由当作者名，写进全局配置会污染之后所有项目。
+ * 教训（2026-09-18）：一次手动 `abs config set user tester` 让新项目每条 todo 都标 [[tester]]。
+ * 注意只拦 setUser（持久配置），**不拦 ABS_USER 环境变量** —— env 是一次性显式覆盖，
+ * 且测试套件全程用 ABS_USER=tester（7 个测试文件），拦它会全线爆掉。 */
+const PLACEHOLDER_NAMES = new Set([
+  'tester', 'test', 'testing', 'foo', 'bar', 'baz', 'foobar',
+  'admin', 'user', 'username', 'me', 'you', 'someone', 'nobody',
+  'example', 'demo', 'sample', 'tmp', 'temp', 'default', 'null', 'none',
+]);
+
+/** 校验是否是像样的人名；不合格抛带指引的错误。setUser 专用（ABS_USER 不过此关）。 */
+function assertRealName(name) {
+  const lower = name.toLowerCase();
+  if (PLACEHOLDER_NAMES.has(lower)) {
+    throw new Error(
+      `✗ "${name}" 是占位名，不是真人姓名 —— 它会成为所有项目的作者标记。\n` +
+      '  请填你本人的名字（如 abs config set user 张三 / alice）'
+    );
+  }
+  // 无意义重复串：aaa/xxx/111 之类。
+  // 长度门槛 ≥3 —— `oo`/`ee`/`ww` 这种两字母是合法的姓名缩写（2026-10-03 审查发现
+  // 原规则会误伤它们），也避免中文叠字小名（如 `中中`）被无故拒绝。
+  if (lower.length >= 3 && /^(.)\1+$/.test(lower)) {
+    throw new Error(`✗ "${name}" 看起来不是名字（重复字符）—— 请填你本人的名字`);
+  }
+  return name;
+}
+
 /** 写配置的 user 字段（保留其它键）。 */
 export async function setUser(name) {
   const clean = String(name || '').trim();
@@ -38,6 +66,7 @@ export async function setUser(name) {
   if (!/^[\w\u4e00-\u9fff.-]+$/.test(clean)) {
     throw new Error(`✗ 姓名 "${clean}" 含不支持的字符（只允许字母/数字/中文/._-，且不含空格）`);
   }
+  assertRealName(clean);
   const p = userConfigPath();
   await fs.mkdir(join(p, '..'), { recursive: true });
   let cfg = {};
@@ -66,6 +95,17 @@ export async function requireUser() {
   throw e;
 }
 
+/** 只读体检：当前生效的作者名是否是占位名（脏配置检测）。
+ * 给 load 用 —— 不抛错，返回占位名或 null。历史遗留的 tester 配置靠这条被看见。 */
+export async function placeholderWarn() {
+  const u = await getUser();
+  if (!u) return null;
+  const lower = u.toLowerCase();
+  // 与 assertRealName 同一规则（含长度门槛 ≥3），两处不能写成不同判据
+  if (PLACEHOLDER_NAMES.has(lower) || (lower.length >= 3 && /^(.)\1+$/.test(lower))) return u;
+  return null;
+}
+
 /** 标记串：`[[name]]`（wikilink 到人页 entities/<name>.md）。
  * 用 wiki 链接而非裸 `@name`：人是图谱实体，点得进去看技术栈/特点。
  * 旧数据里的裸 `@name` 仍可解析（见 todo.js extractAuthor），但不回填。 */