1. 🚀 快速上手
Yudo 是一个面向水利工程的 AI 知识库助手，核心能力是多模态文献检索与学术问答。拥有 4 项工具技能，由 LLM 自主判断何时调用。
2. 🧠 核心架构
Yudo 采用 三层 Agent 架构：LLM ↔ Host（app.py）↔ MCP Server（mcp_server.py）+ Host 工具
与普通 RAG 不同，Yudo 没有硬编码分支——所有行为由 LLM 自主决策。当 LLM 返回 tool_calls 时，Host 根据工具名路由到 MCP 或 Host 执行器，结果以 tool role 发回 LLM 进行第二轮生成。
MCP 工具（mcp_server.py）：需要调用 LLM 子 Agent 或访问向量库的服务端能力。
Host 工具（app.py）：直接操作用户状态，无需额外进程。
3. 🔍 多模态 RAG 工作原理
3.1 索引阶段（上传/重建索引时）
上传文件后，系统根据文件类型选择对应解析器，生成文本嵌入向量。PDF 额外支持页面图像多模态嵌入：
3.2 检索阶段（用户提问时）
3.3 向量空间可视化
点击侧边栏的 【向量】 按钮打开 3D 可视化页面，可直观查看向量空间分布：
- 文本块：按文件着色，使用标准色板（蓝、绿、橙、紫等 10 色循环）
- 图像块：在文件基色上叠加
#FF6F00暖橙色（blend 45%），尺寸更大（0.14 vs 0.08），一眼可辨 - 统计栏：显示
X 个片段（Y 文本 · Z 图片）· N 个文件 - 文件面板：每文件旁显示
(5文+2图)明细
PCA 降维将 2048 维向量投影到 3D 空间。同主题的文本/图像块会在空间中聚集，便于理解检索相似性。
文本和图像的向量分数分布不同——文本块可以同时参与 BM25 关键词匹配获得额外加分，而图像块只能靠向量相似度。混在一起用同一个阈值过滤不够精细。分开后可以分别控制权重和阈值，也避免了图像占位符 [第N页图片] 污染 BM25 索引。
4. 🔧 工具清单
4.1 📡 MCP 工具（mcp_server.py 独立进程）
| 工具名 | 功能 | 参数 |
|---|---|---|
search_knowledge_base |
语义检索知识库，自动经过子 Agent 优化流程（AI 空间判断 → 关键词优化 → HyDE → 混合检索 → 摘要提取）。支持文献/代码双空间，AI 自动判断检索范围 | query：搜索语句 |
read_knowledge_file |
根据文件名读取知识库中的文件全文（截断至 1 万字符） | filename：含扩展名的文件名 |
list_knowledge_folder |
浏览知识库目录结构（最多 3 层），含文件大小 | path（可选）：子路径 |
4.2 🏠 Host 工具（app.py 内置）
| 工具名 | 功能 | 参数 |
|---|---|---|
write_note |
将文本写入 Yudo 的记忆笔记（user_preferences.md） |
text：自由文本 |
4.3 子 Agent 搜索流程
search_knowledge_base 始终经过子 Agent 处理：
- AI 空间判断：LLM 分析问题属于"文献空间"(document)还是"代码空间"(code)，决定检索范围
- 关键词优化：LLM 分析原始问题，改写为更适合向量检索的语句
- HyDE 假想文档（可选）：LLM 生成一段可能的答案段落，用于增强向量匹配
- 混合检索：向量检索 + BM25 关键词检索，分数融合。仅在指定空间中搜索
- 跨空间 fallback：若当前空间无结果，自动尝试另一空间
- 摘要提取：逐篇提取摘要/引言/结论/匹配片段
- 结构化输出：返回带相关度评分的文献摘要给主 Agent
PDF、Word、TXT 等学术资料归入 文献空间（document）；Python、JavaScript、C++ 等编程代码归入 代码空间（code）。检索时 AI 自动判断问题类型，只搜索相关空间，提升检索精度。
5. 🖥️ 界面说明
5.1 主界面布局
5.2 工具调用气泡
Yudo 调用工具时，气泡内实时显示当前活动（带旋转动画），如：
- 🔍 正在搜索知识库 · 关键词
- 📖 正在读取文件 · xxx.pdf
- 📂 正在浏览目录
LLM 开始输出文本后，状态标记为"完成"。最终回复下方保留可折叠的调用历史。
5.3 设置面板（⚙）
| 设置项 | 说明 | 默认值 |
|---|---|---|
| 主题配色 | 5 种主题切换（学术蓝/深海藏蓝/青屿松石/晴空浅蓝/竹影青雾） | 默认 (学术蓝) |
| LLM 模型 | DeepSeek 模型名称（支持运行时修改，MCP 子进程自动同步） | deepseek-v4-flash |
| 携带上下文条数 | 每轮携带的历史消息数 | 20 |
| 检索上限 (TOP_K) | 每次检索返回的片段数 | 5 |
| 相似度阈值 | 低于此分数的片段被过滤（滑块调整，主题色填充） | 0.30 |
点击"保存"按钮后，配置持久化到 search_config.json。MCP Server 通过 _get_runtime_model() 读取同一文件，自动同步模型名变更。
5.4 📄 对话导出
聊天头部新增 📄 按钮，点击可将当前会话的全部对话记录导出为 Markdown 文件，便于保存和分享问答结果。
5.5 📚 向量空间可视化
在聊天头部点击 坐标轴图标 打开向量可视化页面：
- 左右双 3D 场景：左侧显示文献空间点云，右侧显示代码空间点云，各自独立 PCA 降维
- 双侧文件面板：左侧文献列表、右侧代码列表，可分别隐藏/展开
- 颜色标识：每个文件分配独立颜色，图片块叠加暖橙色区分
5.6 📖 阅读器支持
- 语法高亮：代码文件（.py/.js/.ts/.java/.cpp/.css 等）使用 highlight.js 自动着色
- 主题联动：阅读器自动继承主页的主题配色设置（深海藏蓝/青屿松石等）
- 公式渲染：KaTeX 渲染 LaTeX 数学公式
- PDF 阅读：内嵌 PDF.js 渲染器，支持缩放/翻页
6. 🧩 记忆与角色系统
所有配置统一存放在 role_and_memory/ 文件夹：
| 文件 | 内容 | 管理者 |
|---|---|---|
yudo_persona.md | AI Agent 人设、技能、行为准则 | 可手动编辑 |
context.json | 对话历史（最近 200 条） | 系统自动管理 |
user_preferences.md | 记忆笔记（带时间戳的自由文本） | Yudo 通过 write_note 写入 |
6.1 System Prompt 构成
编辑 role_and_memory/yudo_persona.md，重启后生效。
7. 📤 文件管理
7.1 支持格式
| 类别 | 格式 |
|---|---|
| 文档 | PDF DOCX DOC |
| 文本 | TXT MD |
| Python代码 | PY |
| JavaScript代码 | JS |
| TypeScript代码 | TS |
| Java代码 | JAVA |
| C/C++代码 | CPP C H |
| HTML文件 | HTML HTM |
| CSS文件 | CSS |
| 数据 | JSON XML CSV XLSX |
| 演示 | PPT PPTX |
7.2 分块策略
不同类型文件采用不同的分块策略：
- 文献文件（PDF/DOCX/TXT/MD）：语义分块，按章节标题和段落边界切分，200-1200 字符/块，带句子重叠
- 代码文件（PY/JS/TS/JAVA/CPP/C/CSS/HTML）：结构分块，按函数/类/方法边界切分，优先保持函数完整性
7.3 重建索引
上传新文件后，系统自动建立索引。如需重建全部索引，在设置面板点击"重建索引"：
50 篇 PDF 含多模态嵌入可能需要数分钟。重建过程在后台异步执行，不影响其他操作。
8. ⚙ 配置说明
8.1 核心配置（config.py）
| 配置项 | 说明 | 默认值 |
|---|---|---|
DEEPSEEK_API_KEY | DeepSeek API 密钥 | 硬编码（生产环境用环境变量覆盖） |
DEEPSEEK_MODEL | 默认 LLM 模型名 | deepseek-v4-flash |
ARK_API_KEY | 火山引擎 Ark API 密钥 | 硬编码 |
ARK_EMBEDDING_MODEL | 多模态嵌入模型 | doubao-embedding-vision-251215 |
ARK_EMBEDDING_DIM | 嵌入向量维度 | 2048 |
MAX_PAGE_IMAGES_PER_DOC | 每个 PDF 最多嵌入页数 | 30 |
ENABLE_HYDE | 是否启用 HyDE 假想文档 | True |
HYBRID_VECTOR_WEIGHT | 向量检索权重 | 0.6 |
HYBRID_BM25_WEIGHT | BM25 检索权重 | 0.4 |
8.2 运行时配置（search_config.json）
通过设置面板修改，持久化到 search_config.json：
| 字段 | 说明 | 默认值 |
|---|---|---|
model | 运行时 LLM 模型名（MCP Server 自动同步） | deepseek-v4-flash |
top_k | 检索返回片段数 | 5 |
similarity_threshold | 相似度阈值 | 0.3 |
context_count | 携带上下文条数 | 20 |
8.3 权限说明
| 操作 | 权限要求 |
|---|---|
| 对话 / 搜索 / 上传文件 | 登录用户 |
| 修改设置 / 重建索引 | 登录用户 |
| 开发者统计 | 白名单账号 |
9. ❓ 常见问题
Yudo 是 Agent，不是 pipeline。普通 RAG 是固定流程：搜索→拼接→回答。Yudo 自主判断要不要搜索、用什么词搜索、搜完是否需要读全文、是否需要记录信息。没有硬编码分支。
Yudo 的嵌入模型（Ark doubao-embedding-vision）能同时处理文本和图片，将它们编码到同一个向量空间。上传 PDF 时，每一页会被渲染成图片并生成嵌入向量。检索时，用户的文字查询会同时与文本块和图片块做相似度匹配。但 Yudo 的 LLM（DeepSeek）是纯文本模型，不会"看图"——它只知道"第 N 页有一张匹配的图片"。
每次调用 search_knowledge_base 都走子 Agent 流程。子 Agent 优化关键词 → HyDE 生成假想文档 → 混合检索 → 提取摘要 → 返回结构化结果，即使只匹配到 1 篇也走完整流程以保证质量。
设置面板保存模型名后，写入 search_config.json。MCP Server 通过 _get_runtime_model() 读取该文件，子 Agent 的关键词优化和 HyDE 调用会自动使用新模型名。
不会。Yudo 基于 DeepSeek 内置知识 + 本地知识库文件回答。
运行 backup.sh 脚本自动备份知识库文件、向量索引、配置和记忆数据到 backup 目录。
上传文件时，系统根据扩展名自动归类：PDF/DOCX/TXT/MD 等归入文献空间，PY/JS/TS/JAVA 等代码文件归入代码空间。检索时 AI 判断问题类型，只搜索相关空间，避免文献结果干扰代码查找。如果一个空间无结果，系统会自动尝试另一个空间。
不一样。文献文件按章节和段落边界做语义分块（200-1200 字符）。代码文件则按函数、类、方法边界做结构分块，每个函数/类独立成块，保证代码逻辑完整性。支持 Python、JavaScript、TypeScript、Java、C/C++、HTML、CSS 七种语言。