企业官网建设流程全解析

HOP（Open HWP）是一款开源的跨平台 HWP/HWPX 文档编辑器，支持在 macOS、Windows、Linux 三大系统上打开、编辑和打印韩文 HWP 文档。在这个产品背后，有一类高频出现的工程动作——升级上游引擎。本文结合 HOP 的真实仓库实践，讲清楚一页纸的1-Pager 问题陈述法如何让这类跨平台重构变得风险可控。

🧩 什么是 1-Pager 问题陈述法

1-Pager（一页纸文档）是一种固定结构的问题陈述：动手写代码之前，先用同一个八段式模板回答"要做什么、不做什么、怎么验证、如何回滚"：

它的价值不在"写了文档"，而在于编码之前就强制团队把边界和回滚路径说清楚。HOP 把这类文档统一放在 docs/operations/ 目录，覆盖了 bug 修复、上游引擎升级、功能集成到版本发布的完整周期。

⚠️ 为什么跨平台重构天然高危

HOP 的文档解析与渲染核心是上游引擎rhwp，以只读 git submodule（third_party/rhwp）形式引入，HOP 只在其上覆盖一层"薄壳"：

• apps/desktop/：Tauri 桌面壳、原生文件读写、保存/导出/打印、多窗管理
• apps/studio-host/：编辑器宿主层，负责覆盖与组合上游 UI
• apps/desktop/rhwp-adapter/：唯一直接调用 Rust 引擎的桥接层

这种"升级引擎、不 fork 引擎"的策略，让每次引擎升级都可能冲击 HOP 的覆盖层：

1. 边界漂移——上游已经修好的问题，HOP 里可能还留着一份重复的 workaround；
2. 跨平台回归——在 macOS 上通过的行为，在 Linux 输入法或 Windows 环境下可能悄悄失效；
3. 中途不可逆——升级做到一半失败，仓库停在半更新状态。

为此，HOP 在 docs/architecture/UPSTREAM.md 里写死所有权规则：上游目录只读，HOP 只拥有产品代码；每一处覆盖都必须在 config/rhwp-studio-overrides.json 中登记策略（extension / fork / contribution）和存在理由。而 1-Pager，就是这套规则在每次具体任务上的落地。

🎯 1-Pager 中隐藏的四个风险控制机制

1. Non-goals：先砍掉范围

1-Pager 里最反直觉的章节是 Non-goals。rhwp v0.8.7 升级 1-Pager（docs/operations/rhwp-v0.8.7-integration-1pager.md）明确写出：不修改上游源码、不顺手引入英文 UI / Word 导出 / 自动保存等新功能、不默认启用渲染后端切换。少了这一节，一次"升级"很容易滚雪球成一次"重构产品"——这正是许多重构失控的根源。

2. Constraints：把跨平台不变量写明

约束章节把跨平台开发的不变量写成一句话，例如：保留 macOS、Windows、Linux 三端行为；工具链版本与上游固定值一致（Node 24、pnpm、固定版本的 Rust 与 wasm-pack）；文件、PDF、打印等副作用只由原生桥接层拥有。

这些句子随后成为每份 diff 的审查依据。docs/operations/issue-85-table-input-rendering-1pager.md 中修复"表格单元格输入不刷新"的问题，就受两条约束约束：三端行为必须平台中立；事件数据不一致时必须回退到全量刷新。

3. Verification plan：自动验证与真实验证分开

1-Pager 要求在动手前列出验证清单，并诚实区分两类结果：

• 自动验证：上游契约测试、Studio/桌面单元测试、clippy、构建；
• 真实验证：打开真实 HWP 文档，验证保存重开、嵌套表格、韩文输入法、PDF 导出。

v0.8.7 升级 1-Pager 的完成记录是典型范例：34 个上游测试、145 个 Studio 测试、81 个桌面测试全部通过，但文中同时明确写"韩文输入法组合、Windows/Linux GUI 验证未执行，且合成文档的往返验证不能替代这些验证"。这种"未验证清单"，正是跨平台项目里防止"单机通过 = 三端通过"的幻觉的关键。

4. Rollback：恢复路径先于实现写

每个 1-Pager 都有 Rollback 章节，HOP 的惯例是：

• 升级工具失败时自动恢复 HOP 自有产物与上一个 submodule 提交，并原地保留失败状态；
• 禁止手动覆盖文件、git reset --hard、移动 tag 这类破坏性操作，统一以 docs/operations/RHWP_UPDATE.md 操作手册为准；
• 疑似新版回归时，用旧版本 checkpoint 做二分诊断，而不是直接回退仓库。

"先写逃生绳，再开始攀岩"——这就是把不确定的重构变成可恢复变更的机制。

🔍 实战复盘：rhwp v0.8.7 升级如何安全落地

按 docs/operations/rhwp-v0.8.7-integration-1pager.md 的完整流程，可以归纳为三步：

1. 边界预检：改代码之前先对照上游发布说明，建立"变化 → HOP 影响"对照表，提前发现上游 patch 来源从 Git 源切换为 vendor 路径，会导致升级工具直接停摆；
2. 单一回滚单元：submodule 指针、生成 WASM、两份 Cargo 清单与覆盖层 hash 基线作为同一个 candidate，由 scripts/update-rhwp-upstream.mjs 统一生成与恢复；
3. 边界防回归：8 个覆盖文件的 SHA-256 基线登记在 config/rhwp-studio-overrides.json 中，tests/rhwp-boundary.test.mjs 边界测试确保"上游变了但边界层没人审"的情况无法溜进发布。

最终结果：全部自动验证通过，引擎基线从 v0.8.4 平滑升至 v0.8.7，且保存、渲染、字体、打印等跨平台行为契约保持不变。

🚀 从单个任务到版本发布

1-Pager 不只服务于大重构。v0.4.5 发布 1-Pager（docs/operations/release-v0.4.5-1pager.md）里有两条很有"纪律感"的约束：

• tag 一旦推送永不移动，出问题就修复并向前发布新补丁版本；
• 未验证的问题（如剪贴板 issue #96）禁止在发布说明中被标为已修复。

从 docs/operations/issue-triage-0.4.0-1pager.md 的问题分诊，到 docs/operations/quicklook-extension-1pager.md 的 macOS Quick Look 预览扩展，HOP 的工程节奏始终一致：先陈述问题，再定边界与回滚，然后实现、验证，最后如实记录结果。

📌 小结：三步把 1-Pager 引入你的项目

1. 模板化：固定 Background / Problem / Goal / Non-goals / Constraints / Implementation / Verification / Rollback 八段，与代码一起归档在仓库中；
2. 边界化：有上游依赖的项目，把所有覆盖点登记进机器可校验的 manifest，并用 hash 基线 + 边界测试防止漂移；
3. 诚实化：完成记录中严格区分"自动验证过"与"真实验证过"，未验证项一律视为未完成。

对跨平台、多上游依赖的项目来说，1-Pager 不是文档开销，而是成本最低、收益最确定的保险。