# OINK CLI 文档维护路线图

> 文档维护与 Oink Studio 的 R1–R8 历史需求记录，保留对应验收证据并指向当前精简 CLI 契约。

---

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

---

> [!NOTE] 已实现需求记录
> 有限 R1–R8 受支持本地实现与 A18 运行时/归档范围对验收增补记录的历史源码和
> 二进制通过；当前精简 CLI 需要独立验证。本记录保留原 URL
> 与锚点，保留历史排期文本和失败试验；稳定行为归属
> [CLI 契约](/zh/docs/design/decisions/cli/)与[指南](/zh/docs/start/cli/)，历史证据归属
> [2026-10-04 增补](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#a18)。
> 记录退出活动导航，未启动 E1–E4 是独立非活动范围。渲染导航/URL 验证需要这些准确晋升字节的独立收据。

先完成文档维护，再建立本地可视化工作台。产品应当帮助维护者检查修改、理解影响、
审阅安全变更，并发布刚才通过检查的同一份产物。Studio 使用这些相同能力。

| 记录 | 内容 |
| --- | --- |
| 状态 | 已实现；R1–R8 受支持本地范围与当前 A18 运行时/归档验收通过；渲染生命周期验证具有独立准确字节收据边界 |
| 负责人 | OINK 维护者；具体研发与评审人员待确认 |
| 日期 | 2026-10-03 |
| 已有基线 | 本地 CLI `0.1.0-dev`，提交 `e623d93`；macOS arm64 上的 Hugo Extended 0.166.0 与 Go 1.27.1 |
| 完成范围 | R1–R8 及下文验收用例；条件性扩展另有启动条件 |
| 受影响范围 | CLI 命令与结果契约、Starter 投影、消费站 CI、翻译政策、维护操作、本地 Studio、中英文指南 |
| 排期假设 | 一名全职开发，配合定期文档与评审支持；工期属于规划判断 |

## 背景与证据 {#background}

[原 CLI 路线图](/zh/docs/design/proposals/oink-cli-roadmap/)已接受独立 Go
可执行文件，将首次实现收敛为 `doctor`、`check`、`init`、单站点 `upgrade`、
`dev` 与 `build`。本提案增加有明确边界的文档维护计划。Docsy 迁移、版本生命周期、
OpenAPI 生成与主题 1.2 保留各自范围。

2026-10-03 的本地盘点重新执行了 Go 套件与真实 Hugo 集成测试。初始化的双语站点
检查通过，覆盖 223 个文件、4,461 条引用。PIG 消费站检查通过，覆盖 1,392 个文件、
64,440 条引用；858 个源文件及 Git 状态保持不变。这些是本地验证观察，不代表公开
分发、独立用户采用或部署。

盘点还复现了四项限制：渲染链接缺失时 `check` 失败而 `build` 成功；普通 HTML
引用越出配置的 base path 时被标为未检查；`doctor --release` 接受仍使用
`https://example.org/` 的 Starter；两份内嵌部署工作流都直接调用 Hugo，没有执行
CLI 的附加检查。翻译完整性与可读升级 diff 也尚未实现。首批增量由这些发现确定。

## 产品目标与用户 {#product-goal}

优先服务多语言工程文档维护者，以及维护多个 Hugo 站点的小团队。高频任务是审阅
翻译、防止发布损坏内容、更新依赖，以及在不丢失引用和公开 URL 的前提下整理文档。

普通消费站能在本地与 CI 使用同一个质量入口，查看受影响页面，审阅并应用修改，
同时保留无关工作，才算实现产品目标。CLI、Studio 与 Agent 调用应得到相同的发现项
和修改计划。

## 功能取舍 {#feature-selection}

| 原设计能力 | 决策 | 交付阶段 |
| --- | --- | --- |
| 内链、锚点、附件与机器产物 | 加强已有检查，说明未覆盖情况 | R1–R3 |
| 环境诊断、预览与严格构建 | 补齐发布诊断，增加显式的已验证构建流程 | R1、R3 |
| 翻译完整性与受保护结构 | 作为核心产品能力建设 | R2 |
| 初始化与 CI 配置 | 扩展固定 Starter，管理可审阅的 CI 修改 | R3–R4 |
| 原生内容规则与项目风格 | 实现少量确定性核心规则，通用工具按需接入 | R2、R6 |
| 新建内容、片段与编辑器配置 | 生成普通 Hugo 输入，保护已有文件 | R4 |
| 安全升级与迁移预检 | 增加 diff 和候选对比；框架迁移保持独立范围 | R4 |
| 页面移动、重命名与影响分析 | 页面关系与修改计划可靠后再实施 | R5 |
| 问题面板与翻译对照 | 先做只读的本地 Studio | R7 |
| 多站点 | 在单站引擎上增加显式站点登记 | R6 |
| EPUB、PDF 与离线打包 | 对可分发出版工具的条件性适配 | E1 |
| 可执行文档示例 | 使用显式执行配置的条件性功能 | E2 |
| Agent 检查、影响与上下文 | 实现确定性的本地操作 | R5 |
| AI 翻译与语义审阅 | 确定性维护流程可用后，再验证修改提案 | E4 |
| 来源、证据与知识依赖 | 本轮限定为构建及审阅来源、已观察到的页面关系 | 更广的知识管理延后 |
| 富文本编辑、实时协作与原生桌面端 | 只交付安全 Markdown 编辑；更大的平台延后 | R8；其余暂缓 |

## 范围与非目标 {#scope}

R1–R8 是本 PRD 有限且明确的完成范围，每阶段都能独立产生价值并验收。拟议 CLI
版本 `0.2`、`0.3` 与 `0.4` 仅标识候选交付，不要求创建对应公开标签，也不绑定主题版本。

本计划不包含新渲染器、通用迁移引擎、托管账户管理器、部署 API、内置 LLM、向量
数据库、远程编辑器、实时协作、原生桌面壳或完整所见即所得编辑器。部署由既有
服务商工作流完成；发布权限与凭据继续由消费站所有者管理。

## 共享项目事实与检查政策 {#shared-project-facts}

此范围已本地接受。下文保留原始提案需求作为历史；当前行为与参数归
[CLI 契约](/zh/docs/design/decisions/cli/#project-policy)所有。

扩展已有隔离 Hugo 分析，不另建配置解析器或导航权威。拟议内部事实包括页面身份、
语言、发布状态、实际输出 URL、已知源文件、翻译关系及已观察到的渲染引用。

使用 Hugo 公开的 [Page.Translations](https://gohugo.io/methods/page/translations/)
与 [Page.OutputFormats](https://gohugo.io/methods/page/outputformats/) 获取关系和产物。
[Page.File](https://gohugo.io/methods/page/file/)可提供来源，但部分页面没有对应文件。
这些发现项必须保留产物位置和源码未知状态。临时探针移除后，普通发布产物的字节
应保持不变。

仅用 `oink.yaml` 管理检查选择、严重度、翻译政策、已审阅排除项及工具和流程选项。
语言、标题、菜单、URL 与站点配置继续归 Hugo，主题版本归模块文件。先提供共享
同一次分析的 `check links`、`check translations` 与 `check style`。保留 `--json`；
`--format json` 可以作为兼容性的新增别名。

阻断错误、警告与建议沿用 `error`、`warning`、`info` 严重度。必需工具或输入形态
不受支持时仍返回退出码 `2`。政策不能把构建失败、输入不可读或必需检查未完成降级
为成功。源码位置需要可靠映射；无法定位时报告实际产物和 pointer。

## 翻译维护 {#translation-maintenance}

此范围已本地接受。下文保留原始提案需求作为历史；当前行为与参数归
[CLI 契约](/zh/docs/design/decisions/cli/#translations)所有。

支持 Hugo 解析的文件名语言、独立语言内容目录与 `translationKey` 关系。覆盖政策
在明确的内容范围内选择必需语言；已禁用语言和有意本地化不能变成缺译错误。
检查重复身份以及政策指定的草稿和发布状态。生产构建未包含评估政策所需的源文档时，
使用明确的分析视图；不能把分析视图当成可发布产物。

提供两类政策：技术手册使用严格对译，博客或产品页面使用本地化内容。严格政策可
要求显式 ID、声明的占位符、指定代码块和必要字段一致；本地化政策只检查明确声明
的共同约束。标题数量相等、所有代码块相等都不能成为普遍要求。

拟议提供 `translations status`、`translations diff <page>` 和显式的审阅记录操作。
带版本的记录将译文绑定到源文档内容哈希或 Git 修订，并记录译文哈希与声明的源语言。
没有记录表示未知；哈希改变表示审阅后有变更，不自动断言翻译错误。记录审阅必须
来自用户要求的写入，检查器运行本身不能自动生成已审阅状态。

## 原生内容规则与问题基线 {#native-content-rules}

此范围已本地接受。下文保留原始提案需求作为历史；当前行为与参数归
[CLI 契约](/zh/docs/design/decisions/cli/#native-content)所有。

先从真实消费站故障中提取少量高置信度规则：受支持组件及属性写法非法、显式 ID
冲突、已知弃用形式，以及项目配置的受保护内容。代码块、行内代码、短代码正文、
原始 HTML 和属性块需要各自的语法边界，不能无差别套用正则。

使用实际生效主题版本的契约。没有类型约束的编辑器 Schema 不能作为完整严格验证器。
缺少兼容元数据时，应明确限制覆盖范围，不能拿最新主题规则验证旧项目。基本检查
完成不以未来主题发布为前提。

可见且带版本的问题基线可以用稳定指纹、原因和审阅元数据确认已有发现项。报告
分别显示已确认项和新增项。基线更新必须显式、可审阅，不能隐藏必需检查未完成。
格式化与文风建议属于可选项。自动修复先生成 diff，再验证候选，最后只应用少量
边界明确的文件。

## 已验证发布产物与 CI {#verified-publication}

此范围已本地接受。下文保留原始提案需求作为历史；当前行为与参数归
[CLI 契约](/zh/docs/design/decisions/cli/#checked-artifacts)所有。

保留当前 `build` 默认的透明调用。增加显式受管理的 `build --check` 流程：严格运行
一次 Hugo，在同一份输出上执行选定检查，再把已验证产物导出到新目录或空目录。
不能删除任意目录，也不能把旧文件混入已验证产物树。默认 `build` 必须继续说明
附加检查尚未执行。

本地版本化 manifest 记录已知的源码修订与修改状态、源码输入哈希、实际主题身份、
Hugo/CLI 版本、构建设置、base URL、检查覆盖与文件摘要。秘密和本机路径不得进入
公开元数据。启用公开构建标识时，只保留验证所需的最少身份信息。检查后产物字节
发生变化，已有检查结果就不能继续证明该产物。

拟议提供 `ci init github-pages` 和 `ci init cloudflare-pages --mode direct-upload`。
只生成本地配置，解释变量与权限，记录模板来源。发现已有工作流时展示 diff，保留
未知修改，并要求显式应用。两种模板使用相同质量引擎，上传已验证输出，中间不能
再运行一次 Hugo。CLI 尚无公开版本时，模板必须接受明确记录的不可变源码或归档
输入，不能假设某个下载标签已经存在。

发布诊断增加示例地址警告；发布政策要求正式地址时，该问题成为阻断项。可取得时，
报告实际本地来源提交和修改状态，并与受支持的已生成 CI 设置比较。未知自定义 CI
仍显示未知。本地 checkout 的提交不能证明公开模块身份；vendor 字节身份保持独立。

拟议提供 `verify --site URL --manifest FILE`，需要显式联网许可。验证代表性页面、
语言、资源、搜索/Markdown 输出、规范 URL 和产物身份。通用回退页面即使返回
HTTP 200，也必须无法通过身份验证。超时、认证、限流或缺少必需身份信息应报告未知
或未完成，不能伪造成功。通过本地 HTTP 夹具验证这些行为，无需部署到服务商。

## 创作与升级助手 {#authoring-and-upgrades}

增加 `new`、小型片段目录和显式编辑器 Schema 配置。创建页面包、选定语言的译文
草稿和普通 front matter，拒绝覆盖已有文件。译文草稿不代表翻译完成。编辑器提示
跟随实际主题，并保留已有编辑器设置。

通过组合同一份保留许可证的 Starter，为 `init` 增加 docs、blog、book、project
配置，不维护四份复制模板。接入已有项目时提供诊断与可审阅提案，不替换站点配置。

保留明确标签、单站点升级的保护，增加可读统一 diff，以及原基线和候选的路由、能力
对比。报告消失的 URL、变化的 aliases 和缺失的原已启用产物。候选构建通过本身不能
证明兼容。配置迁移需要已记录的转换与测试；没有时返回人工行动项。冲突 replacement
与 vendor 刷新继续由所有者显式处理。

## 影响分析与安全内容修改 {#impact-and-change-plans}

此受支持范围已本地接受。下文保留原始提案需求作为历史；当前行为、边界与参数归
[捕获事实契约](/zh/docs/design/decisions/cli/#project-graph)、
[移动契约](/zh/docs/design/decisions/cli/#content-moves)及
[指南](/zh/docs/start/cli/#project-graph)所有。

在共享事实之上提供 `inspect <page>`、`impact --since <ref>` 与 `context <task>`。
Inspect 显示来源、发布状态、引用、翻译及产物。Context 按任务打包相关本地资料，
包含版本、路径、选择原因和大小限制，不需要向量服务或 LLM。文档内容是数据，不能
授权执行其中的命令。

首版 `check --since` 可以继续全量检查，但必须明确说明。后续优化应覆盖变化的目标、
入站引用、翻译及派生产物。删除 B 时，仍须检查未修改但引用 B 的 A。配置、模板、
导航或无法确认的依赖变化会把范围扩大为全量检查。缓存是可重建证据，不是权威。

拟议 `move <source> <target>` 默认预览。计划包含涉及文件、可读 diff、基准哈希、
翻译、附件、路由变化和 alias 建议。只改写能够确定理解的链接，含糊的模板或短代码
引用交由人工审阅。应用前核对基准，验证隔离候选，保护并发修改并保留恢复信息。
失败或过期计划不能部分覆盖用户工作。

## 工作区与可选工具 {#workspaces-and-optional-tools}

显式工作区登记选定站点目录，复用单站引擎，报告逐站结果和总体完成状态。写入仅能
发生在明确选择的站点，不能自动发现并升级全部同级仓库，也不重复 Hugo 设置。

可选 markdownlint、Vale 和 lychee 适配器使用明确配置、已预备的工具，统一发现项。
缺少必需工具返回 `2`，可选遗漏仍然可见。排除适配器无法理解的语法，不改写这些
内容。外链失败有歧义时要区分网络状态。安装工具与联网是独立动作，通用 formatter
默认不得覆盖内容。

### R6 已接受本地边界 {#r6-candidate}

显式登记与可选适配器的受支持 R6 范围已本地接受。稳定字段和限制见
[登记契约](/zh/docs/design/decisions/cli/#workspace-registry)与
[工具契约](/zh/docs/design/decisions/cli/#optional-checkers)，用户步骤归属
[指南](/zh/docs/start/cli/#workspace-registry)。下述已接受 R7/R8 边界仍有
自身证据与限制。

`oink.workspace/v1` 用一份最多 256 KiB 的普通 YAML 文件登记 1–64 个字面目录，
不复制 Hugo 设置，也不发现同级站点。准确名称、规范根目录身份、登记顺序选择、
逐站 `0`/`1`/`2` 一致性及显式名称应用保存计划构成受支持工作区边界。已预备的
markdownlint-cli `0.49.1`、Vale `3.24.0` 与 lychee `0.24.2` 扩展各站政策，
捕获配置并提供类型化协议/源码/网络覆盖；不安装工具或格式化内容。Lychee 需要
显式联网授权；有歧义的外部失败保留未知，不判为确定断链。

冻结 Go/vet、实际 Hugo/固定工具及归属 race 门禁已经通过。精确二进制也通过
四站直接/汇总诊断/覆盖/退出一致性，以及全部源码字节/完整模式/Git/被忽略输入/
目录保护。初次预备失败仍不计作验证通过证据；仅验收驱动命令元数据的收据修正
独立记录，没有 CLI 运行时修正或重跑。受保护规范中英文源码/渲染检查通过，
R6/A07/A15 受支持范围已本地接受，见
[R6 记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r6)。
当前 A18 运行时/归档验证通过；Darwin amd64 保持实验/未验证。聚焦测试不能推断版本发布、消费者采用、源码写入或部署。

## 只读 Oink Studio {#read-only-studio}

建设本地 Web 界面，提供项目总览、问题面板、翻译对照、页面关系和发布面板。
这些视图使用与 CLI/CI 相同的核心结果，支持筛选、跳转已知来源、真实 Hugo 预览、
变更对照和复制建议。大型图谱或内置编辑器不是这一阶段验收的前提。

默认仅监听本机，明确允许访问的站点。将不可信渲染内容与管理界面隔离到不同 origin；
增加写 API 前，做好 Host/Origin 检查和会话授权。UI 预构建后随 CLI 分发，Node 是
贡献者构建依赖，不是消费用户运行依赖。覆盖键盘操作、屏幕阅读器标签、移动端布局、
深浅色和长问题列表的可读性。

### R7 候选边界 {#r7-candidate}

只读 Studio 候选现已基于同一原生检查与捕获 Hugo 事实，提供内嵌五视图浏览器和
鉴权字面回环 API。稳定候选边界见[契约](/zh/docs/design/decisions/cli/#studio)与
[指南](/zh/docs/start/cli/#studio)。显式现存站点/登记选择、类型化分页发现、源码/
diff/哈希状态、真实生产预览及独立可选分析覆盖保留 CLI 权威。

冻结原生/浏览器/核心案例及精确二进制四消费者收据现已验证受支持只读范围，
包含明确局部预览未完成状态。它们覆盖原生 `0`/`1`/`2` 一致性、键盘/移动端/深浅色、
字面源码数据及独立 origin 预览攻击。R7/A16 已通过受保护规范晋升/渲染门禁并
本地接受。R1–R8 受支持范围已接受；
当前 A18 运行时/归档验证通过。不新增消费者 Node 依赖、隐式安装、源码写入、公开发布/采用
或部署。

## 安全 Markdown 编辑 {#safe-markdown-editing}

只读工作台验收后，增加 Markdown 编辑、front matter 表单、选定组件插入和附件。
复用 CLI 修改计划引擎及真实 Hugo 预览，不建立第二套保存与验证机制。

没有修改的打开/保存周期必须保留原始字节。更新一个字段应保留未知字段、注释、顺序、
编码和无关空白。检测外部编辑器修改，拒绝过期保存。表单无法保留某种 front matter
构造时，保留文本编辑并说明表单限制，不通过通用序列化器重新输出整篇文档。

写入需要已授权本地会话、允许目录、基准校验和可见 diff。拒绝目录穿越、符号链接
越界以及来自不可信预览内容的请求。附件不能覆盖既有文件。发布静态站点不会把管理
API 一并发布出去。

### R8 已接受编辑边界 {#r8-candidate}

R8 已为 CLI `edit text`、`field`、`snippet`、`attachment` 及显式
`studio --edit` 实现同一源码保护提议引擎，默认 Studio 保持只读。已知站点所有
Markdown、准确源码哈希、支持顶层 YAML 标量/文本回退、原生目录字节边界插入及
仅新建 leaf-bundle 附件共享同一保存计划和保护写入器。完整可见审阅绑定计划/文件/
完整模式身份；候选 HTML 来自实际选定不可发布 Hugo 分析，原生发现与必需视图
未完成保持不同。

已接受本地接口见[契约](/zh/docs/design/decisions/cli/#editing)及
[指南](/zh/docs/start/cli/#editing)。修正冻结公共/Go/race/vet、实际/普通
Hugo、Editor 浏览器/无障碍/移动端及精确二进制四消费者保护门禁已通过。
R8/A17 受支持本地范围也通过受保护规范源码/渲染门禁并已接受，记录于 [R8 记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r8)。
先前失败浏览器/准备试验只证明当次输入，不验证后续字节。R1–R8 受支持范围已接受；当前 A18 运行时/归档验证通过。Darwin amd64 保持实验/未验证，公开发布、采用
与部署是独立未执行状态。

## 交付顺序与排期 {#delivery-sequence}

以下按一名开发估算，不代表已经测量的开发效率。T0 是范围批准后的实施起点，尚未
承诺日历开始日期。阶段依赖由顺序验收门禁约束；增加人员可并行独立测试与 UI 工作，
但不能取消门禁。

| 阶段 | 有效工作周 | 交付内容 | 验收门禁 |
| --- | --- | --- | --- |
| R1 | 第 1–2 周 | 共享事实、检查政策、分类检查、可信位置 | Hugo 拥有路由和关系；必需检查未完成不能通过 |
| R2 | 第 3–5 周 | 翻译政策及审阅状态、原生检查、可见基线 | 三种语言组织方式；严格/本地化用例；审阅修复保留文件 |
| R3 | 第 6–8 周 | 已验证构建产物、CI init、发布诊断、公网站点验证 | 上传同一份已检查产物；检测字节漂移与 HTTP 200 回退 |
| R4 | 第 9–11 周 | 新建内容、配置组合、片段/编辑器配置、升级 diff 与对比 | 普通 Hugo 可构建；脏文件、替换、vendor 与路由回归仍安全 |
| R5 | 第 12–15 周 | Inspect、Impact、Context、Move 与共享修改计划 | 包含未改入站引用及翻译；过期计划不能写入 |
| R6 | 第 16–17 周 | 显式工作区与可选检查适配器 | 逐站结果一致；必需工具缺失为未完成；不隐式安装 |
| R7 | 第 18–20 周 | 只读 Studio 与安全边界 | 五个实用视图；CLI/UI 发现项相同；无障碍与预览隔离通过 |
| R8 | 第 21–24 周 | 安全 Markdown/表单/附件与冲突审阅 | 无修改保存零 diff；注释和未知字段保留；并发保存安全失败 |

另留 4–6 周用于集成、误报审阅、跨平台执行与修复，分配到各验收门禁。总规划范围为
28–30 个有效工作周。投入约为半职时，日历跨度可能约翻倍；这是需要复核的假设，
不是承诺。

R1–R3 形成拟议 `0.2` 质量与发布候选，计入早期预留后约在第 9–10 周。R4–R6
形成拟议 `0.3` 维护候选，累计约第 19–20 周。R7–R8 形成拟议 `0.4` 本地 Studio
候选，累计约第 28–30 周。公开发布是另行授权的动作，本地候选不要求每阶段都发布。

## 条件性扩展 {#conditional-extensions}

| 扩展 | 启动条件 | 拟议边界 | 独立估算 |
| --- | --- | --- | --- |
| E1 出版导出 | 至少两本维护中的书需要重复执行导出流程 | 复用可分发 EPUB/PDF 工具，打包本地产物，声明外部依赖 | R3/R4 后 1–2 周 |
| E2 可执行示例 | 明确的所有者指定可运行示例及可丢弃环境 | 审阅的执行配置、时间和资源上限、默认离线；不自动执行发现的正文 | R5 后 3–5 周 |
| E3 MCP | 既有 Agent 集成确实需要 JSON CLI 调用以外的能力 | 对 inspect/check/impact/context/plans 的薄适配，沿用权限和诊断 | R5 后 1–2 周 |
| E4 AI 审阅与翻译 | 确定性翻译维护可用，且已有审阅过的评估语料 | 用户选择服务商，显式网络及费用设置，提案绑定源码哈希；不自动写源文件 | R5 后 3–6 周的有限实验 |

这些估算不计入 R1–R8 总工期。扩展只在相应场景成立时启动；未来需求不是尚未完成
的核心里程碑。远程 Studio、实时协作、原生壳、通用知识来源管理、向量检索与通用
框架迁移需要独立 PRD 和证据。

## 架构与兼容 {#architecture-and-compatibility}

核心操作继续用 Go，通过子进程调用 Hugo 和可选工具。已有包拥有相应行为时就在
其中扩展，新包随真实能力加入。实际消费者需要之前，不建设通用插件平台、公共 SDK
或共享服务层。

保留 `oink.result/v1`、退出码含义和默认薄包装。诊断详情与命令数据可增加字段，
改变字段语义则需要新结果版本。审阅记录、基线、计划、构建 manifest 和工作区登记
分别版本化。从实际主题检测受支持能力，不强制全部用户安装最新版本。

读取/检查/预览、应用本地文件、联网、执行示例和部署是不同副作用。维护操作不顺便
进行遥测、后台更新、发现凭据、清理任意目录、修改全局配置、提交、推送或部署。
消费站只读试点保留源码、replacement、workspace 和 vendor 字节。

## 验收用例与归属检查 {#acceptance-cases}

| 用例 | 必须达到的结果 | 主要归属 |
| --- | --- | --- |
| A01 JSON 与完成状态 | stdout 只有一个 JSON；日志分离；发现问题为 `1`，必需未完成为 `2` | `internal/report`、`internal/app`、Schema |
| A02 Hugo 权威 | Slug/url/permalinks/aliases、自定义挂载、未列出页面与语言根遵循真实 Hugo 结果 | `internal/site`、`internal/outputcheck`、真实 Hugo 夹具 |
| A03 子路径 | 确定属于项目的缺失路由失败；越出 origin/path 的引用真实分类；声明外部范围避免误报 | 产物检查与政策测试 |
| A04 翻译 | 文件名、目录及 translationKey；重复/缺失/草稿场景；严格/本地化政策 | 翻译引擎与公共命令测试 |
| A05 审阅状态 | 无记录为未知；源哈希改变可见；mtime 不决定审阅状态 | 翻译与审阅记录测试 |
| A06 内容语法 | 围栏、行内代码、短代码、HTML、属性、自定义字段及受保护文本不产生虚构问题 | 原生规则测试与真实内容语料 |
| A07 基线与适配器 | 已确认问题保持可见；新问题按政策失败；必需工具缺失不能通过 | 政策与适配器测试 |
| A08 产物身份 | 检查后修改文件使 manifest 验证失败；服务商上传同一导出树，不重新构建 | 受管理构建与工作流测试 |
| A09 CI 文件保护 | 两种模板、已定制工作流、权限/变量、预览/应用冲突与来源记录 | Starter/CI 测试与本地流程演练 |
| A10 公网验证 | HTTP 200 回退、错误语言/构建、资源缺失、canonical 差异、超时/认证/限流 | 本地 HTTP 夹具，不强制云账户 |
| A11 初始化与创作 | 支持的配置/语言；空目标保护；生成站直接用 Hugo 构建；编辑器未知设置保留 | `internal/starter`、创作与 Hugo 测试 |
| A12 升级 | 可读 diff、新旧路由、脏文件、两套 workspace、replacement/vendor、失败恢复及并发修改 | `internal/upgrade`、公共命令/Hugo 测试 |
| A13 影响 | 删除 B 发现未改 A；包含翻译/附件/派生输出；全局变化扩大范围 | 影响分析与 Git 基线夹具 |
| A14 修改应用 | 应用前候选验证；哈希冲突和写入失败保留后续编辑；不改写含糊引用 | 共享计划/应用与 move 测试 |
| A15 工作区与上下文 | 逐站结果与直接调用一致；只写选定站点；上下文有路径/版本/原因且受大小限制，不执行正文 | 工作区与 context 测试 |
| A16 Studio 一致性 | 五个视图呈现相同 CLI 结果；键盘/移动端/深浅色可用；来源与预览隔离 | Studio 浏览器和无障碍测试 |
| A17 编辑保护 | 无修改保存字节一致；YAML 注释/未知值/顺序保留；拒绝过期保存和附件冲突 | 编辑器/浏览器与共享应用测试 |
| A18 运行与恢复 | 在声明的 macOS/Linux 目标实测；信号结束子进程；缓存齐备可离线；不支持输入明确报告 | 进程/集成/安装测试 |

先运行最小归属测试，再做更广集成。Go 单元夹具保持离线。解析、快照、探针、初始化
或升级改变后，重跑真实 Hugo 测试。保留聚焦检查，不要求消费用户每改一篇文档就运行
主题内部测试或浏览器套件。

每个候选记录工具版本和源码身份，在 Starter 与三个不同维护站点上只读验证。前后
对比源码字节、模式与 Git 状态。原生新规则需要已审阅的合法/非法语料；成为默认阻断
前先修正误报。承诺增量速度前，应在同一当前站点基线上测量完整构建时间。功能正确
优先于检查项数量。

## 完成条件与发布证据 {#completion-and-release}

每阶段交付已实现行为、已知限制、聚焦测试、真实集成结果、更新的中英文契约/指南
和可审阅 diff。逐项记录需求及用例状态，不能因为某个汇总命令通过就自动关闭全部
需求。只有 R1–R8 及其必需验收用例满足，本 PRD 才算完成。

实现、本地验证、提交、归档和运行平台验收、公开分发、消费站采用、服务商部署与
公网内容验证分别报告。交叉编译不等于运行验收。缺少凭据或尚无公开下载地址不能
成为声称远程交付的理由，也不要求为此建设托管控制台。

受支持行为被接受后，进入归属 CLI 契约、使用指南和长期决策，再按现有生命周期
退役相应提案内容。本 PRD 不作为永久的第二份命令手册。

## 待决项与停止条件 {#decisions-and-stop-conditions}

将相对工作周转换为日历日期前，确认投入和开始日期。R1 决定支持的运行平台、审阅
记录的具体存储、首批原生规则和精确的兼容新增参数。这些是范围内的有限实现选择，
不应因此重开产品边界或等待整个主题发布。

文件保护或正确性工作超过估算时，把可选便利功能移后，不能删掉过期写入保护、真实
完成状态或普通 Hugo 兼容。多轮语料审阅仍无法可靠的规则保持建议级或移除。表单
无法保留源码字节的语法继续用文本模式。不能因为某个扩展值得尝试，就让它进入关键
交付路径。

## 决策日志 {#decision-log}

| 日期 | 记录 |
| --- | --- |
| 2026-10-03 | 根据当前 CLI 盘点与提供的功能目标创建草案，提出 R1–R8、可选扩展门禁、投入假设及可执行验收用例。本文不声称新增 CLI 能力、版本发布、消费站采用或部署已经完成。 |
| 2026-10-03 | R1 共享 Hugo 事实与检查政策通过本地归属/真实 Hugo 检查。稳定行为移入 [CLI 契约](/zh/docs/design/decisions/cli/#project-policy)和[指南](/zh/docs/start/cli/#project-policy)；[验收记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r1)分别跟踪最终报告刷新与中英文产物证据。R2–R8 及条件性扩展仍未完成，不声称公开分发、采用或部署。 |
| 2026-10-03 | R2 翻译范围/哈希审阅、有界原生规则和可见基线已使用共享保护文件计划。本地归属、真实 Hugo 与聚焦 race 门禁通过，最终消费站刷新和中英文文档验收仍在[记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r2)中待完成。已实现行为见[契约](/zh/docs/design/decisions/cli/#translations)与[指南](/zh/docs/start/cli/#translations)。R3–R8 仍未完成。 |
| 2026-10-03 | R2 最终语料与中英文文档门禁通过。R3 一次渲染的已检查导出、准确文件身份、两种服务商的保护 CI 计划、发布诊断和显式联网 HTTP 验证已通过各自本地门禁，包括自定义 workflow 发现。稳定行为移入[契约](/zh/docs/design/decisions/cli/#checked-artifacts)与[指南](/zh/docs/start/cli/#checked-artifacts)；准确证据与 A08–A10 结果归[维护记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r3)所有。R4–R8、最终 A18 运行时/归档刷新及 Darwin amd64 仍未完成。不声称公开分发、托管 CI 已执行、采用或部署。 |
| 2026-10-03 | R4 受支持本地范围通过冻结 Go/vet、真实 Hugo/race 及准确二进制只读 Starter/文档站/PIG/repository 门禁。同一未修改许可证 Starter 组合全部配置/语言；普通 new/editor/snippet 流程与源码/外部输入保护，以及可读有界升级视图和 alias/输出回归保护均通过。稳定行为归[契约](/zh/docs/design/decisions/cli/#authoring)与[指南](/zh/docs/start/cli/#authoring)，准确 A11/A12 证据和边界归[记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r4)。R5–R8、最终 A18 运行时/归档刷新及 Darwin amd64 仍未完成。未公开发布、写消费站/采用或部署。 |
| 2026-10-03 | R5 修正冻结 Go/vet、实际 Hugo/race 及精确二进制四消费者只读门禁已完成。全部站点 inspect/context 完成；历史影响与移动阻断保持明确。受保护规范源码/渲染门禁及阶段接受仍待完成。稳定行为归[契约](/zh/docs/design/decisions/cli/#project-graph)与[指南](/zh/docs/start/cli/#project-graph)所有；[记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r5)标识 A13/A14/context 证据、缓存模块修正及精确保护记录。R6–R8、workspace A15 与最终 A18 保持未完成；没有消费者写入或部署。 |
| 2026-10-03 | R5 受支持检查/影响/有界上下文与受保护移动范围在修正冻结归属门禁、精确二进制四消费者保护及首次晋升规范源码/渲染门禁后已本地接受。生产翻译检查仅保留已知 draft 发布文档缺失；独立不可发布分析的全部归属检查通过。稳定行为归[契约](/zh/docs/design/decisions/cli/#project-graph)与[指南](/zh/docs/start/cli/#content-moves)所有；[记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r5)保留精确结果及单独渲染后证据边界。A13/A14 受支持 CLI 范围通过；A15 context 通过，workspace/direct 一致仍归 R6。R6–R8 与最终 A18 未完成；没有发布、消费者写入/采用或部署。 |
| 2026-10-03 | R6 显式登记与有界可选工具候选已实现；聚焦工作区与修正实际协议试验通过，预备失败独立记录。最终运行时/语料/规范门禁及 A07/A15 阶段接受仍待完成，见 [R6 记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r6)。R7/R8 与最终 A18 未完成；无版本发布、消费者写入或部署。 |
| 2026-10-03 | R6 冻结 Go/vet、实际 Hugo/固定工具、归属 race 及精确二进制四消费者直接/汇总一致性与保护已验证。完成收据记录六个原始操作、repository 已有重复 ID 发现，以及不变原始输出上的驱动命令摘要修正；无需 CLI/Hugo 重跑或运行时修正。规范源码/渲染检查和显式 R6/A07/A15 阶段接受仍在[记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r6)中待完成。R7/R8/最终 A18 未完成；没有消费者源码写入、版本发布或部署。 |
| 2026-10-03 | R6 受支持显式登记与可选工具范围在冻结 Go/vet、实际 Hugo/固定工具、race、精确二进制四消费者一致性/保护及受保护规范源码/渲染门禁后已本地接受。A07 适配器与 A15 工作区/直接/context 受支持范围通过；[R6 记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r6)区分首次晋升渲染字节与本次渲染后状态/证据修订。R7/R8 与最终 A18 仍未完成；没有公开发布、消费者源码写入/采用或部署。 |

| 2026-10-03 | R7 只读内嵌 Studio 候选及鉴权回环视图已实现；冻结核心/浏览器及精确二进制四消费者验收在声明范围内完成；受保护规范晋升/渲染及显式 R7/A16 接受仍待完成。R1–R6 保持已接受；R8/最终 A18 未完成；没有消费者写入、公开发布或部署。 |

| 2026-10-03 | R7/A16 受支持只读 Studio 在冻结累计已执行案例/浏览器证明、精确二进制四消费者一致性/保护及受保护规范源码/渲染门禁后已本地接受。首次晋升渲染字节与本次渲染后状态修订保持不同；完整调用失败与明确局部预览未完成保持可见。R1–R7 已接受；R8/最终 A18 未完成；没有公开发布、消费者写入/采用或部署。 |

| 2026-10-03 | R8 CLI/显式 Editor 源码编辑候选已实现；默认 Studio 保持只读。纯核心/流式输出复制聚焦证据已记录，失败浏览器试验保留。最终冻结公共/浏览器/消费者/规范门禁及 A17 阶段接受仍待完成，见 [R8 记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r8)。R1–R7 保持已接受，R8/最终 A18 未完成；没有公开发布或消费者写入/部署。 |

| 2026-10-03 | R8/A17 受审阅 CLI/显式 Editor 受支持本地范围在修正冻结完整归属/浏览器、精确二进制四消费者提议一致性与源码保护，以及受保护首次规范晋升/实际渲染后接受。R1–R8 已本地接受；[R8 记录](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#r8)独立绑定首次渲染与本次状态字节，并保留所有失败试验、原生发现与必需局部预览未完成。最终 A18 当前 Linux/归档验证仍未完成；没有消费者写入、公开发布、采用或部署。 |

| 2026-10-04 | 当前后端完整性修正、刷新归属/Hugo/race、未变运行时复用的四消费者保护与三个声明运行时/归档验证通过，见[带日期完成增补](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/#a18)。有限 R1–R8 实现本地完成；需求记录/锚点保留，退出活动导航，稳定行为归属契约/指南。最终规范渲染生命周期验证独立，E1–E4 未启动；没有公开发布、采用或部署。 |

---

反链：

- [CLI](/zh/docs/cli/)
- [2026-10-03 CLI 维护](/zh/docs/design/research/2026-10-03-cli-maintenance-acceptance/)