@allbluecn/web-app 0.23.6 → 0.23.7

package/src/lib/auth/__tests__/page-gate.test.ts

@@ -1,5 +1,16 @@
-import { describe, expect, it } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { isRedirect } from '@tanstack/react-router'
+
+// 桌面判定双通道（SSR/服务端导航读 DEPLOY_TARGET，客户端导航读 desktopBridge
+// 运行时事实）：两者任一为真都不应把本地用户踢去 /login（桌面免登录 P0）
+const H = vi.hoisted(() => ({ desktopServer: false, desktopClient: false }))
+
+vi.mock('@/server/desktop-guest', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/server/desktop-guest')>()
+  return { ...actual, isDesktopServer: () => H.desktopServer }
+})
+vi.mock('@/lib/desktop-env', () => ({ isDesktopClient: () => H.desktopClient }))
+
 import { requireSessionPage } from '../page-gate'
 
 function makeArgs(session: { user?: { id?: string } } | null) {
@@ -10,6 +21,11 @@ function makeArgs(session: { user?: { id?: string } } | null) {
 }
 
 describe('requireSessionPage', () => {
+  beforeEach(() => {
+    H.desktopServer = false
+    H.desktopClient = false
+  })
+
   it('已登录放行（不抛错）', () => {
     expect(() => requireSessionPage(makeArgs({ user: { id: 'u1' } }))).not.toThrow()
   })
@@ -26,4 +42,24 @@ describe('requireSessionPage', () => {
     expect(options?.to).toBe('/login')
     expect(options?.search?.redirect).toBe('/settings/account')
   })
+
+  it('桌面（服务端 SSR：DEPLOY_TARGET=desktop）：未登录也放行', () => {
+    H.desktopServer = true
+    expect(() => requireSessionPage(makeArgs(null))).not.toThrow()
+  })
+
+  it('桌面（客户端导航：desktopBridge 在场）：未登录也放行', () => {
+    H.desktopClient = true
+    expect(() => requireSessionPage(makeArgs(null))).not.toThrow()
+  })
+
+  it('web（两通道都为假）：行为不变，未登录仍跳 /login', () => {
+    let caught: unknown
+    try {
+      requireSessionPage(makeArgs(null))
+    } catch (e) {
+      caught = e
+    }
+    expect(isRedirect(caught as never)).toBe(true)
+  })
 })

package/src/lib/auth/anonymous-safe.ts

@@ -1,4 +1,5 @@
 import type { AnyRouter } from '@tanstack/react-router'
+import { isDesktopClient } from '@/lib/desktop-env'
 
 const UNAUTHORIZED_NAME = 'UnauthorizedError'
 const UNAUTHORIZED_STATUS = 401
@@ -30,6 +31,10 @@ export function navigateToLoginOnUnauthorized(
   router: Pick<AnyRouter, 'state' | 'navigate'>,
 ): boolean {
   if (!isUnauthorizedError(error)) return false
+  // 桌面端免登录：401 不等于「需要登录」（本地 guest 已是合法身份；个别端点的
+  // 401 是数据/云态问题），自动跳登录会把用户从正在编辑的页面踢走。登录云端
+  // 由用户在 settings/sync 自主发起，本兜底在桌面壳内不动作。
+  if (isDesktopClient()) return false
   const loc = router.state.location
   router.navigate({
     to: '/login',

package/src/lib/auth/page-gate.ts

@@ -1,14 +1,24 @@
 import { redirect } from '@tanstack/react-router'
+import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 
 interface SessionLike {
   user?: { id?: string } | null
 }
 
-/** 「需登录页面」beforeLoad gate：未登录跳登录并携带回跳。直接用于路由 beforeLoad。 */
+/**
+ * 「需登录页面」beforeLoad gate：未登录跳登录并携带回跳。直接用于路由 beforeLoad。
+ *
+ * 桌面端（Electron + 本地 PGlite）免登录：guest 影子会话即合法本地身份，是否
+ * 登录云端由用户在 settings/sync 自主决定——一律放行，不自动踢 /login。
+ * 判定必须同时覆盖两种执行环境：SSR/服务端导航（isDesktopServer，读
+ * DEPLOY_TARGET）与客户端导航（isDesktopClient，读 desktopBridge 运行时事实）。
+ */
 export function requireSessionPage(args: {
   context: { session: SessionLike | null }
   location: { pathname: string; searchStr: string }
 }): void {
+  if (isDesktopServer() || isDesktopClient()) return
   if (!args.context.session?.user?.id) {
     throw redirect({
       to: '/login',

package/src/lib/changelog/sdk-versions.ts

@@ -112,7 +112,7 @@ export const SDK_GROUPS: SdkGroup[] = [
     "items": [
       {
         "name": "@allbluecn/web-app",
-        "version": "v0.23.6",
+        "version": "v0.23.7",
         "lastUpdate": "Nov 1, 2026",
         "source": "apps/web/package.json",
         "docsUrl": "https://github.com/allbluecn/allblue"

package/src/lib/desktop-env.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// 桌面端运行时判定（客户端安全）：Electron preload 注入的 window.desktopBridge
+// 是「当前页面确实跑在桌面壳里」的运行时事实。
+//
+// 为什么不能只用 isDesktopServer()：它读 process.env.DEPLOY_TARGET，只在
+// sidecar（Node 服务端）进程里成立。TanStack Router 的 beforeLoad 在**客户端
+// 导航时也会重跑**，浏览器上下文没有 DEPLOY_TARGET → false → requireSessionPage
+// 把桌面 guest 误判成「未登录」踢去 /login（桌面本地优先实测缺陷）。
+//
+// 为什么不用 isDesktopEdition()（VITE_DEPLOY_TARGET 构建期常量）：那是「构建
+// 目标」判定；Electron 壳以运行时 env 启动 sidecar 时 bundle 未必内联 desktop，
+// 会 false negative。桥对象的判定口径与 session-guard / sync-indicator /
+// cloud-login 一致（它们都以 getDesktopBridge() 为准）。
+//
+// SSR 恒 false（无 window）：服务端侧由 isDesktopServer() 覆盖，两者在
+// beforeLoad 里「服务端 SSR 放行 + 客户端导航放行」形成闭环，无 hydration 分叉。
+import { getDesktopBridge } from './desktop-bridge-types'
+
+/** 是否运行在桌面壳渲染进程（客户端）；SSR / 浏览器恒 false */
+export function isDesktopClient(): boolean {
+  return getDesktopBridge() !== null
+}

package/src/lib/desktop-logout.ts

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 桌面云态登出编排（桌面本地优先 P2-A9 反向转移，从 sidebar-03/user-menu.tsx
+// 抽出为可测纯编排：零 React / 零 i18n / 零 DOM 依赖，副作用全由调用方注入）。
+//
+// 编排顺序（裁定口径，改动需同步单测）：
+// ① 置转移锁（复用 bind 锁文件——引擎每 tick 判定同源，「转移进行中引擎勿 tick」；
+//   旧壳无此 IPC ⇒ lock 省略，视为置锁成功，锁为双保险）；
+// ② transfer（serverFn reverseTransferOwnershipFn：校验 remoteAuth/会话本人 →
+//   单事务 cloud→guest + outbox/row_state 同事务清空 + 重建 guest 行；事务提交后
+//   server 侧已清 remote-auth——崩窗口收敛）；
+// ③ 双会话清理：logoutRemote（幂等 re-clear remote-auth）+ clearCloudSession
+//   （清 cloud-session.json，引擎 guest 守卫回 idle）→ 解锁（先清云会话再解锁，
+//   引擎恢复 tick 前云会话已不可用）；
+// ④ clearQueries + 整页 reload（reload 后 getSessionFn 回落 guest 会话）。
+//
+// 失败路径（保持既有语义）：
+// - 置锁失败（抛错或 ok=false）：notify('failed') + 返回 lock-failed，不转移、不
+//   reload（留在云态，数据仍是云属主，可重试）；
+// - 转移失败：尽力解锁 + notify('failed') + 返回 transfer-failed，不清会话、不
+//   reload（单事务已回滚，重试幂等）；
+// - 会话清理/解锁失败：全部 best-effort 吞掉，**不阻塞** ④（云会话已由 serverFn
+//   侧清理，解锁抛错也不阻止 reload——reload 后引擎按 guest 守卫重新判定）。
+
+/** 用户可见提示事件（文案由调用方决定，本模块不持有 i18n） */
+export type DesktopLogoutNotice = 'in-progress' | 'failed'
+
+/** 编排终态：lock-failed / transfer-failed 表示留在云态（未 reload） */
+export type DesktopLogoutStatus = 'done' | 'lock-failed' | 'transfer-failed'
+
+export interface DesktopLogoutDeps {
+  /** 置转移锁（旧壳无 IPC ⇒ 省略 = 视为成功） */
+  lock?: () => Promise<{ ok: boolean; error?: string }>
+  /** 反向转移（失败必须抛出，单事务回滚语义由 serverFn 保证） */
+  transfer: (cloudUserId: string) => Promise<unknown>
+  /** 清 remote-auth（幂等 best-effort，失败不得阻塞后续） */
+  logoutRemote: () => Promise<unknown>
+  /** 清 cloud-session.json（旧壳无 IPC ⇒ 省略 = no-op） */
+  clearCloudSession?: () => Promise<unknown>
+  /** 解转移锁（失败不得阻塞后续） */
+  unlock?: () => Promise<unknown>
+  /** 清 react-query 缓存 */
+  clearQueries: () => void
+  /** 整页 reload */
+  reload: () => void
+  /** 提示回调（in-progress 在置锁前，failed 在失败路径） */
+  notify?: (notice: DesktopLogoutNotice) => void
+}
+
+/**
+ * 执行桌面云态登出编排。**调用方负责在桌面壳存在且无本地 authjs 会话时调用**
+ * （云态判别式），本地凭据登出仍走 signOut 链。
+ */
+export async function runDesktopLogout(
+  cloudUserId: string,
+  deps: DesktopLogoutDeps,
+): Promise<DesktopLogoutStatus> {
+  deps.notify?.('in-progress')
+
+  // ① 转移锁
+  let lockOk = true
+  if (deps.lock) {
+    try {
+      lockOk = (await deps.lock()).ok
+    } catch {
+      lockOk = false
+    }
+  }
+  if (!lockOk) {
+    deps.notify?.('failed')
+    return 'lock-failed'
+  }
+
+  // ② 反向转移（失败：单事务回滚留在云态，尽力解锁后可重试）
+  try {
+    await deps.transfer(cloudUserId)
+  } catch {
+    await bestEffort(deps.unlock)
+    deps.notify?.('failed')
+    return 'transfer-failed'
+  }
+
+  // ③ 双会话清理 + 解锁（全部尽力而为：serverFn 已清 remote-auth，此处兜底）
+  await bestEffort(deps.logoutRemote)
+  await bestEffort(deps.clearCloudSession)
+  await bestEffort(deps.unlock)
+
+  // ④ 缓存清空 + 整页刷新（reload 后 desktop-state 回 guest）
+  deps.clearQueries()
+  deps.reload()
+  return 'done'
+}
+
+/** best-effort：缺省跳过、抛错吞掉（失败路径不得阻塞主流程） */
+async function bestEffort(action?: () => Promise<unknown>): Promise<void> {
+  if (!action) return
+  try {
+    await action()
+  } catch {
+    /* 尽力而为 */
+  }
+}

package/src/lib/session.ts

@@ -22,6 +22,11 @@ import { getAuthConfig } from './auth/auth.config'
 // desktop-session-merge 为纯数据组装 + remote-auth 纯 fs 读取（node:fs +
 // env 守卫），无 prisma/server 重依赖链，客户端/云端部署零副作用。
 import { getDesktopRemoteSession } from '@/server/desktop-session-merge'
+// 桌面免登录（本地优先 P0 修复）：guest 影子身份是本地合法身份，必须在**鉴权
+// 单点**生效——requireAuth / server seam / 各 serverFn 的软鉴权（getAccountTeamFn、
+// design/detail 等）全部复用本函数，只在这里补一次即可让全站口径一致；否则
+// 这些端点把 guest 判成未登录，路由 beforeLoad 收到 unauthorized 后踢 /login。
+import { buildGuestSession, isDesktopServer } from '@/server/desktop-guest'
 
 export type SessionUser = NonNullable<AuthSession['user']> & {
   id?: string
@@ -43,6 +48,51 @@ export type SessionUser = NonNullable<AuthSession['user']> & {
 
 export type Session = Omit<AuthSession, 'user'> & { user?: SessionUser | null }
 
+/** desktop guest 降级的 warn-once 标记（进程级；沿用 requireAuth 的排查线索语义：
+ *  桌面单机 guest 合法，但服务器部署误设 DEPLOY_TARGET=desktop 时匿名请求会变成
+ *  共享 guest 身份（fail-open）——至少留一条日志） */
+let warnedDesktopGuest = false
+
+/** fail-open 安全自检的 warn/error-once 标记（进程级） */
+let warnedDesktopSecurity = false
+
+/**
+ * 桌面回落入口的安全自检（进程级一次）。
+ *
+ * `DEPLOY_TARGET=desktop` 在本仓是**安全边界**而不只是功能开关：它让匿名请求
+ * 变成共享的本地 guest 身份（AI / SSE / anyhub 文件代理等全部 getCurrentSession
+ * 消费点一起生效）。真正的桌面后端由 Electron 主进程注入 `DESKTOP_USER_DATA_DIR`
+ * （PGlite 数据目录 + remote-auth.json 的根）——该 env 缺失而 DEPLOY_TARGET 仍是
+ * desktop，最可能的解释是「云部署误设了 DEPLOY_TARGET」。
+ *
+ * 当前口径：**只 console.error 告警，不硬失败**（开发/测试也放行）。生产环境是否
+ * 直接拒绝启动/拒绝 guest 回落由控制者另行裁决；在此之前保留可用的同时留下显眼
+ * 线索。硬失败点应加在本函数之后（返回 guest 之前）。
+ */
+function checkDesktopFallbackEnvOnce(): void {
+  if (warnedDesktopSecurity) return
+  warnedDesktopSecurity = true
+  if (process.env.DESKTOP_USER_DATA_DIR) return
+  console.error(
+    '[session] 安全告警：DEPLOY_TARGET=desktop 但未设置 DESKTOP_USER_DATA_DIR。\n' +
+      '  DEPLOY_TARGET=desktop 是安全边界：匿名请求会被当作本地 guest 身份（AI / SSE / 文件代理等全部放行）。\n' +
+      '  若非桌面单机部署，请立即移除 DEPLOY_TARGET=desktop 以恢复鉴权；\n' +
+      '  桌面壳会由 Electron 主进程注入 DESKTOP_USER_DATA_DIR（PGlite 目录 / remote-auth.json 根）。',
+  )
+}
+
+function guestSession() {
+  checkDesktopFallbackEnvOnce()
+  if (!warnedDesktopGuest) {
+    warnedDesktopGuest = true
+    console.warn(
+      '[session] DEPLOY_TARGET=desktop：无会话请求已回落到本地 guest 身份。' +
+        '若这是服务器/云端部署，请移除 DEPLOY_TARGET=desktop 以恢复鉴权。',
+    )
+  }
+  return buildGuestSession()
+}
+
 export async function getCurrentSession(request?: Request): Promise<Session | null> {
   if (!request) return null
   try {
@@ -56,12 +106,32 @@ export async function getCurrentSession(request?: Request): Promise<Session | nu
     // 604 处自动受益；非 desktop 恒 null（desktop 判定先于 fs 读取，零 IO）。
     const remoteSession = await getDesktopRemoteSession()
     if (remoteSession) return remoteSession
+    // 桌面免登录（本地优先 P0）：既无 cloud 身份也未登录时，guest 影子用户即
+    // 本机当前用户（与 getSessionFn / requireAuth 的 guest 分支同一身份）。
+    // 放在本单点而非各端点：否则 account-team / design-detail 等「软鉴权」端点
+    // 把 guest 判成未登录 → beforeLoad unauthorized → 自动跳 /login（实测 P0）。
+    if (isDesktopServer()) return guestSession()
     return session
   } catch (error) {
     // JWT 解密失败（AUTH_SECRET 轮换 / 跨应用同名 cookie 污染）等效于无 session：
     // 返回 null 走未登录分支；@auth/core 会自行清理坏 cookie。
     // 不兜底时 JWTSessionError 会炸穿所有未捕获的调用点（route beforeLoad / serverFn）。
     console.warn('[session] 读取 session 失败（坏 cookie 或 auth 配置异常），降级为未登录:', error instanceof Error ? error.message : error)
+    // 桌面端不存在「未登录」态：坏 cookie / 鉴权配置异常不得让本地用户掉线
+    // （否则首屏 session 为 null → 页面守卫与控制台全是登录引导）。
+    //
+    // 但「authjs 抛错」≠「本机无身份」：桌面 cloud 态的真身份在 remote-auth.json，
+    // 必须先试云身份再回落 guest——直接回 guest 会让云账号用户看起来「数据全空」，
+    // 期间写入还会落到 local-guest 属主（数据错主，后续反向转移也救不回来）。
+    if (isDesktopServer()) {
+      try {
+        const remoteSession = await getDesktopRemoteSession()
+        if (remoteSession) return remoteSession
+      } catch (remoteError) {
+        console.warn('[session] 桌面云身份回落失败，降级本地 guest:', remoteError instanceof Error ? remoteError.message : remoteError)
+      }
+      return guestSession()
+    }
     return null
   }
 }

package/src/routes/__tests__/-edition-routing.test.tsx

@@ -15,7 +15,7 @@ async function importIndexRoute(profileId: 'oss' | 'saas', desktop = false) {
   return import('../_public/index/route')
 }
 
-async function importNavRoute(opts: { profileId: 'oss' | 'saas'; desktop: boolean }) {
+async function importNavRoute(opts: { profileId: 'oss' | 'saas'; desktop: boolean; desktopClient?: boolean }) {
   vi.resetModules()
   vi.doMock('@/plugins/modules.gen', () => ({ profileId: opts.profileId }))
   // 部分 mock：保留真实 GUEST_USER_ID 等导出——source-mode 键隔离引入了
@@ -24,6 +24,9 @@ async function importNavRoute(opts: { profileId: 'oss' | 'saas'; desktop: boolea
     const actual = await importOriginal<typeof import('@/server/desktop-guest')>()
     return { ...actual, isDesktopServer: () => opts.desktop }
   })
+  // 客户端导航判定（desktopBridge 运行时事实）：桌面壳里 process.env 无
+  // DEPLOY_TARGET，仅靠 isDesktopServer 会在浏览器 side 失守
+  vi.doMock('@/lib/desktop-env', () => ({ isDesktopClient: () => opts.desktopClient === true }))
   return import('../_nav/route')
 }
 
@@ -115,6 +118,13 @@ describe('_nav beforeLoad', () => {
       catchRedirect(() => Route.options.beforeLoad!({ context: { session: null }, location } as never)),
     ).toBeNull()
   })
+
+  it('桌面客户端导航（无 DEPLOY_TARGET，desktopBridge 在场）：同样无条件放行', async () => {
+    const { Route } = await importNavRoute({ profileId: 'saas', desktop: false, desktopClient: true })
+    expect(
+      catchRedirect(() => Route.options.beforeLoad!({ context: { session: null }, location } as never)),
+    ).toBeNull()
+  })
 })
 
 describe('GlobalErrorBoundary', () => {
@@ -146,11 +156,17 @@ describe('GlobalErrorBoundary', () => {
 })
 
 describe('需登录页面 gate', () => {
-  it.each([
-    ['../_nav/settings/route', '/settings/general'],
-    ['../_nav/notifications/route', '/notifications'],
-    ['../_nav/workspaces/route', '/workspaces'],
-  ])('%s 未登录跳 /login', async (mod, pathname) => {
+  // 本 describe 的桌面判定统一钉死（前面的 importNavRoute 会注册 doMock，
+  // vi.doMock 跨 resetModules 持久，不显式覆盖会串味）
+  async function mockDesktop(opts: { desktopServer: boolean; desktopClient: boolean }) {
+    vi.doMock('@/server/desktop-guest', async (importOriginal) => {
+      const actual = await importOriginal<typeof import('@/server/desktop-guest')>()
+      return { ...actual, isDesktopServer: () => opts.desktopServer }
+    })
+    vi.doMock('@/lib/desktop-env', () => ({ isDesktopClient: () => opts.desktopClient }))
+  }
+
+  async function prepareRoute(mod: string, desktop: { desktopServer: boolean; desktopClient: boolean }) {
     vi.resetModules()
     vi.doMock('@/plugins/modules.gen', () => ({ profileId: 'oss' }))
     vi.doMock('@/lib/i18n/server', () => ({ createServerI18n: () => ({ t: (k: string) => k }) }))
@@ -162,7 +178,16 @@ describe('需登录页面 gate', () => {
       NOTIFICATION_LIST_KEY: ['notifications', 'list'],
       NOTIFICATION_UNREAD_KEY: ['notifications', 'unread'],
     }))
-    const { Route } = await import(mod)
+    await mockDesktop(desktop)
+    return import(mod)
+  }
+
+  it.each([
+    ['../_nav/settings/route', '/settings/general'],
+    ['../_nav/notifications/route', '/notifications'],
+    ['../_nav/workspaces/route', '/workspaces'],
+  ])('%s 未登录跳 /login', async (mod, pathname) => {
+    const { Route } = await prepareRoute(mod, { desktopServer: false, desktopClient: false })
     const r = catchRedirect(() =>
       Route.options.beforeLoad!({
         context: { session: null },
@@ -172,4 +197,20 @@ describe('需登录页面 gate', () => {
     expect(r?.to).toBe('/login')
     expect(r?.search?.redirect).toBe(pathname)
   })
+
+  it.each([
+    ['../_nav/settings/route', '/settings/general'],
+    ['../_nav/notifications/route', '/notifications'],
+    ['../_nav/workspaces/route', '/workspaces'],
+  ])('%s 桌面客户端（desktopBridge 在场）未登录也放行', async (mod, pathname) => {
+    const { Route } = await prepareRoute(mod, { desktopServer: false, desktopClient: true })
+    expect(
+      catchRedirect(() =>
+        Route.options.beforeLoad!({
+          context: { session: null },
+          location: { pathname, searchStr: '' },
+        } as never),
+      ),
+    ).toBeNull()
+  })
 })

package/src/routes/__tests__/-login-admin-redirect.test.ts

@@ -0,0 +1,99 @@
+// 桌面端登录页不得跳管理后台 setup（实测 P0：打开 /login 被重定向到
+// http://localhost:3001/setup）。桌面没有管理员概念（本地 guest + 云端账号），
+// 该跳转是 admin 应用首启向导的死链。
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+const H = vi.hoisted(() => ({
+  checkAdminExists: vi.fn(async () => ({ hasAdmin: false })),
+  desktopServer: true,
+  desktopClient: false,
+}))
+
+vi.mock('@/server/serverFns/auth/setup', () => ({
+  checkAdminExistsFn: () => H.checkAdminExists(),
+}))
+// 登录页 loader 依赖：无需真实 provider 解析（会触 prisma）
+vi.mock('@/server/serverFns/auth/providers', () => ({
+  getAuthProviders: vi.fn(async () => ({ googleEnabled: false })),
+}))
+
+async function importLoginRoute(opts: { desktopServer?: boolean; desktopClient?: boolean } = {}) {
+  vi.resetModules()
+  H.desktopServer = opts.desktopServer ?? false
+  H.desktopClient = opts.desktopClient ?? false
+  vi.doMock('@/server/desktop-guest', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@/server/desktop-guest')>()
+    return { ...actual, isDesktopServer: () => H.desktopServer }
+  })
+  // 客户端导航通道（desktopBridge 运行时事实）：beforeLoad 在浏览器重跑时
+  // process.env.DEPLOY_TARGET 不存在，只有这一条能挡住 admin setup 跳转
+  vi.doMock('@/lib/desktop-env', () => ({ isDesktopClient: () => H.desktopClient }))
+  return import('../_login/login/route')
+}
+
+/** 跑 async beforeLoad，返回 redirect 目标（无跳转 → null） */
+async function runBeforeLoad(
+  Route: Awaited<ReturnType<typeof importLoginRoute>>['Route'],
+): Promise<{ href?: string; to?: string } | null> {
+  try {
+    await (Route.options.beforeLoad as unknown as (ctx: unknown) => Promise<void>)({})
+    return null
+  } catch (e) {
+    return (e as { options?: { href?: string; to?: string } }).options ?? {}
+  }
+}
+
+describe('/login beforeLoad 的 admin 首启向导跳转', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.clearAllMocks()
+  })
+
+  it('桌面端（服务端 SSR）：hasAdmin=false 也不跳 setup（且不发起 admin 检测 RPC）', async () => {
+    H.checkAdminExists.mockResolvedValue({ hasAdmin: false })
+    vi.stubEnv('ADMIN_URL', 'http://admin.example:9999')
+
+    const { Route } = await importLoginRoute({ desktopServer: true })
+    const redirectTarget = await runBeforeLoad(Route)
+
+    expect(redirectTarget).toBeNull()
+    expect(H.checkAdminExists).not.toHaveBeenCalled()
+  })
+
+  it('桌面端（客户端导航：仅 desktopBridge 在场、无 DEPLOY_TARGET）同样不跳 setup', async () => {
+    // K1：beforeLoad 会在浏览器重跑，此时 isDesktopServer 为 false——只靠服务端
+    // 通道会让「本地会话退出 / 注册重置回跳 / 错误页登录链接」再次被送去 setup
+    H.checkAdminExists.mockResolvedValue({ hasAdmin: false })
+    vi.stubEnv('ADMIN_URL', 'http://admin.example:9999')
+
+    const { Route } = await importLoginRoute({ desktopServer: false, desktopClient: true })
+    const redirectTarget = await runBeforeLoad(Route)
+
+    expect(redirectTarget).toBeNull()
+    expect(H.checkAdminExists).not.toHaveBeenCalled()
+  })
+
+  it('web 端：hasAdmin=false 仍跳 ADMIN_URL/setup（既有行为不回归）', async () => {
+    H.checkAdminExists.mockResolvedValue({ hasAdmin: false })
+    vi.stubEnv('ADMIN_URL', 'http://admin.example:9999')
+
+    const { Route } = await importLoginRoute()
+    const redirectTarget = await runBeforeLoad(Route)
+
+    expect(redirectTarget?.href).toBe('http://admin.example:9999/setup')
+  })
+
+  it('web 端：admin 已初始化则放行', async () => {
+    H.checkAdminExists.mockResolvedValue({ hasAdmin: true })
+
+    const { Route } = await importLoginRoute()
+    expect(await runBeforeLoad(Route)).toBeNull()
+  })
+
+  it('web 端：admin 检测失败（RPC 抛错）时放行不阻断登录', async () => {
+    H.checkAdminExists.mockRejectedValue(new Error('rpc down'))
+
+    const { Route } = await importLoginRoute()
+    expect(await runBeforeLoad(Route)).toBeNull()
+  })
+})

package/src/routes/_login/login/route.tsx

@@ -19,6 +19,8 @@ import { createFileRoute, redirect } from '@tanstack/react-router'
 import { z } from 'zod'
 import { getAuthProviders } from '@/server/serverFns/auth/providers'
 import { checkAdminExistsFn } from '@/server/serverFns/auth/setup'
+import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 
 export const Route = createFileRoute('/_login/login')({
   validateSearch: z.object({
@@ -28,9 +30,22 @@ export const Route = createFileRoute('/_login/login')({
     ssoError: z.string().optional(),
   }),
   beforeLoad: async () => {
-    // env 读取必须在 beforeLoad 内（服务端执行）：路由模块会被客户端加载，
-    // 顶层读 process.env 在浏览器 chunk 求值时直接 ReferenceError
-    const adminUrl = process.env.ADMIN_URL || 'http://localhost:3001'
+    // 桌面端（Electron + 本地 PGlite）没有「管理员/首启向导」概念：本地是
+    // guest 影子身份、云端账号经 settings/sync 的 DesktopCloudLogin 激活。
+    // /setup 是 admin 应用（默认 localhost:3001）的首启向导，桌面壳里既没有
+    // 该服务、也没有可初始化超管，跳过去必是死链/连接失败（实测 P0：打开
+    // /login 直接被重定向到 http://localhost:3001/setup）。
+    //
+    // 判定必须双通道：beforeLoad 会在**客户端导航时重跑**，浏览器里
+    // process.env.DEPLOY_TARGET 不存在（isDesktopServer 为 false），只有
+    // desktopBridge 运行时事实（isDesktopClient）能挡住——否则从本地凭据退出、
+    // 注册/重置成功回跳、错误页/邀请页的登录链接都会再次被送去 admin setup。
+    if (isDesktopServer() || isDesktopClient()) return
+    // 以下只在非桌面路径求值：桌面在上一行已返回，不会读 env、也不会发 RPC。
+    // env 读取必须留在 beforeLoad 内（不能提到模块顶层：路由模块会被客户端加载，
+    // 顶层读 process.env 在浏览器 chunk 求值时直接 ReferenceError）；此处再补
+    // typeof 守卫，防非桌面客户端导航时浏览器无 Node process。
+    const adminUrl = (typeof process !== 'undefined' ? process.env.ADMIN_URL : undefined) || 'http://localhost:3001'
     const result = await checkAdminExistsFn().catch(() => null)
     if (result?.hasAdmin === false) {
       throw redirect({ href: `${adminUrl}/setup` })

package/src/routes/_nav/design/canvas/$id/route.tsx

@@ -17,12 +17,17 @@
 
 import { createFileRoute, notFound, redirect } from '@tanstack/react-router'
 import { getDesignDetailFn } from '@/server/serverFns/design/detail'
+import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 
 export const Route = createFileRoute('/_nav/design/canvas/$id')({
   beforeLoad: async (ctx) => {
     const id = ctx.params.id
     const result = await getDesignDetailFn({ data: { id } })
     if (result.error === 'unauthorized') {
+      // 桌面端免登录：不自动跳 /login（guest 已是本地身份，走到这里属异常态），
+      // 降级为 notFound 页，登录与否由用户自主决定
+      if (isDesktopServer() || isDesktopClient()) throw notFound()
       throw redirect({ to: '/login' })
     }
     if (result.error === 'not_found' || !result.prd) {

package/src/routes/_nav/knowledge/$kbId/route.tsx

@@ -17,6 +17,8 @@
 
 import { createFileRoute, redirect } from '@tanstack/react-router'
 import { getKnowledgeDetailFn, listDocumentsFn } from '@/server/serverFns/knowledge'
+import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 import { KnowledgeWorkspacePending } from './-components/knowledge-workspace-pending'
 
 export const Route = createFileRoute('/_nav/knowledge/$kbId')({
@@ -24,8 +26,10 @@ export const Route = createFileRoute('/_nav/knowledge/$kbId')({
   pendingComponent: KnowledgeWorkspacePending,
   beforeLoad: async ({ context, location, params }) => {
     // 会话守卫：ssr:false 路由的 beforeLoad 在客户端导航也会执行，
-    // 覆盖 _nav 守卫不重跑（父路由已匹配）时 session 过期的窗口
-    if (!context.session?.user?.id) {
+    // 覆盖 _nav 守卫不重跑（父路由已匹配）时 session 过期的窗口。
+    // 桌面端免登录（server/client 双判）：本地 guest 即身份，不自动跳 /login，
+    // 缺数据时降级为下方「知识库不存在」分支，登录由用户自主发起。
+    if (!context.session?.user?.id && !isDesktopServer() && !isDesktopClient()) {
       throw redirect({
         to: '/login',
         search: { redirect: location.pathname + location.searchStr },

package/src/routes/_nav/route.tsx

@@ -18,6 +18,7 @@
 import { createFileRoute } from '@tanstack/react-router'
 
 import { isDesktopServer } from '@/server/desktop-guest'
+import { isDesktopClient } from '@/lib/desktop-env'
 import { requireSessionPage } from '@/lib/auth/page-gate'
 import { listPinnedWorkspacesBriefFn } from '@/server/serverFns/workspace'
 import { listKnowledgeFn } from '@/server/serverFns/knowledge'
@@ -29,7 +30,10 @@ import { NavNotFound } from './-components/nav-not-found'
 
 export const Route = createFileRoute('/_nav')({
   beforeLoad: ({ context, location }) => {
-    if (isDesktopServer()) return
+    // 桌面端免登录：isDesktopServer 只在 SSR/sidecar 成立，客户端导航（beforeLoad
+    // 会在浏览器重跑）必须靠 desktopBridge 运行时事实判定，否则 guest 被误判
+    // 未登录踢去 /login（实测 P0；用户要求「不自动跳转登录，自主决定」）
+    if (isDesktopServer() || isDesktopClient()) return
     requireSessionPage({ context, location })
   },
   loader: async ({ context }) => {