From d1ffa9ba05e509adae63194b2cb7e26cde6d85dc Mon Sep 17 00:00:00 2001
From: chuan <pchuan98@qq.com>
Date: Tue, 2 Jun 2026 23:57:43 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=9B=B4=E6=96=B0=20README.md=EF=BC=8C?=
 =?UTF-8?q?=E5=AE=8C=E5=96=84=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E=E5=92=8C?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=E7=BB=86=E8=8A=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 99 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 4bd20cd..db8519e 100644
--- a/README.md
+++ b/README.md
@@ -1,66 +1,143 @@
 # auto-answer
 
-一个尽可能简单的纯 Python 自动答题框架。
+一个纯 Python 的自动练题脚本，用 Playwright 控制 Microsoft Edge，自动进入中石化网络学院“自主练测”的顺序练习页面，并根据页面里的“答案解析”选择正确答案。
 
-当前只包含命令行入口、配置、浏览器控制和答题逻辑占位，不包含 Web/API。
+不包含 Web 服务和 API 服务，直接命令行运行。
 
-## 安装
+## 快速使用
+
+最简单方式：双击项目根目录的 `start.bat`。
+
+它会执行：
+
+```bat
+uv run auto-answer practice --answer-count -1 --delay-ms 500
+```
+
+含义：
+
+- `--answer-count -1`：一直答题，直到没有下一题。
+- `--delay-ms 500`：每答完一题后等待 500ms。
+- 题库名称、账号、密码等从 `.env` 读取。
+
+## 首次准备
+
+安装依赖：
 
 ```powershell
 uv sync
+```
+
+如果本机 Playwright 没有浏览器运行环境，可执行：
+
+```powershell
 uv run playwright install chromium
 ```
 
-## 运行
+本项目默认使用系统里的 Microsoft Edge：
 
-```powershell
-uv run auto-answer login
-uv run auto-answer run
+```text
+BROWSER_CHANNEL=msedge
 ```
 
-打开自主练测页，如果登录过期则自动登录：
+## 配置
+
+复制 `.env.example` 为 `.env`，然后填写账号密码：
+
+```dotenv
+LOGIN_USERNAME=你的账号
+LOGIN_PASSWORD=你的密码
+QUESTION_BANK=测录融合
+ANSWER_COUNT=0
+ANSWER_DELAY_MS=0
+```
+
+常用配置说明：
+
+- `LOGIN_URL`：登录页地址。
+- `TARGET_URL`：自主练测入口地址。
+- `LOGIN_USERNAME` / `LOGIN_PASSWORD`：登录账号密码。
+- `QUESTION_BANK`：题库关键词，程序会从页面 tab 中自动匹配最接近的题库。
+- `ANSWER_COUNT`：自动答题数量，`0` 表示只进入练习不答题，`-1` 表示一直答到结束。
+- `ANSWER_DELAY_MS`：每题答完后的等待时间，单位毫秒。
+- `STORAGE_STATE_PATH`：保存 cookie/localStorage 的文件。
+- `SESSION_STATE_PATH`：保存 sessionStorage 的文件。
+
+`.env`、`.auth/` 已加入 `.gitignore`，不会提交到 Git。
+
+## 常用命令
+
+进入自主练测，但不自动答题：
 
 ```powershell
 uv run auto-answer practice
 ```
 
-指定题库关键词，程序会自动选择匹配度最高的题库 tab，并进入顺序练习：
+指定题库关键词：
 
 ```powershell
 uv run auto-answer practice --bank "测录融合"
 ```
 
-进入顺序练习后自动答指定数量的题：
+答 10 题：
 
 ```powershell
 uv run auto-answer practice --bank "测录融合" --answer-count 10
 ```
 
-一直答到没有下一题，并在每题后等待 500ms：
+一直答到结束，每题等待 500ms：
 
 ```powershell
 uv run auto-answer practice --bank "测录融合" --answer-count -1 --delay-ms 500
 ```
 
-连续登录并复用同一个 Edge 窗口：
+只登录并保存登录态：
 
 ```powershell
-uv run auto-answer start
+uv run auto-answer login
 ```
 
-也可以复制 `.env.example` 为 `.env`，然后直接运行：
+## 工作原理
 
-```powershell
-uv run auto-answer
+整体流程：
+
+```text
+启动 Edge
+  -> 打开自主练测页
+  -> 如果登录过期，跳转登录页并自动登录
+  -> 保存 cookie/localStorage/sessionStorage
+  -> 回到自主练测页
+  -> 按 QUESTION_BANK 模糊匹配题库 tab
+  -> 点击“顺序练习”的“开始练习”
+  -> 展开“答案解析”
+  -> 读取“正确答案：A/B/C/D”
+  -> 点击对应选项
+  -> 点击“下一题”
+  -> 循环
 ```
 
-## 结构
+题库匹配逻辑：
+
+- 读取页面中所有题库 tab 的文本。
+- 对 `QUESTION_BANK` 或 `--bank` 传入的关键词做模糊匹配。
+- 如果关键词包含在题库名里，优先使用该题库。
+- 否则使用相似度最高的题库。
+
+答题逻辑：
+
+- 每题先点击“答案解析”。
+- 从页面文本中解析 `正确答案：B` 或类似格式。
+- 如果是多选，例如 `正确答案：ABC`，会依次点击 A、B、C。
+- 点击“下一题”后等待题号变化。
+- `--answer-count -1` 时会一直循环，直到找不到下一题或题号不再变化。
+
+## 目录结构
 
 ```text
 src/auto_answer/
-  cli.py       命令行入口
-  config.py    配置读取
-  browser.py   Playwright 浏览器封装
-  runner.py    主流程
-  solver.py    答题逻辑
+  cli.py       命令行参数
+  config.py    .env 配置
+  browser.py   Edge/Playwright 封装
+  runner.py    登录、选题库、答题主流程
+  solver.py    保留的答题逻辑扩展位
 ```