brain.md CLI 完整命令清单:16 个子命令从 init 到 lint-links 一次讲透

原创2026-11-15 17:48:531,388 阅读

brain.md CLI 完整命令清单:16 个子命令从 init 到 lint-links 一次讲透

brain.md 是为编程智能体(Claude Code、Codex、Cursor 等)提供持久化、文件化项目记忆层的开源工具。它把一个项目的长期决策、需求与约束,用纯 Markdown 沉淀在仓库里,并全部通过一个零依赖的 brain CLI 来读写。本文带你把 brain 命令行的 16 个子命令从 init 到 lint-links 逐一讲透,附常用参数与实战组合,帮你快速上手。

核心铁律:所有读写都走 brain CLI,永远不要手改 brain 目录下的文件。正确性由 CLI 在构造期保证,文件层没有任何校验器能兜底。

一、3 步快速上手 brain.md

先装工具(全局,把 brain 放到 PATH),再进入目标项目初始化:

npm install -g @mindmux/brain-md
brain setup -y     # 把 skills 分发到各智能体的全局目录

进入项目根目录执行初始化:

brain init        # 生成 BRAIN.md + 空 brain/ 骨架,并默认接线 CLAUDE.md / AGENTS.md

完成后用 brain-bootstrap 技能给大脑"灌入"真实知识,之后边写代码边维护大脑即可。

二、16 个子命令总览表

brain 的 16 个子命令按职责分为四大类,一表看清:

类别 子命令 一句话说明
读取(位置无关) brain-dir 打印解析出的 brain 目录及来源
读取 list-pages 列出所有页面:id / 标题 / 类别 / 状态
读取 read-page <id> 读取 brain/pages/<id>.md
读取 read-root <slug> 读取根页面 brain/<slug>.md
写入(构造期正确) create-page 新建一个知识页面
写入 update-truth 重写 compiled_truth(原子追加时间线)
写入 append-timeline 仅追加一条时间线记录
写入 archive-page 归档页面(可附反转原因)
写入 set-tags 修改页面标签
写入 update-root <slug> 重写某个根页面
项目搭建 init 生成 BRAIN.md + 骨架 + 默认接线
项目搭建 wire 把智能体配置接到 BRAIN.md
钩子 install-hooks 安装 Claude Code 会话启动快照钩子
钩子 uninstall-hooks 移除该会话启动钩子
索引 / 校验 reindex 重建 brain/index.md
索引 / 校验 lint-links 校验 [[page-id]] 链接是否可解析

命令完整实现见 skills/brain-page/bin/brain.mjs,操作手册见 skills/brain-page/SKILL.md。

三、读取类命令:无需知道大脑在哪里

这四个命令是"位置无关"的——CLI 会自己解析 brain 目录(优先读 ./.mindmux/preferences.json 的 brainRoot,否则回退到 ./brain),你不用关心大脑到底落在哪。

brain brain-dir:打印解析出的目录、来源(source:)、是否存在与是否已有内容(populated:)。排查"大脑到底在哪"时先跑它。

brain list-pages:列出全部页面(id、标题、类别、状态),相当于索引的"目录视图"。

brain read-page <id> / brain read-root <slug>:分别读取某个知识页与某个根页面。

brain brain-dir
brain list-pages
brain read-page markdown-over-sqlite
brain read-root architecture

根页面固定只有六个:background / architecture / flow / mindmap / stack / roadmap,模板位于 skills/brain-setup/assets/brain/。

四、写入类命令:构造期正确,杜绝手改

写入类是 brain.md 的精华——每条命令都在写入时自动保证 frontmatter 合法、compiled_truth 与时间线"改理解必留痕"。

brain create-page:从模板生成新页面,随后自动重建索引。

brain create-page --id markdown-over-sqlite --category decision --title "配置存 Markdown 而非 SQLite"

类别(--category)五选一:project / concept / decision / person / reference;id 必须为 kebab-case 且与文件名一致。

brain update-truth:新内容从 stdin 读入,重写 compiled_truth 并在同一次原子写入中追加 decision 时间线——"改理解"与"记原因"不可分割。

echo "## 结论:配置用 Markdown,便于 diff 与迁移" | \
  brain update-truth --id markdown-over-sqlite --summary "补充迁移成本对比"

brain append-timeline:只在时间线末尾追加,--kind 取 decision / evidence / reversal / note。

brain archive-page:置 status: archived,可用 --reversal-summary 记录"为何被推翻"。

brain set-tags:brain set-tags --id <id> --tags a,b,c 替换标签。

brain update-root <slug>:整体重写某个根页面(正文走 stdin),CLI 会重生成 frontmatter 并保证规范 H1 标题存在;根页面无时间线,其历史交给 git。

echo "## 分层 …… (mermaid graph)" | brain update-root architecture

五、项目搭建命令:init 与 wire

brain init:一键生成 BRAIN.md、brain/ 骨架(含六根页面模板与空 pages/),并默认接线 CLAUDE.md + AGENTS.md。它幂等——已存在的内容绝不覆盖,可用 --no-wire 跳过接线。

brain wire:单独做"接线",把统一的 brain 代码块(包裹在 <!-- BEGIN brain.md --> … <!-- END brain.md --> 标记内)写入智能体配置文件,指向 ./BRAIN.md。缺文件则创建,已有文件只替换/追加标记块,永不整文件覆盖;可用 --agent 指定子集(claude-code / codex / opencode / cursor / pi / all)。

六、钩子命令:给 Claude Code 加"会话快照"

brain install-hooks:可选安装一个项目本地的 Claude Code SessionStart 钩子,每次会话开始时注入一份精简的 brain list-pages 快照。它只合并 .claude/settings.json,绝不写全局 ~/.claude/settings.json,且幂等。

brain uninstall-hooks:移除该钩子与对应脚本,保留其他设置。两者均为"尽力而为"——brain 未填充时直接 no-op,失败也以退出码 0 收尾,属于便利层而非硬依赖。

钩子脚本模板见 skills/brain-setup/hooks/session-start。

七、索引与校验:reindex 与 lint-links

brain reindex:根据 brain/pages/*.md 重建 brain/index.md。多数写命令会自动重建,无需手动频繁执行。

brain lint-links:校验每个 [[page-id]] 是否都能解析到对应页面。它把页面的 compiled_truth 当作"当前知识图谱",但有意跳过时间线(时间线是只追加的证据链,可能含历史引用)。发现指向根页 slug 的 [[ ]] 会给出警告,发现悬空链接则报错并以非零码退出。

brain reindex && brain lint-links

刻意没有 validate 命令:因为所有写操作都经 CLI,frontmatter 永远合法、compiled_truth 改动必带时间线,校验器本要防护的失效模式在构造期就不可能发生。reindex 与 lint-links 只是可选的"卫生检查",而非承重闸门。

八、常用组合速查

  • 新建并落地一条决策:create-page → update-truth(stdin 给正文)
  • 记录新证据但不改结论:append-timeline --kind evidence
  • 推翻旧结论:update-truth 与/或 append-timeline --kind reversal,必要时 archive-page
  • 提交前自检:brain reindex && brain lint-links(亦可挂 git pre-commit,见 skills/brain-setup/hooks/pre-commit)

小结

brain.md 用 16 个 brain 子命令覆盖"读取—写入—搭建—钩子—索引校验"全链路,让你把项目知识变成可随 git 流转、跨智能体复用的持久记忆。记住三件事:从项目根目录执行、永远走 CLI 不手改、只沉淀"六个月后仍重要且难从代码重建"的知识。命令清单完整定义见 package.json 与 README.md,动手前再读一遍 skills/brain-page/SKILL.md 即可游刃有余。

登录后查看全文
brain.md