Textbook Version Guard

When to Use

Use this skill when the user is producing K12 course-planning documents, flyers, handouts, or question-bank deliverables that must reference specific textbook editions (e.g., Shanghai 五四制, Hujiao, Huke, Oxford). It automates checking that every file in the project uses the agreed version and optionally repairs outdated labels in Word documents.

Common triggers:
- "Check that all my flyers use the latest textbook version"
- "Ensure the 9th-grade docs say the 2025-2026 edition"
- "Find any outdated textbook labels in my deliverables"
- "Build a tool to keep textbook version consistent"

Overview

The skill provides a small CLI tool plus a JSON contract file:

• 教材版本约定.json — single source of truth. It lists, for each subject/grade, the exact required text tokens that must appear in a deliverable (e.g., ["沪教版五四制", "2025-2026"] for 9th-grade math).
• check_textbook_version.py — scanner that:
  1. Extracts text from .docx, .pdf (via PyMuPDF/fitz), .md, .txt, .json.
  2. Detects subject and grade from filename + first paragraphs.
  3. Compares extracted labels against the contract.
  4. Reports OK, MISMATCH, MISSING, or SKIP.
  5. With --fix, safely upgrades weak labels in .docx only when the current text is a prefix of the agreed text (e.g., 沪教版五四制 → 沪教版五四制2025-2026版). PDFs are generation artifacts; they are flagged as needing regeneration rather than edited directly.

Workflow

1. Copy and customize the config template in the target project.
   - Adjust subjects, grades, grade_map, and scan.roots.
   - Keep the rule: for any (subject, grade), if every string in required is present in the file, it passes.
   - Set fix_from only for safe upgrades where the current label is a strict prefix/alias of the agreed label.
2. Run a dry check to see the current state:
   bash python3 check_textbook_version.py --config 教材版本约定.json
3. Apply safe fixes in docx:
   bash python3 check_textbook_version.py --config 教材版本约定.json --fix
4. Regenerate any PDFs flagged as PDF_NEED_REGEN. The script intentionally does not edit PDFs; regenerate them from the now-fixed source docx or from a reportlab/pandoc pipeline that pulls the version label from the same config.
5. Review any MISSING items. The tool cannot guess where to insert a version label in a file that has none; it only flags it.
6. Check the markdown report (教材版本校验报告.md by default) and commit the config file with the project so future edits can re-run the tool.

Key Design Notes

• Grade detection uses only explicit labels (e.g., 六年级, 6年级, 九, 九年级). Bare single digits are intentionally ignored because math content often contains answer numbers like =6.
• Subject detection uses keyword lists; the subject with the most keyword hits wins.
• MISSING means the subject/grade was identified but no version token was found. This is common for raw question banks, so keep them out of scan.roots.
• For generated PDFs, the safest lifecycle is: source .docx is fixed by this tool, then PDF is regenerated by a separate generator that reads the same JSON config.

Resources

• scripts/check_textbook_version.py — main CLI.
• scripts/教材版本约定.json — contract template; copy and adapt to the project.