# 反向链接与知识图谱

> 从普通 Hugo 链接推导反向链接、局部与全站图谱的三阶段设计草案。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

> [!WARNING] PRD 草案，尚未实现
> OINK 当前没有 backlink 区块、局部图谱、全站图谱页或 graph 输出格式。提案中的名称和配置在
> 提案被接受、契约发生变化之前都不是公开 API。

## 前提 {#premise}

反向导航与页面连接视图是链接图的属性，不是 `[[wikilink]]` 拼写的属性。Hugo 已经接受普通
Markdown 链接和 `ref` / `relref`。OINK 可以从作者已经在写的内容中派生图谱，无需增加解析器、
Goldmark 扩展或并行创作语法。

首要价值是反向链接，而不是可视化。静态入链列表不需要 JavaScript，在 Print 与 Markdown 中也能
降级。交互图谱应当只是完整列表之上的可选增强。

## 目标与非目标 {#goals-and-non-goals}

目标：

- 每次构建为每种语言派生一份链接索引；
- 在页面上显示确定性的入链；
- 可选显示有界的局部邻接图；
- 可选发布全站视图与机器可读图数据；
- 编辑链接暂时陈旧或不完整时，普通预览仍然可用。

非目标：

- 引入 `[[wikilink]]` 语法；
- 索引外链、`mailto:`、同页锚点或自链接；
- 用 JavaScript 发现正文中已经存在的链接；
- 把可视化变成唯一导航方式；
- 承诺从任意 shortcode 参数或原始 HTML 中完整提取语义图。

## 交付阶段 {#delivery-stages}

| 阶段 | 交付物                       | 运行时                            | 独立价值                           |
| ---- | ---------------------------- | --------------------------------- | ---------------------------------- |
| G1   | 语言内链接索引与反向链接列表 | 无                                | HTML、Print、Markdown 中的反向导航 |
| G2   | 当前页面周围的局部图谱       | 既有 ECharts 加一个小型本地运行时 | 以 G1 为无障碍兜底的空间视图       |
| G3   | 全站图谱页与图数据输出       | 同一运行时                        | 全站探索与机器可读边               |

每个阶段单独验收。G1 不等待 G2，G2 也不会强迫每一页加载图谱代码。

## 提取契约 {#extraction-contract}

提议的索引按语言扫描源码一次，每对来源与目标只记录一条边。它先剥离代码围栏和行内代码，再提取
普通 Markdown 链接与 `ref` / `relref`；随后只解析站内页面，去掉 fragment 以确定页面身份，
排除自链接，并合并重复引用。

实现至少要测试：

- 同一目标的重复链接合并为一条边；
- 围栏与行内代码不产生边；
- 外链、protocol-relative URL、邮件、同页锚点与自链接被排除；
- `ref` 与 `relref` 被纳入；
- 每种语言生成相互独立的图；
- 无法解析的派生边由警告或专项检查报告，但不会让普通 `hugo server` 不可用。

扫描原始源码存在已知遗漏。自定义 shortcode 参数或原始 `<a href>` 中的 URL 可能不会进入图谱。
必须明确记录这种遗漏，不能声称得到完整语义图。

## 反向链接输出 {#backlink-output}

G1 在页尾附近输出一份短小、有序的列表。排序必须确定：先按 section，再按导航 weight、标题，最后
用稳定路径破平。区块使用普通链接与标题，不把内容只藏在 disclosure 中；没有入链时不渲染。

Print 与 Markdown 保留可读列表。除非后续 feed 研究证明反向链接能改善文章订阅而不是制造站点导航
噪音，否则 RSS 省略它。

## 交互图谱边界 {#interactive-graph-boundary}

G2 复用本地内置的 ECharts graph series。当前页面是中心，直接入链与出链邻居组成默认深度。硬性
节点上限防止视图不可读或成本失控。键盘焦点、文字替代、reduced motion、forced colors、窄屏和
Print 都是验收要求，不是后续润色。

JavaScript 或 ECharts 不可用时，G1 仍然完整可见。运行时只在真正渲染图谱的页面加载，并进入既有
feature bundle key，避免不同特性页面在资产缓存中撞车。

## 全站输出 {#global-output}

G3 可以新增专用图谱页与 opt-in JSON 输出。JSON schema 包含版本、语言、节点和带稳定 URL 的有向边，
不暴露本机文件路径或未发布页面。它必须和 G1、G2 使用同一索引，避免三种表示各自漂移。

## 兼容与迁移 {#compatibility-and-migration}

普通 Markdown 写法不变，因此无需内容迁移。配置名称继续待定，直到原型证明最小公开面。所有交互
与全站输出默认关闭；静态反向链接列表可以单独讨论，因为它只是本地导航，不涉及网络与浏览器状态。

## 验收标准 {#acceptance-criteria}

验收需要专项 graph 检查器、提取夹具、HTML/Print/Markdown golden、严格构建负向用例、浏览器无障碍
与响应式测试，以及真实双语站构建。性能在有代表性的大站上测量，但带日期的原型耗时不能自动成为
永久预算。

## 待决问题 {#open-decisions}

1. G1 是 opt-in、opt-out，还是只为选定 shell type 开启？
2. 局部图只暴露一层，还是允许严格限额的第二层？
3. 哪些页面元数据值得进入 graph JSON？
4. 无法解析的启发式边应保持静默并由专项链接检查报告，还是显示去重后的预览警告？
5. 在 G1、G2 获得生产证据前，G3 是否值得新增输出格式？