AI智学项目优化实战：从Bug修复到功能增强

AI智学项目优化实战：从Bug修复到功能增强

项目简介

AI智学 是一个基于 FastAPI + 原生 JavaScript 的智能化教学辅助系统，集成了 DeepSeek API，支持智能对话、教学资源生成、学习效果评估等功能。近期对项目进行了全面的Bug修复和功能优化，本文将详细记录改进过程。

一、关键Bug修复

1. 中文文件名下载乱码问题

问题描述：导出 Word 文档时，中文文件名导致 UnicodeEncodeError。

根本原因：HTTP Content-Disposition header 未正确编码中文字符。

解决方案：

from urllib.parse import quote
safe_filename = re.sub(r'[\\/*?:"<>|]', "_", title)[:50]
ascii_filename = re.sub(r'[^\x00-\x7F]+', "_", safe_filename) + ".docx"
encoded_filename = quote((safe_filename + ".docx").encode('utf-8'))
content_disposition = f"attachment; filename=\"{ascii_filename}\"; filename*=UTF-8''{encoded_filename}"

技术要点：使用 RFC 5987 标准编码，filename*=UTF-8''<encoded_name> 确保现代浏览器正确显示中文文件名。

2. 资源持久化失败

问题描述：生成教学资源后，切换页面或刷新浏览器，之前生成的内容全部丢失。

根本原因：

  • saveResourcesToBackend() 函数使用了错误的变量 window.currentSessionId
  • 页面刷新后会话ID变化，导致无法加载已保存的资源

解决方案：

  1. 修复会话ID持久化（前端 index.html）：
currentSessionId: (function() {
    var saved = localStorage.getItem('session_id');
    if (saved) {
        console.log('[init] 从 localStorage 恢复会话ID:', saved);
        return saved;
    }
    var sid = 'web_' + Date.now() + '_' + Math.random().toString(36).slice(2, 8);
    localStorage.setItem('session_id', sid);
    return sid;
})(),
  1. 修复资源保存逻辑（后端 app.py）：
@app.post("/resource/save")
async def save_resource(req: dict):
    session_id = req.get("session_id") or get_active_session_id()
    if not session_id:
        # 自动创建会话，避免外键错误
        session_id = create_session_if_not_exists(req.get("user_id", "web_user"))
    # 保存资源到数据库...

效果：现在生成的资源会自动保存到数据库，并且通过 localStorage 持久化会话ID，刷新页面后仍能加载历史资源。

3. Mermaid 思维导图渲染失败

问题描述：AI 生成的 Mermaid 思维导图代码包含中文标点（（）：＋，。；？！），导致渲染失败，只能显示降级文字版本。

解决方案：

  1. 添加自动修复函数（fixMermaidCode()）：
function fixMermaidCode(code) {
    // 将中文标点替换为英文标点
    code = code.replace(/（/g, '(').replace(/）/g, ')')
               .replace(/：/g, ':').replace(/，/g, ',')
               .replace(/。/g, '.').replace(/；/g, ';')
               .replace(/？/g, '?').replace(/！/g, '!');
    // 修复 mindmap 的 root 节点格式
    // 用双引号包裹节点文本...
    return code;
}
  1. 浏览器端直接渲染 SVG（不依赖后端）：
function renderMermaidToJpg(code, containerEl) {
    code = fixMermaidCode(code);  // 先修复代码
    mermaid.render(id, code).then(function(result) {
        containerEl.innerHTML = result.svg;  // 直接显示 SVG
    }).catch(function(err) {
        // 显示详细错误信息，方便调试
        containerEl.innerHTML = '<div class="mermaid-error">渲染失败: ' + 
                              escapeHtml(err.message) + '</div>';
    });
}

效果：现在 Mermaid 思维导图可以正确渲染，并且提供了详细的错误日志（按 F12 可查看）。

5. 意图识别不够精准

问题描述：用户请求"总结一下四级重点词汇"，系统却生成了完整的教学方案（讲解文档+练习题+思维导图+视频脚本+实操案例），响应过于冗长。

解决方案：

  1. 增加 summary 意图类别（修改 core.py）：
def build_intent_prompt(last_message: str) -> str:
    return f"""判断以下用户输入的目的，只输出一个词语（greeting / resource / chat / tutor / evaluation / summary）：
- greeting: 打招呼、问候、感谢、开场白
- summary: 请求总结、归纳、概述内容，例如"总结一下..."、"归纳重点"、"概述..."等
- resource: 请求生成完整教学资源（讲解文档、练习题、思维导图、视频脚本等）
- tutor: 请求辅导或解释
- evaluation: 请求学习评估
- chat: 普通学术问题、闲聊、新闻资讯查询
输入: {last_message}
输出:"""
  1. 添加 summary_node_gen() 函数（修改 graph_web.py）：
def summary_node_gen(state: AgentState):
    """总结节点生成器（流式输出）—— 简洁为主，不生成完整教学资源。"""
    last_msg = state["messages"][-1].content
    prompt = f"""用户请求总结以下内容：{last_msg}

要求：
1. 直接回答，简洁为主，不要生成完整的教学资源
2. 使用清晰的标题、列表、表格等结构化格式呈现
3. 突出重点，只列出核心要点，不展开详细讲解
4. 不要生成练习题、思维导图、视频脚本等额外内容

请直接开始总结："""
    # 调用 LLM 生成总结...

效果：现在系统可以正确区分"总结"和"生成教学资源"，避免响应过于冗长。

二、功能增强

1. 多种导出格式支持

实现方式：在前端添加格式选择器，后端支持多种格式导出。

前端（index.html）：

<select id="export-format-select">
    <option value="docx">📄 Word (.docx)</option>
    <option value="md">📝 Markdown (.md)</option>
    <option value="txt">📃 纯文本 (.txt)</option>
    <option value="html">🌐 网页 (.html)</option>
</select>

后端（app.py）：

  • export_docx()：导出 Word 文档
  • export_markdown()：导出 Markdown 文件
  • export_text()：导出纯文本
  • export_html()：导出网页文件

2. 丰富的资源类型支持

系统现在支持生成以下类型的教学资源：

  • 📘 讲解文档：知识点详细讲解
  • 📝 练习题：选择题、填空题、简答题
  • 🗺️ 思维导图：Mermaid 格式，可视化知识结构
  • 🎥 视频脚本：多场景教学视频脚本
  • 💻 实操案例：结合具体场景的实操练习

三、技术架构

后端技术栈

  • 框架：FastAPI（Python）
  • 数据库：SQLite（WAL 模式）
  • AI 模型：DeepSeek API
  • 文档处理：python-docx

前端技术栈

  • 框架：原生 JavaScript（无框架依赖）
  • UI 库：Marked.js（Markdown 渲染）、Mermaid.js（思维导图渲染）
  • 样式：CSS 变量 + Flexbox 布局

项目结构

AI智学/
├── app.py              # FastAPI 后端主程序
├── core.py             # 核心功能（意图识别、Prompt 构建）
├── graph_web.py        # 对话流程图（LangGraph 风格）
├── database.py         # 数据库操作
├── index.html          # 前端单页应用
└── learning_system.db # SQLite 数据库

四、部署与运行

环境要求

  • Python 3.8+
  • FastAPI、uvicorn、python-docx、httpx

启动步骤

# 1. 创建虚拟环境
python -m venv .venv

# 2. 激活虚拟环境
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # macOS/Linux

# 3. 安装依赖
pip install fastapi uvicorn python-docx httpx

# 4. 启动服务器
python app.py

# 5. 访问应用
# 打开浏览器，访问 http://localhost:8000

五、总结与展望

本次优化修复了多个影响用户体验的关键 Bug，并增强了系统的功能。主要成果包括：

✅ 修复中文文件名编码问题
✅ 实现资源持久化保存
✅ 修复 Mermaid 思维导图渲染失败
✅ 优化意图识别，区分"总结"和"生成教学资源"
✅ 支持多种导出格式
✅ 丰富的教学资源类型

未来展望：

  • 集成更多 AI 模型（如 GPT-4、Claude）
  • 支持多模态输入（图片、语音）
  • 添加用户管理和权限控制
  • 优化前端 UI/UX 设计

项目开源地址：[GitHub链接]（如有）
作者：Ding
日期：2026年6月28日

版权声明：本文为博主原创文章，转载请注明出处。

posted on 2026-06-28 17:25  不耻  阅读(3)  评论(0)    收藏  举报

导航