人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载本篇技术指南以 gbrain 仓库中 test/fixtures/openclaw-reference-minimal/skills/query/SKILL.md 这一 OpenClaw 参考工作区 fixture 技能为切入点剖析 gbrain 在不依赖manifest.json的 OpenClaw 风格工作区AGENTS.md位于仓库根、技能平铺在skills/下中如何完成技能目录自动探测、清单自动推导、触发器路由校验与归档审计。读者读完可以掌握gbrain check-resolvable的完整检查链、$OPENCLAW_WORKSPACE与cwd_walk_up的探测优先级以及如何为自己的 OpenClaw 风格工作区编写可被 gbrain 干净解析的SKILL.md与AGENTS.md。一、背景OpenClaw 参考工作区是什么为什么需要兼容层OpenClaw 的典型部署布局与 gbrain 自身体系不同它不要求skills/manifest.json而是在工作区根目录放一份AGENTS.md充当技能路由表技能本体以skills/name/SKILL.md的形式平铺存放。gbrain 在 v0.17 引入了 W1 ship-blocker 门禁承诺gbrain check-resolvable可以对此类布局干净运行并给出合理问题清单。验证这一承诺的正是 test/e2e/openclaw-reference-compat.test.ts其开头注释明确写道这是证明 v0.17 核心声明的 THE test——对 OpenClaw 参考工作区布局根目录AGENTS.md 下方skills/、无manifest.json执行gbrain check-resolvable要求零错误且能暴露合理问题。该测试的输入 fixture 即 test/fixtures/openclaw-reference-minimal/它只包含 4 个技能query、brain-ops、context-now、signal-detector和一份带解析器表的AGENTS.md刻意保持最小。fixture 的 AGENTS.md 是理解整套布局的钥匙它把路由规则组织成若干分区表格## Gate 0 — access control | Trigger | Skill | |---------|-------| | Every inbound message | skills/signal-detector/SKILL.md | ## Brain operations | Trigger | Skill | |---------|-------| | what do we know about, search for, lookup | skills/query/SKILL.md | | any brain read/write/lookup/citation | skills/brain-ops/SKILL.md | ## Calendar | Trigger | Skill | |---------|-------| | am I late, how long until, what time is | skills/context-now/SKILL.md |其中skills/query/SKILL.md这一行正是关联文档在路由表中的落点三个触发器what do we know about、search for、lookup全部指向它。二、fixture 技能的解剖query/SKILL.md 的 frontmatter 契约关联文档 query/SKILL.md 全文极短但它的价值不在正文而在 YAML frontmatter 所声明的契约--- name: query description: Look up brain pages in the OpenClaw reference fixture. triggers: - what do we know about - search for - lookup --- # query Fixture skill for test/e2e/openclaw-reference-compat.test.ts.这份 frontmatter 恰好对应 gbrain 技能解析器在三个维度上的最低要求name技能的规范标识。在无manifest.json时loadOrDeriveManifest通过parseSkillName从 frontmatter 中正则提取name:字段支持裸值、双引号、单引号三种写法提取失败则回退到目录名参见 src/core/skill-manifest.ts。因此name: query与目录名query/一致时两条推导路径殊途同归。description技能的语义摘要供解析器与路由评估routing-eval阅读不参与路由匹配本身。triggers技能自带的触发器列表。这是 v0.41.11 之后路由的权威来源canonical source of truth见 src/core/skill-trigger-index.ts 的注释。与之对照仓库生产版 skills/query/SKILL.md 展示了同一技能的完整形态它额外声明了version: 1.0.0、8 个以上的触发器含tell me about、who is、graph query等、8 个工具依赖recall、search、query、get_page、list_pages、get_backlinks、traverse_graph、get_timeline以及mutating: false。fixture 版则刻意只保留路由所需的最小字段——这正体现了 fixture 的用途只验证布局兼容性不承担技能行为测试。同一 fixture 里的另外三个技能还展示了 frontmatter 的扩展字段# skills/brain-ops/SKILL.md name: brain-ops description: Core read/write cycle for the OpenClaw reference fixture. triggers: - any brain read/write/lookup/citation writes_pages: true writes_to: - people/ - companies/writes_pages: true与writes_to:是 v0.17 归档审计W3的输入。需要特别区分的是writes_pages与更早的mutating语义不同——mutating: true只表示有副作用如写 cron、配置、报告而writes_pages: true特指向某个语义目录写大脑页面。cron/配置类技能只设mutating: true而不设writes_pages从而被归档审计正确豁免见 src/core/filing-audit.ts。三、无 manifest.json 时清单如何推导auto-derive 路径F-ENG-1传统上manifest.json缺失会让可达性检查与自动修复静默失效——这正是 v0.17 要解除的场景。src/core/skill-manifest.ts 将两条调用路径check-resolvable.ts的可达性检查与dry-fix.ts的自动修复收敛到同一个入口loadOrDeriveManifest若skillsDir/manifest.json存在且可解析原样使用否则遍历skillsDir/*子目录对每个含SKILL.md的目录从 frontmatter 读取name:构造{name, path}path 形如query/SKILL.md——这就是 auto-derive 路径返回{skills, derived: boolean}让调用方在--verbose/--json输出中呈现推导模式。推导过程还有两个值得注意的规则点前缀目录以.或_开头被排除——它们承载约定文档与共享规则文件而非技能结果按name字典序排序。对 fixture 而言loadOrDeriveManifest(SKILLS_DIR)应当返回derived: true且skills恰好是[brain-ops, context-now, query, signal-detector]——这正是 test/e2e/openclaw-reference-compat.test.ts 中断言的排序结果。四、技能目录自动探测$OPENCLAW_WORKSPACE 与 cwd_walk_up 的优先级check-resolvable的输入是skills/目录但这个目录本身需要先被找到。src/core/repo-root.ts 注释给出了 v0.31.7 起的完整优先级readwrite 安全序层级探测源说明0$GBRAIN_SKILLS_DIR操作者显式覆盖任何调用方均安全1$OPENCLAW_WORKSPACE显式环境变量优先于仓库向上遍历D-CX-41bcwd_walk_up从 cwd 向上最多 10 层找任意含skills/的祖先目录v0.33 新增无解析器文件门槛2~/.openclaw/workspace/用户默认 OpenClaw 部署目录3findRepoRoot()向上遍历gbrain 自身仓库4./skills回退开发草稿、fixture关键细节有两点。其一$OPENCLAW_WORKSPACE必须显式设置才生效它支持绝对路径或相对startDir的相对路径并且要命中workspace 根含AGENTS.md 同级skills/这种形态时会返回source: openclaw_workspace_env_root子目录形态则返回openclaw_workspace_env。其二cwd_walk_up层1b刻意排在$OPENCLAW_WORKSPACE之后、~/.openclaw/workspace之前是为了保证显式环境变量永远优先防止 R5 优先级回归同时让cd ~/git/your-agent-repo gbrain skillpack scaffold X命中 agent 仓库而非隐式回退到 OpenClaw 默认安装目录。另外该层只接受包含在祖先目录内的skills/逃逸符号链接会被跳过并继续向上见 src/core/repo-root.ts。对于 fixturetest/e2e/openclaw-reference-compat.test.ts 验证了设置OPENCLAW_WORKSPACE: FIXTURE后autoDetectSkillsDir(process.cwd(), env)返回SKILLS_DIR且source为openclaw_workspace_env_root——因为 fixture 的AGENTS.md在工作区根而非skills/内部。而 test/e2e/workspace-generic-compat.test.ts 则用另一个 fixture 验证了cwd_walk_up层不设任何环境变量也能从祖先目录找到skills/。值得注意的还有解析器文件名策略src/core/resolver-filenames.ts 规定RESOLVER.md与AGENTS.md都是合法解析器文件名同一位置两者并存时RESOLVER.md优先gbrain 原生惯例保持 gbrain 自身仓库不受影响。findAllResolverFiles还会把两个文件都找出来让调用方合并条目而非静默忽略更丰富的一份。五、路由表的 UNION 合并语义frontmatter 触发器与 AGENTS.md 行check-resolvable的可达性判定依赖统一触发器索引 src/core/skill-trigger-index.tsloadSkillTriggerIndex(skillsDir) merge(frontmatter 条目, 解析器文件条目)合并语义是UNION 而非替换AGENTS.md中为技能 S 声明的触发器 T 是在 S 的 frontmatter 触发器之上追加而不是覆盖。去重键为(skillPath, trigger.trim().toLowerCase())因此 frontmatter 里的search for与AGENTS.md表格里的search for会折叠为一条且首次出现者获胜——frontmatter 条目先传入所以同形重复行即使也出现在AGENTS.md中其source仍保持frontmatter见 src/core/skill-trigger-index.ts。这条统一路径解决了 v0.41.x 的一类漂移 bug#1451此前checkResolvable、routing-eval CLI、mounts-cache.composeResolver各有各的加载器frontmatter 触发器修复了doctor却漏掉了 routing-eval CLI。合并后所有消费方折叠通过同一原语代价只是每次调用约 50 次readFileSync冷启动约 5ms热启动亚毫秒。对 fixture 而言AGENTS.md的 Brain operations 分区把what do we know about, search for, lookup路由到skills/query/SKILL.md与 query 技能 frontmatter 自带的三个触发器完全吻合因此 4 个技能全部可达。checkResolvable的报告摘要中total_skills: 4、reachable: 4、unreachable: 0见 test/e2e/openclaw-reference-compat.test.ts。六、check-resolvable 的完整检查链与错误/警告语义src/core/check-resolvable.ts 定义了ResolvableIssue的类型全集。从类型联合可以看出检查体系的分层可达性Check 1unreachable技能在 manifest 中但无触发器指向、missing_file解析器指向的文件不存在MECE 完备性mece_overlap多个技能命中同一触发器、mece_gapDRY 违规dry_violation同一触发器在 frontmatter 与解析器表中重复声明、orphan_trigger路由评估W2v0.17routing_miss、routing_ambiguous、routing_false_positive、routing_fixture_lint——由runRoutingEval基于routing-eval.ts的索引与 fixture 产生归档审计W3v0.17filing_missing_writes_to、filing_unknown_directory——由runFilingAudit产生脚手架残留D-CX-9skillify_stub_unreplaced——技能脚本中仍含SKILLIFY_STUB: replace before running check-resolvable --strict哨兵见 src/core/check-resolvable.ts严重度语义同样值得明确见 src/core/check-resolvable.ts 注释ok仅当error 级问题为零warning 不会翻转ok需要严格模式的调用方应同时检查errors.length 0 warnings.length 0。默认退出码也由此决定。issues字段是errors与warnings的合并已标记 deprecated将在 v0.18 移除——新代码应分别消费errors和warnings。归档审计W3的具体规则见 src/core/filing-audit.ts对每个writes_pages: true的技能(1) 必须声明非空writes_to: [dir, ...](2) 每个目录必须是 skills/_brain-filing-rules.json 中的合法归档目标其中sources/显式放行批量数据采集是合法归档目标。审计失败以 warning 呈现D-CX-3 D-CX-5不会让未采用writes_pages/writes_to的工作区 CI 变红若规则文档本身加载失败则以一条近乎 fatal 的filing_unknown_directory条目呈现见 src/core/check-resolvable.ts。fixture 中的 brain-ops 正是干净通过的正面样例它声明了writes_pages: true且writes_to指向people/、companies/因此归档审计警告为零见 test/e2e/openclaw-reference-compat.test.ts。七、CLI 实测两种方式验证 OpenClaw 参考工作区checkResolvable的 CLI 入口是gbrain check-resolvablefixture 测试给出了两种可复现的验证方式。方式一显式指定技能目录bun src/cli.ts check-resolvable --json --skills-dir test/fixtures/openclaw-reference-minimal/skills该命令返回ok: true、report.errors: []、report.summary.total_skills: 4见 test/e2e/openclaw-reference-compat.test.ts。从 gbrain 仓库根目录运行时这等价于直接对 fixture 的skills/执行全量 W1W2W3W4W5 检查。方式二环境变量自动探测OPENCLAW_WORKSPACE/path/to/test/fixtures/openclaw-reference-minimal \ bun src/cli.ts check-resolvable --json不传--skills-dir靠$OPENCLAW_WORKSPACE触发 tier 1 探测输出中skillsDir应等于 fixture 的skills/路径、ok: true见 test/e2e/openclaw-reference-compat.test.ts。这正是从 gbrain 仓库内执行时环境变量不被仓库自身的skills/遮蔽这一优先级设计的实测证明。方式三可选check-resolvable 的三处调用点checkResolvable本身有三个调用点见 src/core/check-resolvable.ts 注释bun test单元测试断言、gbrain doctor运行时健康检查附带可操作的 agent 指引、以及 skill-creator 技能创建后的强制校验门禁。也就是说你在 OpenClaw 风格工作区里新增或修改技能后既可以用gbrain doctor做日常体检也可以在skillify流程中作为发布前的强制闸门。八、skillpack 安装对 OpenClaw 布局的写入契约兼容层不仅读得懂OpenClaw 布局还写得进。fixture 测试的最后一组用例验证了gbrain skillpack install对该布局的写入行为见 test/e2e/openclaw-reference-compat.test.ts把 fixture 复制到临时工作区只保留一份AGENTS.md壳# AGENTS 空的路由表头调用planInstallapplyInstall安装brain-ops技能断言新技能文件被写入、managedBlock.applied: true、解析器文件路径指向AGENTS.md写入后的AGENTS.md包含gbrain:skillpack:begin标记、指向skills/brain-ops/SKILL.md的行且预先存在的路由表头| Trigger | Skill |被完整保留。这意味着 gbrain 以受管区块managed block的形式把新增技能行注入AGENTS.md而不是覆盖用户手工维护的路由表——这与 fixture 布局AGENTS.md 即真实调度器的定位一致。整个流程依赖 src/core/skillpack/installer.ts 的planInstall/applyInstall与 src/core/skillpack/bundle.ts 的findGbrainRoot而测试通过mkdtempSync复制副本保证了 fixture 本身不被污染。九、把 fixture 技能升级为生产级 query 技能最后回到关联文档本身。fixture 版的query/SKILL.md只有 12 行而仓库生产版 skills/query/SKILL.md 是一份 226 行的完整技能说明恰好可作为从 fixture 到生产的升级路线图触发器扩容从 3 个扩展为 8 个以上who is、what happened、background on、connections、graph query等覆盖问答、查找、关系查询三类意图工具清单声明recall、search、query、get_page、list_pages、get_backlinks、traverse_graph、get_timeline八个依赖并给出各工具的语义分工关键词搜索 vs 混合搜索 vs 结构化查询行为契约保证每个答案锚定大脑内容、每条论断带页面 slug 级引用、缺口显式标注the brain doesnt have information on X、冲突来源并列引用失败处理定义了empty_retrieval kinddegraded、listing_truncated、page_not_found等 notice 的解读与应对预算意识如gbrain recall --query zebra telescope --budget-tokens 75 --budget-policy query_first --json这类受限预算查询以及return_unit: page/window整页交付选项。如果你要为自己的 OpenClaw 风格工作区编写技能最低门槛就是 fixture 版那样的 frontmatternamedescriptiontriggers而完整形态则应以生产版为参照。无论哪种形态只要AGENTS.md路由表与 frontmatter 触发器一致、writes_pages技能声明了合法writes_togbrain check-resolvable都能给出ok: true的干净报告。十、小结从 query/SKILL.md 这份 12 行的 fixture 出发我们看到了一条完整的 OpenClaw 兼容链路autoDetectSkillsDirtier 0/1/1b 优先级探测→loadOrDeriveManifest无 manifest.json 时的 frontmatter 推导→loadSkillTriggerIndexfrontmatter 与 AGENTS.md 的 UNION 合并→checkResolvable可达性、MECE、DRY、路由评估、归档审计五层检查→skillpack install受管区块写入 AGENTS.md。每一环都有源码实现与 e2e 测试双保险实现见 src/core/repo-root.ts、src/core/skill-manifest.ts、src/core/skill-trigger-index.ts、src/core/check-resolvable.ts、src/core/filing-audit.ts验证见 test/e2e/openclaw-reference-compat.test.ts 与 test/e2e/workspace-generic-compat.test.ts。对使用 OpenClaw 或任何根目录 AGENTS.md skills/ 平铺工作区的开发者而言这意味着你可以把 gbrain 的check-resolvable、doctor与 skillpack 直接用作该工作区的路由健康检查与技能安装工具无需为 gbrain 改造现有布局也无需维护一份重复的manifest.json。赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐gbrain 的 AGENTS.md 路由解析与 OpenClaw 参考布局兼容从 resolver 表到 check-resolvable 全链路验证gbrain 的 AGENTS.md 路由解析与 OpenClaw 参考布局兼容从 resolver 表到 check resolvable 全链路验证 本篇人工智能RAGAgent 记忆MCP 服务知识管理gbrain 技能文件解剖从 query-helper 理解 SKILL.md 的编写规范与技能目录机制gbrain 技能文件解剖从 query helper 理解 SKILL.md 的编写规范与技能目录机制 导读 query helper 是 gbrain 仓人工智能RAGAgent 记忆MCP 服务知识管理OpenClaw Mastery 实战手把手编写 quick-note 工作区技能SKILL.md 完整拆解与验证流程OpenClaw Mastery 实战手把手编写 quick note 工作区技能SKILL.md 完整拆解与验证流程 在 OpenClaw 的十步进阶课文档教程人工智能大模型上一篇Quantum为什么这么快协程栈池与预分配内存池源码级剖析下一篇N_m3u8DL-RE MKV混流报错 mux failed一个语言标签引发的翻车与修复创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考