@allbluecn/web-app 0.23.2 → 0.23.4

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

package/src/lib/desktop-agent/use-desktop-agent-presence.ts

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+// 本地文件助手入口门控（桌面本地优先 P3-B5）：路由页（_nav/agent lazy 组件）与
+// 侧栏入口共用同一判定，保证「入口可见 ⟹ 页面可达」。
+//
+// 判定 = 桌面构建（isDesktopEdition：VITE_DEPLOY_TARGET 构建期常量，与路由
+// beforeLoad 同口径）× 存在 desktopBridge（Electron preload 注入）× agent 已装配
+// （appInfo.agentPort 为数字，见 ./availability）。云 Web / OSS 构建恒 absent
+// （effect 体被常量折叠）；桌面构建被浏览器直开（无桥）也 absent。
+//
+// 有界重试（冷启动窗口）：Electron 冷启动时 renderer 先挂载、backend 约 3s 后才
+// 广播 agentPort——单次探测会把窗口期误判为 absent，使入口在整次会话内消失（要等
+// 导航重挂载/重启）。故「桌面构建 + 有桥 + agentPort 未广播（或 appInfo 抛错）」
+// 按 1s 间隔重试，累计约 20s；一旦拿到端口立即 present 并停止；到上限仍不就绪
+// 才落 absent 并停止。非桌面构建 / 无桥是终态，不重试。卸载清 timer，无泄漏。
+//
+// mounted 模式（与 sync-indicator / cloud-login 同构）：首帧恒 'pending'——SSR
+// 无 window，hydration 首帧必须与服务端输出一致，挂载后再经 IPC 读桥；重试期间
+// 同样保持 'pending'（消费者按加载态渲染，不提前报「不可用」）。
+import { useEffect, useState } from 'react'
+import { resolveDesktopAgentAvailability } from '@/lib/desktop-agent/availability'
+
+export type DesktopAgentPresence = 'pending' | 'present' | 'absent'
+
+/** 重试间隔与总预算（固定间隔，累计约 20s 覆盖 backend 冷启动窗口） */
+export const DESKTOP_AGENT_RETRY_INTERVAL_MS = 1000
+export const DESKTOP_AGENT_RETRY_BUDGET_MS = 20_000
+
+export function useDesktopAgentPresence(): DesktopAgentPresence {
+  const [presence, setPresence] = useState<DesktopAgentPresence>('pending')
+  useEffect(() => {
+    let cancelled = false
+    let timer: ReturnType<typeof setTimeout> | null = null
+    let spent = 0
+
+    const probe = async () => {
+      const availability = await resolveDesktopAgentAvailability()
+      if (cancelled) return
+      // present / absent 都是终态（absent = 非桌面构建或无桥），停止探测
+      if (availability !== 'retry') {
+        setPresence(availability)
+        return
+      }
+      if (spent >= DESKTOP_AGENT_RETRY_BUDGET_MS) {
+        setPresence('absent')
+        return
+      }
+      spent += DESKTOP_AGENT_RETRY_INTERVAL_MS
+      timer = setTimeout(() => {
+        timer = null
+        void probe()
+      }, DESKTOP_AGENT_RETRY_INTERVAL_MS)
+    }
+
+    void probe()
+    return () => {
+      cancelled = true
+      if (timer !== null) clearTimeout(timer)
+    }
+  }, [])
+  return presence
+}

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

@@ -5,8 +5,23 @@
 // 桌面端类型声明（迁移 P5.3/P6）：desktopBridge 桥（Electron preload 暴露）。
 // 仅类型——运行时对象由 Electron preload 注入，浏览器环境无此对象。
 export interface DesktopBridgeApi {
-  appInfo: () => Promise<{ version: string; clientId: string; platform: string; backendPort: number | null }>
+  /** B4 起追加 agentPort/agentToken（本地文件助手 SSE 端点；add-only，不改既有
+   *  字段）：backend utilityProcess 装配 AgentService 后随 appInfo 广播——
+   *  agentPort = 127.0.0.1 随机端口，agentToken = 启动时生成的访问令牌
+   *  （请求须带 X-Desktop-Token 头）。null = agent 未装配（旧壳，或 DESKTOP_AGENT
+   *  门控未开/bundle 装配失败降级），renderer 据此隐藏 agent 入口。 */
+  appInfo: () => Promise<{
+    version: string
+    clientId: string
+    platform: string
+    backendPort: number | null
+    agentPort?: number | null
+    agentToken?: string | null
+  }>
   cloudLogin: (email: string, password: string) => Promise<{ ok: boolean; userId?: string; error?: string }>
+  /** A10 轻量云身份激活：登录成功后取 cloud-session.json 解出的纯 session
+   *  token（renderer 再走 exchangeRemoteTokenFn 换权益并写 remote-auth）。 */
+  exchangeCloudSession: () => Promise<{ ok: boolean; token?: string; error?: string }>
   conflictRpc: (
     method: "list" | "applyLocal" | "keepRemote" | "keepBoth",
     ...args: unknown[]
@@ -18,6 +33,48 @@ export interface DesktopBridgeApi {
   onRenamed: (cb: (info: { table: string; from: string; to: string }) => void) => () => void
   /** macOS 全屏态切换（enter/leave-full-screen）；旧壳无此 API 时 undefined */
   onFullscreenChange?: (cb: (fullscreen: boolean) => void) => () => void
+  /** A8b 归属转移 bind-flow（main 侧阶段编排；本段为 add-only 追加，不改既有段落）：
+   *  - bindBegin：停引擎自动 tick（bind 锁文件）+ PGlite 数据目录文件级快照；
+   *  - bindDone：清快照 + 解锁 + 请求 backend 触发一次 push；
+   *  - bindFail：停 backend → 还原快照 → 重启 backend（恢复 guest 态）+ 解锁。
+   *  转移 serverFn（transferOwnershipFn）由 renderer 自行调用（localhost cookie
+   *  过鉴权），不经本桥。旧壳（无此三方法）undefined。 */
+  bindBegin?: () => Promise<{ ok: boolean; error?: string }>
+  bindDone?: () => Promise<{ ok: boolean; error?: string }>
+  bindFail?: () => Promise<{ ok: boolean; error?: string }>
+  /** A9 登出反向转移（本段为 add-only 追加，不改既有段落）：transferLock 置/清
+   *  转移锁——复用 bind 锁文件（引擎每 tick 判定同源，语义「转移进行中，引擎勿
+   *  tick」）；clearCloudSession 清 cloud-session.json（登出后引擎 guest 守卫回
+   *  idle）。旧壳无此二方法 undefined——renderer 优雅降级（反向转移单事务自身
+   *  原子，锁为防 tick 并发的双保险；旧壳无云会话文件可清，调用方 optional-
+   *  chaining）。 */
+  transferLock?: (action: "begin" | "end") => Promise<{ ok: boolean; error?: string }>
+  clearCloudSession?: () => Promise<{ ok: boolean; error?: string }>
+  /** A11 desktop-state 三态（本段为 add-only 追加，不改既有段落）：main 侧状态机
+   *  （guest | transferring | cloud，数据属主视角）的查询 + 推送双面。查询用于
+   *  页面 reload 后补齐错过的推送事件；推送由 main 侧 bind/登出流 dispatch 时
+   *  发送。旧壳（无此二方法）undefined——徽标与缓存失效监听 optional-chaining
+   *  优雅降级。 */
+  desktopState?: () => Promise<DesktopStatePayload>
+  onDesktopState?: (cb: (payload: DesktopStatePayload) => void) => () => void
+  /** B1 目录授权（本地优先 P3 agent，本段为 add-only 追加，不改既有段落）：
+   *  agent 访问本地文件的授权清单（main 侧 userData/agent/workspaces.json 增删
+   *  查）。授权模型：renderer 不能注入任意路径——唯一添加入口是用户经原生目录
+   *  选择对话框拣选（pickDirectory 成功即写入清单，返回规范化绝对路径；取消返
+   *  回 null），removeWorkspace 撤销授权、listWorkspaces 查询。旧壳（无此三方
+   *  法）undefined——agent 文件面调用方 optional-chaining 优雅降级。 */
+  pickDirectory?: () => Promise<string | null>
+  listWorkspaces?: () => Promise<string[]>
+  removeWorkspace?: (path: string) => Promise<void>
+}
+
+/** A11 desktop-state 三态载荷（main 侧 desktop-state.json 持久化态的广播形状）：
+ *  guest 本地访客属主 / transferring 归属转移进行中 / cloud 云账号属主。 */
+export type DesktopStateKind = "guest" | "transferring" | "cloud"
+
+export interface DesktopStatePayload {
+  kind: DesktopStateKind
+  updatedAt: string
 }
 
 declare global {

package/src/lib/hotkeys/__tests__/registry.test.ts

@@ -23,8 +23,8 @@ import { appHotkeys, findAppHotkeyConflicts, formatAppHotkeyForBadge, CATEGORY_O
 const DECLARED_IDS = Object.keys(appHotkeys) as AppHotkeyId[]
 
 describe("appHotkeys（defineAppHotkeys 官方声明）", () => {
-  it("恰好 25 条声明，且 id 与迁移前注册表对齐", () => {
-    expect(DECLARED_IDS).toHaveLength(25)
+  it("恰好 26 条声明，且 id 与迁移前注册表对齐（+ B5 agent-abort）", () => {
+    expect(DECLARED_IDS).toHaveLength(26)
     expect(DECLARED_IDS).toEqual(
       expect.arrayContaining([
         "shortcuts-panel",
@@ -34,6 +34,7 @@ describe("appHotkeys（defineAppHotkeys 官方声明）", () => {
         "copy-message",
         "chat-prev",
         "chat-next",
+        "agent-abort",
         "command-palette",
         "toggle-theme",
         "goto-dashboard",
@@ -82,9 +83,15 @@ describe("appHotkeys（defineAppHotkeys 官方声明）", () => {
     }
   })
 
-  it("非序列条目为 9 条 chord（Mod+/ 等）", () => {
+  it("非序列条目为 10 条 chord（Mod+/ 等）", () => {
     const chords = DECLARED_IDS.map((id) => appHotkeys[id]!).filter((e) => typeof e.hotkey === "string")
-    expect(chords).toHaveLength(9)
+    expect(chords).toHaveLength(10)
+  })
+
+  it("agent-abort（本地文件助手中止运行）：Mod+. 聊天分类——输入框内同样生效（ignoreInputs auto 对 Mod 组合放行）", () => {
+    const entry = appHotkeys["agent-abort"]
+    expect(entry.hotkey).toBe("Mod+.")
+    expect(entry.meta).toEqual({ descriptionKey: "common_hotkey_desc_agentAbort", category: "聊天" })
   })
 
   it("现网声明零冲突（findAppHotkeyConflicts）", () => {