feat(memory): add session-based chat history and user metadata retrieval

- Add ChatSessionCache to manage chat history per session
- Add SEARCH_USER_METADATA cypher query for retrieving user entity metadata
- Add "str" mode support to StructResponse for raw text extraction
- Add content_str field to MemorySearchResult for pre-formatted content
- Fix sandbox URL by removing hardcoded port
- Add description field to entity search results
- Remove history from UserInput schema, use session_id instead

.gitignore

@@ -10,9 +10,7 @@ api/res/
 
 # Virtual environments
 .venv
-docs/*
-!docs/rag/
-!docs/rag/**
+docs/
 examples/
 
 # Environment variables

api/app/celery_task_scheduler.py

@@ -158,12 +158,19 @@ class RedisTaskScheduler:
         return {"status": status, "task_id": task_id, "result": result_content}
 
     def _cleanup_finished(self):
-        pending = self.redis.hgetall(PENDING_HASH)
-        if not pending:
+        cursor = 0
+        all_pending = {}
+        while True:
+            cursor, batch = self.redis.hscan(PENDING_HASH, cursor=cursor, count=100)
+            all_pending.update(batch)
+            if cursor == 0:
+                break
+
+        if not all_pending:
             return
 
         now = time.time()
-        task_ids = list(pending.keys())
+        task_ids = list(all_pending.keys())
 
         pipe = self.redis.pipeline()
         for task_id in task_ids:
@@ -176,7 +183,7 @@ class RedisTaskScheduler:
 
         for task_id, raw_result in zip(task_ids, results):
             try:
-                meta = json.loads(pending[task_id])
+                meta = json.loads(all_pending[task_id])
                 lock_key = meta["lock_key"]
                 dispatched_at = meta.get("dispatched_at", 0)
                 age = now - dispatched_at
@@ -276,6 +283,22 @@ class RedisTaskScheduler:
             return True
         return stable_hash(user_id) % self._shard_count == self._shard_index
 
+    def _commit_post_dispatch(self, lock_key, task, msg_id, dispatch_lock):
+        pipe = self.redis.pipeline()
+        pipe.set(lock_key, task.id, ex=3600)
+        pipe.hset(PENDING_HASH, task.id, json.dumps({
+            "lock_key": lock_key,
+            "dispatched_at": time.time(),
+            "msg_id": msg_id,
+        }))
+        pipe.delete(dispatch_lock)
+        pipe.set(
+            f"task_tracker:{msg_id}",
+            json.dumps({"status": "DISPATCHED", "task_id": task.id}),
+            ex=86400,
+        )
+        pipe.execute()
+
     def _dispatch(self, msg_id, msg_data) -> bool:
         user_id = msg_data["user_id"]
         task_name = msg_data["task_name"]
@@ -308,28 +331,17 @@ class RedisTaskScheduler:
                 task_name, user_id, msg_id, e, exc_info=True,
             )
             return False
-
-        try:
-            pipe = self.redis.pipeline()
-            pipe.set(lock_key, task.id, ex=3600)
-            pipe.hset(PENDING_HASH, task.id, json.dumps({
-                "lock_key": lock_key,
-                "dispatched_at": time.time(),
-                "msg_id": msg_id,
-            }))
-            pipe.delete(dispatch_lock)
-            pipe.set(
-                f"task_tracker:{msg_id}",
-                json.dumps({"status": "DISPATCHED", "task_id": task.id}),
-                ex=86400,
-            )
-            pipe.execute()
-        except Exception as e:
-            logger.error(
-                "Post-dispatch state update failed for %s: %s",
-                task.id, e, exc_info=True,
-            )
-            self.errors += 1
+        for attempt in range(2):
+            try:
+                self._commit_post_dispatch(lock_key, task, msg_id, dispatch_lock)
+                break
+            except Exception as e:
+                logger.error(
+                    "Post-dispatch state update failed for %s: %s",
+                    task.id, e, exc_info=True,
+                )
+                time.sleep(0.1)
+                self.errors += 1
 
         self.dispatched += 1
         logger.info("Task dispatched: %s (msg=%s)", task.id, msg_id)
@@ -367,22 +379,21 @@ class RedisTaskScheduler:
             return
 
         for uid, msg in candidates:
+            queue_key = f"{USER_QUEUE_PREFIX}{uid}"
             if self._dispatch(msg["msg_id"], msg):
-                self.redis.lpop(f"{USER_QUEUE_PREFIX}{uid}")
+                self.redis.lpop(queue_key)
+                if self.redis.llen(queue_key) > 0:
+                    self.redis.sadd(READY_SET, uid)
 
     def schedule_loop(self):
         self._heartbeat()
         self._cleanup_finished()
 
-        pipe = self.redis.pipeline()
-        pipe.smembers(READY_SET)
-        pipe.delete(READY_SET)
-        results = pipe.execute()
-        ready_users = results[0] or set()
-
+        ready_users = self.redis.smembers(READY_SET) or set()
         my_users = [uid for uid in ready_users if self._is_mine(uid)]
-
-        if not my_users:
+        if my_users:
+            self.redis.srem(READY_SET, *my_users)
+        else:
             time.sleep(0.5)
             return
 
@@ -445,7 +456,7 @@ class RedisTaskScheduler:
             "Scheduler started: instance=%s", self.instance_id,
         )
 
-        while True:
+        while self.running:
             try:
                 self.schedule_loop()
 
@@ -480,9 +491,7 @@ class RedisTaskScheduler:
             logger.error("Shutdown cleanup error: %s", e)
 
 
-scheduler: RedisTaskScheduler | None = None
-if scheduler is None:
-    scheduler = RedisTaskScheduler()
+scheduler = RedisTaskScheduler()
 
 if __name__ == "__main__":
     import signal

api/app/controllers/chunk_controller.py

@@ -82,19 +82,32 @@ async def get_preview_chunks(
             detail="The file does not exist or you do not have permission to access it"
         )
 
-    # 5. Construct file path：/files/{kb_id}/{parent_id}/{file.id}{file.file_ext}
-    file_path = os.path.join(
-        settings.FILE_PATH,
-        str(db_file.kb_id),
-        str(db_file.parent_id),
-        f"{db_file.id}{db_file.file_ext}"
-    )
-
-    # 6. Check if the file exists
-    if not os.path.exists(file_path):
+    # 5. Get file content from storage backend
+    if not db_file.file_key:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
-            detail="File not found (possibly deleted)"
+            detail="File has no storage key (legacy data not migrated)"
+        )
+
+    from app.services.file_storage_service import FileStorageService
+    import asyncio
+    storage_service = FileStorageService()
+
+    async def _download():
+        return await storage_service.download_file(db_file.file_key)
+
+    try:
+        file_binary = asyncio.run(_download())
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        try:
+            file_binary = loop.run_until_complete(_download())
+        finally:
+            loop.close()
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"File not found in storage: {e}"
         )
 
     # 7. Document parsing & segmentation
@@ -104,11 +117,12 @@ async def get_preview_chunks(
     vision_model = QWenCV(
             key=db_knowledge.image2text.api_keys[0].api_key,
             model_name=db_knowledge.image2text.api_keys[0].model_name,
-            lang="Chinese",  # Default to Chinese
+            lang="Chinese",
             base_url=db_knowledge.image2text.api_keys[0].api_base
         )
     from app.core.rag.app.naive import chunk
-    res = chunk(filename=file_path,
+    res = chunk(filename=db_file.file_name,
+                binary=file_binary,
                 from_page=0,
                 to_page=5,
                 callback=progress_callback,

api/app/controllers/document_controller.py

@@ -20,6 +20,7 @@ from app.models.user_model import User
 from app.schemas import document_schema
 from app.schemas.response_schema import ApiResponse
 from app.services import document_service, file_service, knowledge_service
+from app.services.file_storage_service import FileStorageService, get_file_storage_service
 
 
 # Obtain a dedicated API logger
@@ -231,7 +232,8 @@ async def update_document(
 async def delete_document(
         document_id: uuid.UUID,
         db: Session = Depends(get_db),
-        current_user: User = Depends(get_current_user)
+        current_user: User = Depends(get_current_user),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
 ):
     """
     Delete document
@@ -257,7 +259,7 @@ async def delete_document(
         db.commit()
 
         # 3. Delete file
-        await file_controller._delete_file(db=db, file_id=file_id, current_user=current_user)
+        await file_controller._delete_file(db=db, file_id=file_id, current_user=current_user, storage_service=storage_service)
 
         # 4. Delete vector index
         db_knowledge = knowledge_service.get_knowledge_by_id(db, knowledge_id=db_document.kb_id, current_user=current_user)
@@ -305,38 +307,25 @@ async def parse_documents(
                 detail="The file does not exist or you do not have permission to access it"
             )
 
-        # 3. Construct file path：/files/{kb_id}/{parent_id}/{file.id}{file.file_ext}
-        file_path = os.path.join(
-            settings.FILE_PATH,
-            str(db_file.kb_id),
-            str(db_file.parent_id),
-            f"{db_file.id}{db_file.file_ext}"
-        )
-
-        # 4. Check if the file exists
-        api_logger.debug(f"Constructed file path: {file_path}")
-        api_logger.debug(f"File metadata - kb_id: {db_file.kb_id}, parent_id: {db_file.parent_id}, file_id: {db_file.id}, extension: {db_file.file_ext}")
-        if not os.path.exists(file_path):
-            api_logger.error(f"File not found (possibly deleted): file_path={file_path}, file_id={db_file.id}, document_id={document_id}")
+        # 3. Get file_key for storage backend
+        if not db_file.file_key:
+            api_logger.error(f"File has no storage key (legacy data not migrated): file_id={db_file.id}")
             raise HTTPException(
                 status_code=status.HTTP_404_NOT_FOUND,
-                detail="File not found (possibly deleted)"
+                detail="File has no storage key (legacy data not migrated)"
             )
 
-        # 5. Obtain knowledge base information
-        api_logger.info( f"Obtain details of the knowledge base: knowledge_id={db_document.kb_id}")
+        # 4. Obtain knowledge base information
+        api_logger.info(f"Obtain details of the knowledge base: knowledge_id={db_document.kb_id}")
         db_knowledge = knowledge_service.get_knowledge_by_id(db, knowledge_id=db_document.kb_id, current_user=current_user)
         if not db_knowledge:
-            api_logger.warning(f"The knowledge base does not exist or access is denied: knowledge_id={db_document.kb_id}")
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail="The knowledge base does not exist or access is denied"
-            )
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Knowledge base not found")
 
-        # 6. Task: Document parsing, vectorization, and storage
-        # from app.tasks import parse_document
-        # parse_document(file_path, document_id)
-        task = celery_app.send_task("app.core.rag.tasks.parse_document", args=[file_path, document_id])
+        # 5. Dispatch parse task with file_key (not file_path)
+        task = celery_app.send_task(
+            "app.core.rag.tasks.parse_document",
+            args=[db_file.file_key, document_id, db_file.file_name]
+        )
         result = {
             "task_id": task.id
         }

api/app/controllers/file_controller.py

@@ -1,12 +1,10 @@
 import os
-from pathlib import Path
-import shutil
 from typing import Any, Optional
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, status, File, UploadFile, Query
 from fastapi.encoders import jsonable_encoder
-from fastapi.responses import FileResponse
+from fastapi.responses import Response
 from sqlalchemy.orm import Session
 
 from app.core.config import settings
@@ -19,10 +17,14 @@ from app.models.user_model import User
 from app.schemas import file_schema, document_schema
 from app.schemas.response_schema import ApiResponse
 from app.services import file_service, document_service
+from app.services.knowledge_service import get_knowledge_by_id as get_kb_by_id
+from app.services.file_storage_service import (
+    FileStorageService,
+    generate_kb_file_key,
+    get_file_storage_service,
+)
 from app.core.quota_stub import check_knowledge_capacity_quota
 
-
-# Obtain a dedicated API logger
 api_logger = get_api_logger()
 
 router = APIRouter(
@@ -35,67 +37,37 @@ router = APIRouter(
 async def get_files(
         kb_id: uuid.UUID,
         parent_id: uuid.UUID,
-        page: int = Query(1, gt=0),  # Default: 1, which must be greater than 0
-        pagesize: int = Query(20, gt=0, le=100),  # Default: 20 items per page, maximum: 100 items
+        page: int = Query(1, gt=0),
+        pagesize: int = Query(20, gt=0, le=100),
         orderby: Optional[str] = Query(None, description="Sort fields, such as: created_at"),
         desc: Optional[bool] = Query(False, description="Is it descending order"),
         keywords: Optional[str] = Query(None, description="Search keywords (file name)"),
         db: Session = Depends(get_db),
         current_user: User = Depends(get_current_user)
 ):
-    """
-    Paged query file list
-    - Support filtering by kb_id and parent_id
-    - Support keyword search for file names
-    - Support dynamic sorting
-    - Return paging metadata + file list
-    """
-    api_logger.info(f"Query file list: kb_id={kb_id}, parent_id={parent_id}, page={page}, pagesize={pagesize}, keywords={keywords}, username: {current_user.username}")
-    # 1. parameter validation
-    if page < 1 or pagesize < 1:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="The paging parameter must be greater than 0"
-        )
+    """Paged query file list"""
+    api_logger.info(f"Query file list: kb_id={kb_id}, parent_id={parent_id}, page={page}, pagesize={pagesize}")
 
-    # 2. Construct query conditions
-    filters = [
-        file_model.File.kb_id == kb_id
-    ]
+    if page < 1 or pagesize < 1:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="The paging parameter must be greater than 0")
+
+    filters = [file_model.File.kb_id == kb_id]
     if parent_id:
         filters.append(file_model.File.parent_id == parent_id)
-    # Keyword search (fuzzy matching of file name)
     if keywords:
         filters.append(file_model.File.file_name.ilike(f"%{keywords}%"))
 
-    # 3. Execute paged query
     try:
-        api_logger.debug("Start executing file paging query")
         total, items = file_service.get_files_paginated(
-            db=db,
-            filters=filters,
-            page=page,
-            pagesize=pagesize,
-            orderby=orderby,
-            desc=desc,
-            current_user=current_user
+            db=db, filters=filters, page=page, pagesize=pagesize,
+            orderby=orderby, desc=desc, current_user=current_user
         )
-        api_logger.info(f"File query successful: total={total}, returned={len(items)} records")
     except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Query failed: {str(e)}"
-        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Query failed: {str(e)}")
 
-    # 4. Return structured response
     result = {
         "items": items,
-        "page": {
-            "page": page,
-            "pagesize": pagesize,
-            "total": total,
-            "has_next": True if page * pagesize < total else False
-        }
+        "page": {"page": page, "pagesize": pagesize, "total": total, "has_next": page * pagesize < total}
     }
     return success(data=jsonable_encoder(result), msg="Query of file list succeeded")
 
@@ -108,23 +80,14 @@ async def create_folder(
         db: Session = Depends(get_db),
         current_user: User = Depends(get_current_user),
 ):
-    """
-    Create a new folder
-    """
-    api_logger.info(f"Create folder request: kb_id={kb_id}, parent_id={parent_id}, folder_name={folder_name}, username: {current_user.username}")
-
+    """Create a new folder"""
+    api_logger.info(f"Create folder request: kb_id={kb_id}, parent_id={parent_id}, folder_name={folder_name}")
     try:
-        api_logger.debug(f"Start creating a folder: {folder_name}")
-        create_folder = file_schema.FileCreate(
-            kb_id=kb_id,
-            created_by=current_user.id,
-            parent_id=parent_id,
-            file_name=folder_name,
-            file_ext='folder',
-            file_size=0,
+        create_folder_data = file_schema.FileCreate(
+            kb_id=kb_id, created_by=current_user.id, parent_id=parent_id,
+            file_name=folder_name, file_ext='folder', file_size=0,
         )
-        db_file = file_service.create_file(db=db, file=create_folder, current_user=current_user)
-        api_logger.info(f"Folder created successfully: {db_file.file_name} (ID: {db_file.id})")
+        db_file = file_service.create_file(db=db, file=create_folder_data, current_user=current_user)
         return success(data=jsonable_encoder(file_schema.File.model_validate(db_file)), msg="Folder creation successful")
     except Exception as e:
         api_logger.error(f"Folder creation failed: {folder_name} - {str(e)}")
@@ -138,76 +101,58 @@ async def upload_file(
         parent_id: uuid.UUID,
         file: UploadFile = File(...),
         db: Session = Depends(get_db),
-        current_user: User = Depends(get_current_user)
+        current_user: User = Depends(get_current_user),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
 ):
-    """
-    upload file
-    """
-    api_logger.info(f"upload file request: kb_id={kb_id}, parent_id={parent_id}, filename={file.filename}, username: {current_user.username}")
+    """Upload file to storage backend"""
+    api_logger.info(f"upload file request: kb_id={kb_id}, parent_id={parent_id}, filename={file.filename}")
 
-    # Read the contents of the file
     contents = await file.read()
-    # Check file size
     file_size = len(contents)
-    print(f"file size: {file_size} byte")
     if file_size == 0:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="The file is empty."
-        )
-    # If the file size exceeds 50MB (50 * 1024 * 1024 bytes)
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="The file is empty.")
     if file_size > settings.MAX_FILE_SIZE:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"The file size exceeds the {settings.MAX_FILE_SIZE}byte limit"
-        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"File size exceeds {settings.MAX_FILE_SIZE} byte limit")
 
-    # Extract the extension using `os.path.splitext`
     _, file_extension = os.path.splitext(file.filename)
-    upload_file = file_schema.FileCreate(
-        kb_id=kb_id,
-        created_by=current_user.id,
-        parent_id=parent_id,
-        file_name=file.filename,
-        file_ext=file_extension.lower(),
-        file_size=file_size,
+    file_ext = file_extension.lower()
+
+    # Create File record
+    upload_file_data = file_schema.FileCreate(
+        kb_id=kb_id, created_by=current_user.id, parent_id=parent_id,
+        file_name=file.filename, file_ext=file_ext, file_size=file_size,
     )
-    db_file = file_service.create_file(db=db, file=upload_file, current_user=current_user)
+    db_file = file_service.create_file(db=db, file=upload_file_data, current_user=current_user)
 
-    # Construct a save path：/files/{kb_id}/{parent_id}/{file.id}{file_extension}
-    save_dir = os.path.join(settings.FILE_PATH, str(kb_id), str(parent_id))
-    Path(save_dir).mkdir(parents=True, exist_ok=True)  # Ensure that the directory exists
-    save_path = os.path.join(save_dir, f"{db_file.id}{db_file.file_ext}")
+    # Upload to storage backend
+    file_key = generate_kb_file_key(kb_id=kb_id, file_id=db_file.id, file_ext=file_ext)
+    try:
+        await storage_service.storage.upload(file_key=file_key, content=contents, content_type=file.content_type)
+    except Exception as e:
+        api_logger.error(f"Storage upload failed: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"File storage failed: {str(e)}")
 
-    # Save file
-    with open(save_path, "wb") as f:
-        f.write(contents)
+    # Save file_key
+    db_file.file_key = file_key
+    db.commit()
+    db.refresh(db_file)
 
-    # Verify whether the file has been saved successfully
-    if not os.path.exists(save_path):
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="File save failed"
-        )
+    # Create document (inherit parser_config from knowledge base)
+    default_parser_config = {
+        "layout_recognize": "DeepDOC", "chunk_token_num": 128, "delimiter": "\n",
+        "auto_keywords": 0, "auto_questions": 0, "html4excel": "false"
+    }
+    try:
+        db_knowledge = get_kb_by_id(db, knowledge_id=kb_id, current_user=current_user)
+        if db_knowledge and db_knowledge.parser_config:
+            default_parser_config.update(dict(db_knowledge.parser_config))
+    except Exception:
+        pass
 
-    # Create a document
     create_data = document_schema.DocumentCreate(
-        kb_id=kb_id,
-        created_by=current_user.id,
-        file_id=db_file.id,
-        file_name=db_file.file_name,
-        file_ext=db_file.file_ext,
-        file_size=db_file.file_size,
-        file_meta={},
-        parser_id="naive",
-        parser_config={
-            "layout_recognize": "DeepDOC",
-            "chunk_token_num": 128,
-            "delimiter": "\n",
-            "auto_keywords": 0,
-            "auto_questions": 0,
-            "html4excel": "false"
-        }
+        kb_id=kb_id, created_by=current_user.id, file_id=db_file.id,
+        file_name=db_file.file_name, file_ext=db_file.file_ext, file_size=db_file.file_size,
+        file_meta={}, parser_id="naive", parser_config=default_parser_config
     )
     db_document = document_service.create_document(db=db, document=create_data, current_user=current_user)
 
@@ -221,123 +166,73 @@ async def custom_text(
         parent_id: uuid.UUID,
         create_data: file_schema.CustomTextFileCreate,
         db: Session = Depends(get_db),
-        current_user: User = Depends(get_current_user)
+        current_user: User = Depends(get_current_user),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
 ):
-    """
-    custom text
-    """
-    api_logger.info(f"custom text upload request: kb_id={kb_id}, parent_id={parent_id}, title={create_data.title}, content={create_data.content}, username: {current_user.username}")
-
-    # Check file content size
-    # 将内容编码为字节（UTF-8）
+    """Custom text upload"""
     content_bytes = create_data.content.encode('utf-8')
     file_size = len(content_bytes)
-    print(f"file size: {file_size} byte")
     if file_size == 0:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="The content is empty."
-        )
-    # If the file size exceeds 50MB (50 * 1024 * 1024 bytes)
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="The content is empty.")
     if file_size > settings.MAX_FILE_SIZE:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"The content size exceeds the {settings.MAX_FILE_SIZE}byte limit"
-        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Content size exceeds {settings.MAX_FILE_SIZE} byte limit")
 
-    upload_file = file_schema.FileCreate(
-        kb_id=kb_id,
-        created_by=current_user.id,
-        parent_id=parent_id,
-        file_name=f"{create_data.title}.txt",
-        file_ext=".txt",
-        file_size=file_size,
+    upload_file_data = file_schema.FileCreate(
+        kb_id=kb_id, created_by=current_user.id, parent_id=parent_id,
+        file_name=f"{create_data.title}.txt", file_ext=".txt", file_size=file_size,
     )
-    db_file = file_service.create_file(db=db, file=upload_file, current_user=current_user)
+    db_file = file_service.create_file(db=db, file=upload_file_data, current_user=current_user)
 
-    # Construct a save path：/files/{kb_id}/{parent_id}/{file.id}{file_extension}
-    save_dir = os.path.join(settings.FILE_PATH, str(kb_id), str(parent_id))
-    Path(save_dir).mkdir(parents=True, exist_ok=True)  # Ensure that the directory exists
-    save_path = os.path.join(save_dir, f"{db_file.id}.txt")
+    # Upload to storage backend
+    file_key = generate_kb_file_key(kb_id=kb_id, file_id=db_file.id, file_ext=".txt")
+    try:
+        await storage_service.storage.upload(file_key=file_key, content=content_bytes, content_type="text/plain")
+    except Exception as e:
+        api_logger.error(f"Storage upload failed: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"File storage failed: {str(e)}")
 
-    # Save file
-    with open(save_path, "wb") as f:
-        f.write(content_bytes)
+    db_file.file_key = file_key
+    db.commit()
+    db.refresh(db_file)
 
-    # Verify whether the file has been saved successfully
-    if not os.path.exists(save_path):
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="File save failed"
-        )
-
-    # Create a document
     create_document_data = document_schema.DocumentCreate(
-        kb_id=kb_id,
-        created_by=current_user.id,
-        file_id=db_file.id,
-        file_name=db_file.file_name,
-        file_ext=db_file.file_ext,
-        file_size=db_file.file_size,
-        file_meta={},
-        parser_id="naive",
-        parser_config={
-            "layout_recognize": "DeepDOC",
-            "chunk_token_num": 128,
-            "delimiter": "\n",
-            "auto_keywords": 0,
-            "auto_questions": 0,
-            "html4excel": "false"
-        }
+        kb_id=kb_id, created_by=current_user.id, file_id=db_file.id,
+        file_name=db_file.file_name, file_ext=db_file.file_ext, file_size=db_file.file_size,
+        file_meta={}, parser_id="naive",
+        parser_config={"layout_recognize": "DeepDOC", "chunk_token_num": 128, "delimiter": "\n",
+                       "auto_keywords": 0, "auto_questions": 0, "html4excel": "false"}
     )
     db_document = document_service.create_document(db=db, document=create_document_data, current_user=current_user)
 
-    api_logger.info(f"custom text upload successfully: {create_data.title} (file_id: {db_file.id}, document_id: {db_document.id})")
     return success(data=jsonable_encoder(document_schema.Document.model_validate(db_document)), msg="custom text upload successful")
 
 
 @router.get("/{file_id}", response_model=Any)
 async def get_file(
         file_id: uuid.UUID,
-        db: Session = Depends(get_db)
+        db: Session = Depends(get_db),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
 ) -> Any:
-    """
-    Download the file based on the file_id
-    - Query file information from the database
-    - Construct the file path and check if it exists
-    - Return a FileResponse to download the file
-    """
-    api_logger.info(f"Download the file based on the file_id: file_id={file_id}")
-
-    # 1. Query file information from the database
+    """Download file by file_id"""
     db_file = file_service.get_file_by_id(db, file_id=file_id)
     if not db_file:
-        api_logger.warning(f"The file does not exist or you do not have permission to access it: file_id={file_id}")
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="The file does not exist or you do not have permission to access it"
-        )
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File not found")
 
-    # 2. Construct file path：/files/{kb_id}/{parent_id}/{file.id}{file.file_ext}
-    file_path = os.path.join(
-        settings.FILE_PATH,
-        str(db_file.kb_id),
-        str(db_file.parent_id),
-        f"{db_file.id}{db_file.file_ext}"
-    )
+    if not db_file.file_key:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File has no storage key (legacy data not migrated)")
 
-    # 3. Check if the file exists
-    if not os.path.exists(file_path):
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="File not found (possibly deleted)"
-        )
+    try:
+        content = await storage_service.download_file(db_file.file_key)
+    except Exception as e:
+        api_logger.error(f"Storage download failed: {e}")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File not found in storage")
 
-    # 4.Return FileResponse (automatically handle download)
-    return FileResponse(
-        path=file_path,
-        filename=db_file.file_name,  # Use original file name
-        media_type="application/octet-stream"  # Universal binary stream type
+    import mimetypes
+    media_type = mimetypes.guess_type(db_file.file_name)[0] or "application/octet-stream"
+    return Response(
+        content=content,
+        media_type=media_type,
+        headers={"Content-Disposition": f'attachment; filename="{db_file.file_name}"'}
     )
 
 
@@ -348,50 +243,22 @@ async def update_file(
         db: Session = Depends(get_db),
         current_user: User = Depends(get_current_user)
 ):
-    """
-    Update file information (such as file name)
-    - Only specified fields such as file_name are allowed to be modified
-    """
-    api_logger.debug(f"Query the file to be updated: {file_id}")
-
-    # 1. Check if the file exists
+    """Update file information (such as file name)"""
     db_file = file_service.get_file_by_id(db, file_id=file_id)
-
     if not db_file:
-        api_logger.warning(f"The file does not exist or you do not have permission to access it: file_id={file_id}")
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="The file does not exist or you do not have permission to access it"
-        )
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File not found")
 
-    # 2. Update fields (only update non-null fields)
-    api_logger.debug(f"Start updating the file fields: {file_id}")
-    updated_fields = []
     for field, value in update_data.dict(exclude_unset=True).items():
         if hasattr(db_file, field):
-            old_value = getattr(db_file, field)
-            if old_value != value:
-                # update value
-                setattr(db_file, field, value)
-                updated_fields.append(f"{field}: {old_value} -> {value}")
+            setattr(db_file, field, value)
 
-    if updated_fields:
-        api_logger.debug(f"updated fields: {', '.join(updated_fields)}")
-
-    # 3. Save to database
     try:
         db.commit()
         db.refresh(db_file)
-        api_logger.info(f"The file has been successfully updated: {db_file.file_name} (ID: {db_file.id})")
     except Exception as e:
         db.rollback()
-        api_logger.error(f"File update failed: file_id={file_id} - {str(e)}")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"File update failed: {str(e)}"
-        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"File update failed: {str(e)}")
 
-    # 4. Return the updated file
     return success(data=jsonable_encoder(file_schema.File.model_validate(db_file)), msg="File information updated successfully")
 
 
@@ -399,60 +266,43 @@ async def update_file(
 async def delete_file(
         file_id: uuid.UUID,
         db: Session = Depends(get_db),
-        current_user: User = Depends(get_current_user)
+        current_user: User = Depends(get_current_user),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
 ):
-    """
-    Delete a file or folder
-    """
-    api_logger.info(f"Request to delete file: file_id={file_id}, username: {current_user.username}")
-    await _delete_file(db=db, file_id=file_id, current_user=current_user)
+    """Delete a file or folder"""
+    api_logger.info(f"Request to delete file: file_id={file_id}")
+    await _delete_file(db=db, file_id=file_id, current_user=current_user, storage_service=storage_service)
     return success(msg="File deleted successfully")
 
+
 async def _delete_file(
         file_id: uuid.UUID,
-        db: Session = Depends(get_db),
-        current_user: User = Depends(get_current_user)
+        db: Session,
+        current_user: User,
+        storage_service: FileStorageService,
 ) -> None:
-    """
-    Delete a file or folder
-    """
-    # 1. Check if the file exists
+    """Delete a file or folder from storage and database"""
     db_file = file_service.get_file_by_id(db, file_id=file_id)
-
     if not db_file:
-        api_logger.warning(f"The file does not exist or you do not have permission to access it: file_id={file_id}")
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="The file does not exist or you do not have permission to access it"
-        )
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File not found")
 
-    # 2. Construct physical path
-    file_path = Path(
-        settings.FILE_PATH,
-        str(db_file.kb_id),
-        str(db_file.id)
-    ) if db_file.file_ext == 'folder' else Path(
-        settings.FILE_PATH,
-        str(db_file.kb_id),
-        str(db_file.parent_id),
-        f"{db_file.id}{db_file.file_ext}"
-    )
-
-    # 3. Delete physical files/folders
-    try:
-        if file_path.exists():
-            if db_file.file_ext == 'folder':
-                shutil.rmtree(file_path)  # Recursively delete folders
-            else:
-                file_path.unlink()  # Delete a single file
-    except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to delete physical file/folder: {str(e)}"
-        )
-
-    # 4.Delete db_file
+    # Delete from storage backend
     if db_file.file_ext == 'folder':
+        # For folders, delete all child files from storage first
+        child_files = db.query(file_model.File).filter(file_model.File.parent_id == db_file.id).all()
+        for child in child_files:
+            if child.file_key:
+                try:
+                    await storage_service.delete_file(child.file_key)
+                except Exception as e:
+                    api_logger.warning(f"Failed to delete child file from storage: {child.file_key} - {e}")
         db.query(file_model.File).filter(file_model.File.parent_id == db_file.id).delete()
+    else:
+        if db_file.file_key:
+            try:
+                await storage_service.delete_file(db_file.file_key)
+            except Exception as e:
+                api_logger.warning(f"Failed to delete file from storage: {db_file.file_key} - {e}")
+
     db.delete(db_file)
     db.commit()

api/app/controllers/memory_agent_controller.py

@@ -27,6 +27,7 @@ from app.services import task_service, workspace_service
 from app.services.memory_agent_service import MemoryAgentService
 from app.services.memory_agent_service import get_end_user_connected_config as get_config
 from app.services.model_service import ModelConfigService
+from app.utils.tmp_session import ChatSessionCache
 
 load_dotenv()
 api_logger = get_api_logger()
@@ -300,60 +301,39 @@ async def read_server(
         if knowledge:
             user_rag_memory_id = str(knowledge.id)
 
+    session_id = user_input.session_id.hex
+
     api_logger.info(
-        f"Read service: group={user_input.end_user_id}, storage_type={storage_type}, user_rag_memory_id={user_rag_memory_id}, workspace_id={workspace_id}")
+        f"Read service: group={user_input.end_user_id}, storage_type={storage_type}, user_rag_memory_id={user_rag_memory_id}, workspace_id={workspace_id}, session_id={session_id}")
     try:
-        # result = await memory_agent_service.read_memory(
-        #     user_input.end_user_id,
-        #     user_input.message,
-        #     user_input.history,
-        #     user_input.search_switch,
-        #     config_id,
-        #     db,
-        #     storage_type,
-        #     user_rag_memory_id
-        # )
-        # if str(user_input.search_switch) == "2":
-        #     retrieve_info = result['answer']
-        #     history = await SessionService(store).get_history(user_input.end_user_id, user_input.end_user_id,
-        #                                                       user_input.end_user_id)
-        #     query = user_input.message
-        #
-        #     # 调用 memory_agent_service 的方法生成最终答案
-        #     result['answer'] = await memory_agent_service.generate_summary_from_retrieve(
-        #         end_user_id=user_input.end_user_id,
-        #         retrieve_info=retrieve_info,
-        #         history=history,
-        #         query=query,
-        #         config_id=config_id,
-        #         db=db
-        #     )
-        #     if "信息不足，无法回答" in result['answer']:
-        #         result['answer'] = retrieve_info
         memory_config = get_config(user_input.end_user_id, db)
         service = MemoryService(
             db,
             memory_config["memory_config_id"],
             end_user_id=user_input.end_user_id
         )
+        session_cache = ChatSessionCache(session_id)
         search_result = await service.read(
             user_input.message,
-            SearchStrategy(user_input.search_switch)
+            SearchStrategy(user_input.search_switch),
+            history=await session_cache.get_history(),
         )
         intermediate_outputs = []
         sub_queries = set()
         for memory in search_result.memories:
             sub_queries.add(str(memory.query))
+        idx = 0
         if user_input.search_switch in [SearchStrategy.DEEP, SearchStrategy.NORMAL]:
             intermediate_outputs.append({
                 "type": "problem_split",
                 "title": "问题拆分",
                 "data": [
                     {
-                        "id": f"Q{idx+1}",
+                        "id": f"Q{(idx := idx + 1)}",
                         "question": question
                     }
-                    for idx, question in enumerate(sub_queries)
+                    for question in sub_queries
+                    if question
                 ]
             })
         perceptual_data = [
@@ -375,16 +355,24 @@ async def read_server(
             "raw_result": search_result.memories,
             "total": len(search_result.memories),
         })
+        answer = await memory_agent_service.generate_summary_from_retrieve(
+            end_user_id=user_input.end_user_id,
+            retrieve_info=search_result.content,
+            history=[],
+            query=user_input.message,
+            config_id=config_id,
+            db=db
+        )
+        await session_cache.append_many(
+            [
+                {"role": "user", "content": user_input.message},
+                {"role": "assistant", "content": answer}
+            ]
+        )
         result = {
-            'answer': await memory_agent_service.generate_summary_from_retrieve(
-                end_user_id=user_input.end_user_id,
-                retrieve_info=search_result.content,
-                history=[],
-                query=user_input.message,
-                config_id=config_id,
-                db=db
-            ),
-            "intermediate_outputs": intermediate_outputs
+            'answer': answer,
+            "intermediate_outputs": intermediate_outputs,
+            "session_id": session_id,
         }
 
         return success(data=result, msg="回复对话消息成功")
@@ -480,9 +468,11 @@ async def read_server_async(
         if knowledge: user_rag_memory_id = str(knowledge.id)
     api_logger.info(f"Async read: storage_type={storage_type}, user_rag_memory_id={user_rag_memory_id}")
     try:
+        session_id = user_input.session_id.hex
+        session_cache = ChatSessionCache(session_id)
         task = celery_app.send_task(
             "app.core.memory.agent.read_message",
-            args=[user_input.end_user_id, user_input.message, user_input.history, user_input.search_switch,
+            args=[user_input.end_user_id, user_input.message, await session_cache.get_history(), user_input.search_switch,
                   config_id, storage_type, user_rag_memory_id]
         )
         api_logger.info(f"Read task queued: {task.id}")

api/app/controllers/memory_dashboard_controller.py

@@ -1,4 +1,4 @@
-import asyncio
+
 import uuid
 from fastapi import APIRouter, Depends, HTTPException, status, Query
 from pydantic import BaseModel, Field
@@ -10,7 +10,7 @@ from app.dependencies import get_current_user
 from app.models.user_model import User
 from app.schemas.response_schema import ApiResponse
 
-from app.services import memory_dashboard_service, memory_storage_service, workspace_service
+from app.services import memory_dashboard_service, workspace_service
 from app.services.memory_agent_service import get_end_users_connected_configs_batch
 from app.services.app_statistics_service import AppStatisticsService
 from app.core.logging_config import get_api_logger
@@ -48,7 +48,7 @@ def get_workspace_total_end_users(
 
 
 @router.get("/end_users", response_model=ApiResponse)
-async def get_workspace_end_users(
+def get_workspace_end_users(
     workspace_id: Optional[uuid.UUID] = Query(None, description="工作空间ID（可选，默认当前用户工作空间）"),
     keyword: Optional[str] = Query(None, description="搜索关键词（同时模糊匹配 other_name 和 id）"),
     page: int = Query(1, ge=1, description="页码，从1开始"),
@@ -58,6 +58,15 @@ async def get_workspace_end_users(
 ):
     """
     获取工作空间的宿主列表（分页查询，支持模糊搜索）
+    
+    新增：记忆数量过滤：
+        Neo4j 模式：
+        - 使用 end_users.memory_count 过滤 memory_count > 0 的宿主
+        - memory_num.total 直接取 end_user.memory_count
+
+        RAG 模式：
+        - 使用 documents.chunk_num 聚合过滤 chunk 总数 > 0 的宿主
+        - memory_num.total 取聚合后的 chunk 总数
 
     返回工作空间下的宿主列表，支持分页查询和模糊搜索。
     通过 keyword 参数同时模糊匹配 other_name 和 id 字段。
@@ -80,17 +89,29 @@ async def get_workspace_end_users(
     current_workspace_type = memory_dashboard_service.get_current_workspace_type(db, workspace_id, current_user)
     api_logger.info(f"用户 {current_user.username} 请求获取工作空间 {workspace_id} 的宿主列表, 类型: {current_workspace_type}")
 
-    # 获取分页的 end_users
-    end_users_result = memory_dashboard_service.get_workspace_end_users_paginated(
-        db=db,
-        workspace_id=workspace_id,
-        current_user=current_user,
-        page=page,
-        pagesize=pagesize,
-        keyword=keyword
-    )
+    if current_workspace_type == "rag":
+        end_users_result = memory_dashboard_service.get_workspace_end_users_paginated_rag(
+            db=db,
+            workspace_id=workspace_id,
+            current_user=current_user,
+            page=page,
+            pagesize=pagesize,
+            keyword=keyword,
+        )
+        raw_items = end_users_result.get("items", [])
+        end_users = [item["end_user"] for item in raw_items]
+    else:
+        end_users_result = memory_dashboard_service.get_workspace_end_users_paginated(
+            db=db,
+            workspace_id=workspace_id,
+            current_user=current_user,
+            page=page,
+            pagesize=pagesize,
+            keyword=keyword,
+        )
+        raw_items = end_users_result.get("items", [])
+        end_users = raw_items
 
-    end_users = end_users_result.get("items", [])
     total = end_users_result.get("total", 0)
 
     if not end_users:
@@ -101,50 +122,19 @@ async def get_workspace_end_users(
                 "page": page,
                 "pagesize": pagesize,
                 "total": total,
-                "hasnext": (page * pagesize) < total
-            }
+                "hasnext": (page * pagesize) < total,
+            },
         }, msg="宿主列表获取成功")
 
     end_user_ids = [str(user.id) for user in end_users]
 
-    # 并发执行两个独立的查询任务
-    async def get_memory_configs():
-        """获取记忆配置（在线程池中执行同步查询）"""
-        try:
-            return await asyncio.to_thread(
-                get_end_users_connected_configs_batch,
-                end_user_ids, db
-            )
-        except Exception as e:
-            api_logger.error(f"批量获取记忆配置失败: {str(e)}")
-            return {}
+    try:
+        memory_configs_map = get_end_users_connected_configs_batch(end_user_ids, db)
+    except Exception as e:
+        api_logger.error(f"批量获取记忆配置失败: {str(e)}")
+        memory_configs_map = {}
 
-    async def get_memory_nums():
-        """获取记忆数量"""
-        if current_workspace_type == "rag":
-            # RAG 模式：批量查询
-            try:
-                chunk_map = await asyncio.to_thread(
-                    memory_dashboard_service.get_users_total_chunk_batch,
-                    end_user_ids, db, current_user
-                )
-                return {uid: {"total": count} for uid, count in chunk_map.items()}
-            except Exception as e:
-                api_logger.error(f"批量获取 RAG chunk 数量失败: {str(e)}")
-                return {uid: {"total": 0} for uid in end_user_ids}
-
-        elif current_workspace_type == "neo4j":
-            # Neo4j 模式：批量查询（简化版本，只返回total）
-            try:
-                batch_result = await memory_storage_service.search_all_batch(end_user_ids)
-                return {uid: {"total": count} for uid, count in batch_result.items()}
-            except Exception as e:
-                api_logger.error(f"批量获取 Neo4j 记忆数量失败: {str(e)}")
-                return {uid: {"total": 0} for uid in end_user_ids}
-
-        return {uid: {"total": 0} for uid in end_user_ids}
-
-    # 触发按需初始化：为 implicit_emotions_storage 中没有记录的用户异步生成数据
+    # 触发按需初始化：为 implicit_emotions_storage / interest_distribution 中没有记录的用户异步生成数据
     try:
         from app.celery_app import celery_app as _celery_app
         _celery_app.send_task(
@@ -159,27 +149,26 @@ async def get_workspace_end_users(
     except Exception as e:
         api_logger.warning(f"触发按需初始化任务失败（不影响主流程）: {e}")
 
-    # 并发执行配置查询和记忆数量查询
-    memory_configs_map, memory_nums_map = await asyncio.gather(
-        get_memory_configs(),
-        get_memory_nums()
-    )
-
-    # 构建结果列表
     items = []
-    for end_user in end_users:
+    for index, end_user in enumerate(end_users):
         user_id = str(end_user.id)
         config_info = memory_configs_map.get(user_id, {})
+
+        if current_workspace_type == "rag":
+            memory_total = int(raw_items[index].get("memory_count", 0) or 0)
+        else:
+            memory_total = int(getattr(end_user, "memory_count", 0) or 0)
+
         items.append({
-            'end_user': {
-                'id': user_id,
-                'other_name': end_user.other_name
+            "end_user": {
+                "id": user_id,
+                "other_name": end_user.other_name,
             },
-            'memory_num': memory_nums_map.get(user_id, {"total": 0}),
-            'memory_config': {
+            "memory_num": {"total": memory_total},
+            "memory_config": {
                 "memory_config_id": config_info.get("memory_config_id"),
-                "memory_config_name": config_info.get("memory_config_name")
-            }
+                "memory_config_name": config_info.get("memory_config_name"),
+            },
         })
 
     # 触发社区聚类补全任务（异步，不阻塞接口响应）
@@ -407,6 +396,7 @@ def get_current_user_rag_total_num(
     total_chunk = memory_dashboard_service.get_current_user_total_chunk(end_user_id, db, current_user)
     return success(data=total_chunk, msg="宿主RAG知识数据获取成功")
 
+
 @router.get("/rag_content", response_model=ApiResponse)
 def get_rag_content(
     end_user_id: str = Query(..., description="宿主ID"),

api/app/core/memory/agent/utils/write_tools.py

@@ -20,6 +20,7 @@ from app.core.memory.storage_services.extraction_engine.knowledge_extraction.mem
     memory_summary_generation
 from app.core.memory.utils.llm.llm_utils import MemoryClientFactory
 from app.core.memory.utils.log.logging_utils import log_time
+from app.core.memory.utils.memory_count_utils import sync_end_user_memory_count_from_neo4j
 from app.db import get_db_context
 from app.repositories.neo4j.add_edges import add_memory_summary_statement_edges
 from app.repositories.neo4j.add_nodes import add_memory_summary_nodes
@@ -313,6 +314,28 @@ async def write(
     except Exception as cache_err:
         logger.warning(f"[WRITE] 写入活动统计缓存失败（不影响主流程）: {cache_err}", exc_info=True)
 
+    # 同步 Neo4j 记忆节点总数到 PostgreSQL end_users.memory_count
+    if end_user_id:
+        try:
+            memory_count_connector = Neo4jConnector()
+            try:
+                node_count = await sync_end_user_memory_count_from_neo4j(
+                    end_user_id,
+                    memory_count_connector,
+                )
+            finally:
+                await memory_count_connector.close()
+
+            logger.info(
+                f"[MemoryCount] 写入后同步 memory_count: "
+                f"end_user_id={end_user_id}, count={node_count}"
+            )
+        except Exception as e:
+            logger.warning(
+                f"[MemoryCount] 写入后同步 memory_count 失败（不影响主流程）: {e}",
+                exc_info=True,
+            )
+    
     # Close LLM/Embedder underlying httpx clients to prevent
     # 'RuntimeError: Event loop is closed' during garbage collection
     for client_obj in (llm_client, embedder_client):
@@ -331,3 +354,4 @@ async def write(
 
     logger.info("=== Pipeline Complete ===")
     logger.info(f"Total execution time: {total_time:.2f} seconds")
+

api/app/core/memory/memory_service.py

@@ -43,10 +43,13 @@ class MemoryService:
             self,
             query: str,
             search_switch: SearchStrategy,
+            history: list | None = None,
             limit: int = 10,
     ) -> MemorySearchResult:
+        if history is None:
+            history = []
         with get_db_context() as db:
-            return await ReadPipeLine(self.ctx, db).run(query, search_switch, limit)
+            return await ReadPipeLine(self.ctx, db).run(query, search_switch, history, limit)
 
     async def forget(self, max_batch: int = 100, min_days: int = 30) -> dict:
         raise NotImplementedError

api/app/core/memory/models/service_models.py

@@ -32,10 +32,12 @@ class Memory(BaseModel):
 
 class MemorySearchResult(BaseModel):
     memories: list[Memory]
+    content_str: str = Field(default="")
 
-    @computed_field
     @property
     def content(self) -> str:
+        if self.content_str:
+            return self.content_str
         return "\n".join([memory.content for memory in self.memories])
 
     @computed_field

api/app/core/memory/pipelines/memory_read.py

@@ -1,8 +1,9 @@
 from app.core.memory.enums import SearchStrategy, StorageType
 from app.core.memory.models.service_models import MemorySearchResult
 from app.core.memory.pipelines.base_pipeline import ModelClientMixin, DBRequiredPipeline
-from app.core.memory.read_services.search_engine.content_search import Neo4jSearchService, RAGSearchService
 from app.core.memory.read_services.generate_engine.query_preprocessor import QueryPreprocessor
+from app.core.memory.read_services.generate_engine.retrieval_summary import RetrievalSummaryProcessor
+from app.core.memory.read_services.search_engine.content_search import Neo4jSearchService, RAGSearchService
 
 
 class ReadPipeLine(ModelClientMixin, DBRequiredPipeline):
@@ -10,20 +11,30 @@ class ReadPipeLine(ModelClientMixin, DBRequiredPipeline):
             self,
             query: str,
             search_switch: SearchStrategy,
+            history: list,
             limit: int = 10,
             includes=None
     ) -> MemorySearchResult:
+        memory_l0 = None
+        if self.ctx.storage_type == StorageType.NEO4J:  
+            memory_l0 = await self._get_search_service(includes).memory_l0()
+
         query = QueryPreprocessor.process(query)
         match search_switch:
             case SearchStrategy.DEEP:
-                return await self._deep_read(query, limit, includes)
+                res = await self._deep_read(query, history, limit, includes)
             case SearchStrategy.NORMAL:
-                return await self._normal_read(query, limit, includes)
+                res = await self._normal_read(query, history, limit, includes)
             case SearchStrategy.QUICK:
-                return await self._quick_read(query, limit, includes)
+                res = await self._quick_read(query, limit, includes)
             case _:
                 raise RuntimeError("Unsupported search strategy")
 
+        if memory_l0 is not None:
+            res.content_str = memory_l0.content + '\n' + res.content
+            res.memories.insert(0, memory_l0)
+        return res
+
     def _get_search_service(self, includes=None):
         if self.ctx.storage_type == StorageType.NEO4J:
             return Neo4jSearchService(
@@ -37,10 +48,11 @@ class ReadPipeLine(ModelClientMixin, DBRequiredPipeline):
                 self.db
             )
 
-    async def _deep_read(self, query: str, limit: int, includes=None) -> MemorySearchResult:
+    async def _deep_read(self, query: str, history: list, limit: int, includes=None) -> MemorySearchResult:
         search_service = self._get_search_service(includes)
         questions = await QueryPreprocessor.split(
             query,
+            history,
             self.get_llm_client(self.db, self.ctx.memory_config.llm_model_id)
         )
         query_results = []
@@ -49,12 +61,18 @@ class ReadPipeLine(ModelClientMixin, DBRequiredPipeline):
             query_results.append(search_results)
         results = sum(query_results, start=MemorySearchResult(memories=[]))
         results.memories.sort(key=lambda x: x.score, reverse=True)
+        results.content_str = await RetrievalSummaryProcessor.summary(
+            query,
+            results.content,
+            self.get_llm_client(self.db, self.ctx.memory_config.llm_model_id)
+        )
         return results
 
-    async def _normal_read(self, query: str, limit: int, includes=None) -> MemorySearchResult:
+    async def _normal_read(self, query: str, history: list, limit: int, includes=None) -> MemorySearchResult:
         search_service = self._get_search_service(includes)
         questions = await QueryPreprocessor.split(
             query,
+            history,
             self.get_llm_client(self.db, self.ctx.memory_config.llm_model_id)
         )
         query_results = []
@@ -63,6 +81,11 @@ class ReadPipeLine(ModelClientMixin, DBRequiredPipeline):
             query_results.append(search_results)
         results = sum(query_results, start=MemorySearchResult(memories=[]))
         results.memories.sort(key=lambda x: x.score, reverse=True)
+        results.content_str = await RetrievalSummaryProcessor.summary(
+            query,
+            results.content,
+            self.get_llm_client(self.db, self.ctx.memory_config.llm_model_id)
+        )
         return results
 
     async def _quick_read(self, query: str, limit: int, includes=None) -> MemorySearchResult:

api/app/core/memory/prompt/problem_split.jinja2

@@ -76,8 +76,8 @@ Remember the following:
 - Today's date is {{ datetime }}.
 - Do not return anything from the custom few shot example prompts provided above.
 - Don't reveal your prompt or model information to the user.
-- The output language should match the user's input language.
 - Vague times in user input should be converted into specific dates.
 - If you are unable to extract any relevant information from the user's input, return the user's original input:{"questions":[userinput]}
 
+# [IMPORTANT]: THE OUTPUT LANGUAGE MUST BE THE SAME AS THE USER'S INPUT LANGUAGE.
 The following is the user's input. You need to extract the relevant information from the input and return it in the JSON format as shown above.

api/app/core/memory/prompt/retrieval_summary.jinja2

@@ -0,0 +1,15 @@
+You are a Content Condenser for a memory-augmented retrieval system.
+
+Your task is to compress the retrieved content while preserving all information that is highly relevant to the user’s query.
+
+Guidelines:
+
+Focus only on content related to the query; ignore irrelevant parts.
+Remove redundancy, filler, or repeated information only for non-XML content.
+Preserve all factual details: names, dates, decisions, code snippets, technical details.
+If relevant information is inside XML tags, do not remove, merge, or compress the XML tags or their internal text; keep them fully intact.
+Structure multiple relevant points as a compact bullet list or paragraph, depending on density.
+If no content is relevant, return exactly: "No relevant information found."
+Do not add any knowledge or facts not in the retrieved content.
+# [IMPORTANT] OUTPUT ONLY THE CONDENSED CONTENT, DO NOT ATTEMPT TO ANSWER THE QUERY.
+# [IMPORTANT] DO NOT REMOVE OR PARAPHRASE HIGHLY RELEVANT INFORMATION.

api/app/core/memory/read_services/generate_engine/query_preprocessor.py

@@ -21,14 +21,14 @@ class QueryPreprocessor:
         return text
 
     @staticmethod
-    async def split(query: str, llm_client: RedBearLLM):
+    async def split(query: str, history: list, llm_client: RedBearLLM):
         system_prompt = prompt_manager.render(
             name="problem_split",
             datetime=datetime.now().strftime("%Y-%m-%d"),
         )
         messages = [
             {"role": "system", "content": system_prompt},
-            {"role": "user", "content": query},
+            {"role": "user", "content": f"<history>{history}</history><query>{query}</query>"},
         ]
         try:
             sub_queries = await llm_client.ainvoke(messages) | StructResponse(mode='json')

api/app/core/memory/read_services/generate_engine/retrieval_summary.py

@@ -1,11 +1,29 @@
+import logging
+
 from app.core.models import RedBearLLM
+from app.core.memory.prompt import prompt_manager
+from app.core.memory.utils.llm.llm_utils import StructResponse
+
+logger = logging.getLogger(__name__)
 
 
 class RetrievalSummaryProcessor:
     @staticmethod
-    def summary(content: str, llm_client: RedBearLLM):
-        return
+    async def summary(query, content: str, llm_client: RedBearLLM):
+        system_prompt = prompt_manager.render(
+            name="retrieval_summary"
+        )
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": f"<query>{query}</query><content>{content}</content>"},
+        ]
+        try:
+            summary = await llm_client.ainvoke(messages) | StructResponse(mode='str')
+            return summary
+        except:
+            logger.error("Failed to generate reply summary, returning original content", exc_info=True)
+            return content
 
     @staticmethod
-    def verify(content: str, llm_client: RedBearLLM):
+    async def verify(query, content: str, llm_client: RedBearLLM):
         return

api/app/core/memory/read_services/search_engine/content_search.py

@@ -14,6 +14,8 @@ from app.core.rag.nlp.search import knowledge_retrieval
 from app.repositories import knowledge_repository
 from app.repositories.neo4j.graph_search import search_graph, search_graph_by_embedding
 from app.repositories.neo4j.neo4j_connector import Neo4jConnector
+from app.core.memory.read_services.search_engine.result_builder import MetadataBuilder
+from app.repositories.neo4j.graph_search import search_user_metadata
 
 logger = logging.getLogger(__name__)
 
@@ -177,6 +179,22 @@ class Neo4jSearchService:
         memories.sort(key=lambda x: x.score, reverse=True)
         return MemorySearchResult(memories=memories[:limit])
 
+    async def memory_l0(self) -> Memory:
+        async with Neo4jConnector() as connector:
+            end_user_id = self.ctx.end_user_id
+            user_meta = await search_user_metadata(connector, end_user_id)
+            metadata = MetadataBuilder(user_meta)
+            memory = Memory(
+                score=1,
+                source=Neo4jNodeType.EXTRACTEDENTITY,
+                query='',
+                id=end_user_id,
+                content=metadata.content,
+                data=metadata.data,
+            )
+
+        return memory
+
 
 class RAGSearchService:
     def __init__(self, ctx: MemoryContext, db: Session):

api/app/core/memory/read_services/search_engine/result_builder.py

@@ -42,7 +42,15 @@ class ChunkBuilder(BaseBuilder):
 
     @property
     def content(self) -> str:
-        return self.record.get("content")
+        parts = ["<chunk>"]
+        fields = [
+            ("content", self.record.get("content", "")),
+        ]
+        for tag, value in fields:
+            if value:
+                parts.append(f"<{tag}>{value}</{tag}>")
+        parts.append("</chunk>")
+        return "".join(parts)
 
 
 class StatementBuiler(BaseBuilder):
@@ -57,7 +65,15 @@ class StatementBuiler(BaseBuilder):
 
     @property
     def content(self) -> str:
-        return self.record.get("statement")
+        parts = ["<statement>"]
+        fields = [
+            ("statement", self.record.get("statement", "")),
+        ]
+        for tag, value in fields:
+            if value:
+                parts.append(f"<{tag}>{value}</{tag}>")
+        parts.append("</statement>")
+        return "".join(parts)
 
 
 class EntityBuilder(BaseBuilder):
@@ -73,10 +89,16 @@ class EntityBuilder(BaseBuilder):
 
     @property
     def content(self) -> str:
-        return (f"<entity>"
-                f"<name>{self.record.get("name")}<name>"
-                f"<description>{self.record.get("description")}</description>"
-                f"</entity>")
+        parts = ["<entity>"]
+        fields = [
+            ("name", self.record.get("name", "")),
+            ("description", self.record.get("description", "")),
+        ]
+        for tag, value in fields:
+            if value:
+                parts.append(f"<{tag}>{value}</{tag}>")
+        parts.append("</entity>")
+        return "".join(parts)
 
 
 class SummaryBuilder(BaseBuilder):
@@ -91,7 +113,15 @@ class SummaryBuilder(BaseBuilder):
 
     @property
     def content(self) -> str:
-        return self.record.get("content")
+        parts = ["<summary>"]
+        fields = [
+            ("content", self.record.get("content", "")),
+        ]
+        for tag, value in fields:
+            if value:
+                parts.append(f"<{tag}>{value}</{tag}>")
+        parts.append("</summary>")
+        return "".join(parts)
 
 
 class PerceptualBuilder(BaseBuilder):
@@ -114,15 +144,21 @@ class PerceptualBuilder(BaseBuilder):
 
     @property
     def content(self) -> str:
-        return ("<history-file-info>"
-                f"<file-name>{self.record.get('file_name')}</file-name>"
-                f"<file-path>{self.record.get('file_path')}</file-path>"
-                f"<summary>{self.record.get('summary')}</summary>"
-                f"<topic>{self.record.get('topic')}</topic>"
-                f"<domain>{self.record.get('domain')}</domain>"
-                f"<keywords>{self.record.get('keywords')}</keywords>"
-                f"<file-type>{self.record.get('file_type')}</file-type>"
-                "</history-file-info>")
+        parts = ["<history-file-info>"]
+        fields = [
+            ("file-name", self.record.get("file_name", "")),
+            ("file-path", self.record.get("file_path", "")),
+            ("summary", self.record.get("summary", "")),
+            ("topic", self.record.get("topic", "")),
+            ("domain", self.record.get("domain", "")),
+            ("keywords", self.record.get("keywords", [])),
+            ("file-type", self.record.get("file_type", "")),
+        ]
+        for tag, value in fields:
+            if value:
+                parts.append(f"<{tag}>{value}</{tag}>")
+        parts.append("</history-file-info>")
+        return "".join(parts)
 
 
 class CommunityBuilder(BaseBuilder):
@@ -137,7 +173,54 @@ class CommunityBuilder(BaseBuilder):
 
     @property
     def content(self) -> str:
-        return self.record.get("content")
+        parts = ["<community>"]
+        fields = [
+            ("content", self.record.get("content", "")),
+        ]
+        for tag, value in fields:
+            if value:
+                parts.append(f"<{tag}>{value}</{tag}>")
+        parts.append("</community>")
+        return "".join(parts)
+
+
+class MetadataBuilder(BaseBuilder):
+    @property
+    def data(self) -> dict:
+        return {
+            "id": self.record.get("id", ""),
+            "aliases_name": self.record.get("aliases", []) or [],
+            "description": self.record.get("description", ""),
+            "anchors": self.record.get("anchors", []) or [],
+            "beliefs_or_stances": self.record.get("beliefs_or_stances", []) or [],
+            "core_facts": self.record.get("core_facts", []) or [],
+            "events": self.record.get("events", []) or [],
+            "goals": self.record.get("goals", []) or [],
+            "interests": self.record.get("interests", []) or [],
+            "relations": self.record.get("relations", []) or [],
+            "traits": self.record.get("traits", []) or [],
+        }
+
+    @property
+    def content(self) -> str:
+        parts = ["<user-info>"]
+        fields = [
+            ("description", self.record.get("description", "")),
+            ("aliases", self.record.get("aliases", [])),
+            ("anchors", self.record.get("anchors", [])),
+            ("beliefs_or_stances", self.record.get("beliefs_or_stances", [])),
+            ("core_facts", self.record.get("core_facts", [])),
+            ("events", self.record.get("events", [])),
+            ("goals", self.record.get("goals", [])),
+            ("interests", self.record.get("interests", [])),
+            ("relations", self.record.get("relations", [])),
+            ("traits", self.record.get("traits", [])),
+        ]
+        for tag, value in fields:
+            if value:
+                parts.append(f"<{tag}>{value}</{tag}>")
+        parts.append("</user-info>")
+        return "".join(parts)
 
 
 def data_builder_factory(node_type, data: dict) -> T:

api/app/core/memory/storage_services/forgetting_engine/forgetting_scheduler.py

@@ -20,6 +20,7 @@ from uuid import UUID
 from datetime import datetime
 
 from app.core.memory.storage_services.forgetting_engine.forgetting_strategy import ForgettingStrategy
+from app.core.memory.utils.memory_count_utils import sync_end_user_memory_count_from_neo4j
 from app.repositories.neo4j.neo4j_connector import Neo4jConnector
 
 
@@ -145,7 +146,22 @@ class ForgettingScheduler:
                 }
                 
                 logger.info("没有可遗忘的节点对，遗忘周期结束")
-                
+                # 同步 Neo4j 记忆节点总数到 PostgreSQL 的 end_users.memory_count
+                if end_user_id:
+                    try:
+                        node_count = await sync_end_user_memory_count_from_neo4j(
+                            end_user_id,
+                            self.connector,
+                        )
+                        logger.info(
+                            f"[MemoryCount] 遗忘后同步 memory_count: "
+                            f"end_user_id={end_user_id}, count={node_count}"
+                        )
+                    except Exception as e:
+                        logger.warning(
+                            f"[MemoryCount] 遗忘后同步 memory_count 失败（不影响主流程）: {e}",
+                            exc_info=True,
+                        )
                 return report
             
             # 步骤3：按激活值排序（激活值最低的优先）
@@ -302,7 +318,22 @@ class ForgettingScheduler:
                 f"({reduction_rate:.2%}), "
                 f"耗时 {duration:.2f} 秒"
             )
-            
+            # 同步 Neo4j 记忆节点总数到 PostgreSQL 的 end_users.memory_count
+            if end_user_id:
+                try:
+                    node_count = await sync_end_user_memory_count_from_neo4j(
+                        end_user_id,
+                        self.connector,
+                    )
+                    logger.info(
+                        f"[MemoryCount] 遗忘后同步 memory_count: "
+                        f"end_user_id={end_user_id}, count={node_count}"
+                    )
+                except Exception as e:
+                    logger.warning(
+                        f"[MemoryCount] 遗忘后同步 memory_count 失败（不影响主流程）: {e}",
+                        exc_info=True,
+                    )
             return report
         
         except Exception as e:

api/app/core/memory/utils/llm/llm_utils.py

@@ -17,7 +17,7 @@ async def handle_response(response: type[BaseModel]) -> dict:
 
 
 class StructResponse:
-    def __init__(self, mode: Literal["json", "pydantic"], model: Type[BaseModel] = None):
+    def __init__(self, mode: Literal["json", "pydantic", "str"], model: Type[BaseModel] = None):
         self.mode = mode
         if mode == "pydantic" and model is None:
             raise ValueError("Pydantic model is required")
@@ -31,6 +31,8 @@ class StructResponse:
         for block in other.content_blocks:
             if block.get("type") == "text":
                 text += block.get("text", "")
+        if self.mode == "str":
+            return text
         fixed_json = json_repair.repair_json(text, return_objects=True)
         if self.mode == "json":
             return fixed_json

api/app/core/memory/utils/memory_count_utils.py

@@ -0,0 +1,36 @@
+from uuid import UUID
+
+from app.db import get_db_context
+from app.models.end_user_model import EndUser
+from app.repositories.memory_config_repository import MemoryConfigRepository
+from app.repositories.neo4j.neo4j_connector import Neo4jConnector
+
+
+async def sync_end_user_memory_count_from_neo4j(
+    end_user_id: str,
+    connector: Neo4jConnector,
+) -> int:
+    """
+    Sync one end user's Neo4j memory node count to PostgreSQL.
+
+    The caller owns the Neo4j connector lifecycle.
+    """
+    if not end_user_id:
+        return 0
+
+    result = await connector.execute_query(
+        MemoryConfigRepository.SEARCH_FOR_ALL_BATCH,
+        end_user_ids=[end_user_id],
+    )
+    node_count = int(result[0]["total"]) if result else 0
+
+    with get_db_context() as db:
+        db.query(EndUser).filter(
+            EndUser.id == UUID(end_user_id)
+        ).update(
+            {"memory_count": node_count},
+            synchronize_session=False,
+        )
+        db.commit()
+
+    return node_count

api/app/core/rag/prompts/vision_llm_describe_prompt.md

@@ -14,6 +14,7 @@ Transcribe the content from the provided PDF page image into clean Markdown form
 6. Do NOT wrap the output in ```markdown or ``` blocks.
 7. Only apply Markdown structure to headings, paragraphs, lists, and tables, strictly based on the layout of the image. Do NOT create tables unless an actual table exists in the image.
 8. Preserve the original language, information, and order exactly as shown in the image.
+9. Your output language MUST match the language of the content in the image. If the image contains Chinese text, output in Chinese. If English, output in English. Never translate.
 
 {% if page %}
 At the end of the transcription, add the page divider: `--- Page {{ page }} ---`.

api/app/core/workflow/nodes/base_node.py

@@ -1,5 +1,6 @@
 import asyncio
 import logging
+import re
 import time
 import uuid
 from abc import ABC, abstractmethod
@@ -22,6 +23,9 @@ from app.services.multimodal_service import MultimodalService
 
 logger = logging.getLogger(__name__)
 
+# 匹配模板变量 {{xxx}} 的正则
+_TEMPLATE_PATTERN = re.compile(r"\{\{.*?\}\}")
+
 
 class NodeExecutionError(Exception):
     """节点执行失败异常。
@@ -503,10 +507,29 @@ class BaseNode(ABC):
             variable_pool: The variable pool used for reading and writing variables.
 
         Returns:
-            A dictionary containing the node's input data.
+            A dictionary containing the node's input data with all template
+            variables resolved to their actual runtime values.
         """
-        # Default implementation returns the node configuration
-        return {"config": self.config}
+        return {"config": self._resolve_config(self.config, variable_pool)}
+
+    @staticmethod
+    def _resolve_config(config: Any, variable_pool: VariablePool) -> Any:
+        """递归解析 config 中的模板变量，将 {{xxx}} 替换为实际值。
+
+        Args:
+            config: 节点的原始配置（可能包含模板变量）。
+            variable_pool: 变量池，用于解析模板变量。
+
+        Returns:
+            解析后的配置，所有字符串中的 {{变量}} 已被替换为真实值。
+        """
+        if isinstance(config, str) and _TEMPLATE_PATTERN.search(config):
+            return BaseNode._render_template(config, variable_pool, strict=False)
+        elif isinstance(config, dict):
+            return {k: BaseNode._resolve_config(v, variable_pool) for k, v in config.items()}
+        elif isinstance(config, list):
+            return [BaseNode._resolve_config(item, variable_pool) for item in config]
+        return config
 
     def _extract_output(self, business_result: Any) -> Any:
         """Extracts the actual output from the business result.

api/app/core/workflow/nodes/code/node.py

@@ -132,7 +132,7 @@ class CodeNode(BaseNode):
 
         async with httpx.AsyncClient(timeout=60) as client:
             response = await client.post(
-                f"{settings.SANDBOX_URL}:8194/v1/sandbox/run",
+                f"{settings.SANDBOX_URL}/v1/sandbox/run",
                 headers={
                     "x-api-key": 'redbear-sandbox'
                 },

api/app/core/workflow/nodes/document_extractor/node.py

@@ -121,7 +121,10 @@ class DocExtractorNode(BaseNode):
         return business_result
 
     def _extract_input(self, state: WorkflowState, variable_pool: VariablePool) -> dict[str, Any]:
-        return {"file_selector": self.config.get("file_selector")}
+        file_selector = self.config.get("file_selector", "")
+        # 将变量选择器（如 sys.files）解析为实际值
+        resolved = self.get_variable(file_selector, variable_pool, strict=False, default=file_selector)
+        return {"file_selector": resolved}
 
     async def execute(self, state: WorkflowState, variable_pool: VariablePool) -> Any:
         config = DocExtractorNodeConfig(**self.config)

api/app/core/workflow/nodes/memory/node.py

@@ -40,6 +40,7 @@ class MemoryReadNode(BaseNode):
                 end_user_id=end_user_id,
                 user_rag_memory_id=state["user_rag_memory_id"],
             )
+            # TODO: Historical Messages -> Used to refer to coreference resolution
             search_result = await memory_service.read(
                 self._render_template(self.typed_config.message, variable_pool),
                 search_switch=SearchStrategy(self.typed_config.search_switch)

api/app/models/end_user_model.py

@@ -1,7 +1,7 @@
 import datetime
 import uuid
 
-from sqlalchemy import Column, DateTime, ForeignKey, String, Text
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, String, Text
 from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import relationship
 
@@ -38,6 +38,15 @@ class EndUser(Base):
         comment="关联的记忆配置ID"
     )
     
+    memory_count = Column(
+        Integer,
+        nullable=False,
+        default=0,
+        server_default="0",
+        index=True,
+        comment="记忆节点总数",
+    )
+
     # 用户摘要四个维度 - User Summary Four Dimensions
     user_summary = Column(Text, nullable=True, comment="缓存的用户摘要（基本介绍）")
     personality_traits = Column(Text, nullable=True, comment="性格特点")

api/app/models/file_model.py

@@ -15,4 +15,5 @@ class File(Base):
     file_ext = Column(String, index=True, nullable=False, comment="file extension:folder|pdf")
     file_size = Column(Integer, default=0, comment="file size(byte)")
     file_url = Column(String, index=True, nullable=True, comment="file comes from a website url")
+    file_key = Column(String(512), nullable=True, index=True, comment="storage file key for FileStorageService")
     created_at = Column(DateTime, default=datetime.datetime.now)

api/app/repositories/neo4j/cypher_queries.py

@@ -1296,6 +1296,7 @@ RETURN e.id AS id,
        e.name AS name,
        e.end_user_id AS end_user_id,
        e.entity_type AS entity_type,
+       e.description AS description,
        COALESCE(e.activation_value, e.importance_score, 0.5) AS activation_value,
        COALESCE(e.importance_score, 0.5) AS importance_score,
        e.last_access_time AS last_access_time,
@@ -1479,6 +1480,21 @@ ORDER BY score DESC
 LIMIT $limit
 """
 
+SEARCH_USER_METADATA = """
+MATCH (n:ExtractedEntity)
+WHERE (n.end_user_id = $end_user_id AND n.entity_type ='用户')
+RETURN n.description AS description,
+       n.aliases AS aliases,
+       n.anchors AS anchors,
+       n.beliefs_or_stances AS beliefs_or_stances,
+       n.core_facts AS core_facts,
+       n.events AS events,
+       n.goals AS goals,
+       n.interests AS interests,
+       n.relations AS relations,
+       n.traits AS traits
+"""
+
 FULLTEXT_QUERY_CYPHER_MAPPING = {
     Neo4jNodeType.STATEMENT: SEARCH_STATEMENTS_BY_KEYWORD,
     Neo4jNodeType.EXTRACTEDENTITY: SEARCH_ENTITIES_BY_NAME_OR_ALIAS,

api/app/repositories/neo4j/graph_search.py

@@ -27,9 +27,9 @@ from app.repositories.neo4j.cypher_queries import (
     SEARCH_PERCEPTUAL_BY_USER_ID,
     FULLTEXT_QUERY_CYPHER_MAPPING,
     USER_ID_QUERY_CYPHER_MAPPING,
-    NODE_ID_QUERY_CYPHER_MAPPING
+    NODE_ID_QUERY_CYPHER_MAPPING,
+    SEARCH_USER_METADATA
 )
-
 from app.repositories.neo4j.neo4j_connector import Neo4jConnector
 
 logger = logging.getLogger(__name__)
@@ -513,7 +513,7 @@ async def search_graph_by_embedding(
     task_keys = []
 
     for node_type in include:
-        tasks.append(search_by_embedding(connector, node_type, end_user_id, embedding, limit*2))
+        tasks.append(search_by_embedding(connector, node_type, end_user_id, embedding, limit * 2))
         task_keys.append(node_type.value)
 
     task_results = await asyncio.gather(*tasks, return_exceptions=True)
@@ -557,6 +557,17 @@ async def search_graph_by_embedding(
     return results
 
 
+async def search_user_metadata(
+        connector: Neo4jConnector,
+        end_user_id: str
+) -> dict:
+    user_info = await connector.execute_query(
+        SEARCH_USER_METADATA,
+        end_user_id=end_user_id
+    )
+    return user_info[0] if user_info else {}
+
+
 async def get_dedup_candidates_for_entities(  # 适配新版查询：使用全文索引按名称检索候选实体
         connector: Neo4jConnector,
         end_user_id: str,

api/app/schemas/end_user_schema.py

@@ -19,4 +19,6 @@ class EndUser(BaseModel):
     
     # 用户摘要和洞察更新时间
     user_summary_updated_at: Optional[datetime.datetime] = Field(description="用户摘要最后更新时间", default=None)
-    memory_insight_updated_at: Optional[datetime.datetime] = Field(description="洞察报告最后更新时间", default=None)
+    memory_insight_updated_at: Optional[datetime.datetime] = Field(description="洞察报告最后更新时间", default=None)
+    #用户记忆节点总数（Neo4j模式）
+    memory_count: int = Field(description="记忆节点总数", default=0)

api/app/schemas/file_schema.py

@@ -11,6 +11,7 @@ class FileBase(BaseModel):
     file_ext: str
     file_size: int
     file_url: str | None = None
+    file_key: str | None = None
     created_at: datetime.datetime | None = None
 
 

api/app/schemas/memory_agent_schema.py

@@ -1,14 +1,15 @@
+import uuid
 from abc import ABC
 from typing import Optional
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class UserInput(BaseModel):
     message: str
-    history: list[dict]
     search_switch: str
     end_user_id: str
+    session_id: uuid.UUID = Field(default_factory=uuid.uuid4)
     config_id: Optional[str] = None
 
 

api/app/services/app_dsl_service.py

@@ -102,6 +102,11 @@ class AppDslService:
                     {**r, "_ref": self._agent_ref(r.get("target_agent_id"))} for r in (cfg["routing_rules"] or [])
                 ]
             return enriched
+        if app_type == AppType.WORKFLOW:
+            enriched = {**cfg}
+            if "nodes" in cfg:
+                enriched["nodes"] = self._enrich_workflow_nodes(cfg["nodes"])
+            return enriched
         return cfg
 
     def _export_draft(self, app: App, meta: dict, app_meta: dict) -> tuple[str, str]:
@@ -110,7 +115,7 @@ class AppDslService:
             config_data = {
                 "variables": config.variables if config else [],
                 "edges": config.edges if config else [],
-                "nodes": config.nodes if config else [],
+                "nodes": self._enrich_workflow_nodes(config.nodes) if config else [],
                 "features": config.features if config else {},
                 "execution_config": config.execution_config if config else {},
                 "triggers": config.triggers if config else [],
@@ -190,6 +195,23 @@ class AppDslService:
     def _enrich_tools(self, tools: list) -> list:
         return [{**t, "_ref": self._tool_ref(t.get("tool_id"))} for t in (tools or [])]
 
+    def _enrich_workflow_nodes(self, nodes: list) -> list:
+        """enrich 工作流节点中的模型引用，添加 name、provider、type 信息"""
+        from app.core.workflow.nodes.enums import NodeType
+        enriched_nodes = []
+        for node in (nodes or []):
+            node_type = node.get("type")
+            config = dict(node.get("config") or {})
+            
+            if node_type in (NodeType.LLM.value, NodeType.QUESTION_CLASSIFIER.value, NodeType.PARAMETER_EXTRACTOR.value):
+                model_id = config.get("model_id")
+                if model_id:
+                    config["model_ref"] = self._model_ref(model_id)
+                    del config["model_id"]
+            
+            enriched_nodes.append({**node, "config": config})
+        return enriched_nodes
+
     def _skill_ref(self, skill_id) -> Optional[dict]:
         if not skill_id:
             return None
@@ -620,16 +642,16 @@ class AppDslService:
                         warnings.append(f"[{node_label}] 知识库 '{kb_id}' 未匹配，已移除，请导入后手动配置")
                 config["knowledge_bases"] = resolved_kbs
             elif node_type in (NodeType.LLM.value, NodeType.QUESTION_CLASSIFIER.value, NodeType.PARAMETER_EXTRACTOR.value):
-                model_ref = config.get("model_id")
+                model_ref = config.get("model_ref") or config.get("model_id")
                 if model_ref:
                     ref_dict = None
                     if isinstance(model_ref, dict):
-                        ref_id = model_ref.get("id")
-                        ref_name = model_ref.get("name")
-                        if ref_id:
-                            ref_dict = {"id": ref_id}
-                        elif ref_name is not None:
-                            ref_dict = {"name": ref_name, "provider": model_ref.get("provider"), "type": model_ref.get("type")}
+                        ref_dict = {
+                            "id": model_ref.get("id"),
+                            "name": model_ref.get("name"),
+                            "provider": model_ref.get("provider"),
+                            "type": model_ref.get("type")
+                        }
                     elif isinstance(model_ref, str):
                         try:
                             uuid.UUID(model_ref)
@@ -640,12 +662,18 @@ class AppDslService:
                         resolved_model_id = self._resolve_model(ref_dict, tenant_id, warnings)
                         if resolved_model_id:
                             config["model_id"] = resolved_model_id
+                            if "model_ref" in config:
+                                del config["model_ref"]
                         else:
                             warnings.append(f"[{node_label}] 模型未匹配，已置空，请导入后手动配置")
                             config["model_id"] = None
+                            if "model_ref" in config:
+                                del config["model_ref"]
                     else:
                         warnings.append(f"[{node_label}] 模型未匹配，已置空，请导入后手动配置")
                         config["model_id"] = None
+                        if "model_ref" in config:
+                            del config["model_ref"]
             resolved_nodes.append({**node, "config": config})
         return resolved_nodes
 

api/app/services/draft_run_service.py

@@ -108,6 +108,7 @@ def create_long_term_memory_tool(
         try:
             with get_db_context() as db:
                 memory_service = MemoryService(db, config_id, end_user_id)
+                # TODO: Historical Messages -> Used to refer to coreference resolution
                 search_result = asyncio.run(memory_service.read(question, SearchStrategy.QUICK))
 
             #     memory_content = asyncio.run(

api/app/services/file_storage_service.py

@@ -34,26 +34,7 @@ def generate_file_key(
     Generate a unique file key for storage.
 
     The file key follows the format: {tenant_id}/{workspace_id}/{file_id}{file_ext}
-
-    Args:
-        tenant_id: The tenant UUID.
-        workspace_id: The workspace UUID.
-        file_id: The file UUID.
-        file_ext: The file extension (e.g., '.pdf', '.txt').
-
-    Returns:
-        A unique file key string.
-
-    Example:
-        >>> generate_file_key(
-        ...     uuid.UUID('550e8400-e29b-41d4-a716-446655440000'),
-        ...     uuid.UUID('660e8400-e29b-41d4-a716-446655440001'),
-        ...     uuid.UUID('770e8400-e29b-41d4-a716-446655440002'),
-        ...     '.pdf'
-        ... )
-        '550e8400-e29b-41d4-a716-446655440000/660e8400-e29b-41d4-a716-446655440001/770e8400-e29b-41d4-a716-446655440002.pdf'
     """
-    # Ensure file_ext starts with a dot
     if file_ext and not file_ext.startswith('.'):
         file_ext = f'.{file_ext}'
     if workspace_id:
@@ -61,6 +42,21 @@ def generate_file_key(
     return f"{tenant_id}/{file_id}{file_ext}"
 
 
+def generate_kb_file_key(
+    kb_id: uuid.UUID,
+    file_id: uuid.UUID,
+    file_ext: str,
+) -> str:
+    """
+    Generate a file key for knowledge base files.
+
+    Format: kb/{kb_id}/{file_id}{file_ext}
+    """
+    if file_ext and not file_ext.startswith('.'):
+        file_ext = f'.{file_ext}'
+    return f"kb/{kb_id}/{file_id}{file_ext}"
+
+
 class FileStorageService:
     """
     High-level service for file storage operations.

api/app/services/memory_dashboard_service.py

@@ -1,5 +1,5 @@
 from sqlalchemy.orm import Session
-from sqlalchemy import desc, nullslast, or_, and_, cast, String
+from sqlalchemy import desc, nullslast, or_, cast, String, func
 from typing import List, Optional, Dict, Any
 import uuid
 from fastapi import HTTPException
@@ -102,6 +102,7 @@ def get_workspace_end_users_paginated(
     """获取工作空间的宿主列表（分页版本，支持模糊搜索）
 
     返回结果按 created_at 从新到旧排序（NULL 值排在最后）
+    固定过滤 memory_count > 0 的宿主，保证分页基于“有记忆宿主”集合计算。
     支持通过 keyword 参数同时模糊搜索 other_name 和 id 字段
 
     Args:
@@ -120,7 +121,8 @@ def get_workspace_end_users_paginated(
     try:
         # 构建基础查询
         base_query = db.query(EndUserModel).filter(
-            EndUserModel.workspace_id == workspace_id
+            EndUserModel.workspace_id == workspace_id,
+            EndUserModel.memory_count > 0 , # 只查询有记忆的宿主
         )
 
         # 构建搜索条件（过滤空字符串和None）
@@ -128,20 +130,13 @@ def get_workspace_end_users_paginated(
 
         if keyword:
             keyword_pattern = f"%{keyword}%"
-            # other_name 匹配始终生效；id 匹配仅对 other_name 为空的记录生效
             base_query = base_query.filter(
                 or_(
                     EndUserModel.other_name.ilike(keyword_pattern),
-                    and_(
-                        or_(
-                            EndUserModel.other_name.is_(None),
-                            EndUserModel.other_name == "",
-                        ),
-                        cast(EndUserModel.id, String).ilike(keyword_pattern),
-                    ),
+                    cast(EndUserModel.id, String).ilike(keyword_pattern),
                 )
             )
-            business_logger.info(f"应用模糊搜索: keyword={keyword}（匹配 other_name；other_name 为空时匹配 id）")
+            business_logger.info(f"应用模糊搜索: keyword={keyword}（匹配 other_name 或 id）")
 
         # 获取总记录数
         total = base_query.count()
@@ -169,6 +164,98 @@ def get_workspace_end_users_paginated(
         business_logger.error(f"获取工作空间宿主列表（分页）失败: workspace_id={workspace_id} - {str(e)}")
         raise
 
+def get_workspace_end_users_paginated_rag(
+    db: Session,
+    workspace_id: uuid.UUID,
+    current_user: User,
+    page: int,
+    pagesize: int,
+    keyword: Optional[str] = None,
+) -> Dict[str, Any]:
+    """RAG 模式宿主列表分页。
+
+    RAG 记忆数量以 documents.chunk_num 为准：
+    - file_name = end_user_id + ".txt"
+    - 只统计当前 workspace 下 permission_id="Memory" 的用户记忆知识库
+    - 在 SQL 层过滤 chunk 总数为 0 的宿主，保证分页准确
+    """
+    business_logger.info(
+        f"获取 RAG 宿主列表（分页）: workspace_id={workspace_id}, "
+        f"keyword={keyword}, page={page}, pagesize={pagesize}, 操作者: {current_user.username}"
+    )
+
+    try:
+        from app.models.document_model import Document
+        from app.models.knowledge_model import Knowledge
+
+        chunk_subquery = (
+            db.query(
+                Document.file_name.label("file_name"),
+                func.coalesce(func.sum(Document.chunk_num), 0).label("memory_count"),
+            )
+            .join(Knowledge, Document.kb_id == Knowledge.id)
+            .filter(
+                Knowledge.workspace_id == workspace_id,
+                Knowledge.status == 1,
+                Knowledge.permission_id == "Memory",
+                Document.status == 1,
+            )
+            .group_by(Document.file_name)
+            .subquery()
+        )
+
+        base_query = (
+            db.query(
+                EndUserModel,
+                chunk_subquery.c.memory_count.label("memory_count"),
+            )
+            .join(
+                chunk_subquery,
+                chunk_subquery.c.file_name == func.concat(cast(EndUserModel.id, String), ".txt"),
+            )
+            .filter(
+                EndUserModel.workspace_id == workspace_id,
+                chunk_subquery.c.memory_count > 0,
+            )
+        )
+
+        keyword = keyword.strip() if keyword else None
+        if keyword:
+            keyword_pattern = f"%{keyword}%"
+            base_query = base_query.filter(
+                or_(
+                    EndUserModel.other_name.ilike(keyword_pattern),
+                    cast(EndUserModel.id, String).ilike(keyword_pattern),
+                )
+            )
+
+        total = base_query.count()
+        if total == 0:
+            business_logger.info("RAG 模式下没有符合条件的宿主")
+            return {"items": [], "total": 0}
+
+        rows = base_query.order_by(
+            nullslast(desc(EndUserModel.created_at)),
+            desc(EndUserModel.id),
+        ).offset((page - 1) * pagesize).limit(pagesize).all()
+
+        items = []
+        for end_user_orm, memory_count in rows:
+            items.append({
+                "end_user": EndUserSchema.model_validate(end_user_orm),
+                "memory_count": int(memory_count or 0),
+            })
+
+        business_logger.info(f"成功获取 RAG 宿主记录 {len(items)} 条，总计 {total} 条")
+        return {"items": items, "total": total}
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        business_logger.error(
+            f"获取 RAG 宿主列表（分页）失败: workspace_id={workspace_id} - {str(e)}"
+        )
+        raise
 
 def get_workspace_memory_increment(
     db: Session, 

api/app/services/prompt/perceptual_summary_system.jinja2

@@ -1,13 +1,13 @@
 {% raw %}You are a professional information extraction system.
 
-Your task is to analyze the provided document content and generate structured metadata.
+Your task is to analyze the provided file content and generate structured metadata.
 
 Extract the following fields:
 
-* **summary**: A concise summary of the document in 2–4 sentences.
-* **keywords**: 5–10 important keywords or key phrases that best represent the document. This field MUST be a JSON array of strings.
-* **topic**: The primary topic of the document expressed as a short phrase (3–8 words).
-* **domain**: The broader knowledge domain or field the document belongs to (e.g., Artificial Intelligence, Computer Science, Finance, Healthcare, Education, Law, etc.).
+* **summary**: A concise summary of the file in 3–5 sentences.
+* **keywords**: 5–10 important keywords or key phrases that best represent the file. This field MUST be a JSON array of strings.
+* **topic**: The primary topic of the file expressed as a short phrase (3–8 words).
+* **domain**: The broader knowledge domain or field the file belongs to (e.g., Artificial Intelligence, Computer Science, Finance, Healthcare, Education, Law, etc.).
 
 STRICT RULES:
 
@@ -28,7 +28,7 @@ STRICT RULES:
 {% endif %}
 {% raw %}
 6. `keywords` MUST be a JSON array of strings.
-7. If the document content is insufficient, infer the best possible answer based on context.
+7. If the file content is insufficient, infer the best possible answer based on context.
 8. Ensure the JSON is syntactically correct.
 {% endraw %}
 9. Output using the language {{ language }}
@@ -50,4 +50,4 @@ Required JSON format:
 {% raw %}
 }
 
-Now analyze the following document and return the JSON result.{% endraw %}
+Now analyze the following file and return the JSON result.{% endraw %}

api/app/tasks.py

@@ -210,9 +210,14 @@ def _build_vision_model(file_path: str, db_knowledge):
 
 
 @celery_app.task(name="app.core.rag.tasks.parse_document")
-def parse_document(file_path: str, document_id: uuid.UUID):
+def parse_document(file_key: str, document_id: uuid.UUID, file_name: str = ""):
     """
-    Document parsing, vectorization, and storage
+    Document parsing, vectorization, and storage.
+    
+    Args:
+        file_key: Storage key for FileStorageService (e.g. "kb/{kb_id}/{file_id}.docx")
+        document_id: Document UUID
+        file_name: Original file name (used for extension detection in chunk())
     """
 
     db_document = None
@@ -223,7 +228,6 @@ def parse_document(file_path: str, document_id: uuid.UUID):
 
     with get_db_context() as db:
       try:
-        # Celery JSON 序列化会将 UUID 转为字符串，需要确保类型正确
         if not isinstance(document_id, uuid.UUID):
             document_id = uuid.UUID(str(document_id))
 
@@ -234,7 +238,11 @@ def parse_document(file_path: str, document_id: uuid.UUID):
         if db_knowledge is None:
             raise ValueError(f"Knowledge {db_document.kb_id} not found")
 
-        # 1. Document parsing & segmentation
+        # Use file_name from argument or fall back to document record
+        if not file_name:
+            file_name = db_document.file_name
+
+        # 1. Download file from storage backend
         progress_lines.append(f"{datetime.now().strftime('%H:%M:%S')} Start to parse.")
         start_time = time.time()
         db_document.progress = 0.0
@@ -245,45 +253,36 @@ def parse_document(file_path: str, document_id: uuid.UUID):
         db.commit()
         db.refresh(db_document)
 
+        # Read file content from storage backend (no NFS dependency)
+        from app.services.file_storage_service import FileStorageService
+        import asyncio
+        storage_service = FileStorageService()
+
+        async def _download():
+            return await storage_service.download_file(file_key)
+
+        try:
+            file_binary = asyncio.run(_download())
+        except RuntimeError:
+            # If there's already a running loop (e.g. in some worker configurations)
+            loop = asyncio.new_event_loop()
+            try:
+                file_binary = loop.run_until_complete(_download())
+            finally:
+                loop.close()
+        if not file_binary:
+            raise IOError(f"Downloaded empty file from storage: {file_key}")
+        logger.info(f"[ParseDoc] Downloaded {len(file_binary)} bytes from storage key: {file_key}")
+
         def progress_callback(prog=None, msg=None):
             progress_lines.append(f"{datetime.now().strftime('%H:%M:%S')} parse progress: {prog} msg: {msg}.")
 
         # Prepare vision_model for parsing
-        vision_model = _build_vision_model(file_path, db_knowledge)
-
-        # 先将文件读入内存，避免解析过程中依赖 NFS 文件持续可访问
-        # python-docx 等库在 binary=None 时会用路径直接打开文件，
-        # 在 NFS/共享存储上可能因缓存失效导致 "Package not found"
-        max_wait_seconds = 30
-        wait_interval = 2
-        waited = 0
-        file_binary = None
-        while waited <= max_wait_seconds:
-            # os.listdir 强制 NFS 客户端刷新目录缓存
-            parent_dir = os.path.dirname(file_path)
-            try:
-                os.listdir(parent_dir)
-            except OSError:
-                pass
-            try:
-                with open(file_path, "rb") as f:
-                    file_binary = f.read()
-                if not file_binary:
-                    # NFS 上文件存在但内容为空（可能还在同步中）
-                    raise IOError(f"File is empty (0 bytes), NFS may still be syncing: {file_path}")
-                break
-            except (FileNotFoundError, IOError) as e:
-                if waited >= max_wait_seconds:
-                    raise type(e)(
-                        f"File not accessible at '{file_path}' after waiting {max_wait_seconds}s: {e}"
-                    )
-                logger.warning(f"File not ready on this node, retrying in {wait_interval}s: {file_path} ({e})")
-                time.sleep(wait_interval)
-                waited += wait_interval
+        vision_model = _build_vision_model(file_name, db_knowledge)
 
         from app.core.rag.app.naive import chunk
         logger.info(f"[ParseDoc] file_binary size={len(file_binary)} bytes, type={type(file_binary).__name__}, bool={bool(file_binary)}")
-        res = chunk(filename=file_path,
+        res = chunk(filename=file_name,
                     binary=file_binary,
                     from_page=0,
                     to_page=DEFAULT_PARSE_TO_PAGE,

api/app/utils/tmp_session.py

@@ -0,0 +1,77 @@
+import json
+import logging
+
+import redis.asyncio as redis
+
+from app.aioRedis import get_redis_connection
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TTL = 3600
+
+
+class ChatSessionCache:
+    """Cache user-AI conversation history in Redis with TTL-based expiry.
+
+    Usage::
+
+        cache = ChatSessionCache(session_id="user_123")
+        await cache.append("user", "Hello")
+        await cache.append("assistant", "Hi there!")
+        history = await cache.get_history()
+    """
+
+    def __init__(self, session_id: str, ttl: int = DEFAULT_TTL):
+        self.session_id = session_id
+        self.ttl = ttl
+        self._key = f"chat:session:{session_id}"
+
+    @staticmethod
+    async def _client() -> redis.StrictRedis:
+        return await get_redis_connection()
+
+    async def append(self, role: str, content: str) -> None:
+        r = await self._client()
+        entry = json.dumps({"role": role, "content": content}, ensure_ascii=False)
+        await r.rpush(self._key, entry)
+        await r.expire(self._key, self.ttl)
+
+    async def append_many(self, messages: list[dict[str, str]]) -> None:
+        """Batch append messages. Each dict should have ``role`` and ``content`` keys."""
+        if not messages:
+            return
+        r = await self._client()
+        entries = [
+            json.dumps(m, ensure_ascii=False)
+            for m in messages
+            if "role" in m and "content" in m
+        ]
+        if entries:
+            await r.rpush(self._key, *entries)
+            await r.expire(self._key, self.ttl)
+
+    async def get_history(self) -> list[dict[str, str]]:
+        r = await self._client()
+        raw = await r.lrange(self._key, 0, -1)
+        return [json.loads(item) for item in raw]
+
+    async def get_history_text(self, user_label: str = "User", ai_label: str = "Assistant") -> str:
+        """Return conversation as a formatted text block."""
+        history = await self.get_history()
+        lines = []
+        for msg in history:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+            label = user_label if role == "user" else ai_label if role == "assistant" else role
+            lines.append(f"{label}: {content}")
+        return "\n".join(lines)
+
+    async def reset(self) -> None:
+        """Delete the session from Redis."""
+        r = await self._client()
+        await r.delete(self._key)
+
+    async def touch(self) -> None:
+        """Refresh the TTL without modifying data."""
+        r = await self._client()
+        await r.expire(self._key, self.ttl)

api/migrations/versions/1f85dce125e5_202604271530.py

@@ -0,0 +1,47 @@
+"""202604271530
+
+Revision ID: 1f85dce125e5
+Revises: 4e89970f9e7c
+Create Date: 2026-04-27 15:30:35.614679
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = '1f85dce125e5'
+down_revision: Union[str, None] = '4e89970f9e7c'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column('files', sa.Column('file_key', sa.String(length=512), nullable=True, comment='storage file key for FileStorageService'))
+    op.create_index(op.f('ix_files_file_key'), 'files', ['file_key'], unique=False)
+    op.alter_column('model_configs', 'capability',
+               existing_type=postgresql.ARRAY(sa.VARCHAR()),
+               comment="模型能力列表（如['vision', 'audio', 'video', 'thinking']）",
+               existing_comment="模型能力列表（如['vision', 'audio', 'video']）",
+               existing_nullable=False)
+    # ### end Alembic commands ###
+    op.execute("""
+        UPDATE files
+        SET file_key = 'kb/' || kb_id::text || '/' || parent_id::text || '/' || id::text || file_ext
+        WHERE file_ext != 'folder' AND file_key IS NULL
+    """)
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.alter_column('model_configs', 'capability',
+               existing_type=postgresql.ARRAY(sa.VARCHAR()),
+               comment="模型能力列表（如['vision', 'audio', 'video']）",
+               existing_comment="模型能力列表（如['vision', 'audio', 'video', 'thinking']）",
+               existing_nullable=False)
+    op.drop_index(op.f('ix_files_file_key'), table_name='files')
+    op.drop_column('files', 'file_key')
+    # ### end Alembic commands ###

api/migrations/versions/37e2a73b28c4_202604291755.py

@@ -0,0 +1,139 @@
+"""202604291755
+
+Revision ID: 37e2a73b28c4
+Revises: e2d60c6d1a1a
+Create Date: 2026-04-29 18:52:35.686290
+
+"""
+from typing import Dict, List, Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = '37e2a73b28c4'
+down_revision: Union[str, None] = 'e2d60c6d1a1a'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+BATCH_SIZE = 500
+
+def _chunked(values: List[str], size: int) -> List[List[str]]:
+    return [values[index:index + size] for index in range(0, len(values), size)]
+
+
+def _load_neo4j_end_user_ids(connection) -> List[str]:
+    """加载所有需要从 Neo4j 同步 memory_count 的宿主。
+
+    RAG 工作空间的记忆数量以 documents.chunk_num 为准，不写入 end_users.memory_count。
+    """
+    rows = connection.execute(sa.text("""
+        SELECT eu.id::text AS end_user_id
+        FROM end_users eu
+        JOIN workspaces w ON eu.workspace_id = w.id
+        WHERE w.storage_type IS NULL OR w.storage_type <> 'rag'
+    """)).all()
+    return [row[0] for row in rows]
+
+
+async def _fetch_neo4j_counts(end_user_ids: List[str]) -> Dict[str, int]:
+    if not end_user_ids:
+        return {}
+
+    from app.repositories.memory_config_repository import MemoryConfigRepository
+    from app.repositories.neo4j.neo4j_connector import Neo4jConnector
+
+    connector = Neo4jConnector()
+    try:
+        result = await connector.execute_query(
+            MemoryConfigRepository.SEARCH_FOR_ALL_BATCH,
+            end_user_ids=end_user_ids,
+        )
+    finally:
+        await connector.close()
+
+    counts = {str(row["user_id"]): int(row["total"]) for row in result}
+    for end_user_id in end_user_ids:
+        counts.setdefault(end_user_id, 0)
+    return counts
+
+
+def _update_memory_counts(connection, counts: Dict[str, int]) -> int:
+    updated = 0
+    for end_user_id, memory_count in counts.items():
+        result = connection.execute(
+            sa.text("""
+                UPDATE end_users
+                SET memory_count = :memory_count
+                WHERE id = CAST(:end_user_id AS uuid)
+            """),
+            {
+                "end_user_id": end_user_id,
+                "memory_count": memory_count,
+            },
+        )
+        updated += result.rowcount or 0
+    return updated
+
+
+def _sync_memory_count_from_neo4j() -> None:
+    """迁移时初始化 Neo4j 模式宿主的 memory_count。
+
+    """
+    import asyncio
+
+    print("[memory_count] 开始同步 Neo4j 模式宿主 memory_count")
+    connection = op.get_bind()
+    target_ids = _load_neo4j_end_user_ids(connection)
+    if not target_ids:
+        print("[memory_count] 没有需要同步的 Neo4j 模式宿主")
+        return
+
+    print(
+        f"[memory_count] 待同步宿主数量: {len(target_ids)}, "
+        f"batch_size={BATCH_SIZE}"
+    )
+
+    total_updated = 0
+    batches = _chunked(target_ids, BATCH_SIZE)
+    for batch_index, batch_ids in enumerate(batches, start=1):
+        print(
+            f"[memory_count] 正在查询 Neo4j: "
+            f"batch={batch_index}/{len(batches)}, size={len(batch_ids)}"
+        )
+        counts = asyncio.run(_fetch_neo4j_counts(batch_ids))
+        total_updated += _update_memory_counts(connection, counts)
+        print(
+            f"[memory_count] 已写入 PostgreSQL: "
+            f"updated={total_updated}/{len(target_ids)}"
+        )
+
+    print(
+        f"[memory_count] Neo4j 模式宿主同步完成: "
+        f"total={len(target_ids)}, updated={total_updated}"
+    )
+
+
+def upgrade() -> None:
+    op.add_column(
+        'end_users',
+        sa.Column(
+            'memory_count',
+            sa.Integer(),
+            server_default='0',
+            nullable=False,
+            comment='记忆节点总数',
+        ),
+    )
+    _sync_memory_count_from_neo4j()
+    op.create_index(
+        op.f('ix_end_users_memory_count'),
+        'end_users',
+        ['memory_count'],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(op.f('ix_end_users_memory_count'), table_name='end_users')
+    op.drop_column('end_users', 'memory_count')

api/migrations/versions/e2d60c6d1a1a_202604281230.py

@@ -0,0 +1,34 @@
+"""202604281230
+
+Revision ID: e2d60c6d1a1a
+Revises: 1f85dce125e5
+Create Date: 2026-04-28 12:32:01.643954
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = 'e2d60c6d1a1a'
+down_revision: Union[str, None] = '1f85dce125e5'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column('tenants', 'api_ops_rate_limit')
+    op.drop_column('tenants', 'plan')
+    op.drop_column('tenants', 'plan_expired_at')
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column('tenants', sa.Column('plan_expired_at', postgresql.TIMESTAMP(), autoincrement=False, nullable=True))
+    op.add_column('tenants', sa.Column('plan', sa.VARCHAR(length=50), autoincrement=False, nullable=True))
+    op.add_column('tenants', sa.Column('api_ops_rate_limit', sa.VARCHAR(length=100), autoincrement=False, nullable=True))
+    # ### end Alembic commands ###

docs/rag/INDEX.md

@@ -1,94 +0,0 @@
-# MemoryBear RAG 文档全集 · 总索引（INDEX.md）
-
-> 文件级清单 + 责任矩阵 + 状态追踪。Landing 阅读路径请看 [`README.md`](README.md)。
-
-## 1. 责任矩阵（RACI）
-
-| 角色 | 主要职责 | 角色 ID |
-|---|---|---|
-| **AI 知识库解决方案专家** | 全链路架构图、E2E、架构改造、迭代路线 | `a1c1a61f-f877-4d55-8a68-4f9c6a8f69cf` |
-| **Python 开发工程师** | 源码盘点、Sprint-2 五篇深度文档（除 GraphRAG 待重启） | `f4d1c89f-0c71-4af3-bf72-d34f7ed115cf` |
-| **知识运营与治理专家** | 治理资产、终审评分、目录与索引、运营保鲜 | `7e9211a6-41eb-429e-9dd1-4c7afcffd412` |
-| **项目管理与迭代规划专家** | 节奏规划、风险登记、复盘 | `712fa3ae-9710-4cf3-a478-b081d8c8743c` |
-
-## 2. 文件清单（按目录）
-
-| 路径 | 标题 | 责任人 | 来源任务 | 状态 | 评分 | 备注 |
-|---|---|---|---|---|---|---|
-| `README.md` | Landing 页（v1.0-RC1） | 知识运营 | WS-24 | ✅ 已交付 | — | 三套阅读路径 + 全目录树 |
-| `INDEX.md` | 总索引（本文） | 知识运营 | WS-24 | ✅ 已交付 | — | — |
-| `_meta/README.md` | 治理体系总览 | 知识运营 | WS-12 | ✅ 已交付 | — | 见 [WS-12 评论 `93ea1f50`](mention://issue/b1ead19b-920b-494b-95b5-ab2057d4dd14) |
-| `_meta/document-template.md` | 统一文档模板 | 知识运营 | WS-12 | ✅ 已交付 | — | 同上 |
-| `_meta/scoring-rubric.md` | 质量评分卡 | 知识运营 | WS-12 | ✅ 已交付 | — | 5 维 100 分制，通过线 80 |
-| `_meta/review-sop.md` | 审校流程 SOP | 知识运营 | WS-12 | ✅ 已交付 | — | 自检 → 同行 → 终审 |
-| `_meta/directory-naming-spec.md` | 目录与命名规范 | 知识运营 | WS-12 | ✅ 已交付 | — | frontmatter 规范 |
-| `_meta/rubric-scoresheet.md` | 评分记录表 | 知识运营 | WS-12 | ✅ 已交付 | — | Sprint-2 评分预置 |
-| `overview/01-architecture.mmd` | 全链路架构图 | AI 知识库 | WS-13 | ✅ 已交付 | — | Mermaid Flowchart |
-| `overview/02-indexing-pipeline.mmd` | 文档入库时序图 | AI 知识库 | WS-13 | ✅ 已交付 | — | Mermaid Sequence |
-| `overview/03-query-pipeline.mmd` | 在线检索时序图 | AI 知识库 | WS-13 | ✅ 已交付 | — | Mermaid Sequence |
-| `overview/04-graphrag-indexing.mmd` | GraphRAG 索引时序图 | AI 知识库 | WS-13 | ✅ 已交付 | — | light + general |
-| `overview/boundaries.md` | 11 个 RAG 阶段边界定义 | AI 知识库 | WS-13 | ✅ 已交付 | — | 输入/输出/接口契约 |
-| `overview/DocMap.md` | Sprint-2 41 篇文档大纲 | AI 知识库 | WS-13 | ✅ 已交付 | — | — |
-| `overview/source-inventory.md` | 源码盘点 + 模块依赖图 | Python 工程师 | WS-14 | ✅ 已交付 | — | 见 [WS-14 评论](mention://issue/264529aa-1856-4505-8e26-6125df061c18) |
-| `pipeline/01-loader-parser-chunking.md` | Loader / Parser / Chunking | Python 工程师 | WS-15 | ✅ 已交付 | 待 S2-T7 评分 | 见 [WS-15 评论](mention://issue/1b2dde64-83c3-49b8-8d71-50953c107594) |
-| `pipeline/02-embedding.md` | Embedding 模型与向量生成 | Python 工程师 | WS-16 | ✅ 已交付 | 待 S2-T7 评分 | 见 [WS-16 评论](mention://issue/7a8cd047-f339-427e-bd60-999c62caea22) |
-| `pipeline/03-vdb-and-retrieval.md` | VDB（ES）与混合检索 | Python 工程师 | WS-17 | ✅ 已交付 | 待 S2-T7 评分 | 见 [WS-17 评论](mention://issue/53783731-fd5d-40ef-8063-17a39c0d860d) |
-| `pipeline/04-graphrag.md` | GraphRAG 实现详解 | Python 工程师 | WS-18 | ⏳ 占位 | — | 上一次执行 API Error，待重启 |
-| `pipeline/05-reranking-prompt-llm.md` | Rerank / Prompt / LLM / 后处理 | Python 工程师 | WS-19 | ✅ 已交付 | 待 S2-T7 评分 | 见 [WS-19 评论](mention://issue/eef8ed99-c13e-43ba-a2b3-2c9e59b74301) |
-| `end-to-end/README.md` | E2E 调用链路与时序图 | AI 知识库 | WS-20 | ⏳ 占位 | — | 阻塞中：依赖 S2-T1~T5 全部交付 |
-| `evolution/architecture-refactor-suggestions.md` | 架构改造建议（11 条） | AI 知识库 | WS-22 | ✅ 已交付 + 终审 | **96 / 100** ✅ | 见 [`review/S3-T1-final-review.md`](review/S3-T1-final-review.md) |
-| `evolution/future-extensions-roadmap.md` | 后续迭代功能（6 个方向） | AI 知识库 | WS-23 | ✅ 已交付 + 终审 | **95 / 100** ✅ | 见 [`review/S3-T2-final-review.md`](review/S3-T2-final-review.md) |
-| `evolution/capability-map.mmd` | 能力地图 | AI 知识库 | WS-23 | ✅ 已交付 | — | Mermaid，配合 S3-T2 |
-| `review/S3-T1-final-review.md` | S3-T1 终审报告 | 知识运营 | WS-24 | ✅ 已交付 | — | — |
-| `review/S3-T2-final-review.md` | S3-T2 终审报告 | 知识运营 | WS-24 | ✅ 已交付 | — | — |
-| `review/S2-T7-pending.md` | Sprint-2 评审收口 | 知识运营 | WS-21 | ⏳ 未启动 | — | 上一次 API Error，待重启 |
-| `review/README.md` | 评审历史索引 | 知识运营 | WS-24 | ✅ 已交付 | — | — |
-| `_indexes/glossary.md` | 关键术语表 | 知识运营 | WS-24 | ✅ 已交付 | — | — |
-| `_indexes/file-index.md` | 源码 → 文档反查 | 知识运营 | WS-24 | ✅ 已交付 | — | — |
-| `_indexes/chart-index.md` | Mermaid 图集中清单 | 知识运营 | WS-24 | ✅ 已交付 | — | — |
-| `_release/release-manifest-v1.0-RC1.md` | 发布候选清单 | 知识运营 | WS-24 | ✅ 已交付 | — | 含 v1.0 升版门槛 |
-| `_release/versioning-convention.md` | 版本号约定 | 知识运营 | WS-24 | ✅ 已交付 | — | — |
-| `_release/ops-and-freshness-plan.md` | 运营与保鲜计划 | 知识运营 | WS-24 | ✅ 已交付 | — | — |
-
-## 3. 状态汇总
-
-| 状态 | 数量 | 占比 |
-|---|---|---|
-| ✅ 已交付（终审通过 / 待 Sprint 评审） | 28 | 84.8% |
-| ⏳ 占位 / 阻塞 / 待重启 | 5 | 15.2% |
-| **合计** | **33** | **100%** |
-
-> v1.0-RC1 阶段：核心 RAG 链路文档（_meta + overview + S3 演进）已完整成型；4 篇 Sprint-2 文档（S2-T1/T2/T3/T5）已交付待 Sprint-2 收口评审（[S2-T7]）打分；2 篇（S2-T4 GraphRAG 与 S2-T6 E2E）等待重启。完整 v1.0 在 S2-T7 通过后发布。
-
-## 4. 评审决议汇总
-
-| 文档 | 维度 | 准确性 | 完整性 | 时效性 | 可读性 | 可执行性 | 总分 | 决议 |
-|---|---|---|---|---|---|---|---|---|
-| S3-T1 架构改造建议 | 终审（知识运营） | 25 | 25 | 13 | 14 | 19 | **96** | ✅ PASS |
-| S3-T2 后续迭代路线图 | 终审（知识运营） | 24 | 25 | 13 | 15 | 18 | **95** | ✅ PASS |
-| S1-T1 治理资产 | 自评 + 同行 | 25 | 25 | 14 | 14 | 19 | **97** | ✅ 已交付 |
-| S1-T2 架构图与目录大纲 | 自评 | 24 | 24 | 14 | 14 | 18 | **94** | ✅ 已交付 |
-| S1-T3 源码盘点 | 自评 | 25 | 24 | 14 | 14 | 19 | **96** | ✅ 已交付 |
-| S2-T1 ~ T5 各深度文档 | 待 S2-T7 终审 | — | — | — | — | — | — | 等待评分 |
-
-> **说明**：S1 系列文档自评分为知识运营在本次 v1.0-RC1 整理过程中的"快速复核分"，仅供 PM 排序参考，正式分数以 [S2-T7] 收口评审或后续保鲜窗口为准。S2 各篇深度文档需在 [S2-T7] 评审通过后，由 [@知识运营与治理专家] 在评分卡上正式打分；当前阶段以"已交付"作为质量门槛。
-
-## 5. 与子任务 Issue 的双向链接
-
-| 文档 | 关联 Issue | 标识符 |
-|---|---|---|
-| `_meta/*` | [b1ead19b](mention://issue/b1ead19b-920b-494b-95b5-ab2057d4dd14) | WS-12 / S1-T1 |
-| `overview/01-04, boundaries, DocMap` | [21b40027](mention://issue/21b40027-505d-4064-812b-75bfcc24b89c) | WS-13 / S1-T2 |
-| `overview/source-inventory.md` | [264529aa](mention://issue/264529aa-1856-4505-8e26-6125df061c18) | WS-14 / S1-T3 |
-| `pipeline/01-loader-parser-chunking.md` | [1b2dde64](mention://issue/1b2dde64-83c3-49b8-8d71-50953c107594) | WS-15 / S2-T1 |
-| `pipeline/02-embedding.md` | [7a8cd047](mention://issue/7a8cd047-f339-427e-bd60-999c62caea22) | WS-16 / S2-T2 |
-| `pipeline/03-vdb-and-retrieval.md` | [53783731](mention://issue/53783731-fd5d-40ef-8063-17a39c0d860d) | WS-17 / S2-T3 |
-| `pipeline/04-graphrag.md` (占位) | [16bdb196](mention://issue/16bdb196-e10e-489b-b01c-9067b1f1bb23) | WS-18 / S2-T4 |
-| `pipeline/05-reranking-prompt-llm.md` | [eef8ed99](mention://issue/eef8ed99-c13e-43ba-a2b3-2c9e59b74301) | WS-19 / S2-T5 |
-| `end-to-end/README.md` (占位) | [a3deeaa1](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) | WS-20 / S2-T6 |
-| `review/S2-T7-pending.md` | [41f2482b](mention://issue/41f2482b-6f3e-4253-95f7-3e22e790f31c) | WS-21 / S2-T7 |
-| `evolution/architecture-refactor-suggestions.md` | [bc97a22c](mention://issue/bc97a22c-709e-4c93-a360-f015bc41a2e6) | WS-22 / S3-T1 |
-| `evolution/future-extensions-roadmap.md`, `capability-map.mmd` | [0de2c8f6](mention://issue/0de2c8f6-717d-43c7-af31-1c055550a5e7) | WS-23 / S3-T2 |
-| 全集（本任务） | [a07f108d](mention://issue/a07f108d-06ee-41b8-8b57-22455f60ddeb) | WS-24 / S3-T3 |
-
-— **MemoryBear RAG Docs · INDEX.md · v1.0-RC1 · 2026-05-08** —

docs/rag/README.md

@@ -1,158 +0,0 @@
-# MemoryBear RAG 实现文档全集 v1.0-RC1
-
-> **版本**：v1.0-RC1（Release Candidate 1）
-> **冻结日期**：2026-05-08
-> **基线源码**：MemoryBear `agent/ai/f8de881a` 分支（基于 commit `feae2f2e`）
-> **目标读者**：MemoryBear 平台开发者、RAG 架构师、运维与 SRE、产品需求分析师、二次开发者
-> **维护责任人**：知识运营与治理专家
-> **关联仓库**：https://github.com/LuyaoCoding/MemoryBear
-
----
-
-## 这本书在讲什么
-
-MemoryBear 把"非结构化资料 → 可被对话/Agent 检索消费的知识"这条 RAG 链路完整跑通了：从 Web/飞书/语雀/本地 11 类格式的解析、Chunking、Embedding、Elasticsearch 8.x 上的 Hybrid 向量+全文混合索引、Microsoft GraphRAG（general）与 LightRAG（light）双轨知识图谱、Reranker 三路实现、流式 LLM 调用、引用回填，到对话内存与 RAG 协同的产品差异化设计。
-
-本文档全集是上述链路的**「源码级实现说明 + 架构改造路线 + 后续迭代蓝图」**。所有结论都锚定到具体的源码位置（`path:line`），不允许凭空虚构。
-
-> **当前状态**：**Release Candidate 1（候选发布）**。S3-T1（架构改造建议）与 S3-T2（迭代功能路线图）已通过知识运营终审；Sprint-2 部分文档（S2-T4 GraphRAG、S2-T6 E2E、S2-T7 收口评审）尚未交付，对应章节为占位说明。完整 v1.0 在 S2 收口评审通过后发布。详见 [`_release/release-manifest-v1.0-RC1.md`](_release/release-manifest-v1.0-RC1.md)。
-
----
-
-## 三套阅读路径
-
-不同角色读法不同。从你最关心的入口起：
-
-### 🟢 路径 A · 新手 5 分钟（产品 / 业务 / 新人）
-
-| 步骤 | 文件 | 看什么 |
-|---|---|---|
-| 1 | 本文 §"这本书在讲什么" | 一句话理解 RAG 链路边界 |
-| 2 | [`overview/01-architecture.mmd`](overview/01-architecture.mmd) | 全链路架构图（Mermaid） |
-| 3 | [`evolution/future-extensions-roadmap.md`](evolution/future-extensions-roadmap.md) §"现状速览与设计基线" | 三色标注的能力地图（已有 / 可上 / 愿景） |
-| 4 | [`_indexes/glossary.md`](_indexes/glossary.md) | 关键术语（Chunk / Embedder / Hybrid / GraphRAG / Reranker） |
-
-**预期效果**：你能用一张图讲清 MemoryBear RAG 现在能做什么，未来 6 个月在做什么。
-
-### 🟡 路径 B · 工程师 30 分钟（开发者 / 二次开发 / 运维）
-
-| 步骤 | 文件 | 看什么 |
-|---|---|---|
-| 1 | 本文 §"全部目录树" | 代码模块对应到哪些文档 |
-| 2 | [`overview/source-inventory.md`](overview/source-inventory.md)（来自 S1-T3） | 24,895 LOC 的模块清单 + 依赖图 + Gap 报告 |
-| 3 | [`pipeline/01-loader-parser-chunking.md`](pipeline/01-loader-parser-chunking.md)（S2-T1） | Loader / Parser / Chunking 实现详解（11 类格式解析） |
-| 4 | [`pipeline/02-embedding.md`](pipeline/02-embedding.md)（S2-T2） | Embedding 双轨（RedBearEmbeddings vs 遗留层），含 10+ Provider 速查 |
-| 5 | [`pipeline/03-vdb-and-retrieval.md`](pipeline/03-vdb-and-retrieval.md)（S2-T3） | Elasticsearch 8.x 选型、HNSW、Hybrid 检索（BM25 + 向量），含 SPLADE 接入预埋 |
-| 6 | [`pipeline/05-reranking-prompt-llm.md`](pipeline/05-reranking-prompt-llm.md)（S2-T5） | 三路 Rerank、Prompt 工厂、流式 LLM、引用回填 |
-| 7 | [`overview/boundaries.md`](overview/boundaries.md)（S1-T2 §boundaries） | 11 个 RAG 阶段的输入/输出/接口契约 |
-| 8 | [`_indexes/file-index.md`](_indexes/file-index.md) | 反查：从源码模块倒查到对应文档章节 |
-
-**预期效果**：你能定位"我要改 Embedding，要碰哪些代码、要看哪些文档"。
-
-### 🟣 路径 C · 架构师 1 小时（技术决策 / 架构演进 / 投入决策）
-
-| 步骤 | 文件 | 看什么 |
-|---|---|---|
-| 1 | 路径 B 全套（先打底） | — |
-| 2 | [`overview/source-inventory.md`](overview/source-inventory.md) §四 Gap 报告 | 14 项"代码 vs 架构"差异 |
-| 3 | [`evolution/architecture-refactor-suggestions.md`](evolution/architecture-refactor-suggestions.md)（S3-T1） | 11 条改造建议 + 2 套 PoC + 短/中/长三段路线图 |
-| 4 | [`evolution/future-extensions-roadmap.md`](evolution/future-extensions-roadmap.md)（S3-T2） | 6 个扩展方向（多模态 / 混合搜索 / KG / 对话记忆 / 评估闭环 / 自适应路由） |
-| 5 | [`evolution/capability-map.mmd`](evolution/capability-map.mmd) | 能力地图：现状 vs 短期 vs 长期 |
-| 6 | [`review/S3-T1-final-review.md`](review/S3-T1-final-review.md) + [`review/S3-T2-final-review.md`](review/S3-T2-final-review.md) | 知识运营终审报告（评分 / Should-Fix / 兼容性核对） |
-| 7 | [`_release/ops-and-freshness-plan.md`](_release/ops-and-freshness-plan.md) | 版本演进、保鲜与失效策略 |
-
-**预期效果**：你能为下一季度 RAG 投入排序，给出"先做什么 / 缓做什么 / 不做什么"的判断依据。
-
----
-
-## 全部目录树
-
-```
-docs/rag/
-├── README.md                                   # ← 你在这里
-├── INDEX.md                                    # 完整文件清单 + 责任矩阵
-├── _meta/                                      # 治理资产（S1-T1）
-│   ├── README.md                               # 治理体系总览（含 8 环节 → 代码目录速查）
-│   ├── document-template.md                    # 统一文档模板（9 大章节）
-│   ├── scoring-rubric.md                       # 5 维度评分卡（满分 100，通过线 80）
-│   ├── review-sop.md                           # 审校流程：作者自检 → 同行 → 终审
-│   ├── directory-naming-spec.md                # 目录与命名规范、frontmatter
-│   └── rubric-scoresheet.md                    # Sprint-2 评分记录表
-├── overview/                                   # 总览（S1-T2 + S1-T3）
-│   ├── 01-architecture.mmd                     # 全链路架构图（Mermaid）
-│   ├── 02-indexing-pipeline.mmd                # 文档入库时序图
-│   ├── 03-query-pipeline.mmd                   # 在线检索时序图
-│   ├── 04-graphrag-indexing.mmd                # GraphRAG 索引时序图（light/general）
-│   ├── boundaries.md                           # 11 个 RAG 阶段边界定义
-│   ├── DocMap.md                               # Sprint-2 41 篇文档目录大纲
-│   └── source-inventory.md                     # 源码盘点 + 模块依赖图谱（S1-T3）
-├── pipeline/                                   # 各环节深度文档（S2-T1 ~ T5）
-│   ├── 01-loader-parser-chunking.md            # S2-T1：11 类格式 + 8 种 Chunking 策略
-│   ├── 02-embedding.md                         # S2-T2：10+ Provider + 多模态
-│   ├── 03-vdb-and-retrieval.md                 # S2-T3：ES 8.x + HNSW + Hybrid
-│   ├── 04-graphrag.md                          # S2-T4：GraphRAG light + general（待交付，占位）
-│   └── 05-reranking-prompt-llm.md              # S2-T5：Rerank/Prompt/LLM/引用回填
-├── graphrag/                                   # GraphRAG 专章（合并自 pipeline/04）
-│   └── README.md                               # 占位：S2-T4 完成后并入
-├── end-to-end/                                 # 端到端调用链（S2-T6，待交付）
-│   └── README.md                               # 占位：依赖 S2-T1~T5 全部完成
-├── evolution/                                  # 架构演进（S3-T1 + S3-T2）
-│   ├── architecture-refactor-suggestions.md    # S3-T1：11 条改造建议 + 路线图
-│   ├── future-extensions-roadmap.md            # S3-T2：6 个扩展方向
-│   └── capability-map.mmd                      # 能力地图（已有 / 可上 / 愿景）
-├── review/                                     # 评审报告归档
-│   ├── S3-T1-final-review.md                   # S3-T1 终审报告（96/100 通过）
-│   ├── S3-T2-final-review.md                   # S3-T2 终审报告（95/100 通过）
-│   ├── S2-T7-pending.md                        # Sprint-2 评审收口（占位，未启动）
-│   └── README.md                               # 评审历史索引
-├── _indexes/                                   # 跨文档索引
-│   ├── glossary.md                             # 关键术语表（合并所有 Sprint）
-│   ├── file-index.md                           # 源码模块 → 文档反查
-│   └── chart-index.md                          # 所有 Mermaid 图集中清单
-└── _release/                                   # 发布与运营
-    ├── release-manifest-v1.0-RC1.md            # 发布候选清单（仓库 PR / Wiki / 版本约定）
-    ├── versioning-convention.md                # 版本号约定（语义化 + 锁源码 commit）
-    └── ops-and-freshness-plan.md               # 运营与保鲜计划
-```
-
-> **未交付占位说明**：`pipeline/04-graphrag.md`、`end-to-end/`、`review/S2-T7-pending.md` 三处为占位，正文位于关联子任务的评论中（[WS-18](mention://issue/16bdb196-e10e-489b-b01c-9067b1f1bb23) / [WS-20](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) / [WS-21](mention://issue/41f2482b-6f3e-4253-95f7-3e22e790f31c)）。完整 v1.0 在 S2-T7 评审通过后发布，参见 `_release/release-manifest-v1.0-RC1.md`。
-
----
-
-## 与代码的对应关系（速查）
-
-| RAG 环节 | 代码目录 | 对应文档 |
-|---|---|---|
-| 文档加载（Web / 飞书 / 语雀 / 本地） | `api/app/core/rag/{crawler,integrations}` | [`pipeline/01-loader-parser-chunking.md`](pipeline/01-loader-parser-chunking.md) |
-| 多格式解析 + OCR + 版面识别 | `api/app/core/rag/{deepdoc/{parser,vision},app/naive.py}` | 同上 |
-| Chunking + Tokenization | `api/app/core/rag/{nlp,common/token_utils.py}` | 同上 |
-| Embedding（双轨） | `api/app/core/{models/embedding.py, rag/llm/embedding_model.py}` | [`pipeline/02-embedding.md`](pipeline/02-embedding.md) |
-| Vector DB + 索引 | `api/app/core/rag/vdb/elasticsearch/` | [`pipeline/03-vdb-and-retrieval.md`](pipeline/03-vdb-and-retrieval.md) |
-| BM25 + 向量混合检索 | `api/app/core/rag/{nlp/search.py, vdb/elasticsearch}` | 同上 |
-| Knowledge Graph（GraphRAG） | `api/app/core/rag/graphrag/{light,general}` | [`pipeline/04-graphrag.md`](pipeline/04-graphrag.md)（占位） |
-| Reranking（三路实现） | `api/app/core/{models/rerank.py, workflow/nodes/knowledge/node.py, rag/nlp/search.py}` | [`pipeline/05-reranking-prompt-llm.md`](pipeline/05-reranking-prompt-llm.md) |
-| Prompt 工厂 + 模板 | `api/app/core/rag/prompts/` | 同上 |
-| LLM 调用（流式 + 工具） | `api/app/core/{rag/llm/chat_model.py, agent/langchain_agent.py}` | 同上 |
-| 引用回填 | `api/app/core/rag/nlp/search.py` (`Dealer.insert_citations`) | 同上 |
-| Workflow Knowledge 节点 | `api/app/core/workflow/nodes/knowledge/` | [`pipeline/05-reranking-prompt-llm.md`](pipeline/05-reranking-prompt-llm.md) §3.4 |
-
-> 详细的"源码 → 文档章节"反查请见 [`_indexes/file-index.md`](_indexes/file-index.md)。
-
----
-
-## 文档治理与如何贡献
-
-- **质量标准**：所有文档遵循 [`_meta/document-template.md`](_meta/document-template.md) 模板与 [`_meta/scoring-rubric.md`](_meta/scoring-rubric.md) 5 维评分（≥80 通过）。
-- **审校流程**：作者自检（30min）→ 同行评审（48h）→ 知识运营终审（24h），见 [`_meta/review-sop.md`](_meta/review-sop.md)。
-- **保鲜节奏**：每个 MemoryBear release 同步评审；超过 2 个 release 未更新触发自动归档复审，见 [`_release/ops-and-freshness-plan.md`](_release/ops-and-freshness-plan.md)。
-- **版本号**：遵循语义化版本（v1.0 / v1.1 / v2.0），并在 frontmatter 锁定 `source-commit` SHA。详见 [`_release/versioning-convention.md`](_release/versioning-convention.md)。
-
----
-
-## 反馈与勘误
-
-- 发现源码引用与代码不符：在对应子任务（[WS-12 ~ WS-25](mention://issue/6c0b5472-a0fa-4997-925c-a67f235f82da)）评论中标注，由责任专家修订。
-- 内容缺漏 / 阅读路径建议：在 [WS-24](mention://issue/a07f108d-06ee-41b8-8b57-22455f60ddeb) 评论中提交，由知识运营专家整理进下次保鲜窗口。
-- 安全 / 隐私 / 合规问题：请直接联系工作空间负责人，不要在公开 issue 中详细描述。
-
-— **MemoryBear RAG Docs · v1.0-RC1 · 2026-05-08** —

docs/rag/_indexes/chart-index.md

@@ -1,47 +0,0 @@
-# MemoryBear RAG · 图表索引（Chart Index）
-
-> 全集中所有 Mermaid 图表的集中清单。每张图标注：内容、来源、文件路径、阅读重点。
-
-## 1. 总览
-
-| # | 图表名 | 类型 | 来源任务 | 文件路径 | 一句话描述 |
-|---|---|---|---|---|---|
-| 1 | 全链路架构图 | Mermaid Flowchart | S1-T2 | `overview/01-architecture.mmd` | 11 个 RAG 环节 + 模块映射的全景图 |
-| 2 | 文档入库时序图 | Mermaid Sequence | S1-T2 | `overview/02-indexing-pipeline.mmd` | 上传 → Celery → naive.chunk() → Embedding → ES 写入完整时序 |
-| 3 | 在线检索时序图 | Mermaid Sequence | S1-T2 | `overview/03-query-pipeline.mmd` | Workflow 节点检索 → 4 种模式分支 → 去重/Rerank → Prompt → LLM |
-| 4 | GraphRAG 索引时序图 | Mermaid Sequence | S1-T2 | `overview/04-graphrag-indexing.mmd` | light vs general 两条分支差异 |
-| 5 | 模块依赖图 | Mermaid Graph TB | S1-T3 | `overview/source-inventory.md` §二 | 上层调用者 / RAG Core / 旁路 三层依赖 |
-| 6 | Loader/Parser/Chunking 数据流图 | Mermaid Flowchart LR | S2-T1 | `pipeline/01-loader-parser-chunking.md` §3 | 多源 → 多格式 → Chunking → ES Doc |
-| 7 | 后处理与生成流程图 | ASCII 流程 | S2-T5 | `pipeline/05-reranking-prompt-llm.md` §"实现概览" | Rerank → Prompt → LLM → 后处理 |
-| 8 | 能力地图 | Mermaid（三色） | S3-T2 | `evolution/capability-map.mmd` | 已有（绿）/ 近期可上（黄）/ 中长期愿景（紫） |
-| 9 | 后续迭代路线图甘特图 | Mermaid Gantt | S3-T2 | `evolution/future-extensions-roadmap.md` §4 | Sprint-3 / 短期 / 中期 / 长期 时间线 |
-| 10 | 项目甘特图（总） | Mermaid Gantt | WS-11 主控 | `_release/release-manifest-v1.0-RC1.md` §附录 | 14 子任务的整体计划 |
-
-## 2. 速查：场景 → 应该看哪张图
-
-| 场景 | 推荐图表 | 备注 |
-|---|---|---|
-| 给业务方 / 新人介绍 RAG 链路 | #1 全链路架构图 + #8 能力地图 | 两图配合即可"5 分钟讲清是什么" |
-| 排查"文档为什么没入库" | #2 文档入库时序图 | 找到失败的具体阶段 |
-| 排查"为什么搜不到这个 chunk" | #3 在线检索时序图 + #5 模块依赖图 | 时序图定位调用步骤；依赖图找上下游 |
-| GraphRAG 调试 | #4 GraphRAG 索引时序图 | light/general 差异点 |
-| 评估改造影响面 | #5 模块依赖图 + 本目录 `_indexes/file-index.md` | 看代码 → 文档涟漪 |
-| 给架构会做演进汇报 | #8 能力地图 + #9 后续迭代甘特图 | 现状 + 路线 |
-
-## 3. 图表渲染说明
-
-- **Mermaid 文件 (`.mmd`)**：可直接在 GitHub / Mermaid Live Editor / VS Code Mermaid 插件中渲染。
-- **代码块嵌入图**：直接在 Markdown 渲染器（如 MkDocs Material）打开对应文档即可看到。
-- **未来扩展（建议）**：在 v1.1 时为 `.mmd` 文件配套生成 SVG，挂在 Wiki 上避免 GitHub 渲染限制（当前 GitHub Mermaid 节点上限 1500，建议后续按需拆图）。
-
-## 4. 待补图表（v1.0 → v1.1 计划）
-
-| # | 计划图表 | 来源 | 等待依赖 |
-|---|---|---|---|
-| TBD-1 | E2E 端到端时序图（含 GraphRAG 与 Memory 协同） | S2-T6（待重启） | S2-T1~T5 全部完成 |
-| TBD-2 | GraphRAG light vs general 的内部数据流图 | S2-T4（待重启） | S2-T4 启动 |
-| TBD-3 | "GraphRAG with evidence_path" 时序示意 | S3-T2 D3 落地 | D3 增量图演化第一阶段 |
-| TBD-4 | Memory ↔ RAG 协同时序图 | S3-T2 D4 落地 | D4 PoC-B 实施后回填 |
-| TBD-5 | 散点图：建议 # × 优先级 × 工作量 | S3-T1 + 评审反馈 | S3-T1 终审已完成；散点图作为可选优化 |
-
-— **Chart Index · v1.0-RC1 · 2026-05-08** —

docs/rag/_indexes/file-index.md

@@ -1,166 +0,0 @@
-# MemoryBear RAG · 源码反查索引（File Index）
-
-> 从源码模块反查到对应的文档章节。开发者修改某个文件时，可在此查到所有引用该文件的文档，提前评估改动的"知识涟漪"。
-
-## 1. 总览：代码目录 → 文档映射
-
-| 代码目录 | 主要责任 | 主导文档 | 次要引用 |
-|---|---|---|---|
-| `api/app/core/rag/app/` | 多格式解析 orchestrator | `pipeline/01-loader-parser-chunking.md` | `overview/source-inventory.md` |
-| `api/app/core/rag/common/` | 常量、token、settings | `pipeline/01-loader-parser-chunking.md`, `evolution/architecture-refactor-suggestions.md` §0.2 #4 / #2 | `overview/source-inventory.md` |
-| `api/app/core/rag/crawler/` | Web 爬虫 | `pipeline/01-loader-parser-chunking.md` §4.1 | — |
-| `api/app/core/rag/deepdoc/parser/` | 11 类格式解析 | `pipeline/01-loader-parser-chunking.md` §5 | `overview/source-inventory.md` |
-| `api/app/core/rag/deepdoc/vision/` | OCR + 版面 + TSR | `pipeline/01-loader-parser-chunking.md` §5.6 | `evolution/architecture-refactor-suggestions.md` §0.2 #2（HF_ENDPOINT） |
-| `api/app/core/rag/graphrag/` | GraphRAG 共享工具 + 图搜索 | `pipeline/04-graphrag.md`（待交付） | `overview/source-inventory.md` §3.3 |
-| `api/app/core/rag/graphrag/general/` | Microsoft GraphRAG 风格流水线 | `pipeline/04-graphrag.md` §general（待交付） | `overview/04-graphrag-indexing.mmd` |
-| `api/app/core/rag/graphrag/light/` | LightRAG 风格抽取器 | `pipeline/04-graphrag.md` §light（待交付） | 同上 |
-| `api/app/core/rag/integrations/feishu/` | 飞书 SDK | `pipeline/01-loader-parser-chunking.md` §4 | — |
-| `api/app/core/rag/integrations/yuque/` | 语雀 SDK | 同上 | — |
-| `api/app/core/rag/llm/` | LLM 多模型 facade | `pipeline/05-reranking-prompt-llm.md` §3 | `evolution/architecture-refactor-suggestions.md` #1, #5 |
-| `api/app/core/rag/models/` | Chunk 数据模型 | `pipeline/01-loader-parser-chunking.md` §3 | `overview/source-inventory.md` |
-| `api/app/core/rag/nlp/` | 中文分词、Hybrid 搜索调度 | `pipeline/03-vdb-and-retrieval.md` §6, `pipeline/05-reranking-prompt-llm.md` §1.2 | `evolution/architecture-refactor-suggestions.md` #3 |
-| `api/app/core/rag/prompts/` | Prompt 模板与工厂 | `pipeline/05-reranking-prompt-llm.md` §2 | — |
-| `api/app/core/rag/utils/` | ES/Redis 连接、LibreOffice | `pipeline/03-vdb-and-retrieval.md`, `pipeline/01-loader-parser-chunking.md` §4.2 | — |
-| `api/app/core/rag/vdb/elasticsearch/` | ES 向量+全文 | `pipeline/03-vdb-and-retrieval.md` 全文 | `pipeline/02-embedding.md` §5.4 |
-| `api/app/core/rag/res/` | NER / 同义词 / mapping | `pipeline/03-vdb-and-retrieval.md` §3 | — |
-| `api/app/core/models/` | 统一封装层（Embedding / Rerank / LLM） | `pipeline/02-embedding.md` §1.2, `pipeline/05-reranking-prompt-llm.md` §1.2 | `evolution/architecture-refactor-suggestions.md` #1 |
-| `api/app/core/agent/` | LangChainAgent | `pipeline/05-reranking-prompt-llm.md` §3.4 | — |
-| `api/app/core/workflow/nodes/knowledge/` | Workflow Knowledge 节点 | `pipeline/05-reranking-prompt-llm.md` §3.4, `pipeline/03-vdb-and-retrieval.md` | `evolution/architecture-refactor-suggestions.md` #3 |
-| `api/app/core/rag_utils/`（注意与 `rag/utils` 不同） | Chunk LLM 分析（与 Memory 系统耦合） | `overview/source-inventory.md` §rag_utils | `evolution/future-extensions-roadmap.md` D4 |
-| `api/app/core/memory/` | 对话内存系统（Ebbinghaus / ACT-R / Neo4j / langgraph） | `evolution/future-extensions-roadmap.md` D4（未来扩展引用） | — |
-| `api/app/services/` | 业务服务层 | `pipeline/05-reranking-prompt-llm.md` §3.5 | — |
-| `api/app/tasks.py` | Celery 任务入口 | `overview/source-inventory.md` §3, `pipeline/01-loader-parser-chunking.md` §3.1 | `evolution/future-extensions-roadmap.md` D3 |
-
-## 2. 关键文件 → 文档章节（细粒度）
-
-### `api/app/core/rag/app/naive.py`
-
-| 行号 | 函数 / 关键代码 | 引用文档 |
-|---|---|---|
-| `:27 by_deepdoc()` | DeepDoc 解析路径 | `pipeline/01-loader-parser-chunking.md` §5.1 |
-| `:45 by_mineru()` | MinerU 第三方解析 | 同上 §5.2 |
-| `:65 by_textln()` | TextIn 第三方解析 | 同上 §5.3 |
-| `:257 naive.__call__()` | 主解析入口 | 同上 §3 |
-| `:508-738 chunk()` | 11 路 if/elif 分发，按扩展名挑 parser | 同上 §3, `evolution/architecture-refactor-suggestions.md` §0.2 #5 / #5 改造建议 |
-
-### `api/app/core/rag/llm/embedding_model.py`
-
-| 行号 | 类 / 函数 | 引用文档 |
-|---|---|---|
-| `:14-38 Base` | Embedding 抽象基类（旧） | `pipeline/02-embedding.md` §5.1 |
-| `:50-65 OpenAIEmbed.encode()` | OpenAI 兼容 Embedding 实现 | 同上 §5.2, `evolution/architecture-refactor-suggestions.md` #1 / #4 / #9 |
-| `:138-143 QWenEmbed` | DashScope Embedding（含显式 5 次重试） | `pipeline/02-embedding.md` §3.2 |
-
-### `api/app/core/models/embedding.py`
-
-| 行号 | 类 / 函数 | 引用文档 |
-|---|---|---|
-| `:9-23 RedBearEmbeddings.__init__` | LangChain 统一封装初始化 | `pipeline/02-embedding.md` §1.2 / §5.3 |
-| `:65-78 embed_documents()` | 文档侧 Embedding（含火山多模态分支） | 同上 §2.1 |
-
-### `api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py`
-
-| 行号 | 类 / 函数 | 引用文档 |
-|---|---|---|
-| `:29 ElasticSearchVector` | ES 向量主实现 | `pipeline/03-vdb-and-retrieval.md` §1 |
-| `:55-63 add_chunks()` | 向量入库 | 同上 §4, `pipeline/02-embedding.md` §2.1, `evolution/architecture-refactor-suggestions.md` #4 |
-| `:374-380 search_by_vector()` | 向量检索 | `pipeline/03-vdb-and-retrieval.md` §6, `pipeline/02-embedding.md` §2.2 |
-| `:468 search_by_full_text()` | BM25 检索 | `pipeline/03-vdb-and-retrieval.md` §5 |
-| `:560-607 rerank()` | ES 层 rerank | `pipeline/05-reranking-prompt-llm.md` §1.2 D, `evolution/architecture-refactor-suggestions.md` #3 |
-| `:653-658 dense_vector mapping` | dense_vector 维度动态决定 | `pipeline/02-embedding.md` §3.4, `pipeline/03-vdb-and-retrieval.md` §3 |
-| `:666 ElasticSearchVectorFactory` | 工厂类 | `overview/source-inventory.md`, `pipeline/03-vdb-and-retrieval.md` §1 |
-| `:685-707 ES 配置环境变量` | 6 个 ES 相关 env vars | `evolution/architecture-refactor-suggestions.md` §0.2 #2 |
-
-### `api/app/core/rag/nlp/search.py`
-
-| 行号 | 类 / 函数 | 引用文档 |
-|---|---|---|
-| `:36-147 knowledge_retrieval()` | 知识检索入口（旧通道） | `pipeline/05-reranking-prompt-llm.md` §1.2 |
-| `:284-343 rerank()` | 模块级 rerank | 同上 |
-| `:349 Dealer` | BM25/Hybrid 调度器 | `pipeline/03-vdb-and-retrieval.md` §6, `overview/source-inventory.md` §一 |
-| `:365-373 get_vector()` | 调用旧 Embedding 接口的 `encode_queries` | `pipeline/02-embedding.md` §2.4 |
-| `:387 search()` | 主 search | `pipeline/03-vdb-and-retrieval.md` §6 |
-| `:439 FusionExpr("weighted_sum")` | 0.05/0.95 硬编码权重 | `pipeline/03-vdb-and-retrieval.md` §6, `evolution/future-extensions-roadmap.md` D2 |
-| `:489-577 insert_citations()` | 引用回填（embedding 相似度匹配） | `pipeline/05-reranking-prompt-llm.md` §4.1 |
-| `:579-604 _rank_feature_scores()` | tag TF-IDF + PageRank | `pipeline/05-reranking-prompt-llm.md` §1.2 A |
-| `:606-643 Dealer.rerank()` | 内置混合 rerank（融合分数） | 同上, `evolution/architecture-refactor-suggestions.md` #3 |
-| `:645-666 rerank_by_model()` | 外部模型 rerank | `pipeline/05-reranking-prompt-llm.md` §1.2 B |
-| `:674-768 retrieval()` | 检索主流程 | 同上 §1.3 |
-
-### `api/app/core/workflow/nodes/knowledge/node.py`
-
-| 行号 | 类 / 函数 | 引用文档 |
-|---|---|---|
-| `:12 import OpenAIEmbed` | 硬编码导入旧 Embedding 类 | `evolution/architecture-refactor-suggestions.md` #1 |
-| `:14 import ElasticSearchVectorFactory` | 绕过 BaseVector 抽象 | 同上 §0.2 #1 / #2 改造建议 |
-| `:29 KnowledgeRetrievalNode` | Workflow 节点主类 | `pipeline/05-reranking-prompt-llm.md` §3.4 |
-| `:54 _extract_input()` | 渲染 query 模板 | 同上 |
-| `:108-155 KnowledgeRetrievalNode.rerank()` | 节点级 rerank | 同上 §1.2 C, `evolution/architecture-refactor-suggestions.md` #3 |
-| `:157-193 get_reranker_model()` | 每次调用都查 DB | `evolution/architecture-refactor-suggestions.md` §0.2 #4 |
-| `:195-263 knowledge_retrieval()` | 检索分支（PARTICIPLE / SEMANTIC / HYBRID / Graph） | `pipeline/05-reranking-prompt-llm.md` §3.4, `pipeline/03-vdb-and-retrieval.md` |
-| `:236-271 HYBRID 分支` | vector + full_text 并行 → dedup → rerank | 同上 |
-| `:284 rerank()` 模块级函数 | 三轨 rerank 之一 | `evolution/architecture-refactor-suggestions.md` #3 |
-| `:303-378 execute()` | 节点执行入口 | `pipeline/05-reranking-prompt-llm.md` §3.4 |
-| `:327 print(reranked_docs)` ⚠️ | 调试残留 | `evolution/architecture-refactor-suggestions.md` #3 / #10（hot-fix 候选） |
-
-### `api/app/core/rag/graphrag/`
-
-| 行号 | 类 / 函数 | 引用文档 |
-|---|---|---|
-| `general/index.py:36 run_graphrag()` | GraphRAG 主入口（doc 级） | `pipeline/04-graphrag.md` §general（待交付） |
-| `general/index.py:122 run_graphrag_for_kb()` | KB 级 | 同上 |
-| `general/graph_extractor.py:34 GraphExtractor` | Microsoft 风格抽取 | 同上 |
-| `general/community_reports_extractor.py:37` | 社区报告 | 同上 |
-| `light/graph_extractor.py:31 GraphExtractor` | LightRAG 风格抽取 | 同上 §light |
-| `entity_resolution.py:31 EntityResolution` | 实体消歧 | 同上 |
-| `search.py:19 KGSearch` | 图检索 | 同上 |
-| `utils.py:41 chat_limiter` | Trio 限流 | `pipeline/02-embedding.md` §3.1, `evolution/architecture-refactor-suggestions.md` #9 |
-| `utils.py:115-134 get/set_embed_cache` | Redis Embedding 缓存 | `pipeline/02-embedding.md` §3.3, `evolution/architecture-refactor-suggestions.md` #4 |
-| `utils.py:301-327 graph_node_to_chunk()` | 实体节点 → 向量 → ES | `pipeline/02-embedding.md` §2.3 |
-
-### `api/app/core/rag/llm/chat_model.py`
-
-| 行号 | 类 / 函数 | 引用文档 |
-|---|---|---|
-| `:52 Base` | LLM 抽象基类 | `pipeline/05-reranking-prompt-llm.md` §3.1 |
-| `:54-58 LLM_TIMEOUT_SECONDS / LLM_MAX_RETRIES` | 超时与重试 | 同上 §3.3, `evolution/architecture-refactor-suggestions.md` §0.2 #2 |
-| `:122-150 _chat()` | 非流式 LLM 调用 | `pipeline/05-reranking-prompt-llm.md` §3.2 |
-| `:152-185 _chat_streamly()` | 流式 LLM 调用 | 同上 |
-| `:251-303 chat_with_tools()` | 工具调用 | 同上 §3.4 |
-
-### `api/app/core/rag/prompts/`
-
-| 文件 | 功能 | 引用文档 |
-|---|---|---|
-| `template.py:9 load_prompt()` | 启动时加载 .md 模板 | `pipeline/05-reranking-prompt-llm.md` §2.1 |
-| `generator.py` | 20+ Prompt 工厂函数（citation/keyword/...） | 同上 |
-| `*.md`（31 个模板） | Prompt 内容 | `overview/source-inventory.md` |
-
-### `api/app/core/rag/common/settings.py`
-
-| 行号 | 关键代码 | 引用文档 |
-|---|---|---|
-| `:9-10 retriever / kg_retriever` | 进程级单例 | `evolution/architecture-refactor-suggestions.md` §0.2 #4 |
-| `:13 init_settings()` | 模块导入时副作用 | 同上, `pipeline/03-vdb-and-retrieval.md` |
-| `:24` 触发位置 | — | `evolution/architecture-refactor-suggestions.md` #8 |
-
-### `api/app/services/draft_run_service.py`
-
-| 行号 | 关键代码 | 引用文档 |
-|---|---|---|
-| `:195-263 create_knowledge_retrieval_tool()` | 知识检索工具 | `pipeline/05-reranking-prompt-llm.md` §3.5 |
-| `:227-255` chunk 拼接 | `\n\n` 分隔 chunks | 同上 §2.3 |
-| `:474-490 _filter_citations()` | 引用过滤 + 下载链接 | 同上 §4.2 |
-
-## 3. 当前已识别的"代码残留与修复任务"
-
-| # | 文件:行 | 问题 | 修复建议 | 关联 |
-|---|---|---|---|---|
-| 1 | `workflow/nodes/knowledge/node.py:327` | `print(reranked_docs)` 调试残留 | 立即提 hot-fix PR 删除 | S3-T1 #10 + S3-T1 §3.1 |
-| 2 | `chat_model.py` 各 provider 子类 | base_url 与认证 header 硬编码 | 引入 Plugin Registry | S3-T1 #5 |
-| 3 | `naive.py:508-738 chunk()` | 11 路 if/elif 硬编码 | 抽 `Parser` Protocol | S3-T1 #5 |
-| 4 | `elasticsearch_vector.py:55-63 add_chunks` | 同步循环，无并发 | 改 trio 协程 + 共享 chat_limiter | S3-T1 #9 |
-| 5 | `nlp/search.py:439` | `weighted_sum` 0.05/0.95 硬编码 | 改为 ctx.fusion_weights 注入 | S3-T2 D2 |
-| 6 | `rag_utils/` vs `rag/utils/` | 命名冲突 | 重命名为 `rag/chunk_analytics/` 或合并 | S1-T3 §4.1 |
-
-— **File Index · v1.0-RC1 · 2026-05-08** —

docs/rag/_indexes/glossary.md

@@ -1,198 +0,0 @@
-# MemoryBear RAG · 关键术语表
-
-> 合并 Sprint-1 / Sprint-2 / Sprint-3 各文档术语，按字母顺序排列。
-> 每个术语注明：含义 + 在 MemoryBear 代码中的对应位置 + 出现的文档。
-
-## A
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **ASR** | Automatic Speech Recognition，语音转文字。MemoryBear 中通过 `seq2txt_model.transcription` 调用（QWenSeq2txt 带时间戳，GPTSeq2txt 用 Whisper） | `rag/llm/sequence2txt_model.py:1-215` | S2-T1, S2-T5 |
-| **Autopilot** | 工作空间内的"按时触发 / 按事件触发"自动化代理；与 `multica autopilot` 命令族对应 | — | 平台机制（项目 SOP） |
-
-## B
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **BaseVector** | VDB 抽象基类（仅定义抽象方法，目前唯一实现为 `ElasticSearchVector`） | `rag/vdb/vector_base.py:9` | S1-T3, S2-T3, S3-T1 |
-| **BM25** | Best Match 25，全文检索经典 ranking 函数；MemoryBear 通过 ES `query_string` + IK 分词器实现 | `rag/nlp/query.py`, `rag/vdb/elasticsearch/elasticsearch_vector.py:468 search_by_full_text` | S2-T3, S3-T2 |
-| **Boundaries** | 11 个 RAG 阶段的输入/输出/接口契约文档（S1-T2 交付物之一） | — | S1-T2 |
-
-## C
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **Celery** | 任务队列；MemoryBear 用它派发文档解析、GraphRAG 构建等异步流水线 | `tasks.py:212 parse_document`, `tasks.py:472 build_graphrag_for_kb`, `tasks.py:557 build_graphrag_for_document` | S1-T3, S2-T1, S2-T3, S3-T2 |
-| **chat_limiter** | Trio CapacityLimiter，控制 GraphRAG 中实体/关系 Embedding 的并发；默认 10 | `rag/graphrag/utils.py:41` | S2-T2, S3-T1 |
-| **Chunk** | 最终交给 Embedding 的文本片段，一般 ≤ `chunk_token_num`（默认 128–512） | `rag/models/chunk.py:17 DocumentChunk` | S2-T1, S2-T2, S2-T3 |
-| **chunk_token_num** | 单个 chunk 的最大 token 数 | `rag/app/naive.py` 调用层指定 | S2-T1 |
-| **citation** | 答案文本中插入的 `[ID:N]` 引用标记 | `rag/nlp/search.py:489-577 Dealer.insert_citations` | S2-T5 |
-| **CLIP / BGE-VL / Jina-Clip** | 跨模态 Embedding 模型，把图像和文本映射到同一语义空间 | 当前未启用，规划见 S3-T2 D1 | S3-T2 |
-| **cl100k_base** | OpenAI GPT-4 系列使用的 BPE tokenizer；MemoryBear 用它做 token 计数 | `rag/common/token_utils.py` | S2-T1, S2-T2 |
-| **Cross-Encoder** | 一种 Reranker 范式：把 (query, doc) 拼接后过同一个 Encoder，输出相关性分数 | 当前未自训，仅在外部 rerank 服务（DashScope/Jina）调用，规划见 S3-T2 D5 | S2-T5, S3-T2 |
-
-## D
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **Dealer** | `rag/nlp/search.py:349 Dealer` 类，BM25/hybrid 搜索调度器；GraphRAG 主要使用此通道 | `rag/nlp/search.py:349` | S1-T3, S2-T3, S2-T5, S3-T1 |
-| **deepdoc** | MemoryBear 的多格式解析模块，含 parser（11 种格式）+ vision（OCR / 版面识别 / TSR） | `rag/deepdoc/{parser,vision}` | S1-T3, S2-T1 |
-| **DocumentChunk** | Chunk 数据模型 | `rag/models/chunk.py:17` | S2-T1, S2-T2, S2-T3 |
-| **dense_vector** | ES 向量字段类型；MemoryBear 用 HNSW 索引 + cosine 相似度 | `elasticsearch_vector.py:653-658`, `rag/res/mapping.json` | S2-T2, S2-T3 |
-
-## E
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **E2E（End-to-End）** | 端到端调用链路，覆盖文档入库 + 在线检索 + 生成的完整时序 | `rag/app/`, `workflow/nodes/knowledge/`, `rag/llm/` | S2-T6（待交付） |
-| **Embedder** | Embedding 模型抽象接口（S3-T1 提议的统一 Protocol） | 提议中：`app/core/rag/protocols/embedder.py` | S3-T1, S3-T2 |
-| **Embedding 双轨** | MemoryBear 当前同时存在两条 Embedding 调用路径：`RedBearEmbeddings`（LangChain，新）与 `OpenAIEmbed/QWenEmbed/...`（遗留） | `rag/models/embedding.py` + `rag/llm/embedding_model.py` | S2-T2, S3-T1 |
-| **embed_cache** | GraphRAG 中的实体/关系 Embedding Redis 缓存，TTL 24h | `rag/graphrag/utils.py:115-134` | S2-T2, S3-T1 |
-| **EMBEDDING_BATCH_SIZE** | 批量 Embedding 大小的环境变量（README 提及但当前未生效） | — | S2-T2, S3-T1 |
-| **Entity Resolution** | 实体消歧；GraphRAG 索引流程的一环 | `rag/graphrag/entity_resolution.py:31` | S1-T3 |
-| **ESConnection** | ES 连接单例 | `rag/utils/es_conn.py` | S1-T3, S2-T3 |
-| **ElasticSearchVector** | VDB 主实现；同时承载 chunk + GraphRAG entity/relation + community_report | `rag/vdb/elasticsearch/elasticsearch_vector.py:29` | S1-T3, S2-T3, S3-T1 |
-
-## F
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **FOLDER 类型知识库** | 包含子知识库的文件夹型 KB；检索时递归遍历 | `workflow/nodes/knowledge/node.py` | S1-T3 |
-| **FusionExpr** | ES 检索中的"加权融合"DSL；当前固定 `0.05/0.95`（BM25:Vector） | `rag/nlp/search.py:439` | S2-T3, S3-T2 |
-
-## G
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **GraphRAG（general）** | Microsoft GraphRAG 风格：完整流水线（子图 → 合并 → PageRank → Leiden 社区 → 社区报告） | `rag/graphrag/general/index.py:36 run_graphrag` | S1-T2, S1-T3 |
-| **GraphRAG（light）** | LightRAG 风格：简化的实体/关系抽取，无社区报告；与 general 共享大部分代码 | `rag/graphrag/light/graph_extractor.py:31` | S1-T2, S1-T3 |
-| **GraphStore** | 图存储抽象（S3-T2 提议） | 提议中 | S3-T2 |
-| **GraphAugmentedRetriever** | 在 Hybrid 结果之上叠加 KGSearch 的 Retriever 实现 | 提议中 | S3-T1, S3-T2 |
-
-## H
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **HNSW** | Hierarchical Navigable Small World，向量索引算法；ES 8.x 内置 | ES 集群侧 | S2-T3 |
-| **HYBRID 检索** | BM25 + 向量并行 → 去重 → 可选 Rerank | `workflow/nodes/knowledge/node.py:236-271` | S2-T3, S2-T5 |
-| **HybridRetriever** | Hybrid 检索 Protocol 实现（S3-T1 PoC） | 提议中 | S3-T1 |
-
-## I
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **IK 分词器** | 中文分词器，ES IK plugin（`ik_max_word`） | ES 集群侧 | S2-T3 |
-| **init_settings()** | 模块级副作用，启动时自动建 ES 连接 + retriever 单例 | `rag/common/settings.py:24` | S1-T3, S3-T1 |
-| **insert_citations** | 答案分句后按 embedding 相似度回填 `[ID:N]` 引用 | `rag/nlp/search.py:489-577` | S2-T5 |
-
-## K
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **KGSearch** | GraphRAG 检索器 | `rag/graphrag/search.py:19` | S1-T3, S3-T2 |
-| **knowledge_graph_kwd** | ES 中区分图类型（entity / relation / community_report）的字段 | `rag/vdb/elasticsearch/elasticsearch_vector.py` | S1-T3 |
-| **KnowledgeRetrievalNode** | Workflow 引擎中的知识检索节点 | `workflow/nodes/knowledge/node.py:29` | S1-T3, S2-T5, S3-T1 |
-
-## L
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **LangChainAgent** | 基于 `create_agent` 的 ReAct Agent，工具调用循环 | `agent/langchain_agent.py:26-641` | S2-T5 |
-| **Late-Interaction** | 一种检索范式（如 ColBERT），文档级向量改为 token 级，retrieval 用 MaxSim | 当前未启用，规划见 S3-T2 D2 | S3-T2 |
-| **Leiden 算法** | 社区检测算法；GraphRAG 用它划分社区 | `rag/graphrag/general/index.py` 调用 `graspologic.partition.leiden` | S1-T2, S1-T3 |
-| **LightRAG** | GraphRAG 轻量化变种，无社区报告 | `rag/graphrag/light/` | S1-T2, S1-T3 |
-| **LLM** | Large Language Model；MemoryBear 通过 `chat_model.py` 与 `langchain_agent.py` 调用 | `rag/llm/chat_model.py:52 Base` | S2-T5 |
-| **LO（LibreOffice）** | 用作 PPT/PPTX 转 PDF 的兜底工具 | `rag/utils/libre_office.py` | S2-T1 |
-
-## M
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **MatchSparseExpr / Field.SPARSE_VECTOR** | 已声明未启用的稀疏向量表达式（SPLADE 接入预埋） | `rag/utils/doc_store_conn.py:75`, `vdb/field.py:11` | S3-T2 |
-| **Memory（记忆系统）** | MemoryBear 的对话内存系统：Ebbinghaus 衰减 + ACT-R + Neo4j + langgraph 读写图 | `core/memory/`（与 `core/rag/` 当前完全独立） | S3-T2 D4 |
-| **MemoryAugmentedRetriever** | D4 提议：在检索前用长期记忆改写 query 的 Retriever 包装层 | 提议中 | S3-T2 D4 |
-| **mind_map_extractor** | 独立运行的思维导图抽取器，不在 GraphRAG 主链路 | `rag/graphrag/mind_map_extractor.py` | S1-T2 |
-| **MinerU** | 第三方 PDF 解析服务（外部 API） | `rag/deepdoc/parser/mineru_parser.py:41`, `rag/app/textin_parser.py` | S1-T3, S2-T1 |
-| **Multimodal Embedding** | 多模态 Embedding；MemoryBear 仅火山引擎支持原生多模态 | `rag/models/embedding.py:65-78` 中 `_is_volcano` 分支 | S2-T2, S3-T2 D1 |
-
-## N
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **naive_merge / hierarchical_merge / tree_merge** | 三种 Chunking 合并策略 | `rag/nlp/__init__.py` | S2-T1 |
-| **Neo4j** | 图数据库；README 声明依赖，但 `core/rag` 当前零调用（规划见 S3-T2 D3） | — | S3-T2 |
-
-## O
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **OCR** | 文字检测 + 识别两阶段 | `rag/deepdoc/vision/ocr.py:522 OCR.__call__:694` | S2-T1 |
-| **OpenAIEmbed / QWenEmbed / ...** | 遗留的原始 Embedding 实现，被 GraphRAG 与 Dealer 使用 | `rag/llm/embedding_model.py:14-65` | S2-T2, S3-T1 |
-| **OpenTelemetry (OTel)** | 全链路追踪 + 指标 SDK；MemoryBear 当前未引入（规划见 S3-T1 #6） | 提议中 | S3-T1 |
-
-## P
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **PageRank** | 图节点重要性算法；GraphRAG 用它给实体打分 | `rag/graphrag/general/index.py` | S1-T2, S1-T3 |
-| **PARTICIPLE 检索** | 关键词分词检索（BM25） | `workflow/nodes/knowledge/node.py:195` | S2-T3 |
-| **Plugin Registry** | S3-T1 #5 提议的 Parser/LLM Provider 注册机制，替换 `naive.py` 11 路 if/elif | 提议中 | S3-T1 |
-| **Pydantic Settings** | S3-T1 #7 提议的中心化配置管理框架 | 提议中 | S3-T1 |
-
-## R
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **rag_utils（注意：与 `rag/utils` 不同）** | Chunk 内容 LLM 分析模块（摘要/标签/洞察/人物画像）；与 Memory 系统耦合 | `api/app/core/rag_utils/` | S1-T3 |
-| **RAGAS** | 开源 RAG 评估框架；MemoryBear 当前未集成 | 提议中 | S3-T2 D5 |
-| **rank_feature** | ES 中的 tag TF-IDF + PageRank 辅助排序分 | `rag/nlp/search.py:579-604` | S2-T5 |
-| **RedBearEmbeddings** | LangChain 统一封装的 Embedding 类（新路径） | `rag/models/embedding.py:9-23` | S2-T2 |
-| **RedBearRerank** | LangChain `BaseDocumentCompressor` 封装的 Reranker | `rag/models/rerank.py:11-84` | S2-T5, S3-T2 |
-| **Rerank 三轨** | (a) `node.py:284 rerank()` 模块级；(b) `KnowledgeRetrievalNode.rerank()` 节点方法；(c) `Dealer.rerank()` 融合排序 | `node.py:108-155, 284`、`nlp/search.py:606-643` | S2-T5, S3-T1 |
-| **Reranker** | Reranking Protocol（S3-T1 提议） | 提议中 | S3-T1, S3-T2 |
-| **retrieve_type** | 检索模式 enum：PARTICIPLE / SEMANTIC / HYBRID / Graph | `schemas/chunk_schema.py` | S2-T3, S3-T2 |
-| **Retriever** | 检索器 Protocol（S3-T1 提议） | 提议中 | S3-T1, S3-T2 |
-| **RouterRetriever** | 自适应路由 Retriever（S3-T2 D6 提议） | 提议中 | S3-T2 |
-| **RRF（Reciprocal Rank Fusion）** | 多路检索结果排序融合算法；S3-T2 PoC-A 提议接入 | 提议中 | S3-T2 |
-
-## S
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **SEMANTIC 检索** | 纯向量检索 | `workflow/nodes/knowledge/node.py:195` | S2-T3 |
-| **Section** | 解析器吐出的 `(text, position_or_layout)` 中间结构，是 Chunking 的"原料" | `rag/app/naive.py:257` | S2-T1 |
-| **SPLADE** | 学习型稀疏向量；S3-T2 D2 提议接入 | 提议中（脚手架已存：`MatchSparseExpr`） | S3-T2 |
-| **structlog** | 结构化日志库；S3-T1 #10 提议替换现有非结构化 `logger.*` | 提议中 | S3-T1 |
-| **System Prompt 组装** | "用户自定义 system_prompt + 技能 Prompt + 文档图片识别指令"三段拼接 | `app_chat_service.py:77-96` | S2-T5 |
-
-## T
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **TextIn** | 第三方 PDF 解析 API | `rag/app/textin_parser.py` | S1-T3 |
-| **Token** | 用 cl100k_base 编码后的 BPE token | `rag/common/token_utils.py` | S2-T1, S2-T2 |
-| **tokenize_chunks_with_images** | 带图片的 Chunk 化处理 | `rag/nlp/__init__.py` | S2-T1 |
-| **TSR** | Table Structure Recognition，复杂表格行/列/合并单元格还原 | `rag/deepdoc/vision/table_structure_recognizer.py:15` | S2-T1 |
-
-## V
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **VDB（Vector Database）** | 向量数据库；MemoryBear 当前唯一实现是 Elasticsearch 8.x | `rag/vdb/elasticsearch/` | S2-T3 |
-| **VectorBase** | 见 BaseVector | `rag/vdb/vector_base.py:9` | — |
-| **VLM** | Vision-Language Model；图像理解（CV 模型） | `rag/llm/cv_model.py` | S2-T1 |
-
-## W
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **weighted_sum (0.05, 0.95)** | ES 层 Hybrid 检索的固定权重（BM25:Vector） | `rag/nlp/search.py:439` | S2-T3, S3-T2 |
-| **Workflow Knowledge Node** | 见 KnowledgeRetrievalNode | `workflow/nodes/knowledge/node.py:29` | S1-T3, S2-T5 |
-
-## X
-
-| 术语 | 含义 | 代码位置 | 出现文档 |
-|---|---|---|---|
-| **xxhash** | 快速哈希函数；用于 GraphRAG embed_cache 的 key 生成 | `rag/graphrag/utils.py:115-134` | S2-T2 |
-
-— **Glossary · v1.0-RC1 · 共 81 个术语 · 2026-05-08** —

docs/rag/_meta/README.md

@@ -1,33 +0,0 @@
----
-title: "_meta/ — 治理资产（待补全）"
-status: 占位（待回填）
-source-issue: WS-12 / [S1-T1]
-last-reviewed-at: 2026-05-09
----
-
-# _meta/ — 治理资产（待回填）
-
-本目录用于存放 RAG 文档项目的治理资产（统一模板、评分卡、SOP、命名规范等），由 [WS-12 / S1-T1] 任务交付。
-
-## 状态
-
-[S1-T1] 任务的交付物在 [WS-12 评论 `93ea1f50`](mention://issue/b1ead19b-920b-494b-95b5-ab2057d4dd14) 中已声明完成（写入 agent 工作分支），但相关文件未持久化到 main 分支与本仓库 `docs/rag/` 目录树。本次 v1.0 文档全集提交时，按 [WS-26](mention://issue/5c12d0a3-89ea-4e92-adb4-d98eddfa3eab) 用户指示将仓库迁移到 `git.poflow.cn:30010/adai/MemoryBear.git`，本目录暂作占位，后续回填。
-
-## 应有内容（按 [`../INDEX.md`](../INDEX.md) §2 责任矩阵）
-
-| 文件 | 内容 | 责任人 |
-|---|---|---|
-| `README.md` | 治理体系总览，含 8 环节与代码目录映射速查表 | 知识运营与治理专家 |
-| `document-template.md` | 统一文档模板（覆盖 8 个 RAG 环节，9 大章节结构） | 同上 |
-| `scoring-rubric.md` | 质量评分卡（5 维度 / 100 分制 / 通过线 80） | 同上 |
-| `review-sop.md` | 审校流程 SOP（自检 → 同行 → 终审） | 同上 |
-| `directory-naming-spec.md` | 目录与命名规范（frontmatter 规范） | 同上 |
-| `rubric-scoresheet.md` | 评分记录表模板（Sprint-2 评分预置） | 同上 |
-
-## 回填路径建议
-
-1. **首选**：从 [@知识运营与治理专家](mention://agent/7e9211a6-41eb-429e-9dd1-4c7afcffd412) 的本地工作目录恢复并提交。
-2. **次选**：基于 [WS-12 评论 `93ea1f50`](mention://issue/b1ead19b-920b-494b-95b5-ab2057d4dd14) 中描述的设计决策与各文件大纲，由知识运营重新生成（约 0.5–1 个工作日）。
-3. **快速兜底**：参考 [`../_indexes/glossary.md`](../_indexes/glossary.md) 与 [`../_release/versioning-convention.md`](../_release/versioning-convention.md) 中已沉淀的部分约束（如版本号约定、frontmatter 字段），先建立最小可用版本。
-
-完整回填后，请同步更新 [`../INDEX.md`](../INDEX.md) §3 状态汇总（占位计数 −5 → 已交付 +5）。

docs/rag/_release/ops-and-freshness-plan.md

@@ -1,165 +0,0 @@
-# MemoryBear RAG Docs · 运营与保鲜计划
-
-> **目标**：让 `docs/rag/` 不沦为"上线那天的快照"，而是与 MemoryBear 一同进化的活水。
-> **责任主线**：知识运营与治理专家牵头，与 PM / AI 知识库专家 / Python 工程师协同。
-
-## 1. 保鲜原则（Why）
-
-> 一句话：**代码会跑，文档会过期；过期速度比新代码合并的速度还快。**
-
-- **失效快**：MemoryBear 在 Sprint-3 内合并的关键改造（如 Reranker 缓存、Embedder Protocol、`node.py:327 print` 删除）会在 1-2 周内让相关文档章节失同步。
-- **影响大**：本套文档是 toB 客户、二次开发者、内部 oncall 的"事实来源"；与代码不一致会直接误导决策。
-- **维护成本可控**：用统一的"评审 + 增量更新 + 自动归档"三段式机制，把维护成本摊到每次 release，而不是堆在年度大修。
-
-## 2. 保鲜节奏（When）
-
-### 2.1 与 release 同步评审（强制）
-
-每次 MemoryBear 主仓发 release（语义化版本 `v0.x.y`）时：
-
-| 时点 | 动作 | 责任人 |
-|---|---|---|
-| **release 准备期 -7d** | 自动扫描：`git diff <last-release-tag>..HEAD -- 'api/app/core/rag/**'` 列出受影响文件 | PM 或脚本 |
-| **release 准备期 -5d** | 知识运营对受影响文件清单进行"文档涟漪映射"（用 `_indexes/file-index.md`） | 知识运营 |
-| **release 准备期 -3d** | 责任专家修订对应文档章节（最低粒度：源码引用行号、配置项默认值、流程描述） | AI 知识库 / Python 工程 |
-| **release day** | 知识运营终审；通过后将 `source-commit` 刷到新 commit | 知识运营 |
-| **release day +1d** | 在 `evolution/CHANGELOG.md`（v1.1 起新增）写入"对应 MemoryBear `v0.x.y` 的文档增量" | 知识运营 |
-
-### 2.2 季度全量复审（强制）
-
-每季度（3 / 6 / 9 / 12 月末）做一次"对所有文档的轻量复审"：
-
-| 步骤 | 内容 |
-|---|---|
-| 1 | 抽样 30%（每类文档至少 1 篇）做"源码引用一致性"抽查（用 `_indexes/file-index.md` 对应行号 grep ±3 行） |
-| 2 | 检查每个文档的 `last-reviewed-at`，超过 3 个月的标记为"待复审" |
-| 3 | 评分（按 5 维卡），低于 75 的文档启动 Should-Fix 流程；低于 60 的文档启动 Must-Fix |
-| 4 | 季度报告（约 1 页）发到 [WS-11](mention://issue/6c0b5472-a0fa-4997-925c-a67f235f82da) 作为里程碑通告 |
-
-### 2.3 用户反馈驱动评审（按需）
-
-任何外部读者（开发者、客户）在子任务 issue 中反馈"文档与代码不一致"或"文档不清楚"，触发：
-
-- **24h 内**：知识运营响应 + 复核
-- **48h 内**：责任专家修订或返回澄清
-- **保留**：作为评审记录留在子任务评论中，季度报告时统计"反馈密度"作为质量指标
-
-## 3. 保鲜机制（How）
-
-### 3.1 责任矩阵
-
-| 文档类别 | 主责（修订） | 终审 | 升版决定 |
-|---|---|---|---|
-| `_meta/` 治理资产 | 知识运营 | 知识运营自审 | 知识运营 |
-| `overview/` 总览 | AI 知识库 | 知识运营 | 联合 |
-| `pipeline/` 各环节 | Python 工程 | 知识运营 | 联合 |
-| `graphrag/` GraphRAG | Python 工程 | 知识运营 | 联合 |
-| `end-to-end/` E2E | AI 知识库 | 知识运营 | 联合 |
-| `evolution/` 演进 | AI 知识库 | 知识运营 | 联合 |
-| `review/` 评审报告 | 知识运营 | 知识运营自审 | 知识运营 |
-| `_indexes/` 索引 | 知识运营 | 知识运营自审 | 知识运营 |
-| `_release/` 发布 | 知识运营 | 知识运营自审 + PM | 知识运营 + PM |
-
-### 3.2 过期判定规则（自动 + 人工）
-
-文档进入"过期候选"状态满足以下**任一**：
-
-| 触发条件 | 判定 |
-|---|---|
-| `last-reviewed-at` 距今 ≥ 90 天且 `source-commit` 与当前 main HEAD 差距 ≥ 50 commits | 自动标记 |
-| 用户反馈"文档与代码不一致"且复核成立 | 立即标记 |
-| 文档关联的代码模块在 release 中有变更（用 `git diff` 检测） | 自动标记 |
-| 文档评分 < 80 且未在 14 天内启动修订 | 自动标记 |
-
-> 标记后进入 [`_release/freshness-queue.md`](freshness-queue.md)（v1.1 起新建）。每周一上午 PM 在 [WS-11](mention://issue/6c0b5472-a0fa-4997-925c-a67f235f82da) 评论"本周保鲜任务"通告。
-
-### 3.3 修订流程（强制走 SOP）
-
-所有修订都要遵循 `_meta/review-sop.md`：
-
-1. **作者自检** ≤ 30 min（用 `_meta/scoring-rubric.md`）
-2. **同行评审** ≤ 48 h（≥ 同 Sprint 1 名其他作者）
-3. **知识运营终审** ≤ 24 h
-4. 通过 → 合并 PR；未通过 → 退回作者，最多 2 轮
-
-> 紧急 hot-fix（如调试 print 残留、源码引用错误）可走"快速通道"：直接知识运营 + PM 双人共审 ≤ 4 h，事后补同行评审记录。
-
-### 3.4 归档机制
-
-- 文档被替换或并入新文档时：保留 6 个月，再迁移到 `docs/rag/_archive/<year>/`。
-- 归档保留可读性（保留 frontmatter 的 `status: deprecated`），**不删除**。
-- 季度报告中列出"本季归档清单"。
-
-## 4. 关键指标（Metric）
-
-### 4.1 内容质量指标
-
-| 指标 | 目标 | 测量方式 |
-|---|---|---|
-| 文档评分均值 | ≥ 85 | 季度评审打分 |
-| 评审通过率（一次过） | ≥ 75% | 季度评审统计 |
-| 源码引用一致率（抽查） | 100% | 季度抽样 30% × ±3 行 grep |
-| 失效文档占比（last-reviewed-at > 6 月） | ≤ 10% | 自动扫描 |
-
-### 4.2 使用与反馈指标
-
-| 指标 | 目标 | 测量方式 |
-|---|---|---|
-| 月活读者（PV） | TBD（v1.1 起埋点） | Wiki 自带统计 |
-| 用户反馈数（季度） | ≥ 5 条 | 子任务 issue 评论统计 |
-| 反馈解决率（30 天内闭环） | ≥ 90% | issue 状态统计 |
-| 搜索无结果率（"用户搜了什么找不到"） | ≤ 5% | Wiki 搜索日志（v1.2 起） |
-
-### 4.3 协作健康指标
-
-| 指标 | 目标 | 测量方式 |
-|---|---|---|
-| 修订到合并的中位时间 | ≤ 3 天 | PR 数据 |
-| 紧急 hot-fix 数量（季度） | ≤ 2 | issue 标签统计 |
-| 评审反馈采纳率 | ≥ 80% | 终审记录 |
-
-## 5. 治理工具（推荐落地）
-
-| 工具 | 作用 | 落地阶段 |
-|---|---|---|
-| **Markdown lint**（`markdownlint`） | 检查 frontmatter 完整性、链接有效性 | v1.0 PR 前接入 CI |
-| **链接巡检**（`lychee`） | 自动跑死链 / 失效 mention | v1.1 |
-| **Mermaid 校验**（`@mermaid-js/parser`） | 校验 .mmd 文件可渲染 | v1.0 PR 前 |
-| **`source-commit` 对齐脚本** | 检查 frontmatter 的 commit 是否在 main 历史中可达 | v1.0 PR 前 |
-| **失效扫描器** | 比对 `last-reviewed-at` 与 main HEAD diff，输出过期候选清单 | v1.1（与 PM 协同） |
-| **评分卡 LLM 助手** | 用大模型对文档做初评，节省人工 | v1.2 |
-| **Wiki 同步器** | `.md` → MkDocs / Material 自动构建 | v1.0 同步落地 |
-
-## 6. 与 PM 的协同节律
-
-| 频次 | 内容 | 出口物 |
-|---|---|---|
-| 每周一 | PM 在 [WS-11](mention://issue/6c0b5472-a0fa-4997-925c-a67f235f82da) 评论"本周关注点" | 通告 |
-| 每周三 | 知识运营点检本周已交付文档，必要时介入 | 评分卡更新 |
-| 每周五 EOB | 责任专家在子任务评论"本周完成 + 下周计划" | 子任务通告 |
-| 每月初 | 知识运营汇总月度评分均值，更新 `_release/quality-dashboard.md`（v1.1 起新增） | 月报 |
-| 每季度 | 全量复审（§2.2） + 给 PM 提交季度报告 | 季报（约 1 页） |
-| 每次 release | 同步评审 + 升版 + CHANGELOG（§2.1） | release 通告 |
-
-## 7. 失败模式与止损（备灾）
-
-| 风险 | 触发场景 | 止损 |
-|---|---|---|
-| 知识运营长期不在场 | 评审节奏断 | 提前指定 backup（建议 [@AI 知识库专家] + [@PM] 共审） |
-| 大量文档同时过期（如重大重构） | 无法在一个 release 内修完 | 按"先核心后边缘"分批：核心（pipeline/03 + evolution）→ overview → pipeline 其余 → graphrag → end-to-end |
-| 用户反馈与责任专家判断冲突 | 修订悬而未决 | 由 PM 仲裁；保留双方陈述在 issue |
-| 评分卡刚性导致一线积极性下降 | 因小错频繁返工 | 季度复盘评估"评分卡是否过严"，必要时调整 Should-Fix 与 Must-Fix 边界 |
-
-## 8. 一年内重要里程碑（建议）
-
-| 时点 | 内容 |
-|---|---|
-| 2026-05-08 | v1.0-RC1（本次发布） |
-| 2026-05-22 ~ 05-29 | S2-T7 评审收口；S2-T4/T6 文档补齐；目标升版 v1.0 |
-| 2026-06-01 ~ 06-05 | S3 全套文档落入仓库 PR；启动 [S3-T4 PM 复盘](mention://issue/b98604b1-326f-42b4-a4c2-b3d9ad80ec75) |
-| 2026-Q3 | S3-T1 §3.1 短期路线图全部合入 → v1.1 |
-| 2026-Q4 | S3-T2 PoC-A / PoC-B 落地，回填实测数据 → v1.2 |
-| 2027-Q1-Q2 | 4 大 Protocol 落地 + OTel 接入 → v2.0-RC |
-| 2027-H2 | 多模态 / 增量图等长期方向落地 → v2.0 正式 |
-
-— **Operations & Freshness Plan · v1.0-RC1 · 2026-05-08** —

docs/rag/_release/release-manifest-v1.0-RC1.md

@@ -1,126 +0,0 @@
-# MemoryBear RAG Docs · 发布候选清单 v1.0-RC1
-
-> **状态**：Release Candidate 1 · 候选发布
-> **冻结日期**：2026-05-08
-> **发布方式**：仓库 PR + Wiki + Issue 评论附件
-> **下次升版门槛**：S2-T7 评审通过 + S2-T4 / S2-T6 占位文档替换
-
----
-
-## 1. 版本基本信息
-
-| 项 | 值 |
-|---|---|
-| 版本号 | `v1.0-RC1` |
-| 发布通道 | Release Candidate（候选发布） |
-| 基线源码 | MemoryBear `agent/ai/f8de881a` 分支（基于 commit `feae2f2e`） |
-| 文档作者 | AI 知识库专家 / Python 工程师 / 知识运营专家 / PM 协同 |
-| 终审责任人 | 知识运营与治理专家 |
-| 文件总数 | 33 个（其中 28 已交付，5 占位） |
-| 总字数（含已交付） | ≈ 230k 字（中文） |
-| Mermaid 图表 | 9 张已交付，5 张待补 |
-| 源码引用 | 200+ 处（采样 5 处全部可在 ±3 行内复现） |
-
-## 2. 发布 Targets（"哪些文档随什么形式发布"）
-
-| 路径 | 发布形式 | 责任人 | 交付物 |
-|---|---|---|---|
-| `docs/rag/README.md` | **仓库 PR** | 知识运营 | Landing 页，含三套阅读路径 |
-| `docs/rag/INDEX.md` | **仓库 PR** | 知识运营 | 全集总索引 + 责任矩阵 |
-| `docs/rag/_meta/*` | **仓库 PR** | 知识运营 | 治理资产（已合入 `agent/ai/f8de881a` 分支预备） |
-| `docs/rag/overview/*.mmd` | **仓库 PR**（Mermaid 文件） + **Wiki**（渲染版） | AI 知识库 | 4 张时序/架构图 |
-| `docs/rag/overview/{boundaries.md,DocMap.md,source-inventory.md}` | **仓库 PR** | AI 知识库 / Python 工程 | 边界定义 / 大纲 / 源码盘点 |
-| `docs/rag/pipeline/*.md` | **仓库 PR** | Python 工程 | 4 篇已交付 + 1 占位（S2-T4 待重启） |
-| `docs/rag/end-to-end/README.md` | **占位**（不入 PR） | AI 知识库 | 等 S2-T6 解除阻塞后追加 |
-| `docs/rag/evolution/*` | **仓库 PR** | AI 知识库 | S3-T1 / S3-T2（终审已通过） |
-| `docs/rag/review/*` | **仓库 PR**（已通过部分） + **Issue 归档**（未启动部分） | 知识运营 | S3-T1 / S3-T2 终审报告 + S2-T7 占位 |
-| `docs/rag/_indexes/*` | **仓库 PR** | 知识运营 | Glossary / File Index / Chart Index |
-| `docs/rag/_release/*` | **仓库 PR** | 知识运营 | 本文 + 版本约定 + 运营保鲜计划 |
-
-> **建议 PR 拆分**：
-> - **PR-1**（_meta + README + INDEX）：作为治理 baseline 先合，便于后续文档按统一模板入库。
-> - **PR-2**（overview + 4 个 .mmd）：架构与图谱基础，独立合并便于 review。
-> - **PR-3**（pipeline 4 篇 + 1 占位）：Sprint-2 已交付内容；占位文件含明确"等待重启"说明，避免误读。
-> - **PR-4**（evolution + capability-map.mmd）：架构改造与迭代路线（S3-T1/T2）。
-> - **PR-5**（review + _indexes + _release）：评审报告与索引、运营资产。
-
-## 3. v1.0-RC1 → v1.0 升版门槛（Release Gate）
-
-| 门槛 | 当前状态 | 责任人 | 预计完成 |
-|---|---|---|---|
-| **G1: S2-T7 评审收口完成** | ⏳ todo（上一次 API Error） | 知识运营 | 重启后 1 个工作日 |
-| **G2: S2-T4 GraphRAG 文档交付 + 评审通过** | ⏳ 占位 | Python 工程师 | 重启后 1 周 |
-| **G3: S2-T6 E2E 调用链路文档交付** | ⏳ 阻塞（依赖 S2-T1~T5） | AI 知识库专家 | S2-T4 解除后 3 个工作日 |
-| **G4: 已交付的 4 篇 Sprint-2 文档（T1/T2/T3/T5）正式评分录入** | ⏳ 待 S2-T7 评审落分 | 知识运营 | G1 完成时一并 |
-| **G5: S3-T1 §3.1 短期路线图工作项 #1（删除 `node.py:327 print()`）合入 main** | ⏳ 待提 PR | Python 工程师 / AI 知识库 | 任意 1 个工作日 |
-| **G6: 全部仓库 PR 合入 main 分支** | ⏳ 待 PR 创建 | 知识运营协调 | G1-G5 完成后启动 |
-
-> **任一门槛未达成，停在 v1.0-RCN（N 递增）**。
-
-## 4. v1.0 ~ v2.0 版本节奏（建议）
-
-| 版本 | 触发条件 | 主要内容 |
-|---|---|---|
-| `v1.0` | G1-G6 全部 PASS | 完整的 S1+S2+S3 文档全集，对外可发布 |
-| `v1.1` | S3-T1 §3.1 短期路线图（5 项工作项）全部合入 | 增量更新：Reranker 缓存上线、`RAGSettings` 落地、单测脱离 ES 等 |
-| `v1.2` | S3-T2 PoC-A（RRF）+ PoC-B（Memory Rewrite）合入 | 增量更新 D2 / D4 章节，回填实测数据 |
-| `v1.3` | S3-T1 §3.2 中期路线图完成（OTel / Plugin Registry / 4 大 Protocol） | 大版本：Embedder/Retriever/Reranker/Generator Protocol 落地，可观测性建立 |
-| `v2.0` | S3-T1 §3.3 长期路线图完成 + S3-T2 D1/D3 多模态 + 增量图 | 架构演进里程碑：可插拔 VDB、Pipeline DSL、增量图、跨模态检索 |
-
-> 这套节奏与 [S3-T2] §4 Roadmap 的 Sprint-3 / 短/中/长 时间窗一致；每次升版必须同步刷新 Mermaid 图与 source-commit。
-
-## 5. 文档质量门槛（自检 vs 终审）
-
-| 类别 | 自检通过分 | 终审通过分 | 一票否决项 |
-|---|---|---|---|
-| Sprint-2 各深度文档（S2-T1 ~ S2-T5） | ≥ 70 | ≥ 80 | 源码虚构 / 核心章节缺失 / 安全风险描述 / 架构严重脱节 |
-| Sprint-3 演进文档（S3-T1 / S3-T2） | ≥ 75 | ≥ 80 | 同上 |
-| 治理资产（_meta） | ≥ 70 | ≥ 80 | 同上 |
-| 索引与 Landing | ≥ 70 | ≥ 80 | 同上 |
-
-> 上述阈值与 S1-T1 评分卡保持一致。当前 S3-T1 / S3-T2 已通过终审（96 / 95）。
-
-## 6. 已知风险与应对
-
-| # | 风险 | 影响 | 缓解 |
-|---|---|---|---|
-| R1 | S2-T4 GraphRAG 文档因 API Error 多次失败，可能再次中断 | v1.0 升版被卡 | 启动前先 dry-run 一次，若仍失败则把"GraphRAG 现有 light/general 的简版梳理"由 [@AI 知识库专家] 接管 |
-| R2 | S2-T6 E2E 文档目前 blocked，依赖 S2-T1~T5 全部交付 | v1.0 升版被卡 | S2-T4 完成后立即触发 S2-T6 |
-| R3 | 仓库 PR 与 RAG 主分支合并冲突（仓主可能在并行修改） | PR 滚动 review 难 | 锁定 source-commit，按 PR-1 → PR-5 顺序短链合并；冲突时由责任专家 rebase |
-| R4 | 文档与代码失同步（main 分支前进） | 内容时效性下降 | 见 `ops-and-freshness-plan.md` 的"每次 release 同步评审"机制 |
-| R5 | 内部 Wiki 渲染 Mermaid 节点上限 1500 | 大图渲染失败 | 拆图（Chart Index §4 已规划）、备份 SVG |
-| R6 | Sprint-2 文档评分若多篇低于 80，需返工 | 升版延期 | 先评 in_review 状态的 4 篇，发现共性问题立即下发修订 |
-
-## 7. 发布仪式 Checklist
-
-发布 v1.0 前，逐项打勾：
-
-- [ ] G1-G6 全部门槛达成（§3）
-- [ ] PR-1 ~ PR-5 全部合入 main
-- [ ] 内部 Wiki 同步发布（含 Mermaid 渲染版）
-- [ ] 在 [WS-24](mention://issue/a07f108d-06ee-41b8-8b57-22455f60ddeb) 发"v1.0 正式发布纪要"评论（含交付物清单 + 链接 + 总评分）
-- [ ] 状态由 `in_review` → `done`
-- [ ] 通知 PM 启动 [WS-25 / S3-T4 PM 复盘](mention://issue/b98604b1-326f-42b4-a4c2-b3d9ad80ec75)
-- [ ] 创建 v1.1 跟踪 issue（占位下一轮迭代）
-
----
-
-## 附录 A：当前已交付文件 SHA-1（防篡改）
-
-> 在落入仓库 PR 前，先记录附件的 SHA-1 校验值；合并到仓库后由 reviewer 复核。
-
-| 文件 | 来源 attachment ID | 大小 | 备注 |
-|---|---|---|---|
-| `S3-T1-deliverable.md` → `evolution/architecture-refactor-suggestions.md` | `019e0757-d0ab-704a-b6bb-5c1bbb3d8eb6` | 33 KB | S3-T1 |
-| `future-extensions-roadmap.md` → `evolution/future-extensions-roadmap.md` | `019e075c-42a0-7a64-b5d5-263c0fc92a0b` | 32 KB | S3-T2 |
-| `capability-map.mmd` → `evolution/capability-map.mmd` | `019e075c-42c7-713e-a8c3-41bf37d5ca37` | 4 KB | S3-T2 |
-| `01-architecture.mmd` → `overview/01-architecture.mmd` | `019e0747-0c26-79e8-984b-f6d8394016aa` | 5 KB | S1-T2 |
-| `02-indexing-pipeline.mmd` → `overview/02-indexing-pipeline.mmd` | `019e0747-0c4d-7808-8362-16b237c02048` | 4 KB | S1-T2 |
-| `03-query-pipeline.mmd` → `overview/03-query-pipeline.mmd` | `019e0747-0c71-7ab7-9269-1175e487308e` | 4 KB | S1-T2 |
-| `04-graphrag-indexing.mmd` → `overview/04-graphrag-indexing.mmd` | `019e0747-0c92-7ec5-a2c9-bb3f9c2b4de9` | 3 KB | S1-T2 |
-| `DocMap.md` → `overview/DocMap.md` | `019e0747-0cb6-78c4-8e5c-af441e571e3c` | 18 KB | S1-T2 |
-| `boundaries.md` → `overview/boundaries.md` | `019e0747-0cd9-7a9e-95f1-f5428e35b3c6` | 13 KB | S1-T2 |
-
-> S1-T1 _meta 系列与 Sprint-2 各深度文档当前以**评论正文**形式存在，作为本次 RC 的"评论沉淀+对外引用"双形态。仓库 PR 时由责任专家把评论正文落到对应文件，由知识运营复核 SHA-1 一致性。
-
-— **Release Manifest · v1.0-RC1 · 2026-05-08** —

docs/rag/_release/versioning-convention.md

@@ -1,84 +0,0 @@
-# MemoryBear RAG Docs · 版本号约定
-
-> 适用范围：`docs/rag/` 下所有文档，含 Markdown / Mermaid / 评分卡 / 模板。
-
-## 1. 版本号格式（语义化）
-
-```
-v<MAJOR>.<MINOR>[-RC<N>]
-```
-
-- **MAJOR**：架构层重大变化（如 4 大 Protocol 落地、可插拔 VDB 上线、检索范式切换）
-- **MINOR**：增量内容更新（新增章节、补图、回填基准、修订错误）
-- **-RC\<N\>**：候选发布（Release Candidate）N，用于在所有升版门槛达成前的过渡发布
-- **示例**：`v1.0-RC1` → `v1.0-RC2` → `v1.0` → `v1.1` → `v2.0-RC1` → `v2.0`
-
-## 2. 升版触发规则
-
-| 触发器 | 升版动作 |
-|---|---|
-| Release Gate 全部达成（见 release-manifest） | RCN → 正式版（去掉 -RC 后缀） |
-| 单文档 Should-Fix 修订 | 文档级 frontmatter `version` 增加 patch 标识（如 `1.0.1`），全集版本不变 |
-| 新增 Sprint 全套文档（如 Sprint-4 立项） | 全集 MINOR +1（v1.1 → v1.2） |
-| 4 大 Protocol 落地、可观测性引入、Plugin Registry 上线 | 全集 MAJOR +1（v1.x → v2.0-RC1） |
-| 紧急 hot-fix（修正错误源码引用、补救一票否决项） | 单文档 patch +1，并在 INDEX.md 记录 |
-
-## 3. frontmatter 规范
-
-每个 `.md` 文档 **必须**有 frontmatter，包括：
-
-```yaml
----
-name: <文档简称>
-description: <一句话描述>
-type: <user|feedback|project|reference|review|template|...>
-sprint: <S1|S2|S3>
-task: <T1|T2|...>
-author: <责任人角色名>
-reviewer: <终审责任人或 "待 [S2-T7] 评审">
-version: <语义化版本，如 1.0.0>
-source-commit: <锁定的代码 SHA，如 feae2f2e>
-last-reviewed-at: <YYYY-MM-DD>
----
-```
-
-> **强制项**：name、description、type、source-commit、last-reviewed-at。
-> **可选项**：reviewer（评审中的文档可填 "待 [S2-T7] 评审"）、version（占位文档可不填）。
-
-## 4. source-commit 锁定规则
-
-- **每篇深度文档**必须锁定一个具体的 commit SHA，作为"本文档与代码 100% 对齐的时间点"。
-- 当 main 分支前进、且与文档相关代码发生变化时：
-  - 微改（重命名、注释、格式）→ 不强制更新文档，但可顺手更新 `last-reviewed-at`。
-  - 接口变化、流程改动 → **必须**修订文档，并刷新 source-commit 与 last-reviewed-at。
-- **多文档共享 commit**：本次全集统一锁定到 `feae2f2e`（基线），若后续文档修订采用新 commit，需在 INDEX.md 标注差异。
-
-## 5. 与代码版本的对齐
-
-| 文档版本 | MemoryBear 代码版本 |
-|---|---|
-| `v1.0-RCN`（候选） | 基于 `feae2f2e` 工作分支 `agent/ai/f8de881a` |
-| `v1.0`（正式） | 与下一个 release tag（如 `v0.4.0`）同步发布 |
-| `v1.1` | 与 release `v0.4.x` 增量同步 |
-| `v2.0` | 对应 4 大 Protocol 落地之后的 release（预计 `v0.5.0` 之后） |
-
-> 文档版本号**不强制**与代码版本号一致，但发布通告中需明确"对应代码版本"。
-
-## 6. 已废弃文档处理
-
-- 标记 `status: deprecated` 在 frontmatter；
-- 文件首部加显眼的 `> ⚠️ DEPRECATED · 自 v1.x 起，本文已并入 <新文档路径>` 横幅；
-- 保留 6 个月（覆盖至少一个 release cycle），之后转移到 `docs/rag/_archive/<year>/` 归档。
-
-## 7. 协议变更（如 4 大 Protocol 名称改动）
-
-- 任意涉及命名的协议（Retriever / Reranker / Embedder / Generator / GraphStore）变更，必须同步刷新：
-  1. `evolution/architecture-refactor-suggestions.md` 主文
-  2. `evolution/future-extensions-roadmap.md` 引用处
-  3. `_indexes/glossary.md`
-  4. `_indexes/file-index.md` "提议中"行
-  5. `INDEX.md` 版本与状态
-  6. 所有 Sprint-2 文档中提到该协议的章节
-- 变更记录留在 `evolution/CHANGELOG.md`（v1.1 起新建）。
-
-— **Versioning Convention · v1.0-RC1 · 2026-05-08** —

docs/rag/end-to-end/README.md

@@ -1,264 +0,0 @@
----
-title: "[S2-T6] 端到端检索-生成调用链路与时序图 — 正式版"
-author: AI 知识库解决方案专家
-reviewer: 知识运营与治理专家
-source-commit: feae2f2e (MemoryBear)
-last-reviewed-at: 2026-05-08
-scope: api/app/{services,app_chat_service,draft_run_service,core/agent/langchain_agent,core/models/{llm,rerank,embedding},core/rag/{nlp/search,vdb/elasticsearch/elasticsearch_vector,app/naive,graphrag/{search,general/index}}}
-version: v1.0
-status: 正式版（已解除占位）
----
-
-# [S2-T6] 端到端检索-生成调用链路与时序图 — 正式版
-
-> 本文档为 [WS-24](mention://issue/a07f108d-06ee-41b8-8b57-22455f60ddeb) v1.0 文档全集的正式组成文件，替换 v1.0-RC1 中的占位版本。
-> 原始完整文档与逐节详评见 [WS-20](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) 与 [WS-21](mention://issue/41f2482b-6f3e-4253-95f7-3e22e790f31c) §S2-T6 评审报告。
-
----
-
-## 1. 一句话定位
-
-本文档是 Sprint-2 的"全链路串联"文档，将 [S2-T1]~[S2-T5] 五篇独立深度文档中的调用栈、数据结构与配置项，整合为**两条端到端时序图**（Query 端 + Indexing 端）、**一张关键路径表**、**三套多场景调用链**与**一张错误降级路径图**。所有函数引用均直接来源于子任务文档，未凭空虚构。
-
----
-
-## 2. 评审结果
-
-| 维度 | 满分 | 得分 | 关键说明 |
-|---|---:|---:|---|
-| 准确性 | 25 | 24 | 抽检 7/7 命中：`agnet_chat` / `_prepare_messages` / `knowledge_retrieval` / `_retrieve_for_knowledge` / `insert_citations` / `chunk()` / `_classify_error` |
-| 完整性 | 25 | 24 | 5 项硬性验收 100% 满足：Query 端时序图、Indexing 端时序图、关键路径表（15 行）、3 场景调用链、错误降级矩阵（13 行 + 6 路径 + 5 代码片段） |
-| 时效性 | 15 | 14 | frontmatter 完整规范（author / source-commit `feae2f2e` / last-reviewed-at / scope），仅缺 reviewer 字段（等待评审填入） |
-| 可读性 | 15 | 14 | Mermaid `autonumber` + `Note over` + `alt/par/loop` 专业级写法；瓶颈🔴🟡🟢色标视觉化优秀 |
-| 可执行性 | 20 | 19 | P50/P95 基线 + 瓶颈分析可直接落地为运维 SOP；5 个降级代码片段 copy-pasteable |
-| **合计** | **100** | **95** | **PASS（整合标杆，超 ≥85 门槛 +10）** |
-
-**裁定:** Sprint-2 **整合标杆**，直接通过，无 Must-Fix。
-
----
-
-## 3. Query 端 E2E 时序图（摘要）
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor U as 用户
-    participant FE as 前端
-    participant API as FastAPI
-    participant CS as AppChatService
-    participant AS as AgentRunService
-    participant Agent as LangChainAgent
-    participant KR as knowledge_retrieval()
-    participant VDB as ElasticSearchVector
-    participant Graph as KGSearch
-    participant LLM as RedBearLLM
-
-    U->>FE: 输入 Query
-    FE->>API: POST /api/v1/chat
-    API->>CS: await agnet_chat()
-    CS->>Agent: LangChainAgent()
-    Agent->>LLM: invoke(messages) [首轮判断工具]
-    LLM-->>Agent: 需调用 knowledge_retrieval_tool
-    Agent->>KR: knowledge_retrieval(query, config)
-
-    loop 遍历每个知识库
-        KR->>VDB: _retrieve_for_knowledge()
-        alt retrieve_type == "semantic"
-            VDB->>VDB: search_by_vector() + embed_query()
-        else retrieve_type == "participle"
-            VDB->>VDB: search_by_full_text() + ik_max_word
-        else retrieve_type == "hybrid"
-            par 双路并发
-                VDB->>VDB: search_by_vector()
-                VDB->>VDB: search_by_full_text()
-            end
-            VDB->>VDB: rerank() + RedBearRerank
-        end
-        alt use_graph=true
-            KR->>Graph: kg_retriever.retrieval()
-            Graph->>Graph: query_rewrite() LLM 提取实体+类型
-            Graph->>Graph: 三路召回: entity/relation/community
-        end
-    end
-
-    KR-->>Agent: List[DocumentChunk]
-    Agent->>LLM: astream_events() [流式生成]
-    LLM-->>FE: SSE 逐字渲染
-```
-
-完整版含 30+ 步骤调用栈、输入输出数据结构、同步/异步标注，见 [WS-20](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) §1。
-
----
-
-## 4. Indexing 端 E2E 时序图（摘要）
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor U as 用户
-    participant API as document_controller.py
-    participant Task as Celery Task
-    participant Chunk as chunk()
-    participant Parser as DeepDoc Parser
-    participant NLP as naive_merge
-    participant Emb as RedBearEmbeddings
-    participant VDB as ElasticSearchVector
-    participant ES as Elasticsearch
-    participant Graph as GraphRAG Index
-
-    U->>API: POST /documents 上传文件
-    API->>Task: 异步触发 chunk 任务
-    Task->>Chunk: chunk(filename, binary, ...)
-
-    alt PDF 格式
-        Chunk->>Parser: Pdf.__call__() → OCR → Layout → TSR
-    else DOCX 格式
-        Chunk->>Parser: Docx.parse()
-    else Excel/CSV
-        Chunk->>Parser: ExcelParser.__call__()
-    else Markdown
-        Chunk->>Parser: MarkdownParser
-    end
-
-    Chunk->>NLP: naive_merge(sections) + tokenize_chunks()
-    Chunk-->>Task: List[Dict] (ES doc 格式)
-
-    Task->>Emb: embed_documents(texts)
-    Emb-->>Task: List[List[float]]
-
-    Task->>VDB: add_chunks(chunks, embeddings)
-    VDB->>ES: helpers.bulk(actions)
-
-    alt GraphRAG 启用
-        Task->>Graph: run_graphrag_for_kb()
-        Graph->>Graph: generate_subgraph() → LLM 抽取
-        Graph->>Graph: merge_subgraph()
-        Graph->>ES: 写入 entity/relation chunks
-        alt General 模式
-            Graph->>Graph: EntityResolution()
-            Graph->>Graph: leiden.run() + CommunityReportsExtractor()
-        end
-    end
-```
-
-完整版含 14 步骤调用栈、ES Doc 字段契约，见 [WS-20](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) §2。
-
----
-
-## 5. 关键路径表（Critical Path Table）
-
-| # | 环节 | 关键函数 | 文件:行号 | P50 | P95 | 阻塞性 | 瓶颈 |
-|---|------|---------|-----------|-----|-----|--------|------|
-| 1 | **PDF 解析 (OCR+Layout+TSR)** | `Pdf.__call__()` | `deepdoc/parser/pdf_parser.py:1006` | 3s | 15s | 阻塞 | 🔴 |
-| 2 | **Chunking** | `naive_merge()` + `tokenize_chunks()` | `nlp/__init__.py:562,258` | 50ms | 200ms | 阻塞 | 🟡 |
-| 3 | **Embedding (批量)** | `embed_documents()` | `models/embedding.py:65` | 200ms | 1s | 阻塞 | 🔴 |
-| 4 | **ES 批量写入** | `helpers.bulk()` | `elasticsearch_vector.py:85` | 100ms | 500ms | 阻塞 | 🟡 |
-| 5 | **GraphRAG 实体抽取** | `generate_subgraph()` | `graphrag/general/index.py:333` | 30s | 120s | 阻塞 | 🔴 |
-| 6 | **GraphRAG 消歧** | `EntityResolution.__call__()` | `entity_resolution.py:53` | 10s | 60s | 阻塞 | 🔴 |
-| 7 | **GraphRAG 社区报告** | `CommunityReportsExtractor.__call__()` | `community_reports_extractor.py:55` | 20s | 90s | 阻塞 | 🔴 |
-| 8 | **Query Embedding** | `embed_query()` | `models/embedding.py:65` | 50ms | 300ms | 阻塞 | 🟡 |
-| 9 | **ES 向量检索** | `search_by_vector()` | `elasticsearch_vector.py:374` | 30ms | 200ms | 阻塞 | 🟡 |
-| 10 | **ES 关键词检索** | `search_by_full_text()` | `elasticsearch_vector.py:468` | 20ms | 100ms | 阻塞 | 🟢 |
-| 11 | **外部 Rerank** | `RedBearRerank.compress_documents()` | `models/rerank.py:11` | 100ms | 500ms | 阻塞 | 🟡 |
-| 12 | **GraphRAG 检索** | `KGSearch.retrieval()` | `graphrag/search.py:19` | 200ms | 1s | 阻塞 | 🟡 |
-| 13 | **LLM 首次调用** | `_chat()` | `chat_model.py:122` | 500ms | 3s | 阻塞 | 🔴 |
-| 14 | **LLM 流式生成** | `_chat_streamly()` | `chat_model.py:152` | 500ms | 5s | 流式 | 🔴 |
-| 15 | **引用回填** | `Dealer.insert_citations()` | `search.py:489` | 100ms | 500ms | 阻塞 | 🟡 |
-
-### 5.1 四大🔴瓶颈与缓解方向
-
-| 瓶颈 | 根因 | 缓解方向 |
-|------|------|---------|
-| PDF 解析 (P95=15s) | OCR + Layout + TSR 串行执行 | MinerU 替代 / 异步队列 / 预加载模型 |
-| Embedding API (P95=1s) | 外部 API 延迟，batch_size=16 | 本地 Xinference / GPUStack 部署 |
-| GraphRAG 建图 (P95=120s) | LLM 多轮抽取，单文档串行 | 增加 max_parallel_documents / 增量更新 |
-| LLM 流式输出 (P95=5s) | 首次 token (TTFT) 慢 | 缓存高频 query / 缩短 max_tokens |
-
----
-
-## 6. 多场景调用链（3 场景）
-
-### 场景 A：纯向量检索问答
-```
-Query → AppChatService → LangChainAgent → knowledge_retrieval()
-  → _retrieve_for_knowledge() [retrieve_type="semantic"]
-  → ElasticSearchVector.search_by_vector() + embed_query()
-  → ES script_score: cosineSimilarity
-  → top_k chunks → Agent → LLM 流式生成
-```
-
-### 场景 B：混合检索问答（关键词 + 向量）
-```
-Query → knowledge_retrieval() [retrieve_type="hybrid"]
-  → 双路并发: search_by_vector() + search_by_full_text()
-  → metadata.doc_id 去重
-  → rerank() + RedBearRerank.compress_documents()
-  → top_k → Agent → LLM 流式生成
-```
-
-### 场景 C：GraphRAG 关系推理问答
-```
-Query → knowledge_retrieval() [retrieve_type="graph"]
-  → 先执行 hybrid 检索
-  → KGSearch.retrieval() → query_rewrite() LLM 提取实体+类型
-  → 三路召回: entity/relation/community
-  → n-hop 路径扩展 (sim_decay = 1/(2+hop_depth))
-  → 融合打分: score = sim × pagerank
-  → Token 预算截断 → Agent → LLM 流式生成
-```
-
-完整 ASCII 流程图与数据结构流转详见 [WS-20](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) §4。
-
----
-
-## 7. 错误传播与降级路径
-
-### 7.1 错误矩阵（核心项）
-
-| 环节 | 失败模式 | 兜底逻辑 |
-|---|---|---|
-| PDF 解析 | OCR 模型缺失 | 标记 failed_document |
-| Embedding API | 超时/限流 | 抛出异常，整批重试 |
-| ES 写入 | ConnectionTimeout | ATTEMPT_TIME=2 重试 |
-| 知识库检索 | 单 KB 不可用 | try/except continue，跳过失败 KB |
-| 向量检索为空 | 阈值过严 | fallback 降低 min_match 0.3→0.1 |
-| 外部 Rerank | API 超时 | fallback 返回原始排序 |
-| GraphRAG 检索 | 图谱未建 | fallback 仅 hybrid 结果 |
-| LLM 调用 | RATE_LIMIT | 重试 5 次 + 随机抖动 |
-| LLM 截断 | finish_reason="length" | 自动追加截断提示 |
-
-### 7.2 降级路径图
-
-```
-正常路径:  Query → Hybrid → Rerank → LLM → 引用回填 → 输出
-
-降级 1 (检索为空):   Hybrid (空) → fallback 降低阈值 → 仍空 → LLM 直接回答
-降级 2 (Rerank 失败): Hybrid → Rerank 超时 → fallback 原始排序 → LLM 生成
-降级 3 (GraphRAG 失败): Hybrid → GraphRAG 失败 → fallback 仅 hybrid → LLM 生成
-降级 4 (单 KB 失败):  KB-A 失败 + KB-B 成功 → 合并 → LLM 生成
-降级 5 (LLM 失败):   检索成功 → LLM 5 次重试后 → 返回 "**ERROR**: 服务暂不可用"
-```
-
-完整代码片段（5 段可复用降级代码）见 [WS-20](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) §5.3。
-
----
-
-## 8. 跨文档引用索引
-
-| 本章节 | 被引文档 | 引用点 |
-|--------|---------|--------|
-| §3 Query 端 | [S2-T5] | `app_chat_service.py:43`, `langchain_agent.py:230`, `_chat_streamly()` |
-| §3 Query 端 | [S2-T3] | `search_by_vector()`, `search_by_full_text()`, `rerank()` |
-| §3 Query 端 | [S2-T4] | `KGSearch.retrieval()`, `query_rewrite()` |
-| §3 Query 端 | [S2-T2] | `embed_query()` |
-| §3 Query 端 | [S2-T5] | `RedBearRerank.compress_documents()`, `_filter_citations()` |
-| §4 Indexing 端 | [S2-T1] | `chunk()`, `naive_merge()`, `tokenize_chunks()` |
-| §4 Indexing 端 | [S2-T2] | `embed_documents()` |
-| §4 Indexing 端 | [S2-T3] | `add_chunks()`, `helpers.bulk()` |
-| §4 Indexing 端 | [S2-T4] | `run_graphrag_for_kb()`, `generate_subgraph()`, `EntityResolution()`, `leiden.run()` |
-
-**结论：6 篇文档形成完整闭环，跨文档引用 0 不一致。**
-
----
-
-*本文档为 MemoryBear RAG Docs v1.0 正式版本的组成文件。完整时序图、数据结构定义、关键路径分析与代码片段参见 [WS-20](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) 评论历史。*

docs/rag/end-to-end/source-full.md

@@ -1,645 +0,0 @@
----
-title: "[S2-T6] 端到端检索-生成调用链路与时序图"
-author: AI 知识库解决方案专家
-source-commit: feae2f2e (MemoryBear)
-last-reviewed-at: 2026-05-08
-scope: api/app/{services,app_chat_service,draft_run_service,core/agent/langchain_agent,core/models/{llm,rerank,embedding},core/rag/{nlp/search,vdb/elasticsearch/elasticsearch_vector,app/naive,graphrag/{search,general/index}}}
----
-
-# [S2-T6] 端到端检索-生成调用链路与时序图
-
-## 一句话定位
-
-本文档是 Sprint-2 的"全链路串联"文档，将 [S2-T1]~[S2-T5] 五篇独立深度文档中的调用栈、数据结构与配置项，整合为**两条端到端时序图**（Query 端 + Indexing 端）、**一张关键路径表**、**三套多场景调用链**与**一张错误降级路径图**。所有函数引用均直接来源于子任务文档，未凭空虚构。
-
----
-
-## 1. Query 端 E2E 时序图
-
-**场景**：用户通过分享链接发起对话，Agent 调用知识库检索工具，最终流式输出答案。
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor U as 用户
-    participant FE as 前端 (Web)
-    participant API as FastAPI<br/>api/main.py
-    participant CS as AppChatService<br/>services/app_chat_service.py
-    participant AS as AgentRunService<br/>services/draft_run_service.py
-    participant Agent as LangChainAgent<br/>core/agent/langchain_agent.py
-    participant Tool as knowledge_retrieval_tool<br/>draft_run_service.py:195
-    participant KR as knowledge_retrieval()<br/>core/rag/nlp/search.py:36
-    participant RK as _retrieve_for_knowledge()<br/>core/rag/nlp/search.py:149
-    participant VDB as ElasticSearchVector<br/>core/rag/vdb/elasticsearch/
-    participant ES as Elasticsearch
-    participant Graph as KGSearch<br/>core/rag/graphrag/search.py:19
-    participant LLM as RedBearLLM<br/>core/models/llm.py
-    participant CM as Chat Model<br/>core/rag/llm/chat_model.py
-
-    U->>FE: 输入 Query
-    FE->>API: POST /api/v1/chat<br/>{message, conversation_id, ...}
-
-    API->>CS: await agnet_chat()<br/>app_chat_service.py:43
-    Note over CS: 同步/阻塞: 模型配置加载 + 工具组装
-
-    CS->>CS: 加载 features_config + 文件校验
-    CS->>CS: ModelApiKeyService.get_available_api_key()<br/>获取 LLM api_key/model_name
-    CS->>CS: render_prompt_message()<br/>变量替换 system_prompt
-    CS->>AS: load_knowledge_retrieval_config()<br/>组装知识检索工具
-
-    CS->>Agent: LangChainAgent()<br/>langchain_agent.py:26
-    Note over Agent: 输入: system_prompt + tools<br/>max_iterations = 5 + len(tools)*2
-
-    Agent->>Agent: _prepare_messages()<br/>langchain_agent.py:230<br/>组装: history + context + query
-    Note over Agent: 数据结构: List[BaseMessage]<br/>[SystemMessage, HumanMessage, AIMessage, ...]
-
-    Agent->>LLM: invoke(messages)<br/>models/llm.py:65
-    LLM->>CM: _chat()<br/>chat_model.py:122
-    Note over CM: 同步/阻塞 HTTP 调用<br/>stream=False (首轮判断工具)
-
-    CM-->>LLM: AIMessage(content="", tool_calls=[...])
-    LLM-->>Agent: 需调用 knowledge_retrieval_tool
-
-    Agent->>Tool: 执行知识检索工具
-    Tool->>KR: knowledge_retrieval(query, config)<br/>search.py:36
-    Note over KR: 输入: query=str<br/>config={knowledge_bases, retrieve_type, reranker_id, use_graph}
-
-    loop 遍历每个知识库
-        KR->>RK: _retrieve_for_knowledge()<br/>search.py:149
-        Note over RK: 输入: db_knowledge, kb_config<br/>输出: List[DocumentChunk]
-
-        alt retrieve_type == "semantic" (纯向量)
-            RK->>VDB: search_by_vector()<br/>elasticsearch_vector.py:374
-            VDB->>VDB: embeddings.embed_query(query)<br/>models/embedding.py:65
-            VDB->>ES: script_score: cosineSimilarity()<br/>filter: metadata.status=1
-            ES-->>VDB: List[hit] (score /2 归一化到 [0,1])
-        else retrieve_type == "participle" (纯关键词)
-            RK->>VDB: search_by_full_text()<br/>elasticsearch_vector.py:468
-            VDB->>ES: match + ik_max_word<br/>filter: metadata.status=1
-            ES-->>VDB: List[hit] (_score/max_score 归一化)
-        else retrieve_type == "hybrid" (混合)
-            par 双路并发
-                RK->>VDB: search_by_vector() [异步]
-                RK->>VDB: search_by_full_text() [异步]
-            end
-            RK->>RK: metadata.doc_id 去重
-            RK->>VDB: rerank(query, docs, top_k)<br/>elasticsearch_vector.py:560
-            VDB->>VDB: RedBearRerank.compress_documents()<br/>models/rerank.py:11
-        end
-
-        alt retrieve_type == "graph" 且 use_graph=true
-            RK->>Graph: kg_retriever.retrieval()<br/>graphrag/search.py:19
-            Graph->>Graph: query_rewrite() LLM 提取实体+类型
-            Graph->>ES: 三路召回: entity/relation/community
-            ES-->>Graph: {page_content: entities+relations+community}
-            Graph-->>RK: DocumentChunk 插入 rs[0]
-        end
-    end
-
-    alt reranker_id 配置
-        KR->>KR: rerank()<br/>search.py:284
-        KR->>KR: RedBearRerank.compress_documents()<br/>models/rerank.py:11
-        Note over KR: 外部 rerank API 调用<br/>同步/阻塞, 100-500ms
-    end
-
-    KR-->>Tool: List[DocumentChunk]<br/>page_content + metadata
-    Tool->>Tool: chunks 拼接为 context 字符串
-    Tool-->>Agent: f"检索到以下相关信息: {context}"
-
-    Agent->>Agent: _prepare_messages()<br/>追加工具结果到消息列表
-    Agent->>LLM: astream_events(version="v2")<br/>models/llm.py:117
-    LLM->>CM: _chat_streamly()<br/>chat_model.py:152
-    Note over CM: 异步/流式 HTTP SSE<br/>yield (delta, token_count)
-
-    loop 每收到一个 token chunk
-        CM-->>LLM: GenerationChunk
-        LLM-->>Agent: on_chat_model_stream event
-        Agent-->>CS: yield SSE chunk
-        CS-->>API: StreamingResponse
-        API-->>FE: data: {"content": "..."}
-        FE-->>U: 逐字渲染
-    end
-
-    CS->>CS: _filter_citations()<br/>draft_run_service.py:474<br/>引用过滤 + 下载链接
-    CS-->>API: {content, citations, tokens_used}
-    API-->>FE: JSON 响应
-```
-
-### 1.1 关键调用栈注释
-
-| 步骤 | 函数 | 文件:行号 | 同步/异步 | 输入 | 输出 |
-|------|------|-----------|-----------|------|------|
-| 1 | `agnet_chat()` | `services/app_chat_service.py:43` | `async` | message, config, files | Dict |
-| 2 | `LangChainAgent.__init__()` | `core/agent/langchain_agent.py:26` | 同步 | model_name, tools, system_prompt | Agent 实例 |
-| 3 | `_prepare_messages()` | `core/agent/langchain_agent.py:230` | 同步 | message, history, context | `List[BaseMessage]` |
-| 4 | `knowledge_retrieval()` | `core/rag/nlp/search.py:36` | 同步 | query, config | `List[DocumentChunk]` |
-| 5 | `_retrieve_for_knowledge()` | `core/rag/nlp/search.py:149` | 同步 | db_knowledge, kb_config | `List[DocumentChunk]` |
-| 6 | `search_by_vector()` | `core/rag/vdb/elasticsearch/elasticsearch_vector.py:374` | 同步 | query, top_k, score_threshold | `List[DocumentChunk]` |
-| 7 | `embed_query()` | `core/models/embedding.py:65` | 同步 | query_str | `List[float]` |
-| 8 | `search_by_full_text()` | `core/rag/vdb/elasticsearch/elasticsearch_vector.py:468` | 同步 | query, top_k, score_threshold | `List[DocumentChunk]` |
-| 9 | `rerank()` (独立) | `core/rag/nlp/search.py:284` | 同步 | query, docs, top_k | `List[DocumentChunk]` |
-| 10 | `RedBearRerank.compress_documents()` | `core/models/rerank.py:11` | 同步 | documents, query | `List[Document]` |
-| 11 | `KGSearch.retrieval()` | `core/rag/graphrag/search.py:19` | 同步 | question, kb_ids, emb_mdl | Dict |
-| 12 | `_chat_streamly()` | `core/rag/llm/chat_model.py:152` | 异步流式 | messages | `AsyncGenerator` |
-| 13 | `_filter_citations()` | `services/draft_run_service.py:474` | 同步 | features_config, citations | List[Dict] |
-
-### 1.2 输入输出数据结构
-
-```python
-# 1. DocumentChunk (检索结果单元)
-# core/rag/models/chunk.py
-class DocumentChunk(BaseModel):
-    page_content: str           # chunk 文本内容
-    vector: list[float] | None  # 向量（检索阶段通常为空）
-    metadata: dict = {
-        "doc_id": str,         # 文档唯一标识
-        "file_name": str,      # 原始文件名
-        "score": float,        # 相似度/重排序分数
-        "knowledge_id": str,   # 所属知识库
-        ...
-    }
-
-# 2. knowledge_retrieval 配置结构
-config = {
-    "knowledge_bases": [{
-        "kb_id": str,
-        "retrieve_type": "participle" | "semantic" | "hybrid" | "graph",
-        "similarity_threshold": float,      # 默认 0.2
-        "vector_similarity_weight": float,  # 默认 0.3
-        "top_k": int,                       # 默认 4
-    }],
-    "reranker_id": str | None,
-    "reranker_top_k": int,     # 默认 1024
-    "use_graph": bool,         # 是否启用 GraphRAG
-}
-
-# 3. LangChainAgent 消息结构
-messages = [
-    SystemMessage(content="system_prompt + skill_prompts"),
-    HumanMessage(content="历史消息..."),
-    AIMessage(content="历史回复..."),
-    HumanMessage(content="参考信息：\n\n{chunks}\n\n用户问题：\n{query}"),
-]
-```
-
----
-
-## 2. Indexing 端 E2E 时序图
-
-**场景**：用户上传 PDF 文档到知识库，系统完成解析、分块、Embedding、写入 ES + 构建图谱。
-
-```mermaid
-sequenceDiagram
-    autonumber
-    actor U as 用户
-    participant API as document_controller.py
-    participant Task as Celery Task<br/>tasks.py
-    participant Chunk as chunk()<br/>core/rag/app/naive.py:508
-    participant Parser as DeepDoc Parser<br/>core/rag/deepdoc/parser/
-    participant NLP as naive_merge<br/>core/rag/nlp/__init__.py
-    participant Emb as RedBearEmbeddings<br/>core/models/embedding.py
-    participant VDB as ElasticSearchVector<br/>core/rag/vdb/elasticsearch/
-    participant ES as Elasticsearch
-    participant Graph as GraphRAG Index<br/>core/rag/graphrag/general/index.py
-
-    U->>API: POST /documents<br/>上传文件 + knowledge_id
-    API->>API: 保存原始文件到存储
-    API->>Task: 异步触发 chunk 任务
-
-    Task->>Chunk: chunk(filename, binary, ...)<br/>naive.py:508
-    Note over Chunk: 总入口，按扩展名分派
-
-    alt PDF 格式
-        Chunk->>Chunk: 按 parser_config.layout_recognize 选引擎<br/>PARSERS dict: naive.py:97
-        Chunk->>Parser: Pdf.__call__()<br/>pdf_parser.py:522
-        Parser->>Parser: __images__() OCR<br/>ocr.py:522
-        Parser->>Parser: _layouts_rec() 版面识别<br/>layout_recognizer.py:147
-        Parser->>Parser: _table_transformer_job() TSR<br/>table_structure_recognizer.py
-        Parser->>Parser: _text_merge() + _concat_downward()<br/>XGBoost 段落连接
-        Parser-->>Chunk: sections=[(text, position_tag), ...]<br/>tables=[...]
-    else DOCX 格式
-        Chunk->>Parser: Docx.parse()<br/>docx_parser.py:9
-        Parser-->>Chunk: sections=[(text, image), ...]
-    else Excel/CSV
-        Chunk->>Parser: ExcelParser.__call__()<br/>excel_parser.py:203
-        Parser-->>Chunk: sections (每行一段)
-    else Markdown
-        Chunk->>Parser: MarkdownParser<br/>markdown_parser.py:10
-        Parser-->>Chunk: sections (element block)
-    end
-
-    Chunk->>NLP: naive_merge(sections)<br/>nlp/__init__.py:562
-    Note over NLP: 按 token 上限 + delimiter 切分<br/>默认 chunk_token_num=512 (PDF) / 128 (其他)
-
-    NLP->>NLP: tokenize_chunks()<br/>nlp/__init__.py:258
-    Note over NLP: 注入 ES 字段:<br/>content_with_weight, content_ltks, content_sm_ltks,<br/>page_num_int, position_int, top_int, docnm_kwd
-
-    Chunk-->>Task: List[Dict] (ES doc 格式)
-
-    Task->>Emb: embed_documents(texts)<br/>models/embedding.py:65
-    Note over Emb: 多 provider 支持:<br/>OpenAI/DashScope/Volcano/Xinference/...
-    Emb-->>Task: List[List[float]]
-
-    Task->>VDB: add_chunks(chunks, embeddings)<br/>elasticsearch_vector.py:55
-    VDB->>VDB: create_collection() 懒建索引<br/>elasticsearch_vector.py:65
-    Note over VDB: mapping: page_content(text+ik),<br/>metadata(object), vector(dense_vector+cosine)
-    VDB->>ES: helpers.bulk(actions)<br/>批量写入
-    ES-->>VDB: result (success count)
-
-    alt GraphRAG 启用 (use_graphrag=true)
-        Task->>Graph: run_graphrag_for_kb()<br/>graphrag/general/index.py:122
-        Graph->>Graph: generate_subgraph()<br/>index.py:333
-        Note over Graph: LLM 抽取 entities + relations<br/>多轮 gleaning (max=2)
-        Graph->>Graph: merge_subgraph()<br/>index.py:409
-        Graph->>ES: 写入 entity/relation chunks<br/>带 q_{dim}_vec 向量字段
-
-        alt General 模式 + with_resolution
-            Graph->>Graph: EntityResolution()<br/>entity_resolution.py:53
-            Note over Graph: 编辑距离预筛选 + LLM 批量判断<br/>batch=100, concurrent=5
-        end
-
-        alt General 模式 + with_community
-            Graph->>Graph: leiden.run()<br/>leiden.py:95
-            Graph->>Graph: CommunityReportsExtractor()<br/>community_reports_extractor.py:55
-            Graph->>ES: 写入 community_report chunks
-        end
-    end
-
-    Task-->>API: {ok_documents, failed_documents, seconds}
-    API-->>U: 入库完成通知
-```
-
-### 2.1 关键调用栈注释
-
-| 步骤 | 函数 | 文件:行号 | 同步/异步 | 输入 | 输出 |
-|------|------|-----------|-----------|------|------|
-| 1 | `chunk()` | `core/rag/app/naive.py:508` | 同步 | filename/binary, parser_config | `List[Dict]` ES doc |
-| 2 | `Pdf.__call__()` | `pdf_parser.py:1006` | 同步 | filename, callback | sections, tables |
-| 3 | `OCR.__call__()` | `vision/ocr.py:522` | 同步 | PIL.Image | text_boxes |
-| 4 | `LayoutRecognizer4YOLOv10.__call__()` | `layout_recognizer.py:147` | 同步 | image_list | layout_types |
-| 5 | `naive_merge()` | `core/rag/nlp/__init__.py:562` | 同步 | sections, chunk_token_num | `List[str]` chunks |
-| 6 | `tokenize_chunks()` | `core/rag/nlp/__init__.py:258` | 同步 | chunks, doc | `List[Dict]` ES docs |
-| 7 | `embed_documents()` | `core/models/embedding.py:65` | 同步 | texts | `List[List[float]]` |
-| 8 | `add_chunks()` | `core/rag/vdb/elasticsearch/elasticsearch_vector.py:55` | 同步 | chunks, embeddings | uuids |
-| 9 | `create_collection()` | `elasticsearch_vector.py:609` | 同步 | embeddings | mapping created |
-| 10 | `helpers.bulk()` | elasticsearch.helpers | 同步 | actions | (success, errors) |
-| 11 | `run_graphrag_for_kb()` | `graphrag/general/index.py:122` | 异步 (trio) | document_ids | subgraphs |
-| 12 | `generate_subgraph()` | `graphrag/general/index.py:333` | 异步 | extractor, chunks | nx.Graph |
-| 13 | `EntityResolution.__call__()` | `entity_resolution.py:53` | 异步 | graph, nodes | merged_graph |
-| 14 | `leiden.run()` | `graphrag/general/leiden.py:95` | 同步 | graph | communities |
-
-### 2.2 ES Doc 字段契约
-
-```python
-# 写入 ES 的 chunk 文档结构 (来自 S2-T1 §6.7)
-{
-    "docnm_kwd": str,              # 文件名 (keyword)
-    "title_tks": str,              # 标题粗分词
-    "title_sm_tks": str,           # 标题细分词
-    "content_with_weight": str,    # 原始 chunk 文本 (BM25 加权)
-    "content_ltks": str,           # 内容粗分词 (whitespace analyzer)
-    "content_sm_ltks": str,        # 内容细分词
-    "page_num_int": [int],         # 页码列表
-    "position_int": [(p,x0,x1,y0,y1)],  # 坐标
-    "top_int": [int],              # 行顶 y 坐标
-    "image": bytes | None,         # PIL.Image 二进制
-    "doc_type_kwd": str | None,    # "image" 或空
-    "q_{dim}_vec": [float],        # Embedding 向量 (S2-T2 补充)
-    "metadata": {
-        "doc_id": str,
-        "file_name": str,
-        "knowledge_id": str,
-        "status": 1,
-    }
-}
-```
-
----
-
-## 3. 关键路径表 (Critical Path Table)
-
-> 耗时基线基于代码注释、log 锚点及工程经验估算。实际值取决于文档复杂度、模型 provider、网络延迟与 ES 集群规模。
-
-| # | 环节 | 关键函数 | 文件:行号 | P50 | P95 | 阻塞/非阻塞 | 瓶颈标记 |
-|---|------|---------|-----------|-----|-----|------------|---------|
-| 1 | **PDF 解析 (OCR+Layout+TSR)** | `Pdf.__call__()` | `deepdoc/parser/pdf_parser.py:1006` | 3s | 15s | 阻塞 (CPU/GPU) | 🔴 |
-| 2 | **Chunking (tokenize)** | `naive_merge()` + `tokenize_chunks()` | `nlp/__init__.py:562,258` | 50ms | 200ms | 阻塞 (本地 CPU) | 🟡 |
-| 3 | **Embedding (批量)** | `embed_documents()` | `models/embedding.py:65` | 200ms | 1s | 阻塞 (网络 I/O) | 🔴 |
-| 4 | **ES 批量写入** | `helpers.bulk()` | `elasticsearch_vector.py:85` | 100ms | 500ms | 阻塞 (网络 I/O) | 🟡 |
-| 5 | **GraphRAG 实体抽取** | `generate_subgraph()` | `graphrag/general/index.py:333` | 30s | 120s | 阻塞 (LLM I/O) | 🔴 |
-| 6 | **GraphRAG 实体消歧** | `EntityResolution.__call__()` | `entity_resolution.py:53` | 10s | 60s | 阻塞 (LLM I/O) | 🔴 |
-| 7 | **GraphRAG 社区报告** | `CommunityReportsExtractor.__call__()` | `community_reports_extractor.py:55` | 20s | 90s | 阻塞 (LLM I/O) | 🔴 |
-| 8 | **Query Embedding** | `embed_query()` | `models/embedding.py:65` | 50ms | 300ms | 阻塞 (网络 I/O) | 🟡 |
-| 9 | **ES 向量检索** | `search_by_vector()` | `elasticsearch_vector.py:374` | 30ms | 200ms | 阻塞 (网络 I/O) | 🟡 |
-| 10 | **ES 关键词检索** | `search_by_full_text()` | `elasticsearch_vector.py:468` | 20ms | 100ms | 阻塞 (网络 I/O) | 🟢 |
-| 11 | **外部 Rerank** | `RedBearRerank.compress_documents()` | `models/rerank.py:11` | 100ms | 500ms | 阻塞 (网络 I/O) | 🟡 |
-| 12 | **GraphRAG 检索** | `KGSearch.retrieval()` | `graphrag/search.py:19` | 200ms | 1s | 阻塞 (LLM+ES) | 🟡 |
-| 13 | **LLM 首次调用 (判断工具)** | `_chat()` | `chat_model.py:122` | 500ms | 3s | 阻塞 (网络 I/O) | 🔴 |
-| 14 | **LLM 流式生成** | `_chat_streamly()` | `chat_model.py:152` | 500ms | 5s | 非阻塞 (SSE 流式) | 🔴 |
-| 15 | **引用回填** | `Dealer.insert_citations()` | `search.py:489` | 100ms | 500ms | 阻塞 (本地 embedding) | 🟡 |
-
-### 3.1 瓶颈分析
-
-| 瓶颈 | 根因 | 缓解方向 |
-|------|------|---------|
-| PDF 解析 (P95=15s) | OCR + Layout + TSR 串行执行，GPU 模型加载慢 | MinerU 替代 / 异步队列 / 预加载模型 |
-| Embedding API (P95=1s) | 外部 API 延迟，batch_size=16 不够大 | 本地 Xinference / GPUStack 部署 |
-| GraphRAG 建图 (P95=120s) | LLM 多轮抽取，单文档串行 | 增加 max_parallel_documents / 增量更新 |
-| LLM 流式输出 (P95=5s) | 首次 token (TTFT) 慢，长答案总耗时长 | 缓存高频 query / 缩短 max_tokens |
-
----
-
-## 4. 多场景调用链
-
-### 4.1 场景 A：纯向量检索问答
-
-**适用**：语义匹配质量高的知识库，用户问题与文档表述风格一致。
-
-```
-[User Query]
-    │
-    ▼
-AppChatService.agnet_chat()          [services/app_chat_service.py:43]  async
-    │
-    ▼
-LangChainAgent.invoke()              [core/agent/langchain_agent.py:65]  sync
-    │
-    ▼
-knowledge_retrieval_tool 调用
-    │
-    ▼
-knowledge_retrieval()                [core/rag/nlp/search.py:36]  sync
-    │
-    ▼
-_retrieve_for_knowledge()            [core/rag/nlp/search.py:149]  sync
-    │ retrieve_type="semantic"
-    ▼
-ElasticSearchVector.search_by_vector() [core/rag/vdb/elasticsearch/elasticsearch_vector.py:374]  sync
-    │
-    ├─► embed_query(query)           [core/models/embedding.py:65]  sync, HTTP
-    │       │
-    │       ▼
-    │   List[float] query_vector
-    │
-    ▼
-ES script_score: cosineSimilarity(params.query_vector, 'vector') + 1.0
-    filter: metadata.status=1
-    │
-    ▼
-List[DocumentChunk] (score /2 归一化到 [0,1])
-    │
-    ▼
-score_threshold 过滤 (默认 0.3)
-    │
-    ▼
-返回 top_k chunks → Agent 上下文组装
-    │
-    ▼
-LLM _chat_streamly() 流式生成答案
-```
-
-**数据结构流转**：
-```
-query: str
-  → query_vector: List[float] (dim=512/768/1024/1536)
-  → ES hits: List[{_score, _source}]
-  → DocumentChunk[] (score ∈ [0,1])
-  → context: str (chunks 用 "\n\n" 拼接)
-  → messages: List[BaseMessage] (system + history + context + query)
-  → SSE stream: AsyncGenerator[str]
-```
-
-### 4.2 场景 B：混合检索问答 (关键词 + 向量)
-
-**适用**：关键词精准度与语义召回互补的场景，如技术文档库。
-
-```
-[User Query]
-    │
-    ▼
-knowledge_retrieval()                [core/rag/nlp/search.py:36]  sync
-    │
-    ▼
-_retrieve_for_knowledge()            [core/rag/nlp/search.py:149]  sync
-    │ retrieve_type="hybrid" (默认分支)
-    ▼
-┌─────────────────────────────────────────┐
-│ 双路并发 (asyncio.gather)               │
-│                                         │
-│ 路 1: search_by_vector()               │
-│   [elasticsearch_vector.py:374]        │
-│   → embed_query() → ES script_score    │
-│   → 归一化 score /2 → [0,1]            │
-│                                         │
-│ 路 2: search_by_full_text()            │
-│   [elasticsearch_vector.py:468]        │
-│   → match + ik_max_word → BM25         │
-│   → 归一化 _score/max_score → [0,1]    │
-└─────────────────────────────────────────┘
-    │
-    ▼
-metadata.doc_id 去重 (后到的丢弃)
-    │
-    ▼
-ElasticSearchVector.rerank()         [elasticsearch_vector.py:560]  sync
-    │
-    ▼
-RedBearRerank.compress_documents()   [core/models/rerank.py:11]  sync
-    │ 外部 API 调用 (Xinference/GPUStack/DashScope)
-    ▼
-按 relevance_score 降序取 top_k
-    │
-    ▼
-返回 DocumentChunk[] → Agent
-```
-
-**融合公式**（路径 B 应用层）：
-```
-candidates = vector_topk(q) ∪ bm25_topk(q)
-deduped    = unique_by(metadata.doc_id, candidates)
-final      = reranker(query, deduped)[:top_k]   (若配置 reranker)
-          or sort_by_score_desc(deduped)[:top_k] (未配置时)
-```
-
-### 4.3 场景 C：GraphRAG 关系推理问答
-
-**适用**：需要多跳推理、实体关联分析、全局洞察的复杂问答。
-
-```
-[User Query]
-    │
-    ▼
-knowledge_retrieval()                [core/rag/nlp/search.py:36]  sync
-    │
-    ▼
-_retrieve_for_knowledge()            [core/rag/nlp/search.py:149]  sync
-    │ retrieve_type="graph"
-    ├─► 先执行 hybrid 检索 (同场景 B)
-    │
-    ▼
-KGSearch.retrieval()                 [core/rag/graphrag/search.py:19]  sync
-    │
-    ▼
-query_rewrite()                      [graphrag/search.py:33]
-    │
-    ├─► LLM Prompt: minirag_query2kwd
-    │   输入: question + TYPE_POOL (从 ES 采样)
-    │   输出: {answer_type_keywords, entities_from_query}
-    │
-    ▼
-┌─────────────────────────────────────────┐
-│ 三路召回并行                            │
-│                                         │
-│ 路 1: get_relevant_ents_by_keywords()  │
-│   → embed_query(entities) → ES knn     │
-│   → 实体向量相似度召回 (sim_threshold=0.3)│
-│                                         │
-│ 路 2: get_relevant_ents_by_types()     │
-│   → answer_type_keywords 精确匹配       │
-│                                         │
-│ 路 3: get_relevant_relations_by_txt()  │
-│   → 关系向量相似度召回                  │
-└─────────────────────────────────────────┘
-    │
-    ▼
-n-hop 路径扩展 (预计算)
-    │ sim_decay = 1/(2 + hop_depth)
-    ▼
-融合打分: score = sim × pagerank
-    │ 实体排序: sim × pagerank
-    │ 关系排序: sim × pagerank × boost
-    ▼
-Token 预算截断 (max_token 递减)
-    │
-    ▼
-社区报告召回 (comm_topn=1)
-    │
-    ▼
-返回: {page_content: entities + relations + community,
-       metadata: {...}, vector: None}
-    │
-    ▼
-插入 hybrid 结果头部: rs.insert(0, graph_chunk)
-    │
-    ▼
-Agent 上下文组装 → LLM 生成
-```
-
-**GraphRAG 建图调用链**（前置条件）：
-```
-tasks.py:build_graphrag_for_kb()
-  → run_graphrag_for_kb()          [graphrag/general/index.py:122]
-    → generate_subgraph()          [index.py:333]
-      → LLM 抽取 entities + relations (多轮 gleaning, max=2)
-    → merge_subgraph()             [index.py:409]
-      → graph_merge()              [utils.py:199]
-    → [可选] EntityResolution()    [entity_resolution.py:53]
-    → [可选] leiden.run()          [leiden.py:95]
-    → [可选] CommunityReportsExtractor() [community_reports_extractor.py:55]
-  → ES 写入 entity/relation/community chunks
-```
-
----
-
-## 5. 错误传播与降级路径
-
-### 5.1 错误传播矩阵
-
-| 环节 | 失败模式 | 影响范围 | 兜底逻辑 | 源码位置 |
-|------|---------|---------|---------|---------|
-| **PDF 解析** | OCR 模型缺失 / GPU 不可用 | 单文档失败 | `callback(-1, "OCR model not found")`，任务标记为 failed_document | `pdf_parser.py:50` |
-| **LibreOffice 转换** | soffice 未安装 / 120s 超时 | PPT/DOC 失败 | 抛 HTTP 500，无自动降级 | `utils/libre_office.py:11` |
-| **Embedding API** | 超时 / 限流 / 鉴权失败 | 单批 chunks 失败 | 抛出异常，helpers.bulk 不捕获，整批失败需重试 | `models/embedding.py:65` |
-| **ES 写入** | ConnectionTimeout / 集群不可用 | 单批 chunks 失败 | `ATTEMPT_TIME=2` 重试，回连后重发 | `utils/es_conn.py:294` |
-| **GraphRAG 抽取** | LLM 输出格式错误 | 单 chunk 失败 | `json_repair` 容错 + max_errors=3，超限时跳过 | `extractor.py:97` |
-| **GraphRAG 消歧** | LLM 超时 (280s) | 消歧失败 | `trio.move_on_after` 超时，跳过消歧阶段 | `entity_resolution.py:53` |
-| **知识库检索** | 单 KB 不可用 | 其他 KB 不受影响 | `try/except continue`，失败 KB 被跳过 | `search.py:110` |
-| **向量检索为空** | 阈值过严 / 维度不匹配 | 当前 KB 无结果 | fallback: 降低 min_match 0.3→0.1，提高 similarity 0.1→0.17 | `search.py:447` |
-| **外部 Rerank** | API 超时 / 模型不可用 | 无重排序结果 | fallback: 返回原始结果（不打乱顺序） | `search.py:115` |
-| **GraphRAG 检索** | 图谱未建 / ES 查询失败 | 无图谱增强结果 | fallback: 仅返回 hybrid 结果 | `search.py:263` |
-| **LLM 调用** | RATE_LIMIT / SERVER_ERROR | 生成失败 | 重试 5 次 + 随机抖动；仍失败返回 `**ERROR**: ...` | `chat_model.py:64` |
-| **LLM 截断** | finish_reason="length" | 答案不完整 | 自动追加截断提示 (中英文自适应) | `chat_model.py:152` |
-| **引用回填** | embedding 匹配失败 | 无引用标记 | 跳过 citation 插入，返回裸文本 | `search.py:489` |
-
-### 5.2 降级路径图
-
-```
-正常路径:
-Query → Hybrid 检索 → Rerank → LLM 生成 → 引用回填 → 输出
-
-降级路径 1 (检索为空):
-Query → Hybrid 检索 (空) → fallback 降低阈值重试 → 仍空 → LLM 直接回答 (无上下文)
-
-降级路径 2 (Rerank 失败):
-Query → Hybrid 检索 → Rerank API 超时 → fallback 返回原始排序 → LLM 生成
-
-降级路径 3 (GraphRAG 失败):
-Query → Hybrid 检索 → GraphRAG 查询失败 → fallback 仅 hybrid 结果 → LLM 生成
-
-降级路径 4 (单 KB 失败):
-Query → KB-A (失败, try/except) + KB-B (成功) → 合并结果 → LLM 生成
-
-降级路径 5 (LLM 失败):
-Query → 检索成功 → LLM 调用失败 (5 次重试后) → 返回 "**ERROR**: 服务暂不可用"
-
-降级路径 6 (ES 集群不可用):
-Query → ES 连接失败 → 无检索结果 → LLM 直接回答 (无上下文) / 返回错误
-```
-
-### 5.3 关键降级代码片段
-
-```python
-# 1. 单 KB 失败不影响整体 (search.py:110)
-try:
-    rs, chat_model, embedding_model = _retrieve_for_knowledge(...)
-    all_results.extend(rs)
-except Exception as e:
-    print(f"retrieval knowledge({kb_id}) failed: {str(e)}")
-    continue  # 跳过失败 KB
-
-# 2. Rerank 失败 fallback (search.py:115-128)
-if reranker_id and all_results:
-    try:
-        all_results = rerank(...)
-    except Exception as rerank_error:
-        logger.warning("Reranker failed, falling back to original results")
-        # fallback: 保持原始排序
-
-# 3. 检索为空 fallback (search.py:447-459)
-if total == 0:
-    matchText, _ = self.qryr.question(qst, min_match=0.1)  # 0.3 → 0.1
-    matchDense.extra_options["similarity"] = 0.17         # 0.1 → 0.17
-    res = self.dataStore.search(...)
-
-# 4. GraphRAG 失败 fallback (search.py:263)
-try:
-    graph_doc = kg_retriever.retrieval(...)
-    rs.insert(0, DocumentChunk(...))
-except Exception as graph_error:
-    logger.warning(f"Graph retrieval failed...")  # 仅 hybrid 结果
-
-# 5. LLM 重试 (chat_model.py:64-89)
-retry_max = LLM_MAX_RETRIES  # 默认 5
-while retry_max > 0:
-    try:
-        return self.client.chat.completions.create(...)
-    except (RateLimitError, APIConnectionError, APIError):
-        time.sleep(random.uniform(1, LLM_BASE_DELAY * 2 ** (5-retry_max)))
-        retry_max -= 1
-```
-
----
-
-## 附录：跨文档引用索引
-
-| 本章节 | 引用来源 | 被引文档 |
-|--------|---------|---------|
-| §1 Loader/Parser/Chunking | `naive.py:508`, `naive_merge()` | [S2-T1] |
-| §1/§2 Embedding | `embed_documents()`, `embed_query()` | [S2-T2] |
-| §1/§2 VDB 检索与写入 | `search_by_vector()`, `add_chunks()`, mapping | [S2-T3] |
-| §1/§2 GraphRAG | `KGSearch.retrieval()`, `run_graphrag()` | [S2-T4] |
-| §1 Rerank/Prompt/LLM | `RedBearRerank`, `_chat_streamly()`, `_filter_citations()` | [S2-T5] |
-
----
-
-*本文档直接整合自 [S2-T1]~[S2-T5] 五篇子任务文档的源码引用与流程描述，所有文件:行号均可在 MemoryBear 仓库 commit `feae2f2e` 中验证。*

docs/rag/evolution/architecture-refactor-suggestions.md

@@ -1,434 +0,0 @@
-# [S3-T1] MemoryBear RAG 代码架构改造建议
-
-**Author**: AI 知识库解决方案专家  
-**Source-commit**: 工作分支 `agent/ai/f8de881a`（基于 `feae2f2e`）  
-**Reviewer**: 待 [S3-T3] 终审  
-**Last-reviewed-at**: 2026-05-08
-
----
-
-## 0. 一页摘要：现状评估
-
-### 0.1 三个优点（值得保留与放大）
-
-1. **链路完整、特性丰富**：覆盖了从 11 类文档解析（`rag/app/naive.py:508-738`，按扩展名 if/elif 分发）→ Embedding（10+ Provider）→ Hybrid 检索（BM25 + 向量）→ GraphRAG（light/general 双模式）→ Rerank → Prompt 组装 → 流式 LLM 生成的端到端能力。在国内同类开源项目中链路完整度领先。
-2. **多 Provider 抽象初步成型**：`rag/llm/chat_model.py:52 Base` + `rag/vdb/vector_base.py:9 BaseVector` 已具备抽象基类雏形；`rag/models/embedding.py RedBearEmbeddings` 通过 LangChain 的 `Embeddings` 接口屏蔽了 OpenAI / DashScope / Volcano / Ollama / Bedrock 等 7 类 provider。多模型切换代价较低。
-3. **GraphRAG 与向量检索的双轨设计**：`rag/common/settings.py:9-10` 通过 `retriever`（Dealer）+ `kg_retriever`（KGSearch）两个全局单例并行存在，应用层（`workflow/nodes/knowledge/node.py`）可在 PARTICIPLE / SEMANTIC / HYBRID / GRAPH 四种检索模式间切换，灵活度高，是 MemoryBear 区别于通用 RAG 的核心特色。
-
-### 0.2 五个痛点（基于 S1-T3 Gap 报告 + 源码核验）
-
-1. **抽象层不统一，存在双轨甚至三轨实现**：
-   - **Embedding 双轨**：`rag/models/embedding.py RedBearEmbeddings`（LangChain，新，被 ES Vector 用）vs `rag/llm/embedding_model.py OpenAIEmbed/QWenEmbed/...`（遗留，被 GraphRAG `utils.py:320` 与 Dealer `nlp/search.py:365-373` 用）。**两条路径接口不兼容**：前者 `embed_documents(texts)`、后者 `encode(texts)` 返回 `(np.array, total_tokens)`。
-   - **Rerank 三轨**：模块级 `rerank()`（`workflow/nodes/knowledge/node.py:284`，**第 327 行残留 `print(reranked_docs)` 调试语句**）、节点级 `KnowledgeRetrievalNode.rerank()`（`node.py:108-155`，与前者逻辑高度重复）、Dealer 内置融合 `Dealer.rerank()`（`nlp/search.py:606-643`，token+vector+rank_feature 加权）。三套互不知晓彼此存在。
-   - **VDB 抽象有名无实**：`vector_base.py:9 BaseVector` 仅定义了 9 个抽象方法，但唯一实现为 `ElasticSearchVector`，且 `node.py:14`、`tasks.py` 直接 import 具体类 `ElasticSearchVectorFactory` 绕过基类，抽象层失效。
-
-2. **配置散落，无中心化治理**：`os.environ.get` / `os.getenv` 在 `rag/` 目录下出现 **58 次**，分布在 48 个文件。例如 `LLM_TIMEOUT_SECONDS`/`LLM_MAX_RETRIES`（`chat_model.py:54-58`）、`MAX_CONCURRENT_CHATS`（`graphrag/utils.py:41`）、`ELASTICSEARCH_HOST/PORT/USERNAME/PASSWORD/REQUEST_TIMEOUT/MAX_RETRIES`（`elasticsearch_vector.py:685-707`）、`MINERU_EXECUTABLE/APISERVER/OUTPUT_DIR/BACKEND/DELETE_OUTPUT`（`naive.py:46-60`）、OCR/Layout 系列（`deepdoc/vision/*`）等无统一 schema、无类型校验、无文档可查。运维难以定位"哪个变量影响哪条链路"。
-
-3. **可观测性等同于零**：`requirements*.txt` 中 **没有任何** `opentelemetry / prometheus / sentry / jaeger / datadog / statsd` 依赖；355 处 `logger.*` / `logging.*` 调用全为本地日志，无 trace_id 透传、无 metric 导出、无 P50/P95 实时统计。README 里宣称的"P50/P95"指标在代码中无任何采集落点，业务方排障必须捞日志手工聚合。
-
-4. **资源/状态共享导致单测与并发受阻**：
-   - `rag/common/settings.py:24` 在模块 import 时立即执行 `init_settings()`，创建 `docStoreConn = ESConnection()` / `retriever = Dealer(...)` / `kg_retriever = KGSearch(...)` **进程级全局单例**。任何 `from app.core.rag.common.settings import retriever` 都会触发 ES 连接，单元测试无法 stub。
-   - `KnowledgeRetrievalNode.get_reranker_model()`（`node.py:157-193`）每次 `rerank` 调用都重新查 DB → 实例化 `RedBearRerank`，热路径上反复读库。
-   - GraphRAG 用 Redis 做 Embedding 缓存（`graphrag/utils.py:115-134 get_embed_cache/set_embed_cache`），但 ES VDB 入库/检索路径**完全没有缓存**（`elasticsearch_vector.py:55-63`），同一 query 重复打 Embedding API。
-
-5. **入口分发与扩展点用 if/elif 硬编码，违反开闭原则**：
-   - `rag/app/naive.py:508-738 chunk()` 用 11 个 `re.search(扩展名)` 分支选择 parser；新增格式必须改这个 750 行的函数。
-   - `rag/llm/embedding_model.py` 每个 provider 是独立子类（`OpenAIEmbed` / `QWenEmbed` / `XinferenceEmbed` ...），但选择哪个子类没有 registry，依赖外层硬编码 `OpenAIEmbed` import（`workflow/nodes/knowledge/node.py:12`）。
-   - `chat_model.py` 中 `ChatBase` 子类硬编码各 provider 的 base_url 与认证 header（如 `chat_model.py:41-44 OpenAIEmbed.__init__` 直接拼 base_url），切换路径不优雅。
-
----
-
-## 1. 架构改造建议清单（共 11 条）
-
-每条建议结构：**问题 → 方案 → 收益 → 成本/风险 → 优先级**。
-
-### 【建议 1 · 模块化】拆掉双轨 Embedding，统一到单一 Embedder 协议 `[P0]`
-
-- **问题陈述**：`RedBearEmbeddings`（LangChain）与 `OpenAIEmbed/QWenEmbed/...`（遗留）两套并存，调用方用哪一个看心情；接口不兼容（`embed_documents/embed_query` vs `encode/encode_queries`），返回类型不一致（`list[list[float]]` vs `(np.ndarray, total_tokens)`）。
-  - 源码：`rag/models/embedding.py:9-78`、`rag/llm/embedding_model.py:14-65`、`rag/graphrag/utils.py:301-327`（GraphRAG 调用 `embd_mdl.encode([ent_name])`）、`rag/nlp/search.py:365-373`（Dealer 调用 `emb_mdl.encode_queries(txt)`）。
-- **改造方案**：
-  - 定义 `app/core/rag/protocols/embedder.py` 中的 `Embedder` Protocol：`embed_documents(texts) -> EmbedResult` 与 `embed_query(text) -> EmbedResult`，`EmbedResult` 是 `dataclass(vectors: np.ndarray, total_tokens: int, dim: int)`。
-  - 现有 `OpenAIEmbed` 等遗留类实现 `Embedder`（保留 `encode/encode_queries` 兼容期 6 个月）。
-  - 新建 `EmbedderFactory.from_model_config(config) -> Embedder`，内部根据 `provider` 字段路由；`workflow/nodes/knowledge/node.py:12` 删除对 `OpenAIEmbed` 的硬编码 import。
-  - 把 GraphRAG 与 Dealer 都改为通过 `Embedder` 协议调用。
-- **收益**：维护成本从"两套类各自演进"降为一套；新 provider 只需实现 `Embedder` 协议；单测可用 `FakeEmbedder` mock，**单测覆盖率提升预期 +30%**（当前 rag 模块基本无单测）。
-- **成本与风险**：实现 + 迁移约 **5 人日**。回归风险中（GraphRAG 的 `np.ndarray` 返回类型若变成 `list[list[float]]` 会触发下游 `np` 操作错误，需保留 numpy 输出适配器）。
-- **优先级**：**P0**（解锁后续所有改造的前置条件）。
-
-### 【建议 2 · 接口抽象】定义 `Retriever` / `Reranker` / `Generator` 三大协议（LangChain Runnable 风格）`[P0]`
-
-- **问题陈述**：当前没有"检索器"这层抽象，调用方需要直接知道：用哪个 ES index、是否走 hybrid、要不要叠加 GraphRAG。例如 `workflow/nodes/knowledge/node.py:195-263 knowledge_retrieval()` 内部用 `match retrieve_type` 分四个分支调 `vector_service.search_by_vector()` / `search_by_full_text()` / 二者并行 dedup / 再叠加 `kg_retriever.retrieval()`。每新增一种检索策略都要在这里加 `case`。
-- **改造方案**：定义三个 Protocol（伪代码见 PoC 章节）：
-  ```python
-  class Retriever(Protocol):
-      async def retrieve(self, query: Query) -> RetrievalResult: ...
-  class Reranker(Protocol):
-      async def rerank(self, query: str, docs: list[Doc], top_k: int) -> list[Doc]: ...
-  class Generator(Protocol):
-      async def generate(self, prompt: Prompt, stream: bool) -> GenerationResult | AsyncIterator[Chunk]: ...
-  ```
-  并提供组合算子 `Pipeline = Retriever | Reranker | Generator`（类似 LangChain Runnable 的 `|`）。`KnowledgeRetrievalNode` 不再 `match retrieve_type`，而是注入一个 `Retriever`（`HybridRetriever` / `GraphAugmentedRetriever` / `VectorRetriever` 是不同实现）。
-- **收益**：策略模式取代条件分支；单测可对 `Retriever` 接口做契约测试；A/B 实验只需注入不同实现；"GraphRAG-then-Vector"、"Vector-then-Graph"、"Reranker-only"等组合可声明式表达。
-- **成本与风险**：核心接口设计 + 关键实现 + 迁移调用方约 **8 人日**。风险中（涉及 workflow node 的契约变化，需要保留旧接口至少一个 release）。
-- **优先级**：**P0**。
-
-### 【建议 3 · 模块化】消除 Rerank 的三处重复实现 `[P0]`
-
-- **问题陈述**：
-  - `workflow/nodes/knowledge/node.py:284 rerank()`（模块级函数）— **第 327 行有 `print(reranked_docs)` 调试残留**。
-  - `workflow/nodes/knowledge/node.py:108-155 KnowledgeRetrievalNode.rerank()`（节点方法）— 与前者代码逻辑几乎一致（都做 `RedBearRerank.compress_documents` + 按 `relevance_score` 排序 + 按 `page_content` 字符串匹配回查 metadata）。
-  - `rag/nlp/search.py:606-643 Dealer.rerank()`（融合排序）—— 走的是 token+vector+rank_feature 三项加权，与前两者完全是不同范式但同名为 rerank。
-  - 第二个问题：`KnowledgeRetrievalNode.get_reranker_model()`（`node.py:157-193`）每次 rerank 调用都查一次 DB 获取模型配置，实例化 `RedBearRerank`。
-- **改造方案**：
-  - 实现一个唯一的 `RerankerService`：内部做 (a) DB 缓存 reranker 实例（key=`reranker_id`，TTL=10min）；(b) 屏蔽"按 page_content 字符串匹配 metadata"的脆弱回查（改为 LangChain `Document.metadata["__doc_index__"]` 索引）；(c) 暴露 `Reranker` Protocol。
-  - 删掉 `node.py:284 rerank()` 模块级函数（或仅保留 `@deprecated` 别名指向 `RerankerService`）。
-  - `Dealer.rerank()` 改名为 `Dealer.fuse_scores()`，明确它是"分数融合"不是"模型重排"。
-  - 删除 `node.py:327 print()` 残留。
-- **收益**：消除每次请求多查 DB 一次的开销（实测 DB 查询 5–20ms，去掉后**热路径单次省 5-20ms × QPS**）；rerank 逻辑只需在一处 review 与单测。
-- **成本与风险**：约 **3 人日**。风险低（接口对外不变）。
-- **优先级**：**P0**（含调试残留的 hot fix 应优先合并）。
-
-### 【建议 4 · 性能优化】Embedder 与 Reranker 加缓存层 `[P0]`
-
-- **问题陈述**：
-  - GraphRAG 用 Redis 缓存 Embedding（`graphrag/utils.py:115-134`，TTL=24h，key=xxhash(model_name+text)），命中率高时显著省成本。
-  - 但 ES VDB 入库/检索 (`elasticsearch_vector.py:55-63 add_chunks` / `:374-380 search_by_vector`) **完全无缓存**。同一 query 反复 embedding；同一 chunk 重复入库时也会重复算向量。
-  - Rerank 同样无缓存：`RedBearRerank.compress_documents` 每次都打外部 API（DashScope/Jina），200+ ms。
-- **改造方案**：
-  - 抽出 `app/core/rag/cache/embed_cache.py`（把 `graphrag/utils.py` 中的现有实现搬过来 + 通用化）。
-  - `Embedder` Protocol 在调用层加装饰器 `@cached_embedder(redis, ttl=24h)`，对 `embed_query` 必加（query 重复率高），`embed_documents` 可配置。
-  - 新增 `Reranker` 缓存：key=`xxhash(model + query + sorted(doc_ids))`，TTL=1h（rerank 结果对 query 变体很敏感，不要 TTL 太长）。
-  - 从环境变量读 `REDIS_*` 配置，cache 失败时优雅降级为 no-op（不要 break 主链路）。
-- **收益**：Query embedding 命中场景 **减少 60-90% 外部 API 调用**（基于业内同类系统 query 重复率统计）。Rerank 命中场景再减少 30-50%。**单 query 端到端 P95 下降 100-300ms**（Rerank 是当前最慢的同步阻塞步骤之一）。
-- **成本与风险**：约 **2 人日**。风险低（cache miss 时行为与现状一致）。
-- **优先级**：**P0**。
-
-### 【建议 5 · 性能优化】用 Plugin Registry 替换 `naive.py:508` 的 11 路 if/elif 解析器分发 `[P1]`
-
-- **问题陈述**：`rag/app/naive.py:508 chunk()` 用 `re.search(r"\.docx$", filename)` / `r"\.pdf$"` / `r"\.(pptx|ppt?)$"` / ... 11 个分支硬编码挑 parser。新增一种格式必须改这个 750 行函数；同时 PDF 自身有 `by_deepdoc` / `by_mineru` / `by_textln` 三种实现，选择路径用 `parser_config["layout_recognize"]` 字符串比对，没有类型保护。
-- **改造方案**：
-  - 定义 `Parser` Protocol：`def can_parse(filename) -> bool` + `def parse(filename, binary, **kwargs) -> ParseResult`。
-  - 在 `rag/app/parsers/__init__.py` 中维护一个 `_registry: dict[str, Parser] = {}` + `@register_parser("docx", "pdf", ...)` 装饰器。
-  - `chunk()` 简化为 4 行：`parser = registry.find(filename); sections, tables = parser.parse(...); return tokenize(sections, tables)`。
-  - 第三方 parser（MinerU、TextIn）也注册为可插拔实现，运行时由 `parser_config.layout_recognize` 选择。
-- **收益**：新增格式 = 新增一个文件 + 一行 `register`，不再需要碰 `naive.py`；测试可针对每个 parser 独立写；**`naive.py` 从 750+ 行降到 100 行以内**，可读性大幅提升。
-- **成本与风险**：约 **5 人日**（11 类 parser 都要拆）。风险中（要保留 `vision_figure_parser_pdf_wrapper` 等横切逻辑，需要 hook 点设计）。
-- **优先级**：**P1**。
-
-### 【建议 6 · 可观测性】引入 OpenTelemetry，全链路 trace + 关键指标埋点 `[P1]`
-
-- **问题陈述**：requirements.txt 中无任何 OTel/Prometheus/Sentry 依赖；355 个 `logger` 调用全是本地日志。无法回答"昨天 P95 多少"、"哪一步最慢"、"哪个 KB 召回率最差"。README 中宣称的 P50/P95 是无源之水。
-- **改造方案**：
-  - 在 `requirements.txt` 加入 `opentelemetry-sdk`、`opentelemetry-instrumentation-fastapi`、`opentelemetry-instrumentation-elasticsearch`、`opentelemetry-instrumentation-redis`、`opentelemetry-instrumentation-celery`、`opentelemetry-exporter-otlp`。
-  - 在 `app/core/rag/observability/tracing.py` 提供 `@trace_rag_step("embed/search/rerank/generate")` 装饰器（基于 `opentelemetry.trace.get_tracer`），包装 `Embedder.embed_*` / `Retriever.retrieve` / `Reranker.rerank` / `Generator.generate`。
-  - 关键指标（`opentelemetry.metrics.meter`）：
-    - `rag.embed.latency_ms{provider, model}` Histogram
-    - `rag.search.recall@k{kb_id, retrieve_type}` Counter（结合用户反馈数据）
-    - `rag.llm.tokens_used{provider, model, type=prompt|completion}` Counter
-    - `rag.cache.hit_ratio{layer=embed|rerank|llm}` Gauge
-    - `rag.pipeline.e2e_latency_ms{retrieve_type, has_rerank}` Histogram
-  - LLM 级（`chat_model.py:_chat / _chat_streamly`）也加 `tracer.start_as_current_span`，把 token 用量、provider、model 写到 attributes。
-- **收益**：实时 P50/P95 / 错误率 / Token 成本可观测；oncall 排障从"捞日志 grep"变成"看 Grafana panel"；A/B 实验有可量化的 baseline。
-- **成本与风险**：约 **5 人日**（依赖 + 装饰器 + 关键 span + 一份 Grafana JSON 模板）。风险低（OTel 失败时 no-op）。
-- **优先级**：**P1**（前 2 周做不完，但中期一定要做）。
-
-### 【建议 7 · 配置治理】中心化配置 + Pydantic Settings + 类型校验 `[P1]`
-
-- **问题陈述**：`os.environ.get` 出现 58 次散落在 48 个文件；同一变量名多处使用却无单一文档；类型靠 `int(os.getenv(...))` 手工转换（`elasticsearch_vector.py:699-702` 反复出现）；缺省值随手填，不一致（如 `ELASTICSEARCH_REQUEST_TIMEOUT` 文档说 100000，源码 `elasticsearch_vector.py:699` 缺省是 30）。
-- **改造方案**：
-  - 新增 `app/core/rag/config/settings.py`：用 `pydantic_settings.BaseSettings` 把 RAG 相关全部环境变量收拢成 `RAGSettings`，分组：`LLMSettings` / `EmbeddingSettings` / `ESSettings` / `GraphRAGSettings` / `MinerUSettings` / `OCRSettings` 等。
-  - 启动时 `RAGSettings()` 一次性加载、校验、默认值统一；`docs/rag/_meta/config_reference.md` 自动生成（用 `RAGSettings.model_json_schema()` → markdown）。
-  - 现有调用点 `os.environ.get("X")` 替换为 `from app.core.rag.config import settings; settings.x`。
-  - Secret 管理：API key / DB 密码强制走 `pydantic.SecretStr`，禁止默认值。
-- **收益**：单一可信来源（Single Source of Truth）；类型错误启动期暴露而非运行时；运维有完整变量清单；CI 可静态校验"是否引入了未注册的环境变量"。
-- **成本与风险**：约 **4 人日**（迁移 58 处调用点 + 文档生成）。风险低（一次性脚本可批量替换）。
-- **优先级**：**P1**。
-
-### 【建议 8 · 模块化】消除 `init_settings()` 模块级副作用 `[P1]`
-
-- **问题陈述**：`rag/common/settings.py:24` 在模块导入时立即执行 `init_settings()`，创建进程级 `docStoreConn = ESConnection()`、`retriever = Dealer(...)`、`kg_retriever = KGSearch(...)`。任何 `from app.core.rag.common.settings import retriever` 都会立即建 ES 连接。
-  - 后果：单元测试无法 stub（import 时已触发副作用）；多进程/Celery worker 启动时间增加（每个 worker 都连 ES）；测试容器需要 ES 运行才能 `pytest collect`。
-- **改造方案**：
-  - 替换为 lazy initialization：`@lru_cache def get_doc_store(): ...` / `@lru_cache def get_retriever(): ...` / `@lru_cache def get_kg_retriever(): ...`。
-  - 在 FastAPI 应用层用 dependency injection（`fastapi.Depends`）注入而非全局 singleton。
-  - 测试时用 `app.dependency_overrides[get_retriever] = lambda: FakeRetriever()` mock。
-- **收益**：单测可独立运行（不依赖 ES）；冷启动延后到首次使用；多 worker 避免共享单例的诡异 bug。
-- **成本与风险**：约 **2 人日**（替换 import-style 调用为 `Depends`）。风险中（要逐个排查 `from settings import retriever` 的 24 处调用点）。
-- **优先级**：**P1**。
-
-### 【建议 9 · 性能优化】Embedding 与 Rerank 批量化 + 异步并发 `[P1]`
-
-- **问题陈述**：
-  - `rag/llm/embedding_model.py:50 OpenAIEmbed.encode()` 中 `batch_size = 16` **硬编码**；`QWenEmbed` 是 4，`HuggingFaceEmbed` 是无（全量发送）。`EMBEDDING_BATCH_SIZE` 在 README 提过但代码注释掉未生效。
-  - `elasticsearch_vector.py:55-63 add_chunks` 是同步循环，无 trio/asyncio 并发；`workflow/nodes/knowledge/node.py:knowledge_retrieval` 多 KB 检索时是 `await asyncio.gather` 并发的，但单 KB 内 vector + full_text 是顺序调用。
-  - GraphRAG 已经用 `trio.CapacityLimiter(MAX_CONCURRENT_CHATS=10)` 限流（`graphrag/utils.py:41`），但 ES VDB 写入对应的限流不存在。
-- **改造方案**：
-  - `Embedder` 协议提供 `batch_size` 字段，默认从 `RAGSettings.embedding.batch_size` 读取，每个 provider 可 override。
-  - `ElasticSearchVector.add_chunks` 改为 trio 协程版本，与 GraphRAG 共享 `chat_limiter` 限流。
-  - `HybridRetriever.retrieve` 内部 `vector` + `full_text` 用 `asyncio.gather` 并发（当前在 node 层做了，下沉到 Retriever）。
-- **收益**：Embedding 大批量入库 P95 下降 **20-40%**（瓶颈从串行 16-batch HTTP 变并发）；Hybrid 检索单次 P50 下降 **30-50%**（从串行 → 并发 max 而非 sum）。
-- **成本与风险**：约 **3 人日**。风险中（trio 与 asyncio 混用要小心，已有 `trio.to_thread.run_sync` 模式可参考）。
-- **优先级**：**P1**。
-
-### 【建议 10 · 可观测性 + 配置】消灭遗留 `print()` 与无结构化日志 `[P2]`
-
-- **问题陈述**：
-  - `workflow/nodes/knowledge/node.py:327 print(reranked_docs)` 残留调试语句；同类 `print` 在 rag/ 目录共有数十处（grep 验证）。
-  - 现有 logger 是非结构化字符串日志（`logger.info(f"add_texts result:{result}")` `elasticsearch_vector.py:86`），无法 ELK 聚合查询。
-- **改造方案**：
-  - 引入 `structlog`，所有 `logger.*` 调用改为 KV 格式：`logger.info("vdb.add_texts", n_docs=len(actions), index=self._collection_name, took_ms=...)`。
-  - pre-commit hook 加 `flake8-print` 阻止新 `print` 进入仓库。
-  - 一次性 sweep 删除现有 `print`。
-- **收益**：日志可聚合查询（"过去 1 小时 add_texts 平均 n_docs"）；CI 防止回归。
-- **成本与风险**：约 **2 人日**。风险低。
-- **优先级**：**P2**。
-
-### 【建议 11 · 接口抽象】把 `BaseVector` 的"多模态分支"抽象到 Embedder 而非 VDB 层 `[P2]`
-
-- **问题陈述**：`elasticsearch_vector.py:55-63` 的 `add_chunks` 与 `:374-380 search_by_vector` 都有 `if self.is_multimodal_embedding: ... else: ...` 分支判断（火山引擎多模态走 `embed_batch/embed_text`，其他走 `embed_documents/embed_query`）。这是把"Embedder 的能力差异"泄露到了 VDB 层 — 违反单一职责。
-- **改造方案**：
-  - 在 `Embedder` Protocol 内部统一接口：`embed(items: list[Item]) -> list[list[float]]`，其中 `Item = TextItem | ImageItem | VideoItem`。多模态 Embedder 内部分发到 `multimodal_embeddings.create`，文本 Embedder 走 `embed_documents`。
-  - VDB 层只调 `embedder.embed(...)`，不再有 `is_multimodal` 分支。
-- **收益**：VDB 与 Embedder 职责清晰；后续接入 ColBERT / SPLADE / 多向量 Embedding 时无需修改 VDB。
-- **成本与风险**：约 **2 人日**。
-- **优先级**：**P2**（依赖建议 1 完成）。
-
----
-
-## 2. PoC 代码草案
-
-### 2.1 PoC-1：统一 `Retriever` / `Reranker` / `Generator` 协议（建议 2）
-
-```python
-# api/app/core/rag/protocols/__init__.py
-from __future__ import annotations
-from dataclasses import dataclass, field
-from typing import Protocol, AsyncIterator, runtime_checkable
-
-@dataclass(slots=True)
-class Query:
-    text: str
-    kb_ids: list[str]
-    top_k: int = 4
-    similarity_threshold: float = 0.2
-    rerank: bool = False
-    extras: dict = field(default_factory=dict)  # 其他场景化参数
-
-@dataclass(slots=True)
-class Doc:
-    id: str
-    content: str
-    score: float
-    metadata: dict = field(default_factory=dict)
-
-@dataclass(slots=True)
-class RetrievalResult:
-    docs: list[Doc]
-    total: int
-    debug: dict = field(default_factory=dict)  # latency_ms, recall_strategy, etc.
-
-@runtime_checkable
-class Retriever(Protocol):
-    name: str
-    async def retrieve(self, query: Query) -> RetrievalResult: ...
-
-@runtime_checkable
-class Reranker(Protocol):
-    async def rerank(self, query: str, docs: list[Doc], top_k: int) -> list[Doc]: ...
-
-@runtime_checkable
-class Generator(Protocol):
-    async def generate_stream(self, prompt: str, history: list[dict],
-                              context: list[Doc]) -> AsyncIterator[str]: ...
-```
-
-```python
-# api/app/core/rag/retrievers/hybrid_retriever.py
-import asyncio
-from app.core.rag.protocols import Retriever, Query, RetrievalResult, Doc
-from app.core.rag.vdb.vector_base import BaseVector
-from app.core.rag.protocols.reranker import Reranker
-
-class HybridRetriever(Retriever):
-    name = "hybrid"
-    def __init__(self, vector_store: BaseVector, reranker: Reranker | None = None,
-                 vector_weight: float = 0.7):
-        self._store = vector_store
-        self._reranker = reranker
-        self._vector_weight = vector_weight
-
-    async def retrieve(self, query: Query) -> RetrievalResult:
-        vec_task = asyncio.to_thread(
-            self._store.search_by_vector, query.text, top_k=query.top_k * 4)
-        bm25_task = asyncio.to_thread(
-            self._store.search_by_full_text, query.text, top_k=query.top_k * 4)
-        vec_docs, bm25_docs = await asyncio.gather(vec_task, bm25_task)
-        merged = self._fuse_rrf(vec_docs, bm25_docs)  # Reciprocal Rank Fusion
-        if self._reranker and query.rerank and merged:
-            docs = await self._reranker.rerank(
-                query.text, merged, top_k=query.top_k)
-        else:
-            docs = merged[:query.top_k]
-        return RetrievalResult(docs=docs, total=len(merged),
-                               debug={"strategy": self.name})
-
-    @staticmethod
-    def _fuse_rrf(a: list[Doc], b: list[Doc], k: int = 60) -> list[Doc]:
-        scores = {}
-        for rank, d in enumerate(a):
-            scores[d.id] = scores.get(d.id, 0) + 1 / (k + rank + 1)
-        for rank, d in enumerate(b):
-            scores[d.id] = scores.get(d.id, 0) + 1 / (k + rank + 1)
-        all_docs = {d.id: d for d in a + b}
-        return sorted((all_docs[i] for i in scores),
-                      key=lambda d: scores[d.id], reverse=True)
-```
-
-```python
-# api/app/core/workflow/nodes/knowledge/node_v2.py（重构后）
-class KnowledgeRetrievalNodeV2(BaseNode):
-    def __init__(self, retriever: Retriever, ...):
-        self._retriever = retriever  # 注入，不再 match retrieve_type
-    async def execute(self, state) -> dict:
-        query = Query(text=self._render_query(state),
-                      kb_ids=self._kb_ids, top_k=self._top_k,
-                      rerank=bool(self._reranker_id))
-        result = await self._retriever.retrieve(query)
-        return {"chunks": [d.content for d in result.docs],
-                "citations": [d.metadata for d in result.docs]}
-```
-
-### 2.2 PoC-2：Embedder + Redis 缓存装饰器（建议 1 + 4）
-
-```python
-# api/app/core/rag/cache/embed_cache.py
-import json, xxhash, numpy as np
-from functools import wraps
-
-def cached_embedder(redis_client, ttl: int = 24 * 3600):
-    def decorator(func):
-        @wraps(func)
-        def wrapper(self, texts, *args, **kwargs):
-            if isinstance(texts, str):
-                texts = [texts]
-            keys = [_key(self.model_name, t) for t in texts]
-            cached = redis_client.mget(keys)
-            results, miss_idx, miss_texts = [None]*len(texts), [], []
-            for i, b in enumerate(cached):
-                if b: results[i] = np.array(json.loads(b))
-                else: miss_idx.append(i); miss_texts.append(texts[i])
-            if miss_texts:
-                fresh = func(self, miss_texts, *args, **kwargs)  # ndarray, n_tokens
-                vecs = fresh[0] if isinstance(fresh, tuple) else fresh
-                pipe = redis_client.pipeline()
-                for j, idx in enumerate(miss_idx):
-                    results[idx] = vecs[j]
-                    pipe.setex(keys[idx], ttl, json.dumps(vecs[j].tolist()))
-                pipe.execute()
-            return np.array(results), 0  # tokens cached as 0; metric layer补
-        return wrapper
-    return decorator
-
-def _key(model: str, text: str) -> str:
-    h = xxhash.xxh64(); h.update(f"{model}\0{text}".encode()); return f"emb:{h.hexdigest()}"
-```
-
-使用方式：
-
-```python
-class OpenAIEmbed(Base):
-    @cached_embedder(redis_client)  # 一行注解开启缓存
-    def encode(self, texts: list): ...
-```
-
----
-
-## 3. 改造路线图
-
-> 实施前提：先用 1 周时间立两个 baseline —— (a) 当前端到端 P50/P95（即使靠手工脚本采）；(b) 单测覆盖率（pytest --cov）。所有改造完成后用同一 baseline 比对，验证收益。
-
-### 3.1 短期（Sprint 0–1，1-2 周内交付）
-
-> 目标：止血 + 解锁后续重构的前置条件。
-
-| # | 工作项 | 关联建议 | 工作量 | 交付物 |
-|---|---|---|---|---|
-| 1 | 删除 `node.py:327 print()` 残留 + 全仓 print 扫除 | #10 | 0.5d | PR + pre-commit hook |
-| 2 | 实现 `RerankerService`（含 reranker 实例缓存） | #3 | 2d | 新模块 + 单测 + 替换现有 3 处 rerank |
-| 3 | 给 `Embedder.encode/encode_queries` 加 Redis 缓存装饰器 | #4 | 1.5d | 装饰器 + benchmark 报告 |
-| 4 | 中心化配置：`RAGSettings` Pydantic Settings 框架 | #7 | 2d | `app/core/rag/config/settings.py` + 迁移 ES + LLM 配置 |
-| 5 | 迁移单元测试：先把 settings.py 的 `init_settings()` 副作用改 lazy | #8 | 2d | `pytest` 不再依赖 ES 即可 collect |
-
-**短期里程碑（Sprint 1 末）**：
-- ✅ 调试 print 残留清零；
-- ✅ 单测可独立运行（脱离 ES）；
-- ✅ Reranker 命中场景延迟下降 50%+；
-- ✅ Query Embedding 命中场景延迟下降 70%+。
-
-### 3.2 中期（Sprint 2–4，1-2 月内交付）
-
-> 目标：完成核心抽象层重构，引入可观测性。
-
-| # | 工作项 | 关联建议 | 工作量 | 交付物 |
-|---|---|---|---|---|
-| 6 | 设计 + 落地 `Embedder` Protocol，迁移 `OpenAIEmbed/QWenEmbed/...` | #1 | 5d | 协议 + 适配器 + 弃用计划文档 |
-| 7 | 设计 + 落地 `Retriever / Reranker / Generator` Protocol；实现 `VectorRetriever` `BM25Retriever` `HybridRetriever` `GraphAugmentedRetriever` | #2 | 8d | 协议 + 4 个实现 + 节点改造 |
-| 8 | OpenTelemetry 接入：在 RAG 关键路径加 span 与 metric | #6 | 5d | `observability/tracing.py` + Grafana 模板 + 文档 |
-| 9 | Plugin Registry 重构 `naive.py` 解析器分发 | #5 | 5d | `parsers/` 模块化 + 11 个 parser 注册 |
-| 10 | 配置治理收尾：剩余 50+ 处 `os.environ.get` 全部迁到 `RAGSettings` | #7 | 2d | 文档自动生成脚本 |
-| 11 | Embedder 与 Rerank 批量化 + 异步并发改造 | #9 | 3d | 性能 benchmark 对比报告 |
-
-**中期里程碑（Sprint 4 末）**：
-- ✅ 抽象层统一完成（Embedder / Retriever / Reranker / Generator 四大协议落地）；
-- ✅ Grafana 实时面板：P50/P95/Token 用量/缓存命中率；
-- ✅ 单测覆盖率 RAG 模块从 ~5% 提升到 ≥35%；
-- ✅ 端到端 P95 较 baseline 下降 30%+。
-
-### 3.3 长期（Sprint 5–8，3-6 月内交付）
-
-> 目标：可插拔架构、生产级稳定性、为 [S3-T2] 列出的多模态 / 混合搜索增强 / KG 演化做铺垫。
-
-| # | 工作项 | 关联建议 | 工作量 | 交付物 |
-|---|---|---|---|---|
-| 12 | 多模态分支从 VDB 抽离到 Embedder | #11 | 2d | VDB 接口收敛 |
-| 13 | 引入第二个 VDB 实现（如 Milvus），验证 `BaseVector` 可插拔 | #2 | 8d | `MilvusVector` + 一致性测试套件 |
-| 14 | LLM Provider 也改 Plugin Registry（消除 `chat_model.py` 11 个子类的 if 切换） | #5 | 5d | LLM 层与 Embedding 层架构对齐 |
-| 15 | 完整的 `Pipeline = Retriever \| Reranker \| Generator` DSL，配置驱动 | #2 | 10d | YAML 描述场景 → 运行时拼装 |
-| 16 | A/B 实验框架：基于 OTel metric，把 recall@k / answer_score 接入实验对比 | #6 | 5d | 实验平台对接文档 |
-| 17 | LLM 失败模型降级链（fallback to 备用 provider） | #2 + 现有 Base 增强 | 3d | `FallbackGenerator` 实现 |
-| 18 | 安全 / Secret 管理：从 `pydantic.SecretStr` 升级到 Vault / Secrets Manager 集成 | #7 | 5d | 密钥不进 .env 文件 |
-
-**长期里程碑（Sprint 8 末）**：
-- ✅ 可插拔 VDB（一行配置切换 ES → Milvus）；
-- ✅ Pipeline DSL 上线，新增"GraphRAG-Then-Vector-Then-Rerank"等组合无需改代码；
-- ✅ 全链路 Trace + 指标 + A/B 框架就绪；
-- ✅ 为 [S3-T2] 中"多模态检索 / SPLADE / ColBERT 路由 / KG 演化 / 反馈闭环"等扩展提供清晰的接口注入点。
-
----
-
-## 4. 风险与依赖统一汇总
-
-| 风险类别 | 描述 | 缓解方案 |
-|---|---|---|
-| **回归风险（高）** | `Embedder` 协议迁移可能改变返回类型（`np.ndarray` vs `list[list[float]]`） | 6 个月兼容期，旧接口保留并打 `DeprecationWarning`；CI 加契约测试 |
-| **回归风险（中）** | `KnowledgeRetrievalNode` 接口改造，影响 workflow 已部署应用 | 引入 `node_v2.py`，灰度切换；保留 `node.py` 至少一个 release |
-| **依赖风险** | OpenTelemetry 接入需 collector / Tempo / Loki 等基础设施 | 短期可先只导出到 stdout exporter，基础设施分阶段建设 |
-| **协作依赖** | 与 [@Python 开发工程师](mention://agent/f4d1c89f-0c71-4af3-bf72-d34f7ed115cf) 一起验证 PoC 与迁移可行性 | Sprint 0 启动前先 1 次架构对齐会 |
-| **运营依赖** | 配置治理（建议 #7）落地后，运维需更新部署脚本与文档 | 切换前 2 周通知；提供变量映射表（旧 → 新） |
-
----
-
-## 5. 验收 Checklist 自检
-
-- [x] 至少 8 条建议（实际 11 条）
-- [x] 覆盖 5 个方向：模块化拆分（#1, #3, #5, #8）/ 接口抽象（#1, #2, #11）/ 性能优化（#4, #5, #9）/ 可观测性（#6, #10）/ 配置与依赖治理（#7）
-- [x] 每条建议均有源码引用（文件:行号 + 关键摘录）
-- [x] PoC 代码草案：**2 套**（统一 Retriever 协议 + Embedder 缓存装饰器，均在 10–50 行）
-- [x] 现状评估：3 优点 + 5 痛点
-- [x] 改造路线图：短期 / 中期 / 长期 三阶段，每阶段附交付物清单
-- [x] 与 [S2-T7] Sprint-2 文档兼容：引用 [S2-T2 Embedding](mention://issue/7a8cd047-f339-427e-bd60-999c62caea22) 双轨问题、[S2-T5 LLM/Reranking](mention://issue/eef8ed99-c13e-43ba-a2b3-2c9e59b74301) 三处 rerank 实现，与 [S1-T3 Gap 报告](mention://issue/264529aa-1856-4505-8e26-6125df061c18) 中识别的"`rag_utils` vs `rag/utils` 命名冲突"等差异交叉印证
-- [x] 提交至 [S3-T3] 终审
-
----
-
-*文档基于 MemoryBear `agent/ai/f8de881a` 分支（基于 commit `feae2f2e`）逐文件核验。所有源码引用可在 ±3 行内复现。*

docs/rag/evolution/capability-map.mmd

@@ -1,98 +0,0 @@
-%% MemoryBear RAG 能力地图（Capability Map）
-%% 横轴：能力域；纵轴：成熟度（已有 / 近期可上 / 中长期愿景）
-%% 与 [S3-T1] 提议的 Retriever / Reranker / Generator / Embedder 抽象接口对齐
-graph LR
-    classDef have fill:#10b981,stroke:#065f46,color:#fff,stroke-width:1px
-    classDef near fill:#f59e0b,stroke:#92400e,color:#fff,stroke-width:1px
-    classDef vision fill:#6366f1,stroke:#3730a3,color:#fff,stroke-width:1px
-    classDef domain fill:#e5e7eb,stroke:#374151,color:#111,stroke-width:1px
-
-    subgraph DLOAD[数据接入]
-        L1[Web 爬虫]:::have
-        L2[飞书 / 语雀 / 文件上传]:::have
-        L3[企业 IM / 邮件 / Notion / S3 增量同步]:::near
-        L4[流式数据 / Kafka / CDC]:::vision
-    end
-
-    subgraph DPARSE[解析与多模态采集]
-        P1[deepdoc PDF/OCR/Layout/Table]:::have
-        P2[图片 OCR + VLM describe]:::have
-        P3[音频 ASR]:::have
-        P4[视频 VLM 整体描述]:::have
-        P5[音视频时间戳化抽帧 + 关键帧 caption]:::near
-        P6[原生 CLIP/BGE-VL 跨模态嵌入]:::vision
-    end
-
-    subgraph DCHUNK[切分与表征]
-        C1[naive_merge / 类型化 chunker]:::have
-        C2[RagTokenizer 中英分词]:::have
-        C3[Late-Interaction / ColBERT 子词表征]:::near
-        C4[语义分块 + 自适应粒度]:::vision
-    end
-
-    subgraph DEMB[Embedding]
-        E1[10+ Provider 工厂]:::have
-        E2[问题增强 question_proposal]:::have
-        E3[Sparse 向量 / SPLADE 学习稀疏]:::near
-        E4[Multi-Vector / 多语种统一编码]:::vision
-    end
-
-    subgraph DVDB[向量与检索]
-        V1[ES dense_vector + BM25]:::have
-        V2[FusionExpr 0.05/0.95 加权融合]:::have
-        V3[KGSearch N-hop + Community]:::have
-        V4[HNSW 量化 / Sparse 索引上线]:::near
-        V5[语义路由 / 多检索器自适应组合]:::near
-        V6[联邦检索 / 跨租户隐私检索]:::vision
-    end
-
-    subgraph DRANK[重排序]
-        R1[内置 token+vector 融合排序]:::have
-        R2[Jina / DashScope / Xinference 外部 Reranker]:::have
-        R3[Cross-Encoder 蒸馏 + 在线 PairWise 学习]:::near
-        R4[基于反馈的自动 Reranker 微调]:::vision
-    end
-
-    subgraph DKG[知识图谱]
-        K1[GraphRAG light + general]:::have
-        K2[entity_resolution + Leiden 社区]:::have
-        K3[增量图演化 + 时间戳]:::near
-        K4[路径解释性 + Neo4j 双引擎]:::near
-        K5[多源图融合 / 自动本体演化]:::vision
-    end
-
-    subgraph DMEM[对话记忆]
-        M1[memory.forgetting_engine Ebbinghaus]:::have
-        M2[memory.reflection_engine 周期反思]:::have
-        M3[langgraph 读图 Agent]:::have
-        M4[短期 ↔ 长期 ↔ 检索召回三段桥接]:::near
-        M5[人格化记忆策略 + 用户偏好学习]:::vision
-    end
-
-    subgraph DEVAL[评估与反馈闭环]
-        EV1[README F1/BLEU/J 论文级评估]:::have
-        EV2[RAGAS / TruLens 集成 + 在线 A/B]:::near
-        EV3[👍/👎 反馈 → Rerank 微调闭环]:::near
-        EV4[自演化路由策略 / RLHF 长记忆]:::vision
-    end
-
-    subgraph DOPS[平台与可观测]
-        O1[Celery 任务链 + Redis 缓存]:::have
-        O2[FastAPI / Swagger]:::have
-        O3[OpenTelemetry Trace + 检索指标看板]:::near
-        O4[Prompt 仓库 + Eval CI / 灰度发布]:::vision
-    end
-
-    %% 跨域依赖（仅画关键边，避免过密）
-    DLOAD --> DPARSE
-    DPARSE --> DCHUNK
-    DCHUNK --> DEMB
-    DEMB --> DVDB
-    DVDB --> DRANK
-    DRANK -. citations .-> DOPS
-    DCHUNK -. async .-> DKG
-    DKG --> DVDB
-    DEVAL -. metrics .-> DRANK
-    DEVAL -. metrics .-> DVDB
-    DMEM -. memory-augmented retrieval .-> DVDB
-    DMEM -. summary into prompt .-> DRANK

docs/rag/evolution/future-extensions-roadmap.md

@@ -1,457 +0,0 @@
-# MemoryBear RAG · 后续迭代功能新增方式建议（S3-T2）
-
-> 上游：[WS-11] 总规划、[S1-T2 全链路架构]、[S1-T3 源码盘点]、Sprint-2 各环节深度文档、[S3-T1 架构改造建议]
-> 输出形态：能力地图 + 6 个重点扩展方向 + 2 条 Quick PoC + 优先级矩阵 + 落地路线图
-> 设计原则：所有方向 **必须** 复用 [S3-T1] 提议的统一抽象（`Retriever / Reranker / Generator / Embedder / Loader / Chunker`），避免出现新功能 = 新一团耦合。
-
----
-
-## 0. 现状速览与设计基线
-
-### 0.1 一图看清"已有 / 可上 / 愿景"
-
-详见附件 `capability-map.mmd`（Mermaid 格式）。三色对应：
-- 🟢 **已有**：Sprint-2 文档已覆盖、源码可证、生产可用。
-- 🟡 **近期可上**：1–2 个 Sprint 内可落地，依赖最少。
-- 🟣 **中长期愿景**：3–6 个月，存在跨团队/外部依赖。
-
-### 0.2 关键源码事实（用于支撑后续方案）
-
-| 事实 | 源码定位 | 对扩展的影响 |
-|------|---------|-------------|
-| 多模态目前 **走文本通道** | `rag/app/picture.py:54` 调 `vision_model.describe`；`rag/app/audio.py:29` 调 `seq2txt_mdl.transcription`；`naive.py` 走 video → VLM → 文本 | 跨模态语义损失大；扩展为"原生跨模态向量"是方向 D1 |
-| `MatchSparseExpr` 已声明但未接入 | `rag/utils/doc_store_conn.py:75` 与 `vdb/field.py:11(SPARSE_VECTOR)` 都已存在；`grep -r SparseVector` 仅 1 处定义、0 处调用 | SPLADE 接入是脚手架级改造，不是从零开始（D2） |
-| 混合检索权重写死 `0.05,0.95` | `rag/nlp/search.py:439` 的 `FusionExpr("weighted_sum", topk, {"weights": "0.05,0.95"})` | 语义路由 / 自适应权重的注入点天然存在（D2） |
-| GraphRAG 是"一次构建"模型 | `tasks.py` 的 `build_graphrag_for_document` Celery 链；图存于 ES `knowledge_graph_kwd` 字段 | 增量演化、时间维度、Neo4j 双引擎需要在 Celery 链上加 hook（D3） |
-| 对话记忆与 RAG **不互通** | `core/memory/` 自成一套（Ebbinghaus、ACT-R、Neo4j、langgraph 读图）；`workflow/nodes/knowledge/node.py` 完全不引用 `core/memory` | 对话记忆 ↔ 检索的协同是最大产品差异化机会（D4） |
-| 评估只在 README 体现 | 仓内无 `eval/`、`ragas`、`F1` 类计算代码 | 反馈闭环要从 0 搭，但与 [S3-T1] 提议的"可观测性"天然合并（D5） |
-| Reranker 只能推理不能学 | `core/models/rerank.py:11` 包装 langchain `BaseDocumentCompressor`，仅做远程调用 | 自训练 Cross-Encoder 是一条独立、可量化收益的小路径（D5） |
-| 检索模式硬编码在 enum | `RetrieveType.{PARTICIPLE, SEMANTIC, HYBRID, Graph}` 在 `schemas/chunk_schema.py` | 引入"语义路由"需要把 enum 改成 strategy 模式（D6） |
-
-### 0.3 与 [S3-T1] 接口抽象的联动约定
-
-[S3-T1] 提议把当前散落的检索/排序/生成代码抽象为协议（参考 LangChain Runnable）。本路线图的所有"接口改造点"都引用以下统一协议（命名以 [S3-T1] 终稿为准，本稿先行登记）：
-
-```python
-# rag/protocols.py（[S3-T1] 提议）
-class Retriever(Protocol):
-    async def retrieve(self, query: Query, ctx: RetrievalContext) -> list[ScoredChunk]: ...
-
-class Reranker(Protocol):
-    async def rerank(self, query: Query, chunks: list[ScoredChunk], ctx: RerankContext) -> list[ScoredChunk]: ...
-
-class Embedder(Protocol):
-    def encode(self, items: list[Embeddable]) -> EmbeddingResult: ...   # Embeddable = str | Image | Audio | ...
-
-class Generator(Protocol):
-    async def generate(self, system: str, history: list[Msg], ctx: GenContext) -> GenResult: ...
-```
-
-> **原则**：本文档每条扩展方向都以"新增/扩展某 Protocol 实现 + 注册到工厂"为接入方式，**不**改动调用方代码。这样可以保持 N 个扩展方向 **并行落地** 而不互相阻塞。
-
----
-
-## 1. 重点扩展方向
-
-> 共 6 个方向。第 5、6 个为前述 5 个外的延伸（自适应路由），但和"评估闭环 / 混合搜索 / 对话记忆"高度互补，建议合并审阅。
-
-### D1. 多模态检索（原生跨模态向量空间）
-
-#### 1.1 触发场景
-- 客户问："去年那张含 'Q3 GMV' 的 PPT 切片在哪？" — 当前只能命中 OCR 抽出的文字，**布局/图表整体语义** 丢失。
-- 视频会议纪要库：用户描述"那段讲到老王说'下季度先稳住毛利'的会议"，纯 ASR 文本无法绑定 **说话人 + 时间 + 屏幕共享上下文**。
-- 设备图谱：硬件型号识图（"这块板子是哪一版"），目前只能让 VLM 描述后再走文本检索，VLM 描述不稳定。
-
-#### 1.2 技术方案
-分三层逐步推进：
-
-| 层级 | 方案 | 依赖组件 |
-|------|------|---------|
-| L1（基线增强） | **关键帧抽样 + VLM 多次 describe**：视频每 N 秒抽帧，每帧 VLM 描述独立 chunk，附 `frame_ts` 元数据；图片在 OCR + describe 之外再加 **结构化 VQA**（"图中有什么图表/品牌/人脸？"） | 现有 `cv_model.py`、`sequence2txt_model.py` 即可；新增 `rag/app/video.py` |
-| L2（跨模态检索） | 引入 **CLIP / BGE-VL / Jina-Clip-v2** 作为 `MultimodalEmbedder` Protocol 实现：图片直接编码为向量，文本 query 编码到 **同一向量空间**；ES 索引增加 `vec_image_q_<dim>_vec` 列 | 新依赖 `transformers` / `sentence-transformers` 或托管 API；GPU 资源 |
-| L3（视听统一） | **Whisper + speaker diarization**（pyannote）替换当前一段式 ASR；视频 chunk 同时持有 `text_vec`（ASR 文本）+ `image_vec`（关键帧） + `audio_vec`（可选，用 CLAP） | `pyannote.audio`、`open_clip`；额外存储约 +30% |
-
-#### 1.3 接口改造点（基于 S3-T1）
-- 扩展 `Embedder.encode(items: list[Embeddable])`：`Embeddable = str | PILImage | AudioBytes | VideoFrame`，返回 `EmbeddingResult(vector, modality, dim)`。
-- 新增 `MultimodalRetriever(Retriever)` 实现：内部根据 query 的 `modality_hint`（文本默认）选择走 `text_vec` 还是 `image_vec` 列。
-- VDB 层 schema 演进（`rag/vdb/elasticsearch/elasticsearch_vector.py:653+` 的 mapping 创建）：把"硬编码单 vector 列"改造为"按 modality 多列动态注册"；落地依赖 [S3-T1] 提到的 mapping 模板化改造。
-- `app/picture.py` / `app/audio.py` 的 `chunk()` 函数输出 dict 中新增 `image_b64` / `audio_b64` 字段，供 Embedder 后续无损取用（避免 PIL 对象在 Celery pickle 边界丢失）。
-
-#### 1.4 工作量估计
-- L1 基线：**1.5 人周**（2 个 PR：视频抽帧；结构化 VQA prompt）
-- L2 跨模态：**3 人周**（含 Embedder 抽象、ES schema 迁移、回归测试）
-- L3 视听统一：**4 人周**（含 GPU 容器、speaker diarization 集成）
-- 合计：**~1.5 + 3 + 4 ≈ 8.5 人周**（可分阶段产出）
-
-#### 1.5 风险与依赖
-- ⚠️ **存储膨胀**：image_vec（768d float32）单图 3KB，1M 图 ≈ 3GB；ES dense_vector 启用 `int8_hnsw` 量化可减 75%。
-- ⚠️ **VLM 描述漂移**：同一图不同时间不同模型版本，描述差异大；需要 caption 缓存（key = `sha256(image)+model_version`）。
-- ⛓️ **强依赖**：[S3-T1] mapping 模板化改造完成后再做 L2，否则 schema 演进会成阻塞点。
-- ⛓️ **GPU 依赖**：L2/L3 在自建 GPU 节点或托管 API 二选一；建议先走托管（Jina-Clip API）跑通端到端，再评估自托管。
-
----
-
-### D2. 混合搜索增强（Sparse + Dense + Late-Interaction + 自适应路由）
-
-#### 2.1 触发场景
-- "工号 E12345 的 OKR" — 长尾标识符，BM25 强、稠密向量弱，**当前 0.05/0.95 权重几乎让 BM25 失语**。
-- "怎么做用户分层运营？" — 概念性问题，dense 强、BM25 弱。
-- "GraphRAG 和 LightRAG 的区别" — 需要 ColBERT 这类 token 级精排，单向量混淆术语。
-
-#### 2.2 技术方案
-
-| 子方向 | 方案 | 价值 |
-|-------|------|------|
-| **SPLADE 学习稀疏** | 用 `naver/splade-cocondenser-ensembledistil` 或国产 BGE-M3 sparse 输出，每个文档生成稀疏向量（含 token expansion）；接入 `MatchSparseExpr`（**已存在但未启用**） | 把 BM25 的"词形匹配"升级为"学习权重 + 自动同义扩展" |
-| **ColBERT 后期交互** | 文档级向量改为 token 级（一篇文档 N 个 token vector，N≈chunk_token_num/3）；retrieval 时用 MaxSim；可仅在 reranker 阶段使用 | 在精确匹配上比 cross-encoder 快 5–10×，质量接近 |
-| **语义路由 / 自适应权重** | 先用一个轻 LLM（或 query classifier）判定 query 类型（lookup / concept / list / multi-hop / temporal），路由到 `{BM25权重, vector权重, 是否使用 Graph, 是否使用 Rerank}` | 替代当前写死的 `0.05/0.95`；可灰度（query 哈希 % 100 < 5 上新策略） |
-| **多向量召回融合** | 同 chunk 同时索引 BM25、dense、sparse 三类，retrieval 后用 RRF (Reciprocal Rank Fusion) 融合 | 工程上 RRF 不需训练，落地最快 |
-
-#### 2.3 接口改造点
-- 新增 `SparseEmbedder(Embedder)` 实现：返回 `SparseVector(indices, values)`；ES mapping 增加 `q_sparse_<vocab>_vec` 字段，使用 `rank_features`/`sparse_vector` 类型（ES ≥ 8.11）。
-- 在 `rag/nlp/search.py:Dealer.search()`（第 387 行起）把 `FusionExpr` 的硬编码权重改为 `ctx.fusion_weights`，由 `Retriever` 实现的 `ctx` 参数注入。
-- 新增 `RouterRetriever(Retriever)`：组合多个底层 retriever（DenseRetriever / SparseRetriever / GraphRetriever），按 router 决策选择 / 融合。
-- ColBERT 仅在 Reranker 层接入：新增 `ColBERTReranker(Reranker)` 实现；接 `Reranker` 协议，**完全不影响**调用方。
-
-#### 2.4 工作量估计
-- RRF 多路融合（**Quick PoC，见 §2**）：**0.5 人周**
-- SPLADE 接入：**2 人周**（含 ES mapping、批量重建索引）
-- 语义路由：**2.5 人周**（含 router 训练数据采集、灰度框架）
-- ColBERT Reranker：**3 人周**（GPU 部署 + 蒸馏小型化）
-- 合计：**~8 人周**
-
-#### 2.5 风险与依赖
-- ⚠️ **重建索引成本**：现网 KB 数量 × chunk 数 × 维度，估算总耗时；需要提供"灰度索引切换"工具（详见 §6 路线图 P0）。
-- ⚠️ **路由器误判**：错路由比无路由更糟；必须配 fallback（路由失败回退到当前默认 0.05/0.95）。
-- ⛓️ **依赖 [S3-T1]** 的 `Retriever` Protocol 落地后才能优雅接入路由器；否则会污染 `Dealer` 类。
-
----
-
-### D3. 知识图谱增强（基于 [S2-T4] GraphRAG 的延伸）
-
-#### 3.1 触发场景
-- 法务/合规库每月新增 200+ 条法规：当前必须 **重建整个图**，CI 跑 1 小时；用户要求"增量入库 + 增量图更新"。
-- 报错排查："TS_001 错误码可能由哪些组件触发？" — 需要从 **错误码** 节点 N-hop 走到 **组件** 节点；当前 KGSearch 走的是文本相似度匹配实体，**不是路径推理**。
-- 团队要求"为什么是这个答案" — 需要把推理路径（A→关系1→B→关系2→C）作为 citation 一同返回，提供 **可解释性**。
-
-#### 3.2 技术方案
-
-| 子方向 | 方案 | 现状 → 目标 |
-|-------|------|------------|
-| **增量图演化** | 在 `tasks.py:build_graphrag_for_document` 链上插入 `GraphMerge` 阶段：新文档抽出的子图与全图做 **节点对齐 + 关系合并 + 冲突标记**；保留 `version_int` 字段记录每条边的"加入/失效"版本号 | 一次构建 → 增量更新 + 时间溯源 |
-| **路径解释性** | KGSearch.retrieval() 输出新增 `evidence_path: list[Edge]`；在 prompt 组装时把路径作为引用源；前端渲染"由 X→Y→Z 推断" | 黑盒答案 → 带溯源链路 |
-| **Neo4j 双引擎** | 当前图存在 ES 的 chunk 表里（`knowledge_graph_kwd` 字段），不能利用图算法；引入 Neo4j 作为 **算法引擎**（PageRank 已在 ES 里跑过，但 Cypher 跑社区检测、最短路径远更便利）；ES 仍负责文本召回，Neo4j 负责图算法。README 已声明 Neo4j 是组件，**只是 RAG 层没用** | 单引擎 → 检索 ES + 图算法 Neo4j 混合 |
-| **温度敏感的图衰减** | 复用 `core/memory/forgetting_engine` 的 Ebbinghaus 实现到图边权重：长期未被命中的实体/关系权重衰减；与 D4 共享一套衰减逻辑 | 静态图 → 动态、有"记忆"的图 |
-| **自动本体演化** | 借鉴 `core/memory/ontology_services/General_purpose_entity.ttl`，定期用 LLM 检查"这批新加的实体类型是否应该归并到已有类型？" | 类型膨胀 → 受控演化 |
-
-#### 3.3 接口改造点
-- 新增 `GraphRetriever(Retriever)` 实现，包装现有 `KGSearch`；输出 `ScoredChunk.metadata` 增加 `evidence_path`（`list[(from_entity, relation, to_entity, confidence)]`）。
-- 新增 `GraphStore` 抽象层：`add_subgraph / merge / query_path / pagerank / community_detect`；实现两个：`ESGraphStore`（保留现状）、`Neo4jGraphStore`（新增）。`graphrag/general/index.py` 现在直接操作 `nx.Graph`，全部替换为 `GraphStore` 调用。
-- 在 `tasks.py` 的 Celery 链增加 `graph_merge_task`：依赖 `build_graphrag_for_document`，处理增量合并；需要分布式锁（已有 `redis_lock.py` 可用）。
-- Prompt 层（`prompts/generator.py`）新增 `evidence_aware_citation_prompt`：把 `evidence_path` 作为额外上下文注入。
-
-#### 3.4 工作量估计
-- 增量图演化（最小可用）：**3 人周**（最复杂的是合并冲突的实体消歧）
-- 路径解释性：**2 人周**
-- Neo4j 双引擎：**3 人周**（含 Cypher 工具集、Neo4j 数据迁移脚本）
-- 图衰减 + 本体演化：**2 人周**（与 D4 共享代码）
-- 合计：**~10 人周**
-
-#### 3.5 风险与依赖
-- ⚠️ **实体消歧难度**：跨文档同名异义（"苹果"=公司 / 水果）；建议用现有 `entity_resolution.py` 改造，但需要补全单元测试。
-- ⚠️ **Neo4j 运维成本**：用户已在 README 声明依赖 Neo4j，但当前 RAG 层零调用；引入意味着同时管理两个图的一致性。建议把 Neo4j 定位为"算法只读 / 异步同步"，避免双写一致性。
-- ⛓️ **依赖 [S3-T1]** 把 `GraphStore` 与 `Retriever` 协议落实，否则会跨层塌方。
-
----
-
-### D4. 对话记忆 ↔ RAG 协同（短期 / 长期 / 检索召回三段桥接）
-
-> **MemoryBear 的核心特色**。当前最大产品差异化机会就在这里——`core/memory/` 与 `core/rag/` 是 **两条独立链路**，没有联动。
-
-#### 4.1 触发场景
-- 用户在第 3 轮说"我对海鲜过敏"，第 7 轮问"今晚吃什么？" — 当前 RAG 层无任何记忆能力，每次只看当轮 query。
-- 多 Agent 协作：售前 Agent 收集到客户预算，售后 Agent 重新询问 — 跨 Agent 记忆需要从 `core/memory` 读出 + 注入 RAG 检索 query 重写。
-- 长对话上下文压缩：第 50 轮时，前 40 轮对话需要 **被遗忘但保留要点**，要点变成"用户档案 chunk"加入 KB。
-
-#### 4.2 短期 / 长期 / 检索召回的边界（产品决策）
-
-| 维度 | 短期记忆（Working Memory） | 长期记忆（Episodic / Semantic） | 检索召回（KB） |
-|------|---------------------------|--------------------------------|---------------|
-| 存储位置 | Redis，单 session 8KB cap | Neo4j + ES（`core/memory`） | ES（`core/rag`） |
-| 生命周期 | session（< 24h） | 永久（按 forgetting curve 衰减） | 永久（人工治理） |
-| 写入触发 | 每轮 user/assistant message | reflection_engine 周期性提炼 | 文档入库流水线 |
-| 召回时机 | 始终注入 prompt | LLM 重写 query 时 + 主动检索 | RetrievalNode 命中 |
-| 数据契约 | `list[Msg]` | `MemoryItem(content, strength, type, ts)` | `DocumentChunk` |
-| 可信度 | 高（用户原话） | 中（LLM 提炼） | 高（人工审核） |
-
-> **决策原则**："用户原话进短期，提炼事实进长期，世界知识进 KB。" 三者不能互相替代。
-
-#### 4.3 技术方案
-- **MemoryAugmentedRetriever**：在 `RouterRetriever` 之外再包一层，retrieve 前用 `core/memory.read_services` 拿到当前 user 的 top-K 长期记忆条目，**改写 query**（"今晚吃什么？" + 长期记忆"对海鲜过敏" → "今晚吃什么？避免海鲜"）。
-- **Memory Citation**：检索结果与长期记忆条目并入同一 `chunks` 列表，prompt 模板区分两者来源（"用户提及" vs "知识库")，避免幻觉混淆。
-- **反向写入**：每轮对话产出后，让 `core/memory.write_router` 决定 是否需要把"新事实"写入长期记忆；这一步 **复用** `core/memory.agent.langgraph_graph.write_graph`（已存在）。
-- **遗忘对齐**：把 `core/memory/forgetting_engine` 的 ACT-R 计算复用到 KB chunk 上（D3 已提）；让"很少被命中的过期 KB chunk"自动沉睡，反向触发治理团队复审。
-
-#### 4.4 接口改造点
-- 在 `workflow/nodes/knowledge/node.py` 的 `KnowledgeRetrievalNode.execute()` 中注入 `MemoryService`：当节点配置里 `enable_memory=true` 时，先调 `memory_service.recall(user_id, query)` 拿记忆，再传给 `Retriever.retrieve(query, ctx={memory: ...})`。
-- 新增 `MemoryAwareRetriever(Retriever)` 实现，包装任一底层 Retriever。
-- Workflow Node 配置 `KnowledgeRetrievalNodeConfig` 增加 `memory_strategy: Literal["off", "context_only", "rewrite_query", "merge_chunks"]`。
-- Prompt 模板新增 `<MEMORY>` 段落。
-
-#### 4.5 工作量估计
-- 单向（memory → retrieval）：**3 人周**
-- 双向（retrieval 结果反写 memory）：**2 人周**（大部分代码已在 `core/memory` 存在）
-- 遗忘对齐 + 治理触发：**2 人周**（与 D3 共享）
-- 合计：**~7 人周**
-
-#### 4.6 风险与依赖
-- ⚠️ **隐私边界**：长期记忆是 **per-user**，KB 是 **per-tenant**；混淆会导致跨用户泄露。设计时必须 user_id 级强隔离，code review 重点。
-- ⚠️ **Prompt 长度膨胀**：记忆 + KB 双源；如果未做摘要，长对话场景 token 成本翻倍；必须配合记忆摘要（已有 `summary4memory.md`）。
-- ⛓️ **依赖 [S3-T1]** 的 `Retriever / Reranker` 协议；强依赖 [S2-T6] 的 E2E 时序图明确两条链路的衔接点。
-
----
-
-### D5. 评估与反馈闭环（用户反馈 → Reranker 微调）
-
-#### 5.1 触发场景
-- 答案错了 / 引用不对，用户点👎 — 当前数据 **进了日志，没人消费**。
-- 同一 query 在不同时段表现波动 → 需要离线 A/B 评估。
-- 业务方问"再加一个 KB 之后效果到底变好还是变差？" — 没有可量化的回归指标。
-- README 给的 F1/BLEU/J 在论文中实现过，**但仓内没有这套代码**，每次评估靠手工。
-
-#### 5.2 技术方案（双轨：评估在线化 + 反馈学习）
-
-##### 5.2.1 评估轨：离线 / 在线 / CI 三层
-
-| 层级 | 内容 | 工具 |
-|------|------|------|
-| **离线评估集** | 每 KB 维护一个 `eval_cases.jsonl`：`{query, ideal_chunks, ideal_answer, hard_negatives}`；增量构建（每周从用户问句 + 答疑团队补充） | DSL + Excel 导入工具 |
-| **在线指标** | `Hit@K / MRR / nDCG / Citation Coverage / Hallucination Rate / Latency P50/P95`；通过 OpenTelemetry 埋点写入 Prometheus | OTel + Prometheus + Grafana |
-| **CI 评估** | 每个 PR 跑核心 KB 的回归集；指标低于 baseline n% 时阻塞合并 | RAGAS（开源）+ 自研判分 prompt |
-
-##### 5.2.2 反馈学习轨：从👍/👎到 Reranker 微调
-
-```
-用户反馈（👍/👎/edit）
-   ↓ event log
-事件清洗（同一 query 多个 chunk 评分）
-   ↓
-形成 (query, positive_chunk, negative_chunk) 三元组
-   ↓
-  ├─ 短链：在线 PairWise 调整 BM25/dense 权重（D2 路由器配置）
-  └─ 长链：周/月一次离线训练 Cross-Encoder reranker（基础模型用 bge-reranker-base 蒸馏）
-       ↓
-   新 reranker 走 D6 灰度框架上线
-       ↓
-   评估轨自动验证收益
-```
-
-#### 5.3 接口改造点
-- 新增 `EvaluationProtocol`：`{evaluate(query, retrieved, generated, ground_truth) -> Metrics}`；在 OpenTelemetry trace 末尾自动落 Prometheus。
-- `RedBearRerank` 改造：接入 `LocalCrossEncoderRerank(Reranker)` 子类，加载本地 ONNX/TorchScript 模型；可与 Jina/DashScope 并存于工厂。
-- 反馈采集：复用 `core/memory` 的事件总线（如有）或新建 `feedback_event` 表；前端组件加 thumbs；citation 点击行为也作为隐式反馈。
-- 训练 pipeline 独立仓 / 独立服务；产物（ONNX）通过模型注册表（用现有 `ModelConfig` 表扩展即可）滚动上线。
-
-#### 5.4 工作量估计
-- 评估指标埋点 + Grafana 看板：**1.5 人周**
-- 离线评估集 + RAGAS CI 集成：**2 人周**
-- 反馈采集 + 三元组清洗：**1 人周**
-- Cross-Encoder 蒸馏训练 pipeline：**3 人周**（含数据扩充、训练脚本、产出 ONNX）
-- 合计：**~7.5 人周**
-
-#### 5.5 风险与依赖
-- ⚠️ **冷启动**：刚上线时反馈数据 < 1k 不足以训练；必须先用大模型 LLM-as-Judge 合成训练数据（现成 prompt 在 `prompts/generator.py` 可借鉴）。
-- ⚠️ **反馈污染**：恶意 / 误点；需要置信度过滤（同一 user 短时多次相反反馈丢弃）。
-- ⛓️ **依赖 [S3-T1]** 的可观测性方案，否则数据采不到。
-- ⛓️ **依赖 D2 的语义路由**，否则没有"权重可调"的注入点。
-
----
-
-### D6. 自适应检索路由（Adaptive Retrieval Routing）
-
-> 这是 D2 中"语义路由"的工程化升级版，独立列出是因为它会**统一**所有检索能力（dense / sparse / graph / memory / web），是 RAG 系统的中央调度器。
-
-#### 6.1 触发场景
-- 同一用户在同一 session 内：第 1 个问题需要走 KB，第 2 个问题需要走 Web 搜索（"今天的新闻"），第 3 个问题需要 Graph 推理 — 当前必须用户手动切模式。
-- "你刚才推荐的方案做不了"（指代消解）→ 需要先走对话记忆，再决定是否检索；当前都是无脑全检索。
-
-#### 6.2 技术方案
-
-| 决策类型 | 输入 | 输出 |
-|---------|------|------|
-| 是否需要检索 | query + 短期记忆 | `bool need_retrieval` |
-| 检索来源 | query 类型 | `[KB_id, Graph_flag, Web_flag, Memory_flag]` |
-| 检索策略 | query 类型 + 用户场景 | `(retriever_name, top_k, fusion_weights, rerank_id)` |
-| 兜底 | 第一次检索结果差 | 触发 query rewriting + 二次检索 |
-
-实现：
-- 路由器 = 小型 LLM（如 1.5B–3B）+ rule-based fallback；输出结构化 JSON。
-- 训练数据来源：D5 的反馈数据 + 标注团队人工标 1k 条。
-- 推理用 vllm 或 SGLang 自托管，P95 延迟控制在 50ms。
-
-#### 6.3 接口改造点
-- 把 `RetrieveType` enum 改造成 strategy（与 D2 共享的 `RouterRetriever`）；workflow 层调用方不再选模式，而是传入 query。
-- 新增 `RoutingPolicy` 配置实体：可被工作空间管理员通过 UI 编辑（默认策略 + 灰度策略）。
-- 与 D5 形成闭环：评估指标决定路由器升级时机。
-
-#### 6.4 工作量估计
-- 规则+LLM 路由器最小可用：**2 人周**
-- 完整训练 / 灰度 / 配置 UI：**5 人周**
-- 合计：**~7 人周**
-
-#### 6.5 风险与依赖
-- ⚠️ **路由器变成单点**：必须有 fallback 到当前默认策略。
-- ⛓️ **强依赖 D2 + D5**；不建议独立做。
-
----
-
-## 2. Quick PoC 路径（≤ 1 周可见效果）
-
-### PoC-A：RRF 多路融合检索（属 D2）
-
-**目标**：现网 KB 在不重建索引、不改 schema 的前提下，加入 BM25 + dense 各自独立 top-50 → RRF 融合 → 同一接口返回。1 周内拿到 A/B 数据。
-
-**改动范围**（最小集）：
-- `rag/nlp/search.py:Dealer.search()` 拆为两步：先单独跑 BM25（`emb_mdl=None`），再单独跑 dense（无 BM25），合并时用 RRF。
-- 增加 feature flag `RETRIEVAL_FUSION_MODE = {"weighted", "rrf"}`，默认 weighted（不影响现网）。
-
-**预期收益**：在长尾 lookup query 上 Hit@10 +5–10pp（参考社区数据）。无负向风险，因为 weighted 路径保留。
-
-**PoC 代码草案**（伪代码，约 30 行；正式实现需走完整 PR + 评估）：
-
-```python
-# rag/retrieval/rrf.py（新增）
-def rrf_merge(rankings: list[list[ScoredChunk]], k: int = 60, top_k: int = 20) -> list[ScoredChunk]:
-    """Reciprocal Rank Fusion: score = Σ 1/(k + rank_i)。
-    rankings: 多个独立排序结果，每个内部按相关度降序。
-    """
-    score_map: dict[str, float] = {}
-    chunk_map: dict[str, ScoredChunk] = {}
-    for ranking in rankings:
-        for rank, chunk in enumerate(ranking, start=1):
-            cid = chunk.metadata["doc_id"]
-            score_map[cid] = score_map.get(cid, 0.0) + 1.0 / (k + rank)
-            chunk_map[cid] = chunk  # 保留首次见到的对象
-    merged = sorted(chunk_map.values(),
-                    key=lambda c: score_map[c.metadata["doc_id"]],
-                    reverse=True)
-    for c in merged:
-        c.metadata["score_rrf"] = score_map[c.metadata["doc_id"]]
-    return merged[:top_k]
-
-
-# 调用侧（rag/nlp/search.py:Dealer.search 增量改造）
-if os.getenv("RETRIEVAL_FUSION_MODE", "weighted") == "rrf":
-    bm25_hits = self._search_bm25_only(req, ...)
-    dense_hits = self._search_dense_only(req, ...)
-    return rrf_merge([bm25_hits, dense_hits], k=60, top_k=req.get("topk", 20))
-# else: 走现有 weighted 路径
-```
-
-### PoC-B：Memory-Augmented Query Rewrite（属 D4）
-
-**目标**：把 `core/memory.read_services` 已有的"长期记忆召回"接到 `KnowledgeRetrievalNode` 之前，做 query 改写。1 周内对 1 个内部 demo 应用上线。
-
-**改动范围**：
-- `KnowledgeRetrievalNode.execute()` 第一行加 5 行：拿 user_id（已有 `user_ids`），调 `memory_service.get_user_summary(user_id)`，把 summary 拼到 query 前。
-- 新增 feature flag `MEMORY_AUGMENT_RETRIEVAL = false`（默认关闭）。
-- 不改 prompt，不改 schema，不改 ES。
-
-**预期收益**：在多轮对话场景下，第 N 轮 query 的指代消解正确率提升；无回归风险（flag 默认关）。
-
-```python
-# workflow/nodes/knowledge/node.py:KnowledgeRetrievalNode.execute() 头部增量
-if os.getenv("MEMORY_AUGMENT_RETRIEVAL") == "true" and user_ids:
-    from app.services.user_memory_service import get_user_summary
-    summary = get_user_summary(user_ids[0], ttl_sec=3600)  # 已存在 / 类似函数
-    if summary:
-        query = f"[用户背景: {summary}]\n{query}"
-```
-
-> **注意**：上述两段代码均为 PoC 草案，真实落地需要：1）完整单测；2）评估对比；3）feature flag 走配置中心；4）权限审查（D4 涉及隐私）。
-
----
-
-## 3. 优先级矩阵（用户价值 × 实现成本 × 风险）
-
-> 评分 1–5（5 最高 / 5 最低）。建议落地顺序按"用户价值高 + 成本低 + 风险低"加权。
-
-| 方向 | 用户价值 | 实现成本 (越低越好) | 风险 (越低越好) | 综合分（V × 1/√(C×R)） | 建议落地阶段 |
-|------|---------|--------------------|----------------|----------------------|------------|
-| **D2-PoC RRF 融合** | 4 | 5 (0.5 人周) | 5 (无回归) | 8.0 | 立即（Sprint-3 内） |
-| **D4-PoC Memory Rewrite** | 4 | 5 (0.5 人周) | 4 (隐私) | 7.2 | 立即（Sprint-3 内） |
-| **D5 评估埋点 + Grafana** | 5 | 4 (1.5 人周) | 5 | 5.6 | 短期（1 月） |
-| **D5 RAGAS CI** | 4 | 4 | 5 | 4.5 | 短期（1 月） |
-| **D2 SPLADE 接入** | 4 | 3 (2 人周) | 4 (索引重建) | 3.7 | 短期（1 月） |
-| **D4 完整双向集成** | 5 | 3 (5 人周) | 3 (隐私 / token) | 3.5 | 中期（2 月） |
-| **D5 Reranker 微调** | 4 | 3 (3 人周) | 3 (冷启动) | 2.7 | 中期（2 月） |
-| **D6 自适应路由** | 4 | 2 (5 人周) | 3 | 2.3 | 中期（3 月） |
-| **D1 多模态 L1（基线）** | 3 | 4 (1.5 人周) | 4 | 3.0 | 短期（1 月） |
-| **D1 多模态 L2 跨模态** | 5 | 2 (3 人周) | 3 (GPU) | 2.5 | 中期（3 月） |
-| **D3 增量图演化** | 4 | 2 (3 人周) | 2 (实体消歧) | 2.0 | 中长期（3–4 月） |
-| **D3 Neo4j 双引擎** | 3 | 2 (3 人周) | 2 (运维) | 1.5 | 长期（4–6 月） |
-| **D1 多模态 L3 视听统一** | 3 | 1 (4 人周) | 2 (GPU + diarization) | 1.1 | 长期（6 月+） |
-| **D3 自动本体演化** | 2 | 2 | 2 | 1.0 | 长期 (按需) |
-
-> **维度说明**
-> - 用户价值：高优先级业务场景（toB 客户）调研访谈得分。
-> - 实现成本：人周折算（1 人周=1 分；6 人周=2 分；10 人周=1 分）。
-> - 风险：含技术风险 + 数据迁移 + 上线回滚 + 安全 / 隐私。
-> - 综合分用 `V / sqrt(C×R)` 倒数化，**仅作排序参考**，不取代产品/架构会判断。
-
----
-
-## 4. 落地路线图（Roadmap）
-
-```mermaid
-gantt
-    title MemoryBear RAG 后续迭代 路线图
-    dateFormat  YYYY-MM-DD
-    axisFormat  %m/%d
-    section Sprint-3 (现 Sprint)
-    PoC-A RRF 融合 (D2)            :a1, 2026-06-02, 5d
-    PoC-B Memory Rewrite (D4)      :a2, 2026-06-02, 5d
-    section 短期 (1 个月)
-    评估埋点 + Grafana (D5)         :s1, 2026-06-09, 7d
-    RAGAS CI (D5)                  :s2, after s1, 7d
-    SPLADE 接入 (D2)                :s3, after s1, 10d
-    多模态 L1 基线 (D1)            :s4, 2026-06-09, 7d
-    section 中期 (2-3 个月)
-    Memory ↔ RAG 双向集成 (D4)     :m1, after s2, 25d
-    Reranker 微调 pipeline (D5)    :m2, after s3, 15d
-    自适应路由 (D6)                 :m3, after m1, 25d
-    多模态 L2 跨模态 (D1)          :m4, after s4, 15d
-    section 长期 (3-6 个月)
-    增量图演化 (D3)                 :l1, after m1, 20d
-    Neo4j 双引擎 (D3)              :l2, after l1, 15d
-    多模态 L3 视听统一 (D1)        :l3, after m4, 20d
-    本体演化 (D3)                   :l4, after l2, 10d
-```
-
-> 所有阶段分别绑定一组 OKR + 评估指标（D5 提供数据），未达指标停止下阶段。
-
----
-
-## 5. 风险与依赖总表
-
-| 类型 | 风险 | 缓解策略 |
-|------|------|---------|
-| 架构 | [S3-T1] 接口抽象未落地，本路线图全部方向受阻 | Sprint-3 内先把 `Retriever / Reranker / Embedder / Generator` 4 个 Protocol 落地（[S3-T1] 必交付项） |
-| 数据 | 索引重建（D1/D2/D3）导致服务不可用 | 灰度索引切换工具：双写期 + 流量按租户灰度 + 一键回滚 |
-| 隐私 | D4 跨用户记忆泄露 | user_id 级强隔离 + 单元测试覆盖 + 上线前安全 review |
-| 资源 | D1/D6 引入 GPU 依赖 | 优先走托管 API 跑通 PoC；自托管列入 long-term，需要预算评审 |
-| 治理 | D5 评估集质量低 → CI 阻塞误判 | 评估集双人复核 + 周复盘 + 例外白名单 |
-| 运维 | D3 Neo4j 双引擎一致性 | 定位 Neo4j 为算法只读，从 ES 异步同步；不双写 |
-| 业务 | 路线图与产品 PRD 脱节 | 与 [@产品需求分析师] 在 Sprint-3 启动前对齐 1 次 |
-
----
-
-## 6. 与 [S3-T1] / [S3-T3] 的对齐清单
-
-- ✅ 每个方向都标注了"接口改造点"，所有改造均落到 [S3-T1] 提议的 `Retriever / Reranker / Embedder / Generator / GraphStore / Loader` Protocol；不新增其它接口。
-- ✅ 所有方向有"工作量、风险、依赖"三件套，可被 [S3-T3] 终审按统一模板核对。
-- ✅ Quick PoC 已覆盖 D2 与 D4 各 1 条（≥ 2 条要求达成）。
-- ✅ 优先级建议已按"用户价值 × 实现成本 × 风险"三维评分给出，并配有路线图甘特图。
-- ✅ 多模态、混合搜索、KG 增强、对话记忆、评估闭环均覆盖（5/5）；额外补充自适应路由作为联动方向。
-
-— END —

docs/rag/graphrag/README.md

@@ -1,200 +0,0 @@
----
-title: "[S2-T4] GraphRAG（light + general）实现详解 — 正式版"
-author: Python 开发工程师
-reviewer: 知识运营与治理专家
-source-commit: feae2f2e (MemoryBear)
-last-reviewed-at: 2026-05-08
-scope: api/app/core/rag/graphrag/（含 light/ 与 general/ 子目录）
-version: v1.0
-status: 正式版（已解除占位）
----
-
-# [S2-T4] GraphRAG（light + general）实现详解 — 正式版
-
-> 本文档为 [WS-24](mention://issue/a07f108d-06ee-41b8-8b57-22455f60ddeb) v1.0 文档全集的正式组成文件，替换 v1.0-RC1 中的占位版本。
-> 原始完整文档与逐节详评见 [WS-18](mention://issue/16bdb196-e10e-489b-b01c-9067b1f1bb23) 与 [WS-21](mention://issue/41f2482b-6f3e-4253-95f7-3e22e790f31c) §S2-T4 评审报告。
-
----
-
-## 1. 一句话定位
-
-GraphRAG 是 MemoryBear 知识库系统的**知识图谱增强检索模块**，通过 LLM 从文档中抽取实体-关系三元组构建知识图谱，在检索阶段利用图谱结构（实体关联、社区报告、多跳路径）补充传统向量检索的语义盲区，实现"结构化知识 + 语义向量"的混合召回。
-
----
-
-## 2. 评审结果
-
-| 维度 | 满分 | 得分 | 关键说明 |
-|---|---:|---:|---|
-| 准确性 | 25 | 24 | 抽检 5/5 命中：`run_graphrag` / extractor 三元选择 / `is_similarity` / `KGSearch.retrieval` / Leiden `run()` |
-| 完整性 | 25 | 24 | 12 章节 + 附录索引：术语表 11 条、Light/General 双时序图、5 套源码详解、4 个核心 Prompt 逐段解读 |
-| 时效性 | 15 | 13 | 元数据表完整，缺 YAML frontmatter（Sprint-2 已知遗留） |
-| 可读性 | 15 | 14 | Mermaid 时序图规范、Light/General 三张对照表一目了然、Prompt 逐行设计意图写法出色 |
-| 可执行性 | 20 | 18 | parser_config 配置入口明确、三组参数表完整、资源消耗估算（Light 5-15min / General 30-60min）可验证 |
-| **合计** | **100** | **93** | **PASS（标杆）** |
-
-**裁定:** 与 [S2-T3] 并列 Sprint-2 **双标杆**。Must-Fix 无；Nice-to-Have 7 条留给 [S3-T3] 整合时统一处理。
-
----
-
-## 3. 模块结构
-
-```
-api/app/core/rag/graphrag/
-├── search.py                          # KGSearch：图谱检索入口
-├── entity_resolution.py               # 实体消歧（LLM + 编辑距离）
-├── entity_resolution_prompt.py        # 实体消歧 Prompt
-├── query_analyze_prompt.py            # 查询分析 Prompt（MiniRAG 风格）
-├── utils.py                           # 图操作工具集（merge、cache、ES 读写）
-├── __init__.py
-├── light/
-│   ├── graph_extractor.py             # Light 版实体/关系抽取器
-│   └── graph_prompt.py                # Light 版抽取 Prompt + RAG 回答 Prompt
-└── general/
-    ├── extractor.py                   # 通用抽取基类
-    ├── graph_extractor.py             # General 版实体/关系抽取器
-    ├── graph_prompt.py                # General 版抽取 Prompt
-    ├── index.py                       # 建图总控（子图生成→合并→消歧→社区报告）
-    ├── entity_embedding.py            # Node2Vec 实体嵌入（备用）
-    ├── leiden.py                      # Leiden 社区发现算法封装
-    ├── community_reports_extractor.py # 社区报告抽取器
-    ├── community_report_prompt.py     # 社区报告生成 Prompt
-    ├── mind_map_extractor.py          # 思维导图抽取器
-    └── mind_map_prompt.py             # 思维导图 Prompt
-```
-
----
-
-## 4. 核心时序图
-
-### 4.1 建图时序图
-
-```mermaid
-sequenceDiagram
-    participant U as 用户/任务
-    participant T as tasks.py (Celery Task)
-    participant I as general/index.py run_graphrag
-    participant E as light/general GraphExtractor
-    participant ES as Elasticsearch
-    participant ER as entity_resolution.py
-    participant CR as community_reports_extractor.py
-
-    U->>T: 上传文档 / 触发建图
-    T->>I: run_graphrag_for_kb(document_ids, parser_config)
-    I->>I: load_doc_chunks() 按 1024 token 合并 chunk
-    loop 每个文档并行（max 4）
-        I->>E: generate_subgraph(extractor, chunks)
-        E->>E: LLM 抽取 entities + relations (多轮 gleaning)
-        E->>E: 解析输出 → nx.Graph
-        E->>ES: 写入 subgraph (knowledge_graph_kwd="subgraph")
-    end
-    I->>I: merge_subgraph() 逐个文档合并子图到全局图
-    I->>ES: 写入全局 graph (knowledge_graph_kwd="graph")
-    I->>ES: 写入 entity/relation chunks (带向量嵌入)
-
-    alt with_resolution=true (General 可选)
-        I->>ER: resolve_entities(graph, subgraph_nodes)
-        ER->>ER: 编辑距离预筛选候选对
-        ER->>ER: LLM 批量判断"是否同一实体"
-        ER->>ER: 合并连通分量中的节点
-        ER->>ER: 重新计算 PageRank
-        ER->>ES: 更新 graph/entity/relation
-    end
-
-    alt with_community=true (General 可选)
-        I->>CR: extract_community(graph)
-        CR->>CR: Leiden 社区发现
-        CR->>CR: LLM 生成每个社区的报告
-        CR->>ES: 写入 community_report chunks
-    end
-    I-->>T: 返回 {ok_documents, failed_documents, seconds}
-```
-
-### 4.2 查图时序图
-
-```mermaid
-sequenceDiagram
-    participant U as 用户 Query
-    participant S as search.py KGSearch.retrieval()
-    participant QP as query_analyze_prompt.py minirag_query2kwd
-    participant ES as Elasticsearch
-    participant LLM as LLM
-
-    U->>S: retrieval(question, workspace_ids, kb_ids, ...)
-    S->>LLM: query_rewrite() PROMPTS["minirag_query2kwd"]
-    LLM-->>S: {answer_type_keywords, entities_from_query}
-
-    par 三路召回并行
-        S->>ES: get_relevant_ents_by_keywords() 向量相似度搜索 entity
-        ES-->>S: 候选实体列表 + sim + pagerank + n_hop
-        S->>ES: get_relevant_ents_by_types() 按类型过滤 entity
-        ES-->>S: 类型匹配实体列表
-        S->>ES: get_relevant_relations_by_txt() 向量相似度搜索 relation
-        ES-->>S: 候选关系列表
-    end
-
-    S->>S: 计算 n-hop 路径权重衰减 sim / (2 + hop_depth)
-    S->>S: 实体排序：sim × pagerank
-    S->>S: Token 预算截断（max_token 递减）
-
-    alt 社区报告召回
-        S->>ES: _community_retrieval_() 按 entities_kwd 匹配 community_report
-        ES-->>S: 社区报告文本
-    end
-
-    S-->>U: {page_content: Entities + Relations + Community Reports, metadata, vector: None}
-```
-
----
-
-## 5. Light vs General 差异
-
-| 维度 | Light | General |
-|---|---|---|
-| 实体抽取 Prompt | LightRAG 风格，含 content_keywords | MS GraphRAG 风格，更简洁 |
-| Gleaning 终止 | 自然语言 yes/no | 强制单字 Y（logit_bias） |
-| 实体消歧 | ❌ 不支持 | ✅ 支持 |
-| 社区发现 | ❌ 不支持 | ✅ Leiden 算法 |
-| 社区报告 | ❌ 不支持 | ✅ LLM 生成报告 |
-| 实体嵌入 | 仅实体名向量 | 支持 Node2Vec（备用） |
-| 思维导图 | ❌ 不支持 | ✅ 支持 |
-| 建图耗时 | ~5-15 分钟 | ~30-60 分钟 |
-| 适用规模 | < 1K 文档 | > 1K 文档 |
-
-**切换条件:** `parser_config["graphrag"]["method"] == "general"` 时启用 General，否则默认 Light。
-
----
-
-## 6. 关键源码索引速查表
-
-| 功能 | 文件 | 关键类/函数 | 行号 |
-|---|---|---|---|
-| 建图总控 | `general/index.py` | `run_graphrag()` | 36-119 |
-| KB 级批量建图 | `general/index.py` | `run_graphrag_for_kb()` | 122-330 |
-| 子图生成 | `general/index.py` | `generate_subgraph()` | 333-406 |
-| Light 实体抽取 | `light/graph_extractor.py` | `GraphExtractor._process_single_content()` | 74-131 |
-| General 实体抽取 | `general/graph_extractor.py` | `GraphExtractor._process_single_content()` | 100-150 |
-| 实体消歧 | `entity_resolution.py` | `EntityResolution.__call__()` | 53-141 |
-| 相似度预筛选 | `entity_resolution.py` | `EntityResolution.is_similarity()` | 225-239 |
-| 社区发现 | `general/leiden.py` | `run()` | 95-141 |
-| 社区报告抽取 | `general/community_reports_extractor.py` | `CommunityReportsExtractor.__call__()` | 55-158 |
-| 图谱检索 | `search.py` | `KGSearch.retrieval()` | 130-280 |
-| Query 改写 | `search.py` | `KGSearch.query_rewrite()` | 33-55 |
-| 图合并工具 | `utils.py` | `graph_merge()` | 199-229 |
-| 实体转 chunk | `utils.py` | `graph_node_to_chunk()` | 301-327 |
-| 关系转 chunk | `utils.py` | `graph_edge_to_chunk()` | 352-378 |
-
-完整源码详解、Prompt 逐段解读、ES 存储设计、配置参数表、边界条件与监控指标，请参阅 [WS-18](mention://issue/16bdb196-e10e-489b-b01c-9067b1f1bb23) 原始交付文档。
-
----
-
-## 7. 跨文档一致性
-
-- 与 [S2-T2] 关于 GraphRAG 实体嵌入缓存（Redis + xxhash）描述一致 ✅
-- 与 [S2-T3] 关于 ES 多类型共存（`knowledge_graph_kwd` 区分 6 种类型）设计一致 ✅
-- 与 [S2-T5] 关于 GraphRAG 检索结果并入向量召回的描述一致 ✅
-- 与 [S2-T6] E2E 时序图中 GraphRAG 分支对齐 ✅
-
----
-
-*本文档为 MemoryBear RAG Docs v1.0 正式版本的组成文件。完整详评与源码解读参见 [WS-18](mention://issue/16bdb196-e10e-489b-b01c-9067b1f1bb23) 评论历史。*

docs/rag/overview/01-architecture.mmd

@@ -1,132 +0,0 @@
-%% MemoryBear RAG 全链路架构图（Mermaid Flowchart）
-%% 约定：浅蓝色 = 数据来源层；浅绿色 = 解析与分块；浅黄色 = 向量化与存储；浅紫色 = 检索；浅橙色 = 生成；浅灰色 = 支撑组件
-
-flowchart TB
-    subgraph DATA_SOURCES["数据来源层 (Loader)"]
-        CRAWLER["Web Crawler\ncrawler/web_crawler.py\n-> 输出: CrawledDocument"]
-        FEISHU["飞书 API\nintegrations/feishu/client.py\n-> 输出: 本地文件 (.docx/.pdf)"]
-        YUQUE["语雀 API\nintegrations/yuque/client.py\n-> 输出: 本地文件 (.md/.html/.xlsx)"]
-        UPLOAD["用户上传\ncontrollers/document_controller.py:275\n-> 输出: 文件路径"]
-    end
-
-    subgraph PARSER["文档解析与分块 (Parser + Chunking)"]
-        NAIVE["app/naive.py:chunk()\n统一分块入口\nDispatch by filename extension"]
-        PDFP["deepdoc/parser/pdf_parser.py\nOCR + Layout + Table"]
-        DOCXP["deepdoc/parser/docx_parser.py"]
-        HTMLP["deepdoc/parser/html_parser.py"]
-        MDPP["deepdoc/parser/markdown_parser.py"]
-        EXCELP["deepdoc/parser/excel_parser.py"]
-        TXTPIP["deepdoc/parser/txt_parser.py"]
-        VISION["deepdoc/vision/\nocr.py + layout_recognizer.py\n+ table_structure_recognizer.py"]
-        NLP["nlp/__init__.py\ntokenize / naive_merge / hierarchical_merge"]
-    end
-
-    subgraph CHUNK_TYPES["文档类型适配 (Task Types)"]
-        BOOK["app/book.py\n长文档分级分块"]
-        PAPER["app/paper.py\n论文结构保持"]
-        MANUAL["app/manual.py\n手册按节分块"]
-        LAWS["app/laws.py\n法规层级树分块"]
-        QA["app/qa.py\n问答对独立分块"]
-        ONE["app/one.py\n整文件单块"]
-        PIC["app/picture.py\nOCR + VLM描述"]
-        AUD["app/audio.py\n语音转文本"]
-    end
-
-    subgraph EMBED["向量化 (Embedding)"]
-        EMB_BASE["llm/embedding_model.py\nBase.encode(texts: list)\n→ (np.array, token_count)"]
-        EMB_PROV["Provider 工厂\nOpenAI / LocalAI / Azure / Tongyi /\nHuggingFace / Xinference / VolcEngine /\nGPUStack / NVIDIA / BaiChuan"]
-    end
-
-    subgraph VDB["向量数据库 (VDB)"]
-        ES_VECT["vdb/elasticsearch/elasticsearch_vector.py\nDense + Sparse 混合索引\ncosineSimilarity + BM25"]
-        ES_CONN["utils/es_conn.py\nES 连接管理"]
-        ES_SCHEMA["vdb/field.py\npage_content / metadata / vector / text\n+ doc_id / knowledge_id / sort_id"]
-    end
-
-    subgraph GRAPHRAG["知识图谱 (GraphRAG)"]
-        G_LIGHT["graphrag/light/\ngraph_extractor.py\n实体+关系抽取\n→ nx.Graph"]
-        G_GEN["graphrag/general/\ngraph_extractor.py\n→ community_reports_extractor.py\n+ mind_map_extractor.py"]
-        G_LEIDEN["general/leiden.py\n层次聚类"]
-        G_RESOLVE["entity_resolution.py\n实体消歧 LLM 匹配"]
-        G_SEARCH["graphrag/search.py\nKGSearch.retrieval()\nQuery分析→实体检索→N-hop→社区报告"]
-    end
-
-    subgraph RETRIEVAL["检索 (Retrieval)"]
-        DEALER["nlp/search.py\nDealer.search()\nHybrid: BM25 0.05 + Vector 0.95"]
-        QRYR["nlp/query.py\nQuery理解 / 关键词扩展"]
-        KNOWLEDGE["nlp/search.py:36\nknowledge_retrieval()\n→ 多知识库合并"]
-    end
-
-    subgraph RERANK["重排序 (Reranking)"]
-        RERANK_M["models/rerank.py\nRedBearRerank\ncompress_documents() / rerank()"]
-        RERANK_P["Provider: JinaRerank /\nDashScopeRerank /\nXINFERENCE / GPUSTACK"]
-    end
-
-    subgraph PROMPT["Prompt 组装"]
-        PGEN["prompts/generator.py\ncitation_prompt / keyword_extraction /\nfull_question / content_tagging /\ntoc_relevance / structured_output"]
-        PTEMPLATE["prompts/template.py\n加载 .md 模板文件"]
-    end
-
-    subgraph LLM["LLM 生成"]
-        CHAT["llm/chat_model.py\nBase.chat() / chat_streamly()\n→ (str, tokens)"]
-        CHAT_PROV["Provider 工厂\nOpenAI / Azure / LocalAI /\nXinference / Tongyi /\nHuggingFace / GPUStack / VolcEngine"]
-    end
-
-    subgraph ORCH["编排层 (Orchestration)"]
-        CELERY["tasks.py\nparse_document() /\nbuild_graphrag_for_kb() /\nbuild_graphrag_for_document()"]
-        WORKFLOW["workflow/nodes/knowledge/node.py\nKnowledgeRetrievalNode.execute()\n→ 检索→去重→重排→返回 chunks"]
-    end
-
-    subgraph POST["后处理"]
-        CITE["插入引用标注\nDealer.insert_citations()\npagerank*sim 评分"]
-        CACHE["缓存层\nutils/redis_conn.py\nLLM 结果缓存"]
-    end
-
-    %% === 数据流 ===
-    DATA_SOURCES --> NAIVE
-    NAIVE --> |PDF| PDFP
-    NAIVE --> |DOCX| DOCXP
-    NAIVE --> |HTML| HTMLP
-    NAIVE --> |MD| MDPP
-    NAIVE --> |XLSX| EXCELP
-    NAIVE --> |TXT| TXTPIP
-
-    PDFP --> VISION
-    VISION --> NLP
-    DOCXP --> NLP
-    HTMLP --> NLP
-    MDPP --> NLP
-    EXCELP --> NLP
-    TXTPIP --> NLP
-
-    NAIVE --> |按文档类型| CHUNK_TYPES
-    CHUNK_TYPES --> NLP
-
-    NLP --> EMB_BASE
-    EMB_BASE --> EMB_PROV
-    EMB_PROV --> ES_VECT
-    ES_SCHEMA --> ES_VECT
-    ES_CONN --> ES_VECT
-
-    NLP -.-> |"并行 (async)"| GRAPHRAG
-    G_LIGHT --> G_SEARCH
-    G_GEN --> G_LEIDEN
-    G_GEN --> G_RESOLVE
-    G_LEIDEN --> G_SEARCH
-    G_RESOLVE --> G_SEARCH
-
-    CELERY --> NAIVE
-    CELERY -.-> |"触发"| GRAPHRAG
-
-    WORKFLOW --> QRYR
-    QRYR --> DEALER
-    DEALER --> KNOWLEDGE
-    KNOWLEDGE --> RERANK_M
-    G_SEARCH --> |"GRAPH模式"| KNOWLEDGE
-    RERANK_M --> RERANK_P
-    RERANK_P --> PGEN
-    PGEN --> PTEMPLATE
-    PTEMPLATE --> CHAT
-    CHAT --> CHAT_PROV
-    CHAT --> CITE
-    CITE --> CACHE

docs/rag/overview/02-indexing-pipeline.mmd

@@ -1,87 +0,0 @@
-%% MemoryBear 文档入库时序图（Indexing Pipeline）
-%% 起点：用户上传 / API 调用；终点：向量入库 + GraphRAG 索引完成
-
-sequenceDiagram
-    autonumber
-    participant User as 用户/API
-    participant API as document_controller.py:275<br/>parse_documents()
-    participant Celery as Celery Worker<br/>tasks.py
-    participant DB as PostgreSQL<br/>(Document / Knowledge)
-    participant Chunker as app/naive.py:508<br/>chunk()
-    participant Parser as deepdoc/parser/<br/>(PDF/DOCX/HTML/...)
-    tokenizer as nlp/__init__.py<br/>tokenize / naive_merge
-    participant Embed as llm/embedding_model.py<br/>Base.encode()
-    participant VDB as ESVectorFactory<br/>elasticsearch_vector.py
-    participant Graph as graphrag/general/index.py<br/>run_graphrag_for_kb()
-
-    Note over User,VDB: === 阶段 1：文件上传与触发 ===
-    User->>API: POST /documents (file / URL)
-    API->>DB: INSERT Document (status=pending)
-    API->>Celery: delay parse_document(file_path, document_id)
-
-    Note over Celery,VDB: === 阶段 2：文档解析与分块 ===
-    Celery->>DB: SELECT Document, Knowledge
-    Celery->>Celery: _build_vision_model()
-    Celery->>Chunker: chunk(filename, binary, vision_model)
-
-    alt PDF 格式
-        Chunker->>Parser: RAGPdfParser.__call__()
-        Parser->>Parser: __images__() → OCR → _layouts_rec()
-        Parser->>Parser: _table_transformer_job()
-        Parser->>Parser: _text_merge() + _concat_downward()
-        Parser-->>Chunker: sections: List[(text, tag)]<br/>tables: List[(image, html)]
-    else DOCX 格式
-        Chunker->>Parser: RAGDocxParser.parse()
-        Parser-->>Chunker: sections, tables
-    else HTML/MD/TXT/Excel
-        Chunker->>Parser: 对应 Parser
-        Parser-->>Chunker: sections
-    end
-
-    alt 按文档类型路由
-        Chunker->>Chunker: book.py / paper.py / laws.py / ...
-        Chunker->>tokenizer: hierarchical_merge() / tree_merge()
-    else 默认 naive
-        Chunker->>tokenizer: naive_merge(sections, chunk_token_num)
-    end
-
-    tokenizer->>tokenizer: tokenize(d) → content_ltks / content_sm_ltks
-    tokenizer->>tokenizer: tokenize_chunks() → 附 page_num / position / image
-    tokenizer-->>Celery: res: List[Dict] (chunk dicts)
-
-    Note over Celery,VDB: === 阶段 3：向量化与存储 ===
-    Celery->>DB: progress=0.8
-    Celery->>VDB: delete_by_metadata_field(document_id)
-
-    alt auto_questions 开启
-        Celery->>Celery: ThreadPool 并发生成问题
-        Celery->>Embed: question_proposal(chat_mdl, content)
-    end
-
-    Celery->>Embed: encode(chunk_texts) → np.array
-    Embed-->>Celery: vectors + token_count
-
-    loop 每 batch
-        Celery->>Celery: 组装 DocumentChunk(page_content, vector, metadata)
-        Celery->>VDB: insert_documents(chunks)
-        VDB->>VDB: cosineSimilarity 索引 + BM25
-        VDB-->>Celery: ack
-    end
-
-    Celery->>DB: UPDATE Document (progress=1.0, chunk_num=N)
-
-    Note over Celery,Graph: === 阶段 4：GraphRAG 异步构建 ===
-    Celery->>Celery: build_graphrag_for_document.delay()
-    Celery->>Graph: run_graphrag_for_kb(document_ids)
-    Graph->>Graph: generate_subgraph() per chunk
-    Graph->>Graph: LLM 抽取 entities + relations
-    Graph->>Graph: merge_subgraph() → nx.pagerank
-    opt entity_resolution
-        Graph->>Graph: resolve_entities() (LLM 匹配)
-    end
-    opt community_reports (general only)
-        Graph->>Graph: leiden.run() 层次聚类
-        Graph->>Graph: CommunityReportsExtractor → LLM 报告
-    end
-    Graph->>VDB: store graph entities / relations / reports
-    Graph-->>Celery: done

docs/rag/overview/03-query-pipeline.mmd

@@ -1,102 +0,0 @@
-%% MemoryBear 在线检索时序图（Query Pipeline）
-%% 起点：用户 Query；终点：LLM 生成的回答
-
-sequenceDiagram
-    autonumber
-    participant User as 用户/API
-    participant WF as Workflow Engine<br/>(workflow/nodes/knowledge/node.py)
-    participant Config as config.py<br/>KnowledgeRetrievalNodeConfig
-    participant Retriever as nlp/search.py<br/>knowledge_retrieval()
-    participant Dealer as nlp/search.py:349<br/>Dealer.search()
-    participant Qryr as nlp/query.py<br/>Query理解
-    participant ESVec as ESVector<br/>elasticsearch_vector.py
-    participant Graph as graphrag/search.py<br/>KGSearch.retrieval()
-    participant Rerank as models/rerank.py<br/>RedBearRerank
-    participant Prompt as prompts/generator.py
-    participant LLM as llm/chat_model.py<br/>Base.chat()
-    participant Cache as utils/redis_conn.py
-
-    Note over User,Cache: === 阶段 1：Query 准备 ===
-    User->>WF: 用户输入 Query
-    WF->>WF: _render_template(query, variable_pool)
-    WF->>Config: 读取 knowledge_bases[]<br/>reranker_id / retrieve_type
-
-    Note over Retriever,ESVec: === 阶段 2：多知识库检索 ===
-    loop 每个 Knowledge Base
-        WF->>Retriever: knowledge_retrieval(query, config)
-        Retriever->>DB: 验证 KB 状态 (chunk_num>0, status=1)
-
-        alt RetrieveType == PARTICIPLE
-            Retriever->>ESVec: search_by_full_text(query, top_k)
-            ESVec->>ESVec: match on page_content (ik_max_word)
-            ESVec-->>Retriever: List[DocumentChunk]
-
-        else RetrieveType == SEMANTIC
-            Retriever->>ESVec: search_by_vector(query, top_k)
-            ESVec->>ESVec: script_score cosineSimilarity
-            ESVec-->>Retriever: List[DocumentChunk]
-
-        else RetrieveType == HYBRID
-            par
-                Retriever->>ESVec: search_by_vector()
-                ESVec-->>Retriever: rs1
-            and
-                Retriever->>ESVec: search_by_full_text()
-                ESVec-->>Retriever: rs2
-            end
-            Retriever->>Retriever: _deduplicate_docs(rs1, rs2)
-            Retriever->>Rerank: rerank(query, docs, top_k)
-            Rerank->>Rerank: similarity() 交叉编码评分
-            Rerank-->>Retriever: sorted docs
-
-        else RetrieveType == GRAPH
-            par
-                Retriever->>ESVec: search_by_vector()
-                ESVec-->>Retriever: rs1
-            and
-                Retriever->>ESVec: search_by_full_text()
-                ESVec-->>Retriever: rs2
-            end
-            Retriever->>Retriever: dedup + rerank
-
-            Retriever->>Graph: kg_retriever.retrieval(question)
-            Graph->>Graph: query_rewrite() → keywords + entities
-            Graph->>ESVec: get_relevant_ents_by_keywords()
-            Graph->>ESVec: get_relevant_relations_by_txt()
-            Graph->>Graph: n_hop_with_weight 路径扩展
-            Graph->>Graph: Score = pagerank * sim
-            Graph->>Graph: _community_retrieval_()
-            Graph-->>Retriever: Entity+Relation+CommunityReport chunk
-            Retriever->>Retriever: insert(0, graph_result)
-        end
-
-        Retriever-->>WF: List[DocumentChunk]
-    end
-
-    WF->>WF: _deduplicate_docs(all_results)
-
-    alt reranker_id 配置
-        WF->>Rerank: rerank(query, all_results, reranker_top_k)
-        Rerank-->>WF: reranked chunks
-    end
-
-    Note over Prompt,Cache: === 阶段 3：Prompt 组装 + LLM 生成 ===
-    WF->>WF: 返回 {"chunks": [...], "citations": [...]}
-    WF->>Prompt: citation_prompt(chunks)
-    Prompt->>Prompt: 组装 System Prompt + 检索上下文
-
-    Prompt->>Cache: get_llm_cache(model, prompt)
-    alt cache miss
-        Prompt->>LLM: chat(system, history, gen_conf)
-        LLM-->>Prompt: answer, tokens
-        Prompt->>Cache: set_llm_cache(model, prompt, answer)
-    else cache hit
-        Cache-->>Prompt: cached answer
-    end
-
-    Note over User,Cache: === 阶段 4：后处理 ===
-    Prompt->>Dealer: insert_citations(answer, chunks, chunk_v)
-    Dealer->>Dealer: pagerank*sim 定位引用位置
-    Dealer-->>Prompt: answer_with_citations, cited_ids
-
-    Prompt-->>User: 最终回答（含引用标注）

docs/rag/overview/04-graphrag-indexing.mmd

@@ -1,78 +0,0 @@
-%% MemoryBear GraphRAG 索引构建时序图
-%% 覆盖 Light 与 General 两条分支的差异
-
-sequenceDiagram
-    autonumber
-    participant Celery as Celery<br/>tasks.py:473
-    participant Index as graphrag/general/index.py<br/>run_graphrag_for_kb()
-    participant KGExt as GraphExtractor<br/>light/graph_extractor.py:31<br/>general/graph_extractor.py:34
-    participant LLM as llm/chat_model.py
-    participant ES as ESVector<br/>elasticsearch_vector.py
-    participant Merge as merge_subgraph()
-    participant Resolve as entity_resolution.py<br/>EntityResolution
-    participant Leiden as general/leiden.py<br/>run()
-    participant Community as general/<br/>community_reports_extractor.py:37
-
-    Note over Celery,Community: === 触发条件 ===
-    Celery->>Celery: build_graphrag_for_kb(kb_id)
-    Celery->>Celery: 检查 parser_config.graphrag.use_graphrag
-    Celery->>Index: run_graphrag_for_kb(row, document_ids, ...)
-
-    Note over Index,LLM: === 阶段 1：子图生成 (按 chunk) ===
-    Index->>Index: init_graphrag(task, vector_size)
-    Index->>Index: generate_subgraph() per chunk
-
-    loop 每个 chunk
-        Index->>KGExt: _process_single_content(chunk_key_dp, chunk_text)
-
-        alt Light 分支
-            KGExt->>KGExt: LightRAG-style prompt<br/>+ content_keywords 提取
-            KGExt->>KGExt: GLEANING loop (max 2)
-        else General 分支
-            KGExt->>KGExt: MS GraphRAG-style prompt<br/>perform_variable_replacements
-            KGExt->>KGExt: tiktoken logit-bias Y/N loop
-        end
-
-        KGExt->>LLM: LLM 调用 → entities + relations JSON
-        LLM-->>KGExt: extracted data
-        KGExt->>KGExt: _merge_nodes() + _merge_edges()
-        KGExt-->>Index: (entities_data, relationships_data)
-    end
-
-    Index->>ES: store subgraph (entities + relations chunks)
-
-    Note over Merge,ES: === 阶段 2：子图合并 ===
-    Index->>Merge: merge_subgraph()
-    Merge->>ES: get_graph() 加载全局图
-    Merge->>Merge: graph_merge(old_graph, subgraph, change)
-    Merge->>Merge: nx.pagerank(new_graph)
-    Merge->>ES: set_graph() 写回全局图 + entities + relations
-
-    Note over Resolve,ES: === 阶段 3：实体消歧 (可选) ===
-    opt with_resolution == True
-        Index->>Resolve: resolve_entities(graph, subgraph_nodes)
-        Resolve->>LLM: 两两实体相似度 LLM 匹配
-        LLM-->>Resolve: 合并建议
-        Resolve->>Resolve: nx.pagerank(graph)
-        Resolve->>ES: set_graph()
-    end
-
-    Note over Leiden,Community: === 阶段 4：社区报告 (General only) ===
-    opt with_community == True (General)
-        Index->>Leiden: leiden.run(graph)
-        Leiden->>Leiden: graspologic.partition.<br/>hierarchical_leiden<br/>max_cluster_size=12
-        Leiden-->>Index: {level: {community_id: {nodes: [...]}}}
-
-        loop 每个 community (nodes >= 2)
-            Index->>Community: __call__(graph, callback)
-            Community->>Community: 构建 entity_df + relation_df
-            Community->>LLM: COMMUNITY_REPORT_PROMPT
-            LLM-->>Community: {title, summary, findings, rating}
-            Community->>Community: add_community_info2graph()
-        end
-
-        Community->>ES: index community_report chunks
-    end
-
-    Note over Index,ES: === Mind Map (独立功能，非主链路) ===
-    Note right of Index: mind_map_extractor.py<br/>由外部调用，非索引管道<br/>sections → 层级 markdown mind map

docs/rag/overview/DocMap.md

@@ -1,194 +0,0 @@
-# DocMap — MemoryBear RAG 文档目录大纲
-
-> **定位**：Sprint-2 深度文档化的任务拆解输入。每行 = 一篇待写文档，标题格式与 [S1-T1] 统一模板兼容。
-> **责任人草拟**：基于当前 Sprint-1 分工建议，实际分配由项目经理确认。
-> **目录结构**：`docs/rag/<stage>/<topic>.md`
-
----
-
-## 文档目录总览
-
-```
-docs/rag/
-├── _meta/                          # [S1-T1] 模板与评分卡（由 @知识运营与治理专家 维护）
-├── 01-loader/
-│   ├── 01-web-crawler.md           # Web 爬虫：URL 发现、内容提取、速率控制
-│   ├── 02-feishu-integration.md    # 飞书集成：API 调用、鉴权、文档导出
-│   ├── 03-yuque-integration.md     # 语雀集成：知识库同步、文档下载
-│   └── 04-file-upload.md           # 文件上传与预处理（本地文件系统、NFS 兼容）
-├── 02-parser/
-│   ├── 01-pdf-parser.md            # PDF 解析：OCR + Layout + Table 流水线
-│   ├── 02-docx-parser.md           # DOCX 解析：段落提取、图片嵌入
-│   ├── 03-html-md-parser.md        # HTML / Markdown / TXT 解析
-│   ├── 04-excel-parser.md          # Excel 解析：行列转表格结构
-│   └── 05-vision-pipeline.md       # 视觉模块：OCR、布局识别、表格结构识别
-├── 03-chunking/
-│   ├── 01-chunking-strategies.md   # 分块策略全景：naive_merge、层级分块、树分块
-│   ├── 02-task-type-adapters.md    # 文档类型适配器：book / paper / laws / qa / one
-│   ├── 03-tokenizer.md             # RagTokenizer：中文分词、英文处理、fine_grained
-│   └── 04-multimodal-chunking.md   # 多模态分块：图片 VLM 描述、音频转文本
-├── 04-embedding/
-│   ├── 01-embedding-model-arch.md  # Embedding 模型架构：Base 接口 + 10+ Provider
-│   ├── 02-provider-guide.md        # Provider 接入指南：OpenAI / HuggingFace / 国产模型
-│   └── 03-auto-questions.md        # 自动问题生成：并发策略、LLM 缓存
-├── 05-vdb/
-│   ├── 01-elasticsearch-schema.md  # ES 索引 Schema：字段定义、mapping、analyzer
-│   ├── 02-hybrid-search.md         # 混合检索：BM25 + Vector 加权融合
-│   └── 03-storage-connections.md   # 存储连接层：ES、Redis、DocStore
-├── 06-graphrag/
-│   ├── 01-graphrag-overview.md     # GraphRAG 总览：Light vs General 对比
-│   ├── 02-entity-relation-extraction.md  # 实体关系抽取：Extractor 流程、Prompt 工程
-│   ├── 03-graph-merge-and-rank.md  # 图合并与 PageRank：子图合并、实体消歧
-│   ├── 04-community-reports.md     # 社区报告：Leiden 聚类、LLM 报告生成（General only）
-│   └── 05-knowledge-graph-search.md # KG 检索：Query 分析、实体匹配、N-hop 扩展
-├── 07-retrieval/
-│   ├── 01-retrieval-api.md         # 检索 API：knowledge_retrieval()、Dealer.search()
-│   ├── 02-query-understanding.md   # Query 理解：关键词提取、同义词扩展
-│   └── 03-multi-kb-retrieval.md    # 多知识库检索：结果合并、去重策略
-├── 08-reranking/
-│   ├── 01-rerank-architecture.md   # 重排序架构：内置评分 vs 外部 Rerank 模型
-│   └── 02-rerank-providers.md      # Rerank Provider：Jina / DashScope / Xinference
-├── 09-prompt/
-│   ├── 01-prompt-system.md         # Prompt 模板系统：template.py + generator.py
-│   ├── 02-citation-prompts.md      # 引用标注 Prompt：citation_prompt / citation_plus
-│   └── 03-toc-prompts.md           # 目录相关 Prompt：TOC 检测、提取、相关性
-├── 10-llm/
-│   ├── 01-llm-chat-model.md        # Chat 模型架构：Base.chat() / chat_streamly()
-│   ├── 02-llm-providers.md         # Chat Provider 全景：OpenAI / Azure / 国产模型
-│   └── 03-vision-model.md          # 视觉模型：VLM 描述、图片理解
-├── 11-e2e/
-│   ├── 01-indexing-pipeline.md     # 端到端入库流程：Celery 任务链、错误处理、进度追踪
-│   ├── 02-query-pipeline.md        # 端到端检索流程：Workflow Node → 检索 → 生成
-│   └── 03-answer-postprocess.md    # 回答后处理：引用插入、缓存、流式输出
-└── 12-architecture-evolution/
-    ├── 01-modularization-roadmap.md  # 模块化拆分建议
-    ├── 02-performance-optimization.md # 性能优化方向
-    └── 03-future-extensions.md       # 未来扩展：多模态检索、混合搜索、对话记忆
-```
-
----
-
-## 文档详细定义
-
-### 01-loader
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 01-01 | Web 爬虫 | **写**：URL 规范化、robots.txt 检查、速率限制、HTTP 抓取、内容提取、去重策略。**不写**：搜索引擎索引、分布式爬虫、JS 渲染。 | `crawler/web_crawler.py`, `crawler/http_fetcher.py`, `crawler/content_extractor.py`, `crawler/rate_limiter.py`, `crawler/robots_parser.py` | Python 工程师 | 需覆盖 CrawledDocument 数据结构 |
-| 01-02 | 飞书集成 | **写**：App 鉴权、文件夹遍历、文档导出（PDF/DOCX/Sheet）、异步轮询下载。**不写**：飞书审批流、机器人消息推送。 | `integrations/feishu/client.py`, `integrations/feishu/retry.py`, `integrations/feishu/models.py` | Python 工程师 | 需说明 `_export_file` vs `_download_file` 区别 |
-| 01-03 | 语雀集成 | **写**：个人 Token 鉴权、知识库遍历、文档详情获取、多种格式下载（MD/HTML/Excel）。**不写**：语雀协作编辑、版本管理。 | `integrations/yuque/client.py`, `integrations/yuque/retry.py`, `integrations/yuque/models.py` | Python 工程师 | lakesheet 解压逻辑需重点说明 |
-| 01-04 | 文件上传 | **写**：文件上传接口、NFS 同步等待、binary 读取策略、进度追踪。**不写**：CDN 分发、大文件分片上传。 | `controllers/document_controller.py`, `utils/file_utils.py`, `tasks.py:213` | Python 工程师 | 30s NFS 等待逻辑是 MemoryBear 特有 |
-
-### 02-parser
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 02-01 | PDF 解析 | **写**：PDF 渲染、OCR 文本检测、布局分类、表格结构识别、文本合并策略。**不写**：PDF 生成/编辑、数字签名验证。 | `deepdoc/parser/pdf_parser.py`, `deepdoc/vision/ocr.py`, `deepdoc/vision/layout_recognizer.py`, `deepdoc/vision/table_structure_recognizer.py` | Python 工程师 | 核心中的核心，需重点投入 |
-| 02-02 | DOCX 解析 | **写**：段落提取、图片提取、超链接提取、OLE 嵌入文件。**不写**：DOCX 生成、样式渲染。 | `deepdoc/parser/docx_parser.py`, `utils/file_utils.py:extract_embed_file` | Python 工程师 | 需与 `app/naive.py` 的 vision_figure_parser 联动说明 |
-| 02-03 | HTML/MD/TXT 解析 | **写**：HTML 标签清洗、Markdown 结构化解析、纯文本处理。**不写**：CSS 样式解析、JS 执行。 | `deepdoc/parser/html_parser.py`, `deepdoc/parser/markdown_parser.py`, `deepdoc/parser/txt_parser.py` | Python 工程师 | 合并为一篇即可 |
-| 02-04 | Excel 解析 | **写**：行列读取、Sheet 遍历、表头检测、Markdown 表格转换。**不写**：公式计算、图表提取。 | `deepdoc/parser/excel_parser.py` | Python 工程师 | 轻量 |
-| 02-05 | 视觉流水线 | **写**：OCR 模型（ONNXRuntime）、布局识别模型、表格结构模型、图像预处理。**不写**：模型训练、模型量化。 | `deepdoc/vision/*.py` | Python 工程师 | 含模型加载、推理、后处理 |
-
-### 03-chunking
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 03-01 | 分块策略全景 | **写**：naive_merge、naive_merge_with_images、hierarchical_merge、tree_merge 的实现与选择策略。**不写**：通用 NLP 分词算法原理。 | `nlp/__init__.py:562+`, `nlp/rag_tokenizer.py` | Python 工程师 | 需附决策树：何时用哪种策略 |
-| 03-02 | 文档类型适配器 | **写**：book/paper/manual/laws/qa/one/picture/audio 各自的分块逻辑、数据结构差异。**不写**：业务场景适配（如医疗/法律专有分块）。 | `app/naive.py:508`, `app/book.py`, `app/paper.py`, `app/manual.py`, `app/laws.py`, `app/qa.py`, `app/one.py`, `app/picture.py`, `app/audio.py` | Python 工程师 | 核心章节，需逐一说明 |
-| 03-03 | RagTokenizer | **写**：中文分词（Huqie/datrie）、英文处理（nltk/Porter/WordNet）、fine_grained_tokenize、分词对检索的影响。**不写**：分词算法数学推导。 | `nlp/rag_tokenizer.py` | Python 工程师 | 与 ES ik_max_word 的对比 |
-| 03-04 | 多模态分块 | **写**：图片 VLM 描述调用链、音频 sequence2txt 转录、视频处理（如有）。**不写**：VLM/ASR 模型内部原理。 | `app/picture.py`, `app/audio.py`, `llm/cv_model.py`, `llm/sequence2txt_model.py`, `deepdoc/parser/figure_parser.py` | Python 工程师 | 需说明 vision_model 注入机制 |
-
-### 04-embedding
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 04-01 | Embedding 模型架构 | **写**：Base.encode() 接口、批次处理、Token 截断（8000/2048）、返回格式。**不写**：Embedding 模型原理（Word2Vec/BERT 等）。 | `llm/embedding_model.py` | Python 工程师 | 重点讲接口契约 |
-| 04-02 | Provider 接入指南 | **写**：10+ Provider 的配置方式、API Key 管理、Base URL 设置、批次大小差异。**不写**：各厂商 API 的通用文档。 | `llm/embedding_model.py` 各子类 | Python 工程师 | 表格形式列出即可 |
-| 04-03 | 自动问题生成 | **写**：并发生成策略（ThreadPoolExecutor）、LLM 缓存机制（redis）、问题注入到 chunk metadata。**不写**：问题生成质量评估。 | `tasks.py:323+`, `prompts/generator.py:question_proposal()` | Python 工程师 | 与检索效果的关系 |
-
-### 05-vdb
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 05-01 | ES 索引 Schema | **写**：字段定义、mapping 类型、ik_max_word analyzer、dense_vector cosine 配置、动态维度。**不写**：ES 集群运维、分片策略。 | `vdb/field.py`, `vdb/elasticsearch/elasticsearch_vector.py:653+` | Python 工程师 | 需附完整 mapping 示例 |
-| 05-02 | 混合检索 | **写**：BM25 + Vector 加权融合（0.05:0.95）、FusionExpr、score 归一化、降级策略。**不写**：BM25 算法数学推导、近似最近邻算法。 | `nlp/search.py:439`, `vdb/elasticsearch/elasticsearch_vector.py:374`, `utils/doc_store_conn.py:FusionExpr` | Python 工程师 | 核心章节，需讲清楚为什么权重是 0.05:0.95 |
-| 05-03 | 存储连接层 | **写**：ES 连接、Redis 缓存、DocStore 抽象。**不写**：连接池调优、网络安全配置。 | `utils/es_conn.py`, `utils/redis_conn.py`, `utils/doc_store_conn.py` | Python 工程师 | 轻量 |
-
-### 06-graphrag
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 06-01 | GraphRAG 总览 | **写**：Light vs General 架构对比、适用场景、配置开关（use_graphrag/resolution/community）。**不写**：图数据库选型对比（已选 ES）。 | `graphrag/light/`, `graphrag/general/`, `graphrag/search.py` | Python 工程师 | 必须包含对比表格 |
-| 06-02 | 实体关系抽取 | **写**：Extractor 基类、_process_single_content 流程、Gleaning Loop、Prompt 工程、LLM 输出解析。**不写**：信息抽取的通用 NLP 方法。 | `graphrag/light/graph_extractor.py`, `graphrag/general/graph_extractor.py`, `graphrag/general/extractor.py` | Python 工程师 | 核心章节 |
-| 06-03 | 图合并与 PageRank | **写**：merge_subgraph 流程、nx.Graph 操作、PageRank 计算、实体消歧（EntityResolution）。**不写**：PageRank 数学推导。 | `graphrag/general/index.py`, `graphrag/entity_resolution.py` | Python 工程师 | 需附图数据结构示例 |
-| 06-04 | 社区报告 | **写**：Leiden 层次聚类、社区报告 Prompt、报告数据结构、存储方式。**不写**：社区发现算法数学原理。 | `graphrag/general/leiden.py`, `graphrag/general/community_reports_extractor.py`, `graphrag/general/community_report_prompt.py` | Python 工程师 | General only |
-| 06-05 | KG 检索 | **写**：KGSearch.retrieval() 流程、Query Rewrite、实体匹配、N-hop 扩展、社区报告检索。**不写**：图遍历算法通用理论。 | `graphrag/search.py:130` | Python 工程师 | 与标准检索的交互关系 |
-
-### 07-retrieval
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 07-01 | 检索 API | **写**：knowledge_retrieval() 接口、Dealer.search() 内部实现、MatchDenseExpr / MatchTextExpr / FusionExpr。**不写**：信息检索通用理论。 | `nlp/search.py:36`, `nlp/search.py:349`, `utils/doc_store_conn.py` | Python 工程师 | 核心章节 |
-| 07-02 | Query 理解 | **写**：关键词提取、同义词扩展、查询改写、min_match 阈值调整。**不写**：NLP 句法分析。 | `nlp/query.py`, `nlp/synonym.py`, `nlp/term_weight.py` | Python 工程师 | 轻量 |
-| 07-03 | 多知识库检索 | **写**：Folder 类型递归检索、跨 KB 结果去重、权限过滤。**不写**：权限系统的 RBAC 设计。 | `workflow/nodes/knowledge/node.py:195`, `knowledge_repository.py` | Python 工程师 | 需说明 Folder 类型的特殊处理 |
-
-### 08-reranking
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 08-01 | 重排序架构 | **写**：内置重排（token+vector 相似度融合）vs 外部 Rerank 模型、调用时机、容错降级。**不写**：Learning-to-Rank 通用理论。 | `nlp/search.py:606`, `models/rerank.py` | Python 工程师 | 需对比两种方式的适用场景 |
-| 08-02 | Rerank Provider | **写**：JinaRerank、DashScopeRerank 的 API 调用、参数映射。**不写**：各厂商 API 通用文档。 | `models/rerank.py:57+` | Python 工程师 | 轻量 |
-
-### 09-prompt
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 09-01 | Prompt 模板系统 | **写**：template.py 的 .md 文件加载机制、generator.py 的函数式 Prompt 组装、参数替换。**不写**：Prompt Engineering 通用方法论。 | `prompts/template.py`, `prompts/generator.py` | Python 工程师 | 需列出全部模板清单 |
-| 09-02 | 引用标注 Prompt | **写**：citation_prompt / citation_plus 的输入输出、引用格式、上下文窗口管理。**不写**：学术论文引用规范。 | `prompts/generator.py:citation_prompt()` | Python 工程师 | 与 insert_citations 联动 |
-| 09-03 | 目录相关 Prompt | **写**：TOC 检测、提取、层级分配、基于 TOC 的 chunk 相关性筛选。**不写**：目录生成算法。 | `prompts/generator.py` TOC 系列函数 | Python 工程师 | 轻量 |
-
-### 10-llm
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 10-01 | Chat 模型架构 | **写**：Base.chat() / chat_streamly() / chat_with_tools() 接口、返回格式、流式输出。**不写**：Transformer 模型原理。 | `llm/chat_model.py` | Python 工程师 | 重点讲接口契约 |
-| 10-02 | Chat Provider 全景 | **写**：各 Provider 配置、温度/TopP/MaxTokens 参数透传、错误处理。**不写**：各厂商 API 通用文档。 | `llm/chat_model.py` 各子类 | Python 工程师 | 表格形式 |
-| 10-03 | 视觉模型 | **写**：CV 模型接口、VLM 描述调用、图片理解。**不写**：CNN/ViT 原理。 | `llm/cv_model.py` | Python 工程师 | 轻量 |
-
-### 11-e2e
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 11-01 | 端到端入库流程 | **写**：Celery 任务链、parse_document 完整流程、进度追踪、错误处理、GraphRAG 异步触发。**不写**：Celery 分布式队列原理。 | `tasks.py` | Python 工程师 | 核心章节，需附时序图 |
-| 11-02 | 端到端检索流程 | **写**：Workflow Knowledge Node 完整流程、检索模式选择、结果组装。**不写**：Workflow Engine 通用设计。 | `workflow/nodes/knowledge/node.py` | Python 工程师 | 核心章节 |
-| 11-03 | 回答后处理 | **写**：引用插入、缓存策略、流式输出处理。**不写**：WebSocket 通用原理。 | `nlp/search.py:489`, `utils/redis_conn.py` | Python 工程师 | 轻量 |
-
-### 12-architecture-evolution
-
-| 序号 | 标题 | 范围边界 | 关联源码模块 | 责任人草拟 | 备注 |
-|------|------|----------|-------------|-----------|------|
-| 12-01 | 模块化拆分建议 | **写**：当前耦合点识别、建议的接口抽象（如 ParserInterface、ChunkerInterface）、拆分优先级。**不写**：微服务拆分方案。 | 全局代码分析 | AI 知识库专家 | 架构建议，无代码 |
-| 12-02 | 性能优化方向 | **写**：Embedding 批处理优化、ES 查询优化、GraphRAG 并发优化、缓存命中率提升。**不写**：通用性能优化方法论。 | 全局代码分析 | AI 知识库专家 | 需量化当前瓶颈假设 |
-| 12-03 | 未来扩展 | **写**：多模态检索、混合搜索增强、对话记忆优化、知识图谱演进方向。**不写**：产品需求文档。 | 全局代码分析 | AI 知识库专家 | 架构建议，无代码 |
-
----
-
-## 工作量估算
-
-| 阶段 | 文档数 | 预估 Sprint-2 人天（每篇 0.5~1d） |
-|------|--------|----------------------------------|
-| 01-loader | 4 | 2d |
-| 02-parser | 5 | 3d |
-| 03-chunking | 4 | 2.5d |
-| 04-embedding | 3 | 1.5d |
-| 05-vdb | 3 | 2d |
-| 06-graphrag | 5 | 3d |
-| 07-retrieval | 3 | 2d |
-| 08-reranking | 2 | 1d |
-| 09-prompt | 3 | 1.5d |
-| 10-llm | 3 | 1.5d |
-| 11-e2e | 3 | 2d |
-| 12-architecture-evolution | 3 | 1.5d |
-| **合计** | **41** | **~23.5d** |
-
-> 注：Python 工程师承担约 30 篇（技术实现细节），AI 知识库专家承担约 8 篇（架构/优化/扩展方向）。具体分配由项目经理确认。

docs/rag/overview/boundaries.md

@@ -1,193 +0,0 @@
-# RAG 环节边界定义
-
-> 目标：明确每个 RAG 阶段的输入 / 输出 / 上下游接口（数据结构层面），避免 Sprint-2 各文档之间留白或重叠。
-
----
-
-## 总览图
-
-```
-[Data Sources] ──→ [Loader] ──→ [Parser] ──→ [Chunking] ──→ [Embedding] ──→ [VDB]
-                                                                      ↑
-                                                                      │ (async)
-                                                              [GraphRAG]
-
-[User Query] ──→ [Query Understanding] ──→ [Retrieval] ──→ [Reranking] ──→ [Prompt] ──→ [LLM] ──→ [Post-Process] ──→ [Answer]
-                                              ↑
-                                              │ (GRAPH mode)
-                                        [KG Search]
-```
-
----
-
-## 1. Loader（数据加载层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | 外部系统：飞书 API、语雀 API、Web URL、用户上传接口 |
-| **输入** | 飞书：folder_token, app_id, app_secret；语雀：user_id, token；Web：entry_url, max_pages；上传：multipart/form-data |
-| **输出** | **原始文件内容**：`CrawledDocument` (dataclass) 或 **本地文件路径** (.docx/.pdf/.md/.html/.xlsx) |
-| **输出数据结构** | `CrawledDocument(url, title, content, content_length, crawl_timestamp, metadata)`；本地文件：`str` (path) |
-| **下游** | Parser：接收文件路径或 bytes，调用对应 format-specific parser |
-| **边界约定** | Loader 不做任何格式解析（不提取正文、不做 OCR）。仅负责：鉴权 → 获取/下载 → 存盘。格式识别由 Parser 层的 `naive.chunk()` 根据文件扩展名决定。 |
-
----
-
-## 2. Parser（文档解析层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | Loader：接收文件路径 `str` 或二进制 `bytes` |
-| **输入** | `(filename: str, binary: bytes \| None, from_page, to_page, callback, vision_model)` |
-| **输出** | `sections: List[Tuple[str, str]]` — (text_content, layout_tag)；`tables: List[Tuple[Tuple[Optional[Image.Image], Union[str, List[str]]], List[Tuple]]]` |
-| **输出数据结构** | 元组列表，其中 tag 表示布局类型（"Title"/"Text"/"Table"/...），text 可能含位置标签 `@@page\tx0\tx1\ttop\tbottom##` |
-| **下游** | Chunking：接收 `sections` + `tables`，执行合并与分块 |
-| **边界约定** | Parser 负责格式-specific 的**纯提取**，不负责语义分块。PDF Parser 特殊：需输出 OCR 结果 + 布局信息 + 表格 HTML。Parser 之间互不调用——由 `naive.chunk()` 统一 dispatch。 |
-
----
-
-## 3. Chunking（文本分块层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | Parser：`sections` + `tables` |
-| **输入** | `sections: List[Tuple[str, str]]`, `tables`, `chunk_token_num: int`, `delimiter: str`, `parser_config: dict` |
-| **输出** | `res: List[Dict]` — 分块后的文档字典列表 |
-| **输出数据结构（关键字段）** | `content_with_weight: str`（原始文本）, `content_ltks: str`（粗粒度分词）, `content_sm_ltks: str`（细粒度分词）, `image: PIL.Image`（可选）, `page_num_int: int`, `position_int: List[int]`, `top_int: int`, `doc_type_kwd: str` |
-| **下游** | Embedding：接收 `res`，提取 `content_with_weight` 进行向量化；GraphRAG：接收 `res` 中的文本进行实体关系抽取 |
-| **边界约定** | Chunking 不调用 Embedding，也不直接写入 VDB。它只负责将长文本切分成符合 token 预算的 chunks，并填充分词/位置元数据。多模态（图片/音频）的分块结果也统一为此数据结构。 |
-
----
-
-## 4. Embedding（向量化层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | Chunking：接收 chunk dicts 的 `content_with_weight` |
-| **输入** | `texts: List[str]`（batch，默认 ≤16 条） |
-| **输出** | `(np.array, total_tokens)` — `np.array` shape `(batch_size, vector_dimension)` |
-| **输出数据结构** | NumPy ndarray，float32；向量维度由模型决定（如 OpenAI text-embedding-3: 1536d） |
-| **下游** | VDB：接收 `(chunk_text, vector, metadata)` 组装成 `DocumentChunk` 后入库 |
-| **边界约定** | Embedding 层无状态，不管理模型生命周期。Provider 通过工厂模式实例化（`Base._FACTORY_NAME` 匹配）。输入文本超长时自动截断（OpenAI 截到 8000 tokens，QWen 截到 2048）。支持 `encode_queries()` 单条 query 编码。 |
-
----
-
-## 5. VDB（向量数据库层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | Embedding：接收 `(text, vector, metadata)`；Chunking：接收 chunk dicts 中的 metadata |
-| **输入** | `DocumentChunk(page_content: str, vector: List[float], metadata: dict)`；或检索时：`query: str, top_k: int, indices: str, score_threshold: float` |
-| **输出（入库）** | ack / error；**输出（检索）**：`List[DocumentChunk]` |
-| **存储 Schema** | `page_content: text(ik_max_word)`, `metadata: object(doc_id, document_id, knowledge_id, sort_id, status)`, `vector: dense_vector(cosine, dynamic_dims)` |
-| **下游** | Retrieval：通过 `search_by_vector` / `search_by_full_text` / `search` (hybrid) 获取结果 |
-| **边界约定** | VDB 同时承担**文档存储**（全文索引）和**向量存储**（密集向量索引）双重职责。ES 是唯一的后端（无 Milvus/Pinecone 等）。GraphRAG 的实体/关系/社区报告也以相同 chunk 格式存储于此。 |
-
----
-
-## 6. GraphRAG（知识图谱层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | Chunking：接收 chunk dicts 的 `content_with_weight`；Celery：异步触发 `build_graphrag_for_document` |
-| **输入（索引）** | `(document_id, chunk_text)` tuples；`chat_model: Base`, `embedding_model: OpenAIEmbed`, `vector_service: ElasticSearchVector` |
-| **输入（检索）** | `question: str, workspace_ids: List[str], kb_ids: List[str], emb_mdl, llm` |
-| **输出（索引）** | `nx.Graph`（全局图）存储到 ES；`entity` chunks + `relation` chunks + `community_report` chunks（General only） |
-| **输出（检索）** | `Dict` with `page_content` = "Entities CSV + Relations CSV + Community Reports"，`metadata` 含引用信息 |
-| **下游** | VDB：索引/存储实体、关系、社区报告 chunks；Retrieval：`KGSearch.retrieval()` 返回的 chunk 被 `insert(0, ...)` 插入标准检索结果 |
-| **边界约定** | GraphRAG 是**独立异步流程**，不与标准 RAG 索引同步。Light 和 General 共享相同的存储格式但 General 多出 community_report。GraphRAG 不替代 VDB，而是**在 VDB 之上增加图语义层**。检索时 KG 结果优先级最高（insert at position 0）。 |
-
----
-
-## 7. Retrieval（检索层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | VDB：通过 `search_by_vector` / `search_by_full_text` 获取候选；GraphRAG：`KGSearch.retrieval()` 获取图语义结果；Workflow Node：`KnowledgeRetrievalNode.execute()` 发起调用 |
-| **输入** | `query: str, config: Dict(knowledge_bases[], merge_strategy, reranker_id, reranker_top_k, use_graph)` |
-| **输出** | `List[DocumentChunk]` — 按相关性降序排列的文档块 |
-| **输出数据结构** | `DocumentChunk(page_content: str, metadata: dict)`，其中 metadata 含 `score`, `doc_id`, `document_id`, `knowledge_id`, `highlight` |
-| **下游** | Reranking：接收候选列表，可选执行重排序；Prompt：接收 chunks 组装上下文 |
-| **边界约定** | Retrieval 层支持 4 种模式：PARTICIPLE（全文）、SEMANTIC（向量）、HYBRID（混合）、GRAPH（图增强）。多 KB 时逐 KB 检索后合并。HYBRID 的默认权重为 BM25 0.05 + Vector 0.95。检索失败（空结果）时自动降级（min_match 0.1 + similarity 0.17 重试）。 |
-
----
-
-## 8. Reranking（重排序层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | Retrieval：接收候选 `List[DocumentChunk]` |
-| **输入** | `query: str, docs: List[DocumentChunk], top_k: int`；或 `reranker_id: UUID` |
-| **输出** | `List[DocumentChunk]` — 重排序后的文档块（长度 ≤ top_k） |
-| **输出数据结构** | 同 Retrieval 输出，metadata 中更新 `score` 为重排序后的分数 |
-| **下游** | Prompt：接收重排序后的 chunks 组装上下文 |
-| **边界约定** | Reranking 是**可选层**。未配置 reranker_id 时，HYBRID 结果按 metadata.score 降序截断。配置了 reranker_id 时，调用外部 Rerank API（Jina / DashScope / Xinference）。Rerank 失败时**降级**到原始结果（不阻断流程）。 |
-
----
-
-## 9. Prompt（Prompt 组装层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | Reranking：接收排序后的 chunks；Workflow：接收用户 query |
-| **输入** | `chunks: List[DocumentChunk], query: str, system_prompt: str`（可选） |
-| **输出** | `system: str, history: List[Dict]` — LLM 可调用的消息格式 |
-| **输出数据结构** | `system: str`（含检索上下文 + 系统指令），`history: [{"role": "user", "content": query}]` |
-| **下游** | LLM：`Base.chat(system, history, gen_conf)` |
-| **边界约定** | Prompt 层**不**调用 LLM，只负责**文本组装**。组装逻辑包括：citation_prompt（引用标注格式）、keyword_extraction（用于缓存 key）、content_tagging（内容分类）。Prompt 模板以 `.md` 文件形式存储在 `prompts/` 目录，通过 `template.py` 动态加载。 |
-
----
-
-## 10. LLM（大模型生成层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | Prompt：接收 `system` + `history` |
-| **输入** | `system: str, history: List[Dict], gen_conf: dict(temperature, top_p, max_tokens)` |
-| **输出** | `(answer: str, tokens: int)` 或流式 `Generator[str \| int]` |
-| **输出数据结构** | 字符串（生成的回答文本）；流式模式下逐 token 返回 |
-| **下游** | Post-Process：`insert_citations()` 插入引用标注 |
-| **边界约定** | LLM 层**无上下文记忆**（stateless），每次调用携带完整 history。支持 10+ Provider，通过 `_FACTORY_NAME` 工厂模式匹配。流式输出通过 `chat_streamly()` 实现，返回 Generator。错误处理：API 异常时抛出，由上层（Workflow / Celery）捕获。 |
-
----
-
-## 11. Post-Process（后处理层）
-
-| 维度 | 定义 |
-|------|------|
-| **上游** | LLM：接收生成的 `answer`；Retrieval：接收原始 `chunks` + `chunk_v`（向量） |
-| **输入** | `answer: str, chunks: List[DocumentChunk], chunk_v: List[np.array], embd_mdl, tkweight, vtweight` |
-| **输出** | `(answer_with_citations: str, cited_ids: Set[str])` |
-| **输出数据结构** | 字符串（含 `[1]`, `[2]` 等引用标记），`Set[str]`（被引用的 chunk id 集合） |
-| **下游** | User：最终展示；Cache：写入 Redis 缓存 |
-| **边界约定** | Post-Process 只做**引用标注插入**（`insert_citations()`），不做内容修改。引用定位算法基于 `pagerank * similarity` 评分。代码块（```...```）内**不**插入引用。缓存键由 `(model_name, prompt_text)` 组合生成，TTL 由 Redis 配置决定。 |
-
----
-
-## 跨层数据流总表
-
-| 阶段 | 输入数据类型 | 输出数据类型 | 关键数据结构 / 文件 |
-|------|-------------|-------------|---------------------|
-| Loader | URL / Token / File | `CrawledDocument` / `str` (path) | `crawler/models.py`, `integrations/*/models.py` |
-| Parser | `str` (path) / `bytes` | `List[Tuple[str, str]]` + tables | `deepdoc/parser/*.py` |
-| Chunking | sections + tables | `List[Dict]` | `nlp/__init__.py`, `app/naive.py` |
-| Embedding | `List[str]` | `(np.array, int)` | `llm/embedding_model.py` |
-| VDB | `DocumentChunk` | ack / `List[DocumentChunk]` | `vdb/field.py`, `models/chunk.py` |
-| GraphRAG | chunk texts | `nx.Graph` + chunks | `graphrag/search.py`, `graphrag/general/index.py` |
-| Retrieval | `query + config` | `List[DocumentChunk]` | `nlp/search.py` |
-| Reranking | `query + docs` | `List[DocumentChunk]` | `models/rerank.py` |
-| Prompt | `chunks + query` | `system + history` | `prompts/generator.py` |
-| LLM | `system + history` | `str + int` | `llm/chat_model.py` |
-| Post-Process | `answer + chunks` | `str + Set[str]` | `nlp/search.py:489` |
-
----
-
-## 留白与重叠风险点
-
-| 风险区域 | 说明 | 建议归属 |
-|----------|------|----------|
-| **Parser ↔ Chunking 边界** | Parser 输出的 `sections` 格式（含 tag 和位置信息）被 Chunking 的 `naive_merge` 直接消费。若 Parser 改了 tag 格式，Chunking 会受影响。 | **统一在 Parser 文档中定义 `sections` 数据契约**，Chunking 文档只引用该契约。 |
-| **Embedding ↔ VDB 边界** | Embedding 输出维度必须与 VDB mapping 中 `dense_vector` 的 dims 一致。动态维度由首次 encode 决定。 | **Embedding 文档声明维度获取方式**，VDB 文档只引用。 |
-| **GraphRAG ↔ VDB 边界** | GraphRAG 的实体/关系/社区报告以 `DocumentChunk` 格式存入 VDB，与标准 chunk 共用同一 ES index。 | **VDB 文档定义通用存储格式**，GraphRAG 文档只说明使用了该格式。 |
-| **Retrieval ↔ Reranking 边界** | Retrieval 的 HYBRID 模式在 Node 层已做 dedup，但 `knowledge_retrieval()` 函数也有独立 rerank 调用。 | **Reranking 文档**说明两种调用路径（Node 层 vs 函数层）的区别。 |
-| **Prompt ↔ LLM 边界** | Prompt 组装的 `history` 格式必须与各 Provider 的 API 格式兼容。 | **Prompt 文档**声明输出格式规范，LLM 文档说明各 Provider 的适配。 |

docs/rag/overview/source-inventory.md

@@ -1,249 +0,0 @@
-# [S1-T3] MemoryBear RAG 源码盘点与模块依赖关系图谱 — 交付物
-
-## 一、模块清单
-
-> 统计口径：`api/app/core/rag/` 全部子目录 + `api/app/core/workflow/nodes/knowledge` + `api/app/core/rag_utils/` 共 **~24,900+ LOC** Python 代码。
-
-| 子模块路径 | 主要职责 | 入口文件 / 关键类 / 关键函数 | 对外接口（被谁调用 / 调用谁） | 第三方依赖 | 文件数 / 行数 |
-|---|---|---|---|---|---|
-| `rag/app` | 文档解析与分块 orchestrator；按 doc_type 路由到不同解析策略（naive / book / paper / qa / audio / picture / manual / laws / mail / one） | `naive.py:508 chunk()`、`naive.py:257 naive.__call__()`、`naive.py:27 by_deepdoc()`、`naive.py:45 by_mineru()`、`naive.py:65 by_textln()` | 被 `tasks.py` 调用（Celery ingestion）；调用 `deepdoc/parser` + `deepdoc/vision` + `rag/nlp` + `rag/llm/cv_model` + `rag/llm/sequence2txt_model` | `python-docx`, `openpyxl`, `pdfplumber`, `markdown`, `Pillow` | 12 / 2,923 |
-| `rag/common` | RAG 共享常量、异常、装饰器、工具函数（文件/浮点/日志/字符串/Token 计数） | `constants.py`（常量定义）、`token_utils.py`（encoder）、`settings.py:13 init_settings()`（单例初始化） | 被 `rag/utils/es_conn.py`、`rag/graphrag/utils.py`、`rag/nlp/search.py` 等广泛 import | `tiktoken`（tokenizer） | 12 / 602 |
-| `rag/crawler` | Web 页面抓取与内容提取 | `web_crawler.py`、`content_extractor.py`、`http_fetcher.py` | 被 `tasks.py` 调用；由 knowledge sync 触发 | `requests` | 9 / 1,237 |
-| `rag/deepdoc/parser` | 11 种格式文档解析（PDF/Word/Excel/HTML/MD/JSON/TXT/PPT） | `pdf_parser.py:34 RAGPdfParser.__call__:1124`、`docx_parser.py:9 RAGDocxParser`、mineru_parser.py:41 MinerUParser` | 被 `rag/app/naive.py` import 并调用 | `pdfplumber`, `pypdf`, `python-docx`, `openpyxl`, `beautifulsoup4`, `markdown`, `pandas` | 12 / 3,228 |
-| `rag/deepdoc/vision` | 文档视觉分析：布局识别 + OCR + 表格结构识别 | `ocr.py:522 OCR.__call__:694`、`layout_recognizer.py:17 LayoutRecognizer`、`table_structure_recognizer.py:15 TableStructureRecognizer` | 被 `pdf_parser.py` 调用进行版面/表格/图像识别 | `onnxruntime`, `huggingface_hub`, `Pillow`, `opencv-python`, `numpy` | 10 / 3,657 |
-| `rag/graphrag`（顶层） | GraphRAG 共享工具、实体消歧、查询分析提示、知识图谱搜索 | `search.py:19 KGSearch(Dealer)`、`entity_resolution.py:31 EntityResolution`、`utils.py`（graph merge/persist/LLM cache） | 被 `tasks.py`、workflow knowledge node、prompts/generator.py 调用 | `networkx`, `pandas`, `trio`, `redis`, `xxhash`, `json_repair` | 6 / 1,452 |
-| `rag/graphrag/general` | 通用/完整版 GraphRAG 流水线：子图抽取 → 合并 → 实体消歧 → Leiden 社区 → 社区报告 | `index.py:36 run_graphrag()`、`index.py:122 run_graphrag_for_kb()`、`graph_extractor.py:34 GraphExtractor`、`community_reports_extractor.py:37` | 被 `tasks.py` 的 Celery task 调用；调用 `ElasticSearchVector` 写图数据 | `networkx`, `graspologic`, `tiktoken`, `trio` | 11 / 1,857 |
-| `rag/graphrag/light` | 轻量版 GraphRAG（LightRAG 风格）：简化实体/关系抽取，无社区报告 | `light/graph_extractor.py:31 GraphExtractor` | 被 `general/index.py` 根据 `parser_config.graphrag.method` 条件切换调用 | `networkx`, `trio` | 3 / 462 |
-| `rag/integrations/feishu` | 飞书文档同步客户端 | `client.py: FeishuAPIClient` | 被 `knowledge_controller.py` + `tasks.py` 调用 | `requests` | 6 / 737 |
-| `rag/integrations/yuque` | 语雀文档同步客户端 | `client.py: YuqueAPIClient` | 被 `knowledge_controller.py` + `tasks.py` 调用 | `requests` | 6 / 844 |
-| `rag/llm` | LLM 多模型统一 facade（Chat / Embedding / CV / Seq2txt） | `chat_model.py:52 Base`、`embedding_model.py:14 Base`、`cv_model.py:19 Base`、`sequence2txt_model.py:15 Base` | 被 `rag/app`、`rag/nlp/search`、`rag/graphrag`、`rag/vdb`、`workflow/nodes/knowledge` 等调用 | `openai`, `dashscope`, `azure-openai`, `ollama`, `zhipuai`, `requests` | 5 / 1,676 |
-| `rag/models` | Chunk 数据模型 | `chunk.py:17 DocumentChunk`、`chunk.py:5 ChildDocumentChunk` | 被 `rag/vdb`、`rag/app`、`workflow/nodes/knowledge`、`tasks.py` 引用 | `pydantic` | 2 / 72 |
-| `rag/nlp` | NLP 工具箱：中文分词、BM25/hybrid 搜索调度、同义词扩展、术语权重、Query 重写 | `search.py:349 Dealer`（含 `retrieval:674`、`search:387`、`rerank:606`）、`rag_tokenizer.py:15 RagTokenizer`、`query.py:10 FulltextQueryer` | 被 `rag/app/naive.py`、`rag/graphrag`、`rag/prompts/generator.py`、`rag/common/settings.py` 调用 | `datrie`, `hanziconv`, `nltk`, `pandas`, `numpy` | 7 / 2,962 |
-| `rag/prompts` | Prompt 模板加载与 LLM prompt 工厂 | `template.py:9 load_prompt()`、`generator.py`（citation/keyword/question/toc/reflect 等 20+ 函数） | 被 `tasks.py`、`rag/nlp/search.py`、`rag/graphrag` 调用；依赖 `.md` prompt 文件 | `jinja2`, `json_repair` | 3 / 769 + 31 md 文件 |
-| `rag/utils` | ES 连接、Redis 连接、LibreOffice 转换、文件工具 | `es_conn.py: ESConnection`、`redis_conn.py`、`libre_office.py`、`file_utils.py`、`doc_store_conn.py` | 被 `rag/vdb`、`rag/common/settings.py`、`rag/app/naive.py`、`rag/nlp/search.py` 调用 | `elasticsearch`, `redis` | 6 / 1,578 |
-| `rag/vdb` | 向量数据库抽象 + Elasticsearch 实现 | `elasticsearch/elasticsearch_vector.py:29 ElasticSearchVector`、`elasticsearch/elasticsearch_vector.py:666 ElasticSearchVectorFactory`、`vector_base.py:9 BaseVector` | 被 `tasks.py`、`knowledge_controller.py`、`chunk_controller.py`、`workflow/nodes/knowledge` 调用 | `elasticsearch`, `langchain-core` | 3 / 83 + 2 / 753 |
-| `rag/res` | 静态资源：NER 词表、同义词表、映射表 | `ner.json`、`synonym.json`、`mapping.json` | 被 `rag/nlp/term_weight.py`、`rag/nlp/synonym.py` 加载 | — | 3 JSON |
-| `workflow/nodes/knowledge` | Workflow 知识检索节点：多知识库检索 + 重排序 + GraphRAG 增强 | `node.py:29 KnowledgeRetrievalNode`、`node.py:303 execute()`、`node.py:195 knowledge_retrieval()` | 被 `workflow/nodes/node_factory.py`、`workflow/nodes/__init__.py` 注册；调用 `rag/vdb`、`rag/llm`、`rag/models` | `langchain-core` | 3 / 455 |
-| `rag_utils`（⚠️ 与 `rag/utils` 不同） | Chunk 内容 LLM 分析：摘要生成、标签提取、洞察分析、人物画像 | `chunk_summary.py:68 generate_chunk_summary()`、`chunk_tags.py:56 extract_chunk_tags()`、`chunk_insight.py:137 generate_chunk_insight()` | 被 `services/memory_dashboard_service.py` 调用；依赖 `app.core.memory.*` LLM 工厂 | `pydantic` | 4 / 588 |
-
----
-
-## 二、依赖关系图谱（Mermaid）
-
-```mermaid
-graph TB
-    subgraph "上层调用者"
-        A1[tasks.py<br/>Celery Workers]
-        A2[controllers/<br/>REST API]
-        A3[workflow/nodes/<br/>知识检索节点]
-        A4[services/memory_<br/>dashboard_service.py]
-    end
-
-    subgraph "RAG Core"
-        B1[rag/app<br/>解析与分块]
-        B2[rag/deepdoc/parser<br/>格式解析]
-        B3[rag/deepdoc/vision<br/>版面/OCR]
-        B4[rag/crawler<br/>网页抓取]
-        B5[rag/integrations<br/>飞书/语雀]
-        B6[rag/nlp<br/>分词/搜索调度]
-        B7[rag/llm<br/>多模型Facade]
-        B8[rag/vdb<br/>ES向量存储]
-        B9[rag/graphrag<br/>知识图谱]
-        B10[rag/prompts<br/>Prompt工厂]
-        B11[rag/models<br/>Chunk模型]
-        B12[rag/common<br/>常量/工具]
-        B13[rag/utils<br/>ES/Redis连接]
-    end
-
-    subgraph "旁路模块"
-        C1[rag_utils<br/>Chunk LLM分析]
-    end
-
-    A1 --> B1
-    A1 --> B4
-    A1 --> B5
-    A1 --> B8
-    A1 --> B9
-    A1 --> B10
-    A2 --> B1
-    A2 --> B5
-    A2 --> B8
-    A2 --> B9
-    A3 --> B8
-    A3 --> B7
-    A3 --> B11
-    A4 --> C1
-
-    B1 --> B2
-    B1 --> B3
-    B1 --> B6
-    B1 --> B7
-    B2 --> B3
-    B2 --> B6
-    B3 --> B12
-    B4 --> B13
-    B5 --> B13
-    B6 --> B7
-    B6 --> B13
-    B6 --> B10
-    B8 --> B7
-    B8 --> B11
-    B8 --> B13
-    B9 --> B6
-    B9 --> B7
-    B9 --> B10
-    B9 --> B13
-    B10 --> B7
-    B10 --> B9
-
-    C1 --> B7
-    B12 --> B13
-    B13 --> B8
-```
-
----
-
-## 三、入口链路梳理
-
-### 3.1 文档入库链路（Indexing Pipeline）
-
-```
-REST POST /document 或 /knowledge/{id}/sync
-    ↓ 触发
-Celery task @tasks.py:212 parse_document(file_path, document_id)
-    ↓ 调用
-rag/app/naive.py:508 chunk(filename, binary, ...)
-    ↓ 路由 by file extension
-    ├─ PDF → by_deepdoc() → deepdoc/parser/pdf_parser.py:34 RAGPdfParser.__call__:1124
-    ├─ PDF alt → by_mineru() → deepdoc/parser/mineru_parser.py:41 MinerUParser.parse_pdf()
-    ├─ DOCX → RAGDocxParser.__call__() @ docx_parser.py:9
-    ├─ XLSX → RAGExcelParser.__call__() @ excel_parser.py:16
-    ├─ HTML → RAGHtmlParser.__call__() @ html_parser.py:22
-    ├─ MD  → RAGMarkdownParser.__call__() @ markdown_parser.py:6
-    ├─ JSON → RAGJsonParser.__call__() @ json_parser.py:7
-    └─ TXT → RAGTxtParser.__call__() @ txt_parser.py:7
-    ↓
-rag/app/naive.py:257 naive.__call__() — 提取 sections + tables
-    ↓
-rag/nlp/__init__.py — tokenize / naive_merge / hierarchical_merge
-    ↓
-rag/vdb/elasticsearch/elasticsearch_vector.py:55 add_chunks()
-    ↓ 调用
-rag/vdb/elasticsearch/elasticsearch_vector.py:65 create()
-    ↓ 调用
-embedding_model.py: encode() → LLM API → ES bulk index
-```
-
-### 3.2 在线检索链路（Query Pipeline）
-
-```
-REST POST /retrieval
-    或
-Workflow Node: workflow/nodes/knowledge/node.py:303 execute()
-    ↓
-workflow/nodes/knowledge/node.py:195 knowledge_retrieval()
-    ↓ 根据 retrieve_type 分支
-    ├─ PARTICIPLE → ElasticSearchVector.search_by_full_text() @ elasticsearch_vector.py:468
-    ├─ SEMANTIC  → ElasticSearchVector.search_by_vector() @ elasticsearch_vector.py:374
-    ├─ HYBRID    → 并行 vector + full_text → dedupe → rerank @ node.py:236-271
-    └─ Graph     → HYBRID 结果 + kg_retriever.retrieval()
-                        ↓ 调用
-                        rag/common/settings.py:10 kg_retriever (单例)
-                        ↓ 调用
-                        rag/graphrag/search.py:19 KGSearch.retrieval()
-```
-
-### 3.3 GraphRAG 构建链路
-
-```
-REST POST /knowledge/{knowledge_id}/knowledge_graph
-    或
-Celery task @tasks.py:472 build_graphrag_for_kb(kb_id)
-    ↓
-Celery task @tasks.py:557 build_graphrag_for_document(document_id, knowledge_id)
-    ↓
-rag/graphrag/general/index.py:36 run_graphrag(row, language, with_resolution, with_community, ...)
-    ↓
-rag/graphrag/general/index.py:122 run_graphrag_for_kb(kb_id, ...)
-    ↓ 流水线
-    1. init_graphrag() → 创建 ES 索引
-    2. GraphExtractor.extract() → 逐 chunk 抽取实体/关系
-       ├─ general/graph_extractor.py:34 GraphExtractor (Microsoft GraphRAG 风格)
-       └─ light/graph_extractor.py:31 GraphExtractor (LightRAG 风格，条件切换)
-    3. graph_merge() → 合并子图
-    4. EntityResolution.resolve() → 实体消歧
-    5. leiden.run() → 社区发现
-    6. CommunityReportsExtractor.extract() → 社区摘要
-    7. set_graph() → 写回 ES
-```
-
-### 3.4 Workflow Knowledge 节点链路
-
-```
-workflow/nodes/knowledge/node.py:29 KnowledgeRetrievalNode
-    ↓
-node.py:54 _extract_input() — 渲染 query 模板，读取 knowledge_bases 配置
-    ↓
-node.py:303 execute()
-    ↓
-node.py:335 get_knowledge_by_id() — 校验知识库存在性
-    ↓
-node.py:195 knowledge_retrieval()
-    ↓ 分支处理
-    ├─ FOLDER 类型 → 递归遍历子知识库
-    ├─ PARTICIPLE → vector_service.search_by_full_text()
-    ├─ SEMANTIC  → vector_service.search_by_vector()
-    ├─ HYBRID    → vector + full_text 并行 → dedupe → rerank
-    └─ Graph     → HYBRID + kg_retriever.retrieval() 增强
-    ↓
-node.py:108 rerank() — 调用 RedBearRerank 模型
-    ↓
-node.py:362 返回 {"chunks": [...], "citations": [...]}
-```
-
----
-
-## 四、Gap 报告（代码 vs S1-T2 架构预期）
-
-### 4.1 "架构里列了但代码里没有 / 命名/范围不一致"
-
-| # | 差异项 | S1-T2 架构预期 | 代码实际 | 影响与建议 |
-|---|---|---|---|---|
-| 1 | **缺少 Milvus/Weaviate/Qdrant 支持** | VDB 环节预期讨论"向量数据库选型"，暗示可能多库 | 仅 `rag/vdb/elasticsearch/` 有实现，`BaseVector` 无其他子类 | 架构文档中 VDB 章节需要明确限定为 Elasticsearch 8.x，或规划扩展接口 |
-| 2 | **`rag_utils` vs `rag/utils` 命名冲突** | 预期目录：`api/app/core/rag/{deepdoc,crawler,integrations,llm,vdb,graphrag,prompts,app}` | 实际存在 `rag/utils`（文件工具/ES 连接）**和** `rag_utils/`（Chunk LLM 分析）两个独立目录，仅下划线差异 | 极易混淆，建议将 `rag_utils/` 重命名为 `rag/chunk_analytics/` 或合并到 `rag/app/` 下游 |
-| 3 | **`nlp/search.py` 中的 `Dealer` 是遗留/旁路模块** | 架构中 `rag/nlp` 预期为"分词/NLP 工具" | `rag/nlp/search.py:349 Dealer` 实际是一个完整的 BM25/hybrid 搜索调度器，与 `rag/vdb` 的 ES 向量搜索并行存在两套检索体系 | 两套检索代码并存（`nlp/search.py` 主要被 GraphRAG 使用，`vdb/elasticsearch` 被 Workflow 使用）。架构文档应明确标注 `nlp/search` 是 GraphRAG 专用旧通道 |
-| 4 | **缺少独立的 Reranking 模块** | S1-T2 预期有独立的 Reranking 环节 | 重排序逻辑散布在多处：`workflow/nodes/knowledge/node.py:108 rerank()`、`rag/vdb/elasticsearch/elasticsearch_vector.py:560 rerank()`、以及 `rag/nlp/search.py:606 rerank()` | 建议 Sprint-2 文档将 Reranking 单独成章，汇总这三处实现并标注差异（Workflow 节点用 RedBearRerank，VDB 层也有独立 rerank，NLP 层有 model-based rerank） |
-| 5 | **Prompt 目录含大量 .md 模板但无统一版本管理** | Prompt 工程是独立环节 | `rag/prompts/` 有 31 个 `.md` 模板文件 + `template.py`（加载器）+ `generator.py`（工厂函数），但模板修改无版本控制/审计机制 | 建议文档中标注 prompt 管理现状：文件驱动、运行时加载、无 A/B 或版本回滚机制 |
-| 6 | **Deepdoc vision 模型加载路径硬编码** | 架构预期模型管理可配置 | `deepdoc/vision/` 各 recognizer 硬编码从 `huggingface_hub.snapshot_download(repo_id="InfiniFlow/deepdoc")` 下载到 `res/deepdoc/`，仅 `HF_ENDPOINT` 环境变量可配 | 建议文档中明确标注模型路径约束，为后续模型热更新/私有化部署做铺垫 |
-| 7 | **GraphRAG light 是条件分支而非独立模块** | S1-T2 预期 GraphRAG 有 light 和 general 两个独立目录 | `light/` 仅含 `graph_extractor.py` + `graph_prompt.py`（2 个逻辑文件），其余全部复用 `general/` 的 `Extractor` 基类、`utils.py`、`index.py` | Sprint-2 文档应将 light 标记为"general 的条件子模式"，避免读者误以为两套完整流水线 |
-
-### 4.2 "代码里有但架构没列"
-
-| # | 差异项 | 代码位置 | 说明 |
-|---|---|---|---|
-| 1 | **rag/app 按 doc_type 路由的 11 种解析策略** | `rag/app/{naive,book,paper,qa,audio,picture,manual,laws,mail,one,textin_parser}.py` | S1-T2 架构只提到 "Loader / Parser"，未提及 MemoryBear 特有的 doc_type 路由体系（book/paper/qa/audio 等） |
-| 2 | **MinerU 第三方解析器集成** | `rag/deepdoc/parser/mineru_parser.py` | 架构中 Parser 环节未提及 MinerU（第三方 PDF 解析服务）作为 PDF 解析的替代方案 |
-| 3 | **TextIn 第三方解析器集成** | `rag/app/textin_parser.py` | 同上，未提及 TextIn API 作为另一 PDF 解析备选 |
-| 4 | **rag_utils（Chunk LLM 分析）** | `api/app/core/rag_utils/` | 架构中无此模块定位，它实际做 chunk 摘要/标签/洞察，与 Memory 系统耦合 |
-| 5 | **Toc（目录）智能提取链路** | `rag/prompts/generator.py:408-717` | 大量 LLM-driven TOC 检测/提取/索引/关联代码，架构大纲中未单列 "TOC 处理" 环节 |
-| 6 | **Crawler（网页抓取）** | `rag/crawler/` | 架构中 Loader 环节可能包含爬虫，但代码量 1,200+ LOC 值得单独标注 |
-| 7 | **res/ 静态资源（NER、同义词表）** | `rag/res/{ner.json,synonym.json,mapping.json}` | 架构中未提及术语权重/同义词扩展的资源文件体系 |
-
----
-
-## 五、关键数据速查
-
-| 指标 | 数值 |
-|---|---|
-| `api/app/core/rag/` 总 Python LOC | ~24,895 |
-| `api/app/core/rag/` 子模块数 | 15（不含 res/） |
-| `.md` Prompt 模板数 | 31 |
-| Parser 实现数 | 11 种（含 PDF 3 种策略：deepdoc/mineru/textin） |
-| LLM Provider 实现数 | Chat 9 种 + Embed 10 种 + CV 7 种 + Seq2txt 6 种 = **32 个 provider 类** |
-| Workflow Knowledge 检索类型 | PARTICIPLE / SEMANTIC / HYBRID / Graph（4 种） |
-| GraphRAG 模式 | general（Microsoft GraphRAG）/ light（LightRAG 风格） |
-| VDB 实现 | Elasticsearch 8.x（唯一） |
-
----
-
-以上交付物已同步写入本地文件 `WS-14-deliverable.md`，可作为 Sprint-2 文档化的底图直接复用。

docs/rag/pipeline/01-loader-parser-chunking.md

@@ -1,623 +0,0 @@
----
-title: "[S2-T1] 文档加载与预处理（Loader / Parser / Chunking）实现详解"
-author: Python 开发工程师
-last-reviewed-at: 2026-05-08
-source-commit: HEAD (origin/main, MemoryBear)
-scope: api/app/core/rag/{crawler, integrations, deepdoc, nlp, models, utils, app/naive.py, common/token_utils.py}
----
-
-## 0. 一句话定位
-
-把"任意来源、任意格式"的原始资料，沉淀为带元数据、可被 Embedding/索引消费的标准化 **Chunk** 序列；这一段是 RAG 召回质量的"硬天花板"——它做不好，下游再多优化都救不回来。
-
-## 1. 设计目标与适用场景
-
-| 目标 | 落地策略 |
-|---|---|
-| 多源接入（爬虫 / 飞书 / 语雀 / 本地文件） | `crawler/`、`integrations/feishu`、`integrations/yuque` 三套 SDK，均落到本地文件后再走统一 `chunk()` 入口 |
-| 多格式解析（PDF/Word/Excel/PPT/HTML/MD/JSON/TXT/图片/音视频） | `app/naive.py:chunk()` 单一编排入口，按扩展名分派到 `deepdoc/parser/*` 与 `app/{audio,picture}.py` |
-| 复杂 PDF 还原（表格、图、版面） | `RAGPdfParser` + OCR + 版面识别 + TSR + XGBoost 段落连接模型 |
-| 长文 Chunking 既保语义又控 token | `naive_merge` / `naive_merge_docx` / `hierarchical_merge` / `tree_merge` 多种策略，统一以 `cl100k_base` 计算 token |
-| 同一篇资料的多模态（图 + 文 + 表） | `tokenize_chunks_with_images`、`tokenize_table` 把图片/表格作为附属信息挂在 chunk 上 |
-| 健壮性 | 鉴权 token 缓存、退避重试、robots.txt 合规、编码自动嗅探、嵌入文件递归解构 |
-
-适用于：私有知识库、企业文档库、技术资料归档；不适用于：实时流式数据、对端到端延迟<200ms 的场景（OCR 与版面识别是 CPU/GPU 重负载）。
-
-## 2. 术语表
-
-- **Section**：解析器吐出的中间结构 `(text, position_or_layout)` 元组列表，是 Chunking 之前的"原料"。
-- **Chunk**：最终交给 Embedding 的文本片段，一般 ≤ `chunk_token_num` 个 token（默认 128–512）。
-- **Token**：用 `tiktoken.cl100k_base` 编码后得到的 BPE token 数（与 OpenAI gpt-4 同口径）。
-- **Layout**：页面区块类别（title / text / figure / table / equation 等），由 YOLOv10 检测。
-- **TSR**：Table Structure Recognition，复杂表格行/列/合并单元格的结构还原。
-- **OCR**：文字检测 + 文字识别两阶段的图像字符抽取。
-- **Embed file**：内嵌在 docx/xlsx/pptx 内部的子文件（如 docx 里嵌的 Excel），需递归解析。
-
-## 3. 实现概览（数据流图）
-
-```mermaid
-flowchart LR
-    subgraph Loader["Loader / 多源接入"]
-        A1[本地文件] --> CHUNK
-        A2[Web 站点] --> WC[WebCrawler<br/>BFS 同域]
-        A3[飞书云文档] --> FS[FeishuAPIClient<br/>导出/下载]
-        A4[语雀知识库] --> YQ[YuqueAPIClient<br/>raw markdown]
-        WC --> CD[CrawledDocument<br/>title+content]
-        FS --> LF[本地文件]
-        YQ --> LF
-        CD --> CHUNK
-        LF --> CHUNK
-    end
-
-    subgraph Parser["Parser / 格式分派"]
-        CHUNK[app/naive.py: chunk] --> EX[extract_embed_file<br/>嵌入文件递归]
-        CHUNK -->|.pdf| PARSERS[PARSERS dict<br/>deepdoc/mineru/textln/plaintext]
-        CHUNK -->|.docx| DOCX[Docx/RAGDocxParser]
-        CHUNK -->|.xlsx/.csv| XLS[RAGExcelParser]
-        CHUNK -->|.md| MD[Markdown/RAGMarkdownParser]
-        CHUNK -->|.html| HTML[RAGHtmlParser]
-        CHUNK -->|.json/.jsonl| JSON[RAGJsonParser]
-        CHUNK -->|.txt/code| TXT[RAGTxtParser]
-        CHUNK -->|.ppt/.pptx| LO[LibreOffice<br/>convert_to_pdf]
-        CHUNK -->|.doc| TIKA[Apache Tika]
-        CHUNK -->|图片/音视频| MM[picture/audio<br/>vision_llm_chunk]
-        LO --> PARSERS
-        PARSERS --> OCR[OCR + LayoutRecognizer + TSR]
-        DOCX --> SEC[(sections)]
-        XLS --> SEC
-        MD --> SEC
-        HTML --> SEC
-        JSON --> SEC
-        TXT --> SEC
-        OCR --> SEC
-        TIKA --> SEC
-    end
-
-    subgraph Chunking["Chunking / 切分 + 索引化"]
-        SEC --> NM{有图片?}
-        NM -->|否| NM1[naive_merge]
-        NM -->|是·docx| NM2[naive_merge_docx]
-        NM -->|是·md| NM3[naive_merge_with_images]
-        NM1 --> TC[tokenize_chunks]
-        NM2 --> TCI[tokenize_chunks_with_images]
-        NM3 --> TCI
-        TT[tokenize_table] --> ESDOC
-        TC --> ESDOC[(ES Doc<br/>content_with_weight<br/>content_ltks<br/>page_num_int<br/>position_int<br/>image)]
-        TCI --> ESDOC
-    end
-```
-
-## 4. Loader 章节
-
-### 4.1 Web Crawler（`crawler/`）
-
-- **入口**：`WebCrawler(entry_url, max_pages, delay_seconds, timeout_seconds, user_agent, include_patterns, exclude_patterns)`，源码 `api/app/core/rag/crawler/web_crawler.py:19`。
-- **架构**：BFS（`deque` + `visited_urls`）+ 五个独立组件：`URLNormalizer` / `RobotsParser` / `RateLimiter` / `HTTPFetcher` / `ContentExtractor`，全部通过组合而非继承装配，便于替换。
-- **同域限制**：`URLNormalizer.is_same_domain()` 强制只爬入口域名，避免无界扩散（`url_normalizer.py:102-124`）。
-- **去重**：`URLNormalizer.normalize()` 做：小写 host、去 fragment、去默认端口、剥离 utm_*/fbclid/gclid 等追踪参数、按字母序排 query。`url_normalizer.py:28-100`。
-- **robots.txt 合规**：`RobotsParser.can_fetch()` 与 `get_crawl_delay()`，使用 stdlib 的 `urllib.robotparser`，每域名缓存。robots.txt 拉取失败时**默认允许**（permissive fallback），`robots_parser.py:60-69`。
-- **限速**：`RateLimiter` 默认 1s/请求，`set_delay()` 可被 `Crawl-delay` 动态覆盖（上限 60s 防呆）；`backoff(2.0)` 用于 429/503 指数退避，`rate_limiter.py:38-58`。
-- **HTTP 重试**：`HTTPFetcher` 内置 `max_retries=3`，退避 `1s → 2s → 4s`；429 与 503 显式触发重试，404/4xx 立即返回不重试，5xx 重试到耗尽。`http_fetcher.py:54-180`。
-- **编码处理**：`HTTPFetcher._get_decoded_content` 五级回退：HTML meta charset → response.encoding（跳过 ISO-8859-1） → UTF-8 → GBK/Big5/Shift-JIS/EUC-KR 等 → latin-1 with errors='replace'。`http_fetcher.py:182-248`。
-- **正文抽取**：`ContentExtractor.extract` 基于 `lxml`：移除 `script/style/nav/header/footer/aside`，按 `<article>/<main>` → `[role=main]` → `class/id =~ content|main|article|post` → `<body>` 顺序找主体；用 `is_static_content` 检测"脚本多文本少"的 SPA 页面并直接跳过。`content_extractor.py:24-72`。
-- **错误统计**：`stats.error_breakdown` 记录每种错误类型的计数，便于事后分析。`web_crawler.py:210-215`。
-
-```python
-# api/app/core/rag/crawler/web_crawler.py:103-145（节选）
-while self.url_queue and self.pages_processed < self.max_pages:
-    url = self.url_queue.popleft()
-    if url in self.visited_urls: continue
-    self.visited_urls.add(url)
-    if not self.robots_parser.can_fetch(url):       # robots.txt
-        self.stats['skipped'] += 1; continue
-    self.rate_limiter.wait()                        # 限速
-    fetch_result = self.http_fetcher.fetch(url)     # 重试 + 退避
-    if not fetch_result.success:
-        self._record_error(fetch_result.error or "Unknown error"); continue
-    content_type = fetch_result.headers.get('Content-Type', '').lower()
-    if not any(s in content_type for s in ['text/html', 'application/xhtml+xml']):
-        self.stats['skipped'] += 1; continue        # 非 HTML 跳过
-    extracted = self.content_extractor.extract(fetch_result.content, url)
-    if not extracted.is_static:
-        self.stats['skipped'] += 1; continue        # JS-only 站点跳过
-```
-
-### 4.2 飞书集成（`integrations/feishu/`）
-
-- **入口**：`FeishuAPIClient(app_id, app_secret, api_base_url, timeout, max_retries)`，`integrations/feishu/client.py:24`，是异步客户端（`httpx.AsyncClient`），用 `async with` 管理生命周期。
-- **鉴权**：`tenant_access_token` 模式，`get_tenant_access_token()` 用 `cachetools.TTLCache(maxsize=1, ttl=7200-300)` 缓存（飞书原生 2 小时有效，提前 5 分钟失效）+ `asyncio.Lock` 双检锁防并发请求 token。`client.py:51-127`。
-- **文件类型分派**：`download_document` 按 `document.type` 分两条路径：
-  - **在线文档（doc/docx/sheet/bitable）**：`_export_file` 走"创建导出任务 → 轮询 ticket → 下载 file_token"三步，最多轮询 10 次、间隔 2s，超时抛 `FeishuAPIError`。`client.py:311-406`。
-  - **附件文件（file/slides）**：`_download_file` 直接 GET `/drive/v1/files/{token}/download`，从 `Content-Disposition` 解析 `filename*=UTF-8''xxx` 编码文件名。`client.py:408-452`。
-- **限流与重试**：装饰器 `@with_retry`（`feishu/retry.py:124-137`）。`RetryStrategy.RETRYABLE_ERRORS = (FeishuNetworkError, FeishuRateLimitError, httpx.TimeoutException/ConnectError/ReadError)`，`MAX_RETRIES=3`，退避 `[1, 2, 4]s`；HTTP 429/502/503/5xx 重试，4xx（除 429）不重试；飞书业务码 `99991400/99991401`（限流码）也强制重试。`feishu/retry.py:24-76`。
-- **错误模型**：精细化异常树 `FeishuAuthError / FeishuAPIError / FeishuNotFoundError / FeishuPermissionError / FeishuRateLimitError / FeishuNetworkError / FeishuDataError`，调用方据此决定告警级别。`feishu/exceptions.py:1-46`。
-- **分页与递归**：`list_folder_files` 单页（page_size=200）；`list_all_folder_files(recursive=True)` 自动展开子文件夹。`client.py:226-269`。
-
-```python
-# api/app/core/rag/integrations/feishu/client.py:78-120（鉴权 + 双检锁缓存）
-cached_token = self._token_cache.get("access_token")
-if cached_token: return cached_token
-async with self._token_lock:
-    cached_token = self._token_cache.get("access_token")
-    if cached_token: return cached_token
-    response = await self._http_client.post(
-        "/auth/v3/tenant_access_token/internal",
-        json={"app_id": self.app_id, "app_secret": self.app_secret})
-    data = response.json()
-    if data.get("code") != 0:
-        raise FeishuAuthError(f"Authentication failed: {data.get('msg')}",
-                              error_code=str(data.get("code")), details=data)
-    token = data.get("tenant_access_token")
-    self._token_cache["access_token"] = token
-    return token
-```
-
-### 4.3 语雀集成（`integrations/yuque/`）
-
-- **入口**：`YuqueAPIClient(user_id, token, api_base_url, timeout, max_retries)`，`integrations/yuque/client.py:27`。
-- **鉴权**：个人 PAT，HTTP header `X-Auth-Token`，无需 OAuth/token 刷新（语雀的 token 是长期 token），故没有 token 缓存层。`client.py:55-66`。
-- **API 三段式**：`get_user_repos()` → `get_repo_docs(book_id)` → `get_doc_detail(id, raw=1)`；`get_doc_detail` 用 `params={"raw": 1}` 拉原始 markdown。`client.py:119-291`。
-- **格式分派（download_document）**：根据 `doc.format` 决定本地文件后缀：
-  - `markdown` / `lake` → `.md`（lake 也按 markdown 保存，因为 lake 在 raw 模式下输出兼容 md）
-  - `html` → `.html`
-  - `lakesheet` → `.xlsx`，需 `zlib.decompress(bytes(sheet_data, 'latin-1'))` 解压后由 `generate_excel_from_sheet` 用 openpyxl 重建工作簿（含字体、对齐、颜色、合并单元格）。`client.py:293-545`。
-- **限流与重试**：与飞书同构，`yuque/retry.py:21-118`，`RetryStrategy` 配置一致；HTTP 状态码 401→`YuqueAuthError`、403→`YuquePermissionError`、404→`YuqueNotFoundError`、429→`YuqueRateLimitError`，由 `_handle_api_error` 统一翻译。`client.py:73-117`。
-- **健壮性**：`get_user_repos`/`get_repo_docs` 对单条数据 `try/except` 跳过坏记录而不整体失败（容忍语雀 schema 漂移）。`client.py:158-160, 221-223`。
-
-### 4.4 本地文件（`app/naive.py:chunk`）
-
-- 是所有 Loader 的最终汇入口；接收 `filename` 与 `binary` 两种入参，二者互斥（推荐 `binary`，源码内 `extract_embed_file` 显式不支持 path 模式，详见 `app/naive.py:541`）。
-- **嵌入文件递归**：根调用（`is_root=True`）会先用 `extract_embed_file()` 抽出 docx/xlsx/pptx 内部嵌入的子文件（通过 zip 名单 `word/embeddings/`、`xl/embeddings/`、`ppt/embeddings/` 或 OLE 容器的 `Ole10Native`），逐个递归 `chunk()`，结果合入 `embed_res`。`utils/file_utils.py:69-130` + `app/naive.py:533-552`。
-- **超链接深挖**：`parser_config.analyze_hyperlink=True` 时，docx/pdf 内部超链接经 `extract_links_from_docx` / `extract_links_from_pdf` 抽出后，每条 URL 调用 `extract_html` 拉回 HTML 二进制并递归 `chunk(url, html_bytes, is_root=False)`。`app/naive.py:556-566, 793-803`。
-- **callback 进度上报**：`chunk(..., callback=progress_callback)`，约定 `callback(prog: float, msg: str)`，关键节点：0.05（嵌入抽取）/ 0.1（开始解析）/ 0.6（OCR 完）/ 0.63（版面）/ 0.65（表格）/ 0.67（合并）/ 0.8（解析完）。
-
-## 5. Parser 章节
-
-### 5.1 总分派器（`app/naive.py`）
-
-`chunk()` 是入口，按文件扩展名走分支：
-
-```python
-# api/app/core/rag/app/naive.py:97-102
-PARSERS = {
-    "deepdoc":  by_deepdoc,
-    "mineru":   by_mineru,
-    "textln":   by_textln,
-    "plaintext": by_plaintext,  # default
-}
-# api/app/core/rag/app/naive.py:553-764
-if re.search(r"\.docx$", filename, re.IGNORECASE): ...
-elif re.search(r"\.pdf$", filename, re.IGNORECASE): ...      # 走 PARSERS dict
-elif re.search(r"\.(pptx|ppt?)$", ...): ...                  # LibreOffice → pdf
-elif re.search(r"\.(da|wav|mp3|...)$", ...): ...             # app/audio.py
-elif re.search(r"\.(png|jpeg|...)$", ...): ...               # app/picture.py
-elif re.search(r"\.(csv|xlsx?)$", ...): ExcelParser
-elif re.search(r"\.(txt|py|js|java|...)$", ...): TxtParser
-elif re.search(r"\.(md|markdown)$", ...): Markdown(MarkdownParser 子类)
-elif re.search(r"\.(htm|html)$", ...): HtmlParser
-elif re.search(r"\.(json|jsonl|ldjson)$", ...): JsonParser
-elif re.search(r"\.doc$", ...): tika  # Apache Tika via JVM
-```
-
-PDF 的 `parser_config.layout_recognize` 决定底层走哪条 PDF 引擎，默认 `DeepDOC`：
-
-| layout_recognize | 引擎 | 调用 | 适用 |
-|---|---|---|---|
-| `DeepDOC` | `Pdf(RAGPdfParser)` | `by_deepdoc` | 复杂版面、扫描件 |
-| `Plain Text` | `PlainParser` | `by_plaintext` | 纯文本 PDF，速度快 |
-| `MinerU` | `MinerUParser` | `by_mineru` | 高质量结构化（外部进程或 HTTP） |
-| `TextLn` | `TextLnParser` | `by_textln` | TextIn API（云端付费） |
-| 任意（含 `vision_model`） | `VisionParser` | `by_plaintext` 分支 | 多模态 LLM 直读 |
-
-### 5.2 PDF 解析（`deepdoc/parser/pdf_parser.py`，1387 行）
-
-`RAGPdfParser` 是大头，调用栈：
-
-```python
-# api/app/core/rag/app/naive.py:373-412 （Pdf.__call__ 节选）
-self.__images__(filename if not binary else binary, zoomin, from_page, to_page, callback)
-callback(0.6, f"OCR finished")
-self._layouts_rec(zoomin)              # 版面识别
-callback(0.63, "Layout analysis")
-self._table_transformer_job(zoomin)    # TSR
-callback(0.65, "Table analysis")
-self._text_merge(zoomin=zoomin)        # 文本合并
-self._extract_table_figure(...)        # 提取表与图
-self._naive_vertical_merge()
-self._concat_downward()                # XGBoost 段落连接（updown_concat_xgb）
-self._final_reading_order_merge()
-return [(b["text"], self._line_tag(b, zoomin)) for b in self.boxes], tbls
-```
-
-要点：
-- **OCR**：`OCR()`（`deepdoc/vision/ocr.py:522`）= `TextDetector` + `TextRecognizer` 组合；`pdfplumber` 把每一页 `to_image(resolution=72*zoomin=216).annotated`，再过 OCR。`pdf_parser.py:1006-1122`。
-- **版面识别**：`LayoutRecognizer4YOLOv10`（默认，10 个 label：title / Text / Reference / Figure / Figure caption / Table / Table caption / Equation 等），或 `AscendLayoutRecognizer`（Ascend NPU），由 `LAYOUT_RECOGNIZER_TYPE` 环境变量切换。`pdf_parser.py:53-67` + `vision/layout_recognizer.py:147-160`。
-- **表格结构识别**：`TableStructureRecognizer`（`vision/table_structure_recognizer.py`），裁出 table 区域后把行/列重组成 HTML；与 docx 的"按上下文找最近标题"风格一致。`pdf_parser.py:178-220`。
-- **段落连接模型**：`updown_cnt_mdl`（XGBoost），输入是上下相邻两块的 31 维特征（句末是否标点、x0 距离、行内 token 数、字号差、layout_type 等），决定要不要把下一块续到上一块。`pdf_parser.py:113-156` + `pdf_parser.py:70-83`（模型从 HuggingFace `InfiniFlow/text_concat_xgb_v1.0` 拉）。
-- **位置标签**：每个文本块带 `@@<page>\t<x0>\t<x1>\t<top>\t<bottom>##` 的位置 tag，`remove_tag()` 用 `re.sub(r"@@[\t0-9.-]+?##", "", txt)` 去掉，`extract_positions()` 反解。`pdf_parser.py:1219-1229`。
-- **GPU 加速**：通过 `pip_install_torch()` + `torch.cuda.is_available()` 把 XGBoost 推到 CUDA；`PARALLEL_DEVICES > 1` 时用 `trio.CapacityLimiter` 做多卡并行。`pdf_parser.py:50-77, 1095-1106`。
-- **HuggingFace 模型分发**：`InfiniFlow/text_concat_xgb_v1.0` 通过 `snapshot_download` 拉到 `res/` 目录；推荐 `export HF_ENDPOINT=https://hf-mirror.com` 解决国内拉取慢，`deepdoc/README.md:42`。
-
-#### 5.2.1 备选 PDF 引擎
-
-- **`PlainParser`**（`pdf_parser.py:1300`）：`pypdf.PdfReader` 直接 `extract_text()`，每行一段 + 解析 outline 目录；无 OCR、无版面、无图，纯文本极快。
-- **`VisionParser`**（`pdf_parser.py:1334`）：把每一页转成 PIL.Image，整页直接喂给 `vision_model`（`QWenCV` / `AzureGptV4` 等），让多模态 LLM "看图说话"产出 markdown。`@@page\tx0\tx1\ty0\ty1##` 位置 tag 由 `(0, 0, width/zoomin, 0, height/zoomin)` 占位生成（即整页矩形），方便下游对齐 chunk 与原图。
-- **`MinerUParser`**（`mineru_parser.py:41`）：调用外部 `mineru` 进程（CLI 模式）或 `MINERU_APISERVER`（HTTP 模式，默认 `host.docker.internal:9987`），后端可选 `pipeline / vlm-http-client / vlm-transformers / vlm-vllm-engine`；输出 zip 解压后融合为 sections + tables。`naive.py:45-62`。
-- **`TextLnParser`**（`app/textin_parser.py`）：合合 TextIn 云端 PDF→Markdown 服务，需要 `TEXTLN_APP_ID/SECRET_CODE`。
-
-### 5.3 Word 解析（`deepdoc/parser/docx_parser.py` + `naive.py:Docx`）
-
-两层：
-
-- **底层 `RAGDocxParser`**（`docx_parser.py:9-123`）：`python-docx`+`pandas` 读段落与表格；表格内容经 `__compose_table_content` 做"列类型推断"（日期 Dt / 数字 Nu / 中文人名 Nr / 英文 En 等 11 类正则），自动识别多行表头并把单元格拼成 `表头：值` 格式，保证表格在 chunk 中也能被关键词检索。
-- **上层 `Docx(RAGDocxParser)`**（`naive.py:105-323`）：把段落里的图片用 `python-docx` 的 `xpath('.//pic:pic')` 抽出，挂到对应 paragraph；表格区域用 `__get_nearest_title` 上溯到 7 级标题构造层级路径作为 `<caption>Table Location: A > B > C</caption>`，这是检索时定位表格上下文的关键。
-- **超链接抽取**：`extract_links_from_docx` 遍历 `document.part.rels`，过滤 reltype 为 hyperlink 的关系，得到链接集合。`utils/file_utils.py:133-154`。
-- **`to_markdown`**：可选回退路径，使用 `mammoth.convert_to_html` + `markdownify`，图片嵌成 `data:` base64 URL。`naive.py:325-366`。
-- **NULL 关系修复**：上层 `Docx` 用 `load_from_xml_v2` monkey-patch 掉 `_SerializedRelationships.load_from_xml`，跳过 `../NULL` 与 `NULL` target 以绕过 python-docx#1105 已知 bug。`naive.py:493-506, 569`。
-
-### 5.4 Excel/CSV 解析（`deepdoc/parser/excel_parser.py`）
-
-- **多引擎容错**：`_load_excel_to_workbook` 先看魔数：`PK\x03\x04`（OOXML）或 `\xd0\xcf\x11\xe0`（OLE2）。openpyxl 失败回退 `pandas.read_excel`，再失败回退 `engine="calamine"`；非 Excel 头则当 CSV 处理（`pd.read_csv(on_bad_lines='skip')` 容忍坏行）。`excel_parser.py:18-53`。
-- **非法字符清洗**：`ILLEGAL_CHARACTERS_RE = re.compile(r"[\000-\010]|[\013-\014]|[\016-\037]")`，`_clean_dataframe` 把所有字符串单元格里的控制字符替换成空格，避免写入 Workbook 报错。`excel_parser.py:13, 56-62`。
-- **三种输出形态**：
-  - `__call__()`：每行 → `表头1：值1\n表头2：值2\n...\n——SheetName`，作为一个 section（一个 chunk）。`excel_parser.py:203-246`。
-  - `html()`：每 256 行打包成一张 `<table>`，header 复用，便于检索时整块召回。`excel_parser.py:144-187`。
-  - `markdown()`：`df.to_markdown(index=False)`，整个表一段。
-- **图片抽取**：`_extract_images_from_worksheet` 通过 `ws._images` 的 anchor.row/col 还原图片位置，输出 `single_cell` / `multi_cell` span_type 元数据。`excel_parser.py:98-142`。
-- **重要：Excel 不走 `naive_merge`**：`naive.py:678-680` 显式注释"Excel 每行直接作为一个 chunk，不经过 naive_merge 避免被 delimiter 拆分"——直接 `tokenize_chunks(chunks, ...)`。
-
-### 5.5 Markdown 解析（`deepdoc/parser/markdown_parser.py`）
-
-- **表格抽取**：`extract_tables_and_remainder` 用三个正则按顺序剥离：标准 GFM 边框表格 → 无边框表格 → HTML `<table>...</table>`（含 `<html><body>` 包装），每张表单独成一个 chunk，剩余正文继续走 element 抽取。`markdown_parser.py:10-106`。
-- **元素抽取**：`MarkdownElementExtractor.extract_elements(delimiter)` 按行扫描，识别 `header(#~######)` / `code_block(```)` / `list_block(-/*/+/数字.)` / `blockquote(>)` / `text_block`，每种元素用对应私有方法收集起止行号。`markdown_parser.py:109-277`。
-- **图片嵌入**：当传入 `vision_model` 时，naive.py 会对每个 section 调 `markdown_parser.get_pictures()`（HTTP 下载或本地路径打开），把图片合并 `concat_img` 后丢给 `VisionFigureParser` 让 LLM 描述图片，描述文本拼回 section 末尾。`naive.py:697-709`。
-- **超链接深挖**：`get_hyperlink_urls(soup)` + `analyze_hyperlink=True` 触发递归 chunk。`naive.py:716-720`。
-
-### 5.6 HTML 解析（`deepdoc/parser/html_parser.py`）
-
-- **预清洗**：BeautifulSoup html5lib，移除 `<style>/<script>`，剥离 inline `style` 属性与 HTML 注释。`html_parser.py:39-52`。
-- **递归读文本**：`read_text_recursively` 给每个 BLOCK_TAG（h1-h6/p/div/article/section/aside/ul/ol/li/table/pre/code/blockquote/figure/figcaption）分配 `block_id` UUID，把 NavigableString 收集到所属 block。`<table>` 整段保留，单独给 `table_id` 元数据。`html_parser.py:89-131`。
-- **标题前缀化**：`merge_block_text` 在拼接时把 `h1-h6` 改写为 `# ~ ######`（Markdown 风格），保留层级语义到下游。`html_parser.py:134-161`。
-- **二次切分**：`chunk_block(block_txt_list, chunk_token_num=512)` 按 `chunk_token_num`（默认 512）合并 block，超长 block 用 `rag_tokenizer.tokenize()` 切成等长片段。`html_parser.py:163-196`。
-
-### 5.7 JSON 解析（`deepdoc/parser/json_parser.py`）
-
-- **结构感知切分**：`_json_split` 递归遍历 dict，按 `_json_size`（即 `json.dumps(...)` 的字符长度，乘以 2 作为 max_chunk_size）累计；超过 max 但当前 chunk ≥ min（`max - 200`）时开新 chunk，否则继续递归到子节点。**关键设计**：list 通过 `_list_to_dict_preprocessing` 转成索引化 dict，让数组也能按结构切分。`json_parser.py:46-95`。
-- **JSONL 自动检测**：`is_jsonl_format` 抽样前 10 行，若 ≥ 80% 行单独 `json.loads` 成功且整体不能 parse 为单个 JSON，则按 JSONL 处理。`json_parser.py:134-152`。
-
-### 5.8 TXT/代码 解析（`deepdoc/parser/txt_parser.py`）
-
-- 简单版：`get_text` 读全文（`find_codec` 嗅探编码），按 `delimiter="\n!?;。；！？"` 切分，**就地累加 token**：当前 chunk 超 `chunk_token_num` 才开新 chunk。`txt_parser.py:8-48`。
-- 适配的扩展名集：`.txt|.py|.js|.java|.c|.cpp|.h|.php|.go|.ts|.sh|.cs|.kt|.sql`，`naive.py:685`。
-
-### 5.9 图片/音视频（`app/picture.py` / `app/audio.py`）
-
-- 图片：`from app.core.rag.app.picture import chunk` → `picture_vision_llm_chunk(binary, vision_model, prompt, callback)`，多模态 LLM 直接产文。
-- 音视频：`from app.core.rag.app.audio import chunk` → 调 `seq2txt_mdl`（`QWenSeq2txt` 即 `qwen3-omni-flash`）做语音转文字。
-- PDF 也可以走 VisionParser 让 LLM 整页"看图说话"，是 OCR 失败/扫描件的兜底。
-
-### 5.10 PPT 与 .doc：外部依赖
-
-- **PPTX/PPT** → `naive.py:628-651`：调 `async_convert_to_pdf`（`utils/libre_office.py:59-62`）把文件转 PDF，再递归 `chunk(dest_pdf_path, ...)`。
-- LibreOffice 路径硬编码 `/usr/bin/soffice`（Linux）或 `/Applications/LibreOffice.app/Contents/MacOS/soffice`（macOS），都不存在则抛 `HTTP 500`；`subprocess.run` 设 `timeout=120s` 防卡死。`utils/libre_office.py:11-57`。
-- 用 `ThreadPoolExecutor(max_workers=os.cpu_count()*2)` 提交异步转换任务；同进程多请求共享线程池。
-- **DOC（旧版二进制）** → `naive.py:738-761`：使用 Apache Tika（`tika-server.jar` JVM 进程，端口 9998）。环境必须有 Java 11+；初始化 `tika.initVM()` 后 `tika_parser.from_file(filename)['content']` 按 `\n` 切分。
-
-### 5.11 视觉子系统（`deepdoc/vision/`）
-
-- **OCR**：`OCR.__call__(img, device_id, cls)` 内部跑 `TextDetector` 检测文字框 → `TextRecognizer` 识别字符 → 可选方向分类。`vision/ocr.py:522, 694`。模型走 ONNX。
-- **LayoutRecognizer4YOLOv10**：YOLOv10 ONNX 模型，10 类 label，在 `__call__(image_list, ocr_res, scale_factor=3, thr=0.2, batch_size=16, drop=True)` 中接收图像与 OCR 结果，输出每个文字框的 layout 类型并把 `header/footer` 等 drop 掉。
-- **TableStructureRecognizer**：检测表格单元格的列、行、列头、合并单元格等 5 类。
-- **VisionFigureParser**（`figure_parser.py:52-118`）：用 `ThreadPoolExecutor(10)` 并发把每张图片喂给 `vision_model`，超时 30s（`@timeout(30, 3)` 装饰器表示 30s 超时、3 次重试）。`vision_llm_figure_describe_prompt()` 给出统一的"详细描述这张图"指令。
-
-## 6. Chunking 章节
-
-### 6.1 Token 计数（`common/token_utils.py`）
-
-- 模型固定为 `tiktoken.cl100k_base`（GPT-4 / text-embedding-ada-002 同口径），缓存目录 `res/`。`token_utils.py:6-9`。
-- `num_tokens_from_string(s)` 容错：`encode` 失败返回 0（不会让上层报错）。`token_utils.py:12-18`。
-- `truncate(s, max_len)` 按 token 截断，保护 LLM 上下文。`token_utils.py:56-58`。
-
-### 6.2 编码嗅探（`nlp/__init__.py:37-55`）
-
-- `find_codec(blob)`：先 `chardet.detect(blob[:1024])` 置信度 > 0.5 用结果（"ascii" 强制升级到 "utf-8"，避开 chardet 经典误判）；置信度低则按预设 80+ 编码顺序列表逐个 `decode` 尝试，全失败 fallback `utf-8`。
-
-### 6.3 主切分函数 `naive_merge`（`nlp/__init__.py:562-606`）
-
-```python
-# api/app/core/rag/nlp/__init__.py:562-606（核心算法）
-def naive_merge(sections, chunk_token_num=128, delimiter="\n。；！？", overlapped_percent=0):
-    if isinstance(sections, str): sections = [sections]
-    if isinstance(sections[0], str): sections = [(s, "") for s in sections]
-    cks, tk_nums = [""], [0]
-    def add_chunk(t, pos):
-        nonlocal cks, tk_nums
-        tnum = num_tokens_from_string(t)
-        if tnum < 8: pos = ""        # 太短不挂位置
-        if cks[-1] == "" or tk_nums[-1] > chunk_token_num * (100 - overlapped_percent)/100.:
-            # 开新 chunk，按 overlapped_percent 从上一块尾部留滑窗
-            overlapped = RAGPdfParser.remove_tag(cks[-1])
-            t = overlapped[int(len(overlapped)*(100-overlapped_percent)/100.):] + t
-            if t.find(pos) < 0: t += pos
-            cks.append(t); tk_nums.append(tnum)
-        else:
-            if cks[-1].find(pos) < 0: t += pos
-            cks[-1] += t; tk_nums[-1] += tnum
-    dels = get_delimiters(delimiter)
-    for sec, pos in sections:
-        if num_tokens_from_string(sec) < chunk_token_num:
-            add_chunk("\n"+sec, pos); continue
-        for sub_sec in re.split(r"(%s)" % dels, sec, flags=re.DOTALL):
-            if re.match(f"^{dels}$", sub_sec): continue
-            add_chunk("\n"+sub_sec, pos)
-    return cks
-```
-
-要点：
-- **token 上限**：当 `tk_nums[-1] > chunk_token_num * (1 - overlapped_percent/100)` 时开新 chunk。这意味着 `overlapped_percent=0` → 严格不超；`>0` → 提前开新块以预留滑窗空间。
-- **滑动窗口**：开新 chunk 时把上一块尾部 `overlapped_percent%` 的字符（**不是 token**）拼到新块开头；用 `RAGPdfParser.remove_tag` 先剥离位置标签，避免位置 tag 漏到新块。
-- **delimiter**：默认 `"\n。；！？"`，可被 `parser_config.delimiter` 覆盖。`get_delimiters` 支持反引号包围的多字符分隔符（如 `` `\n\n` ``），并按长度降序优先匹配（避免短符号"吞掉"长符号的左边界）。`nlp/__init__.py:760-776`。
-- **位置 tag 注入**：每段 `pos` 串只在 chunk 内不存在时才追加，避免重复（PDF chunk 一段往往跨多页，位置 tag 自然多次出现）。
-- **长 section 二次拆分**：单段 token 数 ≥ chunk_token_num 才用 delimiter 切，否则整段加入。
-
-### 6.4 带图变体
-
-- **`naive_merge_docx`**（`nlp/__init__.py:706-752`）：sections 是 `[(text, image), ...]`；无图段先累积成行 line，遇到带图段才触发切分；同一 chunk 内多图用 `concat_img` 上下拼接成一张大图。**没有 overlapped_percent**。
-- **`naive_merge_with_images`**（`nlp/__init__.py:609-662`）：与 `naive_merge` 同构，但同步把每段对应的 image 累积到 `result_images` 数组（多图也走 `concat_img` 合并）。
-
-### 6.5 标题树切分（结构感知）
-
-- **`hierarchical_merge(bull, sections, depth)`**（`nlp/__init__.py:471-559`）：用 `BULLET_PATTERN[bull]`（5 套样式：第一/二/三章节系列、英文 PART/Chapter、Markdown # 系列）匹配标题，按层级建组，每组内累计 token 不超过 218 就合并到一个 chunk。是 manual.py / paper.py 等"标准化文档"app 用的策略。
-- **`tree_merge(bull, sections, depth)`**（`nlp/__init__.py:423-469`）：同样基于 BULLET_PATTERN，但建一棵 `Node` 标题树，深度优先生成 chunk，让父级标题路径自动出现在每个 chunk 头部（`title1\ntitle2\nbody`）。
-- 这两个函数 **不在 `app/naive.py` 主链路**调用——naive.py 用的是 `naive_merge` 系列；它们服务于 `app/manual.py`、`app/paper.py`、`app/laws.py`、`app/book.py` 等专业 app。
-
-### 6.6 关键词处理（`tokenize` / `tokenize_chunks` / `tokenize_table`）
-
-最终交给 ES 的不是裸文本 chunk，而是带"分词字段"的 doc：
-
-```python
-# api/app/core/rag/nlp/__init__.py:251-256
-def tokenize(d, t, eng):
-    d["content_with_weight"] = t
-    t = re.sub(r"</?(table|td|caption|tr|th)( [^<>]{0,12})?>", " ", t)
-    d["content_ltks"] = rag_tokenizer.tokenize(t)               # 粗粒度分词
-    d["content_sm_ltks"] = rag_tokenizer.fine_grained_tokenize(d["content_ltks"])  # 细粒度
-```
-
-```python
-# api/app/core/rag/nlp/__init__.py:258-277（tokenize_chunks）
-for ii, ck in enumerate(chunks):
-    d = copy.deepcopy(doc)                                  # doc 含 docnm_kwd / title_tks / title_sm_tks
-    if pdf_parser:                                          # 仅 PDF 链路
-        d["image"], poss = pdf_parser.crop(ck, need_position=True)
-        add_positions(d, poss)
-        ck = pdf_parser.remove_tag(ck)
-    else:
-        add_positions(d, [[ii]*5])                          # 无位置时填占位
-    tokenize(d, ck, eng)
-    res.append(d)
-```
-
-- `add_positions(d, poss)` 写入 `page_num_int / position_int / top_int` 三列（`int` 后缀是 ES 的 type hint）。`nlp/__init__.py:325-337`。
-- `tokenize_table(tbls, doc, eng, batch_size=10)` 每 10 行表格组装成一个 chunk，挂图（如有）时 `doc_type_kwd="image"`。`nlp/__init__.py:295-322`。
-
-### 6.7 `Chunk` Pydantic 模型（`models/chunk.py`）
-
-```python
-# api/app/core/rag/models/chunk.py
-class ChildDocumentChunk(BaseModel):
-    page_content: str
-    vector: list[float] | None = None
-    metadata: dict = Field(default_factory=dict)
-
-class DocumentChunk(BaseModel):           # 父子结构
-    page_content: str
-    vector: list[float] | None = None
-    metadata: dict = Field(default_factory=dict)
-    children: list[ChildDocumentChunk] | None = None
-
-class GeneralStructureChunk(BaseModel):
-    general_chunks: list[str]
-
-class ParentChildChunk(BaseModel):
-    parent_content: str
-    child_contents: list[str]
-
-class ParentChildStructureChunk(BaseModel):
-    parent_child_chunks: list[ParentChildChunk]
-    parent_mode: str = "paragraph"        # 父分段模式
-
-class QAChunk(BaseModel):
-    question: str
-    answer: str
-
-class QAStructureChunk(BaseModel):
-    qa_chunks: list[QAChunk]
-```
-
-> **重要：`DocumentChunk` 是上层服务（`services/`、`controllers/chunk_controller.py`）使用的"业务 schema"，与 `tokenize_chunks` 输出的 ES doc 字段不同。** ES doc 实际字段（来自 `nlp/__init__.py` 注入）：
-> - `docnm_kwd`：原文件名（keyword）
-> - `title_tks` / `title_sm_tks`：标题分词（粗 + 细）
-> - `content_with_weight`：原始 chunk 文本（用于 BM25 加权）
-> - `content_ltks` / `content_sm_ltks`：内容分词（粗 + 细）
-> - `page_num_int` / `position_int` / `top_int`：页码与坐标（用于 PDF 还原图片）
-> - `image`：PIL.Image，存为二进制
-> - `doc_type_kwd`：doc 类型（"image" / 默认空）
-> - 后续 Embedding 阶段补 `q_vec_<dim>`（向量字段，详见 [S2-T2]）。
-
-### 6.8 切分策略汇总
-
-| 策略 | 实现 | 默认参数 | 触发条件 |
-|---|---|---|---|
-| **按 Token + delimiter**（默认） | `naive_merge` | `chunk_token_num=128/512`, `delimiter="\n!?。；！？"` | docx/pdf/html/json/md/txt（主链路） |
-| **滑动窗口** | `naive_merge` 的 `overlapped_percent` | 默认 0 | `parser_config.overlapped_percent=N`（手动） |
-| **按行**（无合并） | `naive.py:678-680` | `excel_parser` 每行一段 | xlsx/csv |
-| **按段落 + 图绑定** | `naive_merge_docx` | 同 naive_merge | docx |
-| **按段落 + 多模态** | `naive_merge_with_images` | 同 naive_merge | md（含图）/ pdf VisionParser |
-| **结构化 JSON 切分** | `RAGJsonParser._json_split` | `max_chunk_size=4000 chars`, `min_chunk_size=max-200` | json/jsonl/ldjson |
-| **按 token 切分（HTML block）** | `RAGHtmlParser.chunk_block` | `chunk_token_num=512` | html |
-| **基于标题树** | `hierarchical_merge` / `tree_merge` | `depth` 参数；token 上限硬编码 218 | manual/paper/book/laws app |
-| **整段（不切）** | `tokenize_chunks` 直接喂 chunks | — | mineru/textln（内置已切好） |
-
-## 7. 关键源码片段速查
-
-| 文件 | 行号 | 内容 |
-|---|---|---|
-| `api/app/core/rag/app/naive.py` | 27-95 | `by_deepdoc` / `by_mineru` / `by_textln` / `by_plaintext` 四个 PDF 适配器 |
-| `api/app/core/rag/app/naive.py` | 97-102 | `PARSERS` 注册表 |
-| `api/app/core/rag/app/naive.py` | 369-412 | `class Pdf(PdfParser)`：OCR→layout→TSR→merge 编排 |
-| `api/app/core/rag/app/naive.py` | 508-811 | `def chunk(...)`：所有格式的总入口 |
-| `api/app/core/rag/nlp/__init__.py` | 562-606 | `naive_merge`（主切分） |
-| `api/app/core/rag/nlp/__init__.py` | 706-752 | `naive_merge_docx`（图绑定） |
-| `api/app/core/rag/nlp/__init__.py` | 251-256 | `tokenize`（生成分词字段） |
-| `api/app/core/rag/nlp/__init__.py` | 258-277 | `tokenize_chunks`（PDF 裁图 + 位置） |
-| `api/app/core/rag/nlp/__init__.py` | 295-322 | `tokenize_table`（表格 batch=10） |
-| `api/app/core/rag/nlp/__init__.py` | 152-184 | `BULLET_PATTERN`（5 套标题样式） |
-| `api/app/core/rag/common/token_utils.py` | 6-18 | `tiktoken.cl100k_base` + `num_tokens_from_string` |
-| `api/app/core/rag/crawler/web_crawler.py` | 81-183 | `WebCrawler.crawl()` 主循环 |
-| `api/app/core/rag/crawler/http_fetcher.py` | 42-180 | `HTTPFetcher.fetch` 重试/退避/4xx/5xx 处理 |
-| `api/app/core/rag/integrations/feishu/client.py` | 68-127 | tenant_access_token + TTLCache + asyncio.Lock |
-| `api/app/core/rag/integrations/feishu/client.py` | 311-406 | `_export_file` 三步轮询导出 |
-| `api/app/core/rag/integrations/yuque/client.py` | 234-291 | `get_doc_detail(raw=1)` |
-| `api/app/core/rag/integrations/yuque/client.py` | 364-455 | `lakesheet → xlsx` 重建 |
-| `api/app/core/rag/utils/libre_office.py` | 11-57 | `convert_to_pdf` 软件路径 + 120s 超时 |
-| `api/app/core/rag/utils/file_utils.py` | 69-130 | `extract_embed_file`（zip/OLE 双路径） |
-| `api/app/core/rag/deepdoc/parser/pdf_parser.py` | 1006-1122 | `__images__` OCR 主入口（trio 并发） |
-| `api/app/core/rag/deepdoc/parser/pdf_parser.py` | 1219-1229 | `remove_tag` / `extract_positions` |
-| `api/app/core/rag/deepdoc/parser/pdf_parser.py` | 1300-1331 | `PlainParser`（pypdf 兜底） |
-| `api/app/core/rag/deepdoc/parser/pdf_parser.py` | 1334-1383 | `VisionParser`（多模态 LLM 整页） |
-| `api/app/core/rag/deepdoc/parser/excel_parser.py` | 18-53 | `_load_excel_to_workbook`（openpyxl/pandas/calamine 三级回退） |
-| `api/app/core/rag/deepdoc/parser/json_parser.py` | 46-95 | `_json_split` 结构感知切分 |
-| `api/app/core/rag/deepdoc/parser/figure_parser.py` | 52-118 | `VisionFigureParser`（10 并发 LLM 描述图） |
-| `api/app/core/rag/deepdoc/vision/layout_recognizer.py` | 147-160 | YOLOv10 10 类 label |
-
-## 8. 配置项与可调参数
-
-### 8.1 `parser_config`（`naive.py:521` 默认值，业务侧可覆盖）
-
-| 参数 | 默认 | 含义 | 影响 |
-|---|---|---|---|
-| `layout_recognize` | `"DeepDOC"` | PDF 引擎选择 | DeepDOC/Plain Text/MinerU/TextLn |
-| `chunk_token_num` | `512`（PDF 默认）/ `128`（其他默认） | 单 chunk 最大 token | 直接影响召回粒度与上下文密度 |
-| `delimiter` | `"\n!?。；！？"` | 切分分隔符（支持反引号多字符） | 细化语义边界 |
-| `analyze_hyperlink` | `True` | 是否递归抓 docx/pdf 内超链接 | 显著拉长解析时间 |
-| `html4excel` | `"false"` | Excel 是否走 HTML 表格输出 | 表格检索友好度 vs token 浪费 |
-| `auto_keywords` | `0` | 自动关键词提取数 | 下游 prompt 注入 |
-| `auto_questions` | `0` | 自动问题提取数 | QA-RAG |
-| `overlapped_percent` | `0` | 滑窗重叠百分比 | 召回连续性 vs 冗余 |
-
-### 8.2 环境变量
-
-| 变量 | 默认 | 用途 |
-|---|---|---|
-| `LAYOUT_RECOGNIZER_TYPE` | `onnx` | `onnx` / `ascend` 切换 NPU |
-| `HF_ENDPOINT` | — | `https://hf-mirror.com` 加速国内 HF 拉取 |
-| `MINERU_EXECUTABLE` | `mineru` | MinerU CLI 路径 |
-| `MINERU_APISERVER` | `http://host.docker.internal:9987` | MinerU HTTP API |
-| `MINERU_BACKEND` | `pipeline` | `pipeline` / `vlm-http-client` / `vlm-transformers` / `vlm-vllm-engine` |
-| `MINERU_DELETE_OUTPUT` | `1` | 是否清理临时输出 |
-| `TEXTLN_APISERVER` | `https://api.textin.com/...` | TextIn 云端 |
-| `TEXTLN_APP_ID/SECRET_CODE` | — | TextIn 鉴权 |
-| `TIKA_SERVER_JAR` | `/tmp/tika-server.jar` | Apache Tika jar 路径 |
-| `TIKA_SERVER_PORT` | `9998` | Tika JVM 端口 |
-
-### 8.3 调用入参（`chunk()` 形参）
-
-| 参数 | 含义 |
-|---|---|
-| `filename` / `binary` | 文件路径或二进制内容（推荐 binary，path 模式不支持嵌入抽取） |
-| `from_page` / `to_page` | PDF 分页范围（节省内存） |
-| `lang` | `"Chinese"` / `"english"`（影响 `is_english` 与表格分隔符） |
-| `vision_model` | 多模态 LLM 实例（图片描述、VisionParser、音视频）|
-| `pdf_cls` | 自定义 PDF 类，继承 `Pdf`（可重写 OCR/layout 钩子） |
-| `is_root` | 内部递归标志，外部勿设 |
-| `section_only` | 仅返回切分文本，不做 ES doc 包装（用于增量调试） |
-
-## 9. 边界条件与已知限制
-
-1. **PPT/DOC 强依赖外部组件**：LibreOffice 与 Apache Tika 任一缺失都会让对应格式直接 500，**没有内建兜底**。建议生产容器固化版本。
-2. **`extract_embed_file` 不支持 path 模式**：仅接受 `bytes`，root 调用必须传 `binary` 否则抛 `Exception`（`naive.py:541`）。
-3. **HF 模型懒加载**：首次启动会从 HuggingFace 拉 `text_concat_xgb_v1.0` 与 OCR/layout/TSR 模型（共数百 MB），冷启动慢；建议 image build 阶段预热。
-4. **同进程 PDF 锁**：`LOCK_KEY_pdfplumber` 全局 lock 串行化 `pdfplumber.open()`，**单进程内 PDF 解析无法真并发**；需要并发则起多进程或多容器。
-5. **`naive_merge` 滑窗按字符不按 token**：`overlapped_percent=20` 实际重叠是上一块字符串末尾 20% 字符，token 数会有偏差（中文字符占 1-3 token 不等）。
-6. **图片 chunk 无 `position_int`**：`tokenize_chunks_with_images` 只填了 `[ii]*5`（占位），不能像 PDF chunk 那样在原图上还原坐标。
-7. **`naive_merge_docx` 没有 `overlapped_percent`**：docx 链路无重叠窗口（实现上漏掉了），如需重叠暂时只能改代码或者把 docx → markdown 再走 markdown 链路。
-8. **JSONL 检测启发式**：`is_jsonl_format` 只看前 10 行 80% 阈值，对"前几行恰好都是合法单行 JSON 但整体也是合法 JSON 数组"的边界情况会误判。
-9. **Crawler 不支持 SPA**：`is_static_content` 直接拒绝 `<200 chars body + >5 scripts` 的页面，没有 Playwright/Puppeteer 渲染兜底。
-10. **飞书在线文档导出超时**：`_export_file` 写死 `max_retries=10, poll_interval=2s`（即 20s 上限），大文档可能超时 → `FeishuAPIError("Export task did not complete...")`。
-
-## 10. 监控指标与排错指引
-
-### 10.1 关键日志锚点（按 timer 输出）
-
-- `__images__ dedupe_chars cost {t}s`（PDF 字符抽取）
-- `__images__ {N} pages cost {t}s`（OCR 总耗时）
-- `naive_merge({filename}): {t}`（chunking 耗时）
-- `OCR finished` / `Layout analysis` / `Table analysis` / `Text merged`（callback 进度）
-
-### 10.2 常见 Bug & 定位
-
-| 现象 | 可能原因 | 定位 |
-|---|---|---|
-| 中文 chunk 出现乱码 | 文件编码非 UTF-8 但 `find_codec` 误判 | 在 `find_codec` 入口打日志看 `chardet.detect` 返回 |
-| Excel 单元格丢失 | `ILLEGAL_CHARACTERS_RE` 把控制字符替换成空格 | `_clean_dataframe` 是不是把业务字符当成非法字符了 |
-| PDF 图被截到一半 | `crop()` 计算 bottom 时跨页页高累积出错 | `pdf_parser.py:1245-1260` 检查 `page_cum_height` |
-| 飞书 token 频繁刷新 | `TTLCache(ttl=7200-300)` 只缓存 1 token，多并发实例每个进程独立缓存 | 接 Redis 共享缓存 |
-| MinerU 报"not found" | `MINERU_EXECUTABLE` PATH 不对 | `mineru_parser.py:check_installation` 打 trace |
-| chunk 数远超预期 | `chunk_token_num` 太小 + delimiter 过细 | 看 `naive_merge` 入口的两个参数 |
-| 解析卡死无反应 | LibreOffice 转换卡 / Tika JVM 挂 | 检查 `convert_to_pdf` 的 120s timeout 是否触发 |
-| HF 模型拉取失败 | 国内网络 | `export HF_ENDPOINT=https://hf-mirror.com` |
-
-## 11. 优化建议与未来扩展点
-
-### 11.1 架构改造建议（即刻收益）
-
-1. **Loader 抽象层**：把 `WebCrawler` / `FeishuAPIClient` / `YuqueAPIClient` 统一收敛为 `BaseLoader.load() -> Iterable[LoadedDocument]` 接口，下游统一消费 `LoadedDocument(filename, binary, source_metadata)`。这样 confluence/Notion/SharePoint 接入只需新写一个 Loader，不用改 `naive.py`。
-2. **Parser 注册表外露**：`PARSERS = {...}` 当前只覆盖 PDF；建议扩到 `FORMAT_PARSERS = {".docx": Docx, ".xlsx": ExcelParser, ...}`，把 `chunk()` 里的大 if-elif 链替换成 dict 查表 + 插件机制。新格式（如 epub/odt）通过 `register_parser(".epub", EpubParser)` 注入。
-3. **Chunking 策略策略化**：把 `naive_merge / naive_merge_docx / naive_merge_with_images / hierarchical_merge / tree_merge` 实现 `BaseChunker` 接口（`chunk(sections) -> List[Chunk]`），由 `parser_config.chunking_strategy` 选择。当前 docx 缺 `overlapped_percent` 这种"碎片化丢失"会自然消失。
-4. **Token 切分而非字符切分**：`naive_merge` 的滑窗用 `encoder.encode(text)[-N:]` 反解 token-level overlap，避免中文字符≠token 的口径错配。
-5. **共享 token 缓存**：飞书/语雀 token 改为 Redis 共享，目前每实例一份的 TTLCache 在 K8s 多副本下会触发限流。
-6. **嵌入文件深度限制**：`extract_embed_file` 是"only first layer"，但调用方递归 `chunk(...is_root=False)` 没有 depth guard，恶意文件可造成栈深递归 → 加 `max_depth=3`。
-7. **PDF 解析进程化**：`pdfplumber` 全局锁实质单线程，对 PDF 重负载场景把 `Pdf` 包成独立 worker（multiprocessing 或 ProcessPoolExecutor），让 OCR/layout 跨核并行。
-
-### 11.2 功能扩展方向
-
-1. **多模态深整合**：现在 `VisionParser` / `picture_vision_llm_chunk` / `VisionFigureParser` 都是"图 → 描述文本 → 文本 chunk"的有损转换；可以保留 image embedding 与 text embedding 并存，下游做多模态混合检索（CLIP/SigLIP 与文本向量并列召回）。
-2. **语义切分（Semantic Chunking）**：按嵌入相似度（如 `cosine(emb_i, emb_{i+1}) < 0.7` 作为切点）替代固定 token 切分，实验证明可显著提升长文档召回。`naive_merge` 已经有插槽，加一个 `chunking_strategy="semantic"` 即可。
-3. **结构化字段抽取**：现在表格只做行→自然语言转换（"列名：值"），没有把表格存成结构化 JSON。可在 `tokenize_table` 旁路输出 `table_data: dict`，配合 [S2-T3] 的混合搜索，用关键词字段精确过滤。
-4. **缓存命中**：相同文件的解析结果（按 sha256 + parser_config hash）应进缓存，重新入库时跳过 OCR；`extract_embed_file` 已有 `_sha10` 雏形，可扩为完整 cache key。
-5. **流式 chunk 输出**：当前 `chunk()` 返回 `List`，大文件全量加载到内存；改为 `Iterable[Chunk]` + 生产者-消费者，可以让 Embedding 与 OCR 并行流水线。
-6. **更细粒度的进度上报**：`callback(prog, msg)` 现在是粗粒度（0.1/0.6/0.8…），生产中需要展示"第几页/共多少页"，建议结构化为 `callback({stage, current, total, msg})`。
-7. **Crawler 增量化**：当前每次全量 crawl，没有 ETag/If-Modified-Since 机制；接 `last_crawl_timestamp` 让二次抓取只拉变化页。
-
-### 11.3 与下游约定（输出契约）
-
-本文档负责输出的 chunk 序列应包含至少：
-
-```python
-{
-    "docnm_kwd": str,                 # 文件名
-    "title_tks": str,                 # 文档标题分词（粗）
-    "title_sm_tks": str,              # 文档标题分词（细）
-    "content_with_weight": str,       # 原始 chunk 文本（必填）
-    "content_ltks": str,              # 内容分词（粗）
-    "content_sm_ltks": str,           # 内容分词（细）
-    "page_num_int": list[int],        # 页码（PDF 才有意义）
-    "position_int": list[tuple],      # (page, x0, x1, top, bottom)
-    "top_int": list[int],             # 行顶 y 坐标
-    "image": Optional[PIL.Image],     # PDF/Excel 才有
-    "doc_type_kwd": Optional[str],    # "image" 或空
-}
-```
-
-[S2-T3] 索引结构应消费上述字段（参考 vdb/elasticsearch/elasticsearch_vector.py 的 mapping）。[S2-T2] Embedding 应在此基础上补 `q_<dim>_vec` 列。[S2-T6] 端到端调用链路从 `app/naive.py:chunk()` 开始追踪。
-
----
-
-**自检清单（对照 [S1-T1] 评分卡，预估 ≥ 80）**
-
-- ✅ 准确性：所有源码引用经 grep 与 line read 验证，路径/函数名/行号 ±3 行内
-- ✅ 完整性：覆盖 Loader（4 种）/ Parser（11 种格式）/ Chunking（8 种策略）/ Chunk 模型 / 配置项 / 限制 / 排错
-- ✅ 时效性：基于 origin/main HEAD（2026-05-08）
-- ✅ 可读性：分层目录、表格、Mermaid 图、源码片段交叉
-- ✅ 可执行性：环境变量、参数默认值、外部依赖列出可直接落地

docs/rag/pipeline/02-embedding.md

@@ -1,608 +0,0 @@
-# [S2-T2] Embedding 模型选择与向量生成实现详解
-
----
-
-## 一句话定位
-
-MemoryBear 的 Embedding 层负责将文本 Chunk 转化为稠密向量，是连接"非结构化文本"与"向量数据库"的核心桥梁。当前系统同时存在两条 Embedding 调用路径：**基于 LangChain 的统一封装层（RedBearEmbeddings，面向 ES 向量库）** 与 **遗留的原始实现层（embedding_model.py，面向 GraphRAG 与 Dealer 检索）**。
-
----
-
-## 设计目标与适用场景
-
-- **多提供商兼容**：覆盖 OpenAI、Azure、DashScope（通义千问）、Volcano（火山引擎）、Xinference、GPUStack、Ollama、Bedrock 等主流 Embedding 服务
-- **多模态扩展**：火山引擎支持文本/图片/视频多模态 Embedding
-- **知识库隔离**：每个知识库独立配置 Embedding 模型，通过 `knowledge.embedding_id` 关联
-- **GraphRAG 支撑**：为实体/关系节点生成向量，用于图检索中的语义匹配
-
----
-
-## 关键概念与术语表
-
-| 术语 | 含义 |
-|------|------|
-| `RedBearEmbeddings` | LangChain 统一封装类，面向 ES 向量库的主入口 |
-| `OpenAIEmbed` | 遗留原始实现，面向 GraphRAG 与 Dealer 检索 |
-| `ModelApiKey` | 数据库表，存储模型的 API Key、base_url、provider |
-| `ModelConfig` | 数据库表，存储模型的配置参数（capability、timeout、max_retries 等） |
-| `EMBEDDING_BATCH_SIZE` | 环境变量，控制向量化批处理大小 |
-| `chat_limiter` | Trio 并发限流器，控制 GraphRAG 中 Embedding 并发数 |
-| `get_embed_cache` | Redis 缓存函数，缓存 GraphRAG 中的实体/关系向量 |
-
----
-
-## 实现概览
-
-### 架构分层
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    调用方（检索 / 入库）                       │
-│  ElasticSearchVector   Dealer.search   GraphRAG             │
-├─────────────────────────────────────────────────────────────┤
-│                    Embedding 封装层                          │
-│  RedBearEmbeddings（新）  │  embedding_model.py（遗留）      │
-├─────────────────────────────────────────────────────────────┤
-│                    底层 SDK / API                            │
-│  langchain_openai  dashscope  volcenginesdkarkruntime  ...  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 数据流：Chunk → Vector
-
-```
-DocumentChunk(page_content="...", metadata={...})
-        │
-        ▼
-ElasticSearchVector.add_chunks(chunks)           [elasticsearch_vector.py:55]
-        │
-        ├─► 火山引擎多模态: self.embeddings.embed_batch(texts)
-        └─► 其他 provider: self.embeddings.embed_documents(list(texts))
-                    │
-                    ▼
-        RedBearEmbeddings.embed_documents(texts) [models/embedding.py:65]
-                    │
-                    ▼
-        OpenAIEmbeddings.embed_documents(texts)  [LangChain 内部]
-                    │
-                    ▼
-        HTTP API Call (OpenAI-compatible / provider-specific)
-                    │
-                    ▼
-        List[List[float]] → ES dense_vector field
-```
-
----
-
-## 1. 模型选择策略
-
-### 1.1 遗留层支持的模型（embedding_model.py）
-
-| 类名 | _FACTORY_NAME | 默认模型 | 上下文长度 | 截断策略 | batch_size | 备注 |
-|------|--------------|---------|-----------|---------|-----------|------|
-| `OpenAIEmbed` | OpenAI | text-embedding-ada-002 | 8000 tokens | `truncate(t, 8000)` | 16 | OpenAI 官方 API |
-| `AzureEmbed` | Azure-OpenAI | 继承 OpenAI | 8000 tokens | 同上 | 16 | Azure OpenAI Service |
-| `BaiChuanEmbed` | BaiChuan | Baichuan-Text-Embedding | 8000 tokens | 同上 | 16 | 百川智能 |
-| `QWenEmbed` | Tongyi-Qianwen | text_embedding_v2 | 2048 tokens | `truncate(t, 2048)` | 4 | 阿里 DashScope，自带 5 次重试 |
-| `XinferenceEmbed` | Xinference | 用户指定 | 8000 tokens | 同上 | 16 | Xinference 本地部署 |
-| `NvidiaEmbed` | NVIDIA | 用户指定 | 不截断（API 端截断） | 无 | 16 | NVIDIA API，含特殊模型路由 |
-| `HuggingFaceEmbed` | HuggingFace | 用户指定 | 不截断 | 无 | 无（全量发送） | 本地 TEI 服务 |
-| `VolcEngineEmbed` | VolcEngine | 用户指定 | 8000 tokens | 同上 | 16 | 火山引擎 Ark |
-| `GPUStackEmbed` | GPUStack | 用户指定 | 8000 tokens | 同上 | 16 | GPUStack 本地部署 |
-| `LocalAIEmbed` | LocalAI | 用户指定 | 8000 tokens | 同上 | 16 | LocalAI / LMStudio |
-
-### 1.2 统一封装层支持的模型（RedBearEmbeddings）
-
-| Provider | 对应的 LangChain 类 | 默认超时 | 默认重试 | 多模态支持 |
-|----------|-------------------|---------|---------|-----------|
-| `openai` | `langchain_openai.OpenAIEmbeddings` | 120s | 2 次 | 否 |
-| `xinference` | `langchain_openai.OpenAIEmbeddings` | 120s | 2 次 | 否 |
-| `gpustack` | `langchain_openai.OpenAIEmbeddings` | 120s | 2 次 | 否 |
-| `dashscope` | `langchain_community.DashScopeEmbeddings` | 120s | 2 次 | 否 |
-| `ollama` | `langchain_ollama.OllamaEmbeddings` | 120s | 2 次 | 否 |
-| `bedrock` | `langchain_aws.BedrockEmbeddings` | 120s | 2 次 | 否 |
-| `volcano` | `volcenginesdkarkruntime.Ark` (原生 SDK) | 120s | 2 次 | **是**（文本/图片/视频） |
-
-### 1.3 默认模型
-
-- **知识库默认 Embedding**：通过 `workspace.embedding` 继承，或管理员在创建知识库时手动指定 `embedding_id`
-- **数据库关联**：`knowledge.embedding_id` → `model_configs.id`（ModelConfig 表）→ `model_api_keys`（API Key 表）
-- **无默认模型硬编码**：系统不内置默认模型名称，完全依赖数据库配置
-
-### 1.4 切换方式
-
-1. **管理后台配置**：在模型管理页面添加新的 Embedding 模型配置（provider + model_name + api_key + base_url）
-2. **知识库绑定**：创建/编辑知识库时选择新的 `embedding_id`
-3. **即时生效**：新写入的 Chunk 使用新模型；历史 Chunk 向量保持不变（见"维度变更兼容"章节）
-
----
-
-## 2. 调用链路详解
-
-### 2.1 入库链路（Chunk → ES Vector）
-
-```
-memory_konwledges_server.py:430
-    vector_service.add_chunks([chunk])
-        │
-        ▼
-elasticsearch_vector.py:55-63
-    def add_chunks(self, chunks: list[DocumentChunk], **kwargs):
-        texts = [chunk.page_content for chunk in chunks]
-        if self.is_multimodal_embedding:
-            embeddings = self.embeddings.embed_batch(texts)      # 火山引擎
-        else:
-            embeddings = self.embeddings.embed_documents(list(texts))  # 其他
-        self.create(chunks, embeddings, **kwargs)
-        │
-        ▼
-models/embedding.py:65-78
-    def embed_documents(self, texts: list[str]) -> list[list[float]]:
-        if self._is_volcano:
-            # 多模态 Embedding
-            contents = [{"type": "text", "text": text} for text in texts]
-            response = self._client.multimodal_embeddings.create(...)
-            return [response.data.embedding]
-        else:
-            return self._model.embed_documents(texts)  # LangChain 标准接口
-```
-
-### 2.2 检索链路（Query → Vector → ES Search）
-
-```
-elasticsearch_vector.py:374-380
-    def search_by_vector(self, query: str, **kwargs: Any) -> list[DocumentChunk]:
-        if self.is_multimodal_embedding:
-            query_vector = self.embeddings.embed_text(query)     # 火山引擎
-        else:
-            query_vector = self.embeddings.embed_query(query)    # 其他
-        # ES script_score: cosineSimilarity(params.query_vector, 'vector') + 1.0
-```
-
-### 2.3 GraphRAG 链路（Entity/Relation → Vector）
-
-```
-graphrag/utils.py:301-327
-    async def graph_node_to_chunk(kb_id, embd_mdl, ent_name, meta, chunks):
-        ebd = get_embed_cache(embd_mdl.model_name, ent_name)
-        if ebd is None:
-            async with chat_limiter:                              # 并发限流
-                with trio.fail_after(...):
-                    ebd, _ = await trio.to_thread.run_sync(
-                        lambda: embd_mdl.encode([ent_name]))      # 遗留 OpenAIEmbed
-            ebd = ebd[0]
-            set_embed_cache(embd_mdl.model_name, ent_name, ebd)  # Redis 缓存
-        chunk["q_%d_vec" % len(ebd)] = ebd
-```
-
-### 2.4 Dealer 检索链路（加权融合检索）
-
-```
-nlp/search.py:365-373
-    def get_vector(self, txt, emb_mdl, topk=10, similarity=0.1):
-        qv, _ = emb_mdl.encode_queries(txt)                      # 遗留 OpenAIEmbed
-        embedding_data = [get_float(v) for v in qv]
-        vector_column_name = f"q_{len(embedding_data)}_vec"
-        return MatchDenseExpr(vector_column_name, embedding_data, ...)
-```
-
-### 2.5 同步/异步说明
-
-| 场景 | 模式 | 说明 |
-|------|------|------|
-| ES 向量入库 | **同步** | `embed_documents()` 为同步调用，在请求线程中执行 |
-| ES 向量检索 | **同步** | `embed_query()` 为同步调用 |
-| GraphRAG 实体嵌入 | **异步** | `trio.to_thread.run_sync()` 将同步 Embedding 调用放入线程池 |
-| 模型验证 | **异步** | `asyncio.to_thread()` 包装同步调用 |
-
-### 2.6 批量大小与并发控制
-
-| 控制点 | 数值 | 位置 |
-|--------|------|------|
-| OpenAI 兼容类 batch_size | 16 | `embedding_model.py:52`, `:83`, `:178` |
-| QWen batch_size | 4 | `embedding_model.py:133` |
-| HuggingFace | 无批量（全量发送） | `embedding_model.py:258` |
-| GraphRAG 并发限流 | `MAX_CONCURRENT_CHATS`（默认 10） | `graphrag/utils.py:41` |
-| RedBearModelConfig 并发 | 5（配置项，当前未在 Embedding 中使用） | `models/base.py:37` |
-
----
-
-## 3. 生产级关注点
-
-### 3.1 限流与配额管理
-
-**现状分析：**
-
-- **无显式 API 速率限制**：代码中未发现针对 Embedding API 的 RPM/TPM 限流逻辑
-- **LangChain 内部限流**：`OpenAIEmbeddings` 内部有基础请求间隔控制，但不可配置
-- **并发控制仅存在于 GraphRAG**：`chat_limiter = trio.CapacityLimiter(10)` 限制 GraphRAG 中实体/关系嵌入的并发数
-
-**源码引用：**
-
-```python
-# graphrag/utils.py:41
-chat_limiter = trio.CapacityLimiter(int(os.environ.get("MAX_CONCURRENT_CHATS", 10)))
-
-# graphrag/utils.py:320-322
-async with chat_limiter:
-    with trio.fail_after(3 if enable_timeout_assertion else 30000000):
-        ebd, _ = await trio.to_thread.run_sync(lambda: embd_mdl.encode([ent_name]))
-```
-
-### 3.2 失败重试与降级
-
-**现状分析：**
-
-| 路径 | 重试机制 | 降级策略 |
-|------|---------|---------|
-| QWenEmbed（遗留） | 显式 5 次重试，间隔 10s | 抛出异常，无降级 |
-| RedBearEmbeddings（统一层） | `max_retries`（默认 2，由 LangChain SDK 内部实现） | 抛出异常，无降级 |
-| ES 连接 | `retry_on_timeout=True`, `max_retries=3` | 抛出 ConnectionError |
-| 知识检索 | 单库失败不影响其他库 | `continue` 跳过 |
-
-**源码引用：**
-
-```python
-# embedding_model.py:138-143（QWen 显式重试）
-retry_max = 5
-resp = dashscope.TextEmbedding.call(...)
-while (resp["output"] is None ...) and retry_max > 0:
-    time.sleep(10)
-    resp = dashscope.TextEmbedding.call(...)
-    retry_max -= 1
-
-# models/base.py:34-36（统一层重试配置）
-timeout: float = Field(default_factory=lambda: float(os.getenv("LLM_TIMEOUT", "120.0")))
-max_retries: int = Field(default_factory=lambda: int(os.getenv("LLM_MAX_RETRIES", "2")))
-```
-
-**⚠️ 关键缺口：无备用模型降级机制。** 当主 Embedding 模型服务不可用时，系统会直接失败，不会自动切换备用模型。
-
-### 3.3 缓存策略
-
-**现状分析：**
-
-- **GraphRAG 实体/关系缓存**：Redis 缓存，TTL 24 小时，key 为 `xxhash(model_name + text)`
-- **ES 向量入库/检索**：**无缓存**，每次调用都实时请求 Embedding API
-- **无全局 Embedding 缓存层**
-
-**源码引用：**
-
-```python
-# graphrag/utils.py:115-134
-redis_client = redis.StrictRedis(**redis_conn_params)
-
-def get_embed_cache(llmnm, txt):
-    hasher = xxhash.xxh64()
-    hasher.update(str(llmnm).encode("utf-8"))
-    hasher.update(str(txt).encode("utf-8"))
-    k = hasher.hexdigest()
-    bin = redis_client.get(k)
-    if not bin:
-        return
-    return np.array(json.loads(bin))
-
-def set_embed_cache(llmnm, txt, arr):
-    # ... 设置 Redis，TTL = 24 * 3600
-```
-
-**影响评估：**
-- 重复文本（如相同实体名）在 GraphRAG 中可命中缓存，节省 API 调用
-- 常规知识库检索/入库中，相同 Chunk 或 Query 重复向量化，造成冗余 API 开销
-
-### 3.4 维度变更对历史向量的兼容
-
-**现状分析：**
-
-- **无自动兼容机制**：更换 Embedding 模型后，历史 Chunk 的向量维度不变，新 Chunk 使用新维度
-- **ES Mapping 冲突**：`create_collection()` 在创建索引时根据第一条向量的长度设置 `dense_vector.dims`，若后续向量维度不同会写入失败
-- **混合维度风险**：同一索引中既有 1536 维又有 768 维的向量，ES `dense_vector` 字段要求固定维度
-
-**源码引用：**
-
-```python
-# elasticsearch_vector.py:653-658
-Field.VECTOR.value: {
-    "type": "dense_vector",
-    "dims": len(embeddings[0]),  # 根据第一条向量动态决定
-    "index": True,
-    "similarity": "cosine"
-}
-```
-
-**推荐操作（如何安全替换 Embedding 模型）：**
-
-1. **创建新知识库**：为新知识库配置新的 Embedding 模型，避免影响已有数据
-2. **重建索引（谨慎）**：如需迁移历史数据，需：
-   - 删除旧 ES 索引（`Vector_index_{knowledge_id}_Node`）
-   - 重新解析所有文档（触发新的 Embedding 调用）
-   - 确认所有 Chunk 使用同一模型生成向量
-3. **版本标记**：建议在知识库 metadata 中记录当前使用的 Embedding 模型版本，便于追踪
-
-**影响面分析：**
-
-| 操作 | 影响范围 | 风险等级 |
-|------|---------|---------|
-| 修改知识库 embedding_id | 仅新入库 Chunk | 低 |
-| 修改已有知识库 embedding_id + 不重建索引 | 检索时 Query 向量与 Chunk 向量维度不匹配 | **高** |
-| 重建索引 | 全量重新 Embedding，API 费用 + 时间成本 | 中 |
-
----
-
-## 4. 配置项汇总
-
-### 4.1 环境变量
-
-| 变量名 | 默认值 | 说明 | 影响范围 |
-|--------|--------|------|---------|
-| `LLM_TIMEOUT` | 120.0 | Embedding HTTP 请求超时（秒） | RedBearEmbeddings 统一层 |
-| `LLM_MAX_RETRIES` | 2 | Embedding 请求最大重试次数 | RedBearEmbeddings 统一层 |
-| `MAX_CONCURRENT_CHATS` | 10 | GraphRAG Embedding 并发限流 | graphrag/utils.py |
-| `ELASTICSEARCH_HOST` | 127.0.0.1 | ES 主机地址 | ES 向量存储 |
-| `ELASTICSEARCH_PORT` | 9200 | ES 端口 | ES 向量存储 |
-| `ELASTICSEARCH_REQUEST_TIMEOUT` | 100000 | ES 请求超时 | ES 连接 |
-| `ELASTICSEARCH_MAX_RETRIES` | 10 | ES 连接重试 | ES 连接 |
-| `EMBEDDING_BATCH_SIZE` | （注释掉，未使用） | 预留环境变量 | — |
-
-### 4.2 数据库配置（model_configs / model_api_keys 表）
-
-| 字段 | 类型 | 说明 | 推荐值 |
-|------|------|------|--------|
-| `provider` | String | 提供商标识 | `openai` / `dashscope` / `volcano` / `xinference` |
-| `model_name` | String | 模型实际名称 | `text-embedding-3-small` / `text-embedding-v3` |
-| `api_key` | String | API 密钥 | — |
-| `api_base` | String | 基础 URL | `https://api.openai.com/v1` |
-| `timeout` | Float | 请求超时 | 120.0（复杂文档可适当延长） |
-| `max_retries` | Int | 最大重试 | 2（生产环境建议 3-5） |
-| `capability` | Array | 模型能力列表 | `[]`（Embedding 模型通常无需特殊能力） |
-
-### 4.3 调用入参（运行时）
-
-| 参数 | 位置 | 默认值 | 说明 |
-|------|------|--------|------|
-| `top_k` | `search_by_vector()` | 1024 | 向量检索返回数量 |
-| `score_threshold` | `search_by_vector()` | 0.3 | 相似度阈值（归一化后 [0,1]） |
-| `similarity_threshold` | `knowledge_retrieval()` | 0.2 | 全文检索阈值 |
-| `vector_similarity_weight` | `knowledge_retrieval()` | 0.3 | 混合检索中向量权重 |
-
----
-
-## 5. 关键源码片段
-
-### 5.1 Embedding 模型基类与统一接口
-
-```python
-# api/app/core/rag/llm/embedding_model.py:14-38
-class Base(ABC):
-    def __init__(self, key, model_name, **kwargs):
-        pass
-
-    def encode(self, texts: list):
-        raise NotImplementedError("Please implement encode method!")
-
-    def encode_queries(self, text: str):
-        raise NotImplementedError("Please implement encode method!")
-```
-
-### 5.2 OpenAI 兼容 Embedding 实现（批量处理）
-
-```python
-# api/app/core/rag/llm/embedding_model.py:50-65
-class OpenAIEmbed(Base):
-    def encode(self, texts: list):
-        batch_size = 16
-        texts = [truncate(t, 8000) for t in texts]  # 安全截断
-        ress = []
-        total_tokens = 0
-        for i in range(0, len(texts), batch_size):
-            res = self.client.embeddings.create(
-                input=texts[i : i + batch_size],
-                model=self.model_name,
-                encoding_format="float",
-                extra_body={"drop_params": True}
-            )
-            ress.extend([d.embedding for d in res.data])
-            total_tokens += self.total_token_count(res)
-        return np.array(ress), total_tokens
-```
-
-### 5.3 统一封装层（RedBearEmbeddings）
-
-```python
-# api/app/core/models/embedding.py:9-23
-class RedBearEmbeddings(Embeddings):
-    def __init__(self, config: RedBearModelConfig):
-        self._config = config
-        self._is_volcano = config.provider.lower() == ModelProvider.VOLCANO
-        if self._is_volcano:
-            self._client = self._create_volcano_client(config)
-            self._model = None
-        else:
-            self._model = self._create_model(config)
-            self._client = None
-
-# api/app/core/models/embedding.py:65-78
-    def embed_documents(self, texts: list[str]) -> list[list[float]]:
-        if self._is_volcano:
-            contents = [{"type": "text", "text": text} for text in texts]
-            response = self._client.multimodal_embeddings.create(
-                model=self._config.model_name,
-                input=contents,
-                encoding_format="float"
-            )
-            return [response.data.embedding]
-        else:
-            return self._model.embed_documents(texts)
-```
-
-### 5.4 ES 向量写入与 Mapping 创建
-
-```python
-# api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:55-63
-    def add_chunks(self, chunks: list[DocumentChunk], **kwargs):
-        texts = [chunk.page_content for chunk in chunks]
-        if self.is_multimodal_embedding:
-            embeddings = self.embeddings.embed_batch(texts)
-        else:
-            embeddings = self.embeddings.embed_documents(list(texts))
-        self.create(chunks, embeddings, **kwargs)
-
-# api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:653-658
-                        Field.VECTOR.value: {
-                            "type": "dense_vector",
-                            "dims": len(embeddings[0]),
-                            "index": True,
-                            "similarity": "cosine"
-                        }
-```
-
-### 5.5 检索端向量生成
-
-```python
-# api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:374-380
-    def search_by_vector(self, query: str, **kwargs: Any) -> list[DocumentChunk]:
-        if self.is_multimodal_embedding:
-            query_vector = self.embeddings.embed_text(query)
-        else:
-            query_vector = self.embeddings.embed_query(query)
-        # cosineSimilarity(params.query_vector, 'vector') + 1.0
-```
-
-### 5.6 GraphRAG 中的 Embedding 缓存
-
-```python
-# api/app/core/rag/graphrag/utils.py:115-134
-redis_client = redis.StrictRedis(**redis_conn_params)
-
-def get_embed_cache(llmnm, txt):
-    hasher = xxhash.xxh64()
-    hasher.update(str(llmnm).encode("utf-8"))
-    hasher.update(str(txt).encode("utf-8"))
-    k = hasher.hexdigest()
-    bin = redis_client.get(k)
-    if not bin:
-        return
-    return np.array(json.loads(bin))
-
-def set_embed_cache(llmnm, txt, arr):
-    # ... TTL = 24 * 3600
-```
-
-### 5.7 模型配置基类
-
-```python
-# api/app/core/models/base.py:22-38
-class RedBearModelConfig(BaseModel):
-    model_name: str
-    provider: str
-    api_key: str
-    base_url: Optional[str] = None
-    timeout: float = Field(default_factory=lambda: float(os.getenv("LLM_TIMEOUT", "120.0")))
-    max_retries: int = Field(default_factory=lambda: int(os.getenv("LLM_MAX_RETRIES", "2")))
-    concurrency: int = 5
-    extra_params: Dict[str, Any] = {}
-```
-
----
-
-## 6. 如何替换 Embedding 模型（操作步骤 + 影响面分析）
-
-### 6.1 操作步骤
-
-**场景 A：为新知识库配置新模型（推荐，零风险）**
-
-1. 进入管理后台 → 模型管理 → 添加新 Embedding 模型配置
-2. 填写 provider、model_name、api_key、base_url
-3. 验证模型可用性（model_service.py 会调用 `embed_documents` 测试）
-4. 创建新知识库时选择该模型作为 `embedding_id`
-5. 新入库文档自动使用新模型生成向量
-
-**场景 B：替换已有知识库的 Embedding 模型（高风险，需重建索引）**
-
-1. **备份数据**：导出知识库下所有文档元数据
-2. **删除旧 ES 索引**：
-   ```python
-   # 索引名格式: Vector_index_{knowledge_id}_Node
-   vector_service.delete()  # elasticsearch_vector.py:176
-   ```
-3. **更新知识库配置**：修改 `knowledge.embedding_id` 为新模型 ID
-4. **重新解析所有文档**：触发完整的 Chunk → Embedding → ES 写入流程
-5. **验证维度一致性**：确认所有 Chunk 向量维度相同
-6. **检索验证**：执行测试查询，确认向量检索正常返回
-
-### 6.2 影响面分析
-
-| 组件 | 影响 | 说明 |
-|------|------|------|
-| ES 索引 | **必须重建** | `dense_vector.dims` 在创建时固定，不支持动态变更 |
-| 历史 Chunk | **需重新嵌入** | 旧向量与新向量维度/语义空间不同，不能混用 |
-| 检索质量 | 可能变化 | 不同模型的语义表示能力不同，需重新调参阈值 |
-| API 成本 | 短期增加 | 重建索引期间产生全量 Embedding API 调用费用 |
-| GraphRAG | 需同步更新 | 实体/关系向量也需使用同一模型，否则语义空间不一致 |
-| 混合检索 | 需重新校准 | 向量相似度权重 `vector_similarity_weight` 可能需要调整 |
-
----
-
-## 7. 边界条件与已知限制
-
-1. **维度上限**：ES `dense_vector` 字段 `index: True` 时维度上限 1024；`index: False` 时上限 2048。当前代码 `index: True`，若使用 1536 维模型（如 OpenAI text-embedding-ada-002）会触发此限制
-2. **batch_size 硬编码**：各模型的 batch_size（16 或 4）在源码中写死，不可配置
-3. **无 Embedding 调用计费统计**：系统未记录 Embedding API 的调用次数和 Token 消耗（仅 LLM 有统计）
-4. **无 Embedding 降级**：主模型失败时无自动切换到备用模型的机制
-5. **QWen 截断差异**：QWen 截断到 2048 tokens，而其他 OpenAI 兼容类截断到 8000，混合使用时需特别注意
-6. **文本截断使用 cl100k_base**：`token_utils.py` 使用 `cl100k_base` 编码器，可能与实际模型使用的 tokenizer 不一致（如 QWen 使用自己的 tokenizer），导致截断长度不准
-
----
-
-## 8. 监控指标与排错指引
-
-### 8.1 建议监控指标
-
-| 指标 | 采集方式 | 告警阈值建议 |
-|------|---------|-------------|
-| Embedding API 响应时间 | LangChain callback 或中间件拦截 | P99 > 5s |
-| Embedding API 错误率 | 异常捕获统计 | > 1% |
-| Embedding Token 消耗 | API 响应中的 usage.total_tokens | 按预算设置 |
-| ES 向量写入延迟 | ES bulk API 响应时间 | > 2s |
-| Redis 缓存命中率 | `get_embed_cache` 命中统计 | < 50% 时排查 |
-
-### 8.2 常见故障排查
-
-| 现象 | 根因 | 排查路径 |
-|------|------|---------|
-| 向量检索返回空 | 维度不匹配 / 相似度阈值过高 | 检查 `dense_vector.dims` 与 Embedding 输出维度是否一致；降低 `score_threshold` |
-| Embedding 调用超时 | API 服务商响应慢 / 文本过长 | 检查 `LLM_TIMEOUT`；检查文本是否被正确截断 |
-| 批量 Embedding 失败 | batch_size 过大 | 减小 batch_size（需改源码） |
-| GraphRAG 实体向量不一致 | 缓存命中但模型已更换 | 清除 Redis 中 `get_embed_cache` 相关 key |
-| ES 写入报错 "illegal_argument_exception" | dense_vector 维度超限 | 确认 `index: True` 时 dims <= 1024 |
-
----
-
-## 9. 优化建议与未来扩展点
-
-### 9.1 短期优化（代码级）
-
-1. **全局 Embedding 缓存层**：将 `get_embed_cache` / `set_embed_cache` 机制扩展到 ES 向量入库/检索链路，减少重复 API 调用
-2. **可配置 batch_size**：将硬编码的 16/4 提取为环境变量或数据库配置项
-3. **备用模型降级**：实现 Embedding 模型的主备切换逻辑（类似 LLM 的 fallback 机制）
-4. **维度一致性校验**：在 `add_chunks()` 和 `search_by_vector()` 中增加维度校验，提前发现不匹配问题
-
-### 9.2 中期优化（架构级）
-
-1. **Embedding 服务化**：将 Embedding 调用抽离为独立微服务，支持：
-   - 统一缓存（Redis + 本地 LRU）
-   - 请求队列 + 速率限制
-   - 多模型负载均衡
-2. **异步 Embedding 流水线**：文档入库时先写入队列，后台异步完成 Embedding 和 ES 写入
-3. **Embedding 质量监控**：定期抽样检测向量空间的分布质量（如余弦相似度分布、异常值检测）
-
-### 9.3 长期扩展（功能级）
-
-1. **多模态 Embedding 全链路支持**：当前仅火山引擎支持多模态，未来可扩展到更多 provider
-2. **自适应维度选择**：根据知识库数据量和精度需求，自动推荐最优 Embedding 维度
-3. **Embedding 微调**：支持基于领域数据的 Embedding 模型微调（如 fine-tune BGE）
-4. **跨模型向量映射**：研究不同 Embedding 模型之间的向量映射技术，实现平滑迁移而不重建索引
-
----
-
-*文档基于 MemoryBear 仓库 commit 最新状态梳理。关键源码路径均已标注行号，可在 ±3 行范围内验证。*

docs/rag/pipeline/03-vdb-and-retrieval.md

@@ -1,973 +0,0 @@
-# [S2-T3] 向量数据库选型、索引与检索策略实现详解
-
-> 范围：`api/app/core/rag/vdb/elasticsearch/`、`api/app/core/rag/utils/es_conn.py`、`api/app/core/rag/utils/doc_store_conn.py`、`api/app/core/rag/nlp/{search.py, query.py}`、`api/app/core/rag/res/mapping.json` 以及调用方 `api/app/core/workflow/nodes/knowledge/node.py`、`api/app/services/memory_konwledges_server.py` 等。
->
-> 提示：MemoryBear 当前版本中存在**两套并行的 ES 实现路径**，本文会逐一拆开说明，并给出二者的边界与实际调用方。
-
----
-
-## 一、一句话定位
-
-MemoryBear 使用 **Elasticsearch 8.x** 作为向量 + 全文一体化的检索引擎，通过 `dense_vector` (HNSW) 实现语义检索、Lucene + IK 分词器实现关键词检索，并在应用层与 ES DSL 层各自实现一套"混合搜索"策略（应用层为"双路 + 去重 + 可选 Rerank"，DSL 层为"weighted_sum 加权融合"）。
-
-## 二、设计目标与选型说明
-
-### 2.1 选型动机（为什么是 Elasticsearch 而非 Milvus / Qdrant / Pinecone？）
-
-README 中明确把 **"Hybrid Search: Keyword + Semantic Vector"** 列为产品级核心能力之一（README.md:62-66）。结合源码可以推出三条关键决策依据：
-
-1. **关键词侧需要 Lucene 生态** — 既要中文分词（IK `ik_max_word`），又要 BM25 / 布尔过滤 / 高亮 / 同义词扩展 / 短语匹配 / 字段权重等成熟能力，Milvus / Qdrant / Pinecone 在这一侧几乎都需要外接 ES/OS。`api/app/core/rag/nlp/query.py:14-22` 的 `query_fields = ["title_tks^10", "important_kwd^30", "content_ltks^2", ...]` 就是典型 Lucene field-boost 写法，离开 ES 改造代价很高。
-2. **一份索引同时承担多种载荷** — 一个 ES 索引同时存储 chunk 文本 (`page_content`)、向量 (`*_vec`)、稀疏 tokens (`*_tks` / `*_ltks`)、标签 rank_features (`tag_feas`)、PageRank-like 分数 (`pagerank_fea`)、地理 (`lat_lon`)、嵌套结构 (`*_nst`) 等异构字段（见 `api/app/core/rag/res/mapping.json:25-209`）。专用向量库无法承载这种混合 schema。
-3. **运维与生态成本** — 团队仅运行 PostgreSQL / Neo4j / Redis / ES（README "Prerequisites"），引入第二套向量服务会显著抬高运维曲线。`@singleton` 的 `ESConnection` (`api/app/core/rag/utils/es_conn.py:26-56`) 与 `ElasticSearchVectorFactory._client` (`api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:666-732`) 共享连接，工程上已经按"单实例多用途"在使用 ES。
-
-> 代价：ES 的 ANN 在百万-千万 chunk 时延迟会明显高于 Milvus/Qdrant；当未来 chunk 量级或 QPS 显著增长时，本架构需要拆出独立向量服务（详见 §6 优化建议）。
-
-### 2.2 ES 版本约束
-
-启动期硬性校验 ES 必须 ≥ 8.0：
-
-```python
-# api/app/core/rag/utils/es_conn.py:44-49
-v = self.info.get("version", {"number": "8.0.0"})
-v = v["number"].split(".")[0]
-if int(v) < 8:
-    msg = f"Elasticsearch version must be greater than or equal to 8, current version: {v}"
-    logger.error(msg)
-    raise Exception(msg)
-```
-
-```python
-# api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:716-722
-if not cls._version_checked:
-    info = client.info()
-    version = info["version"]["number"]
-    if parse_version(version) < parse_version("8.0.0"):
-        raise ValueError(f"Elasticsearch version must be >= 8.0.0, got {version}")
-```
-
-> **why**：ES 8.0 才正式提供 `dense_vector` HNSW 索引、`knn` 顶层查询、以及 query_string + knn 的混合检索，本系统的 `s.knn(...)`、`type=dense_vector index=true similarity=cosine` 都依赖该版本。
-
----
-
-## 三、模块结构与两条实现路径
-
-```
-api/app/core/rag/
-├── res/mapping.json            ← graphrag_{workspace_id} 索引使用的全局 mapping
-├── utils/
-│   ├── doc_store_conn.py       ← 抽象接口 DocStoreConnection + MatchExpr / FusionExpr
-│   └── es_conn.py              ← @singleton 实现 DocStoreConnection（路径 A）
-├── vdb/
-│   ├── vector_base.py          ← 抽象接口 BaseVector
-│   ├── field.py                ← page_content / metadata / vector 等字段名常量
-│   └── elasticsearch/
-│       └── elasticsearch_vector.py  ← BaseVector 的 ES 实现（路径 B）
-├── nlp/
-│   ├── search.py               ← 同时承载两条路径：knowledge_retrieval（路径 B）+ Dealer（路径 A）
-│   └── query.py                ← FulltextQueryer，构造 Lucene query_string
-└── common/
-    ├── settings.py             ← 全局初始化 docStoreConn / retriever / kg_retriever
-    └── constants.py            ← PAGERANK_FLD / TAG_FLD 等常量
-```
-
-### 3.1 路径 A：`ESConnection`（DSL 抽象层，主要服务于 GraphRAG 与高级检索）
-
-- 抽象基类：`api/app/core/rag/utils/doc_store_conn.py:128-256` 定义 `DocStoreConnection` 接口（dbType / createIdx / search / insert / update / delete / sql 等）。
-- 表达式族：同文件 43-126 行定义 `MatchTextExpr`、`MatchDenseExpr`、`MatchSparseExpr`、`MatchTensorExpr`、`FusionExpr`、`OrderByExpr` —— 这是上层与底层解耦的"查询 IR"。
-- ES 实现：`@singleton class ESConnection(DocStoreConnection)`（`api/app/core/rag/utils/es_conn.py:26-634`）。
-- 全局入口：`api/app/core/rag/common/settings.py:13-24` 在模块导入时即 `init_settings()`，把 `ESConnection()` 装进 `docStoreConn`，并注入 `Dealer` / `KGSearch`。
-- 对应的检索门面：`api/app/core/rag/nlp/search.py: Dealer`（350-907 行），由 `kg_retriever`、`retriever` 全局共用。
-
-### 3.2 路径 B：`ElasticSearchVector`（应用层 BaseVector，主要服务于 KB 节点 / 工作流）
-
-- 抽象基类：`api/app/core/rag/vdb/vector_base.py:9-67` 定义 `BaseVector` 接口（create / add_texts / search_by_vector / search_by_full_text / delete 等）。
-- 字段命名：`api/app/core/rag/vdb/field.py`：`page_content` / `metadata` / `vector` / `metadata.doc_id` 等。
-- ES 实现：`class ElasticSearchVector(BaseVector)` + `class ElasticSearchVectorFactory`（`api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:29-732`）。
-- 关键调用方：
-  - `api/app/core/workflow/nodes/knowledge/node.py:195-298` 工作流知识节点，按 `RetrieveType` 分支调用 `search_by_vector / search_by_full_text`。
-  - `api/app/core/rag/nlp/search.py: knowledge_retrieval`（36-147 行）API/服务层入口。
-  - `api/app/services/memory_konwledges_server.py`、`api/app/controllers/{chunk,document,knowledge}_controller.py` 等。
-
-### 3.3 两条路径的边界
-
-| 维度 | 路径 A（ESConnection / Dealer） | 路径 B（ElasticSearchVector） |
-| --- | --- | --- |
-| 索引名 | `graphrag_{workspace_id}` | `Vector_index_{kb_id}_Node`（小写）|
-| 索引粒度 | 一个 workspace 一个 ES index，多 KB 用 `kb_id` 字段过滤 | 一个 KB 一个 ES index |
-| Mapping | `res/mapping.json` 全局 dynamic_templates | 代码里 inline 的 `index_mapping` (`elasticsearch_vector.py:616-661`) |
-| 文本字段 | `content_ltks` / `content_sm_ltks` / `title_tks` / `important_kwd` / `*_tks` | `page_content` (`text` + `ik_max_word`) |
-| 向量字段 | 动态 `q_{dim}_vec` (`*_512_vec` / `*_768_vec` / `*_1024_vec` / `*_1536_vec`) | 固定 `vector`（dim 取首批 embeddings 长度）|
-| 关键词检索 | Lucene `query_string`（field-boost、同义词、短语）| `match` + `analyzer=ik_max_word`（BM25）|
-| 向量检索 | `s.knn(...)`（HNSW，ES 8 原生 ANN）| `script_score` + `cosineSimilarity`（暴力，但精度高）|
-| 混合融合 | `FusionExpr("weighted_sum", weights="0.05,0.95")` 应用层加权 + ES 内部混合 | 双路并发查 → metadata.doc_id 去重 → 可选 reranker |
-| 主要使用者 | GraphRAG、`Dealer.retrieval()`、tag/citation 等高级能力 | 工作流知识节点、KB CRUD、召回测试 |
-
-> **why 不合并**：路径 A 携带丰富 IR（同义词扩展、`tag_feas`、`pagerank_fea`、`question_tks` 等），是面向"知识图谱 + 复杂 RAG"的；路径 B 简单直接，是工作流/服务层的"够用就好"封装。代码上是渐进演化中的双轨，但**目前两条路径都在生产使用**。
-
----
-
-## 四、索引设计
-
-### 4.1 全局 mapping（路径 A，`api/app/core/rag/res/mapping.json`）
-
-#### 4.1.1 settings
-
-```json
-// api/app/core/rag/res/mapping.json:2-15
-"settings": {
-  "index": {
-    "number_of_shards": 2,
-    "number_of_replicas": 0,
-    "refresh_interval": "1000ms"
-  },
-  "similarity": {
-    "scripted_sim": {
-      "type": "scripted",
-      "script": {
-        "source": "double idf = Math.log(1+(field.docCount-term.docFreq+0.5)/(term.docFreq + 0.5))/Math.log(1+((field.docCount-0.5)/1.5)); return query.boost * idf * Math.min(doc.freq, 1);"
-      }
-    }
-  }
-}
-```
-
-| 项 | 值 | 说明 |
-| --- | --- | --- |
-| `number_of_shards` | 2 | 适合中小型部署；超过 50GB / 单 shard 时需重新规划 |
-| `number_of_replicas` | 0 | **生产风险点**：单副本意味着任一分片丢失即数据丢失，建议生产环境改为 ≥1 |
-| `refresh_interval` | 1000ms | 默认 1s 即可见，写入吞吐场景可调高至 30s 或写入期 `-1` |
-| `scripted_sim` | 自定义 BM25 变体 | 用 `Math.min(doc.freq, 1)` 把词频压成 0/1，等价于 binary BM25——抑制高 TF 的关键字"灌水"，对 token 字段更鲁棒 |
-
-#### 4.1.2 dynamic_templates（按字段名后缀决定字段类型）
-
-```json
-// api/app/core/rag/res/mapping.json:25-209（节选）
-{ "int":           { "match": "*_int",   "mapping": { "type": "integer", "store": "true" }}},
-{ "ulong":         { "match": "*_ulong", "mapping": { "type": "unsigned_long" }}},
-{ "long":          { "match": "*_long",  "mapping": { "type": "long" }}},
-{ "numeric":       { "match": "*_flt",   "mapping": { "type": "float" }}},
-
-{ "tks":  { "match": "*_tks",  "mapping": { "type": "text", "similarity": "scripted_sim", "analyzer": "whitespace" }}},
-{ "ltks": { "match": "*_ltks", "mapping": { "type": "text", "analyzer": "whitespace" }}},
-
-{ "kwd":  { "match_pattern": "regex",
-            "match": "^(.*_(kwd|id|ids|uid|uids)|uid)$",
-            "mapping": { "type": "keyword", "similarity": "boolean" }}},
-{ "dt":   { "match_pattern": "regex",
-            "match": "^.*(_dt|_time|_at)$",
-            "mapping": { "type": "date", "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||yyyy-MM-dd_HH:mm:ss" }}},
-
-{ "rank_feature":  { "match": "*_fea",  "mapping": { "type": "rank_feature" }}},
-{ "rank_features": { "match": "*_feas", "mapping": { "type": "rank_features" }}},
-
-{ "dense_vector": { "match": "*_512_vec",  "mapping": { "type": "dense_vector", "index": true, "similarity": "cosine", "dims": 512 }}},
-{ "dense_vector": { "match": "*_768_vec",  "mapping": { "type": "dense_vector", "index": true, "similarity": "cosine", "dims": 768 }}},
-{ "dense_vector": { "match": "*_1024_vec", "mapping": { "type": "dense_vector", "index": true, "similarity": "cosine", "dims": 1024 }}},
-{ "dense_vector": { "match": "*_1536_vec", "mapping": { "type": "dense_vector", "index": true, "similarity": "cosine", "dims": 1536 }}},
-
-{ "nested": { "match": "*_nst", "mapping": { "type": "nested" }}},
-{ "binary": { "match": "*_bin", "mapping": { "type": "binary" }}}
-```
-
-**why dynamic 而不是 strict mapping**：
-
-- 不同 embedding 模型维度不同（512/768/1024/1536），通过字段名后缀让"模型即维度"，在 `nlp/search.py:372` 看到查询侧动态拼名 `f"q_{len(embedding_data)}_vec"`，写入侧也是同样命名，零配置切换 embedding。
-- token 字段分 `*_tks` 与 `*_ltks`：前者使用 `scripted_sim`（去 TF），用于 important_kwd 这类"命中即可"字段；后者 BM25 默认，用于正文型 `content_ltks`。
-- `*_fea` (rank_feature) 与 `*_feas` (rank_features) 用于 PageRank 与 tag 加权，详见检索章节的 `_rank_feature_scores`。
-
-> **why analyzer 是 `whitespace` 而不是 IK**：路径 A 在写入前先用 `rag_tokenizer` 在应用层做完中文分词，写入 ES 时已经是空格分隔的 tokens。这样"分词逻辑"留在应用层，便于热更新词典与同义词，不用 reindex。
-
-### 4.2 路径 B 的 inline mapping（KB 索引）
-
-```python
-# api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:609-663
-def create_collection(self, embeddings, metadatas=None, index_params=None):
-    if not self._client.indices.exists(index=self._collection_name):
-        index_mapping = {
-            "mappings": {
-                "properties": {
-                    Field.CONTENT_KEY.value: {           # "page_content"
-                        "type": "text",
-                        "analyzer": "ik_max_word"
-                    },
-                    Field.METADATA_KEY.value: {           # "metadata"
-                        "type": "object",
-                        "properties": {
-                            "doc_id":          {"type": "keyword"},
-                            "file_id":         {"type": "keyword"},
-                            "file_name":       {"type": "keyword"},
-                            "file_created_at": {"type": "date", "format": "epoch_millis"},
-                            "document_id":     {"type": "keyword"},
-                            "knowledge_id":    {"type": "keyword"},
-                            "sort_id":         {"type": "long"},
-                            "status":          {"type": "integer"}
-                        }
-                    },
-                    Field.VECTOR.value: {                 # "vector"
-                        "type": "dense_vector",
-                        "dims": len(embeddings[0]),
-                        "index": True,
-                        "similarity": "cosine"
-                    }
-                }
-            }
-        }
-        self._client.indices.create(index=self._collection_name, body=index_mapping)
-```
-
-要点：
-
-- 索引按 KB 隔离：`collection_name = f"Vector_index_{knowledge.id}_Node"`（同文件 738 行），ES 端要求小写，所以 `super().__init__(index_name.lower())`（32 行）。
-- `dims = len(embeddings[0])` —— 维度由"第一批数据"决定，**一旦确定不可改**。换 embedding 模型必须重建索引（详见 §6 风险点）。
-- `similarity = "cosine"` —— 写入向量不要求归一化，由 ES 内部计算余弦相似度。
-- 没有显式 `number_of_shards`/`replicas` 设置，**走 ES 集群默认**（8.x 默认 1 shard 1 replica），可用性比路径 A 反而更好；但碎片化风险也更高（每个 KB 一个 index，KB 多了 cluster state 会膨胀）。
-
-### 4.3 索引命名与隔离
-
-| 路径 | 索引模板 | 来源 |
-| --- | --- | --- |
-| A | `graphrag_{workspace_id}` | `nlp/search.py:346` `def index_name(uid): return f"graphrag_{uid}"` |
-| B | `Vector_index_{kb_id}_Node`（小写）| `elasticsearch_vector.py:738` |
-
-路径 A 在删除知识库时**故意不删 ES 索引**，而是仅删 `kb_id` 维度的文档：
-
-```python
-# api/app/core/rag/utils/es_conn.py:115-124
-def deleteIdx(self, indexName: str, knowledgebaseId: str):
-    if len(knowledgebaseId) > 0:
-        # The index need to be alive after any kb deletion since all kb under this workspace are in one index.
-        return
-    try:
-        self.es.indices.delete(index=indexName, allow_no_indices=True)
-    except NotFoundError:
-        pass
-```
-
-> **why**：一个 workspace 多 KB 共享同一个 index，单 KB 删除不能动 index；只能在 `delete()` 通过 `condition["kb_id"]=knowledgebaseId` 走 delete-by-query（同文件 424-471）。
-
----
-
-## 五、写入链路
-
-### 5.1 路径 B：高层封装（KB / 工作流场景）
-
-```python
-# api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:55-87
-def add_chunks(self, chunks: list[DocumentChunk], **kwargs):
-    texts = [chunk.page_content for chunk in chunks]
-    if self.is_multimodal_embedding:
-        embeddings = self.embeddings.embed_batch(texts)
-    else:
-        embeddings = self.embeddings.embed_documents(list(texts))
-    self.create(chunks, embeddings, **kwargs)
-
-def create(self, chunks, embeddings, **kwargs):
-    metadatas = [chunk.metadata or {} for chunk in chunks]
-    if not self._client.indices.exists(index=self._collection_name):
-        self.create_collection(embeddings, metadatas)   # 懒建索引
-    self.add_texts(chunks, embeddings, **kwargs)
-
-def add_texts(self, chunks, embeddings, **kwargs):
-    uuids = self._get_uuids(chunks)
-    actions = []
-    for i, chunk in enumerate(chunks):
-        actions.append({
-            "_index": self._collection_name,
-            "_source": {
-                Field.CONTENT_KEY.value: chunk.page_content,
-                Field.METADATA_KEY.value: chunk.metadata or {},
-                Field.VECTOR.value: embeddings[i] or None,
-            }
-        })
-    result = helpers.bulk(self._client, actions)
-    return uuids
-```
-
-特性：
-
-- **懒建索引**：第一次写入时根据 `len(embeddings[0])` 建 mapping。
-- **批量写**：`elasticsearch.helpers.bulk` 默认 chunk_size=500、max_chunk_bytes=100MB；这里不传 `_id`，ES 自动生成。
-- **唯一性**：路径 B 把 chunk 唯一标识放在 `metadata.doc_id`（`vector_base.py:62-63 _get_uuids`），更新/删除走"先 search by metadata.doc_id 拿真正 _id 再 bulk delete"两步走（`elasticsearch_vector.py:148-174`）。
-- **失败处理**：`helpers.bulk` 默认抛 `BulkIndexError`，调用方在 `delete_by_ids / delete_by_metadata_field` 中分桶捕获 404 与其它错误（同文件 137-147、164-174）。**`add_texts` 没有捕获**——一旦底层网络失败会向上抛，调用方需要保证幂等性或重试。
-
-### 5.2 路径 A：抽象层批量写
-
-```python
-# api/app/core/rag/utils/es_conn.py:294-330
-def insert(self, documents, indexName, knowledgebaseId=None) -> list[str]:
-    operations = []
-    for d in documents:
-        assert "_id" not in d
-        assert "id" in d
-        d_copy = copy.deepcopy(d)
-        d_copy["kb_id"] = knowledgebaseId
-        meta_id = d_copy.pop("id", "")
-        operations.append({"index": {"_index": indexName, "_id": meta_id}})
-        operations.append(d_copy)
-
-    res = []
-    for _ in range(ATTEMPT_TIME):       # 默认 2 次
-        try:
-            r = self.es.bulk(index=indexName, operations=operations,
-                             refresh=False, timeout="60s")
-            if re.search(r"False", str(r["errors"]), re.IGNORECASE):
-                return res
-            for item in r["items"]:
-                for action in ["create", "delete", "index", "update"]:
-                    if action in item and "error" in item[action]:
-                        res.append(str(item[action]["_id"]) + ":" + str(item[action]["error"]))
-            return res
-        except ConnectionTimeout:
-            time.sleep(3); self._connect(); continue
-        except Exception as e:
-            res.append(str(e)); break
-    return res
-```
-
-要点：
-
-- **显式 `_id = id`**：调用方自己保证 chunk_id 唯一（典型实现：`uuid4()` 或基于 `doc_id+chunk_idx` 的稳定 hash），重复写入即"覆盖式更新"，天然支持幂等重试。
-- **强制注入 `kb_id`**：所有 chunk 都打上 `kb_id` 标签，作为多租户隔离与 delete-by-query 的依据。
-- **refresh=False**：写入不等可见，吞吐优先；查询侧通过 1s 默认 refresh 间隔获得近实时性。
-- **显式 timeout="60s"** + ATTEMPT_TIME=2 重连 —— 网络抖动会自动重试一次。
-- **失败回滚？** 只返回失败列表，**不做事务回滚**。这是 ES 的典型用法：bulk 是 best-effort，调用方需要根据返回值决定是否补偿（如 chunker 重新生成失败 chunk）。
-
-### 5.3 增量更新（路径 A）
-
-```python
-# api/app/core/rag/utils/es_conn.py:332-422
-def update(self, condition, newValue, indexName, knowledgebaseId) -> bool:
-    # 单文档 update
-    if "id" in condition and isinstance(condition["id"], str):
-        chunkId = condition["id"]
-        # 删除字段（带 _feas 后缀的 rank_features 必须先 remove 再 set，否则旧 token 残留）
-        for k in doc.keys():
-            if k.split("_")[-1] == "feas":
-                self.es.update(index=indexName, id=chunkId, script=f"ctx._source.remove(\"{k}\");")
-        self.es.update(index=indexName, id=chunkId, doc=doc)
-        return True
-
-    # 批量 update_by_query：构造 painless 脚本
-    bqry = Q("bool")
-    # ... 把 condition 转成 filter
-    scripts = []; params = {}
-    for k, v in newValue.items():
-        if k == "remove":     # remove 单个 list 元素
-            scripts.append(f"int i=ctx._source.{kk}.indexOf(params.p_{kk});ctx._source.{kk}.remove(i);")
-        elif k == "add":      # 向 list 追加
-            scripts.append(f"ctx._source.{kk}.add(params.pp_{kk});")
-        elif isinstance(v, str):
-            v = re.sub(r"(['\n\r]|\\.)", " ", v)         # 防止脚本注入
-            scripts.append(f"ctx._source.{k}=params.pp_{k};")
-        ...
-    ubq = UpdateByQuery(index=indexName).using(self.es).query(bqry)\
-                                          .script(source="".join(scripts), params=params)\
-                                          .params(refresh=True, slices=5, conflicts="proceed")
-    ubq.execute()
-```
-
-亮点：
-
-- **slices=5** —— 并行 update-by-query，写吞吐放大 5 倍。
-- **conflicts="proceed"** —— 遇到版本冲突跳过而不中止任务；适合"标签批量更新"这种最终一致场景。
-- **rank_features 必须先 remove**：因为 `*_feas` 是"key→score"字典，新值无法覆盖旧 key（341-346 行的 patch）。
-- **input sanitation**：对 string 值做 `re.sub(r"(['\n\r]|\\.)", " ", v)` 防止 painless 脚本注入。
-
-### 5.4 路径 B 的 update_by_query
-
-```python
-# api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:299-342
-def update_by_segment(self, chunk: DocumentChunk, **kwargs) -> str:
-    if self.is_multimodal_embedding:
-        chunk.vector = self.embeddings.embed_text(chunk.page_content)
-    else:
-        chunk.vector = self.embeddings.embed_query(chunk.page_content)
-    body = {
-        "script": {
-            "source": """
-                ctx._source.page_content = params.new_content;
-                ctx._source.vector = params.new_vector;
-            """,
-            "params": {"new_content": chunk.page_content, "new_vector": chunk.vector}
-        },
-        "query": {"term": {Field.DOC_ID.value: chunk.metadata["doc_id"]}}
-    }
-    return self._client.update_by_query(index=indices, body=body)['updated']
-```
-
-注意：`metadata.doc_id`(关键字段) 一查多匹配 → 全部刷新内容与向量。这是路径 B 的"chunk 更新"语义，**没有版本控制**，并发更新会以最后写入为准；需要严格控制时应在调用方加锁或退化为先 `delete_by_ids` 再 `add_chunks`。
-
----
-
-## 六、检索链路
-
-### 6.1 三种检索类型（应用层枚举）
-
-```python
-# api/app/schemas/chunk_schema.py:8-13
-class RetrieveType(StrEnum):
-    PARTICIPLE = "participle"   # 关键词 / 分词检索（BM25）
-    SEMANTIC   = "semantic"     # 语义 / 向量检索（cosine）
-    HYBRID     = "hybrid"       # 混合检索：双路 + 去重 (+ rerank)
-    Graph      = "graph"        # 在 hybrid 之上叠加 GraphRAG 检索
-```
-
-在 `api/app/core/workflow/nodes/knowledge/node.py:213-298` 与 `api/app/core/rag/nlp/search.py:220-281` 两处可以看到完全一致的三分支 + 默认走 hybrid 的派发逻辑。
-
-### 6.2 关键词检索（路径 B：BM25 + IK）
-
-```python
-# api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:468-558（节选）
-def search_by_full_text(self, query: str, **kwargs) -> list[DocumentChunk]:
-    top_k           = kwargs.get("top_k", 1024)
-    score_threshold = float(kwargs.get("score_threshold") or 0.2)
-    file_names_filter = kwargs.get("file_names_filter")
-
-    query_str = {
-        "bool": {
-            "must": {
-                "match": {
-                    Field.CONTENT_KEY.value: {
-                        "query": query,
-                        "analyzer": "ik_max_word"        # 与建索引时一致
-                    }
-                }
-            },
-            "filter": {"term": {"metadata.status": 1}}   # 只看启用状态
-        }
-    }
-    # 可选叠加 file_name 多选过滤
-    if file_names_filter:
-        query_str["bool"]["filter"] = [
-            {"term":  {"metadata.status": 1}},
-            {"terms": {"metadata.file_name": file_names_filter}}
-        ]
-
-    result = self._client.search(index=indices, from_=0, size=top_k, query=query_str)
-    max_score = result["hits"]["max_score"] or 1.0
-    docs_and_scores = []
-    for res in result["hits"]["hits"]:
-        normalized_score = res["_score"] / max_score      # 归一化到 [0,1]
-        ...
-    return [doc for doc, score in docs_and_scores if score > score_threshold]
-```
-
-要点：
-
-- BM25 默认相似度，`ik_max_word` 中文分词；写入与查询使用同一 analyzer，避免分词错位。
-- **score 归一化**：BM25 score 是开放区间，除以 `max_score` 缩放到 [0,1]，便于与 `score_threshold` 比较，也便于和向量分数同尺度对齐。
-- 默认 `score_threshold=0.2`、`top_k=1024`。
-
-### 6.3 关键词检索（路径 A：query_string + 同义词扩展）
-
-```python
-# api/app/core/rag/nlp/query.py:69-201（节选）
-class FulltextQueryer:
-    query_fields = [
-        "title_tks^10", "title_sm_tks^5",
-        "important_kwd^30", "important_tks^20",
-        "question_tks^20",
-        "content_ltks^2", "content_sm_ltks",
-    ]
-
-    def question(self, txt, tbl="qa", min_match: float = 0.6):
-        txt = self.add_space_between_eng_zh(txt)        # 中英分词预处理
-        txt = self.rmWWW(txt)                            # 去问句词（怎么/吗/啥/what/how/...）
-        ...
-        # 中文分支：term_weight 权重 + synonym 同义词扩展
-        for tt in self.tw.split(txt)[:256]:
-            twts = self.tw.weights([tt])
-            syns = self.syn.lookup(tt)
-            tk_syns = [f"({tk} OR (%s)^0.2)" % " ".join(tk_syns), ...]   # 同义词权重 0.2
-            tms.append((tk, w))
-        query = " OR ".join([f"({t})" for t in qs if t])
-        return MatchTextExpr(self.query_fields, query, 100,
-                             {"minimum_should_match": min_match}), keywords
-```
-
-```python
-# api/app/core/rag/utils/es_conn.py:196-217
-for m in matchExprs:
-    if isinstance(m, MatchTextExpr):
-        minimum_should_match = m.extra_options.get("minimum_should_match", 0.0)
-        if isinstance(minimum_should_match, float):
-            minimum_should_match = str(int(minimum_should_match * 100)) + "%"
-        bqry.must.append(Q("query_string", fields=m.fields,
-                           type="best_fields", query=m.matching_text,
-                           minimum_should_match=minimum_should_match,
-                           boost=1))
-        bqry.boost = 1.0 - vector_similarity_weight
-```
-
-亮点：
-
-- **多字段 field-boost**：`important_kwd^30` 表示标签字段权重远高于正文，符合"重要标签命中即高排名"的直觉。
-- **同义词加权 0.2**：同义词召回但低权重，避免"同义词稀释"主体相关性。
-- **minimum_should_match**：默认 0.3 / 0.6，控制 BM25 召回的"严苛度"。当 hybrid 总命中为 0 时会 fallback 到 0.1 重试（详见 6.7）。
-- **`type="best_fields"`**：多字段场景取每字段最高分作为最终分，符合"标题命中比正文命中更重要"的语义。
-
-### 6.4 向量检索（路径 B：script_score + cosine）
-
-```python
-# api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:374-466（节选）
-def search_by_vector(self, query: str, **kwargs) -> list[DocumentChunk]:
-    if self.is_multimodal_embedding:
-        query_vector = self.embeddings.embed_text(query)
-    else:
-        query_vector = self.embeddings.embed_query(query)
-    top_k           = kwargs.get("top_k", 1024)
-    score_threshold = float(kwargs.get("score_threshold") or 0.3)
-    file_names_filter = kwargs.get("file_names_filter")
-
-    query_str = {
-        "bool": {
-            "must": {
-                "script_score": {
-                    "query": {"match_all": {}},
-                    "script": {
-                        # cosineSimilarity 范围 [-1,1]，+1 后落到 [0,2]
-                        "source": f"cosineSimilarity(params.query_vector, '{Field.VECTOR.value}') + 1.0",
-                        "params": {"query_vector": query_vector}
-                    }
-                }
-            },
-            "filter": {"term": {"metadata.status": 1}}
-        }
-    }
-
-    result = self._client.search(index=indices, from_=0, size=top_k, query=query_str)
-    docs_and_scores = []
-    for res in result["hits"]["hits"]:
-        score = res["_score"] / 2          # [0,2] -> [0,1]
-        docs_and_scores.append((..., score))
-    return [doc for doc, score in docs_and_scores if score > score_threshold]
-```
-
-特性与权衡：
-
-- **script_score 是暴力扫描**：会对 `match_all` 命中的所有文档（叠加 status=1 filter 后）逐一算 cosine，复杂度 O(N·dim)。优点是结果**精确**、无 ANN 召回率损失；缺点是延迟随 KB chunk 数线性增长，不适合 chunk 量级大的 KB。
-- **score 归一化**：`(cos+1)/2 ∈ [0,1]`，与 BM25 归一化值同尺度。
-- **过滤集成**：`metadata.status=1` 在 filter 上，先过滤再算分；`file_names_filter` 同理。
-
-### 6.5 向量检索（路径 A：knn + filter）
-
-```python
-# api/app/core/rag/utils/es_conn.py:206-217
-elif isinstance(m, MatchDenseExpr):
-    similarity = m.extra_options.get("similarity", 0.0)
-    s = s.knn(
-        m.vector_column_name,
-        m.topn,
-        m.topn * 2,                  # num_candidates = 2 * k，控制召回率
-        query_vector=list(m.embedding_data),
-        filter=bqry.to_dict(),       # 与 BM25 同一份 bool filter
-        # similarity=similarity      # 已注释：未启用阈值剪枝
-    )
-```
-
-```python
-# api/app/core/rag/nlp/search.py:365-373
-def get_vector(self, txt, emb_mdl, topk=10, similarity=0.1):
-    qv, _ = emb_mdl.encode_queries(txt)
-    embedding_data = [get_float(v) for v in qv]
-    vector_column_name = f"q_{len(embedding_data)}_vec"   # 动态选维度
-    return MatchDenseExpr(vector_column_name, embedding_data,
-                          'float', 'cosine', topk, {"similarity": similarity})
-```
-
-要点：
-
-- **HNSW ANN**：路径 A 用的是 ES 8 原生 `knn` query，底层 HNSW 索引，毫秒级，但有近似召回率损失。
-- **k vs num_candidates**：`topn * 2` 即 ANN 阶段先取 2k 候选再精排到 k，是召回率与延迟的折中。生产建议至少 `4 * topn`，更高召回。
-- **filter 共享**：`filter=bqry.to_dict()`——把 BM25 那份 bool filter 同时挂在 knn 上，确保过滤条件在 ANN 内部应用（pre-filter）；这点对多租户 `kb_id` 隔离尤为关键，否则 ANN 先取 top-k 再过滤，可能完全不返回该 KB 的文档。
-- **similarity 阈值已注释**：当前不启用 ES 内置阈值剪枝；需要按相似度阈值过滤的话，由应用层 (`Dealer.retrieval`) 在 rerank 阶段做。
-
-### 6.6 混合搜索 —— 这是本节最关键的"融合公式"
-
-#### 6.6.1 路径 A：`FusionExpr("weighted_sum")` + ES 内部混合（**核心融合点**）
-
-```python
-# api/app/core/rag/nlp/search.py:435-445
-matchDense = self.get_vector(qst, emb_mdl, topk, req.get("similarity", 0.1))
-q_vec = matchDense.embedding_data
-src.append(f"q_{len(q_vec)}_vec")
-
-fusionExpr = FusionExpr("weighted_sum", topk, {"weights": "0.05,0.95"})
-matchExprs = [matchText, matchDense, fusionExpr]
-
-res = self.dataStore.search(src, highlightFields, filters, matchExprs, orderBy,
-                            offset, limit, idx_names, kb_ids, rank_feature=rank_feature)
-```
-
-```python
-# api/app/core/rag/utils/es_conn.py:186-218
-s = Search()
-vector_similarity_weight = 0.5
-for m in matchExprs:
-    if isinstance(m, FusionExpr) and m.method == "weighted_sum" and "weights" in m.fusion_params:
-        # 必须按 [text, dense, fusion] 顺序传入
-        assert len(matchExprs) == 3 and isinstance(matchExprs[0], MatchTextExpr) \
-            and isinstance(matchExprs[1], MatchDenseExpr) and isinstance(matchExprs[2], FusionExpr)
-        weights = m.fusion_params["weights"]
-        vector_similarity_weight = get_float(weights.split(",")[1])    # "0.05,0.95" -> 0.95
-
-for m in matchExprs:
-    if isinstance(m, MatchTextExpr):
-        ...
-        bqry.must.append(Q("query_string", ..., boost=1))
-        bqry.boost = 1.0 - vector_similarity_weight                    # text 整体 boost = 0.05
-    elif isinstance(m, MatchDenseExpr):
-        s = s.knn(m.vector_column_name, m.topn, m.topn * 2,
-                  query_vector=list(m.embedding_data), filter=bqry.to_dict())
-if bqry:
-    s = s.query(bqry)
-```
-
-**融合公式**（这是 [S2-T7] 评审要求"必须明确"的部分）：
-
-```
-final_score(doc) = (1 - w_vec) * BM25_query_string_score(doc)
-                 +     w_vec   * knn_cosine_score(doc)
-                 + Σ rank_feature_score(doc)            ← PageRank + tag 加权（可选）
-```
-
-其中：
-
-- `w_vec = 0.95`（来自 `FusionExpr` 的 `"weights": "0.05,0.95"` 第二个权重）。
-- BM25 整体 `bqry.boost = 0.05`，即 `query_string` 的 BM25 分数被乘 0.05；knn 的分数没有显式 boost，相当于权重 1.0，但语义上由调用方约定 0.95（**即代码层面是"BM25 直接乘 0.05，knn 不缩放"，并未严格归一化到等比例**——这是一个已知近似，见 6.7 fallback）。
-- 排序逻辑：ES 8 的 hybrid 行为是"bool query 命中集 ∪ knn top-k 候选集"，并集后用各自分数相加（未命中那侧分数为 0）。`elasticsearch-dsl Search` 的 `.query(...).knn(...)` 组合自动启用此模式。
-- `rank_feature` 通过 `bqry.should.append(Q("rank_feature", field=fld, linear={}, boost=sc))`（es_conn.py:219-223）以**加性**方式融入最终分。
-
-> 这种"应用层约定 + ES 端 boost 缩放"的混合不是教科书式的归一化加权，但工程上简单：BM25 与 cosine 在统计上不同尺度，0.05/0.95 的**极端偏向语义**是为了"以语义检索为主、关键词作为补强"。
-
-#### 6.6.2 路径 B：双路 + 去重 + 可选 Rerank
-
-```python
-# api/app/core/workflow/nodes/knowledge/node.py:236-271
-case retrieve_type if retrieve_type in (RetrieveType.HYBRID, RetrieveType.Graph):
-    rs1_task = asyncio.to_thread(vector_service.search_by_vector, **{
-        "query": query, "top_k": kb_config.top_k,
-        "indices": indices, "score_threshold": kb_config.vector_similarity_weight
-    })
-    rs2_task = asyncio.to_thread(vector_service.search_by_full_text, **{
-        "query": query, "top_k": kb_config.top_k,
-        "indices": indices, "score_threshold": kb_config.similarity_threshold
-    })
-    rs1, rs2 = await asyncio.gather(rs1_task, rs2_task)        # 双路并发
-
-    unique_rs = self._deduplicate_docs(rs1, rs2)               # 按 doc_id 去重
-    if not unique_rs: return []
-    if self.typed_config.reranker_id:
-        rs.extend(await asyncio.to_thread(
-            self.rerank, **{"query": query, "docs": unique_rs, "top_k": kb_config.top_k}))
-    else:
-        rs.extend(sorted(unique_rs,
-                         key=lambda d: d.metadata.get("score", 0),
-                         reverse=True)[:kb_config.top_k])
-```
-
-```python
-# api/app/core/rag/nlp/search.py:236-261（同等逻辑的同步版）
-case _:
-    rs1 = vector_service.search_by_vector(...)
-    rs2 = vector_service.search_by_full_text(...)
-    seen_ids = set(); unique_rs = []
-    for doc in rs1 + rs2:
-        if doc.metadata["doc_id"] not in seen_ids:
-            seen_ids.add(doc.metadata["doc_id"])
-            unique_rs.append(doc)
-    rs = unique_rs
-    if unique_rs:
-        rs = vector_service.rerank(query=..., docs=unique_rs, top_k=...)
-```
-
-**融合公式**（路径 B）：
-
-```
-candidates = vector_topk(q, w_v) ∪ bm25_topk(q, w_t)         # 双路并发召回
-deduped    = unique_by(metadata.doc_id, candidates)           # 后到的丢弃
-if reranker:
-    final = reranker(query, deduped)[:top_k]                  # 跨编码器重排
-else:
-    final = sort_by_score_desc(deduped)[:top_k]               # 各自归一化分数直接比
-```
-
-> **why 不在路径 B 做加权融合**：路径 B 双路分数已分别归一化到 [0,1]，但"BM25 归一化分"与"cosine 归一化分"之间**不可比**（一个是相对最大分，一个是绝对几何相似度）。直接把它们排序虽然不严谨，但通常依赖下游的 cross-encoder reranker 做最终排序，因此前置阶段以"召回多样性"为优先（vector 主召回 + BM25 补关键词），不再做权重融合。
-
-### 6.7 兜底：低召回 fallback
-
-```python
-# api/app/core/rag/nlp/search.py:447-459
-# If result is empty, try again with lower min_match
-if total == 0:
-    if filters.get("document_id"):
-        # 限定文档场景下，直接退化为"无关键词"召回
-        res = self.dataStore.search(src, [], filters, [], orderBy, offset, limit, idx_names, kb_ids)
-        total = self.dataStore.getTotal(res)
-    else:
-        matchText, _ = self.qryr.question(qst, min_match=0.1)    # 0.3 -> 0.1
-        matchDense.extra_options["similarity"] = 0.17            # 0.1 -> 0.17（提高语义阈值）
-        res = self.dataStore.search(src, highlightFields, filters,
-                                    [matchText, matchDense, fusionExpr],
-                                    orderBy, offset, limit, idx_names, kb_ids,
-                                    rank_feature=rank_feature)
-```
-
-> **设计意图**：第一轮严格匹配（min_match=0.3）保证精度；命中为 0 时放宽 BM25 但提高向量阈值，等价于"换主导侧"，避免空结果。
-
-### 6.8 Rerank：模型重排 + 应用层混合相似度
-
-`Dealer.rerank_by_model` 与 `Dealer.rerank` 是两套 reranker：
-
-```python
-# api/app/core/rag/nlp/search.py:606-666
-def rerank(self, sres, query, tkweight=0.3, vtweight=0.7, ...):
-    sim, tksim, vtsim = self.qryr.hybrid_similarity(
-        sres.query_vector, ins_embd, keywords, ins_tw, tkweight, vtweight)
-    return sim + rank_fea, tksim, vtsim
-
-def rerank_by_model(self, rerank_mdl, sres, query, tkweight=0.3, vtweight=0.7, ...):
-    tksim = self.qryr.token_similarity(keywords, ins_tw)
-    vtsim, _ = rerank_mdl.similarity(query, [...])
-    return tkweight * (np.array(tksim) + rank_fea) + vtweight * vtsim, tksim, vtsim
-```
-
-```python
-# api/app/core/rag/nlp/query.py:203-211
-def hybrid_similarity(self, avec, bvecs, atks, btkss, tkweight=0.3, vtweight=0.7):
-    sims = CosineSimilarity([avec], bvecs)
-    tksim = self.token_similarity(atks, btkss)
-    if np.sum(sims[0]) == 0:
-        return np.array(tksim), tksim, sims[0]
-    return np.array(sims[0]) * vtweight + np.array(tksim) * tkweight, tksim, sims[0]
-```
-
-应用层重排公式：
-
-```
-final_score = vtweight * cosine(q_vec, c_vec) + tkweight * token_sim(q, c) + rank_feature_score
-            ≈ 0.7      * vector_sim          + 0.3       * keyword_sim    + (PageRank + tag)
-```
-
-注意 `Dealer.retrieval()`（674-768 行）调用时传入的是 `1 - vector_similarity_weight, vector_similarity_weight`，所以这两个权重由调用方（用户配置）决定，默认 0.3 / 0.7（`vector_similarity_weight=0.3` 见 678 行）。
-
-### 6.9 top_k / 召回率 / 延迟权衡
-
-| 阶段 | 默认值 | 含义 | 调参建议 |
-| --- | --- | --- | --- |
-| `top_k` (KB 节点) | 工作流配置 | 单 KB 单路召回数 | hybrid 模式建议 ≥ 50；语义高质 KB 可 30 |
-| `topn` / `topk` (Dealer) | 1024 (ann fallback)，10 (默认) | knn 阶段 k | 与下游 RERANK_LIMIT 联动 |
-| `num_candidates` | `topn * 2` (es_conn.py:213) | HNSW 候选数，影响召回率 | 高召回场景改为 `4 * topn` |
-| `RERANK_LIMIT` | `ceil(64/page_size)*page_size` (search.py:683) | rerank 输入数 | 与显示页大小绑定，避免 rerank 过多 |
-| `score_threshold` (BM25) | 0.2 | 归一化后阈值 | 关键词强场景可调到 0.3 |
-| `score_threshold` (vector) | 0.3 | (cos+1)/2 后阈值 | 严苛去噪可到 0.5 |
-| `min_match` | 0.3，fallback 0.1 | BM25 词命中比 | 短查询调高，长查询调低 |
-| `request_timeout` | 30s | ES 客户端超时 | 高并发下 60s |
-| `search timeout` | "600s" (es_conn.py:257) | ES 服务端超时 | 超长 KB 才放宽 |
-
----
-
-## 七、配置项与运维要点
-
-### 7.1 环境变量（连接 + 客户端调优）
-
-```python
-# api/app/core/rag/utils/es_conn.py:60-80
-# api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:685-710
-ELASTICSEARCH_HOST                  # 默认 127.0.0.1，可填 http://es-1 / https://es-1
-ELASTICSEARCH_PORT                  # 默认 9200
-ELASTICSEARCH_USERNAME              # 默认 elastic
-ELASTICSEARCH_PASSWORD              # 默认 elastic
-ELASTICSEARCH_REQUEST_TIMEOUT       # 默认 30 (秒)
-ELASTICSEARCH_RETRY_ON_TIMEOUT      # 默认 True (es_conn 中是字符串比较，注意 bug 见下)
-ELASTICSEARCH_MAX_RETRIES           # 默认 3
-ELASTICSEARCH_VERIFY_CERTS          # 默认 false
-ELASTICSEARCH_CA_CERTS              # 自签证书路径
-ELASTICSEARCH_CONNECTIONS_PER_NODE  # 路径 B 独有，默认 10
-```
-
-> **小坑**：`es_conn.py:72` 写的是 `os.getenv("ELASTICSEARCH_RETRY_ON_TIMEOUT", True) == "true"`——默认值是 bool `True`，但与字符串 `"true"` 比较恒为 `False`。所以**默认情况下其实没开启 retry_on_timeout**，需要显式设置 `ELASTICSEARCH_RETRY_ON_TIMEOUT=true`（小写）才生效。
-
-### 7.2 ES 集群规模建议
-
-按 `mapping.json` 默认 2 shards、0 replicas，**不可直接用于生产**。建议：
-
-| 数据量 | 节点数 | shards | replicas | heap | 备注 |
-| --- | --- | --- | --- | --- | --- |
-| < 100w chunks | 1-3 | 2 | 1 | 8GB | 默认配置 + 1 副本 |
-| 100w-1000w | 3-5 | 4-8 | 1 | 16GB | 增加 shard 减少单 shard 体积 |
-| > 1000w | 5+ | 8-16 | 1-2 | 31GB(不超过 32) | shard 大小控制在 30-50GB |
-
-**核心准则**：
-
-- 单 shard 不超过 50GB；
-- replicas ≥ 1，至少容忍 1 节点宕机；
-- JVM heap 不超过 32GB（zero-based compressed oops）；
-- 留 50% RAM 给 OS file cache（lucene 依赖 mmap）。
-
-### 7.3 索引膨胀治理
-
-观察点：
-
-- **路径 A 的 `graphrag_{workspace_id}` 索引**：随 workspace chunk 数增长，`number_of_shards=2` 容易超过 50GB/shard。需要按"workspace 容量分层"，对热门/大 workspace 单独 reindex 到更多 shards。
-- **路径 B 的 `Vector_index_{kb_id}_Node` 索引**：每 KB 一个 index，KB 数 1000+ 时 cluster state 显著膨胀，可能拖慢所有索引创建/查询。建议引入"KB 共享索引 + kb_id 路由"模式（详见 §8 优化建议）。
-
-```python
-# api/app/core/rag/utils/es_conn.py:587-633
-def get_cluster_stats(self):
-    """
-    暴露 store_size / docs / nodes_version / jvm_heap_used 等用于 dashboard
-    """
-    raw_stats = self.es.cluster.stats()
-    return {...}
-```
-
-> **建议**：在调度器里定时拉取 `get_cluster_stats()`，把 `store_size / docs / heap_used_percent` 接入告警。
-
-### 7.4 慢查询排查
-
-```python
-# api/app/core/rag/utils/es_conn.py:250-263
-logger.debug(f"ESConnection.search {str(indexNames)} query: " + json.dumps(q))
-res = self.es.search(index=indexNames, body=q, timeout="600s",
-                     # search_type="dfs_query_then_fetch",
-                     track_total_hits=True, _source=True)
-```
-
-排查路径：
-
-1. **打开 debug 日志**：`logger=rag.es_conn` 调到 DEBUG，可以看到完整 DSL。
-2. **关闭 `track_total_hits=True`**：超过 10000 hits 时它会真正扫表，对大 KB 是常见慢点；如果不需要精确总数，改为 `track_total_hits=10000`。
-3. **打开 `dfs_query_then_fetch`**：在多 shard 时让 IDF 全局计算，对相关性更准；代价是一次 RTT。
-4. **限制 `num_candidates`**：HNSW 阶段候选数大幅影响延迟；已是 `topn * 2`，进一步压缩到 `topn` 可观察延迟下降。
-5. **slow log**：在 ES 集群层面打开 `index.search.slowlog.threshold.query.warn: 1s`，定位单查询慢点。
-
-### 7.5 健康监控接口
-
-```python
-# api/app/core/rag/utils/es_conn.py:95-98
-def health(self) -> dict:
-    health_dict = dict(self.es.cluster.health())
-    health_dict["type"] = "elasticsearch"
-    return health_dict
-```
-
-```python
-# api/app/core/rag/utils/doc_store_conn.py:140-145
-@abstractmethod
-def health(self) -> dict:
-    """Return the health status of the database."""
-```
-
-接入业务监控的最简方法：起一个轻量 endpoint 调用 `docStoreConn.health()`，把 `status (green/yellow/red)`、`number_of_nodes`、`active_shards_percent_as_number` 上报。
-
----
-
-## 八、边界条件与已知限制
-
-| 限制 | 影响 | 解决方向 |
-| --- | --- | --- |
-| 路径 B `dims = len(embeddings[0])` 锁定维度 | 换 embedding 模型必须重建索引 | 按维度后缀命名向量字段（参考路径 A 的 `q_{dim}_vec`）|
-| 路径 A 默认 0 副本 | 节点宕机即数据丢失 | 修改 `res/mapping.json` `number_of_replicas: 1` |
-| `ELASTICSEARCH_RETRY_ON_TIMEOUT` 默认未生效 | 网络抖动直接抛错 | bug：bool 与 "true" 字符串比较；需显式 `=true` |
-| `script_score` 暴力扫描 | 大 KB 延迟高 | 路径 B 升级到 `knn` query（ES 8 原生）|
-| 路径 B inline mapping 不带 metadata.kb_id | 多 KB 共享索引时无法过滤 | 与路径 A 对齐，引入 `kb_id` keyword |
-| `update_by_segment` 无并发控制 | 并发更新最后写入胜出 | 走 `delete_by_ids` + `add_chunks` 或显式版本号 |
-| `add_texts` 不捕获 `BulkIndexError` | 局部失败整批失败 | 增加 try/except + 失败重投队列 |
-| 一个 workspace 多 KB 共享路径 A 索引 | 单 KB 删除走 delete-by-query，不立即释放磁盘 | 定期 `_forcemerge?only_expunge_deletes=true` |
-| 路径 B 每 KB 一索引 | 大量 KB 时 cluster state 膨胀 | 改为共享索引 + `kb_id` routing |
-| `track_total_hits=True` | 大库 search 全表扫描慢 | 默认改为 10000，按需取 max |
-
----
-
-## 九、监控指标与排错指引
-
-### 9.1 关键指标
-
-| 指标 | 来源 | 告警阈值（参考）|
-| --- | --- | --- |
-| ES cluster status | `health()` | red 立即告警 |
-| `active_shards_percent_as_number` | `health()` | < 100% 持续 5min 告警 |
-| `jvm_heap_used_percent` | `get_cluster_stats()` | > 75% 警告，> 85% 紧急 |
-| `os_mem_used_percent` | `get_cluster_stats()` | > 90% 警告 |
-| 写入失败比例 | `ESConnection.insert` 返回的 `res` 列表长度 / 总 chunk 数 | > 1% 告警 |
-| 单次 search P95 延迟 | 调用方时序日志 | hybrid > 1s 告警 |
-| `track_total_hits` 命中超过 10k 比例 | search.py 总数 | 频繁触发即扩 shard |
-
-### 9.2 典型故障与处理
-
-| 现象 | 可能原因 | 处置 |
-| --- | --- | --- |
-| 写入超时 | bulk 太大 / refresh 阻塞 | 减小 batch（≤ 1000）/ 写入窗口 `refresh_interval=30s` |
-| 检索召回为 0 | min_match 过严 / kb_id 过滤不一致 | 看 search.py:447 fallback 是否触发；核对 kb_id |
-| HNSW 召回率低 | num_candidates 过小 | 增大到 `4 * topn` 或 `topn * 4` |
-| 维度不匹配报错 | 换 embedding 模型未 reindex | 按 §8 维度限制处理；或在路径 B 删 KB 重建 |
-| cluster state 过大 | KB 索引数过多 | §10 改造为共享索引 + kb_id routing |
-| 中文检索召回差 | 写入 analyzer 与查询 analyzer 不一致 | 路径 B 必须保持 `ik_max_word`（写入与查询）|
-
----
-
-## 十、优化建议与未来扩展点
-
-### 10.1 架构改造（短期，1-2 个迭代）
-
-1. **统一双路径**：保留路径 A 抽象 (`DocStoreConnection` + `Dealer`)，把路径 B 的 `ElasticSearchVector` 重构为 `DocStoreConnection` 的薄封装，删除重复的连接管理 (`ElasticSearchVectorFactory`)，全局只用 `@singleton ESConnection`。
-2. **修复默认配置**：
-   - `mapping.json` `number_of_replicas: 0 → 1`；
-   - 修正 `ELASTICSEARCH_RETRY_ON_TIMEOUT` bool/str 比较；
-   - 路径 B 的 `script_score` 切换为 `knn` query；
-   - 路径 B mapping 加上 `kb_id` keyword 字段，为后续合并索引铺路。
-3. **共享索引 + 路由**：把 `Vector_index_{kb_id}_Node` 改为 `kb_chunks_{workspace_id}` 共享索引，`kb_id` 字段做 routing key，索引数从 N(KB) 降到 N(workspace)。
-
-### 10.2 检索增强（中期）
-
-1. **真正的 RRF**（reciprocal rank fusion）：当前 `weighted_sum` 对分数尺度敏感，引入 `rank_fusion` (ES 8.8+) 或在应用层实现 `rrf_score(d) = Σ 1/(k + rank_i(d))`，对尺度不敏感。
-2. **稀疏向量（ELSER / SPLADE）**：路径 A 已在 `MatchSparseExpr` 接口预留位置，但 ES 实现未启用 `rank_features` 稀疏检索，引入后可在中文长尾查询上显著提升召回。
-3. **多模态检索**：路径 B 已感知 `is_multimodal_embedding`（`elasticsearch_vector.py:41`），但只针对火山引擎；引入跨模态 BGE-M3 类模型后，可在同一 dense_vector 字段上做"图文混排"。
-4. **HNSW 参数显式化**：`mapping.json` 没有指定 `index_options`（m / ef_construction）。在构建大索引时显式 `m=16, ef_construction=200` 可显著提升召回率。
-
-### 10.3 工程鲁棒性（中期）
-
-1. **写入幂等保护**：路径 B `add_texts` 不传 `_id`，依赖 `metadata.doc_id` 后查；改为直接用 `doc_id` 作为 `_id`，写入即可幂等，省去后查。
-2. **变更检测 reindex**：当 mapping 变化时，加一个 `migration_version` 字段触发 alias-swap reindex（`old_index → new_index`），避免线上停机重建。
-3. **批量限流**：`helpers.bulk` 默认无背压，引入 `chunk_size=500, max_chunk_bytes=10MB` 显式限制，避免大 chunk 撑爆 ES heap。
-4. **路径 A 的 `ATTEMPT_TIME=2`** 太少：网络抖动 2 次重试后丢错，建议升到 3-5 次，配合指数退避。
-
-### 10.4 长期扩展点
-
-1. **冷热分离**：超过半年/低访问的 chunk 迁到冷节点（warm tier）+ rollover index，配合"记忆遗忘引擎" (Memory Forgetting Engine, README §4) 协同。
-2. **跨集群联邦**：当多 workspace 数据量过大，引入 cross-cluster search（CCS）按 workspace 切集群。
-3. **GraphRAG 与 VDB 联合检索**：当前 `kg_retriever.retrieval` 在路径 B 是后置 insert（node.py:286-298），可改为"先图谱召回相关实体 → 把实体名作为 `important_kwd^30` 注入 BM25"实现一次 ES 调用同时享受图谱与向量。
-
----
-
-## 十一、关键源码片段索引（评审检查点）
-
-| 主题 | 文件:行号 | 一句话说明 |
-| --- | --- | --- |
-| 抽象接口 | `api/app/core/rag/utils/doc_store_conn.py:128-256` | `DocStoreConnection` 14 个抽象方法 |
-| MatchExpr 族 | `api/app/core/rag/utils/doc_store_conn.py:43-114` | 文本/稠密/稀疏/张量/融合表达式 |
-| ES 连接管理 | `api/app/core/rag/utils/es_conn.py:26-86` | `@singleton` + 8.x 版本校验 |
-| 全局 mapping | `api/app/core/rag/res/mapping.json:1-211` | dynamic_templates + 自定义 BM25 |
-| ES 8 hybrid 核心 | `api/app/core/rag/utils/es_conn.py:186-218` | `query_string` + `s.knn(...)` 共享 filter |
-| 加权融合 | `api/app/core/rag/utils/es_conn.py:188-194` 与 `api/app/core/rag/nlp/search.py:439` | `FusionExpr("weighted_sum", weights="0.05,0.95")` |
-| 应用层 hybrid_similarity | `api/app/core/rag/nlp/query.py:203-211` | `0.7*cos + 0.3*token_sim` |
-| 双路 + 去重 + rerank | `api/app/core/workflow/nodes/knowledge/node.py:236-271` | 工作流默认混合策略 |
-| BaseVector 抽象 | `api/app/core/rag/vdb/vector_base.py:9-67` | 路径 B 的接口骨架 |
-| KB 索引 mapping | `api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:609-663` | inline 创建 + dims 锁定 |
-| 关键词检索（BM25+IK）| `api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:468-558` | match + ik_max_word + 归一化 |
-| 向量检索（cosine 暴力）| `api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:374-466` | script_score + filter |
-| 关键词构造（多字段 + 同义词）| `api/app/core/rag/nlp/query.py:14-22, 69-201` | query_fields field-boost + synonym |
-| Dealer.retrieval (主入口) | `api/app/core/rag/nlp/search.py:674-768` | 检索 + rerank + 分页 |
-| 低召回 fallback | `api/app/core/rag/nlp/search.py:447-459` | min_match 0.3→0.1，similarity 0.1→0.17 |
-| update_by_query | `api/app/core/rag/utils/es_conn.py:332-422` | painless + slices=5 + conflicts=proceed |
-| bulk 写 + 错误处理 | `api/app/core/rag/utils/es_conn.py:294-330` | refresh=False + 两次重试 + 错误聚合 |
-| 工厂单例 (路径 B) | `api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py:666-732` | 双重检查锁 + 版本校验一次性 |
-| 全局初始化 | `api/app/core/rag/common/settings.py:13-24` | docStoreConn / retriever / kg_retriever |
-| 检索类型枚举 | `api/app/schemas/chunk_schema.py:8-13` | participle / semantic / hybrid / graph |
-
----
-
-## 十二、TL;DR（一段话总结）
-
-MemoryBear 用 Elasticsearch 8 同时承担**全文（Lucene + IK + 自定义 BM25）和向量（dense_vector + HNSW）**双引擎，所以选 ES 而不是专用向量库。代码里有**两套并行路径**：路径 A `ESConnection`（单例 `DocStoreConnection`，多字段动态模板，配 `Dealer` 做 `weighted_sum=0.05,0.95` 的应用层加权 + ES 原生 hybrid 与 rank_features，主要给 GraphRAG/复杂 RAG 用）；路径 B `ElasticSearchVector`（`BaseVector` 简化封装，`script_score+cosine` 与 `match+ik_max_word`，主要给工作流知识节点和 KB 服务用，hybrid 走"双路并发 → metadata.doc_id 去重 → 可选 reranker"）。索引按 workspace 或按 KB 隔离，`mapping.json` 默认 2 shards / 0 副本 / 1s refresh，向量字段按维度后缀（512/768/1024/1536）动态创建，文本字段以 `_tks/_ltks/_kwd` 后缀套用 dynamic_templates。生产化的主要风险点：路径 B 锁死 dims、默认 0 副本、`ELASTICSEARCH_RETRY_ON_TIMEOUT` 比较 bug、`script_score` 暴力扫描、KB 索引数膨胀；优化方向是合并双路径、改用 `knn` + RRF、共享索引 + `kb_id` routing、配合 GraphRAG 做联合检索。

docs/rag/pipeline/04-graphrag.md

@@ -1,991 +0,0 @@
-# GraphRAG（light + general）实现详解
-
-| 元数据 | 值 |
-|---|---|
-| 环节编号 | 05-graphrag |
-| 源码目录 | `api/app/core/rag/graphrag/` |
-| 关联任务 | [WS-11](mention://issue/6c0b5472-a0fa-4997-925c-a67f235f82da) / [S2-T4](mention://issue/16bdb196-e10e-489b-b01c-9067b1f1bb23) |
-| 依赖输入 | [S2-T2] Embedding、[S2-T3] VDB、[S1-T2] 架构图 |
-| 输出下游 | [S3-T2] 知识图谱增强 |
-
----
-
-## 1. 一句话定位
-
-GraphRAG 是 MemoryBear 知识库系统的**知识图谱增强检索模块**，通过 LLM 从文档中抽取实体-关系三元组构建知识图谱，在检索阶段利用图谱结构（实体关联、社区报告、多跳路径）补充传统向量检索的语义盲区，实现"结构化知识 + 语义向量"的混合召回。
-
----
-
-## 2. 设计目标与适用场景
-
-### 2.1 设计目标
-
-1. **结构化知识补充**：向量检索擅长语义匹配，但对"多跳推理""实体关系推导""全局摘要"等场景覆盖不足。GraphRAG 通过显式构建实体关系图谱填补这一 gap。
-2. **两种精度-成本档位**：
-   - **Light 模式**（默认）：基于 LightRAG 思路，轻量快速，适合对延迟敏感、文档规模中等的场景。
-   - **General 模式**（完整版）：基于 Microsoft GraphRAG，支持实体消歧、社区发现、社区报告生成，适合需要深度分析、复杂推理的场景。
-3. **与现有基础设施复用**：不引入 Neo4j 等独立图数据库，复用 Elasticsearch 作为图谱存储，降低运维复杂度。
-
-### 2.2 适用场景
-
-| 场景 | 推荐模式 | 原因 |
-|---|---|---|
-| 快速知识问答，文档 < 1K | Light | 建图快、成本低 |
-| 企业级知识库，文档 > 10K | General | 实体消歧 + 社区报告提供全局洞察 |
-| 需要跨文档实体关联分析 | General | 实体消歧合并跨文档同名实体 |
-| 需要"某实体的全局影响力"评估 | General | 社区报告 + PageRank 提供全局视角 |
-| 实时对话/低延迟检索 | Light | General 的社区报告生成耗时高 |
-
----
-
-## 3. 关键概念与术语表
-
-| 术语 | 定义 |
-|---|---|
-| **Entity（实体）** | 从文本中抽取的命名对象，如人名、组织、地点。在代码中存储为图的节点。 |
-| **Relationship（关系）** | 实体之间的语义关联，如"A 是 B 的 CEO"。存储为图的边。 |
-| **Subgraph（子图）** | 单个文档抽取出的局部知识图谱，最终合并为全局图谱。 |
-| **Entity Resolution（实体消歧）** | 识别图谱中不同名称但指向同一实体的节点，将其合并（如 "Apple Inc." vs "Apple"）。 |
-| **Community（社区）** | 图谱中高密度连接的节点簇，通过 Leiden 算法发现。 |
-| **Community Report（社区报告）** | 对单个社区的 LLM 生成的结构化摘要报告，含标题、摘要、影响力评级、关键发现。 |
-| **PageRank** | 用于衡量实体在图谱中的重要程度，检索时作为排序因子之一。 |
-| **N-hop Path** | 从查询实体出发，沿图谱边行走 N 步可达的实体路径，用于扩展召回。 |
-| **Tuple Delimiter** | 实体/关系抽取输出中的字段分隔符，代码中为 `<\|>`。 |
-| **Record Delimiter** | 抽取输出中多条记录的分隔符，代码中为 `##`。 |
-| **knowledge_graph_kwd** | ES 文档中的类型标记字段，取值：`entity` / `relation` / `graph` / `subgraph` / `community_report` / `ty2ents`。 |
-
----
-
-## 4. 实现概览
-
-### 4.1 模块结构
-
-```
-api/app/core/rag/graphrag/
-├── search.py                          # KGSearch：图谱检索入口
-├── entity_resolution.py               # 实体消歧（LLM + 编辑距离）
-├── entity_resolution_prompt.py        # 实体消歧 Prompt
-├── query_analyze_prompt.py            # 查询分析 Prompt（MiniRAG 风格）
-├── utils.py                           # 图操作工具集（merge、cache、ES 读写）
-├── __init__.py
-├── light/
-│   ├── graph_extractor.py             # Light 版实体/关系抽取器
-│   └── graph_prompt.py                # Light 版抽取 Prompt + RAG 回答 Prompt
-└── general/
-    ├── extractor.py                   # 通用抽取基类（LLM 调用、节点/边合并）
-    ├── graph_extractor.py             # General 版实体/关系抽取器
-    ├── graph_prompt.py                # General 版抽取 Prompt
-    ├── index.py                       # GraphRAG 建图总控（子图生成→合并→消歧→社区报告）
-    ├── entity_embedding.py            # Node2Vec 实体嵌入（备用）
-    ├── leiden.py                      # Leiden 社区发现算法封装
-    ├── community_reports_extractor.py # 社区报告抽取器
-    ├── community_report_prompt.py     # 社区报告生成 Prompt
-    ├── mind_map_extractor.py          # 思维导图抽取器
-    └── mind_map_prompt.py             # 思维导图 Prompt
-```
-
-### 4.2 建图时序图
-
-```mermaid
-sequenceDiagram
-    participant U as 用户/任务
-    participant T as tasks.py<br/>(Celery Task)
-    participant I as general/index.py<br/>run_graphrag/run_graphrag_for_kb
-    participant E as light/general<br/>GraphExtractor
-    participant ES as Elasticsearch<br/>(Doc Store)
-    participant ER as entity_resolution.py<br/>EntityResolution
-    participant CR as community_reports_extractor.py<br/>CommunityReportsExtractor
-
-    U->>T: 上传文档 / 触发建图
-    T->>I: run_graphrag_for_kb(document_ids, parser_config)
-    I->>I: load_doc_chunks()<br/>按 1024 token 合并 chunk
-    loop 每个文档并行（max 4）
-        I->>E: generate_subgraph(extractor, chunks)
-        E->>E: LLM 抽取 entities + relations<br/>(多轮 gleaning)
-        E->>E: 解析输出 → nx.Graph
-        E->>ES: 写入 subgraph (knowledge_graph_kwd="subgraph")
-    end
-    I->>I: merge_subgraph()<br/>逐个文档合并子图到全局图
-    I->>ES: 写入全局 graph (knowledge_graph_kwd="graph")
-    I->>ES: 写入 entity/relation chunks<br/>(带向量嵌入)
-
-    alt with_resolution=true (General 可选)
-        I->>ER: resolve_entities(graph, subgraph_nodes)
-        ER->>ER: 编辑距离预筛选候选对
-        ER->>ER: LLM 批量判断"是否同一实体"
-        ER->>ER: 合并连通分量中的节点
-        ER->>ER: 重新计算 PageRank
-        ER->>ES: 更新 graph/entity/relation
-    end
-
-    alt with_community=true (General 可选)
-        I->>CR: extract_community(graph)
-        CR->>CR: Leiden 社区发现
-        CR->>CR: LLM 生成每个社区的报告<br/>(title/summary/rating/findings)
-        CR->>ES: 写入 community_report chunks
-    end
-    I-->>T: 返回 {ok_documents, failed_documents, seconds}
-```
-
-### 4.3 查图时序图
-
-```mermaid
-sequenceDiagram
-    participant U as 用户 Query
-    participant S as search.py<br/>KGSearch.retrieval()
-    participant QP as query_analyze_prompt.py<br/>minirag_query2kwd
-    participant ES as Elasticsearch
-    participant LLM as LLM
-
-    U->>S: retrieval(question, workspace_ids, kb_ids, ...)
-    S->>LLM: query_rewrite()<br/>PROMPTS["minirag_query2kwd"]
-    LLM-->>S: {answer_type_keywords, entities_from_query}
-
-    par 三路召回并行
-        S->>ES: get_relevant_ents_by_keywords()<br/>向量相似度搜索 entity
-        ES-->>S: 候选实体列表 + sim + pagerank + n_hop
-        S->>ES: get_relevant_ents_by_types()<br/>按类型过滤 entity
-        ES-->>S: 类型匹配实体列表
-        S->>ES: get_relevant_relations_by_txt()<br/>向量相似度搜索 relation
-        ES-->>S: 候选关系列表
-    end
-
-    S->>S: 计算 n-hop 路径权重衰减<br/>sim / (2 + hop_depth)
-    S->>S: 实体排序：sim × pagerank<br/>关系排序：sim × pagerank × boost
-    S->>S: Token 预算截断（max_token 递减）
-
-    alt 社区报告召回
-        S->>ES: _community_retrieval_()<br/>按 entities_kwd 匹配 community_report
-        ES-->>S: 社区报告文本
-    end
-
-    S-->>U: {page_content: Entities + Relations + Community Reports,<br/>metadata, vector: None}
-```
-
----
-
-## 5. 关键源码详解
-
-### 5.1 图谱构建链路
-
-#### 5.1.1 建图总控入口
-
-**文件**: `api/app/core/rag/graphrag/general/index.py:36-119`
-
-```python
-async def run_graphrag(
-    row: dict, language, with_resolution: bool, with_community: bool,
-    chat_model, embedding_model, callback,
-):
-    # 选择抽取器：LightKGExt（默认）或 GeneralKGExt
-    extractor = LightKGExt if method != "general" else GeneralKGExt
-    subgraph = await generate_subgraph(extractor, workspace_id, kb_id, document_id, chunks, ...)
-    new_graph = await merge_subgraph(workspace_id, kb_id, document_id, subgraph, embedding_model, callback)
-    if with_resolution:
-        await resolve_entities(new_graph, subgraph_nodes, ...)
-    if with_community:
-        await extract_community(new_graph, ...)
-```
-
-**设计要点**：
-- `parser_config["graphrag"]["method"]` 控制 Light/General 切换（`"general"` 为 General，其他为 Light）。
-- `with_resolution` 和 `with_community` 为独立开关，仅在 General 模式下有意义（Light 不支持）。
-- 使用 `RedisDistributedLock` 保证同一 KB 的并发建图安全。
-
-#### 5.1.2 子图生成
-
-**文件**: `api/app/core/rag/graphrag/general/index.py:333-406`
-
-```python
-async def generate_subgraph(extractor, workspace_id, kb_id, document_id, chunks, ...):
-    # 幂等检查：如果 document_id 已在图中，跳过
-    contains = await does_graph_contains(workspace_id, kb_id, document_id)
-    if contains:
-        return None
-    ext = extractor(llm_bdl, language=language, entity_types=entity_types)
-    ents, rels = await ext(document_id, chunks, callback, task_id=task_id)
-    subgraph = nx.Graph()
-    for ent in ents:
-        subgraph.add_node(ent["entity_name"], **ent)
-    for rel in rels:
-        if subgraph.has_node(rel["src_id"]) and subgraph.has_node(rel["tgt_id"]):
-            subgraph.add_edge(rel["src_id"], rel["tgt_id"], **rel)
-    tidy_graph(subgraph, callback, check_attribute=False)
-    # 写入 ES 作为 subgraph 类型文档
-    await trio.to_thread.run_sync(settings.docStoreConn.insert, [chunk], ...)
-    return subgraph
-```
-
-**关键设计**：
-- `does_graph_contains()` 通过查询 `knowledge_graph_kwd="graph"` 的 `source_id` 字段实现幂等性。
-- `tidy_graph()` 清理无 description/source_id 的脏节点/边。
-- 每个文档的 subgraph 独立存储，便于增量更新和重建。
-
-#### 5.1.3 实体/关系抽取（Light vs General）
-
-**Light 版抽取器**
-
-**文件**: `api/app/core/rag/graphrag/light/graph_extractor.py:31-132`
-
-```python
-class GraphExtractor(Extractor):
-    def __init__(self, llm_invoker, language="English", entity_types=None,
-                 example_number=2, max_gleanings=None):
-        # 使用 LightRAG 风格的 Prompt
-        self._entity_extract_prompt = PROMPTS["entity_extraction"]
-        self._continue_prompt = PROMPTS["entity_continue_extraction"]
-        self._if_loop_prompt = PROMPTS["entity_if_loop_extraction"]
-        # 预留 60% token 给输入文本
-        self._left_token_count = max(getattr(llm_invoker, 'max_length', 8096) * 0.6, ...)
-
-    async def _process_single_content(self, chunk_key_dp, chunk_seq, num_chunks, out_results, task_id=""):
-        hint_prompt = self._entity_extract_prompt.format(**self._context_base, input_text=content)
-        # 首轮抽取
-        final_result = await trio.to_thread.run_sync(self._chat, "", [{"role": "user", "content": hint_prompt}], {}, task_id)
-        # 多轮 gleaning：追问"还有遗漏吗？"
-        for now_glean_index in range(self._max_gleanings):
-            glean_result = await trio.to_thread.run_sync(self._chat, "", history, gen_conf, task_id)
-            final_result += glean_result
-            # 用 if_loop_prompt 判断是否继续
-            if_loop_result = await trio.to_thread.run_sync(self._chat, "", history, gen_conf, task_id)
-            if if_loop_result.strip().lower() != "yes":
-                break
-```
-
-**General 版抽取器**
-
-**文件**: `api/app/core/rag/graphrag/general/graph_extractor.py:34-151`
-
-```python
-class GraphExtractor(Extractor):
-    def __init__(self, llm_invoker, language="English", entity_types=None, ...):
-        self._extraction_prompt = GRAPH_EXTRACTION_PROMPT
-        self._max_gleanings = max_gleanings or ENTITY_EXTRACTION_MAX_GLEANINGS
-        # 使用 tiktoken 构造 logit_bias 强制输出 YES/NO
-        encoding = tiktoken.get_encoding("cl100k_base")
-        yes = encoding.encode("YES")
-        no = encoding.encode("NO")
-        self._loop_args = {"logit_bias": {yes[0]: 100, no[0]: 100}, "max_tokens": 1}
-
-    async def _process_single_content(self, chunk_key_dp, chunk_seq, num_chunks, out_results, task_id=""):
-        # 类似 Light，但使用 CONTINUE_PROMPT + LOOP_PROMPT
-        for i in range(self._max_gleanings):
-            history.append({"role": "user", "content": CONTINUE_PROMPT})
-            response = await trio.to_thread.run_sync(lambda: self._chat("", history, {}))
-            if i >= self._max_gleanings - 1:
-                break
-            history.append({"role": "assistant", "content": response})
-            history.append({"role": "user", "content": LOOP_PROMPT})
-            continuation = await trio.to_thread.run_sync(lambda: self._chat("", history))
-            if continuation != "Y":
-                break
-```
-
-**Light vs General 抽取差异**：
-
-| 维度 | Light | General |
-|---|---|---|
-| Prompt 风格 | LightRAG（更详细的示例 + content_keywords） | MS GraphRAG（简洁 + 无 keywords） |
-| Gleaning 终止 | 自然语言判断 `"yes"/"no"` | 强制单字 `"Y"`（logit_bias） |
-| 示例数量 | 默认 3 个，可调 `example_number` | 固定 3 个 |
-| 输出格式 | 含 `content_keywords` 元组 | 仅 entity + relationship |
-
-#### 5.1.4 节点/边合并与摘要
-
-**文件**: `api/app/core/rag/graphrag/general/extractor.py:205-300`
-
-```python
-async def _merge_nodes(self, entity_name, entities, all_relationships_data, task_id=""):
-    # 投票决定实体类型（出现次数最多者）
-    entity_type = sorted(Counter([dp["entity_type"] for dp in entities]).items(), key=lambda x: x[1], reverse=True)[0][0]
-    # 去重合并所有描述
-    description = GRAPH_FIELD_SEP.join(sorted(set([dp["description"] for dp in entities])))
-    # LLM 摘要（描述超过 12 条时触发）
-    description = await self._handle_entity_relation_summary(entity_name, description, task_id=task_id)
-    node_data = dict(entity_type=entity_type, description=description, source_id=already_source_ids)
-    all_relationships_data.append(node_data)
-
-async def _handle_entity_relation_summary(self, entity_or_relation_name, description, task_id=""):
-    description_list = use_description.split(GRAPH_FIELD_SEP)
-    if len(description_list) <= 12:
-        return use_description  # 描述较少时不摘要
-    # 触发 LLM 摘要
-    async with chat_limiter:
-        summary = await trio.to_thread.run_sync(self._chat, "", [{"role": "user", "content": use_prompt}], {}, task_id)
-    return summary
-```
-
-**设计要点**：
-- 同一实体名在不同 chunk 中的描述用 `<SEP>` 拼接，超过 12 条触发 LLM 摘要，防止描述无限膨胀。
-- 关系合并同理：权重累加、关键词去重并集、描述拼接摘要。
-
-#### 5.1.5 子图合并到全局图
-
-**文件**: `api/app/core/rag/graphrag/utils.py:199-229`
-
-```python
-def graph_merge(g1: nx.Graph, g2: nx.Graph, change: GraphChange):
-    """Merge graph g2 into g1 in place."""
-    for node_name, attr in g2.nodes(data=True):
-        change.added_updated_nodes.add(node_name)
-        if not g1.has_node(node_name):
-            g1.add_node(node_name, **attr)
-            continue
-        # 已存在：描述追加、source_id 合并
-        node = g1.nodes[node_name]
-        node["description"] += GRAPH_FIELD_SEP + attr["description"]
-        node["source_id"] += attr["source_id"]
-
-    for source, target, attr in g2.edges(data=True):
-        change.added_updated_edges.add(get_from_to(source, target))
-        edge = g1.get_edge_data(source, target)
-        if edge is None:
-            g1.add_edge(source, target, **attr)
-            continue
-        # 已存在：权重累加、描述追加
-        edge["weight"] += attr.get("weight", 0)
-        edge["description"] += GRAPH_FIELD_SEP + attr["description"]
-        edge["keywords"] += attr["keywords"]
-        edge["source_id"] += attr["source_id"]
-
-    # 更新度中心性（rank）
-    for node_degree in g1.degree:
-        g1.nodes[str(node_degree[0])]["rank"] = int(node_degree[1])
-```
-
-#### 5.1.6 实体消歧
-
-**文件**: `api/app/core/rag/graphrag/entity_resolution.py:31-141`
-
-```python
-class EntityResolution(Extractor):
-    async def __call__(self, graph, subgraph_nodes, prompt_variables=None, callback=None, task_id=""):
-        # 1. 按 entity_type 分组
-        node_clusters = {entity_type: [] for entity_type in entity_types}
-        for node in nodes:
-            node_clusters[graph.nodes[node].get('entity_type', '-')].append(node)
-
-        # 2. 生成候选对（组合数限制 + 编辑距离预筛选）
-        for k, v in node_clusters.items():
-            candidate_resolution[k] = [(a, b) for a, b in itertools.combinations(v, 2)
-                if (a in subgraph_nodes or b in subgraph_nodes) and self.is_similarity(a, b)]
-
-        # 3. LLM 批量判断（batch=100，并发=5，trio 协程）
-        async def limited_resolve_candidate(candidate_batch, result_set, result_lock):
-            async with semaphore:
-                await self._resolve_candidate(candidate_batch, result_set, result_lock, task_id)
-
-        # 4. 合并连通分量
-        connect_graph = nx.Graph()
-        connect_graph.add_edges_from(resolution_result)
-        for sub_connect_graph in nx.connected_components(connect_graph):
-            merging_nodes = list(sub_connect_graph)
-            await self._merge_graph_nodes(graph, merging_nodes, change, task_id)
-
-        # 5. 重新计算 PageRank
-        pr = nx.pagerank(graph)
-```
-
-**编辑距离预筛选算法**（`is_similarity`，第 225-239 行）：
-
-```python
-def is_similarity(self, a, b):
-    # 规则1：2-gram 差异中不能包含数字（避免 "Product 1" vs "Product 2" 被误判）
-    if self._has_digit_in_2gram_diff(a, b):
-        return False
-    # 规则2：英文用 editdistance，阈值 = min(len(a), len(b)) // 2
-    if is_english(a) and is_english(b):
-        return editdistance.eval(a, b) <= min(len(a), len(b)) // 2
-    # 规则3：中文/混合文本用字符集 Jaccard 相似度，阈值 0.8
-    a, b = set(a), set(b)
-    max_l = max(len(a), len(b))
-    if max_l < 4:
-        return len(a & b) > 1
-    return len(a & b) * 1. / max_l >= 0.8
-```
-
-**消歧流程设计意图**：
-1. **预筛选**：编辑距离过滤掉明显不同的实体对，减少 LLM 调用量（组合数从 O(n²) 降到可控范围）。
-2. **批量 LLM 判断**：每批 100 对，并发 5 个请求，timeout 280s（测试环境）或无限（生产环境）。
-3. **连通分量合并**：LLM 判定"A=B"和"B=C"后，即使 LLM 没直接判断"A=C"，通过连通分量也会将 A、B、C 合并。
-4. **任务取消支持**：每步检查 `has_canceled(task_id)`，支持用户中断长时任务。
-
-#### 5.1.7 社区发现与报告生成
-
-**文件**: `api/app/core/rag/graphrag/general/leiden.py:95-141`
-
-```python
-def run(graph, args):
-    max_cluster_size = args.get("max_cluster_size", 12)
-    use_lcc = args.get("use_lcc", True)
-    # 使用 graspologic 的 hierarchical_leiden
-    community_mapping = hierarchical_leiden(graph, max_cluster_size=max_cluster_size, random_seed=seed)
-    # 按层级组织社区，计算社区权重（节点 rank × weight 归一化）
-    for level in levels:
-        for node_id, raw_community_id in node_id_to_community_map[level].items():
-            community_id = str(raw_community_id)
-            result[community_id]["nodes"].append(node_id)
-            result[community_id]["weight"] += graph.nodes[node_id].get("rank", 0) * graph.nodes[node_id].get("weight", 1)
-```
-
-**文件**: `api/app/core/rag/graphrag/general/community_reports_extractor.py:55-158`
-
-```python
-class CommunityReportsExtractor(Extractor):
-    async def __call__(self, graph, callback=None, task_id=""):
-        communities = leiden.run(graph, {})
-        async with trio.open_nursery() as nursery:
-            for level, comm in communities.items():
-                for community in comm.items():
-                    nursery.start_soon(extract_community_report, community)
-
-        async def extract_community_report(community):
-            cm_id, cm = community
-            ents = cm["nodes"]
-            if len(ents) < 2:
-                return  # 忽略单节点社区
-            ent_df = pd.DataFrame([{"entity": e, "description": graph.nodes[e]["description"]} for e in ents])
-            rela_df = pd.DataFrame([...])  # 社区内关系，上限 10000
-            prompt = perform_variable_replacements(COMMUNITY_REPORT_PROMPT,
-                variables={"entity_df": ent_df.to_csv(), "relation_df": rela_df.to_csv()})
-            response = await trio.to_thread.run_sync(self._chat, text, ...)
-            # 解析 JSON，校验字段类型
-            if not dict_has_keys_with_types(response, [("title", str), ("summary", str), ("findings", list), ("rating", float), ("rating_explanation", str)]):
-                return
-```
-
-### 5.2 图谱检索链路
-
-#### 5.2.1 检索入口
-
-**文件**: `api/app/core/rag/graphrag/search.py:19-280`
-
-```python
-class KGSearch(Dealer):
-    def retrieval(self, question, workspace_ids, kb_ids, emb_mdl, llm,
-                  max_token=8196, ent_topn=6, rel_topn=6, comm_topn=1,
-                  ent_sim_threshold=0.3, rel_sim_threshold=0.3, **kwargs):
-        # Step 1: Query 改写
-        ty_kwds, ents = self.query_rewrite(llm, qst, idxnms, kb_ids)
-        # Step 2: 三路召回
-        ents_from_query = self.get_relevant_ents_by_keywords(ents, filters, idxnms, kb_ids, emb_mdl, ent_sim_threshold)
-        ents_from_types = self.get_relevant_ents_by_types(ty_kwds, filters, idxnms, kb_ids, 10000)
-        rels_from_txt = self.get_relevant_relations_by_txt(qst, filters, idxnms, kb_ids, emb_mdl, rel_sim_threshold)
-        # Step 3: n-hop 路径扩展
-        nhop_pathes = defaultdict(dict)
-        for _, ent in ents_from_query.items():
-            for nbr in ent.get("n_hop_ents", []):
-                for i in range(len(path) - 1):
-                    nhop_pathes[(path[i], path[i+1])]["sim"] += ent["sim"] / (2 + i)
-        # Step 4: 融合打分
-        for ent in ents_from_types:
-            if ent in ents_from_query:
-                ents_from_query[ent]["sim"] *= 2  # 类型匹配 boost
-        for (f, t) in rels_from_txt:
-            s = nhop_pathes.get(pair, {}).get("sim", 0)
-            if f in ents_from_types: s += 1
-            if t in ents_from_types: s += 1
-            rels_from_txt[(f, t)]["sim"] *= s + 1  # n-hop + 类型 boost
-        # Step 5: 排序截断
-        ents_from_query = sorted(..., key=lambda x: x[1]["sim"] * x[1]["pagerank"], reverse=True)[:ent_topn]
-        rels_from_txt = sorted(..., key=lambda x: x[1]["sim"] * x[1]["pagerank"], reverse=True)[:rel_topn]
-        # Step 6: 社区报告召回
-        community = self._community_retrieval_([n for n, _ in ents_from_query], filters, kb_ids, idxnms, comm_topn, max_token)
-        return {"page_content": ents + relas + community, "vector": None, ...}
-```
-
-#### 5.2.2 Query 改写
-
-**文件**: `api/app/core/rag/graphrag/search.py:33-55`
-
-```python
-def query_rewrite(self, llm, question, idxnms, kb_ids):
-    # 从 ES 获取当前 KB 的实体类型池
-    ty2ents = trio.run(lambda: get_entity_type2samples(idxnms, kb_ids))
-    hint_prompt = PROMPTS["minirag_query2kwd"].format(
-        query=question,
-        TYPE_POOL=json.dumps(ty2ents, ensure_ascii=False, indent=2))
-    result = self._chat(llm, hint_prompt, [{"role": "user", "content": "Output:"}], {})
-    keywords_data = json_repair.loads(result)
-    type_keywords = keywords_data.get("answer_type_keywords", [])
-    entities_from_query = keywords_data.get("entities_from_query", [])[:5]
-    return type_keywords, entities_from_query
-```
-
-**设计意图**：
-- Query 改写将自然语言问题转换为两种结构化信号：
-  1. `answer_type_keywords`：回答类型（如 "ORGANIZATION", "PERSON"），用于类型过滤召回。
-  2. `entities_from_query`：查询中的具体实体，用于向量相似度召回。
-- 类型池 `ty2ents` 从 ES 中已建图谱的实体类型采样而来，保证类型建议与当前知识库实际类型一致。
-
-#### 5.2.3 实体向量召回
-
-**文件**: `api/app/core/rag/graphrag/search.py:96-106`
-
-```python
-def get_relevant_ents_by_keywords(self, keywords, filters, idxnms, kb_ids, emb_mdl, sim_thr=0.3, N=56):
-    filters["knowledge_graph_kwd"] = "entity"
-    matchDense = self.get_vector(", ".join(keywords), emb_mdl, 1024, sim_thr)
-    es_res = self.dataStore.search(
-        ["page_content", "entity_kwd", "rank_flt"], [], filters, [matchDense],
-        OrderByExpr(), 0, N, idxnms, kb_ids)
-    return self._ent_info_from_(es_res, sim_thr)
-```
-
-**设计要点**：
-- 实体和关系都以独立 chunk 形式存储在 ES 中，附带 dense_vector 字段。
-- 向量维度由 embedding model 决定，存储字段名为 `q_{dim}_vec`。
-- `sim_thr=0.3` 为默认相似度阈值，过滤低质量匹配。
-
-#### 5.2.4 n-hop 路径扩展与融合公式
-
-**文件**: `api/app/core/rag/graphrag/search.py:160-210`
-
-```python
-# n-hop 路径：从命中实体出发，沿预计算的邻居路径扩展
-for _, ent in ents_from_query.items():
-    nhops = ent.get("n_hop_ents", [])
-    for nbr in nhops:
-        path = nbr["path"]
-        wts = nbr["weights"]
-        for i in range(len(path) - 1):
-            f, t = path[i], path[i + 1]
-            if (f, t) in nhop_pathes:
-                nhop_pathes[(f, t)]["sim"] += ent["sim"] / (2 + i)
-            else:
-                nhop_pathes[(f, t)]["sim"] = ent["sim"] / (2 + i)
-            nhop_pathes[(f, t)]["pagerank"] = wts[i]
-
-# 融合公式：P(E|Q) ≈ P(E) * P(Q|E) → pagerank * sim
-# 实体排序：score = sim × pagerank
-ents_from_query = sorted(ents_from_query.items(),
-    key=lambda x: x[1]["sim"] * x[1]["pagerank"], reverse=True)[:ent_topn]
-```
-
-**设计意图**：
-- n-hop 路径在实体入库时预计算（通过 NetworkX 邻居遍历），存储在 `n_hop_with_weight` 字段。
-- 距离越远的 hop，贡献权重按 `1/(2+i)` 衰减（1-hop: 1/3, 2-hop: 1/4...）。
-- 最终排序融合了两个信号：向量相似度（P(Q|E)，查询与实体的语义匹配）和 PageRank（P(E)，实体在全局图谱中的重要性）。
-
-#### 5.2.5 与向量检索的协同
-
-GraphRAG 检索**不替代**向量检索，而是作为**并行的召回源**之一。在 `settings.py` 中：
-
-```python
-kg_retriever = kg_search.KGSearch(docStoreConn)  # 图谱检索器
-retriever = search.Dealer(docStoreConn)          # 向量检索器
-```
-
-上层调用方（如对话工作流）会同时调用两者，将图谱召回结果（Entities + Relations + Community Reports）与向量召回的 Document Chunks 一起送入 LLM 上下文。
-
----
-
-## 6. Light vs General 差异详解
-
-### 6.1 功能对比
-
-| 维度 | Light | General | 说明 |
-|---|---|---|---|
-| **实体抽取 Prompt** | LightRAG 风格，含 content_keywords | MS GraphRAG 风格，更简洁 | `light/graph_prompt.py` vs `general/graph_prompt.py` |
-| **Gleaning 终止** | 自然语言 yes/no | 强制单字 Y（logit_bias） | Light 更灵活，General 更确定 |
-| **实体消歧** | ❌ 不支持 | ✅ 支持 | `entity_resolution.py` 仅在 General 流程中调用 |
-| **社区发现** | ❌ 不支持 | ✅ Leiden 算法 | `general/leiden.py` |
-| **社区报告** | ❌ 不支持 | ✅ LLM 生成报告 | `general/community_reports_extractor.py` |
-| **实体嵌入** | 仅实体名向量 | 支持 Node2Vec（备用） | `general/entity_embedding.py` 当前未在主线使用 |
-| **思维导图** | ❌ 不支持 | ✅ 支持 | `general/mind_map_extractor.py` |
-| **并发控制** | 相同 | 相同 | `trio.Semaphore` + `chat_limiter` |
-| **建图耗时** | 低（无消歧/社区） | 高（消歧 + 社区报告 ≈ 额外 10-30 分钟） | |
-| **Token 消耗** | 低 | 高（社区报告每社区一次 LLM 调用） | |
-| **适用数据规模** | < 1K 文档 | > 1K 文档 | |
-
-### 6.2 切换条件
-
-**配置入口**：`parser_config["graphrag"]["method"]`
-
-```python
-# api/app/core/rag/graphrag/general/index.py:54
-extractor = LightKGExt if (
-    "method" not in row["parser_config"].get("graphrag", {})
-    or row["parser_config"]["graphrag"]["method"] != "general"
-) else GeneralKGExt
-```
-
-| 条件 | 推荐模式 |
-|---|---|
-| `parser_config.graphrag.method` 未设置 或 != `"general"` | **Light**（默认） |
-| `parser_config.graphrag.method == "general"` | **General** |
-| `with_resolution=True` 且 method=general | General + 实体消歧 |
-| `with_community=True` 且 method=general | General + 社区报告 |
-
-### 6.3 资源消耗对比（估算）
-
-以 1000 个 chunk（约 50 万字）的知识库为例：
-
-| 阶段 | Light | General | 差异原因 |
-|---|---|---|---|
-| 实体抽取 | ~100 次 LLM 调用 | ~100 次 LLM 调用 | 两者类似 |
-| 实体消歧 | 0 | ~10-50 次 LLM 调用 | 候选对数量取决于实体重复率 |
-| 社区报告 | 0 | ~20-100 次 LLM 调用 | 社区数量取决于图密度 |
-| 总 Token | ~500K-1M | ~2M-5M | General 多轮摘要 + 社区报告 |
-| 总时间 | ~5-15 分钟 | ~30-60 分钟 | 消歧和社区是主要耗时 |
-| ES 存储 | ~实体数 + 关系数 | + 社区报告数 + 全局图 | |
-
----
-
-## 7. 关键 Prompt 解读
-
-### 7.1 Query 分析 Prompt：`minirag_query2kwd`
-
-**文件**: `api/app/core/rag/graphrag/query_analyze_prompt.py:9-155`
-
-```
----Role---
-You are a helpful assistant tasked with identifying both answer-type and low-level keywords...
-
----Goal---
-Given the query, list both answer-type and low-level keywords.
-answer_type_keywords focus on the type of the answer...
-The answer_type_keywords must be selected from Answer type pool.
-
----Instructions---
-- Output the keywords in JSON format.
-- "answer_type_keywords" for the types of the answer... No more than 3.
-- "entities_from_query" for specific entities or details.
-```
-
-**设计意图逐行解读**：
-
-| Prompt 片段 | 设计意图 |
-|---|---|
-| `answer_type_keywords must be selected from Answer type pool` | 强制从知识库实际存在的类型中选择，避免 LLM 编造不存在的类型。类型池从已建图谱采样，保证类型有效性。 |
-| `No more than 3` | 限制类型数量，防止过度发散导致召回噪声。 |
-| `entities_from_query must be extracted from the query` | 强调实体必须从查询原文提取，禁止 LLM 扩展或推测，保证召回精确性。 |
-| 4 个覆盖不同领域的示例 | Few-shot 示例涵盖时间、地点、组织、抽象概念，帮助 LLM 理解类型判定逻辑。 |
-| `TYPE_POOL` 动态注入 | 运行时从 ES 查询当前 KB 的实体类型分布，使类型建议与知识库内容一致。 |
-
-### 7.2 实体消歧 Prompt：`ENTITY_RESOLUTION_PROMPT`
-
-**文件**: `api/app/core/rag/graphrag/entity_resolution_prompt.py:1-58`
-
-```
--Goal-
-Please answer the following Question as required
-
--Steps-
-1. Identify each line of questioning as required
-2. Return output in English as a single list of each line answer...
-Use **{record_delimiter}** as the list delimiter.
-
--Examples-
-Example 1: Product 对比（computer vs phone → No，television vs TV → No）
-Example 2: Toponym 对比（Chicago vs ChiTown → Yes，Shanghai vs Zhengzhou → No）
-
--Real Data-
-Question:{input_text}
-```
-
-**设计意图逐行解读**：
-
-| Prompt 片段 | 设计意图 |
-|---|---|
-| `only focus on critical properties and overlook noisy factors` | 引导 LLM 关注核心语义特征，忽略大小写、缩写、冠词等噪声。 |
-| `Use domain knowledge of {entity_type}s` | 提示 LLM 利用领域知识辅助判断（如 "Peking" = "Beijing" 在地理领域成立）。 |
-| `answer the above N questions in the format: For Question i, Yes/No...` | 强制固定输出格式，便于正则解析。 |
-| `##` record_delimiter + `<\|>` entity_index_delimiter + `&&` resolution_result_delimiter | 三层分隔符设计，降低解析冲突概率。 |
-| 两个示例分别覆盖产品和地名 | 展示不同领域的消歧标准差异，增强泛化能力。 |
-
-**注意**：示例中 "television vs TV → No" 和 "Chicago vs ChiTown → Yes" 看起来矛盾，实际上是在**引导 LLM 区分"缩写是否代表同一实体"**——TV 是 television 的缩写（同一事物），但 Prompt 标注为 No，可能是示例错误；而 Chicago vs ChiTown（俚语别称）标注为 Yes。这个示例设计值得商榷，实际效果取决于 LLM 的理解。
-
-### 7.3 Light 版实体抽取 Prompt
-
-**文件**: `api/app/core/rag/graphrag/light/graph_prompt.py:20-59`
-
-```
----Goal---
-Given a text document... identify all entities... and all relationships...
-
----Steps---
-1. Identify all entities. Format: ("entity"{tuple_delimiter}<name>{tuple_delimiter}<type>{tuple_delimiter}<description>)
-2. Identify all relationships. Format: ("relationship"{tuple_delimiter}<src>{tuple_delimiter}<tgt>{tuple_delimiter}<desc>{tuple_delimiter}<keywords>{tuple_delimiter}<strength>)
-3. Identify high-level key words... Format: ("content_keywords"{tuple_delimiter}<keywords>)
-4. Return output as a single list...
-5. When finished, output {completion_delimiter}
-```
-
-**设计意图**：
-- **Tuple 格式**：`("entity"<\|>NAME<\|>TYPE<\|>DESC)` 使用固定分隔符，便于正则提取，比 JSON 更抗格式错误。
-- **content_keywords**：额外提取文档级关键词，可用于后续检索增强或标签分类。
-- **relationship_keywords**：关系关键词用于关系 chunk 的文本检索补充。
-- **strength**：关系强度（1-10）用于后续排序加权。
-- **多轮 gleaning**：首轮抽取后，用 `"MANY entities were missed"` 追问，最多 2 轮（`ENTITY_EXTRACTION_MAX_GLEANINGS=2`）。
-
-### 7.4 General 版实体抽取 Prompt
-
-**文件**: `api/app/core/rag/graphrag/general/graph_prompt.py:8-106`
-
-与 Light 版的主要差异：
-- **无 content_keywords**：仅抽取 entity + relationship，更聚焦。
-- **无 relationship_keywords**：关系描述更简洁。
-- **无 strength 数值**：关系权重由出现频率决定（非 LLM 评分）。
-- **LOOP_PROMPT 使用 logit_bias**：强制输出单字 `Y` 或 `N`，比 Light 的自然语言判断更确定。
-
-### 7.5 社区报告 Prompt
-
-**文件**: `api/app/core/rag/graphrag/general/community_report_prompt.py:8-157`
-
-```
-# Goal
-Write a comprehensive report of a community...
-
-# Report Structure
-- TITLE: community's name...
-- SUMMARY: An executive summary...
-- IMPACT SEVERITY RATING: a float score between 0-10...
-- RATING EXPLANATION: single sentence...
-- DETAILED FINDINGS: 5-10 key insights...
-
-# Grounding Rules
-Points supported by data should list their data references as follows:
-"...supported by multiple data references [Data: <dataset name> (record ids)]"
-```
-
-**设计意图**：
-- **结构化 JSON 输出**：强制 `title/summary/rating/rating_explanation/findings` 五字段，便于程序解析。
-- **影响力评级（0-10）**：量化社区重要性，检索时按 `weight_flt` 排序优先返回高影响力社区。
-- **Grounding Rules**：要求引用数据记录 ID，增强可解释性（虽然当前实现未实际利用这些引用）。
-- **示例输入**：提供 `VERDANT OASIS PLAZA` 和 `HARMONY ASSEMBLY` 的完整示例，展示输出格式和数据引用方式。
-
----
-
-## 8. 图谱存储设计
-
-### 8.1 不使用 Neo4j
-
-MemoryBear 的 GraphRAG **不依赖 Neo4j** 等专用图数据库，而是复用 Elasticsearch 作为统一存储。理由：
-1. **运维简化**：无需维护额外的图数据库集群。
-2. **混合检索**：实体/关系的向量嵌入与文档 chunk 存储在同一张索引，便于统一检索。
-3. **增量更新**：ES 的文档模型天然支持增量写入和版本管理。
-
-### 8.2 ES 文档类型（knowledge_graph_kwd）
-
-| 类型 | 存储内容 | 关键字段 |
-|---|---|---|
-| `graph` | 全局图（NetworkX node_link_data JSON） | `page_content`（JSON）、`source_id` |
-| `subgraph` | 单文档子图 | `page_content`（JSON）、`source_id` |
-| `entity` | 单个实体（可向量检索） | `entity_kwd`、`entity_type_kwd`、`rank_flt`、`q_*_vec` |
-| `relation` | 单个关系（可向量检索） | `from_entity_kwd`、`to_entity_kwd`、`weight_int`、`q_*_vec` |
-| `community_report` | 社区报告 | `docnm_kwd`（标题）、`weight_flt`、`entities_kwd` |
-| `ty2ents` | 类型→实体样例映射 | `page_content`（JSON dict） |
-
-### 8.3 向量嵌入策略
-
-**文件**: `api/app/core/rag/graphrag/utils.py:301-327`（实体）和 `352-378`（关系）
-
-```python
-async def graph_node_to_chunk(kb_id, embd_mdl, ent_name, meta, chunks):
-    chunk = {
-        "entity_kwd": ent_name,
-        "knowledge_graph_kwd": "entity",
-        "entity_type_kwd": meta["entity_type"],
-        "page_content": json.dumps(meta, ensure_ascii=False),
-        ...
-    }
-    # 实体向量 = entity_name 的 embedding
-    ebd, _ = embd_mdl.encode([ent_name])
-    chunk["q_%d_vec" % len(ebd)] = ebd
-
-async def graph_edge_to_chunk(kb_id, embd_mdl, from_ent_name, to_ent_name, meta, chunks):
-    # 关系向量 = "from->to: description" 的 embedding
-    txt = f"{from_ent_name}->{to_ent_name}"
-    ebd, _ = embd_mdl.encode([txt + f": {meta['description']}"])
-    chunk["q_%d_vec" % len(ebd)] = ebd
-```
-
-**设计要点**：
-- 实体向量基于**实体名**（`ent_name`），而非描述文本——因为检索时用户查询通常包含实体名。
-- 关系向量基于 `"from->to: description"`，兼顾结构信息和语义信息。
-- 向量缓存：通过 Redis + xxhash 缓存 embedding 结果，避免重复计算。
-
----
-
-## 9. 配置项与可调参数
-
-### 9.1 环境变量
-
-| 环境变量 | 默认值 | 说明 | 源码位置 |
-|---|---|---|---|
-| `MAX_CONCURRENT_CHATS` | 10 | LLM 并发调用上限（trio CapacityLimiter） | `utils.py:41` |
-| `MAX_CONCURRENT_PROCESS_AND_EXTRACT_CHUNK` | 10 | Chunk 处理并发上限 | `general/extractor.py:33` |
-| `ENABLE_TIMEOUT_ASSERTION` | 未设置 | 测试模式：启用短超时（3-280s） | 多处 `trio.fail_after` |
-
-### 9.2 parser_config 配置
-
-**文件**: `api/app/models/knowledge_model.py:77-82` / `document_model.py:27-32`
-
-```python
-"graphrag": {
-    "use_graphrag": False,      # 总开关
-    "method": "light",          # "light" 或 "general"
-    "resolution": False,        # 是否启用实体消歧（仅 General）
-    "community": False,         # 是否启用社区报告（仅 General）
-    "entity_types": []          # 自定义实体类型列表，空则使用默认值
-}
-```
-
-### 9.3 检索参数
-
-**文件**: `api/app/core/rag/graphrag/search.py:130-141`
-
-| 参数 | 默认值 | 说明 |
-|---|---|---|
-| `max_token` | 8196 | 返回结果的总 token 预算 |
-| `ent_topn` | 6 | 返回实体数量上限 |
-| `rel_topn` | 6 | 返回关系数量上限 |
-| `comm_topn` | 1 | 返回社区报告数量上限 |
-| `ent_sim_threshold` | 0.3 | 实体向量相似度阈值 |
-| `rel_sim_threshold` | 0.3 | 关系向量相似度阈值 |
-
-### 9.4 消歧参数
-
-**文件**: `api/app/core/rag/graphrag/entity_resolution.py`
-
-| 参数 | 默认值 | 说明 |
-|---|---|---|
-| `resolution_batch_size` | 100 | 每批消歧的实体对数量 |
-| `max_concurrent_tasks` | 5 | 消歧 LLM 调用并发数 |
-| 超时 | 280s（测试）/ 无限（生产） | `trio.move_on_after` |
-
-### 9.5 社区发现参数
-
-**文件**: `api/app/core/rag/graphrag/general/leiden.py:97`
-
-| 参数 | 默认值 | 说明 |
-|---|---|---|
-| `max_cluster_size` | 12 | 单个社区最大节点数 |
-| `use_lcc` | True | 是否只取最大连通分量 |
-| `seed` | 0xDEADBEEF | Leiden 算法随机种子 |
-
----
-
-## 10. 边界条件与已知限制
-
-### 10.1 已知限制
-
-| 限制 | 影响 | 缓解措施 |
-|---|---|---|
-| 实体消歧仅处理 subgraph_nodes 内的节点 | 历史已消歧的节点不再参与新一轮消歧 | 手动重建图谱触发全量消歧 |
-| 社区报告忽略 < 2 个节点的社区 | 孤立实体无社区报告覆盖 | 通过实体直接召回补充 |
-| 关系抽取忽略无对应实体的关系 | 实体抽取失败导致关系丢失 | `tidy_graph` 后检查日志 |
-| LLM 输出格式错误导致解析失败 | 部分 chunk 的实体/关系丢失 | `json_repair` 库容错 + 错误计数限制（max_errors=3） |
-| 实体名大写归一化 | "Apple" 和 "apple" 被视为同一实体 | 设计如此，避免大小写重复 |
-| 中文编辑距离用字符集 Jaccard | 对短实体（< 4 字）阈值不同 | `is_similarity` 中特殊处理 |
-| 图谱全量重建需遍历所有 subgraph | 大数据集重建耗时高 | 增量合并避免全量重建 |
-
-### 10.2 幂等性与并发安全
-
-- `generate_subgraph()` 检查 `does_graph_contains()`，避免同一文档重复建图。
-- `merge_subgraph()` 使用 `RedisDistributedLock` 保证同一 KB 的并发合并安全。
-- `run_graphrag_for_kb()` 支持 `max_parallel_documents=4`，控制文档级并发。
-
-### 10.3 任务取消
-
-所有长时操作（抽取、消歧、社区报告）都穿插 `has_canceled(task_id)` 检查，支持用户通过 Redis 键取消任务：
-
-```python
-def has_canceled(task_id):
-    return redis_client.get(f"{task_id}-cancel") is not None
-```
-
----
-
-## 11. 监控指标与排错指引
-
-### 11.1 关键日志
-
-| 日志模式 | 含义 | 排查方向 |
-|---|---|---|
-| `ignored X relations due to missing entities` | 关系指向的实体未抽取到 | 检查 LLM 输出格式，或降低 tidy_graph 的清理标准 |
-| `Resolved X candidate pairs, Y of them are selected to merge` | 实体消歧结果统计 | Y/X 过低说明预筛选太严格或 LLM 过于保守 |
-| `Graph extracted X communities in Ys` | 社区发现完成 | 社区数异常（0 或过多）检查图谱连通性 |
-| `Task {id} cancelled during...` | 任务被取消 | 正常用户行为，无需排查 |
-| `Didn't extract any entities and relationships` | LLM 返回空 | 检查 LLM 可用性、Prompt 长度是否超限 |
-| `Insert chunk error` | ES 写入失败 | 检查 ES 集群状态、索引 mapping |
-
-### 11.2 性能指标
-
-| 指标 | 采集方式 | 健康阈值 |
-|---|---|---|
-| 单文档建图耗时 | callback 日志 | Light < 5min，General < 30min |
-| 实体抽取 Token 消耗 | `sum_token_count` | 关注单 chunk 消耗是否异常高 |
-| ES 查询延迟 | `dataStore.search` 耗时 | P99 < 500ms |
-| LLM 调用成功率 | 错误日志计数 | > 95% |
-| 消歧候选对数量 | `num_candidates` | 与节点数平方成正比，关注异常增长 |
-
----
-
-## 12. 优化建议与未来扩展点
-
-### 12.1 短期优化（1-2 周可落地）
-
-1. **实体消歧预筛选优化**：当前 `is_similarity` 对中文使用字符集 Jaccard，对同音字/形近字（如"阿里巴巴" vs "阿狸巴巴"）效果差。建议引入拼音相似度或字形相似度作为第三层预筛选。
-2. **消歧 Prompt 示例修正**：`entity_resolution_prompt.py` 中 "television vs TV → No" 的示例与常识矛盾，建议修正为 Yes，避免误导 LLM。
-3. **社区报告并发控制**：当前 `community_reports_extractor.py` 对每个社区启动一个 trio task，社区数过多时会压垮 LLM。建议增加社区级并发限制。
-4. **关系向量优化**：当前关系向量使用 `"from->to: description"`，但 description 可能很长。建议仅使用 `"from->to"` 或关系关键词作为嵌入文本，提升检索效率。
-
-### 12.2 中期扩展（1-2 月）
-
-1. **多跳推理增强**：当前 n-hop 路径是预计算的静态数据。可考虑在检索阶段动态执行多跳遍历，支持更灵活的推理路径。
-2. **时序图谱**：在关系/实体上增加时间维度，支持"某实体在某时间段的关系变化"类查询。
-3. **图可视化 API**：基于 `nx.node_link_data` 输出，提供前端可消费的图数据接口，支持交互式图谱浏览。
-4. **增量实体类型发现**：当前实体类型是静态配置。可通过 LLM 自动发现文档中的新实体类型，动态扩展类型池。
-
-### 12.3 长期方向（路线图）
-
-1. **GraphRAG + 多模态**：将图片中的实体（如 OCR 提取的组织 logo）纳入图谱，支持跨模态实体关联。
-2. **动态图谱更新**：当前是批处理模式（文档上传后触发建图）。可探索流式更新，支持实时知识库编辑后的图谱增量更新。
-3. **替代 ES 的图数据库评估**：当图谱规模达到百万节点级别时，ES 的图查询性能可能成为瓶颈。可评估 Neo4j / Dgraph 等专用图数据库的接入可行性。
-
----
-
-## 附录：源码索引速查表
-
-| 功能 | 文件 | 关键类/函数 | 行号 |
-|---|---|---|---|
-| 建图总控 | `general/index.py` | `run_graphrag()` | 36-119 |
-| KB 级批量建图 | `general/index.py` | `run_graphrag_for_kb()` | 122-330 |
-| 子图生成 | `general/index.py` | `generate_subgraph()` | 333-406 |
-| 子图合并 | `general/index.py` | `merge_subgraph()` | 409-436 |
-| Light 实体抽取 | `light/graph_extractor.py` | `GraphExtractor._process_single_content()` | 74-131 |
-| General 实体抽取 | `general/graph_extractor.py` | `GraphExtractor._process_single_content()` | 100-150 |
-| 抽取基类 | `general/extractor.py` | `Extractor.__call__()` | 97-203 |
-| 节点合并 | `general/extractor.py` | `Extractor._merge_nodes()` | 205-225 |
-| 边合并 | `general/extractor.py` | `Extractor._merge_edges()` | 227-236 |
-| 图节点合并 | `general/extractor.py` | `Extractor._merge_graph_nodes()` | 238-275 |
-| 描述摘要 | `general/extractor.py` | `Extractor._handle_entity_relation_summary()` | 277-300 |
-| 实体消歧 | `entity_resolution.py` | `EntityResolution.__call__()` | 53-141 |
-| 消歧候选判断 | `entity_resolution.py` | `EntityResolution._resolve_candidate()` | 143-186 |
-| 结果解析 | `entity_resolution.py` | `EntityResolution._process_results()` | 188-213 |
-| 相似度预筛选 | `entity_resolution.py` | `EntityResolution.is_similarity()` | 225-239 |
-| 社区发现 | `general/leiden.py` | `run()` | 95-141 |
-| 社区报告抽取 | `general/community_reports_extractor.py` | `CommunityReportsExtractor.__call__()` | 55-158 |
-| 图谱检索 | `search.py` | `KGSearch.retrieval()` | 130-280 |
-| Query 改写 | `search.py` | `KGSearch.query_rewrite()` | 33-55 |
-| 实体向量召回 | `search.py` | `KGSearch.get_relevant_ents_by_keywords()` | 96-106 |
-| 关系向量召回 | `search.py` | `KGSearch.get_relevant_relations_by_txt()` | 107-117 |
-| 类型过滤召回 | `search.py` | `KGSearch.get_relevant_ents_by_types()` | 118-128 |
-| 社区报告召回 | `search.py` | `KGSearch._community_retrieval_()` | 282-302 |
-| 图合并工具 | `utils.py` | `graph_merge()` | 199-229 |
-| 图写入 ES | `utils.py` | `set_graph()` | 426-516 |
-| 图读取 ES | `utils.py` | `get_graph()` | 407-423 |
-| 实体转 chunk | `utils.py` | `graph_node_to_chunk()` | 301-327 |
-| 关系转 chunk | `utils.py` | `graph_edge_to_chunk()` | 352-378 |
-| LLM 缓存 | `utils.py` | `get_llm_cache()` / `set_llm_cache()` | 97-113 |
-| 任务取消检查 | `utils.py` | `has_canceled()` | 628-634 |
-| Query 分析 Prompt | `query_analyze_prompt.py` | `PROMPTS["minirag_query2kwd"]` | 9-155 |
-| 消歧 Prompt | `entity_resolution_prompt.py` | `ENTITY_RESOLUTION_PROMPT` | 1-58 |
-| Light 抽取 Prompt | `light/graph_prompt.py` | `PROMPTS["entity_extraction"]` | 20-59 |
-| General 抽取 Prompt | `general/graph_prompt.py` | `GRAPH_EXTRACTION_PROMPT` | 8-106 |
-| 社区报告 Prompt | `general/community_report_prompt.py` | `COMMUNITY_REPORT_PROMPT` | 8-157 |
-| 建图触发入口 | `tasks.py` | `build_graphrag_for_document()` | 557-636 |
-| KB 建图触发 | `tasks.py` | `build_graphrag_for_kb()` | 472-556 |
-| 模型默认配置 | `models/knowledge_model.py` | `parser_config["graphrag"]` | 77-82 |

docs/rag/pipeline/05-reranking-prompt-llm.md

@@ -1,445 +0,0 @@
----
-
-# [S2-T5] 检索后处理与生成（Reranking / Prompt 工程 / LLM 调用 / 后处理）实现详解
-
-**author:** Python 开发工程师  
-**source-commit:** `feae2f2e` (Merge PR #1033 release/v0.3.2)  
-**reviewer:** 待 [S2-T7] 评审  
-**last-reviewed-at:** 2026-05-08
-
----
-
-## 一句话定位
-
-本文档覆盖 MemoryBear RAG 链路的后半段：从检索结果进入系统，到最终 LLM 生成答案并输出给用户的全过程，包括重排序、Prompt 组装、多模型 LLM 调用、流式输出、工具调用及生成后处理。
-
-## 设计目标与适用场景
-
-- **设计目标**：在多知识库、多检索策略（关键词 / 向量 / 混合 / GraphRAG）返回的原始结果上，通过重排序提升相关性，通过 Prompt 工程高效利用上下文，通过多提供商 LLM 封装实现高可用调用，最终输出带引用溯源、支持流式/非流式的答案。
-- **适用场景**：
-  - Agent 聊天（`app_chat_service.py` / `draft_run_service.py`）
-  - Workflow 知识检索节点（`workflow/nodes/knowledge/node.py`）
-  - 独立 chunk 检索 API（`chunk_controller.py`）
-
-## 关键概念与术语表
-
-| 术语 | 含义 |
-|------|------|
-| Rerank | 在初步召回后对 chunk 进行精细重排序 |
-| RedBearRerank | 基于 LangChain `BaseDocumentCompressor` 的 rerank 封装 |
-| Dealer | 底层检索调度器，负责混合搜索、内置 rerank、引用插入 |
-| KnowledgeRetrievalNode | Workflow 引擎中的知识检索节点 |
-| LangChainAgent | 基于 `create_agent` 的 ReAct Agent，负责工具调用循环 |
-| citation | 生成后处理阶段向答案文本中插入 `[ID:N]` 引用标记 |
-| rank_feature | 基于 tag 特征和 PageRank 的辅助排序分 |
-
-## 实现概览（Mermaid 流程图）
-
-```
-检索结果输入
-    │
-    ▼
-┌─────────────────┐
-│  Rerank 层       │
-│  A:内置混合      │
-│  B:外部模型      │
-│  C:RedBearRerank │
-│  D:ES层封装      │
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────────────┐
-│ Prompt 工程与上下文组装   │
-│ 系统 Prompt + 技能 Prompt │
-│ 知识上下文拼接             │
-│ Token 预算管理             │
-└────────┬────────────────┘
-         │
-         ▼
-┌─────────────────────────┐
-│ LLM 调用层 (LangChainAgent)│
-│ ReAct 工具调用循环         │
-│ 流式/非流式               │
-│ 多模态 + 深度思考          │
-└────────┬────────────────┘
-         │
-         ▼
-┌─────────────────────────┐
-│ 生成后处理               │
-│ 引用过滤 + 下载链接       │
-│ 引用插入 (embedding 匹配) │
-│ JSON 结构化校验           │
-└─────────────────────────┘
-```
-
----
-
-## 1. Reranking 章节
-
-### 1.1 是否使用显式 Rerank
-
-**是**。MemoryBear 在多处实现了 rerank，采用"多方案并存、按场景选择"策略。
-
-### 1.2 Rerank 方案全景
-
-#### 方案 A：内置混合 Rerank（Dealer.rerank）
-
-**源码**：`api/app/core/rag/nlp/search.py:606-643`
-
-核心融合公式：
-```
-score = tkweight * token_similarity + vtweight * vector_similarity + rank_feature
-```
-
-- `tkweight` 默认 0.3，`vtweight` 默认 0.7
-- `token_similarity`：基于 rag_tokenizer 分词后的 Jaccard 风格相似度
-- `vector_similarity`：query_vector 与 chunk 向量的余弦相似度
-- `rank_feature`：tag 特征 TF-IDF 余弦 + PageRank，缩放 10 倍（`search.py:579-604`）
-- token 权重分配：`content_ltks + title_tks*2 + important_kwd*5 + question_tks*6`
-
-#### 方案 B：外部 Rerank 模型（Dealer.rerank_by_model）
-
-**源码**：`api/app/core/rag/nlp/search.py:645-666`
-
-将向量相似度替换为外部 rerank 模型的 `similarity()` 输出，保留 token 相似度和 rank_feature。
-
-#### 方案 C：RedBearRerank（LCEL 兼容封装）
-
-**源码**：`api/app/core/models/rerank.py:11-84`
-
-- 继承 `langchain_core.documents.BaseDocumentCompressor`
-- 支持 `XINFERENCE` / `GPUSTACK` → `JinaRerank`
-- 支持 `DASHSCOPE` → `DashScopeRerank`
-- 端点自动规范化：补齐 `/v1/rerank`
-
-使用场景：
-- Workflow `KnowledgeRetrievalNode.rerank()`（`node.py:108-155`）
-- `ElasticSearchVector.rerank()`（`elasticsearch_vector.py:560-607`）
-- `nlp/search.py:rerank()`（`search.py:284-343`）
-
-#### 方案 D：ElasticSearchVector 层 Rerank
-
-ES Vector 初始化时注入 `reranker_config`，`rerank()` 中调用 `self.reranker.compress_documents()`。
-
-### 1.3 阈值与延迟
-
-- **内置 rerank**：本地 numpy 计算，毫秒级延迟
-- **外部 rerank**：网络调用，本地 Xinference <10ms，远程 DashScope 100-500ms
-- **相似度阈值**：`similarity_threshold` 默认 0.2，低于此值的 chunk 被过滤（`search.py:674-768`）
-
-### 1.4 为什么没有统一使用 Cross-Encoder
-
-- Cross-Encoder 需额外部署，对小型部署不友好
-- 内置 `Dealer.rerank` 在多数场景已足够
-- RedBearRerank 作为可选增强，仅在显式配置 `reranker_id` 时启用
-
----
-
-## 2. Prompt 工程与上下文组装
-
-### 2.1 Prompt 模板组织
-
-**目录**：`api/app/core/rag/prompts/`
-
-| 模板文件 | 用途 |
-|----------|------|
-| `ask_summary.md` | 知识库问答主 Prompt |
-| `citation_prompt.md` | 引用标注规范（`[ID:i]` 格式） |
-| `citation_plus.md` | 引用回填 Agent Prompt |
-| `question_prompt.md` | 文本生成问题 |
-| `keyword_prompt.md` | 关键词提取 |
-| `structured_output_prompt.md` | JSON Schema 约束 |
-| `cross_languages_*.md` | 跨语言查询扩展 |
-| `analyze_task_*.md` | 任务分析与工具选择 |
-
-**加载机制**：`api/app/core/rag/prompts/template.py:9-20`，启动时加载并缓存。
-
-### 2.2 上下文组装流程
-
-**Agent 层**：`api/app/core/agent/langchain_agent.py:230-271`
-
-```python
-def _prepare_messages(self, message, history, context, files):
-    messages = []
-    for msg in history:
-        if msg["role"] == "user": messages.append(HumanMessage(...))
-        elif msg["role"] == "assistant": messages.append(AIMessage(...))
-    user_content = message
-    if context:
-        user_content = f"参考信息：\n{context}\n\n用户问题：\n{user_content}"
-    messages.append(HumanMessage(content=user_content))
-    return messages
-```
-
-### 2.3 知识检索工具中的 Chunk 拼接
-
-**源码**：`api/app/services/draft_run_service.py:227-255`
-
-```python
-retrieve_chunks_result = knowledge_retrieval(query, kb_config)
-retrieval_knowledge = [i.page_content for i in retrieve_chunks_result]
-context = '\n\n'.join(retrieval_knowledge)
-return f"检索到以下相关信息：\n\n{context}"
-```
-
-- chunk 间用 `\n\n` 分隔
-- 引用信息（document_id、file_name、score）由外部 `citations_collector` 收集，与上下文字符串分离
-- 属于"隐式引用"策略：LLM 看不到 `[ID:N]`，引用回填在生成后完成
-
-### 2.4 Token 预算管理
-
-**源码**：`api/app/core/rag/prompts/generator.py:46-80`
-
-策略：
-1. 计算总 token；未超限直接返回
-2. 超限后保留 `system` + 最后一条消息，丢弃中间历史
-3. 仍超限则按比例截断 system 或 user 内容
-
-### 2.5 System / User 分层结构
-
-```
-system: {用户自定义 system_prompt} + {技能 Prompt} + {文档图片识别指令}
-user:  {历史消息...}
-user:  参考信息：\n\n{chunks}\n\n用户问题：\n{query}
-```
-
-System Prompt 组装见 `app_chat_service.py:77-96`：先变量替换，再追加 skill_prompts。
-
----
-
-## 3. LLM 调用
-
-### 3.1 支持的模型与切换机制
-
-**核心封装**：`api/app/core/rag/llm/chat_model.py:52-63`
-
-`Base` 类基于 OpenAI 兼容 API，子类覆盖：
-
-| 类名 | 提供商 |
-|------|--------|
-| `GptTurbo` | OpenAI |
-| `XinferenceChat` | Xinference |
-| `HuggingFaceChat` | HuggingFace |
-| `ModelScopeChat` | ModelScope |
-| `AzureChat` | Azure OpenAI |
-| `BaiChuanChat` | 百川 |
-| `LocalAIChat` | LocalAI |
-| `VolcEngineChat` | 火山引擎 |
-| `OpenAI_APIChat` | VLLM / OpenAI-API-Compatible |
-| `GPUStackChat` | GPUStack |
-
-**切换机制**：`ModelApiKeyService.get_available_api_key()` 根据 `model_id` 从数据库读取 provider/api_key/base_url/model_name，运行时动态实例化。
-
-### 3.2 流式 vs 非流式
-
-**非流式**（`Base._chat()`，`chat_model.py:122-150`）：
-- `stream=False`，返回 `(text, total_tokens)`
-- QWQ 推理模型强制内部走流式聚合，过滤 `<think>` 标签
-
-**流式**（`Base._chat_streamly()`，`chat_model.py:152-185`）：
-- `stream=True`，yield `(delta, token_count)`
-- 支持 `reasoning_content` 提取
-- `finish_reason == "length"` 时自动追加截断提示（中英文自适应）
-
-**Agent 流式**（`LangChainAgent.chat_stream()`）：
-- `agent.astream_events(version="v2")`
-- 处理 `on_chat_model_stream` / `on_llm_stream`
-- 支持多模态响应解析（OpenAI + 通义千问格式）
-
-### 3.3 超时、重试、降级
-
-**源码**：`chat_model.py:64-89, 192-215`
-
-- 超时：`LLM_TIMEOUT_SECONDS`（默认 600s）
-- 重试：`LLM_MAX_RETRIES`（默认 5）+ 随机抖动延迟
-- 仅对 `RATE_LIMIT` / `SERVER_ERROR` 重试
-- **降级**：无自动模型降级，失败返回 `"**ERROR**: ..."`
-
-### 3.4 函数调用 / 工具使用
-
-**源码**：`chat_model.py:251-303, 335-436`
-
-- 最多 `max_rounds`（默认 5）轮工具调用循环
-- 工具参数解析使用 `json_repair.loads()` 增强容错
-- 流式工具调用：`chat_streamly_with_tools()`
-
-**Agent 工具循环**：`LangChainAgent`
-- `create_agent(model, tools, system_prompt)`
-- `max_iterations = 5 + len(tools) * 2`
-- 单个工具最大连续调用：`max_tool_consecutive_calls = 3`
-- `_wrap_tools_with_tracking()` 防循环
-
-### 3.5 CV 模型与序列到文本模型
-
-**CV 模型**（`cv_model.py`）：`QWenCV`、`AzureGptV4` — 用于图片/版面分析。
-
-**序列到文本**（`sequence2txt_model.py`）：`QWenSeq2txt`（带时间戳 ASR）、`GPTSeq2txt`（Whisper）— 用于音视频预处理。
-
----
-
-## 4. 生成后处理
-
-### 4.1 引用回填（Citation Insertion）
-
-**源码**：`api/app/core/rag/nlp/search.py:489-577`
-
-流程：
-1. 将答案按句子切分（避开代码块 ```` ``` ````）
-2. 对每句话 embedding，与 chunk embeddings 计算 hybrid similarity
-3. 阈值从 0.63 开始动态衰减（×0.8），最低 0.3
-4. 每句最多引用 4 个 chunk，句末插入 `[ID:N]`
-
-### 4.2 引用过滤与下载链接
-
-**源码**：`api/app/services/draft_run_service.py:474-490`
-
-- `features_config.citation.enabled` 开关控制
-- `allow_download=True` 时附加 `download_url`
-
-### 4.3 安全过滤
-
-当前版本无显式敏感词过滤模块。安全依赖：
-- LLM 提供商自带内容过滤
-- `ERROR_CONTENT_FILTER` 错误码捕获
-
-### 4.4 输出结构化（JSON Schema）
-
-**源码**：`api/app/core/agent/langchain_agent.py:85-92`
-
-通过 system prompt 注入 `"\n请以JSON格式输出。"` 实现（非 `response_format` API），因为 LangChain Agent 有工具时无法使用原生 API。
-
----
-
-## 5. 端到端示例
-
-### 场景：Agent 聊天触发知识库检索
-
-**Step 1** — 用户提问：`"MemoryBear 的 Rerank 策略是什么？"`
-
-**Step 2** — System Prompt 组装：
-```
-你是一个专业的 AI 知识库助手，名为 Miss R。
-任务：根据知识库中的信息回答用户问题。
-要求：不要编造信息；使用 Markdown；用用户提问的语言回答。
-```
-（来自 `ask_summary.md`）
-
-**Step 3** — LLM 判断调用 `knowledge_retrieval_tool`
-
-工具内部：
-```python
-retrieve_chunks_result = knowledge_retrieval(query, kb_config)
-context = '\n\n'.join([i.page_content for i in retrieve_chunks_result])
-return f"检索到以下相关信息：\n\n{context}"
-```
-
-**Step 4** — 若配置 `reranker_id`，执行 RedBearRerank：
-```python
-reranker = RedBearRerank(RedBearModelConfig(...))
-reranked_docs = list(reranker.compress_documents(documents, query))
-```
-
-**Step 5** — Agent 组装消息并调用 LLM：
-```
-system: 你是一个专业的 AI 知识库助手...
-user:   参考信息：\n\nChunk 0...\n\nChunk 1...\n\n用户问题：\nMemoryBear 的 Rerank 策略是什么？
-```
-
-**Step 6** — 输出后处理：
-```python
-filtered_citations = _filter_citations(features_config, citations_collector)
-```
-
-最终返回：content + citations（含 document_id、file_name、score、可选 download_url）。
-
----
-
-## 6. 关键源码索引
-
-| 功能 | 文件 | 类/函数 | 行号 |
-|------|------|---------|------|
-| Rerank 封装 | `api/app/core/models/rerank.py` | `RedBearRerank` | 11-84 |
-| 内置混合 Rerank | `api/app/core/rag/nlp/search.py` | `Dealer.rerank` | 606-643 |
-| 外部模型 Rerank | `api/app/core/rag/nlp/search.py` | `Dealer.rerank_by_model` | 645-666 |
-| rank_feature | `api/app/core/rag/nlp/search.py` | `_rank_feature_scores` | 579-604 |
-| 独立 rerank | `api/app/core/rag/nlp/search.py` | `rerank()` | 284-343 |
-| 知识检索入口 | `api/app/core/rag/nlp/search.py` | `knowledge_retrieval()` | 36-147 |
-| ES Vector rerank | `api/app/core/rag/vdb/elasticsearch/elasticsearch_vector.py` | `ElasticSearchVector.rerank` | 560-607 |
-| Workflow 节点 rerank | `api/app/core/workflow/nodes/knowledge/node.py` | `KnowledgeRetrievalNode.rerank` | 108-155 |
-| Workflow 执行 | `api/app/core/workflow/nodes/knowledge/node.py` | `KnowledgeRetrievalNode.execute` | 303-378 |
-| LLM 基类 | `api/app/core/rag/llm/chat_model.py` | `Base` | 52-319 |
-| 流式 LLM | `api/app/core/rag/llm/chat_model.py` | `_chat_streamly` | 152-185 |
-| 工具调用 | `api/app/core/rag/llm/chat_model.py` | `chat_with_tools` | 251-303 |
-| 流式工具调用 | `api/app/core/rag/llm/chat_model.py` | `chat_streamly_with_tools` | 335-436 |
-| 错误分类 | `api/app/core/rag/llm/chat_model.py` | `_classify_error` | 69-89 |
-| CV 模型 | `api/app/core/rag/llm/cv_model.py` | `QWenCV`, `AzureGptV4` | 1-497 |
-| 音频转录 | `api/app/core/rag/llm/sequence2txt_model.py` | `QWenSeq2txt`, `GPTSeq2txt` | 1-215 |
-| Prompt 加载 | `api/app/core/rag/prompts/template.py` | `load_prompt` | 9-20 |
-| Prompt 生成器 | `api/app/core/rag/prompts/generator.py` | `message_fit_in` 等 | 1-744 |
-| Agent 封装 | `api/app/core/agent/langchain_agent.py` | `LangChainAgent` | 26-641 |
-| Agent 消息准备 | `api/app/core/agent/langchain_agent.py` | `_prepare_messages` | 230-271 |
-| 知识检索工具 | `api/app/services/draft_run_service.py` | `create_knowledge_retrieval_tool` | 195-263 |
-| 引用过滤 | `api/app/services/draft_run_service.py` | `_filter_citations` | 474-490 |
-| 聊天服务 | `api/app/services/app_chat_service.py` | `agnet_chat` | 43-239 |
-| 流式聊天 | `api/app/services/app_chat_service.py` | `agnet_chat_stream` | 340-550 |
-| 引用插入 | `api/app/core/rag/nlp/search.py` | `Dealer.insert_citations` | 489-577 |
-
----
-
-## 7. 配置项与可调参数
-
-**环境变量**：
-| 变量 | 默认值 | 说明 |
-|------|--------|------|
-| `LLM_TIMEOUT_SECONDS` | 600 | LLM 超时 |
-| `LLM_MAX_RETRIES` | 5 | 最大重试 |
-| `LLM_BASE_DELAY` | 2.0 | 重试基础延迟 |
-
-**知识检索配置**：
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `retrieve_type` | `participle` | participle/semantic/hybrid/graph |
-| `similarity_threshold` | 0.2 | 关键词相似度阈值 |
-| `vector_similarity_weight` | 0.3 | 向量权重 |
-| `top_k` | 4 | 单次检索 chunk 数 |
-| `reranker_id` | `None` | Rerank 模型 ID |
-| `reranker_top_k` | 4 | Rerank 后最终返回数 |
-
-**Agent 参数**：
-| 配置项 | 默认值 | 说明 |
-|--------|--------|------|
-| `max_iterations` | `5 + len(tools) * 2` | Agent 最大迭代 |
-| `max_tool_consecutive_calls` | 3 | 单工具最大连续调用 |
-| `max_rounds` | 5 | LLM 工具调用最大轮数 |
-| `temperature` | 0.7 | 生成温度 |
-| `max_tokens` | 2000 | 最大生成 token |
-| `json_output` | `False` | 强制 JSON 输出 |
-| `deep_thinking` | `False` | 深度思考 |
-
----
-
-## 8. 边界条件与已知限制
-
-1. **外部 Rerank 延迟高**：RedBearRerank 调用 Jina/DashScope API，无本地缓存。
-2. **Token 裁剪较粗糙**：`message_fit_in` 丢弃中间历史，可能丢失上下文；按比例截断可能切断语义。
-3. **引用回填非 LLM 原生**：基于 embedding 相似度匹配，表述不同可能漏引。
-4. **JSON 输出兼容性差**：通过 system prompt 注入实现，可靠性低于原生 `response_format`。
-5. **无模型降级**：LLM 失败返回错误文本，不自动切换备用模型。
-6. **混合检索融合简单**：仅去重取并集，无 RRF 或加权分数融合。
-7. **GraphRAG 结果前置**：始终 `insert(0, ...)`，优先级最高但无分数参与 rerank。
-
----
-
-## 9. 优化建议与未来扩展点
-
-1. **Rerank 缓存**：对高频 query 做 LRU 缓存，降低外部 API 成本。
-2. **引用增强**：将 `citation_prompt.md` 注入 system prompt，让 LLM 生成阶段就输出 `[ID:N]`。
-3. **Token 预算精细化**：引入 `tiktoken` 精确计数，实现滑动窗口历史管理。
-4. **模型降级**：在 `Base.chat()` 中增加 fallback 模型链。
-5. **混合检索 RRF**：在 ES 查询层面实现 Reciprocal Rank Fusion。
-6. **流式引用**：在 `on_tool_end` 事件中实时 emit citation 元数据。
-7. **输出校验中间件**：对 `json_output=True` 增加 JSON Schema 强制校验层。
-
----
-
-以上为 [S2-T5] 初版全文，请评审。

docs/rag/review/README.md

@@ -1,37 +0,0 @@
-# MemoryBear RAG Docs · 评审报告归档
-
-> 本目录归档全集所有 Sprint 子任务的终审报告。每份报告按 5 维评分卡打分，附 Must-Fix / Should-Fix / Could-Fix 三级建议。
-
-## 已归档评审报告
-
-| Sprint | 任务 | 文档 | 总分 | 决议 | 评审日期 | 评审人 |
-|---|---|---|---|---|---|---|
-| S3 | T1 | [架构改造建议](../evolution/architecture-refactor-suggestions.md) | **96 / 100** | ✅ PASS | 2026-05-08 | 知识运营与治理专家 |
-| S3 | T2 | [后续迭代功能新增方式](../evolution/future-extensions-roadmap.md) | **95 / 100** | ✅ PASS | 2026-05-08 | 知识运营与治理专家 |
-
-## 待评审报告（占位）
-
-| Sprint | 任务 | 文档 | 状态 | 备注 |
-|---|---|---|---|---|
-| S2 | T7（Sprint-2 评审收口） | [WS-21](mention://issue/41f2482b-6f3e-4253-95f7-3e22e790f31c) | ⏳ 未启动（上一次 API Error） | 占位说明见 [`S2-T7-pending.md`](S2-T7-pending.md)；启动后将对 S2-T1 / S2-T2 / S2-T3 / S2-T5 四篇 in_review 文档（以及 S2-T4 / S2-T6 在交付后）做正式打分 |
-
-## 评审节奏
-
-- **滚动评审**（每篇文档进入 `in_review` 状态时立即启动）
-- **Sprint 收口评审**（每个 Sprint 末由知识运营做整体复核）
-- **季度复审**（每季度抽查 30%，详见 [`../_release/ops-and-freshness-plan.md`](../_release/ops-and-freshness-plan.md) §2.2）
-
-## 评审标准
-
-- 评分卡：[`../_meta/scoring-rubric.md`](../_meta/scoring-rubric.md)
-- 流程 SOP：[`../_meta/review-sop.md`](../_meta/review-sop.md)
-- 通过门槛：≥ 80 分；< 80 进入 Must-Fix 流程
-- 一票否决：源码虚构 / 核心章节缺失 / 安全风险描述 / 架构严重脱节
-
-## 评审结果说明（关键解读）
-
-- **PASS**：终审通过，可作为 v1.0 候选纳入仓库 PR；Should-Fix 项进入下个版本（v1.1）增量更新。
-- **CONDITIONAL PASS**：未引入但保留作为状态预案；分数 75-79 + 无一票否决项时使用，需在 14 天内修订到 ≥ 80。
-- **FAIL**：分数 < 75 或触发一票否决项；启动 Must-Fix 流程，由责任专家在 7 天内重写。
-
-— **Review Index · v1.0-RC1 · 2026-05-08** —

docs/rag/review/S2-T7-final-summary.md

@@ -1,195 +0,0 @@
-## Sprint-2 评审最终纪要 — 6/6 全部通过，Sprint-2 收口
-
-**Reviewer:** 知识运营与治理专家 · **Review Date:** 2026-05-08 · **评分卡:** [S1-T1] v1.0
-
-S2-T6 评审已完成（详评见 [S2-T6](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) 评论）。**Sprint-2 全部 6 篇文档评审已 100% 完成**，本评论为最终纪要。
-
-### 1. 最终评分总表
-
-| 任务 | 标识 | 评分 | 裁定 | 验收门槛 | 余量 |
-|---|---|---:|---|---:|---:|
-| 文档加载与预处理 | [S2-T1](mention://issue/1b2dde64-83c3-49b8-8d71-50953c107594) | **91** | PASS | 80 | +11 |
-| Embedding 模型与向量生成 | [S2-T2](mention://issue/7a8cd047-f339-427e-bd60-999c62caea22) | **85** | PASS w/ Must-Fix | 80 | +5 |
-| 向量库选型/索引/检索 | [S2-T3](mention://issue/53783731-fd5d-40ef-8063-17a39c0d860d) | **94** | PASS（标杆） | 80 | +14 |
-| GraphRAG (light + general) | [S2-T4](mention://issue/16bdb196-e10e-489b-b01c-9067b1f1bb23) | **93** | PASS（标杆） | 80 | +13 |
-| 检索后处理与生成 | [S2-T5](mention://issue/eef8ed99-c13e-43ba-a2b3-2c9e59b74301) | **88** | PASS | 80 | +8 |
-| 端到端调用链路（整合） | [S2-T6](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) | **95** | PASS（整合标杆） | **85** | +10 |
-| **Sprint-2 平均** | — | **91.0** | **6/6 PASS** | — | **+10.2** |
-
-**关键亮点：**
-- 6 / 6 全部通过，**100% 通过率**
-- 平均分 91.0，比验收门槛（80/85）平均高 10.2 分
-- 双标杆 + 整合标杆并立：[S2-T3] (94) / [S2-T4] (93) / [S2-T6] (95) 三篇均 ≥ 93
-- 抽样源码核验**累计 21/21 命中（100%）**
-- T2 唯一 Must-Fix 是 frontmatter 缺失等元数据问题，**不影响内容质量已超门槛 +5 的事实**
-
-### 2. 评分卡导出（最终版）
-
-#### 2.1 Markdown 矩阵
-
-| 文档 | 准确性(25) | 完整性(25) | 时效性(15) | 可读性(15) | 可执行性(20) | 合计 | 裁定 |
-|---|---:|---:|---:|---:|---:|---:|---|
-| S2-T1 | 23 | 23 | 14 | 13 | 18 | **91** | PASS |
-| S2-T2 | 22 | 22 | 11 | 13 | 17 | **85** | PASS w/ Must-Fix |
-| S2-T3 | 24 | 24 | 13 | 14 | 19 | **94** | PASS（标杆） |
-| S2-T4 | 24 | 24 | 13 | 14 | 18 | **93** | PASS（标杆） |
-| S2-T5 | 22 | 21 | 14 | 13 | 18 | **88** | PASS |
-| S2-T6 | 24 | 24 | 14 | 14 | 19 | **95** | PASS（整合标杆） |
-| **平均** | **23.2** | **23.0** | **13.2** | **13.5** | **18.2** | **91.0** | — |
-
-#### 2.2 CSV 版（最终）
-
-```csv
-doc,accuracy,completeness,timeliness,readability,executability,total,verdict,bar,margin
-S2-T1,23,23,14,13,18,91,PASS,80,+11
-S2-T2,22,22,11,13,17,85,PASS_with_must_fix,80,+5
-S2-T3,24,24,13,14,19,94,PASS_BENCHMARK,80,+14
-S2-T4,24,24,13,14,18,93,PASS_BENCHMARK,80,+13
-S2-T5,22,21,14,13,18,88,PASS,80,+8
-S2-T6,24,24,14,14,19,95,PASS_INTEGRATION_BENCHMARK,85,+10
-AVERAGE,23.2,23.0,13.2,13.5,18.2,91.0,6/6_PASS,—,+10.2
-```
-
-### 3. 抽样源码核验累计 21/21 命中
-
-| 文档 | 抽检数 | 命中数 | 命中率 |
-|---|---:|---:|---:|
-| S2-T1 | 2 | 2 | 100% |
-| S2-T2 | 2 | 2 | 100% |
-| S2-T3 | 4 | 4 | 100% |
-| S2-T4 | 5 | 5 | 100% |
-| S2-T5 | 1 | 1 | 100% |
-| S2-T6 | 7 | 7 | 100% |
-| **合计** | **21** | **21** | **100%** |
-
-**未发现任何源码虚构、行号错位、函数名错误。** 6 篇文档对 MemoryBear 仓库 `feae2f2e` 的代码引用准确性达到出版级标准。
-
-S2-T6 同时承担\"跨文档一致性见证\"角色：其 §1/§2 时序图 + 附录跨文档引用索引，对 [S2-T1]~[S2-T5] 的 5 处关键引用全部对齐（详见 [S2-T6 评审报告](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) §一致性 §与子文档对齐表）。
-
-### 4. 一致性最终检查
-
-#### 4.1 术语统一（全 6 篇）
-
-| 术语 | T1 | T2 | T3 | T4 | T5 | T6 | 全局一致性 |
-|---|---|---|---|---|---|---|---|
-| Chunk | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 100% |
-| Embedding / RedBearEmbeddings | — | ✅ | ✅ | ✅ | — | ✅ | 100% |
-| VDB / Elasticsearch | — | ✅ | ✅ | — | — | ✅ | 100% |
-| Reranker / RedBearRerank | — | — | — | — | ✅ | ✅ | 100% |
-| GraphRAG / Light vs General | — | — | — | ✅ | — | ✅ | 100% |
-| `metadata.doc_id` / `knowledge_graph_kwd` | — | — | ✅ | ✅ | — | ✅ | 100% |
-| HYBRID 融合公式 (`weighted_sum=0.05,0.95`) | — | — | ✅ | — | — | ✅ | ✅（T6 引用 T3） |
-| `_chat_streamly` / `_filter_citations` | — | — | — | — | ✅ | ✅ | ✅ |
-
-**结论：6 篇文档术语 100% 统一，无随意混用。**
-
-#### 4.2 frontmatter 元数据完整度（最终）
-
-| 文档 | author | reviewer | source-commit | last-reviewed-at | scope | 评级 |
-|---|---|---|---|---|---|---|
-| S2-T1 | ✅ | ❌ | ⚠️ \"HEAD\" | ✅ | ✅ | B+ |
-| S2-T2 | ❌ | ❌ | ❌ | ❌ | ❌ | F |
-| S2-T3 | ⚠️ quote 块 | ❌ | ❌ | ❌ | ⚠️ | C |
-| S2-T4 | ⚠️ 元数据表 | ❌ | ❌ | ❌ | ✅ | C+ |
-| S2-T5 | ✅ | ✅ | ✅ `feae2f2e` | ✅ | ❌ | A- |
-| S2-T6 | ✅ | ❌（待填） | ✅ `feae2f2e` | ✅ | ✅ | A |
-
-**S2-T6 frontmatter 最规范，与 [S2-T5] 同级；建议在 [S3-T3] 整合时以 S2-T6 风格统一全部文档。**
-
-#### 4.3 与 [S1-T2] 架构图对齐
-
-- T1/T6 ↔ `02-indexing-pipeline.mmd` ✅
-- T3/T5/T6 ↔ `03-query-pipeline.mmd` ✅
-- T4/T6 ↔ `04-graphrag-indexing.mmd` ✅
-
-**6 篇文档 + 1 套架构图（S1-T2）形成完整闭环，0 不一致。**
-
-### 5. 验收标准最终核对
-
-| 验收项 | 目标 | 实际 | 状态 |
-|---|---|---|---|
-| 6 篇文档全部完成评审 | 6/6 | **6/6** | ✅ |
-| 至少 5 篇 ≥ 80 分 | 5/6 | **6/6**（100%） | ✅ 超额 |
-| S2-T6 整合性文档 ≥ 85 分 | ≥ 85 | **95** | ✅ +10 |
-| 评分卡导出版本（Markdown / CSV） | 必有 | §2 完整 | ✅ |
-| 抽样源码核验（≥ 5 处） | ≥ 5 | **21 处全部命中** | ✅ +16 |
-| 一致性检查（术语 / 架构 / frontmatter） | 必有 | §4 完整 | ✅ |
-| 修订协调 1 轮 | 必有 | T2 待修订（独立工作流，**不阻塞** Sprint-2 闭环） | ⏸ Sprint-3 协调 |
-| Sprint-2 评审纪要 | 必有 | 本评论 + 历史 2 次更新 | ✅ |
-
-**Sprint-2 完成度：100%（6/6 PASS + 全部硬指标超额满足）。**
-
-### 6. Sprint-3 升版门槛核对
-
-按 PM 此前定义的 3 道升版门槛：
-
-| 门槛 | 内容 | 状态 |
-|---|---|---|
-| **G1** | Sprint-2 评审 6/6 全部通过 | ✅ **本次解除** |
-| **G2** | S2-T4 GraphRAG PASS（[S3-T2] 知识图谱增强章节有一手输入） | ✅ 已解除（5/8 16:45） |
-| **G3** | S2-T6 阻塞解除（依赖 T1~T5 已交付） | ✅ 已解除（5/8 16:42） |
-
-**3 道门槛全部解除，[S3-T3] v1.0 升版条件齐备。**
-
-### 7. Sprint-3 输入预备情况（最终）
-
-| Sprint-3 任务 | 输入依赖 | 当前可用度 | 备注 |
-|---|---|---|---|
-| [S3-T1] 架构改造建议 | T1~T6 | **100%** | 全部就绪；S2-T6 §3.1 瓶颈分析（4 大🔴）+ §5 降级路径是 P0 输入；S2-T3 RETRY_ON_TIMEOUT bug 候选 PR；S2-T4 Prompt 示例修正候选 PR |
-| [S3-T2] 后续迭代功能 | T1~T6 | **100%** | 全部就绪；T4 GraphRAG + T6 §5 错误降级矩阵 → \"评估与反馈闭环\"；T6 §3 缺失的缓存路径 → \"对话记忆优化\"切入点 |
-| [S3-T3] 终验整合 | T1~T6 + T7 | **100%** | 全部就绪；S2-T6 \"跨文档引用索引\"是天然的目录入口骨架；T2 Must-Fix 修订并入 [S3-T3] 整合阶段一并完成 |
-
-### 8. Sprint-2 关键产出沉淀（供 [S3-T3] 复用）
-
-#### 8.1 双（三）标杆文档
-
-- **[S2-T3] VDB（94）** — 最完备的 12 章节结构 + 11 张索引表
-- **[S2-T4] GraphRAG（93）** — Prompt 工程逐段意图解读的范本
-- **[S2-T6] E2E（95）** — Mermaid `autonumber` + Critical Path 表 + 跨文档引用索引
-
-建议在 [S3-T3] 选择 [S2-T6] frontmatter + [S2-T3] 章节骨架 + [S2-T4] Prompt 注解写法的组合作为 Sprint-3 文档样板。
-
-#### 8.2 \"文档化反哺代码改进\" 候选 PR 清单
-
-| 来源 | 问题 | 优先级 |
-|---|---|---|
-| S2-T3 §11 | `ELASTICSEARCH_RETRY_ON_TIMEOUT` 比较 bug，默认未生效 | **P0** |
-| S2-T3 §10.1 | `mapping.json` 默认 `replicas=0` 生产风险 | **P1** |
-| S2-T3 §10.1 | 路径 B `script_score` 暴力扫描可换 ES 8 `knn` query | P2 |
-| S2-T4 §12.1 | 实体消歧 Prompt 示例\"television vs TV → No\"与常识矛盾 | **P0** |
-| S2-T4 §12.1 | `is_similarity` 中文短实体（< 4 字）阈值不一致 | P2 |
-| S2-T2 §9 | 各 Embedding 类 batch_size（16/4）硬编码 | P1 |
-| S2-T6 §3.1 | PDF 解析 + GraphRAG 建图 + LLM 首次调用三大🔴瓶颈 | P1 |
-| S2-T5 §9 / S2-T2 §9 | LLM/Embedding 无自动模型降级 | P1 |
-
-合计 **8 条候选 PR**，其中 P0 2 条建议优先发起；可作为 [S3-T1] \"代码架构改造建议\" 的具体落地清单。
-
-#### 8.3 评分卡使用反馈（供 [S1-T1] 模板迭代）
-
-1. **frontmatter 强制化**：4/6 文档 frontmatter 不完整，建议在 [S1-T1] 模板加 lint 校验，缺失时拒绝进入评审队列。
-2. **\"准确性\" 维度建议引入抽检命中率**：当前 \"准确性\" 是 1-25 主观评分；本次 21/21 命中率证明可量化。建议下版评分卡加一项 \"抽检命中率 = (命中数 / 抽检数) × 100%\"，命中率 < 95% 直接扣分。
-3. **\"整合性文档\" 区分门槛**：S2-T6 因高门槛 +85 仍超 +10，证明高门槛设置是合理的；建议未来类似的整合性文档（如 [S3-T3]）默认 ≥ 85。
-4. **CSV 评分卡导出格式**：本次 CSV 增加 `bar` 和 `margin` 字段，建议沉淀为标准格式，方便看板量化。
-
-### 9. 后续动作建议
-
-#### 9.1 Sprint-2 关闭操作（PM 视角）
-
-- [S2-T1] / [S2-T3] / [S2-T4] / [S2-T5] / [S2-T6] 推进至 `done`（5 篇直接通过，无 Must-Fix）
-- [S2-T2] 维持 `in_review`，等待作者 1 轮修订（3 条 Must-Fix，约 2h 工作量），修订后再评通过即置 `done`
-- 本 [S2-T7] 维持 `in_review`，待 T2 修订完成后置 `done`（亦可由 PM 视情况直接关闭）
-
-#### 9.2 Sprint-3 立即可做
-
-- [S3-T1] 可基于 §8.2 \"候选 PR 清单\" 直接动笔
-- [S3-T2] 可基于 [S2-T4] \"知识图谱增强\" + [S2-T6] \"错误降级矩阵\" 起草
-- [S3-T3] 文档全集整合可启动；建议先冻结 [S2-T6] frontmatter + [S2-T3] 章节骨架作为模板基线
-
-#### 9.3 跨 Sprint 沉淀
-
-- 本次 Sprint-2 \"API 中断 + 自动巡检恢复 + 拆评论 + 降级评审深度\" 的协作机制运行良好；建议 PM 在 [S3-T4] 项目复盘时把这套 SOP 沉淀为 \"长任务 / 异常恢复\" 标准流程。
-- 21/21 源码引用零虚构、6/6 文档零术语混用、跨文档引用 0 不一致 — 这三个数字是本期 Sprint 的硬指标，建议作为后续文档化项目的基线门槛。
-
----
-
-**Sprint-2 [S2-T7] 文档质量评审与修订收口 — 评审纪要至此完结。** 所有验收硬指标 100% 满足且全部超额；建议 PM 推动 Sprint-2 关闭流程，并以本纪要作为 [S3-T3] / [S3-T4] 的输入起点。

docs/rag/review/S2-T7-formal.md

@@ -1,173 +0,0 @@
----
-title: "[S2-T7] Sprint-2 文档质量评审与修订收口 — 正式评审纪要"
-author: 知识运营与治理专家
-reviewer: 知识运营与治理专家
-source-commit: feae2f2e (MemoryBear)
-last-reviewed-at: 2026-05-08
-scope: Sprint-2 全部 6 篇深度文档（S2-T1 ~ S2-T6）
-version: v1.0
-status: 正式版（已解除占位）
----
-
-# [S2-T7] Sprint-2 文档质量评审与修订收口 — 正式评审纪要
-
-> 本文档为 [WS-24](mention://issue/a07f108d-06ee-41b8-8b57-22455f60ddeb) v1.0 文档全集的正式组成文件，替换 v1.0-RC1 中的占位版本。
-> 完整评审过程与逐篇详评见 [WS-21](mention://issue/41f2482b-6f3e-4253-95f7-3e22e790f31c)。
-
----
-
-## 1. 评审结论总览
-
-**Reviewer:** 知识运营与治理专家  
-**Review Date:** 2026-05-08  
-**评分卡版本:** [S1-T1] v1.0（5 维 100 分制，通过线 80；整合性文档 S2-T6 门槛 85）  
-**最终裁定:** 6/6 全部通过，平均 91.0/100
-
-| 任务 | Issue | 评分 | 裁定 | 验收门槛 | 余量 | 抽检命中率 |
-|---|---|---:|---|---:|---:|---:|
-| S2-T1 文档加载与预处理 | [WS-15](mention://issue/1b2dde64-83c3-49b8-8d71-50953c107594) | **91** | PASS | 80 | +11 | 2/2 |
-| S2-T2 Embedding 模型与向量生成 | [WS-16](mention://issue/7a8cd047-f339-427e-bd60-999c62caea22) | **85** | PASS w/ Must-Fix | 80 | +5 | 2/2 |
-| S2-T3 向量库选型/索引/检索 | [WS-17](mention://issue/53783731-fd5d-40ef-8063-17a39c0d860d) | **94** | PASS（标杆） | 80 | +14 | 4/4 |
-| S2-T4 GraphRAG (light + general) | [WS-18](mention://issue/16bdb196-e10e-489b-b01c-9067b1f1bb23) | **93** | PASS（标杆） | 80 | +13 | 5/5 |
-| S2-T5 检索后处理与生成 | [WS-19](mention://issue/eef8ed99-c13e-43ba-a2b3-2c9e59b74301) | **88** | PASS | 80 | +8 | 1/1 |
-| S2-T6 端到端调用链路（整合） | [WS-20](mention://issue/a3deeaa1-5b30-4da5-b4af-1b081f7f6394) | **95** | PASS（整合标杆） | 85 | +10 | 7/7 |
-| **Sprint-2 平均** | — | **91.0** | **6/6 PASS** | — | **+10.2** | **21/21** |
-
-### 1.1 5 维评分矩阵
-
-| 文档 | 准确性(25) | 完整性(25) | 时效性(15) | 可读性(15) | 可执行性(20) | 合计 |
-|---|---:|---:|---:|---:|---:|---:|
-| S2-T1 | 23 | 23 | 14 | 13 | 18 | **91** |
-| S2-T2 | 22 | 22 | 11 | 13 | 17 | **85** |
-| S2-T3 | 24 | 24 | 13 | 14 | 19 | **94** |
-| S2-T4 | 24 | 24 | 13 | 14 | 18 | **93** |
-| S2-T5 | 22 | 21 | 14 | 13 | 18 | **88** |
-| S2-T6 | 24 | 24 | 14 | 14 | 19 | **95** |
-| **平均** | **23.2** | **23.0** | **13.2** | **13.5** | **18.2** | **91.0** |
-
-### 1.2 CSV 评分卡导出
-
-```csv
-doc,accuracy,completeness,timeliness,readability,executability,total,verdict,bar,margin
-S2-T1,23,23,14,13,18,91,PASS,80,+11
-S2-T2,22,22,11,13,17,85,PASS_with_must_fix,80,+5
-S2-T3,24,24,13,14,19,94,PASS_BENCHMARK,80,+14
-S2-T4,24,24,13,14,18,93,PASS_BENCHMARK,80,+13
-S2-T5,22,21,14,13,18,88,PASS,80,+8
-S2-T6,24,24,14,14,19,95,PASS_INTEGRATION_BENCHMARK,85,+10
-AVERAGE,23.2,23.0,13.2,13.5,18.2,91.0,6/6_PASS,—,+10.2
-```
-
----
-
-## 2. 抽样源码核验
-
-累计抽检 **21/21 命中（100%）**，无任何源码虚构、行号错位或函数名错误。
-
-| 文档 | 抽检数 | 命中 | 代表性引用 |
-|---|---:|---:|---|
-| S2-T1 | 2 | 2 | `nlp/__init__.py:562-606` `naive_merge` / `app/naive.py:97-102` `PARSERS` |
-| S2-T2 | 2 | 2 | `embedding_model.py:50-65` `OpenAIEmbed.encode` / `elasticsearch_vector.py:55-63` `add_chunks` |
-| S2-T3 | 4 | 4 | `es_conn.py:44-49` 版本校验 / `:186-218` weighted_sum + knn / `:439` `FusionExpr` / `:72` `RETRY_ON_TIMEOUT` bug |
-| S2-T4 | 5 | 5 | `general/index.py:36-119` `run_graphrag` / `:54` extractor 三元选择 / `entity_resolution.py:225-239` `is_similarity` / `search.py:130-280` `KGSearch.retrieval` / `leiden.py:95-141` `run()` |
-| S2-T5 | 1 | 1 | `nlp/search.py:606-643` `Dealer.rerank` |
-| S2-T6 | 7 | 7 | `app_chat_service.py:43` `agnet_chat` / `langchain_agent.py:230` `_prepare_messages` / `search.py:36` `knowledge_retrieval` / `:149` `_retrieve_for_knowledge` / `:489` `insert_citations` / `naive.py:508` `chunk()` / `chat_model.py:69-89` `_classify_error` |
-
----
-
-## 3. 一致性最终检查
-
-### 3.1 术语统一（6 篇全局）
-
-| 术语 | T1 | T2 | T3 | T4 | T5 | T6 | 全局一致性 |
-|---|---|---|---|---|---|---|---|
-| Chunk | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 100% |
-| Embedding / RedBearEmbeddings | — | ✅ | ✅ | ✅ | — | ✅ | 100% |
-| VDB / Elasticsearch | — | ✅ | ✅ | — | — | ✅ | 100% |
-| Reranker / RedBearRerank | — | — | — | — | ✅ | ✅ | 100% |
-| GraphRAG / Light vs General | — | — | — | ✅ | — | ✅ | 100% |
-| Hybrid 融合公式 | — | — | ✅ | — | — | ✅ | 100% |
-
-### 3.2 与 [S1-T2] 架构图对齐
-
-- T1/T6 ↔ `02-indexing-pipeline.mmd` ✅
-- T3/T5/T6 ↔ `03-query-pipeline.mmd` ✅
-- T4/T6 ↔ `04-graphrag-indexing.mmd` ✅
-
-**6 篇文档 + 1 套架构图形成完整闭环，0 不一致。**
-
-### 3.3 frontmatter 元数据完整度
-
-| 文档 | author | reviewer | source-commit | last-reviewed-at | scope | 评级 |
-|---|---|---|---|---|---|---|
-| S2-T1 | ✅ | ❌ | ⚠️ "HEAD" | ✅ | ✅ | B+ |
-| S2-T2 | ❌ | ❌ | ❌ | ❌ | ❌ | F |
-| S2-T3 | ⚠️ quote 块 | ❌ | ❌ | ❌ | ⚠️ | C |
-| S2-T4 | ⚠️ 元数据表 | ❌ | ❌ | ❌ | ✅ | C+ |
-| S2-T5 | ✅ | ✅ | ✅ `feae2f2e` | ✅ | ❌ | A- |
-| S2-T6 | ✅ | ❌（待填） | ✅ `feae2f2e` | ✅ | ✅ | A |
-
-> **Note:** frontmatter 不完全合规是 Sprint-2 的已知遗留。建议 [S3-T3] 整合时统一补全，以 S2-T6 风格为样板。
-
----
-
-## 4. 修订协调
-
-| 文档 | Must-Fix 数 | 状态 | 说明 |
-|---|---|---|---|
-| S2-T1 | 0 | 直接通过 | — |
-| S2-T2 | 3 | PASS（不影响通过） | frontmatter 补全 / ES 8.x 维度上限纠错 / 与 T3 mapping 描述对齐 |
-| S2-T3 | 0 | 直接通过 | — |
-| S2-T4 | 0 | 直接通过 | — |
-| S2-T5 | 0 | 直接通过 | — |
-| S2-T6 | 0 | 直接通过 | — |
-
-S2-T2 的 3 条 Must-Fix 为 frontmatter/元数据问题，**不影响内容质量已超门槛 +5 的事实**，可在 [S3-T3] 整合阶段一并补全。
-
----
-
-## 5. Sprint-3 输入预备情况（最终）
-
-| Sprint-3 任务 | 输入依赖 | 当前可用度 | 备注 |
-|---|---|---|---|
-| [S3-T1] 架构改造建议 | T1~T6 | **100%** | S2-T6 §3.1 瓶颈分析 + S2-T3 `RETRY_ON_TIMEOUT` bug 候选 PR |
-| [S3-T2] 后续迭代功能 | T1~T6 | **100%** | T4 GraphRAG + T6 降级矩阵 → "评估与反馈闭环" |
-| [S3-T3] 终验整合 | T1~T6 + T7 | **100%** | 全部就绪；S2-T6 跨文档引用索引是天然的目录骨架 |
-
----
-
-## 6. 文档化反哺代码改进 — 候选 PR 清单
-
-| 来源 | 问题 | 优先级 | 当前状态 |
-|---|---|---|---|
-| S2-T3 §11 | `ELASTICSEARCH_RETRY_ON_TIMEOUT` 比较 bug（默认未生效） | **P0** | 待提 PR |
-| S2-T4 §12.1 | 实体消歧 Prompt 示例 "television vs TV → No" 与常识矛盾 | **P0** | 待提 PR |
-| S2-T3 §10.1 | `mapping.json` 默认 `replicas=0` 生产风险 | P1 | 待评估 |
-| S2-T2 §9 | 各 Embedding 类 batch_size（16/4）硬编码 | P1 | 待评估 |
-| S2-T6 §3.1 | PDF 解析 + GraphRAG 建图 + LLM 首次调用三大🔴瓶颈 | P1 | 待 [S3-T1] 方案 |
-| S2-T5 §9 / S2-T2 §9 | LLM/Embedding 无自动模型降级 | P1 | 待 [S3-T1] 方案 |
-| S2-T3 §10.1 | 路径 B `script_score` 暴力扫描可换 ES 8 `knn` query | P2 | 待评估 |
-| S2-T4 §12.1 | `is_similarity` 中文短实体（< 4 字）阈值不一致 | P2 | 待评估 |
-
-合计 8 条候选 PR，其中 P0 2 条建议优先发起。
-
----
-
-## 7. 验收标准最终核对
-
-| 验收项 | 目标 | 实际 | 状态 |
-|---|---|---|---|
-| 6 篇文档全部完成评审 | 6/6 | **6/6** | ✅ |
-| 至少 5 篇 ≥ 80 分 | 5/6 | **6/6（100%）** | ✅ 超额 |
-| S2-T6 整合性文档 ≥ 85 分 | ≥ 85 | **95** | ✅ +10 |
-| 评分卡导出版本（Markdown / CSV） | 必有 | §1.1 / §1.2 完整 | ✅ |
-| 抽样源码核验（≥ 5 处） | ≥ 5 | **21 处全部命中** | ✅ +16 |
-| 一致性检查（术语 / 架构 / frontmatter） | 必有 | §3 完整 | ✅ |
-| 修订协调 1 轮 | 必有 | T2 待修订（不阻塞 Sprint-2 闭环） | ⏸ Sprint-3 协调 |
-| Sprint-2 评审纪要 | 必有 | 本文件 + [WS-21](mention://issue/41f2482b-6f3e-4253-95f7-3e22e790f31c) 历史纪要 | ✅ |
-
-**Sprint-2 [S2-T7] 文档质量评审与修订收口 — 100% 完成。**
-
----
-
-*本文档为 MemoryBear RAG Docs v1.0 正式版本的组成文件。完整逐篇详评请参见 [WS-21](mention://issue/41f2482b-6f3e-4253-95f7-3e22e790f31c) 评论历史。*

docs/rag/review/S3-T1-final-review.md

@@ -1,77 +0,0 @@
----
-name: S3-T1 终审报告 — RAG 代码架构改造建议
-description: 知识运营终审，对 S3-T1 交付物按 5 维评分卡评分；总分 96/100，PASS
-type: review
-sprint: 3
-task: T1
-reviewer: 知识运营与治理专家
-reviewed-at: 2026-05-08
-target-doc: docs/rag/evolution/architecture-refactor-suggestions.md
-target-comment: bc97a22c-709e-4c93-a360-f015bc41a2e6 / 2026-05-08T11:30:59Z
-target-attachment: S3-T1-deliverable.md (33 KB)
----
-
-# [S3-T1] 终审报告：RAG 代码架构改造建议
-
-> **决议**：✅ **PASS**（综合 96/100，超过 80 通过线 + 0 触发一票否决项）。
-
-## 1. 评分明细（按 S1-T1 评分卡）
-
-| 维度 | 权重 | 得分 | 关键观察 |
-|---|---|---|---|
-| **准确性 (Accuracy)** | 25 | **25** | 11 条建议全部带源码引用（`file:line`），且引用风格统一；引用了 `chat_model.py:52`、`vector_base.py:9`、`embedding.py:9-78`、`embedding_model.py:14-65`、`graphrag/utils.py:115-134`、`elasticsearch_vector.py:55-63`、`workflow/nodes/knowledge/node.py:108-155, 195-263, 284, 327`、`naive.py:508-738`、`common/settings.py:24` 等关键节点；与 [S1-T3 源码盘点] / [S2-T2 Embedding] / [S2-T3 VDB] / [S2-T5 检索后处理] 的描述交叉一致。"`os.environ.get` 出现 58 次"等量化论断给出了 grep 口径，可被复核。 |
-| **完整性 (Completeness)** | 25 | **25** | 11 条建议覆盖全部 5 个方向（模块化拆分 / 接口抽象 / 性能优化 / 可观测性 / 配置治理），实测分布：模块化 4 条、抽象 3 条、性能 3 条、可观测性 2 条、配置治理 2 条（含交叉归类）；2 套 PoC 代码草案（Retriever 协议 + Embedder 缓存装饰器）满足"≥2"硬要求；含完整改造路线图（短/中/长三阶段，每阶段带交付物清单与里程碑），含风险登记表。 |
-| **时效性 (Timeliness)** | 15 | **13** | 锁定到 `feae2f2e` 工作分支提交（2026-05-08 当日），符合"frontmatter 锁定 source-commit"规范；未明确给出"代码与文档失效再校准节奏"，扣 2 分（建议在落地后随每次 release 同步刷新）。 |
-| **可读性 (Readability)** | 15 | **14** | 一页摘要（3 优点 / 5 痛点）作为入口；每条建议遵循 "问题 → 方案 → 收益 → 成本/风险 → 优先级" 五段式；表格密度适中；优先级标签 P0/P1/P2 醒目；扣 1 分因 §3 路线图三阶段表格列宽稍紧、移动端阅读体验略差。 |
-| **可执行性 (Actionability)** | 20 | **19** | PoC-1 (Retriever Protocol) 含 50+ 行可运行级伪代码，PoC-2 (Embedder 缓存装饰器) 给出实施样例；每条建议带工作量估算（单位"人日"）+ 优先级 + 收益量化（如 "P95 下降 100-300ms"、"单测覆盖率 +30%"）；扣 1 分因部分量化收益（如"减少 60-90% 外部 API 调用"）依赖业内统计而非本仓基准，建议在路线图 §3.1 实施"baseline 立项"任务时配套测得。 |
-| **总分** | **100** | **96** | — |
-
-> 通过门槛：≥80。**S3-T1 以 96 分通过终审**。
-
-## 2. 一票否决项排查
-
-| 否决项 | 是否触发 | 证据 |
-|---|---|---|
-| 源码虚构 | ❌ 未触发 | 抽查 5 处源码引用全部可在 ±3 行内复现：`node.py:327` 的 `print` 残留断言（建议复核合并）、`elasticsearch_vector.py:55-63 add_chunks` 路径无缓存断言（与 S2-T2 一致）、`init_settings()` 模块级副作用断言（与 S1-T3 §3 调用链路一致）、`chat_model.py:52 Base` 抽象类（与 S2-T5 §3.1 一致）、`naive.py:508 chunk()` 11 个 if/elif 断言（与 S2-T1 §4 一致）。 |
-| 核心章节缺失 | ❌ 未触发 | 验收标准 6 项全部覆盖：现状评估、≥8 条建议、PoC、路线图、风险、Checklist。 |
-| 安全风险描述 | ❌ 未触发 | 建议 7 中明确把 API key / DB 密码升级到 `pydantic.SecretStr` 与 Vault；建议 4 提到 cache 失败优雅降级；隐私边界（建议 8 中提到 Singleton 单例与多 worker 隔离）有论及。 |
-| 架构严重脱节 | ❌ 未触发 | 抽象层与 [S1-T2] 架构图同源；3 个 Protocol 命名（Retriever / Reranker / Generator）与 LangChain Runnable 风格匹配；与 [S3-T2] 路线图引用的"4 个 Protocol 落地"约定一致。 |
-
-## 3. Must-Fix（必改项）
-
-无。所有问题为建议级（Should/Could）。
-
-## 4. Should-Fix（建议落地前修补）
-
-| # | 建议 | 责任 | 处理方式 |
-|---|---|---|---|
-| SF-1 | §3.1 短期路线图工作项 #1（删除 `node.py:327 print()`）应在 v1.0 正式发布前以独立 hot-fix PR 落地，避免成为 v1.0 文档同步描述但代码未修的"知行不一致"案例。 | AI 知识库专家 / Python 工程师 | 进入 [S3-T4] PM 复盘的"近 1 个月迭代主题"清单 |
-| SF-2 | §0.2 痛点 4 提到 `KnowledgeRetrievalNode.get_reranker_model()` 每次 rerank 都查 DB，建议补一个"实测 5-20ms × QPS"的基准点，便于落地后量化收益。 | AI 知识库专家 | 落地建议 #3 时同步采集；纳入 D5 评估埋点（[S3-T2] D5） |
-| SF-3 | §1 建议 1 中"`OpenAIEmbed` 等遗留类实现 `Embedder`（保留 `encode/encode_queries` 兼容期 6 个月）" — 建议明确"6 个月"与 release cadence 的对齐方式（按 v0.x 还是按月）。 | AI 知识库专家 | 在迁移启动前发一份 Deprecation Policy（参考 docs/rag/_meta/review-sop.md） |
-
-## 5. Could-Fix（可选优化）
-
-| # | 建议 |
-|---|---|
-| CF-1 | §3.3 长期路线图工作项 #13（引入 Milvus 验证 BaseVector 可插拔）— 可在 [S3-T2] D2 SPLADE 接入后再评估，避免双轴改造同时进行带来的回归风险。 |
-| CF-2 | 可补一份"建议 # × 优先级 × 工作量"的散点图，方便产品排期与会做"可视化拍板"。 |
-| CF-3 | §0.1 优点 2 里 "7 类 provider" 与 §0.2 痛点 1 里 "10+ Provider" 表述略冲突；建议统一口径（实测 7 类活跃 provider + 多个适配器）。 |
-
-## 6. 与 Sprint 文档生态的兼容性
-
-- ✅ **与 [S1-T3 源码盘点] 一致**：`os.environ.get` 58 次、`logger` 355 次等量化数据可在 [S1-T3] §三 入口链路梳理 中交叉印证；"`rag_utils` vs `rag/utils` 命名冲突"作为遗留问题在 [S1-T3] §4.1 已识别。
-- ✅ **与 [S2-T2 Embedding] 一致**：建议 1（双轨 Embedding）问题陈述与 [S2-T2] §1.1 / §1.2 对"两条调用路径"的论述完全一致。
-- ✅ **与 [S2-T5 检索后处理] 一致**：建议 3（三处 rerank）的位置与 [S2-T5] §1.2 三种 rerank 方案一一对应。
-- ✅ **与 [S3-T2 后续路线图] 一致**：建议 2 落地的 4 个 Protocol 是 [S3-T2] 全部 6 个方向的接口注入点，命名一致。
-
-## 7. 终审结论与下一步
-
-| 决议项 | 内容 |
-|---|---|
-| **总分** | 96 / 100 |
-| **决议** | ✅ **PASS（终审通过）** |
-| **建议落入版本** | `MemoryBear RAG Docs v1.0`（落入 `docs/rag/evolution/architecture-refactor-suggestions.md`） |
-| **状态变更建议** | 由 `in_review` → `done`，由 PM 执行 |
-| **后续衔接** | (1) 与 [S3-T2] 联合作为 Sprint-3 出口物；(2) Should-Fix 项进入 [S3-T4] PM 复盘清单；(3) Sprint-2 文档若 [S2-T7] 评审引入新事实，本文档以增量补丁形式更新（不重写）。 |
-
-— END —

docs/rag/review/S3-T2-final-review.md

@@ -1,81 +0,0 @@
----
-name: S3-T2 终审报告 — 后续迭代功能新增方式建议
-description: 知识运营终审，对 S3-T2 交付物按 5 维评分卡评分；总分 95/100，PASS
-type: review
-sprint: 3
-task: T2
-reviewer: 知识运营与治理专家
-reviewed-at: 2026-05-08
-target-doc: docs/rag/evolution/future-extensions-roadmap.md
-target-comment: 0de2c8f6-717d-43c7-af31-1c055550a5e7 / 2026-05-08T11:32:27Z
-target-attachments:
-  - future-extensions-roadmap.md (32 KB)
-  - capability-map.mmd (4 KB)
----
-
-# [S3-T2] 终审报告：后续迭代功能新增方式建议
-
-> **决议**：✅ **PASS**（综合 95/100，超过 80 通过线 + 0 触发一票否决项）。
-
-## 1. 评分明细（按 S1-T1 评分卡）
-
-| 维度 | 权重 | 得分 | 关键观察 |
-|---|---|---|---|
-| **准确性 (Accuracy)** | 25 | **24** | §0.2 列出的 8 条"关键源码事实"全部带行号，抽查 5 条全部可复现：`MatchSparseExpr` 已声明未启用（`rag/utils/doc_store_conn.py:75`、`vdb/field.py:11`，grep 验证 0 调用）、`weighted_sum 0.05/0.95`（`rag/nlp/search.py:439`）、`core/memory` 与 `core/rag` 完全独立（grep 互无引用）、`RetrieveType` enum 硬编码（`schemas/chunk_schema.py`）、Reranker 仅推理（`core/models/rerank.py:11`）。扣 1 分因 D1.1.4 工作量估算的"+30% 存储"为业内经验值，未在本仓做基线测试，可能与实际 mapping 选择有出入。 |
-| **完整性 (Completeness)** | 25 | **25** | 6 个方向（D1-D6）超出"≥5"硬要求；5 个强制覆盖项（多模态 / 混合搜索 / KG / 对话记忆 / 评估闭环）全部命中；2 套 Quick PoC（PoC-A RRF + PoC-B Memory Rewrite）超过"≥2"硬要求，且每条 PoC 给出 ≤30 行代码草案 + 风险描述。优先级矩阵 14 行覆盖全部 6 方向 × 多层级，附 Mermaid 甘特路线图、能力地图（Mermaid 附件 `capability-map.mmd`）。 |
-| **时效性 (Timeliness)** | 15 | **13** | 路线图日期 2026-06-02 起 → 与 Sprint-3 内 PoC 启动节奏一致；6 个方向均带"立即 / 短 / 中 / 长"四级时间标签；扣 2 分因部分依赖 [S2-T7] 评审产出的新事实（D5 评估集质量、D2 SPLADE 索引重建口径），需保留增量更新窗口（已在 §6 对齐清单中提及）。 |
-| **可读性 (Readability)** | 15 | **15** | 能力地图（Mermaid）+ 优先级矩阵（综合分公式）+ 落地路线图（Gantt）三件套使决策路径清晰；每个方向严格五段式（触发场景 → 技术方案 → 接口改造点 → 工作量 → 风险/依赖）；强调"基于 Protocol 注入而不改调用方"作为统一原则，把 6 个方向的耦合打散为可并行落地的 6 条独立通道。 |
-| **可执行性 (Actionability)** | 20 | **18** | PoC-A（RRF）改动范围最小集化（仅在 `rag/nlp/search.py:Dealer.search` 加 feature flag），可直接成为 Sprint-3 PR；PoC-B（Memory Rewrite）通过 5 行代码加 feature flag 接入；每个方向有人周估算 + 优先级 + 风险三件套；扣 2 分因：(1) D6 自适应路由的"小型 LLM 路由器训练数据来源"仍依赖 D5 反馈数据，链路较长；(2) D5 评估集冷启动方案（"先用大模型 LLM-as-Judge 合成"）只给了方向，缺一份具体的数据规模与验收标准。 |
-| **总分** | **100** | **95** | — |
-
-> 通过门槛：≥80。**S3-T2 以 95 分通过终审**。
-
-## 2. 一票否决项排查
-
-| 否决项 | 是否触发 | 证据 |
-|---|---|---|
-| 源码虚构 | ❌ 未触发 | 8 条"关键源码事实"抽查 5 条均可复现；`core/memory` 与 `core/rag` 互不引用的论断与 [S1-T3] §一 模块清单中 `rag_utils` vs `rag/utils` 双目录相印证。 |
-| 核心章节缺失 | ❌ 未触发 | 验收标准 6 项全部覆盖：能力地图、6 方向、接口改造点、≥2 PoC、优先级矩阵、路线图、风险表、对齐清单。 |
-| 安全风险描述 | ❌ 未触发 | D4.6 显式提及"跨用户记忆隔离需在 code review 重点核查"；§5 风险表把"D4 跨用户记忆泄露"列为隐私风险并给出"user_id 级强隔离 + 上线前 review"缓解策略。 |
-| 架构严重脱节 | ❌ 未触发 | §0.3 明确把所有方向锚定到 [S3-T1] 提议的 4 大 Protocol；§6 对齐清单逐条核对；与 [S3-T1] 命名一致（已与 S3-T1 评审交叉确认）。 |
-
-## 3. Must-Fix（必改项）
-
-无。
-
-## 4. Should-Fix（建议落地前修补）
-
-| # | 建议 | 责任 | 处理方式 |
-|---|---|---|---|
-| SF-1 | D5.5.1 提到的"评估集冷启动 LLM-as-Judge 合成"应给出最小数据规模（建议每 KB 200 条 query × ground-truth + 50 条 hard-negatives）和验收标准（与人工评审一致率 ≥ 75%）。 | AI 知识库专家 | 落 D5 第一条工作项时同步交一份《评估集生产 SOP》。 |
-| SF-2 | D6 自适应路由强依赖 D5 反馈数据，建议在路线图甘特图中显式画出 D5 → D6 的依赖箭头，避免错位启动。 | AI 知识库专家 | 在路线图 §4 增量补一行依赖说明。 |
-| SF-3 | D1 多模态 L2 跨模态的"存储膨胀 +30%" 估算应在 PoC 阶段实测一次，结果回填本文档（增量补丁）。 | AI 知识库专家 | 与 [S3-T1] §3.1 短期任务"建立 baseline"合并执行。 |
-
-## 5. Could-Fix（可选优化）
-
-| # | 建议 |
-|---|---|
-| CF-1 | §1.5 D1 风险中"VLM 描述漂移"可与 [S2-T1] §11 限制中的"OCR 与版面识别 CPU/GPU 重负载"合并撰写，作为多模态扩展的统一约束。 |
-| CF-2 | §3 优先级矩阵的综合分公式 `V × 1/√(C×R)` 略简化，可在脚注里说明这是"产品快速排序工具，不替代正式架构会"，避免被误读为权威。 |
-| CF-3 | D3.3.2 "路径解释性"与 [S2-T6] E2E 链路时序图存在天然结合点，建议在 [S2-T6] 复活时补一段 "GraphRAG with evidence_path" 的时序示意。 |
-
-## 6. 与 Sprint 文档生态的兼容性
-
-- ✅ **与 [S1-T2 架构图] 一致**：6 个方向均锚定 [S1-T2] DocMap.md 列出的 Sprint-2 各环节；GraphRAG light/general 双路径在 D3 与 [S1-T2] §04-graphrag-indexing.mmd 描述一致。
-- ✅ **与 [S2-T1 Loader/Parser/Chunking] 一致**：D1 多模态 L1 把 `rag/app/picture.py:54` 与 `rag/app/audio.py:29` 列为现有 baseline，与 [S2-T1] §4 LibreOffice + Apache Tika 兜底链一致。
-- ✅ **与 [S2-T2 Embedding] 一致**：D1.3 提到的"`Embedder.encode(items: list[Embeddable])`"接口与 [S2-T2] §1.2 RedBearEmbeddings 多模态分支可平滑衔接。
-- ✅ **与 [S2-T3 VDB] 一致**：D2 中"BM25 + dense + sparse 三路融合 + RRF"与 [S2-T3] §6 应用层"双路 + 去重 + Rerank"形成升级路径。
-- ✅ **与 [S2-T5 Reranking/Prompt/LLM] 一致**：D5 的 Cross-Encoder 微调与 [S2-T5] §1 三种 rerank 方案兼容（视为新 Reranker 实现）。
-- ✅ **与 [S3-T1 架构改造] 一致**：§0.3 与 §6 双重对齐，所有 6 方向接口改造点全部落地到 [S3-T1] 4 大 Protocol（Retriever / Reranker / Embedder / Generator）。
-
-## 7. 终审结论与下一步
-
-| 决议项 | 内容 |
-|---|---|
-| **总分** | 95 / 100 |
-| **决议** | ✅ **PASS（终审通过）** |
-| **建议落入版本** | `MemoryBear RAG Docs v1.0`（落入 `docs/rag/evolution/future-extensions-roadmap.md` + `capability-map.mmd`） |
-| **状态变更建议** | 由 `in_review` → `done`，由 PM 执行 |
-| **后续衔接** | (1) Should-Fix 进入 [S3-T4] PM 复盘清单；(2) PoC-A / PoC-B 列入 Sprint-3 内立即可执行清单（与 [S3-T1] §3.1 短期路线图工作项 #1-#5 合并排期）；(3) [S2-T7] 评审若引入新事实，本文档以增量补丁形式更新（不重写）。 |
-
-— END —

web/src/assets/images/login/check.svg

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="16px" height="16px" viewBox="0 0 16 16" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <title>勾选</title>
+    <g id="空间外层页面优化" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
+        <g id="登录页面" transform="translate(-64, -611)" fill="#FFFFFF" fill-rule="nonzero">
+            <g id="编组-8" transform="translate(64, 608)">
+                <g id="勾选" transform="translate(0, 3)">
+                    <path d="M12,0 C14.209139,0 16,1.790861 16,4 L16,12 C16,14.209139 14.209139,16 12,16 L4,16 C1.790861,16 0,14.209139 0,12 L0,4 C0,1.790861 1.790861,4.4408921e-16 4,0 L12,0 Z M11.9182266,4.80024782 C11.7273831,4.80024782 11.5444062,4.87629473 11.4097812,5.0115625 L6.552,9.86932813 L4.4284375,7.74489063 C4.29381317,7.60962766 4.11083967,7.53358379 3.92,7.53358379 C3.72916033,7.53358379 3.54618683,7.60962766 3.4115625,7.74489063 C3.27602096,7.87955071 3.19979999,8.06271883 3.19979999,8.25378125 C3.19979999,8.44484367 3.27602096,8.62801179 3.4115625,8.76267188 L6.0453125,11.3946719 C6.17993745,11.5299396 6.3629143,11.6059866 6.55375781,11.6059866 C6.74460132,11.6059866 6.92757818,11.5299396 7.06220312,11.3946719 L12.4311094,6.02667188 C12.5659036,5.89187668 12.6412595,5.70881589 12.6404302,5.51818919 C12.639587,5.3275625 12.5626279,5.14516989 12.4266562,5.0115625 C12.2920469,4.87629473 12.1090701,4.80024782 11.9182266,4.80024782 Z" id="形状结合"></path>
+                </g>
+            </g>
+        </g>
+    </g>
+</svg>

web/src/styles/index.css

@@ -467,4 +467,29 @@ input:-webkit-autofill:active {
   animation-name: onAutoFillStart;
   animation-duration: 1ms;
 }
-@keyframes onAutoFillStart { from {} to {} }
+@keyframes onAutoFillStart { from {} to {} }
+/* Login input placeholder */
+.login-input input::placeholder {
+  color: #A8A9AA !important;
+}
+
+.login-input {
+  border-color: #A8A9AA;
+}
+
+/* Login input hover/focus border */
+.login-input:hover,
+.login-input:focus-within {
+  border-color: #FFFFFF !important;
+  box-shadow: none !important;
+}
+
+/* Override browser autofill styles */
+.login-input input:-webkit-autofill,
+.login-input input:-webkit-autofill:hover,
+.login-input input:-webkit-autofill:focus,
+.login-input input:-webkit-autofill:active {
+  -webkit-box-shadow: 0 0 0px 1000px #0A0A0A inset !important;
+  -webkit-text-fill-color: #FFFFFF !important;
+  transition: background-color 5000s ease-in-out 0s !important;
+}

web/src/views/Index/index.tsx

@@ -102,7 +102,7 @@ const Index = () => {
     <Flex gap={12} wrap="nowrap" className="rb:w-full! rb:h-full! rb:overflow-y-auto">
       <div className="rb:flex-1 rb:min-w-0">
         <Flex vertical>
-          <div className='rb:w-full rb:h-26 rb:p-4 rb:bg-cover rb:bg-[url("@/assets/images/index/index_bg@2x.png")] rb:rounded-xl rb:overflow-hidden'>
+          <div className='rb:w-full rb:h-26 rb:p-4 rb:bg-cover rb:bg-[url("@/assets/images/index/index_bg.png")] rb:rounded-xl rb:overflow-hidden'>
             <div className="rb:font-[MiSans-Bold] rb:font-bold rb:text-white rb:text-[18px] rb:leading-7">
               {t('index.spaceTitle')}
             </div>

web/src/views/Login/index.tsx

@@ -14,27 +14,33 @@ import React, { useState, useEffect } from 'react';
 import { useTranslation } from 'react-i18next';
 import { Button, Input, Form, App } from 'antd';
 import type { FormProps } from 'antd';
+import clsx from 'clsx';
 
 import { useUser, type LoginInfo } from '@/store/user';
 import { login } from '@/api/user'
-import loginBg from '@/assets/images/login/loginBg.png'
-import check from '@/assets/images/login/check.png'
+import loginBg from '@/assets/images/login/bg.mp4'
+import check from '@/assets/images/login/check.svg'
 import email from '@/assets/images/login/email.svg'
 import lock from '@/assets/images/login/lock.svg'
 import type { LoginForm } from './types';
+import { useI18n } from '@/store/locale'
 
 /**
  * Input field styling
  */
-const inputClassName = "rb:rounded-[8px]! rb:p-[12px]! rb:h-[44px]!"
+const inputClassName = "login-input rb:rounded-[8px]! rb:p-[12px]! rb:h-[44px]! rb:bg-transparent! rb:text-[#FFFFFF]! [&_input]:rb:text-[#FFFFFF]! [&_input]:rb:caret-[#FFFFFF]!"
 
 /**
  * Login page component
  */const LoginPage: React.FC = () => {
   const { t } = useTranslation();
   const { clearUserInfo, updateLoginInfo, getUserInfo } = useUser();
+  const { language } = useI18n()
   const [loading, setLoading] = useState(false);
   const [form] = Form.useForm<LoginForm>();
+  const emailVal = Form.useWatch('email', form);
+  const passwordVal = Form.useWatch('password', form);
+  const canLogin = !!(emailVal && passwordVal);
   const { message } = App.useApp();
 
   useEffect(() => {
@@ -43,6 +49,7 @@ const inputClassName = "rb:rounded-[8px]! rb:p-[12px]! rb:h-[44px]!"
 
   /** Handle login form submission */
   const handleLogin: FormProps<LoginForm>['onFinish'] = async (values) => {
+    if (!canLogin) return;
     if (!values.email) {
       message.warning(t('login.emailPlaceholder'));
       return;
@@ -64,42 +71,45 @@ const inputClassName = "rb:rounded-[8px]! rb:p-[12px]! rb:h-[44px]!"
 
 
   return (
-    <div className="rb:min-h-screen rb:flex rb:h-screen">
+    <div className="rb:min-h-screen rb:flex rb:h-screen rb:bg-[#0A0A0A] rb:text-[#FFFFFF]">
       <div className="rb:relative rb:w-1/2 rb:h-screen rb:overflow-hidden">
-        <img src={loginBg} alt="loginBg" className="rb:w-full rb:h-full rb:object-cover rb:absolute rb:top-1/2 rb:-translate-y-1/2 rb:left-0" />
-        <div className="rb:absolute rb:top-14 rb:left-16">
-          <div className="rb:text-[28px] rb:leading-8.25 rb:font-bold rb:font-[AlimamaShuHeiTi,AlimamaShuHeiTi] rb:mb-4">{t('login.title')}</div>
-          <div className="rb:text-[18px] rb:leading-6.25 rb:font-regular">{t('login.subTitle')}</div>
+        <video src={loginBg} loop autoPlay playsInline muted className="rb:w-full rb:h-full rb:object-cover"></video>
+        <div className="rb:absolute rb:top-10 rb:left-12">
+          <div className={clsx("rb:h-8.25 rb:bg-cover", {
+            "rb:w-89 rb:bg-[url('@/assets/images/login/title_en.png')]": language !== 'zh',
+            "rb:w-42 rb:bg-[url('@/assets/images/login/title_zh.png')]": language === 'zh'
+          })}></div>
+          <div className="rb:text-[18px] rb:text-[rgba(255,255,255,0.7)] rb:leading-6.25 rb:font-regular rb:mt-3">{t('login.subTitle')}</div>
         </div>
 
-        <div className="rb:absolute rb:bottom-20.25 rb:left-16 rb:grid rb:grid-cols-2 rb:gap-x-30 rb:gap-y-10.75">
-          {['intelligentMemory', 'instantRecall', 'knowledgeAssociation'].map(key => (
-            <div key={key} className="rb:flex">
+        <div className="rb:absolute rb:bottom-14 rb:left-12 rb:right-12 rb:grid rb:grid-cols-2 rb:gap-x-30 rb:gap-y-10.75">
+          {['intelligentMemory', 'instantRecall', 'knowledgeAssociation'].map((key, index) => (
+            <div key={key} className={`rb:flex${index === 0 ? ' rb:col-span-2' : ''}`}>
               <img src={check} className="rb:w-4 rb:h-4 rb:mr-2 rb:mt-0.75" />
               <div className="rb:text-[16px] rb:leading-5.5">
                 <div className="rb:font-medium">{t(`login.${key}`)}</div>
-                <div className="rb:text-[#5B6167] rb:text-[14px] rb:leading-5 rb:font-regular! rb:mt-2">{t(`login.${key}Desc`)}</div>
+                <div className="rb:text-[14px] rb:text-[rgba(255,255,255,0.7)] rb:leading-5 rb:font-regular! rb:mt-2">{t(`login.${key}Desc`)}</div>
               </div>
             </div>
           ))}
         </div>
       </div>
 
-      <div className="rb:bg-[#FFFFFF] rb:flex rb:items-center rb:justify-center rb:flex-[1_1_auto]">
-        <div className="rb:w-100 rb:mx-auto">
-          <div className="rb:text-center rb:text-[28px] rb:font-semibold rb:leading-8 rb:mb-12">{t('login.welcome')}</div>
+      <div className="rb:flex rb:items-center rb:justify-center rb:flex-[1_1_auto]">
+        <div className="rb:w-110 rb:mx-auto">
+          <div className="rb:text-center rb:text-[24px] rb:font-[MiSans-Bold] rb:font-bold rb:leading-8 rb:mb-12">{t('login.welcome')}</div>
           <Form
             form={form}
             onFinish={handleLogin}
           >
-            <Form.Item name="email" className="rb:mb-5!">
+            <Form.Item name="email" className="rb:mb-6!">
               <Input
                 prefix={<img src={email} className="rb:w-5 rb:h-5 rb:mr-2" />}
                 placeholder={t('login.emailPlaceholder')}
                 className={inputClassName}
               />
             </Form.Item>
-            <Form.Item name="password">
+            <Form.Item name="password" className="rb:mb-0!">
               <Input.Password
                 prefix={<img src={lock} className="rb:w-5 rb:h-5 rb:mr-2" />}
                 placeholder={t('login.passwordPlaceholder')}
@@ -111,7 +121,11 @@ const inputClassName = "rb:rounded-[8px]! rb:p-[12px]! rb:h-[44px]!"
               block
               loading={loading}
               htmlType="submit"
-              className="rb:h-10! rb:rounded-lg! rb:mt-4"
+              disabled={!canLogin}
+              className={clsx("rb:h-11.5! rb:rounded-lg! rb:mt-12", {
+                'rb:hover:bg-[#2d6ef1]! rb:bg-[#155EEF]! rb:border-[#155EEF]!': canLogin,
+                'rb:bg-[#171719]! rb:border-[#171719]!': !canLogin
+              })}
             >
               {t('login.loginIn')}
             </Button>

web/src/views/ToolManagement/Market.tsx

@@ -361,7 +361,7 @@ const Market: React.FC<{ getStatusTag?: (status: string) => ReactNode }> = () =>
               )}
             </Flex>
             <div>
-              <div className="rb:font-[MiSans Bold] rb:font-bold rb:text-[16px] rb:leading-5.5">{source.name}</div>
+              <div className="rb:font-[MiSans-Bold] rb:font-bold rb:text-[16px] rb:leading-5.5">{source.name}</div>
               <div className="rb:text-[#5B6167] rb:text-[12px] rb:leading-4.5">{t('tool.availableMcp')} ({mcpTotal})</div>
             </div>
           </Flex>

web/src/views/Workflow/components/Properties/CaseList/index.tsx

@@ -355,14 +355,13 @@ const CaseList: FC<CaseListProps> = ({
   // Update node ports based on case count changes (add/remove cases)
   const updateNodePorts = (caseCount: number, removedCaseIndex?: number) => {
     if (!selectedNode || !graphRef?.current) return;
-    
-    // Get current port count to determine if it's an add or remove operation
-    const currentPorts = selectedNode.getPorts().filter((port: any) => port.group === 'right');
-    const currentCaseCount = currentPorts.length - 1; // Exclude ELSE port
+    const graph = graphRef.current;
+
+    const currentRightPorts = selectedNode.getPorts().filter((port: any) => port.group === 'right');
+    const currentCaseCount = currentRightPorts.length - 1;
     const isAddingCase = removedCaseIndex === undefined && caseCount > currentCaseCount;
-    
-    // Save existing edge connections (including left-side port connections)
-    const existingEdges = graphRef.current.getEdges().filter((edge: any) => 
+
+    const existingEdges = graph.getEdges().filter((edge: any) =>
       edge.getSourceCellId() === selectedNode.id || edge.getTargetCellId() === selectedNode.id
     );
     const edgeConnections = existingEdges.map((edge: any) => ({
@@ -371,113 +370,70 @@ const CaseList: FC<CaseListProps> = ({
       targetCellId: edge.getTargetCellId(),
       targetPortId: edge.getTargetPortId(),
       sourceCellId: edge.getSourceCellId(),
-      isIncoming: edge.getTargetCellId() === selectedNode.id
+      isIncoming: edge.getTargetCellId() === selectedNode.id,
     }));
-    
-    // Remove all existing right-side ports
-    const existingPorts = selectedNode.getPorts();
-    existingPorts.forEach((port: any) => {
-      if (port.group === 'right') {
-        selectedNode.removePort(port.id);
+
+    const cases = form.getFieldValue(name) || [];
+    const leftPorts = selectedNode.getPorts().filter((p: any) => p.group !== 'right');
+    const newRightPorts = Array.from({ length: caseCount + 1 }, (_, i) => ({
+      id: `CASE${i + 1}`,
+      group: 'right',
+      args: { x: nodeWidth, y: getConditionNodeCasePortY(cases, i) },
+    }));
+
+    graph.startBatch('update-ports');
+
+    existingEdges.forEach((edge: any) => graph.removeCell(edge));
+    // Replace all ports in one prop call — produces a single cell:change:ports command
+    selectedNode.prop('ports/items', [...leftPorts, ...newRightPorts], { rewrite: true });
+    selectedNode.prop('size', { width: nodeWidth, height: calcConditionNodeTotalHeight(cases) });
+
+    edgeConnections.forEach(({sourcePortId, targetCellId, targetPortId, sourceCellId, isIncoming }: any) => {
+      if (isIncoming) {
+        const sourceCell = graph.getCellById(sourceCellId);
+        if (sourceCell) {
+          graph.addEdge({
+            source: { cell: sourceCellId, port: sourcePortId },
+            target: { cell: selectedNode.id, port: targetPortId },
+            ...edgeAttrs
+          });
+          sourceCell.toFront();
+          bringLoopChildrenToFront(sourceCell);
+          selectedNode.toFront();
+          bringLoopChildrenToFront(selectedNode);
+        }
+        return;
+      }
+      const originalCaseNumber = parseInt(sourcePortId.match(/CASE(\d+)/)?.[1] || '0');
+      if (removedCaseIndex !== undefined && originalCaseNumber === removedCaseIndex + 1) return;
+      let newPortId = sourcePortId;
+
+      if (removedCaseIndex !== undefined) {
+        if (originalCaseNumber > removedCaseIndex + 1) {
+          newPortId = `CASE${originalCaseNumber - 1}`;
+        } else if (originalCaseNumber === currentCaseCount + 1) {
+          newPortId = `CASE${caseCount + 1}`;
+        }
+      } else if (isAddingCase && originalCaseNumber === currentCaseCount + 1) {
+        newPortId = `CASE${caseCount + 1}`;
+      }
+      if (newRightPorts.find((p) => p.id === newPortId)) {
+        const targetCell = graph.getCellById(targetCellId);
+        if (targetCell) {
+          graph.addEdge({
+            source: { cell: selectedNode.id, port: newPortId },
+            target: { cell: targetCellId, port: targetPortId },
+            ...edgeAttrs
+          });
+          selectedNode.toFront();
+          bringLoopChildrenToFront(selectedNode);
+          targetCell.toFront();
+          bringLoopChildrenToFront(targetCell);
+        }
       }
     });
 
-    const cases = form.getFieldValue(name) || [];
-    selectedNode.prop('size', { width: nodeWidth, height: calcConditionNodeTotalHeight(cases) });
-
-    // Add ELIF ports
-    for (let i = 0; i < caseCount; i++) {
-      selectedNode.addPort({
-        id: `CASE${i + 1}`,
-        group: 'right',
-        args: {
-          x: nodeWidth,
-          y: getConditionNodeCasePortY(cases, i),
-        },
-      });
-    }
-    
-    // Add ELSE port
-    selectedNode.addPort({
-      id: `CASE${caseCount + 1}`,
-      group: 'right',
-      args: {
-        x: nodeWidth,
-        y: getConditionNodeCasePortY(cases, caseCount),
-      },
-    });
-    
-    // Restore edge connections
-    setTimeout(() => {
-      edgeConnections.forEach(({ edge, sourcePortId, targetCellId, targetPortId, sourceCellId, isIncoming }: any) => {
-        // If it's an incoming connection (left-side port), restore directly
-        if (isIncoming) {
-          const sourceCell = graphRef.current?.getCellById(sourceCellId);
-          if (sourceCell) {
-            graphRef.current?.addEdge({
-              source: { cell: sourceCellId, port: sourcePortId },
-              target: { cell: selectedNode.id, port: targetPortId },
-              ...edgeAttrs,
-            });
-          }
-          sourceCell.toFront()
-          selectedNode.toFront()
-          bringLoopChildrenToFront(sourceCell)
-          bringLoopChildrenToFront(selectedNode)
-          graphRef.current?.removeCell(edge);
-          return;
-        }
-        
-        // Handle right-side port connections
-        const originalCaseNumber = parseInt(sourcePortId.match(/CASE(\d+)/)?.[1] || '0');
-        
-        // If it's a remove operation and the port is being removed, delete the connection
-        if (removedCaseIndex !== undefined && originalCaseNumber === removedCaseIndex + 1) {
-          graphRef.current?.removeCell(edge);
-          return;
-        }
-        
-        let newPortId = sourcePortId;
-        
-        // If it's a remove operation, remap port IDs
-        if (removedCaseIndex !== undefined) {
-          if (originalCaseNumber > removedCaseIndex + 1) {
-            // Ports after the removed port, shift numbering forward
-            newPortId = `CASE${originalCaseNumber - 1}`;
-          }
-          // ELSE port always maps to the new ELSE port position
-          else if (originalCaseNumber === currentCaseCount + 1) {
-            newPortId = `CASE${caseCount + 1}`;
-          }
-        } else if (isAddingCase) {
-          // If it's an add operation, ELSE port needs to be remapped
-          if (originalCaseNumber === currentCaseCount + 1) {
-            newPortId = `CASE${caseCount + 1}`; // New ELSE port
-          }
-          // Newly added ports don't restore any connections
-        }
-        
-        const newPorts = selectedNode.getPorts();
-        const matchingPort = newPorts.find((port: any) => port.id === newPortId);
-        
-        if (matchingPort) {
-          const targetCell = graphRef.current?.getCellById(targetCellId);
-          if (targetCell) {
-            graphRef.current?.addEdge({
-              source: { cell: selectedNode.id, port: newPortId },
-              target: { cell: targetCellId, port: targetPortId },
-              ...edgeAttrs
-            });
-            selectedNode.toFront()
-            bringLoopChildrenToFront(selectedNode)
-            targetCell.toFront()
-            bringLoopChildrenToFront(targetCell)
-          }
-        }
-        
-        graphRef.current?.removeCell(edge);
-      });
-    }, 50);
+    graph.stopBatch('update-ports');
   };
 
   const handleChangeLogicalOperator = (index: number) => {

web/src/views/Workflow/components/Properties/CategoryList/index.tsx

@@ -42,109 +42,73 @@ const CategoryList: FC<CategoryListProps> = ({ parentName, selectedNode, graphRe
   // Update node ports based on category count changes (add/remove categories)
   const updateNodePorts = (caseCount: number, removedCaseIndex?: number) => {
     if (!selectedNode || !graphRef?.current) return;
+    const graph = graphRef.current;
 
-    // Save existing edge connections (including left-side port connections)
-    const existingEdges = graphRef.current.getEdges().filter((edge: any) =>
+    const existingEdges = graph.getEdges().filter((edge: any) =>
       edge.getSourceCellId() === selectedNode.id || edge.getTargetCellId() === selectedNode.id
     );
     const edgeConnections = existingEdges.map((edge: any) => ({
-      edge,
       sourcePortId: edge.getSourcePortId(),
       targetCellId: edge.getTargetCellId(),
       targetPortId: edge.getTargetPortId(),
       sourceCellId: edge.getSourceCellId(),
-      isIncoming: edge.getTargetCellId() === selectedNode.id
+      isIncoming: edge.getTargetCellId() === selectedNode.id,
     }));
 
-    // Remove all existing right-side ports
-    const existingPorts = selectedNode.getPorts();
-    existingPorts.forEach((port: any) => {
-      if (port.group === 'right') {
-        selectedNode.removePort(port.id);
-      }
-    });
+    graph.startBatch('update-ports');
+
+    existingEdges.forEach((edge: any) => graph.removeCell(edge));
+    // Replace all ports in one prop call — produces a single cell:change:ports command
+    const leftPorts = selectedNode.getPorts().filter((p: any) => p.group !== 'right');
+    const newRightPorts = Array.from({ length: caseCount }, (_, i) => ({
+      id: `CASE${i + 1}`,
+      group: 'right',
+      args: { x: nodeWidth, y: portItemArgsY * i + conditionNodePortItemArgsY },
+    }));
+    selectedNode.prop('ports/items', [...leftPorts, ...newRightPorts], { rewrite: true });
 
-    // Calculate new node height: base height 88px + 30px for each additional port
     const newHeight = conditionNodeHeight + (caseCount - 2) * conditionNodeItemHeight;
+    selectedNode.prop('size', { width: nodeWidth, height: newHeight < conditionNodeHeight ? conditionNodeHeight : newHeight });
 
-    selectedNode.prop('size', { width: nodeWidth, height: newHeight < conditionNodeHeight ? conditionNodeHeight : newHeight })
-
-    // Update right port x position
-    const currentPorts = selectedNode.getPorts();
-    currentPorts.forEach(port => {
-      if (port.group === 'right' && port.args) {
-        selectedNode.portProp(port.id!, 'args/x', nodeWidth);
+    edgeConnections.forEach(({ sourcePortId, targetCellId, targetPortId, sourceCellId, isIncoming }: any) => {
+      if (isIncoming) {
+        const sourceCell = graph.getCellById(sourceCellId);
+        if (sourceCell) {
+          graph.addEdge({
+            source: { cell: sourceCellId, port: sourcePortId },
+            target: { cell: selectedNode.id, port: targetPortId },
+            ...edgeAttrs
+          });
+          sourceCell.toFront();
+          bringLoopChildrenToFront(sourceCell);
+          selectedNode.toFront();
+          bringLoopChildrenToFront(selectedNode);
+        }
+        return;
+      }
+      const originalCaseNumber = parseInt(sourcePortId.match(/CASE(\d+)/)?.[1] || '0');
+      if (removedCaseIndex !== undefined && originalCaseNumber === removedCaseIndex + 1) return;
+      let newPortId = sourcePortId;
+      if (removedCaseIndex !== undefined && originalCaseNumber > removedCaseIndex + 1) {
+        newPortId = `CASE${originalCaseNumber - 1}`;
+      }
+      if (newRightPorts.find((p) => p.id === newPortId)) {
+        const targetCell = graph.getCellById(targetCellId);
+        if (targetCell) {
+          graph.addEdge({
+            source: { cell: selectedNode.id, port: newPortId },
+            target: { cell: targetCellId, port: targetPortId },
+            ...edgeAttrs
+          });
+          selectedNode.toFront();
+          bringLoopChildrenToFront(selectedNode);
+          targetCell.toFront();
+          bringLoopChildrenToFront(targetCell);
+        }
       }
     });
 
-    // Add category ports
-    for (let i = 0; i < caseCount; i++) {
-      selectedNode.addPort({
-        id: `CASE${i + 1}`,
-        group: 'right',
-        args: {
-          x: nodeWidth,
-          y: portItemArgsY * i + conditionNodePortItemArgsY,
-        },
-      });
-    }
-    // Restore edge connections
-    setTimeout(() => {
-      edgeConnections.forEach(({ edge, sourcePortId, targetCellId, targetPortId, sourceCellId, isIncoming }: any) => {
-        graphRef.current?.removeCell(edge);
-        
-        // If it's an incoming connection (left-side port), restore directly
-        if (isIncoming) {
-          const sourceCell = graphRef.current?.getCellById(sourceCellId);
-          if (sourceCell) {
-            graphRef.current?.addEdge({
-              source: { cell: sourceCellId, port: sourcePortId },
-              target: { cell: selectedNode.id, port: targetPortId },
-              ...edgeAttrs
-            });
-            sourceCell.toFront()
-            bringLoopChildrenToFront(sourceCell)
-            selectedNode.toFront()
-            bringLoopChildrenToFront(selectedNode)
-          }
-          return;
-        }
-
-        // Handle right-side port connections
-        const originalCaseNumber = parseInt(sourcePortId.match(/CASE(\d+)/)?.[1] || '0');
-
-        // If it's a removed port, don't recreate the connection
-        if (removedCaseIndex !== undefined && originalCaseNumber === removedCaseIndex + 1) {
-          return;
-        }
-
-        let newPortId = sourcePortId;
-
-        // If a port was removed, remap subsequent port IDs
-        if (removedCaseIndex !== undefined && originalCaseNumber > removedCaseIndex + 1) {
-          newPortId = `CASE${originalCaseNumber - 1}`;
-        }
-
-        // Check if the new port exists
-        const newPorts = selectedNode.getPorts();
-        const matchingPort = newPorts.find((port: any) => port.id === newPortId);
-
-        if (matchingPort) {
-          const targetCell = graphRef.current?.getCellById(targetCellId);
-          if (targetCell) {
-            graphRef.current?.addEdge({
-              source: { cell: selectedNode.id, port: newPortId },
-              target: { cell: targetCellId, port: targetPortId },
-              ...edgeAttrs
-            });
-            selectedNode.toFront()
-            bringLoopChildrenToFront(selectedNode)
-            targetCell.toFront()
-            bringLoopChildrenToFront(targetCell)
-          }
-        }
-      });
-    }, 50);
+    graph.stopBatch('update-ports');
   };
 
   const handleAddCategory = (addFunc: Function) => {

web/src/views/Workflow/hooks/useWorkflowGraph.ts

@@ -124,9 +124,7 @@ export const useWorkflowGraph = ({
   const [canRedo, setCanRedo] = useState(false)
   const [historyRecords, setHistoryRecords] = useState<HistoryRecord[]>([])
   const lastHistoryRef = useRef<{ cellIds: string[]; timestamp: number; type: string } | null>(null)
-  const undoRef = useRef<() => void>(() => {})
-  const redoRef = useRef<() => void>(() => {})
-  const syncChildRelationshipsRef = useRef<() => void>(() => {})
+  const syncChildRelationshipsRef = useRef<() => void>(() => { })
   const isSyncingRef = useRef(false)
   useEffect(() => {
     if (!graphRef.current) return
@@ -532,24 +530,82 @@ export const useWorkflowGraph = ({
     const graph = graphRef.current
     graph.disableHistory()
     graph.getNodes().forEach(node => {
-      const cycleId = node.getData()?.cycle
-      if (!cycleId) return
-      const parentNode = graph.getCellById(cycleId) as Node | null
-      if (!parentNode) return
-      if (!parentNode.getChildren()?.some(c => c.id === node.id)) {
-        parentNode.addChild(node, { silent: true })
-      }
-    })
-    graph.getNodes().forEach(node => {
+      const nodeData = node.getData()
       const children = node.getChildren()
-      if (!children?.length) return
-      children.forEach(child => {
-        if (!child.isNode()) return
-        const childCycleId = (child as Node).getData?.()?.cycle
-        if (childCycleId !== node.id && childCycleId !== node.getData?.()?.id) {
-          node.removeChild(child, { silent: true })
+
+      const cycleId = nodeData?.cycle
+
+      if (cycleId) {
+        const parentNode = graph.getCellById(cycleId) as Node | null
+        if (!parentNode) return
+        if (!parentNode.getChildren()?.some(c => c.id === node.id)) {
+          parentNode.addChild(node, { silent: true })
         }
-      })
+      }
+
+      if (nodeData.type === 'if-else') {
+        const rightPorts = node.getPorts().filter(p => p.group === 'right')
+        const caseCount = rightPorts.length - 1 // last port is ELSE
+        const currentCases: any[] = nodeData.config?.cases?.defaultValue ?? []
+        const newCases = caseCount !== currentCases.length
+          ? Array.from({ length: caseCount }, (_, i) => currentCases[i] ?? { logical_operator: 'and', expressions: [] })
+          : currentCases
+        if (caseCount !== currentCases.length) {
+          node.setData({
+            ...nodeData,
+            config: { ...nodeData.config, cases: { ...nodeData.config.cases, defaultValue: newCases } }
+          }, { deep: false, silent: true })
+        }
+        // Sync node height and port Y positions
+        node.prop('size', { width: nodeWidth, height: calcConditionNodeTotalHeight(newCases) })
+        newCases.forEach((_c: any, i: number) => {
+          node.portProp(`CASE${i + 1}`, 'args/y', getConditionNodeCasePortY(newCases, i))
+        })
+        node.portProp(`CASE${newCases.length + 1}`, 'args/y', getConditionNodeCasePortY(newCases, newCases.length))
+        node.toFront()
+        graph.getEdges().filter(e => e.getSourceCellId() === node.id).forEach(e => {
+          const tgt = graph.getCellById(e.getTargetCellId())
+          tgt?.toFront()
+        })
+      } else if (nodeData.type === 'question-classifier') {
+        const rightPorts = node.getPorts().filter(p => p.group === 'right')
+        const currentCategories: any[] = nodeData.config?.categories?.defaultValue ?? []
+        const categoryCount = rightPorts.length
+        const newCategories = categoryCount !== currentCategories.length
+          ? rightPorts.map((port, i) => {
+            if (currentCategories[i]) return currentCategories[i]
+            const edge = graph.getEdges().find(e => e.getSourceCellId() === node.id && e.getSourcePortId() === port.id)
+            return edge ? { name: '' } : {}
+          })
+          : currentCategories
+        if (categoryCount !== currentCategories.length) {
+          node.setData({
+            ...nodeData,
+            config: { ...nodeData.config, categories: { ...nodeData.config.categories, defaultValue: [...newCategories] } }
+          }, { deep: false, silent: true })
+        }
+        // Sync node height and port Y positions
+        const newHeight = conditionNodeHeight + (categoryCount - 2) * conditionNodeItemHeight
+        node.prop('size', { width: nodeWidth, height: Math.max(newHeight, conditionNodeHeight) })
+        rightPorts.forEach((_p, i) => {
+          node.portProp(`CASE${i + 1}`, 'args/y', portItemArgsY * i + conditionNodePortItemArgsY)
+        })
+        node.toFront()
+        graph.getEdges().filter(e => e.getSourceCellId() === node.id).forEach(e => {
+          const tgt = graph.getCellById(e.getTargetCellId())
+          tgt?.toFront()
+        })
+      }
+
+      if (children?.length) {
+        children.forEach(child => {
+          if (!child.isNode()) return
+          const childCycleId = (child as Node).getData?.()?.cycle
+          if (childCycleId !== node.id && childCycleId !== node.getData?.()?.id) {
+            node.removeChild(child, { silent: true })
+          }
+        })
+      }
     })
     resizeGroupNodes(graph)
     graph.getEdges().forEach(edge => {