GBrain 从入门到精通：构建可引用的本地知识层

我最近把 GBrain 接到了一个 Agent 应用的应用侧。接入之前，我对它的理解比较简单：把团队文档导进去，然后让 Agent 搜索。

真正做起来之后，我发现 GBrain 的价值不只是“能不能搜到文档”，而是能不能把团队知识变成一层可检索、可引用、可版本化、可被 Agent 安全消费的 Knowledge Plane。

这篇文章记录我对 GBrain 的完整理解，也给出一条从本地 MVP 走向团队系统的实践路径。

一句话总结

GBrain 是一个面向 LLM 的知识组织和检索运行时：它把事实源编译成可查询的知识索引，再把相关内容以 Evidence 和 Citation 的形式交给 Agent。

它在系统里的位置可以表示成：

代码 / Spec / ADR / 团队文档
          ↓
      GBrain Ingestion
          ↓
   FTS / BM25 / Vector / Graph
          ↓
   Evidence + Citation + Revision
          ↓
    应用侧 / Agent Context
          ↓
       Codex / Qoder

GBrain 负责“知识怎么被找到和组织”，应用侧负责“谁能使用这些知识、作用于哪个 Workspace、最终执行是否成功”。两者不能混成一个边界。

GBrain 解决什么问题

普通聊天模型有三个天然限制：

• 不知道团队刚刚写下的内部规范。
• 不知道当前仓库的真实代码状态。
• 回答有依据时，也很难告诉你依据具体来自哪里。

把所有文档直接拼到 Prompt 里也不可行：内容太多、上下文太长、成本太高，还会把过期和无权限内容一起带进去。

GBrain 的基本任务就是把这个问题拆开：

1. 收集事实源。
2. 把事实源切成可检索的知识单元。
3. 建立关键词、语义和关系索引。
4. 根据问题取回最相关的 Evidence。
5. 为结果保留 Source、Citation、Provenance 和 Revision。
6. 把受治理的上下文交给 LLM。

所以，GBrain 不是“让模型记住一切”，而是让模型在需要时找到可信的外部事实。

先分清几个概念

Source：事实源

Source 是知识从哪里来的，例如：

• Git repository
• Markdown、PDF、设计文档
• 语雀文档、钉钉文档
• ADR、会议纪要、需求说明
• 构建报告、测试报告和发布回执

语雀或钉钉文档当然可以是 Source，但它们只是事实源，不等于已经完成治理的 Knowledge Asset。

Evidence：证据

Evidence 是能够支撑某个结论的具体内容片段。

例如：

Claim：Overlay 不修改基础 Revision。
Evidence：架构 Spec 中对 Overlay 的定义段落。
Citation：gbrain://default/example-workspace-spec

Evidence 不等于 Agent 的自述，也不等于一段没有来源的摘要。它应该能定位回原始文档、文件、行号或 Chunk。

Citation：引用

Citation 是 Evidence 的可回溯地址。在 GBrain 接入应用侧的 MVP 中，我使用类似下面的形式：

gbrain://default/example-workspace-knowledge-architecture

Citation 的价值是让用户知道答案为什么可信，也让后续的评测和审计有入口。

Revision：知识版本

同一个文件可能在不同时间代表不同事实。Revision 用来回答：

这条知识在哪个版本、哪个 Workspace、哪个时间范围内有效？

应用侧不允许拿旧 Revision 的索引结果冒充当前 Workspace 的知识。知识检索必须和当前 Session Pin、Workspace 和 Permission Scope 对齐。

GBrain 的内部数据流

一个比较完整的 GBrain 数据流如下：

Source
  ↓ parse
Document
  ↓ split
Chunk
  ↓ index
FTS / BM25 / Vector / Graph
  ↓ search
Evidence
  ↓ cite
Citation + Provenance
  ↓ compose
LLM Context

这里最容易犯的错误是把“索引”当成事实源。索引只是派生数据，应该可以从已验证的原始输入重新构建；真正的事实源应该保留自己的版本和摘要。

GBrain 如何检索

FTS 和 BM25

FTS 是 Full-Text Search，负责全文索引和关键词召回；BM25 负责对候选结果排序。

它们适合：

• 函数名、类名、错误码
• API 名称和配置项
• Workspace Revision 这类领域术语
• 代码和规范里的精确标识符

它们不真正理解语义，所以中文自然语言问题可能需要更好的分词、Query Rewrite 或 Vector Search。

Vector Search

Vector Search 通过 Embedding 把问题和文本放进向量空间，适合处理同义表达和自然语言描述。

例如：

Revision 是什么？
工作区如何固定可信资产？
如何保证 Agent 使用的知识版本一致？

这些问题的词不完全一样，但语义可能指向同一组文档。

Graph Search

当问题关注实体之间的关系时，图结构更有用：

Workspace Revision ──固定──> Asset Version
Overlay ──叠加于──> Revision
Projection ──派生自──> Revision
Evidence ──支撑──> Claim

实际系统通常会采用 Hybrid Retrieval：关键词保证精确术语，向量补足语义召回，图和 Metadata Filter 限定关系、权限和版本范围。

GBrain 和 LLM Wiki 的关系

LLM Wiki 可以理解为“知识治理层”，GBrain 可以作为它的知识运行时。

简单 RAG 重点是：

问题 → 找文本 → 塞 Prompt → 回答

成熟的 LLM Wiki 还要处理：

• 哪个 Source 是事实源？
• 两份文档冲突时谁优先？
• 这条知识是否已经过期？
• 当前用户有没有权限看到它？
• 结论能否回到 Evidence？
• 一次执行产生的结果能否经过审核后反哺知识库？

GBrain 提供检索和知识组织能力，但不应该直接拥有组织发布权，也不应该替应用侧作出 Permission 或 Approval 决策。

在应用侧的正确位置

应用侧通过 Codex 和 Qoder 执行任务，因此 GBrain 最适合放在应用侧后面：

Agent Chat UI
      ↓
应用侧
  ├── Workspace / Revision / Permission
  ├── GBrain Adapter
  ├── Session Pin
  ├── Approval
  └── Evidence / Audit
      ↓
Codex / Qoder Provider

这样做有三个好处：

1. Provider 不需要分别理解 GBrain、Sirchmunk 和 Understand Anything。
2. 应用侧可以先做 Workspace、Revision 和权限过滤。
3. GBrain 不可用时，可以降级为无知识检索，不阻断 Agent 主流程。

当前 MVP 的具体行为是：

• 将 Bun 和固定版本的 GBrain 一起打进桌面应用。
• 用户不需要安装 Bun、GBrain 或 Postgres。
• 使用本地 PGLite 保存 GBrain brain。
• 每个 Agent Turn 开始前最多检索 5 条知识。
• 结果通过只读上下文注入 Codex 或 Qoder。
• 检索超时约 8 秒时自动降级。
• 每条结果生成 gbrain:// Citation。

这是一个很重要的工程原则：GBrain 增强 Agent，但不应该成为 Agent 执行的单点故障。

从零搭建 GBrain 的实践顺序

第一步：确定事实源

不要一开始就把所有文件都导进去。先选择高价值、相对稳定的内容：

docs/specs/
docs/adr/
CONTEXT.md
核心 README

代码仓库可以接入，但需要区分“团队长期知识”和“当前 Raw Files”。变化很快的源码，更适合作为当前 Turn 的上下文或通过专门的 Code Search 读取。

第二步：给 Source 补 Metadata

至少保留这些字段：

{
  "source": "example-repository",
  "workspace": "example-workspace",
  "revision": "git-sha-or-asset-digest",
  "scope": "team",
  "path": "docs/specs/architecture.md",
  "updatedAt": "2026-07-22T12:00:00Z"
}

没有 Metadata 的索引，很快会变成一个无法解释、无法隔离、无法清理的文本仓库。

第三步：先实现可解释检索

第一版建议从 FTS/BM25 开始，因为它快、便宜、结果可解释。先确保：

• 能命中精确领域词。
• 能返回 Source 和 Citation。
• 能按 Revision 过滤。
• 没有结果时能明确返回空。

再根据评测结果加入 Embedding，而不是为了“看起来先进”一开始就堆完整检索栈。

第四步：把检索结果包装成 Evidence

不要把原始搜索结果直接拼接给模型。建议统一成：

{
  "content": "Overlay 不修改基础 Revision……",
  "source": "example-workspace-spec",
  "citation": "gbrain://default/example-workspace-spec",
  "revision": "workspace-revision-digest",
  "score": 0.99,
  "retrievedAt": "2026-07-22T12:00:00Z"
}

这样 LLM 得到的是可治理的上下文，而不是一堆没有身份的文本。

第五步：建立拒答和降级策略

知识系统必须允许三个结果：

命中可靠 Evidence → 基于证据回答
命中不足 → 明确说明依据不足
GBrain 不可用 → 降级执行，并记录诊断信息

最危险的状态是“没有命中，但模型假装命中了”。因此 Prompt 和 Adapter 都应该要求：没有 Citation 的关键结论不得伪装成团队事实。

如何验证 GBrain 是否真的有效

不要只看界面显示“已连接”。至少做四组测试。

正向命中

只根据当前 Workspace 的本地知识回答：
Projection、Overlay、Workspace Revision 三者有什么区别？
每条关键结论附上 gbrain:// Citation。

检查定义是否正确、Citation 是否存在、来源是否能回溯。

负向拒答

当前应用已上线的云端 Control Plane 域名是什么？
如果知识库没有可靠证据，请回答不知道。

如果知识库没有这个事实，系统应该拒答或声明依据不足。

A/B 对照

同一批问题分别在 GBrain 开启和关闭时运行，比较：

• 正确率
• Citation 覆盖率
• 幻觉率
• 首 token 延迟和总延迟
• Agent 是否减少了重复探索

版本隔离

修改一份 Spec，建立新 Revision，再查询旧 Session 和新 Session。旧 Session 不应该突然看到新版本，新 Session 也不应该读取旧索引冒充当前知识。

生产化时最容易踩的坑

把数据库当成事实源

GBrain database、FTS index、Vector index 都应该是可重建的派生实现。跨云端和本地同步时，同步版本化 Knowledge Asset，不要粗暴复制数据库文件。

把执行结果直接写回 Wiki

一次 Agent 执行产生的 Log、Diff、测试结果属于 Execution Evidence。它不能未经审核就变成团队当前事实。

正确的闭环是：

Execution Evidence
  → Knowledge Draft
  → Citation / Conflict Check
  → Review Gate
  → Published Knowledge

把三个工具都暴露给 Provider

GBrain、Sirchmunk、Understand Anything 可以各自擅长不同问题，但不应该让 Codex 或 Qoder 自己决定调用哪一个。应该由 Host 做意图路由：

最终 Provider 只看到统一的 Knowledge Context 契约。

要不要用 / 我的判断框架

GBrain 值得使用，但不要把它当成“装上就拥有团队记忆”的黑盒。

我的落地顺序是：

先接入高价值事实源
→ 先用 FTS/BM25 验证精确检索
→ 补 Evidence 和 Citation
→ 再加入 Vector Search
→ 关系稳定后再建 Graph
→ 最后补权限、Revision、冲突和审核

对应用侧来说，GBrain 的第一目标不是回答所有问题，而是让 Agent 在执行前拿到当前 Workspace 可用、来源明确、版本一致的知识。

如果它能让 Agent 少猜一次、少重复读一次 Spec、少改错一次代码，并且能解释“为什么这么做”，那它就已经从一个搜索工具变成了真正有价值的 Knowledge Plane。