# OINK CLI 功能与后续方向

> 2026-09-30 的六命令 CLI 快照、安全与自动化能力，以及当时提出的后续研发方向。

---

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

---

> [!NOTE] 首期历史快照
> 本页保留 2026-09-30 的命令清单与证据。六个命令、平台状态及 CI 建议描述的是
> 当时情况。当前维护行为归[CLI 契约](/zh/docs/design/decisions/cli/)与
> [使用指南](/zh/docs/start/cli/)所有；
> [维护记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/)
> 保留其指定源码与二进制的历史验收。
> 本地验收不代表公开 CLI 发布或部署。

`oink` 是面向 OINK 站点维护者的命令行工具，把创建站点、检查环境、验证产物、
本地预览和主题升级放在同一个入口中。当前六个命令已经形成可用的本地工作流程。
接下来最有价值的工作，是让更多用户能顺利安装、准确定位问题并重复完成维护；
迁移、文档版本管理和 API 参考生成可以在此基础上逐项推进。

本文介绍现有功能和后续方向。完整安装步骤见[使用 OINK CLI](/zh/docs/start/cli/)，
已执行的测试见[首期验收记录](/zh/docs/design/research/2026-09-29-cli-acceptance/)。

> [!NOTE] 当前状态
> 截至 2026-09-30，本文对应本地 `0.1.0-dev`、提交 `e623d93`。代码、测试、
> 安装流程和可复现归档已经准备并验证；公开 CLI 发布和部署尚未完成。
> 下文的后续功能是建议或既有提案，不是可立即使用的命令，也不构成排期承诺。

## 工具的定位 {#purpose}

OINK 主题负责页面呈现、导航、搜索、内容组件和各类输出，Hugo 负责配置加载和渲染。
CLI 负责把这些输入与结果串成可检查、可重复的维护流程：哪里配置不对、实际用了哪份
主题、链接是否失效、升级会修改什么，都应有可查看的证据。

CLI 是独立的 Go 可执行文件，调用外部 Hugo，不依赖 Python、Node.js、账户或后台服务。
初始化后的站点保留普通 Hugo 配置与内容；依赖齐备后，即使不安装 CLI，也能直接用
Hugo 构建。主题和 CLI 的版本号承担不同职责。

它适合三类使用者：新站维护者可以更快建立基线；既有站点维护者可以诊断、检查和
审阅升级；CI 或自动化程序可以读取稳定的 JSON 结果与退出码。

## 已实现的六个命令 {#commands}

| 命令 | 解决的问题 | 当前行为与边界 |
| --- | --- | --- |
| `oink doctor` | 环境能否工作，站点实际用了什么 | 检查 Hugo Extended 与版本、必要的 Go/Git、生效配置、主题固定版本与实际来源，以及 workspace、replacement、vendor、语言和输出。只读诊断，不构建站点。 |
| `oink check` | 构建后是否存在可检测的问题 | 复制输入并隔离输出和缓存，用 `--panicOnWarning` 构建，再检查实际产物中的站内链接、锚点、资源及受支持的机器输出。 |
| `oink init <目录>` | 如何得到可用且可复现的起点 | 从内嵌、保留许可证与来源记录的固定 Starter 快照生成站点。支持 `en`、`en,zh`、`all`（英中法）；候选验证通过后才创建文件，拒绝覆盖非空目录。 |
| `oink upgrade --to <标签>` | 升级是否可行，会改动什么 | 只处理选定的一个站点，先验证候选，再输出计划。默认不写入；显式 `--write` 才应用选定的模块文件变更。 |
| `oink dev` | 如何启动日常本地预览 | 透明调用 `hugo server`，`--` 后的参数传给 Hugo，并转发进程信号。 |
| `oink build` | 如何执行严格的生产构建 | 透明调用 Hugo，默认选择 `production`，加上 `--panicOnWarning`。不会额外执行 `check` 的引用检查。 |

`doctor` 和 `check` 的区别在于是否真正构建并检查产物。`build` 生成站点通常使用的
发布产物，`check` 则在隔离副本中验收。`dev`、`build` 可以写入正常的 Hugo 输出和
缓存；只读诊断与升级预览保留站点源码。

### 检查以实际产物为准 {#rendered-checks}

`check` 由 Hugo 枚举各语言、各页面实际声明的输出格式和 URL，再核对生成文件。
它支持多语言、根路径与子路径，尊重 URL 编码和外部链接边界，不从 Markdown 文件名
自行推导另一套路由。页面输出覆盖、未进入列表的静态页面，以及有意只生成链接而
不渲染的页面，都按 Hugo 的实际语义处理。

受支持的机器输出包括 NAVJSON v1 导航树、BookManifest v1 书籍清单、离线搜索索引、
LLMS 导览和 LLMSFULL 内容集合。未启用的输出不是错误；某个语言应有但缺失的输出
不能被另一种语言的有效文件掩盖。未知且必需的契约会报告未完成覆盖。

`check --release` 验证面向公开主题版本的构建：关闭 Go 与 Hugo 两套 workspace，
并禁用隔离副本中的 Hugo replacement。冲突的主题 `go.mod replace` 会被报告，
不会被静默删除。实际选中 vendor 时，普通 `check` 可以检查产物；`--release` 则会
指出公开来源的字节验证尚未完成。

### 升级前先验证候选 {#upgrade-safety}

升级计划说明目标版本、待改文件和前后状态。写入可以通过 `--expect-plan` 绑定已审阅
的计划，还会检查目标文件是否在计划后变化。未提交的目标模块文件受到保护，无关依赖
和用户修改保留，写入失败时提供备份与恢复证据。遇到并发编辑，恢复不能为了撤销
自己的操作而覆盖用户的新内容。

目前升级处理 `go.mod` 与 `go.sum`，不自动刷新 `_vendor`，也不改写任意内容或配置。
vendor 刷新需要单独、显式且可审阅的流程。CLI 不执行 commit、push 或部署。

## 自动化与离线能力 {#automation}

所有命令都不等待交互。`--json` 的 stdout 只输出一份 `oink.result/v1`，工具日志写入
stderr。结果包含规则 ID、严重度、已知位置、解释、行动建议、覆盖状态和 Hugo 原始
证据；无法确定源码行号时，不编造位置。

| 退出码 | 含义 | 自动化应如何理解 |
| --- | --- | --- |
| `0` | 必需工作完成，没有阻断项 | 本次请求通过；仍要查看未执行的覆盖项。 |
| `1` | 已完成的检查发现政策问题 | 根据诊断修改输入，再次检查。 |
| `2` | 必需工作未完成 | 排查工具、构建、I/O、缓存或不支持的输入；不能视为检查通过。 |

默认使用离线策略，只有显式 `--network` 才允许本次操作联网。CLI 不下载 Go 工具链、
安装系统包、修改全局配置或增加遥测。模块依赖预备齐全后，受支持的流程可以离线运行；
缓存不足会准确失败。

隔离命令使用可清理的临时缓存，`init --network` 成功不等于后续命令已有持久缓存。
当前只复用已准备的模块下载制品，不复用 Hugo 全局远程资源缓存。构建时必需的远程
内容应预先保存为本地资源，或为该次调用明确启用网络。

## 一条完整的使用路径 {#workflow}

完成[本地安装](/zh/docs/start/cli/#install)，并安装 Starter 所需的 Go、Git 和
Hugo Extended 后，可以按下面的顺序工作。首条命令是显式的联网依赖预备步骤：

```sh
GOWORK=off GOTOOLCHAIN=local go mod download github.com/pgsty/oink@v1.1.0
export GOMODCACHE="$(go env GOMODCACHE)"

oink init my-docs --languages en,zh
oink doctor --site my-docs
oink dev --site my-docs -- --bind 127.0.0.1 --port 1313
```

预览时修改站名、`baseURL` 和内容，结束预览后执行：

```sh
oink check --site my-docs --release --json > check.json 2> check.log
oink build --site my-docs -- --minify
```

升级既有站点时先预览，再按[升级指南](/zh/docs/start/cli/#upgrade)审阅计划并显式写入。
这里的 OINK v1.1.0 是已验收的初始化基线，不表示它始终是最新主题版本。

## 已验证范围与当前限制 {#limits}

首期验收记录覆盖 Go 测试、vet、race、三种 Starter 配置的普通 Hugo 根路径与子路径
构建，以及 OINK 文档站、PIG 站点和软件仓库文档站三个真实消费站。还执行了操作系统
禁止联网条件下的初始化与检查、真实升级写入保护、薄包装进程和归档复现检查。

实际运行平台为 macOS arm64，记录的工具链为 Go 1.27.1、Hugo Extended 0.166.0。
Darwin amd64 与 Linux amd64/arm64 已交叉编译，尚未完成对应平台的运行验收；
Windows 不属于首期支持范围。源码安装可用，公开下载、标签安装和 Homebrew 分发
尚未交付。

当前隔离检查支持已物化、单主机的站点。关联 Git worktree 的 `.git` 指针、已挂载
符号链接、隔离范围之外的挂载、自定义配置目录、动态内容适配器、多主机语言输出，
以及抑制验证探针的 render segment，仍有明确的支持边界，详见
[输入范围表](/zh/docs/start/cli/#check)。不支持的必需输入不会得到完整检查通过的结论。

静态检查不证明浏览器交互、无障碍、外链可访问性、托管重定向、翻译完整性或内容语义
正确。浏览器验收与部署验收应由相应流程负责。

## 下一步优先完善的功能 {#next}

建议先围绕现有六个命令减少使用阻力。下面是基于首期限制的功能建议，尚未实现；
涉及新参数或新契约时，仍应进入[正式提案流程](/zh/docs/design/proposals/)。

| 优先方向 | 可以增加的能力 | 完成时应看到的结果 |
| --- | --- | --- |
| 安装分发与平台支持 | 在目标 macOS/Linux 平台运行完整流程，发布带校验和的正式归档，提供可复现的标签安装或 Homebrew 入口。 | 新用户按公开说明即可安装、初始化、预览并检查，平台声明都有实际运行证据。 |
| 更易行动的诊断 | 按工具、依赖、配置、产物分组；增加规则说明和修复示例；只在有可靠映射时回溯源码位置；评估 CI 注解或 SARIF 导出。 | 用户能定位应修改的输入，CI 保留原始证据，误报能用真实样本复核。 |
| 明确的依赖预备 | 提供显式缓存预备与缺项报告，区分模块和远程资源，记录确切版本、来源及网络需求。 | 第一次联网准备后能够重复离线运行；失败时能说清楚缺什么、如何准备。 |
| 更完整的升级维护 | 评估单独的 vendor 候选刷新与字节比对、可保存的审阅计划及更直接的恢复说明。 | 用户能审阅完整差异；vendor、无关依赖与并发修改继续受到保护。 |
| 更顺手的初始化与创作 | 提供站名、URL 和受支持语言配置的声明式输入；增加少量官方文档、文章和 Book 页面模板。 | 减少手工改占位内容的步骤，生成的仍是普通 Markdown、data 和 Hugo 配置。 |
| 扩大真实项目覆盖 | 优先验证关联 worktree 等常见结构，再按需求处理多主机、外部挂载和动态内容；依据测量优化大站检查耗时。 | 每新增一种支持范围，都有不改源文件、失败可解释的回归证据。 |

不建议同时启动所有方向。先用独立用户的安装和维护记录找出最常见的阻碍，每次选择
一个可验证的改进。新的忽略规则或检查基线不能掩盖 Hugo 构建失败或必需覆盖缺失。

## 随后可以扩展的产品能力 {#later}

以下方向已在[CLI 路线图](/zh/docs/design/proposals/oink-cli-roadmap/)讨论，仍是
后续提案。它们应继续遵守“生成普通站点源码，渲染不依赖 CLI”的边界。

| 能力 | CLI 可以承担什么 | 主要前提与限制 |
| --- | --- | --- |
| 有范围的 Docsy 迁移 | 先生成评估报告，逐项标注兼容、可转换、需人工复核或不支持；随后向新目录转换并核对旧新路由。 | 先支持真实样本中的一套明确配置，不承诺任意 Docsy、MDX 或 React 内容的一键迁移；原始文件和代码示例必须保留。 |
| 文档版本生命周期 | 准备版本快照、维护小型版本清单、检查跨版本页面对应关系和归档状态。 | 主题负责读者界面，CLI 生成可纳入 Git 的配置；缺页不能伪装成等价页，各版本仍可独立构建。 |
| 静态 OpenAPI 参考 | 从本地规范生成操作、参数、请求响应和 Schema 的 Markdown/data，让既有 Hugo 输出链路处理它们。 | 先定义规范子集，保证可重复生成并保护人工修改；远程引用显式准备，请求执行、凭据管理和 SDK 平台另行考虑。 |
| Agent 与编辑器集成 | 在稳定 JSON 结果之上评估编辑器入口或 MCP，让其他工具复用相同诊断和升级计划。 | 先证明现有命令被反复使用；MCP、Studio、图谱和托管服务都需要独立需求与维护资源。 |

推荐顺序是先完成可公开使用的维护工具，再以评估报告启动首条迁移路径。新增内容
能力默认优先文档版本生命周期；若真实 API 用户有更强的重复需求，再将静态 OpenAPI
提前。同一阶段选择一个基础能力，避免同时维护多套尚未经过用户验证的模型。

## 进一步阅读 {#references}

- [使用 OINK CLI](/zh/docs/start/cli/)：构建、安装、参数和完整操作步骤。
- [CLI 与结果契约](/zh/docs/design/decisions/cli/)：稳定行为、JSON、退出码与文件保护。
- [首期验收记录](/zh/docs/design/research/2026-09-29-cli-acceptance/)：实际测试、真实站点及平台边界。
- [CLI 与下一阶段路线](/zh/docs/design/proposals/oink-cli-roadmap/)：后续设计的依据、优先级与接受条件。