设计与开发

• 1: 架构契约
• 2: 组件契约
• 3: 外壳与导航契约
• 4: 落地页契约
• 5: OINK 迁移边界
• 6: 设计决策
  • 6.1: 警告与安全回退
  • 6.2: 配置模型
  • 6.3: Markdown 优先创作
  • 6.4: 生成式配置 Schema
  • 6.5: 可选 CLI 与结果契约
  • 6.6: Paper 与 Slate 视觉预设
• 7: 设计研究
  • 7.1: Goldmark 块属性实测
  • 7.2: Ink 与 Terminal 实验，2026-10-05
  • 7.3: OINK 1.2 发布前审查，2026-10-05
  • 7.4: 视觉预设验收，2026-10-05
  • 7.5: 消费站与迁移证据
  • 7.6: OINK 全面审查（2026-08-26）
  • 7.7: 社区 Issue 与 PR 调研，2026-09-19
  • 7.8: OINK 1.1 发布审查，2026-09-20
  • 7.9: 2026-10-03 CLI 维护验收
  • 7.10: 2026-09-29 CLI 验收快照
• 8: 设计提案与 PRD
  • 8.1: 反向链接与知识图谱
  • 8.2: 媒体收敛
  • 8.3: OINK CLI 与下一阶段产品路线
  • 8.4: OINK CLI 文档维护路线图
  • 8.5: 视觉预设与外观切换

1 - 架构契约

仓库与装配

仓库根目录是一个完整的 Hugo 模块与主题，不是站点，也不是 npm workspace。 Hugo Extended 负责编译 SCSS 与模板。浏览器运行时与第三方资源都已提交到仓库， 因此普通构建不会访问网络。公开的双语文档、示例与浏览器测试位于同级的 oink.pgsty.com 仓库；主题仓库只在 tests/site/ 中保留范围明确的内部回归 夹具，不再维护独立的公开示例面。

生成的 public/ 与 resources/ 目录绝不是源文件。随主题内置的运行时、字体 家族与 Font Awesome 字形定义属于受支持的发行内容，并非待清理的死代码； VENDOR.json 与 bin/check-vendor.py 固定其完整性。OINK 发布完整的受支持 Font Awesome 发行包，因为用户编写的内容可能使用主题模板本身没有引用的图标。

Font Awesome 官方编译 CSS 作为一份稳定、带指纹的 vendor 样式表发布，并排在由 主题与消费站 SCSS 编译出的指纹 main.css 之前。站点样式的普通修改不会再让图标 发行包失效，同时常规层叠顺序仍允许站点覆盖它。KaTeX、DocSearch、Swagger 与 Asciinema 等能力样式继续保持独立，只在实际使用时加载。内容指纹使不可变 URL 成为 可能；HTTP 缓存响应头属于部署宿主，而不是 Hugo 主题的职责。

Hugo 类型 docs、book、blog 与 swagger 选择阅读外壳； params.ui.shell_types 可以增加类型。落地页使用 layout: landing。OINK 没有 article 类型或第二套博客外壳；沉浸式页面只是外壳契约 定义的一种博客展示方式。

layouts/_partials/shell/config.html 解析共享外壳事实。布局必须先通过 content/render.html 渲染，再执行 scripts.html，因为渲染钩子与 shortcode 会在 Page Store 中登记能力标志。覆盖时应选择范围最窄的 partial；若合并会改变 Hugo 的查找优先级，即使几个基础模板看起来相似，也应保持分离。

配置与诊断

主题策略位于 params.ui.*；comments.giscus、plantuml、drawio 等包含多项 设置的集成保留在顶层。布尔功能直接使用布尔值，除非它还包含多项设置。页面级 覆盖会去掉 ui. 前缀：params.ui.image_zoom 对应 image_zoom，front matter 中绝不嵌套 ui map。hugo.yaml 声明公开默认值；对应的解析器与检查器定义 任何可选配置的结构或范围。

无效输入遵循同一条规则：警告中写明输入值、允许的结构与安全回退，然后使用该 回退，或省略不安全的功能。普通 hugo server 因而仍可使用，而所有发布门禁都 使用 --panicOnWarning。主题绝不调用 errorf，check-params.py 会强制守住 这条边界。不要为无法到达的状态增加臆测式校验。

OINK 没有通用的键名重命名注册表。仍需给出迁移诊断的过渡，应在所属解析器中 添加针对性警告，并配严格的反向测试；已经移除的键绝不能作为兼容路径继续读取。

可能联网的功能必须显式启用，并以关闭方式降级。PlantUML 需要 plantuml.svg_image_url，Draw.io 需要 drawio.drawio_server，Algolia 需要 appId、apiKey 与 indexName；配置不完整时发出警告，而且不产生网络请求。 Draw.io 只在渲染内容含 PNG 或 SVG 候选图片时加载，并且每个不同的图片 URL 只检查一次。 图表端点必须是字符串，内容为带主机的 HTTP(S) URL 或同站路径。不支持的协议、 省略协议的 URL、反斜杠、空白字符及缺少路径的同站引用都会告警，并在选择运行时前关闭该集成。

界面本地化

OINK 为 google/docsy@64f51c5 中现有的 31 个 locale 文件名提供原生界面文本，并额外保留通用 zh 作为简体中文 默认值：

ar az bg bn de en es et fa fi fr he hi hu it ja ko nl no oc pl pt-br ro ru
sr-cyrl sr-latn sv tr uk zh-cn zh-tw

这是一项兼容范围，不代表运行时依赖 Docsy，也不声称消费站点编写的正文已经翻译。 Docsy 以后增加的 locale 不会自动成为 OINK 支持项；它必须先补齐完整的 OINK 词条，并接受与现有语言相同的审校。

i18n/en.yaml 管理 194 条消息的 schema。OINK 的 32 份语言包都必须拥有完全相同 的消息集与原生界面文本；只有经过审查的产品名、标点、通行缩写或目标语言真实 同形词可以与英文保持相同，不再生成整段英文 fallback。zh 与 zh-cn 使用简体中文， zh-tw 使用繁体中文。

在兼容下限 Hugo 0.160.x 上，如果同时存在地区化的中文语言包，作为非默认语言的 通用 zh 语言键必须显式设置具体的 locale: zh-CN；从 Hugo 0.161 起，该配置也能 解析裸 locale: zh。这项约束只影响语言配置，不改变语言包文件名 i18n/zh.yaml。

%s、{count}、{{ .Count }} 等运行时占位符可以移到符合目标语言语法的位置， 但字节内容必须保持不变。取值可以是字符串或 Hugo 复数消息映射。复数映射使用该 语言支持的类别（zero、one、two、few、many、other），必须包含 other， 每种形式都是包含相同占位符的字符串。语言包不得包含隐藏的双向文本控制符； 阿拉伯语、波斯语和希伯来语的方向仍由消费站点的语言设置（direction: rtl） 决定，不得把方向字符塞进译文。 bin/check-i18n.py 会检查 locale 集合、schema、取值类型、占位符、方向控制符， 以及少量已审查的英文本地同形词。因此增加可见字符串时，必须在同一变更中为每份 语言包提供译文，不能再运行 fallback 生成器。

特色图片

Hugo 的 images 是唯一的创作 API；params.images 只作为全站社交卡片回退。

images: [] 会清除显式值或 cascade 继承值，但不会禁止发现页面包资源。只把解析 到的第一张图片作为代表图。Hugo 可以裁剪本地可处理的位图；SVG、static 与远程 资源仍然有效，只是不能执行 Hugo 图片操作。

featured-image-resolve.html 统一决定来源优先级与相对、绝对 URL。页面自己的 显式 images 优先于页面包资源，页面包资源优先于继承的 cascade 图片；显式值与 继承值恰好相同时也遵守此顺序。有源文件的页面通过原始 front matter 判断是否显式 声明，由 Hugo 解析 YAML、TOML 或 JSON；没有源文件的生成页面将解析后的 images 视为显式值。列表缩略图、Open Graph/Twitter/schema 帮助模板、作者头像、Pinterest 图片与博客展示都消费同一个决定。

params.ui.featured_image 只用于博客，默认值为 none；页面或 cascade 可用 front matter 覆盖。banner 在单页标题上方渲染图片，wash 用图片给页头着色， hero 在单页与分区索引上把图片绘制为外壳背景。缺少图片或使用非 HTML 输出时 不渲染图片。

输出与运行时

每个基础模板都会设置 Page.Store.tdOutputFormat：

各输出格式按既定顺序执行；可变格式状态并不存在跨格式竞态。但在 Print 内，Hugo 可能并行渲染同一 Book 页面与相互重叠的聚合。因此每页由一个缓存 coordinator 按 固定顺序生成普通与整书两种变体，各调用方只选择自己需要的形态。普通 Print 保留 页面局部标题与带路由的 xref URL；Book 聚合保留带命名空间的标题与文档内 xref。

站点自行选择是否启用自定义输出；OINK 不会强制生成昂贵的整书聚合。HTML 加载 共享操作层、核心层，以及由页面 flag 选择的稳定第一方能力分片。需要模板化的能力 每种语言至多发布一份；flag 只决定引用哪些 script tag，绝不再生成新的组合 bundle。 Print 保留操作层，并且只加载渲染打印功能所需的运行时。大型第三方 UMD 文件保持 独立；未使用的功能运行时不会出现。

顶层 section 在自己 _index front matter 的 outputs 中列出 LLMSFULL 才会启用它， 主题绝不替站点把它加进输出集合。逐页 Markdown 与全文包由同一个渲染器产出，因此全文包 就是那份语义 Markdown（同样不含 td- 组件标记）按侧栏与 pager 的阅读顺序拼接。在顶层 之下启用会告警且不产出任何文件，普通构建仍然可用，而 --panicOnWarning 会拦住发布。

站点在 outputs.home 中启用 NAVJSON，为每种语言在语言根下发布一份 navigation.json。 它序列化侧栏与 pager 所读的同一条权威链：存在显式 data/docs_nav.json 树时用它，否则用 带 weight 的内容树。数组顺序就是契约，weight 绝不序列化，该输出标记为 notAlternative。 schema/nav.v1.schema.json 为该格式提供版本，它是手写的契约产物，随模板与检查器一同修改， 不受生成式配置 Schema 漂移门禁管辖。两种输出默认关闭，都不启用的站点构建结果逐字节不变； bin/check-agent-indexes.py 是它们的归属检查器。

只有 Book 根在 outputs 中明确列出 BookManifest 时才会生成它。它引用该 Book 既有的逐页 Markdown，并记录派生出的页面顺序、标题、编号目标与 xref；主题不会在 其中猜测出版元数据，它也不是可分发的电子书。

主题仓库提供 bin/book-epub.py 与 bin/book-pdf.py 作为显式出版步骤，并用 bin/check-book-epub.py 与 bin/check-book-pdf.py 承担产物门禁。EPUB 打包器组合 BookManifest 与同一份整书 Print HTML，消费站另行传入出版 metadata；PDF runner 只在临时回环地址提供该 Print 产物，通过 script-src 'none' 内容安全策略调用显式指定的 Chrome/Chromium 二进制，输出带 CSS 页码的 A4 页面。两种工具都会拒绝缺失资源或越出构建树的资源；网络资源 与覆盖已有输出分别需要独立的显式开关。网络 opt-in 只允许被动 HTTP(S) 媒体，远程脚本与 本地文件协议仍属非法。EPUB metadata 文件中的相对资源以该文件所在目录为基准，不依赖 调用者的工作目录。普通 Hugo 构建不会执行出版工作；PDF 仍从 Print 派生，而不是另一种 模板输出。

PDF 服务还会应用 CSP sandbox、拒绝 meta refresh 导航，并拒绝指向构建树以外的 符号链接。没有网络 opt-in 时，图片与媒体请求仅限回环同源地址和 data URL， CSS 或 SVG 发起的请求也受此限制。

性能规则如下：

• 若站点级资源或 partialCached 结果可以承担工作，不要为每一页遍历 .Site.Pages；
• .Content 只渲染一次，完成后再读取 Page Store 标志；
• 直接输出正确标记，不要扫描 DOM 后再修复；
• 浏览器工作按资源 URL 分组，而不是按 DOM 实例重复；
• 成本显著的普通输出应保持选择启用；
• 默认不输出 Speculation Rules：必须先由一个明确的生产消费站用可回滚的 moderate 实验测量 Sec-Purpose: prefetch 请求、实际命中导航、传输字节与 CSP 影响；
• 校验确实可达的作者输入，不校验假想的内部状态。

bin/measure-baseline.py 测量构建时间、输出体积、bundle 数量与 shortcode 密度。

信任边界、CSS 与无障碍

作者可以启用 Goldmark unsafe，但配置与组件参数不能视作原始 HTML。共享属性 策略使用允许清单、校验 class token、放行 data-* 与 aria-*，并在丢弃 style、srcdoc、on*、保留属性与未知属性时发出警告。需要本地 URL 或明确 绝对 URL 时，URL 帮助模板会拒绝危险协议与协议相对 URL。公开 API 承诺支持的 远程 URL 仍然可用，但构建时绝不抓取它们。

主题输出使用 td- class、data-td-* 属性与 --td-* 自定义属性；.steps、 .cards、.full-width 等作者标记保持无前缀。CSS 支持 RTL、打印、强制颜色、 减少动画、超长 token 与窄视口。主题拥有的装饰图标带 aria-hidden；只有包含 任务列表或原始 Font Awesome 元素的页面才加载作者内容无障碍修复。

阅读容器区分指针聚焦与键盘导航。由指针聚焦的 main 区域、表格滚动区或代码 pre 不会仅因读者随后按键而出现边框；Tab、失焦或新的非指针聚焦会清除这项豁免。普通控件 保留自己的焦点样式，滚动容器保留 tabindex，跳过导航的目标在标题附近显示局部边框， 不再包围整篇文章。强制颜色模式保留键盘提示，不使用全局焦点边框重置。

字体角色为 ui、body、heading、code、display、meta、brand 与 print， 通过 --td-*-font-family 暴露。ui 是主字体：body 经它解析，heading 又经 body 解析，因此赋一次值即同时移动界面、正文与标题。params.ui.typography 可取 technical 或 system；两者编译到同一份样式表，不加载运行时。旧 Bootstrap/Docsy Sass 变量继续为这些角色提供初值。

params.ui.fonts 让配置层触达同一组角色，供不愿挂载 SCSS 或新增样式表的站点 使用。它只写字体族名，绝不加载字体文件：所写字体族必须是读者已有的，或站点 自己用 @font-face 声明过的，这也让该键留在网络契约之外。取值只放行纯粹的 字体族语法，输出的 :root 块由匹配到的片段重新拼装；未知角色或不安全取值只 告警并单独丢弃。该块在样式表之后渲染，正是这一点让作者字体在同等优先级下压 过预设。外壳读站点的字体，不自带字体：Book 的编号与题注用正文字体，而非某种 技术字体。

强调色按角色拆开。强调文字（链接、外链、行内代码）跟随 Bootstrap 链接 族与 --bs-code-color，主题色永不重声明它们；行内代码随视觉预设变化：Slate 保留胭脂红明暗对，Paper 使用墨色文字与淡底， 使一页密集的标识符读成「代码与正文」而非「代码与链接」。强调底（选中行、 指针划过导航行时那层更灰的底、hover 淡铺、目录药丸与轨道光点、徽章 hover、 卡片 hover 时的外边、分享按钮 hover 时的实心底、文本选中、焦点环）跟随 --td-accent、--td-accent-rgb 与 --td-accent-hover，它们默认取链接族，也是 params.ui.theme_color 唯一注入的属性。属于外壳而非正文的文字同样跟随它们： 视口正停在其上的目录锚点、以及指针或键盘焦点落在其上的 Book 章节小标题， 按分区颜色点亮，而不是链接蓝。theme_color 与 theme_color_dark 取 #rgb/#rrggbb；front matter 与分区 cascade 覆盖站点值。未配置的站点不注入 任何内容。解析失败的值告警并保留默认配色。解析成功但在主题自身画布上低于 4.5:1 的颜色，带可抑制 id 告警并照常生效：该检查是建议性的，只有解析失败才丢弃颜色。 亮色是主键：没有有效 theme_color 的 theme_color_dark 告警并被忽略，一页要么 两种模式都着色，要么都不着色。省略暗色一半时，向白按 4% 步进提亮，直到在暗色画布 上达到 4.5:1。注入的每个字节 都由解析出的整数通道格式化，绝不来自作者文本。同一个解析器同时回答 head 注入块 与侧栏根切换器的「这一页是什么颜色」。

视觉预设

OINK 1.2.0 默认使用 Paper。params.ui.preset 接受 paper、slate，以及显式 选择的实验预设 ink、terminal；非法值与保留名称（folio、canvas）告警并回退到 paper。params.ui.preset_menu 默认 false；true 提供 Paper、Slate 与站点默认值， 列表指定可选项并可显式开启实验。列表必须包含站点默认值，缺失时告警并补入。不支持页面级预设。

Hugo 为所有文档根元素输出 data-td-preset 与 data-td-site-preset，包括 404 和打印输出。开启读者选择时，head 内联脚本在 CSS 加载前校验 td-preset。选择 带默认标记的预设会删除该存储键。非法存储值被清除；存储被禁用时，控件仍可在当前 页面使用，并显示无法持久化的提示。storage 事件同步标签页，td-preset-change 携带 {preset, previous, stored}。明暗状态独立使用 data-bs-theme、 td-color-theme 与 td-theme-change。浏览器栏颜色跟随实际明暗和预设。禁用 JavaScript 时显示站点默认的浅色预设；外观控件需要 JavaScript。

四套预设编入同一个样式表。Slate 保留 v1.1.0 的基础色板选择器与值。Paper 调整 配色和少量组件规则，不改变外壳列宽、断点或全局间距。Paper 深色块重声明浅色块的 每个色板 token，并覆盖嵌套深色区域。字体角色保持同等选择器优先级，顺序为预设、 typography: system、head 输出的 params.ui.fonts；站点的 _styles_project.scss 仍在最后。brand 单独控制字标。Paper 使用本地 IBM Plex Sans， Slate 保留 Inter；两者的字标保留 Chakra Petch，代码保留 IBM Plex Mono。 系统排版模式不请求内置文字字体，除非站点显式覆盖角色。没有新增外部字体请求。 Ink 统一使用 Inter，配合红色标记、正文链接下划线、直角与无阴影。Terminal 使用 等宽界面和标题、Plex Sans 正文、青色链接、琥珀强调、2 px 圆角与无阴影；仅压紧 桌面导航，保留正文行长与手机触控目标。CSS 标题标记使用空的无障碍替代文字， 不支持的浏览器省略标记。显式 fonts.ui 仍控制主字体，除非设置了有效的 fonts.body。参见实验记录。

Giscus 自动色板同时跟随风格与明暗；显式主题或浅深色样式表配置仍优先。打印使用 当前预设的浅色配色与白纸背景，即使屏幕为深色。Mermaid 与 ECharts 继续只跟随 明暗，API 组件保留供应商色板。参见已接受决策 与本地验收记录。

发布状态

源码完成、本地验证、提交、打标签、推送、消费站点固定版本、部署与生产一致是彼此 独立的状态。一次本地 Hugo 构建只能证明本地验证通过。

2 - 组件契约

教程与完整示例位于面向读者的组件专栏。本页定义这些 指南所依赖的 API 与行为。

创作模型

一个区块加属性便能表达组件时，使用普通 Markdown；需要复合正文或 Markdown 无法携带的事实时，使用 shortcode。OINK 没有并行的组件注册表。原生形态要求：

markup:
  goldmark:
    renderer: { unsafe: true }
    parser:
      wrapStandAloneImageWithinParagraph: false
      attribute: { block: true }

只有 {{%/* steps */%}} 使用百分号分隔符，因为它的正文属于页面大纲；其它 shortcode 一律使用尖括号分隔符。复合正文通过 content/render-block.html 处理，并使用唯一的 ID 作用域。Shortcode 与组件参数中的 caption、label、title 和 name 是纯文本，Markdown 应放在正文里。落地页叙述字段遵循自己的契约。图标 由一对 Font Awesome class 表示。组件暴露安全的 class 与属性，不接受任意颜色 或内联样式。

公共 API

OINK 有 29 个 shortcode：

• 核心：tabs、tab、steps、cards、card、fields、field、include、 kbd、badge、param、comment、contributors、asciinema；
• Book：fig、tbl、eq、eg、xref、book-toc、book-figures、 book-tables、book-equations、book-examples；
• 发布：release-card、release-assets、download；
• OpenAPI：swagger、redoc。

校验

无效的作者输入遵循架构契约：发出警告，使用文档 规定的安全回退或省略组件，再由 --panicOnWarning 在发布门禁中把同一条诊断 变为致命错误。命名参数与位置参数不能混用。Book 目标 ID 匹配 [A-Za-z][A-Za-z0-9_.:-]*，Book 编号匹配 [0-9A-Za-z.-]+，class 必须通过 token 校验。渲染钩子与 shortcode 目标共享同一个页面注册表，因此冲突不会生成 重复的输出 ID。

URL 使用 content/url.html；不允许原始反斜杠，因为浏览器可能将其解释为 URL 分隔符。图片依次从页面资源、分区资源、全局 assets、static 或显式远程 URL 中解析。本地位图带固有尺寸；SVG、static 与远程来源仍然有效， 但不能执行 Hugo 图片操作。 资源元数据 alt 必须是字符串；无效值会告警并被忽略，保留正文填写的替代文本。

组件行为

提示块与标签页

提示块类型包括 note、tip、important、warning、caution、success、 danger、question、example、quote 与 details；- 表示初始折叠，+ 表示初始展开。未知类型渲染为保留原标记的普通块引用，不依赖 JavaScript。

只有连续且区块类型相同的相邻标签页才会分组。group 启用 #<group>-<value> hash 与 td-tabs:v1:<group> 存储键；未分组标签页两者都不用。 HTML 在 JavaScript 运行前暴露所有面板，打印输出展开面板，Markdown 保留作者 源文，RSS 接收渲染后的文本摘要。完整形态支持任意 Markdown；tab.label 必填， 父级存在 group 时 value 才严格必填，孤立的 tab 会警告且不渲染。

步骤、卡片、参数表与表格

原生步骤接受普通区块内容。只有某一步必须包含百分号容器时才使用 shortcode。 原生卡片是链接列表；完整形态增加正文、徽章、图标与图片。原生参数表把第一列 映射为名称、最后一列映射为描述，中间列由 meta= 或表头映射；完整形态允许 区块描述。card 与 field 只能放在各自的父容器中。

参数锚点为 field-<name>，名称转小写，连续标点折叠为连字符，因此 params.ui.typography 变成 field-params-ui-typography。重复锚点追加位置后缀。

表格渲染钩子负责响应式包装与 caption。.matrix 把第一列变为行表头； .full-width 加宽普通表格或矩阵表格。.fields 不能与 matrix、full-width、 编号或标签页组合；编号与标签页也互斥。

图片、画廊、FileTree 与围栏

Markdown 图片钩子是普通图片 API。行内图片保持行内；块图片带 caption 或 num 时变为 figure。图片处理只属于这一原生形态：完整 fig 源形态是编号容器，其参数表 刻意不含 command/options，需要处理的编号图片写成带 num 的原生块图片。 允许的图片属性包括 id、num、caption、width、height、 link、command 与 options，以及共享安全属性。command 与 options 必须同时 出现，并对可处理的本地资源调用 Hugo Fit、Resize、Fill 或 Crop。普通 链接图片使用 Markdown 语法，因此 link 属性要求同时有 caption 或编号。链接 图片与装饰图片不加载缩放。

缩放按钮通过 ARIA 无障碍名称保留图片的 alt 与本地化预览操作，不向正文插入辅助 文字。复制纯文本或富文本 HTML 时，即使编辑器移除主题样式，也不得额外带入 预览提示；作者原有的图片与图注保持不变。资源 metadata 中的 alt 必须是字符串； 无效值会告警并被忽略，保留正文中编写的图片 alt。 Draw.io 与图片缩放共用一张图片时，编辑与缩放是同级的独立按钮。编辑入口支持 键盘访问，并在触摸设备和强制颜色模式下保持可见。

画廊每行接受一张 Markdown 图片，可带描述、链接与 class。FileTree 接受缩进、 - name、可选 /、注释，以及经过校验的 icon、tone、open、type 属性。Markdown 保留作者源文；打印输出渲染展开的静态图片与文件树。

所有代码高亮都使用 Chroma。通用围栏属性包括 title、copy、wrap、 collapse、label、id、行选项、标签页，以及 Book 的 num/caption。复制 操作返回作者源文。Mermaid 色板按明暗切换，与视觉预设独立；默认深色连线标签 背景使用 #404040，使标签文字达到 AA 对比度。显式 params.mermaid.themeVariables 配置仍然优先。

ECharts 输入是声明式 JSON/YAML；回调使用 window.OinkEchartsFunctions 中的 $fn:<name>，绝不执行嵌入脚本。

数学公式使用 Hugo 构建时生成的 KaTeX 产物和本地 CSS，不加载浏览器数学运行时。 共享渲染器在 HTML 和 Print 中将 KaTeX 0.18 之前的类名统一为本地样式支持的类名， 保留 Hugo 0.160.1 兼容下限、MathML 与作者的 TeX 源文。Markmap 使用与样式配套的 本地 KaTeX 运行时。 窄屏中，编号公式的标题在阅读列内换行，长标题不得撑宽整页。

Swagger 与 Redoc 接受 HTTP(S) 规范 URL 或以 static/ 为根的路径，都不解析页面 资源。Redoc 将开头有无斜杠视为等价，并把本地路径与 baseURL 拼接。只有 HTML 输出可交互；Print、Markdown 与 RSS 输出静态规范链接。

Book

book 类型扩展 docs 外壳，并遵循内容树或 data/docs_nav.json。book_number、 book_part、book_kind 与 book_status 是展示元数据，不改变 Hugo 发布状态。

带编号的类型为 fig、tbl、eq 与 eg，默认 ID 是 <kind>-<num>。eg 需要 caption；不带 num 的 eq 是无编号展示公式。xref 要么准确指定一种类型 并可附带 page/anchor，要么指定一个 anchor 和显式文字。带编号的示例是一个 完整的边框正文与 caption。

脚注属于页面文档。原生编号表格与围栏会让脚注留在页面里。Shortcode 正文是独立 的 Goldmark 文档，因此 tbl、eg、fig、card、tab、field 或 include 中的脚注引用会警告并保持字面形式；该检查忽略代码形态的文本。

book-toc 按 1–3 层导航顺序生成目录；四个 book-* 索引各自收集一种目标。 单页 Print 与普通 HTML 保持完全相同的普通标题与脚注 ID。只有多页分区 Print 与整书 Print 会改写跨页链接，并给这些页面局部标题与脚注增加命名 空间，避免聚合后冲突；显式目标 ID 保持不变。消费站点自行选择是否启用这些 潜在成本较高的聚合输出。

发布与下载

发布 front matter 使用一个 https://github.com/<owner>/<repo>/releases/tag/<tag> 形态的 release_url；owner、 项目与 tag 来自 URL，日期来自页面。构建不会抓取远程发布状态。已经移除的 release map、release_products 与 release_group_by_product 会警告并给出 替代项，它们不是兼容路径。分区索引列出所有页面；能解析时使用 project tag， 否则使用页面标题。

校验和可以接受规范行，也可以接受一个源资源，两者不能同时提供；文件名不能是 路径。HTML 增加本地复制功能，静态输出暴露完整 hash。

下载使用 data/download/<key>.yaml。channel 可取 rolling 或 pinned；只有 pinned URL 与命令会插值 ${version} 和 ${tag}。发布前，rolling channel 保持 可用，pinned channel 显示 pending。Markdown 渲染完整 channel 列表；RSS 省略 该组件。

验证

共享输出规则见架构契约，例外随各组件定义。 Markdown 与 RSS 不设置浏览器运行时标志；Print 只保留渲染打印功能需要的标志。 源码检查覆盖参数、渲染钩子策略、运行时隔离与迁移；输出检查比较 HTML、Print、 Markdown、RSS 与 LLMS golden；浏览器测试覆盖交互界面。迁移行为见 迁移边界。

3 - 外壳与导航契约

权威来源与导航

任何功能都不能引入另一套菜单或页面树。菜单只允许一层子项交互；更深层级会警告， 并平铺到带链接的分组标题下。外部链接使用 target="_blank" rel="noopener noreferrer"；内部链接保持语言与子路径感知。

顶部导航栏的桌面视图与抽屉视图投影同一棵树，每个下拉面板都是一列宽度适中的 “图标 + 标题"行——mega 面板与其 columns 菜单参数已退役，配置 columns 会发出警告并保持单列。菜单描述只是配置数据，不再渲染。链接树在任何宽度都保持居中： lg 以上是文字链接，之下收缩为图标链接。lg 与 md 之间，右端保留搜索、版本、 语言、主题与 GitHub，没有菜单按钮；md 以下外观入口保留在搜索与抽屉入口旁，版本、语言与 GitHub 移入底栏工具组，此时首页 与显式 Landing 页在搜索旁增加一枚抽屉入口，展开完整的带标签菜单树。带侧栏的外壳页面 在这个位置打开自己的侧栏抽屉；从 md 起均不显示抽屉按钮。语言链接指向页面译文，缺少译文时 指向对应语言首页；多个语言共享主机与 base path 时保持相对链接，只有语言拥有 独立 baseURL 时才变成绝对链接；hreflang 始终使用绝对链接，而且只列出真实译文， 不把切换器提供的语言首页回退当成译文。博客分页使用每一页自己的 canonical URL； 后续分页不输出跨语言 alternate，因为不同语言归档的分页边界未必相同。 navbar_autohide 从 768px 起只对精细指针生效，绝不作用于触控或抽屉宽度； 隐藏的导航栏不交还占位：两种状态下布局都保留导航栏横带，固定顶栏正好占满这条 横带、下边框画在带内，显现时原地淡入、不遮挡静止内容，hero 页面忽略该策略、 保留自己的叠加导航栏。首页与 hero 页面共用同一套柔和边界：导航栏不画下边框、 滚动时不投阴影，改由栏下一小段渐隐过渡收束边缘。

侧栏与翻页共享同一个根和顺序。manual_link、build.render: link、分隔行、 隐藏节点与占位节点保留各自已定义的语义。sidebar_icon_policy 可取默认的 all、 groups 或 none；图标是一对 Font Awesome class。无效策略遵循共享的警告与 回退契约。达到 sidebar_cache_limit 后，两种 walker 只有在语言、导航根与实际 影响输出的有效设置均相同时才复用中性标记。没有 JavaScript 时这份标记仍然可见； 普通外壳运行时只补上 active 路径。会输出 sidebar_headings 的 Book 页面保持页面 专属，并绕过共享树缓存。

根候选先收集可链接、非分隔项的顶层分区，再收集 sidebar_root_for: self 分区，并按 URL 去重。 两种来源都遵守显式的 sidebar_root_menu: false；未设置或 true 时保留。 当前解析出的根即使被排除在全站候选之外，仍会追加。零入口不输出控件，单入口 输出静态链接；所有 URL 保留语言和部署路径前缀。分隔项和使用 build.render: never 的分区不会成为切换器链接。

sidebar_divider 叶子保持静态标题；分区节点在两套侧栏遍历器中保留子项，标题不跳转， 启用折叠时提供真正的展开按钮。分组自身不进入翻页序列，子页保持原有顺序。配合 build.render: never 可省略分区自己的输出而不隐藏后代。面包屑显示不带链接的标题， 搜索跳过分组，导航 JSON 提升其子节点，Print 保留子文档。Book 目录保留分组标题和子项链接， 但跳过未发布的分组正文标题。toc_hide 仍隐藏整棵子树， 不能代替分组。显式导航键使用不含语言和部署前缀的路径，实际链接则保留这两个前缀。 显式导航的 sections 数组为空时发出警告，并在所有导航输出中回退到内容树。 两种权威来源都剪掉 toc_hide 子树；导航 JSON 将 manual_link_relref 保留为指向 解析目标的内部链接，不把占位页自身当成页面身份。

侧栏运行时

window.OinkSidebar 管理已注册的树分支及可搬迁的 TOC、反向链接和分类法分组， 不依赖它们当前的 DOM 父节点。setExpanded(id, boolean, {source}) 对有效目标返回 true，对未知 ID 或非布尔值返回 false。getState(id) 返回新的 {id, expanded} 快照 或 null。ID 使用现有 aria-controls 指定的受控区域 ID，不能修改注册范围之外的元素。

来源为 user、active-path、responsive 和默认的 api。所有写入先提交 aria-expanded、td-is-open、本地化标签和区域的 inert 状态，再向 document 发送一次 oink:sidebar-disclosure 事件，详情为 {id, expanded, source}。重复写入相同状态不发 事件。API 恢复时保留当前路径祖先展开，用户仍可主动折叠这些分支。关闭含焦点的区域时， 先把焦点归还给展开按钮，再执行隔离。

ready 是初始活动路径补全和响应式搬迁完成后解析为 API 的 Promise；isReady 和 oink:sidebar-ready 也提供可供晚加载消费者检查的完成状态。可选的持久化由站点负责： 等待 ready，在 try/catch 中读取存储，再通过 setter 恢复有效 ID。OINK 自身保存整栏 折叠、宽度和滚动位置，不定义读者分支选择的版本/语言存储格式。

桌面折叠和移动抽屉关闭时，面板内容设为 inert，面板标记 aria-hidden。先移出焦点再 隔离，打开时先解除隔离再聚焦。面板本身继续充当 16px 指针感应区，外部恢复按钮保持 可用。悬浮、Escape、遮罩关闭、断点清理和滚动解锁保留原有行为。这些运行时属性不进入 无 JavaScript 的服务端回退标记。

TOC 整栏折叠时也隔离其隐藏面板。如果焦点原本位于折叠按钮，先移至可见的浮动恢复按钮； 恢复整栏后，焦点回到栏内可见的控制按钮。右侧内容搬入移动侧栏时，先清除原先的整栏 隔离，再由抽屉管理交互。抽屉的 Tab 循环只包括可见、非 inert 的控件，排除隐藏或 折叠区域中的后代。

沉浸式博客展示

OINK 没有 article 类型或第二套外壳。沉浸式阅读由普通博客外壳上的四个独立键 组成，可设在页面或分区 cascade 上；分区索引会重复它自己也需要的值：

featured_image: hero
toc_style: flow
toc_taxonomies: false
sidebar_enabled: false

博客外壳默认不渲染面包屑导航——文章应作为独立作品阅读——所以这份配置不需要 相应的键。breadcrumb 仍是普通键，页面或 cascade 可以在任何外壳上明确打开 或关闭它。

hero 在单页与分区索引上把共享特色图片用作装饰性的全出血背景。没有图片时 渲染普通开场；banner 与 wash 仍只用于单页。顶部导航栏以对比遮罩叠在 hero 上，并随页面一起滚动。

toc_style 可取 fixed 或 flow；flow 在文章旁放置更宽的导轨，并且只在滚动 之后固定。它的静止位置与文章信息行对齐；页面没有信息行时，与描述对齐。标题 换行数无法预知，因此由 docs-shell.js 测量偏移；没有 JavaScript 时，导轨从 文章起点开始。toc_taxonomies: false 移除术语云；导轨既无 TOC 又无术语云时 完全不渲染。notoc 仍是页面级 TOC 退出键。这些开关不改变署名、标签、系列、 翻页顺序、feed 或页尾组合；导轨在 xl 断点以下消失。

搜索、操作与运行时

params.offline_search 选择启用各语言的本地索引。启用后默认也在 hugo server 期间构建；大型编辑循环可以设置 offline_search_on_serve: false。HTML 搜索出现 在首页、外壳页面，以及启用 landing_search 的落地页上。其它非外壳页面与 Print 不包含对话框、Lunr 或命令面板。

搜索元数据包括 search_keywords、默认值为 1 的 search_boost，以及 search_exclude。索引携带 URL、标题、分类法、摘录、小标题、description、 正文或摘要、根、分区、类型、关键词、boost、面包屑导航与图标。夹具预算为原始 2 MiB、gzip 512 KiB。站点可以通过 hooks/search-keywords-extra.html 返回额外 字符串。关键词用于匹配与排序；CJK 查询仅命中关键词时，结果显示页面描述或 摘录，不展示关键词列表。正文命中仍使用匹配位置附近的文字作为摘要。

内置操作 ID 包括 copy_markdown、copy_link、open_chatgpt、open_claude、 view_markdown、view_history、edit_page、create_child_page、create_issue、 create_project_issue、print_section、print、switch_preset、switch_theme、 switch_language、switch_version 与 open_github。分享栏之外的 copy_link 只出现在命令面板中。站点通过 languages.<lang>.params.ui.command_palette.commands 配置的命令可以打开安全 URL，或调用内置 ID，绝不能注入 JavaScript。剪贴板的旧式回退恢复此前的焦点、选区及其方向， 但复制期间其他控件已获得焦点时不再抢回。

编辑、历史与新建子页操作要求源文件具有仓库相对路径。物理文件名和站点工作目录 先统一为 / 分隔符，再判断包含关系。path_base_for_github_subdir 匹配归一化后的 路径：站点内内容使用相对工作目录的路径，外部挂载使用绝对路径。字符串正则可以 移除匹配的内容，{from, to} 映射可以替换它；外部来源必须显式匹配规则。 映射并整理路径后，空路径、.、绝对路径、带盘符的路径以及以 .. 路径段开头的 结果都会隐藏这三项操作。文档 issue 与项目 issue 操作仍按各自的仓库配置提供。 Windows 映射应匹配 / 而不是 \；归一化不会改变文件名大小写。

命令面板有空状态、文本搜索状态与 > 命令状态；快捷链接来自导航。它没有历史、 语义搜索、个性化或远程回退。搜索查询留在浏览器内，默认不发送遥测。

OinkSurfaceCoordinator 协调命令面板、抽屉、根栏目、语言与版本菜单。各界面自行 管理焦点恢复与 Escape。键盘导航会忽略可编辑控件与模态框，Ctrl/Cmd+K 同样避让 其他已打开的 dialog，包括固定定位的 ARIA 对话框。/、\、f、c 打开搜索或命令；j/k 移动标题；q/e 翻页；h 改变展示方式；l/y、 t、r 分别打开语言、主题与根栏目选项。侧栏 WASD/方向键导航使用真实焦点， 不会改写 Tab 顺序。 不带链接的分隔分组按钮也参与树导航。从子页按 Left/a 先聚焦父分组，再按一次才折叠； Right/d 展开已折叠的分组，已展开时进入第一个可见子项。上一页/下一页仍只遍历链接， 不会把分组按钮当成页面。

页面大纲从同一套标题模型与滚动容器计算后的 scroll-padding-top 推导光标和可见 标题范围；SVG 线条与圆点共享同一组动画值，不会漂移。合法 URL 片段会被解码； 非法百分号序列则回退到字面的标题 ID，建立链接索引和选中页尾请求的标题时遵循 同一规则。禁止增加臆测性的 DOM 修复遍历。这项跟踪始终由普通外壳运行时负责。params.ui.scroll_spy 与页面键 scroll_spy 在整个 1.x 期间都是静默兼容 no-op，不加载独立运行时；只有未来的 破坏性版本才会删除它们。

搜索尾部扩展

受信任的站点 JavaScript 可调用 OinkCommandPalette.registerSearchTail({id, rows, activate})；YAML 和操作清单仍然只接受 数据。资源包继续按本地搜索开关装配。注册要求唯一且符合 [A-Za-z0-9][A-Za-z0-9_-]* 的 ID，以及两个函数；非法或重复注册抛出异常。返回的注销函数可重复调用，旧句柄不能删除 复用该 ID 的新注册。面板打开时的注册变化会合并调度一次渲染，注销会取消该扩展的待完成操作。

rows(context) 同步返回描述符。context 是冻结的 {query, locale, phase, pageResultCount} 快照：query 去除首尾空白，locale 使用 HTML 的语言标签，phase 为 results、empty 或 error，数量只统计上限截取后的本地页面结果。仅在非空文本搜索完成后调用扩展，不在空查询、 命令、选择或加载状态调用。扩展行按注册顺序放在本地化的 Actions 组中，排在全部原生页面及 操作之后。原生空结果、错误提示与输入触发的索引重试保留。

描述符必须提供扩展内唯一、符合相同语法的 id，以及非空字符串 title。 可选的 description、icon、disabledReason 为字符串，available 为布尔值，默认 true。 OINK 复制并冻结这些字段，把显示字符串当作文本渲染。描述符非法、ID 重复、返回异步结果或 回调抛出异常时，本轮跳过整个扩展，其他扩展不受影响。不承诺回调的精确调用次数。

activate(row, context) 只通过普通结果行的激活路径调用，收到复制后的描述符和生成该行时 的上下文，另带 AbortSignal 与 handoff()。操作待完成时阻止其他结果行激活，包括进入原生 选择菜单。同步异常和 Promise 拒绝会释放待完成状态、保持面板打开，并播报本地化的操作失败信息。成功值被忽略；成功时关闭 面板，不从其他界面抢回焦点。关闭、重新打开、渲染的查询改变或注销会取消待完成操作，旧操作 的迟到结果不能修改新会话。

打开另一个受协调器管理的界面前，调用 context.handoff()。它关闭面板，但不归还焦点，也不 取消本次激活。随后由站点管理新界面的焦点与错误提示。之后的新 Palette 会话或注销仍可取消 尚未完成的操作；成功完成不会取消已经移交的操作。OINK 不强制超时。

rows() 必须保持纯净。这是受信任代码的契约，不是安全沙箱。默认查询仍留在本地，不内置 远程服务商或遥测。扩展的网络行为和服务商所需授权由站点负责。

分享

params.ui.share 默认为空，可接受 16 个目标的任意有序子集：x、bluesky、 mastodon、facebook、linkedin、reddit、hackernews、telegram、 whatsapp、line、pinterest、weibo、chatgpt、claude、email、copy。 页面列表会替换继承列表；share: false 退出。未知项会警告并丢弃。只有普通页面 渲染分享栏；Print、Markdown 与 RSS 省略它。

目标是携带页面永久链接与标题的普通 intent 链接，外加本地 copy_link 按钮。 Pinterest 图片来自共享特色图片解析器。ChatGPT 与 Claude 接收构建期生成的永久 链接提示，与页面菜单里的助理操作相互独立。Discord 没有公共 intent 目标，因此 有意不提供。

分享栏不加载平台 SDK、iframe、脚本、样式表、计数器或 campaign 参数；只有读者 主动点击链接时才产生请求。它是一行带无障碍标签的字形。 share/items.html 解析目标，share/bar.html 负责渲染。

注记

页面注记在 annotation-items.html 中解析描述项，再通过 page-meta-lastmod.html 渲染；两者都可以做窄范围覆盖。各行顺序如下：

upstream_link 是页面级事实；cascade 有效，upstream_link: "" 表示退出。 其它上游事实按站点参数 → data/upstreams[upstream_source] → front matter 解析： upstream_name、upstream_copyright、upstream_license、upstream_notice， 以及可选的 upstream_ref、upstream_modified。存在链接时，前四项必填。无效或 残缺的署名会警告，而且不渲染法律声明；不支持的 URL 会被拒绝。发布门禁通过 --panicOnWarning 拒绝这类警告。

upstream_modified 改变署名动词并链接提交历史，不增加新行。notice 页面承载 完整的许可证与免责声明。翻译说明通过 params.ui.translation_notice 选择启用， 以页面键 translation_notice 参与 cascade，跳过生成页面或无正文页面；以本语言 原创的页面可以用 translation_notice: false 关闭。

作者与系列

博客文章页头依次为标题、信息行、术语徽章、作者署名、系列条；description 在其后 引出正文。信息行 article-info.html 始终包含日期；启用 reading_time 后再增加 字数与分钟数。Front matter 的 upstream_link 与注记使用同一个页面级事实， 并在共享 URL 策略保护下增加本地化的原文链接。术语行只是裸徽章组，分类法名称 位于分组标签中，不显示前缀。术语徽章静止时是浅中性底与弱化文字，前置该分类法的 term 图标；可点击徽章在 hover 或 focus 时才取得当前分区的强调色淡铺、边框与文字。 图标词汇表由 taxonomy-icon.html 独家拥有——每个 分类法配一对图标：整体分类法一枚、单个术语一枚（folder-open/folder、 tags/tag、cubes/cube、users/user-pen、series 用 book-bookmark/book，其余用 shapes）；params.ui.taxonomy_icons 可覆盖： 字符串同时作用于两个表面，taxonomy/term map 分别设置；无效输入警告并保留 内置。右栏词云只在云头戴整体图标：云 chip 保持"文本 + 计数”——分类法已经亮明 身份，再在每个 chip 上重复图标只是噪声。独立的分类法目录卡片会带一枚术语图标； 作者署名只放人物——头像、姓名与个人资料的一行简介—— 不带标签或日期。列表行、卡片与术语归档共享同一形态的元数据行：日期、一条本地化 的作者与分区短语，以及由同一个 reading_time 开关控制的字数和分钟数。句子下方 是独立成行、自动换行的徽章行，按分类法字母序列出页面在全部分类法下的词条，每枚 徽章佩戴各自的 term 图标；卡片排除 authors——其句中已具名。

只有声明 taxonomies: {author: authors} 才启用作者。作者 term 页面拥有显示名称、 摘要、正文与特色图片头像；没有 profile 时，回退到链接标题、首字母与归档。 authors-resolve.html 在文章页头、列表行中保留 front matter 顺序，并为每位作者 生成一个 RSS dc:creator。没有 authors 时，旧 author 保持原样；两者同时 存在时，authors 无警告胜出。自定义作者分类法复数名按普通分类法处理。

只有声明 taxonomies: {series: series} 才启用系列。Term 页面拥有引言；不新增 参数、数据文件、封面模型或运行时。页面使用 series: [name] 与可选的 series_weight。series-pages.html 先按 weight 排有权重成员，再按日期升序排 无权重成员，并用 Path 打破平局；系列条与 term 页面共享该顺序。第一个命名系列 得到一条 HTML/Print 系列条。面板是半透明加模糊，而不是一张不透明卡片：hero 文章会把题图铺在这一段背后，不透明底色等于在画面上挖个洞；普通文章上这层色调 就落回页面自身的底色，所以一种处理同时服务两种场景。summary 拥有整行与末端 箭头；系列名连同它的分类法图标，仍是 summary 的兄弟链接，覆盖在一份隐藏的等宽 占位文字上，避免 summary 内出现嵌套交互控件。展开后先划一条细线，再在同一层 表面上把成员阅读顺序放进一个保持 DOM 顺序的自适应网格。每个链接都把序号纳入 点击目标，序号贴在固定方格轨道的末端，因此无论多少篇，标题都对齐在同一条边上； 窄屏保持一栏，只有当每个标题仍有可读宽度时才增加等宽栏，因此桌面面板能用满自身 宽度，也不会把一条选中背景拖过整篇正文。悬停与读者所在位置直接借用侧栏导航 处理这两种状态的同两种底色，当前篇再加上填充序号与加粗标题，不靠颜色单独表意。打印时显示同一份展开 列表，收为单栏。单篇系列与非 HTML 输出省略它。编号、交叉引用与聚合输出仍属于 Book。

默认文章分类法徽章会排除保留的 authors 与 series，因为专属界面已经展示 它们。显式设置 params.taxonomy.page_header 可以恢复任意一项。

博客索引与页面组合

博客分区索引使用 params.ui.blog_index：默认的 list 与 cards 都是按最新优先 排列的一段扁平结果，共享 blog_index_size 分页；元数据行已经显示日期，所以不再 需要年份标题。table 把整个分区显示为日期、标题、标签行，不分页。卡片使用共享 首图、本地化日期/作者/分区元数据、标签与三行摘要。

分类法页（/tags/、/authors/）与其术语页共用一个页头 shell/taxonomy-head.html。分类法页以整体分类法图标的着色方块、本地化名称与 术语数开头；术语页以术语标题与取自 ui_taxonomy_pages、按当前 locale 的 CLDR 复数类别选择的页面数开头，没有渲染面包屑时标题上方再加一行 kicker，写明分类法并链回列表页——面包屑开启时它在上一行已经做了这两件事：代表 生成的分类法页的那一级面包屑借用页头同一个本地化标签，而不是 Hugo 的复数名标题。 页头之下，分类法页把术语排成单行卡片网格 shell/taxonomy-cards.html：使用次数 多者在前、同数按字母序（与右栏词云同序），以 auto-fill 填满等宽列，因此术语 很少时两张卡片也不会被拉宽到整页。一张卡片就是术语图标、术语名与页面数，整张 卡片即链接；只有作者以署名同款小头像开头，走同一个头像 partial。卡片不带描述、 不带最新一页：术语没有标题与计数之外值得一说的内容，多出的那一行只会让网格发糊。 不再有筛选芯片行与「全部」芯片：分区根已经在侧栏与顶栏里。术语页保持行列表， 作者资料页保留自己的页头。

分类法页与术语页的右栏以 shell/taxonomy-switcher.html 开头：声明的每种分类法 一行——整体图标、本地化名称、术语数——链向其列表页，当前分类法置于选中底色上。 这是从一种分类法的页面去另一种的路：词云芯片跳到术语页，词云头只负责折叠；只有 一种分类法的站点不渲染切换器。这一组与词云共用 toc_taxonomies 开关。分类法页 的词云按全站统计（taxonomy-root.html 对该 kind 不返回根），并省略自己那一组， 它的术语就是旁边的卡片；术语页保持分区作用域与完整的一组。

params.ui.blog_index_toggle 为当前分页切片渲染三种形态，并允许读者循环切换。 配置值控制首次绘制，隐藏形态不加载图片。读者存储的选择只作用于发布了全部三种 形态的索引：切换器关闭的分区只发布一种形态，并始终显示它。Front matter 或 cascade 可为每个分区覆盖站点模式。没有切换器的 table 仍是完整且不分页的归档。

params.logo 始终是品牌标志；params.wordmark 或站点标题是紧凑宽度下隐藏的 文字部分。Docs、Book、Blog 与 Swagger 共享一个外壳模型。页尾顺序为分享、反馈、 注记、翻页、评论。Docs/Book 翻页遵循侧栏前序遍历；Blog 按 weight 后接日期倒序； pager: false 退出。静态输出省略翻页 UI。

每一种实际渲染的页脚形态，都会在最底层栏右侧保留纯图标工具组，顺序为版本、 语言、主题、快捷键帮助。各菜单向上展开；版本触发器不直接显示当前分支或版本名。 胖页脚的折叠箭头排在工具组之后。低于 lg 时，底层栏放弃版权/居中/工具组的 三列布局，改为三行全宽居中堆叠，工具组在最后一行。这些全局控件不再出现在 侧栏底部；footer_style: none 会移除整条底栏。

OINK 没有归档外壳、任意深度飞出菜单、第二个导航权威、查询上传，也没有针对已 移除配置的浏览器兼容 shim。反馈只通过既有 gtag 发出 docs_feedback，在本地 保存选择，而且不替代 Giscus。

验证

bin/check-navigation-contract.py、bin/check-shell.py、JavaScript 测试、输出 golden 与消费站点浏览器套件覆盖导航、语言与子路径链接、博客变体、页尾顺序、 键盘行为、无障碍与响应式布局。

外观控件

顶栏与底栏共用点击或键盘展开的外观控件，Landing 手机抽屉另有带标签的入口。 preset_menu 允许选择时显示原生风格单选组；dark_mode.show_menu 开启时显示 浅色、深色、跟随系统单选组。选择立即生效，面板保持打开。Enter、Space 或向下 方向键展开；方向键在组内选择，Tab 在组间移动，Escape 关闭并归还焦点。触发按钮 图标表示实际明暗状态：浅色显示太阳，深色显示月亮，跟随系统变化时也同步更新。

英文分组标题为 Style 和 Light，中文为「风格」与「明暗」。风格选项以两列独立 按钮排列，使用带主题色的纸页、叠层、笔尖或终端图标与预设名称，不显示 Aa 预览 或实验标记。站点默认项在悬停提示与无障碍名称中注明，选择后清除保存的风格。 选中项使用淡色背景与边框，键盘焦点另有轮廓线。

桌面使用锚定触发器的非模态 dialog，外部点击或焦点离开时关闭。低于 768 px 或 从 Landing 抽屉进入时，通过 showModal() 在浏览器顶层打开底部表单，提供关闭 按钮和 44 px 选项目标。关闭表单保留下方抽屉。表面协调器在展开前关闭无关弹层。 t 快捷键继续通过 switch_theme 切换明暗；switch_preset 是独立的命令面板选项。

本地 Ink/Terminal 实验仍需显式配置；preset_menu: true 继续提供 Paper/Slate 与站点默认值。两者复用同一套状态、键盘、命令面板与底部表单 机制。Terminal 压紧桌面导航行，保留正文与手机触控目标尺寸。

4 - 落地页契约

共享规则见架构契约与 组件契约；迁移行为属于 迁移边界。

外壳与数据

任何普通页面都可以声明 layout: landing。它渲染顶部导航栏、全宽画布与页脚， 不显示 docs 侧栏或 TOC 导轨。首页继续把 data/home/<lang>.yaml 作为兼容的创作 路径，并通过同一个渲染器处理。

非首页依次从内联 front matter、data/landing/<key>/<lang>.yaml、单个 data/landing/<key>.yaml 中精确匹配语言的条目，以及英文或无后缀本地数据中 解析 sections。落地页绝不抓取可变事实；星标数、价格、截图与头像必须在 Hugo 运行前提交或生成。

params.ui.landing_search 默认为 true，而且只有启用 offline_search 时才打开 既有本地命令面板。params.ui.github_stars 与 params.ui.alt_site 是可选的本地 界面事实。

区块注册表

注册表恰好有 22 种内置区块：

• hero、metrics、capabilities、principles、cards、logo-wall、 gallery、testimonials、contributors、faq、markdown、cta；
• pricing、pricing-compare、command-box、steps、timeline、 code-plate、preview、case-study、download、bar-chart。

条目可以是类型字符串，也可以是包含 type、key、id、enabled、内联 data 或有意指定的本地 partial 的 map。作者提供唯一 ID，OINK 把它规范为 锚点安全值。未知类型遵循共享的警告与安全回退策略，绝不静默消失；发布时 --panicOnWarning 会拒绝它。内置区块由 landing/ partial 负责；已经移除的 home/ partial 名称不是 API。

preview 通过站点渲染钩子，把 Markdown source 放在 RenderString 输出旁， 因此其内容会登记与 docs 内容相同的运行时。源码面板使用 Chroma，并带默认值为 page.md 的 file 名称。Markdown 输出使用四个反引号包围的 markdown 围栏； RSS 省略它。面板标签来自主题 i18n。

hero.align 可取 start 或 center。Center 只适用于文本；与图片组合时会警告， 并回退到 start，同时保留图片。download 消费与 shortcode 相同的 data/download/<key>.yaml 结构，不引入第二套 channel、版本、发布或插值模型。

语言、运行时与无障碍

叙述文件可以按语言拆分。共享事实字段依次解析 <field>_<exact language>——其中 - 规范为 _——再解析 <field>_<primary language>，最后解析无后缀字段。 不接受 camelCase 别名。叙述字段通过站点渲染钩子渲染行内或区块 Markdown；复用 为无障碍名称的值会转为纯文本。区块文案属于站点数据；只有主题控件使用 OINK i18n。

交互式 HTML 设置 hasLanding，从而只按需添加 landing.js。运行时复用 OinkSurfaceCoordinator，负责出现动画、数字递增、复制、紧凑菜单与主题图片 增强。没有 JavaScript 或 Landing 脚本加载失败时，服务端输出仍然完整可见。 出现动画的候选元素默认可见，只有成功安装观察器后才标记为等待动画。数字指标 由服务端按配置输出完整的数字格式、前缀和后缀，递增动画的最后一帧使用同一显示文本。

跑马灯只用 CSS 复制；副本带 aria-hidden 与 inert，本地化复选框无需 JavaScript 也能持久保存暂停状态。减少动画会停用动画，强制颜色保留控件，主题 图片响应共享主题事件。顶部导航栏的 mega 面板与其 columns 参数已退役：仍然配置 columns 的菜单会告警并保持单列。紧凑菜单使用真实链接 与按钮，不捕获焦点，也不复制桌面导航树。

输出与兼容性

非 HTML 输出不设置 Landing 标志或运行时。根相对链接与资源遵循部署子路径；普通 构建不下载图片。

已经移除的 0.4 组件形态属于迁移工具，不是并行的落地页实现。OINK 不增加价格 周期切换、远程事实 API、热点编辑器、可视化构建器或第二套注册表。既有首页数据 与显式自定义区块 partial 继续有效。

视觉预设

Paper 去掉首屏网格与光晕，使用暖色阴影、Plex Sans 展示标题和链接色主按钮。 Slate 保留技术网格、光晕、Chakra Petch 标题与原有主按钮颜色。两者共用分区结构， 不改变密度。手机抽屉包含共用外观表单，参见外壳契约。

显式开启的 Ink/Terminal 实验也去掉网格、光晕与阴影。Ink 使用高字重 Inter 标题、 直角卡片与红色主按钮；Terminal 使用等宽标题、2 px 圆角、琥珀主按钮与静态光标形 装饰。两者都不新增动画，不改变分区列结构。

5 - OINK 迁移边界

这是源码与配置指南，不是版本发布流水账。本地源码、提交、标签、推送、消费站点 固定版本、部署与生产一致仍是彼此独立的状态。面向读者的升级流程见 版本升级。

工具范围

bin/migrations/oink06.py 只扫描和自动改写站点内容目录下的 Markdown 文件， 包括受支持的 YAML front matter。它不改写 Hugo 配置、数据文件、布局、资源、 模块或生成输出。TOML/JSON front matter 与有歧义的 Markdown 会连同位置一起报告， 留给人工检查。

默认执行 dry-run；完成后的迁移具有幂等性：

python3 bin/migrations/oink06.py report --sites <dir>... --md report.md --json report.json
python3 bin/migrations/oink06.py migrate --site <dir>
python3 bin/migrations/oink06.py migrate --site <dir> --write
python3 bin/migrations/oink06.py check --site <dir>

代码围栏的内容不会改写，包括与有序或无序列表标记处于同一行、可带引用前缀的围栏。 代码示例里额外的字面引用前缀不会结束该围栏。 book_figures.py 保留范围明确的 TPME、DDIA v1/v2 与 pg-internal profile；它不是通用解析器。

隔离验证工具 bin/measure-baseline.py 和 bin/sites/build-all.py 会在清理已有 输出前，拒绝与任一输入站点、运行工具的 checkout、选中的主题 checkout 或其他 快照交叠的快照目录，包括通过符号链接别名指向这些位置的 --keep 目标，以及 通过 --theme 选择其他主题 checkout 的情况。

更新消费站点仓库

主题发布后，应清点维护中的消费站点 checkout，并升级它们固定的版本。 主题的 bin/update-consumers.py 扫描指定根目录下的直属项目目录，不递归进入 归档、生成站点、缓存或主题测试夹具。

此工具随 OINK 1.2.0 发布。在主题 checkout 中执行，先清点，再升级到正式标签。

python3 bin/update-consumers.py v1.2.0 --roots ~/www ~/pgsty
python3 bin/update-consumers.py v1.2.0 --roots ~/www ~/pgsty --write --check

第一条命令只报告版本采用情况。第二条更新 go.mod 和 go.sum 中的 OINK 条目，核对精确的模块解析图，并对每个选中站点运行将警告视为失败的构建。 执行时禁用 GOWORK、Hugo 模块 workspace 和环境变量中的模块替换。日志与 原始模块文件保存在临时报告目录，也可通过 --report-dir 指定目录。 更新失败会恢复模块文件；构建失败则保留新版本以便排查，并返回失败状态。 扫描根目录无法读取或消费站模块格式错误时，会记录失败条目，继续清点其余站点， 并以非零状态退出。显式选择的目录不存在或不是 OINK 消费站时，也会明确报告失败。

工具跳过链接 worktree、隐藏副本和非默认分支。应检查所有跳过与阻塞条目： 通过 --sites <path>... 显式选择已核对的 checkout，包括已有模块改动的目录。 go.mod 中的 OINK 替换需要手工处理。vendor 主题需先独立核对，再使用 --refresh-vendor 备份并重新生成 _vendor/；只改模块版本不会更新 vendor 中的主题。

保留无关改动，同步站点 README 和配置中的当前主题版本说明，并运行站点自身的 检查与视觉验收。工具不改写正文、不提交、不推送、不部署。这些完成状态必须 分别记录，已使用目标标签的站点也要纳入清点。

从 0.4 内容迁移到当前形态

配置与 front matter

以下配置改动需要手工处理；工具可以报告匹配的 front matter 键，但绝不编辑站点 配置。

Prism、rss_sections 与 algolia_docsearch 已移除。Chroma 是唯一高亮器；Algolia 配置为 search.algolia。页面级覆盖会去掉 ui. 前缀。旧 hide_feedback、 hide_readingtime、exclude_search、content_width、camelCase 手工链接与嵌套 front matter ui map 会连同替代项一起报告。

从 0.5 到 0.6

• 用 upstream_link 加 upstream_name、upstream_copyright、 upstream_license、upstream_notice 替代 upstream_attribution；把 downstream_modified 改名为 upstream_modified。
• 用一个 GitHub release_url 替代 release map；从发布索引移除 release_products 与 release_group_by_product。
• 博客与默认日期现在采用 ISO 2006-01-02；面向读者的日期继续显式保留 time_format_blog 或 time_format_default。

已移除名称会警告，并采用文档规定的安全回退或不渲染；普通预览可以继续，严格 门禁通过 --panicOnWarning 拒绝它们。blog_index_toggle、 featured_image: hero、toc_style 与 toc_taxonomies 是增量选择启用项，不会 引入内容类型；沉浸式阅读仍使用普通博客外壳。

前置条件与验证

按照组件契约启用 Goldmark unsafe 渲染、块属性与 独立块图片。要使用 \(...\)、\[...\] 或 $$...$$，需要显式启用 passthrough； Hugo 不会合并主题的 markup 配置。

针对改动的契约，使用固定的 Hugo Extended 0.165.0 工具链运行范围最小的源码与输出 检查；运行时变化时执行 JavaScript 测试，并严格构建根路径与子路径。对于维护范围 内的站点，在桌面与窄视口检查有代表性的 EN/ZH Docs 与 Blog 路由，再分别记录固定 版本、部署与线上一致状态。

6 - 设计决策

OINK 过去把评审、PRD 与执行记录放在本地 plan/ 目录中。这样既不便发现有价值的 推理，也容易让已经放弃的设计看起来仍有权威。已经接受的理由现在统一进入这座双语、 版本化的文档站，与它所支撑的契约放在一起。

决策地图

记录格式

一份已接受决策应记录背景、选择、后果，以及证明该选择仍然成立的证据。它不重复参数 参考或教程。每份决策都要链接到归属契约与验证面，中英文页面必须同步修改。

决策发生变化时，应在同一次交付中更新实现、检查器、受影响契约与决策记录。旧答案留在 Git 历史和版本变更记录中，不在导航树里并列保留两套“现行”答案。

相关

• 设计契约 — 当前规范行为
• 研究 — 为决策提供依据的定期快照
• 提案 — 尚未接受的想法

6.1 - 警告与安全回退

背景

Hugo 把整座站点作为一次事务构建。编辑一页时触发的 errorf 会让该次重建中的所有 URL 都返回错误，包括无关页面和首页。服务器进程仍然存在，修正输入后也会自动恢复，但多人共享 的预览在此期间完全不可用。

警告的开发成本不同。出错的值可以回退，站点其余部分仍可检查，作者也能看到准确消息。 发布构建则不会放过它，因为 OINK 的 CI 与集成门禁都会加上 --panicOnWarning。

决策

校验遵循四条规则：

1. 点明无效键和值、允许的形状以及实际采用的回退值。
2. 值来自页面 front matter 时带上页面位置；站点级错误不要在每一页重复刷屏。
3. 不允许无效值继续参与后续运算。先校验，再用规范化后的值渲染。
4. 没有诚实回退时，警告并且不渲染。不能为了继续构建而编造内容、发起网络请求或输出 不安全 URL。

枚举、布尔、CSS 长度与数字的共享校验形状位于 layouts/_partials/validate.html。领域 resolver 可以增加更窄的规则，但必须保留同一套 警告与回退契约。

安全边界

继续构建不等于继续输出危险内容。被拒绝的 CSS 长度要在进入 style 属性之前回退；远程服务 配置不完整时，要在浏览器可能发起请求之前省略组件；不安全的操作 URL 直接丢弃。真正的保护是 坏输出没有出现，而不是 Hugo 被终止。

这也把编辑与发布清晰分开：

后果

• 每个回退值都是公开契约的一部分，必须与主题声明的默认值一致。
• 从“失败”改成“回退”时，测试也必须改变。负向测试要同时证明普通构建存活、警告文案、 渲染后的回退，以及严格构建失败。
• 检查器必须直接验证被拒绝的输出。例如 URL 安全测试应断言危险 URL 没有进入产物，不能把 任意构建失败当作充分证据。
• 渲染产物负责 DOM、属性、顺序与已注入 token 的断言；浏览器套件负责计算后的颜色、尺寸、 间距、断点与交互结果。只要公开结果可以直接观察，检查器就不应冻结某一种 Sass 写法。
• 源码级检查仍用于 errorf 等禁止构造，以及产物无法证明的少量拓扑不变量，例如唯一 authority、 唯一 resolver，或有意收窄的 caller set。

验证

本决策的归属参考包括 架构契约、 bin/check-params.py，以及主题夹具与本站的严格构建。

6.2 - 配置模型

背景

OINK 继承了成熟的配置面，又增加了阅读外壳、内容输出和本地交互。早期设计曾尝试把所有 主题自有键迁入一个新命名空间，并在每页一次性解析完整配置字典。这样会在 Hugo 原生键旁边 再造一种语言，使 section cascade 更复杂，迁移规模甚至超过它要控制的行为本身。

现行模型直接体现每一层的归属：

决策

配置 API 遵循以下规则：

1. 站点事实保留在既有顶层；界面选择归入 params.ui.*。
2. 页面覆盖去掉 ui. 前缀，其余名称保持一致。section 的 cascade 可以把这个顶层键应用到后代。
3. 一个布尔值足以表达完整政策时使用标量；只有真正存在下级设置时才使用 map。既有 map 可以接受 布尔速记。
4. 名称采用正向、snake_case，并按功能分组。密切相关的设置共用前缀，不为此再建一层 resolver。
5. 主题默认值声明在主题的 hugo.yaml 中。只有静态值会抹掉刻意存在的外壳差异时，模板才可以 推导默认值。
6. 每个功能族负责自己的规范化与校验。共享 helper 提供常见形状，但不存在一套悄悄重写任意旧键的 全局兼容注册表。

完整的现行键、类型与默认值统一放在配置参考中。本决策只记录 归属规则，不再维护第二张参数表。

兼容策略

公开键改名时，由归属 resolver 给出定向警告，同时提供迁移说明和负向测试。已移除或拼错的键 不构成永久别名层的理由。Hugo 与第三方原生 camelCase 键继续保留原样；OINK 自有新增使用 snake_case。

页面值通过 Hugo 普通的 front matter 与 cascade 模型解析。OINK 不要求作者在 front matter 里写嵌套 ui: 树，也不承诺合并任意嵌套页面 map。

后果

• 新增公开设置时，必须有声明或明确推导的默认值、归属 resolver、文档，以及正向和负向测试。
• 配置指南链接到唯一参考表，不在各处重复类型与默认值。
• 只有有序或重复事实才值得新增数据结构，不能只因为不想增加参数就造一个 data 文件。
• 无效标量值遵循警告与回退决策。

验证

bin/check-params.py 审计声明默认值、页面别名、警告行为与禁止 errorf 的不变量。公开参考及其 中文对页由集成站的双语和渲染链接检查覆盖。

6.3 - Markdown 优先创作

背景

OINK 同时服务短手册、大型参考文档、发布归档、落地页和书籍。对十一个消费站点、五千多篇 Markdown 的盘点呈现了两个极端：有些页面几乎不用主题语法，有些页面则由大量嵌套 shortcode 与站点自有 layout 拼成。

只为后一类优化的组件 API 会变成私有 DSL；只支持纯 Markdown 又会迫使书籍、富图、标签页和 结构化发布退回站点自有 HTML。真正有用的边界是能力，而不是语法看起来是否新颖。

决策

OINK 按以下顺序设计：

1. 原生 Markdown 优先。 列表可以成为 Steps、Cards 或 FileTree 标记；表格可以成为 Fields 或矩阵；blockquote 可以成为 callout；代码围栏、图片与 passthrough 块通过渲染钩子携带属性。
2. shortcode 只补能力。 CommonMark 缩进、嵌套容器、处理选项或跨页登记无法安全表达同一结果时， 才保留全量 shortcode 形态。
3. 语义实现只有一套。 原生形态与全量形态进入同一组规范化 partial 和输出契约，不能只是两种 外观相似的组件。
4. 沿一条系统延长。 新 Landing 区块进入 section 注册表；新 Blog 呈现仍是 Blog 变体；Book 编号接入内容原语与导航系统。OINK 不为一个功能再造第二套卡片、落地页、导航或 Article 外壳。
5. 事实不藏在呈现字符串里。 版本、仓库、日期与有序记录来自 front matter、站点参数或数据文件。 shortcode 参数不能成为第二个事实来源。

输出契约

只有在每种已启用输出中都得到明确语义结果，一种创作形态才算完整：

这一要求避免一个漂亮的 HTML-only 组件悄悄破坏 Agent 输出、订阅源或整书打印。

信任与呈现

渲染钩子与 shortcode 使用明确的属性白名单。不安全 URL scheme、内联事件处理器和任意 style 输入会被丢弃。只有在文档明确规定、下游站点 CSS 已属于既有创作契约的表面，才接受作者 class。 图标使用一对 Font Awesome class；OINK 不再发明第二种图标 ID 语言。

后果

• 提议新组件时，必须先说明 Markdown 加既有渲染钩子为什么不够。
• 保留全量 shortcode 时，必须点明它独有的能力，并测试两种形态进入相同的规范化输出。
• 外壳变体使用相互独立的呈现键，因此启用 Hero 或流式大纲不会改变分类法、订阅源、翻页顺序或 内容类型。
• 消费站证据是带日期的研究，不是永久冻结偶然语法的理由。当前公开面仍由 组件契约与外壳契约定义。

验证

主题的组件、Book、输出与 golden 检查器先验证创作契约，本站的双语示例与浏览器套件再完成集成 验收。原生形态背后的 Goldmark 事实记录在 块属性研究中。

6.4 - 生成式配置 Schema

背景

主题已有两个配置权威：hugo.yaml 在注释旁声明每个默认值；check-params.py 的读取点扫描知道模板实际消费的每一个键。编辑器对两者一无所知，作者只能凭记忆 敲 params.ui.* 和 front matter。

JSON Schema 能给编辑器补全与悬浮文档，风险在于 Schema 悄悄变成会漂移的第三个 权威。任何手工维护的 Schema 都终将与实现脱节，而脱节的补全比没有补全更危险。

决策

bin/generate-config-schema.py 在 schema/ 下生成两个文件： site-params.schema.json 校验站点的 hugo.yaml（类型与默认值取自主题自己的 hugo.yaml，描述取自其注释块）；front-matter.schema.json 校验页面 front matter（模板作为创作面读取的全部键，描述继承自对应站点键）。仅为提示「已重命名 或已移除」而读取的键按名排除。

两个刻意的克制成为决策的一部分：

• front-matter Schema 不带类型约束。多个键在站点类型之外还接受裸布尔退出 （share: false、theme_color: false）；对合法输入画红线比没有提示更糟。
• hugo.yaml 读取器只解析该文件实际使用的形态——嵌套映射、标量、行内列表。 读不懂的构造是硬错误，超出能力时漂移门禁会大声失败而不是错误生成。

后果

改变 Schema 的唯一途径是修改 hugo.yaml 或扫描所读的模板：公开配置面变化时， Schema 在同一次提交中随之再生，不存在需要单独记得维护的第二份清单。代价是 生成器与读取点扫描成为公开配置面的隐含门禁——新增参数键必须能被它们理解， 否则 CI 直接失败。

验证

python3 bin/generate-config-schema.py --check 在内存中重新生成，schema/ 过期或缺失即失败；主题 CI 把它放在参数契约检查旁边运行。编辑器接入方法与 行为描述的规范位置是配置总览。

视觉预设枚举值另从 preset-config.html 提取。preset_menu 联合类型接受布尔值或 由解析器管理的预设名称列表，schema 不另行维护名称清单。

6.5 - 可选 CLI 与结果契约

背景与归属

主题是 Hugo 模块；消费站工具是可选的可执行文件，具有不同的安装和版本发布周期。 pgsty/oink-cli 负责名为 oink 的可执行文件及其 Go 测试。它调用外部 Hugo 二进制，不引入 Hugo 私有运行时，也不在运行时依赖同级 checkout、Python、Node.js 或未发布的主题脚本。

配置解析、渲染、路由与锚点由 Hugo 负责。CLI 检查 Hugo 的生效配置、模块图、挂载 与渲染文件，不另建路由解析器、导航权威或配置命名空间。仅针对主题的回归脚本继续 作为维护者工具。架构契约仍负责主题行为；本页 负责首期 CLI 边界与结果封套。

配置预处理仅在临时副本中重定位 workspace、replacement 与缓存路径。默认值、 配置合并、语言选择、验证和渲染语义仍由 Hugo 负责。

使用指南提供安装与命令示例。 带日期的验收记录将已执行 检查、未解决限制和发布状态分开说明。 维护验收记录 保留历史 R1–R8 计划与绑定源码的验收证据。 路线图继续保留后续提案和采用假设， 不再重复当前命令参考。

命令与修改边界

命令帮助按日常、维护与发布分组，使用 oink COMMAND --help 查看准确选项。

联网默认关闭，所有命令均不交互。Hugo 参数仅在 dev/build 的 -- 后透传。 已撤下命令与其旧计划不能应用；受支持计划类型仅为 authoring.new、 translations.review、baseline.capture、content.move。

版本化结果封套

只能选择一种结构化格式。非空 NO_COLOR 或 TERM=dumb 也会关闭文本颜色。 结构化输出不添加终端颜色，工具日志写入 stderr。--format json|yaml 与 --non-interactive 保留为隐藏兼容选项；所有命令均不交互。

默认文本展示状态、计数、最多八条活动发现及明确的未检查覆盖。详细事实与已审阅 发现保留在结构化结果中。计划与升级预览展示完整 diff。Cobra 管理命令分发与各级 帮助。CLI 提示采用 ASD-STE100 风格的简短主动英文句，不宣称认证；用户内容与 外部工具证据保留原语言。

首版允许添加字段与新规则 ID。消费者应忽略未知字段，将 ID 作为不透明字符串， 不解析其拼写。改变已有封套字段的含义或类型，需要新的 Schema 版本。命令专有事实 与原始工具输出属于证据，不是供用户导入内部 Go 包的 SDK。

机器可读 Schema 随 CLI 仓库提供，路径为 schema/result.v1.schema.json。 其标识符不证明 Schema 端点或 CLI 公开版本已经部署。

每份证据记录包含 command（参数数组）、可选的 directory、stdout、 stderr 和子进程自己的 exit_code。捕获的诊断与构建输出保留在结果中。 dev / build 直接流式输出的内容进入日志流，不再重复缓冲进证据。子进程状态与 CLI 的 0 / 1 / 2 结果码不同；负的子进程状态可能表示未取得正常退出码。

JSON Schema 定义了该结果封装的结构。

发现项、严重度与位置

每个诊断包含 rule_id、severity、message、action，以及可选的 location。 稳定规则 ID 标识问题条件。原始 Hugo 文案、翻译后的消息、路径和特定构建细节不是 稳定 ID。已有 ID 不得重新分配给不同条件。

可选的 incomplete: true 标识必需工作失败，政策不能降级这种失败。 经过审阅的排除项和基线确认仍保留在 diagnostics 中，附带 disposition: "excluded" 或 "baseline"， 以及含 reason、reviewed_by 和 RFC 3339 reviewed_at 的 review。 被排除的问题保留已记录严重度并保持可见，但不阻断已完成的政策检查。 任何未完成的必需覆盖（包括 not_checked）都决定退出码 2； 只有 complete 或 not_applicable 满足必需覆盖。

严重度取值为 info、warning 和 error。error 是阻断项，info 与 warning 是信息或建议项。但如果所需 Hugo 构建因 --panicOnWarning 失败，则必要工作未完成。信息性的完成说明与范围解释放在覆盖 详情中。自动化必须读取结果退出码与覆盖状态，不能只统计严重度。

提供 location 时，其中包含 file，以及可选的 kind、line 和 pointer。 kind 区分 source 与 output。渲染产物中的问题指向实际产物，可以在 pointer 中给出元素、属性或 JSON 位置提示；这个字段并不统一承诺采用 RFC 6901 语法。 只有明确知道行号时才提供 line。渲染链接失败不能成为编造 Markdown 源码行号的理由。

CLI 不会仅因生成的编辑器 Schema 未列出某个字段，就拒绝合法的自定义 front matter。 配置有效性继续服从 Hugo 与所属主题解析器、检查器；参见 生成式 Schema 决策。

覆盖范围与退出语义

每个覆盖条目包含 id、status、required（布尔值）和 detail，描述实际运行的 范围。一份报告可能对同一大类提供多条声明，应全部检查。

未完成状态的优先级高于政策问题。未完成的必需覆盖不能返回成功； 只有 complete 或 not_applicable 能满足必需覆盖。 Hugo 构建失败时保留原始证据并停止产物验收，不会把旧产物或部分产物报告为检查通过。 未启用的可选机器输出不构成缺失输出错误。

渲染引用范围包括受支持的 HTML URL、锚点和已输出的机器契约。覆盖声明明确排除 浏览器交互、无障碍、视觉呈现、外部 URL 可访问性、托管重定向及生产部署，也列出 未检查的动态资源与内容语义。静态产物证据不能证明未声明的翻译覆盖、翻译语义等价 或浏览器执行结果。

Hugo 公共 Page.OutputFormats 按页面和启用语言给出预期产物名称与 URL。隔离 副本添加带有本次运行唯一标识、不会进入普通列表的探针；每个启用语言都必须输出 自己的有效清单。产物检查前会移除已识别的探针文件，不改动已有页面选择的输出。 未进入普通列表的静态内容通过 Hugo GetPage 解析，不从源码语法推导路由或输出 文件名。枚举还提供每种语言的生效 base URL 与本地搜索设置。已启用且受支持的机器 产物按这些确切预期检查；未启用的可选输出仍然可选。

同一 Hugo 探针通过公共 Page.Path、Page.File、Page.Translations、 Page.Aliases 和 Page.OutputFormats 提供 data.pages，保留语言、实际 URL、 发布设置、翻译关系及声明输出。没有可靠来源时，sourceKnown: false 和 sourceScope: "unknown" 明确说明未知；生成分区不会得到虚构的源文件。 站点所属的已知路径相对于选定站点，已复制的已知依赖输入明确标记依赖范围。 这些事实描述生产视图；独立的内部分析视图可以包含草稿、未来和过期页面， 但不改变生产产物，也不把它们声称为已发布。

data.references 记录实际观察到的 HTML 和机器输出引用、解析后的实际 URL、 产物文件/位置、存在时的本地目标和已检查时的锚点状态，不推断 Markdown 源码行号。 页面与引用数据仍是可增补的命令证据，不是公开 Go SDK。

项目检查政策

选定站点根目录可以提供普通文件 oink.yaml，使用 schema_version: oink.policy/v1，管理检查选择、严重度覆盖、经审阅的问题排除、 外部 URL 范围、翻译范围、受保护正文声明和可选基线文件路径。 语言、标题、URL、菜单及配置继续归 Hugo 输入所有；依赖版本归模块文件。 符号链接、未知字段/分组、不支持版本、无效审阅元数据或多个 YAML 文档属于必需输入失败 （退出码 2）。诊断与检查只读取这项政策。

没有政策时，链接、翻译和风格均启用且必需。check links、 check translations 或 check style 显式选择一个必需分组，不受政策选择影响。 未选中或禁用的可选分组报告 not_checked。每次检查仍保留必需的严格 Hugo 构建和输出枚举前提。独立检查的翻译与源码引擎另用显式且不可发布的草稿/未来/过期 分析视图，从不替代生产产物。受管理的 build --check 只渲染生产视图，遇到未知且 必需的范围身份时返回 2。

rules 映射向确切且不透明的规则 ID 指定 error、warning 或 info。 经审阅的 exclusions 项须有 rule_id、规范相对 file glob、reason、 reviewed_by 和 RFC 3339 reviewed_at；不支持 ** 和路径逃逸形式。 站点内部源码位置使用相对站点路径匹配；选定站点之外的源码路径不能匹配排除项。 问题及审阅元数据保持可见。必需构建、输入、工具或覆盖失败不能经严重度更改或排除变成成功。

同 origin 但位于配置 base path 之外的 HTML 引用属于政策问题，除非经审阅的 external_scopes URL 声明其为单独部署的路径范围。每项范围要求同样的审阅元数据， 以及不含凭据、query 或 fragment 的绝对 HTTP(S) URL；匹配按完整路径段进行。 范围不能豁免项目内部缺失目标或机器输出的必需本地目标。 不同 origin 的引用在离线静态检查中仍明确标记为未验证。

翻译政策与审阅证据

translations.scopes 按规范绝对 Hugo Page.Path 前缀选择源页面，再通过 Hugo 翻译身份寻找目标，不从文件名推断公开路由或语言。每项范围包含 path、 source_language、required_languages、mode 和 drafts。 mode 默认 localized，也支持 strict。drafts 默认 include； ignore 排除草稿源页面/目标，require-published 要求选定源页面和必需目标实际 存在于生产发布视图。Hugo 已知但禁用的语言为 not_applicable；未知语言属于 无效政策。最具体的匹配路径决定源页面所属范围。

没有范围时，检查以 Hugo 已启用默认语言为源的已有配对及重复关系，不要求全站普遍 本地化；translations.coverage 将未配置语言覆盖记为可选 not_checked。 缺失必需目标和选定关系重复属于政策问题。草稿/发布状态与审阅状态分别记录。

约束均须显式选择：严格模式的 explicit_ids 比较完整的已识别显式 ID 映射， 本地化模式要求选定 ids 列表。ids 要求两份文件均有指定 ID，placeholders 比较指定正文字符串的确切数量，code_labels 保护指定语言/info token 的围栏代码。 required_fields 要求双方指定的点分 front matter 字段非空；equal_fields 比较其实际值。默认没有规则要求标题数量、翻译正文或所有代码块一致。

.oink/translations.json 使用 oink.translations/v1。显式审阅记录绑定 Hugo 源/目标 ID、源语言、完整源文件/译文的字节 SHA-256、审阅人、理由和 RFC 3339 时间。无记录为 unknown；哈希相等为 current；仅源、仅译文或双方改变分别为 source_changed、translation_changed、both_changed。这些状态只证明审阅后 发生变化，不判断翻译语义。文件修改时间不能建立审阅状态。来源未证实则保持未知； 已有审阅或受保护约束无法验证时，返回必需工作未完成。

原生内容规则与覆盖

源码规则从 Markdown 结构和独立的已启用 Hugo 属性提取证据，保留原始 UTF-8 字节、CRLF/BOM、源码偏移及含未知字段的 YAML/TOML/JSON front matter。 实际生效的 Hugo 属性开关和数学透传分隔符控制识别。围栏/行内代码、短代码主体、 原始 HTML 和透传内容不会成为正文或虚构标题。不支持的正文语法保持可见； 必需源码覆盖不能静默通过。

通用规则检测重复的已识别显式 ID，并检查 style.protected 声明中的 file、 确切正文 literal 和预期 count。有界 OINK v1.1.0 目录另提供代码/表格属性、 弃用 front matter 和被丢弃的不安全属性建议。每项规则在 data.native_rule_provenance 中记录模块、版本、不可变 revision、模块 sum、 许可证及确切来源文件的 SHA-256。

只有实际挂载的公开 v1.1.0 模块缓存输入匹配这些哈希时，才运行该目录。 replacement、vendor 副本、其他版本或未知来源不选择最新主题回退： native-theme-rules 为可选 not_checked，通用语法检查仍运行。 这份目录不保证覆盖每个自定义组件或主题功能。

基线与经审阅文件计划

baseline 选择规范相对文件，默认 .oink/baseline.json，使用 oink.baseline/v1。捕获要求工作已完成并有显式审阅元数据。指纹绑定确切规则 ID、 规范化位置/指针和条件消息，不包含严重度。已确认问题保留原严重度，附带 disposition: "baseline" 并保持可见；新条件仍按政策阻断。 必需但未完成的发现项或覆盖不能被确认豁免。

审阅和捕获预览 oink.plan/v1：选定编辑、可读 diff、基础存在状态/字节/模式、 修改后字节及只读保护条件。计划 ID 不包含可变的验证/应用/恢复状态。 --plan FILE 排他保存计划；这些命令不接受 --write。 plans apply FILE --site DIR 要求确切选定站点、通过相同检查重新验证隔离候选， 并在任何写入前重新检查源码保护条件。逃逸、.git、符号链接和非普通文件受保护， 候选与源码目录重叠会被拒绝。过期计划安全失败。可选 external_inputs_hash 将 捕获的非站点输入字节、完整模式和清单绑定计划 ID。这个不透明 SHA-256 不授予 外部路径或读取权限；归属验证器比较新证明的输入，选定写入前后重新核对可信原始 外部保护条件。

排他安装保留提交期间新创建的文件。部分失败只还原本次拥有且未变化的写入，保留 后续编辑器字节、模式或删除状态。报告的恢复目录保存原字节/模式及实际捕获的并发 证据。无关文件和编辑器新建子文件均保留。文件内容不能授权 shell 执行或发布。

捕获页面查询与影响

inspect PAGE 按精确的 language:path ID、Hugo Path、permalink 或已证明的 站点源文件选择实际 Hugo 页面。已知默认语言可消解同一 Path 的多语言匹配；仍有 歧义或未知选择器时返回必需未完成 2。data.inspection 展示源码字节哈希、完整 模式、实际输出身份、观察到的入站/出站引用、翻译与物理 bundle 附件。物理附件与 观察到的发布资源分别记录。

impact --since REF 比较捕获的当前输入与隔离的 Git 已提交树，二者由同一 Hugo 引擎渲染。保留已删除的旧页面与其入站边，纳入未修改的引用页面、翻译同伴、附件及 实际派生产物。全局或不确定输入扩大因果范围；alias 等无法证明页面归属的实际 HTML 输出也会保守扩大为全范围。不会按 alias 声明猜测路由归属。只有证明归属 Git 模式范围的历史输入比较可执行位；其他模块/外部输入与当前事实保留完整模式。

历史 materialization 读取有界 Git 对象，不运行 checkout hook、filter、smudge 或文档内容。上限为 10,000 个文件、单文件 16 MiB、树总计 128 MiB；必需的私有 历史上限为 256 MiB。符号链接、submodule、超限/缺失对象、必需历史不完整及不支持 的 monorepo GitInfo 均明确为未完成。已提交的站点内部依赖可被证明；当前外部本地 replacement/workspace 字节不能替代历史证据。

data.impact.baseline_state 为 complete、incomplete 或 unavailable。 必需基线不可用时返回 2，保留全部已知当前页面、附件、引用与输出，并扩大范围。 不虚构旧页面或变更；只记录实际解析出的 commit。check [GROUP] --since REF 有意执行完整当前检查，并声明 data.check_scope: full，不承诺增量提速或部分 验证。data.impact.full_scope 单独描述因果不确定性，与验证范围分别表达。

完成的 inspect、impact 事实查询返回 0，即使单独报告的 data.current_check 含已完成质量发现 1。必需捕获失败仍为顶层 2。 check --since 保留当前政策的质量退出码和必需完成状态优先级。

context 已移除，页面事实可通过 inspect 的 JSON/YAML 报告读取。

内容移动计划

move SOURCE TARGET [--plan FILE] 预览物理站点相对文件或 bundle 的迁移。 由实际 Hugo 身份确定翻译同伴与新旧输出。计划包含保留字节/完整模式的文件及二进制 附件、可读 diff、已证明的 Markdown 目标重写、观察到的路由变化及 alias 建议。 不通过重写 front matter 自动安装 alias。原始 HTML、shortcode 输出、经过变换的 目标及源码/输出归属歧义保持为可见人工动作；不修改不透明源码片段。重复的普通 Markdown 目标也可能缺少唯一源码/输出出现位置证明，包括聚合/打印视图。仅 URL 匹配不足以授权重写这些出现位置。物理附件迁移不证明新的发布 URL。资源 URL 变化需要配对实际渲染边及相同产物字节；已证明的处理后图片 URL 不证明绝对原始 资源 URL。未证明的原始 URL 保持人工处理，不按目录迁移构造。

原始 before 检查与临时 route_probe 独立于最终候选检查。临时迁移可能因旧入站 链接产生发现 1。只有最终隔离候选及引用证明通过，计划才标记验证或保存。不支持 的身份或必需捕获失败返回 2；实际最终质量失败保持 1，不能保存可应用计划。

内容移动计划必须保存在选定站点之外。oink.plan/v1 的新增 move 选择器与 source_inputs_hash 绑定完整原始源码清单、字节及完整模式，同时应用外部输入与新 目录保护。应用已保存计划时重新生成原始/迁移 Hugo 证明，并在最终引用验证前要求 期望 plan ID 与文件完全一致。写前重新核对当前保护条件，恢复原始模式而非隔离 副本模式，拒绝或受保护恢复时保留后续编辑者的字节/模式。过期输入或已有新目标 无法提供必需证明，返回 2。只有显式 plans apply 写选定文件；预览不 stage 也不提交 Git 变更。

支持的输入边界

首期完整验证支持普通 checkout 或无 Git 元数据的实际文件，包括复制到隔离目录中 的受支持本地模块 replacement。它不会沿已挂载符号链接或外部挂载项返回用户工作区。 有效挂载范围之外的辅助符号链接不复制到快照，也不视为已验证。使用 .git 文件的 关联 Git worktree 需要实际文件审查副本；依赖 Git 的行为需要副本具有自己的 Git 元数据。

快照排除顶层 public、resources、node_modules、tmp 和 Hugo 构建锁。 挂载项需要这些被排除的输入时，不能静默通过。支持根配置与标准 config 树；显式 配置文件必须在选定站点内，自定义 HUGO_CONFIGDIR 位置会被拒绝。受支持的配置 路径重定位不构成第二套 Hugo 验证实现。

内容适配器（_content.gotmpl）可能生成无法通过受支持公共 Hugo API 完整枚举的 隐藏页面，因此完整产物验证对这类输入返回必要工作未完成。禁用页面类型或选择 render segment 导致某个启用语言缺少探针，也属于未完成。多主机语言配置不在首期 完整检查范围内，返回必要工作未完成；单主机的多语言路径仍受支持。上述情况不能 被报告为成功的部分检查。

普通内容计划

new BUNDLE --title TEXT [--language LANG] [--translations LANGS] [--kind page|docs|blog|book] [--plan FILE] 根据捕获的站点自有内容挂载预览普通 Hugo 叶子包。主语言默认采用生效默认语言，选定译文必须是不同的已启用语言。 共享文件名与语言目录布局跟随真实 Hugo 挂载，包括实际 sites.matrix.languages 选择，不假定旧 lang 字段。含糊、过滤或不支持映射需要人工创作。已有包或占用同一页面的同级内容文件会被拒绝。

主索引 draft: false，选定译文索引 draft: true。标题文本来自显式输入，不会 自动翻译，也不创建审阅记录。完整质量分析和隔离候选验证先于共享受保护计划。每份新文件必须对应恰好一个 实际站点自有 Hugo 源页面且有实际渲染输出，译文草稿使用显式分析视图。仅链接/无 输出、忽略、隐藏或 build-never 内容不能仅凭既有站点构建正常而通过，即使普通源码检查组关闭也须验证 必需来源身份。 --plan 只保存新计划文件，显式 plans apply FILE --site DIR 重新验证源码字节/ 模式、存在状态、新目录和后续附件冲突，再应用修改。新目录状态绑定计划身份， 在验证前后、写入之间和完成时核对。回滚保留后续编辑器附件并报告恢复， 不删除无关目录条目。

编辑器设置与 Markdown 片段由站点编辑器管理，editor 与 snippets 已移除。

初始化配置

init DIR [--profile project|docs|blog|book] [--languages en|en,zh|all] 组合同一份内嵌 MIT 许可证 Starter 归档。默认 project 按字节保留此前完整语言投影。 语言选择独立于内容配置，all 表示英语、中文、法语。

显式 docs、blog、book 保留对应归档内容分区及共享首页、资源、示例、工作流与 许可证。原生分区 front matter 定义文档、博客或连续书籍模型与导航。各语言站名/ 描述来自其归档分区，已有本地化首页卡片/动作/CTA 投影到该分区。只序列化这些配置 生成的 hugo.yaml 和 data/home YAML，保留内容与许可证字节不变。 没有四份复制 Starter 树，也不在运行时下载模板。

未知配置在候选验证或写入前拒绝，政策退出 1；必需 Hugo 缺失/验证失败为未完成 2。新建/空目标、先候选验证再发布、排他创建与并发编辑恢复保护适用于全部配置。 预备依赖后，普通 Hugo 可以构建生成站点。归档工作流仍为来源示例，init 不生成或 执行 R3 的校验和绑定 CI 模板。

有界升级比较

upgrade --to TAG 现根据同一原始站点输入捕获基线与候选视图，返回可读模块 diff 及完整模式变化。比较记录实际 Hugo 页面/输出/语言设置、生成文件哈希/大小/模式， 以及原始 alias 声明和单独观察的重定向文件。报告删除/新增 URL、已证明重定向、 alias 目标/字节变化及启用语言/输出/搜索变化。候选构建正常本身不能证明路由或能力 得到保留。

只有在确切旧输出文件处观察到指向对应实际候选页面的重定向，才能证明旧 URL 被保留。 未知/相对定制 alias 身份仍为必需未完成 2；删除此前生成路由或输出为阻断发现 1。 两个实际解析主题版本必须匹配明确选择的 pin；未知/替换 pin、未知/不同的规范 Hugo 版本或环境、意外其他输入变化均保持未完成。比较支持单个 HTTP(S) base origin/path， 多主机输入保持未完成。不宣称配置迁移转换或普遍浏览器/主题兼容，人工审阅保持 明确的可选未检查覆盖。观察到 alias 改指向另一个唯一 Hugo 页面时，独立于同页 URL 移动而阻断。

升级 v2 计划 ID 绑定选定模块计划、复制源码字节/完整模式/文件清单和规范实际比较。 --expect-plan ID 核对新的捕获/比较，不复用此前成功构建。生成文件哈希也绑定计划， 因此非确定性模板即使源码看似不变，也可能需要重新预览。预览返回前、每次写入前及 写入后重新核对保护条件，包括只读核对已证明的本地依赖/workspace 输入。只写选定 模块文件，回滚只恢复该操作拥有且未变化的文件，保留后续编辑器字节。已有脏目标、 replacement 与 vendor 保护继续生效。

文件保护与发布检查

初始化内嵌完整 Starter 提交并保留许可证。来源清单记录其哈希和每项投影：选择已有 语言配置、确切的公开主题 pin 与校验和，以及为新目录关闭 Git 元数据。候选验证先于 目标写入。排他创建拒绝既有文件；回滚只移除本次操作创建且未发生变化的文件，并保留 并发用户编辑、给出恢复证据。

升级只处理单站点选定的 go.mod 与 go.sum 变更。它保留无关依赖与指令， --write 拒绝有未提交修改的目标文件；传入审阅后的计划 ID 时核对该 ID，写入前 再次检查目标，并记录备份与恢复信息。无关的脏源文件不应阻止只读诊断，更不能成为 覆盖这些文件的理由。

check --release 关闭 GOWORK 与 HUGO_MODULE_WORKSPACE，并移除子进程的 环境 replacement。它保留 go.mod replacement，报告冲突的本地 OINK 替换政策， 并将 vendor 证据与公开 requirement 分开。升级拒绝 OINK replacement，也拒绝 _vendor；vendor 刷新保留为单独的显式流程。修改模块 pin 不会被描述为已更新 vendor 字节。实际选中 vendor 主题时，--release 将公开来源验证报告为必需但未完成（退出码 2）；仅版本元数据相同不足以证明 vendor 字节来自该公开标签。普通 check 仍可验证 vendor 的实际产物。

Hugo 配置中的模块 replacement 也仅在发布快照中禁用。如果 Hugo 在解析或构建时 修改了该快照的模块文件，CLI 会报告依赖输入需要显式预备和审查，保留原始字节， 而不会静默接受依赖未审查模块文件变更的构建。

已检查构建与产物身份

build --check --destination DIR --manifest FILE 在隔离环境中严格构建生产视图。 Hugo 只渲染一次；检查引擎检查该产物，再封装并导出同一份字节。CLI 不调用第二个 渲染器生成发布目录，源码 checkout 保持不变。只有结果为 0，且必需覆盖已完成 或不适用时，才能封装产物。阻断项或未完成检查不会产生已验证导出。

这个生产视图不包含单独的不可发布维护渲染。显式翻译范围政策所需的 Hugo 身份 因源码被排除发布而未知时，返回 2。CLI 不根据文件名推断缺失翻译，也不静默 跳过范围。独立 check 与 translations 命令保留完整维护视图。

目标必须为新目录或空目录，且父目录已存在；本地清单必须是产物树之外的新文件。 导出通过独占创建保留准确字节和普通文件的完整模式，不受 umask 影响，并按清单 重新检查源树与目标树。既有条目、符号链接和重叠目录树会被拒绝。部分导出失败后， 目标仍是未验证证据并予以保留。空目录和目录模式不属于发布文件清单。

--marker 可选，默认关闭。它添加 .well-known/oink-build.json，只包含 oink.build-marker/v1 和产物 ID。计算产物 ID 时排除该文件条目以避免循环哈希， 再将其准确摘要纳入最终清单。既有标记路径会被拒绝。本地清单不会自动复制到公开 产物树。

单独保存的 oink.artifact/v1 清单记录源码输入哈希、已知源码 Git revision 与 dirty 状态、实际解析的主题身份、CLI/Hugo 版本、生效环境/base URL/发布设置、 必需覆盖、实际 Hugo 路由上下文，以及每个文件的相对路径、大小、完整模式和 SHA-256。规范 URL 和 HTML 语言来自实际 HTML；Hugo 语言键单独保留。 未知 Git 状态仍是未知。原始输入字节和模式在添加临时探针、重定位 workspace 或 replacement 路径之前捕获。公开清单不包含本机绝对路径、任意参数、进程日志或 覆盖条目的自由文本。哈希证明字节身份，不是签名，也不证明本地 checkout 已公开发布。

受管理构建仅接受 -- 后的布尔 Hugo 参数 --minify、--gc、--ignoreCache 和 --noTimes，包括 =true/=false 形式。其他透传参数属于不支持的输入。 普通 build 保持既有透明透传行为。生效的示例/本地地址在普通诊断中是警告， 在已检查发布构建中是错误。--release 仍需独立的实际公开主题解析证据；本地 Git revision 或声明 pin 不能证明 vendor/replacement 字节的公开身份。

本地产物与部署验证

artifacts verify --artifact DIR --manifest FILE 只读且离线，比对准确文件集合、 字节、大小和完整模式。文件修改、缺失、新增、不安全或模式变化会使身份失效 （1）。无效清单、不可读输入以及不支持或中断的检查返回 2。上传器消费产物 之前应立即重新验证；后续编辑不能沿用先前的成功结果。

verify --site URL --manifest FILE --network 显式授权 HTTP 读取。它按清单限制 响应大小并比对解码后的字节摘要，检查每个声明文件和不同的实际 Hugo 路由 URL，包括全部语言与 子路径上下文。已记录的 HTML 规范 URL/语言值和启用的标记也会接受检查。 共享 URL/文件的请求可以合并，但保留其上下文。HTTP 无法验证本地文件模式位。

错误正文、soft-404、错误路由、已捕获规范 URL/语言值变化或错误标记是确定的 发现项（1）。超时、认证失败、限流、服务不可用或缺少必需标记属于未完成工作 （2）。跳转离开选定 origin/base path 时会被阻止；命令不发现或发送凭据。 静态构建检查不执行部署验证。构建联网权限不授权后续验证请求或上传。

已撤下 CI 生成

移除 ci init。CI 配置保留在站点或 Starter 中。 本地 CLI 验证不执行托管 CI，也不部署站点。plans apply 拒绝旧 CI 计划。

显式工作区登记

工作区是一份显式指定的 YAML 登记文件，独立版本为 oink.workspace/v1。 它只包含站点名称与目录：

schema_version: oink.workspace/v1
sites:
  - name: docs
    directory: ../docs-site
  - name: blog
    directory: ../blog-site

登记文件必须是非符号链接的普通文件，只包含一份 YAML 文档和已知字段，登记 1–64 个站点，最多 256 KiB。名称符合 [A-Za-z][A-Za-z0-9_-]{0,63}，区分大小写。 目录是相对登记文件实际父目录的字面路径，或绝对路径；不展开变量、glob 或扫描同级 目录。显式目录符号链接与操作系统路径别名解析到规范身份。拒绝重名、实际根目录 重复或重叠、文件系统根目录、悬空符号链接，以及非目录祖先。若缺失目录有已证明的 现存祖先，仍可列出；检查该站点返回 2，不会阻止后续选定站点继续检查。

workspace list|check [GROUP] --workspace FILE [--sites NAME,NAME] 在省略 --sites 时选择全部登记站点。显式选择必须使用准确、非空、不重复的登记名称；即使 参数顺序不同，仍保留登记顺序。list 不需要 Hugo 渲染器。check 复用单站引擎、 各站自己的 Hugo 输入与 oink.policy/v1 政策，不在登记文件中复制 Hugo 配置。

现有 oink.result/v1 封套包含 data.registry、selected_sites、 sites: [{name, path, result}]、completed_sites、finding_sites 和 incomplete_sites。每个子项是完整单站结果。已完成站点包括退出 0 与 1；发现 问题的站点是退出 1 的子集。只要有选定站点未完成，汇总退出为 2；否则有阻断项 时为 1，其余为 0。人类可读输出包含逐站结果与发现项，不推断未选站点已完成。

受支持的单站命令接受 --workspace FILE --site NAME，必须显式选一个登记名称， 没有默认站点。init、artifacts 与 verify 不接受这种选择。 保存的 plans apply FILE 必须绑定选定规范目录；改选其他登记站点时，在写入前 返回 2。不自动批量应用计划或升级。既有候选验证及源码/依赖字节与模式保护条件 继续生效。列出或检查登记不会创建缺失站点、安装工具、提交或写入消费者配置。

可选检查适配器

各站 oink.yaml 中的显式 tools 项选择已预备的可执行程序。这些项扩展 oink.policy/v1，不是另一份 Hugo 配置，也不是安装器。每种工具包含 enabled （默认 true）、required（默认 false）、command（默认与工具种类同名）、 config（提供时为站点内干净相对路径的普通文件）与 timeout_seconds （默认 60 秒；非默认值限 1–300）。命令是单个可执行文件名称或绝对路径，不能是 shell 表达式。

未配置的工具不会自动发现。工具不属于选定检查组时，明确显示 not_checked。 已配置的可选工具若缺失、不受支持或无法完成，会保留遗漏；必需工作未完成返回 2，不能通过规则严重度、排除项或问题基线降级。不能同时设为必需和禁用。 已完成的类型化发现项仍按政策处理：阻断项返回 1。未知工具版本或无效协议输出 不能算作检查完成。

data.adapters 记录每种工具的必需属性、状态、类型化诊断、adapter.KIND 覆盖、原始进程证据、遗漏与来源。来源包含已观察的受支持版本、可执行文件 SHA-256、 捕获配置/风格路径及其 SHA-256 和完整模式，以及固定的公开协议源码。工具日志写入 stderr 和证据；JSON stdout 仍只有一份结果。每个进程的时间与输出受限；可执行文件、 捕获配置发生变化，或工具修改私有输入时，其证据失效。

文字工具接收已证明站点自有 Markdown 的私有遮蔽副本。Front matter、BOM/CRLF 与 UTF-8 偏移、代码、短代码、原始 HTML、已配置数学公式与属性保留其源码边界。 代码正文不参与源码归因；markdownlint 仍能读取 Markdown 结构和围栏/行内代码 边界，Vale 使用纯正文遮蔽。触及排除区域或遮蔽生成文本的发现项不会归因到原文。 只有已证明的原始行/范围才输出源码位置；不支持语法与被抑制发现项保留可见遗漏。 适配器不格式化或改写原文。

Markdownlint 通过不可预测的生成 JSON pointer，在上游 rc 合并之后隔离捕获的规则 对象。拒绝可执行配置、自定义规则加载器与递归 extends。Vale 使用显式捕获 INI、 --no-global 和复制的声明式风格；不支持 sync、packages、actions、scripts、转换 或风格流水线。Lychee 接受有界 timeout、max_retries 与 max_concurrency 设置，以及字面 cache = false；缓存保持关闭，拒绝 cache = true。拒绝预处理器 与任意命令选项。

默认离线。没有显式 --network 时，不调用 lychee，连版本探测也不运行：可选覆盖 为 not_checked，必需覆盖为未完成 2。它只接收实际 Hugo 输出观察到的外部 HTTP(S) 引用；本地链接仍归原生检查。确定失败的 4xx 响应属于政策发现项，但 401、403、408、425 与 429 除外；这些状态、5xx、DNS/TLS 失败和 超时属于不确定结果，必需时返回 2，可选时保留遗漏。不验证外部片段、浏览器行为 或远端内容身份。发现项保留渲染输出文件与 DOM pointer，不从外部 URL 臆造 Markdown 行号。

子进程不接收调用者的代理 URL/凭据设置或 Node 预加载变量。已验证运行时可以传入 字面的 NO_PROXY/no_proxy 主机列表数据。这不保证所有操作系统代理路由都被 禁用，也不是操作系统网络沙箱。工具预备与任何联网操作仍是独立显式动作；这些 命令不安装工具。

离线与兼容性边界

受管理子进程默认离线。依赖缺失属于未完成工作。--network 为当前操作显式启用 联网，不能与 --offline 同时使用。隔离检查可以从已准备的本地模块为临时缓存提供 依赖。在临时缓存下载，并不承诺下一次调用拥有持久缓存。

只有模块下载制品会用于预备缓存，隔离资源缓存从空目录开始。CLI 不复用全局 GetRemote 缓存来承诺远程资源构建可离线运行。必需资源应作为本地输入提供，或为 该次操作显式启用联网。

CLI 不下载 Go 工具链，不安装软件包，不修改全局配置，也不启用遥测。进程政策不是 操作系统网络沙箱。兼容验证记录应区分普通离线执行与确实在操作系统边界禁止出站的 测试。

兼容性依据已执行证据声明，不从交叉编译成功推导。本地候选已经实测 macOS arm64、 Hugo Extended 0.166.0 和公开 OINK v1.1.0；版本门禁接受 Hugo Extended 0.160.1 或更新版本，但不声称这些版本都已测试。初始化站点保留普通 Hugo 输入，移除 CLI 后 只需要站点文档要求的依赖。

已撤下本地 Studio

CLI 移除 studio。使用普通编辑器与 oink dev 预览站点；通过 inspect 及结构化报告读取维护事实。带日期 R7 验收保留为对应输入的历史证据。

已撤下管理 API

CLI 不再提供管理 API，旧 Studio API 验收不代表当前可执行程序。

历史捕获限制

历史 R7 限制归属带日期验收记录；当前命令覆盖与输入范围以本契约为准。

已撤下通用编辑

移除 edit 与 Studio 编辑。使用普通编辑器修改源码，再运行 check。 new、move、审阅记录与基线计划继续保留候选验证和字节/模式保护。 旧编辑计划会被拒绝，带日期 R8 记录保留为历史证据。

已撤下文本和字段编辑

CLI 不再承担通用文本或 front matter 编辑表单。

已撤下片段和附件编辑

使用站点编辑器编写 Markdown、添加附件。CLI 不再提供片段目录或通用附件编辑命令。

已撤下 Studio 编辑

CLI 不提供编辑器，也不接受浏览器 Apply 请求。

验证与剩余范围

使用 make test 验证离线 Go 测试与 vet；使用 make test-hugo 验证真实 Hugo， 并为已配置可选工具运行 make test-tools。跳过集成不等于通过。 当前实现修改需要绑定新的源码与二进制证据；历史记录不自动赋予当前版本运行资格。

带日期维护验收记录 保留旧 R1–R8 与 A18 证据。声明目标为 macOS arm64、Linux arm64/amd64， Darwin amd64 是未取得资格的实验目标，Windows 不受支持。归档生成、签名、 分发、消费者采用与部署是不同状态。此契约不授权自动提交、推送、发布或部署。

6.6 - Paper 与 Slate 视觉预设

决策

Paper 成为默认，使用暖纸色与墨色、蓝色链接、IBM Plex Sans、标题细线和外框 表格。Slate 保留 v1.1.0 色板、Inter/Chakra/Plex Mono 字体角色与 Landing 网格、 光晕。这样为阅读站点提供更安静的默认外观，同时保留明确的兼容选项。代价是默认 外观发生可见变化：原站点可设置 params.ui.preset: slate。1.2.0 发布注记与升级指南已醒目说明此变化。

读者菜单默认关闭（preset_menu: false），文档站开启。一个外观入口包含原生 风格与明暗单选组，手机通过浏览器顶层模态 dialog 显示底部表单。触屏和键盘无需 悬停即可使用。代价是原来单击即切明暗变成选择面板；t 快捷键仍可直接切换明暗。

风格与明暗使用不同的属性和存储键。选择站点默认预设清除风格键。Hugo 在无 JavaScript 时输出默认值，白名单内联脚本在 CSS 前恢复读者选择，避免初始预设 不一致；禁用存储时仍可操作。预设共用一个样式表，代价是增加少量 CSS。

brand 将字标与展示标题分开。Paper 新增本地 OFL IBM Plex Sans 可变字体，包含 正体、斜体和六个小型文字系统子集，按实际使用下载。系统排版与显式字体角色覆盖 仍优先，中文使用系统栈。第一阶段不加入衬线字体，不新增外部字体请求。

密度由页面任务决定：首页保留展示尺度，长文保留阅读行宽，导航与参数表保持紧凑。 不统一扩大间距，不引入第二套外壳或几何抽象。Giscus 和打印跟随预设，API 供应商 组件与图表保持现有的明暗行为，以此约束第一阶段范围。

后续工作

10 月 5 日随后开展的实验在显式配置后提供 Ink 与 Terminal，见 实验记录。两者尚未成为 稳定默认选项。preset_menu: true 提供 Paper/Slate 与站点默认值；显式列表可以 展示实验。四种风格共用简洁的图标与名称按钮，不另加实验标记。这样可用真实主题 输出评审，同时保留普通菜单的 选项范围，代价是额外的局部 CSS，以及开启实验后更大的菜单。

实验以主题自有组件规则实现直角/2 px 圆角与紧凑桌面导航，不引入全局密度框架。 复用现有本地字体、状态管理与无障碍控件。图表和 API 供应商组件仍只随明暗变化， 评论色板与打印跟随实验预设。剩余工作是视觉定稿、更广设备评审，以及是否晋升为 稳定选项的决定。

依据

架构契约与 外壳契约管理当前行为。 check-presets.py 管理 token 对称、AA 色板、冻结的 Slate v1.1.0 色板及严格配置 输出。字体、参数、vendor、命名空间、动作与运行时检查继续沿用原归属。文档站的 appearance.spec.mjs 检查真实输出；带日期验收记录 区分已执行检查与后续实验。

7 - 设计研究

只有其他维护者能够检查方法、理解边界并复现相关检查时，研究才适合进入公开 Design 内容树。 原始 Agent 对话、临时构建日志和本机绝对路径不符合这一标准。

研究地图

发布规则

研究记录必须说明日期、输入、相关版本、方法、结果与已知边界。容易变化的数字明确标为快照。 涉及外部框架的比较，公开前要依据一手资料重新核验，并提炼成与 OINK 有关的结论，不能直接 复制成竞品目录。

研究结果成为稳定产品选择后，从已接受的决策链接它；如果它提出的 行为尚不存在，则把设计问题放入提案。

7.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 输出检查，再更新 这份快照。

7.2 - Ink 与 Terminal 实验，2026-10-05

输入与方法

本实验基于 10 月 5 日工作树中的 Paper/Slate 实现。 工具为 macOS ARM64 上的 Hugo Extended 0.166.0、Go 1.27.1、Node 26.9.0、 Playwright 1.62.1。集成检查使用文档站与同级本地主题；站点公开 pin 仍为 v1.1.0。 这不是兼容下限、CI 固定工具链或线上验收。

首页、配置、提示块与标签页以相同内容比较四套预设、EN/ZH、390/1440 px 和浅深色。 检查真实字体、溢出、外观控件与本地字体请求。进一步的组件检查覆盖代码、参数字段、 Blog、Book、API、Mermaid、ECharts、搜索与打印。沿用站点既有边界，axe 不检查 API 供应商自有 DOM。

设计选择

Ink 使用 #ffffff / #0b0b0b 画布、#141414 / #ededed 正文与 #c8102e / #ff5c4d 强调。Terminal 使用 #f4f5f2 / #0c0f0e 画布、 #1d211f / #d3dbd6 正文、#0a6560 / #4cc9bd 链接与 #935400 / #f0a73a 强调。站点与栏目强调色覆盖仍然优先。 Terminal 的标题标记使用空的无障碍替代文字，不支持的引擎省略标记。首页光标为 静态图形，不引入打字、闪烁、扫描线或发光效果。

试用

params:
  ui:
    preset: paper
    preset_menu: [paper, slate, ink, terminal]
    dark_mode: true

本地文档站已开启此列表。在外观菜单选择 Ink 或 Terminal，再独立选择亮色、暗色或 跟随系统。10 月 5 日菜单修订后，四个选项统一使用图标与名称按钮，不显示实验标记。 站点可以直接将任一实验设为 preset，不依赖读者菜单。preset_menu: true 仍提供 Paper/Slate 与站点默认值，不包含所有实验。选择站点默认预设会清除保存的预设。 字体覆盖、系统排版与 CSS 加载前初始化沿用 Paper/Slate 的契约。

验证

标准 sitemap axe 检查限定 15 个路径：EN/ZH 首页、配置、提示块、标签页、OpenAPI； 英文搜索、Mermaid、ECharts、Blog 与 /book/04-design/。既有响应式 axe 矩阵另行 运行，这不是全站穷举。标准浏览器检查使用既有 4173 样例服务器；引擎专项使用来源 已确认的同级主题 1313 开发服务器。外观矩阵未观察到外部字体请求。

首次默认 Terminal 字体构建发现建议性背景亮度表漏项，造成强调色对比度误报警。 现已登记两套实验背景，并由检查器断言与显式强调色样例覆盖。修正后仅重跑受影响的 外观套件。新增研究索引和更新的提案描述经逐项审阅后，刷新 LLMS golden 中对应的 两处变化。

实验暴露了两处新增样式问题：全局禁用下划线的规则覆盖了 Ink 链接，Terminal 搜索 选中行的摘要仍使用弱化文字色。两者均作了局部修正。另一个继承问题是 Mermaid 深色 标签（#cccccc 配 #585858，4.43:1），在 Paper 与 Slate 中同样复现。共享的 明暗色板默认标签背景现改为 #404040，作者显式配置仍优先；没有引入预设图表色板。

后续工作

晋升稳定选项前仍需真实 Windows 与 Android 设备评审，包括中文回退字体、下划线、 等宽标题换行与长参数表。人工屏幕阅读器朗读和首屏逐帧截图仍未验证；CSS 初始化 顺序检查不保证每个绘制帧。

Mermaid/ECharts 保留明暗色板，API 组件保留供应商样式；Giscus 检查针对生成的 色板资源，而非远端 iframe。实验没有引入完整几何/密度 token 框架。是否晋升 Ink/Terminal、是否重做图表色板仍待决定。本记录不包含提交、推送、发布、消费站点 升级或部署。

7.3 - OINK 1.2 发布前审查，2026-10-05

范围与输入

主题起点为 a1979a4，文档站起点为 ed2d0e3。受检工作树还包括 CJK 关键词 摘要、字面百分号大纲与仓库源文件路径修复，站点既有的英文编辑修改，以及下列 清理。独立可选 CLI 不属于本次主题发布范围。没有打标签、推送、升级消费站或部署。

多数检查使用 macOS ARM64 上的 Hugo Extended 0.166.0、Go 1.27.1、 Node 26.9.0 和 Playwright 1.62.1。选定兼容性检查使用经校验和验证的官方 Hugo Extended 0.160.1、0.165.0 二进制。这些是本地结果，不是完整 Linux CI 工具链的复跑结果。

审查发现与清理

这些清理没有要求新增运行时修改。工作树原有运行时修复由各自检查器及最终集成 测试覆盖。

已执行验证

本地候选版本通过下列技术性发布前检查，在受检范围内没有发现阻塞发布的主题 缺陷。数字均为本次工作树审查的带日期快照。

完整 sitemap 扫描沿用站点现有 axe 策略：检查 OINK 维护的界面，阻断 Giscus 请求，排除 Swagger UI/Redoc 的供应商 DOM。结果不代表这些组件自身的无障碍 验收。响应式检查覆盖 360、768、820、1024、1200、1440 px，以及中英文、浅深色。

外观检查在四套预设、中英文、390/1440 px、浅深色下使用相同首页、配置、提示块 与标签页内容；也覆盖搜索、代码、表格、输入/焦点状态、Blog、Book、API、图表 与打印。Ink、Terminal 仍需显式选择，测试通过不等于把实验提升为稳定预设。

出版使用本地 Pandoc 3.11、Java 26 和 Chrome headless-shell 151.0.7922.34。 第一次使用完整 Chrome for Testing 应用时在本机超时。像 CI 一样显式选择 headless-shell 后，生成的 PDF 通过验证。结果不代表所有 Chrome 安装均兼容； CI 在 Linux 上固定 Pandoc 3.10 与 Java 21。

本地优先的资源边界

IBM Plex Sans、Inter、IBM Plex Mono、Chakra Petch、图标、KaTeX 字体与 核心浏览器库均已本地化。预设切换没有引入运行时字体服务或 CDN 脚本依赖。 系统字体模式与显式字体角色覆盖保留其约定优先级。

生产审计在每套预设下访问首页、中文配置、数学、Mermaid、Markmap、ECharts 及 OpenAPI，再切换浅深色。测试保留生产 base origin，由本地产物提供响应。 请求追踪记录并阻断跨 origin 请求；本地字体与图表仍加载成功，没有未捕获 JavaScript 异常或本地 HTTP 错误。

两个已配置服务会请求外部脚本：Giscus 与 Google Analytics。Giscus 是已接受的 可选评论集成，其 OINK 色板文件来自本地。文档站原本配置了统计 ID，因此生产 产物包含 Google Tag Manager 脚本。二者都不是新预设的必要依赖。本次保留 这些配置，文档站因此不作“零外部请求”的承诺。作者引用的远程媒体与显式选用的 图表服务也保留既有可选边界。

复现检查

先运行主题归属检查，再检查真实站点。以下命令通过约定的 Make 目标选择同级 主题，不能把文件系统模块替换提交进仓库：

python3 bin/check-presets.py
node --test 'tests/js/**/*.test.js'
make -C ../oink.pgsty.com check
env -u A11Y_PATHS -u PLAYWRIGHT_BASE_URL make -C ../oink.pgsty.com browser

完整主题检查器与出版命令定义在 .github/workflows/ci.yml。用新构建的 fixture 运行所有归属检查，覆盖参数/Schema、vendor/字体、导航/搜索/操作、组件、 产物/命名空间/golden、迁移、快照保护、消费站工具及 PDF 隔离。 文档站的独立引擎套件为 npm run test:appearance:engines。

兼容性检查将选定 Hugo 二进制放入 PATH，禁用继承的 Go/Hugo workspace， 并明确同级模块替换。真实站点用 --environment production --minify --printPathWarnings --panicOnWarning 构建到独立输出目录。检查已发布 pin 时， 还须禁用模块替换；两者是不同验证目标。

剩余发布步骤与边界

本地技术性发布前验收通过。正式发布仍需把受检修改整理为提交， 在这些精确提交上运行 CI，发布标签及模块归档，完成消费站采用与托管验证。 仅修改版本号不能替代这些步骤。发布说明仍为草案，既有消费站 pin 没有改变。

尚未验证真实 Windows/Android 设备上的字体表现、人工屏幕阅读器朗读与首绘 逐帧画面。Windows 源文件路径行为使用确定性 fixture 验证，没有使用 Windows 主机。Ink/Terminal 设计后续项仍见 实验记录。

7.4 - 视觉预设验收，2026-10-05

输入

2026-10-05 的主题与文档站工作树；macOS ARM64，Hugo Extended 0.166.0、 Go 1.27.1、Node 26.9.0、Playwright 1.62.1。常规浏览器套件使用 Chromium； 另有 Chromium、Firefox 与 WebKit 专项检查。站点仍固定 v1.1.0， make check、make browser 与 make dev 使用同级本地主题，公开 pin 未修改。 本轮不是 Hugo 0.160.1 下限或 CI 固定工具链验收。

已执行检查

浏览器套件的 sitemap axe 扫描通过 A11Y_PATHS 限定为 15 条代表性路由：中英文 首页、配置、提示块、标签页与 OpenAPI，以及英文搜索、Mermaid、ECharts、Blog 和一个 Book 章节。另运行现有响应式 axe 矩阵。跨域 Giscus 与 API 供应商组件 DOM 沿用既有排除规则，本轮不是全量 sitemap 扫描。

整合检查发现并修复了 Paper 深色高亮代码行的行号对比度，以及平滑滚动干扰阅读 锚点恢复的问题。章节强调色测试现在分别断言 Paper 的暖色不透明选中底和 Slate 原有的半透明选中底。

限制与后续检查

手工读屏播报和逐帧绘制追踪尚未验证。阻塞样式表及 CPU 限速断言验证初始化顺序， 不等同于证明所有浏览器的首个绘制帧。Slate 比较冻结基础色板并检查渲染字体行为， 不宣称包含其他 1.2 改动后的所有组件与 1.1.0 像素等价。

Mermaid/ECharts 继续仅随明暗。Ink 与 Terminal 仍为研究；衬线展示标题、完整 几何与密度 token、图表随预设配色留待后续。本轮没有创建发布标签、推送、跨站 升级或部署。

7.5 - 消费站与迁移证据

语料

创作语料盘点扫描了十一个 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 边界见 创作书籍和 迁移契约。

出版采纳快照

2026-08-24 的隔离验证让两个消费站运行了已发布的通用 Book 出版链路：

这是下游采纳证据，不是尚未解决的上游设计边界。

边界

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

7.6 - 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/契约，本次没有重新发布或部署任何站点。

7.7 - 社区 Issue 与 PR 调研，2026-09-19

以下保留最初的调研快照。随后维护者决定先合并 PR #43，再直接在 main 实施其余修复； 最新进展见同日实施与验收补记。

判断结论

这些反馈都有值得处理的内容，但不能全部归为同一种缺陷。应优先修复隐藏导航仍能获得焦点的问题。 PR #43 的小修复方向正确，明确边界并补齐测试后可以接收。搜索尾部扩展与侧栏状态公开接口则属于 新增 API，应分别设计和验收。

基线与方法

通过 GitHub API 查到 4 个未关闭的外部 Issue 和 1 个未关闭的外部 PR。另一个未关闭的 #37 是维护者自己的版本发布跟踪项。 截至本次快照，这些外部反馈尚无讨论评论，PR 也没有已提交的 review。

Design 中的 released-v1.1.0 标记和本地发布准备提交，不构成 v1.1.0 已经公开发布的证据。 源码修改、标签、消费站版本固定与线上部署仍是不同状态。本次没有升级公开消费站。

调研覆盖完整 Issue/PR 正文与评论、精确 diff、双语 Design 契约、相关模板和 JavaScript、 部署在 /sub/ 下的临时双语站点，以及真实文档站的定向浏览器交互。共享工作区中的主题实现未改动。

PR 43：接收小修复，明确它解决到哪里

root-menu-roots.html 第一轮收集顶层分区时会检查 sidebar_root_menu；第二轮收集 sidebar_root_for: self 分区时没有检查。于是第一轮已排除的节点又被第二轮加回来。

PR 给第二轮补上同样的显式 false 判断：

{{- if and .IsSection (ne .Params.sidebar_root_menu false) -}}

这保留了未配置和配置为 true 时的默认行为，也保留了分区类型约束与 URL 去重，不改变侧栏树及 翻页顺序，不破坏按语言缓存。没有必要为这一个遗漏重构整个导航系统。

但是，后面的 root-menu-entries.html 还会把不在集合中的当前根追加回来。这是已有行为，导航指南也提到最后追加当前根，不能误报为 PR 引入的新回归；但它意味着不能宣称“设成 false 后，在所有页面都不再显示”。

临时复现站包含一个顶层 Blog 自根、一个嵌套 Docs 自根，二者均设 sidebar_root_for: self 和 sidebar_root_menu: false，另有可见 Docs 根和未覆盖可见性的自根。 英文、中文结果一致，URL 都正确保留 /sub/ 与语言前缀：

建议把契约明确为：false 将节点排除在全站可选根集合之外，但当前根可为位置提示而保留。 保留这个已有例外是改动最小、最兼容的解释，需要在两种语言中写清楚。如果真正希望 false 表示绝对排除，就要另行协调修改当前根回退和切换器标题逻辑，并检查零入口、单入口状态。 只再加一个条件，不足以完成这项语义变化。

合并前应补齐：

1. 在 bin/check-shell.py 增加输出测试，覆盖顶层与嵌套隐藏自根、未设置/true、去重、当前根 例外、单入口退化，以及 EN/ZH 子路径。
2. 同步更新 Shell 契约与导航指南。PR 描述示例里的 YAML 注释 // 也应改成 #，保证可复制。
3. 处理工作流的 action_required 状态，在最终 HEAD 上运行 必要检查。截至快照，PR HEAD 没有成功的 check run 或 commit status。API 返回 MERGEABLE、UNSTABLE，这两个状态都不等于测试通过。

维护者可以保留贡献者的提交并补上这些收尾工作。不应把实现 #40 或完整 #41 作为接收这行修复的前提。

Issue 41：先修隔离，再公开状态

这里有两件不同的事。

第一，整栏隐藏主要依靠 transform，桌面还使用 opacity；抽屉和折叠控制器没有将隐藏控件移出键盘 导航。在浏览器实测中，点击折叠按钮后，焦点留在已经透明的折叠按钮上，再按 Tab 就进入隐藏的根 切换按钮。此时面板 opacity 为零，也没有生效的 inert 或 aria-hidden 祖先。这是可复现的 使用缺陷，不只是缺少给集成方调用的接口。移动端关闭面板的实现同样仅移到屏幕外，没有显式隔离。

第二，展开状态分别由 点击控制器、响应式搬迁 和 缓存活动路径补全 直接写入，没有公开 setter、getter 或状态提交事件。现在对整栏折叠、宽度和滚动位置的存储，并不 等于每个分支的展开选择能跨页面持久保存。创作指南中“读者的展开状态保存在本地”也需要说明这个区别。

建议分步处理：

1. 集中处理整栏隔离，在初始化及打开、关闭、折叠、悬浮展开、恢复和断点切换时同步更新。 先解除隔离再把焦点移进去；关闭时先把焦点归还给可见的外部控件，再使内容 inert。
2. 隔离内容区，同时保留外部恢复按钮和桌面边缘的悬浮感应区域。直接把感应区域一起 inert 会破坏 已有悬浮行为。仅用 aria-hidden 不能阻止键盘进入； HTML 的 inert 定义 同时约束交互与无障碍树暴露。
3. 将分支展开修改另行收敛到一个提交函数：更新 aria-expanded、展开 class 和本地化标签后， 再发送一次事件；重复写入同一状态不重复通知。
4. 在定义稳定 ID、非法 ID 处理、初始化就绪信号和恢复次序后，再公开最小 setter/getter 与事件。 版本和语言的存储命名空间继续由下游管理，恢复后以当前活动路径展开为准。

原提案有一处范围需要校正：TOC、反向链接和分类法分组在宽屏时会从侧栏移回右栏。 如果控制器只查询“当前侧栏 DOM 下的后代”，就无法同时管理宽屏时的这些写入。 应按 OINK 管理的目标注册元素，不依赖其当下 DOM 父节点；对外的侧栏 API 则只开放约定的注册子集。

验收必须检查隐藏状态下的真实 Tab 顺序与无障碍树、初次载入时恢复折叠、悬浮进出、焦点归还、 Escape、遮罩关闭、滚动解锁，以及 768/1200 断点。还要保留 #24 已修好的无 JavaScript 导航。 静态 axe 扫描通过、或者测试“抽屉可以打开”，不能证明这些状态转换正确。

Issue 44：现象真实，部分行为符合预期

在文档站配置页分别点击文章标题、表头单元格和代码块，会让 main#td-main-content、 div.td-table-scroll、pre.chroma 获得焦点。三者在点击后都不匹配 :focus-visible，按下未绑定 快捷键的字母 z 后都开始匹配。正文和代码块出现浏览器的 auto outline，表格使用主题的实线 outline。这说明不需要作者的 Linux 桌面或 Super 键，也能复现相同机制。

Selectors 规范 明确描述了这种情况：键盘交互可以改变焦点提示，即使焦点元素没有变化。因此，这是一条有价值的 阅读体验反馈，但“鼠标聚焦之后，无论再按什么键都不该出现框”不是浏览器必须遵守的正确性要求。

建议这样处理：

• 保留 main 作为跳过导航的目标以及它的可聚焦性，把包围整栏的 outline 改成正文入口附近的局部 可见提示，例如标题区提示，并实际验证 skip link。
• 保留可滚动表格和代码块的键盘焦点提示，必要时统一其视觉样式。可聚焦性使键盘滚动成为可能。
• 不做全局 outline: none，不删除所有 tabindex，不在任意按键后主动 blur。
• 如果产品仍决定抑制“鼠标先聚焦再阅读按键”这一路径，需要明确新增语义，只限定这些非编辑容器， 并验证鼠标、Tab、skip link、程序聚焦、深色及强制颜色模式。为这条反馈建立全站输入模式框架 并不划算。

本次证据支持小范围的显示改进，不支持为了消除现象而直接取消表格和代码块的键盘提示。

Issue 42：区分隐藏与分组

提问写的是 _index.json，并依赖截图而没有提供源码复现。本次未能成功完成原始截图的视觉核验， 第一项需求具体想改变哪里仍需澄清。回复时应请作者提供小目录树及实际 index/front matter， 不能没有证据就断言 _index.json 是受支持的页面源文件或只是笔误。

现有选项的含义并不相同：

临时站点确认：带 divider 的分区，其子页面 HTML 仍然存在，但侧栏子链接消失；仅设置 build.render: link 的分区没有自己的 HTML，侧栏中却仍有可点击的分区链接和子页。 这与 Hugo 的 构建选项定义 以及主题的 共享节点渲染器 一致。

如果真实需求就是“保留分组标题和子链接，但标题不跳转到目录页”，优先考虑补齐 sidebar_divider 在分区节点上的行为：叶子分隔项保持原样，有子项的分区保留 children，允许折叠 时使用真正的 disclosure button。决定前应检查已有消费站；只有现有 divider 契约无法兼容表达时， 才增加独立的节点级开关。“是否生成分区页面”与“导航标题是否可点击”应分别处理。

实现必须保留两套遍历器中的层级和活动路径展开，使子页继续进入翻页顺序。如果目录页确实不发布， 还要检查面包屑、搜索、根切换器、Print 和机器可读导航，不能留下死链接。直接用 CSS 隐藏整个节点 解决不了这个需求。

Issue 40：可以接受范围受限的扩展方向

源码核实了提案指出的限制： groupsFor 只组合内置页面和操作；公开 Palette 对象没有 provider 注册接口； registerExecutor 只允许内置 action ID。静态 URL command 无法替代携带当前查询的结果行。 现有 Palette/controller 测试通过，证明已有功能能工作，不能证明该扩展能力已经存在。

提议的 search-tail 位置是合理的上游接口边界：同步返回纯数据行、异步执行操作、本地结果优先， 由 OINK 管理渲染、选择、键盘和 ARIA。OINK 不需要因此内置 AI 服务商、凭据、远程搜索或通用插件系统。

接受 API 前，需要定清并测试：

1. 只在哪些已完成的文本搜索状态调用 provider；保留空查询、命令、选择、加载中，以及未注册扩展时 的原有行为。
2. 保存生成每一行时的 query/locale 快照，保留原生空结果、索引错误及重试提示，区分本地页面数与 全部可选择操作数。
3. 校验并复制 descriptor，把标题和描述当文本渲染；隔离 provider 异常、重复 ID 和非法描述符。
4. 同时处理同步 throw、Promise rejection、pending 释放、重复激活、旧会话取消，以及 ID 重用后的 旧 unregister 句柄。
5. 验证向另一个对话框移交焦点。现有 Palette 关闭逻辑已经会在焦点移出后避免强行归还，应保留这个 判断。还要区分“成功把交互交给新界面”和“取消”，否则“任何 close 都 abort 激活”的规则可能 把刚打开的助手操作一并取消。
6. 保持默认查询不出浏览器和按需加载资源的行为。对受信任站点脚本约定 rows() 纯净，不等于主题 有能力建立安全沙箱。

实现前，应把接受的 API 形状沉淀为双语 Design 提案。下游 Ask AI 包装可以继续使用，直到公开标签 包含该接口。它不应成为小型正确性修复的发布前提。

实施顺序与归属

每项公共行为修改先跑对应检查器，再通过同级文档站的 make check、make browser、make dev 做相关集成与视觉验收。不要把这些不同需求绑成一次大规模侧栏/搜索重写，也不要等待所有新功能 完成才交付小修复。

建议回复内容，尚未发送：对 #43 承认过滤遗漏并解释当前根例外；对 #41 接受隔离缺陷、拆开 API 诉求；对 #44 确认复现并说明标准焦点机制；给 #42 解释配置区别并索取最小输入；把 #40 归为受限 扩展需求，而非本地搜索故障。

历史外部反馈已经关闭：#22 通过开启 Goldmark passthrough 解决，提问者明确确认有效；#21 已提供 Mermaid 查看器与 固定居中展示，任意右对齐选项则明确没有纳入。二者不应被算作新的待处理缺陷。

验证结果与边界

本次实际执行：

• 本地基线及 PR #43 精确 HEAD 的隔离 checkout 均通过 python3 bin/check-shell.py。
• Palette 控制器和模型测试通过，共 2 个测试文件，零失败。
• 对真实 PR diff 应用前后分别进行严格 Hugo 临时构建，在 EN/ZH 与 /sub/ 下复现自根过滤和 当前根回退；同一 fixture 验证了分组配置的限制。
• 真实双语文档站使用本地主题，通过带 --panicOnWarning 的构建；Chromium 定向交互复现三个 容器的焦点边框，以及桌面侧栏隐藏后的焦点问题。
• 文档站双语覆盖、渲染与链接检查通过，非浏览器套件的 57 项测试均已通过。首次 make check 因新增报告改变 llms.txt 索引而停在快照检查；确认仅新增报告这一行、同步快照后，重跑该组 及其余测试组全部成功。

新增缺陷断言属于调研探针，尚未成为提交到仓库的回归测试。本次不是完整发布验收，也没有跑所有 浏览器矩阵。本地 Hugo 为 0.166.0，并非 CI 固定的 0.165.0 或声明的 0.160.1 兼容性下限。 Linux Super 键、移动端无障碍树隔离、深色/强制颜色模式及作者 #42 的精确截图，还需要上述验收覆盖。 本次未改变线上部署、公开版本、消费站依赖或上游讨论。

实施与验收补记

维护者决定先合并贡献者补丁，再直接在 main 完成修复与扩展，不另提 PR。 PR #43 已合并为 6e814089， 随后拉取到本地，保留原有发布说明提交。第二阶段实施提交为 56bfe37。

使用同级主题 checkout，在 macOS、Hugo Extended 0.166.0、Node 26.9.0 与 Chromium 上完成：

• 主题 JavaScript 测试 44 项全部通过。
• check-shell.py、check-reading.py、check-palette.py、check-keyboard.py 通过。 按主题 CI 配置扩大检查，另外 31 条命令中 29 条通过；本地两项失败来自媒体检查器固定的图片处理 指纹，以及四份黄金文件中 Hugo 0.166 改变的 KaTeX 输出。保留原有空白格式后，普通导航标记与 黄金文件一致。固定 CI 工具链的结果单独核验，不因此改写无关预期。
• make -C ../oink.pgsty.com check 通过：双语源文件、渲染与链接检查，以及 57 项非浏览器测试。
• make -C ../oink.pgsty.com browser 共 141 项通过：无障碍 30，响应式／博客／Palette 45， 键盘 16，内容 10，代码块 18，场景 4，主题色 5，社区回归 13。无障碍套件包含完整双语站点地图逐页扫描。
• 主题 fixture 严格构建、输出与命名空间检查通过。Book 本地打包生成五章 EPUB，检查零错误； PDF 为 23 页，包含全部五个预期 Book 页面，检查零错误。
• 通过 make dev 在真实文档站实测桌面亮色、中文暗色、折叠侧栏恢复，以及 375px 移动抽屉。 Escape 关闭后焦点回到可见的打开按钮。验收后已恢复浏览器视口并清理临时开发服务。

已接受的契约写入 Shell 与架构， 中英文同步，并更新导航、组织内容、Palette 和 Print 指南。集成回归留在文档站仓库，主题只保留 专项检查器和合成输入。

PR 合并提交的固定工具链 CI 三个任务全部通过。最终实施提交的 CI 也已全部通过，精确版本为 56bfe37092a43fc12c0e16f865d3d3407c55cbde：Hugo 0.165.0、 浏览器运行时测试与 Book 出版三个任务均成功，包含本地 Hugo 0.166.0 出现差异的媒体和 四状态黄金文件检查，以及根路径／子路径出版。声明的 0.160.1 兼容性下限没有额外复测； 本项目固定的持续测试工具链仍为 0.165.0。

这是源码与集成验收，并非新版本发布：没有创建新标签，文档站仍固定 v1.0.0，生产站没有升级。 同级文档与测试变更在本地 main 为下一次主题发布准备；若立即推送新增浏览器门禁，远端会拿旧公开 依赖测试新接口，无法构成正确验收。本次没有发送贡献者回复，#40、#41、#42、#44 仍保持打开状态。 #42 原始截图和报告中的 Linux Super 键环境没有独立复现；明确的纯分组需求及等价的“点击后按键” 路径已按上表实测。

图片复制补记

维护者另行报告：把博客文章复制到富文本编辑器后，图片下面出现预览提示。博客固定 OINK v1.0.0，并开启 params.ui.image_zoom。该版本与本次审查的 main 都会在每张 符合条件的图片后插入一个视觉隐藏的文字 span。Chromium 原生复制已复现剪贴板额外 带入“打开图片预览”及对应英文文字，因此这是独立于目标编辑器的主题缺陷。

主题提交 75052f8 把图片描述与本地化 操作改放到按钮的 aria-label，不再向文章插入辅助文字节点。图片 alt、作者图注、 原生按钮操作和对话框焦点归还均保留。组件契约 与图片指南 已同步说明复制行为。

check-image-zoom.py 与站点全部 57 项非浏览器测试通过。专项浏览器验收 16 项通过： 14 项内容组件测试，其中包含新增的中英文图片／画廊四项剪贴板回归，以及桌面亮色／ 手机暗色两项对话框无障碍检查。回归读取纯文本与 HTML 两种剪贴板格式，检查脱离样式 后的文字，并核对图片地址、alt、图注和按钮的无障碍名称。

本次没有在真实知乎编辑器里做粘贴验收。博客依赖与线上部署保持原状；消费站升级主题 依赖并重新构建后，公开页面才会获得修复。

7.8 - OINK 1.1 发布审查，2026-09-20

范围与基线

审查从主题提交 75052f8a3106d13ef313644836a5ad545135f484 开始，此时社区反馈与图片复制修复已经进入 main。范围包括 v1.0.0..main 差异、 #40、 #41、 #42、 #44 与已合并 PR #43 所要求的行为，以及双语文档和发布边界。 前一轮调研 记录了原始反馈及其实施过程。

方法是检查拥有相关行为的 JavaScript、模板与契约，通过定向回归覆盖状态转换，比较修复前 失败断言与修复后的实现，再运行主题检查器和真实同级文档站的集成、浏览器套件。本轮不扩展 新的功能计划，也不声称进行无边界的完整安全审计。

截至本次快照，公开版本、文档站 go.mod 固定依赖与配置中的公开版本仍为 v1.0.0。 博客消费站固定的主题版本保持不变。

发现与修复

本轮复现并修复了五项 P2 正确性缺陷，已提交为 08f6563 并推送 main。它们涉及新增 API 的时序和既有焦点、导航行为， 不需要新增配置格式或迁移正文内容。

实现与回归归属：

修复前，就绪时序与待完成选择的新增单测在旧实现上失败；右栏隔离的浏览器断言也在中英文 两种页面上失败。修复保持局部：调整就绪通知时序、提前一项 pending 检查、明确右栏隔离、 补齐树焦点目标和抽屉可见性过滤。

这些改动保留已有结果：两个根收集器都遵守 sidebar_root_menu: false；无链接分组保留 子页；指针聚焦不引入正文大边框，键盘提示仍然可见；搜索扩展保留取消与交接契约。图片预览 继续通过无障碍名称表达操作，不向复制的正文插入辅助文字。最终回归结果在下方单独记录， 不由源码检查推断通过。

文档准备

当前使用文档更新覆盖 28 个文件、14 组 EN/ZH 页面：

• 六组 Design 契约使用 candidate-v1.1.0，描述 main 已实现行为，不提前声明正式发布。
• 导航、布局和 front matter 指南对齐根过滤、分隔分组、双语部署路径、居中顶栏、窄屏抽屉 与原位淡入的顶栏行为。
• 内容组织和命令面板指南说明运行时加载顺序、就绪、能力检测，以及站点负责的持久化和集成。 键盘与图片指南说明修复行为和旧版本边界。
• 安装指南区分验收工具链与公开版本；既有标题 ID 保持稳定，新增侧栏 API 标题的中英文 ID 匹配。

另已准备两份 1.1.0 发布注记和两份升级指南。发布注记保持 draft/candidate 状态，首页中英 发布入口都回到已公开的 1.0 版本。这些源码修改没有更新站点模块依赖，也不代表新行为已经 部署。历史研究继续保留当时的观察，不为消除旧状态而重写。

验证快照

下表数字是主题 08f6563 在 2026-09-20 的验证快照。站点验收通过命令作用域内的模块 替换使用同级 checkout，不证明尚未发布的模块标签可用，也不代表已经部署到生产环境。 本地站点检查使用 Hugo Extended 0.166.0、Node 26.9.0 和 Playwright 1.62.1；候选版本 CI 使用固定的 Hugo 0.165.0 工具链。0.160.1 下限使用官方二进制单独验证。

在本轮审查与验收范围内，未发现尚未解决的实现阻断项，可以进入下方发布流程。

在同级 checkout 中复核，开发期间保留公开依赖固定版本：

# 在主题仓库执行
node --test tests/js/*.test.js
python3 bin/check-shell.py
python3 bin/check-palette.py
python3 bin/check-keyboard.py
python3 bin/check-image-zoom.py

# 站点 Make 目标使用命令作用域内的同级模块替换。
make -C ../oink.pgsty.com check
make -C ../oink.pgsty.com browser

待执行发布步骤

尚未执行发布。最终版本通过验收后：

1. 确定 CHANGELOG.md、发布日期与发布记录，从通过验证的主题提交发布 v1.1.0 标签 和 GitHub Release。
2. 验证模块代理可将该标签解析到预期提交。
3. 一并更新文档站固定依赖、版本配置、首页发布入口、契约状态，以及发布注记的 draft: false 状态。
4. 不使用 HUGO_MODULE_REPLACEMENTS，从已发布依赖重新构建并验收文档站，再部署 并检查公开路由。

最终结论必须标明被测主题提交，分别说明本地源码验收、公开模块可用与实际部署结果。

可以后续改进的是：为从 HTML 进入的 Agent 提供位置更靠前、一致的 llms.txt 发现提示。 这项评分告警不影响现有 Markdown 输出，也不要求在 1.1 前增加新功能。Safari/Firefox 检查与真实知乎编辑器粘贴验证也是有用的后续工作，本轮 Chromium 验收不涵盖它们。

限制

浏览器证据来自 Chromium，不是 Safari/Firefox 矩阵。无障碍门禁覆盖主题自有界面，保留 对 vendored Redoc 与 Swagger UI 的既有排除。原生剪贴板回归覆盖纯文本、富文本 HTML、图片描述与作者图注，但不证明真实知乎编辑器的粘贴行为。本轮没有修改或验收博客的 依赖固定版本及线上产物。Hugo 下限的定向检查，也不代表该版本上所有出版路径都已执行。

这是对明确源码与行为的发布准备审查，不声称无边界的安全覆盖、生产上线，或支持额外的新功能。

发布后续

审查之后，v1.1.0 正式版 已于 2026-09-20 从提交 3a18234 发布。该版本相对已验收的 08f6563 实现只修改更新日志。创建附注标签并发布稳定版 GitHub Release 前，全部三项发布提交 CI 均已通过。

仅使用官方 Go 模块代理、从全新缓存下载的版本准确解析到该提交。.info、.mod、 .zip、版本列表条目与签名校验和记录均已验证。模块校验和为 h1:121L5g57ChRCPyidzEBBcln2Co+0zYRQ+XDDXjymd0Q=，go.mod 校验和为 h1:pHvbUhJCfseB41n5RGwsF7abT3i32VSTpofLQoq4b7Y=。 公开记录见代理版本信息与 校验和条目。

文档站发布更新在 go.mod 与 go.sum 中固定 v1.1.0，同步公开版本标识和双语首页 入口，公开两篇发布注记，并将六对契约标记为 released-v1.1.0。上方历史验收表继续 描述此前的同级 checkout 运行。公开依赖的验证单独记录在本站的 Site checks 和 Browser quality 工作流中，两者均关闭 Go 与 Hugo 模块工作区。

本地使用该公开模块通过了全部 57 项非浏览器测试、26 项命令面板与社区问题浏览器测试， 以及严格生产构建（每种语言 378 页）。这些检查均设置 GOWORK=off、 HUGO_MODULE_WORKSPACE=off，且未使用 HUGO_MODULE_REPLACEMENTS。完整的 149 项 浏览器套件另由发布提交的 Browser quality 工作流执行；其结果与此前本地候选版本的 运行记录分别记录。

7.9 - 2026-10-03 CLI 维护验收

范围与证据规则

维护路线图 定义已授权的 R1–R8 范围，当前 CLI 契约 定义兼容基线。原路线图 不会把 Docsy 迁移、版本生命周期、OpenAPI、主题发布或条件性 E1–E4 扩展 加入本计划。Hugo 继续作为外部渲染器，生成站点仍是普通 Hugo 项目。

各阶段按依赖顺序验收。每阶段都需要完整可用的流程、归属测试、相关真实 Hugo 集成、已知限制、可审阅 diff，以及已验收的中英文契约和指南更新。 汇总命令通过不能自动关闭用例。新公开行为只有在实现和验收证据齐备后， 才从提案移入归属契约。

下表中的 已有，未重跑 表示已经检查代码或具名测试，但尚未确认本轮运行结果。 部分已有 表示首个候选提供了所需行为的一部分。未完成 表示缺少新实现或决定性验收证据。 后续记录 通过、失败、未验证 和 不支持 时，必须说明具体执行输入和范围。 历史结果不会改标为本轮通过。

已检查输入与工具

2026-10-03 的初始审计读取了两个仓库的指令、文档站 README 和翻译规则、 维护 PRD 的中英文文件、原提案、当前 CLI 契约，以及已有 Go 包和测试名称。 本次只执行版本与 Git 检查命令，没有运行归属测试套件，也没有写入消费站源码。

2026-09-29 验收记录 包含首个候选的历史检查，可提供复现输入，但不能证明新的维护范围。 保留已有脏文件；此次初始研究记录不会验收或覆盖它们。

阶段需求与实现证据

R1 本地验证

R1 现已提供共享 Hugo 页面/翻译/来源事实、产物引用与锚点证据、严格 oink.policy/v1 输入、check links、--format json、可见的经审阅排除/外部范围， 以及必需工作优先级。翻译和风格选择明确报告必需但不支持的覆盖，并非已实现引擎。 默认 build/dev 继续直接调用 Hugo。下列证据接受所测共享事实/政策范围， 不关闭 R2–R8 或完整 A01–A18 用例。

较早离线 R1 试验在三个消费站上均返回 0 且无发现项：

这些较早报告把可选未选中覆盖写为 not_selected，不属于已有结果 Schema 的枚举值。 最终代码已修正为 not_checked 并包含 project.pages 覆盖。 计数及精确清单仍是较早二进制的有效观察；下方最终刷新报告证明 JSON 合规。 原始证据保留在消费站源码外、带任务名称的本地验收目录。 这些试验不证明外链可访问性、部署、Linux 运行环境或翻译/风格验收。

最终 R1 二进制由基于 e623d93d589c49e5c58b8fae1bd5db720fc904cb 的 CLI 脏工作树重新构建。记录的输入清单包含文件哈希、模式和 Git 状态身份， 按排序后的 JSON 序列化计算 SHA-256 为 518260f07f3c916468ee3d56c4eeca03c131514155aa82539564ccd2f3c1f664。 实际运行二进制 SHA-256 为 3deb7e357fc86f6907df60da0769d93f2d41ba5e01949b641548a67d7f459d12。 它们标识本地输入和已执行二进制，不表示维护提交、公开归档或已发布模块。

最终结果均有必需的 check.links: complete 和 project.pages: complete。 未选中翻译/风格覆盖为可选的 not_checked。最终离线 make test 与 vet 通过， 修正后的真实 Hugo 归属目标也通过。记录的工具仍为 macOS arm64 上的 Go 1.27.1、 Hugo Extended 0.166.0、Git 2.54.0。编写本记录时独立比较了三个精确前后清单。

生产产物通过 Markdown 和链接检查。全站翻译检查返回 1，唯一原因是已有草稿 content/blog/release/1.2.0.md / .zh.md 正确地没有进入生产产物。 R1 修改页面均已双语渲染。另一个显式分析构建将 HUGO_BUILDDRAFTS、 HUGO_BUILDFUTURE 和 HUGO_BUILDEXPIRED 设为 true，三项归属检查均通过： 137/137 组源码、1,085 个标题、产物 Markdown 与产物链接。 该视图属于不可发布的排除源码证据，从未替代生产产物，也不修改或发布草稿。 没有为了让全站生产检查变绿而修改已有草稿文件。

R2 本地验收

本地候选已实现翻译政策/状态/diff/哈希审阅、有界原生内容规则、可见的经审阅基线， 以及共享 oink.plan/v1 预览/验证/应用。默认 check 要求链接、翻译和风格。 生产输出与显式草稿/未来/过期分析相互独立，后者不可发布。稳定行为与示例见 契约与 指南。R2 本地门禁已通过归属检查、最终冻结输入 消费站报告及产物双语文档。下文分别记录确切实测二进制和后续有界相等比较修复， 不表示公开发布或消费站写入。

冻结解析器语料位于 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r2-source-corpus-lqx25kwr/summary.json， 解析器输入 SHA-256 为 a601200ec4fe275d2bd4baf11d4db7d46a2cc6f1674900c1fd801769e55d12de。 每项范围均完整解析且无发现项。核心范围使用已记录配置下 Hugo 实际站点源码身份； 补充 Markdown 包含禁用/未发布文件，不虚构路由或关系。这些捕获早于已授权的 R2 文档修改。

初步公共命令报告位于 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r2-final-qu_zprps/summary.json， 使用二进制 c8d87e6d73d3101fefcb62c5d6845518573c02c400f474dc9f4603afafc774d5， CLI 输入清单为 d8a75be0e074365a4164b7aaaa27d82a1e844e04406a36c3dd6d39ff2b6e873f。 这些报告早于最终解析器/文档冻结，不是最终验收证据。最初 Starter 命令错误选择了 外层证据目录并返回 2，属于验证环境选择错误。改选其实际 site 子目录后返回 0，证据位于 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r2-starter-27vmi0w5。

软件仓库目录的结果是已完成的发现项结果，不是站点通过或实现失败。 没有降级政策，也没有修改消费站源码。信息性审阅状态仍保持可见。 最终冻结输入报告位于 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r2-candidate-6xzcs7fk/summary.json， 实测二进制 SHA-256 为 ff88b407a6cddb9007f94275c65a80ed4c9c4fd13f5e821f9b7a4a8973abaa56， CLI 输入清单为 bd8c71b55250a89dc15c7534924bb82a5447d6f2628eba23c8cb3d864309ee9f。 独立比对确认四份源码字节/模式/Git 清单操作前后均精确相等，替代初步公共命令试验：

最终报告均无未完成诊断。软件仓库目录保留 10,462 项实际合并打印 HTML_ID_DUPLICATE 和 788 项信息性审阅状态；其他站点保留信息性的未知审阅状态。 这接受实测检查行为和源码保护，并未将软件仓库目录称为通过的发布。

保留的生产文档位于 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-site-2201601475/public， 产物 Markdown 和链接通过。全站翻译检查返回 1，仅因既有草稿 release 1.2.0 双语页面未进入生产。另一个明确不可发布的草稿/未来/过期分析位于 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-site-3698773232/public， 三项 node 检查均通过：137 配对/1,092 标题、216 内容页面/41,586 文本节点， 347 页面/48,682 内链/4,171 片段。证据日志为 /tmp/oink-r2-docs-production-{translations,markdown,links}.log 和 /tmp/oink-r2-docs-analysis-{translations,markdown,links}.log。 分析输出或创作草稿均未替代生产，也未发布。

最终审阅发现可选 equal_fields 仍按表示形式比较 JSON 7.0 和 YAML/TOML 数值 7。有界补充现将已解码数值递归规范为精确有理数标签，保留字符串与数值、 映射键及数组顺序的区别。测试覆盖小数/指数、负零、超出 float64 精度的整数、 嵌套差异、源码字节保护，以及不可表示值导致必需未完成。 真实 Hugo 翻译测试在 /tmp/oink-r2-numeric-translations-gate.log 中通过， 全部公共维护真实 Hugo 用例在 /tmp/oink-r2-numeric-public-gate.log 中通过， 归属 vet 和空白检查通过。补充源码 SHA-256 为：

冻结真实站点报告及上下文 Linux 验收早于该补充。对应站点没有配置数值相等约束， 记录的输出不受影响，因此没有为这项有界修复重跑。后续完整运行与归档验收必须 刷新后续源码。本次证据修订属于验收运行后已授权文档写入，前后源码保护范围结束 于修订之前。

A18 仍未完成。macOS arm64 已实测；本机尝试 Darwin amd64 运行时， arch -x86_64 返回 posix_spawn: Bad CPU type in executable （/tmp/oink-r2-darwin-amd64-gate.log）。这是主机运行支持不可用，不是代码失败， 也不是 Darwin amd64 验收通过，未安装系统组件。原生 Linux arm64 和 Docker Desktop Rosetta 模拟的 Linux amd64 均实际执行，同一运行/Schema/许可证输入 SHA-256 为 0f786df68ef3c4844c983a51595f79242d1cb1d2bf6c5b5eb7f2c6415fb8d861。 证据保留在 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-a18-linux-ajbbnvki 的 arm64-results、amd64-results、commands.json、candidate-inputs.json、 preparation.json 和 qualify.sh。每个目标均通过 270 个测试/子测试，无失败， 仅跳过两项可选外部语料/来源验证：完整真实 Hugo go test ./...、vet、构建 CLI 版本/双语 init/doctor/完整 check/翻译 status，以及缺失 Hugo 退出 2 smoke。 JSON stdout 和源码字节/模式清单均核对。Go 1.27.1 运行在 Linux arm64， Hugo Extended 0.166.0 各架构资源已核对 SHA。这证明对应源码运行路径， 不证明最终归档或托管 CI。Darwin amd64 仍未完成，交叉编译不能关闭它。 后续阶段及未来命令/适配器/浏览器验收仍未完成。

R3 本地验证

R3 新增受管理 build --check、oink.artifact/v1 封存/导出/本地验证、 显式联网 HTTP 验证、发布诊断和受保护的本地 CI 生成。默认 build/dev 保持普通 Hugo。 已执行运行和中英文契约/指南门禁通过，R3 已本地接受；未运行托管 CI 或部署。

最新单二进制语料位于 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r3-ci-final-ahc4csjk/summary.json。 从精确捕获的 CLI 输入副本编译，二进制 SHA-256 为 425845c1d2db7b1cd3c3cdb5f28475cb06ba6f656054909759e2359a39925dd2， 67 个运行/Schema/许可证输入 SHA-256 为 6789a3a0235ff8d81453b9bfde37824979eac7d56af3710da390e4d2ef8479dc， 108 个更广 CLI 输入 SHA-256 为 4ca473a4cb586d232baeb4cee029b281469c5bb03c831cc199b95451e6832c60。 全部运行后运行输入仍精确相等。实时工具为 Darwin arm64 上 Go 1.27.1 和 Hugo Extended 0.166.0；manifest 的规范 Hugo 版本排除发行方构建文本与私有路径。

每次离线 build --check 使用消费站外的新导出/manifest 路径、可选标记和保留隔离 目录。已有本地消费站未使用 --release，保留其配置的 workspace。每份原始报告 均恰好一次严格 Hugo 渲染、零未完成诊断、零必需未完成覆盖。

两份清单均精确比较操作前后字节、模式与文件类型，主清单还比较逻辑 Git 状态。 Git 站点包括 tracked 和未被忽略的 untracked 源码；无 Git Starter 包括既有生成 文件与锁。补充复制源码清单还包括快照读取的被忽略 workspace/编辑器元数据， 排除已有生成输出/缓存树。文件数不是证明，四份对比均精确相等。

软件仓库目录保留 10,462 项既有合并打印 HTML_ID_DUPLICATE，未创建导出或 manifest。 这是完整政策发现，不是通过的发布，也不是实现失败。生产审阅状态为 28/143/120/786； 分析包括未发布页，解释此前 R2 的 144/788。既有定制工作流信息仍可见， Starter 示例地址在此次非发布运行为警告。

三份新导出在全部原始文件 SHA-256、大小与模式上匹配保留的独立普通 Hugo 产物。 唯一新增文件为 .well-known/oink-build.json。原始源码清单与完整 manifest 输入哈希 均匹配此前捕获，复用普通产物未替换输入。辅助源码 SHA-256 为 13e4957a3d7847eb28c8b1eeba3588a4f4a9982c2bfca2ebc729ab2827159607， 二进制 SHA-256 为 b2699fe7a7aa3a34c41f9e4aba4b22d39cf8d0c156a369f3dfc4ca8c8c0fbce5。 原始辅助与普通产物证据位于 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r3-candidate-wb643dhh； 编译辅助程序后删除临时构建源码。

此前 R3 捕获保留为历史：首次捕获早于运行冻结，首份冻结捕获 oink-r3-final-pisrr21h 早于定制 CI 诊断。最初选择 /Users/vonng/pgsty/PIG 返回 2，因为不同仓库不是目标站；改用 pig.pgsty.com 后通过。 保留这些环境选择试验，不改标为候选失败；最新语料替代此前受管理构建结果。 CI 模板/bootstrap 根据已记录服务商第一方契约独立编写，未纳入服务商实现源码。

限定 R3 文档门禁通过，证据为 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r3-docs-render-pljj5aqd/summary.json。 十份成对契约/指南/路线图/索引/概览修改只有匹配原始字节/模式后才安装，哈希位于 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r3-doc-drafts-s0b3g48l/applied-files.json。 源码风格通过 88 个中文文档，翻译通过 137 配对/1,099 标题，Schema 保持相等且限定 空白检查通过。真实生产 Markdown 通过 214 页面/41,871 文本节点，链接通过 345 页面/48,344 内链/4,171 片段。生产翻译仅因未修改的草稿 release 1.2.0 未进入生产返回 1。另一个明确不可发布的草稿/未来/过期分析通过 Hugo 及三项 归属检查：137 配对/1,099 标题、216 页面/42,177 文本节点、347 页面/48,720 内链/ 4,199 片段。产物检查期间 421 个规范源码和 488 个复制源码文件均保持精确字节/模式。 分析没有发布或替代生产，本次验收修订发生于该冻结保护边界之后。

该门禁不宣称托管工作流执行、上传、公开发布、最低版本组合、浏览器行为或本轮 Linux/Darwin amd64 验收。A18 仍未完成，历史 Linux R2 结果保留原始源码哈希。 已授权双语证据/契约/指南写入发生于保护清单之后，不属于其无写入范围。

R4 创作与升级验收

受支持 R4 实现与只读语料范围在冻结归属/全量门禁后已本地接受。本记录覆盖配置、 普通创作/编辑器/片段和有界升级视图。受保护规范文档推广与新产物限定验证也已通过， 详见下文；R5–R8 和最终 A18 验证保持未完成。

归属证据保留于 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r4-starter-owning-0pv41lw5/summary.json。 日志为 /tmp/oink-r4-starter-{unit,hugo,vet,snapshot,race}-gate.log、 /tmp/oink-r4-public-init-gate.log 与 /tmp/oink-r4-public-init-vet-gate.log。 生成源码数量为 project 94、docs 58、blog 40、book 34。未编辑 Starter checkout， 未公开发布、消费站采用或部署。

最终冻结门禁均为 0：make test/vet 见 /tmp/oink-r4-frozen-go-gate.log， make test-hugo 见 /tmp/oink-r4-frozen-hugo-gate.log，真实 Hugo 核心 race 见 /tmp/oink-r4-frozen-core-race-gate.log。最终公共流程覆盖 Starter docs → 主页面/ 译文草稿 → 编辑器 → 检查 → 普通 Hugo；候选验证后的外部 Schema 修改仍在写源码前 拒绝。17 份归属与三份最终门禁日志及哈希原样保留在最终语料 owning-gates.json。

准确四站证据为 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r4-corpus-lw2cjyq6/summary.json， 另有有界 summary.compact.json、原始 JSON/日志和逐命令清单。二进制 SHA 为 c169b3d4d046c811dca80867068b86fb66ada5c8ce6910dd5cda7353c406f377；82 份运行时输入 SHA 为 fdff7f50d49b44f03fa1db79eec6b6c9b9bd5e52f8967a88aed84b3207a7b3c6， 与最后根清单完全相等，无运行时修改。139 份完整 CLI 输入 SHA 为 562e838d9eccb628eac86ae59b9b9587c1e23ad52991ec50eafb1e604e3924da。 驱动 SHA 为 d3ac41dc2e18295bfb26134d1a696935c8174913e2801a5766dbf7a1139d89f8。 实际工具为 macOS arm64 上的 Go 1.27.1 与 Hugo 0.166.0 Extended。

每次受管理构建恰好使用一次严格生产 Hugo 渲染，没有必需未完成或未完成的必需覆盖。 Git 可见主源码字节/完整模式/逻辑 Git 状态、补充复制输入以及源码目录模式在每条命令 和完整站点流程前后均精确相等。Repo 既有 merged_print 中 10,462 处重复 HTML ID 保持可见；其已完成发现既不是通过产物，也不是实现失败。未调整政策或消费站输入。

消费站升级预览选择已有公开 v1.1.0 pin，不应用写入；跨版本路由/alias/输出回归采用 明确合成夹具 pin，不虚构已发布主题版本。New/editor 计划为已验证预览，未在消费站 保存或应用计划。多主机及未知相对 alias 身份保持未完成。非确定性产物可能需要重新 预览 v2 计划；浏览器/普遍兼容、配置迁移及当前跨平台/归档验证不在此限定结果内。 此前 Linux R2 输入哈希仍属历史证据；Darwin amd64 与最终 A18 刷新仍未验证。 获授权的中英文规范写入只在这份冻结无写入证据边界之后发生。

父任务应用十份受保护文件后，新的规范文档验收通过。证据为 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r4-docs-render-v01eima0/summary.json； 推广清单为 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r4-doc-drafts-3i8bw994/applied-files.json。 冻结 c169b3… CLI 执行一次严格生产构建，定点链接检查返回 0。

生产产物保持独立，未被分析树替换；分析不可发布。临时辅助程序复制冻结核心而不 修改它：辅助源码 SHA 7faea7e726a6c6fb2e0747be1a4428f4c5fb5734fa52b6f981157a5fe37d9989， 辅助二进制 SHA 532638e76f96f8b173c122e512b3bf5fc2c4d4a7130f59c99c2c69e135e87073， 与原始日志一并保留。获授权的双语研究补录发生于精确无写入捕获边界之后，另行接受 定点源码检查。R4 本地限定文档门禁已接受；该结果不宣称公开发布、部署、R5–R8 完成或最终 A18 验证。

R5 实现与文档验收

R5 受支持范围在聚焦公开命令/核心、修正冻结全阶段、精确二进制只读消费者及 受保护规范源码/渲染文档门禁后已本地接受。有界结果保持明确，见下文。R6–R8、 workspace A15 与最终 A18 验收保持未完成。首次晋升与单独授权的渲染后状态/证据 修订保留不同的保护边界。

实际公开 Git/Hugo 流程在 /tmp/oink-r5-public-final-flow.log 以 53.963 秒通过。 已提交的合成站点拥有本地主题、双语页面及二进制附件；普通 0640、0600 保持为 完整当前事实，历史 Git 比较仅使用可执行位。删除乙后纳入未改入站甲、剩余翻译、 删除的附件与实际 RSS 输出。实际 alias 入站归属不确定性、全局配置/模板/数据及 未知输入变更扩大为全范围。

完成的 inspect/impact/context 返回 0，单独展示当前检查发现 1；check-since 保留当前质量 1 与完整验证范围。缺失、未提交或外部历史返回 2，保留全部已知 当前页面、附件、引用、输出，不虚构旧身份或变更。已测试无效选择器/限额、缺失工具 及失败渲染器日志。有界上下文提供理由、版本、源码及摘要哈希、可见遗漏/截断，不 执行文档字面指令。

保存移动预览/应用及随后普通 Hugo 已通过，保留二进制字节、原始完整模式、无关 文件与 Git index/revision。实际不透明 HTML/shortcode 引用保持人工动作；inline、 fence 与不透明片段保持不变。它们的最终断链候选返回 1，无保存计划或源文件 写入。源码、配置、附件、模式或新目标漂移返回 2，保留后续编辑。实际候选渲染器 之后的确定性变更同样在写前拒绝，保留编辑者字节/模式。聚焦实际移动 race 在 /tmp/oink-r5-public-move-race.log 以 8.286 秒通过；app vet 在 /tmp/oink-r5-public-vet.log 通过。

缓存模块补充之前，冻结父级 make test/vet 与 make test-hugo 分别在 /tmp/oink-r5-frozen-go-gate.log、/tmp/oink-r5-frozen-hugo-gate.log 通过 （实际 app 夹具 185.709 秒）。实际移动/源码 race 与 vet 在 /tmp/oink-r5-move-hugo-gate.log、/tmp/oink-r5-source-move-race-gate.log 及其 vet 日志通过；完整清单/模式/选择器计划保护在 /tmp/oink-r5-plan-owning-final.log 通过。

首轮冻结消费者试验发现实际缓存公开模块保护缺口：原始关系图含已解析模块输入， 新的外层候选哈希却未纳入它们，产生错误未完成 2，没有源码写入。内容计划现先 解析/捕获同一模块输入再比较，并保留旧元数据/创作计划范围。独立的校验和验证公开 OINK v1.1.0 回归在 /tmp/oink-r5-public-cached-module-move.log 以 27.42 秒 （package 28.220）通过预览、重新验证已保存应用与普通双语 Hugo，保留原始模式、 二进制字节、无关输入与 Git。修正当前二进制语料及补充 race 证据与旧未接受试验 分别记录。

修正当前候选的完整 make test/vet 在 /tmp/oink-r5-corrected-frozen-go-gate.log 通过；实际 make test-hugo 在 /tmp/oink-r5-corrected-frozen-hugo-gate.log 通过（app 278.787 秒）。缓存公开/ 已提交站点内部移动保护 race 在 /tmp/oink-r5-public-cached-seam-race.log 以 38.578 秒通过，app vet 也通过。

/tmp/oink-r5-corrected-runtime-freeze.json 记录 96 个运行输入，SHA-256 为 e5b6e0eda972116dbb94a8086668e6ef34bfaa56138cf31f1f71f4832c477842； 165 个较广 CLI 输入的 SHA-256 为 4965a0c92cb6126f67a6dabd548c7c25ee5d7c9c57e14cce5e55ebb7a22fca2d。 修正二进制 SHA-256 为 d7675aecca2f77b1eb37bb4f664c3314cf5207149e6abbb86523686c5c50bff0。 这些是本地工作输入/可执行文件身份，不是新 commit 或发布归档。修正四消费者捕获 在 831.825 秒内完成 16 个命令，证据位于 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r5-corpus-corrected-y2eue81h。 有界 final-receipt.json 的 SHA-256 为 b86e0e6c7dbfbaed62c845c03a55d963068f7d9a16771de5ff3b0974e76fce3b； 记录保留 12 份归属门禁日志、全部 20 条实际移动路由，以及完整原始 JSON/日志和 各移动分类文件的位置。

Starter 与仓库站 impact 保留已知当前事实，不虚构旧页面或变更。PIG 实际基线 完整（主题 v1.0.0 对当前 v1.1.0），但必需外部输入来源未完成，因此比较扩大为 全范围并返回 2。这些结果分别记录。文档站 impact 完成，包含 192 个捕获输入 变更、343 个受影响旧/当前页面并采用全范围。已完成事实查询独立展示当前质量发现； 仓库站 inspect/context 仍为 0。

文档站移动证明 18 处重写及四条路由。content/docs/customize/repository.md 第 216、313 行两个普通字面 /docs/admin/comments/ 目标保持人工动作，因为 普通/打印输出的重复源码/输出出现位置无法精确归属。六条候选缺失引用阻止验证。 PIG 移动两个 Markdown 文件及四个二进制附件，证明八条页面/处理后资源路由。 配对且字节相同的输出证明处理后 featured_hu_* 资源，但未证明四个原始绝对图片 引用 /article/pgext-day/{featured,topic,venue,schedule}.webp 的新 URL。 32 条候选缺失引用阻止验证，不猜测重写原始资源 URL。这些普通 Markdown 边界 与不透明 HTML/shortcode 边界分别记录。

仓库站移动证明十处重写及四条路由；候选只有同一批已有 10,462 个重复 ID 发现， 没有新缺失引用或必需未完成发现。Starter 无入链的双语移动已验证。四次移动均未 应用，未保存消费者计划或写入消费者源码。失败候选为 validated: false。 全部 JSON stdout 纯净；主源码、复制输入、完整模式、目录清单及逻辑 Git/index 状态保持不变，包含忽略的复制输入。Git 元数据清单不包含不可变对象存储。 运行与较广 CLI 清单仍匹配捕获身份。本记录不验证其他平台、浏览器运行或部署。

首次十文件受保护规范晋升使用上述修正冻结二进制/运行哈希，在 62.37 秒内 完成验证。独立渲染记录为 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r5-docs-render-ks2tw82c/summary.json， SHA-256 为 06ae844a4b3f1c01bb5faa8a21091d5461c28aab592d12c4310fb34bc176c5d4。

分析树没有替换生产输出，也不可发布。首次晋升的永久 applied-files.json 位于 /var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r5-doc-drafts-t3_klnck， 保留十个授权文件及其原始模式。这次单独授权的渲染后修订仅触及成对提案/索引/研究 六个文件，发生在已记录无写入边界之后；已验证契约与指南字节保持冻结。受保护原文、 准备 diff 与定点源码检查单独保留。不追溯宣称后续证据字节属于先前渲染捕获，也不 从修订推断完整语料或渲染重跑。

核心归属日志 /tmp/oink-r5-frozen-core-hugo.log、 /tmp/oink-r5-owning-race.log、/tmp/oink-r5-owning-vet.log 已通过。A13 影响 与 A14 移动保护所需受支持 CLI 范围通过；A15 有界上下文通过，workspace/direct 一致性仍属于 R6。不宣称消费者写入、提交、发布、网络部署、远程模型集成或增量提速。

R6 工作区与适配器验收证据

R6 受支持范围在冻结归属/运行时、精确二进制消费者一致性/保护及受保护规范 源码/渲染门禁后已本地接受。受支持登记/工具字段归属 契约与 指南。R1–R6 已本地接受；历史收据保持不变。 A07 适配器与 A15 工作区/直接/context 受支持范围通过下列门禁；R7/R8 与最终 A18 仍未完成。

登记独立版本为 oink.workspace/v1：严格单文档普通 YAML、1–64 个条目、最多 256 KiB、准确 ASCII 名称、字面相对/绝对目录、已证明的规范身份，以及重叠拒绝。 缺失站点保持逐站未完成，后续选定站点继续运行。选择保留登记顺序；不提供默认登记 站点、同级发现、Hugo 设置复制或自动多站应用。可选工具扩展 oink.policy/v1， 固定协议版本，提供配置/完整模式来源，以及类型化遗漏/覆盖。

工作区归属收据

这些是归属夹具结果，不是消费者采用，也不授权对真实消费者应用计划。已检查核心 workspace.go 的 SHA-256 为 cf2cbc9509e8c83eedf6d8833c9eb0ea6492de9a85c959798112fa3f105213f4； 归属测试为 9070a8e2c3e58680f6567f2394160ec682bf0457c068c2addf354921e7612d6b； 公共测试为 3e57a6417ae2e7604f7cb06933759bb06a2f40758ff7059848593cedbaa6570a。 这三份已检查文件均保留 0600 模式。下方冻结全部运行时清单覆盖这些归属源码 捕获；单独文件哈希不代表实际运行二进制身份。

修正协议与阶段门禁

永久聚焦工具收据位于 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r6-tools-6bf67ltv/r6-public-tools-acceptance.json， SHA-256 为 16b6e47fc0618c76d2f9e3680a4112b6e47b478af8aabd3f2fc84821f840cc8a。 它绑定工具准备记录、可执行文件/配置证据与 1,422 个已解析 Node 包文件。Markdownlint 报告原始 content/tools.md 第 7 行，bytes[80:92]（ppears here.）；Vale 报告同一行，bytes[71:78]（BADTERM）。七个网络用例每个均实际发出一个 HTTP 请求。这些记录不认证全部传递解释器、其他运行时目标或完整消费者语料。

精确二进制消费者收据位于 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r6-corpus-59_asiyr/final-receipt.json， 42,212 字节，SHA-256 为 0ad86afaf235bdcff0c474e76b08e0591591a7b22c7992b02e20fb17975d029e； 完成摘要绑定 467b66eb6d178829508115050d4243909313acf1b4d59317ecda37ab7383ca55。 它保留 14 份归属/完成门禁日志副本。六个原始操作合计 314.912887 秒，不计候选编译 和仅收据修正。workspace list 返回 0；四个直接完整检查返回 0/0/0/1； 汇总返回 1，全部四站完成。

直接和汇总子结果的身份、顺序、每项诊断与覆盖记录均一致。全部四消费者源码在每次 操作后及整体保留完整模式/类型、逻辑与可变 Git 元数据、被忽略复制输入和目录清单； 完整根 CLI 清单也仍等于冻结捕获。478,603,149 字节 repository 直接 JSON 与 635,470,795 字节汇总 JSON 通过流式完整验证，没有截断。可选工具协议归属独立 固定工具夹具；消费者登记只存在任务临时目录，不写消费者政策。

初始验收驱动将摘要结果的 command 字符串覆盖为调用 argv，六个 CLI 操作及其 逐操作保护全部完成后，产生错误的一致性异常。失败驱动与摘要仍保留为 pre-correction.r6_qualify.py 与 pre-correction.summary.json。收据完成只修正 调用元数据，验证原始结果 SHA-256 和头部命令不变，保留全部原始完整流诊断/覆盖 摘要，并重查整体消费者/根目录保护。无需 CLI 运行时修正或 Hugo/CLI 重跑。仅收据 完成耗时 2.002 秒，/tmp/oink-r6-corpus-receipt-completion.log 退出 0。

实际执行驱动 SHA-256 为 4d2a360c6f7f6f96c38698bd189bc4d4b2cb02a7509858920d752897fdd85988； 修正后驱动为 4870f5c0374fcc11ad1a6b2e3aefe36f493b6f9f4666c293993dc6a59df8a11b； 收据完成驱动为 cd50d3fe704370f73fa4e7d94ce8e4bc925d11ec8ef04d463aacec37c2053daf。 流式辅助程序绑定 144f778cdb7907372797b47b97f817f340e70423701a2a958dee589281a9a11c， 清单辅助程序绑定 d3ac41dc2e18295bfb26134d1a696935c8174913e2801a5766dbf7a1139d89f8。 此收据验证本地 darwin/arm64，使用 Go 1.27.1、Hugo Extended 0.166.0、Node 26.9.0 与 Apple Git 2.54.0。它不刷新最终 A18，不验证 Darwin amd64 或其他平台， 不应用消费者计划，不公开发布或部署。语料捕获时，规范晋升与实际渲染中英文 归属门禁是独立待完成工作；后续收据在下方关闭该边界。首次晋升字节不能追溯 宣称本次渲染后修订。

初次实际工具试验属于预备证据，不是验证通过证据。它暴露了 Darwin /var 与 /private/var 暂存身份、实际回环代理路由，以及 Vale 夹具中无效的行内块属性/行号 断言。暂存现在使用规范路径；Vale 夹具改为真实独立行块属性，源码遮蔽边界不变。 已验证子环境传入字面的 NO_PROXY/no_proxy 主机列表数据，不传代理 URL/凭据 和 Node 预加载设置。空代理环境与 NO_PROXY=* 都未建立已测试 Darwin 回环路径； 不宣称通用操作系统代理绕过。

受支持源码诊断需要已证明原始范围；渲染 lychee 位置仍是输出文件/DOM pointer， 不推断 Markdown 行号。离线时不调用 lychee。鉴权/限流/服务器/传输不确定性不能 通过严重度、排除项或基线确认变成必需成功。外部片段、浏览器执行与远端内容身份 未经证明。声明、结果封套与必需未完成优先级独立于最终平台/归档验证；Darwin amd64 与最终 A18 仍未完成。

首次受保护十文件晋升及其新鲜渲染验证现已完成。收据位于 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r6-docs-render-dcwtcmyl/summary.json， 555,297 字节，SHA-256 为 ee153932900dc6f1ec62beef1a75927fc60b857efccfbcc558bf0e2c2b12cc04。 64.17 秒运行使用上方记录的精确已验证 aa8b347f…371f 二进制及不变的 103 输入 b85affd9…a03b 运行时清单。

首次晋升安装器收据 oink-r6-doc-drafts-ymjop499/applied-files.json 绑定 13c965592d64056d8365aed1927d2d422fadec8adc54ee7050b22e2ea0ad6270。 它在私有临时存储中保留捕获的实际原始 inode，保护后续旧打开句柄写入；恢复也保留 后续目标修改或删除。随后双语状态/证据修订具有独立完整字节/模式保护及源码归属 收据，只更新当前说明、命令状态和本台账，保留此前收据和配置示例。新字节不是 64.17 秒渲染运行的输入，不将该运行宣称为新字节重渲染。这些门禁后，R6/A07/A15 受支持范围已本地接受；R7/R8 与最终 A18 仍未完成。不宣称重复语料验收、公开 发布、消费者计划应用/采用或部署。

R7 只读 Studio 候选证据

R7 已实现契约与 指南描述的内嵌五视图浏览器及鉴权回环 API 候选。 R1–R6 历史章节及准确收据保持不变。冻结核心/浏览器及精确二进制四消费者验收 及受保护规范渲染门禁在声明范围内通过；R7/A16 受支持只读范围已本地接受。 R1–R7 已本地接受。R8 编辑与最终 A18 未完成。

聚焦原生与浏览器证据

首次浏览器收据位于 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-studio-browser-AfwaYi/summary.json， SHA-256 为 930fbd1ab86806069b963bff2e3e95aaa07e3634400cec65e2b8c7922e2a1707； 准确二进制绑定 92e5b962e40fbe828a0b006f3ae76a2bddf4ad7e8b1c5b6967e365b8f1827879。 后续声明/捕获主题元数据行不宣称由此前二进制测试。本地验证版本为 Node 26.9.0、 Playwright 1.62.1、@axe-core/playwright 4.13.0、Chromium 151.0.7922.34； 它们是明确预备的贡献者依赖，不是消费者运行时需求或自动安装。剪贴板证据覆盖 实际 UI 点击和私有剪贴板实现，不覆盖完整宿主剪贴板。

刷新保持 UI/后端浏览器收据位于 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-studio-browser-vn0ofb/summary.json， SHA-256 为 520603779f712539865c6e9ef7a9ad3ad21ec1906adfb067ec607cc69d071b7e， 准确二进制为 73bf90c69dce84849ee20ddfbfe825b9f2dd46f0cd37a228ce1b041a83afa33f。 全部 14 次 axe 与 14 张截图通过，包含声明/捕获主题元数据及全部五个 320 像素 视图。它保留上方针对前一运行时的有界合成夹具/源码/预览/剪贴板声明，不证明 后续局部预览修正；新浏览器、全阶段、消费者及渲染文档验收保持独立。

初次并行完整套件试跑 /tmp/oink-r7-frozen-go-gate.log 与 /tmp/oink-r7-frozen-hugo-gate.log 失败，不属于验收收据。失败原因是并行包负载下 既有 CI 测试十秒截止时间，以及图测试观察器刷新自身 Git 索引。单独 CI 目标组随后 分别用 12.149、2.291 秒通过；受控 Git 观察器图运行用 1.354 秒通过。仅 internal/projectgraph/hugo_test.go 改动：其只读观察器关闭 Git optional locks、 filesystem monitoring 与 untracked cache。该测试修正后，普通实际 Hugo 图运行 用 1.562 秒通过。运行时与内嵌 UI 字节均未改动。

修正冻结收据为 /tmp/oink-r7-corrected-runtime-freeze.json：113 运行时输入保持 15a7de85a1ae9e6a73d8ea6570aa4f97bdd0ad5677ad7ca996fdd081ad43f7b5； 193 更广输入现绑定 67c6d36cf91d175f208f79cdd4d337aab6d2ef71e43453b20394b677678725e8， 相对前一份 85ad60d24c93e899020fbdcd34f8252c578253ce5afaf8652e561a432ecc8067 冻结只改变测试观察器文件。修正后的串行 Go 测试与 vet 已通过，日志为 /tmp/oink-r7-corrected-go-gate.log。修正后的串行实际 Hugo/固定版本工具套件也 已通过，日志为 /tmp/oink-r7-corrected-hugo-gate.log，SHA-256 为 2aed822ff6fc8be04919aa74ca6ada721789232c14c1d77f1d44113bc0d235a7； 应用包耗时 220.782 秒。独立 Go 后源码保护审计收据为 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r7-postgo-audit-qygh7bcc/receipt.json， SHA-256 为 5ee45fe041536243bc1229054516835c61b27909a4f296ac226b1a138e4bc8dc。 它验证完整物理/逻辑输入保护，不证明 Hugo 或消费者结果。

持久修正归属门禁收据为 /tmp/oink-r7-corrected-owning-gates.json，SHA-256 为 c7f94a740e33a7349886b3f3689419719f857f39031375e80ca384a3dac36e67。 它将两份串行成功运行绑定到修正冻结，并保留失败试跑为未验收。预备文档渲染驱动 现要求完整消费者收据证明私有捕获源码重建与最终浏览器二进制字节相同。独立 源码审计 oink-r7-docdriver-audit-ig_r8ud1/receipt.json 绑定 SHA-256 858cc48bf602fbdb26fcbda03c78ca485338b1295d64257d32cfb14b24f1ade3， 以及预备驱动 f25d9ac4bf1a7ef43d5526b7b3cbadf84dd64ad8a57fd82d1c82e76fdb2b3435。 该审计没有执行或验收规范渲染。

首次消费者驱动试跑 oink-r7-corpus-h1lOFl 因 KeyError('preview_base_path') 停止：驱动直接索引实际预览基路径为空时合理省略的 字段。该私有重建与最终浏览器二进制 73bf90c69dce84849ee20ddfbfe825b9f2dd46f0cd37a228ce1b041a83afa33f 字节相同；四消费者源码清单与根清单全部保留。失败的驱动运行不构成四消费者 门禁验收。新 oink-r7-corpus-corrected-cByXTa 驱动仅将这两个访问改为 get(..., '')，SHA-256 为 4c409acacbb9b82e658e6705eddefd9a3541def5c63c340b65678a6c9a8354e4。 该新运行随后因仓库产物中一个清单文件超过 64 MiB 而失败：前一运行时拒绝全部 生产预览。原生检查保持结果 1，必需预览不可用使 Studio 结果为 2。 Starter、docs、PIG 在本次运行完成并返回 0；四消费者源码清单与根清单保持 不变。失败 cByXTa 试跑保留，不构成四消费者门禁验收。空基路径驱动修正均未 改动运行时或消费者源码。

父任务随后授权局部预览的窄运行时/测试修正：保持 64 MiB 限制，开放限制内受保护 生产文件，准确跳过的超大路径返回 413，必需 studio.preview 覆盖保持未完成。 原生检查结果不变；必需预览未完成仍使 Studio 返回 2。内嵌 UI 保持不变。 此前浏览器/归属/二进制/语料收据都只描述各自旧运行时边界，不证明此新运行时。 新归属/浏览器门禁在下方独立记录，不从旧收据推断；精确二进制四消费者验收 保持独立。 旧失败捕获证明有产物超过 64 MiB，但未暴露其捕获路径/大小；被忽略仓库产物不 构成该捕获身份的证据。新的有界覆盖 detail 将记录实际省略相对路径、大小与总数。 预备实际 Hugo 浏览器夹具增加 64 MiB 加一字节的 static/oversized.bin，用于 验证可用受保护 HTML 预览、准确跳过文件的 413、原生结果 1 及必需局部视图 结果 2。该夹具准备本身不是浏览器验收；随后已完成浏览器证明在下方记录。

新局部预览冻结收据为 /tmp/oink-r7-partial-preview-runtime-freeze.json，SHA-256 为 c426ce3e641ed7b39bb711a26006306cab22e761c5062f2164f10deb4bea8765。 113 运行时输入绑定 4900ae05abbdf4409b0be54f276fb4135269cf0a49e9071013ccf42544d35c84； 193 更广输入绑定 8b172cef2b228e2642f0139d6cc569136e86843f818e52e412fa4a2d56add25d。 运行时输入仅改动 internal/studio/preview.go；更广改动还包含其测试及 scripts/test-studio.mjs。三个 UI 文件字节与模式全部保持相同。聚焦核心最终 race 用 1.748 秒通过，vet 与限定空白检查也通过。收据 oink-r7-partial-preview-owning-a56dunn4/receipt.json 绑定 SHA-256 7b6ecb491f283d04fe54347e564dba426b1a84d152040a1d945af54bc67756ac。 初次稀疏夹具模式试跑排除：宿主 umask 0077 使请求 0640 的文件实际为 0600； 夹具显式 chmod 到 0640 修正该设置，未改变生产行为。聚焦证明覆盖正常 200、超大 GET/HEAD 的 413、身份变化 409、私有路径 404 及其他未知产物错误拒绝。 它不替代随后独立的更广浏览器/归属/语料/渲染门禁。

新局部预览冻结的完整串行 Go 测试随后用 61.481 秒通过，vet 用 0.571 秒通过。 完整日志为 /tmp/oink-r7-partial-preview-go-gate.log，SHA-256 be7d6eccf99a6f4c1b8f09d1fb782455c7cbd3bad4a2f37e2f0e9da916bcb313， 以及 /tmp/oink-r7-partial-preview-vet-gate.log，空文件 SHA-256 为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。 独立保持输入审计 oink-r7-partial-held-audit-o6p98i1l/receipt.json，SHA-256 e567efc5f580db9395afab8ad36c4db842c3db95db442eb1cb1c740dbd43ec31， 在父任务 Go/vet 运行期间验证全部 113/193 输入及物理/逻辑身份。它不构成套件后 或浏览器/语料/渲染完成声明。新完整实际 Hugo/固定版本工具调用随后用 285.649 秒 完成，退出 1。唯一失败是父任务使用不可用 Markdownlint 准备路径 /md/node_modules；其他实际案例全部通过。该日志保留为失败调用： /tmp/oink-r7-partial-preview-hugo-gate.log，SHA-256 为 1ab6b8cfd399d484e08a1d1f05d25475754caa731991dd1eec1cca03cf6ce970。 唯一归属案例改用准确预备的 /markdownlint/node_modules 可执行文件重跑，源码/ 运行时不变，通过：应用包 2.317 秒，墙钟 3.265 秒。收据为 /tmp/oink-r7-partial-preview-corrected-tools-gate.json，SHA-256 62b75e563e8074995ed9dd354434e653b2f5f2c6d20767226286d0c08d4c667c； 日志 SHA-256 为 e9bddac210654d219d9c5d6ebabaa3b91a0f5f4de4daf228b3ae21aeaac7673a。 可执行文件来自预备收据 268e601e81bc03a263296d57257b85635371bda642d0632532a7d9318c981461。 独立案例矩阵/保持源码审计验证失败完整调用加该修正案例形成累计已执行实际 归属案例覆盖 0。收据 oink-r7-partial-case-matrix-audit-16_bl9hr/receipt.json 绑定 SHA-256 0a9e4a1a1e1a08f597becb2f27e743c9f23df672c713c2757241704edb16b51e。 全部 113/193 物理/逻辑输入保持冻结。可选 TestArtifactCorpus 与 TestPublishedRuleSourceProvenance 案例明确跳过。不能将完整调用重新标为退出 0，也不能宣称跳过案例已经执行。

新 Go 后输入审计 oink-r7-partial-postgo-audit-g1hcqdtl/receipt.json，SHA-256 b369737ec48456f673c850ea702cb3cb7efffb8ecc129d87e00dc03af82b2e3b， 随后确认 Go/vet 后全部保持的 113/193 物理/逻辑输入。该范围不宣称完整 Hugo、 浏览器或消费者完成。

新局部预览浏览器基于准确二进制 f39d6754f7ad13599e4e849394e0f470b2c6f26edf96ce40f199d27b65a8030e 通过，版本 0.4.0-r7-local，16,000,578 字节、模式 0700。摘要为 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-studio-browser-cE9be3/summary.json， SHA-256 为 9099e6c407fd0f9de3c29ce80e03f034a4223d7d7a7c1f1378052e8b9084e0ae； 来源收据 SHA-256 为 85b9f537fb09eecbb09d133b53a297c78184c11200ab0938734c0d10f3449095。 私有 oink-r7-browser-partial-ZZIqzZ/source-binding.build.json，SHA-256 7a89ab8318c3a38455ab6ce12bcdbc53ae5ce0674fb5aaaa1df0fcf68a093399， 将捕获/构建前后全部 113 运行时及 193 更广源码输入和物理身份绑定到新冻结； 根输入保持不变。全部 14 次 axe 零违规、14 张截图通过，保留上方键盘/移动/深浅色/ 源码/剪贴板/安全检查。实际 Hugo 生成 67,108,865 字节 oversized.bin，经渲染 /sub/oversized.bin 链接实际到达并返回 413；普通实际 HTML 返回 200。 必需局部预览覆盖保持可见；228 条类型化原生诊断、原生覆盖/结果 1 在 CLI/API/UI 中一致，Studio 及随后刷新返回 2。源码保护仍仅排除明确任务夹具外部编辑。 这是有界合成浏览器证明，不是完整四消费者或规范渲染门禁。

另一份未执行的预备语料驱动假定正常可用预览总会附加 studio.preview 覆盖行。 实际正常 Starter/docs/PIG Overview 不输出该行；准备假设已修正，未改变原生覆盖。 修正后的新 oink-r7-corpus-partial-pZLwY0 驱动，SHA-256 47778df62505beeb7432985be927f1b001e03824e9dee3a6dbed9d9b2dbe049c， 已针对这三份保留实际 Overview 及当前局部浏览器捕获复核。正常可用仍需实际 预览 URL 和独立 HTML 200；局部捕获保留真实必需覆盖行、省略总数/身份和 413。 准备审计为 oink-r7-partial-driver-correction-audit-sa98cm6k/receipt.json，SHA-256 a519a5bc6ae83438146ff4710d53f5edb0e656a05d0532c02123e5771416f07e。 此前 f762 准备没有执行或验收。父任务随后释放修正驱动重新运行全部四站点； 其完整验收记录如下。

新四消费者验收用 234.6425 秒完成，驱动结果 0。本轮摘要为 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r7-corpus-partial-pZLwY0/summary.json， SHA-256 d7b5a4f1607b6f75ae6a596c19cbab28685fb67dac750096173060ed097c8bf5； 日志 /tmp/oink-r7-partial-corpus-gate.log 绑定 SHA-256 a7b724500569bd594d8e01502ec1956eb089cc9153b04b693992a9322013c811。 持久本轮语料 qualification.receipt.json 绑定 SHA-256 4e5df7c3fda9f0b763091af3e6cb85c68c736c319a1de68030b81d5cd5b384bc； 主源码清单分别包含 97/421/858/2,294 个文件。 私有捕获源码重建与新浏览器二进制 f39d6754f7ad13599e4e849394e0f470b2c6f26edf96ce40f199d27b65a8030e 字节相同。113 运行时/193 更广输入及根物理身份保持冻结；每次操作与整体边界均 保留四消费者字节、完整模式/类型、逻辑/可变 Git、被忽略捕获输入和目录。

四站嵌套原生 header、类型化诊断、覆盖及退出与直接 CLI 检查准确一致。Issues 完整分页；其他视图采用有界样本，四站均有捕获物理源码及翻译 diff。前三站实际 生产预览 HTML 返回 200；它们不输出 studio.preview 省略行，驱动没有虚构该行。 仓库正常 HTML 返回 200、60,100 字节。当前捕获准确暴露四个超大 print 路径； 每个实际 HEAD 返回 413，响应体零字节：

这些身份来自本轮有界捕获 detail 与实际请求，不来自此前被忽略产物线索。必需 studio.preview 保持未完成，仓库 Studio 2 因而保留原生 1。docs 与 repo 实际 仅分析 draft 路由在生产返回 404；Starter/PIG 缺少唯一捕获 draft 路由，该测试 明确不适用。工作区子集/全集/健康子集会话仅选登记站点，不捕获并关闭监听器； 未知或选定缺失站点在启动前返回 2。这是本地 Darwin/arm64 CLI/API 证据，使用 Hugo 0.166.0 Extended、Go 1.27.1、Git 2.54.0；浏览器范围保持为独立合成夹具。 没有源码写入、安装、公开发布、采用或部署。独立最终语料审计 oink-r7-final-corpus-audit-xr3_u5dt/receipt.json，SHA-256 b8a8eedf5c899fe5830bdde959783c46b3f191ab144c0d3798077555d55238fc， 不重渲染、不新增 HTTP 请求，验证原始类型化原生/API/退出一致、132 项操作保护 比较及四项整体保护。仅受保护规范晋升/渲染及显式 R7/A16 阶段决策仍待完成；R8 与最终 A18 未完成。

临时磁盘容量准备期间，父任务仅清理三个明确创建的私有 Go build cache，共 366,184,826 字节，收据为 /tmp/oink-r7-private-cache-retirement.json。 源码、二进制与验收证据均保留；未删除全局、用户或系统缓存。此准备操作不是 运行时修正或验收门禁。

剩余阶段门禁与晋升边界

下一份预备文档安装器在成功与恢复时都将捕获的实际旧 inode 保留在规范源码外， 不会在较早目标身份检查后取消其最后名称。此私有辅助程序加固及新恢复夹具属于 新的预备边界；已执行 R6 安装器/哈希/收据保持不可变，不追溯宣称包含该修正。 R6 成功晋升已保留原始 inode。本候选文档或本地浏览器夹具不推断消费者计划写入、 公开发布、采用或部署。

首次晋升渲染门禁完成，收据为 /private/var/folders/df/bfm8q07d7bv3kpjf1fjchq4m0000gn/T/oink-r7-docs-render-n8tw2tbw/summary.json，SHA-256 35e79f51d39803b3e4cdf134ed277957dd627acba42e0e0dc785e4745ec3c481，日志 SHA-256 de3a07eac661c15805070e0ed2e364a71ebbd38e15d8907aab3bdf716e95131d，耗时 63.33 秒。准确已验证二进制 f39d6754f7ad13599e4e849394e0f470b2c6f26edf96ce40f199d27b65a8030e 在一次严格 Hugo 构建下通过生产 CLI 链接。无 probe 普通生产 Hugo 通过渲染 Markdown（214 页/44,075 文本节点）及链接（345 页/48,482 内链/4,303 片段）。其翻译归属仅因既有未发布 release 1.2.0 draft 保留退出 1。独立 draft/future/expired 分析通过 Markdown（216 页/44,381 节点）、链接（347 页/48,858 内链/4,331 片段）及翻译（137 对/1,129 标题）；未替换生产产物。源码翻译/样式/空白检查通过，CLI/文档 schema 7468c2d04cde8a368ce0ba44a1f27125b5fca364b6d4672353519b9545b3bdda 保持相同。十二项操作、schema 及整体保护均保留 421 主文件、427 捕获输入、109 目录、36 可变 Git 文件和 113 运行时输入。

首次受保护晋升收据 oink-r7-root-promotion-p9g1u7pz/summary.json，SHA-256 323a5ce267e39aaf8f97dc4a12cccbdde83730155a199efb5f3815e29b334e4a，验证实际原始 inode 保留在规范源码外。写入后收据查找曾使用 0 而非 00；该仅元数据驱动失败保留，随后使用不变原始保护完成收据。已成功源码安装没有重复执行。已执行 R6/R7 辅助程序与首次晋升收据保持不可变。

R7/A16 受支持只读本地范围在上述冻结累计归属案例/浏览器/语料及规范门禁后已接受。原完整 Hugo 调用仍退出 1；唯一修正工具案例加独立矩阵形成累计已执行案例覆盖。仓库原生 1 与必需局部预览/Studio 2 保持可见。R1–R7 已本地接受；R8 编辑与最终 A18 未完成。此渲染后状态/证据修订具有独立字节/完整模式保护、不变标题/命令围栏、配对源码检查及保留 inode 安装器夹具。其新字节不宣称由此前 63.33 秒渲染测试；不推断额外渲染、消费者写入、公开发布、采用或部署。

R8 已接受受审阅编辑证据

R8/A17 受支持编辑范围在下文修正冻结归属/浏览器/语料及受保护规范渲染门禁 后已本地接受。CLI edit text、field、 snippet、attachment 预览与显式 studio --edit 相同的绑定 oink.edit/v1 意图。保存计划应用或 Editor 显式确认 Apply 拥有选定源码写入；默认 Studio 会话 保持只读。本节保留捕获时的候选事实和试验，随后记录已完成当前验证；不把先前 R1–R7 证据延伸到变动代码。

候选范围与保护

已知站点所有 UTF-8 Markdown 上限 1 MiB。完整文本及受支持普通顶层 YAML 标量 表单保留声明的 BOM/换行及源码区间保护边界，不支持表单形态保留文本。准确 value_json 数值避免浏览器 Number 舍入。标量表单把数值字面量限制为 4,096 字节、 十进制指数绝对值 10,000，更大/非有限构造保留手工文本。字段 JSON 最多 1 MiB； 转义孤立 surrogate 拒绝，有效 Unicode 对受支持。目录组件使用原始 UTF-8 正文字节偏移； 附件要求实际 leaf-bundle 身份、最多 4 MiB、独占干净新 basename。源码哈希、 完整模式、全部站点/外部输入、重新生成意图及新实际 Hugo 验证绑定同一共享保护 应用路径。

Editor 展示完整 UTF-8 审阅、选中文件基准/结果身份及原生候选结果；审阅上限 2 MiB，确认前对准确可见字节验证哈希。实际选定候选 HTML 是 draft/future/expired 分析，明确不可发布，与原生产预览独立。必需候选视图未完成可以把提议/会话升为 2，而不改写原生发现。页面文件编辑的选定候选源码哈希/完整模式须匹配已审阅 After 状态；附件/no-op 提议的选定页面保持已审阅 Base 状态。 过期/重放计划、附件冲突及不可信预览请求会拒绝；已应用但刷新失败保持明确已应用。

聚焦准备收据

Helper 证据只验证聚焦文件复制/取消，不是整个编辑应用或全部平台支持。浏览器 试验只描述实际停止范围，不构成最终 A17、消费者采用、部署或当前冻结浏览器 二进制成功证明。

前述准备行记录于首次完整 R8 冻结之前，保持开发历史边界。后续首次完整冻结 门禁通过，二进制为 84b804d3246a5be581e44884ed910fa3f45d8be29734b8babdeeb763a11fa882 （0.5.0-r8-local），运行时 123/58517b8e98b80df6642be4ee6275a0074ec187768b20e009f41da2607b635d46， 更广源码 212/d81335c78413acc60e27adee0ac794862285e41cb2a3a7687ec820c1065ba003。 完整门禁摘要为 b49f4a3272af3e3dcc92e7e9b38d4289bb49cb19aa3e9354ea148d2d8cb2cea8： Go 测试 0/56.523 秒、vet 0/0.904 秒、完整实际 Hugo 及三个固定工具 0/320.044 秒、核心 race 0/16.610 秒、公共 R8/helper race 0/48.319 秒。 源码保护通过，这些收据只验证此前对应字节。

首次冻结浏览器收据 eb6977235ef9ae6cec28651b5654eb101685af67abe0cbed0acb0f8375458d9c 绑定相同二进制及源码冻结。Editor 12 项 axe 零违规、12 张截图；保留只读 Studio 为 14/零/14。实际表单保留 1e400 字面量、计划 after 哈希及 diff，随后 丢弃；指数 ±10,001 与 4,097 字节数值在本地拒绝，不发送 API 请求。四次确认的 字段/组件/二进制/draft 应用只发生于一次性夹具。默认只读拒绝、过期输入保留、 no-op 源码字节、预览隔离及原生结果独立性通过。这是首次冻结的开发浏览器 证据，不是四消费者或当前修正运行时的阶段接受。

首次准确二进制消费者试验随后在 Starter 停止，耗时 37.533 秒。不可变失败试验 收据为 853a8397ba4c527c03aa3cc9ac7cacc41c0ab0379549d145b874f1d1ecc3901c。 两项失败分别记录：驱动事件哈希依赖 JSON 对象键顺序，但递归比较证明 API/CLI 数组相等，均为 28 条诊断、29 条覆盖、原生退出 0/0。另一个是真实运行时 问题：重复解析缓存捕获产生 .gitattributes 模块输入重复；必需候选图捕获不完整， 修改结果为 2，原生检查仍为 0，没有实际选定 DFE HTML 或可应用 lease。 公共发布缓存夹具重现该缺陷，保留失败日志为 50ab704e715665096e0f36391bb1364841c3a2b2ac88dd262915ce53fb66afa6。 全部 48 份已记录逐操作源码证明及四份消费者整体保护保留字节、完整模式、类型、 Git、忽略但复制的输入与目录，根输入准确不变。没有 Apply 或保存计划；停止的 试验不构成完成四消费者验证。

定点运行时修正先收集完整解析模块行，再提交新增记录。相同重复或重新排序的 捕获保留原清单。既有范围内哈希/完整模式变化、路径增删、整个范围缺失、身份 冲突或捕获错误都拒绝，不刷新此前证据或追加部分结果；非模块行保持准确。 site 归属收据 e7b284b9dece1c5f2b696cd76166d2286fcbec69e6c48912ab9a78204bdb980b 记录聚焦 0/0.746 秒、site 0/2.123 秒、聚焦 race 0/1.958 秒、vet 0/0.167 秒。这比较重新观察的完整行，不锁定模块文件阻止并发写入。

修正公共发布缓存收据 6358dc81f06e34b789cb47a0f4442d6d036d2e33423a06f5dbe85b3064766da6 使用任务本地复制、校验过的 github.com/pgsty/[email protected] 归档，没有下载或 replacement。原始/候选图各有 1,256 条唯一输入，含 1,198 条模块输入。完整 API/CLI 类型化诊断、覆盖、退出及计划身份一致，实际选定 DFE HTML 返回 200， 源码字节/完整模式/Git 不变，没有 Apply 或保存计划。归属 race 30.255 秒通过， vet 通过；修正 race 日志为 c7d21a30b8af141d9d9604a80ddf9cf3f608320b97a441a06a742376e2119551。

当前完整修正冻结为 fb276500a3d2643bd0aa220f8bebb380fce2c98493d62b0502b6497b2f02949f， 运行时 123/cdf629eeb4bbef6d4d88ee27fe3fb0a73b07b6bf6438336e033a18fb7feb1c17， 更广源码 212/f6e305e792733a550814eb841615d12fa14a9a6bb2a97c4ada85f7275183e579。 相对首次冻结只变动 source_inputs.go、其归属测试及公共发布缓存测试；受控 UI/helper 字节及全部完整模式不变。重建候选为 bd25f9e0b35ec10e227aabf9582ae40b0b367390f64b93668de6ae85222c3d71 （0.5.0-r8-local）。已观察的修正源码绑定浏览器收据 33a698985a55c14c3e64e981da1f8e74c686497083dc0edb241406f185e3eeb8 再次记录 Editor 12/零/12、只读 14/零/14，完整 123/212 前后源码保护通过。 本次证据修订时，修正完整归属门禁、新四消费者语料及受保护规范渲染仍待完成。 R8/A17 尚未阶段接受，最终 A18 保持未完成。

下一次证据观察时，修正完整门禁已完成，绑定前述受控 bd25f9e0…22c3d71 二进制及 fb276500…02949f 冻结。摘要 208f156c0954e803eccbada678a4689683dc1576c543c379e5cc04b3497ef772 记录 Go 测试 0/57.826 秒、vet 0/0.521 秒、完整实际 Hugo 及三个固定工具 0/378.847 秒、核心/site/Studio race 0/17.937 秒、公共 R8/附件/输出 helper race 0/85.159 秒。每项门禁源码前后保护通过。实际 Hugo 日志有 434 项顶层 通过、零失败；两个可选外部夹具 TestArtifactCorpus 与 TestPublishedRuleSourceProvenance 明确保留跳过状态，不宣称已执行对应语料或 来源验证。

修正完整实际 Hugo 日志为 4eb1a2afdce2adbe570b10922fd53b6d8954f7c95747370c3c661e94d2f71a05； Go 日志 ea59463e9649ffe2f8aff9da66c91cf6895c86fde96a524db23c89cd4eb35925， 核心 race cdd3d761b5ca7b5e986b25aee3129d65663e3e5ebb83eecb6fbb080387298a58， 公共 race bb610bdcd7a299cb9b66f4c69e30e246c20546efae47653c01d350b1026ea2de。 前述修正浏览器专项证据继续绑定相同当前源码及二进制。独立授权的新四消费者 试验正在执行；不由这些归属门禁推断完成语料、规范渲染、R8/A17 接受或最终 A18 验证。

前述 434 项通过与两个可选跳过是顶层计数。同次完整调用还跳过嵌套 Unix socket 拒绝夹具，原因是 Darwin 临时路径超过 socket 限制。首次缩短私有路径 试验仍跳过：收据 93106854ca890b497d3c74522b895f597ac60cec55ced42cad7b187d334da200 保留进程退出 0，但明确记录未实际执行 socket、验证失败，不改称夹具通过。

后续不解析别名的短私有 TMPDIR 在 race 下实际执行相同冻结 socket 夹具， 没有跳过，0/2.954 秒。收据 531a503b3b91e1b423c2be61b92ed806d3a813738c38d57e5ec122577b4337f9 与日志 236c84f1842ffce76174c834f3888718a109cec6377ada6f3242b02f551f00b3 绑定 fb276500…02949f，全部 123/212 逻辑/物理/Git 输入前后不变。这补充实际 socket 拒绝用例，没有改动源码或原始完整调用跳过历史。语料、规范渲染、R8/A17 阶段接受及最终 A18 仍待完成。

前述语料待完成陈述记录各自观察时点。随后，修正四消费者试验于 845.705 秒 完成。摘要 af4fc53326163c4a03aa2982c1f01363fbbdd5a447c9baed3639bd8599d46370 与验证收据 4d6fd02543c1920497e1a1bb0a68fcf89b0546130fd9cc12c1df391b7e673e75 绑定逐字节相同私有重建 bd25f9e0…22c3d71、完整受控 123/cdf629ee…feb1c17 运行时及 212/f6e305e7…5183e579 输入。原失败语料、 发布缓存回归与首次冻结浏览器/门禁字节保持独立历史证据；首次失败试验全部 2,383 项准确保留字节/完整模式/类型。

这些是独立、明确不可发布 draft/future/expired 候选视图中的实际选定 Hugo HTML 路由，预期候选 marker 均存在。API 与 CLI 的完整类型化诊断/覆盖、原生退出、 计划 ID、Base/After 哈希及完整模式、unified diff 和选定页面提议源码一致。 完整准确 API 审阅及其哈希独立验证。 没有消费者 Apply 或保存计划，没有遗留监听器。仓库保留 10,462 条已有重复 ID 发现和 788 条信息记录，四个实际 PRINT 输出仍为必需局部预览未完成： _print/pkg/index.html 73,976,221 字节、 _print/pkg/pgsql/index.html 69,903,999 字节、 zh/_print/pkg/index.html 73,086,240 字节、 zh/_print/pkg/pgsql/index.html 69,052,754 字节。每次有界 HEAD 请求均返回 413、正文为零，选定限内 HTML 保持 200。原生 1 未改动，提议/会话 2 及拒绝 Apply 保持可见。其余三站完整预览不编造显式完整覆盖行，而以实际受保护 HTML 200 作为证据。

准确 53 次受保护操作每次检查全部四站：212 次逐操作源码证明加四次整体证明， 源码字节/完整模式/类型、复制的忽略输入、目录及逻辑/可变 Git 均未改变。每次源码 证明比较四类清单，因此含整体比较共 864 对原始清单。全部 53 次根目录保护及 最终完整 123/212 逻辑/物理输入也相同。所有 issues 与 pages 分页遍历，其他五个 视图端点仅取前 50 项，每站一个已知源码及一个有界 diff。完整原生/CLI 记录 一致性使用已声明有界完整记录 codec；对象顺序规范化，数组顺序、类型、null 和 字段存在性仍有意义。不宣称已人工查看每条关系或编辑每个源码文件。

独立审计收据 6b72ca06d8392a5271fc40757f176f26e1144c21eec93dbd035e0a1bd645657b 验证 69 项产物哈希、完整有界 API/spool/关闭类型化记录及大型原生/CLI 原始文件 摘要绑定，没有单独重复数 GB 原生语义扫描。追加收据 335f137663d4ec0b2a0d3e49c8d70b9918f86078ab6264855171a2644d8aa6c6 还把当前根目录完整逻辑 Git 清单与冻结重新验证，原审计保持不可变。修正归属、 socket、浏览器及四消费者受支持范围已验证。规范 TEN 晋升/渲染、R8/A17 阶段 决策及最终 A18 仍待完成。

前述 R8 候选/试验陈述保留各自捕获时范围。随后，经审阅首次 TEN 晋升通过 受保护保留 inode 安装器，根收据为 7cd9b4604d2340b9e46965a26281c921b967060909d518b8b4b31e5f42d0120c。 实际原源码 inode 保留在文档站外；未选中源码/复制输入、目录和 Git，以及完整 CLI 123/212 逻辑/物理输入保持不变。

独立授权规范渲染随后仅执行一次，于 67.21 秒完成，摘要为 bb0d0710294f810fb14284f7b5b0329befbd290b66c21397b9a45e8382287fb6， 验证收据为 32d3ffeca43bc9ad4615edcca0d3cc47cc932bbc93c6576724c800e0a62405b1。 它使用准确已验证 bd25f9e0…22c3d71 二进制及修正 123/212 冻结。实际 CLI 生产 链接通过 0，只有一次严格 Hugo 构建。独立普通无探针生产 Hugo/Markdown/链接 通过：214 个 Markdown 页面/44,691 个节点，以及 345 个链接页面/48,532 条内部 引用/4,351 个片段。生产翻译归属仅因已有 release/1.2.0 draft 不在生产而保持 1。独立明确不可发布 draft/future/expired Hugo 分析的 Markdown（216 页面/ 44,997 节点）、链接（347 页面/48,908 引用/4,379 片段）及全部翻译均通过 0。 分析没有替换生产输出。

源码翻译通过 137/137 对、1,143 个标题；中文样式通过 137 文件/181 个加粗区间/ 零强调，空白通过，Schema SHA-256 7468c2d04cde8a368ce0ba44a1f27125b5fca364b6d4672353519b9545b3bdda 准确相同。全部 12 个命令、Schema 及整体保护保持 421 个主源码文件、427 个复制 输入、109 个目录和 36 个可变 Git 文件，以及全部 123 运行时/212 更广 CLI 逻辑/物理输入不变。验证收据绑定 60 对规范清单、15 对 CLI 保护及六对私有复制 源码，不宣称消费者写入或部署。

R8/A17 受支持本地编辑范围在修正归属、socket、源码绑定浏览器、精确二进制 四消费者保护及这些受保护规范门禁后已接受。R1–R8 已本地接受；仓库原生发现及 必需局部预览 2/拒绝 Apply 保持可见。最终 A18 当前 Linux/运行时/归档验证仍 未完成。独立平台权限依据审计 762571dab9a07651ac8e4c71764bfef292f8d5eba729a089e72d9d755b7e2d7c 确认初始契约验证实际执行架构：macOS arm64、原生 Linux arm64 与模拟 Linux amd64。Darwin amd64 保持实验归档，实际执行失败/运行时未验证；历史保持不变， 交叉编译成功不能成为运行通过。两种当前 Linux 运行时与最终归档仍须新证明。

本次渲染后状态/证据增补独立保护完整字节/完整模式和 inode，稳定 ID/命令围栏 不变，并有双语源码检查和保留 inode 安装器夹具。新增字节没有经前述 67.21 秒 运行渲染；不推断重复渲染、消费者源码写入、公开发布、采用或部署。

必需门禁矩阵

通过与待完成条目明确列出，不推断后续门禁成功。先前 R1–R7 节、完整调用失败及限定接受 收据保持不变。临时验收文件留在规范内容和 Git 外；首次规范晋升与渲染已有准确收据，但本次状态增补仍为受保护提议， 不宣称公开发布或部署。

2026-10-04 当前运行时完成增补

本增补记录 2026-10-04（Asia/Shanghai）的当前候选。带日期页面 URL 与初始 2026-10-03/R1–R7 记录保持不变。此前 R8 阶段及浏览器/渲染收据只证明各自冻结 输入，不验证后来变动的后端字节。三个 UI 文件与已通过浏览器验证的字节/完整模式 准确相同；当前 Go、Hugo、平台、归档与四消费者检查刷新变动后端。

首次当前 ARM 离线单元运行发现真实产物复制完整性缺口：ext4 上增加目录项时， 父目录分配大小和实际观察时间戳可能不变。该失败运行在后续验收前停止。有界 修正捕获并重新验证实际排序目录成员及项身份，同时保留常规文件字节/完整模式 证明。仅 internal/app/studio_output.go 与其归属测试变更。失败收据和独立审计 保留，失败运行不会改标为通过。

前一完整性修正验收的完整冻结为 683daca0e522193c7ff1b0de6ac2fee5d2fca080811bf184a8dfd5b90a33f224： 123 个运行输入哈希为 d346ad15cd4239004e32e1b9f30d727eaf156be0187dc165ca874032a7cf962a， 212 个完整 CLI 输入哈希为 2abd1a044d8192b07f9bbc06b55dc8b4544d66ca17b8867971cec702ba3af088。 0.5.0-r8-local Darwin arm64 候选为 74ad94e73557f6538cd64edd1766d6df92c596d98411031159d94af072c186ec。 下列已观察的完整性修正收据绑定前一源码范围；旧 R2 Linux 与此前 R8 二进制收据保持历史范围。 后续单个归属夹具修改具有独立完整源码身份和已完成的正式验收边界，如下记录。

当前完整源码冻结现为 196245a3ba09305e34b86539c8eb79f1473e4373ee47aa1f56f8933b04a42d43。 123 个运行时输入准确保持 d346ad15cd4239004e32e1b9f30d727eaf156be0187dc165ca874032a7cf962a； 212 个完整 CLI 输入为 2c487bfb4c65ed40ff78356b2860de627e6ac1afa0da2df433b09345dab7f5b0。 只修改发布缓存归属测试，其源码为 54c10ef89310256b5f4c165c7de5de9668e1d4d2991b71751076680141dbe779。 夹具修改有独立保护，生产字节与全部语义断言保持不变。该完整源码的八项当前 归属门禁、刷新归档与完整 plain-Go AMD/ARM 正式验收已通过。根 A18 证明 2c018cb2afa3f26699a9e6b5a0971096246b12405fde5a27e43a9e213e46da60 绑定全部三个声明支持目标与五份复现归档。此前收据保持自身捕获范围， 不改称新测试源码的运行。

此前六门禁 b40b7787b3da8dc1e0763812b6dde529b4b5b69fe479d79940f1161223124e1d、host/归档 bcb4d7599e965c1b3cfe7fe698ca14061ad53d45e7a194337aeebb8d37aa77c1 与 ARM 外层 a022e40f068703cd59ce6d6a7fb6530cce6907681baa26eb1dfc77c09f0c8898 / guest 409990bc1425f4bf219f8911a71581af6e68729865580121dbeb6d85a06d2ea7 / 审计 24afc50f6f860394d1ebfa7a8b754ddd9cb97f9e88a0dcfcbcb659193ecbfe5f 仅验证自身捕获源码，与新准确源码证明共同保留，不覆盖或改称新结果。历史 26 项 axe/截图与 22 项 codec 案例依据未变 UI/codec/运行时输入复用，不宣称重新执行。

首次 max CPU 的 AMD 试验保持失败：收据 3543664ba5590f2ba5a8f676b196bb636b72bc819913289f415d0a8a841c1bdb、guest 汇总 16075204d287713c7f7650c0a65dd289dd4bd83db07c9ba4b85b3f21244d5240。测试客户端等待候选响应头 90 秒后超时，候选一致性、其余六项选定 Hugo、原生重构/安装 smoke 未执行。guest 输入保持准确；host 保护只记录 .git 目录时间戳变化，原因未证明。独立 qemu64 单案例 preflight 也在未变更的 90 秒 HTTP 客户端截止时间失败：外层收据 fc68173ccdfd8ce263ecdf082a533d9da666a4cc2e1e5e29880ee827286132ac、guest 汇总 e350ff65feeee166ffac1d337db9bbd70d3895b1fb6d93df0a30ca4de09019fc。具名案例耗时 177.71 秒，首次为 176.64 秒，不能推断 CPU 模型提速。其输入准确保留、VM 已回收；两次失败均不改称通过。

随后明确不构成验收的 Go overlay 诊断保留相同生产源码与全部原语义断言。 外层收据 0bc6d563b7cd9ca862717c2123ee0836d83b6b927d00204a0b031049c38e93f0 与原始记录绑定分类 66a1422cdb79ab9f1cf683f441ade0ce4adb4a7a666d524c4b9ed98ebee28708 记录具名案例在 352.40 秒内通过。原始捕获耗时 26.254 秒、Studio 捕获 26.211、 候选 HTTP 94.312、直接预览 94.318、CLI 预览 81.962。两份图均保留 1,256 个 唯一输入，其中模块输入 1,198 个。HTTP 返回时旧的原始捕获 context 已过期； 独立的新直接/CLI context 正常完成。全部 20,564 项 host 保护与五对 guest 命令 保护准确一致，独占 VM 正常回收。该诊断改变测试预算，不构成准确源码或完整 A18 验收。限定归属夹具修改现为该候选请求及独立直接/CLI 操作各提供 300 秒， 约为已观察最慢操作的 3.18 倍。一般/原始捕获 90 秒限制、共享客户端恢复、 15 秒 shutdown 与 Go 默认十分钟上限不变。这是测试夹具上限，不是产品性能 SLA。 正式 plain-Go AMD/ARM 与当前归档验收归上表当前记录；该诊断本身仍不构成验收。

前次语料验证未变更的运行时 CLI 与所捕获、未变更的最终 TEN 修订前消费者输入，不验证 随后修改的规范文档字节；最终 TEN 有独立渲染收据边界。

消费者 driver 比较 API 与 CLI 的完整类型化诊断、覆盖、原生退出、PlanID、所选 Base/After/完整模式、统一 diff 与所选源码，另外独立验证完整字面 API 审阅及其 哈希。附件和 no-op 的所选页面保持审阅 Base，页面文件编辑匹配审阅 After。 非问题视图为有界样本，所有问题/页面分页读取。53 个保护操作具有 212 次全四站 逐操作源码证明与四次整体证明（四种清单类别共 864 对原始清单），以及 53 对 根清单。绑定 71 份保留产物。没有 Apply、保存计划或消费者写入。已完成语料的 纯文件 collector 因旧试验/self-test 文件不在新目录而保留两次元数据修正；未重跑 CLI/Hugo 操作。现有 22 个负向 codec 案例是相同 codec 字节的历史检查，不能 宣称本轮新执行 self-test。

仓库保留 10,462 项已有重复 ID 发现和 788 项审阅信息。所选实际 DFE HTML 可用， 四份过大实际 PRINT 文件保持不服务（413，响应正文零字节）： _print/pkg/index.html 73,976,221 字节、_print/pkg/pgsql/index.html 69,903,999、 zh/_print/pkg/index.html 73,086,240、zh/_print/pkg/pgsql/index.html 69,052,754。 逐文件 64 MiB 预览上限不变：必需局部预览未完成仍为 2，原生发现仍为 1， Apply 被拒绝。这是预期诊断结果，不是保护检查失败。

Linux 前置条件在独占私有 guest 中依据签名 Debian 元数据预备：准确十个新包和 三个获准既有包升级，安装前后均验证。SDK/Hugo/模块缓存独立供应后离线复用。 验收在 ext4 上以普通用户运行，缓存输入及全部 212 个源码文件的字节/完整模式受保护。 缺少前置工具的 guest 不隐含可选工具/浏览器通过：默认单元跳过保留实际门控或 不适用原因，所有必需纯测试顶层、无跳过目录成员子项、选定 Hugo 与信号案例必须执行。Linux amd64 在 ARM 主机上通过 QEMU TCG 明确模拟。Darwin amd64 保持实验归档：实际执行 返回 Bad CPU type（errno 86），没有安装 Rosetta 或宣称受支持运行时。Windows 不在声明范围。

当前 Linux 归档摘要为 ac883e54a1df0b820696279c63881ba75a00d279f507330128fe8d5aff59c52e （arm64，4,552,687 字节）与 2dde43bf94ef35aac2111b07dcb9b2766fbf9f883fe39ccd646d14a98b94d734 （amd64，5,034,668 字节）。此前 683daca0…33f224 的摘要 c191383af21913be6940ec41be11755b3d985344bbc0f65cc3f5de16424a96a4 与 6531b27d889260afe804c1f49f37541fbae46e57b5d17a20178c28cb51968794 保持历史范围。交叉编译本身不证明运行支持。SDK/guest 准备失败、 首次 ext4 成员检查失败及此前私有 host 元数据/resources 试验保持不可变证据。 本地完成不建立提交、公开版本、消费者采用、托管 CI 执行、部署或公网站点验证。 未启动 E1–E4 是独立非活动范围，不使有限 R1–R8 完成保持未决。

验收用例台账

下表结合初始审计、已接受 R1–R7 证据与已验证 R8 候选门禁。 每个完整用例只有在全部结果记录后才能关闭； 已验收阶段不关闭后续阶段范围。

候选站点与源码保护

选定验收输入为内嵌 Starter 和三个不同的维护中消费站，复用历史语料但不写入消费站源码。 Starter 源 checkout 是来源输入；生成的配置试验使用临时目录。

每次运行记录有效模块来源和版本、参数/网络政策、退出码/结果/覆盖、原始证据位置和保护结果。 前后清单必须包含所有 tracked 和未被忽略的 untracked 源码字节与模式、Git 状态/index、 workspace/replacement 文件及有效 vendor 输入。比较精确清单；文件数相同不能证明保留。 报告、隔离候选、产物和缓存放在消费站源码外，并保持不入 Git。 承诺增量速度前，全量构建耗时必须基于同一份当前输入比较。

归属检查与文档验收

先执行最小受影响 Go 包和公共行为测试。仓库现有门槛为 make test（离线测试和 vet） 及 make test-hugo（真实 Hugo Starter、快照、manifest 与公共命令夹具）。 归属 Hugo 门禁现运行全部归属包，不再使用旧的窄测试名称过滤器；新增夹具必须保持在门禁中。 并发计划/服务修改在归属测试需要时使用 race 检查。单元夹具保持离线，联网须显式调用。

文档保留中英文标题数量、顺序和稳定显式 ID。最小源码检查为：

node scripts/check-markdown-style.mjs content/docs/design/research
node scripts/check-doc-translations.mjs

添加本记录及中文对应文件后，两项源码检查均通过：八个中文研究文件通过风格检查； 翻译源码覆盖为 137/137 组，共检查 1,082 个源码标题。 这些检查只证明源码风格、配对和中文显式 ID；此次文档审计没有执行产物验收。

构建相关站点后，完成产物文档验收：

npm run _check:markdown-style
npm run _check:translations
npm run _check:rendered-markdown
npm run _check:rendered-links

make build 验证声明的公开固定版本；make check 选用同级主题执行完整非浏览器回归套件。 两种输入不能互相替代。Studio 需要自身的真实浏览器和无障碍验收。 文案源码检查通过不能证明双语渲染输出或 Studio 交互。

交付状态与剩余限制

有限 R1–R8 实现与必需当前 A01–A18 运行时/归档范围已有决定性本地证据。 规范生命周期渲染需要这些准确新文档字节的独立收据，此前渲染证据不证明新字节。 未启动 E1–E4 和实验/ 不支持平台不增加未完成核心要求。公开发布、推送、部署、托管 CI 和消费者写入 保持独立未执行；已知仓库发现及必需预览未完成是诊断限制，不隐含通过。

7.10 - 2026-09-29 CLI 验收快照

输入与方法

CLI 位于独立的 oink-cli Go 仓库。已接受的边界见 CLI 与结果契约，可复现的用户步骤见 使用指南。Hugo 继续作为外部渲染器，生成站点保留普通 Hugo 输入。

Starter 归档哈希为 e55bde279715f6d8d19d3d88671a2cf7561b515be46915b0f12c640d0ce1d958。 已记录的投影包括选择已有语言配置、固定 OINK v1.1.0，以及为新目录设置 enableGitInfo: false。最后一项来自真实故障：原有 enableGitInfo: true 会让 尚无第一次 Git 提交的站点在严格构建中因警告而失败。没有通过创建 Git 仓库或提交 掩盖这一问题。

检查使用临时源副本、模块及渲染缓存、输出目录。CLI 检查没有写入原始 Starter 或 消费站源码，并保留了主题与文档已有的无关修改。下列数量是对应输入与 CLI 修订的 快照，不是要求后续文档修改继续维持的阈值。

Starter 与普通 Hugo

预备模块并隔离缓存后，六组普通 Hugo 用例均通过 --environment production --panicOnWarning：

测试检查了预期语言根与代表性 Docs、Blog、Book 产物，并比对 Hugo 构建前后的 生成源码字节。公共 CLI 的 init 命令还分别通过了三种语言配置验证，每组均无诊断， 生成 94 个源文件。三种配置的区别在于选定的根配置；其他语言示例仍保留在快照中， 通过既有语言配置禁用。

Starter 包的单元测试、race 与 vet 检查通过。失败用例覆盖非空及符号链接目标、候选 验证失败、计划后目标替换、取消回滚、并发修改或删除，以及归档路径拒绝。重生成脚本 精确复现了固定归档、来源清单与许可证。

真实站点检查快照

下列每次运行均返回 CLI 退出码 0，没有记录诊断。数量描述渲染产物与检查的引用， 不代表作者编写的页面数或独立用户数。

后三项是三个不同的本地消费站仓库。PIG 与目录站验证公开 pin 的解析；OINK 文档站 验证明确选定的本地主题修改，不能用来替代公开 pin 或部署站点的验收。执行这些只读 试点前已阅读站点指令。

检查覆盖已实现的 HTML 链接、锚点、资源及已输出的机器产物，不执行 JavaScript， 不检查外部 URL、托管重定向，也不执行浏览器、无障碍或视觉验收。最终 Hugo 清单 分别枚举了 261、766、662、3,192 项输出声明，按实际语言和 URL 要求每个受支持且 已启用的机器输出。前后清单逐项比对 tracked 与未被忽略的 untracked 源文件字节、 模式和 Git 状态：四站全部未变，分别覆盖 94、415、858、2,294 个源文件。

本轮修复了两项真实回归。仅生成英文的 NAVJSON 模板原本会掩盖中文产物缺失， 现在会返回政策退出码 1 并给出产物位置。PIG 有意使用的 build.render: link 侧栏项最初被误认为缺失页面，现在依据 Hugo 的生效参数排除，并有直接声明与 cascade 继承回归测试。双语 Starter 的普通构建与探针构建对照还证明，全部 223 个 原有产物字节完全一致。

离线执行与升级

macOS 上，在依赖齐备后，已初始化双语 Starter 的全站 check 在 sandbox-exec 的 (deny network*) 限制下通过。结果为退出码 0、零诊断、 223 个文件、95 个 HTML 文件、4,461 条引用、4 个机器产物。另一次英语 init 也在相同操作系统网络禁止条件下通过，返回退出码 0、零诊断，并生成预期的 94 个 文件。这些是针对对应操作实际执行的网络禁止测试，不是 Linux 防火墙测试，也不代表 所有消费站的远程资源流程都已验证。

一个依赖 example.invalid/[email protected] 的冷缓存夹具返回 CLI 退出码 2，并保留 Hugo 原始的 module lookup disabled by GOPROXY=off 证据。 依赖缺失因此被报告为必要工作未完成，没有静默启用联网解析。

另一个临时站点执行了真实公开模块从 v1.0.0 到 v1.1.0 的升级，原始消费站没有作为 写入目标：

无关的已修改 README.md 和未跟踪的 user-note.txt 在三次操作后均保留。预览与写入具有相同计划 ID，以及相同 模块文件前后哈希。这证明已执行的单站点路径，不代表 vendor 刷新或独立用户完成 升级。replacement、workspace、脏目标文件、回滚及失败保护场景通过了最终聚焦 Go 测试与 race 检查。写入只改变 go.mod、go.sum，备份清单保留原始字节； 预览与重复执行保留全部源码字节。

另在临时初始化站点运行了真实薄包装验收：build --json 返回 0 并生成 index.html；dev --json 提供 HTTP 200，将 SIGINT 转发给 Hugo，并关闭监听。 Hugo 返回 0，被取消的包装进程按约定返回 2。这些运行使用预备缓存，未启用 --network。

最终 make test（全部包与 vet）、make test-hugo（普通 Hugo、workspace/配置 优先级、输出探针及语言缺失回归）和 go test -race ./... 全部通过。三种公开 init 配置均在操作系统禁止网络的条件下重跑通过，冷依赖夹具再次返回 2。

归档与安装准备

一个冻结的 CLI 源码快照生成了四份二进制归档、一份源码归档，以及 SHA256SUMS。 从源码归档独立重建后，全部五份归档的 SHA-256 均一致。此次打包验证的输入哈希为：

b07c5b98ef787dfe9924ce7b50c57d018c6149ec493124bb0103551a01535547

最终快照替代中途打包实验。全部五份归档的校验和均已核对，并从解压后的源码归档 精确复现。源码与二进制归档均包含版本化 JSON Schema、许可证、依赖 pin 和 Starter 来源记录。make install 安装到临时前缀及安装后二进制的 --version 检查通过。

归档构建器记录工具链、参数、源码输入哈希与平台限制，只准备本地文件。这项测试 没有建立公开下载 URL 或已发布的安装标签。

复现相关检查

在依赖已经预备的 CLI checkout 中执行：

make build
make test
make test-hugo
go run scripts/snapshot-starter.go --source ../oink-starter

按同级目录布局复现站点产物检查时，将 JSON 与日志保存在各消费站源码之外：

oink_acceptance_dir="$(mktemp -d)"
mkdir "$oink_acceptance_dir/reports"
./bin/oink init "$oink_acceptance_dir/my-docs" --languages all
./bin/oink check --site "$oink_acceptance_dir/my-docs" --release \
  --base-url https://example.org/manual/ --json \
  > "$oink_acceptance_dir/reports/starter.json" \
  2> "$oink_acceptance_dir/reports/starter.log"
HUGO_MODULE_REPLACEMENTS="github.com/pgsty/oink -> $(cd ../oink && pwd)" \
  ./bin/oink check --site ../oink.pgsty.com --json \
  > "$oink_acceptance_dir/reports/docs.json" \
  2> "$oink_acceptance_dir/reports/docs.log"
./bin/oink check --site ../pig.pgsty.com --release --json \
  > "$oink_acceptance_dir/reports/pig.json" \
  2> "$oink_acceptance_dir/reports/pig.log"
./bin/oink check --site ../repo.pgsty.com --release --json \
  > "$oink_acceptance_dir/reports/catalog.json" \
  2> "$oink_acceptance_dir/reports/catalog.log"

在提供 sandbox-exec 的 macOS 主机上，初始化双语站点之后执行：

./bin/oink init "$oink_acceptance_dir/my-bilingual-docs" --languages en,zh
sandbox-exec -p '(version 1) (allow default) (deny network*)' \
  ./bin/oink check --site "$oink_acceptance_dir/my-bilingual-docs" --json \
  > "$oink_acceptance_dir/reports/offline.json" \
  2> "$oink_acceptance_dir/reports/offline.log"
sandbox-exec -p '(version 1) (allow default) (deny network*)' \
  ./bin/oink init "$oink_acceptance_dir/offline-en" --languages en --json \
  > "$oink_acceptance_dir/reports/offline-init.json" \
  2> "$oink_acceptance_dir/reports/offline-init.log"

升级指南说明预览、计划审查与显式应用步骤。 写入路径测试应使用单独的审查副本。归档实验需保持 Go 工具链和发布版本一致：

make release VERSION=0.1.0-dev DIST=dist/first
mkdir -p dist/rebuild
tar -xzf dist/first/oink_0.1.0-dev_source.tar.gz -C dist/rebuild
make -C dist/rebuild/oink_0.1.0-dev_source release \
  VERSION=0.1.0-dev DIST=dist
cmp dist/first/SHA256SUMS \
  dist/rebuild/oink_0.1.0-dev_source/dist/SHA256SUMS

限制与交付状态

原始 JSON、日志、源码保留清单、升级恢复证据与归档核验结果保留在 CLI checkout 已忽略的 tmp/acceptance/ 下，归档位于 dist/first/。这些是本地证据，不是公开 下载。本次改变 CLI 行为和文案，不改变主题呈现或交互，因此未运行浏览器套件。

首期候选没有实现 Docsy 转换。上述试点已经使用 OINK，不能验证任意 Docsy 或 MDX 迁移。路线图继续将有范围的 Docsy 评估及后续迁移、主题能力描述、版本生命周期、OpenAPI、MCP 与 Studio 作为 独立提案。本地证据记录没有接受任何后续能力，也没有将它们计为完成。

8 - 设计提案与 PRD

本栏目是 OINK 产品需求文档、RFC 风格设计与未决维护者提案的唯一正本位置。不要在主题仓库或 文档仓库中另建本地 plan/、plans/、proposal/ 或其它并行设计树。

当前提案

Agent 批量索引提案已在输出交付后退役。稳定行为现在归属 架构，用户步骤归属 Agent 就绪输出。Book 出版提案也在 BookManifest 与 EPUB/PDF 工具交付后退役。稳定行为归属架构与 创作书籍，带日期的下游采纳证据归属 消费站证据。剩余的消费站采纳工作 不会让上游设计提案继续保持活动状态。两份提案草案均由 Git 历史保存。

生成式配置 Schema 提案已按生命周期退役：行为的规范位置是配置总览， 长期理由进入生成式配置 Schema 决策，草案原文由 Git 历史保存。

CLI 工作区与适配器

显式 workspace 与可选适配器保留在当前收缩后的 CLI 中。 当前契约与 使用指南定义命令边界。 带日期 R1–R8/A18 记录是绑定历史源码/二进制的证据，不能证明后续命令或输出修改。 有限维护路线继续退出活动导航，尚未建立公开 CLI 发布或部署。

新 PRD 放在哪里

创建一份英文主页面及其简体中文对页：

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

两份文件都使用显式、稳定的英文标题 ID。中文页面中的代码、键、路径、版本与 API 名称保持原样。 提案开头要有可见的草案状态，并包含：

1. 状态、负责人、日期和受影响契约面；
2. 背景与证据；
3. 目标与明确非目标；
4. 提议行为，以及输出、无障碍、安全边界；
5. 兼容与迁移影响；
6. 实现与归属检查器计划；
7. 验收标准与待决问题；
8. 记录提案自身变化的决策日志。

大型实验可以在 ../research/ 下增加带日期的页面；临时日志与生成 产物不进入 Hugo 内容，也不进入 Git。

生命周期

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

提案被接受后不会自动成为第二份契约。稳定行为进入归属契约，稳定理由进入 Decisions，用户步骤进入 相关指南，然后把提案退出活动导航。本地构建、提交、tag、公开模块、消费站 pin 与部署仍是相互独立 的完成状态。

评审门禁

实施前，评审者确认提案没有重复已有外壳、resolver、组件族或数据权威。实施期间，如果设计改变， 先更新这份双语提案，不能让代码悄悄漂移。验收至少覆盖主题的最窄归属检查、真实文档站、渲染后的 中英文、相关输出、无障碍与响应式检查。

只读 Studio 候选

2026-10-04 当前 CLI 移除 Studio。使用 oink dev、普通编辑器与 inspect/check 结构化报告。R7 记录 保留此前浏览器实现的历史验收。

受审阅编辑

当前 CLI 移除通用源码编辑，保留受保护的 new、move、审阅记录与基线计划。 旧编辑计划会被拒绝。R8 记录 继续作为历史证据，不是当前命令 API。

8.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。

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

8.3 - OINK CLI 与下一阶段产品路线

核心建议

独立建立 oink-cli 仓库，发布名为 oink 的可执行文件，对外继续使用 OINK 这一个产品品牌。主题负责渲染内容；CLI 帮助用户初始化、诊断、校验、升级，随后逐步支持迁移。文档站继续管理公开指南、双语设计记录和集成验收。

仓库选择与 Go 实现现已接受并在本地建立，公开发布仍是独立动作。首期行为已移入 CLI 契约；带日期的验收记录列出实际执行的检查与剩余限制。本路线图继续承载后续阶段和采用目标。

首发应改善从现有仓库到可靠发布的流程，四项实质性能力是 doctor、check、init、upgrade。dev 和 build 可以提供轻量、透明的 Hugo 快捷入口。根据真实输入仓库的证据，再扩展一条有明确支持范围的 Docsy 迁移路径。版本生命周期和 OpenAPI 生成排在首个可用版本之后，同一时间只推进一个主要内容模型项目。

主题必须允许用户不安装 CLI。对于生成内容，这意味着提交生成后的 Hugo 输入，或者以其它明确方式提供这些输入：移除 CLI 后，普通 Hugo 仍能构建站点。重新生成输入是独立操作。

产品定位与目标用户

建议对外描述为：

OINK 是基于 Hugo 的本地优先文档工具箱，将工程知识发布给读者与 Agent。

安装说明和检索入口仍保留“Hugo 主题”，因为它准确描述用户安装的东西。“知识编译器”适合作为架构方向，但目前不足以证明 OINK 已经建立了新的产品类别。新的叙事不应遮蔽现有 Markdown/Hugo 路径。

优先服务使用 Git 的开源基础设施、开发者工具和多语言技术文档维护者。他们眼前的任务是让站点运行起来、定位故障、安全升级，以及在迁移中保留 URL 和内容含义。现有维护站点提供回归证据，独立团队提供采用证据，两者用途不同。

首阶段明确不做可视化 CMS、托管账户、部署控制台、软件包市场、LLM 运行时、语义搜索服务或新渲染引擎。书籍、博客和落地页继续得到支持，但不由这些场景的功能清单驱动本轮路线图。

证据与对研究建议的调整

本提案参考用户提供的战略报告，并对照本地实现、双语 Design 专栏、Starter 和当前官方文档核实。不把报告中的 Star 数、工时估算、商业价格或市场判断视为已验证需求。

原报告正确强调了采用成本和可选工具层。以下四项调整能让它成为可执行计划：

1. 将安全升级与初始化、诊断并列。现有用户已经有直接、可测试的维护需求。
2. 区分维护者回归检查器与消费站检查。面向固定夹具的脚本不会自动成为通用站点校验器。
3. 按明确的输入配置范围承诺迁移，不承诺完整 Docsy 或任意 MDX 转换。
4. 将同时开展版本化、OpenAPI、图谱和平台建设，改成逐阶段决策。功能列表与工时相加不是人员到位的交付计划。

竞品能够证明流程方向已有先例，不能证明 OINK 自身的需求。Mintlify CLI 提供预览、校验和链接检查；Nimbus 将脚手架与 Agent 可读产物结合，目前仍为 pre-1.0；Docusaurus 明确定义版本快照，也提醒其维护与构建成本。如果照搬 Nimbus 将整套界面源码交给用户的模式，会把升级维护工作转给 OINK 消费者。可以对小型内容模板借鉴该方式，主题本身仍保留可升级模块。

为什么独立建仓

这是发布与职责划分，不是说单仓在技术上不可行。嵌套模块能够隔离依赖；分仓也确实会带来协作成本：一次渲染行为变化可能需要两个 PR、配套契约与兼容性测试。OINK 已经采用主题、文档站和 Starter 分仓，只要公共边界足够小，这个成本可以接受。

主题与 CLI 不应强制使用相同版本号。建议 CLI 0.1.x 同时支持经过测试的主题 1.1.0 基线和下一受支持版本，按能力声明兼容范围。遇到不支持的功能应明确报告，不能拿最新主题的全部 Schema 去判断所有旧站点。

现在不另建 linter、迁移引擎、OpenAPI 生成器或共享 SDK 仓库，先作为 CLI 内部包。二进制可以用 Go 编写，同时不引用 Hugo 内部 Go 包，也不让主题模块依赖 CLI。

职责划分

                         可选的 oink CLI
                  init / doctor / check / upgrade
                      后续 migrate / generate
                               |
                               v
                 用户拥有的 Markdown + Hugo 配置 + data
                               |
                     Hugo Extended + OINK 主题
                               |
               HTML / Print / Markdown / 搜索 / 索引
                               |
                     读者 / Agent / 可选适配器

CLI 读取 Hugo 的生效配置、实际解析到的主题所发布的契约文件，以及构建产物。不应通过文件名猜测最终页面树，也不维护第二套导航解析器。Hugo config 已能输出生效配置；模块检查还需覆盖 replacement、workspace 与 vendoring。

下一期主题：建议 OINK 1.2

本节保持草案。本地 CLI 候选使用已发布的 OINK v1.1.0 基线；首期 CLI 决策既未接受主题 1.2 发布或新的工具能力描述，也不以它们作为前提。

本版本以降低采用成本为目标：站点能向工具准确说明配置与输出能力，升级不要求引入新的创作模型。范围应足够小，能够独立于后续大路线发布。

能力描述属于发布元数据，不是新的配置权威。配置 Schema 继续从现有权威生成，可选形态校验仍归对应解析器与检查器。不要违反现有诊断决策，另建通用改名键注册表。迁移转换应属于明确的 CLI 配置范围，而不是模板中的永久兼容路径。

1.2 不要求增加新的视觉组件族。正确性、无障碍和已经发现的回归仍可驱动修改。现有媒体工作保留其独立验收范围，本路线图不把所有草案完成都变成发布条件。

CLI 首发：建议 0.1

下列命令已在本地 0.1.0-dev 候选中实现。当前参数、结果语义与限制由 CLI 契约及使用指南定义；公开分发与最终验收仍为独立状态。

check 是统一质量入口。0.1 不同时设计职责重叠的 lint、validate、audit、check。后续确有需求时，用 --scope 区分源码提示和产物校验。

诊断与质量范围

先覆盖高置信度、可行动的失败：工具链不符、主题未解析、必要配置非法、本地链接目标或锚点或资源缺失、已启用输出的引用不一致。路由和锚点以 Hugo 产物为准，覆盖语言与 base path。不能因为编辑器 Schema 未列出某个自定义 front matter 字段，就把合法输入判成错误。

未启用的可选输出不应触发缺失错误。本地候选不检查翻译完整性；后续完整性规则必须使用站点实际声明的语言和覆盖政策。重复标题、孤儿页、缺少描述、文风与新鲜度仍属后续可选观察项，经过真实误报评审后再决定默认值。静态检查不能声称浏览器无障碍或交互测试已经通过。

本地候选冻结 oink.result/v1：结构化诊断包含稳定规则 ID、严重度、已知位置、解释、行动建议与明确覆盖范围。JSON stdout 只输出结果，日志进入 stderr，所有命令均不等待输入。退出码 0 表示必要工作完成且无阻断项，1 表示政策问题，2 表示必要工作未完成。必需但不支持的检查不能返回成功。详细字段归属结果契约，不为构建派生问题编造行号。

保留 Hugo 原始错误作为子进程证据，其人工文案不构成 CLI 协议。将来可以从同一结果投影 SARIF，而不改变规则语义。

升级与文件保护

现有消费站升级脚本提供了有价值的本地先例：区分声明 pin 与解析版本，发布验证时禁用两套 workspace，识别模块 replacement，检查 _vendor。通过聚焦测试移植这些行为，不能在背后调用未发布的 Python 文件，却宣称是独立 Go 二进制。

0.1 只升级一个明确选择的站点。跨站批量发现暂留维护者脚本，等真实消费者提出需求。普通 check 可以检查有意使用本地主题替换的环境；check --release 必须排除这些替换，验证声明的公开版本。发现 go.mod 中冲突的 replacement 应报告，不应擅自删掉。

先展示将修改的文件，验证候选升级，再应用。只备份涉及的文件；预览后文件又发生变化时拒绝覆盖；保留无关的未提交工作。失败时应说明哪些已应用、哪些未应用，并提供不会覆盖后续编辑的恢复路径。仓库不干净不应阻止只读诊断。刷新 vendor 是单独的显式动作，只改 go.mod 不等于升级了 vendor 输出。

初始化和修复不能顺便 commit、push、部署、修改全局 Agent 设置或安装系统包。向明确的新目录初始化，本身就是用户请求的创建动作；修改既有文件则默认预览。不要为了这些有边界的操作构建通用工作流引擎。

分发与离线行为

本地候选当前提供已测试的源码／Make 安装路径与归档准备。公开 Homebrew formula、下载入口及标签安装仍属后续分发工作。当前运行验收覆盖 macOS arm64；其他归档目标仅为交叉编译候选，尚未在对应平台执行。

采用 Go 可执行文件，提供发布归档、校验和与 Homebrew 安装方式。先正式验证实际测试过的 macOS、Linux 架构，其它平台在文件系统和进程行为验证前标记为实验支持。安装后的 CLI 本身不要求安装 Go 工具链、Python、Node 或注册账户。Hugo 仍为外部渲染器；首次模块解析仍需要站点文档规定的 Git、Go、Hugo 工具链。

嵌入或随版本提供准确、保留许可证的 Starter 快照，保证初始化可重复。不应每次抓取变化中的 main，也不在 CLI 中手工维护 Starter 配置副本。发布 CLI 时检查内嵌模板与来源的一致性。

区分冷安装与离线运行。未在本地提供时，下载 Hugo、主题或未缓存模板需要网络。依赖齐备之后，本地诊断、检查和构建路径应无需外部服务。离线请求遇到缓存缺失应明确失败，不能偷偷下载。外链检查、远程规范等联网行为单独启用。无需默认遥测或后台更新检查。

第一项扩展：迁移

从实际候选站点中选择一套 有文档说明的 Docsy 输入配置范围，参考现有迁移夹具和报告模型。现有 OINK 0.4/0.6 转换并不能证明任意 Docsy 站点已经可以迁移。除 Markdown 语法外，还必须检查配置、导航、资源、语言和路由。

拟议流程为 oink migrate --from docsy --source <site> --output <new-site>。先评估再写入；应用需要显式参数，并输出到独立目录。每个源项目只有一个主要状态：原样兼容、已转换、人工复核、不支持。数量必须能够核对，附理由与源码位置。自定义模板和动态行为应明确列为人工工作。

验收包括源文件保留、支持范围内的转换幂等、不修改字面代码示例、站内引用有效，以及明确的旧新路由对照。优先保持 URL；改变 URL 时须提供适合托管目标的重定向方案。HTML 构建成功不足以证明语义一致或生产重定向生效。

不要承诺“一条命令迁移任意 Docusaurus 站点”。任意 JSX、import、内嵌 React/Vue 是程序，不能执行不受信任的源码来猜测含义，也不能静默删除无法处理的内容。第一条配置范围在没有维护者救场的情况下得到复用后，再开始第二个框架。完整 MDX 迁移是后续产品投入，不是 MVP 的一个解析器任务。

下一项内容能力：版本生命周期

首个 CLI 有用之后，默认优先考虑版本生命周期，因为它延续 OINK 已有的独立构建模型。只有真实 API 用户提出更强、反复出现的需求时，才把 OpenAPI 提前。单一主维护者不同时实现这两个基础。

主题负责读者界面的版本身份、可靠页面切换、归档状态，以及范围正确的搜索和机器输出。CLI 负责查看版本、准备快照、验证页面对应关系、修改声明的生命周期状态。oink --version 表示可执行文件版本；将来的 oink docs version ... 避免与文档版本混淆。

优先采用小型版本清单，记录版本标签、源引用、base URL、状态和默认选择。保留各版本独立构建及现有外部归档。CLI 管理的清单可以生成纳入 Git 的 Hugo 配置；在该模式中，清单由用户维护，配置是接受检查的投影。现有手工管理的 params.versions 继续受支持。原型必须先确定投影关系，再冻结格式。

页面对应关系需要按文档族、语言、版本区分的逻辑页面键。优先复用合适的 translationKey 或显式稳定键，不先引入通用 UUID。目标版本缺页时应明确说明，并进入约定的版本或分区首页，不能伪造等价页或盲目拼接 URL。路由别名处理页面搬迁，与页面身份分开。

内容有实质差异的历史页通常保留自己的 canonical URL，不能全部指向最新版。语言 alternate 应指向同版本中确实存在的翻译。默认搜索与 Agent bundle 保持在当前语言和版本范围内；将来若有跨版本聚合，必须显式启用。归档应保留源码并记录构建产物如何保存，不等于删除，也不悄悄重新部署不可变归档。

NAVJSON v1 的对象 Schema 当前禁止额外字段。因此增加版本或身份字段需要明确的新 Schema、输出契约或独立产物，不能声称是无影响的 v1 字段扩展。仅仅为未来图谱预留空间，不足以成为修改当前页面身份的理由。

随后的能力：静态 OpenAPI 参考

首个 OpenAPI 产品应是 只读静态参考生成器。CLI 解析本地规范及支持的本地引用，输出普通 Markdown/Hugo data，记录来源。主题提供符合无障碍要求的语义呈现和已有输出流水线，再由普通 Hugo 将生成页构建为 HTML、Print、Markdown、搜索和 Agent 索引。

先支持操作、参数、请求与响应正文，以及带链接的 Schema 描述。解析器原型完成后明确支持的 OpenAPI 版本和构造，不能静默丢弃不支持的构造。操作身份按 API/规范分域；缺少 operationId 时可由 method/path 派生，同时提示路径变化会影响身份。不同 API 复用同一 operationId 不能发生冲突。

人工指南与生成事实分开保存。生成必须确定、记录源哈希和生成器版本、能够检测过期输出，遇到非预期人工修改拒绝覆盖。将生成源码纳入站点 Git，或作为带版本的构建输入提供，使渲染本身仍不依赖 CLI。解析远程引用属于显式准备步骤，普通生成不能遍历任意外部 URL。

验收除玩具示例外，还要有真实用户规范；支持的操作完整可核对，循环引用能够处理，路由稳定，选定输出均包含语义内容，新静态渲染器的无障碍检查不继承 Swagger/Redoc 豁免。承诺吞吐指标前先测有代表性的大型规范。

保留现有 Swagger/Redoc 集成的兼容性。交互请求、凭据管理、SDK 生成、mock server 和 API 测试平台不进入本轮生成器增量。

架构与兼容规则

CLI 内部保持简单：命令处理、Hugo/进程适配、诊断、模板加载、限定范围的文件修改。迁移和 OpenAPI 到达对应阶段后再增加内部包。这只是建议分层，不是插件 ABI 或公共 SDK。

三个边界需要版本化：CLI 的机器结果格式、主题的公共 Schema/输出契约、受支持的迁移或生成输入配置范围。优先按能力检测，不一刀切要求“最新 OINK”。遇到更新但不支持的 Schema 时，必须给出可理解的兼容性诊断。

CLI 不能导入同级主题的私有 Python 模块、依赖特定本地 checkout 布局，或者运行时下载可执行检查器。通过行为测试移植选中的消费站操作。模板内部检查器仍留在主题；公开消费规则的后续变化同步更新其对应契约。过渡期间保留现有脚本，替代实现覆盖受支持场景后再退出重复实现。

初期不要求 CLI 配置文件，渲染配置继续由 Hugo 管理。重复使用证明有必要时，工具政策文件可以包含忽略路径、规则严重性和经过审阅的基线，但不能再维护 params.ui、导航、语言或模块 pin 的副本。Lint 基线不能豁免 Hugo 构建失败、输入不可读或必需检查不受支持。

路线图与人力假设

下列时间范围保留原始规划含义，不作为执行日志。阶段 0 与阶段 1 已有首期本地候选，但这不代表公开发布、独立用户研究、迁移或后续内容模型目标已完成。实际证据归入验收记录。

以下是 首阶段 8–12 周的规划范围，假设约一名全职实现负责人，并有部分文档与评审支持。这不是交付承诺，也不是对实际人力的判断。工具链验证、用户招募和双语评审都需要时间；应优先缩小范围，避免名义上的多线并行。

如果阶段 2 超期，移除该版本中的迁移写入能力，保留评估报告。不能削减升级保护、真实诊断或 CLI 可选性。如果没有独立团队需要这套迁移配置范围，就停止扩充框架覆盖，回到上手体验与定位研究。

新鲜度、归属信息是后续可选质量能力，先以用户确实会处理的报告验证价值。修改日期绝不能冒充验证日期。先提供少量有用的官方页面模板，再考虑 registry。G2/G3 图谱、MCP、分析适配器、可执行示例、Studio 和托管服务，都需要具体用户问题及资源决策，不应现在填入确定日程。已有静态 Agent 输出，使 MCP 的紧迫性低于采用流程。

验收与产品指标

下列用户与采用指标仍是目标。维护者执行的本地试点用于验证实现和文件保护，不能证明独立团队、首次使用成功率、留存或生产采用情况。

主要采用指标使用独立维护的生产站点，通过公开引用或用户自愿确认核实。稳定文档站不应因为 60 天没有提交而退出统计；主题升级时效与留存分别衡量。Star、下载次数、自有消费站数量和 Agent 生成量都只是辅助信号，不能证明独立采用。

首次本地成功时间、首次生产发布时间、升级成本、迁移人工成本分别记录。部署可能依赖 CLI 之外的账户与服务商，不能把本地验证等同于发布。不要为收集指标引入默认遥测。

实现归属与验证

先运行最小归属检查。公共行为变化仍要求实现、检查器和双语契约协调交付。真实集成与视觉验收使用同级站点的 make check、make browser、make dev 流程。公开回归场景不搬回主题的合成夹具树，也不要求普通消费者安装维护者使用的 Node 测试栈。

发布时分别记录本地检查、提交、标签、公开模块或二进制解析、消费站 pin 与部署。主题发布后的采用继续使用现有消费站盘点流程。一个协调 issue 或清单即可连接各仓库，无需新增编排框架。

待决问题与停止条件

仓库选择与首期实现在本地已确定。剩余发布决策包括经过验证的平台、公开分发渠道、有实际执行证据支持的兼容声明，以及独立试点招募。验收记录列明实际本地工具链与选定站点，不代表未来平台或用户已经验证。

本地候选的结果与退出语义已在 CLI 契约中冻结。最小主题能力描述与稳定主题警告 ID 保持独立提案，不追加入首个 CLI 的前提条件。版本 beta 前确定清单投影、归档保存方式和页面对应关系；OpenAPI beta 前确定支持的规范子集与生成源码归属。

如果试点实际只需要一个小型维护脚本，规则必须反复复制模板语义，或者分发维护成本超过测得的用户价值，就重新评估独立 CLI 投入，并保留已经有用的独立脚本。证据变化时可以调整版本化与 OpenAPI 的顺序，不增加同时开展的总范围。

决策日志与来源

查阅的本地权威包括：架构、生成式 Schema 决策、迁移边界、现有版本行为、OpenAPI 限制、图谱提案状态。还检查了主题 bin/、schema/nav.v1.schema.json、现有 Starter 与文档站构建检查命令。本地在途改动没有被表述为公开发布证据。

外部一手资料核实日期为 2026-09-29，包括上文链接的 Mintlify 命令参考、Nimbus 仓库、Docusaurus 版本指南及 Hugo 配置和模块文档。这些来源支持产品比较，不能证明 OINK 的市场需求或拟议时间表。