设计契约

非规范性材料 提案描述的行为可能尚不存在。当前行为由契约、已接受决策、实现与归属检查器定义。不能把提案 当作配置参考。 本栏目是 OINK 产品需求文档、RFC 风格设计与未决维护者提案的唯一正本位置。不要在主题仓库或 文档仓库中另建本地 plan/、plans/、proposal/ 或其它并行设计树。 当前提案 提案 当前边界 反向链接与知识图谱 G1（静态反向链接）已接受，已在主题 main 分支实现，随 OINK 0.8.0 发布；局部与全站图谱（G2/G3）保持草案 媒体收敛 部分已实 …

证据，不是契约 研究记录测量了什么、使用了哪些输入与工具版本。它可以解释决策，但不能覆盖当前契约或实现。 只有其他维护者能够检查方法、理解边界并复现相关检查时，研究才适合进入公开 Design 内容树。 原始 Agent 对话、临时构建日志和本机绝对路径不符合这一标准。 研究地图 记录 证据 Goldmark 块属性 支持的 Hugo 下限版本上，渲染钩子能看到什么，以及 CommonMark 容器的边界 消费站与迁移证据 带日期的语料盘点与确定性 Book 迁移结果 2026-08-26 全 …

OINK 1.2.0 契约 本契约描述 v1.2.0 的正式行为。唯一的中英文契约源文件位于 content/docs/design/。 Hugo Extended 0.160.1 仍为兼容下限，CI 固定使用 0.165.0；下限版本 不作为第二套完整 CI 矩阵。 本专栏是 OINK 可长期维护的设计记录。站内其它专栏按任务讲解如何搭建站点； 这里集中说明现行不变量、这些选择背后的理由、用于比较方案的证据，以及仍处于 候选阶段的工作。 如何阅读本专栏 层次 含义 契约 兼容实现必须保留的规 …

已接受的理由 决策记录解释 OINK 为什么在多个兼容方案中选择了当前设计。上方五份契约仍是 现行行为的规范描述；实现与归属检查器仍是可执行事实。 OINK 过去把评审、PRD 与执行记录放在本地 plan/ 目录中。这样既不便发现有价值的 推理，也容易让已经放弃的设计看起来仍有权威。已经接受的理由现在统一进入这座双语、 版本化的文档站，与它所支撑的契约放在一起。 决策地图 决策 解决的问题 警告与安全回退 为什么普通预览能容忍错误输入，而发布仍保持严格 配置模型 配置放在哪里、页面如何覆盖， …

本地实现与验收完成 本地 0.1.0-dev 实现已通过本文记录的检查，CLI 源码已提交为 e623d93。 公开发布、下游采用和生产部署仍是独立状态，本轮未执行。 输入与方法 CLI 位于独立的 oink-cli Go 仓库。已接受的边界见 CLI 与结果契约，可复现的用户步骤见 使用指南。Hugo 继续作为外部渲染器，生成站点保留普通 Hugo 输入。 输入 观察到的基线 主机 macOS，darwin/arm64 Go go1.27.1 Hugo …

历史源码与二进制证据 本记录保留此前 R1–R8/A18 验收，不随命令调整重写历史结果。2026-10-04 的 CLI 精简与 Cobra/文本/JSON/YAML 界面以当前契约和 指南为准；旧运行时资格不能自动证明修改后的二进制。 有限实现已本地验证 下文保留初始审计。R1 实现与归属检查已通过其本地范围， 包括刷新后的消费站报告和限定范围的中英文产物验收。R2 本地范围门禁也已接受， 数值相等比较补充单独测试。R3 运行与双语文档门禁通过，阶段已本地接受。 R4 受支持实现与只读语料 …

OINK 1.2.0 Paper 与 Slate 已随 1.2.0 发布。Ink 与 Terminal 作为显式启用的风格一同提供， 后续设计工作见下文记录。 决策 Paper 成为默认，使用暖纸色与墨色、蓝色链接、IBM Plex Sans、标题细线和外框 表格。Slate 保留 v1.1.0 色板、Inter/Chakra/Plex Mono 字体角色与 Landing 网格、 光晕。这样为阅读站点提供更安静的默认外观，同时保留明确的兼容选项。代价是默认 外观发生可见变化：原站点可设置 …

OINK 1.2.0 契约 本契约描述 v1.2.0 的正式行为。唯一的中英文契约源文件位于 content/docs/design/。 这是源码与配置指南，不是版本发布流水账。本地源码、提交、标签、推送、消费站点 固定版本、部署与生产一致仍是彼此独立的状态。面向读者的升级流程见 版本升级。 工具范围 bin/migrations/oink06.py 只扫描和自动改写站点内容目录下的 Markdown 文件， 包括受支持的 YAML front matter。它不改写 Hugo 配置、数据文件 …

当前范围；本地候选 本契约描述 2026-10-04 收缩后的本地 0.1.0-dev 命令界面。保留站点诊断、 真实 Hugo 检查、初始化、构建、升级及有保护的维护计划；使用 Cobra、默认彩色 英文文本与 JSON/YAML 结果。Studio、通用编辑、context、snippets、editor 与 CI 生成已撤下。历史 R1–R8 验收只对记录中的源码和二进制成立，不能替代当前验证。 尚未建立公开 CLI 发布、Homebrew 分发或部署。 背景与归属 主题是 Hugo 模 …

发布准备，不是发布声明 本文分别记录审查基线、已提交修复、已完成验证与尚待执行的发布步骤。基线 CI 通过不能 证明后续修复也已通过验收。从正文到“限制”保留发布前快照；后续已核实的发布证据追加在 发布后续中。 范围与基线 审查从主题提交 75052f8a3106d13ef313644836a5ad545135f484 开始，此时社区反馈与图片复制修复已经进入 main。范围包括 v1.0.0..main 差异、 #40、 #41、 #42、 #44 与已合并 PR #43 所要求的行为，以及 …

第一阶段随 1.2.0 发布，Ink/Terminal 可显式启用 Paper、Slate 与外观菜单已随 OINK 1.2.0 发布。当前行为与证据由 架构契约、 已接受决策和 验收记录管理。 随后的 Ink/Terminal 实验提供真实可切换输出；本提案继续承载两者的设计定稿。10 月 4 日注入样式生成的截图仍是研究原型， 与 10 月 5 日真实主题输出截图分开看待。 状态与影响面 字段 值 状态 第一阶段随 1.2.0 发布；Ink/Terminal 显式启用 负责人 OINK 维 …

决策 schema/ 下的两份 JSON Schema 由 bin/generate-config-schema.py 从主题的 hugo.yaml 与模板读取点投影生成，手工编辑无法通过 CI。Schema 是既有权威的 只读投影，不是第三个配置权威。 背景 主题已有两个配置权威：hugo.yaml 在注释旁声明每个默认值；check-params.py 的读取点扫描知道模板实际消费的每一个键。编辑器对两者一无所知，作者只能凭记忆 敲 params.ui.* 和 front matter。 …

OINK 1.2.0 契约 本契约描述 v1.2.0 的正式行为。唯一的中英文契约源文件位于 content/docs/design/。 共享规则见架构契约与 组件契约；迁移行为属于 迁移边界。 外壳与数据 任何普通页面都可以声明 layout: landing。它渲染顶部导航栏、全宽画布与页脚， 不显示 docs 侧栏或 TOC 导轨。首页继续把 data/home/<lang>.yaml 作为兼容的创作 路径，并通过同一个渲染器处理。 非首页依次从内联 front …

原始调研快照 本文记录 2026-09-19 的源码审查、GitHub 实时状态、本地构建与定向浏览器观察。 初始调研完成时，这些建议尚未成为已接受契约，功能也尚未实现；当时没有合并 PR、 发布版本或向贡献者发送回复。文末的实施补记单独记录了随后完成的变更。 以下保留最初的调研快照。随后维护者决定先合并 PR #43，再直接在 main 实施其余修复； 最新进展见同日实施与验收补记。 判断结论 这些反馈都有值得处理的内容，但不能全部归为同一种缺陷。应优先修复隐藏导航仍能获得焦点的问题。 PR …

已实现需求记录 有限 R1–R8 受支持本地实现与 A18 运行时/归档范围对验收增补记录的历史源码和 二进制通过；当前精简 CLI 需要独立验证。本记录保留原 URL 与锚点，保留历史排期文本和失败试验；稳定行为归属 CLI 契约与指南，历史证据归属 2026-10-04 增补。 记录退出活动导航，未启动 E1–E4 是独立非活动范围。渲染导航/URL 验证需要这些准确晋升字节的独立收据。 先完成文档维护，再建立本地可视化工作台。产品应当帮助维护者检查修改、理解影响、 审阅安全变更，并发布刚 …

OINK 1.2.0 契约 本契约描述 v1.2.0 的正式行为。唯一的中英文契约源文件位于 content/docs/design/。 权威来源与导航 关注点 权威来源 全局导航 Hugo menus.main Docs / Book 侧栏与翻页 内容树或 data/docs_nav.json 根栏目切换器 解析后的顶层内容根 内容发现 各语言的本地搜索索引 页面与命令面板操作 共享操作注册表 任何功能都不能引入另一套菜单或页面树。菜单只允许一层子项交互；更深层级会警告， 并平铺到带链接的分 …

决策 Goldmark 能保留目标语义时，优先提供原生 Markdown 形态。只有原生形态无法表达真实能力时， 才保留 shortcode。新增内容场景时延长既有外壳和数据模型，不另建一套并行渲染系统。 背景 OINK 同时服务短手册、大型参考文档、发布归档、落地页和书籍。对十一个消费站点、五千多篇 Markdown 的盘点呈现了两个极端：有些页面几乎不用主题语法，有些页面则由大量嵌套 shortcode 与站点自有 layout 拼成。 只为后一类优化的组件 API 会变成私有 DSL；只 …

首期为本地候选，后续路线仍是草案 用户于 2026-09-29 授权独立 Go 仓库 pgsty/oink-cli 及首期开发。六个命令已有本地 0.1.0-dev 实现，最终本地验收单独记录。当前行为归属 CLI 决策与结果契约及使用指南。这不代表 CLI 已公开发布或已有独立用户采用。主题 1.2、工具能力描述、Docsy 迁移、版本生命周期、OpenAPI、MCP 与 Studio 保持提案状态。 记录 内容 状态 仓库选择与首期范围已接受；本地候选已实现并验证；后续路线保持草案 负责人 …

审查快照，不是新契约 本文记录 2026-08-26 对 github.com/pgsty/oink 主线与本站集成面的审查证据。 它不会改变既有 API，也不表示文中建议已经实现。当前行为仍以 Design 契约、实现与 owning checker 为准。 其中一部分已被 OINK 0.7.1 取代。 F01–F06 这些代码问题已在该版本修复，见 0.7.1 发布说明。下面的发现应当读作促成修复的证据，而不是主题当前的状态。 审查结论 OINK 的主干质量明显高于一般 Hugo 主题：默 …

OINK 1.2.0 契约 本契约描述 v1.2.0 的正式行为。唯一的中英文契约源文件位于 content/docs/design/。 教程与完整示例位于面向读者的组件专栏。本页定义这些 指南所依赖的 API 与行为。 创作模型 一个区块加属性便能表达组件时，使用普通 Markdown；需要复合正文或 Markdown 无法携带的事实时，使用 shortcode。OINK 没有并行的组件注册表。原生形态要求： markup: goldmark: renderer: { unsafe: …

带日期的语料快照 这些计数描述 2026 年 8 月被检查的仓库。它们是设计选择的证据，不是实时产品指标或兼容承诺。 语料 创作语料盘点扫描了十一个 OINK 消费站点的 content/ 树：共 5,325 个 Markdown 文件，其中 5,293 个带 YAML front matter。样本同时包含单语言英文与中文参考站、双语产品站、发布归档、 自定义落地页，以及独立的 Book 消费站。 盘点刻意测量源码 Markdown，而不是生成后的 HTML。统计项包括 shortcode …

决策 OINK 保留 Hugo 原生键与仍有价值的 Docsy 兼容键，把主题呈现和行为放在 params.ui.* 下，并用同名的顶层 front matter 键提供页面覆盖。它不增加 params.oink.* 配置树，也不建立一套遮蔽 Hugo 配置模型的注册表。 背景 OINK 继承了成熟的配置面，又增加了阅读外壳、内容输出和本地交互。早期设计曾尝试把所有 主题自有键迁入一个新命名空间，并在每页一次性解析完整配置字典。这样会在 Hugo 原生键旁边 再造一种语言，使 section …

部分已实现 M1（共享 media-result 契约）与 M2（Landing 资源元数据）已在主题 main 分支实现； M3 已决议为方案 2：图片处理只属于原生 Markdown 图片形态，完整 fig 源形态保持 容器语义，其参数表刻意不含 command/options。M4（兼容退役）在完成消费方盘点 之前保持开放。以下各节为原始设计记录。 当前基线 正文图片钩子、编号 fig、卡片与 gallery 统一通过 content/image-resolve.html 解析页面资源、 …

仅为本地证据 本记录针对同级主题 checkout 的真实输出，没有注入原型样式；不代表发布版本、 升级消费站点或验收线上站点。 输入 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 …

本地候选版本证据 本次审查覆盖 10 月 5 日工作树，包含尚未提交的修改。 它不代表某个不可变发布提交或已发布 1.2.0 模块的验收结果。 公开主题标签与文档站消费版本仍为 v1.1.0。 范围与输入 主题起点为 a1979a4，文档站起点为 ed2d0e3。受检工作树还包括 CJK 关键词 摘要、字面百分号大纲与仓库源文件路径修复，站点既有的英文编辑修改，以及下列 清理。独立可选 CLI 不属于本次主题发布范围。没有打标签、推送、升级消费站或部署。 多数检查使用 macOS ARM64 …

本地实验，不代表发布 Ink 与 Terminal 现已编入真实主题样式表，使用现有外观控件，不是截图注入样式。 两者仍为需要显式开启的实验，等待视觉定稿。 输入与方法 本实验基于 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。 这不是兼容下限 …

G1 已实现，G2/G3 仍是草案 2026-08-27 决议 G1 的全部待决问题并接受 G1（静态反向链接）。它已在主题 main 分支实现，随 OINK 0.8.0 发布。局部与全站图谱（G2/G3）保持草案状态，等待 G1 的 真实使用证据；它们的名称和配置在被接受之前不是公开 API。 前提 反向导航与页面连接视图是链接图的属性，不是 [[wikilink]] 拼写的属性。Hugo 已经接受普通 Markdown 链接和 ref / relref。OINK 可以从作者已经在写的内容中 …

决策 OINK 不调用 Hugo 的 errorf。作者或站点输入无效时，主题发出警告，并使用文档中 明确的安全回退，或者省略无效片段。版本发布与部署构建使用 --panicOnWarning， 因此同一条警告在发布门禁中仍会导致硬失败。 背景 Hugo 把整座站点作为一次事务构建。编辑一页时触发的 errorf 会让该次重建中的所有 URL 都返回错误，包括无关页面和首页。服务器进程仍然存在，修正输入后也会自动恢复，但多人共享 的预览在此期间完全不可用。 警告的开发成本不同。出错的值可以回退 …

OINK 1.2.0 契约 本契约描述 v1.2.0 的正式行为。唯一的中英文契约源文件位于 content/docs/design/。 仓库与装配 仓库根目录是一个完整的 Hugo 模块与主题，不是站点，也不是 npm workspace。 Hugo Extended 负责编译 SCSS 与模板。浏览器运行时与第三方资源都已提交到仓库， 因此普通构建不会访问网络。公开的双语文档、示例与浏览器测试位于同级的 oink.pgsty.com 仓库；主题仓库只在 tests/site/ 中保留范围明 …

已验证快照 这些探针在 Hugo Extended 0.160.1 与 0.164.0 上得到字节一致的相关输出。它们解释 OINK 的原生组件形态；当前组件契约仍是权威。 方法 探针使用一个不带 OINK 模板的最小 Hugo 站点。渲染钩子把上下文字段与 .Attributes 输出为 可见标记。站点开启 Goldmark 块属性、行内与块级数学 passthrough 分隔符，以及为检查原始 HTML 而刻意启用的 unsafe 渲染，并设置 …