@fanchao8609/agent_brain_sync 1.2.1 → 1.2.3

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.1",
+  "version": "1.2.3",
   "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/wrapup.js

@@ -18,6 +18,25 @@ export function wrapupLogPath() {
 // 同项目两次快照的最小间隔(秒)。agent_end 会逐 turn 触发, 无变化时不刷屏。
 export const WRAPUP_MIN_INTERVAL_MS = 5 * 60 * 1000;
 
+// wrapup.log 轮转阈值。只留 .1 一层: 排查/Rebuild 只靠每个 proj 的最近一块,
+// 旧块是死重量(parseWrapup 用 byProj.set 覆盖, 前面的块永远不会被读到)。
+export const WRAPUP_MAX_BYTES = 1024 * 1024; // 1 MiB
+
+/** 超阈值则轮转为 .1。放在 appendWrapup 里 → CLI/MCP/hook 三条路径都覆盖。 */
+async function rotateIfNeeded(p) {
+  const max = Number(process.env.ABS_WRAPUP_MAX_BYTES || WRAPUP_MAX_BYTES);
+  let st;
+  try { st = await fs.stat(p); } catch { return; }
+  if (!Number.isFinite(max) || st.size <= max) return;
+  // 先把当前内容落成 .1(覆盖旧 .1), 再截断；失败则不动, 不让轮转本身丢数据
+  try {
+    await fs.rename(p, p + '.1');
+  } catch {
+    return;
+  }
+  await fs.writeFile(p, `[${localStamp()}] wrapup 轮转: 原文件 ${st.size} bytes > ${max}, 已移入 wrapup.log.1\n`, 'utf8').catch(() => {});
+}
+
 /** 从 todo 文本/快照块提取任务清单。兼容顶层(todo.md `- [ ]`)与缩进(快照 `  - [ ]`)两种行。
  * body = 去掉 `- [ ]` 前缀、`(认领|完成 date)` 标注后的核心文本。bp 去掉 `↳ 断点|卡点: ` 前缀。
  * Done 区（## Done 下）不采。返回 [{ body, bp }]，bp 为附属断点数组（或空）。 */
@@ -102,6 +121,8 @@ export async function appendWrapup(root) {
   await fs.mkdir(join(p, '..'), { recursive: true });
   const todo = await readTodo(root); // readTodo 幂等迁移，拿到权威内容
   const tasks = extractOpenTasks(todo);
+  // 轮转在写前做：否则文件无上限增长（只追加不清理，旧块永远读不到=死重量）
+  await rotateIfNeeded(p);
   let prev = '';
   try { prev = await fs.readFile(p, 'utf8'); } catch { /* 尚无文件 */ }
   const snap = parseWrapup(prev);