跳到主要内容

gbrain sources 命令详解

GBrain 的 sources 命令系列用于管理多源知识库（Multi-source Brain）。
自 v0.18.0 起，一个 GBrain 数据库可以容纳多个独立的知识源（Source），每个源有自己的 slug 命名空间、同步状态和联邦搜索策略。

📖 背景：为什么需要多源？​

GBrain 的 source（知识源）概念类似于数据库中的 schema（模式）：

概念类比说明
Brain（大脑）一个 PostgreSQL 数据库物理上独立的存储实例
Source（源）数据库中的一个 schema逻辑上隔离的内容仓库

一个 brain 可以包含多个 source，每个 source 拥有：

  • 独立的 pages 命名空间（slug 只在一个 source 内唯一）
  • 独立的同步状态（last_sync_at）
  • 独立的联邦策略（federated 标记）
  • 独立的本地路径映射（local_path）

典型场景​

场景 1：统一搜索 —— 个人 Wiki + GStack 计划书

你的个人笔记放在 wiki，项目计划在 gstack。
两个都是你的知识，搜 "retry budgets" 时希望能同时查到。
→ 两个 source 都标记为 federated=true

场景 2：隔离存储 —— YC Media + Garry's List

两个完全不同的内容线，不希望搜索结果混合。
YC 投资组合文章不应该出现在个人随笔的搜索结果中。
→ 两个 source 标记为 federated=false

场景 3：混合模式 —— Wiki 联合 + 对话记录隔离

主 Wiki 联合启用（跨源搜索），
但对话/会话记录存入独立源，不污染搜索结果。
→ Wiki federated=true, 对话源 federated=false

📋 子命令总览​

子命令功能引入版本
add注册新知识源v0.18.0
list列出所有知识源v0.18.0
remove永久删除知识源v0.18.0
rename重命名显示名称v0.18.0
default设置默认知识源v0.18.0
attach / detach绑定/解绑当前目录v0.18.0
federate / unfederate切换联合搜索（联邦搜索）v0.18.0
archive软删除（保留数据）v0.26.5
restore恢复软删除的源v0.26.5
purge永久清理已归档源v0.26.5
archived查看已归档源v0.26.5
current查看当前解析的源v0.37.7
status显示源健康状态v0.40.3
audit审计源的磁盘文件v0.41
webhook管理 GitHub webhookv0.40
tracked-branch管理追踪分支v0.40
set-cr-mode设置上下文检索模式v0.40.3

🚀 核心子命令详解​

sources add —— 注册新知识源​

gbrain sources add <id> --path <路径> [选项]

参数说明：

参数必填说明
<id>✅源 ID，1-32 位小写字母数字加连字符（如 wiki, gstack, yc-media）
--path <路径>可选本地文件系统路径（与 --url 二选一）
--url <https-url>可选远程 Git URL（与 --path 二选一）
--name <显示名>可选显示名称，不传则默认用 ID
--federated可选启用联邦搜索（出现在跨源搜索中）
--no-federated可选关闭联邦搜索（仅显式 --source 时可搜索）
--clone-dir <路径>可选指定 clone 目录（配合 --url）

示例：

# 注册本地路径的知识源（联邦开启）
gbrain sources add gstack --path ~/.gstack --federated

# 注册远程 Git 仓库的知识源
gbrain sources add docs --url https://github.com/user/docs.git --federated

# 注册隔离的源（不出现在默认搜索中）
gbrain sources add sessions --path ~/sessions --no-federated

关于 --url：

  • 从 v0.40 起支持直接从远程 Git URL 创建源
  • 系统会自动 clone 到 $GBRAIN_HOME/clones/<id> 目录
  • 之后 gbrain sync --source <id> 会执行 git pull 同步

sources list —— 列出所有知识源​

gbrain sources list [--json]

输出示例：

SOURCES
───────
  default               federated       3 pages  never synced
  gstack                federated      42 pages  last sync 2024-06-01T10:30:00.000Z
  sessions              isolated        0 pages  never synced
  • --json：以 JSON 格式输出，便于程序化处理
  • 每行显示：源 ID、联邦状态、页面数量、最后同步时间

sources remove —— 永久删除知识源​

gbrain sources remove <id> [--yes] [--confirm-destructive] [--dry-run] [--keep-storage]

⚠️ 危险操作！删除会级联清除该源的所有页面、chunks、embeddings。

选项说明
--dry-run仅预览影响，不实际删除
--yes跳过确认提示
--confirm-destructive确认破坏性操作（当源有数据时必需）
--keep-storage保留底层存储（当前未实现）

不能删除 default 源。 default 源是 v0.18 前的向后兼容根源。

sources archive / restore / purge —— 软删除与恢复​

archive（软删除）​

gbrain sources archive <id>
  • 将源标记为已归档（隐藏于搜索）
  • 数据保留 72 小时（SOFT_DELETE_TTL_HOURS）
  • 可随时用 restore 恢复
  • 不能归档 default 源

restore（恢复）​

gbrain sources restore <id> [--no-federate]
  • 恢复被归档的源
  • 默认会重新联邦（re-federated）
  • --no-federate 可保持隔离状态
  • 如果源此前有远程 URL 且 clone 目录已被删除，会自动重新 clone

purge（永久删除）​

# 清理所有过期归档
gbrain sources purge

# 强制永久删除指定归档
gbrain sources purge <id> --confirm-destructive
  • 无参数时：清除所有超过 TTL 的已过期归档
  • 指定 ID 时：强制永久删除（需 --confirm-destructive）

archived（查看归档）​

gbrain sources archived [--json]
  • 列出被归档的源及其过期时间
  • 格式：id, pages 数量, 距离过期剩余小时

sources federate / unfederate —— 联合搜索（联邦搜索）​

gbrain sources federate <id>
gbrain sources unfederate <id>

联合搜索控制的搜索行为：

状态gbrain search "关键词" 的行为
federated=true该源出现在所有跨源联合搜索中
federated=false仅在 --source <id> 显式指定时搜索

联合翻转的额外效果（v0.40）：

  • 当联合化一个源且其 embedding 覆盖率不足 100% 时，会自动提交一个 embed-backfill 作业
  • 这确保联合开启后，所有内容立即可搜索

sources attach / detach —— 目录绑定​

cd ~/my-project && gbrain sources attach gstack
# 写入 .gbrain-source 文件到当前目录
# 之后在该目录及其子目录中运行 gbrain 命令，默认使用 gstack 源

gbrain sources detach
# 删除当前目录的 .gbrain-source 文件

解析优先级（source resolution）：

1. --source <id> 显式标志
2. GBRAIN_SOURCE 环境变量
3. .gbrain-source 文件（当前目录或祖先目录）
4. local_path 匹配（最长前缀胜出）
5. sources.default 配置（通过 `gbrain sources default <id>` 设置）
6. 回退到 "default" 源

sources current —— 查看当前解析的源​

gbrain sources current [--source <id>] [--json]

用途： 在执行破坏性操作前，确认当前命令会命中哪个源。

示例输出：

source: gstack
  tier: dotfile (/home/user/.gstack)
  • 显示当前解析到的源 ID 和解析层级（flag / env / dotfile / local_path / brain_default / seed_default）
  • 可传 --source <id> 来模拟指定标志会解析到哪个源（不实际执行）

sources default —— 设置默认源​

gbrain sources default <id>
  • 设置 brain 级的默认源
  • 存储在大脑配置表（config 表）中，而非源配置中
  • 当没有其他更优先的解析规则时使用

sources rename —— 重命名显示名称​

gbrain sources rename <id> <new-name>
  • 只改显示名称（name 字段）
  • 源 ID 不可变，所有引用保持有效

sources status —— 源健康状态（v0.40.3+）​

gbrain sources status [--json]

显示所有注册源的运行状态仪表盘：

SOURCES — health
────────────────
  SOURCE                LAG      EMBED    FAILS   QUEUE    PAGES  LAST SYNC
  default               never    100%     0       0             3  never
  gstack                2h       95%      1       0            42  2024-06-01 10:30:00
  yc-media              0s       100%     0       0            15  2024-06-01 14:00:00
列说明
LAG距离上次同步的时间（never / Xs / Xm / Xh / Xd）
EMBEDembedding 覆盖率百分比
FAILS24 小时内失败的作业数
QUEUE队列深度
PAGES页面总数
LAST SYNC上次同步时间

警告提示：

  • 如果 local_path 不存在，提示 "no local_path"
  • 如果从未同步，提示 "never synced — run gbrain sync --source <id>"
  • 如果 embedding 覆盖率低于 95% 且总 chunk 数大于 100，提示嵌入回填
  • 如果 24 小时内失败 >= 3 次，建议检查 gbrain jobs list --status failed

sources audit —— 审计源磁盘文件（v0.41+）​

gbrain sources audit <source-id> [--json] [--include-warns]

只读操作 —— 不会修改任何数据。

审计内容：

  • 文件数量和大小分布（p50 / p99 / max）
  • 硬拦截：匹配垃圾模式的文件（新 ingests 会拒绝）
  • 软拦截：仅超大文件（会写入但跳过 embedding）
  • 垃圾模式命中次数（按模式名分组）
  • Facts backfill 估算（对符合条件的页面估算 segment 数量和成本）

示例输出：

Source: gstack (/home/user/.gstack)
Files scanned: 42 markdown files
Size distribution: p50=2048 bytes, p99=24576 bytes, max=65536 bytes
Would-hard-block: 0
Would-soft-block: 1
Junk-pattern hits: llm_output ×3, autogenerated ×2
Facts backfill estimate: 0 eligible page(s), ~0 segments, ~$0.00.

🛠️ 高级子命令​

sources webhook —— GitHub Webhook 管理（v0.40+）​

配置 GitHub webhook 实现源数据的自动同步。

# 配置 webhook（会生成 secret 并显示）
gbrain sources webhook set <id> --github-repo owner/repo [--secret VAL]

# 查看 webhook 配置（不显示 secret）
gbrain sources webhook show <id>

# 轮换 secret
gbrain sources webhook rotate <id>

# 清除 webhook 配置
gbrain sources webhook clear <id>

配置后需要在 GitHub 仓库设置中添加 webhook：

  • Payload URL: http://<your-gbrain-http-url>/webhooks/github
  • Content type: application/json
  • Secret: 使用生成的 secret
  • Events: Push events
  • Active: ✅

sources tracked-branch —— 追踪分支管理（v0.40+）​

# 设置追踪分支
gbrain sources tracked-branch <id> --set main

# 自动检测当前分支
gbrain sources tracked-branch <id> --detect

# 查看当前追踪分支
gbrain sources tracked-branch <id>

sources set-cr-mode —— 上下文检索模式（v0.40.3+）​

gbrain sources set-cr-mode <id> <none|title|per_chunk_synopsis>
模式说明
none不附加上下文检索信息
title每个 chunk 附加标题
per_chunk_synopsis每个 chunk 附加摘要（最精确但更贵）

传 unset 或 default 清除覆盖，回退到全局模式的设置。

🔄 源解析优先级​

当任一命令需要选择一个源时，GBrain 按以下顺序解析（从前到后，最先匹配的生效）：

1. 显式标志:     --source <id>
2. 环境变量:     GBRAIN_SOURCE
3. 目录文件:     .gbrain-source（当前或祖先目录）
4. 路径匹配:     local_path 包含当前工作目录（最长前缀胜出）
5. 大脑默认:     通过 gbrain sources default <id> 设置
6. 种子默认:     回退到 "default" 源

目录绑定工作原理：

  • 在 ~/.gstack 中运行 gbrain sources attach gstack 会在该目录创建 .gbrain-source 文件
  • 之后在该目录或其子目录中运行 GBrain 命令，默认使用 gstack 源
  • 离开该目录后在其他位置运行，依然使用默认解析规则

📝 引文格式​

当 agent 接收到多源搜索结果时，必须以 [source-id:slug] 格式引用页面：

See [wiki:topics/ai] and [gstack:plans/multi-repo] for where this came from.

引文键是 sources.id（不可变）。重命名源只会改变显示名称，现有引文仍然有效。

⚡ 完整使用示例​

场景：建立个人知识库 + 项目库​

# 1. 初始化 GBrain
gbrain init --pglite
gbrain config set openai_api_key sk-...

# 2. 添加个人 Wiki 知识源
gbrain sources add wiki --path ~/my-wiki --federated

# 3. 添加项目计划知识源
gbrain sources add projects --path ~/project-plans --federated

# 4. 添加隔离的对话记录源
gbrain sources add sessions --path ~/sessions --no-federated

# 5. 绑定目录（目录内命令自动使用对应源）
(cd ~/my-wiki && gbrain sources attach wiki && gbrain sync --source wiki)
(cd ~/project-plans && gbrain sources attach projects && gbrain sync --source projects)

# 6. 跨源搜索（所有 federated=true 的源）
gbrain search "分布式系统设计"

# 7. 单源搜索
gbrain search "项目计划" --source projects

# 8. 查看健康状态
gbrain sources status

# 9. 设置默认源
gbrain sources default wiki

📚 相关文档​

提示： sources 命令是 GBrain 多源能力的核心。善用联邦搜索和目录绑定，可以实现灵活的知识组织方案。