智能Agent

使用AI辅助完成的智能体小项目。 一个基于 Flask + 原生 JavaScript 的全栈智能对话系统，整合硅基流动 Qwen 大模型、秘塔联网搜索、本地知识库以及 ReAct 多工具推理能力，提供科技风的响应式界面与可持久化的多轮会话体验。

✨ 功能特性

• 🤖 AI 对话: 调用 SiliconFlow Qwen/Qwen3 系列模型，自动裁剪上下文，支持多轮连续交流。
• 🚀 ReAct 多工具推理: 面向 /api/react-chat 的思考-行动循环，能够在一次请求中串联多次工具调用。
• 🧠 智能意图识别（新增）: 基于关键词与正则模式的轻量级意图分类器，自动识别用户意图并推荐最佳工具，提升 ReAct 模式的决策效率。
• 🧩 插件化工具体系: 启动时自动加载 ReAct_Plugins/ 目录下的 Python 插件，无需修改核心代码即可扩展能力。
• 🔍 联网搜索: 集成秘塔搜索 API，可按需为用户提问附带实时检索结果。
• 📚 知识库检索: 使用 Qwen 嵌入模型构建本地向量库，在回答时注入命中文档片段。
• 💾 会话持久化: 采用 SQLite 保存会话历史，提供 /api/sessions 列表与前端会话管理界面。
• 📊 结构化日志（新增）: 详细的对话跟踪与工具调用记录，支持后期分析与性能优化。
• ⚡ 性能优化: 自动调整上下文长度与响应策略，平衡回答质量与响应速度。
• 🛡️ 安全边界（新增）: Python 解释器工具实施严格的安全限制，防止文件系统访问与系统命令执行。
• 📱 现代化界面: 深色科技风设计，居中式欢迎界面，支持会话导出、快捷键与流畅动画。

🚀 快速开始

1. 安装依赖

git clone <your-repo-url>
cd Mini-Project

# 可选：创建虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

2. 配置环境变量

在项目根目录创建 .env 文件（可参考 env.example）：

# 必填
SILICONFLOW_TOKEN=your_siliconflow_token
SECRET_KEY=your_secret_key

# 可选，未配置时采用内置示例值
METASO_TOKEN=mk-53C5D736E10D8F22D8991EC28003AD31

# 知识库与调优选项
KNOWLEDGE_AUTO_BUILD=true
KNOWLEDGE_TOP_K=5
CONVERSATION_DB_PATH=conversation_history.db

3. 启动服务

python app.py

默认服务运行在 http://localhost:5000。

⚙️ 环境变量说明

变量名	描述	必需	默认值
SILICONFLOW_TOKEN	硅基流动 API 密钥	是	-
SECRET_KEY	Flask 会话密钥	是	-
METASO_TOKEN	秘塔搜索 API 密钥	否	示例密钥
CONVERSATION_DB_PATH	会话历史 SQLite 路径	否	./conversation_history.db
KNOWLEDGE_BASE_PATH	知识库根目录	否	./Knowledge_Base
KNOWLEDGE_SOURCE_SUBDIR	知识库文档子目录	否	documents
KNOWLEDGE_INDEX_FILENAME	向量索引文件名	否	index.json
KNOWLEDGE_EMBEDDING_MODEL	嵌入模型名称	否	Qwen/Qwen3-Embedding-4B
KNOWLEDGE_CHUNK_SIZE	文本分块字符数	否	400
KNOWLEDGE_CHUNK_OVERLAP	分块重叠字符数	否	80
KNOWLEDGE_TOP_K	默认返回片段数量	否	5
KNOWLEDGE_AUTO_BUILD	首次请求自动构建索引	否	false
PYTHON_SANDBOX_ENABLED	预留的代码沙盒开关	否	false

使用的 AI 模型

• 普通对话模式 (/api/chat): Qwen/Qwen3-Omni-30B-A3B-Instruct
• ReAct 推理模式 (/api/react-chat): Qwen/Qwen3-Next-80B-A3B-Instruct（更强的推理能力）
• 知识库嵌入: Qwen/Qwen3-Embedding-4B

注意事项：

• Google 翻译工具使用 deep-translator 库，需要可访问 Google 翻译服务的网络环境。
• ReAct 模式使用更大的模型以获得更好的推理和工具调用能力，但响应时间略长于普通模式。
• 如果您使用 Python 3.13+，请确保已安装 deep-translator==1.11.4 而非旧版的 googletrans。

📁 项目结构

Mini-Project/
├── app.py                          # Flask 主应用入口（模块化重构，仅~120行）
├── config.py                       # 配置管理
├── 
├── core/                           # 核心功能模块 ⭐ 新增
│   ├── __init__.py
│   ├── ai_agent.py                 # AI代理类
│   └── conversation_store.py       # 对话存储和会话管理
├── 
├── api/                            # API蓝图模块 ⭐ 新增
│   ├── __init__.py
│   ├── chat.py                     # 聊天API (含ReAct模式)
│   ├── sessions.py                 # 会话管理API
│   ├── filebox.py                  # 文件盒子API
│   └── memorybox.py                # 记忆盒子API
├── 
├── services/                       # 服务层模块 ⭐ 新增
│   ├── __init__.py
│   └── initialization.py           # 所有服务的初始化逻辑
├── 
├── utils/                          # 工具函数模块 ⭐ 新增
│   ├── __init__.py
│   ├── helpers.py                  # 辅助函数
│   └── logging_utils.py            # 日志工具
├── 
├── react_agent.py                  # ReAct 推理循环实现
├── intent_classifier/              # 意图识别分类器
├── react_plugin_loader.py          # 插件自动加载与注册
├── react_plugins/                  # 工具插件目录（自动扫描）
│   ├── calculator_tool.py
│   ├── knowledge_search_tool.py
│   ├── python_interpreter_tool.py.example
│   ├── text_tool.py
│   ├── time_tool.py
│   ├── translate_tool.py
│   ├── web_search_tool.py
│   ├── example_plugin.py.example
│   └── README.md                   # 插件开发指南
├── knowledge_base/
│   ├── __init__.py
│   ├── build_index.py              # 向量索引构建脚本
│   ├── documents/                  # 知识库原始文档
│   │   ├── deepseek.md
│   │   └── History.md
│   └── index.json                  # 默认索引缓存
├── logs/                           # 日志目录
│   └── conversation.log            # 结构化对话日志
├── templates/
│   └── index.html                  # 前端页面
├── static/
│   ├── css/style.css
│   └── js/main.js
├── README/                         # 文档目录
│   ├── QUICK_START_REACT.md
│   ├── REACT_MODE_GUIDE.md
│   ├── PLUGIN_QUICK_START.md
│   ├── HOW_TO_ADD_TOOLS.md
│   └── OPTIMIZATION_GUIDE.md
├── test/                           # 测试文件
│   ├── test_react_agent.py
│   ├── test_plugin_loader.py
│   └── test_integration.py
├── requirements.txt
├── env.example
├── conversation_history.db         # 首次运行后自动创建
├── PROJECT_STRUCTURE.md            # 项目结构详细说明 ⭐ 新增
├── REFACTORING_GUIDE.md            # 重构指南 ⭐ 新增
└── README.md

🎉 项目已进行模块化重构！

• app.py 从 1658行 精简至 ~120行
• 采用清晰的分层架构（核心层、API层、服务层、工具层）
• 更好的代码组织和可维护性

🧠 ReAct 模式与插件系统

模式简介

• 默认启用: 前端默认使用 ReAct 推理模式（/api/react-chat），自动进行多步骤推理和工具调用。
• 推理循环: 后端基于 ReActAgent 执行 "Thought → Action → Observation" 循环，默认最多 6 次迭代。
• 集成意图识别: 自动分析用户问题的意图类型（计算、搜索、翻译等），并推荐最合适的工具，提高首次工具选择的准确率。
• 循环检测: 自动识别重复的工具调用模式，避免陷入无效循环，提示 Agent 尝试其他方法。
• 安全防护: 严格限制 Python 解释器等高风险工具的使用范围，拒绝文件系统、网络和系统命令相关操作。
• 可视化推理: 工具调用记录和意图分析结果会在前端自动展开显示，便于理解 Agent 的完整思考过程。

接口定义

POST /api/react-chat
{
    "message": "用户问题",
    "session_id": "可选，会话 ID",
    "max_iterations": 6,
    "include_history": false
}

返回示例：

{
  "response": "最终回答",
  "session_id": "6f0c7d05-6c24-4da3-b802-4f6d5b4a2c9d",
  "timestamp": "2024-06-12T12:34:56.789123",
  "react_details": {
    "total_iterations": 3,
    "iterations": [
      {
        "iteration": 1,
        "thought": "用户想要搜索最新信息，我需要使用 web_search 工具",
        "action": {"tool": "web_search", "parameters": {"query": "示例"}},
        "observation": "{\"success\": true, \"content\": \"...\"}"
      }
    ],
    "tool_calls": [
      {"tool": "web_search", "parameters": {"query": "示例"}, "result": {...}}
    ],
    "intent_analysis": {
      "intent": "web_search",
      "confidence": 0.7,
      "reason": "可能需要联网搜索最新信息；命中关键词「搜索」",
      "suggested_tools": ["web_search"],
      "should_use_tool": true,
      "evidence": ["命中关键词「搜索」"]
    }
  }
}

插件机制

• 插件文件放在 ReAct_Plugins/ 目录下，需定义执行函数与 TOOL_CONFIG 配置字典。
• 启动时自动扫描 .py 文件并注册到 Agent，无需修改主程序代码。
• 通过设置 TOOL_CONFIG["enabled"] = False 可以临时禁用某个工具，或调整工具参数与描述。
• 详细的插件开发指南请参考 ReAct_Plugins/README.md 与 example_plugin.py.example。

内置工具一览

工具名称	说明	主要参数	意图类型
web_search	调用秘塔联网搜索最新信息	query, size	web_search
knowledge_search	本地知识库语义检索	query, top_k	knowledge_search
time_tool	返回当前日期与时间信息	timezone	-
calculator	安全数学表达式计算（支持三角函数、对数等）	expression	math_calculation
text_processor	文本统计 / 大小写转换 / 反转	text, operation	text_processing
translator	基于 deep-translator 的多语言翻译	text, target_lang, source_lang	translation
python_interpreter	受限 Python 代码沙盒（仅限纯计算）	code, timeout	python_execution

说明: "意图类型" 列表示意图识别器会为该意图推荐的工具。当用户输入匹配对应意图时，ReAct Agent 会优先考虑使用该工具。

更多示例可参考 ReAct_Plugins/README.md 与 example_plugin.py.example。

最佳实践

ReAct 模式使用建议

前端默认启用 ReAct 模式，适合绝大多数场景。系统会智能判断是否需要调用工具：

• ✅ 自动调用工具的场景：

  • 需要多步骤推理的复杂问题
  • 需要获取实时数据（搜索、天气、新闻等）
  • 需要精确计算（数学、统计、公式等）
  • 需要语言处理（翻译、文本分析等）
  • 需要查询内部知识库

• ✨ 直接回答的场景：

  • 简单的问答或闲聊
  • 纯文本生成和创作
  • 已有足够信息的问题
  • 意图识别认为无需工具的场景

优化技巧

1. 清晰表达意图：使用"搜索"、"计算"、"翻译"等关键词可帮助系统快速识别需求。
2. 提供足够上下文：完整描述问题背景，有助于 Agent 做出更准确的判断。
3. 合理设置迭代次数：默认 6 次迭代适合大多数场景，API 调用时可根据任务复杂度调整。
4. 查看推理轨迹：前端会自动展开推理过程，了解 Agent 的思考路径有助于优化提问方式。
5. 利用意图分析：查看意图识别结果（在推理详情中），了解系统如何理解您的问题。

🧠 智能意图识别系统

工作原理

项目集成了轻量级的意图识别分类器 (intent_classifier.py)，通过关键词匹配和正则表达式模式识别用户意图，并在 ReAct 模式下为 Agent 提供决策参考。

支持的意图类型

意图类型	描述	触发关键词示例	推荐工具
math_calculation	数学计算或公式推断	计算、求和、百分比、平均	calculator
knowledge_search	内部知识库查询	知识库、内部文档、政策、流程	knowledge_search
web_search	联网搜索最新信息	搜索、查一下、最新、新闻	web_search
translation	文本翻译需求	翻译、translate、英文怎么说	translator
text_processing	文本统计或格式化	统计字数、转大写、反转文本	text_processor
python_execution	Python 代码执行	运行python、执行代码、print(	python_interpreter
general_chat	通用对话（默认）	未命中特定规则	-

意图分析结果示例

{
  "intent": "web_search",
  "confidence": 0.7,
  "reason": "可能需要联网搜索最新信息；命中关键词「搜索」",
  "suggested_tools": ["web_search"],
  "should_use_tool": true,
  "evidence": ["命中关键词「搜索」"]
}

与 ReAct 的集成

• 自动注入上下文: 意图分析结果以系统消息形式提供给 LLM，帮助其快速选择合适的工具。
• 提升首次准确率: 减少试错次数，特别是在明确的计算、搜索等场景下效果显著。
• 灵活覆盖: Agent 仍可根据实际情况选择其他工具或直接回答，意图识别仅作为参考建议。

自定义意图规则

您可以在 intent_classifier.py 中的 IntentClassifier.__init__() 方法里添加新的 IntentRule：

IntentRule(
    intent="your_custom_intent",
    description="您的意图描述",
    keywords=("关键词1", "关键词2"),
    regex=(r"正则模式1", r"正则模式2"),
    suggested_tools=("tool_name",),
    negative_keywords=("排除词",)
)

💬 会话与历史记录

• 对话消息使用 SQLite (conversation_history.db) 持久化存储，防止浏览器刷新导致记录丢失。
• 前端支持会话列表展示、历史会话加载、当前会话导出与清空等功能。
• 相关接口：
  • GET /api/sessions：返回当前客户端的会话摘要列表。
  • GET /api/sessions/<session_id>：返回指定会话的完整消息流。

📊 结构化日志系统

日志功能

项目实现了详细的对话跟踪与分析系统，所有请求、工具调用和响应都会被记录到 logs/conversation.log。

日志类型

1. 对话请求日志 (chat_request/react_request)

   • 记录客户端 ID、会话 ID、用户输入、请求参数（迭代次数、历史包含等）
   • 便于追踪用户行为和功能使用情况

2. 对话响应日志 (chat_response/react_response)

   • 记录响应内容长度、工具调用次数、意图分析结果
   • 用于性能分析和模型行为监控

3. 结构化追踪 (conversation_trace)

   • 完整的 JSON 格式日志，包含请求全生命周期信息
   • 支持后期数据分析、问题诊断和模型优化

日志示例

2024-06-12 10:30:15 [INFO] conversation: [react_request] client=abc-123 session=def-456 include_history=False max_iterations=6 message="今天北京天气怎么样？"
2024-06-12 10:30:20 [INFO] conversation: [react_response] client=abc-123 session=def-456 iterations=2 tool_calls=1:web_search intent=web_search@0.70/tool=True answer_length=156 answer_preview="根据最新信息，北京今天多云转晴..."
2024-06-12 10:30:20 [INFO] conversation: [conversation_trace] {"event": "react_chat", "client_id": "abc-123", "session_id": "def-456", ...}

日志配置

• 自动轮转: 日志文件达到 2MB 时自动轮转，保留最近 5 个备份文件
• 编码: UTF-8 编码，支持中文内容完整记录
• 级别: INFO 级别记录正常操作，ERROR 级别记录异常情况

🔌 API 接口说明

前端默认行为

前端界面默认使用 ReAct 推理模式（/api/react-chat），自动启用联网搜索、知识库检索和多工具推理能力，为用户提供最强大的 AI 能力。

POST /api/react-chat（推荐，前端默认）

这是前端默认使用的接口，提供完整的推理和工具调用能力。

请求示例：

{
  "message": "帮我搜索一下深圳今天的天气",
  "session_id": "可选",
  "max_iterations": 6,
  "include_history": false
}

参数说明：

• message: 用户问题（必需）
• session_id: 会话 ID，可复用已有会话；若缺失则自动生成 UUID
• max_iterations: 最大推理迭代次数，默认 6 次
• include_history: 是否包含历史对话上下文，默认 false

成功响应：

{
  "response": "根据最新信息，深圳今天多云转晴，气温 25-30°C...",
  "session_id": "abc-123-def-456",
  "timestamp": "2024-06-12T12:00:00.000Z",
  "react_details": {
    "total_iterations": 2,
    "iterations": [...],
    "tool_calls": [...],
    "intent_analysis": {...}
  }
}

POST /api/chat（传统模式）

普通对话模式，适合不需要工具调用的简单对话场景。

请求示例：

{
  "message": "你好",
  "use_search": true,
  "use_knowledge": true,
  "knowledge_top_k": 3,
  "fast_mode": false,
  "session_id": "可选"
}

参数说明：

• use_search: 是否执行联网搜索并将结果注入上下文
• use_knowledge: 是否追加知识库检索结果
• fast_mode: 是否启用快速模式（减少上下文和输出长度）
• session_id: 会话 ID

成功响应：

{
  "response": "AI 回复内容",
  "session_id": "返回的会话 ID",
  "timestamp": "2024-06-12T12:00:00.000Z",
  "knowledge": [
    {
      "id": "doc-1",
      "score": 0.81,
      "source": "documents/law.txt",
      "content": "..."
    }
  ]
}

错误响应：发生错误时返回 {"error": "错误信息"} (HTTP 500)

📚 知识库使用指南

1. 将知识文档（支持 .txt、.md、.json 问答格式等）放入 Knowledge_Base/documents/。
2. 首次使用可运行 python -m Knowledge_Base.build_index --refresh 手动构建索引，或在 .env 中启用 KNOWLEDGE_AUTO_BUILD=true 让服务在首次请求时自动构建。
3. 前端自动启用：ReAct 模式默认会在需要时自动检索知识库；传统模式 /api/chat 可通过 use_knowledge: true 参数启用。
4. 若目录大小写与默认值不同，可在 .env 中设置 KNOWLEDGE_BASE_PATH=./Knowledge_Base 指向实际路径。
5. 需要刷新知识库时，重新运行索引构建脚本或删除旧索引文件后再次启动。

嵌入向量依赖硅基流动的 Qwen/Qwen3-Embedding-4B 模型，请确保 SILICONFLOW_TOKEN 拥有相应权限。

🎨 前端体验亮点

界面设计

• 深色科技风 UI：配合霓虹渐变、毛玻璃效果与流畅动效，提供沉浸式体验。
• 居中欢迎界面：新对话以居中卡片形式展示核心功能，发送首条消息后自动切换为标准聊天模式。
• 响应式布局：完美适配桌面与移动端，侧边栏支持滑动切换。

交互优化

• 自动功能启用：默认同时启用联网搜索、知识库检索和 ReAct 推理模式，无需手动配置。
• 智能输入框：自动高度调整（最高 120px），支持快捷键（Enter 发送、Shift+Enter 换行）。
• 实时状态反馈：显示处理时长、支持取消正在进行的回答、网络状态实时监控。
• 会话管理：侧边栏展示历史会话列表，点击快速切换，支持导出与清空当前会话。
• 推理过程可视化：自动展开显示意图识别、思考过程、工具调用和观察结果，让 AI 的推理透明可见。

核心功能卡片

新对话时，界面中央展示四大核心能力：

• 🌐 实时联网搜索：获取最新网络资讯
• 🧠 智能推理：多步骤复杂问题求解
• 📚 知识库检索：查询内部文档资料
• 🛠️ 工具调用：计算、翻译、文本处理等

🔧 开发指南

1. 后端扩展：在 app.py 或独立蓝图中新增路由，并在 static/js/main.js 接入前端逻辑。
2. 插件开发：在 ReAct_Plugins/ 中创建新的工具文件，编写执行函数并配置 TOOL_CONFIG，参考 example_plugin.py.example。
3. 意图规则扩展：在 intent_classifier.py 中添加新的 IntentRule，自定义关键词、正则模式和工具推荐。
4. 主题定制：修改 static/css/style.css 内的 CSS 变量即可快速调整配色方案。
5. 配置扩展：在 config.py 添加新的配置项，通过环境变量覆盖实现差异化部署。
6. 日志分析：使用 logs/conversation.log 中的结构化日志进行用户行为分析、性能监控和模型调优。

🛡️ 安全建议

Python 解释器工具安全

• python_interpreter 工具默认为示例文件（.example），需要手动启用。
• 启用后仅允许纯计算操作，禁止访问文件系统、网络和系统命令。
• 不要在生产环境对外暴露该工具，除非实施额外的沙盒隔离（如 Docker 容器）。

API 密钥保护

• 将 .env 文件添加到 .gitignore，避免泄露 API 密钥。
• 在生产环境使用环境变量注入，不要将密钥硬编码在代码中。
• 定期轮换 API 密钥，并监控使用量避免滥用。

会话数据隐私

• 对话历史存储在本地 SQLite 数据库中，包含用户输入和 AI 响应。
• 如需符合数据保护法规（如 GDPR），请实施适当的数据加密和用户同意机制。
• 定期清理过期会话数据，避免数据库无限增长。