chore: 版本升迁 v0.1.2

fix: 修复发布流水线 LFS 资产校验
chore: 版本升迁 v0.1.1
2026-05-05 09:58:08 +08:00 · 2026-05-05 09:57:02 +08:00 · 2026-05-05 04:39:31 +08:00 · 2026-05-05 04:39:21 +08:00 · 2026-05-05 04:32:38 +08:00 · 2026-05-05 04:18:10 +08:00
73 changed files with 3616 additions and 422 deletions
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,8 +1,9 @@
 * text=auto eol=lf
-
 assets/*.png filter=lfs diff=lfs merge=lfs -text
 assets/**/*.png filter=lfs diff=lfs merge=lfs -text
 assets/*.icns filter=lfs diff=lfs merge=lfs -text
 assets/**/*.icns filter=lfs diff=lfs merge=lfs -text
 assets/*.ico filter=lfs diff=lfs merge=lfs -text
 assets/**/*.ico filter=lfs diff=lfs merge=lfs -text
+frontend/public/*.png filter=lfs diff=lfs merge=lfs -text
+frontend/public/**/*.png filter=lfs diff=lfs merge=lfs -text
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -0,0 +1,221 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: read
+
+jobs:
+  prepare:
+    name: Prepare Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          lfs: true
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.work
+          cache-dependency-path: |
+            backend/go.sum
+            versionctl/go.sum
+
+      - name: Verify tag and VERSION
+        id: version
+        run: |
+          version=$(go run ./versionctl print)
+          go run ./versionctl verify-tag "${GITHUB_REF_NAME}"
+          printf 'version=%s\n' "$version" >> "$GITHUB_OUTPUT"
+
+  build-linux:
+    name: Build Linux Assets
+    needs: prepare
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          lfs: true
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.work
+          cache-dependency-path: |
+            backend/go.sum
+            versionctl/go.sum
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install Linux desktop build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libayatana-appindicator3-dev libgtk-3-dev
+
+      - name: Preflight Linux release toolchain
+        run: |
+          set -euo pipefail
+          command -v go
+          go version
+          command -v bun
+          bun --version
+          command -v gcc
+          gcc --version
+          command -v pkg-config
+          pkg-config --modversion ayatana-appindicator3-0.1
+          pkg-config --modversion gtk+-3.0
+          make release-assets-check
+
+      - name: Build Linux release assets
+        run: make release-assets-linux
+
+      - name: Upload Linux release assets
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-linux
+          path: build/release/*
+
+  build-windows:
+    name: Build Windows Assets
+    needs: prepare
+    runs-on: windows-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          lfs: true
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.work
+          cache-dependency-path: |
+            backend/go.sum
+            versionctl/go.sum
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Setup MSYS2 toolchain
+        uses: msys2/setup-msys2@v2
+        with:
+          msystem: MINGW64
+          path-type: inherit
+          update: true
+          install: >-
+            make
+            mingw-w64-x86_64-gcc
+
+      - name: Preflight Windows release toolchain
+        shell: msys2 {0}
+        run: |
+          set -euo pipefail
+          command -v go
+          go version
+          command -v bun
+          bun --version
+          command -v make
+          make --version
+          command -v gcc
+          gcc --version
+          command -v windres
+          windres --version
+          if command -v powershell.exe >/dev/null 2>&1; then
+            powershell.exe -NoProfile -Command '$PSVersionTable.PSVersion.ToString()'
+          else
+            command -v powershell
+            powershell -NoProfile -Command '$PSVersionTable.PSVersion.ToString()'
+          fi
+          make release-assets-check
+
+      - name: Build Windows release assets
+        shell: msys2 {0}
+        run: make release-assets-windows
+
+      - name: Upload Windows release assets
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-windows
+          path: build/release/*
+
+  build-macos:
+    name: Build macOS Assets
+    needs: prepare
+    runs-on: macos-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          lfs: true
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.work
+          cache-dependency-path: |
+            backend/go.sum
+            versionctl/go.sum
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Preflight macOS release toolchain
+        run: |
+          set -euo pipefail
+          command -v go
+          go version
+          command -v bun
+          bun --version
+          command -v ditto
+          xcrun --find lipo
+          xcrun --find vtool
+          make release-assets-check
+
+      - name: Build macOS release assets
+        run: make release-assets-macos
+
+      - name: Upload macOS release assets
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-macos
+          path: build/release/*
+
+  draft-release:
+    name: Create Draft Release
+    needs: [prepare, build-linux, build-windows, build-macos]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download release assets
+        uses: actions/download-artifact@v4
+        with:
+          pattern: release-*
+          merge-multiple: true
+          path: dist
+
+      - name: Publish draft release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: v${{ needs.prepare.outputs.version }}
+          tag_name: ${{ github.ref_name }}
+          draft: true
+          files: |
+            dist/*
--- a/.gitignore
+++ b/.gitignore
@@ -408,6 +408,7 @@ temp
 skills-lock.json
 .worktrees
 !scripts/build/
+backend/bin

 # Embedfs generated
 embedfs/assets/
--- a/403
+++ b/403
@@ -1,175 +1,161 @@
-.PHONY: all dev build test lint clean \
-	backend-build backend-run backend-dev backend-test backend-test-all backend-test-unit backend-test-integration backend-test-coverage \
-	backend-lint backend-clean backend-deps backend-generate \
-	backend-db-up backend-db-down backend-db-status backend-db-create \
-	test-mysql-up test-mysql-down test-mysql test-mysql-quick \
-	frontend-build frontend-dev frontend-test frontend-test-watch frontend-test-coverage frontend-test-e2e frontend-lint frontend-clean \
-	desktop-build desktop-build-mac desktop-build-win desktop-build-linux \
-	desktop-dev desktop-test desktop-clean \
-	desktop-prepare-frontend desktop-prepare-embedfs desktop-prepare-windows-resource
+.PHONY: \
+	lint test clean \
+	version-sync version-check version-bump \
+	server-run server-build server-lint server-test server-clean \
+	desktop-build-mac desktop-build-win desktop-build-linux \
+	desktop-lint desktop-test desktop-clean \
+	release-assets-check release-assets-linux release-assets-windows release-assets-macos \
+	_backend-lint _backend-test _backend-clean _backend-build \
+	_versionctl-lint _versionctl-test \
+	_frontend-install _frontend-build _frontend-check _frontend-test _frontend-dev _frontend-clean \
+	_desktop-test _desktop-clean _desktop-prepare-frontend _desktop-prepare-embedfs _desktop-prepare-windows-resource \
+	_server-run-backend _server-run-frontend
+
+# Delay shell lookups until a target needs them, then cache the result for this make run.
+lazy_shell = $(or $($(1)),$(eval $(1) := $(shell $(2)))$($(1)))
+
+VERSION = $(call lazy_shell,_VERSION,go run ./versionctl print)
+GIT_COMMIT ?= $(call lazy_shell,_GIT_COMMIT,git rev-parse --short HEAD 2>/dev/null || printf 'unknown')
+BUILD_TIME ?= $(call lazy_shell,_BUILD_TIME,date -u +"%Y-%m-%dT%H:%M:%SZ")
+GO_LDFLAGS = -X nex/backend/pkg/buildinfo.version=$(VERSION) -X nex/backend/pkg/buildinfo.commit=$(GIT_COMMIT) -X nex/backend/pkg/buildinfo.buildTime=$(BUILD_TIME)
+GO_LDFLAGS_WIN = $(GO_LDFLAGS) -H=windowsgui
+RELEASE_DIR := build/release
+SERVER_LINUX_ASSET = $(call lazy_shell,_SERVER_LINUX_ASSET,go run ./versionctl asset-name server linux amd64)
+SERVER_WINDOWS_ASSET = $(call lazy_shell,_SERVER_WINDOWS_ASSET,go run ./versionctl asset-name server windows amd64)
+SERVER_DARWIN_AMD64_ASSET = $(call lazy_shell,_SERVER_DARWIN_AMD64_ASSET,go run ./versionctl asset-name server darwin amd64)
+SERVER_DARWIN_ARM64_ASSET = $(call lazy_shell,_SERVER_DARWIN_ARM64_ASSET,go run ./versionctl asset-name server darwin arm64)
+DESKTOP_LINUX_ASSET = $(call lazy_shell,_DESKTOP_LINUX_ASSET,go run ./versionctl asset-name desktop linux)
+DESKTOP_WINDOWS_ASSET = $(call lazy_shell,_DESKTOP_WINDOWS_ASSET,go run ./versionctl asset-name desktop windows)
+DESKTOP_MACOS_ASSET = $(call lazy_shell,_DESKTOP_MACOS_ASSET,go run ./versionctl asset-name desktop macos)

 # ============================================
-# 顶层便捷命令
+# 全局命令
 # ============================================

-dev:
-	@echo "🚀 Starting development environment..."
-	@$(MAKE) -j2 backend-dev frontend-dev
+lint: _backend-lint _frontend-check _versionctl-lint
+	@printf 'Lint complete\n'

-build: backend-build frontend-build
-	@echo "✅ Build complete"
+test: _backend-test _frontend-test _desktop-test _versionctl-test
+	@printf 'All tests passed\n'

-test: backend-test desktop-test frontend-test
-	@echo "✅ All tests passed"
-
-lint: backend-lint frontend-lint
-	@echo "✅ Lint complete"
-
-all: build test lint
+clean: _backend-clean _frontend-clean _desktop-clean
+	@printf 'Clean complete\n'

 # ============================================
-# 后端
+# 版本管理
 # ============================================

-backend-build:
-	cd backend && go build -o bin/server ./cmd/server
+version-sync:
+	go run ./versionctl sync

-backend-run:
-	cd backend && go run ./cmd/server
+version-check:
+	go run ./versionctl check

-backend-dev:
-	cd backend && go run ./cmd/server
-
-backend-test:
-	cd backend && go test ./internal/... ./pkg/... ./tests/... ./cmd/server/... -v
-
-backend-test-all:
-	cd backend && go test ./... -v
-
-backend-test-unit:
-	cd backend && go test ./internal/... ./pkg/... -v
-
-backend-test-integration:
-	cd backend && go test ./tests/... -v
-
-backend-test-coverage:
-	cd backend && go test ./... -coverprofile=coverage.out
-	cd backend && go tool cover -html=coverage.out -o coverage.html
-	@echo "Coverage report generated: backend/coverage.html"
-
-backend-lint:
-	cd backend && go tool golangci-lint run ./...
-
-backend-clean:
-	rm -rf backend/bin/ backend/coverage.out backend/coverage.html
-
-backend-deps:
-	cd backend && go mod tidy
-
-backend-generate:
-	cd backend && go generate ./...
-
-backend-db-up:
-	@echo "Running database migration up..."
-	cd backend && goose -dir migrations/sqlite sqlite3 "$(DB_PATH)" up
-
-backend-db-down:
-	@echo "Running database migration down..."
-	cd backend && goose -dir migrations/sqlite sqlite3 "$(DB_PATH)" down
-
-backend-db-status:
-	@echo "Checking database migration status..."
-	cd backend && goose -dir migrations/sqlite sqlite3 "$(DB_PATH)" status
-
-backend-db-create:
-	@read -p "Migration name: " name; \
-	cd backend && goose -dir migrations/sqlite create $$name sql; \
-	cd backend && goose -dir migrations/mysql create $$name sql
+version-bump: BUMP ?= patch
+version-bump:
+	$(eval _BUMP_ARG := $(if $(SET_VERSION),$(SET_VERSION),$(BUMP)))
+	$(eval _NEW_VERSION := $(shell go run ./versionctl bump $(_BUMP_ARG)))
+	git add VERSION frontend/
+	git commit -m "chore: 版本升迁 v$(_NEW_VERSION)"
+	git tag "v$(_NEW_VERSION)"
+	@printf '版本升迁完成: v%s\n' "$(_NEW_VERSION)"

 # ============================================
-# MySQL 专项测试
+# Server 模式
 # ============================================

-test-mysql-up:
-	@echo "Starting MySQL test container..."
-	cd backend/tests/mysql && docker-compose up -d
-	@echo "Waiting for MySQL to be ready..."
-	@for i in $$(seq 1 30); do \
-		if docker exec nex-mysql-test mysqladmin ping -h localhost -u root -ptestpass --silent 2>/dev/null; then \
-			echo "MySQL is ready!"; \
-			exit 0; \
-		fi; \
-		echo "Waiting... ($$i/30)"; \
-		sleep 1; \
-	done; \
-	echo "MySQL failed to start"; \
-	exit 1
+server-run:
+	@$(MAKE) -j2 _server-run-backend _server-run-frontend

-test-mysql-down:
-	@echo "Stopping MySQL test container..."
-	cd backend/tests/mysql && docker-compose down -v
+server-build: version-check _backend-build _frontend-build
+	@printf 'Server build complete\n'

-test-mysql: test-mysql-up
-	@echo "Running MySQL tests..."
-	cd backend && go test -tags=mysql ./tests/mysql/... -v -count=1
-	$(MAKE) test-mysql-down
+server-lint: _backend-lint _frontend-check
+	@printf 'Server lint complete\n'

-test-mysql-quick:
-	@echo "Running MySQL tests (without container management)..."
-	cd backend && go test -tags=mysql ./tests/mysql/... -v -count=1
+server-test: _backend-test _frontend-test
+	@printf 'Server tests passed\n'
+
+server-clean: _backend-clean _frontend-clean
+	@printf 'Server artifacts cleaned\n'
+
+_server-run-backend:
+	@$(MAKE) -C backend run
+
+_server-run-frontend: _frontend-install
+	cd frontend && bun run dev

 # ============================================
-# 前端
+# Desktop 模式
 # ============================================

-frontend-install:
-	cd frontend && bun install
+desktop-build-mac: version-check _desktop-prepare-frontend _desktop-prepare-embedfs
+	@printf 'Building macOS desktop...\n'
+	cd backend && CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 go build -ldflags "$(GO_LDFLAGS)" -o ../build/nex-mac-arm64 ./cmd/desktop
+	cd backend && CGO_ENABLED=1 GOOS=darwin GOARCH=amd64 go build -ldflags "$(GO_LDFLAGS)" -o ../build/nex-mac-amd64 ./cmd/desktop
+	lipo -create build/nex-mac-arm64 build/nex-mac-amd64 -output build/nex-mac-universal
+	@printf 'Packaging macOS app bundle...\n'
+	mkdir -p build/Nex.app/Contents/MacOS build/Nex.app/Contents/Resources
+	cp build/nex-mac-universal build/Nex.app/Contents/MacOS/nex
+	@if [ -f assets/icon.icns ]; then \
+		cp assets/icon.icns build/Nex.app/Contents/Resources/; \
+	else \
+		printf 'Missing assets/icon.icns\n'; \
+	fi
+	@MIN_MACOS_VERSION=$$(vtool -show-build build/nex-mac-universal | awk '/minos / {print $$2; exit}'); \
+	if [ -z "$$MIN_MACOS_VERSION" ]; then \
+		printf 'Unable to read macOS minimum version\n'; \
+		exit 1; \
+	fi; \
+	go run ./versionctl macos-plist "$$MIN_MACOS_VERSION" > build/Nex.app/Contents/Info.plist
+	chmod +x build/Nex.app/Contents/MacOS/nex
+	@printf 'macOS desktop build complete\n'

-frontend-build: frontend-install
-	cd frontend && bun run build
+desktop-build-win: version-check _desktop-prepare-frontend _desktop-prepare-embedfs _desktop-prepare-windows-resource
+	@printf 'Building Windows desktop...\n'
+ifeq ($(OS),Windows_NT)
+	powershell -NoProfile -Command "New-Item -ItemType Directory -Path 'build' -Force | Out-Null"
+	cd backend && set "CGO_ENABLED=1"&& set "GOOS=windows"&& set "GOARCH=amd64"&& go build -ldflags "$(GO_LDFLAGS_WIN)" -o ../build/nex-win-amd64.exe ./cmd/desktop
+else
+	mkdir -p build
+	cd backend && CGO_ENABLED=1 GOOS=windows GOARCH=amd64 go build -ldflags "$(GO_LDFLAGS_WIN)" -o ../build/nex-win-amd64.exe ./cmd/desktop
+endif
+	@printf 'Windows desktop build complete\n'

-frontend-dev: frontend-install
-	cd frontend && bun dev
+desktop-build-linux: version-check _desktop-prepare-frontend _desktop-prepare-embedfs
+	@printf 'Building Linux desktop...\n'
+	cd backend && CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -ldflags "$(GO_LDFLAGS)" -o ../build/nex-linux-amd64 ./cmd/desktop
+	@printf 'Linux desktop build complete\n'

-frontend-test: frontend-install
-	cd frontend && bun run test
+desktop-lint: _backend-lint _frontend-check
+	@printf 'Desktop lint complete\n'

-frontend-test-watch: frontend-install
-	cd frontend && bun run test:watch
+desktop-test: _desktop-test
+	@printf 'Desktop tests passed\n'

-frontend-test-coverage: frontend-install
-	cd frontend && bun run test:coverage
+desktop-clean: _desktop-clean
+	@printf 'Desktop artifacts cleaned\n'

-frontend-test-e2e: frontend-install
-	cd frontend && bun run test:e2e
+_desktop-test:
+	cd backend && go test ./cmd/desktop/... -v

-frontend-lint: frontend-install
-	cd frontend && bun run lint
+_desktop-clean:
+	rm -rf build/ embedfs/assets embedfs/frontend-dist backend/cmd/desktop/rsrc_windows_amd64.syso

-frontend-clean:
-	rm -rf frontend/dist frontend/.next frontend/node_modules frontend/coverage frontend/playwright-report frontend/test-results frontend/tsconfig.tsbuildinfo
-
-# ============================================
-# 桌面应用
-# ============================================
-
-desktop-build: desktop-build-mac desktop-build-win desktop-build-linux
-	@echo "✅ Desktop builds complete for all platforms"
-
-desktop-prepare-frontend:
-	@echo "📦 Preparing frontend for desktop..."
+_desktop-prepare-frontend: _frontend-install
+	@printf 'Preparing frontend for desktop...\n'
 ifeq ($(OS),Windows_NT)
 	powershell -NoProfile -Command "Copy-Item -LiteralPath 'frontend/.env.desktop' -Destination 'frontend/.env.production.local' -Force"
-	cd frontend && bun install && bun run build
+	cd frontend && bun run build
 	powershell -NoProfile -Command "Remove-Item -LiteralPath 'frontend/.env.production.local' -Force -ErrorAction SilentlyContinue"
 else
 	cd frontend && cp .env.desktop .env.production.local
-	cd frontend && bun install && bun run build
+	cd frontend && bun run build
 	rm -f frontend/.env.production.local
 endif

-desktop-prepare-embedfs:
-	@echo "📦 Preparing embedded filesystem..."
+_desktop-prepare-embedfs:
+	@printf 'Preparing embedded filesystem...\n'
 ifeq ($(OS),Windows_NT)
 	powershell -NoProfile -Command "Remove-Item -LiteralPath 'embedfs/assets' -Recurse -Force -ErrorAction SilentlyContinue; Remove-Item -LiteralPath 'embedfs/frontend-dist' -Recurse -Force -ErrorAction SilentlyContinue; Copy-Item -LiteralPath 'assets' -Destination 'embedfs/assets' -Recurse; Copy-Item -LiteralPath 'frontend/dist' -Destination 'embedfs/frontend-dist' -Recurse"
 else
@@ -178,8 +164,8 @@ else
 	cp -r frontend/dist embedfs/frontend-dist
 endif

-desktop-prepare-windows-resource:
-	@echo "📦 Preparing Windows executable icon..."
+_desktop-prepare-windows-resource:
+	@printf 'Preparing Windows executable icon...\n'
 ifeq ($(OS),Windows_NT)
 	cd backend/cmd/desktop && windres -O coff -F pe-x86-64 -i icon_windows.rc -o rsrc_windows_amd64.syso
 else
@@ -188,97 +174,82 @@ else
 	elif command -v windres >/dev/null 2>&1; then \
 		cd backend/cmd/desktop && windres -O coff -F pe-x86-64 -i icon_windows.rc -o rsrc_windows_amd64.syso; \
 	else \
-		echo "❌ 未找到 windres，无法生成 Windows exe 图标资源"; \
+		printf 'Missing windres for Windows icon resource generation\n'; \
 		exit 1; \
 	fi
 endif

-desktop-build-mac: desktop-prepare-frontend desktop-prepare-embedfs
-	@echo "🍎 Building macOS..."
-	cd backend && CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 go build -o ../build/nex-mac-arm64 ./cmd/desktop
-	cd backend && CGO_ENABLED=1 GOOS=darwin GOARCH=amd64 go build -o ../build/nex-mac-amd64 ./cmd/desktop
-	lipo -create build/nex-mac-arm64 build/nex-mac-amd64 -output build/nex-mac-universal
-	@echo "📦 Packaging macOS .app..."
-	mkdir -p build/Nex.app/Contents/MacOS build/Nex.app/Contents/Resources
-	cp build/nex-mac-universal build/Nex.app/Contents/MacOS/nex
-	@if [ -f assets/icon.icns ]; then \
-		cp assets/icon.icns build/Nex.app/Contents/Resources/; \
-	else \
-		echo "⚠️  未找到 assets/icon.icns"; \
-	fi
-	@MIN_MACOS_VERSION=$$(vtool -show-build build/nex-mac-universal | awk '/minos / {print $$2; exit}'); \
-	if [ -z "$$MIN_MACOS_VERSION" ]; then \
-		echo "❌ 无法读取 macOS 最低系统版本"; \
-		exit 1; \
-	fi; \
-	{ \
-		printf '%s\n' '<?xml version="1.0" encoding="UTF-8"?>' \
-			'<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' \
-			'<plist version="1.0">' \
-			'<dict>' \
-			'    <key>CFBundleDevelopmentRegion</key>' \
-			'    <string>zh-Hans</string>' \
-			'    <key>CFBundleExecutable</key>' \
-			'    <string>nex</string>' \
-			'    <key>CFBundleIconFile</key>' \
-			'    <string>icon</string>' \
-			'    <key>CFBundleIdentifier</key>' \
-			'    <string>com.lanyuanxiaoyao.nex</string>' \
-			'    <key>CFBundleInfoDictionaryVersion</key>' \
-			'    <string>6.0</string>' \
-			'    <key>LSApplicationCategoryType</key>' \
-			'    <string>public.app-category.developer-tools</string>' \
-			'    <key>CFBundleName</key>' \
-			'    <string>Nex</string>' \
-			'    <key>CFBundleDisplayName</key>' \
-			'    <string>Nex</string>' \
-			'    <key>CFBundlePackageType</key>' \
-			'    <string>APPL</string>' \
-			'    <key>CFBundleShortVersionString</key>' \
-			'    <string>1.0.0</string>' \
-			'    <key>CFBundleVersion</key>' \
-			'    <string>1.0.0</string>' \
-			'    <key>NSHumanReadableCopyright</key>' \
-			'    <string>Copyright © 2026 Nex</string>' \
-			'    <key>LSMinimumSystemVersion</key>' \
-			"    <string>$$MIN_MACOS_VERSION</string>" \
-			'    <key>LSUIElement</key>' \
-			'    <true/>' \
-			'    <key>NSHighResolutionCapable</key>' \
-			'    <true/>' \
-			'</dict>' \
-			'</plist>'; \
-	} > build/Nex.app/Contents/Info.plist
-	chmod +x build/Nex.app/Contents/MacOS/nex
-	@echo "✅ macOS app packaged: build/Nex.app"
+# ============================================
+# 发布资产
+# ============================================

-desktop-build-win: desktop-prepare-frontend desktop-prepare-embedfs desktop-prepare-windows-resource
-	@echo "🪟 Building Windows..."
+release-assets-check:
+	go run ./versionctl release-assets-check
+	@printf 'Release assets check passed\n'
+
+release-assets-linux: version-check release-assets-check desktop-build-linux
+	rm -rf "$(RELEASE_DIR)"
+	mkdir -p "$(RELEASE_DIR)"
+	cd backend && CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -ldflags "$(GO_LDFLAGS)" -o ../build/nex-server-linux-amd64 ./cmd/server
+	tar -C build -czf "$(RELEASE_DIR)/$(SERVER_LINUX_ASSET)" nex-server-linux-amd64
+	tar -C build -czf "$(RELEASE_DIR)/$(DESKTOP_LINUX_ASSET)" nex-linux-amd64
+
+release-assets-windows: version-check release-assets-check desktop-build-win
 ifeq ($(OS),Windows_NT)
-	powershell -NoProfile -Command "New-Item -ItemType Directory -Path 'build' -Force | Out-Null"
-	cd backend && set "CGO_ENABLED=1"&& set "GOOS=windows"&& set "GOARCH=amd64"&& go build -ldflags "-H=windowsgui" -o ../build/nex-win-amd64.exe ./cmd/desktop
+	powershell -NoProfile -Command "Remove-Item -LiteralPath '$(RELEASE_DIR)' -Recurse -Force -ErrorAction SilentlyContinue; New-Item -ItemType Directory -Path '$(RELEASE_DIR)' -Force | Out-Null"
+	cd backend && set "CGO_ENABLED=1"&& set "GOOS=windows"&& set "GOARCH=amd64"&& go build -ldflags "$(GO_LDFLAGS_WIN)" -o ../build/nex-server-win-amd64.exe ./cmd/server
+	powershell -NoProfile -Command "Compress-Archive -LiteralPath 'build/nex-server-win-amd64.exe' -DestinationPath '$(RELEASE_DIR)/$(SERVER_WINDOWS_ASSET)' -Force"
+	powershell -NoProfile -Command "Compress-Archive -LiteralPath 'build/nex-win-amd64.exe' -DestinationPath '$(RELEASE_DIR)/$(DESKTOP_WINDOWS_ASSET)' -Force"
 else
-	mkdir -p build
-	cd backend && CGO_ENABLED=1 GOOS=windows GOARCH=amd64 go build -ldflags "-H=windowsgui" -o ../build/nex-win-amd64.exe ./cmd/desktop
+	@printf 'release-assets-windows requires Windows\n'
+	@exit 1
 endif

-desktop-build-linux: desktop-prepare-frontend desktop-prepare-embedfs
-	@echo "🐧 Building Linux..."
-	cd backend && CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -o ../build/nex-linux-amd64 ./cmd/desktop
-
-desktop-dev: desktop-prepare-frontend desktop-prepare-embedfs
-	@echo "🖥️  Starting desktop app in dev mode..."
-	cd backend && go run ./cmd/desktop
-
-desktop-test:
-	cd backend && go test ./cmd/desktop/... -v
-
-desktop-clean:
-	rm -rf build/ embedfs/assets embedfs/frontend-dist
+release-assets-macos: version-check release-assets-check desktop-build-mac
+	rm -rf "$(RELEASE_DIR)"
+	mkdir -p "$(RELEASE_DIR)"
+	cd backend && CGO_ENABLED=1 GOOS=darwin GOARCH=amd64 go build -ldflags "$(GO_LDFLAGS)" -o ../build/nex-server-darwin-amd64 ./cmd/server
+	cd backend && CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 go build -ldflags "$(GO_LDFLAGS)" -o ../build/nex-server-darwin-arm64 ./cmd/server
+	tar -C build -czf "$(RELEASE_DIR)/$(SERVER_DARWIN_AMD64_ASSET)" nex-server-darwin-amd64
+	tar -C build -czf "$(RELEASE_DIR)/$(SERVER_DARWIN_ARM64_ASSET)" nex-server-darwin-arm64
+	ditto -c -k --keepParent build/Nex.app "$(RELEASE_DIR)/$(DESKTOP_MACOS_ASSET)"

 # ============================================
-# 清理
+# 共享 helper targets
 # ============================================

-clean: backend-clean frontend-clean desktop-clean
-	@echo "✅ Clean complete"
+_backend-build:
+	@$(MAKE) -C backend build
+
+_backend-lint:
+	@$(MAKE) -C backend lint
+
+_backend-test:
+	@$(MAKE) -C backend test
+
+_backend-clean:
+	@$(MAKE) -C backend clean
+
+_versionctl-lint:
+	@$(MAKE) -C versionctl lint
+
+_versionctl-test:
+	@$(MAKE) -C versionctl test
+
+_frontend-install:
+	cd frontend && bun install
+
+_frontend-build: _frontend-install
+	cd frontend && bun run build
+
+_frontend-check: _frontend-install
+	cd frontend && bun run check
+
+_frontend-test: _frontend-install
+	cd frontend && bun run test
+
+_frontend-dev: _frontend-install
+	cd frontend && bun run dev
+
+_frontend-clean:
+	rm -rf frontend/dist frontend/.next frontend/coverage frontend/playwright-report frontend/test-results frontend/tsconfig.tsbuildinfo
--- a/README.md
+++ b/README.md
@@ -91,7 +91,7 @@ JSON:    {"level":"info","logger":"handler.proxy","msg":"处理请求","method":
 - **图表库**: Recharts
 - **路由**: React Router v7
 - **数据获取**: TanStack Query v5
- **样式**: SCSS Modules
+- **样式**: TDesign 组件 props 优先，TDesign tokens 次之，SCSS 作为兜底补充
 - **测试**: Vitest + React Testing Library + Playwright

 ## 快速开始
@@ -109,9 +109,6 @@ make desktop-build-win

 # Linux
 make desktop-build-linux
-
-# 构建所有平台
-make desktop-build
 ```

 **使用桌面应用**：
@@ -132,32 +129,28 @@ make desktop-build
 - Xfce: 需要 libappindicator
 - 其他支持 StatusNotifierItem 规范的环境

-### CLI 模式
-
-#### 后端
+### Server 模式（前后端分离）

 ```bash
-cd backend
-go mod download
-go run cmd/server/main.go
+make server-run
 ```

-后端服务将在 `http://localhost:9826` 启动。首次启动会自动：
+`make server-run` 会并行启动：
+- 后端服务：`http://localhost:9826`
+- 前端开发服务器：`http://localhost:5173`
+
+前端请求会继续通过 Vite proxy 转发到后端。后端首次启动会自动：
 - 创建配置文件 `~/.nex/config.yaml`
 - 初始化数据库 `~/.nex/config.db`
 - 运行数据库迁移
 - 创建日志目录 `~/.nex/log/`

-### 前端
+**构建 server 模式产物**：

 ```bash
-cd frontend
-bun install
-bun dev
+make server-build
 ```

-前端开发服务器将在 `http://localhost:5173` 启动，API 请求通过 Vite proxy 转发到后端。
-
 ## API 接口

 ### 代理接口（对外部应用）
@@ -206,6 +199,9 @@ bun dev

 查询参数支持：`provider_id`、`model_name`、`start_date`、`end_date`、`group_by`

+#### 版本信息
+- `GET /api/version` - 获取后端构建版本信息（`version`、`commit`、`build_time`），用于前端 About 页面诊断前后端版本一致性
+
 ## 配置

 配置支持多种方式，优先级为：**CLI 参数 > 环境变量 > 配置文件 > 默认值**
@@ -279,53 +275,100 @@ export NEX_DATABASE_DBNAME=nex
 ## 测试

 ```bash
-# 顶层便捷命令
-make test                       # 运行所有测试
+# 全局默认测试（不含 MySQL 和前端 E2E）
+make test

-# 后端测试
-make backend-test               # 后端测试
-make backend-test-coverage      # 后端覆盖率
-make backend-test-unit          # 后端单元测试
-make backend-test-integration   # 后端集成测试
-
-# 前端测试
-make frontend-test              # 前端测试
-make frontend-test-e2e          # 前端 E2E 测试
-make frontend-test-coverage     # 前端覆盖率
+# 产品级测试
+make server-test
+make desktop-test
 ```

+backend 分类测试、MySQL 专项测试和前端 E2E 测试请分别查看 `backend/README.md` 与 `frontend/README.md`。
+
 ## 开发

 ```bash
 # 首次克隆后安装 Git hooks
 lefthook install

-# 顶层便捷命令
-make dev                        # 启动开发环境（并行启动后端和前端）
-make build                      # 构建所有产物
-make lint                       # 检查所有代码
-make clean                      # 清理所有构建产物
+# 全局命令
+make lint                       # 前后端共享检查
+make test                       # 默认全量测试（不含 MySQL/E2E）
+make clean                      # 清理所有构建产物和测试报告

-# 后端开发
-make backend-build              # 构建后端
-make backend-run                # 运行后端
-make backend-dev                # 后端开发模式
-make backend-lint               # 后端代码检查
-make backend-clean              # 清理后端构建产物
+# server 模式
+make server-run                 # 并行启动后端和前端开发服务
+make server-build               # 构建 backend/bin/server 和 frontend/dist
+make server-lint                # server 模式检查
+make server-test                # server 模式测试
+make server-clean               # 清理 server 模式产物

-# 数据库操作
-make backend-db-up              # 数据库迁移
-make backend-db-down            # 数据库回滚
-make backend-db-status          # 数据库迁移状态
-make backend-db-create          # 创建新迁移
-
-# 前端开发
-make frontend-build             # 构建前端
-make frontend-dev               # 前端开发模式
-make frontend-lint              # 前端代码检查
-make frontend-clean             # 清理前端构建产物
+# desktop 模式
+make desktop-build-mac          # 构建 macOS 桌面应用
+make desktop-build-win          # 构建 Windows 桌面应用
+make desktop-build-linux        # 构建 Linux 桌面应用
+make desktop-lint               # desktop 模式检查
+make desktop-test               # desktop 专属测试
+make desktop-clean              # 清理 desktop 产物
 ```

+## 版本与发布
+
+### 统一版本源
+
+- 仓库根目录 `VERSION` 是全仓唯一版本源，格式固定为 `x.y.z`
+- `frontend/package.json` 和前端 `.env.*` 中的 `VITE_APP_VERSION` 由仓库工具同步，不能手工漂移
+
+### 本地版本演进
+
+```bash
+# 递增版本（自动 sync + check + commit + tag）
+make version-bump BUMP=minor
+
+# 或指定具体版本号
+make version-bump SET_VERSION=1.0.0
+
+# 推送到远程
+git push --follow-tags
+```
+
+手动同步和校验：
+
+```bash
+make version-sync
+make version-check
+```
+
+### 本地生成发布资产
+
+```bash
+# Linux: server + desktop
+make release-assets-linux
+
+# Windows: server + desktop（需在 Windows 环境执行）
+make release-assets-windows
+
+# macOS: darwin-amd64 server、darwin-arm64 server、desktop universal
+make release-assets-macos
+```
+
+生成的版本化发布资产位于 `build/release/`。
+
+### GitHub Draft Release
+
+- 推送 `vX.Y.Z` tag 后，`.github/workflows/release.yml` 会自动执行发布流水线
+- 三个平台 job 会在正式构建前先检查 `go`、`bun` 和各自的平台打包工具链，缺失时快速失败并在日志中输出诊断信息
+- Windows 发布 job 在 `MSYS2 / MINGW64` shell 中执行，并继承 `setup-go` / `setup-bun` 准备好的工具链路径
+- 流水线会先校验 tag 与 `VERSION` 一致，再构建以下资产并上传到 GitHub Draft Release：
+  - Linux server
+  - Windows server
+  - darwin-amd64 server
+  - darwin-arm64 server
+  - Linux desktop
+  - Windows desktop
+  - macOS desktop universal
+- Release 默认以 Draft 形式创建，需人工检查后再公开发布
+
 ## 开发规范

 详见各子项目的 README.md：
--- a/1
+++ b/1
@@ -0,0 +1 @@
+0.1.2
--- a/backend/Makefile
+++ b/backend/Makefile
@@ -0,0 +1,97 @@
+.PHONY: \
+	build run \
+	test test-unit test-integration test-coverage \
+	lint clean \
+	migrate-up migrate-down migrate-status migrate-create \
+	mysql-up mysql-down mysql-test mysql-test-quick
+
+VERSION := $(shell go run ../versionctl print)
+GIT_COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null || printf 'unknown')
+BUILD_TIME ?= $(shell date -u +"%Y-%m-%dT%H:%M:%SZ")
+GO_LDFLAGS := -X nex/backend/pkg/buildinfo.version=$(VERSION) -X nex/backend/pkg/buildinfo.commit=$(GIT_COMMIT) -X nex/backend/pkg/buildinfo.buildTime=$(BUILD_TIME)
+
+DB_DRIVER ?= sqlite3
+DB_DSN ?= $(HOME)/.nex/config.db
+
+ifeq ($(DB_DRIVER),mysql)
+GOOSE_DIR := migrations/mysql
+GOOSE_DRIVER := mysql
+else ifeq ($(DB_DRIVER),sqlite3)
+GOOSE_DIR := migrations/sqlite
+GOOSE_DRIVER := sqlite3
+else
+$(error unsupported DB_DRIVER '$(DB_DRIVER)', use sqlite3 or mysql)
+endif
+
+build:
+	go build -ldflags "$(GO_LDFLAGS)" -o bin/server ./cmd/server
+
+run:
+	go run -ldflags "$(GO_LDFLAGS)" ./cmd/server
+
+test:
+	go test ./internal/... ./pkg/... ./tests/... ./cmd/server/... -v
+
+test-unit:
+	go test ./internal/... ./pkg/... -v
+
+test-integration:
+	go test ./tests/... -v
+
+test-coverage:
+	go test ./... -coverprofile=coverage.out
+	go tool cover -html=coverage.out -o coverage.html
+	@printf 'Coverage report generated: backend/coverage.html\n'
+
+lint:
+	go tool golangci-lint run ./...
+
+clean:
+	rm -rf bin/ coverage.out coverage.html
+
+migrate-up:
+	@printf 'Running database migration up...\n'
+	goose -dir $(GOOSE_DIR) $(GOOSE_DRIVER) "$(DB_DSN)" up
+
+migrate-down:
+	@printf 'Running database migration down...\n'
+	goose -dir $(GOOSE_DIR) $(GOOSE_DRIVER) "$(DB_DSN)" down
+
+migrate-status:
+	@printf 'Checking database migration status...\n'
+	goose -dir $(GOOSE_DIR) $(GOOSE_DRIVER) "$(DB_DSN)" status
+
+migrate-create:
+	@printf 'Migration name: '; \
+	read name; \
+	goose -dir migrations/sqlite create $$name sql; \
+	goose -dir migrations/mysql create $$name sql
+
+mysql-up:
+	@printf 'Starting MySQL test container...\n'
+	cd tests/mysql && docker-compose up -d
+	@printf 'Waiting for MySQL to be ready...\n'
+	@for i in $$(seq 1 30); do \
+		if docker exec nex-mysql-test mysqladmin ping -h localhost -u root -ptestpass --silent 2>/dev/null; then \
+			printf 'MySQL is ready\n'; \
+			exit 0; \
+		fi; \
+		printf 'Waiting... (%s/30)\n' $$i; \
+		sleep 1; \
+	done; \
+	printf 'MySQL failed to start\n'; \
+	exit 1
+
+mysql-down:
+	@printf 'Stopping MySQL test container...\n'
+	cd tests/mysql && docker-compose down -v
+
+mysql-test:
+	@set -e; \
+	$(MAKE) mysql-up; \
+	trap '$(MAKE) mysql-down' EXIT; \
+	go test -tags=mysql ./tests/mysql/... -v -count=1
+
+mysql-test-quick:
+	@printf 'Running MySQL tests without container management...\n'
+	go test -tags=mysql ./tests/mysql/... -v -count=1
--- a/backend/README.md
+++ b/backend/README.md
@@ -54,7 +54,7 @@ func NewProxyHandler(..., logger *zap.Logger) *ProxyHandler {
 使用 `pkg/logger/field.go` 中定义的字段构造函数：

 ```go
-logger.Info("请求开始",
+logger.Debug("请求开始",
    pkglogger.Method("POST"),
    pkglogger.Path("/v1/chat"),
    pkglogger.RequestID("xxx"),
@@ -437,24 +437,37 @@ docker run -d -e NEX_SERVER_PORT=9000 -e NEX_LOG_LEVEL=info nex-server
 ## 测试

 ```bash
-# 运行所有测试
+# 运行 backend 默认测试
 make test

+# 分类测试
+make test-unit
+make test-integration
+
 # 生成覆盖率报告
 make test-coverage
+
+# MySQL 专项测试
+make mysql-up
+make mysql-down
+make mysql-test
+make mysql-test-quick
 ```

 ## 数据库迁移

 ```bash
 # 使用 Makefile
-make migrate-up DB_PATH=~/.nex/config.db
-make migrate-down DB_PATH=~/.nex/config.db
-make migrate-status DB_PATH=~/.nex/config.db
+make migrate-up DB_DSN=~/.nex/config.db
+make migrate-down DB_DSN=~/.nex/config.db
+make migrate-status DB_DSN=~/.nex/config.db

 # 创建新迁移
 make migrate-create

+# MySQL 迁移
+make migrate-up DB_DRIVER=mysql DB_DSN='user:pass@tcp(localhost:3306)/nex'
+
 # 或直接使用 goose
 goose -dir migrations sqlite3 ~/.nex/config.db up
 ```
@@ -564,6 +577,20 @@ GET  /anthropic/v1/models

 查询参数：`provider_id`、`model_name`、`start_date`（YYYY-MM-DD）、`end_date`、`group_by`（provider/model/date）

+#### 版本信息
+
+- `GET /api/version` - 获取后端构建版本信息
+
+响应字段来源于构建阶段注入的 `buildinfo` 元数据：
+
+```json
+{
+  "version": "0.1.0",
+  "commit": "abc1234",
+  "build_time": "2026-05-05T00:00:00Z"
+}
+```
+
 #### 健康检查

 - `GET /health` - 返回 `{"status": "ok"}`
@@ -571,9 +598,12 @@ GET  /anthropic/v1/models
 ## 开发

 ```bash
-make build    # 构建
-make lint     # 代码检查
-make deps     # 整理依赖
+make build           # 构建 backend/bin/server
+make run             # 运行后端服务
+make lint            # 代码检查
+make clean           # 清理 backend 构建产物
+go mod tidy          # 整理依赖
+go generate ./...    # 刷新 mock 等生成代码
 ```

 环境要求：Go 1.26 或更高版本
--- a/backend/cmd/desktop/main.go
+++ b/backend/cmd/desktop/main.go
@@ -25,6 +25,7 @@ import (
 	"nex/backend/internal/provider"
 	"nex/backend/internal/repository"
 	"nex/backend/internal/service"
+	"nex/backend/pkg/buildinfo"

 	"github.com/getlantern/systray"
 	"github.com/gin-gonic/gin"
@@ -129,6 +130,7 @@ func main() {
 	providerHandler := handler.NewProviderHandler(providerService)
 	modelHandler := handler.NewModelHandler(modelService)
 	statsHandler := handler.NewStatsHandler(statsService)
+	versionHandler := handler.NewVersionHandler()

 	gin.SetMode(gin.ReleaseMode)
 	r := gin.New()
@@ -138,7 +140,7 @@ func main() {
 	r.Use(middleware.Logging(zapLogger))
 	r.Use(middleware.CORS())

-	setupRoutes(r, proxyHandler, providerHandler, modelHandler, statsHandler)
+	setupRoutes(r, proxyHandler, providerHandler, modelHandler, statsHandler, versionHandler)
 	setupStaticFiles(r)

 	server = &http.Server{
@@ -151,7 +153,11 @@ func main() {
 	shutdownCtx, shutdownCancel = context.WithCancel(context.Background())

 	go func() {
-		zapLogger.Info("AI Gateway 启动", zap.String("addr", server.Addr))
+		zapLogger.Info("AI Gateway 启动",
+			zap.String("addr", server.Addr),
+			zap.String("version", buildinfo.Version()),
+			zap.String("commit", buildinfo.Commit()),
+			zap.String("build_time", buildinfo.BuildTime()))
 		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 			zapLogger.Fatal("服务器启动失败", zap.Error(err))
 		}
@@ -167,9 +173,10 @@ func main() {
 	setupSystray(port)
 }

-func setupRoutes(r *gin.Engine, proxyHandler *handler.ProxyHandler, providerHandler *handler.ProviderHandler, modelHandler *handler.ModelHandler, statsHandler *handler.StatsHandler) {
+func setupRoutes(r *gin.Engine, proxyHandler *handler.ProxyHandler, providerHandler *handler.ProviderHandler, modelHandler *handler.ModelHandler, statsHandler *handler.StatsHandler, versionHandler *handler.VersionHandler) {
 	r.Any("/openai/*path", withProtocol("openai", proxyHandler.HandleProxy))
 	r.Any("/anthropic/*path", withProtocol("anthropic", proxyHandler.HandleProxy))
+	r.GET("/api/version", versionHandler.GetVersion)

 	providers := r.Group("/api/providers")
 	{
@@ -252,13 +259,13 @@ func setupStaticFilesWithFS(r *gin.Engine, distFS fs.FS) {
 		c.Data(200, getContentType(filepath), data)
 	})

-	r.GET("/favicon.svg", func(c *gin.Context) {
-		data, err := fs.ReadFile(distFS, "favicon.svg")
+	r.GET("/icon.png", func(c *gin.Context) {
+		data, err := fs.ReadFile(distFS, "icon.png")
 		if err != nil {
 			c.Status(404)
 			return
 		}
-		c.Data(200, "image/svg+xml", data)
+		c.Data(200, "image/png", data)
 	})

 	r.NoRoute(func(c *gin.Context) {
--- a/backend/cmd/desktop/routes_test.go
+++ b/backend/cmd/desktop/routes_test.go
@@ -0,0 +1,44 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"testing/fstest"
+
+	"nex/backend/internal/handler"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestSetupRoutes_VersionDoesNotFallback(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	r := gin.New()
+	setupRoutes(r, &handler.ProxyHandler{}, &handler.ProviderHandler{}, &handler.ModelHandler{}, &handler.StatsHandler{}, handler.NewVersionHandler())
+	setupStaticFilesWithFS(r, fstest.MapFS{
+		"index.html": {Data: []byte("<html>fallback</html>")},
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/api/version", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", w.Code, http.StatusOK)
+	}
+	if contentType := w.Header().Get("Content-Type"); contentType == "text/html; charset=utf-8" {
+		t.Fatalf("版本接口不应返回 SPA fallback HTML")
+	}
+
+	var result map[string]string
+	if err := json.Unmarshal(w.Body.Bytes(), &result); err != nil {
+		t.Fatalf("解析响应失败: %v", err)
+	}
+	for _, key := range []string{"version", "commit", "build_time"} {
+		if result[key] == "" {
+			t.Fatalf("响应缺少 %s 字段: %#v", key, result)
+		}
+	}
+}
--- a/backend/cmd/desktop/static_test.go
+++ b/backend/cmd/desktop/static_test.go
@@ -5,6 +5,7 @@ import (
 	"net/http/httptest"
 	"strings"
 	"testing"
+	"testing/fstest"

 	"github.com/gin-gonic/gin"
 )
@@ -100,6 +101,30 @@ func TestSetupStaticFiles(t *testing.T) {
 	t.Log("静态文件服务测试通过")
 }

+func TestSetupStaticFilesWithFS_IconPNG(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	r := gin.New()
+	setupStaticFilesWithFS(r, fstest.MapFS{
+		"icon.png":   {Data: []byte("png")},
+		"index.html": {Data: []byte("<html>fallback</html>")},
+	})
+
+	req := httptest.NewRequest("GET", "/icon.png", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("期望状态码 200, 实际 %d", w.Code)
+	}
+	if w.Header().Get("Content-Type") != "image/png" {
+		t.Fatalf("期望 Content-Type image/png, 实际 %s", w.Header().Get("Content-Type"))
+	}
+	if w.Body.String() != "png" {
+		t.Fatalf("期望返回 PNG 内容，实际 %q", w.Body.String())
+	}
+}
+
 func TestWithProtocolAndStaticRoutes(t *testing.T) {
 	gin.SetMode(gin.TestMode)

--- a/backend/cmd/server/main.go
+++ b/backend/cmd/server/main.go
@@ -22,6 +22,7 @@ import (
 	"nex/backend/internal/provider"
 	"nex/backend/internal/repository"
 	"nex/backend/internal/service"
+	"nex/backend/pkg/buildinfo"
 	pkgLogger "nex/backend/pkg/logger"
 )

@@ -92,6 +93,7 @@ func main() {
 	providerHandler := handler.NewProviderHandler(providerService)
 	modelHandler := handler.NewModelHandler(modelService)
 	statsHandler := handler.NewStatsHandler(statsService)
+	versionHandler := handler.NewVersionHandler()

 	gin.SetMode(gin.ReleaseMode)
 	r := gin.New()
@@ -101,7 +103,7 @@ func main() {
 	r.Use(middleware.Logging(zapLogger))
 	r.Use(middleware.CORS())

-	setupRoutes(r, proxyHandler, providerHandler, modelHandler, statsHandler)
+	setupRoutes(r, proxyHandler, providerHandler, modelHandler, statsHandler, versionHandler)

 	srv := &http.Server{
 		Addr:         fmt.Sprintf(":%d", cfg.Server.Port),
@@ -111,7 +113,11 @@ func main() {
 	}

 	go func() {
-		zapLogger.Info("AI Gateway 启动", zap.String("addr", srv.Addr))
+		zapLogger.Info("AI Gateway 启动",
+			zap.String("addr", srv.Addr),
+			zap.String("version", buildinfo.Version()),
+			zap.String("commit", buildinfo.Commit()),
+			zap.String("build_time", buildinfo.BuildTime()))
 		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 			zapLogger.Fatal("服务器启动失败", zap.Error(err))
 		}
@@ -135,8 +141,9 @@ func main() {
 	zapLogger.Info("服务器已关闭")
 }

-func setupRoutes(r *gin.Engine, proxyHandler *handler.ProxyHandler, providerHandler *handler.ProviderHandler, modelHandler *handler.ModelHandler, statsHandler *handler.StatsHandler) {
+func setupRoutes(r *gin.Engine, proxyHandler *handler.ProxyHandler, providerHandler *handler.ProviderHandler, modelHandler *handler.ModelHandler, statsHandler *handler.StatsHandler, versionHandler *handler.VersionHandler) {
 	r.Any("/:protocol/*path", proxyHandler.HandleProxy)
+	r.GET("/api/version", versionHandler.GetVersion)

 	providers := r.Group("/api/providers")
 	{
--- a/backend/cmd/server/routes_test.go
+++ b/backend/cmd/server/routes_test.go
@@ -0,0 +1,37 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"nex/backend/internal/handler"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestSetupRoutes_Version(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	r := gin.New()
+	setupRoutes(r, &handler.ProxyHandler{}, &handler.ProviderHandler{}, &handler.ModelHandler{}, &handler.StatsHandler{}, handler.NewVersionHandler())
+
+	req := httptest.NewRequest(http.MethodGet, "/api/version", nil)
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", w.Code, http.StatusOK)
+	}
+
+	var result map[string]string
+	if err := json.Unmarshal(w.Body.Bytes(), &result); err != nil {
+		t.Fatalf("解析响应失败: %v", err)
+	}
+	for _, key := range []string{"version", "commit", "build_time"} {
+		if result[key] == "" {
+			t.Fatalf("响应缺少 %s 字段: %#v", key, result)
+		}
+	}
+}
--- a/backend/internal/handler/middleware/logging.go
+++ b/backend/internal/handler/middleware/logging.go
@@ -20,7 +20,7 @@ func Logging(logger *zap.Logger) gin.HandlerFunc {
 		if id, ok := requestID.(string); ok {
 			requestIDStr = id
 		}
-		logger.Info("请求开始",
+		logger.Debug("请求开始",
 			pkglogger.Method(c.Request.Method),
 			pkglogger.Path(path),
 			pkglogger.Query(query),
@@ -33,7 +33,7 @@ func Logging(logger *zap.Logger) gin.HandlerFunc {
 		latency := time.Since(start)
 		statusCode := c.Writer.Status()

-		logger.Info("请求结束",
+		logger.Debug("请求结束",
 			pkglogger.StatusCode(statusCode),
 			pkglogger.Method(c.Request.Method),
 			pkglogger.Path(path),
--- a/backend/internal/handler/middleware/middleware_test.go
+++ b/backend/internal/handler/middleware/middleware_test.go
@@ -7,6 +7,8 @@ import (
 	"github.com/gin-gonic/gin"
 	"github.com/stretchr/testify/assert"
 	"go.uber.org/zap"
+	"go.uber.org/zap/zapcore"
+	"go.uber.org/zap/zaptest/observer"
 )

 func init() {
@@ -65,6 +67,61 @@ func TestLogging(t *testing.T) {
 	assert.Equal(t, 200, w.Code)
 }

+func TestLogging_DoesNotLogLifecycleAtInfoLevel(t *testing.T) {
+	core, logs := observer.New(zapcore.InfoLevel)
+	logger := zap.New(core)
+
+	w := serveLoggingRequest(logger)
+
+	assert.Equal(t, 200, w.Code)
+	assert.Empty(t, logs.FilterMessage("请求开始").All())
+	assert.Empty(t, logs.FilterMessage("请求结束").All())
+}
+
+func TestLogging_LogsLifecycleAtDebugLevel(t *testing.T) {
+	core, logs := observer.New(zapcore.DebugLevel)
+	logger := zap.New(core)
+
+	w := serveLoggingRequest(logger)
+
+	assert.Equal(t, 200, w.Code)
+	startLogs := logs.FilterMessage("请求开始").All()
+	endLogs := logs.FilterMessage("请求结束").All()
+	if assert.Len(t, startLogs, 1) {
+		fields := startLogs[0].ContextMap()
+		assert.Equal(t, "GET", fields["method"])
+		assert.Equal(t, "/test", fields["path"])
+		assert.Equal(t, "key=value", fields["query"])
+		assert.Equal(t, "existing-id-123", fields["request_id"])
+		assert.NotEmpty(t, fields["client_ip"])
+	}
+	if assert.Len(t, endLogs, 1) {
+		fields := endLogs[0].ContextMap()
+		assert.Equal(t, int64(200), fields["status"])
+		assert.Equal(t, "GET", fields["method"])
+		assert.Equal(t, "/test", fields["path"])
+		assert.Equal(t, int64(2), fields["body_size"])
+		assert.Equal(t, "existing-id-123", fields["request_id"])
+		assert.Contains(t, fields, "latency")
+	}
+}
+
+func serveLoggingRequest(logger *zap.Logger) *httptest.ResponseRecorder {
+	r := gin.New()
+	r.Use(RequestID())
+	r.Use(Logging(logger))
+	r.GET("/test", func(c *gin.Context) {
+		c.String(200, "ok")
+	})
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/test?key=value", nil)
+	req.Header.Set("X-Request-ID", "existing-id-123")
+	r.ServeHTTP(w, req)
+
+	return w
+}
+
 func TestRecovery_NoPanic(t *testing.T) {
 	logger := zap.NewNop()

--- a/backend/internal/handler/version_handler.go
+++ b/backend/internal/handler/version_handler.go
@@ -0,0 +1,26 @@
+package handler
+
+import (
+	"net/http"
+
+	"nex/backend/pkg/buildinfo"
+
+	"github.com/gin-gonic/gin"
+)
+
+// VersionHandler 提供后端构建版本信息。
+type VersionHandler struct{}
+
+// NewVersionHandler 创建版本信息处理器。
+func NewVersionHandler() *VersionHandler {
+	return &VersionHandler{}
+}
+
+// GetVersion 返回构建注入的版本元数据。
+func (h *VersionHandler) GetVersion(c *gin.Context) {
+	c.JSON(http.StatusOK, gin.H{
+		"version":    buildinfo.Version(),
+		"commit":     buildinfo.Commit(),
+		"build_time": buildinfo.BuildTime(),
+	})
+}
--- a/backend/internal/handler/version_handler_test.go
+++ b/backend/internal/handler/version_handler_test.go
@@ -0,0 +1,31 @@
+package handler
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestVersionHandler_GetVersion(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	h := NewVersionHandler()
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodGet, "/api/version", nil)
+
+	h.GetVersion(c)
+
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	var result map[string]string
+	require.NoError(t, json.Unmarshal(w.Body.Bytes(), &result))
+	assert.Equal(t, "dev", result["version"])
+	assert.Equal(t, "unknown", result["commit"])
+	assert.Equal(t, "unknown", result["build_time"])
+}
--- a/backend/pkg/buildinfo/buildinfo.go
+++ b/backend/pkg/buildinfo/buildinfo.go
@@ -0,0 +1,22 @@
+package buildinfo
+
+var (
+	version   = "dev"
+	commit    = "unknown"
+	buildTime = "unknown"
+)
+
+// Version 返回构建注入的版本号。
+func Version() string {
+	return version
+}
+
+// Commit 返回构建注入的 git commit。
+func Commit() string {
+	return commit
+}
+
+// BuildTime 返回构建注入的构建时间。
+func BuildTime() string {
+	return buildTime
+}
--- a/backend/pkg/buildinfo/buildinfo_test.go
+++ b/backend/pkg/buildinfo/buildinfo_test.go
@@ -0,0 +1,17 @@
+package buildinfo
+
+import "testing"
+
+func TestDefaults(t *testing.T) {
+	if Version() == "" {
+		t.Fatal("Version() 不应为空")
+	}
+
+	if Commit() == "" {
+		t.Fatal("Commit() 不应为空")
+	}
+
+	if BuildTime() == "" {
+		t.Fatal("BuildTime() 不应为空")
+	}
+}
--- a/frontend/.env.desktop
+++ b/frontend/.env.desktop
@@ -1 +1,2 @@
 VITE_API_BASE=
+VITE_APP_VERSION=0.1.2
--- a/frontend/.env.development
+++ b/frontend/.env.development
@@ -1 +1,2 @@
 VITE_API_BASE=
+VITE_APP_VERSION=0.1.2
--- a/frontend/.env.production
+++ b/frontend/.env.production
@@ -1 +1,2 @@
 VITE_API_BASE=/api
+VITE_APP_VERSION=0.1.2
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -1,4 +1,4 @@
-# AI Gateway Frontend
+# Nex Frontend

 AI 网关管理前端，提供供应商配置和用量统计界面。

@@ -11,7 +11,7 @@ AI 网关管理前端，提供供应商配置和用量统计界面。
 - **UI 组件库**: TDesign
 - **路由**: React Router v7
 - **数据获取**: TanStack Query v5
- **样式**: SCSS Modules（禁止使用纯 CSS）
+- **样式**: TDesign 组件 props 优先，TDesign tokens 次之，SCSS 作为兜底补充
 - **测试**: Vitest + React Testing Library + Playwright
 - **代码格式化**: Prettier

@@ -86,17 +86,20 @@ frontend/
 │   │   ├── client.ts           # 统一 request<T>() + 字段转换
 │   │   ├── providers.ts        # Provider CRUD
 │   │   ├── models.ts           # Model CRUD
-│   │   └── stats.ts            # Stats 查询
+│   │   ├── stats.ts            # Stats 查询
+│   │   └── version.ts          # 后端版本查询
 │   ├── components/
 │   │   └── AppLayout/          # 侧边栏导航布局
 │   ├── hooks/                  # TanStack Query hooks
 │   │   ├── useProviders.ts
 │   │   ├── useModels.ts
-│   │   └── useStats.ts
+│   │   ├── useStats.ts
+│   │   └── useVersion.ts
 │   ├── pages/
 │   │   ├── Providers/          # 供应商管理（含内嵌模型管理）
 │   │   ├── Stats/              # 用量统计
 │   │   ├── Settings/           # 设置（开发中）
+│   │   ├── About/              # 关于页面（品牌与版本信息）
 │   │   └── NotFound.tsx
 │   ├── routes/
 │   │   └── index.tsx           # 路由配置
@@ -111,6 +114,7 @@ frontend/
 │   ├── main.tsx
 │   └── index.scss
 ├── e2e/                        # Playwright E2E 测试
+├── public/                     # 静态资源（icon.png 来源于 ../assets/icon.png）
 ├── vitest.config.ts
 ├── playwright.config.ts
 ├── tsconfig.json
@@ -200,6 +204,12 @@ bun run test:e2e
 - 按模型筛选
 - 按日期范围筛选（DatePicker.RangePicker）

+### 关于页面
+
+- 展示应用名称、产品描述和项目链接
+- 展示前端版本、后端版本、后端 commit 和构建时间
+- 根据 `VITE_APP_VERSION` 与 `GET /api/version` 返回值提示前后端版本是否一致
+
 ## 测试策略

 ### 目录结构
@@ -231,9 +241,10 @@ __tests__/

 ## 环境变量

-| 变量            | 开发环境 | 生产环境 | 说明                            |
-| --------------- | -------- | -------- | ------------------------------- |
-| `VITE_API_BASE` | （空）   | `/api`   | API 基础路径，空则走 Vite proxy |
+| 变量               | 开发环境 | 生产环境 | 说明                                      |
+| ------------------ | -------- | -------- | ----------------------------------------- |
+| `VITE_API_BASE`    | （空）   | `/api`   | API 基础路径，空则走 Vite proxy           |
+| `VITE_APP_VERSION` | `0.1.0`  | `0.1.0`  | 前端构建版本，由 `make version-sync` 同步 |

 **E2E 测试特有**：

@@ -242,9 +253,11 @@ __tests__/

 ## 开发规范

- 所有样式使用 SCSS，禁止使用纯 CSS 文件
- 组件级样式使用 SCSS Modules（\*.module.scss）
+- 样式优先使用 TDesign 组件 props（如 `hoverShadow`、`headerBordered`、`variant`、`shape`、`gutter`）
+- 组件 props 无法表达时使用 TDesign tokens（`var(--td-*)`）
+- 仅当 props 和 tokens 无法满足布局、响应式或品牌视觉需求时使用 SCSS，禁止使用纯 CSS 文件
 - 图标优先使用 TDesign 图标（tdesign-icons-react）
+- 应用 favicon 使用 `frontend/public/icon.png`，该文件来源于仓库根目录 `assets/icon.png`
 - TypeScript strict 模式，禁止 any 类型
 - API 层自动处理 snake_case ↔ camelCase 字段转换
 - 使用路径别名 `@/` 引用 src 目录
--- a/frontend/e2e/navigation.spec.ts
+++ b/frontend/e2e/navigation.spec.ts
@@ -12,7 +12,7 @@ test.describe('侧边栏', () => {
  })

  test('应显示应用名称', async ({ page }) => {
-    await expect(page.locator('aside').getByText('AI Gateway')).toBeVisible()
+    await expect(page.locator('aside').getByText('Nex')).toBeVisible()
  })

  test('应显示导航菜单项', async ({ page }) => {
@@ -41,6 +41,15 @@ test.describe('页面导航', () => {
    await expect(page.getByRole('heading', { name: '供应商管理' })).toBeVisible()
  })

+  test('应能切换到关于页面并显示版本信息', async ({ page }) => {
+    await page.locator('aside').getByText('关于').click()
+
+    await expect(page.getByRole('heading', { name: '关于' })).toBeVisible()
+    await expect(page.getByRole('heading', { name: 'Nex' })).toBeVisible()
+    await expect(page.getByText('前端版本')).toBeVisible()
+    await expect(page.getByText('后端版本')).toBeVisible()
+  })
+
  test('应在刷新后保持当前页面', async ({ page }) => {
    await page.locator('aside').getByText('用量统计').click()
    await expect(page.getByRole('heading', { name: '用量统计' })).toBeVisible()
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -2,9 +2,9 @@
 <html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="icon" type="image/png" href="/icon.png" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>AI Gateway</title>
+    <title>Nex</title>
  </head>
  <body>
    <div id="root"></div>
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -1,7 +1,7 @@
 {
  "name": "frontend",
  "private": true,
-  "version": "0.0.0",
+  "version": "0.1.2",
  "license": "Apache-2.0",
  "type": "module",
  "scripts": {
--- a/frontend/public/favicon.svg
+++ b/frontend/public/favicon.svg
--- a/frontend/public/icon.png
+++ b/frontend/public/icon.png
--- a/frontend/public/icons.svg
+++ b/frontend/public/icons.svg
@@ -1,24 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg">
-  <symbol id="bluesky-icon" viewBox="0 0 16 17">
-    <g clip-path="url(#bluesky-clip)"><path fill="#08060d" d="M7.75 7.735c-.693-1.348-2.58-3.86-4.334-5.097-1.68-1.187-2.32-.981-2.74-.79C.188 2.065.1 2.812.1 3.251s.241 3.602.398 4.13c.52 1.744 2.367 2.333 4.07 2.145-2.495.37-4.71 1.278-1.805 4.512 3.196 3.309 4.38-.71 4.987-2.746.608 2.036 1.307 5.91 4.93 2.746 2.72-2.746.747-4.143-1.747-4.512 1.702.189 3.55-.4 4.07-2.145.156-.528.397-3.691.397-4.13s-.088-1.186-.575-1.406c-.42-.19-1.06-.395-2.741.79-1.755 1.24-3.64 3.752-4.334 5.099"/></g>
-    <defs><clipPath id="bluesky-clip"><path fill="#fff" d="M.1.85h15.3v15.3H.1z"/></clipPath></defs>
-  </symbol>
-  <symbol id="discord-icon" viewBox="0 0 20 19">
-    <path fill="#08060d" d="M16.224 3.768a14.5 14.5 0 0 0-3.67-1.153c-.158.286-.343.67-.47.976a13.5 13.5 0 0 0-4.067 0c-.128-.306-.317-.69-.476-.976A14.4 14.4 0 0 0 3.868 3.77C1.546 7.28.916 10.703 1.231 14.077a14.7 14.7 0 0 0 4.5 2.306q.545-.748.965-1.587a9.5 9.5 0 0 1-1.518-.74q.191-.14.372-.293c2.927 1.369 6.107 1.369 8.999 0q.183.152.372.294-.723.437-1.52.74.418.838.963 1.588a14.6 14.6 0 0 0 4.504-2.308c.37-3.911-.63-7.302-2.644-10.309m-9.13 8.234c-.878 0-1.599-.82-1.599-1.82 0-.998.705-1.82 1.6-1.82.894 0 1.614.82 1.599 1.82.001 1-.705 1.82-1.6 1.82m5.91 0c-.878 0-1.599-.82-1.599-1.82 0-.998.705-1.82 1.6-1.82.893 0 1.614.82 1.599 1.82 0 1-.706 1.82-1.6 1.82"/>
-  </symbol>
-  <symbol id="documentation-icon" viewBox="0 0 21 20">
-    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="m15.5 13.333 1.533 1.322c.645.555.967.833.967 1.178s-.322.623-.967 1.179L15.5 18.333m-3.333-5-1.534 1.322c-.644.555-.966.833-.966 1.178s.322.623.966 1.179l1.534 1.321"/>
-    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M17.167 10.836v-4.32c0-1.41 0-2.117-.224-2.68-.359-.906-1.118-1.621-2.08-1.96-.599-.21-1.349-.21-2.848-.21-2.623 0-3.935 0-4.983.369-1.684.591-3.013 1.842-3.641 3.428C3 6.449 3 7.684 3 10.154v2.122c0 2.558 0 3.838.706 4.726q.306.383.713.671c.76.536 1.79.64 3.581.66"/>
-    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M3 10a2.78 2.78 0 0 1 2.778-2.778c.555 0 1.209.097 1.748-.047.48-.129.854-.503.982-.982.145-.54.048-1.194.048-1.749a2.78 2.78 0 0 1 2.777-2.777"/>
-  </symbol>
-  <symbol id="github-icon" viewBox="0 0 19 19">
-    <path fill="#08060d" fill-rule="evenodd" d="M9.356 1.85C5.05 1.85 1.57 5.356 1.57 9.694a7.84 7.84 0 0 0 5.324 7.44c.387.079.528-.168.528-.376 0-.182-.013-.805-.013-1.454-2.165.467-2.616-.935-2.616-.935-.349-.91-.864-1.143-.864-1.143-.71-.48.051-.48.051-.48.787.051 1.2.805 1.2.805.695 1.194 1.817.857 2.268.649.064-.507.27-.857.49-1.052-1.728-.182-3.545-.857-3.545-3.87 0-.857.31-1.558.8-2.104-.078-.195-.349-1 .077-2.078 0 0 .657-.208 2.14.805a7.5 7.5 0 0 1 1.946-.26c.657 0 1.328.092 1.946.26 1.483-1.013 2.14-.805 2.14-.805.426 1.078.155 1.883.078 2.078.502.546.799 1.247.799 2.104 0 3.013-1.818 3.675-3.558 3.87.284.247.528.714.528 1.454 0 1.052-.012 1.896-.012 2.156 0 .208.142.455.528.377a7.84 7.84 0 0 0 5.324-7.441c.013-4.338-3.48-7.844-7.773-7.844" clip-rule="evenodd"/>
-  </symbol>
-  <symbol id="social-icon" viewBox="0 0 20 20">
-    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M12.5 6.667a4.167 4.167 0 1 0-8.334 0 4.167 4.167 0 0 0 8.334 0"/>
-    <path fill="none" stroke="#aa3bff" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.35" d="M2.5 16.667a5.833 5.833 0 0 1 8.75-5.053m3.837.474.513 1.035c.07.144.257.282.414.309l.93.155c.596.1.736.536.307.965l-.723.73a.64.64 0 0 0-.152.531l.207.903c.164.715-.213.991-.84.618l-.872-.52a.63.63 0 0 0-.577 0l-.872.52c-.624.373-1.003.094-.84-.618l.207-.903a.64.64 0 0 0-.152-.532l-.723-.729c-.426-.43-.289-.864.306-.964l.93-.156a.64.64 0 0 0 .412-.31l.513-1.034c.28-.562.735-.562 1.012 0"/>
-  </symbol>
-  <symbol id="x-icon" viewBox="0 0 19 19">
-    <path fill="#08060d" fill-rule="evenodd" d="M1.893 1.98c.052.072 1.245 1.769 2.653 3.77l2.892 4.114c.183.261.333.48.333.486s-.068.089-.152.183l-.522.593-.765.867-3.597 4.087c-.375.426-.734.834-.798.905a1 1 0 0 0-.118.148c0 .01.236.017.664.017h.663l.729-.83c.4-.457.796-.906.879-.999a692 692 0 0 0 1.794-2.038c.034-.037.301-.34.594-.675l.551-.624.345-.392a7 7 0 0 1 .34-.374c.006 0 .93 1.306 2.052 2.903l2.084 2.965.045.063h2.275c1.87 0 2.273-.003 2.266-.021-.008-.02-1.098-1.572-3.894-5.547-2.013-2.862-2.28-3.246-2.273-3.266.008-.019.282-.332 2.085-2.38l2-2.274 1.567-1.782c.022-.028-.016-.03-.65-.03h-.674l-.3.342a871 871 0 0 1-1.782 2.025c-.067.075-.405.458-.75.852a100 100 0 0 1-.803.91c-.148.172-.299.344-.99 1.127-.304.343-.32.358-.345.327-.015-.019-.904-1.282-1.976-2.808L6.365 1.85H1.8zm1.782.91 8.078 11.294c.772 1.08 1.413 1.973 1.425 1.984.016.017.241.02 1.05.017l1.03-.004-2.694-3.766L7.796 5.75 5.722 2.852l-1.039-.004-1.039-.004z" clip-rule="evenodd"/>
-  </symbol>
-</svg>
--- a/frontend/src/tests/api/version.test.ts
+++ b/frontend/src/tests/api/version.test.ts
@@ -0,0 +1,30 @@
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+import { describe, it, expect, beforeAll, afterEach, afterAll } from 'vitest'
+import { getBackendVersion } from '@/api/version'
+
+describe('version API', () => {
+  const server = setupServer()
+
+  beforeAll(() => server.listen({ onUnhandledRequest: 'bypass' }))
+  afterEach(() => server.resetHandlers())
+  afterAll(() => server.close())
+
+  it('fetches backend version and converts build_time to buildTime', async () => {
+    server.use(
+      http.get('http://localhost:3000/api/version', () => {
+        return HttpResponse.json({
+          version: '0.1.0',
+          commit: 'abc1234',
+          build_time: '2026-05-05T00:00:00Z',
+        })
+      })
+    )
+
+    await expect(getBackendVersion()).resolves.toEqual({
+      version: '0.1.0',
+      commit: 'abc1234',
+      buildTime: '2026-05-05T00:00:00Z',
+    })
+  })
+})
--- a/frontend/src/tests/components/AppLayout.test.tsx
+++ b/frontend/src/tests/components/AppLayout.test.tsx
@@ -1,25 +1,37 @@
 import { render, screen } from '@testing-library/react'
-import { BrowserRouter } from 'react-router'
+import userEvent from '@testing-library/user-event'
+import { MemoryRouter } from 'react-router'
 import { describe, it, expect } from 'vitest'
 import { AppLayout } from '@/components/AppLayout'

 const renderWithRouter = (component: React.ReactNode) => {
-  return render(<BrowserRouter>{component}</BrowserRouter>)
+  return render(<MemoryRouter initialEntries={['/providers']}>{component}</MemoryRouter>)
 }

 describe('AppLayout', () => {
  it('renders sidebar with app name', () => {
    renderWithRouter(<AppLayout />)

-    const appNames = screen.getAllByText('AI Gateway')
-    expect(appNames.length).toBeGreaterThan(0)
+    expect(screen.getByText('Nex')).toBeInTheDocument()
+    expect(screen.getByAltText('Nex logo')).toBeInTheDocument()
+  })
+
+  it('keeps logo visible when sidebar is collapsed', async () => {
+    const user = userEvent.setup()
+    renderWithRouter(<AppLayout />)
+
+    await user.click(screen.getByLabelText('收起侧边栏'))
+
+    expect(screen.getByAltText('Nex logo')).toBeInTheDocument()
+    expect(screen.queryByText('Nex')).not.toBeInTheDocument()
+    expect(screen.getByLabelText('展开侧边栏')).toBeInTheDocument()
  })

  it('renders navigation menu items', () => {
    renderWithRouter(<AppLayout />)

-    expect(screen.getByText('供应商管理')).toBeInTheDocument()
-    expect(screen.getByText('用量统计')).toBeInTheDocument()
+    expect(screen.getAllByText('供应商管理').length).toBeGreaterThan(0)
+    expect(screen.getAllByText('用量统计').length).toBeGreaterThan(0)
  })

  it('renders settings menu item', () => {
@@ -28,6 +40,12 @@ describe('AppLayout', () => {
    expect(screen.getByText('设置')).toBeInTheDocument()
  })

+  it('renders about menu item', () => {
+    renderWithRouter(<AppLayout />)
+
+    expect(screen.getByText('关于')).toBeInTheDocument()
+  })
+
  it('renders content outlet', () => {
    const { container } = renderWithRouter(<AppLayout />)

--- a/frontend/src/tests/hooks/useVersion.test.tsx
+++ b/frontend/src/tests/hooks/useVersion.test.tsx
@@ -0,0 +1,33 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { renderHook, waitFor } from '@testing-library/react'
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+import React from 'react'
+import { useBackendVersion } from '@/hooks/useVersion'
+
+const server = setupServer(
+  http.get('/api/version', () => {
+    return HttpResponse.json({ version: '0.1.0', commit: 'abc1234', build_time: '2026-05-05T00:00:00Z' })
+  })
+)
+
+function createWrapper() {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+  return function Wrapper({ children }: { children: React.ReactNode }) {
+    return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  }
+}
+
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+
+describe('useBackendVersion', () => {
+  it('fetches backend version', async () => {
+    const { result } = renderHook(() => useBackendVersion(), { wrapper: createWrapper() })
+
+    await waitFor(() => expect(result.current.isSuccess).toBe(true))
+
+    expect(result.current.data).toEqual({ version: '0.1.0', commit: 'abc1234', buildTime: '2026-05-05T00:00:00Z' })
+  })
+})
--- a/frontend/src/tests/pages/About.test.tsx
+++ b/frontend/src/tests/pages/About.test.tsx
@@ -0,0 +1,88 @@
+import { render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { useBackendVersion } from '@/hooks/useVersion'
+import AboutPage from '@/pages/About'
+
+vi.mock('@/hooks/useVersion', () => ({
+  useBackendVersion: vi.fn(),
+}))
+
+vi.mock('@/constants/app', () => ({
+  APP_NAME: 'Nex',
+  APP_DESCRIPTION: 'AI Gateway - 统一的大模型 API 网关',
+  APP_WEBSITE: 'https://github.com/nex/gateway',
+  APP_VERSION: '0.1.0',
+}))
+
+const mockUseBackendVersion = useBackendVersion as ReturnType<typeof vi.fn>
+
+describe('AboutPage', () => {
+  beforeEach(() => {
+    mockUseBackendVersion.mockReturnValue({
+      data: { version: '0.1.0', commit: 'abc1234', buildTime: '2026-05-05T00:00:00Z' },
+      isError: false,
+      isLoading: false,
+    } as ReturnType<typeof useBackendVersion>)
+  })
+
+  it('renders brand, description and links', () => {
+    render(<AboutPage />)
+
+    expect(screen.getByRole('heading', { name: 'Nex' })).toBeInTheDocument()
+    expect(screen.getByText('AI Gateway - 统一的大模型 API 网关')).toBeInTheDocument()
+    expect(screen.getByText('GitHub')).toHaveAttribute('href', 'https://github.com/nex/gateway')
+  })
+
+  it('shows frontend and backend versions', () => {
+    render(<AboutPage />)
+
+    expect(screen.getByText('前端版本')).toBeInTheDocument()
+    expect(screen.getAllByText('0.1.0').length).toBeGreaterThan(0)
+    expect(screen.getByText('abc1234')).toBeInTheDocument()
+    expect(screen.getByText('2026-05-05T00:00:00Z')).toBeInTheDocument()
+  })
+
+  it('shows matched status', () => {
+    render(<AboutPage />)
+
+    expect(screen.getByText('版本一致')).toBeInTheDocument()
+  })
+
+  it('shows mismatched status', () => {
+    mockUseBackendVersion.mockReturnValue({
+      data: { version: '0.2.0', commit: 'abc1234', buildTime: '2026-05-05T00:00:00Z' },
+      isError: false,
+      isLoading: false,
+    } as ReturnType<typeof useBackendVersion>)
+
+    render(<AboutPage />)
+
+    expect(screen.getByText('版本不一致')).toBeInTheDocument()
+    expect(screen.getByText(/用于部署诊断/)).toBeInTheDocument()
+  })
+
+  it('shows unknown status for dev backend version', () => {
+    mockUseBackendVersion.mockReturnValue({
+      data: { version: 'dev', commit: 'unknown', buildTime: 'unknown' },
+      isError: false,
+      isLoading: false,
+    } as ReturnType<typeof useBackendVersion>)
+
+    render(<AboutPage />)
+
+    expect(screen.getByText('无法判断版本')).toBeInTheDocument()
+  })
+
+  it('shows unavailable status on backend request failure', () => {
+    mockUseBackendVersion.mockReturnValue({
+      data: undefined,
+      isError: true,
+      isLoading: false,
+    } as ReturnType<typeof useBackendVersion>)
+
+    render(<AboutPage />)
+
+    expect(screen.getByText('无法获取后端版本')).toBeInTheDocument()
+    expect(screen.getByText(/后端版本接口暂时不可用/)).toBeInTheDocument()
+  })
+})
--- a/frontend/src/tests/utils/version.test.ts
+++ b/frontend/src/tests/utils/version.test.ts
@@ -0,0 +1,21 @@
+import { describe, it, expect } from 'vitest'
+import { getVersionStatus } from '@/utils/version'
+
+describe('getVersionStatus', () => {
+  it('returns matched when versions are equal', () => {
+    expect(getVersionStatus('1.2.3', { version: '1.2.3', commit: 'abc', buildTime: 'now' }).kind).toBe('matched')
+  })
+
+  it('returns mismatched when release versions differ', () => {
+    expect(getVersionStatus('1.2.3', { version: '1.2.4', commit: 'abc', buildTime: 'now' }).kind).toBe('mismatched')
+  })
+
+  it('returns unknown for dev or unknown versions', () => {
+    expect(getVersionStatus('dev', { version: '1.2.3', commit: 'abc', buildTime: 'now' }).kind).toBe('unknown')
+    expect(getVersionStatus('1.2.3', { version: 'unknown', commit: 'abc', buildTime: 'now' }).kind).toBe('unknown')
+  })
+
+  it('returns unavailable on request failure', () => {
+    expect(getVersionStatus('1.2.3', undefined, true).kind).toBe('unavailable')
+  })
+})
--- a/frontend/src/api/version.ts
+++ b/frontend/src/api/version.ts
@@ -0,0 +1,6 @@
+import type { BackendVersion } from '@/types'
+import { request } from './client'
+
+export async function getBackendVersion(): Promise<BackendVersion> {
+  return request<BackendVersion>('GET', '/api/version')
+}
--- a/frontend/src/components/AppLayout/index.tsx
+++ b/frontend/src/components/AppLayout/index.tsx
@@ -9,6 +9,7 @@ import {
  ChevronRightIcon,
 } from 'tdesign-icons-react'
 import { Layout, Menu, Button } from 'tdesign-react'
+import { APP_NAME } from '@/constants/app'

 const { MenuItem } = Menu

@@ -22,7 +23,7 @@ export function AppLayout() {
    if (location.pathname === '/stats') return '用量统计'
    if (location.pathname === '/settings') return '设置'
    if (location.pathname === '/about') return '关于'
-    return 'AI Gateway'
+    return APP_NAME
  }

  const asideWidth = collapsed ? '64px' : '232px'
@@ -52,15 +53,18 @@ export function AppLayout() {
                display: 'flex',
                alignItems: 'center',
                justifyContent: 'center',
+                gap: 10,
                fontSize: '1.25rem',
                fontWeight: 600,
              }}
            >
-              {!collapsed && 'AI Gateway'}
+              <img src='/icon.png' alt={`${APP_NAME} logo`} style={{ width: 28, height: 28 }} />
+              {!collapsed && APP_NAME}
            </div>
          }
          operations={
            <Button
+              aria-label={collapsed ? '展开侧边栏' : '收起侧边栏'}
              variant='text'
              shape='square'
              icon={collapsed ? <ChevronRightIcon /> : <ChevronLeftIcon />}
--- a/frontend/src/constants/app.ts
+++ b/frontend/src/constants/app.ts
@@ -0,0 +1,4 @@
+export const APP_NAME = 'Nex'
+export const APP_DESCRIPTION = 'AI Gateway - 统一的大模型 API 网关'
+export const APP_WEBSITE = 'https://github.com/nex/gateway'
+export const APP_VERSION = import.meta.env.VITE_APP_VERSION || 'dev'
--- a/frontend/src/hooks/useVersion.ts
+++ b/frontend/src/hooks/useVersion.ts
@@ -0,0 +1,13 @@
+import { useQuery } from '@tanstack/react-query'
+import * as api from '@/api/version'
+
+export const versionKeys = {
+  backend: ['version', 'backend'] as const,
+}
+
+export function useBackendVersion() {
+  return useQuery({
+    queryKey: versionKeys.backend,
+    queryFn: api.getBackendVersion,
+  })
+}
--- a/frontend/src/pages/About/index.tsx
+++ b/frontend/src/pages/About/index.tsx
@@ -1,30 +1,77 @@
-import { Card } from 'tdesign-react'
+import { Alert, Card, Descriptions, Link, Space, Tag } from 'tdesign-react'
+import { APP_DESCRIPTION, APP_NAME, APP_VERSION, APP_WEBSITE } from '@/constants/app'
+import { useBackendVersion } from '@/hooks/useVersion'
+import type { VersionStatusKind } from '@/types'
+import { getVersionStatus } from '@/utils/version'
+
+const statusTheme: Record<VersionStatusKind, 'success' | 'warning' | 'default'> = {
+  matched: 'success',
+  mismatched: 'warning',
+  unknown: 'default',
+  unavailable: 'warning',
+}

 export default function AboutPage() {
+  const { data: backendVersion, isError, isLoading } = useBackendVersion()
+  const versionStatus = getVersionStatus(APP_VERSION, backendVersion, isError)
+
  return (
-    <Card bordered={false}>
-      <div
-        style={{
-          display: 'flex',
-          flexDirection: 'column',
-          alignItems: 'center',
-          justifyContent: 'center',
-          padding: '4rem 0',
-        }}
-      >
-        <h1 style={{ margin: 0, fontSize: '2rem' }}>Nex</h1>
-        <p style={{ margin: '0.5rem 0 0', color: 'var(--td-text-color-secondary)', fontSize: '1rem' }}>
-          AI Gateway - 统一的大模型 API 网关
-        </p>
-        <a
-          href='https://github.com/nex/gateway'
-          target='_blank'
-          rel='noopener noreferrer'
-          style={{ marginTop: '1rem', color: 'var(--td-brand-color)' }}
+    <div style={{ display: 'grid', gap: 'var(--td-comp-margin-l)' }}>
+      <Card bordered={false} hoverShadow>
+        <Space align='center' size='large'>
+          <img src='/icon.png' alt={`${APP_NAME} logo`} style={{ width: 56, height: 56 }} />
+          <div>
+            <h1 style={{ margin: 0, fontSize: '2rem' }}>{APP_NAME}</h1>
+            <p style={{ margin: '0.5rem 0 0', color: 'var(--td-text-color-secondary)', fontSize: '1rem' }}>
+              {APP_DESCRIPTION}
+            </p>
+          </div>
+        </Space>
+      </Card>
+
+      <div style={{ position: 'relative' }}>
+        <Card bordered={false} hoverShadow>
+          {(versionStatus.kind === 'mismatched' || versionStatus.kind === 'unavailable') && (
+            <Alert
+              theme='warning'
+              message={versionStatus.description}
+              style={{ marginBottom: 'var(--td-comp-margin-l)' }}
+            />
+          )}
+          <Descriptions
+            column={2}
+            itemLayout='vertical'
+            items={[
+              { label: '前端版本', content: APP_VERSION },
+              { label: '后端版本', content: isLoading ? '加载中' : backendVersion?.version || 'unknown' },
+              { label: '后端提交', content: isLoading ? '加载中' : backendVersion?.commit || 'unknown' },
+              { label: '后端构建时间', content: isLoading ? '加载中' : backendVersion?.buildTime || 'unknown' },
+            ]}
+          />
+        </Card>
+        <Tag
+          theme={statusTheme[versionStatus.kind]}
+          variant='light'
+          shape='round'
+          style={{ position: 'absolute', top: 'var(--td-comp-paddingLR-l)', right: 'var(--td-comp-paddingLR-l)' }}
        >
-          https://github.com/nex/gateway
-        </a>
+          {versionStatus.label}
+        </Tag>
      </div>
-    </Card>
+
+      <Card bordered={false} hoverShadow>
+        <Space breakLine size='large'>
+          <Link href={APP_WEBSITE} target='_blank' theme='primary'>
+            GitHub
+          </Link>
+          <Link href={APP_WEBSITE} target='_blank' theme='primary'>
+            文档
+          </Link>
+          <Link href={`${APP_WEBSITE}/blob/main/LICENSE`} target='_blank' theme='primary'>
+            License
+          </Link>
+        </Space>
+      </Card>
+    </div>
  )
 }
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -62,6 +62,20 @@ export interface StatsQueryParams {
  endDate?: string
 }

+export interface BackendVersion {
+  version: string
+  commit: string
+  buildTime: string
+}
+
+export type VersionStatusKind = 'matched' | 'mismatched' | 'unknown' | 'unavailable'
+
+export interface VersionStatus {
+  kind: VersionStatusKind
+  label: string
+  description: string
+}
+
 export class ApiError extends Error {
  status: number
  code?: string
--- a/frontend/src/utils/version.ts
+++ b/frontend/src/utils/version.ts
@@ -0,0 +1,42 @@
+import type { BackendVersion, VersionStatus } from '@/types'
+
+function isUnknownVersion(version: string | undefined): boolean {
+  const normalized = version?.trim().toLowerCase()
+  return !normalized || normalized === 'dev' || normalized === 'unknown'
+}
+
+export function getVersionStatus(
+  frontendVersion: string,
+  backendVersion?: BackendVersion,
+  hasError = false
+): VersionStatus {
+  if (hasError) {
+    return {
+      kind: 'unavailable',
+      label: '无法获取后端版本',
+      description: '后端版本接口暂时不可用，当前仅展示前端版本。',
+    }
+  }
+
+  if (!backendVersion || isUnknownVersion(frontendVersion) || isUnknownVersion(backendVersion.version)) {
+    return {
+      kind: 'unknown',
+      label: '无法判断版本',
+      description: '当前处于开发构建或版本信息不完整，不判定为版本错误。',
+    }
+  }
+
+  if (frontendVersion === backendVersion.version) {
+    return {
+      kind: 'matched',
+      label: '版本一致',
+      description: '前端和后端来自同一版本构建。',
+    }
+  }
+
+  return {
+    kind: 'mismatched',
+    label: '版本不一致',
+    description: '前后端版本不同，该状态用于部署诊断，不影响当前功能使用。',
+  }
+}
--- a/go.work
+++ b/go.work
@@ -3,4 +3,5 @@ go 1.26.2
 use (
 	backend
 	embedfs
+	versionctl
 )
--- a/go.work.sum
+++ b/go.work.sum
@@ -4,8 +4,6 @@ cloud.google.com/go/auth v0.15.0/go.mod h1:WJDGqZ1o9E9wKIL+IwStfyn/+s59zl4Bi+1KQ
 cloud.google.com/go/auth/oauth2adapt v0.2.7/go.mod h1:NTbTTzfvPl1Y3V1nPpOgl2w6d/FjO7NNUQaWSox6ZMc=
 cloud.google.com/go/compute/metadata v0.6.0/go.mod h1:FjyFAW1MW0C203CEOMDTu3Dk1FlqW3Rga40jzHL4hfg=
 cloud.google.com/go/longrunning v0.5.7/go.mod h1:8GClkudohy1Fxm3owmBGid8W0pSgodEMwEAztp38Xng=
-filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
-filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
 github.com/ClickHouse/ch-go v0.71.0/go.mod h1:NwbNc+7jaqfY58dmdDUbG4Jl22vThgx1cYjBw0vtgXw=
 github.com/ClickHouse/clickhouse-go/v2 v2.43.0/go.mod h1:o6jf7JM/zveWC/PP277BLxjHy5KjnGX/jfljhM4s34g=
 github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
@@ -14,6 +12,7 @@ github.com/antlr4-go/antlr/v4 v4.13.1/go.mod h1:GKmUxMtwp6ZgGwZSva4eWPC5mS6vUAmO
 github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
 github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
 github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/cristalhq/acmd v0.12.0/go.mod h1:LG5oa43pE/BbxtfMoImHCQN++0Su7dzipdgBjMCBVDQ=
 github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
 github.com/docker/go-connections v0.6.0/go.mod h1:AahvXYshr6JgfUJGdDCs2b5EZG/vmaMAntpSFH5BFKE=
@@ -26,8 +25,6 @@ github.com/go-faster/city v1.0.1/go.mod h1:jKcUJId49qdW3L1qKHH/3wPeUstCVpVSXTM6v
 github.com/go-faster/errors v0.7.1/go.mod h1:5ySTjWFiphBs07IKuiL69nxdfd5+fzh1u7FPGZP2quo=
 github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
 github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0=
-github.com/go-sql-driver/mysql v1.9.3 h1:U/N249h2WzJ3Ukj8SowVFjdtZKfu9vlLZxjPXV1aweo=
-github.com/go-sql-driver/mysql v1.9.3/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
 github.com/golang-jwt/jwt/v4 v4.5.2/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0=
 github.com/golang-sql/civil v0.0.0-20220223132316-b832511892a9/go.mod h1:8vg3r2VgvsThLBIFL93Qb5yWzgyZWhEmBwUJWevAkK0=
 github.com/golang-sql/sqlexp v0.1.0/go.mod h1:J4ad9Vo8ZCWQ2GMrC4UCQy1JpCbwU9m3EOqtpKwwwHI=
@@ -48,6 +45,7 @@ github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwA
 github.com/jonboulle/clockwork v0.5.0/go.mod h1:3mZlmanh0g2NDKO5TWZVJAfofYk64M7XN3SzBPjZF60=
 github.com/jordanlewis/gcassert v0.0.0-20250430164644-389ef753e22e/go.mod h1:ZybsQk6DWyN5t7An1MuPm1gtSZ1xDaTXS9ZjIOxvQrk=
 github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
 github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
 github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0/go.mod h1:zJYVVT2jmtg6P3p1VtQj7WsuWi/y4VnjVBn7F8KPB3I=
 github.com/magefile/mage v1.14.0/go.mod h1:z5UZb/iS3GoOSn0JgWuiw7dxlurVYTu+/jHXqQg881A=
@@ -66,8 +64,10 @@ github.com/pelletier/go-toml v1.9.5 h1:4yBQzkHv+7BHq2PQUZF3Mx0IYxG7LsP222s7Agd3v
 github.com/pelletier/go-toml v1.9.5/go.mod h1:u1nR/EPcESfeI/szUZKdtJ0xRNbUoANCkoOuaOx1Y+c=
 github.com/phayes/checkstyle v0.0.0-20170904204023-bfd46e6a821d/go.mod h1:3OzsM7FXDQlpCiw2j81fOmAwQLnZnLGXVKUzeKQXIAw=
 github.com/pierrec/lz4/v4 v4.1.25/go.mod h1:EoQMVJgeeEOMsCqCzqFm2O0cJvljX2nGZjcRIPL34O4=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
 github.com/power-devops/perfstat v0.0.0-20210106213030-5aafc221ea8c/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
 github.com/quasilyte/go-ruleguard/rules v0.0.0-20211022131956-028d6511ab71/go.mod h1:4cgAphtvu7Ftv7vOT2ZOYhC6CvBxZixcasr8qIOTA50=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
 github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
 github.com/shirou/gopsutil/v4 v4.25.2/go.mod h1:34gBYJzyqCDT11b6bMHP0XCvWeU3J61XRT7a2EmCRTA=
 github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME=
--- a/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/.openspec.yaml
+++ b/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-04
--- a/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/design.md
+++ b/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/design.md
@@ -0,0 +1,105 @@
+## Context
+
+Nex 已经具备统一版本源：仓库根目录 `VERSION` 是权威版本，`versionctl sync` 会同步 `frontend/package.json` 和前端 `.env.*` 中的 `VITE_APP_VERSION`，Go 二进制构建通过 `-ldflags` 注入 `backend/pkg/buildinfo`。当前缺口在运行时可见性：前端只能知道自身构建版本，无法从后端获取 server/desktop 二进制版本，也无法判断前后端是否来自同一版本。
+
+前端侧边栏当前在 `AppLayout` 中以 `AI Gateway` 作为品牌文字，折叠后 logo 区域为空，HTML title 也仍为 `AI Gateway`。About 页面只展示名称、描述和链接，缺少版本、构建信息、状态反馈和现代化信息层次。图标资源方面，前端 public 目录维护独立 SVG favicon 和未使用的 `icons.svg`，而桌面托盘和打包资源已经使用仓库 `assets/icon.png`、`assets/icon.ico`、`assets/icon.icns`。desktop 代码中的 `appName/appTooltip` 已经是 `Nex`，但现有 `desktop-app` spec 仍保留旧 tooltip 文案，需要借本次 change 同步。
+
+本变更跨越前端页面、前端 API、后端管理接口、desktop 静态资源服务、README 和 OpenSpec，因此需要先固定实现边界，避免实现阶段出现多个版本来源或重复图标资源。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 统一用户可见应用名称为 `Nex`，覆盖前端侧边栏、HTML title 和相关测试断言，`AI Gateway` 作为产品描述保留。
+- 侧边栏展开态显示统一图标和 `Nex`，折叠态仍显示统一图标。
+- 前端 favicon/public 图标复用仓库 `assets/icon.png`，清理不再使用的 SVG public 图标资源。
+- About 页面展示前端版本、后端版本、后端 commit、后端 build_time 和版本匹配状态。
+- 后端在 server 和 desktop 模式下都提供 `GET /api/version`。
+- 明确并落地前端样式优先级：TDesign 组件 props、TDesign tokens、SCSS。
+- 补充单元测试、组件测试、后端路由测试和必要的 E2E 覆盖。
+- 同步更新根 README、frontend README、backend README。
+
+**Non-Goals:**
+
+- 不改变版本权威来源，仍以根目录 `VERSION` 为唯一版本源。
+- 不新增前端或后端依赖。
+- 不引入用户认证、权限控制或配置项开关。
+- 不让 About 页面阻断业务功能；版本不一致仅提示，不禁止使用。
+- 不重构所有已有内联样式，只处理本次触达的品牌和 About 页面相关样式。
+
+## Decisions
+
+### Decision: 后端版本信息复用 buildinfo 并通过 `/api/version` 暴露
+
+后端 SHALL 新增 `GET /api/version` 管理接口，响应字段为 `version`、`commit`、`build_time`，字段值来自 `buildinfo.Version()`、`buildinfo.Commit()`、`buildinfo.BuildTime()`。
+
+选择 `/api/version` 的原因：管理接口已经统一使用 `/api/*`，前端 API 客户端也以该路径族访问后端；`/health` 应保持存活检查语义，不混入构建元数据。选择 `buildinfo` 的原因：Makefile 已在 server 和 desktop 构建中注入版本、commit 和 buildTime，运行时读取 `VERSION` 会破坏发布产物独立性。
+
+备选方案：扩展 `/health`。放弃原因是健康检查会被监控系统频繁调用，混入构建信息容易模糊职责，并且前端语义上需要的是管理信息而不是存活探针。
+
+### Decision: server 和 desktop 分别注册同一个版本接口
+
+server 和 desktop 当前拥有独立 `setupRoutes`，因此两个入口都 MUST 注册 `GET /api/version`。desktop 还需要确保该路径不会落入 SPA fallback 或协议代理路由。
+
+备选方案：只在 server 注册。放弃原因是桌面应用使用独立路由装配和静态资源服务，用户在 desktop 模式下同样需要 About 页面展示后端版本。
+
+### Decision: 前端版本使用 `VITE_APP_VERSION`，不运行时读取 package.json
+
+前端 SHALL 使用 `import.meta.env.VITE_APP_VERSION` 作为自身版本，缺失时降级为 `dev` 或 `unknown` 显示。该值由版本同步工具写入 `.env.*`，符合现有构建版本注入规则。
+
+备选方案：在前端运行时请求或打包 `package.json`。放弃原因是会产生第二个版本读取路径，并可能在 desktop 嵌入构建、生产构建和测试环境中产生不一致。
+
+### Decision: About 页面只提示版本一致性，不阻断功能
+
+About 页面 SHALL 根据前端版本和后端版本显示状态：一致、不一致、开发构建无法判断、后端版本获取失败。状态通过 TDesign `Tag` 和必要时的 `Alert` 展示。
+
+判断规则：前端版本等于后端版本时为一致；任一版本为 `dev`、`unknown`、空值时为无法判断；请求失败时为后端版本获取失败；其余不相等时为不一致。
+
+备选方案：版本不一致时阻断或弹窗提示。放弃原因是版本检查用于部署诊断，不能影响现有配置和代理能力。
+
+### Decision: 图标资源统一到 `assets/icon.png` 并固定运行时路径
+
+前端 public 图标 SHALL 由仓库 `assets/icon.png` 派生，实施时将根目录 `assets/icon.png` 复制为 `frontend/public/icon.png`，前端入口 SHALL 使用 `/icon.png` 作为 PNG favicon 路径。`frontend/public/favicon.svg` 不再作为 favicon 来源，`frontend/public/icons.svg` 经确认未被引用后 SHALL 删除。
+
+Vite 会将 `frontend/public/icon.png` 输出到 dist 根目录，因此 desktop 静态服务 SHALL 显式服务 `/icon.png` 并读取嵌入 dist 中的 `icon.png`。README SHALL 标注 `frontend/public/icon.png` 来源于根目录 `assets/icon.png`，后续更新应用图标时应以根目录资源为准并同步 public 镜像。
+
+备选方案：继续保留 SVG favicon。放弃原因是会继续存在两套应用图标来源，与用户要求的统一资源方向不一致。
+
+### Decision: 前端样式优先级写入 README 并指导实现
+
+实现视觉效果时，前端 SHALL 优先使用 TDesign 组件 props，例如 `Card` 的 `bordered`、`hoverShadow`、`headerBordered`，`Tag` 的 `theme`、`variant`、`shape`，`Row/Col` 的响应式 props。组件 props 不足时使用 TDesign tokens，例如 `var(--td-text-color-secondary)`、`var(--td-brand-color)`。只有 props 和 tokens 无法表达布局、响应式或品牌细节时才使用 SCSS。
+
+备选方案：直接新增 SCSS Modules 完成全部视觉。放弃原因是项目已经在 OpenSpec 中要求优先使用 TDesign 样式体系，过多 SCSS 会增加覆盖组件内部样式的风险。
+
+### Decision: About 页面采用信息面板布局
+
+About 页面 SHALL 以三个独立 `Card` 垂直排列呈现：顶部品牌卡片展示图标、`Nex`、产品描述；中部版本信息卡片展示前端版本、后端版本、commit、build_time，版本状态 Tag 以绝对定位浮动在卡片右上角；下部链接卡片展示外部链接入口。
+
+布局示意：
+
+```text
+┌─────────────────────────────────────────────┐
+│  Icon  Nex                                   │
+│        AI Gateway - 统一的大模型 API 网关      │
+└─────────────────────────────────────────────┘
+┌─────────────────────────────────────────────┐
+│ 前端版本        后端版本        构建信息 [Tag] │
+│ v0.1.0          v0.1.0          commit/time   │
+└─────────────────────────────────────────────┘
+┌─────────────────────────────────────────────┐
+│ GitHub / 文档 / License                      │
+└─────────────────────────────────────────────┘
+```
+
+### Decision: desktop-app spec 同步现有 Nex tooltip
+
+desktop 代码已经通过 `appName = "Nex"` 和 `appTooltip = appName` 使用统一应用名称，现有 `desktop-app` spec 中 tooltip 仍写 `AI Gateway`。本次 change 已触达 `desktop-app` capability，因此 delta spec SHALL 同步修正托盘 tooltip 要求为 `Nex`，避免归档后主 spec 与当前代码继续漂移。
+
+## Risks / Trade-offs
+
+- `/api/version` 在未通过 Makefile 运行的本地 Go 进程中可能返回 `dev/unknown/unknown` → About 页面将其视为开发构建，显示“无法判断”而不是错误。
+- desktop 与 server 路由重复维护，可能漏注册 → 任务中明确分别添加路由测试，覆盖两个入口。
+- 前端 public PNG 与根 `assets/icon.png` 可能漂移 → README 明确来源；实现阶段复制 `assets/icon.png` 到 `frontend/public/icon.png`，并通过构建验证确认 `/icon.png` 可用。
+- 删除 `frontend/public/icons.svg` 可能影响隐藏引用 → 已通过全文搜索未发现引用；实现阶段删除前再次全文确认，删除后运行前端测试和构建验证。
+- 样式优先级与现有 README “SCSS Modules” 表述可能冲突 → 本变更同步更新 README，以 TDesign props/tokens 优先作为新的明确规则。
+- 版本不一致提示可能被误解为严重故障 → 文案应说明该状态用于部署诊断，不影响当前功能使用。
--- a/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/proposal.md
+++ b/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/proposal.md
@@ -0,0 +1,34 @@
+## Why
+
+当前前端侧边栏仍显示旧的 `AI Gateway` 文案，折叠后品牌区域为空；About 页面信息展示较简陋，无法展示和判断前后端构建版本是否匹配。同时前端 public 图标资源与仓库统一的 `assets/icon.png` 不一致，并存在未使用的 SVG 图标资源，增加了品牌和资源维护成本。
+
+## What Changes
+
+- 将前端侧边栏品牌统一为 `Nex`，展开时显示统一图标和应用名称，折叠时仍显示图标。
+- 将前端 favicon/public 图标统一复用仓库 `assets/icon.png`，运行时统一使用 `/icon.png`；替换当前 `/favicon.svg` 引用并清理未使用的 `frontend/public/icons.svg` 资源。
+- 将前端 HTML 标题等用户可见应用名称同步为 `Nex`，保留 `AI Gateway` 作为产品描述。
+- 重新设计 About 页面信息结构，使用三个独立卡片分别展示品牌、版本信息和外部链接，版本状态 Tag 浮动在版本信息卡片右上角。
+- 新增后端管理接口 `GET /api/version`，暴露构建注入的 `version`、`commit`、`build_time`，供前端判断前后端版本一致性。
+- 在 server 和 desktop 两种启动模式下都注册版本接口，并确保 desktop 静态资源路由支持新的 PNG 图标路径。
+- 明确前端样式优先级：TDesign 组件 props 优先，其次使用 TDesign tokens，最后才在无法通过前两者表达时使用 SCSS，并同步更新 README。
+- 为菜单品牌、About 页面、版本接口、版本匹配状态和资源清理补充测试。
+
+## Capabilities
+
+### New Capabilities
+
+无。
+
+### Modified Capabilities
+
+- `frontend`: 侧边栏品牌标识、折叠态 logo、HTML 标题、前端样式优先级和 public 图标资源使用规则发生变化。
+- `about-page`: About 页面从简单品牌信息扩展为现代化信息面板，并展示前后端版本与匹配状态。
+- `repository-versioning`: 后端需要通过管理接口暴露构建版本信息，前端需要使用构建注入版本与后端版本进行一致性判断。
+- `desktop-app`: desktop 模式需要支持新的 PNG 图标静态资源路径，保证版本接口作为 API 路由处理，并同步现有 `Nex` 托盘 tooltip 规范。
+
+## Impact
+
+- 前端：`frontend/src/components/AppLayout`、`frontend/src/pages/About`、`frontend/src/api`、`frontend/src/hooks`、`frontend/src/types`、`frontend/index.html`、`frontend/public`、前端测试和 E2E 测试。
+- 后端：`backend/internal/handler`、`backend/cmd/server`、`backend/cmd/desktop`、后端测试。
+- 文档与规范：根 `README.md`、`frontend/README.md`、`backend/README.md`、相关 OpenSpec specs。
+- API：新增 `GET /api/version` 管理接口；不引入新依赖。
--- a/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/specs/about-page/spec.md
+++ b/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/specs/about-page/spec.md
@@ -0,0 +1,78 @@
+## MODIFIED Requirements
+
+### Requirement: 关于页面
+
+前端 SHALL 提供现代化关于页面，使用 TDesign 组件展示项目品牌信息、项目链接、前端版本、后端版本和版本匹配状态。
+
+#### Scenario: 显示关于页面
+
+- **WHEN** 用户访问 `/about` 路径
+- **THEN** 前端 SHALL 显示关于页面
+- **THEN** 页面 SHALL 展示应用名称 `Nex`
+- **THEN** 页面 SHALL 展示应用描述 `AI Gateway - 统一的大模型 API 网关`
+- **THEN** 页面 SHALL 展示项目链接 `https://github.com/nex/gateway`
+
+#### Scenario: 页面布局
+
+- **WHEN** 渲染关于页面
+- **THEN** 页面 SHALL 使用三个独立 TDesign Card 组件分别承载品牌区、版本信息区和链接区
+- **THEN** 三个 Card SHALL 使用 grid 布局垂直排列
+- **THEN** 每个 Card SHALL 设置 `bordered={false}` 和 `hoverShadow`
+- **THEN** Card SHALL 使用 TDesign 组件 props 和 tokens 完成主要视觉效果
+
+#### Scenario: 品牌卡片
+
+- **WHEN** 渲染品牌卡片
+- **THEN** 卡片 SHALL 展示应用图标、应用名称 `Nex` 和产品描述
+
+#### Scenario: 版本信息卡片
+
+- **WHEN** 渲染版本信息卡片
+- **THEN** 版本状态 Tag SHALL 以绝对定位浮动在卡片右上角，不占据内容布局空间
+- **THEN** 版本状态 Tag SHALL 使用 TDesign Tag 的 `theme`、`variant`、`shape` props
+- **THEN** 卡片 SHALL 展示前端版本、后端版本、后端提交和后端构建时间
+
+#### Scenario: 链接卡片
+
+- **WHEN** 渲染链接卡片
+- **THEN** 卡片 SHALL 展示项目外部链接
+
+#### Scenario: 展示前端版本
+
+- **WHEN** 渲染关于页面
+- **THEN** 页面 SHALL 显示前端版本号
+- **THEN** 前端版本号 SHALL 来源于构建注入的 `VITE_APP_VERSION`
+- **THEN** 当前端版本号缺失时页面 SHALL 显示开发或未知版本状态
+
+#### Scenario: 展示后端版本
+
+- **WHEN** 渲染关于页面且后端版本接口请求成功
+- **THEN** 页面 SHALL 显示后端 `version`
+- **THEN** 页面 SHALL 显示后端 `commit`
+- **THEN** 页面 SHALL 显示后端 `build_time`
+
+#### Scenario: 判断版本一致
+
+- **WHEN** 前端版本号与后端版本号相同
+- **THEN** 页面 SHALL 显示版本一致状态
+- **THEN** 版本状态 SHALL 使用 TDesign Tag 展示成功语义
+
+#### Scenario: 判断版本不一致
+
+- **WHEN** 前端版本号与后端版本号不同且两者均为可判断的发布版本
+- **THEN** 页面 SHALL 显示版本不一致状态
+- **THEN** 页面 SHALL 展示提示信息说明该状态用于部署诊断
+- **THEN** 页面 SHALL NOT 阻断用户使用其他功能
+
+#### Scenario: 后端版本无法判断
+
+- **WHEN** 后端版本号为 `dev`、`unknown` 或空值
+- **THEN** 页面 SHALL 显示开发构建或无法判断状态
+- **THEN** 页面 SHALL NOT 将该状态显示为版本错误
+
+#### Scenario: 后端版本获取失败
+
+- **WHEN** 请求后端版本接口失败
+- **THEN** 页面 SHALL 显示无法获取后端版本的状态
+- **THEN** 页面 SHALL 保留前端版本信息
+- **THEN** 页面 SHALL NOT 因版本接口失败而崩溃
--- a/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/specs/desktop-app/spec.md
+++ b/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/specs/desktop-app/spec.md
@@ -0,0 +1,91 @@
+## MODIFIED Requirements
+
+### Requirement: 系统托盘
+
+系统 SHALL 提供跨平台系统托盘功能，支持托盘图标和菜单。图标格式 SHALL 根据平台自动选择。
+
+#### Scenario: 托盘图标显示
+
+- **WHEN** 桌面应用启动成功
+- **THEN** 系统根据平台加载正确的图标格式
+- **AND** 在 Windows 上加载 ICO 格式图标（`assets/icon.ico`）
+- **AND** 在 macOS 和 Linux 上加载 PNG 格式图标（`assets/icon.png`）
+- **AND** 托盘图标 tooltip 显示 `Nex`
+
+#### Scenario: 托盘菜单显示
+
+- **WHEN** 用户点击托盘图标（左键或右键）
+- **THEN** 显示托盘菜单
+- **AND** 菜单包含"打开管理界面"选项
+- **AND** 菜单包含"状态: 运行中"选项（禁用状态）
+- **AND** 菜单包含"端口: 9826"选项（禁用状态）
+- **AND** 菜单包含"退出"选项
+
+#### Scenario: 打开管理界面
+
+- **WHEN** 用户点击托盘菜单"打开管理界面"
+- **THEN** 系统在浏览器中打开 `http://localhost:9826`
+
+#### Scenario: 浏览器打开失败
+
+- **WHEN** 系统无法打开浏览器（浏览器未安装等）
+- **THEN** 托盘菜单仍可正常使用
+- **AND** 用户可手动访问 `http://localhost:9826`
+
+#### Scenario: 退出应用
+
+- **WHEN** 用户点击托盘菜单"退出"
+- **THEN** 系统优雅关闭后端服务
+- **AND** 托盘图标消失
+- **AND** 应用进程退出
+
+### Requirement: 静态文件服务
+
+系统 SHALL 通过 Gin 同时服务 API、协议代理和前端静态资源。
+
+#### Scenario: API 请求路由
+
+- **WHEN** 请求路径以 `/api/` 或 `/health` 开头
+- **THEN** 请求由现有业务 handler 处理或返回 API 风格 404
+
+#### Scenario: 版本接口路由
+
+- **WHEN** desktop 模式收到 `GET /api/version` 请求
+- **THEN** 请求 SHALL 由版本信息 handler 处理
+- **THEN** 响应 SHALL 为 API JSON 响应
+- **THEN** 请求 SHALL NOT 返回前端 `index.html`
+
+#### Scenario: 协议代理请求路由
+
+- **WHEN** 请求路径以 `/openai/` 或 `/anthropic/` 开头
+- **THEN** 请求 SHALL 被视为协议代理请求或返回 API 风格 404
+- **THEN** 请求 SHALL NOT 返回前端 `index.html`
+
+#### Scenario: OpenAI 代理路由
+
+- **WHEN** desktop 模式收到 `/openai/v1/chat/completions` 请求
+- **THEN** 请求 SHALL 进入 ProxyHandler
+- **THEN** ProxyHandler SHALL 获取 clientProtocol 为 `openai`
+
+#### Scenario: Anthropic 代理路由
+
+- **WHEN** desktop 模式收到 `/anthropic/v1/messages` 请求
+- **THEN** 请求 SHALL 进入 ProxyHandler
+- **THEN** ProxyHandler SHALL 获取 clientProtocol 为 `anthropic`
+
+#### Scenario: 静态资源路由
+
+- **WHEN** 请求路径为 `/assets/*`
+- **THEN** 返回嵌入的前端静态资源文件
+- **THEN** 请求 SHALL NOT 被协议代理路由处理
+
+#### Scenario: PNG Favicon 路由
+
+- **WHEN** 请求路径为 `/icon.png`
+- **THEN** 返回来源于统一应用图标的 PNG favicon 资源
+- **THEN** 请求 SHALL NOT 被协议代理路由处理
+
+#### Scenario: SPA 路由回退
+
+- **WHEN** 请求路径不匹配任何 API、协议代理或静态资源路由
+- **THEN** 返回 `index.html`（支持前端 SPA 路由）
--- a/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/specs/frontend/spec.md
+++ b/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/specs/frontend/spec.md
@@ -0,0 +1,121 @@
+## MODIFIED Requirements
+
+### Requirement: 样式体系
+
+前端样式 SHALL 优先使用 TDesign 组件 props，其次使用 TDesign tokens，最后在前两者无法表达所需效果时使用 SCSS 作为补充工具。
+
+#### Scenario: TDesign 组件 Props 优先
+
+- **WHEN** 实现组件视觉效果
+- **THEN** 前端 SHALL 优先使用 TDesign 组件的视觉增强 Props（如 color、trend、hoverShadow、stripe、variant、shape、headerBordered、gutter 等）
+- **THEN** 前端 SHALL NOT 通过 CSS 类名覆盖组件内部样式
+
+#### Scenario: TDesign Tokens 作为第二优先级
+
+- **WHEN** 组件 props 无法完整表达颜色、边框、背景、间距等视觉细节
+- **THEN** 前端 SHALL 使用 TDesign CSS Token 引用（`var(--td-*)`）表达样式
+- **THEN** 前端 SHALL NOT 在布局样式中硬编码 `#fff`、`#e7e7e7`、`#999` 等颜色值
+
+#### Scenario: CSS Variables 主题微调
+
+- **WHEN** 需要调整全局视觉风格
+- **THEN** 前端 SHALL 通过 `:root` 中声明 TDesign CSS Variables（`--td-*`）进行覆盖
+- **THEN** 前端 SHALL NOT 使用 `!important` 或高优先级选择器覆盖组件样式
+
+#### Scenario: SCSS 兜底使用
+
+- **WHEN** TDesign 组件 props 和 TDesign tokens 均无法满足布局、响应式或品牌视觉需求
+- **THEN** 前端 MAY 使用 SCSS 作为补充
+- **THEN** SCSS SHALL 只承载必要的补充样式
+- **THEN** 前端 SHALL NOT 使用纯 CSS 文件（*.css）
+
+### Requirement: 提供响应式布局
+
+前端 SHALL 使用 TDesign Layout 提供侧边栏导航布局。
+
+#### Scenario: 桌面布局
+
+- **WHEN** 在桌面屏幕上查看前端
+- **THEN** 布局 SHALL 使用 TDesign `Layout.Aside` + `Menu`
+- **THEN** 侧边栏 SHALL 显示导航菜单，包含图标和文字标签
+- **THEN** 侧边栏 SHALL 使用固定宽度 232px
+- **THEN** Menu 组件 SHALL 使用 `logo` prop 显示品牌标识
+- **THEN** Menu 组件 SHALL 使用 `operations` prop 在底部显示操作区域
+- **THEN** Menu 组件 SHALL 支持 `collapsed` 折叠功能
+
+#### Scenario: 侧边栏折叠布局
+
+- **WHEN** 用户折叠侧边栏
+- **THEN** 侧边栏 SHALL 使用折叠宽度 64px
+- **THEN** Menu logo 区域 SHALL 保留应用图标
+- **THEN** Menu logo 区域 SHALL 隐藏应用名称文字
+- **THEN** Menu logo 区域 SHALL NOT 显示为空白
+
+#### Scenario: 页面内容区域
+
+- **WHEN** 显示页面内容
+- **THEN** 内容区域 SHALL 在 `Layout.Content` 中渲染
+- **THEN** 页面之间 SHALL 通过 React Router Outlet 渲染
+
+#### Scenario: Header 区域
+
+- **WHEN** 渲染页面 Header
+- **THEN** Header SHALL 仅显示当前页面标题
+- **THEN** Header SHALL 不包含导航菜单
+- **THEN** Header 背景色 SHALL 使用 `var(--td-bg-color-container)` Token
+- **THEN** Header 底部分割线 SHALL 使用 `var(--td-component-stroke)` Token
+
+### Requirement: 提供侧边栏导航
+
+前端 SHALL 使用 TDesign `Layout.Aside` 提供侧边栏导航。
+
+#### Scenario: 侧边栏内容
+
+- **WHEN** 渲染侧边栏
+- **THEN** 侧边栏顶部 SHALL 显示统一应用图标和应用名称 `Nex`
+- **THEN** 侧边栏 SHALL NOT 显示旧品牌文字 `AI Gateway` 作为应用名称
+- **THEN** 侧边栏 SHALL 包含导航菜单
+- **THEN** 导航菜单项 SHALL 包含：供应商管理（ServerIcon 图标）、用量统计（ChartLineIcon 图标）、设置（SettingIcon 图标）、关于（InfoCircleIcon 图标）
+
+#### Scenario: 侧边栏折叠品牌显示
+
+- **WHEN** 侧边栏处于折叠状态
+- **THEN** 侧边栏顶部 SHALL 显示统一应用图标
+- **THEN** 侧边栏顶部 SHALL 隐藏 `Nex` 文案
+- **THEN** 侧边栏顶部 SHALL NOT 为空白
+
+#### Scenario: 导航菜单交互
+
+- **WHEN** 用户点击导航中的"供应商管理"
+- **THEN** 前端 SHALL 导航到 `/providers` 并高亮当前菜单项
+- **WHEN** 用户点击导航中的"用量统计"
+- **THEN** 前端 SHALL 导航到 `/stats` 并高亮当前菜单项
+- **WHEN** 用户点击导航中的"设置"
+- **THEN** 前端 SHALL 导航到 `/settings` 并高亮当前菜单项
+- **WHEN** 用户点击导航中的"关于"
+- **THEN** 前端 SHALL 导航到 `/about` 并高亮当前菜单项
+
+## ADDED Requirements
+
+### Requirement: 统一 public 图标资源
+
+前端 SHALL 使用仓库统一应用图标作为 public favicon 和品牌图标来源。
+
+#### Scenario: 使用 PNG favicon
+
+- **WHEN** 前端页面加载 HTML 入口
+- **THEN** 页面 SHALL 使用 `/icon.png` 作为 PNG favicon 路径
+- **THEN** `frontend/public/icon.png` SHALL 来源于仓库根目录 `assets/icon.png`
+- **THEN** 页面 SHALL NOT 引用独立维护的 SVG favicon
+
+#### Scenario: HTML 标题使用统一应用名称
+
+- **WHEN** 前端页面加载 HTML 入口
+- **THEN** 页面标题 SHALL 使用 `Nex` 作为应用名称
+- **THEN** 页面标题 SHALL NOT 使用旧应用名称 `AI Gateway`
+
+#### Scenario: 清理未使用 public SVG 图标
+
+- **WHEN** public 目录中的 SVG 图标资源没有被前端代码、HTML 或 desktop 静态服务引用
+- **THEN** 前端 SHALL 删除该未使用 SVG 图标资源
+- **THEN** 前端 SHALL NOT 保留未使用的 `frontend/public/icons.svg`
--- a/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/specs/repository-versioning/spec.md
+++ b/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/specs/repository-versioning/spec.md
@@ -0,0 +1,54 @@
+## ADDED Requirements
+
+### Requirement: 后端运行时版本查询
+
+系统 SHALL 通过管理接口暴露后端运行时构建版本信息，供前端和用户诊断前后端版本一致性。
+
+#### Scenario: 查询后端版本信息
+
+- **WHEN** 客户端请求 `GET /api/version`
+- **THEN** 后端 SHALL 返回 HTTP 200
+- **THEN** 响应 JSON SHALL 包含 `version` 字段
+- **THEN** 响应 JSON SHALL 包含 `commit` 字段
+- **THEN** 响应 JSON SHALL 包含 `build_time` 字段
+
+#### Scenario: 版本信息来源于构建注入
+
+- **WHEN** 后端返回版本信息
+- **THEN** `version` SHALL 来源于 `buildinfo.Version()`
+- **THEN** `commit` SHALL 来源于 `buildinfo.Commit()`
+- **THEN** `build_time` SHALL 来源于 `buildinfo.BuildTime()`
+- **THEN** 后端 SHALL NOT 在运行时读取仓库 `VERSION` 文件作为接口响应来源
+
+#### Scenario: 本地开发构建降级值
+
+- **WHEN** 后端未通过构建参数注入版本元数据
+- **THEN** 后端版本接口 SHALL 返回 buildinfo 的默认降级值
+- **THEN** 前端 SHALL 能够展示该降级值而不崩溃
+
+### Requirement: 前后端版本一致性诊断
+
+系统 SHALL 支持前端使用自身构建版本和后端运行时版本进行一致性诊断。
+
+#### Scenario: 前端读取构建版本
+
+- **WHEN** 前端渲染版本信息
+- **THEN** 前端 SHALL 使用 `VITE_APP_VERSION` 作为前端版本号
+- **THEN** `VITE_APP_VERSION` SHALL 继续由版本同步流程保持与 `VERSION` 一致
+
+#### Scenario: 诊断版本匹配
+
+- **WHEN** 前端版本号和后端版本号均可判断且完全相同
+- **THEN** 前端 SHALL 将版本状态判定为一致
+
+#### Scenario: 诊断版本不匹配
+
+- **WHEN** 前端版本号和后端版本号均可判断且不相同
+- **THEN** 前端 SHALL 将版本状态判定为不一致
+- **THEN** 前端 SHALL 将该状态作为诊断提示展示
+
+#### Scenario: 诊断版本不可判断
+
+- **WHEN** 任一版本号为空、`dev` 或 `unknown`
+- **THEN** 前端 SHALL 将版本状态判定为无法判断
+- **THEN** 前端 SHALL NOT 将该状态判定为版本不一致
--- a/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/tasks.md
+++ b/openspec/changes/archive/2026-05-05-unify-branding-and-about-version/tasks.md
@@ -0,0 +1,57 @@
+## 1. 后端版本接口
+
+- [x] 1.1 新增后端版本信息 handler，响应 `version`、`commit`、`build_time` 并复用 `buildinfo`
+- [x] 1.2 在 server 入口注册 `GET /api/version`
+- [x] 1.3 在 desktop 入口注册 `GET /api/version`
+- [x] 1.4 为版本 handler 增加单元测试覆盖响应字段和默认降级值
+- [x] 1.5 为 server 路由增加测试覆盖 `GET /api/version`
+- [x] 1.6 为 desktop 路由增加测试覆盖 `GET /api/version` 不落入 SPA fallback
+
+## 2. 前端版本 API 与状态判断
+
+- [x] 2.1 新增前端版本信息类型定义，包含后端 `version`、`commit`、`buildTime`
+- [x] 2.2 新增前端版本 API 调用 `GET /api/version`
+- [x] 2.3 新增 TanStack Query hook 获取后端版本信息
+- [x] 2.4 集中定义前端 `APP_NAME`、产品描述和 `VITE_APP_VERSION` 降级值
+- [x] 2.5 实现前后端版本状态判断逻辑，覆盖一致、不一致、无法判断和请求失败
+- [x] 2.6 为版本 API 和版本状态判断增加前端单元测试
+
+## 3. 品牌与图标资源
+
+- [x] 3.1 将侧边栏品牌名称从 `AI Gateway` 替换为 `Nex`
+- [x] 3.2 使用统一应用图标渲染侧边栏 logo，折叠态保留图标并隐藏文字
+- [x] 3.3 为侧边栏折叠按钮补充清晰的无障碍标签
+- [x] 3.4 将根目录 `assets/icon.png` 复制为 `frontend/public/icon.png`
+- [x] 3.5 将前端 HTML favicon 路径改为 `/icon.png` 并将 HTML title 改为 `Nex`
+- [x] 3.6 将 desktop 静态文件服务的 `/favicon.svg` 路由替换为 `/icon.png` 路由
+- [x] 3.7 删除未使用的 `frontend/public/icons.svg` 和旧 SVG favicon 资源
+- [x] 3.8 全文确认不存在未处理的 `icons.svg`、`favicon.svg` 引用
+- [x] 3.9 更新 AppLayout 组件测试覆盖展开态 `Nex`、折叠态图标和 About 菜单项
+- [x] 3.10 更新导航 E2E 中旧 `AI Gateway` 品牌断言为 `Nex`
+
+## 4. About 页面改造
+
+- [x] 4.1 重构 About 页面为品牌卡片、版本信息卡片和链接卡片三卡布局
+- [x] 4.2 使用 TDesign Card、Tag、Descriptions、Alert、Row/Col 等组件 props 完成主要视觉结构
+- [x] 4.3 在 About 页面展示前端版本、后端版本、commit 和 build_time
+- [x] 4.4 在 About 页面展示版本一致、不一致、无法判断和请求失败状态
+- [x] 4.5 确保版本不一致或接口失败时 About 页面不崩溃且不阻断其他功能
+- [x] 4.6 为 About 页面增加组件测试覆盖布局、版本展示和所有版本状态
+- [x] 4.7 为 About 页面补充必要的 E2E 导航与版本区域可见性测试
+
+## 5. 文档同步
+
+- [x] 5.1 更新根 README 的管理接口列表，加入 `GET /api/version`
+- [x] 5.2 更新根 README 的前端样式技术栈说明，体现 TDesign props、TDesign tokens、SCSS 优先级
+- [x] 5.3 更新 backend README 的管理接口文档，说明版本响应字段来源
+- [x] 5.4 更新 frontend README 的环境变量说明，加入 `VITE_APP_VERSION`
+- [x] 5.5 更新 frontend README 的样式优先级为 TDesign props、TDesign tokens、SCSS
+- [x] 5.6 更新 frontend README 的项目结构、About 页面说明和 public 图标来源说明
+- [x] 5.7 更新 desktop 相关文档说明 PNG favicon、`/icon.png` 静态路由和 API 版本接口路由
+
+## 6. 验证
+
+- [x] 6.1 运行后端测试，确保 handler、server 和 desktop 路由测试通过
+- [x] 6.2 运行前端测试，确保 API、hook、AppLayout 和 About 页面测试通过
+- [x] 6.3 运行前端检查和构建，确保 Bun/Vite 构建能加载 PNG favicon
+- [x] 6.4 运行 OpenSpec 校验，确保 proposal、design、specs 和 tasks 状态可实施
--- a/openspec/config.yaml
+++ b/openspec/config.yaml
@@ -8,7 +8,7 @@ context: |
  - 新增代码优先复用已有组件、工具、依赖库，不引入新依赖
  - 新增的逻辑必须编写完善的测试，并保证测试的正确性，不允许跳过任何测试
  - backend是使用go开发的后端，阅读backend/README.md了解项目架构，优先使用公共组件实现功能逻辑（优先级：官方库>主流三方库>项目公共工具>自行实现）
-  - frontend是基于bun+vite+typescript开发的前端，使用bun作为唯一包管理器，严禁使用pnpm、npm
+  - frontend是基于bun+vite+typescript开发的前端，使用bun作为唯一包管理器，严禁使用pnpm、npm，使用bunx运行工具，严禁使用npx、pnpx
  - Git提交: 仅中文; 格式"类型: 简短描述", 类型: feat/fix/refactor/docs/style/test/chore; 多行描述空行后写详细说明
  - 禁止创建git操作task
  - 积极使用subagents精心设计并行任务，节省上下文空间，加速任务执行
--- a/openspec/specs/about-page/spec.md
+++ b/openspec/specs/about-page/spec.md
@@ -2,25 +2,83 @@

 ## Purpose

-TBD - 提供关于页面展示项目品牌信息
+TBD - 提供关于页面展示项目品牌信息、版本信息和外部链接

 ## Requirements

 ### Requirement: 关于页面

-前端 SHALL 提供关于页面，使用 TDesign Card 组件居中展示项目品牌信息（应用名称、描述、项目链接）。
+前端 SHALL 提供现代化关于页面，使用 TDesign 组件展示项目品牌信息、项目链接、前端版本、后端版本和版本匹配状态。

 #### Scenario: 显示关于页面

 - **WHEN** 用户访问 `/about` 路径
 - **THEN** 前端 SHALL 显示关于页面
- **THEN** 页面 SHALL 展示应用名称"Nex"
- **THEN** 页面 SHALL 展示应用描述"AI Gateway - 统一的大模型 API 网关"
- **THEN** 页面 SHALL 展示项目链接"https://github.com/nex/gateway"
+- **THEN** 页面 SHALL 展示应用名称 `Nex`
+- **THEN** 页面 SHALL 展示应用描述 `AI Gateway - 统一的大模型 API 网关`
+- **THEN** 页面 SHALL 展示项目链接 `https://github.com/nex/gateway`

 #### Scenario: 页面布局

 - **WHEN** 渲染关于页面
- **THEN** 页面 SHALL 使用 TDesign Card 组件作为容器
- **THEN** Card SHALL 设置 `bordered={false}`
- **THEN** 内容 SHALL 居中展示
+- **THEN** 页面 SHALL 使用三个独立 TDesign Card 组件分别承载品牌区、版本信息区和链接区
+- **THEN** 三个 Card SHALL 使用 grid 布局垂直排列
+- **THEN** 每个 Card SHALL 设置 `bordered={false}` 和 `hoverShadow`
+- **THEN** Card SHALL 使用 TDesign 组件 props 和 tokens 完成主要视觉效果
+
+#### Scenario: 品牌卡片
+
+- **WHEN** 渲染品牌卡片
+- **THEN** 卡片 SHALL 展示应用图标、应用名称 `Nex` 和产品描述
+
+#### Scenario: 版本信息卡片
+
+- **WHEN** 渲染版本信息卡片
+- **THEN** 版本状态 Tag SHALL 以绝对定位浮动在卡片右上角，不占据内容布局空间
+- **THEN** 版本状态 Tag SHALL 使用 TDesign Tag 的 `theme`、`variant`、`shape` props
+- **THEN** 卡片 SHALL 展示前端版本、后端版本、后端提交和后端构建时间
+
+#### Scenario: 链接卡片
+
+- **WHEN** 渲染链接卡片
+- **THEN** 卡片 SHALL 展示项目外部链接
+
+#### Scenario: 展示前端版本
+
+- **WHEN** 渲染关于页面
+- **THEN** 页面 SHALL 显示前端版本号
+- **THEN** 前端版本号 SHALL 来源于构建注入的 `VITE_APP_VERSION`
+- **THEN** 当前端版本号缺失时页面 SHALL 显示开发或未知版本状态
+
+#### Scenario: 展示后端版本
+
+- **WHEN** 渲染关于页面且后端版本接口请求成功
+- **THEN** 页面 SHALL 显示后端 `version`
+- **THEN** 页面 SHALL 显示后端 `commit`
+- **THEN** 页面 SHALL 显示后端 `build_time`
+
+#### Scenario: 判断版本一致
+
+- **WHEN** 前端版本号与后端版本号相同
+- **THEN** 页面 SHALL 显示版本一致状态
+- **THEN** 版本状态 SHALL 使用 TDesign Tag 展示成功语义
+
+#### Scenario: 判断版本不一致
+
+- **WHEN** 前端版本号与后端版本号不同且两者均为可判断的发布版本
+- **THEN** 页面 SHALL 显示版本不一致状态
+- **THEN** 页面 SHALL 展示提示信息说明该状态用于部署诊断
+- **THEN** 页面 SHALL NOT 阻断用户使用其他功能
+
+#### Scenario: 后端版本无法判断
+
+- **WHEN** 后端版本号为 `dev`、`unknown` 或空值
+- **THEN** 页面 SHALL 显示开发构建或无法判断状态
+- **THEN** 页面 SHALL NOT 将该状态显示为版本错误
+
+#### Scenario: 后端版本获取失败
+
+- **WHEN** 请求后端版本接口失败
+- **THEN** 页面 SHALL 显示无法获取后端版本的状态
+- **THEN** 页面 SHALL 保留前端版本信息
+- **THEN** 页面 SHALL NOT 因版本接口失败而崩溃
--- a/openspec/specs/database-migration/spec.md
+++ b/openspec/specs/database-migration/spec.md
@@ -67,11 +67,11 @@

 ### Requirement: 迁移命令集成

-迁移 SHALL 集成到 Makefile。
+迁移 SHALL 集成到 `backend/Makefile`，而不是根目录 `Makefile`。

 #### Scenario: 迁移 up 命令

- **WHEN** 执行 `make backend-migrate-up`
+- **WHEN** 在 `backend/` 目录执行 `make migrate-up`
 - **THEN** SHALL 执行所有待执行的迁移
 - **THEN** SHALL 使用 `DB_DRIVER` 变量选择方言目录（默认 `sqlite3`）
 - **THEN** SHALL 使用 `DB_DSN` 变量作为数据库连接串
@@ -79,20 +79,20 @@

 #### Scenario: 迁移 down 命令

- **WHEN** 执行 `make backend-migrate-down`
+- **WHEN** 在 `backend/` 目录执行 `make migrate-down`
 - **THEN** SHALL 回滚最后一个迁移
 - **THEN** SHALL 使用 `DB_DRIVER` 和 `DB_DSN` 变量
 - **THEN** SHALL 显示回滚进度

 #### Scenario: 迁移状态命令

- **WHEN** 执行 `make backend-migrate-status`
+- **WHEN** 在 `backend/` 目录执行 `make migrate-status`
 - **THEN** SHALL 显示当前迁移状态
 - **THEN** SHALL 显示已执行和待执行的迁移

 #### Scenario: 创建迁移命令

- **WHEN** 执行 `make backend-migrate-create`
+- **WHEN** 在 `backend/` 目录执行 `make migrate-create`
 - **THEN** SHALL 同时在 `migrations/sqlite/` 和 `migrations/mysql/` 两个目录创建新的迁移文件模板
 - **THEN** SHALL 使用递增的版本号

--- a/openspec/specs/desktop-app/spec.md
+++ b/openspec/specs/desktop-app/spec.md
@@ -42,7 +42,7 @@ TBD - 提供跨平台桌面应用支持，将后端服务与前端静态资源
 - **THEN** 系统根据平台加载正确的图标格式
 - **AND** 在 Windows 上加载 ICO 格式图标（`assets/icon.ico`）
 - **AND** 在 macOS 和 Linux 上加载 PNG 格式图标（`assets/icon.png`）
- **AND** 托盘图标 tooltip 显示"AI Gateway"
+- **AND** 托盘图标 tooltip 显示 `Nex`

 #### Scenario: 托盘菜单显示

@@ -80,6 +80,13 @@ TBD - 提供跨平台桌面应用支持，将后端服务与前端静态资源
 - **WHEN** 请求路径以 `/api/` 或 `/health` 开头
 - **THEN** 请求由现有业务 handler 处理或返回 API 风格 404

+#### Scenario: 版本接口路由
+
+- **WHEN** desktop 模式收到 `GET /api/version` 请求
+- **THEN** 请求 SHALL 由版本信息 handler 处理
+- **THEN** 响应 SHALL 为 API JSON 响应
+- **THEN** 请求 SHALL NOT 返回前端 `index.html`
+
 #### Scenario: 协议代理请求路由

 - **WHEN** 请求路径以 `/openai/` 或 `/anthropic/` 开头
@@ -104,10 +111,10 @@ TBD - 提供跨平台桌面应用支持，将后端服务与前端静态资源
 - **THEN** 返回嵌入的前端静态资源文件
 - **THEN** 请求 SHALL NOT 被协议代理路由处理

-#### Scenario: Favicon 路由
+#### Scenario: PNG Favicon 路由

- **WHEN** 请求路径为 `/favicon.svg`
- **THEN** 返回嵌入的前端 favicon 资源
+- **WHEN** 请求路径为 `/icon.png`
+- **THEN** 返回来源于统一应用图标的 PNG favicon 资源
 - **THEN** 请求 SHALL NOT 被协议代理路由处理

 #### Scenario: SPA 路由回退
@@ -132,38 +139,50 @@ TBD - 提供跨平台桌面应用支持，将后端服务与前端静态资源

 ### Requirement: 跨平台构建

-系统 SHALL 支持跨平台构建和打包。构建 target SHALL 按平台分离，产物文件名 SHALL 使用 `nex-{os}-{arch}[.exe]` 格式。
+系统 SHALL 支持跨平台构建和打包。构建 target SHALL 按平台分离，中间构建产物文件名 SHALL 保持 `nex-{os}-{arch}[.exe]` 格式，最终桌面发布资产文件名 SHALL 包含统一版本号和平台标识。

 #### Scenario: macOS 构建

- **WHEN** 执行 `desktop-build-mac` 构建命令
+- **WHEN** 执行 `desktop-build-mac` 构建命令且当前版本为 `1.2.3`
 - **THEN** 生成 `nex-mac-arm64` 和 `nex-mac-amd64` 可执行文件
- **AND** 可打包为 `.app` bundle
+- **AND** 系统生成可打包为 `.app` bundle 的 macOS 桌面产物
+- **AND** 最终发布资产文件名 SHALL 包含 `1.2.3` 和 `macOS` 平台标识

 #### Scenario: Windows 构建

- **WHEN** 执行 `desktop-build-win` 构建命令
- **THEN** 生成 `nex-win-amd64.exe` 可执行文件
+- **WHEN** 执行 `desktop-build-win` 构建命令且当前版本为 `1.2.3`
+- **THEN** 系统生成 Windows 桌面可执行文件
+- **AND** 生成 `nex-win-amd64.exe` 可执行文件
 - **AND** 使用 `-H=windowsgui` linker flag 隐藏控制台窗口
+- **AND** 最终发布资产文件名 SHALL 包含 `1.2.3` 和 `windows` 平台标识

 #### Scenario: Linux 构建

- **WHEN** 执行 `desktop-build-linux` 构建命令
- **THEN** 生成 `nex-linux-amd64` 可执行文件
+- **WHEN** 执行 `desktop-build-linux` 构建命令且当前版本为 `1.2.3`
+- **THEN** 系统生成 Linux 桌面可执行文件
+- **AND** 生成 `nex-linux-amd64` 可执行文件
+- **AND** 最终发布资产文件名 SHALL 包含 `1.2.3` 和 `linux` 平台标识

 ### Requirement: macOS .app 打包

-系统 SHALL 支持打包为 macOS .app bundle。
+系统 SHALL 支持打包为 macOS `.app` bundle，并使 bundle 元数据中的版本字段来源于统一版本号而非硬编码值。

 #### Scenario: .app 结构

- **WHEN** 执行打包脚本
+- **WHEN** 执行 macOS 桌面打包脚本
 - **THEN** 生成 `Nex.app` 目录结构
 - **AND** 包含 `Contents/Info.plist` 元数据
 - **AND** 包含 `Contents/MacOS/nex` 可执行文件
 - **AND** 包含 `Contents/Resources/icon.icns` 图标
 - **AND** `Info.plist` 中 `LSUIElement` 为 `true`（不显示 Dock 图标）

+#### Scenario: bundle 版本元数据同步
+
+- **WHEN** 当前统一版本号为 `1.2.3`
+- **THEN** `Info.plist` 中 `CFBundleShortVersionString` SHALL 为 `1.2.3`
+- **AND** `Info.plist` 中 `CFBundleVersion` SHALL 为 `1.2.3`
+- **AND** 打包流程 SHALL NOT 使用硬编码版本值
+
 ### Requirement: Windows 原生对话框

 系统 SHALL 在 Windows 上使用 `user32.dll` 的 `MessageBoxW` API 显示错误对话框，替代 `msg *` 命令。
--- a/openspec/specs/frontend/spec.md
+++ b/openspec/specs/frontend/spec.md
@@ -8,31 +8,31 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面

 ### Requirement: 样式体系

-前端样式 SHALL 优先使用 TDesign 样式体系，SCSS 作为补充工具。
+前端样式 SHALL 优先使用 TDesign 组件 props，其次使用 TDesign tokens，最后在前两者无法表达所需效果时使用 SCSS 作为补充工具。

 #### Scenario: TDesign 组件 Props 优先

 - **WHEN** 实现组件视觉效果
- **THEN** 前端 SHALL 优先使用 TDesign 组件的视觉增强 Props（如 color、trend、hoverShadow、stripe、variant、shape 等）
+- **THEN** 前端 SHALL 优先使用 TDesign 组件的视觉增强 Props（如 color、trend、hoverShadow、stripe、variant、shape、headerBordered、gutter 等）
 - **THEN** 前端 SHALL NOT 通过 CSS 类名覆盖组件内部样式

+#### Scenario: TDesign Tokens 作为第二优先级
+
+- **WHEN** 组件 props 无法完整表达颜色、边框、背景、间距等视觉细节
+- **THEN** 前端 SHALL 使用 TDesign CSS Token 引用（`var(--td-*)`）表达样式
+- **THEN** 前端 SHALL NOT 在布局样式中硬编码 `#fff`、`#e7e7e7`、`#999` 等颜色值
+
 #### Scenario: CSS Variables 主题微调

 - **WHEN** 需要调整全局视觉风格
- **THEN** 前端 SHALL 通过 \`:root\` 中声明 TDesign CSS Variables（\`--td-*\`）进行覆盖
- **THEN** 前端 SHALL NOT 使用 \`!important\` 或高优先级选择器覆盖组件样式
+- **THEN** 前端 SHALL 通过 `:root` 中声明 TDesign CSS Variables（`--td-*`）进行覆盖
+- **THEN** 前端 SHALL NOT 使用 `!important` 或高优先级选择器覆盖组件样式

-#### Scenario: 布局样式 Token 化
+#### Scenario: SCSS 兜底使用

- **WHEN** 编写布局级 inline style
- **THEN** 前端 SHALL 使用 TDesign CSS Token 引用（\`var(--td-*)\`）替代硬编码颜色值
- **THEN** 前端 SHALL NOT 在布局样式中硬编码 \`#fff\`、\`#e7e7e7\`、\`#999\` 等颜色值
-
-#### Scenario: SCSS 补充使用
-
- **WHEN** TDesign 样式体系无法满足需求
+- **WHEN** TDesign 组件 props 和 TDesign tokens 均无法满足布局、响应式或品牌视觉需求
 - **THEN** 前端 MAY 使用 SCSS 作为补充
- **THEN** SCSS 文件 SHALL 仅用于 \`:root\` 级别的 CSS Variables 声明和全局 reset
+- **THEN** SCSS SHALL 只承载必要的补充样式
 - **THEN** 前端 SHALL NOT 使用纯 CSS 文件（*.css）


@@ -231,12 +231,20 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
 #### Scenario: 桌面布局

 - **WHEN** 在桌面屏幕上查看前端
- **THEN** 布局 SHALL 使用 TDesign \`Layout.Aside\` + \`Menu\`
+- **THEN** 布局 SHALL 使用 TDesign `Layout.Aside` + `Menu`
 - **THEN** 侧边栏 SHALL 显示导航菜单，包含图标和文字标签
 - **THEN** 侧边栏 SHALL 使用固定宽度 232px
- **THEN** Menu 组件 SHALL 使用 \`logo\` prop 显示品牌标识
- **THEN** Menu 组件 SHALL 使用 \`operations\` prop 在底部显示操作区域
- **THEN** Menu 组件 SHALL 支持 \`collapsed\` 折叠功能
+- **THEN** Menu 组件 SHALL 使用 `logo` prop 显示品牌标识
+- **THEN** Menu 组件 SHALL 使用 `operations` prop 在底部显示操作区域
+- **THEN** Menu 组件 SHALL 支持 `collapsed` 折叠功能
+
+#### Scenario: 侧边栏折叠布局
+
+- **WHEN** 用户折叠侧边栏
+- **THEN** 侧边栏 SHALL 使用折叠宽度 64px
+- **THEN** Menu logo 区域 SHALL 保留应用图标
+- **THEN** Menu logo 区域 SHALL 隐藏应用名称文字
+- **THEN** Menu logo 区域 SHALL NOT 显示为空白

 #### Scenario: 页面内容区域

@@ -402,21 +410,29 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面

 ### Requirement: 提供侧边栏导航

-前端 SHALL 使用 TDesign \`Layout.Aside\` 提供侧边栏导航。
+前端 SHALL 使用 TDesign `Layout.Aside` 提供侧边栏导航。

 #### Scenario: 侧边栏内容

 - **WHEN** 渲染侧边栏
- **THEN** 侧边栏顶部 SHALL 显示应用名称/Logo
+- **THEN** 侧边栏顶部 SHALL 显示统一应用图标和应用名称 `Nex`
+- **THEN** 侧边栏 SHALL NOT 显示旧品牌文字 `AI Gateway` 作为应用名称
 - **THEN** 侧边栏 SHALL 包含导航菜单
 - **THEN** 导航菜单项 SHALL 包含：供应商管理（ServerIcon 图标）、用量统计（ChartLineIcon 图标）、设置（SettingIcon 图标）、关于（InfoCircleIcon 图标）

+#### Scenario: 侧边栏折叠品牌显示
+
+- **WHEN** 侧边栏处于折叠状态
+- **THEN** 侧边栏顶部 SHALL 显示统一应用图标
+- **THEN** 侧边栏顶部 SHALL 隐藏 `Nex` 文案
+- **THEN** 侧边栏顶部 SHALL NOT 为空白
+
 #### Scenario: 导航菜单交互

 - **WHEN** 用户点击导航中的"供应商管理"
- **THEN** 前端 SHALL 导航到 \`/providers\` 并高亮当前菜单项
+- **THEN** 前端 SHALL 导航到 `/providers` 并高亮当前菜单项
 - **WHEN** 用户点击导航中的"用量统计"
- **THEN** 前端 SHALL 导航到 \`/stats\` 并高亮当前菜单项
+- **THEN** 前端 SHALL 导航到 `/stats` 并高亮当前菜单项
 - **WHEN** 用户点击导航中的"设置"
 - **THEN** 前端 SHALL 导航到 `/settings` 并高亮当前菜单项
 - **WHEN** 用户点击导航中的"关于"
@@ -583,3 +599,26 @@ TBD - 提供供应商、模型配置和用量统计的前端管理界面
 - **THEN** 前端 SHALL 显示全局错误提示
 - **THEN** 错误消息 SHALL 具有描述性

+### Requirement: 统一 public 图标资源
+
+前端 SHALL 使用仓库统一应用图标作为 public favicon 和品牌图标来源。
+
+#### Scenario: 使用 PNG favicon
+
+- **WHEN** 前端页面加载 HTML 入口
+- **THEN** 页面 SHALL 使用 `/icon.png` 作为 PNG favicon 路径
+- **THEN** `frontend/public/icon.png` SHALL 来源于仓库根目录 `assets/icon.png`
+- **THEN** 页面 SHALL NOT 引用独立维护的 SVG favicon
+
+#### Scenario: HTML 标题使用统一应用名称
+
+- **WHEN** 前端页面加载 HTML 入口
+- **THEN** 页面标题 SHALL 使用 `Nex` 作为应用名称
+- **THEN** 页面标题 SHALL NOT 使用旧应用名称 `AI Gateway`
+
+#### Scenario: 清理未使用 public SVG 图标
+
+- **WHEN** public 目录中的 SVG 图标资源没有被前端代码、HTML 或 desktop 静态服务引用
+- **THEN** 前端 SHALL 删除该未使用 SVG 图标资源
+- **THEN** 前端 SHALL NOT 保留未使用的 `frontend/public/icons.svg`
+
--- a/openspec/specs/middleware-system/spec.md
+++ b/openspec/specs/middleware-system/spec.md
@@ -29,13 +29,13 @@
 #### Scenario: 记录请求开始

 - **WHEN** 收到 HTTP 请求
- **THEN** SHALL 记录请求开始日志
+- **THEN** SHALL 以 debug 级别记录请求开始日志
 - **THEN** SHALL 包含请求方法、路径、客户端 IP、请求 ID

 #### Scenario: 记录请求结束

 - **WHEN** HTTP 请求处理完成
- **THEN** SHALL 记录请求结束日志
+- **THEN** SHALL 以 debug 级别记录请求结束日志
 - **THEN** SHALL 包含响应状态码、响应大小、请求耗时、请求 ID

 #### Scenario: 记录错误
@@ -44,6 +44,12 @@
 - **THEN** SHALL 记录错误日志
 - **THEN** SHALL 包含错误详情和请求 ID

+#### Scenario: Info 级别过滤请求生命周期日志
+
+- **WHEN** 日志中间件使用 info 级别 logger
+- **THEN** SHALL NOT 输出“请求开始”日志
+- **THEN** SHALL NOT 输出“请求结束”日志
+
 ### Requirement: 实现错误恢复中间件

 系统 SHALL 实现错误恢复中间件。
--- a/openspec/specs/mysql-testing/spec.md
+++ b/openspec/specs/mysql-testing/spec.md
@@ -8,16 +8,16 @@

 ### Requirement: MySQL 测试环境可启动

-系统 SHALL 提供 Docker Compose 配置以启动 MySQL 8.0 测试环境。
+系统 SHALL 提供 Docker Compose 配置和 backend 局部 make 命令以启动 MySQL 8.0 测试环境。

 #### Scenario: 启动 MySQL 测试容器
- **WHEN** 执行 `make test-mysql-up`
+- **WHEN** 在 `backend/` 目录执行 `make mysql-up`
 - **THEN** 启动 MySQL 8.0 容器，端口 13306
 - **AND** 创建数据库 `nex_test`
 - **AND** 容器数据存储在内存盘（tmpfs）

 #### Scenario: 销毁 MySQL 测试容器
- **WHEN** 执行 `make test-mysql-down`
+- **WHEN** 在 `backend/` 目录执行 `make mysql-down`
 - **THEN** 停止并删除容器
 - **AND** 所有数据被销毁

@@ -90,15 +90,15 @@ MySQL 测试 SHALL 验证并发写入不丢失数据。

 ### Requirement: MySQL 测试命令完整

-Makefile SHALL 提供完整的 MySQL 测试命令。
+`backend/Makefile` SHALL 提供完整的 MySQL 测试命令。

 #### Scenario: 完整测试流程
- **WHEN** 执行 `make test-mysql`
+- **WHEN** 在 `backend/` 目录执行 `make mysql-test`
 - **THEN** 启动 Docker MySQL
 - **AND** 等待 MySQL 就绪
 - **AND** 运行所有 MySQL 测试
 - **AND** 销毁容器

 #### Scenario: 快速测试（容器已运行）
- **WHEN** 执行 `make test-mysql-quick`
+- **WHEN** 在 `backend/` 目录执行 `make mysql-test-quick`
 - **THEN** 直接运行测试，不管理容器生命周期
--- a/openspec/specs/release-pipeline/spec.md
+++ b/openspec/specs/release-pipeline/spec.md
@@ -0,0 +1,164 @@
+# 发布流水线
+
+## Purpose
+
+定义 tag 驱动的发布流程、跨平台构建产物要求与 Draft Release 组装规则，确保发布结果可复现且可审阅。
+
+## Requirements
+
+### Requirement: Tag 驱动发布流水线
+
+系统 SHALL 仅在符合 `vX.Y.Z` 格式的 Git tag 上触发发布流水线，普通分支 push SHALL NOT 创建发布。发布流水线 SHALL 使用 `./versionctl` 而非 `./backend/cmd/versionctl` 调用版本管理工具。
+
+#### Scenario: 有效发布 tag
+
+- **WHEN** 仓库收到 `v1.2.3` tag push
+- **THEN** 发布流水线 SHALL 启动版本校验、构建和 Release 组装步骤
+- **AND** 版本校验步骤 SHALL 使用 `go run ./versionctl print` 和 `go run ./versionctl verify-tag` 获取并验证版本
+
+#### Scenario: 普通分支推送
+
+- **WHEN** 仓库收到非 tag 的分支 push
+- **THEN** 系统 SHALL NOT 创建 GitHub Release
+
+### Requirement: 发布流水线 Go 模块缓存覆盖
+
+发布流水线 SHALL 在所有 Go module 的 go.sum 文件存在时正确设置 Go 模块缓存路径，确保新增的 `versionctl` module 依赖也被缓存。
+
+#### Scenario: CI 缓存覆盖所有 module
+
+- **WHEN** 发布流水线设置 Go 模块缓存
+- **THEN** `cache-dependency-path` SHALL 覆盖 `backend/go.sum` 和 `versionctl/go.sum`
+
+### Requirement: 三平台发布构建
+
+系统 SHALL 在发布流水线中构建 server 与 desktop 的 Linux、Windows、macOS 三个平台产物。
+
+#### Scenario: Linux 发布构建
+
+- **WHEN** 发布流水线执行 Linux 构建 job
+- **THEN** 系统 SHALL 在可访问 Go、Bun 和 Linux 桌面构建依赖的 shell 环境中执行 Linux 发布构建
+- **AND** 系统 SHALL 生成 Linux server 发布资产
+- **AND** 系统 SHALL 生成 Linux desktop 发布资产
+
+#### Scenario: Windows 发布构建
+
+- **WHEN** 发布流水线执行 Windows 构建 job
+- **THEN** 系统 SHALL 在包含 MSYS2 / MINGW64 构建工具且可访问 Go 与 Bun 工具链的 shell 环境中执行 Windows 发布构建
+- **AND** 系统 SHALL 生成 Windows server 发布资产
+- **AND** 系统 SHALL 生成 Windows desktop 发布资产
+
+#### Scenario: macOS 发布构建
+
+- **WHEN** 发布流水线执行 macOS 构建 job
+- **THEN** 系统 SHALL 在可访问 Go、Bun 和 macOS 打包工具链的 shell 环境中执行 macOS 发布构建
+- **AND** 系统 SHALL 生成 darwin-amd64 server 发布资产
+- **AND** 系统 SHALL 生成 darwin-arm64 server 发布资产
+- **AND** 系统 SHALL 生成 macOS desktop universal 发布资产
+
+### Requirement: 三平台发布构建预检
+
+系统 SHALL 在正式执行各平台 `make release-assets-*` 前验证对应发布 job 的关键工具链可用性，并在环境不完整时快速失败且输出明确诊断。
+
+#### Scenario: Linux 预检通过后开始构建
+
+- **WHEN** Linux 发布 job 中的 `go`、`bun` 与 Linux 桌面构建依赖均可用
+- **THEN** 系统 SHALL 输出关键工具的版本信息或解析路径
+- **AND** 系统 SHALL 继续执行 `make release-assets-linux`
+
+#### Scenario: Windows 预检通过后开始构建
+
+- **WHEN** Windows 发布 job 中的 `go`、`bun` 与 MSYS2 构建工具均可用
+- **THEN** 系统 SHALL 输出关键工具的版本信息或解析路径
+- **AND** 系统 SHALL 继续执行 `make release-assets-windows`
+
+#### Scenario: macOS 预检通过后开始构建
+
+- **WHEN** macOS 发布 job 中的 `go`、`bun` 与 macOS 打包工具均可用
+- **THEN** 系统 SHALL 输出关键工具的版本信息或解析路径
+- **AND** 系统 SHALL 继续执行 `make release-assets-macos`
+
+#### Scenario: 任一平台预检发现工具缺失
+
+- **WHEN** 任一平台发布 job 中存在关键工具不可用
+- **THEN** 发布流水线 SHALL 在正式构建前失败
+- **AND** 系统 SHALL 在日志中标识缺失的工具链名称
+
+### Requirement: 发布流水线 LFS 资产拉取
+
+发布流水线 SHALL 在所有会 checkout 仓库并参与版本校验或平台构建的 job 中拉取 Git LFS 真实文件，确保发布构建读取到真实二进制资产而非 LFS pointer 文本。
+
+#### Scenario: 发布 job 获取真实 LFS 图标资产
+
+- **WHEN** 发布流水线执行 `prepare`、`build-linux`、`build-windows` 或 `build-macos` job 的 checkout 步骤
+- **THEN** checkout 步骤 SHALL 拉取 Git LFS 文件
+- **AND** `assets/icon.ico`、`assets/icon.icns`、`assets/icon.png` 和 `frontend/public/icon.png` SHALL 在后续步骤中表现为真实图标文件而非 LFS pointer 文本
+
+### Requirement: 发布资产图标预检
+
+发布流水线 SHALL 在正式执行各平台发布构建前校验关键图标资产可用，并在检测到 LFS pointer 或错误格式时快速失败且输出明确诊断。
+
+#### Scenario: 图标资产为 LFS pointer
+
+- **WHEN** 发布资产预检发现关键图标文件内容为 Git LFS pointer 文本
+- **THEN** 发布流水线 SHALL 在执行平台发布构建前失败
+- **AND** 系统 SHALL 在日志中标识对应图标文件需要拉取 Git LFS 真实内容
+
+#### Scenario: 图标资产格式无效
+
+- **WHEN** 发布资产预检发现关键图标文件不是对应格式的有效资源
+- **THEN** 发布流水线 SHALL 在执行平台发布构建前失败
+- **AND** 系统 SHALL 在日志中标识格式无效的图标文件路径
+
+#### Scenario: 图标资产预检通过
+
+- **WHEN** `assets/icon.ico`、`assets/icon.icns`、`assets/icon.png` 和 `frontend/public/icon.png` 均为真实且格式可用的图标资产
+- **THEN** 发布流水线 SHALL 继续执行对应平台的 `make release-assets-*` 构建
+
+### Requirement: 发布流水线运行时兼容性
+
+系统 SHALL 保持与 GitHub-hosted runner 当前受支持的 workflow runtime 约束兼容，避免发布流程依赖已声明弃用的 runtime 或执行约束。
+
+#### Scenario: runner runtime 升级前完成兼容更新
+
+- **WHEN** GitHub-hosted runner 宣布 workflow runtime 或关键执行约束将从旧版本迁移到新版本
+- **THEN** 发布流水线 SHALL 在旧约束移除前完成兼容性更新
+
+#### Scenario: 发布流水线执行时不依赖已弃用 runtime
+
+- **WHEN** 发布流水线运行 release workflow
+- **THEN** 关键发布步骤 SHALL NOT 依赖已被 GitHub-hosted runner 标记为待移除的 runtime 或执行约束
+
+### Requirement: 版本化发布资产命名
+
+系统 SHALL 为 server 与 desktop 的发布资产使用包含统一版本号和目标平台信息的文件名，确保 Release 页面可直接区分产物用途与平台。
+
+#### Scenario: server 资产命名
+
+- **WHEN** 当前发布版本为 `1.2.3`
+- **THEN** Linux server 发布资产文件名 SHALL 包含 `1.2.3`、`linux` 和 `amd64`
+- **AND** Windows server 发布资产文件名 SHALL 包含 `1.2.3`、`windows` 和 `amd64`
+- **AND** macOS server 发布资产文件名 SHALL 分别包含 `1.2.3`、`darwin`、`amd64` 与 `1.2.3`、`darwin`、`arm64`
+
+#### Scenario: desktop 资产命名
+
+- **WHEN** 当前发布版本为 `1.2.3`
+- **THEN** Linux desktop 发布资产文件名 SHALL 包含 `1.2.3` 和 `linux`
+- **AND** Windows desktop 发布资产文件名 SHALL 包含 `1.2.3` 和 `windows`
+- **AND** macOS desktop universal 发布资产文件名 SHALL 包含 `1.2.3` 和 `macOS`
+
+### Requirement: Draft Release 组装
+
+系统 SHALL 将发布流水线产物上传到 GitHub Draft Release，由人工确认后再公开发布。
+
+#### Scenario: 发布成功时创建 Draft Release
+
+- **WHEN** 版本校验通过且三平台发布资产构建完成
+- **THEN** 系统 SHALL 创建或更新与该 tag 对应的 GitHub Draft Release
+- **AND** 系统 SHALL 上传 server 与 desktop 的全部发布资产
+
+#### Scenario: 构建失败时阻止完成发布
+
+- **WHEN** 任一平台发布资产构建失败或版本校验失败
+- **THEN** 发布流水线 SHALL 失败
+- **AND** 系统 SHALL NOT 产生可直接公开的成功发布结果
--- a/openspec/specs/repository-versioning/spec.md
+++ b/openspec/specs/repository-versioning/spec.md
@@ -0,0 +1,121 @@
+# 仓库版本管理
+
+## Purpose
+
+定义仓库统一版本源、镜像同步、发布一致性校验与构建版本注入规则，确保所有构建消费者使用同一版本语义。
+
+## Requirements
+
+### Requirement: 统一版本源
+
+系统 SHALL 使用仓库根目录 `VERSION` 文件作为全仓唯一版本源，文件内容 SHALL 仅包含一行 `x.y.z` 格式的语义版本号。
+
+#### Scenario: 读取有效版本号
+
+- **WHEN** 仓库中的 `VERSION` 文件内容为 `1.2.3`
+- **THEN** 本地工具和 CI SHALL 将 `1.2.3` 视为当前仓库版本
+- **AND** 其他版本消费者 SHALL NOT 覆盖该值作为权威来源
+
+#### Scenario: 拒绝非法版本格式
+
+- **WHEN** `VERSION` 文件内容不是 `x.y.z` 格式
+- **THEN** 版本同步与发布校验流程 SHALL 失败
+- **AND** 系统 SHALL 输出格式错误信息
+
+### Requirement: 版本镜像同步
+
+系统 SHALL 提供仓库内的版本同步入口，将 `VERSION` 中的版本值写入需要镜像版本号的构建消费者。
+
+#### Scenario: 同步前端镜像字段
+
+- **WHEN** 执行版本同步流程且 `VERSION` 为 `1.2.3`
+- **THEN** `frontend/package.json` 中的 `version` 字段 SHALL 被同步为 `1.2.3`
+
+#### Scenario: 同步构建模板值
+
+- **WHEN** 执行版本同步流程且存在依赖版本号的构建模板或元数据模板
+- **THEN** 这些模板消费的版本值 SHALL 与 `VERSION` 保持一致
+- **AND** 系统 SHALL NOT 要求用户手工修改多个版本文件
+
+### Requirement: 发布版本一致性校验
+
+系统 SHALL 在发布前校验仓库版本与 Git tag 一致，确保发布锚点与仓库状态不漂移。
+
+#### Scenario: tag 与 VERSION 一致
+
+- **WHEN** 发布使用的 Git tag 为 `v1.2.3` 且 `VERSION` 为 `1.2.3`
+- **THEN** 发布校验 SHALL 通过
+
+#### Scenario: tag 与 VERSION 不一致
+
+- **WHEN** 发布使用的 Git tag 为 `v1.2.4` 但 `VERSION` 为 `1.2.3`
+- **THEN** 发布校验 SHALL 失败
+- **AND** 系统 SHALL 阻止后续发布步骤继续执行
+
+### Requirement: 统一构建版本注入
+
+系统 SHALL 在构建阶段把统一版本信息注入 frontend、server 和 desktop，而不是在运行时依赖外部发布平台查询版本。
+
+#### Scenario: Go 二进制注入版本元数据
+
+- **WHEN** 构建 server 或 desktop 二进制
+- **THEN** 构建流程 SHALL 注入 `version`、`commit` 和 `buildTime` 元数据
+
+#### Scenario: 前端注入构建版本
+
+- **WHEN** 执行前端生产构建
+- **THEN** 构建流程 SHALL 注入 `VITE_APP_VERSION`
+- **AND** 该值 SHALL 等于 `VERSION` 中的版本号
+
+### Requirement: 后端运行时版本查询
+
+系统 SHALL 通过管理接口暴露后端运行时构建版本信息，供前端和用户诊断前后端版本一致性。
+
+#### Scenario: 查询后端版本信息
+
+- **WHEN** 客户端请求 `GET /api/version`
+- **THEN** 后端 SHALL 返回 HTTP 200
+- **THEN** 响应 JSON SHALL 包含 `version` 字段
+- **THEN** 响应 JSON SHALL 包含 `commit` 字段
+- **THEN** 响应 JSON SHALL 包含 `build_time` 字段
+
+#### Scenario: 版本信息来源于构建注入
+
+- **WHEN** 后端返回版本信息
+- **THEN** `version` SHALL 来源于 `buildinfo.Version()`
+- **THEN** `commit` SHALL 来源于 `buildinfo.Commit()`
+- **THEN** `build_time` SHALL 来源于 `buildinfo.BuildTime()`
+- **THEN** 后端 SHALL NOT 在运行时读取仓库 `VERSION` 文件作为接口响应来源
+
+#### Scenario: 本地开发构建降级值
+
+- **WHEN** 后端未通过构建参数注入版本元数据
+- **THEN** 后端版本接口 SHALL 返回 buildinfo 的默认降级值
+- **THEN** 前端 SHALL 能够展示该降级值而不崩溃
+
+### Requirement: 前后端版本一致性诊断
+
+系统 SHALL 支持前端使用自身构建版本和后端运行时版本进行一致性诊断。
+
+#### Scenario: 前端读取构建版本
+
+- **WHEN** 前端渲染版本信息
+- **THEN** 前端 SHALL 使用 `VITE_APP_VERSION` 作为前端版本号
+- **THEN** `VITE_APP_VERSION` SHALL 继续由版本同步流程保持与 `VERSION` 一致
+
+#### Scenario: 诊断版本匹配
+
+- **WHEN** 前端版本号和后端版本号均可判断且完全相同
+- **THEN** 前端 SHALL 将版本状态判定为一致
+
+#### Scenario: 诊断版本不匹配
+
+- **WHEN** 前端版本号和后端版本号均可判断且不相同
+- **THEN** 前端 SHALL 将版本状态判定为不一致
+- **THEN** 前端 SHALL 将该状态作为诊断提示展示
+
+#### Scenario: 诊断版本不可判断
+
+- **WHEN** 任一版本号为空、`dev` 或 `unknown`
+- **THEN** 前端 SHALL 将版本状态判定为无法判断
+- **THEN** 前端 SHALL NOT 将该状态判定为版本不一致
--- a/openspec/specs/structured-logging/spec.md
+++ b/openspec/specs/structured-logging/spec.md
@@ -82,21 +82,29 @@

 ### Requirement: 记录请求日志

-系统 SHALL 记录 HTTP 请求日志。
+系统 SHALL 记录 HTTP 请求日志，其中请求开始和请求结束生命周期日志 SHALL 使用 debug 级别记录。

 #### Scenario: 请求开始日志

 - **WHEN** 收到 HTTP 请求
+- **THEN** SHALL 以 debug 级别记录请求开始日志
 - **THEN** SHALL 记录请求方法、路径、客户端 IP
 - **THEN** SHALL 包含请求 ID

 #### Scenario: 请求结束日志

 - **WHEN** HTTP 请求处理完成
+- **THEN** SHALL 以 debug 级别记录请求结束日志
 - **THEN** SHALL 记录响应状态码、响应大小
 - **THEN** SHALL 记录请求耗时
 - **THEN** SHALL 包含请求 ID

+#### Scenario: Info 级别过滤请求生命周期日志
+
+- **WHEN** 日志级别配置为 info
+- **THEN** SHALL NOT 输出“请求开始”日志
+- **THEN** SHALL NOT 输出“请求结束”日志
+
 ### Requirement: 支持日志级别

 系统 SHALL 支持日志级别控制。
--- a/openspec/specs/test-coverage/spec.md
+++ b/openspec/specs/test-coverage/spec.md
@@ -157,26 +157,33 @@

 ### Requirement: 集成到构建流程

-测试 SHALL 集成到构建流程中。
+测试 SHALL 同时集成到根目录公共流程和 backend 局部流程中。

 #### Scenario: 运行测试命令

 - **WHEN** 执行 `make test` 命令
- **THEN** SHALL 运行所有单元测试和集成测试
+- **THEN** SHALL 运行 backend 核心测试、frontend 的 Vitest 单元/组件测试和 desktop 专属测试
+- **THEN** SHALL NOT 运行 MySQL 专项测试和 frontend E2E 测试
 - **THEN** SHALL 显示测试结果
 - **THEN** SHALL 在测试失败时返回非零退出码

+#### Scenario: 运行 backend 局部测试命令
+
+- **WHEN** 在 `backend/` 目录执行 `make test` 命令
+- **THEN** SHALL 运行 backend 核心测试
+- **THEN** SHALL NOT 运行 frontend 的 Vitest 单元/组件测试、desktop 专属测试、MySQL 专项测试或 frontend E2E 测试
+
 #### Scenario: 分类测试命令

- **WHEN** 执行 `make test-unit` 命令
+- **WHEN** 在 `backend/` 目录执行 `make test-unit` 命令
 - **THEN** SHALL 仅运行 `./internal/...` 和 `./pkg/...` 下的单元测试

- **WHEN** 执行 `make test-integration` 命令
+- **WHEN** 在 `backend/` 目录执行 `make test-integration` 命令
 - **THEN** SHALL 仅运行 `./tests/...` 下的集成测试

 #### Scenario: 覆盖率检查命令

- **WHEN** 执行 `make test-coverage` 命令
+- **WHEN** 在 `backend/` 目录执行 `make test-coverage` 命令
 - **THEN** SHALL 运行测试并生成覆盖率报告
 - **THEN** SHALL 检查覆盖率是否达标
 - **THEN** SHALL 在覆盖率不足时返回非零退出码
--- a/openspec/specs/version-bump/spec.md
+++ b/openspec/specs/version-bump/spec.md
@@ -0,0 +1,123 @@
+# 版本升迁
+
+## Purpose
+
+定义 `version bump` 子命令的版本号递增、下游文件同步、倒退防护及 Makefile 编排规则，确保版本升迁流程安全可自动化。
+
+## Requirements
+
+### Requirement: 版本号递增
+
+`version bump` 子命令 SHALL 支持三种递增模式：`major`（major+1, minor=0, patch=0）、`minor`（minor+1, patch=0）、`patch`（patch+1），以及直接指定具体版本号。
+
+#### Scenario: minor 递增
+
+- **WHEN** 当前 VERSION 为 `0.1.0`，执行 `version bump minor`
+- **THEN** VERSION 文件 SHALL 被更新为 `0.2.0`
+
+#### Scenario: major 递增
+
+- **WHEN** 当前 VERSION 为 `0.1.0`，执行 `version bump major`
+- **THEN** VERSION 文件 SHALL 被更新为 `1.0.0`
+
+#### Scenario: patch 递增
+
+- **WHEN** 当前 VERSION 为 `0.1.0`，执行 `version bump patch`
+- **THEN** VERSION 文件 SHALL 被更新为 `0.1.1`
+
+#### Scenario: 指定具体版本号
+
+- **WHEN** 当前 VERSION 为 `0.1.0`，执行 `version bump 1.0.0`
+- **THEN** VERSION 文件 SHALL 被更新为 `1.0.0`
+
+#### Scenario: 指定版本号等于当前 VERSION
+
+- **WHEN** 当前 VERSION 为 `0.1.0`，执行 `version bump 0.1.0`
+- **THEN** 命令 SHALL 正常执行，完成 sync 和 check，输出 `0.1.0`
+
+#### Scenario: 非法 bump 参数
+
+- **WHEN** 执行 `version bump` 传入既非 `major|minor|patch` 也非合法 semver 的参数
+- **THEN** 命令 SHALL 以非零退出码失败并输出错误信息
+
+### Requirement: bump 自动同步下游文件
+
+`version bump` 子命令 SHALL 在写回 VERSION 文件后自动执行 sync 和 check，确保 `frontend/package.json` 和所有 `frontend/.env.*` 文件与新版本号一致。
+
+#### Scenario: bump 自动 sync 和 check
+
+- **WHEN** 执行 `version bump minor` 且当前 VERSION 为 `0.1.0`
+- **THEN** 命令 SHALL 自动将新版本号 `0.2.0` 同步到 `frontend/package.json` 的 `version` 字段和所有 `frontend/.env.*` 的 `VITE_APP_VERSION` 变量
+- **AND** 命令 SHALL 自动验证所有下游文件版本号一致性
+
+#### Scenario: sync 失败时 bump 中止
+
+- **WHEN** 执行 `version bump minor` 但下游文件同步失败（如文件缺失）
+- **THEN** 命令 SHALL 以非零退出码失败
+
+### Requirement: 版本号倒退防护
+
+`version bump` 子命令 SHALL 检查新版本号严格大于所有已有 git tag 中的最大版本号，防止版本号倒退。
+
+#### Scenario: 新版本大于已有 tag
+
+- **WHEN** 已有 tag `v0.1.0`，执行 `version bump minor`
+- **THEN** 命令 SHALL 成功将版本更新为 `0.2.0`
+
+#### Scenario: 新版本等于已有 tag
+
+- **WHEN** 已有 tag `v0.1.0`，执行 `version bump 0.1.0`
+- **THEN** 命令 SHALL 以非零退出码失败并提示版本号已存在
+
+#### Scenario: 新版本小于已有 tag
+
+- **WHEN** 已有 tag `v0.2.0`，执行 `version bump 0.1.5`
+- **THEN** 命令 SHALL 以非零退出码失败并提示版本号倒退
+
+#### Scenario: 无已有 tag
+
+- **WHEN** 不存在任何 `v*.*.*` 格式的 git tag，执行 `version bump 0.1.0`
+- **THEN** 命令 SHALL 成功
+
+### Requirement: bump 输出新版本号
+
+`version bump` 子命令成功时 SHALL 仅将新版本号（不含 `v` 前缀）输出到 stdout，供 Makefile 等外部工具使用。
+
+#### Scenario: 输出格式
+
+- **WHEN** 执行 `version bump minor`，当前版本为 `0.1.0`
+- **THEN** stdout SHALL 输出 `0.2.0`（换行结尾，无额外内容）
+
+### Requirement: 版本升迁 Makefile 编排
+
+`make version-bump` SHALL 编排完整的版本升迁流程：工作区干净检查 → `version bump`（含 sync/check/倒退检查）→ git add → git commit → git tag。不传 `BUMP` 参数时 SHALL 默认执行 `BUMP=patch`。
+
+#### Scenario: 完整升迁流程
+
+- **WHEN** 执行 `make version-bump BUMP=minor`，工作区干净，当前版本 `0.1.0`
+- **THEN** Makefile SHALL 依次执行：工作区检查 → `version bump minor` → `git add VERSION frontend/` → `git commit -m "chore: 版本升迁 v0.2.0"` → `git tag v0.2.0`
+
+#### Scenario: 不传 BUMP 默认 patch
+
+- **WHEN** 执行 `make version-bump`，工作区干净，当前版本 `0.1.0`
+- **THEN** Makefile SHALL 等效于执行 `make version-bump BUMP=patch`，将版本更新为 `0.1.1`
+
+#### Scenario: 工作区不干净
+
+- **WHEN** 执行 `make version-bump BUMP=minor`，但工作区有未提交的改动
+- **THEN** Makefile SHALL 以非零退出码失败并提示先提交或暂存改动
+
+#### Scenario: 支持指定版本号
+
+- **WHEN** 执行 `make version-bump SET_VERSION=1.0.0`
+- **THEN** Makefile SHALL 将 `1.0.0` 传递给 `version bump` 子命令
+
+#### Scenario: SET_VERSION 优先于默认 BUMP
+
+- **WHEN** 执行 `make version-bump SET_VERSION=2.0.0`
+- **THEN** Makefile SHALL 使用 `SET_VERSION=2.0.0` 而非默认的 `BUMP=patch`
+
+#### Scenario: 不自动推送
+
+- **WHEN** `make version-bump` 成功完成
+- **THEN** commit 和 tag SHALL 仅存在于本地，SHALL NOT 自动 push 到远程
--- a/openspec/specs/workspace-command-flows/spec.md
+++ b/openspec/specs/workspace-command-flows/spec.md
@@ -0,0 +1,114 @@
+# Workspace Command Flows
+
+## Purpose
+
+定义根目录 `Makefile` 与 `backend/Makefile` 的公开命令边界，明确全仓命令、产品级命令和 backend 局部维护命令的职责分层。
+
+## Requirements
+
+### Requirement: 根目录公开命令分层
+
+根目录 `Makefile` SHALL 仅暴露全局命令、版本命令、server 产品命令、desktop 产品命令和 release 命令，不再作为 backend 局部维护命令或内部打包步骤的公开入口。
+
+#### Scenario: 查看根目录公开命令
+- **WHEN** 开发者查看根目录 `Makefile` 的公开 target
+- **THEN** SHALL 仅看到 `lint`、`test`、`clean`、`version-sync`、`version-check`、`server-run`、`server-build`、`server-lint`、`server-test`、`server-clean`、`desktop-build-mac`、`desktop-build-win`、`desktop-build-linux`、`desktop-lint`、`desktop-test`、`desktop-clean`、`release-assets-linux`、`release-assets-windows`、`release-assets-macos` 这类公共入口
+
+#### Scenario: 根目录不暴露局部和内部命令
+- **WHEN** 开发者查看根目录 `Makefile` 的公开 target
+- **THEN** SHALL NOT 暴露 `backend-*`、`frontend-*`、数据库迁移命令、MySQL 专项测试命令或 `desktop-prepare-*` 之类内部步骤
+- **THEN** SHALL NOT 暴露 `dev`、`build`、`all`、`desktop-dev`、`desktop-build` 这类模糊或聚合式公共命令
+
+### Requirement: 全局质量与清理命令
+
+根目录 `Makefile` SHALL 提供 `lint`、`test`、`clean` 作为全仓默认入口。
+
+#### Scenario: 执行全局 lint
+- **WHEN** 执行 `make lint`
+- **THEN** SHALL 运行 backend 的 Go lint 检查和 frontend 的 lint / format check
+- **THEN** SHALL 在任一检查失败时返回非零退出码
+
+#### Scenario: 执行全局 test
+- **WHEN** 执行 `make test`
+- **THEN** SHALL 运行 backend 核心测试、frontend 的 Vitest 单元/组件测试和 desktop 专属测试
+- **THEN** SHALL NOT 运行 MySQL 专项测试和 frontend E2E 测试
+- **THEN** SHALL 在任一测试失败时返回非零退出码
+
+#### Scenario: 执行全局 clean
+- **WHEN** 执行 `make clean`
+- **THEN** SHALL 清理 server 与 desktop 相关的构建产物、发布产物和测试报告
+- **THEN** SHALL NOT 删除 `frontend/node_modules`、Go module cache 或 bun cache 之类依赖目录和全局缓存
+
+### Requirement: Server 产品命令
+
+根目录 `Makefile` SHALL 提供面向前后端分离 server 模式的产品级命令。
+
+#### Scenario: 启动 server 模式联调环境
+- **WHEN** 执行 `make server-run`
+- **THEN** SHALL 并行启动 Go 后端服务和前端 Vite 开发服务器
+- **THEN** SHALL 使前端继续通过现有代理访问本地 backend 服务
+
+#### Scenario: 构建 server 模式产物
+- **WHEN** 执行 `make server-build`
+- **THEN** SHALL 生成 `backend/bin/server`
+- **AND** SHALL 生成 `frontend/dist`
+- **AND** SHALL 在构建前校验版本一致性
+- **AND** SHALL NOT 隐式执行 `version-sync` 或修改版本镜像文件
+
+#### Scenario: 执行 server lint
+- **WHEN** 执行 `make server-lint`
+- **THEN** SHALL 运行 backend 的 Go lint 检查和 frontend 的 lint / format check
+
+#### Scenario: 执行 server test
+- **WHEN** 执行 `make server-test`
+- **THEN** SHALL 运行 backend 核心测试和 frontend 的 Vitest 单元/组件测试
+- **THEN** SHALL NOT 运行 MySQL 专项测试、frontend E2E 测试或 desktop 专属测试
+
+#### Scenario: 执行 server clean
+- **WHEN** 执行 `make server-clean`
+- **THEN** SHALL 清理 `backend/bin/server`、`frontend/dist` 以及 server 模式相关测试报告与临时产物
+
+### Requirement: Desktop 产品命令
+
+根目录 `Makefile` SHALL 提供按平台拆分的 desktop 构建命令，以及 desktop 产品级 `lint`、`test`、`clean` 命令。
+
+#### Scenario: 执行按平台拆分的 desktop 构建
+- **WHEN** 执行 `make desktop-build-mac`、`make desktop-build-win` 或 `make desktop-build-linux`
+- **THEN** SHALL 分别构建对应平台的 desktop 产物
+- **THEN** SHALL 在构建前执行版本一致性校验
+- **THEN** SHALL NOT 隐式执行 `version-sync` 或修改版本镜像文件
+- **THEN** SHALL NOT 要求通过额外的 `desktop-build` 聚合命令触发构建
+
+#### Scenario: 根目录不提供 desktop 开发聚合入口
+- **WHEN** 开发者查看根目录 `Makefile`
+- **THEN** SHALL NOT 提供 `desktop-dev` 作为公共命令
+
+#### Scenario: 执行 desktop lint
+- **WHEN** 执行 `make desktop-lint`
+- **THEN** SHALL 运行 backend 的 Go lint 检查和 frontend 的 lint / format check
+
+#### Scenario: 执行 desktop test
+- **WHEN** 执行 `make desktop-test`
+- **THEN** SHALL 运行 desktop 专属测试
+
+#### Scenario: 执行 desktop clean
+- **WHEN** 执行 `make desktop-clean`
+- **THEN** SHALL 清理 desktop 构建目录、嵌入资源目录和 desktop 相关测试/打包产物
+
+### Requirement: Release 命令沿用根目录入口
+
+根目录 `Makefile` SHALL 继续提供 `release-assets-*` 作为发布资产入口，并与新的版本校验规则保持一致。
+
+#### Scenario: 执行 release 资产命令
+- **WHEN** 执行 `make release-assets-linux`、`make release-assets-windows` 或 `make release-assets-macos`
+- **THEN** SHALL 在构建发布资产前执行版本一致性校验
+- **THEN** SHALL NOT 隐式执行 `version-sync` 或修改版本镜像文件
+
+### Requirement: Backend 局部命令下沉
+
+数据库迁移、MySQL 专项测试以及其他 backend 局部维护命令 SHALL 由 `backend/Makefile` 提供，而不是由根目录 `Makefile` 公开。
+
+#### Scenario: 执行 backend 局部维护命令
+- **WHEN** 开发者需要执行数据库迁移或 MySQL 专项测试
+- **THEN** SHALL 在 `backend/` 目录使用 backend 局部 make 命令完成操作
+- **THEN** 根目录 `Makefile` SHALL NOT 提供等价的公共命令别名
--- a/versionctl/.golangci.yml
+++ b/versionctl/.golangci.yml
@@ -0,0 +1,52 @@
+run:
+  timeout: 5m
+  tests: true
+
+linters:
+  disable-all: true
+  enable:
+    - errorlint
+    - errcheck
+    - staticcheck
+    - revive
+    - gocritic
+    - gosec
+    - nilerr
+    - goimports
+    - gocyclo
+
+linters-settings:
+  errcheck:
+    check-blank: true
+    check-type-assertions: true
+  revive:
+    rules:
+      - name: exported
+      - name: var-naming
+      - name: indent-error-flow
+      - name: error-strings
+      - name: error-return
+      - name: blank-imports
+  goimports:
+    local-prefixes: nex/versionctl
+  gocyclo:
+    min-complexity: 10
+
+issues:
+  exclude-generated: true
+  exclude-rules:
+    - path: '_test\.go'
+      linters:
+        - errcheck
+      source: '(^\s*_\s*=|,\s*_)'
+    - path: '_test\.go'
+      linters:
+        - revive
+      text: '^exported:'
+    - path: '_test\.go'
+      linters:
+        - gosec
+      text: 'G(101|401|501)'
+    - path: 'main\.go'
+      linters:
+        - gocyclo
--- a/versionctl/Makefile
+++ b/versionctl/Makefile
@@ -0,0 +1,16 @@
+.PHONY: \
+	lint test test-coverage clean
+
+lint:
+	go tool golangci-lint run ./...
+
+test:
+	go test ./... -v
+
+test-coverage:
+	go test ./... -coverprofile=coverage.out
+	go tool cover -html=coverage.out -o coverage.html
+	@printf 'Coverage report generated: versionctl/coverage.html\n'
+
+clean:
+	rm -rf coverage.out coverage.html
--- a/versionctl/go.mod
+++ b/versionctl/go.mod
@@ -0,0 +1,14 @@
+module nex/versionctl
+
+go 1.26.2
+
+require github.com/stretchr/testify v1.11.1
+
+require (
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/kr/pretty v0.3.1 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/rogpeppe/go-internal v1.14.1 // indirect
+	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
--- a/versionctl/go.sum
+++ b/versionctl/go.sum
@@ -0,0 +1,8 @@
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
--- a/versionctl/main.go
+++ b/versionctl/main.go
@@ -0,0 +1,156 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"nex/versionctl/projectversion"
+)
+
+func main() {
+	if err := run(os.Args[1:]); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func run(args []string) error {
+	if len(args) == 0 {
+		return usageError()
+	}
+
+	root, err := projectversion.FindRepoRoot(mustGetwd())
+	if err != nil {
+		return err
+	}
+
+	switch args[0] {
+	case "print":
+		version, readErr := projectversion.ReadString(root)
+		if readErr != nil {
+			return readErr
+		}
+		fmt.Println(version)
+		return nil
+	case "sync":
+		return projectversion.Sync(root)
+	case "check":
+		return projectversion.Check(root)
+	case "verify-tag":
+		if len(args) != 2 {
+			return fmt.Errorf("verify-tag 需要一个 tag 参数")
+		}
+		return projectversion.VerifyTag(root, args[1])
+	case "bump":
+		if len(args) != 2 {
+			return fmt.Errorf("bump 需要一个参数: major|minor|patch 或具体版本号")
+		}
+		return runBump(root, args[1])
+	case "macos-plist":
+		if len(args) != 2 {
+			return fmt.Errorf("macos-plist 需要一个最低系统版本参数")
+		}
+		return printMacOSPlist(root, args[1])
+	case "asset-name":
+		return printAssetName(root, args[1:])
+	case "release-assets-check":
+		if len(args) != 1 {
+			return fmt.Errorf("release-assets-check 不需要额外参数")
+		}
+		return projectversion.CheckReleaseAssets(root)
+	default:
+		return usageError()
+	}
+}
+
+func runBump(root, arg string) error {
+	newVersion, err := projectversion.Bump(root, arg)
+	if err != nil {
+		return err
+	}
+
+	tags, err := projectversion.ListGitTags(root)
+	if err != nil {
+		return err
+	}
+
+	if err := projectversion.CheckNoRegression(newVersion, tags); err != nil {
+		return err
+	}
+
+	if err := projectversion.Sync(root); err != nil {
+		return err
+	}
+
+	if err := projectversion.Check(root); err != nil {
+		return err
+	}
+
+	fmt.Println(newVersion.String())
+	return nil
+}
+
+func printMacOSPlist(root, minMacOSVersion string) error {
+	version, err := projectversion.ReadString(root)
+	if err != nil {
+		return err
+	}
+
+	plist, err := projectversion.DesktopInfoPlist(version, minMacOSVersion)
+	if err != nil {
+		return err
+	}
+
+	fmt.Print(plist)
+	return nil
+}
+
+func printAssetName(root string, args []string) error {
+	if len(args) < 2 {
+		return fmt.Errorf("asset-name 至少需要 kind 和 platform 参数")
+	}
+
+	version, err := projectversion.ReadString(root)
+	if err != nil {
+		return err
+	}
+
+	switch args[0] {
+	case "server":
+		if len(args) != 3 {
+			return fmt.Errorf("server 资产命名需要 platform 和 arch 参数")
+		}
+		name, nameErr := projectversion.ServerAssetName(version, args[1], args[2])
+		if nameErr != nil {
+			return nameErr
+		}
+		fmt.Println(name)
+		return nil
+	case "desktop":
+		if len(args) != 2 {
+			return fmt.Errorf("desktop 资产命名只需要 platform 参数")
+		}
+		name, nameErr := projectversion.DesktopAssetName(version, args[1])
+		if nameErr != nil {
+			return nameErr
+		}
+		fmt.Println(name)
+		return nil
+	default:
+		return fmt.Errorf("不支持的资产类型 %q", args[0])
+	}
+}
+
+func mustGetwd() string {
+	wd, err := os.Getwd()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+
+	return wd
+}
+
+func usageError() error {
+	return fmt.Errorf("用法: version <print|sync|check|verify-tag|bump|macos-plist|asset-name|release-assets-check>")
+}
--- a/versionctl/projectversion/release_assets.go
+++ b/versionctl/projectversion/release_assets.go
@@ -0,0 +1,69 @@
+package projectversion
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+var releaseAssetChecks = []releaseAssetCheck{
+	{
+		path:        "assets/icon.ico",
+		description: "Windows ICO 图标",
+		magic:       []byte{0x00, 0x00, 0x01, 0x00},
+	},
+	{
+		path:        "assets/icon.icns",
+		description: "macOS ICNS 图标",
+		magic:       []byte("icns"),
+	},
+	{
+		path:        "assets/icon.png",
+		description: "PNG 图标",
+		magic:       []byte{0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a},
+	},
+	{
+		path:        "frontend/public/icon.png",
+		description: "前端 PNG 图标",
+		magic:       []byte{0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a},
+	},
+}
+
+var gitLFSPointerPrefix = []byte("version https://git-lfs.github.com/spec/v1")
+
+type releaseAssetCheck struct {
+	path        string
+	description string
+	magic       []byte
+}
+
+func CheckReleaseAssets(root string) error {
+	var errs []error
+
+	for _, check := range releaseAssetChecks {
+		if err := checkReleaseAsset(root, check); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	return errors.Join(errs...)
+}
+
+func checkReleaseAsset(root string, check releaseAssetCheck) error {
+	content, err := os.ReadFile(filepath.Join(root, check.path))
+	if err != nil {
+		return fmt.Errorf("%s 不可读取: %w", check.path, err)
+	}
+
+	if bytes.HasPrefix(content, gitLFSPointerPrefix) {
+		return fmt.Errorf("%s 是 Git LFS pointer，请先拉取 Git LFS 真实内容", check.path)
+	}
+
+	if !bytes.HasPrefix(content, check.magic) {
+		return fmt.Errorf("%s 不是有效的%s", check.path, check.description)
+	}
+
+	return nil
+}
--- a/versionctl/projectversion/release_assets_test.go
+++ b/versionctl/projectversion/release_assets_test.go
@@ -0,0 +1,58 @@
+package projectversion
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestCheckReleaseAssets(t *testing.T) {
+	t.Run("valid assets", func(t *testing.T) {
+		root := setupReleaseAssetRoot(t)
+
+		require.NoError(t, CheckReleaseAssets(root))
+	})
+
+	t.Run("lfs pointer", func(t *testing.T) {
+		root := setupReleaseAssetRoot(t)
+		writeReleaseAsset(t, root, "assets/icon.ico", []byte("version https://git-lfs.github.com/spec/v1\noid sha256:abc\nsize 123\n"))
+
+		err := CheckReleaseAssets(root)
+
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "assets/icon.ico 是 Git LFS pointer")
+	})
+
+	t.Run("invalid format", func(t *testing.T) {
+		root := setupReleaseAssetRoot(t)
+		writeReleaseAsset(t, root, "frontend/public/icon.png", []byte("not a png"))
+
+		err := CheckReleaseAssets(root)
+
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "frontend/public/icon.png 不是有效的前端 PNG 图标")
+	})
+}
+
+func setupReleaseAssetRoot(t *testing.T) string {
+	t.Helper()
+
+	root := t.TempDir()
+	writeReleaseAsset(t, root, "assets/icon.ico", []byte{0x00, 0x00, 0x01, 0x00, 0x01})
+	writeReleaseAsset(t, root, "assets/icon.icns", []byte("icnsdata"))
+	writeReleaseAsset(t, root, "assets/icon.png", []byte{0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00})
+	writeReleaseAsset(t, root, "frontend/public/icon.png", []byte{0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00})
+
+	return root
+}
+
+func writeReleaseAsset(t *testing.T, root, relPath string, content []byte) {
+	t.Helper()
+
+	fullPath := filepath.Join(root, relPath)
+	require.NoError(t, os.MkdirAll(filepath.Dir(fullPath), 0o755))
+	require.NoError(t, os.WriteFile(fullPath, content, 0o600))
+}
--- a/versionctl/projectversion/version.go
+++ b/versionctl/projectversion/version.go
@@ -0,0 +1,443 @@
+package projectversion
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+const versionFileName = "VERSION"
+
+var (
+	semverRegex          = regexp.MustCompile(`^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$`)
+	packageVersionRegex  = regexp.MustCompile(`(?m)^(\s*"version"\s*:\s*")([^"]+)(",?)$`)
+	frontendVersionFiles = []string{
+		"frontend/.env.production",
+		"frontend/.env.development",
+		"frontend/.env.desktop",
+	}
+)
+
+type Version struct {
+	Major int
+	Minor int
+	Patch int
+}
+
+func Parse(raw string) (Version, error) {
+	trimmed := strings.TrimSpace(raw)
+	parts := semverRegex.FindStringSubmatch(trimmed)
+	if parts == nil {
+		return Version{}, fmt.Errorf("版本号 %q 不符合 x.y.z 格式", raw)
+	}
+
+	major, err := strconv.Atoi(parts[1])
+	if err != nil {
+		return Version{}, fmt.Errorf("解析 major 失败: %w", err)
+	}
+
+	minor, err := strconv.Atoi(parts[2])
+	if err != nil {
+		return Version{}, fmt.Errorf("解析 minor 失败: %w", err)
+	}
+
+	patch, err := strconv.Atoi(parts[3])
+	if err != nil {
+		return Version{}, fmt.Errorf("解析 patch 失败: %w", err)
+	}
+
+	return Version{Major: major, Minor: minor, Patch: patch}, nil
+}
+
+func (v Version) String() string {
+	return fmt.Sprintf("%d.%d.%d", v.Major, v.Minor, v.Patch)
+}
+
+func (v Version) Less(other Version) bool {
+	if v.Major != other.Major {
+		return v.Major < other.Major
+	}
+
+	if v.Minor != other.Minor {
+		return v.Minor < other.Minor
+	}
+
+	return v.Patch < other.Patch
+}
+
+func FindRepoRoot(start string) (string, error) {
+	current := start
+	for {
+		workspacePath := filepath.Join(current, "go.work")
+		if _, err := os.Stat(workspacePath); err == nil {
+			return current, nil
+		}
+
+		parent := filepath.Dir(current)
+		if parent == current {
+			return "", errors.New("未找到仓库根目录 go.work")
+		}
+
+		current = parent
+	}
+}
+
+func Read(root string) (Version, error) {
+	content, err := os.ReadFile(filepath.Join(root, versionFileName))
+	if err != nil {
+		return Version{}, fmt.Errorf("读取 VERSION 失败: %w", err)
+	}
+
+	return Parse(string(content))
+}
+
+func ReadString(root string) (string, error) {
+	version, err := Read(root)
+	if err != nil {
+		return "", err
+	}
+
+	return version.String(), nil
+}
+
+func Sync(root string) error {
+	version, err := ReadString(root)
+	if err != nil {
+		return err
+	}
+
+	packageJSONPath := filepath.Join(root, "frontend", "package.json")
+	packageJSONContent, err := os.ReadFile(packageJSONPath)
+	if err != nil {
+		return fmt.Errorf("读取 frontend/package.json 失败: %w", err)
+	}
+
+	updatedPackageJSON, err := UpdatePackageJSONVersion(string(packageJSONContent), version)
+	if err != nil {
+		return err
+	}
+
+	if err := os.WriteFile(packageJSONPath, []byte(updatedPackageJSON), 0o600); err != nil {
+		return fmt.Errorf("写入 frontend/package.json 失败: %w", err)
+	}
+
+	for _, relPath := range frontendVersionFiles {
+		fullPath := filepath.Join(root, relPath)
+		content, err := os.ReadFile(fullPath)
+		if err != nil {
+			return fmt.Errorf("读取 %s 失败: %w", relPath, err)
+		}
+
+		updated := UpsertEnvVar(string(content), "VITE_APP_VERSION", version)
+		if err := os.WriteFile(fullPath, []byte(updated), 0o600); err != nil {
+			return fmt.Errorf("写入 %s 失败: %w", relPath, err)
+		}
+	}
+
+	return nil
+}
+
+func Check(root string) error {
+	version, err := ReadString(root)
+	if err != nil {
+		return err
+	}
+
+	var errs []error
+
+	packageJSONPath := filepath.Join(root, "frontend", "package.json")
+	packageJSONContent, err := os.ReadFile(packageJSONPath)
+	if err != nil {
+		errs = append(errs, fmt.Errorf("读取 frontend/package.json 失败: %w", err))
+	} else {
+		actualVersion, readErr := ReadPackageJSONVersion(string(packageJSONContent))
+		if readErr != nil {
+			errs = append(errs, readErr)
+		} else if actualVersion != version {
+			errs = append(errs, fmt.Errorf("frontend/package.json 版本为 %s，期望 %s", actualVersion, version))
+		}
+	}
+
+	for _, relPath := range frontendVersionFiles {
+		fullPath := filepath.Join(root, relPath)
+		content, readErr := os.ReadFile(fullPath)
+		if readErr != nil {
+			errs = append(errs, fmt.Errorf("读取 %s 失败: %w", relPath, readErr))
+			continue
+		}
+
+		actualValue, ok := ReadEnvVar(string(content), "VITE_APP_VERSION")
+		if !ok {
+			errs = append(errs, fmt.Errorf("%s 缺少 VITE_APP_VERSION", relPath))
+			continue
+		}
+
+		if actualValue != version {
+			errs = append(errs, fmt.Errorf("%s 的 VITE_APP_VERSION 为 %s，期望 %s", relPath, actualValue, version))
+		}
+	}
+
+	if len(errs) > 0 {
+		return errors.Join(errs...)
+	}
+
+	return nil
+}
+
+func VerifyTag(root, tag string) error {
+	version, err := ReadString(root)
+	if err != nil {
+		return err
+	}
+
+	if !strings.HasPrefix(tag, "v") {
+		return fmt.Errorf("tag %q 必须以 v 开头", tag)
+	}
+
+	if tag[1:] != version {
+		return fmt.Errorf("tag %q 与 VERSION %q 不一致", tag, version)
+	}
+
+	return nil
+}
+
+func UpdatePackageJSONVersion(content, version string) (string, error) {
+	if _, err := Parse(version); err != nil {
+		return "", err
+	}
+
+	if !packageVersionRegex.MatchString(content) {
+		return "", errors.New("frontend/package.json 缺少 version 字段")
+	}
+
+	updated := packageVersionRegex.ReplaceAllString(content, `${1}`+version+`${3}`)
+	return updated, nil
+}
+
+func ReadPackageJSONVersion(content string) (string, error) {
+	parts := packageVersionRegex.FindStringSubmatch(content)
+	if parts == nil {
+		return "", errors.New("frontend/package.json 缺少 version 字段")
+	}
+
+	if _, err := Parse(parts[2]); err != nil {
+		return "", err
+	}
+
+	return parts[2], nil
+}
+
+func UpsertEnvVar(content, key, value string) string {
+	lines := strings.Split(strings.TrimRight(content, "\n"), "\n")
+	if len(lines) == 1 && lines[0] == "" {
+		lines = lines[:0]
+	}
+
+	updated := false
+	for i, line := range lines {
+		if strings.HasPrefix(line, key+"=") {
+			lines[i] = key + "=" + value
+			updated = true
+		}
+	}
+
+	if !updated {
+		lines = append(lines, key+"="+value)
+	}
+
+	return strings.Join(lines, "\n") + "\n"
+}
+
+func ReadEnvVar(content, key string) (string, bool) {
+	for _, line := range strings.Split(content, "\n") {
+		if strings.HasPrefix(line, key+"=") {
+			return strings.TrimPrefix(line, key+"="), true
+		}
+	}
+
+	return "", false
+}
+
+func ServerAssetName(version, goos, arch string) (string, error) {
+	if _, err := Parse(version); err != nil {
+		return "", err
+	}
+
+	switch goos {
+	case "linux", "windows", "darwin":
+	default:
+		return "", fmt.Errorf("不支持的 server 平台 %q", goos)
+	}
+
+	if arch == "" {
+		return "", errors.New("server 资产命名缺少架构")
+	}
+
+	ext := ".tar.gz"
+	if goos == "windows" {
+		ext = ".zip"
+	}
+
+	return fmt.Sprintf("nex-server_%s_%s_%s%s", version, goos, arch, ext), nil
+}
+
+func DesktopAssetName(version, platform string) (string, error) {
+	if _, err := Parse(version); err != nil {
+		return "", err
+	}
+
+	switch platform {
+	case "linux":
+		return fmt.Sprintf("Nex_%s_linux_amd64.tar.gz", version), nil
+	case "windows":
+		return fmt.Sprintf("Nex_%s_windows_amd64.zip", version), nil
+	case "macos":
+		return fmt.Sprintf("Nex_%s_macOS_universal.zip", version), nil
+	default:
+		return "", fmt.Errorf("不支持的 desktop 平台 %q", platform)
+	}
+}
+
+func DesktopInfoPlist(version, minMacOSVersion string) (string, error) {
+	if _, err := Parse(version); err != nil {
+		return "", err
+	}
+
+	if strings.TrimSpace(minMacOSVersion) == "" {
+		return "", errors.New("min macOS version 不能为空")
+	}
+
+	content := strings.Join([]string{
+		`<?xml version="1.0" encoding="UTF-8"?>`,
+		`<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">`,
+		`<plist version="1.0">`,
+		`<dict>`,
+		`    <key>CFBundleDevelopmentRegion</key>`,
+		`    <string>zh-Hans</string>`,
+		`    <key>CFBundleExecutable</key>`,
+		`    <string>nex</string>`,
+		`    <key>CFBundleIconFile</key>`,
+		`    <string>icon</string>`,
+		`    <key>CFBundleIdentifier</key>`,
+		`    <string>com.lanyuanxiaoyao.nex</string>`,
+		`    <key>CFBundleInfoDictionaryVersion</key>`,
+		`    <string>6.0</string>`,
+		`    <key>LSApplicationCategoryType</key>`,
+		`    <string>public.app-category.developer-tools</string>`,
+		`    <key>CFBundleName</key>`,
+		`    <string>Nex</string>`,
+		`    <key>CFBundleDisplayName</key>`,
+		`    <string>Nex</string>`,
+		`    <key>CFBundlePackageType</key>`,
+		`    <string>APPL</string>`,
+		`    <key>CFBundleShortVersionString</key>`,
+		`    <string>` + version + `</string>`,
+		`    <key>CFBundleVersion</key>`,
+		`    <string>` + version + `</string>`,
+		`    <key>NSHumanReadableCopyright</key>`,
+		`    <string>Copyright © 2026 Nex</string>`,
+		`    <key>LSMinimumSystemVersion</key>`,
+		`    <string>` + minMacOSVersion + `</string>`,
+		`    <key>LSUIElement</key>`,
+		`    <true/>`,
+		`    <key>NSHighResolutionCapable</key>`,
+		`    <true/>`,
+		`</dict>`,
+		`</plist>`,
+	}, "\n")
+
+	return content + "\n", nil
+}
+
+var tagRegex = regexp.MustCompile(`^v(\d+\.\d+\.\d+)$`)
+
+func ListGitTags(root string) ([]string, error) {
+	cmd := exec.Command("git", "-C", root, "tag", "--list", "--merge", "HEAD")
+	output, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("获取 git tag 列表失败: %w", err)
+	}
+
+	var tags []string
+	for _, line := range strings.Split(strings.TrimSpace(string(output)), "\n") {
+		line = strings.TrimSpace(line)
+		if line != "" {
+			tags = append(tags, line)
+		}
+	}
+
+	return tags, nil
+}
+
+func CheckNoRegression(newVersion Version, tags []string) error {
+	var maxVersion Version
+	found := false
+
+	for _, tag := range tags {
+		parts := tagRegex.FindStringSubmatch(tag)
+		if parts == nil {
+			continue
+		}
+
+		v, err := Parse(parts[1])
+		if err != nil {
+			continue
+		}
+
+		if !found || maxVersion.Less(v) {
+			maxVersion = v
+			found = true
+		}
+	}
+
+	if !found {
+		return nil
+	}
+
+	if newVersion == maxVersion {
+		return fmt.Errorf("版本号 %s 已存在（tag v%s）", newVersion, maxVersion)
+	}
+
+	if newVersion.Less(maxVersion) {
+		return fmt.Errorf("版本号 %s 小于已有 tag v%s，不允许倒退", newVersion, maxVersion)
+	}
+
+	return nil
+}
+
+func Bump(root, arg string) (Version, error) {
+	current, err := Read(root)
+	if err != nil {
+		return Version{}, err
+	}
+
+	var newVersion Version
+
+	switch arg {
+	case "major":
+		newVersion = Version{Major: current.Major + 1, Minor: 0, Patch: 0}
+	case "minor":
+		newVersion = Version{Major: current.Major, Minor: current.Minor + 1, Patch: 0}
+	case "patch":
+		newVersion = Version{Major: current.Major, Minor: current.Minor, Patch: current.Patch + 1}
+	default:
+		parsed, parseErr := Parse(arg)
+		if parseErr != nil {
+			return Version{}, fmt.Errorf("参数 %q 既非 major|minor|patch 也非合法版本号: %w", arg, parseErr)
+		}
+
+		newVersion = parsed
+	}
+
+	versionPath := filepath.Join(root, versionFileName)
+	if err := os.WriteFile(versionPath, []byte(newVersion.String()+"\n"), 0o600); err != nil {
+		return Version{}, fmt.Errorf("写入 VERSION 失败: %w", err)
+	}
+
+	return newVersion, nil
+}
--- a/versionctl/projectversion/version_test.go
+++ b/versionctl/projectversion/version_test.go
@@ -0,0 +1,215 @@
+package projectversion
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParse(t *testing.T) {
+	t.Run("valid", func(t *testing.T) {
+		version, err := Parse("1.2.3")
+		require.NoError(t, err)
+		assert.Equal(t, Version{Major: 1, Minor: 2, Patch: 3}, version)
+		assert.Equal(t, "1.2.3", version.String())
+	})
+
+	t.Run("invalid", func(t *testing.T) {
+		invalidValues := []string{"", "1.2", "1.2.3.4", "v1.2.3", "01.2.3", "1.02.3"}
+		for _, tc := range invalidValues {
+			_, err := Parse(tc)
+			assert.Error(t, err, "%q 应校验失败", tc)
+		}
+	})
+}
+
+func TestUpdatePackageJSONVersion(t *testing.T) {
+	content := "{\n  \"name\": \"frontend\",\n  \"version\": \"0.0.0\"\n}\n"
+	updated, err := UpdatePackageJSONVersion(content, "1.2.3")
+	require.NoError(t, err)
+	assert.Contains(t, updated, `"version": "1.2.3"`)
+
+	version, err := ReadPackageJSONVersion(updated)
+	require.NoError(t, err)
+	assert.Equal(t, "1.2.3", version)
+}
+
+func TestUpsertEnvVar(t *testing.T) {
+	updated := UpsertEnvVar("VITE_API_BASE=/api\n", "VITE_APP_VERSION", "1.2.3")
+	assert.Contains(t, updated, "VITE_API_BASE=/api\n")
+	assert.Contains(t, updated, "VITE_APP_VERSION=1.2.3\n")
+
+	updated = UpsertEnvVar(updated, "VITE_APP_VERSION", "2.0.0")
+	value, ok := ReadEnvVar(updated, "VITE_APP_VERSION")
+	assert.True(t, ok)
+	assert.Equal(t, "2.0.0", value)
+	assert.Equal(t, 1, strings.Count(updated, "VITE_APP_VERSION="))
+}
+
+func TestSyncAndCheck(t *testing.T) {
+	root := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(root, "VERSION"), []byte("1.2.3\n"), 0o600))
+	require.NoError(t, os.MkdirAll(filepath.Join(root, "frontend"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(root, "frontend", "package.json"), []byte("{\n  \"name\": \"frontend\",\n  \"version\": \"0.0.0\"\n}\n"), 0o600))
+	require.NoError(t, os.WriteFile(filepath.Join(root, "frontend", ".env.production"), []byte("VITE_API_BASE=/api\n"), 0o600))
+	require.NoError(t, os.WriteFile(filepath.Join(root, "frontend", ".env.development"), []byte("VITE_API_BASE=\n"), 0o600))
+	require.NoError(t, os.WriteFile(filepath.Join(root, "frontend", ".env.desktop"), []byte("VITE_API_BASE=\n"), 0o600))
+
+	require.NoError(t, Sync(root))
+	require.NoError(t, Check(root))
+
+	packageJSONContent, err := os.ReadFile(filepath.Join(root, "frontend", "package.json"))
+	require.NoError(t, err)
+	assert.Contains(t, string(packageJSONContent), `"version": "1.2.3"`)
+
+	for _, relPath := range frontendVersionFiles {
+		content, readErr := os.ReadFile(filepath.Join(root, relPath))
+		require.NoError(t, readErr)
+		assert.Contains(t, string(content), "VITE_APP_VERSION=1.2.3\n")
+	}
+}
+
+func TestVerifyTag(t *testing.T) {
+	root := t.TempDir()
+	require.NoError(t, os.WriteFile(filepath.Join(root, "VERSION"), []byte("1.2.3\n"), 0o600))
+
+	require.NoError(t, VerifyTag(root, "v1.2.3"))
+	assert.Error(t, VerifyTag(root, "1.2.3"))
+	assert.Error(t, VerifyTag(root, "v1.2.4"))
+}
+
+func TestAssetNames(t *testing.T) {
+	linuxServer, err := ServerAssetName("1.2.3", "linux", "amd64")
+	require.NoError(t, err)
+	assert.Equal(t, "nex-server_1.2.3_linux_amd64.tar.gz", linuxServer)
+
+	macServer, err := ServerAssetName("1.2.3", "darwin", "arm64")
+	require.NoError(t, err)
+	assert.Equal(t, "nex-server_1.2.3_darwin_arm64.tar.gz", macServer)
+
+	macDesktop, err := DesktopAssetName("1.2.3", "macos")
+	require.NoError(t, err)
+	assert.Equal(t, "Nex_1.2.3_macOS_universal.zip", macDesktop)
+
+	_, err = DesktopAssetName("1.2.3", "ios")
+	assert.Error(t, err)
+}
+
+func TestDesktopInfoPlist(t *testing.T) {
+	plist, err := DesktopInfoPlist("1.2.3", "13.0")
+	require.NoError(t, err)
+	assert.Contains(t, plist, "<key>CFBundleShortVersionString</key>\n    <string>1.2.3</string>")
+	assert.Contains(t, plist, "<key>CFBundleVersion</key>\n    <string>1.2.3</string>")
+	assert.Contains(t, plist, "<key>LSMinimumSystemVersion</key>\n    <string>13.0</string>")
+
+	_, err = DesktopInfoPlist("1.2", "13.0")
+	assert.Error(t, err)
+	_, err = DesktopInfoPlist("1.2.3", "")
+	assert.Error(t, err)
+}
+
+func TestLess(t *testing.T) {
+	assert.True(t, Version{1, 0, 0}.Less(Version{2, 0, 0}))
+	assert.True(t, Version{1, 1, 0}.Less(Version{1, 2, 0}))
+	assert.True(t, Version{1, 0, 1}.Less(Version{1, 0, 2}))
+	assert.False(t, Version{2, 0, 0}.Less(Version{1, 0, 0}))
+	assert.False(t, Version{1, 0, 0}.Less(Version{1, 0, 0}))
+}
+
+func TestBump(t *testing.T) {
+	setupRoot := func(t *testing.T) string {
+		t.Helper()
+		root := t.TempDir()
+		require.NoError(t, os.WriteFile(filepath.Join(root, "VERSION"), []byte("0.1.0\n"), 0o600))
+		return root
+	}
+
+	t.Run("major", func(t *testing.T) {
+		root := setupRoot(t)
+		v, err := Bump(root, "major")
+		require.NoError(t, err)
+		assert.Equal(t, Version{1, 0, 0}, v)
+
+		read, readErr := ReadString(root)
+		require.NoError(t, readErr)
+		assert.Equal(t, "1.0.0", read)
+	})
+
+	t.Run("minor", func(t *testing.T) {
+		root := setupRoot(t)
+		v, err := Bump(root, "minor")
+		require.NoError(t, err)
+		assert.Equal(t, Version{0, 2, 0}, v)
+
+		read, readErr := ReadString(root)
+		require.NoError(t, readErr)
+		assert.Equal(t, "0.2.0", read)
+	})
+
+	t.Run("patch", func(t *testing.T) {
+		root := setupRoot(t)
+		v, err := Bump(root, "patch")
+		require.NoError(t, err)
+		assert.Equal(t, Version{0, 1, 1}, v)
+
+		read, readErr := ReadString(root)
+		require.NoError(t, readErr)
+		assert.Equal(t, "0.1.1", read)
+	})
+
+	t.Run("specific version", func(t *testing.T) {
+		root := setupRoot(t)
+		v, err := Bump(root, "1.0.0")
+		require.NoError(t, err)
+		assert.Equal(t, Version{1, 0, 0}, v)
+	})
+
+	t.Run("same version as current", func(t *testing.T) {
+		root := setupRoot(t)
+		v, err := Bump(root, "0.1.0")
+		require.NoError(t, err)
+		assert.Equal(t, Version{0, 1, 0}, v)
+	})
+
+	t.Run("invalid argument", func(t *testing.T) {
+		root := setupRoot(t)
+		_, err := Bump(root, "invalid")
+		assert.Error(t, err)
+	})
+}
+
+func TestCheckNoRegression(t *testing.T) {
+	t.Run("greater than existing tag", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 2, 0}, []string{"v0.1.0"})
+		assert.NoError(t, err)
+	})
+
+	t.Run("equal to existing tag", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 1, 0}, []string{"v0.1.0"})
+		assert.Error(t, err)
+	})
+
+	t.Run("less than existing tag", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 1, 5}, []string{"v0.2.0"})
+		assert.Error(t, err)
+	})
+
+	t.Run("no tags", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 1, 0}, nil)
+		assert.NoError(t, err)
+	})
+
+	t.Run("skips non-semver tags", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 2, 0}, []string{"v0.1.0", "some-other-tag"})
+		assert.NoError(t, err)
+	})
+
+	t.Run("picks max tag", func(t *testing.T) {
+		err := CheckNoRegression(Version{0, 1, 5}, []string{"v0.1.0", "v0.2.0", "v0.0.5"})
+		assert.Error(t, err)
+	})
+}
Author	SHA1	Message	Date
lanyuanxiaoyao	6de7a2d2e1	chore: 版本升迁 v0.1.2	2026-05-05 09:58:08 +08:00
lanyuanxiaoyao	6181923d8d	fix: 修复发布流水线 LFS 资产校验	2026-05-05 09:57:02 +08:00
lanyuanxiaoyao	235efb0e62	chore: 版本升迁 v0.1.1	2026-05-05 04:39:31 +08:00
lanyuanxiaoyao	6b1af27ea2	fix: 移除 version-bump 的工作区干净检查	2026-05-05 04:39:21 +08:00
lanyuanxiaoyao	32f48777f3	feat: make version-bump 默认 BUMP=patch，无需显式传参	2026-05-05 04:32:38 +08:00
lanyuanxiaoyao	bc7a7c6e81	feat: 迁移 versionctl 为独立模块并新增 make version-bump 命令 - 将 backend/cmd/versionctl 和 backend/pkg/projectversion 迁移至独立 versionctl/ Go 模块 - 新增 bump 子命令支持 major/minor/patch 和指定版本号，含版本倒退防护 - 新增 make version-bump 编排完整升迁流程（bump + sync + check + commit + tag） - 更新所有引用路径：根 Makefile、backend/Makefile、release.yml、.golangci.yml - 新增 versionctl/.golangci.yml（精简配置）和 Makefile（lint/test/coverage） - 根 Makefile lint/test 集成 versionctl 模块 - 同步 openspec specs：新增 version-bump spec，更新 release-pipeline spec	2026-05-05 04:18:10 +08:00
lanyuanxiaoyao	3cd0458c2c	fix: 修复 golangci-lint 报告的 gosec/gocyclo/forbidigo 问题	2026-05-05 03:35:20 +08:00
lanyuanxiaoyao	8eea30ea11	feat: 统一品牌标识、关于页面三卡片布局与版本诊断功能 - 统一品牌为 Nex：侧边栏、托盘 tooltip、HTML 标题、favicon (PNG 替代 SVG) - 重构关于页面为三卡片布局（品牌/版本/链接），版本状态 Tag 绝对定位右上角 - 新增 GET /api/version 后端接口，返回 version/commit/build_time - 新增前端版本一致性诊断：匹配/不匹配/不可判断三种状态 - 同步 delta specs 到主 specs 并归档变更	2026-05-05 03:28:22 +08:00
lanyuanxiaoyao	9e33e570af	fix: 降低请求生命周期日志级别	2026-05-05 01:54:53 +08:00
lanyuanxiaoyao	7653385838	fix: 加固发布流水线运行环境修复 Windows 发布作业在 MSYS2 环境下无法访问 Go 工具链的问题。为三平台发布增加工具链预检并升级 release workflow 运行时兼容性，减少版本检查噪音和 CI 告警。	2026-05-05 01:27:38 +08:00
lanyuanxiaoyao	2c401f7ae6	chore: streamline workspace make workflows Clarify product-level server and desktop commands while moving backend-only maintenance tasks into backend/Makefile. This keeps root automation focused on core flows and aligns the main OpenSpec specs with the new command boundaries.	2026-04-28 17:44:23 +08:00
lanyuanxiaoyao	a9972360c2	feat: 增加版本化构建与发布流程引入 VERSION 作为统一版本源，避免前端、后端、桌面打包和发布资产之间的版本漂移。新增 tag 驱动的 Draft Release 流程与版本化资产命名，使本地演进和 GitHub 发布共享同一套约束。	2026-04-28 14:20:27 +08:00