@fanchao8609/agent_brain_sync 1.31.1 → 1.31.3

package/README.md

@@ -172,7 +172,7 @@ npm i -g @fanchao8609/agent_brain_sync@latest
 abs install    # 重新刷 hook/skill
 ```
 
-> ⚠️ 改完源码（尤其 `skill/*/SKILL.md`、`src/`）后**必须 `abs install --yes` 重扇出**，否则宿主还在跑旧副本 —— 版本号与代码会脱节。发布用 `npm version patch`（自动打 tag），别手改 `package.json` 的 version；发布后 `npm view` 有缓存延迟，必要时 `npm cache clean --force` 再验。
+> ⚠️ 改完源码（尤其 `skill/*/SKILL.md`、`src/`）后**必须重扇出**，否则宿主还在跑旧副本 —— 版本号与代码会脱节。TTY 下跑 `abs install` 选宿主；脚本/CI 里 `abs install --agent pi --yes`（`--yes` 只装默认的 pi，不是全部）。发布用 `npm version patch`（自动打 tag），别手改 `package.json` 的 version；发布后 `npm view` 有缓存延迟，必要时 `npm cache clean --force` 再验。
 
 ---
 

package/bin/abs.js

@@ -410,8 +410,8 @@ const subUsage = {
     '',
     '参数:',
     '  --agent <宿主>   只装一个宿主: claude-code | codex | opencode | pi | omp',
-    '                   (不传则在 TTY 下交互多选; 非 TTY / --yes 时为全部)',
-    '  --yes            不交互，直接装全部宿主（自动化用）',
+    '                   (不传则在 TTY 下交互多选; 非 TTY / --yes 时只装默认的 pi)',
+    '  --yes            不交互（只装默认的 pi；要装全部用 --all）',
     '  --no-mcp         不注册 MCP server',
     '  --no-skill       不装 skill',
     '',
@@ -422,7 +422,8 @@ const subUsage = {
     '',
     '例:',
     '  abs install                    交互选择',
-    '  abs install --yes              全部宿主',
+    '  abs install --all              全部宿主',
+    '  abs install --yes              不问，只装 pi',
     '  abs install --agent pi --yes   只装 pi',
   ].join('\n'),
   uninstall: [

package/hooks/abs.pi.ts

@@ -265,7 +265,14 @@ const TODO_GUIDELINES = [
   // ⑧ 有疑惑先查记忆（用户 2026-11-03 定）：主动搜索不是等报错才应激，
   //   而是「心里形成关键词/有疑问的那一刻」自己查。上面七条只讲了登记，
   //   没讲「记下来的东西怎么取」——实测一场会话从头到尾没查过一次记忆。
-  'When a doubt forms about something the project has likely dealt with before (a design choice, a past bug, a convention), run `abs recall <关键词>` (or `abs query <词>` for wider matches) BEFORE acting on the assumption. Do not wait for an error or for the user to remind you — asking the memory is your own decision, made the moment the question arises.',
+  //   ★ 2026-11-09 修：原来写的是 `abs recall`，那个命令 11-08 就删了 ——
+  //     规矩给成不存在的命令，模型只能白撞一次。
+  'When a doubt forms about something the project has likely dealt with before (a design choice, a past bug, a convention), run `abs query <关键词>` BEFORE acting on the assumption. Do not wait for an error or for the user to remind you — asking the memory is your own decision, made the moment the question arises.',
+  // ⑨ 参数规矩要说在**前面**（用户 2026-11-09 提：闸门拦得住，但得先告诉模型规矩）。
+  //   起因：另一个 pi 会话（pi-capsule-tools）连撞两次 —— ① 不传 cwd → 被 schema 拒；
+  //   ② 把整句话当 id → 被「id 不能含空格」拒。两次都是「没提前说」而不是「不会做」。
+  //   放在常驻指引里而不是只靠工具 description：description 模型常不读。
+  'abs task tool parameters — wrong ones are rejected before anything is written, so get them right the first time: `cwd` = the project root that contains `.brain/` and is ALWAYS required; `id` = ONE word, no spaces / tabs / brackets (put the readable name in `note`); `start`/`add` require `note` (what to do, one sentence); `child_done` / `child_undone` / `state` take `n` = which child item (1-based, default = last); `done` takes the conclusion in `note` plus `as` (落地 / 否决 / 仅方案). A child row must keep `note` to ONE short sentence (≤200 字) — longer text goes to `abs log` (progress) or `abs note` (lessons), not the board.',
 ]
 
 /** 当前项目是否有 .brain 图谱 —— 有才加指引（没图谱的项目里这指引是噪音）。
@@ -526,7 +533,7 @@ export function injectSessionGuideline(options: any, sid: string): boolean {
   return true
 }
 
-/** 注入 todo 指引。静态 6 条（行为要求） + 实时看板（对齐用）—— 两者职责不同：
+/** 注入 todo 指引。静态 9 条（行为要求 + 参数规矩） + 实时看板（对齐用）—— 两者职责不同：
  * 静态条说「该怎么做」，看板说「现在是什么」。 */
 export function injectTodoGuidelines(options: any, board?: string | null): boolean {
   if (String(process.env.ABS_TODO_GUIDE || '') === '0') return false
@@ -556,8 +563,8 @@ const LOAD_MARK = '[开工] '
  *   每次开会话都多塞 200 行，而其中大部分（图谱组织/容量纪律/tesardown 流程）
  *   只在真正做 abs 维护时才用得上。
  *
- * 与【常驻 6 条】TODO_GUIDELINES 的区别（两者职责不同，别合并）：
- *   - 6 条常驻：行为要求，每轮都在（看板对齐用）。
+ * 与【常驻 9 条】TODO_GUIDELINES 的区别（两者职责不同，别合并）：
+ *   - 9 条常驻：行为要求与参数规矩，每轮都在（看板对齐用）。
  *   - 这 3 条：**只在开工第一轮出现一次** —— 因为它们是「开工那一刻」的触发器，
  *     每次都说等于噪音（历史教训：静态指引有痕 414 次、行为 0 变化）。
  *

package/hooks/event.sh

@@ -13,7 +13,11 @@ ABS_BIN="__ABS_BIN__"
 NODE_BIN="__NODE_BIN__"
 EVENT="__EVENT__"
 
-PAYLOAD=$(cat 2>/dev/null | head -c 500)
+# 全文收下（Stop 的 transcript_path / session_id 可能在 500 字节之外，截断会让
+# teardown-check 解析不到字段）。日志行仍另截 120；指纹用这份全文（上限 64KB），
+# 旧版只指纹前 500 字节：两个不同事件开头相同时会被当重复丢掉。
+# 64KB 对 hook 元数据足够，又不至于把 MB 级 prompt 整个摚进 shell 变量。
+PAYLOAD=$(cat 2>/dev/null | head -c 65536)
 
 # ── Stop 收尾注入 (CC/Co​dex 的"主动推") ─────────────────────────────────
 # 守卫同 pi 插件四条件: ①本会话真改过文件 ②本项目有 .brain ③log.md 今日无条目 ④每会话一次。

package/package.json

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

package/src/brain/gate.js

@@ -4,12 +4,15 @@
 import { setFormatGate } from '../lock.js';
 import { enforceBrainFormat, ensureStateMark } from '../todo.js';
 import { BRAIN_SHAPE, legacyRenames } from './shape.js';
+import { basename } from 'node:path';
 
 /** 写入侧格式闸门：lock.js 的 editFile 是所有写入的唯一收口，
  * 这里把「哪个文件名用哪套标准」告诉它 —— 三个目标文件之外的写入一律放行。
  * 非目标文件返回 null 表示不管。 */
 setFormatGate((file, text, current) => {
-  const name = file.split('/').pop();
+  // basename 而不是 split('/')：Windows 路径是反斜杠，split 取不到文件名，
+  // 闸门会静默放行（等于没装）。install.js 有 win32 候选，Windows 是支持目标。
+  const name = basename(file);
   const spec = BRAIN_SHAPE[name];
   if (!spec) return null;
   const r = enforceBrainFormat(text, { ...spec, renames: legacyRenames() }, current);

package/src/brain/ingest.js

@@ -332,9 +332,10 @@ export async function cmdIngest({ dir, file, force = false, mark = false, last =
     hit = best;
   } else {
     const want = basename(String(file).trim());
+    // 子串匹配必须够长（≥8）：短词会把「日志」「test」这类撞上任意文件名，
+    // 静默选错会话。精确同名仍然放行。
     hit = names.find((n) => n === want)
-      || names.find((n) => want.length >= 8 && n.includes(want))
-      || names.find((n) => n.includes(want));
+      || (want.length >= 8 && names.find((n) => n.includes(want)));
     if (!hit) {
       return `✗ 会话目录里找不到 "${want}"。\n  可用: abs summon（列出待总结的会话）`;
     }

package/src/brain/load.js

@@ -17,7 +17,7 @@ const SESSION_UNFILLED_SHOW = 5;
 /** 开机屏的使用方法（2026-11-08 用户定 load 三件套之一）。一行一个动作，别写成手册。 */
 const LOAD_USAGE = [
   '--- 用法 ---',
-  '接经验   abs search <词> / abs recall     记一句   abs note "…"',
+  '查经验   abs query <词>                记一句   abs note "…"',
   '立概念   abs concept <id> --title "…"      登记活   abs todo start <id> --note "做什么"',
   '收尾     abs todo done <id> --as 落地|否决|仅方案 "结论"',
   '体检     abs lint        看全量     abs show index|log|status',

package/src/install.js

@@ -634,7 +634,10 @@ async function uninstallClaudeCode() {
   if (settings && settings.mcpServers && settings.mcpServers.abs) {
     delete settings.mcpServers.abs; touched = true;
   }
-  if (touched) await atomicWrite(settingsP, JSON.stringify(settings, null, 2));
+  if (touched) {
+    await backup(settingsP);
+    await atomicWrite(settingsP, JSON.stringify(settings, null, 2));
+  }
   if (settings) steps.push(`✓ hooks/MCP 已从 ${settingsP} 移除`);
   // staged hook 脚本目录 —— 只删本 agent 的，绝不整删 ~/.abs/（其它 agent 的 hook / mcp.log 共存）
   await fs.rm(join(homedir(), '.abs', 'hooks', 'claude-code'), { recursive: true, force: true });
@@ -751,6 +754,7 @@ async function uninstallCodex() {
     }
   }
   if (changed) {
+    await backup(p);
     await atomicWrite(p, JSON.stringify(cfg, null, 2));
     steps.push(`✓ hooks 已从 ${p} 移除`);
   }
@@ -761,6 +765,7 @@ async function uninstallCodex() {
     // 留下非法行 ["/…/mcp.js"] 让用户的 TOML 解析失败。
     const { text: after, removed } = removeTomlAbsSection(text);
     if (removed) {
+      await backup(mcpP);
       await atomicWrite(mcpP, after);
       steps.push(`✓ MCP 已从 ${mcpP} 移除`);
     }
@@ -889,6 +894,7 @@ async function uninstallOpenCode() {
   }
   if (cfg && cfg.mcp && cfg.mcp.abs) {
     delete cfg.mcp.abs;
+    await backup(mcpP);
     await atomicWrite(mcpP, JSON.stringify(cfg, null, 2));
     steps.push(`✓ MCP 已从 ${mcpP} 移除`);
   }
@@ -949,6 +955,7 @@ async function uninstallPi() {
   }
   if (cfg && cfg.mcpServers && cfg.mcpServers.abs) {
     delete cfg.mcpServers.abs;
+    await backup(mcpP);
     await atomicWrite(mcpP, JSON.stringify(cfg, null, 2));
     steps.push(`✓ MCP 已从 ${mcpP} 移除`);
   }
@@ -1001,6 +1008,7 @@ async function uninstallOmp() {
   }
   if (cfg && cfg.mcpServers && cfg.mcpServers.abs) {
     delete cfg.mcpServers.abs;
+    await backup(mcpP);
     await atomicWrite(mcpP, JSON.stringify(cfg, null, 2));
     steps.push(`✓ MCP 已从 ${mcpP} 移除`);
   }

package/src/lock.js

@@ -32,10 +32,22 @@ const LOCK_WAIT_MAX_MS = 150;  // 指数退避上限
 // 抢锁总预算：排队等锁的进程须依次排完。多进程高并发(CLI/MCP/hook 同刻抢一文件)下,
 // 3s 会让后到进程在排队中途 LockTimeout 崩溃丢写入。设 30s 容纳大批排队者正常排完。
 const LOCK_MAX_WAIT_MS = 30 * 1000;
-// 超过此年龄视为残留锁(持锁进程崩溃没释放)，允许摘除。须 > LOCK_MAX_WAIT_MS，
-// 否则持锁进程在排队预算内会被误当残留摘除导致临界区重叠。
+// 兜底年龄：锁文件里没有有效 PID 时（旧版空锁 / PID 读不出），超过此年龄才当残留摘除。
+// 有 PID 后不再按年龄摘活人的锁 —— mutator 跑慢一点也不能让两个进程同时进临界区。
 const STALE_MS = 60 * 1000;
 
+/** 进程还活着吗。true=活 / false=已死 / null=判不了（没写 PID、权限不够等）。 */
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    // ESRCH = 没这个进程；其它（权限等）当活着，宁可等也不误抢
+    return e.code === 'ESRCH' ? false : true;
+  }
+}
+
 async function acquireLock(lockPath) {
   const start = Date.now();
   let backoff = LOCK_WAIT_BASE_MS;
@@ -43,20 +55,35 @@ async function acquireLock(lockPath) {
     let handle = null;
     try {
       handle = await fs.open(lockPath, 'wx'); // 原子创建(O_EXCL)；已存在则抛 EEXIST → 排队等
+      // 写入 PID：后来者据此判断持锁人是否已死（崩溃残留可立刻摘，不等 60s）。
+      // 写 PID 失败不回滚 —— 空锁退回按年龄判残留，锁本身仍然有效。
+      await handle.writeFile(String(process.pid), 'utf8').catch(() => {});
       await handle.close(); // 锁的存在即持有信号；无需保持 fd
       return;
     } catch (e) {
       if (handle) await handle.close().catch(() => {});
       if (e.code !== 'EEXIST') throw e;
-      // 残留锁检测：锁太老(持锁进程崩溃没释放)则摘除重试；正常排队者持锁时间远小于阈值
+      // 残留锁检测：优先看 PID（持锁进程已死 → 立刻摘，不等 60s）；
+      // PID 读不出再退回按年龄（兼容旧版空锁文件）。
+      // ★ 持锁进程还活着就绝不摘 —— 哪怕超过 STALE_MS。
+      //   旧逻辑按 60s 硬摘，mutator 跑慢一点就让两个进程同时进临界区（2026-11-10 审查）。
       try {
-        const st = await fs.stat(lockPath);
-        if (Date.now() - st.mtimeMs > STALE_MS) {
+        const raw = (await fs.readFile(lockPath, 'utf8')).trim();
+        const alive = pidAlive(Number(raw));
+        if (alive === false) {
           await fs.rm(lockPath, { force: true });
-          backoff = LOCK_WAIT_BASE_MS; // 摘除残留后重置退避
+          backoff = LOCK_WAIT_BASE_MS;
           continue;
         }
-      } catch { /* stat 失败(锁刚被释放) → 下一轮重试 */ }
+        if (alive === null) {
+          const st = await fs.stat(lockPath);
+          if (Date.now() - st.mtimeMs > STALE_MS) {
+            await fs.rm(lockPath, { force: true });
+            backoff = LOCK_WAIT_BASE_MS;
+            continue;
+          }
+        }
+      } catch { /* 读锁失败(刚被释放) → 下一轮重试 */ }
       if (Date.now() - start > LOCK_MAX_WAIT_MS) {
         throw new LockTimeout(`写锁排队超时(等 ${Date.now() - start}ms > 预算 ${LOCK_MAX_WAIT_MS}ms): ${lockPath} 仍被占用`);
       }
@@ -98,7 +125,18 @@ export async function editFile(file, mutator) {
       if (gate) write = gate(file, write, current) ?? write;
     }
     if (write && write !== current) {
-      await fs.writeFile(file, write, 'utf8');
+      // 原子落盘：先写同目录临时文件再 rename。
+      // fs.writeFile 是「截断再写」，进程死在中间 = 图谱剩半截/空文件。
+      // rename 在同一文件系统上是原子的 —— 读方要么见旧要么见新，不见半截。
+      // tmp 名带随机段：同毫秒两个进程写同一文件也不会撞名（summon.js 同坑）。
+      const tmp = join(dirname(file), `.${basename(file)}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+      try {
+        await fs.writeFile(tmp, write, 'utf8');
+        await fs.rename(tmp, file);
+      } catch (e) {
+        await fs.rm(tmp, { force: true }).catch(() => {});
+        throw e;
+      }
     }
     return res;
   } finally {

package/src/todo/task-cmd.js

@@ -9,15 +9,22 @@ import { ensurePersonPage } from '../note.js';
 
 // 纪律: task 过程动作(start/done/note/blocked)只改 todo.md, 不写 log.md。
 // log.md 是「工作成果沉淀摘要」(用户/AI 主动 abs log "..." 记), 不收工具动作流水。
+/** 任务 id 的合法形状：一个词，不含空白 / 路径分隔符 / 方括号。
+ *  为什么这么严（2026-11-10 审查实测）：
+ *  ① 空白会被 extractId 截断（静默丢信息）；换行还会往 todo.md 里注一行。
+ *  ② `/` `\` 会被 setMemo 拼进文件名写出 .brain/ 外（路径穿越，`../..` 实测逃逸）。
+ *  ③ `[` `]` 撞行首状态标记 `[进行中]` 的语法。
+ *  旧注释写了「不能含方括号」，代码只查了空格 tab —— 这次收口。 */
+function isValidId(s) {
+  return !/[\s\\/\0[\]]/.test(s);
+}
+
 export async function cmdTask({ dir, action, id, section, note, as, session, n }) {
-  // ★ id 校验（2026-10-16 模糊测试找出来的真 bug）：id 不能含空白/方括号。
-  //   不校就是**静默丢信息**：id="带 空格" 写进文件时被 extractId 截成 "带"，
-  //   后面的 "空格" 与描述一起消失，不报错（实测：`abs todo start "带 空格"` 落成 `- [ ] 带`）。
-  //   宁可明确拒掉，也不替人猜哪个词算 id。
+  // ★ id 校验：宁可明确拒掉，也不替人猜哪个词算 id、不把怪 id 写出图谱外。
   const idStr = id === undefined || id === null ? '' : String(id);
-  if (idStr && (idStr.includes(' ') || idStr.includes('\t'))) {
+  if (idStr && !isValidId(idStr)) {
     throw new Error(
-      `✗ 任务 id 不能含空格（收到 "${idStr}"）—— id 是一个词，空白会被当分隔符。\n` +
+      `✗ 任务 id 不能含空格、/、\\、[、]（收到 "${idStr}"）—— id 是一个词，也会被拼进文件名。\n` +
       `  想要带空格的名字：用连字符或下划线；完整名称写进 --note。`,
     );
   }
@@ -113,7 +120,7 @@ export async function cmdTask({ dir, action, id, section, note, as, session, n }
     // --note 传新 id（沿用既有 CLI 习惯，免得再加一个 flag）。
     if (!note) throw new Error('✗ 用法: abs todo rename <旧id> --note "<新id>"');
     const newId = String(note).replace(/[\u200b\u200c\u200d\ufeff]/g, '').trim();
-    if (!newId || /\s/.test(newId)) throw new Error(`✗ 新 id 不能为空或含空白: "${newId}"`);
+    if (!newId || !isValidId(newId)) throw new Error(`✗ 新 id 不能为空，且不能含空白、/、\\、[、]: "${newId}"`);
     const f = brainPath(root, 'todo.md');
     let done = false;
     await editFile(f, (cur) => {