@allbluecn/web-app 0.23.6 → 0.24.0

package/src/routes/api/auth/__tests__/auth-session-desktop.test.ts

@@ -0,0 +1,194 @@
+// /api/auth/$ 的 GET 桌面回落（useSession 依赖的「我是谁」端点）。
+// 根因：authjs 只认自己的 JWT cookie，桌面壳内（本地免登录 / 云端身份在
+// remote-auth.json）恒返回 null → useSession() 恒 null → 各组件把本地用户当匿名。
+// 修法：仅 GET /api/auth/session 在 desktop 且 authjs 无会话时回落
+// getCurrentSession（authjs → remote-auth 云身份 → guest 影子身份）。
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const H = vi.hoisted(() => ({
+  getSession: vi.fn(),
+  readRemoteAuth: vi.fn(),
+  authJsGet: vi.fn(),
+  authJsPost: vi.fn(),
+  ensureLocalShadowUser: vi.fn(async () => 'local-guest'),
+  desktopServer: true,
+}))
+
+vi.mock('start-authjs', () => ({
+  StartAuthJS: async () => ({ GET: H.authJsGet, POST: H.authJsPost }),
+  getSession: H.getSession,
+}))
+vi.mock('@/lib/auth/auth.config', () => ({
+  getAuthConfig: async () => ({}),
+  resetProfileCache: vi.fn(),
+}))
+vi.mock('@/server/remote-auth', () => ({
+  readRemoteAuth: H.readRemoteAuth,
+}))
+// seed 走真模块会拉起 @allbluecn/database 的模块级 prisma 单例（测试环境无 DB）
+vi.mock('@/server/desktop-bootstrap', () => ({
+  ensureLocalShadowUser: H.ensureLocalShadowUser,
+}))
+
+type AuthRoute = typeof import('../$')['Route']
+
+async function importAuthRoute(desktop: boolean): Promise<AuthRoute> {
+  vi.resetModules()
+  H.desktopServer = desktop
+  vi.doMock('@/server/desktop-guest', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@/server/desktop-guest')>()
+    return { ...actual, isDesktopServer: () => H.desktopServer }
+  })
+  return (await import('../$')).Route
+}
+
+/** 模拟 authjs 的 session 端点响应（无会话 → JSON null） */
+function authJsResponse(body: unknown, init?: ResponseInit): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+    ...init,
+  })
+}
+
+function callGet(Route: AuthRoute, path = '/api/auth/session'): Promise<Response> {
+  const handlers = (Route.options as unknown as {
+    server: { handlers: Record<string, (ctx: { request: Request }) => Promise<Response>> }
+  }).server.handlers
+  return handlers.GET!({ request: new Request(`http://localhost${path}`, { method: 'GET' }) })
+}
+
+describe('/api/auth/session 桌面回落', () => {
+  beforeEach(() => {
+    // 真实桌面后端由 Electron 主进程注入该 env（fail-open 自检的正常路径）：
+    // 测试里显式给出，避免每条用例都打安全告警
+    vi.stubEnv('DESKTOP_USER_DATA_DIR', '/tmp/allblue-desktop-test')
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+    vi.clearAllMocks()
+  })
+
+  it('desktop + 无 authjs cookie → 返回 guest 影子身份（user.id=local-guest）且懒 seed 影子用户', async () => {
+    H.getSession.mockResolvedValue(null)
+    H.readRemoteAuth.mockResolvedValue(null)
+    H.authJsGet.mockResolvedValue(authJsResponse(null))
+
+    const Route = await importAuthRoute(true)
+    const res = await callGet(Route)
+    const data = (await res.json()) as { user?: { id?: string; isGuest?: boolean }; desktopSession?: string }
+
+    expect(res.status).toBe(200)
+    expect(data.user?.id).toBe('local-guest')
+    expect(data.user?.isGuest).toBe(true)
+    expect(data.desktopSession).toBe('guest')
+    // I3：端点命中 guest 时补 seed（不能只靠 root beforeLoad 的 getSessionFn——
+    // 那一步 RPC 失败时这里会下发未落库身份，后续写入撞 FK P2003）
+    expect(H.ensureLocalShadowUser).toHaveBeenCalledTimes(1)
+  })
+
+  it('desktop guest seed 抛错：仅 warn，不阻断「我是谁」响应', async () => {
+    H.getSession.mockResolvedValue(null)
+    H.readRemoteAuth.mockResolvedValue(null)
+    H.authJsGet.mockResolvedValue(authJsResponse(null))
+    H.ensureLocalShadowUser.mockRejectedValueOnce(new Error('db gone'))
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    const Route = await importAuthRoute(true)
+    const res = await callGet(Route)
+    const data = (await res.json()) as { user?: { id?: string } }
+
+    expect(res.status).toBe(200)
+    expect(data.user?.id).toBe('local-guest')
+    expect(warnSpy).toHaveBeenCalled()
+  })
+
+  it('desktop + remoteAuth 云身份 → 返回云 userId（不是 guest），且不 seed guest 影子行', async () => {
+    H.getSession.mockResolvedValue(null)
+    H.readRemoteAuth.mockResolvedValue({
+      userId: 'cloud-user-abc',
+      planName: 'pro',
+      features: {},
+      sessionToken: 'cloud-session-token',
+      username: '云端用户',
+    })
+    H.authJsGet.mockResolvedValue(authJsResponse(null))
+
+    const Route = await importAuthRoute(true)
+    const data = (await (await callGet(Route)).json()) as {
+      user?: { id?: string; name?: string; isGuest?: boolean }
+      desktopSession?: string
+    }
+
+    expect(data.user?.id).toBe('cloud-user-abc')
+    expect(data.user?.name).toBe('云端用户')
+    expect(data.user?.isGuest).toBe(false)
+    expect(data.desktopSession).toBe('cloud')
+    expect(H.ensureLocalShadowUser).not.toHaveBeenCalled()
+  })
+
+  it('非 desktop：authjs 的 null 原样透传（不扩大暴露面）', async () => {
+    H.getSession.mockResolvedValue(null)
+    H.readRemoteAuth.mockResolvedValue(null)
+    H.authJsGet.mockResolvedValue(authJsResponse(null))
+
+    const Route = await importAuthRoute(false)
+    const data = await (await callGet(Route)).json()
+
+    expect(data).toBeNull()
+  })
+
+  it('desktop + 有效 authjs 会话：authjs 结果优先（不追加 desktopSession 标记）', async () => {
+    const authJsSession = { user: { id: 'authjs-user-1', name: '本地账号' }, expires: '2026-12-31' }
+    H.getSession.mockResolvedValue(authJsSession)
+    H.authJsGet.mockResolvedValue(authJsResponse(authJsSession))
+
+    const Route = await importAuthRoute(true)
+    const data = (await (await callGet(Route)).json()) as Record<string, unknown>
+
+    expect((data.user as { id?: string }).id).toBe('authjs-user-1')
+    expect(data.desktopSession).toBeUndefined()
+  })
+
+  it('desktop + 非 session 路径（csrf）：原样透传，不做身份回落', async () => {
+    H.authJsGet.mockResolvedValue(
+      new Response(JSON.stringify({ csrfToken: 't' }), { status: 200, headers: { 'content-type': 'application/json' } }),
+    )
+
+    const Route = await importAuthRoute(true)
+    const data = (await (await callGet(Route, '/api/auth/csrf')).json()) as Record<string, unknown>
+
+    expect(data.csrfToken).toBe('t')
+    expect(H.getSession).not.toHaveBeenCalled()
+  })
+
+  it('POST 原样交给 authjs（登录/登出流程零改动）', async () => {
+    H.authJsPost.mockResolvedValue(new Response('{}', { status: 200 }))
+
+    const Route = await importAuthRoute(true)
+    const handlers = (Route.options as unknown as {
+      server: { handlers: Record<string, (ctx: { request: Request }) => Promise<Response>> }
+    }).server.handlers
+    const res = await handlers.POST!({
+      request: new Request('http://localhost/api/auth/callback/credentials', { method: 'POST' }),
+    })
+
+    expect(H.authJsPost).toHaveBeenCalledTimes(1)
+    expect(res.status).toBe(200)
+  })
+
+  it('透传 authjs 的 Set-Cookie（坏 cookie 清理头不丢）', async () => {
+    H.getSession.mockResolvedValue(null)
+    H.readRemoteAuth.mockResolvedValue(null)
+    H.authJsGet.mockResolvedValue(
+      authJsResponse(null, { headers: { 'content-type': 'application/json', 'set-cookie': 'auth.session-token=; Max-Age=0' } }),
+    )
+
+    const Route = await importAuthRoute(true)
+    const res = await callGet(Route)
+
+    expect(res.headers.getSetCookie().some((c) => c.startsWith('auth.session-token='))).toBe(true)
+    expect(res.headers.get('cache-control')).toBe('no-store')
+  })
+})

package/src/server/__tests__/chat-conversations.test.ts

@@ -142,7 +142,7 @@ describe("createConversationFn", () => {
 
     expect(mocks.findFirst).not.toHaveBeenCalled()
     expect(mocks.create).toHaveBeenCalledWith({
-      data: { userId, agentId: null },
+      data: { userId, agentId: null, engine: "cloud", localCwd: null },
       include: { agent: { select: { name: true, avatarEmoji: true } } },
     })
     expect(result).toMatchObject({
@@ -173,7 +173,7 @@ describe("createConversationFn", () => {
       },
     })
     expect(mocks.create).toHaveBeenCalledWith({
-      data: { userId, agentId },
+      data: { userId, agentId, engine: "cloud", localCwd: null },
       include: { agent: { select: { name: true, avatarEmoji: true } } },
     })
     expect(result).toMatchObject({
@@ -198,7 +198,7 @@ describe("createConversationFn", () => {
 
     expect(mocks.findFirst).not.toHaveBeenCalled()
     expect(mocks.create).toHaveBeenCalledWith({
-      data: { userId, agentId: null },
+      data: { userId, agentId: null, engine: "cloud", localCwd: null },
       include: { agent: { select: { name: true, avatarEmoji: true } } },
     })
   })
@@ -213,6 +213,8 @@ describe("listConversationsFn", () => {
         updatedAt: now,
         isArchived: false,
         agentId: "agent-001",
+        engine: "cloud",
+        localCwd: null,
         _count: { messages: 5 },
         agent: { name: "Researcher", avatarEmoji: "🔬" },
         interrupts: [{ id: "int-001" }],
@@ -223,6 +225,8 @@ describe("listConversationsFn", () => {
         updatedAt: new Date("2026-08-16T08:00:00.000Z"),
         isArchived: false,
         agentId: null,
+        engine: "cloud",
+        localCwd: null,
         _count: { messages: 0 },
         agent: null,
         interrupts: [],
@@ -240,6 +244,8 @@ describe("listConversationsFn", () => {
         title: true,
         isArchived: true,
         agentId: true,
+        engine: true,
+        localCwd: true,
         updatedAt: true,
         _count: { select: { messages: true } },
         agent: { select: { name: true, avatarEmoji: true } },
@@ -254,6 +260,8 @@ describe("listConversationsFn", () => {
         messageCount: 5,
         isArchived: false,
         agentId: "agent-001",
+        engine: "cloud",
+        localCwd: null,
         agentName: "Researcher",
         agentEmoji: "🔬",
         pendingInteraction: true,
@@ -265,6 +273,8 @@ describe("listConversationsFn", () => {
         messageCount: 0,
         isArchived: false,
         agentId: null,
+        engine: "cloud",
+        localCwd: null,
         agentName: null,
         agentEmoji: null,
         pendingInteraction: false,

package/src/server/__tests__/desktop-bootstrap.test.ts

@@ -83,7 +83,6 @@ vi.mock('@/server/entitlements-token', () => ({ generateEntitlementsToken: vi.fn
 vi.mock('@/server/middlewares/rate-limit', () => ({ checkAuthRateLimit: vi.fn() }))
 
 import { prisma } from '@allbluecn/database'
-import { ensureBuiltinIndependentProject } from '@/server/builtin-project'
 import { ensureLocalShadowUser } from '../desktop-bootstrap'
 import { getSessionFn } from '../serverFns/auth/session'
 

package/src/server/ai-gateway/__tests__/local-agent-adapter.test.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  LOCAL_AGENT_GLOBAL_KEY,
+  LocalAgentAdapter,
+  extractLastUserText,
+} from '../local-agent-adapter'
+
+const original = (globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY]
+
+afterEach(() => {
+  if (original === undefined) delete (globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY]
+  else (globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY] = original
+})
+
+function installService(run: (input: unknown) => AsyncIterable<unknown>) {
+  ;(globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY] = {
+    runLocalAgentPrompt: run,
+  }
+}
+
+function options(overrides: Record<string, unknown> = {}) {
+  return {
+    messages: [{ role: 'user', content: '总结这个目录' }],
+    threadId: 'thread-1',
+    runId: 'run-1',
+    modelOptions: { cwd: '/tmp/workspace' },
+    ...overrides,
+  } as never
+}
+
+describe('extractLastUserText', () => {
+  it('取最后一条非空 user 文本（字符串 / text parts 两种形态）', () => {
+    expect(
+      extractLastUserText([
+        { role: 'user', content: 'old' },
+        { role: 'assistant', content: 'answer' },
+        { role: 'user', content: [{ type: 'text', content: 'new' }] },
+      ] as never),
+    ).toBe('new')
+  })
+
+  it('忽略空 user 文本，回退更早的一条', () => {
+    expect(
+      extractLastUserText([
+        { role: 'user', content: 'first' },
+        { role: 'user', content: '   ' },
+      ] as never),
+    ).toBe('first')
+  })
+})
+
+describe('LocalAgentAdapter', () => {
+  it('未装配桌面运行时 → RUN_ERROR，不抛错', async () => {
+    delete (globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY]
+    const events: Array<{ type: string; message?: string }> = []
+    for await (const event of new LocalAgentAdapter().chatStream(options())) {
+      events.push(event as never)
+    }
+    expect(events).toHaveLength(1)
+    expect(events[0]?.type).toBe('RUN_ERROR')
+    expect(events[0]?.message).toContain('本地 Agent 不可用')
+  })
+
+  it('转发 pi 的 AG-UI 事件，并为 RUN_FINISHED 补 finishReason=stop', async () => {
+    const received: unknown[] = []
+    installService(async function* (input) {
+      received.push(input)
+      yield { type: 'RUN_STARTED', threadId: 'thread-1', runId: 'run-1' }
+      yield { type: 'TEXT_MESSAGE_START', messageId: 'm1', role: 'assistant' }
+      yield { type: 'TEXT_MESSAGE_CONTENT', messageId: 'm1', delta: '你好' }
+      yield { type: 'TEXT_MESSAGE_END', messageId: 'm1' }
+      yield { type: 'RUN_FINISHED', threadId: 'thread-1', runId: 'run-1' }
+    })
+
+    const events: Array<Record<string, unknown>> = []
+    for await (const event of new LocalAgentAdapter().chatStream(options())) {
+      events.push(event as never)
+    }
+
+    expect(received[0]).toMatchObject({
+      cwd: '/tmp/workspace',
+      sessionId: 'thread-1',
+      threadId: 'thread-1',
+      runId: 'run-1',
+    })
+    expect(events.map((event) => event.type)).toEqual([
+      'RUN_STARTED',
+      'TEXT_MESSAGE_START',
+      'TEXT_MESSAGE_CONTENT',
+      'TEXT_MESSAGE_END',
+      'RUN_FINISHED',
+    ])
+    expect(events[4]).toMatchObject({ finishReason: 'stop', model: 'local-pi' })
+  })
+
+  it('缺少 cwd → RUN_ERROR', async () => {
+    installService(async function* () {})
+    const events: Array<{ type: string }> = []
+    for await (const event of new LocalAgentAdapter().chatStream(
+      options({ modelOptions: {} }),
+    )) {
+      events.push(event as never)
+    }
+    expect(events[0]?.type).toBe('RUN_ERROR')
+  })
+})

package/src/server/ai-gateway/__tests__/unified-router-local-agent.test.ts

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+
+import { afterEach, describe, expect, it } from 'vitest'
+import { resolveUnifiedAiRoute } from '../unified-router'
+import { LOCAL_AGENT_GLOBAL_KEY } from '../local-agent-adapter'
+
+const originalTarget = process.env.DEPLOY_TARGET
+const originalService = (globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY]
+
+afterEach(() => {
+  if (originalTarget === undefined) delete process.env.DEPLOY_TARGET
+  else process.env.DEPLOY_TARGET = originalTarget
+  if (originalService === undefined) delete (globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY]
+  else (globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY] = originalService
+})
+
+const baseRequest = {
+  userId: 'local-guest',
+  messages: [{ role: 'user' as const, content: '看看这个目录' }],
+  threadId: 'thread-local-1',
+  engine: 'local' as const,
+  localCwd: '/tmp/work',
+}
+
+describe('resolveUnifiedAiRoute — 本地 Agent 引擎', () => {
+  it('非桌面部署 → 拒绝（云端不能走本地文件）', async () => {
+    process.env.DEPLOY_TARGET = 'web'
+    await expect(resolveUnifiedAiRoute(baseRequest)).rejects.toThrow(/仅在桌面客户端可用/)
+  })
+
+  it('桌面但未装配运行时 → 明确报错而不是回落 BYOK', async () => {
+    process.env.DEPLOY_TARGET = 'desktop'
+    delete (globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY]
+    await expect(resolveUnifiedAiRoute(baseRequest)).rejects.toThrow(/运行时未装配/)
+  })
+
+  it('桌面 + 运行时 + cwd → 装配 local 路由（adapter 由声明式 harness 包装）', async () => {
+    process.env.DEPLOY_TARGET = 'desktop'
+    ;(globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY] = {
+      runLocalAgentPrompt: async function* () {},
+    }
+    const route = await resolveUnifiedAiRoute(baseRequest)
+    expect(route.kind).toBe('local')
+    if (route.kind === 'local') {
+      // 只需确认可迭代对象已装配；真正的事件映射在 local-agent-adapter 单测覆盖
+      expect(typeof route.stream[Symbol.asyncIterator]).toBe('function')
+    }
+  })
+
+  it('engine 缺省时不走本地链路（保持云端行为）', async () => {
+    process.env.DEPLOY_TARGET = 'desktop'
+    ;(globalThis as Record<string, unknown>)[LOCAL_AGENT_GLOBAL_KEY] = {
+      runLocalAgentPrompt: async function* () {},
+    }
+    // 没有 engine=local：会进入 BYOK/hosted 解析（测试环境无 provider → NoAiAvailableError），
+    // 关键断言是错误不是「本地 Agent」相关，证明没有误走本地分支
+    await expect(
+      resolveUnifiedAiRoute({ ...baseRequest, engine: undefined }),
+    ).rejects.not.toThrow(/本地 Agent/)
+  })
+})

package/src/server/ai-gateway/chat-handler.ts

@@ -303,6 +303,11 @@ export const chatBodySchema = z.object({
   parentRunId: z.string().max(200).optional(),
   // resume 为 durable run 重放载荷（chunk 数组）：限条数，单条体积随 chunk 契约
   resume: z.array(z.unknown()).max(100).optional(),
+  // 执行引擎（线程级）：cloud=服务端模型；local=桌面 pi 本地 Agent。
+  // 只有 desktop 部署且后端装配 __allblueAgentService 时才允许 local。
+  engine: z.enum(["cloud", "local"]).default("cloud"),
+  /** local 引擎的授权工作目录（桌面壳 workspaces.json 精确匹配复核） */
+  cwd: z.string().min(1).max(1000).optional(),
   promptKey: z.string().max(200).optional(),
   /**
    * 附件列表：图片走 dataURL parts，非图片走服务端 BlobStore ref。
@@ -411,7 +416,12 @@ export async function* handleChatRequest(
   scheduleLazyReap()
 
   const raw = await (options?.body ?? request.json())
-  const body = { ...raw, ...(raw.forwardedProps ?? {}) }
+  // Pro 兼容窗口：旧 OSS 客户端（0.x 信封）把业务字段放在 data 里，经
+  // forwardToSaas 转发进来；forwardedProps 缺省时回落 data。窗口结束后可删。
+  const body = {
+    ...raw,
+    ...(raw.forwardedProps ?? (raw as { data?: Record<string, unknown> }).data ?? {}),
+  }
   // 服务端 overrides 最后落笔（审计 2026-10-25 🟠，原顺序 body 在后展开会把服务端
   // 值覆盖掉）：allowedTools / knowledgeBaseIds / temperature 是 serverFn/agent 侧
   // 下发的服务端约束，客户端 body 不得放宽——否则 agent 收紧的工具白名单被击穿。
@@ -426,11 +436,67 @@ export async function* handleChatRequest(
       `Invalid chat request body [${path}]: ${issue?.message ?? "validation failed"}`,
     )
   }
-  const { messages, allowedTools, knowledgeBaseIds, temperature, webSearchEnabled, codeModeEnabled, sandbox, model, provider, workspaceId, workspaceContext, threadId, runId, parentRunId, resume, attachments } = parsed.data
+  const { messages, allowedTools, knowledgeBaseIds, temperature, webSearchEnabled, codeModeEnabled, sandbox, model, provider, workspaceId, workspaceContext, threadId, runId, parentRunId, resume, attachments, engine, cwd } = parsed.data
   // 1.0 起 threadId 为必填：非 1.0 客户端缺省时由服务端兜底生成（每次请求即新会话），
   // 防 resolveUnifiedAiRoute 的 durability/memory 装配与 SaaS 转发在缺参时静默降级。
   // 空字符串已在 schema 被 min(1) 拒绝，这里只需处理 undefined。
   const effectiveThreadId = threadId ?? crypto.randomUUID()
+
+  // 桌面本地 Agent（pi）：线程级引擎与 cwd 是持久化语义的一部分——
+  // - 既有的 cloud 线程不允许中途改成本地（会让历史消息与 pi 会话错位）；
+  // - 线程必须先落 engine=local 再跑，pi 侧以 threadId 作为 session id 续接。
+  // 鉴权边界仍在桌面壳：cwd 必须精确命中 workspaces.json 授权清单。
+  if (engine === "local") {
+    if (attachments.length > 0) {
+      throw new Error("本地 Agent 不支持附件：请移除附件或切换到云端引擎")
+    }
+    const existing = await prisma.chatThread.findUnique({
+      where: { id: effectiveThreadId },
+      select: { userId: true, engine: true, localCwd: true },
+    })
+    if (existing && existing.userId !== session.user.id) {
+      throw new Error("thread not found")
+    }
+    if (existing && existing.engine !== "local") {
+      throw new Error("该会话不是本地 Agent 会话：请新建会话后选择本地工作区")
+    }
+    if (!existing) {
+      await prisma.chatThread.create({
+        data: {
+          id: effectiveThreadId,
+          userId: session.user.id,
+          engine: "local",
+          localCwd: cwd ?? null,
+        },
+      })
+    } else if (cwd && existing.localCwd !== cwd) {
+      // 同一线程固定工作目录（UI 在已有消息时禁用切换）；服务端兜底更新
+      // 只影响 pi 的 sessionId 派生，不改变历史消息归属。
+      await prisma.chatThread.update({
+        where: { id: effectiveThreadId },
+        data: { localCwd: cwd },
+      })
+    }
+    const localRoute = await resolveUnifiedAiRoute(
+      {
+        userId: session.user.id,
+        messages: messages as any[],
+        threadId: effectiveThreadId,
+        runId,
+        parentRunId,
+        engine: "local",
+        localCwd: cwd,
+        aiSourceMode: session.user.aiSourceMode ?? null,
+      },
+      request,
+    )
+    if (localRoute.kind !== "local") {
+      throw new Error("本地 Agent 路由装配失败")
+    }
+    yield* localRoute.stream
+    return
+  }
+
   // 计费闸只在请求真的启用沙箱时才走：feature 未开通或分钟配额耗尽都在这一步
   // fail-closed，不会白付一次 provider 装配与沙箱创建的成本。
   // 知识库所有权校验：过滤客户端传入的非法 KB ID（非自有/非所属工作空间共享）

package/src/server/ai-gateway/chat-stream-builder.ts

@@ -95,6 +95,13 @@ interface BuildChatStreamParams {
    * 允许 adapter 传 null（后台无 adapter 可用）；非 attach 模式 adapter 必填。
    */
   attach?: boolean
+  /**
+   * 桌面本地 Agent（pi）：true 时跳过服务端工具/技能/沙箱/系统提示装配，
+   * adapter 自己跑 agent loop（只读四件套由桌面壳强制）。
+   */
+  localAgent?: boolean
+  /** localAgent 的授权工作目录（桌面壳会再次复核 workspaces.json） */
+  localCwd?: string
 }
 
 /**
@@ -126,6 +133,51 @@ export async function buildChatStreamWithTools(
     throw new Error("buildChatStreamWithTools: 非 attach 模式必须提供 adapter")
   }
 
+  // 本地 Agent 是 harness adapter：pi 自己跑工具循环。服务端工具池、技能、
+  // Code Mode、沙箱与系统提示全部不参与（pi 的封闭 ResourceLoader 自带提示词，
+  // 且只读四件套由桌面壳的 path-guard 强制）。持久化/取消/工具卡仍走同一份
+  // chat() + withPersistence，保证 Harness 的 thread/run 语义不变。
+  if (params.localAgent) {
+    const localThreadId = params.threadId ?? randomUUID()
+    const localPersistence = createPrismaPersistence(params.userId)
+    const localContext: AppContext = {
+      userId: params.userId,
+      db: prisma,
+      threadId: localThreadId,
+      provider: 'local-pi',
+      model: 'local-pi',
+      runId: params.runId,
+      workspaceContext: params.localCwd
+        ? { type: 'local', path: params.localCwd }
+        : undefined,
+    }
+    return chat({
+      adapter: params.adapter,
+      messages: params.messages,
+      tools: [],
+      threadId: localThreadId,
+      runId: params.runId,
+      context: localContext,
+      modelOptions: {
+        cwd: params.localCwd,
+        sessionId: localThreadId,
+      },
+      // pi 自带 agent loop：单次 adapter 调用即完整运行，禁止引擎再发起模型轮次
+      agentLoopStrategy: maxIterations(1),
+      middleware: [
+        loggerMiddleware,
+        rateLimitMiddleware,
+        otelMiddleware({ tracer: otelTracer, captureContent: false }),
+        createAiOutputGuardMiddleware(),
+        withPersistence(localPersistence, {
+          snapshotStreaming: true,
+          snapshotIntervalMs: 1500,
+        }),
+        createUsageLogMiddleware({ activity: 'chat' }),
+      ] as any,
+    }) as AsyncIterable<StreamChunk>
+  }
+
   const nativeSearchTools = buildProviderWebSearchTools(
     params.providerConfigKind,
   ) as any[]