应用商城上架教程

用 AI 提交，只需一次浏览器授权

推荐先按 AI 一句话上手 配置环境，再告诉 AI：

请把这个应用准备上架 app.doit.am，完善资料与截图，验证后提交审核。

工具会用本机签名私钥证明公钥归属，并打开浏览器让你登录、确认该应用短码。授权仅限该应用上传，有效 30 天，可从后台撤销；私钥不上传、令牌不进入聊天或命令参数。首次后可复用授权。

先告诉 AI 公开名称、简介、面向谁、要支持哪些设备，以及素材是否有权发布；现成图标可以直接提供。分类、标签、更新说明可让 AI 起草。有生图能力时由 AI 制作图标和可选封面；没有时可制作简单图标并跳过封面。运行 store prepare 后按商城实际要求补齐缺项。

.pxa/pxa store prepare apps/my-app
.pxa/pxa store authorize apps/my-app apps/my-app/dist/pxa-my-app.pxa --wait
.pxa/pxa store publish apps/my-app apps/my-app/dist/pxa-my-app.pxa --changelog '首次发布'

先通过 store prepare 获取商城当前规格和可用分类。推荐 512×512 图标与 1280×960（4:3）封面画，支持 PNG、JPEG、WebP；返回的字节、像素和截图数量限制为准。封面可使用创作插画，截图必须展示实际运行的应用。

有图片工具时可以生成图标与封面；没有图片工具时，可以由用户提供文件，或选择跳过图标、封面上传。--skip-icon / --skip-cover 会保留商城现有素材，不会删除。不要因为缺少图片工具停止整个上架流程。

截图必须来自真实运行的 PXA 模拟器。使用 verify --store-screenshots，拍摄前关闭圆角、圆屏遮罩、安全边距、性能浮层和底部导航，应用自己的性能浮层也要关闭。逐张检查完整矩形原图，禁止裁剪、修图或生图替代运行截图；多屏联系表只供检查，不能上传为截图。

{
  "kind": "game",
  "category": "puzzle",
  "tags": ["益智", "休闲"],
  "icon": "store/icon.png",
  "cover": "store/cover.png"
}

把这份资料放在项目内 store.json。图片路径相对于项目，icon 或 cover 为 null 表示明确跳过该项上传。标签最多十个，每个最多 24 个字符；作品类型及分类应选择预检返回的值。命令行也可传 --icon icon.png --cover cover.png --screenshot screen.png，这些路径相对于工作区。

已有作品的名称和简介保持不变；store.json 显式提供的类型、分类、标签会更新并遵循资料审核，未提供的字段保留原值，空标签数组清空标签。返回 pending_review 表示提交审核，审核通过后才公开。设备安装与商店提交是不同操作；桌面验证不能代替目标 CPU 的签名包检查。

手动发布与高级接入

下面的浏览器上传、签名公钥验证和 CI 令牌流程仍可使用。日常 AI 开发优先用上面的浏览器短码授权，无需打开浏览器控制台。

发布流程先看这里

准备签名包 → 登录开发者后台 → 登记公钥 → 创建应用资料 → 上传包并提交审核。先完成下文 1–4，再使用命令行上传。本文中 challenge 表示一次性验证串，保留英文是为了对应接口字段，不译为“挑战”。

使用 DevKit 命令行上传

先运行 pxa publish hello/dist/pxa-hello.pxa --check-only 验证最终包。下文完成账号、公钥登记和应用资料后，在应用管理页下载 30 天有效、只允许上传这一应用的令牌：

pxa publish hello/dist/pxa-hello.pxa --token-file /安全目录/pxa-upload-token.json

该命令上传原始签名文件，不重新构建或签名；商城返回 pending 和 SHA-256，仍需审核。生成新令牌会替换旧令牌，可随时在管理页撤销。账号停用或登录授权版本变化也会使令牌失效。令牌与发布私钥分别保存，不要提交到仓库。

商城以 Core、每项服务版本范围和必需 feature、以及全部组件的匹配制品筛选设备目录。上传签名有效不代表所有设备都能运行；设备 Host 仍核对最终能力。官方当前基线为 Core 2.1；板型及可选服务以实际能力为准。

1. 发布前准备

先完成签名与打包，在模拟器和目标真机验证安装、启动、退出、权限拒绝和升级。准备应用名称、简介、详细说明、分类、图标、实际截图与更新说明。

正式版本使用自己长期维护的 P-256 密钥。App ID、publisher lineage root 和 release sequence 决定更新身份；不能用商城表单修正签名包里错误的身份。

2. 注册与登录

进入 PXA 应用商城，注册或登录开发者账号，再进入开发者后台。按当前页面完成邮箱或 GitHub 登录流程；登录方式由商城配置决定。

3. 登记发布者身份

商城要求发布者公钥完成持有证明，否则上传会返回“签名公钥尚未登记或已撤销”。目前使用已登录会话和 CSRF token 调用两个接口，下面给出完整操作步骤。流程只上传公钥和签名证明，私钥始终留在本机。

获取一次性验证串

在已登录的商城后台页面打开浏览器开发者工具的 Console，执行下面代码。它会从当前页面读取 CSRF 字段，用当前登录会话申请一次性验证串：

var csrf = document.querySelector('input[name="csrf"]').value;
var response = await fetch('/api/v2/publisher-keys/challenge', {
  method: 'POST',
  headers: { 'X-CSRF-Token': csrf }
});
if (!response.ok) throw new Error(await response.text());
var challenge = await response.json();
console.log(challenge);

返回 challenge 和 domain。复制 challenge 字段的字符串，在 10 分钟内完成登记；验证串使用一次后失效。此代码要在 app.doit.am 的已登录后台运行，不是在本官网页面运行。

本地生成签名证明

使用打包页设置的 PXA_SIGNING_KEY 与 PXA_DEVKIT。脚本使用 Python 3 标准库与 DevKit 自带 OpenSSL，无需 pip 或 cryptography。下载本站的公钥证明脚本，保存为 local/publisher-proof.py。可先查看脚本，它只在本地读密钥、签名并打印证明，不会发起网络请求。

mkdir -p local
curl --fail --location https://pxa.doit.am/assets/publisher-proof.py -o local/publisher-proof.py
python3 local/publisher-proof.py "$PXA_SIGNING_KEY" \
  --openssl "$PXA_DEVKIT/runtime/bin/openssl"

粘贴刚取得的验证串（challenge）。脚本输出 JSON，包含 challenge、Base64 DER SPKI 公钥 publisher_spki 和 Base64 P1363 签名 signature。

实现细节：待签名字节为 PXA-STORE-PUBLISHER-KEY、一个 NUL 字节和 challenge 的 UTF-8 字节，使用 ECDSA P-256 / SHA-256。签名是 32 字节 r 加 32 字节 s，并规范化为 low-S；脚本负责转换，不能直接提交 OpenSSL 的 DER 签名字节。

提交证明

回到同一个后台 Console，将下面空对象替换为脚本输出的完整 JSON，然后执行：

var proof = {}; // 替换为本地脚本输出的 JSON
var result = await fetch('/api/v2/publisher-keys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-Token': document.querySelector('input[name="csrf"]').value
  },
  body: JSON.stringify(proof)
});
if (!result.ok) throw new Error(await result.text());
console.log(await result.json());

预期返回 key_id 和 status: "verified"。若验证串过期，重新获取并重新签名；若提示公钥属于其他开发者，应使用正确账号或自己的密钥。401/403 时检查登录状态和 CSRF，刷新后台页面后重新开始。接口参考见商城 API 文档。

4. 创建应用并上传图片

在后台创建应用，填写标识、名称、简介、详细介绍、应用 / 游戏类型和对应分类。保持应用标识与签名包身份一致。

上传 PNG、JPEG 或 WebP 图标和截图。图标会裁剪为 512×512，截图保留比例且最长边缩放至 1920 像素；文件大小和数量上限以页面显示为准。图片需要直接上传到商城，不能只填外部 URL。

商城截图使用真实 PXA 模拟器运行应用后，通过 .pxa/pxa verify apps/my-app --profiles pai-touch --store-screenshots 获取。截图前关闭性能浮层，并在运行器中隐藏底部手势条和三按键导航；逐张检查原图后上传，不能通过裁剪或修图掩盖这些界面。真机 pxadb screenshot 可用于硬件诊断，但不能替代商城所需的模拟器截图流程。

5. 上传 .pxa 并提交审核

打开应用详情中的“上传新版本”，选择 .pxa 容器并填写更新说明，然后点击“提交审核”。选择 PXA 后，版本、平台和兼容性由服务端从已签名 manifest 读取。

服务器核对容器签名和清单签名、发布者和 lineage、release sequence、组件、制品、服务与权限。上传成功后检查“PXA 已验证兼容性”和版本记录，确认目标架构、运行时 ABI 与权限符合预期。

6. 多平台版本

设备按目标选择下载包时，分别构建单目标包，并保持 App ID、version、sequence、lineage root 和当前发布者密钥一致：

pxa build hello --target esp32s3 --aot-only --output hello/dist/pxa-hello-s3.pxa
pxa build hello --target esp32s31 --aot-only --output hello/dist/pxa-hello-s31.pxa

在同一应用中依次上传 hello/dist/pxa-hello-s3.pxa 与 hello/dist/pxa-hello-s31.pxa。同 sequence 的不同目标包会合并到同一个待审版本，同目标重传替换该目标包。已完成审核的 sequence 不能复用；后续版本提高 sequence 后重新构建。

7. 审核与公开验证

应用资料审核与版本审核分别进行，且应用不能处于下架状态。已上架后修改名称、介绍或图片，会暂停公开入口并进入资料审核，审核通过后恢复。

上架后再用目标设备确认目录可见、包可安装与更新可用。签名有效不等于目标设备具备应用所需服务，仍需核对设备 Profile 与产品策略。

8. 后续更新

保留相同应用身份，修改 version 并提高 release_sequence，用相同密钥或有效 lineage 签名，重复构建、测试和审核。保存原始源码、构建环境、制品摘要和 provenance，方便追溯问题。

不要把短时下载票据写死进文档或 App。商城在实际下载时提供带有效期的地址；需要设备集成时使用 /api/v2 的签名目录与下载票据流程。

常见错误

Host 能力配置

Profile 名称代表冻结的 Host 能力快照，例如 *-pxa-0.5.0-r2。PXA 0.9.0 可继续使用能力匹配的既有 Profile，不能只按固件发行号推测兼容性。历史 *-pxa-0.4.0、*-pxa-0.3.0、*-pxa-0.3.0-r2 和 *-wamr-2.4.0 配置与包继续保留，不改写旧配置。商城逐项核对容器版本、压缩算法、解压块大小、Core、全部服务版本、feature bits、目标和运行时 ABI，不要求应用与 Host 发行号相等。

同一应用可按架构分别上传，设备目录选择自身能运行的完整 .pxa 文件。API 的 size 是这个文件的精确字节数，包含签名、清单、代码与资源；不等于单个 AOT 文件，也不等于所有架构包的总和。

设备安装必须确认

普通签名应用也可请求 Host 安装服务，不限定系统预置的商城身份。Host 负责验证下载来源、短时票据与包签名，并要求原生系统弹窗确认；应用不能静默安装。商城审核、包的发布者身份与设备上的安装确认各有独立职责。

遇到环境、编译、串口或提交问题时，查看 AI 开发排障。商城截图须通过真实模拟器拍摄，拍摄前关闭性能浮层和底部导航，上传前逐张检查原图。