# AI 智能体系统架构与流程图 ## 系统概览 ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ AI 智能体系统 │ ├─────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ HTTP API ┌──────────────┐ Function Call │ │ │ 前端 UI │ ◄──────────────► │ Flask 服务端 │ ◄──────────────────┐ │ │ │ HTML/JS/CSS │ │ server.py │ │ │ │ └──────────────┘ └──────┬───────┘ │ │ │ │ │ │ │ ▼ │ │ │ ┌────────────────────────┐ │ │ │ │ Agent 核心 │ │ │ │ │ core.py │ │ │ │ │ (意图识别/路由/协调) │ │ │ │ └───────┬────────────────┘ │ │ │ │ │ │ │ ┌───────────────────────────┼───────────────────────────┐ │ │ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ │ Planner │ │ Executor │ │ RAG 系统 │ │ │ │ │ planner.py │ │ executor.py │ │ rag.py │ │ │ │ │ (计划生成) │ │ (计划执行) │ │ (知识检索) │ │ │ │ └──────────────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ │ │ │ │ │ ▼ ▼ │ │ │ ┌──────────────────┐ ┌──────────────┐ │ │ │ │ Tool Registry │ │ Retriever │ │ │ │ │ tools/ │ │ (混合检索) │ │ │ │ └────────┬─────────┘ └──────────────┘ │ │ │ │ │ │ │ ┌───────────────────────┼───────────────────────┐ │ │ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ │ │ │ 文件操作工具 │ │ 文档处理工具 │ │ LLM 生成模块 │ │ │ │ │(扫描/移动等) │ │(读取/PDF等) │ │ llm.py (本地/API) │──┘ │ │ └──────────────┘ └──────────────┘ └──────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ 数据存储层 │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ │ │ SQLite 会话 │ │ sqlite-vec │ │ 文件系统 (workspace) │ │ │ │ │ │ sessions.db │ │ vec_3.db │ │ workspace/{session_id} │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 1. 创建新会话流程 ``` 用户点击"+ 新会话" │ ▼ ┌───────────────┐ │ POST /api/ │ │ sessions │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ server.py: │ │ create_session│ └───────┬───────┘ │ ▼ ┌───────────────┐ ┌───────────────┐ │ 生成 UUID │────►│ 创建数据库记录 │ │ (session_id) │ │ sessions表 │ └───────────────┘ └───────┬───────┘ │ ▼ ┌───────────────────┐ │ 创建工作区目录 │ │ workspace/{uuid}/ │ └─────────┬─────────┘ │ ▼ ┌───────────────────┐ │ 返回 session_id │ │ 给前端 │ └───────────────────┘ │ ▼ ┌───────────────────┐ │ 前端: App.state │ │ sessionId = xxx │ │ 显示新会话界面 │ └───────────────────┘ ``` ### 涉及的代码位置： - **前端**: `src/web/static/js/app.js:84-124` (createNewSession) - **后端**: `src/web/server.py:91-114` (create_session) --- ## 2. 文件上传流程 ``` 用户拖拽或点击上传文件 │ ▼ ┌───────────────┐ │ 选择文件后 │ │ handleFiles() │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ uploadFile() │ │ FormData封装 │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ POST /api/ │ │ sessions/{id}/│ │ upload │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ server.py: │ │ upload_file() │ └───────┬───────┘ │ ├──► 保存文件到磁盘 │ workspace/{session_id}/{filename} │ ├──► 识别文件类型 │ (.pdf → pdf, .docx → word, etc.) │ └──► 写入数据库 workspace_files表 │ ▼ ┌───────────────┐ │ 返回上传结果 │ │ (文件名/大小) │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ 前端显示 │ │ 系统消息： │ │ "xxx 上传成功"│ └───────────────┘ ``` ### 涉及的代码位置： - **前端**: `src/web/static/js/app.js:133-175` (handleFiles/uploadFile) - **后端**: `src/web/server.py:153-208` (upload_file) --- ## 3. 分析文件/知识查询流程 ``` 用户输入："分析简历.pdf" │ ▼ ┌───────────────┐ │ chat.js: │ │ sendMessage() │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ POST /api/ │ │ agent/chat │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ server.py: │ │ agent_chat() │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ Agent.chat() │ │ core.py:37 │ └───────┬───────┘ │ ▼ ┌───────────────────────┐ │ _recognize_intent() │ │ 意图识别 │ │ 关键词："分析" → query │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ _handle_query() │ │ core.py:188 │ └───────────┬───────────┘ │ ├──► 扫描工作区文件 │ 获取文件名列表 │ ├──► 匹配消息中的文件名 │ "简历.pdf" in "分析简历.pdf" ✓ │ └──► 找到匹配文件！ ▼ ┌───────────────────────┐ │ _analyze_file() │ │ 直接读取文件内容 │ │ _read_file() │ │ - PDF: DocumentLoader │ │ - 其他: 直接读取文本 │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ 构建分析 Prompt │ │ "请分析以下文件内容..."│ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ LLM.chat() │ │ 调用大模型分析 │ │ - 本地模型 或 │ │ - API 调用 │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ 返回分析结果 │ │ 前端显示助手回复 │ └───────────────────────┘ ``` ### 备选路径：知识库检索（RAG） ``` 如果用户说 "搜索xxx" 但没有匹配工作区文件 │ ▼ ┌───────────────────────┐ │ RAG 检索流程 │ │ core.py:228 │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ rag.retrieve_for_query│ │ rag.py:73 │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ Retriever.retrieve_mix│ │ 混合检索： │ │ 1. 向量检索 (top_k) │ │ 2. BM25关键词检索 │ │ 3. RRF 融合排序 │ │ 4. LLM 重排序 │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ 构建上下文 Prompt │ │ 检索结果 + 用户问题 │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ LLM 生成回答 │ └───────────────────────┘ ``` ### 涉及的代码位置： - **前端**: `src/web/static/js/chat.js:47-109` (sendMessage) - **后端**: `src/web/server.py:265-285` (agent_chat) - **Agent**: `src/agent/core.py:37-90` (chat), `188-320` (_handle_query, _analyze_file) - **RAG**: `src/RAG/rag.py:73-92` (retrieve_for_query, retrieval_augmented_generate) --- ## 4. 文件操作（Plan-Execution）流程 ``` 用户输入："整理文件，按类型分类" │ ▼ ┌───────────────┐ │ Agent.chat() │ └───────┬───────┘ │ ▼ ┌───────────────────────┐ │ _recognize_intent() │ │ 关键词："整理" → │ │ file_operation │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ Planner.create_plan() │ │ planner.py │ └───────────┬───────────┘ │ ├──► 分析工作区现状 │ (有哪些文件) │ ├──► LLM 生成计划 │ 描述 + 步骤列表 │ └──► 标记危险操作 move/rename/delete → safe=false │ ▼ ┌───────────────────────┐ │ 返回 Plan 结构 │ │ { │ │ intent: "organize" │ │ description: "..." │ │ steps: [...], │ │ warning: "..." │ │ } │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ 前端显示计划确认弹窗 │ │ App.showPlanModal() │ │ 显示步骤和安全警告 │ └───────────┬───────────┘ │ ▼ ┌───────────────┐ │ 用户点击确认？ │ └───────┬───────┘ │ ┌───────┴───────┐ │ │ 是 否 │ │ ▼ ▼ ┌──────────┐ ┌──────────┐ │ 执行计划 │ │ 取消操作 │ └────┬─────┘ └──────────┘ │ ▼ ┌─────────────────┐ │ POST /api/agent/│ │ execute │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Executor.execute│ │ executor.py │ └────────┬────────┘ │ ├──► 遍历计划步骤 │ ├──► 调用 ToolRegistry │ 执行具体工具 │ └──► 收集执行结果 │ ▼ ┌─────────────────┐ │ 返回执行结果 │ │ 格式化为消息 │ │ "✅ 执行完成..." │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ 前端显示结果 │ │ 刷新文件列表 │ └─────────────────┘ ``` ### 涉及的代码位置： - **Agent**: `src/agent/core.py:78-134` (execute_plan) - **Planner**: `src/agent/planner.py` (create_plan) - **Executor**: `src/agent/executor.py` (execute) - **Tools**: `src/agent/tools/` (ToolRegistry, file_operations) --- ## 5. 生成思维导图流程 ``` 用户输入："生成思维导图" 或点击工具栏"思维导图"按钮 │ ▼ ┌───────────────┐ │ 意图识别 │ │ type: mindmap │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ _handle_mindmap│ │ core.py:206 │ └───────┬───────┘ │ ▼ ┌───────────────────────┐ │ MindmapGenerator │ │ knowledge/mindmap_ │ │ generator.py │ └───────────┬───────────┘ │ ├──► 扫描工作区文件 │ ├──► 提取知识实体 │ (时间、主题等) │ └──► 构建层级结构 │ ▼ ┌───────────────────────┐ │ 返回 mindmap 数据 │ │ { │ │ root: "知识图谱" │ │ children: [...] │ │ timeline: [...] │ │ } │ └───────────┬───────────┘ │ ▼ ┌───────────────────────┐ │ 前端 Mindmap.show() │ │ mindmap.js │ │ 渲染可视化图表 │ └───────────────────────┘ ``` --- ## 6. 浏览工作区流程 ``` 用户点击"📂 浏览工作区" │ ▼ ┌───────────────┐ │ browseWorkspace│ │ app.js:318 │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ GET /api/ │ │ sessions/{id}/│ │ files │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ server.py: │ │ list_files() │ │ 查询数据库 │ └───────┬───────┘ │ ▼ ┌───────────────────────┐ │ 前端按类型分组显示 │ │ 📄 PDF (2) │ │ 📝 Word (1) │ │ 📃 文本 (3) │ │ 显示：文件名/大小/时间 │ └───────────────────────┘ ``` --- ## 7. 数据流总览 ### 7.1 会话数据流 ``` 创建会话 ──► sessions.db (sessions表) │ ├──► session_id (UUID) ├──► title ├──► created_at └──► context_json (对话历史) ``` ### 7.2 文件数据流 ``` 上传文件 ──► 1. 保存到磁盘 │ workspace/{session_id}/ │ └── filename.pdf │ └──► 2. 记录到数据库 workspace_files表 ├──► id ├──► session_id ├──► original_name ├──► stored_path ├──► file_type ├──► file_size └──► processed (0/1) ``` ### 7.3 LLM 调用数据流 ``` 用户输入 ──► Intent识别 ──► 需要LLM？ │ ┌───────┴───────┐ │ │ 是 否 │ │ ▼ ▼ ┌───────────────┐ ┌───────────────┐ │ llm.chat() │ │ 直接返回 │ │ │ │ (简单问候等) │ ├──► use_local? │ └───────────────┘ │ ├──► true ──► 本地 transformers │ 模型推理 │ └──► false ──► API调用 DashScope ``` --- ## 8. 安全机制流程 ``` 文件操作请求 │ ▼ ┌───────────────┐ │ Planner 生成 │ │ 执行计划 │ └───────┬───────┘ │ ├──► 标记安全等级 │ safe: true/false │ └──► 危险操作加警告 warning: "..." │ ▼ ┌───────────────┐ │ 用户确认弹窗 │ │ 显示警告信息 │ └───────┬───────┘ │ ▼ ┌───────────────┐ │ Executor 执行 │ └───────┬───────┘ │ ├──► 路径安全检查 │ 防止目录遍历 │ └──► 限制在工作区内 workspace/{session_id}/ │ ▼ ┌───────────────┐ │ 记录操作日志 │ │ operation_logs│ │ 表 │ └───────────────┘ ``` --- ## 9. 模块调用关系 ``` ┌──────────────────┐ │ server.py │ │ (Flask 入口) │ └────────┬─────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ ▼ ▼ ▼ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ sessions │ │ upload │ │ agent (chat) │ │ (会话管理) │ │ (文件上传) │ │ (Agent对话) │ └────────────────┘ └────────────────┘ └────────┬───────┘ │ ┌─────────────────────────────┼─────────────┐ │ │ │ ▼ ▼ ▼ ┌────────────────┐ ┌────────────────┐ ┌──────────┐ │ Agent.core │ │ Agent.planner │ │ Agent. │ │ (意图识别/路由) │ │ (计划生成) │ │ executor │ └───────┬────────┘ └────────────────┘ └────┬─────┘ │ │ ┌───────────┼───────────┐ ┌──────────┼──────────┐ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │_handle_ │ │_handle_ │ │_handle_ │ │ Tool │ │ File │ │ 其他 │ │query │ │summary │ │mindmap │ │ Registry │ │ Operations│ │ 工具 │ └────┬─────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ RAG 系统 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐ │ │ │ rag.py │ │ retriever.py │ │ embedding.py │ │ llm.py │ │ │ │ (RAG主类) │ │ (混合检索) │ │ (向量化) │ │ (LLM调用)│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ 数据存储 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │ │ sessions.db │ │ vec_3.db │ │ workspace/ │ │ │ │ (SQLite) │ │ (sqlite-vec) │ │ (文件系统) │ │ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 10. 时序图示例：完整对话流程 ``` 用户 前端 Flask Agent.core Planner Executor Tools DB │ │ │ │ │ │ │ │ │──发送────►│ │ │ │ │ │ │ │ 消息 │ │ │ │ │ │ │ │ │──POST──────►│ │ │ │ │ │ │ │ /agent/chat │ │ │ │ │ │ │ │ │──────────►│ │ │ │ │ │ │ │ │─意图识别───►│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │◄─返回plan──│ │ │ │ │ │ │ │ (file_op) │ │ │ │ │ │ │◄─────────│ │ │ │ │ │ │◄─返回plan──│ │ │ │ │ │ │ │ │ │ │ │ │ │ │◄─显示────│ │ │ │ │ │ │ │ 计划确认 │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │──确认────►│ │ │ │ │ │ │ │ │──POST──────►│ │ │ │ │ │ │ │ /agent/exec │ │ │ │ │ │ │ │ │──────────►│ │ │ │ │ │ │ │ │────────────►│ │ │ │ │ │ │ │ │─遍历步骤─►│ │ │ │ │ │ │ │ │─调用工具─►│ │ │ │ │ │ │ │ │─读文件─►│ │ │ │ │ │ │ │◄───────│ │ │ │ │ │ │◄─返回────│ │ │ │ │ │ │◄────────│ │ │ │ │ │ │────────────►│ │ │ │ │ │ │◄─────────│ │ │ │ │ │ │◄─返回结果──│ │ │ │ │ │ │ │ │ │ │ │ │ │ │◄─显示────│ │ │ │ │ │ │ │ 执行结果 │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ``` --- ## 附录：核心文件功能速查表 | 文件路径 | 功能描述 | 关键方法/类 | |---------|---------|------------| | `src/web/server.py` | Flask 服务端，HTTP API 入口 | `create_session()`, `upload_file()`, `agent_chat()` | | `src/web/static/js/app.js` | 前端主逻辑，状态管理 | `App.init()`, `createNewSession()`, `browseWorkspace()` | | `src/web/static/js/chat.js` | 前端对话模块 | `Chat.sendMessage()`, `Chat.addMessage()` | | `src/agent/core.py` | Agent 核心，意图识别和路由 | `Agent.chat()`, `_recognize_intent()`, `_handle_query()` | | `src/agent/planner.py` | 计划生成器 | `Planner.create_plan()` | | `src/agent/executor.py` | 计划执行器 | `Executor.execute()` | | `src/agent/tools/` | 工具注册表和实现 | `ToolRegistry`, `file_operations.py` | | `src/RAG/rag.py` | RAG 主类 | `RAG.retrieve_for_query()`, `retrieval_augmented_generate()` | | `src/RAG/llm_generate/llm.py` | LLM 调用封装 | `LLM.chat()`, `_chat_local()`, `_chat_api()` | | `src/RAG/retrieve/retriever.py` | 混合检索 | `Retriever.retrieve_mix()` | | `src/RAG/build_index/embedding.py` | 向量化 | `EmbeddingGenerator.encode()` |