@fanchao8609/agent_brain_sync 1.2.0 → 1.2.2

package/README.md

@@ -1,96 +1,123 @@
-# abs — agent-brain-sync 跨会话 AI 编码记忆
+# abs — agent-brain-sync
 
-跨会话记忆的机械落盘：**hook 纯触发 → CLI/MCP 读写 → markdown 图谱（`.brain/`，可进 git）**。
-让每个会话不再无状态——经验/进度/踩坑有统一落点，重开不"失忆"。
-参考 [ai-memory](https://github.com/akitaonrails/ai-memory) 的接入机制，砍掉全部重引擎。
+**跨会话 AI 编码记忆。** 让 AI 会话不再「重开就失忆」：任务进度、经验、踩坑都落盘到项目里的 markdown 图谱，下一个会话开机能直接读回来。
 
-> npm 发布名 `@fanchao8609/agent_brain_sync`（因 `agent-brain-sync` 已存在、相似名被 npm 拦截）；全局命令 `abs`（包名与命令名独立）。
+- 图谱纯 markdown，放在项目根 `.brain/`，**可以进 git**，人和 AI 读同一份
+- 多项目自动隔离：从当前目录向上找最近的 `.brain/`
+- 并发安全：CLI / MCP / hook 同时写不会互相覆盖
 
-## 架构
+npm 包名 `@fanchao8609/agent_brain_sync`，全局命令 **`abs`**。
 
+---
+
+## 安装
+
+```bash
+npm install -g @fanchao8609/agent_brain_sync
+abs install
 ```
-hook (宿主事件, 纯触发) ──▶ abs log (一行技术流水, fire-and-forget, 不阻塞)
-agent (会话中)          ──▶ MCP (abs_load/abs_board/abs_task/…) ──▶ 读写 .brain/
-人   (终端)             ──▶ abs CLI 同一套读写
+
+`abs install` 会交互式让你勾选智能体；也可以直接指定：
+
+```bash
+abs install --agent pi            # 只装 pi
+abs install                       # 全部: claude-code / codex / opencode / pi
+abs install --agent pi --no-mcp   # 只装 hook + skill，不要 MCP
 ```
 
-- **唯一真源**: `<项目>/.brain/`（index/todo/log + concepts/entities/sources/syntheses/sessions）
-- **多项目隔离**: 任何读写先从 cwd 向上找最近 `.brain/`（代码写死，MCP 无状态，各会话各归各位）
-- **三层分工**:
-  - **hook（机械层）**：宿主生命周期事件 → 只写技术日志（`~/.abs/log/`），不碰图谱 todo/log.md
-  - **CLI/MCP（实时层）**：任务/经验实时落盘（`abs task start/note/blocked/done`、`abs note`）
-  - **skill（自觉层）**：深提炼（sources→concepts）+ 收尾循环（详见 skill/SKILL.md）
-- **并发写保护**: 所有 .brain 读改写经 `lock.editFile`（`open wx` 原子锁 + 排队等锁 + SKIP 哨兵），跨进程(CLI/MCP/hook)同写不覆盖丢更新
+装了什么：
 
-## 安装
+| 宿主 | hook | MCP | skill |
+|---|---|---|---|
+| claude-code | `~/.claude/settings.json` hooks | `mcpServers.abs` (stdio) | `~/.claude/skills/abs-agent-brain-sync/` |
+| codex | `~/.codex/hooks.json` | config.toml `[mcp_servers.abs]` | `~/.codex/skills/` |
+| opencode | `~/.config/opencode/plugins/abs.ts` | opencode.json mcp.abs | skills/ |
+| pi | `~/.pi/agent/extensions/abs.ts` | extension 内桥接 | skills/ |
+
+- **幂等**：重复安装 = 更新，写入前自动备份
+- **共存**：追加式合并，不会顶掉你这个事件上的其它 hook
+- 装完**重启宿主**才生效
 
-### 方式一：npm 全局安装（产品模式，推荐）
+从源码跑（开发用）：
 
 ```bash
-npm install -g @fanchao8609/agent_brain_sync
-abs install                    # 交互式选智能体（或 --agent 指定）
+git clone <repo-url> && cd agent_brain_sync
+npm install && npm link        # 之后全局就有 abs
 ```
 
-### 方式二：从源码（开发）
+---
+
+## 怎么用
+
+### 项目里开一次
 
 ```bash
-git clone <repo> && cd <repo> && npm install
-node bin/abs.js install        # 或先 npm link 使 `abs` 全局可用
+cd 你的项目
+abs init          # 建 .brain/ 图谱，只需一次
 ```
 
-### 安装到宿主（hook + MCP + skill）
+### 日常命令
 
 ```bash
-abs install                     # 全部: claude-code codex opencode pi
-abs install --agent claude-code # 只装 Claude Code (MCP+hook+skill)
-abs install --agent claude-code --no-mcp   # 只 hook+skill
+abs load                       # 开机读状态（路线 + 看板 + 最近流水）
+abs todo                       # 看板 Today / In Progress / Blocked / Done
+
+abs task start   TASK-1 --note "要做什么"
+abs task note    TASK-1 --note "改到 X 文件 L40"   # 实时断点
+abs task blocked TASK-1 --note "卡在哪"
+abs task done    TASK-1
+
+abs note "一句话经验" --tags 坑,docker    # 经验暂存 → sources/
+abs log "完成 X"                          # 记一行流水；abs log 无参 = 查看
+abs query <词>                            # 检索图谱（多词 OR）
+abs status                                # 当前项目 + 图谱概要
+abs lint                                  # 体检：死链/孤岛/超尺寸/堆积
+```
+
+### 工作流
+
+- **hook 自动**：宿主生命周期事件写技术流水到 `~/.abs/log/`
+- **实时层（你/AI 手动）**：任务和经验在边界处立刻用 `abs task` / `abs note` 落盘
+- **收尾层**：`abs wrapup` 在 Stop 时快照未完成任务；下个会话开头对账 todo、沉淀经验、修 index
+
+---
 
-abs uninstall --agent claude-code   # 卸载（只删 abs 装的，保留其它共存 hook）
-abs uninstall                        # 全部
+## 更新
+
+```bash
+abs update
 ```
 
-安装内容：
-| 宿主 | hook | MCP | skill |
-|---|---|---|---|
-| claude-code | `~/.claude/settings.json` hooks（与 moshi-hook 等**共存追加**，不覆盖） | settings.json `mcpServers.abs` (stdio) | `~/.claude/skills/abs-agent-brain-sync/` |
-| codex | `~/.codex/hooks.json` | config.toml `[mcp_servers.abs]` | `~/.codex/skills/` |
-| opencode | `~/.config/opencode/plugins/abs.ts` | opencode.json mcp.abs | skills/ |
-| pi | `~/.pi/agent/extensions/abs.ts` | extension 内桥接 | skills/ |
+查 npm 最新版 → 升级 → 自动重刷四个宿主的 hook/skill（hook 里烧的是绝对路径，升级后必须重装，`abs update` 帮你做了）。完事重启宿主。
+
+手动方式：
 
-幂等：重复安装=更新；写入前自动备份；卸载只删 abs 的条目、保留其它共存 hook。
+```bash
+npm i -g @fanchao8609/agent_brain_sync@latest
+abs install    # 重新刷 hook/skill
+```
 
-## 项目里用
+---
+
+## 卸载
 
 ```bash
-abs init          # 项目根建 .brain/ 图谱（一次）
-abs load          # 开机读状态（index 路线 + todo 看板 + 最近 log）
-abs todo          # 看板（Today/Backlog/Blocked/Done）
-abs task start   TASK-1 --note "做什么"        # 登记（幂等）
-abs task note    TASK-1 --note "改到X文件L40"  # 实时断点（↳ 断点: 行，幂等）
-abs task blocked TASK-1 --note "卡点原因"      # 碰壁移 Blocked
-abs task done    TASK-1                        # 完成归位 Done
-abs note "经验一句话" --tags 坑,docker          # 经验实时暂存 → sources/
-abs log "完成X：…"   # 记一行工作成果流水；abs log 无参=查看 log.md
-abs query <词>    # 检索图谱（多词 OR）
-abs lint          # 图谱体检（死链/孤岛/超尺寸/堆积/index 漏列）
-abs status        # 当前项目 + 图谱概要
+abs uninstall                      # 全部宿主
+abs uninstall --agent pi           # 只卸 pi
+npm uninstall -g @fanchao8609/agent_brain_sync
 ```
 
-实时化分工：**hook 自动记技术流水；任务/经验经 CLI/MCP 实时落盘（每个任务边界立即调）；
-深提炼（sources→concepts）归收尾自觉层，工具不替你判断什么值得沉淀。** 详见 `skill/SKILL.md`。
+只删 abs 自己装的条目，**保留其它共存 hook**。
 
-## 核心能力
+**注意**：卸载**不会**删项目里的 `.brain/`——那是你的知识资产，要删自己 `rm -rf .brain`。
 
-- **并发写保护（lock）**: `.brain` 是"读-改-整写回"，跨进程并发会互相覆盖。`src/lock.js` 用同目录 `.lock` 文件 `open('wx')` 原子抢占 + 排队等锁（预算 30s，指数退避）+ `SKIP` 哨兵，把 todo/index/log 的写串行化，避免丢失更新。
-- **统一读写收口（brainio）**: `src/brainio.js` 提供 `readBrain / writeBrain / appendBrain / createBrainFile`——所有需读写 .brain 文档的地方统一走它，写自动带 lock 防并发（新代码遵循此入口）。
-- **收尾自动化**: Stop 时 hook 在 `~/.abs/log/wrapup.log` 留 wrapup 提醒；下会话开头走"收尾循环"（对账 todo / 沉淀经验 / 修 index/log）。
-- **多宿主共存**: install 分区合并追加，不会顶掉同事件的其它 hook（如 moshi-hook）。
+---
 
 ## 开发
 
 ```bash
-npm test          # 全量 110+ 单测（四层: CLI/install/MCP/hook + lock/brainio）
-npm run pack:check  # 预览 npm 发布产物（files 白名单）
+npm test           # 110+ 单测（node:test，零外部测试依赖）
+npm run pack:check # 预览 npm 发布产物
 ```
 
 ## 目录
@@ -98,15 +125,17 @@ npm run pack:check  # 预览 npm 发布产物（files 白名单）
 ```
 agent_brain_sync/
 ├── bin/abs.js      CLI 入口
-├── bin/mcp.js      MCP server (stdio, 官方 SDK, 窄工具面)
+├── bin/mcp.js      MCP server (stdio)
 ├── src/index.js    图谱定位（向上找最近 .brain/）
-├── src/lock.js     .brain 并发写保护（原子锁 + 排队 + SKIP）
-├── src/brainio.js  统一读写收口（readBrain/writeBrain/appendBrain）
+├── src/lock.js     并发写保护（原子锁 + 排队 + SKIP）
+├── src/brainio.js  统一读写收口
 ├── src/todo.js     todo.md 分区读写
-├── src/store.js    CLI 命令实现 (init/load/todo/task/log/query/lint/status/…)
+├── src/store.js    CLI 命令实现
 ├── src/hosts.js    四宿主接入定义
-├── src/install.js  安装/卸载向导（分区共存合并）
-├── hooks/event.sh  hook 模板（纯触发 → 技术日志 + Stop wrapup 提醒）
-├── skill/SKILL.md  技能（安装到各智能体）
-└── test/           单测（node:test，零外部测试依赖）
+├── src/install.js  安装/卸载（分区共存合并）
+├── hooks/event.sh  hook 模板
+├── skill/SKILL.md  技能（装到各智能体）
+└── test/           单测
 ```
+
+MIT

package/package.json

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

package/skill/SKILL.md

@@ -103,6 +103,11 @@ monorepo 若多个子包各自独立交付，可各建一份 `.brain/`；横向
 **todo 不是收尾仪式，是干活中随改随写的活看板。** 每个任务边界立即更新，和 git commit
 同一个反射，别等收尾。用工具（MCP `abs_task` / CLI `abs task`）：
 
+> **写操作优先 MCP，不要用 `bash` 跑 `abs`。** 实测：MCP 单次 ~2ms（server 常驻），
+> CLI 单次 27ms（其中 20ms 是每次起 node 进程的固定开销，读写本身仅 3ms）。
+> 一轮发多条命令时差距明显。CLI 留给「人手动查看看板」，agent 读写走 MCP。
+> 详见 [[perf-fixed-overhead]]。
+
 | 时机 | 动作 |
 |---|---|
 | 认领新任务 | `abs task start <id> --note "做什么"` |

package/src/store.js

@@ -4,7 +4,7 @@ import { promises as fs } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { requireBrain, findBrainRoot, brainPath } from './index.js';
-import { addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, moveBlocked, insertDoneGrouped } from './todo.js';
+import { addTask, upsertTask, boardText, readTodo, ensureTodo, todoTemplate, today, localStamp, setBreakpoint, moveBlocked, insertDoneGrouped, idOfTaskLine } from './todo.js';
 import { editFile, SKIP } from './lock.js';
 import { appendWrapup, strandedFor, wrapupLogPath } from './wrapup.js';
 
@@ -320,9 +320,10 @@ async function markDone(file, id) {
     let changed = false;
     let moved = null;
     const kept = [];
+    const wantId = String(id).replace(/\u200b/g, '');
     for (let i = 0; i < lines.length; i++) {
       const l = lines[i];
-      if (!moved && l.startsWith('- [ ]') && l.includes(id)) {
+      if (!moved && idOfTaskLine(l) === wantId) {
         changed = true;
         const head = l.replace('- [ ]', '- [x]').replace(/\(认领[^)]*\)/, '') + ` (完成 ${today()})`;
         const bp = [];

package/src/todo.js

@@ -215,8 +215,8 @@ export async function upsertTask(brainRoot, { section, text }) {
   const out = await editFile(p, (orig) => {
     const base = normalizeTodo(orig);
     const lines = base.split('\n');
-    // 在所有分区中找含该 id 的未完成任务行（Done 的已完成行不重复动）
-    const idx = lines.findIndex((l) => l.startsWith('- [ ]') && id && l.includes(id));
+    // 在所有分区中找该 id 对应的未完成任务行（Done 的已完成行不重复动）；全等比对
+    const idx = findTaskLine(lines, id);
     if (idx !== -1) {
       // 原位更新：保留断点附属行，只换任务行本体
       const oldNote = extractNote(lines[idx].replace(/^- \[ \] /, ''));
@@ -244,10 +244,25 @@ export function extractNote(text) {
   return i === -1 ? '' : String(text).slice(i + 3).replace(/\s*\(认领[^)]*\)\s*$/, '');
 }
 
-/** 定位含 id 的未完成任务行下标；附属断点行（↳ 开头）不算任务行。 */
+/**
+ * 从任务行取出行首 id token（`- [ ] <id> …` 里的 <id>）。
+ * 坑: 不能用 l.includes(id) 定位任务 —— 那是子串匹配，`T1` 会命中 `T11`（同理
+ * TASK-1/TASK-10、fix-hook/fix-hook-2），导致 upsert 误判"已存在"而原地改写别的任务、
+ * 新任务静默消失。必须取出 id token 做全等比对。
+ * id 里可能混入零宽字符(历史瑕疵)，比对前先剥掉。
+ */
+export function idOfTaskLine(line) {
+  if (!line || !line.startsWith('- [ ]')) return null;
+  const m = line.match(/^- \[ \] (\S+)/);
+  return m ? m[1].replace(/\u200b/g, '') : null;
+}
+
+/** 定位 id 对应的未完成任务行下标；附属断点行（↳ 开头）不算任务行。
+ *  全等比对，不用 includes（否则 T1 会误命中 T11）。 */
 export function findTaskLine(lines, id) {
   if (!id) return -1;
-  return lines.findIndex((l) => l.startsWith('- [ ]') && l.includes(id));
+  const want = String(id).replace(/\u200b/g, '');
+  return lines.findIndex((l) => idOfTaskLine(l) === want);
 }
 
 /** 实时断点: 在 id 任务行下原位补/换 `↳ 断点:` 附属行（不挪任务位置）。 */