GBrain 0.41 从头安装 & 架构全解剖

从零开始，在 Mac 上用 PGLite 引擎 + 本地 MLX 嵌入、绕过非 TTY 嵌入陷阱、scaffold 65 个技能包，并深挖其核心架构。一份既是安装日志也是运维手册的文档。

一、安装全记录

环境前提

macOS（Apple Silicon MLX 可用）
Bun 已安装
gbrain v0.41.28.0（通过 bun install -g gbrain 安装）
本地 MLX 嵌入 API 运行在 http://127.0.0.1:4321/v1（模型 bge-m3-mlx-8bit，1536 维）

安装时间线

| 步骤 | 命令 | 耗时 | 状态 |
|------|------|------|------|
| Bun 安装 | curl -fsSL https://bun.sh/install \| bash | 1 min | ✅ |
| gbrain 全局安装 | bun install -g gbrain | 2 min | ✅ v0.41.28.0 |
| 初始化 brain | gbrain init | 3 min | ⚠️ 默认跳过嵌入 |
| 配置嵌入模型 | 手动改 config.json → wipe → re-init | 10 min | ✅ |
| 配置 Anthropic API | gbrain config set anthropic_api_key ... | 1 min | ✅ |
| Scaffold 技能 | gbrain skillpack reference --all | 2 min | ✅ 65 个 |

🔴 核心陷阱：非 TTY 环境跳过嵌入

这是整个安装过程中最大的单一障碍，耗费了 10+ 轮调试。

症状： 在 agent 脚本环境（非交互式 shell）中运行 gbrain init，它检测到没有 TTY 后自动附加 --no-embedding flag，导致 embedding 被完全跳过。

失败方案清单（8 种均无效）：

❌ gbrain init --embedding-model openai:bge-m3-mlx-8bit — 这不是合法 init 参数
❌ gbrain config set embedding_model openai:bge-m3-mlx-8bit — 直接返回错误
❌ 设置 OPENAI_API_KEY + OPENAI_BASE_URL env vars 后 init — init 的交互式 provider picker 仅在 TTY 环境下显示
❌ 用 Python subprocess.Popen + stdin.write 模拟交互 — gbrain 使用 raw TTY 检测，pipe 不算 TTY
❌ 用 script 命令伪终端 — gbrain 仍然拒绝
❌ echo "openai" | gbrain init — 如上，管道不算 TTY
❌ expect 脚本 — gbrain 的 bubbletea TUI 不认
❌ osascript 在 Terminal.app 开窗口 — 环境隔离，无法传递 API key

✅ 唯一有效方案：直接手术 config.json

# Step 1: 读取当前配置
cat ~/.gbrain/config.json

# Step 2: 手动写入 embedding_model
# 用 jq 或任何 JSON 工具：
jq '.embedding_model = "openai:bge-m3-mlx-8bit"' ~/.gbrain/config.json > /tmp/gb.json
mv /tmp/gb.json ~/.gbrain/config.json

# Step 3: 同时确保 OPENAI 兼容的 env vars
export OPENAI_API_KEY="sk-lm-HntbFL3A:O6vAtwZgedF09ou0R8QE"
export OPENAI_BASE_URL="http://127.0.0.1:4321/v1"

# Step 4: Wipe 旧 brain，重新 init
rm -rf ~/.gbrain/brain.pglite
gbrain init --engine pglite

# Step 5: 验证
gbrain doctor
# 输出中应显示：
#   embedding_model: openai:bge-m3-mlx-8bit
#   embedding_dimensions: 1536
#   embedding_disabled: (不再出现)

为什么这能成功： gbrain 的配置有两个 plane——config.json 是 "file plane"（静态持久化），gbrain config set 是 "CLI plane"（运行时覆盖）。init 本身会从 config.json 读取已有配置；如果 json 中已有 embedding_model，init 不会重新打开交互式 picker，而是直接采用已有值。

🔴 次要陷阱：skillpack 找不到 repo root

gbrain skillpack scaffold 依赖 git 仓库来确定 brain repo root。如果 gbrain 安装在 ~/node_modules/gbrain/ 而非一个 git 仓库中，scaffold 会失败。

解决方案： 确保 GBRAIN_ROOT 指向一个有 .git 的目录，或者在技能源码目录 git init。

🔴 已知限制：Reranker 不可自定义

gbrain v0.41 的 config show 和 config set 中不暴露 reranker_model 配置键。默认使用内置 ZeroEntropy reranker（作为 RRF 后处理的一部分）。本地 MLX 的 bge-reranker-v2-m3-mlx-fp16 无法配置为 gbrain 的 reranker——这是 gbrain 的设计选择，reranker 是框架层内置的，不开放替换。

二、GBrain 架构深挖

1. 核心哲学：Thin Harness, Fat Skills

这是理解整个 GBrain 最关键的一句话：

GBrain CLI = 确定性层（薄 harness）
Skills = 潜在空间层（胖技能）
Recipes = 安装了基础设施的胖技能

Harness（缰绳） 只做确定性的基础操作：文件解析、嵌入计算、向量/全文搜索、数据库事务。相同输入→相同输出。
Skills 是 agent 阅读后执行的 Markdown 指令集，包含 ingest（摄入）、query（查询）、maintain（维护）、enrich（丰富）、briefing（简报）、migrate（迁移）等能力。它们调用 gbrain 的确定性工具来完成工作。
Recipes 是安装了完整基础设施的技能，比如 voice-to-brain（语音转知识）、email-to-brain（邮件转知识）。

这意味着：gbrain 自身没有 "智能"——它只是基础设施。智能来自 agent 阅读 skills 后调用 gbrain 工具。

2. System of Record：Markdown 文件

这是第二重要的概念：

GitHub 仓库里的 Markdown 文件是 System of Record。
PGLite/Postgres 数据库只是衍生缓存。不备份数据库——从仓库重建它。

灾难恢复只需一行命令：
gbrain rebuild --confirm-destructive

多机同步用 git（push/pull），不是数据库 export/import
敏感页面可以 gitignore（通过 gbrain.yml 或 per-page 配置）
多个 agent 可以同时写入同一个 brain，因为 git 处理并发编辑

3. 数据管道

输入（Markdown 文件 / git repo）
  ↓
文件解析（gray-matter frontmatter + body）
  → compiled_truth + timeline 分离
  ↓
内容哈希（SHA-256 幂等检查，未变化则跳过）
  ↓
分块（3种策略可配置）
  ├── Recursive: 300词块、50词重叠、5级分隔符层级
  ├── Semantic: 嵌入句子、余弦相似度、Savitzky-Golay 平滑
  └── LLM-guided: Claude Haiku 在 128 词候选中识别主题转换
  ↓
嵌入（1536 维向量，batch 100，指数退避，非致命性失败）
  ↓
数据库事务（原子：page + chunks + tags + version）
  ↓
即时可用搜索

4. 搜索架构：四层混合 + RRF 融合

这是 GBrain 区别于纯向量搜索的核心竞争力：

用户查询
  ↓
扩展（可选：Claude Haiku 生成 2 个替代表述）
  ↓
  ├── 向量搜索（pgvector HNSW，余弦距离）
  │     → 每查询变体 2x 限制结果
  │
  └── 关键词搜索（PostgreSQL tsvector，ts_rank）
        → 2x 限制
  ↓
RRF 融合（score = Σ(1/(60 + rank))，公平平衡两者）
  ↓
四层去重
  ├── 每页最佳 3 块（源去重）
  ├── Jaccard 相似度 > 0.85（文字去重）
  ├── 无类型超过 60%（多样性）
  └── 每页最多 2 块（页 cap）
  ↓
TOP N 结果（默认 20）

另外还有两种搜索模式：

Graph Walk（图遍历）： BFS 扩展，沿 [[wikilinks]] 和结构化边（knows、works_at 等）遍历邻居页面的内容
Unified FTS（全文搜索）： 加权 tsvector（title A级权重、compiled_truth B级、timeline C级）

5. Schema Pack：定义脑的形状

Schema Pack 告诉 gbrain 你的 brain 长什么样——有哪些目录、什么类型、agent 如何从路径推断类型、什么 link verb 连接什么到什么地方。

| 版本 | 类型数 | 说明 |
|------|--------|------|
| gbrain-base | 24 种 | v0.39 前硬编码行为，向后兼容 |
| gbrain-base-v2 | 14 种 + note | v0.41 精简版，解决 94 种冗余类型问题 |

14 种规范类型（v2）：

| 类型 | 基元 | 内容 |
|------|------|------|
| person | entity | 人 |
| company | entity | 公司/产品/组织 |
| media | media | 文章/视频/论文 |
| concept | concept | 思维模型/框架/原理 |
| place | place | 位置/城市/场所 |
| meeting | event | 会议/通话 |
| deal | deal | 投资/收购/交易 |
| project | project | 可交付成果/项目 |
| writing | writing | 原始写作/帖子/备忘录 |
| analysis | analysis | 推理/研究/评估 |
| guide | guide | 操作指南/检查清单 |
| hardware | hardware | 设备/基础设施 |
| architecture | architecture | 系统设计 |
| original | original | 真实来源/ raw data |
| note | note | 快速笔记/大纲（catch-all） |

6. Brain Filing Rules：主体定位置

这是所有写入 brain 的技能必须遵守的规则：

内容的 PRIMARY SUBJECT 决定它放在哪里。不是格式，不是来源，不是运行的技能。

常见错误模式：

| 错误 | 正确 | 原因 |
|------|------|------|
| 分析文章 → sources/ | → 主题目录 | sources/ 只放 raw data |
| 人物文章 → sources/ | → people/ | 主体是人 |
| 会议信息 → 只放 meetings/ | → 同时更新 companies/ | 实体传播是强制要求 |
| 公司调研 → sources/ | → companies/ | 主体是公司 |
| 可复用框架 → sources/ | → concepts/ | 它是思维模型 |

7. Brains vs Sources 双轴模型

Brain = 数据库实例。可以有多个（工作脑、个人脑、研究脑）。
Source = 命名的内容仓库。每个 source 绑定到一个 git repo 根路径。

配置解析优先级（Brain）：

1. --brain <id> 参数
2. GBRAIN_BRAIN_ID env
3. .gbrain-mount dotfile
4. 最长前缀挂载路径匹配
5. brains.default 配置
6. fallback: 'host'

8. 数据库 Schema（10 张表）

| 表 | 用途 |
|----|------|
| pages | slug（唯一）、type、title、compiled_truth、timeline、frontmatter |
| content_chunks | 1536 维 pgvector 嵌入 |
| links | 类型化边（knows、works_at、invested_in、founded 等）|
| tags | 多对多页面标签 |
| timeline_entries | 结构化事件（日期、来源、摘要、详情）|
| page_versions | 快照历史用于 diff/revert |
| raw_data | 外部 API 的 sidecar JSON（保留溯源）|
| files | 二进制附件 |
| ingest_log | 导入操作审计追踪 |
| config | brain 级设置（版本、嵌入模型、分块策略）|

三、运维检查手册

日常健康检查

# 全面诊断
gbrain doctor

# 检查配置
gbrain config show

# 检查 schema
gbrain schema active
gbrain schema list

搜索测试

# 基础搜索
gbrain search "你的查询"

# 按类型过滤
gbrain search "查询" --type person

# 搜索结果解释（看 RRF 分数）
gbrain search "查询" --explain

重建与同步

# 从 markdown 重建整个数据库
gbrain rebuild --confirm-destructive

# 从 markdown 同步增量
gbrain sync

评估与 AB 测试

# 导出当前 eval
gbrain eval export > before.ndjson

# 改配置后对比
gbrain eval replay --against before.ndjson

# 用标记数据 AB 测试检索策略
gbrain eval --qrels labels.tsv --config balanced.json

技能管理

# 查看已安装技能
gbrain skillpack list

# 重新 scaffold（更新后）
gbrain skillpack reference --all

嵌入测试

# 测试嵌入是否正常
gbrain embed "测试文本"

四、配置更改指南

config.json 结构

位置：~/.gbrain/config.json

关键字段：

{
  "engine": "pglite",
  "database_path": "/Users/xxx/.gbrain/brain.pglite",
  "embedding_model": "openai:bge-m3-mlx-8bit",
  "openai_base_url": "http://127.0.0.1:4321/v1",
  "expansion_model": "anthropic:claude-haiku-4-5-20251001",
  "chat_model": "anthropic:claude-opus-4-7",
  "schema_pack": "gbrain-base-v2",
  "embedding_dimensions": 1536
}

切换 Schema Pack

# 查看可用 pack
gbrain schema list

# 切换到 recommended（14 类型）
gbrain schema use gbrain-recommended

# 回退到 base
gbrain schema downgrade --to gbrain-base

切换嵌入模型

# 方法 1：直接改 config.json（推荐，因为避免非 TTY 问题）
jq '.embedding_model = "openai:your-model"' ~/.gbrain/config.json > /tmp/gb.json
mv /tmp/gb.json ~/.gbrain/config.json
rm -rf ~/.gbrain/brain.pglite
gbrain init --engine pglite

# 方法 2：如果在交互式终端中
gbrain init  # 重新打开 provider picker

添加自定义 Schema Pack

# 创建新 pack
gbrain schema init my-pack

# 基于已有 pack fork
gbrain schema fork gbrain-base-v2 my-pack

环境变量速查

# 嵌入 API（OpenAI 兼容格式）
export OPENAI_API_KEY="your-key"
export OPENAI_BASE_URL="http://127.0.0.1:4321/v1"

# Brain 选择
export GBRAIN_BRAIN_ID="my-brain"

# Source 选择
export GBRAIN_SOURCE="my-source"

# 技能 repo root
export GBRAIN_ROOT="/path/to/brain/repo"

五、总结

| 维度 | 关键结论 |
|------|----------|
| 安装核心坑 | 非 TTY 环境 gbrain init 跳过嵌入配置。唯一破解：手动写 config.json → wipe brain → re-init |
| 架构核心哲学 | Thin Harness + Fat Skills。gbrain 是确定性的基础设施，智能来自 agent 阅读 skills |
| 数据真理来源 | Markdown 文件是 System of Record，DB 只是缓存。备份靠 git 不是 pg_dump |
| 搜索核心技术 | 混合检索（向量 + 关键词 + 图 + 全文），RRF 融合，四层去重 |
| 运维核心命令 | gbrain doctor、gbrain rebuild、gbrain sync、gbrain eval |
| 配置核心文件 | ~/.gbrain/config.json，Schema Pack 定义 brain 形状 |
| 已知限制 | Reranker 不可自定义（内置 ZeroEntropy）、技能全装不影响 GA 每轮上下文 |