@allbluecn/web-app 0.23.3 → 0.23.5

package/src/components/desktop-agent/agent-workspace-card.tsx

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手 · 授权目录卡（桌面本地优先 P3-B5）：agent 只能读取这里列出的目录。
+// - 添加：desktopBridge.pickDirectory（main 侧原生目录对话框，选中即写入
+//   userData/agent/workspaces.json 并返回规范化绝对路径；取消返回 null）——
+//   renderer 无法注入任意路径，授权入口只有这一个（B1 授权模型）。
+// - 清单：react-query 工厂 desktopAgentWorkspacesQueryOptions（listWorkspaces）。
+// - 撤销：removeWorkspace；增删成功后按 DESKTOP_AGENT_QUERY_KEY 前缀 invalidate。
+// - 单选当前工作目录（对话 cwd）；运行中由父级锁定（disabled），避免中途换目录。
+// - 门控：useDesktopAgentPresence（含 agentPort 装配判定 + 冷启动有界重试）+
+//   isAgentWorkspaceSupported（B1 三方法）双条件，与侧栏入口/页面同源；presence
+//   为 pending（探测/重试中）时按加载态渲染，absent（终态）才提示升级。
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { FolderOpen, FolderPlus, Loader2, X } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from '@/components/ui/empty'
+import { Label } from '@/components/ui/label'
+import { RadioGroup, RadioGroupItem } from '@/components/ui/radio-group'
+import { Skeleton } from '@/components/ui/skeleton'
+import { toast } from '@/components/ui/toast'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { getDesktopBridge } from '@/lib/desktop-bridge-types'
+import { isAgentWorkspaceSupported } from '@/lib/desktop-agent/availability'
+import { useDesktopAgentPresence } from '@/lib/desktop-agent/use-desktop-agent-presence'
+import { DESKTOP_AGENT_QUERY_KEY, desktopAgentWorkspacesQueryOptions } from '@/lib/queries/desktop-agent'
+import { cn } from '@/lib/utils'
+import { m } from '@/paraglide/messages.js'
+
+/** 路径末段作为目录显示名（POSIX / Windows 分隔符均可） */
+function folderNameOf(path: string): string {
+  return path.split(/[\\/]/).filter(Boolean).at(-1) ?? path
+}
+
+export interface AgentWorkspaceCardProps {
+  /** 当前选中的工作目录（对话 cwd） */
+  selected: string | null
+  onSelect: (path: string) => void
+  /** 运行中锁定切换与撤销 */
+  disabled?: boolean
+}
+
+export function AgentWorkspaceCard({ selected, onSelect, disabled = false }: AgentWorkspaceCardProps) {
+  const queryClient = useQueryClient()
+  // 门控口径与侧栏入口/页面同源（presence 已含 agentPort：agent 未装配即不可用），
+  // 再叠加 B1 三方法检查——旧壳（无目录授权 IPC）同样整卡降级为升级提示。
+  const presence = useDesktopAgentPresence()
+  const supported = presence === 'present' && isAgentWorkspaceSupported()
+  const workspacesQuery = useQuery({ ...desktopAgentWorkspacesQueryOptions(), enabled: supported })
+
+  const addMutation = useMutation({
+    mutationFn: async () => (await getDesktopBridge()?.pickDirectory?.()) ?? null,
+    onSuccess: async (picked) => {
+      if (!picked) return // 用户取消对话框
+      await queryClient.invalidateQueries({ queryKey: DESKTOP_AGENT_QUERY_KEY })
+      onSelect(picked)
+    },
+    onError: () => {
+      toast.error(m.agent_desktop_workspaceAddFailed())
+    },
+  })
+
+  const removeMutation = useMutation({
+    mutationFn: async (path: string) => {
+      await getDesktopBridge()?.removeWorkspace?.(path)
+    },
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: DESKTOP_AGENT_QUERY_KEY }),
+    onError: () => {
+      toast.error(m.agent_desktop_workspaceRemoveFailed())
+    },
+  })
+
+  const workspaces = workspacesQuery.data ?? []
+  const loadingBody = (
+    <div className="flex flex-col gap-2">
+      <Skeleton className="h-12 w-full" />
+      <Skeleton className="h-12 w-full" />
+    </div>
+  )
+
+  let body: React.ReactNode
+  if (presence === 'pending') {
+    // 门控探测 / 冷启动有界重试中：按加载态渲染，不提前报「请升级客户端」
+    body = loadingBody
+  } else if (!supported) {
+    body = <p className="text-sm text-muted-foreground">{m.agent_desktop_workspaceUnsupported()}</p>
+  } else if (workspacesQuery.isPending) {
+    body = loadingBody
+  } else if (workspacesQuery.isError) {
+    body = <p className="text-sm text-destructive">{m.agent_desktop_workspaceLoadFailed()}</p>
+  } else if (workspaces.length === 0) {
+    body = (
+      <Empty className="border p-6">
+        <EmptyHeader>
+          <EmptyMedia variant="icon">
+            <FolderOpen />
+          </EmptyMedia>
+          <EmptyTitle>{m.agent_desktop_workspaceEmpty()}</EmptyTitle>
+          <EmptyDescription>{m.agent_desktop_workspaceEmptyHint()}</EmptyDescription>
+        </EmptyHeader>
+      </Empty>
+    )
+  } else {
+    body = (
+      <RadioGroup
+        value={selected ?? ''}
+        onValueChange={(value) => {
+          if (typeof value === 'string' && value !== '') onSelect(value)
+        }}
+        disabled={disabled}
+        className="gap-2"
+      >
+        {workspaces.map((path, index) => {
+          const id = `desktop-agent-workspace-${index}`
+          const checked = path === selected
+          return (
+            <div
+              key={path}
+              className={cn(
+                'flex items-center gap-3 rounded-lg border px-3 py-2 transition-colors',
+                checked ? 'border-primary/60 bg-primary/5' : 'hover:border-primary/30',
+              )}
+            >
+              <RadioGroupItem value={path} id={id} />
+              <Label htmlFor={id} className="min-w-0 flex-1 cursor-pointer flex-col items-start gap-1">
+                <span className="w-full truncate text-sm font-medium">{folderNameOf(path)}</span>
+                <span className="w-full truncate text-xs font-normal text-muted-foreground">{path}</span>
+              </Label>
+              <Tooltip>
+                <TooltipTrigger
+                  render={
+                    <Button
+                      variant="ghost"
+                      size="icon-sm"
+                      aria-label={m.agent_desktop_workspaceRemove()}
+                      disabled={disabled || removeMutation.isPending}
+                      onClick={() => removeMutation.mutate(path)}
+                    />
+                  }
+                >
+                  <X />
+                </TooltipTrigger>
+                <TooltipContent>{m.agent_desktop_workspaceRemove()}</TooltipContent>
+              </Tooltip>
+            </div>
+          )
+        })}
+      </RadioGroup>
+    )
+  }
+
+  return (
+    <Card className="gap-4">
+      <CardHeader>
+        <CardTitle>{m.agent_desktop_workspaceTitle()}</CardTitle>
+        <CardDescription>{m.agent_desktop_workspaceDescription()}</CardDescription>
+        {supported && (
+          <CardAction>
+            <Button
+              variant="outline"
+              size="sm"
+              disabled={addMutation.isPending}
+              onClick={() => addMutation.mutate()}
+            >
+              {addMutation.isPending ? <Loader2 className="animate-spin" /> : <FolderPlus />}
+              {m.agent_desktop_workspaceAdd()}
+            </Button>
+          </CardAction>
+        )}
+      </CardHeader>
+      <CardContent>{body}</CardContent>
+    </Card>
+  )
+}

package/src/components/layout/sidebar-03/app-sidebar.tsx

@@ -32,7 +32,7 @@ import { NavKnowledge } from "@/components/layout/sidebar-03/nav-knowledge";
 import { NavWorkspace } from "@/components/layout/sidebar-03/nav-workspace";
 import { UserMenu } from "@/components/layout/sidebar-03/user-menu";
 import { AnimatedThemeToggler } from '@/components/magicui/animated-theme-toggler'
-import { workspaceRoutes } from "@/config/sidebar-routes";
+import { desktopAgentRoute, workspaceRoutes } from "@/config/sidebar-routes";
 import type { Route } from "@/config/sidebar-routes";
 import { PresenceAvatarStack } from "@/components/layout/sidebar-03/presence-avatar-stack";
 import { SidebarSearchTrigger } from "@/components/layout/sidebar-03/nav-search-trigger"
@@ -40,6 +40,7 @@ import { NavSecondary } from "@/components/layout/sidebar-03/nav-secondary"
 import { PluginNavItems } from '@/components/plugin-slots/plugin-nav-items'
 import { isDesktopEdition } from "@/lib/edition-desktop";
 import { getDesktopBridge } from "@/lib/desktop-bridge-types";
+import { useDesktopAgentPresence } from "@/lib/desktop-agent/use-desktop-agent-presence";
 
 // presence 渲染工厂（§8.2 消费者两文件之一）：nav-main 按 route.id 查
 // MODULE_ROUTES 得 module key 后回调；module 级单例 map，identity 稳定。
@@ -47,10 +48,16 @@ const routes: Route[] = workspaceRoutes.map((route) => ({
   ...route,
   presence: (module: string) => <PresenceAvatarStack module={module} />,
 }));
+// 桌面壳追加本地文件助手入口（P3-B5）：module 级常量保 identity 稳定
+const routesWithDesktopAgent: Route[] = [...routes, desktopAgentRoute];
 
 export function DashboardSidebar() {
   const { state } = useSidebar();
   const isCollapsed = state === "collapsed";
+  // 本地文件助手入口门控（与 /_nav/agent 路由同源判定）：SSR / hydration 首帧恒
+  // pending（不渲染该项，首帧一致），挂载后桌面壳恢复；云 Web / OSS 恒不可见
+  const desktopAgentPresence = useDesktopAgentPresence();
+  const navRoutes = desktopAgentPresence === "present" ? routesWithDesktopAgent : routes;
   // 桌面壳（Electron hiddenInset）：红绿灯悬浮在窗口左上角，顶栏重排为
   // 「第一行红绿灯让位 + 右侧按钮组（整行可拖动窗口）、第二行 logo」。
   // web/云端 SaaS 布局不变（isDesktopEdition 为构建期常量，死分支消除）。
@@ -149,7 +156,7 @@ export function DashboardSidebar() {
         )}
       </SidebarHeader>
       <SidebarContent className="gap-4 px-2 py-4">
-        <DashboardNavigation routes={routes} />
+        <DashboardNavigation routes={navRoutes} />
         <NavWorkspace />
         <NavKnowledge />
         <PluginNavItems />

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/changelog/sdk-versions.ts

@@ -112,7 +112,7 @@ export const SDK_GROUPS: SdkGroup[] = [
     "items": [
       {
         "name": "@allbluecn/web-app",
-        "version": "v0.23.3",
+        "version": "v0.23.5",
         "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' }),
+    )
+  })
+})