# CraftLabs 授权 SDK — 发布与完整性

对齐架构文档 [SYSTEM_ARCHITECTURE §9.8](../docs/engineering/SYSTEM_ARCHITECTURE.md)：官方渠道、**SHA-256 清单**、**GPG 签名（建议）**、`java` 与 `native` **同 Git tag**。

## 1. 发布前检查

- [ ] `mvn -f java/pom.xml verify` 通过（JDK 17+）。
- [ ] `native` 已在各目标平台完成构建，且与本次 **同一 tag** 一并交付。
- [ ] `CHANGELOG`（或发布说明）写明 **比特 SDK / 运行时** 兼容版本。

## 2. 生成 SHA256SUMS（必做）

在仓库根目录执行（会先 `mvn -DskipTests package`）：

```bash
chmod +x scripts/sdk-release-checksums.sh
./scripts/sdk-release-checksums.sh --output dist/sdk-release
```

已构建过时跳过 Maven：

```bash
./scripts/sdk-release-checksums.sh --no-mvn --output dist/sdk-release
```

把 **本机构建出的 Native** 一并写入清单（路径相对于仓库根，便于客户校验）：

```bash
./scripts/sdk-release-checksums.sh --output dist/sdk-release --native-path "$(pwd)/native/build"
```

含完整测试的构建后再生成清单：

```bash
./scripts/sdk-release-checksums.sh --verify --output dist/sdk-release
```

输出：

- `dist/sdk-release/SHA256SUMS` — 每行：`哈希  相对路径`
- `dist/sdk-release/RELEASE-MANIFEST.txt` — 提交 SHA、UTC 时间

**客户校验**（在克隆/解压后的仓库根或同目录结构下）：

```bash
sha256sum -c dist/sdk-release/SHA256SUMS
```

macOS：

```bash
shasum -a 256 -c dist/sdk-release/SHA256SUMS
```

对 `SHA256SUMS` 本身做 **分离签名**（本机已配置 GPG）：

```bash
SIGN=1 ./scripts/sdk-release-checksums.sh --no-mvn --output dist/sdk-release
```

生成 `SHA256SUMS.asc`；客户使用公布的公钥：`gpg --verify SHA256SUMS.asc SHA256SUMS`。

## 3. Maven JAR 的 GPG 签名（强烈建议）

父 POM 已配置 `maven-gpg-plugin`，**默认跳过**（`gpg.skip=true`），不影响日常 `verify`。

发布前在已导入私钥的机器上：

```bash
gpg --version   # 确认可用
mvn -f java/pom.xml -Prelease-sign verify
```

各 **可发布模块**（`craftlabs-auth-core`、`craftlabs-auth-bitanswer`、`craftlabs-auth-selfhosted`）的 `target/*.jar` 旁会出现 **`.asc`**。`craftlabs-auth-tests` 模块固定 **不签名**。

若无私钥或未就绪，可只发 **SHA256SUMS**；待密钥就绪后再打开 `-Prelease-sign`。

### CI / 无人值守（可选）

在构建机配置 `MAVEN_GPG_PASSPHRASE` 等环境变量，或使用 `gpg-agent`；勿将私钥提交仓库。GitHub Actions 可用 `GPG_PRIVATE_KEY` secret + [crazy-max/ghaction-import-gpg](https://github.com/crazy-max/ghaction-import-gpg) 导入后再执行 `mvn -Prelease-sign verify`。

## 4. GitHub Release 建议资产

每个 **tag** 上传：

1. 三个 **release JAR**（及对应 **.asc**，若已签名）
2. 各平台 **Native** 压缩包
3. **`SHA256SUMS`** 与 **`SHA256SUMS.asc`**
4. 固定页面公布 **GPG 公钥指纹** 与下载说明

---

版权所有 © 广州创飞人工智能技术有限公司（以项目实际声明为准）。