OINK CLI 与下一阶段产品路线

核心建议

独立建立 oink-cli 仓库，发布名为 oink 的可执行文件，对外继续使用 OINK 这一个产品品牌。主题负责渲染内容；CLI 帮助用户初始化、诊断、校验、升级，随后逐步支持迁移。文档站继续管理公开指南、双语设计记录和集成验收。

仓库选择与 Go 实现现已接受并在本地建立，公开发布仍是独立动作。首期行为已移入 CLI 契约；带日期的验收记录列出实际执行的检查与剩余限制。本路线图继续承载后续阶段和采用目标。

首发应改善从现有仓库到可靠发布的流程，四项实质性能力是 doctor、check、init、upgrade。dev 和 build 可以提供轻量、透明的 Hugo 快捷入口。根据真实输入仓库的证据，再扩展一条有明确支持范围的 Docsy 迁移路径。版本生命周期和 OpenAPI 生成排在首个可用版本之后，同一时间只推进一个主要内容模型项目。

主题必须允许用户不安装 CLI。对于生成内容，这意味着提交生成后的 Hugo 输入，或者以其它明确方式提供这些输入：移除 CLI 后，普通 Hugo 仍能构建站点。重新生成输入是独立操作。

产品定位与目标用户

建议对外描述为：

OINK 是基于 Hugo 的本地优先文档工具箱，将工程知识发布给读者与 Agent。

安装说明和检索入口仍保留“Hugo 主题”，因为它准确描述用户安装的东西。“知识编译器”适合作为架构方向，但目前不足以证明 OINK 已经建立了新的产品类别。新的叙事不应遮蔽现有 Markdown/Hugo 路径。

优先服务使用 Git 的开源基础设施、开发者工具和多语言技术文档维护者。他们眼前的任务是让站点运行起来、定位故障、安全升级，以及在迁移中保留 URL 和内容含义。现有维护站点提供回归证据，独立团队提供采用证据，两者用途不同。

首阶段明确不做可视化 CMS、托管账户、部署控制台、软件包市场、LLM 运行时、语义搜索服务或新渲染引擎。书籍、博客和落地页继续得到支持，但不由这些场景的功能清单驱动本轮路线图。

证据与对研究建议的调整

本提案参考用户提供的战略报告，并对照本地实现、双语 Design 专栏、Starter 和当前官方文档核实。不把报告中的 Star 数、工时估算、商业价格或市场判断视为已验证需求。

原报告正确强调了采用成本和可选工具层。以下四项调整能让它成为可执行计划：

1. 将安全升级与初始化、诊断并列。现有用户已经有直接、可测试的维护需求。
2. 区分维护者回归检查器与消费站检查。面向固定夹具的脚本不会自动成为通用站点校验器。
3. 按明确的输入配置范围承诺迁移，不承诺完整 Docsy 或任意 MDX 转换。
4. 将同时开展版本化、OpenAPI、图谱和平台建设，改成逐阶段决策。功能列表与工时相加不是人员到位的交付计划。

竞品能够证明流程方向已有先例，不能证明 OINK 自身的需求。Mintlify CLI 提供预览、校验和链接检查；Nimbus 将脚手架与 Agent 可读产物结合，目前仍为 pre-1.0；Docusaurus 明确定义版本快照，也提醒其维护与构建成本。如果照搬 Nimbus 将整套界面源码交给用户的模式，会把升级维护工作转给 OINK 消费者。可以对小型内容模板借鉴该方式，主题本身仍保留可升级模块。

为什么独立建仓

这是发布与职责划分，不是说单仓在技术上不可行。嵌套模块能够隔离依赖；分仓也确实会带来协作成本：一次渲染行为变化可能需要两个 PR、配套契约与兼容性测试。OINK 已经采用主题、文档站和 Starter 分仓，只要公共边界足够小，这个成本可以接受。

主题与 CLI 不应强制使用相同版本号。建议 CLI 0.1.x 同时支持经过测试的主题 1.1.0 基线和下一受支持版本，按能力声明兼容范围。遇到不支持的功能应明确报告，不能拿最新主题的全部 Schema 去判断所有旧站点。

现在不另建 linter、迁移引擎、OpenAPI 生成器或共享 SDK 仓库，先作为 CLI 内部包。二进制可以用 Go 编写，同时不引用 Hugo 内部 Go 包，也不让主题模块依赖 CLI。

职责划分

                         可选的 oink CLI
                  init / doctor / check / upgrade
                      后续 migrate / generate
                               |
                               v
                 用户拥有的 Markdown + Hugo 配置 + data
                               |
                     Hugo Extended + OINK 主题
                               |
               HTML / Print / Markdown / 搜索 / 索引
                               |
                     读者 / Agent / 可选适配器

CLI 读取 Hugo 的生效配置、实际解析到的主题所发布的契约文件，以及构建产物。不应通过文件名猜测最终页面树，也不维护第二套导航解析器。Hugo config 已能输出生效配置；模块检查还需覆盖 replacement、workspace 与 vendoring。

下一期主题：建议 OINK 1.2

本节保持草案。本地 CLI 候选使用已发布的 OINK v1.1.0 基线；首期 CLI 决策既未接受主题 1.2 发布或新的工具能力描述，也不以它们作为前提。

本版本以降低采用成本为目标：站点能向工具准确说明配置与输出能力，升级不要求引入新的创作模型。范围应足够小，能够独立于后续大路线发布。

能力描述属于发布元数据，不是新的配置权威。配置 Schema 继续从现有权威生成，可选形态校验仍归对应解析器与检查器。不要违反现有诊断决策，另建通用改名键注册表。迁移转换应属于明确的 CLI 配置范围，而不是模板中的永久兼容路径。

1.2 不要求增加新的视觉组件族。正确性、无障碍和已经发现的回归仍可驱动修改。现有媒体工作保留其独立验收范围，本路线图不把所有草案完成都变成发布条件。

CLI 首发：建议 0.1

下列命令已在本地 0.1.0-dev 候选中实现。当前参数、结果语义与限制由 CLI 契约及使用指南定义；公开分发与最终验收仍为独立状态。

check 是统一质量入口。0.1 不同时设计职责重叠的 lint、validate、audit、check。后续确有需求时，用 --scope 区分源码提示和产物校验。

诊断与质量范围

先覆盖高置信度、可行动的失败：工具链不符、主题未解析、必要配置非法、本地链接目标或锚点或资源缺失、已启用输出的引用不一致。路由和锚点以 Hugo 产物为准，覆盖语言与 base path。不能因为编辑器 Schema 未列出某个自定义 front matter 字段，就把合法输入判成错误。

未启用的可选输出不应触发缺失错误。本地候选不检查翻译完整性；后续完整性规则必须使用站点实际声明的语言和覆盖政策。重复标题、孤儿页、缺少描述、文风与新鲜度仍属后续可选观察项，经过真实误报评审后再决定默认值。静态检查不能声称浏览器无障碍或交互测试已经通过。

本地候选冻结 oink.result/v1：结构化诊断包含稳定规则 ID、严重度、已知位置、解释、行动建议与明确覆盖范围。JSON stdout 只输出结果，日志进入 stderr，所有命令均不等待输入。退出码 0 表示必要工作完成且无阻断项，1 表示政策问题，2 表示必要工作未完成。必需但不支持的检查不能返回成功。详细字段归属结果契约，不为构建派生问题编造行号。

保留 Hugo 原始错误作为子进程证据，其人工文案不构成 CLI 协议。将来可以从同一结果投影 SARIF，而不改变规则语义。

升级与文件保护

现有消费站升级脚本提供了有价值的本地先例：区分声明 pin 与解析版本，发布验证时禁用两套 workspace，识别模块 replacement，检查 _vendor。通过聚焦测试移植这些行为，不能在背后调用未发布的 Python 文件，却宣称是独立 Go 二进制。

0.1 只升级一个明确选择的站点。跨站批量发现暂留维护者脚本，等真实消费者提出需求。普通 check 可以检查有意使用本地主题替换的环境；check --release 必须排除这些替换，验证声明的公开版本。发现 go.mod 中冲突的 replacement 应报告，不应擅自删掉。

先展示将修改的文件，验证候选升级，再应用。只备份涉及的文件；预览后文件又发生变化时拒绝覆盖；保留无关的未提交工作。失败时应说明哪些已应用、哪些未应用，并提供不会覆盖后续编辑的恢复路径。仓库不干净不应阻止只读诊断。刷新 vendor 是单独的显式动作，只改 go.mod 不等于升级了 vendor 输出。

初始化和修复不能顺便 commit、push、部署、修改全局 Agent 设置或安装系统包。向明确的新目录初始化，本身就是用户请求的创建动作；修改既有文件则默认预览。不要为了这些有边界的操作构建通用工作流引擎。

分发与离线行为

本地候选当前提供已测试的源码／Make 安装路径与归档准备。公开 Homebrew formula、下载入口及标签安装仍属后续分发工作。当前运行验收覆盖 macOS arm64；其他归档目标仅为交叉编译候选，尚未在对应平台执行。

采用 Go 可执行文件，提供发布归档、校验和与 Homebrew 安装方式。先正式验证实际测试过的 macOS、Linux 架构，其它平台在文件系统和进程行为验证前标记为实验支持。安装后的 CLI 本身不要求安装 Go 工具链、Python、Node 或注册账户。Hugo 仍为外部渲染器；首次模块解析仍需要站点文档规定的 Git、Go、Hugo 工具链。

嵌入或随版本提供准确、保留许可证的 Starter 快照，保证初始化可重复。不应每次抓取变化中的 main，也不在 CLI 中手工维护 Starter 配置副本。发布 CLI 时检查内嵌模板与来源的一致性。

区分冷安装与离线运行。未在本地提供时，下载 Hugo、主题或未缓存模板需要网络。依赖齐备之后，本地诊断、检查和构建路径应无需外部服务。离线请求遇到缓存缺失应明确失败，不能偷偷下载。外链检查、远程规范等联网行为单独启用。无需默认遥测或后台更新检查。

第一项扩展：迁移

从实际候选站点中选择一套 有文档说明的 Docsy 输入配置范围，参考现有迁移夹具和报告模型。现有 OINK 0.4/0.6 转换并不能证明任意 Docsy 站点已经可以迁移。除 Markdown 语法外，还必须检查配置、导航、资源、语言和路由。

拟议流程为 oink migrate --from docsy --source <site> --output <new-site>。先评估再写入；应用需要显式参数，并输出到独立目录。每个源项目只有一个主要状态：原样兼容、已转换、人工复核、不支持。数量必须能够核对，附理由与源码位置。自定义模板和动态行为应明确列为人工工作。

验收包括源文件保留、支持范围内的转换幂等、不修改字面代码示例、站内引用有效，以及明确的旧新路由对照。优先保持 URL；改变 URL 时须提供适合托管目标的重定向方案。HTML 构建成功不足以证明语义一致或生产重定向生效。

不要承诺“一条命令迁移任意 Docusaurus 站点”。任意 JSX、import、内嵌 React/Vue 是程序，不能执行不受信任的源码来猜测含义，也不能静默删除无法处理的内容。第一条配置范围在没有维护者救场的情况下得到复用后，再开始第二个框架。完整 MDX 迁移是后续产品投入，不是 MVP 的一个解析器任务。

下一项内容能力：版本生命周期

首个 CLI 有用之后，默认优先考虑版本生命周期，因为它延续 OINK 已有的独立构建模型。只有真实 API 用户提出更强、反复出现的需求时，才把 OpenAPI 提前。单一主维护者不同时实现这两个基础。

主题负责读者界面的版本身份、可靠页面切换、归档状态，以及范围正确的搜索和机器输出。CLI 负责查看版本、准备快照、验证页面对应关系、修改声明的生命周期状态。oink --version 表示可执行文件版本；将来的 oink docs version ... 避免与文档版本混淆。

优先采用小型版本清单，记录版本标签、源引用、base URL、状态和默认选择。保留各版本独立构建及现有外部归档。CLI 管理的清单可以生成纳入 Git 的 Hugo 配置；在该模式中，清单由用户维护，配置是接受检查的投影。现有手工管理的 params.versions 继续受支持。原型必须先确定投影关系，再冻结格式。

页面对应关系需要按文档族、语言、版本区分的逻辑页面键。优先复用合适的 translationKey 或显式稳定键，不先引入通用 UUID。目标版本缺页时应明确说明，并进入约定的版本或分区首页，不能伪造等价页或盲目拼接 URL。路由别名处理页面搬迁，与页面身份分开。

内容有实质差异的历史页通常保留自己的 canonical URL，不能全部指向最新版。语言 alternate 应指向同版本中确实存在的翻译。默认搜索与 Agent bundle 保持在当前语言和版本范围内；将来若有跨版本聚合，必须显式启用。归档应保留源码并记录构建产物如何保存，不等于删除，也不悄悄重新部署不可变归档。

NAVJSON v1 的对象 Schema 当前禁止额外字段。因此增加版本或身份字段需要明确的新 Schema、输出契约或独立产物，不能声称是无影响的 v1 字段扩展。仅仅为未来图谱预留空间，不足以成为修改当前页面身份的理由。

随后的能力：静态 OpenAPI 参考

首个 OpenAPI 产品应是 只读静态参考生成器。CLI 解析本地规范及支持的本地引用，输出普通 Markdown/Hugo data，记录来源。主题提供符合无障碍要求的语义呈现和已有输出流水线，再由普通 Hugo 将生成页构建为 HTML、Print、Markdown、搜索和 Agent 索引。

先支持操作、参数、请求与响应正文，以及带链接的 Schema 描述。解析器原型完成后明确支持的 OpenAPI 版本和构造，不能静默丢弃不支持的构造。操作身份按 API/规范分域；缺少 operationId 时可由 method/path 派生，同时提示路径变化会影响身份。不同 API 复用同一 operationId 不能发生冲突。

人工指南与生成事实分开保存。生成必须确定、记录源哈希和生成器版本、能够检测过期输出，遇到非预期人工修改拒绝覆盖。将生成源码纳入站点 Git，或作为带版本的构建输入提供，使渲染本身仍不依赖 CLI。解析远程引用属于显式准备步骤，普通生成不能遍历任意外部 URL。

验收除玩具示例外，还要有真实用户规范；支持的操作完整可核对，循环引用能够处理，路由稳定，选定输出均包含语义内容，新静态渲染器的无障碍检查不继承 Swagger/Redoc 豁免。承诺吞吐指标前先测有代表性的大型规范。

保留现有 Swagger/Redoc 集成的兼容性。交互请求、凭据管理、SDK 生成、mock server 和 API 测试平台不进入本轮生成器增量。

架构与兼容规则

CLI 内部保持简单：命令处理、Hugo/进程适配、诊断、模板加载、限定范围的文件修改。迁移和 OpenAPI 到达对应阶段后再增加内部包。这只是建议分层，不是插件 ABI 或公共 SDK。

三个边界需要版本化：CLI 的机器结果格式、主题的公共 Schema/输出契约、受支持的迁移或生成输入配置范围。优先按能力检测，不一刀切要求“最新 OINK”。遇到更新但不支持的 Schema 时，必须给出可理解的兼容性诊断。

CLI 不能导入同级主题的私有 Python 模块、依赖特定本地 checkout 布局，或者运行时下载可执行检查器。通过行为测试移植选中的消费站操作。模板内部检查器仍留在主题；公开消费规则的后续变化同步更新其对应契约。过渡期间保留现有脚本，替代实现覆盖受支持场景后再退出重复实现。

初期不要求 CLI 配置文件，渲染配置继续由 Hugo 管理。重复使用证明有必要时，工具政策文件可以包含忽略路径、规则严重性和经过审阅的基线，但不能再维护 params.ui、导航、语言或模块 pin 的副本。Lint 基线不能豁免 Hugo 构建失败、输入不可读或必需检查不受支持。

路线图与人力假设

下列时间范围保留原始规划含义，不作为执行日志。阶段 0 与阶段 1 已有首期本地候选，但这不代表公开发布、独立用户研究、迁移或后续内容模型目标已完成。实际证据归入验收记录。

以下是 首阶段 8–12 周的规划范围，假设约一名全职实现负责人，并有部分文档与评审支持。这不是交付承诺，也不是对实际人力的判断。工具链验证、用户招募和双语评审都需要时间；应优先缩小范围，避免名义上的多线并行。

如果阶段 2 超期，移除该版本中的迁移写入能力，保留评估报告。不能削减升级保护、真实诊断或 CLI 可选性。如果没有独立团队需要这套迁移配置范围，就停止扩充框架覆盖，回到上手体验与定位研究。

新鲜度、归属信息是后续可选质量能力，先以用户确实会处理的报告验证价值。修改日期绝不能冒充验证日期。先提供少量有用的官方页面模板，再考虑 registry。G2/G3 图谱、MCP、分析适配器、可执行示例、Studio 和托管服务，都需要具体用户问题及资源决策，不应现在填入确定日程。已有静态 Agent 输出，使 MCP 的紧迫性低于采用流程。

验收与产品指标

下列用户与采用指标仍是目标。维护者执行的本地试点用于验证实现和文件保护，不能证明独立团队、首次使用成功率、留存或生产采用情况。

主要采用指标使用独立维护的生产站点，通过公开引用或用户自愿确认核实。稳定文档站不应因为 60 天没有提交而退出统计；主题升级时效与留存分别衡量。Star、下载次数、自有消费站数量和 Agent 生成量都只是辅助信号，不能证明独立采用。

首次本地成功时间、首次生产发布时间、升级成本、迁移人工成本分别记录。部署可能依赖 CLI 之外的账户与服务商，不能把本地验证等同于发布。不要为收集指标引入默认遥测。

实现归属与验证

先运行最小归属检查。公共行为变化仍要求实现、检查器和双语契约协调交付。真实集成与视觉验收使用同级站点的 make check、make browser、make dev 流程。公开回归场景不搬回主题的合成夹具树，也不要求普通消费者安装维护者使用的 Node 测试栈。

发布时分别记录本地检查、提交、标签、公开模块或二进制解析、消费站 pin 与部署。主题发布后的采用继续使用现有消费站盘点流程。一个协调 issue 或清单即可连接各仓库，无需新增编排框架。

待决问题与停止条件

仓库选择与首期实现在本地已确定。剩余发布决策包括经过验证的平台、公开分发渠道、有实际执行证据支持的兼容声明，以及独立试点招募。验收记录列明实际本地工具链与选定站点，不代表未来平台或用户已经验证。

本地候选的结果与退出语义已在 CLI 契约中冻结。最小主题能力描述与稳定主题警告 ID 保持独立提案，不追加入首个 CLI 的前提条件。版本 beta 前确定清单投影、归档保存方式和页面对应关系；OpenAPI beta 前确定支持的规范子集与生成源码归属。

如果试点实际只需要一个小型维护脚本，规则必须反复复制模板语义，或者分发维护成本超过测得的用户价值，就重新评估独立 CLI 投入，并保留已经有用的独立脚本。证据变化时可以调整版本化与 OpenAPI 的顺序，不增加同时开展的总范围。

决策日志与来源

查阅的本地权威包括：架构、生成式 Schema 决策、迁移边界、现有版本行为、OpenAPI 限制、图谱提案状态。还检查了主题 bin/、schema/nav.v1.schema.json、现有 Starter 与文档站构建检查命令。本地在途改动没有被表述为公开发布证据。

外部一手资料核实日期为 2026-09-29，包括上文链接的 Mintlify 命令参考、Nimbus 仓库、Docusaurus 版本指南及 Hugo 配置和模块文档。这些来源支持产品比较，不能证明 OINK 的市场需求或拟议时间表。