brain-link-discipline

brain-link-discipline — 链接也是交付内容的一部分

**约定：**参见 _output-rules.md—— “确定性链接”部分包含跨技能的规范（页面内使用相对链接，消息中使用经过验证的链接，以及备用方案链）。此技能介绍具体操作：推导路径、先推送再发送链接、验证、重写子 Agent 中继内容，以及批量列表的格式。

约定：conventions/brain-first.md 阐述了一行原则（“输出中的每个 brain 页面引用，都应使用适合当前部署环境的可点击链接格式”）。此技能是对这行原则的完整展开。

这是一项报告约定：框架会通过此约定处理 brain 页面交付消息。它是撰写此类消息时应遵循的常设规则，并非工具强制执行的机械保证。

规则（同一条消息）

如果你提交并推送了 brain 页面，报告工作进展的消息中就必须包含链接。每次都要如此。推送成功后，链接必须出现在同一条回复中，不能只说“我来提交并推送”，却不附上链接。用户不应该还得追问“把链接发给我”或“页面在哪”。

适用于：

• 任何报告已创建或编辑 brain 页面的消息
• 批量报告（“创建了 5 个页面”——每个页面都要单独占一行并附上链接）
• 在日常对话中引用 brain 页面
• 转述提及 brain 路径的子 Agent 结果（先重写——见下文）

最常见的链接错误是提交了 brain 页面，却让用户自己去找。链接是交付内容的一部分，不是后续补充。

范围区分：消息内与页面内（形式相反）

这两种输出场景使用完全相反的链接形式：

场景	链接形式	原因
发给用户的聊天消息	绝对且经过验证的 URL（或下文的备用方案链）	在聊天界面中，仓库相对路径无法点击
brain 页面正文内	相对 Markdown 链接：[Alice Example](../people/alice-example.md)	gbrain 会从相对于文件系统的链接中提取链接和反向链接关系图，用于关系检索。两个 brain 页面之间的绝对 URL 对该关系图不可见

**在 brain 页面内引用其他页面时，绝不要使用绝对 URL。**页面正文中的绝对 URL 仅用于真正的外部目标。Frontmatter 中的 related: / people: 键应保留为不带格式的相对路径（由机器解析，不作为正文内容呈现）。大量添加链接后，使用 gbrain check-backlinks check 审计关系图，并用 gbrain sync --no-pull 使页面可供搜索。

以机械方式推导路径

托管 Git 远程仓库所提供的相对路径，是相对于 Git 仓库根目录（git rev-parse --show-toplevel），而不是当前工作目录。当仓库根目录位于工作目录的上级时，手动去除当前工作目录前缀会悄然丢掉中间目录段，导致你构建的每个链接都返回 404。不要手动去除前缀。按以下方式推导：

# From anywhere inside the repo, prints the EXACT path the remote serves:
cd "$(dirname <file>)" && git ls-files --full-name "$(basename <file>)"
# e.g. people/alice-example.md

然后组装：

https://<host>/<owner>/<repo>/blob/<branch>/<that-exact-path>

• <host>/<owner>/<repo> 来自 git remote get-url origin
• <branch> 来自 git rev-parse --abbrev-ref HEAD（或远程仓库的默认分支）
• 文件使用 /blob/，目录使用 /tree/（GitHub 风格的托管平台）

顺序（先推送，再链接）

1. 编写或编辑脑文件。
2. 执行 scripts/brain-commit-push.sh "<msg>" <file>（如果脑库没有辅助脚本，则执行 gbrain git commit-push -m "<msg>" -- <file>）。 该命令会在检出目录的写入锁下仅提交指定文件并推送， 合并远程提交，同时不触碰其他 Agent 的文件。
3. 确认推送已成功——命令必须以 0 退出，并打印 pushed <sha> to origin/<branch>（或 nothing to commit；即使出现 [gbrain notice] 提示检出目录落后，也仍表示推送已成功）。推送完成前，托管 URL 会返回 404。退出码非 0 时，不要输出链接： 遇到 commit_lock_busy 时重试一次；遇到 integrate_conflict 或 writer_coordinator_required 时停止并告知用户；绝不可退而使用 stash、pull --rebase 或普通推送 （结果）。
4. 在报告提交的同一条消息中，输出链接——使用可点击的 Markdown 链接或纯 URL，绝不能使用反引号括起来的代码片段。

链接前先验证（存在托管远程时）

在面向用户的消息中加入托管远程链接之前，确认远程上存在该路径。GitHub 示例（私有仓库需要令牌）：

curl -sf -o /dev/null -w '%{http_code}' \
  -H "Authorization: token $GITHUB_TOKEN" \
  "https://api.github.com/repos/<owner>/<repo>/contents/<repo-relative-path>"

只有返回 200 时才发送链接。如果刚刚推送，而主机 API 尚未同步， 能证明引用已更新的推送输出就足以作为依据——但绝不能编造或猜测 URL。

令牌只能发送给签发它的主机。 上方的 Authorization: token 请求头 指向 api.github.com，因为远程是 github.com 上的远程。如果尚未确认 git remote get-url origin 得出的主机就是令牌的签发主机，绝不要将 $GITHUB_TOKEN 发送给该主机：被篡改或意外设置的远程（origin 指向攻击者的主机，或令牌无权访问的企业版／自托管主机）可能会窃取凭据。对于 github.com 远程，使用 api.github.com。对于任何其他远程，进行未认证验证（检查公开仓库是否存在不需要令牌），或者跳过验证，改用推送提供的引用更新证据。有疑问时，不要发送令牌。

后备方案链（按顺序）

1. 已验证的托管 git 远程 URL。 脑库仓库在能呈现文件的主机上有远程 → 按上述方式构建并验证链接。
2. 相对于仓库的路径 + 范围说明。 没有托管远程（默认的 PGLite 脑库通常没有远程，或者仓库仅在本地）→ 提供相对于仓库的路径（people/alice-example.md），并明确说明这是脑库仓库中的本地路径。
3. 将 gbrain publish 的输出作为可附加的 HTML 制品。 gbrain publish <page-path> 会生成一个独立的本地 HTML 文件（其输出行是 Published: <local-path>）。提出附加或发送该文件——绝不可将其作为 URL 呈现，因为它不是 URL。敏感内容请使用 --password。

子 Agent 转达改写规则

子 Agent 在本地上下文中运行，并返回本地路径。原样转达子 Agent 的完成信息，是链接错误的首要来源：子 Agent 报告 media/books/widget-co-notes.md（或脑库检出目录中的绝对路径），转达时又原样复述。在将子 Agent 的完成信息改写成面向用户的回复前，必须按照上述推导方式和后备方案链改写每一条脑页面路径。

启动将要编写脑页面的子 Agent 时，请在其任务提示词中加入：

报告脑页面时，请提供由 git ls-files --full-name 输出的仓库相对路径。 父级负责在转达前将其改写为链接。

批量列表

每行一个链接，使用完整 URL（或后备形式），不加反引号：

Created 3 pages:
- https://github.com/<owner>/<repo>/blob/main/people/alice-example.md
- https://github.com/<owner>/<repo>/blob/main/people/charlie-example.md
- https://github.com/<owner>/<repo>/blob/main/companies/acme-example.md

范围说明：链接仅对仓库成员有效

指向私有脑库仓库的托管远程链接，只能由拥有仓库访问权限的人打开。这适用于用户自己的聊天界面；但它不是可分享给外部受众的链接。要分享给外部人员，请改用后备方案链中的 gbrain publish 制品（第 3 步）。

约定

此技能保证：

• 每条报告脑页写入的外发消息都包含链接（或备用形式），且链接就在同一条消息中——用户无需询问。
• 链接通过 git 数据（git ls-files --full-name、git remote get-url origin）机械生成，绝不凭记忆拼凑。
• 推送完成前不会发送托管 URL；发送链接前，必须先完成验证（或取得引用更新的证据）。
• 子 Agent 的转达内容会在发送前改写。
• 页面内交叉引用保持相对路径，以保留链接/反向链接图。
• 路由与 frontmatter 中的规范触发条件一致。
• 保留隐私约定：不出现真实姓名、特定于 fork 的文件系统路径字面值或上游 fork 引用。

输出格式

托管远程服务（已验证）：

已完成 — 已推送。 https://github.com///blob/main/concepts/widget-co-pricing.md

已提交更改（abc1234）：

• concepts/widget-co-pricing.md（编辑）——重写了定价部分

没有托管远程服务（备用步骤 2–3）：

已将 concepts/widget-co-pricing.md 保存到脑知识库仓库中（本地路径 — 此脑知识库没有托管远程服务）。需要可分享的 HTML 渲染版吗？我可以用 gbrain publish 生成并附上文件。

失败时

对于任何 gbrain 错误 code、退出码、[AGENT] 区块或通知区块，请遵循Agent 操作者协议。此技能的具体要求：

• 脑页链接会因页面未提交或未同步而返回 404：说明链接尚未生效，并提供相对于仓库的路径；不要编造托管 URL。
• get_page / gbrain get 对你想链接的 slug 返回 page_not_found：先解析出真实 slug（按标题搜索），再创建链接；绝不要发送猜测的 slug。
• gbrain publish 失败：请提供相对于仓库的路径和范围说明，而不是失效的分享链接。

反模式

• ❌“已提交并推送。”——没有链接。
• ❌“该页面位于 /absolute/local/path/...。”——给出的是本地绝对路径，而不是链接或相对于仓库的备用路径。
• ❌提交后等用户询问链接。
• ❌原样转达含有本地脑知识库路径的子 Agent 结果。
• ❌在推送完成前输出托管 URL（推送完成前这些 URL 会返回 404——先推送，确认引用已更新，再提供链接）。
• ❌将 gbrain publish 的输出当作 URL。它会生成本地 HTML 文件路径；应将其作为可附加的文件提供。
• ❌手动剥除 cwd 前缀来构建相对于仓库的路径。请使用 git ls-files --full-name。
• ❌在脑页内部使用绝对 URL 作为页面间引用——这会破坏关系检索所依赖的链接/反向链接图。
• ❌聊天中使用反引号括起路径，而原本可以提供可点击链接。
• ❌凭记忆猜测或重构 URL。

去重（明确边界）

• skills/publish/SKILL.md — 负责如何生成可分享的 HTML 文档（清理、加密、输出选项）。brain-link-discipline 只决定何时回退到它，并禁止将其输出承诺为 URL。
• skills/_output-rules.md（确定性链接）— 承载跨技能的规范：确定性构造、页面内/消息内的范围划分、回退链。本技能承载每条消息的具体机制：推导、排序、验证、中继重写、批量格式化。
• skills/conventions/brain-first.md — 在查询约定中阐述单行可点击链接原则；本技能则将其扩展到交付消息。
• skills/conventions/subagent-routing.md — 如何将工作路由给子 Agent。本技能在中继边界处增加路径重写义务；subagent-routing 不涉及链接/路径重写。
• skills/citation-fixer/SKILL.md — 修复现有脑页内部的失效引用，与外发消息链接无关。
• skills/reports/SKILL.md — 保存/加载报告页面。当报告交付消息引用脑页时，该消息应遵循本规范；reports 技能本身不包含链接规则。