automate publishing: release github + release pypi

docs/publishing.md

@@ -120,24 +120,62 @@ python build/run.py verify --gui-dist --product ory_finger
 
 ---
 
-## 3. 发布（目前仍需人工）
+## 3. 发布（两条命令）
 
-阶段一不包含自动发布。当前人工步骤：
-
-1. 用 `release preflight` 拿到 PASS（并保留 `preflight.json`）。
-2. 把 `SDK/<version>/` 同步到 `orisys-sdk-release` 仓库的 `release/<version>/`。
-3. GitHub：打 tag **`v<version>`** 并创建 Release，上传 6 个 wheel 作为附件。
-   - 注意历史 tag 里有一个 typo：`0.50`（与 `v0.5.1` 指向同一 commit）。
-4. PyPI：先 TestPyPI 再正式仓库。
+先决条件：`release preflight` PASS，**而且是在干净提交上跑的**。两个发布命令都只发布「preflight 认证过的东西」——它们会读取 `build/release/reports/<version>/preflight.json`，逐个核对 wheel 的 sha256，并拒绝使用带豁免项（`--skip-tests` / `--allow-dirty` / `--no-runtime` / `--force`）的报告。所以正确顺序是：
 
 ```powershell
-python -m twine upload --repository testpypi SDK/<version>/*.whl
-python -m twine upload SDK/<version>/*.whl
+git add -A; git commit -m "..."
+python build/run.py wheel-win && python build/run.py manylinux
+python build/run.py release preflight --all-wheel-pythons --check-pypi   # 干净树 + 无豁免
 ```
 
-**不要把 API token 写进仓库**。`release preflight --check-pypi` 只做只读查询，不需要 token。
+两个命令**默认都是 dry run**，只打印将要执行的动作；必须显式加 `--apply` 才会真正动手。GitHub 的 `gh release create`、`git push`，以及 PyPI 上传（版本号永久占用、不可覆盖）都属于不可撤销操作。
 
-### 已知的历史发布空洞
+### 3.1 GitHub：同步公开仓库 + 上传 Release
+
+```powershell
+python build/run.py release github --version 0.5.2              # 预览
+python build/run.py release github --version 0.5.2 --apply      # 执行
+```
+
+执行顺序：
+
+1. 认证书校验（上面那份报告 + 逐 wheel sha256）
+2. `git fetch --tags`，若 `v0.5.2` 或 `0.5.2` 已存在则拒绝；`gh release view` 已存在也拒绝
+3. 按 `tools/downstream_sync_manifest.json` 同步公开内容到 `../orisys-sdk-release`，并运行 manifest 里的 `checks`
+4. 把 `SDK/0.5.2/*.whl` 放到 `orisys-sdk-release/release/0.5.2/`（该目录在 release 仓库里是 gitignore 的，只用于上传附件）
+5. 提交 → 打 tag `v0.5.2` → push 分支与 tag
+6. `gh release create v0.5.2 --verify-tag --latest <6 个 wheel>`，然后回读 `gh release view --json assets` 核对附件齐全
+
+需要：`gh` 已安装并登录（`winget install --id GitHub.cli` 然后 `gh auth login`）。没装 gh 时：
+
+- dry run 仍会完整打印计划（只告警）
+- `--apply` 会失败，或改用 `--skip-release-upload`：同步、提交、打 tag、push 都自动完成，然后打印出你自己要跑的 `gh release create`
+
+其他开关：`--notes-file`（自定义 release notes）、`--attach-preflight`（把 `preflight.json` 也作为附件上传，便于审计；注意报告里有本机绝对路径）、`--allow-dirty-release`、`--skip-fetch`、`--skip-checks`。
+
+> tag 拼写沿用历史风格 `v<version>`（注意历史里那个 typo tag `0.50` 指向 `v0.5.1`）。命令会在动手前拒绝已存在的 tag，所以不会重复发布。
+
+### 3.2 PyPI：TestPyPI 先行，确认后再上正式仓库
+
+```powershell
+python build/run.py release pypi --version 0.5.2                          # 预览
+python build/run.py release pypi --version 0.5.2 --apply                  # 只发 TestPyPI
+python build/run.py release pypi --version 0.5.2 --confirm-pypi --apply   # TestPyPI + 正式 PyPI
+```
+
+执行顺序：
+
+1. 同样的证书校验
+2. `twine check` 全部 wheel（校验 METADATA/long description，上传前就能发现问题）
+3. 只读查询目标索引，确认该版本不存在（TestPyPI 与 PyPI 各查各的）
+4. 上传 TestPyPI → 回读索引确认 6 个文件都在 → `pip download` 把刚上传的 wheel 拉回来，证明产物可获取
+5. 只有加了 `--confirm-pypi` 才会对正式 PyPI 重复第 3-4 步；否则停在这里并打印后续命令
+
+凭证由 twine 自己解析：`~/.pypirc` 的 `[testpypi]` / `[pypi]` 段，或 `TWINE_USERNAME=__token__` + `TWINE_PASSWORD=<token>`。命令会在**任何写操作之前**检查凭证是否配置好并给出提示。**不要把 token 写进仓库。**
+
+### 3.3 已知的历史发布空洞
 
 | 版本 | 本地 `SDK/` | PyPI | GitHub Release |
 | --- | --- | --- | --- |