【句匠20】HarmonyOS ArkTS AppGallery 发布复查实战核对包名、版本、设备、素材和离线声明HarmonyOS 应用进入 AppGallery Connect 之前最危险的并不是某一个字段忘填而是多个事实来源彼此矛盾源码里的包名是一套上传包里的版本是另一套商店勾选了平板但界面没有经过平板验证宣传页写“完全离线”却又声明了网络权限。任何单项看起来都不复杂组合起来却会让审核人员无法确认“这份素材描述的到底是不是这个包”。本文以句匠项目本地句匠工程脱敏路径为对象只使用当前工作区能够复核的源码、资源和本地构建产物。项目当前构建配置为compatibleSdkVersion 6.0.1(21)、targetSdkVersion 6.0.2(22)。文章不会把本地检查写成 AGC 后台已验证也不会把已有 HAP 写成已经完成安装、启动、核心流程和卸载烟测。证据边界本文“本地事实”来自本轮对 AppScope、entry 模块、页面清单、入口 Ability、断点系统、本地存储、TTS 代码、图标像素和历史 HAP 的静态复核发布步骤同时对照华为官方文档。本轮没有重新构建或解析候选包没有进行设备烟测也没有登录 AGC 回读后台字段与审核状态。一、先建立“发布事实表”再打开 AGC发布复查的第一步不是登录后台而是把不依赖后台的事实先冻结。句匠当前可从源码直接得到以下基线复查项本地事实来源应用名句匠AppScope/resources/base/element/string.jsonBundle Name当前 Bundle Name已脱敏AppScope/app.json5versionName1.0.0AppScope/app.json5versionCode10000000AppScope/app.json5入口模块entryentry/src/main/module.json5入口 AbilityEntryAbilitymainElement与abilities设备类型phone、tablet、2in1deviceTypes权限ohos.permission.INTERNETrequestPermissions安装方式随应用安装非免安装deliveryWithInstall、installationFree首页入口pages/SplashPageloadContent()这张表的价值在于区分“事实”和“填写动作”。例如源码声明三种设备只是事实AGC 是否已经勾选三种设备、是否给每种设备上传合规截图仍要在后台逐项回读不能由源码反推。二、包名不是文案它是应用身份AppScope/app.json5中的核心字段如下{ app: { bundleName: 当前 Bundle Name已脱敏, versionCode: 10000000, versionName: 1.0.0, icon: $media:app_icon_square, label: $string:app_name } }发布时至少要核对四个位置本地bundleName、候选包解析结果、AGC 应用条目的包名、准备提交版本绑定的包。它们必须指向同一应用。仅凭文件名entry-default-signed.hap无法证明包名正确因为文件名可以被改写真正身份在包元数据里。队列记录的 App ID 为当前 App ID已脱敏这可以作为自动化任务的目标标识但本文没有登录 AGC 回读该 App ID 对应的当前页面因此不声称后台绑定关系已在本次复查中确认。三、版本号要同时满足“递增”和“可解释”句匠当前源码是versionName 1.0.0 versionCode 10000000versionName面向用户versionCode用于系统和分发平台判断升级关系。准备新版本时不能只把1.0.0改成1.0.1也不能只替换宣传文案必须让新的versionCode高于已发布版本并重新构建、签名、解析候选包。华为官方的应用安装卸载与更新指导也明确指出更新应用首先要更新app.json5中的versionCode再重新打包发布。本地目录中存在一个签名 HAP修改时间为 2026-05-26大小为 18.73 MiB约 19.64 MB。这个文件只能证明“磁盘上存在历史构建产物”不能证明它就是当前源码生成的最终候选包。只要源码、资源、版本号或签名配置在产物生成后发生过变化就应重新构建不能沿用旧包。四、设备类型要从声明走到可达性验证句匠模块声明deviceTypes: [ phone, tablet, 2in1 ]这意味着发布材料不能只准备一组手机截图便结束。源码确实包含BreakpointSystem.register()Index.ets也监听currentBreakpoint并保留底部导航和侧边导航两套结构HomePage.ets还会在lg且页面宽度不小于 700vp 时使用网格布局。这些是多设备适配的实现证据。但源码里还有一个值得复查的条件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明确声明requestPermissions: [ { name: ohos.permission.INTERNET } ]同时PracticePage.ets使用系统 TextToSpeech 能力代码采用“尽力播放、失败仍显示发音文本”的降级策略。仅凭未发现普通网络请求不能推导“应用绝不联网”或“完全不使用网络能力”。发布时更稳妥的描述是核心题库、练习记录和学习进度可在本地使用听音功能调用系统语音合成能力能力不可用时仍可查看发音文本。是否保留INTERNET权限应结合 TTS 在目标设备和目标 SDK 下的官方能力要求与实机行为验证而不是为了迎合“离线”标签直接删除。十、权限、隐私标签和文案要组成同一闭环当前清单只看到INTERNET没有相机、麦克风、位置、通讯录、通知、登录和支付权限。源码中也没有发现账号、广告、推送、分析或 Web 组件证据。因此 AGC 隐私标签不应凭经验勾选一长串数据类型也不能因为“没有敏感权限”就完全跳过隐私复查。至少要核对Preferences 中保存哪些收藏、错题、笔记、进度和设置。是否存在导出、云备份、账号同步或第三方 SDK。清除数据入口是否与隐私说明一致。网络权限的用途是否有准确说明。商店文案是否声称离线、无数据收集或无网络。如果后台已经托管隐私政策还要回读公开链接和正文版本。项目目录中没有找到某个文件不代表后台没有材料也不代表后台材料仍与当前包一致。十一、启动链路要核对资源和异常降级EntryAbility.onWindowStageCreate()会加载pages/SplashPage并在之前初始化用户数据、AppStorage 和断点系统。它还读取系统避让区把顶部和底部高度保存到 AppStorage。发布候选包需要验证安装 - 冷启动 - SplashPage - Index - Preferences 初始化 - BreakpointSystem 注册 - 避让区监听 - 主页面可操作如果窗口对象或避让区查询异常源码会回退为 0 并记录日志如果loadContent失败当前实现只记录错误并返回。这意味着白屏风险不能由静态检查排除必须在候选包上做冷启动和重复启动。十二、状态栏、导航栏与底部安全区是审核可见问题句匠通过TYPE_NAVIGATION_INDICATOR和TYPE_SYSTEM计算底部避让bottomSafePadding()取设计最小值与系统区域的较大者。主 Tab 导航高度由 Tab 高度和安全区共同组成这比固定写死底部间距更可靠。复查时仍要覆盖三键导航与手势导航。横竖屏切换。分屏和自由窗口缩放。软键盘弹出后的输入页。状态栏背景与深浅色图标。2in1 鼠标和键盘可达性。代码中强制COLOR_MODE_LIGHT因此不能在商店材料中宣称已完整支持系统深色模式。应验证系统切换深色后应用仍保持清晰的浅色方案并确保系统栏图标可读。十三、候选包必须重新建立可追溯证据一个可提交候选包至少要记录源码提交或快照 构建时间 bundleName versionName / versionCode target / compatible SDK 签名状态 文件大小 SHA-256 安装设备 安装、启动、核心流程、卸载结果句匠当前磁盘上已有entry-default-signed.hap但其时间早于本次文章复查。正确动作不是把它直接认定为候选包而是在版本和资源冻结后重新执行仓库规定的构建命令再对新产物计算哈希并测试。签名证书、Profile、私钥和密码属于敏感信息。复查只记录证书有效性、应用绑定和签名结果不把密码、密钥内容或令牌写进日志、文章和队列。十四、AGC 包选择比“上传成功”更关键在 AGC 中上传包成功只代表服务器接收了文件。正式提交前还要返回版本页面从候选列表中选择本次目标包按版本、上传时间、大小和解析出的应用身份核对后保存。自动化记录至少要区分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、版本与签名。PackageSDK、模块、权限、设备类型、页面和候选包哈希。Runtime安装、启动、路由、数据、TTS、异常和卸载。Material图标、截图、简介、更新说明、隐私政策和标签。AGC上传、选包、保存、提交、审核与公开页回读。只有第五层能够证明平台状态。前四层通过最多说明“具备提交条件”不能提前生成公开 URL、发布时间或审核结果。十八、可自动化的检查与必须人工停下的边界可以自动化的内容包括解析 JSON5 中的包名、版本、设备和权限。检查图片尺寸、格式、Alpha 通道和哈希。构建候选包并记录产物信息。跑本地硬检查、单元测试和静态扫描。在已登录会话中填写可逆字段并回读保存状态。遇到验证码、短信、扫码、安全校验、法律确认、付费确认、账号权限异常或最终不可逆提交时应立即停止。自动化不能绕过验证也不能保存 Cookie、令牌、证书密码或身份信息。十九、句匠当前可以确认什么不能确认什么本次静态复查可以确认包名为当前 Bundle Name已脱敏。版本为1.0.0 / 10000000。目标 HarmonyOS SDK 为 6.0.2兼容 6.0.1。声明 phone、tablet、2in1。声明INTERNET权限。包内图标为 1024×1024、不含 Alpha 通道。有响应式、避让区、本地数据和 TTS 降级代码。磁盘上存在历史签名 HAP。本次不能确认AGC 当前应用条目、包绑定和素材保存状态。历史 HAP 与当前源码完全一致。三类设备的候选包烟测已经通过。TTS 在所有目标设备都可用。后台隐私政策和标签已与当前版本同步。版本已提交、审核通过或公开发布。二十、提交前的最小验收清单最后把动作压缩成一张可执行清单[ ] 冻结 bundleName、versionName、versionCode [ ] 重新构建并解析候选包 [ ] 记录候选包 SHA-256 与签名验证结果 [ ] phone / tablet / 2in1 安装与启动 [ ] 覆盖主 Tab、练习、结果、设置和异常路径 [ ] 验证状态栏、底部安全区、缩放和输入法 [ ] 核对 INTERNET 权限与 TTS 说明 [ ] 图标、截图、简介、更新说明均来自真实版本 [ ] 隐私政策、隐私标签、权限和本地存储一致 [ ] AGC 上传后重新选中目标包并保存 [ ] 最终提交前人工确认目标应用和版本 [ ] 提交后按真实状态记录不伪造公开链接AppGallery 发布复查的核心不是“把表单填满”而是让源码、候选包、运行结果、商店素材和平台状态形成一条可追溯证据链。对句匠而言当前最需要保留的审慎结论是核心学习流程具有本地能力源码未发现普通 HTTP 请求但因为存在INTERNET声明和系统 TTS 调用不应直接宣传为“完全离线”三种设备也必须在新候选包上完成真实烟测后才能把“支持”升级为“已验证”。二十一、源码配置和候选包必须双向核对发布事实表不能只从工程文件抄一遍。工程配置回答“准备构建什么”候选包解析回答“实际构建出了什么”。二者都正确才允许把包交给设备烟测和 AGC。若只看源码可能错拿旧产物若只看文件名又可能无法发现版本、包名或设备声明与当前工程不一致。{ sourceSnapshot: commit-or-archive-id, bundleName: redacted-but-compared, versionName: 1.0.0, versionCode: 10000000, devices: [phone, tablet, 2in1], artifactSha256: calculated-after-build, builtAt: recorded-after-build }这份清单不保存签名口令、私钥、Cookie 或令牌。自动化只比较经过脱敏的身份字段并记录哈希、时间与验证结论任何秘密都应留在受控凭据系统中。二十二、多设备支持要设置可阻断的验收矩阵当前模块声明了 phone、tablet、2in1但断点系统只产生sm、md、lg而 Index 对这三个值全部进入底部导航分支。因此“存在侧边栏代码”不是它会运行的证据。发布门禁应把设备、窗口和输入方式拆开验证面最小场景失败时动作phone竖屏、横屏、手势导航阻止提交并修复安全区tablet竖屏、横屏、分屏核对断点与导航形态2in1自由窗口、鼠标、键盘补齐焦点与可达性共同路径启动、五个 Tab、练习、结果记录首个失败路由任何一类设备没有运行证据都应在发布报告中保持“待验证”而不是由deviceTypes自动升级成“已适配”。二十三、离线声明应分成三个强度等级“没有发现普通 HTTP 请求”只说明静态检索没有命中常见客户端调用不等于运行时绝不联网。句匠还声明了INTERNET系统 TTS 也会在离线引擎失败后尝试在线引擎。因此商店文案应选择能够被证据支撑的强度表述所需证据当前是否足够核心学习可离线使用题库与记录本地化断网核心流程可达源码支持仍需设备断网烟测不依赖账号和云同步无登录、云端存储和第三方账号链路静态检查支持完全不联网无网络权限、无在线兜底、运行流量验证当前不支持更稳妥的发布说明是描述能力而不是给应用贴绝对标签核心题库、收藏、错题、笔记和进度保存在本地听音能力依赖系统语音服务可用性不足时提供文字降级。二十四、平台状态必须由保存后的回读证明华为官方发布入口明确区分上传软件包、通过基础合法检测、在发布版本中选取软件包和提交审核。自动化日志也应使用同样的状态粒度避免看到上传成功就提前宣称发布完成。source_checked → local_built → package_parsed → device_smoke_passed → package_uploaded → package_selected → version_saved → submitted → reviewing / approved / rejected每次页面跳转后重新获取当前版本和目标包保存后再回读可见值。若出现验证码、短信、扫码、安全验证或最终法律确认应停在对应状态把控制权交还给用户不能通过重试或隐藏接口绕过。二十五、复查报告要能回答“这条结论来自哪里”一份可交接报告至少包含五列检查项、期望值、实际值、证据来源、状态。包名来自源码和包解析双证据版本还要与在架版本比较设备支持来自声明、布局和运行三类证据素材来自文件检查与后台预览平台状态只能来自当前 AGC 页面或接口回读。对句匠而言当前可以形成的是本地静态基线应用名、版本、SDK、设备声明、权限、页面、图标和历史产物都已核对候选包重建、设备烟测、AGC 选包、素材保存、隐私标签和审核状态仍必须保持未验证。把这些空白明确留出才是发布复查真正防止误提交的价值。参考资料华为开发者联盟在应用市场分发华为 HarmonyOS 开发者应用安装卸载与更新开发指导华为 HarmonyOS 开发者应用图标AI 辅助声明本文在人工核对句匠工程配置、入口、页面、断点、本地存储、TTS、图标和历史构建产物并对照华为官方发布资料后使用 AI 辅助整理结构、润色表达并生成示意图未执行的构建、设备、AGC 和审核状态均未写成已完成。CSDN-SERIES:ALL-163185768