跳转到主要内容

OINK CLI 功能与后续方向

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

本页保留 2026-09-30 的命令清单与证据。六个命令、平台状态及 CI 建议描述的是 当时情况。当前维护行为归CLI 契约与 使用指南所有； 维护记录 保留其指定源码与二进制的历史验收。 本地验收不代表公开 CLI 发布或部署。

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

本文介绍现有功能和后续方向。完整安装步骤见使用 OINK CLI， 已执行的测试见首期验收记录。

当前状态

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

工具的定位

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

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

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

已实现的六个命令

命令 解决的问题 当前行为与边界
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 输出和 缓存；只读诊断与升级预览保留站点源码。

检查以实际产物为准

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 则会 指出公开来源的字节验证尚未完成。

升级前先验证候选

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

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

自动化与离线能力

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

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

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

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

一条完整的使用路径

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

GOWORK=off GOTOOLCHAIN=local go mod download github.com/pgsty/[email protected]
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 和内容，结束预览后执行：

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

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

已验证范围与当前限制

首期验收记录覆盖 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，仍有明确的支持边界，详见 输入范围表。不支持的必需输入不会得到完整检查通过的结论。

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

下一步优先完善的功能

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

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

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

随后可以扩展的产品能力

以下方向已在CLI 路线图讨论，仍是 后续提案。它们应继续遵守“生成普通站点源码，渲染不依赖 CLI”的边界。

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

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

进一步阅读

最后修改 2026-10-05 · test: align command palette assertions with the v1.2.0 release (edeb45b)