diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1caba9b..068aa48 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,10 +1,12 @@
 name: CI
 
+# 只认 main：push 到 main、以及任何以 main 为目标的 PR。
+# 开发分支（feat/*）自己 push 不跑 CI，靠合入 main 前的 PR 把关。
 on:
   push:
-    branches: [main, dev]
+    branches: [main]
   pull_request:
-    branches: [main, dev]
+    branches: [main]
 
 # 同一分支新 push 取消上一次未完成的运行，省 CI 时间。
 concurrency:
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index f6a32dd..4a8d9ac 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,6 +1,6 @@
 name: Release
 
-# 打 vX.Y.Z 标签即触发：各平台用 wails 构建桌面端安装包 → 发布到 GitHub Release。
+# 打 vX.Y.Z 标签即触发：各平台用 wails3 构建桌面端 → 发布到 GitHub Release。
 # 用户旧版 App 启动时查 /releases/latest，发现新版即提示下载（见 frontend/src/lib/version.ts）。
 on:
   push:
@@ -9,6 +9,11 @@ on:
 permissions:
   contents: write # 创建 release + 上传产物需要
 
+env:
+  # 必须与 sundynix-desktop/go.mod 里的 wails/v3 版本一致：alpha 阶段 CLI 生成的
+  # bindings 与运行时是配套的，版本错开会出难查的怪问题。升级时两处一起改。
+  WAILS3_VERSION: v3.0.0-alpha2.117
+
 jobs:
   build:
     name: 构建 ${{ matrix.label }}
@@ -19,10 +24,10 @@ jobs:
         include:
           - os: macos-latest
             label: macOS (universal)
-            platform: darwin/universal
+            asset: sundynix_desktop_macos_universal.zip
           - os: windows-latest
             label: Windows (amd64)
-            platform: windows/amd64
+            asset: sundynix_desktop_windows_amd64.exe
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
@@ -31,30 +36,43 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
-      - name: 安装 wails CLI
-        run: go install github.com/wailsapp/wails/v2/cmd/wails@v2.12.0
+      - name: 安装 wails3 CLI
+        run: go install github.com/wailsapp/wails/v3/cmd/wails3@${{ env.WAILS3_VERSION }}
 
-      - name: 构建桌面端（wails build；GOWORK=off 因 desktop 不在工作区）
+      # v3 的 build 只出裸二进制（macOS 上双击不起窗），必须 package 才有 .app；
+      # universal 走 darwin:package:universal：分别编 amd64/arm64 再 lipo 合并。
+      # 任务链自带 npm install + generate:bindings，故不需要单独的前端构建步骤。
+      - name: 构建 macOS .app（universal）
+        if: runner.os == 'macOS'
         working-directory: sundynix-desktop
         env:
           GOWORK: "off" # 必须加引号：YAML 裸 off 会被解析成布尔 false，使 workflow 校验不合法而不触发
-        run: wails build -clean -platform ${{ matrix.platform }}
+        run: wails3 task darwin:package:universal
+
+      # Windows 沿用 v2 时代的行为：发裸 .exe。v3 的 package 默认走 NSIS 出 installer，
+      # 需 runner 上有 makensis，属于额外未知数，要升级安装包再单独议。
+      - name: 构建 Windows .exe
+        if: runner.os == 'Windows'
+        working-directory: sundynix-desktop
+        env:
+          GOWORK: "off"
+        run: wails3 build
 
       # macOS：.app 是目录，打包成 zip 才能作为单文件资产分发。
       - name: 打包 macOS 产物
         if: runner.os == 'macOS'
-        working-directory: sundynix-desktop/build/bin
-        run: zip -r -y sundynix_desktop_macos_universal.zip sundynix_desktop.app
+        working-directory: sundynix-desktop/bin
+        run: zip -r -y ${{ matrix.asset }} sundynix_desktop.app
 
       - name: 重命名 Windows 产物
         if: runner.os == 'Windows'
-        working-directory: sundynix-desktop/build/bin
-        run: ren sundynix_desktop.exe sundynix_desktop_windows_amd64.exe
+        working-directory: sundynix-desktop/bin
+        run: Rename-Item sundynix_desktop.exe ${{ matrix.asset }}
 
+      # fail_on_unmatched_files 必须为 true：产物路径写错时要当场炸，而不是安静地
+      # 发一个没有附件的 Release。v2→v3 迁移正是把产物从 build/bin 挪到了 bin。
       - name: 发布到 GitHub Release（按 tag 创建/追加资产）
         uses: softprops/action-gh-release@v2
         with:
-          fail_on_unmatched_files: false
-          files: |
-            sundynix-desktop/build/bin/sundynix_desktop_macos_universal.zip
-            sundynix-desktop/build/bin/sundynix_desktop_windows_amd64.exe
+          fail_on_unmatched_files: true
+          files: sundynix-desktop/bin/${{ matrix.asset }}
diff --git a/.gitignore b/.gitignore
index 3ef8ede..efc5da4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,10 +14,10 @@ __pycache__/
 # Wails v3（只忽略产物/缓存；build/ 的 Taskfile+配置是项目构建系统，需提交）
 build/bin/
 frontend/dist/
+# v3 的构建产物落在 bin/，已被第 3 行的 bin/ 通配覆盖，无需单列。
 sundynix-desktop/build/bin/
 sundynix-desktop/.task/
 .task/
-sundynix-desktop/frontend/wailsjs/
 sundynix-desktop/frontend/package.json.md5
 
 # Data
diff --git a/Makefile b/Makefile
index edc28a1..b85ae10 100644
--- a/Makefile
+++ b/Makefile
@@ -55,10 +55,10 @@ admin:        ## 运维控制台 dev（Vite :5174，配置 LLM 模型等控制
 	cd sundynix-admin && npm install && npm run dev
 
 desktop:       ## 真实桌面端开发模式（Wails 原生窗口 + 热重载；需先 make infra + 后端 + 配模型）
-	cd sundynix-desktop && GOWORK=off wails dev
+	cd sundynix-desktop && GOWORK=off wails3 dev
 
-desktop-build: ## 打包桌面端为原生应用（产物在 sundynix-desktop/build/bin/）
-	cd sundynix-desktop && GOWORK=off wails build
+desktop-build: ## 打包桌面端为原生 .app（产物在 sundynix-desktop/bin/）
+	cd sundynix-desktop && GOWORK=off wails3 package
 
 tidy:
 	cd sundynix-gateway    && go mod tidy
diff --git a/README.md b/README.md
index 5e915c0..344ec9b 100644
--- a/README.md
+++ b/README.md
@@ -55,7 +55,7 @@ SSE 客户端: event:token data:已  event:token data:编 ... event:done   ← 
 ### 完整环境（git clone 后零配置直跑）
 
 **前置**：Docker、Go ≥1.24、Node ≥20、Python ≥3.11。
-跑**真实桌面端**还需：Wails CLI（`go install github.com/wailsapp/wails/v2/cmd/wails@latest`）；macOS 再装 Xcode 命令行工具（`xcode-select --install`，webkit 编译用）。
+跑**真实桌面端**还需：Wails v3 CLI（`go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha2.117`，版本须与 `sundynix-desktop/go.mod` 一致）；macOS 再装 Xcode 命令行工具（`xcode-select --install`，webkit 编译用）。
 
 > 各服务默认配置已对齐 docker-compose（NATS:4222 / PG sundynix\@5432 / Redis:6379 /
 > Milvus:19530 / Neo4j neo4j-sundynix\@7687），**clone 后无需改任何配置**即可连上。
diff --git a/RELEASE.md b/RELEASE.md
index b6ab9dc..2fe44d8 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -1,7 +1,7 @@
 # 发版清单（桌面端 Release）
 
 打 `vX.Y.Z` 标签即触发 [`.github/workflows/release.yml`](.github/workflows/release.yml)：
-GitHub 用 macOS/Windows runner `wails build` 出安装包并发布到 **Releases**；
+GitHub 用 macOS/Windows runner `wails3` 出包并发布到 **Releases**（mac 出 universal `.app` 的 zip、Windows 出 `.exe`）；
 旧版用户的 App 启动时查 `releases/latest`，发现新版即弹横幅提示下载
 （逻辑见 [`version.ts`](sundynix-desktop/frontend/src/lib/version.ts)）。
 
@@ -15,8 +15,11 @@ GitHub 用 macOS/Windows runner `wails build` 出安装包并发布到 **Release
 |---|---|---|
 | `sundynix-desktop/frontend/src/lib/version.ts` | `APP_VERSION` | **功能性**：App 拿它和 GitHub 最新版比，决定是否提示更新 |
 | `sundynix-desktop/frontend/package.json` | `version` | 前端包版本（保持一致，便于追溯） |
+| `sundynix-desktop/build/config.yml` | `info.version` | 原生包元数据版本（macOS `Info.plist` 的 `CFBundleShortVersionString` 由它生成） |
 
-> （`wails.json` 当前无版本字段；要在原生包元数据里带版本，可自行加 `info.productVersion`。）
+> ⚠️ 改完 `build/config.yml` 必须跑 `wails3 task common:update:build-assets` 重新生成
+> `build/darwin/Info.plist` 等资产，**光改 config.yml 不生效**——生成物是提交进仓库的。
+> （这坑踩过：config.yml 填好了但没重新生成，`.app` 里还是脚手架模板值，直接起不来。）
 
 ⚠️ **`APP_VERSION` 必须等于即将打的 tag（去掉 v）**，否则更新提示会错乱：
 新包内嵌的 APP_VERSION = 新版本；旧用户 App 内是旧版本，比对才会提示。