GBrain 进阶使用指南

从"能用"到"好用"，深入理解 GBrain 的核心机制和高级用法。

一、核心机制详解

1.1 三层架构

┌─────────────────────────────────────────┐
│  应用层：问答/搜索/分析                  │
│  - gbrain query                         │
│  - gbrain whoknows                      │
│  - gbrain graph-query                   │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  技能层：60+ 可调用能力                   │
│  - 合成（synthesize）                    │
│  - 事实提取（extract-facts）             │
│  - 关系遍历（graph traversal）           │
│  - 缺口分析（gap analysis）              │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  存储层：PGLite/Postgres + pgvector      │
│  - pages 表（页面元数据）                │
│  - chunks 表（内容分块）                 │
│  - embeddings 表（向量索引）             │
│  - facts 表（结构化事实）                │
│  - edges 表（实体关系）                  │
└─────────────────────────────────────────┘

1.2 查询流程

当你执行 gbrain query "问题" 时：

路由决策 → 确定使用哪个 brain 和 source
向量搜索 → 找到最相关的 chunks
重排序 → 使用 reranker 精排结果
合成 → LLM 阅读相关 chunks，生成带引用的答案
缺口分析 → 识别大脑不知道的信息
返回 → 结构化答案 + 来源引用

1.3 事实提取机制

在 Markdown 文件中使用 ## Facts 代码块：

## Facts

| field | value | unit | period | event_type |
|-------|-------|------|--------|------------|
| mrr | 50000 | USD | monthly | metric |
| raised | 2000000 | USD | - | metric |
| date | 2026-05-23 | - | - | meeting |
| attended_by | alice-example | - | - | meeting |

GBrain 会自动提取这些结构化数据，存入 facts 表，支持：

数值比较（"MRR 超过 10 万的公司"）
时间序列（"追踪某公司的融资历史"）
关系查询（"谁参加了这个会议"）

二、Schema 深度使用

2.1 理解 Primitive（原始类型）

每个页面类型都有一个 primitive，决定它的行为：

Primitive	用途	示例
`entity`	独立实体	person, company, project
`temporal`	时间相关事件	meeting, call, calendar_event
`annotation`	对内容的标注	paper_review, code_review
`note`	通用笔记（默认）	未分类的内容

2.2 创建自定义类型

# 创建 researcher 类型
gbrain schema add-type researcher \
  --primitive entity \
  --prefix people/researchers/ \
  --expert \
  --extractable

# 参数说明：
# --primitive: 原始类型
# --prefix: 该类型的文件路径前缀
# --expert: 是否使用专家路由（针对该类型的查询优先）
# --extractable: 是否自动提取事实

2.3 定义关系类型

# 定义研究者与论文的关系
gbrain schema add-link-type authored \
  --page-type researcher \
  --target-type paper

# 定义论文之间的引用关系
gbrain schema add-link-type cites \
  --page-type paper \
  --target-type paper

# 定义数据集使用关系
gbrain schema add-link-type uses_dataset \
  --page-type paper \
  --target-type dataset

2.4 Schema 同步

# 查看待同步的变更
gbrain schema sync --dry-run

# 应用变更（会回填现有页面）
gbrain schema sync --apply

# 只同步 schema 不回填
gbrain schema sync --schema-only

2.5 查询 Schema

# 列出所有类型
gbrain schema list-types

# 列出所有关系
gbrain schema list-link-types

# 查看某个类型的定义
gbrain schema show-type researcher

# 查看谁属于某个类型
gbrain whoknows --type researcher

三、图查询（Graph Query）

3.1 基础图遍历

# 查找 Alice 的所有直接关系
gbrain graph-query alice-example --depth 1

# 查找两度关系（朋友的朋友）
gbrain graph-query alice-example --depth 2

# 指定关系类型
gbrain graph-query alice-example --type authored --depth 1

3.2 复杂图查询

# 查找所有发表过论文的研究者
gbrain graph-query --target-type paper --reverse-type authored

# 查找引用了某篇论文的所有论文
gbrain graph-query paper-123 --type cites --depth 1

# 查找通过 intro 关系连接的路径
gbrain graph-query alice-example --type intro-from --depth 3

3.3 轨迹查询（v0.35.7+）

针对有 metric 事实的实体，查询时间序列：

# 查看公司的融资轨迹
gbrain eval trajectory companies/acme

# 查看研究者的发表轨迹
gbrain eval trajectory people/researchers/alice

# 输出包含：
# - 按时间排序的事件
# - 自动标记的异常（regressions）
# - 增长率分析

四、多大脑架构

4.1 理解大脑边界

个人大脑（host）
├── source: wiki（个人笔记）
├── source: gstack（技术栈笔记）
└── source: openclaw（项目文档）

团队大脑 1（media-team）
├── source: wiki
├── source: pipeline
└── source: enriched

团队大脑 2（policy-team）
├── source: wiki
├── source: research
└── source: letters

4.2 挂载团队大脑

# 添加团队大脑
gbrain mounts add media-team \
  --path ~/team-brains/media \
  --db-url postgres://team-db-url \
  --description "媒体团队的共享大脑"

# 查看已挂载的大脑
gbrain mounts list

4.3 自动路由

在目录中创建 .gbrain-mount 文件：

# 进入团队目录
cd ~/team-brains/media

# 自动绑定到团队大脑
echo "media-team" > .gbrain-mount

# 现在该目录下的所有查询都自动使用团队大脑
gbrain query "最近的项目进展"
# 等同于：gbrain query "最近的项目进展" --brain media-team

4.4 跨大脑查询

# 查询个人大脑
gbrain query "Alice 的联系方式"

# 查询团队大脑
gbrain query "Alice 的联系方式" --brain media-team

# 跨大脑查询（需要手动 fan-out）
# 1. 查询个人大脑
gbrain query "Alice" --brain host
# 2. 查询团队大脑
gbrain query "Alice" --brain media-team
# 3. 合成结果（由 Agent 完成）

五、性能优化

5.1 嵌入提供商选择

提供商	速度	价格	推荐场景
OpenAI	基准	基准	通用场景
ZeroEntropy	2×	0.4×	推荐，性价比高
Voyage	1.5×	0.6×	备选
本地模型	取决于硬件	免费	隐私优先

切换嵌入提供商：

# 使用 ZeroEntropy
gbrain config set zeroentropy_api_key sk-...
gbrain config set embedder zeroentropy

# 使用 Voyage
gbrain config set voyage_api_key sk-...
gbrain config set embedder voyage

5.2 重排序器（Reranker）

# 使用本地 reranker（llama.cpp）
gbrain config set reranker llama-server
gbrain config set reranker_model Qwen3-Reranker

# 使用 ZeroEntropy reranker
gbrain config set reranker zeroentropy

5.3 分块策略

# 查看当前分块配置
gbrain config show chunker

# 调整分块大小（影响检索粒度）
gbrain config set chunk_size 500
gbrain config set chunk_overlap 50

# 重新分块现有内容
gbrain sync --rechunk

5.4 索引优化

# 重建向量索引
gbrain sync --reembed

# 清理孤儿页面（无入向链接）
gbrain orphans --json

# 修复损坏的 JSONB 数据
gbrain repair-jsonb --dry-run

六、运维与监控

6.1 健康检查

# 完整健康检查（JSON 格式）
gbrain doctor --json

# 快速检查（不消耗 API）
gbrain doctor --fast

# 自动修复发现的问题
gbrain doctor --fix

# 修复计划预览
gbrain doctor --remediation-plan --json

6.2 版本管理

# 查看当前版本
gbrain version

# 升级到最新版本
gbrain upgrade

# 强制应用 schema 迁移
gbrain apply-migrations --yes

# 查看迁移历史
gbrain migrate history

6.3 备份与恢复

# 导出所有数据
gbrain export --format json --output backup.json

# 导出为 Markdown
gbrain export --format markdown --output ./export

# 从备份恢复
gbrain import ./export --restore

# 只恢复 schema
gbrain schema sync --restore-only

6.4 日志与调试

# 查看最近的活动
gbrain events --limit 50

# 实时监控活动
gbrain events --follow

# 启用详细日志
gbrain config set log_level debug

七、与 Agent 平台集成

7.1 OpenClaw 集成

# 在 OpenClaw 中安装 GBrain
gbrain install

# 这会安装：
# - 60+ 技能
# - 9 个技能包
# - 默认大脑结构
# - MCP 服务器配置

7.2 技能路由

Agent 通过 skills/RESOLVER.md 路由意图：

# RESOLVER.md（简化版）

## 意图 → 技能映射

- query → skills/search/query.md
- write → skills/write/page.md
- sync → skills/sync/watch.md
- extract → skills/extract/facts.md
- graph → skills/graph/traverse.md

7.3 自定义技能

# 创建自定义技能
gbrain skill scaffold my-custom-skill

# 编辑技能
vim skills/my-custom-skill.md

# 重新加载技能
gbrain skill reload my-custom-skill

八、最佳实践

8.1 命名规范

people/alice-example.md        # 人名用连字符
companies/acme-corp.md         # 公司名用连字符
meetings/2026-05-23-alice.md   # 会议名：日期 - 主题
projects/website-redesign.md   # 项目名：描述性

8.2 页面模板

# Alice Chen

## Summary
角色、公司、关键信息摘要。

## Facts
| field | value |
|-------|-------|
| company | acme-corp |
| role | Engineering Manager |
| email | alice@acme.com |

## Connections
- [[bob-smith]] - 同事
- [[charlie-lee]] - 介绍人

## Notes
时间线式的详细笔记。

8.3 定期维护

# 每日：检查健康状态
gbrain doctor --fast

# 每周：清理孤儿页面
gbrain orphans | wc -l

# 每月：运行完整诊断
gbrain doctor --json > health-report-$(date +%Y%m).json

# 每季度：备份数据
gbrain export --format json --output backup-$(date +%Y%m).json

九、故障排查

9.1 常见问题

问题：查询返回空结果

# 检查是否有内容
gbrain list | wc -l

# 检查嵌入是否配置
gbrain models doctor

# 重新嵌入
gbrain sync --reembed

问题：schema 同步失败

# 检查待同步变更
gbrain schema sync --dry-run

# 手动应用迁移
gbrain apply-migrations --yes

# 查看错误详情
gbrain doctor --json

问题：API 调用失败

# 检查 API 密钥
gbrain config show

# 测试模型连接
gbrain models doctor

# 查看最近的错误
gbrain events --limit 10 --filter error

9.2 获取帮助

# 查看完整文档
gbrain docs

# 查看技能列表
gbrain skill list

# 提交问题（生成诊断报告）
gbrain doctor --json | pbcopy

一、核心机制详解​

1.1 三层架构​

1.2 查询流程​

1.3 事实提取机制​

二、Schema 深度使用​

2.1 理解 Primitive（原始类型）​

2.2 创建自定义类型​

2.3 定义关系类型​

2.4 Schema 同步​

2.5 查询 Schema​

三、图查询（Graph Query）​

3.1 基础图遍历​

3.2 复杂图查询​

3.3 轨迹查询（v0.35.7+）​

四、多大脑架构​

4.1 理解大脑边界​

4.2 挂载团队大脑​

4.3 自动路由​

4.4 跨大脑查询​

五、性能优化​

5.1 嵌入提供商选择​

5.2 重排序器（Reranker）​

5.3 分块策略​

5.4 索引优化​

六、运维与监控​

6.1 健康检查​

6.2 版本管理​

6.3 备份与恢复​

6.4 日志与调试​

七、与 Agent 平台集成​

7.1 OpenClaw 集成​

7.2 技能路由​

7.3 自定义技能​

八、最佳实践​

8.1 命名规范​

8.2 页面模板​

8.3 定期维护​

九、故障排查​

9.1 常见问题​

9.2 获取帮助​

十、进阶阅读​

相关文档​