# @fanchao8609/agent\_brain\_sync 中文文档

规范地址：https://npmcn.com/package/%40fanchao8609/agent_brain_sync/

版本：1\.31\.7
npm 元数据更新时间：2026-11-12T17:03:13.956Z
中文译文更新时间：2026-11-14T09:42:16.856Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fanchao8609/agent_brain_sync
原文对照：https://npmcn.com/package/%40fanchao8609/agent_brain_sync/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：639 kB，45 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18
- 运行依赖：2 个
- 首次发布：2026-09-09T04:31:34.427Z
- 最新版本发布：2026-11-12T17:03:13.787Z
- 近 30 天下载量：7273（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：116（近 12 个月 116 个）

## 中文简介

代理-大脑同步:QQ AI--悬钩+CLI/MCP +. 大脑标记-QQ,QQ。

## 安装

```sh
npm install @fanchao8609/agent_brain_sync
```

也可以使用：`pnpm add @fanchao8609/agent_brain_sync`、`yarn add @fanchao8609/agent_brain_sync`、`bun add @fanchao8609/agent_brain_sync`

## README

# abs — agent-brain-sync

**跨会话 AI 编码记忆。** 让 AI 会话不再「重开就失忆」：任务进度、经验、踩坑都落盘到项目里的 markdown 图谱，下一个会话开机能直接读回来。

-   图谱纯 markdown，放在项目根 `.brain/`，**可以进 git**，人和 AI 读同一份
-   多项目自动隔离：只在当前目录找 `.brain/`，不向上穿透
-   并发安全：CLI / MCP / hook 同时写不会互相覆盖

npm 包名 `@fanchao8609/agent_brain_sync`，全局命令 **`abs`**。

* * *

## 安装

```bash
npm install -g @fanchao8609/agent_brain_sync
abs install
```

**默认只装 pi**（其余宿主 opt-in）——装到不用的宿主上会往那边配置文件塞 hook/MCP 条目。

```bash
abs install                       # 默认: 只装 pi
abs install --all                 # 全装: claude-code / codex / opencode / pi / omp
abs install --agent claude-code   # 只装指定宿主
abs install --agent pi --no-mcp   # 只装 hook + skill，不要 MCP
```

交互模式下回车 = 只装 pi；输入 `all` 才全装。

装了什么：

| 宿主 | 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` | `~/.pi/agent/mcp-adapter.json` `mcpServers.abs` | `~/.pi/agent/skills/` |
| omp | `~/.omp/agent/extensions/abs.ts` | `~/.omp/agent/mcp.json` `mcpServers.abs` | `~/.omp/agent/skills/` |

> **skill 规则**：`skill/` 下每个含 `SKILL.md` 的子目录 = 一个 skill， **目录名即安装名**（须与 frontmatter `name` 一致，否则 pi 会告警）。 新增 skill 只需建目录，无需改代码。

-   **幂等**：重复安装 = 更新，写入前自动备份
-   **共存**：追加式合并，不会顶掉你这个事件上的其它 hook
-   装完**重启宿主**才生效

从源码跑（开发用）：

```bash
git clone <repo-url> && cd agent_brain_sync
npm install && npm link        # 之后全局就有 abs
```

* * *

## 怎么用

### pi / omp：编辑器上的 todo 面板

pi 与 omp 宿主额外多一层 UI（其它宿主没有）：**编辑器上方常驻一块 todo 面板**，直接读当前项目 `.brain/todo.md`。

```
─────────────────────────────────────────────────
📋 todo (3) — fanchao · ☕ 靠咖啡续命
├─ [进行中] some-task ●●○ — 干活中
│  - [ ] hooks/abs.pi.ts:120
├─ [滞留中] waiting — 等外部输入
└─ [进行中] another ●●● — …
```

-   **只显示未完成**，Done 归计数不占位（数量在标题里）
-   **按当前使用者过滤**：显示 `[[我]]` 的 + 没标作者的（老任务/手写），别人的不显示
-   **子项（缩进的 `- [ ]`）挂在父任务下**；`├─` / `└─` 表结构
-   **子项可各自勾选**： `- [ ] 一句话` → `- [x] 一句话`；全部勾上才能 `done` 父任务
-   **「进行中」带三点动画**`○○○ → ●●○ → ●●●`（250ms/帧）—— 一眼看出哪条在跑
-   **实时刷新**：我调 `abs_task` 后立即重画，不用等我讲完话
-   **上描边与输入框同色满宽**（主题色 `thinkingOff`，跟 pi 输入框的边框一致）
-   窄终端按显示宽度截断（CJK 计 2 列），不溢出

**每次启动随机昵称**（132 条，附在作者名后）—— 每次打开 pi 换一条；池子分三批： 日常作息吃喝摸鱼 / 职场抱怨 / 自嘲（`编程全靠蒙`、`AI救我狗命`）。

| 环境变量 | 作用 |
| --- | --- |
| `ABS_TODO_PANEL=0` | 关掉面板 |
| `ABS_TODO_NICK=0` | 关掉随机昵称 |
| `ABS_TODO_GUIDE=0` | 关掉 system prompt 里的 todo 登记指引 |

> **设计取舍**：面板是**纯展示层**，只读 `todo.md` 不写任何东西，也不建第二套状态 —— 数据源就是 abs 自己的看板（磁盘文件，跨会话可续接）。所以没有折叠快捷键、没有依赖图， 只有 ~50 行渲染代码；对比 rpiv-todo 的 ~1800 行（它把状态存会话 transcript，新会话会丢）。
> 
> 另一层是**触发指引**：扩展往 system prompt 的 Guidelines 段注入 3 条静态条目 （动手前 `start` / 完成立刻 `done` / 断点及时 `note`）。这是**静态 prompt 内容**， 不是往对话里插消息 —— 本项目删过两次「插话式提醒」（会抢 turn 打断用户）。

### 项目里开一次

```bash
cd 你的项目
abs init          # 建 .brain/ 图谱，只需一次
```

### 日常命令

```bash
abs load                       # 开机读状态（Rules + 图谱计数 + 看板 + 最近流水）
abs todo                       # 看板 Todo / Done（行首带状态标记）

abs todo add     TASK-1 --note "要做什么"
abs todo note    TASK-1 --note "改到 X 文件 L40"   # 追加一条子项（标准 md 嵌套列表，可多条）
abs todo child-done   TASK-1 [--n 2]             # 勾子项（n=第几条，缺省最后一条）
abs todo child-undone TASK-1 [--n 2]             # 取消勾（勾错了退回）
abs todo memo    TASK-1 "随手记一段（可多句，不上看板）"   # 任务笔记 → sessions/；无参=查看
abs todo state   TASK-1 --note "进行中|讨论中|滞留中|搁置"      # 改行首状态标记
abs todo state   TASK-1 --note "滞留中" --n 2                 # 改第 2 条子项的状态（子项也能标四态）
abs todo done    TASK-1

abs note "一句话经验" --tags 坑,docker    # 经验暂存 → sources/
abs log "完成 X"                          # 记一行流水；abs log 无参 = 查看
abs query <词>                            # 检索图谱（多词 OR 扫全 .brain/）；已被推翻的经验默认隐藏（--all 可看）
abs capture [--layer 1-6] [--kind …] "一句话"  # 按七层判层后落到位（L7 用 abs note；--kind: gotcha|decision|tradeoff|howto）
abs ingest --list                       # 列出还没落页的会话（只读，不写盘）
abs ingest <会话文件或 id>                 # 把一场 pi 会话摘要并进当天的 log-<日期>.md（## 会话 <id8> 段）
abs resolve <页名或id>                    # 反查页面路径（页改名后 id 不变）
abs supersede <页名> [--by <新页>]        # 标记经验已失效（不删文件，保留历史；query 默认不再返回）
abs status                                # 当前项目 + 图谱概要
abs lint                                  # 体检：死链/孤岛/超尺寸/堆积
abs rule                                  # 列出 index.md 的 ## Rules 硬规则
abs rule add "一句话"                     # 追加一条硬规则（违反会丢数据/静默失效级的）
abs config show                           # 查看使用者姓名（标记作者用）
abs config set user <名字>                # 设置作者名 → ~/.abs/config.json
abs todo archive                          # 归档 Done 区旧日期组（默认留近 3 天）
abs update                                # 升级到最新版并刷新四宿主 hook/skill
```

> `abs todo start` 与 `abs todo add` 等价（都登记任务）。 **子项就是标准 Markdown 嵌套列表**：任务下缩进 2 空格的 `- [ ] …`，可多条、可各自勾选； 面板按缩进画树线，归档时原样保留缩进。 旧版的 `↳ 断点:` 写法已在 1.20.0 移除；存量会在 `abs load` 或任意写操作时 自动迁移成标准子项（内容一条不丢），不需要手工改。 任务 id 不能含空格（用连字符），含空格会被明确拒掉。 旧版 `abs task ...` / `abs board` 已废，打它们会报「未知命令」并退出码 1。 `abs wrapup` / `abs teardown-check` 是 hook 内部命令，无需手动调用。 **作者名要填真的**：`tester` / `foo` / `aaa` 这类占位名会被拒 —— 因为 `{user}` 是全局单值， 填错会污染之后所有项目的 `[[作者]]` 标记（`aaa` 这类堆字也拒，但 `oo`/`ee` 这种两字母缩写放行）。 `abs load` 对已落盘的占位名会给出警告，提示改回真名。 **升级后分区名自动归一**：`abs load` 每次都会顺手核对 `index/log/todo` 三文件结构，旧的分区名（如 `# 🗂 图谱索引` → `# 🗂 Graph Index`）会被自动改回标准；缺分区自动补建，无头文件只提醒不自动改。

### 工作流

-   **hook 自动**：宿主生命周期事件写技术流水到 `~/.abs/log/`
-   **实时层（你/AI 手动）**：任务和经验在边界处立刻用 `abs todo` / `abs note` 落盘
-   **收尾层**：`abs wrapup` 在 Stop 时快照未完成任务；下个会话开头对账 todo、沉淀经验、修 index

* * *

## 更新

```bash
abs update
```

查 npm 最新版 → 升级 → 自动重刷五个宿主的 hook/skill（hook 里烧的是绝对路径，升级后必须重装，`abs update` 帮你做了）。完事重启宿主。

手动方式：

```bash
npm i -g @fanchao8609/agent_brain_sync@latest
abs install    # 重新刷 hook/skill
```

> ⚠️ 改完源码（尤其 `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` 再验。

* * *

## 卸载

```bash
abs uninstall                      # 全部宿主
abs uninstall --agent pi           # 只卸 pi（omp 同理：--agent omp）
npm uninstall -g @fanchao8609/agent_brain_sync
```

只删 abs 自己装的条目，**保留其它共存 hook**。

**注意**：卸载**不会**删项目里的 `.brain/`——那是你的知识资产，要删自己 `rm -rf .brain`。

* * *

## 开发

```bash
npm test           # 全部单测（node:test，零外部测试依赖）
npm run pack:check # 预览 npm 发布产物
```

## 目录

```
agent_brain_sync/
├── bin/abs.js      CLI 入口
├── bin/mcp.js      MCP server (stdio)
├── src/index.js    图谱定位（只认当前目录的 .brain/）+ 全局技术日志目录
├── src/lock.js     并发写保护（原子锁 + 排队 + SKIP）
├── src/todo.js     todo 对外入口（re-export，实现见 src/todo/）
├── src/todo/       todo.md 分区读写 + 格式闸门（common/spec/structure/validate/archive/tasks）
├── src/store.js    CLI 命令实现
├── src/lint.js     图谱体检（死链/孤岛/超尺寸/堆积；同类问题折叠计数）
├── src/query.js    检索知识页（多词 OR）
├── src/relevant.js 相关页推荐（按"当前在干什么"挑该读的页）
├── src/codegraph.js  借本机 CodeGraph 取"代码影响面"，写回图谱
├── src/hosts.js    五宿主接入定义
├── src/install.js  安装/卸载（分区共存合并）
├── src/userconfig.js  使用者姓名配置（作者标记；占位名如 tester/foo 会被拒）
├── src/wrapup.js   Stop 收尾快照/归档
├── hooks/event.sh  hook 模板
├── hooks/abs.pi.ts pi 扩展模板（含 todo 面板 / 随机昵称 / 常驻指引）
├── hooks/abs.omp.ts omp 扩展模板（同上；omp 的 before_agent_start 是 systemPrompt 整体替换）
├── skill/<名称>/SKILL.md  技能（每个子目录 = 一个 skill，装到各智能体）
├── scripts/        构建期脚本（语法检查等，不进 npm 包）
├── docs/plans/     方案文件（YYYYMMDD-<名>.md，不进 npm 包）
├── .githooks/      pre-commit（语法+图谱 lint）/ pre-push（全量测试）
└── test/           单测（node:test，零外测试依赖）
```

MIT

## 常见问题

### @fanchao8609/agent\_brain\_sync 是什么？

代理-大脑同步:QQ AI--悬钩\+CLI/MCP \+\. 大脑标记-QQ,QQ。

### 如何安装 @fanchao8609/agent\_brain\_sync？

在项目目录运行 npm install @fanchao8609/agent\_brain\_sync，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 abs，可以用 npx abs 直接运行。

### @fanchao8609/agent\_brain\_sync 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/fanchao8609\_\_agent\_brain\_sync 是否存在。

### @fanchao8609/agent\_brain\_sync 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fanchao8609/agent\_brain\_sync 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fanchao8609/agent\_brain\_sync 可以商用吗？

@fanchao8609/agent\_brain\_sync 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fanchao8609/agent\_brain\_sync 的下载量有多少？

根据 npm 官方下载统计，@fanchao8609/agent\_brain\_sync 在 2026/10/14 – 2026/11/12 这 30 天内被下载 7,273 次，日均约 242 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fanchao8609/agent\_brain\_sync 还在维护吗？

最新版本 1\.31\.7 发布于 2026/11/13（1 天前）；至今共发布 116 个版本，其中过去 12 个月发布了 116 个；首次发布于 2026/09/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。