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 作为 独立提案。本地证据记录没有接受任何后续能力，也没有将它们计为完成。