# 架构契约

> 仓库装配、配置、诊断、本地化、输出、性能、安全、CSS、无障碍与发布状态的边界。

---

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

---

> [!NOTE] OINK 1.3.1 契约
> 本契约描述 OINK v1.3.1。主题开发使用同级 checkout；发布验收在关闭替换与
> 工作区后验证公开模块。消费站升级与部署分别检查。

## Hugo 工具链 {#hugo-toolchain}

> [!NOTE] OINK 1.3.1 工具链
> 以下构建要求适用于 OINK 1.3.1。从 v1.3.0 升级前，先安装独立 Sass 编译器。

截至 2026-10-17，经过验证的开发与发布工具链为 **Go 1.27.2** 和
**Hugo Extended 0.168.0**。CI 自动跟随 Go 和 Hugo 的最新稳定版，并记录实际版本。
这些默认值不是精确版本锁定：模块声明的最低版本仍为 Go 1.27.0 与 Hugo Extended
0.168.0，不设版本上限。提高 Hugo 最低版本时，同步调整 `hugo.yaml`、`theme.toml`、
站点要求、CLI 版本门禁和当前双语文档。

除非用户明确要求，不运行旧 Hugo 兼容性矩阵，不为旧版本适配代码或增加兼容补丁。
历史发布说明和带日期的研究保留当时的工具版本，不构成当前支持要求。

在 `PATH` 中安装独立的 [Dart Sass 1.105.2](https://github.com/sass/dart-sass/releases/tag/1.105.2)，
不需要 npm 包。主样式与 ReDoc 样式显式选择 Dart Sass，CI 校验编译器压缩包的摘要。
Bootstrap 5.3 与公开的项目变量钩子仍共享传统导入作用域。主样式仅忽略 `import`、
`global-builtin`、`color-functions`、`if-function` 四类已知语言弃用提示；
Sass `@warn`、无效选择器与 Hugo 警告仍会使严格发布构建失败。
Font Awesome 继续使用独立的预编译供应商样式表。

## 仓库与装配 {#repository-and-assembly}

仓库根目录是一个完整的 Hugo 模块与主题，不是站点，也不是 npm workspace。
Hugo 渲染模板，并调用独立的 Dart Sass 编译 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` 类型或第二套博客外壳；沉浸式页面只是[外壳契约](/zh/docs/design/shell/)
定义的一种博客展示方式。

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

## 配置与诊断 {#configuration-and-diagnostics}

主题策略位于 `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、反斜杠、空白字符及缺少路径的同站引用都会告警，并在选择运行时前关闭该集成。

> [!NOTE] OINK 1.3.0 修复
> 添加嵌入参数时保留编辑器 URL 原有的查询参数与片段。消息必须同时来自当前
> 编辑器 iframe 及其配置的源；无关或格式错误的消息会被忽略。图表数据只发送到
> 该源。导出结果必须是 PNG 或 SVG 的 data URL。

## 界面本地化 {#interface-localization}

> [!NOTE] 自 OINK 1.1 起提供
> OINK 1.1.0 将原生界面语言包扩展到下方列出的完整语言集合；消费站点编写的正文
> 仍需自行翻译。

OINK 为
[`google/docsy@64f51c5`](https://github.com/google/docsy/tree/64f51c5bde2abd2e8a001cb31b32656f5800ca56/theme/i18n)
中现有的 31 个 locale 文件名提供原生界面文本，并额外保留通用 `zh` 作为简体中文
默认值：

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

当前 Hugo 基线允许通用 `zh` 语言与地区化中文语言包并存时使用 `locale: zh`，也可
选择 `locale: zh-CN`。两种配置都不改变语言包文件名 `i18n/zh.yaml`。

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

## 特色图片 {#featured-images}

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

| 来源 | 阅读列表缩略图 | 社交卡片 |
| --- | --- | --- |
| 页面 `images`，或页面包中的 `**featured*`、`*feature*`、`{*cover*,*thumbnail*}` | 是 | 是 |
| 分区 `cascade.images` | 是 | 是 |
| 站点 `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 输出时
不渲染图片。

## 输出与运行时 {#outputs-and-runtime}

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

| 输出 | 契约 |
| --- | --- |
| HTML | 完整的语义内容；只为实际用到的能力加载本地运行时 |
| Print | 展开的内容；不含外壳导航、搜索或图片缩放运行时；共享操作层仍支持明确的打印控制 |
| Markdown / LLMS | 保持源 Markdown 形态，不含 `td-` 组件标记 |
| LLMSFULL | 按顶层 section 选择启用：每个启用 section、每种语言一份 `llms-full.txt`，按阅读顺序拼接同一份 Markdown |
| RSS | 安全的静态摘要，或明确省略 |
| NAVJSON | 按站点选择启用：每种语言一份 `navigation.json`，序列化侧栏与 pager 已经在读的导航权威 |
| BookManifest | 选择启用、供出版打包器消费的有序 JSON 交接；绝不冒充 EPUB 或 PDF |

各输出格式按既定顺序执行；可变格式状态并不存在跨格式竞态。但在 Print 内，Hugo
可能并行渲染同一 Book 页面与相互重叠的聚合。因此每页由一个缓存 coordinator 按
固定顺序生成普通与整书两种变体，各调用方只选择自己需要的形态。普通 Print 保留
页面局部标题与带路由的 xref URL；Book 聚合保留带命名空间的标题与文档内 xref。
正文移入 Print 之前，相对链接按各自来源页面的 HTML URL 解析。单页和聚合输出
都保留语言与部署路径前缀、查询参数和编码路径。纯片段链接仍留在当前文档，交由
标题和脚注命名空间处理；规范路径与外部链接保持原目标。
只改写实际的 `href` 属性；`title` 等非链接属性内即使出现相同文字，也必须原样保留。

标题片段在命名空间匹配前只解码一次百分号编码，涵盖 Unicode 与编码后的 ASCII。
字面加号仍为加号，格式错误的转义保持原样；ID 与属性中的 HTML 实体单独解码。
片段规范化不会改动路径、查询参数或外部来源。
Tabs 及其他 Markdown shortcode 内渲染的标题使用相同的命名空间，
即使 Hugo 没有将它们纳入 `Page.Fragments`。
以实际渲染的标题 ID 为准，保留中文、字面加号和百分号序列，不从转义后的标题自链接反推 ID。

Landing 页面配置 RSS 输出后，通过共享 RSS 渲染器生成静态 feed。
声明的 alternate 输出必须存在实际文件；省略交互式 Landing 组件不等于省略 feed。

Print 页面在送往纸张之前也是可供浏览器阅读的文档。屏幕预览中的宽表格保留带名称、
可键盘聚焦的滚动区，不得撑宽整个页面；打印媒体样式在实际打印时展开这些区域。
表格无需加载运行时；RSS 表格仍是不可聚焦的静态内容。

站点自行选择是否启用自定义输出；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
密度。

单页 Print 只输出一次页面摘要。分区 Print 将所有纳入后代页面的数学能力标志
传递到聚合根，因此目录页本身没有公式时，仍会按子页需要加载本地 KaTeX 样式。
完全没有公式的打印文档不加载这些样式。

## 信任边界、CSS 与无障碍 {#trust-css-and-accessibility}

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

> [!NOTE] OINK 1.3.0 修复
> 普通图片、Gallery 及缩放原图的 URL 在校验后仍须按 HTML 属性转义。
> 引号与 `&` 保持为 URL 的内容，不得生成新属性或被当作 HTML 实体解码。

主题输出使用 `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 注入块
与侧栏根切换器的「这一页是什么颜色」。

## 视觉预设 {#visual-presets}

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`。参见[实验记录](/zh/docs/design/research/2026-10-05-ink-terminal-experiment/)。

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

## 发布状态 {#release-states}

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

---

反链：

- [发布](/zh/blog/release/)
- [版本升级](/zh/docs/admin/upgrade/)
- [多语言](/zh/docs/customize/i18n/)
- [设计](/zh/docs/design/)
- [组件](/zh/docs/design/components/)
- [CLI 契约](/zh/docs/design/decisions/cli/)
- [诊断策略](/zh/docs/design/decisions/diagnostics/)
- [视觉预设](/zh/docs/design/decisions/visual-presets/)
- [落地页](/zh/docs/design/landing/)
- [提案](/zh/docs/design/proposals/)
- [CLI 与路线图](/zh/docs/design/proposals/oink-cli-roadmap/)
- [视觉预设](/zh/docs/design/proposals/visual-presets/)
- [研究](/zh/docs/design/research/)
- [2026-09-19 社区反馈调研](/zh/docs/design/research/2026-09-19-upstream-review/)
- [2026-10-13 主题审查](/zh/docs/design/research/2026-10-13-theme-review/)