# OINK CLI 与下一阶段产品路线

> 已接受的独立 CLI 边界与首期本地候选，并明确保留后续采用、主题、迁移及内容模型提案。

---

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

---

> [!WARNING] 首期为本地候选，后续路线仍是草案
> 用户于 2026-09-29 授权独立 Go 仓库 `pgsty/oink-cli` 及首期开发。六个命令已有本地 `0.1.0-dev` 实现，最终本地验收单独记录。当前行为归属 [CLI 决策与结果契约](/zh/docs/design/decisions/cli/)及[使用指南](/zh/docs/start/cli/)。这不代表 CLI 已公开发布或已有独立用户采用。主题 1.2、工具能力描述、Docsy 迁移、版本生命周期、OpenAPI、MCP 与 Studio 保持提案状态。

| 记录 | 内容 |
| --- | --- |
| 状态 | 仓库选择与首期范围已接受；本地候选已实现并验证；后续路线保持草案 |
| 负责人 | OINK 维护者；最终本地验收与公开发布仍为独立状态 |
| 日期 | 2026-09-29 |
| 范围 | OINK 主题、独立 CLI、现有 Starter 与文档站 |
| 受影响契约 | 架构、配置与诊断、输出、迁移，以及后续的版本导航与 API 内容 |
| 源码快照 | 主题 HEAD `3a18234`、文档站 HEAD `85f16bf`、Starter HEAD `137843b`，以及下文明确标注的本地工作 |

## 核心建议 {#recommendation}

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

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

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

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

## 产品定位与目标用户 {#position}

建议对外描述为：

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

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

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

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

## 证据与对研究建议的调整 {#evidence}

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

| 观察 | 产品含义 |
| --- | --- |
| OINK 已有公开 Starter、生成式配置 Schema、迁移脚本、出版工具和主题检查器 | 应把选定流程产品化，避免另起一套全量实现 |
| front-matter Schema 刻意不包含类型约束 | 它不是完整的可执行校验器；严格检查要尊重对应解析器和真实 Hugo 输出 |
| 现有版本功能包括跨站菜单、归档横幅和可选的路径拼接 | 缺口是生命周期与可靠的页面对应关系，不是再加一个菜单或横幅 |
| 当前版本文档明确采用各版本独立 Hugo 构建 | 首先延续该模型，不悄悄引入单次构建内的多版本渲染体系 |
| OpenAPI 组件在 HTML 之外只保留规范链接，并有明确的无障碍豁免 | 静态、无障碍的端点内容是一项具体的后续改进 |
| 反向链接已实现，G2/G3 仍为草案 | 图谱可视化不是已经接受的交付承诺 |
| `bin/update-consumers.py` 在当前工作树中属于尚未提交的本地工作 | 可以参考其版本解析与文件保护规则，不能据此宣称 CLI 已发布 |
| 主题和文档站有大量与本提案无关的本地修改 | 本提案只记录建议，不替这些工作完成验收或发布 |

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

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

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

## 为什么独立建仓 {#repository-choice}

| 方案 | 好处 | 代价 | 建议 |
| --- | --- | --- | --- |
| 继续扩充主题 `bin/` 下的 Python 脚本 | 小型维护改进最快，可以同时修改并测试 | 安装分发体验弱，没有统一的公共命令契约 | 保留内部和历史工具 |
| 在主题根 Go 模块内添加 `cmd/oink` | 单一 checkout，源码修改可以原子提交 | 混合 Hugo 资源模块、应用依赖、二进制发布和消费站支持 | 不作为公共 CLI 的方案 |
| 在主题仓库中使用独立 Go 子模块 | 保留同仓修改，同时隔离 Go 依赖 | 仍需管理子模块标签与独立发布，也更容易直接调用未发布主题内部实现 | 可用于限时原型，不作为首选产品归属 |
| 新建 `pgsty/oink-cli` | 可执行工具边界清楚、独立发布，用户无需克隆主题内部工具 | 必须显式维护兼容性和跨仓验收 | 已接受；本地 Go 仓库已建立 |

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

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

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

## 职责划分 {#responsibilities}

| 范围 | 归属 | 边界 |
| --- | --- | --- |
| 布局、组件、样式、导航、搜索、无障碍、输出语义 | `pgsty/oink` | 在 Hugo 与静态站点中运行 |
| 主题默认值、对应解析器、生成式 Schema、输出 Schema | `pgsty/oink` | 主题行为权威及其投影 |
| 主题实现检查与小范围非法输入夹具 | `pgsty/oink` | 继续作为维护者工具，允许使用 Python 或 JavaScript |
| 环境诊断、消费站检查、初始化、升级，以及后续迁移转换 | `pgsty/oink-cli` | 首期命令已在本地实现；迁移保持提案 |
| OpenAPI 解析与源码生成、后续版本快照编排 | `pgsty/oink-cli` 的拟议后续能力 | 生成普通 Hugo 输入，不负责最终渲染 |
| 小型官方站点骨架与语言配置 | `pgsty/oink-starter` | CLI 初始化的单一来源；可将固定快照嵌入 CLI 版本 |
| 指南、案例、PRD、已接受理由、双语集成与浏览器验收 | `pgsty/oink.pgsty.com` | 继续作为公开文档与回归站点的权威 |
| 托管凭据、账户开通、部署授权 | 消费站工作流 | 使用现有 CI 与服务商工具；CLI 首发不执行部署 |

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

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

## 下一期主题：建议 OINK 1.2 {#theme-next}

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

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

| 优先级 | 需求 | 验收 |
| --- | --- | --- |
| P0 | 在已有 Schema 旁提供小型、带版本的工具能力描述，声明可用 Schema、输出契约与工具链边界 | 描述由对应实现校验；CLI 从实际解析的模块读取；不新增逐页产物或运行时请求 |
| P0 | 让少量高价值配置诊断直接指导修复：参数、非法值、允许形式、回退和对应指南 | 覆盖真实上手故障，如 Goldmark、输出与语言配置；保留普通预览告警、严格发布失败的约定 |
| P0 | 读者界面与机器产物继续共用导航和 Markdown 权威 | 现有输出、导航检查继续覆盖语言、顺序、子路径及可选输出；CLI 不另写渲染器 |
| P0 | 随版本交付经过测试的 Starter 快照与下游采用记录 | 将公开模块解析与同级替换构建分开验证，分别记录消费站 pin 和部署 |
| P1 | 原型证明有必要时，为工具消费的少数诊断加入稳定标识 | 每个标识有对应检查器；CLI 不依赖对所有人工告警文本的解析 |

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

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

## CLI 首发：建议 0.1 {#cli-first}

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

| 命令 | 用户结果 | 首发边界 |
| --- | --- | --- |
| `oink doctor` | 理解站点为何无法运行，或者本地环境为何与 CI 不同 | 检查 Hugo Extended 与版本、模块 pin 与实际来源、Starter/工具链要求、必要配置、启用输出；默认不修复 |
| `oink check` | 知道发布构建和本地引用是否有效 | 在隔离输出中进行一次严格构建，再检查站内链接、锚点、资源与启用的机器产物；报告覆盖范围与不支持的检查 |
| `oink init my-docs` | 得到一个无需 CLI 也能维护的小型中性站点 | 从固定 Starter 快照生成到新目录或空目录，选择支持的语言配置并固定主题版本 |
| `oink upgrade --to <tag>` | 看清主题升级需要修改哪些内容 | 默认预览，`--write` 在验证后应用已审阅范围；保护无关模块依赖、用户修改与 vendor 内容 |
| `oink dev` / `oink build` | 获得容易记忆的入口，无需学习第二套构建系统 | 轻量调用 Hugo，展示生效参数；`build` 使用发布严格度；始终支持直接使用 Hugo |

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

### 诊断与质量范围 {#diagnosis-quality}

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

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

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

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

### 升级与文件保护 {#upgrade-preservation}

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

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

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

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

### 分发与离线行为 {#distribution-offline}

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

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

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

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

## 第一项扩展：迁移 {#migration}

从实际候选站点中选择一套 **有文档说明的 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 的一个解析器任务。

## 下一项内容能力：版本生命周期 {#version-lifecycle}

首个 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}

首个 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 测试平台不进入本轮生成器增量。

## 架构与兼容规则 {#architecture}

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

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

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

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

## 路线图与人力假设 {#roadmap}

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

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

| 阶段 | 自批准起的时间 | 交付物 | 退出证据 |
| --- | --- | --- | --- |
| 0：确定边界 | 第 1–2 周 | 接受仓库选择，收集真实故障，定义结果格式与支持基线，在当前 1.1.0 上原型验证只读 doctor/check | Starter 加至少三个不同形态的真实仓库；记录失败与覆盖缺口 |
| 1：完成日常流程 | 第 3–6 周 | doctor/check、固定模板 init、轻量 dev/build、单站候选升级与文件保护测试 | 新用户能定位预置故障；生成站仍可直接 Hugo 构建；没有无法解释的源码修改 |
| 2：发布有边界的产品 | 第 7–12 周 | 拟议主题 1.2、CLI 0.1、兼容记录、文档、经过验证的安装方式、有限 Docsy 迁移评估与试点 | 首次使用测试与重复升级使用；迁移限制明确；公开 pin 与下游采用单独验收 |
| 3：验证迁移及一个内容模型 | 第 4–6 月 | 完善首条迁移路径；按用户证据选择版本生命周期或 OpenAPI；需要时规划主题 1.3 / CLI 0.2 | 至少两个真实仓库使用所选流程；接受契约后才承诺兼容性 |
| 4：证据支持的扩展 | 第 6 月之后 | 另一项内容能力，再按需求引入模板、来源信息或 Agent 传输层 | 有重复使用与维护能力；不自动承诺 SaaS 产品 |

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

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

## 验收与产品指标 {#acceptance}

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

| 范围 | 初始目标或必须满足的性质 |
| --- | --- |
| 首次成功 | 前置工具已安装时，5 名不熟悉 OINK 的目标用户中，至少 4 名在 15 分钟内无需维护者干预就完成预览与严格检查；冷安装另行记录 |
| 维护价值 | 至少三个真实站点使用诊断与检查，并重复完成受支持升级；每次失败均有可行动报告 |
| 诊断准确性 | 试点中逐项复核阻断发现，在明确计数、人工标注的样本中争取误报率低于 5%，不能把它当作未经测量的宣传 |
| 完整性 | 零静默内容丢失；迁移输入逐项可核对；重复转换无差异；用户编辑和无关依赖得到保留 |
| 独立性 | 依赖准备好后，初始化或生成的站点可以直接用 Hugo 构建；CLI 与可选输出仍可选择 |
| 离线行为 | 依赖准备完成后，在禁止出站访问的环境验证受支持本地流程；缓存缺失和显式联网功能分别记录 |
| 兼容性 | 当前经过测试的主题基线与候选版本、固定的站点回归工具链、根路径和子路径、中英文场景；不暗示已测试兼容下限以上的每个 Hugo 版本 |
| 采用情况 | 首阶段争取五个独立试点团队，跟踪其是否进入生产及在 30/90 天后继续使用；这是验证目标，不是现有用户成绩 |

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

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

## 实现归属与验证 {#implementation-validation}

| 改动 | 对应验证 |
| --- | --- |
| 工具能力描述与 Schema 兼容 | 聚焦的主题描述检查器，以及 `generate-config-schema.py --check` 和相关参数检查 |
| 暴露给消费者的诊断 | 对应解析器与检查器用例，CLI 诊断结果和退出码测试 |
| 已有输出行为 | 按变化范围选择 `check-agent-indexes.py`、输出、安全和导航检查 |
| 初始化与升级 | 固定 Starter 快照，以及包含 replacement、vendor、无关依赖、目标文件未提交修改的 CLI 测试仓库 |
| 迁移 | 移植并扩充转换用例、源文件保护与重复运行检查，真实站点路由和内容复核 |
| 后续版本与 API 呈现 | 主题输出检查，以及双语文档站的集成、浏览器、无障碍、响应式和视觉评审 |

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

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

## 待决问题与停止条件 {#open-decisions}

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

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

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

## 决策日志与来源 {#decision-log}

| 日期 | 记录 |
| --- | --- |
| 2026-09-29 | 根据提供的战略研究与本地源码评审创建草案。建议独立可选 CLI、小型采用版本、有边界的迁移和依次推进的内容能力。本文件没有接受任何实现或建仓操作。 |
| 2026-09-29 | 随后用户授权并接受独立 Go 仓库与首期开发。本地 `0.1.0-dev` 候选已实现 doctor/check/init/upgrade/dev/build；稳定行为移入 CLI 决策与使用指南。CLI 提交 `e623d93` 已通过本地验收；公开发布、独立采用及所有后续阶段提案继续分别记录状态。 |

查阅的本地权威包括：[架构](/zh/docs/design/architecture/)、[生成式 Schema 决策](/zh/docs/design/decisions/config-schema/)、[迁移边界](/zh/docs/design/migration/)、[现有版本行为](/zh/docs/customize/versions/)、[OpenAPI 限制](/zh/docs/write/openapi/#limits)、[图谱提案状态](/zh/docs/design/proposals/knowledge-graph/)。还检查了主题 `bin/`、`schema/nav.v1.schema.json`、现有 Starter 与文档站构建检查命令。本地在途改动没有被表述为公开发布证据。

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

---

反链：

- [CLI 契约](/zh/docs/design/decisions/cli/)
- [提案](/zh/docs/design/proposals/)
- [CLI 文档维护](/zh/docs/design/proposals/oink-cli-maintenance-roadmap/)
- [2026-09-29 CLI 验收](/zh/docs/design/research/2026-09-29-cli-acceptance/)
- [2026-10-03 CLI 维护](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/)
- [CLI 功能概览](/zh/docs/start/cli-overview/)