Sync master updates into mac

.gitattributes

@@ -0,0 +1,6 @@
+thirdparty/screeningzoom/**/*.cpp linguist-vendored=false
+thirdparty/screeningzoom/**/*.h   linguist-vendored=false
+thirdparty/screeningzoom/**/*.hpp linguist-vendored=false
+
+# Wails auto-generated bindings
+frontend/wailsjs/**/*.js linguist-generated=true

.github/workflows/build-release.yml

@@ -0,0 +1,182 @@
+name: Build Release
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-windows:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Install Wails CLI
+        shell: pwsh
+        run: |
+          go install github.com/wailsapp/wails/v2/cmd/wails@v2.10.2
+          "$(go env GOPATH)\bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
+      - name: Read version
+        id: version
+        shell: pwsh
+        run: |
+          $version = (Get-Content version.json -Raw | ConvertFrom-Json).appVersion
+          if ([string]::IsNullOrWhiteSpace($version)) {
+            throw "version.json appVersion is empty"
+          }
+          "app_version=$($version.Trim())" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+
+      - name: Download runtime archive
+        shell: pwsh
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          $appVersion = "${{ steps.version.outputs.app_version }}"
+          $repo = "${{ github.repository }}"
+          $runtimeDir = Join-Path $PWD "resources/runtime"
+          $runtimeArchive = Join-Path $runtimeDir "runtime.7z"
+          New-Item -ItemType Directory -Path $runtimeDir -Force | Out-Null
+          $downloaded = $false
+
+          $candidates = @(
+            "https://github.com/$repo/releases/download/v$appVersion/runtime.7z"
+          )
+
+          $apiHeaders = @{
+            Authorization = "Bearer $env:GITHUB_TOKEN"
+            "User-Agent"  = "plotkitycat-actions"
+          }
+
+          try {
+            $latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/$repo/releases/latest" -Headers $apiHeaders
+            $latestRuntime = $latestRelease.assets | Where-Object { $_.name -eq "runtime.7z" } | Select-Object -First 1
+            if ($null -ne $latestRuntime -and -not [string]::IsNullOrWhiteSpace($latestRuntime.browser_download_url)) {
+              $candidates += $latestRuntime.browser_download_url
+            }
+
+            $latestZip = $latestRelease.assets | Where-Object { $_.name -like "PlotKityCat-v*.zip" } | Select-Object -First 1
+            if ($null -ne $latestZip -and -not [string]::IsNullOrWhiteSpace($latestZip.browser_download_url)) {
+              $zipPath = Join-Path $env:RUNNER_TEMP "latest-release.zip"
+              $extractDir = Join-Path $env:RUNNER_TEMP "latest-release"
+              Write-Host "Downloading fallback release zip from $($latestZip.browser_download_url)"
+              Invoke-WebRequest -Uri $latestZip.browser_download_url -OutFile $zipPath
+              if (Test-Path -LiteralPath $extractDir) {
+                Remove-Item -LiteralPath $extractDir -Recurse -Force
+              }
+              Expand-Archive -LiteralPath $zipPath -DestinationPath $extractDir -Force
+              $embeddedRuntime = Get-ChildItem -Path $extractDir -Recurse -Filter runtime.7z | Select-Object -First 1
+              if ($null -ne $embeddedRuntime) {
+                Copy-Item -LiteralPath $embeddedRuntime.FullName -Destination $runtimeArchive -Force
+                $downloaded = $true
+              }
+            }
+          } catch {
+            Write-Host "Latest release lookup failed: $($_.Exception.Message)"
+          }
+
+          if (-not $downloaded) {
+            foreach ($url in $candidates | Select-Object -Unique) {
+              try {
+                Write-Host "Downloading runtime from $url"
+                Invoke-WebRequest -Uri $url -OutFile $runtimeArchive
+                $downloaded = $true
+                break
+              } catch {
+                Write-Host "Runtime download failed from $url : $($_.Exception.Message)"
+              }
+            }
+          }
+
+          if (-not $downloaded) {
+            throw "Unable to download runtime.7z from release assets."
+          }
+
+      - name: Bootstrap vcpkg
+        shell: pwsh
+        run: |
+          $vcpkgRoot = Join-Path $env:RUNNER_TEMP "vcpkg"
+          git clone https://github.com/microsoft/vcpkg.git $vcpkgRoot
+          & (Join-Path $vcpkgRoot "bootstrap-vcpkg.bat") -disableMetrics
+          $vcpkgExe = Join-Path $vcpkgRoot "vcpkg.exe"
+          & $vcpkgExe install nlohmann-json:x64-windows-static
+          "VCPKG_ROOT=$vcpkgRoot" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+
+      - name: Build screening zoom helper
+        shell: pwsh
+        run: |
+          $toolchain = Join-Path $env:VCPKG_ROOT "scripts/buildsystems/vcpkg.cmake"
+          cmake -S thirdparty/screeningzoom `
+            -B thirdparty/screeningzoom/build `
+            -DCMAKE_BUILD_TYPE=Release `
+            -DCMAKE_TOOLCHAIN_FILE="$toolchain" `
+            -DVCPKG_TARGET_TRIPLET=x64-windows-static
+          cmake --build thirdparty/screeningzoom/build --config Release
+
+      - name: Build versioned app
+        shell: pwsh
+        run: .\tools\build-versioned-app.ps1 -Version "${{ steps.version.outputs.app_version }}"
+
+      - name: Prepare update artifacts
+        shell: pwsh
+        run: .\tools\prepare-update-release.ps1 -Version "${{ steps.version.outputs.app_version }}"
+
+      - name: Package full release
+        shell: pwsh
+        run: .\tools\package-release.ps1 -Version "${{ steps.version.outputs.app_version }}"
+
+      - name: Upload app binary
+        uses: actions/upload-artifact@v4
+        with:
+          name: PlotKityCat-build-${{ steps.version.outputs.app_version }}
+          path: build/bin/PlotKityCat.exe
+          if-no-files-found: error
+
+      - name: Upload update artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: PlotKityCat-update-${{ steps.version.outputs.app_version }}
+          path: build/update/${{ steps.version.outputs.app_version }}
+          if-no-files-found: error
+
+      - name: Upload full release package
+        uses: actions/upload-artifact@v4
+        with:
+          name: PlotKityCat-release-${{ steps.version.outputs.app_version }}
+          path: build/release/PlotKityCat-v${{ steps.version.outputs.app_version }}.zip
+          if-no-files-found: error
+
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.app_version }}
+          name: v${{ steps.version.outputs.app_version }}
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+          files: |
+            build/release/PlotKityCat-v${{ steps.version.outputs.app_version }}.zip
+            build/update/${{ steps.version.outputs.app_version }}/PlotKityCat-${{ steps.version.outputs.app_version }}-windows-amd64.exe
+            build/update/${{ steps.version.outputs.app_version }}/manifest.json
+            resources/runtime/runtime.7z

.gitignore

@@ -7,12 +7,12 @@ build/release/
 build/update/
 /runtime/
 /runtime.tmp/
-/Scripts/
 *.exe
 *.dll
 *.zip
 !/resources/runtime/
 !/resources/runtime/.gitkeep
+/resources/runtime/runtime.7z
 .runtime-staging/
 .runtime-staging.7z
 .tools_py/
@@ -25,9 +25,11 @@ nul
 .DS_Store
 Thumbs.db
 /.gocache/
+/.cache/
 /.runtime-pack/
 __pycache__/
 *.py[cod]
+thirdparty/screeningzoom/build/
 
 # Legacy root docs
 Tec.md
@@ -36,3 +38,6 @@ tec.md
 prd.md
 designcard.md
 designcard-tec.md
+
+# Local experiment sandbox (prompt eval / card gen)
+.tmp/

DEVELOPMENT.md

@@ -1,9 +1,11 @@
 # PlotKityCat Development
 
+本地开发启动、runtime 与构建发布、Git 仓库约定。
+
 ## 环境
 
 - Windows
-- Go 1.21+
+- Go 1.22+
 - Node.js 18+
 - Wails v2
 
@@ -23,61 +25,64 @@ wails dev
 
 ## 版本
 
-应用版本唯一来源：
+应用版本唯一来源为 `version.json` 中的 `appVersion`。构建与发布脚本默认都读取这里的值。
 
-- `version.json`
+## 本地状态
 
-相关脚本都会默认读取这里的 `appVersion`。
+- `config/app-state.json` 保存版本化的应用状态，新手引导使用 `onboarding` 字段。
+- 新发布包不携带 `config/`；应用创建 Store 时先检查既有 `config/`，早于本次启动写入状态。
+- 历史用户写入 `suppressed / existing-user`，不自动显示教程。
+- 教程模板缺失时写入 `suppressed / template-missing`，后续启动不再重复尝试。
+- 新用户依次记录 `unseen`、`started`、`dismissed`、`completed`；后三者均停止自动启动。
+- `Scripts/新手引导/` 保存教程内容，状态与内容采用独立生命周期。
 
 ## Runtime
 
-项目运行依赖便携 Python runtime：
+项目运行依赖便携 Python runtime。约定如下：
 
-- runtime 占位目录：`resources/runtime/`
-- 发布输入：本地放置的 `resources/runtime/runtime.zip`
+- 占位目录：`resources/runtime/`
+- 本地发布输入：`resources/runtime/runtime.7z`
 - 本地展开目录：`runtime/`
 - 临时展开目录：`runtime.tmp/`
 - 元数据文件：`runtime.version.json`
-
-约定：
-
-- `resources/runtime/runtime.zip` 默认不提交到 Git
-- 该文件应通过 GitHub Release asset 或其他制品存储分发
-- 仓库仅跟踪 runtime 脚本、元数据和第三方补丁源码
+- runtime 通过 GitHub Release asset 分发
+- 仓库仅跟踪 runtime 脚本和元数据
 
 准备 runtime 压缩包：
 
 ```powershell
 .\tools\prepare-runtime.ps1 -SourceRuntimeDir <你的 runtime 目录>
 ```
 
-当前默认应保留的核心库：
+默认核心库：
 
 - Python 标准库
 - numpy
 - matplotlib
 - scipy
 - PyQt5
 
-`runtime.version.json` 应同步填写实际 Python 与核心库版本，不要长期保留 `pending`。
+`runtime.version.json` 必须填写真实版本，`pending` 仅为占位值。
 
 从零重建 runtime 的完整说明见 [RUNTIME_BUILD.md](D:/projects/plotkitycat/RUNTIME_BUILD.md)。
 
-## 打包入口
+## 构建与打包
 
 构建 exe：
 
 ```powershell
 .\tools\build-versioned-app.ps1
 ```
 
-生成发布 zip：
+构建成功会同时生成 `build/bin/build-metadata.json`。打包与在线更新产物脚本会强制核对其中的版本，禁止复用旧 EXE。
+
+生成完整发布包：
 
 ```powershell
 .\tools\package-release.ps1
 ```
 
-生成自动更新发布物：
+生成在线更新产物：
 
 ```powershell
 .\tools\prepare-update-release.ps1
@@ -86,15 +91,17 @@ wails dev
 如果要覆盖默认版本：
 
 ```powershell
-.\tools\build-versioned-app.ps1 -Version 0.0.2.1
-.\tools\package-release.ps1 -Version 0.0.2.1
-.\tools\prepare-update-release.ps1 -Version 0.0.2.1
+.\tools\build-versioned-app.ps1 -Version 0.0.3.5
+.\tools\package-release.ps1 -Version 0.0.3.5
+.\tools\prepare-update-release.ps1 -Version 0.0.3.5
 ```
 
 ## 发布前检查
 
 - 确认 `version.json` 版本正确
-- 确认 `resources/runtime/runtime.zip` 存在
+- 确认 `resources/runtime/runtime.7z` 存在
+- 确认 `zoomit.exe` 已经准备好，优先放在 `resources/screeningzoom/zoomit.exe`
+- 如果还没放到 `resources/screeningzoom/zoomit.exe`，至少确认存在开发构建产物 `thirdparty/screeningzoom/build/Release/zoomit.exe`
 - 确认 `runtime.version.json` 已填写真实版本
 - 确认 `Scripts/` 中示例内容就是准备随包分发的内容
 - 确认 `config/` 没有本机账号、缓存、更新状态等脏数据
@@ -107,21 +114,25 @@ wails dev
 - `frontend/`
 - `tools/`
 - `build/windows/`
-- `resources/` 下需要随项目维护的静态资源
+- `resources/` 下需要随项目维护的静态资源与占位文件
 - `resources/runtime/.gitkeep`
+- `resources/screeningzoom/.gitkeep`
 - `README.md`
 - `DEVELOPMENT.md`
+- `UPDATE_RELEASE.md`
 - `RUNTIME_BUILD.md`
 - `version.json`
 - `runtime.version.json`
+- `Scripts/` 下随产品发布的预制工作区
 
 不应跟踪：
 
 - `config/`
 - `runtime/`
 - `runtime.tmp/`
-- `Scripts/`
 - `build/bin/`
 - `build/release/`
 - `build/update/`
 - `packaging/`
+
+发布服务器更新步骤见 [UPDATE_RELEASE.md](D:/projects/plotkitycat/UPDATE_RELEASE.md)。