@huoye/app-ship 0.1.0

package/README.md

@@ -0,0 +1,503 @@
+# App Ship
+
+多平台应用商店上传引擎 — CLI 命令行工具 & npm 库，支持 APK / IPA / AAB / HAP 一键分发。
+
+[![npm version](https://img.shields.io/npm/v/@huoye/app-ship.svg)](https://www.npmjs.com/package/@huoye/app-ship)
+[![npm downloads](https://img.shields.io/npm/dm/@huoye/app-ship.svg)](https://www.npmjs.com/package/@huoye/app-ship)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Languages**: [English](README_EN.md) | 简体中文
+
+## 特性
+
+- **8 大平台实测通过** ✅：蒲公英、华为、小米、OPPO、vivo、腾讯应用宝、App Store、鸿蒙
+- **并行上传**：多平台同时上传，可配置并发数
+- **智能分发**：自动路由 APK → Android 商店、IPA → Apple、HAP → 鸿蒙
+- **指数退避重试**：网络波动自动重试，可配置退避策略
+- **YAML 单配置**：一个配置文件管理所有平台凭据
+- **三种使用方式**：CLI 命令行、npm 库、VSCode 插件
+- **框架无关**：Flutter、React Native、原生 Android/iOS、鸿蒙均可使用
+
+## 安装
+
+```bash
+# 全局安装 CLI
+npm install -g @huoye/app-ship
+
+# 作为项目依赖
+npm install @huoye/app-ship
+```
+
+## 快速开始
+
+```bash
+# 1. 安装
+npm install -g @huoye/app-ship
+
+# 2. 初始化配置
+app-ship init
+
+# 3. 上传
+app-ship upload -c app-ship.yaml -f app.apk
+```
+
+## 三种使用方式
+
+### 1. CLI 命令行
+
+适合 DevOps、CI/CD 流水线和命令行用户。
+
+```bash
+# 初始化配置文件
+app-ship init
+
+# 上传到所有启用的平台
+app-ship upload -c app-ship.yaml -f app-release.apk
+
+# 仅上传到指定平台
+app-ship upload -c app-ship.yaml -f app-release.apk --platform pgyer,huawei
+
+# 带元数据上传
+app-ship upload -c app-ship.yaml -f app-release.apk \
+  --version 2.0.0 \
+  --build-number 42 \
+  --changelog "修复了已知问题"
+
+# 查看支持的平台
+app-ship platforms
+
+# 查看帮助
+app-ship --help
+```
+
+**CLI 参数说明**：
+
+| 参数                 | 简写 | 说明                                                       |
+| -------------------- | ---- | ---------------------------------------------------------- |
+| `--config <path>`    | `-c` | 配置文件路径 (YAML)                                        |
+| `--file <path>`      | `-f` | 安装包路径 (APK/IPA/AAB/HAP)                               |
+| `--platform <list>`  | `-p` | 逗号分隔的平台列表（可选，不填则使用配置文件中启用的平台） |
+| `--version <ver>`    | `-v` | 版本号（默认：配置文件中的值或 "1.0.0"）                   |
+| `--build-number <n>` | `-b` | 构建号（默认："1"）                                        |
+| `--changelog <text>` |      | 更新日志                                                   |
+| `--verbose`          |      | 显示详细输出                                               |
+
+### 2. npm 库（编程集成）
+
+适合自建发布系统或集成到现有工作流。
+
+```typescript
+import { UploadManager, ConfigValidator } from '@huoye/app-ship'
+
+// 加载并验证配置
+const config = ConfigValidator.loadAndValidate('./app-ship.yaml')
+
+// 创建上传管理器
+const manager = new UploadManager({
+  maxConcurrent: 3, // 最大并发数
+  continueOnError: true, // 部分失败后继续
+  verbose: true, // 显示详细日志
+})
+
+// 执行上传
+const report = await manager.uploadToMultiplePlatforms('./app-release.apk', config, {
+  version: '2.0.0',
+  buildNumber: '42',
+  changelog: '修复了已知问题',
+})
+
+// 查看结果
+console.log(`成功: ${report.successCount}, 失败: ${report.failureCount}`)
+console.log(`总耗时: ${report.totalDurationMs}ms`)
+
+// 遍历每个平台的结果
+for (const result of report.results) {
+  if (result.success) {
+    console.log(`✅ ${result.platform}: ${result.url || result.consoleUrl}`)
+  } else {
+    console.log(`❌ ${result.platform}: ${result.message}`)
+  }
+}
+```
+
+**单平台上传示例**：
+
+```typescript
+import { PgyerUploader } from '@huoye/app-ship'
+
+const uploader = new PgyerUploader()
+const result = await uploader.upload(
+  './app-release.apk',
+  { enable: true, apiKey: 'YOUR_API_KEY' },
+  { version: '1.0.0', buildNumber: '1', changelog: '首次发布' },
+)
+
+if (result.success) {
+  console.log(`下载地址: ${result.url}`)
+  console.log(`二维码: ${result.qrCode}`)
+}
+```
+
+### 3. VSCode 插件（可视化）
+
+安装 **Flu CLI** VSCode 插件，在 IDE 内点击操作即可完成构建和上传。
+
+功能：
+
+- 实时构建 & 上传进度展示
+- 可视化配置面板
+- 自动密钥管理
+- 下载链接 + 二维码展示
+
+详见 [VSCode 插件文档](https://gitee.com/flu-cli/flu-cli/tree/main/packages/vscode-extension#readme)。
+
+## 支持平台
+
+| 平台                 | 文件类型 | 认证方式           | 状态        |
+| -------------------- | -------- | ------------------ | ----------- |
+| 蒲公英 (Pgyer)       | APK, IPA | API Key            | ✅ 已实测   |
+| 华为 (Huawei)        | APK, AAB | OAuth2             | ✅ 已实测   |
+| 小米 (Xiaomi)        | APK      | RSA 公钥签名       | ✅ 已实测   |
+| OPPO                 | APK      | HMAC-SHA256        | ✅ 已实测   |
+| vivo                 | APK      | HMAC-SHA256 + MD5  | ✅ 已实测   |
+| 腾讯应用宝 (Tencent) | APK      | HMAC-SHA256        | ✅ 已实测   |
+| App Store            | IPA      | Apple ID / API Key | ✅ 已实测   |
+| 鸿蒙 (Harmony)       | HAP      | OAuth2             | ✅ 已实测   |
+| TestFlight           | IPA      | Apple API Key      | ⚠️ 框架就绪（开发中） |
+| Ad Hoc               | IPA      | 签名证书           | ⚠️ 框架就绪（开发中） |
+| Google Play          | APK, AAB | Service Account    | 🔄 计划中（v0.2.0）   |
+
+## 完整配置参考
+
+`app-ship.yaml` 完整结构：
+
+```yaml
+version: '1.0.0'
+
+# 重试策略（可选）
+retry:
+  maxRetries: 3 # 最大重试次数
+  initialDelayMs: 1000 # 初始延迟 (毫秒)
+  backoffMultiplier: 2 # 指数退避乘数
+  maxDelayMs: 30000 # 最大延迟 (毫秒)
+
+publish:
+  # ── 蒲公英 ──
+  pgyer:
+    enable: true
+    apiKey: '${PGYER_API_KEY}' # 支持环境变量
+    description: '测试版本'
+
+  # ── 华为 AppGallery ──
+  huawei:
+    enable: false
+    auth:
+      clientId: '${HUAWEI_CLIENT_ID}'
+      clientSecret: '${HUAWEI_CLIENT_SECRET}'
+    appId: 'YOUR_APP_ID'
+    releaseType: draft # draft = 仅上传 | submit = 提交审核
+    # apiBaseUrl: ''                  # 可选：指定区域 API
+
+  # ── 小米 ──
+  xiaomi:
+    enable: false
+    auth:
+      userName: 'your@email.com' # 开发者账号邮箱
+      privateKey: '${XIAOMI_KEY}' # API 访问密码（非登录密码）
+      # publicKeyPath: './rsa.cer'   # 可选：RSA 公钥文件
+    packageName: 'com.example.app'
+
+  # ── OPPO ──
+  oppo:
+    enable: false
+    auth:
+      clientId: '${OPPO_CLIENT_ID}'
+      clientSecret: '${OPPO_CLIENT_SECRET}'
+
+  # ── vivo ──
+  vivo:
+    enable: false
+    auth:
+      accessKey: '${VIVO_ACCESS_KEY}'
+      accessSecret: '${VIVO_ACCESS_SECRET}'
+
+  # ── 腾讯应用宝 ──
+  tencent:
+    enable: false
+    auth:
+      userId: '${TENCENT_USER_ID}' # 开发者用户 ID
+      appId: '${TENCENT_APP_ID}' # 应用 ID
+      accessSecret: '${TENCENT_SECRET}' # 接入密钥
+
+  # ── 鸿蒙 ──
+  harmony:
+    enable: false
+    auth:
+      clientId: '${HARMONY_CLIENT_ID}'
+      clientSecret: '${HARMONY_CLIENT_SECRET}'
+    appId: 'YOUR_APP_ID'
+
+  # ── App Store / TestFlight / Ad Hoc ──
+  app_store:
+    enable: false
+    mode: app_store # app_store | testflight | adhoc
+    auth:
+      appleId: '${APPLE_ID}' # Apple ID 邮箱
+      appPassword: '${APP_PASSWORD}' # App 专用密码
+      # API Key 认证（可选，用于自动更新发行说明）：
+      # apiKeyId: ''
+      # apiIssuerId: ''
+      # privateKeyPath: './AuthKey.p8'
+
+  # ── Google Play（计划中）──
+  google_play:
+    enable: false
+    auth:
+      serviceAccountJsonPath: './service-account.json'
+    packageName: 'com.example.app'
+    track: production # internal | alpha | beta | production
+```
+
+### 环境变量
+
+配置值支持 `${VAR_NAME}` 语法引用环境变量，避免敏感信息硬编码：
+
+```yaml
+pgyer:
+  enable: true
+  apiKey: ${PGYER_API_KEY} # 运行时自动替换
+```
+
+## 目录架构
+
+```
+packages/app-ship/
+├── src/
+│   ├── index.ts                          # 📦 库入口 — 导出所有公共 API
+│   ├── cli.ts                            # 🖥️ CLI 入口 — 命令行工具主程序
+│   ├── types.ts                          # 📐 类型定义 — 所有接口和类型
+│   ├── adapters/                         # 🔌 上传适配器层
+│   │   ├── index.ts                      #    适配器统一导出
+│   │   ├── pgyer_uploader.ts             #    蒲公英 — API Key 认证
+│   │   ├── huawei_uploader.ts            #    华为 — OAuth2 三步上传
+│   │   ├── xiaomi_uploader.ts            #    小米 — RSA 1024 分段加密
+│   │   ├── oppo_uploader.ts              #    OPPO — HMAC-SHA256 签名
+│   │   ├── vivo_uploader.ts              #    vivo — HMAC-SHA256 + MD5
+│   │   ├── tencent_uploader.ts           #    腾讯应用宝 — COS 直传
+│   │   ├── apple_store_uploader.ts       #    App Store — Transporter/altool
+│   │   ├── harmony_uploader.ts           #    鸿蒙 — 复用华为 AGC API
+│   │   ├── testflight_uploader.ts        #    TestFlight — 半成品
+│   │   └── adhoc_uploader.ts             #    Ad Hoc — 半成品
+│   ├── utils/                            # 🔧 工具层
+│   │   ├── index.ts                      #    工具统一导出
+│   │   ├── upload-manager.ts             #    上传管理器 — 并发调度 + 智能分发
+│   │   ├── retry-strategy.ts             #    重试策略 — 指数退避 + 错误分类
+│   │   ├── apple-jwt-generator.ts        #    Apple JWT — ES256 签名生成
+│   │   ├── package-parser.ts             #    包解析器 — APK/AAB 信息提取
+│   │   └── logger.ts                     #    日志工具 — 仅内部使用，不对外导出
+│   └── validators/                       # ✅ 验证层
+│       ├── index.ts                      #    验证器统一导出
+│       ├── config_validator.ts           #    配置验证 — YAML 加载 + Schema 校验
+│       └── env_validator.ts              #    环境变量验证
+├── dist/                                 # 构建产物
+├── package.json
+├── tsconfig.json
+└── tsup.config.ts
+```
+
+### 分层架构图
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    用户界面层                         │
+├───────────┬──────────────────┬───────────────────────┤
+│ CLI       │ VSCode 插件      │ npm 库集成             │
+│ (cli.ts)  │ (另一个包)       │ (index.ts)            │
+└─────┬─────┴────────┬─────────┴──────────┬────────────┘
+      │              │                    │
+      ▼              ▼                    ▼
+┌─────────────────────────────────────────────────────┐
+│                  配置管理层                           │
+│  ConfigValidator — YAML 解析 + 环境变量替换 + 校验    │
+│  EnvValidator — 环境变量存在性检查                     │
+└─────────────────────┬───────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────┐
+│                  上传管理层                           │
+│  UploadManager                                      │
+│  ├── 适配器注册与查找                                 │
+│  ├── 并发控制 (maxConcurrent)                        │
+│  ├── 智能分发 (APK→Android, IPA→Apple, HAP→鸿蒙)     │
+│  └── 结果聚合 → UploadReport                         │
+└─────────────────────┬───────────────────────────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────┐
+│              平台适配器层 (IUploader)                  │
+├────────┬────────┬────────┬────────┬────────┬────────┤
+│ Pgyer  │ Huawei │ Xiaomi │ Apple  │ Harmony│  ...   │
+└────────┴────────┴────────┴────────┴────────┴────────┘
+                      │
+                      ▼
+┌─────────────────────────────────────────────────────┐
+│                  基础设施层                           │
+│  RetryStrategy — 指数退避 + 错误分类                  │
+│  AppleJWTGenerator — ES256 JWT 签名                  │
+│  Logger — 彩色日志输出                                │
+└─────────────────────────────────────────────────────┘
+```
+
+## 自定义开发指南
+
+### 新增一个平台适配器
+
+只需 3 步即可添加新的上传平台：
+
+**第 1 步：实现 `IUploader` 接口**
+
+在 `src/adapters/` 下创建新文件，例如 `my_platform_uploader.ts`：
+
+```typescript
+import { IUploader, UploadResult, AppMetadata } from '../types.js'
+
+export class MyPlatformUploader implements IUploader {
+  name = 'my_platform'
+
+  // 验证配置是否完整
+  validateConfig(config: any): boolean {
+    return config?.enable && config?.auth?.apiKey
+  }
+
+  // 判断是否支持该文件类型
+  canHandle(filePath: string): boolean {
+    return filePath.endsWith('.apk')
+  }
+
+  // 执行上传
+  async upload(filePath: string, config: any, metadata: AppMetadata): Promise<UploadResult> {
+    try {
+      // ... 你的上传逻辑
+      return {
+        platform: this.name,
+        success: true,
+        message: '上传成功',
+        url: 'https://...',
+      }
+    } catch (error: any) {
+      return {
+        platform: this.name,
+        success: false,
+        message: error.message || '上传失败',
+        error,
+      }
+    }
+  }
+}
+```
+
+**第 2 步：注册适配器**
+
+在 `src/adapters/index.ts` 中添加导出：
+
+```typescript
+export * from './my_platform_uploader.js'
+```
+
+然后在 `src/utils/upload-manager.ts` 的 `registerBuiltinUploaders()` 中注册：
+
+```typescript
+this.registerUploader('my_platform', new MyPlatformUploader())
+```
+
+**第 3 步：添加配置类型**
+
+在 `src/types.ts` 的 `UploadConfig.publish` 中添加平台配置：
+
+```typescript
+my_platform?: {
+  enable: boolean
+  auth: {
+    apiKey: string
+  }
+}
+```
+
+完成！新平台将自动被 `UploadManager` 管理，支持并行上传和重试。
+
+### 关键接口说明
+
+| 接口           | 文件     | 用途                               |
+| -------------- | -------- | ---------------------------------- |
+| `IUploader`    | types.ts | 所有上传适配器必须实现的接口       |
+| `UploadConfig` | types.ts | YAML 配置文件的完整类型定义        |
+| `AppMetadata`  | types.ts | 上传时附带的应用元数据             |
+| `UploadResult` | types.ts | 每个平台上传后的统一返回格式       |
+| `BuildResult`  | types.ts | 构建结果（Android/iOS 构建器使用） |
+
+### 文件功能速查
+
+| 文件                     | 功能           | 修改场景                     |
+| ------------------------ | -------------- | ---------------------------- |
+| `types.ts`               | 所有接口定义   | 新增平台配置字段、扩展返回值 |
+| `cli.ts`                 | CLI 入口       | 新增命令、修改参数           |
+| `upload-manager.ts`      | 并行调度       | 调整并发策略、修改分发逻辑   |
+| `retry-strategy.ts`      | 重试机制       | 调整退避参数、新增错误分类   |
+| `config_validator.ts`    | 配置校验       | 新增平台必填项验证规则       |
+| `apple-jwt-generator.ts` | JWT 签名       | 仅 Apple 平台相关            |
+| `package-parser.ts`      | APK/AAB 解析   | 扩展包信息提取               |
+| `adapters/*.ts`          | 各平台上传逻辑 | 修复 API 变更、调整上传流程  |
+
+### 本地开发
+
+```bash
+# 安装依赖
+npm install
+
+# 构建
+npm run build          # 等效于 tsup
+
+# 开发模式（监听文件变化）
+npm run dev
+```
+
+## 常见问题
+
+### 如何获取各平台的 API Key？
+
+- **蒲公英**: 登录 [pgyer.com](https://www.pgyer.com) → 账号设置 → API 信息
+- **华为**: [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) → 我的项目 → 项目设置 → 密钥管理
+- **小米**: [小米开放平台](https://dev.mi.com/console/) → 应用管理 → 应用详情 → 上传接口
+- **OPPO/vivo/腾讯**: 对应开发者平台 → 应用管理 → API 管理
+
+### 配置文件支持环境变量吗？
+
+支持！使用 `${VAR_NAME}` 语法：
+
+```yaml
+pgyer:
+  apiKey: '${PGYER_API_KEY}'
+```
+
+### 上传失败如何排查？
+
+1. 使用 `--verbose` 参数查看详细日志
+2. 检查网络连接和各平台服务状态
+3. 确认 API Key 和权限配置正确
+4. 查看 [Issues](https://gitee.com/flu-cli/flu-cli/issues) 是否有类似问题
+
+## 🤝 社区
+
+扫描下方二维码或搜索公众号**火叶**关注我们
+
+| 关注公众号 | 加作者微信入群 | 赞赏支持 |
+| :------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------: |
+| <img src="https://gitee.com/flu-cli/flu-cli/raw/main/packages/vscode-extension/images/qcode-wx.png" alt="微信号" width="160"/> <br> **火叶** | <img src="https://gitee.com/flu-cli/flu-cli/raw/main/packages/vscode-extension/images/wechat-group.png" alt="微信号" width="160"/> <br> **微信**: `Huoye-TT`<br>（备注: `flu-cli`） | [给作者加鸡腿 ☕️](http://huozhiye.cn/flu-cli/advanced/rewards/rewards) |
+
+> 💡 你也可以点击插件详情页顶部的 **Sponsor** 按钮来支持本项目。
+
+---
+
+## License
+
+MIT | Copyright © 2025-2026 火叶工作室