gbrain 输出规范指南确定性链接、无废话写作与脑页交付纪律【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本篇技术指南围绕 gbrain 技能包中的跨技能输出规范_output-rules.md展开系统讲解 brain-writing 类技能在生成脑页brain page与面向用户的聊天交付物时必须遵守的质量底线链接必须确定性构建并区分页面内/消息内两种相反形态、交付链接必须可验证且先推送再给出、正文严禁 LLM 套话、原话保留与标题质量的具体标准。读完本文你将掌握一套可直接套用的输出纪律以及这些规范在 gbrain 源码链接图提取、backlinks 审计命令中的落地点能用于约束 Agent 写出可检索、可追溯、零噪音的持久知识产物。一、为什么 brain-writing 技能需要一份横切输出规范gbrain 仓库的skills/目录下承载着大量脑页写入技能capture、meeting-ingestion、schema-author 等而plugin-variants/gbrain-coding/skills/_output-rules.md与skills/_output-rules.md这两份同源文件正是为所有 brain-writing 技能提供跨切面cross-cutting输出质量标准的公共约定。它与plugin-variants/gbrain-coding/skills/_AGENT_README.md中定义的技能目录结构相呼应该目录下_output-rules.md被标注为 output quality standards (no LLM slop, exact phrasing)与_brain-filing-rules.md页面归档规则、_friction-protocol.md摩擦日志协议并列构成 Agent 每次冷启动都应当读取的操作契约。规范的核心判断是脑页不是聊天输出而是持久化的知识工件Brain pages are not chat output. They are durable knowledge artifacts。因此它的质量要求与聊天回复截然不同需要用独立的成文标准来约束。二、确定性链接Deterministic Links绝不靠 LLM 猜 URL规范的第一条铁律是脑页中的所有链接必须是确定性的deterministic——由真实数据构建slug、commit hash、API 响应而不是由 LLM 凭记忆拼凑。任何猜测一个 URL 或路径的行为都是被禁止的脑页链接page title—— 由页面所属类型people/companies/deals 等与 slug 构建提交链接[abc1234](https://host/owner/repo/commit/abc1234)—— hash 来自真实提交外部链接使用来源给出的实际 URL绝不重建never reconstruct it。这条规则的动机很实际LLM 组合出的路径一旦与真实文件系统不一致就会产生 404 死链而这类死链在知识图谱类系统中破坏力尤其大——因为 gbrain 的链接图正是从这些路径构建的。双表面反转页面内用相对链接消息内用绝对链接规范中最反直觉、也最关键的一条是两个输出表面output surface采用完全相反的链接形态输出表面链接形态原因脑页内部in-page相对 Markdown 链接如page titlegbrain 的链接提取器从文件系统相对链接构建 links/backlinks 图该图支撑关系检索relational retrieval两个脑页之间的绝对 URL 对该图不可见面向用户的聊天消息in-message绝对、已验证的 URL或下方回退链仓库相对路径在聊天界面中不可点击由此派生出两条明确的禁令脑页正文里永远不要写页间绝对 URL—— 绝对 URL 只留给真正的外部目标frontmatter 中的related:/people:键保持裸相对路径机器解析不参与渲染为散文。这背后有源码级的支撑src/commands/backlinks.ts的头部注释明确写着gbrain check-backlinks是 Deterministic: zero LLM calls它通过扫描页面中的实体提及entity mentions来检查/创建反向链接其实现从src/core/link-extraction.ts导入规范的实体引用提取器canonicalExtractEntityRefs并只投影people/与companies/两类目录的引用。也就是说页面内相对链接的书写质量直接决定check-backlinks能否正确审计链接图。技能侧的操作指引也一致skills/brain-link-discipline/SKILL.md在链接密集写入后建议运行gbrain check-backlinks check审计链接图再用gbrain sync --no-pull让新页面可被搜索——这与skills/conventions/brain-first.md中每次脑页写入后触发同步的约定完全吻合。已验证交付链接准则Verified-deliverable-link canon当链接作为交付物deliverable交给用户时它必须满足三步准则从实际数据构建仓库相对路径取自git ls-files --full-name远端取自git remote get-url origin绝不凭记忆组合先推送再链接Pushed before linked托管 URL 在推送落地之前必然 404验证可解析存在托管远端时验证链接确实能打开推送的 ref-update 输出在宿主 API 滞后时可作为证据。回退链Fallback chain没有托管远端时怎么办当脑库没有托管远端或验证失败时按顺序回退托管 git 远端 URL已验证——脑库有可渲染文件的远端宿主时仓库相对路径 范围说明——无托管远端默认的 PGLite 脑库常常没有远端或仓库仅本地时给出people/alice-example.md这类路径并直说它是脑库内的本地路径gbrain publish输出作为可附带的 HTML 工件——gbrain publish page-path生成自包含的本地 HTML 文件输出行格式为Published: local-path可以附带或发送该文件但绝不能把它当作 URL 呈现因为它不是 URL敏感内容用--password。关于第 3 级回退skills/publish/SKILL.md提供了完整补充发布的 HTML 完全自包含、无服务器依赖发布前会剥离全部私有元数据YAML frontmatter、[Source: ...]引用、确认号、脑页交叉链接、时间线段落、See also 行仅保留外部 URL 与正文默认总是加密AES-256-GCM PBKDF2100K 次迭代随机 16 字节盐与 12 字节 IV解密在客户端经 Web Crypto API 完成除非用户明确要求 open/no password/public。三、机制落地brain-link-discipline 技能是这份准则的操作手册_output-rules.md自己声明了分工它承载准则canon——确定性构建、双表面范围切分、回退链而具体的机制mechanics——路径推导、推送-链接顺序、验证、子代理中继重写、批量列表格式——由skills/brain-link-discipline/SKILL.md负责该技能在 frontmatter 中同样引用了_output-rules.md的 Deterministic Links 一节。从该技能可以提取出准则的完整操作规程路径机械推导。托管远端服务的路径是相对git 仓库根git rev-parse --show-toplevel的而不是当前工作目录。当仓库根位于工作目录之上时手工剥离 cwd 前缀会静默丢掉中间目录段导致所有链接 404。正确做法# 在仓库内任意位置打印远端服务的精确路径 cd $(dirname file) git ls-files --full-name $(basename file) # 例如people/alice-example.md然后组装https://host/owner/repo/blob/branch/精确路径其中host/owner/repo来自git remote get-url originbranch来自git rev-parse --abbrev-ref HEAD文件用/blob/、目录用/tree/。顺序铁律push BEFORE link① 写入/编辑脑页文件 → ②git add git commit git push→ ③ 验证推送落地push 输出必须显示 ref 更新如abc123..def456 main - main→ ④ 在报告该提交的同一条消息中输出链接可点击的 Markdown 链接或裸 URL绝不用反引号代码段。验证再链接存在托管远端时用 GitHub API 检查路径是否存在仅200才发送链接若刚推送完宿主 API 滞后则推送输出中 ref 移动的证据已足够。技能还特别强调凭据安全Authorization: token头只能发给api.github.comtoken 的签发宿主绝不要把你从git remote get-url origin推导出的、未经确认的宿主当作 token 接收方——被篡改的origin指向攻击者主机会导致凭据被收割。其他远端一律以未认证方式验证公开仓库存在性检查无需 token拿不准就不发 token。子代理中继重写规则子代理在本地上下文运行、返回的是本地路径原样转述子代理结果如media/books/widget-co-notes.md是链接 bug 的头号来源。中继前必须把每个脑页路径按同一套推导 回退链重写。派生子代理写脑页时任务提示中应包含以git ls-files --full-name的仓库相对路径报告脑页由父代理在转发前重写为链接。批量列表格式每行一个链接或回退形态、完整 URL、不加反引号例如Created 3 pages: - https://host/owner/repo/blob/main/people/alice-example.md - https://host/owner/repo/blob/main/people/charlie-example.md - https://host/owner/repo/blob/main/companies/acme-example.md范围说明私有脑库中的托管链接只对拥有仓库访问权限的人可打开适合用户自己的聊天界面但不是面向外部受众的可分享链接对外分享应落入gbrain publish工件这一级。该技能还罗列了典型的反模式可直接作为自查清单提交后不给链接给出本地绝对路径而非链接或相对路径回退等用户来要链接原样转述含本地路径的子代理结果在git push落地前输出托管 URL把gbrain publish的输出当作 URL手工剥离 cwd 前缀应使用git ls-files --full-name在脑页内部用绝对 URL 做页间引用在可点击链接可用时用反引号包路径凭记忆猜 URL。四、无废话No Slop脑页是知识工件不是聊天记录规范用 No Slop 一章为脑页正文立下文体标准明确禁止以下内容填充短语如 Its worth noting that...、Interestingly...值得一提的是、有趣的是有据可查时的含糊措辞应写 According to the source, X is true而不是 X might be trueLLM 开场白如 Ive created...、Heres the updated...、Certainly!我已创建、这是更新后的、当然占位日期如 YYYY-MM-DD、recently、in the near future近期、不久的将来。同时提出正面要求短段落、具体事实、行内引用Short paragraphs. Concrete facts. Inline citations。这一定位的核心依然是那句判断——脑页是持久知识工件任何废话都会稀释后续检索与阅读的价值并污染被skills/conventions/brain-first.md所要求的脑优先查找流程。五、原话保留Exact Phrasing Preservation语言本身就是洞见当记录某人原本的思考时规范要求使用他们的原话不要转述不要修正语法——The language IS the insight语言本身就是洞见。具体到三类场景直接引用在引用块中逐字保留观点与框架slug 与标题使用对方自己的术语观察记录捕捉原表述而非净化版本。这条规范保证了脑库作为第二大脑的记忆保真度转述会引入信息损耗与价值判断而原话保留了说话者的措辞、语气与思维框架——这些恰恰是后续关系检索与语义理解中最有价值的部分。六、标题质量Title Quality让页面在搜索结果中可识别规范对页面标题给出三条可操作标准描述性足够仅凭搜索结果就能识别页面Meeting with Pedro 比 Meeting 强足够短列表扫读友好60 字符以内不是句子、不是泛化词反例是 Meeting with Pedro about the new deal structure句子与 Person Page泛化正例是 Pedro Franceschi用实体名作为标题。这些标准直接服务于脑页的可检索性——标题是gbrain search、query、get_page等脑优先工具见skills/conventions/brain-first.md的工具清单命中与展示的第一依据。七、规范体系的边界与相互关系_output-rules.md不是孤立的文档它与相邻约定有明确边界dedupskills/brain-link-discipline/SKILL.md负责每次交付消息的机制推导、排序、验证、中继重写、批量格式_output-rules.md只承载跨技能的准则本身skills/publish/SKILL.md负责如何生成可分享 HTML 工件剥离、加密、输出选项输出规范只决定何时回退到它并禁止把它的产物承诺为 URLskills/conventions/brain-first.md规定查找链中的一行原则——输出中每个脑页引用都应使用与部署形态适配的可点击链接格式GitHub URL、本地路径或 slugbrain-link-discipline 是这一行原则在交付消息上的完整展开skills/citation-fixer/SKILL.md负责修复脑页内部的损坏引用不处理对外消息链接。从plugin-variants/gbrain-coding/skills/_AGENT_README.md的目录说明还能看到这套规范在宿主环境中的角色技能目录中_output-rules.md是 Agent 每次冷启动都要读取的操作契约之一其内容随 gbrain 版本升级通过gbrain skillpack reference对比、而非自动覆盖——本地修改被视为有意为之gbrain 只是参考库。结语一条可复用的输出自检清单综合_output-rules.md与仓库中配套技能与源码可以把整套输出规范浓缩为一份 Agent 交付前的自检清单脑页内的页间链接是否全部为相对路径保护 links/backlinks 图绝对 URL 是否只用于真正的外部目标交付给用户的链接是否由git ls-files --full-name/git remote get-url origin机械推导而非凭记忆是否遵守了先推送、后链接的顺序并验证了可解析性或持有 ref-update 证据无托管远端时是否按已验证远端 URL → 仓库相对路径 本地说明 →gbrain publishHTML 工件的顺序回退中继子代理结果前是否完成了路径重写正文是否有填充短语、含糊措辞、LLM 开场白、占位日期是否做到了短段落、具体事实、行内引用引用他人原话时是否逐字保留标题是否≤60 字符、描述性足够、既非句子也非泛化词把这套纪律落到 Agent 的每次脑页写入与交付上就能让 gbrain 的链接图保持完整、检索保持高效、知识工件保持零噪音——这正是plugin-variants/gbrain-coding/skills/_output-rules.md作为跨技能规范的真正价值所在。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
