【句匠｜20】HarmonyOS ArkTS AppGallery 发布复查实战：核对包名、版本、设备、素材和离线声明

HarmonyOS 应用进入 AppGallery Connect 之前，最危险的并不是某一个字段忘填，而是多个事实来源彼此矛盾：源码里的包名是一套，上传包里的版本是另一套，商店勾选了平板但界面没有经过平板验证，宣传页写"完全离线"却又声明了网络权限。任何单项看起来都不复杂，组合起来却会让审核人员无法确认"这份素材描述的到底是不是这个包"。

本文以句匠项目 D:\huawei\one18-11 为对象，只使用当前工作区能够复核的源码、资源和本地构建产物。项目面向 HarmonyOS 5.0 及以上版本，实际构建配置为 compatibleSdkVersion 6.0.1(21)、targetSdkVersion 6.0.2(22)。文章不会把本地检查写成 AGC 后台已验证，也不会把已有 HAP 写成已经完成安装、启动、核心流程和卸载烟测。

一、先建立"发布事实表"，再打开 AGC

发布复查的第一步不是登录后台，而是把不依赖后台的事实先冻结。句匠当前可从源码直接得到以下基线：

复查项	本地事实	来源
应用名	句匠	`AppScope/resources/base/element/string.json`
Bundle Name	`com.jiaweikang.one18`	`AppScope/app.json5`
versionName	`1.0.0`	`AppScope/app.json5`
versionCode	`10000000`	`AppScope/app.json5`
入口模块	`entry`	`entry/src/main/module.json5`
入口 Ability	`EntryAbility`	`mainElement` 与 `abilities`
设备类型	phone、tablet、2in1	`deviceTypes`
权限	`ohos.permission.INTERNET`	`requestPermissions`
安装方式	随应用安装，非免安装	`deliveryWithInstall`、`installationFree`
首页入口	`pages/SplashPage`	`loadContent()`

这张表的价值在于区分"事实"和"填写动作"。例如，源码声明三种设备只是事实；AGC 是否已经勾选三种设备、是否给每种设备上传合规截图，仍要在后台逐项回读，不能由源码反推。

二、包名不是文案，它是应用身份

AppScope/app.json5 中的核心字段如下：

json5 复制代码

{
  "app": {
    "bundleName": "com.jiaweikang.one18",
    "versionCode": 10000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon_square",
    "label": "$string:app_name"
  }
}

发布时至少要核对四个位置：本地 bundleName、候选包解析结果、AGC 应用条目的包名、准备提交版本绑定的包。它们必须指向同一应用。仅凭文件名 entry-default-signed.hap 无法证明包名正确，因为文件名可以被改写，真正身份在包元数据里。

队列记录的 App ID 为 6917606389807278354，这可以作为自动化任务的目标标识，但本文没有登录 AGC 回读该 App ID 对应的当前页面，因此不声称后台绑定关系已在本次复查中确认。

三、版本号要同时满足"递增"和"可解释"

句匠当前源码是：

text 复制代码

versionName = 1.0.0
versionCode = 10000000

versionName 面向用户，versionCode 用于系统和分发平台判断升级关系。准备新版本时，不能只把 1.0.0 改成 1.0.1，也不能只替换宣传文案；必须让新的 versionCode 高于已发布版本，并重新构建、签名、解析候选包。华为官方的应用安装卸载与更新指导也明确指出，更新应用首先要更新 app.json5 中的 versionCode，再重新打包发布。

本地目录中存在一个签名 HAP，修改时间为 2026-05-26，大小约 19.6 MB。这个文件只能证明"磁盘上存在历史构建产物"，不能证明它就是当前源码生成的最终候选包。只要源码、资源、版本号或签名配置在产物生成后发生过变化，就应重新构建，不能沿用旧包。

四、设备类型要从声明走到可达性验证

句匠模块声明：

json5 复制代码

"deviceTypes": [
  "phone",
  "tablet",
  "2in1"
]

这意味着发布材料不能只准备一组手机截图便结束。源码确实包含 BreakpointSystem.register()，Index.ets 也监听 currentBreakpoint，并保留底部导航和侧边导航两套结构；HomePage.ets 还会在 lg 且页面宽度不小于 700vp 时使用网格布局。这些是多设备适配的实现证据。

但源码里还有一个值得复查的条件：

typescript 复制代码

if (this.currentBp === 'sm' ||
    this.currentBp === 'md' ||
    this.currentBp === 'lg') {
  // 底部导航
} else {
  // 侧边导航
}

如果断点系统只会产生 sm、md、lg，侧边导航分支就可能永远不可达。发布前必须用实际窗口宽度和断点输出验证，不能仅凭"代码写了侧栏"就宣称平板、2in1 已适配。

五、页面清单决定烟测范围

main_pages.json 当前登记 19 个页面，包括启动页、首页、题库详情、练习、考试结果、搜索、分类、学习统计、设置、每日打卡、段位、排行榜和 AI 纠错等。

发布烟测不需要平均点击每一个控件，但必须覆盖入口与关键路由：

冷启动进入 SplashPage，再到 Index。
五个主 Tab 均能进入，系统返回行为符合页面层级。
从首页进入题库、搜索、分类、每日打卡、段位、排行榜和 AI 纠错。
从题库进入练习，完成作答并到达结果页。
空数据、错误参数、重复点击和二次进入不会崩溃。
手机、平板、2in1 的核心操作都可达。

这份路由矩阵应与上一阶段的回归测试设计复用。发布复查不是重新发明测试，而是把已识别风险绑定到"即将上传的同一个候选包"。

六、应用名、模块描述与页面品牌要一致

句匠的应用级名称是"句匠"，入口 Ability 标签也是"句匠"，模块描述同样为"句匠"；首页标题显示"句匠 / Wordsmith"，副文案为"纠正错误 · 提升语感 · 让英语更地道"。这些内容目前没有明显的品牌冲突。

发布材料仍要避免两类夸大：

把题库中的模拟统计写成真实用户规模、学习效果或准确率。
把规则型 AI 纠错描述成已接入在线大模型服务。

源码事实应决定商店文案的边界。能展示某个功能入口，不代表后台服务、云同步或智能模型已经存在。

七、图标要核对"引用、像素、透明度、后台素材"四层

app.json5、module.json5、EntryAbility 图标和启动页图标都引用 $media:app_icon_square，资源文件为 1024×1024 PNG。实际读取结果是 RGB 模式，没有 Alpha 通道，因此不存在依赖透明背景的问题。这是一个良好的本地基础。

不过，包内图标和 AGC 应用信息图标属于两个展示面。复查时应确认：

包内实际图标仍是当前 1024×1024 版本。
启动页和桌面图标没有使用旧资源。
AGC 上传图标与包内品牌一致。
浅色、深色、圆角裁切和商店缩略图中仍清晰。
图标不冒充系统图标，也不包含难以辨认的小字。

本地资源合格不能替代后台预览回读，后台保存后的缩略图才是最终证据。

八、截图必须来自真实可达页面

截图不是装饰图，也不是功能愿望清单。句匠适合覆盖以下真实页面：

首页：品牌、今日挑战、快捷入口和题型分类。
题库页：实际题库卡片、章节与进度。
练习页：作答、解析和听音弹窗。
学习统计或错题页：本地数据闭环。
AI 纠错页：输入、空状态和规则纠错结果。

每张截图都要复查顶部状态栏、底部手势区、文字截断、数据真实性和设备画幅。若截图中展示了统计数字，应使用可解释的演示数据，不能把本地模拟数值包装成平台运营数据、PV、点赞或真实用户成绩。

九、"离线应用"不能只看有没有 HTTP 请求

对句匠源码执行聚焦检索，没有发现 fetch()、Axios、WebSocket 或普通 HTTP 客户端调用；用户学习数据由本地 UserDataManager 管理。这支持"核心学习数据本地保存""主要题库可离线使用"等有限表述。

但 module.json5 明确声明：

json5 复制代码

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  }
]

同时 PracticePage.ets 使用系统 TextToSpeech 能力，代码采用"尽力播放、失败仍显示发音文本"的降级策略。仅凭未发现普通网络请求，不能推导"应用绝不联网"或"完全不使用网络能力"。发布时更稳妥的描述是：

核心题库、练习记录和学习进度可在本地使用；听音功能调用系统语音合成能力，能力不可用时仍可查看发音文本。

是否保留 INTERNET 权限，应结合 TTS 在目标设备和目标 SDK 下的官方能力要求与实机行为验证，而不是为了迎合"离线"标签直接删除。

十、权限、隐私标签和文案要组成同一闭环

当前清单只看到 INTERNET，没有相机、麦克风、位置、通讯录、通知、登录和支付权限。源码中也没有发现账号、广告、推送、分析或 Web 组件证据。

因此 AGC 隐私标签不应凭经验勾选一长串数据类型，也不能因为"没有敏感权限"就完全跳过隐私复查。至少要核对：

Preferences 中保存哪些收藏、错题、笔记、进度和设置。
是否存在导出、云备份、账号同步或第三方 SDK。
清除数据入口是否与隐私说明一致。
网络权限的用途是否有准确说明。
商店文案是否声称离线、无数据收集或无网络。

如果后台已经托管隐私政策，还要回读公开链接和正文版本。项目目录中没有找到某个文件，不代表后台没有材料，也不代表后台材料仍与当前包一致。

十一、启动链路要核对资源和异常降级

EntryAbility.onWindowStageCreate() 会加载 pages/SplashPage，并在之前初始化用户数据、AppStorage 和断点系统。它还读取系统避让区，把顶部和底部高度保存到 AppStorage。

发布候选包需要验证：

text 复制代码

安装 -> 冷启动 -> SplashPage -> Index
     -> Preferences 初始化
     -> BreakpointSystem 注册
     -> 避让区监听
     -> 主页面可操作

如果窗口对象或避让区查询异常，源码会回退为 0 并记录日志；如果 loadContent 失败，当前实现只记录错误并返回。这意味着白屏风险不能由静态检查排除，必须在候选包上做冷启动和重复启动。

十二、状态栏、导航栏与底部安全区是审核可见问题

句匠通过 TYPE_NAVIGATION_INDICATOR 和 TYPE_SYSTEM 计算底部避让，bottomSafePadding() 取设计最小值与系统区域的较大者。主 Tab 导航高度由 Tab 高度和安全区共同组成，这比固定写死底部间距更可靠。

复查时仍要覆盖：

三键导航与手势导航。
横竖屏切换。
分屏和自由窗口缩放。
软键盘弹出后的输入页。
状态栏背景与深浅色图标。
2in1 鼠标和键盘可达性。

代码中强制 COLOR_MODE_LIGHT，因此不能在商店材料中宣称已完整支持系统深色模式。应验证系统切换深色后应用仍保持清晰的浅色方案，并确保系统栏图标可读。

十三、候选包必须重新建立可追溯证据

一个可提交候选包至少要记录：

text 复制代码

源码提交或快照
构建时间
bundleName
versionName / versionCode
target / compatible SDK
签名状态
文件大小
SHA-256
安装设备
安装、启动、核心流程、卸载结果

句匠当前磁盘上已有 entry-default-signed.hap，但其时间早于本次文章复查。正确动作不是把它直接认定为候选包，而是在版本和资源冻结后重新执行仓库规定的构建命令，再对新产物计算哈希并测试。

签名证书、Profile、私钥和密码属于敏感信息。复查只记录证书有效性、应用绑定和签名结果，不把密码、密钥内容或令牌写进日志、文章和队列。

十四、AGC 包选择比"上传成功"更关键

在 AGC 中上传包成功，只代表服务器接收了文件。正式提交前还要返回版本页面，从候选列表中选择本次目标包，按版本、上传时间、大小和解析出的应用身份核对后保存。

自动化记录至少要区分：

text 复制代码

local_built
package_uploaded
package_selected
version_saved
submitted
pre_reviewing
approved
rejected

这些状态不能互相替代。尤其不能把"上传成功"写成"发布成功"，也不能把草稿、预审核或审核中写成公开上架。

十五、设备勾选与素材分组必须同步

如果包支持 phone、tablet、2in1，而 AGC 应用信息只勾选 phone，就会产生包能力和商店信息不一致；反过来，如果后台勾选了某类设备，却没有对应截图和真实适配，也会形成审核风险。

发布复查可按以下矩阵执行：

设备	包声明	布局证据	运行验证	素材
phone	已声明	底部导航	待候选包烟测	手机截图
tablet	已声明	断点与网格	待候选包烟测	平板截图
2in1	已声明	响应式页面	待鼠标键盘验证	对应素材

"待验证"比虚构一个"通过"更有价值，因为它能阻止自动化越过发布门槛。

十六、功能描述必须匹配真实交互

首页展示"AI 纠错""排行榜""每日打卡"等入口，但发布描述要继续向下验证实现：

AI 纠错是规则与本地逻辑，不能包装成已接入云端大模型。
排行榜若为本地演示数据，不能宣传成真实全网排名。
每日打卡是本地记录，不能声称多端云同步。
听音使用系统 TTS，不能声称内置真人音频库。
学习统计来自本地记录，不能声称平台级学习分析。

审核人员会从截图和交互进入功能。文案越具体，越需要源码和运行结果支撑。

十七、发布复查分成五层更容易定位责任

建议把复查责任拆成五层：

Identity：应用名、Bundle Name、App ID、版本与签名。
Package：SDK、模块、权限、设备类型、页面和候选包哈希。
Runtime：安装、启动、路由、数据、TTS、异常和卸载。
Material：图标、截图、简介、更新说明、隐私政策和标签。
AGC：上传、选包、保存、提交、审核与公开页回读。

只有第五层能够证明平台状态。前四层通过，最多说明"具备提交条件"，不能提前生成公开 URL、发布时间或审核结果。

十八、可自动化的检查与必须人工停下的边界

可以自动化的内容包括：

解析 JSON5 中的包名、版本、设备和权限。
检查图片尺寸、格式、Alpha 通道和哈希。
构建候选包并记录产物信息。
跑本地硬检查、单元测试和静态扫描。
在已登录会话中填写可逆字段并回读保存状态。

遇到验证码、短信、扫码、安全校验、法律确认、付费确认、账号权限异常或最终不可逆提交时，应立即停止。自动化不能绕过验证，也不能保存 Cookie、令牌、证书密码或身份信息。

十九、句匠当前可以确认什么，不能确认什么

本次静态复查可以确认：

包名为 com.jiaweikang.one18。
版本为 1.0.0 / 10000000。
目标 HarmonyOS SDK 为 6.0.2，兼容 6.0.1。
声明 phone、tablet、2in1。
声明 INTERNET 权限。
包内图标为 1024×1024、不含 Alpha 通道。
有响应式、避让区、本地数据和 TTS 降级代码。
磁盘上存在历史签名 HAP。

本次不能确认：

AGC 当前应用条目、包绑定和素材保存状态。
历史 HAP 与当前源码完全一致。
三类设备的候选包烟测已经通过。
TTS 在所有目标设备都可用。
后台隐私政策和标签已与当前版本同步。
版本已提交、审核通过或公开发布。

二十、提交前的最小验收清单

最后把动作压缩成一张可执行清单：

text 复制代码

[ ] 冻结 bundleName、versionName、versionCode
[ ] 重新构建并解析候选包
[ ] 记录候选包 SHA-256 与签名验证结果
[ ] phone / tablet / 2in1 安装与启动
[ ] 覆盖主 Tab、练习、结果、设置和异常路径
[ ] 验证状态栏、底部安全区、缩放和输入法
[ ] 核对 INTERNET 权限与 TTS 说明
[ ] 图标、截图、简介、更新说明均来自真实版本
[ ] 隐私政策、隐私标签、权限和本地存储一致
[ ] AGC 上传后重新选中目标包并保存
[ ] 最终提交前人工确认目标应用和版本
[ ] 提交后按真实状态记录，不伪造公开链接

AppGallery 发布复查的核心不是"把表单填满"，而是让源码、候选包、运行结果、商店素材和平台状态形成一条可追溯证据链。对句匠而言，当前最需要保留的审慎结论是：核心学习流程具有本地能力，源码未发现普通 HTTP 请求，但因为存在 INTERNET 声明和系统 TTS 调用，不应直接宣传为"完全离线"；三种设备也必须在新候选包上完成真实烟测后，才能把"支持"升级为"已验证"。

AI 辅助声明：本文由 AI 协助梳理结构与文字表达，所有项目能力、配置、路径和风险结论均以句匠真实源码及本地可复核产物为边界；未执行的 AGC、真机、审核和公开发布状态均未写成已完成。

参考资料

https://developer.huawei.com/consumer/cn/app/submit/

https://developer.huawei.com/consumer/cn/doc/doccenter-getting-started/application-package-install-uninstall

https://developer.huawei.com/consumer/cn/doc/doccenter-feature-dev/bpta-app-icon-configuration

华为开发者联盟：《提交 HarmonyOS 应用与鸿蒙 APP》
华为 HarmonyOS 开发者：《应用安装卸载与更新开发指导》
华为 HarmonyOS 开发者：《应用图标配置与开发》