docs(release): align public preview downloads and desktop packaging

.github/workflows/release-desktop.yml

@@ -21,6 +21,8 @@ on:
       # Product/dependency changes are checked by central CI. PR packaging
       # validates changes to the release machinery and distribution inputs.
       - '.github/workflows/release-desktop.yml'
+      - 'scripts/check-download-docs.py'
+      - 'scripts/test_download_docs.py'
       - 'cmd/packagede2e/**'
       - 'cmd/producte2e/**'
       - 'cmd/releasegate/**'
@@ -142,6 +144,19 @@ jobs:
           "phase=$phase" >> $env:GITHUB_OUTPUT
           "signing_prepare=$($signingPrepare.ToString().ToLowerInvariant())" >> $env:GITHUB_OUTPUT
 
+      - name: Check public download documentation before release work
+        shell: pwsh
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          RELEASE_VERSION: ${{ steps.release.outputs.version }}
+        run: |
+          $arguments = @('-B', 'scripts/check-download-docs.py')
+          if ($env:EVENT_NAME -ceq 'push') { $arguments += @('--version', $env:RELEASE_VERSION) }
+          python @arguments
+          if ($LASTEXITCODE -ne 0) { throw "Update both READMEs and platform download guides before publishing" }
+          python -B -m unittest discover -s scripts -p test_download_docs.py -v
+          if ($LASTEXITCODE -ne 0) { throw "Download documentation regression checks failed" }
+
       - name: Require successful full central CI for the exact release revision
         if: ${{ github.event_name != 'pull_request' }}
         shell: pwsh
@@ -1071,6 +1086,15 @@ jobs:
             if ($env:IS_PRERELEASE -ceq 'false') { $verify += '--require-release-ready' }
             python @verify
             if ($LASTEXITCODE -ne 0) { throw "Mac archive verification failed: $arch" }
+            $dmgDirectory = "build/macos-dmg/$arch"
+            gh run download $env:GITHUB_RUN_ID --repo $env:GITHUB_REPOSITORY `
+              --name "TraverseBoard-macos-dmg-$arch-$env:RELEASE_REVISION" --dir $dmgDirectory
+            if ($LASTEXITCODE -ne 0) { throw "Exact Mac DMG download failed: $arch" }
+            $dmgName = "TraverseBoard-$env:RELEASE_VERSION-macos-$arch-$($env:RELEASE_REVISION.Substring(0,12))-preview.dmg"
+            $dmgPath = Join-Path $dmgDirectory $dmgName
+            $expectedChecksum = (Get-FileHash -Algorithm SHA256 -LiteralPath $dmgPath).Hash.ToLowerInvariant() + "  " + $dmgName
+            $checksum = [System.IO.File]::ReadAllText("$dmgPath.sha256").TrimEnd([char[]]"`r`n")
+            if ($checksum -cne $expectedChecksum) { throw "Mac DMG checksum differs: $arch" }
           }
 
       - name: Download stable Store submission from this run
@@ -1280,7 +1304,7 @@ jobs:
           $assets = @(
             "build/public/TraverseBoard.exe",
             "build/desktop/direct-exe-signing.json",
-            "build/desktop/SHA256SUMS",
+            "build/public/SHA256SUMS",
             "build/desktop/release-metadata.json",
             "build/desktop/windows-compatibility.json",
             "build/desktop/standard-code-packaged-e2e.json",
@@ -1312,12 +1336,16 @@ jobs:
             $assets += Join-Path build/attestations $bundleName
           }
           $macRevision = '${{ needs.portable-zip.outputs.revision }}'
+          $publicChecksums = [System.IO.File]::ReadAllText('build/desktop/SHA256SUMS').TrimEnd([char[]]"`r`n")
           foreach ($arch in @('arm64', 'amd64')) {
             $stem = "TraverseBoard-$env:RELEASE_VERSION-macos-$arch-$($macRevision.Substring(0,12))-preview"
             foreach ($extension in @('.zip', '.manifest.json', '.sha256')) {
               $assets += "build/macos/$arch/$stem$extension"
             }
+            $assets += "build/macos-dmg/$arch/$stem.dmg", "build/macos-dmg/$arch/$stem.dmg.sha256"
+            $publicChecksums += "`n" + [System.IO.File]::ReadAllText("build/macos-dmg/$arch/$stem.dmg.sha256").TrimEnd([char[]]"`r`n")
           }
+          [System.IO.File]::WriteAllText('build/public/SHA256SUMS', $publicChecksums + "`n", [System.Text.UTF8Encoding]::new($false))
           foreach ($asset in $assets) {
             if (-not (Test-Path -LiteralPath $asset -PathType Leaf)) {
               throw "Release asset is missing: $asset"
@@ -1412,6 +1440,15 @@ jobs:
               $missing.Count -ne 0) {
             throw "Published release asset inventory differs from the exact public allowlist"
           }
+          # Validate documented links against the uploaded draft before making
+          # it public. Missing EXE/checksums/either DMG keeps the release private.
+          $releaseJSON = gh api "repos/$env:GITHUB_REPOSITORY/releases/tags/$env:RELEASE_VERSION"
+          if ($LASTEXITCODE -ne 0) { throw "Download entry point asset readback failed" }
+          [System.IO.File]::WriteAllText('build/public/download-release.json', ($releaseJSON | Out-String), [System.Text.UTF8Encoding]::new($false))
+          python -B scripts/check-download-docs.py `
+            --version $env:RELEASE_VERSION --revision $macRevision `
+            --release-json build/public/download-release.json --allow-draft
+          if ($LASTEXITCODE -ne 0) { throw "Public download entry points do not match the release assets" }
           $publish = @(
             "release", "edit", $env:RELEASE_VERSION,
             "--repo", $env:GITHUB_REPOSITORY,

CONTRIBUTING.md

@@ -88,6 +88,19 @@ export CYBERAGENT_API_CONTROL_TOKEN="local-control-token"
 
 ---
 
+## 发行下载入口维护
+
+准备发布时，同步 `README.md`、`README.en.md`、`docs/windows-release.md`、`docs/macos-release.md` 中 `public-downloads` 标记内的版本、日期、下载与启动说明，再运行：
+
+```sh
+python -B scripts/check-download-docs.py
+python -B -m unittest discover -s scripts -p test_download_docs.py -v
+```
+
+每个入口必须使用同一个明确的 Release tag；`/releases/latest` 不包含预发布，不能作为预览版入口。Windows 链接指向 `TraverseBoard.exe`，Mac 按 `macos-arm64` / `macos-amd64` 选择 DMG。Release 页负责展示包含源码 revision 的完整文件名，避免在源码文档中预先引用该提交自身的 hash。
+
+发布 tag 时，Desktop release 工作流会要求四份文档的版本等于待发布版本；上传 Draft 资产后，还会确认 EXE、校验和及两个架构的 DMG 均已上传、非空，且 DMG 文件名绑定本次版本与源码 revision。任何入口或资产不一致都会阻止公开发布。Actions 测试候选另列，保留其登录与过期说明。
+
 ## OpenAPI 契约与 DTO 代码生成
 
 Universal-Code 以 **Go 结构体与路由定义作为 API 的唯一真相来源 (Single Source of Truth)**。

README.en.md

@@ -42,12 +42,18 @@
 
 ### Option 1: Download Pre-built Binaries
 
-| OS | Instructions |
+<!-- public-downloads:start -->
+Current public preview: [**v1.0.0-preview.20261020**](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases/tag/v1.0.0-preview.20261020), published on 2026-10-20.
+
+| OS | Download and launch |
 | :--- | :--- |
-| **Windows 10/11** | Get the current Actions test package and launch steps from the [Windows download guide](docs/windows-release.md). The executable is named `TraverseBoard.exe`; double-click it to launch. Edge WebView2 Runtime is required. The newest public Release remains the [older preview from 2026-09-05](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases/tag/v0.1.0-pr195-preview). |
-| **macOS (Apple Silicon / Intel)** | Get the Actions preview ZIP for your architecture from the [macOS download guide](docs/macos-release.md), unpack it, and open `TraverseBoard.app`. It is ad-hoc signed and unnotarized. Public Releases do not yet contain Mac packages. |
+| **Windows x64** | Download [TraverseBoard.exe](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases/download/v1.0.0-preview.20261020/TraverseBoard.exe) and double-click it. Edge WebView2 Runtime is required. See the [Windows download guide](docs/windows-release.md). |
+| **macOS Apple Silicon / Intel** | In [Release Assets](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases/tag/v1.0.0-preview.20261020), choose the `.dmg` containing `macos-arm64` (Apple Silicon) or `macos-amd64` (Intel), then drag `TraverseBoard.app` into Applications. See the [macOS download guide](docs/macos-release.md). |
+
+Public Release downloads require no GitHub login and are not subject to Actions artifact retention limits. Verify downloads against [SHA256SUMS](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases/download/v1.0.0-preview.20261020/SHA256SUMS) on the same release. The Windows EXE is unsigned; Mac apps are ad-hoc signed and unnotarized, so the OS may block the first launch. This is a preview; see the release notes for verified scope and known issues.
+<!-- public-downloads:end -->
 
-Use the [Desktop release run list](https://github.com/CWNU-Open-Source-Community/Universal-Code/actions/workflows/release-desktop.yml) as the ongoing candidate entry point. Actions downloads require a GitHub login and expire. Each platform guide records the candidate version, source revision, and expiry date.
+For test candidates newer than the public preview, use the [Desktop release run list](https://github.com/CWNU-Open-Source-Community/Universal-Code/actions/workflows/release-desktop.yml) and check the version and source revision. Actions downloads require a GitHub login and expire.
 Packages retain their historical filenames; the product name shown in the application is Universal-Code.
 
 ### Option 2: Build from Source

README.md

@@ -42,13 +42,19 @@
 
 ### 方式一：下载预编译客户端
 
+<!-- public-downloads:start -->
+当前公开预览版：[**v1.0.0-preview.20261020**](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases/tag/v1.0.0-preview.20261020)（2026-10-20 发布）。
+
 | 平台 | 下载与运行说明 |
 | :--- | :--- |
-| **Windows 10/11** | 当前 Actions 测试包及启动步骤见 [Windows 下载说明](docs/windows-release.md)。实际文件名为 `TraverseBoard.exe`，双击运行，需 Edge WebView2 Runtime。最新公开 Release 仍是 [2026-09-05 的旧预览](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases/tag/v0.1.0-pr195-preview)。 |
-| **macOS (Apple Silicon / Intel)** | 从 [macOS 下载说明](docs/macos-release.md) 获取对应架构的 Actions 预览 ZIP，解包后打开 `TraverseBoard.app`。当前仅有 ad-hoc 签名，未公证；公开 Release 尚无 Mac 包。 |
+| **Windows x64** | 下载 [TraverseBoard.exe](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases/download/v1.0.0-preview.20261020/TraverseBoard.exe)，双击运行；需要 Edge WebView2 Runtime。详见 [Windows 下载说明](docs/windows-release.md)。 |
+| **macOS Apple Silicon / Intel** | 在 [Release Assets](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases/tag/v1.0.0-preview.20261020) 中选择名称含 `macos-arm64`（M 系列）或 `macos-amd64`（Intel）的 `.dmg`，将 `TraverseBoard.app` 拖入 Applications。详见 [macOS 下载说明](docs/macos-release.md)。 |
+
+公开 Release 下载无需登录 GitHub，不受 Actions artifact 保留期限限制；可用同页的 [SHA256SUMS](https://github.com/CWNU-Open-Source-Community/Universal-Code/releases/download/v1.0.0-preview.20261020/SHA256SUMS) 核对文件。Windows EXE 未签名，Mac 包仅 ad-hoc 签名、未经 Apple 公证，首次启动可能被系统阻止。这是预览版，验证范围与已知问题以 Release 说明为准。
+<!-- public-downloads:end -->
 
-持续更新的候选入口为 [Desktop release 打包记录](https://github.com/CWNU-Open-Source-Community/Universal-Code/actions/workflows/release-desktop.yml)。Actions 下载需要登录 GitHub，且有保留期限；对应版本、源码提交和到期时间见平台说明。
-测试包沿用历史文件名，窗口中的产品名为 Universal-Code。
+需要比公开预览更新的测试候选时，查看 [Desktop release 打包记录](https://github.com/CWNU-Open-Source-Community/Universal-Code/actions/workflows/release-desktop.yml)，核对版本与源码提交。Actions 下载需要登录 GitHub，且会过期。
+文件保留历史名称，窗口中的产品名为 Universal-Code。
 
 ### 方式二：从源码构建运行