设计提案与 PRD

• 1: 反向链接与知识图谱
• 2: 媒体收敛

content/docs/design/proposals/<slug>.md
content/docs/design/proposals/<slug>.zh.md

草案提案
    ├── 拒绝或被替代 → 从活动树移除，由 Git 历史保存
    └── 接受
          ├── 实现与归属检查器
          ├── 受影响的中英文契约
          ├── 理由具有长期价值时新增已接受 Design 决策
          └── 相关受众需要时更新变更记录、迁移与用户文档

1 - 反向链接与知识图谱

前提

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

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

目标与非目标

目标：

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

非目标：

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

交付阶段

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

提取契约

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

实现至少要测试：

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

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

反向链接输出

G1 在右栏输出一个 aside 组，与目录、分类标签云并列：目录讲这一页写了什么，反向链接 讲哪些页面指向这一页。该组默认展开，先显示前八条，其余折进原生 disclosure，避免被 大量引用的页面把右栏撑满。开关是站点键 params.ui.backlinks（裸布尔，默认关闭），页面用同名去前缀的 front matter 键 backlinks 覆盖，section 可以 cascade。排序必须确定：按稳定页面路径 排序——它与语言无关、与导航自然同组，且不需要第二个排序权威。该组使用普通链接；没有 入链时不渲染。

无法解析的派生边被静默丢弃并作为已知遗漏记录在案：G1 是本地导航增强，不是链接检查器， 让它替站点报告断链只会制造重复告警。

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

交互图谱边界

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

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

全站输出

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

兼容与迁移

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

验收标准

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

待决问题

G1 的问题已全部决议（见决策日志）。仍然开放、属于 G2/G3 的问题：

1. 局部图只暴露一层，还是允许严格限额的第二层？
2. 哪些页面元数据值得进入 graph JSON？
3. 在 G1、G2 获得生产证据前，G3 是否值得新增输出格式？

决策日志

• 2026-08-19：起草三阶段设计。
• 2026-08-27：决议 G1 并接受，排入 OINK 0.8.0。G1 是 opt-in：站点键 params.ui.backlinks 裸布尔默认关闭，页面覆盖键 backlinks，不按 shell type 区分——策略归站点与页面，不归外壳。排序简化为稳定页面路径单键排序，删去 「section → weight → 标题」的三级链：单一确定性权威已经满足反向导航，多级排序 等于第二个导航权威。无法解析的边静默丢弃并记录为已知遗漏，不产生告警。 G2/G3 与图数据输出继续等待生产证据。
• 2026-08-27：设计评审把这一块从页尾移到右栏。反向链接是页面元数据，与目录成对； 页尾是读者的收尾区——分享、反馈、出处、翻页、评论。右栏这一组同时引入八条上限， 其余收进原生 disclosure。

2 - 媒体收敛

当前基线

正文图片钩子、编号 fig、卡片与 gallery 统一通过 content/image-resolve.html 解析页面资源、 section 资源、全局资产、static 文件与显式远程 URL。栅格资源可以提供固有尺寸与处理后派生图。 HTML Zoom 资格使用 data-td-image-zoom 标记；构建期检测只查找主题自己输出的标记。

独占 Markdown 图片已经可以把题注或 Book 编号与图片处理、链接组合起来。编号图片 figure 共用 td-figure 与 td-book-figure 语义。Landing 媒体经过共享 URL 信任策略；代表图片则刻意使用 排序 resolver，因为它的职责是选择代表图片，而不是渲染一个显式来源。

剩余问题

共享安全边界已经比共享媒体模型更成熟。Landing 媒体仍然拿不到与正文图片相同的页面资源元数据和 处理结果；代表图片选择与显式图片解析返回不同结果形状；部分兼容 class 仍保留在标记中；Book 的 全量 fig 形态也不能表达原生图片钩子的所有处理选项。

因此问题已经不再是“替换七种图片入口”，而是：能否在不抹掉各自语义差异的前提下，让剩余表面共享 一份小型结果契约。

目标与非目标

目标：

• 为 URL、原始 URL、尺寸、替代文字、署名、可处理状态与外部状态定义一个规范化媒体结果形状；
• 在来源语义重合处，让显式正文图片、Landing 媒体与代表图片复用这个形状；
• 继续让 figure 标记与 Zoom 资格分别只有一个归属实现；
• 决定全量 fig 是否需要处理能力，还是要求处理过的编号图使用原生图片形态；
• 只有在完成消费站证据与 release note 后才退役兼容标记。

非目标：

• 增加第三方 lightbox 或远程图片服务；
• 意外把 image Zoom 从 opt-in 改成站点政策；
• 给 gallery 新增题注、序列或轮播模型；
• 把表格、公式、示例等非图片 Book 目标合并进只适用于图片的基类；
• 强迫代表图片排序与显式图片解析完全相同。

提议阶段

M1 — 结果契约

记录正文 resolver 与代表图片 resolver 的返回字段，再把交集提取成一份内部媒体结果契约。代表图片 继续负责来源排序，正文 resolver 继续负责显式来源解析。这是要求字节输出不变的内部重构。

M2 — Landing 资源元数据

允许 Landing 条目中的合格本地资源通过媒体契约解析，获得固有尺寸与相同 URL/安全结论。Landing 数据中显式给出的宽高继续优先。远程与 static 来源仍然合法，但不能伪装成拥有可处理资源元数据。

M3 — 全量 figure 能力决策

从两个答案中明确选择一个：

1. 为全量 fig 的来源形态增加处理参数，并通过同一处理 helper 规范化；或者
2. 处理能力只属于原生 Markdown 图片，把全量 fig 明确定义为任意编号块内容的容器。

实现不能让两个答案各完成一半。两种形态的 Markdown/LLMS 输出必须一致地链接到文档规定的原图 或派生图。

M4 — 兼容标记退役

移除旧图片元素 class 或属性之前，先盘点下游 CSS 与 JavaScript。兼容名称仍被使用时，要么保留一个 明确的版本窗口，要么在同一 release train 中迁移归属站点。

安全、输出与无障碍

• 图片 URL 继续遵守共享 scheme 与远程主机策略。
• 缺少必需替代文字时发出警告，且只在现行契约允许处渲染装饰性回退。
• 宽高不能声称 SVG、static 文件或远程来源没有提供的元数据。
• 带链接的图片不是 Zoom 目标；运行时保留 dialog 焦点、键盘关闭、reduced motion 与窄屏约束。
• Print、Markdown、RSS 与 LLMS 去掉交互标记，同时保留目标图片、题注、署名、编号与链接。

验收标准

每个阶段分别拥有 HTML 与 Markdown 字节级证据、正文与 Landing resolver 测试、URL/安全检查、图片处理 测试、Book 目标、gallery/Zoom 浏览器测试，以及真实站中英文窄屏审查。只有 M3 的能力选择明确后， 提案才能被接受。

待决问题

1. 一份共享结果结构是否足够，还是共享更底层的 URL/资源记录会让 resolver 归属更清晰？
2. Landing 应消费资源署名，还是只消费尺寸与 URL？
3. 原生图片已经能组合编号、题注、链接和处理后，全量 fig 处理能力是否仍有真实消费需求？
4. 哪些输出兼容名称仍被真实消费站使用？