┌─────────────────────────────────────────────────────────┐
│                    用户界面层                            │
│  (Web App / Mobile App / Chrome Extension)             │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────────────┐
│                  应用逻辑层                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │ 文档管理 │  │ 对话引擎 │  │ 音频生成 │             │
│  └──────────┘  └──────────┘  └──────────┘             │
└────────────────┬────────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────────────┐
│                  核心AI层                                │
│  ┌─────────────────────────────────────────────┐       │
│  │  RAG Pipeline                               │       │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐ │       │
│  │  │Document  │→ │Embedding │→ │ Vector   │ │       │
│  │  │Processing│  │Generation│  │  Store   │ │       │
│  │  └──────────┘  └──────────┘  └──────────┘ │       │
│  │         ↓                          ↓        │       │
│  │  ┌──────────────────────────────────┐     │       │
│  │  │     Query + Retrieval Engine     │     │       │
│  │  └──────────────────────────────────┘     │       │
│  │         ↓                                   │       │
│  │  ┌──────────────────────────────────┐     │       │
│  │  │   LLM (Gemini 2.0 / GPT-4)      │     │       │
│  │  └──────────────────────────────────┘     │       │
│  └─────────────────────────────────────────────┘       │
│                                                          │
│  ┌──────────────────────────────────────────────┐      │
│  │  Audio Generation Pipeline                   │      │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  │      │
│  │  │ Script   │→ │Voice TTS │→ │ Audio    │  │      │
│  │  │Generation│  │(ElevenLabs│  │Mixing    │  │      │
│  │  │          │  │ /Gemini)  │  │          │  │      │
│  │  └──────────┘  └──────────┘  └──────────┘  │      │
│  └──────────────────────────────────────────────┘      │
└─────────────────────────────────────────────────────────┘
                 │
┌────────────────┴────────────────────────────────────────┐
│                  基础设施层                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │ 对象存储 │  │ 向量数据库│  │ 缓存层   │             │
│  │(GCS/S3)  │  │(Vertex AI)│  │(Redis)   │             │
│  └──────────┘  └──────────┘  └──────────┘             │
└─────────────────────────────────────────────────────────┘

class DocumentProcessor:
    """
    文档处理器：将各种格式转换为统一的结构化表示
    """
    def __init__(self):
        self.pdf_parser = PyMuPDFParser()
        self.html_parser = BeautifulSoupParser()
        self.audio_transcriber = WhisperTranscriber()
        self.vision_extractor = GeminiVisionExtractor()

    async def process_document(self, file_path: str, file_type: str) -> Document:
        """
        统一的文档处理接口

        Args:
            file_path: 文档路径
            file_type: 文档类型 (pdf, html, audio, etc.)

        Returns:
            结构化的Document对象
        """
        # 步骤1：内容提取
        if file_type == "pdf":
            raw_content = self.pdf_parser.extract(file_path)
        elif file_type == "html":
            raw_content = self.html_parser.extract(file_path)
        elif file_type == "audio":
            raw_content = self.audio_transcriber.transcribe(file_path)

        # 步骤2：结构化处理
        structured_doc = self._structure_content(raw_content)

        # 步骤3：元数据提取
        metadata = await self._extract_metadata(structured_doc)

        # 步骤4：分块处理（用于embedding）
        chunks = self._create_chunks(
            structured_doc,
            chunk_size=512,
            overlap=50,
            preserve_structure=True
        )

        return Document(
            content=structured_doc,
            metadata=metadata,
            chunks=chunks
        )

    def _create_chunks(self, doc: StructuredContent,
                       chunk_size: int, overlap: int,
                       preserve_structure: bool) -> List[Chunk]:
        """
        智能分块：保持语义完整性

        关键点：
        - 在句子边界分块
        - 保持章节完整性
        - 添加上下文元数据
        """
        chunks = []

        for section in doc.sections:
            # 使用滑动窗口，但在句子边界
            text = section.text
            sentences = self._split_sentences(text)

            current_chunk = []
            current_size = 0

            for sent in sentences:
                sent_tokens = len(self.tokenizer.encode(sent))

                if current_size + sent_tokens > chunk_size and current_chunk:
                    # 创建chunk并保留上下文信息
                    chunk_text = " ".join(current_chunk)
                    chunks.append(Chunk(
                        text=chunk_text,
                        metadata={
                            "section_title": section.title,
                            "doc_id": doc.id,
                            "position": len(chunks)
                        }
                    ))

                    # 重叠处理：保留最后几个句子
                    overlap_sents = self._get_overlap_sentences(
                        current_chunk, overlap
                    )
                    current_chunk = overlap_sents + [sent]
                    current_size = sum(len(self.tokenizer.encode(s))
                                     for s in current_chunk)
                else:
                    current_chunk.append(sent)
                    current_size += sent_tokens

            # 处理最后一个chunk
            if current_chunk:
                chunks.append(Chunk(
                    text=" ".join(current_chunk),
                    metadata={
                        "section_title": section.title,
                        "doc_id": doc.id,
                        "position": len(chunks)
                    }
                ))

        return chunks

# generated by hugo's coding agent

class RAGEngine:
    """
    RAG引擎：检索增强生成
    """
    def __init__(self, vector_store, llm_client, embedder):
        self.vector_store = vector_store
        self.llm = llm_client
        self.embedder = embedder
        self.reranker = CrossEncoderReranker()

    async def answer_query(self, query: str,
                          source_docs: List[str],
                          top_k: int = 5) -> Answer:
        """
        基于源文档回答问题

        流程：
        1. 查询理解和扩展
        2. 向量检索
        3. 重排序
        4. 上下文构建
        5. LLM生成
        6. 答案验证
        """
        # 步骤1：查询增强
        enhanced_query = await self._enhance_query(query)

        # 步骤2：混合检索（向量+关键词）
        vector_results = await self._vector_search(
            enhanced_query,
            source_docs,
            top_k=top_k*2
        )
        keyword_results = await self._keyword_search(
            query,
            source_docs,
            top_k=top_k
        )

        # 步骤3：融合和重排序
        combined = self._merge_results(vector_results, keyword_results)
        reranked = await self.reranker.rerank(query, combined, top_k=top_k)

        # 步骤4：构建提示词
        prompt = self._build_rag_prompt(query, reranked)

        # 步骤5：LLM生成（带约束）
        response = await self.llm.generate(
            prompt,
            temperature=0.1,  # 低温度保证准确性
            max_tokens=1024,
            stop_sequences=["[END]"]
        )

        # 步骤6：引用验证
        validated_answer = self._validate_citations(
            response.text,
            reranked
        )

        return Answer(
            text=validated_answer.text,
            citations=validated_answer.citations,
            confidence=validated_answer.confidence
        )

    def _build_rag_prompt(self, query: str,
                          contexts: List[Chunk]) -> str:
        """
        构建RAG提示词

        关键约束：
        - 只使用提供的上下文
        - 必须引用来源
        - 不确定时明确说明
        """
        context_str = "\n\n".join([
            f"[Source {i+1}: {ctx.metadata['section_title']}]\n{ctx.text}"
            for i, ctx in enumerate(contexts)
        ])

        prompt = f"""你是一个精确的问答助手，只基于提供的文档内容回答问题。

上下文文档：
{context_str}

用户问题：{query}

回答要求：
1. 只使用上述文档中的信息
2. 对每个事实标注来源（如 [Source 1]）
3. 如果文档中没有相关信息，明确说明"文档中未提及"
4. 不要添加文档外的知识

回答："""

        return prompt

    async def _vector_search(self, query: str,
                            doc_ids: List[str],
                            top_k: int) -> List[Chunk]:
        """
        向量检索
        """
        # 生成查询向量
        query_embedding = await self.embedder.embed(query)

        # 在向量数据库中检索
        results = await self.vector_store.search(
            embedding=query_embedding,
            filters={"doc_id": {"$in": doc_ids}},
            top_k=top_k,
            metric="cosine"
        )

        return results

    def _validate_citations(self, answer: str,
                           contexts: List[Chunk]) -> ValidatedAnswer:
        """
        验证答案中的引用是否准确

        防止LLM编造引用
        """
        cited_sources = self._extract_citations(answer)

        for citation in cited_sources:
            source_idx = citation.source_id - 1
            if source_idx >= len(contexts):
                # 引用了不存在的来源
                answer = answer.replace(citation.text,
                                      f"{citation.text} [引用验证失败]")
            else:
                # 验证引用内容是否在原文中
                source_text = contexts[source_idx].text
                if not self._fuzzy_match(citation.content, source_text):
                    answer = answer.replace(citation.text,
                                          f"{citation.text} [需要人工验证]")

        return ValidatedAnswer(text=answer, citations=cited_sources)

# generated by hugo's coding agent

class AudioOverviewGenerator:
    """
    音频概览生成器：将文档转化为播客式对话
    """
    def __init__(self, llm, tts_engine, audio_mixer):
        self.llm = llm
        self.tts = tts_engine
        self.mixer = audio_mixer

    async def generate_overview(self, documents: List[Document],
                                style: str = "conversational",
                                duration_minutes: int = 10) -> AudioFile:
        """
        生成音频概览

        流程：
        1. 内容分析和要点提取
        2. 对话脚本生成
        3. 语音合成
        4. 音频后处理
        """
        # 步骤1：多文档摘要和要点提取
        key_insights = await self._extract_key_insights(
            documents,
            target_duration=duration_minutes
        )

        # 步骤2：生成对话脚本
        dialogue_script = await self._generate_dialogue_script(
            key_insights,
            style=style,
            duration_minutes=duration_minutes
        )

        # 步骤3：语音合成（双声道）
        audio_tracks = await self._synthesize_voices(dialogue_script)

        # 步骤4：混音和后处理
        final_audio = await self.mixer.mix(
            audio_tracks,
            add_intro=True,
            add_background_music=True,
            normalize=True
        )

        return final_audio

    async def _generate_dialogue_script(self,
                                       insights: List[Insight],
                                       style: str,
                                       duration_minutes: int) -> DialogueScript:
        """
        生成双人对话脚本

        角色设定：
        - Host: 主持人，引导对话，提出问题
        - Expert: 专家，详细解释，提供见解
        """
        # 估算字数（英文约150词/分钟，中文约250字/分钟）
        target_word_count = duration_minutes * 200  # 混合估算

        prompt = f"""基于以下要点，创建一个{duration_minutes}分钟的播客式对话脚本。

要点内容：
{self._format_insights(insights)}

对话风格：{style}
目标时长：{duration_minutes}分钟（约{target_word_count}字）

角色设定：
- **Host（主持人）**：友好、好奇、会提出听众可能关心的问题
- **Expert（专家）**：知识渊博、善于解释、使用类比和例子

脚本要求：
1. 开场：吸引听众，预告主题
2. 主体：逐步展开各个要点
   - 使用对话式语言，不是简单朗读
   - Host提问，Expert回答并展开
   - 适当使用类比、例子、反问
   - 自然的语气词（"嗯"、"对"、"确实"）
3. 收尾：总结关键点，给出行动建议

输出格式：
```json
{{
  "segments": [
    {{
      "speaker": "Host",
      "text": "欢迎来到今天的节目...",
      "emotion": "enthusiastic",
      "pause_after": 0.5
    }},
    {{
      "speaker": "Expert",
      "text": "很高兴能聊这个话题...",
      "emotion": "friendly",
      "pause_after": 0.3
    }}
  ]
}}

**技术难点**：

1. **脚本生成**：需要LLM理解"对话感"，而不是生成论文式文本
2. **情感韵律**：TTS需要支持情感控制和自然变化
3. **时长控制**：精确控制最终音频时长
4. **自然度**：添加语气词、停顿、呼吸音等细节

#### 4. 向量数据库设计

```python
# 向量索引结构
{
  "chunk_id": "doc123_chunk_5",
  "embedding": [0.123, -0.456, ...],  # 768或1536维
  "metadata": {
    "doc_id": "doc123",
    "doc_title": "机器学习入门",
    "section": "神经网络基础",
    "page": 42,
    "chunk_position": 5,
    "text": "原始文本内容...",
    "created_at": "2026-01-03T10:00:00Z"
  }
}