gbrain schema-author 技能全解从 7 阶段工作流到安全演进 Schema Pack 的实战指南【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain导读本文以 gbrain 仓库中 plugin/skills/schema-author/SKILL.md 为骨架完整解析 Agent 如何通过gbrain schema命令族对大脑的 Schema Pack页面类型、链接动词、前缀、标志进行创作型演进。你将掌握 gbrain 官方 Agent 技能中brain → assess → propose → apply → sync → verify → commit七阶段工作流、每条命令的完整参数与 JSON 输出契约、withMutation八步安全骨架的底层实现以及所有失败码与反模式的应对方案。读完即可让 Agent 安全地为研究脑、法务脑、创始人运营脑等自定义领域添加一等公民页面类型并回填存量页面。什么是 schema-author改规则的人而不是归档的人gbrain 的大脑brain由活跃的 Schema Pack 驱动。Pack 声明了大脑里存在哪些类型person、company、meeting、researcher、类型之间有哪些链接动词attended、authored、哪些类型参与事实抽取extractable: true、哪些类型参与专家路由expert_routing: true。schema-author 这个技能做的事只有一件改变 Pack 本身——添加页面类型、链接动词、前缀和标志即作者时间authoring time的规则修改。它与相邻职责有明确边界SKILL.md 的 Non-goals 部分场景正确去向给某一篇具体页面定归档位置这篇笔记放哪brain-taxonomist它负责写入时路由EIIRP 迭代中的 schema 检查eiirp 已内置 schema-check 阶段不要重复只想查看某个类型的设置直接gbrain schema explain type本技能用于改而非读查询谁了解某主题直接gbrain whoknows topicschema-author 只负责让类型可被专家路由不负责执行查询该技能的前置约定同样明确查找链路遵循 skills/conventions/brain-first.mdsearch → query → get_page → external何时加类型 vs 别名 vs 前缀的启发式规则遵循 skills/conventions/schema-evolution.md20 页不固化为包类型20–100 页加别名或窄前缀100 页才建一等类型。注schema-author 声明了brain_first: exempt技能前置元数据中的豁免标记因为它的职责是操作 Pack 文件本身而不是先查询大脑内容。何时触发技能的前置条件triggersSKILL.md 的 frontmatter 声明了该技能应被调用的用户意图包括但不限于Add aresearchertype to my schema向 schema 添加类型I have 4000 untyped pages undermeetings/存在大量未类型化页面My brain doesnt know thatjournal-articleis a typeSetpaperto be extractable设置可抽取标志Propose types from what Ive ingested从语料中提议新类型Sync the new types to backfill existing pages同步并回填存量页面反面触发不要调用本技能这篇笔记放哪用 brain-taxonomist谁知道 X用专家路由/gbrain whoknows。技能暴露的 27 个gbrain schema子命令与 7 个 MCP opget_active_schema_pack、list_schema_packs、schema_stats、schema_lint、schema_graph、schema_explain_type、schema_review_orphans、schema_apply_mutations、reload_schema_pack构成了完整能力面。对应的 CLI 实现集中在 src/commands/schema.ts1274 行按生命周期分组Inspection / Activation / Authoring / Discoveryrepair而底层纯函数位于src/core/schema-pack/目录mutate、sync、stats、review、lint-rules、expert-types、pack-lock、registry、query-cache-invalidator 等模块。七阶段工作流Agent 演进 Schema Pack 的标准路径SKILL.md 将完整的 schema 创作流程拆成七个阶段每一阶段对应明确的命令与判断信号。Phase 1 — Brain确认当前活跃 Packgbrain schema active --json输出包含pack_name、version、sha8、page_types_count、source_tier五个字段。关键判断若source_tier default说明用户在捆绑包gbrain-base上任何变更前必须先 fork进入 Phase 4。gbrain-base是开箱即用的通用起点22 个页面类型、12 个链接动词、hot/warm/cold 三种 takes kinds但它只是够用不是你的大脑的形状。MCP 侧对应get_active_schema_packCLI 的active子命令仅输出人类可读文本需要 JSON 时走 MCP op。Phase 2 — Assess评估当前 Pack 的覆盖情况gbrain schema stats --json返回每个类型的页面计数、未类型化untyped页面数以及dead_prefixesPack 声明但零匹配页面的前缀——很可能是误声明。若覆盖率 90%就存在值得类型化的未类型化内容。gbrain schema review-orphans --json未类型化页面下钻。寻找共享的路径前缀——例如这 12 页都在research/papers/下它们就是新类型的候选。该命令对应 src/core/schema-pack/review.ts 的实现。Phase 3 — Propose提议 Pack 应新增的类型gbrain schema detect --json按source_path聚类页面并提议候选类型。纯启发式无 LLM 调用因此成本低、可频繁运行。gbrain schema suggest --jsonLLM 精炼的候选带置信度分数。以 top-3 命中率作为哪些候选值得晋升为正式类型的信号。注意suggester 是启发式的可能提议与现有类型重叠的类型必须用lint --with-db在写入前拦截前缀冲突。Phase 4 — Apply变更 Pack本阶段命令最密集若活跃 Pack 是捆绑包gbrain-base或gbrain-recommended先 forkgbrain schema fork gbrain-base mine gbrain schema use minefork 产生gbrain-base的逐字节拷贝位于~/.gbrain/schema-packs/mine/pack.jsonuse将其激活写入~/.gbrain/config.json的schema_pack字段source_tier变为home-config。然后逐个添加类型gbrain schema add-type researcher \ --primitive entity \ --prefix people/researchers/ \ --extractable \ --expert参数语义与 manifest 字段一一对应参数含义底层字段--primitive entity原始类别entity/annotation/temporal等见PACK_PRIMITIVESprimitive--prefix people/researchers/路径前缀put_page 写入推断与 sync 回填的依据path_prefixes--extractable该类型参与extract_facts周期的事实抽取extractable: true--expert该类型参与whoknows/find_experts的专家路由expert_routing: true对于复杂多变更重构例如同时添加类型 指向它的链接动词通过 MCP 的批量 opschema_apply_mutations提交一次withPackLock作用域内原子完成、统一审计{op: add_type, name: researcher, primitive: entity, prefix: people/researchers/, extractable: true, expert_routing: true} {op: add_type, name: paper, primitive: annotation, prefix: research/papers/, extractable: true} {op: add_link_type, name: authored, inference: {page_type: researcher, target_type: paper}}sync 前先验证gbrain schema lint --with-db--with-db标志开启 4 条 DB 感知规则extractable_empty_corpus可抽取类型无对应语料、mutation_count_anomaly7 天内突变超 50 次、stored_type_is_aliasDB 中存储的类型实为别名、stored_type_undeclaredDB 存储了 Pack 未声明的类型。这 4 条规则能捕获只能在运行时才发现的类型误声明规则实现见 src/core/schema-pack/lint-rules.ts。底层原理withMutation 八步安全骨架。每次变更都走 src/core/schema-pack/mutate.ts 中的withMutation按失败安全顺序执行 8 步BUNDLED guard—— 捆绑包变更直接抛PACK_READONLY并记审计失败withPackLock—— 原子O_CREAT|O_EXCL锁刻意不用易 TOCTOU 的existsSyncwriteFileSync模式忙则抛LOCK_BUSYread parse—— 读取解析包文件解析失败抛PACK_CORRUPTmutator—— 执行变更函数runFilePlaneLintRules—— 文件平面 lint 校验无效抛INVALID_RESULTwriteAtomic——.tmp fsync rename原子写ENOSPC 抛IOauditSuccess → invalidatePackCache → invalidateQueryCachebest-effort绝不 throw锁由 finally 自动释放。不变量磁盘上的 Pack 文件绝不处于半写状态——要么第 6 步原子 rename 成功要么原文件原封不动崩溃残留的.tmp会在下次写入前被清理。两个并发 Agent 无法竞争写同一 Pack。Phase 5 — Sync将新类型回填到存量页面先 dry-rungbrain schema sync --json返回每个前缀的would_apply计数 示例 slug。数字确认无误后再执行gbrain schema sync --apply实现细节src/core/schema-pack/sync.ts分块 UPDATE每批 1000 行batchSize默认 1000可调每块 100ms批间释放行锁永不卡死并发写入者这是 v0.22.1statement_timeout代价换来的教训对应注释中的 D14 约束幂等第二次--apply找不到任何可回填的行写侧 source 作用域codex C5变更使用调用者ctx.sourceId的直接写权限而非可能继承 OAuth 联合读的sourceScopeOpts——MCP 的schema_apply_mutations在调度层同样强制执行PGLite 与 Postgres 通过executeRaw保持行为一致。每个前缀的结果结构PerPrefixResulttype、prefix、would_apply、sample_slugs最多 10 个Agent 的下钻信号、dead_prefix、applied。Phase 6 — Verify验证布线生效gbrain schema stats --json此时覆盖率应 ≥95%。gbrain whoknows machine learning若researcher声明了--expert结果中应出现 researcher 类型的页面。这是 pack-aware 布线的决定性验证查询路径读取活跃 Pack 中expert_routing: true的类型而非硬编码的[person, company]列表。实现见 src/core/schema-pack/expert-types.ts 的expertTypesFromPack——它按 manifest 声明顺序过滤expert_routing true的类型配套的expertTypesFromPackOrThrow在活跃 Pack 无任何专家类型时抛清晰错误而不是静默返回零结果。v0.38 之前的whoknows.ts硬编码DEFAULT_TYPES [person, company]codex finding #3 在三处源码中定位到该字面量。注意版本前提pack-aware 查询路径布线在v0.40.6.0加入v0.40.6 之前的脑会静默忽略自定义专家路由类型。Phase 7 — Commit持久化变更若 Pack 位于源码管理中提交cd ~/.gbrain/schema-packs/mine git add pack.json git commit -m schema: add researcher paper types authored link git push若大脑守护进程正在运行gbrain serve --http其他进程在 1 秒内即可感知变更——loadActivePack内置 stat-mtime TTL 门控v0.40.6.0 关闭了跨进程失效缺口。操作者从终端gbrain schema add-typeautopilot 守护进程无需重启即采纳新类型。输出契约Outputs Contract四类输出落点变更后的 Pack 文件~/.gbrain/schema-packs/name/pack.{json,yaml}审计行~/.gbrain/audit/schema-mutations-YYYY-Www.jsonl每次变更一条pages.type回填sync --apply后匹配行被更新查询路径whoknows、find_experts现在经由新专家类型路由输入 / 输出 / 副作用 / 幂等性契约输入命名了类型/前缀/链接动词/标志变更的自然语言请求或gbrain schema review-orphans显示需要新类型的未类型化页面的结果。输出变更后的 Pack 文件 审计行 若执行了sync --apply回填的pages.type。副作用使进程内 Pack 缓存 该 source 的查询缓存失效其他进程在 1 秒内stat-mtime TTL感知变更。幂等性每个原语都是幂等的。add-alias/add-prefix重复执行是 no-opsync --apply第二次运行找不到可更新行。信任模型CLI 本地信任无 scope 检查MCP OAuthadminscope写操作审计日志每条变更记录actor: mcp:clientId8。原子性每次变更都在withMutation原子写.tmp fsync rename 每 PackO_CREAT|O_EXCL锁内完成写入中途崩溃原文件不受影响。结构化输出格式Agent 可消费的 JSON单次变更结果{schema_version: 1, pack: mine, path: ~/.gbrain/schema-packs/mine/pack.json, format: json, prev_sha8: a1b2c3d4, new_sha8: e5f6g7h8}批量变更结果schema_apply_mutationsMCP op{schema_version: 1, pack: mine, batch_id: batch-1716491400-abc123, mutations_applied: 3, results: [{...}, {...}, {...}]}统计 JSON按 source 聚合 dead-prefix 提示{schema_version: 1, pack_identity: mine1.0.0abc12345, aggregate: {total_pages: 4823, typed_pages: 4710, untyped_pages: 113, coverage: 0.9766, by_type: [{type: person, count: 2104}, ...]}, per_source: [...], dead_prefixes: [{type: researcher, prefix: people/researchers/}]}Sync dry-run JSON{schema_version: 1, apply: false, pack_identity: mine1.0.0abc12345, per_prefix: [{type: meeting, prefix: meetings/, would_apply: 4000, sample_slugs: [meetings/2026-01-01-foo, ...], dead_prefix: false, applied: 0}], total_would_apply: 4000, total_applied: 0}人类可读输出Agent 最终总结每个变更一行Pack: name (format)Sha8: prev → new统计总页数、类型化百分比、未类型化计数、按类型分解、dead-prefix 列表sync 的每个前缀would_apply/applied计数 dry-run 模式下的示例 slug。失败时的错误信封遵循标准StructuredAgentError形状{error, code, message, details?}。反模式清单容易踩的六个坑不要直接变更gbrain-base或gbrain-recommended。必须先 forkgbrain schema fork gbrain-base mine。这两个是捆绑包直接编辑会在升级时丢失变更原语会以PACK_READONLY拒绝。不要为一次性 triage 导入的目录加类型。Pack 类型是永久决策一次性导入不是。参考 skills/conventions/schema-evolution.md 的20 页不固化启发式。不要给没有path_prefixes的类型加--expert。expert_routing_without_prefixlint 规则正是为此设计——没有前缀的专家路由类型永远匹配不到 put_page 推断whoknows会静默永不浮现它。不要未经验证就提升schema suggest候选。suggester 是启发式的可能提议与现有类型重叠的类型add-type前先跑lint --with-db捕获前缀冲突。不要跳过sync --apply前的 dry-run。先sync看would_apply计数 示例 slug。一个匹配 5 万页的 Pack 前缀虽然可恢复但很慢先验证的成本很低。不要不检查引用就移除类型。若其他类型的aliases/enrichable_types/link_types/frontmatter_links引用了目标类型remove-type以STILL_REFERENCED拒绝。先解除引用不要加--force。失败模式速查表错误码含义处置PACK_READONLY试图变更gbrain-base/gbrain-recommended先 forkPACK_NOT_FOUND指定的 Pack 不存在用gbrain schema list核对名称PACK_CORRUPTPack 文件解析失败检查 manifest 是否损坏第 3 步 parse 失败TYPE_EXISTS/TYPE_NOT_FOUND类型已存在 / 不存在用explain/stats核对INVALID_RESULT变更会产生悬空引用或前缀冲突读错误消息其中 lint 规则名即问题所在写前 lint 门禁已拦截STILL_REFERENCED移除的类型仍被其他类型的aliases/enrichable_types/link_types/frontmatter_links引用错误会列出每个引用先解除INVALID_PRIMITIVEprimitive 不在PACK_PRIMITIVES集合内核对entity/annotation/temporal等合法值IO_ERROR原子写失败如 ENOSPC检查磁盘空间原文件未受影响LOCK_BUSY另一进程正在变更中等 30 秒重试确认持锁者卡死时用--force偷陈旧锁而非跳过锁permission_denied仅 MCPOAuth 客户端无adminscopegbrain auth register-client --scopes admin重新注册从技能文档到实战配套资源5 分钟上手教程docs/schema-author-tutorial.md —— fork 捆绑包、加 researcher 类型、导入占位页、sync --apply回填、gbrain whoknows证明端到端布线全程无需 API key且提供完整的 undo 路径每个原语都有逆操作gbrain schema downgrade --to pack可恢复此前活跃 Pack。为什么要做7 个杀手级用例docs/what-schemas-unlock.md —— 4000 页隐形会议变成可查询、创始人运营脑、研究脑、法务脑、团队脑、Agent 联合策展以及类型在查询期起作用的结构性论证。何时加类型 vs 别名 vs 前缀skills/conventions/schema-evolution.md 的决策树。Agent 调度入口本技能文件本体 plugin/skills/schema-author/SKILL.mdfrontmatter 声明了全部 27 个 CLI 工具与 9 个 MCP 工具、triggers 与brain_first: exempt。架构落点CLI 分发表 src/commands/schema.ts变更骨架 src/core/schema-pack/mutate.ts专家路由 src/core/schema-pack/expert-types.ts回填核心 src/core/schema-pack/sync.ts。一句话总结schema-author 让 Agent 从给你归档升级为替你塑造大脑的类型学——通过原子锁、审计日志、MCP 批量 op 与查询路径的 pack-aware 布线以数据库级别的结构完整性保证安全地、可追溯地、幂等地演进 Schema Pack。这正是 gbrain 区别于堆了一堆标签的笔记应用的核心所在。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gbrain schema-author 技能全解：从 7 阶段工作流到安全演进 Schema Pack 的实战指南
gbrain schema-author 技能全解从 7 阶段工作流到安全演进 Schema Pack 的实战指南【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain导读本文以 gbrain 仓库中 plugin/skills/schema-author/SKILL.md 为骨架完整解析 Agent 如何通过gbrain schema命令族对大脑的 Schema Pack页面类型、链接动词、前缀、标志进行创作型演进。你将掌握 gbrain 官方 Agent 技能中brain → assess → propose → apply → sync → verify → commit七阶段工作流、每条命令的完整参数与 JSON 输出契约、withMutation八步安全骨架的底层实现以及所有失败码与反模式的应对方案。读完即可让 Agent 安全地为研究脑、法务脑、创始人运营脑等自定义领域添加一等公民页面类型并回填存量页面。什么是 schema-author改规则的人而不是归档的人gbrain 的大脑brain由活跃的 Schema Pack 驱动。Pack 声明了大脑里存在哪些类型person、company、meeting、researcher、类型之间有哪些链接动词attended、authored、哪些类型参与事实抽取extractable: true、哪些类型参与专家路由expert_routing: true。schema-author 这个技能做的事只有一件改变 Pack 本身——添加页面类型、链接动词、前缀和标志即作者时间authoring time的规则修改。它与相邻职责有明确边界SKILL.md 的 Non-goals 部分场景正确去向给某一篇具体页面定归档位置这篇笔记放哪brain-taxonomist它负责写入时路由EIIRP 迭代中的 schema 检查eiirp 已内置 schema-check 阶段不要重复只想查看某个类型的设置直接gbrain schema explain type本技能用于改而非读查询谁了解某主题直接gbrain whoknows topicschema-author 只负责让类型可被专家路由不负责执行查询该技能的前置约定同样明确查找链路遵循 skills/conventions/brain-first.mdsearch → query → get_page → external何时加类型 vs 别名 vs 前缀的启发式规则遵循 skills/conventions/schema-evolution.md20 页不固化为包类型20–100 页加别名或窄前缀100 页才建一等类型。注schema-author 声明了brain_first: exempt技能前置元数据中的豁免标记因为它的职责是操作 Pack 文件本身而不是先查询大脑内容。何时触发技能的前置条件triggersSKILL.md 的 frontmatter 声明了该技能应被调用的用户意图包括但不限于Add aresearchertype to my schema向 schema 添加类型I have 4000 untyped pages undermeetings/存在大量未类型化页面My brain doesnt know thatjournal-articleis a typeSetpaperto be extractable设置可抽取标志Propose types from what Ive ingested从语料中提议新类型Sync the new types to backfill existing pages同步并回填存量页面反面触发不要调用本技能这篇笔记放哪用 brain-taxonomist谁知道 X用专家路由/gbrain whoknows。技能暴露的 27 个gbrain schema子命令与 7 个 MCP opget_active_schema_pack、list_schema_packs、schema_stats、schema_lint、schema_graph、schema_explain_type、schema_review_orphans、schema_apply_mutations、reload_schema_pack构成了完整能力面。对应的 CLI 实现集中在 src/commands/schema.ts1274 行按生命周期分组Inspection / Activation / Authoring / Discoveryrepair而底层纯函数位于src/core/schema-pack/目录mutate、sync、stats、review、lint-rules、expert-types、pack-lock、registry、query-cache-invalidator 等模块。七阶段工作流Agent 演进 Schema Pack 的标准路径SKILL.md 将完整的 schema 创作流程拆成七个阶段每一阶段对应明确的命令与判断信号。Phase 1 — Brain确认当前活跃 Packgbrain schema active --json输出包含pack_name、version、sha8、page_types_count、source_tier五个字段。关键判断若source_tier default说明用户在捆绑包gbrain-base上任何变更前必须先 fork进入 Phase 4。gbrain-base是开箱即用的通用起点22 个页面类型、12 个链接动词、hot/warm/cold 三种 takes kinds但它只是够用不是你的大脑的形状。MCP 侧对应get_active_schema_packCLI 的active子命令仅输出人类可读文本需要 JSON 时走 MCP op。Phase 2 — Assess评估当前 Pack 的覆盖情况gbrain schema stats --json返回每个类型的页面计数、未类型化untyped页面数以及dead_prefixesPack 声明但零匹配页面的前缀——很可能是误声明。若覆盖率 90%就存在值得类型化的未类型化内容。gbrain schema review-orphans --json未类型化页面下钻。寻找共享的路径前缀——例如这 12 页都在research/papers/下它们就是新类型的候选。该命令对应 src/core/schema-pack/review.ts 的实现。Phase 3 — Propose提议 Pack 应新增的类型gbrain schema detect --json按source_path聚类页面并提议候选类型。纯启发式无 LLM 调用因此成本低、可频繁运行。gbrain schema suggest --jsonLLM 精炼的候选带置信度分数。以 top-3 命中率作为哪些候选值得晋升为正式类型的信号。注意suggester 是启发式的可能提议与现有类型重叠的类型必须用lint --with-db在写入前拦截前缀冲突。Phase 4 — Apply变更 Pack本阶段命令最密集若活跃 Pack 是捆绑包gbrain-base或gbrain-recommended先 forkgbrain schema fork gbrain-base mine gbrain schema use minefork 产生gbrain-base的逐字节拷贝位于~/.gbrain/schema-packs/mine/pack.jsonuse将其激活写入~/.gbrain/config.json的schema_pack字段source_tier变为home-config。然后逐个添加类型gbrain schema add-type researcher \ --primitive entity \ --prefix people/researchers/ \ --extractable \ --expert参数语义与 manifest 字段一一对应参数含义底层字段--primitive entity原始类别entity/annotation/temporal等见PACK_PRIMITIVESprimitive--prefix people/researchers/路径前缀put_page 写入推断与 sync 回填的依据path_prefixes--extractable该类型参与extract_facts周期的事实抽取extractable: true--expert该类型参与whoknows/find_experts的专家路由expert_routing: true对于复杂多变更重构例如同时添加类型 指向它的链接动词通过 MCP 的批量 opschema_apply_mutations提交一次withPackLock作用域内原子完成、统一审计{op: add_type, name: researcher, primitive: entity, prefix: people/researchers/, extractable: true, expert_routing: true} {op: add_type, name: paper, primitive: annotation, prefix: research/papers/, extractable: true} {op: add_link_type, name: authored, inference: {page_type: researcher, target_type: paper}}sync 前先验证gbrain schema lint --with-db--with-db标志开启 4 条 DB 感知规则extractable_empty_corpus可抽取类型无对应语料、mutation_count_anomaly7 天内突变超 50 次、stored_type_is_aliasDB 中存储的类型实为别名、stored_type_undeclaredDB 存储了 Pack 未声明的类型。这 4 条规则能捕获只能在运行时才发现的类型误声明规则实现见 src/core/schema-pack/lint-rules.ts。底层原理withMutation 八步安全骨架。每次变更都走 src/core/schema-pack/mutate.ts 中的withMutation按失败安全顺序执行 8 步BUNDLED guard—— 捆绑包变更直接抛PACK_READONLY并记审计失败withPackLock—— 原子O_CREAT|O_EXCL锁刻意不用易 TOCTOU 的existsSyncwriteFileSync模式忙则抛LOCK_BUSYread parse—— 读取解析包文件解析失败抛PACK_CORRUPTmutator—— 执行变更函数runFilePlaneLintRules—— 文件平面 lint 校验无效抛INVALID_RESULTwriteAtomic——.tmp fsync rename原子写ENOSPC 抛IOauditSuccess → invalidatePackCache → invalidateQueryCachebest-effort绝不 throw锁由 finally 自动释放。不变量磁盘上的 Pack 文件绝不处于半写状态——要么第 6 步原子 rename 成功要么原文件原封不动崩溃残留的.tmp会在下次写入前被清理。两个并发 Agent 无法竞争写同一 Pack。Phase 5 — Sync将新类型回填到存量页面先 dry-rungbrain schema sync --json返回每个前缀的would_apply计数 示例 slug。数字确认无误后再执行gbrain schema sync --apply实现细节src/core/schema-pack/sync.ts分块 UPDATE每批 1000 行batchSize默认 1000可调每块 100ms批间释放行锁永不卡死并发写入者这是 v0.22.1statement_timeout代价换来的教训对应注释中的 D14 约束幂等第二次--apply找不到任何可回填的行写侧 source 作用域codex C5变更使用调用者ctx.sourceId的直接写权限而非可能继承 OAuth 联合读的sourceScopeOpts——MCP 的schema_apply_mutations在调度层同样强制执行PGLite 与 Postgres 通过executeRaw保持行为一致。每个前缀的结果结构PerPrefixResulttype、prefix、would_apply、sample_slugs最多 10 个Agent 的下钻信号、dead_prefix、applied。Phase 6 — Verify验证布线生效gbrain schema stats --json此时覆盖率应 ≥95%。gbrain whoknows machine learning若researcher声明了--expert结果中应出现 researcher 类型的页面。这是 pack-aware 布线的决定性验证查询路径读取活跃 Pack 中expert_routing: true的类型而非硬编码的[person, company]列表。实现见 src/core/schema-pack/expert-types.ts 的expertTypesFromPack——它按 manifest 声明顺序过滤expert_routing true的类型配套的expertTypesFromPackOrThrow在活跃 Pack 无任何专家类型时抛清晰错误而不是静默返回零结果。v0.38 之前的whoknows.ts硬编码DEFAULT_TYPES [person, company]codex finding #3 在三处源码中定位到该字面量。注意版本前提pack-aware 查询路径布线在v0.40.6.0加入v0.40.6 之前的脑会静默忽略自定义专家路由类型。Phase 7 — Commit持久化变更若 Pack 位于源码管理中提交cd ~/.gbrain/schema-packs/mine git add pack.json git commit -m schema: add researcher paper types authored link git push若大脑守护进程正在运行gbrain serve --http其他进程在 1 秒内即可感知变更——loadActivePack内置 stat-mtime TTL 门控v0.40.6.0 关闭了跨进程失效缺口。操作者从终端gbrain schema add-typeautopilot 守护进程无需重启即采纳新类型。输出契约Outputs Contract四类输出落点变更后的 Pack 文件~/.gbrain/schema-packs/name/pack.{json,yaml}审计行~/.gbrain/audit/schema-mutations-YYYY-Www.jsonl每次变更一条pages.type回填sync --apply后匹配行被更新查询路径whoknows、find_experts现在经由新专家类型路由输入 / 输出 / 副作用 / 幂等性契约输入命名了类型/前缀/链接动词/标志变更的自然语言请求或gbrain schema review-orphans显示需要新类型的未类型化页面的结果。输出变更后的 Pack 文件 审计行 若执行了sync --apply回填的pages.type。副作用使进程内 Pack 缓存 该 source 的查询缓存失效其他进程在 1 秒内stat-mtime TTL感知变更。幂等性每个原语都是幂等的。add-alias/add-prefix重复执行是 no-opsync --apply第二次运行找不到可更新行。信任模型CLI 本地信任无 scope 检查MCP OAuthadminscope写操作审计日志每条变更记录actor: mcp:clientId8。原子性每次变更都在withMutation原子写.tmp fsync rename 每 PackO_CREAT|O_EXCL锁内完成写入中途崩溃原文件不受影响。结构化输出格式Agent 可消费的 JSON单次变更结果{schema_version: 1, pack: mine, path: ~/.gbrain/schema-packs/mine/pack.json, format: json, prev_sha8: a1b2c3d4, new_sha8: e5f6g7h8}批量变更结果schema_apply_mutationsMCP op{schema_version: 1, pack: mine, batch_id: batch-1716491400-abc123, mutations_applied: 3, results: [{...}, {...}, {...}]}统计 JSON按 source 聚合 dead-prefix 提示{schema_version: 1, pack_identity: mine1.0.0abc12345, aggregate: {total_pages: 4823, typed_pages: 4710, untyped_pages: 113, coverage: 0.9766, by_type: [{type: person, count: 2104}, ...]}, per_source: [...], dead_prefixes: [{type: researcher, prefix: people/researchers/}]}Sync dry-run JSON{schema_version: 1, apply: false, pack_identity: mine1.0.0abc12345, per_prefix: [{type: meeting, prefix: meetings/, would_apply: 4000, sample_slugs: [meetings/2026-01-01-foo, ...], dead_prefix: false, applied: 0}], total_would_apply: 4000, total_applied: 0}人类可读输出Agent 最终总结每个变更一行Pack: name (format)Sha8: prev → new统计总页数、类型化百分比、未类型化计数、按类型分解、dead-prefix 列表sync 的每个前缀would_apply/applied计数 dry-run 模式下的示例 slug。失败时的错误信封遵循标准StructuredAgentError形状{error, code, message, details?}。反模式清单容易踩的六个坑不要直接变更gbrain-base或gbrain-recommended。必须先 forkgbrain schema fork gbrain-base mine。这两个是捆绑包直接编辑会在升级时丢失变更原语会以PACK_READONLY拒绝。不要为一次性 triage 导入的目录加类型。Pack 类型是永久决策一次性导入不是。参考 skills/conventions/schema-evolution.md 的20 页不固化启发式。不要给没有path_prefixes的类型加--expert。expert_routing_without_prefixlint 规则正是为此设计——没有前缀的专家路由类型永远匹配不到 put_page 推断whoknows会静默永不浮现它。不要未经验证就提升schema suggest候选。suggester 是启发式的可能提议与现有类型重叠的类型add-type前先跑lint --with-db捕获前缀冲突。不要跳过sync --apply前的 dry-run。先sync看would_apply计数 示例 slug。一个匹配 5 万页的 Pack 前缀虽然可恢复但很慢先验证的成本很低。不要不检查引用就移除类型。若其他类型的aliases/enrichable_types/link_types/frontmatter_links引用了目标类型remove-type以STILL_REFERENCED拒绝。先解除引用不要加--force。失败模式速查表错误码含义处置PACK_READONLY试图变更gbrain-base/gbrain-recommended先 forkPACK_NOT_FOUND指定的 Pack 不存在用gbrain schema list核对名称PACK_CORRUPTPack 文件解析失败检查 manifest 是否损坏第 3 步 parse 失败TYPE_EXISTS/TYPE_NOT_FOUND类型已存在 / 不存在用explain/stats核对INVALID_RESULT变更会产生悬空引用或前缀冲突读错误消息其中 lint 规则名即问题所在写前 lint 门禁已拦截STILL_REFERENCED移除的类型仍被其他类型的aliases/enrichable_types/link_types/frontmatter_links引用错误会列出每个引用先解除INVALID_PRIMITIVEprimitive 不在PACK_PRIMITIVES集合内核对entity/annotation/temporal等合法值IO_ERROR原子写失败如 ENOSPC检查磁盘空间原文件未受影响LOCK_BUSY另一进程正在变更中等 30 秒重试确认持锁者卡死时用--force偷陈旧锁而非跳过锁permission_denied仅 MCPOAuth 客户端无adminscopegbrain auth register-client --scopes admin重新注册从技能文档到实战配套资源5 分钟上手教程docs/schema-author-tutorial.md —— fork 捆绑包、加 researcher 类型、导入占位页、sync --apply回填、gbrain whoknows证明端到端布线全程无需 API key且提供完整的 undo 路径每个原语都有逆操作gbrain schema downgrade --to pack可恢复此前活跃 Pack。为什么要做7 个杀手级用例docs/what-schemas-unlock.md —— 4000 页隐形会议变成可查询、创始人运营脑、研究脑、法务脑、团队脑、Agent 联合策展以及类型在查询期起作用的结构性论证。何时加类型 vs 别名 vs 前缀skills/conventions/schema-evolution.md 的决策树。Agent 调度入口本技能文件本体 plugin/skills/schema-author/SKILL.mdfrontmatter 声明了全部 27 个 CLI 工具与 9 个 MCP 工具、triggers 与brain_first: exempt。架构落点CLI 分发表 src/commands/schema.ts变更骨架 src/core/schema-pack/mutate.ts专家路由 src/core/schema-pack/expert-types.ts回填核心 src/core/schema-pack/sync.ts。一句话总结schema-author 让 Agent 从给你归档升级为替你塑造大脑的类型学——通过原子锁、审计日志、MCP 批量 op 与查询路径的 pack-aware 布线以数据库级别的结构完整性保证安全地、可追溯地、幂等地演进 Schema Pack。这正是 gbrain 区别于堆了一堆标签的笔记应用的核心所在。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考