yianxue-assistant/README.md

谊安学助手 2.0

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

安装与启动

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

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

六个功能栏

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

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

统一题库与准确匹配

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

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

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

视频、任务与后台

任务模式为“仅视频、视频＋课中答题、仅考试、视频＋考试”，执行方式默认顺序，并行最多一个视频和一场考试。识别网页现有目录和入口，不猜业务接口。阶段数与课件数分别处理，非视频及未开放任务显示具体原因，已跳过或失败不计为完成。

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

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

默认连续 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 打开，与 question-bank-core.js 放在同一目录。工具以静态 DOM 解析并中和原脚本及资源，不执行原站代码；保留 CSV 防公式转义、UTF-8 BOM 和缺失答案提示。

开发与验证

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、exam-controller.js、quiz-adapter.js、learning-engine.js、assistant-panel.js、practice-exporter.js。发布仅需构建后的单个 .user.js。

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