@fanchao8609/agent_brain_sync 1.15.3 → 1.16.2

package/README.md

@@ -125,7 +125,7 @@ abs update                                # 升级到最新版并刷新四宿主
 ```
 
 > `abs todo start` 与 `abs todo add` 等价（都登记任务）。
-> 旧版 `abs task ...` / `abs board` 已改名，会报错并提示新写法。
+> 旧版 `abs task ...` / `abs board` 已废，打它们会报「未知命令」并退出码 1。
 > `abs wrapup` / `abs teardown-check` 是 hook 内部命令，无需手动调用。
 > **作者名要填真的**：`tester` / `foo` / `aaa` 这类占位名会被拒 —— 因为 `{user}` 是全局单值，
 > 填错会污染之后所有项目的 `[[作者]]` 标记（`aaa` 这类堆字也拒，但 `oo`/`ee` 这种两字母缩写放行）。

package/bin/abs.js

@@ -279,10 +279,10 @@ const subUsage = {
     '',
     '用法:',
     '  abs todo                       看板',
-    '  abs todo add <id> [--note "做什么"] [--section 讨论中|滞留中]',
-    '  abs todo rename <旧id> --note "<新id>"   给自动登记的占位条目起真名',
+    '  abs todo add <id> [--note "做什么"] [--section 讨论中|滞留中|搁置]',
+    '  abs todo rename <旧id> --note "<新id>"   改任务 id（起错名/不可读时）',
     '  abs todo note <id> --note "断点/进度"',
-    '  abs todo state <id> --note 进行中|讨论中|滞留中',
+    '  abs todo state <id> --note 进行中|讨论中|滞留中|搁置',
     '  abs todo done <id> [--as 落地|否决|仅方案] [结语文字]',
     '  abs todo archive [--keep-days N] [--dry-run]',
     '',
@@ -336,19 +336,17 @@ function rejectExtra(extra, fix) {
   throw new Error(`✗ 不认识多余参数 ${q}\n  正确用法: ${fix}`);
 }
 
-// 已改名/已废弃命令 → 新写法（报错而非静默，避免用户白跑一趟）
-const RENAMED = {
-  task: () => '命令已改名: abs task → abs todo\n  例: abs todo add <id> --note "…"  /  abs todo done <id>',
-  board: () => '命令已改名: abs board → abs todo',
-};
+// 已废弃命令 → 报错（而非静默）。曾用 RENAMED 表做"已改名"提示，
+// 2026-10-05 删掉 task/board 两条：未知命令分支本来就报错+退出码 1+打印帮助，
+// 别名不提供额外信息，只多一处要维护的文案。
 
 // task/todo 共用的子命令 → 归一化后的 action
 const TODO_ACTIONS = {
   add: 'start',
   start: 'start', // add 的别名(老习惯保留)
   note: 'note',
-  state: 'state', // 改行首状态标记：进行中|讨论中|滞留中（原地，不搬区）
-  rename: 'rename', // 改任务 id：hook 只开 auto-TBD-<会话> 占位，真名由此处补
+  state: 'state', // 改行首状态标记：进行中|讨论中|滞留中|搁置（原地，不搬区）
+  rename: 'rename', // 改任务 id：人工起错名、或旧 id 不可读时用
   done: 'done',
 };
 
@@ -387,7 +385,6 @@ async function cmdConfig({ sub, value }) {
 async function main() {
   try {
     const opts = parseArgv(rest);
-    if (RENAMED[cmd]) throw new Error(RENAMED[cmd]());
     // 子命令级 --help: 有用法页的命令在此一处拦截（此前只在 install/uninstall 分支里判,
     // 其余命令的 --help 被忽略 —— 曾出现子命令 --help 直接执行动作、挂住终端）。
     if (opts.help && subUsage[cmd] && !(cmd === 'todo' && opts._.length)) {

package/bin/mcp.js

@@ -112,12 +112,12 @@ tool(
 
 tool(
   'abs_task',
-  '任务实时落盘（幂等键 = id）。start 登记进 Todo / note 补断点(改到哪文件哪行) / state 改状态 / done 完成归位 Done（done 时 note=结语文字，as=结语类型：落地|否决|仅方案）。',
+  '任务实时落盘（幂等键 = id）。start 登记进 Todo / note 补断点(改到哪文件哪行) / state 改状态 / done 完成归位 Done（done 时 note=结语文字，as=结语类型：落地|否决|仅方案）。必填: cwd, action, id。',
   {
     action: z.enum(['add', 'start', 'done', 'note', 'state']),
     id: z.string().describe('任务幂等键，如 TASK-xxx 或子任务名'),
     cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
-    note: z.string().optional().describe('add/start=做什么; note=断点(文件/到哪步); state=进行中|讨论中|滞留中; done=结语文字'),
+    note: z.string().optional().describe('add/start=做什么; note=断点(文件/到哪步); state=进行中|讨论中|滞留中|搁置（搁置=用户改方向/不做了；滞留中=还要做只是卡住）; done=结语文字'),
     as: z.enum(['落地', '否决', '仅方案']).optional().describe('仅 done：结语类型。默认 落地。做了又撤/评估后不做用 否决，只设计过用 仅方案 —— 别让假【落地】污染看板'),
   },
   async ({ action, id, cwd, note, as }) => {
@@ -131,7 +131,7 @@ tool(
 
 tool(
   'abs_resolve',
-  '按页面 id（或页面名 slug）反查文件路径。页改名后 id 不变，引用请用返回的路径/id。',
+  '按页面 id（或页面名 slug）反查文件路径。页改名后 id 不变，引用请用返回的路径/id。必填: cwd, refs（数组，一次可查多个）。',
   {
     cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
     refs: z.array(z.string()).min(1).describe('页面 id 或页面名，如 "file-write-locking"'),
@@ -151,7 +151,7 @@ tool(
 
 tool(
   'abs_supersede',
-  '标记一条经验/知识页已失效（被推翻），不删文件、保留历史。之后 abs_query 默认不再返回它。核实后发现仍有效可手动把 status 改回 active。',
+  '标记一条经验/知识页已失效（被推翻），不删文件、保留历史。之后 abs_query 默认不再返回它。核实后发现仍有效可手动把 status 改回 active。必填: cwd, refs（数组）。',
   {
     cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
     refs: z.array(z.string()).min(1).describe('页名或 id，如 "old-approach"'),
@@ -181,7 +181,7 @@ tool(
 
 tool(
   'abs_query',
-  '检索当前项目 .brain/ 知识页（多词 OR）：以前踩过什么坑、哪页记了 X。',
+  '检索当前项目 .brain/ 知识页（多词 OR）：以前踩过什么坑、哪页记了 X。必填: cwd, terms（数组，不是 query；可传多个词）。',
   { 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());
@@ -233,7 +233,7 @@ tool(
 
 tool(
   'abs_note',
-  '经验实时暂存：把刚踩的坑/技巧/结论一句话落进 sources/（防 context 断了流失）。Teardown 时再提炼进 concepts/。',
+  '经验实时暂存：把刚踩的坑/技巧/结论一句话落进 sources/（防 context 断了流失）。Teardown 时再提炼进 concepts/。必填: cwd, text。',
   {
     cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
     text: z.string().min(1).describe('经验/坑/技巧一句话'),
@@ -248,7 +248,7 @@ tool(
 
 tool(
   'abs_concept',
-  '建概念页骨架（给写入定结构：触发场景/表现/解法/验证）。只给结构不给内容 —— 值不值得留、归哪页仍靠人判断。',
+  '建概念页骨架（给写入定结构：触发场景/表现/解法/验证）。只给结构不给内容 —— 值不值得留、归哪页仍靠人判断。必填: cwd, slug。',
   {
     cwd: z.string().describe('项目根目录（.brain/ 所在处）'),
     slug: z.string().min(1).describe('文件名/slug，如 "docker-prisma-429"（命名即链接）'),

package/hooks/abs.pi.ts

@@ -99,6 +99,31 @@ let pendingTodoTool = false
  *  只记第一次写文件，不是每次都记：断点是「记到哪」不是流水账。 */
 let autoTaskSeen = false
 
+/** 本会话动过的文件（去重，最多记 FILES_SEEN_MAX 个）。
+ *
+ * ★ 定位（用户 2026-10-05 定，别改）：这**是「摆事实」，不是「发现问题」**。
+ *   它只把我自己刚干过的事（改过哪些文件）与看板并列摆出来，
+ *   **不判断这些改动算不算任务、不提醒、不追踪、不逼登记**。
+ *   是否意识到「我干的和看板对不上」、要不要补记 —— 全部由 LLM 自己反思。
+ *
+ * 为何不挂在「改文件/一轮结束」两个时机：那两个钩子改不了 system prompt
+ *   （tool_call/agent_end 拿不到 systemPromptOptions，只有 before_agent_start 有）；
+ *   而 sendUserMessage 插话已被否决（打断用户）。故记在这里、下轮带出。
+ *
+ * 今日最大的教训：**不要用技术手段替 LLM 发现 todo 问题。**
+ *   一侧（摆事实）有效，另一侧（替它发现）十二次全败。详见 concept remind-vs-gate。 */
+const filesSeen = new Set<string>()
+const FILES_SEEN_MAX = 8
+
+/** 写类工具调用的文件路径：edit/write 直接取 input.path，bash 取命令里像路径的片段。 */
+function touchedPath(name: string, input: any): string | null {
+  const p = input?.path ?? input?.file_path ?? input?.filename
+  if (typeof p === 'string' && p.trim()) return p.trim()
+  // bash 的写入靠命令字符串抻出路径（重定向/ sed -i / tee 等）
+  const cmd = String(input?.command ?? '')
+  const m = cmd.match(/(?:>>?|tee|sed -i[^ ]*)\s+([^\s|;&<>]+)/)
+  return m ? m[1] : null
+}
 
 /** 最近一次渲染拿到的 tui 引用。hidePanel 用它请求重绘 —— 面板消失时动画
  *  定时器已停，没有别的重绘通道（见 hidePanel 的坑注解）。 */
@@ -136,9 +161,23 @@ function resetThrottle(): void {
 // （表现：嘴上说"先登记"，实际没落盘）。故改成描述**意图 + 名字规律**，
 // 让模型按当前会话实际可见的形态自己挑，不去猜死一个。
 const TODO_GUIDELINES = [
-  'Use the abs task tool to track multi-step work **before** you start it, not after: on the first file edit of a task, call it with action "start" and a short id. (Name varies by host: `mcp__abs` with tool="abs_task", or `mcp__abs__abs_task`, or `abs_task` — use whichever form this session exposes.)',
+  // ① 锚点（2026-10-05 照 rpiv-todo 改写）：原写 `on the first file edit of a task` ——
+  //   实测太晚：那一刻注意力全在"要改什么"上，没人会想起登记。用户实报两次
+  //   （"侦察阶段全漏"、另一个 pi 会话干脆没登）。rpiv-todo 挂在
+  //   `immediately after receiving new instructions`（收到指令时）—— 早得多，且
+  //   侦察/只读工作（读代码、问需求）也落在"收到指令"之后，能被盖住。
+  'Use the abs task tool as soon as you receive instructions that involve changing this project — including investigation work where you read code or ask questions before any edit. Call it with action "start" and a short id before the work itself, not after. Skip it for pure questions about general knowledge, one-line answers, and conversation. (Tool name varies by host: `mcp__abs` with tool="abs_task", or `mcp__abs__abs_task`, or `abs_task` — use whichever form this session exposes.)',
+  // ② 完成即结：不许攒
   '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.',
+  // ④ 反例（照 rpiv-todo）：明确什么情况【不许】标完成 —— 只给正向要求时，
+  //   模型倾向于把"我以为做完了"当成完成，结语失真会污染下个会话的判断。
+  'Never mark a task "done" when tests are failing, the implementation is partial, or an error is unresolved — keep it in progress and add a task for the blocker instead.',
+  // ⑤ 唯一进行中（同 rpiv-todo）：看板要能回答"现在在做什么"，多的应转走。
+  'Keep exactly one task in "进行中" at a time; when the user switches direction or drops a task, use action "state" with 搁置 (dropped/not doing it); 滞留中 for still-wanted-but-stuck; 讨论中 for still-open. If you finish one and another is ready, promote it explicitly.',
+  // ⑥ 结语要真实：三种结语各有含义，别一律写落地。
+  'When completing, pick the honest conclusion via the `as` field: 落地 (built and verified) / 否决 (decided against, or built then reverted) / 仅方案 (designed only). A wrong conclusion makes the next session treat "considered" as "completed".',
 ]
 
 /** 当前项目是否有 .brain 图谱 —— 有才加指引（没图谱的项目里这指引是噪音）。
@@ -159,12 +198,83 @@ async function hasBrain(cwd: string): Promise<boolean> {
   }
 }
 
-function injectTodoGuidelines(options: any): boolean {
+/** 看板快照在 guidelines 里的前缀 —— 用于每轮替换上轮快照（内容会变，不能用 includes 去重）。 */
+const BOARD_MARK = '[看板] '
+
+/** 把当前看板拼成 Guidelines 里的一段（对齐用）。
+ *
+ * 设计（用户 2026-10-05 定）：**只对齐，不多说** —— 把「现在看板上有什么」摆在
+ * 面前让 LLM 自己对照，不写「记得登记」这类劝告（那些已证明会被忽略）。
+ *
+ * ★ 铁律（2026-10-05 用户定，别改）：
+ *   - **只用对齐，不用技术手段替 LLM 发现 todo 问题。**
+ *     今天最大的收获：技术只负责「摆事实」，不负责「发现问题、提醒、追踪、逼补记」。
+ *     让 LLM 自己看到、自己反思、自己决定 —— 这是唯一活下来的方向。
+ *   - **反复对齐，不厌其烦**：不是一次性提示，是**每一轮都摆**。
+ *     用户原话：「对齐永远是反反复复的对齐，不厌其烦」。
+ *     别用节流/去重/「刚说过就不重复」去优化掉它 —— 反复就是它的工作方式。
+ *   - **尺度：只说 todo.md 本身**。不夹带判断、不写劝告、不评价好坏。
+ *     只把「看板上现在有什么」摆出来。
+ *   - **是否添加/完成/删除/转状态，全部由 LLM 自己判断** —— 不替它决定，
+ *     不自动登记、不自动完成、不写看板。
+ *   - **不做重任务**：不起进程、不 spawn、不写盘；只读一个本地文件。
+ *   理由：前 12 次尝试都失败，根因是「让不掌握判据的一方启动动作」。
+ *   判据在 LLM 手里，这里只负责保证它**每轮都看得见**。
+ *   详见 concept remind-vs-gate（对齐必做 + 门禁兜底）。
+ *
+ * 与以前删掉的两种注入的本质区别：那不调 sendUserMessage（不插话、不抢 turn），
+ * 只改 system prompt 内容 —— 和静默的 TODO_GUIDELINES 走同一个通道。
+ *
+ * 看板空或全完成时不拼（没有可对齐的东西，拼个空列表纯占位）。 */
+export function boardGuideline(md: string, who: string, touched: string[] = []): string | null {
+  const { total, rows } = parseOpenTasks(md, PANEL_MAX_ROWS, who)
+  // 看板空但动过文件：仍要输出（「改了文件却没任务」正是最该对齐的时刻）。
+  if ((!total || !rows.length) && !touched.length) return null
+  const lines = rows.map((r) => {
+    // desc 为空时不拖空破折号（MCP 登记只给 id 的常见情形）。
+    const head = `  ${r.state ? `[${r.state}] ` : ''}${r.id}${r.desc ? ` — ${r.desc}` : ''}`
+    // 断点必须带上：它就是「改到哪一步」，丢了等于对齐了也接不上。
+    return r.note ? `${head}\n    ↳ ${r.note}` : head
+  })
+  const more = total > rows.length ? `  …另 ${total - rows.length} 条` : ''
+  // 本会话动过的文件 —— 与看板并列摆出，让 LLM 自己对照（不判断算不算任务）。
+  const touchLines = touched.length
+    ? ['本会话改过:', ...touched.map((f) => `  ${f}`)]
+    : []
+  return [
+    '当前 .brain/todo.md 看板（开工前对齐：正在做的算哪条？有新任务要加吗？有该删的吗？）:',
+    ...(lines.length ? lines : ['  （空）']),
+    ...(more ? [more] : []),
+    ...touchLines,
+  ].join('\n')
+}
+
+/** 读看板拼成对齐段。失败/无图谱/看板空都返 null（静默降级，绝不阻断对话）。 */
+async function readBoardForGuide(cwd: string): Promise<string | null> {
+  try {
+    const md = await readFile(join(cwd, '.brain', 'todo.md'), 'utf8')
+    return boardGuideline(md, await currentUser(), [...filesSeen])
+  } catch {
+    return null
+  }
+}
+
+/** 注入 todo 指引。静态 6 条（行为要求） + 实时看板（对齐用）—— 两者职责不同：
+ * 静态条说「该怎么做」，看板说「现在是什么」。 */
+export function injectTodoGuidelines(options: any, board?: string | null): 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)
   }
+  // 看板内容每轮会变（任务增减/状态转换），不能用 includes 去重 —— 先删上轮的旧快照再推。
+  // ★ 必须先删：board 为 null（看板空了/全完成）时同样要删 ——
+  //   曾只在 board 非空时删，结果看板清空后旧快照残留在 prompt 里，
+  //   LLM 会继续看到已经不存在的任务（对齐撒谎）。
+  for (let i = list.length - 1; i >= 0; i--) {
+    if (list[i].startsWith(BOARD_MARK)) list.splice(i, 1)
+  }
+  if (board) list.push(BOARD_MARK + board)
   return true
 }
 
@@ -504,7 +614,7 @@ export function renderPanelLines(
   nickname = '',
 ): string[] {
   if (data.total === 0) return []
-  const colorOf = (state: string): string => (state === '滞留中' ? 'muted' : state === '讨论中' ? 'dim' : 'accent')
+  const colorOf = (state: string): string => (state === '搁置' ? 'dim' : state === '滞留中' ? 'muted' : state === '讨论中' ? 'dim' : 'accent')
   const lines: string[] = []
   // 上描边：用 `thinkingOff` —— 跟 Pi 输入框描边**完全同一个色**。
   // 排查过程（2026-10-03 用户两轮反馈）：
@@ -606,6 +716,7 @@ export default function absPiHook(pi: ExtensionAPI): void {
   pi.on("session_start", (event: any, ctx: any) => {
     // 新会话 = 重新登记：不重置则同进程的第二个会话永远不再落断点
     autoTaskSeen = false
+    filesSeen.clear() // 同理：新会话的文件痕迹不能带到下个会话
     resetThrottle()
     // 本会话的随机昵称 —— 在这里抽一次（不是每帧抽，否则面板会疯狂闪）。
     // 每次 session_start（startup/reload/new/resume/fork）重抽 → “每次打开 pi 都是随机的”。
@@ -649,6 +760,12 @@ export default function absPiHook(pi: ExtensionAPI): void {
       const sid = sessionIdFor(ctx)
       logHook(`tool_call first_write name=${name} sid=${sid || '-'}`).catch(() => {})
     }
+    // 记下动过的文件（去重）—— 下一轮对齐时摆给 LLM（见 filesSeen 注释）。
+    // 每轮都记（不限首次）：一轮里改多个文件都要能看到。
+    if (isWriteCall(name, input)) {
+      const p = touchedPath(name, input)
+      if (p && filesSeen.size < FILES_SEEN_MAX) filesSeen.add(p)
+    }
   })
 
   pi.on("tool_execution_end", (_event: any, ctx: any) => {
@@ -676,7 +793,7 @@ export default function absPiHook(pi: ExtensionAPI): void {
           logHook(`before_agent_start todo_guide=off reason=no_brain`).catch(() => {})
           return
         }
-        const ok = injectTodoGuidelines(event?.systemPromptOptions)
+        const ok = injectTodoGuidelines(event?.systemPromptOptions, await readBoardForGuide(cwd))
         logHook(`before_agent_start todo_guide=${ok ? 'on' : 'off'} cwd=${cwd}`).catch(() => {})
 
         // 自动登记已整体移除（2026-10-05 用户实报两点）：

package/package.json

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

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

@@ -121,7 +121,7 @@ abs rule [add "一句话"]           # 读写 ## Rules；abs lint 体检；abs t
      结论：hook 只会"看到动过文件"，不知道"这是件什么事"；名字必须由读懂上下文的你起。
    - 名字要像 `fix-skill-trigger` / `fix-opencode-v2-plugin` 那样说清**在干什么**，
      不是抄用户的原话（实测抄出来的是 `我已经重启测试一下` 这种开场白）。
-   - 需要改已有任务的 id：`abs todo rename <旧id> --note "<新id>"`（描述同步换掉）。
+   - 需要改已有任务的 id：`abs todo rename <旧id> --note "<新id>"`。
 2. **一段活儿干完立刻 done** —— 不是等整个需求收尾。宁可拆成 5 条小的，别攒成 1 条大的。
 3. **动手超过两三轮还没登记 = 已在失控路上** —— 立刻补 `start`。
 

package/src/lint.js

@@ -3,8 +3,8 @@
 import { promises as fs } from 'node:fs';
 import { join } from 'node:path';
 import { requireBrain, brainPath, BRAIN_DIR } from './index.js';
-import { readRules, idOfPage, statusOfPage, supersededByOf, clip } from './store.js';
-import { doneKindOf, doneDateOf, checkFileShape } from './todo.js';
+import { readRules, idOfPage, statusOfPage, supersededByOf, clip, RULE_BODY_MAX } from './store.js';
+import { doneKindOf, doneDateOf, checkFileShape, TODO_MAX_LINES, LOG_MAX_LINES, INDEX_MAX_LINES } from './todo.js';
 
 // ---------- 图谱遍历 ----------
 
@@ -105,9 +105,6 @@ export async function listPages(vault) {
 // 为什么补这段（2026-10-05）：lint 此前只看 PAGE_DIRS 子目录，三个根文件不在扫描范围，
 // OVER-SIZE 也只对 concepts/entities/syntheses 生效。于是「todo.md 涨到上百行、
 // 断点行里塞实施报告」可以 lint 报 0 问题 —— 看着健康，实际已经变成笔记本。
-const TODO_MAX_LINES = 60;
-const LOG_MAX_LINES = 2000;
-const INDEX_MAX_LINES = 200;
 const LINT_BREAKPOINT_MAX = 200;
 
 async function checkRootFiles(vault) {
@@ -345,9 +342,11 @@ async function checkFiles(vault, pages, indexLinks) {
     if (found && items.length > LINT_RULES_MAX) {
       issues.push(`RULES-PILED-UP: Rules 区 ${items.length} 条 > ${LINT_RULES_MAX}；把长条目提炼成概念页，这里只留一句话`);
     }
-    const longOnes = items.filter((l) => l.trim().length > 160);
+    // 单条长度：与 cmdRule 用同一个阈值（RULE_BODY_MAX）—— 写入侧和体检侧必须同标准，
+    // 否则「手工编辑绕过写入校验」的条目静默通过，而 lint 报 0 问题（假健康）。
+    const longOnes = items.filter((l) => l.trim().length > RULE_BODY_MAX);
     if (longOnes.length) {
-      issues.push(`RULES-TOO-LONG: Rules 区 ${longOnes.length} 条超 160 字符（如 "${clip(longOnes[0].trim(), 40)}"）；展开写进概念页，这里只留一句话（不带链接）`);
+      issues.push(`RULES-TOO-LONG: Rules 区 ${longOnes.length} 条超 ${RULE_BODY_MAX} 字（如 "${clip(longOnes[0].trim(), 40)}"，${longOnes[0].trim().length} 字）；展开写进概念页，这里只留一句话`);
     }
   }
   return issues;

package/src/note.js

@@ -0,0 +1,275 @@
+// src/note.js — 经验实时暂存与知识页脚手架：note（一念一落）/ concept（骨架）/ person（人页）
+//              + registerInIndex（把新页登记进 index.md 清单区，三块都用到）。
+//
+// 从 store.js 拆出（2026-10-05）：原来 18 个职责挤在一个 1500+ 行文件里。
+// 依赖方向：note.js ← store.js（store 先 import 再 re-export，保持既有调用面）。
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { requireBrain, brainPath } from './index.js';
+import { requireUser, atTag } from './userconfig.js';
+import { today, localStamp, LOG_KINDS } from './todo.js';
+import { editFile, SKIP } from './lock.js';
+import { collapseIndex } from './page.js';
+import { impactOf } from './codegraph.js';
+import { clip, slugOf } from './text.js';
+
+// ---------- note: 经验实时暂存（source 页，一念一落，防流失） ----------
+const NOTE_DEDUP_MS = 60 * 1000;
+
+export async function cmdNote({ dir, text, tags, when, impact, type }) {
+  const clean = String(text || '').trim();
+  if (!clean) return '用法: abs note "经验/坑/技巧一句话" [--when "何时该读它"]（落 sources/ 暂存页，实时不流失）';
+  let root;
+  try {
+    root = await requireBrain(dir || process.cwd());
+  } catch {
+    return `未找到 .brain/ 图谱。先在项目根运行: abs init`;
+  }
+  const who = await requireUser(); // 写操作守卫
+  await ensurePersonPage(root, who); // 首次写操作即建人页（已存在不动）
+  const srcDir = brainPath(root, 'sources');
+  await fs.mkdir(srcDir, { recursive: true });
+  // 幂等: 同文本 60s 内只落一份
+  const existing = (await fs.readdir(srcDir).catch(() => [])).filter((f) => f.endsWith('.md'));
+  for (const f of existing) {
+    const body = await fs.readFile(join(srcDir, f), 'utf8').catch(() => '');
+    if (body.includes(clean)) {
+      return `• 60s 内已落同文本 → ${f} (跳过重复)`;
+    }
+  }
+  // 影响面（可选）：显式传 --impact <符号> 时，借本机 CodeGraph 拿「改它波及谁」。
+  // 失败/未装 codegraph 静默降级为无，绝不阻断 note 落盘。
+  const impactText = impact ? await impactOf(impact, root) : null;
+  // 类型（可选）：借鉴 TencentDB 的 L1 四分类，把自由文本经验分成可分类的资产。
+  // 默认不强制（自由文本仍是主体）；显式 --type 时才写进 frontmatter，供检索/load 区分。
+  // 合法值对齐 L1 四类：fact 事实 / pref 偏好 / constraint 约束 / event 事件。
+  const NOTE_TYPES = ['fact', 'pref', 'constraint', 'event'];
+  const noteType = NOTE_TYPES.includes(String(type || '').trim().toLowerCase())
+    ? String(type).trim().toLowerCase() : '';
+  const tagList = String(tags || '').split(',').map((t) => t.trim()).filter(Boolean);
+  const fmTags = ['source', ...tagList].join(', ');
+  const slugSrc = slugOf(clean);
+  const file = `${today()}-${slugSrc || 'note'}.md`;
+  const heading = clip(clean, 80); // 页面标题: 完整优先, 超长才收口
+  // 触发条件（2026-09-16）：经验"写入多读得少"的根因之一是存的是结论、不是"何时该看"。
+  // 带上 --when 后，load 的相关页推荐能按当前在做的事匹配，而不是按主题词。
+  const whenText = String(when || '').trim();
+  const body = [
+    '---',
+    `tags: [${fmTags}]`,
+    `id: ${file.replace(/\.md$/, '')}`,
+    `author: ${who}`,
+    `updated: ${today()}`,
+    'status: draft',
+    ...(noteType ? [`type: ${noteType}`] : []),
+    '---',
+    '',
+    `# 来源：${heading}`,
+    '',
+    `TITLE: ${clean}`,
+    ...(whenText ? ['', `WHEN: ${whenText}`] : []),
+    ...(impactText ? ['', '## 影响面（本机 CodeGraph 自动带出）', '```', impactText, '```'] : []),
+    '',
+    `## 记录（实时暂存，Teardown 时提炼进 concepts/ 后本页可删）`,
+    `- ${clean}`,
+    ...(whenText ? [`- 何时读：${whenText}`] : []),
+    '',
+    '## 关联连接',
+    `- ${atTag(who)} — 本页沉淀者`,
+    '（提炼成 concepts 规律页后，在此挂双链到该页）',
+    '',
+  ].join('\n');
+  // 源文件是新写唯一文件：tmp+rename 原子落盘（避免并发读读到半写文件）
+  const srcFile = join(srcDir, file);
+  const tmp = join(srcDir, `.${file}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`);
+  await fs.writeFile(tmp, body, 'utf8');
+  await fs.rename(tmp, srcFile);
+  // index Sources 区登记（锁内幂等：别页已登记则跳过，防并发重复） + log 一行
+  const slug = file.replace(/\.md$/, '');
+  await registerInIndex(root, 'Sources', slug, heading);
+  await cmdLog({ dir: root, title: clean, kind: 'note' });
+  return `✓ 经验暂存 → sources/${file}\n  ${clean} ${atTag(who)}`;
+}
+
+// ---------- concept: 概念页脚手架（给「写入」定结构，不替人做判断） ----------
+/** 建一张带骨架的概念页。
+ *
+ * 为何需要它（实测 2026-09-15）: concepts/ 页原来**没有任何代码写入路径** ——
+ * 全靠人/AI 手写 markdown，结果 26 页里 2 页完全没有「做完怎么确认」。
+ * 而骨架只写在 skill 的**文字里**（"触发场景/表现/解法/验证命令"），没有执行点 → 看运气。
+ * 对照: `abs note` 落的 source 页结构整齐，因为模板在**代码里**。
+ *
+ * 边界（关键）: 它只给**结构**，不给**内容**。
+ * 「这条值不值得留 / 归哪一页」仍靠人判断 —— 那是 skill 明写的分工（深提炼不自动化）。
+ * 所以本命令不猜语义、不自动提炼，只在你要新建页时把该有的位置摆好。
+ *
+ * 尾巴用「占位符」而非真实值: 这样 lint 的 NO-TAIL 判据在占位未填时仍会报
+ * （骨架≠完成）。填完删掉占位行即可。 */
+export async function cmdConcept({ dir, slug, title, tags, desc }) {
+  let root;
+  try {
+    root = await requireBrain(dir || process.cwd());
+  } catch {
+    return `未找到 .brain/ 图谱。先在项目根运行: abs init`;
+  }
+  const raw = String(slug || '').trim();
+  if (!raw) {
+    return [
+      '用法: abs concept <slug> --title "一句话标题" [--tags a,b] [--desc "index 里的一句话"]',
+      '  例: abs concept docker-prisma-429 --title "Docker 内存超限导致 Prisma 429"',
+      '  说明: 只给骨架（头/中/尾位置），内容仍由你写 —— 判断不自动化。',
+    ].join('\n');
+  }
+  // slug 即文件名（命名即链接）。收口掉路径分隔符与空白，防逃出 concepts/。
+  const name = raw.replace(/[\s/\\]+/g, '-').replace(/[^\w\u4e00-\u9fff.-]/g, '').replace(/^-+|-+$/g, '');
+  if (!name) return `✗ slug 无效（清洗后为空）: ${raw}`;
+  const who = await requireUser();
+  await ensurePersonPage(root, who);
+  const dirP = brainPath(root, 'concepts');
+  await fs.mkdir(dirP, { recursive: true });
+  const file = join(dirP, `${name}.md`);
+  const head = String(title || '').trim() || name;
+  const tagList = ['concept', ...String(tags || '').split(',').map((t) => t.trim()).filter(Boolean)];
+  const body = [
+    '---',
+    `tags: [${tagList.join(', ')}]`,
+    `id: ${name}`,
+    `author: ${who}`,
+    `updated: ${today()}`,
+    'status: draft',
+    '---',
+    '',
+    `# 概念：${head}`,
+    '',
+    '## 触发场景',
+    '<!-- 什么情况下该想起这条？（写可检索的词，别只写“遇到问题”） -->',
+    '',
+    '## ❌ 表现',
+    '<!-- 具体症状 / 贴报错 / 复现条件 -->',
+    '',
+    '## 🛠 解法',
+    '<!-- 根因 + 修复 -->',
+    '',
+    '## 验证',
+    '<!-- 做完怎么确认？跑什么命令 / 看什么信号 / 用什么判据。必须填 —— 没尾巴的经验只能被“相信”，不能被“验证” -->',
+    '',
+    '## 关联连接',
+    `- ${atTag(who)} — 本页沉淀者`,
+    '（在这挂相关页双链，别留孤岛）',
+    '',
+  ].join('\n');
+  // 独占写（wx）：已存在则 EEXIST —— 与 ensurePersonPage 同路数。
+  // 不用「先查后写」：那有 TOCTOU 竞态，且已有人工内容一律不覆盖是本仓硬规则。
+  // 也不走 tmp+rename：rename 会默默覆盖已存在文件，而这里必须「存在就拒绝」。
+  try {
+    await fs.writeFile(file, body, { encoding: 'utf8', flag: 'wx' });
+  } catch (e) {
+    if (e.code === 'EEXIST') {
+      return `• 已存在，不覆盖 → .brain/concepts/${name}.md\n  要改请直接编辑（或先删页）；新建请换个 slug。`;
+    }
+    throw e;
+  }
+  const oneLine = String(desc || '').trim() || clip(head, 60);
+  await registerInIndex(root, 'Concepts', name, oneLine);
+  // 不写 log.md（2026-10-05 用户定）：`新建概念页 x` 是**命令的副作用**不是成果 ——
+  // 38 字符、零信息量，且「该页存在」已由 registerInIndex 落在 index.md 的 Concepts 区
+  // （那是 index 的职责）。同件事落两处，且建 10 个页 = 10 行流水噪声自动重现，
+  // 靠事后清理治不了。故删掉这次调用，不加开关（没人需要读「某页被创建了」）。
+  return `✓ 概念页骨架 → .brain/concepts/${name}.md ${atTag(who)}\n` +
+    '  已给好四段位置；填完内容后：删掉 <!-- --> 占位、按需改 status: active、挂双链。\n' +
+    '  尾部「## 验证」必须填（留空会被 abs lint 报 NO-TAIL）。';
+}
+
+// ---------- person: 使用者实体页（首次需要时创建，已存在则不动） ----------
+/** 确保 entities/<name>.md 存在。已存在一律不动（里面的技术栈/特点是人工沉淀的）。
+ * 用 `wx` 独占写：并发下后到者拿到 EEXIST 就静默跳过，不覆盖。
+ * 失败不抛：建页是附带动作，不能因为它让 todo/log 写不进去。
+ * 返回 'created' | 'exists' | 'skip'。 */
+export async function ensurePersonPage(root, name) {
+  const nm = String(name || '').trim();
+  if (!nm || !/^[\w\u4e00-\u9fff.-]+$/.test(nm)) return 'skip';
+  const dir = brainPath(root, 'entities');
+  const file = join(dir, `${nm}.md`);
+  const body = [
+    '---',
+    'tags: [entity, person]',
+    `id: ${nm}`,
+    `author: ${nm}`,
+    `updated: ${today()}`,
+    'status: draft',
+    '---',
+    '',
+    `# ${nm}`,
+    '',
+    '## 技术栈',
+    '<!-- 沉淀时填: 主力语言/框架/工具链。例: TypeScript + Node, 熟悉 MCP 协议与 CLI 工具链 -->',
+    '',
+    '## 特点 / 工作习惯',
+    '<!-- 沉淀时填: 决策偏好、沟通习惯、反复出现的判断倾向。例: 先要方案后动手; 质疑"这需求是否需要存在" -->',
+    '',
+    '## 名下踩过的坑',
+    '（本页被 [[todo]] / [[log]] 里的作者标记引用；沉淀经验时在此挂双链）',
+    '',
+  ].join('\n');
+  try {
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(file, body, { encoding: 'utf8', flag: 'wx' });
+  } catch (e) {
+    if (e.code === 'EEXIST') return 'exists';
+    return 'skip';
+  }
+  // 只有真建成才登记 index（否则 index 指向不存在的页 → INDEX-DEAD-LINK）。
+  // 放这里而非各调用点：todo/log/note 三条写路径都要登记，抄三遍必漂。
+  await registerInIndex(root, 'Entities', nm, `${nm} — 使用者；技术栈 / 特点 / 名下踩过的坑`);
+  return 'created';
+}
+
+/** 把新页登记进 index.md 的指定分区（幂等）。供人页/其它程序建页用。 */
+export async function registerInIndex(root, section, slug, desc) {
+  const iP = brainPath(root, 'index.md');
+  await editFile(iP, (index) => {
+    if (!index || index.includes(`[[${slug}]]`)) return SKIP;
+    const sIdx = index.indexOf(`## ${section}`);
+    if (sIdx === -1) return SKIP;
+    const after = index.indexOf('\n## ', sIdx + 1);
+    const line = `- [[${slug}]] — ${desc}`;
+    const next = after === -1
+      ? `${index.replace(/\s*$/, '')}\n${line}\n`
+      : index.slice(0, after) + `\n${line}` + index.slice(after);
+    // 归一空行：历史手工编辑会留 3+ 空行（load 时 collapseIndex 会压掉，但文件本身没清）。
+    // 追加新条目的同时顺手压一次，既清旧债又不改内容（与 collapseIndex 同一判据）。
+    return { text: next.replace(/\n{3,}/g, '\n\n') };
+  });
+}
+// ---------- log: 追加工作成果沉淀摘要（用户/AI 主动 abs log "..." 记, 不收工具动作流水） ----------
+export async function cmdLog({ dir, title, kind = 'dev' }) {
+  const root = await requireBrain(dir || process.cwd());
+  const who = await requireUser(); // 写操作守卫
+  // ★ kind 必须是枚举值（2026-10-05 加）：此前无校验，传什么写什么 ——
+  //   实测有测试传 kind:'test' 写进去，而形状闸门上线后才暴露。
+  //   枚举内校在**入口**（这里）比事后 lint 更早，且报错能直接告诉可用值。
+  if (!LOG_KINDS.includes(String(kind))) {
+    throw new Error(
+      `✗ log 的 kind 只能是 ${LOG_KINDS.join(' / ')}（收到 "${kind}"）\n` +
+      `  note=经验/踩坑 / dev=完成的工作 / concept=新建概念页 / ingest=沉淀资料`,
+    );
+  }
+  await ensurePersonPage(root, who); // 首次写操作即建人页（已存在不动）
+  const p = brainPath(root, 'log.md');
+  const stamp = localStamp();
+  // 不硬切: log.md 是人类读的成果摘要, 也是 abs load 的开机入口。600 码点够一条完整小结,
+  // 超出才在语义边界收口（曾 slice(0,100) → 34/85 条断在词中间）
+  const clean = clip(String(title || '').replace(/\n/g, ' '), 600);
+  // 作者前置于 kind：`## [时间] @name dev | 内容`。
+  // 一眼先看到谁做的（与 todo 行 `ID @name — 说明` 排版对齐）。
+  const line = `## [${stamp}] ${atTag(who)} ${kind} | ${clean}`;
+  await editFile(p, (cur) => {
+    const text = cur ?? '# 🗒 Activity Log\n';
+    // 倒序：新行插在标题后（若已是模板占位行则替换它）
+    const lines = text.split('\n');
+    const headerIdx = lines.findIndex((l) => l.startsWith('#'));
+    lines.splice(headerIdx + 1, 0, line);
+    return { text: lines.join('\n') };
+  });
+  return `✓ log → ${p}\n  ${line}`;
+}