跳转到主要内容

2026-10-03 CLI 维护验收

R1–R8/A18 本地实施的带日期源码与二进制证据,保留初始审计、失败试验与最终受支持验收范围。
历史源码与二进制证据

本记录保留 2026-10-03 至 2026-10-04 的 R1–R8/A18 本地验收证据,含初始审计、 中间试验及三个支持目标的运行时与归档验证。2026-10-04 的 CLI 精简与 Cobra/文本/JSON/YAML 界面以当前契约和CLI 简介为准。这些结果仅对应当时记录的源码与二进制,后续精简 CLI 的改动需独立验证。

范围与证据规则

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

各阶段按依赖顺序验收。每阶段都需要完整可用的流程、对应测试、相关真实 Hugo 集成、已知限制、可审阅 diff,以及已验收的中英文契约和指南更新。 新公开行为在实现和验收证据齐备后移入对应契约。

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

已检查输入与工具

2026-10-03 的初始审计读取了两个仓库的指令、文档站 README 和翻译规则、 维护 PRD 的中英文文件、原提案、当前 CLI 契约,以及已有 Go 包和测试名称。 初始审计阶段仅执行版本与 Git 检查命令。

输入 初始观察状态
主机与 Go darwin/arm64;go version go1.27.1 darwin/arm64
Hugo hugo v0.166.0+extended+withdeploy darwin/arm64;Homebrew 构建日期为 2026-09-09
Node 与 npm v26.9.0;11.19.1;属于贡献者/文档工具,不是 CLI 下游运行依赖
Git 2.54.0 (Apple Git-157)
CLI 源码 e623d93d589c49e5c58b8fae1bd5db720fc904cb,main;初始 tracked/untracked 状态干净;生成的 bin/、dist/、tmp/ 已忽略
文档源码 907d873eb05cfc2e194f492462dfa94849e93474,main;初始 porcelain 状态有 184 项,含已有提案、契约、指南及无关内容修改
内嵌 Starter 137843b25bacd76ddd1f7ce71330bf2e3155b954;internal/starter 已记录来源和许可证
声明的主题基线 Starter 与三个选定站点声明 github.com/pgsty/oink v1.1.0;有效解析字节在每次验收中确认

2026-09-29 验收记录 包含首个候选的历史检查,可提供复现输入。

阶段需求与实现证据

阶段 所需完整流程与不变量 初始实现证据 仍需验收证据
R1 由 Hugo 提供共享页面身份、语言、发布状态、来源、实际输出、翻译和观察到的引用;oink.yaml 只管理检查政策;链接/翻译/风格共享分析;严重程度和排除项不能隐藏必需未完成;位置可信 部分已有:internal/site 隔离快照与 Page.OutputFormats 探针、internal/outputcheck、internal/report;初始审计时尚无共享翻译/页面事实或政策命令 真实 Hugo 路由、别名、挂载、未列出/生成来源场景与语言关系;公共分类检查/政策用例;必需未知、工具、构建、输入失败仍为 2;仅在可靠时报告源码位置
R2 三种语言组织;严格/手册和本地化政策;重复、缺失和草稿状态;显式版本化审阅记录绑定源语言及源/译文哈希;有语法边界的原生规则;有效主题覆盖;可见版本化基线;审阅修复先验证再窄范围应用 未完成:初始审计时无翻译/审阅/原生规则/基线公共命令;可复用产物引用检查 A04–A07;经审阅的有效/无效内容语料;不用 mtime 推断审阅;处理禁用/本地化语言;已确认问题仍可见;必需检查缺失仍为未完成;修复保留文件
R3 保留默认透明 build/dev;build --check 在一次严格 Hugo 输出上检查和生成 manifest,只导出到新建/空目标;摘要/来源 manifest 和可选最小公开身份;两种本地 CI 模板上传同一树;发布诊断;显式联网公网验证 部分已有:直接封装、严格隔离检查和有许可证的工作流输入;初始审计时缺少受管理构建/导出、摘要验证、CI 计划和公网 verify A08–A10;恰好一次 Hugo 构建;拒绝字节漂移;revision/dirty/input/theme/tool/settings/coverage 来源不含秘密或本机路径;工作流定制/冲突/来源及不可变源码输入;示例地址政策;回退/语言/资源/canonical/超时/认证/限流 HTTP 夹具
R4 new、片段和编辑器配置创建普通输入且不覆盖;docs/blog/book/project 配置组合复用一个有许可证的 Starter;升级提供可读 diff 及新旧路由、别名、启用输出;不支持迁移给出人工操作;保留原有保护 部分已有:固定归档语言配置、绑定哈希的单站模块升级、候选验证、备份,以及脏文件/workspace/replacement/vendor 保护 A11–A12;所有新增配置/语言组合可用普通 Hugo 构建;保留未知编辑器设置;升级路由/能力回归和可读 diff;保留来源与许可证
R5 inspect、impact --since、受限 context、默认预览 move;共享计划包含文件、diff、基线哈希、翻译、附件、输出/路由变化和别名建议;候选验证与过期/并发安全恢复;含糊引用要求审阅 部分已有:模块专用升级计划/应用基础;初始审计时无共享内容计划或 inspect/impact/context/move 流程 A13–A15;删除 B 包含未改入站 A;翻译/附件/派生产物影响;不确定/全局变化强制全量检查;不执行内容;候选/过期/写入失败保护及含糊链接处理
R6 显式版本化站点注册复用单站引擎;逐站与汇总完成状态;只写选定站点;已配置且预先供应的 markdownlint/Vale/lychee 适配器规范发现项并声明语法/网络覆盖 未完成:初始审计时无 workspace/adapter 公共命令 A07/A15/A18;直接/逐站一致;无同级发现、隐式安装或默认格式化写入;必需工具缺失为 2,可选遗漏可见,外网不确定性明确区分
R7 只读 loopback Studio,提供概览、问题、翻译比较、页面关系和发布视图;筛选、已知来源、真实 Hugo 预览、比较与复制操作;CLI 一致;预构建资源;显式 allowlist、独立预览 origin、Host/Origin/session 保护 未完成:初始审计时无 Studio 服务或资源 A16;真实浏览器/键盘/读屏/移动端/深浅色/长列表流程;使用相同 CLI 结果;拒绝未授权 host/origin/session 和预览到管理接口请求;消费者运行不需要 Node
R8 Markdown/文本和 front matter 表单、选定组件与不覆盖附件复用计划;授权允许范围内写入须有可见 diff、哈希和候选验证;无修改字节及未知字段/注释/顺序/编码/空白保留;表单不支持的语法保留文本模式 未完成:编辑在只读 R7 验收后实施;初始审计时无编辑 API A17/A14;无修改字节一致、YAML 字段定点更新与文本回退;外部编辑器过期保存、路径穿越/符号链接逃逸及预览请求安全失败;附件不覆盖;静态发布无管理 API

证据分页

各阶段的验收记录保存在两个配套页面中。为了让每个页面都能被读者和代理工具完整读取, 它们于 2026-11-06 原样迁移至此:

  • R1–R5 证据:R1 至 R3 的本地验证、 编写与升级验收(R4),以及实现与文档验收(R5)。
  • R6–R8 与 A18 证据:工作区与适配器验收 (R6)、只读 Studio 候选(R7)、已接受的审阅编辑(R8),以及 2026-10-04 的运行时 完成补充(A18)。

验收用例台账

下表结合初始审计、已接受 R1–R7 证据与已验证 R8 候选门禁。

用例 所需结果 代码或检查证据 状态与缺少的决定性证据
A01 单个 oink.result/v1 JSON;stderr 日志;政策为 1,必需未完成为 2 协议/公共 R1–R8 命令、冻结归属测试及精确二进制 CLI/API 报告;未改变结果 Schema;当前八项归属门禁/Linux 验收与未变运行时复用的此前语料见 #a18 受支持当前命令范围通过
A02 Hugo 解析 slug/url/permalinks/aliases、挂载、未列出页面和语言根 真实 PageFacts/manifest/自定义挂载/translationKey 夹具;普通产物保留;最终消费站事实 R1 范围通过
A03 确定本地缺失路由失败;真实分类 origin/path 外引用和声明外部范围 真实产物引用夹具、子路径/政策回归及最终真实站点 所需 A03 范围通过;外链可访问性保持未检查
A04 文件名、目录和 translationKey;重复/缺失/草稿;严格/本地化政策 R2 翻译引擎、真实 Hugo/公共命令、最终报告和数值补充 所需 R2 范围通过
A05 无记录为未知;源/译文哈希变化可见;不依赖 mtime R2 哈希/status/diff、公共预览/应用和最终报告 所需 R2 范围通过
A06 真实围栏、行内代码、短代码、HTML、属性、未知字段和受保护文本边界 R2 真实语法/来源夹具、经审阅语料和最终报告 所需 R2 范围通过;目录及不支持源码限制仍明确
A07 已确认问题可见;新问题按政策阻断;必需工具缺失不能通过 R2 基线/公共计划;R6 假/实际协议、缺失/不安全/离线/网络不确定及必需优先级夹具通过 受支持范围通过;必需不可用/不确定工具保持 2
A08 检查后字节变化使 manifest 无效;服务商上传已验证树而不再次构建 R3 manifest/导出/篡改/公共单构建测试,最终普通 Hugo 对比及服务商演练 所需 R3 本地范围通过
A09 两种 CI 模板;保留定制工作流;权限/变量/来源和过期计划保护 R3 离线生成/bootstrap、公共预览/应用/过期输入、定制工作流补充及本地演练 所需 R3 本地范围通过;定制工作流未知且不变
A10 拒绝 HTTP 200 回退、错误语言/构建、缺失资源/canonical 差异;超时/认证/限流为未完成 R3 显式联网本地 HTTP 和公共结果夹具,含必需身份缺失 所需 R3 夹具范围通过
A11 所有声明配置/语言;目标保护;普通 Hugo;保留未知编辑器设置 R4 24 次普通 Hugo/公共配置、完整 Starter 创作/编辑器流程、片段、实际挂载、来源身份、JSONC 保护与外部 Schema 重新证明 所需受支持 R4 本地实现/语料范围通过;已声明不支持编辑器输入仍明确
A12 可读 diff 和路由比较;脏文件/workspace/replacement/vendor;恢复/并发 冻结真实 Hugo 七个固定合成模块用例、公共升级、源码/外部保护、实际 alias 改指向与受保护部分回滚 所需有界 R4 本地实现/语料范围通过;未知重定向/多主机仍未完成
A13 删除 B 找到未改入站 A;翻译/附件/派生产物;全局全量范围 R5 已提交 Git/实际 Hugo 删除、alias 入站、全局/不确定输入和不可用基线夹具;精确二进制消费者报告 所需受支持 R5 范围通过;不可用或未证明历史输入明确为 2
A14 应用前候选;过期/哈希/写入失败保留后续编辑;含糊引用不变 R2/R4 共享保护、R5 完整模式/清单移动及 R8 重新生成意图/新输入候选验证、保护写入器及过期/后续编辑/附件测试;当前八项归属门禁/Linux 验收与未变运行时复用的此前语料见 #a18 受支持 R5 CLI 与 R8 CLI/Studio 编辑范围通过;含糊或必需不可用输入仍阻断
A15 工作区/直接一致;只写选定站;上下文受限且有路径/版本/原因;不执行内容 R5 有界捕获源码/context 夹具与四站查询;R6 登记/直接/汇总一致及显式名称保存应用、其他站保留 受支持 context/工作区范围通过;无隐式批量写入
A16 五个实用 CLI 一致视图;键盘/移动端/深浅色;来源/预览隔离 已接受 R7 证据保留;历史源码绑定 R8 只读 14 项 axe/截图及 Editor 12 项 axe/截图,UI 字节未变;当前后端门禁、ARM 与语料独立验证、原生/API 一致、预览隔离、四消费者及规范渲染通过;当前八项归属门禁/Linux 验收与未变运行时复用的此前语料见 #a18 受支持本地视图通过;必需局部预览未完成/原生发现仍可见
A17 无修改字节;YAML 未知/注释/顺序保留;拒绝过期保存和附件冲突 修正冻结核心/公共/保护写入器 race、实际 Hugo/工具、源码绑定 Editor/只读浏览器、精确二进制四消费者提议一致性/保护及受保护规范源码/渲染在 #r8 通过;当前八项归属门禁/Linux 验收与未变运行时复用的此前语料见 #a18 受支持本地编辑范围通过;必需局部预览/原生发现仍阻断 Apply;最终 A18 独立
A18 实测声明 macOS/Linux 环境、子进程信号、已供应离线运行与明确不支持输入 当前冻结/源码与五归档重复复现;Darwin arm64、原生 Linux arm64、模拟 Linux amd64 非 root ext4/完整离线单元-vet/选定 Hugo/原生归档/信号 smoke 在 #a18 通过 当前声明运行时/归档范围通过;可选 guest 前置条件保持明确跳过;Darwin amd64 实验/未验证,Windows 不在范围

候选站点与源码保护

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

同级 checkout 布局中的输入 初始观察身份与用途 本轮候选验收
oink-starter / 生成 Starter 源码 137843b,初始状态两项;有许可证的固定归档,语言/配置/根路径/子路径试验 R1 双语 init/check 与 R4 全配置普通/公共创作流程通过;归档/许可证不变
oink.pgsty.com 源码 907d873 和已有修改;双语文档/回归与显式本地主题试验 最终 R1 检查与源码保护通过;本地主题证据仍与公开固定版本分开
pig.pgsty.com 源码 75050c0,初始状态五项;Docs/Blog 根路由重写、不渲染侧栏条目;声明 v1.1.0 最终 R1 检查与源码保护通过
repo.pgsty.com 未产生提交的 main,无 HEAD revision;已物化的未跟踪源码、生成目录和声明的 v1.1.0 最终 R1 检查与源码保护通过;revision 仍未知

每次运行记录有效模块来源和版本、参数/网络政策、退出码/结果/覆盖、原始证据位置和保护结果。 前后清单必须包含所有 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 个源码标题。

构建相关站点后,完成产物文档验收:

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

make build 验证声明的公开固定版本;make check 选用同级主题执行完整非浏览器回归套件。 Studio 使用自身的真实浏览器和无障碍验收。

交付状态与剩余限制

状态 当前完成证据,历史保留于上文
本地实现 有限 R1–R8 受支持实现本地完成,包含只读 Studio 与显式受审阅编辑;当前 A18 运行时/归档通过。规范生命周期渲染独立绑定这些准确字节
本地验证 历史 R1–R8 归属/浏览器/语料/渲染记录保留;2026-10-04 当前后端修正和八项当前归属门禁、三个实际目标运行时/归档,以及运行时未变的此前四消费者保护/一致性证据复用在 #a18 通过。必需仓库发现/局部预览保持可见。渲染导航/URL 检查具有独立准确字节收据边界
提交 已识别 CLI 基线提交
归档与运行环境验收 当前修正源码:Darwin arm64、原生 Linux arm64 与 QEMU TCG 模拟 Linux amd64 的安装归档/离线/信号/文件系统流程通过,两个新构建复现全部五归档;Darwin amd64 实际执行失败,保持实验/未验证
公开分发与消费站采用 本轮本地验证未执行
部署与公网内容验证 已通过本地 HTTP 夹具验证

有限 R1–R8 实现与必需当前 A01–A18 运行时/归档范围已有本地验收证据。 已知仓库发现及必需预览未完成保持为可见诊断输出。

表格阅读