MathForge 是一个 Windows 友好的本地数学题库工坊：把输入目录中的 PDF 逐份交给本地安装的 MinerU或可选的 PaddleOCR，再将结果锻造成可校对、可拆题、可入库的 Markdown 工件。它不调用付费 API，也不上传文件。可视化工作台会显示环境状态、转换资产、题库统计、审校入口、Obsidian 联动与组卷导出。
个人日常启动、备份、清理缓存和升级自检请优先看根目录的 QUICKSTART.md；开源协作请看 CONTRIBUTING.md，安全和本地数据边界请看 SECURITY.md。本文保留完整功能说明和架构背景。
它现在也是一个本地数学题库基座：PDF 转换完成后可重新生成层级化 Obsidian Markdown、自动切分单题、初判题型、人工校对题干/答案/解析、标记知识点与难度、同步到 Obsidian，并按单选/多选/填空/解答四类自动分区组卷，导出 Markdown、Word 和 PDF。
引擎层负责版面分析、OCR、公式 LaTeX、表格和阅读顺序；本项目负责批处理、统一输出、图片相对路径、日志、单题切分、SQLite 题库、人工校对和试卷导出。任何 OCR 结果都应按原 PDF 人工核验，尤其是数学公式和几何图。
从 V0.7/V0.8 开始，项目进入标准产品架构重构阶段：不再把所有界面都强塞进 Streamlit。核心原则是每个功能使用最适合、最快速、最可维护的技术：
- Python：继续负责 MinerU/PaddleOCR/Pix2Text 等 OCR、Markdown 清洗、SQLite 题库、Word/PDF 导出；
- FastAPI：作为下一代本地 API 层，给前端提供题库、转换、日志、文件资产和导出接口；
- TypeScript + React：负责高交互界面，例如 PDF 阅读器、目录跳转、缩略图、截图 Ctrl+V 粘贴、Canvas 框选裁剪、标签泡泡、专业 Markdown 编辑器和公式诊断；
- SQLite：继续作为单机题库数据库，仓储接口预留将来迁移 PostgreSQL 的空间。
当前新增并开始落地的全栈基座：
apps/
api/ # Python FastAPI 本地后端：统计、来源、题目、标签、PDF 证据页、手动入库
web/ # TypeScript + React 前端：PDF 解析壳、快速入库、截图粘贴、单题校对
docs/
progress/archive/fullstack-refactor.md
现有 Streamlit 工作台仍保留为稳定兼容壳；高交互模块会逐步迁移到 React，而不是一次性砸掉可用工具。V1.0.0 已将题库读写能力和本地转换任务入口沉淀到 FastAPI：React 页面可以直接读取题目、保存题干/答案/解析、选择标签泡泡、新增标签，把外部粘贴的 Markdown / 文本 / LaTeX 入库，也可以选择、拖拽或 Ctrl+V 粘贴图片并作为题目证据入库；PDF 解析页现在能调用后端启动本地文件夹转换任务，也能拖拽/选择 PDF 上传后直接创建转换任务，上传时显示文件体积预检和进度条，并可在任务创建前取消上传；任务运行后通过 SSE/轮询显示固定高度滚动日志，并提供最近任务队列用于按状态/关键词/优先级筛选、分页、切换历史日志、取消和重试。PDF 阅读器采用 react-pdf，支持总页码、书签目录、页码跳转、缩略图、缩放、PDF 文本层搜索和可拖拽调整的 bbox 裁剪框；标签/知识点选择采用 react-select/creatable；题干、答案、解析编辑采用 CodeMirror，并用 react-markdown + remark-math + KaTeX 提供编辑 / 分屏 / 预览三种公式校对模式；公式诊断会提示未闭合 $、OCR 乱码、脆弱 LaTeX 命令、过长公式行、明显括号不平衡，并对已正确定界的公式片段运行 KaTeX parse 校验；单题校对页还能通过本地规则给出局部公式复核与替换建议，也能把指定建议排入 Pix2Text/Qwen-VL 模型级公式复核任务队列。当前模型任务会先用题目的来源页码和 bbox 裁剪公式 evidence image，再传给 Pix2Text recognize_formula(image_path) adapter path；Round 42 已在本机生成 docs/progress/releases/v1.0.0/artifacts/formula-runner-real-sample.json 并记录 pass_real_sample。模型结果只进入任务 result 供人工应用，不会自动覆盖草稿；Qwen-VL 生成 runner 和 Pix2Text 作为完整 PDF OCR 引擎仍按可选占位边界处理。详细设计见 docs/progress/archive/fullstack-refactor.md。
开发预览启动方式：
.\.venv\Scripts\python.exe -m uvicorn apps.api.main:create_app --factory --host 127.0.0.1 --port 8765
cd apps\web
npm install
npm run dev当前 React 入口默认连接 http://127.0.0.1:8765。如果后端端口变化，可设置 VITE_API_BASE。
扫描 PDF
→ MinerU（主引擎）/ PaddleOCR（备用解析）
→ result.md（原始可追溯）
→ obsidian.md（唯一层级、公式安全阅读版）
→ 单题拆分与题型初判
→ SQLite 题库 + 单题证据优先校对 / 知识点 / 难度
↔ Obsidian 单题 Markdown
→ 按四大题型组题
→ 试卷 Markdown + Word + PDF + 参考答案
数据库默认位于项目目录的 local/data/数学题库.sqlite3。旧版 data/数学题库.sqlite3 仍会被兼容读取，方便已有本机题库平滑迁移。它是本地单文件数据库，不需要安装 MySQL 或启动任何服务；复制这个文件即可备份题库。题干、原图、原始 Markdown 则始终保留在转换输出目录，便于回到原稿校对。
项目将本机资料集中放在 local/，避免根目录混入样本、缓存和导出物：
local/input-pdfs/：默认 PDF 输入样本目录；local/conversions/：每份 PDF 的转换工作区，用于保留可追溯原稿和审校工件；旧版output/仍可被读取；local/exports/papers/：默认组卷导出目录；旧版outputs/papers/仍可下载；local/runtime/：上传分片、任务缓存、模型缓存、页图缓存等可再生运行态；local/data/：SQLite 题库和任务状态；local/references/：参考项目和临时资料副本。
对 local/input-pdfs/algebra.pdf，转换输出为：
local/conversions/
algebra/
result.md # 主 Markdown；公式与表格由 MinerU 生成
clean.md # 可编辑的标准阅读稿（与 Obsidian 阅读版一致）
obsidian.md # 为 Obsidian 清洗的阅读版，题号为唯一层级编号
formula-review.md # 不安全 OCR 公式的人工校对清单
obsidian.css # 可选 Obsidian 公式排版 CSS
metadata.json # 引擎、原 PDF、题目数与校对工件索引
questions.jsonl # 一题一行的结构化题库导出
questions/ # 每题一个独立 Markdown 文件
review/
review.md # 公式、图片、题号等疑似问题清单
review.json # 可被后续程序读取的校对信号
review.html # 可离线打开的校对概览
images/ # 从 MinerU 结果复制的图、几何图、函数图等
logs/
mineru.stdout.log / mineru.stderr.log # MinerU 时生成
paddleocr.stdout.log / paddleocr.stderr.log # PaddleOCR 时生成
conversion.json # 成功时生成
error.log # 失败时生成
batch.log
summary.json
Markdown 中的本地图片会被改写为 images/... 相对路径。公式、表格和段落结构保留 MinerU 的原始表达；例如 MinerU 通常输出 $...$ / $$...$$ LaTeX 公式和 HTML 表格。不同 Markdown 渲染器对公式分隔符的支持不同，建议使用支持 MathJax/KaTeX 的渲染器。
- Windows 10/11、WSL2 或 Linux。
- 批处理封装支持 Python 3.9+；MinerU 3.4 建议使用独立的 Python 3.10+ 虚拟环境。当前 MinerU 版本的 Python、PyTorch、CUDA 支持范围可能变化，请以其官方安装说明为准。
- 已安装可在终端运行的 MinerU CLI。若在另一台 Windows + NVIDIA 机器上从零安装，可使用项目中已验证的依赖组合：
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r .\requirements-windows-gpu.txt如果 mineru --version 能运行，即表示 CLI 已就绪。没有 NVIDIA GPU 时，按 MinerU 官方的 CPU/Windows 指引安装；长文档会明显更慢。WSL2/Docker 也可以，只要容器或 Linux 环境内能调用 mineru。
本项目当前已安装并验证：MinerU 3.4.0、Streamlit 1.58.0、CUDA 12.1 PyTorch 2.5.1；检测到 RTX 3090 且 CUDA 可用。首次执行某个 MinerU 后端时，它还会下载对应模型，请预留磁盘空间并保持网络畅通。
若 MinerU 的安装说明修改了 CLI 参数，本项目仍通过
--mineru-command支持指定自定义启动脚本；默认调用方式为mineru -p <pdf> -o <raw-output> -m auto。
在项目根目录执行：
pip install -e .这只安装批处理封装本身；MinerU 仍按上一节单独安装，以便选择符合 CPU/GPU 的版本。
在项目根目录直接双击 00_START_MATHFORGE.bat。它是一个简单菜单，不重新实现业务逻辑，只把 WebUI 常用入口放到一起：推荐主界面、FastAPI 后端、React 开发界面、API+React 双窗口、React 构建、旧 Streamlit 兼容壳、最终发布审计和 1.0 文档。本项目当前不再保留 exe 启动方式。
安装完成后，在 PowerShell 执行；该脚本会调用同一份 launcher.py，因此也会优先打开 FastAPI + React，缺少 apps/web/dist/index.html 时才回退 Streamlit：
.\start_ui.ps1如遇 PowerShell 执行策略限制，改用：
powershell -ExecutionPolicy Bypass -File .\start_ui.ps1通常浏览器会打开 http://127.0.0.1:8501；若旧版本服务仍占用该端口，新启动器会自动打开 8502–8520 中的可用端口。启动后先进入 “总览”：这里展示 MinerU / PaddleOCR 的实际可用状态、已转换来源数、题库单题数、待校对数、已建试卷数和最近来源的审校信号；它还明确区分转换工作区、导出目录和运行态缓存。
界面使用固定的左侧竖向导航，避免长文档把顶部导航滚出可点击区域；五个工作区为：
- 总览：确认环境、数据资产和推荐的下一步。
- PDF 识别与 Markdown：选择引擎、来源、识别范围和输出目录，实时查看日志与转换产物。
- 图片/文本快速入库：上传题目截图、TXT、Markdown、LaTeX，或直接粘贴整理好的题目，快速变成题库候选。
- 单题校对工作台：按来源 PDF、章节/方法和校对队列定位单题；顶部优先完整显示原 PDF 页或题目裁剪，下方再进行题目列表筛选与 Markdown 编辑/预览/审校记录。
- 题库、Obsidian 与组卷：导入拆题、人工校对与分类、组卷导出、Obsidian 同步、数据规则。
“PDF 识别与 Markdown”支持：
- 点击“浏览…”打开 Windows 系统文件夹选择框来选输入/输出目录，也可直接上传多个 PDF；选择框不可用时仍可手动填写路径；
- 上传 PDF 前会显示文件数量、总体积和超大文件提示；React 端默认使用分片上传协议，已上传分片会落盘到
local/runtime/api_uploads/chunks/以支持中断后续传，上传过程中有进度条，并可在后端任务创建前取消上传，避免大文件提交时像“卡死”； - 选择
pipeline、hybrid-engine或vlm-engine，以及单份 PDF 超时； - 像专业 PDF 解析产品一样明确设置：表格转换为 Markdown 表格或保留为图片、图片本地
images/存储、公式分隔符偏好、扫描件 OCR、图表分析、递归扫描、精度等级、跨页表格人工校对提示和自动旋转偏好； - 实时查看固定高度的滚动日志与批量成功/失败统计；MinerU 高频进度行会折叠，只显示每个进度通道的最新状态，完整日志仍保留在结果目录的
logs/； - 查看最近任务队列，按状态、优先级或关键词筛选任务，分页切换历史任务日志；失败任务可按原命令重试，排队/运行中任务可取消；排队中的任务支持高/普通/低三档优先级，高优先任务可让普通/低优先级的外部 OCR 转换进程让出执行槽并重新排队；
- 渲染预览
obsidian.md、clean.md、公式审校清单和结构审校信号；下载 Markdown 或单题 JSONL。
转换工作区会把最后一次修改后的引擎、MinerU 后端、精度、PDF 类型、Paddle 设备、表格模式、图片存储、公式/图表选项、递归开关、超时、来源模式、任务优先级和输入/输出目录自动写入本机的设置文件。新安装默认位于 local/data/conversion_settings.json；旧版 data/conversion_settings.json 仍可兼容。下次打开工作台会恢复这些选择，不需要重新填写长路径。侧栏仍提供“保存当前设置”和“恢复默认”两个按钮；上传的临时 PDF 文件本身不会被记入设置。
设置文件有独立的版本、白名单校验和原子写入：即使浏览器刷新中断或文件内容被意外改坏，也会安全回退到默认设置，而不会影响题库 SQLite 数据。
长 Markdown、PDF 原页和单题编辑器都在独立滚动框中显示，不会让整页无限变长。左侧导航始终保留“返回页面顶部”链接。升级代码后如浏览器仍显示旧报错，请关闭旧的工作台服务/浏览器标签后重新双击启动器，以清除 Streamlit 的旧模块缓存。
许可证：MIT。默认本地 WebUI 不需要 OpenAI、云 OCR 或其他付费 API key；可选模型/视觉引擎只在你本机安装对应依赖和权重后才会运行，缺失时会明确失败，不会伪造 OCR 输出。可参考 .env.example 查看少量可选环境变量。
本项目已按代码仓库方式整理：.gitignore 会排除 .venv/、local/、旧版 output/ / outputs/ / work/ / data/ / pdfs/、本地转换资产、SQLite 数据库和参考项目副本，避免把个人题库、原始 PDF 或运行缓存误提交。
如果本机已安装并登录 GitHub CLI，可直接运行：
.\scripts\publish_github.ps1发布脚本默认会以当前目录名创建 private GitHub 仓库，绑定 origin 并推送 main；这是为了先保护个人题库和本地样本。准备公开时请先完成密钥、路径、个人数据和大文件检查，再显式指定可见性：
.\scripts\publish_github.ps1 -RepoName MathForge -Visibility public若提示 GitHub CLI 未登录，先执行：
"C:\Program Files\GitHub CLI\gh.exe" auth login --hostname github.com --git-protocol https --web网页登录完成后重新运行发布脚本即可。Codex 应用内连接 GitHub 和本机 gh 的认证环境不同；创建远程仓库需要本机 GitHub CLI 或可用 token。
打开界面后切换到 “题库、Obsidian 与组卷”。其中有五个明确步骤：
- 导入与拆题：选择一个转换目录中的
obsidian.md；若尚未生成阅读版，列表会自动回退显示clean.md或result.md，不会漏掉新转换来源。可先点击“重新生成层级化 Obsidian 阅读版”，它会把重复的习题1改成例如习题 2.3.4-01，层级为“章 → 节 → 方法 → 单题”。随后导入 SQLite。 - 校对与分类：系统会初判
单选题 / 多选题 / 填空题 / 解答题 / 待确认，并记录置信度。这里可编辑题干、答案、解析、难度、状态、标签、知识点和来源 PDF 页码。填写页码后会显示左侧原页、右侧题目 Markdown；还可单独抽取该页交给 MinerU 重试，重试结果不会自动覆盖题库。 - 组题与导出：选择题目创建试卷。React 组卷页支持题目预览、上移/下移排序、按题型自动分区排序、逐题设置分区标题/分值/是否带答案，并写出
试卷.md、试卷.docx、试卷.pdf以及对应参考答案；历史试卷也可一键按当前导出目录重新导出。 - Obsidian 联动：导出后，Obsidian 仓库中会有
题库/下的单题 Markdown、题库索引.md和assets/<来源ID>/图片副本；本地图片会改写为 Obsidian 的![[assets/...]]嵌入，不依赖原转换目录。修改题干、答案、解析、标签、知识点后点击“导入 Obsidian 中的修改”即可回写 SQLite。 - 数据与规则：显示数据库位置和当前题库的规则说明。
data/和默认obsidian_vault/已被 Git 忽略，避免把个人题库误提交到代码仓库。
导入页同时支持“已有转换结果”联动、“选择 Markdown…”和“选择转换目录…”三种方式，不再需要粘贴长路径。保存题目、重新导入和刷新来源列表都会自动刷新当前列表。对于高考卷、练习册等 OCR 未生成“习题/例题/题目”标题的来源，可勾选“编号兜底拆分”：它仅识别位于题目区域的 1.、2、、3 空格 等连续编号，要求至少两题才生效，并给结果加上 自动编号切分 标签；这些题必须人工校对，不会被自动发布。点击“预览拆分候选”会在导入前列出题号、题型初判、标签和切片长度，异常长的切片应先回到 Markdown 修订或拆分后再写入 SQLite。
转换结果预览页还提供“导入此结果到题库”快捷按钮。导入成功后会直接跳至题库页并刷新来源；该来源随后会出现在单题校对工作台的“来源 PDF”下拉列表中。识别成功但未导入题库的 PDF 不会出现在该下拉列表，这是为了避免把尚未拆题的原稿误当作可校对单题。
工作区 “图片/文本快速入库” 是参考 Zpdf“图片解析”入口后保留下来的本地化功能：它只做题库需要的素材录入，不做积分、登录、云存储或 30 天 URL。
- 直接粘贴纯文本、Markdown 或 LaTeX；没有题号的单段内容会被包装为一题，已有标题或连续编号的内容会按多题切分；
- 上传或拖拽一个或多个
.txt、.md、.markdown、.tex文件；React 端会通过/api/intake/files以 multipart 传给后端，由后端统一处理 UTF-8、UTF-8 BOM、GB18030 和 UTF-16 编码，避免浏览器端硬猜中文文本编码； - 上传多张
.png、.jpg、.webp等截图。可选择将每张截图作为一题，或把多图合并为同一题的图形资产； - “直接保存并入库”不需要 OCR，适合已经整理好的文字或只想先保留题图；图片会复制到本地手动素材目录，并尽可能生成多页原图 PDF，供证据优先的校对工作台查看；
- “图片 OCR 后入库（MinerU）”会把图片先暂存到
local/runtime/image_ocr_staging/，再打包成临时本地 PDF，用 MinerU 的pipeline + ocr识别后导入。快速入库页提供暂存目录盘点和清理按钮：默认先 dry-run 显示可清理空间，只有点击执行清理才删除不再被排队/运行中任务引用的imgocr_*暂存目录；完整 OCR 日志仍保留在手动素材目录。
外部素材统一保存于 local/runtime/manual_imports/，题库只保存可检索字段；每次导入均可在来源下拉列表中找到，后续仍可编辑、加标签、联动 Obsidian、组卷与导出。Streamlit 兼容界面支持文件选择与拖拽上传；React 快速入库页支持三条入口：/api/intake/files 用于 TXT/MD/TEX 与图片文件混合入库，浏览器 Ctrl+V 剪贴板截图可通过 /api/intake/images 直接保存为题图证据，也可通过 /api/intake/images/ocr-task 排入统一 image_ocr 任务队列，用本地 MinerU OCR 后自动导入题库，并可通过 /api/intake/images/ocr-staging 与 /api/intake/images/ocr-staging/cleanup 维护暂存目录。
总览中的“题库单题”“待人工校对”及公式/结构/图片队列按钮会进入这个工作区。它是日常人工校对的主界面：
顶部：原 PDF 页 / 单题裁剪 / PDF 目录 / 缩略图 / 搜索跳页，优先保证原始证据完整可见
下左：来源 PDF → 章节 / 方法 → 单题队列与上一题 / 下一题
下右：题干、答案、解析的 Markdown 编辑器 → 公式诊断 → 标签/知识点/审校信号 → 保存
每次保存会写回 SQLite，记录 api_save 审校日志；“保存并标记已校对”会记录 api_reviewed 并将状态更新为 reviewed。当前支持的状态为 needs_review、formula_check、image_check、structure_check、reviewed、draft、published 和 archived。新的或迁移的题目会根据可解释的信号（例如公式待校对占位、未闭合 $、复杂数组命令、乱码）自动加入公式/结构待核队列；这只是排序线索，绝不代替人工判断。
左侧题目列表支持按来源、状态、题型、审校信号、知识点和关键词组合筛选；关键词输入会以轻量防抖自动刷新，也可以点击“立即刷新列表”。勾选多题后可批量处理：可以一次性设置状态、题型、难度，也可以批量添加/移除标签、知识点和审校信号，或将当前筛选列表中的多题批量标记为已校对。批量操作走 PATCH /api/questions/batch，后端在 SQLite 事务中复用同一套标签/知识点目录和 review_logs 记录，不通过前端循环调用单题保存来“假装批量”。同一侧栏也提供 Obsidian 联动面板：可导出到项目默认 obsidian_vault/ 或自定义 Vault 路径，并从已导出的单题 Markdown 回写题干、答案、解析、标签、知识点、状态和 bbox。
右侧编辑区包含“审校历史”时间线，直接读取 GET /api/questions/{question_id}/review-logs。保存、批量分类、证据定位确认和 Obsidian 回写都会出现在这里；历史列表固定高度滚动，不会把校对页面无限拉长。
bbox 是可选的归一化坐标 x0,y0,x1,y1，每个值在 0 到 1 之间。没有 bbox 时，系统明确回退到整页模式，不会假装能够可靠地自动裁剪单题。页码和 bbox 均可在顶部证据区确认后保存，题目内容则在下方编辑区保存。
题目数据采用可扩展的分层结构：
来源层：documents（原 PDF、转换 Markdown、引擎、时间）
单题层：questions（题干、答案、解析、题型、难度、状态、页码、bbox）
目录层：tag_catalog、knowledge_catalog（全局可维护的标签与知识点目录）
关系层：question_tags、question_knowledge、papers、paper_questions
审校层：review_logs（保存、批量分类、Obsidian 同步、标记已校对）
资产层：转换目录的 images/；单题 Markdown 与 questions.jsonl 保持可移植
题目拆分采用保守策略：仅明确的“习题 / 例题 / 题目 / 练习 / 小题”标题会开始一个新题，避免将公式编号误切成题目。自动题型初判只提供起点；“多选”“填空”“证明/求证/解答”等显式文字优先，四个选项但没有“多选”标记的题会暂定为单选并给出较低置信度。
每次转换或重新导入还会生成校对工件：未闭合 $、不平衡公式花括号、复杂公式待校对标记、缺失图片引用、孤立图片、重复题号与题号跳号都会被列入 review/review.md。这些是疑似问题，不会自动修改题干或公式。原 PDF 页预览使用本地 PDFium 按需生成，只渲染当前正在校对的页面，不会预先把数百页全部转成图片。
Word/PDF 导出会将常用 LaTeX 符号转换为可读文本，并始终同时保留 Markdown 原稿。复杂 OCR 公式的最终版式应以 Obsidian/Markdown 校对稿为准；不能在没有人工确认的情况下伪造 Word 原生公式，这会有改变数学含义的风险。
首次使用某个 MinerU 后端或 PaddleOCR 时会下载并初始化模型，可能需要数分钟。界面会实时显示当前引擎日志；处理期间请保持页面打开。Windows 中文文件名的日志已按 UTF-8 传递，避免显示乱码。
所有操作都在本机完成。上传 PDF 仅会暂存到项目的 local/runtime/api_uploads/，不会发送到网络。
对于大多数扫描数学题，建议从 pipeline + ocr 开始；有 RTX 3090 等较大显存 GPU 时，可试用 hybrid-engine + high 改善复杂图表和版面，但首次运行需要下载更多模型且更耗时。
将 PDF 放入 ./local/input-pdfs 后：
python main.py --input ./local/input-pdfs --output ./local/conversions或安装后：
mathforge --input .\local\input-pdfs --output .\local\conversions --recursive常用选项：
--method auto|ocr|txt 默认 auto；扫描件通常选 auto 或 ocr
--engine mineru|paddleocr 本地文档解析引擎；默认 mineru
--backend pipeline|hybrid-engine|vlm-engine
--effort medium|high 只影响 hybrid-engine
--lang ch 文档语言；默认中文
--no-formula 关闭公式识别
--no-table 关闭表格识别
--no-image-analysis 关闭图表分析
--recursive 包含子文件夹 PDF
--timeout 1800 单份 PDF 超时（秒）
--mineru-command <路径> 指定 mineru.exe 或启动脚本
--paddle-device gpu:0|cpu PaddleOCR 设备（仅 PaddleOCR 引擎）
若某一份 PDF 失败，程序仍会继续。失败详情位于该 PDF 的 logs/error.log、当前引擎日志位于 logs/（MinerU 为 mineru.stderr.log，PaddleOCR 为 paddleocr.stderr.log），批次汇总位于 local/conversions/summary.json。批次里同名 PDF 会自动输出为 文件名、文件名-2，避免覆盖。
本项目的基础测试不需要安装 MinerU：
python -m pip install pytest
python -m pytest要做真实的端到端测试，准备一份清晰 PDF 后运行：
python main.py --input .\sample_pdfs --output .\sample_output --method auto检查 sample_output/<文件名>/result.md 是否存在，图片是否位于 images/，以及 summary.json 中状态是否为 success。
扫描质量决定上限。低分辨率、倾斜、透视变形、阴影、模糊页、复杂手写、密集双栏、特殊字体或很复杂的几何图，都可能造成文字、题号、公式、阅读顺序或表格错误。几何图、函数图和复杂图片会尽量以图片资产保留而不是强行转写，但仍应对最终 Markdown 人工校对，并按原 PDF 核验公式与题号。
src/pdf_markdown_cli/ocr_engines/base.py 定义了统一的 OCREngine 接口，ocr_engines/registry.py 负责注册 MinerU、PaddleOCR 以及 Marker/olmOCR/Qwen-VL/Pix2Text 可选适配器。PaddleOCREngine 已实现为 PaddleOCR PP-StructureV3 的本地备用文档解析器；它和 MinerU 输出相同的 result.md / images / logs / obsidian.md 目录约定，因此可在界面中显式切换，而不会破坏后续拆题、题库或组卷流程。Marker/olmOCR/Qwen-VL/Pix2Text 目前通过注册表、/api/ocr-engines、/api/ocr-engines/health 和 /api/ocr-engines/{engine_key}/install-plan 暴露可用性、Python 包/命令探测、官方安装计划、推荐隔离方式与缺失原因；未安装本地模型或命令时会明确失败，不会伪造 OCR 结果，也不会自动下载模型。发布审计可运行 scripts/verify_optional_ocr_runners.py，生成 docs/progress/releases/v1.0.0/artifacts/optional-ocr-runner-verification.json，记录当前机器上可选 PDF/视觉引擎究竟是缺依赖、占位适配器，还是需要真实样本验证。
PaddleOCR 是可选依赖，默认不会影响已验证的 MinerU 环境。当前工作台会在“总览”和“⑤ 数据与规则”中直接显示它是否已安装；未安装时界面会阻止使用 PaddleOCR 开始转换。需要启用时，在项目虚拟环境中执行：
.\.venv\Scripts\python.exe -m pip install -r .\requirements-paddleocr.txt不想打开终端时，在工作台的 “题库、Obsidian 与组卷 → ⑤ 数据与规则” 点击 “安装 PaddleOCR 备用引擎” 即可。安装后刷新界面，在左侧“解析引擎”选择 PaddleOCR（备用解析）。PaddleOCR 会在首次运行时下载 PP-StructureV3 需要的模型；如果当前机器没有可用的 Paddle GPU 运行时，将“Paddle 设备”填为 cpu。PaddleOCR 3.x 的接口更新较快，适配器会在启动时检查 PPStructureV3 是否存在，并在不兼容时给出明确错误而不是静默降级。
SQLite 中包含 documents、questions、tag_catalog、knowledge_catalog、question_tags、question_knowledge、papers、paper_questions、paper_templates 等核心记录。每道题有稳定 ID、来源 Markdown 层级、原始题块、可编辑题干/答案/解析、题型置信度、难度、审核状态、标签和知识点；标签与知识点先进入全局目录，再通过关系表挂到题目上，便于泡泡选择、重命名、删除和后续知识树扩展。每张试卷只保存题目引用与顺序，因此修改题目后可重新导出，不会复制出多份失控文本；试卷模板只保存组卷配置，不复制题目内容，导出仍复用同一个 PaperExporter。
后续新增能力（例如教材知识树、难度统计、错题本、选题约束、答题卡版式主题、题目图片裁切、局部 OCR 重跑或本地大模型辅助打标签）应建立在这些字段和服务层上，不需要改动 MinerU/PaddleOCR 的转换代码。批量分类也已经沉淀在 QuestionBankDatabase.batch_update_questions() 这个深接口上，前端只提交题目 ID 和变更意图，标签目录、关系表与审校日志均由数据库层统一维护。
本版本（0.8.7）已经实现并在工作台或新全栈基座中暴露：MinerU 主转换、可选 PaddleOCR 备用转换、Zpdf 风格但本地化的 PDF 解析设置、Markdown 清洗、审校信号、SQLite 单题库、证据优先的单题校对工作台、审校日志、独立图片/文本/LaTeX 快速入库、原生文件夹/Markdown 选择器、固定左侧导航、可滚动长文档预览、单选/多选/填空/解答/待确认题型、人工分类、Obsidian 双向同步、按四类题型分区组卷及 Markdown / Word / PDF 导出，可校验、自动恢复的本地转换设置，以及 apps/api + apps/web 的可运行全栈基座。
1.0 的停止条件不再按“无限功能清单”定义，而按本地离线数学题库产品能否长期稳定使用来验收；逐项标准见 docs/progress/releases/v1.0.0/ACCEPTANCE.md。发布审计可运行 scripts/run_release_sample_acceptance.py，生成 docs/progress/releases/v1.0.0/artifacts/release-sample-acceptance.json，记录受控样本从 OCR-like Markdown/source PDF evidence 到题库复核、组卷和 Markdown/Word/PDF/答题卡导出的闭环；真实局部公式模型样本由 scripts/verify_formula_runner_real_sample.py 单独记录。
V1.0.0 已冻结的 FastAPI 与 React 能力包括：统计、转换资产、转换资产一键导入题库、转换目录完整日志聚合下载、非标准 Markdown 整篇兜底为单题、来源文档、题目列表、单题读取、单题保存、局部公式复核建议、Pix2Text/Qwen-VL 局部公式模型复核任务框架、批量题目分类与审校、Obsidian 导出与回写、来源页码与 bbox 保存、审校日志、审校队列计数、按审校信号过滤、标签目录新增/重命名/删除、知识点目录新增/重命名/删除、题型/难度/状态/标签/知识点字典、PDF 总页数、书签目录、原 PDF 文件流、PDF 文本层搜索、扫描件题库 OCR 文本索引兜底、转换资产导入前 OCR Markdown 搜索、未导入本地扫描 PDF 的显式 OCR 搜索索引任务与缓存、PDF OCR 索引缓存 dry-run/apply 清理、OCR 索引搜索质量反馈、按 DPI 隔离缓存的证据页渲染、Markdown 同目录图片资产代理、外部文本/Markdown/LaTeX 快速入库、base64 图片/截图快速入库、图片 OCR 异步入库任务、图片 OCR staging dry-run/apply 清理入口、转换设置保存，以及 POST /api/tasks/conversions 本地文件夹转换任务、POST /api/tasks/conversions/upload 兼容 multipart 上传 PDF 转换任务、POST /api/tasks/conversions/uploads/chunks/start、PUT /api/tasks/conversions/uploads/chunks/{upload_id}/{file_index}/{chunk_index}、POST /api/tasks/conversions/uploads/chunks/{upload_id}/complete 分片续传转换任务、POST /api/questions/{question_id}/formula-rerun-task、GET /api/pdf-ocr-index/status、POST /api/pdf-ocr-index/tasks、POST /api/pdf-ocr-index/page-refinement-task、GET /api/pdf-ocr-index/search、GET /api/pdf-ocr-index/cache、POST /api/pdf-ocr-index/cache/cleanup、GET /api/tasks 任务列表、GET /api/tasks/settings 队列并发策略、GET /api/tasks/{task_id} 任务状态、GET /api/tasks/{task_id}/events SSE 日志事件、GET /api/tasks/{task_id}/logs.txt 日志下载、GET /api/tasks/{task_id}/logs/search 完整任务日志搜索、POST /api/tasks/{task_id}/cancel 任务取消和 POST /api/tasks/{task_id}/retry 任务重试。组卷能力也已沉淀为 GET /api/papers、POST /api/papers、GET /api/papers/{paper_id}、POST /api/papers/{paper_id}/export、POST /api/papers/{paper_id}/export-task、GET /api/paper-exports/file、GET /api/paper-templates、POST /api/paper-templates、GET /api/paper-templates/{template_id}、DELETE /api/paper-templates/{template_id}、GET /api/paper-answer-sheet-themes 和答题卡主题模板市场/云协作占位接口，复用现有 SQLite 题库和 PaperExporter 导出试卷 Markdown、参考答案 Markdown、基础/紧凑/留白/自定义答题卡 Markdown、基础/紧凑/留白/自定义答题卡 Word、基础/紧凑/留白/自定义答题卡 PDF、试卷 Word、试卷 PDF、参考答案 PDF 与导出清单 JSON；导出清单会记录题量、总分、分区统计、题型统计、每个分区内的题目 ID/编号/标题/题型/分值/答案开关、结果文件名和自定义答题卡主题参数。React 组卷页已支持题目预览、模板管理、模板预览、分区规则编辑、答题卡主题可视化编辑、题型与分值统计、导出前检查、结果文件直接下载、结果路径复制、@dnd-kit 拖拽排序、上移/下移排序、按题型自动分区排序、逐题设置分区标题/分值/是否带答案，并通过统一任务队列异步显示试卷导出进度与结果文件。任务记录保存到 data/api_tasks.sqlite3，API 重启后历史任务仍可查看；本地 OCR 任务默认单执行槽排队，也可在 React 队列面板调整为 1-3 个执行槽，排队任务支持高/普通/低三档优先级，避免多个 MinerU/PaddleOCR 进程无意抢占 GPU。React 前端已经接入这些接口，提供 PDF 解析任务页、外部题目快速入库页、图片 OCR 任务、单题校对、审校信号队列、批量勾选与批量标签/知识点/题型/难度/状态更新、Obsidian Vault 导出/导入面板、react-pdf 标准 PDF 阅读模式、虚拟滚动缩略图侧栏、文本搜索跳页、鼠标拖框 bbox、已保存 bbox 拖拽/八向缩放、CodeMirror Markdown 编辑器、KaTeX 公式预览、本地相对图片预览、可点击定位到题干/答案/解析行号的公式诊断面板、可刷新并应用到草稿的局部公式复核建议面板、模型级公式重跑任务入口、带错误分类和证据行定位的任务失败摘要卡、完整任务日志搜索定位、可创建标签/知识点/审校信号选择器，以及标签/知识点目录维护面板。React 页面已经改为 React.lazy 按需加载，并通过 Vite manual chunks 拆分 PDF 阅读器、标签选择器、Markdown 预览和 CodeMirror 栈，减少首屏负担。
当前仍未彻底完成的重构如下。它们会复用 V0.8 的 API 和 SQLite 服务，而不是继续堆 Streamlit 状态逻辑：
| 模块 | 当前状态 | 尚未完成 | 下一步 |
|---|---|---|---|
| React PDF 转换页 | 可读取/保存设置、启动本地文件夹转换任务、拖拽/选择 PDF 分片上传并转换、分片落盘续传、上传前体积预检、超大 PDF 本地文件夹优先提示、上传进度条、上传取消、SSE/轮询任务状态、显示短窗口滚动日志、转换资产一键导入题库；分片上传已覆盖取消后干净重启、API 重启后继续上传、主清单损坏时从 manifest.json.bak 自动修复、主备清单均损坏时返回取消重来提示、缺失分片修复提示等契约测试；Playwright mock E2E 已覆盖浏览器分片 PUT 网络失败时展示重试/取消重来的恢复提示，并确认失败后仍可点击取消上传清理会话；真实后端 E2E 已覆盖第一分片落盘后刷新续传、主备 manifest 同时损坏时取消坏会话并重新上传、单文件 complete 前 chunk 文件丢失时显示缺块提示并补传成功、多文件上传中第二份 PDF 缺 chunk 后只补传缺块并完成、合并阶段磁盘写入失败后显示本机磁盘/权限恢复建议并可重试成功，以及 complete 已创建任务但响应丢失后重试返回同一个 task_id，以及真正任务创建前 settings 校验失败后显示错误并通过原会话重试成功；刷新标签页后会恢复未完成上传会话提示，用户重新选择同一批 PDF 后可沿用原 resume_key 继续上传；导入成功后会自动切到单题校对页 |
超大 PDF 通过浏览器仍会占用前端网络和临时磁盘，批量大文件更推荐本地文件夹模式；浏览器刷新后不会保存 PDF 文件内容，必须由用户重新选择本地文件 | 仍不从任意残留 chunk 文件猜测重建清单；主备清单都损坏时需取消后重来 |
| 任务队列 | FastAPI 线程任务 + SQLite 历史记录，可返回命令、状态、优先级、日志尾部、失败分类、证据行和建议，支持本地文件夹和上传 PDF 两种来源，并支持取消/重试；React 已提供最近任务队列面板，可按状态/关键词/优先级筛选、分页、切换历史任务查看日志；默认单执行槽排队，也可在面板里配置 1-3 个执行槽；排队任务可取消，高/普通/低优先级会决定下一个启动项；高优先任务可抢占普通/低优先级的外部 OCR 转换进程，被抢占任务会按原命令重新排队；API 重启后会把可恢复的外部 OCR 转换任务按原命令恢复为 queued 并重新调度；paper_export 与 image_ocr 已改为带持久化 payload 的 durable 内部任务，API 重启后可按保存参数重新排队执行 |
匿名进程内 callable 任务仍没有可持久化 runner；内部任务也不做强制抢占 | 后续如需恢复更多内部任务，需把任务参数改造成 durable payload 或外部命令 |
| 实时日志 | React 优先使用 GET /api/tasks/{id}/events SSE 流式日志，断开时退回轮询；日志框固定高度并显示可定位窗口，可下载 API 任务日志；GET /api/tasks/{task_id}/logs/search 可搜索持久化任务日志并跳到旧错误行；历史转换资产可聚合下载 logs/*.log、batch.log、summary.json；失败任务会显示摘要卡、错误分类、匹配证据行、常见修复建议，并可一键跳到当前日志窗口内的命中行；已能识别 Marker/olmOCR/Qwen-VL/Pix2Text 可选引擎缺依赖、模型环境缺失和占位适配器尚未接真实运行器等错误 |
失败摘要仍是规则匹配，不能覆盖所有第三方模型运行时异常 | 持续从真实日志补充第三方模型错误模式 |
| PDF 阅读器 | 已接入 react-pdf 标准阅读模式；保留页图裁剪模式、总页数、书签目录、页码跳转、PDF 文本层搜索、扫描件题库 OCR 文本索引兜底、转换资产导入前 OCR Markdown 搜索、未导入本地扫描 PDF 的显式 OCR 搜索索引任务与 local/runtime/pdf_ocr_search_index/ 缓存、页级 OCR refinement 任务入口、索引缓存 dry-run/apply 清理、基于命中数/文本行数/字符数/查询长度的索引搜索质量反馈、虚拟滚动缩略图侧栏、bbox 框选、已保存 bbox 拖拽移动和八向缩放 |
OCR 索引和页级 refinement 仍依赖本机 MinerU/PaddleOCR/可选引擎实际可用；页级任务只把单页渲染后交给现有图片 OCR 队列，不自动改题库、不做 OCR 准确率评测 | 后续接真实局部公式/视觉模型 runner，并继续补真实失败样本 |
| Markdown/公式编辑器 | 题干、答案、解析已使用 CodeMirror；已接入 react-markdown + remark-math + KaTeX 的编辑 / 分屏 / 预览模式；相对图片路径会通过受限本地资产接口解析；公式诊断可提示未闭合 $、OCR 乱码、脆弱命令、过长公式、括号不平衡和 KaTeX parse 失败，可一键加入公式待核，也可点击“定位”跳到对应字段的对应行；GET /api/questions/{question_id}/formula-review 会返回本地规则型局部复核建议，React 可把确定性替换应用到草稿并继续要求人工保存；POST /api/questions/{question_id}/formula-evidence 可从原 PDF 页和 bbox 裁剪公式证据图；POST /api/questions/{question_id}/formula-rerun-task 可把证据图排入 Pix2Text/Qwen-VL 模型复核任务并在统一任务面板展示日志/失败摘要；后端已有 pdf_markdown_cli.formula_runners，Round 42 在本机安装 Pix2Text 后已通过 recognize_formula(image_path) 真实样本并返回 manual-apply result |
仍不是完整 LaTeX 文档编译器；Qwen-VL 仍要求显式模型路径且不自动下载权重；模型结果不会自动回写 Markdown，也不承诺自动正确 | 后续可做人工确认式结果合并和更多真实样本 |
| 图片 OCR 队列 | 图片/截图可直接保存为题图证据，也可通过 durable image_ocr 任务交给本地 MinerU OCR 后自动入库；图片 OCR 任务会先把图片落盘到 local/runtime/image_ocr_staging/ 并把 manifest 路径写入任务 payload，避免大批图片 base64 直接膨胀 SQLite；API 重启后可按保存的标题、manifest 路径、MinerU 命令和超时重新排队；React 快速入库页会显示任务尾部日志并可下载任务日志，并可 dry-run 盘点/显式 apply 清理不再被 queued/running 任务引用的 imgocr_* 暂存目录；最近任务队列已支持本页批量选择、批量取消 queued/running 任务、批量重试失败的 conversion 任务；单题校对页已有本地规则型公式复核与替换建议，以及 Pix2Text/Qwen-VL 模型级公式复核任务入口；后端 formula runner 已要求 evidence image，并能从来源 PDF/bbox 生成该证据图，避免把 Markdown 行文本当成 OCR 输入 |
批量队列管理仍未覆盖内部任务强制抢占；真实 OCR 批次编排仍按具体引擎逐步扩展 | 后续增加更完整的 OCR 批次编排和更多真实模型样本 |
| 组卷与导出 | SQLite 已保存试卷、题目引用和 paper_templates；FastAPI 已暴露列表、创建、详情、同步导出、paper_export 异步导出任务、默认导出目录文件下载、模板 CRUD、答题卡主题预设接口，以及答题卡主题模板市场/云协作占位接口；导出复用 PaperExporter 写出试卷 Markdown、参考答案 Markdown、基础/紧凑/留白/自定义答题卡 Markdown、基础/紧凑/留白/自定义答题卡 Word、基础/紧凑/留白/自定义答题卡 PDF、试卷 Word、试卷 PDF、参考答案 PDF 与导出清单 JSON；React 组卷页支持题目预览、模板管理、模板预览、分区规则编辑、答题卡主题可视化编辑、题型与分值统计、导出前检查、结果文件下载、结果路径复制、@dnd-kit 拖拽排序、上移/下移排序、按题型自动分区排序、逐题设置分区标题/分值/是否带答案，并显示导出任务尾部日志与结果文件；内置校级周测、月考和主观题留白模板，模板可保存自定义答题卡主题 |
模板市场与云端多人协作只保留 extension_placeholder 接口，不实现云服务、账号或多人同步 |
除非后续明确需要云协作，否则继续保持本地模板管理 |
| 多引擎增强 | MinerU 主引擎、PaddleOCR 备用引擎；OCREngine 注册表已暴露 Marker/olmOCR/Qwen-VL/Pix2Text 可选适配器、可用性检查、健康检查、安装计划和清晰缺失原因，CLI/API/React 不再硬编码两项；React PDF 转换页会展示模型环境健康检查、包/命令探测、官方文档和建议命令；局部公式模型复核队列已复用这些健康事实判断 Pix2Text/Qwen-VL 是否可用；scripts/verify_optional_ocr_runners.py 可把当前发布机器的可选 runner 状态写成 JSON 证据 |
Marker/olmOCR/Qwen-VL/Pix2Text 的真实本地运行器仍依赖用户安装对应模型、命令或 Python 包；当前框架只做检查、安装计划、任务编排和发布证据记录，不自动安装、不下载模型、不伪造推理结果 | 按具体本地运行环境补充真实 convert_pdf_to_markdown 与局部公式 Pix2Text/Qwen-VL runner |
| WebUI 启动 | 根目录 00_START_MATHFORGE.bat、start_ui.ps1 和 launcher.py 都优先启动 FastAPI + React 构建产物，缺少 dist 时回退 Streamlit 兼容壳；launcher smoke 已覆盖 fullstack 选择、Streamlit fallback、当前服务复用和 stale marker 清理 |
不再保留 exe 启动方式；仍不是 Tauri 原生壳；没有托盘/显式后台关闭按钮，这部分不作为 1.0 必需项 | 1.0 保持轻量 WebUI 启动器，稳定后再评估 Tauri/托盘化 |
| 前端验证 | 已安装 npm 依赖并通过 npm run build；Vite 已把 PDF 阅读器、标签选择器和 React vendor 分包；已接入 Playwright Chromium smoke E2E，使用 API mock 覆盖首页、PDF 任务诊断、快速入库、单题校对、KaTeX parse 公式诊断、组卷导出页面加载、OCR 索引缓存维护、OCR 索引搜索质量反馈、页级 OCR refinement 任务创建、分片上传 PUT 网络失败后的恢复提示，以及标签页刷新后提示重新选择同一 PDF 并续传；另有 npm run e2e:real 启动临时 FastAPI + SQLite + 真实 PDF，校验 react-pdf canvas 非空像素、真实 PDF 文本层搜索、真实转换资产 OCR Markdown 搜索、真实 Pix2Text 可选/PDF 适配器失败摘要、真实分片上传部分落盘后刷新续传、主备 manifest 双损坏后的浏览器取消/重启恢复、单文件与多文件 complete 前 chunk 文件丢失后的缺块提示与补传恢复、合并阶段磁盘写入失败后的恢复提示与重试成功、complete 响应丢失后的同任务幂等恢复、pre-task settings 校验失败后的恢复重试，以及浏览器端完整组卷导出交互、异步 paper_export 完成、导出文件列表和 manifest 下载解析；API 契约测试覆盖分片上传取消后重启、API 重启后恢复继续上传、损坏清单、缺失分片修复提示、合并阶段写入失败可重试、pre-task 校验失败可重试、PDF OCR 索引缓存清理、搜索质量反馈和页级 OCR refinement 入口 |
现有 1.0 阻塞项已覆盖；后续样本只按真实用户失败继续补充 | 进入 1.0 前保持 final audit 全绿 |
答题卡导出主题目前包括基础答题卡、紧凑答题卡、留白答题卡、校级周测/月考/主观题留白模板和 React 可视化编辑出的自定义答题卡；它们共享同一份组卷结构和导出清单，只改变留白、边距、字号和主观题作答空间。自定义主题会随 paper_templates.answer_sheet_theme_json 保存，下一次应用模板时会同步恢复。
Zpdf 的 PDF 解析页有三个值得学习的点：上传区清晰、处理设置语义明确、历史结果与下载入口集中。本项目吸收这些交互结构，但只保留本地数学题库需要的部分：
- 保留：PDF → Markdown、表格处理模式、图片本地资产、图片识别入口、历史/结果、API 式边界说明；
- 不保留：积分、登录、会员、云端 URL 存图、翻译、AI PPT、在线 API Key 管理；
- 本地替代：图片存储固定为
images/相对路径；历史文件来自local/conversions/（兼容旧output/）与 SQLite；图片解析输出直接进入local/runtime/manual_imports/和题库候选。
V0.5.1 额外修复了两类常见 Streamlit 状态错误：文本控件创建后再写入同名状态、侧栏导航创建后再直接切换工作区。现在改为回调请求与下一轮渲染前应用，避免“session_state ... cannot be modified after the widget ... is instantiated”的红色异常页。
已本地阅读 docutranslate-main 的配置模块、useSettings 设置组合式逻辑和任务界面组织。我们吸收了“集中默认值 + 独立设置存储 + 校验后保存 + 设置导入/恢复边界”的工程方法，而没有直接复制其 Vue 前端、翻译 API 配置或任务队列：本项目的 OCR、题库和 SQLite 都是离线本地工作流，继续保持 Streamlit 作为轻量界面更合适。对应的转换设置逻辑集中在 src/pdf_markdown_cli/settings.py，UI 只负责读取与提交，后续增加 MinerU/PaddleOCR 参数时不需要把持久化逻辑散落到各个页面。
单题校对工作台会为每个原 PDF 在 local/runtime/pdf_navigation/ 建立本地页码文本索引，并读取 PDF 自带书签目录。首次打开一份较长 PDF 时需要少量时间；后续直接复用缓存。阅读器提供总页数、首页/上一页/下一页/末页、页码输入和 PDF 目录跳转。
题目尚未带来源页码时，系统只会给出候选页及匹配置信度，不会自动写入数据库，更不会默认把每题错误地指向第 1 页。核对后点击“确认当前页为本题来源页”才会持久化。编辑器保存时也会同步当前阅读页。
“单题裁剪”在 React 中支持鼠标拖框、拖动已有红框移动，以及拖拽八个控制点进行四边和四角缩放；点击“保存当前页”或保存题目后会保留该题的归一化 bbox。Streamlit 兼容工作台仍保留滑块裁剪入口。这些都不宣称自动识别题目边框，因此仍需要人工确认。
题型、难度、校对状态、审校标记采用泡泡式选择。标签和知识点采用“已选项泡泡 + 可搜索下拉框”，避免几百个历史标签同时铺满编辑区；可以直接输入新标签/知识点并回车。编辑区右上角的“管理标签”可新增标签、全局重命名或删除标签；删除会从所有关联题目移除该标签，因此只应删除确认无用的全局标签。
以下能力尚未实现为自动化功能，因此不会在界面或命令行中虚假承诺：Pix2Text/Qwen-VL 局部公式自动修订、Marker/olmOCR 多引擎自动竞赛、Qwen-VL 自动修订、TikZ/GeoGebra 图形重绘、AI 自动解题。答题卡主题模板市场与云端多人协作只保留占位接口，不进入当前本地离线产品范围。当前局部公式复核建议只是本地规则型草稿辅助；模型级公式重跑入口已有 PDF/bbox evidence crop 和 Pix2Text adapter path，Round 42 已跑通 Pix2Text 真实样本，但结果只作为人工应用建议，不能代替原 PDF/题图核对。识图模型安装/健康检查框架已经能显示官方安装计划、包/命令探测和隔离建议；完整 PDF 级可选模型运行器仍需按具体引擎逐个接入并用样本验收。
界面只暴露命令行后端实际支持的 --engine、--method、--backend、--effort、--paddle-device、--timeout、递归和三个识别开关；命令行仍是批量自动化的完整入口。题库的“单页重试”目前固定使用 MinerU，以便不自动覆盖已人工校对的题库记录。