English Practice - 英语练习册生成技能 v2.1

基于题库化 + 组卷化的英语练习生成系统
更新日期：2026-03-14
版本：v2.1

📚 功能说明

基于 AI 的英语练习册生成工具，支持：

• ✅ 题库化存储 - 单题入库，按题型统一 schema
• ✅ 组卷算法 - 按 blueprint 抽题，难度 + 标签分散
• ✅ 指纹去重 - 每题唯一 hash，防止重复
• ✅ 历史去重 - 7 天使用记录，避免每天同一套题
• ✅ PDF 导出 - 学生版/教师版（含答案）
• ✅ 多版本 - 人教版（3-6 年级）、外研版（7-9 年级）
• ✅ 8 种题型 - 情景单选、完形填空、阅读理解、句型转换、词形转换、改错、语法填空、写作

🎯 核心架构

题库层 → 生成层 → 校验层 → 组卷层 → 导出层

架构说明

📋 题库结构（v2.1 标准）

公共字段（每题都有）

{
  "id": "cloze_001",
  "type": "cloze_test",
  "grade": 7,
  "version": "外研版",
  "difficulty": "medium",
  "tags": ["daily_life", "weather"],
  "source": "manual",
  "status": "approved",
  "fingerprint": "cloze_test:A Rainy Morning:This morning...",
  "created_at": "2026-03-14T22:00:00Z",
  "updated_at": "2026-03-14T22:00:00Z",
  "content": {}
}

📝 题型 Schema

1. 情景单选 (multiple_choice)

{
  "type": "multiple_choice",
  "content": {
    "title": "Daily Conversation",
    "scenario": "thanking",
    "dialogue": "— Thank you for your help.\n— ______",
    "question": "Choose the best response:",
    "options": ["You're welcome", "Never mind", "That's right", "Good idea"],
    "answer": "You're welcome",
    "explanation": "对感谢的回答用 You're welcome"
  }
}

必填字段：title, dialogue, question, options(4 个), answer

2. 完形填空 (cloze_test)

{
  "type": "cloze_test",
  "content": {
    "title": "A Rainy Morning",
    "passage": "This morning, I woke up... ___1___ ... ___2___ ...",
    "blanks": [
      {"id": 1, "answer": "umbrella", "options": ["umbrella", "ticket", "basket", "cap"]},
      {"id": 2, "answer": "earlier", "options": ["earlier", "later", "faster", "again"]}
    ],
    "word_count": 270,
    "explanation": "完形填空测试综合语言理解能力"
  }
}

强校验：

• passage 中的 ___1___ ... ___N___ 数量必须等于 blanks.length
• blanks[].id 必须连续
• 每个 options 必须 4 个
• answer 必须存在于 options

3. 阅读理解 (reading_comprehension)

{
  "type": "reading_comprehension",
  "content": {
    "title": "The Power of Reading",
    "passage": "Reading is one of the most important skills...",
    "word_count": 180,
    "questions": [
      {
        "id": 1,
        "question": "What is the main benefit of reading?",
        "options": ["It helps us gain knowledge", "It makes us rich", "...", "..."],
        "answer": "It helps us gain knowledge",
        "explanation": "文章第一段明确提到"
      }
    ]
  }
}

强校验：

• 每篇阅读至少 3~5 小题
• 每小题 4 个选项
• answer 必须在 options 中

4. 句型转换 (sentence_transformation)

{
  "type": "sentence_transformation",
  "content": {
    "title": "Sentence Transformation",
    "original": "Tom is interested in playing football.",
    "prompt": "Rewrite the sentence using the word in brackets",
    "target": "Tom is interested in ___ (play) football.",
    "answer": "playing",
    "grammar_point": "动名词"
  }
}

必填字段：original, prompt, target, answer

5. 词形转换 (word_formation)

{
  "type": "word_formation",
  "content": {
    "title": "Word Formation",
    "root_word": "care",
    "sentence": "Be ___ when you cross the road.",
    "answer": "careful",
    "explanation": "care → careful (形容词)"
  }
}

必填字段：root_word, sentence, answer

6. 改错题 (error_correction)

{
  "type": "error_correction",
  "content": {
    "title": "Error Correction",
    "sentence": "They was very happy yesterday.",
    "answer": "They were very happy yesterday.",
    "explanation": "主语是 They，be 动词应使用 were"
  }
}

必填字段：sentence, answer

7. 语法填空 (fill_blank)

{
  "type": "fill_blank",
  "content": {
    "title": "Grammar Fill-in-the-Blank",
    "question": "She ___ (go) to school every day.",
    "blanks": [
      {"id": 1, "answer": "goes", "hint": "一般现在时"}
    ],
    "explanation": "一般现在时，第三人称单数动词加 -es"
  }
}

必填字段：question, blanks, blanks[].answer

8. 写作题 (writing)

{
  "type": "writing",
  "content": {
    "title": "My Favorite Season",
    "prompt": "Write a short passage (60-80 words) about your favorite season.",
    "word_limit": "60-80 words",
    "requirements": ["Clear structure", "Correct grammar", "Relevant vocabulary"]
  }
}

必填字段：prompt, word_limit

🔧 组卷算法

Blueprint（试卷模板）

BLUEPRINT = {
    "multiple_choice": 2,
    "cloze_test": 4,
    "reading_comprehension": 5,
    "sentence_transformation": 2,
    "word_formation": 2,
    "error_correction": 2,
    "fill_blank": 2,
    "writing": 1
}
# 总计：20 道题

组卷流程

# 1. 加载题库
question_bank = load_question_bank('question_bank_v2.json')

# 2. 筛选候选（过滤已使用、非 approved）
candidates = filter_candidates(
    question_bank=question_bank,
    qtype='cloze_test',
    grade=7,
    version='外研版',
    history_used_ids=used_last_7_days,
    used_ids_in_this_paper=current_paper_ids
)

# 3. 选题（难度 + 标签分散）
selected = select_questions(
    candidates=candidates,
    qtype='cloze_test',
    count=4
)

# 4. 校验 + 去重
validated = validate_and_dedup(
    new_questions=selected,
    question_bank=question_bank,
    current_paper_questions=paper_questions
)

# 5. 整卷校验
validate_full_paper(paper_questions)

# 6. 输出试卷
paper = build_paper_json(
    grade=7,
    version='外研版',
    questions=paper_questions
)

指纹生成规则

def build_fingerprint(q):
    t = q['type']
    c = q['content']
    
    if t in ['cloze_test', 'reading_comprehension']:
        raw = f"{t}|{c.get('title')}|{c.get('passage')}"
    elif t == 'sentence_transformation':
        raw = f"{t}|{c.get('original')}|{c.get('target')}"
    elif t == 'word_formation':
        raw = f"{t}|{c.get('root_word')}|{c.get('sentence')}"
    elif t == 'error_correction':
        raw = f"{t}|{c.get('sentence')}"
    elif t == 'fill_blank':
        raw = f"{t}|{c.get('question')}"
    elif t == 'multiple_choice':
        raw = f"{t}|{c.get('dialogue')}|{json.dumps(c.get('options'))}"
    elif t == 'writing':
        raw = f"{t}|{c.get('prompt')}"
    
    return hashlib.md5(raw.encode('utf-8')).hexdigest()

💻 使用方法

CLI 方式

# 生成练习册
english-practice generate --grade 7 --version 外研版 --count 20

# 指定题型
english-practice generate \
  --grade 7 \
  --version 外研版 \
  --types multiple_choice,cloze_test,reading \
  --output practice.pdf

# 生成 PDF
english-practice pdf \
  --input paper_demo.json \
  --output student.pdf \
  --with-answers teacher.pdf

Python API

from paper_assembler import generate_paper, load_question_bank

# 加载题库
question_bank = load_question_bank('question_bank_v2.json')

# 生成试卷
paper = generate_paper(
    question_bank=question_bank,
    grade=7,
    version='外研版',
    history_used_ids=set()  # 最近 7 天用过的题 ID
)

# 保存试卷
with open('paper.json', 'w', encoding='utf-8') as f:
    json.dump(paper, f, ensure_ascii=False, indent=2)

# 生成 PDF
from pdf_gen import PDFGenerator
pdf_gen = PDFGenerator()
pdf_gen.generate(
    practice_id=paper['paper_id'],
    questions=paper['questions'],
    version=paper['version'],
    grade=paper['grade'],
    with_answers=False  # 学生版
)

交互模式

english-practice interactive

# 交互式问答：
# 1. 选择年级：7
# 2. 选择版本：外研版
# 3. 选择题型：全选
# 4. 生成 PDF：是

🌐 API 端点

基础 URL: http://101.34.62.112:8083

生成练习册请求示例

curl -X POST http://101.34.62.112:8083/api/practice/generate \
  -H "Content-Type: application/json" \
  -d '{
    "version": "外研版",
    "grade": 7,
    "question_types": ["multiple_choice", "cloze_test", "reading"],
    "question_count": 20
  }'

📁 文件结构

english-practice/
├── backend/
│   ├── question_bank_v2.json       # 标准化题库
│   ├── paper_assembler.py          # 组卷算法
│   ├── question_gen.py             # 题目生成
│   ├── pdf_gen.py                  # PDF 生成
│   └── main.py                     # API 服务
├── pdfs/
│   ├── paper_*_student.pdf         # 学生版
│   └── paper_*_teacher.pdf         # 教师版（含答案）
├── data/
│   └── questions_v2.db             # SQLite 题库
└── README.md

🎯 核心改进（v2.1）

📊 验证清单

生成试卷后，运行以下验证：

# 1. 验证题量
python3 -c "
import json
with open('paper.json') as f:
    paper = json.load(f)
print('题目总数:', len(paper['questions']))
"

# 2. 验证无重复
python3 -c "
from paper_assembler import validate_full_paper, load_question_bank
paper = load_question_bank('paper.json')
assert validate_full_paper(paper), '整卷校验失败'
print('✅ 整卷校验通过')
"

# 3. 验证题型分布
python3 -c "
from collections import Counter
types = Counter([q['type'] for q in paper['questions']])
for t, c in sorted(types.items()):
    print(f'  {t}: {c}道')
"

预期输出：

题目总数：20
✅ 整卷校验通过
  cloze_test: 4 道
  error_correction: 2 道
  fill_blank: 2 道
  multiple_choice: 2 道
  reading_comprehension: 5 道
  sentence_transformation: 2 道
  word_formation: 2 道
  writing: 1 道

🔧 依赖

Python 3.8+
FastAPI
uvicorn
reportlab (PDF 生成)
sqlite3
hashlib (指纹生成)

安装：

pip install fastapi uvicorn reportlab

📝 更新日志

v2.1 (2026-03-14) - 题库化 + 组卷化

• ✅ 题库 JSON 标准结构（16 个公共字段）
• ✅ 8 种题型 content schema
• ✅ 组卷算法实现（6 个核心函数）
• ✅ 指纹去重（按题型生成唯一 hash）
• ✅ 标签分散（避免同主题堆积）
• ✅ 难度控制（easy/medium/hard）
• ✅ 整卷校验（题量、重复、状态）

v2.0 (2026-03-14) - 去重机制

• ✅ key_for_question() 唯一键生成
• ✅ deduplicate_questions() 去重
• ✅ generate_with_dedup() 生成 + 去重 + 补题

v1.0 (2026-03-10) - 初始版本

• 基础出题功能
• PDF 导出

📚 相关文档

• ARCHITECTURE_V2.1.md - 架构设计
• DELIVERY_REPORT.md - 交付报告
• 成果汇报.md - 实际成果展示

技能版本：v2.1
最后更新：2026-03-14
维护者：老六 🥷