成考英语学习与试卷生成系统

在自己的 Windows 电脑上运行：导入 PDF、Word（.docx）、TXT 或 Markdown 试卷，生成可作答的试题、判卷并管理错题和学习记录。

本仓库只提供程序，不附带作者的卷子、学习资料、API Key 或个人记录。首次启动时试卷列表为空，需要导入自己的试卷文件。

新增 Android 8.0 及以上的独立试用版：手机直接调用模型，数据保存在本机，无需运行电脑服务。当前应用名称为“学卷·试用版”，免费开源，并在界面显示项目出处。0.2.4修复空完形题干和逐题计分误报；移植试卷生成及检查 / 修复、分类与回收站、作答 / 笔记 / 记录 / 导出、判卷、错题重做、学习计划 / 计时 / 日报，并打包单词复习页面和词库。GitHub Release公开APK不内置API Key；首次使用AI功能前请在设置页填写个人模型密钥。

构建和安装范围见 Android 说明，验证情况见 Android 验证记录。生成任务使用原生前台服务和持久化检查点；进程中断后可重试。手机与电脑的数据独立保存；使用同一签名覆盖安装可升级旧APK并迁移其本地记录。

不懂编程、没有安装 Python？请使用便携版。

PDF 模型要求：必须使用支持图片输入和文字识别的多模态大模型（视觉模型）。 PDF 一律逐页转成图片识别，不使用内嵌文字层绕过识别。纯文字聊天模型、只能生成图片的模型不适用于 PDF；请确认模型平台的 API 也支持图片输入。

DOCX、TXT、Markdown 会先读取文字，再交给大模型整理。Word 中的图片、公式对象和复杂自动编号请先导出为 PDF，以免漏掉内容；旧版 .doc 请另存为 .docx 或 PDF。文字文档按“内容段”定位原文，PDF 按页定位。听力原卷若只有选项，需要自行播放配套音频，软件不会编造音频中的题干。

1. 打开 软件下载页（Releases），选择 Windows 便携试用版。
2. 下载 Assets 中的 Chengkao-Windows-x64-….zip，不要下载名为 Source code 的源码包。
3. 右键“全部解压”，直接解压到桌面等较短路径，避免套多层文件夹，再双击 启动成考助手.exe。若提示路径过长，请换短目录重新完整解压，不要跳过错误。
4. 含默认试用配置的版本会自动启动并打开网页，无需先填写模型。导入自己的卷子即可开始。没有默认配置的版本，请点击“模型配置”填写三项信息。
5. 默认共享额度用完或希望更换模型时，点击启动窗口或网页中的“模型配置”，填写自己的接口地址、模型名称和 API Key，点击“保存并使用”。切换前保存作答并等待任务完成；重启后使用新打开的页面。

适用于 Windows 10/11 x64，自带运行环境，不需要安装 Python、Codex，也不需要输入命令或手动编辑配置文件。默认试用额度由作者提供，额度有限，不保证长期可用；切换自己的模型后由所选平台计费。自己的配置优先，并可通过“恢复默认试用模型”切回默认。

不会填写三项信息时，查看 新手模型配置教程。包内也有可直接打开的“使用说明.html”。首次建议用一页完整小卷子验证生成和判卷。

便携版数据在 程序文件/app/data，配置在 程序文件/app/models.json。更新前停止程序并备份，然后把自己的数据和配置复制到新版本的相同位置。试用包尚未进行商业代码签名，Windows 可能提示未知发布者，请核对下载来源。

以下是源码版安装方法，便携版用户可以跳过。

• Windows 10 / 11；本教程和批处理脚本面向 Windows。
• Python 3.12（64 位）。从 https://www.python.org/downloads/windows/ 下载 3.12 的 Windows installer (64-bit)，安装时勾选 Add python.exe to PATH，保留 Python Launcher。
• 安装依赖需要联网。模型生成、识别和 AI 判卷需要你自己的模型服务账号与 API Key，费用由你的服务商收取。
• 用于 PDF 识别的模型必须支持图片输入，接口应兼容 OpenAI API。源码版不含默认密钥，需要自行配置；带试用额度的便携包以对应版本说明为准。

在 GitHub 仓库首页点击绿色 Code → Download ZIP，下载后右键“全部解压”。进入包含 start.bat 和 requirements.txt 的目录。

不要直接在压缩包中运行。建议解压到自己的固定目录，例如 D:\chengkao-project。

双击 install.bat，等待出现 Installation complete。

安装程序会在项目文件夹内创建 .venv，安装依赖，并从模板创建 models.json 和 .env。重复运行不会覆盖已有配置和学习数据。首次安装可能需要几分钟；失败时窗口会保留错误信息，可以修复网络或 Python 安装后重试。

新手建议直接按 模型配置教程 操作：获取接口地址、模型名称、API Key，然后在安装生成的文件中只修改这三项。下面的完整 JSON 供需要重新建立配置时参考。

用记事本打开 models.json。只使用试卷功能时，可以把内容替换成下面这个最小配置，再填写服务商提供的实际值：

{
  "default": "my-vision-model",
  "fallback": "my-vision-model",
  "fast": "my-vision-model",
  "vision": "my-vision-model",
  "models": [
    {
      "id": "my-vision-model",
      "channel": "openai",
      "type": "chat",
      "supports_vision": true,
      "model": "填写服务商的真实模型名称",
      "base_url": "https://你的服务商接口地址/v1",
      "api_key": "填写你自己的API密钥"
    }
  ]
}

• id 是本地别名；上面的 default、fallback、fast、vision 都引用它，可以保持示例中的名称。
• model 必须填写服务商实际支持的模型标识，并确认该模型支持图片。设置 supports_vision: true 本身不会让纯文本模型获得识图能力。
• base_url 使用服务商文档中的 API 基础地址，通常以 /v1 结尾，不要填聊天网页地址或完整的 /chat/completions 地址。
• api_key 填你自己的密钥。不要把配置文件或带密钥的截图发到 GitHub、群聊或问题反馈里。
• 保存为 UTF-8 的 models.json，注意不要变成 models.json.txt。保留 JSON 的英文双引号和逗号。

普通本地试卷功能不需要填写 .env 中的数据库配置，也不需要运行 Docker 或另外安装 Node.js。改动模型配置后重启程序生效。

双击 start.bat，保留打开的命令窗口，然后在浏览器访问：

• 试卷页面：http://127.0.0.1:8020/exam
• 学习页面：http://127.0.0.1:8020/study
• 错题本：http://127.0.0.1:8020/wrong-book

在试卷页面选择 上传 PDF 生成试卷，选择自己的 PDF 后点击 生成试卷。第一次建议使用一份页数较少、文字清楚的 PDF，确认 API 配置和生成结果正常后再处理长卷。AI 识别、答案和判卷结果可能有误，请结合原卷核对。

命令窗口中按 Ctrl+C 停止服务。下次使用只需双击 start.bat，不用重复安装。这个本地地址只能访问自己电脑上的程序。

试卷、上传文件、作答和学习记录保存在项目的 data 文件夹内。它会在运行后自动创建。请定期在停止程序后备份 data，并另外妥善保存自己的 models.json 和 .env。

更新时先停止程序并备份上述文件，再下载新版本，把新版本的程序文件复制到原目录覆盖。保留原来的 data、models.json 和 .env。然后运行 install.bat 更新依赖，再运行 start.bat。

update_and_restart.bat 是已经替换代码后的快捷入口：安装依赖并重启本地服务，不会自动从 GitHub 下载代码。

不要删除整个旧目录后直接使用新目录，否则旧目录中的个人数据不会自动迁移。

请在 GitHub Issues 中说明 Windows 版本、操作步骤、错误提示和 Python 版本（运行 py -3.12 --version）。截图前遮住密钥和个人信息。不要提交自己的 data 或真实配置文件。

当前发布副本没有附带包含原卷内容的历史测试数据，因此不包含完整的自动化测试集。支持范围和实际验证结果以发布说明为准。

原有功能规划和设计说明保存在 项目设计文档。其中的规划不等于已验证的发布功能。

当前依赖版本记录在 constraints.txt，安装时会自动使用。已完成的检查和未验证范围见 发布检查记录。

本项目采用 Apache License 2.0。使用、修改和分发本项目时，请遵守许可证中的声明保留等要求。第三方依赖仍遵循各自的许可证。