feat(release): PKG-2A PG 二进制分发源——上游直拉,零配置产物含嵌入式 PG

.gitattributes

@@ -4,3 +4,6 @@
 
 # PowerShell 脚本固定 CRLF（仅在 Windows runner 运行）。
 *.ps1 text eol=crlf
+
+# upstream.lock 被 bash 按行解析（fetch-binaries.sh lock_get），CRLF 会让 URL/SHA 带 \r 尾巴。
+scripts/pg/upstream.lock text eol=lf

.github/workflows/ci.yml

@@ -149,3 +149,6 @@ jobs:
           git config --global user.email "ci@inkframe.test"
           git config --global user.name "InkFrame CI"
           bash test/scripts/release_tag_test.sh
+      # fetch-binaries.sh 回归测试（PKG-2A：upstream/bucket 双模式，curl/brew 全 PATH-stub 零网络）。
+      - name: fetch-binaries.sh regression test
+        run: bash test/scripts/fetch_binaries_test.sh

.github/workflows/release.yml

@@ -9,8 +9,10 @@
 #   release 已存在则更新并追加资产，不覆盖 release-tag.sh 生成的 notes。
 #
 # 「证书/存储就绪前」一切可跑：
-#   - PG 二进制 fetch：仅当 repo variable PG_ARTIFACT_BASE_URL 配置时执行；缺则 ::warning::
-#     并继续（产物不含嵌入式 PG，无法在干净机首启 PG，仅供构建/链接验证）。
+#   - PG 二进制 fetch：默认 upstream 直拉（PKG-2A 方案 A——Windows=EDB 官方 zip 按
+#     scripts/pg/upstream.lock SHA256 锁定；macOS=runner Homebrew postgresql@17 +
+#     make-relocatable），零配置即产出含嵌入式 PG 的安装物；repo variable
+#     PG_ARTIFACT_BASE_URL 配置时切对象存储（方案 B 覆盖）。
 #   - 签名/公证/MSIX 签名：脚本自检环境，缺凭据 → 打印 SKIPPED 退出 0，不阻断。
 #   - 原始构建产物（zip 的 .app / Release 目录）无条件上传，零密钥也有可下载工件。
 name: release
@@ -63,17 +65,17 @@ jobs:
           fi
           echo "BUILD_NUMBER=${GITHUB_RUN_NUMBER}" >> "$GITHUB_ENV"
       - name: cache PG binaries
-        if: ${{ vars.PG_ARTIFACT_BASE_URL != '' }}
         uses: actions/cache@v4
         with:
           path: macos/Runner/Resources/pg/
-          key: pg-${{ hashFiles('scripts/pg/pg-version.txt') }}-macos-arm64
+          key: pg-${{ hashFiles('scripts/pg/pg-version.txt', 'scripts/pg/upstream.lock') }}-${{ vars.PG_ARTIFACT_BASE_URL != '' && 'bucket' || 'upstream' }}-macos-arm64
+      # 不以 cache-hit 门控：缓存树若未过脚本校验会走重建路径，届时必须有 brew keg 兜底
+      #（否则坏缓存 = 每次 re-run 恢复同一份坏树的死循环）。主版本从 pg-version.txt 推导。
+      - name: install upstream PostgreSQL (Homebrew)
+        if: ${{ vars.PG_ARTIFACT_BASE_URL == '' }}
+        run: brew install "postgresql@$(cut -d. -f1 scripts/pg/pg-version.txt)"
       - name: fetch embedded PG binaries
-        if: ${{ vars.PG_ARTIFACT_BASE_URL != '' }}
         run: bash scripts/pg/fetch-binaries.sh
-      - name: warn — PG not bundled
-        if: ${{ vars.PG_ARTIFACT_BASE_URL == '' }}
-        run: echo "::warning title=PG not bundled::PG_ARTIFACT_BASE_URL 未配置，产物不含嵌入式 PostgreSQL，无法在干净机首启 PG（仅验证构建/链接）。配置 repo variable PG_ARTIFACT_BASE_URL 后重跑。"
       - name: flutter pub get
         run: flutter pub get
       - name: flutter analyze
@@ -125,18 +127,13 @@ jobs:
           "BUILD_NAME=$ver" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
           "BUILD_NUMBER=$env:GITHUB_RUN_NUMBER" | Out-File -FilePath $env:GITHUB_ENV -Append -Encoding utf8
       - name: cache PG binaries
-        if: ${{ vars.PG_ARTIFACT_BASE_URL != '' }}
         uses: actions/cache@v4
         with:
           path: windows/runner/resources/pg/
-          key: pg-${{ hashFiles('scripts/pg/pg-version.txt') }}-windows-x64
+          key: pg-${{ hashFiles('scripts/pg/pg-version.txt', 'scripts/pg/upstream.lock') }}-${{ vars.PG_ARTIFACT_BASE_URL != '' && 'bucket' || 'upstream' }}-windows-x64
       - name: fetch embedded PG binaries
-        if: ${{ vars.PG_ARTIFACT_BASE_URL != '' }}
         shell: bash
         run: bash scripts/pg/fetch-binaries.sh
-      - name: warn — PG not bundled
-        if: ${{ vars.PG_ARTIFACT_BASE_URL == '' }}
-        run: echo "::warning title=PG not bundled::PG_ARTIFACT_BASE_URL 未配置，产物不含嵌入式 PostgreSQL（仅验证构建/链接）。"
       - name: flutter pub get
         run: flutter pub get
       - name: flutter analyze
@@ -179,6 +176,13 @@ jobs:
           merge-multiple: true
       - name: list artifacts
         run: ls -R dist
+      - name: generate checksums (QG-6)
+        run: |
+          set -o pipefail
+          cd dist
+          find . -type f ! -name checksums.txt -print0 | sort -z \
+            | xargs -0 sha256sum | sed 's|\./||' > checksums.txt
+          cat checksums.txt
       - name: attach artifacts to release
         uses: softprops/action-gh-release@v2
         with:

CONTRIBUTING.md

@@ -196,19 +196,24 @@ flutter test
 ### 方式 B：嵌入二进制（发布打包）
 
 ```bash
+# 默认 upstream 直拉（零配置）：Windows=EDB 官方 zip（scripts/pg/upstream.lock 锁 SHA256），
+# macOS=本机 Homebrew postgresql@17 + make-relocatable（即方式 C 的自动化封装）
+./scripts/pg/fetch-binaries.sh
+
+# 可选：对象存储覆盖（方案 B）
 export PG_ARTIFACT_BASE_URL=<对象存储 base URL>
 ./scripts/pg/fetch-binaries.sh
 ```
 
-拉取脚本会按 `scripts/pg/pg-version.txt`（当前 17.2）校验 SHA256，写入：
-- macOS: `macos/Runner/Resources/pg/<platform>/bin + /lib`
-- Windows: `windows/runner/resources/pg/<platform>/bin + /lib`
+拉取脚本按 `scripts/pg/pg-version.txt`（当前 17.2；macOS upstream 因 brew 补丁位浮动只锁主版本）校验，写入：
+- macOS: `macos/Runner/Resources/pg/<platform>/bin + /lib + /share`
+- Windows: `windows/runner/resources/pg/<platform>/bin + /lib + /share`
 
-未配置对象存储时脚本输出 `NOT_CONFIGURED`，不会误判成功。
+装配在 `<target>.partial` 完成并通过校验（必需工具 + 版本）后才对换，失败零残留。
 
-### 方式 C：本机 Homebrew → 可重定位嵌入 PG（macOS 开发/本地出包，无需对象存储）
+### 方式 C：本机 Homebrew → 可重定位嵌入 PG（macOS 手动路径，等价于方式 B 的 macOS 分支）
 
-当对象存储尚未配置时，开发机可直接从本机 Homebrew `postgresql@17` 生成「可重定位」的
+开发机可直接从本机 Homebrew `postgresql@17` 生成「可重定位」的
 嵌入式 PG（vendoring 全部依赖闭包 + 改写 install name 为 `@rpath` + ad-hoc 重签名），
 落地到 `macos/Runner/Resources/pg/macos-arm64/`，供 `flutter build macos` 打进 `.app`：
 

ROADMAP.md

@@ -34,7 +34,7 @@
 
 - **M4 能力完整** — 分镜流水线(脚本解析/序列预览) · 导出转码归一 · 画廊复用(存角色/发送画布) · 自定义 Provider 设置页 UI · 角色一致性进阶(见 MASTERPLAN §2)
 - **M5 能上生产** — 数据安全(备份/导出导入仍为零;崩溃钩子 #160、PG SCRAM #172、应用内检查更新 #173 已落地) · 签名公证打包 · onboarding
-- **发布工程** — release.yml 已首跑出双平台产物;待补:PG 分发源(干净机可装)、签名凭据(U1/U2)
+- **发布工程** — release.yml 已首跑出双平台产物;PG 分发源已落(官方上游直拉,产物含嵌入式 PG);待补:签名凭据(U1/U2)
 
 ## 🙋 Help Wanted
 

docs/ARCHITECTURE.md

@@ -1189,15 +1189,16 @@ PG 二进制**不进代码仓库**。当前现状：
 - **CI 测试**：`.github/workflows/ci.yml` 用 `postgres:17-alpine` service container（`TEST_PG_URL` 注入），不打包二进制。
 - **本地开发**：`PgBinaryLocator`（`lib/storage/pg_binary_locator.dart`）按约定目录发现本机 PG；找不到时 storage 集成测试 `markTestSkipped`。
 
-> **Planned**：Release 构建打包内嵌 PG 二进制的拉取脚本（`scripts/fetch-pg-binaries.sh` + `scripts/pg-version.txt`，从对象存储按平台拉取并校验版本）尚未编写——Release 流水线立项时一并实现。
+- **Release 构建**：`scripts/pg/fetch-binaries.sh`（版本锁 `scripts/pg/pg-version.txt`）置备嵌入式 PG——默认 upstream 直拉（Windows=EDB 官方 zip 按 `scripts/pg/upstream.lock` SHA256 锁定裁剪；macOS=Homebrew postgresql@17 + `make-relocatable-macos.sh`），设 `PG_ARTIFACT_BASE_URL` 时切对象存储。详见 `docs/BUILD-RELEASE.md` §3。
 
 ### 14.4 构建步骤
 
-> **Planned**：Release 流水线（含 `fetch-pg-binaries.sh` / `sign-and-notarize.sh`）尚未搭建；当前 CI 只跑 PR 检查（analyze + test + coverage）。以下为 Release 蓝图：
+> Release 流水线已落地（`.github/workflows/release.yml`，alpha.10 起真实跑通；签名步缺凭据自跳过）。
+> 完整流程与顺序约束见 `docs/BUILD-RELEASE.md` §4/§13，此处仅示意：
 
 ```bash
 # 完整 Release 构建流程
-scripts/fetch-pg-binaries.sh        # 1. 拉取 PG 二进制
+bash scripts/pg/fetch-binaries.sh   # 1. 置备 PG 二进制（默认 upstream 直拉）
 flutter pub get                      # 2. 依赖
 flutter gen-l10n                     # 3. 生成 i18n
 dart run build_runner build          # 4. 代码生成（freezed / riverpod）

docs/BOARD.md

@@ -8,8 +8,9 @@
 > ROAD-TO-BETA）视为**归档快照**，不再更新；状态以本表为准。
 >
 > 状态图例：✅ 完成 · 🔵 进行中 · ⬜ 未开始 · 🅿️ 已延后（附因）
-> 最近更新：2026-07-14 · 最新发布：**v0.1.0-alpha.10**（release.yml 首跑,双平台 unsigned 产物;
-> 待 PG 分发源 PKG-2 + 签名 U1/U2 方为干净机可装）
+> 最近更新：2026-07-18 · 最新发布：**v0.1.0-alpha.10**（release.yml 首跑,双平台 unsigned 产物;
+> PG 分发源已随 PKG-2A 落地——下个 tag 起产物含嵌入式 PG（mac 侧待 release CI 首跑验证）;
+> 待签名 U1/U2 方为干净机免绕行可装）
 
 ## M1 —「能用起来」✅ 完成（已随 PR #133 合入 main）
 
@@ -97,6 +98,7 @@
 | GAP-7 Inspector 测试欠账收口（预设点选应用+成本文案精确断言）+ ON-5 五屏空态 golden（Studio empty/error、Canvas empty、Gallery empty、Settings；ubuntu 铸线）——第 10 条（ON-3/4/GAP-7/ON-5）收官；**余 GAP-1 整卡、GAP-3 余量未清**（评审 P1 纠偏：勿宣「全部收官」） | #198 |
 | GAP-3 余量收口（24 站点审计:方向读错并入横幅链;raw toString 上屏收敛——设置页探测诊断行为有意例外;base style 编辑器读错中止防空覆盖（评审 P2-3）;InkErrorBanner.onRetry 死参数删除;**InkAsyncSlot 判 YAGNI**——列表槽位 LB-06 已全收口） | #199 |
 | **GAP-1 设置页 Custom Provider 编辑 UI（上线前必做最后一卡）**：CustomProviderStore 写侧（raw 保真+损坏拒写+原子写）;校验抽 core 纯函数双端共用;列表+表单+删除确认+重启生效常驻条;API Keys custom:* 行 displayName 顺带修——**随本卡合入,上线前必做 1-10 全部落地** | #200 |
+| **PKG-2A PG 二进制分发源（方案 A 上游直拉,beta 硬阻塞里唯一零用户依赖项收官）**：fetch-binaries.sh 双模式重写——upstream 默认（Win=EDB 官方 zip `upstream.lock` 锁 URL+SHA256+裁剪 bin/lib/share;mac=runner brew postgresql@17+make-relocatable,主版本匹配）,`PG_ARTIFACT_BASE_URL` 保留为方案 B 覆盖;`.partial` 原子落位+必需工具校验（含 pg_dump/pg_restore）;release.yml 去门控无条件 fetch;回归测试入 ci release-scripts;**顺带 QG-6 的 checksums.txt**（publish job 全资产 sha256）;本机真栈验收=EDB 裁剪产物过 realpg E2E 全链 | 本 PR |
 
 ## M1 补遗（审计发现的悬空项）
 
@@ -158,4 +160,5 @@
 | GAP-3 评审 P3 残留（#199）:①方向读错期 lane_toolbar 置灰未做（二元域无损毁,但 toggle 到不了 horizontal 的怪异 UX）;②横幅三源 `??` 链+单 `_dismissed` 遮蔽——关掉 edges 错后并发 lanes/direction 错不上屏（改集合）;③非 InkError→errorUnknown 后无任何日志线索（此前 raw toString 至少可报障）,建议 error 分支补 log 或 ProviderObserver.providerDidFail | 🅿️ | ①②低害 UX;③可观测性,随日志面收口 |
 | ON-5 评审 P3 残留（#198）:①golden sentinel 单点——删 studio_empty.png 五测静默 skip 而 node_card 仍 ran>0 骗过整 job 守卫;评审提的 `skipped>0&&baselines>0→fail` 会误伤增量铸线 bootstrap（本 PR 自身流程即反例）,需更细粒度方案;②成本断言 0.01×1 测不出漏乘 batch,补 maxBatchSize>1→\$0.02 用例;③ci.yml 与 update-goldens.yml 双 pin FLUTTER_VERSION 升级必须同步+重铸 | 🅿️ | ①设计再议 ②一测的事 ③升级 checklist 项 |
 | ON-3 评审 P3 残留（#196）:卸载 ffmpeg 后设置页旧 Available 滞留（hit 缓存 app 级,设置页不调 invalidate;导出失败路径会自愈）;PATH 命中显示裸 `ffmpeg` 当路径 | 🅿️ | 低害:重启/导出失败自愈;若做刷新按钮同窗顺修 |
+| PKG-2A 评审 P3 残留:fetch-binaries macOS upstream 无架构核对——arm64 机上 INKFRAME_PG_PLATFORM=macos-x64 会把 arm64 二进制落进 x64 目录且本机 verify 照过（操作员失误场景;release.yml 现只建 arm64;make-relocatable 旧脚本同病） | 🅿️ | 随 macos-13 x64 matrix（PKG-7 真做）同窗加 uname 对 PLATFORM 的核对 |
 | ON-2b 评审 P3 三条（#195）:①真 PG 回滚测只走 projects+canvas 两仓储,建议扩成与 createSample 同构四步;②泳道带厚 400 魔数散落三处（接口默认/注释/测试）,建议提 kDefaultLaneSize;③示例 laneStylePrompt 走 zh 本地化与 base_style_presets「模型合约保英文」惯例有张力（用户可见可编辑,判定可接受）——产品可拍板改为仅本地化 label | 🅿️ | ①②低成本顺窗;③产品取舍,英文语系 provider 出图质量考量 |