feat(server): 重构知识库服务和路由配置，优化LLM维基知识管理接口，增强知识检索能力

server/src/app/api/v1/endpoints/knowledge.py

@@ -16,18 +16,19 @@ from app.schemas.knowledge import (
     KnowledgeActionResponse,
     KnowledgeDocumentDetailRead,
     KnowledgeLibraryRead,
-    LlmWikiDocumentDetailRead,
-    LlmWikiIndexRead,
-    LlmWikiSummaryUpdateWrite,
     KnowledgeOnlyOfficeCallbackRead,
     KnowledgeOnlyOfficeCallbackWrite,
     KnowledgeOnlyOfficeConfigRead,
-    LlmWikiSyncRead,
+    LlmWikiDocumentDetailRead,
+    LlmWikiIndexRead,
+    LlmWikiSyncTaskRead,
     LlmWikiSyncWrite,
+    LlmWikiSummaryUpdateWrite,
 )
 from app.services.agent_runs import AgentRunService
-from app.services.knowledge import KnowledgeService
+from app.services.knowledge import KNOWLEDGE_INGEST_STATUS_SYNCING, KnowledgeService
 from app.services.llm_wiki import LlmWikiService
+from app.services.llm_wiki_tasks import llm_wiki_task_manager
 
 router = APIRouter(prefix="/knowledge")
 
@@ -46,8 +47,9 @@ router = APIRouter(prefix="/knowledge")
 )
 def get_knowledge_library(
     _: Annotated[CurrentUserContext, Depends(get_current_user)],
+    db: Annotated[Session, Depends(get_db)],
 ) -> KnowledgeLibraryRead:
-    return KnowledgeService().list_library()
+    return KnowledgeService(db=db).list_library()
 
 
 @router.get(
@@ -140,9 +142,9 @@ def update_llm_wiki_document_summary(
 
 @router.post(
     "/llm-wiki/sync",
-    response_model=LlmWikiSyncRead,
-    summary="触发 Hermes 形成 LLM Wiki 与规则草稿",
-    description="按知识库文档变化情况增量触发系统 Hermes，形成知识候选和规则草稿。",
+    response_model=LlmWikiSyncTaskRead,
+    summary="异步触发 Hermes 形成 LLM Wiki 与规则草稿",
+    description="按知识库文档变化情况将系统 Hermes 归纳任务放入后台执行，并返回可追踪的 AgentRun 编号。",
     responses={
         status.HTTP_401_UNAUTHORIZED: {
             "model": ErrorResponse,
@@ -158,8 +160,15 @@ def sync_llm_wiki(
     payload: LlmWikiSyncWrite,
     current_user: Annotated[CurrentUserContext, Depends(require_admin_user)],
     db: Annotated[Session, Depends(get_db)],
-) -> LlmWikiSyncRead:
+) -> LlmWikiSyncTaskRead:
     run_service = AgentRunService(db)
+    knowledge_service = KnowledgeService(db=db)
+    requested_ids = {str(item).strip() for item in payload.document_ids if str(item).strip()}
+    target_document_ids = [
+        str(item.get("id") or "").strip()
+        for item in knowledge_service.list_folder_documents(folder=payload.folder)
+        if str(item.get("id") or "").strip() and (not requested_ids or str(item.get("id") or "").strip() in requested_ids)
+    ]
     task_asset = db.scalar(
         select(AgentAsset).where(AgentAsset.code == "task.hermes.llm_wiki_rule_formation")
     )
@@ -170,47 +179,52 @@ def sync_llm_wiki(
         task_id=task_asset.id if task_asset is not None else None,
         permission_level=AgentPermissionLevel.READ.value,
         status=AgentRunStatus.RUNNING.value,
-        result_summary="Hermes 正在形成 LLM Wiki 与规则草稿。",
+        result_summary="Hermes 归纳任务已入队，等待后台执行。",
+        route_json={
+            "job_type": "llm_wiki_sync",
+            "phase": "queued",
+            "folder": payload.folder,
+            "force": payload.force,
+            "requested_document_ids": target_document_ids,
+            "progress": {
+                "total_documents": len(target_document_ids),
+                "completed_documents": 0,
+                "failed_documents": 0,
+                "skipped_documents": 0,
+                "percent": 0,
+            },
+        },
     )
 
     try:
-        result = LlmWikiService(db).sync_folder(
+        if target_document_ids:
+            knowledge_service.set_document_ingest_statuses(
+                target_document_ids,
+                status_code=KNOWLEDGE_INGEST_STATUS_SYNCING,
+                agent_run_id=run.run_id,
+            )
+        llm_wiki_task_manager.submit_sync(
+            agent_run_id=run.run_id,
             folder=payload.folder,
             current_user=current_user,
-            document_ids=payload.document_ids,
+            document_ids=target_document_ids,
             force=payload.force,
         )
-        run_service.record_tool_call(
-            run_id=run.run_id,
-            tool_type="llm",
-            tool_name="system_hermes_llm_wiki_sync",
-            request_json=payload.model_dump(),
-            response_json=result.model_dump(),
-            status="succeeded",
-            duration_ms=0,
+        return LlmWikiSyncTaskRead(
+            ok=True,
+            agent_run_id=run.run_id,
+            folder=payload.folder,
+            document_ids=target_document_ids,
+            queued_at=run.started_at,
+            status=run.status,
+            summary="Hermes 已进入后台归纳，可在日志管理查看进度。",
         )
-        run_service.update_run(
-            run.run_id,
-            status=AgentRunStatus.SUCCEEDED.value,
-            result_summary=result.summary,
-            finished_at=datetime.now(UTC),
-        )
-        return result
     except Exception as exc:
-        run_service.record_tool_call(
-            run_id=run.run_id,
-            tool_type="llm",
-            tool_name="system_hermes_llm_wiki_sync",
-            request_json=payload.model_dump(),
-            response_json={"error": str(exc)},
-            status="failed",
-            duration_ms=0,
-            error_message=str(exc),
-        )
         run_service.update_run(
             run.run_id,
             status=AgentRunStatus.FAILED.value,
             error_message=str(exc),
+            result_summary=str(exc),
             finished_at=datetime.now(UTC),
         )
         if isinstance(exc, ValueError):
@@ -239,9 +253,10 @@ def sync_llm_wiki(
 def get_knowledge_document(
     document_id: str,
     _: Annotated[CurrentUserContext, Depends(get_current_user)],
+    db: Annotated[Session, Depends(get_db)],
 ) -> KnowledgeDocumentDetailRead:
     try:
-        return KnowledgeService().get_document_detail(document_id)
+        return KnowledgeService(db=db).get_document_detail(document_id)
     except FileNotFoundError as exc:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,