gbrain Brain-First 技能合规检查实战：以 compliant-phase 为例解析 Phase 1 头脑优先查找协议

gbrain Brain-First 技能合规检查实战：以 compliant-phase 为例解析 Phase 1 头脑优先查找协议

【免费下载链接】gbrainGarry's 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."（在执行任何实体/人物/公司/事实查找前必读）。其核心规则是强制查找链：

1. 已知确切 token / 名称 / 结构化字段 →search（廉价混合检索，无扩展）
2. 概念 / 全景 / 同义改写类问题 →query（多查询扩展）
3. 拿到 slug 后 →get_page读取完整编译事实
4. 仅当步骤 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 语料固化，每个文件对应一个判定结果（reason）：

本文的主角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 1（H1）❌、## Phase 2❌。

四、合规判定的完整逻辑：豁免优先，三级阶梯兜底

判定入口是纯函数analyzeSkillBrainFirst(content, skillName, frontmatter)（src/core/skill-brain-first.ts）。它的执行顺序是"豁免优先，从上到下"：

第一层：显式声明豁免（exempt_explicit）

frontmatter 中出现规范形式brain_first: exempt时直接判定 OK。适用于纯基础设施类技能（cron 调度、容器管理、浏览器驱动、ask-user 提示器等），它们的工作根本不涉及知识查询。

第二层：正文无外部模式（exempt_no_external）

分析器先把 frontmatter 剥离（stripFrontmatter），再在正文中扫描外部查找模式。一个关键细节（源码 F6 说明，src/core/skill-brain-first.ts）：frontmatter 里的tools: [web_search]声明不会触发误报——声明是元数据而非执行，所以位置比较一律基于剥离 frontmatter 后的正文。

外部模式共 8 种（EXTERNAL_LOOKUP_PATTERNS），全部词边界锚定、忽略大小写：

第三层：合规三级阶梯（任一命中即 OK）

• a. 规范 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_first（warn）

外部模式存在、三层阶梯全未命中，则返回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）。

拼写错误的 frontmatter：typo 提示而非静默放行

typo-frontmatter语料展示了"近乎豁免但未落地"的场景：作者写了brain-first: exempt（kebab-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)会：

1. 通过loadOrDeriveManifest加载技能清单，逐个 SKILL.md 调用analyzeSkillBrainFirst；
2. 收集warn违规者与 typo 提示技能；
3. 执行快照 + diff 审计（A2 契约）：将本次违规者集合与上次快照（skill-brain-first-snapshot.json）比对，仅对"新增检测 / 已解决"的状态迁移追加审计事件（detected/resolved）到skill-brain-first-YYYY-Www.jsonl（ISO 周格式文件）；首次运行则引导写入每条当前违规者的detected事件；
4. 违规者为空时返回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.ts

test/skill-brain-first.test.ts 的 fixture 语料驱动用例逐条断言：compliant-phase必须返回ok且 reason 为compliant_phase；missing-brain-first与multi-pattern必须返回warn且external_patterns_matched分别包含对应的外部模式名（multi-pattern 同时命中exa、perplexity、crustdata三个）。

九、写给技能作者：四条落地准则

综合 skills/conventions/brain-first.md、fixture 语料与源码判定逻辑，编写任何涉及外部查找的 SKILL.md 时，只需满足以下任一条件即可通过skill_brain_first检查：

1. 显式阶段标题（本主题核心）：正文最前方声明## Phase 1: Brain-First Lookup（或### Step 0: Brain Context），H2+、含brain、编号为 Phase 1 / Step 0；
2. 规范 callout：正文顶部放> **Convention:** see conventions/brain-first.md for the lookup chain...，引用路径写法不限；
3. 位置优先：确保正文中第一个 brain 引用（如gbrain search）严格出现在第一个外部引用之前——negation-prose语料证明即便是否定式表述，只要顺序正确同样合规；
4. 显式豁免：frontmatter 中写规范形式brain_first: exempt（注意严格 snake_case、小写、无引号），且仅在技能确实不依赖大脑知识时使用。

无论选择哪种形态，都建议遵循 skills/conventions/brain-first.md 中"每个 brain 页面引用都应输出可点击链接""外部 API 拉取结果务必gbrain capture回收入箱"等实践，让"先查大脑、外部补充、结果回存"形成完整闭环——这不仅是为了通过检查，更是为了让大脑知识图谱随每次查找持续增值。

【免费下载链接】gbrainGarry's Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain