name	release
description	发布 OpenMate 新版本。当用户提到"发布"、"release"、"打版本"、"版本发布"、"新版本"时触发。更新版本号与 CHANGELOG，打 git 标签并推送，由 GitHub Actions 自动构建全平台产物并创建 Release。Release 成功后更新 version.json 并清除 CDN 缓存。

OpenMate 发布流程

发布 = 更新版本号 + 编写 CHANGELOG + 打 tag 并 push + CI 构建 + 更新 version.json + 清 CDN 缓存。

关键约束：version.json 必须在 GitHub Release 创建且产物上传完成之后再更新并推送，否则用户触发更新时会下载到尚不存在的产物。

步骤

确认版本号
- 读取当前版本：D:\openmate\opencode-bridge\Cargo.toml 的 version 字段
- 提示用户确认或输入新版本号（如 0.2.0）
- Bridge 和 Android 版本号保持一致
确认 git 工作区干净
- 运行 git status --short
- 如有未提交的变更，先提示用户处理，不要自动提交无关变更
更新版本号
- D:\openmate\opencode-bridge\Cargo.toml 的 version
- D:\openmate\android\app\build.gradle.kts 的 versionName，并将 versionCode +1
编写 CHANGELOG
- 读取项目根目录 CHANGELOG.md，了解现有格式（中文，只描述 Bridge 和 Android 变更，其他组件不描述）
- 运行 git log v{上一个tag}..HEAD --oneline --no-merges 获取本次变更
- 筛选原则：只记录用户已发布版本中遇到的问题修复；开发过程中发现并修复的 bug（用户从未遇到过）不写入
- 人工精炼变更条目：将技术性 commit 归纳为用户可读的中文描述，按"新功能"/"问题修复"分类
- 每条以 **关键词**： 开头，简洁说明功能或修复内容
- 不描述尚未正式测试支持的平台（如 macOS）
- 在 CHANGELOG.md 顶部（# Changelog 标题之后）插入新版本条目，保留所有历史版本
- 格式模板：
```
## {版本号}

Released: {yyyy-MM-dd}

### 新功能

- **功能名**：描述

### 问题修复

- 修复描述
```
提交版本号与 CHANGELOG
- git add opencode-bridge/Cargo.toml opencode-bridge/Cargo.lock android/app/build.gradle.kts CHANGELOG.md
- git commit -m "release: v{版本号}"
打 tag 并推送（触发 CI）
- git tag v{版本号}
- git push origin main
- git push origin v{版本号} —— push 该 tag 即触发 release.yml
- 如遇网络问题，确认 git 已配置代理：git config http.proxy / git config https.proxy
监控 CI 构建
- gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId') --exit-status
- 确认 6 个构建 job 全部成功：
  - Android APK
  - Bridge (Windows)
  - Bridge (Linux x86_64, musl 静态)
  - Bridge (Linux arm64, musl 静态)
  - Bridge (macOS, Apple Silicon)
  - Relay Gateway (Linux)
- 全部成功后，release job 会自动创建 GitHub Release 并上传所有产物（generate_release_notes: true）
- 如有 job 失败，不打断：报告失败原因，修复后重新打 tag（需先删除旧 tag）
验证 Release
- gh release view v{版本号} 确认 Release 已创建且产物完整
- 核对产物清单（见下）
更新 version.json（Release 成功后）
- 必须在 GitHub Release 创建且产物上传完成之后执行此步骤
- 编辑 D:\openmate\version.json，将 android 和 bridge 的 version、tag、releasedAt 更新为新版本
- 示例：
```
{
  "android": {"version": "0.2.0", "tag": "v0.2.0", "releasedAt": "2026-06-16"},
  "bridge": {"version": "0.2.0", "tag": "v0.2.0", "releasedAt": "2026-06-16"}
}
```
- git add version.json && git commit -m "chore: update version.json to v{版本号}"
- git push origin main
同步 version.json 到 Gateway 服务器
- scp D:\openmate\version.json root@gateway.clawmate.net:/data/relay-gateway/static/version.json
- 这确保客户端通过 https://gateway.clawmate.net/version.json（主源）立即获取到新版
- nginx 已配置 Cache-Control: no-store，无需额外清缓存

CI 产物清单

release job 自动上传到 GitHub Release 的文件：

文件	说明
`OpenMate-{version}.apk`	Android 客户端
`openmate.exe`	Bridge, Windows
`openmate-linux-x86_64`	Bridge, Linux x86_64（musl 静态，兼容所有发行版）
`openmate-linux-arm64`	Bridge, Linux arm64（musl 静态）
`openmate-darwin-arm64`	Bridge, macOS Apple Silicon
`relay-gateway-linux-x86_64`	Relay Gateway, Linux

Linux 二进制为 musl 静态链接，不依赖目标系统的 glibc/openssl，可在任意 Linux 发行版上运行。

版本号规则

Bridge 和 Android 版本号保持一致
版本号来源以 Cargo.toml 为准
git 标签格式：v{版本号}（如 v0.2.0）
commit 消息格式：release: v{版本号}
versionCode 每次发布递增 1，versionName 与 Cargo.toml 的 version 一致
version.json 在每次发布后手动更新，仅更新有变更的模块

version.json 与自动更新机制

version.json 位于仓库根目录，按模块记录最新发布版本
客户端通过 Gateway 服务器（主）和 raw.githubusercontent.com（备）读取该文件判断是否有更新
Gateway 服务器：https://gateway.clawmate.net/version.json，nginx 配置 Cache-Control: no-store，无缓存问题
raw.githubusercontent.com 无缓存，几乎实时，作为 fallback 兜底
每次发布后必须 scp version.json 到 Gateway 服务器（步骤 10）

注意事项

构建完全由 GitHub Actions 负责，无需本地 Rust/Android/WSL 编译环境
tag v* 是 release.yml 的唯一触发条件；push 普通 commit 到 main 不会触发发布
GitHub Release 的 release notes 由 generate_release_notes: true 自动生成（基于 commits/PRs）；项目根目录 CHANGELOG.md 是手动维护的详细中文变更日志，两者并存
Android keystore 在 D:\openmate\android\release.keystore，密码在 local.properties，这两个文件已在 .gitignore 中，不要提交
GitHub Actions 的 secrets（RELEASE_STORE_PASSWORD、RELEASE_KEY_PASSWORD）需在仓库 Settings → Secrets 中配置，用于 CI 签名 APK
严禁在 Release 创建前更新 version.json，否则用户会看到有新版本但下载失败

OpenMate 发布流程

发布 = 更新版本号 + 编写 CHANGELOG + 打 tag 并 push + CI 构建 + 更新 version.json + 清 CDN 缓存。

关键约束：version.json 必须在 GitHub Release 创建且产物上传完成之后再更新并推送，否则用户触发更新时会下载到尚不存在的产物。

步骤

确认版本号

读取当前版本：D:\openmate\opencode-bridge\Cargo.toml 的 version 字段
提示用户确认或输入新版本号（如 0.2.0）
Bridge 和 Android 版本号保持一致

确认 git 工作区干净

运行 git status --short
如有未提交的变更，先提示用户处理，不要自动提交无关变更

更新版本号

D:\openmate\opencode-bridge\Cargo.toml 的 version
D:\openmate\android\app\build.gradle.kts 的 versionName，并将 versionCode +1

编写 CHANGELOG

读取项目根目录 CHANGELOG.md，了解现有格式（中文，只描述 Bridge 和 Android 变更，其他组件不描述）
运行 git log v{上一个tag}..HEAD --oneline --no-merges 获取本次变更
筛选原则：只记录用户已发布版本中遇到的问题修复；开发过程中发现并修复的 bug（用户从未遇到过）不写入
人工精炼变更条目：将技术性 commit 归纳为用户可读的中文描述，按"新功能"/"问题修复"分类
每条以 **关键词**： 开头，简洁说明功能或修复内容
不描述尚未正式测试支持的平台（如 macOS）
在 CHANGELOG.md 顶部（# Changelog 标题之后）插入新版本条目，保留所有历史版本

格式模板：

## {版本号}

Released: {yyyy-MM-dd}

### 新功能

- **功能名**：描述

### 问题修复

- 修复描述

提交版本号与 CHANGELOG

git add opencode-bridge/Cargo.toml opencode-bridge/Cargo.lock android/app/build.gradle.kts CHANGELOG.md
git commit -m "release: v{版本号}"

打 tag 并推送（触发 CI）

git tag v{版本号}
git push origin main
git push origin v{版本号} —— push 该 tag 即触发 release.yml
如遇网络问题，确认 git 已配置代理：git config http.proxy / git config https.proxy

监控 CI 构建

gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId') --exit-status
确认 6 个构建 job 全部成功：
- Android APK
- Bridge (Windows)
- Bridge (Linux x86_64, musl 静态)
- Bridge (Linux arm64, musl 静态)
- Bridge (macOS, Apple Silicon)
- Relay Gateway (Linux)
全部成功后，release job 会自动创建 GitHub Release 并上传所有产物（generate_release_notes: true）
如有 job 失败，不打断：报告失败原因，修复后重新打 tag（需先删除旧 tag）

验证 Release

gh release view v{版本号} 确认 Release 已创建且产物完整
核对产物清单（见下）

更新 version.json（Release 成功后）

必须在 GitHub Release 创建且产物上传完成之后执行此步骤
编辑 D:\openmate\version.json，将 android 和 bridge 的 version、tag、releasedAt 更新为新版本

示例：

{
  "android": {"version": "0.2.0", "tag": "v0.2.0", "releasedAt": "2026-06-16"},
  "bridge": {"version": "0.2.0", "tag": "v0.2.0", "releasedAt": "2026-06-16"}
}

git add version.json && git commit -m "chore: update version.json to v{版本号}"
git push origin main

同步 version.json 到 Gateway 服务器

scp D:\openmate\version.json root@gateway.clawmate.net:/data/relay-gateway/static/version.json
这确保客户端通过 https://gateway.clawmate.net/version.json（主源）立即获取到新版
nginx 已配置 Cache-Control: no-store，无需额外清缓存

CI 产物清单

release job 自动上传到 GitHub Release 的文件：

文件

说明

OpenMate-{version}.apk

Android 客户端

openmate.exe

Bridge, Windows

openmate-linux-x86_64

Bridge, Linux x86_64（musl 静态，兼容所有发行版）

openmate-linux-arm64

Bridge, Linux arm64（musl 静态）

openmate-darwin-arm64

Bridge, macOS Apple Silicon

relay-gateway-linux-x86_64

Relay Gateway, Linux

Linux 二进制为 musl 静态链接，不依赖目标系统的 glibc/openssl，可在任意 Linux 发行版上运行。

版本号规则

Bridge 和 Android 版本号保持一致

版本号来源以 Cargo.toml 为准

git 标签格式：v{版本号}（如 v0.2.0）

commit 消息格式：release: v{版本号}

versionCode 每次发布递增 1，versionName 与 Cargo.toml 的 version 一致

version.json 在每次发布后手动更新，仅更新有变更的模块

version.json 与自动更新机制

version.json 位于仓库根目录，按模块记录最新发布版本

客户端通过 Gateway 服务器（主）和 raw.githubusercontent.com（备）读取该文件判断是否有更新

Gateway 服务器：https://gateway.clawmate.net/version.json，nginx 配置 Cache-Control: no-store，无缓存问题

raw.githubusercontent.com 无缓存，几乎实时，作为 fallback 兜底

每次发布后必须 scp version.json 到 Gateway 服务器（步骤 10）

注意事项

构建完全由 GitHub Actions 负责，无需本地 Rust/Android/WSL 编译环境

tag v* 是 release.yml 的唯一触发条件；push 普通 commit 到 main 不会触发发布

GitHub Release 的 release notes 由 generate_release_notes: true 自动生成（基于 commits/PRs）；项目根目录 CHANGELOG.md 是手动维护的详细中文变更日志，两者并存

Android keystore 在 D:\openmate\android\release.keystore，密码在 local.properties，这两个文件已在 .gitignore 中，不要提交

GitHub Actions 的 secrets（RELEASE_STORE_PASSWORD、RELEASE_KEY_PASSWORD）需在仓库 Settings → Secrets 中配置，用于 CI 签名 APK

严禁在 Release 创建前更新 version.json，否则用户会看到有新版本但下载失败