人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载本文以 gbrain 仓库中的测试夹具 test/fixtures/brain-first-skills/typo-frontmatter/SKILL.md 为切入点深入讲解 v0.36.x 引入的skill_brain_firstdoctor 检查当技能作者用 kebab-case 的brain-first: exempt替代规范的 snake_casebrain_first: exempt时解析器如何捕获这一未落地的豁免声明、如何给出可直接粘贴的 typo 修复提示同时仍然将技能标记为不合规。读完本文你将掌握 gbrain 中 brain-first 合规分析器的判定优先级、typo 检测的四类分类、三个消费方doctor / skillify-check / dry-fix的调用链路以及正确的豁免与合规声明写法。夹具Fixture解剖一个想豁免却未生效的典型场景夹具文件位于 test/fixtures/brain-first-skills/typo-frontmatter/SKILL.md全文如下--- name: typo-frontmatter description: Skill with typo in brain_first declaration triggers: - do a thing brain-first: exempt --- # typo-frontmatter The maintainer tried to opt out but used kebab-case brain-first instead of canonical snake_case brain_first. The analyzer should surface a typo hint AND still flag the skill (because the exempt declaration didnt land). ## How Call web_search and perplexity for fresh data.这个夹具同时包含两个关键特征frontmatter 中的豁免声明拼写错误作者意图通过brain-first: exempt声明本技能豁免 brain-first 合规检查但键名使用了 kebab-case连字符分隔而非规范要求的 snake_casebrain_first。在 YAML 解析层面这只是一个普通自定义字段永远不会被 gbrain 的豁免逻辑识别。正文包含外部查找调用## How小节明确写了web_search和perplexity——两者都在外部查找检测模式清单中。这意味着该技能确实执行外部检索需要明确声明其 brain-first 立场。注释中明确描述了预期行为contract「The analyzer should surface a typo hint AND still flag the skill」——既要给出 typo 提示又必须把技能标记为不合规因为豁免声明并未生效。这一行为契约在 test/skill-brain-first.test.ts 中被固化test(typo-frontmatter → warn with typo_hint surfaced, () { const { content, skillName } loadFixture(typo-frontmatter); const fm parseSkillFrontmatter(content); const result analyzeSkillBrainFirst(content, skillName, fm); expect(result.status).toBe(warn); expect(result.typo_hint).toBeDefined(); expect(result.typo_hint).toContain(brain-first); expect(result.typo_hint).toContain(snake_case); });什么是 Brain-First为什么豁免声明需要被严格校验brain-first 是 gbrain 的核心运行原则在执行任何外部 API 查询之前必须先检索自身大脑brain中已有的知识与上下文。其动机记录在分析器源码 src/core/skill-brain-first.ts 中——2026-05-19 的 tweet-shield incident跨模态评测发现Garry 的一条推文被标记为有风险因为没有任何模型知道他构建过该产品而大脑中其实早已存有设计了整个 Finance 产品 UI和150 张 PSD2006 年 4 月–12 月等事实。如果遵循 brain-first 合规在任何外部调用前先检索大脑本可以避免这次误判。因此gbrain 要求每个技能要么显式声明豁免brain_first: exempt要么在正文中呈现合规信号下文详述的合规三阶梯。问题是声明拼写错误等于没有声明。源码注释src/core/skill-frontmatter.ts明确阐述了严格性设计的理由Strictness rationale: silent typos are the worst kind. A developer who writesbrain-first: exemptthinking it works deserves a loud hint pointing at the canonical form, not a silent failure to exempt.静默的拼写错误是最糟的——作者以为自己已经豁免实际却未被豁免若医生检查不提示这种错误会悄无声息地蔓延。frontmatter 解析器typo 检测的四分类体系typo 检测实现在 src/core/skill-frontmatter.ts 的parseBrainFirst函数中src/core/skill-frontmatter.ts#L186-L247。解析器先用宽松正则^(brain[-_]?first)\s*:\s*(.?)\s*$im标志大小写不敏感、键名兼容连字符或下划线扫描所有形似 brain_first 声明的行取第一处匹配然后与规范形态brain_first: exemptsnake_case 键 小写未加引号的值比对将任何偏差归类为四种 typo 类型typo reason触发场景示例noncanonical_key键名分隔符或大小写错误brain-first: exempt、BrainFirst: exemptquoted_value键正确但值被引号包裹brain_first: exemptcapitalized_value键正确但值首字母大写brain_first: Exemptunknown_value键正确但值不在支持集合内brain_first: required、brain_first: true夹具typo-frontmatter属于第一类noncanonical_key。检测到后解析器会写入brain_first_typo字段记录原始 key、原始 value 与原因而brain_first字段保持未定义——这正是豁免未落地的根源。四种 typo 的修复提示文案formatBrainFirstTypoHintsrc/core/skill-frontmatter.ts#L254-L266为每种原因生成可直接粘贴的修复提示noncanonical_keyFound brain-first: exempt — did you mean brain_first: exempt? (snake_case key required)quoted_valueFound brain_first: exempt — drop the quotes: brain_first: exemptcapitalized_valueFound brain_first: Exempt — value must be lowercase: brain_first: exemptunknown_valueFound brain_first: required — v0.36 ships only brain_first: exempt (declarative opt-out)提示中明确包含正确的 snake_case 写法开发者可以直接复制替换。typo 检测对键故意宽松连字符、大小写都抓对规范匹配严格只有唯一形态才生效这是注释中所说的 permissive on the KEY, strict on the canonical match 策略。分析器判定流程豁免优先合规阶梯兜底核心纯函数analyzeSkillBrainFirstsrc/core/skill-brain-first.ts#L226-L325接收 SKILL.md 原始内容、技能名与解析后的 frontmatter按严格顺序执行判定豁免优先先到先得1. exempt_explicit frontmatter.brain_first exempt规范声明→ ok 2. exempt_no_external 正文中未发现任何外部查找模式 → ok 3. compliant_callout 正文含规范 Convention 引用 **Convention:** ... brain-first ...→ ok 4. compliant_phase 正文含 ## Phase 1 / ## Step 0 且提及 brain 的标题 → ok 5. compliant_position 正文中首个 brain 引用出现在首个外部引用之前 → ok 6. missing_brain_first 存在外部模式但无任何合规信号 → warn对typo-frontmatter夹具的执行过程可以逐步推演brain_first字段为 undefinedtypo 未落地brain_first_typo已填充 → 跳过exempt_explicitstripFrontmatter剥离 YAML 围栏后正文包含web_search与perplexity二者命中外部查找模式 → 跳过exempt_no_external正文没有 Convention 引用、没有 Phase 1/Step 0 标题、也没有任何 brain 引用如gbrain search出现在外部引用之前 → 三级合规阶梯全部落空最终返回status: warn、reason: missing_brain_first、external_patterns_matched: [web_search, perplexity]同时typo_hint被透传。外部查找模式的完整清单EXTERNAL_LOOKUP_PATTERNSsrc/core/skill-brain-first.ts#L112-L121定义了触发合规门的 8 个外部检索模式全部单词边界锚定、大小写不敏感web_search、web_fetch、exa要求带分隔符避免误匹配 exam/exalt、perplexity、happenstance、crustdata、captain_api兼容captain api/captain_api/captain-api/captainapi四种写法、firecrawl。external_patterns_matched在合规路径上也会填充便于消费者展示该技能调用了什么。一个关键设计frontmatter 中的tools声明不参与位置比对位置相关的扫描只针对正文body-only。stripFrontmattersrc/core/skill-brain-first.ts#L338-L340会移除前导 YAML 围栏防止tools: [web_search]这类元数据声明被当作首个外部引用从而误报注释中记为 F6 设计决策。这在 test/skill-brain-first.test.ts 中有专门回归测试。typo 提示的三个消费方医生、技能审查门、dry-fixanalyzeSkillBrainFirst是一个无 I/O 的纯函数有三个消费者共享同一套逻辑src/core/skill-brain-first.ts#L12-L16gbrain doctor检查doctor 类别skill_brain_first注册在 src/core/doctor-categories.ts对技能清单逐项执行分析把结果渲染成医生报告。typo 提示经由buildBrainFirstSummaryLinesrc/core/skill-brain-first.ts#L383-L399拼入诊断行格式如typo-frontmatter: external lookup (web_search, perplexity) without brain-first compliance (typo: Found brain-first: exempt — did you mean brain_first: exempt? (snake_case key required))。skillify-check门禁对新生成/变更的 SKILL.md 做单文件检查要求清单第 12 项未通过则阻止技能进入清单。dry-fix自动修复MISSING_RULE_PATTERNSsrc/core/dry-fix.ts调用analyzeSkillBrainFirst判断此处是否应插入 Convention 说明当检测到 warn 时gbrain doctor --fix会尝试自动插入规范的 **Convention:** ... brain-first ...引用块通过 dry-fix 安全门用户始终在环内不做静默迁移。曾硬编码豁免的技能列表过渡提示FORMERLY_HARDCODED_EXEMPTsrc/core/skill-brain-first.ts#L193-L209保留了 PR #1206 中硬编码豁免清单的 40 个技能名分为三类大脑内部技能、外部工具封装、纯基础设施技能。该集合不是豁免规则仅用于医生提示当这些技能在 v0.36.x 之后首次被标记时诊断信息会追加引导文案——要么运行gbrain doctor --fix自动添加规范引用要么在 frontmatter 中显式写brain_first: exempt。其目的注释为 guided opt-in surface, NOT an exemption rule。正确的写法豁免与合规的两种规范形态结合源码与同目录夹具test/fixtures/brain-first-skills/给出可直接套用的规范写法形态一显式豁免适用于真正不需要 brain-first 的基础设施/纯外部工具技能--- name: my-skill description: ... brain_first: exempt ---注意三点键必须是brain_firstsnake_case值必须是exempt小写、不加引号除exempt外的任何值required、true等都会被归类为unknown_valuetypo。形态二合规信号适用于调用外部工具但承诺先查大脑的技能三选一即可通过规范 Convention 引用compliant_callout正文中以行首 blockquote 形式书写 **Convention:** ... brain-first ...路径语法不限纯文本、反引号、Markdown 链接均可正则CONVENTION_CALLOUT_RE只锚定字面量**Convention:**brain-first子串src/core/skill-brain-first.ts#L153。参考夹具 test/fixtures/brain-first-skills/compliant-callout/SKILL.md。显式阶段标题compliant_phaseH2 及以上标题形如## Phase 1: Brain-First Lookup或### Step 0: Brain Context正则PHASE_HEADING_RE要求Phase 1/Step 0与brain同现src/core/skill-brain-first.ts#L160。参考 test/fixtures/brain-first-skills/compliant-phase/SKILL.md。位置合规compliant_position正文中首个 brain 引用如gbrain search、search the brain模式见BRAIN_REFERENCE_PATTERNSsrc/core/skill-brain-first.ts#L127-L139出现在首个外部引用之前。参考 test/fixtures/brain-first-skills/compliant-position/SKILL.md。行为验证与回归保障分析器的行为由三层测试保障均可直接阅读与运行夹具语料驱动test/skill-brain-first.test.ts的analyzeSkillBrainFirst (fixture corpus)用例组覆盖了同目录下 9 个夹具compliant-callout、compliant-phase、compliant-position、exempt-frontmatter、missing-brain-first、multi-pattern、negation-prose、no-external、typo-frontmatter每个断言都钉死了status与reason的组合。PR #1206 回归吸收直接内联的 4 个历史用例确保旧行为不被破坏。审计快照audit-skill-brain-first模块src/core/audit-skill-brain-first.ts以 ISO 周为单位生成快照与 JSONL 审计事件detected/resolved/fixed无状态变迁的运行零写入由 A2 契约测试锁定。小结typo-frontmatter这个夹具浓缩了 brain-first 合规体系的设计哲学对拼写错误要大声、具体、可修复对合规状态要严格、透明、可追溯。一次brain-first: exempt的拼写失误会被 src/core/skill-frontmatter.ts 归类为noncanonical_keytypo被 src/core/skill-brain-first.ts 判定为missing_brain_firstwarn并在 doctor 报告、skillify-check 门禁与 dry-fix 修复建议中同步呈现——既不会让作者蒙在鼓里也不会让不合规技能悄悄混入。理解这条链路你就能在编写或审查 gbrain 技能时准确预判分析器行为写出一次通过的合规 SKILL.md。赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐GBrain 位置相对合规检测让 SKILL.md 用「脑内优先于外部」的顺序通过 Brain-First 审查GBrain 位置相对合规检测让 SKILL.md 用「脑内优先于外部」的顺序通过 Brain First 审查 导读 GBrain 的 Brain Firs人工智能RAGAgent 记忆MCP 服务知识管理用 brain_first: exempt 声明豁免gbrain Brain-First 合规体系中的纯基础设施 Skill 退出机制用 brain_first: exempt 声明豁免gbrain Brain First 合规体系中的纯基础设施 Skill 退出机制 在 gbrainGa人工智能RAGAgent 记忆MCP 服务知识管理gbrain Brain-First 合规检测剖析从 no-external 豁免语义到 skill_brain_first 三层合规阶梯gbrain Brain First 合规检测剖析从 no external 豁免语义到 skill_brain_first 三层合规阶梯 gbrainGa人工智能RAGAgent 记忆MCP 服务知识管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
