Back to Details

maintain

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Maintain Skill

维护Skill

Periodic brain health checks and cleanup.
定期执行大脑健康检查与清理工作。

Contract

协议

This skill guarantees:
  • All health dimensions are checked (stale, orphan, dead links, cross-refs, backlinks, citations, filing, tags)
  • Each issue found has a specific fix action
  • Back-link iron law is enforced
  • Citation format is validated against the standard
  • Results are reported with counts per dimension
本Skill保证：
  • 检查所有健康维度（过时页面、孤立页面、失效链接、交叉引用、反向链接、引用、归档、标签）
  • 每个发现的问题都有具体的修复操作
  • 强制执行反向链接铁则
  • 根据标准验证引用格式
  • 按维度统计结果并报告

Phases

执行阶段

  1. Run health check. Check gbrain health to get the dashboard.
  2. Check each dimension:
  1. 运行健康检查。检查gbrain健康状况以获取仪表盘。
  2. 检查每个维度：

Stale pages

过时页面

Pages where compiled_truth is older than the latest timeline entry. The assessment hasn't been updated to reflect recent evidence.
  • Check the health output for stale page count
  • For each stale page: read the page from gbrain, review timeline, determine if compiled_truth needs rewriting
compiled_truth早于最新时间线条目的页面。评估内容未更新以反映最新证据。
  • 查看健康输出中的过时页面数量
  • 对于每个过时页面：从gbrain读取页面内容，查看时间线，判断是否需要重写compiled_truth

Orphan pages

孤立页面

Pages with zero inbound links. Nobody references them.
  • Review orphans: are they genuinely isolated or just missing links?
  • Add links in gbrain from related pages or flag for deletion
没有入站链接的页面，即没有任何页面引用它们。
  • 审核孤立页面：它们是真的孤立还是只是缺少链接？
  • 在gbrain中从相关页面添加链接，或标记为待删除

Dead links

失效链接

Links pointing to pages that don't exist.
  • Remove dead links in gbrain
指向不存在页面的链接。
  • 在gbrain中移除失效链接

Missing cross-references

缺失交叉引用

Pages that mention entity names but don't have formal links.
  • Read compiled_truth from gbrain, extract entity mentions, create links in gbrain
提及实体名称但未添加正式链接的页面。
  • 从gbrain读取compiled_truth，提取实体提及内容，在gbrain中创建链接

Link graph extraction

链接图谱提取

If link_count is 0 or low relative to page_count, run batch extraction:
bash
gbrain extract links --dir ~/brain
This scans all markdown files for entity references, See Also sections, and frontmatter fields, then creates typed links in the database.
如果link_count为0或相对于page_count较低，运行批量提取：
bash
gbrain extract links --dir ~/brain
此命令会扫描所有markdown文件中的实体引用、“另请参阅”部分和前置元数据字段，然后在数据库中创建带类型的链接。

Timeline extraction

时间线提取

If timeline_entry_count is 0, extract structured timeline from markdown:
bash
gbrain extract timeline --dir ~/brain
Parses 
- **YYYY-MM-DD** | Source — Summary
and 
### YYYY-MM-DD — Title
formats. Note: extracted entries improve structured queries (
gbrain timeline
), not vector search.
如果timeline_entry_count为0，从markdown中提取结构化时间线：
bash
gbrain extract timeline --dir ~/brain
解析 
- **YYYY-MM-DD** | Source — Summary
和 
### YYYY-MM-DD — Title
格式。 注意：提取的条目可改进结构化查询（
gbrain timeline
），但对向量搜索无帮助。

Autopilot check

Autopilot检查

Verify autopilot is running:
bash
gbrain autopilot --status
If not running, install it:
bash
gbrain autopilot --install --repo ~/brain
Autopilot runs sync, extract, and embed in a continuous loop with adaptive scheduling. In v0.11.1+, autopilot dispatches each cycle as a single 
autopilot-cycle
Minion job and supervises the worker child — one install step gives you sync + extract + embed + backlinks + durable job processing.
验证autopilot是否正在运行：
bash
gbrain autopilot --status
如果未运行，则安装它：
bash
gbrain autopilot --install --repo ~/brain
Autopilot会以自适应调度持续循环运行同步、提取和嵌入操作。 在v0.11.1及以上版本中，autopilot会将每个周期作为单个
autopilot-cycle
Minion任务分发，并监督工作子进程——一次安装即可获得同步+提取+嵌入+反向链接+持久化任务处理功能。

Fix a half-migrated install

修复半迁移安装

A v0.11.0 install where the migration skill never fired leaves Minions partially set up: schema is applied, but 
~/.gbrain/preferences.json
doesn't exist, autopilot runs inline, host manifests still reference 
agentTurn
. Repair:
bash
undefined
在v0.11.0版本安装中，如果迁移Skill未触发，会导致Minions仅部分设置完成：架构已应用，但
~/.gbrain/preferences.json
不存在，autopilot以内联方式运行，主机清单仍引用
agentTurn
。修复步骤：
bash
undefined

Check migration status

检查迁移状态

gbrain apply-migrations --list
gbrain apply-migrations --list

Apply pending migrations (idempotent; safe on healthy installs)

应用待处理迁移（幂等操作；在健康安装上执行是安全的）

gbrain apply-migrations --yes
gbrain apply-migrations --yes

If host-specific handlers are flagged in ~/.gbrain/migrations/pending-host-work.jsonl:

如果~/.gbrain/migrations/pending-host-work.jsonl中标记了主机特定处理程序：

walk them per skills/migrations/v0.11.0.md + docs/guides/plugin-handlers.md,

按照skills/migrations/v0.11.0.md + docs/guides/plugin-handlers.md中的步骤操作，

ship handler registrations in the host repo, then re-run apply-migrations.

在主机仓库中提交处理程序注册，然后重新运行apply-migrations。


Full troubleshooting guide: `docs/guides/minions-fix.md`.
完整故障排除指南：`docs/guides/minions-fix.md`。

Back-link enforcement

反向链接强制执行

Check that the back-linking iron law is being followed:
  • For each recently updated page, check if entities mentioned in it have corresponding back-links FROM those entity pages
  • A mention without a back-link is a broken brain
  • Fix: add the missing back-link to the entity's Timeline or See Also section
  • Format: 
    - **YYYY-MM-DD** | Referenced in [page title](path) -- brief context
检查是否遵循反向链接铁则：
  • 对于每个最近更新的页面，检查其中提及的实体是否在对应实体页面上有相应的反向链接
  • 提及实体但无反向链接会导致大脑数据损坏
  • 修复方法：在实体的时间线或“另请参阅”部分添加缺失的反向链接
  • 格式：
    - **YYYY-MM-DD** | 引用自[页面标题](路径) -- 简要上下文

Filing rule violations

归档规则违规

Check for common misfiling patterns (see 
skills/_brain-filing-rules.md
):
  • Content with clear primary subjects filed in 
    sources/
    instead of the appropriate directory (people/, companies/, concepts/, etc.)
  • Use gbrain search to find pages in 
    sources/
    that reference specific people, companies, or concepts -- these may be misfiled
  • Flag misfiled pages for review or re-filing
检查常见的错误归档模式（详见
skills/_brain-filing-rules.md
）：
  • 具有明确主题的内容被归档在
    sources/
    目录而非适当的目录（people/、companies/、concepts/等）
  • 使用gbrain搜索查找
    sources/
    目录中提及特定人物、公司或概念的页面——这些页面可能被错误归档
  • 标记错误归档页面以供审核或重新归档

Citation audit

引用审计

Spot-check pages for missing 
[Source: ...]
citations:
  • Read 5-10 recently updated pages
  • Check that compiled truth (above the line) has inline citations
  • Check that timeline entries have source attribution
  • Flag pages where facts appear without provenance
抽查页面是否缺失
[Source: ...]
引用：
  • 读取5-10个最近更新的页面
  • 检查线上的compiled truth是否有内联引用
  • 检查时间线条目是否有来源归因
  • 标记无来源依据的事实页面

Tag consistency

标签一致性

Inconsistent tagging (e.g., "vc" vs "venture-capital", "ai" vs "artificial-intelligence").
  • Standardize to the most common variant using gbrain tag operations
标签不一致（例如“vc”与“venture-capital”，“ai”与“artificial-intelligence”）。
  • 使用gbrain标签操作将标签标准化为最常用的变体

Embedding freshness

嵌入新鲜度

Chunks without embeddings, or chunks embedded with an old model.
  • For large embedding refreshes (>1000 chunks), use nohup: 
    nohup gbrain embed refresh > /tmp/gbrain-embed.log 2>&1 &
  • Then check progress: 
    tail -1 /tmp/gbrain-embed.log
没有嵌入向量的块，或使用旧模型生成嵌入向量的块。
  • 对于大规模嵌入刷新（>1000个块），使用nohup： 
    nohup gbrain embed refresh > /tmp/gbrain-embed.log 2>&1 &
  • 然后检查进度：
    tail -1 /tmp/gbrain-embed.log

Security (RLS verification)

安全性（RLS验证）

Run 
gbrain doctor --json
and check the RLS status. All tables should show RLS enabled. If not, run 
gbrain init
again.
运行
gbrain doctor --json
并检查RLS状态。 所有表应显示RLS已启用。如果未启用，重新运行
gbrain init
。

Schema health

架构健康

Check that the schema version is up to date. 
gbrain doctor --json
reports the current version vs expected. If behind, 
gbrain init
runs migrations automatically.
检查架构版本是否为最新版本。
gbrain doctor --json
会报告当前版本与预期版本。如果版本落后，
gbrain init
会自动运行迁移。

File storage health

文件存储健康

Check the integrity of stored files and redirect pointers:
  • Run 
    gbrain files verify
    to check all DB records have valid data
  • Run 
    gbrain files status
    to see migration state (local, mirrored, redirected)
  • Check for orphan 
    .redirect.yaml
    pointers that reference missing storage files
  • Check for large binary files (>= 100 MB) still in git that should be in cloud storage
  • If storage backend is configured: verify redirect pointers resolve (download test)
检查存储文件和重定向指针的完整性：
  • 运行
    gbrain files verify
    以检查所有数据库记录是否有有效数据
  • 运行
    gbrain files status
    查看迁移状态（本地、镜像、重定向）
  • 检查引用缺失存储文件的孤立
    .redirect.yaml
    指针
  • 检查仍存储在git中、应转移到云存储的大型二进制文件（>=100 MB）
  • 如果配置了存储后端：验证重定向指针可解析（下载测试）

Open threads

未处理任务

Timeline items older than 30 days with unresolved action items.
  • Flag for review
超过30天未解决的时间线任务项。
  • 标记以供审核

Benchmark Testing

基准测试

Periodically verify search quality hasn't regressed. Run a battery of test queries across difficulty tiers:
  • Tier 1 (entity lookup): known names -- should always resolve
  • Tier 2 (topic recall): concepts, topics -- keyword search should handle
  • Tier 3 (semantic): queries with no exact keyword match -- needs embeddings
  • Tier 4 (cross-domain): relational/connection queries -- only semantic handles
Compare results from 
gbrain search
(keyword) vs 
gbrain query
(hybrid). Quality matters more than speed (2.5s right > 200ms wrong).
When to run benchmarks:
  • After major brain imports or re-imports
  • After gbrain version upgrades
  • After embedding regeneration
  • Monthly to track quality drift
定期验证搜索质量是否未退化。运行一组不同难度级别的测试查询：
  • Tier 1（实体查找）： 已知名称——应始终能解析
  • Tier 2（主题召回）： 概念、主题——关键词搜索应能处理
  • Tier 3（语义搜索）： 无精确关键词匹配的查询——需要嵌入向量
  • Tier 4（跨领域）： 关系/关联查询——仅语义搜索能处理
比较
gbrain search
（关键词）与
gbrain query
（混合）的结果。 质量比速度更重要（2.5秒得到正确结果优于200毫秒得到错误结果）。
何时运行基准测试：
  • 完成重大大脑导入或重新导入后
  • 升级gbrain版本后
  • 重新生成嵌入向量后
  • 每月运行以跟踪质量漂移

Heartbeat Integration

心跳集成

For production agents running on a schedule, integrate gbrain health checks into your operational heartbeat.
对于按计划运行的生产环境Agent，将gbrain健康检查集成到你的运维心跳中。

On every heartbeat (hourly or per-session)

每次心跳（每小时或每次会话）

Run 
gbrain doctor --json
and check for degradation. Report any failing checks to the user. Key signals: connection health, schema version, RLS status, embedding staleness.
运行
gbrain doctor --json
并检查是否有性能下降。向用户报告任何失败的检查项。关键信号：连接健康状况、架构版本、RLS状态、嵌入向量过时情况。

Weekly maintenance

每周维护

Run 
gbrain embed --stale
to refresh embeddings for pages that have changed since their last embedding. For large brains (>5000 pages), run this with nohup:
bash
nohup gbrain embed --stale > /tmp/gbrain-embed.log 2>&1 &
运行
gbrain embed --stale
以刷新自上次嵌入后已更改页面的嵌入向量。对于大型大脑（>5000页面），使用nohup运行：
bash
nohup gbrain embed --stale > /tmp/gbrain-embed.log 2>&1 &

Daily verification

每日验证

Verify sync is running: check 
gbrain stats
and confirm 
last_sync
is within the last 24 hours. If sync has stopped, the brain is drifting from the repo.
验证同步是否正在运行：查看
gbrain stats
并确认
last_sync
在过去24小时内。如果同步已停止，大脑数据会与仓库脱节。

Stale compiled truth detection

过时compiled truth检测

Flag pages where compiled truth is >30 days old but the timeline has recent entries. This means new evidence exists that hasn't been synthesized. These pages need a compiled truth rewrite (see the maintain workflow above).
标记compiled truth超过30天但时间线有最新条目的页面。 这意味着存在未被整合的新证据。这些页面需要重写compiled truth（参见上述维护工作流）。

Report Storage

报告存储

After maintenance runs, save a report:
  • Health check results (before/after scores for each dimension)
  • Back-link violations found and fixed
  • Filing rule violations found
  • Citation gaps flagged
  • Benchmark results (if run)
  • Outstanding issues requiring user attention
This creates an audit trail for brain health over time.
维护完成后，保存一份报告：
  • 健康检查结果（每个维度修复前后的分数）
  • 发现并修复的反向链接违规项
  • 发现的归档规则违规项
  • 标记的引用缺失项
  • 基准测试结果（如果已运行）
  • 需要用户关注的未解决问题
这会创建大脑健康状况随时间变化的审计跟踪记录。

Quality Rules

质量规则

  • Never delete pages without confirmation
  • Log all changes via timeline entries
  • Check gbrain health before and after to show improvement
  • 未获确认绝不删除页面
  • 通过时间线条目记录所有更改
  • 维护前后检查gbrain健康状况以显示改进效果

Anti-Patterns

反模式

  • Fixing pages without reading them first -- you must understand context before editing
  • Silently skipping dimensions -- every dimension must be checked and reported, even if clean
  • Deleting orphan pages without checking if they should be linked instead
  • Running embedding refresh during peak usage hours
  • Batch-fixing back-links without verifying the relationship is real
  • Marking a dimension "clean" without actually querying it
  • Rewriting compiled truth without reading the full timeline first
  • Removing tags without checking if other pages use the same tag consistently
  • 未阅读页面就直接修复——编辑前必须理解上下文
  • 悄悄跳过某些维度——每个维度都必须检查并报告，即使没有问题
  • 未检查是否应添加链接就删除孤立页面
  • 在高峰使用时段运行嵌入向量刷新
  • 批量修复反向链接但未验证关系是否真实
  • 未实际查询就标记某个维度“无问题”
  • 未完整阅读时间线就重写compiled truth
  • 未检查其他页面是否一致使用该标签就移除标签

Output Format

输出格式

The maintenance report follows this structure:
undefined
维护报告遵循以下结构：
undefined

Brain Health Report — YYYY-MM-DD

大脑健康报告 — YYYY-MM-DD

DimensionIssues FoundFixedRemaining
Stale pagesNNN
Orphan pagesNNN
Dead linksNNN
Missing cross-refsNNN
Back-link violationsNNN
Citation gapsNNN
Filing violationsNNN
Tag inconsistenciesNNN
Embedding stalenessNNN
Security (RLS)NNN
Schema healthNNN
File storageNNN
Open threadsNNN
维度发现问题数已修复剩余问题
过时页面NNN
孤立页面NNN
失效链接NNN
缺失交叉引用NNN
反向链接违规NNN
引用缺失NNN
归档违规NNN
标签不一致NNN
嵌入向量过时NNN
安全性（RLS）NNN
架构健康NNN
文件存储NNN
未处理任务NNN

Details

详细信息

[Per-dimension breakdown with specific pages and actions taken]
[各维度细分，包含具体页面和已执行操作]

Benchmark Results (if run)

基准测试结果（若已运行）

[Tier 1-4 query results with pass/fail]
[Tier 1-4查询结果，包含通过/失败情况]

Outstanding Issues

未解决问题

[Items requiring user attention or confirmation]
undefined
[需要用户关注或确认的事项]
undefined

Tools Used

使用的工具

  • Check gbrain health (get_health)
  • List pages in gbrain with filters (list_pages)
  • Read a page from gbrain (get_page)
  • Check backlinks in gbrain (get_backlinks)
  • Link entities in gbrain (add_link)
  • Remove links in gbrain (remove_link)
  • Tag a page in gbrain (add_tag)
  • Remove a tag in gbrain (remove_tag)
  • View timeline in gbrain (get_timeline)
  • 检查gbrain健康状况（get_health）
  • 按过滤条件列出gbrain中的页面（list_pages）
  • 从gbrain读取页面（get_page）
  • 检查gbrain中的反向链接（get_backlinks）
  • 在gbrain中关联实体（add_link）
  • 在gbrain中移除链接（remove_link）
  • 在gbrain中为页面添加标签（add_tag）
  • 在gbrain中移除标签（remove_tag）
  • 查看gbrain中的时间线（get_timeline）