gbrain 紧凑列表格式 RESOLVER.md 解析原理与回归测试剖析：OpenClaw 规模化路由问题的修复锚点

gbrain 紧凑列表格式 RESOLVER.md 解析原理与回归测试剖析OpenClaw 规模化路由问题的修复锚点【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain导读本文围绕 gbrain 仓库中test/fixtures/openclaw-compact-resolver/skills/RESOLVER.md这一测试夹具fixture展开深入讲解 gbrain 技能路由解析器对紧凑列表格式compact list-formatRESOLVER.md的解析规则、kebab 小写技能名校验、散文条目prose bullet防误判机制以及它们如何与checkResolvable核心校验函数和gbrain doctor健康检查协同工作。读完本文你将掌握紧凑列表格式的书写语法、与 Markdown 表格格式的混用规则、触发词索引的构建原理以及 v0.41.7.0 中 238 个 FAIL 错误归零这一回归事件的完整技术背景。一、背景OpenClaw 部署下的规模化路由回归gbrain 是一个Agent Brain代理大脑实现它通过skills/RESOLVER.md作为调度器dispatcher来把入站消息路由到对应的技能skill。skills/RESOLVER.md见 仓库根级解析器明确说明每个技能的 frontmattertriggers:数组是权威的路由信号而RESOLVER.md则是同一路由的人类可读调度映射——一处扫描所有技能及其触发短语的地方。在 v0.41.7.0 之前的版本中OpenClaw 部署出现了一个规模化回归问题任何使用紧凑- **name**: t1 | t2形状而非 Markdown 表格编写解析器的 agent都会在gbrain doctor中被报告为所有技能不可达unreachable。该回归的具体数据是238 个 FAIL 错误 → 修复后 0 错误。这一事件记录在 回归测试文件 的头部注释中并被定位为 OpenClaw 规模化回归的二分锚点bisect anchor。二、夹具结构openclaw-compact-resolver的完整布局本文章的核心对象位于test/fixtures/openclaw-compact-resolver/目录其结构如下test/fixtures/openclaw-compact-resolver/ └── skills/ ├── brain-search/SKILL.md ├── calendar-prep/SKILL.md ├── content-creation/SKILL.md ├── daily-digest/SKILL.md ├── email-triage/SKILL.md ├── executive-assistant/SKILL.md ├── flight-tracker/SKILL.md ├── gift-advisor/SKILL.md ├── investor-update-ingest/SKILL.md ├── meeting-prep/SKILL.md └── RESOLVER.md夹具由两部分组成约 10 个技能目录每个目录内是带有效 frontmattertriggers:的SKILL.md桩文件stub且全部使用虚构的技能名如gift-advisor、flight-tracker避免遮蔽真实打包技能。每个桩文件的 frontmatter 与解析器条目一一对应例如--- name: email-triage triggers: - triage email - sort my inbox - morning email --- # email-triage Stub for fixture testing (v0.40.11.0 compact-resolver regression suite).skills/RESOLVER.md——即本文章的主体文档采用纯紧凑列表格式按##小节组织末尾附有一段专门用于钉住pinD4 正则收紧行为的散文小节详见下文。值得注意的是夹具中的技能桩文件注释标记为 v0.40.11.0 compact-resolver regression suite而 回归测试 的注释标记为 v0.41.7.0二者是同一回归事件的不同阶段标记测试在 v0.41.7.0 正式合入。另有一个姊妹夹具test/fixtures/openclaw-mixed-merge/用于钉住 v0.31.7 引入的 D-CX-14 多解析器合并场景表格格式的skills/RESOLVER.md 父目录紧凑列表格式的../AGENTS.md。三、紧凑列表格式解析语法紧凑列表格式是 OpenClaw 生态原生的解析器形状其完整语法规则定义在核心解析函数 parseResolverEntries 中。与传统的 Markdown 表格格式| trigger | skills/name/SKILL.md |并列二者可以在同一文件中混合使用。3.1 两种行形态解析器同时支持以下两种列表行加粗形态推荐- **skill-name**: trigger1 | trigger2纯文本形态回退- skill-name: trigger1 | trigger2其对应的正则分别为const listBold line.match(/^-\s\*\*([a-z][a-z0-9-])\*\*\s*:\s*(.)$/); const listPlain listBold ? null : line.match(/^-\s([a-z][a-z0-9-])\s*:\s*(.)$/); const listMatch listBold ?? listPlain;3.2 技能名必须是 kebab-lowercaseD4 收紧两条正则中的技能名部分均限定为[a-z][a-z0-9-]即首字符必须是小写字母a-z后续可以是小写字母、数字或连字符-大写字母如Note、TODO一律不匹配。这一设计是 D4 回归修复的核心。真实世界的AGENTS.md文件中充斥着类似- **Note**: ...、- **Convention**: ...这样的散文项目符号如果解析器不加以区分它们会被误解析为技能行进而产生幽灵触发词orphan trigger。夹具中的## Notes小节专门钉住了这一行为详见第四节。3.3 多个触发词扇出为多条条目一行内通过|分隔的多个触发词会被扇出fan out为多条解析条目每条共享同一个skillPath。例如夹具中的- **gift-advisor**: gift idea | what should I bring | birthday gift | housewarming会被解析为 4 条{ trigger: gift idea | what should I bring | birthday gift | housewarming, skillPath: skills/gift-advisor/SKILL.md }条目。checkResolvable下游会按skillPath去重因此技能可达性计数中每个技能只计一次。3.4 路径后缀被剥离但不被采用D3列表行允许携带一个可选的显式路径后缀解析器会将其从触发词字符串中剥离但不会作为实际路径采用const cleaned triggersRaw.replace(/\s*(?:→|-)\s*skills\/[^]\s*$/, );Unicode 箭头→和 ASCII 箭头-均可接受。skillPath始终按约定推导为skills/name/SKILL.md。源码注释明确指出下游消费者如routing-eval.ts的skillSlugFromPath以及本文件的可达性查找都假设该约定路径对于非约定路径必须改用表格格式。3.5 其他细节空触发词和被字面量...占位符会被过滤##标题行会被捕获为当前小节名section并挂到该小节内的每条条目上供--fix建议和报告定位使用支持#注释行——从源码看解析器会跳过所有不匹配的行既非标题、也非表格行、也非列表行因此散文、空行和说明文字天然被忽略。四、Notes 小节散文防误判的回归哨兵夹具RESOLVER.md末尾的## Notes小节是整个夹具的反向测试用例原文如下## Notes The bullets below are prose, not skill rows. The v0.41.7.0 parser rejects them via the kebab-lowercase name regex. If you see entries materialize for any of these, the D4 regex tighten regressed. - **Note**: this is a prose bullet (capitalized name, must be skipped) - **Convention**: see [parent docs] (capitalized name, must be skipped) - **TODO**: nothing here is a real skill row (capitalized, skipped) - **Important**: this is just a callout (capitalized, skipped)这 4 个散文条目Note、Convention、TODO、Important都使用大写开头的名字故意设计为不匹配kebab-lowercase 正则。它们的存在是为了保证如果未来某次改动放宽了 D4 正则收紧这些条目会立刻以orphan_trigger警告的形式在回归测试中暴露出来防止技能行被误解析的问题重新出现。在真实世界的skills/RESOLVER.md中也有对应的结构## Notes之外的常规正文如Memory defaults、Disambiguation rules都是纯散文或表格解析器同样依靠正则自然跳过它们。五、checkResolvable 的完整校验流水线checkResolvable 是解析器的核心校验函数它有三个调用点bun test——单元测试直接导入并断言checkResolvable()的返回值gbrain doctor——运行时健康检查附带可操作的 agent 指引skill-creator技能——创建技能后的强制性校验门post-creation validation gate。其返回的ResolvableReport结构包含ok、errors、warnings、issues和summary含total_skills、reachable、unreachable、overlaps、gaps五项统计。ok仅在errors为空时为真警告默认不翻转ok但--strict模式会将其提升为失败条件。5.1 输入加载frontmatter 触发词 解析器行条目的并集自 v0.41.11 起触发词来源采用 UNION 语义加载自loadSkillTriggerIndex(skillsDir)见 skill-trigger-index.ts每个技能SKILL.md的 frontmattertriggers:权威——每个技能自带触发词新技能即使没有RESOLVER.md行也能保持可达RESOLVER.md/AGENTS.md中的策划行条目——来自skillsDir及其父目录保留 D-CX-14 的 OpenClaw 工作区根布局。frontmatter 是事实来源关闭 #1451 漂移问题RESOLVER.md行仍然做加法贡献使人类可读的调度映射保持承载价值。解析器文件名集合定义于 resolver-filenames.ts第 19 行RESOLVER_FILENAMES [RESOLVER.md, AGENTS.md]。5.2 六类检查流水线依次执行以下检查序号检查严重级别触发条件1可达性unreachableerror低置信度场景降级为 warningmanifest 中的技能在解析器条目中无对应触发词2文件缺失missing_fileerror解析器引用了磁盘上不存在的skills/name/SKILL.md3MECE 重叠mece_overlapwarning同一触发词命中多个技能白名单除外4MECE 缺口mece_gapwarning技能 frontmatter 缺少triggers:数组5DRY 违规dry_violationwarning技能内联了应委托给约定文件的跨切面规则6路由评估routing_*warning结构性路由评估与 routing-eval.jsonl 夹具不一致其中 MECE 重叠的白名单为OVERLAP_WHITELISTingest路由器、signal-detector始终开启、brain-ops始终开启——它们被设计为与许多技能有意重叠。5.3 低置信度外部目录的降级逻辑当满足以下全部条件时unreachable从 error 降级为 warning技能目录通过cwd_walk_up发现、无解析器文件贡献行或仅有一个零行条目的AGENTS.md、不可达数大于可达数、且磁盘上无manifest.json。这避免了其他工具目录中恰好带triggers:的单个技能导致其所有兄弟技能被硬判为 error。高置信度来源显式 flag、env、安装路径始终保持严格。六、回归测试如何验证紧凑格式解析回归测试文件 使用两个夹具驱动多个回归测试。对紧凑夹具而言共有 5 项断言所有技能可达report.summary.unreachable为 0reachable total_skills且total_skills 10——这是头条断言修复前每个技能都是unreachableN零 error 级问题report.errors.length 0且report.ok true——对应 238 FAIL → 0 的结果零 mece_gap 警告夹具桩文件均带有效 frontmatter 触发词gap 检测应保持静默该断言一旦触发即说明某个夹具文件丢失了triggers:数组D4 回归守卫4 个散文条目Note、Convention、TODO、Important不得以orphan_trigger警告形式出现零 missing_file 警告每条列表条目都能解析到磁盘上的真实文件。对混合合并夹具openclaw-mixed-merge另有 3 项断言8 个技能表格格式 5 个 紧凑列表格式 3 个全部可达、零 error、两种格式的技能都在合并结果中贡献条目——专门防止某一种格式的解析器通过dedup-by-skillPath路径吞掉另一种格式的输出。要本地运行这组测试可以在仓库根目录执行bun test test/check-resolvable-openclaw-compact.test.ts该测试使用 Bun 的bun:test运行时见 package.json 与 bunfig.toml 中的测试配置。七、实战为 OpenClaw 工作区编写紧凑格式解析器基于上述解析规则为 OpenClaw 风格的 agent 工作区编写紧凑格式RESOLVER.md时应遵循以下最佳实践7.1 推荐的行模板## Always-on - **brain-search**: search my brain | what do we know about | find references to ## Personal - **gift-advisor**: gift idea | what should I bring | birthday gift | housewarming - **flight-tracker**: track my flight | flight status | when does my flight land ## Email Calendar - **email-triage**: triage email | sort my inbox | morning email要点使用加粗形态- **name**: ...技能名保持小写连字符kebab-lowercase用##小节对技能做语义分组Always-on、Personal、Email Calendar、Workflows 等解析器会把小节名关联到每条条目一个技能最多一行多个触发词用|分隔若需要指向非约定路径改用表格格式| trigger | \skills/ /SKILL.md |。7.2 保持每个技能文件自带 frontmatter triggers由于 frontmattertriggers:是权威信号且RESOLVER.md行是加法贡献双写时务必保持二者一致。仓库级 RESOLVER.md 也强调如果某一行与技能的 frontmatter 冲突frontmatter 胜出且应修复该行。7.3 规避散文误判不要在解析器文件中使用- **Note**:、- **Convention**:等大写开头的散文项目符号来写注释它们会被跳过但语义容易误导如需注释可放在正文段落中或使用不会被正则匹配的行形态。夹具的## Notes小节本身就是反面教材式注释可参考其写法。7.4 使用 gbrain doctor 验证运行gbrain doctor会对解析器做全量校验输出unreachable、missing_file、orphan_trigger、mece_overlap、mece_gap、dry_violation等报告项并在--strict模式下将警告提升为失败。新技能创建后skill-creator技能也会强制调用checkResolvable作为完成门。八、与真实仓库级 RESOLVER.md 的差异对照仓库根级的 skills/RESOLVER.md 是生产环境的调度映射含 100 技能行、GStack 思维技能、身份与访问规则、消歧规则、跨切面约定等它主要使用表格格式同时遵循相同的路由契约frontmattertriggers:是权威路由信号。而本夹具是纯紧凑列表格式的最小化副本二者共同验证了parseResolverEntries对两种格式以及混用场景的兼容性。夹具中的技能名gift-advisor、flight-tracker等均为虚构确保测试不会遮蔽真实打包技能。结语test/fixtures/openclaw-compact-resolver/skills/RESOLVER.md看似只是一个小型测试夹具实则是 gbrain 技能路由体系的关键回归锚点它同时钉住了紧凑列表格式的完整语法kebab-lowercase 名校验、触发词扇出、路径后缀剥离、散文条目防误判D4 收紧、以及 238 FAIL → 0 的规模化回归修复。理解这份夹具就理解了parseResolverEntries的解析边界与checkResolvable的校验语义也掌握了在 OpenClaw 风格工作区中编写、验证和演进紧凑格式解析器的全部要点。相关代码入口解析器实现、校验函数、回归测试、解析器文件名定义。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考