@allbluecn/web-app 0.23.5 → 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.5",
+        "version": "v0.23.7",
         "lastUpdate": "Nov 1, 2026",
         "source": "apps/web/package.json",
         "docsUrl": "https://github.com/allbluecn/allblue"

package/src/lib/desktop-agent/__tests__/connection.test.ts

@@ -2,10 +2,12 @@
 // AllBlue - 理想之海
 // Copyright (C) 2026 AllBlue Contributors
 
-// desktop-agent 连接（桌面本地优先 P3-B5）：appInfo 调用时懒取 agentPort/agentToken
-// → 真实 fetchServerSentEvents 直连 http://127.0.0.1:{port}/prompt。fetch 打桩、
-// SSE 解析走真实 @tanstack/ai-client 实现——请求线格式即与 Pro 端点的跨仓契约：
-// URL / X-Desktop-Token / X-Run-Id 头 / forwardedProps.cwd（端点 extractCwd 取值位）。
+// desktop-agent 连接（桌面本地优先 P3-B5）：调用时懒取 agent 端点 → 真实
+// fetchServerSentEvents 直连 http://127.0.0.1:{port}/prompt。fetch 打桩、SSE 解析
+// 走真实 @tanstack/ai-client 实现——请求线格式即与 Pro 端点的跨仓契约：URL /
+// X-Desktop-Token / X-Run-Id 头 / forwardedProps.cwd（端点 extractCwd 取值位）。
+// 两种壳形态各覆盖：新壳经 agentCredentials 按需取凭据（appInfo.agentToken 恒 null，
+// 不参与连接），旧壳回落 appInfo 的 agentPort/agentToken。
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { UIMessage } from '@tanstack/ai-client'
 
@@ -18,7 +20,15 @@ type AppInfo = {
   agentToken?: string | null
 }
 
-const bridgeRef: { current: { appInfo: () => Promise<AppInfo> } | null } = { current: null }
+type AgentCredentials = { port: number; token: string }
+
+type Bridge = {
+  appInfo: () => Promise<AppInfo>
+  /** 新壳按需取凭据通道；旧壳无此方法（undefined） */
+  agentCredentials?: () => Promise<AgentCredentials | null>
+}
+
+const bridgeRef: { current: Bridge | null } = { current: null }
 
 vi.mock('@/lib/desktop-bridge-types', () => ({
   getDesktopBridge: () => bridgeRef.current,
@@ -36,6 +46,14 @@ function bridgeWith(info: Partial<AppInfo>) {
   return { appInfo: vi.fn(async () => ({ ...BASE_INFO, ...info })) }
 }
 
+/** 新壳桥：appInfo 里 agentPort 仍广播（门控用）、agentToken 恒 null；凭据走按需 IPC */
+function newShellBridge(credentials: AgentCredentials | null, info: Partial<AppInfo> = {}) {
+  return {
+    appInfo: vi.fn(async () => ({ ...BASE_INFO, agentPort: null, agentToken: null, ...info })),
+    agentCredentials: vi.fn(async () => credentials),
+  }
+}
+
 const encoder = new TextEncoder()
 function sse(event: Record<string, unknown>): Uint8Array {
   return encoder.encode(`data: ${JSON.stringify(event)}\n\n`)
@@ -119,6 +137,50 @@ describe('resolveDesktopAgentEndpoint（appInfo 懒取）', () => {
   })
 })
 
+describe('resolveDesktopAgentEndpoint（新壳 agentCredentials 优先 / 旧壳回落 appInfo）', () => {
+  it('新壳：用 agentCredentials 的 {port, token} 构造端点，不读 appInfo 的令牌', async () => {
+    // appInfo 故意给一个不同的端口 + 陈旧令牌：端点必须只来自 agentCredentials
+    const bridge = newShellBridge({ port: 2468, token: 'tok-cred' }, { agentPort: 4567, agentToken: 'ok' })
+    bridgeRef.current = bridge
+    await expect(resolveDesktopAgentEndpoint()).resolves.toEqual({
+      url: 'http://127.0.0.1:2468/prompt',
+      token: 'tok-cred',
+    })
+    expect(bridge.agentCredentials).toHaveBeenCalledTimes(1)
+    expect(bridge.appInfo).not.toHaveBeenCalled()
+  })
+
+  it('新壳：agentCredentials 返回 null（未装配）或抛错（IPC 断开）→ null，不回落 appInfo', async () => {
+    const bridge = newShellBridge(null)
+    bridgeRef.current = bridge
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+    expect(bridge.appInfo).not.toHaveBeenCalled()
+
+    bridgeRef.current = {
+      appInfo: vi.fn(async () => ({ ...BASE_INFO, agentPort: 4567, agentToken: null })),
+      agentCredentials: vi.fn(async () => {
+        throw new Error('ipc closed')
+      }),
+    }
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+  })
+
+  it('新壳：agentCredentials 产出的端口/令牌非法 → null（与 appInfo 路径同口径）', async () => {
+    bridgeRef.current = newShellBridge({ port: 0, token: 'tok' })
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+    bridgeRef.current = newShellBridge({ port: 4567, token: '' })
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+  })
+
+  it('旧壳（无 agentCredentials）→ 回落 appInfo 的 agentPort + agentToken', async () => {
+    bridgeRef.current = bridgeWith({ agentPort: 4567, agentToken: 'tok-abc' })
+    await expect(resolveDesktopAgentEndpoint()).resolves.toEqual({
+      url: 'http://127.0.0.1:4567/prompt',
+      token: 'tok-abc',
+    })
+  })
+})
+
 describe('createDesktopAgentConnection（fetchServerSentEvents 包装）', () => {
   it('端点不可用 → 抛 DesktopAgentUnavailableError，且不发起 fetch', async () => {
     const fetchMock = stubSseFetch(RUN_EVENTS)
@@ -173,6 +235,31 @@ describe('createDesktopAgentConnection（fetchServerSentEvents 包装）', () =>
     expect(body.messages).toEqual([expect.objectContaining({ role: 'user', content: '列出目录' })])
   })
 
+  it('新壳：URL / X-Desktop-Token 取自 agentCredentials（appInfo 的 agentToken 恒 null 不参与）', async () => {
+    const fetchMock = stubSseFetch(RUN_EVENTS)
+    const bridge = newShellBridge({ port: 2468, token: 'tok-cred' }, { agentPort: 4567, agentToken: null })
+    bridgeRef.current = bridge
+    await drain(
+      createDesktopAgentConnection().connect([USER_MESSAGE], undefined, undefined, { threadId: 't-1', runId: 'r-1' }),
+    )
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchMock.mock.calls[0]!
+    expect(url).toBe('http://127.0.0.1:2468/prompt')
+    expect((init?.headers as Record<string, string>)['X-Desktop-Token']).toBe('tok-cred')
+    // 每次 connect 都重新按需取一次凭据（backend 重启换端口/令牌后下一问即用新值）
+    expect(bridge.agentCredentials).toHaveBeenCalledTimes(1)
+    expect(bridge.appInfo).not.toHaveBeenCalled()
+  })
+
+  it('新壳未装配（agentCredentials → null）→ 抛 DesktopAgentUnavailableError，不发 fetch', async () => {
+    const fetchMock = stubSseFetch(RUN_EVENTS)
+    bridgeRef.current = newShellBridge(null)
+    await expect(
+      drain(createDesktopAgentConnection().connect([USER_MESSAGE], undefined, undefined, { threadId: 't', runId: 'r' })),
+    ).rejects.toBeInstanceOf(DesktopAgentUnavailableError)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
   it('SSE 帧原样产出为 AG-UI chunk（RUN_STARTED 起、RUN_FINISHED 止）', async () => {
     stubSseFetch(RUN_EVENTS)
     bridgeRef.current = bridgeWith({ agentPort: 4567, agentToken: 'tok-abc' })
@@ -191,7 +278,7 @@ describe('createDesktopAgentConnection（fetchServerSentEvents 包装）', () =>
     ])
   })
 
-  it('每次 connect 都重取 appInfo（backend 重启换端口/令牌后下一问即用新值）', async () => {
+  it('旧壳：每次 connect 都重取 appInfo（backend 重启换端口/令牌后下一问即用新值）', async () => {
     const fetchMock = stubSseFetch(RUN_EVENTS)
     const appInfo = vi
       .fn<() => Promise<AppInfo>>()

package/src/lib/desktop-agent/connection.ts

@@ -5,13 +5,18 @@
 // 本地文件助手的 agent 连接（桌面本地优先 P3-B5）：useChat 的 connection 适配。
 //
 // 端点 = Pro desktop 域 AgentService（B4）：backend utilityProcess 内 127.0.0.1
-// 随机端口 `POST /prompt`（AG-UI SSE），须带 `X-Desktop-Token`。端口与令牌经
-// desktopBridge.appInfo() 的 agentPort/agentToken 广播——backend 重启即换新值
-// （main 侧 backend exit 清空），所以**每次请求时懒取**，不在组件顶层静态拼 URL。
+// 随机端口 `POST /prompt`（AG-UI SSE），须带 `X-Desktop-Token`。端口与令牌经桌面桥
+// 取得，两种壳形态：
+// - 新壳：`desktopBridge.agentCredentials()` 按需 IPC 返回 { port, token }（令牌不再
+//   随 appInfo 常驻广播——常驻信息面会让任意 renderer JS（含 XSS）随时拿到令牌去读
+//   已授权目录；appInfo.agentToken 在新壳恒为 null 占位）。
+// - 旧壳（无 agentCredentials）：回落 `desktopBridge.appInfo()` 的 agentPort/agentToken。
+// backend 重启即换新值（main 侧 backend exit 清空），所以**每次请求时懒取**，不在组件
+// 顶层静态拼 URL。
 //
 // 为什么包一层而不是直接 fetchServerSentEvents(url, options)：其 url 参数只接受
 // 同步 getter，且在 connect() 内先于（可异步的）options 求值——URL 无法来自同一次
-// 调用里 await 的 appInfo。包装只做「await appInfo → 构造 fetchServerSentEvents →
+// 调用里 await 的桥调用。包装只做「await 桥 → 构造 fetchServerSentEvents →
 // 原样委托 connect」，SSE 解析/AG-UI 协议/abort 全部是官方实现，无自定义协议面。
 //
 // 请求线格式（与 Pro 端点的跨仓契约，见 agent-service.ts extractCwd/extractPrompt）：
@@ -28,8 +33,8 @@ export interface DesktopAgentEndpoint {
   token: string
 }
 
-/** agent 端点不可用：无桥（云 Web / OSS）、旧壳（appInfo 无 agent 字段）、或
- *  agent 未装配（DESKTOP_AGENT 门控未开 / bundle 装配失败 → agentPort null） */
+/** agent 端点不可用：无桥（云 Web / OSS）、旧壳（appInfo 无 agent 字段）、新壳未装配
+ *  （agentCredentials 返回 null）、或 DESKTOP_AGENT 门控未开 / bundle 装配失败 */
 export class DesktopAgentUnavailableError extends Error {
   constructor() {
     super('desktop agent endpoint unavailable')
@@ -37,20 +42,36 @@ export class DesktopAgentUnavailableError extends Error {
   }
 }
 
-/** 调用时读取当前 agent 端点；不可用返回 null（端口/令牌非法同样视为不可用，不拼坏 URL） */
+/** 端口合法性（1..65535 整数）：非法即「不可用」，不拼出坏 URL */
+function isValidAgentPort(port: unknown): port is number {
+  return typeof port === 'number' && Number.isInteger(port) && port >= 1 && port <= 65535
+}
+
+/** 由端口 + 令牌构造端点；任一非法返回 null（不吞半截凭据）。令牌空串按不可用处理
+ *  ——新壳 appInfo.agentToken 恒 null，回落路径若拿到空串说明壳未装配 */
+function buildEndpoint(port: unknown, token: unknown): DesktopAgentEndpoint | null {
+  if (!isValidAgentPort(port)) return null
+  if (typeof token !== 'string' || token === '') return null
+  return { url: `http://127.0.0.1:${port}/prompt`, token }
+}
+
+/** 调用时读取当前 agent 端点；不可用返回 null（端口/令牌非法同样视为不可用，不拼坏 URL）。
+ *  取端点优先 agentCredentials（新壳按需取凭证），旧壳回落 appInfo 的 agentPort/agentToken。 */
 export async function resolveDesktopAgentEndpoint(): Promise<DesktopAgentEndpoint | null> {
   const bridge = getDesktopBridge()
   if (!bridge) return null
-  // main 未就绪 / IPC 断开时 appInfo 会抛错：归「服务未就绪」（不可用 → 上层抛
-  // DesktopAgentUnavailableError），不把原生错误原文当「运行失败：<原文>」透出
+  // 新壳独占使用 agentCredentials：其存在即表示令牌不再经 appInfo 广播，回落拿到
+  // 的只会是恒 null 占位，无收益。IPC 断开/main 未就绪时抛错与 appInfo 同口径归
+  // 「服务未就绪」（不可用），不把原生错误原文透出成「运行失败：<原文>」
+  if (typeof bridge.agentCredentials === 'function') {
+    const credentials = await bridge.agentCredentials().catch(() => null)
+    if (!credentials) return null
+    return buildEndpoint(credentials.port, credentials.token)
+  }
+  // 旧壳：端口/令牌同随 appInfo 广播
   const info = await bridge.appInfo().catch(() => null)
   if (!info) return null
-  const { agentPort, agentToken } = info
-  if (typeof agentPort !== 'number' || !Number.isInteger(agentPort) || agentPort < 1 || agentPort > 65535) {
-    return null
-  }
-  if (typeof agentToken !== 'string' || agentToken === '') return null
-  return { url: `http://127.0.0.1:${agentPort}/prompt`, token: agentToken }
+  return buildEndpoint(info.agentPort, info.agentToken)
 }
 
 /**

package/src/lib/desktop-bridge-types.ts

@@ -9,15 +9,26 @@ export interface DesktopBridgeApi {
    *  字段）：backend utilityProcess 装配 AgentService 后随 appInfo 广播——
    *  agentPort = 127.0.0.1 随机端口，agentToken = 启动时生成的访问令牌
    *  （请求须带 X-Desktop-Token 头）。null = agent 未装配（旧壳，或 DESKTOP_AGENT
-   *  门控未开/bundle 装配失败降级），renderer 据此隐藏 agent 入口。 */
+   *  门控未开/bundle 装配失败降级），renderer 据此隐藏 agent 入口。
+   *  ⚠ agentToken 仅旧壳有值：新壳把它移出 appInfo 常驻广播（任意 renderer JS
+   *  含 XSS 都能随时取到令牌去读已授权目录），改由 agentCredentials 按需取一次，
+   *  保留下来的该字段**恒为 null（纯兼容占位，勿再消费）**。agentPort 仍随
+   *  appInfo 广播（仅端口、不可用于取文件，供入口门控）。 */
   appInfo: () => Promise<{
     version: string
     clientId: string
     platform: string
     backendPort: number | null
     agentPort?: number | null
+    /** @deprecated 新壳恒 null（令牌不再广播）；请改用 agentCredentials() */
     agentToken?: string | null
   }>
+  /** 本地文件助手 agent 凭据按需获取（Pro 侧新增 IPC `desktopBridge:agentCredentials`）：
+   *  仅在建立 agent 连接时调用一次，返回 { port, token }（port = 127.0.0.1 随机端口，
+   *  token = 请求头 X-Desktop-Token 的值）；agent 未装配 → null。与 appInfo 不同，
+   *  本方法**不是**常驻可查询的信息面，令牌不进入任何长期可读的全局面。
+   *  旧壳无此方法 → undefined，调用方回落到 appInfo 的 agentPort/agentToken。 */
+  agentCredentials?: () => Promise<{ port: number; token: string } | null>
   cloudLogin: (email: string, password: string) => Promise<{ ok: boolean; userId?: string; error?: string }>
   /** A10 轻量云身份激活：登录成功后取 cloud-session.json 解出的纯 session
    *  token（renderer 再走 exchangeRemoteTokenFn 换权益并写 remote-auth）。 */

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
   }
 }