gbrain Doctor 前端元数据扫描增量化的架构设计从有界磁盘遍历到 DB-backed 增量状态Phase 2【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本篇技术指南以 gbrain 仓库中 docs/architecture/frontmatter-scan-incremental.md 为核心系统讲解 Doctorfrontmatter_integrity检查的现状有界磁盘遍历与 Phase 2 增量化的完整设计包括frontmatter_scan_state表结构、sync 侧 UPSERT 写入、增量扫描命令与 autopilot 周期相位、O(1) 的 Doctor 读取查询以及首次扫描、源归档、路径重命名等排序关注点。读完你既能理解 gbrain 现有 30 秒有界遍历的实现细节walkDir、pruneDir、GBRAIN_DOCTOR_FM_TIMEOUT_MS、partial 状态语义也能掌握一套把 O(N) 全量扫描演进为 O(1) SQL 聚合的落地方案与迁移步骤。一、为什么需要增量扫描现状与稳态成本gbrain 的 Doctor 诊断中包含一项frontmatter_integrity子检查它负责在磁盘上遍历大脑brain目录逐个解析所有.md文件的前端元数据frontmatter完整性。当前实现的核心特征如下磁盘遍历通过src/core/brain-writer.ts中的scanBrainSources入口启动内部使用walkDir递归遍历每个 source 的local_path。下潜时剪枝pruneDirwalkDir在每次进入子目录前调用 src/core/sync.ts 导出的pruneDir(name, parentDir)作为唯一剪枝门。跳过规则包括所有点前缀目录如.git、.obsidian、node_modules、ops、以.raw结尾的目录gbrain sidecar 约定、以及以 gitfile 形态出现的 git 子模块目录。该剪枝是 v0.38.2.0PR #1287解决 216K 页面大脑上gbrain doctor挂死问题的核心修复——此前 walker 会下潜到每个子树再在叶节点用isSyncable过滤白白为成千上万个永远不会被解析的 vendor 条目支付stat的 IO 成本。有界墙钟bounded wall-clock整个扫描在src/commands/doctor.ts的frontmatter_integrity分支src/commands/doctor.ts中受一个 deadline 约束超时默认 30 秒可用环境变量GBRAIN_DOCTOR_FM_TIMEOUT_MS覆盖解析逻辑见 src/commands/doctor.ts非有限或非正数时回退到 30000ms。诚实的部分状态scanBrainSources对每个 source 输出scanned / partial / skipped三态超时触发时 Doctor 会输出已扫描约 N 个文件该 source 在 DB 中约 M 个页面这样的诚实提示而不是把不完整的结果伪装成权威结论见 src/core/brain-writer.ts 中的markRemainingSkipped、between-source 截止检查、COUNT 查询与 deadline 的竞态处理。这套设计保证了大多数大脑秒级完成、任何大脑有界时间内完成但其稳态成本是O(N)每次 Doctor 运行都重新遍历文件系统并重新解析每个.md文件。对于 20 万以上页面的用户稳态耗时仍在秒级而要想让 Doctor 达到适合 cron 监控健康检查的亚秒级稳态扫描就必须增量化了——这正是本文档要解决的问题。二、Phase 2 目标与大脑规模无关的 Doctor设计文档给出明确目标Doctor 的frontmatter_integrity检查无论大脑规模多大都只执行 O(1) 次 SQL 查询完成同时保持与有界遍历相同的 per-source 明细和 partial-state 语义。关键的分摊思路是增量刷新incremental refresh作为sync 侧的写入加一个autopilot 周期相位运行把稳态工作量分摊到本来就会触碰每个文件的既有工作流中——sync 本来就逐文件解析顺带写一行状态即可autopilot 本来就周期性跑维护任务加一个相位即可。这样增量扫描的成本被摊销amortized掉了而不是新增一条独立的常驻成本。三、Schema 设计frontmatter_scan_state表设计文档给出的新表定义如下CREATE TABLE frontmatter_scan_state ( source_id TEXT NOT NULL REFERENCES sources(id) ON DELETE CASCADE, path TEXT NOT NULL, -- relative to source.local_path mtime_ms BIGINT NOT NULL, content_hash TEXT NOT NULL, -- sha256 of file content at scan time codes JSONB NOT NULL DEFAULT []::jsonb, -- ParseValidationCode[] last_scanned_at TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (source_id, path) ); CREATE INDEX frontmatter_scan_state_has_issues_idx ON frontmatter_scan_state (source_id) WHERE codes ! []::jsonb;各列的设计意图与工程权衡mtime_mscontent_hash增量检查在两者之间择一。mtime更快无需读文件内容一次stat即可但可能被touch之类的操作欺骗内容没变也算变了content_hash是真相truth能击败改了 mtime 但内容没变的场景。增量 walker 的策略是用 mtime 做快速闸门当 mtime 提示文件变更时再用 content_hash 兜底裁决——兼顾了速度与正确性。codesJSONB每行存放一个ParseValidationCode[]错误码列表NULL或[]表示该文件干净。Doctor 聚合时用jsonb_array_length(codes) 0判断是否有问题。部分索引WHERE codes ! []::jsonbDoctor 的聚合查询只遍历有问题的行。由于大部分页面是干净的有问题行的比例很小索引因此保持轻量。这是本设计的性能关键全表里干净行占绝大多数部分索引让发现问题的路径只扫到问题行。外键ON DELETE CASCADEsource 被删除时级联清理本表数据保证没有孤儿行。这里遵循了 gbrain 仓库中applyForwardReferenceBootstrap的经典模式见 src/core/pglite-engine.ts 与 src/core/postgres-engine.ts新增的表/列都要进入两个引擎的 bootstrap probe 集合。这样做的原因写在了 CLAUDE.md 中——旧大脑沿着 schema 链向前演进时如果代码引用了尚不存在的表就会卡死wedgebootstrap probe 用一次性information_schema探测避免这一情况。四、迁移形态追加 MIGRATIONS 条目 bootstrap probe设计文档给出了迁移代码的落点与形状// src/core/migrate.ts — append after the CURRENT last entry in the // MIGRATIONS array (take the next unused version number at implementation // time; the numbers below are placeholders, not a reserved slot) const migrations [ // ...existing entries... { version: NEXT_VERSION, // next unused number in the MIGRATIONS array name: frontmatter_scan_state, sql: CREATE TABLE IF NOT EXISTS frontmatter_scan_state (...); CREATE INDEX IF NOT EXISTS frontmatter_scan_state_has_issues_idx ...; , }, ];实际仓库中 MIGRATIONS 数组位于 src/core/migrate.ts实现时版本号取当前数组中的下一个未用数字文档特别强调占位数字不预留槽位以避免冲突。迁移除了 SQL 本身还需要在pglite-engine.ts与postgres-engine.ts两个引擎的 bootstrap probe 集合中各加一条frontmatter_scan_state表存在性探测扩展test/schema-bootstrap-coverage.test.ts中的REQUIRED_BOOTSTRAP_COVERAGE保证新表进入 bootstrap 覆盖清单防止未来有人把它漏掉。迁移 SQL 中的CREATE TABLE IF NOT EXISTS/CREATE INDEX IF NOT EXISTS保证了幂等性这是 gbrain 迁移链一贯的风格——旧大脑逐个版本向前走不会因重复执行而报错。五、写入路径两条数据写入管线1. Sync 侧写入canonical 路径src/core/sync.ts中的performSync本来就会解析它触碰的每一个文件。设计要求在现有的parseMarkdown调用之后把文件的path / mtime / content_hash / codes以UPSERT方式写入frontmatter_scan_state。其成本分析非常关键每个被 sync 的文件多一行 UPSERT而解析工作在 sync 中本来就已经发生零额外解析开销——相比 sync 已有的 parse DB 写这一行 UPSERT 可忽略不计。仓库中parseMarkdown的实际调用形态可以从 src/core/brain-writer.ts 看到parseMarkdown(content, relPath, { validate: true, expectedSlug })。这个{ validate: true }就是校验 frontmatter 的入口产出的ParseValidationCode[]正是codes列要存的内容——单一事实来源single source of truthPhase 2 不引入独立的校验规则集。2. 增量扫描gbrain frontmatter scan --incremental增量扫描器通过walkBrainTree遍历磁盘对每个文件检查mtime last_scanned_atmtime 快速闸门或content_hash ! storedhash 兜底裁决只有变更过的文件才会被重新解析。大部分运行周期里首次全量回填之后就是零工作——文件没变mtime 闸门直接放行连文件内容都不用读。该命令还暴露为 autopilot 的周期相位frontmatter_scan与 sync / extract / embed 等其他周期性维护相位并列运行设计文档明确不加新后台守护进程——而是挂进现有的autopilot-cycleMinion handler 作为新相位。增量 walker 弥补了 sync 漏掉的两类场景sync 之外的编辑用户直接在编辑器里改文件、保存但从未git commit——sync 只看到 git 触碰过的文件local_path不是 git 仓库的 sourcesync 只处理 git-tracked 文件这类 source 的文件 sync 完全看不到。这两类场景正是磁盘 walker 存在的意义也是它作为安全网不能被替换的原因。六、Doctor 读取器一次 SQL恒定时间Phase 2 的 Doctor 读取形态如下// src/commands/doctor.ts:frontmatter_integrity (Phase 2 shape) const rows await engine.executeRaw{ source_id: string; issues: number }( SELECT source_id, count(*) FILTER (WHERE jsonb_array_length(codes) 0)::int AS issues FROM frontmatter_scan_state GROUP BY source_id, );一条 SQL 查询与大脑规模无关无论 1K 还是 200K 页面都是同一查询。jsonb_array_length(codes) 0过滤有问题行配合部分索引frontmatter_scan_state_has_issues_idx只覆盖codes ! []的行聚合只扫问题行——干净行多的典型大脑上这条查询极快。partial-state 语义保留当frontmatter_scan_state数据过期时——某个已注册 source 没有任何行或某个 source 的last_scanned_at超过 24 小时未更新——Doctor 会警告数据新鲜度而不是把可能过期的数据当作权威结论报告。这与现有 bounded-walk 的诚实部分状态哲学一脉相承现有实现里partial/skipped/aborted_at_source字段会喂给 JSON 消费者见 src/commands/doctor.ts 的注释。七、排序关注点三个必须处理的边界情况1. 首次扫描fresh upgrade升级后frontmatter_scan_state是空表有两种方案Lazy推荐Doctor 报告尚无扫描状态请先运行gbrain frontmatter scan --incremental操作者驱动Eager创建表的迁移同时向 autopilot 排入一次全量扫描任务。文档明确推荐lazy 清晰提示。理由是 autopilot 路径是更重的表面积需要把新相位frontmatter_scan加进现有的 cycle.ts 机制以及 doctor-routed 后台任务系统。第一版先保持轻量。2. 源归档 / 删除frontmatter_scan_state.source_id带有ON DELETE CASCADE所以现有的软删除 72 小时 TTL purge流程会自动把它清理干净不需要额外逻辑。3. source 内部的路径重命名这是设计中最容易积累垃圾的场景sync 需要按 path 删除旧行、插入新行通过周期性 reconcile 步骤。如果没有这一步表里会积累陈旧的 path 行。两种处置方案增量扫描器内的 reconcile 步骤遍历期间任何未被看到的 path 行直接删除或作为新鲜度信号Doctor 报告N 条陈旧行用gbrain frontmatter scan --reconcile作为补救命令。八、成本估算设计文档给出的量化评估每个被 sync 的文件多一条 UPSERT相对 sync 已有的 parse DB 写可忽略不计增量刷新运行时主要由 mtime 的stat支配SSD 上约每 1000 个文件毫秒级Doctor 读取一条走索引的 SQL 查询任意大脑规模下亚 100ms。这组数字直接支撑了本文开头的目标表述稳态成本从 O(N)每次全量遍历 全量解析降到sync 顺带写一行 mtime 级增量刷新 一条索引查询。九、设计明确不做的事边界声明不替换 bounded-walk 安全网Phase 2 只是让稳态变便宜磁盘 walker含 deadline 检查继续作为 source 状态缺失或过期时的 source-of-truth 兜底。双保险belt-and-suspenders。不引入独立的 frontmatter 校验规则集复用parseMarkdown(..., { validate: true })和现有ParseValidationCode枚举单一事实来源。不新增后台守护进程挂进现有autopilot-cycleMinion handler 作为新相位与 sync / extract / embed 并列。十、留给实现者的开问题路径规范化pages.source_path与磁盘 walker 计算的相对路径相似但不完全相同斜杠、前导./等。增量扫描器必须与 sync 存储的路径完全一致否则 UPSERT 无法正确按 key 命中。动手前先审计。软删除交互DB 中软删除的页面在磁盘上仍有文件。增量扫描是否继续跟踪它的 frontmatter 状态文档倾向应该继续这样未来的restore_page不会因过期 frontmatter 而意外但需要与软删除模块的负责人确认。两阶段 rollout先落地表 写入让数据回填一个发布周期再切换 Doctor 读取器。这能避免Phase 2 上线了但表是空的这一尴尬局面——否则 Doctor 会回退到报告无扫描状态。十一、TODO 条目后续实施入口设计文档末尾给出了可直接落到 TODO 的条目- [ ] Implement Phase 2: DB-backed frontmatter scan state. Design lives at docs/architecture/frontmatter-scan-incremental.md. New schema migration sync-side UPSERT incremental scan command autopilot cycle phase doctor reader. Two-phase rollout: ship table writes first; flip the reader one release later.延伸阅读现有有界遍历的实现scanBrainSources / walkDir含 deadline、partial 状态、visitDir测试钩子剪枝规则的唯一事实来源pruneDirDoctor 侧当前调用与超时配置frontmatter_integrity 分支Bootstrap probe 模式pglite-engine.ts、postgres-engine.ts迁移数组与版本编排src/core/migrate.ts校验入口与错误码类型src/core/brain-writer.ts【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考