OneKeyPublish 操作指南
本指南面向使用者，只讲怎么用——如何对项目、分支、编译任务进行增、删、改，以及完整的发版操作流程。图文并茂，跟着截图操作即可。
🎁 适用版本： v2.2.2 运行形态： 本地服务 + 浏览器 UI，启动后自动打开默认浏览器 配置文件： 所有配置自动保存在
~/.onekey-publish/config.json，无需手动维护 下载地址：https://git.n.xiaomi.com/zhangshuo16/onekeypublish/-/tree/main/release?ref_type=heads
一、界面总览
启动 OneKeyPublish 后浏览器会自动打开工具页面，整体分三栏：
5.4 Grapple Token
Grapple 平台的 API Token。每人一份，请务必替换默认 Token 为自己的。改完点 「保存 Token」。
⚠️ Grapple Token 属于个人凭证，切勿共享。如果需要备份配置分享给同事，导出 JSON 时不要勾选「包含敏感凭证」。
六、发版流程操作（4 步）
配置就绪后，点中间区的 ③ 发版流程 区块开始发版。
6.1 发版前准备
第 1 步： 点 「拉取代码」 —— 同步业务仓库和 Packages 仓库的最新代码。
第 2 步： 点 「计算下一版本」 —— 自动读取当前 versionName / versionCode，并推算下一版本。可手动微调「下一 versionName / versionCode」。
6.2 启动发版
点 「启动发版」 → 弹窗二次确认 → 开始 4 步流程：
| 步骤 | 名称 | 做什么 |
|---|---|---|
| ① | 版本升级与提交 | 更新版本号文件，提交到 Gerrit |
| ② | Gradle 编译发布 | 注入凭证，跑 Gradle 任务，构建产物，清理凭证 |
| ③ | Packages 更新 | 更新目标 XML 中的版本号，生成 Changelog，提交到 Gerrit |
| ④ | Grapple 编译 | 分类 Change 到 SSI/Vendor/BP，触发 XCD/DCD 编译，轮询进度 |
每一步都有独立的进度条和日志窗口，可实时查看。第 ④ 步失败时会自动重试一次，仍失败可点击 「重试步骤 4」 按钮单独重跑。
6.3 发版完成
发版完成后弹出结果弹窗，含 Gerrit 和 Grapple 平台的可点击超链接，可直接跳转查看。
也可以点 「一键复制」 复制发版信息到剪贴板发给别人。
七、其他常用功能
7.1 左侧栏底部功能按钮
| 按钮 | 作用 |
|---|---|
| + 添加项目 | 新增一个项目（见第二章） |
| 历史记录 | 查看过往所有发版记录，含每次的版本号、结果、Gerrit / Grapple 链接 |
| 日志 | 打开右侧抽屉查看实时日志（可按 trace_id / 级别 / 模块过滤） |
| 配置 IO | 导入 / 导出全部配置 JSON |
| 退出服务 | 停止本地后端服务并退出（安全关闭） |
7.2 配置导入 / 导出
- 导出 —— 把
~/.onekey-publish/config.json下载下来，可分享给同事或备份。默认不含凭证，需要连凭证一起导出请勾选「包含敏感凭证」。 - 导入 —— 从 JSON 文件恢复配置。导入会完全覆盖当前配置，导入前记得先导出备份。发版进行中且未到 Grapple 阶段时，会拒绝导入以防产物错乱。
7.3 历史记录
每次发版都会自动记录（最多保留 100 条），包含：
- 项目名、分支、版本号、发版时间
- 每一步是否成功
- Gerrit / Grapple 平台链接
点击列表中某一条即可查看详情。
八、常见问题速查
❓ Q1：改了配置为什么没保存？ A：中间区的改动要点 「保存配置」，右侧栏的改动要点 「保存凭证」 或 「保存 Token」。按钮变灰显示「配置无变更」就说明已保存。
❓ Q2：发版第 ② 步 Gradle 编译失败？ A：优先检查右侧栏的 Artifactory 用户名/密码是否正确，以及「凭证注入文件」路径是否与业务仓库中 Gradle 脚本读取的变量名匹配。
❓ Q3：Grapple 编译一直失败？ A：确认右侧栏 Grapple Token 已替换为自己的（不要用默认 Token）；确认车型和分支线选择正确；点 「重试步骤 4」 单独重跑。
❓ Q4：想把配置分享给同事？ A：左侧栏 → 配置 IO → 导出（不要勾选「包含敏感凭证」）→ 把 JSON 发给同事 → 同事导入即可。凭证和 Token 让对方自己填。
❌ Q5：不小心删错了项目/分支怎么办？ A：删除不可撤销。养成习惯：动手改配置前先「配置 IO → 导出」备份 JSON。
附录：完整界面结构图
祝发版愉快 🚀