gbrain Brain-First 技能合规检查实战以 compliant-phase 为例解析 Phase 1 头脑优先查找协议【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain导读本文围绕 gbrain 仓库中 test/fixtures/brain-first-skills/compliant-phase/SKILL.md 这一测试语料系统讲解 gbrain 的Brain-First头脑优先技能合规机制为什么所有涉及外部数据查找的技能必须先查大脑知识库如何在 SKILL.md 中以显式 Phase 1: Brain-First Lookup 标题声明合规以及 doctor 检查、审计快照与--fix自动修复如何贯穿 CI。读完本文你将掌握编写符合 gbrain 合规检查的 Skill 文件的全部规则与源码级判定原理。一、背景为什么 gbrain 强制要求 先查大脑gbrain 的核心设计是让 Agent 拥有一个可持续累积的个人知识图谱brain。如果每个技能在收到实体、人物、公司、事实类查询时都直接调用web_search、perplexity、exa等外部 API就会产生两类问题重复付费外部 API 成本高与知识孤岛大脑里已有的结论被忽略。仓库中 skills/conventions/brain-first.md 是这条约定的权威定义开头即声明Read this before doing ANY entity/person/company/fact lookup.在执行任何实体/人物/公司/事实查找前必读。其核心规则是强制查找链已知确切 token / 名称 / 结构化字段 →search廉价混合检索无扩展概念 / 全景 / 同义改写类问题 →query多查询扩展拿到 slug 后 →get_page读取完整编译事实仅当步骤 1–2 无有效结果时才允许调用外部 API该文件的源码注释src/core/skill-brain-first.ts记录了一个真实事故作为动机2026-05-19 的 tweet-shield 事件中跨模态评估发现没有任何模型知道某条推文的关键背景而大脑中其实早已存有相关记录——先查大脑再查外部的合规检查本可以避免这次误判。这正是skill_brain_first检查存在的意义在代码层面拦截那些声明了外部查找却未声明或未实现头脑优先的技能作者。二、测试语料全景brain-first-skills 目录的 9 个 SKILL.md合规判定逻辑的完整行为边界由 test/fixtures/brain-first-skills/ 下的 9 个 SKILL.md 语料固化每个文件对应一个判定结果reasonFixture 目录SKILL.md 声明形态判定 reasoncompliant-phase/显式## Phase 1: Brain-First Lookup标题compliant_phasecompliant-callout/顶部 **Convention:**规范 calloutcompliant_calloutcompliant-position/第一个 brain 引用先于外部引用compliant_positionexempt-frontmatter/frontmatter 声明brain_first: exemptexempt_explicitno-external/正文无任何外部查找模式exempt_no_externalmissing-brain-first/直接外部查找、无任何合规信号missing_brain_firstmulti-pattern/同时使用 exa / perplexity / crustdatamissing_brain_firstwarntypo-frontmatter/brain-first: exemptkebab-case 拼写错误missing_brain_first typo 提示negation-prose/否定式表述但 brain 引用在前compliant_position本文的主角compliant-phase属于第一种合规路径——通过显式的阶段标题声明头脑优先。三、compliant-phase 解析Phase 1 标题就是合规证据compliant-phase/SKILL.md全文如下frontmatter 正文--- name: compliant-phase description: External-lookup skill with explicit Phase 1 brain heading triggers: - enrich entity mutating: true --- # compliant-phase A skill that enriches entities via web_search but starts with an explicit Phase 1 brain-first lookup section. ## Phase 1: Brain-First Lookup Before reaching for external sources, check what the brain already knows. ## Phase 2: External Enrichment If the brain answer is thin, run web_search for missing context, then cross-reference with exa.api for citations.这是一个外部查找型技能会调用web_search和exa因此必然触发外部模式检测但它在正文最前面显式声明了## Phase 1: Brain-First Lookup向分析器表明我先查大脑、外部只是补充从而通过合规判定。注意 frontmatter 中mutating: true表示该技能会写数据。这与compliant-callout语料形成了完整的对照实验两个文件都调用外部 API只是合规证据形态不同一个是 callout一个是 Phase 标题。为什么是 Phase 1 或 Step 0源码中判定标题的正则src/core/skill-brain-first.ts为export const PHASE_HEADING_RE /^##\s*(?:Phase\s*1|Step\s*0)\b[^\n]*brain/im;它要求满足三个条件必须是 H2 及以上标题^### Phase 1: Brain Lookup这类 H1 不匹配因为 H1 通常是技能名本身不算执行步骤必须是Phase 1或Step 0## Phase 2: Synthesis不匹配——外部查找必须排在第 1 阶段/第 0 步这是时间顺序的强约束标题中必须包含brain字样[^\n]*brain忽略大小写## Phase 1: Research这种含糊标题不匹配。测试套件在 test/skill-brain-first.test.ts 中逐一验证了这四种形态## Phase 1: Brain-First Lookup✅、### Step 0: Brain Context✅、# Phase 1H1❌、## Phase 2❌。四、合规判定的完整逻辑豁免优先三级阶梯兜底判定入口是纯函数analyzeSkillBrainFirst(content, skillName, frontmatter)src/core/skill-brain-first.ts。它的执行顺序是豁免优先从上到下第一层显式声明豁免exempt_explicitfrontmatter 中出现规范形式brain_first: exempt时直接判定 OK。适用于纯基础设施类技能cron 调度、容器管理、浏览器驱动、ask-user 提示器等它们的工作根本不涉及知识查询。第二层正文无外部模式exempt_no_external分析器先把 frontmatter 剥离stripFrontmatter再在正文中扫描外部查找模式。一个关键细节源码 F6 说明src/core/skill-brain-first.tsfrontmatter 里的tools: [web_search]声明不会触发误报——声明是元数据而非执行所以位置比较一律基于剥离 frontmatter 后的正文。外部模式共 8 种EXTERNAL_LOOKUP_PATTERNS全部词边界锚定、忽略大小写模式名正则匹配示例web_search\bweb_search\bweb_search不会误匹配web_search_historyweb_fetch\bweb_fetch\bweb_fetchexa\bexa[\s._-]exa.search、exa_lookup不会误匹配exam、exaltperplexity\bperplexity\bPerplexity、perplexityhappenstance\bhappenstance\bhappenstancecrustdata\bcrustdata\bcrustdatacaptain_api\bcaptain[\s._-]?api\bcaptain api、captain_api、captain-api、captainapi四种形态firecrawl\bfirecrawl\bfirecrawl第三层合规三级阶梯任一命中即 OKa. 规范 callout正文存在 **Convention:**块引用且包含brain-first子串CONVENTION_CALLOUT_RE /^\s*\*\*Convention:\*\*[^\n]*brain-first/im。路径写法不限纯文本路径、markdown 链接均可这是 F7 修复的兼容性设计src/core/skill-brain-first.ts。b. 显式 Phase 1 / Step 0 标题即本文主角compliant-phase走的路径见第三节。c. 位置优先findFirstBrainRefOffset(body) findFirstExternalRefOffset(body)即正文中第一个 brain 引用gbrain search、gbrain query、search the brain等 11 种模式见 BRAIN_REFERENCE_PATTERNS严格出现在第一个外部引用之前。默认兜底missing_brain_firstwarn外部模式存在、三层阶梯全未命中则返回warn。missing-brain-first语料即此形态——Call web_search to find information. Hit perplexity for synthesis. No brain consultation at all.测试断言它同时匹配到web_search与perplexity两个模式test/skill-brain-first.test.ts。拼写错误的 frontmattertypo 提示而非静默放行typo-frontmatter语料展示了近乎豁免但未落地的场景作者写了brain-first: exemptkebab-case。分析器拒绝猜测返回 warn 并附带 paste-ready 修复提示Found brain-first: exempt — did you mean brain_first?。skills/conventions/brain-first.md 列出了全部 5 种近失形态及修复提示kebab-case / CamelCase 需改 snake_case、带引号需去引号、大写值需转小写、required等未知值不被支持。设计原则是静默的拼写错误是最坏的结果——我声明了豁免它却还报警所以解析器宁可响亮提示也不猜测。五、doctor 集成skill_brain_first 检查与审计快照合规判定不是孤立脚本而是 gbraindoctor命令的正式检查项。在 src/commands/doctor/skill-checks.ts 中skillBrainFirstCheck(skillsDir)会通过loadOrDeriveManifest加载技能清单逐个 SKILL.md 调用analyzeSkillBrainFirst收集warn违规者与 typo 提示技能执行快照 diff 审计A2 契约将本次违规者集合与上次快照skill-brain-first-snapshot.json比对仅对新增检测 / 已解决的状态迁移追加审计事件detected/resolved到skill-brain-first-YYYY-Www.jsonlISO 周格式文件首次运行则引导写入每条当前违规者的detected事件违规者为空时返回ok如N skill(s) compliant or exempt否则按技能名排序输出 warn 消息。审计相关实现位于 src/core/audit-skill-brain-first.ts。零迁移运行的零写入契约由 e2e 测试严格验证第二次 doctor 运行若违规集合无变化审计文件行数必须保持不变test/e2e/skill-brain-first.test.ts。六、gbrain doctor --fix自动插入规范 callout对违规技能doctor --fix会通过 dry-fix 机制自动插入规范 callout将warn翻转回ok。自动修复有严格的安全门test/e2e/skill-brain-first.test.ts必须处于 git 仓库内且文件已跟踪否则拒绝写入防止破坏唯一的文件副本、无法回滚dry-run 模式autoFixDryViolations(..., { dryRun: true })只报告拟插入内容而不落盘插入位置必须满足frontmatter 闭合之后 首个 H1 之后测试通过索引比较断言test/e2e/skill-brain-first.test.ts二次运行幂等已插入过的技能跳过并报already_delegated插入后重新运行 doctor违规者归零typo-frontmatter也会被一并修复因为它的 typo 豁免未生效、同样被判定为违规。七、CI 门禁check-skill-brain-first.sh仓库自身的技能目录也受此规则约束。scripts/check-skill-brain-first.sh 是bun run verify链路上的 CI 守卫它运行GBRAIN_SKILLS_DIR$ROOT/skills bun run src/cli.ts doctor --fast --json并对 JSON 输出做显式解析断言skill_brain_first检查状态不是warn。脚本注释特别强调--fast参数是必需的不带它时 doctor 会调用connectEngine()在无~/.gbrain/config.json的 CI 环境未初始化 brain会以状态码 1 退出、产生零 stdout 导致解析失败--fast走纯文件系统检查resolver_health、skill_conformance、skill_brain_first后者本就是文件系统级检查因此这是正确用法而非绕过scripts/check-skill-brain-first.sh。触发时脚本给出两条修复路径对确实不需要头脑优先的技能加brain_first: exempt否则在技能正文顶部添加规范 callout。八、如何验证运行测试与复现判定本仓库用 Bun 运行测试。执行下面命令即可复现本文全部判定结论# 单元测试驱动 fixtures 语料断言 9 个 SKILL.md 的判定 reason bun test test/skill-brain-first.test.ts # e2e将语料镜像进临时 git 仓库验证 doctor 检查 --fix 自动修复 审计 bun test test/e2e/skill-brain-first.test.tstest/skill-brain-first.test.ts 的 fixture 语料驱动用例逐条断言compliant-phase必须返回ok且 reason 为compliant_phasemissing-brain-first与multi-pattern必须返回warn且external_patterns_matched分别包含对应的外部模式名multi-pattern 同时命中exa、perplexity、crustdata三个。九、写给技能作者四条落地准则综合 skills/conventions/brain-first.md、fixture 语料与源码判定逻辑编写任何涉及外部查找的 SKILL.md 时只需满足以下任一条件即可通过skill_brain_first检查显式阶段标题本主题核心正文最前方声明## Phase 1: Brain-First Lookup或### Step 0: Brain ContextH2、含brain、编号为 Phase 1 / Step 0规范 callout正文顶部放 **Convention:** see conventions/brain-first.md for the lookup chain...引用路径写法不限位置优先确保正文中第一个 brain 引用如gbrain search严格出现在第一个外部引用之前——negation-prose语料证明即便是否定式表述只要顺序正确同样合规显式豁免frontmatter 中写规范形式brain_first: exempt注意严格 snake_case、小写、无引号且仅在技能确实不依赖大脑知识时使用。无论选择哪种形态都建议遵循 skills/conventions/brain-first.md 中每个 brain 页面引用都应输出可点击链接外部 API 拉取结果务必gbrain capture回收入箱等实践让先查大脑、外部补充、结果回存形成完整闭环——这不仅是为了通过检查更是为了让大脑知识图谱随每次查找持续增值。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考