@geminilight/mindos 0.6.74 → 0.6.75

package/app/__tests__/im/feishu-ws-client.test.ts

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { FeishuConfig } from '@/lib/im/types';
+
+const { startMock, closeMock, wsClientCtor, registerMock } = vi.hoisted(() => {
+  const startMock = vi.fn().mockResolvedValue(undefined);
+  const closeMock = vi.fn();
+  const wsClientCtor = vi.fn();
+  const registerMock = vi.fn(function () { return this; });
+  return { startMock, closeMock, wsClientCtor, registerMock };
+});
+
+vi.mock('@larksuiteoapi/node-sdk', () => ({
+  LoggerLevel: { info: 'info' },
+  EventDispatcher: class MockEventDispatcher {
+    register(handles: unknown) {
+      registerMock(handles);
+      return this;
+    }
+  },
+  WSClient: class MockWSClient {
+    constructor(params: unknown) {
+      wsClientCtor(params);
+    }
+
+    async start(params: unknown) {
+      return await startMock(params);
+    }
+
+    close(params?: unknown) {
+      closeMock(params);
+    }
+  },
+}));
+
+describe('Feishu WS client manager', () => {
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    const mod = await import('@/lib/im/feishu-ws-client');
+    mod.__resetFeishuWSClientForTests();
+  });
+
+  it('starts a WS client once for long connection', async () => {
+    const mod = await import('@/lib/im/feishu-ws-client');
+    const config: FeishuConfig = {
+      app_id: 'cli_xxx',
+      app_secret: 'secret',
+      conversation: { enabled: true, transport: 'long_connection' },
+    };
+
+    await mod.startFeishuWSClient(config);
+    await mod.startFeishuWSClient(config);
+
+    expect(wsClientCtor).toHaveBeenCalledTimes(1);
+    expect(wsClientCtor).toHaveBeenCalledWith(expect.objectContaining({
+      appId: 'cli_xxx',
+      appSecret: 'secret',
+      autoReconnect: true,
+    }));
+    expect(startMock).toHaveBeenCalledTimes(1);
+    expect(registerMock).toHaveBeenCalledWith(expect.objectContaining({
+      'im.message.receive_v1': expect.any(Function),
+    }));
+    expect(mod.getFeishuWSClientStatus().running).toBe(true);
+  });
+
+  it('stops the running WS client', async () => {
+    const mod = await import('@/lib/im/feishu-ws-client');
+    await mod.startFeishuWSClient({
+      app_id: 'cli_xxx',
+      app_secret: 'secret',
+      conversation: { enabled: true, transport: 'long_connection' },
+    });
+
+    mod.stopFeishuWSClient();
+
+    expect(closeMock).toHaveBeenCalled();
+    expect(mod.getFeishuWSClientStatus().running).toBe(false);
+  });
+
+  it('reports configuration errors before trying to connect', async () => {
+    const mod = await import('@/lib/im/feishu-ws-client');
+
+    await expect(mod.startFeishuWSClient({
+      app_id: '',
+      app_secret: 'secret',
+      conversation: { enabled: true, transport: 'long_connection' },
+    })).rejects.toThrow('Feishu App ID and App Secret are required');
+
+    expect(wsClientCtor).not.toHaveBeenCalled();
+  });
+});

package/app/__tests__/settings/custom-provider-form.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { buildDefaultProviderName } from '@/components/settings/useCustomProviderForm';
+
+
+describe('buildDefaultProviderName', () => {
+  it('uses the protocol display name by default', () => {
+    expect(buildDefaultProviderName('openai', [], undefined, 'en')).toBe('OpenAI');
+  });
+
+  it('appends numeric suffixes when the default name already exists', () => {
+    expect(buildDefaultProviderName('openai', ['OpenAI'], undefined, 'en')).toBe('OpenAI 2');
+    expect(buildDefaultProviderName('openai', ['OpenAI', 'OpenAI 2'], undefined, 'en')).toBe('OpenAI 3');
+  });
+
+  it('ignores the currently edited provider name when computing duplicates', () => {
+    expect(buildDefaultProviderName('openai', ['OpenAI'], 'OpenAI', 'en')).toBe('OpenAI');
+  });
+
+  it('uses localized protocol name in Chinese', () => {
+    expect(buildDefaultProviderName('minimax-cn', [], undefined, 'zh')).toBe('MiniMax (国内版)');
+  });
+
+  it('uses LM Studio as the default generated name', () => {
+    expect(buildDefaultProviderName('lm-studio', [], undefined, 'en')).toBe('LM Studio');
+  });
+
+  it('uses vLLM as the default generated name', () => {
+    expect(buildDefaultProviderName('vllm', [], undefined, 'en')).toBe('vLLM');
+  });
+});

package/app/app/api/ask/route.ts

@@ -648,6 +648,8 @@ export async function POST(req: NextRequest) {
         path.join(projectRoot, 'app', 'node_modules', 'pi-mcp-adapter', 'index.ts'),
         // IM extension: 8-platform IM integration (Telegram, Feishu, Discord, Slack, etc.)
         path.join(projectRoot, 'app', 'lib', 'im', 'index.ts'),
+        // pi-subagents: task delegation to subagents with chains, parallel, async support
+        path.join(projectRoot, 'app', 'node_modules', 'pi-subagents', 'index.ts'),
       ],
     });
     await resourceLoader.reload();

package/app/app/api/im/config/route.ts

@@ -35,6 +35,7 @@ export async function PUT(req: NextRequest) {
       credentials?: Record<string, string>;
       conversation?: {
         enabled?: boolean;
+        transport?: 'webhook' | 'long_connection';
         encrypt_key?: string;
         verification_token?: string;
         public_base_url?: string;
@@ -69,6 +70,7 @@ export async function PUT(req: NextRequest) {
       merged.conversation = {
         ...(merged.conversation ?? {}),
         enabled: Boolean(conversation.enabled),
+        transport: conversation.transport ?? merged.conversation?.transport ?? 'webhook',
         encrypt_key: conversation.encrypt_key ?? merged.conversation?.encrypt_key,
         verification_token: conversation.verification_token ?? merged.conversation?.verification_token,
         public_base_url: conversation.public_base_url ?? merged.conversation?.public_base_url,

package/app/app/api/im/webhook/feishu/route.ts

@@ -1,6 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { getPlatformConfig } from '@/lib/im/config';
-import { handleFeishuWebhook } from '@/lib/im/webhook/feishu';
+import { dispatchFeishuWebhook } from '@/lib/im/feishu-dispatcher';
 
 export async function POST(req: NextRequest) {
   try {
@@ -10,9 +10,11 @@ export async function POST(req: NextRequest) {
     }
 
     const body = await req.json();
-    const result = await handleFeishuWebhook({
+    const headers = Object.fromEntries(req.headers.entries());
+    const result = await dispatchFeishuWebhook({
       config,
       body,
+      headers,
     });
 
     return NextResponse.json(result.body, { status: result.status });

package/app/components/ask/FileChip.tsx

@@ -29,7 +29,7 @@ const VARIANT_ICON = {
   upload: { icon: Paperclip, cls: 'text-muted-foreground' },
   image: { icon: ImageIcon, cls: 'text-muted-foreground' },
   skill: { icon: Zap, cls: 'text-[var(--amber)]' },
-  agent: { icon: Bot, cls: 'text-muted-foreground' },
+  agent: { icon: Bot, cls: 'text-[var(--amber)]' },
 } as const;
 
 const VARIANT_STYLE = {

package/app/components/ask/MessageList.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useRef, useEffect, memo, useState, useCallback } from 'react';
-import { Sparkles, Loader2, AlertCircle, Wrench, WifiOff, Zap, Copy, Check, ArrowDown, FolderInput, Search, PenLine, Lightbulb, FileText, Paperclip } from 'lucide-react';
+import { Sparkles, Loader2, AlertCircle, Wrench, WifiOff, Zap, Copy, Check, ArrowDown, FolderInput, Search, PenLine, Lightbulb, FileText, Paperclip, Bot } from 'lucide-react';
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import type { Message, ImagePart } from '@/lib/types';
@@ -111,7 +111,7 @@ function AssistantAgentBadge({ agentName }: { agentName?: string }) {
   if (!agentName) return null;
   return (
     <div className="mb-2 inline-flex items-center gap-1 rounded-full border border-[var(--amber)]/15 bg-[var(--amber)]/8 px-2 py-0.5 text-[10px] font-medium tracking-wide text-[var(--amber)]">
-      <Sparkles size={10} className="shrink-0" />
+      <Bot size={10} className="shrink-0" />
       <span>{agentName}</span>
     </div>
   );

package/app/components/settings/CustomProviderFields.tsx

@@ -25,7 +25,7 @@ export default function CustomProviderFields({
 
   const nameLabel = locale === 'zh' ? '名称' : 'Name';
   const protocolLabel = locale === 'zh' ? '协议' : 'Protocol';
-  const namePlaceholder = locale === 'zh' ? '输入名称' : 'Enter name';
+  const namePlaceholder = locale === 'zh' ? '可选，默认使用协议名称' : 'Optional, defaults to protocol name';
 
   const nameHint = form.isDuplicateName
     ? (locale === 'zh' ? '名称已存在' : 'Name already exists')

package/app/components/settings/CustomProvidersCard.tsx

@@ -119,6 +119,9 @@ export default function CustomProvidersCard({
         onClose={() => setIsModalOpen(false)}
         onSave={handleSaveProvider}
         initialProvider={editingProvider ?? undefined}
+        existingNames={providers
+          .filter((p) => p.id !== editingId)
+          .map((p) => p.name)}
         t={t}
       />
 

package/app/components/settings/useCustomProviderForm.ts

@@ -1,7 +1,7 @@
 'use client';
 
-import { useState, useCallback } from 'react';
-import { type ProviderId } from '@/lib/agent/providers';
+import { useState, useCallback, useMemo, useEffect } from 'react';
+import { type ProviderId, PROVIDER_PRESETS } from '@/lib/agent/providers';
 import { type Provider, generateProviderId } from '@/lib/custom-endpoints';
 
 export type TestState = 'idle' | 'testing' | 'ok' | 'error';
@@ -32,6 +32,29 @@ export interface CustomProviderFormState {
   handleSave: () => void;
 }
 
+export function buildDefaultProviderName(
+  protocol: ProviderId,
+  existingNames: string[] = [],
+  excludeName?: string,
+  locale?: string,
+): string {
+  const preset = PROVIDER_PRESETS[protocol];
+  const baseName = locale === 'zh' ? preset.nameZh : preset.name;
+  const normalizedExisting = new Set(
+    existingNames
+      .filter((name) => name && name !== excludeName)
+      .map((name) => name.trim().toLowerCase()),
+  );
+
+  if (!normalizedExisting.has(baseName.trim().toLowerCase())) return baseName;
+
+  let index = 2;
+  while (normalizedExisting.has(`${baseName} ${index}`.toLowerCase())) {
+    index++;
+  }
+  return `${baseName} ${index}`;
+}
+
 /**
  * Shared form state + test/save logic for provider forms.
  * Used by both the inline form (AiTab) and the modal (ProviderModal).
@@ -47,27 +70,64 @@ export function useCustomProviderForm({
   locale: string;
   existingNames?: string[];
 }): CustomProviderFormState {
-  const [name, setName] = useState(initial?.name ?? '');
-  const [protocol, setProtocol] = useState<ProviderId>(initial?.protocol ?? 'openai');
+  const initialName = useMemo(
+    () => initial?.name ?? buildDefaultProviderName(initial?.protocol ?? 'openai', existingNames, initial?.name, locale),
+    [initial?.name, initial?.protocol, existingNames, locale],
+  );
+
+  const [name, setNameState] = useState(initialName);
+  const [protocol, setProtocolState] = useState<ProviderId>(initial?.protocol ?? 'openai');
   const [apiKey, setApiKey] = useState(initial?.apiKey ?? '');
   const [model, setModel] = useState(initial?.model ?? '');
   const [baseUrl, setBaseUrl] = useState(initial?.baseUrl ?? '');
   const [testResult, setTestResult] = useState<TestResult>({ state: 'idle' });
+  const [nameTouched, setNameTouched] = useState(!!initial?.name);
+
+  const autoName = useMemo(
+    () => buildDefaultProviderName(protocol, existingNames, initial?.name, locale),
+    [protocol, existingNames, initial?.name, locale],
+  );
+
+  useEffect(() => {
+    if (!nameTouched) {
+      setNameState(autoName);
+    }
+  }, [autoName, nameTouched]);
+
+  const setName = useCallback((value: string) => {
+    setNameTouched(true);
+    setNameState(value);
+  }, []);
+
+  const setProtocol = useCallback((value: ProviderId) => {
+    setProtocolState(value);
+    setTestResult({ state: 'idle' });
+  }, []);
 
   // Check for duplicate name (exclude the provider being edited)
   const trimmedName = name.trim();
-  const isDuplicateName = !!(trimmedName && existingNames?.some(
-    n => n.toLowerCase() === trimmedName.toLowerCase(),
+  const effectiveName = trimmedName || autoName;
+  const isDuplicateName = !!(effectiveName && existingNames?.some(
+    n => n !== initial?.name && n.toLowerCase() === effectiveName.toLowerCase(),
   ));
 
-  const canSave = !!(trimmedName && baseUrl.trim() && model.trim() && !isDuplicateName);
+  const canSave = !!(baseUrl.trim() && model.trim() && !isDuplicateName);
+
+  const requiredFieldsMessage = locale === 'zh'
+    ? '接口地址和模型为必填'
+    : 'Base URL and model are required';
+
+  const duplicateNameMessage = locale === 'zh'
+    ? '名称已存在，请使用其他名称'
+    : 'Name already exists, please use a different name';
 
   const handleTest = useCallback(async () => {
-    if (!canSave) {
-      setTestResult({
-        state: 'error',
-        error: locale === 'zh' ? '名称、接口地址和模型为必填' : 'Name, base URL, and model are required',
-      });
+    if (isDuplicateName) {
+      setTestResult({ state: 'error', error: duplicateNameMessage });
+      return;
+    }
+    if (!baseUrl.trim() || !model.trim()) {
+      setTestResult({ state: 'error', error: requiredFieldsMessage });
       return;
     }
     setTestResult({ state: 'testing' });
@@ -90,32 +150,26 @@ export function useCustomProviderForm({
     } catch {
       setTestResult({ state: 'error', code: 'network_error', error: 'Network error' });
     }
-  }, [canSave, apiKey, model, baseUrl, protocol, locale, initial?.id]);
+  }, [isDuplicateName, duplicateNameMessage, baseUrl, model, initial?.id, apiKey, protocol, requiredFieldsMessage]);
 
   const handleSave = useCallback(() => {
     if (isDuplicateName) {
-      setTestResult({
-        state: 'error',
-        error: locale === 'zh' ? '名称已存在，请使用其他名称' : 'Name already exists, please use a different name',
-      });
+      setTestResult({ state: 'error', error: duplicateNameMessage });
       return;
     }
-    if (!canSave) {
-      setTestResult({
-        state: 'error',
-        error: locale === 'zh' ? '名称、接口地址和模型为必填' : 'Name, base URL, and model are required',
-      });
+    if (!baseUrl.trim() || !model.trim()) {
+      setTestResult({ state: 'error', error: requiredFieldsMessage });
       return;
     }
     onSave({
       id: initial?.id || generateProviderId(),
-      name: name.trim(),
+      name: effectiveName,
       protocol,
       apiKey,
       model: model.trim(),
       baseUrl: baseUrl.trim(),
     });
-  }, [canSave, isDuplicateName, name, protocol, apiKey, model, baseUrl, initial?.id, onSave, locale]);
+  }, [isDuplicateName, duplicateNameMessage, baseUrl, model, requiredFieldsMessage, onSave, initial?.id, effectiveName, protocol, apiKey]);
 
   return {
     name, setName,

package/app/components/shared/ProviderSelect.tsx

@@ -39,7 +39,8 @@ export default function ProviderSelect({
     : [];
 
   // Add panel shows ALL providers as protocol templates (can add multiple of the same type)
-  const { primary: primaryItems, more: moreItems } = groups;
+  const { primary: primaryItems, local: localItems, more: moreItems } = groups;
+  const secondaryItems = [...localItems, ...moreItems];
 
   /* ── Compact tab button (for legacy builtin-only mode) ── */
   const renderCompactTab = (id: ProviderId) => {
@@ -175,7 +176,7 @@ export default function ProviderSelect({
       </div>
 
       {/* More toggle */}
-      {moreItems.length > 0 && (
+      {secondaryItems.length > 0 && (
         <>
           <button
             type="button"
@@ -186,13 +187,13 @@ export default function ProviderSelect({
             {showMore
               ? (locale === 'zh' ? '收起' : 'Show less')
               : (locale === 'zh'
-                  ? `更多 (${moreItems.length})`
-                  : `More (${moreItems.length})`)}
+                  ? `更多 (${secondaryItems.length})`
+                  : `More (${secondaryItems.length})`)}
           </button>
 
           {showMore && (
             <div className={compact ? 'flex flex-wrap gap-2' : 'grid grid-cols-1 gap-2'}>
-              {moreItems.map(id => compact ? renderCompactTab(id) : renderCard(id))}
+              {secondaryItems.map(id => compact ? renderCompactTab(id) : renderCard(id))}
             </div>
           )}
         </>

package/app/lib/agent/providers.ts

@@ -18,7 +18,7 @@ export type ProviderId =
   | 'xai' | 'openrouter' | 'mistral' | 'deepseek'
   | 'zai' | 'zai-cn' | 'kimi-coding'
   | 'cerebras' | 'minimax' | 'minimax-cn' | 'huggingface'
-  | 'ollama';
+  | 'ollama' | 'lm-studio' | 'vllm';
 
 /**
  * UI/UX metadata for each provider.
@@ -44,7 +44,7 @@ export interface ProviderPreset {
   supportsThinking: boolean;
   supportsListModels: boolean;
   signupUrl?: string;
-  category: 'primary' | 'more';
+  category: 'primary' | 'local' | 'more';
 }
 
 export const PROVIDER_PRESETS: Record<ProviderId, ProviderPreset> = {
@@ -242,7 +242,41 @@ export const PROVIDER_PRESETS: Record<ProviderId, ProviderPreset> = {
     supportsThinking: false,
     supportsListModels: true,
     signupUrl: 'https://ollama.com/download',
-    category: 'more',
+    category: 'local',
+  },
+  'lm-studio': {
+    id: 'lm-studio',
+    name: 'LM Studio',
+    nameZh: 'LM Studio (本地)',
+    shortLabel: 'LM Studio',
+    description: 'Local OpenAI-compatible server',
+    descriptionZh: '本地 OpenAI 兼容服务',
+    defaultModel: 'local-model',
+    piProviderOverride: 'openai' as KnownProvider,
+    fixedBaseUrl: 'http://localhost:1234/v1',
+    apiKeyFallback: 'lm-studio',
+    supportsBaseUrl: true,
+    supportsThinking: false,
+    supportsListModels: true,
+    signupUrl: 'https://lmstudio.ai/',
+    category: 'local',
+  },
+  vllm: {
+    id: 'vllm',
+    name: 'vLLM',
+    nameZh: 'vLLM (本地)',
+    shortLabel: 'vLLM',
+    description: 'Local OpenAI-compatible server',
+    descriptionZh: '本地 OpenAI 兼容服务',
+    defaultModel: 'local-model',
+    piProviderOverride: 'openai' as KnownProvider,
+    fixedBaseUrl: 'http://localhost:8000/v1',
+    apiKeyFallback: 'vllm',
+    supportsBaseUrl: true,
+    supportsThinking: false,
+    supportsListModels: true,
+    signupUrl: 'https://docs.vllm.ai/',
+    category: 'local',
   },
 };
 
@@ -256,15 +290,19 @@ export function getPreset(id: ProviderId): ProviderPreset {
   return PROVIDER_PRESETS[id] ?? PROVIDER_PRESETS.anthropic;
 }
 
-export function groupedProviders(): { primary: ProviderId[]; more: ProviderId[] } {
+export function groupedProviders(): { primary: ProviderId[]; local: ProviderId[]; more: ProviderId[] } {
   const primary: ProviderId[] = [];
+  const local: ProviderId[] = [];
   const more: ProviderId[] = [];
   for (const id of ALL_PROVIDER_IDS) {
-    if (PROVIDER_PRESETS[id].category === 'primary') primary.push(id);
+    const category = PROVIDER_PRESETS[id].category;
+    if (category === 'primary') primary.push(id);
+    else if (category === 'local') local.push(id);
     else more.push(id);
   }
+  local.sort((a, b) => PROVIDER_PRESETS[a].name.localeCompare(PROVIDER_PRESETS[b].name));
   more.sort((a, b) => PROVIDER_PRESETS[a].name.localeCompare(PROVIDER_PRESETS[b].name));
-  return { primary, more };
+  return { primary, local, more };
 }
 
 // ---------------------------------------------------------------------------

package/app/lib/im/feishu-dispatcher.ts

@@ -0,0 +1,111 @@
+import type { FeishuConfig, FeishuWebhookDispatchResult } from './types';
+import { buildFeishuWebhookStatus, handleFeishuMessageReceiveEvent } from './webhook/feishu';
+
+type FeishuHeaders = Record<string, string>;
+type FeishuBody = Record<string, unknown>;
+type FeishuDispatcher = {
+  encryptKey?: string;
+  register(handles: Record<string, (data: unknown) => unknown>): FeishuDispatcher;
+  invoke(data: unknown, params?: { needCheck?: boolean }): Promise<unknown>;
+};
+
+type LarkSdkModule = typeof import('@larksuiteoapi/node-sdk');
+
+let cachedSdk: LarkSdkModule | null = null;
+let cachedDispatcher: { key: string; dispatcher: FeishuDispatcher } | null = null;
+
+function buildDispatcherKey(config: FeishuConfig): string {
+  return JSON.stringify({
+    encryptKey: config.conversation?.encrypt_key ?? '',
+    verificationToken: config.conversation?.verification_token ?? '',
+  });
+}
+
+function buildPayload(body: FeishuBody, headers: FeishuHeaders): FeishuBody {
+  return Object.assign(Object.create({ headers }), body);
+}
+
+function normalizeDispatcherBody(result: unknown): Record<string, unknown> {
+  if (result && typeof result === 'object' && !Array.isArray(result)) {
+    return result as Record<string, unknown>;
+  }
+  if (result == null) {
+    return { ok: true };
+  }
+  return { ok: false, error: `Unexpected Feishu dispatcher result: ${String(result)}` };
+}
+
+async function getLarkSdk(): Promise<LarkSdkModule> {
+  if (cachedSdk) return cachedSdk;
+  cachedSdk = await import('@larksuiteoapi/node-sdk');
+  return cachedSdk;
+}
+
+async function getDispatcher(config: FeishuConfig): Promise<FeishuDispatcher> {
+  const key = buildDispatcherKey(config);
+  if (cachedDispatcher?.key === key) {
+    return cachedDispatcher.dispatcher;
+  }
+
+  const lark = await getLarkSdk();
+  const dispatcher = new lark.EventDispatcher({
+    encryptKey: config.conversation?.encrypt_key,
+    verificationToken: config.conversation?.verification_token,
+  }).register({
+    'im.message.receive_v1': (event: unknown) => handleFeishuMessageReceiveEvent(event as import('./types').FeishuSdkMessageEvent),
+  }) as FeishuDispatcher;
+
+  cachedDispatcher = { key, dispatcher };
+  return dispatcher;
+}
+
+function shouldHandleChallenge(body: FeishuBody): boolean {
+  return typeof body.challenge === 'string'
+    || body.type === 'url_verification'
+    || typeof body.encrypt === 'string';
+}
+
+export async function dispatchFeishuWebhook(params: {
+  config: FeishuConfig;
+  body: FeishuBody;
+  headers: FeishuHeaders;
+}): Promise<FeishuWebhookDispatchResult> {
+  const status = buildFeishuWebhookStatus(params.config);
+  if (status.state !== 'ready') {
+    return {
+      status: 202,
+      body: { ok: false, ignored: true, reason: status.lastError ?? 'Webhook is not ready' },
+    };
+  }
+
+  const payload = buildPayload(params.body, params.headers);
+  if (shouldHandleChallenge(params.body)) {
+    const lark = await getLarkSdk();
+    const { isChallenge, challenge } = lark.generateChallenge(payload, {
+      encryptKey: params.config.conversation?.encrypt_key ?? '',
+    });
+
+    if (isChallenge) {
+      return {
+        status: 200,
+        body: challenge,
+      };
+    }
+  }
+
+  const dispatcher = await getDispatcher(params.config);
+  const result = await dispatcher.invoke(payload);
+
+  if (typeof result === 'undefined') {
+    return {
+      status: 401,
+      body: { ok: false, error: 'Invalid Feishu webhook signature or payload.' },
+    };
+  }
+
+  const normalized = normalizeDispatcherBody(result);
+  return {
+    status: normalized.ok === false ? 500 : 202,
+    body: normalized,
+  };
+}

package/app/lib/im/feishu-ws-client.ts

@@ -0,0 +1,72 @@
+import * as Lark from '@larksuiteoapi/node-sdk';
+import type { FeishuConfig, FeishuSdkMessageEvent } from './types';
+import { handleFeishuMessageReceiveEvent } from './webhook/feishu';
+
+type FeishuWSRuntime = {
+  client: Lark.WSClient;
+  startedAt: string;
+};
+
+let runtime: FeishuWSRuntime | null = null;
+let lastError: string | undefined;
+
+function assertFeishuWSConfig(config: FeishuConfig): void {
+  if (!config.app_id?.trim() || !config.app_secret?.trim()) {
+    throw new Error('Feishu App ID and App Secret are required for long connection mode');
+  }
+}
+
+function createDispatcher(): Lark.EventDispatcher {
+  return new Lark.EventDispatcher({}).register({
+    'im.message.receive_v1': (event: unknown) => handleFeishuMessageReceiveEvent(event as FeishuSdkMessageEvent),
+  });
+}
+
+export async function startFeishuWSClient(config: FeishuConfig): Promise<void> {
+  if (runtime) return;
+
+  assertFeishuWSConfig(config);
+  lastError = undefined;
+
+  const client = new Lark.WSClient({
+    appId: config.app_id,
+    appSecret: config.app_secret,
+    autoReconnect: true,
+    loggerLevel: Lark.LoggerLevel.info,
+  });
+
+  try {
+    await client.start({
+      eventDispatcher: createDispatcher(),
+    });
+    runtime = {
+      client,
+      startedAt: new Date().toISOString(),
+    };
+  } catch (error) {
+    lastError = error instanceof Error ? error.message : String(error);
+    throw error;
+  }
+}
+
+export function stopFeishuWSClient(): void {
+  runtime?.client.close();
+  runtime = null;
+}
+
+export function getFeishuWSClientStatus(): {
+  running: boolean;
+  startedAt?: string;
+  lastError?: string;
+} {
+  return {
+    running: runtime !== null,
+    startedAt: runtime?.startedAt,
+    lastError,
+  };
+}
+
+export function __resetFeishuWSClientForTests(): void {
+  runtime = null;
+  lastError = undefined;
+}