【免费下载链接】gbrain
Garry's Opinionated OpenClaw/Hermes Agent Brain
导读
skills/maintain/SKILL.md 是 gbrain（Garry's Opinionated OpenClaw/Hermes Agent Brain）中最核心的"大脑维护"技能定义：它以一份可执行的技能契约，规定了周期性健康检查的 13 个质量维度（陈旧页、孤儿页、死链、缺失交叉引用、反向链接、引用规范、归档规则、标签一致性等）、gbrain dream 全量维护循环的相位编排，以及从 v0.36.4.0 起新增的"一条命令把脑健康分数修到目标值"的自动化修复路径。读完本文，你将掌握：如何用 gbrain doctor --remediate 自动巡检并修复知识库、如何理解并配置 synthesize/patterns 两个新相位、如何执行链接图与时间线回填、以及如何把健康检查集成进你的运维心跳。
技能定义与契约
维护技能以 gbrain 的技能清单（skill manifest）形式存在，文件头部声明了它的元数据与触发条件：
| 字段 | 值 | 说明 |
|---|---|---|
name | maintain | 技能唯一标识 |
version | 1.1.0 | 技能版本 |
upstream | maintain@fc834ee | 上游技能版本锁定 |
mutating | true | 本技能会写库/写盘，需要显式授权 |
tools | get_health, get_page, put_page, list_pages, get_backlinks, add_link, search | 技能运行时可用的 gbrain 工具面 |
触发词覆盖三类场景：健康检查（brain health、check backlinks、maintenance、orphan pages、stale pages）、图结构维护（extract links、build link graph、populate timeline、backfill graph、extract timeline entries）、以及语义维护（run dream、process today's session、synthesize my conversations、consolidate yesterday's conversations）。
技能契约（Contract）承诺五件事，这也是自动化质量门禁的基础：
- 所有健康维度都被检查（stale、orphan、dead links、cross-refs、backlinks、citations、filing、tags）；
- 每个发现的问题都有具体的修复动作；
- 反向链接铁律（back-link iron law）被强制执行；
- 引用格式按标准校验；
- 结果按维度统计数量上报。
两条维护路径：自主修复 vs 逐维巡检
自主路径（v0.36.4.0+）：一条命令把分数修到目标
当用户说"把大脑修到 90/100"或"修复所有问题"时，不要手工逐维度走，而是用单命令循环：
gbrain doctor --remediation-plan --json # 预览将要执行什么
gbrain doctor --remediate --yes --target-score 90 --max-usd 5
--remediation-plan 输出一个按依赖排序的修复计划（例如 sync 先于 extract、embed 在 consolidate 之后），每步带 est_seconds（预估耗时）与 est_usd_cost（预估 LLM 花费）。--remediate 则按计划逐步执行，每步以 Minion 作业（autopilot-cycle 式子作业）提交，并在每一步之间重新检查健康分数。--max-usd N 是硬成本上限——当计划总花费将超过上限时直接拒绝提交，防止无人值守时 synthesize 循环烧光 Anthropic 额度。
从源码看，这一流程被抽成了可复用的库函数，而非内联在 CLI 里：计划计算实现在 src/core/remediation/plan.ts，其 computeRemediationPlan 是纯读操作（从不入队、从不写库），基于 getHealth() + loadRecommendationContext() 调用 computeRecommendations 生成建议，再经 classifyChecks 判定可修复/被阻塞，最终给出 schema_version: 2 的计划结构，包含 brain_score_current、max_reachable_score、target_unreachable 标志与 blocked 列表。执行器在 src/core/remediation/run.ts，其 runRemediation 用 BudgetTracker 包裹整个循环、支持 checkpoint 断点续跑（--resume，按 plan_hash 绑定）、失败步骤级联中止后续依赖步骤（D5 cascade），并在每步之间基于最新健康数据重算计划（D7 scoped recheck）。CLI 层在 src/commands/doctor.ts 解析参数（--target-score 默认 90），计划的 SYNTHETIC_CHECK_NAMES 明确列出参与打分的五个维度：brain_score、sync_freshness、missing_embeddings、dead_links、orphan_pages（见 src/core/remediation/plan.ts）。
目标不可达时会主动退出而非空转循环：空大脑没有实体页时 graph_coverage 上限为 70；未配置 embedding key 时上限为 60。此时命令会报出缺失清单直接退出。
手动路径：逐维巡检
当以下情况出现时，应使用逐维巡检（下文 Phase 2 起的各小节）：
- 用户明确要求维度逐个审计；
- 正在排查分数卡在
--remediate天花板之下的原因； - 某个维度需要自动路径跳过的人工判断。
手动路径流程：1）运行健康检查获取仪表盘；2）逐维度检查并修复。
十三项健康维度逐项巡检
陈旧页（Stale pages）
compiled_truth（页面的综合事实结论区）早于最新时间线条目，说明评估结论没有吸收最新证据。做法：查看健康输出中的 stale 页数量；对每个 stale 页读全文、审查时间线、判断 compiled_truth 是否需要重写。
孤儿页（Orphan pages）
零入链的页面，没有人引用它。做法：判断它是"真的孤立"还是"缺链接"；从相关页加链，或标记待删除（删除前必须确认，见"质量规则"）。
死链（Dead links）
指向不存在页面的链接。做法：直接在 gbrain 中移除。
缺失交叉引用（Missing cross-references）
页面提到了实体名但没有正式链接。做法：读 compiled_truth，提取实体提及，在 gbrain 中创建链接。
链接图抽取（Link graph extraction）
当 link_count 为 0 或相对 page_count 偏低时，运行批量抽取：
gbrain extract links --dir ~/brain
该命令扫描所有 markdown 文件中的实体引用、See Also 小节与 frontmatter 字段，在数据库中创建带类型的链接。可用链接类型（配合 gbrain graph-query --type 使用）包括：attended、works_at、invested_in、founded、advises、mentions、source。
时间线抽取（Timeline extraction）
当 timeline_entry_count 为 0 时，从 markdown 抽取结构化时间线：
gbrain extract timeline --dir ~/brain
它解析 - **YYYY-MM-DD** | Source — Summary 与 ### YYYY-MM-DD — Title 两种格式。注意：抽取出的条目改善的是结构化查询（gbrain timeline），不改善向量检索。
Dream 循环（v0.23+）：synthesize + patterns
gbrain dream 运行完整维护循环，核心相位链为：
lint -> backlinks -> sync -> synthesize -> extract -> patterns -> embed -> orphans
（opt-in 相位如 atoms/concepts/drift 插在中间）。其中两个新相位负责把昨天的对话固化进长期记忆。
Synthesize 相位：两段式级联
- Triage 门控（先审后花）：从
dream.synthesize.session_corpus_dir读取 transcripts，先用廉价 utility 级评判模型（models.dream.triage）对每个新文件打 0–1 分（显著性 salience），并预抽取候选引用与实体，结果缓存在dream_verdicts（带评判模型与 prompt 版本）。单周期打分预算由dream.triage.max_ms限制（默认 5 分钟），未完成的文件下个周期重试，绝不静默拒绝。 - 通过门控的两条途径：分数 ≥
dream.triage.threshold（默认 0.5）直接通过；或者触发 verified-segment 救援——分数落在[dream.triage.rescue_floor, threshold)区间，但评判模型自带的引用片段中至少有dream.triage.rescue_min_segments（默认 2；设为 0 关闭）条能在 transcript 中逐字验证为子串，且内容类型在dream.triage.rescue_content_types（默认mixed,reflection,idea,strategy,people，不含 routine/technical）内。救援路径零额外 LLM 调用（直接重读缓存裁决），专门捞回普通 transcript 里埋着的真信号。 - 门控在读取时应用：调整 threshold 或救援旋钮后重新过门控不需要任何新的 LLM 调用。
gbrain dream retriage --dry-run只重放缓存分数（零 LLM 调用）排空积压队列，--reconcile-queue落队，--force则全量重判。retriage 与主循环读同一门控，所以 reconcile 永远不会取消救援准入的作业。 - 合成子代理：通过的文件按 transcript 分块扇出一个子代理，默认 one-shot 模式（
dream.synthesize.mode，默认oneshot）：对携带预检索 LINK CANDIDATES 清单（dream.synthesize.link_manifest，默认开）与写入白名单的 prompt 做一次无工具的补全，在写任何页面之前做端到端校验（slug 围栏、任务形状、wikilink）。校验失败的响应回退到同一作业内的经典 agentic 循环，受dream.synthesize.max_turns（默认 16）限制；回退拨盘：gbrain config set dream.synthesize.mode agentic。每个子代理写反思页（wiki/personal/reflections/...）与原创页（wiki/originals/ideas/...）；people 时间线条目仅在 agentic 路径写入。编排器从subagent_tool_executions（不是pages.updated_at，那会误收无关写入）收集新 slug，跑引用验证，再把每个新页从 DB 反向渲染回 markdown。 - 引用验证/修复（写后、零 LLM）：
dream.synthesize.quote_verify（默认开）检查本相位新建页面上的每个引用跨度与来源 transcript：完全一致保留；仅空白、弯引号、破折号或大小写差异的替换为逐字片段；近匹配同样修复；无法落地的保留文本但去掉引号——绝不捏造，也不删除内容。数字与日期类声明若在 transcript 中缺失只计为警告。遥测落在details.synthesis.quote_verify。
synthesize 的配置链路在 src/core/config.ts 中有完整注册（dream.synthesize.session_corpus_dir、max_turns、mode、link_manifest、quote_verify、dream.triage.threshold、rescue_floor、rescue_min_segments、rescue_content_types 等均为可配置键），门控读取逻辑在 src/core/cycle/synthesize.ts（rescue_band 即 [rescueFloor, threshold) 区间）。
Patterns 相位
在 extract 之后运行（保证图状态新鲜）：读取 dream.patterns.lookback_days（默认 30）内的反思页，用一次 Sonnet 调用浮出反复出现的主题，当 ≥ dream.patterns.min_evidence（默认 3）条反思支持某主题时写入 wiki/personal/patterns/<theme> 页面。完成的运行记录其消费的最新反思时间戳（dream.patterns.last_evidence_ts）；窗口内没有更新的反思时，重跑直接以 no_new_evidence 跳过，不再付模型调用费——gbrain dream --phase patterns --once 可强制跑一次。
合成质量铁律（6 条）
- 逐字引用用户：引号只用于能精确从 transcript 复现的片段；无法精确复现就无引号转述；不要转述本可逐字引用的难忘措辞（quote verify 相位会在写后机械强制执行）。
- 强迫式交叉引用：每个新页面至少有一个 wikilink。
- Slug 纪律：仅小写字母数字与连字符，禁止下划线与文件扩展名。
- 编辑过的 transcript 产生新 slug（content-hash 后缀变化），绝不静默覆盖。
- 保留具体事实：数字、日期、金额、人名、谁决定了什么，逐字携带；不填充例行物流信息。
- 每项主张都要有 transcript 依据：推测标注为推测；绝不陈述 transcript 未显示的完成态或结果。
信任边界（allowed_slug_prefixes）
合成子代理运行在一个显式写入白名单内，白名单来自 _brain-filing-rules.json 的 dream_synthesize_paths.globs。即使 prompt 注入成功，子代理也无法写到名单之外。信任来自 PROTECTED_JOB_NAMES——MCP 根本不能提交子代理作业；编辑 JSON 是允许合成器写入新目录的唯一途径。
幂等性与隐私
transcript 以 (file_path, content_hash) 为键，重跑相同内容是无操作。dream.synthesize.exclude_patterns（默认 ["medical", "therapy"]）在任何 LLM 调用前过滤掉对应 transcript；每条目自动包裹为词边界正则（medical 匹配 "medical advice" 但不匹配 "comedical"），高级用户可传完整正则。
冷却（Cooldown）
dream.synthesize.cooldown_hours（默认 12）意味着 autopilot 下每天最多约 2 次 synthesize。完成时间戳 dream.synthesize.last_completion_ts 只在成功运行时写入（跳过/失败不写）。显式 --input / --date / --from / --to 调用绕过冷却。
--dry-run 语义
运行打分 triage（对新文件评判并缓存裁决）但跳过合成子代理。这不是零 LLM 调用——想要零调用的缓存分数预览请用 gbrain dream retriage --dry-run。
新大脑上配置 synthesize
gbrain config set dream.synthesize.session_corpus_dir /path/to/transcripts
gbrain config set dream.synthesize.enabled true
gbrain dream --phase synthesize --dry-run --json # 预览
gbrain dream # 完整循环
调用模式汇总
gbrain dream # 完整循环
gbrain dream --phase synthesize # 只跑 synthesize
gbrain dream --phase patterns # 只跑 patterns
gbrain dream --input ~/transcripts/2026-04-25.txt # 单条 ad-hoc transcript
gbrain dream --from 2026-04-01 --to 2026-04-25 # 按日期区间回填
gbrain dream --json # 输出 CycleReport JSON
自动提交推迟到 v1.1：v1 只写 brain_dir 文件，不执行 git add / commit / push——要么自己提交，要么交给 gbrain autopilot。
Autopilot 检查
gbrain autopilot --status
退出码可用于门禁：0 表示新鲜（或未安装）；1 表示需要关注（心跳过期、从未运行、或被迁移暂停）；2 表示守护进程自行禁用（仓库路径消失）。--json 输出完整报告（state、heartbeat_age_seconds、paused_reason、disabled_reason）。状态只读文件系统，数据库宕机时依然可用。
未运行则安装：
gbrain autopilot --install --repo ~/brain
v0.11.1+ 中 autopilot 把每个周期作为单个 autopilot-cycle Minion 作业派发并监督 worker 子进程——一次安装即可获得 sync + extract + embed + backlinks + 持久作业处理。
修复半迁移安装
v0.11.0 安装（迁移技能未触发）会留下部分配置的 Minions：schema 已应用，但 ~/.gbrain/preferences.json 不存在、autopilot 内联运行、宿主清单仍引用 agentTurn。修复：
# 检查迁移状态
gbrain apply-migrations --list
# 应用待处理迁移（幂等；对健康安装安全）
gbrain apply-migrations --yes
若 ~/.gbrain/migrations/pending-host-work.jsonl 中标记了宿主相关 handler，按 skills/migrations/v0.11.0.md 与 docs/guides/plugin-handlers.md 逐个处理，在宿主仓库中注册 handler 后重跑 apply-migrations。完整排障指南见 docs/guides/minions-fix.md。
反向链接强制
逐条核对反向链接铁律：对每个最近更新的页面，检查其提及的实体是否在实体页有对应的反向链接。有提及无反向链接就是"大脑坏了"。修复方式：在实体的 Timeline 或 See Also 小节补上反向链接，格式为：
- **YYYY-MM-DD** | Referenced in page title -- brief context
归档规则违规
常见错误归档模式（完整规则见 skills/_brain-filing-rules.md）：有明确主主题的内容被归档在 sources/ 而非 people/、companies/、concepts/ 等对应目录。做法：用 gbrain search 找出 sources/ 中引用特定人/公司/概念的页面，标记为疑似误归档，交由人工复核或重新归档。
引用审计
抽查缺失 [Source: ...] 引用的页面：读 5–10 个最近更新的页面；检查 compiled_truth（线以上部分）有行内引用；检查时间线条目有来源归属；标记无出处的事实页面。
标签一致性
不一致的标签（如 vc vs venture-capital、ai vs artificial-intelligence）会割裂检索。用 gbrain 标签操作统一到最常见变体。
图结构回填（v0.10.3+）
links 与 timeline_entries 表是结构化图层，应在批量导入后周期性回填：
gbrain extract links --source db— 从引擎走页面回填结构化链接，读取Name/Name引用并推断关系类型，幂等；有 markdown checkout 时可用--source fs --dir <brain>走文件系统。gbrain extract timeline --source db— 解析页面内容中的- **YYYY-MM-DD** | summary行回填结构化时间线，幂等（DB UNIQUE 约束）。gbrain extract all --source db— 一次跑两者。gbrain graph-query <slug> --depth 2— 用任意已知实体 slug 探测连通性。gbrain stats— 抽取后验证link_count > 0与timeline_entry_count > 0。gbrain health— 查看实体页（person/company）的link_coverage与timeline_coverage百分比；低于 50% 说明需要更多抽取。实体页极少的脑上，两者报告too few to grade（JSON 中为null，分母由entity_page_count承载）而非误导性的 0%/100%——先增长实体集再行动。
从今往后，每次 gbrain put 调用都会通过 auto-link 后钩子自动创建并调和对齐链接（默认开；关闭：gbrain config set auto_link false）。因此 link-extract 基本是一次性回填；timeline-extract 应在批量导入或新增带日期条目后重跑。
功能采用检查（每周）
gbrain features --json # 扫描未充分利用的功能 + 建议
与 lint 一起每周运行。浮出缺失的 embeddings、未使用的集成与配置改进项。
Embedding 新鲜度
无 embedding 的 chunk，或旧模型嵌入的 chunk。大批量刷新（>1000 chunk）用 nohup 后台执行：
nohup gbrain embed refresh > /tmp/gbrain-embed.log 2>&1 &
然后 tail -1 /tmp/gbrain-embed.log 查看进度。
安全（RLS 验证）
运行 gbrain doctor --json 检查 RLS 状态：所有表都应显示 RLS 已启用；未启用则重跑 gbrain init。
Schema 健康
gbrain doctor --json 报告当前版本与期望版本。落后时 gbrain init 自动运行迁移。
文件存储健康
gbrain files verify— 检查所有 DB 记录的数据有效性；gbrain files status— 查看迁移状态（local、mirrored、redirected）；- 检查引用缺失存储文件的孤儿
.redirect.yaml指针； - 检查仍留在 git 中应迁往云存储的大二进制文件（≥ 100 MB）；
- 若配置了存储后端：验证重定向指针能解析（下载测试）。
开放线程
时间线中超过 30 天未解决行动项的条目，标记交由用户复核。
基准测试：搜索质量回归检测
周期性验证搜索质量未回退，按难度分四档跑查询集：
- Tier 1（实体查找）：已知名字——应总能解析；
- Tier 2（主题召回）：概念、主题——关键字搜索应能处理；
- Tier 3（语义）：无精确关键词匹配的查询——需要 embeddings；
- Tier 4（跨域）：关系/连接类查询——只有语义能处理。
对比 gbrain search（关键字）与 gbrain query（混合）的结果。质量比速度重要（2.5s 的正确结果胜过 200ms 的错误结果）。
何时运行基准：大脑大量导入/重导入之后、gbrain 版本升级之后、embedding 重新生成之后、以及每月跟踪质量漂移。
心跳集成：生产 Agent 的维护节奏
对于按计划运行的生产 Agent，把健康检查织入运维心跳：
-
每小时/每会话：
gbrain doctor --json检查退化项并上报。关键信号：连接健康、schema 版本、RLS 状态、embedding 陈旧度。 -
每周：
gbrain embed --stale刷新自上次 embedding 以来变更过的页面。大库（>5000 页）用 nohup：nohup gbrain embed --stale > /tmp/gbrain-embed.log 2>&1 & -
每月备份检查：
gbrain backup status，转发任何红色告警。它验证每个知识库（与 agent 工作区）都有 git 远端——仅本地意味着磁盘丢失即数据丢失。修复命令内联打印（gbrain bootstrap repo、git remote add、gbrain sources harden <id>）。 -
每日验证：
gbrain stats确认last_sync在 24 小时内。同步停止则大脑与仓库漂移。 -
陈旧 compiled truth 检测：标记 compiled truth 超过 30 天但时间线有近期条目的页面——存在未综合的新证据，需要重写（回到上面的维护流程）。
维护报告存储
每次维护运行后保存报告，形成随时间的审计轨迹：
- 各维度的健康检查结果（前后分数）；
- 发现并修复的反向链接违规；
- 发现的归档规则违规；
- 标记的引用缺口；
- 基准结果（如运行）；
- 需用户关注的问题清单。
质量规则与反模式
质量规则：未经确认绝不删除页面；所有变更通过时间线条目记录；维护前后各跑一次 health 以展示改进。
反模式清单（逐条对照自检）：
- 不读页面就修复——编辑前必须先理解上下文；
- 静默跳过维度——每个维度都必须检查并报告，即使干净；
- 不检查"是否应加链"就删孤儿页；
- 高峰时段跑 embedding 刷新；
- 未验证关系真实性就批量修反向链接；
- 不实际查询就标记维度"干净"；
- 不先读完整时间线就重写 compiled truth；
- 不检查其他页面是否同用该标签就移除标签。
输出格式：Brain Health Report
维护报告遵循以下结构（Markdown 表格 + 分维详情）：
## Brain Health Report — YYYY-MM-DD
| Dimension | Issues Found | Fixed | Remaining |
|----------------------|-------------|-------|-----------|
| Stale pages | N | N | N |
| Orphan pages | N | N | N |
| Dead links | N | N | N |
| Missing cross-refs | N | N | N |
| Back-link violations | N | N | N |
| Citation gaps | N | N | N |
| Filing violations | N | N | N |
| Tag inconsistencies | N | N | N |
| Embedding staleness | N | N | N |
| Security (RLS) | N | N | N |
| Schema health | N | N | N |
| File storage | N | N | N |
| Open threads | N | N | N |
### Details
[Per-dimension breakdown with specific pages and actions taken]
### Benchmark Results (if run)
[Tier 1-4 query results with pass/fail]
### Outstanding Issues
[Items requiring user attention or confirmation]
技能工具面
维护技能可调用的 gbrain 工具面（对应技能声明中的 tools 列表及其扩展）：get_health 检查脑健康、list_pages 带过滤器列页、get_page 读页、get_backlinks 查反向链接、add_link/remove_link 链接/移除实体、add_tag/remove_tag 标签操作、get_timeline 查看时间线。这些工具与 gbrain health、gbrain stats、gbrain doctor 等 CLI 互为表里，共同构成可编程的维护控制面。
结语
maintain 技能把"知识库保养"从手工巡检升级为可度量的工程实践：doctor --remediate 提供成本感知的自动修复闭环，dream 循环用 triage 门控 + 引用验证把对话固化进长期记忆，13 维健康报告则让每一次维护都可追溯、可对比。从源码看，plan/run 库化设计（src/core/remediation/plan.ts、src/core/remediation/run.ts）、synthesize 门控实现（src/core/cycle/synthesize.ts）与配置注册（src/core/config.ts）让这些能力不止于 CLI，还能被 onboard、MCP 与自动化心跳复用——这正是 gbrain 把"维护"做成技能而非脚本的原因。
【免费下载链接】gbrain
Garry's Opinionated OpenClaw/Hermes Agent Brain
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
