设计研究

• 1: Goldmark 块属性实测
• 2: 消费站与迁移证据
• 3: OINK 全面审查（2026-08-26）

1 - Goldmark 块属性实测

方法

探针使用一个不带 OINK 模板的最小 Hugo 站点。渲染钩子把上下文字段与 .Attributes 输出为 可见标记。站点开启 Goldmark 块属性、行内与块级数学 passthrough 分隔符，以及为检查原始 HTML 而刻意启用的 unsafe 渲染，并设置 wrapStandAloneImageWithinParagraph: false。

每种源码形态分别用兼容下限版本和当时的当前 Hugo 版本渲染，再逐字节比较相关产物。以下结论 记录平台行为，不涉及视觉样式。

结论

容器边界

Hugo 的 % shortcode delimiter 会把 .Inner 渲染成 Markdown，但模板必须在内部 Markdown 前后各输出一个空行。缺少任一空行时，后续列表可能被当作 HTML block 的字面内容，而不是 Markdown。

把多行 % 容器放进 CommonMark 列表项还有更硬的限制：生成的 HTML 不会随列表内容缩进，列表会在 容器之前闭合，并在容器之后重新开始。因此，当步骤中必须放另一个全量容器时，OINK 仍保留全量 Steps 形态。普通富块、围栏与 < shortcode 不受这一限制。

在相关收集器形态中，嵌套 % shortcode 收到的也是已经渲染好的内部 HTML。需要保留子项原始 Markdown 的收集器应使用 < delimiter，再通过共享的作用域块渲染器处理捕获到的正文。

属性归属

钩子能看到某个属性，并不等于它自动成为公开属性。每个钩子拥有文档明确的白名单。style 与内联 on* 处理器会被拒绝；携带 URL 的值必须经过共享 URL 策略。只有下游 CSS 已属于既有扩展机制的 表面，才保留站点 class。

实验还表明：gallery 列表项中的图片可以被视为块图，却仍不知道父列表带有什么 marker。因此运行时 要么依赖主题显式输出的标记，要么保留一条窄的结构兜底，不能假设图片钩子能看到任意祖先。

边界与验证

这些结果只覆盖 Hugo 0.160.1、0.164.0 与上述 Goldmark 设置。修改设置的站点或未来 Hugo 版本不在 承诺范围内。调整 Hugo 兼容下限时，应先重跑组件、Book、表格、gallery 与 Markdown 输出检查，再更新 这份快照。

2 - 消费站与迁移证据

语料

创作语料盘点扫描了十一个 OINK 消费站点的 content/ 树：共 5,325 个 Markdown 文件，其中 5,293 个带 YAML front matter。样本同时包含单语言英文与中文参考站、双语产品站、发布归档、 自定义落地页，以及独立的 Book 消费站。

盘点刻意测量源码 Markdown，而不是生成后的 HTML。统计项包括 shortcode 调用、代码围栏属性、 callout、表格 marker、原始 HTML、front matter 键、内容类型与站点自有 layout。随后针对五个 长篇内容消费者又做了一轮 Book 专项盘点。

改变设计的结论

证据也否决了若干看起来诱人的新增项：文档站不足以支撑第二套 Landing 系统；Book 站不需要新封面 组件；连载归档不值得增加独立 shell type；远程 API 采集属于站点侧 CI，而不是承诺本地构建的 Hugo 主题。

块与表格证据

针对十一个站点与 Book 消费者的专项盘点共发现 11,484 张 pipe table。只有 11 张已经匹配严格的 Fields 表头词汇，约 874 张属于参考型表格，约 1,300 张属于兼容矩阵。因此 OINK 采用显式 .fields 与 .matrix marker，不按表格形状猜测语义。

同一轮盘点在十一个站点中发现 18 个 Steps 块，它们都使用带标题和富内容的全量形态。平台探针表明， 原生有序列表可以承载其中大多数内容，却不能在列表项内安全容纳另一个全量 % 容器。因此 OINK 保留 两种形态是为了技术能力边界，而不只是书写偏好。

确定性 Book 迁移

三个带日期的干跑 profile 用于证明迁移规则能解释每个被识别的来源，而不编造语义：

每个 profile 都先干跑，只在歧义边界明确后写入；第二次执行变更数为零；随后以警告即失败的模式 构建，并通过渲染后的 kind、编号和锚点检查。公开迁移工具与当前 profile 边界见 创作书籍和 迁移契约。

边界

这些数字不能直接用于产品宣传，也不能当作当前站点清单。重做研究时，需要重新确定仓库清单并生成 新的带日期报告。本公开记录刻意排除了本机路径、未提交内容、私有仓库名称、原始 Agent 对话与生成 构建产物。

3 - OINK 全面审查（2026-08-26）

审查结论

OINK 的主干质量明显高于一般 Hugo 主题：默认路径可构建、双语完整、组件测试广、输出与安全意识强， 真实站点在桌面、移动端、深浅色和无障碍主路径上没有发现普遍性崩坏。当前 main 与远端一致， 主题 CI 和本站 CI 都是绿色；本次重新执行的主题检查、迁移单测、浏览器单测、全站链接、 Playwright 与 axe 也全部通过。

但「全部绿色」不能等价为「契约全部成立」。本次审查发现 4 项 P1、9 项 P2、5 项 P3。 最重要的共同原因是：项目已经建立了一套很强的原则，却仍有若干早期/边缘实现没有接入这套原则； 而现有门禁主要证明已选中的正向场景不回归，不能系统发现配置空间、静态输出和公开文档的语义漂移。

建议在下一个版本标签前至少完成以下四项：

1. 关闭 Swagger UI 默认在线 validator，并用非 localhost 的浏览器请求测试锁定「零隐式外联」；
2. 把所有公开配置和 Landing 数据纳入统一的类型、范围、URL 与 CSS 值验证；
3. 重做 Swagger、Redoc、Asciinema 的 HTML/Print/Markdown/RSS 降级和 runtime gate；
4. 修复生成 Schema，并让公开配置/Front matter 参考重新与当前实现对齐。

基线与方法

审查基线

实际执行的验证

• 31 个主题 checker 全部通过；
• 85 个迁移单测全部通过；
• 38 个主题浏览器运行时单测全部通过；
• 40 个 HTML/Print/Markdown/RSS/LLMS golden 表面通过；
• tests/site 严格 Hugo 构建通过；
• 真实双语站点的 npm test 通过：121/121 中英页面配对、886 个标题 ID、24,860 个站内链接与 3,172 个 fragment 均通过；
• 真实站点的完整 Playwright 套件通过：全站 sitemap axe 扫描、29 个无障碍场景、45 个响应式/ 导航场景、16 个键盘场景、10 个内容组件场景、18 个代码块场景、4 个 PRD5 场景与 5 个主题色场景；
• 额外在 320 CSS px 下人工检查 EN 首页、ZH 配置页、ZH Book 页、OpenAPI/Redoc 页，未发现页面级水平溢出；
• npm audit 对本站 79 个 npm 依赖报告 0 项漏洞；对 VENDOR.json 的 26 个精确 npm 版本调用 OSV Query API 未返回已知公告；
• measure-baseline.py assets --fixture-site 的严格隔离构建通过。

判级

发现摘要

详细发现

F01 — Swagger UI 会隐式联系在线 validator（P1）

证据。 layouts/_shortcodes/swagger.html 初始化 SwaggerUIBundle 时没有声明 validatorUrl: null。随主题内置的 swagger-ui-bundle.js 把默认值设为 https://validator.swagger.io/validator；它只对包含 localhost 或 127.0.0.1 的 spec URL 跳过在线校验。部署到真实域名后，Swagger UI 会创建在线 validator badge，请求参数包含 spec URL。

影响。 这违反「主题自有网络功能默认关闭」「本地优先」「同源 spec 在浏览器中不访问外部服务」三项承诺。 内网站点尤其会把内部主机名/spec 地址暴露给第三方。由于上游特意跳过 localhost，当前所有本地浏览器测试都看不到它。

建议。 初始化时显式写 validatorUrl: null。若未来允许在线 validator，应做成明确 opt-in 的 URL 配置， 走共享 URL 验证并在隐私/CSP 文档中说明。浏览器测试应使用一个非 localhost 的虚拟 origin，拦截全部请求， 断言同源 spec 页面只请求首方资源。

F02 — 非法配置没有统一 warn/fallback，甚至击穿普通预览（P1）

ui-param.html 明确写着「caller validates the type」，但多个 caller 没有验证。最小复现得到：

Landing 的 marquee.rows、capabilities.columns 和 Asciinema 的数字参数也直接调用 int/float， 错误文本会终止模板执行。print.toc、offline_search_max_results 等错误类型则静默改变行为。

影响。 这是对 Diagnostics decision 的直接反例：普通 hugo server 可能整体不可用，而错误输入也可能在 --panicOnWarning 下零告警上线。

建议。 为整数、正整数、范围、成对范围和 CSS grid count 增加共享 validator；先归一化再参与运算或输出。 每个公开键至少需要四态用例：合法站点值、合法 page override、非法普通构建（warn+fallback）、非法严格构建（失败）。 对 min <= max、分页大小 >= 1、列数为合理整数等交叉约束加领域 resolver，不要依赖浏览器吞掉坏 CSS。

F03 — OpenAPI 与 Asciinema 仍是 HTML-only 岛（P1）

Architecture/Components 规定 Markdown/LLMS 不含 td-* 组件标记，Print 静态展开且不依赖交互，RSS 只保留安全静态内容或明确省略。 但当前实现与公开示例表明：

• redoc 在生成 .md 中原样输出 <style>、<div class="td-redoc"> 与 <redoc spec-url=...>；
• swagger 把可执行 inline initializer 直接写在 shortcode 中；
• asciinema 的 .md 输出包含整套 td-asciinema HTML 与 JSON script；
• Asciinema 的 Print 仍加载约 185 KB 的 player JS/CSS，只能碰巧打印某一帧；
• Swagger/Redoc 在 Print 里留下空容器，并仍可能装载 1–2 MB runtime；
• 这些 shortcode 没有进入 Markdown/RSS/Print golden 矩阵。

影响。 Agent 输出被主题 HTML 污染；纸面/EPUB 读者拿到空壳；Print/PDF 负担无意义的大 runtime； Swagger inline script 也破坏 CSP。当前用户文档把这些缺陷写成「输出形态」，等于让 reader guide 与规范契约相互否定。

建议。 三者都先读取 tdOutputFormat：HTML 输出完整组件；Print/Markdown/RSS 输出一个有标题的静态链接、 spec/cast 地址与必要的文字说明，或者明确省略。只有交互 HTML 才设置 capability flag。Swagger initializer 应移入稳定 chunk， Redoc 的样式移入 stylesheet，新增四输出 golden 与 runtime-absence 断言。

F04 — Landing 的 CSS/URL/数值入口没有同一安全边界（P1）

layouts/_partials/landing/sections/hero.html 对 title_size 做了 CSS 长度验证，却把 media.ratio 与 media.max_width 原样拼进字符串，再整体 safeCSS。最小输入：

sections:
  - type: hero
    data:
      title: Probe
      image: /icons/logo.svg
      media:
        ratio: "1fr; background-image: url(https://example.invalid/x)"
        max_width: "240px; color: red"

普通和严格构建均零告警，输出：

style="--td-hero-columns: 1fr; background-image: url(https://example.invalid/x);
       --td-hero-media-max: 240px; color: red;"

Landing 允许把 sections 直接写进 front matter，因此这不是只属于仓库管理员的内部常量。 其它 section 的 columns、rules、宽高、style、icon 与 URL 也各自处理；非法 javascript: 通常被 Go template 变成 #ZgotmplZ，但没有 warning，严格门禁仍通过；字符串列数会变成 ZgotmplZ，某些 int 转换则直接终止构建。

建议。 为 Landing 建立一层 section schema/normalizer：所有类型共享 class、icon、URL、CSS length、grid count、 boolean、enum 解析；section partial 只消费规范化结果。hero.media.ratio 应是两个受限 track 值而不是任意 CSS 片段， max_width 走 CSS length validator。所有 link/action 复用 content/url.html，并给每种 section 一个负向用例。

F05 — 两个配置 URL 面绕过共享策略（P2）

params.ui.page_context_menu.links 经 url-template.html 替换占位符后直接 safeURL； url_latest_version 也被当作「trusted site configuration」直接 safeURL。它们没有检查 scheme、host、空白或 protocol-relative URL。

最小配置可零告警产出：

<a class="td-page-actions__item"
   href="javascript:document.body.dataset.pwned=1;undefined">

点击该 URL 会执行 JavaScript。站点配置本身是高信任输入，因此这不是默认远程攻击面，但它与公开的「safe URL」配置模型不一致， 也让复制来的配置片段拥有不必要的执行能力。

建议。 自定义动作只允许 http/https 与明确支持的站内相对 URL，并复用 content/url.html； 归档版本 URL 也应验证。浏览器 action registry 的二次检查值得保留，但 progressive-enhancement 的 <a> 不能绕过它。

F06 — 生成 Schema 与真实 YAML 不一致（P2）

generate-config-schema.py 的小型 YAML parser 不剥离行尾注释，至少 11 个默认值被生成成字符串，例如：

• print.toc 的默认值是字符串 "true # ..."，不是 boolean true；
• print.section_break_wordcount、section_index_columns、blog_index_columns 变成字符串；
• footer_style、blog_index、typography 的 enum 默认值包含注释正文。

注释关联也会漂移：解释「breadcrumb 没有全站默认」的注释被挂到 section_index；解释 quick_links 的注释被挂到 sidebar_icon_policy；taxonomy icon 注释被挂到 pager_types；本地 chrome 注释被挂到 image_zoom。

Front matter Schema 还会把探测器读到的已移除键 release、upstream_attribution、downstream_modified 暴露给编辑器， 并把 navbar menu 的 Params.columns 误判成 page front matter。--check 只比较「同一个有 bug 的生成器」与已提交产物， 所以会稳定地保持错误。

建议。 不要继续扩展 ad-hoc YAML parser。使用能保留注释的正式 parser，或为默认值/描述建立显式机器元数据标记； scanner 需要区分 page、menu、shortcode 和 legacy detector 上下文。生成测试必须拿 Schema 默认值与 Hugo 实际解析值逐项比对， 并维护「禁止出现在补全中的已移除键」列表。

F07 — 配置与 Front matter 参考不是当前实现的完整参考（P2）

content/docs/customize/config.md 与 content/docs/write/frontmatter.md 都自称「每个主题实际读取的键的唯一完整参考」， 但当前存在多类实质错误：

• 日期默认仍写成长英文日期，而 hugo.yaml 已是 ISO 2006-01-02；
• Blog 只写 none|banner|wash 和 list|cards，遗漏 hero、table、toggle、size、toc_style、toc_taxonomies；
• Front matter 仍把已移除的 release map、release_products、release_group_by_product 当现行 API，遗漏 release_url；
• images: [] 被写成「没有 featured image」，但契约明确 bundle resource discovery 仍继续；
• upstream_modified 被写成新增一行，而现行契约是改变 credit verb，不新增行；
• 大量页面说非法参数「直接失败」，与 warn/fallback decision 混在一起，普通预览与严格发布门禁没有说清；
• Book guide 仍说主题止于 Print HTML，而 v0.7 已发布 BookManifest、EPUB 与 PDF 工具；
• Asciinema/OpenAPI guide 将污染静态输出的现状写成产品契约；
• Features 页仍写 28 个 vendor 依赖，权威清单是 26 个。

中英文在这些旧答案上通常保持一致，所以 translation parity 不会报错。

建议。 先把配置参考与 Front matter 参考作为一次专门的契约迁移处理；从实现/Schema 生成一份可比对的 key inventory， 人工维护语义文字。发布门禁应检查：现行键全部出现、removed 键只出现在迁移章节、enum/default 与 hugo.yaml/resolver 一致。

F08 — Design 树出现互相冲突的权威和未退休提案（P2）

最直接的矛盾是：Shell 契约声明 navbar columns/mega panel 已退役、配置会 warning 并保持单列； Landing 契约却仍声明「Navbar mega-menu columns accept 1–4」。实现与 checker 支持前者。

提案生命周期也没有按自己的规则执行：config-schema 已标记 implemented，仍位于 Active proposals； Book publication 已把 manifest、EPUB、PDF 和 CI 做完大半，却仍以 Draft proposal 与正式 Architecture contract 重复描述； media-convergence 把已实现里程碑和未完成 M4 混在一份原始设计记录中。

建议。 修正 Landing 契约；把已实现的 config-schema 稳定事实移到 Architecture/Decision 后退休提案； Book proposal 只保留尚未完成的 consumer migration 问题，或拆成新的窄提案。Active proposal 中不应存在第二份现行 API。

F09 — OpenAPI 无障碍承诺与测试排除项不一致（P2）

本站 axe 套件明确排除 .td-swagger-ui 和 .td-redoc。注释记录的已知问题包括 Swagger UI 的无名称 server select、 不可键盘访问的 scrollable version stamp，以及 Redoc operation description 的颜色对比度。

OpenAPI guide 却只公开 Swagger 的问题，并把「真正渲染的 Redoc」作为替代；这会让读者误以为 Redoc 满足本站的零违规门禁。

建议。 立即在 EN/ZH guide 中公开两者的真实边界。短期可通过主题 CSS 修复可修的 Redoc contrast， 对 Swagger 的可修 DOM 用 narrow post-render adapter；不能修的上游问题应有版本化 waiver、issue 链接和单独 axe 报告， 而不是把整块 DOM 排除后仍称全站零违规。

F10 — 当前主题不能直接配合严格 CSP（P2）

部署指南说同源资源使 strict CSP 可行，却只列作者 inline script、ECharts callback、analytics、远程 spec/diagram 和 Giscus。 主题自身在普通 Docs 页就输出两段可执行 inline script（颜色首绘与 shell prepaint）和 inline style；Markmap、Swagger、Algolia、 Google CSE 还增加主题自有 inline initializer。项目没有 nonce 参数、hash manifest 或完整的 CSP 示例。

影响。 script-src 'self' 会阻止主题自己的首绘与 shell 状态恢复；style-src 'self' 会阻止主题色、字体角色、Landing 和多个 inline custom property。站点只能加 'unsafe-inline'、自行维护 hash，或覆盖模板；当前文档没有说清。

建议。 把稳定初始化逻辑移到同源外部 chunk，以 data/JSON 传递页面配置；剩余必须 inline 的内容提供可生成的 CSP hash 清单， 或统一 nonce hook。文档应给出「最小核心」「带 Markmap/OpenAPI」「带第三方集成」三套策略，并明确 style-src 需求。

F11 — 浏览器兼容性承诺缺少基线与跨引擎证明（P2）

Playwright CI 只安装 Chromium；仓库和产品文档没有写最低 Chrome/Firefox/Safari 版本。 但实现依赖或增强使用 :has()、dialog、inert、color-mix()、@property、logical properties、 discrete display transition 等新能力。部分功能有 fallback，但没有一个浏览器矩阵证明它们。

RTL 主要依靠源码 marker、少量 JS 单测和一个临时给元素设置 dir=rtl 的几何测试；没有完整 RTL 语言站。 forced-colors 多数只检查 SCSS 中是否出现字符串，没有浏览器 computed-style/交互测试。

建议。 发布一个小而明确的支持矩阵，并至少对核心 shell/导航/内容/对话框跑 Chromium + Firefox + WebKit。 增加一条真正 languageDirection: rtl 的集成配置，以及 forced-colors、reduced-motion、320px、200% zoom 场景。

F12 — 输出安全和 Markdown 门禁没有检查自己宣称的全部表面（P2）

check-output-security.py 对 .md 只匹配 Markdown link 语法，不把其中 raw HTML 送入 HTML scanner； 因此 Redoc/Asciinema 的 <script>、spec-url 与 raw href 不会被发现。它也不检查 style 中的 url()、JSON config 中的 URL， 而 theme fixture 以全局 --third-party 运行，降低了第三方元素检查的区分度。

本站的 check-rendered-markdown.mjs 名字也容易误导：它扫描的是生成 HTML 的文本节点里是否残留 Markdown 标记， 并不读取生成 .md。真正的 md-output golden 只有 15 个页面，未覆盖 OpenAPI/Asciinema。

建议。 将门禁拆成三个明确工具：HTML trust、machine-output purity、rendered-text residue。 .md 中允许的 raw HTML 应有极窄 allowlist；CSS URL、form/action、JSON URL 与非可执行 JSON script 需要分别解析； 每个 public shortcode 至少进入一个 Markdown/Print/RSS 行为用例。

F13 — 两个仓库之间没有自动的候选提交集成门禁（P2）

主题 CI 只对 tests/site 合成夹具运行；文档站 CI 则只测试 go.mod 固定的公开标签。 主题 PR 的真实 EN/ZH/Playwright 验证依赖维护者本地执行 HUGO_MODULE_REPLACEMENTS，两个仓库的变更也无法原子提交。

这次的结果说明两边可以分别全绿，而公开参考仍与实现漂移。现有 release-state 文字区分是正确的，但自动化没有执行 「实现 + owning checker + EN/ZH contract」同一交付规则。

建议。 增加一个只读的跨仓库候选 workflow：主题 PR checkout 当前 SHA，同时 checkout 文档站指定 main SHA， 用临时 module replace 跑 npm test 与关键浏览器套件；反向也让 Design contract PR 指向待验证主题 SHA。 发布仍保持 tag/pin/deploy 分离，但候选提交应有一个可追溯的联合验证结果。

F14 — checker 维护成本和源码耦合过高（P3）

当前 checker 覆盖面值得肯定，但 34 个 check-*.py 中有 546 次 read_text()；多数脚本重复实现 require、临时站点、 写文件、Hugo 命令和错误聚合。大量断言锁定模板/SCSS 的源码拼写、注释附近结构或整文件相等，而不是最终行为。

一部分 helper 又硬编码 theme: oink + --themesDir <repo-parent>，使 checkout/worktree 目录名成为隐藏前提。 项目没有统一的 Python lint/type gate。结果是新增 checker 很快，却更容易出现「门禁全绿但共同盲区没有人拥有」。

建议。 建立共享 fixture builder 和 assertion library；把负向 case 作为表驱动数据； 只给真正的 topology invariant 留源码检查，其余转到解析后的 HTML/JSON/computed style。 测试主题应通过显式 symlink/module replace 装载，不依赖仓库 basename。

F15 — runtime 拆分成功，但基础 CSS/字体仍占主要首访成本（P3）

严格隔离 fixture 基线：

第一方 capability chunk 已经消除了 2^N 组合包，这是正确方向；大第三方 runtime 也按页面隔离。 剩余主要成本来自所有页面都加载的 Bootstrap/主题/Landing CSS 与完整 Font Awesome 分发。

建议。 不要违背现有合同去按模板用量裁剪 Font Awesome。优先测量可独立缓存/按 surface 加载的 Landing、Book、Swagger CSS， 检查真实首访实际加载的 font subset，并给预算建立趋势报告而非武断阈值。

F16 — vendor 可复现，但漏洞与 CI 供应链仍靠人工（P3）

正面证据：VENDOR.json 精确记录 26 个包、56 个 artifact、31 个 license 文件和 tree hash， check-vendor.py 通过；本次 OSV 与 npm audit 均未发现已知漏洞。

缺口：custom manifest 没有进入通用 SBOM/OSV gate，npm audit 也天然看不到这些 vendored 浏览器包； 文档站两个 workflow 通过 curl 下载 Hugo .deb 后直接 sudo dpkg -i，没有校验摘要；Actions 用可移动的 major tag， 主题 CI 的 Python 是浮动 3.x。

建议。 从 VENDOR.json 生成 CycloneDX/SPDX SBOM，增加定期 OSV 扫描；Hugo archive/deb 固定 SHA-256； 高信任 release workflow 的 action 固定 commit SHA；选择明确 Python 版本或建立版本矩阵。

F17 — 设计记录与发行文字的信噪比下降（P3）

CHANGELOG.md 已有 1,768 行，0.7.0 单节约 300 行；Unreleased 用约 20 行解释一次 checker retry。 这些叙事对工程复盘有价值，但升级读者很难快速找到 breaking change、迁移和行为差异。

同时，book_kind/book_part 被契约「认可」并出现在大量内容 front matter，却明确不被模板读取； 它们给作者增加了类似 API 的负担但没有行为。已实现提案仍留在 Active proposals 又放大了重复答案。

建议。 Changelog 保留用户可观察变化、breaking/migration 与修复摘要；长设计故事移到 Blog/Research，并从 changelog 链接。 没有行为的 metadata 要么定义消费者和 schema，要么从公共契约降级为站点自有字段。

F18 — Print isHTML FIXME 已经失真（P3）

hugo.yaml 说「等 Hugo 修复 #14381 前保持 isHTML 未设置」。该 Hugo issue 已于 2026-01-17 修复， 修复进入 OINK 兼容性下限之前的 Hugo 0.155 系列；OINK floor 是 0.160.1。

但在当前主题上简单启用 isHTML: true 仍会产生 page/section/landing print layout missing warnings， 严格构建失败。这说明真实依赖已经从「等待 Hugo alias fix」变成「当前 Print 模板命名依赖 non-HTML lookup 规则」。

建议。 不要直接删除 workaround。先为 HTML-classified Print 补齐 lookup matrix 与 alias/subpath 测试； 若继续保持 false，就更新注释说明当前真实原因，并增加一个测试防止未来维护者依据已关闭 issue 做错误清理。

做得好的地方

• 主题、文档站、发布标签和消费站 pin 被明确区分，没有把本地 replacement 当成发布；
• Hugo floor 0.160.1 与 0.164/0.165 的主题矩阵覆盖扎实；
• 大多数新组件已经遵循 warn/fallback、四输出、共享 URL/attribute policy 与 capability flag；
• 32 个 locale schema 一致，EN/ZH 真实页面、标题 ID、站内链接和窄屏导航有强门禁；
• 搜索、键盘、surface coordinator、页面动作和主题色测试既有单测也有浏览器行为测试；
• vendor license/hash、EPUB/PDF 的路径边界、PDF loopback+CSP 与不可覆盖默认值设计认真；
• 320px 人工复核未发现页面级水平溢出，当前核心视觉质量良好；
• 构建性能很好，第一方 JS 已从组合 bundle 迁移到稳定 capability chunk。

建议修复路线

阶段 0：下一个标签前

1. Swagger 写死 validatorUrl: null，增加 production-origin no-network test；
2. 建立公开参数 inventory，为 F02/F04 中所有字段补 validator 与负向矩阵；
3. 重做 Swagger/Redoc/Asciinema 四输出和 runtime gate；
4. 修复自定义 action/归档版本 URL；
5. 修复 Schema parser/scanner，并重新生成两份 Schema；
6. 同步 EN/ZH Config、Front matter、OpenAPI、Asciinema、Book、Features 与 Landing contract。

阶段 1：契约门禁

1. 为 29 个 shortcode 建立最小 HTML/Print/Markdown/RSS coverage map；
2. 拆分并增强 output trust / machine-output purity 检查；
3. 将 Landing section 输入统一归一化；
4. 外部化 theme-owned inline initializer，发布 CSP 参考；
5. 建立跨仓库候选提交 workflow。

阶段 2：兼容性与结构

1. 加 Firefox/WebKit、真实 RTL、forced-colors、200% zoom；
2. 收敛 Python checker harness 和源码字符串断言；
3. 评估按 surface 拆 CSS 与字体实际请求；
4. 生成 SBOM、定期 OSV、固定 CI 下载摘要；
5. 退休已实现提案并精简 Changelog。

完成判据

• 使用同源 Swagger spec 的生产 origin 除首方资源外无请求；
• 每个公开配置错误在普通构建中 warn+fallback/omit，在严格构建中失败，且不出现 Go template ZgotmplZ；
• 生成 .md 不含 td-*、theme <script>/<style> 或空交互容器；
• Print 不加载 Swagger/Redoc/Asciinema runtime，并给读者可理解的静态替代；
• Schema 默认值类型与 Hugo 实际解析完全一致，removed key 不出现在补全中；
• EN/ZH 配置和 Front matter 参考的 key/enum/default 与实现 inventory 一致；
• 核心 Playwright 在 Chromium、Firefox、WebKit 通过，真实 RTL 与 forced-colors 有行为断言；
• 主题候选 SHA 有一条可追溯的真实文档站联合验证记录。

审查边界

本次没有逐一审查全部消费站仓库、真实生产响应头/CDN 缓存、Firefox/Safari 实机、读屏器， 也没有人工逆向 13 MB minified 第三方源代码。漏洞查询是 2026-08-26 的快照，之后可能变化。 DDIA/TPME 的 EPUB/PDF 真实消费站结果引用现有 CI/契约，本次没有重新发布或部署任何站点。