企业官网建设流程全解析

IELTS Atlas（仓库名IELTS-practice）是一套纯前端的雅思阅读与听力练习系统，支持题库浏览、套题练习、成绩记录、错题分析与数据备份。除了内置题库，它还提供「导入自己的题库」能力：你可以在「系统设置」里一键上传本地文件夹，自动识别阅读 HTML/PDF 与听力 HTML+音频，并生成全量或增量两种自定义题库配置。本文用 6 个步骤，带你从零完成雅思题库导入。

一、导入前先搞懂：全量 vs 增量两种模式

在点击任何按钮前，先理解两种导入模式的区别，避免误操作：

• 创建全量配置：只替换当前类型的索引。导入阅读时，旧的阅读题会被新文件夹覆盖，听力不受影响；反之亦然。适合「整本换新」的场景。
• 创建增量配置：只追加或更新新题目，保留已有题目，适合作业增量补题。

💡配置隔离：每次导入都会创建一套全新的题库配置，旧配置和你的练习记录都保持不动。阅读与听力索引独立更新，另一类型会自动从当前配置继承。也就是说——导入不会覆盖你的历史成绩。

⚠️ 浏览器本地存储按「浏览器 / 协议 / 域名」隔离，file://打开的数据与http://localhost下不一定共享，建议在固定环境操作。

二、一键打开「加载题库」面板

导入入口非常直观，全程只需三步点进去：

1. 用 Chrome 或 Edge 打开项目根目录的index.html（首次请允许弹窗）。
2. 进入「系统设置」，点击「📚 题库管理」入口，打开题库管理弹窗。
3. 在弹窗中点击「📂 加载题库」，弹出「加载题库」窗口，里面并排显示两张卡片：阅读题库（READING）和听力题库（LISTENING）。

入口按钮定义见 js/components/libraryManagerPanel.js，阅读/听力卡片的文案与说明见 js/boot-fallbacks.js#L1181-L1192。

三、导入自定义阅读题库（步骤清单）

阅读卡片提示「从所选文件夹递归识别 HTML/PDF 题源」。按以下清单操作即可：

1. 整理文件夹：把每篇阅读放在独立子文件夹，文件夹内放*.html（或*.pdf）题源文件，同目录可附带图片等素材。
2. 在「阅读题库」卡片点击「创建全量配置」或「创建增量配置」。
3. 在系统弹出的文件夹选择器中，选中你的阅读根文件夹，确认。
4. 系统按目录分组，逐个识别 HTML/PDF 并解析分类（自动识别 P1–P3）、题号、高频/低频标签。
5. 导入完成后，弹窗会展示「导入报告」。

分类与题号的自动推断逻辑见 js/services/libraryDiscovery.js#L137-L160，阅读条目识别见 js/services/libraryDiscovery.js#L380-L416。

四、导入自定义听力题库（步骤清单）

听力卡片提示「从任意层级识别带答案链路的听力 HTML 和音频」。由于版权原因，公开包默认不含听力音频，需你自备资源。操作如下：

1. 准备资源：每个听力单元一个文件夹，内含听力 HTML 页面 + 音频文件（支持mp3 / m4a / wav / ogg / aac / flac / webm）。
2. 在「听力题库」卡片点击「创建全量配置」或「创建增量配置」，选中听力根文件夹（如ListeningPractice/P1–P4）。
3. 系统会扫描 HTML 内容，识别「答案链路」（如CONFIG_DATA/answerKey/finishTest）并关联同目录音频。
4. 自动从路径推断 P1–P4 分类；信号不足或疑似阅读的文件会被「排除」并在报告中说明原因。

听力信号评分与接收判定见 js/services/libraryDiscovery.js#L174-L228，音频文件关联见 js/services/libraryDiscovery.js#L247-L269。

五、查看导入报告并切换题库配置

导入完成后不要急着关掉弹窗，先看「导入报告」：

• 识别题目：成功接收的题目数。
• 排除候选：被过滤的文件数，下方会列出原因（如「听力题源信号不足」「疑似阅读题源」）。
• 新增 / 更新：本次合并到索引中的数量。
• 若出现「外部文件夹题源已用当前会话 Blob URL 打开」提示，说明题目通过会话临时链接加载——刷新浏览器后若原文件夹路径不可访问，请重新选择该文件夹。

确认无误后：

1. 返回「题库管理」弹窗顶部的「题库配置列表」。
2. 找到刚生成的配置（名称形如阅读增量-2026/10/10 …），点击「切换」。
3. 回到「题库浏览」，用类型/分类/关键词筛选，确认新题出现后即可开始练习。

配置列表的切换与删除交互见 js/services/libraryManager.js#L776-L738，合并与去重逻辑见 js/services/libraryDiscovery.js#L583-L618。

六、常见问题（FAQ）

• 导入后题库列表是空的？检查文件夹是否按「每篇一个子文件夹 + 含 HTML/PDF」组织；或先切换回「默认题库」再重新导入。
• 听力题没被识别？多半是 HTML 缺少答案链路信号或没有同目录音频，查看报告中的「排除原因」。
• 换电脑后导入题不见了？导入配置存在浏览器本地存储，需在新环境重新选择文件夹导入；练习记录建议用「导出数据」迁移。
• 频繁移动/重命名文件夹会怎样？可能让历史记录与题目索引对不上，建议导入后保持目录结构稳定。

七、延伸阅读与相关源码

• 架构文档：Library-Management-&-Configuration-System.md
• 题库管理服务：js/services/libraryManager.js
• 题源识别服务：js/services/libraryDiscovery.js
• 题库管理面板：js/components/libraryManagerPanel.js
• 使用说明：README.md

📌 记住核心口诀：整理文件夹 → 选全量/增量 → 查看报告 → 切换配置。按这四步走，你的个人雅思题库就能稳稳跑起来。