fix: wrong agentid

- Add get_user_info() to WecomClient to fetch user name via /user/get API
- Update WecomEventConverter.target2yiri to accept bot param and fetch real user name
- Update register_listener call to pass self.bot for user name lookup
- URL-encode userid parameter for safety

Co-authored-by: RockChinQ <45992437+RockChinQ@users.noreply.github.com>

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langbot"
-version = "4.8.7"
+version = "4.9.0"
 description = "Production-grade platform for building agentic IM bots"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -61,10 +61,10 @@ dependencies = [
     "html2text>=2024.2.26",
     "langchain>=0.2.0",
     "langchain-text-splitters>=0.0.1",
-    "chromadb>=0.4.24",
+    "chromadb>=1.0.0,<2.0.0",
     "qdrant-client (>=1.15.1,<2.0.0)",
-    "pyseekdb==1.0.0b7",
-    "langbot-plugin==0.2.7",
+    "pyseekdb==1.1.0.post3",
+    "langbot-plugin==0.3.0",
     "asyncpg>=0.30.0",
     "line-bot-sdk>=3.19.0",
     "tboxsdk>=0.0.10",

src/langbot/__init__.py

@@ -1,3 +1,3 @@
 """LangBot - Production-grade platform for building agentic IM bots"""
 
-__version__ = '4.8.7'
+__version__ = '4.9.0'

src/langbot/libs/wecom_api/api.py

@@ -4,6 +4,7 @@ import base64
 import binascii
 import httpx
 import traceback
+from urllib.parse import quote
 from quart import Quart
 import xml.etree.ElementTree as ET
 from typing import Callable, Dict, Any
@@ -67,6 +68,31 @@ class WecomClient:
                 await self.logger.error(f'获取accesstoken失败:{response.json()}')
                 raise Exception(f'未获取access token: {data}')
 
+    async def get_user_info(self, userid: str) -> dict:
+        """
+        Get user information by user ID using the application secret.
+
+        Args:
+            userid: The user ID to look up.
+
+        Returns:
+            dict: User information including 'name' field.
+        """
+        if not await self.check_access_token():
+            self.access_token = await self.get_access_token(self.secret)
+
+        url = self.base_url + '/user/get?access_token=' + self.access_token + '&userid=' + quote(userid)
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url)
+            data = response.json()
+            if data.get('errcode') == 40014 or data.get('errcode') == 42001:
+                self.access_token = await self.get_access_token(self.secret)
+                return await self.get_user_info(userid)
+            if data.get('errcode', 0) != 0:
+                await self.logger.error(f'获取用户信息失败:{data}')
+                return {}
+            return data
+
     async def get_users(self):
         if not self.check_access_token_for_contacts():
             self.access_token_for_contacts = await self.get_access_token(self.secret_for_contacts)

src/langbot/libs/wecom_customer_service_api/api.py

@@ -10,6 +10,7 @@ from typing import Callable
 from .wecomcsevent import WecomCSEvent
 import langbot_plugin.api.entities.builtin.platform.message as platform_message
 import aiofiles
+import time
 
 
 class WecomCSClient:
@@ -34,6 +35,10 @@ class WecomCSClient:
         self.unified_mode = unified_mode
         self.app = Quart(__name__)
 
+        # Customer info cache: {external_userid: (info_dict, timestamp)}
+        self._customer_cache: dict[str, tuple[dict, float]] = {}
+        self._cache_ttl = 60  # Cache TTL in seconds (1 minute)
+
         # 只有在非统一模式下才注册独立路由
         if not self.unified_mode:
             self.app.add_url_rule(
@@ -378,3 +383,53 @@ class WecomCSClient:
     async def get_media_id(self, image: platform_message.Image):
         media_id = await self.upload_to_work(image=image)
         return media_id
+
+    async def get_customer_info(self, external_userid: str) -> dict | None:
+        """
+        Get customer information by external_userid with caching.
+
+        Uses a 1-minute cache to avoid repeated API calls for the same user.
+
+        Args:
+            external_userid: The external user ID of the customer.
+
+        Returns:
+            Customer info dict with 'nickname', 'avatar', etc., or None if not found.
+        """
+        # Check cache first
+        current_time = time.time()
+        if external_userid in self._customer_cache:
+            cached_info, cached_time = self._customer_cache[external_userid]
+            if current_time - cached_time < self._cache_ttl:
+                return cached_info
+
+        # Cache miss or expired, fetch from API
+        if not await self.check_access_token():
+            self.access_token = await self.get_access_token(self.secret)
+
+        url = f'{self.base_url}/kf/customer/batchget?access_token={self.access_token}'
+
+        payload = {
+            'external_userid_list': [external_userid],
+        }
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(url, json=payload)
+            data = response.json()
+
+            if data.get('errcode') in [40014, 42001]:
+                self.access_token = await self.get_access_token(self.secret)
+                return await self.get_customer_info(external_userid)
+
+            if data.get('errcode', 0) != 0:
+                if self.logger:
+                    await self.logger.warning(f'Failed to get customer info: {data}')
+                return None
+
+            customer_list = data.get('customer_list', [])
+            if customer_list:
+                customer_info = customer_list[0]
+                # Store in cache
+                self._customer_cache[external_userid] = (customer_info, current_time)
+                return customer_info
+            return None

src/langbot/pkg/api/http/controller/groups/knowledge/base.py

@@ -13,7 +13,10 @@ class KnowledgeBaseRouterGroup(group.RouterGroup):
 
             elif quart.request.method == 'POST':
                 json_data = await quart.request.json
-                knowledge_base_uuid = await self.ap.knowledge_service.create_knowledge_base(json_data)
+                try:
+                    knowledge_base_uuid = await self.ap.knowledge_service.create_knowledge_base(json_data)
+                except ValueError as e:
+                    return self.http_status(400, -1, str(e))
                 return self.success(data={'uuid': knowledge_base_uuid})
 
             return self.http_status(405, -1, 'Method not allowed')
@@ -39,7 +42,7 @@ class KnowledgeBaseRouterGroup(group.RouterGroup):
             elif quart.request.method == 'PUT':
                 json_data = await quart.request.json
                 await self.ap.knowledge_service.update_knowledge_base(knowledge_base_uuid, json_data)
-                return self.success({})
+                return self.success(data={'uuid': knowledge_base_uuid})
 
             elif quart.request.method == 'DELETE':
                 await self.ap.knowledge_service.delete_knowledge_base(knowledge_base_uuid)
@@ -65,8 +68,12 @@ class KnowledgeBaseRouterGroup(group.RouterGroup):
                 if not file_id:
                     return self.http_status(400, -1, 'File ID is required')
 
+                parser_plugin_id = json_data.get('parser_plugin_id')
+
                 # 调用服务层方法将文件与知识库关联
-                task_id = await self.ap.knowledge_service.store_file(knowledge_base_uuid, file_id)
+                task_id = await self.ap.knowledge_service.store_file(
+                    knowledge_base_uuid, file_id, parser_plugin_id=parser_plugin_id
+                )
                 return self.success(
                     {
                         'task_id': task_id,
@@ -90,5 +97,13 @@ class KnowledgeBaseRouterGroup(group.RouterGroup):
         async def retrieve_knowledge_base(knowledge_base_uuid: str) -> str:
             json_data = await quart.request.json
             query = json_data.get('query')
-            results = await self.ap.knowledge_service.retrieve_knowledge_base(knowledge_base_uuid, query)
+
+            if not query or not query.strip():
+                return self.http_status(400, -1, 'Query is required and cannot be empty')
+
+            # Extract retrieval_settings to allow dynamic control over Knowledge Engine behavior (e.g. top_k, filters)
+            retrieval_settings = json_data.get('retrieval_settings', {})
+            results = await self.ap.knowledge_service.retrieve_knowledge_base(
+                knowledge_base_uuid, query, retrieval_settings
+            )
             return self.success(data={'results': results})

src/langbot/pkg/api/http/controller/groups/knowledge/engines.py

@@ -0,0 +1,45 @@
+import quart
+from urllib.parse import unquote
+from ... import group
+
+
+@group.group_class('knowledge_engines', '/api/v1/knowledge/engines')
+class KnowledgeEnginesRouterGroup(group.RouterGroup):
+    async def initialize(self) -> None:
+        @self.route('', methods=['GET'], auth_type=group.AuthType.USER_TOKEN_OR_API_KEY)
+        async def list_knowledge_engines() -> quart.Response:
+            """List all available Knowledge Engines from plugins.
+
+            Returns a list of Knowledge Engines with their capabilities and configuration schemas.
+            This is used by the frontend to render the knowledge base creation wizard.
+            """
+            engines = await self.ap.knowledge_service.list_knowledge_engines()
+            return self.success(data={'engines': engines})
+
+        @self.route(
+            '/<path:plugin_id>/creation-schema', methods=['GET'], auth_type=group.AuthType.USER_TOKEN_OR_API_KEY
+        )
+        async def get_engine_creation_schema(plugin_id: str) -> quart.Response:
+            """Get creation settings schema for a specific Knowledge Engine.
+
+            plugin_id is in 'author/name' format, captured via <path:> converter.
+            """
+            plugin_id = unquote(plugin_id)
+            if '/' not in plugin_id:
+                return self.http_status(400, -1, 'Invalid plugin_id format. Expected author/name.')
+            schema = await self.ap.knowledge_service.get_engine_creation_schema(plugin_id)
+            return self.success(data={'schema': schema})
+
+        @self.route(
+            '/<path:plugin_id>/retrieval-schema', methods=['GET'], auth_type=group.AuthType.USER_TOKEN_OR_API_KEY
+        )
+        async def get_engine_retrieval_schema(plugin_id: str) -> quart.Response:
+            """Get retrieval settings schema for a specific Knowledge Engine.
+
+            plugin_id is in 'author/name' format, captured via <path:> converter.
+            """
+            plugin_id = unquote(plugin_id)
+            if '/' not in plugin_id:
+                return self.http_status(400, -1, 'Invalid plugin_id format. Expected author/name.')
+            schema = await self.ap.knowledge_service.get_engine_retrieval_schema(plugin_id)
+            return self.success(data={'schema': schema})

src/langbot/pkg/api/http/controller/groups/knowledge/external.py

@@ -1,61 +0,0 @@
-import quart
-from ... import group
-
-
-@group.group_class('external_knowledge_base', '/api/v1/knowledge/external-bases')
-class ExternalKnowledgeBaseRouterGroup(group.RouterGroup):
-    async def initialize(self) -> None:
-        @self.route('/retrievers', methods=['GET'])
-        async def list_knowledge_retrievers() -> quart.Response:
-            """List all available knowledge retrievers from plugins."""
-            retrievers = await self.ap.plugin_connector.list_knowledge_retrievers()
-            return self.success(data={'retrievers': retrievers})
-
-        @self.route('', methods=['POST', 'GET'])
-        async def handle_external_knowledge_bases() -> quart.Response:
-            if quart.request.method == 'GET':
-                external_kbs = await self.ap.external_kb_service.get_external_knowledge_bases()
-                return self.success(data={'bases': external_kbs})
-
-            elif quart.request.method == 'POST':
-                json_data = await quart.request.json
-                kb_uuid = await self.ap.external_kb_service.create_external_knowledge_base(json_data)
-                return self.success(data={'uuid': kb_uuid})
-
-            return self.http_status(405, -1, 'Method not allowed')
-
-        @self.route(
-            '/<kb_uuid>',
-            methods=['GET', 'DELETE', 'PUT'],
-        )
-        async def handle_specific_external_knowledge_base(kb_uuid: str) -> quart.Response:
-            if quart.request.method == 'GET':
-                external_kb = await self.ap.external_kb_service.get_external_knowledge_base(kb_uuid)
-
-                if external_kb is None:
-                    return self.http_status(404, -1, 'external knowledge base not found')
-
-                return self.success(
-                    data={
-                        'base': external_kb,
-                    }
-                )
-
-            elif quart.request.method == 'PUT':
-                json_data = await quart.request.json
-                await self.ap.external_kb_service.update_external_knowledge_base(kb_uuid, json_data)
-                return self.success({})
-
-            elif quart.request.method == 'DELETE':
-                await self.ap.external_kb_service.delete_external_knowledge_base(kb_uuid)
-                return self.success({})
-
-        @self.route(
-            '/<kb_uuid>/retrieve',
-            methods=['POST'],
-        )
-        async def retrieve_external_knowledge_base(kb_uuid: str) -> str:
-            json_data = await quart.request.json
-            query = json_data.get('query')
-            results = await self.ap.external_kb_service.retrieve_external_knowledge_base(kb_uuid, query)
-            return self.success(data={'results': results})

src/langbot/pkg/api/http/controller/groups/knowledge/migration.py

@@ -0,0 +1,372 @@
+import asyncio
+import json
+
+import httpx
+import quart
+import sqlalchemy
+
+from ... import group
+from ......core import taskmgr
+from ......entity.persistence import metadata as persistence_metadata
+from langbot_plugin.runtime.plugin.mgr import PluginInstallSource
+
+LANGRAG_PLUGIN_AUTHOR = 'langbot-team'
+LANGRAG_PLUGIN_NAME = 'LangRAG'
+LANGRAG_PLUGIN_ID = f'{LANGRAG_PLUGIN_AUTHOR}/{LANGRAG_PLUGIN_NAME}'
+DEFAULT_SPACE_URL = 'https://space.langbot.app'
+
+# Old Retriever plugin_name -> New Connector plugin_name
+EXTERNAL_PLUGIN_NAME_MAPPING = {
+    'DifyDatasetsRetriever': 'DifyDatasetsConnector',
+    'RAGFlowRetriever': 'RAGFlowConnector',
+    'FastGPTRetriever': 'FastGPTConnector',
+}
+
+# Per-plugin: which old retriever_config fields belong to creation_settings.
+# Remaining fields go to retrieval_settings.
+# None means ALL fields go to creation_settings (no retrieval_schema).
+EXTERNAL_PLUGIN_CREATION_FIELDS: dict[str, set[str] | None] = {
+    'langbot-team/DifyDatasetsConnector': {'api_base_url', 'dify_apikey', 'dataset_id'},
+    'langbot-team/RAGFlowConnector': {'api_base_url', 'api_key', 'dataset_ids'},
+    'langbot-team/FastGPTConnector': None,  # all fields -> creation_settings
+}
+
+
+@group.group_class('knowledge/migration', '/api/v1/knowledge/migration')
+class KnowledgeMigrationRouterGroup(group.RouterGroup):
+    async def _get_migration_flag(self) -> bool:
+        """Check if rag_plugin_migration_needed flag is set."""
+        result = await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.select(persistence_metadata.Metadata).where(
+                persistence_metadata.Metadata.key == 'rag_plugin_migration_needed'
+            )
+        )
+        row = result.first()
+        return row is not None and row.value == 'true'
+
+    async def _set_migration_flag(self, value: str):
+        """Set rag_plugin_migration_needed flag."""
+        await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.update(persistence_metadata.Metadata)
+            .where(persistence_metadata.Metadata.key == 'rag_plugin_migration_needed')
+            .values(value=value)
+        )
+
+    async def _table_exists(self, table_name: str) -> bool:
+        """Check if a table exists."""
+        if self.ap.persistence_mgr.db.name == 'postgresql':
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text(
+                    'SELECT EXISTS (SELECT FROM information_schema.tables WHERE table_name = :table_name);'
+                ).bindparams(table_name=table_name)
+            )
+            return result.scalar()
+        else:
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text("SELECT name FROM sqlite_master WHERE type='table' AND name=:table_name;").bindparams(
+                    table_name=table_name
+                )
+            )
+            return result.first() is not None
+
+    async def _install_plugin_from_marketplace(
+        self, plugin_id: str, task_context: taskmgr.TaskContext, space_url: str
+    ) -> None:
+        """Install a single plugin from the marketplace."""
+        p_author, p_name = plugin_id.split('/', 1)
+        self.ap.logger.info(f'RAG migration: installing plugin {plugin_id} from marketplace...')
+        task_context.trace(f'Installing plugin {plugin_id} from marketplace...')
+
+        async with httpx.AsyncClient(trust_env=True, timeout=15) as client:
+            resp = await client.get(f'{space_url}/api/v1/marketplace/plugins/{p_author}/{p_name}')
+            resp.raise_for_status()
+            p_data = resp.json().get('data', {}).get('plugin', {})
+            p_version = p_data.get('latest_version')
+            if not p_version:
+                raise Exception(f'Could not determine latest version for {plugin_id}')
+
+        await self.ap.plugin_connector.install_plugin(
+            PluginInstallSource.MARKETPLACE,
+            {
+                'plugin_author': p_author,
+                'plugin_name': p_name,
+                'plugin_version': p_version,
+            },
+            task_context=task_context,
+        )
+        self.ap.logger.info(f'RAG migration: plugin {plugin_id} install request sent.')
+
+    async def _execute_rag_migration(self, task_context: taskmgr.TaskContext, install_plugin: bool = True):
+        """Execute RAG migration: install required plugins and restore backup data."""
+        warnings = []
+
+        # Collect all plugins we need: LangRAG (always) + connector plugins (from external KBs)
+        needed_plugins: dict[str, str] = {
+            LANGRAG_PLUGIN_ID: LANGRAG_PLUGIN_NAME,
+        }
+
+        has_external = await self._table_exists('external_knowledge_bases')
+        if has_external:
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text('SELECT DISTINCT plugin_author, plugin_name FROM external_knowledge_bases;')
+            )
+            for row in result.fetchall():
+                plugin_author = row[0] or ''
+                plugin_name = row[1] or ''
+                mapped_name = EXTERNAL_PLUGIN_NAME_MAPPING.get(plugin_name, plugin_name)
+                plugin_id = f'{plugin_author}/{mapped_name}'
+                if plugin_id not in needed_plugins:
+                    needed_plugins[plugin_id] = mapped_name
+
+        self.ap.logger.info(f'RAG migration: plugins needed: {list(needed_plugins.keys())}')
+
+        if install_plugin:
+            # Step 1: Install all required plugins from marketplace
+            task_context.trace('Installing required plugins...', action='install-plugin')
+            space_url = self.ap.instance_config.data.get('space', {}).get('url', DEFAULT_SPACE_URL).rstrip('/')
+
+            for plugin_id in needed_plugins:
+                try:
+                    await self._install_plugin_from_marketplace(plugin_id, task_context, space_url)
+                except Exception as e:
+                    self.ap.logger.warning(f'RAG migration: plugin {plugin_id} install returned: {e}')
+                    task_context.trace(f'Plugin install note ({plugin_id}): {e}')
+
+            # Step 2: Wait for all plugins to become available as knowledge engines
+            task_context.trace(
+                f'Waiting for plugins to become available: {list(needed_plugins.keys())}...',
+                action='wait-plugin',
+            )
+            max_retries = 30
+            engine_id_set: set[str] = set()
+            for i in range(max_retries):
+                try:
+                    engines = await self.ap.plugin_connector.list_knowledge_engines()
+                    engine_id_set = {e.get('plugin_id') for e in engines}
+                except Exception:
+                    pass
+                if all(pid in engine_id_set for pid in needed_plugins):
+                    self.ap.logger.info(f'RAG migration: all plugins ready: {engine_id_set}')
+                    task_context.trace('All required plugins are ready.')
+                    break
+                if i == max_retries - 1:
+                    still_missing = [pid for pid in needed_plugins if pid not in engine_id_set]
+                    warning = f'Plugin(s) {still_missing} did not become available after {max_retries} retries'
+                    self.ap.logger.warning(f'RAG migration: {warning}')
+                    warnings.append(warning)
+                    task_context.trace(warning)
+                await asyncio.sleep(2)
+        else:
+            try:
+                engines = await self.ap.plugin_connector.list_knowledge_engines()
+                engine_id_set = {e.get('plugin_id') for e in engines}
+            except Exception:
+                engine_id_set = set()
+
+        # Step 3: Restore internal knowledge bases from backup
+        task_context.trace('Restoring internal knowledge bases...', action='restore-internal')
+        if await self._table_exists('knowledge_bases_backup'):
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text('SELECT * FROM knowledge_bases_backup;')
+            )
+            rows = result.fetchall()
+            columns = result.keys()
+
+            for row in rows:
+                row_dict = dict(zip(columns, row))
+                kb_uuid = row_dict.get('uuid')
+                name = row_dict.get('name', 'Untitled')
+                description = row_dict.get('description', '')
+                emoji = row_dict.get('emoji', '\U0001f4da')
+                embedding_model_uuid = row_dict.get('embedding_model_uuid', '')
+                top_k = row_dict.get('top_k', 5)
+                created_at = row_dict.get('created_at')
+                updated_at = row_dict.get('updated_at')
+
+                creation_settings = json.dumps({'embedding_model_uuid': embedding_model_uuid})
+                retrieval_settings = json.dumps({'top_k': top_k})
+
+                await self.ap.persistence_mgr.execute_async(
+                    sqlalchemy.text(
+                        'INSERT INTO knowledge_bases '
+                        '(uuid, name, description, emoji, created_at, updated_at, '
+                        'knowledge_engine_plugin_id, collection_id, creation_settings, retrieval_settings) '
+                        'VALUES (:uuid, :name, :description, :emoji, :created_at, :updated_at, '
+                        ':plugin_id, :collection_id, :creation_settings, :retrieval_settings);'
+                    ).bindparams(
+                        uuid=kb_uuid,
+                        name=name,
+                        description=description,
+                        emoji=emoji,
+                        created_at=created_at,
+                        updated_at=updated_at,
+                        plugin_id=LANGRAG_PLUGIN_ID,
+                        collection_id=kb_uuid,
+                        creation_settings=creation_settings,
+                        retrieval_settings=retrieval_settings,
+                    )
+                )
+
+                try:
+                    config = {'embedding_model_uuid': embedding_model_uuid}
+                    await self.ap.plugin_connector.rag_on_kb_create(LANGRAG_PLUGIN_ID, kb_uuid, config)
+                    task_context.trace(f'Restored internal KB: {name} ({kb_uuid})')
+                except Exception as e:
+                    warning = f'Failed to notify plugin for KB {name} ({kb_uuid}): {e}'
+                    warnings.append(warning)
+                    task_context.trace(warning)
+
+            await self.ap.rag_mgr.load_knowledge_bases_from_db()
+
+        # Step 4: Restore external knowledge bases
+        task_context.trace('Restoring external knowledge bases...', action='restore-external')
+        if has_external:
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text('SELECT * FROM external_knowledge_bases;')
+            )
+            rows = result.fetchall()
+            columns = result.keys()
+
+            self.ap.logger.info(
+                f'RAG migration: {len(rows)} external KB(s) to restore. Available engines: {engine_id_set}'
+            )
+            task_context.trace(f'Found {len(rows)} external KB(s). Available engines: {engine_id_set}')
+
+            for row in rows:
+                row_dict = dict(zip(columns, row))
+                kb_uuid = row_dict.get('uuid')
+                name = row_dict.get('name', 'Untitled')
+                description = row_dict.get('description', '')
+                emoji = row_dict.get('emoji', '\U0001f517')
+                plugin_author = row_dict.get('plugin_author', '')
+                plugin_name = row_dict.get('plugin_name', '')
+                retriever_config = row_dict.get('retriever_config', {})
+                created_at = row_dict.get('created_at')
+
+                mapped_plugin_name = EXTERNAL_PLUGIN_NAME_MAPPING.get(plugin_name, plugin_name)
+                external_plugin_id = f'{plugin_author}/{mapped_plugin_name}'
+
+                self.ap.logger.info(
+                    f'RAG migration: processing external KB "{name}" ({kb_uuid}), '
+                    f'plugin: {plugin_author}/{plugin_name} -> {external_plugin_id}'
+                )
+
+                if isinstance(retriever_config, str):
+                    try:
+                        retriever_config = json.loads(retriever_config)
+                    except (json.JSONDecodeError, TypeError):
+                        retriever_config = {}
+
+                creation_fields = EXTERNAL_PLUGIN_CREATION_FIELDS.get(external_plugin_id)
+                if creation_fields is None:
+                    creation_settings_dict = retriever_config
+                    retrieval_settings_dict = {}
+                else:
+                    creation_settings_dict = {k: v for k, v in retriever_config.items() if k in creation_fields}
+                    retrieval_settings_dict = {k: v for k, v in retriever_config.items() if k not in creation_fields}
+
+                await self.ap.persistence_mgr.execute_async(
+                    sqlalchemy.text(
+                        'INSERT INTO knowledge_bases '
+                        '(uuid, name, description, emoji, created_at, updated_at, '
+                        'knowledge_engine_plugin_id, collection_id, creation_settings, retrieval_settings) '
+                        'VALUES (:uuid, :name, :description, :emoji, :created_at, :updated_at, '
+                        ':plugin_id, :collection_id, :creation_settings, :retrieval_settings);'
+                    ).bindparams(
+                        uuid=kb_uuid,
+                        name=name,
+                        description=description,
+                        emoji=emoji,
+                        created_at=created_at,
+                        updated_at=created_at,
+                        plugin_id=external_plugin_id,
+                        collection_id=kb_uuid,
+                        creation_settings=json.dumps(creation_settings_dict),
+                        retrieval_settings=json.dumps(retrieval_settings_dict),
+                    )
+                )
+
+                if external_plugin_id not in engine_id_set:
+                    warning = (
+                        f'External KB "{name}" ({kb_uuid}) record saved, but plugin {external_plugin_id} '
+                        f'is not installed yet. Install the connector plugin to use it.'
+                    )
+                    warnings.append(warning)
+                    task_context.trace(warning)
+                else:
+                    try:
+                        await self.ap.plugin_connector.rag_on_kb_create(
+                            external_plugin_id, kb_uuid, creation_settings_dict
+                        )
+                        task_context.trace(f'Restored external KB: {name} ({kb_uuid})')
+                    except Exception as e:
+                        warning = f'Failed to notify plugin for external KB {name} ({kb_uuid}): {e}'
+                        warnings.append(warning)
+                        task_context.trace(warning)
+
+            await self.ap.rag_mgr.load_knowledge_bases_from_db()
+
+        # Step 5: Clear migration flag
+        await self._set_migration_flag('false')
+        task_context.trace('RAG migration completed.', action='done')
+
+        if warnings:
+            task_context.trace(f'Completed with {len(warnings)} warning(s).')
+
+    async def initialize(self) -> None:
+        @self.route('/status', methods=['GET'], auth_type=group.AuthType.USER_TOKEN)
+        async def _() -> str:
+            needed = await self._get_migration_flag()
+
+            internal_kb_count = 0
+            external_kb_count = 0
+
+            if needed:
+                if await self._table_exists('knowledge_bases_backup'):
+                    result = await self.ap.persistence_mgr.execute_async(
+                        sqlalchemy.text('SELECT COUNT(*) FROM knowledge_bases_backup;')
+                    )
+                    internal_kb_count = result.scalar() or 0
+
+                if await self._table_exists('external_knowledge_bases'):
+                    result = await self.ap.persistence_mgr.execute_async(
+                        sqlalchemy.text('SELECT COUNT(*) FROM external_knowledge_bases;')
+                    )
+                    external_kb_count = result.scalar() or 0
+
+            return self.success(
+                data={
+                    'needed': needed,
+                    'internal_kb_count': internal_kb_count,
+                    'external_kb_count': external_kb_count,
+                }
+            )
+
+        @self.route('/execute', methods=['POST'], auth_type=group.AuthType.USER_TOKEN)
+        async def _() -> str:
+            needed = await self._get_migration_flag()
+            if not needed:
+                return self.http_status(400, -1, 'RAG migration is not needed')
+
+            data = await quart.request.get_json(silent=True) or {}
+            install_plugin = data.get('install_plugin', True)
+
+            ctx = taskmgr.TaskContext.new()
+            wrapper = self.ap.task_mgr.create_user_task(
+                self._execute_rag_migration(task_context=ctx, install_plugin=install_plugin),
+                kind='rag-migration',
+                name='rag-migration-execute',
+                label='Migrating knowledge bases to plugin architecture',
+                context=ctx,
+            )
+
+            return self.success(data={'task_id': wrapper.id})
+
+        @self.route('/dismiss', methods=['POST'], auth_type=group.AuthType.USER_TOKEN)
+        async def _() -> str:
+            needed = await self._get_migration_flag()
+            if not needed:
+                return self.http_status(400, -1, 'RAG migration is not needed')
+
+            await self._set_migration_flag('false')
+            return self.success()

src/langbot/pkg/api/http/controller/groups/knowledge/parsers.py

@@ -0,0 +1,16 @@
+import quart
+from ... import group
+
+
+@group.group_class('parsers', '/api/v1/knowledge/parsers')
+class ParsersRouterGroup(group.RouterGroup):
+    async def initialize(self) -> None:
+        @self.route('', methods=['GET'], auth_type=group.AuthType.USER_TOKEN_OR_API_KEY)
+        async def list_parsers() -> quart.Response:
+            """List all available parsers from plugins.
+
+            Optional query parameter `mime_type` to filter parsers by supported MIME type.
+            """
+            mime_type = quart.request.args.get('mime_type')
+            parsers = await self.ap.knowledge_service.list_parsers(mime_type)
+            return self.success(data={'parsers': parsers})

src/langbot/pkg/api/http/controller/groups/pipelines/pipelines.py

@@ -68,7 +68,7 @@ class PipelinesRouterGroup(group.RouterGroup):
                     return self.http_status(404, -1, 'pipeline not found')
 
                 # Only include plugins with pipeline-related components (Command, EventListener, Tool)
-                # Plugins that only have KnowledgeRetriever components are not suitable for pipeline extensions
+                # Plugins that only have KnowledgeEngine components are not suitable for pipeline extensions
                 pipeline_component_kinds = ['Command', 'EventListener', 'Tool']
                 plugins = await self.ap.plugin_connector.list_plugins(component_kinds=pipeline_component_kinds)
                 mcp_servers = await self.ap.mcp_service.get_mcp_servers(contain_runtime_info=True)

src/langbot/pkg/api/http/service/external_kb.py

@@ -1,80 +0,0 @@
-from __future__ import annotations
-
-from ....core import app
-import sqlalchemy
-from langbot.pkg.entity.persistence import rag as persistence_rag
-import uuid
-
-
-class ExternalKBService:
-    """External KB service"""
-
-    ap: app.Application
-
-    def __init__(self, ap: app.Application) -> None:
-        self.ap = ap
-
-    # External Knowledge Base methods
-    async def get_external_knowledge_bases(self) -> list[dict]:
-        result = await self.ap.persistence_mgr.execute_async(sqlalchemy.select(persistence_rag.ExternalKnowledgeBase))
-        external_kbs = result.all()
-        return [
-            self.ap.persistence_mgr.serialize_model(persistence_rag.ExternalKnowledgeBase, external_kb)
-            for external_kb in external_kbs
-        ]
-
-    async def get_external_knowledge_base(self, kb_uuid: str) -> dict | None:
-        result = await self.ap.persistence_mgr.execute_async(
-            sqlalchemy.select(persistence_rag.ExternalKnowledgeBase).where(
-                persistence_rag.ExternalKnowledgeBase.uuid == kb_uuid
-            )
-        )
-        external_kb = result.first()
-        if external_kb is None:
-            return None
-        return self.ap.persistence_mgr.serialize_model(persistence_rag.ExternalKnowledgeBase, external_kb)
-
-    async def create_external_knowledge_base(self, kb_data: dict) -> str:
-        kb_data['uuid'] = str(uuid.uuid4())
-        await self.ap.persistence_mgr.execute_async(
-            sqlalchemy.insert(persistence_rag.ExternalKnowledgeBase).values(kb_data)
-        )
-
-        kb = await self.get_external_knowledge_base(kb_data['uuid'])
-
-        await self.ap.rag_mgr.load_external_knowledge_base(kb)
-
-        return kb_data['uuid']
-
-    async def retrieve_external_knowledge_base(self, kb_uuid: str, query: str) -> list[dict]:
-        """Retrieve external knowledge base"""
-        runtime_kb = await self.ap.rag_mgr.get_knowledge_base_by_uuid(kb_uuid)
-        if runtime_kb is None:
-            raise Exception('Knowledge base not found')
-        return [
-            result.model_dump() for result in await runtime_kb.retrieve(query, 5)
-        ]  # top_k is just a placeholder for external knowledge base
-
-    async def update_external_knowledge_base(self, kb_uuid: str, kb_data: dict) -> None:
-        if 'uuid' in kb_data:
-            del kb_data['uuid']
-
-        await self.ap.persistence_mgr.execute_async(
-            sqlalchemy.update(persistence_rag.ExternalKnowledgeBase)
-            .values(kb_data)
-            .where(persistence_rag.ExternalKnowledgeBase.uuid == kb_uuid)
-        )
-        await self.ap.rag_mgr.remove_knowledge_base_from_runtime(kb_uuid)
-
-        kb = await self.get_external_knowledge_base(kb_uuid)
-
-        await self.ap.rag_mgr.load_external_knowledge_base(kb)
-
-    async def delete_external_knowledge_base(self, kb_uuid: str) -> None:
-        await self.ap.persistence_mgr.execute_async(
-            sqlalchemy.delete(persistence_rag.ExternalKnowledgeBase).where(
-                persistence_rag.ExternalKnowledgeBase.uuid == kb_uuid
-            )
-        )
-
-        await self.ap.rag_mgr.delete_knowledge_base(kb_uuid)

src/langbot/pkg/api/http/service/knowledge.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import uuid
 import sqlalchemy
 
 from ....core import app
@@ -17,64 +16,77 @@ class KnowledgeService:
 
     async def get_knowledge_bases(self) -> list[dict]:
         """获取所有知识库"""
-        result = await self.ap.persistence_mgr.execute_async(sqlalchemy.select(persistence_rag.KnowledgeBase))
-        knowledge_bases = result.all()
-        return [
-            self.ap.persistence_mgr.serialize_model(persistence_rag.KnowledgeBase, knowledge_base)
-            for knowledge_base in knowledge_bases
-        ]
+        return await self.ap.rag_mgr.get_all_knowledge_base_details()
 
     async def get_knowledge_base(self, kb_uuid: str) -> dict | None:
         """获取知识库"""
-        result = await self.ap.persistence_mgr.execute_async(
-            sqlalchemy.select(persistence_rag.KnowledgeBase).where(persistence_rag.KnowledgeBase.uuid == kb_uuid)
-        )
-        knowledge_base = result.first()
-        if knowledge_base is None:
-            return None
-        return self.ap.persistence_mgr.serialize_model(persistence_rag.KnowledgeBase, knowledge_base)
+        return await self.ap.rag_mgr.get_knowledge_base_details(kb_uuid)
 
     async def create_knowledge_base(self, kb_data: dict) -> str:
         """创建知识库"""
-        kb_data['uuid'] = str(uuid.uuid4())
-        await self.ap.persistence_mgr.execute_async(sqlalchemy.insert(persistence_rag.KnowledgeBase).values(kb_data))
+        # In new architecture, we delegate entirely to RAGManager which uses plugins.
+        # Legacy internal KB creation is removed.
 
-        kb = await self.get_knowledge_base(kb_data['uuid'])
+        knowledge_engine_plugin_id = kb_data.get('knowledge_engine_plugin_id')
+        if not knowledge_engine_plugin_id:
+            raise ValueError('knowledge_engine_plugin_id is required')
 
-        await self.ap.rag_mgr.load_knowledge_base(kb)
-
-        return kb_data['uuid']
+        kb = await self.ap.rag_mgr.create_knowledge_base(
+            name=kb_data.get('name', 'Untitled'),
+            knowledge_engine_plugin_id=knowledge_engine_plugin_id,
+            creation_settings=kb_data.get('creation_settings', {}),
+            retrieval_settings=kb_data.get('retrieval_settings', {}),
+            description=kb_data.get('description', ''),
+        )
+        return kb.uuid
 
     async def update_knowledge_base(self, kb_uuid: str, kb_data: dict) -> None:
         """更新知识库"""
-        if 'uuid' in kb_data:
-            del kb_data['uuid']
+        # Filter to only mutable fields
+        filtered_data = {k: v for k, v in kb_data.items() if k in persistence_rag.KnowledgeBase.MUTABLE_FIELDS}
 
-        if 'embedding_model_uuid' in kb_data:
-            del kb_data['embedding_model_uuid']
+        if not filtered_data:
+            return
 
         await self.ap.persistence_mgr.execute_async(
             sqlalchemy.update(persistence_rag.KnowledgeBase)
-            .values(kb_data)
+            .values(filtered_data)
             .where(persistence_rag.KnowledgeBase.uuid == kb_uuid)
         )
         await self.ap.rag_mgr.remove_knowledge_base_from_runtime(kb_uuid)
 
         kb = await self.get_knowledge_base(kb_uuid)
+        if kb is None:
+            raise Exception('Knowledge base not found after update')
 
         await self.ap.rag_mgr.load_knowledge_base(kb)
 
-    async def store_file(self, kb_uuid: str, file_id: str) -> int:
+    async def _check_doc_capability(self, kb_uuid: str, operation: str) -> None:
+        """Check if the KB's Knowledge Engine supports document operations.
+
+        Args:
+            kb_uuid: Knowledge base UUID.
+            operation: Human-readable operation name for error messages.
+
+        Raises:
+            Exception: If the KB does not support doc_ingestion.
+        """
+        kb_info = await self.ap.rag_mgr.get_knowledge_base_details(kb_uuid)
+        if not kb_info:
+            raise Exception('Knowledge base not found')
+        capabilities = kb_info.get('knowledge_engine', {}).get('capabilities', [])
+        if 'doc_ingestion' not in capabilities:
+            raise Exception(f'This knowledge base does not support {operation}')
+
+    async def store_file(self, kb_uuid: str, file_id: str, parser_plugin_id: str | None = None) -> str:
         """存储文件"""
-        # await self.ap.persistence_mgr.execute_async(sqlalchemy.insert(persistence_rag.File).values(kb_id=kb_uuid, file_id=file_id))
-        # await self.ap.rag_mgr.store_file(file_id)
         runtime_kb = await self.ap.rag_mgr.get_knowledge_base_by_uuid(kb_uuid)
         if runtime_kb is None:
             raise Exception('Knowledge base not found')
-        # Only internal KBs support file storage
-        if runtime_kb.get_type() != 'internal':
-            raise Exception('Only internal knowledge bases support file storage')
-        result = await runtime_kb.store_file(file_id)
+
+        await self._check_doc_capability(kb_uuid, 'document upload')
+
+        result = await runtime_kb.store_file(file_id, parser_plugin_id=parser_plugin_id)
 
         # Update the KB's updated_at timestamp
         await self.ap.persistence_mgr.execute_async(
@@ -85,14 +97,18 @@ class KnowledgeService:
 
         return result
 
-    async def retrieve_knowledge_base(self, kb_uuid: str, query: str) -> list[dict]:
+    async def retrieve_knowledge_base(
+        self, kb_uuid: str, query: str, retrieval_settings: dict | None = None
+    ) -> list[dict]:
         """检索知识库"""
         runtime_kb = await self.ap.rag_mgr.get_knowledge_base_by_uuid(kb_uuid)
         if runtime_kb is None:
             raise Exception('Knowledge base not found')
-        return [
-            result.model_dump() for result in await runtime_kb.retrieve(query, runtime_kb.knowledge_base_entity.top_k)
-        ]
+
+        # Pass retrieval_settings
+        results = await runtime_kb.retrieve(query, settings=retrieval_settings)
+
+        return [result.model_dump() for result in results]
 
     async def get_files_by_knowledge_base(self, kb_uuid: str) -> list[dict]:
         """获取知识库文件"""
@@ -107,9 +123,9 @@ class KnowledgeService:
         runtime_kb = await self.ap.rag_mgr.get_knowledge_base_by_uuid(kb_uuid)
         if runtime_kb is None:
             raise Exception('Knowledge base not found')
-        # Only internal KBs support file deletion
-        if runtime_kb.get_type() != 'internal':
-            raise Exception('Only internal knowledge bases support file deletion')
+
+        await self._check_doc_capability(kb_uuid, 'document deletion')
+
         await runtime_kb.delete_file(file_id)
 
         # Update the KB's updated_at timestamp
@@ -121,13 +137,14 @@ class KnowledgeService:
 
     async def delete_knowledge_base(self, kb_uuid: str) -> None:
         """删除知识库"""
-        await self.ap.rag_mgr.delete_knowledge_base(kb_uuid)
-
+        # Delete from DB first to commit the deletion, then clean up runtime/plugin (best-effort)
         await self.ap.persistence_mgr.execute_async(
             sqlalchemy.delete(persistence_rag.KnowledgeBase).where(persistence_rag.KnowledgeBase.uuid == kb_uuid)
         )
 
         # delete files
+        # NOTE: Chunk cleanup is for legacy (pre-plugin) KBs that stored chunks locally.
+        # For plugin-based Knowledge Engines, the Chunk table is not populated, so this is a no-op.
         files = await self.ap.persistence_mgr.execute_async(
             sqlalchemy.select(persistence_rag.File).where(persistence_rag.File.kb_id == kb_uuid)
         )
@@ -140,3 +157,53 @@ class KnowledgeService:
             await self.ap.persistence_mgr.execute_async(
                 sqlalchemy.delete(persistence_rag.File).where(persistence_rag.File.uuid == file.uuid)
             )
+
+        # Remove from runtime and notify plugin (best-effort, DB is already cleaned up)
+        await self.ap.rag_mgr.delete_knowledge_base(kb_uuid)
+
+    # ================= Knowledge Engine Discovery =================
+
+    async def list_knowledge_engines(self) -> list[dict]:
+        """List all available Knowledge Engines from plugins."""
+        engines = []
+
+        if not self.ap.plugin_connector.is_enable_plugin:
+            return engines
+
+        # Get KnowledgeEngine plugins
+        try:
+            knowledge_engines = await self.ap.plugin_connector.list_knowledge_engines()
+            engines.extend(knowledge_engines)
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to list Knowledge Engines from plugins: {e}')
+
+        return engines
+
+    async def list_parsers(self, mime_type: str | None = None) -> list[dict]:
+        """List available parsers, optionally filtered by MIME type."""
+        if not self.ap.plugin_connector.is_enable_plugin:
+            return []
+        try:
+            parsers = await self.ap.plugin_connector.list_parsers()
+            if mime_type:
+                parsers = [p for p in parsers if mime_type in p.get('supported_mime_types', [])]
+            return parsers
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to list parsers: {e}')
+            return []
+
+    async def get_engine_creation_schema(self, plugin_id: str) -> dict:
+        """Get creation settings schema for a specific Knowledge Engine."""
+        try:
+            return await self.ap.plugin_connector.get_rag_creation_schema(plugin_id)
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to get creation schema for {plugin_id}: {e}')
+            return {}
+
+    async def get_engine_retrieval_schema(self, plugin_id: str) -> dict:
+        """Get retrieval settings schema for a specific Knowledge Engine."""
+        try:
+            return await self.ap.plugin_connector.get_rag_retrieval_schema(plugin_id)
+        except Exception as e:
+            self.ap.logger.warning(f'Failed to get retrieval schema for {plugin_id}: {e}')
+            return {}

src/langbot/pkg/api/http/service/monitoring.py

@@ -30,6 +30,7 @@ class MonitoringService:
         level: str = 'info',
         platform: str | None = None,
         user_id: str | None = None,
+        user_name: str | None = None,
         runner_name: str | None = None,
         variables: str | None = None,
         role: str = 'user',
@@ -49,6 +50,7 @@ class MonitoringService:
             'level': level,
             'platform': platform,
             'user_id': user_id,
+            'user_name': user_name,
             'runner_name': runner_name,
             'variables': variables,
             'role': role,
@@ -152,6 +154,7 @@ class MonitoringService:
         pipeline_name: str,
         platform: str | None = None,
         user_id: str | None = None,
+        user_name: str | None = None,
     ) -> None:
         """Record a new session"""
         session_data = {
@@ -166,6 +169,7 @@ class MonitoringService:
             'is_active': True,
             'platform': platform,
             'user_id': user_id,
+            'user_name': user_name,
         }
 
         await self.ap.persistence_mgr.execute_async(

src/langbot/pkg/core/app.py

@@ -29,7 +29,6 @@ from ..api.http.service import knowledge as knowledge_service
 from ..api.http.service import mcp as mcp_service
 from ..api.http.service import apikey as apikey_service
 from ..api.http.service import webhook as webhook_service
-from ..api.http.service import external_kb as external_kb_service
 from ..api.http.service import monitoring as monitoring_service
 from ..discover import engine as discover_engine
 from ..storage import mgr as storagemgr
@@ -37,6 +36,7 @@ from ..utils import logcache
 from . import taskmgr
 from . import entities as core_entities
 from ..rag.knowledge import kbmgr as rag_mgr
+from ..rag.service import RAGRuntimeService
 from ..vector import mgr as vectordb_mgr
 from ..telemetry import telemetry as telemetry_module
 from ..survey import manager as survey_module
@@ -63,6 +63,7 @@ class Application:
     model_mgr: llm_model_mgr.ModelManager = None
 
     rag_mgr: rag_mgr.RAGManager = None
+    rag_runtime_service: RAGRuntimeService = None
 
     # TODO move to pipeline
     tool_mgr: llm_tool_mgr.ToolManager = None
@@ -138,8 +139,6 @@ class Application:
 
     knowledge_service: knowledge_service.KnowledgeService = None
 
-    external_kb_service: external_kb_service.ExternalKBService = None
-
     mcp_service: mcp_service.MCPService = None
 
     apikey_service: apikey_service.ApiKeyService = None

src/langbot/pkg/core/stages/build_app.py

@@ -12,6 +12,7 @@ from ...provider.session import sessionmgr as llm_session_mgr
 from ...provider.modelmgr import modelmgr as llm_model_mgr
 from ...provider.tools import toolmgr as llm_tool_mgr
 from ...rag.knowledge import kbmgr as rag_mgr
+from ...rag.service import RAGRuntimeService
 from ...platform import botmgr as im_mgr
 from ...platform.webhook_pusher import WebhookPusher
 from ...persistence import mgr as persistencemgr
@@ -26,7 +27,6 @@ from ...api.http.service import knowledge as knowledge_service
 from ...api.http.service import mcp as mcp_service
 from ...api.http.service import apikey as apikey_service
 from ...api.http.service import webhook as webhook_service
-from ...api.http.service import external_kb as external_kb_service
 from ...api.http.service import monitoring as monitoring_service
 from ...discover import engine as discover_engine
 from ...storage import mgr as storagemgr
@@ -73,9 +73,6 @@ class BuildAppStage(stage.BootingStage):
         knowledge_service_inst = knowledge_service.KnowledgeService(ap)
         ap.knowledge_service = knowledge_service_inst
 
-        external_kb_service_inst = external_kb_service.ExternalKBService(ap)
-        ap.external_kb_service = external_kb_service_inst
-
         mcp_service_inst = mcp_service.MCPService(ap)
         ap.mcp_service = mcp_service_inst
 
@@ -152,6 +149,9 @@ class BuildAppStage(stage.BootingStage):
         await rag_mgr_inst.initialize()
         ap.rag_mgr = rag_mgr_inst
 
+        # Initialize RAG Runtime Service for plugins
+        ap.rag_runtime_service = RAGRuntimeService(ap)
+
         # 初始化向量数据库管理器
         vectordb_mgr_inst = vectordb_mgr.VectorDBManager(ap)
         await vectordb_mgr_inst.initialize()

src/langbot/pkg/entity/persistence/monitoring.py

@@ -20,6 +20,7 @@ class MonitoringMessage(Base):
     level = sqlalchemy.Column(sqlalchemy.String(50), nullable=False)  # info, warning, error, debug
     platform = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
     user_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    user_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)  # User display name
     runner_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)  # Runner name for this query
     variables = sqlalchemy.Column(sqlalchemy.Text, nullable=True)  # Query variables as JSON string
     role = sqlalchemy.Column(sqlalchemy.String(50), nullable=True, default='user')  # user, assistant
@@ -64,6 +65,7 @@ class MonitoringSession(Base):
     is_active = sqlalchemy.Column(sqlalchemy.Boolean, nullable=False, default=True, index=True)
     platform = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
     user_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
+    user_name = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)  # User display name
 
 
 class MonitoringError(Base):

src/langbot/pkg/entity/persistence/rag.py

@@ -10,8 +10,21 @@ class KnowledgeBase(Base):
     emoji = sqlalchemy.Column(sqlalchemy.String(10), nullable=True, default='📚')
     created_at = sqlalchemy.Column(sqlalchemy.DateTime, default=sqlalchemy.func.now())
     updated_at = sqlalchemy.Column(sqlalchemy.DateTime, default=sqlalchemy.func.now(), onupdate=sqlalchemy.func.now())
-    embedding_model_uuid = sqlalchemy.Column(sqlalchemy.String, default='')
-    top_k = sqlalchemy.Column(sqlalchemy.Integer, default=5)
+    # New fields for plugin-based RAG
+    knowledge_engine_plugin_id = sqlalchemy.Column(sqlalchemy.String, nullable=True)
+    collection_id = sqlalchemy.Column(sqlalchemy.String, nullable=True)
+    creation_settings = sqlalchemy.Column(sqlalchemy.JSON, nullable=True, default=None)
+    retrieval_settings = sqlalchemy.Column(sqlalchemy.JSON, nullable=True, default=None)
+
+    # Field sets for different operations
+    MUTABLE_FIELDS = {'name', 'description', 'retrieval_settings'}
+    """Fields that can be updated after creation."""
+
+    CREATE_FIELDS = MUTABLE_FIELDS | {'uuid', 'knowledge_engine_plugin_id', 'collection_id', 'creation_settings'}
+    """Fields used when creating a new knowledge base."""
+
+    ALL_DB_FIELDS = CREATE_FIELDS | {'emoji', 'created_at', 'updated_at'}
+    """All fields stored in database (for loading from DB row)."""
 
 
 class File(Base):
@@ -29,16 +42,3 @@ class Chunk(Base):
     uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
     file_id = sqlalchemy.Column(sqlalchemy.String(255), nullable=True)
     text = sqlalchemy.Column(sqlalchemy.Text)
-
-
-class ExternalKnowledgeBase(Base):
-    __tablename__ = 'external_knowledge_bases'
-    uuid = sqlalchemy.Column(sqlalchemy.String(255), primary_key=True, unique=True)
-    name = sqlalchemy.Column(sqlalchemy.String, index=True)
-    description = sqlalchemy.Column(sqlalchemy.Text)
-    emoji = sqlalchemy.Column(sqlalchemy.String(10), nullable=True, default='🔗')
-    plugin_author = sqlalchemy.Column(sqlalchemy.String, nullable=False)
-    plugin_name = sqlalchemy.Column(sqlalchemy.String, nullable=False)
-    retriever_name = sqlalchemy.Column(sqlalchemy.String, nullable=False)
-    retriever_config = sqlalchemy.Column(sqlalchemy.JSON, nullable=False, default={})
-    created_at = sqlalchemy.Column(sqlalchemy.DateTime, default=sqlalchemy.func.now())

src/langbot/pkg/persistence/migrations/dbm020_knowledge_engine_plugin_architecture.py

@@ -0,0 +1,161 @@
+import sqlalchemy
+from .. import migration
+
+
+@migration.migration_class(20)
+class DBMigrateKnowledgeEnginePluginArchitecture(migration.DBMigration):
+    """Migrate to unified Knowledge Engine plugin architecture.
+
+    Changes:
+    - Backup existing knowledge_bases data to knowledge_bases_backup
+    - Clear knowledge_bases table and add new plugin architecture columns
+    - Drop old columns (PostgreSQL only; SQLite leaves them unmapped)
+    - Preserve external_knowledge_bases table as-is for future migration
+    - Set rag_plugin_migration_needed flag in metadata if old data exists
+    """
+
+    async def upgrade(self):
+        """Upgrade"""
+        has_internal_data = await self._backup_knowledge_bases()
+        has_external_data = await self._check_external_knowledge_bases()
+        await self._clear_knowledge_bases()
+        await self._add_columns_to_knowledge_bases()
+        await self._drop_old_columns()
+        if has_internal_data or has_external_data:
+            await self._set_migration_flag()
+
+    async def _get_table_columns(self, table_name: str) -> list[str]:
+        """Get column names from a table (works for both SQLite and PostgreSQL)."""
+        if self.ap.persistence_mgr.db.name == 'postgresql':
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text(
+                    'SELECT column_name FROM information_schema.columns WHERE table_name = :table_name;'
+                ).bindparams(table_name=table_name)
+            )
+            return [row[0] for row in result.fetchall()]
+        else:
+            # SQLite PRAGMA does not support bind parameters; validate identifier.
+            if not table_name.isidentifier():
+                raise ValueError(f'Invalid table name: {table_name}')
+            result = await self.ap.persistence_mgr.execute_async(sqlalchemy.text(f'PRAGMA table_info({table_name});'))
+            return [row[1] for row in result.fetchall()]
+
+    async def _table_exists(self, table_name: str) -> bool:
+        """Check if a table exists."""
+        if self.ap.persistence_mgr.db.name == 'postgresql':
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text(
+                    'SELECT EXISTS (SELECT FROM information_schema.tables WHERE table_name = :table_name);'
+                ).bindparams(table_name=table_name)
+            )
+            return result.scalar()
+        else:
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text("SELECT name FROM sqlite_master WHERE type='table' AND name=:table_name;").bindparams(
+                    table_name=table_name
+                )
+            )
+            return result.first() is not None
+
+    async def _backup_knowledge_bases(self) -> bool:
+        """Backup knowledge_bases data. Returns True if data was backed up."""
+        result = await self.ap.persistence_mgr.execute_async(sqlalchemy.text('SELECT COUNT(*) FROM knowledge_bases;'))
+        count = result.scalar()
+        if count == 0:
+            return False
+
+        # Drop backup table if it already exists (from a previous failed migration)
+        if await self._table_exists('knowledge_bases_backup'):
+            await self.ap.persistence_mgr.execute_async(sqlalchemy.text('DROP TABLE knowledge_bases_backup;'))
+
+        await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.text('CREATE TABLE knowledge_bases_backup AS SELECT * FROM knowledge_bases;')
+        )
+        self.ap.logger.info(
+            'Backed up %d knowledge base(s) to knowledge_bases_backup table.',
+            count,
+        )
+        return True
+
+    async def _check_external_knowledge_bases(self) -> bool:
+        """Check if external_knowledge_bases table exists and has data.
+
+        The table is preserved as-is (not dropped) for future migration.
+        """
+        if not await self._table_exists('external_knowledge_bases'):
+            return False
+
+        result = await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.text('SELECT COUNT(*) FROM external_knowledge_bases;')
+        )
+        count = result.scalar()
+        if count > 0:
+            self.ap.logger.info(
+                'Found %d external knowledge base(s) in external_knowledge_bases table. '
+                'Table preserved for future migration.',
+                count,
+            )
+        return count > 0
+
+    async def _clear_knowledge_bases(self):
+        """Clear all rows from knowledge_bases table (preserve table structure)."""
+        await self.ap.persistence_mgr.execute_async(sqlalchemy.text('DELETE FROM knowledge_bases;'))
+
+    async def _add_columns_to_knowledge_bases(self):
+        """Add new RAG plugin architecture columns to knowledge_bases table."""
+        columns = await self._get_table_columns('knowledge_bases')
+
+        new_columns = {
+            'knowledge_engine_plugin_id': 'VARCHAR',
+            'collection_id': 'VARCHAR',
+            'creation_settings': 'TEXT',  # JSON stored as TEXT for SQLite compatibility
+            'retrieval_settings': 'TEXT',
+        }
+
+        for col_name, col_type in new_columns.items():
+            if col_name not in columns:
+                await self.ap.persistence_mgr.execute_async(
+                    sqlalchemy.text(f'ALTER TABLE knowledge_bases ADD COLUMN {col_name} {col_type};')
+                )
+
+    async def _drop_old_columns(self):
+        """Drop embedding_model_uuid and top_k columns (PostgreSQL only).
+
+        SQLite does not support DROP COLUMN in older versions, so we leave the
+        columns in place — the SQLAlchemy entity simply won't map them.
+        """
+        if self.ap.persistence_mgr.db.name != 'postgresql':
+            return
+
+        columns = await self._get_table_columns('knowledge_bases')
+
+        if 'embedding_model_uuid' in columns:
+            await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text('ALTER TABLE knowledge_bases DROP COLUMN embedding_model_uuid;')
+            )
+
+        if 'top_k' in columns:
+            await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text('ALTER TABLE knowledge_bases DROP COLUMN top_k;')
+            )
+
+    async def _set_migration_flag(self):
+        """Set rag_plugin_migration_needed flag in metadata table."""
+        # Check if the key already exists
+        result = await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.text("SELECT value FROM metadata WHERE key = 'rag_plugin_migration_needed';")
+        )
+        row = result.first()
+        if row is not None:
+            await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text("UPDATE metadata SET value = 'true' WHERE key = 'rag_plugin_migration_needed';")
+            )
+        else:
+            await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text("INSERT INTO metadata (key, value) VALUES ('rag_plugin_migration_needed', 'true');")
+            )
+        self.ap.logger.info('Set rag_plugin_migration_needed=true in metadata.')
+
+    async def downgrade(self):
+        """Downgrade"""
+        pass

src/langbot/pkg/persistence/migrations/dbm021_merge_exception_handling.py

@@ -0,0 +1,74 @@
+from .. import migration
+
+import sqlalchemy
+import json
+
+
+@migration.migration_class(21)
+class DBMigrateMergeExceptionHandling(migration.DBMigration):
+    """Merge hide-exception and block-failed-request-output into a single exception-handling select option,
+    and add failure-hint field.
+
+    Conversion logic:
+    - block-failed-request-output=true  ->  exception-handling: hide
+    - hide-exception=true               ->  exception-handling: show-hint
+    - hide-exception=false              ->  exception-handling: show-error
+    """
+
+    async def upgrade(self):
+        """Upgrade"""
+        result = await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.text('SELECT uuid, config FROM legacy_pipelines')
+        )
+        pipelines = result.fetchall()
+
+        current_version = self.ap.ver_mgr.get_current_version()
+
+        for pipeline_row in pipelines:
+            uuid = pipeline_row[0]
+            config = json.loads(pipeline_row[1]) if isinstance(pipeline_row[1], str) else pipeline_row[1]
+
+            if 'output' not in config:
+                config['output'] = {}
+            if 'misc' not in config['output']:
+                config['output']['misc'] = {}
+
+            misc = config['output']['misc']
+
+            # Determine new exception-handling value from legacy fields
+            hide_exception = misc.get('hide-exception', True)
+            block_failed = misc.get('block-failed-request-output', False)
+
+            if block_failed:
+                exception_handling = 'hide'
+            elif hide_exception:
+                exception_handling = 'show-hint'
+            else:
+                exception_handling = 'show-error'
+
+            misc['exception-handling'] = exception_handling
+
+            # Add failure-hint with default value
+            misc['failure-hint'] = 'Request failed.'
+
+            # Remove legacy fields
+            misc.pop('hide-exception', None)
+
+            if self.ap.persistence_mgr.db.name == 'postgresql':
+                await self.ap.persistence_mgr.execute_async(
+                    sqlalchemy.text(
+                        'UPDATE legacy_pipelines SET config = :config::jsonb, for_version = :for_version WHERE uuid = :uuid'
+                    ),
+                    {'config': json.dumps(config), 'for_version': current_version, 'uuid': uuid},
+                )
+            else:
+                await self.ap.persistence_mgr.execute_async(
+                    sqlalchemy.text(
+                        'UPDATE legacy_pipelines SET config = :config, for_version = :for_version WHERE uuid = :uuid'
+                    ),
+                    {'config': json.dumps(config), 'for_version': current_version, 'uuid': uuid},
+                )
+
+    async def downgrade(self):
+        """Downgrade"""
+        pass

src/langbot/pkg/persistence/migrations/dbm022_monitoring_user_name.py

@@ -0,0 +1,73 @@
+import sqlalchemy
+from .. import migration
+
+
+@migration.migration_class(22)
+class DBMigrateMonitoringUserId(migration.DBMigration):
+    """Add user_id and user_name columns to monitoring_sessions table
+
+    This migration adds the missing user_id column and also ensures user_name
+    column exists (in case migration 21 failed or was skipped).
+    """
+
+    async def _table_exists(self, table_name: str) -> bool:
+        """Check if a table exists (works for both SQLite and PostgreSQL)."""
+        if self.ap.persistence_mgr.db.name == 'postgresql':
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text(
+                    'SELECT EXISTS (SELECT FROM information_schema.tables WHERE table_name = :table_name);'
+                ).bindparams(table_name=table_name)
+            )
+            return bool(result.scalar())
+        else:
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text("SELECT name FROM sqlite_master WHERE type='table' AND name=:table_name;").bindparams(
+                    table_name=table_name
+                )
+            )
+            return result.first() is not None
+
+    async def _get_table_columns(self, table_name: str) -> list[str]:
+        """Get column names from a table (works for both SQLite and PostgreSQL)."""
+        if self.ap.persistence_mgr.db.name == 'postgresql':
+            result = await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.text(
+                    'SELECT column_name FROM information_schema.columns WHERE table_name = :table_name;'
+                ).bindparams(table_name=table_name)
+            )
+            return [row[0] for row in result.fetchall()]
+        else:
+            if not table_name.isidentifier():
+                raise ValueError(f'Invalid table name: {table_name}')
+            result = await self.ap.persistence_mgr.execute_async(sqlalchemy.text(f'PRAGMA table_info({table_name});'))
+            return [row[1] for row in result.fetchall()]
+
+    async def _add_column_if_not_exists(self, table_name: str, column_name: str, column_type: str):
+        """Add a column to a table if it does not already exist."""
+        columns = await self._get_table_columns(table_name)
+        if column_name in columns:
+            self.ap.logger.debug('%s column already exists in %s.', column_name, table_name)
+            return
+        await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.text(f'ALTER TABLE {table_name} ADD COLUMN {column_name} {column_type};')
+        )
+        self.ap.logger.info('Added %s column to %s table.', column_name, table_name)
+
+    async def upgrade(self):
+        # Check if monitoring_sessions table exists
+        if not await self._table_exists('monitoring_sessions'):
+            self.ap.logger.warning('monitoring_sessions table does not exist, skipping migration.')
+            return
+
+        # Add user_id column to monitoring_sessions table
+        await self._add_column_if_not_exists('monitoring_sessions', 'user_id', 'VARCHAR(255)')
+
+        # Add user_name column to monitoring_sessions table (in case migration 21 failed)
+        await self._add_column_if_not_exists('monitoring_sessions', 'user_name', 'VARCHAR(255)')
+
+        # Add user_name column to monitoring_messages table (in case migration 21 failed)
+        if await self._table_exists('monitoring_messages'):
+            await self._add_column_if_not_exists('monitoring_messages', 'user_name', 'VARCHAR(255)')
+
+    async def downgrade(self):
+        pass

src/langbot/pkg/pipeline/config_coercion.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# metadata type -> coercion function
+_COERCE_MAP = {
+    'integer': lambda v: int(v),
+    'number': lambda v: float(v),
+    'float': lambda v: float(v),
+}
+
+
+def _coerce_bool(v):
+    if isinstance(v, bool):
+        return v
+    if isinstance(v, str):
+        if v.lower() == 'true':
+            return True
+        if v.lower() == 'false':
+            return False
+        raise ValueError(f'Cannot convert string {v!r} to bool')
+    return bool(v)
+
+
+def _coerce_value(value, expected_type: str):
+    """Convert a single value to the expected type.
+
+    Returns the converted value, or the original value if no conversion needed.
+    """
+    if value is None:
+        return value
+
+    if expected_type == 'boolean':
+        if isinstance(value, bool):
+            return value
+        return _coerce_bool(value)
+
+    coerce_fn = _COERCE_MAP.get(expected_type)
+    if coerce_fn is None:
+        return value
+
+    # Already the correct type
+    if expected_type == 'integer' and isinstance(value, int) and not isinstance(value, bool):
+        return value
+    if expected_type in ('number', 'float') and isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+
+    return coerce_fn(value)
+
+
+def coerce_pipeline_config(
+    config: dict,
+    *metadata_list: dict,
+) -> None:
+    """Coerce pipeline config values according to metadata type definitions.
+
+    Walks each metadata dict (trigger, safety, ai, output) and converts
+    config values in-place so that strings coming from the JSON column are
+    cast to their declared types (integer, number/float, boolean).
+
+    Args:
+        config: The pipeline config dict to modify in-place.
+        *metadata_list: Metadata dicts loaded from the YAML templates.
+    """
+    for meta in metadata_list:
+        section_name = meta.get('name')
+        if not section_name or section_name not in config:
+            continue
+
+        section = config[section_name]
+        if not isinstance(section, dict):
+            continue
+
+        for stage_def in meta.get('stages', []):
+            stage_name = stage_def.get('name')
+            if not stage_name or stage_name not in section:
+                continue
+
+            stage_config = section[stage_name]
+            if not isinstance(stage_config, dict):
+                continue
+
+            for field_def in stage_def.get('config', []):
+                field_name = field_def.get('name')
+                field_type = field_def.get('type')
+                if not field_name or not field_type or field_name not in stage_config:
+                    continue
+
+                old_value = stage_config[field_name]
+                try:
+                    new_value = _coerce_value(old_value, field_type)
+                    if new_value is not old_value:
+                        stage_config[field_name] = new_value
+                except (ValueError, TypeError) as e:
+                    logger.warning(
+                        'Failed to coerce config %s.%s.%s (%r) to %s: %s',
+                        section_name,
+                        stage_name,
+                        field_name,
+                        old_value,
+                        field_type,
+                        e,
+                    )

src/langbot/pkg/pipeline/monitoring_helper.py

@@ -34,6 +34,15 @@ class MonitoringHelper:
             # Check if session exists, if not, record session start
             session_id = f'{query.launcher_type}_{query.launcher_id}'
 
+            # Get sender name from message event
+            sender_name = None
+            if hasattr(query, 'message_event'):
+                if hasattr(query.message_event, 'sender'):
+                    if hasattr(query.message_event.sender, 'nickname'):
+                        sender_name = query.message_event.sender.nickname
+                    elif hasattr(query.message_event.sender, 'member_name'):
+                        sender_name = query.message_event.sender.member_name
+
             # Try to record message
             # Use JSON serialization to preserve message chain structure (including image URLs, etc.)
             if hasattr(query, 'message_chain') and hasattr(query.message_chain, 'model_dump'):
@@ -57,6 +66,7 @@ class MonitoringHelper:
                 if hasattr(query.launcher_type, 'value')
                 else str(query.launcher_type),
                 user_id=query.sender_id,
+                user_name=sender_name,
                 runner_name=runner_name,
                 variables=None,  # Will be updated in record_query_success
             )
@@ -80,6 +90,7 @@ class MonitoringHelper:
                     if hasattr(query.launcher_type, 'value')
                     else str(query.launcher_type),
                     user_id=query.sender_id,
+                    user_name=sender_name,
                 )
 
             return message_id
@@ -128,6 +139,15 @@ class MonitoringHelper:
         try:
             session_id = f'{query.launcher_type}_{query.launcher_id}'
 
+            # Get sender name from message event
+            sender_name = None
+            if hasattr(query, 'message_event'):
+                if hasattr(query.message_event, 'sender'):
+                    if hasattr(query.message_event.sender, 'nickname'):
+                        sender_name = query.message_event.sender.nickname
+                    elif hasattr(query.message_event.sender, 'member_name'):
+                        sender_name = query.message_event.sender.member_name
+
             # Extract response content from resp_message_chain
             if hasattr(query, 'resp_message_chain') and query.resp_message_chain:
                 # Serialize the last response message chain
@@ -162,6 +182,7 @@ class MonitoringHelper:
                 if hasattr(query.launcher_type, 'value')
                 else str(query.launcher_type),
                 user_id=query.sender_id,
+                user_name=sender_name,
                 runner_name=runner_name,
                 role='assistant',
             )
@@ -183,6 +204,15 @@ class MonitoringHelper:
         try:
             session_id = f'{query.launcher_type}_{query.launcher_id}'
 
+            # Get sender name from message event
+            sender_name = None
+            if hasattr(query, 'message_event'):
+                if hasattr(query.message_event, 'sender'):
+                    if hasattr(query.message_event.sender, 'nickname'):
+                        sender_name = query.message_event.sender.nickname
+                    elif hasattr(query.message_event.sender, 'member_name'):
+                        sender_name = query.message_event.sender.member_name
+
             # Record error message
             message_id = await ap.monitoring_service.record_message(
                 bot_id=bot_id,
@@ -197,6 +227,7 @@ class MonitoringHelper:
                 if hasattr(query.launcher_type, 'value')
                 else str(query.launcher_type),
                 user_id=query.sender_id,
+                user_name=sender_name,
                 runner_name=runner_name,
             )
 

src/langbot/pkg/pipeline/pipelinemgr.py

@@ -13,6 +13,7 @@ import langbot_plugin.api.entities.builtin.platform.message as platform_message
 import langbot_plugin.api.entities.builtin.platform.events as platform_events
 import langbot_plugin.api.entities.events as events
 from ..utils import importutil
+from .config_coercion import coerce_pipeline_config
 
 import langbot_plugin.api.entities.builtin.provider.session as provider_session
 import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
@@ -420,6 +421,14 @@ class PipelineManager:
         elif isinstance(pipeline_entity, dict):
             pipeline_entity = persistence_pipeline.LegacyPipeline(**pipeline_entity)
 
+        coerce_pipeline_config(
+            pipeline_entity.config,
+            getattr(self.ap, 'pipeline_config_meta_trigger', {'name': 'trigger', 'stages': []}),
+            getattr(self.ap, 'pipeline_config_meta_safety', {'name': 'safety', 'stages': []}),
+            getattr(self.ap, 'pipeline_config_meta_ai', {'name': 'ai', 'stages': []}),
+            getattr(self.ap, 'pipeline_config_meta_output', {'name': 'output', 'stages': []}),
+        )
+
         # initialize stage containers according to pipeline_entity.stages
         stage_containers: list[StageInstContainer] = []
         for stage_name in pipeline_entity.stages:

src/langbot/pkg/pipeline/process/handlers/chat.py

@@ -12,7 +12,7 @@ from ... import entities
 from ....provider import runner as runner_module
 
 import langbot_plugin.api.entities.events as events
-from ....utils import importutil, constants
+from ....utils import importutil, constants, runner as runner_utils
 from ....provider import runners
 import langbot_plugin.api.entities.builtin.provider.session as provider_session
 import langbot_plugin.api.entities.builtin.pipeline.query as pipeline_query
@@ -149,12 +149,19 @@ class ChatMessageHandler(handler.MessageHandler):
                 self.ap.logger.error(f'Conversation({query.query_id}) Request Failed: {error_info}')
                 traceback.print_exc()
 
-                hide_exception_info = query.pipeline_config['output']['misc']['hide-exception']
+                exception_handling = query.pipeline_config['output']['misc'].get('exception-handling', 'show-hint')
+
+                if exception_handling == 'show-error':
+                    user_notice = f'{e}'
+                elif exception_handling == 'show-hint':
+                    user_notice = query.pipeline_config['output']['misc'].get('failure-hint', 'Request failed.')
+                else:  # hide
+                    user_notice = None
 
                 yield entities.StageProcessResult(
                     result_type=entities.ResultType.INTERRUPT,
                     new_query=query,
-                    user_notice='请求失败' if hide_exception_info else f'{e}',
+                    user_notice=user_notice,
                     error_notice=f'{e}',
                     debug_notice=traceback.format_exc(),
                 )
@@ -185,10 +192,15 @@ class ChatMessageHandler(handler.MessageHandler):
 
                     pipeline_plugins = query.variables.get('_pipeline_bound_plugins', None)
 
+                    runner_category = runner_utils.get_runner_category_from_runner(
+                        runner_name, runner, query.pipeline_config
+                    )
+
                     payload = {
                         'query_id': query.query_id,
                         'adapter': adapter_name,
                         'runner': runner_name,
+                        'runner_category': runner_category,
                         'duration_ms': duration_ms,
                         'model_name': model_name,
                         'version': constants.semantic_version,

src/langbot/pkg/platform/botmgr.py

@@ -282,6 +282,8 @@ class PlatformManager:
         return runtime_bot
 
     async def get_bot_by_uuid(self, bot_uuid: str) -> RuntimeBot | None:
+        if self.websocket_proxy_bot and self.websocket_proxy_bot.bot_entity.uuid == bot_uuid:
+            return self.websocket_proxy_bot
         for bot in self.bots:
             if bot.bot_entity.uuid == bot_uuid:
                 return bot

src/langbot/pkg/platform/sources/telegram.py

@@ -1,4 +1,5 @@
 from __future__ import annotations
+import time
 
 
 import telegram
@@ -250,6 +251,39 @@ class TelegramAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
 
         await self.bot.send_message(**args)
 
+    def _process_markdown(self, text: str) -> str:
+        if self.config.get('markdown_card', False):
+            return telegramify_markdown.markdownify(content=text)
+        return text
+
+    def _build_message_args(self, chat_id: int, text: str, message_thread_id: int = None, **extra_args) -> dict:
+        args = {'chat_id': chat_id, 'text': self._process_markdown(text), **extra_args}
+        if message_thread_id:
+            args['message_thread_id'] = message_thread_id
+        if self.config.get('markdown_card', False):
+            args['parse_mode'] = 'MarkdownV2'
+        return args
+
+    async def create_message_card(self, message_id, event):
+        assert isinstance(event.source_platform_object, Update)
+        update = event.source_platform_object
+        chat_id = update.effective_chat.id
+        chat_type = update.effective_chat.type
+        message_thread_id = update.message.message_thread_id
+
+        if chat_type == 'private':
+            draft_id = int(time.time() * 1000)
+            self.msg_stream_id[message_id] = ('private', draft_id)
+
+            args = self._build_message_args(chat_id, 'Thinking...', message_thread_id, draft_id=draft_id)
+            await self.bot.send_message_draft(**args)
+        else:
+            args = self._build_message_args(chat_id, 'Thinking...', message_thread_id)
+            send_msg = await self.bot.send_message(**args)
+            self.msg_stream_id[message_id] = ('group', send_msg.message_id)
+
+        return True
+
     async def reply_message_chunk(
         self,
         message_source: platform_events.MessageEvent,
@@ -258,59 +292,47 @@ class TelegramAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
         quote_origin: bool = False,
         is_final: bool = False,
     ):
+        message_id = bot_message.resp_message_id
         msg_seq = bot_message.msg_sequence
-        if (msg_seq - 1) % 8 == 0 or is_final:
-            assert isinstance(message_source.source_platform_object, Update)
-            components = await TelegramMessageConverter.yiri2target(message, self.bot)
-            args = {}
-            message_id = message_source.source_platform_object.message.id
+        assert isinstance(message_source.source_platform_object, Update)
+        update = message_source.source_platform_object
+        chat_id = update.effective_chat.id
+        message_thread_id = update.message.message_thread_id
 
-            component = components[0]
-            if message_id not in self.msg_stream_id:  # 当消息回复第一次时，发送新消息
-                # time.sleep(0.6)
-                if component['type'] == 'text':
-                    if self.config['markdown_card'] is True:
-                        content = telegramify_markdown.markdownify(
-                            content=component['text'],
-                        )
-                    else:
-                        content = component['text']
-                    args = {
-                        'chat_id': message_source.source_platform_object.effective_chat.id,
-                        'text': content,
-                    }
-                    if message_source.source_platform_object.message.message_thread_id:
-                        args['message_thread_id'] = message_source.source_platform_object.message.message_thread_id
+        if message_id not in self.msg_stream_id:
+            return
 
-                    if quote_origin:
-                        args['reply_to_message_id'] = message_source.source_platform_object.message.id
+        chat_mode, draft_id = self.msg_stream_id[message_id]
+        components = await TelegramMessageConverter.yiri2target(message, self.bot)
 
-                    if self.config['markdown_card'] is True:
-                        args['parse_mode'] = 'MarkdownV2'
-
-                send_msg = await self.bot.send_message(**args)
-                send_msg_id = send_msg.message_id
-                self.msg_stream_id[message_id] = send_msg_id
-            else:  # 存在消息的时候直接编辑消息1
-                if component['type'] == 'text':
-                    if self.config['markdown_card'] is True:
-                        content = telegramify_markdown.markdownify(
-                            content=component['text'],
-                        )
-                    else:
-                        content = component['text']
-                    args = {
-                        'message_id': self.msg_stream_id[message_id],
-                        'chat_id': message_source.source_platform_object.effective_chat.id,
-                        'text': content,
-                    }
-                    if self.config['markdown_card'] is True:
-                        args['parse_mode'] = 'MarkdownV2'
-
-                await self.bot.edit_message_text(**args)
+        if not components or components[0]['type'] != 'text':
             if is_final and bot_message.tool_calls is None:
-                # self.seq = 1  # 消息回复结束之后重置seq
-                self.msg_stream_id.pop(message_id)  # 消息回复结束之后删除流式消息id
+                self.msg_stream_id.pop(message_id)
+            return
+
+        content = components[0]['text']
+
+        if chat_mode == 'private':
+            args = self._build_message_args(chat_id, content, message_thread_id, draft_id=draft_id)
+            await self.bot.send_message_draft(**args)
+            if is_final and bot_message.tool_calls is None:
+                del args['draft_id']
+                await self.bot.send_message(**args)
+                self.msg_stream_id.pop(message_id)
+        else:
+            stream_id = draft_id
+            if (msg_seq - 1) % 8 == 0 or is_final:
+                args = {
+                    'message_id': stream_id,
+                    'chat_id': chat_id,
+                    'text': self._process_markdown(content),
+                }
+                if self.config.get('markdown_card', False):
+                    args['parse_mode'] = 'MarkdownV2'
+                await self.bot.edit_message_text(**args)
+
+            if is_final and bot_message.tool_calls is None:
+                self.msg_stream_id.pop(message_id)
 
     def get_launcher_id(self, event: platform_events.MessageEvent) -> str | None:
         if not isinstance(event.source_platform_object, Update):

src/langbot/pkg/platform/sources/websocket_adapter.py

@@ -37,16 +37,24 @@ class WebSocketSession:
     id: str
     message_lists: dict[str, list[WebSocketMessage]] = {}
     """消息列表 {pipeline_uuid: [messages]}"""
+    stream_message_indexes: dict[str, dict[str, int]] = {}
+    """流式消息索引 {pipeline_uuid: {resp_message_id: message_index}}"""
 
     def __init__(self, id: str):
         self.id = id
         self.message_lists = {}
+        self.stream_message_indexes = {}
 
     def get_message_list(self, pipeline_uuid: str) -> list[WebSocketMessage]:
         if pipeline_uuid not in self.message_lists:
             self.message_lists[pipeline_uuid] = []
         return self.message_lists[pipeline_uuid]
 
+    def get_stream_message_indexes(self, pipeline_uuid: str) -> dict[str, int]:
+        if pipeline_uuid not in self.stream_message_indexes:
+            self.stream_message_indexes[pipeline_uuid] = {}
+        return self.stream_message_indexes[pipeline_uuid]
+
 
 class WebSocketAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
     """WebSocket适配器 - 支持双向实时通信"""
@@ -89,20 +97,46 @@ class WebSocketAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter)
         target_id: str,
         message: platform_message.MessageChain,
     ) -> dict:
-        """发送消息 - 这里用于主动推送消息到前端"""
-        message_data = {
-            'type': 'bot_message',
-            'target_type': target_type,
-            'target_id': target_id,
-            'content': str(message),
-            'message_chain': [component.__dict__ for component in message],
-            'timestamp': datetime.now().isoformat(),
-        }
+        """发送消息 - 这里用于主动推送消息到前端
 
-        # 推送到所有相关连接
-        await self.outbound_message_queue.put(message_data)
+        对于 WebSocket 适配器，我们需要将消息广播到正确的 pipeline 连接。
+        target_id 可能是 launcher_id（如 websocket_xxx）或 pipeline_uuid。
+        我们需要尝试两种方式来确保消息能够送达。
+        """
+        # 获取当前的 pipeline_uuid
+        pipeline_uuid = self.ap.platform_mgr.websocket_proxy_bot.bot_entity.use_pipeline_uuid
+        session_type = 'group' if target_type == 'group' else 'person'
 
-        return message_data
+        # 选择会话
+        session = self.websocket_group_session if session_type == 'group' else self.websocket_person_session
+
+        # 生成唯一消息ID
+        msg_id = len(session.get_message_list(pipeline_uuid)) + 1
+
+        message_data = WebSocketMessage(
+            id=msg_id,
+            role='assistant',
+            content=str(message),
+            message_chain=[component.__dict__ for component in message],
+            timestamp=datetime.now().isoformat(),
+            is_final=True,
+        )
+
+        # 保存到历史记录
+        session.get_message_list(pipeline_uuid).append(message_data)
+
+        # 直接广播到当前pipeline的连接
+        await ws_connection_manager.broadcast_to_pipeline(
+            pipeline_uuid,
+            {
+                'type': 'response',
+                'session_type': session_type,
+                'data': message_data.model_dump(),
+            },
+            session_type=session_type,
+        )
+
+        return message_data.model_dump()
 
     async def reply_message(
         self,
@@ -169,10 +203,16 @@ class WebSocketAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter)
         pipeline_uuid = self.ap.platform_mgr.websocket_proxy_bot.bot_entity.use_pipeline_uuid
         session_type = 'group' if isinstance(message_source, platform_events.GroupMessage) else 'person'
         message_list = session.get_message_list(pipeline_uuid)
+        stream_message_indexes = session.get_stream_message_indexes(pipeline_uuid)
 
-        # 检查是否是新的流式消息（通过bot_message对象判断）
-        # 如果列表为空，或者最后一条消息已经is_final=True，则创建新消息
-        if not message_list or message_list[-1].is_final:
+        # Streaming messages in LangBot have a stable resp_message_id during the same assistant reply.
+        # Use it as the primary key to avoid overwriting an old card from a previous reply.
+        resp_message_id = str(getattr(bot_message, 'resp_message_id', '') or '')
+        existing_index = stream_message_indexes.get(resp_message_id) if resp_message_id else None
+
+        message_is_final = is_final and bot_message.tool_calls is None
+
+        if existing_index is None or existing_index >= len(message_list):
             # 创建新消息
             msg_id = len(message_list) + 1
             message_data = WebSocketMessage(
@@ -181,27 +221,31 @@ class WebSocketAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter)
                 content=str(message),
                 message_chain=[component.__dict__ for component in message],
                 timestamp=datetime.now().isoformat(),
-                is_final=is_final and bot_message.tool_calls is None,
+                is_final=message_is_final,
             )
 
-            # 只有在is_final时才保存到历史记录
-            if is_final and bot_message.tool_calls is None:
-                message_list.append(message_data)
+            # 立即添加到历史记录（即使is_final=False），以便后续块可以更新它
+            message_list.append(message_data)
+            if resp_message_id:
+                stream_message_indexes[resp_message_id] = len(message_list) - 1
         else:
-            # 更新最后一条消息
-            msg_id = message_list[-1].id
+            # 更新同一条流式消息
+            old_message = message_list[existing_index]
+            msg_id = old_message.id
             message_data = WebSocketMessage(
                 id=msg_id,
                 role='assistant',
                 content=str(message),
                 message_chain=[component.__dict__ for component in message],
-                timestamp=message_list[-1].timestamp,  # 保持原始时间戳
-                is_final=is_final and bot_message.tool_calls is None,
+                timestamp=old_message.timestamp,  # 保持原始时间戳
+                is_final=message_is_final,
             )
 
-            # 如果是final，更新历史记录中的最后一条
-            if is_final and bot_message.tool_calls is None:
-                message_list[-1] = message_data
+            # 更新历史记录中的对应消息
+            message_list[existing_index] = message_data
+
+        if message_is_final and resp_message_id:
+            stream_message_indexes.pop(resp_message_id, None)
 
         # 直接广播到所有该pipeline的连接，包含session_type信息
         await ws_connection_manager.broadcast_to_pipeline(
@@ -410,6 +454,10 @@ class WebSocketAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter)
         if session_type == 'person':
             if pipeline_uuid in self.websocket_person_session.message_lists:
                 self.websocket_person_session.message_lists[pipeline_uuid] = []
+            if pipeline_uuid in self.websocket_person_session.stream_message_indexes:
+                self.websocket_person_session.stream_message_indexes[pipeline_uuid] = {}
         else:
             if pipeline_uuid in self.websocket_group_session.message_lists:
                 self.websocket_group_session.message_lists[pipeline_uuid] = []
+            if pipeline_uuid in self.websocket_group_session.stream_message_indexes:
+                self.websocket_group_session.stream_message_indexes[pipeline_uuid] = {}

src/langbot/pkg/platform/sources/wecom.py

@@ -148,51 +148,54 @@ class WecomEventConverter(abstract_platform_adapter.AbstractEventConverter):
             pass
 
         if type(event) is platform_events.FriendMessage:
-            payload = {
-                'MsgType': 'text',
-                'Content': '',
-                'FromUserName': event.sender.id,
-                'ToUserName': bot_account_id,
-                'CreateTime': int(datetime.datetime.now().timestamp()),
-                'AgentID': event.sender.nickname,
-            }
-            wecom_event = WecomEvent.from_payload(payload=payload)
-            if not wecom_event:
-                raise ValueError('无法从 message_data 构造 WecomEvent 对象')
-
-            return wecom_event
+            return event.source_platform_object
 
     @staticmethod
-    async def target2yiri(event: WecomEvent):
+    async def target2yiri(event: WecomEvent, bot: WecomClient = None):
         """
         将 WecomEvent 转换为平台的 FriendMessage 对象。
 
         Args:
             event (WecomEvent): 企业微信事件。
+            bot (WecomClient): 企业微信客户端，用于获取用户信息。
 
         Returns:
             platform_events.FriendMessage: 转换后的 FriendMessage 对象。
         """
+        # Try to get the user's real name from the WeCom API
+        nickname = str(event.user_id)
+        if bot and event.user_id:
+            try:
+                user_info = await bot.get_user_info(event.user_id)
+                if user_info and user_info.get('name'):
+                    nickname = user_info.get('name')
+            except Exception:
+                pass  # Fall back to user_id as nickname
+
         # 转换消息链
         if event.type == 'text':
             yiri_chain = await WecomMessageConverter.target2yiri(event.message, event.message_id)
             friend = platform_entities.Friend(
                 id=f'u{event.user_id}',
-                nickname=str(event.agent_id),
+                nickname=nickname,
                 remark='',
             )
 
-            return platform_events.FriendMessage(sender=friend, message_chain=yiri_chain, time=event.timestamp)
+            return platform_events.FriendMessage(
+                sender=friend, message_chain=yiri_chain, time=event.timestamp, source_platform_object=event
+            )
         elif event.type == 'image':
             friend = platform_entities.Friend(
                 id=f'u{event.user_id}',
-                nickname=str(event.agent_id),
+                nickname=nickname,
                 remark='',
             )
 
             yiri_chain = await WecomMessageConverter.target2yiri_image(picurl=event.picurl, message_id=event.message_id)
 
-            return platform_events.FriendMessage(sender=friend, message_chain=yiri_chain, time=event.timestamp)
+            return platform_events.FriendMessage(
+                sender=friend, message_chain=yiri_chain, time=event.timestamp, source_platform_object=event
+            )
 
 
 class WecomAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
@@ -210,7 +213,6 @@ class WecomAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
             'secret',
             'token',
             'EncodingAESKey',
-            'contacts_secret',
         ]
 
         missing_keys = [key for key in required_keys if key not in config]
@@ -223,7 +225,7 @@ class WecomAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
             secret=config['secret'],
             token=config['token'],
             EncodingAESKey=config['EncodingAESKey'],
-            contacts_secret=config['contacts_secret'],
+            contacts_secret=config.get('contacts_secret', ''),  # Optional, kept for backward compatibility
             logger=logger,
             unified_mode=True,
             api_base_url=config.get('api_base_url', 'https://qyapi.weixin.qq.com/cgi-bin'),
@@ -248,18 +250,17 @@ class WecomAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
     ):
         Wecom_event = await WecomEventConverter.yiri2target(message_source, self.bot_account_id, self.bot)
         content_list = await WecomMessageConverter.yiri2target(message, self.bot)
-        fixed_user_id = Wecom_event.user_id
-        # 删掉开头的u
-        fixed_user_id = fixed_user_id[1:]
+        # user_id is the original FromUserName from WecomEvent
+        user_id = Wecom_event.user_id
         for content in content_list:
             if content['type'] == 'text':
-                await self.bot.send_private_msg(fixed_user_id, Wecom_event.agent_id, content['content'])
+                await self.bot.send_private_msg(user_id, Wecom_event.agent_id, content['content'])
             elif content['type'] == 'image':
-                await self.bot.send_image(fixed_user_id, Wecom_event.agent_id, content['media_id'])
+                await self.bot.send_image(user_id, Wecom_event.agent_id, content['media_id'])
             elif content['type'] == 'voice':
-                await self.bot.send_voice(fixed_user_id, Wecom_event.agent_id, content['media_id'])
+                await self.bot.send_voice(user_id, Wecom_event.agent_id, content['media_id'])
             elif content['type'] == 'file':
-                await self.bot.send_file(fixed_user_id, Wecom_event.agent_id, content['media_id'])
+                await self.bot.send_file(user_id, Wecom_event.agent_id, content['media_id'])
 
     async def send_message(self, target_type: str, target_id: str, message: platform_message.MessageChain):
         content_list = await WecomMessageConverter.yiri2target(message, self.bot)
@@ -287,7 +288,7 @@ class WecomAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
         async def on_message(event: WecomEvent):
             self.bot_account_id = event.receiver_id
             try:
-                return await callback(await self.event_converter.target2yiri(event), self)
+                return await callback(await self.event_converter.target2yiri(event, self.bot), self)
             except Exception:
                 await self.logger.error(f'Error in wecom callback: {traceback.format_exc()}')
 

src/langbot/pkg/platform/sources/wecom.yaml

@@ -39,13 +39,6 @@ spec:
       type: string
       required: true
       default: ""
-    - name: contacts_secret
-      label:
-        en_US: Contacts Secret
-        zh_Hans: 通讯录密钥
-      type: string
-      required: true
-      default: ""
     - name: api_base_url
       label:
         en_US: API Base URL

src/langbot/pkg/platform/sources/wecomcs.py

@@ -81,22 +81,33 @@ class WecomEventConverter(abstract_platform_adapter.AbstractEventConverter):
             return event.source_platform_object
 
     @staticmethod
-    async def target2yiri(event: WecomCSEvent):
+    async def target2yiri(event: WecomCSEvent, bot: WecomCSClient = None):
         """
         将 WecomEvent 转换为平台的 FriendMessage 对象。
 
         Args:
             event (WecomEvent): 企业微信客服事件。
+            bot (WecomCSClient): 企业微信客服客户端，用于获取用户信息。
 
         Returns:
             platform_events.FriendMessage: 转换后的 FriendMessage 对象。
         """
+        # Try to get customer nickname from WeChat API
+        nickname = str(event.user_id)
+        if bot and event.user_id:
+            try:
+                customer_info = await bot.get_customer_info(event.user_id)
+                if customer_info and customer_info.get('nickname'):
+                    nickname = customer_info.get('nickname')
+            except Exception:
+                pass  # Fall back to user_id as nickname
+
         # 转换消息链
         if event.type == 'text':
             yiri_chain = await WecomMessageConverter.target2yiri(event.message, event.message_id)
             friend = platform_entities.Friend(
                 id=f'u{event.user_id}',
-                nickname=str(event.user_id),
+                nickname=nickname,
                 remark='',
             )
 
@@ -106,7 +117,7 @@ class WecomEventConverter(abstract_platform_adapter.AbstractEventConverter):
         elif event.type == 'image':
             friend = platform_entities.Friend(
                 id=f'u{event.user_id}',
-                nickname=str(event.user_id),
+                nickname=nickname,
                 remark='',
             )
 
@@ -187,7 +198,7 @@ class WecomCSAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
         async def on_message(event: WecomCSEvent):
             self.bot_account_id = event.receiver_id
             try:
-                return await callback(await self.event_converter.target2yiri(event), self)
+                return await callback(await self.event_converter.target2yiri(event, self.bot), self)
             except Exception:
                 await self.logger.error(f'Error in wecomcs callback: {traceback.format_exc()}')
 

src/langbot/pkg/plugin/connector.py

@@ -7,7 +7,6 @@ import typing
 import os
 import sys
 import httpx
-import traceback
 import sqlalchemy
 from async_lru import alru_cache
 from langbot_plugin.api.entities.builtin.pipeline.query import provider_session
@@ -102,12 +101,6 @@ class PluginRuntimeConnector:
             self.handler_task = asyncio.create_task(self.handler.run())
             _ = await self.handler.ping()
             self.ap.logger.info('Connected to plugin runtime.')
-            # Sync polymorphic component instances after connection
-            try:
-                await self.sync_polymorphic_component_instances()
-            except Exception as e:
-                traceback.print_exc()
-                self.ap.logger.error(f'Failed to sync polymorphic component instances: {e}')
             await self.handler_task
 
         task: asyncio.Task | None = None
@@ -463,30 +456,18 @@ class PluginRuntimeConnector:
 
             yield cmd_ret
 
-    # KnowledgeRetriever methods
-    async def list_knowledge_retrievers(self, bound_plugins: list[str] | None = None) -> list[dict[str, Any]]:
-        """List all available KnowledgeRetriever components."""
-        if not self.is_enable_plugin:
-            return []
-
-        retrievers_data = await self.handler.list_knowledge_retrievers(include_plugins=bound_plugins)
-        return retrievers_data
-
     async def retrieve_knowledge(
         self,
         plugin_author: str,
         plugin_name: str,
         retriever_name: str,
-        instance_id: str,
         retrieval_context: dict[str, Any],
-    ) -> list[dict[str, Any]]:
-        """Retrieve knowledge using a KnowledgeRetriever instance."""
+    ) -> dict[str, Any]:
+        """Retrieve knowledge using a KnowledgeEngine instance."""
         if not self.is_enable_plugin:
-            return []
+            return {'results': []}
 
-        return await self.handler.retrieve_knowledge(
-            plugin_author, plugin_name, retriever_name, instance_id, retrieval_context
-        )
+        return await self.handler.retrieve_knowledge(plugin_author, plugin_name, retriever_name, retrieval_context)
 
     def dispose(self):
         # No need to consider the shutdown on Windows
@@ -500,41 +481,84 @@ class PluginRuntimeConnector:
             self.heartbeat_task.cancel()
             self.heartbeat_task = None
 
-    async def sync_polymorphic_component_instances(self) -> dict[str, Any]:
-        """Sync polymorphic component instances with runtime.
+    @staticmethod
+    def _parse_plugin_id(plugin_id: str) -> tuple[str, str]:
+        """Parse a plugin ID string into (author, name).
 
-        This collects all external knowledge bases from database and sends to runtime
-        to ensure instance integrity across restarts.
+        Args:
+            plugin_id: Plugin ID in 'author/name' format.
+
+        Returns:
+            Tuple of (plugin_author, plugin_name).
+
+        Raises:
+            ValueError: If plugin_id is not in the expected 'author/name' format.
+        """
+        if '/' not in plugin_id:
+            raise ValueError(
+                f"Invalid plugin_id format: '{plugin_id}'. Expected 'author/name' format (e.g. 'langbot/rag-engine')."
+            )
+        return plugin_id.split('/', 1)
+
+    async def call_rag_ingest(self, plugin_id: str, context_data: dict[str, Any]) -> dict[str, Any]:
+        """Call plugin to ingest document.
+
+        Args:
+            plugin_id: Target plugin ID (author/name).
+            context_data: IngestionContext data.
+        """
+        plugin_author, plugin_name = self._parse_plugin_id(plugin_id)
+        return await self.handler.rag_ingest_document(plugin_author, plugin_name, context_data)
+
+    async def call_rag_delete_document(self, plugin_id: str, document_id: str, kb_id: str) -> bool:
+        plugin_author, plugin_name = self._parse_plugin_id(plugin_id)
+        return await self.handler.rag_delete_document(plugin_author, plugin_name, document_id, kb_id)
+
+    async def get_rag_creation_schema(self, plugin_id: str) -> dict[str, Any]:
+        plugin_author, plugin_name = self._parse_plugin_id(plugin_id)
+        return await self.handler.get_rag_creation_schema(plugin_author, plugin_name)
+
+    async def get_rag_retrieval_schema(self, plugin_id: str) -> dict[str, Any]:
+        plugin_author, plugin_name = self._parse_plugin_id(plugin_id)
+        return await self.handler.get_rag_retrieval_schema(plugin_author, plugin_name)
+
+    async def rag_on_kb_create(self, plugin_id: str, kb_id: str, config: dict[str, Any]) -> dict[str, Any]:
+        """Notify plugin about KB creation."""
+        plugin_author, plugin_name = self._parse_plugin_id(plugin_id)
+        return await self.handler.rag_on_kb_create(plugin_author, plugin_name, kb_id, config)
+
+    async def rag_on_kb_delete(self, plugin_id: str, kb_id: str) -> dict[str, Any]:
+        """Notify plugin about KB deletion."""
+        plugin_author, plugin_name = self._parse_plugin_id(plugin_id)
+        return await self.handler.rag_on_kb_delete(plugin_author, plugin_name, kb_id)
+
+    async def call_rag_retrieve(self, plugin_id: str, retrieval_context: dict[str, Any]) -> dict[str, Any]:
+        """Call plugin to retrieve knowledge.
+
+        Args:
+            plugin_id: Target plugin ID (author/name).
+            retrieval_context: RetrievalContext data.
+        """
+        plugin_author, plugin_name = self._parse_plugin_id(plugin_id)
+        return await self.handler.retrieve_knowledge(plugin_author, plugin_name, '', retrieval_context)
+
+    async def list_knowledge_engines(self) -> list[dict[str, Any]]:
+        """List all available Knowledge Engines from plugins.
+
+        Returns a list of Knowledge Engines with their capabilities and configuration schemas.
         """
         if not self.is_enable_plugin:
-            return {}
+            return []
 
-        # ===== external knowledge bases =====
+        return await self.handler.list_knowledge_engines()
 
-        external_kbs = await self.ap.external_kb_service.get_external_knowledge_bases()
+    async def list_parsers(self) -> list[dict[str, Any]]:
+        """List all available parsers from plugins."""
+        if not self.is_enable_plugin:
+            return []
+        return await self.handler.list_parsers()
 
-        # Build required_instances list
-        required_instances = []
-        for kb in external_kbs:
-            required_instances.append(
-                {
-                    'instance_id': kb['uuid'],
-                    'plugin_author': kb['plugin_author'],
-                    'plugin_name': kb['plugin_name'],
-                    'component_kind': 'KnowledgeRetriever',
-                    'component_name': kb['retriever_name'],
-                    'config': kb['retriever_config'],
-                }
-            )
-
-        self.ap.logger.info(f'Syncing {len(required_instances)} polymorphic component instances to runtime')
-
-        # Send to runtime
-        sync_result = await self.handler.sync_polymorphic_component_instances(required_instances)
-
-        self.ap.logger.info(
-            f'Sync complete: {len(sync_result.get("success_instances", []))} succeeded, '
-            f'{len(sync_result.get("failed_instances", []))} failed'
-        )
-
-        return sync_result
+    async def call_parser(self, plugin_id: str, context_data: dict[str, Any], file_bytes: bytes) -> dict[str, Any]:
+        """Call plugin to parse a document."""
+        plugin_author, plugin_name = self._parse_plugin_id(plugin_id)
+        return await self.handler.parse_document(plugin_author, plugin_name, context_data, file_bytes)

src/langbot/pkg/plugin/handler.py

@@ -26,6 +26,20 @@ from ..core import app
 from ..utils import constants
 
 
+def _make_rag_error_response(error: Exception, error_type: str, **extra_context) -> handler.ActionResponse:
+    """Create a clean error response for RAG operations.
+
+    Args:
+        error: The caught exception.
+        error_type: A category string like 'EmbeddingError', 'VectorStoreError'.
+        **extra_context: Additional context fields for the error message.
+    """
+    context_parts = [f'{k}={v}' for k, v in extra_context.items()]
+    context_str = f' [{", ".join(context_parts)}]' if context_parts else ''
+    message = f'[{error_type}/{type(error).__name__}]{context_str} {str(error)}'
+    return handler.ActionResponse.error(message=message)
+
+
 class RuntimeConnectionHandler(handler.Handler):
     """Runtime connection handler"""
 
@@ -323,7 +337,14 @@ class RuntimeConnectionHandler(handler.Handler):
                 )
 
             messages_obj = [provider_message.Message.model_validate(message) for message in messages]
-            funcs_obj = [resource_tool.LLMTool.model_validate(func) for func in funcs]
+
+            # The func field is excluded during model_dump() in plugin side (marked as exclude=True),
+            # but it's a required field for LLMTool validation. We need to provide a placeholder
+            # function when reconstructing the LLMTool objects from serialized data.
+            async def _placeholder_func(**kwargs):
+                pass
+
+            funcs_obj = [resource_tool.LLMTool.model_validate({**func, 'func': _placeholder_func}) for func in funcs]
 
             result = await llm_model.provider.invoke_llm(
                 query=None,
@@ -439,7 +460,7 @@ class RuntimeConnectionHandler(handler.Handler):
                 },
             )
 
-        @self.action(RuntimeToLangBotAction.GET_CONFIG_FILE)
+        @self.action(PluginToRuntimeAction.GET_CONFIG_FILE)
         async def get_config_file(data: dict[str, Any]) -> handler.ActionResponse:
             """Get a config file by file key"""
             file_key = data['file_key']
@@ -458,6 +479,125 @@ class RuntimeConnectionHandler(handler.Handler):
                     message=f'Failed to load config file {file_key}: {e}',
                 )
 
+        # ================= RAG Capability Handlers =================
+
+        @self.action(PluginToRuntimeAction.INVOKE_EMBEDDING)
+        async def invoke_embedding(data: dict[str, Any]) -> handler.ActionResponse:
+            embedding_model_uuid = data['embedding_model_uuid']
+            texts = data['texts']
+
+            embedding_model = await self.ap.model_mgr.get_embedding_model_by_uuid(embedding_model_uuid)
+            if embedding_model is None:
+                return handler.ActionResponse.error(
+                    message=f'Embedding model with embedding_model_uuid {embedding_model_uuid} not found',
+                )
+
+            try:
+                vectors = await embedding_model.provider.invoke_embedding(embedding_model, texts)
+                return handler.ActionResponse.success(data={'vectors': vectors})
+            except Exception as e:
+                return _make_rag_error_response(e, 'EmbeddingError', embedding_model_uuid=embedding_model_uuid)
+
+        @self.action(PluginToRuntimeAction.VECTOR_UPSERT)
+        async def vector_upsert(data: dict[str, Any]) -> handler.ActionResponse:
+            collection_id = data['collection_id']
+            vectors = data['vectors']
+            ids = data['ids']
+            metadata = data.get('metadata')
+            documents = data.get('documents')
+            if len(vectors) != len(ids):
+                return handler.ActionResponse.error(message='vectors and ids must have same length')
+            if metadata and len(metadata) != len(vectors):
+                return handler.ActionResponse.error(message='metadata must match vectors length')
+            if documents and len(documents) != len(vectors):
+                return handler.ActionResponse.error(message='documents must match vectors length')
+            try:
+                await self.ap.rag_runtime_service.vector_upsert(
+                    collection_id,
+                    vectors,
+                    ids,
+                    metadata,
+                    documents,
+                )
+                return handler.ActionResponse.success(data={})
+            except Exception as e:
+                return _make_rag_error_response(e, 'VectorStoreError', collection_id=collection_id)
+
+        @self.action(PluginToRuntimeAction.VECTOR_SEARCH)
+        async def vector_search(data: dict[str, Any]) -> handler.ActionResponse:
+            collection_id = data['collection_id']
+            query_vector = data['query_vector']
+            top_k = data['top_k']
+            filters = data.get('filters')
+            search_type = data.get('search_type', 'vector')
+            query_text = data.get('query_text', '')
+            try:
+                results = await self.ap.rag_runtime_service.vector_search(
+                    collection_id,
+                    query_vector,
+                    top_k,
+                    filters,
+                    search_type,
+                    query_text,
+                )
+                return handler.ActionResponse.success(data={'results': results})
+            except Exception as e:
+                return _make_rag_error_response(e, 'VectorStoreError', collection_id=collection_id)
+
+        @self.action(PluginToRuntimeAction.VECTOR_DELETE)
+        async def vector_delete(data: dict[str, Any]) -> handler.ActionResponse:
+            collection_id = data['collection_id']
+            file_ids = data.get('file_ids')
+            filters = data.get('filters')
+            try:
+                count = await self.ap.rag_runtime_service.vector_delete(collection_id, file_ids, filters)
+                return handler.ActionResponse.success(data={'count': count})
+            except Exception as e:
+                return _make_rag_error_response(e, 'VectorStoreError', collection_id=collection_id)
+
+        @self.action(PluginToRuntimeAction.GET_KNOWLEDEGE_FILE_STREAM)
+        async def get_knowledge_file_stream(data: dict[str, Any]) -> handler.ActionResponse:
+            storage_path = data['storage_path']
+            try:
+                content_bytes = await self.ap.rag_runtime_service.get_file_stream(storage_path)
+                file_key = await self.send_file(content_bytes, '')
+                return handler.ActionResponse.success(data={'file_key': file_key})
+            except Exception as e:
+                return _make_rag_error_response(e, 'FileServiceError', storage_path=storage_path)
+
+        @self.action(PluginToRuntimeAction.INVOKE_PARSER)
+        async def invoke_parser(data: dict[str, Any]) -> handler.ActionResponse:
+            """Plugin requests host to invoke a parser plugin."""
+            plugin_author = data['plugin_author']
+            plugin_name = data['plugin_name']
+            storage_path = data['storage_path']
+            mime_type = data.get('mime_type', 'application/octet-stream')
+            filename = data.get('filename', '')
+            metadata = data.get('metadata', {})
+            try:
+                # Read file from storage
+                file_bytes = await self.ap.rag_runtime_service.get_file_stream(storage_path)
+                context_data = {
+                    'mime_type': mime_type,
+                    'filename': filename,
+                    'metadata': metadata,
+                }
+                result = await self.ap.plugin_connector.call_parser(
+                    f'{plugin_author}/{plugin_name}', context_data, file_bytes
+                )
+                return handler.ActionResponse.success(data=result)
+            except Exception as e:
+                return _make_rag_error_response(e, 'ParserError')
+
+        @self.action(CommonAction.PING)
+        async def ping(data: dict[str, Any]) -> handler.ActionResponse:
+            """Ping"""
+            return handler.ActionResponse.success(
+                data={
+                    'pong': 'pong',
+                },
+            )
+
     async def ping(self) -> dict[str, Any]:
         """Ping the runtime"""
         return await self.call_action(
@@ -717,26 +857,13 @@ class RuntimeConnectionHandler(handler.Handler):
         async for ret in gen:
             yield ret
 
-    # KnowledgeRetriever methods
-    async def list_knowledge_retrievers(self, include_plugins: list[str] | None = None) -> list[dict[str, Any]]:
-        """List knowledge retrievers"""
-        result = await self.call_action(
-            LangBotToRuntimeAction.LIST_KNOWLEDGE_RETRIEVERS,
-            {
-                'include_plugins': include_plugins,
-            },
-            timeout=10,
-        )
-        return result['retrievers']
-
     async def retrieve_knowledge(
         self,
         plugin_author: str,
         plugin_name: str,
         retriever_name: str,
-        instance_id: str,
         retrieval_context: dict[str, Any],
-    ) -> list[dict[str, Any]]:
+    ) -> dict[str, Any]:
         """Retrieve knowledge"""
         result = await self.call_action(
             LangBotToRuntimeAction.RETRIEVE_KNOWLEDGE,
@@ -744,22 +871,10 @@ class RuntimeConnectionHandler(handler.Handler):
                 'plugin_author': plugin_author,
                 'plugin_name': plugin_name,
                 'retriever_name': retriever_name,
-                'instance_id': instance_id,
                 'retrieval_context': retrieval_context,
             },
             timeout=30,
         )
-        return result['retrieval_results']
-
-    async def sync_polymorphic_component_instances(self, required_instances: list[dict[str, Any]]) -> dict[str, Any]:
-        """Sync polymorphic component instances with runtime"""
-        result = await self.call_action(
-            LangBotToRuntimeAction.SYNC_POLYMORPHIC_COMPONENT_INSTANCES,
-            {
-                'required_instances': required_instances,
-            },
-            timeout=30,
-        )
         return result
 
     async def get_debug_info(self) -> dict[str, Any]:
@@ -770,3 +885,91 @@ class RuntimeConnectionHandler(handler.Handler):
             timeout=10,
         )
         return result
+
+    # ================= RAG Capability Callers (LangBot -> Runtime) =================
+
+    async def rag_ingest_document(
+        self, plugin_author: str, plugin_name: str, context_data: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Send INGEST_DOCUMENT action to runtime."""
+        result = await self.call_action(
+            LangBotToRuntimeAction.RAG_INGEST_DOCUMENT,
+            {'plugin_author': plugin_author, 'plugin_name': plugin_name, 'context': context_data},
+            timeout=300,  # Ingestion can be slow
+        )
+        return result
+
+    async def rag_delete_document(self, plugin_author: str, plugin_name: str, document_id: str, kb_id: str) -> bool:
+        result = await self.call_action(
+            LangBotToRuntimeAction.RAG_DELETE_DOCUMENT,
+            {'plugin_author': plugin_author, 'plugin_name': plugin_name, 'document_id': document_id, 'kb_id': kb_id},
+            timeout=30,
+        )
+        return result.get('success', False)
+
+    async def rag_on_kb_create(
+        self, plugin_author: str, plugin_name: str, kb_id: str, config: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Notify plugin about KB creation."""
+        result = await self.call_action(
+            LangBotToRuntimeAction.RAG_ON_KB_CREATE,
+            {'plugin_author': plugin_author, 'plugin_name': plugin_name, 'kb_id': kb_id, 'config': config},
+            timeout=30,
+        )
+        return result
+
+    async def rag_on_kb_delete(self, plugin_author: str, plugin_name: str, kb_id: str) -> dict[str, Any]:
+        """Notify plugin about KB deletion."""
+        result = await self.call_action(
+            LangBotToRuntimeAction.RAG_ON_KB_DELETE,
+            {'plugin_author': plugin_author, 'plugin_name': plugin_name, 'kb_id': kb_id},
+            timeout=30,
+        )
+        return result
+
+    async def get_rag_creation_schema(self, plugin_author: str, plugin_name: str) -> dict[str, Any]:
+        return await self.call_action(
+            LangBotToRuntimeAction.GET_RAG_CREATION_SETTINGS_SCHEMA,
+            {'plugin_author': plugin_author, 'plugin_name': plugin_name},
+            timeout=10,
+        )
+
+    async def get_rag_retrieval_schema(self, plugin_author: str, plugin_name: str) -> dict[str, Any]:
+        return await self.call_action(
+            LangBotToRuntimeAction.GET_RAG_RETRIEVAL_SETTINGS_SCHEMA,
+            {'plugin_author': plugin_author, 'plugin_name': plugin_name},
+            timeout=10,
+        )
+
+    async def list_knowledge_engines(self) -> list[dict[str, Any]]:
+        """List all available Knowledge Engines from plugins."""
+        result = await self.call_action(LangBotToRuntimeAction.LIST_KNOWLEDGE_ENGINES, {}, timeout=60)
+        return result.get('engines', [])
+
+    # ================= Parser Capability Callers (LangBot -> Runtime) =================
+
+    async def list_parsers(self) -> list[dict[str, Any]]:
+        """List all available parsers from plugins."""
+        result = await self.call_action(LangBotToRuntimeAction.LIST_PARSERS, {}, timeout=60)
+        return result.get('parsers', [])
+
+    async def parse_document(
+        self, plugin_author: str, plugin_name: str, context_data: dict[str, Any], file_bytes: bytes
+    ) -> dict[str, Any]:
+        """Send PARSE_DOCUMENT action to runtime.
+
+        Sends file content via chunked FILE_CHUNK transfer, then invokes
+        the PARSE_DOCUMENT action with a file_key reference.
+        """
+        # Send file to runtime via chunked transfer
+        file_key = await self.send_file(file_bytes, '')
+
+        # Include file_key in context_data for the runtime to read
+        context_data['file_key'] = file_key
+
+        result = await self.call_action(
+            LangBotToRuntimeAction.PARSE_DOCUMENT,
+            {'plugin_author': plugin_author, 'plugin_name': plugin_name, 'context': context_data},
+            timeout=300,
+        )
+        return result

src/langbot/pkg/provider/runners/difysvapi.py

@@ -72,6 +72,28 @@ class DifyServiceAPIRunner(runner.RequestRunner):
                 content = f'<think>\n{thinking_content}\n</think>\n{content}'.strip()
             return content, thinking_content
 
+    def _extract_dify_text_output(self, value: typing.Any) -> str:
+        """Extract text content from Dify output payload."""
+        if value is None:
+            return ''
+        if isinstance(value, dict):
+            content = value.get('content')
+            if isinstance(content, str):
+                return content
+            return json.dumps(value, ensure_ascii=False)
+        if isinstance(value, str):
+            text = value.strip()
+            if not text:
+                return ''
+            try:
+                parsed = json.loads(text)
+            except json.JSONDecodeError:
+                return value
+            if isinstance(parsed, dict) and isinstance(parsed.get('content'), str):
+                return parsed['content']
+            return value
+        return str(value)
+
     async def _preprocess_user_message(self, query: pipeline_query.Query) -> tuple[str, list[dict]]:
         """预处理用户消息，提取纯文本，并将图片/文件上传到 Dify 服务
 
@@ -192,7 +214,8 @@ class DifyServiceAPIRunner(runner.RequestRunner):
             if mode == 'workflow':
                 if chunk['event'] == 'node_finished':
                     if chunk['data']['node_type'] == 'answer':
-                        content, _ = self._process_thinking_content(chunk['data']['outputs']['answer'])
+                        answer = self._extract_dify_text_output(chunk['data']['outputs'].get('answer'))
+                        content, _ = self._process_thinking_content(answer)
 
                         yield provider_message.Message(
                             role='assistant',
@@ -405,6 +428,7 @@ class DifyServiceAPIRunner(runner.RequestRunner):
             for f in upload_files
         ]
 
+        mode = 'basic'
         basic_mode_pending_chunk = ''
 
         inputs = {}
@@ -417,6 +441,7 @@ class DifyServiceAPIRunner(runner.RequestRunner):
         is_final = False
         think_start = False
         think_end = False
+        yielded_final = False
 
         remove_think = self.pipeline_config['output'].get('misc', '').get('remove-think')
 
@@ -430,11 +455,12 @@ class DifyServiceAPIRunner(runner.RequestRunner):
         ):
             self.ap.logger.debug('dify-chat-chunk: ' + str(chunk))
 
-            # if chunk['event'] == 'workflow_started':
-            #     mode = 'workflow'
-            # if mode == 'workflow':
-            # elif mode == 'basic':
-            # 因为都只是返回的 message也没有工具调用什么的，暂时不分类
+            if chunk['event'] == 'workflow_started':
+                mode = 'workflow'
+            elif chunk['event'] in ('node_started', 'node_finished', 'workflow_finished'):
+                # Some Dify deployments may omit workflow_started in streamed chunks.
+                mode = 'workflow'
+
             if chunk['event'] == 'message':
                 message_idx += 1
                 if remove_think:
@@ -457,14 +483,30 @@ class DifyServiceAPIRunner(runner.RequestRunner):
 
             if chunk['event'] == 'message_end':
                 is_final = True
+            elif chunk['event'] == 'workflow_finished':
+                is_final = True
+                if chunk['data'].get('error'):
+                    raise errors.DifyAPIError(chunk['data']['error'])
 
-            if is_final or message_idx % 8 == 0:
+            if mode == 'workflow' and chunk['event'] == 'node_finished':
+                if chunk['data'].get('node_type') == 'answer':
+                    answer = self._extract_dify_text_output(chunk['data'].get('outputs', {}).get('answer'))
+                    if answer:
+                        basic_mode_pending_chunk = answer
+
+            if (
+                not yielded_final
+                and (is_final or message_idx % 8 == 0)
+                and (basic_mode_pending_chunk != '' or is_final)
+            ):
                 # content, _ = self._process_thinking_content(basic_mode_pending_chunk)
                 yield provider_message.MessageChunk(
                     role='assistant',
                     content=basic_mode_pending_chunk,
                     is_final=is_final,
                 )
+                if is_final:
+                    yielded_final = True
 
         if chunk is None:
             raise errors.DifyAPIError('Dify API 没有返回任何响应，请检查网络连接和API配置')

src/langbot/pkg/provider/runners/localagent.py

@@ -74,15 +74,13 @@ class LocalAgentRunner(runner.RequestRunner):
                     self.ap.logger.warning(f'Knowledge base {kb_uuid} not found, skipping')
                     continue
 
-                # Get top_k based on KB type
-                if kb.get_type() == 'internal':
-                    top_k = kb.knowledge_base_entity.top_k
-                elif kb.get_type() == 'external':
-                    top_k = 5  # external kb's top_k is managed by plugin config
-                else:
-                    top_k = 5  # default fallback
-
-                result = await kb.retrieve(user_message_text, top_k)
+                result = await kb.retrieve(
+                    user_message_text,
+                    settings={
+                        'sender_id': str(query.sender_id),
+                        'session_name': f'{query.session.launcher_type.value}_{query.session.launcher_id}',
+                    },
+                )
 
                 if result:
                     all_results.extend(result)
@@ -97,9 +95,9 @@ class LocalAgentRunner(runner.RequestRunner):
                         if content.type == 'text' and content.text is not None:
                             texts.append(f'[{idx}] {content.text}')
                             idx += 1
-                rag_context = '\n\n'.join(texts)
+                rag_context_text = '\n\n'.join(texts)
                 final_user_message_text = rag_combined_prompt_template.format(
-                    rag_context=rag_context, user_message=user_message_text
+                    rag_context=rag_context_text, user_message=user_message_text
                 )
 
             else:

src/langbot/pkg/rag/knowledge/base.py

@@ -22,12 +22,12 @@ class KnowledgeBaseInterface(metaclass=abc.ABCMeta):
         pass
 
     @abc.abstractmethod
-    async def retrieve(self, query: str, top_k: int) -> list[rag_context.RetrievalResultEntry]:
+    async def retrieve(self, query: str, settings: dict | None = None) -> list[rag_context.RetrievalResultEntry]:
         """Retrieve relevant documents from the knowledge base
 
         Args:
             query: The query string
-            top_k: Number of top results to return
+            settings: Optional per-request retrieval settings overrides
 
         Returns:
             List of retrieve result entries
@@ -45,8 +45,8 @@ class KnowledgeBaseInterface(metaclass=abc.ABCMeta):
         pass
 
     @abc.abstractmethod
-    def get_type(self) -> str:
-        """Get the type of knowledge base (internal/external)"""
+    def get_knowledge_engine_plugin_id(self) -> str:
+        """Get the Knowledge Engine plugin ID"""
         pass
 
     @abc.abstractmethod

src/langbot/pkg/rag/knowledge/external.py

@@ -1,85 +0,0 @@
-"""External knowledge base implementation"""
-
-from __future__ import annotations
-
-from langbot.pkg.core import app
-from langbot.pkg.entity.persistence import rag as persistence_rag
-from langbot_plugin.api.entities.builtin.rag import context as rag_context
-from .base import KnowledgeBaseInterface
-
-
-class ExternalKnowledgeBase(KnowledgeBaseInterface):
-    """External knowledge base that queries via HTTP API or plugin retriever"""
-
-    external_kb_entity: persistence_rag.ExternalKnowledgeBase
-
-    # Plugin retriever instance ID
-    retriever_instance_id: str | None
-
-    def __init__(self, ap: app.Application, external_kb_entity: persistence_rag.ExternalKnowledgeBase):
-        super().__init__(ap)
-        self.external_kb_entity = external_kb_entity
-        self.retriever_instance_id = None
-
-    async def initialize(self):
-        """Initialize the external knowledge base"""
-        # Use KB UUID as instance ID
-        # Instance creation is now handled by the unified sync mechanism
-        # when LangBot connects to runtime
-        self.retriever_instance_id = self.external_kb_entity.uuid
-
-        self.ap.logger.info(
-            f'Initialized external KB {self.external_kb_entity.uuid}, instance will be created by sync mechanism'
-        )
-
-    async def retrieve(self, query: str, top_k: int = 5) -> list[rag_context.RetrievalResultEntry]:
-        """Retrieve documents from external knowledge base via plugin retriever"""
-        if not self.retriever_instance_id:
-            self.ap.logger.error(f'No retriever instance for KB {self.external_kb_entity.uuid}')
-            return []
-
-        try:
-            results = await self.ap.plugin_connector.retrieve_knowledge(
-                self.external_kb_entity.plugin_author,
-                self.external_kb_entity.plugin_name,
-                self.external_kb_entity.retriever_name,
-                self.retriever_instance_id,
-                {'query': query},
-            )
-
-            # Convert plugin results to RetrievalResultEntry
-            retrieval_entries = []
-            for result in results:
-                retrieval_entries.append(rag_context.RetrievalResultEntry(**result))
-
-            return retrieval_entries
-        except Exception as e:
-            self.ap.logger.error(f'Plugin retriever error: {e}')
-            import traceback
-
-            traceback.print_exc()
-            return []
-
-    def get_uuid(self) -> str:
-        """Get the UUID of the external knowledge base"""
-        return self.external_kb_entity.uuid
-
-    def get_name(self) -> str:
-        """Get the name of the external knowledge base"""
-        return self.external_kb_entity.name
-
-    def get_type(self) -> str:
-        """Get the type of knowledge base"""
-        return 'external'
-
-    async def dispose(self):
-        """Clean up resources"""
-        # Trigger sync to immediately delete the instance from plugin process
-        # This ensures instance is cleaned up without waiting for next LangBot restart
-        try:
-            await self.ap.plugin_connector.sync_polymorphic_component_instances()
-            self.ap.logger.info(
-                f'Disposed external KB {self.external_kb_entity.uuid}, triggered sync to delete instance'
-            )
-        except Exception as e:
-            self.ap.logger.error(f'Failed to sync after disposing KB: {e}')

src/langbot/pkg/rag/knowledge/kbmgr.py

@@ -1,18 +1,19 @@
 from __future__ import annotations
+import mimetypes
+import os.path
 import traceback
 import uuid
 import zipfile
 import io
-from .services import parser, chunker
+from typing import Any
 from langbot.pkg.core import app
-from langbot.pkg.rag.knowledge.services.embedder import Embedder
-from langbot.pkg.rag.knowledge.services.retriever import Retriever
 import sqlalchemy
+
+
 from langbot.pkg.entity.persistence import rag as persistence_rag
 from langbot.pkg.core import taskmgr
 from langbot_plugin.api.entities.builtin.rag import context as rag_context
 from .base import KnowledgeBaseInterface
-from .external import ExternalKnowledgeBase
 
 
 class RuntimeKnowledgeBase(KnowledgeBaseInterface):
@@ -20,28 +21,16 @@ class RuntimeKnowledgeBase(KnowledgeBaseInterface):
 
     knowledge_base_entity: persistence_rag.KnowledgeBase
 
-    parser: parser.FileParser
-
-    chunker: chunker.Chunker
-
-    embedder: Embedder
-
-    retriever: Retriever
-
     def __init__(self, ap: app.Application, knowledge_base_entity: persistence_rag.KnowledgeBase):
         super().__init__(ap)
         self.knowledge_base_entity = knowledge_base_entity
-        self.parser = parser.FileParser(ap=self.ap)
-        self.chunker = chunker.Chunker(ap=self.ap)
-        self.embedder = Embedder(ap=self.ap)
-        self.retriever = Retriever(ap=self.ap)
-        # 传递kb_id给retriever
-        self.retriever.kb_id = knowledge_base_entity.uuid
 
     async def initialize(self):
         pass
 
-    async def _store_file_task(self, file: persistence_rag.File, task_context: taskmgr.TaskContext):
+    async def _store_file_task(
+        self, file: persistence_rag.File, task_context: taskmgr.TaskContext, parser_plugin_id: str | None = None
+    ):
         try:
             # set file status to processing
             await self.ap.persistence_mgr.execute_async(
@@ -50,31 +39,46 @@ class RuntimeKnowledgeBase(KnowledgeBaseInterface):
                 .values(status='processing')
             )
 
-            task_context.set_current_action('Parsing file')
-            # parse file
-            text = await self.parser.parse(file.file_name, file.extension)
-            if not text:
-                raise Exception(f'No text extracted from file {file.file_name}')
+            task_context.set_current_action('Processing file')
 
-            task_context.set_current_action('Chunking file')
-            # chunk file
-            chunks_texts = await self.chunker.chunk(text)
-            if not chunks_texts:
-                raise Exception(f'No chunks extracted from file {file.file_name}')
+            # Get file size from storage
+            file_size = await self.ap.storage_mgr.storage_provider.size(file.file_name)
 
-            task_context.set_current_action('Embedding chunks')
+            # Detect MIME type from extension
+            mime_type, _ = mimetypes.guess_type(file.file_name)
+            if mime_type is None:
+                mime_type = 'application/octet-stream'
 
-            embedding_model = await self.ap.model_mgr.get_embedding_model_by_uuid(
-                self.knowledge_base_entity.embedding_model_uuid
-            )
-            # embed chunks
-            await self.embedder.embed_and_store(
-                kb_id=self.knowledge_base_entity.uuid,
-                file_id=file.uuid,
-                chunks=chunks_texts,
-                embedding_model=embedding_model,
+            # If a parser plugin is specified, call it before ingestion
+            parsed_content = None
+            if parser_plugin_id:
+                task_context.set_current_action('Parsing file')
+                file_bytes = await self.ap.storage_mgr.storage_provider.load(file.file_name)
+                parse_context = {
+                    'mime_type': mime_type,
+                    'filename': file.file_name,
+                    'metadata': {},
+                }
+                parsed_content = await self.ap.plugin_connector.call_parser(parser_plugin_id, parse_context, file_bytes)
+
+            # Call plugin to ingest document
+            result = await self._ingest_document(
+                {
+                    'document_id': file.uuid,
+                    'filename': file.file_name,
+                    'extension': file.extension,
+                    'file_size': file_size,
+                    'mime_type': mime_type,
+                },
+                file.file_name,  # storage path
+                parsed_content=parsed_content,
             )
 
+            # Check plugin result status
+            if result.get('status') == 'failed':
+                error_msg = result.get('error_message', 'Plugin ingestion returned failed status')
+                raise Exception(error_msg)
+
             # set file status to completed
             await self.ap.persistence_mgr.execute_async(
                 sqlalchemy.update(persistence_rag.File)
@@ -97,16 +101,17 @@ class RuntimeKnowledgeBase(KnowledgeBaseInterface):
             # delete file from storage
             await self.ap.storage_mgr.storage_provider.delete(file.file_name)
 
-    async def store_file(self, file_id: str) -> str:
+    async def store_file(self, file_id: str, parser_plugin_id: str | None = None) -> str:
         # pre checking
         if not await self.ap.storage_mgr.storage_provider.exists(file_id):
             raise Exception(f'File {file_id} not found')
 
         file_name = file_id
-        extension = file_name.split('.')[-1].lower()
+        _, ext = os.path.splitext(file_name)
+        extension = ext.lstrip('.').lower() if ext else ''
 
         if extension == 'zip':
-            return await self._store_zip_file(file_id)
+            return await self._store_zip_file(file_id, parser_plugin_id=parser_plugin_id)
 
         file_uuid = str(uuid.uuid4())
         kb_id = self.knowledge_base_entity.uuid
@@ -126,7 +131,7 @@ class RuntimeKnowledgeBase(KnowledgeBaseInterface):
         # run background task asynchronously
         ctx = taskmgr.TaskContext.new()
         wrapper = self.ap.task_mgr.create_user_task(
-            self._store_file_task(file_obj, task_context=ctx),
+            self._store_file_task(file_obj, task_context=ctx, parser_plugin_id=parser_plugin_id),
             kind='knowledge-operation',
             name=f'knowledge-store-file-{file_id}',
             label=f'Store file {file_id}',
@@ -134,7 +139,7 @@ class RuntimeKnowledgeBase(KnowledgeBaseInterface):
         )
         return wrapper.id
 
-    async def _store_zip_file(self, zip_file_id: str) -> str:
+    async def _store_zip_file(self, zip_file_id: str, parser_plugin_id: str | None = None) -> str:
         """Handle ZIP file by extracting each document and storing them separately."""
         self.ap.logger.info(f'Processing ZIP file: {zip_file_id}')
 
@@ -150,7 +155,8 @@ class RuntimeKnowledgeBase(KnowledgeBaseInterface):
                 if file_info.is_dir() or file_info.filename.startswith('.'):
                     continue
 
-                file_extension = file_info.filename.split('.')[-1].lower()
+                _, file_ext = os.path.splitext(file_info.filename)
+                file_extension = file_ext.lstrip('.').lower()
                 if file_extension not in supported_extensions:
                     self.ap.logger.debug(f'Skipping unsupported file in ZIP: {file_info.filename}')
                     continue
@@ -159,18 +165,18 @@ class RuntimeKnowledgeBase(KnowledgeBaseInterface):
                     file_content = zip_ref.read(file_info.filename)
 
                     base_name = file_info.filename.replace('/', '_').replace('\\', '_')
-                    extension = base_name.split('.')[-1]
-                    file_name = base_name.split('.')[0]
+                    file_stem, file_ext = os.path.splitext(base_name)
+                    extension = file_ext.lstrip('.')
 
-                    if file_name.startswith('__MACOSX'):
+                    if file_stem.startswith('__MACOSX'):
                         continue
 
-                    extracted_file_id = file_name + '_' + str(uuid.uuid4())[:8] + '.' + extension
+                    extracted_file_id = file_stem + '_' + str(uuid.uuid4())[:8] + '.' + extension
                     # save file to storage
 
                     await self.ap.storage_mgr.storage_provider.save(extracted_file_id, file_content)
 
-                    task_id = await self.store_file(extracted_file_id)
+                    task_id = await self.store_file(extracted_file_id, parser_plugin_id=parser_plugin_id)
                     stored_file_tasks.append(task_id)
 
                     self.ap.logger.info(
@@ -189,21 +195,28 @@ class RuntimeKnowledgeBase(KnowledgeBaseInterface):
 
         return stored_file_tasks[0] if stored_file_tasks else ''
 
-    async def retrieve(self, query: str, top_k: int) -> list[rag_context.RetrievalResultEntry]:
-        embedding_model = await self.ap.model_mgr.get_embedding_model_by_uuid(
-            self.knowledge_base_entity.embedding_model_uuid
-        )
-        return await self.retriever.retrieve(self.knowledge_base_entity.uuid, query, embedding_model, top_k)
+    async def retrieve(self, query: str, settings: dict | None = None) -> list[rag_context.RetrievalResultEntry]:
+        # Merge stored retrieval_settings with per-request overrides
+        stored = self.knowledge_base_entity.retrieval_settings or {}
+        merged = {**stored, **(settings or {})}
+        if 'top_k' not in merged:
+            merged['top_k'] = 5  # fallback default
+
+        response = await self._retrieve(query, merged)
+
+        results_data = response.get('results', [])
+        entries = []
+        for r in results_data:
+            if isinstance(r, dict):
+                entries.append(rag_context.RetrievalResultEntry(**r))
+            elif isinstance(r, rag_context.RetrievalResultEntry):
+                entries.append(r)
+        return entries
 
     async def delete_file(self, file_id: str):
-        # delete vector
-        await self.ap.vector_db_mgr.vector_db.delete_by_file_id(self.knowledge_base_entity.uuid, file_id)
-
-        # delete chunk
-        await self.ap.persistence_mgr.execute_async(
-            sqlalchemy.delete(persistence_rag.Chunk).where(persistence_rag.Chunk.file_id == file_id)
-        )
+        await self._delete_document(file_id)
 
+        # Also cleanup DB record
         await self.ap.persistence_mgr.execute_async(
             sqlalchemy.delete(persistence_rag.File).where(persistence_rag.File.uuid == file_id)
         )
@@ -216,32 +229,295 @@ class RuntimeKnowledgeBase(KnowledgeBaseInterface):
         """Get the name of the knowledge base"""
         return self.knowledge_base_entity.name
 
-    def get_type(self) -> str:
-        """Get the type of knowledge base"""
-        return 'internal'
+    def get_knowledge_engine_plugin_id(self) -> str:
+        """Get the Knowledge Engine plugin ID"""
+        return self.knowledge_base_entity.knowledge_engine_plugin_id or ''
 
     async def dispose(self):
-        await self.ap.vector_db_mgr.vector_db.delete_collection(self.knowledge_base_entity.uuid)
+        """Dispose the knowledge base, notifying the plugin to cleanup."""
+        await self._on_kb_delete()
+
+    # ========== Plugin Communication Methods ==========
+
+    async def _on_kb_create(self) -> None:
+        """Notify plugin about KB creation."""
+        plugin_id = self.knowledge_base_entity.knowledge_engine_plugin_id
+        if not plugin_id:
+            return
+
+        try:
+            config = self.knowledge_base_entity.creation_settings or {}
+            self.ap.logger.info(
+                f'Calling RAG plugin {plugin_id}: on_knowledge_base_create(kb_id={self.knowledge_base_entity.uuid})'
+            )
+            await self.ap.plugin_connector.rag_on_kb_create(plugin_id, self.knowledge_base_entity.uuid, config)
+        except Exception as e:
+            self.ap.logger.error(f'Failed to notify plugin {plugin_id} on KB create: {e}')
+            raise
+
+    async def _on_kb_delete(self) -> None:
+        """Notify plugin about KB deletion."""
+        plugin_id = self.knowledge_base_entity.knowledge_engine_plugin_id
+        if not plugin_id:
+            return
+
+        try:
+            self.ap.logger.info(
+                f'Calling RAG plugin {plugin_id}: on_knowledge_base_delete(kb_id={self.knowledge_base_entity.uuid})'
+            )
+            await self.ap.plugin_connector.rag_on_kb_delete(plugin_id, self.knowledge_base_entity.uuid)
+        except Exception as e:
+            self.ap.logger.error(f'Failed to notify plugin {plugin_id} on KB delete: {e}')
+
+    async def _ingest_document(
+        self,
+        file_metadata: dict[str, Any],
+        storage_path: str,
+        parsed_content: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Call plugin to ingest document."""
+        kb = self.knowledge_base_entity
+        plugin_id = kb.knowledge_engine_plugin_id
+        if not plugin_id:
+            self.ap.logger.error(f'No RAG plugin ID configured for KB {kb.uuid}. Ingestion failed.')
+            raise ValueError('RAG Plugin ID required')
+
+        self.ap.logger.info(f'Calling RAG plugin {plugin_id}: ingest(doc={file_metadata.get("filename")})')
+
+        # Inject knowledge_base_id into file metadata as required by SDK schema
+        file_metadata['knowledge_base_id'] = kb.uuid
+
+        context_data = {
+            'file_object': {
+                'metadata': file_metadata,
+                'storage_path': storage_path,
+            },
+            'knowledge_base_id': kb.uuid,
+            'collection_id': kb.collection_id or kb.uuid,
+            'creation_settings': kb.creation_settings or {},
+            'parsed_content': parsed_content,
+        }
+
+        try:
+            result = await self.ap.plugin_connector.call_rag_ingest(plugin_id, context_data)
+            return result
+        except Exception as e:
+            self.ap.logger.error(f'Plugin ingestion failed: {e}')
+            raise
+
+    async def _retrieve(
+        self,
+        query: str,
+        settings: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Call plugin to retrieve documents.
+
+        Raises:
+            ValueError: If no RAG plugin is configured for this KB.
+            Exception: If the plugin retrieval call fails.
+        """
+        kb = self.knowledge_base_entity
+        plugin_id = kb.knowledge_engine_plugin_id
+        if not plugin_id:
+            raise ValueError(f'No RAG plugin ID configured for KB {kb.uuid}. Retrieval failed.')
+
+        # Session context (e.g. session_name) stays in retrieval_settings
+        # for plugins that need it. Do NOT move them into filters, as filters
+        # are passed directly to vector_search by some plugins (e.g. LangRAG)
+        # and would cause empty results when the metadata field doesn't exist.
+        filters = settings.pop('filters', {})
+
+        retrieval_context = {
+            'query': query,
+            'knowledge_base_id': kb.uuid,
+            'collection_id': kb.collection_id or kb.uuid,
+            'retrieval_settings': settings,
+            'creation_settings': kb.creation_settings or {},
+            'filters': filters,
+        }
+
+        result = await self.ap.plugin_connector.call_rag_retrieve(
+            plugin_id,
+            retrieval_context,
+        )
+        return result
+
+    async def _delete_document(self, document_id: str) -> bool:
+        """Call plugin to delete document."""
+        kb = self.knowledge_base_entity
+        plugin_id = kb.knowledge_engine_plugin_id
+        if not plugin_id:
+            return False
+
+        self.ap.logger.info(f'Calling RAG plugin {plugin_id}: delete_document(doc_id={document_id})')
+
+        try:
+            return await self.ap.plugin_connector.call_rag_delete_document(plugin_id, document_id, kb.uuid)
+        except Exception as e:
+            self.ap.logger.error(f'Plugin document deletion failed: {e}')
+            return False
 
 
 class RAGManager:
     ap: app.Application
 
-    knowledge_bases: list[KnowledgeBaseInterface]
+    knowledge_bases: dict[str, KnowledgeBaseInterface]
 
     def __init__(self, ap: app.Application):
         self.ap = ap
-        self.knowledge_bases = []
+        self.knowledge_bases = {}
 
     async def initialize(self):
         await self.load_knowledge_bases_from_db()
 
+    async def get_all_knowledge_base_details(self) -> list[dict]:
+        """Get all knowledge bases with enriched Knowledge Engine details."""
+        # 1. Get raw KBs from DB
+        result = await self.ap.persistence_mgr.execute_async(sqlalchemy.select(persistence_rag.KnowledgeBase))
+        knowledge_bases = result.all()
+
+        # 2. Get all available Knowledge Engines for enrichment
+        engine_map = {}
+        if self.ap.plugin_connector.is_enable_plugin:
+            try:
+                engines = await self.ap.plugin_connector.list_knowledge_engines()
+                engine_map = {e['plugin_id']: e for e in engines}
+            except Exception as e:
+                self.ap.logger.warning(f'Failed to list Knowledge Engines: {e}')
+
+        # 3. Serialize and enrich
+        kb_list = []
+        for kb in knowledge_bases:
+            kb_dict = self.ap.persistence_mgr.serialize_model(persistence_rag.KnowledgeBase, kb)
+            self._enrich_kb_dict(kb_dict, engine_map)
+            kb_list.append(kb_dict)
+
+        return kb_list
+
+    async def get_knowledge_base_details(self, kb_uuid: str) -> dict | None:
+        """Get specific knowledge base with enriched Knowledge Engine details."""
+        result = await self.ap.persistence_mgr.execute_async(
+            sqlalchemy.select(persistence_rag.KnowledgeBase).where(persistence_rag.KnowledgeBase.uuid == kb_uuid)
+        )
+        kb = result.first()
+        if not kb:
+            return None
+
+        kb_dict = self.ap.persistence_mgr.serialize_model(persistence_rag.KnowledgeBase, kb)
+
+        # Fetch engines
+        engine_map = {}
+        if self.ap.plugin_connector.is_enable_plugin:
+            try:
+                engines = await self.ap.plugin_connector.list_knowledge_engines()
+                engine_map = {e['plugin_id']: e for e in engines}
+            except Exception as e:
+                self.ap.logger.warning(f'Failed to list Knowledge Engines: {e}')
+
+        self._enrich_kb_dict(kb_dict, engine_map)
+        return kb_dict
+
+    @staticmethod
+    def _to_i18n_name(name) -> dict:
+        """Ensure name is always an I18nObject-compatible dict.
+
+        If *name* is already a dict (with ``en_US`` / ``zh_Hans`` keys) it is
+        returned as-is.  A plain string is wrapped into an I18nObject so the
+        frontend ``extractI18nObject`` helper never receives an unexpected type.
+        """
+        if isinstance(name, dict):
+            return name
+        return {'en_US': str(name), 'zh_Hans': str(name)}
+
+    def _enrich_kb_dict(self, kb_dict: dict, engine_map: dict) -> None:
+        """Helper to inject engine info into KB dict."""
+        plugin_id = kb_dict.get('knowledge_engine_plugin_id')
+
+        # Default fallback structure — name must be I18nObject for frontend compatibility
+        fallback_name = self._to_i18n_name(plugin_id or 'Internal (Legacy)')
+        fallback_info = {
+            'plugin_id': plugin_id,
+            'name': fallback_name,
+            'capabilities': [],
+        }
+
+        if not plugin_id:
+            kb_dict['knowledge_engine'] = fallback_info
+            return
+
+        engine_info = engine_map.get(plugin_id)
+        if engine_info:
+            kb_dict['knowledge_engine'] = {
+                'plugin_id': plugin_id,
+                'name': self._to_i18n_name(engine_info.get('name', plugin_id)),
+                'capabilities': engine_info.get('capabilities', []),
+            }
+        else:
+            kb_dict['knowledge_engine'] = fallback_info
+
+    async def create_knowledge_base(
+        self,
+        name: str,
+        knowledge_engine_plugin_id: str,
+        creation_settings: dict,
+        retrieval_settings: dict | None = None,
+        description: str = '',
+    ) -> persistence_rag.KnowledgeBase:
+        """Create a new knowledge base using a RAG plugin."""
+        # Validate that the Knowledge Engine plugin exists
+        if self.ap.plugin_connector.is_enable_plugin:
+            try:
+                engines = await self.ap.plugin_connector.list_knowledge_engines()
+                engine_ids = [e.get('plugin_id') for e in engines]
+                if knowledge_engine_plugin_id not in engine_ids:
+                    raise ValueError(f'Knowledge Engine plugin {knowledge_engine_plugin_id} not found')
+            except ValueError:
+                raise
+            except Exception as e:
+                self.ap.logger.warning(f'Failed to validate Knowledge Engine plugin existence: {e}')
+
+        kb_uuid = str(uuid.uuid4())
+        # Use UUID as collection ID by default for isolation
+        collection_id = kb_uuid
+
+        kb_data = {
+            'uuid': kb_uuid,
+            'name': name,
+            'description': description,
+            'knowledge_engine_plugin_id': knowledge_engine_plugin_id,
+            'collection_id': collection_id,
+            'creation_settings': creation_settings,
+            'retrieval_settings': retrieval_settings or {},
+        }
+
+        # Create Entity
+        kb = persistence_rag.KnowledgeBase(**kb_data)
+
+        # Persist
+        await self.ap.persistence_mgr.execute_async(sqlalchemy.insert(persistence_rag.KnowledgeBase).values(kb_data))
+
+        # Load into Runtime
+        runtime_kb = await self.load_knowledge_base(kb)
+
+        # Notify Plugin — rollback DB record and runtime entry on failure
+        try:
+            await runtime_kb._on_kb_create()
+        except Exception:
+            self.knowledge_bases.pop(kb_uuid, None)
+            await self.ap.persistence_mgr.execute_async(
+                sqlalchemy.delete(persistence_rag.KnowledgeBase).where(persistence_rag.KnowledgeBase.uuid == kb_uuid)
+            )
+            raise
+
+        self.ap.logger.info(f'Created new Knowledge Base {name} ({kb_uuid}) using plugin {knowledge_engine_plugin_id}')
+        return kb
+
     async def load_knowledge_bases_from_db(self):
         self.ap.logger.info('Loading knowledge bases from db...')
 
-        self.knowledge_bases = []
+        self.knowledge_bases = {}
 
-        # Load internal knowledge bases
+        # Load knowledge bases
         result = await self.ap.persistence_mgr.execute_async(sqlalchemy.select(persistence_rag.KnowledgeBase))
         knowledge_bases = result.all()
 
@@ -253,86 +529,37 @@ class RAGManager:
                     f'Error loading knowledge base {knowledge_base.uuid}: {e}\n{traceback.format_exc()}'
                 )
 
-        # Load external knowledge bases
-        external_result = await self.ap.persistence_mgr.execute_async(
-            sqlalchemy.select(persistence_rag.ExternalKnowledgeBase)
-        )
-        external_kbs = external_result.all()
-
-        for external_kb in external_kbs:
-            try:
-                # Don't trigger sync during batch loading - will sync once after LangBot connects to runtime
-                await self.load_external_knowledge_base(external_kb, trigger_sync=False)
-            except Exception as e:
-                self.ap.logger.error(
-                    f'Error loading external knowledge base {external_kb.uuid}: {e}\n{traceback.format_exc()}'
-                )
-
     async def load_knowledge_base(
         self,
         knowledge_base_entity: persistence_rag.KnowledgeBase | sqlalchemy.Row | dict,
     ) -> RuntimeKnowledgeBase:
         if isinstance(knowledge_base_entity, sqlalchemy.Row):
+            # Safe access to _mapping for SQLAlchemy 1.4+
             knowledge_base_entity = persistence_rag.KnowledgeBase(**knowledge_base_entity._mapping)
         elif isinstance(knowledge_base_entity, dict):
-            knowledge_base_entity = persistence_rag.KnowledgeBase(**knowledge_base_entity)
+            # Filter out non-database fields (like knowledge_engine which is computed)
+            filtered_dict = {
+                k: v for k, v in knowledge_base_entity.items() if k in persistence_rag.KnowledgeBase.ALL_DB_FIELDS
+            }
+            knowledge_base_entity = persistence_rag.KnowledgeBase(**filtered_dict)
 
         runtime_knowledge_base = RuntimeKnowledgeBase(ap=self.ap, knowledge_base_entity=knowledge_base_entity)
 
         await runtime_knowledge_base.initialize()
 
-        self.knowledge_bases.append(runtime_knowledge_base)
+        self.knowledge_bases[runtime_knowledge_base.get_uuid()] = runtime_knowledge_base
 
         return runtime_knowledge_base
 
-    async def load_external_knowledge_base(
-        self,
-        external_kb_entity: persistence_rag.ExternalKnowledgeBase | sqlalchemy.Row | dict,
-        trigger_sync: bool = True,
-    ) -> ExternalKnowledgeBase:
-        """Load external knowledge base into runtime
-
-        Args:
-            external_kb_entity: External KB entity to load
-            trigger_sync: Whether to trigger sync after loading (default True for manual creation, False for batch loading)
-        """
-        if isinstance(external_kb_entity, sqlalchemy.Row):
-            external_kb_entity = persistence_rag.ExternalKnowledgeBase(**external_kb_entity._mapping)
-        elif isinstance(external_kb_entity, dict):
-            external_kb_entity = persistence_rag.ExternalKnowledgeBase(**external_kb_entity)
-
-        external_kb = ExternalKnowledgeBase(ap=self.ap, external_kb_entity=external_kb_entity)
-
-        await external_kb.initialize()
-
-        self.knowledge_bases.append(external_kb)
-
-        # Trigger sync to create the instance immediately (for manual creation)
-        # Skip sync during batch loading from DB to avoid multiple sync calls
-        if trigger_sync:
-            try:
-                await self.ap.plugin_connector.sync_polymorphic_component_instances()
-                self.ap.logger.info(f'Triggered sync after loading external KB {external_kb_entity.uuid}')
-            except Exception as e:
-                self.ap.logger.error(f'Failed to sync after loading external KB: {e}')
-
-        return external_kb
-
     async def get_knowledge_base_by_uuid(self, kb_uuid: str) -> KnowledgeBaseInterface | None:
-        for kb in self.knowledge_bases:
-            if kb.get_uuid() == kb_uuid:
-                return kb
-        return None
+        return self.knowledge_bases.get(kb_uuid)
 
     async def remove_knowledge_base_from_runtime(self, kb_uuid: str):
-        for kb in self.knowledge_bases:
-            if kb.get_uuid() == kb_uuid:
-                self.knowledge_bases.remove(kb)
-                return
+        self.knowledge_bases.pop(kb_uuid, None)
 
     async def delete_knowledge_base(self, kb_uuid: str):
-        for kb in self.knowledge_bases:
-            if kb.get_uuid() == kb_uuid:
-                await kb.dispose()
-                self.knowledge_bases.remove(kb)
-                return
+        kb = self.knowledge_bases.pop(kb_uuid, None)
+        if kb is not None:
+            await kb.dispose()
+        else:
+            self.ap.logger.warning(f'Knowledge base {kb_uuid} not found in runtime, skipping plugin notification')

src/langbot/pkg/rag/knowledge/services/base_service.py

@@ -1,15 +0,0 @@
-# 封装异步操作
-import asyncio
-
-
-class BaseService:
-    def __init__(self):
-        pass
-
-    async def _run_sync(self, func, *args, **kwargs):
-        """
-        在单独的线程中运行同步函数。
-        如果第一个参数是 session，则在 to_thread 中获取新的 session。
-        """
-
-        return await asyncio.to_thread(func, *args, **kwargs)

src/langbot/pkg/rag/knowledge/services/chunker.py

@@ -1,49 +0,0 @@
-from __future__ import annotations
-
-import json
-from typing import List
-from langbot.pkg.rag.knowledge.services import base_service
-from langbot.pkg.core import app
-from langchain_text_splitters import RecursiveCharacterTextSplitter
-
-
-class Chunker(base_service.BaseService):
-    """
-    A class for splitting long texts into smaller, overlapping chunks.
-    """
-
-    def __init__(self, ap: app.Application, chunk_size: int = 500, chunk_overlap: int = 50):
-        self.ap = ap
-        self.chunk_size = chunk_size
-        self.chunk_overlap = chunk_overlap
-        if self.chunk_overlap >= self.chunk_size:
-            self.ap.logger.warning(
-                'Chunk overlap is greater than or equal to chunk size. This may lead to empty or malformed chunks.'
-            )
-
-    def _split_text_sync(self, text: str) -> List[str]:
-        """
-        Synchronously splits a long text into chunks with specified overlap.
-        This is a CPU-bound operation, intended to be run in a separate thread.
-        """
-        if not text:
-            return []
-
-        text_splitter = RecursiveCharacterTextSplitter(
-            chunk_size=self.chunk_size,
-            chunk_overlap=self.chunk_overlap,
-            length_function=len,
-            is_separator_regex=False,
-        )
-        return text_splitter.split_text(text)
-
-    async def chunk(self, text: str) -> List[str]:
-        """
-        Asynchronously chunks a given text into smaller pieces.
-        """
-        self.ap.logger.info(f'Chunking text (length: {len(text)})...')
-        # Run the synchronous splitting logic in a separate thread
-        chunks = await self._run_sync(self._split_text_sync, text)
-        self.ap.logger.info(f'Text chunked into {len(chunks)} pieces.')
-        self.ap.logger.debug(f'Chunks: {json.dumps(chunks, indent=4, ensure_ascii=False)}')
-        return chunks

src/langbot/pkg/rag/knowledge/services/embedder.py

@@ -1,55 +0,0 @@
-from __future__ import annotations
-import uuid
-from typing import List
-from langbot.pkg.rag.knowledge.services.base_service import BaseService
-from langbot.pkg.entity.persistence import rag as persistence_rag
-from langbot.pkg.core import app
-from langbot.pkg.provider.modelmgr.requester import RuntimeEmbeddingModel
-import sqlalchemy
-
-
-class Embedder(BaseService):
-    def __init__(self, ap: app.Application) -> None:
-        super().__init__()
-        self.ap = ap
-
-    async def embed_and_store(
-        self, kb_id: str, file_id: str, chunks: List[str], embedding_model: RuntimeEmbeddingModel
-    ) -> list[persistence_rag.Chunk]:
-        # save chunk to db
-        chunk_entities: list[persistence_rag.Chunk] = []
-        chunk_ids: list[str] = []
-
-        for chunk_text in chunks:
-            chunk_uuid = str(uuid.uuid4())
-            chunk_ids.append(chunk_uuid)
-            chunk_entity = persistence_rag.Chunk(uuid=chunk_uuid, file_id=file_id, text=chunk_text)
-            chunk_entities.append(chunk_entity)
-
-        chunk_dicts = [
-            self.ap.persistence_mgr.serialize_model(persistence_rag.Chunk, chunk) for chunk in chunk_entities
-        ]
-
-        await self.ap.persistence_mgr.execute_async(sqlalchemy.insert(persistence_rag.Chunk).values(chunk_dicts))
-
-        # get embeddings (batch size limit: 64 for OpenAI)
-        MAX_BATCH_SIZE = 64
-        embeddings_list: list[list[float]] = []
-
-        for i in range(0, len(chunks), MAX_BATCH_SIZE):
-            batch = chunks[i : i + MAX_BATCH_SIZE]
-            batch_embeddings = await embedding_model.provider.invoke_embedding(
-                model=embedding_model,
-                input_text=batch,
-                extra_args={},  # TODO: add extra args
-                knowledge_base_id=kb_id,
-                call_type='embedding',
-            )
-            embeddings_list.extend(batch_embeddings)
-
-        # save embeddings to vdb
-        await self.ap.vector_db_mgr.vector_db.add_embeddings(kb_id, chunk_ids, embeddings_list, chunk_dicts)
-
-        self.ap.logger.info(f'Successfully saved {len(chunk_entities)} embeddings to Knowledge Base.')
-
-        return chunk_entities

src/langbot/pkg/rag/knowledge/services/parser.py

@@ -1,291 +0,0 @@
-from __future__ import annotations
-
-import PyPDF2
-import io
-from docx import Document
-import chardet
-from typing import Union, Callable, Any
-import markdown
-from bs4 import BeautifulSoup
-import re
-import asyncio  # Import asyncio for async operations
-from langbot.pkg.core import app
-
-
-class FileParser:
-    """
-    A robust file parser class to extract text content from various document formats.
-    It supports TXT, PDF, DOCX, XLSX, CSV, Markdown, HTML, and EPUB files.
-    All core file reading operations are designed to be run synchronously in a thread pool
-    to avoid blocking the asyncio event loop.
-    """
-
-    def __init__(self, ap: app.Application):
-        self.ap = ap
-
-    async def _run_sync(self, sync_func: Callable, *args: Any, **kwargs: Any) -> Any:
-        """
-        Runs a synchronous function in a separate thread to prevent blocking the event loop.
-        This is a general utility method for wrapping blocking I/O operations.
-        """
-        try:
-            return await asyncio.to_thread(sync_func, *args, **kwargs)
-        except Exception as e:
-            self.ap.logger.error(f'Error running synchronous function {sync_func.__name__}: {e}')
-            raise
-
-    async def parse(self, file_name: str, extension: str) -> Union[str, None]:
-        """
-        Parses the file based on its extension and returns the extracted text content.
-        This is the main asynchronous entry point for parsing.
-
-        Args:
-            file_name (str): The name of the file to be parsed, get from ap.storage_mgr
-
-        Returns:
-            Union[str, None]: The extracted text content as a single string, or None if parsing fails.
-        """
-
-        file_extension = extension.lower()
-        parser_method = getattr(self, f'_parse_{file_extension}', None)
-
-        if parser_method is None:
-            self.ap.logger.error(f'Unsupported file format: {file_extension} for file {file_name}')
-            return None
-
-        try:
-            # Pass file_path to the specific parser methods
-            return await parser_method(file_name)
-        except Exception as e:
-            self.ap.logger.error(f'Failed to parse {file_extension} file {file_name}: {e}')
-            return None
-
-    # --- Helper for reading files with encoding detection ---
-    async def _read_file_content(self, file_name: str) -> Union[str, bytes]:
-        """
-        Reads a file with automatic encoding detection, ensuring the synchronous
-        file read operation runs in a separate thread.
-        """
-
-        # def _read_sync():
-        #     with open(file_path, 'rb') as file:
-        #         raw_data = file.read()
-        #         detected = chardet.detect(raw_data)
-        #         encoding = detected['encoding'] or 'utf-8'
-
-        #     if mode == 'r':
-        #         return raw_data.decode(encoding, errors='ignore')
-        #     return raw_data  # For binary mode
-
-        # return await self._run_sync(_read_sync)
-        file_bytes = await self.ap.storage_mgr.storage_provider.load(file_name)
-
-        detected = chardet.detect(file_bytes)
-        encoding = detected['encoding'] or 'utf-8'
-
-        return file_bytes.decode(encoding, errors='ignore')
-
-    # --- Specific Parser Methods ---
-
-    async def _parse_txt(self, file_name: str) -> str:
-        """Parses a TXT file and returns its content."""
-        self.ap.logger.info(f'Parsing TXT file: {file_name}')
-        return await self._read_file_content(file_name)
-
-    async def _parse_pdf(self, file_name: str) -> str:
-        """Parses a PDF file and returns its text content."""
-        self.ap.logger.info(f'Parsing PDF file: {file_name}')
-
-        # def _parse_pdf_sync():
-        #     text_content = []
-        #     with open(file_name, 'rb') as file:
-        #         pdf_reader = PyPDF2.PdfReader(file)
-        #         for page in pdf_reader.pages:
-        #             text = page.extract_text()
-        #             if text:
-        #                 text_content.append(text)
-        #     return '\n'.join(text_content)
-
-        # return await self._run_sync(_parse_pdf_sync)
-
-        pdf_bytes = await self.ap.storage_mgr.storage_provider.load(file_name)
-
-        def _parse_pdf_sync():
-            pdf_reader = PyPDF2.PdfReader(io.BytesIO(pdf_bytes))
-            text_content = []
-            for page in pdf_reader.pages:
-                text = page.extract_text()
-                if text:
-                    text_content.append(text)
-            return '\n'.join(text_content)
-
-        return await self._run_sync(_parse_pdf_sync)
-
-    async def _parse_docx(self, file_name: str) -> str:
-        """Parses a DOCX file and returns its text content."""
-        self.ap.logger.info(f'Parsing DOCX file: {file_name}')
-
-        docx_bytes = await self.ap.storage_mgr.storage_provider.load(file_name)
-
-        def _parse_docx_sync():
-            doc = Document(io.BytesIO(docx_bytes))
-            text_content = [paragraph.text for paragraph in doc.paragraphs if paragraph.text.strip()]
-            return '\n'.join(text_content)
-
-        return await self._run_sync(_parse_docx_sync)
-
-    async def _parse_doc(self, file_name: str) -> str:
-        """Handles .doc files, explicitly stating lack of direct support."""
-        self.ap.logger.warning(f'Direct .doc parsing is not supported for {file_name}. Please convert to .docx first.')
-        raise NotImplementedError('Direct .doc parsing not supported. Please convert to .docx first.')
-
-    # async def _parse_xlsx(self, file_name: str) -> str:
-    #     """Parses an XLSX file, returning text from all sheets."""
-    #     self.ap.logger.info(f'Parsing XLSX file: {file_name}')
-
-    #     xlsx_bytes = await self.ap.storage_mgr.storage_provider.load(file_name)
-
-    #     def _parse_xlsx_sync():
-    #         excel_file = pd.ExcelFile(io.BytesIO(xlsx_bytes))
-    #         all_sheet_content = []
-    #         for sheet_name in excel_file.sheet_names:
-    #             df = pd.read_excel(io.BytesIO(xlsx_bytes), sheet_name=sheet_name)
-    #             sheet_text = f'--- Sheet: {sheet_name} ---\n{df.to_string(index=False)}\n'
-    #             all_sheet_content.append(sheet_text)
-    #         return '\n'.join(all_sheet_content)
-
-    #     return await self._run_sync(_parse_xlsx_sync)
-
-    # async def _parse_csv(self, file_name: str) -> str:
-    #     """Parses a CSV file and returns its content as a string."""
-    #     self.ap.logger.info(f'Parsing CSV file: {file_name}')
-
-    #     csv_bytes = await self.ap.storage_mgr.storage_provider.load(file_name)
-
-    #     def _parse_csv_sync():
-    #         # pd.read_csv can often detect encoding, but explicit detection is safer
-    #         # raw_data = self._read_file_content(
-    #         #     file_name, mode='rb'
-    #         # )  # Note: this will need to be await outside this sync function
-    #         # _ = raw_data
-    #         # For simplicity, we'll let pandas handle encoding internally after a raw read.
-    #         # A more robust solution might pass encoding directly to pd.read_csv after detection.
-    #         detected = chardet.detect(io.BytesIO(csv_bytes))
-    #         encoding = detected['encoding'] or 'utf-8'
-    #         df = pd.read_csv(io.BytesIO(csv_bytes), encoding=encoding)
-    #         return df.to_string(index=False)
-
-    #     return await self._run_sync(_parse_csv_sync)
-
-    async def _parse_md(self, file_name: str) -> str:
-        """Parses a Markdown file, converting it to structured plain text."""
-        self.ap.logger.info(f'Parsing Markdown file: {file_name}')
-
-        md_bytes = await self.ap.storage_mgr.storage_provider.load(file_name)
-
-        def _parse_markdown_sync():
-            md_content = io.BytesIO(md_bytes).read().decode('utf-8', errors='ignore')
-            html_content = markdown.markdown(
-                md_content, extensions=['extra', 'codehilite', 'tables', 'toc', 'fenced_code']
-            )
-            soup = BeautifulSoup(html_content, 'html.parser')
-            text_parts = []
-            for element in soup.children:
-                if element.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']:
-                    level = int(element.name[1])
-                    text_parts.append('#' * level + ' ' + element.get_text().strip())
-                elif element.name == 'p':
-                    text = element.get_text().strip()
-                    if text:
-                        text_parts.append(text)
-                elif element.name in ['ul', 'ol']:
-                    for li in element.find_all('li'):
-                        text_parts.append(f'* {li.get_text().strip()}')
-                elif element.name == 'pre':
-                    code_block = element.get_text().strip()
-                    if code_block:
-                        text_parts.append(f'```\n{code_block}\n```')
-                elif element.name == 'table':
-                    table_str = self._extract_table_to_markdown_sync(element)  # Call sync helper
-                    if table_str:
-                        text_parts.append(table_str)
-                elif element.name:
-                    text = element.get_text(separator=' ', strip=True)
-                    if text:
-                        text_parts.append(text)
-            cleaned_text = re.sub(r'\n\s*\n', '\n\n', '\n'.join(text_parts))
-            return cleaned_text.strip()
-
-        return await self._run_sync(_parse_markdown_sync)
-
-    async def _parse_html(self, file_name: str) -> str:
-        """Parses an HTML file, extracting structured plain text."""
-        self.ap.logger.info(f'Parsing HTML file: {file_name}')
-
-        html_bytes = await self.ap.storage_mgr.storage_provider.load(file_name)
-
-        def _parse_html_sync():
-            html_content = io.BytesIO(html_bytes).read().decode('utf-8', errors='ignore')
-            soup = BeautifulSoup(html_content, 'html.parser')
-            for script_or_style in soup(['script', 'style']):
-                script_or_style.decompose()
-            text_parts = []
-            for element in soup.body.children if soup.body else soup.children:
-                if element.name in ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']:
-                    level = int(element.name[1])
-                    text_parts.append('#' * level + ' ' + element.get_text().strip())
-                elif element.name == 'p':
-                    text = element.get_text().strip()
-                    if text:
-                        text_parts.append(text)
-                elif element.name in ['ul', 'ol']:
-                    for li in element.find_all('li'):
-                        text = li.get_text().strip()
-                        if text:
-                            text_parts.append(f'* {text}')
-                elif element.name == 'table':
-                    table_str = self._extract_table_to_markdown_sync(element)  # Call sync helper
-                    if table_str:
-                        text_parts.append(table_str)
-                elif element.name:
-                    text = element.get_text(separator=' ', strip=True)
-                    if text:
-                        text_parts.append(text)
-            cleaned_text = re.sub(r'\n\s*\n', '\n\n', '\n'.join(text_parts))
-            return cleaned_text.strip()
-
-        return await self._run_sync(_parse_html_sync)
-
-    def _add_toc_items_sync(self, toc_list: list, text_content: list, level: int):
-        """Recursively adds TOC items to text_content (synchronous helper)."""
-        indent = '  ' * level
-        for item in toc_list:
-            if isinstance(item, tuple):
-                chapter, subchapters = item
-                text_content.append(f'{indent}- {chapter.title}')
-                self._add_toc_items_sync(subchapters, text_content, level + 1)
-            else:
-                text_content.append(f'{indent}- {item.title}')
-
-    def _extract_table_to_markdown_sync(self, table_element: BeautifulSoup) -> str:
-        """Helper to convert a BeautifulSoup table element into a Markdown table string (synchronous)."""
-        headers = [th.get_text().strip() for th in table_element.find_all('th')]
-        rows = []
-        for tr in table_element.find_all('tr'):
-            cells = [td.get_text().strip() for td in tr.find_all('td')]
-            if cells:
-                rows.append(cells)
-
-        if not headers and not rows:
-            return ''
-
-        table_lines = []
-        if headers:
-            table_lines.append(' | '.join(headers))
-            table_lines.append(' | '.join(['---'] * len(headers)))
-
-        for row_cells in rows:
-            padded_cells = row_cells + [''] * (len(headers) - len(row_cells)) if headers else row_cells
-            table_lines.append(' | '.join(padded_cells))
-
-        return '\n'.join(table_lines)

src/langbot/pkg/rag/knowledge/services/retriever.py

@@ -1,53 +0,0 @@
-from __future__ import annotations
-
-from . import base_service
-from ....core import app
-from ....provider.modelmgr.requester import RuntimeEmbeddingModel
-from langbot_plugin.api.entities.builtin.rag import context as rag_context
-from langbot_plugin.api.entities.builtin.provider.message import ContentElement
-
-
-class Retriever(base_service.BaseService):
-    def __init__(self, ap: app.Application):
-        super().__init__()
-        self.ap = ap
-
-    async def retrieve(
-        self, kb_id: str, query: str, embedding_model: RuntimeEmbeddingModel, k: int = 5
-    ) -> list[rag_context.RetrievalResultEntry]:
-        self.ap.logger.info(
-            f"Retrieving for query: '{query[:10]}' with k={k} using {embedding_model.model_entity.uuid}"
-        )
-
-        query_embedding: list[float] = await embedding_model.provider.invoke_embedding(
-            model=embedding_model,
-            input_text=[query],
-            extra_args={},  # TODO: add extra args
-            knowledge_base_id=kb_id,
-            query_text=query,
-            call_type='retrieve',
-        )
-
-        vector_results = await self.ap.vector_db_mgr.vector_db.search(kb_id, query_embedding[0], k)
-
-        # 'ids' shape mirrors the Chroma-style response contract for compatibility
-        matched_vector_ids = vector_results.get('ids', [[]])[0]
-        distances = vector_results.get('distances', [[]])[0]
-        vector_metadatas = vector_results.get('metadatas', [[]])[0]
-
-        if not matched_vector_ids:
-            self.ap.logger.info('No relevant chunks found in vector database.')
-            return []
-
-        result: list[rag_context.RetrievalResultEntry] = []
-
-        for i, id in enumerate(matched_vector_ids):
-            entry = rag_context.RetrievalResultEntry(
-                id=id,
-                content=[ContentElement.from_text(vector_metadatas[i].get('text', ''))],
-                metadata=vector_metadatas[i],
-                distance=distances[i],
-            )
-            result.append(entry)
-
-        return result

src/langbot/pkg/rag/service/__init__.py

@@ -0,0 +1 @@
+from .runtime import RAGRuntimeService as RAGRuntimeService

src/langbot/pkg/rag/service/runtime.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import posixpath
+from typing import Any
+from langbot.pkg.core import app
+
+
+class RAGRuntimeService:
+    """Service to handle RAG-related requests from plugins (Runtime).
+
+    This service acts as the bridge between plugin RPC requests and
+    LangBot's infrastructure (embedding models, vector databases, file storage).
+    """
+
+    def __init__(self, ap: app.Application):
+        self.ap = ap
+
+    async def vector_upsert(
+        self,
+        collection_id: str,
+        vectors: list[list[float]],
+        ids: list[str],
+        metadata: list[dict[str, Any]] | None = None,
+        documents: list[str] | None = None,
+    ) -> None:
+        """Handle VECTOR_UPSERT action."""
+        metadatas = metadata if metadata else [{} for _ in vectors]
+        await self.ap.vector_db_mgr.upsert(
+            collection_name=collection_id,
+            vectors=vectors,
+            ids=ids,
+            metadata=metadatas,
+            documents=documents,
+        )
+
+    async def vector_search(
+        self,
+        collection_id: str,
+        query_vector: list[float],
+        top_k: int,
+        filters: dict[str, Any] | None = None,
+        search_type: str = 'vector',
+        query_text: str = '',
+    ) -> list[dict[str, Any]]:
+        """Handle VECTOR_SEARCH action."""
+        return await self.ap.vector_db_mgr.search(
+            collection_name=collection_id,
+            query_vector=query_vector,
+            limit=top_k,
+            filter=filters,
+            search_type=search_type,
+            query_text=query_text,
+        )
+
+    async def vector_delete(
+        self, collection_id: str, file_ids: list[str] | None = None, filters: dict[str, Any] | None = None
+    ) -> int:
+        """Handle VECTOR_DELETE action.
+
+        Deletes vectors associated with the given file IDs from the collection.
+        Each file_id corresponds to a document whose vectors will be removed.
+
+        Args:
+            collection_id: The collection to delete from.
+            file_ids: File IDs whose associated vectors should be deleted.
+                Each file_id maps to a set of vectors stored with that file_id
+                in their metadata.
+            filters: Filter-based deletion (not yet supported, will raise).
+        """
+        count = 0
+        if file_ids:
+            await self.ap.vector_db_mgr.delete_by_file_id(collection_name=collection_id, file_ids=file_ids)
+            count = len(file_ids)
+        elif filters:
+            count = await self.ap.vector_db_mgr.delete_by_filter(collection_name=collection_id, filter=filters)
+        return count
+
+    async def get_file_stream(self, storage_path: str) -> bytes:
+        """Handle GET_KNOWLEDEGE_FILE_STREAM action.
+
+        Uses the storage manager abstraction to load file content,
+        regardless of the underlying storage provider.
+        """
+        # Validate storage_path to prevent path traversal
+        normalized = posixpath.normpath(storage_path)
+        if normalized.startswith('/') or '..' in normalized.split('/'):
+            raise ValueError('Invalid storage path')
+        content_bytes = await self.ap.storage_mgr.storage_provider.load(normalized)
+        return content_bytes if content_bytes else b''

src/langbot/pkg/storage/provider.py

@@ -43,6 +43,13 @@ class StorageProvider(abc.ABC):
     ):
         pass
 
+    @abc.abstractmethod
+    async def size(
+        self,
+        key: str,
+    ) -> int:
+        pass
+
     @abc.abstractmethod
     async def delete_dir_recursive(
         self,

src/langbot/pkg/storage/providers/localstorage.py

@@ -47,6 +47,12 @@ class LocalStorageProvider(provider.StorageProvider):
     ):
         os.remove(os.path.join(LOCAL_STORAGE_PATH, f'{key}'))
 
+    async def size(
+        self,
+        key: str,
+    ) -> int:
+        return os.path.getsize(os.path.join(LOCAL_STORAGE_PATH, f'{key}'))
+
     async def delete_dir_recursive(
         self,
         dir_path: str,

src/langbot/pkg/storage/providers/s3storage.py

@@ -117,6 +117,21 @@ class S3StorageProvider(provider.StorageProvider):
             self.ap.logger.error(f'Failed to delete from S3: {e}')
             raise
 
+    async def size(
+        self,
+        key: str,
+    ) -> int:
+        """Get object size from S3 without downloading it"""
+        try:
+            response = self.s3_client.head_object(
+                Bucket=self.bucket_name,
+                Key=key,
+            )
+            return response['ContentLength']
+        except Exception as e:
+            self.ap.logger.error(f'Failed to get size from S3: {e}')
+            raise
+
     async def delete_dir_recursive(
         self,
         dir_path: str,

src/langbot/pkg/telemetry/telemetry.py

@@ -60,7 +60,7 @@ class TelemetryManager:
                     except Exception:
                         sanitized['query_id'] = str(sanitized.get('query_id', ''))
 
-                for sfield in ('adapter', 'runner', 'model_name', 'version', 'error', 'timestamp'):
+                for sfield in ('adapter', 'runner', 'runner_category', 'model_name', 'version', 'error', 'timestamp'):
                     v = sanitized.get(sfield)
                     sanitized[sfield] = '' if v is None else str(v)
 

src/langbot/pkg/utils/constants.py

@@ -2,7 +2,7 @@ import langbot
 
 semantic_version = f'v{langbot.__version__}'
 
-required_database_version = 19
+required_database_version = 22
 """Tag the version of the database schema, used to check if the database needs to be migrated"""
 
 debug_mode = False

src/langbot/pkg/utils/runner.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+
+class RunnerCategory:
+    LOCAL = 'local'
+    CLOUD = 'cloud'
+    UNKNOWN = 'unknown'
+
+
+CLOUD_DOMAINS = [
+    '.n8n.cloud',
+    '.n8n.io',
+    'api.dify.ai',
+    'cloud.dify.ai',
+    '.coze.com',
+    '.coze.cn',
+    'cloud.langflow.ai',
+    '.langflow.org',
+]
+
+LOCAL_PATTERNS = [
+    'localhost',
+    '127.0.0.1',
+    '0.0.0.0',
+    '192.168.',
+    '10.',
+    '172.16.',
+    '172.17.',
+    '172.18.',
+    '172.19.',
+    '172.20.',
+    '172.21.',
+    '172.22.',
+    '172.23.',
+    '172.24.',
+    '172.25.',
+    '172.26.',
+    '172.27.',
+    '172.28.',
+    '172.29.',
+    '172.30.',
+    '172.31.',
+]
+
+
+def get_runner_category(runner_name: str, runner_url: str) -> str:
+    if not runner_url:
+        return RunnerCategory.UNKNOWN
+
+    try:
+        parsed_url = urlparse(runner_url)
+        host = parsed_url.hostname.lower() if parsed_url.hostname else ''
+    except Exception:
+        return RunnerCategory.UNKNOWN
+
+    for pattern in LOCAL_PATTERNS:
+        if host.startswith(pattern):
+            return RunnerCategory.LOCAL
+
+    for domain in CLOUD_DOMAINS:
+        if host.endswith(domain):
+            return RunnerCategory.CLOUD
+
+    return RunnerCategory.CLOUD
+
+
+def get_runner_info(runner_name: str, runner_url: str) -> dict:
+    return {
+        'name': runner_name,
+        'url': runner_url,
+        'category': get_runner_category(runner_name, runner_url),
+    }
+
+
+def is_cloud_runner(runner_name: str, runner_url: str) -> bool:
+    return get_runner_category(runner_name, runner_url) == RunnerCategory.CLOUD
+
+
+def is_local_runner(runner_name: str, runner_url: str) -> bool:
+    return get_runner_category(runner_name, runner_url) == RunnerCategory.LOCAL
+
+
+def extract_runner_url(runner_name: str, runner, pipeline_config: dict | None) -> str | None:
+    if not runner or not hasattr(runner, 'pipeline_config'):
+        return None
+
+    ai_config = pipeline_config.get('ai', {}) if pipeline_config else {}
+
+    if runner_name == 'dify-service-api':
+        return ai_config.get('dify-service-api', {}).get('base-url')
+    elif runner_name == 'n8n-service-api':
+        return ai_config.get('n8n-service-api', {}).get('webhook-url')
+    elif runner_name == 'coze-api':
+        return ai_config.get('coze-api', {}).get('api-base')
+    elif runner_name == 'langflow-api':
+        return ai_config.get('langflow-api', {}).get('base-url')
+
+    return None
+
+
+def get_runner_category_from_runner(runner_name: str, runner, pipeline_config: dict | None) -> str:
+    runner_url = extract_runner_url(runner_name, runner, pipeline_config)
+    return get_runner_category(runner_name, runner_url)

src/langbot/pkg/vector/filter_utils.py

@@ -0,0 +1,69 @@
+"""Shared utilities for metadata filter handling across VDB backends.
+
+Canonical filter format (Chroma-style ``where`` syntax):
+
+    {"file_id": "abc"}                      # implicit $eq
+    {"file_id": {"$eq": "abc"}}             # explicit $eq
+    {"created_at": {"$gte": 1700000000}}    # comparison
+    {"file_type": {"$in": ["pdf", "docx"]}} # in-list
+
+Multiple top-level keys are AND-ed.  Supported operators:
+``$eq``, ``$ne``, ``$gt``, ``$gte``, ``$lt``, ``$lte``, ``$in``, ``$nin``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+SUPPORTED_OPS = frozenset({'$eq', '$ne', '$gt', '$gte', '$lt', '$lte', '$in', '$nin'})
+
+logger = logging.getLogger(__name__)
+
+
+def normalize_filter(
+    raw: dict[str, Any] | None,
+) -> list[tuple[str, str, Any]]:
+    """Parse a canonical filter dict into ``[(field, op, value)]`` triples.
+
+    Returns an empty list when *raw* is ``None`` or empty.
+
+    Raises ``ValueError`` on unsupported operators or malformed entries.
+    """
+    if not raw:
+        return []
+
+    triples: list[tuple[str, str, Any]] = []
+    for field, condition in raw.items():
+        if isinstance(condition, dict):
+            for op, value in condition.items():
+                if op not in SUPPORTED_OPS:
+                    raise ValueError(f'Unsupported filter operator: {op}')
+                triples.append((field, op, value))
+        else:
+            # Bare value -> implicit $eq
+            triples.append((field, '$eq', condition))
+    return triples
+
+
+def strip_unsupported_fields(
+    triples: list[tuple[str, str, Any]],
+    supported_fields: set[str],
+) -> list[tuple[str, str, Any]]:
+    """Return only triples whose field is in *supported_fields*.
+
+    Dropped fields are logged at WARNING level so the caller knows they were
+    silently ignored (useful for Milvus / pgvector which only store a fixed
+    schema).
+    """
+    kept: list[tuple[str, str, Any]] = []
+    for field, op, value in triples:
+        if field in supported_fields:
+            kept.append((field, op, value))
+        else:
+            logger.warning(
+                'Filter field %r is not supported by this backend and will be ignored (supported: %s)',
+                field,
+                ', '.join(sorted(supported_fields)),
+            )
+    return kept

src/langbot/pkg/vector/mgr.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from ..core import app
-from .vdb import VectorDatabase
+from .vdb import VectorDatabase, SearchType
 from .vdbs.chroma import ChromaVectorDatabase
 from .vdbs.qdrant import QdrantVectorDatabase
 from .vdbs.seekdb import SeekDBVectorDatabase
@@ -65,3 +65,95 @@ class VectorDBManager:
         else:
             self.vector_db = ChromaVectorDatabase(self.ap)
             self.ap.logger.warning('No vector database backend configured, defaulting to Chroma.')
+
+    def get_supported_search_types(self) -> list[str]:
+        """Return the search types supported by the current VDB backend."""
+        if self.vector_db is None:
+            return [SearchType.VECTOR.value]
+        return [st.value for st in self.vector_db.supported_search_types()]
+
+    async def upsert(
+        self,
+        collection_name: str,
+        vectors: list[list[float]],
+        ids: list[str],
+        metadata: list[dict] | None = None,
+        documents: list[str] | None = None,
+    ):
+        """Proxy: Upsert vectors"""
+        await self.vector_db.add_embeddings(
+            collection=collection_name,
+            ids=ids,
+            embeddings_list=vectors,
+            metadatas=metadata or [{} for _ in vectors],
+            documents=documents,
+        )
+
+    async def search(
+        self,
+        collection_name: str,
+        query_vector: list[float],
+        limit: int,
+        filter: dict | None = None,
+        search_type: str = 'vector',
+        query_text: str = '',
+    ) -> list[dict]:
+        """Proxy: Search vectors.
+
+        Returns a list of dicts with keys: 'id', 'score', 'metadata'.
+        The underlying VectorDatabase.search returns Chroma-style format:
+        { 'ids': [['id1']], 'distances': [[0.1]], 'metadatas': [[{}]] }
+        """
+        results = await self.vector_db.search(
+            collection=collection_name,
+            query_embedding=query_vector,
+            k=limit,
+            search_type=search_type,
+            query_text=query_text,
+            filter=filter,
+        )
+
+        if not results or 'ids' not in results or not results['ids']:
+            return []
+
+        # Flatten nested lists (Chroma returns batch-style: list of lists)
+        raw_ids = results['ids']
+        raw_dists = results.get('distances', [])
+        raw_metas = results.get('metadatas', [])
+
+        r_ids = raw_ids[0] if raw_ids and isinstance(raw_ids[0], list) else raw_ids
+        r_dists = raw_dists[0] if raw_dists and isinstance(raw_dists[0], list) else raw_dists
+        r_metas = raw_metas[0] if raw_metas and isinstance(raw_metas[0], list) else raw_metas
+
+        parsed_results = []
+        for i, id_val in enumerate(r_ids):
+            parsed_results.append(
+                {
+                    'id': id_val,
+                    'score': r_dists[i] if r_dists and i < len(r_dists) else 0.0,
+                    'metadata': r_metas[i] if r_metas and i < len(r_metas) else {},
+                }
+            )
+
+        return parsed_results
+
+    async def delete_by_file_id(self, collection_name: str, file_ids: list[str]):
+        """Proxy: Delete vectors by file_id (metadata-level identifier).
+
+        This delegates to VectorDatabase.delete_by_file_id which removes
+        all vectors associated with the given file IDs.
+        """
+        for file_id in file_ids:
+            await self.vector_db.delete_by_file_id(collection_name, file_id)
+
+    async def delete_collection(self, collection_name: str):
+        """Proxy: Delete an entire collection."""
+        await self.vector_db.delete_collection(collection_name)
+
+    async def delete_by_filter(self, collection_name: str, filter: dict) -> int:
+        """Proxy: Delete vectors by metadata filter.
+
+        Returns:
+            Number of deleted vectors (best-effort; some backends return 0).
+        """
+        return await self.vector_db.delete_by_filter(collection_name, filter)

src/langbot/pkg/vector/vdb.py

@@ -1,10 +1,28 @@
 from __future__ import annotations
 import abc
+import enum
 from typing import Any, Dict
 import numpy as np
 
 
+class SearchType(str, enum.Enum):
+    """Supported search types for vector databases."""
+
+    VECTOR = 'vector'
+    FULL_TEXT = 'full_text'
+    HYBRID = 'hybrid'
+
+
 class VectorDatabase(abc.ABC):
+    @classmethod
+    def supported_search_types(cls) -> list[SearchType]:
+        """Return the search types supported by this VDB backend.
+
+        Default: vector search only. Override in subclasses that support
+        full-text or hybrid search.
+        """
+        return [SearchType.VECTOR]
+
     @abc.abstractmethod
     async def add_embeddings(
         self,
@@ -12,14 +30,47 @@ class VectorDatabase(abc.ABC):
         ids: list[str],
         embeddings_list: list[list[float]],
         metadatas: list[dict[str, Any]],
-        documents: list[str],
+        documents: list[str] | None = None,
     ) -> None:
-        """Add vector data to the specified collection."""
+        """Add vector data to the specified collection.
+
+        Args:
+            collection: Collection name.
+            ids: Unique IDs for each vector.
+            embeddings_list: List of embedding vectors.
+            metadatas: List of metadata dicts.
+            documents: Optional raw text documents. Required for full-text
+                and hybrid search in backends that support them.
+        """
         pass
 
     @abc.abstractmethod
-    async def search(self, collection: str, query_embedding: np.ndarray, k: int = 5) -> Dict[str, Any]:
-        """Search for the most similar vectors in the specified collection."""
+    async def search(
+        self,
+        collection: str,
+        query_embedding: np.ndarray,
+        k: int = 5,
+        search_type: str = 'vector',
+        query_text: str = '',
+        filter: dict[str, Any] | None = None,
+    ) -> Dict[str, Any]:
+        """Search for the most similar vectors in the specified collection.
+
+        Args:
+            collection: Collection name.
+            query_embedding: Query vector for similarity search.
+            k: Number of results to return.
+            search_type: One of 'vector', 'full_text', 'hybrid'.
+            query_text: Raw query text, used for full_text and hybrid search.
+            filter: Optional metadata filters using Chroma-style ``where``
+                syntax.  Multiple top-level keys are AND-ed.  Supported
+                operators: ``$eq``, ``$ne``, ``$gt``, ``$gte``, ``$lt``,
+                ``$lte``, ``$in``, ``$nin``.  Example::
+
+                    {"file_id": "abc"}
+                    {"created_at": {"$gte": 1700000000}}
+                    {"file_type": {"$in": ["pdf", "docx"]}}
+        """
         pass
 
     @abc.abstractmethod
@@ -27,6 +78,20 @@ class VectorDatabase(abc.ABC):
         """Delete vectors from the specified collection by file_id."""
         pass
 
+    @abc.abstractmethod
+    async def delete_by_filter(self, collection: str, filter: dict[str, Any]) -> int:
+        """Delete vectors matching the given metadata filter.
+
+        Args:
+            collection: Collection name.
+            filter: Metadata filter dict in canonical format (see ``search``).
+
+        Returns:
+            Number of deleted vectors (best-effort; backends that cannot
+            report an exact count may return 0).
+        """
+        pass
+
     @abc.abstractmethod
     async def get_or_create_collection(self, collection: str):
         """Get or create collection."""

src/langbot/pkg/vector/vdbs/chroma.py

@@ -2,11 +2,14 @@ from __future__ import annotations
 import asyncio
 from typing import Any
 from chromadb import PersistentClient
-from langbot.pkg.vector.vdb import VectorDatabase
+from langbot.pkg.vector.vdb import VectorDatabase, SearchType
 from langbot.pkg.core import app
 import chromadb
 import chromadb.errors
 
+# RRF smoothing constant (standard value from the literature)
+_RRF_K = 60
+
 
 class ChromaVectorDatabase(VectorDatabase):
     def __init__(self, ap: app.Application, base_path: str = './data/chroma'):
@@ -14,6 +17,10 @@ class ChromaVectorDatabase(VectorDatabase):
         self.client = PersistentClient(path=base_path)
         self._collections = {}
 
+    @classmethod
+    def supported_search_types(cls) -> list[SearchType]:
+        return [SearchType.VECTOR, SearchType.FULL_TEXT, SearchType.HYBRID]
+
     async def get_or_create_collection(self, collection: str) -> chromadb.Collection:
         if collection not in self._collections:
             self._collections[collection] = await asyncio.to_thread(
@@ -28,27 +35,192 @@ class ChromaVectorDatabase(VectorDatabase):
         ids: list[str],
         embeddings_list: list[list[float]],
         metadatas: list[dict[str, Any]],
+        documents: list[str] | None = None,
     ) -> None:
         col = await self.get_or_create_collection(collection)
-        await asyncio.to_thread(col.add, embeddings=embeddings_list, ids=ids, metadatas=metadatas)
-        self.ap.logger.info(f"Added {len(ids)} embeddings to Chroma collection '{collection}'.")
+        kwargs: dict[str, Any] = dict(embeddings=embeddings_list, ids=ids, metadatas=metadatas)
+        if documents is not None:
+            kwargs['documents'] = documents
+        await asyncio.to_thread(col.upsert, **kwargs)
+        self.ap.logger.info(f"Upserted {len(ids)} embeddings to Chroma collection '{collection}'.")
 
-    async def search(self, collection: str, query_embedding: list[float], k: int = 5) -> dict[str, Any]:
+    async def search(
+        self,
+        collection: str,
+        query_embedding: list[float],
+        k: int = 5,
+        search_type: str = 'vector',
+        query_text: str = '',
+        filter: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
         col = await self.get_or_create_collection(collection)
-        results = await asyncio.to_thread(
-            col.query,
+
+        if search_type == SearchType.FULL_TEXT:
+            return await self._full_text_search(col, collection, k, query_text, filter)
+        elif search_type == SearchType.HYBRID:
+            return await self._hybrid_search(col, collection, query_embedding, k, query_text, filter)
+
+        # Default: vector search
+        return await self._vector_search(col, collection, query_embedding, k, filter)
+
+    async def _vector_search(
+        self,
+        col: chromadb.Collection,
+        collection: str,
+        query_embedding: list[float],
+        k: int,
+        filter: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        query_kwargs: dict[str, Any] = dict(
             query_embeddings=query_embedding,
             n_results=k,
             include=['metadatas', 'distances', 'documents'],
         )
-        self.ap.logger.info(f"Chroma search in '{collection}' returned {len(results.get('ids', [[]])[0])} results.")
+        if filter:
+            query_kwargs['where'] = filter
+        results = await asyncio.to_thread(col.query, **query_kwargs)
+        self.ap.logger.info(
+            f"Chroma vector search in '{collection}' returned {len(results.get('ids', [[]])[0])} results."
+        )
         return results
 
+    async def _full_text_search(
+        self,
+        col: chromadb.Collection,
+        collection: str,
+        k: int,
+        query_text: str,
+        filter: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        if not query_text:
+            return {'ids': [[]], 'metadatas': [[]], 'distances': [[]], 'documents': [[]]}
+
+        get_kwargs: dict[str, Any] = dict(
+            where_document={'$contains': query_text},
+            include=['metadatas', 'documents'],
+            limit=k,
+        )
+        if filter:
+            get_kwargs['where'] = filter
+        results = await asyncio.to_thread(col.get, **get_kwargs)
+
+        # col.get returns flat lists; wrap into column-major format.
+        # Distances are all 0.0 because Chroma's local $contains is a boolean
+        # filter with no relevance scoring.  Chroma's BM25 sparse embedding
+        # function (ChromaBm25EmbeddingFunction) can generate scored sparse
+        # vectors, but sparse vector *indexing* is only available on Chroma
+        # Cloud, not locally.  For ranked results, use hybrid mode or apply a
+        # reranker in a downstream stage.
+        ids = results.get('ids', [])
+        metadatas = results.get('metadatas', []) or [None] * len(ids)
+        documents = results.get('documents', []) or [None] * len(ids)
+        distances = [0.0] * len(ids)
+
+        self.ap.logger.info(f"Chroma full-text search in '{collection}' returned {len(ids)} results.")
+        return {'ids': [ids], 'metadatas': [metadatas], 'distances': [distances], 'documents': [documents]}
+
+    async def _hybrid_search(
+        self,
+        col: chromadb.Collection,
+        collection: str,
+        query_embedding: list[float],
+        k: int,
+        query_text: str,
+        filter: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        # Fall back to pure vector search when no text is provided
+        if not query_text:
+            return await self._vector_search(col, collection, query_embedding, k, filter)
+
+        # Run vector search and full-text search in parallel
+        vector_task = self._vector_search(col, collection, query_embedding, k, filter)
+        text_task = self._full_text_search(col, collection, k, query_text, filter)
+        vector_results, text_results = await asyncio.gather(vector_task, text_task)
+
+        vector_ids = vector_results.get('ids', [[]])[0]
+        text_ids = text_results.get('ids', [[]])[0]
+
+        if not vector_ids and not text_ids:
+            return {'ids': [[]], 'metadatas': [[]], 'distances': [[]], 'documents': [[]]}
+
+        # RRF fusion
+        fused = self._rrf_fuse([vector_ids, text_ids], k)
+        if not fused:
+            return {'ids': [[]], 'metadatas': [[]], 'distances': [[]], 'documents': [[]]}
+
+        fused_ids = [doc_id for doc_id, _ in fused]
+
+        # Fetch full metadata and documents for fused results
+        fetched = await asyncio.to_thread(col.get, ids=fused_ids, include=['metadatas', 'documents'])
+
+        # col.get returns results in arbitrary order; re-order to match fused ranking
+        fetched_map: dict[str, tuple] = {}
+        for i, fid in enumerate(fetched.get('ids', [])):
+            meta = (fetched.get('metadatas') or [None] * len(fetched['ids']))[i]
+            doc = (fetched.get('documents') or [None] * len(fetched['ids']))[i]
+            fetched_map[fid] = (meta, doc)
+
+        ordered_ids = []
+        ordered_metas = []
+        ordered_docs = []
+        ordered_dists = []
+
+        # Normalize RRF scores to 0~1 distances via min-max scaling.
+        # Raw RRF scores are tiny (e.g. 0.016~0.033 with k=60) so a naive
+        # ``1 - score`` would compress all distances into a narrow 0.96~0.98
+        # band with almost no discriminative power.  Min-max normalization
+        # spreads them across the full 0~1 range (0.0 = best match).
+        max_score = fused[0][1]
+        min_score = fused[-1][1]
+        score_range = max_score - min_score
+
+        for doc_id, score in fused:
+            if doc_id in fetched_map:
+                meta, doc = fetched_map[doc_id]
+                ordered_ids.append(doc_id)
+                ordered_metas.append(meta)
+                ordered_docs.append(doc)
+                if score_range > 0:
+                    ordered_dists.append(1.0 - (score - min_score) / score_range)
+                else:
+                    ordered_dists.append(0.0)
+
+        self.ap.logger.info(
+            f"Chroma hybrid search in '{collection}' returned {len(ordered_ids)} results "
+            f'(vector={len(vector_ids)}, text={len(text_ids)}).'
+        )
+        return {
+            'ids': [ordered_ids],
+            'metadatas': [ordered_metas],
+            'distances': [ordered_dists],
+            'documents': [ordered_docs],
+        }
+
+    @staticmethod
+    def _rrf_fuse(result_lists: list[list[str]], k: int) -> list[tuple[str, float]]:
+        """Reciprocal Rank Fusion over multiple ranked ID lists.
+
+        Returns a list of (doc_id, rrf_score) sorted by descending score,
+        truncated to *k* entries.
+        """
+        scores: dict[str, float] = {}
+        for ranked_ids in result_lists:
+            for rank, doc_id in enumerate(ranked_ids):
+                scores[doc_id] = scores.get(doc_id, 0.0) + 1.0 / (_RRF_K + rank + 1)
+        sorted_results = sorted(scores.items(), key=lambda x: x[1], reverse=True)
+        return sorted_results[:k]
+
     async def delete_by_file_id(self, collection: str, file_id: str) -> None:
         col = await self.get_or_create_collection(collection)
         await asyncio.to_thread(col.delete, where={'file_id': file_id})
         self.ap.logger.info(f"Deleted embeddings from Chroma collection '{collection}' with file_id: {file_id}")
 
+    async def delete_by_filter(self, collection: str, filter: dict[str, Any]) -> int:
+        col = await self.get_or_create_collection(collection)
+        await asyncio.to_thread(col.delete, where=filter)
+        self.ap.logger.info(f"Deleted embeddings from Chroma collection '{collection}' by filter")
+        return 0  # Chroma delete does not return a count
+
     async def delete_collection(self, collection: str):
         if collection in self._collections:
             del self._collections[collection]

src/langbot/pkg/vector/vdbs/milvus.py

@@ -4,8 +4,51 @@ from typing import Any, Dict
 from pymilvus import MilvusClient, DataType, CollectionSchema, FieldSchema
 from pymilvus.milvus_client.index import IndexParams
 from langbot.pkg.vector.vdb import VectorDatabase
+from langbot.pkg.vector.filter_utils import normalize_filter, strip_unsupported_fields
 from langbot.pkg.core import app
 
+# Milvus schema only stores these metadata fields; filter on other fields is
+# silently dropped with a warning.
+_MILVUS_SUPPORTED_FIELDS = {'text', 'file_id', 'chunk_uuid'}
+
+
+def _build_milvus_expr(filter_dict: dict[str, Any]) -> str:
+    """Translate canonical filter dict into a Milvus boolean expression string."""
+    triples = normalize_filter(filter_dict)
+    triples = strip_unsupported_fields(triples, _MILVUS_SUPPORTED_FIELDS)
+    if not triples:
+        return ''
+
+    parts: list[str] = []
+    for field, op, value in triples:
+        if op == '$eq':
+            parts.append(f'{field} == {_milvus_literal(value)}')
+        elif op == '$ne':
+            parts.append(f'{field} != {_milvus_literal(value)}')
+        elif op == '$gt':
+            parts.append(f'{field} > {_milvus_literal(value)}')
+        elif op == '$gte':
+            parts.append(f'{field} >= {_milvus_literal(value)}')
+        elif op == '$lt':
+            parts.append(f'{field} < {_milvus_literal(value)}')
+        elif op == '$lte':
+            parts.append(f'{field} <= {_milvus_literal(value)}')
+        elif op == '$in':
+            items = ', '.join(_milvus_literal(v) for v in value)
+            parts.append(f'{field} in [{items}]')
+        elif op == '$nin':
+            items = ', '.join(_milvus_literal(v) for v in value)
+            parts.append(f'{field} not in [{items}]')
+    return ' and '.join(parts)
+
+
+def _milvus_literal(value: Any) -> str:
+    """Format a Python value as a Milvus expression literal."""
+    if isinstance(value, str):
+        escaped = value.replace('\\', '\\\\').replace('"', '\\"')
+        return f'"{escaped}"'
+    return str(value)
+
 
 class MilvusVectorDatabase(VectorDatabase):
     """Milvus vector database implementation"""
@@ -155,6 +198,7 @@ class MilvusVectorDatabase(VectorDatabase):
         ids: list[str],
         embeddings_list: list[list[float]],
         metadatas: list[dict[str, Any]],
+        documents: list[str] | None = None,
     ) -> None:
         """Add vector embeddings to Milvus collection
 
@@ -200,7 +244,15 @@ class MilvusVectorDatabase(VectorDatabase):
 
         self.ap.logger.info(f"Added {len(ids)} embeddings to Milvus collection '{collection}'")
 
-    async def search(self, collection: str, query_embedding: list[float], k: int = 5) -> Dict[str, Any]:
+    async def search(
+        self,
+        collection: str,
+        query_embedding: list[float],
+        k: int = 5,
+        search_type: str = 'vector',
+        query_text: str = '',
+        filter: dict[str, Any] | None = None,
+    ) -> Dict[str, Any]:
         """Search for similar vectors in Milvus collection
 
         Args:
@@ -217,14 +269,19 @@ class MilvusVectorDatabase(VectorDatabase):
         # Perform search
         search_params = {'metric_type': 'COSINE', 'params': {}}
 
-        results = await asyncio.to_thread(
-            self.client.search,
+        search_kwargs: dict[str, Any] = dict(
             collection_name=collection,
             data=[query_embedding],
             limit=k,
             search_params=search_params,
             output_fields=['text', 'file_id', 'chunk_uuid'],
         )
+        if filter:
+            expr = _build_milvus_expr(filter)
+            if expr:
+                search_kwargs['filter'] = expr
+
+        results = await asyncio.to_thread(self.client.search, **search_kwargs)
 
         # Convert results to Chroma-compatible format
         # Milvus returns: [[ {id, distance, entity: {...}} ]]
@@ -268,6 +325,21 @@ class MilvusVectorDatabase(VectorDatabase):
         await asyncio.to_thread(self.client.delete, collection_name=collection, filter=f'file_id == "{file_id}"')
         self.ap.logger.info(f"Deleted embeddings from Milvus collection '{collection}' with file_id: {file_id}")
 
+    async def delete_by_filter(self, collection: str, filter: dict[str, Any]) -> int:
+        collection = self._normalize_collection_name(collection)
+        await self.get_or_create_collection(collection)
+
+        expr = _build_milvus_expr(filter)
+        if not expr:
+            self.ap.logger.warning(
+                f"Milvus delete_by_filter on '{collection}': filter produced empty expression, skipping"
+            )
+            return 0
+
+        await asyncio.to_thread(self.client.delete, collection_name=collection, filter=expr)
+        self.ap.logger.info(f"Deleted embeddings from Milvus collection '{collection}' by filter")
+        return 0  # Milvus delete does not return a count
+
     async def delete_collection(self, collection: str):
         """Delete a Milvus collection
 

src/langbot/pkg/vector/vdbs/pgvector_db.py

@@ -5,10 +5,21 @@ from sqlalchemy.orm import declarative_base
 from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
 from pgvector.sqlalchemy import Vector
 from langbot.pkg.vector.vdb import VectorDatabase
+from langbot.pkg.vector.filter_utils import normalize_filter, strip_unsupported_fields
 from langbot.pkg.core import app
 
 Base = declarative_base()
 
+# pgvector schema only stores these metadata fields.
+_PG_SUPPORTED_FIELDS = {'text', 'file_id', 'chunk_uuid'}
+
+# Map schema field names to SQLAlchemy columns (resolved lazily from PgVectorEntry).
+_PG_COLUMN_MAP = {
+    'text': 'text',
+    'file_id': 'file_id',
+    'chunk_uuid': 'chunk_uuid',
+}
+
 
 class PgVectorEntry(Base):
     """SQLAlchemy model for pgvector entries"""
@@ -23,6 +34,33 @@ class PgVectorEntry(Base):
     chunk_uuid = Column(String)
 
 
+def _build_pg_conditions(filter_dict: dict[str, Any]) -> list:
+    """Translate canonical filter dict into a list of SQLAlchemy conditions."""
+    triples = normalize_filter(filter_dict)
+    triples = strip_unsupported_fields(triples, _PG_SUPPORTED_FIELDS)
+
+    conditions = []
+    for field, op, value in triples:
+        col = getattr(PgVectorEntry, _PG_COLUMN_MAP[field])
+        if op == '$eq':
+            conditions.append(col == value)
+        elif op == '$ne':
+            conditions.append(col != value)
+        elif op == '$gt':
+            conditions.append(col > value)
+        elif op == '$gte':
+            conditions.append(col >= value)
+        elif op == '$lt':
+            conditions.append(col < value)
+        elif op == '$lte':
+            conditions.append(col <= value)
+        elif op == '$in':
+            conditions.append(col.in_(value))
+        elif op == '$nin':
+            conditions.append(col.notin_(value))
+    return conditions
+
+
 class PgVectorDatabase(VectorDatabase):
     """PostgreSQL with pgvector extension database implementation"""
 
@@ -109,6 +147,7 @@ class PgVectorDatabase(VectorDatabase):
         ids: list[str],
         embeddings_list: list[list[float]],
         metadatas: list[dict[str, Any]],
+        documents: list[str] | None = None,
     ) -> None:
         """Add vector embeddings to pgvector
 
@@ -142,7 +181,15 @@ class PgVectorDatabase(VectorDatabase):
                 self.ap.logger.error(f'Error adding embeddings to pgvector: {e}')
                 raise
 
-    async def search(self, collection: str, query_embedding: list[float], k: int = 5) -> Dict[str, Any]:
+    async def search(
+        self,
+        collection: str,
+        query_embedding: list[float],
+        k: int = 5,
+        search_type: str = 'vector',
+        query_text: str = '',
+        filter: dict[str, Any] | None = None,
+    ) -> Dict[str, Any]:
         """Search for similar vectors using cosine distance
 
         Args:
@@ -174,6 +221,10 @@ class PgVectorDatabase(VectorDatabase):
                     .limit(k)
                 )
 
+                if filter:
+                    for cond in _build_pg_conditions(filter):
+                        stmt = stmt.filter(cond)
+
                 result = await session.execute(stmt)
                 rows = result.fetchall()
 
@@ -225,6 +276,39 @@ class PgVectorDatabase(VectorDatabase):
                 self.ap.logger.error(f'Error deleting from pgvector: {e}')
                 raise
 
+    async def delete_by_filter(self, collection: str, filter: dict[str, Any]) -> int:
+        """Delete vectors matching a metadata filter.
+
+        Args:
+            collection: Collection name
+            filter: Canonical metadata filter dict
+        """
+        conditions = _build_pg_conditions(filter)
+        if not conditions:
+            self.ap.logger.warning(
+                f"pgvector delete_by_filter on '{collection}': filter produced no conditions, skipping"
+            )
+            return 0
+
+        await self.get_or_create_collection(collection)
+
+        async with self.AsyncSessionLocal() as session:
+            try:
+                from sqlalchemy import delete
+
+                stmt = delete(PgVectorEntry).where(PgVectorEntry.collection == collection)
+                for cond in conditions:
+                    stmt = stmt.where(cond)
+                result = await session.execute(stmt)
+                await session.commit()
+                deleted = result.rowcount
+                self.ap.logger.info(f"Deleted {deleted} embeddings from pgvector collection '{collection}' by filter")
+                return deleted
+            except Exception as e:
+                await session.rollback()
+                self.ap.logger.error(f'Error deleting from pgvector by filter: {e}')
+                raise
+
     async def delete_collection(self, collection: str):
         """Delete all vectors in a collection
 

src/langbot/pkg/vector/vdbs/qdrant.py

@@ -5,6 +5,37 @@ from typing import Any, Dict, List
 from qdrant_client import AsyncQdrantClient, models
 from langbot.pkg.core import app
 from langbot.pkg.vector.vdb import VectorDatabase
+from langbot.pkg.vector.filter_utils import normalize_filter
+
+
+def _build_qdrant_filter(filter_dict: dict[str, Any]) -> models.Filter:
+    """Translate canonical filter dict into a Qdrant ``models.Filter``."""
+    triples = normalize_filter(filter_dict)
+    must: list[models.Condition] = []
+    must_not: list[models.Condition] = []
+
+    for field, op, value in triples:
+        if op == '$eq':
+            must.append(models.FieldCondition(key=field, match=models.MatchValue(value=value)))
+        elif op == '$ne':
+            must_not.append(models.FieldCondition(key=field, match=models.MatchValue(value=value)))
+        elif op == '$in':
+            must.append(models.FieldCondition(key=field, match=models.MatchAny(any=value)))
+        elif op == '$nin':
+            must_not.append(models.FieldCondition(key=field, match=models.MatchAny(any=value)))
+        elif op in ('$gt', '$gte', '$lt', '$lte'):
+            range_kwargs: dict[str, Any] = {}
+            if op == '$gt':
+                range_kwargs['gt'] = value
+            elif op == '$gte':
+                range_kwargs['gte'] = value
+            elif op == '$lt':
+                range_kwargs['lt'] = value
+            elif op == '$lte':
+                range_kwargs['lte'] = value
+            must.append(models.FieldCondition(key=field, range=models.Range(**range_kwargs)))
+
+    return models.Filter(must=must or None, must_not=must_not or None)
 
 
 class QdrantVectorDatabase(VectorDatabase):
@@ -48,6 +79,7 @@ class QdrantVectorDatabase(VectorDatabase):
         ids: List[str],
         embeddings_list: List[List[float]],
         metadatas: List[Dict[str, Any]],
+        documents: List[str] | None = None,
     ) -> None:
         if not embeddings_list:
             return
@@ -60,19 +92,29 @@ class QdrantVectorDatabase(VectorDatabase):
         await self.client.upsert(collection_name=collection, points=points)
         self.ap.logger.info(f"Added {len(ids)} embeddings to Qdrant collection '{collection}'.")
 
-    async def search(self, collection: str, query_embedding: list[float], k: int = 5) -> dict[str, Any]:
+    async def search(
+        self,
+        collection: str,
+        query_embedding: list[float],
+        k: int = 5,
+        search_type: str = 'vector',
+        query_text: str = '',
+        filter: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
         exists = await self.client.collection_exists(collection)
         if not exists:
             return {'ids': [[]], 'metadatas': [[]], 'distances': [[]]}
 
-        hits = (
-            await self.client.query_points(
-                collection_name=collection,
-                query=query_embedding,
-                limit=k,
-                with_payload=True,
-            )
-        ).points
+        query_kwargs: dict[str, Any] = dict(
+            collection_name=collection,
+            query=query_embedding,
+            limit=k,
+            with_payload=True,
+        )
+        if filter:
+            query_kwargs['query_filter'] = _build_qdrant_filter(filter)
+
+        hits = (await self.client.query_points(**query_kwargs)).points
         ids = [str(hit.id) for hit in hits]
         metadatas = [hit.payload or {} for hit in hits]
         # Qdrant's score is similarity; convert to a pseudo-distance for consistency
@@ -95,6 +137,19 @@ class QdrantVectorDatabase(VectorDatabase):
         )
         self.ap.logger.info(f"Deleted embeddings from Qdrant collection '{collection}' with file_id: {file_id}")
 
+    async def delete_by_filter(self, collection: str, filter: dict[str, Any]) -> int:
+        exists = await self.client.collection_exists(collection)
+        if not exists:
+            return 0
+
+        qdrant_filter = _build_qdrant_filter(filter)
+        await self.client.delete(
+            collection_name=collection,
+            points_selector=qdrant_filter,
+        )
+        self.ap.logger.info(f"Deleted embeddings from Qdrant collection '{collection}' by filter")
+        return 0  # Qdrant delete does not return a count
+
     async def delete_collection(self, collection: str):
         try:
             await self.client.delete_collection(collection)

src/langbot/pkg/vector/vdbs/seekdb.py

@@ -5,7 +5,7 @@ from typing import Any, Dict, List
 
 
 from langbot.pkg.core import app
-from langbot.pkg.vector.vdb import VectorDatabase
+from langbot.pkg.vector.vdb import VectorDatabase, SearchType
 
 try:
     import pyseekdb
@@ -25,9 +25,13 @@ class SeekDBVectorDatabase(VectorDatabase):
     SeekDB is an AI-native search database by OceanBase that unifies
     relational, vector, text, JSON and GIS in a single engine.
 
-    Supports both embedded mode and remote server mode.
+    Supports embedded mode, remote server mode, and full-text/hybrid search.
     """
 
+    @classmethod
+    def supported_search_types(cls) -> list[SearchType]:
+        return [SearchType.VECTOR, SearchType.FULL_TEXT, SearchType.HYBRID]
+
     def __init__(self, ap: app.Application):
         if not SEEKDB_AVAILABLE:
             raise ImportError('pyseekdb is not installed. Install it with: pip install pyseekdb')
@@ -89,6 +93,7 @@ class SeekDBVectorDatabase(VectorDatabase):
             {
                 '\x00': '',
                 '\\': '\\\\',
+                "'": "''",  # Standard SQL escaping (OceanBase NO_BACKSLASH_ESCAPES)
                 '"': '\\"',
                 '\n': '\\n',
                 '\r': '\\r',
@@ -111,8 +116,10 @@ class SeekDBVectorDatabase(VectorDatabase):
 
         # Collection doesn't exist, create it
         if vector_size is None:
-            # Default dimension if not specified
-            vector_size = 384
+            raise ValueError(
+                f"Cannot create SeekDB collection '{collection}' without knowing the vector dimension. "
+                'Ensure add_embeddings is called before any standalone get_or_create_collection.'
+            )
 
         # Create HNSW configuration
         config = HNSWConfiguration(dimension=vector_size, distance='cosine')
@@ -147,7 +154,12 @@ class SeekDBVectorDatabase(VectorDatabase):
         return await self._get_or_create_collection_internal(collection)
 
     async def add_embeddings(
-        self, collection: str, ids: List[str], embeddings_list: List[List[float]], metadatas: List[Dict[str, Any]]
+        self,
+        collection: str,
+        ids: List[str],
+        embeddings_list: List[List[float]],
+        metadatas: List[Dict[str, Any]],
+        documents: List[str] | None = None,
     ) -> None:
         """Add vector embeddings to the specified collection.
 
@@ -156,6 +168,7 @@ class SeekDBVectorDatabase(VectorDatabase):
             ids: List of document IDs
             embeddings_list: List of embedding vectors
             metadatas: List of metadata dictionaries
+            documents: Optional raw text documents for full-text search support
         """
         if not embeddings_list:
             return
@@ -166,17 +179,33 @@ class SeekDBVectorDatabase(VectorDatabase):
 
         cleaned_metadatas = [self._clean_metadata(meta) for meta in metadatas]
 
-        await asyncio.to_thread(coll.add, ids=ids, embeddings=embeddings_list, metadatas=cleaned_metadatas)
+        kwargs: Dict[str, Any] = dict(ids=ids, embeddings=embeddings_list, metadatas=cleaned_metadatas)
+        if documents is not None:
+            kwargs['documents'] = [doc.translate(self._escape_table) for doc in documents]
+        await asyncio.to_thread(coll.add, **kwargs)
 
         self.ap.logger.info(f"Added {len(ids)} embeddings to SeekDB collection '{collection}'")
 
-    async def search(self, collection: str, query_embedding: List[float], k: int = 5) -> Dict[str, Any]:
+    async def search(
+        self,
+        collection: str,
+        query_embedding: List[float],
+        k: int = 5,
+        search_type: str = 'vector',
+        query_text: str = '',
+        filter: Dict[str, Any] | None = None,
+    ) -> Dict[str, Any]:
         """Search for the most similar vectors in the specified collection.
 
+        SeekDB supports vector, full-text, and hybrid search modes.
+
         Args:
             collection: Collection name
-            query_embedding: Query vector
+            query_embedding: Query vector (used for vector and hybrid modes)
             k: Number of results to return
+            search_type: One of 'vector', 'full_text', 'hybrid'
+            query_text: Raw query text (used for full_text and hybrid modes)
+            filter: Optional metadata filters (Chroma-style ``where`` syntax).
 
         Returns:
             Dictionary with 'ids', 'metadatas', 'distances' keys
@@ -193,11 +222,73 @@ class SeekDBVectorDatabase(VectorDatabase):
         else:
             coll = self._collections[collection]
 
-        # Perform query
-        # SeekDB's query() returns: {'ids': [[...]], 'metadatas': [[...]], 'distances': [[...]]}
-        results = await asyncio.to_thread(coll.query, query_embeddings=query_embedding, n_results=k)
+        # Route by search type.
+        # pyseekdb's query() always requires embeddings, so full-text and
+        # hybrid modes use hybrid_search() which supports text-only queries
+        # and returns the same nested-list format with distances.
+        if search_type == SearchType.FULL_TEXT:
+            if not query_text:
+                return {'ids': [[]], 'metadatas': [[]], 'distances': [[]]}
 
-        self.ap.logger.info(f"SeekDB search in '{collection}' returned {len(results.get('ids', [[]])[0])} results")
+            query_cfg: Dict[str, Any] = {
+                'where_document': {'$contains': query_text},
+                'n_results': k,
+            }
+            if filter:
+                query_cfg['where'] = filter
+
+            # TODO: pyseekdb hybrid_search with query-only (no knn) returns None
+            # for IDs due to column name mismatch (*/_id vs _id).
+            # See: https://github.com/oceanbase/pyseekdb/issues/171
+            results = await asyncio.to_thread(
+                coll.hybrid_search,
+                query=query_cfg,
+                knn=None,
+                n_results=k,
+                include=['documents', 'metadatas'],
+            )
+
+        elif search_type == SearchType.HYBRID:
+            if not query_text:
+                # Fall back to pure vector search when no text is provided
+                query_kwargs: Dict[str, Any] = {
+                    'n_results': k,
+                    'query_embeddings': query_embedding,
+                }
+                if filter:
+                    query_kwargs['where'] = filter
+                results = await asyncio.to_thread(coll.query, **query_kwargs)
+            else:
+                query_cfg = {
+                    'where_document': {'$contains': query_text},
+                    'n_results': k,
+                }
+                knn_cfg: Dict[str, Any] = {
+                    'query_embeddings': query_embedding,
+                    'n_results': k,
+                }
+                if filter:
+                    query_cfg['where'] = filter
+                    knn_cfg['where'] = filter
+
+                results = await asyncio.to_thread(
+                    coll.hybrid_search,
+                    query=query_cfg,
+                    knn=knn_cfg,
+                    rank={'rrf': {}},
+                    n_results=k,
+                    include=['documents', 'metadatas'],
+                )
+        else:
+            # Default: vector search via query()
+            query_kwargs = {'n_results': k, 'query_embeddings': query_embedding}
+            if filter:
+                query_kwargs['where'] = filter
+            results = await asyncio.to_thread(coll.query, **query_kwargs)
+
+        self.ap.logger.info(
+            f"SeekDB {search_type} search in '{collection}' returned {len(results.get('ids', [[]])[0])} results"
+        )
 
         return results
 
@@ -227,6 +318,28 @@ class SeekDBVectorDatabase(VectorDatabase):
 
         self.ap.logger.info(f"Deleted embeddings from SeekDB collection '{collection}' with file_id: {file_id}")
 
+    async def delete_by_filter(self, collection: str, filter: Dict[str, Any]) -> int:
+        """Delete vectors from the collection by metadata filter.
+
+        Args:
+            collection: Collection name
+            filter: Chroma-style ``where`` filter dict
+        """
+        exists = await asyncio.to_thread(self.client.has_collection, collection)
+        if not exists:
+            self.ap.logger.warning(f"SeekDB collection '{collection}' not found for deletion")
+            return 0
+
+        if collection not in self._collections:
+            coll = await asyncio.to_thread(self.client.get_collection, collection, embedding_function=None)
+            self._collections[collection] = coll
+        else:
+            coll = self._collections[collection]
+
+        await asyncio.to_thread(coll.delete, where=filter)
+        self.ap.logger.info(f"Deleted embeddings from SeekDB collection '{collection}' by filter")
+        return 0  # SeekDB delete does not return a count
+
     async def delete_collection(self, collection: str):
         """Delete the entire collection.
 

src/langbot/templates/default-pipeline-config.json

@@ -95,11 +95,12 @@
             "max": 0
         },
         "misc": {
-            "hide-exception": true,
+            "exception-handling": "show-hint",
+            "failure-hint": "Request failed.",
             "at-sender": true,
             "quote-origin": true,
             "track-function-calls": false,
             "remove-think": false
         }
     }
-}
+}

src/langbot/templates/metadata/pipeline/output.yaml

@@ -78,13 +78,39 @@ stages:
       en_US: Misc
       zh_Hans: 杂项
     config:
-      - name: hide-exception
+      - name: exception-handling
         label:
-          en_US: Hide Exception
-          zh_Hans: 不输出异常信息给用户
-        type: boolean
+          en_US: Exception Handling Strategy
+          zh_Hans: 异常处理策略
+        description:
+          en_US: Controls how error messages are displayed to the user when an AI request fails
+          zh_Hans: 控制 AI 请求失败时向用户展示错误信息的方式
+        type: select
         required: true
-        default: true
+        default: show-hint
+        options:
+          - name: show-error
+            label:
+              en_US: Show Full Error
+              zh_Hans: 显示完整报错信息
+          - name: show-hint
+            label:
+              en_US: Show Failure Hint
+              zh_Hans: 仅文字提示
+          - name: hide
+            label:
+              en_US: Hide All
+              zh_Hans: 不显示任何异常信息
+      - name: failure-hint
+        label:
+          en_US: Failure Hint Text
+          zh_Hans: 失败提示文本
+        description:
+          en_US: The text to display when a request fails. Only effective when Exception Handling Strategy is set to "Show Failure Hint"
+          zh_Hans: 请求失败时显示的提示文本，仅在异常处理策略设置为"仅文字提示"时生效
+        type: string
+        required: false
+        default: 'Request failed.'
       - name: at-sender
         label:
           en_US: At Sender
@@ -119,3 +145,4 @@ stages:
         type: boolean
         required: true
         default: false
+

tests/unit_tests/pipeline/test_config_coercion.py

@@ -0,0 +1,113 @@
+"""Unit tests for config_coercion module"""
+
+from __future__ import annotations
+
+import pytest
+
+from langbot.pkg.pipeline.config_coercion import _coerce_value, coerce_pipeline_config
+
+
+class TestCoerceValue:
+    """Tests for _coerce_value function"""
+
+    def test_none_passthrough(self):
+        assert _coerce_value(None, 'integer') is None
+        assert _coerce_value(None, 'boolean') is None
+
+    def test_string_to_integer(self):
+        assert _coerce_value('120', 'integer') == 120
+        assert _coerce_value('0', 'integer') == 0
+        assert _coerce_value('-5', 'integer') == -5
+
+    def test_integer_passthrough(self):
+        assert _coerce_value(42, 'integer') == 42
+
+    def test_string_to_float(self):
+        assert _coerce_value('3.14', 'number') == 3.14
+        assert _coerce_value('3.14', 'float') == 3.14
+
+    def test_int_to_float(self):
+        assert _coerce_value(3, 'number') == 3.0
+        assert isinstance(_coerce_value(3, 'number'), float)
+
+    def test_float_passthrough(self):
+        assert _coerce_value(3.14, 'float') == 3.14
+
+    def test_string_to_bool(self):
+        assert _coerce_value('true', 'boolean') is True
+        assert _coerce_value('True', 'boolean') is True
+        assert _coerce_value('false', 'boolean') is False
+        assert _coerce_value('False', 'boolean') is False
+
+    def test_bool_passthrough(self):
+        assert _coerce_value(True, 'boolean') is True
+        assert _coerce_value(False, 'boolean') is False
+
+    def test_invalid_bool_string_raises(self):
+        with pytest.raises(ValueError):
+            _coerce_value('notabool', 'boolean')
+
+    def test_unknown_type_passthrough(self):
+        assert _coerce_value('hello', 'string') == 'hello'
+        assert _coerce_value('hello', 'unknown') == 'hello'
+
+    def test_invalid_integer_raises(self):
+        with pytest.raises(ValueError):
+            _coerce_value('abc', 'integer')
+
+
+class TestCoercePipelineConfig:
+    """Tests for coerce_pipeline_config function"""
+
+    def _make_meta(self, section_name: str, stage_name: str, fields: list[dict]) -> dict:
+        return {
+            'name': section_name,
+            'stages': [{'name': stage_name, 'config': fields}],
+        }
+
+    def test_coerce_integer_in_config(self):
+        config = {'trigger': {'misc': {'timeout': '120'}}}
+        meta = self._make_meta('trigger', 'misc', [{'name': 'timeout', 'type': 'integer'}])
+        coerce_pipeline_config(config, meta)
+        assert config['trigger']['misc']['timeout'] == 120
+
+    def test_coerce_boolean_in_config(self):
+        config = {'output': {'misc': {'at-sender': 'true'}}}
+        meta = self._make_meta('output', 'misc', [{'name': 'at-sender', 'type': 'boolean'}])
+        coerce_pipeline_config(config, meta)
+        assert config['output']['misc']['at-sender'] is True
+
+    def test_missing_section_skipped(self):
+        config = {'ai': {}}
+        meta = self._make_meta('trigger', 'misc', [{'name': 'x', 'type': 'integer'}])
+        coerce_pipeline_config(config, meta)  # should not raise
+
+    def test_missing_field_skipped(self):
+        config = {'trigger': {'misc': {}}}
+        meta = self._make_meta('trigger', 'misc', [{'name': 'nonexistent', 'type': 'integer'}])
+        coerce_pipeline_config(config, meta)  # should not raise
+
+    def test_invalid_value_logs_warning(self, caplog):
+        config = {'trigger': {'misc': {'timeout': 'abc'}}}
+        meta = self._make_meta('trigger', 'misc', [{'name': 'timeout', 'type': 'integer'}])
+        import logging
+
+        with caplog.at_level(logging.WARNING):
+            coerce_pipeline_config(config, meta)
+        assert config['trigger']['misc']['timeout'] == 'abc'  # unchanged
+        assert 'Failed to coerce' in caplog.text
+
+    def test_empty_metadata(self):
+        config = {'trigger': {'misc': {'timeout': '120'}}}
+        coerce_pipeline_config(config)  # no metadata args, should not raise
+
+    def test_multiple_metadata(self):
+        config = {
+            'trigger': {'misc': {'timeout': '120'}},
+            'output': {'misc': {'at-sender': 'false'}},
+        }
+        meta_trigger = self._make_meta('trigger', 'misc', [{'name': 'timeout', 'type': 'integer'}])
+        meta_output = self._make_meta('output', 'misc', [{'name': 'at-sender', 'type': 'boolean'}])
+        coerce_pipeline_config(config, meta_trigger, meta_output)
+        assert config['trigger']['misc']['timeout'] == 120
+        assert config['output']['misc']['at-sender'] is False

tests/unit_tests/plugin/test_plugin_component_filtering.py

@@ -38,13 +38,11 @@ async def test_plugin_list_filter_by_component_kinds():
                 'manifest': {
                     'metadata': {
                         'author': 'author2',
-                        'name': 'plugin_with_knowledge_retriever_only',
+                        'name': 'plugin_with_knowledge_engine_only',
                     }
                 }
             },
-            'components': [
-                {'manifest': {'manifest': {'kind': 'KnowledgeRetriever', 'metadata': {'name': 'retriever1'}}}}
-            ],
+            'components': [{'manifest': {'manifest': {'kind': 'KnowledgeEngine', 'metadata': {'name': 'retriever1'}}}}],
         },
         {
             'debug': False,
@@ -81,7 +79,7 @@ async def test_plugin_list_filter_by_component_kinds():
                 }
             },
             'components': [
-                {'manifest': {'manifest': {'kind': 'KnowledgeRetriever', 'metadata': {'name': 'retriever2'}}}},
+                {'manifest': {'manifest': {'kind': 'KnowledgeEngine', 'metadata': {'name': 'retriever2'}}}},
                 {'manifest': {'manifest': {'kind': 'Tool', 'metadata': {'name': 'tool2'}}}},
             ],
         },
@@ -108,8 +106,8 @@ async def test_plugin_list_filter_by_component_kinds():
     assert 'plugin_with_command' in plugin_names
     assert 'plugin_with_event_listener' in plugin_names
     assert 'plugin_with_mixed_components' in plugin_names
-    # Plugin with only KnowledgeRetriever should NOT be included
-    assert 'plugin_with_knowledge_retriever_only' not in plugin_names
+    # Plugin with only KnowledgeEngine should NOT be included
+    assert 'plugin_with_knowledge_engine_only' not in plugin_names
 
 
 @pytest.mark.asyncio
@@ -150,9 +148,7 @@ async def test_plugin_list_filter_no_filter():
                     }
                 }
             },
-            'components': [
-                {'manifest': {'manifest': {'kind': 'KnowledgeRetriever', 'metadata': {'name': 'retriever1'}}}}
-            ],
+            'components': [{'manifest': {'manifest': {'kind': 'KnowledgeEngine', 'metadata': {'name': 'retriever1'}}}}],
         },
     ]
 
@@ -189,7 +185,7 @@ async def test_plugin_list_filter_empty_result():
     connector = PluginRuntimeConnector(mock_app, AsyncMock())
     connector.handler = MagicMock()
 
-    # Mock plugin data - only KnowledgeRetriever plugins
+    # Mock plugin data - only KnowledgeEngine plugins
     mock_plugins = [
         {
             'debug': False,
@@ -201,9 +197,7 @@ async def test_plugin_list_filter_empty_result():
                     }
                 }
             },
-            'components': [
-                {'manifest': {'manifest': {'kind': 'KnowledgeRetriever', 'metadata': {'name': 'retriever1'}}}}
-            ],
+            'components': [{'manifest': {'manifest': {'kind': 'KnowledgeEngine', 'metadata': {'name': 'retriever1'}}}}],
         },
     ]
 

web/package.json

@@ -6,8 +6,8 @@
     "dev": "next dev --turbopack",
     "build": "next build",
     "start": "next start",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
     "lint-staged": "lint-staged"
   },
   "lint-staged": {
@@ -103,4 +103,4 @@
     "typescript-eslint": "^8.31.1"
   },
   "packageManager": "pnpm@8.9.2+sha512.b9d35fe91b2a5854dadc43034a3e7b2e675fa4b56e20e8e09ef078fa553c18f8aed44051e7b36e8b8dd435f97eb0c44c4ff3b44fc7c6fa7d21e1fac17bbe661e"
-}
+}

web/pnpm-lock.yaml

@@ -508,6 +508,7 @@ packages:
     resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -516,6 +517,7 @@ packages:
     resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -524,6 +526,7 @@ packages:
     resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -532,6 +535,7 @@ packages:
     resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -540,6 +544,7 @@ packages:
     resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -548,6 +553,7 @@ packages:
     resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -556,6 +562,7 @@ packages:
     resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: false
     optional: true
@@ -564,6 +571,7 @@ packages:
     resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: false
     optional: true
@@ -573,6 +581,7 @@ packages:
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     optionalDependencies:
       '@img/sharp-libvips-linux-arm64': 1.2.4
@@ -584,6 +593,7 @@ packages:
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     optionalDependencies:
       '@img/sharp-libvips-linux-arm': 1.2.4
@@ -595,6 +605,7 @@ packages:
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     optionalDependencies:
       '@img/sharp-libvips-linux-ppc64': 1.2.4
@@ -606,6 +617,7 @@ packages:
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     optionalDependencies:
       '@img/sharp-libvips-linux-riscv64': 1.2.4
@@ -617,6 +629,7 @@ packages:
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     optionalDependencies:
       '@img/sharp-libvips-linux-s390x': 1.2.4
@@ -628,6 +641,7 @@ packages:
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     optionalDependencies:
       '@img/sharp-libvips-linux-x64': 1.2.4
@@ -639,6 +653,7 @@ packages:
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     optionalDependencies:
       '@img/sharp-libvips-linuxmusl-arm64': 1.2.4
@@ -650,6 +665,7 @@ packages:
     engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     optionalDependencies:
       '@img/sharp-libvips-linuxmusl-x64': 1.2.4
@@ -766,6 +782,7 @@ packages:
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -775,6 +792,7 @@ packages:
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: false
     optional: true
@@ -784,6 +802,7 @@ packages:
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -793,6 +812,7 @@ packages:
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: false
     optional: true
@@ -1892,6 +1912,7 @@ packages:
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -1901,6 +1922,7 @@ packages:
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: false
     optional: true
@@ -1910,6 +1932,7 @@ packages:
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -1919,6 +1942,7 @@ packages:
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: false
     optional: true
@@ -2334,6 +2358,7 @@ packages:
     resolution: {integrity: sha512-34gw7PjDGB9JgePJEmhEqBhWvCiiWCuXsL9hYphDF7crW7UgI05gyBAi6MF58uGcMOiOqSJ2ybEeCvHcq0BCmQ==}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: true
     optional: true
@@ -2342,6 +2367,7 @@ packages:
     resolution: {integrity: sha512-RyMIx6Uf53hhOtJDIamSbTskA99sPHS96wxVE/bJtePJJtpdKGXO1wY90oRdXuYOGOTuqjT8ACccMc4K6QmT3w==}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: true
     optional: true
@@ -2350,6 +2376,7 @@ packages:
     resolution: {integrity: sha512-D8Vae74A4/a+mZH0FbOkFJL9DSK2R6TFPC9M+jCWYia/q2einCubX10pecpDiTmkJVUH+y8K3BZClycD8nCShA==}
     cpu: [ppc64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: true
     optional: true
@@ -2358,6 +2385,7 @@ packages:
     resolution: {integrity: sha512-frxL4OrzOWVVsOc96+V3aqTIQl1O2TjgExV4EKgRY09AJ9leZpEg8Ak9phadbuX0BA4k8U5qtvMSQQGGmaJqcQ==}
     cpu: [riscv64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: true
     optional: true
@@ -2366,6 +2394,7 @@ packages:
     resolution: {integrity: sha512-mJ5vuDaIZ+l/acv01sHoXfpnyrNKOk/3aDoEdLO/Xtn9HuZlDD6jKxHlkN8ZhWyLJsRBxfv9GYM2utQ1SChKew==}
     cpu: [riscv64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: true
     optional: true
@@ -2374,6 +2403,7 @@ packages:
     resolution: {integrity: sha512-kELo8ebBVtb9sA7rMe1Cph4QHreByhaZ2QEADd9NzIQsYNQpt9UkM9iqr2lhGr5afh885d/cB5QeTXSbZHTYPg==}
     cpu: [s390x]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: true
     optional: true
@@ -2382,6 +2412,7 @@ packages:
     resolution: {integrity: sha512-C3ZAHugKgovV5YvAMsxhq0gtXuwESUKc5MhEtjBpLoHPLYM+iuwSj3lflFwK3DPm68660rZ7G8BMcwSro7hD5w==}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: true
     optional: true
@@ -2390,6 +2421,7 @@ packages:
     resolution: {integrity: sha512-rV0YSoyhK2nZ4vEswT/QwqzqQXw5I6CjoaYMOX0TqBlWhojUf8P94mvI7nuJTeaCkkds3QE4+zS8Ko+GdXuZtA==}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: true
     optional: true
@@ -4424,6 +4456,7 @@ packages:
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -4433,6 +4466,7 @@ packages:
     engines: {node: '>= 12.0.0'}
     cpu: [arm64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: false
     optional: true
@@ -4442,6 +4476,7 @@ packages:
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [linux]
+    libc: [glibc]
     requiresBuild: true
     dev: false
     optional: true
@@ -4451,6 +4486,7 @@ packages:
     engines: {node: '>= 12.0.0'}
     cpu: [x64]
     os: [linux]
+    libc: [musl]
     requiresBuild: true
     dev: false
     optional: true

web/src/app/home/bots/components/bot-form/BotForm.tsx

@@ -319,6 +319,7 @@ export default function BotForm({
               required: item.required,
               type: parseDynamicFormItemType(item.type),
               options: item.options,
+              show_if: item.show_if,
             }),
         ),
       );

web/src/app/home/bots/components/bot-session/BotSessionMonitor.tsx

@@ -6,6 +6,7 @@ import { httpClient } from '@/app/infra/http/HttpClient';
 import { ScrollArea } from '@/components/ui/scroll-area';
 import { Button } from '@/components/ui/button';
 import { cn } from '@/lib/utils';
+import { Copy, Check } from 'lucide-react';
 import {
   MessageChainComponent,
   Plain,
@@ -27,6 +28,7 @@ interface SessionInfo {
   is_active: boolean;
   platform?: string | null;
   user_id?: string | null;
+  user_name?: string | null;
 }
 
 interface SessionMessage {
@@ -60,8 +62,29 @@ export default function BotSessionMonitor({ botId }: BotSessionMonitorProps) {
   const [messages, setMessages] = useState<SessionMessage[]>([]);
   const [loadingSessions, setLoadingSessions] = useState(false);
   const [loadingMessages, setLoadingMessages] = useState(false);
+  const [copiedUserId, setCopiedUserId] = useState(false);
   const messagesContainerRef = useRef<HTMLDivElement>(null);
 
+  const parseSessionType = (sessionId: string): string | null => {
+    const idx = sessionId.indexOf('_');
+    if (idx === -1) return null;
+    const type = sessionId.slice(0, idx);
+    if (type === 'person' || type === 'group') return type;
+    return null;
+  };
+
+  const abbreviateId = (id: string): string => {
+    if (id.length <= 10) return id;
+    return `${id.slice(0, 4)}..${id.slice(-4)}`;
+  };
+
+  const copyUserId = (userId: string) => {
+    navigator.clipboard.writeText(userId).then(() => {
+      setCopiedUserId(true);
+      setTimeout(() => setCopiedUserId(false), 2000);
+    });
+  };
+
   const loadSessions = useCallback(async () => {
     setLoadingSessions(true);
     try {
@@ -338,24 +361,36 @@ export default function BotSessionMonitor({ botId }: BotSessionMonitorProps) {
                   >
                     <div className="flex items-center justify-between mb-0.5">
                       <span className="text-sm font-medium truncate mr-2">
-                        {session.user_id || session.session_id.slice(0, 12)}
+                        {session.user_name ||
+                          session.user_id ||
+                          session.session_id.slice(0, 12)}
                       </span>
                       <span className="text-[11px] text-muted-foreground tabular-nums flex-shrink-0">
                         {formatRelativeTime(session.last_activity)}
                       </span>
                     </div>
                     <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                      {parseSessionType(session.session_id) && (
+                        <span className="px-1 py-0.5 rounded bg-muted text-[10px]">
+                          {parseSessionType(session.session_id)}
+                        </span>
+                      )}
                       {session.platform && (
                         <span className="px-1 py-0.5 rounded bg-muted text-[10px]">
                           {session.platform}
                         </span>
                       )}
+                      {session.user_id && (
+                        <span className="truncate text-[10px]">
+                          {abbreviateId(session.user_id)}
+                        </span>
+                      )}
                       {session.is_active && (
                         <span className="flex items-center gap-0.5 text-green-600 dark:text-green-400">
                           <span className="w-1.5 h-1.5 rounded-full bg-green-500 inline-block" />
                         </span>
                       )}
-                      <span>{session.pipeline_name}</span>
+                      <span className="truncate">{session.pipeline_name}</span>
                     </div>
                   </button>
                 );
@@ -377,15 +412,42 @@ export default function BotSessionMonitor({ botId }: BotSessionMonitorProps) {
             <div className="px-6 py-3 border-b shrink-0 flex items-center justify-between">
               <div className="min-w-0">
                 <div className="text-sm font-medium truncate">
-                  {selectedSession?.user_id || selectedSessionId.slice(0, 20)}
+                  {selectedSession?.user_name ||
+                    selectedSession?.user_id ||
+                    selectedSessionId.slice(0, 20)}
                 </div>
                 <div className="flex items-center gap-2 text-xs text-muted-foreground">
+                  {parseSessionType(selectedSessionId) && (
+                    <span>{parseSessionType(selectedSessionId)}</span>
+                  )}
                   {selectedSession?.platform && (
-                    <span>{selectedSession.platform}</span>
+                    <>
+                      {parseSessionType(selectedSessionId) && <span>·</span>}
+                      <span>{selectedSession.platform}</span>
+                    </>
+                  )}
+                  {selectedSession?.user_id && (
+                    <>
+                      <span>·</span>
+                      <span className="font-mono">
+                        {selectedSession.user_id}
+                      </span>
+                      <button
+                        onClick={() => copyUserId(selectedSession.user_id!)}
+                        className="inline-flex items-center text-muted-foreground hover:text-foreground transition-colors"
+                        title={t('common.copy')}
+                      >
+                        {copiedUserId ? (
+                          <Check className="w-3 h-3 text-green-600" />
+                        ) : (
+                          <Copy className="w-3 h-3" />
+                        )}
+                      </button>
+                    </>
                   )}
                   {selectedSession?.pipeline_name && (
                     <>
-                      {selectedSession?.platform && <span>·</span>}
+                      <span>·</span>
                       <span>{selectedSession.pipeline_name}</span>
                     </>
                   )}

web/src/app/home/components/dynamic-form/DynamicFormComponent.tsx

@@ -13,20 +13,26 @@ import {
 import DynamicFormItemComponent from '@/app/home/components/dynamic-form/DynamicFormItemComponent';
 import { useCallback, useEffect, useRef } from 'react';
 import { extractI18nObject } from '@/i18n/I18nProvider';
+import { useTranslation } from 'react-i18next';
 
 export default function DynamicFormComponent({
   itemConfigList,
   onSubmit,
   initialValues,
   onFileUploaded,
+  isEditing,
+  externalDependentValues,
 }: {
   itemConfigList: IDynamicFormItemSchema[];
   onSubmit?: (val: object) => unknown;
   initialValues?: Record<string, object>;
   onFileUploaded?: (fileKey: string) => void;
+  isEditing?: boolean;
+  externalDependentValues?: Record<string, unknown>;
 }) {
   const isInitialMount = useRef(true);
   const previousInitialValues = useRef(initialValues);
+  const { t } = useTranslation();
 
   // 根据 itemConfigList 动态生成 zod schema
   const formSchema = z.object(
@@ -55,6 +61,9 @@ export default function DynamicFormComponent({
           case 'llm-model-selector':
             fieldSchema = z.string();
             break;
+          case 'embedding-model-selector':
+            fieldSchema = z.string();
+            break;
           case 'knowledge-base-selector':
             fieldSchema = z.string();
             break;
@@ -81,7 +90,9 @@ export default function DynamicFormComponent({
           (fieldSchema instanceof z.ZodString ||
             fieldSchema instanceof z.ZodArray)
         ) {
-          fieldSchema = fieldSchema.min(1, { message: '此字段为必填项' });
+          fieldSchema = fieldSchema.min(1, {
+            message: t('common.fieldRequired'),
+          });
         }
 
         return {
@@ -141,6 +152,9 @@ export default function DynamicFormComponent({
     }
   }, [initialValues, form, itemConfigList]);
 
+  // Get reactive form values for conditional rendering
+  const watchedValues = form.watch();
+
   // Stable ref for onSubmit to avoid re-triggering the effect when the
   // parent passes a new closure on every render.
   const onSubmitRef = useRef(onSubmit);
@@ -183,34 +197,75 @@ export default function DynamicFormComponent({
   return (
     <Form {...form}>
       <div className="space-y-4">
-        {itemConfigList.map((config) => (
-          <FormField
-            key={config.id}
-            control={form.control}
-            name={config.name as keyof FormValues}
-            render={({ field }) => (
-              <FormItem>
-                <FormLabel>
-                  {extractI18nObject(config.label)}{' '}
-                  {config.required && <span className="text-red-500">*</span>}
-                </FormLabel>
-                <FormControl>
-                  <DynamicFormItemComponent
-                    config={config}
-                    field={field}
-                    onFileUploaded={onFileUploaded}
-                  />
-                </FormControl>
-                {config.description && (
-                  <p className="text-sm text-muted-foreground">
-                    {extractI18nObject(config.description)}
-                  </p>
-                )}
-                <FormMessage />
-              </FormItem>
-            )}
-          />
-        ))}
+        {itemConfigList.map((config) => {
+          if (config.show_if) {
+            const dependValue =
+              watchedValues[
+                config.show_if.field as keyof typeof watchedValues
+              ] !== undefined
+                ? watchedValues[
+                    config.show_if.field as keyof typeof watchedValues
+                  ]
+                : externalDependentValues?.[config.show_if.field];
+
+            if (
+              config.show_if.operator === 'eq' &&
+              dependValue !== config.show_if.value
+            ) {
+              return null;
+            }
+            if (
+              config.show_if.operator === 'neq' &&
+              dependValue === config.show_if.value
+            ) {
+              return null;
+            }
+            if (
+              config.show_if.operator === 'in' &&
+              Array.isArray(config.show_if.value) &&
+              !config.show_if.value.includes(dependValue)
+            ) {
+              return null;
+            }
+          }
+
+          // All fields are disabled when editing (creation_settings are immutable)
+          const isFieldDisabled = !!isEditing;
+          return (
+            <FormField
+              key={config.id}
+              control={form.control}
+              name={config.name as keyof FormValues}
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel>
+                    {extractI18nObject(config.label)}{' '}
+                    {config.required && <span className="text-red-500">*</span>}
+                  </FormLabel>
+                  <FormControl>
+                    <div
+                      className={
+                        isFieldDisabled ? 'pointer-events-none opacity-60' : ''
+                      }
+                    >
+                      <DynamicFormItemComponent
+                        config={config}
+                        field={field}
+                        onFileUploaded={onFileUploaded}
+                      />
+                    </div>
+                  </FormControl>
+                  {config.description && (
+                    <p className="text-sm text-muted-foreground">
+                      {extractI18nObject(config.description)}
+                    </p>
+                  )}
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+          );
+        })}
       </div>
     </Form>
   );

web/src/app/home/components/dynamic-form/DynamicFormItemComponent.tsx

@@ -22,8 +22,7 @@ import {
   LLMModel,
   Bot,
   KnowledgeBase,
-  ExternalKnowledgeBase,
-  ApiRespPluginSystemStatus,
+  EmbeddingModel,
 } from '@/app/infra/entities/api';
 import { toast } from 'sonner';
 import { useTranslation } from 'react-i18next';
@@ -51,16 +50,12 @@ export default function DynamicFormItemComponent({
   onFileUploaded?: (fileKey: string) => void;
 }) {
   const [llmModels, setLlmModels] = useState<LLMModel[]>([]);
+  const [embeddingModels, setEmbeddingModels] = useState<EmbeddingModel[]>([]);
   const [knowledgeBases, setKnowledgeBases] = useState<KnowledgeBase[]>([]);
-  const [externalKnowledgeBases, setExternalKnowledgeBases] = useState<
-    ExternalKnowledgeBase[]
-  >([]);
   const [bots, setBots] = useState<Bot[]>([]);
   const [uploading, setUploading] = useState<boolean>(false);
   const [kbDialogOpen, setKbDialogOpen] = useState(false);
   const [tempSelectedKBIds, setTempSelectedKBIds] = useState<string[]>([]);
-  const [pluginSystemStatus, setPluginSystemStatus] =
-    useState<ApiRespPluginSystemStatus | null>(null);
   const { t } = useTranslation();
 
   const handleFileUpload = async (file: File): Promise<IFileConfig | null> => {
@@ -111,7 +106,20 @@ export default function DynamicFormItemComponent({
           setLlmModels(models);
         })
         .catch((err) => {
-          toast.error('Failed to get LLM model list: ' + err.msg);
+          toast.error(t('models.getModelListError') + err.msg);
+        });
+    }
+  }, [config.type]);
+
+  useEffect(() => {
+    if (config.type === DynamicFormItemType.EMBEDDING_MODEL_SELECTOR) {
+      httpClient
+        .getProviderEmbeddingModels()
+        .then((resp) => {
+          setEmbeddingModels(resp.models);
+        })
+        .catch((err) => {
+          toast.error(t('embedding.getModelListError') + err.msg);
         });
     }
   }, [config.type]);
@@ -127,39 +135,11 @@ export default function DynamicFormItemComponent({
           setKnowledgeBases(resp.bases);
         })
         .catch((err) => {
-          toast.error('Failed to get knowledge base list: ' + err.msg);
-        });
-
-      // Fetch plugin system status
-      httpClient
-        .getPluginSystemStatus()
-        .then((status) => {
-          setPluginSystemStatus(status);
-        })
-        .catch((err) => {
-          console.error('Failed to get plugin system status:', err);
+          toast.error(t('knowledge.getKnowledgeBaseListError') + err.msg);
         });
     }
   }, [config.type]);
 
-  useEffect(() => {
-    if (
-      (config.type === DynamicFormItemType.KNOWLEDGE_BASE_SELECTOR ||
-        config.type === DynamicFormItemType.KNOWLEDGE_BASE_MULTI_SELECTOR) &&
-      pluginSystemStatus?.is_enable &&
-      pluginSystemStatus?.is_connected
-    ) {
-      httpClient
-        .getExternalKnowledgeBases()
-        .then((resp) => {
-          setExternalKnowledgeBases(resp.bases);
-        })
-        .catch((err) => {
-          console.error('Failed to get external knowledge base list:', err);
-        });
-    }
-  }, [config.type, pluginSystemStatus]);
-
   useEffect(() => {
     if (config.type === DynamicFormItemType.BOT_SELECTOR) {
       httpClient
@@ -168,7 +148,7 @@ export default function DynamicFormItemComponent({
           setBots(resp.bots);
         })
         .catch((err) => {
-          toast.error('Failed to get bot list: ' + err.msg);
+          toast.error(t('bots.getBotListError') + err.msg);
         });
     }
   }, [config.type]);
@@ -304,7 +284,56 @@ export default function DynamicFormItemComponent({
         </Select>
       );
 
+    case DynamicFormItemType.EMBEDDING_MODEL_SELECTOR:
+      // Group embedding models by provider
+      const groupedEmbeddingModels = embeddingModels.reduce(
+        (acc, model) => {
+          const providerName = model.provider?.name || 'Unknown';
+          if (!acc[providerName]) acc[providerName] = [];
+          acc[providerName].push(model);
+          return acc;
+        },
+        {} as Record<string, EmbeddingModel[]>,
+      );
+
+      return (
+        <Select value={field.value} onValueChange={field.onChange}>
+          <SelectTrigger className="bg-[#ffffff] dark:bg-[#2a2a2e]">
+            <SelectValue placeholder={t('knowledge.selectEmbeddingModel')} />
+          </SelectTrigger>
+          <SelectContent>
+            {Object.entries(groupedEmbeddingModels).map(
+              ([providerName, models]) => (
+                <SelectGroup key={providerName}>
+                  <SelectLabel>{providerName}</SelectLabel>
+                  {models.map((model) => (
+                    <SelectItem key={model.uuid} value={model.uuid}>
+                      {model.name}
+                    </SelectItem>
+                  ))}
+                </SelectGroup>
+              ),
+            )}
+          </SelectContent>
+        </Select>
+      );
+
     case DynamicFormItemType.KNOWLEDGE_BASE_SELECTOR:
+      // Group KBs by Knowledge Engine name
+      const kbsByEngine = knowledgeBases.reduce(
+        (acc, kb) => {
+          const engineName = kb.knowledge_engine?.name
+            ? extractI18nObject(kb.knowledge_engine.name)
+            : t('knowledge.unknownEngine');
+          if (!acc[engineName]) {
+            acc[engineName] = [];
+          }
+          acc[engineName].push(kb);
+          return acc;
+        },
+        {} as Record<string, typeof knowledgeBases>,
+      );
+
       return (
         <Select value={field.value} onValueChange={field.onChange}>
           <SelectTrigger className="bg-[#ffffff] dark:bg-[#2a2a2e]">
@@ -315,53 +344,45 @@ export default function DynamicFormItemComponent({
               <SelectItem value="__none__">{t('knowledge.empty')}</SelectItem>
             </SelectGroup>
 
-            {knowledgeBases.length > 0 && (
-              <SelectGroup>
-                <SelectLabel>{t('knowledge.builtIn')}</SelectLabel>
-                {knowledgeBases.map((base) => (
+            {Object.entries(kbsByEngine).map(([engineName, kbs]) => (
+              <SelectGroup key={engineName}>
+                <SelectLabel>{engineName}</SelectLabel>
+                {kbs.map((base) => (
                   <SelectItem key={base.uuid} value={base.uuid ?? ''}>
                     {base.name}
                   </SelectItem>
                 ))}
               </SelectGroup>
-            )}
-
-            {externalKnowledgeBases.length > 0 && (
-              <SelectGroup>
-                <SelectLabel>{t('knowledge.external')}</SelectLabel>
-                {externalKnowledgeBases.map((base) => (
-                  <SelectItem key={base.uuid} value={base.uuid ?? ''}>
-                    <div className="flex items-center gap-2">
-                      <img
-                        src={httpClient.getPluginIconURL(
-                          base.plugin_author,
-                          base.plugin_name,
-                        )}
-                        alt="plugin icon"
-                        className="w-4 h-4 rounded-[8%] flex-shrink-0"
-                      />
-                      <span>{base.name}</span>
-                    </div>
-                  </SelectItem>
-                ))}
-              </SelectGroup>
-            )}
+            ))}
           </SelectContent>
         </Select>
       );
 
     case DynamicFormItemType.KNOWLEDGE_BASE_MULTI_SELECTOR:
+      // Group KBs by Knowledge Engine name for multi-selector
+      const multiKbsByEngine = knowledgeBases.reduce(
+        (acc, kb) => {
+          const engineName = kb.knowledge_engine?.name
+            ? extractI18nObject(kb.knowledge_engine.name)
+            : t('knowledge.unknownEngine');
+          if (!acc[engineName]) {
+            acc[engineName] = [];
+          }
+          acc[engineName].push(kb);
+          return acc;
+        },
+        {} as Record<string, typeof knowledgeBases>,
+      );
+
       return (
         <>
           <div className="space-y-2">
             {field.value && field.value.length > 0 ? (
               <div className="space-y-2">
                 {field.value.map((kbId: string) => {
-                  const kb = knowledgeBases.find((base) => base.uuid === kbId);
-                  const externalKb = externalKnowledgeBases.find(
+                  const currentKb = knowledgeBases.find(
                     (base) => base.uuid === kbId,
                   );
-                  const currentKb = kb || externalKb;
                   if (!currentKb) return null;
 
                   return (
@@ -370,18 +391,17 @@ export default function DynamicFormItemComponent({
                       className="flex items-center justify-between rounded-lg border p-3 hover:bg-accent"
                     >
                       <div className="flex items-center gap-2 flex-1">
-                        {externalKb && (
-                          <img
-                            src={httpClient.getPluginIconURL(
-                              externalKb.plugin_author,
-                              externalKb.plugin_name,
-                            )}
-                            alt="plugin icon"
-                            className="w-8 h-8 rounded-[8%] flex-shrink-0"
-                          />
-                        )}
                         <div className="flex-1 min-w-0">
-                          <div className="font-medium">{currentKb.name}</div>
+                          <div className="font-medium flex items-center gap-2">
+                            {currentKb.name}
+                            {currentKb.knowledge_engine?.name && (
+                              <span className="text-xs px-2 py-0.5 rounded-full bg-purple-100 text-purple-700 dark:bg-purple-900 dark:text-purple-300">
+                                {extractI18nObject(
+                                  currentKb.knowledge_engine.name,
+                                )}
+                              </span>
+                            )}
+                          </div>
                           {currentKb.description && (
                             <div className="text-sm text-muted-foreground">
                               {currentKb.description}
@@ -435,13 +455,12 @@ export default function DynamicFormItemComponent({
                 <DialogTitle>{t('knowledge.selectKnowledgeBases')}</DialogTitle>
               </DialogHeader>
               <div className="flex-1 overflow-y-auto space-y-4 pr-2">
-                {/* Built-in Knowledge Bases */}
-                {knowledgeBases.length > 0 && (
-                  <div className="space-y-2">
+                {Object.entries(multiKbsByEngine).map(([engineName, kbs]) => (
+                  <div key={engineName} className="space-y-2">
                     <div className="text-sm font-semibold text-muted-foreground px-2">
-                      {t('knowledge.builtIn')}
+                      {engineName}
                     </div>
-                    {knowledgeBases.map((base) => {
+                    {kbs.map((base) => {
                       const isSelected = tempSelectedKBIds.includes(
                         base.uuid ?? '',
                       );
@@ -474,56 +493,7 @@ export default function DynamicFormItemComponent({
                       );
                     })}
                   </div>
-                )}
-
-                {/* External Knowledge Bases */}
-                {externalKnowledgeBases.length > 0 && (
-                  <div className="space-y-2">
-                    <div className="text-sm font-semibold text-muted-foreground px-2">
-                      {t('knowledge.external')}
-                    </div>
-                    {externalKnowledgeBases.map((base) => {
-                      const isSelected = tempSelectedKBIds.includes(
-                        base.uuid ?? '',
-                      );
-                      return (
-                        <div
-                          key={base.uuid}
-                          className="flex items-center gap-3 rounded-lg border p-3 hover:bg-accent cursor-pointer"
-                          onClick={() => {
-                            const kbId = base.uuid ?? '';
-                            setTempSelectedKBIds((prev) =>
-                              prev.includes(kbId)
-                                ? prev.filter((id) => id !== kbId)
-                                : [...prev, kbId],
-                            );
-                          }}
-                        >
-                          <Checkbox
-                            checked={isSelected}
-                            aria-label={`Select ${base.name}`}
-                          />
-                          <img
-                            src={httpClient.getPluginIconURL(
-                              base.plugin_author,
-                              base.plugin_name,
-                            )}
-                            alt="plugin icon"
-                            className="w-8 h-8 rounded-[8%] flex-shrink-0"
-                          />
-                          <div className="flex-1">
-                            <div className="font-medium">{base.name}</div>
-                            {base.description && (
-                              <div className="text-sm text-muted-foreground">
-                                {base.description}
-                              </div>
-                            )}
-                          </div>
-                        </div>
-                      );
-                    })}
-                  </div>
-                )}
+                ))}
               </div>
               <DialogFooter>
                 <Button

web/src/app/home/components/dynamic-form/DynamicFormItemConfig.ts

@@ -2,6 +2,7 @@ import {
   IDynamicFormItemSchema,
   DynamicFormItemType,
   IDynamicFormItemOption,
+  IShowIfCondition,
 } from '@/app/infra/entities/form/dynamic';
 import { I18nObject } from '@/app/infra/entities/common';
 
@@ -14,6 +15,7 @@ export class DynamicFormItemConfig implements IDynamicFormItemSchema {
   type: DynamicFormItemType;
   description?: I18nObject;
   options?: IDynamicFormItemOption[];
+  show_if?: IShowIfCondition;
 
   constructor(params: IDynamicFormItemSchema) {
     this.id = params.id;
@@ -24,6 +26,7 @@ export class DynamicFormItemConfig implements IDynamicFormItemSchema {
     this.type = params.type;
     this.description = params.description;
     this.options = params.options;
+    this.show_if = params.show_if;
   }
 }
 

web/src/app/home/components/home-sidebar/HomeSidebar.tsx

@@ -422,12 +422,12 @@ export default function HomeSidebar({
                   const language = localStorage.getItem('langbot_language');
                   if (language === 'zh-Hans' || language === 'zh-Hant') {
                     window.open(
-                      'https://docs.langbot.app/zh/insight/guide.html',
+                      'https://docs.langbot.app/zh/insight/guide',
                       '_blank',
                     );
                   } else {
                     window.open(
-                      'https://docs.langbot.app/en/insight/guide.html',
+                      'https://docs.langbot.app/en/insight/guide',
                       '_blank',
                     );
                   }

web/src/app/home/components/home-sidebar/sidbarConfigList.tsx

@@ -23,9 +23,9 @@ export const sidebarConfigList = [
     route: '/home/bots',
     description: t('bots.description'),
     helpLink: {
-      en_US: 'https://docs.langbot.app/en/usage/platforms/readme.html',
-      zh_Hans: 'https://docs.langbot.app/zh/usage/platforms/readme.html',
-      ja_JP: 'https://docs.langbot.app/ja/usage/platforms/readme.html',
+      en_US: 'https://docs.langbot.app/en/usage/platforms/readme',
+      zh_Hans: 'https://docs.langbot.app/zh/usage/platforms/readme',
+      ja_JP: 'https://docs.langbot.app/ja/usage/platforms/readme',
     },
   }),
   new SidebarChildVO({
@@ -44,9 +44,9 @@ export const sidebarConfigList = [
     route: '/home/pipelines',
     description: t('pipelines.description'),
     helpLink: {
-      en_US: 'https://docs.langbot.app/en/usage/pipelines/readme.html',
-      zh_Hans: 'https://docs.langbot.app/zh/usage/pipelines/readme.html',
-      ja_JP: 'https://docs.langbot.app/ja/usage/pipelines/readme.html',
+      en_US: 'https://docs.langbot.app/en/usage/pipelines/readme',
+      zh_Hans: 'https://docs.langbot.app/zh/usage/pipelines/readme',
+      ja_JP: 'https://docs.langbot.app/ja/usage/pipelines/readme',
     },
   }),
   new SidebarChildVO({
@@ -65,8 +65,8 @@ export const sidebarConfigList = [
     route: '/home/monitoring',
     description: t('monitoring.description'),
     helpLink: {
-      en_US: 'https://docs.langbot.app/en/features/monitoring.html',
-      zh_Hans: 'https://docs.langbot.app/zh/features/monitoring.html',
+      en_US: '',
+      zh_Hans: '',
     },
   }),
   new SidebarChildVO({
@@ -84,9 +84,9 @@ export const sidebarConfigList = [
     route: '/home/knowledge',
     description: t('knowledge.description'),
     helpLink: {
-      en_US: 'https://docs.langbot.app/en/usage/knowledge/readme.html',
-      zh_Hans: 'https://docs.langbot.app/zh/usage/knowledge/readme.html',
-      ja_JP: 'https://docs.langbot.app/ja/usage/knowledge/readme.html',
+      en_US: 'https://docs.langbot.app/en/usage/knowledge/readme',
+      zh_Hans: 'https://docs.langbot.app/zh/usage/knowledge/readme',
+      ja_JP: 'https://docs.langbot.app/ja/usage/knowledge/readme',
     },
   }),
   new SidebarChildVO({
@@ -105,9 +105,9 @@ export const sidebarConfigList = [
     route: '/home/plugins',
     description: t('plugins.description'),
     helpLink: {
-      en_US: 'https://docs.langbot.app/en/usage/plugin/plugin-intro.html',
-      zh_Hans: 'https://docs.langbot.app/zh/usage/plugin/plugin-intro.html',
-      ja_JP: 'https://docs.langbot.app/ja/usage/plugin/plugin-intro.html',
+      en_US: 'https://docs.langbot.app/en/usage/plugin/plugin-intro',
+      zh_Hans: 'https://docs.langbot.app/zh/usage/plugin/plugin-intro',
+      ja_JP: 'https://docs.langbot.app/ja/usage/plugin/plugin-intro',
     },
   }),
 ];

web/src/app/home/components/new-version-dialog/NewVersionDialog.tsx

@@ -36,11 +36,11 @@ export default function NewVersionDialog({
   const getUpdateDocsUrl = () => {
     const language = i18n.language;
     if (language === 'zh-Hans' || language === 'zh-Hant') {
-      return 'https://docs.langbot.app/zh/deploy/update.html';
+      return 'https://docs.langbot.app/zh/deploy/update';
     } else if (language === 'ja-JP') {
-      return 'https://docs.langbot.app/ja/deploy/update.html';
+      return 'https://docs.langbot.app/ja/deploy/update';
     } else {
-      return 'https://docs.langbot.app/en/deploy/update.html';
+      return 'https://docs.langbot.app/en/deploy/update';
     }
   };
 

web/src/app/home/knowledge/KBDetailDialog.tsx

@@ -21,18 +21,17 @@ import {
 import { Button } from '@/components/ui/button';
 import { useTranslation } from 'react-i18next';
 import { httpClient } from '@/app/infra/http/HttpClient';
-// import { KnowledgeBase } from '@/app/infra/entities/api';
+import { KnowledgeBase } from '@/app/infra/entities/api';
+import { CustomApiError } from '@/app/infra/entities/common';
+import { toast } from 'sonner';
 import KBForm from '@/app/home/knowledge/components/kb-form/KBForm';
 import KBDoc from '@/app/home/knowledge/components/kb-docs/KBDoc';
-import KBRetrieve from '@/app/home/knowledge/components/kb-retrieve/KBRetrieve';
-import ExternalKBForm from '@/app/home/knowledge/components/external-kb-form/ExternalKBForm';
-import ExternalKBRetrieve from '@/app/home/knowledge/components/kb-retrieve/ExternalKBRetrieve';
+import KBRetrieveGeneric from '@/app/home/knowledge/components/kb-retrieve/KBRetrieveGeneric';
 
 interface KBDetailDialogProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   kbId?: string;
-  kbType: 'builtin' | 'external';
   onFormCancel: () => void;
   onKbDeleted: () => void;
   onNewKbCreated: (kbId: string) => void;
@@ -43,7 +42,6 @@ export default function KBDetailDialog({
   open,
   onOpenChange,
   kbId: propKbId,
-  kbType,
   onFormCancel,
   onKbDeleted,
   onNewKbCreated,
@@ -53,13 +51,41 @@ export default function KBDetailDialog({
   const [kbId, setKbId] = useState<string | undefined>(propKbId);
   const [activeMenu, setActiveMenu] = useState('metadata');
   const [showDeleteConfirm, setShowDeleteConfirm] = useState(false);
+  const [kbInfo, setKbInfo] = useState<KnowledgeBase | null>(null);
 
   useEffect(() => {
     setKbId(propKbId);
     setActiveMenu('metadata');
+    if (propKbId) {
+      loadKbInfo(propKbId);
+    } else {
+      setKbInfo(null);
+    }
   }, [propKbId, open]);
 
-  // Build menu based on KB type
+  async function loadKbInfo(id: string) {
+    try {
+      const resp = await httpClient.getKnowledgeBase(id);
+      setKbInfo(resp.base);
+    } catch (e) {
+      console.error('Failed to load KB info:', e);
+      toast.error(
+        t('knowledge.loadKnowledgeBaseFailed') + (e as CustomApiError).msg,
+      );
+    }
+  }
+
+  // Check if this KB supports document management
+  const hasDocumentCapability = (): boolean => {
+    if (!kbInfo || !kbInfo.knowledge_engine) {
+      return false;
+    }
+    return (
+      kbInfo.knowledge_engine.capabilities?.includes('doc_ingestion') ?? false
+    );
+  };
+
+  // Build menu based on KB capabilities
   const menu = [
     {
       key: 'metadata',
@@ -74,8 +100,8 @@ export default function KBDetailDialog({
         </svg>
       ),
     },
-    // Only show documents for builtin KB
-    ...(kbType === 'builtin'
+    // Show documents only if capability is present
+    ...(hasDocumentCapability()
       ? [
           {
             key: 'documents',
@@ -107,66 +133,51 @@ export default function KBDetailDialog({
     },
   ];
 
-  const confirmDelete = () => {
-    const deletePromise =
-      kbType === 'builtin'
-        ? httpClient.deleteKnowledgeBase(kbId ?? '')
-        : httpClient.deleteExternalKnowledgeBase(kbId ?? '');
-
-    deletePromise.then(() => {
+  const confirmDelete = async () => {
+    try {
+      await httpClient.deleteKnowledgeBase(kbId ?? '');
       onKbDeleted();
-    });
-    setShowDeleteConfirm(false);
+    } catch (e) {
+      console.error('Failed to delete KB:', e);
+      toast.error(
+        t('knowledge.deleteKnowledgeBaseFailed') + (e as CustomApiError).msg,
+      );
+    } finally {
+      setShowDeleteConfirm(false);
+    }
+  };
+
+  // Retrieve function
+  const retrieveFunction = async (id: string, query: string) => {
+    return await httpClient.retrieveKnowledgeBase(id, query);
   };
 
   if (!kbId) {
-    // new kb
+    // New KB creation
     return (
       <Dialog open={open} onOpenChange={onOpenChange}>
         <DialogContent className="overflow-hidden p-0 !max-w-[40vw] max-h-[70vh] flex">
           <main className="flex flex-1 flex-col h-[70vh]">
             <DialogHeader className="px-6 pt-6 pb-4 shrink-0">
-              <DialogTitle>
-                {kbType === 'builtin'
-                  ? t('knowledge.createKnowledgeBase')
-                  : t('knowledge.addExternal')}
-              </DialogTitle>
+              <DialogTitle>{t('knowledge.createKnowledgeBase')}</DialogTitle>
             </DialogHeader>
             <div className="flex-1 overflow-y-auto px-6 pb-6">
-              {kbType === 'builtin' ? (
-                <KBForm
-                  initKbId={undefined}
-                  onNewKbCreated={onNewKbCreated}
-                  onKbUpdated={onKbUpdated}
-                />
-              ) : (
-                <ExternalKBForm
-                  initKBId={undefined}
-                  onFormSubmit={() => onOpenChange(false)}
-                  onKBDeleted={() => {}}
-                  onNewKBCreated={onNewKbCreated}
-                />
-              )}
+              <KBForm
+                initKbId={undefined}
+                onNewKbCreated={onNewKbCreated}
+                onKbUpdated={onKbUpdated}
+              />
             </div>
-            {activeMenu === 'metadata' && (
-              <DialogFooter className="px-6 py-4 border-t shrink-0">
-                <div className="flex justify-end gap-2">
-                  <Button
-                    type="submit"
-                    form={kbType === 'builtin' ? 'kb-form' : 'external-kb-form'}
-                  >
-                    {t('common.save')}
-                  </Button>
-                  <Button
-                    type="button"
-                    variant="outline"
-                    onClick={onFormCancel}
-                  >
-                    {t('common.cancel')}
-                  </Button>
-                </div>
-              </DialogFooter>
-            )}
+            <DialogFooter className="px-6 py-4 border-t shrink-0">
+              <div className="flex justify-end gap-2">
+                <Button type="submit" form="kb-form">
+                  {t('common.save')}
+                </Button>
+                <Button type="button" variant="outline" onClick={onFormCancel}>
+                  {t('common.cancel')}
+                </Button>
+              </div>
+            </DialogFooter>
           </main>
         </DialogContent>
       </Dialog>
@@ -205,7 +216,7 @@ export default function KBDetailDialog({
                 </SidebarGroup>
               </SidebarContent>
             </Sidebar>
-            <main className="flex flex-1 flex-col h-[75vh]">
+            <main className="flex flex-1 flex-col h-[75vh] min-w-0 overflow-x-hidden">
               <DialogHeader className="px-6 pt-6 pb-4 shrink-0">
                 <DialogTitle>
                   {activeMenu === 'metadata'
@@ -216,33 +227,28 @@ export default function KBDetailDialog({
                 </DialogTitle>
               </DialogHeader>
               <div className="flex-1 overflow-y-auto px-6 pb-6">
-                {activeMenu === 'metadata' &&
-                  (kbType === 'builtin' ? (
-                    <KBForm
-                      initKbId={kbId}
-                      onNewKbCreated={onNewKbCreated}
-                      onKbUpdated={onKbUpdated}
-                    />
-                  ) : (
-                    <ExternalKBForm
-                      initKBId={kbId}
-                      onFormSubmit={() => onOpenChange(false)}
-                      onKBDeleted={() => {
-                        onKbDeleted();
-                        onOpenChange(false);
-                      }}
-                      onNewKBCreated={onNewKbCreated}
-                    />
-                  ))}
-                {activeMenu === 'documents' && kbType === 'builtin' && (
-                  <KBDoc kbId={kbId} />
+                {activeMenu === 'metadata' && (
+                  <KBForm
+                    initKbId={kbId}
+                    onNewKbCreated={onNewKbCreated}
+                    onKbUpdated={onKbUpdated}
+                  />
+                )}
+                {activeMenu === 'documents' && hasDocumentCapability() && (
+                  <KBDoc
+                    kbId={kbId}
+                    ragEngineName={kbInfo?.knowledge_engine?.name}
+                    ragEngineCapabilities={
+                      kbInfo?.knowledge_engine?.capabilities
+                    }
+                  />
+                )}
+                {activeMenu === 'retrieve' && (
+                  <KBRetrieveGeneric
+                    kbId={kbId}
+                    retrieveFunction={retrieveFunction}
+                  />
                 )}
-                {activeMenu === 'retrieve' &&
-                  (kbType === 'builtin' ? (
-                    <KBRetrieve kbId={kbId} />
-                  ) : (
-                    <ExternalKBRetrieve kbId={kbId} />
-                  ))}
               </div>
               {activeMenu === 'metadata' && (
                 <DialogFooter className="px-6 py-4 border-t shrink-0">
@@ -254,12 +260,7 @@ export default function KBDetailDialog({
                     >
                       {t('common.delete')}
                     </Button>
-                    <Button
-                      type="submit"
-                      form={
-                        kbType === 'builtin' ? 'kb-form' : 'external-kb-form'
-                      }
-                    >
+                    <Button type="submit" form="kb-form">
                       {t('common.save')}
                     </Button>
                     <Button
@@ -277,7 +278,7 @@ export default function KBDetailDialog({
         </DialogContent>
       </Dialog>
 
-      {/* 删除确认对话框 */}
+      {/* Delete confirmation dialog */}
       <Dialog open={showDeleteConfirm} onOpenChange={setShowDeleteConfirm}>
         <DialogContent>
           <DialogHeader>

web/src/app/home/knowledge/components/external-kb-card/ExternalKBCard.tsx

@@ -1,59 +0,0 @@
-import { ExternalKBCardVO } from '@/app/home/knowledge/components/external-kb-card/ExternalKBCardVO';
-import { useTranslation } from 'react-i18next';
-import styles from '../kb-card/KBCard.module.css';
-import { httpClient } from '@/app/infra/http/HttpClient';
-
-export default function ExternalKBCard({
-  kbCardVO,
-}: {
-  kbCardVO: ExternalKBCardVO;
-}) {
-  const { t } = useTranslation();
-  return (
-    <div className={`${styles.cardContainer}`}>
-      <div className={`${styles.basicInfoContainer}`}>
-        <div className={`${styles.iconBasicInfoContainer}`}>
-          {/* Emoji with plugin icon badge */}
-          <div className="relative">
-            <div className={`${styles.iconEmoji}`}>
-              {kbCardVO.emoji || '🔗'}
-            </div>
-            {/* Plugin icon badge at bottom right */}
-            <img
-              src={httpClient.getPluginIconURL(
-                kbCardVO.pluginAuthor,
-                kbCardVO.pluginName,
-              )}
-              alt="plugin icon"
-              className="absolute -bottom-1 -right-1 w-5 h-5 rounded-[20%]"
-            />
-          </div>
-
-          <div className={`${styles.basicInfoNameContainer}`}>
-            <div className={`${styles.basicInfoNameText}  ${styles.bigText}`}>
-              {kbCardVO.name}
-            </div>
-            <div className={`${styles.basicInfoDescriptionText}`}>
-              {kbCardVO.description}
-            </div>
-          </div>
-        </div>
-
-        <div className={`${styles.basicInfoLastUpdatedTimeContainer}`}>
-          <svg
-            className={`${styles.basicInfoUpdateTimeIcon}`}
-            xmlns="http://www.w3.org/2000/svg"
-            viewBox="0 0 24 24"
-            fill="currentColor"
-          >
-            <path d="M12 22C6.47715 22 2 17.5228 2 12C2 6.47715 6.47715 2 12 2C17.5228 2 22 6.47715 22 12C22 17.5228 17.5228 22 12 22ZM12 20C16.4183 20 20 16.4183 20 12C20 7.58172 16.4183 4 12 4C7.58172 4 4 7.58172 4 12C4 16.4183 7.58172 20 12 20ZM13 12H17V14H11V7H13V12Z"></path>
-          </svg>
-          <div className={`${styles.basicInfoUpdateTimeText}`}>
-            {t('knowledge.updateTime')}
-            {kbCardVO.lastUpdatedTimeAgo}
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}

web/src/app/home/knowledge/components/external-kb-card/ExternalKBCardVO.ts

@@ -1,43 +0,0 @@
-export class ExternalKBCardVO {
-  id: string;
-  name: string;
-  description: string;
-  emoji?: string;
-  retrieverName: string;
-  retrieverConfig: Record<string, unknown>;
-  lastUpdatedTimeAgo: string;
-  pluginAuthor: string;
-  pluginName: string;
-
-  constructor({
-    id,
-    name,
-    description,
-    emoji,
-    retrieverName,
-    retrieverConfig,
-    lastUpdatedTimeAgo,
-    pluginAuthor,
-    pluginName,
-  }: {
-    id: string;
-    name: string;
-    description: string;
-    emoji?: string;
-    retrieverName: string;
-    retrieverConfig: Record<string, unknown>;
-    lastUpdatedTimeAgo: string;
-    pluginAuthor: string;
-    pluginName: string;
-  }) {
-    this.id = id;
-    this.name = name;
-    this.description = description;
-    this.emoji = emoji;
-    this.retrieverName = retrieverName;
-    this.retrieverConfig = retrieverConfig;
-    this.lastUpdatedTimeAgo = lastUpdatedTimeAgo;
-    this.pluginAuthor = pluginAuthor;
-    this.pluginName = pluginName;
-  }
-}

web/src/app/home/knowledge/components/external-kb-form/ExternalKBForm.tsx

@@ -1,593 +0,0 @@
-import { useEffect, useState } from 'react';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { useForm } from 'react-hook-form';
-import { z } from 'zod';
-import { toast } from 'sonner';
-import { useTranslation } from 'react-i18next';
-import { UUID } from 'uuidjs';
-
-import {
-  DynamicFormItemConfig,
-  getDefaultValues,
-  parseDynamicFormItemType,
-} from '@/app/home/components/dynamic-form/DynamicFormItemConfig';
-import { IDynamicFormItemSchema } from '@/app/infra/entities/form/dynamic';
-import DynamicFormComponent from '@/app/home/components/dynamic-form/DynamicFormComponent';
-import { httpClient } from '@/app/infra/http/HttpClient';
-import { ExternalKnowledgeBase } from '@/app/infra/entities/api';
-import EmojiPicker from '@/components/ui/emoji-picker';
-import {
-  Dialog,
-  DialogContent,
-  DialogDescription,
-  DialogHeader,
-  DialogTitle,
-  DialogFooter,
-} from '@/components/ui/dialog';
-import { Button } from '@/components/ui/button';
-import {
-  Form,
-  FormControl,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormMessage,
-} from '@/components/ui/form';
-import { Input } from '@/components/ui/input';
-import {
-  Select,
-  SelectContent,
-  SelectGroup,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from '@/components/ui/select';
-import {
-  HoverCard,
-  HoverCardContent,
-  HoverCardTrigger,
-} from '@/components/ui/hover-card';
-import { extractI18nObject } from '@/i18n/I18nProvider';
-import { I18nObject } from '@/app/infra/entities/common';
-
-// Form schema
-const getFormSchema = (t: (key: string) => string) =>
-  z.object({
-    name: z.string().min(1, { message: t('knowledge.nameRequired') }),
-    description: z.string().optional(),
-    emoji: z.string().optional(),
-    plugin_author: z.string().min(1, { message: 'Please select a retriever' }),
-    plugin_name: z.string().min(1, { message: 'Please select a retriever' }),
-    retriever_name: z.string().min(1, { message: 'Please select a retriever' }),
-    retriever_config: z.record(z.string(), z.any()),
-  });
-
-// Retriever information interface
-interface RetrieverInfo {
-  plugin_author: string;
-  plugin_name: string;
-  retriever_name: string;
-  retriever_description: I18nObject;
-  manifest: {
-    manifest?: {
-      metadata?: {
-        label?: I18nObject;
-        description?: I18nObject;
-      };
-      spec?: {
-        config?: IDynamicFormItemSchema[];
-      };
-    };
-  };
-}
-
-interface ExternalKBFormProps {
-  initKBId?: string;
-  onFormSubmit: (value: z.infer<ReturnType<typeof getFormSchema>>) => void;
-  onKBDeleted: () => void;
-  onNewKBCreated: (kbId: string) => void;
-}
-
-export default function ExternalKBForm({
-  initKBId,
-  onFormSubmit,
-  onKBDeleted,
-  onNewKBCreated,
-}: ExternalKBFormProps) {
-  const { t } = useTranslation();
-  const formSchema = getFormSchema(t);
-
-  // Form setup
-  const form = useForm<z.infer<typeof formSchema>>({
-    resolver: zodResolver(formSchema),
-    defaultValues: {
-      name: '',
-      description: '',
-      emoji: '🔗',
-      plugin_author: '',
-      plugin_name: '',
-      retriever_name: '',
-      retriever_config: {},
-    },
-  });
-
-  // State management
-  const [showDeleteConfirmModal, setShowDeleteConfirmModal] = useState(false);
-  const [availableRetrievers, setAvailableRetrievers] = useState<
-    RetrieverInfo[]
-  >([]);
-  const [retrieverNameToConfigMap, setRetrieverNameToConfigMap] = useState(
-    new Map<string, IDynamicFormItemSchema[]>(),
-  );
-  const [showDynamicForm, setShowDynamicForm] = useState<boolean>(false);
-  const [dynamicFormConfigList, setDynamicFormConfigList] = useState<
-    IDynamicFormItemSchema[]
-  >([]);
-
-  // Initialize form when initKBId changes
-  useEffect(() => {
-    loadFormData();
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [initKBId]);
-
-  /**
-   * Load form data: initialize retrievers list and load KB config if editing
-   */
-  async function loadFormData() {
-    const configMap = await loadAvailableRetrievers();
-
-    if (initKBId) {
-      // Edit mode: load existing KB configuration
-      try {
-        const kbConfig = await loadKBConfig(initKBId);
-        // Set form values
-        form.setValue('name', kbConfig.name);
-        form.setValue('description', kbConfig.description || '');
-        form.setValue('emoji', kbConfig.emoji || '🔗');
-        form.setValue('plugin_author', kbConfig.plugin_author);
-        form.setValue('plugin_name', kbConfig.plugin_name);
-        form.setValue('retriever_name', kbConfig.retriever_name);
-        form.setValue('retriever_config', kbConfig.retriever_config);
-
-        // Load dynamic form for the selected retriever
-        const fullName = `${kbConfig.plugin_author}/${kbConfig.plugin_name}/${kbConfig.retriever_name}`;
-        loadDynamicFormConfig(fullName, configMap);
-      } catch (err) {
-        toast.error('Failed to load KB config: ' + (err as Error).message);
-      }
-    } else {
-      // Create mode: reset form
-      form.reset();
-    }
-  }
-
-  /**
-   * Load available retrievers from API and build config map
-   */
-  async function loadAvailableRetrievers(): Promise<
-    Map<string, IDynamicFormItemSchema[]>
-  > {
-    const retrieversRes = await httpClient.listKnowledgeRetrievers();
-    setAvailableRetrievers((retrieversRes.retrievers || []) as RetrieverInfo[]);
-
-    // Build retriever name to config map
-    const configMap = new Map<string, IDynamicFormItemSchema[]>();
-    ((retrieversRes.retrievers || []) as RetrieverInfo[]).forEach(
-      (retriever) => {
-        const fullName = `${retriever.plugin_author}/${retriever.plugin_name}/${retriever.retriever_name}`;
-        const configSchema = retriever.manifest?.manifest?.spec?.config || [];
-
-        configMap.set(
-          fullName,
-          configSchema.map(
-            (item) =>
-              new DynamicFormItemConfig({
-                default: item.default,
-                id: UUID.generate(),
-                label: item.label,
-                description: item.description,
-                name: item.name,
-                required: item.required,
-                type: parseDynamicFormItemType(item.type),
-                options: item.options,
-              }),
-          ),
-        );
-      },
-    );
-
-    setRetrieverNameToConfigMap(configMap);
-    return configMap;
-  }
-
-  /**
-   * Load KB configuration from API
-   */
-  async function loadKBConfig(
-    kbId: string,
-  ): Promise<z.infer<typeof formSchema>> {
-    const res = await httpClient.getExternalKnowledgeBase(kbId);
-    const kb = res.base;
-    return {
-      name: kb.name,
-      description: kb.description,
-      emoji: kb.emoji || '🔗',
-      plugin_author: kb.plugin_author,
-      plugin_name: kb.plugin_name,
-      retriever_name: kb.retriever_name,
-      retriever_config: kb.retriever_config || {},
-    };
-  }
-
-  /**
-   * Load dynamic form configuration for selected retriever
-   * @param fullRetrieverName - Full retriever name in format: plugin_author/plugin_name/retriever_name
-   * @param configMapOverride - Optional config map to use (for initial load)
-   */
-  function loadDynamicFormConfig(
-    fullRetrieverName: string,
-    configMapOverride?: Map<string, IDynamicFormItemSchema[]>,
-  ) {
-    if (!fullRetrieverName) {
-      setShowDynamicForm(false);
-      return;
-    }
-
-    // Use provided config map or fall back to state
-    const configMap = configMapOverride || retrieverNameToConfigMap;
-    const configList = configMap.get(fullRetrieverName);
-
-    if (configList && configList.length > 0) {
-      setDynamicFormConfigList(configList);
-      setShowDynamicForm(true);
-
-      // Only reset to default values when manually selecting (not initial load)
-      if (!configMapOverride) {
-        form.setValue('retriever_config', getDefaultValues(configList));
-      }
-    } else {
-      setShowDynamicForm(false);
-      if (!configMapOverride) {
-        form.setValue('retriever_config', {});
-      }
-    }
-  }
-
-  /**
-   * Handle retriever selection change
-   */
-  function handleRetrieverSelect(fullRetrieverName: string) {
-    if (!fullRetrieverName) {
-      setShowDynamicForm(false);
-      return;
-    }
-
-    // Parse and update form fields
-    const parts = fullRetrieverName.split('/');
-    if (parts.length === 3) {
-      form.setValue('plugin_author', parts[0]);
-      form.setValue('plugin_name', parts[1]);
-      form.setValue('retriever_name', parts[2]);
-    }
-
-    // Load dynamic form configuration
-    loadDynamicFormConfig(fullRetrieverName);
-  }
-
-  /**
-   * Handle form submission (create or update)
-   */
-  function handleFormSubmit() {
-    const formData: ExternalKnowledgeBase = {
-      name: form.getValues().name,
-      description: form.getValues().description || '',
-      emoji: form.getValues().emoji,
-      plugin_author: form.getValues().plugin_author,
-      plugin_name: form.getValues().plugin_name,
-      retriever_name: form.getValues().retriever_name,
-      retriever_config: form.getValues().retriever_config,
-    };
-
-    if (initKBId) {
-      // Update existing KB
-      httpClient
-        .updateExternalKnowledgeBase(initKBId, { ...formData, uuid: initKBId })
-        .then(() => {
-          onFormSubmit(form.getValues());
-          toast.success(t('knowledge.updateExternalSuccess'));
-        })
-        .catch((err) => {
-          toast.error('Failed to update KB: ' + err.msg);
-        });
-    } else {
-      // Create new KB
-      httpClient
-        .createExternalKnowledgeBase(formData)
-        .then((res) => {
-          toast.success(t('knowledge.createExternalSuccess'));
-          onNewKBCreated(res.uuid);
-          form.reset();
-        })
-        .catch((err) => {
-          toast.error('Failed to create KB: ' + err.msg);
-        });
-    }
-  }
-
-  /**
-   * Handle KB deletion
-   */
-  function handleDelete() {
-    if (!initKBId) return;
-
-    httpClient
-      .deleteExternalKnowledgeBase(initKBId)
-      .then(() => {
-        onKBDeleted();
-        toast.success(t('knowledge.deleteExternalSuccess'));
-      })
-      .catch((err) => {
-        toast.error('Failed to delete KB: ' + err.msg);
-      });
-  }
-
-  /**
-   * Get retriever label with i18n support
-   */
-  function getRetrieverLabel(fullName: string): string {
-    const retriever = availableRetrievers.find(
-      (r) =>
-        `${r.plugin_author}/${r.plugin_name}/${r.retriever_name}` === fullName,
-    );
-    return retriever?.manifest?.manifest?.metadata?.label
-      ? extractI18nObject(retriever.manifest.manifest.metadata.label)
-      : fullName;
-  }
-
-  // Compute full retriever name for display
-  const currentRetrieverFullName =
-    form.watch('plugin_author') &&
-    form.watch('plugin_name') &&
-    form.watch('retriever_name')
-      ? `${form.watch('plugin_author')}/${form.watch(
-          'plugin_name',
-        )}/${form.watch('retriever_name')}`
-      : '';
-
-  return (
-    <div>
-      {/* Delete Confirmation Dialog */}
-      <Dialog
-        open={showDeleteConfirmModal}
-        onOpenChange={setShowDeleteConfirmModal}
-      >
-        <DialogContent>
-          <DialogHeader>
-            <DialogTitle>{t('common.confirmDelete')}</DialogTitle>
-          </DialogHeader>
-          <DialogDescription>
-            {t('knowledge.deleteConfirmation')}
-          </DialogDescription>
-          <DialogFooter>
-            <Button
-              variant="outline"
-              onClick={() => setShowDeleteConfirmModal(false)}
-            >
-              {t('common.cancel')}
-            </Button>
-            <Button
-              variant="destructive"
-              onClick={() => {
-                handleDelete();
-                setShowDeleteConfirmModal(false);
-              }}
-            >
-              {t('common.confirmDelete')}
-            </Button>
-          </DialogFooter>
-        </DialogContent>
-      </Dialog>
-
-      {/* Main Form */}
-      <Form {...form}>
-        <form
-          id="external-kb-form"
-          onSubmit={form.handleSubmit(handleFormSubmit)}
-          className="space-y-8"
-        >
-          <div className="space-y-4">
-            {/* KB Name and Emoji in same row */}
-            <div className="flex gap-4 items-start">
-              <FormField
-                control={form.control}
-                name="name"
-                render={({ field }) => (
-                  <FormItem className="flex-1">
-                    <FormLabel>
-                      {t('knowledge.kbName')}
-                      <span className="text-red-500">*</span>
-                    </FormLabel>
-                    <FormControl>
-                      <Input {...field} />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-              <FormField
-                control={form.control}
-                name="emoji"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel>{t('common.icon')}</FormLabel>
-                    <FormControl>
-                      <EmojiPicker
-                        value={field.value}
-                        onChange={field.onChange}
-                      />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-            </div>
-
-            {/* KB Description */}
-            <FormField
-              control={form.control}
-              name="description"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>{t('knowledge.kbDescription')}</FormLabel>
-                  <FormControl>
-                    <Input {...field} />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            {/* Retriever Selector */}
-            <FormField
-              control={form.control}
-              name="retriever_name"
-              render={() => (
-                <FormItem>
-                  <FormLabel>
-                    {t('knowledge.retriever')}
-                    <span className="text-red-500">*</span>
-                  </FormLabel>
-                  <FormControl>
-                    <Select
-                      onValueChange={handleRetrieverSelect}
-                      value={currentRetrieverFullName}
-                    >
-                      <SelectTrigger className="w-full bg-[#ffffff] dark:bg-[#2a2a2e]">
-                        <SelectValue
-                          placeholder={t('knowledge.selectRetriever')}
-                        />
-                      </SelectTrigger>
-                      <SelectContent className="fixed z-[1000]">
-                        <SelectGroup>
-                          {availableRetrievers.map((retriever) => {
-                            const fullName = `${retriever.plugin_author}/${retriever.plugin_name}/${retriever.retriever_name}`;
-                            const label = retriever.manifest?.manifest?.metadata
-                              ?.label
-                              ? extractI18nObject(
-                                  retriever.manifest.manifest.metadata.label,
-                                )
-                              : retriever.retriever_name;
-                            const description = extractI18nObject(
-                              retriever.retriever_description,
-                            );
-
-                            return (
-                              <HoverCard
-                                key={fullName}
-                                openDelay={0}
-                                closeDelay={0}
-                              >
-                                <HoverCardTrigger asChild>
-                                  <SelectItem value={fullName}>
-                                    {label}
-                                  </SelectItem>
-                                </HoverCardTrigger>
-                                <HoverCardContent
-                                  className="w-80 data-[state=open]:animate-none"
-                                  align="end"
-                                  side="right"
-                                  sideOffset={10}
-                                >
-                                  <div className="space-y-2">
-                                    <div className="flex items-start gap-3">
-                                      <img
-                                        src={httpClient.getPluginIconURL(
-                                          retriever.plugin_author,
-                                          retriever.plugin_name,
-                                        )}
-                                        alt="plugin icon"
-                                        className="w-10 h-10 rounded-[8%] flex-shrink-0"
-                                      />
-                                      <div className="flex flex-col gap-1 flex-1 min-w-0">
-                                        <h4 className="font-medium text-sm">
-                                          {label}
-                                        </h4>
-                                        <p className="text-xs text-muted-foreground">
-                                          {retriever.plugin_author} /{' '}
-                                          {retriever.plugin_name}
-                                        </p>
-                                      </div>
-                                    </div>
-                                    {description && (
-                                      <p className="text-sm text-muted-foreground">
-                                        {description}
-                                      </p>
-                                    )}
-                                  </div>
-                                </HoverCardContent>
-                              </HoverCard>
-                            );
-                          })}
-                        </SelectGroup>
-                      </SelectContent>
-                    </Select>
-                  </FormControl>
-                  <FormMessage />
-                  <p className="text-sm text-muted-foreground">
-                    {t('knowledge.retrieverInstallInfo')}{' '}
-                    <a
-                      href="https://space.langbot.app/market?category=KnowledgeRetriever"
-                      target="_blank"
-                      rel="noopener noreferrer"
-                      className="text-primary underline hover:no-underline"
-                    >
-                      {t('knowledge.retrieverMarketLink')}
-                    </a>
-                  </p>
-                </FormItem>
-              )}
-            />
-
-            {/* Selected Retriever Card */}
-            {currentRetrieverFullName && (
-              <div className="flex items-start gap-3 p-4 rounded-lg border">
-                <img
-                  src={httpClient.getPluginIconURL(
-                    form.watch('plugin_author'),
-                    form.watch('plugin_name'),
-                  )}
-                  alt="plugin icon"
-                  className="w-12 h-12 rounded-[8%] flex-shrink-0"
-                />
-                <div className="flex flex-col gap-1">
-                  <div className="font-medium">
-                    {getRetrieverLabel(currentRetrieverFullName)}
-                  </div>
-                  <div className="text-sm text-gray-500">
-                    {form.watch('plugin_author')} / {form.watch('plugin_name')}
-                  </div>
-                </div>
-              </div>
-            )}
-
-            {/* Dynamic Retriever Configuration Form */}
-            {showDynamicForm && dynamicFormConfigList.length > 0 && (
-              <div className="space-y-4">
-                <div className="text-lg font-medium">
-                  {t('knowledge.retrieverConfiguration')}
-                </div>
-                <DynamicFormComponent
-                  itemConfigList={dynamicFormConfigList}
-                  initialValues={form.watch('retriever_config')}
-                  onSubmit={(values) => {
-                    form.setValue('retriever_config', values);
-                  }}
-                />
-              </div>
-            )}
-          </div>
-        </form>
-      </Form>
-    </div>
-  );
-}

web/src/app/home/knowledge/components/kb-card/KBCard.module.css

@@ -169,3 +169,18 @@
   width: 1.2rem;
   height: 1.2rem;
 }
+
+.engineBadge {
+  font-size: 0.75rem;
+  line-height: 1rem;
+  padding: 0.125rem 0.5rem;
+  border-radius: 9999px;
+  background-color: #f3e8ff;
+  color: #7e22ce;
+  white-space: nowrap;
+}
+
+:global(.dark) .engineBadge {
+  background-color: #581c87;
+  color: #d8b4fe;
+}

web/src/app/home/knowledge/components/kb-card/KBCard.tsx

@@ -4,14 +4,21 @@ import styles from './KBCard.module.css';
 
 export default function KBCard({ kbCardVO }: { kbCardVO: KnowledgeBaseVO }) {
   const { t } = useTranslation();
+
   return (
     <div className={`${styles.cardContainer}`}>
       <div className={`${styles.basicInfoContainer}`}>
         <div className={`${styles.iconBasicInfoContainer}`}>
           <div className={`${styles.iconEmoji}`}>{kbCardVO.emoji || '📚'}</div>
           <div className={`${styles.basicInfoNameContainer}`}>
-            <div className={`${styles.basicInfoNameText}  ${styles.bigText}`}>
-              {kbCardVO.name}
+            <div className="flex items-center gap-2">
+              <div className={`${styles.basicInfoNameText} ${styles.bigText}`}>
+                {kbCardVO.name}
+              </div>
+              {/* Engine badge */}
+              <span className={styles.engineBadge}>
+                {kbCardVO.getEngineName()}
+              </span>
             </div>
             <div className={`${styles.basicInfoDescriptionText}`}>
               {kbCardVO.description}

web/src/app/home/knowledge/components/kb-card/KBCardVO.ts

@@ -1,29 +1,52 @@
+import { KnowledgeEngineInfo } from '@/app/infra/entities/api';
+import { extractI18nObject } from '@/i18n/I18nProvider';
+
 export interface IKnowledgeBaseVO {
   id: string;
   name: string;
   description: string;
-  embeddingModelUUID: string;
-  top_k: number;
   lastUpdatedTimeAgo: string;
   emoji?: string;
+  ragEngine?: KnowledgeEngineInfo;
+  ragEnginePluginId?: string;
 }
 
 export class KnowledgeBaseVO implements IKnowledgeBaseVO {
   id: string;
   name: string;
   description: string;
-  embeddingModelUUID: string;
-  top_k: number;
   lastUpdatedTimeAgo: string;
   emoji?: string;
+  ragEngine?: KnowledgeEngineInfo;
+  ragEnginePluginId?: string;
 
   constructor(props: IKnowledgeBaseVO) {
     this.id = props.id;
     this.name = props.name;
     this.description = props.description;
-    this.embeddingModelUUID = props.embeddingModelUUID;
-    this.top_k = props.top_k;
     this.lastUpdatedTimeAgo = props.lastUpdatedTimeAgo;
     this.emoji = props.emoji;
+    this.ragEngine = props.ragEngine;
+    this.ragEnginePluginId = props.ragEnginePluginId;
+  }
+
+  /**
+   * Check if this KB supports document management
+   */
+  hasDocumentCapability(): boolean {
+    if (!this.ragEngine) {
+      return false;
+    }
+    return this.ragEngine.capabilities.includes('doc_ingestion');
+  }
+
+  /**
+   * Get display name for the Knowledge Engine
+   */
+  getEngineName(): string {
+    if (!this.ragEngine) {
+      return 'Unknown';
+    }
+    return extractI18nObject(this.ragEngine.name);
   }
 }

web/src/app/home/knowledge/components/kb-docs/FileUploadZone.tsx

@@ -1,17 +1,32 @@
-import React, { useCallback, useState } from 'react';
+import React, { useCallback, useEffect, useState } from 'react';
 import { Card, CardContent } from '@/components/ui/card';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { Button } from '@/components/ui/button';
 import { httpClient } from '@/app/infra/http/HttpClient';
 import { toast } from 'sonner';
 import { useTranslation } from 'react-i18next';
+import { ParserInfo } from '@/app/infra/entities/api';
+import { CustomApiError, I18nObject } from '@/app/infra/entities/common';
+import { extractI18nObject } from '@/i18n/I18nProvider';
 
 interface FileUploadZoneProps {
   kbId: string;
+  ragEngineName?: I18nObject;
+  ragEngineCapabilities?: string[];
   onUploadSuccess: () => void;
   onUploadError: (error: string) => void;
 }
 
 export default function FileUploadZone({
   kbId,
+  ragEngineName,
+  ragEngineCapabilities,
   onUploadSuccess,
   onUploadError,
 }: FileUploadZoneProps) {
@@ -19,7 +34,85 @@ export default function FileUploadZone({
   const [isDragOver, setIsDragOver] = useState(false);
   const [isUploading, setIsUploading] = useState(false);
 
-  const handleUpload = useCallback(
+  // Parser selection state
+  const [pendingFile, setPendingFile] = useState<File | null>(null);
+  const [availableParsers, setAvailableParsers] = useState<ParserInfo[]>([]);
+  const [selectedParser, setSelectedParser] = useState<string>('builtin');
+  const [loadingParsers, setLoadingParsers] = useState(false);
+
+  // Whether the Knowledge Engine natively supports document parsing.
+  // This is a coarse-grained capability check rather than per-MIME-type filtering.
+  // Fine-grained MIME type declaration (e.g. supported_parse_mime_types on the engine)
+  // would require changes across the SDK, backend, and frontend prop chain;
+  // using an engine-level capability flag keeps the change minimal.
+  const ragEngineCanParse =
+    ragEngineCapabilities?.includes('doc_parsing') ?? false;
+
+  // When a file is selected, check for available parsers
+  useEffect(() => {
+    if (!pendingFile) return;
+
+    const mimeType = pendingFile.type || undefined;
+    setLoadingParsers(true);
+    httpClient
+      .listParsers(mimeType)
+      .then((resp) => {
+        const parsers = resp.parsers || [];
+        setAvailableParsers(parsers);
+        if (ragEngineCanParse) {
+          setSelectedParser('builtin');
+        } else if (parsers.length > 0) {
+          setSelectedParser(parsers[0].plugin_id);
+        } else {
+          setSelectedParser('');
+        }
+      })
+      .catch(() => {
+        setAvailableParsers([]);
+      })
+      .finally(() => {
+        setLoadingParsers(false);
+      });
+  }, [pendingFile, ragEngineCanParse]);
+
+  const doUpload = useCallback(
+    async (file: File, parserPluginId?: string) => {
+      setIsUploading(true);
+      const toastId = toast.loading(t('knowledge.documentsTab.uploadingFile'));
+
+      try {
+        // Step 1: Upload file to server
+        const uploadResult = await httpClient.uploadDocumentFile(file);
+
+        // Step 2: Associate file with knowledge base (with optional parser)
+        await httpClient.uploadKnowledgeBaseFile(
+          kbId,
+          uploadResult.file_id,
+          parserPluginId,
+        );
+
+        toast.success(t('knowledge.documentsTab.uploadSuccess'), {
+          id: toastId,
+        });
+        onUploadSuccess();
+      } catch (error) {
+        console.error('File upload failed:', error);
+        const errorMessage =
+          t('knowledge.documentsTab.uploadError') +
+          (error as CustomApiError).msg;
+        toast.error(errorMessage, { id: toastId });
+        onUploadError(errorMessage);
+      } finally {
+        setIsUploading(false);
+        setPendingFile(null);
+        setAvailableParsers([]);
+        setSelectedParser('builtin');
+      }
+    },
+    [kbId, onUploadSuccess, onUploadError, t],
+  );
+
+  const handleFileSelected = useCallback(
     async (file: File) => {
       if (isUploading) return;
 
@@ -30,32 +123,46 @@ export default function FileUploadZone({
         return;
       }
 
-      setIsUploading(true);
-      const toastId = toast.loading(t('knowledge.documentsTab.uploadingFile'));
-
-      try {
-        // Step 1: Upload file to server
-        const uploadResult = await httpClient.uploadDocumentFile(file);
-
-        // Step 2: Associate file with knowledge base
-        await httpClient.uploadKnowledgeBaseFile(kbId, uploadResult.file_id);
-
-        toast.success(t('knowledge.documentsTab.uploadSuccess'), {
-          id: toastId,
-        });
-        onUploadSuccess();
-      } catch (error) {
-        console.error('File upload failed:', error);
-        const errorMessage = t('knowledge.documentsTab.uploadError');
-        toast.error(errorMessage, { id: toastId });
-        onUploadError(errorMessage);
-      } finally {
-        setIsUploading(false);
-      }
+      // Set loadingParsers=true BEFORE pendingFile so both state updates
+      // batch together in the same render. This prevents the auto-upload
+      // effect from firing before parser fetch completes.
+      setLoadingParsers(true);
+      setPendingFile(file);
     },
-    [kbId, isUploading, onUploadSuccess, onUploadError, t],
+    [isUploading, t],
   );
 
+  // Auto-upload if Knowledge Engine can parse and no external parsers available
+  useEffect(() => {
+    if (
+      pendingFile &&
+      !loadingParsers &&
+      ragEngineCanParse &&
+      availableParsers.length === 0
+    ) {
+      doUpload(pendingFile);
+    }
+  }, [
+    pendingFile,
+    loadingParsers,
+    ragEngineCanParse,
+    availableParsers,
+    doUpload,
+  ]);
+
+  const handleConfirmUpload = useCallback(() => {
+    if (!pendingFile) return;
+    const parserPluginId =
+      selectedParser === 'builtin' ? undefined : selectedParser;
+    doUpload(pendingFile, parserPluginId);
+  }, [pendingFile, selectedParser, doUpload]);
+
+  const handleCancelUpload = useCallback(() => {
+    setPendingFile(null);
+    setAvailableParsers([]);
+    setSelectedParser('builtin');
+  }, []);
+
   const handleDragOver = useCallback((e: React.DragEvent) => {
     e.preventDefault();
     setIsDragOver(true);
@@ -73,79 +180,145 @@ export default function FileUploadZone({
 
       const files = Array.from(e.dataTransfer.files);
       if (files.length > 0) {
-        handleUpload(files[0]);
+        handleFileSelected(files[0]);
       }
     },
-    [handleUpload],
+    [handleFileSelected],
   );
 
   const handleFileSelect = useCallback(
     (e: React.ChangeEvent<HTMLInputElement>) => {
       const files = e.target.files;
       if (files && files.length > 0) {
-        handleUpload(files[0]);
+        handleFileSelected(files[0]);
       }
+      // Reset the input so the same file can be selected again
+      e.target.value = '';
     },
-    [handleUpload],
+    [handleFileSelected],
   );
 
+  // Show parser selection UI when there are choices to make, or when no parser is available
+  const showParserSelector =
+    pendingFile &&
+    !loadingParsers &&
+    (availableParsers.length > 0 || !ragEngineCanParse);
+
+  const noParserAvailable = !ragEngineCanParse && availableParsers.length === 0;
+
   return (
     <Card className="mb-4">
       <CardContent className="p-4">
-        <div
-          className={`
-            relative border-2 border-dashed rounded-lg p-4 text-center transition-colors
-            ${
-              isDragOver
-                ? 'border-blue-500 bg-blue-50'
-                : 'border-gray-300 hover:border-gray-400'
-            }
-            ${isUploading ? 'opacity-50 pointer-events-none' : ''}
-          `}
-          onDragOver={handleDragOver}
-          onDragLeave={handleDragLeave}
-          onDrop={handleDrop}
-        >
-          <input
-            type="file"
-            id="file-upload"
-            className="hidden"
-            onChange={handleFileSelect}
-            accept=".pdf,.doc,.docx,.txt,.md,.html,.zip"
-            disabled={isUploading}
-          />
-
-          <label htmlFor="file-upload" className="cursor-pointer block">
-            <div className="space-y-2">
-              <div className="mx-auto w-10 h-10 bg-gray-100 rounded-full flex items-center justify-center">
-                <svg
-                  className="w-5 h-5 text-gray-400"
-                  fill="none"
-                  stroke="currentColor"
-                  viewBox="0 0 24 24"
+        {showParserSelector ? (
+          <div className="space-y-3">
+            <p className="text-sm font-medium text-gray-900 dark:text-gray-100">
+              {pendingFile.name}
+            </p>
+            {noParserAvailable ? (
+              <div className="rounded-md bg-yellow-50 dark:bg-yellow-900/20 border border-yellow-200 dark:border-yellow-800 p-3">
+                <p className="text-sm text-yellow-800 dark:text-yellow-200">
+                  {t('knowledge.documentsTab.noParserAvailable')}
+                </p>
+              </div>
+            ) : (
+              <div className="space-y-2">
+                <label className="text-sm text-gray-600 dark:text-gray-400">
+                  {t('knowledge.documentsTab.selectParser')}
+                </label>
+                <Select
+                  value={selectedParser}
+                  onValueChange={setSelectedParser}
                 >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    strokeWidth={2}
-                    d="M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12"
-                  />
-                </svg>
-              </div>
-
-              <div>
-                <p className="text-base font-medium text-gray-900 dark:text-gray-100">
-                  {isUploading
-                    ? t('knowledge.documentsTab.uploading')
-                    : t('knowledge.documentsTab.dragAndDrop')}
-                </p>
-                <p className="text-xs text-gray-500 mt-1 dark:text-gray-400">
-                  {t('knowledge.documentsTab.supportedFormats')}
-                </p>
+                  <SelectTrigger className="w-full">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {ragEngineCanParse && (
+                      <SelectItem value="builtin">
+                        {ragEngineName
+                          ? extractI18nObject(ragEngineName)
+                          : t('knowledge.documentsTab.builtInParser')}
+                      </SelectItem>
+                    )}
+                    {availableParsers.map((parser) => (
+                      <SelectItem
+                        key={parser.plugin_id}
+                        value={parser.plugin_id}
+                      >
+                        {extractI18nObject(parser.name)}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
               </div>
+            )}
+            <div className="flex justify-end gap-2">
+              <Button variant="outline" size="sm" onClick={handleCancelUpload}>
+                {t('knowledge.documentsTab.cancelUpload')}
+              </Button>
+              {!noParserAvailable && (
+                <Button size="sm" onClick={handleConfirmUpload}>
+                  {t('knowledge.documentsTab.confirmUpload')}
+                </Button>
+              )}
             </div>
-          </label>
-        </div>
+          </div>
+        ) : (
+          <div
+            className={`
+              relative border-2 border-dashed rounded-lg p-4 text-center transition-colors
+              ${
+                isDragOver
+                  ? 'border-blue-500 bg-blue-50'
+                  : 'border-gray-300 hover:border-gray-400'
+              }
+              ${isUploading || loadingParsers ? 'opacity-50 pointer-events-none' : ''}
+            `}
+            onDragOver={handleDragOver}
+            onDragLeave={handleDragLeave}
+            onDrop={handleDrop}
+          >
+            <input
+              type="file"
+              id="file-upload"
+              className="hidden"
+              onChange={handleFileSelect}
+              accept=".pdf,.doc,.docx,.txt,.md,.html,.zip"
+              disabled={isUploading || loadingParsers}
+            />
+
+            <label htmlFor="file-upload" className="cursor-pointer block">
+              <div className="space-y-2">
+                <div className="mx-auto w-10 h-10 bg-gray-100 rounded-full flex items-center justify-center">
+                  <svg
+                    className="w-5 h-5 text-gray-400"
+                    fill="none"
+                    stroke="currentColor"
+                    viewBox="0 0 24 24"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12"
+                    />
+                  </svg>
+                </div>
+
+                <div>
+                  <p className="text-base font-medium text-gray-900 dark:text-gray-100">
+                    {isUploading
+                      ? t('knowledge.documentsTab.uploading')
+                      : t('knowledge.documentsTab.dragAndDrop')}
+                  </p>
+                  <p className="text-xs text-gray-500 mt-1 dark:text-gray-400">
+                    {t('knowledge.documentsTab.supportedFormats')}
+                  </p>
+                </div>
+              </div>
+            </label>
+          </div>
+        )}
       </CardContent>
     </Card>
   );

web/src/app/home/knowledge/components/kb-docs/KBDoc.tsx

@@ -1,48 +1,80 @@
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import { httpClient } from '@/app/infra/http/HttpClient';
 import { KnowledgeBaseFile } from '@/app/infra/entities/api';
+import { I18nObject, CustomApiError } from '@/app/infra/entities/common';
 import { columns, DocumentFile } from './documents/columns';
 import { DataTable } from './documents/data-table';
 import FileUploadZone from './FileUploadZone';
 import { toast } from 'sonner';
 import { useTranslation } from 'react-i18next';
 
-export default function KBDoc({ kbId }: { kbId: string }) {
+export default function KBDoc({
+  kbId,
+  ragEngineName,
+  ragEngineCapabilities,
+}: {
+  kbId: string;
+  ragEngineName?: I18nObject;
+  ragEngineCapabilities?: string[];
+}) {
   const [documentsList, setDocumentsList] = useState<DocumentFile[]>([]);
   const { t } = useTranslation();
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
 
-  useEffect(() => {
-    getDocumentsList();
-
-    const intervalId = setInterval(() => {
-      getDocumentsList();
-    }, 5000);
-
-    return () => {
-      clearInterval(intervalId);
-    };
+  const getDocumentsList = useCallback(async () => {
+    const resp = await httpClient.getKnowledgeBaseFiles(kbId);
+    const files = resp.files.map((file: KnowledgeBaseFile) => ({
+      uuid: file.uuid,
+      name: file.file_name,
+      status: file.status,
+    }));
+    setDocumentsList(files);
+    return files;
   }, [kbId]);
 
-  async function getDocumentsList() {
-    const resp = await httpClient.getKnowledgeBaseFiles(kbId);
-    setDocumentsList(
-      resp.files.map((file: KnowledgeBaseFile) => {
-        return {
-          uuid: file.uuid,
-          name: file.file_name,
-          status: file.status,
-        };
-      }),
-    );
-  }
+  const startPolling = useCallback(() => {
+    if (intervalRef.current) return;
+    intervalRef.current = setInterval(() => {
+      getDocumentsList().then((files) => {
+        const allDone =
+          files.length > 0 &&
+          files.every(
+            (doc: DocumentFile) =>
+              doc.status === 'completed' || doc.status === 'failed',
+          );
+        if (allDone && intervalRef.current) {
+          clearInterval(intervalRef.current);
+          intervalRef.current = null;
+        }
+      });
+    }, 5000);
+  }, [getDocumentsList]);
+
+  useEffect(() => {
+    getDocumentsList().then((files) => {
+      const hasProcessing = files.some(
+        (doc: DocumentFile) =>
+          doc.status !== 'completed' && doc.status !== 'failed',
+      );
+      if (hasProcessing) {
+        startPolling();
+      }
+    });
+
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+        intervalRef.current = null;
+      }
+    };
+  }, [kbId, getDocumentsList, startPolling]);
 
   const handleUploadSuccess = () => {
-    // Refresh document list after successful upload
     getDocumentsList();
+    startPolling();
   };
 
   const handleUploadError = (error: string) => {
-    // Error messages are already handled by toast in FileUploadZone component
     console.error('Upload failed:', error);
   };
 
@@ -55,7 +87,10 @@ export default function KBDoc({ kbId }: { kbId: string }) {
       })
       .catch((error) => {
         console.error('Delete failed:', error);
-        toast.error(t('knowledge.documentsTab.fileDeleteFailed'));
+        toast.error(
+          t('knowledge.documentsTab.fileDeleteFailed') +
+            (error as CustomApiError).msg,
+        );
       });
   };
 
@@ -63,6 +98,8 @@ export default function KBDoc({ kbId }: { kbId: string }) {
     <div className="container mx-auto py-2">
       <FileUploadZone
         kbId={kbId}
+        ragEngineName={ragEngineName}
+        ragEngineCapabilities={ragEngineCapabilities}
         onUploadSuccess={handleUploadSuccess}
         onUploadError={handleUploadError}
       />

web/src/app/home/knowledge/components/kb-form/KBForm.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useState } from 'react';
+import Link from 'next/link';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
@@ -14,18 +15,26 @@ import {
   FormMessage,
   FormDescription,
 } from '@/components/ui/form';
-import { httpClient, systemInfo, userInfo } from '@/app/infra/http';
+import { httpClient } from '@/app/infra/http/HttpClient';
 import {
   Select,
   SelectContent,
-  SelectGroup,
   SelectItem,
-  SelectLabel,
   SelectTrigger,
   SelectValue,
 } from '@/components/ui/select';
-import { KnowledgeBase, EmbeddingModel } from '@/app/infra/entities/api';
+import { KnowledgeBase, KnowledgeEngine } from '@/app/infra/entities/api';
+import { CustomApiError } from '@/app/infra/entities/common';
 import { toast } from 'sonner';
+import { extractI18nObject } from '@/i18n/I18nProvider';
+import DynamicFormComponent from '@/app/home/components/dynamic-form/DynamicFormComponent';
+import { IDynamicFormItemSchema } from '@/app/infra/entities/form/dynamic';
+import {
+  DynamicFormItemConfig,
+  getDefaultValues,
+  parseDynamicFormItemType,
+} from '@/app/home/components/dynamic-form/DynamicFormItemConfig';
+import { UUID } from 'uuidjs';
 
 const getFormSchema = (t: (key: string) => string) =>
   z.object({
@@ -34,15 +43,42 @@ const getFormSchema = (t: (key: string) => string) =>
       .string()
       .min(1, { message: t('knowledge.kbDescriptionRequired') }),
     emoji: z.string().optional(),
-    embeddingModelUUID: z
+    ragEngineId: z
       .string()
-      .min(1, { message: t('knowledge.embeddingModelUUIDRequired') }),
-    top_k: z
-      .number()
-      .min(1, { message: t('knowledge.topKRequired') })
-      .max(30, { message: t('knowledge.topKMax') }),
+      .min(1, { message: t('knowledge.knowledgeEngineRequired') }),
   });
 
+/**
+ * Parse creation schema from Knowledge Engine to IDynamicFormItemSchema[]
+ * Same pattern as ExternalKBForm uses for retriever config
+ */
+function parseCreationSchema(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schemaItems: any | any[] | undefined,
+): IDynamicFormItemSchema[] {
+  if (!schemaItems) return [];
+
+  // Handle wrapped schema (e.g. { schema: [...] }) which might be returned by the API
+  const items = Array.isArray(schemaItems) ? schemaItems : schemaItems.schema;
+
+  if (!items || !Array.isArray(items)) return [];
+
+  return items.map(
+    (item) =>
+      new DynamicFormItemConfig({
+        default: item.default,
+        id: UUID.generate(),
+        label: item.label,
+        description: item.description,
+        name: item.name,
+        required: item.required,
+        type: parseDynamicFormItemType(item.type),
+        options: item.options,
+        show_if: item.show_if,
+      }),
+  );
+}
+
 export default function KBForm({
   initKbId,
   onNewKbCreated,
@@ -53,6 +89,17 @@ export default function KBForm({
   onKbUpdated: (kbId: string) => void;
 }) {
   const { t } = useTranslation();
+  const [ragEngines, setRagEngines] = useState<KnowledgeEngine[]>([]);
+  const [selectedEngineId, setSelectedEngineId] = useState<string>('');
+  const [configSettings, setConfigSettings] = useState<Record<string, unknown>>(
+    {},
+  );
+  const [retrievalSettings, setRetrievalSettings] = useState<
+    Record<string, unknown>
+  >({});
+  const [isEditing, setIsEditing] = useState(false);
+  const [loading, setLoading] = useState(true);
+
   const formSchema = getFormSchema(t);
 
   const form = useForm<z.infer<typeof formSchema>>({
@@ -61,98 +108,173 @@ export default function KBForm({
       name: '',
       description: t('knowledge.defaultDescription'),
       emoji: '📚',
-      embeddingModelUUID: '',
-      top_k: 5,
+      ragEngineId: '',
     },
   });
 
-  const [embeddingModels, setEmbeddingModels] = useState<EmbeddingModel[]>([]);
+  // Get selected engine details
+  const selectedEngine = ragEngines.find(
+    (e) => e.plugin_id === selectedEngineId,
+  );
 
   useEffect(() => {
-    getEmbeddingModelNameList().then(() => {
+    loadRagEngines().then(() => {
       if (initKbId) {
-        getKbConfig(initKbId).then((val) => {
-          form.setValue('name', val.name);
-          form.setValue('description', val.description);
-          form.setValue('emoji', val.emoji);
-          form.setValue('embeddingModelUUID', val.embeddingModelUUID);
-          form.setValue('top_k', val.top_k || 5);
-        });
+        loadKbConfig(initKbId);
       }
     });
   }, []);
 
-  const getKbConfig = async (
-    kbId: string,
-  ): Promise<z.infer<typeof formSchema>> => {
-    return new Promise((resolve) => {
-      httpClient.getKnowledgeBase(kbId).then((res) => {
-        resolve({
-          name: res.base.name,
-          description: res.base.description,
-          emoji: res.base.emoji || '📚',
-          embeddingModelUUID: res.base.embedding_model_uuid,
-          top_k: res.base.top_k || 5,
-        });
-      });
-    });
+  // Auto-select first engine when engines are loaded and no selection
+  useEffect(() => {
+    if (ragEngines.length > 0 && !selectedEngineId && !isEditing) {
+      const firstEngine = ragEngines[0];
+      setSelectedEngineId(firstEngine.plugin_id);
+      form.setValue('ragEngineId', firstEngine.plugin_id);
+      // Initialize config settings with defaults
+      const formItems = parseCreationSchema(firstEngine.creation_schema);
+      if (formItems.length > 0) {
+        setConfigSettings(getDefaultValues(formItems));
+      }
+      const retrievalItems = parseCreationSchema(firstEngine.retrieval_schema);
+      if (retrievalItems.length > 0) {
+        setRetrievalSettings(getDefaultValues(retrievalItems));
+      }
+    }
+  }, [ragEngines, selectedEngineId, isEditing]);
+
+  const loadRagEngines = async () => {
+    setLoading(true);
+    try {
+      const resp = await httpClient.getKnowledgeEngines();
+      setRagEngines(resp.engines);
+    } catch (err) {
+      console.error('Failed to load Knowledge Engines:', err);
+    } finally {
+      setLoading(false);
+    }
   };
 
-  const getEmbeddingModelNameList = async () => {
-    const resp = await httpClient.getProviderEmbeddingModels();
-    let models = resp.models;
-    // Filter out space-chat-completions models when not logged in with space account or when models service is disabled
-    if (
-      systemInfo.disable_models_service ||
-      userInfo?.account_type !== 'space'
-    ) {
-      models = models.filter(
-        (m) => m.provider?.requester !== 'space-chat-completions',
-      );
+  const loadKbConfig = async (kbId: string) => {
+    try {
+      setIsEditing(true);
+
+      const res = await httpClient.getKnowledgeBase(kbId);
+      const kb = res.base;
+
+      const engineId = kb.knowledge_engine_plugin_id || '';
+      setSelectedEngineId(engineId);
+
+      form.setValue('name', kb.name);
+      form.setValue('description', kb.description);
+      form.setValue('emoji', kb.emoji || '📚');
+      form.setValue('ragEngineId', engineId);
+
+      setConfigSettings(kb.creation_settings || {});
+      setRetrievalSettings(kb.retrieval_settings || {});
+    } catch (err) {
+      console.error('Failed to load KB config:', err);
+    }
+  };
+
+  const handleEngineChange = (engineId: string) => {
+    setSelectedEngineId(engineId);
+    form.setValue('ragEngineId', engineId);
+
+    // Find engine and initialize config settings with defaults from schema
+    const engine = ragEngines.find((e) => e.plugin_id === engineId);
+    if (engine) {
+      const formItems = parseCreationSchema(engine.creation_schema);
+      if (formItems.length > 0) {
+        setConfigSettings(getDefaultValues(formItems));
+      } else {
+        setConfigSettings({});
+      }
+      const retrievalItems = parseCreationSchema(engine.retrieval_schema);
+      if (retrievalItems.length > 0) {
+        setRetrievalSettings(getDefaultValues(retrievalItems));
+      } else {
+        setRetrievalSettings({});
+      }
     }
-    setEmbeddingModels(models);
   };
 
   const onSubmit = (data: z.infer<typeof formSchema>) => {
+    const kbData: KnowledgeBase = {
+      name: data.name,
+      description: data.description,
+      emoji: data.emoji,
+      knowledge_engine_plugin_id: selectedEngineId,
+      creation_settings: configSettings,
+      retrieval_settings: retrievalSettings,
+    };
+
     if (initKbId) {
-      // update knowledge base
-      const updateKb: KnowledgeBase = {
-        name: data.name,
-        description: data.description,
-        emoji: data.emoji,
-        embedding_model_uuid: data.embeddingModelUUID,
-        top_k: data.top_k,
-      };
+      // Update knowledge base
       httpClient
-        .updateKnowledgeBase(initKbId, updateKb)
+        .updateKnowledgeBase(initKbId, kbData)
         .then((res) => {
           onKbUpdated(res.uuid);
           toast.success(t('knowledge.updateKnowledgeBaseSuccess'));
         })
         .catch((err) => {
           console.error('update knowledge base failed', err);
-          toast.error(t('knowledge.updateKnowledgeBaseFailed'));
+          toast.error(
+            t('knowledge.updateKnowledgeBaseFailed') +
+              (err as CustomApiError).msg,
+          );
         });
     } else {
-      // create knowledge base
-      const newKb: KnowledgeBase = {
-        name: data.name,
-        description: data.description,
-        emoji: data.emoji,
-        embedding_model_uuid: data.embeddingModelUUID,
-        top_k: data.top_k,
-      };
+      // Create knowledge base
       httpClient
-        .createKnowledgeBase(newKb)
+        .createKnowledgeBase(kbData)
         .then((res) => {
           onNewKbCreated(res.uuid);
         })
         .catch((err) => {
           console.error('create knowledge base failed', err);
+          toast.error(
+            t('knowledge.createKnowledgeBaseFailed') +
+              (err as CustomApiError).msg,
+          );
         });
     }
   };
 
+  // Convert creation schema to dynamic form items (same as ExternalKBForm)
+  const configFormItems = parseCreationSchema(selectedEngine?.creation_schema);
+
+  // Convert retrieval schema to dynamic form items
+  const retrievalFormItems = parseCreationSchema(
+    selectedEngine?.retrieval_schema,
+  );
+
+  // Show loading state
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center py-8">
+        <p className="text-muted-foreground">{t('common.loading')}</p>
+      </div>
+    );
+  }
+
+  // Show message if no engines available
+  if (ragEngines.length === 0) {
+    return (
+      <div className="flex flex-col items-center justify-center py-8 space-y-4">
+        <p className="text-muted-foreground">
+          {t('knowledge.noEnginesAvailable')}
+        </p>
+        <Link
+          href="/home/plugins"
+          className="text-sm text-primary hover:underline"
+        >
+          {t('knowledge.installEngineHint')}
+        </Link>
+      </div>
+    );
+  }
+
   return (
     <>
       <Form {...form}>
@@ -162,6 +284,57 @@ export default function KBForm({
           className="space-y-8"
         >
           <div className="space-y-4">
+            {/* Knowledge Engine Selector */}
+            <FormField
+              control={form.control}
+              name="ragEngineId"
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel>
+                    {t('knowledge.knowledgeEngine')}
+                    <span className="text-red-500">*</span>
+                  </FormLabel>
+                  <FormControl>
+                    <Select
+                      disabled={isEditing}
+                      onValueChange={(value) => {
+                        field.onChange(value);
+                        handleEngineChange(value);
+                      }}
+                      value={field.value}
+                    >
+                      <SelectTrigger className="w-full bg-[#ffffff] dark:bg-[#2a2a2e]">
+                        <SelectValue
+                          placeholder={t('knowledge.selectKnowledgeEngine')}
+                        />
+                      </SelectTrigger>
+                      <SelectContent className="fixed z-[1000]">
+                        {ragEngines.map((engine) => (
+                          <SelectItem
+                            key={engine.plugin_id}
+                            value={engine.plugin_id}
+                          >
+                            {extractI18nObject(engine.name)}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                  </FormControl>
+                  {selectedEngine?.description && (
+                    <FormDescription>
+                      {extractI18nObject(selectedEngine.description)}
+                    </FormDescription>
+                  )}
+                  {isEditing && (
+                    <FormDescription>
+                      {t('knowledge.cannotChangeKnowledgeEngine')}
+                    </FormDescription>
+                  )}
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+
             {/* Name and Emoji in same row */}
             <div className="flex gap-4 items-start">
               <FormField
@@ -197,6 +370,8 @@ export default function KBForm({
                 )}
               />
             </div>
+
+            {/* Description */}
             <FormField
               control={form.control}
               name="description"
@@ -213,96 +388,45 @@ export default function KBForm({
                 </FormItem>
               )}
             />
-            <FormField
-              control={form.control}
-              name="embeddingModelUUID"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>
-                    {t('knowledge.embeddingModelUUID')}
-                    <span className="text-red-500">*</span>
-                  </FormLabel>
-                  <FormControl>
-                    <div className="relative">
-                      <Select
-                        disabled={!!initKbId}
-                        onValueChange={(value) => {
-                          field.onChange(value);
-                        }}
-                        value={field.value}
-                      >
-                        <SelectTrigger className="w-[180px] bg-[#ffffff] dark:bg-[#2a2a2e]">
-                          <SelectValue
-                            placeholder={t('knowledge.selectEmbeddingModel')}
-                          />
-                        </SelectTrigger>
-                        <SelectContent className="fixed z-[1000]">
-                          {(() => {
-                            const grouped = embeddingModels.reduce(
-                              (acc, model) => {
-                                const providerName =
-                                  model.provider?.name ||
-                                  model.provider?.requester ||
-                                  'Unknown';
-                                if (!acc[providerName]) acc[providerName] = [];
-                                acc[providerName].push(model);
-                                return acc;
-                              },
-                              {} as Record<string, EmbeddingModel[]>,
-                            );
-                            return Object.entries(grouped).map(
-                              ([providerName, models]) => (
-                                <SelectGroup key={providerName}>
-                                  <SelectLabel>{providerName}</SelectLabel>
-                                  {models.map((model) => (
-                                    <SelectItem
-                                      key={model.uuid}
-                                      value={model.uuid}
-                                    >
-                                      {model.name}
-                                    </SelectItem>
-                                  ))}
-                                </SelectGroup>
-                              ),
-                            );
-                          })()}
-                        </SelectContent>
-                      </Select>
-                    </div>
-                  </FormControl>
-                  <FormDescription>
-                    {initKbId
-                      ? t('knowledge.cannotChangeEmbeddingModel')
-                      : t('knowledge.embeddingModelDescription')}
-                  </FormDescription>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-            <FormField
-              control={form.control}
-              name="top_k"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>
-                    {t('knowledge.topK')}
-                    <span className="text-red-500">*</span>
-                  </FormLabel>
-                  <FormControl>
-                    <Input
-                      type="number"
-                      {...field}
-                      onChange={(e) => field.onChange(Number(e.target.value))}
-                      className="w-[180px] h-10 text-base appearance-none"
-                    />
-                  </FormControl>
-                  <FormDescription>
-                    {t('knowledge.topKdescription')}
-                  </FormDescription>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
+
+            {/* Engine specific fields (dynamic form from creation_schema) */}
+            {configFormItems.length > 0 && (
+              <div className="space-y-4 pt-2 border-t">
+                <div className="text-sm font-medium text-muted-foreground">
+                  {t('knowledge.engineSettings')}
+                </div>
+                <div>
+                  <DynamicFormComponent
+                    itemConfigList={configFormItems}
+                    initialValues={configSettings as Record<string, object>}
+                    onSubmit={(val) =>
+                      setConfigSettings(val as Record<string, unknown>)
+                    }
+                    isEditing={isEditing}
+                    externalDependentValues={retrievalSettings}
+                  />
+                </div>
+              </div>
+            )}
+
+            {/* Retrieval settings (dynamic form from retrieval_schema) */}
+            {retrievalFormItems.length > 0 && (
+              <div className="space-y-4 pt-2 border-t">
+                <div className="text-sm font-medium text-muted-foreground">
+                  {t('knowledge.retrievalSettings')}
+                </div>
+                <div>
+                  <DynamicFormComponent
+                    itemConfigList={retrievalFormItems}
+                    initialValues={retrievalSettings as Record<string, object>}
+                    onSubmit={(val) =>
+                      setRetrievalSettings(val as Record<string, unknown>)
+                    }
+                    externalDependentValues={configSettings}
+                  />
+                </div>
+              </div>
+            )}
           </div>
         </form>
       </Form>

web/src/app/home/knowledge/components/kb-migration-dialog/KBMigrationDialog.tsx

@@ -0,0 +1,157 @@
+'use client';
+
+import { useState } from 'react';
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogFooter,
+} from '@/components/ui/dialog';
+import { Button } from '@/components/ui/button';
+import { useTranslation } from 'react-i18next';
+import { httpClient } from '@/app/infra/http/HttpClient';
+import { useAsyncTask, AsyncTaskStatus } from '@/hooks/useAsyncTask';
+import { toast } from 'sonner';
+import { Loader2 } from 'lucide-react';
+
+interface KBMigrationDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  internalKbCount: number;
+  externalKbCount: number;
+  onMigrationComplete: () => void;
+}
+
+export default function KBMigrationDialog({
+  open,
+  onOpenChange,
+  internalKbCount,
+  externalKbCount,
+  onMigrationComplete,
+}: KBMigrationDialogProps) {
+  const { t } = useTranslation();
+  const [dismissing, setDismissing] = useState(false);
+
+  const asyncTask = useAsyncTask({
+    onSuccess: () => {
+      toast.success(t('knowledge.migration.success'));
+      onOpenChange(false);
+      onMigrationComplete();
+    },
+    onError: (error) => {
+      toast.error(`${t('knowledge.migration.error')}${error}`);
+    },
+  });
+
+  const handleMigration = async (installPlugin: boolean) => {
+    try {
+      const resp = await httpClient.executeRagMigration(installPlugin);
+      asyncTask.startTask(resp.task_id);
+    } catch {
+      toast.error(t('knowledge.migration.error'));
+    }
+  };
+
+  const handleDismiss = async () => {
+    setDismissing(true);
+    try {
+      await httpClient.dismissRagMigration();
+      onOpenChange(false);
+    } catch {
+      toast.error(t('knowledge.migration.dismissError'));
+    } finally {
+      setDismissing(false);
+    }
+  };
+
+  const isRunning = asyncTask.status === AsyncTaskStatus.RUNNING;
+  const isError = asyncTask.status === AsyncTaskStatus.ERROR;
+  const totalCount = internalKbCount + externalKbCount;
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(v) => {
+        if (!isRunning) onOpenChange(v);
+      }}
+    >
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>{t('knowledge.migration.title')}</DialogTitle>
+          <DialogDescription>
+            {t('knowledge.migration.description')}
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="py-4 space-y-3">
+          {!isRunning && !isError && (
+            <p className="text-sm text-muted-foreground">
+              {t('knowledge.migration.detected', {
+                total: totalCount,
+                internal: internalKbCount,
+                external: externalKbCount,
+              })}
+            </p>
+          )}
+
+          {isRunning && (
+            <div className="flex items-center gap-3">
+              <Loader2 className="h-5 w-5 animate-spin text-primary" />
+              <p className="text-sm">{t('knowledge.migration.running')}</p>
+            </div>
+          )}
+
+          {isError && (
+            <div className="space-y-2">
+              <p className="text-sm text-destructive">
+                {t('knowledge.migration.error')}
+              </p>
+              {asyncTask.error && (
+                <p className="text-xs text-muted-foreground bg-muted p-2 rounded">
+                  {asyncTask.error}
+                </p>
+              )}
+            </div>
+          )}
+        </div>
+
+        <DialogFooter className="flex flex-col gap-2 sm:flex-col">
+          {!isRunning && !isError && (
+            <>
+              <Button onClick={() => handleMigration(true)} className="w-full">
+                {t('knowledge.migration.startWithInstall')}
+              </Button>
+              <Button
+                variant="outline"
+                onClick={() => handleMigration(false)}
+                className="w-full"
+              >
+                {t('knowledge.migration.startDataOnly')}
+              </Button>
+              <p className="text-xs text-muted-foreground text-center">
+                {t('knowledge.migration.dataOnlyHint')}
+              </p>
+            </>
+          )}
+          {isError && (
+            <Button onClick={() => handleMigration(true)} className="w-full">
+              {t('knowledge.migration.retry')}
+            </Button>
+          )}
+          {!isRunning && (
+            <Button
+              variant="ghost"
+              onClick={handleDismiss}
+              disabled={dismissing}
+              className="w-full text-destructive hover:text-destructive"
+            >
+              {t('knowledge.migration.dismiss')}
+            </Button>
+          )}
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

web/src/app/home/knowledge/components/kb-retrieve/ExternalKBRetrieve.tsx

@@ -1,35 +0,0 @@
-'use client';
-
-import React from 'react';
-import { httpClient } from '@/app/infra/http/HttpClient';
-import { RetrieveResult } from '@/app/infra/entities/api';
-import KBRetrieveGeneric from './KBRetrieveGeneric';
-
-interface ExternalKBRetrieveProps {
-  kbId: string;
-}
-
-/**
- * External knowledge base retrieve component
- * Uses the generic retrieve component with external KB API
- */
-export default function ExternalKBRetrieve({ kbId }: ExternalKBRetrieveProps) {
-  const getResultTitle = (result: RetrieveResult): string => {
-    // For external KB, try to get document_name or use a generic title
-    return (
-      (result.metadata.document_name as string) ||
-      (result.metadata.source as string) ||
-      result.id
-    );
-  };
-
-  return (
-    <KBRetrieveGeneric
-      kbId={kbId}
-      retrieveFunction={httpClient.retrieveExternalKnowledgeBase.bind(
-        httpClient,
-      )}
-      getResultTitle={getResultTitle}
-    />
-  );
-}

web/src/app/home/knowledge/components/kb-retrieve/KBRetrieve.tsx

@@ -1,124 +0,0 @@
-'use client';
-
-import React, { useState, useEffect } from 'react';
-import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
-import { Button } from '@/components/ui/button';
-import { Input } from '@/components/ui/input';
-import { useTranslation } from 'react-i18next';
-import { httpClient } from '@/app/infra/http/HttpClient';
-import { RetrieveResult, KnowledgeBaseFile } from '@/app/infra/entities/api';
-import { toast } from 'sonner';
-
-interface KBRetrieveProps {
-  kbId: string;
-}
-
-export default function KBRetrieve({ kbId }: KBRetrieveProps) {
-  const { t } = useTranslation();
-  const [query, setQuery] = useState('');
-  const [results, setResults] = useState<RetrieveResult[]>([]);
-  const [files, setFiles] = useState<KnowledgeBaseFile[]>([]);
-  const [loading, setLoading] = useState(false);
-
-  useEffect(() => {
-    const loadFiles = async () => {
-      try {
-        const response = await httpClient.getKnowledgeBaseFiles(kbId);
-        setFiles(response.files);
-      } catch (error) {
-        console.error('Failed to load files:', error);
-      }
-    };
-    loadFiles();
-  }, [kbId]);
-
-  const handleRetrieve = async () => {
-    if (!query.trim()) return;
-
-    setLoading(true);
-    try {
-      setResults([]);
-      const response = await httpClient.retrieveKnowledgeBase(kbId, query);
-      setResults(response.results);
-    } catch (error) {
-      console.error('Retrieve failed:', error);
-      toast.error(t('knowledge.retrieveError'));
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  const getFileName = (fileId?: string) => {
-    if (!fileId) return '';
-    const file = files.find((f) => f.uuid === fileId);
-    return file?.file_name || fileId;
-  };
-
-  /**
-   * Extract text content from the content array
-   * The content array may contain multiple items with type 'text'
-   */
-  const extractTextFromContent = (result: RetrieveResult): string => {
-    // First try to get content from the new format
-    if (result.content && Array.isArray(result.content)) {
-      const textParts = result.content
-        .filter((item) => item.type === 'text' && item.text)
-        .map((item) => item.text);
-
-      if (textParts.length > 0) {
-        return textParts.join('\n\n');
-      }
-    }
-
-    // Fallback to metadata.text for backward compatibility
-    if (result.metadata?.text) {
-      return result.metadata.text as string;
-    }
-
-    return '';
-  };
-
-  return (
-    <div className="space-y-4">
-      <div className="flex gap-2">
-        <Input
-          value={query}
-          onChange={(e) => setQuery(e.target.value)}
-          placeholder={t('knowledge.queryPlaceholder')}
-          onKeyPress={(e) => e.key === 'Enter' && handleRetrieve()}
-        />
-        <Button onClick={handleRetrieve} disabled={loading || !query.trim()}>
-          {t('knowledge.query')}
-        </Button>
-      </div>
-
-      <div className="space-y-3">
-        {results.length === 0 && !loading && (
-          <p className="text-muted-foreground">{t('knowledge.noResults')}</p>
-        )}
-
-        {loading ? (
-          <p className="text-muted-foreground">{t('common.loading')}</p>
-        ) : (
-          results.map((result) => (
-            <Card key={result.id} className="w-full">
-              <CardHeader className="pb-3">
-                <CardTitle className="text-sm font-medium flex justify-between items-center">
-                  <span>{getFileName(result.metadata.file_id)}</span>
-                  <span className="text-xs text-muted-foreground">
-                    {t('knowledge.distance')}: {result.distance.toFixed(4)}
-                  </span>
-                </CardTitle>
-              </CardHeader>
-              <CardContent>
-                <p className="text-sm whitespace-pre-wrap">
-                  {extractTextFromContent(result)}
-                </p>
-              </CardContent>
-            </Card>
-          ))
-        )}
-      </div>
-    </div>
-  );
-}

web/src/app/home/knowledge/components/kb-retrieve/KBRetrieveGeneric.tsx

@@ -6,6 +6,7 @@ import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { useTranslation } from 'react-i18next';
 import { RetrieveResult } from '@/app/infra/entities/api';
+import { CustomApiError } from '@/app/infra/entities/common';
 import { toast } from 'sonner';
 
 interface KBRetrieveGenericProps {
@@ -41,7 +42,7 @@ export default function KBRetrieveGeneric({
       setResults(response.results);
     } catch (error) {
       console.error('Retrieve failed:', error);
-      toast.error(t('knowledge.retrieveError'));
+      toast.error(t('knowledge.retrieveError') + (error as CustomApiError).msg);
     } finally {
       setLoading(false);
     }
@@ -51,10 +52,10 @@ export default function KBRetrieveGeneric({
     if (getResultTitle) {
       return getResultTitle(result);
     }
-    // Default: use file_id or document_name from metadata
+    // Default: use document_name from metadata, fallback to file_id or id
     return (
-      (result.metadata.file_id as string) ||
       (result.metadata.document_name as string) ||
+      (result.metadata.file_id as string) ||
       result.id
     );
   };
@@ -106,7 +107,8 @@ export default function KBRetrieveGeneric({
                 <CardTitle className="text-sm font-medium flex justify-between items-center">
                   <span>{getTitle(result)}</span>
                   <span className="text-xs text-muted-foreground">
-                    {t('knowledge.distance')}: {result.distance.toFixed(4)}
+                    {t('knowledge.distance')}:{' '}
+                    {(result.distance ?? 0).toFixed(4)}
                   </span>
                 </CardTitle>
               </CardHeader>

web/src/app/home/knowledge/knowledgeBase.module.css

@@ -5,7 +5,6 @@
 
 .knowledgeListContainer {
   width: 100%;
-  margin-top: 2rem;
   padding-left: 0.8rem;
   padding-right: 0.8rem;
   display: grid;

web/src/app/home/knowledge/page.tsx

@@ -5,139 +5,84 @@ import styles from './knowledgeBase.module.css';
 import { useTranslation } from 'react-i18next';
 import { useEffect, useState } from 'react';
 import { KnowledgeBaseVO } from '@/app/home/knowledge/components/kb-card/KBCardVO';
-import { ExternalKBCardVO } from '@/app/home/knowledge/components/external-kb-card/ExternalKBCardVO';
 import KBCard from '@/app/home/knowledge/components/kb-card/KBCard';
-import ExternalKBCard from '@/app/home/knowledge/components/external-kb-card/ExternalKBCard';
 import KBDetailDialog from '@/app/home/knowledge/KBDetailDialog';
+import KBMigrationDialog from '@/app/home/knowledge/components/kb-migration-dialog/KBMigrationDialog';
 import { httpClient } from '@/app/infra/http/HttpClient';
-import {
-  KnowledgeBase,
-  ExternalKnowledgeBase,
-  ApiRespPluginSystemStatus,
-} from '@/app/infra/entities/api';
-import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { KnowledgeBase } from '@/app/infra/entities/api';
 
 export default function KnowledgePage() {
   const { t } = useTranslation();
-  const [activeTab, setActiveTab] = useState('builtin');
   const [knowledgeBaseList, setKnowledgeBaseList] = useState<KnowledgeBaseVO[]>(
     [],
   );
-  const [externalKBList, setExternalKBList] = useState<ExternalKBCardVO[]>([]);
   const [selectedKbId, setSelectedKbId] = useState<string>('');
-  const [selectedKbType, setSelectedKbType] = useState<'builtin' | 'external'>(
-    'builtin',
-  );
   const [detailDialogOpen, setDetailDialogOpen] = useState(false);
-  const [pluginSystemStatus, setPluginSystemStatus] =
-    useState<ApiRespPluginSystemStatus | null>(null);
+
+  // Migration dialog state
+  const [migrationDialogOpen, setMigrationDialogOpen] = useState(false);
+  const [migrationInternalCount, setMigrationInternalCount] = useState(0);
+  const [migrationExternalCount, setMigrationExternalCount] = useState(0);
 
   useEffect(() => {
     getKnowledgeBaseList();
-    getExternalKBList();
-    fetchPluginSystemStatus();
+    checkMigrationStatus();
   }, []);
 
-  async function fetchPluginSystemStatus() {
+  async function checkMigrationStatus() {
     try {
-      const status = await httpClient.getPluginSystemStatus();
-      setPluginSystemStatus(status);
-    } catch (error) {
-      console.error('Failed to fetch plugin system status:', error);
+      const resp = await httpClient.getRagMigrationStatus();
+      if (resp.needed) {
+        setMigrationInternalCount(resp.internal_kb_count);
+        setMigrationExternalCount(resp.external_kb_count);
+        setMigrationDialogOpen(true);
+      }
+    } catch {
+      // Silently ignore - migration check is non-critical
     }
   }
 
   async function getKnowledgeBaseList() {
     const resp = await httpClient.getKnowledgeBases();
-    setKnowledgeBaseList(
-      resp.bases.map((kb: KnowledgeBase) => {
-        const currentTime = new Date();
-        const lastUpdatedTimeAgo = Math.floor(
-          (currentTime.getTime() -
-            new Date(kb.updated_at ?? currentTime.getTime()).getTime()) /
-            1000 /
-            60 /
-            60 /
-            24,
-        );
 
-        const lastUpdatedTimeAgoText =
-          lastUpdatedTimeAgo > 0
-            ? ` ${lastUpdatedTimeAgo} ${t('knowledge.daysAgo')}`
-            : t('knowledge.today');
+    const currentTime = new Date();
 
-        return new KnowledgeBaseVO({
-          id: kb.uuid || '',
-          name: kb.name,
-          description: kb.description,
-          emoji: kb.emoji,
-          embeddingModelUUID: kb.embedding_model_uuid,
-          top_k: kb.top_k ?? 5,
-          lastUpdatedTimeAgo: lastUpdatedTimeAgoText,
-        });
-      }),
-    );
-  }
-
-  async function getExternalKBList() {
-    try {
-      const resp = await httpClient.getExternalKnowledgeBases();
-      setExternalKBList(
-        resp.bases.map((kb: ExternalKnowledgeBase) => {
-          const currentTime = new Date();
-          const lastUpdatedTimeAgo = Math.floor(
-            (currentTime.getTime() -
-              new Date(kb.created_at ?? currentTime.getTime()).getTime()) /
-              1000 /
-              60 /
-              60 /
-              24,
-          );
-
-          const lastUpdatedTimeAgoText =
-            lastUpdatedTimeAgo > 0
-              ? ` ${lastUpdatedTimeAgo} ${t('knowledge.daysAgo')}`
-              : t('knowledge.today');
-
-          return new ExternalKBCardVO({
-            id: kb.uuid || '',
-            name: kb.name,
-            description: kb.description,
-            emoji: kb.emoji,
-            retrieverName: `${kb.plugin_author}/${kb.plugin_name}/${kb.retriever_name}`,
-            retrieverConfig: kb.retriever_config || {},
-            lastUpdatedTimeAgo: lastUpdatedTimeAgoText,
-            pluginAuthor: kb.plugin_author,
-            pluginName: kb.plugin_name,
-          });
-        }),
+    const kbs = resp.bases.map((kb: KnowledgeBase) => {
+      const lastUpdatedTimeAgo = Math.floor(
+        (currentTime.getTime() -
+          new Date(kb.updated_at ?? currentTime.getTime()).getTime()) /
+          1000 /
+          60 /
+          60 /
+          24,
       );
-    } catch (error) {
-      console.error('Failed to load external knowledge bases:', error);
-    }
+
+      const lastUpdatedTimeAgoText =
+        lastUpdatedTimeAgo > 0
+          ? ` ${lastUpdatedTimeAgo} ${t('knowledge.daysAgo')}`
+          : t('knowledge.today');
+
+      return new KnowledgeBaseVO({
+        id: kb.uuid || '',
+        name: kb.name,
+        description: kb.description,
+        emoji: kb.emoji,
+        lastUpdatedTimeAgo: lastUpdatedTimeAgoText,
+        ragEngine: kb.knowledge_engine,
+        ragEnginePluginId: kb.knowledge_engine_plugin_id,
+      });
+    });
+
+    setKnowledgeBaseList(kbs);
   }
 
   const handleKBCardClick = (kbId: string) => {
     setSelectedKbId(kbId);
-    setSelectedKbType('builtin');
     setDetailDialogOpen(true);
   };
 
   const handleCreateKBClick = () => {
     setSelectedKbId('');
-    setSelectedKbType('builtin');
-    setDetailDialogOpen(true);
-  };
-
-  const handleExternalKBCardClick = (kbId: string) => {
-    setSelectedKbId(kbId);
-    setSelectedKbType('external');
-    setDetailDialogOpen(true);
-  };
-
-  const handleCreateExternalKB = () => {
-    setSelectedKbId('');
-    setSelectedKbType('external');
     setDetailDialogOpen(true);
   };
 
@@ -146,105 +91,60 @@ export default function KnowledgePage() {
   };
 
   const handleKbDeleted = () => {
-    if (selectedKbType === 'builtin') {
-      getKnowledgeBaseList();
-    } else {
-      getExternalKBList();
-    }
+    getKnowledgeBaseList();
     setDetailDialogOpen(false);
   };
 
   const handleNewKbCreated = (newKbId: string) => {
-    if (selectedKbType === 'builtin') {
-      getKnowledgeBaseList();
-    } else {
-      getExternalKBList();
-    }
+    getKnowledgeBaseList();
     setSelectedKbId(newKbId);
     setDetailDialogOpen(true);
   };
 
   const handleKbUpdated = () => {
-    if (selectedKbType === 'builtin') {
-      getKnowledgeBaseList();
-    } else {
-      getExternalKBList();
-    }
+    getKnowledgeBaseList();
+  };
+
+  const handleMigrationComplete = () => {
+    getKnowledgeBaseList();
   };
 
   return (
     <div>
+      <KBMigrationDialog
+        open={migrationDialogOpen}
+        onOpenChange={setMigrationDialogOpen}
+        internalKbCount={migrationInternalCount}
+        externalKbCount={migrationExternalCount}
+        onMigrationComplete={handleMigrationComplete}
+      />
+
       <KBDetailDialog
         open={detailDialogOpen}
         onOpenChange={setDetailDialogOpen}
         kbId={selectedKbId || undefined}
-        kbType={selectedKbType}
         onFormCancel={handleFormCancel}
         onKbDeleted={handleKbDeleted}
         onNewKbCreated={handleNewKbCreated}
         onKbUpdated={handleKbUpdated}
       />
 
-      <Tabs value={activeTab} onValueChange={setActiveTab} className="w-full">
-        <div className="flex flex-row justify-between items-center px-[0.8rem]">
-          <TabsList className="shadow-md py-5 bg-[#f0f0f0] dark:bg-[#2a2a2e]">
-            <TabsTrigger value="builtin" className="px-6 py-4 cursor-pointer">
-              {t('knowledge.builtIn')}
-            </TabsTrigger>
-            {/* Only show external tab if plugin system is enabled and connected */}
-            {pluginSystemStatus?.is_enable &&
-              pluginSystemStatus?.is_connected && (
-                <TabsTrigger
-                  value="external"
-                  className="px-6 py-4 cursor-pointer"
-                >
-                  {t('knowledge.external')}
-                </TabsTrigger>
-              )}
-          </TabsList>
-        </div>
+      <div className={styles.knowledgeListContainer}>
+        <CreateCardComponent
+          width={'100%'}
+          height={'10rem'}
+          plusSize={'90px'}
+          onClick={handleCreateKBClick}
+        />
 
-        <TabsContent value="builtin">
-          <div className={styles.knowledgeListContainer}>
-            <CreateCardComponent
-              width={'100%'}
-              height={'10rem'}
-              plusSize={'90px'}
-              onClick={handleCreateKBClick}
-            />
-
-            {knowledgeBaseList.map((kb) => {
-              return (
-                <div key={kb.id} onClick={() => handleKBCardClick(kb.id)}>
-                  <KBCard kbCardVO={kb} />
-                </div>
-              );
-            })}
-          </div>
-        </TabsContent>
-
-        <TabsContent value="external">
-          <div className={styles.knowledgeListContainer}>
-            <CreateCardComponent
-              width={'100%'}
-              height={'10rem'}
-              plusSize={'90px'}
-              onClick={handleCreateExternalKB}
-            />
-
-            {externalKBList.map((kb) => {
-              return (
-                <div
-                  key={kb.id}
-                  onClick={() => handleExternalKBCardClick(kb.id)}
-                >
-                  <ExternalKBCard kbCardVO={kb} />
-                </div>
-              );
-            })}
-          </div>
-        </TabsContent>
-      </Tabs>
+        {knowledgeBaseList.map((kb) => {
+          return (
+            <div key={kb.id} onClick={() => handleKBCardClick(kb.id)}>
+              <KBCard kbCardVO={kb} />
+            </div>
+          );
+        })}
+      </div>
     </div>
   );
 }

web/src/app/home/pipelines/components/pipeline-form/PipelineFormComponent.tsx

@@ -120,6 +120,8 @@ export default function PipelineFormComponent({
 
   // Track unsaved changes by comparing current form values against a saved snapshot
   const savedSnapshotRef = useRef<string>('');
+  // Track which dynamic form stages have completed their initial mount emission.
+  const initializedStagesRef = useRef<Set<string>>(new Set());
   const watchedValues = form.watch();
   const hasUnsavedChanges = useMemo(() => {
     if (!isEditMode || !savedSnapshotRef.current) return false;
@@ -160,6 +162,7 @@ export default function PipelineFormComponent({
           };
           form.reset(loadedValues);
           savedSnapshotRef.current = JSON.stringify(loadedValues);
+          initializedStagesRef.current.clear();
         });
     }
   }, []);
@@ -235,6 +238,33 @@ export default function PipelineFormComponent({
       });
   }
 
+  // Called from DynamicFormComponent/N8nAuthFormComponent onSubmit callbacks.
+  // On the first emission for a stage (mount-time default filling), the
+  // snapshot is synchronously re-captured so that hasUnsavedChanges stays false.
+  function handleDynamicFormEmit(
+    formName: keyof FormValues,
+    stageName: string,
+    values: object,
+  ) {
+    const stageKey = `${String(formName)}.${stageName}`;
+    const isFirstEmission = !initializedStagesRef.current.has(stageKey);
+
+    const currentValues =
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (form.getValues(formName) as Record<string, any>) || {};
+    form.setValue(formName, {
+      ...currentValues,
+      [stageName]: values,
+    });
+
+    if (isFirstEmission) {
+      initializedStagesRef.current.add(stageKey);
+      // Synchronously re-capture snapshot so that the useMemo comparison
+      // in the same render cycle still returns false.
+      savedSnapshotRef.current = JSON.stringify(form.getValues());
+    }
+  }
+
   function renderDynamicForms(
     stage: PipelineConfigStage,
     formName: keyof FormValues,
@@ -264,13 +294,7 @@ export default function PipelineFormComponent({
                 {}
               }
               onSubmit={(values) => {
-                const currentValues =
-                  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                  (form.getValues(formName) as Record<string, any>) || {};
-                form.setValue(formName, {
-                  ...currentValues,
-                  [stage.name]: values,
-                });
+                handleDynamicFormEmit(formName, stage.name, values);
               }}
             />
           </div>
@@ -302,13 +326,7 @@ export default function PipelineFormComponent({
                 {}
               }
               onSubmit={(values) => {
-                const currentValues =
-                  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                  (form.getValues(formName) as Record<string, any>) || {};
-                form.setValue(formName, {
-                  ...currentValues,
-                  [stage.name]: values,
-                });
+                handleDynamicFormEmit(formName, stage.name, values);
               }}
             />
           </div>
@@ -333,13 +351,7 @@ export default function PipelineFormComponent({
             (form.watch(formName) as Record<string, any>)?.[stage.name] || {}
           }
           onSubmit={(values) => {
-            const currentValues =
-              // eslint-disable-next-line @typescript-eslint/no-explicit-any
-              (form.getValues(formName) as Record<string, any>) || {};
-            form.setValue(formName, {
-              ...currentValues,
-              [stage.name]: values,
-            });
+            handleDynamicFormEmit(formName, stage.name, values);
           }}
         />
       </div>

web/src/app/home/plugins/components/plugin-installed/PluginComponentList.tsx

@@ -1,5 +1,5 @@
 import { TFunction } from 'i18next';
-import { Wrench, AudioWaveform, Hash, Book } from 'lucide-react';
+import { Wrench, AudioWaveform, Hash, Book, FileText } from 'lucide-react';
 import { Badge } from '@/components/ui/badge';
 
 export default function PluginComponentList({
@@ -21,7 +21,8 @@ export default function PluginComponentList({
     Tool: <Wrench className="w-5 h-5" />,
     EventListener: <AudioWaveform className="w-5 h-5" />,
     Command: <Hash className="w-5 h-5" />,
-    KnowledgeRetriever: <Book className="w-5 h-5" />,
+    KnowledgeEngine: <Book className="w-5 h-5" />,
+    Parser: <FileText className="w-5 h-5" />,
   };
 
   const componentKindList = Object.keys(components || {});
@@ -32,45 +33,39 @@ export default function PluginComponentList({
       {componentKindList.length > 0 && (
         <>
           {componentKindList.map((kind) => {
-            return (
-              <>
-                {useBadge && (
-                  <Badge
-                    key={kind}
-                    variant="outline"
-                    className="flex items-center gap-1"
-                  >
-                    {kindIconMap[kind]}
-                    {/* 响应式显示组件名称：在中等屏幕以上显示 */}
-                    {responsive ? (
-                      <span className="hidden md:inline">
-                        {t('plugins.componentName.' + kind)}
-                      </span>
-                    ) : (
-                      showComponentName && t('plugins.componentName.' + kind)
-                    )}
-                    <span className="ml-1">{components[kind]}</span>
-                  </Badge>
+            return useBadge ? (
+              <Badge
+                key={kind}
+                variant="outline"
+                className="flex items-center gap-1"
+              >
+                {kindIconMap[kind]}
+                {/* 响应式显示组件名称：在中等屏幕以上显示 */}
+                {responsive ? (
+                  <span className="hidden md:inline">
+                    {t('plugins.componentName.' + kind)}
+                  </span>
+                ) : (
+                  showComponentName && t('plugins.componentName.' + kind)
                 )}
-
-                {!useBadge && (
-                  <div
-                    key={kind}
-                    className="flex flex-row items-center justify-start gap-[0.2rem]"
-                  >
-                    {kindIconMap[kind]}
-                    {/* 响应式显示组件名称：在中等屏幕以上显示 */}
-                    {responsive ? (
-                      <span className="hidden md:inline">
-                        {t('plugins.componentName.' + kind)}
-                      </span>
-                    ) : (
-                      showComponentName && t('plugins.componentName.' + kind)
-                    )}
-                    <span className="ml-1">{components[kind]}</span>
-                  </div>
+                <span className="ml-1">{components[kind]}</span>
+              </Badge>
+            ) : (
+              <div
+                key={kind}
+                className="flex flex-row items-center justify-start gap-[0.2rem]"
+              >
+                {kindIconMap[kind]}
+                {/* 响应式显示组件名称：在中等屏幕以上显示 */}
+                {responsive ? (
+                  <span className="hidden md:inline">
+                    {t('plugins.componentName.' + kind)}
+                  </span>
+                ) : (
+                  showComponentName && t('plugins.componentName.' + kind)
                 )}
-              </>
+                <span className="ml-1">{components[kind]}</span>
+              </div>
             );
           })}
         </>

web/src/app/home/plugins/components/plugin-market/PluginMarketComponent.tsx

@@ -17,7 +17,14 @@ import {
   SelectValue,
 } from '@/components/ui/select';
 import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
-import { Search, Wrench, AudioWaveform, Hash, Book } from 'lucide-react';
+import {
+  Search,
+  Wrench,
+  AudioWaveform,
+  Hash,
+  Book,
+  FileText,
+} from 'lucide-react';
 import PluginMarketCardComponent from './plugin-market-card/PluginMarketCardComponent';
 import { PluginMarketCardVO } from './plugin-market-card/PluginMarketCardVO';
 import { getCloudServiceClientSync } from '@/app/infra/http';
@@ -499,12 +506,20 @@ function MarketPageContent({
                 {t('plugins.componentName.EventListener')}
               </ToggleGroupItem>
               <ToggleGroupItem
-                value="KnowledgeRetriever"
-                aria-label="KnowledgeRetriever"
+                value="KnowledgeEngine"
+                aria-label="KnowledgeEngine"
                 className="text-xs sm:text-sm cursor-pointer"
               >
                 <Book className="h-4 w-4 mr-1" />
-                {t('plugins.componentName.KnowledgeRetriever')}
+                {t('plugins.componentName.KnowledgeEngine')}
+              </ToggleGroupItem>
+              <ToggleGroupItem
+                value="Parser"
+                aria-label="Parser"
+                className="text-xs sm:text-sm cursor-pointer"
+              >
+                <FileText className="h-4 w-4 mr-1" />
+                {t('plugins.componentName.Parser')}
               </ToggleGroupItem>
             </ToggleGroup>
           </div>
@@ -547,8 +562,7 @@ function MarketPageContent({
         {/* Recommendation Lists */}
         {!searchQuery &&
           componentFilter === 'all' &&
-          selectedTags.length === 0 &&
-          currentPage === 1 && (
+          selectedTags.length === 0 && (
             <div className="pt-4">
               <RecommendationLists
                 lists={recommendationLists}

web/src/app/home/plugins/components/plugin-market/RecommendationLists.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useState } from 'react';
+import { useState, useRef, useEffect, useCallback } from 'react';
 import { ChevronLeft, ChevronRight, Star } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import PluginMarketCardComponent from './plugin-market-card/PluginMarketCardComponent';
@@ -18,7 +18,7 @@ export interface RecommendationList {
   plugins: PluginV4[];
 }
 
-const PAGE_SIZE = 4; // plugins per page in a recommendation row
+// Match the main plugin grid: grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4
 
 function pluginToVO(
   plugin: PluginV4,
@@ -54,11 +54,44 @@ function RecommendationListRow({
 }) {
   const { t } = useTranslation();
   const [page, setPage] = useState(0);
+  const [perPage, setPerPage] = useState(4);
+  const gridRef = useRef<HTMLDivElement>(null);
 
   const plugins = list.plugins || [];
-  const totalPages = Math.ceil(plugins.length / PAGE_SIZE);
-  const start = page * PAGE_SIZE;
-  const visiblePlugins = plugins.slice(start, start + PAGE_SIZE);
+
+  // Measure how many columns the CSS grid actually renders
+  const measureCols = useCallback(() => {
+    if (!gridRef.current) return;
+    const style = window.getComputedStyle(gridRef.current);
+    const cols = style.gridTemplateColumns.split(' ').length;
+    setPerPage(cols);
+  }, []);
+
+  useEffect(() => {
+    measureCols();
+    const observer = new ResizeObserver(measureCols);
+    if (gridRef.current) observer.observe(gridRef.current);
+    return () => observer.disconnect();
+  }, [measureCols]);
+
+  // Auto-advance every 5 seconds
+  useEffect(() => {
+    if (plugins.length <= perPage) return;
+    const timer = setInterval(() => {
+      setPage((p) => {
+        const tp = Math.max(1, Math.ceil(plugins.length / perPage));
+        return p >= tp - 1 ? 0 : p + 1;
+      });
+    }, 5000);
+    return () => clearInterval(timer);
+  }, [plugins.length, perPage]);
+
+  const totalPages = Math.max(1, Math.ceil(plugins.length / perPage));
+  const safePage = Math.min(page, totalPages - 1);
+  if (safePage !== page) setPage(safePage);
+
+  const start = safePage * perPage;
+  const visiblePlugins = plugins.slice(start, start + perPage);
 
   if (plugins.length === 0) return null;
 
@@ -77,19 +110,19 @@ function RecommendationListRow({
               variant="ghost"
               size="sm"
               onClick={() => setPage((p) => Math.max(0, p - 1))}
-              disabled={page === 0}
+              disabled={safePage === 0}
               className="h-7 w-7 p-0"
             >
               <ChevronLeft className="w-4 h-4" />
             </Button>
             <span className="text-xs text-muted-foreground px-1">
-              {page + 1} / {totalPages}
+              {safePage + 1} / {totalPages}
             </span>
             <Button
               variant="ghost"
               size="sm"
               onClick={() => setPage((p) => Math.min(totalPages - 1, p + 1))}
-              disabled={page >= totalPages - 1}
+              disabled={safePage >= totalPages - 1}
               className="h-7 w-7 p-0"
             >
               <ChevronRight className="w-4 h-4" />
@@ -97,7 +130,10 @@ function RecommendationListRow({
           </div>
         )}
       </div>
-      <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4 gap-6">
+      <div
+        ref={gridRef}
+        className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 2xl:grid-cols-4 gap-6"
+      >
         {visiblePlugins.map((plugin) => (
           <PluginMarketCardComponent
             key={plugin.author + ' / ' + plugin.name}

web/src/app/home/plugins/components/plugin-market/plugin-market-card/PluginMarketCardComponent.tsx

@@ -1,6 +1,12 @@
 import { PluginMarketCardVO } from './PluginMarketCardVO';
 import { useTranslation } from 'react-i18next';
 import { Badge } from '@/components/ui/badge';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@/components/ui/tooltip';
 import {
   Wrench,
   AudioWaveform,
@@ -8,6 +14,8 @@ import {
   Download,
   ExternalLink,
   Book,
+  FileText,
+  Info,
 } from 'lucide-react';
 import { useState } from 'react';
 import { Button } from '@/components/ui/button';
@@ -41,9 +49,17 @@ export default function PluginMarketCardComponent({
     Tool: <Wrench className="w-4 h-4" />,
     EventListener: <AudioWaveform className="w-4 h-4" />,
     Command: <Hash className="w-4 h-4" />,
-    KnowledgeRetriever: <Book className="w-4 h-4" />,
+    KnowledgeEngine: <Book className="w-4 h-4" />,
+    Parser: <FileText className="w-4 h-4" />,
   };
 
+  // Plugins that only contain KnowledgeRetriever components are deprecated
+  const isDeprecated = (() => {
+    if (!cardVO.components) return false;
+    const keys = Object.keys(cardVO.components);
+    return keys.length > 0 && keys.every((k) => k === 'KnowledgeRetriever');
+  })();
+
   return (
     <div
       className="w-[100%] h-auto min-h-[8rem] sm:min-h-[9rem] bg-white rounded-[10px] shadow-[0px_0px_4px_0_rgba(0,0,0,0.2)] p-3 sm:p-[1rem] hover:shadow-[0px_3px_6px_0_rgba(0,0,0,0.12)] transition-all duration-200 hover:scale-[1.005] dark:bg-[#1f1f22] relative"
@@ -64,8 +80,34 @@ export default function PluginMarketCardComponent({
               <div className="text-[0.65rem] sm:text-[0.7rem] text-[#666] dark:text-[#999] truncate w-full">
                 {cardVO.pluginId}
               </div>
-              <div className="text-base sm:text-[1.2rem] text-black dark:text-[#f0f0f0] truncate w-full">
-                {cardVO.label}
+              <div className="flex items-center gap-1.5 w-full min-w-0">
+                <div className="text-base sm:text-[1.2rem] text-black dark:text-[#f0f0f0] truncate">
+                  {cardVO.label}
+                </div>
+                {isDeprecated && (
+                  <TooltipProvider delayDuration={200}>
+                    <Tooltip>
+                      <TooltipTrigger
+                        asChild
+                        onClick={(e) => e.preventDefault()}
+                      >
+                        <Badge
+                          variant="outline"
+                          className="text-[0.6rem] px-1.5 py-0 h-4 flex-shrink-0 border-red-400 text-red-500 dark:border-red-500 dark:text-red-400 gap-0.5 cursor-help"
+                        >
+                          {t('market.deprecated')}
+                          <Info className="w-2.5 h-2.5" />
+                        </Badge>
+                      </TooltipTrigger>
+                      <TooltipContent
+                        side="top"
+                        className="max-w-[240px] text-xs"
+                      >
+                        {t('market.deprecatedTooltip')}
+                      </TooltipContent>
+                    </Tooltip>
+                  </TooltipProvider>
+                )}
               </div>
             </div>
 

web/src/app/infra/entities/api/index.ts

@@ -70,17 +70,6 @@ export interface LLMModel {
   extra_args?: object;
 }
 
-export interface KnowledgeBase {
-  uuid?: string;
-  name: string;
-  description: string;
-  embedding_model_uuid: string;
-  created_at?: string;
-  updated_at?: string;
-  top_k: number;
-  emoji?: string;
-}
-
 export interface ApiRespProviderEmbeddingModels {
   models: EmbeddingModel[];
 }
@@ -166,31 +155,47 @@ export interface KnowledgeBase {
   uuid?: string;
   name: string;
   description: string;
-  embedding_model_uuid: string;
-  top_k: number;
   created_at?: string;
   updated_at?: string;
   emoji?: string;
+  // New unified fields
+  knowledge_engine_plugin_id?: string;
+  creation_settings?: Record<string, unknown>;
+  retrieval_settings?: Record<string, unknown>;
+  knowledge_engine?: KnowledgeEngineInfo;
 }
 
-export interface ExternalKnowledgeBase {
-  uuid?: string;
-  name: string;
-  description: string;
-  created_at?: string;
-  plugin_author: string;
-  plugin_name: string;
-  retriever_name: string;
-  retriever_config?: Record<string, unknown>;
-  emoji?: string;
+// Knowledge Engine types
+export interface KnowledgeEngineInfo {
+  plugin_id: string | null;
+  name: I18nObject;
+  capabilities: string[];
 }
 
-export interface ApiRespExternalKnowledgeBases {
-  bases: ExternalKnowledgeBase[];
+export interface KnowledgeEngine {
+  plugin_id: string;
+  name: I18nObject;
+  description?: I18nObject;
+  capabilities: string[];
+  // Schema format: Array of form field definitions (IDynamicFormItemSchema-like)
+  // Each item: { name, label, type, required, default, description?, options? }
+  creation_schema?: unknown[];
+  retrieval_schema?: unknown[];
 }
 
-export interface ApiRespExternalKnowledgeBase {
-  base: ExternalKnowledgeBase;
+export interface ApiRespKnowledgeEngines {
+  engines: KnowledgeEngine[];
+}
+
+export interface ParserInfo {
+  plugin_id: string;
+  name: I18nObject;
+  description?: I18nObject;
+  supported_mime_types: string[];
+}
+
+export interface ApiRespParsers {
+  parsers: ParserInfo[];
 }
 
 export interface ApiRespKnowledgeBaseFiles {
@@ -257,6 +262,12 @@ export interface ApiRespSystemInfo {
   limitation: SystemLimitation;
 }
 
+export interface RagMigrationStatusResp {
+  needed: boolean;
+  internal_kb_count: number;
+  external_kb_count: number;
+}
+
 export interface ApiRespPluginSystemStatus {
   is_enable: boolean;
   is_connected: boolean;

web/src/app/infra/entities/form/dynamic.ts

@@ -1,5 +1,12 @@
 import { I18nObject } from '@/app/infra/entities/common';
 
+export interface IShowIfCondition {
+  field: string;
+  operator: 'eq' | 'neq' | 'in';
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  value: any;
+}
+
 export interface IDynamicFormItemSchema {
   id: string;
   default: string | number | boolean | Array<unknown>;
@@ -9,6 +16,7 @@ export interface IDynamicFormItemSchema {
   type: DynamicFormItemType;
   description?: I18nObject;
   options?: IDynamicFormItemOption[];
+  show_if?: IShowIfCondition;
 
   /** when type is PLUGIN_SELECTOR, the scopes is the scopes of components(plugin contains), the default is all */
   scopes?: string[];
@@ -26,6 +34,7 @@ export enum DynamicFormItemType {
   FILE_ARRAY = 'array[file]',
   SELECT = 'select',
   LLM_MODEL_SELECTOR = 'llm-model-selector',
+  EMBEDDING_MODEL_SELECTOR = 'embedding-model-selector',
   PROMPT_EDITOR = 'prompt-editor',
   UNKNOWN = 'unknown',
   KNOWLEDGE_BASE_SELECTOR = 'knowledge-base-selector',

web/src/app/infra/http/BackendClient.ts

@@ -35,12 +35,12 @@ import {
   ApiRespMCPServers,
   ApiRespMCPServer,
   MCPServer,
-  ExternalKnowledgeBase,
-  ApiRespExternalKnowledgeBases,
-  ApiRespExternalKnowledgeBase,
   ApiRespModelProviders,
   ApiRespModelProvider,
   ModelProvider,
+  ApiRespKnowledgeEngines,
+  ApiRespParsers,
+  RagMigrationStatusResp,
 } from '@/app/infra/entities/api';
 import { Plugin } from '@/app/infra/entities/plugin';
 import { GetBotLogsRequest } from '@/app/infra/http/requestParam/bots/GetBotLogsRequest';
@@ -356,6 +356,7 @@ export class BackendClient extends BaseHttpClient {
       is_active: boolean;
       platform: string | null;
       user_id: string | null;
+      user_name: string | null;
     }>;
     total: number;
   }> {
@@ -384,6 +385,7 @@ export class BackendClient extends BaseHttpClient {
       level: string;
       platform: string | null;
       user_id: string | null;
+      user_name: string | null;
       runner_name: string | null;
       variables: string | null;
       role: string | null;
@@ -435,9 +437,11 @@ export class BackendClient extends BaseHttpClient {
   public uploadKnowledgeBaseFile(
     uuid: string,
     file_id: string,
+    parserPluginId?: string,
   ): Promise<object> {
     return this.post(`/api/v1/knowledge/bases/${uuid}/files`, {
       file_id,
+      parser_plugin_id: parserPluginId,
     });
   }
 
@@ -461,49 +465,23 @@ export class BackendClient extends BaseHttpClient {
   public retrieveKnowledgeBase(
     uuid: string,
     query: string,
+    retrievalSettings?: Record<string, unknown>,
   ): Promise<ApiRespKnowledgeBaseRetrieve> {
-    return this.post(`/api/v1/knowledge/bases/${uuid}/retrieve`, { query });
-  }
-
-  // ============ External Knowledge Base API ============
-  public getExternalKnowledgeBases(): Promise<ApiRespExternalKnowledgeBases> {
-    return this.get('/api/v1/knowledge/external-bases');
-  }
-
-  public getExternalKnowledgeBase(
-    uuid: string,
-  ): Promise<ApiRespExternalKnowledgeBase> {
-    return this.get(`/api/v1/knowledge/external-bases/${uuid}`);
-  }
-
-  public createExternalKnowledgeBase(
-    base: ExternalKnowledgeBase,
-  ): Promise<{ uuid: string }> {
-    return this.post('/api/v1/knowledge/external-bases', base);
-  }
-
-  public updateExternalKnowledgeBase(
-    uuid: string,
-    base: ExternalKnowledgeBase,
-  ): Promise<{ uuid: string }> {
-    return this.put(`/api/v1/knowledge/external-bases/${uuid}`, base);
-  }
-
-  public deleteExternalKnowledgeBase(uuid: string): Promise<object> {
-    return this.delete(`/api/v1/knowledge/external-bases/${uuid}`);
-  }
-
-  public retrieveExternalKnowledgeBase(
-    uuid: string,
-    query: string,
-  ): Promise<ApiRespKnowledgeBaseRetrieve> {
-    return this.post(`/api/v1/knowledge/external-bases/${uuid}/retrieve`, {
+    return this.post(`/api/v1/knowledge/bases/${uuid}/retrieve`, {
       query,
+      retrieval_settings: retrievalSettings ?? {},
     });
   }
 
-  public listKnowledgeRetrievers(): Promise<{ retrievers: unknown[] }> {
-    return this.get('/api/v1/knowledge/external-bases/retrievers');
+  // ============ Knowledge Engines API ============
+  public getKnowledgeEngines(): Promise<ApiRespKnowledgeEngines> {
+    return this.get('/api/v1/knowledge/engines');
+  }
+
+  // ============ Parsers API ============
+  public listParsers(mimeType?: string): Promise<ApiRespParsers> {
+    const params = mimeType ? `?mime_type=${encodeURIComponent(mimeType)}` : '';
+    return this.get(`/api/v1/knowledge/parsers${params}`);
   }
 
   // ============ Plugins API ============
@@ -735,6 +713,23 @@ export class BackendClient extends BaseHttpClient {
     return this.get('/api/v1/system/status/plugin-system');
   }
 
+  // ============ RAG Migration API ============
+  public getRagMigrationStatus(): Promise<RagMigrationStatusResp> {
+    return this.get('/api/v1/knowledge/migration/status');
+  }
+
+  public executeRagMigration(
+    installPlugin: boolean = true,
+  ): Promise<AsyncTaskCreatedResp> {
+    return this.post('/api/v1/knowledge/migration/execute', {
+      install_plugin: installPlugin,
+    });
+  }
+
+  public dismissRagMigration(): Promise<object> {
+    return this.post('/api/v1/knowledge/migration/dismiss');
+  }
+
   public getPluginDebugInfo(): Promise<{
     debug_url: string;
     plugin_debug_key: string;

web/src/app/login/page.tsx

@@ -284,6 +284,27 @@ export default function Login() {
               </form>
             </Form>
           )}
+
+          <p className="text-xs text-center text-muted-foreground">
+            {t('common.agreementNotice')}{' '}
+            <a
+              href="https://langbot.app/privacy"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="underline hover:text-foreground transition-colors"
+            >
+              {t('common.privacyPolicy')}
+            </a>{' '}
+            {t('common.and')}{' '}
+            <a
+              href={t('common.dataCollectionPolicyUrl')}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="underline hover:text-foreground transition-colors"
+            >
+              {t('common.dataCollectionPolicy')}
+            </a>
+          </p>
         </CardContent>
       </Card>
     </div>

web/src/app/register/page.tsx

@@ -253,6 +253,27 @@ export default function Register() {
               </Button>
             </form>
           </Form>
+
+          <p className="text-xs text-center text-muted-foreground">
+            {t('common.agreementNotice')}{' '}
+            <a
+              href="https://langbot.app/privacy"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="underline hover:text-foreground transition-colors"
+            >
+              {t('common.privacyPolicy')}
+            </a>{' '}
+            {t('common.and')}{' '}
+            <a
+              href={t('common.dataCollectionPolicyUrl')}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="underline hover:text-foreground transition-colors"
+            >
+              {t('common.dataCollectionPolicy')}
+            </a>
+          </p>
         </CardContent>
       </Card>
     </div>