yianxue-assistant/README.md

# 谊安学助手 2.0

<!-- repository-metadata:start -->
**中文简介**：谊安学学习辅助脚本，提供课程、题库与练习工具。

**English summary**: Learning userscript for Yianxue courses, question banks and practice.

| 中文标签 | English topic |
| --- | --- |
| 教育 | `education` |
| 用户脚本 | `userscript` |
| 学习助手 | `learning-assistant` |
<!-- repository-metadata:end -->

当前发布版本 **2.1.4**。一个可直接安装的油猴脚本，集成统一题库、六栏面板、视频与考试任务、答案全文核对、复制和题库导出。题库本地保存，内置 ZIP 解析，无 CDN 依赖。

## 安装与启动

1. 安装 Tampermonkey 等兼容用户脚本管理器，打开 [谊安学助手 2.0.user.js](谊安学助手%202.0.user.js) 安装或更新。
2. 打开 `http://10.119.67.7/clientcn/` 下的学习地图、课程、练习或考试页面。
3. 展开右下角面板，在“题库搜索”导入 [统一题库.csv](题库/统一题库.csv)。原 ZIP、三个岗位 CSV、CSV/JSON 仍可导入，无需选择岗位。
4. 若考试标题与题库课程不同，在题库栏建立明确的主题关联。关联使用完整标题和完整题库课程名；相似关键词只提供候选，不授权自动答题。
5. 在“任务总览”选择任务模式、顺序或并行，点击“开始本轮”。新安装默认“视频＋考试（含课中答题）”，升级保留你已经保存的模式；若希望视频完成后进入关联考试，请确认当前模式为“视频＋考试”。人工刷新或重开浏览器后默认暂停，检查清单后点击“继续上次任务”。

脚本仅在 `http://10.119.67.7/clientcn/*` 生效，含其下课程、练习及考试路径；其他主机、HTTPS、其他端口及站点目录外不会注入功能。名称继续为“谊安学助手 2.0”。

## 六个功能栏

| 功能栏 | 内容 |
|---|---|
| 任务总览 | 四种任务模式、顺序/并行、任务清单、当前任务、总进度及预计剩余时间 |
| 视频学习 | 实际倍速、播放进度、平台学习记录、课中题、局部暂停与恢复；续播、单次答题机会保护、切回恢复三个开关 |
| 考试答题 | 自动选择开关、缺题人工确认开关、答案核对、答题间隔、预计得分、考试计时和交卷状态；兼容原练习页 |
| 题库搜索 | 统一题库导入、关键词搜索、课程筛选、选中文字搜索、来源及主题关联 |
| 控制台 | 最近 500 条运行日志、级别筛选、复制、清空显示；默认开启的持续诊断记录、最近 2000 条持久诊断及 JSON/TXT 导出 |
| 其他设置 | 允许复制开关、默认关闭的题库导出折叠区、异常恢复参数 |

桌面左导航右内容，窄屏顶部标签。全局状态、进度和暂停/继续常驻；切栏不启停任务、不重置计时、不触发导出。拖动标题栏移动面板，位置自动保存；搜索和设置控件不会触发拖拽。

## 统一题库与准确匹配

统一文件保留 **5520 条来源记录**，包含 **2458 道唯一题、2459 个答案组合、1 道冲突题**。原主操、副操、班长仅作来源信息，不限制搜索和自动答案。相同题型、题干、选项及正确答案文字可以聚合，并显示全部来源。详见 [题库说明](题库/README.md)。

- 升级自动读取并迁移旧 v2 题库，验证后写入 v3；原存储保留，迁移保存失败仍可读取原库。
- 原题号、课程、答案文字、来源文件及网址保留；重复导入同一来源不增加记录。新增 CSV/JSON 合入统一题库；完整 ZIP 导入作为整库替换。
- 搜索允许关键词、选项或正确答案文字，可按课程筛选；宽松搜索结果不会直接授权自动选择。
- 自动匹配严格比较题型、完整题干与全部选项，以正确答案全文定位网页当前选项，支持选项乱序。仅清理排版空白和不可见字符，保留大小写、单位、指数、数字、否定词和标点。
- 分值、难度和题号单独读取，不污染题干。同题同选项存在不同答案时保留冲突，不按多数票或岗位选答案；只有明确课程/来源能够消歧才自动作答。
- 无匹配、图片题、未适配结构或无法唯一映射时等待人工或跳过，并显示原因。网站正常保存真实选项点击，不伪造作答记录。

自动选择开关默认关闭。仅手动开启此开关只选择当前页答案；通过任务总览启动考试任务后，才启用下述按条件交卷流程。手动作答、关闭开关、暂停或修改题库/主题关联会取消旧交卷计划，继续前重新核验。

## 视频、任务与后台

任务模式为“仅视频、视频＋课中答题、仅考试、视频＋考试”，新安装默认“视频＋考试”，已有保存的模式继续沿用，执行方式默认顺序，并行最多一个视频和一场考试。“仅视频”和“视频＋课中答题”均不会进入独立或关联考试；选择“视频＋考试”后，按目录的完成条件处理视频与已开放的关联考试，仍需通过单次机会保护及题库预检。视频栏根据当前模式显示后续流程。识别网页现有目录和入口，不猜业务接口。阶段数与课件数分别处理，非视频及未开放任务显示具体原因，已跳过或失败不计为完成。

视频支持 1X、1.25X、1.5X、2X，显示实际播放器倍率。播放到末尾后继续等待平台学习完成标记；平台记录时长与播放器位置分别展示。没有明确学习时长要求或任务耗时依据时，预计时间显示待确认，2X 不代表整轮耗时必然减半。

封面页自动点击实际绑定事件的“开始学习”文字按钮；已完成首项会跳过，从对应未完成的目录行进入，避免封面默认重播第一项。点击一次后等待播放器异步出现；人工继续或受控刷新均重新获得本次 15 秒加载窗口，不沿用旧超时，也不清零自动恢复次数。

橙色图标不代表完成。脚本读取它的网页提示，在视频栏和日志显示观看时长、观看进度、是否还需考试或及格等条件。明确按时长要求时，只使用同一课件的后台累计学习时长判断观看阶段；按百分比要求时，不用累计秒数推断进度。若视频已到末尾且提示仍要求考试，可先进入已识别的关联考试，随后返回原课程核对平台完成标记；不会因此把视频或整课记为完成。未处理的课中题、续播弹窗和用户暂停优先。已完成课件自动跳过；从学习地图启动时，当前可执行任务结束后通过已访问的原地图及真实课程入口进入下一任务。直接进入课程而没有已知地图地址时，不猜测其他课程地址。

课中答题适配保存 JS 模板中的 `app-question-modal` 与 PC CDK portal：按完整题干及选项匹配，回读选中集合，走网站“查看答案”判分，只有明确回答正确并关闭/进入下一题后才继续。仅视频模式遇强制题、无库、冲突或未知结构时等待人工，不刷新弹题。课中题不套用考试交卷规则。

“视频学习”栏新增三个独立开关，默认开启并保存设置：

- **自动继续上次播放**（`autoContinuePlayback`）：运行中的视频任务遇到正文为“是否继续上次播放的位置？”、同时有“重新开始”和“继续播放”的明确弹窗时，选择“继续播放”。关闭后由你处理；不会点击其他未知弹窗。
- **仅 1 次答题机会时交给我处理**（`skipSingleAttemptQuiz`）：用户确认的含义是“只剩 1 次或总共仅允许 1 次答题机会”，包含课中题与课程考试。开启时停止受影响的自动进入、选项点击及提交，交给你手动操作；0 次同样不自动操作。次数只取当前题目或考试容器中明确可见的允许、总、剩余次数及“还可补考 N 次”等提示，不把本人已答 1 次、已答 1/40 题或交卷人数当成机会数。未显示明确次数时不作推断，关闭保护仍需满足原有题库和交卷条件。
- **切回页面时自动恢复播放**（`resumePlaybackOnReturn`）：只对切页前正在播放、因网站切页逻辑而暂停的当前视频，在返回后尝试正常续播。手动暂停优先，暂停任务、课中题或其他待处理状态不会被自动播放覆盖。关闭后保持暂停，按网站或面板正常继续。

默认连续 60 秒没有播放进度时尝试续播，15 秒后仍失败再刷新当前视频页面，最多 3 次，两次刷新至少间隔 30 秒，次数跨刷新保存。主动暂停、课中题、等待平台确认、等待交卷或等待人工不算故障。脚本发起的恢复及任务跳转保存一次性续作标记；人工刷新默认暂停。并行页面通过共享租约、心跳及全局控制协调，打开失败或未确认时显示等待，不假称并行成功。

同类任务被另一执行页面占用时，临时等待租约并自动重试；旧执行页停止心跳、租约失效后继续调度，不要求因此手动点击继续。拿到租约后更新状态提示，避免仍显示“等待同类任务租约释放”。另一页面仍在正常处理时继续保持互斥；课中题、单次机会保护等需要人工处理的等待不会被自动重试覆盖。

保存站点脚本显示：网站切到后台会主动暂停播放器，返回前台没有相应自动恢复逻辑。本版记录切页前的真实播放状态，后台暂停时显示“后台暂停，等待返回”，开启上述恢复开关后返回再尝试续播，不把后台暂停误当成长时间卡顿而刷新。不能保证后台一直播放，也不能保证浏览器关闭、设备休眠或标签冻结期间执行；恢复后按实际播放器及平台记录校准，不伪造学习时长。真实账号的解锁、倍速、后台和并行规则仍需实站验收。

## 考试预计得分与交卷

适配明确为 `flag=test`、完整加载且可作答的桌面试卷。开考前检查主题及题库，整卷加载后逐题预检；默认题间隔 **4 秒**，最早交卷时间为本场进入试卷起 **6 分钟**。练习多选的正常确认仍按现有网页流程处理。

只有以下条件同时成立才自动交卷：

1. 主题关联明确，网页整卷及答题卡完整，所有可匹配题均完成作答且当前选中答案全文回读核验通过；并满足下述缺题人工确认开关规则。
2. 按网页每题实际分值累计的可核验预计得分 **严格大于 80 分**；正好 80 分也等待人工。
3. 达到最早交卷时长，试卷仍有效、未暂停、未结束，交卷入口及确认流程可以唯一识别。

“考试答题”栏提供 **“题目不全时手动确认交卷”开关，默认开启**（`manualConfirmIncomplete`）：

- **开启：** 每一道题都须唯一精确匹配且当前选中全文核验通过；有未匹配、冲突、未核验、无法唯一映射或不支持的题目时，即使已核验 84 分并满 6 分钟，也等待用户在网站手动确认。网站正常未答完提醒不自动确认。
- **关闭：** 恢复部分题库自动交卷。网页整卷完整、全部可匹配题处理并全文核验、已核验预计得分严格大于 80 分且满 6 分钟，并满足其他通用条件后，可保留未知题自动交卷及确认本场正常未答完提醒。未知题仍不猜答、不计正分。

切换开关会暂停当前答题和交卷计划，须明确继续并重新核验后执行，关闭开关不会立即提交。设置跨页面和刷新保存。网页题目或答题卡加载不全、分值或 100 分分制不明、主题不明确、可匹配题未核验、预计得分不超过 80 分、计时未到等通用门槛，在任何开关状态下都不放行。

未知题计 0 分且不猜答，人工补选的未知答案不自动计为正确，多选必须整个集合一致才计分。预计得分来自本地题库，不是官方成绩，也不保证真实得分。完整 100 分且每题核验通过后，仍需满足 6 分钟等其余条件才自动交卷。

提交前再次检查当前试卷、题库版本、整卷完整性、选中全文和开关；只走当前场次正常交卷及确认，网站显示成功结果才计完成。提交结果不明停止重复点击。暂停脚本不会暂停网站倒计时；网站剩余时间不足、身份验证或异常流程需人工处理。

## 导出与离线工具

“其他设置”的导出开关默认关闭；开启才展开 CSV/JSON/TXT 按钮，兼容练习页答案完整时自动导出一次 CSV。关闭后停止后续导出，主动重新开启可再次下载。切换功能栏不触发下载。考试页参考答案为空时不提供考试题库导出，导出不会用导入题库填补网页缺失答案。

已保存的 HTML 可双击 [离线导出题库.html](离线导出题库.html) 打开，与 `question-bank-core.js` 放在同一目录。工具以静态 DOM 解析并中和原脚本及资源，不执行原站代码；保留 CSV 防公式转义、UTF-8 BOM 和缺失答案提示。

## 开发与验证

```powershell
npm run build
npm test
npm run merge:banks
```

测试依赖 Node.js 和 Playwright/Chrome；使用本机模拟页面及中和后的保存 DOM，所有业务 URL 由测试拦截，未访问业务服务器。验证范围包括统一题库迁移/来源/冲突、真实 40 题全文乱序、题间隔、80 分门槛与 4/6 分钟边界、缺题人工确认开关两种模式、设置保存及切换暂停、加载不全等通用门槛、整卷 100 分核验后的交卷流程、防重复、视频恢复、并行心跳、六栏及拖拽/窄屏、复制/导出/站点范围和完整任务流程；本次结果以实际测试记录为准。

源代码按职责拆分：`bank-store.js`、`answer-matcher.js`、`answer-runner.js`、`attempt-policy.js`、`diagnostic-logger.js`、`exam-controller.js`、`quiz-adapter.js`、`learning-engine.js`、`assistant-panel.js`、`practice-exporter.js`。发布仅需构建后的单个 `.user.js`。

## 2.1.4 更新记录

修复封面“开始学习”未点击、播放器异步加载期间重复点目录、继续任务立即沿用旧加载超时，以及返回地图后不再点击下一课程入口的问题。新增读取完成条件、观看与关联考试分阶段调度和完成后重新核对平台记录；同名课程与异步导航分别核对入口身份，避免把旧课程目录挂到下一课程。

`npm test` 的 20 套回归全部通过。新增本地课程入口与 7 项跨页导航检查，覆盖封面真实子节点、跳过已完成课件、多课件、多关联考试、暂停及迟到存储、时长条件、课中题保护、模式边界、返回地图及恢复超时；完整链验证考试确认提交后返回课程，等待真实完成标记，再进入下一课程。桌面与 390px 窄屏已检查。所有业务请求本地拦截；仍需实际账号验收平台学习条件及解锁行为。

## 2.1.3 更新记录

已在本地复现并修复两项缺陷：租约临时冲突被记作永久人工等待，以及成功恢复后仍保留旧等待提示。另一执行页面仍有效时保持互斥，旧占用失效后自动重试。学习地图归档中的课程与考试入口使用 Angular 当前页路由，不能仅凭租约提示认定用户打开了重复标签。

控制台保留最近 500 条运行日志，“清空显示”只清运行日志显示。新增“持续记录诊断日志”开关，默认开启，最近 2000 条诊断记录独立持久保存，刷新后保留；使用“导出诊断 JSON”“导出诊断 TXT”可一键导出，使用“清空已保存诊断”可删除这些诊断记录。关闭开关只停止新增记录，已保存内容仍可导出。两种清空都不删除任务检查点或题库；诊断日志不记录完整题干、选项、答案和 URL 查询参数。

`npm test` 的 18 套回归全部通过，执行权恢复另完成 12 项检查，涵盖过期自动接续、有效外页持续续租不抢占、旧等待迁移、丢失执行权停止旧动作、恢复重验及人工等待优先。完整脚本验证了 JSON/TXT 实际下载、跨刷新保留、关闭后停止新增及清空不删检查点；桌面与 390px 窄屏无相关浏览器错误。所有业务请求均在本地拦截，真实账号环境仍需实站验收。

## 2.1.2 更新记录

新增默认开启的三个视频栏开关，统一课中题及课程考试的单次机会判断，修复切页后网站暂停而返回不能及时续播的问题。新安装默认选择“视频＋考试”，升级保留原模式，并显示视频完成后是否进入考试的具体说明。

本次提供的 `08.zip` 仅包含 Angular 页面外壳，没有播放器、续播弹窗或次数提示的实际 DOM，也没有业务 JS 资源。适配依据旧完整归档的静态模板和脚本片段，未执行原站代码。`npm test` 的 15 套回归全部通过，学习引擎另完成 52 项检查，覆盖共享设置、暂停保存竞争和关联考试完整导航；桌面及 390px 窄屏无相关控制台错误，所有业务请求均在本地拦截。本地模拟通过仍需结合真实账号验收。

开发依据与实施顺序见 [需求.md](需求.md) 和 [实施开发方案.md](实施开发方案.md)。真实课中弹题交互、课程完成条件、账号登录后的并发限制与正式提交结果需在实际环境核实；识别不明时脚本等待人工，不把本地模拟通过等同于全站验收完成。