设计决策
解释 OINK 现行公开契约与实现为何采用当前形态的已接受选择。
已接受的理由
决策记录解释 OINK 为什么在多个兼容方案中选择了当前设计。上方五份契约仍是 现行行为的规范描述;实现与归属检查器仍是可执行事实。
OINK 过去把评审、PRD 与执行记录放在本地 plan/ 目录中。这样既不便发现有价值的
推理,也容易让已经放弃的设计看起来仍有权威。已经接受的理由现在统一进入这座双语、
版本化的文档站,与它所支撑的契约放在一起。
决策地图
| 决策 | 解决的问题 |
|---|---|
| 警告与安全回退 | 为什么普通预览能容忍错误输入,而发布仍保持严格 |
| 配置模型 | 配置放在哪里、页面如何覆盖,以及 OINK 为什么不另造配置命名空间 |
| Markdown 优先创作 | 为什么优先使用原生 Markdown,以及 Docs、Blog、Book、Landing 如何延长共享系统 |
| 生成式配置 Schema | 为什么编辑器 Schema 是生成的投影,以及漂移门禁如何阻止第三个配置权威出现 |
| 可选 CLI 与结果契约 | 本地 CLI 候选的独立 Go 可执行文件、版本化诊断、覆盖范围与显式写入边界 |
| 视觉预设 | Paper 默认、Slate 兼容、可选外观菜单、独立明暗状态与字体边界 |
| Expo 相册 | 资源页面包、可选元数据、共享外观与相册查看 |
| 博客画廊 | 文章封面、共享 Expo 排布、独立偏好与可读的文字说明 |
| 表格阅读 | 显式 .expand、独立 .wide,以及可还原原表格的角落直接展开入口 |
| 译文对照 | 一个开关、真实同源译文、按需加载的双栏阅读器和基于标题的同步 |
| 组件精修 | 共用样式、分隔式卡片、紧凑步骤与命令条 | | 统一图表阅读 | Mermaid 与本地 PlantUML 共用查看器、源码导出与按需加载 | | 本地搜索改进 | 混合查询、真实小节锚点、部分匹配与栏目范围 |
记录格式
一份已接受决策应记录背景、选择、后果,以及证明该选择仍然成立的证据。它不重复参数 参考或教程。每份决策都要链接到归属契约与验证面,中英文页面必须同步修改。
决策发生变化时,应在同一次交付中更新实现、检查器、受影响契约与决策记录。旧答案留在 Git 历史和版本变更记录中,不在导航树里并列保留两套“现行”答案。