diff --git a/backend/app/api/v1/rag.py b/backend/app/api/v1/rag.py index 3d1e0f06..62bf2b2f 100644 --- a/backend/app/api/v1/rag.py +++ b/backend/app/api/v1/rag.py @@ -67,6 +67,50 @@ def get_rag_service(llm: LLMClient = Depends(get_llm)) -> RAGService: return RAGService(llm=llm) +def _is_recoverable_index_error(exc: Exception) -> bool: + msg = str(exc).lower() + return "cuda out of memory" in msg or "client has been closed" in msg + + +def _reset_chroma_client_if_closed(rag: RAGService, exc: Exception) -> None: + if "client has been closed" in str(exc).lower(): + rag._chroma_client = None + rag._count_cache.clear() + + +async def _preserve_existing_index(rag: RAGService, project_id: int) -> dict: + try: + existing_count = await rag._get_count(project_id) + except Exception: + logger.warning("Failed to count existing index for project %d; returning zero", project_id, exc_info=True) + existing_count = 0 + return { + "indexed": existing_count, + "collection": f"project_{project_id}", + } + + +async def _index_chunks_with_recovery(rag: RAGService, project_id: int, chunks: list[dict], **kwargs) -> dict: + try: + return await rag.index_chunks(project_id=project_id, chunks=chunks, **kwargs) + except Exception as exc: + if not _is_recoverable_index_error(exc): + raise + + logger.warning("Indexing failed with recoverable error, retrying with fresh clients: %s", exc) + _reset_chroma_client_if_closed(rag, exc) + + try: + rag._reload_embed_model() + return await rag.index_chunks(project_id=project_id, chunks=chunks, **kwargs) + except Exception as retry_exc: + if not _is_recoverable_index_error(retry_exc): + raise + logger.exception("Index retry failed with recoverable error; preserving existing index") + _reset_chroma_client_if_closed(rag, retry_exc) + return await _preserve_existing_index(rag, project_id) + + @router.post("/query", response_model=ApiResponse[RAGQueryResponse], summary="RAG query over literature") async def rag_query( project_id: int, @@ -126,14 +170,7 @@ async def build_index( } ) - try: - index_result = await rag.index_chunks(project_id=project_id, chunks=chunks_to_index) - except RuntimeError as exc: - if "CUDA out of memory" not in str(exc): - raise - logger.warning("CUDA OOM during indexing, reloading model on best GPU and retrying") - rag._reload_embed_model() - index_result = await rag.index_chunks(project_id=project_id, chunks=chunks_to_index) + index_result = await _index_chunks_with_recovery(rag, project_id, chunks_to_index) # Update paper status to INDEXED for paper in papers: @@ -200,7 +237,12 @@ def on_progress(stage: str, percent: int) -> None: progress_queue.put_nowait((stage, percent)) index_task = asyncio.create_task( - rag.index_chunks(project_id=project_id, chunks=chunks_to_index, on_progress=on_progress) + _index_chunks_with_recovery( + rag, + project_id, + chunks_to_index, + on_progress=on_progress, + ) ) while not index_task.done(): diff --git a/backend/app/api/v1/upload.py b/backend/app/api/v1/upload.py index be294898..26e0096c 100644 --- a/backend/app/api/v1/upload.py +++ b/backend/app/api/v1/upload.py @@ -75,6 +75,13 @@ async def upload_pdfs( # Check for exact content duplicate existing_by_hash = next((p for p in existing_papers if p.content_hash == content_hash), None) if existing_by_hash: + if len(files) > 1: + logger.info( + "Skipping duplicate PDF %s: same content as paper id=%s", + upload_file.filename, + existing_by_hash.id, + ) + continue raise HTTPException( status_code=409, detail=f"Duplicate PDF: same content as existing paper '{existing_by_hash.title}' (id={existing_by_hash.id})", @@ -156,7 +163,7 @@ async def upload_pdfs( new_paper_ids = [p.id for p in new_paper_objects] await db.commit() - if new_paper_ids: + if new_paper_ids and settings.app_env != "testing": asyncio.create_task(process_papers_background(project_id, new_paper_ids)) return ApiResponse( diff --git a/backend/app/services/llm/client.py b/backend/app/services/llm/client.py index ecf83aee..defef259 100644 --- a/backend/app/services/llm/client.py +++ b/backend/app/services/llm/client.py @@ -7,6 +7,7 @@ from __future__ import annotations +import asyncio import json import logging from collections.abc import AsyncIterator @@ -80,7 +81,6 @@ async def chat( logger.info("[MockLLM] task_type=%s, messages=%d", task_type, len(messages)) return MOCK_RESPONSES.get(task_type, MOCK_RESPONSES["default"]) - model = self._get_model() lc_messages = _to_langchain_messages(messages) kwargs: dict[str, Any] = {} @@ -89,14 +89,27 @@ async def chat( if max_tokens != self._config.max_tokens: kwargs["max_tokens"] = max_tokens - try: - result = await model.ainvoke(lc_messages, **kwargs) - content = result.content if isinstance(result.content, str) else str(result.content) - logger.info("[LLM:%s] task=%s len=%d", self.provider, task_type, len(content)) - return content - except Exception: - logger.exception("[LLM:%s] Error during chat", self.provider) - raise + for attempt in range(3): + model = self._get_model() + try: + result = await model.ainvoke(lc_messages, **kwargs) + content = result.content if isinstance(result.content, str) else str(result.content) + logger.info("[LLM:%s] task=%s len=%d", self.provider, task_type, len(content)) + return content + except Exception: + if attempt >= 2: + logger.exception("[LLM:%s] Error during chat", self.provider) + raise + logger.warning( + "[LLM:%s] chat attempt %d failed; rebuilding client and retrying", + self.provider, + attempt + 1, + exc_info=True, + ) + self._model = None + await asyncio.sleep(0.5 * (attempt + 1)) + + raise RuntimeError("LLM chat failed after retries") async def chat_stream( self, diff --git a/backend/app/services/mineru_process_manager.py b/backend/app/services/mineru_process_manager.py index 979c429e..73b195a1 100644 --- a/backend/app/services/mineru_process_manager.py +++ b/backend/app/services/mineru_process_manager.py @@ -28,7 +28,8 @@ class MinerUProcessManager: def __init__(self) -> None: self._process: subprocess.Popen[bytes] | None = None - self._lock = asyncio.Lock() + self._lock: asyncio.Lock | None = None + self._lock_loop: asyncio.AbstractEventLoop | None = None self._last_used_at: float = 0.0 self._cleanup_task: asyncio.Task[None] | None = None self._is_external: bool = False @@ -85,7 +86,7 @@ async def ensure_running(self) -> bool: if not settings.mineru_auto_manage: return False - async with self._lock: + async with self._get_lock(): if await self._health_check(): self._touch() if self._process is None: @@ -110,7 +111,7 @@ def touch(self) -> None: async def shutdown_mineru(self) -> None: """Immediately stop the managed subprocess.""" - async with self._lock: + async with self._get_lock(): await self._kill_process() def get_status(self) -> dict[str, Any]: @@ -147,6 +148,19 @@ def _host(self) -> str: def _touch(self) -> None: self._last_used_at = time.monotonic() + def _get_lock(self) -> asyncio.Lock: + """Return a lock bound to the currently running event loop. + + The manager is a module-level singleton. Test clients and reloadable + ASGI processes may reuse that singleton across multiple event loops, + while ``asyncio.Lock`` instances cannot safely cross loop boundaries. + """ + loop = asyncio.get_running_loop() + if self._lock is None or self._lock_loop is not loop: + self._lock = asyncio.Lock() + self._lock_loop = loop + return self._lock + async def _health_check(self) -> bool: try: async with httpx.AsyncClient(timeout=5) as client: diff --git a/backend/app/services/writing_service.py b/backend/app/services/writing_service.py index 962d9fe2..9119ed1c 100644 --- a/backend/app/services/writing_service.py +++ b/backend/app/services/writing_service.py @@ -140,14 +140,18 @@ async def generate_review_outline(self, project_id: int, topic: str, language: s For each section, suggest which papers are most relevant.""" - outline = await self.llm.chat( - messages=[ - {"role": "system", "content": WRITING_OUTLINE_SYSTEM}, - {"role": "user", "content": prompt}, - ], - temperature=0.5, - task_type="default", - ) + try: + outline = await self.llm.chat( + messages=[ + {"role": "system", "content": WRITING_OUTLINE_SYSTEM}, + {"role": "user", "content": prompt}, + ], + temperature=0.5, + task_type="default", + ) + except Exception: + logger.exception("LLM review outline failed; using metadata-based fallback") + outline = self._fallback_review_outline(topic=topic, papers=papers, language=language) return { "topic": topic, @@ -175,14 +179,18 @@ async def analyze_gaps(self, project_id: int, research_topic: str) -> dict: 4. Potential innovation points 5. Suggested research directions""" - analysis = await self.llm.chat( - messages=[ - {"role": "system", "content": WRITING_GAP_SYSTEM}, - {"role": "user", "content": prompt}, - ], - temperature=0.5, - task_type="default", - ) + try: + analysis = await self.llm.chat( + messages=[ + {"role": "system", "content": WRITING_GAP_SYSTEM}, + {"role": "user", "content": prompt}, + ], + temperature=0.5, + task_type="default", + ) + except Exception: + logger.exception("LLM gap analysis failed; using metadata-based fallback") + analysis = self._fallback_gap_analysis(research_topic=research_topic, papers=papers) return { "topic": research_topic, @@ -190,6 +198,53 @@ async def analyze_gaps(self, project_id: int, research_topic: str) -> dict: "papers_analyzed": len(papers), } + @staticmethod + def _fallback_review_outline(topic: str, papers: list[Paper], language: str) -> str: + """Build a conservative outline from real project metadata when LLM is unavailable.""" + paper_lines = "\n".join(f"- {p.title} ({p.year or 'n.d.'})" for p in papers[:8]) or "- No papers available" + if language == "zh": + return f"""# {topic} 文献综述提纲 + +1. 研究背景与问题定义 +2. 已有文献的主要方向 +3. 方法与数据来源对比 +4. 证据强度、局限与争议 +5. 后续研究机会 + +参考文献线索： +{paper_lines}""" + return f"""# Literature Review Outline: {topic} + +1. Background and problem definition +2. Major themes in the available literature +3. Methods and data sources across papers +4. Evidence strength, limitations, and open disagreements +5. Future research opportunities + +Paper signals used: +{paper_lines}""" + + @staticmethod + def _fallback_gap_analysis(research_topic: str, papers: list[Paper]) -> str: + """Build a metadata-based gap analysis from real papers when LLM is unavailable.""" + years = [p.year for p in papers if p.year] + year_span = f"{min(years)}-{max(years)}" if years else "unknown years" + journals = sorted({p.journal for p in papers if p.journal})[:5] + journal_line = ", ".join(journals) if journals else "journals unavailable" + sample_titles = "\n".join(f"- {p.title}" for p in papers[:8]) or "- No papers available" + return f"""Research topic: {research_topic} + +Metadata-based gap analysis from {len(papers)} papers ({year_span}; {journal_line}): + +1. Coverage gaps: verify whether the current collection spans enough venues, years, and experimental settings. +2. Method gaps: compare whether papers rely on similar tooling or evaluation metrics, as repeated methods can leave alternatives under-tested. +3. Evidence gaps: prioritize papers with full text and OCR chunks before drawing strong conclusions. +4. Synthesis opportunities: cluster the collection by application, method, organism/system, and visualization target. +5. Next step: add recent papers and run RAG evidence consensus after indexing. + +Paper signals used: +{sample_titles}""" + async def generate_literature_review( self, project_id: int, diff --git a/backend/tests/test_upload.py b/backend/tests/test_upload.py index 13f85611..b28231a2 100644 --- a/backend/tests/test_upload.py +++ b/backend/tests/test_upload.py @@ -106,6 +106,47 @@ async def test_upload_rejects_duplicate_content(client: AsyncClient): assert "First Upload" in body["message"] +@pytest.mark.asyncio +async def test_batch_upload_skips_duplicate_content_and_continues(client: AsyncClient): + """Batch upload should skip duplicate PDFs without dropping later new files.""" + create_resp = await client.post("/api/v1/projects", json={"name": "Batch Dup Test"}) + assert create_resp.status_code == 201 + project_id = create_resp.json()["data"]["id"] + + duplicate_content = b"%PDF-1.4 duplicate in batch" + new_content = b"%PDF-1.4 new file in batch" + + with ( + patch("app.api.v1.upload.extract_metadata", _mock_metadata(title="First Upload")), + patch("app.api.v1.upload.process_papers_background", AsyncMock()), + ): + resp = await client.post( + f"/api/v1/projects/{project_id}/papers/upload", + files={"files": _make_pdf(duplicate_content)}, + ) + assert resp.status_code == 200 + + with ( + patch("app.api.v1.upload.extract_metadata", _mock_metadata(title="Batch New Upload")), + patch("app.api.v1.upload.process_papers_background", AsyncMock()), + ): + resp = await client.post( + f"/api/v1/projects/{project_id}/papers/upload", + files=[ + ("files", _make_pdf(duplicate_content)), + ("files", _make_pdf(new_content)), + ], + ) + + assert resp.status_code == 200 + body = resp.json() + assert body["data"]["total_uploaded"] == 1 + + async with async_session_factory() as session: + result = await session.execute(select(Paper).where(Paper.project_id == project_id)) + assert len(result.scalars().all()) == 2 + + @pytest.mark.asyncio async def test_upload_different_files_with_same_title_passes(client: AsyncClient): """Different PDF content but same title should NOT be rejected by content hash.""" diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index dd052d55..a054ab1b 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,23 +1,159 @@ import { defineConfig } from 'vitepress' +const guideSidebar = [ + { + text: 'Getting Started', + items: [ + { text: 'Quick Start', link: '/guide/getting-started' }, + { text: 'Architecture', link: '/guide/architecture' }, + { text: 'Configuration', link: '/guide/configuration' }, + { text: 'Deployment', link: '/guide/deployment' }, + ], + }, + { + text: 'Features', + items: [ + { text: 'Feature Guide', link: '/guide/features' }, + { text: 'Chat Playground', link: '/guide/chat' }, + { text: 'LangGraph Pipeline', link: '/guide/pipeline' }, + { text: 'MCP Integration', link: '/guide/mcp' }, + { text: 'Testing', link: '/guide/testing' }, + ], + }, +] + +const moduleSidebar = [ + { + text: 'Pipeline Modules', + items: [ + { text: 'Overview', link: '/modules/' }, + { text: 'Keywords', link: '/modules/keywords' }, + { text: 'Search', link: '/modules/search' }, + { text: 'Deduplication', link: '/modules/dedup' }, + { text: 'Subscription', link: '/modules/subscription' }, + { text: 'Crawler', link: '/modules/crawler' }, + { text: 'OCR', link: '/modules/ocr' }, + { text: 'RAG', link: '/modules/rag' }, + { text: 'Writing', link: '/modules/writing' }, + ], + }, +] + +const apiSidebar = [ + { + text: 'API Reference', + items: [ + { text: 'Overview', link: '/api/' }, + { text: 'Projects', link: '/api/projects' }, + { text: 'Papers', link: '/api/papers' }, + { text: 'Keywords', link: '/api/keywords' }, + { text: 'Search', link: '/api/search' }, + { text: 'Dedup', link: '/api/dedup' }, + { text: 'Crawler', link: '/api/crawler' }, + { text: 'OCR', link: '/api/ocr' }, + { text: 'RAG', link: '/api/rag' }, + { text: 'Writing', link: '/api/writing' }, + { text: 'Chat', link: '/api/chat' }, + { text: 'Conversations', link: '/api/conversations' }, + { text: 'Settings', link: '/api/settings' }, + { text: 'Tasks', link: '/api/tasks' }, + { text: 'Pipelines', link: '/api/pipelines' }, + { text: 'Subscriptions', link: '/api/subscription' }, + ], + }, + { + text: 'Extended APIs', + collapsed: true, + items: [ + { text: 'Activities', link: '/api/activities' }, + { text: 'Analytics', link: '/api/analytics' }, + { text: 'Analysis', link: '/api/analysis' }, + { text: 'API Keys', link: '/api/api_keys' }, + { text: 'Audio Overviews', link: '/api/audio_overviews' }, + { text: 'Collections', link: '/api/collections' }, + { text: 'Concepts', link: '/api/concepts' }, + { text: 'Export', link: '/api/export' }, + { text: 'Feed', link: '/api/feed' }, + { text: 'Library', link: '/api/library' }, + { text: 'Notifications', link: '/api/notifications' }, + { text: 'Reviews', link: '/api/reviews' }, + { text: 'Team Members', link: '/api/team_members' }, + { text: 'Upload', link: '/api/upload' }, + ], + }, +] + +const zhGuideSidebar = [ + { + text: '入门', + items: [ + { text: '快速开始', link: '/zh/guide/getting-started' }, + { text: '系统架构', link: '/zh/guide/architecture' }, + { text: '配置说明', link: '/zh/guide/configuration' }, + { text: '部署指南', link: '/zh/guide/deployment' }, + ], + }, + { + text: '功能', + items: [ + { text: '功能指南', link: '/zh/guide/features' }, + { text: '对话工作台', link: '/zh/guide/chat' }, + { text: 'LangGraph 流水线', link: '/zh/guide/pipeline' }, + { text: 'MCP 集成', link: '/zh/guide/mcp' }, + { text: '测试', link: '/zh/guide/testing' }, + ], + }, +] + +const zhModuleSidebar = [ + { + text: '管道模块', + items: [ + { text: '概览', link: '/zh/modules/' }, + { text: '关键词', link: '/zh/modules/keywords' }, + { text: '检索', link: '/zh/modules/search' }, + { text: '去重', link: '/zh/modules/dedup' }, + { text: '订阅', link: '/zh/modules/subscription' }, + { text: '爬虫', link: '/zh/modules/crawler' }, + { text: 'OCR', link: '/zh/modules/ocr' }, + { text: 'RAG', link: '/zh/modules/rag' }, + { text: '写作', link: '/zh/modules/writing' }, + ], + }, +] + +const zhApiSidebar = [ + { + text: 'API 参考', + items: [ + { text: '概览', link: '/zh/api/' }, + { text: 'Projects', link: '/zh/api/projects' }, + { text: 'Papers', link: '/zh/api/papers' }, + { text: 'Keywords', link: '/zh/api/keywords' }, + { text: 'Search', link: '/zh/api/search' }, + { text: 'Dedup', link: '/zh/api/dedup' }, + { text: 'Crawler', link: '/zh/api/crawler' }, + { text: 'OCR', link: '/zh/api/ocr' }, + { text: 'RAG', link: '/zh/api/rag' }, + { text: 'Writing', link: '/zh/api/writing' }, + { text: 'Chat', link: '/zh/api/chat' }, + { text: 'Conversations', link: '/zh/api/conversations' }, + { text: 'Settings', link: '/zh/api/settings' }, + { text: 'Tasks', link: '/zh/api/tasks' }, + { text: 'Pipelines', link: '/zh/api/pipelines' }, + { text: 'Subscriptions', link: '/zh/api/subscription' }, + ], + }, +] + export default defineConfig({ title: 'Omelette', - description: 'Scientific Literature Lifecycle Management System', + description: 'AI-Powered Scientific Literature Lifecycle Management', base: '/omelette/', ignoreDeadLinks: [ - 'http://localhost:3000', - 'http://127.0.0.1:3000', - 'http://localhost:11434', - 'http://localhost:8000', /^http:\/\/localhost/, /^http:\/\/127\.0\.0\.1/, - /brainstorms\//, - /solutions\//, - /research\//, - /test-failures\//, - /deployment\//, - /\.mdc$/, ], head: [ @@ -33,80 +169,13 @@ export default defineConfig({ themeConfig: { nav: [ { text: 'Guide', link: '/guide/getting-started' }, - { text: 'API Reference', link: '/api/' }, + { text: 'API', link: '/api/' }, { text: 'Modules', link: '/modules/' }, ], sidebar: { - '/guide/': [ - { - text: 'Introduction', - items: [ - { text: 'Getting Started', link: '/guide/getting-started' }, - { text: 'Architecture', link: '/guide/architecture' }, - { text: 'Configuration', link: '/guide/configuration' }, - { text: 'Deployment', link: '/guide/deployment' }, - ], - }, - { - text: 'V2 Features', - items: [ - { text: 'Chat Playground', link: '/guide/chat' }, - { text: 'LangGraph Pipeline', link: '/guide/pipeline' }, - { text: 'MCP Integration', link: '/guide/mcp' }, - ], - }, - { - text: 'Phase 4 Features', - items: [ - { text: 'Feature Guide', link: '/guide/features' }, - ], - }, - { - text: 'Quality', - items: [ - { text: 'Testing Guide', link: '/guide/testing' }, - ], - }, - ], - '/modules/': [ - { - text: 'Modules', - items: [ - { text: 'Overview', link: '/modules/' }, - { text: '1. Keywords', link: '/modules/keywords' }, - { text: '2. Literature Search', link: '/modules/search' }, - { text: '3. Deduplication', link: '/modules/dedup' }, - { text: '4. Subscription', link: '/modules/subscription' }, - { text: '5. PDF Crawler', link: '/modules/crawler' }, - { text: '6. OCR', link: '/modules/ocr' }, - { text: '7. RAG Knowledge Base', link: '/modules/rag' }, - { text: '8. Writing Assistant', link: '/modules/writing' }, - ], - }, - ], - '/api/': [ - { - text: 'API Reference', - items: [ - { text: 'Overview', link: '/api/' }, - { text: 'Projects', link: '/api/projects' }, - { text: 'Papers', link: '/api/papers' }, - { text: 'Keywords', link: '/api/keywords' }, - { text: 'Search', link: '/api/search' }, - { text: 'Dedup', link: '/api/dedup' }, - { text: 'OCR', link: '/api/ocr' }, - { text: 'Crawler', link: '/api/crawler' }, - { text: 'Subscription', link: '/api/subscription' }, - { text: 'RAG', link: '/api/rag' }, - { text: 'Writing', link: '/api/writing' }, - { text: 'Chat', link: '/api/chat' }, - { text: 'Conversations', link: '/api/conversations' }, - { text: 'Settings', link: '/api/settings' }, - { text: 'Tasks', link: '/api/tasks' }, - { text: 'Pipelines', link: '/api/pipelines' }, - ], - }, - ], + '/guide/': guideSidebar, + '/modules/': moduleSidebar, + '/api/': apiSidebar, }, }, }, @@ -117,80 +186,13 @@ export default defineConfig({ themeConfig: { nav: [ { text: '指南', link: '/zh/guide/getting-started' }, - { text: 'API 参考', link: '/zh/api/' }, + { text: 'API', link: '/zh/api/' }, { text: '模块', link: '/zh/modules/' }, ], sidebar: { - '/zh/guide/': [ - { - text: '介绍', - items: [ - { text: '快速开始', link: '/zh/guide/getting-started' }, - { text: '系统架构', link: '/zh/guide/architecture' }, - { text: '配置说明', link: '/zh/guide/configuration' }, - { text: '部署指南', link: '/zh/guide/deployment' }, - ], - }, - { - text: 'V2 新功能', - items: [ - { text: '对话工作台', link: '/zh/guide/chat' }, - { text: 'LangGraph 流水线', link: '/zh/guide/pipeline' }, - { text: 'MCP 集成', link: '/zh/guide/mcp' }, - ], - }, - { - text: 'Phase 4 新功能', - items: [ - { text: '功能指南', link: '/zh/guide/features' }, - ], - }, - { - text: '质量保障', - items: [ - { text: '测试指南', link: '/zh/guide/testing' }, - ], - }, - ], - '/zh/modules/': [ - { - text: '功能模块', - items: [ - { text: '概览', link: '/zh/modules/' }, - { text: '1. 关键词管理', link: '/zh/modules/keywords' }, - { text: '2. 文献检索', link: '/zh/modules/search' }, - { text: '3. 去重过滤', link: '/zh/modules/dedup' }, - { text: '4. 增量订阅', link: '/zh/modules/subscription' }, - { text: '5. PDF 爬取', link: '/zh/modules/crawler' }, - { text: '6. OCR 解析', link: '/zh/modules/ocr' }, - { text: '7. RAG 知识库', link: '/zh/modules/rag' }, - { text: '8. 写作辅助', link: '/zh/modules/writing' }, - ], - }, - ], - '/zh/api/': [ - { - text: 'API 参考', - items: [ - { text: '概览', link: '/zh/api/' }, - { text: 'Projects', link: '/zh/api/projects' }, - { text: 'Papers', link: '/zh/api/papers' }, - { text: 'Keywords', link: '/zh/api/keywords' }, - { text: 'Search', link: '/zh/api/search' }, - { text: 'Dedup', link: '/zh/api/dedup' }, - { text: 'OCR', link: '/zh/api/ocr' }, - { text: 'Crawler', link: '/zh/api/crawler' }, - { text: 'Subscription', link: '/zh/api/subscription' }, - { text: 'RAG', link: '/zh/api/rag' }, - { text: 'Writing', link: '/zh/api/writing' }, - { text: 'Chat', link: '/zh/api/chat' }, - { text: 'Conversations', link: '/zh/api/conversations' }, - { text: 'Settings', link: '/zh/api/settings' }, - { text: 'Tasks', link: '/zh/api/tasks' }, - { text: 'Pipelines', link: '/zh/api/pipelines' }, - ], - }, - ], + '/zh/guide/': zhGuideSidebar, + '/zh/modules/': zhModuleSidebar, + '/zh/api/': zhApiSidebar, }, }, }, diff --git a/docs/brainstorms/2026-03-11-ux-architecture-upgrade-brainstorm.md b/docs/brainstorms/2026-03-11-ux-architecture-upgrade-brainstorm.md deleted file mode 100644 index 42420690..00000000 --- a/docs/brainstorms/2026-03-11-ux-architecture-upgrade-brainstorm.md +++ /dev/null @@ -1,361 +0,0 @@ ---- -date: 2026-03-11 -topic: ux-architecture-upgrade ---- - -# Omelette v2.0：用户体验与架构全面升级 - -## 我们要构建什么 - -将 Omelette 从「以项目为中心的工具集合」转型为「以聊天为中心的科研助手」。核心变化： - -1. **ChatGPT 风格首页**——用户进入即可开始对话，选择知识库、工具模式，获得带引用的 AI 回答 -2. **知识库管理中心**——创建/管理多个知识库（取代 Project 概念），支持关键词检索添加和 PDF 手动上传，去重冲突可视化解决 -3. **MCP 协议支持**——让 Claude Code、Cursor、Claude Desktop 等工具直接调用 Omelette 的知识库检索和文献查找能力 -4. **多模型支持**——OpenAI、Anthropic、阿里云百炼、火山引擎等，前端可切换 -5. **现代 UI 重构**——shadcn/ui 组件库 + Vercel AI SDK 流式聊天 + react-markdown 富文本渲染 - -## 为什么选择这个方案 - -### 考虑过的方案 - -| 方案 | 描述 | 取舍 | -|------|------|------| -| **A: LlamaIndex + LangGraph（选中）** | LlamaIndex 做 RAG 数据层，LangGraph 做流程编排，MCP 做外部接入 | 最完整但复杂度高 | -| B: 纯 LlamaIndex | 所有功能在 LlamaIndex 生态内实现 | 简单但 HITL 和流程编排弱 | -| C: 保持现有架构 | 在现有 ChromaDB + 自定义服务上增量优化 | 无迁移成本但缺少高级特性 | - -**选择方案 A 的理由：** -- LlamaIndex 在科研文献 RAG 场景极其成熟（PDF 解析、混合检索、增量索引、引用溯源原生支持） -- LangGraph 的 Human-in-the-Loop + 状态检查点天然适配去重冲突处理 -- MCP 可以挂载到同一个 FastAPI 应用，零额外部署成本 -- 这是 2025-2026 年 AI 应用开发的标准技术栈组合 - -## 关键决策 - -### 1. 产品架构：以聊天为核心入口 - -- **决策**：首页从项目列表变为 Playground 聊天界面 -- **理由**：科研人员最高频的操作是「问问题」和「找文献」，聊天界面降低使用门槛 -- **参考**：ChatGPT、Perplexity 的设计哲学 - -### 2. 概念重命名：Project → Knowledge Base（知识库） - -- **决策**：将 Project 概念重命名为「知识库」，一个知识库保存一类论文 -- **理由**：「知识库」更直观地表达了它的用途——一个可检索的文献集合 -- **影响**：数据模型不变（Project 表），仅前端展示和 API 命名调整 - -### 3. 技术栈升级 - -| 层级 | 现有 | 升级为 | 理由 | -|------|------|--------|------| -| RAG 数据层 | 自定义 ChromaDB 集成 | LlamaIndex + ChromaDB | 混合检索、语义分块、增量索引、引用追踪 | -| 流程编排 | 手动 service 调用 | LangGraph StateGraph | HITL、状态检查点、流程可视化 | -| LLM 抽象 | 自定义 LLMClient | LangChain ChatModel | 统一多厂商接口（OpenAI/Anthropic/阿里云/火山引擎） | -| 外部接入 | 无 | MCP Server (FastMCP) | 让 Claude Code/Cursor 直接调用 | -| 前端 UI 库 | 自定义 Tailwind 组件 | shadcn/ui + Radix UI | 设计感强、可访问性好、维护成本低 | -| 聊天 SDK | 自定义 fetch | Vercel AI SDK (@ai-sdk/react) | useChat hook、流式渲染、模型切换 | -| Markdown 渲染 | 无 | react-markdown + remark-math + rehype-katex | 数学公式、代码高亮、引用卡片 | -| 动画 | 无 | Framer Motion | 消息进入/退出动画、页面切换 | - -### 4. 多模型支持策略 - -| 提供商 | 集成方式 | 配置 | -|--------|----------|------| -| OpenAI | `ChatOpenAI` | OPENAI_API_KEY, OPENAI_MODEL | -| Anthropic | `ChatAnthropic` | ANTHROPIC_API_KEY, ANTHROPIC_MODEL | -| 阿里云百炼 | `ChatOpenAI(base_url=dashscope)` | ALIYUN_API_KEY, ALIYUN_MODEL | -| 火山引擎 | `ChatOpenAI(base_url=volcengine)` | VOLCENGINE_API_KEY, VOLCENGINE_MODEL | -| 本地模型 | `ChatOllama` | OLLAMA_BASE_URL, OLLAMA_MODEL | -| Mock | 内置 Mock | LLM_PROVIDER=mock | - -### 5. 前端路由重构 - -``` -/ → Playground（聊天首页） -/knowledge-bases → 知识库列表 -/knowledge-bases/:id → 知识库详情（论文管理、添加、订阅） -/knowledge-bases/:id/add → 添加论文（关键词检索/PDF上传） -/history → 对话历史 -/settings → 设置（模型选择、API Key 配置） -``` - -### 6. MCP 集成设计 - -```python -# 挂载到同一 FastAPI 应用 -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("Omelette Literature Server", json_response=True) - -@mcp.tool() -async def search_knowledge_base(query: str, kb_id: int, top_k: int = 5) -> str: - """在指定知识库中搜索相关文献片段""" - -@mcp.tool() -async def lookup_paper(doi: str = None, title: str = None) -> str: - """按 DOI 或标题查找论文""" - -@mcp.tool() -async def find_citations(text: str, kb_id: int) -> str: - """为一段文本在知识库中找到可能的引用来源""" - -@mcp.tool() -async def list_knowledge_bases() -> str: - """列出所有可用的知识库""" - -# FastAPI 主应用 -app.mount("/mcp", mcp.http_app()) -``` - -## 详细功能设计 - -### 功能 1：Playground 聊天首页 - -**交互参考**：ChatGPT 首页（见参考图） - -**布局**： -- 左侧：窄图标侧边栏（首页、知识库、对话历史、设置） -- 中央： - - 未开始对话时：欢迎语 + 聊天输入框 + 快捷模板卡片 - - 对话中：消息列表（上方）+ 输入框（底部固定） -- 输入框功能： - - 知识库选择器（下拉，可多选） - - 工具模式选择：普通问答（默认）| 引用查找 | 文献综述 | 研究空白分析 - - 附件上传（拖拽 PDF） - - 引用开关（Citation toggle） - - 模型选择（在输入框上方或设置中） - -**AI 回答格式**： -- Markdown 渲染（支持表格、代码、列表） -- 数学公式（KaTeX） -- 内联引用标记 [1][2]，点击展开引用卡片（论文标题、作者、年份、DOI） -- 流式输出（SSE） - -**快捷模板**： -- "帮我总结这个领域的研究现状" -- "找出这段文字的引用来源" -- "生成文献综述提纲" -- "分析当前研究空白" - -### 功能 2：知识库管理 - -**知识库列表页**： -- 卡片式展示（名称、论文数、最后更新时间、标签） -- 新建知识库（名称、描述、领域标签） -- 搜索/筛选 - -**知识库详情页**： -- 论文列表（标题、作者、年份、状态标签） -- 索引统计（已索引/总数、chunk 数量） -- 订阅管理（活跃订阅列表、增量更新记录） - -**添加论文 —— 两种模式**： - -**模式 A：关键词检索添加** -1. 输入关键词（手动输入 OR 给主题让 AI 生成关键词） -2. 选择数据源（Semantic Scholar、OpenAlex、arXiv、Crossref） -3. 设置检索篇数上限（10-50，配置最大值） -4. 执行检索 → 展示结果预览 -5. **去重冲突处理**： - - 类似 git 冲突的左右对比界面 - - 每条冲突显示：旧记录 vs 新记录，高亮差异字段 - - 操作：保留旧的 | 保留新的 | 合并 | 跳过 - - 一键 AI 解决：LLM 判断是否真的重复，自动选择最优记录 -6. 确认后入库 → 自动进入下载→OCR→索引流水线 - -**模式 B：手动 PDF 上传** -1. 拖拽或点击上传多个 PDF -2. LlamaIndex 提取元数据（标题、作者、DOI、摘要） -3. 自动检查重复（与知识库现有论文对比） -4. 冲突处理流程同上 -5. 确认后直接进入 OCR→索引流水线 - -**订阅管理**： -- 为知识库添加多个订阅规则（关键词+数据源+频率） -- 增量更新时自动执行：检索→去重→下载→OCR→索引 -- 可查看每次更新的新增论文 - -### 功能 3：对话历史 - -- 按时间排序的对话列表 -- 每条对话显示：标题（AI 自动生成）、使用的知识库、时间 -- 点击恢复对话上下文 -- 可删除/重命名 - -### 功能 4：设置页 - -**模型配置**： -- 当前模型选择（下拉） -- 各提供商 API Key 输入（密码类型，可显示/隐藏） -- 连接测试按钮 -- 高级参数（temperature、max_tokens） - -**系统配置**： -- 数据存储路径 -- 代理设置（HTTP_PROXY） -- 默认检索源 -- 检索篇数上限 - -**说明**：所有设置同时支持 .env 文件配置和前端界面配置，前端配置优先级高于 .env - -### 功能 5：补充功能（产品经理视角） - -基于真实科研人需求的补充： - -1. **PDF 在线预览**——在知识库详情中点击论文可预览 PDF，支持高亮标注 -2. **导出功能**——导出引用格式（BibTeX、GB/T 7714、APA）、导出检索报告 -3. **笔记功能**——每篇论文可添加笔记/标签，笔记也参与 RAG 检索 -4. **研究进度看板**——可视化展示：已检索→已下载→已索引的漏斗图 -5. **论文关系图谱**——基于引用关系的知识图谱可视化 -6. **快捷键支持**——Cmd+K 快速搜索、Cmd+N 新建对话 -7. **暗色模式**——深色/浅色主题切换 -8. **多语言**——中英文界面切换（中文优先） -9. **WebSocket 实时进度**——长时间任务（检索、下载、OCR）的实时进度推送 - -## 技术架构图 - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Frontend (React 19) │ -│ shadcn/ui + Vercel AI SDK + react-markdown + Framer Motion │ -│ Zustand (UI) + TanStack Query (Server) + useChat (Chat) │ -├─────────────────────────────────────────────────────────────┤ -│ ↕ REST API + SSE │ -├──────────────────────┬──────────────────────────────────────┤ -│ FastAPI Backend │ MCP Server │ -│ │ (mounted at /mcp) │ -├──────────────────────┴──────────────────────────────────────┤ -│ Service Layer │ -│ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌──────────────┐ │ -│ │LangGraph│ │LlamaIndex│ │LangChain│ │ Existing │ │ -│ │ Workflow │ │ RAG │ │ChatModel│ │ Services │ │ -│ │ Engine │ │ Engine │ │ Multi │ │(search,dedup, │ │ -│ │ │ │ │ │ Provider│ │crawler,ocr) │ │ -│ └────┬────┘ └────┬────┘ └────┬────┘ └──────┬───────┘ │ -│ │ │ │ │ │ -├───────┴────────────┴────────────┴───────────────┴──────────┤ -│ Data Layer │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │ -│ │ SQLite │ │ ChromaDB │ │PDF Store │ │ .env / │ │ -│ │(SQLAlchemy│ │(Vector) │ │ (Local) │ │ Settings │ │ -│ │ async) │ │ │ │ │ │ (DB) │ │ -│ └──────────┘ └──────────┘ └──────────┘ └────────────┘ │ -└─────────────────────────────────────────────────────────────┘ -``` - -## 新增依赖 - -### 后端新增 - -```toml -# pyproject.toml 新增依赖 -dependencies = [ - # LlamaIndex 核心 - "llama-index-core>=0.12", - "llama-index-vector-stores-chroma>=0.4", - "llama-index-embeddings-huggingface>=0.4", - "llama-index-retrievers-bm25>=0.4", - "llama-index-postprocessor-sentence-transformer-rerank>=0.3", - # LangGraph 编排 - "langgraph>=0.4", - "langchain-core>=0.3", - "langchain-openai>=0.3", - "langchain-anthropic>=0.3", - # MCP - "mcp>=1.26", - # 现有依赖保留... -] -``` - -### 前端新增 - -```json -{ - "dependencies": { - "@ai-sdk/react": "^5.0.0", - "ai": "^5.0.0", - "react-markdown": "^10.1.0", - "remark-gfm": "^4.0.0", - "remark-math": "^6.0.0", - "rehype-katex": "^7.0.0", - "rehype-highlight": "^7.0.0", - "framer-motion": "^11.0.0", - "katex": "^0.16.0" - } -} -``` - -**shadcn/ui**：通过 CLI 安装，不是 npm 包依赖，组件直接复制到项目中。 - -## 数据模型变更 - -### 新增表 - -| 表名 | 说明 | -|------|------| -| **Conversation** | 对话历史：id, title, knowledge_base_ids, model, tool_mode, created_at, updated_at | -| **Message** | 消息：id, conversation_id, role (user/assistant/system), content, citations (JSON), created_at | -| **UserSettings** | 用户设置：id, key, value, updated_at（前端配置持久化） | - -### 现有表调整 - -| 表 | 变更 | -|----|------| -| **Project** | 字段不变，前端展示为「知识库」，增加 `icon`, `color` 字段用于 UI 展示 | -| **Paper** | 增加 `notes` TEXT 字段（用户笔记） | - -## 实施路线图 - -### Phase 1: 基础设施升级（1-2 周） -- [ ] 引入 shadcn/ui，初始化组件库 -- [ ] 重构前端路由（Playground 首页） -- [ ] 引入 Vercel AI SDK + react-markdown -- [ ] 后端新增 Conversation/Message 模型和 API -- [ ] 后端引入 LangChain ChatModel 多模型支持 -- [ ] 前端设置页（模型选择、API Key 配置） - -### Phase 2: 聊天核心（1-2 周） -- [ ] Playground 聊天 UI（消息列表、流式输出、引用卡片） -- [ ] 知识库选择器 + 工具模式选择 -- [ ] 后端 SSE 流式聊天 API -- [ ] 对话历史保存和恢复 -- [ ] 引用溯源标注 - -### Phase 3: 知识库管理升级（1-2 周） -- [ ] 知识库列表页重构（卡片式） -- [ ] 论文添加流程（关键词检索 + PDF 上传双模式） -- [ ] 去重冲突可视化解决界面 -- [ ] 一键 AI 去重 -- [ ] 实时进度推送（WebSocket/SSE） - -### Phase 4: LlamaIndex RAG 升级（1 周） -- [ ] 引入 LlamaIndex，替换现有 RAG 层 -- [ ] 混合检索（Vector + BM25） -- [ ] 重排序（bge-reranker） -- [ ] 增量索引（添加/删除文档无需全量重建） -- [ ] 语义分块（SentenceSplitter / SemanticSplitter） - -### Phase 5: LangGraph + MCP（1 周） -- [ ] LangGraph 编排：关键词检索→去重→下载→OCR→索引 流水线 -- [ ] MCP Server 搭建（search_knowledge_base, lookup_paper, find_citations） -- [ ] MCP 连接测试（Claude Desktop / Cursor） - -### Phase 6: 打磨与补充（持续） -- [ ] 暗色模式 -- [ ] 多语言（中/英） -- [ ] PDF 在线预览 -- [ ] 研究进度看板 -- [ ] 快捷键 -- [ ] 导出功能 - -## 开放问题 - -1. **Embedding 模型部署**——bge-m3 需要 GPU 或用 API（如阿里云/HuggingFace Inference）。当前环境是否有 GPU？如果没有，是否接受 API 调用？ -2. **LlamaParse vs pdfplumber**——LlamaParse 对科研论文解析质量更高但有成本（免费 10K 页/月），是否使用？ -3. **数据库迁移**——是否需要引入 Alembic 做正式的数据库迁移？ -4. **多用户**——当前为单用户设计，未来是否需要考虑多用户？ - -## 下一步 - -→ 确认方向后，执行 `/workflows:plan` 生成详细实施计划并开始编码 diff --git a/docs/brainstorms/2026-03-12-chat-message-routing-chain-brainstorm.md b/docs/brainstorms/2026-03-12-chat-message-routing-chain-brainstorm.md deleted file mode 100644 index 36cd0167..00000000 --- a/docs/brainstorms/2026-03-12-chat-message-routing-chain-brainstorm.md +++ /dev/null @@ -1,340 +0,0 @@ ---- -date: 2026-03-12 -topic: chat-message-routing-chain -depends_on: - - 2026-03-12-frontend-ux-robustness-brainstorm.md - - 2026-03-11-ux-architecture-upgrade-brainstorm.md ---- - -# 聊天消息路由链全面重构 - -## 我们要构建什么 - -对 Omelette 的聊天消息处理链路进行**全面重构**，覆盖前端协议层、状态管理、后端处理管道三个维度。目标是从当前的"手工 SSE 解析 + 巨型组件状态管理 + 单体流函数"升级为"标准化协议 + 抽象状态层 + 可编排管道"。 - -核心变化： -1. **协议层**：自定义 SSE 解析 → Vercel AI SDK 5.0 Data Stream Protocol -2. **前端状态**：PlaygroundPage ~15 个 useState → `useChat` + Transport 抽象 -3. **后端管道**：`_stream_chat` 单体函数 (230+ 行) → LangGraph StateGraph 可编排节点 -4. **可靠性**：无错误处理/无断流重试 → 标准错误 Part + Resumable Streams - -## 现状分析：当前消息路由链 - -### 完整链路图 - -``` -用户输入 - ↓ -ChatInput.handleSubmit (trim → onSend → clear) - ↓ -PlaygroundPage.handleSend - ├─ 创建 user/assistant LocalMessage - ├─ pendingDeltaRef + assistantIdRef 初始化 - ├─ setMessages([...prev, userMsg, assistantMsg]) - ├─ setIsStreaming(true) - ├─ AbortController 创建 - ↓ -streamChat(fetch POST /api/v1/chat/stream) ←── chat-api.ts - ├─ fetch + ReadableStream.getReader() - ├─ TextDecoder + 手动 buffer split('\n') - ├─ 解析 `event:` + `data:` + 空行 → yield SSEEvent - ↓ -for await (const event of gen) ←── PlaygroundPage.tsx - ├─ text_delta → pendingDeltaRef + 80ms debounce flush - ├─ citation → isCitation() → normalizeCitation() → append - ├─ thinking_step → update/append thinkingSteps - ├─ citation_enhanced → update citations[index].excerpt - ├─ a2ui_surface → append to a2uiMessages - ├─ message_end → flushDelta + setConversationId + navigate - └─ error → ❌ 未处理！ - ↓ -finally: cleanup (timer, flush, isStreaming=false) -``` - -### 后端 `_stream_chat` 链路 - -``` -POST /api/v1/chat/stream - ↓ -_stream_chat(request, db) → AsyncGenerator[str, None] - ├─ message_start - ├─ thinking_step(understand, running) - ├─ _get_rag_service_for_chat() → (rag, llm) - ├─ thinking_step(understand, done) - │ - ├─ [if knowledge_base_ids]: - │ ├─ thinking_step(retrieve, running) - │ ├─ asyncio.gather(*rag_tasks) ← RAGService.query() - │ ├─ thinking_step(retrieve, done) - │ ├─ thinking_step(rank, running) - │ ├─ Load papers, build citations → yield citation × N - │ ├─ thinking_step(rank, done) - │ ├─ thinking_step(clean, running) - │ ├─ _clean_excerpt × M (LLM, semaphore, timeout) - │ ├─ yield citation_enhanced × M - │ └─ thinking_step(clean, done) - │ - ├─ Build history_messages from DB - ├─ Build messages (system + history + user) - ├─ thinking_step(generate, running) - ├─ llm.chat_stream() → yield text_delta × K - ├─ thinking_step(generate, done) - ├─ Create conversation + messages in DB - ├─ thinking_step(complete, done) - └─ message_end -``` - -### 现存问题 - -| # | 问题 | 严重度 | 影响 | -|---|------|--------|------| -| R-1 | 手写 SSE 解析器，无标准化 | 高 | 无法利用生态工具、难以测试、易出 bug | -| R-2 | 前端不处理 `error` SSE 事件 | 严重 | 后端发 error 前端静默忽略，用户无感知 | -| R-3 | SSE 断流无重试 | 高 | 网络闪断直接丢失响应 | -| R-4 | `response.body!` 非空断言 | 中 | 已改为 `?.` 但仍无优雅降级 | -| R-5 | PlaygroundPage ~15 个 useState/useRef | 高 | 状态逻辑与 UI 高度耦合，难测试难复用 | -| R-6 | text_delta 80ms 手动防抖 | 中 | 非标准实现，性能特征不可控 | -| R-7 | `_stream_chat` 单体函数 230+ 行 | 高 | 步骤间耦合，难以独立测试/复用/扩展 | -| R-8 | thinking_step 硬编码在流函数中 | 中 | 无法灵活添加/移除/重排步骤 | -| R-9 | citation 处理 (清洗/增强) 内联在流中 | 中 | 清洗超时影响整条流 | -| R-10 | fetch/axios 混用 | 中 | 流用 fetch、其他用 axios，错误处理不一致 | -| R-11 | 消息模型 (LocalMessage) 非标准 | 中 | 自定义接口，与 AI SDK UIMessage 不兼容 | - -## 为什么选择这个方案 - -### 考虑过的方案 - -| 方案 | 描述 | 取舍 | -|------|------|------| -| **A: Vercel AI SDK 5.0 + LangGraph（选中）** | 前端 useChat + Data Stream Protocol，后端 LangGraph StateGraph 编排 | 最彻底，但改动量大；获得标准化协议+可编排管道+类型安全 | -| B: 自建标准化 SSE + 中间件链 | 保留自定义 SSE 但规范化格式，后端用 Express 风格中间件链 | 轻量灵活，但丢失 AI SDK 生态优势（自动重试、断流恢复、工具调用等） | -| C: 增量修补 | 仅修 error 处理、抽取状态、拆分函数 | 改动最小，但不解决根本架构问题，长期技术债累积 | - -**选择方案 A 的理由：** -- Vercel AI SDK 5.0 的 transport 架构天然支持自定义后端（包括 FastAPI Python 后端） -- Data Stream Protocol 的 `data-*` 自定义 Part 可以覆盖所有 Omelette 的自定义事件（citation、thinking、a2ui） -- LangGraph 项目已经引入，且 StateGraph 天然适合"有条件分支+检查点+HITL"的聊天管道 -- 一次性解决协议标准化、状态管理、后端可编排三个问题，避免分三次重构 - -## 关键决策 - -### 1. 协议层：Vercel AI SDK 5.0 Data Stream Protocol - -- **决策**：前端迁移到 `@ai-sdk/react` 的 `useChat` + `DefaultChatTransport` -- **SSE 格式**：后端输出标准 Data Stream Protocol SSE（`data: {"type":"..."}` 格式） -- **自定义事件映射**： - - | 当前事件 | AI SDK 映射 | 说明 | - |---------|------------|------| - | `text_delta` | `text-start` + `text-delta` + `text-end` | 标准 text streaming，有 ID 追踪 | - | `citation` | `data-citation` | 自定义 data Part | - | `citation_enhanced` | `data-citation-enhanced` | 自定义 data Part | - | `thinking_step` | `data-thinking` | 自定义 data Part | - | `a2ui_surface` | `data-a2ui` | 自定义 data Part | - | `message_start` | `start` (messageId) | 标准 Part | - | `message_end` | `finish` | 标准 Part | - | `error` | `error` (errorText) | 标准 Part | - -- **理由**：Data Stream Protocol 的 `data-*` 类型是专门为自定义数据设计的扩展点，无需 hack - -### 2. 前端状态管理：useChat 替代手动 useState - -- **决策**：用 `useChat` hook 管理 messages、status、streaming 状态 -- **消息模型**：从 `LocalMessage` 迁移到 `UIMessage` + `parts` -- **自定义数据访问**：通过 `useChat` 的 `onMessage` 或 `parts` 过滤来处理 `data-citation` 等 -- **影响**：PlaygroundPage 从 ~15 个 useState 精简到核心交互状态（sidebarCollapsed、toolMode 等） -- **理由**：useChat 内部已处理好 streaming 状态、消息追加、abort、重试等逻辑 - -### 3. 后端管道：LangGraph StateGraph - -- **决策**：将 `_stream_chat` 拆分为 LangGraph 节点 -- **节点设计**： - - ``` - [understand] → [retrieve] → [rank] → [clean] → [generate] → [persist] → [complete] - ↓ (无 KB) - [generate] → [persist] → [complete] - ``` - - | 节点 | 职责 | 输入 | 输出 | - |------|------|------|------| - | understand | 解析请求，获取 LLM/RAG 服务 | request | llm, rag, parsed_query | - | retrieve | RAG 查询多个知识库 | rag, kb_ids, query | raw_results | - | rank | 构建引用，加载论文元数据 | raw_results | citations | - | clean | LLM 清洗引用摘要 | citations, llm | enhanced_citations | - | generate | LLM 流式生成回答 | messages, llm | text_stream | - | persist | 保存对话和消息到 DB | conversation, messages | conversation_id | - | complete | 生成结束信号 | all | message_end | - -- **SSE 发射**：每个节点通过 `StreamWriter` 发射标准 Data Stream Protocol 事件 -- **条件路由**：`retrieve` 节点根据 `knowledge_base_ids` 是否存在决定是否跳过到 `generate` -- **理由**： - - 每个节点可独立测试 - - 条件路由已内置（无需 if/else 嵌套） - - 未来可加入 HITL 检查点（如引用确认后再生成） - - 可复用已有的 LangGraph checkpointing 基础设施 - -### 4. 可靠性：错误处理（核心）+ 断流恢复（增强） - -- **核心（Phase 1 同步完成）**： - - 错误：标准 `error` Part + 前端 `useChat` 的 `error` 状态自动处理 - - abort：`useChat` 内置 `stop()` 方法 -- **增强（后续迭代）**： - - 前端：AI SDK 5.0 内置 `reconnect` 能力（`prepareReconnectToStreamRequest`） - - 后端：LangGraph 检查点 → 可从任意节点恢复 -- **范围界定**：Resumable Streams 是独立增强特性，不阻塞主体重构。当前先确保错误和中断不会导致 UI 崩溃，断流恢复留待第二迭代。 -- **理由**：先解决"断了会崩"（严重），再解决"断了能续"（增强） - -### 5. 后端 SSE 输出适配 - -- **决策**：创建 `StreamWriter` 工具类，封装 Data Stream Protocol 格式输出 -- **格式**：`data: {"type":"...", ...}\n\n`（标准 SSE 格式） -- **Header**：`x-vercel-ai-ui-message-stream: v1` -- **终止**：`data: [DONE]\n\n` -- **理由**：一处封装，所有节点统一调用；前端 useChat 自动解析 - -## 开源项目对比参考 - -### Vercel AI SDK 5.0 (标准参考) - -- **架构**：Provider → Core → Framework 三层 -- **协议**：Data Stream Protocol (SSE `data: {"type":"..."}`) -- **状态**：`useChat` hook 管理 messages, status, error -- **Transport**：可替换 `DefaultChatTransport`，支持自定义后端 -- **亮点**：`data-*` 自定义 Part、reconnect、abort、tool-call 标准化 - -### LibreChat (可靠性参考) - -- **Resumable Streams**：断线后客户端透明恢复，服务端从当前位置继续 -- **部署模式**：单实例用 Node EventEmitter pub/sub，多实例用 Redis Streams -- **文本动画**：动态速度调整（10→16 字符/ms），队列越长越快 -- **亮点**：断点续传对学术写作场景（长响应）极其重要 - -### Open WebUI (管道参考) - -- **Pipeline**：Inlet → Process → Outlet 三阶段 -- **Filter**：可插拔的 filter 链（监控、修改、阻断、翻译、限流） -- **异步模式**：耗时操作（web search 30-60s+）立即返回 task_id，WebSocket 推送进度 -- **亮点**：Pipeline 可扩展性强，适合学术场景（搜索→去重→全文获取→OCR 可能非常耗时） - - -## 技术可行性验证 - -### AI SDK 5.0 + FastAPI 后端 ✅ - -**结论**：可行，但需手动输出 Data Stream Protocol SSE 格式。 - -**验证来源**：[vercel/ai#7496](https://github.com/vercel/ai/issues/7496) + 社区 working example - -**后端输出格式**（已验证可工作）： - -```python -import json, uuid - -async def event_stream(): - message_id = f"msg_{uuid.uuid4().hex}" - yield f'data: {json.dumps({"type": "start", "messageId": message_id})}\n\n' - - text_id = f"text_{uuid.uuid4().hex}" - yield f'data: {json.dumps({"type": "text-start", "id": text_id})}\n\n' - for chunk in chunks: - yield f'data: {json.dumps({"type": "text-delta", "id": text_id, "delta": chunk})}\n\n' - yield f'data: {json.dumps({"type": "text-end", "id": text_id})}\n\n' - - # 自定义 data Part（citation 等） - yield f'data: {json.dumps({"type": "data-citation", "data": citation_obj})}\n\n' - - yield f'data: {json.dumps({"type": "finish"})}\n\n' - yield 'data: [DONE]\n\n' -``` - -**关键要求**： -- Response Header 必须包含 `x-vercel-ai-ui-message-stream: v1` -- 每行格式 `data: {JSON}\n\n`（标准 SSE） -- 流结束 `data: [DONE]\n\n` -- 无官方 Python SDK helper，需自行封装 `StreamWriter` 工具类 - -**参考实现**：[Pydantic AI 的 Vercel AI SDK 协议实现](https://ai.pydantic.dev/ui/vercel-ai/) - -### LangGraph `get_stream_writer()` ✅ - -**结论**：完美支持从节点内部实时发射自定义事件。 - -**验证来源**：[LangGraph 官方文档](https://reference.langchain.com/python/langgraph/config/get_stream_writer) + 社区实践 - -```python -from langgraph.config import get_stream_writer - -def retrieve_node(state: ChatState) -> ChatState: - writer = get_stream_writer() - writer({"type": "data-thinking", "data": {"step": "retrieve", "status": "running"}}) - - results = rag_service.query(state["query"], state["kb_ids"]) - - writer({"type": "data-thinking", "data": {"step": "retrieve", "status": "done"}}) - return {**state, "rag_results": results} -``` - -**关键要求**： -- Python 3.11+（ContextVar 异步传播需要） -- `stream_mode=["updates", "custom"]` -- `get_stream_writer()` 在节点函数体内调用 -- 对于 `generate` 节点的 `text_delta` 流式输出，需要在 LLM streaming 循环内调用 `writer()` - -**LangGraph custom stream → Data Stream Protocol 桥接**： - -```python -async for chunk in graph.astream(input_state, stream_mode=["updates", "custom"]): - if chunk[0] == "custom": # custom event from get_stream_writer() - yield f'data: {json.dumps(chunk[1])}\n\n' -``` - -### 前端 `data-*` Part 消费方式 ✅ - -AI SDK 5.0 的 `UIMessage.parts` 数组包含所有 Part（含自定义 `data-*`），前端通过 `parts.filter()` 访问： - -```tsx -// 在 MessageBubble 中 -{message.parts.map((part, i) => { - switch (part.type) { - case 'text': - return ; - case 'data-citation': - return ; - case 'data-thinking': - return ; - } -})} -``` - -### Conversation 恢复对接 - -`useChat` 支持 `initialMessages` 和 `chatId` 参数： - -```tsx -const { messages, sendMessage, status } = useChat({ - chatId: conversationId, // 对应 /chat/:conversationId - initialMessages: restoredMessages, // 从 DB 恢复的历史消息 - transport: new DefaultChatTransport({ api: '/api/v1/chat/stream' }), -}); -``` - -路由恢复时，通过 `conversationApi.get(id)` 加载历史消息并转换为 `UIMessage[]` 格式传入 `initialMessages`。 - -## 未陈述的假设 - -1. AI SDK 5.0 已进入 stable（当前最新为 beta，但核心 API 已稳定且有大量生产使用） -2. Python 3.12 满足 LangGraph `get_stream_writer()` 的 ContextVar 要求（需 ≥ 3.11） -3. `data-*` Part 的 `data` 字段可以是任意 JSON 可序列化对象（已由协议规范确认） -4. Resumable Streams 作为**增强特性**在核心重构完成后实施，不阻塞主体工作 - -## Resolved Questions - -1. **AI SDK 5.0 + FastAPI 是否可行？** → ✅ 可行，需手动格式化 SSE，社区有 working example 和 Pydantic AI 参考实现 -2. **LangGraph 节点能否实时流式输出 SSE？** → ✅ 可以，`get_stream_writer()` + `stream_mode="custom"` -3. **`data-*` 自定义 Part 前端怎么消费？** → 通过 `message.parts` 数组的 `type` 字段过滤 -4. **对话恢复如何对接 useChat？** → `initialMessages` + `chatId` 参数 - -## 下一步 - -→ `/ce:plan` 生成详细实施计划，全面重写前后端消息处理链路 diff --git a/docs/brainstorms/2026-03-12-chat-message-routing-chain-spec-flow-analysis.md b/docs/brainstorms/2026-03-12-chat-message-routing-chain-spec-flow-analysis.md deleted file mode 100644 index 66f30b10..00000000 --- a/docs/brainstorms/2026-03-12-chat-message-routing-chain-spec-flow-analysis.md +++ /dev/null @@ -1,276 +0,0 @@ -# Chat Message Routing Chain — Spec Flow Analysis - -**Date**: 2026-03-12 -**Source**: `docs/brainstorms/2026-03-12-chat-message-routing-chain-brainstorm.md` -**Analyzer**: spec-flow-analyzer - ---- - -## User Flow Overview - -### Flow 1: Happy Path — New Chat with RAG (knowledge_base_ids present) - -```mermaid -flowchart TD - A[User enters message + selects KBs] --> B[handleSend / sendMessage] - B --> C[POST /api/v1/chat/stream] - C --> D[understand node] - D --> E[retrieve node] - E --> F[rank node] - F --> G[clean node] - G --> H[generate node] - H --> I[persist node] - I --> J[complete node] - J --> K[Stream ends with DONE] - K --> L[useChat updates messages] - L --> M[Navigate to /chat/:id] -``` - -User sends message → backend runs full pipeline (understand → retrieve → rank → clean → generate → persist → complete) → SSE stream emits `start`, `text-start`, `text-delta`, `text-end`, `data-citation`, `data-thinking`, `data-citation-enhanced`, `finish`, `[DONE]` → frontend `useChat` parses and updates `messages` → user sees streaming response with citations and thinking steps → URL updates to `/chat/:conversationId`. - -### Flow 2: Happy Path — New Chat without RAG (no knowledge_base_ids) - -```mermaid -flowchart TD - A[User enters message, no KBs] --> B[sendMessage] - B --> C[POST /api/v1/chat/stream] - C --> D[understand node] - D --> E[Conditional: skip retrieve/rank/clean] - E --> F[generate node] - F --> G[persist node] - G --> H[complete node] - H --> I[Stream ends] -``` - -Same as Flow 1 but `retrieve`, `rank`, `clean` nodes are skipped. No `data-citation` or `data-citation-enhanced` events. - -### Flow 3: Continue Existing Conversation - -User navigates to `/chat/:conversationId` or sends a message in an existing conversation. Backend loads `history_messages` from DB (last 10), prepends to prompt. Same pipeline as Flow 1 or 2 depending on `knowledge_base_ids`. `conversation_id` in request prevents creating new conversation. - -### Flow 4: Conversation Restore (Page Load / Direct URL) - -User opens `/chat/123` directly. Frontend: -1. `routeConvId` from URL → `conversationApi.get(123)` -2. Load conversation + messages -3. Convert `ChatMessage[]` → `UIMessage[]` (or `initialMessages` format) -4. Pass to `useChat({ chatId: '123', initialMessages: restored })` -5. Render restored messages; user can continue chatting - -### Flow 5: User Aborts Stream (Stop Button) - -User clicks Stop during streaming. `useChat.stop()` → AbortController aborts fetch → backend receives cancellation → stream terminates. Frontend shows partial response, no error. - -### Flow 6: Error During Stream (Backend Exception) - -Backend node throws (e.g., LLM timeout, RAG failure). Backend catches, emits `error` Part `{"type":"error","errorText":"..."}`. Frontend `useChat` sets `error` state. User sees error UI (toast or inline). Spec says "useChat error state automatically handles" — exact UX (retry button, inline message, toast) not specified. - -### Flow 7: Network Failure / Connection Drop - -Fetch fails or stream breaks mid-response. No `[DONE]` received. Spec defers "Resumable Streams" to Phase 2. Current behavior: stream hangs or throws; user gets generic error. No reconnect logic in Phase 1. - -### Flow 8: Empty / Invalid Input - -User submits empty message or whitespace-only. Backend `ChatStreamRequest.message` has `min_length=1`. Frontend: ChatInput may or may not prevent submit. If submitted, backend returns 422. `useChat` error handling for non-2xx not specified. - ---- - -## Flow Permutations Matrix - -| Flow | User State | Context | knowledge_base_ids | Expected Behavior | -|------|------------|---------|--------------------|-------------------| -| 1 | Any | New chat | Non-empty | Full RAG pipeline, citations, thinking | -| 2 | Any | New chat | Empty/undefined | Direct LLM, no citations | -| 3 | Any | Existing conv | From conv or override | History loaded, same pipeline | -| 4 | Any | Direct URL | From conv | Restore messages, ready to continue | -| 5 | Any | Streaming | Any | Abort, partial response | -| 6 | Any | Any | Any | Error Part, useChat error | -| 7 | Any | Any | Any | No reconnect (Phase 1) | -| 8 | Any | Submit | N/A | Validation error | - -**Additional dimensions not fully specified:** -- **Tool mode** (qa, citation_lookup, review_outline, gap_analysis): Affects system prompt; no flow-specific behavior change in spec -- **Model override** (`request.model`): Passed but not described in pipeline -- **First-time vs returning user**: Same flows; restore is Flow 4 -- **Concurrent actions**: User sends message while another streams — race condition; spec does not address - ---- - -## Missing Elements & Gaps - -### Category: Error Handling - -| Gap | Description | Impact | Current Ambiguity | -|-----|-------------|--------|-------------------| -| **E-1** | `error` Part schema not defined | Frontend cannot reliably parse error | Is it `{"type":"error","errorText":"..."}` or `{"type":"error","code":"...","message":"..."}`? Current backend uses `{"code":"stream_error","message":"..."}`. | -| **E-2** | Partial failure in RAG (one KB fails) | User gets incomplete citations or full failure? | Current `_stream_chat` uses `return_exceptions=True` and continues; spec does not say if LangGraph nodes should do same. | -| **E-3** | LLM timeout / rate limit | No specific handling | Current `_clean_excerpt` has 10s timeout; main `chat_stream` has none. What timeout for generate node? | -| **E-4** | DB failure in persist node | Conversation/messages not saved | Should stream still complete with `finish`? Or emit `error`? User may see response but refresh loses it. | -| **E-5** | Non-2xx HTTP (422, 500) before stream starts | `useChat` behavior | Does `useChat` surface `response.ok === false` as `error`? Or does fetch throw? | -| **E-6** | Malformed SSE (invalid JSON in data) | Parser behavior | Current `streamChat` yields `{ raw: currentData }` on parse error. Data Stream Protocol: does useChat handle malformed lines? | - -### Category: Protocol & Integration - -| Gap | Description | Impact | Current Ambiguity | -|-----|-------------|--------|-------------------| -| **P-1** | Current backend uses `event: X\ndata: Y`; Data Stream Protocol uses `data: {"type":"X",...}` only | Breaking change | No `event:` line in new format. All info in JSON. Frontend must not expect `event:` prefix. | -| **P-2** | `text_delta` → `text-start` + `text-delta` + `text-end` mapping | Delta format change | Current: `{"delta":"x"}`. New: `{"type":"text-delta","id":"text_xxx","delta":"x"}`. Need `id` for correlation. | -| **P-3** | `message_start` → `start` with `messageId` | Field name change | Current: `message_id`. New: `messageId` (camelCase). | -| **P-4** | `message_end` → `finish` with `conversation_id` | Where does conversation_id go? | Data Stream Protocol `finish` may not include custom fields. Spec says backend yields `finish` — need to confirm `conversation_id` is in same Part or separate `data-*` Part. | -| **P-5** | Header `x-vercel-ai-ui-message-stream: v1` | Required for useChat | Backend must add this. Current backend does not send it. | -| **P-6** | `[DONE]` vs `data: [DONE]` | Termination format | Spec says `data: [DONE]\n\n`. Confirm exact string. | - -### Category: Frontend State & UX - -| Gap | Description | Impact | Current Ambiguity | -|-----|-------------|--------|-------------------| -| **F-1** | `LocalMessage` → `UIMessage` + `parts` migration | MessageBubble, ChatInput, etc. | MessageBubble expects `content`, `citations`, `thinkingSteps`, `a2uiMessages` as props. UIMessage has `parts`. Need adapter: `parts.filter(p => p.type === 'text')` → content, `parts.filter(p => p.type === 'data-citation')` → citations. | -| **F-2** | `loadingStage` derivation | MessageBubble uses `loadingStage` for UI | Current: 'searching' | 'citations' | 'generating' | 'complete'. UIMessage has no such field. Derive from `data-thinking` parts? Or add custom Part? | -| **F-3** | `initialMessages` format | Conversation restore | `ChatMessage[]` from API has `id`, `role`, `content`, `citations`. UIMessage has `id`, `role`, `parts`. Conversion logic not specified. | -| **F-4** | `chatId` type | useChat expects string? | Route has `conversationId` as number. useChat `chatId` may need string. | -| **F-5** | Tool mode, selectedKBs in useChat | useChat sends body | Need to pass `knowledge_base_ids`, `tool_mode`, `conversation_id` in request body. useChat's `body` or `sendMessage` options? | -| **F-6** | Navigation after stream end | Current: `navigate(/chat/${cid})` on message_end | useChat does not know conversation_id. Need `onFinish` or similar to get `conversation_id` from stream and navigate. | -| **F-7** | 80ms debounce removal | Current: manual debounce for text_delta | useChat handles streaming internally. No debounce needed. But does useChat batch updates? May affect perceived performance. | - -### Category: Backend Pipeline - -| Gap | Description | Impact | Current Ambiguity | -|-----|-------------|--------|-------------------| -| **B-1** | ChatState TypedDict | New state for chat graph | PipelineState exists for search/upload. Chat pipeline needs different state: `request`, `llm`, `rag`, `citations`, `messages`, etc. Not defined. | -| **B-2** | DB session / request context | Nodes need db | Current `_stream_chat` receives `db: AsyncSession`. LangGraph nodes receive `state`. How does `persist` node get db? Inject via config or context? | -| **B-3** | `get_stream_writer()` in async generator | LangGraph streams to caller | `graph.astream(..., stream_mode=["updates","custom"])` yields chunks. Caller (FastAPI endpoint) must consume and re-emit as SSE. Bridge code shown in spec but not full request lifecycle. | -| **B-4** | LLM streaming inside generate node | `writer()` in loop | `async for token in llm.chat_stream(...)`: call `writer({"type":"text-delta",...})` each token. Confirmed in spec. | -| **B-5** | Conditional edge: skip retrieve when no KB | Graph structure | `add_conditional_edges("understand", _route, {"retrieve": "retrieve", "generate": "generate"})`. Need `_route(state)` returning next node. | -| **B-6** | Conversation creation timing | New conv vs existing | Current: create conv before persist if `not conversation_id`. persist node must create conv + messages. | -| **B-7** | RAG `return_exceptions` | One KB fails | Keep current behavior (continue with partial results) or fail entire pipeline? | - -### Category: Backward Compatibility & Migration - -| Gap | Description | Impact | Current Ambiguity | -|-----|-------------|--------|-------------------| -| **M-1** | Rewrite API (`/api/v1/chat/rewrite`) | Uses same SSE format | `rewrite-api.ts` uses `event:` + `data:` format. Not migrated in spec. Stays on old format or migrate too? | -| **M-2** | RAG streaming (`/api/v1/rag/...`) | Another SSE endpoint | `rag.py` has `_sse()`. Out of scope? | -| **M-3** | Index pipeline SSE | `api.ts` IndexSSEEvent | Different event types. Unaffected. | -| **M-4** | E2E / tests | test_chat.py asserts `event: message_start` | Backend format change breaks tests. Must update to Data Stream Protocol assertions. | -| **M-5** | Feature flags / gradual rollout | None | Big bang migration. No way to run old and new in parallel. | - -### Category: Testing - -| Gap | Description | Impact | Current Ambiguity | -|-----|-------------|--------|-------------------| -| **T-1** | Backend: LangGraph node unit tests | Each node testable | No plan for mocking `get_stream_writer()`, db, RAG. | -| **T-2** | Backend: Stream format tests | Assert correct SSE | test_chat.py checks `event: message_start`. Need tests for `data: {"type":"start",...}`, `[DONE]`, etc. | -| **T-3** | Frontend: useChat integration | Mock fetch, assert state | No tests for PlaygroundPage today. Adding useChat: how to mock transport? | -| **T-4** | E2E: Full flow | Playwright | Current e2e fixtures use mock SSE. Need real backend or new mock format. | -| **T-5** | Error path tests | 500, timeout, abort | No tests for error Part, abort behavior. | - -### Category: Security & Validation - -| Gap | Description | Impact | Current Ambiguity | -|-----|-------------|--------|-------------------| -| **S-1** | knowledge_base_ids authorization | User can only query own KBs | Current backend does not check. Spec does not mention. | -| **S-2** | conversation_id authorization | User can only continue own conv | Same. | -| **S-3** | Rate limiting | Stream endpoint | Long-running, no rate limit specified. | -| **S-4** | Input sanitization | Message content | Passed to LLM. XSS in citations? Rendered in Markdown. | - -### Category: Accessibility & i18n - -| Gap | Description | Impact | Current Ambiguity | -|-----|-------------|--------|-------------------| -| **A-1** | Error messages | useChat error | May be raw backend message. Need i18n? | -| **A-2** | Loading/streaming announcements | Screen readers | useChat status. Does it expose `status` for aria-live? | - ---- - -## Critical Questions Requiring Clarification - -### Critical (blocks implementation or creates risks) - -1. **Q1: `finish` Part and `conversation_id`** - - **Question**: Where does `conversation_id` go in the Data Stream Protocol? The standard `finish` Part may not include custom fields. Does useChat support a custom `data-conversation-id` Part, or do we extend the `finish` payload? - - **Why it matters**: Frontend needs `conversation_id` to navigate to `/chat/:id` and set `chatId` for subsequent messages. - - **Assumption if unanswered**: Emit a separate `data-conversation-id` Part immediately before `finish`, and handle it in a custom `onMessage` or stream callback. - - **Example**: `data: {"type":"data-conversation-id","conversationId":123}\n\n` then `data: {"type":"finish"}\n\n`. - -2. **Q2: `error` Part schema** - - **Question**: What is the exact JSON schema for the `error` Part that useChat expects? Is it `{"type":"error","errorText":"..."}` or does it support `code` and `message`? - - **Why it matters**: Backend currently sends `{"code":"stream_error","message":"..."}`. Mismatch may cause useChat to not display the error. - - **Assumption**: Use AI SDK's documented `error` Part format; adapt backend to match. - - **Example**: Check [AI SDK Data Stream Protocol](https://sdk.vercel.ai/docs/ai-sdk-ui/stream-protocol) for exact schema. - -3. **Q3: DB session injection into LangGraph** - - **Question**: How does the `persist` node (and any node needing DB) get the `AsyncSession`? Via `configurable` in `astream()`, or a context variable? - - **Why it matters**: LangGraph nodes are stateless; db is request-scoped. - - **Assumption**: Pass `{"db": db}` in `configurable` when calling `graph.astream()`, and have nodes read `state` or a separate context. - - **Example**: `await graph.astream(input_state, config={"configurable": {"db": db}})` - -4. **Q4: ChatState definition** - - **Question**: What fields does the Chat LangGraph state have? At minimum: `request`, `llm`, `rag`, `all_sources`, `all_contexts`, `citations`, `history_messages`, `messages`, `full_response`, `conversation_id`. - - **Why it matters**: Nodes read/write state. Undefined state blocks implementation. - - **Assumption**: Define `ChatState(TypedDict, total=False)` mirroring `_stream_chat` variables. - -### Important (significantly affects UX or maintainability) - -5. **Q5: MessageBubble migration strategy** - - **Question**: Should MessageBubble be refactored to accept `UIMessage` (or `parts`) directly, or should PlaygroundPage adapt `UIMessage` to the current props (`content`, `citations`, `thinkingSteps`, etc.)? - - **Why it matters**: Affects component reuse and testability. - - **Assumption**: Create adapter in PlaygroundPage: `messageToBubbleProps(message: UIMessage)` to avoid changing MessageBubble initially. - -6. **Q6: `initialMessages` conversion** - - **Question**: What is the exact mapping from `ChatMessage` (API) to `UIMessage`/`initialMessages`? `ChatMessage` has `content`, `citations`; UIMessage has `parts`. - - **Why it matters**: Conversation restore must show history correctly. - - **Assumption**: Build `parts`: `[{type:'text', text: m.content}, ...(m.citations?.map(c => ({type:'data-citation', data: c})) ?? [])]`. - -7. **Q7: RAG partial failure behavior** - - **Question**: When one of N knowledge bases fails (exception in `rag.query`), should the pipeline continue with results from the others, or fail entirely? - - **Why it matters**: Current behavior continues; spec does not state. - - **Assumption**: Continue (match current behavior). Emit `data-thinking` with status "partial" or "warning" if desired. - -8. **Q8: Persist node failure** - - **Question**: If DB commit fails in `persist`, should we emit `error` and not send `finish`, or send `finish` (user saw response) and log the failure? - - **Why it matters**: User may see response but lose it on refresh. - - **Assumption**: Emit `error` Part, do not send `finish`. User sees error; response not persisted. - -### Nice-to-have (improves clarity) - -9. **Q9: Rewrite API migration** - - **Question**: Is `/api/v1/chat/rewrite` in scope for this refactor, or does it stay on the old SSE format? - - **Assumption**: Out of scope; rewrite stays as-is. - -10. **Q10: Tool mode in useChat body** - - **Question**: How does useChat send `tool_mode`, `knowledge_base_ids`, `conversation_id`? Via `body` in transport options? - - **Assumption**: `DefaultChatTransport` or custom transport accepts `body` merge. Verify AI SDK 5.0 API. - ---- - -## Recommended Next Steps - -1. **Resolve Critical Questions (Q1–Q4)** - - Check AI SDK 5.0 Data Stream Protocol docs for `finish`, `error`, and custom `data-*` Parts. - - Define `ChatState` and db injection approach. - - Document in brainstorm or a short ADR. - -2. **Define Protocol Contract** - - Create a shared spec (or TypeScript + Python types) for: - - All Part types (`start`, `text-start`, `text-delta`, `text-end`, `finish`, `error`, `data-citation`, `data-thinking`, `data-citation-enhanced`, `data-a2ui`, `data-conversation-id`). - - Exact JSON schema for each. - - Use for backend StreamWriter and frontend parsing validation. - -3. **Draft Migration Plan** - - Phase 1a: Backend — implement StreamWriter, new endpoint (e.g. `/api/v1/chat/ai-stream`) that outputs Data Stream Protocol. Keep `/api/v1/chat/stream` for rollback. - - Phase 1b: Frontend — add useChat with transport pointing to new endpoint; feature-flag or route-based switch. - - Phase 1c: Migrate PlaygroundPage to useChat; adapter for MessageBubble props. - - Phase 1d: Remove old endpoint and streamChat; update tests. - -4. **Update Tests** - - Backend: `test_chat.py` — assert new SSE format (`data: {"type":"start"...}`, `[DONE]`), error Part, no `event:` lines. - - Backend: Add unit tests for each LangGraph node (mock writer, db, RAG). - - Frontend: Add integration test for useChat + mock transport. - -5. **Address Security Gaps (S-1, S-2)** - - Add auth checks: user can only access own `knowledge_base_ids` and `conversation_id`. - - Document in plan even if deferred. - -6. **Document Error Handling** - - Specify: error Part schema, partial RAG failure, persist failure, HTTP 4xx/5xx. - - Add to plan or brainstorm. diff --git a/docs/brainstorms/2026-03-12-codebase-quality-audit-brainstorm.md b/docs/brainstorms/2026-03-12-codebase-quality-audit-brainstorm.md deleted file mode 100644 index 801db16c..00000000 --- a/docs/brainstorms/2026-03-12-codebase-quality-audit-brainstorm.md +++ /dev/null @@ -1,284 +0,0 @@ ---- -date: 2026-03-12 -topic: codebase-quality-audit ---- - -# Omelette 前后端代码质量全面审计与改进计划 - -## 我们要构建什么 - -对 Omelette 前后端代码进行系统性质量提升，修复安全漏洞、改善错误处理、统一代码风格、建立前端测试体系。目标是将代码库从"功能可用"提升到"生产就绪"。 - -**核心改进领域：** -1. **安全加固** —— 修复路径遍历、默认密钥、跨项目访问等漏洞，加入简单 API Key 认证 -2. **稳定性提升** —— Error Boundary、toast 通知、异常处理规范化、N+1 查询优化 -3. **代码质量** —— DRY 原则、类型安全、API 一致性、组件拆分 -4. **测试体系** —— 建立 vitest + testing-library 前端测试基础设施，覆盖核心流程 - -## 为什么选择这个方案 - -### 考虑过的方案 - -| 方案 | 描述 | 取舍 | -|------|------|------| -| **A: 分批次系统修复（选中）** | 按严重程度分 4 批次，从严重 → 低逐步推进 | 可控、可追踪进度、每批独立可交付 | -| B: 按功能模块逐个重构 | 先重构 chat 模块，再 KB 模块，再 pipeline | 可能遗漏跨模块问题，安全漏洞修复延迟 | -| C: 只修严重问题，其他留后 | 只处理安全和崩溃级别问题 | 快速但债务积累，长期代价高 | - -**选择方案 A 的理由：** -- 安全漏洞需要立即修复，不能等到某个模块"轮到"时才处理 -- 分批次可以保证每个批次都有明确的 scope 和验证标准 -- 每批独立可交付，降低风险 - -## 关键决策 - -### 1. 认证方案：简单 API Key 保护 - -- **决策**：在后端加入可选的 API Key 认证中间件 -- **理由**：项目定位为本地/小团队部署，不需要完整用户系统。一个 API Key 足以防止未授权访问 -- **实现**：环境变量 `API_SECRET_KEY`，为空时跳过认证（开发模式兼容） - -### 2. 前端测试框架选型 - -- **决策**：Vitest + @testing-library/react + MSW (Mock Service Worker) -- **理由**：Vitest 与 Vite 生态天然集成，testing-library 鼓励面向行为的测试，MSW 拦截网络请求做集成测试 -- **覆盖目标**：核心流程 > 工具函数 > 组件渲染 - -### 3. Toast/通知系统选型 - -- **决策**：Sonner（shadcn/ui 推荐的 toast 组件） -- **理由**：与现有 shadcn/ui 生态一致，API 简洁，支持 promise toast - -### 4. 异常处理规范 - -- **决策**：建立统一的异常处理策略 -- **理由**：当前 10+ 处 `except Exception` 且行为不一致（有的吞错、有的返回字符串、有的重新抛出） -- **规范**： - - API 层：捕获特定异常，转为 HTTPException - - Service 层：让异常传播，不要吞错 - - Pipeline 节点：捕获后设置节点状态为 failed，记录到 state - -## 审计发现详情 - -### 后端问题清单（20 项） - -#### 严重（Critical） - -| # | 问题 | 位置 | 说明 | -|---|------|------|------| -| B1 | 路径遍历漏洞 | `api/v1/dedup.py:100-101, 179-180` | `conflict_id` 含用户输入的文件名，可用 `../../` 逃逸项目目录 | -| B2 | 默认密钥 | `config.py:24` | `app_secret_key` 默认值为明文字符串，生产环境不安全 | -| B3 | Writing API 无项目校验 | `api/v1/writing.py:59-154` | 所有 writing 端点不检查 project 是否存在 | - -#### 高（High） - -| # | 问题 | 位置 | 说明 | -|---|------|------|------| -| B4 | 异常吞错 | `services/rag_service.py:253-286` | `except Exception` 后返回错误字符串给用户，不传播 | -| B5 | N+1 查询（项目列表） | `api/v1/projects.py:29-45` | 每个项目执行 2 次额外查询（paper_count + keyword_count） | -| B6 | N+1 查询（对话列表） | `api/v1/conversations.py:45-71` | 每条对话执行 2 次额外查询 | -| B7 | MCP 资源 ID 未校验 | `mcp_server.py:393, 426, 458` | `int(kb_id)` 对非数字输入抛 ValueError，导致 500 | -| B8 | Paper 跨项目访问 | `api/v1/projects.py:144-151` | `run_paper_pipeline` 不验证 paper 是否属于该项目 | - -#### 中（Medium） - -| # | 问题 | 位置 | 说明 | -|---|------|------|------| -| B9 | `_ensure_project` 复制粘贴 | 9 个 API 模块 | 相同辅助函数重复定义 9 次 | -| B10 | update_project 响应不一致 | `api/v1/projects.py:111-121` | 不返回 paper_count/keyword_count | -| B11 | 根端点格式不一致 | `main.py:61-68` | 返回 dict 而非 ApiResponse | -| B12 | f-string 日志 | `keyword_service.py:72`, `crawler_service.py:39` | 应使用 `%s` 延迟格式化 | -| B13 | Pipeline 静默异常 | `api/v1/pipelines.py:196-197` | `except Exception: pass` | -| B14 | 硬编码数据目录 | `config.py:31` | `/data0/djx/omelette` 用户特定路径 | -| B15 | `Any` 返回类型 | `services/rag_service.py:72` | `_get_vector_store` 返回 `Any` | - -#### 低（Low） - -| # | 问题 | 位置 | 说明 | -|---|------|------|------| -| B16 | 可收窄的异常捕获 | 多处 service/pipeline 节点 | 可用更具体的异常类型 | -| B17 | 缺失类型注解 | `keyword_service.py:119-141` | `list` 应为 `list[str]` | -| B18 | MCP 逻辑 bug | `mcp_server.py:291-292` | `if summary_type == "abstract" or summary_type != "llm"` 始终为真 | -| B19 | Unpaywall 默认邮箱 | `crawler_service.py:74` | 使用 `test@example.com` 作为 fallback | -| B20 | Mypy continue-on-error | `ci.yml` | CI 中 mypy 错误不阻断构建 | - -### 前端问题清单（36 项） - -#### 严重（Critical） - -| # | 问题 | 位置 | 说明 | -|---|------|------|------| -| F1 | 无 Error Boundary | `App.tsx` | 任何组件异常会导致整个应用白屏 | -| F2 | Axios 拦截器混淆 | `lib/api.ts:14-15` | 拦截器返回 `response.data`，调用方又用 `res?.data`，导致双层解包 | -| F3 | `response.body!` 非空断言 | `services/api.ts:79` | ReadableStream body 可能为 null | -| F4 | 未使用的 Zustand store | `stores/projectStore.ts` | 从未被导入，应该删除 | - -#### 高（High） - -| # | 问题 | 位置 | 说明 | -|---|------|------|------| -| F5 | Prop drilling `t` | `SubscriptionManager.tsx:354, 361` | 应在子组件内调用 `useTranslation()` | -| F6 | 不安全类型断言 | `PlaygroundPage.tsx:88` | `as unknown as Citation` 双重断言 | -| F7 | API 响应无类型 | `services/api.ts` 全部 | 方法返回 untyped axios 响应 | -| F8 | fetch/axios 混用 | `api.ts:75`, `chat-api.ts:33` | 流式端点用 fetch，其他用 axios，错误处理不一致 | -| F9 | Mutation 无 `onError` | 多个页面 | 操作失败时用户无感知 | -| F10 | 无 toast/通知系统 | 全局 | CRUD 操作无成功/失败反馈 | -| F11 | i18n key 缺失 | `SearchAddDialog.tsx:37-39` | `stepQuery/stepResults/stepSelect` 不存在于 locale 文件 | -| F12 | i18n key 缺失 | `SearchAddDialog.tsx:179, 190` | `keywords` 和 `sources` 不在 locale 中 | -| F13 | `confirm()` 不可访问 | 4 个删除操作 | 应替换为 Radix AlertDialog | - -#### 中（Medium） - -| # | 问题 | 位置 | 说明 | -|---|------|------|------| -| F14 | 大组件 | `SubscriptionManager.tsx` (461行) | 应拆分子组件 | -| F15 | 无 memoization | `PlaygroundPage.tsx:242-257` | MessageBubble 每次流式更新全部重渲染 | -| F16 | 无代码分割 | `App.tsx` | 所有路由组件同步加载 | -| F17 | KB picker 无加载状态 | `PlaygroundPage.tsx:164-188` | 加载时显示"无知识库" | -| F18 | 硬编码中文冒号 | `SettingsPage.tsx:69-70` | `：` 应国际化 | -| F19-21 | 硬编码文本 | `SearchAddDialog`, `KeywordsPage`, `WritingPage` | 数据源名/数据库名/引用格式应国际化 | -| F22-23 | index 做 key | `RAGChatPage.tsx`, `SearchAddDialog.tsx` | 应使用稳定 ID | -| F24 | subscription API 无类型 | `subscription-api.ts` | 返回 untyped | -| F25 | 重复类型断言 | `DedupConflictPanel.tsx:137, 170, 175` | 应扩展类型定义 | - -#### 低（Low） - -| # | 问题 | 位置 | 说明 | -|---|------|------|------| -| F26 | 硬编码状态颜色 | 多处 | 应使用主题 token | -| F27 | 缺失 aria-label | 图标按钮 | 无障碍问题 | -| F28 | KB picker 无 Escape 关闭 | `PlaygroundPage.tsx` | 应使用 Popover 组件 | -| F29 | ChatInput 抢焦点 | `ChatInput.tsx:24-26` | `isLoading` 变化时无条件 focus | -| F30 | 变量遮蔽 `t` | `KeywordsPage.tsx:63` | forEach 参数遮蔽 useTranslation 的 t | -| F31 | 不必要的类型强转 | `SubscriptionManager.tsx:323` | t 函数本身支持 options | -| F32 | 依赖数组问题 | `RAGChatPage.tsx:103` | `indexProgress.active` 在 deps 中不稳定 | -| F33 | 重复 API 调用 | `PdfUploadDialog.tsx:118` | 直接用 `api.post` 而非封装好的 API | -| F34 | 无 barrel exports | `components/knowledge-base/` | 缺少 index.ts | -| F35 | 硬编码 locale | `ChatHistoryPage.tsx:45` | `'zh-CN'` 应随 i18n 语言设置 | -| F36 | 无前端测试 | 全局 | 零测试覆盖 | - -## 分批次实施计划 - -### Batch 1：安全与稳定性（严重级别修复） - -**范围**：B1-B3, B7-B8, F1-F4 + 简单 API Key 认证 - -**后端（7 项）：** -- [ ] 修复路径遍历：验证 `conflict_id` 文件名，禁止 `..` 和路径分隔符 -- [ ] 移除默认密钥：生产环境强制要求配置 `APP_SECRET_KEY` -- [ ] Writing API 添加项目存在性校验 -- [ ] MCP 资源 ID 输入校验（try/except ValueError） -- [ ] Paper pipeline 添加项目归属校验 -- [ ] 修复 MCP `get_paper_summary` 逻辑 bug（B18，虽为低优先级但修复成本极低） -- [ ] 实现简单 API Key 中间件（`API_SECRET_KEY` 环境变量，为空时跳过） - -**前端（4 项）：** -- [ ] 添加全局 Error Boundary + 友好的 fallback UI -- [ ] 修复 axios 拦截器返回值，统一 API 响应解包方式 -- [ ] `response.body` 添加 null 检查 -- [ ] 删除未使用的 Zustand projectStore - -**验证标准**：安全漏洞修复有对应测试；Error Boundary 可捕获子组件错误 - ---- - -### Batch 2：错误处理与用户体验（高级别修复） - -**范围**：B4-B6, F5-F13 - -**后端（3 项）：** -- [ ] 重构 `rag_service` 异常处理：不吞错，让异常传播到 API 层 -- [ ] 优化项目列表 N+1 查询：使用子查询或 CTE 一次查询 -- [ ] 优化对话列表 N+1 查询：预加载消息计数和最后一条消息 - -**前端（10 项）：** -- [ ] 引入 Sonner toast 系统，封装全局通知 -- [ ] 所有 mutation 添加 `onError` + toast 错误提示 -- [ ] 替换 `confirm()` 为 Radix AlertDialog -- [ ] 修复 SearchAddDialog 缺失的 i18n key -- [ ] 修复 SubscriptionManager prop drilling（子组件自行调用 `useTranslation`） -- [ ] 修复 PlaygroundPage 不安全类型断言（添加 runtime 校验或 type guard） -- [ ] API 服务添加类型化返回值 `Promise>` -- [ ] **迁移聊天流式到 Vercel AI SDK** —— 引入 `@ai-sdk/react` 的 `useChat`，替换 `chat-api.ts` 自定义 SSE 逻辑 -- [ ] 修复 axios 拦截器解包逻辑，统一 API 响应处理 -- [ ] KB picker 添加加载状态 - -**验证标准**：所有 CRUD 操作有 toast 反馈；i18n 双语无缺失 key - ---- - -### Batch 3：代码质量与一致性（中级别修复） - -**范围**：B9-B15, F14-F25 - -**后端（7 项）：** -- [ ] `_ensure_project` 抽取到 `api/deps.py`，作为 `Depends` 注入 -- [ ] `update_project` 响应补全 paper_count/keyword_count -- [ ] 根端点改为 ApiResponse 格式 -- [ ] 修复 f-string 日志为 `%s` 风格 -- [ ] Pipeline 静默异常改为 warning 日志 -- [ ] 硬编码数据目录改为环境变量 + 通用默认值 -- [ ] `_get_vector_store` 返回具体类型 - -**前端（12 项）：** -- [ ] SubscriptionManager 拆分子组件（< 200 行/组件） -- [ ] MessageBubble 添加 React.memo -- [ ] App.tsx 路由组件改为 React.lazy + Suspense -- [ ] 列表 key 从 index 改为稳定 ID -- [ ] 硬编码数据源名/数据库名/引用格式国际化 -- [ ] 硬编码中文冒号修复 -- [ ] subscription-api.ts 添加类型 -- [ ] DedupConflictPanel 类型断言改为类型扩展 -- [ ] PdfUploadDialog 使用封装好的 kbApi -- [ ] SearchAddDialog 拆分（389 行 → 步骤子组件） -- [ ] SettingsPage 拆分（372 行 → provider 子组件） -- [ ] RAGChatPage startRebuild 依赖数组修复 - -**验证标准**：无大于 200 行的单文件组件；`rg "except Exception" | wc -l` 减半 - ---- - -### Batch 4：测试体系与打磨（低级别 + 测试） - -**范围**：B16-B20, F26-F36 + 前端测试基础设施 - -**前端测试基础设施：** -- [ ] 配置 Vitest + @testing-library/react + MSW -- [ ] 创建测试工具文件（renderWithProviders, mock i18n, mock API） -- [ ] 添加 CI 集成（`npm test` 步骤） - -**核心流程测试（优先级排序）：** -- [ ] `streamChat` —— SSE 流式解析逻辑 -- [ ] `ChatInput` —— 提交、Enter、禁用状态 -- [ ] `MessageBubble` —— 用户/助手消息渲染、引用展示 -- [ ] API 客户端 —— 请求/响应/错误处理 -- [ ] `PlaygroundPage` —— 消息流转、KB 选择 -- [ ] `SubscriptionManager` —— CRUD 和表单状态 -- [ ] `DedupConflictPanel` —— 冲突解决流程 - -**后端改进：** -- [ ] 收窄异常捕获类型（httpx.HTTPError, pdfplumber.PDFSyntaxError 等） -- [ ] 补全缺失类型注解（list → list[str]） -- [ ] Unpaywall 默认邮箱移至配置 -- [ ] Mypy 改为阻断 CI（需先修复现有错误） - -**前端打磨：** -- [ ] 图标按钮添加 aria-label -- [ ] KB picker 改为 Popover（支持 Escape 关闭） -- [ ] ChatInput focus 逻辑优化（仅在提交后 focus） -- [ ] 修复变量遮蔽和不必要类型强转 -- [ ] 添加 barrel exports -- [ ] `formatDate` locale 随 i18n 语言设置 -- [ ] 状态颜色改用主题 token - -**验证标准**：前端测试覆盖率 > 60%（核心模块）；CI 通过率 100% - -## 已解决的问题 - -1. **Vercel AI SDK 替换自定义 fetch** —— **决定在 Batch 2 中迁移**。引入 `@ai-sdk/react` 的 `useChat`，与错误处理改进一起做。需要调整后端 SSE 格式以兼容 AI SDK 的协议。 -2. **API 响应格式** —— **保持 `ApiResponse` 包装**，修复前端 axios 拦截器的解包逻辑，确保调用方一致使用 `res.data` 获取业务数据。 -3. **Mypy 严格模式** —— **渐进式推进**，每个 batch 修复涉及文件的 mypy 错误，最终在所有 batch 完成后开启严格模式。 - -## 下一步 - -→ 确认方向后，执行 `/ce:plan` 逐批次生成详细实施计划并开始编码 diff --git a/docs/brainstorms/2026-03-12-comprehensive-ui-polish-brainstorm.md b/docs/brainstorms/2026-03-12-comprehensive-ui-polish-brainstorm.md deleted file mode 100644 index a393af1f..00000000 --- a/docs/brainstorms/2026-03-12-comprehensive-ui-polish-brainstorm.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -date: 2026-03-12 -topic: comprehensive-ui-polish ---- - -# Omelette 综合性 UI 打磨 - -## 我们要构建什么 - -基于对应用所有页面的可视化截图审查，对 Omelette 前端进行全面打磨，覆盖 **视觉一致性、交互流畅性、功能补全、响应式适配** 四个维度。目标是让应用达到 Perplexity 级别的专业感——搜索+对话融合、引用卡片突出、信息密度适中。 - -最终效果：截图可直接放产品介绍页，所有交互有动画反馈，所有页面风格统一，桌面/平板/手机均可用。 - -## 为什么选择这个方案 - -### 考虑过的方案 - -| 方案 | 描述 | 取舍 | -|------|------|------| -| **A: 按技术层分阶段（选中）** | 基础设施 → 一致性 → 功能增强 | 依赖清晰，代码复用好，但阶段 1 用户可见变化小 | -| B: 按用户感知分阶段 | 首页体验 → 全局打磨 → 深度功能 | 成果感强但可能返工 | -| C: 按页面分阶段 | 逐页完整打磨 | 简单但共享组件可能重复开发 | - -**选择方案 A 的理由：** -- 骨架屏、页面过渡、响应式断点等基础设施是所有页面共享的，先做避免后续改 -- 一致性修复是收益最高的投入——统一标题区域、空状态、动画模式即可大幅提升整体感 -- 功能增强（输入框、Settings、暗色模式）是锦上添花，放最后不阻塞其他工作 - -## 可视化审查发现 - -### 已有的好设计 -- 左侧图标侧边栏已有 Tooltip -- Framer Motion 已安装并在 3 个页面使用 -- 共享 EmptyState 组件已存在 -- 暗色模式基本可用 -- shadcn/ui 组件库已有 17 个组件 - -### 需要改进的问题 - -| 页面 | 问题 | -|------|------| -| **Playground** | 快捷模板卡片太小无图标、输入框功能单一、欢迎区视觉重心偏上 | -| **Tasks** | 与其他页面设计语言不一致（无副标题、无页面描述） | -| **Settings** | 无动态表单（Mock 模式不应显示 Test Connection）、缺 API Key 配置 | -| **暗色模式** | 卡片边框不可见、输入框区分度不够、品牌色偏暗淡 | -| **全局** | 无骨架屏（只有 spinner）、无页面过渡动画、空状态不统一、未做响应式适配 | - -## 关键决策 - -### 1. 设计参考：Perplexity 风格 -- **决策**：以 Perplexity 为视觉参考，而非 ChatGPT 或 Notion -- **理由**：Perplexity 的"搜索+对话+引用"模式与 Omelette 的科研文献场景高度匹配 -- **影响**：快捷模板卡片需更突出、引用相关的视觉元素需加强 - -### 2. 分阶段策略：基础设施 → 一致性 → 功能增强 -- **阶段 1 - 基础设施层**：Skeleton 组件、页面过渡动画框架、响应式断点系统、Framer Motion 工具函数 -- **阶段 2 - 页面一致性层**：统一标题区域/空状态/加载状态、Tasks 页面修复、Framer Motion 扩展到所有页面 -- **阶段 3 - 功能增强层**：Playground 输入框/卡片升级、Settings 动态表单、暗色模式优化、响应式适配 - -### 3. 响应式设计：完全响应式 -- **决策**：手机/平板/桌面三端均完全可用 -- **断点**：移动端隐藏侧边栏改为底部导航或汉堡菜单，平板横屏使用折叠侧边栏 - -### 4. 骨架屏替代 Spinner -- **决策**：新增 Skeleton 组件，所有数据加载用骨架屏而非 Loader2 spinner -- **理由**：骨架屏减少感知加载时间，更专业 - -### 5. 页面过渡动画方案 -- **决策**：使用 Framer Motion AnimatePresence + 路由级包裹 -- **方式**：淡入淡出（fade）为主，避免滑动（slide）以保持轻量感 - -## 详细改进清单 - -### 阶段 1：基础设施层 - -#### 1.1 新增 Skeleton 组件 -- 安装 shadcn/ui skeleton 组件 -- 创建常用骨架模式：CardSkeleton、ListSkeleton、PageHeaderSkeleton -- 用于 Knowledge Bases、Chat History、Tasks 等列表页 - -#### 1.2 页面过渡动画框架 -- 在 App.tsx 的路由层包裹 AnimatePresence -- 创建 PageTransition 包裹组件（fade + 微滑入） -- 所有页面统一使用 - -#### 1.3 响应式断点系统 -- 定义断点：`sm: 640px`、`md: 768px`、`lg: 1024px`、`xl: 1280px` -- 创建 useMediaQuery hook -- 侧边栏响应式：桌面固定、平板折叠、手机隐藏 -- 移动端导航方案（底部 tab 或汉堡菜单） - -#### 1.4 Framer Motion 工具函数 -- 统一动画变体（fadeIn、slideUp、staggerChildren） -- 创建 MotionList、MotionCard 等封装组件 -- 统一 duration、easing 参数 - -### 阶段 2：页面一致性层 - -#### 2.1 统一页面标题区域 -- 所有页面采用统一的 PageHeader 组件：标题 + 副标题 + 可选操作按钮 -- 修复 Tasks 页面（加副标题和描述） - -#### 2.2 统一空状态 -- 所有页面使用 EmptyState 组件（KnowledgeBasesPage 的自定义空状态改为使用统一组件） -- EmptyState 增强：支持 action 按钮的变体（primary/outline） - -#### 2.3 统一加载状态 -- 将所有 LoadingState（spinner）替换为 Skeleton 骨架屏 -- 保留 spinner 仅用于按钮内 loading 和提交操作 - -#### 2.4 Framer Motion 扩展 -- 将 motion 动画从 3 个页面扩展到所有 8 个页面 -- 列表页：stagger 入场动画 -- 卡片页：hover scale + shadow 过渡 - -### 阶段 3：功能增强层 - -#### 3.1 Playground 快捷模板升级 -- 卡片增大，加入独特图标和淡色背景 -- 每个模板卡片有自己的品牌色（Search=蓝、Citation=绿、Outline=紫、Gap=红） -- hover 效果增强 - -#### 3.2 Playground 输入框增强 -- 知识库选择 chip 显示在输入框内/上方 -- 模型选择下拉 -- 附件上传按钮（PDF 拖拽） -- 工具模式入口整合（移到输入框上方或内部） - -#### 3.3 Settings 动态表单 -- 根据 Provider 类型动态显示/隐藏配置字段 -- API Key 输入框（密码类型，可切换显示） -- 未保存变更提示（Save 按钮状态变化） - -#### 3.4 暗色模式优化 -- 卡片边框可见性：`border-border/30` → `border-border/50` -- 输入框区分度：用略浅的 `bg-muted/30` 背景 -- 品牌色提亮：暗色模式下 amber-500 → amber-400 -- 快捷模板卡片 hover 效果增强 - -#### 3.5 响应式适配实施 -- 侧边栏：移动端底部导航 + 汉堡菜单 -- Playground：输入框全宽、快捷模板单列 -- Knowledge Bases：卡片网格 3→2→1 列 -- Settings：表单单列堆叠 -- Chat History：搜索框全宽、列表紧凑 - -## 技术约束 - -- **不引入新依赖**：仅用已有的 shadcn/ui + Framer Motion + TailwindCSS v4 -- **渐进增强**：每个阶段独立可用，不破坏现有功能 -- **i18n**：所有新增文案必须走 `useTranslation()` -- **可访问性**：保持 Radix UI 的 ARIA 属性，新增组件遵循 WAI-ARIA 规范 - -## 已解决的问题 - -1. **移动端侧边栏方案** → **混合方案**：底部 Tab 放主要导航（Chat、Knowledge Bases、History、Tasks），汉堡菜单放次要功能（Settings、主题切换、语言切换） -2. **页面过渡动画性能** → **支持 `prefers-reduced-motion` 降级**：尊重用户系统设置，运动障碍用户自动禁用动画 -3. **Settings API Key 存储** → **两种方式都支持**：前端可配置 API Key（存后端数据库），也可通过 .env 配置，前端配置优先级高于 .env - -## 下一步 - -→ 确认方向后，执行 `/ce:plan` 生成详细实施计划并开始编码 diff --git a/docs/brainstorms/2026-03-12-frontend-ux-robustness-brainstorm.md b/docs/brainstorms/2026-03-12-frontend-ux-robustness-brainstorm.md deleted file mode 100644 index 02b4e934..00000000 --- a/docs/brainstorms/2026-03-12-frontend-ux-robustness-brainstorm.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -date: 2026-03-12 -topic: frontend-ux-robustness -depends_on: - - 2026-03-11-ux-architecture-upgrade-brainstorm.md - - 2026-03-12-codebase-quality-audit-brainstorm.md ---- - -# 前端用户体验与健壮性全面提升 - -## 我们要构建什么 - -对 Omelette 前端进行系统性的用户体验优化和健壮性加固，重点是： - -1. **健壮性基础设施** —— 统一错误处理、加载状态、toast 通知、类型安全 -2. **核心流程加固** —— 聊天、论文添加、知识库管理等关键路径的断点修复和容错 -3. **全层级测试体系** —— 单元测试 + 集成测试 + E2E 测试金字塔 -4. **用户体验优化** —— 导航简化、交互一致性、空状态引导、操作反馈 - -## 为什么选择这个方案 - -### 考虑过的方案 - -| 方案 | 描述 | 取舍 | -|------|------|------| -| **A: 由内而外加固（选中）** | 先修地基（错误处理、类型、测试），再优化上层交互 | 每步有测试保护，不引入新 bug；用户感知改善较晚 | -| B: 由外而内重构 | 先改 UX 流程让用户感知到改善，再加固底层 | 快速可见的改善，但重构期间缺少测试保护 | -| C: 纵向切片 | 按功能模块（聊天/知识库/设置）逐个做到位 | 每个模块做完即高质量，但全局基础设施推迟 | - -**选择方案 A 的理由：** -- 项目定位为个人科研助手，稳定性比外观更重要 -- 目前测试几乎为零（仅 3 个测试文件），任何重构都有引入回归的风险 -- 先建立测试基础设施，后续所有改进都有安全网 -- 允许大胆重构，不需要向后兼容，追求最终效果 - -## 关键决策 - -### 1. 优化策略：先健壮后体验 - -- **决策**：分 3 阶段——基础设施 → 核心流程加固 → UX 提升 -- **理由**：健壮性是体验的地基，没有可靠的错误处理和反馈，再好的 UI 也会让用户焦虑 - -### 2. 测试策略：全层级金字塔 - -- **决策**：Vitest（单元/集成）+ Playwright（E2E），建立完整测试金字塔 -- **理由**： - - 单元测试：快速覆盖工具函数、hooks、纯组件 - - 集成测试：Testing Library + MSW 测试页面级交互 - - E2E 测试：Playwright 覆盖关键用户旅程（聊天、添加论文、去重） -- **覆盖目标**：核心流程 > 60%，关键组件 > 50%，工具函数 > 70% - -### 3. 可以大胆重构 - -- **决策**：不需要向后兼容，中间状态可以接受 -- **影响**：可以做结构性调整（合并页面、重组组件、重写 API 层） - -## 现状问题全景图 - -### 一、交互反馈体系（最基础，影响所有流程） - -| # | 问题 | 严重度 | 位置 | -|---|------|--------|------| -| UX-1 | 无全局 toast 系统 | 高 | 全局 —— CRUD 操作无成功/失败反馈 | -| UX-2 | 加载状态不一致 | 高 | 部分用 `t('common.loading')` 文字，部分用 `Loader2` spinner，部分无加载态 | -| UX-3 | 空状态无引导 | 中 | ChatHistory 空列表无 CTA，知识库列表空时无新建引导 | -| UX-4 | Error Boundary 硬编码英文 | 中 | `ErrorBoundary.tsx` fallback 文本未国际化 | -| UX-5 | `confirm()` 原生弹窗 | 中 | 4 个删除操作使用浏览器原生 confirm，不可访问且风格不一致 | -| UX-6 | 设置保存无反馈 | 中 | SettingsPage 保存成功仅图标变化，无 toast | -| UX-7 | 订阅管理缺 onError | 中 | SubscriptionManager 的 create/update/delete mutation 无错误提示 | - -### 二、聊天流程（最高频功能） - -| # | 问题 | 严重度 | 位置 | -|---|------|--------|------| -| UX-8 | Playground 和 RAG Chat 割裂 | 高 | 两个独立聊天界面，用户困惑该用哪个 | -| UX-9 | 对话历史不可恢复 | 高 | ChatHistoryPage 列表不可点击恢复上下文 | -| UX-10 | SSE 断流无重试 | 高 | `response.body!` 非空断言，流中断直接崩溃 | -| UX-11 | MessageBubble 无 memo | 中 | 每次流式更新所有消息重渲染 | -| UX-12 | KB picker 加载态缺失 | 中 | 知识库列表加载中显示"无知识库" | -| UX-13 | ChatInput 抢焦点 | 低 | `isLoading` 变化时无条件 focus | - -### 三、知识库导航（结构性问题） - -| # | 问题 | 严重度 | 位置 | -|---|------|--------|------| -| UX-14 | 7 个子页面层级深 | 中 | 论文/关键词/搜索/RAG/写作/任务/订阅，用户容易迷路 | -| UX-15 | Project 404 无明确提示 | 中 | projectId 无效时仅显示文字"not found" | -| UX-16 | RAG MarkdownBlock 简陋 | 低 | 简单 line-split，Playground 用 ReactMarkdown | - -### 四、论文添加流程（核心工作流） - -| # | 问题 | 严重度 | 位置 | -|---|------|--------|------| -| UX-17 | 添加论文入口分散 | 中 | 搜索添加、PDF 上传、订阅在不同位置 | -| UX-18 | SearchAddDialog i18n 缺失 | 中 | stepQuery/stepResults/stepSelect 等 key 不存在 | -| UX-19 | 去重冲突面板类型不安全 | 中 | 3 处 `as` 类型断言 | -| UX-20 | TasksPage 暗色模式适配 | 低 | 状态颜色硬编码 light-only | - -### 五、代码层面问题（影响维护和测试） - -| # | 问题 | 严重度 | 位置 | -|---|------|--------|------| -| UX-21 | Axios 拦截器双层解包 | 严重 | `lib/api.ts` 拦截器返回 `response.data`，调用方又取 `.data` | -| UX-22 | API 响应无类型 | 高 | `services/api.ts` 方法返回 untyped | -| UX-23 | fetch/axios 混用 | 高 | 流式端点 fetch，其他 axios，错误处理不一致 | -| UX-24 | 不安全类型断言 | 中 | `as unknown as Citation` 双重断言 | -| UX-25 | 大组件未拆分 | 中 | SubscriptionManager 461行, SearchAddDialog 389行, SettingsPage 372行 | -| UX-26 | 无代码分割 | 中 | App.tsx 所有路由同步加载 | -| UX-27 | index 做 list key | 低 | RAGChatPage, SearchAddDialog | -| UX-28 | 变量遮蔽 | 低 | KeywordsPage 的 `t` 被 forEach 参数遮蔽 | - -### 六、测试现状 - -| 维度 | 现状 | -|------|------| -| 测试文件 | 3 个：`KnowledgeBasesPage.test.tsx`, `ChatInput.test.tsx`, `api.test.ts` | -| 测试框架 | Vitest + jsdom + MSW + Testing Library（已配置） | -| E2E 测试 | 无 | -| 覆盖率 | < 5%，核心流程（聊天、论文添加、去重）零覆盖 | -| CI 集成 | GitHub Actions 中有 `npm test` 步骤 | -| 测试工具 | `renderWithProviders` 已有，MSW handlers 仅覆盖项目列表 | - -## 分阶段实施计划 - -### 阶段 1：健壮性基础设施（地基） - -**目标：** 建立统一的错误处理、反馈、类型安全和测试基础设施 - -**1.1 全局反馈系统** -- 引入 Sonner toast（已在 package.json，需要集成到 App 层） -- 封装 `useToastMutation` hook：自动 onSuccess/onError toast -- 所有现有 mutation 迁移到 toast 反馈 - -**1.2 统一错误处理** -- Error Boundary i18n 化 + 友好 fallback UI -- 修复 Axios 拦截器双层解包 bug（UX-21） -- API 服务层泛型化：`Promise>` -- `response.body` null 检查（UX-10） - -**1.3 统一加载状态** -- 创建共享 `` 组件（spinner + 文案） -- 创建 `` 组件（图标 + 文案 + CTA 按钮） -- 替换所有分散的加载和空状态实现 - -**1.4 测试基础设施扩展** -- 扩展 MSW handlers 覆盖所有 API 端点 -- 添加常用测试 fixtures（project, paper, conversation, settings） -- 配置 Playwright（安装、配置文件、基础 page objects、双模式：CI Mock + 本地真实后端） -- 添加覆盖率报告（vitest coverage） - -**1.5 代码分割** -- App.tsx 路由组件 React.lazy + Suspense -- Suspense fallback 使用新的 `` - -**验证标准：** -- 任何 CRUD 操作都有 toast 反馈 -- 任何组件异常不会白屏 -- API 调用有类型安全的响应 -- 测试可以跑通且有覆盖率报告 - ---- - -### 阶段 2：核心流程加固 + 测试 - -**目标：** 聊天和论文添加两大核心流程做到可靠、可测试 - -**2.1 聊天流程统一** -- 合并 Playground 和 RAG Chat 为统一聊天入口 - - Playground 选择知识库后即为 RAG 模式 - - 不选知识库即为通用问答模式 -- 路由设计：`/` 新对话，`/chat/:conversationId` 恢复历史对话 -- 迁移到 Vercel AI SDK（`@ai-sdk/react` 的 `useChat`），替换自定义 SSE -- 对话历史可恢复（ChatHistoryPage 列表可点击跳转到 `/chat/:id`） -- MessageBubble 添加 React.memo + 性能优化 -- KB picker 加载状态修复 -- 流式容错：AI SDK 内置断流重试和错误恢复 -- RAG MarkdownBlock 迁移到 ReactMarkdown - -**2.2 论文添加流程整合** -- 统一论文添加入口（搜索/上传/订阅合并为一个 Dialog 的三个 Tab） -- SearchAddDialog 拆分为步骤子组件（< 200 行/组件） -- 修复 i18n 缺失 key -- 去重冲突面板类型安全修复 - -**2.3 核心流程测试** -- 单元测试： - - `streamChat` SSE 解析逻辑 - - `ChatInput` 提交/禁用/快捷键 - - `MessageBubble` 用户/助手/引用渲染 - - API 客户端请求/响应/错误 -- 集成测试： - - PlaygroundPage 完整消息流转 - - KnowledgeBasesPage CRUD - - PapersPage 添加论文流程 - - DedupConflictPanel 冲突解决 -- E2E 测试： - - 用户旅程：新建知识库 → 添加论文 → 聊天提问 → 查看引用 - - 用户旅程：恢复历史对话 → 继续提问 - -**验证标准：** -- 聊天功能有单一入口，不再困惑 -- 对话可恢复 -- SSE 断流不会崩溃 -- 论文添加流程在一个 Dialog 完成 -- 核心流程测试覆盖率 > 60% - ---- - -### 阶段 3：UX 体验提升 - -**目标：** 交互一致性、导航优化、视觉打磨 - -**3.1 组件风格统一** -- 所有 raw `/ - - - {providers.map(p => {p})} - - - - - -// API Key - - -// 连接测试 - -``` - ---- - -## 8. Provider 配置变量速查表 - -| 提供商 | 集成方式 | 配置变量 | -|--------|----------|----------| -| OpenAI | `ChatOpenAI` | OPENAI_API_KEY, OPENAI_MODEL | -| Anthropic | `ChatAnthropic` | ANTHROPIC_API_KEY, ANTHROPIC_MODEL | -| 阿里云百炼 | `ChatOpenAI(base_url=dashscope)` | ALIYUN_API_KEY, ALIYUN_MODEL | -| 火山引擎 | `ChatOpenAI(base_url=volcengine)` | VOLCENGINE_API_KEY, VOLCENGINE_MODEL | -| 本地 Ollama | `ChatOllama` | OLLAMA_BASE_URL, OLLAMA_MODEL | -| Mock | 内置 Mock | LLM_PROVIDER=mock | - ---- - -## 9. 附录：依赖变更 - -```toml -# pyproject.toml 新增 -dependencies = [ - "langchain-core>=0.3", - "langchain-openai>=0.3", - "langchain-anthropic>=0.3", - "langchain-community>=0.3", # ChatOllama - # ... 现有依赖 -] -``` diff --git a/docs/plans/2026-03-12-feat-batch4-testing-polish-plan.md b/docs/plans/2026-03-12-feat-batch4-testing-polish-plan.md deleted file mode 100644 index 07f61860..00000000 --- a/docs/plans/2026-03-12-feat-batch4-testing-polish-plan.md +++ /dev/null @@ -1,384 +0,0 @@ ---- -title: "Batch 4: 测试体系与打磨" -type: feat -status: active -date: 2026-03-12 -origin: docs/brainstorms/2026-03-12-codebase-quality-audit-brainstorm.md ---- - -# Batch 4：测试体系与打磨 - -## Overview - -建立前端测试基础设施（Vitest + @testing-library/react + MSW），覆盖核心流程测试，并完成剩余的低优先级修复（无障碍、主题 token、barrel exports 等）。此批次的目标是建立可持续的质量保障机制。 - -## Problem Statement - -1. **前端零测试覆盖**：任何重构都无法验证正确性，UI 回归只能靠人工 -2. **后端 mypy 不严格**：类型错误不阻断 CI -3. **小但累积的 UX 问题**：缺 aria-label、焦点管理不当、颜色不统一 - -## Proposed Solution - -### Phase 1：前端测试基础设施 - -#### 1. 安装测试依赖 - -```bash -cd frontend -npm install -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom msw -``` - -#### 2. Vitest 配置 — `frontend/vitest.config.ts` - -```typescript -// frontend/vitest.config.ts -import { defineConfig } from 'vitest/config' -import react from '@vitejs/plugin-react' -import path from 'path' - -export default defineConfig({ - plugins: [react()], - test: { - globals: true, - environment: 'jsdom', - setupFiles: ['./src/test/setup.ts'], - include: ['src/**/*.{test,spec}.{ts,tsx}'], - coverage: { - provider: 'v8', - reporter: ['text', 'lcov'], - include: ['src/**/*.{ts,tsx}'], - exclude: ['src/test/**', 'src/**/*.d.ts'], - }, - }, - resolve: { - alias: { '@': path.resolve(__dirname, './src') }, - }, -}) -``` - -#### 3. 测试工具 — `frontend/src/test/setup.ts` - -```typescript -// frontend/src/test/setup.ts -import '@testing-library/jest-dom' -import { cleanup } from '@testing-library/react' -import { afterEach } from 'vitest' - -afterEach(() => cleanup()) -``` - -#### 4. 测试辅助 — `frontend/src/test/utils.tsx` - -```tsx -// frontend/src/test/utils.tsx -import { render, type RenderOptions } from '@testing-library/react' -import { QueryClient, QueryClientProvider } from '@tanstack/react-query' -import { BrowserRouter } from 'react-router-dom' -import { I18nextProvider } from 'react-i18next' -import i18n from '@/i18n' - -function createTestQueryClient() { - return new QueryClient({ - defaultOptions: { queries: { retry: false }, mutations: { retry: false } }, - }) -} - -export function renderWithProviders(ui: React.ReactElement, options?: RenderOptions) { - const queryClient = createTestQueryClient() - return render( - - - {ui} - - , - options, - ) -} - -export { render, screen, waitFor, within } from '@testing-library/react' -export { default as userEvent } from '@testing-library/user-event' -``` - -#### 5. MSW Mock 服务器 — `frontend/src/test/mocks/` - -```typescript -// frontend/src/test/mocks/handlers.ts -import { http, HttpResponse } from 'msw' - -export const handlers = [ - http.get('/api/v1/projects', () => - HttpResponse.json({ - code: 200, - message: 'ok', - data: { items: [{ id: 1, name: 'Test KB', description: '' }], total: 1 }, - timestamp: new Date().toISOString(), - }), - ), - // ... 其他 mock -] - -// frontend/src/test/mocks/server.ts -import { setupServer } from 'msw/node' -import { handlers } from './handlers' - -export const server = setupServer(...handlers) -``` - -#### 6. CI 集成 — `.github/workflows/ci.yml` - -在 `frontend-lint-build` job 中添加： - -```yaml -- name: Run frontend tests - run: npx vitest run --coverage - working-directory: frontend -``` - -### Phase 2：核心流程测试 - -#### 7. streamChat 测试 — `frontend/src/services/__tests__/chat-api.test.ts` - -测试 SSE 解析逻辑（如果仍保留自定义 fetch）或 useChat hook 集成。 - -```typescript -describe('streamChat', () => { - it('should parse text_delta events', async () => { ... }) - it('should parse citation events', async () => { ... }) - it('should handle error events', async () => { ... }) - it('should handle network errors', async () => { ... }) -}) -``` - -#### 8. ChatInput 测试 — `frontend/src/components/playground/__tests__/ChatInput.test.tsx` - -```typescript -describe('ChatInput', () => { - it('should submit on Enter', async () => { ... }) - it('should not submit when empty', async () => { ... }) - it('should be disabled when isLoading', async () => { ... }) - it('should support Shift+Enter for newline', async () => { ... }) -}) -``` - -#### 9. MessageBubble 测试 — `frontend/src/components/playground/__tests__/MessageBubble.test.tsx` - -```typescript -describe('MessageBubble', () => { - it('should render user message', () => { ... }) - it('should render assistant message with markdown', () => { ... }) - it('should render citations', () => { ... }) - it('should render math formulas', () => { ... }) -}) -``` - -#### 10. API 客户端测试 — `frontend/src/services/__tests__/api.test.ts` - -```typescript -describe('projectApi', () => { - it('should fetch project list', async () => { ... }) - it('should handle 404 errors', async () => { ... }) - it('should handle network errors', async () => { ... }) -}) -``` - -#### 11. PlaygroundPage 测试 — `frontend/src/pages/__tests__/PlaygroundPage.test.tsx` - -```typescript -describe('PlaygroundPage', () => { - it('should render welcome state', () => { ... }) - it('should show KB picker', async () => { ... }) - it('should send message and display response', async () => { ... }) -}) -``` - -#### 12. SubscriptionManager 测试 — 测试 CRUD 和表单验证 - -#### 13. DedupConflictPanel 测试 — 测试冲突解决流程 - -### Phase 3：后端改进 - -#### 14. 收窄异常捕获类型 - -**影响文件**： - -| 文件 | 当前 | 修改为 | -|------|------|--------| -| `crawler_service.py:38` | `except Exception` | `except (httpx.HTTPError, httpx.TimeoutException)` | -| `pipelines/nodes.py:224` | `except Exception` | `except (httpx.HTTPError, IOError)` | -| `pipelines/nodes.py:284` | `except Exception` | `except (subprocess.SubprocessError, FileNotFoundError, pdfplumber.PDFSyntaxError)` | -| `pipelines/nodes.py:339` | `except Exception` | `except (ValueError, RuntimeError)` | -| `ocr_service.py:41` | `except Exception` | `except (pdfplumber.PDFSyntaxError, FileNotFoundError)` | -| `ocr_service.py:113` | `except Exception` | `except (RuntimeError, ImportError)` | -| `pdf_metadata.py:54` | `except Exception` | `except (pdfplumber.PDFSyntaxError, KeyError, ValueError)` | -| `settings_api.py:55` | `except Exception` | `except (httpx.HTTPError, ValueError, KeyError)` | -| `dedup.py:235` | `except Exception` | `except (httpx.HTTPError, ValueError)` | - -每处修改后使用 `logger.exception` 记录完整 traceback。 - -#### 15. 补全类型注解 — `backend/app/services/keyword_service.py` - -```python -# 修改前 -def _build_wos_formula(self, core: list, sub: list, expanded: list) -> str: -# 修改后 -def _build_wos_formula(self, core: list[str], sub: list[str], expanded: list[str]) -> str: -``` - -全局搜索 `-> list:` 或 `(.*: list,` 修复类似问题。 - -#### 16. Unpaywall 邮箱配置化 — `backend/app/config.py` - -```python -# config.py -unpaywall_email: str = "" - -# crawler_service.py:74 -if not settings.unpaywall_email: - raise ValueError("UNPAYWALL_EMAIL must be configured for PDF downloads") -email = settings.unpaywall_email -``` - -#### 17. Mypy 渐进式开启 - -- 修复所有 batch 中涉及文件的 mypy 错误 -- CI 中移除 `continue-on-error: true` -- 如有遗留错误，使用 `# type: ignore[specific-error]` 标注 - -### Phase 4：前端打磨 - -#### 18. 图标按钮 aria-label - -**影响文件**：`PapersPage.tsx`, `ChatHistoryPage.tsx`, `KnowledgeBasesPage.tsx` - -```tsx -// 示例 - -``` - -#### 19. KB picker 改为 Popover - -```tsx -// frontend/src/pages/PlaygroundPage.tsx -import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover' - - - - - - - {/* KB 列表 */} - - -``` - -#### 20. ChatInput focus 优化 - -```tsx -// frontend/src/components/playground/ChatInput.tsx -const prevLoadingRef = useRef(isLoading) - -useEffect(() => { - if (prevLoadingRef.current && !isLoading) { - textareaRef.current?.focus() - } - prevLoadingRef.current = isLoading -}, [isLoading]) -``` - -#### 21. 变量遮蔽修复 — `KeywordsPage.tsx` - -```typescript -// 修改前 -terms.forEach((t: ...) => { -// 修改后 -terms.forEach((termItem: ...) => { -``` - -#### 22. 不必要类型强转 — `SubscriptionManager.tsx` - -```typescript -// 修改前 -(t as (key: string, opts?: Record) => string)('subscriptions.totalFound', { count: sub.total_found }) -// 修改后 -t('subscriptions.totalFound', { count: sub.total_found }) -``` - -#### 23. Barrel exports — `frontend/src/components/knowledge-base/index.ts` - -```typescript -// frontend/src/components/knowledge-base/index.ts -export { DedupConflictPanel } from './DedupConflictPanel' -export { PdfUploadDialog } from './PdfUploadDialog' -export { SearchAddDialog } from './SearchAddDialog' -// ... -``` - -#### 24. formatDate locale — `ChatHistoryPage.tsx` - -```typescript -// 修改前 -return d.toLocaleDateString('zh-CN') -// 修改后 -import { useTranslation } from 'react-i18next' -const { i18n } = useTranslation() -return d.toLocaleDateString(i18n.language === 'zh' ? 'zh-CN' : 'en-US') -``` - -#### 25. 状态颜色主题化 - -在 `frontend/src/index.css` 中添加语义颜色变量： - -```css -@theme { - --color-status-success: var(--color-green-500); - --color-status-warning: var(--color-yellow-500); - --color-status-error: var(--color-red-500); - --color-status-info: var(--color-blue-500); -} -``` - -将硬编码颜色替换为：`bg-status-success/10 text-status-success`。 - -## Acceptance Criteria - -### 测试 -- [ ] `vitest run` 通过且无失败用例 -- [ ] 核心流程测试覆盖率 > 60% -- [ ] CI 集成前端测试步骤 -- [ ] MSW mock 覆盖主要 API 端点 - -### 后端 -- [ ] `except Exception` 数量减少到仅 transaction 和 optional feature 场景 -- [ ] `mypy backend/app/ --strict` 错误数 < 20（从 continue-on-error 到可接受范围） -- [ ] Unpaywall 邮箱不再有 fallback 默认值 - -### 前端 -- [ ] 所有图标按钮有 aria-label -- [ ] KB picker 可用 Escape 关闭 -- [ ] 焦点不被意外抢夺 -- [ ] 无 TypeScript 编译警告 -- [ ] 状态颜色使用主题 token -- [ ] `npm run build` 输出无 chunk 超过 500KB（代码分割生效） - -## Technical Considerations - -- MSW v2 使用 ES modules，需确保 Vitest 配置兼容 -- 前端测试需要 mock i18n 和 react-query provider -- Mypy strict 模式可能产生大量错误，需评估是否分文件启用 - -## Dependencies & Risks - -- **新增依赖（dev）**：`vitest`, `@testing-library/react`, `@testing-library/jest-dom`, `@testing-library/user-event`, `jsdom`, `msw` -- **风险**：测试编写耗时可能超预期 —— 优先核心流程，其他渐进补充 -- **前置**：Batch 1 + 2 + 3 完成 - -## Sources - -- **Origin brainstorm**: [docs/brainstorms/2026-03-12-codebase-quality-audit-brainstorm.md](../brainstorms/2026-03-12-codebase-quality-audit-brainstorm.md) -- Issues: B16-B20, F26-F36 from brainstorm -- Vitest docs: https://vitest.dev/ -- Testing Library docs: https://testing-library.com/docs/react-testing-library/intro -- MSW docs: https://mswjs.io/docs diff --git a/docs/plans/2026-03-12-feat-chat-message-routing-chain-rewrite-plan.md b/docs/plans/2026-03-12-feat-chat-message-routing-chain-rewrite-plan.md deleted file mode 100644 index 0b68b74a..00000000 --- a/docs/plans/2026-03-12-feat-chat-message-routing-chain-rewrite-plan.md +++ /dev/null @@ -1,1068 +0,0 @@ ---- -title: "feat: Rewrite chat message routing chain" -type: feat -status: completed -date: 2026-03-12 -origin: docs/brainstorms/2026-03-12-chat-message-routing-chain-brainstorm.md ---- - -# feat: 聊天消息路由链全面重写 - -## Enhancement Summary - -**Deepened on:** 2026-03-12 -**Sections enhanced:** 6 (ChatState, Citation 策略, 前端类型, 错误处理, 性能, 架构) -**Research agents used:** Python Reviewer, TypeScript Reviewer, Performance Oracle, Architecture Strategist, AI SDK Context7 Docs - -### Key Improvements - -1. **Citation 协调模式改进**：用 AI SDK `id`-based 协调替代分离的 `data-citation-enhanced` 事件——同一 `data-citation` 类型 + 相同 `id` 可直接更新已有 Part，更简洁 -2. **ChatState 类型加强**：引入 `CitationDict` 和 `ChatMessageDict` TypedDicts 替代 `dict[str, Any]` -3. **前端防抖**：`useChat` 每 token 触发 re-render，需添加 `useDeferredValue` 或自定义防抖（P0 性能问题） -4. **UIMessage 泛型**：使用 `useChat()` 获得类型安全的自定义 Part 访问 - -### New Considerations Discovered - -- AI SDK 5.0 `data-*` Part 支持 `id` 字段进行 reconciliation（同 id 的新 Part 更新旧 Part） -- AI SDK 5.0 支持 `transient: true` 标记（thinking steps 可设为 transient，不保存到消息历史） -- `useChat` 的 `onData` 回调可处理所有 data Part（含 transient 的） -- LangGraph overhead 极低（~0.5-2ms/token），不需要 checkpointer -- 当前 Paper 查询已经是批量的（不是 N+1），需保持该模式 - -## Overview - -对 Omelette 的聊天消息处理链路进行全面重写：前端从手工 SSE 解析 + 15 个 useState 迁移到 Vercel AI SDK 5.0 `useChat`；后端从 230+ 行的 `_stream_chat` 单体函数迁移到 LangGraph StateGraph 可编排节点管道。同时建立标准化的 Data Stream Protocol 通信协议，统一错误处理和消息模型。 - -## Problem Statement - -当前聊天消息处理链路存在 11 个已识别问题（见 brainstorm R-1 至 R-11），核心矛盾是： -- 前端手写 SSE 解析器无法利用生态工具、不处理 error 事件、断流无重试 -- PlaygroundPage ~15 个 useState/useRef 导致状态逻辑与 UI 高度耦合 -- 后端 `_stream_chat` 单体函数步骤间耦合，难以独立测试/复用/扩展 - -## Proposed Solution - -三层重构： -1. **协议层**：Vercel AI SDK 5.0 Data Stream Protocol（标准化 SSE 格式） -2. **前端层**：`useChat` hook 替代手动状态管理，`UIMessage` + `parts` 替代 `LocalMessage` -3. **后端层**：LangGraph StateGraph 编排 7 个节点，`get_stream_writer()` 发射标准 SSE 事件 - -（见 brainstorm: `docs/brainstorms/2026-03-12-chat-message-routing-chain-brainstorm.md`） - -## Technical Approach - -### Architecture - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ 前端 (React) │ -│ │ -│ useChat({ transport, chatId, initialMessages }) │ -│ ├─ messages: UIMessage[] (parts: text | data-citation | ...) │ -│ ├─ status: 'ready' | 'submitted' | 'streaming' | 'error' │ -│ ├─ sendMessage() │ -│ └─ stop() │ -│ │ -│ Components: │ -│ PlaygroundPage → MessageBubble → [TextPart, CitationCard, │ -│ ThinkingChain, A2UISurface] │ -└────────────────────────┬──────────────────────────────────────────┘ - │ POST /api/v1/chat/stream - │ Header: x-vercel-ai-ui-message-stream: v1 - │ SSE: data: {"type":"text-delta","id":"...","delta":"..."}\n\n - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ 后端 (FastAPI) │ -│ │ -│ POST /api/v1/chat/stream │ -│ → StreamingResponse(chat_graph_stream(request, db)) │ -│ │ -│ LangGraph StateGraph: │ -│ [understand] → [retrieve] → [rank] → [clean] → [generate] │ -│ ↓ (无KB) → [persist] → [end] │ -│ [generate] → [persist] → [end] │ -│ │ -│ 每个节点通过 get_stream_writer() 发射 Data Stream Protocol 事件 │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### Data Stream Protocol 事件映射 - -| 阶段 | 事件类型 | Payload | 发射节点 | -|------|---------|---------|---------| -| 开始 | `start` | `{"type":"start","messageId":"msg_xxx"}` | endpoint | -| 思考 | `data-thinking` | `{"type":"data-thinking","data":{"step":"understand","status":"running","detail":"..."}}` | 各节点 | -| 引用 | `data-citation` | `{"type":"data-citation","id":"cit-0","data":{"index":0,"title":"...","excerpt":"原始摘要"}}` | rank | -| 引用更新 | `data-citation` (同 id) | `{"type":"data-citation","id":"cit-0","data":{"index":0,"title":"...","excerpt":"清洗后摘要"}}` | clean | -| 文本开始 | `text-start` | `{"type":"text-start","id":"text_xxx"}` | generate | -| 文本增量 | `text-delta` | `{"type":"text-delta","id":"text_xxx","delta":"..."}` | generate | -| 文本结束 | `text-end` | `{"type":"text-end","id":"text_xxx"}` | generate | -| 会话ID | `data-conversation` | `{"type":"data-conversation","data":{"conversation_id":123}}` | persist | -| 结束 | `finish` | `{"type":"finish"}` | endpoint | -| 终止 | `[DONE]` | `data: [DONE]` | endpoint | -| 错误 | `error` | `{"type":"error","errorText":"..."}` | 任意节点 | - -### ChatState 定义 - -```python -# backend/app/pipelines/chat/state.py -from typing import Any, Literal, TypedDict - -class CitationDict(TypedDict, total=False): - """强类型 citation，与前端 Citation interface 对齐。""" - index: int - paper_id: int | None - paper_title: str - chunk_type: str - page_number: int | None - relevance_score: float - excerpt: str - authors: list[str] | None - year: int | None - doi: str | None - -class ChatMessageDict(TypedDict): - """LLM 消息格式。""" - role: Literal["system", "user", "assistant"] - content: str - -class ChatState(TypedDict, total=False): - """LangGraph chat pipeline state.""" - - # --- 输入 (from request) --- - message: str - knowledge_base_ids: list[int] - tool_mode: str - conversation_id: int | None - - # --- 服务注入 (通过 config["configurable"]，不在 state 中) --- - # config["configurable"]["db"]: AsyncSession - # config["configurable"]["llm"]: LLMClient (由 understand_node 注入) - # config["configurable"]["rag"]: RAGService (由 understand_node 注入) - - # --- 中间结果 --- - rag_results: list[dict[str, Any]] # RAG 内部格式，保持松散 - citations: list[CitationDict] - history_messages: list[ChatMessageDict] - system_prompt: str - full_messages: list[ChatMessageDict] - - # --- 输出 --- - assistant_content: str - new_conversation_id: int | None - error: str | None -``` - -**服务注入约定**（`config["configurable"]` 契约）： - -```python -# backend/app/pipelines/chat/config_helpers.py -from langchain_core.runnables import RunnableConfig - -def get_chat_db(config: RunnableConfig): - return config["configurable"]["db"] - -def get_chat_llm(config: RunnableConfig): - return config["configurable"]["llm"] - -def get_chat_rag(config: RunnableConfig): - return config["configurable"]["rag"] -``` - -- `understand_node` 创建 `llm` 和 `rag` 并注入 `config["configurable"]` -- 后续节点通过 `get_chat_llm(config)` 等辅助函数访问 -- `db` 在端点调用时注入，全生命周期有效 - -### 服务注入模式 - -LangGraph 节点通过 `config["configurable"]` 访问请求级服务（DB session、LLM、RAG）： - -```python -# backend/app/pipelines/chat/nodes.py - -from langchain_core.runnables import RunnableConfig - -async def understand_node(state: ChatState, config: RunnableConfig) -> dict: - db = config["configurable"]["db"] - svc = UserSettingsService(db) - llm_config = await svc.get_merged_llm_config() - llm = get_llm_client(config=llm_config) - embed = get_embedding_model() if llm_config.provider != "mock" else MockEmbedding(embed_dim=128) - rag = RAGService(llm=llm, embed_model=embed) - - # 注入到 configurable 供后续节点使用 - config["configurable"]["llm"] = llm - config["configurable"]["rag"] = rag - - writer = get_stream_writer() - writer({"type": "data-thinking", "data": {"step": "understand", "status": "done", ...}}) - - return {"history_messages": [...], "system_prompt": "..."} -``` - -**调用侧**： - -```python -# backend/app/api/v1/chat.py - -async def chat_graph_stream(request: ChatStreamRequest, db: AsyncSession): - graph = get_chat_graph() - config = {"configurable": {"db": db, "thread_id": str(uuid4())}} - initial_state = { - "message": request.message, - "knowledge_base_ids": request.knowledge_base_ids or [], - "tool_mode": request.tool_mode or "qa", - "conversation_id": request.conversation_id, - } - - yield f'data: {json.dumps({"type": "start", "messageId": f"msg_{uuid4().hex}"})}\n\n' - - async for mode, chunk in graph.astream(initial_state, config=config, stream_mode=["updates", "custom"]): - if mode == "custom": - yield f'data: {json.dumps(chunk)}\n\n' - - yield f'data: {json.dumps({"type": "finish"})}\n\n' - yield 'data: [DONE]\n\n' -``` - -### 前端 UIMessage Parts 适配 - -```typescript -// frontend/src/types/chat.ts - -// AI SDK 5.0 UIMessage 扩展类型 -interface CitationData { - index: number; - title: string; - authors: { name: string }[]; - year?: number; - doi?: string; - excerpt: string; - paper_id?: number; - source?: string; - confidence?: number; -} - -interface ThinkingData { - step: string; - label?: string; - status: 'running' | 'done' | 'error' | 'skipped'; - detail?: string; - duration_ms?: number; - summary?: string; -} - -interface ConversationData { - conversation_id: number; -} - -// 从 UIMessage.parts 提取自定义数据 -function getCitations(message: UIMessage): CitationData[] { - return message.parts - .filter(p => p.type === 'data-citation') - .map(p => p.data as CitationData); -} - -function getThinkingSteps(message: UIMessage): ThinkingData[] { - return message.parts - .filter(p => p.type === 'data-thinking') - .map(p => p.data as ThinkingData); -} -``` - -### MessageBubble 适配 - -```tsx -// frontend/src/components/playground/MessageBubble.tsx - -function MessageBubble({ message }: { message: UIMessage }) { - const citations = useMemo(() => getCitations(message), [message.parts]); - const thinkingSteps = useMemo(() => getThinkingSteps(message), [message.parts]); - - return ( -
- {message.parts.map((part, i) => { - switch (part.type) { - case 'text': - return ; - case 'data-citation': - return null; // 在 CitationCardList 中统一渲染 - case 'data-thinking': - return null; // 在 ThinkingChain 中统一渲染 - default: - return null; - } - })} - {thinkingSteps.length > 0 && } - {citations.length > 0 && } -
- ); -} - -export default memo(MessageBubble); -``` - -### Conversation 恢复 - -```tsx -// frontend/src/pages/PlaygroundPage.tsx - -function PlaygroundPage() { - const { conversationId: routeConvId } = useParams(); - const [initialMessages, setInitialMessages] = useState([]); - - // 从 DB 恢复消息并转换为 UIMessage 格式 - useEffect(() => { - if (routeConvId) { - conversationApi.get(Number(routeConvId)).then(conv => { - setInitialMessages(convertToUIMessages(conv.messages)); - }); - } - }, [routeConvId]); - - const { messages, sendMessage, status, stop, error } = useChat({ - chatId: routeConvId, - initialMessages, - transport: new DefaultChatTransport({ - api: '/api/v1/chat/stream', - headers: { 'Content-Type': 'application/json' }, - }), - }); - - // 从 streaming message 中提取 conversation_id 用于 URL 更新 - const latestConvId = useMemo(() => { - const lastAssistant = [...messages].reverse().find(m => m.role === 'assistant'); - if (!lastAssistant) return null; - const convPart = lastAssistant.parts.find(p => p.type === 'data-conversation'); - return convPart?.data?.conversation_id ?? null; - }, [messages]); - // ... -} -``` - -### Implementation Phases - -#### Phase 1: 后端 LangGraph Chat Pipeline + Data Stream Protocol - -**目标**：创建新的 LangGraph chat graph 和 Data Stream Protocol 端点，与旧端点并行运行 - -**文件变更**： - -| 操作 | 文件 | 说明 | -|------|------|------| -| 新建 | `backend/app/pipelines/chat/__init__.py` | 包初始化 | -| 新建 | `backend/app/pipelines/chat/state.py` | ChatState TypedDict | -| 新建 | `backend/app/pipelines/chat/nodes.py` | 7 个节点函数 | -| 新建 | `backend/app/pipelines/chat/graph.py` | StateGraph 定义 | -| 新建 | `backend/app/pipelines/chat/stream_writer.py` | Data Stream Protocol SSE 格式化工具 | -| 修改 | `backend/app/api/v1/chat.py` | 新增 `/stream/v2` 端点 | -| 新建 | `backend/tests/test_chat_pipeline.py` | 节点单元测试 | - -**详细任务**： - -**1.1 ChatState 定义** (`backend/app/pipelines/chat/state.py`) - -```python -from typing import Any, TypedDict - -class ChatState(TypedDict, total=False): - message: str - knowledge_base_ids: list[int] - tool_mode: str - conversation_id: int | None - rag_results: list[dict[str, Any]] - citations: list[dict[str, Any]] - enhanced_citations: list[dict[str, Any]] - history_messages: list[dict[str, Any]] - system_prompt: str - full_messages: list[dict[str, Any]] - assistant_content: str - new_conversation_id: int | None - error: str | None -``` - -**1.2 StreamWriter 工具** (`backend/app/pipelines/chat/stream_writer.py`) - -```python -import json -import uuid - -class DataStreamWriter: - """Formats events in Vercel AI SDK 5.0 Data Stream Protocol.""" - - @staticmethod - def start(message_id: str | None = None) -> str: - mid = message_id or f"msg_{uuid.uuid4().hex}" - return f'data: {json.dumps({"type": "start", "messageId": mid})}\n\n' - - @staticmethod - def text_start(text_id: str | None = None) -> str: - tid = text_id or f"text_{uuid.uuid4().hex}" - return f'data: {json.dumps({"type": "text-start", "id": tid})}\n\n' - - @staticmethod - def text_delta(text_id: str, delta: str) -> str: - return f'data: {json.dumps({"type": "text-delta", "id": text_id, "delta": delta})}\n\n' - - @staticmethod - def text_end(text_id: str) -> str: - return f'data: {json.dumps({"type": "text-end", "id": text_id})}\n\n' - - @staticmethod - def data_part(data_type: str, data: dict) -> str: - return f'data: {json.dumps({"type": data_type, "data": data})}\n\n' - - @staticmethod - def error(message: str) -> str: - return f'data: {json.dumps({"type": "error", "errorText": message})}\n\n' - - @staticmethod - def finish() -> str: - return f'data: {json.dumps({"type": "finish"})}\n\n' - - @staticmethod - def done() -> str: - return 'data: [DONE]\n\n' -``` - -**1.3 节点实现** (`backend/app/pipelines/chat/nodes.py`) - -每个节点遵循已有模式（`backend/app/pipelines/nodes.py`）：接收 state + config，返回 partial state update，通过 `get_stream_writer()` 发射自定义事件。 - -| 节点 | 职责 | `get_stream_writer()` 事件 | -|------|------|---------------------------| -| `understand_node` | 获取 LLM/RAG 服务，加载历史消息，构建 system prompt | `data-thinking(understand)` | -| `retrieve_node` | `asyncio.gather()` 并行 RAG 查询多个 KB | `data-thinking(retrieve)` | -| `rank_node` | 批量加载 Paper 元数据，构建 citation 列表 | `data-thinking(rank)` + `data-citation(id=cit-N)` × N | -| `clean_node` | LLM 并行清洗 citation excerpts | `data-thinking(clean)` + `data-citation(id=cit-N, 同 id 更新)` × M | -| `generate_node` | LLM 流式生成回答 | `data-thinking(generate)` + `text-start` + `text-delta` × K + `text-end` | -| `persist_node` | 创建/更新 conversation 和 messages | `data-conversation` | - -**关键：`generate_node` 的流式输出** - -```python -async def generate_node(state: ChatState, config: RunnableConfig) -> dict: - writer = get_stream_writer() - llm = config["configurable"]["llm"] - - writer({"type": "data-thinking", "data": {"step": "generate", "status": "running"}}) - - text_id = f"text_{uuid.uuid4().hex}" - writer({"type": "text-start", "id": text_id}) - - content = "" - async for token in llm.chat_stream(state["full_messages"]): - content += token - writer({"type": "text-delta", "id": text_id, "delta": token}) - - writer({"type": "text-end", "id": text_id}) - writer({"type": "data-thinking", "data": {"step": "generate", "status": "done"}}) - - return {"assistant_content": content} -``` - -**注意**：`generate_node` 发射的 `text-start/delta/end` 不是 `data-*` 类型，是标准 Part，直接作为 `custom` stream 事件输出。 - -**1.4 Graph 定义** (`backend/app/pipelines/chat/graph.py`) - -```python -from langgraph.graph import END, StateGraph - -def _route_after_understand(state: ChatState) -> str: - if state.get("knowledge_base_ids"): - return "retrieve" - return "generate" - -def build_chat_graph(): - graph = StateGraph(ChatState) - - graph.add_node("understand", understand_node) - graph.add_node("retrieve", retrieve_node) - graph.add_node("rank", rank_node) - graph.add_node("clean", clean_node) - graph.add_node("generate", generate_node) - graph.add_node("persist", persist_node) - - graph.set_entry_point("understand") - graph.add_conditional_edges("understand", _route_after_understand, { - "retrieve": "retrieve", - "generate": "generate", - }) - graph.add_edge("retrieve", "rank") - graph.add_edge("rank", "clean") - graph.add_edge("clean", "generate") - graph.add_edge("generate", "persist") - graph.add_edge("persist", END) - - return graph.compile() -``` - -**1.5 新端点** (`backend/app/api/v1/chat.py`) - -在现有 `/stream` 旁新增 `/stream/v2`： - -```python -@router.post("/stream/v2") -async def chat_stream_v2( - request: ChatStreamRequest, - db: AsyncSession = Depends(get_db), -): - return StreamingResponse( - _stream_chat_v2(request, db), - media_type="text/event-stream", - headers={ - "Cache-Control": "no-cache", - "Connection": "keep-alive", - "X-Accel-Buffering": "no", - "x-vercel-ai-ui-message-stream": "v1", - }, - ) -``` - -**1.6 后端测试** (`backend/tests/test_chat_pipeline.py`) - -- 每个节点独立测试（mock state + config） -- `understand_node`：验证 LLM/RAG 初始化、history 加载 -- `retrieve_node`：验证 RAG 查询、部分失败处理 -- `rank_node`：验证批量 Paper 查询、citation 构建 -- `clean_node`：验证 LLM 清洗、超时降级 -- `generate_node`：验证流式输出事件序列 -- `persist_node`：验证 conversation 创建/更新 -- 集成测试：验证完整 graph 执行和事件序列 - -**1.7 端点级错误处理** - -```python -async def _stream_chat_v2(request: ChatStreamRequest, db: AsyncSession): - writer = DataStreamWriter - yield writer.start() - try: - graph = build_chat_graph() - config = {"configurable": {"db": db, "thread_id": str(uuid4())}} - initial_state = {...} - - async for mode, chunk in graph.astream(initial_state, config=config, stream_mode=["updates", "custom"]): - if mode == "custom": - yield f'data: {json.dumps(chunk)}\n\n' - - yield writer.finish() - except Exception as e: - logger.exception("Chat graph error") - yield writer.error(str(e)) - finally: - yield writer.done() -``` - -### Phase 1 Research Insights - -**错误处理（Python Reviewer）**： -- 端点级 `try/except` 捕获所有 graph 异常并发射 `error` Part -- 节点内错误通过 `writer({"type": "error", ...})` 发射 + `return {"error": str(e)}` -- `generate_node` 中 LLM 错误可能发生在 partial content 已发射后——保留已发射内容 - -**性能（Performance Oracle）**： -- LangGraph overhead ~0.5-2ms/token，远低于 LLM 50-200ms 延迟 -- **不要使用 checkpointer**——`graph.compile()` 不传 checkpointer，避免序列化开销 -- `json.dumps` 每 token ~2-5µs，500 token 总计 < 3ms，可忽略 -- 当前 Paper 查询已是批量的（`IN` 查询），`rank_node` 须保持此模式 - -**测试（Python Reviewer）**： -- `get_stream_writer()` 在 graph 外部调用时为 None——测试需通过可选参数注入或在最小 graph 中运行 -- 建议节点签名添加 `_writer` 可选参数用于测试注入 - -**架构（Architecture Strategist）**： -- LangGraph 是正确选择（与现有 pipeline 一致、支持 HITL、支持 checkpointing） -- 路由函数返回类型用 `Literal["retrieve", "generate"]` -- `DataStreamWriter` 改为模块级函数而非 class + @staticmethod - -**RAG 效率（Python Reviewer）**： -- 考虑添加 `RAGService.retrieve_only()` 避免生成未使用的 answer -- 或保持 `query()` 并忽略 answer（更简单但有微小浪费） - -**Phase 1 验证标准**： -- [ ] 所有节点有单元测试（mock writer + config） -- [ ] `/stream/v2` 输出标准 Data Stream Protocol SSE -- [ ] 端点级错误处理：graph 异常 → `error` Part -- [ ] 旧 `/stream` 端点仍然工作（无破坏性变更） -- [ ] `ruff lint` 通过 -- [ ] 不使用 checkpointer - ---- - -#### Phase 2: 前端 Vercel AI SDK 迁移 - -**目标**：安装 AI SDK 5.0，创建 `useChat` 集成，替换手动状态管理 - -**文件变更**： - -| 操作 | 文件 | 说明 | -|------|------|------| -| 修改 | `frontend/package.json` | 添加 `ai`, `@ai-sdk/react` | -| 新建 | `frontend/src/hooks/useChatStream.ts` | `useChat` 封装（含自定义 data-* 处理） | -| 新建 | `frontend/src/lib/chat-transport.ts` | 自定义 Transport（请求体格式适配） | -| 修改 | `frontend/src/types/chat.ts` | 新增 UIMessage 辅助类型 + 提取函数 | -| 修改 | `frontend/src/pages/PlaygroundPage.tsx` | 重写为 useChat 驱动 | -| 修改 | `frontend/src/components/playground/MessageBubble.tsx` | 适配 UIMessage parts | -| 修改 | `frontend/src/components/playground/ThinkingChain.tsx` | 适配 ThinkingData | -| 修改 | `frontend/src/components/playground/CitationCard.tsx` | 适配 CitationData | -| 修改 | `frontend/src/components/playground/CitationCardList.tsx` | 适配 CitationData[] | -| 删除 | `frontend/src/services/chat-api.ts` (streamChat 部分) | 不再需要手写 SSE 解析 | -| 修改 | `frontend/src/components/playground/ChatInput.tsx` | 适配 sendMessage API | - -**详细任务**： - -**2.1 安装依赖** - -```bash -cd frontend && npm install ai @ai-sdk/react -``` - -**2.2 自定义 Transport** (`frontend/src/lib/chat-transport.ts`) - -```typescript -import { DefaultChatTransport } from 'ai'; -import type { UIMessage } from 'ai'; - -function getMessageText(message: UIMessage): string { - return message.parts - .filter((p): p is { type: 'text'; text: string } => p.type === 'text') - .map(p => p.text) - .join(''); -} - -export function createChatTransport(options?: { - knowledgeBaseIds?: number[]; - toolMode?: string; -}) { - return new DefaultChatTransport({ - api: '/api/v1/chat/stream/v2', - headers: { 'Content-Type': 'application/json' }, - prepareSendMessagesRequest: ({ messages, id }) => ({ - body: { - message: getMessageText(messages[messages.length - 1]), - knowledge_base_ids: options?.knowledgeBaseIds ?? [], - tool_mode: options?.toolMode ?? 'qa', - conversation_id: id ? Number(id) : undefined, - }, - }), - }); -} -``` - -**关键细节**（TypeScript Reviewer 反馈）： -- `messages[*].content` 在 AI SDK 5.0 已废弃 → 用 `getMessageText()` 从 parts 提取 -- `conversation_id` 通过 `id` 参数（即 `chatId`）传递到请求体 -- Transport 实例须通过 `useMemo` 稳定引用，数组 deps 需序列化 - -**2.3 UIMessage 类型定义** (`frontend/src/types/chat.ts`) - -```typescript -import type { UIMessage } from 'ai'; - -// 自定义 data-* Part 的 payload 类型（与后端 CitationDict 对齐） -export interface CitationData { - index: number; - paper_id?: number; - paper_title: string; - chunk_type?: string; - page_number?: number; - relevance_score?: number; - excerpt: string; - authors?: string[] | null; - year?: number | null; - doi?: string | null; -} - -export interface ThinkingData { - step: string; - label: string; // 必须，后端保证发射 - status: 'running' | 'done' | 'error' | 'skipped'; - detail?: string; - duration_ms?: number; - summary?: string; -} - -export interface ConversationData { - conversation_id: number; -} - -// AI SDK 5.0 泛型：强类型自定义 data parts -export type OmeletteDataParts = { - citation: CitationData; - thinking: ThinkingData; - conversation: ConversationData; -}; - -export type OmeletteUIMessage = UIMessage; - -// Citation 提取辅助（AI SDK id-based reconciliation 自动合并同 id Part） -export function getCitations(message: OmeletteUIMessage): CitationData[] { - return message.parts - .filter((p): p is { type: 'data-citation'; id?: string; data: CitationData } => - p.type === 'data-citation') - .map(p => p.data); -} - -export function getThinkingSteps(message: OmeletteUIMessage): ThinkingData[] { - return message.parts - .filter((p): p is { type: 'data-thinking'; data: ThinkingData } => - p.type === 'data-thinking') - .map(p => p.data); -} -``` - -**2.4 useChatStream Hook** (`frontend/src/hooks/useChatStream.ts`) - -```typescript -import { useChat } from '@ai-sdk/react'; -import { useDeferredValue, useMemo } from 'react'; -import { createChatTransport } from '@/lib/chat-transport'; -import type { - CitationData, ThinkingData, OmeletteUIMessage, - getCitations, getThinkingSteps, -} from '@/types/chat'; - -export function useChatStream(options: { - chatId?: string; - initialMessages?: OmeletteUIMessage[]; - knowledgeBaseIds?: number[]; - toolMode?: string; -}) { - // 稳定化 array deps（TypeScript Reviewer 反馈） - const kbIdsKey = useMemo( - () => JSON.stringify(options.knowledgeBaseIds ?? []), - [options.knowledgeBaseIds], - ); - - const transport = useMemo( - () => createChatTransport({ - knowledgeBaseIds: options.knowledgeBaseIds, - toolMode: options.toolMode, - }), - [kbIdsKey, options.toolMode], - ); - - const chat = useChat({ - id: options.chatId, // AI SDK 5.0 用 `id` 而非 `chatId` - initialMessages: options.initialMessages, - transport, - onData: (dataPart) => { - // 处理 transient parts（如通知） - if (dataPart.type === 'data-thinking' && dataPart.data.status === 'running') { - // thinking steps 可选择为 transient（不保存到消息历史） - } - }, - }); - - // 防抖流式内容（Performance Oracle P0 建议） - const deferredMessages = useDeferredValue(chat.messages); - - const lastAssistant = useMemo(() => { - return [...deferredMessages].reverse().find(m => m.role === 'assistant'); - }, [deferredMessages]); - - const citations = useMemo( - () => lastAssistant ? getCitations(lastAssistant) : [], - [lastAssistant], - ); - - const thinkingSteps = useMemo( - () => lastAssistant ? getThinkingSteps(lastAssistant) : [], - [lastAssistant], - ); - - const conversationId = useMemo(() => { - if (!lastAssistant) return null; - const part = lastAssistant.parts.find(p => p.type === 'data-conversation'); - return part ? (part.data as { conversation_id: number }).conversation_id : null; - }, [lastAssistant]); - - return { - ...chat, - messages: deferredMessages, - citations, - thinkingSteps, - conversationId, - }; -} -``` - -**关键改进（Research Insights）**： -- `useChat()` 泛型获得强类型 `data-*` Part 访问 -- `useDeferredValue(chat.messages)` 防止每 token re-render（Performance Oracle P0） -- `kbIdsKey = JSON.stringify(...)` 稳定化数组 deps（TypeScript Reviewer） -- `id` 替代 `chatId`（AI SDK 5.0 API 修正） -- `onData` 回调处理 transient parts -- Citation 用 type guard `(p): p is {...}` 替代 `as` 类型断言 - -**2.4 PlaygroundPage 重写** - -核心变化： -- 移除 `messages` useState → `useChatStream.messages` -- 移除 `isStreaming` useState → `status === 'streaming'` -- 移除 `pendingDeltaRef`、`flushTimerRef`、`assistantIdRef` → AI SDK 内部管理 -- 移除 `abortRef` → `stop()` -- 移除整个 `for await (event of gen)` 循环 → AI SDK 自动处理 -- 保留 `sidebarCollapsed`、`toolMode`、`selectedKBs` 等 UI 状态 - -**2.5 MessageBubble 适配** - -- `content` prop → 从 `message.parts` 中提取 text parts -- `citations` prop → `getCitations(message)` -- `thinkingSteps` prop → `getThinkingSteps(message)` -- `isStreaming` → 通过 `status` 判断 -- 保持 `memo()` 优化 - -**2.6 Conversation 恢复** - -```typescript -// 从后端 ChatMessage 转换为 UIMessage -function convertToUIMessages(messages: ChatMessage[]): UIMessage[] { - return messages.map(msg => ({ - id: String(msg.id), - role: msg.role as 'user' | 'assistant', - parts: [{ type: 'text' as const, text: msg.content }], - // 恢复的消息不包含 citation/thinking parts（已完成的对话） - })); -} -``` - -**2.7 删除旧代码** - -- `chat-api.ts` 中的 `streamChat` 函数和 `SSEEvent` 类型 -- `PlaygroundPage.tsx` 中的手动 SSE 处理逻辑 -- `LocalMessage` interface - -### Phase 2 Research Insights - -**类型安全（TypeScript Reviewer）**： -- `CitationData` 字段须与后端 `CitationDict` 对齐（`paper_title` 而非 `title`） -- 用 type guards 替代 `as CitationData` 类型断言 -- `convertToUIMessages` 须映射恢复消息的 citations 到 `data-citation` parts - -**性能（Performance Oracle P0）**： -- `useChat` 每 token 触发 re-render → 用 `useDeferredValue(chat.messages)` 防抖 -- `memo(MessageBubble)` 必须保留 -- `getCitations()` / `getThinkingSteps()` 放在 `useMemo` 中，依赖 `lastAssistant` - -**A2UISurface 迁移**： -- `LocalMessage.a2uiMessages` → `data-a2ui` Part（与 citation 同模式） -- 如果 A2UISurface 暂时不迁移，保留为独立 prop 从消息中提取 - -**错误/加载状态**： -- `status === 'submitted'`：已发送，等待首 token -- `status === 'streaming'`：流式中 -- `status === 'error'`：错误（`chat.error` 有详细信息） -- `chat.stop()`：中止 -- ChatInput disabled when `status !== 'ready'` - -**Phase 2 验证标准**： -- [ ] `useChat` 正常发送消息并接收流式响应 -- [ ] citations（含 id reconciliation 更新）正确渲染 -- [ ] thinking steps 正确渲染 -- [ ] 对话恢复（`/chat/:id`）正常工作（`initialMessages` + `id`） -- [ ] abort（`stop()`）正常工作 -- [ ] error 状态显示 toast 或内联错误 -- [ ] 流式文本无明显卡顿（`useDeferredValue` 生效） -- [ ] ESLint 无新增错误 -- [ ] TypeScript 编译通过 - ---- - -#### Phase 3: 清理与测试 - -**目标**：删除旧端点、补充测试、处理边缘情况 - -**文件变更**： - -| 操作 | 文件 | 说明 | -|------|------|------| -| 修改 | `backend/app/api/v1/chat.py` | `/stream/v2` → `/stream`（替换旧端点） | -| 修改 | `frontend/src/lib/chat-transport.ts` | URL 从 `/stream/v2` → `/stream` | -| 删除 | `backend/app/api/v1/chat.py` 旧代码 | 移除 `_stream_chat`、`_thinking`、`_clean_excerpt` | -| 修改 | `backend/tests/test_chat.py` | 更新为 Data Stream Protocol 格式断言 | -| 新建 | `frontend/src/hooks/__tests__/useChatStream.test.ts` | Hook 测试 | -| 新建 | `frontend/src/lib/__tests__/chat-transport.test.ts` | Transport 测试 | - -**详细任务**： - -**3.1 端点切换** - -- `/stream/v2` 重命名为 `/stream` -- 删除旧的 `_stream_chat` 函数和所有相关 helper -- 更新前端 Transport URL - -**3.2 边缘情况处理** - -| 场景 | 处理 | -|------|------| -| RAG 部分失败（某个 KB 查询失败） | `retrieve_node` 中 `asyncio.gather(return_exceptions=True)` + 过滤异常 | -| LLM 清洗超时 | `clean_node` 中 `asyncio.wait_for(timeout=10)` + 降级为原始 excerpt | -| DB 持久化失败 | `persist_node` catch → 发射 `data-thinking(persist, error)` + 继续完成流 | -| 用户 abort 中途 | `useChat.stop()` → 前端断开连接 → FastAPI `ClientDisconnect` | -| 无效 knowledge_base_ids | `retrieve_node` 跳过无效 ID + 发射 warning | -| conversation_id 不存在 | `persist_node` 创建新对话而非更新 | - -**3.3 测试补充** - -- 后端节点单元测试（Phase 1 已覆盖） -- 后端集成测试（完整 graph 执行 + SSE 事件验证） -- 前端 `useChatStream` hook 测试（MSW mock `/stream` 端点） -- 前端 `convertToUIMessages` 单元测试 -- 手动 E2E 验证（浏览器工具） - -**3.4 Rewrite API 评估** - -`backend/app/api/v1/rewrite.py` 也使用自定义 SSE 格式（`rewrite_delta`, `rewrite_end`）。本次不迁移——范围限定在 chat 端点。后续可复用 `DataStreamWriter` 统一所有 SSE 端点。 - -**Phase 3 验证标准**： -- [ ] 旧端点已删除，所有流量走新管道 -- [ ] 所有后端测试通过（`pytest`） -- [ ] 所有前端测试通过（`vitest`） -- [ ] 边缘情况有处理（部分失败、超时、abort） -- [ ] `ruff lint` + `eslint` 通过 - -## System-Wide Impact - -### Interaction Graph - -``` -用户点击发送 - → useChat.sendMessage() - → DefaultChatTransport.fetch(POST /api/v1/chat/stream) - → FastAPI chat_stream_v2() - → StreamingResponse(chat_graph_stream()) - → LangGraph graph.astream(stream_mode=["updates","custom"]) - → understand_node → retrieve_node → ... → persist_node - → get_stream_writer() → custom event → SSE data line - → yield SSE line - → Response body - → useChat internal SSE parser - → UIMessage.parts update - → React re-render - → MessageBubble → ThinkingChain, CitationCardList, MarkdownRenderer -``` - -### Error & Failure Propagation - -| 错误源 | 传播路径 | 处理 | -|--------|---------|------| -| LLM API 错误 | node → exception → graph → `_stream_chat_v2` catch → `error` Part | `useChat.error` 状态 | -| RAG 查询失败 | `retrieve_node` → `return_exceptions=True` → 过滤 | 跳过失败 KB，继续 | -| DB 错误 | `persist_node` → catch → `data-thinking(persist, error)` | 回答仍然显示，URL 不更新 | -| 网络断开 | fetch abort → `useChat` 检测 → `error` 状态 | 显示错误 toast | -| 用户 abort | `stop()` → abort signal → FastAPI `ClientDisconnect` | 清理状态 | - -### State Lifecycle Risks - -| 风险 | 缓解 | -|------|------| -| Graph 执行中 DB session 关闭 | 在 `chat_graph_stream` generator 中保持 `db` scope | -| 部分 citation 发射后 LLM 失败 | 前端已收到的 citation 保留显示，error 消息追加 | -| persist 失败导致对话丢失 | catch 异常 + log + 不影响已发射的回答内容 | - -### API Surface Parity - -| 接口 | 变更 | -|------|------| -| `POST /api/v1/chat/stream` | 输出格式从 `event:X\ndata:{}\n\n` → `data:{"type":"..."}\n\n` | -| `POST /api/v1/chat/rewrite` | **不变**（本次不迁移） | -| `GET /api/v1/rag/{id}/stream` | **不变**（本次不迁移） | -| `conversationApi.*` | **不变**（REST CRUD 不受影响） | - -### Integration Test Scenarios - -1. **完整 RAG 聊天流**：发送带 KB 的消息 → 验证 thinking steps 顺序 → 验证 citations 出现在 text 之前 → 验证 text streaming → 验证 conversation_id 更新 URL -2. **无 KB 直聊**：发送无 KB 的消息 → 验证跳过 retrieve/rank/clean → 直接 generate -3. **中途 abort**：发送消息 → 等 text_delta 出现 → stop() → 验证 UI 停止更新且不崩溃 -4. **对话恢复**：创建对话 → 导航到 `/chat/:id` → 验证 initialMessages 加载 → 继续发送消息 -5. **后端错误**：配置无效 LLM provider → 发送消息 → 验证 error Part 到达前端 → error 状态显示 - -## Acceptance Criteria - -### Functional Requirements - -- [ ] 用户发送消息后，收到标准 Data Stream Protocol SSE 响应 -- [ ] thinking steps 实时显示各节点状态（running → done） -- [ ] citations 在文本生成前出现 -- [ ] citation 更新（同 id reconciliation）正确替换摘要 -- [ ] 文本流式显示 -- [ ] conversation_id 正确传递并更新 URL -- [ ] 对话可通过 URL 恢复（`/chat/:id`） -- [ ] 错误正确显示（LLM 错误、网络错误） -- [ ] abort 正常工作 - -### Non-Functional Requirements - -- [ ] 首 token 延迟 ≤ 2s（与旧端点持平） -- [ ] 流式文本无明显卡顿 -- [ ] 旧端点的所有功能在新端点中可用 -- [ ] 新增代码有测试覆盖 - -### Quality Gates - -- [ ] `pytest` 通过，chat 节点测试 ≥ 7 个 -- [ ] `vitest` 通过 -- [ ] `ruff lint` + `eslint` 通过 -- [ ] 手动 E2E 验证聊天流程 - -## Success Metrics - -- PlaygroundPage 代码行数减少 ≥ 40%（手动状态管理被 useChat 替代） -- 后端 chat.py 拆分为 7 个可独立测试的节点 -- SSE 协议标准化（可被任何 AI SDK 兼容客户端消费） -- error 事件有处理（从 0 处理到 100% 处理） - -## Dependencies & Prerequisites - -| 依赖 | 版本要求 | 说明 | -|------|---------|------| -| `ai` (npm) | ^5.0.0 | Vercel AI SDK core | -| `@ai-sdk/react` (npm) | ^2.0.0 | React hooks | -| `langgraph` (pip) | >=0.4.0 | 已安装 | -| `langchain-core` (pip) | >=0.3 | 已安装 | -| Python | >=3.12 | 已满足（LangGraph `get_stream_writer()` 需 ≥3.11） | -| React | >=18 | 已满足（当前 v19） | - -## Risk Analysis & Mitigation - -| 风险 | 概率 | 影响 | 缓解 | -|------|------|------|------| -| AI SDK 5.0 beta 不稳定 | 中 | 高 | 先在 `/stream/v2` 并行运行，确认稳定后切换；Pydantic AI 已有生产参考 | -| `data-*` Part 前端消费 API 不明确 | 低 | 中 | 已验证 `message.parts.filter()` 可用（见 brainstorm 技术验证） | -| LangGraph `get_stream_writer()` + `astream` 组合行为未预期 | 中 | 中 | Phase 1 先写节点测试验证事件发射 | -| `useChat` 的 `prepareSendMessagesRequest` 不支持所需的请求体格式 | 低 | 高 | 备选：自定义 Transport 类继承 `ChatTransport` | -| 并行运行两个端点增加维护成本 | 低 | 低 | Phase 3 快速切换并删除旧代码 | - -## Future Considerations - -- **Resumable Streams**：AI SDK 5.0 支持 `prepareReconnectToStreamRequest`，结合 LangGraph checkpointing 可实现断流续传 -- **Rewrite API 统一**：复用 `DataStreamWriter` 迁移 `/rewrite` 端点 -- **工具调用**：AI SDK 5.0 原生支持 `tool-input-start/delta/available` + `tool-output-available` Part -- **多模型并行**：LangGraph 支持并行节点，可扩展为多模型对比回答 - -## Sources & References - -### Origin - -- **Brainstorm document**: [docs/brainstorms/2026-03-12-chat-message-routing-chain-brainstorm.md](docs/brainstorms/2026-03-12-chat-message-routing-chain-brainstorm.md) — 关键决策：AI SDK 5.0 Data Stream Protocol、LangGraph StateGraph、data-* 自定义 Part - -### Internal References - -- LangGraph 现有模式: `backend/app/pipelines/graphs.py:39-68` -- LangGraph 节点模式: `backend/app/pipelines/nodes.py:16-33` -- 当前 chat 端点: `backend/app/api/v1/chat.py:99-330` -- 当前 SSE 客户端: `frontend/src/services/chat-api.ts:27-78` -- 当前 Playground 状态: `frontend/src/pages/PlaygroundPage.tsx:31-40,114-269` -- HITL 模式: `docs/solutions/integration-issues/langgraph-hitl-interrupt-api-snapshot-next.md` -- Sync 调用模式: `docs/solutions/performance-issues/blocking-sync-calls-asyncio-to-thread.md` -- RAG 性能: `docs/solutions/performance-issues/2026-03-12-rag-rich-citation-performance-analysis.md` -- LangGraph 规则: `.cursor/rules/langgraph-pipelines.mdc` - -### External References - -- Vercel AI SDK 5.0 Stream Protocol: https://sdk.vercel.ai/docs/ai-sdk-ui/stream-protocol -- AI SDK 5.0 + FastAPI working example: https://github.com/vercel/ai/issues/7496#issuecomment-2379142 -- Pydantic AI 的 AI SDK 协议实现: https://ai.pydantic.dev/ui/vercel-ai/ -- LangGraph `get_stream_writer()`: https://reference.langchain.com/python/langgraph/config/get_stream_writer -- LangGraph + FastAPI SSE guide: https://dev.to/kasi_viswanath/streaming-ai-agent-with-fastapi-langgraph-2025-26-guide-1nkn diff --git a/docs/plans/2026-03-12-feat-frontend-ux-robustness-upgrade-plan.md b/docs/plans/2026-03-12-feat-frontend-ux-robustness-upgrade-plan.md deleted file mode 100644 index be68f2ec..00000000 --- a/docs/plans/2026-03-12-feat-frontend-ux-robustness-upgrade-plan.md +++ /dev/null @@ -1,771 +0,0 @@ ---- -title: "feat: 前端用户体验与健壮性全面升级" -type: feat -status: completed -date: 2026-03-12 -origin: ../brainstorms/2026-03-12-frontend-ux-robustness-brainstorm.md -supersedes: - - docs/plans/2026-03-12-fix-batch1-security-stability-plan.md (frontend parts) - - docs/plans/2026-03-12-fix-batch2-error-handling-ux-plan.md (frontend parts) - - docs/plans/2026-03-12-refactor-batch3-code-quality-plan.md (frontend parts) - - docs/plans/2026-03-12-feat-batch4-testing-polish-plan.md (frontend parts) ---- - -# feat: 前端用户体验与健壮性全面升级 - -## Overview - -对 Omelette 前端进行系统性的健壮性加固和用户体验优化，采用「由内而外」策略：先建设测试和错误处理地基（Phase 1），再加固核心聊天和论文流程（Phase 2），最后打磨交互一致性和导航（Phase 3）。 - -本计划**取代** Batch 1-4 的所有前端任务（F1-F36），将其重新编号为 UX-1 至 UX-28 并纳入 3 阶段实施。Batch 1-4 的**后端任务**（B1-B20）仍然有效，独立执行。 - -## Problem Statement / Motivation - -当前前端存在 28 个已识别问题，包括： -- **严重**：Axios 拦截器双层解包导致类型不安全（UX-21） -- **高**：Playground 和 RAG Chat 割裂、对话历史不可恢复、SSE 断流崩溃（UX-8/9/10） -- **高**：所有 CRUD 操作缺少一致的反馈（UX-1/2） -- **结构性**：7 个知识库子页面导航复杂、论文添加入口分散（UX-14/17） -- **测试**：仅 3 个测试文件，核心流程零覆盖 - -项目定位为个人科研助手，稳定性是第一优先级。允许大胆重构，不需要向后兼容。 - -## Proposed Solution - -3 阶段「由内而外」加固： - -1. **Phase 1：健壮性基础设施** —— toast/错误处理/类型安全/测试基础设施/代码分割 -2. **Phase 2：核心流程加固 + 测试** —— 聊天合并 + AI SDK 迁移 + 论文添加整合 + 核心测试 -3. **Phase 3：UX 体验提升** —— 组件一致性 + 导航精简 + 空状态 + 交互打磨 + 补充测试 - -## Technical Approach - -### Architecture - -``` -Phase 1 改动范围（基础层） -├── src/lib/api.ts # 修复拦截器，泛型化 -├── src/components/ErrorBoundary.tsx # i18n 化 -├── src/components/ui/loading-state.tsx # 新建 -├── src/components/ui/empty-state.tsx # 新建 -├── src/hooks/use-toast-mutation.ts # 新建 -├── src/App.tsx # React.lazy + Suspense -├── src/test/mocks/handlers.ts # 扩展所有 API -├── playwright.config.ts # 新建 -└── e2e/ # 新建 - -Phase 2 改动范围（核心流程） -├── src/pages/PlaygroundPage.tsx # 重写：合并 RAG，useChat -├── src/pages/ChatHistoryPage.tsx # 可点击恢复 -├── src/pages/project/RAGChatPage.tsx # 删除（合并到 Playground） -├── src/components/playground/ # MessageBubble memo, ChatInput 优化 -├── src/components/knowledge-base/ -│ └── AddPaperDialog.tsx # 重写：三 Tab 合并 -├── src/services/chat-api.ts # 移除 streamChat（AI SDK 替代） -└── src/**/__tests__/ # 核心流程测试 - -Phase 3 改动范围（UX 打磨） -├── src/pages/project/ # 7 → 3 子页面 -├── src/components/knowledge-base/ -│ └── SubscriptionManager.tsx # 拆分 -├── src/pages/SettingsPage.tsx # 拆分 -└── src/i18n/locales/ # 补全 key -``` - -### Implementation Phases - ---- - -#### Phase 1: 健壮性基础设施（地基） - -**目标：** 统一的错误处理、反馈系统、类型安全、测试基础设施 - -##### 1.1 全局反馈系统 - -- [x] **Sonner toast 集成验证** —— 确认 `` 在 `App.tsx:63` 已存在 -- [x] **创建 `src/hooks/use-toast-mutation.ts`** —— 封装 TanStack Query 的 `useMutation`，自动处理 `onSuccess`/`onError` toast - -```typescript -// src/hooks/use-toast-mutation.ts -import { useMutation, type UseMutationOptions } from '@tanstack/react-query'; -import { toast } from 'sonner'; -import { useTranslation } from 'react-i18next'; - -export function useToastMutation( - options: UseMutationOptions & { - successMessage?: string; - errorMessage?: string; - } -) { - const { t } = useTranslation(); - const { successMessage, errorMessage, onSuccess, onError, ...rest } = options; - - return useMutation({ - ...rest, - onSuccess: (data, variables, context) => { - if (successMessage) toast.success(successMessage); - onSuccess?.(data, variables, context); - }, - onError: (error, variables, context) => { - toast.error(errorMessage || t('common.operationFailed'), { - description: error.message, - }); - onError?.(error, variables, context); - }, - }); -} -``` - -- [x] **添加 `renderWithProviders` 中的 Toaster** —— `src/test/utils.tsx` wrapper 增加 `` -- [x] **迁移所有现有 mutation** —— 按页面逐个替换 - -| 页面 | mutation 数量 | 当前状态 | -|------|-------------|---------| -| `KnowledgeBasesPage.tsx` | 2 (create, delete) | 已有 toast | -| `PapersPage.tsx` | 3 (delete, ocr, resolveConflict) | 部分 toast，resolveConflict 仅 console.error | -| `KeywordsPage.tsx` | 3 (create, delete, expand) | 已有 toast | -| `ChatHistoryPage.tsx` | 1 (delete) | 已有 toast | -| `SettingsPage.tsx` | 2 (save, testConnection) | 无 toast | -| `WritingPage.tsx` | 4 (summarize, cite, outline, gap) | 无 toast | -| `SubscriptionManager.tsx` | 3 (create, update, delete) | 无 toast | -| `SearchPage.tsx` | 2 (search, import) | 无 toast | -| `RAGChatPage.tsx` | 1 (query) | 无 toast | - -##### 1.2 统一错误处理 - -- [x] **Error Boundary i18n 化** —— `src/components/ErrorBoundary.tsx` - - 硬编码 "Something went wrong" → `t('error.boundary.title')` - - 硬编码 "An unexpected error occurred" → `t('error.boundary.description')` - - 硬编码 "Reload Page" → `t('error.boundary.reload')` - - 在 `zh.json` 和 `en.json` 添加对应 key -- [x] **修复 Axios 拦截器双层解包 (UX-21)** —— `src/lib/api.ts` - - 当前：拦截器返回 `response.data`，调用方又用 `res.data` - - 修复方案：拦截器返回完整 `response`，在 service 层统一解包 - - 同步修改所有 `services/*.ts` 的调用方式 - -```typescript -// src/lib/api.ts — 修复后 -api.interceptors.response.use( - (response) => response, // 不再解包，返回完整 AxiosResponse - (error) => { - const message = error.response?.data?.message || error.message || 'Unknown error'; - return Promise.reject(new Error(message)); - } -); -``` - -- [x] **API 服务层泛型化** —— `src/services/api.ts` - -```typescript -// src/services/api.ts — 类型化示例 -export const projectApi = { - list: () => api.get>('/projects').then(r => r.data), - get: (id: number) => api.get>(`/projects/${id}`).then(r => r.data), - create: (data: CreateProjectInput) => api.post>('/projects', data).then(r => r.data), - // ... -}; -``` - -- [x] **`response.body` null 检查 (UX-10)** —— `src/services/api.ts:79` - - `response.body!` → `if (!response.body) throw new Error('Stream body is null')` - -##### 1.3 统一加载与空状态组件 - -- [x] **创建 `src/components/ui/loading-state.tsx`** - -```typescript -// src/components/ui/loading-state.tsx -import { Loader2 } from 'lucide-react'; - -interface LoadingStateProps { - message?: string; - className?: string; -} - -export function LoadingState({ message, className }: LoadingStateProps) { - return ( -
- - {message &&

{message}

} -
- ); -} -``` - -- [x] **创建 `src/components/ui/empty-state.tsx`** - -```typescript -// src/components/ui/empty-state.tsx -import { type LucideIcon } from 'lucide-react'; -import { Button } from './button'; - -interface EmptyStateProps { - icon: LucideIcon; - title: string; - description?: string; - action?: { label: string; onClick: () => void }; -} - -export function EmptyState({ icon: Icon, title, description, action }: EmptyStateProps) { - return ( -
- -

{title}

- {description &&

{description}

} - {action && ( - - )} -
- ); -} -``` - -- [x] **替换所有分散的加载/空状态实现** —— 涉及 9 个页面 - -| 页面 | 当前加载态 | 当前空状态 | -|------|----------|----------| -| `KnowledgeBasesPage` | `t('common.loading')` text | 有空状态，需加 CTA | -| `ChatHistoryPage` | `t('common.loading')` text | 无 CTA | -| `PapersPage` | `t('common.loading')` text | 无 | -| `KeywordsPage` | `t('common.loading')` text | 无 | -| `TasksPage` | `t('common.loading')` text | 无 | -| `PlaygroundPage` | KB picker 无加载态 | N/A | -| `ProjectOverview` | `t('common.loading')` text | 无 | -| `SettingsPage` | `t('common.loading')` text | N/A | -| `SubscriptionManager` | `t('common.loading')` text | 无 | - -##### 1.4 测试基础设施扩展 - -- [x] **扩展 MSW handlers** —— `src/test/mocks/handlers.ts` - - 添加：papers, keywords, chat/stream, chat/conversations, settings, subscriptions, search, rag, writing, tasks, dedup, ocr - - 每个 handler 返回符合 `ApiResponse` 格式的 mock 数据 -- [x] **添加测试 fixtures** —— `src/test/fixtures/` - -``` -src/test/fixtures/ -├── projects.ts # mockProject, mockProjectList -├── papers.ts # mockPaper, mockPaperList -├── conversations.ts # mockConversation, mockMessage -├── settings.ts # mockSettings -└── index.ts # barrel export -``` - -- [x] **配置 Playwright** —— 项目根目录 - -```typescript -// playwright.config.ts -import { defineConfig, devices } from '@playwright/test'; - -export default defineConfig({ - testDir: './e2e', - fullyParallel: true, - retries: process.env.CI ? 2 : 0, - workers: process.env.CI ? 1 : undefined, - reporter: 'html', - use: { - baseURL: 'http://localhost:5173', - trace: 'on-first-retry', - screenshot: 'only-on-failure', - }, - projects: [ - { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, - ], - webServer: { - command: 'npm run dev', - url: 'http://localhost:5173', - reuseExistingServer: !process.env.CI, - cwd: './frontend', - }, -}); -``` - -- [x] **创建 E2E mock helpers** —— `e2e/fixtures/mock-sse.ts` - -``` -e2e/ -├── pages/ -│ ├── chat.page.ts # ChatPage POM -│ ├── knowledge-bases.page.ts -│ └── settings.page.ts -├── fixtures/ -│ └── mock-sse.ts # SSE mock helper for page.route() -└── chat.spec.ts # 第一个 E2E 测试（Phase 2 使用） -``` - -- [ ] **添加 Vitest 覆盖率** —— `vitest.config.ts` 已配置 v8 + lcov -- [ ] **CI 更新** —— `.github/workflows/ci.yml` - - 添加 Playwright 安装和运行步骤 - - 确保 `npm test` 输出覆盖率 - -##### 1.5 代码分割 - -- [x] **App.tsx 路由 React.lazy** —— 确认已使用 `lazy(() => import(...))`（研究发现已实现） -- [x] **Suspense fallback 替换** —— 将 `"Loading..."` 字符串替换为 `` - -```typescript -// src/App.tsx -}> - ... - -``` - -##### Phase 1 验证标准 - -- [x] 任何 CRUD 操作都有 toast 反馈（成功或失败） -- [x] Error Boundary 捕获异常，显示国际化 fallback -- [x] API 调用有类型安全的响应（`ApiResponse`） -- [x] `response.body` null 不会导致崩溃 -- [x] 所有页面使用 `` 和 `` -- [x] MSW handlers 覆盖所有 API 端点 -- [x] Playwright 可运行（至少有一个 smoke test） -- [ ] `npm test` 输出覆盖率报告（推迟：CI 配置未修改） - -##### Phase 1 测试 - -| 类型 | 测试 | 文件 | -|------|------|------| -| 单元 | `useToastMutation` 成功/失败 toast | `src/hooks/__tests__/use-toast-mutation.test.ts` | -| 单元 | Error Boundary 捕获并渲染 fallback | `src/components/__tests__/ErrorBoundary.test.tsx` | -| 单元 | API 客户端类型安全、错误规范化 | `src/services/__tests__/api.test.ts`（扩展现有） | -| 集成 | LoadingState / EmptyState 渲染 | `src/components/ui/__tests__/states.test.tsx` | - ---- - -#### Phase 2: 核心流程加固 + 测试 - -**目标：** 聊天和论文添加做到可靠、可测试 - -**前置条件：** Phase 1 完成（toast、错误处理、LoadingState、测试基础设施） - -##### 2.1 聊天流程统一 - -**路由变更：** - -``` -当前路由 → 目标路由 -/ (Playground) → / (统一聊天，新对话) -/projects/:id/rag (RAG Chat) → 删除（合并到 /） - → /chat/:conversationId (恢复历史对话) -/history (ChatHistory) → /history (可点击跳转到 /chat/:id) -``` - -- [x] ~~**安装 Vercel AI SDK**~~ —— 推迟：后端尚无兼容端点，改为优化现有 SSE 流 -- [x] ~~**后端 SSE 协议适配**~~ —— 推迟同上 - - AI SDK Data Stream Protocol 要求如下 SSE 事件格式： - - | 当前后端事件 | AI SDK 目标事件 | 说明 | - |-------------|----------------|------| - | `message_start` | `start` | 流开始 | - | `text_delta` | `text-delta` | 文本增量 | - | `citation` | `source-document` 或自定义 `data-citation` | 引用 | - | `message_end` | `finish` | 流结束 | - | `error` | `error` | 错误 | - | - | `[DONE]` | SSE 终止信号 | - - **方案：后端新增 AI SDK 兼容端点** `/api/v1/chat/ai-stream`，保留旧端点过渡。后端任务已记录到 B 系列，本计划前端假设新端点可用。 - -- [x] **重写 `PlaygroundPage.tsx`** —— 增强现有 SSE 流 + stop + URL 更新（AI SDK 推迟） - -```typescript -// src/pages/PlaygroundPage.tsx — 核心结构 -import { useChat, DefaultChatTransport } from '@ai-sdk/react'; - -const transport = new DefaultChatTransport({ - api: '/api/v1/chat/ai-stream', - body: { knowledge_base_ids: selectedKBs, tool_mode: toolMode }, -}); - -const { messages, sendMessage, status, error, stop } = useChat({ transport }); -``` - - - 选择知识库 → RAG 模式；不选 → 通用问答 - - 支持从 `/chat/:conversationId` 加载历史消息 - - `error` 状态 → toast + 内联错误提示 - - `stop()` 中止流 → 保留部分消息 - - `status === 'streaming'` → 显示打字指示器 - -- [x] **聊天状态机** —— idle/streaming/error 通过现有 isLoading + AbortController 实现 - -``` -idle → sending → streaming → idle - ↓ ↓ ↓ -error error error/aborted - ↓ ↓ ↓ -(toast) (toast) (toast + 保留部分消息) -``` - - - `idle`：可输入，可发送 - - `sending`：禁用输入，显示 spinner - - `streaming`：显示逐字输出，可点击 Stop - - `error`：显示 toast，可重试（`regenerate()`） - - `aborted`：保留已接收内容，回到 idle - -- [x] **对话恢复** —— `ChatHistoryPage.tsx` 可点击跳转 `/chat/:conversationId`，PlaygroundPage 检测路由参数加载历史 - -- [x] **MessageBubble 性能优化** —— 已有 `React.memo` - -- [x] **KB picker 加载态** —— 加载中显示 `` - -- [x] **删除 RAGChatPage** —— 移除路由 + 重定向 `/projects/:id/rag` → `/` - -- [ ] ~~**删除 `streamChat`**~~ —— 保留：AI SDK 推迟，现有 SSE 逻辑仍在使用 - -##### 2.2 论文添加流程整合 - -- [x] **重写 `AddPaperDialog.tsx`** —— 搜索 + 上传两 Tab 合并（订阅已独立到 DiscoveryPage） - -``` -AddPaperDialog -├── Tab 1: 搜索添加（原 SearchAddDialog） -│ ├── Step 1: 输入关键词 + 选择数据源 -│ ├── Step 2: 查看搜索结果 -│ └── Step 3: 选择导入 → 去重检查 -├── Tab 2: PDF 上传（原 PdfUploadDialog） -│ ├── 拖拽/选择文件 -│ ├── 上传进度 -│ └── 元数据提取 → 去重检查 -└── Tab 3: 订阅（新增/管理订阅规则） - ├── 创建新订阅 - └── 已有订阅列表 -``` - -- [x] **SearchAddDialog 拆分** —— SearchQueryStep + SearchResultsStep 提取 - -``` -src/components/knowledge-base/ -├── AddPaperDialog.tsx # 顶层 Dialog + Tabs -├── search-add/ -│ ├── SearchQueryStep.tsx # 关键词输入 + 数据源选择 -│ ├── SearchResultsStep.tsx # 结果列表 + 选择 -│ └── SearchSelectStep.tsx # 确认导入 -├── pdf-upload/ -│ └── PdfUploadStep.tsx # 文件选择 + 上传 -└── subscription/ - └── SubscriptionTab.tsx # 订阅管理 -``` - -- [x] **修复 i18n 缺失 key (UX-18)** —— 补充 history/playground/discovery 相关 key - -- [ ] **去重冲突面板类型安全 (UX-19)** —— 留待后续优化 - -- [ ] **Dialog 关闭保护** —— 留待后续优化 - -##### 2.3 核心流程测试 - -**单元测试：** - -| 测试 | 文件 | 覆盖 | -|------|------|------| -| ChatInput 提交/禁用/Shift+Enter | `src/components/playground/__tests__/ChatInput.test.tsx` | 扩展现有 | -| MessageBubble 用户/助手/引用/memo | `src/components/playground/__tests__/MessageBubble.test.tsx` | 新建 | -| API 客户端请求/响应/错误 | `src/services/__tests__/api.test.ts` | 扩展现有 | -| useToastMutation 已测(Phase 1) | — | — | - -**集成测试：** - -| 测试 | 文件 | 覆盖 | -|------|------|------| -| PlaygroundPage 完整消息流转 | `src/pages/__tests__/PlaygroundPage.test.tsx` | 新建 | -| PlaygroundPage 对话恢复 | 同上 | 新建 | -| KnowledgeBasesPage CRUD | `src/pages/__tests__/KnowledgeBasesPage.test.tsx` | 扩展现有 | -| PapersPage 添加论文 | `src/pages/__tests__/PapersPage.test.tsx` | 新建 | -| DedupConflictPanel 冲突解决 | `src/components/__tests__/DedupConflictPanel.test.tsx` | 新建 | - -**E2E 测试：** - -| 测试 | 文件 | 覆盖 | -|------|------|------| -| 新建 KB → 添加论文 → 聊天 → 引用 | `e2e/chat-flow.spec.ts` | 新建 | -| 恢复历史对话 → 继续提问 | `e2e/chat-restore.spec.ts` | 新建 | - -**E2E SSE Mock 策略：** - -```typescript -// e2e/fixtures/mock-sse.ts -export async function mockChatStream(page: Page) { - await page.route('/api/v1/chat/ai-stream', async (route) => { - const body = [ - 'event: start\ndata: {}\n\n', - 'event: text-delta\ndata: {"textDelta":"Hello"}\n\n', - 'event: text-delta\ndata: {"textDelta":" world"}\n\n', - 'event: finish\ndata: {}\n\n', - 'data: [DONE]\n\n', - ].join(''); - await route.fulfill({ - status: 200, - headers: { 'Content-Type': 'text/event-stream', 'x-vercel-ai-ui-message-stream': 'v1' }, - body, - }); - }); -} -``` - -##### Phase 2 验证标准 - -- [x] 聊天功能有单一入口（Playground），选 KB 即为 RAG -- [x] `/chat/:id` 可恢复历史对话 -- [x] 无效 `/chat/99999` 显示 "对话未找到" + 返回首页 -- [x] SSE 断流不崩溃，显示 toast + 保留部分消息 -- [x] 中止流保留已接收内容 -- [x] 论文添加在一个 Dialog 的两个 Tab 完成（搜索 | 上传） -- [ ] Dialog 关闭中保护上传进行中的操作（留待后续） -- [x] i18n 无缺失 key（中英文双语） -- [x] 核心流程单元+集成测试覆盖率 > 60% -- [x] 4 个 E2E 测试通过（chat-flow, chat-restore, smoke, kb-paper-flow） - ---- - -#### Phase 3: UX 体验提升 - -**目标：** 交互一致性、导航精简、视觉打磨 - -**前置条件：** Phase 2 完成（聊天合并、论文整合） - -##### 3.1 组件风格统一 - -- [x] **替换 raw HTML 表单元素** —— 所有 ``, `