★ FEATURED ARTICLE 人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载本文以 test/fixtures/brain-first-skills/compliant-callout/SKILL.md 为切入点讲解 GBrain 技能Skill如何通过一段规范化的 **Convention:**引用callout声明 Brain-First 合规性从而通过skill_brain_first静态检查。读完本文你将理解 Brain-First Lookup 协议、analyzeSkillBrainFirst分析器的三层合规阶梯与两类豁免路径、brain_first: exempt的严格写法以及如何对照夹具语料自查自己的 SKILL.md。背景为什么技能必须先查大脑GBrain 是 OpenClaw/Hermes 场景下的Agent 大脑以 Markdown 页面为知识图载体。在 docs/guides/brain-first-lookup.md 中项目的核心约定是在任何外部 API 调用之前先检查大脑。外部 API 只用于补缺口而不是从零开始。这个约定的动机非常具体如果某个 Agent 对一个你已经开过 12 次会议的人直接调用 Brave Search得到的是一份 LinkedIn 摘要而不是你的关系历史。反过来先查大脑能得到你们如何认识、讨论过什么、做过什么判断、最近有什么变化这类外部 API 永远给不出的上下文。Brain-First 的核心主张来自 docs/guides/brain-first-lookup.md大脑拥有任何外部 API 都无法提供的上下文关系历史、你自己的评估、会议记录、交叉引用、时间线一份 LinkedIn 抓取给你职位头衔大脑给你的是你们喝过三次咖啡、上次讨论了支付基础设施论点、她对你的 AI Agent 观点感兴趣违反该约定的 Agent 既浪费钱又给出更差的答案。compliant-callout 夹具一个完整的最小合规示例test/fixtures/brain-first-skills/是skill_brain_first分析器的回归夹具语料库共包含 9 个 SKILL.md 样本分别覆盖合规、违规、豁免、拼写错误等场景。我们讨论的 compliant-callout/SKILL.md 是其中通过 Convention callout 声明合规的标准样本全文如下--- name: compliant-callout description: External-lookup skill with canonical Convention callout triggers: - research a person mutating: true --- # compliant-callout A skill that researches people via Perplexity but properly delegates to the brain-first convention. **Convention:** see conventions/brain-first.md for the lookup chain (search → query → get_page → external). ## Phase 1: Research Use Perplexity to find recent news about the person; cross-reference web_search for primary sources.这个夹具刻意制造了一个矛盾它明确调用了Perplexity和web_search两个外部检索工具正文中出现外部模式同时mutating: true表示它可能写入大脑页面。按直觉这很容易被当成违规技能但它的合规点正是正文开头那段引用 **Convention:** see conventions/brain-first.md for the lookup chain (search → query → get_page → external).只要这段 callout 存在分析器就会返回okreason 为compliant_callout并保留已匹配的外部模式列表用于展示如perplexity、web_search。分析器如何判定三层合规阶梯与豁免优先级skill_brain_first检查的核心实现是 src/core/skill-brain-first.ts 中的纯函数analyzeSkillBrainFirst(content, skillName, frontmatter)。根据文件头注释该模块有三个消费方doctor命令中的skill_brain_first检查src/commands/doctor/skill-checks.tsskillify-check对单个 SKILL.md 的门禁检查src/commands/skillify-check.tsdry-fix.ts的MISSING_RULE_PATTERNS是否应插入 Convention callout的判定门。判定逻辑按**豁免优先级先命中先返回**组织共两层豁免加三条合规阶梯优先级路径判定依据结果 reason1显式豁免frontmatter 中brain_first: exemptexempt_explicit2无外部模式正文中不含任何外部检索模式exempt_no_external3合规阶梯 a规范的 **Convention:** ...brain-first...引用compliant_callout4合规阶梯 b## Phase 1或## Step 0且标题含 braincompliant_phase5合规阶梯 c正文中第一个 brain 引用出现在第一个外部引用之前compliant_position6违规有外部模式且无任何合规信号missing_brain_first关键实现细节正文body扫描而非全文扫描F6。stripFrontmatter会先把 YAML fence 剥掉再执行位置相关扫描避免tools: [web_search]这类 frontmatter 中的元数据声明被误判为第一个外部引用。这一点在 test/skill-brain-first.test.ts 有专门的回归用例。外部模式清单8 项EXTERNAL_LOOKUP_PATTERNS 用词边界锚定的正则匹配web_search、web_fetch、exa、perplexity、happenstance、crustdata、captain_api、firecrawl。exa需要分隔符避免误配exam、exaltcaptain_api兼容四种书写形态captain api/captain_api/captain-api/captainapi且全部大小写不敏感。规范 callout 正则F7CONVENTION_CALLOUT_RE /^\s*\*\*Convention:\*\*[^\n]*brain-first/im它锚定行首的 blockquote同时要求包含字面量**Convention:**和brain-first子串对路径语法不敏感——纯文本路径、反引号路径、Markdown 链接形式都能匹配src/core/skill-brain-first.ts。单元测试覆盖了三种形式见 test/skill-brain-first.test.ts。无结构性豁免CMT2代码注释明确指出不存在toolswrites_pages类结构性豁免。像idea-ingest、meeting-ingestion、data-research这种既写页面又调外部 API的技能恰是 Brain-First 要约束的对象它们会被标记迫使作者显式声明立场而不是躲在结构性规则后面。为什么选 callout 而非位置判定夹具语料中有三个合规样本对应三条阶梯compliant-calloutcallout、compliant-phasePhase 1 标题、compliant-positionbrain 引用先于外部引用。compliant-callout的价值在于零歧义无论技能正文怎么组织只要开头有一句规范 callout合规意图就一目了然路径无关callout 指向 skills/conventions/brain-first.md 即可具体用相对路径还是链接形式不影响判定可自动修复gbrain doctor --fix的 dry-fix 门就是拿CONVENTION_CALLOUT_RE当是否已合规的判定未合规时自动插入这句 callout跳过显式豁免的技能。值得注意的是现有技能brain-ops、signal-detector、idea-ingest、enrich、perplexity-research、academic-verify都通过 callout 路径直接判为 OK——即使它们本身就是大脑如brain-ops也不需要额外的结构性豁免规则见 skills/conventions/brain-first.md 与 src/core/skill-brain-first.ts 的说明。对照夹具自查你的技能属于哪一类test/fixtures/brain-first-skills/的 9 个夹具覆盖了全部分类是自查的绝佳参照系夹具特征判定结果compliant-callout外部模式 规范 calloutok (compliant_callout)compliant-phase外部模式 ## Phase 1: Brain-First Lookupok (compliant_phase)compliant-position外部模式 brain 引用先出现ok (compliant_position)exempt-frontmatterbrain_first: exemptok (exempt_explicit)no-external无任何外部模式ok (exempt_no_external)negation-prosebrain 引用先于外部引用含否定措辞ok (compliant_position)missing-brain-first直接外部检索、无 brain 信号warn (missing_brain_first)multi-pattern同时命中 exa / perplexity / crustdatawarn (missing_brain_first)typo-frontmatterbrain-first: exemptkebab-casewarn typo 提示其中 missing-brain-first/SKILL.md 展示了最典型的违规形态——正文直接写Call web_search to find information. Hit perplexity for synthesis. No brain consultation at all.而 typo-frontmatter/SKILL.md 展示了想豁免却写错键名的情况brain-first: exemptkebab-case不会落地分析器既给出可粘贴修复提示又照常标记违规——正如约定文档所说静默的拼写错误是最坏的结果。这些断言全部被 test/skill-brain-first.test.ts 的夹具驱动用例锁定IRON-RULE 回归集保证行为不被后续修改破坏。合规实操两种零摩擦写法根据 skills/conventions/brain-first.md 的声明式豁免小节只要满足以下任一条件技能即合规写法一顶部加规范 Convention callout **Convention:** see conventions/brain-first.md for the lookup chain (search → query → get_page → external).这是compliant-callout采用的方式也是gbrain doctor --fix自动修复的落地方案。写法二frontmatter 显式豁免纯基建类技能--- name: my-infra-skill brain_first: exempt ---用于 cron 调度、容器管理、ask-user 提示、浏览器驱动等整个任务就是不咨询大脑的技能。注意严格规范形式——分析器对拼写错误非常敏感skills/conventions/brain-first.md 给出了完整对照表写法结果brain_first: exempt✅ 匹配brain-first: exempt⚠ 提示需 snake_caseBrainFirst: exempt⚠ 提示需 snake_casebrain_first: exempt⚠ 提示去掉引号brain_first: Exempt⚠ 提示值必须小写brain_first: required⚠ v0.36 仅支持exempt接近正确但未到位的写法会打印一行可直接粘贴的修复提示formatBrainFirstTypoHint见 src/core/skill-frontmatter.ts且技能保持标记状态直到规范形式落地。另外当你的技能声明豁免后doctor --fix的自动插入 callout 流程会跳过它src/commands/doctor/skill-checks.ts 附近的处理逻辑不会产生自相矛盾的标记。三层查找链callout 背后引用的完整协议compliant-callout 的 callout 文本点出了完整查找链search → query → get_page → external。结合 docs/guides/brain-first-lookup.md 的伪代码实现完整协议如下lookup(name_or_topic): // STEP 1: Keyword search (fast, works day one, no embeddings needed) results gbrain search {name_or_topic} if results.length 0: page gbrain get {results[0].slug} return page // done, brain had it // STEP 2: Hybrid search (needs embeddings, finds semantic matches) results gbrain query what do we know about {name_or_topic} if results.length 0: page gbrain get {results[0].slug} return page // STEP 3: Direct slug (if you know or can guess the slug) page gbrain get people/{slugify(name_or_topic)} if page: return page // STEP 4: External API (FALLBACK ONLY) // Only reach here if brain has nothing return external_search(name_or_topic)约定文档 skills/conventions/brain-first.md 进一步按问题形态路由确切的已知 token / 名字 / 结构化字段 →search廉价混合检索概念 / 全景 / 同义改写类问题所有做 X 的 Y→query优先多查询扩展能找回search漏掉的措辞拿到 slug 后 →get_page读取完整编译事实步骤 1-2 无有效结果 → 才允许外部 API。另有几条硬性规则值得注意search计数非零不代表完整枚举类问题用list_pages分页Score 0.5 use it大脑已作答就别去外部写页后触发同步OpenClaw 下gbrain__sync_brainCLI 下gbrain sync --no-pull每次外部 API 拉取都要用gbrain capture入收件箱沉淀否则付过费的查找还会再付一次费实体查找禁用memory_search那是会话笔记检索不是知识图检索。写给技能作者的最后清单先问我的技能会调用外部检索工具web_search、perplexity、exa、crustdata、firecrawl、happenstance、captain api、web_fetch 之一吗不会 → 自动豁免无需任何声明。会在正文靠前位置加规范 callout **Convention:** see conventions/brain-first.md for the lookup chain (search → query → get_page → external).或者显式## Phase 1: Brain-First Lookup标题或者保证 brain 引用出现在外部引用之前。纯基建在 frontmatter 写brain_first: exempt务必 snake_case、小写、不带引号。验证跑gbrain doctor查看skill_brain_first检查或对新技能运行skillify-check如果被标记且来自 PR #1206 旧豁免清单doctor 会引导你gbrain doctor --fix自动补 callout或手动声明豁免src/commands/doctor/skill-checks.ts。通过compliant-callout这个最小样本可以看到GBrain 把先查大脑从口头约定变成了可静态校验的工程约束一条 callout、一个 frontmatter 字段、一段位置扫描就足以让每个技能包括那些必须调用外部 API 的技能在架构层面声明自己的数据获取顺序。赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐gbrain Brain-First Lookup 协议先查大脑、再问外部 API 的 Agent 检索规范gbrain Brain First Lookup 协议先查大脑、再问外部 API 的 Agent 检索规范 本文讲解 gbrain 的 Brain Firs人工智能RAGAgent 记忆MCP 服务知识管理gbrain Brain-First 合规检测剖析从 no-external 豁免语义到 skill_brain_first 三层合规阶梯gbrain Brain First 合规检测剖析从 no external 豁免语义到 skill_brain_first 三层合规阶梯 gbrainGa人工智能RAGAgent 记忆MCP 服务知识管理为 Codex 接入 GBrain 记忆插件、远程 MCP 与 brain-first 协议实战指南为 Codex 接入 GBrain 记忆插件、远程 MCP 与 brain first 协议实战指南 GBrain 提供了一套为已有编码 Agent 增加显人工智能RAGAgent 记忆MCP 服务知识管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
