【寻迹校园 HarmonyOS NEXT 实战 50】从单元测试到 AGC 审核：HarmonyOS 项目的五级证据与最终交付清单

m0_74969023

162人浏览 · 2026-08-28 10:35:54

m0_74969023 · 2026-08-28 10:35:54 发布

【寻迹校园 HarmonyOS NEXT 实战 50】从单元测试到 AGC 审核：HarmonyOS 项目的五级证据与最终交付清单

本章导读：这是“寻迹校园 HarmonyOS NEXT 实战”系列第 50 篇，也是阶段性收官篇。一个 HarmonyOS 项目很容易出现证据越级：Node 测试通过被写成真机通过，BUILD SUCCESSFUL 被写成应用可用，FunctionComponent 打开被写成 AI 参数交接成功，AGC“准备提交”被写成审核中。本文把交付证据划分为 Contract、Build、Runtime、Capability、Platform 五级，并以 2026-08-28 的当前项目状态给出逐级证明、反证、风险和最终验收清单。

HarmonyOS 项目五级证据原创封面图

上图是原创证据金字塔，不是 AGC 或 DevEco Studio 截图。越往上越依赖真实环境与外部状态，下层通过不能自动让上层变绿。

一、为什么要把证据分级

软件交付中最危险的句子往往不是“失败”，而是范围过大的“已经通过”。例如：

纯规则断言通过，不代表数据库设备集成通过；
ArkTS 编译通过，不代表签名包能安装；
首页能打开，不代表小艺能力可用；
小艺能回复，不代表候选摘要自动传入；
APP 已上传，不代表已提交审核；
预审中，不代表正式审核通过或上架。

五级证据模型的目的，是让每个结论只覆盖它真实证明的范围。

二、Level 1：Contract 规则与合约证据

Contract 层验证确定性规则、数据边界、状态迁移和接口契约。寻迹校园当前包括：

六维筛选 AND 语义与时间边界；
Repository 返回克隆、私密证明不进入公开列表；
认领、交接、举报状态机；
小艺候选最多 3 条、240 字和二次脱敏；
本机剪贴板只写不读的源码合约。

这一级常用 Node assert、静态扫描和数据样例，运行快，适合每次修改后回归。

三、Contract 层的反证

即使所有断言绿色，以下结论仍然没有被证明：

RelationalStore 在真实设备成功建库和迁移；
系统 Photo Picker 返回真实 URI；
ArkUI 页面不会白屏；
HAP/HSP 可以安装；
Agent 或 AGC 平台可用。

Contract 负责“规则是否符合预期”，不负责“平台是否执行这些规则”。

四、Level 2：Build 编译、打包与签名证据

Build 层验证项目在指定 SDK、JBR、hvigor、product 和 build mode 下能否产生产物。至少记录：

实际命令；
type check 结果；
HAP/HSP/APP 任务；
signed/unsigned 区分；
版本号、构建号；
产物路径、大小、时间和 SHA-256；
签名 Profile 类型。

项目的 scripts/build-app.ps1 使用 DevEco JBR 与 SDK，执行完整 assembleApp。

五、Build 层的反证

BUILD SUCCESSFUL 不能证明：

当前设备已安装新包；
HSP 与 HAP 版本组合正确；
Ability 冷启动成功；
系统 Kit 权限和账号满足；
正式分发签名可普通侧载；
AGC 接受了这个 APP。

构建成功是必要条件，不是发布完成的同义词。

六、Level 3：Runtime 设备运行证据

Runtime 层从真实设备或明确标注的模拟器开始。标准预检是：

hdc list targets -v
hdc shell "echo write_ok > /data/local/tmp/codex_write_test && cat /data/local/tmp/codex_write_test && rm /data/local/tmp/codex_write_test"

预检通过后，安装同一次构建的 signed HSP/HAP，强制停止旧进程，冷启动 EntryAbility，读取新 PID、前台状态和第一条真实错误，再执行目标用户路径。

七、Runtime 层要记录哪些场景

寻迹校园的核心运行验收包括：

首次空库冷启动；
发布丢失/拾得记录；
本地候选召回与解释；
认领核验和重复提交门禁；
固定交接点、一次改期、双方确认；
举报去重、受理、隐藏/驳回；
冷启动持久化；
断网、长文本、暗色模式和权限拒绝。

一次“首页截图”不能替代完整用户路径。

八、模拟器、真机和历史证据要分开

模拟器适合布局、导航和部分本地数据流程；相册、Agent Framework Kit、账号、分发策略等能力通常需要真机。历史真机记录仍有价值，但必须保留设备类型、API、日期、包哈希和验证范围。

2026-08-28 当天 HDC 没有连接目标，因此 Runtime 级结论为 not run。项目曾有 API 24 真机冷启动、业务闭环与 HSP/HAP 联合安装证据，但它们不会被冒充成当天结果。

九、Level 4：Capability 系统能力与云能力证据

Capability 层专门验证相机、相册、定位、剪贴板、网络、AI Agent 等能力。它比一般 Runtime 更严格，因为还依赖权限、账号、地区、平台关联和系统版本。

对寻迹校园的小艺能力，至少拆成：

isAgentSupport；
FunctionComponent 可见；
系统小艺界面拉起；
目标智能体标题一致；
候选摘要交接；
当前输入得到当前回复；
失败时原生候选回退。

十、Capability 级最典型的证据越级

项目历史上已经出现：系统小艺成功打开，但 FunctionOptions.queryText 没有自动显示。若只记录“FunctionComponent 拉起成功”，就会掩盖参数交接失败。

因此当前结论是：

Agent 支持性与系统拉起：历史 passed
目标智能体可见回复：历史 passed
queryText 自动交接：failed
显式复制/粘贴/发送：历史 passed
原生候选回退：passed

五项结论同时存在，没有一项可以删除另一项。

十一、Level 5：Platform 外部平台证据

Platform 层包括小艺开放平台、AppGallery Connect、比赛提交平台和内容发布平台。它们的状态来自外部系统，必须按页面回读区分：

本地准备完成；
已上传；
已绑定版本；
准备提交；
已提交；
预审中；
审核中；
审核通过；
已上架。

任何前一状态都不能自动写成后一状态。

十二、AGC 当前状态如何准确表达

截至项目 2026-08-27 的最新回读记录：

分类和标签已保存；
1.0.2 (1000002)、构建版本 3 的 APP 已上传并绑定；
商店文案和 3 张真实真机截图已保存；
菜单和版本页显示 1.0.2 准备提交；
最终“提交审核”未执行。

所以准确表述是“发行资料和版本草稿已准备，尚未提交审核”，不能写“AGC 审核中”或“应用已发布”。

十三、小艺平台状态也要注明来源

工作流 V6 在 2026-08-17 预览通过并重新提交；用户于 2026-08-20 确认智能体显示已上架，真机同日完成目标智能体拉起和可见回复。

本文准备时没有重新登录平台独立回读，因此“已上架”应注明为用户确认状态，而真机能力则引用本地历史证据。来源透明比一句模糊的“平台已完成”更可信。

十四、五级证据不是线性打勾

五级模型存在依赖，但不是“低级全过，上级自动通过”。例如 Contract 和 Build 可以当天通过，Runtime 因设备未连接而 not run；Capability 仍可引用历史真机证据，但不能升级为当天通过；Platform 可能停在准备提交，与本地构建完全独立。

因此交付状态更适合矩阵，而不是一个总分。

十五、2026-08-28 当前状态矩阵

证据级别	当前结果	证据	不能推出
Contract	passed	四组本地测试全过	真机数据库/Kit 通过
Build	passed	完整 APP 增量构建成功	当天安装、商店发布
Runtime	not run	当天无 HDC 目标	当前包已真机运行
Capability	historical mixed	拉起/显式复制通过，自动 queryText 失败	所有设备账号均支持
Platform	prepared, not submitted	1.0.2 准备提交	审核中、已上架

这个矩阵是文章发表日的项目证据边界，不是永久状态。

十六、五级证据金字塔如何落地

HarmonyOS 最终交付五级检查地图原创图

上图把规则、构建、设备、能力和平台拆成五条独立通道。绿色表示证据已具备，黄色表示待执行或来源受限；只有对应交付目标要求的通道都满足，最终门禁才能放行。

十七、最终交付清单：Contract

需求边界与不可承诺项写入文档；
状态机前置条件和副作用有自动化；
私密字段不进入公开 DTO、日志或 Prompt；
关键 Repository 返回隔离对象；
时间、重复提交、空值和错误路径有用例；
测试调用生产实现而不是规则副本；
失败命令保留第一条真实错误。

十八、最终交付清单：Build

记录 DevEco、SDK、JBR、hvigor 和 product；
type check、HSP、HAP、APP 任务结果明确；
clean 与增量构建不混写；
signed/unsigned 产物分开；
版本号、构建号与发布草稿一致；
产物生成时间、大小和 SHA-256 已记录；
签名路径、密码和证书私钥未进入公开材料。

十九、最终交付清单：Runtime

hdc list targets -v 有目标；
/data/local/tmp 写入预检通过；
同一次构建的 HSP/HAP 联合安装；
强制停止后冷启动成功；
新 PID 和前台 Ability 已记录；
核心路径、空态、错误态和持久化通过；
无崩溃、freeze、panic 或未处理异常；
真机、模拟器与未运行项分别标注。

二十、最终交付清单：Capability

系统版本与能力支持性检查；
权限、登录、隐私协议、网络和地区条件；
真实能力界面可见；
输入参数在用户界面真实出现；
新会话回复可归因于本次输入；
不支持、拒绝和断网有降级；
AI 输出不自动获得业务授权；
自动交接失败与显式交接成功分别记录。

二十一、最终交付清单：Platform

目标账号、应用、bundle 和版本核对；
APP 上传成功并回读解析信息；
分类、标签、文案、截图和隐私资料已保存；
最终提交前获得用户明确确认；
提交后回读预审/审核状态；
驳回时下载真实报告并原版本修复；
不把准备提交、审核中和已上架混写；
比赛材料与商店材料分别归档。

二十二、比赛项目还要增加一层“陈述验收”

竞赛演示常见风险不是功能完全不可用，而是讲解超出证据。例如单机角色模拟被说成真实多用户平台、应用内消息被说成系统推送、固定测试数据被说成线上数据库。

最终演示稿应逐句检查：

“可以演示”还是“生产可用”；
“本机持久化”还是“多端同步”；
“用户确认”还是“平台独立回读”；
“历史真机通过”还是“当前版本当天通过”；
“准备提交”还是“已提交审核”。

真实边界不会削弱项目，反而能体现工程判断。

二十三、如何组织最终证据包

建议按日期和层级归档：

artifacts/
  contract/       测试输出与规则矩阵
  build/          命令、产物清单、哈希、签名摘要
  runtime/        HDC、安装、冷启动、PID、场景记录
  capability/     Kit 支持性、权限、真实输入输出
  platform/       上传、版本绑定、提交与审核回读

敏感文件不进入公开仓库；公开报告只保留脱敏摘要和必要哈希。证据文件名包含日期和版本，避免后来拿错旧截图或旧包。

二十四、发布前的停止条件

出现以下情况应停止并请求确认或补证据：

目标版本、账号或 bundle 不一致；
需要新增权限、签名、SDK 或平台服务；
当天无设备却要求声称真机通过；
APP 上传版本不是验收版本；
审核按钮将触发不可逆外部提交；
文章、截图或日志包含隐私与签名信息；
外部状态只有旧记忆，没有可接受的当前来源。

停止不是拖延，而是保护发布真实性。

二十五、本章能证明什么

2026-08-28 本章准备过程中，四组本地测试为 passed，完整 APP 增量构建为 passed；当天 HDC 设备预检为无目标，因此安装和冷启动为 not run。小艺能力引用日期明确的历史混合证据，AGC 引用 2026-08-27 的最新“1.0.2 准备提交”记录。

本章不能证明当天真机运行、当前平台审核状态已经变化、AGC 已提交或应用已上架。如果后续发生外部操作，必须更新对应 Platform 证据，不能回改低层结果冒充完成。

二十六、系列收官总结

从第 1 篇项目拆解到第 50 篇交付证据，“寻迹校园 HarmonyOS NEXT 实战”始终围绕同一条主线：把页面、状态、数据、系统能力、AI 增强和外部发布拆成可验证的工程边界。

最终最值得保留的不是某一段 ArkTS 代码，而是五级证据纪律：Contract 证明规则，Build 证明产物，Runtime 证明设备行为，Capability 证明真实系统能力，Platform 证明外部提交与审核状态。只有这样，BUILD SUCCESSFUL 才不会被误写成“已经上线”，比赛演示也能经得起追问。