从实验日志到可核验报告：云实验复盘助手的四状态设计

完成云实验后，最容易留下的材料通常是手册、几张截图和一段终端输出。把它们整理成报告时，我遇到一个很实际的问题：手册写着“执行成功”，并不表示这个步骤已经执行；命令返回正常，也不表示平台已经记录完成。

这次使用华为云码道 CodeArts 开发“云实验复盘助手”，我把这个问题变成了程序必须遵守的规则：计划、执行、检查和平台记录分别保存，任何一层的成功都不能替另一层作证。

本文使用 AI 辅助整理与校对，依据本次开发和验收记录撰写。文中的 JSON 和日志片段均为模拟数据，不代表真实云资源、证书或积分结果。

一、为什么需要四种状态

最初的输入设计包含 planned、executed、checked 和 platform_record 四个部分。它们分别回答四个问题：

这四层在代码中分别判定。例如，已经获取 HTTP 响应，可以支持某项检查；如果没有平台完成记录，报告仍然只能把最后一层写成“未验证”。

这样做的价值是保留不确定性。复盘报告应当帮助读者找到缺失的证据，而不是把缺失部分补成一个顺利完成的故事。

二、一个成功标记，需要配套证据

验收时发现，直接相信 result: "pass" 太宽松。输入者可能只是复制了模板，还没有填写真实检查结果。

下面的输入特意省略证据：

{
  "lab": {"name": "模拟服务检查"},
  "steps": [{
    "title": "检查服务响应",
    "planned": "访问服务并记录响应",
    "checked": {"result": "pass"},
    "platform_record": {"status": "completed"}
  }]
}

在这个版本的工具里，两处成功声明都会降为“未验证”。只有 pass 配合非空字符串 evidence，才显示检查通过；平台完成状态也需要自己的证据。

这里还有一个边界：程序只能验证证据字段是否存在、格式是否符合要求，不能自动证明证据真实。使用者仍需核对原始日志和平台页面。把这条限制写清楚，比把工具描述成“自动验真”更准确。

三、命令文本不能直接算作执行记录

另一个容易混淆的例子，是手册里的命令被填进了执行字段：

{"executed": {"command": "echo sample"}}

这只能说明提供了一条命令。工具不会据此认定已经执行。

本版本接受非空输出，或者“非空命令加整数退出码”作为执行记录。退出码为零也不会自动推导检查通过，因为命令是否正常结束和实验目标是否达到，是两个问题。

类型校验也必须明确。这个项目的回归测试专门覆盖了布尔值被误当作退出码的情况，避免一个 true 就满足整数退出码条件。

四、日志处理要同时避免漏删和误删

报告往往要分享，日志中的凭据需要隐藏。但粗糙的匹配同样会损坏材料。

这次补充了两组相反方向的测试：一组要求隐藏常见密码、访问密钥和授权头；另一组要求保留 tasks、mask、author 等普通字段。不能因为字段名碰巧包含相似字母，就把正常内容全部抹掉。

带引号和空格的模拟密码也是单独的测试场景。如果只遮住第一个单词，后半段仍会进入报告。

目前的实现只覆盖常见形式，不能保证识别任意自定义凭据。公开分享前，仍应预览生成结果，检查账号信息、内部地址和其他不适合公开的内容。

五、报告格式本身也要验证

真实日志可能包含竖线、HTML 文本和 Markdown 代码围栏。如果不处理，原本属于日志的一行文字可能变成报告标题，表格也可能错列。

本次修订对元信息和表格文本进行转义，日志则使用动态长度的代码围栏：当输入已经包含三个反引号时，外层使用更长的围栏包住它。目标是保留日志原文，同时让报告结构稳定。

此外，输出路径不能覆盖输入文件。读入失败、类型错误或写入失败应返回失败结果，而不是留下一个看似成功的报告。

六、让结论可以复现

当前版本有 7 项基础场景验证和 11 项回归验证，本次验收共 18 项通过。它们覆盖成功示例、证据不足、无效输入、常见凭据隐藏、格式处理、文件错误与输入保护。

项目中可用下面两条命令复现测试：

python3 tests/run_tests.py
python3 -m unittest discover -s tests -p 'test_*.py' -v

这些测试只能支持各自覆盖的行为，不能代表所有输入都正确，也不能替代平台审核。

同一个原则也适用于提交作品：收到 submitted 回执，说明提交请求已有记录；它不等于审核通过，更不能由此推断证书或积分已经到账。报告里把提交、审核和结果记录分别写清楚，后续排查才有依据。

对我来说，这个小工具最有用的部分，是让每个“完成”都有对应材料。缺少材料时，明确写“未验证”，下一次检查就知道该从哪里继续。