@allbluecn/web-app 0.23.7 → 0.24.1

package/src/paraglide/messages/harness_localworkspace_dialogdescription2.js

@@ -0,0 +1,30 @@
+/* eslint-disable */
+import { getLocale, experimentalStaticLocale } from '../runtime.js';
+
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+
+/** @typedef {{}} Harness_Localworkspace_Dialogdescription2Inputs */
+
+const zh_harness_localworkspace_dialogdescription2 = /** @type {(inputs: Harness_Localworkspace_Dialogdescription2Inputs) => LocalizedString} */ () => {
+	return /** @type {LocalizedString} */ (`pi 只能读取下方列出的目录；可随时撤销授权。`)
+};
+
+const en_harness_localworkspace_dialogdescription2 = /** @type {(inputs: Harness_Localworkspace_Dialogdescription2Inputs) => LocalizedString} */ () => {
+	return /** @type {LocalizedString} */ (`pi can only read the folders listed below; revoke access at any time.`)
+};
+
+/**
+* | output |
+* | --- |
+* | "pi can only read the folders listed below; revoke access at any time." |
+*
+* @param {Harness_Localworkspace_Dialogdescription2Inputs} inputs
+* @param {{ locale?: "zh" | "en" }} options
+* @returns {LocalizedString}
+*/
+const harness_localworkspace_dialogdescription2 = /** @type {((inputs?: Harness_Localworkspace_Dialogdescription2Inputs, options?: { locale?: "zh" | "en" }) => LocalizedString) & import('../runtime.js').MessageMetadata<Harness_Localworkspace_Dialogdescription2Inputs, { locale?: "zh" | "en" }, {}>} */ ((inputs = {}, options = {}) => {
+	const locale = experimentalStaticLocale ?? options.locale ?? getLocale()
+	if (locale === "en") return en_harness_localworkspace_dialogdescription2(inputs)
+	return zh_harness_localworkspace_dialogdescription2(inputs)
+});
+export { harness_localworkspace_dialogdescription2 as "harness_localWorkspace_dialogDescription" }

package/src/paraglide/messages/harness_localworkspace_dialogtitle2.d.ts

@@ -0,0 +1,17 @@
+export { harness_localworkspace_dialogtitle2 as "harness_localWorkspace_dialogTitle" };
+export type LocalizedString = import("../runtime.js").LocalizedString;
+export type Harness_Localworkspace_Dialogtitle2Inputs = {};
+/**
+* | output |
+* | --- |
+* | "Local workspace" |
+*
+* @param {Harness_Localworkspace_Dialogtitle2Inputs} inputs
+* @param {{ locale?: "zh" | "en" }} options
+* @returns {LocalizedString}
+*/
+declare const harness_localworkspace_dialogtitle2: ((inputs?: Harness_Localworkspace_Dialogtitle2Inputs, options?: {
+    locale?: "zh" | "en";
+}) => LocalizedString) & import("../runtime.js").MessageMetadata<Harness_Localworkspace_Dialogtitle2Inputs, {
+    locale?: "zh" | "en";
+}, {}>;

package/src/paraglide/messages/harness_localworkspace_dialogtitle2.js

@@ -0,0 +1,30 @@
+/* eslint-disable */
+import { getLocale, experimentalStaticLocale } from '../runtime.js';
+
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+
+/** @typedef {{}} Harness_Localworkspace_Dialogtitle2Inputs */
+
+const zh_harness_localworkspace_dialogtitle2 = /** @type {(inputs: Harness_Localworkspace_Dialogtitle2Inputs) => LocalizedString} */ () => {
+	return /** @type {LocalizedString} */ (`本地工作区`)
+};
+
+const en_harness_localworkspace_dialogtitle2 = /** @type {(inputs: Harness_Localworkspace_Dialogtitle2Inputs) => LocalizedString} */ () => {
+	return /** @type {LocalizedString} */ (`Local workspace`)
+};
+
+/**
+* | output |
+* | --- |
+* | "Local workspace" |
+*
+* @param {Harness_Localworkspace_Dialogtitle2Inputs} inputs
+* @param {{ locale?: "zh" | "en" }} options
+* @returns {LocalizedString}
+*/
+const harness_localworkspace_dialogtitle2 = /** @type {((inputs?: Harness_Localworkspace_Dialogtitle2Inputs, options?: { locale?: "zh" | "en" }) => LocalizedString) & import('../runtime.js').MessageMetadata<Harness_Localworkspace_Dialogtitle2Inputs, { locale?: "zh" | "en" }, {}>} */ ((inputs = {}, options = {}) => {
+	const locale = experimentalStaticLocale ?? options.locale ?? getLocale()
+	if (locale === "en") return en_harness_localworkspace_dialogtitle2(inputs)
+	return zh_harness_localworkspace_dialogtitle2(inputs)
+});
+export { harness_localworkspace_dialogtitle2 as "harness_localWorkspace_dialogTitle" }

package/src/paraglide/messages/harness_localworkspace_manage1.d.ts

@@ -0,0 +1,17 @@
+export { harness_localworkspace_manage1 as "harness_localWorkspace_manage" };
+export type LocalizedString = import("../runtime.js").LocalizedString;
+export type Harness_Localworkspace_Manage1Inputs = {};
+/**
+* | output |
+* | --- |
+* | "Manage authorized folders" |
+*
+* @param {Harness_Localworkspace_Manage1Inputs} inputs
+* @param {{ locale?: "zh" | "en" }} options
+* @returns {LocalizedString}
+*/
+declare const harness_localworkspace_manage1: ((inputs?: Harness_Localworkspace_Manage1Inputs, options?: {
+    locale?: "zh" | "en";
+}) => LocalizedString) & import("../runtime.js").MessageMetadata<Harness_Localworkspace_Manage1Inputs, {
+    locale?: "zh" | "en";
+}, {}>;

package/src/paraglide/messages/harness_localworkspace_manage1.js

@@ -0,0 +1,30 @@
+/* eslint-disable */
+import { getLocale, experimentalStaticLocale } from '../runtime.js';
+
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+
+/** @typedef {{}} Harness_Localworkspace_Manage1Inputs */
+
+const zh_harness_localworkspace_manage1 = /** @type {(inputs: Harness_Localworkspace_Manage1Inputs) => LocalizedString} */ () => {
+	return /** @type {LocalizedString} */ (`管理授权目录`)
+};
+
+const en_harness_localworkspace_manage1 = /** @type {(inputs: Harness_Localworkspace_Manage1Inputs) => LocalizedString} */ () => {
+	return /** @type {LocalizedString} */ (`Manage authorized folders`)
+};
+
+/**
+* | output |
+* | --- |
+* | "Manage authorized folders" |
+*
+* @param {Harness_Localworkspace_Manage1Inputs} inputs
+* @param {{ locale?: "zh" | "en" }} options
+* @returns {LocalizedString}
+*/
+const harness_localworkspace_manage1 = /** @type {((inputs?: Harness_Localworkspace_Manage1Inputs, options?: { locale?: "zh" | "en" }) => LocalizedString) & import('../runtime.js').MessageMetadata<Harness_Localworkspace_Manage1Inputs, { locale?: "zh" | "en" }, {}>} */ ((inputs = {}, options = {}) => {
+	const locale = experimentalStaticLocale ?? options.locale ?? getLocale()
+	if (locale === "en") return en_harness_localworkspace_manage1(inputs)
+	return zh_harness_localworkspace_manage1(inputs)
+});
+export { harness_localworkspace_manage1 as "harness_localWorkspace_manage" }

package/src/paraglide/messages/harness_localworkspace_required1.d.ts

@@ -0,0 +1,17 @@
+export { harness_localworkspace_required1 as "harness_localWorkspace_required" };
+export type LocalizedString = import("../runtime.js").LocalizedString;
+export type Harness_Localworkspace_Required1Inputs = {};
+/**
+* | output |
+* | --- |
+* | "Choose a local workspace first" |
+*
+* @param {Harness_Localworkspace_Required1Inputs} inputs
+* @param {{ locale?: "zh" | "en" }} options
+* @returns {LocalizedString}
+*/
+declare const harness_localworkspace_required1: ((inputs?: Harness_Localworkspace_Required1Inputs, options?: {
+    locale?: "zh" | "en";
+}) => LocalizedString) & import("../runtime.js").MessageMetadata<Harness_Localworkspace_Required1Inputs, {
+    locale?: "zh" | "en";
+}, {}>;

package/src/paraglide/messages/harness_localworkspace_required1.js

@@ -0,0 +1,30 @@
+/* eslint-disable */
+import { getLocale, experimentalStaticLocale } from '../runtime.js';
+
+/** @typedef {import('../runtime.js').LocalizedString} LocalizedString */
+
+/** @typedef {{}} Harness_Localworkspace_Required1Inputs */
+
+const zh_harness_localworkspace_required1 = /** @type {(inputs: Harness_Localworkspace_Required1Inputs) => LocalizedString} */ () => {
+	return /** @type {LocalizedString} */ (`请先选择本地工作目录`)
+};
+
+const en_harness_localworkspace_required1 = /** @type {(inputs: Harness_Localworkspace_Required1Inputs) => LocalizedString} */ () => {
+	return /** @type {LocalizedString} */ (`Choose a local workspace first`)
+};
+
+/**
+* | output |
+* | --- |
+* | "Choose a local workspace first" |
+*
+* @param {Harness_Localworkspace_Required1Inputs} inputs
+* @param {{ locale?: "zh" | "en" }} options
+* @returns {LocalizedString}
+*/
+const harness_localworkspace_required1 = /** @type {((inputs?: Harness_Localworkspace_Required1Inputs, options?: { locale?: "zh" | "en" }) => LocalizedString) & import('../runtime.js').MessageMetadata<Harness_Localworkspace_Required1Inputs, { locale?: "zh" | "en" }, {}>} */ ((inputs = {}, options = {}) => {
+	const locale = experimentalStaticLocale ?? options.locale ?? getLocale()
+	if (locale === "en") return en_harness_localworkspace_required1(inputs)
+	return zh_harness_localworkspace_required1(inputs)
+});
+export { harness_localworkspace_required1 as "harness_localWorkspace_required" }

package/src/routeTree.gen.ts

@@ -23,7 +23,6 @@ import { Route as LoginLoginRouteRouteImport } from './routes/_login/login/route
 import { Route as LoginRegisterRouteRouteImport } from './routes/_login/register/route'
 import { Route as LoginResetPasswordRouteRouteImport } from './routes/_login/reset-password/route'
 import { Route as LoginVerifyEmailRouteRouteImport } from './routes/_login/verify-email/route'
-import { Route as NavAgentRouteRouteImport } from './routes/_nav/agent/route'
 import { Route as NavAppsRouteRouteImport } from './routes/_nav/apps/route'
 import { Route as NavBugsRouteRouteImport } from './routes/_nav/bugs/route'
 import { Route as NavChangelogRouteRouteImport } from './routes/_nav/changelog/route'
@@ -252,13 +251,6 @@ const LoginVerifyEmailRouteRoute = LoginVerifyEmailRouteRouteImport.update({
 } as any).lazy(() =>
   import('./routes/_login/verify-email/route.lazy').then((d) => d.Route),
 )
-const NavAgentRouteRoute = NavAgentRouteRouteImport.update({
-  id: '/agent',
-  path: '/agent',
-  getParentRoute: () => NavRouteRoute,
-} as any).lazy(() =>
-  import('./routes/_nav/agent/route.lazy').then((d) => d.Route),
-)
 const NavAppsRouteRoute = NavAppsRouteRouteImport.update({
   id: '/apps',
   path: '/apps',
@@ -1131,7 +1123,6 @@ export interface FileRoutesByFullPath {
   '/register': typeof LoginRegisterRouteRoute
   '/reset-password': typeof LoginResetPasswordRouteRoute
   '/verify-email': typeof LoginVerifyEmailRouteRoute
-  '/agent': typeof NavAgentRouteRoute
   '/apps': typeof NavAppsRouteRouteWithChildren
   '/bugs': typeof NavBugsRouteRouteWithChildren
   '/changelog': typeof NavChangelogRouteRoute
@@ -1271,7 +1262,6 @@ export interface FileRoutesByTo {
   '/register': typeof LoginRegisterRouteRoute
   '/reset-password': typeof LoginResetPasswordRouteRoute
   '/verify-email': typeof LoginVerifyEmailRouteRoute
-  '/agent': typeof NavAgentRouteRoute
   '/apps': typeof NavAppsRouteRouteWithChildren
   '/changelog': typeof NavChangelogRouteRoute
   '/dashboard': typeof NavDashboardRouteRoute
@@ -1400,7 +1390,6 @@ export interface FileRoutesById {
   '/_login/register': typeof LoginRegisterRouteRoute
   '/_login/reset-password': typeof LoginResetPasswordRouteRoute
   '/_login/verify-email': typeof LoginVerifyEmailRouteRoute
-  '/_nav/agent': typeof NavAgentRouteRoute
   '/_nav/apps': typeof NavAppsRouteRouteWithChildren
   '/_nav/bugs': typeof NavBugsRouteRouteWithChildren
   '/_nav/changelog': typeof NavChangelogRouteRoute
@@ -1542,7 +1531,6 @@ export interface FileRouteTypes {
     | '/register'
     | '/reset-password'
     | '/verify-email'
-    | '/agent'
     | '/apps'
     | '/bugs'
     | '/changelog'
@@ -1682,7 +1670,6 @@ export interface FileRouteTypes {
     | '/register'
     | '/reset-password'
     | '/verify-email'
-    | '/agent'
     | '/apps'
     | '/changelog'
     | '/dashboard'
@@ -1810,7 +1797,6 @@ export interface FileRouteTypes {
     | '/_login/register'
     | '/_login/reset-password'
     | '/_login/verify-email'
-    | '/_nav/agent'
     | '/_nav/apps'
     | '/_nav/bugs'
     | '/_nav/changelog'
@@ -2073,13 +2059,6 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof LoginVerifyEmailRouteRouteImport
       parentRoute: typeof LoginRouteRoute
     }
-    '/_nav/agent': {
-      id: '/_nav/agent'
-      path: '/agent'
-      fullPath: '/agent'
-      preLoaderRoute: typeof NavAgentRouteRouteImport
-      parentRoute: typeof NavRouteRoute
-    }
     '/_nav/apps': {
       id: '/_nav/apps'
       path: '/apps'
@@ -3372,7 +3351,6 @@ const NavChatRouteWithChildren =
   NavChatRoute._addFileChildren(NavChatRouteChildren)
 
 interface NavRouteRouteChildren {
-  NavAgentRouteRoute: typeof NavAgentRouteRoute
   NavAppsRouteRoute: typeof NavAppsRouteRouteWithChildren
   NavBugsRouteRoute: typeof NavBugsRouteRouteWithChildren
   NavChangelogRouteRoute: typeof NavChangelogRouteRoute
@@ -3394,7 +3372,6 @@ interface NavRouteRouteChildren {
 }
 
 const NavRouteRouteChildren: NavRouteRouteChildren = {
-  NavAgentRouteRoute: NavAgentRouteRoute,
   NavAppsRouteRoute: NavAppsRouteRouteWithChildren,
   NavBugsRouteRoute: NavBugsRouteRouteWithChildren,
   NavChangelogRouteRoute: NavChangelogRouteRoute,

package/src/routes/_nav/harness/$threadId.lazy.tsx

@@ -25,9 +25,26 @@ export const Route = createLazyFileRoute('/_nav/harness/$threadId')({
     // loader 推断类型是 serverFn 的 JSON 序列化形状（role 含 "tool"、parts 为
     // JsonValue），与 HarnessWorkbenchPage 的 UIMessage 入参不结构兼容，
     // 断言是承载性的（审计建议的「免断言」会使 tsc 报错）
-    const messages = Route.useLoaderData() as { messages: UIMessage[] }
+    const data = Route.useLoaderData() as {
+      messages: UIMessage[]
+      conversation: {
+        id: string
+        title: string | null
+        agentId: string | null
+        engine: "cloud" | "local"
+        localCwd: string | null
+        isArchived: boolean
+      } | null
+    }
     // key 强制重建：HarnessWorkbenchPage 以 useState(initialThreadId) 持有会话状态，
     // route param 变化时组件实例被复用，无 key 会残留上一线程的消息
-    return <HarnessWorkbenchPage key={threadId} initialThreadId={threadId} initialMessages={messages.messages} />
+    return (
+      <HarnessWorkbenchPage
+        key={threadId}
+        initialThreadId={threadId}
+        initialMessages={data.messages}
+        initialConversation={data.conversation}
+      />
+    )
   },
 })

package/src/routes/_nav/harness/$threadId.tsx

@@ -17,10 +17,16 @@
 
 import { createFileRoute } from '@tanstack/react-router'
 import { listMessagesFn } from '@/server/serverFns/chat/list-messages'
+import { getConversationFn } from '@/server/serverFns/chat/conversations'
 
 export const Route = createFileRoute('/_nav/harness/$threadId')({
   loader: async ({ params }) => {
-    const messages = await listMessagesFn({ data: { threadId: params.threadId } })
-    return { messages }
+    // 会话元数据（engine/localCwd）与消息并行取：Harness 打开线程时要据此
+    // 还原「云端 / 本地工作区」引擎与目录选择，不能等首条消息再猜。
+    const [messages, conversation] = await Promise.all([
+      listMessagesFn({ data: { threadId: params.threadId } }),
+      getConversationFn({ data: { id: params.threadId } }),
+    ])
+    return { messages, conversation }
   },
 })

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