应用投递助手桌面端使用教程

本文面向需要将应用投递到统信/deepin UOS 应用商店的开发者，说明桌面端从登录、同步、资料维护、素材处理、适配范围配置到提交审核的完整操作流程。GitHub Action 自动化发布方式见文末附录。

适用场景

统信应用投递助手主要解决三类工作：

1. 新应用上架：拖入本地 .deb、玲珑 .uab 或 .layer 包，自动解析元数据，补齐文案、截图、图标和适配范围后提交。
2. 已上架应用更新：选择“我的应用”中的线上应用，可只更新文案、截图、图标或适配范围；如果拖入新包，则作为版本更新提交。
3. 多架构包更新：同一个应用可以同时维护 x86、amd64、arm64、loong64 等不同架构包。包列表按包展示，点击某个包后，右侧显示该包对应的截图、图标和适配范围。

准备工作

使用前应准备以下内容：

• 统信/deepin UOS 应用商店开发者账号。
• 待提交的应用安装包，例如 .deb、.uab 或 .layer。
• 应用图标和截图素材。截图可先准备原始图，后续由工具做规范化处理。
• 应用中文文案和英文文案，包括名称、简介、详情、更新说明。
• 需要上架的系统线和具体版本范围。

如果是更新已上架应用，包名必须和线上应用对应。直接拖入新包时，工具会优先按包名匹配“我的应用”；匹配不到时需要先在左侧选择线上应用。

启动软件

安装 deb 后，可以从启动器打开：

统信应用投递助手

开发环境下也可以直接运行 Qt 程序：

./Qt-C++/build/utpublisher-qt-cpp

首次启动后，点击右上角“同步”，拉取商店能力缓存。能力缓存包括 deb 系统线、玲珑系统线、baseline、CPU 和主板适配项等。

界面结构

主界面分成四个区域：

• 左侧栏：登录状态、我的应用列表、当前任务队列。
• 中间区：当前应用资料、包列表、多语言文案、发布区域。
• 右侧栏：当前包的图标、截图、截图管理和适配范围。
• 底部栏：解析、制图、等待、提交的工作流状态，以及最终提交按钮。

左侧“我的应用”是入口按钮。点击后会回到空状态，并刷新线上应用列表；不会保留之前选择的本地包。

登录与同步

1. 点击左下角“登录”。
2. 选择扫码登录或账号密码登录。
3. 登录成功后，左下角会显示账号和 Cookie 有效状态。
4. 点击右上角“同步”，刷新商店能力缓存和应用列表。

登录成功后，左侧会列出“我的应用”。应用较多时，列表支持滚动和继续加载。点击某个应用会进入该应用的更新模式。

新应用上架

新应用上架通常按以下流程操作：

1. 点击左侧“我的应用”，确保回到未选择任何应用和本地包的空状态。
2. 将本地 .deb、.uab 或 .layer 文件拖入中间的虚线框，或者点击“选择包文件”。
3. 等待工具解析包信息。解析后会自动填充应用名、版本号、架构、包格式、官网等基础数据。
4. 在“应用资料与包列表”里检查包列表。多架构包会显示多行，点击某个包可以查看该包对应的右侧信息。
5. 填写或修改文案：
   • 官网：不做严格 URL 格式限制，可填写官网、项目地址或文档地址。
   • 开发者：填写开发者名称，提交时会写入商店语言信息。
   • 分类：选择应用分类。
   • 中文文案：填写名称、简介、详情、更新说明。
   • English Copy：填写英文名称、简介、详情、更新说明。
6. 选择发布区域：
   • 中国（包含港澳台）
   • 其他地区
7. 准备图标和截图：
   • 点击“添加截图”选择本地截图。
   • 点击“粘贴”从剪贴板导入截图。
   • 点击“占位”生成临时占位截图，仅适合测试。
   • 需要替换图标和截图时，勾选“替换图标/截图”。
8. 点击“预处理素材”，让工具把截图调整到商店规范尺寸。
9. 在右侧“适配范围”点击“调整”，选择每个包对应的系统线和版本范围。
10. 检查底部状态后，点击“执行全自动提交”。

提交完成后，工具会生成报告。报告中包含每个包的提交状态、错误信息和输出目录。

更新已上架应用

已上架应用不一定要有新包才能提交。只更新文案、图标、截图或适配范围时，直接选择线上应用即可。

操作流程：

1. 登录并同步。
2. 在左侧“我的应用”列表中点击要更新的应用。
3. 工具会加载该应用的线上资料，包括包列表、文案、图标、截图和适配范围。
4. 按需要修改：
   • 中文或英文文案。
   • 官网和开发者名称。
   • 发布区域。
   • 图标和截图。
   • 系统线和版本范围。
5. 不拖入新包时，点击“执行全自动提交”会提交资料更新。
6. 如果需要更新安装包，再拖入新版本包。工具会把新包和当前选择的线上应用关联，作为版本更新提交。

切换应用时，本地已选择的包会被丢弃，避免线上应用资料与本地包资料交叉保留。

更新安装包

更新安装包有两种入口：

1. 先选线上应用，再拖入新包。
2. 直接拖入新包，让工具按包名自动匹配线上应用。

优先使用第一种方式，尤其是在账号下有多个相近包名、历史包名变更或社区版/专业版并存时。

包列表的使用规则：

• 包列表按实际包展示，不按单应用单架构简化。
• 多架构包需要全部显示，即使某些架构本次不更新，也不能丢弃线上已有包信息。
• 点击包列表中的某一行后，右侧会切换到该包对应的图标、截图和适配范围。
• 右侧“当前包”显示的是正在操作的包，不代表整个应用只有这一个包。

如果商店返回“包文件名称不一致”，通常说明上传的新包名、解析出的 Package 名或线上应用包名不匹配，需要重新确认包名。

截图与素材规范

截图管理在右侧“截图工坊”完成。

支持的操作：

• 添加截图：从本地选择图片。
• 粘贴：从剪贴板读取图片。
• 占位：生成临时截图，用于流程测试。
• 删除所选：删除当前选中的截图。
• 预处理素材：按商店规范调整图标和截图。

截图预处理规则：

• 横屏截图：3:2，尺寸范围 1050x700 到 1920x1280。
• 竖屏截图：9:16，尺寸范围 360x640 到 900x1600。
• 只有点击“预处理素材”后，工具才会对截图做尺寸适配。
• 自动截图功能目前不可用，界面上保留入口但暂不使用。

至少准备 3 张有效截图。截图内容应能体现应用主界面、核心功能和典型使用场景。

图标提取与替换

工具会尝试从包内提取应用图标：

• deb 包通常从 desktop 文件、图标主题路径或安装资源中提取。
• 玲珑包会按包内元数据和资源路径尝试识别。
• 如果识别出的图标不正确，可以手动替换图标。

更新已上架应用时，如果只更新安装包或文案，并保留线上图标和截图，不勾选“替换图标/截图”。勾选后，提交时会用当前预处理后的素材覆盖线上素材。

适配范围

适配范围按“包”设置，不是整个应用统一设置一次。

基本规则：

• 每个包都有自己的架构，例如 x86、arm64、loong64。
• 点击包列表中的包，再点击右侧“调整”，设置该包的系统线。
• CPU 和主板适配主要针对 ARM 架构；非 ARM 包通常不需要设置这些项。
• 线上已有系统线会同步回来，更新时应在此基础上调整。

系统版本选择逻辑需要和商店网页保持一致：

• 只勾选系统线，不选择具体版本时，表示使用商店默认兼容逻辑。
• 选择具体版本时，表示明确限定该系统线的具体版本范围。
• “不上架版本”用于排除某些版本，不等于选择可上架版本。

应根据包的实际支持情况选择系统线和版本范围，避免无差别全选。

只更新文案或系统线

已上架应用可以不上传新包，直接提交这些更新：

• 中文文案。
• 英文文案。
• 官网。
• 开发者名称。
• 发布区域。
• 适配系统线和具体版本。
• 图标或截图。

操作方式：

1. 登录并同步“我的应用”。
2. 点击目标应用。
3. 修改文案或适配范围。
4. 不选择本地包，直接提交。

这类提交适合修正文案、补充英文说明、调整社区版/专业版适配范围、替换截图等场景。

提交与报告

点击“执行全自动提交”后，底部状态会依次更新：

• 解析
• 制图
• 等待
• 提交

提交结束后会生成报告文件，通常包含：

• report.json
• report.xlsx

报告会记录每个应用或包的状态。常见状态包括：

• submitted：提交成功。
• submit_failed：商店接口返回失败。
• failed：工具执行阶段失败。

如果失败，优先打开 report.json 查看 message 字段，再根据错误信息处理。

常见问题

登录失败：提示 Qt bindings not found

这是 Python 后端需要的 Qt 绑定缺失。桌面打包版本应内置运行环境；开发环境运行时需要确保 PySide6、PyQt6 或 PyQt5 可用。

扫码登录时下载 Chromium 很慢

扫码登录依赖 Chromium 浏览器运行时。工具会按运行地区自动选择下载源：国内环境优先使用华为云镜像，其次回退到其他国内镜像和官方源。

如需手动指定下载源，可在启动前设置环境变量：

export UTPUBLISHER_CHROMIUM_REGION=cn
export UTPUBLISHER_CHROMIUM_MIRROR=huaweicloud

也可以直接指定 Pyppeteer 下载源：

export PYPPETEER_DOWNLOAD_HOST=https://repo.huaweicloud.com

可选镜像名称包括 huaweicloud、huaweicloud-mirror、npmmirror、official。

Pyppeteer 官方快照不提供 loong64/loongarch64 版本。loong64 系统需要安装本机 Chromium/Chrome，并在启动前指定浏览器路径：

可以手动下载 Playwright Chromium，并配置到对应缓存目录(amd架构例子)

export UTPUBLISHER_CHROMIUM_EXECUTABLE=/usr/bin/chromium

mkdir -p ~/.local/share/pyppeteer/local-chromium/1181205

curl -L \
  -o /tmp/chrome-linux-1181205.zip \
  https://storage.googleapis.com/chromium-browser-snapshots/Linux_x64/1181205/chrome-linux.zip

unzip -q /tmp/chrome-linux-1181205.zip \
  -d ~/.local/share/pyppeteer/local-chromium/1181205

chmod +x ~/.local/share/pyppeteer/local-chromium/1181205/chrome-linux/chrome

~/.local/share/pyppeteer/local-chromium/1181205/chrome-linux/chrome --version

拖入包后自动匹配错应用

先点击左侧“我的应用”，回到空状态；再手动点击正确的线上应用，之后拖入本地包。

切换应用后资料混在一起

新版逻辑会在切换线上应用时清空本地包状态。若仍看到混合状态，先点击“我的应用”重置，再重新选择应用。

官网格式不正确

工具本身不对官网做严格格式限制。但如果商店接口返回官网格式错误，需要按商店当时的校验要求调整，例如补全协议或使用可访问地址。

截图不符合尺寸

先添加或粘贴原图，再点击“预处理素材”。未处理截图不应直接提交。

包名不一致

新包的包名必须和线上应用的包名一致。检查 deb 控制字段、玲珑元数据和线上应用包名。

玲珑包格式不支持

确认拖入的是工具当前支持的玲珑包格式，例如 .uab 或 .layer。如果是特殊格式，需要先转换或补充解析支持。

玲珑包和deb包名一致的话

就不能自动识别到对应的应用下，需要手动选择对应应用进行上传包，下个版本修复。

GitHub Action 附录

桌面端适合人工检查和半自动投递；GitHub Action 适合在项目发布新版本时自动更新已上架应用。

最小示例：

name: Update UOS Store App

on:
  workflow_dispatch:
    inputs:
      package:
        description: Package path
        required: true

jobs:
  update-app:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Update app store listing
        uses: guanzi008/appstore@main
        with:
          username: ${{ secrets.APPSTORE_USERNAME }}
          password: ${{ secrets.APPSTORE_PASSWORD }}
          packages: ${{ inputs.package }}
          app-id: "1096227"
          note: "自动更新"
          mode: api

多包更新：

          packages: |
            dist/app_1.2.0_amd64.deb
            dist/app_1.2.0_arm64.deb
            dist/app_1.2.0_loong64.deb

只验证账号：

          test-only: "true"

Action 更适合固定流程。涉及截图挑选、适配范围核对、文案编辑时，优先使用桌面端。