gbrain 路径纪律Path DisciplineAgent 必须把显示字符串与文件路径当作两种类型【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain这篇技术指南解读 gbrain 技能库中面向 LLM Agent 的硬性约定 path-discipline.md当 Agent 使用文件工具读写脑库页面时任何带 Markdown 链接、反引号或 URL 的显示字符串都不能被当作路径参数传入。读完本文你将掌握路径参数的判别规则、写入类调用静默失败的识别方法、首次失败即修复的重试纪律以及基于 git 元数据机械推导路径、用 shell 变量拼接路径等可落地的防御手段。问题本质上下文把两种不同类型揉成了一团gbrain 是一个由 Agent 驱动的个人脑库系统Agent 负责把对话、笔记、研究结果写成脑库中的 Markdown 页面people/、concepts/、companies/等目录再用search、query、get_page、put_page等工具读写它们。这些工具是围绕文件系统路径设计的——cli.ts 中get_page命令接收的正是脑库内的相对路径如people/alice-example.md。问题出在 Agent 的对话上下文上同一轮对话里Agent 既要给用户输出给人看的路径Markdown 链接、完整 URL、反引号、加粗又要给工具传给系统用的裸路径。这两种东西在文本形态上高度相似上下文很容易把它们揉在一起——上一轮刚渲染出来的label下一轮被模式补全pattern-completion直接填进了工具调用的路径参数里。于是工具收到的是一个链接格式字符串而不是文件系统路径。这就是path-discipline.md全文想钉死的一条规定A display string is not a path. Never pass a link-formatted reference to a file tool.两种类型裸路径 vs 显示形态约定把路径明确分成两类并指出这是不同的类型different types不是同一东西的两种写法类型用途示例裸路径Bare path仅用于工具输入people/alice-example.md显示形态Display forms仅用于回复输出[people/alice-example.md](https://github.com/acme-example/brain/blob/main/people/alice-example.md)、原始 URL、任何被反引号或加粗包裹的上述形式上表中的acme-example是原文档用来示意链接形态的虚构占位符并非真实外部地址。调用前的判别规则在任何 read / write / edit / grep / shell 调用之前路径参数中**不得出现、这种链接标记时工具不会报错而是创建一个名字里就带着链接标记的垃圾目录顶层目录名以[开头把内容写进这个目录里返回Successfully wrote N bytes。于是文件落地在一个谁都找不到的地方而那条成功消息反过来支撑了一个虚假的已完成声明。约定因此给出两个推论写入成功消息不是文件落地的证据只要路径参数里含链接标记无论返回值是什么本次调用都必须按失败处理任何重要的写入之后都要ls裸路径确认再声称 done / captured / committed。从仓库的测试可以看到这种显式路径纪律explicit-path discipline是项目级共识例如 write-through-commit.serial.test.ts 和 delete-write-through-commit.serial.test.ts 中都断言无关的编辑保持未提交状态显式路径纪律说明测试本身也在验证 Agent 是否只触碰显式给定的路径。重试纪律与恢复流程首次失败即修复绝不原样重发约定明确警告畸形参数不是工具不稳定a malformed argument is not a flaky tool。同一字符串的重试永远不会成功——因为问题不在工具而在参数本身。正确的做法是第一次失败后立即修复参数而不是原样重发dont reissue在重试前先做类型检查参数里有没有 、 规定脑库页面里的所有链接必须由真实数据构建而不是由 LLM 脑补——从 slug、commit hash 或 API 响应构建绝不凭记忆猜测 URL 或路径。这与路径纪律互为表里路径纪律禁止把显示字符串当路径用确定性链接规则禁止把猜测出来的路径当真实路径用。该文件还定义了输出表面的作用域分裂scope split值得特别注意——两个输出表面要求的链接形式是相反的输出表面链接形式原因脑库页面内部in-page相对 Markdown 链接page titlegbrain 的链接提取依赖文件系统相对链接构建 links/backlinks 图图驱动关系检索页面间的绝对 URL 对该图不可见聊天消息交付in-message绝对且验证过的 URL仓库相对路径在聊天表面不可点击脑库页面之间的引用写绝对 URL会直接破坏关系检索而 frontmatter 中的related:/people:键要保持裸相对路径机器解析不是渲染文本。2. 路径机械推导 先推送后链接brain-link-discipline/SKILL.md 给出了路径纪律在交付链接场景的完整机制。其核心同样是把路径推导从凭感觉写变成机械命令输出# 从仓库任意位置打印远端实际服务的精确路径 cd $(dirname file) git ls-files --full-name $(basename file) # 例如people/alice-example.md推导时以git 仓库根git rev-parse --show-toplevel为基准而不是当前工作目录手动裁剪 cwd 前缀会静默丢掉中间目录段导致每个链接 404。组装托管 URL 时host/owner/repo取自git remote get-url origin分支取自git rev-parse --abbrev-ref HEAD。另一个与路径纪律同构的教训是顺序必须先推送、后链接——托管 URL 在推送落地之前必然 404。这跟先ls裸路径、再声称 done是同一个验证先于声明verify-before-claim的模式。对子代理返回的本地路径父代理在转发前必须重写subagent-relay rewrite这正是显示字符串流入工具参数的高发边界。3. 验证工具检查链接图与记录摩擦链接密集的写入之后用gbrain check-backlinks check审计链接图实现见 src/commands/backlinks.ts用gbrain sync --no-pull让页面可被检索如果遇到路径纪律本身难以解释的摩擦文档说一套、工具做另一套、成功条件不清晰按 _friction-protocol.md 用gbrain friction log记录让维护者可见CLI 实现见 src/commands/friction.ts。这与把摩擦闷在肚子里然后继续犯错形成对照摩擦报告是反馈闭环的输入。反模式清单Anti-Patterns原文档给出的四个反模式是路径纪律最典型的四种破功方式逐条展开#反模式为什么危险正确做法1从自己格式化过的回复里把路径复制进工具调用回复里的路径是显示形态可能带链接标记或反引号复制即中毒用git ls-files --full-name重新机械推导或从 shell 变量引用2信任路径里含](时的Successfully wrote N bytes写入的成功只证明写了不证明写到了对的地方任何重要写入后ls裸路径再声称 done3因为错误看起来像偶发而重试同一个中毒字符串畸形参数不是 flaky 工具重试只会再次失败首次失败即修复参数4未ls裸路径就声称 captured / committed / done成功消息支撑的是虚假的完成声明先验证、后声明与相邻约定的关系regex-discipline.md正则纪律讲的是不要把需要判断的事交给正则路径纪律讲的是不要把显示字符串交给路径 API。两者共享同一条元规则——工具参数必须来自机械可验证的源头而不是来自 Agent 输出文本的自我引用。正则是对已亲眼验证过的机械模式的压缩路径则必须由 git 元数据等实际数据推导二者都不允许凭感觉。test-before-bulk.md先在小样本上验证再批量执行——与任何重要写入后ls验证一样都是验证先于宣称的纪律。brain-first.md与_output-rules.md前者给出脑库页面引用应使用与部署方式匹配的可点击链接的一行原则后者承载确定性链接与作用域分裂的跨技能准则path-discipline 则管住它们共同的底层前提——任何链接形态的字符串都不许进入文件工具。落地自检清单每次调用文件工具尤其是写入类前按此清单过一遍类型检查路径参数里是否含有[、](、http有任何一个 → 这是显示字符串先还原为裸路径。源头检查路径是从自己的回复文本里抄来的还是从 git 元数据 / shell 变量 / API 响应推导来的前者必须重建。失败响应报错出现https:/单斜杠或ENOENT先修参数不要原样重发。写入验证写入返回成功 ≠ 文件落地。ls裸路径确认文件在真实位置再声称 done。上下文防御对话记录里已充满链接形态路径时用D$BASE/...变量拼接不在生成文本中输出完整路径字符串。把显示字符串和文件路径当成两种类型对待是 gbrain 这类 Agent 脑库系统中成本最低、收益最直接的防错纪律——它同时防住了路径 404、垃圾目录堆积和虚假的已完成声明也让每一次工具调用都建立在机械可验证的路径之上。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
