hot-updater

Hot Updater CLI

当任务涉及 Hot Updater 的 CLI、hot-updater.config.ts、React Native OTA 部署、补丁产物、bundle 操作、回滚、发布渠道管理、代码签名密钥、数据库迁移、指纹或诊断时，请使用此技能。

操作规则

• 除非用户指定其他应用目录，否则从项目根目录开始。
• 在假设提供商行为之前，先读取本地 hot-updater.config.ts。
• CLI 示例和面向用户的说明中使用 npx hot-updater ...。
• 不要代替用户运行 npx hot-updater init。此命令为交互式命令，会询问提供商、构建和项目特定选项。请指导用户直接运行，并遵循设置文档。
• 在运行 npx hot-updater doctor 检查服务器／基础设施之前，确保服务器基础 URL 可用。如果用户没有提供，且本地配置中也无法明显判断，请先询问更新服务器 URL。
• 对于 doctor 修复循环，先运行 npx hot-updater doctor --json。通过编辑本地项目文件修复标记为 fixability: "auto" 的问题；对标记为 fixability: "command" 的问题，运行列出的 commands；每次针对性修改后都重新运行 doctor。当 doctor 检查通过，或剩余问题均标记为 fixability: "blocked" 时停止。
• 将 fixability: "blocked" 视为超出自主本地修复范围。服务器基础设施修复通常需要提供商凭据、环境变量和重新部署权限；请概述阻碍，而不要运行迁移或修改提供商配置。
• 将 deploy、patch、bundle enable、bundle disable、bundle update、bundle delete、bundle promote、rollback、channel set、keys export-public、keys remove 和 db migrate 视为会更改状态的操作。
• 将 keys generate 和 db generate 视为会写入本地文件／产物的操作。
• 仅对本文档中注明支持 --json 的命令使用该选项。对于变更操作，--json 只会在请求的变更已获授权后改变输出格式。如果目标项目使用的是不支持此选项的旧版 CLI，则改用人类可读的输出。
• 对于非交互式 shell，仅当用户已明确请求执行确切的变更，且目标明确无误时，才使用 -y。
• 修改 bundle 状态后，通过 bundle list 或相关提供商状态进行验证。
• 如果 deploy 失败，请停止部署工作流。除非用户明确要求后续操作，否则不要继续重试修复、编辑设置、更改凭据、安装依赖或运行迁移。只分析失败的命令、相关输出、可能原因和建议的后续检查。
• 除非用户明确提出要求，否则不要编辑提供商凭据。凭据通常存储在 .env.hotupdater 中，但项目也可能采用不同的环境加载配置。

自然语言请求

用户可能会用以下提示词调用此技能：

$hot-updater deploy using the current app version
$hot-updater deploy the current iOS app version to production
$hot-updater roll back the most recently deployed bundle
$hot-updater list iOS bundles on the production channel
$hot-updater update rollout cohort count for bundle <bundle-id> to 500
$hot-updater promote bundle <bundle-id> to staging
$hot-updater create a patch from bundle <old-id> to <new-id>
$hot-updater export the code signing public key
$hot-updater run doctor with server URL https://updates.example.com/api/check-update
$hot-updater fix local doctor issues that do not require server credentials

将请求转换为最安全的 CLI 流程。如果会更改状态的请求缺少必需的渠道、平台、bundle 目标、补丁基线、目标渠道或服务器 URL，且无法从本地上下文推断，请在执行任何变更之前先提出一个简洁的问题。对于 deploy 和 patch 的渠道，除非用户指定其他渠道，或本地上下文明确表明应使用其他渠道，否则使用 CLI 默认值 production。

当前应用版本部署

当用户要求部署当前应用版本时：

1. 在支持时运行 npx hot-updater app-version --json；否则运行 npx hot-updater app-version。
2. 如果有 JSON 输出，从中提取 ios 和／或 android；否则将人类可读的输出 作为备用来源。
3. 如果缺少平台信息，询问用户要部署 iOS、Android 还是两者。
4. 使用 -t <version> 部署：

npx hot-updater deploy -p ios -t <ios-app-version>
npx hot-updater deploy -p android -t <android-app-version>

如果要部署两个平台，逐个平台运行，并在支持时使用 npx hot-updater bundle list -p <platform> --limit 5 --json 验证每个平台的结果； 否则将 --json 去掉作为备用方案。

如果部署命令失败，不要继续部署下一个平台，也不要尝试自动修复。报告失败分析并等待用户提出新请求。

回滚最近的 Bundle

当用户要求回滚最近一次部署，但未指定 bundle 时：

1. 运行 npx hot-updater bundle list --json --limit 10。
2. 从 JSON 结果中选择最近的已启用 bundle。
3. 使用该 bundle 的 channel、platform 和 id 进行指定范围的回滚：

npx hot-updater rollback <channel> -p <platform> --target <bundle-id> -y

如果最近的 bundle 已被禁用，告知用户并询问是否回滚下一个已启用的 bundle。回滚后，使用以下命令验证：

npx hot-updater bundle list -c <channel> -p <platform> --limit 5 --json

如果不支持 --json，则不带 --json 重新运行同一命令。

核心命令

设置和诊断

npx hot-updater init
npx hot-updater doctor --server-base-url <update-server-url>
npx hot-updater doctor --json
npx hot-updater doctor --server-base-url <update-server-url> --json
npx hot-updater fingerprint
npx hot-updater fingerprint create
npx hot-updater app-version
npx hot-updater app-version --json
npx hot-updater console

• init 会创建或更新项目配置。由于该命令需要交互，请告知用户直接运行，而不要替他们选择答案。
• doctor 会检查本地设置和服务健康状况。请提供 --server-base-url；该命令会在服务检查时附加 /version。如果用户尚未提供该地址，请先询问再运行命令。
• doctor --json 是首选的 Agent 接口。它会返回稳定的问题代码、相关路径、fixability 和命令提示，便于进行本地迭代修复。有 JSON 输出时，不要解析人类可读的 doctor 输出。
• fingerprint 和 fingerprint create 会生成应用指纹。
• app-version 会读取原生 iOS 和 Android 应用版本。支持该功能的 CLI 中，--json 会返回 { "android": string | null, "ios": string | null }。
• console 会打开本地管理控制台。

部署

npx hot-updater deploy -p <ios|android>
npx hot-updater deploy -p ios -c production -r 25
npx hot-updater deploy -p android -f
npx hot-updater deploy -p ios -d
npx hot-updater deploy -p ios -o ./hot-updater-output

重要选项：

选项	含义
-p, --platform <platform>	目标平台：ios 或 android。
-c, --channel <channel>	发布渠道，默认为 production。
-t, --target-app-version <range>	应用版本范围，例如 1.2.3 或 1.x.x。
-r, --rollout <percentage>	初始发布百分比，范围为 0 到 100。
-f, --force-update	客户端更新时立即应用。
-d, --disabled	上传后禁用，以便稍后启用。
-o, --bundle-output-path <path>	生成 bundle 压缩包的目录。
-m, --message <message>	自定义部署消息。
-i, --interactive	引导式部署流程。

修补工件

npx hot-updater patch -b <bundle-id> --base-bundle-id <base-bundle-id> -p ios
npx hot-updater patch -b <bundle-id> --base-bundle-id <base-bundle-id> -p android -c production
npx hot-updater patch -i

重要选项：

选项	含义
-b, --bundle-id <bundleId>	接收修补工件的目标 bundle ID。
--base-bundle-id <baseBundleId>	用作修补基准的较旧 bundle ID。
-p, --platform <platform>	目标平台：ios 或 android。
-c, --channel <channel>	用于加载配置的渠道，默认为 production。
-i, --interactive	引导式修补流程。

Bundle 清单和状态

npx hot-updater bundle list
npx hot-updater bundle list -c production -p ios --limit 10
npx hot-updater bundle list -c production -p ios --limit 10 --json
npx hot-updater bundle list --json
npx hot-updater bundle show <bundle-id>
npx hot-updater bundle show <bundle-id> --json
npx hot-updater bundle disable <bundle-id>
npx hot-updater bundle enable <bundle-id>
npx hot-updater bundle update <bundle-id> --rollout-cohort-count 500
npx hot-updater bundle update <bundle-id> --force-update true --json
npx hot-updater bundle update <bundle-id> --target-cohorts 1,2,3
npx hot-updater bundle update <bundle-id> --clear-target-cohorts
npx hot-updater bundle delete <bundle-id>
npx hot-updater bundle promote <bundle-id> -t staging
npx hot-updater bundle promote <bundle-id> -t staging -a move

• bundle list 会优先显示最新的 bundle。
• bundle list --limit <n> 的默认值为 20。
• 支持该选项的 CLI 中，bundle list、bundle show 和 bundle update 均可使用 --json。
• bundle disable 和 bundle enable 会读取 bundle、更改启用状态、提交更改，然后重新读取以进行验证。
• bundle update 可将 rollout 队列数设为 0 到 1000、强制更新元数据，并指定目标队列。
• bundle delete 会按 id 删除 bundle 记录。
• bundle promote 默认会将 bundle 复制到目标渠道。只有当用户明确希望保留相同的 bundle id 并切换渠道时，才使用 -a move。
• 在 CI 或其他非交互式 Shell 中，使用 -y 执行 enable 或 disable。只有当用户要求的变更目标明确无误时，才对 update、delete 或 promote 使用 -y。

回滚

npx hot-updater rollback <channel>
npx hot-updater rollback production -p ios
npx hot-updater rollback production -p ios --target <bundle-id> -y

• 回滚会禁用该渠道上最新的已启用 bundle。
• 不使用 -p 时，回滚会同时应用于 iOS 和 Android。
• 同一渠道和平台上次新的已启用 bundle 会成为备用版本。
• 如果不存在更早的已启用 bundle，应用会回退到原生二进制文件中附带的 JavaScript bundle。
• 使用 --target <bundle-id> 可针对一个确切的 bundle 重试部分回滚。

渠道

npx hot-updater channel set <channel>

此操作会将默认渠道写入原生 iOS 和 Android 项目文件。更改此嵌入式渠道需要重新进行原生构建。

代码签名密钥

npx hot-updater keys generate
npx hot-updater keys generate -o ./keys -k 4096
npx hot-updater keys export-public
npx hot-updater keys export-public -i ./keys/private.pem --print-only
npx hot-updater keys remove

• keys generate 会生成 RSA 密钥对。默认输出目录为 ./keys，支持的密钥长度为 2048 和 4096，默认值为 4096。
• keys export-public 会从 -i 或 hot-updater.config.ts 中的 signing.privateKeyPath 读取私钥，然后将原生公钥配置写入文件，除非使用 --print-only。
• keys remove 会从原生配置文件中移除公钥。
• 仅当用户明确要求执行相应操作时，才使用 -y 写入原生文件。

数据库

npx hot-updater db generate [configPath] [outputDir]
npx hot-updater db generate --sql
npx hot-updater db generate --sql postgresql
npx hot-updater db migrate [configPath]

• db generate 会生成迁移文件，但不会应用迁移。默认输出目录为 hot-updater_migrations。
• db generate --sql [provider] 会生成独立的 SQL 文件，且不会读取配置。支持的 provider 为 postgresql、mysql 和 sqlite；省略 provider 时会启动交互式选择。
• db migrate 会通过配置的数据库插件应用最新迁移。
• 仅当用户明确要求写入或迁移时，才使用 -y。