feat(desktop): add client release updater

apps/desktop-client/src/main/account-health.test.ts

@@ -0,0 +1,108 @@
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { AuthProbeResult } from './auth-types'
+
+const probeAIAccountSession = vi.fn()
+const probePublishAccountSession = vi.fn()
+const silentRefreshAIAccountSession = vi.fn()
+const silentRefreshPublishAccountSession = vi.fn()
+const getSessionHandle = vi.fn()
+const getPersistedPartition = vi.fn()
+const emitRuntimeInvalidated = vi.fn()
+
+vi.mock('electron/main', () => ({
+  app: {
+    getPath: () => join(tmpdir(), 'geo-rankly-account-health-test'),
+  },
+}))
+
+vi.mock('./account-binder', () => ({
+  probeAIAccountSession,
+  probePublishAccountSession,
+  silentRefreshAIAccountSession,
+  silentRefreshPublishAccountSession,
+}))
+
+vi.mock('./session-registry', () => ({
+  getSessionHandle,
+  getPersistedPartition,
+}))
+
+vi.mock('./runtime-events', () => ({
+  emitRuntimeInvalidated,
+}))
+
+const account = {
+  id: 'account-1',
+  platform: 'doubao',
+  platformUid: 'doubao-session:demo',
+  displayName: '豆包账号',
+}
+
+function challenge(reason: AuthProbeResult['reason'] = 'captcha_gate'): AuthProbeResult {
+  return {
+    verdict: 'challenge_required',
+    reason,
+    profile: null,
+    sessionFingerprint: null,
+  }
+}
+
+function active(): AuthProbeResult {
+  return {
+    verdict: 'active',
+    reason: 'probe_success',
+    profile: {
+      displayName: '豆包账号',
+      avatarUrl: null,
+      subjectUid: 'doubao-session:demo',
+    },
+    sessionFingerprint: 'fingerprint-live',
+  }
+}
+
+describe('account health challenge recheck', () => {
+  beforeEach(() => {
+    vi.resetModules()
+    vi.clearAllMocks()
+    getSessionHandle.mockReturnValue({ partition: 'persist:test' })
+    getPersistedPartition.mockReturnValue('persist:test')
+    silentRefreshAIAccountSession.mockResolvedValue(true)
+    silentRefreshPublishAccountSession.mockResolvedValue(true)
+  })
+
+  it('hides a first challenge result when the automatic recheck succeeds', async () => {
+    probeAIAccountSession.mockResolvedValueOnce(challenge()).mockResolvedValueOnce(active())
+    const { probeTrackedAccount } = await import('./account-health')
+
+    const snapshot = await probeTrackedAccount(account, {
+      trigger: 'manual',
+      allowSilentRefresh: true,
+      force: true,
+    })
+
+    expect(probeAIAccountSession).toHaveBeenCalledTimes(2)
+    expect(snapshot.authState).toBe('active')
+    expect(snapshot.authReason).toBe('probe_success')
+  })
+
+  it('shows manual verification only after the automatic recheck still needs it', async () => {
+    probeAIAccountSession
+      .mockResolvedValueOnce(challenge('risk_control'))
+      .mockResolvedValueOnce(challenge('risk_control'))
+    const { probeTrackedAccount } = await import('./account-health')
+
+    const snapshot = await probeTrackedAccount(account, {
+      trigger: 'manual',
+      allowSilentRefresh: true,
+      force: true,
+    })
+
+    expect(probeAIAccountSession).toHaveBeenCalledTimes(2)
+    expect(snapshot.authState).toBe('challenge_required')
+    expect(snapshot.authReason).toBe('risk_control')
+  })
+})

apps/desktop-client/src/main/account-health.ts

@@ -13,7 +13,11 @@ import type {
   AccountProbeState,
   AuthProbeResult,
 } from './auth-types'
-import { getPlatformAdapter, type PlatformFailureInput } from './platform-auth-adapters'
+import {
+  getPlatformAdapter,
+  type PlatformAdapter,
+  type PlatformFailureInput,
+} from './platform-auth-adapters'
 import { emitRuntimeInvalidated } from './runtime-events'
 import { getPersistedPartition, getSessionHandle } from './session-registry'
 
@@ -30,6 +34,7 @@ const MAX_CONCURRENT_ACCOUNT_PROBES = 2
 const MANUAL_PROBE_CACHE_TTL_MS = 5 * 60_000
 const MANUAL_PROBE_MIN_INTERVAL_MS = 15_000
 const ACCOUNT_PROBE_RETRY_BACKOFF_MS = [1_000, 3_000, 10_000] as const
+const CHALLENGE_RECHECK_ATTEMPTS = 1
 
 type ProbeTrigger = 'scheduled' | 'manual' | 'preflight' | 'confirm'
 
@@ -366,6 +371,62 @@ function applyNetworkResult(
   return commitRecord(record, previousSignature)
 }
 
+function networkProbeResult(): AuthProbeResult {
+  return {
+    verdict: 'network_error',
+    reason: 'network_error',
+    profile: null,
+    sessionFingerprint: null,
+  }
+}
+
+async function probeAdapter(
+  adapter: PlatformAdapter,
+  account: PublishAccountIdentity,
+  partition: string,
+): Promise<AuthProbeResult> {
+  return await adapter.probe(account, partition).catch<AuthProbeResult>(() => networkProbeResult())
+}
+
+async function recheckChallengeResult(
+  adapter: PlatformAdapter,
+  account: PublishAccountIdentity,
+  partition: string,
+  result: AuthProbeResult,
+): Promise<AuthProbeResult> {
+  if (result.verdict !== 'challenge_required') {
+    return result
+  }
+
+  let confirmed = result
+  for (let attempt = 0; attempt < CHALLENGE_RECHECK_ATTEMPTS; attempt += 1) {
+    confirmed = await probeAdapter(adapter, account, partition)
+    if (confirmed.verdict !== 'challenge_required') {
+      return confirmed
+    }
+  }
+
+  return confirmed
+}
+
+function applyProbeResult(
+  record: AccountHealthRecord,
+  result: AuthProbeResult,
+  now: number,
+  trigger: ProbeTrigger,
+): AccountHealthSnapshot {
+  switch (result.verdict) {
+    case 'active':
+      return applyActiveResult(record, result, now)
+    case 'expired':
+      return applyExpiredResult(record, result, now)
+    case 'challenge_required':
+      return applyChallengeResult(record, result, now)
+    default:
+      return applyNetworkResult(record, result, now, trigger)
+  }
+}
+
 async function performProbeLocked(
   account: PublishAccountIdentity,
   options: {
@@ -407,28 +468,18 @@ async function performProbeLocked(
     }
   }
 
-  const result = await adapter.probe(account, partition).catch<AuthProbeResult>(() => ({
-    verdict: 'network_error',
-    reason: 'network_error',
-    profile: null,
-    sessionFingerprint: null,
-  }))
+  const result = await probeAdapter(adapter, account, partition)
 
   if (record.authRevision !== probeAuthRevision) {
     return toPublicSnapshot(record)
   }
 
-  const now = Date.now()
-  switch (result.verdict) {
-    case 'active':
-      return applyActiveResult(record, result, now)
-    case 'expired':
-      return applyExpiredResult(record, result, now)
-    case 'challenge_required':
-      return applyChallengeResult(record, result, now)
-    default:
-      return applyNetworkResult(record, result, now, options.trigger)
+  const confirmedResult = await recheckChallengeResult(adapter, account, partition, result)
+  if (record.authRevision !== probeAuthRevision) {
+    return toPublicSnapshot(record)
   }
+
+  return applyProbeResult(record, confirmedResult, Date.now(), options.trigger)
 }
 
 function canUseCachedProbe(
@@ -922,15 +973,25 @@ export async function reportAccountFailure(
     const now = Date.now()
 
     if (classification === 'challenge' || classification === 'risk_control') {
-      record.authState = 'challenge_required'
-      record.probeState = 'idle'
-      record.authReason = classification === 'risk_control' ? 'risk_control' : 'captcha_gate'
-      record.lastAuthFailureAt = now
-      record.lastProbeAt = now
-      record.nextProbeAt = nextRegularProbeAt(now)
-      record.suspectedExpiredAt = null
-      record.confirmFailureCount = 0
-      return commitRecord(record, previousSignature)
+      record.probeState = 'probing'
+      commitRecord(record, previousSignature)
+
+      const partition = resolveKnownPartition(account.id)
+      const result = partition
+        ? await recheckChallengeResult(adapter, account, partition, {
+            verdict: 'challenge_required',
+            reason: classification === 'risk_control' ? 'risk_control' : 'captcha_gate',
+            profile: null,
+            sessionFingerprint: null,
+          })
+        : {
+            verdict: 'expired' as const,
+            reason: 'missing_partition' as const,
+            profile: null,
+            sessionFingerprint: null,
+          }
+
+      return applyProbeResult(record, result, Date.now(), 'confirm')
     }
 
     if (classification === 'network') {

apps/desktop-client/src/main/app-version.ts

@@ -0,0 +1,9 @@
+import { app } from 'electron/main'
+
+export function getDesktopAppVersion(): string {
+  return app.getVersion()
+}
+
+export function getDesktopReleaseChannel(): string {
+  return process.env.DESKTOP_RELEASE_CHANNEL ?? (app.isPackaged ? 'stable' : 'dev')
+}

apps/desktop-client/src/main/bootstrap.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 
 import type {
   DesktopAccountInfo,
+  DesktopClientReleaseCheckResponse,
   DesktopClientRotateResponse,
   DesktopRuntimeSessionSyncRequest,
 } from '@geo/shared-types'
@@ -31,23 +32,29 @@ import {
   setDesktopAppSetting,
   type DesktopAppSettingKey,
 } from './app-settings'
-import { resolveDesktopClientID, resolveDesktopDeviceInfo } from './device-id'
+import { getDesktopAppVersion, getDesktopReleaseChannel } from './app-version'
 import {
-  installObservedGlobalFetch,
-  registerObservedRequestRendererTarget,
-} from './network-observer'
-import { getPlaywrightCDPPort, startHiddenPlaywrightReaper } from './playwright-cdp'
+  defaultDesktopUpdateChannel,
+  startDesktopClientUpdate,
+  type DesktopClientUpdateProgressEvent,
+} from './client-updater'
+import { resolveDesktopClientID, resolveDesktopDeviceInfo } from './device-id'
 import {
   clearSavedLoginCredentials,
   getSavedLoginCredentials,
   saveLoginCredentials,
 } from './login-credentials'
+import {
+  installObservedGlobalFetch,
+  registerObservedRequestRendererTarget,
+} from './network-observer'
+import { getPlaywrightCDPPort, startHiddenPlaywrightReaper } from './playwright-cdp'
 import { initProcessMetricsSampler } from './process-metrics'
 import { registerRendererDevtoolsProxyTarget } from './renderer-devtools-proxy'
 import {
+  getRuntimeControllerSnapshot,
   noteRuntimeAccountBound,
   refreshRuntimeAccounts,
-  getRuntimeControllerSnapshot,
   releaseRuntimeSession,
   requestRuntimeAccountProbe,
   syncRuntimeSession,
@@ -59,8 +66,10 @@ import { initScheduler } from './scheduler'
 import { initSessionRegistry } from './session-registry'
 import { initSingleInstance } from './single-instance'
 import {
+  checkDesktopClientRelease,
   initTransport,
   listDesktopPublishTasks,
+  resolveDesktopClientReleaseDownloadURL,
   retryDesktopPublishTask,
   rotateDesktopClient,
 } from './transport/api-client'
@@ -772,15 +781,73 @@ function isSafeExternalUrl(url: string): boolean {
   }
 }
 
+function desktopReleasePlatform(): string {
+  switch (process.platform) {
+    case 'darwin':
+      return 'darwin'
+    case 'win32':
+      return 'win32'
+    case 'linux':
+      return 'linux'
+    default:
+      return process.platform
+  }
+}
+
+function desktopReleaseArch(): string {
+  switch (process.arch) {
+    case 'x64':
+    case 'arm64':
+    case 'ia32':
+      return process.arch
+    default:
+      return 'universal'
+  }
+}
+
+async function checkCurrentDesktopClientRelease(): Promise<DesktopClientReleaseCheckResponse> {
+  const snapshot = getRuntimeControllerSnapshot()
+  if (!snapshot.session?.client_token) {
+    throw new Error('desktop_client_not_registered')
+  }
+
+  return checkDesktopClientRelease({
+    platform: desktopReleasePlatform(),
+    arch: desktopReleaseArch(),
+    version: getDesktopAppVersion(),
+    channel: snapshot.session.desktop_client?.channel || getDesktopReleaseChannel(),
+  })
+}
+
+async function resolveCurrentDesktopClientReleaseDownloadURL(): Promise<{ download_url: string }> {
+  const snapshot = getRuntimeControllerSnapshot()
+  if (!snapshot.session?.client_token) {
+    throw new Error('desktop_client_not_registered')
+  }
+
+  return resolveDesktopClientReleaseDownloadURL({
+    platform: desktopReleasePlatform(),
+    arch: desktopReleaseArch(),
+    version: getDesktopAppVersion(),
+    channel: snapshot.session.desktop_client?.channel || getDesktopReleaseChannel(),
+  })
+}
+
+function emitClientUpdateProgress(event: DesktopClientUpdateProgressEvent): void {
+  for (const window of BrowserWindow.getAllWindows()) {
+    if (!window.isDestroyed()) {
+      window.webContents.send('desktop:client-update-progress', event)
+    }
+  }
+}
+
 function registerDesktopProtocolClient(): void {
   if (app.isDefaultProtocolClient(desktopDeepLinkScheme)) {
     return
   }
 
   if (process.defaultApp && process.execPath) {
-    app.setAsDefaultProtocolClient(desktopDeepLinkScheme, process.execPath, [
-      process.argv[1] ?? '',
-    ])
+    app.setAsDefaultProtocolClient(desktopDeepLinkScheme, process.execPath, [process.argv[1] ?? ''])
     return
   }
 
@@ -847,6 +914,34 @@ function handleDesktopDeepLink(rawUrl: string): void {
 
 function registerBridgeHandlers(): void {
   ipcMain.handle('desktop:ping', () => 'pong')
+  ipcMain.handle('desktop:version-info', () => ({
+    version: getDesktopAppVersion(),
+    channel: getDesktopReleaseChannel(),
+  }))
+  safeHandle('desktop:check-client-release', () => checkCurrentDesktopClientRelease())
+  safeHandle('desktop:client-release-download-url', () =>
+    resolveCurrentDesktopClientReleaseDownloadURL(),
+  )
+  safeHandle('desktop:quit-app', async () => {
+    app.quit()
+    return null
+  })
+  safeHandle('desktop:start-client-update', async () => {
+    const snapshot = getRuntimeControllerSnapshot()
+    if (!snapshot.session?.client_token) {
+      throw new Error('desktop_client_not_registered')
+    }
+
+    return startDesktopClientUpdate({
+      platform: desktopReleasePlatform(),
+      arch: desktopReleaseArch(),
+      channel: defaultDesktopUpdateChannel(snapshot.session.desktop_client?.channel),
+      notify: emitClientUpdateProgress,
+      beforeInstall: () => {
+        quitReleaseInFlight = true
+      },
+    })
+  })
   ipcMain.handle('desktop:device-info', () => resolveDesktopDeviceInfo())
   safeHandle(
     'desktop:client-id',

apps/desktop-client/src/main/client-updater.ts

@@ -0,0 +1,240 @@
+import { autoUpdater, type ProgressInfo, type UpdateDownloadedEvent } from 'electron-updater'
+import { app } from 'electron/main'
+
+import { getDesktopAppVersion, getDesktopReleaseChannel } from './app-version'
+import { resolveDesktopApiURL } from './transport/api-client'
+
+export type DesktopClientUpdateStage =
+  | 'idle'
+  | 'checking'
+  | 'downloading'
+  | 'downloaded'
+  | 'installing'
+  | 'not-available'
+  | 'error'
+
+export interface DesktopClientUpdateProgressEvent {
+  stage: DesktopClientUpdateStage
+  percent: number | null
+  transferred: number | null
+  total: number | null
+  bytesPerSecond: number | null
+  version: string | null
+  message?: string
+}
+
+export interface DesktopClientUpdateResult {
+  update_available: boolean
+  version: string | null
+  stage: DesktopClientUpdateStage
+}
+
+interface StartDesktopClientUpdateOptions {
+  platform: string
+  arch: string
+  channel: string
+  notify: (event: DesktopClientUpdateProgressEvent) => void
+  beforeInstall?: () => void
+}
+
+let updateInFlight: Promise<DesktopClientUpdateResult> | null = null
+let updaterConfigured = false
+let downloadedVersion: string | null = null
+let progressNotifier: StartDesktopClientUpdateOptions['notify'] | null = null
+
+function encodeFeedPathSegment(value: string): string {
+  return encodeURIComponent(value.trim())
+}
+
+function updaterFeedURL(options: StartDesktopClientUpdateOptions): string {
+  return resolveDesktopApiURL(
+    [
+      '/api/desktop/releases/updater',
+      encodeFeedPathSegment(options.platform),
+      encodeFeedPathSegment(options.arch),
+      encodeFeedPathSegment(options.channel),
+      encodeFeedPathSegment(getDesktopAppVersion()),
+      '',
+    ].join('/'),
+  )
+}
+
+function emitProgress(
+  notify: StartDesktopClientUpdateOptions['notify'] | null,
+  event: DesktopClientUpdateProgressEvent,
+): void {
+  notify?.(event)
+}
+
+function updaterErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function isCodeSignatureValidationError(message: string): boolean {
+  return (
+    message.includes('Code signature') ||
+    message.includes('did not pass validation') ||
+    message.includes('代码未能满足指定的代码要求') ||
+    message.includes('code requirements')
+  )
+}
+
+function normalizeUpdaterError(error: unknown): string {
+  const message = updaterErrorMessage(error)
+  if (isCodeSignatureValidationError(message)) {
+    return 'desktop_client_update_signature_validation_failed'
+  }
+  return message || 'desktop_client_update_failed'
+}
+
+function configureUpdater(options: StartDesktopClientUpdateOptions): void {
+  progressNotifier = options.notify
+  autoUpdater.autoDownload = false
+  autoUpdater.autoInstallOnAppQuit = false
+  autoUpdater.disableDifferentialDownload = true
+  autoUpdater.allowDowngrade = false
+  autoUpdater.allowPrerelease = options.channel !== 'stable'
+  autoUpdater.channel = null
+  autoUpdater.logger = console
+  autoUpdater.setFeedURL({
+    provider: 'generic',
+    url: updaterFeedURL(options),
+    channel: 'latest',
+  })
+
+  if (updaterConfigured) {
+    return
+  }
+  updaterConfigured = true
+
+  autoUpdater.on('download-progress', (info: ProgressInfo) => {
+    emitProgress(progressNotifier, {
+      stage: 'downloading',
+      percent: Number.isFinite(info.percent) ? info.percent : null,
+      transferred: Number.isFinite(info.transferred) ? info.transferred : null,
+      total: Number.isFinite(info.total) ? info.total : null,
+      bytesPerSecond: Number.isFinite(info.bytesPerSecond) ? info.bytesPerSecond : null,
+      version: downloadedVersion,
+    })
+  })
+
+  autoUpdater.on('update-downloaded', (event: UpdateDownloadedEvent) => {
+    downloadedVersion = event.version
+    emitProgress(progressNotifier, {
+      stage: 'downloaded',
+      percent: 100,
+      transferred: null,
+      total: null,
+      bytesPerSecond: null,
+      version: event.version,
+      message: 'update_downloaded',
+    })
+  })
+
+  autoUpdater.on('error', (error) => {
+    console.warn('[desktop-updater] update failed', error)
+    emitProgress(progressNotifier, {
+      stage: 'error',
+      percent: null,
+      transferred: null,
+      total: null,
+      bytesPerSecond: null,
+      version: downloadedVersion,
+      message: normalizeUpdaterError(error),
+    })
+  })
+}
+
+export function startDesktopClientUpdate(
+  options: StartDesktopClientUpdateOptions,
+): Promise<DesktopClientUpdateResult> {
+  if (updateInFlight) {
+    return updateInFlight
+  }
+
+  updateInFlight = runDesktopClientUpdate(options).finally(() => {
+    updateInFlight = null
+  })
+  return updateInFlight
+}
+
+async function runDesktopClientUpdate(
+  options: StartDesktopClientUpdateOptions,
+): Promise<DesktopClientUpdateResult> {
+  if (!app.isPackaged && process.env.DESKTOP_ALLOW_DEV_UPDATER !== '1') {
+    throw new Error('desktop_update_requires_packaged_app')
+  }
+
+  downloadedVersion = null
+  configureUpdater(options)
+
+  emitProgress(options.notify, {
+    stage: 'checking',
+    percent: null,
+    transferred: null,
+    total: null,
+    bytesPerSecond: null,
+    version: null,
+  })
+
+  let checkResult
+  try {
+    checkResult = await autoUpdater.checkForUpdates()
+  } catch (error) {
+    throw new Error(normalizeUpdaterError(error))
+  }
+  if (!checkResult?.isUpdateAvailable) {
+    emitProgress(options.notify, {
+      stage: 'not-available',
+      percent: null,
+      transferred: null,
+      total: null,
+      bytesPerSecond: null,
+      version: checkResult?.updateInfo.version ?? null,
+    })
+    return {
+      update_available: false,
+      version: checkResult?.updateInfo.version ?? null,
+      stage: 'not-available',
+    }
+  }
+
+  downloadedVersion = checkResult.updateInfo.version
+  emitProgress(options.notify, {
+    stage: 'downloading',
+    percent: 0,
+    transferred: 0,
+    total: null,
+    bytesPerSecond: null,
+    version: checkResult.updateInfo.version,
+  })
+
+  try {
+    await autoUpdater.downloadUpdate(checkResult.cancellationToken)
+  } catch (error) {
+    throw new Error(normalizeUpdaterError(error))
+  }
+  emitProgress(options.notify, {
+    stage: 'installing',
+    percent: 100,
+    transferred: null,
+    total: null,
+    bytesPerSecond: null,
+    version: checkResult.updateInfo.version,
+  })
+
+  setTimeout(() => {
+    options.beforeInstall?.()
+    autoUpdater.quitAndInstall(process.platform === 'win32', true)
+  }, 250)
+
+  return {
+    update_available: true,
+    version: checkResult.updateInfo.version,
+    stage: 'installing',
+  }
+}
+
+export function defaultDesktopUpdateChannel(clientChannel: string | null | undefined): string {
+  return clientChannel?.trim() || getDesktopReleaseChannel()
+}

apps/desktop-client/src/main/runtime-controller.ts

@@ -54,6 +54,7 @@ import {
   type MonitorAdapter,
   type PublishAdapter,
 } from './adapters'
+import { getDesktopAppVersion, getDesktopReleaseChannel } from './app-version'
 import {
   getLeaseManagerSnapshot,
   noteLeaseExtended,
@@ -1096,8 +1097,8 @@ async function sendHeartbeat(source: 'startup' | 'timer'): Promise<void> {
       device_name: hostname() || state.client?.device_name || `Desktop ${process.platform}`,
       os: process.platform,
       cpu_arch: process.arch,
-      client_version: state.client?.client_version ?? '0.1.0-dev',
-      channel: state.client?.channel ?? 'dev',
+      client_version: getDesktopAppVersion(),
+      channel: state.client?.channel ?? getDesktopReleaseChannel(),
       startup: source === 'startup',
       account_ids: state.accounts
         .filter((account) => shouldReportAccountPresence(account))

apps/desktop-client/src/main/transport/api-client.ts

@@ -13,6 +13,7 @@ import type {
   DesktopArticleContent,
   DesktopClientHeartbeatRequest,
   DesktopClientHeartbeatResponse,
+  DesktopClientReleaseCheckResponse,
   DesktopClientRotateResponse,
   DesktopPublishTaskListResponse,
   DesktopRuntimeSessionSyncRequest,
@@ -35,13 +36,13 @@ import type {
 } from '@geo/shared-types'
 import { app } from 'electron/main'
 
+import { normalizeDesktopApiBaseURL } from '../../shared/api-base-url'
 import {
   failObservedRequest,
   resolveObservedRequest,
   startObservedRequest,
 } from '../network-observer'
 import { canUseRendererDevtoolsProxy, rendererDevtoolsFetch } from '../renderer-devtools-proxy'
-import { normalizeDesktopApiBaseURL } from '../../shared/api-base-url'
 
 type TransportAuthState = 'pending' | 'registered' | 'expired'
 type TransportDispatchState = 'idle' | 'connecting' | 'streaming'
@@ -225,10 +226,7 @@ function normalizeErrorForDiagnostics(error: unknown): Record<string, unknown> {
   }
 }
 
-function appendAccountUpsertDiagnostic(
-  payload: UpsertDesktopAccountRequest,
-  error: unknown,
-): void {
+function appendAccountUpsertDiagnostic(payload: UpsertDesktopAccountRequest, error: unknown): void {
   const target = join(app.getPath('userData'), ACCOUNT_UPSERT_DIAGNOSTIC_FILE)
   const event = {
     at: new Date().toISOString(),
@@ -514,6 +512,44 @@ export async function rotateDesktopClient(): Promise<DesktopClientRotateResponse
   )
 }
 
+export async function checkDesktopClientRelease(params: {
+  platform: string
+  arch: string
+  version: string
+  channel?: string
+}): Promise<DesktopClientReleaseCheckResponse> {
+  const search = new URLSearchParams({
+    platform: params.platform,
+    arch: params.arch,
+    version: params.version,
+  })
+  if (params.channel?.trim()) {
+    search.set('channel', params.channel.trim())
+  }
+  return desktopGet<DesktopClientReleaseCheckResponse>(
+    `/api/desktop/clients/releases/latest?${search.toString()}`,
+  )
+}
+
+export async function resolveDesktopClientReleaseDownloadURL(params: {
+  platform: string
+  arch: string
+  version: string
+  channel?: string
+}): Promise<{ download_url: string; expires_in?: number | null }> {
+  const search = new URLSearchParams({
+    platform: params.platform,
+    arch: params.arch,
+    version: params.version,
+  })
+  if (params.channel?.trim()) {
+    search.set('channel', params.channel.trim())
+  }
+  return desktopGet<{ download_url: string; expires_in?: number | null }>(
+    `/api/desktop/clients/releases/download-url?${search.toString()}`,
+  )
+}
+
 export async function offlineDesktopClient(): Promise<void> {
   await desktopPost<{ server_time: string }, Record<string, never>>(
     '/api/desktop/clients/offline',

apps/desktop-client/src/preload/bridge.ts

@@ -1,7 +1,10 @@
 import type {
   CreatePublishJobResponse,
   DesktopAccountInfo,
+  DesktopClientReleaseCheckResponse,
   DesktopClientRotateResponse,
+  DesktopClientUpdateProgressEvent,
+  DesktopClientUpdateResult,
   DesktopPublishTaskListResponse,
   DesktopRuntimeSessionSyncRequest,
   ListDesktopPublishTasksParams,
@@ -17,6 +20,11 @@ interface DesktopDeviceInfo {
   cpu_arch: string
 }
 
+interface DesktopAppVersionInfo {
+  version: string
+  channel: string
+}
+
 interface DesktopClientIDScope {
   tenant_id: number
   workspace_id: number
@@ -115,6 +123,18 @@ if (import.meta.env.DEV) {
 const desktopBridge = {
   app: {
     ping: () => ipcRenderer.invoke('desktop:ping') as Promise<string>,
+    versionInfo: () => ipcRenderer.invoke('desktop:version-info') as Promise<DesktopAppVersionInfo>,
+    checkClientRelease: () =>
+      ipcRenderer.invoke(
+        'desktop:check-client-release',
+      ) as Promise<DesktopClientReleaseCheckResponse>,
+    clientReleaseDownloadURL: () =>
+      ipcRenderer.invoke('desktop:client-release-download-url') as Promise<{
+        download_url: string
+      }>,
+    quitApp: () => ipcRenderer.invoke('desktop:quit-app') as Promise<null>,
+    startClientUpdate: () =>
+      ipcRenderer.invoke('desktop:start-client-update') as Promise<DesktopClientUpdateResult>,
     deviceInfo: () => ipcRenderer.invoke('desktop:device-info') as Promise<DesktopDeviceInfo>,
     clientId: (scope: DesktopClientIDScope) =>
       ipcRenderer.invoke('desktop:client-id', scope) as Promise<string>,
@@ -153,11 +173,14 @@ const desktopBridge = {
     getAppSettings: () =>
       ipcRenderer.invoke('desktop:get-app-settings') as Promise<DesktopAppSettings>,
     getLoginCredentials: () =>
-      ipcRenderer.invoke('desktop:get-login-credentials') as Promise<DesktopLoginCredentials | null>,
+      ipcRenderer.invoke(
+        'desktop:get-login-credentials',
+      ) as Promise<DesktopLoginCredentials | null>,
     saveLoginCredentials: (credentials: DesktopLoginCredentials) =>
-      ipcRenderer.invoke('desktop:save-login-credentials', credentials) as Promise<
-        DesktopLoginCredentials
-      >,
+      ipcRenderer.invoke(
+        'desktop:save-login-credentials',
+        credentials,
+      ) as Promise<DesktopLoginCredentials>,
     clearLoginCredentials: () =>
       ipcRenderer.invoke('desktop:clear-login-credentials') as Promise<null>,
     setAppSetting: (key: keyof DesktopAppSettings, value: boolean) =>
@@ -205,6 +228,15 @@ const desktopBridge = {
         ipcRenderer.off('desktop:network-observed', wrapped)
       }
     },
+    onClientUpdateProgress: (listener: (event: DesktopClientUpdateProgressEvent) => void) => {
+      const wrapped = (_event: IpcRendererEvent, payload: DesktopClientUpdateProgressEvent) => {
+        listener(payload)
+      }
+      ipcRenderer.on('desktop:client-update-progress', wrapped)
+      return () => {
+        ipcRenderer.off('desktop:client-update-progress', wrapped)
+      }
+    },
   },
   workbenchNavigation: {
     getState: () =>
@@ -212,8 +244,7 @@ const desktopBridge = {
         'desktop:workbench-navigation:get-state',
       ) as Promise<WorkbenchNavigationState>,
     goBack: () => ipcRenderer.invoke('desktop:workbench-navigation:go-back') as Promise<null>,
-    goForward: () =>
-      ipcRenderer.invoke('desktop:workbench-navigation:go-forward') as Promise<null>,
+    goForward: () => ipcRenderer.invoke('desktop:workbench-navigation:go-forward') as Promise<null>,
     reload: () => ipcRenderer.invoke('desktop:workbench-navigation:reload') as Promise<null>,
     onStateChanged: (listener: (state: WorkbenchNavigationState) => void) => {
       const wrapped = (_event: IpcRendererEvent, payload: WorkbenchNavigationState) => {

apps/desktop-client/src/renderer/components/DesktopShell.vue

@@ -1,15 +1,17 @@
 <script setup lang="ts">
 import {
   AppstoreOutlined,
+  DownloadOutlined,
   LinkOutlined,
   LogoutOutlined,
   RobotOutlined,
   SendOutlined,
   SettingOutlined,
 } from '@ant-design/icons-vue'
-import { computed } from 'vue'
+import { computed, onMounted, ref, watch } from 'vue'
 import { RouterLink, RouterView, useRoute } from 'vue-router'
 
+import { useClientRelease } from '../composables/useClientRelease'
 import { useDesktopRuntime } from '../composables/useDesktopRuntime'
 import { useDesktopSession } from '../composables/useDesktopSession'
 import { desktopMonitoringMediaCatalog, desktopPublishMediaCatalog } from '../lib/media-catalog'
@@ -17,6 +19,21 @@ import { desktopMonitoringMediaCatalog, desktopPublishMediaCatalog } from '../li
 const route = useRoute()
 const { snapshot, error, refreshAccounts } = useDesktopRuntime()
 const { session, logout } = useDesktopSession()
+const {
+  check: checkClientRelease,
+  startUpdate: startClientUpdate,
+  openManualDownload,
+  updateProgress,
+  updateError,
+  updateManualDownloadRequired,
+  manualDownloadLoading,
+  updating,
+} = useClientRelease()
+let hasCheckedClientRelease = false
+const updateModalOpen = ref(false)
+const updateModalVersion = ref('')
+const updateModalForce = ref(false)
+const updateModalStarted = ref(false)
 
 const accountAwareRoutes = new Set(['/media-platforms', '/ai-platforms'])
 
@@ -66,12 +83,7 @@ const navItems = computed(() => {
 
 const operatorName = computed(() => {
   const user = session.value?.user
-  return (
-    user?.name?.trim() ||
-    user?.phone?.trim() ||
-    user?.email?.trim() ||
-    '未命名操作员'
-  )
+  return user?.name?.trim() || user?.phone?.trim() || user?.email?.trim() || '未命名操作员'
 })
 const operatorEmail = computed(() => {
   const user = session.value?.user
@@ -87,10 +99,131 @@ const clientLabel = computed(
   () =>
     liveClientLabel.value ?? session.value?.desktopClient?.device_name ?? '当前设备尚未注册 client',
 )
+const updateProgressPercent = computed(() => {
+  const percent = updateProgress.value?.percent
+  if (typeof percent !== 'number' || !Number.isFinite(percent)) {
+    return null
+  }
+  return Math.max(0, Math.min(100, Math.round(percent)))
+})
+const updateProgressLabel = computed(() => {
+  if (isUpdateFailed.value) {
+    return '热更新失败，请去官网更新'
+  }
+  switch (updateProgress.value?.stage) {
+    case 'checking':
+      return '正在准备更新'
+    case 'downloading':
+      return updateProgressPercent.value === null
+        ? '正在下载更新'
+        : `正在下载 ${updateProgressPercent.value}%`
+    case 'downloaded':
+      return '下载完成，准备安装'
+    case 'installing':
+      return '正在重启安装'
+    case 'not-available':
+      return '当前已是最新版本'
+    default:
+      return updateModalStarted.value ? '正在准备更新' : ''
+  }
+})
+const isUpdateFailed = computed(() => Boolean(updateError.value))
+const updateProgressBarPercent = computed(() => {
+  if (!updateModalStarted.value) {
+    return 0
+  }
+  if (updateProgress.value?.stage === 'checking') {
+    return 8
+  }
+  if (updateProgress.value?.stage === 'downloaded' || updateProgress.value?.stage === 'installing') {
+    return 100
+  }
+  return updateProgressPercent.value ?? 8
+})
+const updatePrimaryLabel = computed(() => {
+  if (!updateModalStarted.value) {
+    return '立即更新'
+  }
+  if (updating.value) {
+    return '更新中'
+  }
+  return updateError.value ? '重试更新' : '立即更新'
+})
+const updateModalEyebrow = computed(() => {
+  if (isUpdateFailed.value) {
+    return '热更新失败'
+  }
+  return updateModalForce.value ? '必须更新' : '发现新版本'
+})
+const updateModalTitle = computed(() => {
+  if (isUpdateFailed.value) {
+    return '热更新失败，请去官网更新'
+  }
+  return '发现新的客户端版本'
+})
+const updateModalDescription = computed(() => {
+  if (isUpdateFailed.value) {
+    return `最新版本 ${updateModalVersion.value} 已可下载，请前往官网下载安装包后手动更新。`
+  }
+  return `最新版本 ${updateModalVersion.value} 已可下载。自动更新失败时会打开官网下载地址。`
+})
 
 function openSettingsWindow() {
   void window.desktopBridge.app.openSettingsWindow()
 }
+
+async function startClientReleaseUpdate() {
+  updateModalStarted.value = true
+  const updated = await startClientUpdate()
+  if (updated) {
+    return
+  }
+}
+
+function notifyClientUpdate(latestVersion: string, forceUpdate: boolean) {
+  updateModalVersion.value = latestVersion
+  updateModalForce.value = forceUpdate
+  updateModalStarted.value = false
+  updateModalOpen.value = true
+}
+
+function closeUpdateModal() {
+  if (isUpdateFailed.value || updateModalForce.value || updating.value) {
+    return
+  }
+  updateModalOpen.value = false
+}
+
+function openUpdateManualDownload() {
+  void openManualDownload()
+}
+
+function quitApp() {
+  void window.desktopBridge.app.quitApp()
+}
+
+async function checkClientReleaseOnce() {
+  if (hasCheckedClientRelease || !session.value?.clientToken) {
+    return
+  }
+  hasCheckedClientRelease = true
+  const result = await checkClientRelease('silent')
+  if (!result?.update_available) {
+    return
+  }
+  notifyClientUpdate(result.latest_version, result.force_update)
+}
+
+onMounted(() => {
+  void checkClientReleaseOnce()
+})
+
+watch(
+  () => session.value?.clientToken,
+  () => {
+    void checkClientReleaseOnce()
+  },
+)
 </script>
 
 <template>
@@ -172,6 +305,89 @@ function openSettingsWindow() {
       <div class="content-dragbar" aria-hidden="true"></div>
       <RouterView />
     </main>
+
+    <a-modal
+      v-model:open="updateModalOpen"
+      :closable="!isUpdateFailed && !updateModalForce && !updating"
+      :mask-closable="!isUpdateFailed && !updateModalForce && !updating"
+      :keyboard="!isUpdateFailed && !updateModalForce && !updating"
+      :footer="null"
+      width="520px"
+      centered
+      class="client-update-modal"
+      @cancel="closeUpdateModal"
+    >
+      <section class="client-update-dialog">
+        <div class="client-update-dialog__mark">
+          <DownloadOutlined />
+        </div>
+        <div class="client-update-dialog__copy">
+          <span>{{ updateModalEyebrow }}</span>
+          <h2>{{ updateModalTitle }}</h2>
+          <p>{{ updateModalDescription }}</p>
+          <button
+            v-if="isUpdateFailed"
+            type="button"
+            class="client-update-link-button"
+            :disabled="manualDownloadLoading"
+            @click="openUpdateManualDownload"
+          >
+            <DownloadOutlined />
+            {{ manualDownloadLoading ? '正在打开更新包链接' : '打开更新包链接' }}
+          </button>
+        </div>
+
+        <div v-if="updateModalStarted && !isUpdateFailed" class="client-update-progress">
+          <div class="client-update-progress__meta">
+            <strong>{{ updateProgressLabel }}</strong>
+            <span v-if="updateProgressPercent !== null">{{ updateProgressPercent }}%</span>
+          </div>
+          <div class="client-update-progress__bar">
+            <span :style="{ width: `${updateProgressBarPercent}%` }"></span>
+          </div>
+        </div>
+
+        <div class="client-update-dialog__actions">
+          <button
+            v-if="isUpdateFailed"
+            type="button"
+            class="client-update-button client-update-button--primary"
+            @click="quitApp"
+          >
+            退出
+          </button>
+          <button
+            v-else-if="!updateModalForce"
+            type="button"
+            class="client-update-button client-update-button--ghost"
+            :disabled="updating"
+            @click="closeUpdateModal"
+          >
+            稍后
+          </button>
+          <button
+            v-if="!isUpdateFailed && updateManualDownloadRequired"
+            type="button"
+            class="client-update-button client-update-button--ghost"
+            :disabled="manualDownloadLoading"
+            @click="openUpdateManualDownload"
+          >
+            <DownloadOutlined />
+            {{ manualDownloadLoading ? '打开中' : '官网下载' }}
+          </button>
+          <button
+            v-if="!isUpdateFailed"
+            type="button"
+            class="client-update-button client-update-button--primary"
+            :disabled="updating"
+            @click="startClientReleaseUpdate"
+          >
+            <DownloadOutlined />
+            {{ updatePrimaryLabel }}
+          </button>
+        </div>
+      </section>
+    </a-modal>
   </div>
 </template>
 
@@ -548,6 +764,195 @@ h1 {
   z-index: 5;
 }
 
+:global(.client-update-modal .ant-modal-content) {
+  overflow: hidden;
+  border-radius: 12px;
+  padding: 0;
+  box-shadow:
+    0 22px 48px rgba(15, 23, 42, 0.18),
+    0 8px 18px rgba(15, 23, 42, 0.08);
+}
+
+:global(.client-update-modal .ant-modal-close) {
+  top: 18px;
+  right: 18px;
+}
+
+.client-update-dialog {
+  display: flex;
+  flex-direction: column;
+  gap: 22px;
+  padding: 34px 36px 30px;
+  background: #ffffff;
+}
+
+.client-update-dialog__mark {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 42px;
+  height: 42px;
+  border-radius: 8px;
+  background: #e6f4ff;
+  color: #1677ff;
+  font-size: 20px;
+}
+
+.client-update-dialog__copy {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.client-update-dialog__copy span {
+  color: #1677ff;
+  font-size: 13px;
+  font-weight: 800;
+}
+
+.client-update-dialog__copy h2 {
+  margin: 0;
+  color: #111827;
+  font-size: 24px;
+  font-weight: 800;
+  line-height: 1.25;
+}
+
+.client-update-dialog__copy p {
+  margin: 0;
+  color: #374151;
+  font-size: 16px;
+  font-weight: 600;
+  line-height: 1.75;
+}
+
+.client-update-link-button {
+  align-self: flex-start;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  min-height: 36px;
+  padding: 0 0 2px;
+  border: 0;
+  border-bottom: 2px solid rgba(22, 119, 255, 0.28);
+  background: transparent;
+  color: #1677ff;
+  cursor: pointer;
+  font-size: 15px;
+  font-weight: 800;
+  transition:
+    border-color 0.2s ease,
+    color 0.2s ease,
+    opacity 0.2s ease;
+}
+
+.client-update-link-button:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.client-update-link-button:not(:disabled):hover {
+  border-color: #1677ff;
+  color: #0958d9;
+}
+
+.client-update-progress {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.client-update-progress__meta {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  color: #64748b;
+  font-size: 13px;
+}
+
+.client-update-progress__meta strong {
+  min-width: 0;
+  color: #334155;
+  font-size: 13px;
+  font-weight: 800;
+}
+
+.client-update-progress__meta span {
+  color: #1677ff;
+  font-weight: 800;
+}
+
+.client-update-progress__bar {
+  height: 8px;
+  overflow: hidden;
+  border-radius: 999px;
+  background: #eef2f7;
+}
+
+.client-update-progress__bar span {
+  display: block;
+  width: 0;
+  height: 100%;
+  border-radius: inherit;
+  background: #1677ff;
+  transition: width 0.2s ease;
+}
+
+.client-update-dialog__actions {
+  display: flex;
+  justify-content: flex-end;
+  align-items: center;
+  gap: 12px;
+}
+
+.client-update-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  min-width: 104px;
+  height: 40px;
+  padding: 0 18px;
+  border-radius: 8px;
+  cursor: pointer;
+  font-size: 15px;
+  font-weight: 800;
+  transition:
+    background 0.2s ease,
+    border-color 0.2s ease,
+    color 0.2s ease,
+    opacity 0.2s ease;
+}
+
+.client-update-button:disabled {
+  cursor: not-allowed;
+  opacity: 0.62;
+}
+
+.client-update-button--primary {
+  border: 1px solid #1677ff;
+  background: #1677ff;
+  color: #ffffff;
+}
+
+.client-update-button--primary:not(:disabled):hover {
+  background: #0958d9;
+  border-color: #0958d9;
+}
+
+.client-update-button--ghost {
+  border: 1px solid #dbe3ee;
+  background: #ffffff;
+  color: #475569;
+}
+
+.client-update-button--ghost:not(:disabled):hover {
+  border-color: #b6cff5;
+  color: #1677ff;
+  background: #f8fbff;
+}
+
 @media (max-width: 1080px) {
   .sidebar {
     width: 260px;

apps/desktop-client/src/renderer/composables/useClientRelease.ts

@@ -0,0 +1,194 @@
+import type {
+  DesktopClientReleaseCheckResponse,
+  DesktopClientUpdateProgressEvent,
+} from '@geo/shared-types'
+import { computed, readonly, ref } from 'vue'
+
+type CheckMode = 'manual' | 'silent'
+
+const release = ref<DesktopClientReleaseCheckResponse | null>(null)
+const loading = ref(false)
+const error = ref<string | null>(null)
+const lastCheckedAt = ref<number | null>(null)
+const updateProgress = ref<DesktopClientUpdateProgressEvent | null>(null)
+const updateError = ref<string | null>(null)
+const updateManualDownloadRequired = ref(false)
+const manualDownloadLoading = ref(false)
+let inFlight: Promise<DesktopClientReleaseCheckResponse | null> | null = null
+let updateInFlight: Promise<boolean> | null = null
+let progressListenerRegistered = false
+
+const MANUAL_DOWNLOAD_UPDATE_ERROR = '自动更新包校验失败，请前往官网下载最新版客户端'
+
+function normalizeReleaseError(err: unknown): string {
+  const message = err instanceof Error ? err.message : String(err)
+  if (message.includes('desktop_client_not_registered')) {
+    return '当前客户端尚未注册'
+  }
+  if (message.includes('desktop_client_release_not_configured')) {
+    return '暂未配置当前平台版本'
+  }
+  return message || '版本检查失败'
+}
+
+async function check(
+  mode: CheckMode = 'manual',
+): Promise<DesktopClientReleaseCheckResponse | null> {
+  if (inFlight) {
+    return inFlight
+  }
+
+  loading.value = true
+  if (mode === 'manual') {
+    error.value = null
+  }
+
+  inFlight = window.desktopBridge.app
+    .checkClientRelease()
+    .then((result) => {
+      release.value = result
+      error.value = null
+      lastCheckedAt.value = Date.now()
+      return result
+    })
+    .catch((err: unknown) => {
+      const message = normalizeReleaseError(err)
+      if (mode === 'manual') {
+        error.value = message
+      }
+      return null
+    })
+    .finally(() => {
+      loading.value = false
+      inFlight = null
+    })
+
+  return inFlight
+}
+
+function clearReleaseCheck(): void {
+  release.value = null
+  error.value = null
+  lastCheckedAt.value = null
+}
+
+function normalizeUpdateError(err: unknown): string {
+  const message = err instanceof Error ? err.message : String(err)
+  if (requiresManualDownload(message)) {
+    return MANUAL_DOWNLOAD_UPDATE_ERROR
+  }
+  if (message.includes('desktop_update_requires_packaged_app')) {
+    return '自动更新需要在打包后的客户端中执行'
+  }
+  if (message.includes('desktop_client_release_missing_sha256')) {
+    return '自动更新需要先配置安装包 SHA256'
+  }
+  if (message.includes('desktop_client_update_package_not_supported')) {
+    return '当前安装包格式不支持自动更新'
+  }
+  return message || '自动更新失败'
+}
+
+function requiresManualDownload(message: string): boolean {
+  return (
+    message.includes('desktop_client_update_signature_validation_failed') ||
+    message.includes('Code signature') ||
+    message.includes('did not pass validation') ||
+    message.includes('代码未能满足指定的代码要求')
+  )
+}
+
+function ensureProgressListener(): void {
+  if (progressListenerRegistered) {
+    return
+  }
+  progressListenerRegistered = true
+  window.desktopBridge.app.onClientUpdateProgress((event) => {
+    updateProgress.value = event
+    if (event.stage === 'error') {
+      const message = event.message ?? '自动更新失败'
+      updateManualDownloadRequired.value = requiresManualDownload(message)
+      updateError.value = normalizeUpdateError(message)
+    }
+  })
+}
+
+async function startUpdate(): Promise<boolean> {
+  ensureProgressListener()
+  if (updateInFlight) {
+    return updateInFlight
+  }
+  updateError.value = null
+  updateManualDownloadRequired.value = false
+  updateProgress.value = {
+    stage: 'checking',
+    percent: null,
+    transferred: null,
+    total: null,
+    bytesPerSecond: null,
+    version: release.value?.latest_version ?? null,
+  }
+
+  updateInFlight = window.desktopBridge.app
+    .startClientUpdate()
+    .then((result) => result.update_available)
+    .catch((err: unknown) => {
+      const message = err instanceof Error ? err.message : String(err)
+      updateManualDownloadRequired.value = requiresManualDownload(message)
+      updateError.value = normalizeUpdateError(err)
+      return false
+    })
+    .finally(() => {
+      updateInFlight = null
+    })
+
+  return updateInFlight
+}
+
+async function openManualDownload(): Promise<boolean> {
+  if (manualDownloadLoading.value) {
+    return false
+  }
+  manualDownloadLoading.value = true
+  try {
+    const result = await window.desktopBridge.app.clientReleaseDownloadURL()
+    if (!result.download_url) {
+      updateError.value = '暂未配置官网下载地址'
+      return false
+    }
+    await window.desktopBridge.app.openExternalUrl(result.download_url)
+    return true
+  } catch (err: unknown) {
+    updateError.value = normalizeReleaseError(err)
+    return false
+  } finally {
+    manualDownloadLoading.value = false
+  }
+}
+
+export function useClientRelease() {
+  ensureProgressListener()
+  return {
+    release: readonly(release),
+    loading: readonly(loading),
+    error: readonly(error),
+    lastCheckedAt: readonly(lastCheckedAt),
+    updateProgress: readonly(updateProgress),
+    updateError: readonly(updateError),
+    updateManualDownloadRequired: readonly(updateManualDownloadRequired),
+    manualDownloadLoading: readonly(manualDownloadLoading),
+    updateAvailable: computed(() => release.value?.update_available === true),
+    forceUpdate: computed(() => release.value?.force_update === true),
+    updating: computed(
+      () =>
+        updateProgress.value?.stage === 'checking' ||
+        updateProgress.value?.stage === 'downloading' ||
+        updateProgress.value?.stage === 'downloaded' ||
+        updateProgress.value?.stage === 'installing',
+    ),
+    check,
+    startUpdate,
+    openManualDownload,
+    clearReleaseCheck,
+  }
+}

apps/desktop-client/src/renderer/composables/useDesktopSession.ts

@@ -479,12 +479,28 @@ async function registerPayload(
   device?: ResolvedDeviceInfo,
 ): Promise<DesktopClientRegisterRequest> {
   const resolvedDevice = device ?? (await resolveDeviceInfo())
+  const versionInfo = await resolveVersionInfo()
   return {
     client_id: await resolveDesktopClientID(user),
     device_name: resolvedDevice.device_name,
     os: resolvedDevice.os,
     cpu_arch: resolvedDevice.cpu_arch,
-    client_version: '0.1.0-dev',
+    client_version: versionInfo.version,
+    channel: versionInfo.channel,
+  }
+}
+
+async function resolveVersionInfo(): Promise<{ version: string; channel: string }> {
+  try {
+    const info = await window.desktopBridge?.app?.versionInfo?.()
+    if (info?.version && info.channel) {
+      return info
+    }
+  } catch (err) {
+    console.warn('[desktop-session] versionInfo bridge failed', err)
+  }
+  return {
+    version: '0.1.0',
     channel: 'dev',
   }
 }
@@ -519,6 +535,7 @@ function createPreviewUser(): UserInfo {
 async function createPreviewClient(): Promise<DesktopClientInfo> {
   const now = new Date().toISOString()
   const device = await resolveDeviceInfo()
+  const versionInfo = await resolveVersionInfo()
   return {
     id: 'preview-client',
     tenant_id: 0,
@@ -527,8 +544,8 @@ async function createPreviewClient(): Promise<DesktopClientInfo> {
     device_name: `Preview ${device.device_name}`,
     os: device.os,
     cpu_arch: device.cpu_arch,
-    client_version: '0.1.0-preview',
-    channel: 'dev',
+    client_version: versionInfo.version,
+    channel: versionInfo.channel,
     created_at: now,
     last_seen_at: now,
     last_rotated_at: now,

apps/desktop-client/src/renderer/env.d.ts

@@ -1,6 +1,9 @@
 import type {
   CreatePublishJobResponse,
   DesktopAccountInfo,
+  DesktopClientReleaseCheckResponse,
+  DesktopClientUpdateProgressEvent,
+  DesktopClientUpdateResult,
   DesktopClientRotateResponse,
   DesktopPublishTaskListResponse,
   DesktopRuntimeSessionSyncRequest,
@@ -36,6 +39,14 @@ declare global {
     desktopBridge: {
       app: {
         ping(): Promise<string>
+        versionInfo(): Promise<{
+          version: string
+          channel: string
+        }>
+        checkClientRelease(): Promise<DesktopClientReleaseCheckResponse>
+        clientReleaseDownloadURL(): Promise<{ download_url: string }>
+        quitApp(): Promise<null>
+        startClientUpdate(): Promise<DesktopClientUpdateResult>
         deviceInfo(): Promise<{
           device_name: string
           os: string
@@ -70,9 +81,7 @@ declare global {
         openSettingsWindow(): Promise<null>
         getAppSettings(): Promise<DesktopAppSettings>
         getLoginCredentials(): Promise<DesktopLoginCredentials | null>
-        saveLoginCredentials(
-          credentials: DesktopLoginCredentials,
-        ): Promise<DesktopLoginCredentials>
+        saveLoginCredentials(credentials: DesktopLoginCredentials): Promise<DesktopLoginCredentials>
         clearLoginCredentials(): Promise<null>
         setAppSetting(key: keyof DesktopAppSettings, value: boolean): Promise<DesktopAppSettings>
         syncRuntimeSession(session: DesktopRuntimeSessionSyncRequest | null): Promise<null>
@@ -94,6 +103,9 @@ declare global {
           }) => void,
         ): () => void
         onNetworkObserved(listener: (event: DesktopObservedRequest) => void): () => void
+        onClientUpdateProgress(
+          listener: (event: DesktopClientUpdateProgressEvent) => void,
+        ): () => void
       }
       workbenchNavigation: {
         getState(): Promise<WorkbenchNavigationState>

apps/desktop-client/src/renderer/views/SettingsView.vue

@@ -1,17 +1,36 @@
 <script setup lang="ts">
 import {
+  DownloadOutlined,
   InfoCircleOutlined,
   LoginOutlined,
   SlidersOutlined,
+  SyncOutlined,
   ToolOutlined,
 } from '@ant-design/icons-vue'
 import { computed, onMounted, ref, watch } from 'vue'
 
+import { useClientRelease } from '../composables/useClientRelease'
 import { useDesktopRuntime } from '../composables/useDesktopRuntime'
 import { DEFAULT_API_BASE_URL, useDesktopSession } from '../composables/useDesktopSession'
 
 const { snapshot } = useDesktopRuntime()
 const { apiBaseURL, setApiBaseURL } = useDesktopSession()
+const {
+  release: clientRelease,
+  loading: releaseLoading,
+  error: releaseError,
+  lastCheckedAt,
+  updateProgress,
+  updateError,
+  updateManualDownloadRequired,
+  manualDownloadLoading,
+  updateAvailable,
+  forceUpdate,
+  updating,
+  check: checkClientRelease,
+  startUpdate: startClientUpdate,
+  openManualDownload,
+} = useClientRelease()
 
 type SectionKey =
   | 'general'
@@ -54,6 +73,75 @@ const subsystemEntries = computed(() =>
 )
 
 const appVersion = computed(() => snapshot.value?.app.version ?? '0.1.0')
+const releaseCheckedAtLabel = computed(() => {
+  if (!lastCheckedAt.value) {
+    return ''
+  }
+  return new Date(lastCheckedAt.value).toLocaleString('zh-CN', {
+    hour12: false,
+  })
+})
+const releaseStateLabel = computed(() => {
+  if (releaseLoading.value) {
+    return '检查中'
+  }
+  if (releaseError.value) {
+    return '检查失败'
+  }
+  if (!clientRelease.value) {
+    return '未检查'
+  }
+  if (updateAvailable.value) {
+    return forceUpdate.value ? '必须更新' : '发现新版本'
+  }
+  return '已是最新'
+})
+const releaseDetail = computed(() => {
+  if (releaseError.value) {
+    return releaseError.value
+  }
+  if (!clientRelease.value) {
+    return '当前版本会按平台、架构和渠道匹配运营端配置'
+  }
+  if (updateAvailable.value) {
+    return `最新版本 ${clientRelease.value.latest_version}`
+  }
+  return `当前版本 ${clientRelease.value.current_version}`
+})
+const releaseSourceLabel = computed(() => {
+  if (!clientRelease.value) {
+    return ''
+  }
+  return clientRelease.value.download_source === 'oss' ? 'OSS 自动地址' : '自定义地址'
+})
+const updateProgressPercent = computed(() => {
+  const percent = updateProgress.value?.percent
+  if (typeof percent !== 'number' || !Number.isFinite(percent)) {
+    return null
+  }
+  return Math.max(0, Math.min(100, Math.round(percent)))
+})
+const updateProgressLabel = computed(() => {
+  if (updateError.value) {
+    return updateError.value
+  }
+  switch (updateProgress.value?.stage) {
+    case 'checking':
+      return '正在准备更新'
+    case 'downloading':
+      return updateProgressPercent.value === null
+        ? '正在下载更新'
+        : `正在下载 ${updateProgressPercent.value}%`
+    case 'downloaded':
+      return '下载完成，准备安装'
+    case 'installing':
+      return '正在重启安装'
+    case 'not-available':
+      return '当前已是最新版本'
+    default:
+      return ''
+  }
+})
 const hasServerSettingChanged = computed(
   () => normalizeServerURLInput(serverBaseURL.value) !== apiBaseURL.value,
 )
@@ -86,6 +174,21 @@ function openServiceTerms() {
   void window.desktopBridge.app.openExternalUrl('https://shengxintui.com/terms')
 }
 
+function checkReleaseManually() {
+  void checkClientRelease('manual')
+}
+
+async function openReleaseDownload() {
+  if (!clientRelease.value?.update_available) {
+    return
+  }
+  await startClientUpdate()
+}
+
+async function openOfficialDownload() {
+  await openManualDownload()
+}
+
 function normalizeServerURLInput(value: string): string {
   return value.trim() || DEFAULT_API_BASE_URL
 }
@@ -155,6 +258,7 @@ async function toggleAppSetting(key: keyof DesktopAppSettings) {
 
 onMounted(() => {
   void loadAppSettings()
+  void checkClientRelease('silent')
 })
 
 watch(apiBaseURL, (next) => {
@@ -192,7 +296,61 @@ watch(apiBaseURL, (next) => {
               <span class="brand-ring"></span>
               <span class="brand-core"></span>
             </div>
-            <strong>版本: {{ appVersion }}</strong>
+            <div class="about-version-copy">
+              <span>当前版本</span>
+              <strong>{{ appVersion }}</strong>
+            </div>
+          </div>
+
+          <div class="release-check-card">
+            <div class="release-check-copy">
+              <span class="release-state" :class="{ 'is-update': updateAvailable }">
+                {{ releaseStateLabel }}
+              </span>
+              <strong>{{ releaseDetail }}</strong>
+              <p v-if="clientRelease">
+                {{ releaseSourceLabel }}
+                <span v-if="releaseCheckedAtLabel">· {{ releaseCheckedAtLabel }}</span>
+              </p>
+              <p v-else>检查服务端配置的最新客户端版本和下载地址</p>
+            </div>
+            <div class="release-check-actions">
+              <button
+                type="button"
+                class="server-button"
+                :disabled="releaseLoading"
+                @click="checkReleaseManually"
+              >
+                <SyncOutlined />
+                {{ releaseLoading ? '检查中' : '检查更新' }}
+              </button>
+              <button
+                v-if="clientRelease && updateAvailable"
+                type="button"
+                class="server-button server-button--primary"
+                :disabled="updating"
+                @click="openReleaseDownload"
+              >
+                <DownloadOutlined />
+                {{ updating ? '更新中' : '立即更新' }}
+              </button>
+              <button
+                v-if="clientRelease && updateAvailable && updateManualDownloadRequired"
+                type="button"
+                class="server-button"
+                :disabled="manualDownloadLoading"
+                @click="openOfficialDownload"
+              >
+                <DownloadOutlined />
+                {{ manualDownloadLoading ? '打开中' : '官网下载' }}
+              </button>
+            </div>
+            <div v-if="updateProgressLabel" class="release-update-progress">
+              <div class="release-update-progress__bar">
+                <span :style="{ width: `${updateProgressPercent ?? 12}%` }"></span>
+              </div>
+              <p>{{ updateProgressLabel }}</p>
+            </div>
           </div>
 
           <footer class="about-footer">
@@ -398,7 +556,7 @@ watch(apiBaseURL, (next) => {
 .settings-heading h1 {
   margin: 0;
   color: #000000;
-  font-size:22px;
+  font-size: 22px;
   font-weight: 900;
   line-height: 1;
 }
@@ -412,6 +570,9 @@ watch(apiBaseURL, (next) => {
 
 .about-page {
   position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
   min-height: 100%;
   padding: 28px 44px 108px;
 }
@@ -432,6 +593,19 @@ watch(apiBaseURL, (next) => {
   font-weight: 800;
 }
 
+.about-version-copy {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 5px;
+}
+
+.about-version-copy span {
+  color: #777777;
+  font-size: 13px;
+  font-weight: 700;
+}
+
 .about-logo {
   position: relative;
   display: grid;
@@ -460,6 +634,83 @@ watch(apiBaseURL, (next) => {
   box-shadow: 0 3px 8px rgba(22, 119, 255, 0.35);
 }
 
+.release-check-card {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 20px;
+  align-items: center;
+  padding: 22px 30px;
+  border-radius: 8px;
+  background: #ffffff;
+}
+
+.release-update-progress {
+  grid-column: 1 / -1;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.release-update-progress__bar {
+  height: 6px;
+  overflow: hidden;
+  border-radius: 999px;
+  background: #eeeeef;
+}
+
+.release-update-progress__bar span {
+  display: block;
+  width: 0;
+  height: 100%;
+  border-radius: inherit;
+  background: #1677ff;
+  transition: width 0.2s ease;
+}
+
+.release-update-progress p {
+  margin: 0;
+  color: #777777;
+  font-size: 12px;
+  font-weight: 700;
+}
+
+.release-check-copy {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 7px;
+}
+
+.release-state {
+  color: #777777;
+  font-size: 13px;
+  font-weight: 800;
+}
+
+.release-state.is-update {
+  color: #d93025;
+}
+
+.release-check-copy strong {
+  color: #070707;
+  font-size: 16px;
+  font-weight: 850;
+}
+
+.release-check-copy p {
+  margin: 0;
+  color: #777777;
+  font-size: 13px;
+  font-weight: 600;
+}
+
+.release-check-actions {
+  display: inline-flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  gap: 8px;
+}
+
 .about-footer {
   position: absolute;
   left: 0;
@@ -580,6 +831,10 @@ watch(apiBaseURL, (next) => {
 }
 
 .server-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
   height: 32px;
   padding: 0 14px;
   border: 0;
@@ -763,5 +1018,13 @@ watch(apiBaseURL, (next) => {
     grid-template-columns: 1fr;
     gap: 14px;
   }
+
+  .release-check-card {
+    grid-template-columns: 1fr;
+  }
+
+  .release-check-actions {
+    justify-content: flex-start;
+  }
 }
 </style>