鸿蒙 PC Markdown 编辑器质量工程：证据驱动的技术验证

鸿蒙 PC Markdown 编辑器质量工程：证据驱动的技术验证

本文讨论如何把自动化、模拟器、真机、性能和故障证据组织成可审计的质量结论，避免用一次演示替代阶段验证。完整示例代码：https://gitcode.com/VON-/codex_md_oh。

评审不是功能演示

鸿蒙 PC Markdown 编辑器的阶段评审不应只看“能否输入一行文字”。演示可以避开异常路径，也很难回答性能是否可复现。一个可用的阶段评审至少需要四类证据：

1. 产物证据：Debug 与 Release HAP 都能由脚本重复构建。
2. 自动化证据：可自动化的编辑、安全、布局和打包约束进入测试。
3. 设备证据：文件选择器、ArkWeb、IME 和进程内存在模拟器或真机实测。
4. 遗留风险：不达标和未测项必须写入报告，不用“基本可以”隐去。

把关键行为写成自动化证据

下面是实际安全预览测试中的核心断言。它不只检查标题和粗体是否渲染，还检查脚本节点不存在且全局副作用没有发生；同一用例还验证预览可见性与模式切换：

test('在源码、分栏和预览模式下安全渲染 Markdown',async({page})=>{constsource='# HarmonyOS Markdown\n\nHello **world**.\n\n<script>window.unsafeScriptExecuted=true</script>';awaitpage.evaluate((content)=>{consthost=windowasunknownasEditorTestWindow;host.OhMarkdownEditor.setDocument(content);host.OhMarkdownEditor.setMode('split');},source);awaitexpect(page.locator('#workspace')).toHaveAttribute('data-mode','split');awaitexpect(page.locator('#preview h1')).toHaveText('HarmonyOS Markdown');awaitexpect(page.locator('#preview strong')).toHaveText('world');awaitexpect(page.locator('#preview script')).toHaveCount(0);expect(awaitpage.evaluate(()=>(windowasunknownasEditorTestWindow).unsafeScriptExecuted)).toBeUndefined();});

代码来源：web-editor/tests/editor.spec.ts

当前 Playwright 套件共 14 项，覆盖：

• 安全预览和三种视图模式。
• 中文输入、撤销、重做和显式保存快照。
• 切换文档时清理撤销/重做历史。
• 撤销回已保存基线时清除修改状态。
• 5MiB 大文档降级模式。
• 720px 窄窗口的垂直分栏。
• 1.5 秒恢复快照和恢复文档脏状态。
• CRLF 文档的编辑器行分隔语义。
• 安全 HTML 导出与打印媒体 DOM。
• 生产包不引用外部 JavaScript 或 CSS 子资源。

阶段状态必须反映真实证据

一次实际技术评审没有采用“全部完成”或“整体失败”的二元判断，而是根据证据给出条件通过：

• ArkUI + ArkWeb + CodeMirror 纵切已经完成输入、预览、Bridge、打开、保存和大文件降级，没有发现必须更换编辑器内核的阻断问题。
• 1MiB 完整进程组 PSS 为 324.7MiB，比 250MiB 正式目标高 29.9%，仍处于预先允许的 30% 技术验证容差内。
• HTML 安全导出、打印页面和 HarmonyOS Print Kit 编译链路已经通过。
• 真机多窗口、系统 PDF 产物、本地图片资源解析和用户 URI 故障注入被明确带入 Alpha 硬门槛。

因此该轮技术评审采用“条件通过并进入 Alpha”的结论。条件通过不是降低标准，而是确认架构值得继续投资，同时把尚未满足的正式指标保留为后续不可跳过的验收项。

鸿蒙 PC 设备闭环截图

下图为一份中文 Markdown 在鸿蒙 PC / 2in1 模拟器中保存后重新打开的设备证据。标签、编辑内容、Opened状态和字数来自完整的文件闭环，不是静态样式图。

一个可执行的评审清单

1. 固定 DevEco Studio、SDK、设备、HAP 哈希和测试文档。
2. 运行 Release 构建和 Web 自动化，保留命令与结果。
3. 在鸿蒙 PC 真机重复性能测试，使用 P95 而不是最优单次数据。
4. 对文件取消、只读、磁盘写满和异常中断做故障注入。
5. 将每项判定标记为通过、条件通过或不通过，并把遗留项带入下一阶段计划。

评审结论、实现审查、测试批次和进度变化需要进入可追溯记录。评审的价值不是制造一个“已完成”标签，而是用可复现证据决定架构是否值得继续投资，并确保遗留风险有明确的下一阶段归属。

技术验证要围绕可证伪假设

“ArkUI 加 ArkWeb 适合做编辑器”范围太大，几乎无法一次证明。更可执行的方式是把它拆成可以失败的假设：ArkWeb 能离线加载 CodeMirror；中文输入、撤销和重做正确；Bridge 不需要每次按键传全文；10MiB 文档在降级后仍可编辑；用户 URI 能完成打开保存闭环；恶意 Markdown 不会在预览执行。

每个假设都要定义反证条件。例如 10MiB 文档如果只能显示、不能保存，就不能算大文件能力通过；预览过滤<script>但允许javascript:链接，也不能算安全边界完成。把失败条件提前写下，可以避免实现后根据结果临时降低标准。

阶段评审的对象不是功能数量，而是这些关键假设剩余的不确定性。低风险的按钮和样式可以继续迭代，高风险的数据安全、输入法、内存与权限必须在扩展功能前获得证据。

建立需求到证据的追踪矩阵

一条结论应能反向追到需求、实现、测试和设备记录。可以用简化矩阵管理：

矩阵中出现空格不是坏事，它直接暴露缺失证据。真正危险的是把“代码存在”同时当作自动化和设备通过。每种证据回答不同问题：实现可以审查意图，测试验证可重复行为，设备验证平台集成，性能数据验证非功能目标。

证据强度存在层级

从弱到强可以大致分为：代码阅读、单次手工观察、自动化重复、模拟器集成、真机多次采样、可控故障注入和长期使用数据。层级不是说自动化一定比人工好，而是证据要匹配声明。

纯函数的 BOM 检测，用自动化夹具比人工打开十个文件更可靠；系统中文输入候选窗，真机人工与录屏比浏览器合成事件更可信；性能目标需要 Release 真机 P95，单张截图没有意义；保存断电安全需要故障注入，正常保存一百次也不能证明异常路径。

报告必须写清证据边界。可以说“鸿蒙 2in1 模拟器上强制停止后恢复通过”，不能简化成“所有鸿蒙 PC 崩溃恢复可靠”。精确表述不会削弱成果，反而让下一步验证可安排。

自动化测试应保护稳定契约

编辑器自动化不应只按照 DOM 结构点按钮，因为界面重构会产生大量无意义失败。更值得保护的是稳定业务契约：

• 设置文档后，源码与预览来自同一内容。
• 文档变更产生脏状态，撤销回保存基线清除脏状态。
• 新文档替换旧文档后撤销历史隔离。
• 恶意 Markdown 不产生脚本、危险链接和全局副作用。
• 大文档进入保护模式，Split/Preview 不再执行。
• 恢复快照在节流窗口后产生，并携带正确 revision。
• CRLF 文档经过编辑后保持配置的行分隔符。
• 导出 HTML 独立、净化且不引用在线资源。

这些契约与用户数据正确性直接相关，即使按钮位置和颜色变化也不应失效。界面端到端测试再覆盖关键工作流，两层组合会比全部依赖截图点击更稳定。

性能结论必须带上下文

“10MiB 在 345ms 打开”至少还缺少包类型、设备、样本数、冷暖状态和测量区间。性能报告应包含：

1. HAP 类型和 SHA-256。
2. 设备型号、系统、模拟器宿主机或真机状态。
3. 测试文档大小、结构和摘要。
4. 开始与结束测量点。
5. 运行次数、P50、P95、最大值。
6. 完整进程组 PSS、峰值与稳定值。
7. 大文件模式开启的具体能力变化。

当前 1MiB 总加载 83ms、10MiB 345ms 是模拟器技术证据；1MiB 完整进程组 324.7MiB 高于 250MiB 正式目标。把两类数据同时放入结论，才能避免用一项优势覆盖另一项风险。

条件通过要绑定硬性后续项

条件通过不是“先过再说”。它必须包含三个元素：为什么可以继续、哪些指标尚未满足、在什么节点前必须补齐。例如混合架构核心纵切已经运行，没有发现编辑模型阻断问题，所以可以进入 Alpha；但真机 IME、内存正式目标和保存故障注入未完成，因此这些项目不能在公开测试前继续延期。

遗留项要有优先级和归属。使用“以后优化”“有时间再测”会让风险不断滚动。更好的写法是：问题、影响、当前缓解、负责人/阶段、验收方法。例如“用户 URI 保存不是原子替换，当前以沙箱旧版本备份缓解；在 Alpha 数据安全闸门前完成强杀和短写故障注入”。

如果后续节点仍然没有证据，应重新判定阶段状态，而不是复制上一轮条件通过。

缺陷严重度由用户影响决定

编辑器缺陷不应只按修复难度排序。数据丢失、静默改写和安全越权属于最高优先级，即使触发概率低；侧栏像素偏差通常可以延后。一个实用分类是：

• P0：可能丢失/覆盖用户文件、执行不可信代码、无法启动或大范围崩溃。
• P1：核心编辑、打开、保存、恢复、输入法在常见场景不可用。
• P2：非核心功能错误、可绕过的性能或交互问题。
• P3：视觉细节、文案和低频一致性问题。

严重度还要结合可检测性。保存失败并提示用户通常比“显示 Saved 但磁盘没写入”轻，后者是静默数据风险。评审时应优先寻找静默错误，因为演示最难暴露它们。

设备证据需要固定元数据

一张应用截图能证明界面在某次运行出现，但无法单独证明包版本、操作步骤或结果可重复。设备记录应附带：

• 日期、设备/模拟器型号和系统版本。
• DevEco Studio、SDK 和 HAP 哈希。
• 前置文件、授权状态和网络条件。
• 精确操作步骤，包括等待时间和强制停止方式。
• 期望、实际结果、截图或录屏文件。
• 是否重复执行、是否发现偶发差异。

图片必须来自应用内部并展示与用例相关的状态。系统文件选择器可以作为辅助证据，但不能替代应用内“打开后内容正确”“保存后状态清洁”或“恢复提示出现”的结果画面。

失败用例和正常用例同样重要

正常路径证明系统在理想条件下连通，失败路径决定它是否值得用户托付资料。文件编辑器至少需要取消、无权限、外部修改、短写、空间不足、进程强停、恢复记录损坏和超大文件等测试。

故障注入要控制变量。测试保存途中强杀时，需要知道强杀发生在备份前、写入中还是 fsync 后；否则一次“文件没坏”可能只是没有打中危险窗口。可以在内部测试版本加入阶段钩子或人工暂停点，但这些钩子不能进入正式行为，也不能改变被测代码路径。

发现失败后，报告不仅记录现象，还应保存最小复现、日志、文件前后哈希和恢复能力。修复完成后用同一夹具回归，并加入自动化或设备清单防止复发。

评审会议应围绕差异而非朗读文档

有效评审前，参与者已经能看到 PRD、执行计划、测试报告和已知风险。会议重点应是：目标与证据是否匹配、失败项是否被正确分级、条件通过是否有足够理由、下一阶段是否存在不可接受的数据风险。

可以按以下顺序进行：

1. 重申本阶段要证伪的关键假设。
2. 展示自动化、构建和设备结果摘要。
3. 单独讨论未达目标、未测和偶发问题。
4. 检查架构边界是否仍成立，有无扩大复杂度的临时补丁。
5. 给出通过、条件通过或不通过判定。
6. 把条件与下一阶段具体任务绑定并记录。

演示只用于帮助理解证据，不能取代报告。一次现场操作失败也不应立刻否定全部自动化，而要判断环境、复现和影响。

可复用的技术评审模板

目标：本阶段要验证的技术假设 范围：包含项、排除项、架构边界 环境：提交、HAP 哈希、SDK、设备、测试语料 实现：关键模块和不可逆决策 自动化：命令、用例数、通过/失败 设备：步骤、结果、截图或录屏 性能：测量点、样本、P50/P95、内存 风险：未达标、未测试、已知限制、缓解措施 判定：通过 / 条件通过 / 不通过 后续：负责人、阶段、退出条件

模板的重点是强迫结论带环境和边界。只写“测试通过”或“功能完成”无法支持技术决策。

发布前质量闸门清单

• 每项核心需求都能追到实现、自动化和适当的设备证据。
• Debug 与 Release 构建由脚本重复生成，候选 HAP 有摘要。
• 用户文件相关功能完成正常、取消、冲突和故障路径。
• 中文 IME、物理键盘、触控板和自由窗口在目标真机验证。
• 性能使用固定语料与 P95，内存包含完整 ArkWeb 进程组。
• 不可信 Markdown 在预览、导出和打印三条路径都经过安全回归。
• 条件通过项有硬性截止阶段和可执行验收，不无限延期。
• 未测项明确写出，不用模拟器结果推断所有真机行为。
• 高优先级缺陷按用户数据和安全影响排序。
• 每个结论都能由另一名工程师按记录重复。

证据驱动的质量工程并不会拖慢编辑器开发。它把争论从“感觉已经很好”转成“哪个假设还有多大不确定性”，让资源优先投入到用户数据、输入正确性、安全和平台兼容这些真正决定产品上限的地方。

退出条件应在阶段开始前冻结

阶段执行中可以因为新信息补充用例，但不能在结果不理想时悄悄删除原目标。开始前冻结核心退出条件、允许容差和证据类型；需要变更时单独记录理由、影响和批准，而不是直接覆盖旧文本。

例如正式内存目标与技术验证容差是两个数。测得 324.7MiB 后可以依据已定义容差给出条件通过，却不能把正式目标改成 330MiB。下一阶段仍保留原目标或通过新的产品/架构决策正式调整。

冻结条件也防止范围无限增长。阶段外的新想法进入待办，不阻塞已定义假设；发现的数据安全阻断则可以升级为退出条件，因为它改变继续开发的风险。

回归责任要跟随能力而不是个人

每个核心能力应有长期测试归属：编辑内核变更触发 IME/撤销回归，文件服务变更触发格式与故障回归，渲染依赖变更触发安全与导出回归，工作台变更触发窗口和焦点回归。责任写在工程规则或测试配置，不依赖某位开发者记得。

发现缺陷时先补能稳定复现的测试，再修复并验证。设备偶发问题无法立即自动化，也要进入设备清单和回归批次。修复关闭时附同一环境下的失败前、通过后证据。

随着功能扩大，测试可以按标签选择，但核心数据安全套件始终作为发布硬门槛，不能为了缩短流水线跳过。

证据保存要兼顾可追溯与隐私

文本报告、测试命令和无敏感截图可以版本化；HAP、大文件夹具、长录屏和原始性能日志进入制品存储并用哈希引用。真实用户文档、目录和账号信息不得作为公共证据。

证据设置保留期限：公开版本的评审与关键产物长期保留，日常调试日志定期清理。截图文件名包含能力和状态，不只写“最新”；报告中使用相对路径或制品 ID，迁移后仍可找到。

删除过期材料前确认没有未关闭缺陷引用。安全载荷和故障夹具应保留为最小无敏感版本，便于未来回归。

从阶段评审过渡到发布评审

技术阶段可以接受条件通过，公开发布需要更严格：所有 P0/P1 关闭，数据安全和安全预览硬门槛通过，目标鸿蒙 PC 真机矩阵完成，签名升级和回滚可执行，隐私与许可证准备好。

发布评审还要检查支持能力：用户遇到恢复提示、文件冲突或导出失败时是否有可理解文案和诊断；已知限制是否公开；回滚版本是否兼容新沙箱数据。技术可运行不等于可运营。

Alpha、Beta、正式版可以有不同门槛，但名称不能替代条件。每个渠道写清用户范围、允许风险、数据备份建议和停止发布触发器。

评审结论也需要复盘

进入下一阶段后，应检查上一轮条件通过项是否按期关闭、当时的性能预测是否准确、哪些测试真正发现了问题、哪些材料成本高却没有提供判断价值。复盘结果用于调整下一轮证据组合。

如果某类缺陷总在设备端晚发现，应把相关模拟器或契约测试前移；如果截图很多但无法绑定 HAP，应改进元数据；如果自动化频繁不稳定，应先修测试基础设施。质量系统本身也要通过反馈持续改进。

成熟评审不是文档数量越来越多，而是更早发现高影响问题，用更少但更强的证据作出决定。

质量结论要区分事实、推断与计划

“模拟器中十次强杀恢复成功”是事实；“真机大概率相同”是推断；“下个阶段补真机”是计划。三者不能合并成“恢复已完全通过”。报告把事实放在结果，推断写明依据与不确定性，计划绑定责任和退出条件。

同样，代码审查发现保存顺序合理只是设计证据，不能推断磁盘写满一定安全；一次真机 PDF 生成成功也不能推断所有字体与分页。精确分类能让读者知道结论强度。

停止条件保护项目免于错误扩张

除通过条件外，还应定义停止或回退条件：出现不可恢复文件损坏、中文输入无法稳定、ArkWeb 内存无法控制、安全模型必须开放过宽权限，均暂停功能扩张并重新评估架构。停止不是项目失败，而是技术验证发挥作用。

若问题有明确缓解，可以缩小范围继续，例如大文档关闭预览；若缓解会违反产品底线，例如静默截断文件，则不能用来换取进度。停止条件让团队在投入更多成本前保留选择。

用户验收与技术验收互补

技术测试证明正确性和边界，真实用户试用验证工作流是否高效、状态是否理解、错误是否可处理。Alpha 反馈应使用专用或已备份文档，明确已知限制，收集任务耗时和困惑点而非用户正文。

用户觉得“保存不放心”可能暴露状态文案或响应问题，即使底层测试通过也值得修正；用户觉得预览慢则与性能数据结合定位。主观反馈不替代安全与字节验证，但能发现技术指标没有覆盖的体验缺口。