🎓 Smart Mistake Lab（智能错题本）

一款基于 AI 视觉识别的多学科错题管理工具。支持数学、物理、化学、英语、语文五大学科，通过自动化流程简化错题整理。一键扫描本地图片文件夹，AI 自动识别题目内容并按学科分类打标签，支持详细的解答编辑、灵活的学习追踪、超时督促提醒等功能。

核心特色：

🤖 AI 智能识别 — 自动提取题目文字、知识点标签和解题思路
📂 学科自动分类 — 按目录结构自动识别学科，无需手动标记
💡 专科知识库 — 每个学科内置 100+ 核心知识点库，分析更精准
🔍 强大检索 — 支持关键词、标签、日期、掌握程度多维筛选
📌 重点练管理 — 标记薄弱题目，自动超时督促与鼓励语生成
📊 学习数据 — 练习次数、掌握程度、难度评分全记录
💾 本地存储 — 所有数据存本地 SQLite，图片保留原位置

功能概览

📂 学科目录分类

按目录自动归类 — 图片目录下的一级子目录自动识别为学科名称（如 数学/ 物理/），无需手动标记
学科专属 AI 分析 — 分析时自动使用对应学科的知识点列表生成标签，分析结果更精准
分类统计 — 错题库页面按学科页签展示，每学科独立计数，一目了然
预设顺序 — 学科页签按数学 → 物理 → 化学 → 英语 → 语文排序，未分类图片固定在末尾

核心功能

📂 目录扫描 — 指定本地图片文件夹，程序自动扫描 jpg / png / gif / webp / bmp 图片，按学科分组展示
🔄 索引状态追踪 — 自动判断每张图片是否已被索引，区分"已索引"和"待索引"
🔃 刷新扫描 — 在文件夹中加入新图片后，点击刷新按钮即可发现未索引的新图片
🤖 AI 分析 — 点击未索引图片，调用大模型自动提取题目文字内容、题目标题、知识点标签
📝 题目内容提取 — AI 自动从图片中提取题目的题干文字，独立保存为"题目内容"字段，便于复习和搜索
🏷️ 标签编辑 — 支持标签的增加、删除、修改（双击标签进入编辑模式）
🔍 错题库检索 — 按学科切换、按知识点标签筛选、按掌握程度筛选、按关键词搜索已索引的错题（搜索范围包括标题、题目内容、标签、备注），支持日期范围筛选
📅 日期视图分组 — 错题库支持按日 / 周 / 月切换分组展示，方便按时间回顾和对比
📌 重点练专区 — 独立页面管理重点练题目，支持最多 5 道的重点练标记、超时督促提醒和红框高亮
💾 本地数据库 — 图片文件保留在原始目录，元数据存储在 SQLite 数据库中

解答功能

✏️ 解答编辑 — 每道错题可独立编辑解答/解析，支持纯文本输入
🖼️ 图片粘贴 — 在解答区域可直接粘贴（Ctrl+V）剪贴板中的解题图片
📎 图片上传 — 点击上传按钮从本地选择解题图片
🖼️ 双击查看原图 — 解答缩略图支持双击放大预览，点击遮罩/关闭按钮/Esc 关闭
🗑️ 图片删除 — 每个解题图片右上角有删除按钮，可单独移除
💾 自动保存 — 解答文本和图片变更后自动保存，无需手动点击保存按钮
📸 图片命名规范 — 解答图片自动按 {原文件名}_sol_{序号}.{扩展名} 规范命名

删除管理

🗑️ 仅移除索引 — 只删除错题库中的索引记录，保留原题图片和解答图片等资源，之后可重新索引
⚠️ 彻底删除 — 同时删除索引记录、原题图片、解答图片等所有关联资源，不可恢复
删除确认弹窗 — 每次删除操作前弹出确认弹窗，明确选择删除方式，防止误操作

学习追踪

📊 掌握程度 — 每道错题可标记掌握程度（已掌握 / 不熟悉 / 继续练习）
⭐ 难度评分 — 每道错题可设置 1–5 星难度（1=简单，5=困难，默认 3），在卡片和详情页直观展示
🔄 练习计数 — 自动记录每道错题的练习次数
⏰ 最近练习 — 记录最近一次练习的时间
📌 重点练管理 — 可将题目标记为重点练，最多同时保留 5 道；超过设置的未练习时长后，会在重点练页面显示督促提醒，并用红色边框高亮
📝 备注笔记 — 每道错题可添加自由文本备注

📌 重点练使用

在错题卡片详情弹窗中点击 设为重点练，即可把当前题目加入重点练列表。
顶部切换到 重点练 页面，可以集中查看当前标记的题目，页面会显示重点练数量和超时提醒。
当重点练题目长时间没有练习时，页面会显示督促横幅，并用红色边框高亮相关题目，方便优先处理。
重点练最多同时保留 5 道题；如果不再需要，回到详情页点击 取消重点练 即可移除。
重点练页面中的卡片会沿用错题卡片的基础信息，同时额外突出显示超时状态和未练习时长。

架构概览

图片目录（按学科分类）               前端 (React + Vite)              后端 (Python FastAPI)               存储层
┌─────────────────┐              ┌──────────────────────┐        ┌──────────────────────────┐      ┌──────────┐
│ 数学/            │              │  mistake-notebook    │  HTTP  │  server/server.py        │ SQL  │ SQLite   │
│ 物理/            │   文件读取    │  .jsx                │◄──────►│  (port 8765)             │─────►│ data.db  │
│ 化学/            │◄─────────────┤                      │ proxy  │  ┌────────────────────┐  │      │          │
│ 英语/            │              │  （无 AI 逻辑）       │        │  │ llm.py (AI 交互)  │  │      │ 图片元数据│
│ 语文/            │              │                      │        │  │ log.py (日志)      │  │      │ 配置信息  │
│ 📄 未分类图片     │              │                      │        │  └────────────────────┘  │      └──────────┘
└─────────────────┘              └──────────────────────┘        └──────────────────────────┘

学科目录：图片目录下的一级子目录自动识别为学科名，AI 分析时使用对应学科的知识点列表
后端：统一管理 AI 调用、学科专用 Prompt 构建、API 鉴权与日志
前端：只负责界面展示与用户交互，不含任何 AI 或 API Key 逻辑
Vite 代理：将 /api 请求转发到后端（开发环境免跨域）

技术栈

层	技术
前端框架	React 19 + Vite 7
图标库	Lucide React
后端	Python FastAPI + Uvicorn
AI 交互	Python httpx（`server/llm.py`）
日志	Python logging + RotatingFileHandler（`server/log.py`）
数据库	SQLite（通过 Python sqlite3）
AI 接口	支持图片输入的 OpenAI Chat Completions / Anthropic Messages / Ollama

🚀 快速开始

前置要求

组件	版本要求	说明
Node.js	≥ 18	前端构建和运行
npm	≥ 9	前端包管理
Python	≥ 3.10	后端服务（由 uv 自动管理）
uv	最新	Python 包管理器与虚拟环境管理（推荐）
AI 服务	—	OpenAI/Claude/Ollama 等支持图片输入的模型服务

安装 uv

项目后端使用 uv 管理 Python 虚拟环境与依赖。未安装 uv 时，请先按操作系统安装：

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后重新打开一个终端，执行 uv --version 验证安装成功。

其他安装方式（pip install uv、pipx install uv、winget install astral-sh.uv、scoop install uv 等）详见 uv 官方安装文档。

第 1 步：克隆项目并初始化依赖

# 克隆项目
git clone <repository-url>
cd Smart-Mistake-Lab

# 初始化前端依赖（生成 node_modules/）
npm install

# 初始化后端依赖：uv sync 会自动创建 server/.venv 虚拟环境，
# 并按 server/pyproject.toml 安装全部 Python 依赖（fastapi / uvicorn / httpx / python-dotenv）
cd server
uv sync
cd ..

依赖初始化说明：

前端：npm install 依据根目录 package.json 安装 React / Vite 等前端依赖。
后端：uv sync 依据 server/pyproject.toml 自动创建 server/.venv 虚拟环境并安装依赖；首次运行会下载 Python 运行时与依赖包，请保持网络畅通。
后续启动统一使用 uv run python server.py（一键脚本 start.ps1 / start.bat / start.sh 内部也是调用 uv），无需手动激活虚拟环境。
若依赖清单有更新（如拉取了新代码），重新执行 uv sync 即可同步安装。

请确保在执行 npm run dev 时当前目录是 Smart-Mistake-Lab（包含 package.json 的目录），否则 npm 会启动失败。

第 2 步：配置 AI 服务

在项目根目录创建或编辑 .env 文件，配置两套 AI 服务参数（所有密钥仅保存在 .env）：

# ---- 图片题目提取配置（视觉模型，必须支持图片输入）----
IMAGE_ANALYSIS_AI_API_URL=http://localhost:11434
IMAGE_ANALYSIS_AI_MODEL=llava
IMAGE_ANALYSIS_API_KEY=sk-your-image-analysis-api-key

# ---- 解题分析配置（文本模型，无需图片输入）----
PROBLEM_AI_API_URL=http://localhost:11434
PROBLEM_API_MODEL=qwen2.5
PROBLEM_API_KEY=sk-your-problem-analysis-api-key

📌 重要：

图片题目提取模型（IMAGE_ANALYSIS_*）必须支持图片输入（如 GPT-4 Vision、Claude、LLaVA）。

解题分析模型（PROBLEM_*）只需支持文本输入即可，可选用更便宜或更擅长结构化输出的模型。

不同 AI 服务的配置格式详见「AI 配置（.env）」部分。

第 3 步：一键启动（推荐）

项目提供脚本自动启动前后端服务。根据你的操作系统选择对应脚本：

Windows (PowerShell)

.\start.ps1

Windows (命令提示符)

start.bat

Linux / macOS

chmod +x start.sh
./start.sh

脚本会自动检测缺失依赖、安装依赖，然后启动后端（端口 8765）和前端（端口 5173）服务。

启动完成后，在浏览器打开 http://127.0.0.1:5173 即可使用。

高级启动选项

指定 IP 地址（局域网访问）：

# Windows PowerShell
.\start.ps1 --ip 192.168.1.10

# Windows CMD
start.bat --ip 192.168.1.10

# Linux/macOS
./start.sh --ip 192.168.1.10

其他启动参数：

参数	说明
`--ip <地址>`	指定前后端绑定的 IP 地址（本机网卡实际 IP，不能是网关地址）
`--no-frontend`	仅启动后端服务
`--no-backend`	仅启动前端服务
`--port <端口>`	指定后端端口（默认 8765）

第 4 步：手动启动（开发调试）

如果需要分别启动前后端进行开发调试：

# 终端 1：启动后端 (http://127.0.0.1:8765)
cd server
uv run python server.py

# 终端 2：启动前端 (http://localhost:5173) — 新开一个终端
npm run dev

Vite 开发服务器会自动将 /api 请求代理到后端，避免跨域问题。

生产部署

构建前端

npm run build      # 输出到 dist/ 目录
npm run preview    # 在本地预览生产构建

部署要点

后端服务：确保后端持续运行（建议用 systemd/supervisor 等进程管理）
反向代理：配置 Nginx/Apache 将 /api 请求转发到后端
HTTPS：生产环境建议配置 SSL/TLS 证书
环境变量：在服务器上配置 .env 文件中的 AI 服务参数

Nginx 配置示例：

server {
    listen 80;
    server_name example.com;

    # 前端静态文件
    location / {
        root /path/to/dist;
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api {
        proxy_pass http://127.0.0.1:8765;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

配置说明

图片目录配置（学科分类）

在应用的配置页面设置本地存放错题图片的文件夹路径，例如：

C:\Users\me\Pictures\错题

目录配置保存在后端 SQLite 数据库中，重启后依然生效。

同一页面还可以设置 重点练超时阈值，用于控制重点练题目多久未练习后触发督促提醒，默认是 48 小时。

学科分类约定：图片目录下的第一级子目录名自动识别为学科名称。建议按以下结构组织：

C:\Users\me\Pictures\错题\
├── 数学\          ← 自动归类为"数学"
│   ├── 01-三角形\
│   │   ├── 错题1.jpg
│   │   └── 错题2.png
│   └── 02-函数\
│       └── 错题3.jpg
├── 物理\          ← 自动归类为"物理"
│   └── 错题4.jpg
├── 化学\          ← 自动归类为"化学"
├── 英语\          ← 自动归类为"英语"
├── 语文\          ← 自动归类为"语文"
├── 未分类的题.png  ← 归类为"未分类"
└── 封面.jpg       ← 归类为"未分类"

深层子目录（如 数学/01-三角形/）不会产生独立学科，其图片归到一级子目录对应的学科。

AI 配置（.env）

AI 参数由后端服务统一管理，通过 Smart-Mistake-Lab/ 根目录下的 .env 文件配置（后端启动时会自动加载，见 server/server.py）。系统使用两套独立配置，分别用于不同的 AI 任务：

# ---- 图片题目提取配置（视觉模型，必须支持图片输入）----
IMAGE_ANALYSIS_AI_API_URL=https://your-vision-model-host/v1/chat/completions
IMAGE_ANALYSIS_AI_MODEL=your-vision-model
IMAGE_ANALYSIS_API_KEY=sk-your-image-analysis-api-key

# ---- 解题分析配置（文本模型，无需图片输入）----
PROBLEM_AI_API_URL=https://your-text-model-host/v1/chat/completions
PROBLEM_API_MODEL=your-text-model
PROBLEM_API_KEY=sk-your-problem-analysis-api-key

# ---- 通用配置（两套 AI 共用，可选）----
# AI_TIMEOUT=120              # 单次 AI 请求超时（秒），默认 120
# AI_MAX_TOKENS=4096          # 模型最大输出 token 数，默认 4096

所有 LLM 配置（URL / 模型名 / API Key）仅存于 .env，不会暴露到浏览器端，也不会写入数据库。修改后需重启后端服务（重新运行启动脚本，或手动执行 uv run python server.py）。

配置项说明

变量	必填	默认值	说明
`IMAGE_ANALYSIS_AI_API_URL`	✅	—	图片题目提取服务地址（视觉模型）
`IMAGE_ANALYSIS_AI_MODEL`	✅	—	图片题目提取使用的模型名
`IMAGE_ANALYSIS_API_KEY`	视服务	—	图片题目提取 API Key（Ollama 可留空）
`PROBLEM_AI_API_URL`	✅	—	解题分析服务地址（文本模型）
`PROBLEM_API_MODEL`	✅	—	解题分析使用的模型名
`PROBLEM_API_KEY`	视服务	—	解题分析 API Key（Ollama 可留空）
`AI_TIMEOUT`	否	`120`	单次 AI 请求超时（秒）
`AI_MAX_TOKENS`	否	`4096`	模型最大输出 token 数；若分析结果被截断（日志出现 `max_tokens` 截断提示），可调大此值

职责说明：

图片题目提取（IMAGE_ANALYSIS_*）：从错题图片中提取完整题目内容，所用模型必须支持视觉输入。
解题分析（PROBLEM_*）：基于题目文本生成解题思路（summary）、知识点标签（tags）和难度（difficulty），以及重点练鼓励语，所用模型只需支持文本输入。

常见模型配置示例

OpenAI 兼容服务（GPT-4o / Qwen / GLM / 硅基流动 / vLLM 等）：

IMAGE_ANALYSIS_AI_API_URL=https://api.openai.com/v1/chat/completions
IMAGE_ANALYSIS_AI_MODEL=gpt-4o
IMAGE_ANALYSIS_API_KEY=sk-xxxxxxxx

PROBLEM_AI_API_URL=https://api.openai.com/v1/chat/completions
PROBLEM_API_MODEL=gpt-4o-mini
PROBLEM_API_KEY=sk-xxxxxxxx

DeepSeek（仅支持文本，只能用于解题分析，不能用于图片提取）：

PROBLEM_AI_API_URL=https://api.deepseek.com/v1/chat/completions
PROBLEM_API_MODEL=deepseek-chat
PROBLEM_API_KEY=sk-xxxxxxxx

Anthropic Claude（视觉 + 文本）：

IMAGE_ANALYSIS_AI_API_URL=https://api.anthropic.com/v1/messages
IMAGE_ANALYSIS_AI_MODEL=claude-sonnet-4-20250514
IMAGE_ANALYSIS_API_KEY=sk-ant-xxxxxxxx

PROBLEM_AI_API_URL=https://api.anthropic.com/v1/messages
PROBLEM_API_MODEL=claude-sonnet-4-20250514
PROBLEM_API_KEY=sk-ant-xxxxxxxx

Ollama 本地部署（无需 API Key）：

IMAGE_ANALYSIS_AI_API_URL=http://localhost:11434
IMAGE_ANALYSIS_AI_MODEL=qwen3.6-flash

PROBLEM_AI_API_URL=http://localhost:11434
PROBLEM_API_MODEL=deepseek-v4-flash

# 请求超时（秒），默认 120。本地模型处理图片可能需要更长时间
AI_TIMEOUT=600

# 最大输出 token 数量。分析只输出一个 JSON（content 复制题目 + summary + tags），
# 一般 1500 token 内足够；但 DeepSeek 等推理模型（deepseek-v4-flash）会把大部分
# token 消耗在 reasoning_content 推理过程上，若 max_tokens 太小会在推理中途被截断
# （finish_reason=length），导致 content 字段为空、最终 JSON 缺失。因此这里调大。
# 若使用 8K 上下文的本地小模型，请按需调小（如 4096）。
AI_MAX_TOKENS=32768

支持的 AI 接口格式

格式	鉴权方式	适用服务
OpenAI 兼容 `/v1/chat/completions`	`Authorization: Bearer`	支持图片输入的 OpenAI 兼容模型服务
Anthropic `/v1/messages`	`x-api-key` + `anthropic-version`	支持图片输入的 Claude 模型服务
Ollama `/api/chat`	无	本地 Ollama 服务（如 `http://localhost:11434`）

程序会根据接口 URL 自动判断请求格式。如果直接填写 Ollama 的基础地址（如 http://localhost:11434），程序会自动补全为 /api/chat。

项目结构

Smart-Mistake-Lab/
├── index.html                  # 入口 HTML
├── package.json                # 前端依赖与脚本
├── vite.config.js              # Vite 配置（含 API 代理）
├── .env                        # 环境变量（需自行创建，两套 LLM 配置：IMAGE_ANALYSIS_* / PROBLEM_*，见「AI 配置」）
├── mistake-notebook.jsx        # 主应用组件（含所有页面逻辑与样式）
├── start.ps1                   # Windows PowerShell 一键启动脚本
├── start.bat                   # Windows CMD 一键启动脚本
├── start.sh                    # Linux / macOS 一键启动脚本
├── src/
│   ├── main.jsx                # React 挂载入口
│   └── App.jsx                 # 组件导出
└── server/
    ├── pyproject.toml           # 项目配置与依赖（uv 管理）
    ├── server.py               # FastAPI 后端服务入口（REST API + 图片服务）
    ├── db.py                   # SQLite 数据库操作层（CRUD + 迁移 + 学科查询）
    ├── llm.py                  # AI 交互模块（学科 Prompt 管理、API 调用、响应解析）
    ├── log.py                  # 日志模块（控制台 + 轮转文件输出）
    ├── data.db                 # SQLite 数据库（自动创建）
    └── logs/
        └── server.log          # 服务端运行日志（自动创建，10MB 轮转）

API 接口一览

方法	路径	说明
GET	`/api/health`	健康检查
GET	`/api/config`	获取配置（图片目录、重点练超时阈值）
PUT	`/api/config`	保存配置（图片目录、重点练超时阈值）
GET	`/api/ai-config`	获取 AI 配置状态（仅展示 .env 中两套配置的 URL/模型/是否已设置 Key，不返回 Key 原文）
PUT	`/api/ai-config`	已废弃：LLM 配置仅由 .env 管理，写请求不再生效
GET	`/api/scan`	扫描图片目录，按学科分组返回已索引/未索引文件列表（含 `subject_order`）
GET	`/api/images/all`	获取所有已索引图片，支持筛选参数
		- `subject`: 按学科筛选（默认空=全部）
		- `query`: 关键词搜索（标题/内容/标签/备注）
		- `mastery`: 按掌握程度筛选（mastered / unfamiliar / practice）
		- `date_enabled`: 是否启用日期范围
		- `start_date` / `end_date`: 日期范围（YYYY-MM-DD）
		返回 `{items, total_count, filtered_count, subjects}`
POST	`/api/images/index`	将图片标记为已索引（自动推断学科，接收 title/content/tags/difficulty 等）
PUT	`/api/images/update`	更新已索引图片的元数据（含解答、掌握程度、难度、备注等）
DELETE	`/api/images/delete`	从索引中移除图片（参数：`file_path`），不删除文件
DELETE	`/api/images/purge`	彻底删除图片：移除索引 + 删除原题图片 + 解答图片等关联资源（参数：`file_path`）
GET	`/api/images/focus`	获取重点练题目列表、数量及超时状态
PUT	`/api/images/focus`	设为/取消重点练（最多 5 道）
POST	`/api/images/focus/reminders`	批量生成重点练超时题目的鼓励语
POST	`/api/analyze`	对指定图片进行 AI 分析（自动按学科选择知识点列表），返回 `{title, summary, tags}`
POST	`/api/solution-image`	上传解答图片，自动按 `{原文件名}_sol_{序号}.{扩展名}` 命名
DELETE	`/api/solution-image`	删除指定路径的解答图片（参数：`path`）
GET	`/api/timeline`	获取时间线数据，按天/周/月聚合练习记录（参数：`offset`）
GET	`/api/image-file`	提供图片文件访问服务（参数：`path`）

使用说明

初次使用

按学科组织图片目录（参见"图片目录配置"部分），将错题截图放入对应子目录
运行一键启动脚本（如 start.ps1），或分别手动启动后端和前端
打开浏览器访问 http://127.0.0.1:5173 或 http://localhost:5173（指定 --ip 时访问对应的地址）
进入配置页面，设置图片存放目录路径并保存
确保 .env 文件中已配置 IMAGE_ANALYSIS_AI_API_URL / IMAGE_ANALYSIS_AI_MODEL（图片提取，需视觉模型）以及 PROBLEM_AI_API_URL / PROBLEM_API_MODEL（解题分析）
切换到扫描页面，点击 刷新扫描，图片会按学科分组展示
点击任意 待索引 的图片缩略图
点击 AI 分析知识点，等待分析完成（AI 会根据学科自动选择知识点列表）
检查/编辑标题、题目文字内容、知识点标签（双击标签可编辑，点击 × 可删除）
点击 保存索引，该图片标记为已索引并归入对应学科

保存索引后切换到错题库页面，会自动跳转到该图片所属的学科页签。

错题库浏览

切换到 错题库 页面，所有已索引的错题以卡片形式展示
学科页签栏：顶部显示全部学科页签，每个页签标注该学科错题数量，点击切换学科
学科标题：当前学科名称后显示"共 N 题，当前筛出 M 题"的统计信息
按知识点标签筛选、按关键词搜索（支持标题、题目内容、标签、备注）
按掌握程度筛选（全部 / 已掌握 / 不熟悉 / 需练习）
支持按添加日期范围筛选（勾选"按添加时间筛选"后选择起止日期）
支持按日期视图切换为按日 / 按周 / 按月分组展示，方便查看同一时间段新增的题目
搜索条件变化时自动防抖请求后端，无需手动刷新
当前学科和筛选条件自动保存在浏览器中

题目详情与解答

点击错题卡片进入详情弹窗，可进行以下操作：

卡片本身会显示题目标题、前几个知识点标签、掌握程度、星级难度和练习次数；如果题目已标记为重点练，还会显示「重点练」标识。

功能	说明
编辑标题	点击标题旁的 ✎ 按钮，修改后自动保存
题目内容	查看/编辑 AI 提取的题目文字内容，修改后自动保存
知识点标签	添加、修改（双击）、删除标签
解答编辑	在解答文本框中输入解题思路或解析，内容自动保存
粘贴图片	在解答区域按 Ctrl+V 粘贴剪贴板中的解题图片
上传图片	点击"添加图片"按钮从本地选择解题图片
双击查看原图	双击解答缩略图，全屏预览原图，点击遮罩或按 Esc 关闭
删除图片	悬停解答图片，点击右上角 × 删除
难度评分	通过星级设置题目难度（1=简单 ~ 5=困难）
掌握程度	设置掌握程度（已掌握 / 不熟悉 / 继续练习）
练习计数	点击"练习 +1"按钮增加练习次数
题目翻页	在详情弹窗中可点击左右箭头切换上一题 / 下一题，也支持键盘左右方向键切换
时间信息	详情页会显示题目添加时间和最近练习时间
删除错题	点击删除按钮，弹出确认弹窗选择"仅移除索引"或"彻底删除"
备注笔记	添加自由文本备注

日常使用

按学科将新错题图片放入配置的图片目录下的对应子目录（如 数学/、物理/）
打开应用，进入扫描页面，点击 刷新扫描
新图片会按学科分组出现在"待索引"区域，点击即可分析
切换到 错题库 页面，通过学科页签切换浏览不同学科的错题
搜索时输入关键词、选择标签、或按日期范围精确筛选；也可以切换日期视图按日 / 周 / 月分组查看
点击错题卡片查看详情，可编辑解答、标签、掌握程度等，并可用左右箭头切换前后题目
如需集中复习薄弱题目，切换到 重点练 页面查看已标记题目和督促提醒

标签操作

操作	方式
添加标签	在输入框输入后回车或点击 + 按钮
修改标签	双击标签，或点击编辑按钮 ✎，修改后回车确认
删除标签	点击标签上的 × 按钮

💡 使用小贴士

目录结构：错题图片按学科放入不同子目录（数学/ 物理/ 化学/ 英语/ 语文/），扫描时自动分类
深层目录：一级子目录下的深层目录（如 数学/几何/三角形/）不会产生独立学科，图片归到一级学科
扫描后自动跳转：在扫描页面完成分析并保存索引后，切换到错题库页面会自动定位到该学科
状态持久化：当前所处的学科页签和筛选状态保存在浏览器 localStorage 中，刷新页面不会丢失
切学科清标签：切换学科页签时会自动清空已选的知识点标签，避免跨学科筛选混淆

⚡ 最佳实践

图片管理

统一的目录结构 — 建立清晰的学科目录，便于长期维护：

错题/
├── 数学/
├── 物理/
├── 化学/
├── 英语/
└── 语文/

命名规范 — 图片文件名可包含日期或简短描述，便于搜索：
```
2025-01-15_三角形的中线定理.jpg
20250115_求导_难度 5.png
```
定期整理 — 每月检查一次待索引图片，及时将新题目加入数据库

AI 分析优化

选择合适的模型 — 不同模型分析能力有差异：
- GPT-4 Vision — 精准度最高，适合要求严格的学习
- Claude 3.5 Sonnet — 性能均衡，分析稳定
- Ollama (LLaVA) — 免费本地运行，但精准度较低
审核 AI 结果 — AI 有时会：
- 误读题目中的特殊符号或图形
- 标签选择不够精准
- 建议：完成索引后仔细审查，手动调整不准确的标签
使用学科专属知识点 — 系统已为五大学科内置 100+ 知识点库，确保 AI 分析时选中正确的学科

学习追踪

定期回顾 — 利用"重点练"功能标记薄弱题目，集中强化学习
难度评分 — 为不同难度的题目评分，帮助制定复习计划
掌握程度 — 及时更新题目掌握状态，避免重复复习已掌握的内容
备注笔记 — 记录解题思路、常见陷阱、关键公式等，加深记忆

重点练管理

合理设置超时阈值 — 默认 48 小时，可根据学习节奏调整
定期清理 — 完全掌握的题目及时移除，为新题目腾出空间
结合鼓励语 — 系统会为超时题目生成个性化鼓励语，利用心理暗示提高学习动力

🔧 故障排除

启动问题

问题 1：npm 安装失败

症状：npm install 出错，提示缺少依赖

解决方案：

# 清除缓存并重试
npm cache clean --force
npm install --legacy-peer-deps

# 或者升级 npm
npm install -g npm@latest
npm install

问题 2：Python 依赖不足

症状：运行 uv sync 或 python server.py 出错

解决方案：

cd server
uv sync --upgrade  # 强制更新所有依赖
cd ..

问题 3：启动脚本执行失败

症状：Windows PowerShell 报错"因为在此系统上禁止运行脚本"

解决方案（PowerShell）：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# 然后重新运行 start.ps1
.\start.ps1

连接问题

问题 4：前端无法连接后端

症状：浏览器控制台报错 Failed to fetch /api/...

解决方案：

检查后端是否正常运行（应输出 Uvicorn running on http://127.0.0.1:8765）
检查防火墙是否阻止了 8765 端口
确保 vite.config.js 中的 API 代理配置正确
尝试直接访问 http://127.0.0.1:8765/api/health 测试后端

问题 5：指定 IP 后无法访问

症状：按 --ip 192.168.1.10 启动后，访问该 IP 无法连接

解决方案：

确认 IP 地址正确（运行 ipconfig 或 ifconfig 查看本机 IP）
确保该 IP 确实属于本机网卡（不是网关地址）
检查防火墙是否允许外部连接到该 IP
尝试在同一局域网的其他设备上访问

AI 分析问题

问题 6：AI 分析失败或超时

症状：点击"AI 分析知识点"后长时间无响应或报错

解决方案：

检查 .env 文件中的配置是否正确：
- 图片提取：IMAGE_ANALYSIS_AI_API_URL、IMAGE_ANALYSIS_AI_MODEL（须支持图片输入）
- 解题分析：PROBLEM_AI_API_URL、PROBLEM_API_MODEL
- 若为 Anthropic 端点，还需对应配置 IMAGE_ANALYSIS_API_KEY / PROBLEM_API_KEY
确保网络连接正常（如使用国外 API，检查是否需要代理）
检查 AI 服务是否在线（访问官网或尝试其他客户端）
查看后端日志：server/logs/server.log，获取详细错误信息
尝试用其他模型或 AI 服务测试

问题 7：AI 分析结果不准确

症状：提取的题目内容错误、标签不相关

解决方案：

检查上传的图片清晰度和质量（图片过糊或过小会影响识别）
确保图片中题目明确（避免手写不清晰、拍摄角度歪斜等）
对于复杂题目，手动检查后编辑标题、内容和标签
考虑更换模型或 AI 服务提升准确度

数据库问题

问题 8：无法索引图片或数据丢失

症状：索引后刷新页面数据消失、或报错"数据库锁定"

解决方案：

检查 server/data.db 文件是否存在且可写
关闭所有正在访问数据库的进程（停止前端和后端）
删除 data.db 文件重启后端，系统会自动创建新数据库
查看后端日志获取具体错误信息

问题 9：图片文件无法访问

症状：图片缩略图显示失败、或解答图片加载不出来

解决方案：

确认图片文件仍存在于原位置（未被移动或删除）
检查文件权限（特别是在 Linux/macOS 上）
确认图片路径不包含特殊字符或中文（如必须包含，需正确编码）

性能问题

问题 10：应用加载缓慢或卡顿

症状：错题库页面加载慢、搜索响应缓慢

解决方案：

减少同时显示的题目数量（使用日期范围或标签筛选）
清理浏览器缓存和 localStorage（开发者工具 → 应用 → 清除数据）
检查后端日志是否有错误或警告
如错题数量很多（>10000），考虑分库存储或优化数据库索引

❓ 常见问题

Q: 如何备份我的错题数据？

A: 数据存储在 server/data.db 文件中。定期复制此文件作为备份，或通过导出功能（未来版本）生成备份。

Q: 可以在多台设备上共享数据吗？

A: 可以。部署生产版本后，多台设备可通过网络访问同一个后端服务。或将 server/data.db 放在共享网络存储上。

Q: 支持离线使用吗？

A: 前端可离线访问（生产构建后），但 AI 分析功能需要网络连接。已索引的数据会缓存在浏览器，但修改需要后端。

Q: 如何删除所有数据重新开始？

A: 删除 server/data.db 文件并重启后端，系统会创建新的空数据库。

Q: 支持哪些图片格式？

A: 支持 JPG、PNG、GIF、WebP、BMP 等常见格式。其他格式自动忽略。

Q: 如何导出数据库中的图片数据做运维检查？

A: 可在 server 目录下执行下面的命令，将 images 表中的 id、file_path、title、subject 导出为 images.csv：

cd server
python -c "import sqlite3,csv; conn=sqlite3.connect('data.db'); rows=conn.execute('SELECT id,file_path,title,subject FROM images').fetchall(); open('images.csv','w',newline='',encoding='utf-8-sig').write('id,file_path,title,subject\n' + ''.join([','.join(map(str,r))+'\n' for r in rows]))"

📝 开发与贡献

本项目欢迎贡献！如有 Bug 报告、功能建议或代码改进，请：

提交 Issue — 描述问题或功能需求
发起 PR — 提交改进代码
讨论改进 — 参与项目讨论

开发环境配置

# 安装开发依赖（前端）
npm install

# 运行前端开发服务器（含热重载）
npm run dev

# 运行后端开发服务器（含自动重启）
cd server
uv run python server.py

项目架构与代码组织

前端 — 单文件组件 (mistake-notebook.jsx)，便于快速迭代
后端 — 模块化设计，易于扩展和维护
数据库 — SQLite，轻量级，便于本地测试和部署

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

📞 联系方式与反馈

提交 Issue 或 PR：GitHub Repository
反馈邮箱：wubo0067@hotmail.com

祝你学习进步！🎉

Name		Name	Last commit message	Last commit date
server		server
src		src
.gitignore		.gitignore
README.md		README.md
index.html		index.html
mistake-notebook.jsx		mistake-notebook.jsx
package-lock.json		package-lock.json
package.json		package.json
start.bat		start.bat
start.ps1		start.ps1
start.sh		start.sh
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation

🎓 Smart Mistake Lab（智能错题本）

功能概览

📂 学科目录分类

核心功能

解答功能

删除管理

学习追踪

📌 重点练使用

架构概览

技术栈

🚀 快速开始

前置要求

安装 uv

Windows (PowerShell)

macOS / Linux

第 1 步：克隆项目并初始化依赖

第 2 步：配置 AI 服务

第 3 步：一键启动（推荐）

Windows (PowerShell)

Windows (命令提示符)

Linux / macOS

高级启动选项

第 4 步：手动启动（开发调试）

生产部署

构建前端

部署要点

配置说明

图片目录配置（学科分类）

AI 配置（.env）

配置项说明

常见模型配置示例

支持的 AI 接口格式

项目结构

API 接口一览

使用说明

初次使用

错题库浏览

题目详情与解答

日常使用

标签操作

💡 使用小贴士

⚡ 最佳实践

图片管理

AI 分析优化

学习追踪

重点练管理

🔧 故障排除

启动问题

问题 1：npm 安装失败

问题 2：Python 依赖不足

问题 3：启动脚本执行失败

连接问题

问题 4：前端无法连接后端

问题 5：指定 IP 后无法访问

AI 分析问题

问题 6：AI 分析失败或超时

问题 7：AI 分析结果不准确

数据库问题

问题 8：无法索引图片或数据丢失

问题 9：图片文件无法访问

性能问题

问题 10：应用加载缓慢或卡顿

❓ 常见问题

📝 开发与贡献

开发环境配置

项目架构与代码组织

📄 许可证

📞 联系方式与反馈

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors