01 把包名、版本号和 release 签名先做了预检，02 又把权限、隐私政策和三方 SDK 的披露关系收成了一张矩阵。到了 03，代码本身反而不是主角了。

真正进入 AppGallery Connect 版本信息页后，发布负责人开始面对另一类问题：图标、截图、应用描述、新功能、语言和内容分级，这些展示信息和当前构建到底是不是同一个版本。

这类问题看起来偏运营，实际很适合工程化。原因很简单：截图可能来自 1.2.0，应用描述已经写成 1.3.0，新功能又引用了一个尚未上线的页面；中文简介没超限，但英文语言没补；手机素材已经更新，平板素材却还留着旧界面。

AppGallery Connect 当前的 HarmonyOS 应用发布文档已经把本地化信息拆得很清楚：应用全量介绍必填，中文简短介绍有字符上限，新功能描述也有版本信息页的长度约束；截图、介绍视频、宣传视频按支持设备配置，手机和平板共享同一组素材入口。ReleaseGuard 03 就围绕这些“可以自动核对的事情”继续往前走。

本轮固定数据：

taskId:
release_20261002_03

defaultLocale:
zh-CN

configuredLocales:
zh-CN / en-US

localeComplete:
2 / 2

appName:
ReleaseGuard

zhBriefIntro:
应用发布预检助手

zhBriefChars:
8 / 17

zhFullIntroChars:
612 / 8000

zhNewFeaturesChars:
126 / 500

assetGroup:
phone_tablet

phoneTabletScreenshots:
4

promoVideoCount:
0

iconHash:
7d4a11c8

screenshotSetHash:
0e6bd2f4

contentRatingConfigured:
true

ratingSnapshot:
rating_20261002_03

metadataMismatch:
0

assetMissing:
0

checks:
9 / 9

status:
LISTING_READY

一、03 先解决“商店信息和构建版本不是一套”的问题

我最开始整理上架素材时，文件夹是这样：

store-assets/
├─ icon.png
├─ screenshot_01.png
├─ screenshot_02.png
├─ intro.md
└─ whats-new.md

看起来很清楚，但最大的问题是：这些文件没有任何版本身份。

只要有人手动替换了一张图，或者复制了上一版的 whats-new.md，流水线并不知道。

所以 ReleaseGuard 给商店素材也建立了 Snapshot：

export interface ListingMetadataSnapshot {
  taskId: string

  defaultLocale: string
  configuredLocales: string[]

  appName: string

  briefIntro: string
  fullIntro: string
  newFeatures: string

  assetGroup: string

  iconHash: string
  screenshotSetHash: string

  screenshotCount: number
  promoVideoCount: number

  contentRatingConfigured: boolean
  ratingSnapshotId: string
}

这里最重要的字段不是文案，而是：

taskId
iconHash
screenshotSetHash
ratingSnapshotId

它们把“这一组市场信息”绑定到当前发布上下文里。

这样 01 的包体报告、02 的隐私报告和 03 的素材报告就不再是三个孤立页面，而是同一个 release_20261002_xx 发布链逐步补全。

二、中文简短介绍不能等上传以后再数

当前 AppGallery Connect 的 HarmonyOS 应用本地化信息文档明确给出了长度约束：

全量介绍：
最多 8000 字符

中文简短介绍：
最多 17 字符

其他语言简短介绍：
最多 80 字符

中国大陆新功能：
最多 500 字符

本轮：

中文简短介绍：
应用发布预检助手
8 / 17

全量介绍：
612 / 8000

新功能：
126 / 500

ReleaseGuard 不需要等到浏览器表单报红。

检查器可以直接完成：

export class LocalizedMetadataAudit {
  checkZhCN(
    brief: string,
    full: string,
    whatsNew: string
  ): CheckItem[] {
    return [
      {
        key: 'ZH_BRIEF',
        passed: brief.length <= 17,
        message: `${brief.length}/17`
      },
      {
        key: 'ZH_FULL',
        passed: full.length <= 8000,
        message: `${full.length}/8000`
      },
      {
        key: 'ZH_WHATS_NEW',
        passed: whatsNew.length <= 500,
        message: `${whatsNew.length}/500`
      }
    ]
  }
}

这里的目标不是替 AppGallery Connect 做最终字符计数，而是把最确定的长度规则前移到构建阶段。

三、语言完整性要按“版本”检查，而不是按“曾经配过”检查

当前配置语言：

zh-CN
en-US

两种语言都显示：

2 / 2

我不只检查：

en-US 目录存在

还检查：

appName
briefIntro
fullIntro
newFeatures

当前版本有没有对应内容。

因为“语言存在”与“本次版本信息完整”完全不是一回事。

如果中文 1.3.0 已经写了：

新增发布门禁与素材校验

英文还保留：

What's new in 1.2.0

技术上语言没缺，版本语义却已经错位。

所以 ReleaseGuard 还会把：

versionName
metadataRevision
localeRevision

一起写进报告。

四、图标和截图也应该有可比较的 hash

03 里我没有把图像识别搞得很复杂。

第一步只做最稳定的东西：

iconHash:
7d4a11c8

screenshotSetHash:
0e6bd2f4

团队发布清单里会保存“当前批准素材”的 hash。

新构建跑预检时，如果图标或截图集合变化：

ASSET_CHANGED

不是直接失败，而是进入人工确认。

因为素材变化本身可能是正常的，但发布负责人应该知道：

这次提交的商店截图已经不是上一次确认过的那组。

这种检查比肉眼打开文件夹翻四张图可靠得多。

五、手机和平板共享素材组，工具里也只维护一个 source of truth

AppGallery Connect 当前的 HarmonyOS 应用本地化资料说明中，手机和平板共享同一个素材入口。

所以本轮：

assetGroup:
phone_tablet

screenshots:
4

ReleaseGuard 不再分别维护：

phone/
tablet/

两套重复文件。

而是：

phone_tablet/
├─ 01.png
├─ 02.png
├─ 03.png
└─ 04.png

如果以后支持 PC / Vision 等其他设备，再增加对应设备资产组。

这样文件目录本身就和市场侧设备素材分组保持同样语义。

六、截图数量通过不代表截图内容一定合规

这一篇工具只做：

文件存在
集合 hash
设备素材组
命名规则
版本关联

不会自动宣称：

截图一定符合审核内容要求

真正视觉内容还要人工确认：

是不是当前版本真实界面
有没有水印
有没有夸张文案
有没有错误品牌素材
有没有展示尚未开放能力

ReleaseGuard 能做的是：

减少漏图
减少旧图
减少错版本

不能代替内容审核。

这种边界必须在发布工具里写清。

七、内容分级不应该由 ReleaseGuard 自己“算一个年龄”

AppGallery Connect 版本信息页包含内容分级配置。

但 03 不会自己根据页面关键词算：

3+
12+
18+

然后当成官方结果。

ReleaseGuard 只检查两件事：

本次版本是否已经完成内容分级配置

本次分级配置是否有对应 snapshot

当前：

contentRatingConfigured=true
ratingSnapshot=rating_20261002_03

这表示内容分级材料已经纳入发布上下文。

真正分级结果仍以 AppGallery Connect 当前问卷和市场结果为准。

八、内容分级 Snapshot 也要防止“应用内容变了，问卷没重做”

假设 1.3.0 新增了：

用户生成内容
社交功能
付费内容

但 rating snapshot 还是 1.2.0 的。

即使 AppGallery Connect 页面里“已经配置过”，团队也应该重新人工确认。

所以 RatingSnapshot 会保存：

ratingRevision
featureFlagsHash
reviewedAt

只要应用发布功能标签发生变化：

RATING_NEEDS_REVIEW

而不是继续用旧快照自动绿灯。

03 当前没有触发：

metadataMismatch=0

九、9 项检查怎么组成

本轮 9 项：

1 默认语言存在

2 所有配置语言完整

3 中文简短介绍未超 17

4 全量介绍未超 8000

5 新功能未超 500

6 phone/tablet 素材组存在

7 截图数量符合团队发布计划

8 icon / screenshot hash 与批准素材一致

9 内容分级 snapshot 已配置

全部通过：

9 / 9

才进入：

LISTING_READY

这个状态只代表：

市场展示元数据已经进入可提交状态。

不代表最终审核通过。

十、DevEco 里要把“长度”和“hash”同时看见

开发图：

HiLog：

taskId=
release_20261002_03

locales=
2/2

default=
zh-CN

zhBrief=
8/17

zhFull=
612/8000

newFeatures=
126/500

assetGroup=
phone_tablet

screenshots=
4

promoVideo=
0

iconHash=
7d4a11c8

screenshotSetHash=
0e6bd2f4

ratingSnapshot=
rating_20261002_03

metadataMismatch=
0

assetMissing=
0

checks=
9/9

status=
LISTING_READY

这组日志让市场资料不再是一堆“文件夹里的图片”。

它已经变成可进入 CI 的结构化发布数据。

十一、手机诊断页的价值是给发布负责人一次性看完

最终运行图：

页面把：

语言
文案长度
图标
4 张截图
内容分级
9 项结果

放在一起。

相比在 AppGallery Connect 的多个区域来回点，ReleaseGuard 更适合做一次本地总览。

但它仍然只是 internal 页面。

正式 release 构建里不会把“商店素材报告”暴露给普通用户。

十二、截图和描述最好绑定同一个 metadataRevision

只绑定 taskId 还不够。

如果同一次流水线里先生成素材报告，后面又有人改了介绍文案，报告和提交内容仍然可能错位。

所以最终发布上下文再加：

metadataRevision

它由：

localization files
asset manifest
rating snapshot

共同摘要生成。

进入上传步骤时重新计算一次。

只要变化：

LISTING_CONTEXT_CHANGED

必须重新跑 03。

这个思路和 01 的 releaseContextId 保持一致。

十三、为什么 03 不把 AppGallery 页面自动提交也做掉

因为这篇的目标是：

预检

不是：

替人自动发布

自动把截图、介绍和分级信息提交到市场属于另一层发布自动化，需要额外权限、接口和审批流程。

ReleaseGuard 当前只输出：

可机器读取报告

CI 可以决定：

LISTING_READY
→ 允许进入后续上传 / 人工提交步骤

这比“工具顺手把所有东西都发了”更安全。

十四、03 最后固定九组异常测试

除了正常 9/9，我会故意制造：

1 zh-CN 缺失

2 en-US 缺全量介绍

3 中文简短介绍超过 17

4 新功能超过 500

5 截图少 1 张

6 icon hash 变化

7 screenshotSetHash 变化

8 rating snapshot 缺失

9 metadataRevision 在检查后发生变化

这些问题都必须给不同风险码。

如果工具只会告诉我：

素材检查失败

还不够。

发布负责人需要知道到底应该找开发、设计还是运营修改。

十五、下一篇从“商店展示资料”回到包体解析

到 03 为止，ReleaseGuard 已经覆盖：

包体身份
隐私合规
市场元数据

04 会回到一个更底层、也更接近 AppGallery Connect 包解析错误的主题：

deviceTypes
release Profile 权限
HAP 签名
package type

特别是官方错误码里明确存在：

998：
包不支持所选设备

7014：
包内权限与 Profile 权限不一致

999：
Profile 类型错误

1014：
HAP 未签名

04 会把这些“可以本地确认”的包体风险做成一份 Package Report。

十六、素材校验还要区分“文件存在”和“发布页面可用”

有一次我碰到的情况很典型：截图文件都在，hash 也正确，但真正打开 AppGallery Connect 的素材配置页，发现其中一张图属于旧的页面布局，虽然文件技术上完全没问题，发布负责人仍然需要把它换掉。

所以 ReleaseGuard 后来把素材状态拆成两层：

FILE_VALID
REVIEW_APPROVED

FILE_VALID 表示：

文件存在
格式可读
hash 可计算
归属设备组明确

REVIEW_APPROVED 则表示：

发布负责人已经确认
这张素材就是本次版本要展示的真实界面

机器只负责第一层和“批准记录有没有过期”的检查。

第二层仍然保留人工确认。

这种分层很重要，因为商店截图不是单纯的构建资源，它还是对用户展示功能能力的承诺。

工具如果把“文件存在”直接等价成“审核素材正确”，反而会制造错误安全感。

十七、素材批准记录也应该跟 appVersion 绑定

当前版本：

1.3.0
10300

所以我给批准记录增加：

approvedForVersionName
approvedForVersionCode
approvedAt
approvedByRole

只要版本号变化，原批准记录默认进入：

NEEDS_REVIEW

并不是说每次小版本都必须换截图，而是要求发布负责人重新确认：

这组素材仍然准确代表当前版本。

如果 1.3.1 只是修复稳定性，人工确认后可以继续沿用；如果页面已经改版，就必须更新 hash 和批准记录。

这种“强制重新确认，但允许继续复用”的机制，比每次自动判定截图失效更符合真实发布流程。

十八、多语言文案还要检查“默认语言回退是否被误用”

AppGallery Connect 当前说明里提到：如果某个语言没有配置对应信息，会使用默认语言内容。

从平台体验角度这是合理的兜底，但 ReleaseGuard 不希望团队把它当成常规发布策略。

例如：

configuredLocales:
zh-CN / en-US

如果 en-US 里只配了应用名称，没有全量介绍，平台可能回退到默认语言，但海外用户看到中文描述，产品体验明显不完整。

所以 ReleaseGuard 的 2/2 完成度口径是：

本次主动配置的语言
必须完成团队要求的字段集合

不会因为平台可以 fallback 就把它算通过。

这个规则属于团队发布质量门槛，不是 AppGallery Connect 的强制行为。

十九、新功能文案还要和 versionCode 做一致性检查

新功能很容易变成发布流程里的“最后一秒复制粘贴”。

我会在 whats-new.md 头部写一份机器可读元数据：

versionName=1.3.0
versionCode=10300

Preflight 读取后和当前 Snapshot 对比。

如果代码是：

1.3.0 / 10300

文案头部却是：

1.2.9 / 10290

直接：

WHATS_NEW_VERSION_MISMATCH

这种错误几乎没有技术难度，却很常见。

而且 AppGallery 的更新页会直接把新功能文案展示给用户，版本错位比普通 README 错一行严重得多。

二十、03 的输出最终应该是一份可归档的 Listing Evidence

除了页面上的 9/9，我还会输出：

ListingMetadataSnapshot.json
AssetManifest.json
RatingSnapshotRef.json
ListingAuditReport.json

后面审核被退回时，可以直接拿当前提交证据对照。

如果某次提交几天以后才收到审核反馈，团队成员已经切到下一个开发分支，仅靠记忆很难还原：

当时到底提交了哪四张图
简介是哪一版
内容分级用的是哪个问卷快照

Evidence 让这件事变成可追溯记录。

二十一、为什么 Listing Report 值得独立成为系列一篇

商店元数据经常被当成“开发结束后的运营工作”。

实际它和代码一样存在版本、依赖和一致性。

ReleaseGuard 03 最终形成的关系是：

构建版本
↔
本地化文案
↔
视觉素材
↔
设备素材组
↔
内容分级

只要其中一项来自旧版本，用户在 AppGallery 看到的就不是当前应用的真实状态。

因此把它工程化，并不是想让开发者替运营做所有事，而是让发布资料也拥有：

版本身份
变更记录
检查结果
审核证据

这才是 LISTING_READY 真正要表达的含义。

参考资料

• AppGallery Connect：Configuring Localized Information (Introduction, Features, and Assets)
  https://developer.huawei.com/consumer/fr/doc/app/agc-help-release-app-intro-0000002313477961
• AppGallery Connect：Maintaining an App / Content Rating / Release Flow
  https://developer.huawei.com/consumer/de/doc/app/agc-help-maintain-0000002270829401
• AppGallery Connect：Specifications for App Visual Assets
  https://developer.huawei.com/consumer/de/doc/app/agc-help-service-white-paper-0000001156658451