@allbluecn/web-app 0.23.2 → 0.23.4

package/src/components/layout/sidebar-03/user-menu.tsx

@@ -23,7 +23,11 @@ import {
   Settings,
   Users,
 } from "lucide-react";
+import type { QueryClient } from "@tanstack/react-query";
 import { logoutRemoteFn } from '@/server/serverFns/auth/session'
+import { reverseTransferOwnershipFn } from '@/server/serverFns/sync/transfer'
+import { getDesktopBridge } from '@/lib/desktop-bridge-types'
+import type { DesktopBridgeApi } from '@/lib/desktop-bridge-types'
 import { toast } from '@/components/ui/toast'
 
 import {
@@ -49,6 +53,56 @@ import type { AvatarConfig } from "@allbluecn/kernel";
 import { SparklesText } from "@/components/magicui/sparkles-text";
 import { m } from "@/paraglide/messages.js";
 
+/**
+ * 桌面云态登出（桌面本地优先 P2-A9 反向转移编排，裁定顺序）：登出 = 把云身份名下
+ * 数据翻回 guest（数据保留本机），双会话清理后回到 guest 态。
+ * ① 置转移锁（transferLock，复用 bind 锁文件——引擎每 tick 判定同源，「转移进行中
+ *   引擎勿 tick」；旧壳无此 IPC 优雅降级：反向转移单事务自身原子，锁为双保险）；
+ * ② reverseTransferOwnershipFn（serverFn：校验 remoteAuth/会话本人 → 单事务
+ *   cloud→guest + outbox/row_state 同事务清空防反向 op 上云 + 重建 guest 行；
+ *   事务提交后 server 侧已清 remote-auth——崩窗口收敛，A8b 发现 2 的镜像）；
+ * ③ 双会话清理：logoutRemoteFn（幂等 re-clear remote-auth）+ clearCloudSession
+ *   （清 cloud-session.json，引擎 guest 守卫回 idle）→ 清锁（先清云会话再解锁，
+ *   引擎恢复 tick 前云会话已不可用）；
+ * ④ queryClient.clear() + 整页 reload——reload 后 getSessionFn 回落 guest 会话。
+ * 失败路径（锁失败 / 转移失败）：解锁 + toast sync_logout_failed + 不 reload（留在
+ * 云态可重试；转移失败单事务已回滚，数据仍是云属主，重试幂等）。模块内局部函数
+ * （非导出）：本文件唯一导出是 UserMenu 组件，勿破坏 Fast Refresh 纯组件边界。
+ */
+async function desktopCloudLogout(
+  bridge: DesktopBridgeApi,
+  cloudUserId: string,
+  queryClient: QueryClient,
+): Promise<void> {
+  toast.info(m.sync_logout_in_progress());
+  // ① 转移锁
+  let lock: { ok: boolean; error?: string } = { ok: true };
+  try {
+    lock = bridge.transferLock ? await bridge.transferLock("begin") : { ok: true };
+  } catch {
+    lock = { ok: false };
+  }
+  if (!lock.ok) {
+    toast.error(m.sync_logout_failed());
+    return;
+  }
+  // ② 反向转移（失败：单事务回滚留在云态，解锁可重试）
+  try {
+    await reverseTransferOwnershipFn({ data: { cloudUserId } });
+  } catch {
+    try { await bridge.transferLock?.("end"); } catch { /* 尽力而为 */ }
+    toast.error(m.sync_logout_failed());
+    return;
+  }
+  // ③ 双会话清理（均幂等 best-effort：serverFn 已清 remote-auth，此处兜底）
+  try { await logoutRemoteFn({ data: {} }); } catch { /* 尽力而为 */ }
+  try { await bridge.clearCloudSession?.(); } catch { /* 尽力而为 */ }
+  try { await bridge.transferLock?.("end"); } catch { /* 尽力而为 */ }
+  // ④ 缓存清空 + 整页刷新（reload 后 desktop-state 回 guest）
+  queryClient.clear();
+  window.location.reload();
+}
+
 export function UserMenu() {
   const { isMobile } = useSidebar();
   const { data: clientSession } = useSession();
@@ -83,6 +137,15 @@ export function UserMenu() {
       window.location.reload();
       return;
     }
+    // 桌面云态（A9）：桌面壳存在且无本地 authjs 会话（clientSession 为空）＝当前
+    // 会话是 remote-auth 回落的轻量云身份，登出走反向转移编排（数据翻回 guest）。
+    // 本地凭据登录（clientSession 非空）与 web 照旧走 signOut 链——云身份回落仅在
+    // authjs 会话无效时生效，clientSession 为空是云态判别式。
+    const bridge = getDesktopBridge();
+    if (bridge && !clientSession && user?.id) {
+      await desktopCloudLogout(bridge, user.id, queryClient);
+      return;
+    }
     await signOut();
     queryClient.resetQueries({ queryKey: ['session'] });
     await router.navigate({ to: "/login" });

package/src/config/sidebar-routes.tsx

@@ -26,6 +26,7 @@ import {
   Bug,
   PenTool,
   ListTodo,
+  FolderSearch,
 } from "lucide-react";
 
 export type RouteSubItem = {
@@ -100,4 +101,16 @@ export const workspaceRoutes: Route[] = [
     icon: <ListTodo className="size-4" />,
     link: "/tasks",
   },
-];
+];
+
+/**
+ * 本地文件助手（桌面本地优先 P3-B5）：依赖桌面壳 AgentService，不进上方常驻列表——
+ * app-sidebar 经 useDesktopAgentPresence（桌面构建 + desktopBridge，mounted 模式）
+ * 判定后条件追加，云 Web / OSS 恒不可见（与 /_nav/agent 路由门控同源）。
+ */
+export const desktopAgentRoute: Route = {
+  id: "desktop-agent",
+  title: m.agent_desktop_title,
+  icon: <FolderSearch className="size-4" />,
+  link: "/agent",
+};

package/src/lib/__tests__/session.test.ts

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// getCurrentSession 桌面回落单点测试（桌面本地优先 P2 / A10）。
+// 优先级链钉死（复审③ B1/B2）：authjs session（有效则返回）→ desktop 时
+// remoteAuth → null。start-authjs / auth.config / remote-auth 全 mock：
+// 不触真实 JWT 解密、不真读写 DESKTOP_USER_DATA_DIR 下的 remote-auth.json
+// （#578 fs 实现勿真写盘）。desktop 判定走 DEPLOY_TARGET env stub
+// （isDesktopServer 调用时读 env，见 desktop-guest.ts:40）。
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { getCurrentSession } from '../session'
+import type { Session } from '../session'
+
+const { getSessionMock, getAuthConfigMock, readRemoteAuthMock } = vi.hoisted(() => ({
+  getSessionMock: vi.fn(),
+  getAuthConfigMock: vi.fn(async () => ({})),
+  readRemoteAuthMock: vi.fn(),
+}))
+
+vi.mock('start-authjs', () => ({
+  getSession: getSessionMock,
+}))
+
+vi.mock('@/lib/auth/auth.config', () => ({
+  getAuthConfig: getAuthConfigMock,
+}))
+
+vi.mock('@/server/remote-auth', () => ({
+  readRemoteAuth: readRemoteAuthMock,
+}))
+
+const AUTHED: Session = {
+  user: { id: 'authjs-user-1', name: 'AuthJS 用户' },
+  expires: '2026-01-01T00:00:00.000Z',
+}
+
+const REMOTE_AUTH = {
+  userId: 'cloud-user-abc',
+  planName: 'pro',
+  features: {},
+  sessionToken: 'cloud-session-token',
+}
+
+const REQ = () => new Request('http://localhost/api/auth/session')
+
+describe('getCurrentSession 桌面回落（A10 优先级链）', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.clearAllMocks()
+  })
+
+  it('①a authjs session 有效 → 直接返回，desktop 下也不读 remoteAuth', async () => {
+    vi.stubEnv('DEPLOY_TARGET', 'desktop')
+    getSessionMock.mockResolvedValue(AUTHED)
+    const session = await getCurrentSession(REQ())
+    expect(session?.user?.id).toBe('authjs-user-1')
+    expect(readRemoteAuthMock).not.toHaveBeenCalled()
+  })
+
+  it('①b+② authjs 无效 + desktop + remoteAuth 有 → 组装轻量云身份（user.id=cloudUserId）', async () => {
+    vi.stubEnv('DEPLOY_TARGET', 'desktop')
+    getSessionMock.mockResolvedValue(null)
+    readRemoteAuthMock.mockResolvedValue(REMOTE_AUTH)
+    const session = await getCurrentSession(REQ())
+    // 审查重点 4 前半：回落 session 的属主必须是云 userId（非 guest / 非 authjs 残影）
+    expect(session?.user?.id).toBe('cloud-user-abc')
+    // 组装形态与 buildRemoteSession 对齐（RemoteAuthData 实际字段，不虚构）
+    expect(session?.user?.name).toBe('cloud-user-abc') // username 缺省回落 userId
+    expect(session?.user?.isGuest).toBe(false)
+    expect(session?.user?.hasAiKey).toBe(false)
+    expect(session?.expires).toBe('never')
+  })
+
+  it('①c authjs 无效 + desktop + remoteAuth 无 → null', async () => {
+    vi.stubEnv('DEPLOY_TARGET', 'desktop')
+    getSessionMock.mockResolvedValue(null)
+    readRemoteAuthMock.mockResolvedValue(null)
+    expect(await getCurrentSession(REQ())).toBeNull()
+  })
+
+  it('③ 非 desktop 不读 remoteAuth（env 判定先于 fs 读取）', async () => {
+    vi.stubEnv('DEPLOY_TARGET', '')
+    getSessionMock.mockResolvedValue(null)
+    expect(await getCurrentSession(REQ())).toBeNull()
+    expect(readRemoteAuthMock).not.toHaveBeenCalled()
+  })
+
+  it('无 request → null（既有守卫不回归，不触发任何读取）', async () => {
+    vi.stubEnv('DEPLOY_TARGET', 'desktop')
+    expect(await getCurrentSession()).toBeNull()
+    expect(getSessionMock).not.toHaveBeenCalled()
+    expect(readRemoteAuthMock).not.toHaveBeenCalled()
+  })
+})

package/src/lib/auth/auth.config.ts

@@ -74,6 +74,19 @@ export function invalidateProfileCache(userId: string): void {
   profileCache.delete(userId)
 }
 
+/**
+ * 全量清空 profile 缓存（桌面本地优先 A11 缓存三件套之一）：身份切换（guest↔
+ * cloud）后旧身份的缓存条目必须整体失效——按 userId 逐个 invalidate 需要知道旧
+ * id，身份切换场景里调用方（renderer 经 resetAuthProfileCacheFn）恰恰没有可靠
+ * 的旧 id，全量 clear 是唯一正确形态。服务端进程内存缓存，清空零风险（miss 后
+ * 自然回源）。桌面 guest/remote-auth 回落会话不经过本缓存（buildGuestSession /
+ * buildRemoteSession 不查 profileCache），本清理覆盖的是「本地凭据 authjs 会话
+ * 与桌面身份切换并存」的混合场景（getCachedProfile(token.id) 消费面）。
+ */
+export function resetProfileCache(): void {
+  profileCache.clear()
+}
+
 async function queryProfile(userId: string): Promise<CachedProfile | null> {
   const [dbUser, providerConfigs, sub] = await Promise.all([
     prisma.user.findUnique({

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

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

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

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// 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 取值位）。
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { UIMessage } from '@tanstack/ai-client'
+
+type AppInfo = {
+  version: string
+  clientId: string
+  platform: string
+  backendPort: number | null
+  agentPort?: number | null
+  agentToken?: string | null
+}
+
+const bridgeRef: { current: { appInfo: () => Promise<AppInfo> } | null } = { current: null }
+
+vi.mock('@/lib/desktop-bridge-types', () => ({
+  getDesktopBridge: () => bridgeRef.current,
+}))
+
+import {
+  DesktopAgentUnavailableError,
+  createDesktopAgentConnection,
+  resolveDesktopAgentEndpoint,
+} from '../connection'
+
+const BASE_INFO: AppInfo = { version: '1.0.0', clientId: 'c1', platform: 'darwin', backendPort: 51000 }
+
+function bridgeWith(info: Partial<AppInfo>) {
+  return { appInfo: vi.fn(async () => ({ ...BASE_INFO, ...info })) }
+}
+
+const encoder = new TextEncoder()
+function sse(event: Record<string, unknown>): Uint8Array {
+  return encoder.encode(`data: ${JSON.stringify(event)}\n\n`)
+}
+
+/** 打桩 fetch：返回给定 AG-UI 事件序列的 SSE 响应 */
+function stubSseFetch(events: Array<Record<string, unknown>>) {
+  const fetchMock = vi.fn(async (_url: string | URL | RequestInfo, _init?: RequestInit) => {
+    const stream = new ReadableStream<Uint8Array>({
+      start(c) {
+        for (const e of events) c.enqueue(sse(e))
+        c.close()
+      },
+    })
+    return new Response(stream, { status: 200, headers: { 'content-type': 'text/event-stream' } })
+  })
+  vi.stubGlobal('fetch', fetchMock)
+  return fetchMock
+}
+
+const RUN_EVENTS = [
+  { type: 'RUN_STARTED', threadId: 't-1', runId: 'r-1' },
+  { type: 'TEXT_MESSAGE_START', messageId: 'msg-1', role: 'assistant' },
+  { type: 'TEXT_MESSAGE_CONTENT', messageId: 'msg-1', delta: '目录里有 a.txt' },
+  { type: 'TEXT_MESSAGE_END', messageId: 'msg-1' },
+  { type: 'RUN_FINISHED', threadId: 't-1', runId: 'r-1' },
+]
+
+const USER_MESSAGE: UIMessage = { id: 'u1', role: 'user', parts: [{ type: 'text', content: '列出目录' }] }
+
+async function drain(iterable: AsyncIterable<unknown>): Promise<unknown[]> {
+  const out: unknown[] = []
+  for await (const chunk of iterable) out.push(chunk)
+  return out
+}
+
+beforeEach(() => {
+  bridgeRef.current = null
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+})
+
+describe('resolveDesktopAgentEndpoint（appInfo 懒取）', () => {
+  it('无桥（云 Web / OSS）→ null', async () => {
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+  })
+
+  it('agent 未装配（agentPort/agentToken 为 null 或旧壳 undefined）→ null', async () => {
+    bridgeRef.current = bridgeWith({ agentPort: null, agentToken: null })
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+    bridgeRef.current = bridgeWith({})
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+  })
+
+  it('端口或令牌非法（越界 / 非整数 / 空令牌）→ null，不拼出坏 URL', async () => {
+    for (const agentPort of [0, 65536, 1.5, -1]) {
+      bridgeRef.current = bridgeWith({ agentPort, agentToken: 'tok' })
+      await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+    }
+    bridgeRef.current = bridgeWith({ agentPort: 4567, agentToken: '' })
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+  })
+
+  it('就绪 → 127.0.0.1 端点 URL + 令牌', 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',
+    })
+  })
+
+  it('appInfo 抛错（IPC 断开 / main 未就绪）→ null，不流出原生错误原文', async () => {
+    bridgeRef.current = {
+      appInfo: vi.fn(async () => {
+        throw new Error('ipc closed')
+      }),
+    }
+    await expect(resolveDesktopAgentEndpoint()).resolves.toBeNull()
+  })
+})
+
+describe('createDesktopAgentConnection（fetchServerSentEvents 包装）', () => {
+  it('端点不可用 → 抛 DesktopAgentUnavailableError，且不发起 fetch', async () => {
+    const fetchMock = stubSseFetch(RUN_EVENTS)
+    bridgeRef.current = bridgeWith({ agentPort: null, agentToken: null })
+    const connection = createDesktopAgentConnection()
+    await expect(
+      drain(connection.connect([USER_MESSAGE], undefined, undefined, { threadId: 't-1', runId: 'r-1' })),
+    ).rejects.toBeInstanceOf(DesktopAgentUnavailableError)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('appInfo 抛错 → 同样归「服务未就绪」（DesktopAgentUnavailableError），不发 fetch、不透出 IPC 原文', async () => {
+    const fetchMock = stubSseFetch(RUN_EVENTS)
+    bridgeRef.current = {
+      appInfo: vi.fn(async () => {
+        throw new Error('ipc closed')
+      }),
+    }
+    const error = await drain(
+      createDesktopAgentConnection().connect([USER_MESSAGE], undefined, undefined, { threadId: 't', runId: 'r' }),
+    ).catch((cause: unknown) => cause)
+    expect(error).toBeInstanceOf(DesktopAgentUnavailableError)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('请求线格式：URL / X-Desktop-Token / X-Run-Id / forwardedProps.cwd 与 Pro 端点契约一致', async () => {
+    const fetchMock = stubSseFetch(RUN_EVENTS)
+    bridgeRef.current = bridgeWith({ agentPort: 4567, agentToken: 'tok-abc' })
+    const connection = createDesktopAgentConnection()
+    await drain(
+      connection.connect([USER_MESSAGE], undefined, undefined, {
+        threadId: 't-1',
+        runId: 'r-1',
+        forwardedProps: { cwd: '/Users/x/proj' },
+      }),
+    )
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchMock.mock.calls[0]!
+    expect(url).toBe('http://127.0.0.1:4567/prompt')
+    expect(init?.method).toBe('POST')
+    const headers = init?.headers as Record<string, string>
+    expect(headers['X-Desktop-Token']).toBe('tok-abc')
+    expect(headers['X-Run-Id']).toBe('r-1')
+    expect(headers['Content-Type']).toBe('application/json')
+    const body = JSON.parse(String(init?.body)) as Record<string, unknown>
+    // 端点 extractCwd：顶层无 cwd，取 forwardedProps.cwd（fetchServerSentEvents 真实形态）
+    expect(body.cwd).toBeUndefined()
+    expect(body.forwardedProps).toEqual({ cwd: '/Users/x/proj' })
+    expect(body.threadId).toBe('t-1')
+    expect(body.runId).toBe('r-1')
+    // 端点 extractPrompt：messages 末条 user 消息文本（纯文本 content 为 string）
+    expect(body.messages).toEqual([expect.objectContaining({ role: 'user', content: '列出目录' })])
+  })
+
+  it('SSE 帧原样产出为 AG-UI chunk（RUN_STARTED 起、RUN_FINISHED 止）', async () => {
+    stubSseFetch(RUN_EVENTS)
+    bridgeRef.current = bridgeWith({ agentPort: 4567, agentToken: 'tok-abc' })
+    const chunks = (await drain(
+      createDesktopAgentConnection().connect([USER_MESSAGE], undefined, undefined, {
+        threadId: 't-1',
+        runId: 'r-1',
+      }),
+    )) as Array<{ type: string }>
+    expect(chunks.map((c) => c.type)).toEqual([
+      'RUN_STARTED',
+      'TEXT_MESSAGE_START',
+      'TEXT_MESSAGE_CONTENT',
+      'TEXT_MESSAGE_END',
+      'RUN_FINISHED',
+    ])
+  })
+
+  it('每次 connect 都重取 appInfo（backend 重启换端口/令牌后下一问即用新值）', async () => {
+    const fetchMock = stubSseFetch(RUN_EVENTS)
+    const appInfo = vi
+      .fn<() => Promise<AppInfo>>()
+      .mockResolvedValueOnce({ ...BASE_INFO, agentPort: 4567, agentToken: 'tok-old' })
+      .mockResolvedValueOnce({ ...BASE_INFO, agentPort: 5678, agentToken: 'tok-new' })
+    bridgeRef.current = { appInfo }
+    const connection = createDesktopAgentConnection()
+    const ctx = { threadId: 't-1', runId: 'r-1' }
+    await drain(connection.connect([USER_MESSAGE], undefined, undefined, ctx))
+    await drain(connection.connect([USER_MESSAGE], undefined, undefined, ctx))
+    expect(appInfo).toHaveBeenCalledTimes(2)
+    expect(fetchMock.mock.calls.map((c) => c[0])).toEqual([
+      'http://127.0.0.1:4567/prompt',
+      'http://127.0.0.1:5678/prompt',
+    ])
+    expect((fetchMock.mock.calls[1]![1]?.headers as Record<string, string>)['X-Desktop-Token']).toBe('tok-new')
+  })
+
+  it('端点非 2xx（如 401 令牌失效）→ 错误携带 status 透传给 useChat error 态', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response('{"error":"bad token"}', { status: 401, statusText: 'Unauthorized' })),
+    )
+    bridgeRef.current = bridgeWith({ agentPort: 4567, agentToken: 'tok-abc' })
+    await expect(
+      drain(createDesktopAgentConnection().connect([USER_MESSAGE], undefined, undefined, { threadId: 't', runId: 'r' })),
+    ).rejects.toMatchObject({ status: 401 })
+  })
+})

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

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// desktop-agent 错误文案映射（桌面本地优先 P3-B5）：useChat error 态 → 可读 i18n 文案。
+// 错误来源三类：连接包装（DesktopAgentUnavailableError）、端点非 2xx（官方
+// StreamHttpError 携带 status：401 令牌失效 / 403 目录未授权或 origin 被拒）、
+// 网络层（StreamReadError：端口不通 / CORS 预检被拒），其余（RUN_ERROR 等）透出原文。
+import { describe, expect, it } from 'vitest'
+import { m } from '@/paraglide/messages.js'
+import { DesktopAgentUnavailableError } from '../connection'
+import { describeDesktopAgentError } from '../errors'
+
+function withStatus(status: number): Error {
+  return Object.assign(new Error(`HTTP error! status: ${status}`), { name: 'StreamHttpError', status })
+}
+
+describe('describeDesktopAgentError', () => {
+  it('端点不可用 → 未就绪提示（实例与同名错误两种形态）', () => {
+    expect(describeDesktopAgentError(new DesktopAgentUnavailableError())).toBe(m.agent_desktop_errorUnavailable())
+    const renamed = Object.assign(new Error('x'), { name: 'DesktopAgentUnavailableError' })
+    expect(describeDesktopAgentError(renamed)).toBe(m.agent_desktop_errorUnavailable())
+  })
+
+  it('401 → 令牌失效提示；403 → 未授权/来源被拒提示', () => {
+    expect(describeDesktopAgentError(withStatus(401))).toBe(m.agent_desktop_errorUnauthorized())
+    expect(describeDesktopAgentError(withStatus(403))).toBe(m.agent_desktop_errorForbidden())
+  })
+
+  it('网络层失败（StreamReadError：端口不通 / CORS）→ 无法连接提示', () => {
+    const err = Object.assign(new Error('Failed to fetch'), { name: 'StreamReadError' })
+    expect(describeDesktopAgentError(err)).toBe(m.agent_desktop_errorConnection())
+  })
+
+  it('其余（RUN_ERROR、400、500 等）→ 运行失败 + 原文', () => {
+    expect(describeDesktopAgentError(new Error('模型配置缺失'))).toBe(
+      m.agent_desktop_errorGeneric({ message: '模型配置缺失' }),
+    )
+    expect(describeDesktopAgentError(withStatus(500))).toBe(
+      m.agent_desktop_errorGeneric({ message: 'HTTP error! status: 500' }),
+    )
+  })
+})

package/src/lib/desktop-agent/__tests__/tool-result.test.ts

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// desktop-agent 工具结果解析（桌面本地优先 P3-B5）：TOOL_CALL_RESULT.content =
+// JSON.stringify(pi AgentToolResult)（B3 mapper），TanStack processor JSON.parse 后
+// 挂到 tool-call part.output。本测试按 pi 1.4 只读四件套的真实文本格式取证——
+// grep `path:N: text`（上下文行 `path-N- text`）、ls 目录带 `/`、find 相对路径、
+// read 原文；尾部 `\n\n[...limit reached / Use offset=...]` 截断提示；空结果哨兵。
+import { describe, expect, it } from 'vitest'
+import {
+  AGENT_TOOL_MAX_ENTRIES,
+  extractAgentToolText,
+  parseAgentToolArgs,
+  summarizeAgentTool,
+} from '../tool-result'
+
+const piResult = (text: string) => ({ content: [{ type: 'text', text }], details: undefined })
+
+describe('extractAgentToolText', () => {
+  it('pi AgentToolResult 对象（processor 已 JSON.parse）→ 文本块拼接', () => {
+    expect(extractAgentToolText(piResult('a.txt\nsrc/'))).toBe('a.txt\nsrc/')
+    expect(
+      extractAgentToolText({ content: [{ type: 'text', text: 'L1' }, { type: 'image', data: 'x' }, { type: 'text', text: 'L2' }] }),
+    ).toBe('L1\nL2')
+  })
+
+  it('output 缺席时回落 tool-result part 内容（字符串或 ContentPart[] 内嵌 JSON）', () => {
+    const json = JSON.stringify(piResult('hello'))
+    expect(extractAgentToolText(undefined, json)).toBe('hello')
+    expect(extractAgentToolText(undefined, [{ type: 'text', content: json }])).toBe('hello')
+  })
+
+  it('非 JSON 文本 / processor 错误对象 / 空值', () => {
+    expect(extractAgentToolText('plain text')).toBe('plain text')
+    expect(extractAgentToolText({ error: '读取失败' })).toBe('读取失败')
+    expect(extractAgentToolText(undefined, undefined)).toBeNull()
+    expect(extractAgentToolText({ unrelated: true })).toBeNull()
+  })
+
+  it('无 text 块的对象（read 图片：仅 base64 image 块）→ null，不回落原始 JSON 串', () => {
+    const base64 = 'iVBORw0KGgoAAAANSUhEUg=='
+    const imageOnly = { content: [{ type: 'image', mimeType: 'image/png', data: base64 }], details: undefined }
+    // processor 已解析的对象形态
+    expect(extractAgentToolText(imageOnly)).toBeNull()
+    // tool-result part 回落形态：JSON 串 / ContentPart[] 内嵌 JSON 串
+    expect(extractAgentToolText(undefined, JSON.stringify(imageOnly))).toBeNull()
+    expect(extractAgentToolText(undefined, [{ type: 'text', content: JSON.stringify(imageOnly) }])).toBeNull()
+    // 摘要侧同样无条目（不会把 base64 铺进折叠卡）
+    expect(summarizeAgentTool('read', { path: 'logo.png' }, extractAgentToolText(imageOnly))).toMatchObject({
+      entries: [],
+      total: 0,
+    })
+  })
+})
+
+describe('parseAgentToolArgs', () => {
+  it('优先已解析 input；否则解析 arguments 字符串；流式不完整 JSON → 空对象', () => {
+    expect(parseAgentToolArgs({ input: { path: 'src' }, arguments: '{"path":"x"}' })).toEqual({ path: 'src' })
+    expect(parseAgentToolArgs({ arguments: '{"pattern":"TODO"}' })).toEqual({ pattern: 'TODO' })
+    expect(parseAgentToolArgs({ arguments: '{"pattern":"TO' })).toEqual({})
+    expect(parseAgentToolArgs({ arguments: '' })).toEqual({})
+    expect(parseAgentToolArgs({ arguments: '[1,2]' })).toEqual({})
+  })
+})
+
+describe('summarizeAgentTool', () => {
+  it('grep：命中行解析为 文件/行号/内容，上下文行与截断提示不计入，提示置 truncated', () => {
+    const text = [
+      'src/a.ts:12: const TODO = 1',
+      'src/a.ts-13- context line',
+      'docs/b.md:3: TODO: write docs',
+      '',
+      '[100 matches limit reached. Use limit=200 for more, or refine pattern]',
+    ].join('\n')
+    const s = summarizeAgentTool('grep', { pattern: 'TODO' }, text)
+    expect(s.kind).toBe('grep')
+    expect(s.target).toBe('TODO')
+    expect(s.entries).toEqual([
+      { kind: 'hit', path: 'src/a.ts', line: 12, text: 'const TODO = 1' },
+      { kind: 'hit', path: 'docs/b.md', line: 3, text: 'TODO: write docs' },
+    ])
+    expect(s.total).toBe(2)
+    expect(s.truncated).toBe(true)
+    expect(s.empty).toBe(false)
+  })
+
+  it('grep：路径含冒号 / 内容含 `:N: ` 均不误切（取首个 `:行号: ` 边界）', () => {
+    const s = summarizeAgentTool(
+      'grep',
+      { pattern: 'x' },
+      'dir:with:colon/a.ts:7: x = 1\nsrc/log.ts:9: msg("at a.ts:3: boom")',
+    )
+    expect(s.entries).toEqual([
+      { kind: 'hit', path: 'dir:with:colon/a.ts', line: 7, text: 'x = 1' },
+      { kind: 'hit', path: 'src/log.ts', line: 9, text: 'msg("at a.ts:3: boom")' },
+    ])
+  })
+
+  it('ls：条目为文件名（目录保留 / 后缀），target 缺省为 .', () => {
+    const s = summarizeAgentTool('ls', {}, 'README.md\nsrc/\npackage.json')
+    expect(s.target).toBe('.')
+    expect(s.entries).toEqual([
+      { kind: 'file', path: 'README.md' },
+      { kind: 'file', path: 'src/' },
+      { kind: 'file', path: 'package.json' },
+    ])
+    expect(s.total).toBe(3)
+    expect(s.truncated).toBe(false)
+  })
+
+  it('find：target 为 glob，条目为相对路径', () => {
+    const s = summarizeAgentTool('find', { pattern: '**/*.ts', path: 'src' }, 'src/a.ts\nsrc/b/c.ts')
+    expect(s.target).toBe('**/*.ts')
+    expect(s.entries.map((e) => (e.kind === 'file' ? e.path : null))).toEqual(['src/a.ts', 'src/b/c.ts'])
+  })
+
+  it('read：target 为文件路径，条目为内容行，尾部 Showing lines 提示剥离并置 truncated', () => {
+    const s = summarizeAgentTool(
+      'read',
+      { path: 'README.md' },
+      '# Title\n\nbody line\n\n[Showing lines 1-3 of 900. Use offset=4 to continue.]',
+    )
+    expect(s.target).toBe('README.md')
+    expect(s.entries).toEqual([
+      { kind: 'text', text: '# Title' },
+      { kind: 'text', text: '' },
+      { kind: 'text', text: 'body line' },
+    ])
+    expect(s.truncated).toBe(true)
+  })
+
+  it('read：正文本身以方括号结尾（非 pi 提示措辞）不被误剥离', () => {
+    const s = summarizeAgentTool('read', { path: 'notes.md' }, 'intro\n\n[TODO]')
+    expect(s.entries.map((e) => (e.kind === 'text' ? e.text : null))).toEqual(['intro', '', '[TODO]'])
+    expect(s.truncated).toBe(false)
+  })
+
+  it('空结果哨兵：grep 无匹配 / ls 空目录 / find 无文件 → empty 且无条目', () => {
+    expect(summarizeAgentTool('grep', { pattern: 'zzz' }, 'No matches found')).toMatchObject({ empty: true, entries: [], total: 0 })
+    expect(summarizeAgentTool('ls', { path: 'empty' }, '(empty directory)')).toMatchObject({ empty: true, entries: [] })
+    expect(summarizeAgentTool('find', { pattern: '*.x' }, 'No files found matching pattern')).toMatchObject({ empty: true })
+  })
+
+  it('条目超过展示上限：entries 截至上限、total 保留真实数量', () => {
+    const lines = Array.from({ length: AGENT_TOOL_MAX_ENTRIES + 7 }, (_, i) => `f${i}.txt`).join('\n')
+    const s = summarizeAgentTool('ls', {}, lines)
+    expect(s.entries).toHaveLength(AGENT_TOOL_MAX_ENTRIES)
+    expect(s.total).toBe(AGENT_TOOL_MAX_ENTRIES + 7)
+  })
+
+  it('未知工具：kind=other、target=null、条目为文本行；无结果文本 → 无条目', () => {
+    expect(summarizeAgentTool('custom', {}, 'line1\nline2')).toMatchObject({
+      kind: 'other',
+      target: null,
+      entries: [
+        { kind: 'text', text: 'line1' },
+        { kind: 'text', text: 'line2' },
+      ],
+    })
+    expect(summarizeAgentTool('read', { path: 'a' }, null)).toMatchObject({ entries: [], total: 0, empty: false })
+  })
+})