企业官网建设流程全解析

gbrain 输出规范指南：确定性链接、无废话写作与脑页交付纪律

【免费下载链接】gbrainGarry's 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）采用完全相反的链接形态：

由此派生出两条明确的禁令：

1. 脑页正文里永远不要写页间绝对 URL—— 绝对 URL 只留给真正的外部目标；
2. 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）交给用户时，它必须满足三步准则：

1. 从实际数据构建：仓库相对路径取自git ls-files --full-name，远端取自git remote get-url origin；绝不凭记忆组合；
2. 先推送，再链接（Pushed before linked）：托管 URL 在推送落地之前必然 404；
3. 验证可解析：存在托管远端时验证链接确实能打开（推送的 ref-update 输出在宿主 API 滞后时可作为证据）。

回退链（Fallback chain）：没有托管远端时怎么办

当脑库没有托管远端（或验证失败）时，按顺序回退：

1. 托管 git 远端 URL（已验证）——脑库有可渲染文件的远端宿主时；
2. 仓库相对路径 + 范围说明——无托管远端（默认的 PGLite 脑库常常没有远端，或仓库仅本地）时，给出people/alice-example.md这类路径，并直说它是脑库内的本地路径；
3. 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 + PBKDF2，100K 次迭代，随机 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 origin，<branch>来自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.com（token 的签发宿主），绝不要把你从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" 一章为脑页正文立下文体标准，明确禁止以下内容：

• 填充短语：如 "It's worth noting that..."、"Interestingly..."（值得一提的是、有趣的是）；
• 有据可查时的含糊措辞：应写 "According to the source, X is true"，而不是 "X might be true"；
• LLM 开场白：如 "I've created..."、"Here's 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不是孤立的文档，它与相邻约定有明确边界（dedup）：

• skills/brain-link-discipline/SKILL.md负责每次交付消息的机制（推导、排序、验证、中继重写、批量格式），_output-rules.md只承载跨技能的准则本身；
• skills/publish/SKILL.md负责"如何"生成可分享 HTML 工件（剥离、加密、输出选项），输出规范只决定"何时"回退到它，并禁止把它的产物承诺为 URL；
• skills/conventions/brain-first.md规定查找链中的一行原则——"输出中每个脑页引用都应使用与部署形态适配的可点击链接格式"（GitHub URL、本地路径或 slug），brain-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 交付前的自检清单：

1. 脑页内的页间链接是否全部为相对路径（保护 links/backlinks 图）？绝对 URL 是否只用于真正的外部目标？
2. 交付给用户的链接是否由git ls-files --full-name/git remote get-url origin机械推导，而非凭记忆？
3. 是否遵守了先推送、后链接的顺序，并验证了可解析性（或持有 ref-update 证据）？
4. 无托管远端时，是否按"已验证远端 URL → 仓库相对路径 + 本地说明 →gbrain publishHTML 工件"的顺序回退？
5. 中继子代理结果前，是否完成了路径重写？
6. 正文是否有填充短语、含糊措辞、LLM 开场白、占位日期？是否做到了短段落、具体事实、行内引用？
7. 引用他人原话时是否逐字保留？
8. 标题是否≤60 字符、描述性足够、既非句子也非泛化词？

把这套纪律落到 Agent 的每次脑页写入与交付上，就能让 gbrain 的链接图保持完整、检索保持高效、知识工件保持零噪音——这正是plugin-variants/gbrain-coding/skills/_output-rules.md作为跨技能规范的真正价值所在。

【免费下载链接】gbrainGarry's Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain