• 设计契约

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

背景与证据

原 CLI 路线图已接受独立 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 也尚未实现。首批增量由这些发现确定。

产品目标与用户

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

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

功能取舍

范围与非目标

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

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

共享项目事实与检查政策

此范围已本地接受。下文保留原始提案需求作为历史；当前行为与参数归 CLI 契约所有。

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

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

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

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

翻译维护

此范围已本地接受。下文保留原始提案需求作为历史；当前行为与参数归 CLI 契约所有。

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

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

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

原生内容规则与问题基线

此范围已本地接受。下文保留原始提案需求作为历史；当前行为与参数归 CLI 契约所有。

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

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

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

已验证发布产物与 CI

此范围已本地接受。下文保留原始提案需求作为历史；当前行为与参数归 CLI 契约所有。

保留当前 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 夹具验证这些行为，无需部署到服务商。

创作与升级助手

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

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

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

影响分析与安全内容修改

此受支持范围已本地接受。下文保留原始提案需求作为历史；当前行为、边界与参数归 捕获事实契约、 移动契约及 指南所有。

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

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

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

工作区与可选工具

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

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

R6 已接受本地边界

显式登记与可选适配器的受支持 R6 范围已本地接受。稳定字段和限制见 登记契约与 工具契约，用户步骤归属 指南。下述已接受 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 记录。 当前 A18 运行时/归档验证通过；Darwin amd64 保持实验/未验证。聚焦测试不能推断版本发布、消费者采用、源码写入或部署。

只读 Oink Studio

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

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

R7 候选边界

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

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

安全 Markdown 编辑

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

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

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

R8 已接受编辑边界

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

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

交付顺序与排期

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

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

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

条件性扩展

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

架构与兼容

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

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

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

验收用例与归属检查

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

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

完成条件与发布证据

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

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

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

待决项与停止条件

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

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

决策日志

| 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 记录。R1–R7 保持已接受，R8/最终 A18 未完成；没有公开发布或消费者写入/部署。 |

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

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