设计提案与 PRD

• 1: 反向链接与知识图谱
• 2: 媒体收敛
• 3: Agent 批量索引

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

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、严格构建负向用例、浏览器无障碍 与响应式测试，以及真实双语站构建。性能在有代表性的大站上测量，但带日期的原型耗时不能自动成为 永久预算。

待决问题

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

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. 哪些输出兼容名称仍被真实消费站使用？

3 - Agent 批量索引

当前基线

站点可以为 page 与 section 启用 Hugo 的 Markdown 输出，并为 home 启用生成 llms.txt 的 LLMS 输出。OINK 把 shortcode 渲染成语义化 Markdown，保留源码 URL 和语言内 LLMS 索引发现信息，Copy Markdown 也读取同一个 alternative output URL。主题声明输出格式，但不强迫站点选择哪些 outputs。

导航已经存在权威链：有显式 data/docs_nav.json 树时使用它，否则使用内容树与 weight。侧栏、 pager 与已声明 section index 共用这一权威。机器导航输出必须从同一棵树派生，不能再造排序。

目标与非目标

目标：

• 为小型站点可选装配语言内全文包，为大型站点可选按顶层 section 分包；
• 可选发布带版本的导航 JSON，供 Agent 与外部工具使用；
• 复用人工站点的同一 Markdown 页面渲染器、页面纳入规则与导航权威；
• 所有输出仍通过 Hugo output 配置 opt-in；
• 验证链接、语言隔离、media type 与确定性顺序。

非目标：

• 替换每页 Markdown 或 llms.txt；
• 新建 params.oink.* 配置树；
• 在 Hugo 构建期间抓取生成好的 public/ 文件；
• 嵌入私有源码路径、草稿页面或跨语言回退；
• 承诺一个巨型全文包适合所有模型上下文。

全文包

提议的 llms-full.txt 输出拼接每页输出所用的同一份语义化 Markdown。页面之间使用稳定、可见的 分隔符与来源 URL。站点从两种部署形态中选择：

由 Hugo output 配置决定哪些页面获得该格式，而不是由主题参数决定。主题可以提供检查器，报告意图 与实际输出不一致，但不能修改站点输出集合。

全文包在 Hugo 内部通过共享页面渲染 partial 组装，不读取 public/ 中的兄弟产物，也不依赖输出 构建顺序。文件大小作为证据报告；任意阈值不能通过警告让 --panicOnWarning 拒绝原本合法的发布。

导航 JSON

提议的 JSON 包含 schema 版本、语言、根节点与递归有序节点。页面节点包含稳定 ID、标题、HTML URL、 启用时的 Markdown URL、kind/type、weight 与 children。显式外部导航节点只包含标签、URL 与 external kind。

输出遵循渲染侧栏相同的可见性与排序规则，排除 draft、headless resource、隐藏导航项与当前语言 不可用页面，永不序列化本机文件名。

该格式拥有自己的 JSON Schema 与 golden 夹具，并标记为 notAlternative，避免 Hugo 把它广告为 页面级 alternate。

发现信息与输出边界

llms.txt 可以链接已经启用的全文包与导航 JSON。HTML head 继续发现每页 Markdown 和语言内 LLMS 索引，不把每个批量产物塞进每一页。

shortcode、Landing section、Book 目标与交互组件继续使用当前 Markdown 降级。新输出无权增加组件 HTML、脚本、评论、反馈控件或导航 chrome。

验收标准

• EN 与 ZH 输出只包含各自语言的页面和 URL。
• 每个列出的 Markdown URL 都存在；每个导航 URL 都可解析，或明确标记为外部节点。
• 同一根下的顺序与渲染侧栏、pager 一致。
• 固定 Hugo 版本与输入时，相同源码重建得到字节稳定输出。
• 新格式关闭时，HTML、Markdown、Print、RSS 与 LLMS golden 均无回归。
• 大站夹具能证明按 section 分包，而不是为每个嵌套 section 都生成文件。

待决问题

1. 两种全文部署形态是否都需要，还是只按 section 分包更安全？
2. 导航 JSON 应当是 home output，还是由 resource template 支撑的专用内容页？
3. 哪些节点元数据足够稳定，可以进入 schema version 1？
4. 导航 JSON 存在时，llms.txt 是否默认列出它？
5. 检查器应报告哪些体积证据，又不武断执行某个模型上下文上限？