@allbluecn/web-app 0.23.3 → 0.23.5

package/src/routeTree.gen.ts

@@ -23,6 +23,7 @@ import { Route as LoginLoginRouteRouteImport } from './routes/_login/login/route
 import { Route as LoginRegisterRouteRouteImport } from './routes/_login/register/route'
 import { Route as LoginResetPasswordRouteRouteImport } from './routes/_login/reset-password/route'
 import { Route as LoginVerifyEmailRouteRouteImport } from './routes/_login/verify-email/route'
+import { Route as NavAgentRouteRouteImport } from './routes/_nav/agent/route'
 import { Route as NavAppsRouteRouteImport } from './routes/_nav/apps/route'
 import { Route as NavBugsRouteRouteImport } from './routes/_nav/bugs/route'
 import { Route as NavChangelogRouteRouteImport } from './routes/_nav/changelog/route'
@@ -251,6 +252,13 @@ const LoginVerifyEmailRouteRoute = LoginVerifyEmailRouteRouteImport.update({
 } as any).lazy(() =>
   import('./routes/_login/verify-email/route.lazy').then((d) => d.Route),
 )
+const NavAgentRouteRoute = NavAgentRouteRouteImport.update({
+  id: '/agent',
+  path: '/agent',
+  getParentRoute: () => NavRouteRoute,
+} as any).lazy(() =>
+  import('./routes/_nav/agent/route.lazy').then((d) => d.Route),
+)
 const NavAppsRouteRoute = NavAppsRouteRouteImport.update({
   id: '/apps',
   path: '/apps',
@@ -1123,6 +1131,7 @@ export interface FileRoutesByFullPath {
   '/register': typeof LoginRegisterRouteRoute
   '/reset-password': typeof LoginResetPasswordRouteRoute
   '/verify-email': typeof LoginVerifyEmailRouteRoute
+  '/agent': typeof NavAgentRouteRoute
   '/apps': typeof NavAppsRouteRouteWithChildren
   '/bugs': typeof NavBugsRouteRouteWithChildren
   '/changelog': typeof NavChangelogRouteRoute
@@ -1262,6 +1271,7 @@ export interface FileRoutesByTo {
   '/register': typeof LoginRegisterRouteRoute
   '/reset-password': typeof LoginResetPasswordRouteRoute
   '/verify-email': typeof LoginVerifyEmailRouteRoute
+  '/agent': typeof NavAgentRouteRoute
   '/apps': typeof NavAppsRouteRouteWithChildren
   '/changelog': typeof NavChangelogRouteRoute
   '/dashboard': typeof NavDashboardRouteRoute
@@ -1390,6 +1400,7 @@ export interface FileRoutesById {
   '/_login/register': typeof LoginRegisterRouteRoute
   '/_login/reset-password': typeof LoginResetPasswordRouteRoute
   '/_login/verify-email': typeof LoginVerifyEmailRouteRoute
+  '/_nav/agent': typeof NavAgentRouteRoute
   '/_nav/apps': typeof NavAppsRouteRouteWithChildren
   '/_nav/bugs': typeof NavBugsRouteRouteWithChildren
   '/_nav/changelog': typeof NavChangelogRouteRoute
@@ -1531,6 +1542,7 @@ export interface FileRouteTypes {
     | '/register'
     | '/reset-password'
     | '/verify-email'
+    | '/agent'
     | '/apps'
     | '/bugs'
     | '/changelog'
@@ -1670,6 +1682,7 @@ export interface FileRouteTypes {
     | '/register'
     | '/reset-password'
     | '/verify-email'
+    | '/agent'
     | '/apps'
     | '/changelog'
     | '/dashboard'
@@ -1797,6 +1810,7 @@ export interface FileRouteTypes {
     | '/_login/register'
     | '/_login/reset-password'
     | '/_login/verify-email'
+    | '/_nav/agent'
     | '/_nav/apps'
     | '/_nav/bugs'
     | '/_nav/changelog'
@@ -2059,6 +2073,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LoginVerifyEmailRouteRouteImport
       parentRoute: typeof LoginRouteRoute
     }
+    '/_nav/agent': {
+      id: '/_nav/agent'
+      path: '/agent'
+      fullPath: '/agent'
+      preLoaderRoute: typeof NavAgentRouteRouteImport
+      parentRoute: typeof NavRouteRoute
+    }
     '/_nav/apps': {
       id: '/_nav/apps'
       path: '/apps'
@@ -3351,6 +3372,7 @@ const NavChatRouteWithChildren =
   NavChatRoute._addFileChildren(NavChatRouteChildren)
 
 interface NavRouteRouteChildren {
+  NavAgentRouteRoute: typeof NavAgentRouteRoute
   NavAppsRouteRoute: typeof NavAppsRouteRouteWithChildren
   NavBugsRouteRoute: typeof NavBugsRouteRouteWithChildren
   NavChangelogRouteRoute: typeof NavChangelogRouteRoute
@@ -3372,6 +3394,7 @@ interface NavRouteRouteChildren {
 }
 
 const NavRouteRouteChildren: NavRouteRouteChildren = {
+  NavAgentRouteRoute: NavAgentRouteRoute,
   NavAppsRouteRoute: NavAppsRouteRouteWithChildren,
   NavBugsRouteRoute: NavBugsRouteRouteWithChildren,
   NavChangelogRouteRoute: NavChangelogRouteRoute,

package/src/routes/-tests/agent-gate.test.ts

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手页（/_nav/agent）路由门控（桌面本地优先 P3-B5）：依赖桌面壳
+// AgentService，云 Web / OSS 构建无此页——beforeLoad 以构建期常量
+// isDesktopEdition（VITE_DEPLOY_TARGET）判定，非桌面构建直接 throw notFound
+// （SSR 即 404，无占位闪烁）。运行时的桥探测（useDesktopAgentPresence）另由
+// lib/desktop-agent/__tests__/use-desktop-agent-presence.test.tsx 覆盖。
+// 断言方式同 -edition-routing.test.tsx：直接调 Route.options.beforeLoad。
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+async function importAgentRoute(desktop: boolean) {
+  vi.resetModules()
+  vi.doMock('@/lib/edition-desktop', () => ({ isDesktopEdition: () => desktop }))
+  return import('../_nav/agent/route')
+}
+
+/** beforeLoad 抛出的 notFound 对象（@tanstack/router-core：{ isNotFound: true }） */
+function catchNotFound(fn: () => unknown): { isNotFound?: boolean } | null {
+  try {
+    fn()
+    return null
+  } catch (error) {
+    return error as { isNotFound?: boolean }
+  }
+}
+
+afterEach(() => {
+  vi.doUnmock('@/lib/edition-desktop')
+  vi.resetModules()
+})
+
+describe('/_nav/agent beforeLoad 门控', () => {
+  it('非桌面构建（云 Web / OSS）：throw notFound（页面不存在，SSR 即 404）', async () => {
+    const { Route } = await importAgentRoute(false)
+    const result = catchNotFound(() => Route.options.beforeLoad!({} as never))
+    expect(result?.isNotFound).toBe(true)
+  })
+
+  it('桌面构建：放行（运行时无桥由 lazy 组件的 useDesktopAgentPresence 落到 NotFound）', async () => {
+    const { Route } = await importAgentRoute(true)
+    expect(Route.options.beforeLoad!({} as never)).toBeUndefined()
+  })
+})

package/src/routes/_nav/agent/route.lazy.tsx

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手页（桌面本地优先 P3-B5）：授权目录卡 + agent 对话区。门控说明见
+// 同目录 route.tsx；本文件承担运行时桥探测（mounted 模式：SSR / hydration 首帧
+// 渲染空白、不读 window，挂载后 Electron 恢复页面，无桥即 NotFound）。
+//
+// 双层判定：presence（含 agentPort 装配，见 lib/desktop-agent/availability）决定
+// 页面是否可达；isAgentWorkspaceSupported（B1 三方法）决定目录授权是否可用——
+// 旧壳缺三方法时整页只留升级提示，不渲染对话区（否则对话区「请先添加授权目录」
+// 与卡片「请升级客户端」互相打脸）。
+import { useState } from 'react'
+import { createLazyFileRoute } from '@tanstack/react-router'
+import { useQuery } from '@tanstack/react-query'
+import { AgentChat } from '@/components/desktop-agent/agent-chat'
+import { AgentWorkspaceCard } from '@/components/desktop-agent/agent-workspace-card'
+import { isAgentWorkspaceSupported } from '@/lib/desktop-agent/availability'
+import { useDesktopAgentPresence } from '@/lib/desktop-agent/use-desktop-agent-presence'
+import { desktopAgentWorkspacesQueryOptions } from '@/lib/queries/desktop-agent'
+import { m } from '@/paraglide/messages.js'
+import { NavNotFound } from '../-components/nav-not-found'
+
+export const Route = createLazyFileRoute('/_nav/agent')({
+  component: DesktopAgentRoute,
+})
+
+function DesktopAgentRoute() {
+  const presence = useDesktopAgentPresence()
+  if (presence === 'pending') return null
+  if (presence === 'absent') return <NavNotFound />
+  return <DesktopAgentPage />
+}
+
+function DesktopAgentPage() {
+  const supportsWorkspaces = isAgentWorkspaceSupported()
+  // enabled 与卡片同口径：不支持目录授权时不查清单，避免无效 IPC
+  const { data: workspaces = [] } = useQuery({
+    ...desktopAgentWorkspacesQueryOptions(),
+    enabled: supportsWorkspaces,
+  })
+  const [picked, setPicked] = useState<string | null>(null)
+  const [running, setRunning] = useState(false)
+  // 未选择 / 选中项已被撤销 → 回落清单首项（清单为空则 null，对话区禁用输入）
+  const cwd = picked !== null && workspaces.includes(picked) ? picked : (workspaces[0] ?? null)
+
+  return (
+    <div className="flex h-full min-h-0 flex-col gap-4 overflow-hidden p-6">
+      <header className="space-y-1">
+        <h1 className="text-lg font-semibold">{m.agent_desktop_title()}</h1>
+        <p className="text-sm text-muted-foreground">{m.agent_desktop_pageDescription()}</p>
+      </header>
+      <div className="flex min-h-0 flex-1 flex-col gap-4 lg:flex-row">
+        <div className="shrink-0 lg:w-80 lg:overflow-y-auto">
+          <AgentWorkspaceCard selected={cwd} onSelect={setPicked} disabled={running} />
+        </div>
+        {/* 旧壳（无目录授权 IPC）只留卡片里的升级提示；否则每个目录一份会话
+            （换目录即新会话，运行中由 disabled 锁定切换） */}
+        {supportsWorkspaces && <AgentChat key={cwd ?? 'none'} cwd={cwd} onRunningChange={setRunning} />}
+      </div>
+    </div>
+  )
+}

package/src/routes/_nav/agent/route.tsx

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手（桌面本地优先 P3-B5）：依赖桌面壳的 AgentService，云 Web / OSS
+// 部署无此页。门控三层，保证「入口可见 ⟹ 页面可达」：
+// ① beforeLoad：构建期常量 isDesktopEdition()（VITE_DEPLOY_TARGET，同构执行、SSR
+//   安全——与 settings/sync、_public/index 的 beforeLoad 同口径），非桌面构建直接
+//   notFound（服务端即 404，无占位闪烁）；
+// ② lazy 组件：挂载后 getDesktopBridge() 运行时探测（useDesktopAgentPresence）——
+//   桌面构建被浏览器直开 backend 端口（无桥）→ NotFound；
+// ③ 侧栏入口：同一 presence 判定条件渲染（app-sidebar）。
+// 无 loader：授权清单走 react-query 工厂（lib/queries/desktop-agent，IPC 数据源）。
+import { createFileRoute, notFound } from '@tanstack/react-router'
+import { isDesktopEdition } from '@/lib/edition-desktop'
+
+export const Route = createFileRoute('/_nav/agent')({
+  beforeLoad: () => {
+    if (!isDesktopEdition()) throw notFound()
+  },
+})

package/src/routes/api/sync/account-status.ts

@@ -5,8 +5,10 @@
 // account-status 端点（桌面本地优先 P2-A5，迁移设计归属转移前置核对）：桌面端绑定
 // 云账号前探测目标账号是否「空账号」——仅空账号才走归属转移（一期唯一路径）。
 // 六表 count 口径与属主字段实查收敛在 server/sync/account-status.ts 的
-// isAccountEmpty（A8a 抽取，transferOwnershipFn 复核复用同源），此处只做
-// requireAuth + 响应映射。
+// isAccountEmpty，此处只做 requireAuth + 响应映射。
+// 注意（I2 裁定）：转移侧的复核**不再**调本地 isAccountEmpty（本地库看不到云端
+// 数据、且转移后本地计数恒 >0 会破坏幂等重试），改由
+// server/sync/account-status-cloud.ts 请求**本端点**取云端权威结果。
 import { createFileRoute } from "@tanstack/react-router"
 import { getPrisma } from "@allbluecn/database/get-prisma"
 import { requireAuth, UnauthorizedError } from "@/server/auth-helpers"

package/src/routes/api/sync/push.ts

@@ -87,9 +87,15 @@ export const Route = createFileRoute("/api/sync/push")({
         const body = pushSchema.parse(await request.json())
 
         const prisma = await getPrisma()
-        const { applyOp } = await import("@allbluecn/sync-core")
+        const { applyOp, admitScopeForOp } = await import("@allbluecn/sync-core")
         const { SYNC_TABLE_MAP } = await import("@allbluecn/sync-core/registrations")
         const scopes = await resolveSyncScopes(prisma, userId)
+        // 首次上云的 scope 动态准入（C1 / 裁定 R5）：空云账号的 scopes 只有
+        // user:<id>，而 outbox 的容器行 scope = 自身 id、子行 scope = 父容器 id。
+        // 逐 op 按「属主自证」累积准入集合（同一 Set 穿过整批 op，依赖 outbox
+        // 的父先子后拓扑序），再交给 applyOp 做行级校验——准入只覆盖自证行，
+        // 不放宽到整表（边界见 @allbluecn/sync-core 的 scope-admission 头注释）。
+        const admittedScopes = new Set(scopes)
 
         // 整批单事务：逐 op 应用（依赖拓扑由客户端 outbox 顺序保证）
         const results = await prisma.$transaction(async (tx) => {
@@ -107,9 +113,11 @@ export const Route = createFileRoute("/api/sync/push")({
               continue
             }
             const payload = op.payload as SyncPayload | undefined
+            await admitScopeForOp(executor, reg, { pk: op.pk, op: op.op, payload }, userId, admittedScopes)
+            const ctxScopes = [...admittedScopes]
             let outcome = await applyOp(executor, reg, { ...op, payload }, {
               userId,
-              scopes,
+              scopes: ctxScopes,
               now: new Date(),
             })
             // 编号重发号特例：stories/bugs 撞 identifier 唯一键 → 服务端重发号重试
@@ -119,7 +127,7 @@ export const Route = createFileRoute("/api/sync/push")({
               if (newIdentifier && newIdentifier !== oldIdentifier) {
                 outcome = await applyOp(executor, reg, { ...op, payload }, {
                   userId,
-                  scopes,
+                  scopes: ctxScopes,
                   now: new Date(),
                 })
                 if (outcome.kind === "applied") {

package/src/server/__tests__/desktop-cloud-identity.test.ts

@@ -0,0 +1,331 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 云身份幂等落库（C2 / 裁定 R3）回归哨兵：
+// ① 新建：upsert create 载荷含云端资料（name→username、email、头像三件）+ 随机
+//    password 占位 + ACTIVE；update 留空；
+// ② 幂等：同 id 已存在 → created:false 且零写入（不覆盖用户后续改名/改头像）；
+// ③ email 冲突（本地凭据用户已占用云邮箱）→ 不崩，降级 `<cloudUserId>@cloud.local`；
+// ④ username 冲突逐级降级 name → id → `<id>@cloud`；
+// ⑤ copyPreferencesFrom：新建行复制用户级配置列（C3 裁定；null 不复制）；
+// ⑥ R1：existing 行 + copyPreferencesFrom → 仅填充空/默认值列（真实绑定链：
+//    exchange 先幂等建行 → transfer 命中 existing，不填充则配置随 guest 行丢失）；
+// ⑦ R1：existing 行已有非空配置 → 不被覆盖（云态用户自己的值优先）。
+// @vitest-environment node
+import { describe, expect, it, vi } from 'vitest'
+import type { Prisma } from '@allbluecn/database'
+
+import {
+  USER_PREFERENCE_COLUMNS,
+  ensureCloudIdentity,
+  readUserPreferences,
+} from '../desktop-cloud-identity'
+
+type UserRow = Record<string, unknown> & { id: string }
+
+/** 最小 users 表 fake：findUnique 按 where 的单键查找，upsert 落行，update 合并 patch */
+function makeTx(seed: UserRow[] = []) {
+  const rows = new Map<string, UserRow>(seed.map((r) => [r.id, r]))
+  const upsert = vi.fn(async ({ create }: { create: UserRow; update: Record<string, never> }) => {
+    rows.set(create.id, create)
+    return create
+  })
+  const update = vi.fn(async ({ where, data }: { where: { id: string }; data: UserRow }) => {
+    const row = rows.get(where.id)
+    if (row) rows.set(where.id, { ...row, ...data })
+    return row
+  })
+  const findUnique = vi.fn(async ({ where }: { where: Record<string, string> }) => {
+    const [field, value] = Object.entries(where)[0] ?? []
+    for (const row of rows.values()) {
+      if (row[field] === value) return row
+    }
+    return null
+  })
+  const tx = { user: { findUnique, upsert, update } } as unknown as Prisma.TransactionClient
+  return { tx, rows, findUnique, upsert, update }
+}
+
+const CLOUD = 'cloud-user-1'
+
+describe('ensureCloudIdentity（C2 云身份自洽）', () => {
+  it('①新建：create 载荷含云端资料 + 随机 password 占位 + ACTIVE，update 留空', async () => {
+    const { tx, upsert } = makeTx()
+
+    const result = await ensureCloudIdentity(tx, {
+      id: CLOUD,
+      name: '云上名字',
+      email: 'cloud@example.com',
+      avatarConfig: { hat: 2 },
+      bgShape: 'circle',
+      bgColor: '#3b82f6',
+    })
+
+    expect(result).toEqual({
+      created: true,
+      email: 'cloud@example.com',
+      username: '云上名字',
+      emailFallback: false,
+    })
+    expect(upsert).toHaveBeenCalledTimes(1)
+    const arg = upsert.mock.calls[0][0] as { where: { id: string }; create: UserRow; update: object }
+    expect(arg.where).toEqual({ id: CLOUD })
+    expect(arg.create).toMatchObject({
+      id: CLOUD,
+      email: 'cloud@example.com',
+      username: '云上名字',
+      avatarConfig: { hat: 2 },
+      bgShape: 'circle',
+      bgColor: '#3b82f6',
+      status: 'ACTIVE',
+    })
+    // password 随机占位（非 bcrypt）：凭据登录必失败
+    expect(typeof arg.create.password).toBe('string')
+    expect((arg.create.password as string).length).toBeGreaterThan(0)
+    expect(arg.update).toEqual({})
+  })
+
+  it('②幂等：同 id 行已存在 → created:false 且零写入（不覆盖改后资料）', async () => {
+    const { tx, upsert, findUnique } = makeTx([{ id: CLOUD, email: 'x@y.z', username: '我改过的名字' }])
+
+    const result = await ensureCloudIdentity(tx, { id: CLOUD, name: '云上名字' })
+
+    expect(result.created).toBe(false)
+    expect(upsert).not.toHaveBeenCalled()
+    // 只做了存在性探测（单次 findUnique by id），未触发冲突探测链
+    expect(findUnique).toHaveBeenCalledTimes(1)
+  })
+
+  it('③email 冲突（本地凭据用户已占用云邮箱）→ 降级占位地址，不抛 P2002', async () => {
+    const { tx, upsert } = makeTx([
+      { id: 'local-user-9', email: 'cloud@example.com', username: '本地用户九' },
+    ])
+
+    const result = await ensureCloudIdentity(tx, {
+      id: CLOUD,
+      name: '云上名字',
+      email: 'cloud@example.com',
+    })
+
+    expect(result).toMatchObject({ created: true, emailFallback: true })
+    expect(result.email).toBe(`${CLOUD}@cloud.local`)
+    const create = (upsert.mock.calls[0][0] as { create: UserRow }).create
+    expect(create.email).toBe(`${CLOUD}@cloud.local`)
+  })
+
+  it('④username 冲突逐级降级：name 被占 → id → （id 也被占）<id>@cloud', async () => {
+    const taken = makeTx([{ id: 'local-2', email: 'a@b.c', username: '云上名字' }])
+    const first = await ensureCloudIdentity(taken.tx, { id: CLOUD, name: '云上名字' })
+    expect(first.username).toBe(CLOUD)
+
+    const bothTaken = makeTx([
+      { id: 'local-2', email: 'a@b.c', username: '云上名字' },
+      { id: 'local-3', email: 'd@e.f', username: CLOUD },
+    ])
+    const second = await ensureCloudIdentity(bothTaken.tx, { id: CLOUD, name: '云上名字' })
+    expect(second.username).toBe(`${CLOUD}@cloud`)
+  })
+
+  it('⑤copyPreferencesFrom：复制用户级配置列（null 不复制，未列列不出现）', async () => {
+    const { tx, upsert } = makeTx([
+      {
+        id: 'local-guest',
+        email: 'guest@localhost',
+        username: '本地用户',
+        aiApiKey: 'sk-local',
+        aiProvider: 'openrouter',
+        aiModel: 'openai/gpt-4o-mini',
+        aiSourceMode: null,
+        locale: 'zh',
+        timezone: 'Asia/Shanghai',
+        storyDisplayOptions: { showEmptyGroups: true },
+        preferredCurrency: 'cny',
+        defaultWorkspaceId: 'ws-1',
+        role: 'ADMIN', // 非配置列，不得复制
+      },
+    ])
+
+    await ensureCloudIdentity(
+      tx,
+      { id: CLOUD, name: '云上名字' },
+      { copyPreferencesFrom: 'local-guest' },
+    )
+
+    const create = (upsert.mock.calls[0][0] as { create: UserRow }).create
+    expect(create).toMatchObject({
+      aiApiKey: 'sk-local',
+      aiProvider: 'openrouter',
+      aiModel: 'openai/gpt-4o-mini',
+      locale: 'zh',
+      timezone: 'Asia/Shanghai',
+      storyDisplayOptions: { showEmptyGroups: true },
+      preferredCurrency: 'cny',
+      defaultWorkspaceId: 'ws-1',
+    })
+    // null 不复制（保持目标行 DB 默认/空值）
+    expect('aiSourceMode' in create).toBe(false)
+    // 账号安全态不在复制清单内
+    expect('role' in create).toBe(false)
+    expect(USER_PREFERENCE_COLUMNS).not.toContain('role' as never)
+  })
+
+  it('readUserPreferences：源行不存在 → 空对象（不抛）', async () => {
+    const { tx } = makeTx()
+    await expect(readUserPreferences(tx, 'missing')).resolves.toEqual({})
+  })
+
+  it('⑥R1 existing 行 + copyPreferencesFrom → 仅填充空/默认值列（不整行覆盖）', async () => {
+    // 真实绑定链：exchange 先幂等建行（无源）→ 云行只有资料、配置列全空
+    const { tx, rows, upsert, update } = makeTx([
+      {
+        id: 'local-guest',
+        username: '本地用户',
+        aiApiKey: 'sk-local',
+        aiProvider: 'openrouter',
+        aiModel: 'openai/gpt-4o-mini',
+        aiSourceMode: 'byok',
+        locale: 'zh',
+        timezone: 'Asia/Shanghai',
+        storyDisplayOptions: { showEmptyGroups: true },
+        preferredCurrency: 'cny',
+        defaultWorkspaceId: 'ws-1',
+      },
+      {
+        // exchange 建出来的云行：资料有值，配置列全 null（preferredCurrency 走 DB 默认 usd）
+        id: CLOUD,
+        username: '云上名字',
+        email: 'cloud@example.com',
+        aiApiKey: null,
+        aiProvider: null,
+        aiModel: null,
+        aiSourceMode: null,
+        locale: null,
+        timezone: null,
+        storyDisplayOptions: null,
+        preferredCurrency: 'usd',
+        defaultWorkspaceId: null,
+      },
+    ])
+
+    const result = await ensureCloudIdentity(
+      tx,
+      { id: CLOUD, name: '云上名字' },
+      { copyPreferencesFrom: 'local-guest' },
+    )
+
+    expect(result.created).toBe(false)
+    // 已存在不建行
+    expect(upsert).not.toHaveBeenCalled()
+    // 只发一次 patch 更新，且只含空列（preferredCurrency 默认 usd 也算空）
+    expect(update).toHaveBeenCalledTimes(1)
+    const arg = update.mock.calls[0][0] as { where: { id: string }; data: Record<string, unknown> }
+    expect(arg.where).toEqual({ id: CLOUD })
+    expect(arg.data).toEqual({
+      aiApiKey: 'sk-local',
+      aiProvider: 'openrouter',
+      aiModel: 'openai/gpt-4o-mini',
+      aiSourceMode: 'byok',
+      locale: 'zh',
+      timezone: 'Asia/Shanghai',
+      storyDisplayOptions: { showEmptyGroups: true },
+      preferredCurrency: 'cny',
+      defaultWorkspaceId: 'ws-1',
+    })
+    // 落地后配置到手（guest 行随后被删也不丢）
+    expect(rows.get(CLOUD)).toMatchObject({ aiApiKey: 'sk-local', locale: 'zh', preferredCurrency: 'cny' })
+  })
+
+  it('⑦R1 existing 行已有非空配置 → 不被覆盖（云端值优先）', async () => {
+    const { tx, rows, update } = makeTx([
+      {
+        id: 'local-guest',
+        username: '本地用户',
+        aiApiKey: 'sk-local',
+        aiProvider: 'openrouter',
+        locale: 'zh',
+        timezone: 'Asia/Shanghai',
+        preferredCurrency: 'cny',
+      },
+      {
+        // 用户在云态已自行填过 AI key / 语言（云行有值）
+        id: CLOUD,
+        username: '云上名字',
+        aiApiKey: 'sk-cloud',
+        aiProvider: 'openai',
+        locale: 'en',
+        preferredCurrency: 'usd',
+      },
+    ])
+
+    const result = await ensureCloudIdentity(
+      tx,
+      { id: CLOUD, name: '云上名字' },
+      { copyPreferencesFrom: 'local-guest' },
+    )
+
+    expect(result.created).toBe(false)
+    // 只补云行仍为空的列：timezone（aiApiKey/aiProvider/locale 有值不覆盖；
+    // preferredCurrency 为默认 usd → 视为未设置，可填）
+    expect(update).toHaveBeenCalledTimes(1)
+    const patch = (update.mock.calls[0][0] as { data: Record<string, unknown> }).data
+    expect(patch).toEqual({ timezone: 'Asia/Shanghai', preferredCurrency: 'cny' })
+    expect(patch).not.toHaveProperty('aiApiKey')
+    expect(patch).not.toHaveProperty('aiProvider')
+    expect(patch).not.toHaveProperty('locale')
+    expect(rows.get(CLOUD)).toMatchObject({ aiApiKey: 'sk-cloud', aiProvider: 'openai', locale: 'en' })
+  })
+
+  it('⑦b R1 existing 行目标列全部已有值 → patch 为空，零写入', async () => {
+    const { tx, update } = makeTx([
+      { id: 'local-guest', username: '本地用户', locale: 'zh' },
+      { id: CLOUD, username: '云上名字', locale: 'en' },
+    ])
+
+    await ensureCloudIdentity(tx, { id: CLOUD, name: '云上名字' }, { copyPreferencesFrom: 'local-guest' })
+
+    expect(update).not.toHaveBeenCalled()
+  })
+
+  it('⑧R1 真实顺序模拟：exchange 建行（无源）→ transfer 复制 → 配置到手', async () => {
+    const { tx, rows } = makeTx([
+      {
+        id: 'local-guest',
+        username: '本地用户',
+        aiApiKey: 'sk-local',
+        aiModel: 'openai/gpt-4o-mini',
+        locale: 'zh',
+        timezone: 'Asia/Shanghai',
+        preferredCurrency: 'cny',
+      },
+    ])
+
+    // ① exchange：建云行（无 copyPreferencesFrom —— 交换阶段没有源）
+    await ensureCloudIdentity(tx, { id: CLOUD, name: '云上名字', email: 'cloud@example.com' })
+    expect(rows.get(CLOUD)).toMatchObject({ id: CLOUD, username: '云上名字' })
+    expect(rows.get(CLOUD)?.aiApiKey).toBeUndefined()
+
+    // ② transfer：命中 existing + 传源 → 仅填空复制（此前实现直接 return，配置全丢）
+    const result = await ensureCloudIdentity(
+      tx,
+      { id: CLOUD, name: '云上名字', email: 'cloud@example.com' },
+      { copyPreferencesFrom: 'local-guest' },
+    )
+    expect(result.created).toBe(false)
+    expect(rows.get(CLOUD)).toMatchObject({
+      aiApiKey: 'sk-local',
+      aiModel: 'openai/gpt-4o-mini',
+      locale: 'zh',
+      timezone: 'Asia/Shanghai',
+      preferredCurrency: 'cny',
+      // 资料不被覆盖
+      username: '云上名字',
+      email: 'cloud@example.com',
+    })
+  })
+
+  it('id 为空 → 拒绝（防御非法调用）', async () => {
+    const { tx } = makeTx()
+    await expect(ensureCloudIdentity(tx, { id: '  ' })).rejects.toThrow(/id/)
+  })
+})

package/src/server/__tests__/desktop-session-merge.test.ts

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 桌面回落会话组装（C2）：remote-auth 落盘的云资料（name/email/avatar）必须
+// 组装成真实身份——此前 remote-auth 不存 profile，name 恒回落 UUID。
+// @vitest-environment node
+import { describe, expect, it } from 'vitest'
+
+import { buildRemoteSession } from '../desktop-session-merge'
+
+describe('buildRemoteSession（C2 云资料组装）', () => {
+  it('有资料：name/email/avatar 取自云资料，不再是 UUID', () => {
+    const session = buildRemoteSession({
+      userId: 'cloud-uuid-1',
+      planName: 'pro',
+      features: {},
+      username: '云上名字',
+      email: 'cloud@example.com',
+      avatarConfig: { hat: 1, face: 2 },
+      bgShape: 'circle',
+      bgColor: '#3b82f6',
+    })
+
+    expect(session.user).toMatchObject({
+      id: 'cloud-uuid-1',
+      name: '云上名字',
+      email: 'cloud@example.com',
+      avatarConfig: { hat: 1, face: 2 },
+      bgShape: 'circle',
+      bgColor: '#3b82f6',
+      isGuest: false,
+    })
+  })
+
+  it('旧文件无资料：name 回落 userId（行为与旧版逐字一致）', () => {
+    const session = buildRemoteSession({ userId: 'cloud-uuid-2', planName: 'free', features: {} })
+    expect(session.user).toMatchObject({ id: 'cloud-uuid-2', name: 'cloud-uuid-2' })
+    expect(session.user?.email).toBeUndefined()
+    expect(session.user?.avatarConfig).toBeUndefined()
+  })
+})