@allbluecn/web-app 0.23.3 → 0.23.5

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

package/src/lib/desktop-agent/__tests__/use-desktop-agent-presence.test.tsx

@@ -0,0 +1,181 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手入口门控（桌面本地优先 P3-B5）：路由页与侧栏入口同源判定——
+// 桌面构建（VITE_DEPLOY_TARGET=desktop，与路由 beforeLoad 同口径）× 存在
+// desktopBridge × agent 已装配（appInfo.agentPort 为数字，与 Pro main 侧 B4 广播
+// 语义一致：null = 未就绪 → 隐藏入口）。首帧恒 pending（SSR 无 window，hydration
+// 首帧须与 SSR 一致）；「桌面 + 有桥 + 端口未广播」走 1s 间隔、累计约 20s 的
+// 有界重试（冷启动 backend 约 3s 才广播，单次探测会让入口整会话消失）。
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, renderHook } from '@testing-library/react'
+import { renderToString } from 'react-dom/server'
+import {
+  DESKTOP_AGENT_RETRY_BUDGET_MS,
+  DESKTOP_AGENT_RETRY_INTERVAL_MS,
+  useDesktopAgentPresence,
+} from '../use-desktop-agent-presence'
+
+const state = vi.hoisted(() => ({
+  desktopEdition: true as boolean,
+  bridge: null as unknown,
+}))
+
+vi.mock('@/lib/edition-desktop', () => ({
+  isDesktopEdition: () => state.desktopEdition,
+}))
+vi.mock('@/lib/desktop-bridge-types', () => ({
+  getDesktopBridge: () => state.bridge,
+}))
+
+const BASE_INFO = { version: '1.0.0', clientId: 'c1', platform: 'darwin', backendPort: 51000 }
+
+/** 桥 + 可定制 appInfo（agent 装配状态由 appInfo 返回值决定） */
+function bridgeWith(appInfoImpl: () => Promise<unknown>) {
+  const appInfo = vi.fn(appInfoImpl)
+  state.bridge = { appInfo }
+  return appInfo
+}
+
+/** 推进假时钟（含微任务），用于驱动重试链 */
+async function advance(ms: number) {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(ms)
+  })
+}
+
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+  state.desktopEdition = true
+  state.bridge = null
+})
+
+describe('useDesktopAgentPresence', () => {
+  it('桌面构建 + 有桥 + agent 已装配（agentPort 为数字）→ 首次探测即 present，不再重试', async () => {
+    const appInfo = bridgeWith(async () => ({ ...BASE_INFO, agentPort: 4567, agentToken: 'tok' }))
+    const { result } = renderHook(() => useDesktopAgentPresence())
+    expect(result.current).toBe('pending')
+    await advance(0)
+    expect(result.current).toBe('present')
+    await advance(DESKTOP_AGENT_RETRY_INTERVAL_MS * 3)
+    expect(appInfo).toHaveBeenCalledTimes(1)
+  })
+
+  it('冷启动：首次 agentPort=null → 下一次探测拿到数字 → present 并停止重试', async () => {
+    const appInfo = vi
+      .fn<() => Promise<unknown>>()
+      .mockResolvedValueOnce({ ...BASE_INFO, agentPort: null, agentToken: null })
+      .mockResolvedValue({ ...BASE_INFO, agentPort: 4567, agentToken: 'tok' })
+    state.bridge = { appInfo }
+    const { result } = renderHook(() => useDesktopAgentPresence())
+    expect(result.current).toBe('pending')
+
+    await advance(0)
+    expect(appInfo).toHaveBeenCalledTimes(1)
+    expect(result.current).toBe('pending') // 仍在窗口内：保持 pending，不报不可用
+
+    await advance(DESKTOP_AGENT_RETRY_INTERVAL_MS)
+    expect(appInfo).toHaveBeenCalledTimes(2)
+    expect(result.current).toBe('present')
+
+    await advance(DESKTOP_AGENT_RETRY_INTERVAL_MS * 5)
+    expect(appInfo).toHaveBeenCalledTimes(2) // 就绪即停，无残余 timer
+    expect(result.current).toBe('present')
+  })
+
+  it('agentPort 持续 null（未装配 / 旧壳无该字段）→ 重试到预算上限后 absent 并停止', async () => {
+    const appInfo = bridgeWith(async () => ({ ...BASE_INFO, agentPort: null, agentToken: null }))
+    const { result } = renderHook(() => useDesktopAgentPresence())
+    await advance(0)
+    expect(result.current).toBe('pending')
+
+    // 预算内一直 pending（入口尚未出现，但也没有被判死）
+    await advance(DESKTOP_AGENT_RETRY_BUDGET_MS - DESKTOP_AGENT_RETRY_INTERVAL_MS)
+    expect(result.current).toBe('pending')
+
+    await advance(DESKTOP_AGENT_RETRY_INTERVAL_MS)
+    expect(result.current).toBe('absent')
+
+    const calls = appInfo.mock.calls.length
+    expect(calls).toBe(DESKTOP_AGENT_RETRY_BUDGET_MS / DESKTOP_AGENT_RETRY_INTERVAL_MS + 1)
+    await advance(DESKTOP_AGENT_RETRY_INTERVAL_MS * 5)
+    expect(appInfo).toHaveBeenCalledTimes(calls) // 达上限即停
+  })
+
+  it('旧壳（appInfo 无 agent 字段）同样走重试 → 上限后 absent', async () => {
+    const appInfo = bridgeWith(async () => BASE_INFO)
+    const { result } = renderHook(() => useDesktopAgentPresence())
+    await advance(DESKTOP_AGENT_RETRY_BUDGET_MS)
+    expect(result.current).toBe('absent')
+    expect(appInfo).toHaveBeenCalledTimes(DESKTOP_AGENT_RETRY_BUDGET_MS / DESKTOP_AGENT_RETRY_INTERVAL_MS + 1)
+  })
+
+  it('appInfo 持续抛错（IPC 断开 / main 未就绪）→ 重试到上限后 absent，不炸整页', async () => {
+    bridgeWith(async () => {
+      throw new Error('ipc closed')
+    })
+    const { result } = renderHook(() => useDesktopAgentPresence())
+    await advance(DESKTOP_AGENT_RETRY_BUDGET_MS)
+    expect(result.current).toBe('absent')
+  })
+
+  it('重试窗口内 appInfo 抛错后恢复 → 下一次探测成功即 present', async () => {
+    const appInfo = vi
+      .fn<() => Promise<unknown>>()
+      .mockRejectedValueOnce(new Error('ipc closed'))
+      .mockResolvedValue({ ...BASE_INFO, agentPort: 4567, agentToken: 'tok' })
+    state.bridge = { appInfo }
+    const { result } = renderHook(() => useDesktopAgentPresence())
+    await advance(0)
+    expect(result.current).toBe('pending')
+    await advance(DESKTOP_AGENT_RETRY_INTERVAL_MS)
+    expect(result.current).toBe('present')
+  })
+
+  it('重试中卸载 → 清理 timer，不再发起探测', async () => {
+    const appInfo = bridgeWith(async () => ({ ...BASE_INFO, agentPort: null }))
+    const { result, unmount } = renderHook(() => useDesktopAgentPresence())
+    await advance(0)
+    expect(appInfo).toHaveBeenCalledTimes(1)
+    unmount()
+    await advance(DESKTOP_AGENT_RETRY_INTERVAL_MS * 5)
+    expect(appInfo).toHaveBeenCalledTimes(1)
+    expect(result.current).toBe('pending')
+  })
+
+  it('桌面构建但无桥（浏览器直开桌面 backend 端口）→ 终态 absent，不调 appInfo、不重试', async () => {
+    const appInfo = vi.fn(async () => ({ ...BASE_INFO, agentPort: 4567 }))
+    state.bridge = null
+    const { result } = renderHook(() => useDesktopAgentPresence())
+    await advance(0)
+    expect(result.current).toBe('absent')
+    await advance(DESKTOP_AGENT_RETRY_INTERVAL_MS * 3)
+    expect(appInfo).not.toHaveBeenCalled()
+  })
+
+  it('非桌面构建（云 Web / OSS）即使注入了桥对象也 → 终态 absent（与路由 beforeLoad 404 一致，入口不成死链）', async () => {
+    state.desktopEdition = false
+    const appInfo = bridgeWith(async () => ({ ...BASE_INFO, agentPort: 4567 }))
+    const { result } = renderHook(() => useDesktopAgentPresence())
+    await advance(0)
+    expect(result.current).toBe('absent')
+    await advance(DESKTOP_AGENT_RETRY_INTERVAL_MS * 3)
+    expect(appInfo).not.toHaveBeenCalled()
+  })
+
+  it('SSR / hydration 首帧恒 pending（不读 window，服务端与客户端首帧一致）', () => {
+    bridgeWith(async () => ({ ...BASE_INFO, agentPort: 4567 }))
+    let firstRender: string | null = null
+    function Probe() {
+      firstRender = useDesktopAgentPresence()
+      return null
+    }
+    renderToString(<Probe />)
+    expect(firstRender).toBe('pending')
+  })
+})

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

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 桌面本地助手的运行时可用性判定（单一来源）：入口门控、页面与卡片降级共用，
+// 避免「侧栏入口 / 页面 / 卡片」三处各自判一套口径。
+//
+// 两层判定：
+// - agent 可用（resolveDesktopAgentAvailability）：桌面构建 × 存在 desktopBridge ×
+//   agent 已装配。第三项与 Pro main 侧 B4 广播契约同口径——`appInfo.agentPort`
+//   为 null/undefined 表示 AgentService 尚未就绪（DESKTOP_AGENT 门控未开 / bundle
+//   装配失败 / backend 启动窗口期），renderer 据此隐藏 agent 入口；否则入口可见
+//   但页面打开后用户输入才报「服务未就绪」。
+//   单次探测分三态：present 已就绪 / retry 桌面+有桥但端口未广播（**可重试**，
+//   冷启动时 renderer 挂载早于 backend 广播约 3s，单次判定会把入口误判为不可用）/
+//   absent 终态不可用（非桌面构建 / 无桥，重试无意义）。
+// - 目录授权可用（isAgentWorkspaceSupported）：B1 起的三方法（pickDirectory /
+//   listWorkspaces / removeWorkspace）齐备，旧壳缺失 → 整页降级升级提示。
+import { getDesktopBridge } from '@/lib/desktop-bridge-types'
+import { isDesktopEdition } from '@/lib/edition-desktop'
+
+export type DesktopAgentAvailability = 'present' | 'retry' | 'absent'
+
+/** 单次探测（appInfo 经 IPC 取 main 侧端口广播）。appInfo 抛错（IPC 断开 / main
+ *  未就绪）与「端口未广播」同归 retry——重试由调用方（presence hook）做有界收敛，
+ *  到上限仍不就绪才落 absent。 */
+export async function resolveDesktopAgentAvailability(): Promise<DesktopAgentAvailability> {
+  if (!isDesktopEdition()) return 'absent'
+  const bridge = getDesktopBridge()
+  if (!bridge) return 'absent'
+  const info = await bridge.appInfo().catch(() => null)
+  return typeof info?.agentPort === 'number' ? 'present' : 'retry'
+}
+
+/** 目录授权三方法齐备（B1 旧壳无此三方法）；非桌面 / 无桥同样 false */
+export function isAgentWorkspaceSupported(): boolean {
+  const bridge = getDesktopBridge()
+  return Boolean(bridge?.pickDirectory && bridge.listWorkspaces && bridge.removeWorkspace)
+}

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

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手的 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。
+//
+// 为什么包一层而不是直接 fetchServerSentEvents(url, options)：其 url 参数只接受
+// 同步 getter，且在 connect() 内先于（可异步的）options 求值——URL 无法来自同一次
+// 调用里 await 的 appInfo。包装只做「await appInfo → 构造 fetchServerSentEvents →
+// 原样委托 connect」，SSE 解析/AG-UI 协议/abort 全部是官方实现，无自定义协议面。
+//
+// 请求线格式（与 Pro 端点的跨仓契约，见 agent-service.ts extractCwd/extractPrompt）：
+// cwd 由 useChat `forwardedProps: { cwd }` 进 RunAgentInput.forwardedProps；端点
+// 取 messages 末条 user 消息为 prompt；X-Run-Id 头由官方客户端自动附带（端点预检已放行）。
+import { fetchServerSentEvents } from '@tanstack/ai-client'
+import type { ConnectConnectionAdapter } from '@tanstack/ai-client'
+import { getDesktopBridge } from '@/lib/desktop-bridge-types'
+
+export interface DesktopAgentEndpoint {
+  /** `http://127.0.0.1:{agentPort}/prompt` */
+  url: string
+  /** X-Desktop-Token 访问令牌（AgentService 每次启动随机生成） */
+  token: string
+}
+
+/** agent 端点不可用：无桥（云 Web / OSS）、旧壳（appInfo 无 agent 字段）、或
+ *  agent 未装配（DESKTOP_AGENT 门控未开 / bundle 装配失败 → agentPort null） */
+export class DesktopAgentUnavailableError extends Error {
+  constructor() {
+    super('desktop agent endpoint unavailable')
+    this.name = 'DesktopAgentUnavailableError'
+  }
+}
+
+/** 调用时读取当前 agent 端点；不可用返回 null（端口/令牌非法同样视为不可用，不拼坏 URL） */
+export async function resolveDesktopAgentEndpoint(): Promise<DesktopAgentEndpoint | null> {
+  const bridge = getDesktopBridge()
+  if (!bridge) return null
+  // main 未就绪 / IPC 断开时 appInfo 会抛错：归「服务未就绪」（不可用 → 上层抛
+  // DesktopAgentUnavailableError），不把原生错误原文当「运行失败：<原文>」透出
+  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 }
+}
+
+/**
+ * useChat 的 connection：每次 connect 懒取端点后委托官方 fetchServerSentEvents。
+ * `resolveEndpoint` 可注入（测试 / 未来多端点），缺省读 desktopBridge.appInfo。
+ */
+export function createDesktopAgentConnection(
+  resolveEndpoint: () => Promise<DesktopAgentEndpoint | null> = resolveDesktopAgentEndpoint,
+): ConnectConnectionAdapter {
+  return {
+    async *connect(messages, data, abortSignal, runContext) {
+      const endpoint = await resolveEndpoint()
+      if (!endpoint) throw new DesktopAgentUnavailableError()
+      yield* fetchServerSentEvents(endpoint.url, {
+        headers: { 'X-Desktop-Token': endpoint.token },
+      }).connect(messages, data, abortSignal, runContext)
+    },
+  }
+}

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

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手错误文案映射（桌面本地优先 P3-B5）：把 useChat 的 error 态翻译成
+// 用户可读的 i18n 文案。三类可归因错误：
+// - 端点不可用（DesktopAgentUnavailableError）：无桥 / 旧壳 / agent 未装配
+// - 端点非 2xx（@tanstack/ai-client StreamHttpError，带 status）：401 令牌失效
+//   （backend 重启换了令牌，下一问懒取即恢复）、403 目录未授权或 origin 被拒
+// - 网络层（StreamReadError）：端口不通、CORS 预检被拒（浏览器只给 TypeError）
+// 其余（RUN_ERROR 的 agent 失败原因、400/5xx 等）原文透出，便于排障。
+import { m } from '@/paraglide/messages.js'
+
+export function describeDesktopAgentError(error: Error): string {
+  if (error.name === 'DesktopAgentUnavailableError') return m.agent_desktop_errorUnavailable()
+  const status = (error as { status?: unknown }).status
+  if (status === 401) return m.agent_desktop_errorUnauthorized()
+  if (status === 403) return m.agent_desktop_errorForbidden()
+  if (error.name === 'StreamReadError') return m.agent_desktop_errorConnection()
+  return m.agent_desktop_errorGeneric({ message: error.message || String(error) })
+}

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

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手工具结果解析（桌面本地优先 P3-B5）：把 pi 只读四件套
+// （read / grep / find / ls）的结果整理成「文件名 / 命中行」条目，供折叠卡片渲染。
+//
+// 数据来路：B3 mapper 产出 TOOL_CALL_RESULT.content = JSON.stringify(pi
+// AgentToolResult = { content: [{ type: 'text', text }], details })；TanStack
+// processor 收到后 JSON.parse 挂到 tool-call part.output（tool-result part 另存
+// 原串，作回落）。文本格式按 pi-coding-agent 1.4 源码（dist/core/tools/*.js）：
+// - grep：命中行 `path:N: text`，上下文行 `path-N- text`（不计命中）
+// - ls：一行一个条目，目录带 `/` 后缀；find：一行一个相对路径
+// - read：文件原文
+// - 尾段 `\n\n[...]` 是 pi 的截断/续读提示（limit reached / Use offset= …）
+// - 空结果哨兵：`No matches found` / `(empty directory)` / `No files found matching pattern`
+
+export type AgentToolKind = 'read' | 'grep' | 'find' | 'ls' | 'other'
+
+export type AgentToolEntry =
+  /** ls / find：文件或目录（目录保留 `/` 后缀） */
+  | { kind: 'file'; path: string }
+  /** grep：命中行 */
+  | { kind: 'hit'; path: string; line: number; text: string }
+  /** read 内容行 / 未知工具文本行 */
+  | { kind: 'text'; text: string }
+
+export interface AgentToolSummary {
+  kind: AgentToolKind
+  /** 工具目标：read/ls 的路径（ls 缺省 `.`）、grep/find 的模式；未知工具 null */
+  target: string | null
+  /** 展示条目（截至 AGENT_TOOL_MAX_ENTRIES） */
+  entries: AgentToolEntry[]
+  /** 条目总数（截断前） */
+  total: number
+  /** pi 侧结果已截断（尾段提示存在） */
+  truncated: boolean
+  /** pi 空结果哨兵（无匹配 / 空目录 / 无文件） */
+  empty: boolean
+}
+
+/** 折叠卡片单个工具最多展示的条目数（其余以「还有 N 项」提示） */
+export const AGENT_TOOL_MAX_ENTRIES = 50
+
+const EMPTY_SENTINELS = new Set(['No matches found', '(empty directory)', 'No files found matching pattern'])
+
+/** pi 尾段提示的措辞特征——只认这些，正文恰以方括号结尾时不误剥 */
+const PI_NOTICE_RE = /^\[[^\n]*(?:limit reached|Use offset=|more lines in file|Showing lines|exceeds)[^\n]*\]$/
+
+/** grep 命中行：取首个 `:行号: ` 边界（惰性），内容里再出现 `:3: ` 也不误切 */
+const GREP_HIT_RE = /^(.+?):(\d+): (.*)$/
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function tryParseJson(raw: string): unknown {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return undefined
+  }
+}
+
+function textFromParts(parts: readonly unknown[]): string | null {
+  const texts: string[] = []
+  for (const part of parts) {
+    if (!isPlainObject(part) || part.type !== 'text') continue
+    if (typeof part.text === 'string') texts.push(part.text)
+    else if (typeof part.content === 'string') texts.push(part.content)
+  }
+  return texts.length > 0 ? texts.join('\n') : null
+}
+
+function textFromValue(value: unknown): string | null {
+  if (typeof value === 'string') {
+    // processor 对非 JSON content 保留原串；JSON 串（pi AgentToolResult）再解一层
+    const parsed = tryParseJson(value)
+    // 解出的对象/数组里没有 text 块（如 read 图片 → 只有 base64 image 块）：判定为
+    // 无文本，**不**回落原始 JSON 串（否则巨型 base64 会整段铺进折叠卡）
+    if (parsed !== null && typeof parsed === 'object') return textFromValue(parsed)
+    return value
+  }
+  if (Array.isArray(value)) {
+    // tool-result part 回落形态：ContentPart[] 内嵌 JSON 串
+    const joined = textFromParts(value)
+    return joined === null ? null : textFromValue(joined)
+  }
+  if (isPlainObject(value)) {
+    if (Array.isArray(value.content)) return textFromParts(value.content)
+    if (typeof value.error === 'string') return value.error
+  }
+  return null
+}
+
+/** 工具结果文本：优先 tool-call part.output（已解析对象），回落 tool-result part 内容 */
+export function extractAgentToolText(output: unknown, resultContent?: unknown): string | null {
+  return textFromValue(output) ?? textFromValue(resultContent)
+}
+
+/** 工具参数：优先已解析 input；否则解析 arguments 串（流式未完成的 JSON → 空对象） */
+export function parseAgentToolArgs(part: { input?: unknown; arguments?: string }): Record<string, unknown> {
+  if (isPlainObject(part.input)) return part.input
+  const parsed = tryParseJson(part.arguments ?? '')
+  return isPlainObject(parsed) ? parsed : {}
+}
+
+function toolKindOf(name: string): AgentToolKind {
+  return name === 'read' || name === 'grep' || name === 'find' || name === 'ls' ? name : 'other'
+}
+
+function stringArg(value: unknown): string | null {
+  return typeof value === 'string' && value !== '' ? value : null
+}
+
+function targetOf(kind: AgentToolKind, args: Record<string, unknown>): string | null {
+  switch (kind) {
+    case 'grep':
+    case 'find':
+      return stringArg(args.pattern)
+    case 'read':
+      return stringArg(args.path)
+    case 'ls':
+      return stringArg(args.path) ?? '.'
+    default:
+      return null
+  }
+}
+
+/** 剥离 pi 尾段提示：返回正文与是否截断 */
+function splitNotice(text: string): { body: string; truncated: boolean } {
+  const trimmed = text.replace(/\s+$/, '')
+  if (PI_NOTICE_RE.test(trimmed)) return { body: '', truncated: true }
+  const cut = trimmed.lastIndexOf('\n\n')
+  if (cut !== -1 && PI_NOTICE_RE.test(trimmed.slice(cut + 2))) {
+    return { body: trimmed.slice(0, cut), truncated: true }
+  }
+  return { body: trimmed, truncated: false }
+}
+
+function entriesOf(kind: AgentToolKind, lines: string[]): AgentToolEntry[] {
+  switch (kind) {
+    case 'grep':
+      return lines.flatMap((line): AgentToolEntry[] => {
+        const hit = GREP_HIT_RE.exec(line)
+        return hit ? [{ kind: 'hit', path: hit[1]!, line: Number(hit[2]), text: hit[3]! }] : []
+      })
+    case 'ls':
+    case 'find':
+      return lines.filter((line) => line.trim() !== '').map((path) => ({ kind: 'file', path }))
+    default:
+      return lines.map((text) => ({ kind: 'text', text }))
+  }
+}
+
+/** 汇总一次工具调用：目标 + 截断后的展示条目 + 计数/截断/空结果标记 */
+export function summarizeAgentTool(
+  name: string,
+  args: Record<string, unknown>,
+  text: string | null,
+): AgentToolSummary {
+  const kind = toolKindOf(name)
+  const target = targetOf(kind, args)
+  const base = { kind, target, entries: [], total: 0, truncated: false, empty: false }
+  if (text === null) return base
+  if (EMPTY_SENTINELS.has(text.trim())) return { ...base, empty: true }
+  const { body, truncated } = splitNotice(text)
+  const all = body === '' ? [] : entriesOf(kind, body.split('\n'))
+  return { ...base, entries: all.slice(0, AGENT_TOOL_MAX_ENTRIES), total: all.length, truncated }
+}