# Project Details / 项目详情

## English

GCSE, IGCSE, A-Level & AP AI Revision Guide Skill is an open-source Skill and Python pipeline for
generating image-rich study/revision handbooks from official UK GCSE,
International IGCSE, and A-Level syllabus/specification sources, plus College
Board AP course descriptions.

It is intentionally narrower than a generic AI education platform. The core
principle is stable across subjects: confirm how the user wants the handbook,
then turn the official syllabus into a reusable revision-handbook framework.

1. confirm the user's subject/provider, required exam year, term-support language, and explanation style;
2. retrieve the relevant official syllabus/specification source;
3. keep official PDFs out of the repository;
4. extract detailed syllabus units and assessment structure;
5. keep review metadata beside each knowledge unit;
6. generate student-facing explanations and original worked examples in the
   chosen style;
7. run a second pass to decide which knowledge points and examples need visuals;
8. let the host LLM/Agent decide whether each item is text-only, an exact SVG
   candidate, or an external infographic brief; Python records the manifest and
   renders only reviewed or approved visual assets;
9. render the handbook package as HTML with `sections/`, `images/`, manifests,
   source metadata, and supporting diagnostics, but no PDF yet;
10. require the user's active LLM/Agent to personally open the current HTML,
    compare it with the syllabus outline, and return every fixable problem to
    the Writer;
11. rerender and repeat the visible LLM review until the current HTML passes,
    then record hash-bound approval in `agent-product-review.json` and export
    the final PDF through the approval gate;
12. use Analyst, Writer, and Reviewer as lightweight operating roles; separate
    agents are optional when the user explicitly wants that orchestration.

### What Makes It Different

- **Syllabus-grounded**: handbook content starts from the official syllabus.
- **Repository-safe sources**: public PDFs are used at runtime, not committed.
- **Review metadata**: topic blocks keep enough context for later checking.
- **Explicit language policy**: the student-facing handbook body stays English
  because the exam is English. A non-English choice adds a 30-50 item
  selected-language-to-English professional glossary instead of translating the
  whole handbook body.
- **Visual learning layer**: the Writer first builds source-bound topic content,
  then records `visual_decision` for every topic. `text-ok` is allowed only with
  a `no_visual_reason`; exact SVG is allowed only when the LLM marks
  `svg_fit: "exact"` and the asset is reviewed or approved; complex lab,
  geometry, circuit, multi-factor, or text-heavy infographic needs are routed to
  source-bound visual briefs and prompt queues unless a callable image route or
  imported asset directory is available.
- **Narrative explanation modes**: topic blocks can be explained as life
  scenes, detective reasoning, or anime-quest style study missions while
  avoiding protected-IP copying by default.
- **Child-safety mindset**: examples are original and source-bound, and should
  be reviewed by a subject specialist before high-stakes exam preparation.
- **LLM HTML review before PDF**: the user's Agent must personally inspect and
  repair the current visible HTML instead of treating generated files or Python
  gates as proof of student-usable quality. Complete `agent-product-review.json`
  evidence bound to the current HTML hash is required before PDF export.
- **LLM-owned workflow boundary**: Python provides evidence extraction,
  validation, rendering, and manifests; the host LLM owns analysis, writing,
  visual judgment, and final visible-handbook review. Multi-agent orchestration is
  optional rather than the default contract.
- **Qualification structure**: UK GCSE and International IGCSE are treated as
  the GCSE-level routes. A-Level is one qualification with AS and A2 stages;
  International A-Level is handled as modular unless the official source says
  otherwise.
- **Website listing checks**: OxfordAQA subject buttons are recorded as the
  blue International GCSE listing or red International A-Level listing when
  that metadata is available. The internal compatibility tag remains
  `international_as_a_level`.

### Current Release

The current release can generate guides for AQA International GCSE and
International A-Level qualification pages, plus Edexcel and CAIE candidate
discovery with official URL/PDF fallbacks. Full official names are OxfordAQA /
Oxford International AQA, Pearson Edexcel, and Cambridge International / CAIE.
Current route evidence:

The entries below are validation samples, not a blanket subject support matrix.
They remain candidate delivery routes unless the delivery matrix records current
validation, final-review, concept-status, and visual-status evidence. The provider/parser
pipeline is designed to work across discovered OxfordAQA qualification pages;
unprofiled subjects fall back to source-bound generic examples instead of
borrowing Mathematics, Chemistry, or Economics templates.

For v0.7 release evidence, use four status words:

- `candidate`: route evidence exists, but it is not delivery-grade.
- `draft`: a fresh output exists, but concepts, images, PDF/export, validation,
  or Agent self-review still blocks final handoff.
- `final-ready`: current evidence passes validation, final review, concept
  status, visual status, and package checks.
- `certified`: final-ready evidence has also been approved by the release owner
  or a subject-aware reviewer and recorded in a release-evidence manifest.

No current route should be described as certified unless
`docs/release-evidence/` contains the matching manifest entry. v0.3 ready
evidence remains a historical release fact, not a standing certification.
The project-level rebuild plan for 95%+ student-usable delivery quality is a
historical planning note recorded in `docs/DELIVERY_QUALITY_REBUILD_PLAN.md`.
It does not override the current Skill contract.

- Offline synthetic demo: no network, no copyrighted PDF, handbook package
  output, validation issues: none.
- International GCSE Mathematics (9260): historical PDF extraction sample with
  90 syllabus units, 180 worked/practice cards, exact-SVG candidates, and 39
  complex infographic briefs.
- International GCSE Chemistry (9202): historical PDF extraction sample with 35
  syllabus units, 70 worked/practice cards, exact-SVG candidates, and 18 complex
  infographic briefs.
- International A-Level Chemistry (9620): 3 topic groups, 6 assessment
  entries, HTML/PDF output, no validation issues.
- International GCSE Economics (9214): detailed PDF extraction produces 38
  syllabus units, 76 worked/practice cards, and 38 complex infographic briefs.
- International A-Level Business (9725) revised: qualification-page
  lookup, assessment extraction, HTML/PDF output, and validation checks. This verifies code
  lookup when the subject listing omits the qualification code.

The public release showcase guides are treated as final only after each guide's
own active LLM has completely reviewed the current HTML, recorded its exact
topic/visual coverage and HTML hash in `agent-product-review.json`, exported
the PDF through `export-pdf`, and passed
`scripts/verify_release_samples.py --outputs-root <outputs>` without
`--allow-pending`. One guide's review cannot authorize another guide. For v0.7,
the same claim also needs a concise `docs/release-evidence/<version>/manifest.json`
entry; the generated output folder itself remains untracked.

The repository commits the source, skill package, documentation, screenshots,
and intro animation. Full `outputs/*-sample/` folders are reproducible release
artifacts and are kept out of Git because the image-rich packages are large.

Listing discovery has also been audited across the live OxfordAQA subject index:
17 subject pages, 48 qualification links, 31 International GCSE listings, 17
International A-Level listings, and no unknown listing types. The parser keeps
the historical `international_as_a_level` tag for source compatibility.

The same audit opened all 48 discovered qualification pages. Every page produced
at least one topic group, at least one assessment structure entry, and a
specification link, with no blue/red listing conflict. The parser now covers
Science-style heading lists, Economics-style `strong` headings with paragraph
points, revised Business `span` lists, Literature text-list labels, new
History/Sociology assessment-derived topic groupings, and project-based learning
components.

### Provider Scope

The current product covers three British-curriculum source families plus the
College Board AP course system. Do not
describe it as covering all International GCSE or International A-Level
providers, and do not claim full Pearson/Cambridge catalogue crawling yet.
This scope means automatic official-syllabus acquisition. Other curriculum
systems and exam boards do not have an automatic provider; manual imports are
unverified and may fail with unknown compatibility errors.

| Provider / exam board | Status | Notes |
|---|---|---|
| AQA | implemented | Catalogue discovery through OxfordAQA / Oxford International AQA pages plus qualification parsing. |
| Edexcel | implemented baseline | Subject-name candidate discovery for common official Pearson Edexcel page patterns; official URL/PDF fallback. |
| CAIE | implemented baseline | Official Cambridge International subject-index discovery; official URL/PDF fallback; `exam_year` required for multi-range pages. |
| College Board AP | implemented | Full 42-subject directory discovery, strict core CED selection, official-domain validation, and effective-version/exam-year recording. |
| OCR, WJEC/Eduqas, CCEA, and other UK boards | out of scope | Do not promise support in README or generated examples. |

Market comments about relative exam difficulty, vocabulary load, or scoring
friendliness should stay in planning notes until reviewed by a subject expert.
They are useful positioning context, but they are not official provider facts.

### Roadmap

1. Improve PDF section segmentation for subject content, command words,
   assessment objectives, appendices, and version history.
2. Add provider fixtures with synthetic test PDFs.
3. Add a reviewed authoring adapter for deeper worked examples.
4. Add stricter exact-SVG review fixtures for common chart, axis, and simple
   geometry cases.
5. Add configurable explanation-style presets for different student audiences.
6. Add an optional image-provider adapter for reviewed educational
   illustrations, with model/prompt/source metadata recorded for every asset.
7. Add visual regression snapshots for generated HTML.
8. Expand Edexcel and CAIE beyond candidate discovery after provider fixtures
   and quality gates are stable.

## 中文

IGCSE、A-Level 与 AP AI Revision Guide Skill 是一个开源流水线，用来为 AQA、Edexcel、CAIE 与 College Board AP 的受支持课程路线生成可追溯来源的复习指南：AQA 和 Edexcel 支持英国本土 GCSE、国际 IGCSE 与 A-Level 路线；CAIE 对应 Cambridge International，支持国际 IGCSE 与 Cambridge International A-Level；AP 对应 College Board Advanced Placement。AS 和 A2 是 A-Level 内部阶段，不是并列课程体系。按国内常用习惯，文档主称使用 AQA、Edexcel、CAIE 和 AP；对应全称分别是 OxfordAQA / Oxford International AQA、Pearson Edexcel、Cambridge International / CAIE 与 College Board Advanced Placement。

它不是泛泛的 AI 教育平台。核心原理对各学科通用：以官方 specification 为输入，
再把大纲内容融合进统一的学习复习手册框架。

1. 先确认用户选择的考试局、科目、必要考试年份、术语辅助语言和讲解风格；
2. 找到官方 qualification 页面；
3. 在运行时下载公开 course specification；
4. 抽取详细 syllabus units、assessment structure 和 PDF 页文本；
5. 给每个知识单元匹配页码级 source snippets；
6. 按用户选择的风格生成学生能读懂的讲解和原创例题；
7. 二次分析哪些知识点和例题需要图文结合；
8. 由宿主 LLM/Agent 判断每个条目是纯文字、exact-SVG 候选，还是外部信息图 brief；
   Python 只记录 manifest，并只渲染 reviewed/approved 的视觉资产；
9. 渲染完整交付包：HTML、PDF、`sections/`、`images/`、manifest、source metadata
   和 validation；
10. 校验输出是否完整到足以交付用户或进入人工复核。

### 它和普通 AI 总结器有什么不同

- **大纲优先**：官方页面和 PDF 是权威来源。
- **运行时下载**：公开 PDF 不提交到仓库，避免版权和版本问题。
- **页码级追溯**：topic block 可以显示匹配到的 source snippets。
- **明确语言策略**：学生手册正文保持英文；用户选择的辅助语言只用于 30-50 个专业词对照表。
- **图文学习层**：先生成可追溯的基础知识点和例题，再由 AI 判断哪些条目需要图文
  结合讲解。只有 LLM 写明 `svg_fit="exact"` 且资产 reviewed/approved 的场景才能使用 SVG；复杂实验装置、几何、电路、经济学场景或密集文字信息图
  先进入 source-bound visual brief 和 prompt queue，只有用户提供可调用路线或已审核图片资产时才生成、导入或挂接；如果路线可调用，应由 Agent 自动执行，并记录 prompt/source metadata。
- **叙事讲解模式**：topic block 可以切换成生活场景、侦探推理、动漫闯关感等讲法，
  默认不复刻受保护 IP。
- **给孩子用的谨慎逻辑**：例题必须原创、绑定来源，并建议正式备考前由学科老师复核。
- **区分资格结构**：英国 GCSE 与国际 IGCSE 属于 GCSE 层级；A-Level 是一套
  qualification，内部按 AS、A2 两个阶段组织，国际 A-Level 默认按 modular
  qualification 处理，除非官方来源明确说明不同结构。
- **记录网站分组**：如果从 OxfordAQA subject 页面发现 qualification，会记录蓝色
  International GCSE listing 或红色 International A-Level listing；内部兼容标签仍为
  `international_as_a_level`。

### 当前版本

当前版本路线证据：

下面列的是验证样例，不是“一切科目都已交付级验证”的支持范围。除非交付矩阵记录了当前
validation、final-review 和视觉状态证据，否则这些路线仍按 candidate delivery routes 处理。
provider/parser 流程面向已发现的 OxfordAQA qualification pages；暂未做专门 profile 的科目会使用
基于官方大纲的通用例题和图文判断，不会借用 Mathematics、Chemistry 或 Economics 的模板。

v0.7 发布证据只使用四个状态词：

- `candidate`：有路线证据，但不是交付级。
- `draft`：有当前输出，但概念、图片、PDF/export、validation 或 Agent 自查仍有阻塞。
- `final-ready`：当前证据通过 validation、概念状态、视觉状态和 package 检查，并且当前 LLM 已完整审查该手册的 HTML、记录准确 topic/视觉覆盖和 HTML 哈希，再通过门禁导出 PDF。
- `certified`：在 final-ready 之上，又经过发布负责人或熟悉学科的人确认，并写入 release-evidence manifest。

除非 `docs/release-evidence/` 里有对应 manifest 条目，否则不要把任何路线称为 certified。
v0.3 的 ready 证据是历史发布事实，不等于 v0.7 长期认证。

- Offline synthetic demo：无网络、无版权 PDF，能生成完整 handbook package，
  validation 无问题。
- International GCSE Mathematics (9260)：历史 PDF 抽取样例，包含 90 个 syllabus units、
  180 张例题/练习卡、exact-SVG 候选和 39 个复杂信息图 briefs。
- International GCSE Chemistry (9202)：历史 PDF 抽取样例，包含 35 个 syllabus units、
  70 张例题/练习卡、exact-SVG 候选和 18 个复杂信息图 briefs。
- International A-Level Chemistry (9620)：3 个 topic groups、6 个
  assessment entries、HTML/PDF 输出、validation 无问题。
- International GCSE Economics (9214)：PDF 详细抽取 38 个 syllabus units，
  生成 76 张例题/练习卡和 38 个复杂信息图 briefs。
- International A-Level Business (9725) revised：能通过 qualification page
  lookup 抽取 assessment structure，生成 HTML/PDF 并通过 validation。这个样例验证
  subject listing 没有代码时，代码查询仍然会进入详情页精确匹配。

公开发布用 showcase guides 只有在各自完成当前 HTML 的全量 LLM 审查、分别写入与自身 HTML 哈希绑定的 `agent-product-review.json`、通过 `export-pdf` 导出 PDF，并且 `scripts/verify_release_samples.py --outputs-root <outputs>` 不带 `--allow-pending` 通过之后，才算最终完成。一份手册的审查不能授权另一份。v0.7 仍要求在 `docs/release-evidence/<version>/manifest.json` 中记录精简证据；完整输出目录不提交到 Git。
这三份是首页展示和发布验收样例，不是生成器的科目支持上限。

仓库提交源码、Skill 包、文档、截图和介绍动画；完整的
`outputs/*-sample/` 目录是可复现发布产物，因为图文版 HTML/PDF 包体积较大，
不直接放进 Git。

同时已对 live OxfordAQA subject index 做 discovery audit：17 个 subject pages、
48 个 qualification links、31 个 International GCSE listings、17 个
International A-Level listings，没有 unknown listing types；内部兼容标签仍为
`international_as_a_level`。

同一轮审计还打开了全部 48 个 qualification pages。每个页面都能抽取至少一个
topic group、至少一个 assessment structure entry 和一个 specification link，
并且没有蓝色/红色 listing 冲突。解析器已经覆盖 Science 的 heading/list 结构、
Economics 的 strong heading + paragraph points、修订版 Business 的 span 列表、
Literature 的 text-list 标签、History/Sociology 从 assessment 回推 topic 的结构，
以及 project-based learning 的项目组件。

### Provider 范围

当前产品支持 AQA、Edexcel、CAIE，以及 College Board AP；不应写成覆盖全部
GCSE、IGCSE、A-Level 或其他课程体系 provider。这里的支持特指 AQA 和 Edexcel 的英国本土 GCSE、国际 IGCSE、A-Level 路线，CAIE 的国际 IGCSE 与 Cambridge International A-Level 路线，以及 College Board AP 的官方大纲自动获取。CAIE 的英国考点选择会保留为市场元数据，但不代表存在独立的 CAIE 英国本土 GCSE。其他考试体系或考试局没有自动 Provider；手动导入未经完整验证，可能出现未知兼容错误。

| Provider / exam board | 状态 | 备注 |
|---|---|---|
| AQA | 已实现 | 通过 OxfordAQA / Oxford International AQA 页面进行目录发现与 qualification 解析。 |
| Edexcel | 基础版已实现 | 根据官方 Pearson Edexcel 页面规则做候选发现；官方 URL/PDF 可以作为精确输入。 |
| CAIE | 基础版已实现 | 通过 Cambridge International 官方科目索引做候选发现；官方 URL/PDF 可以作为精确输入；多年份页面需要 `exam_year`。 |
| OCR、WJEC/Eduqas、CCEA 等其他英国考试局 | 暂不支持 | README 和样例里都不承诺覆盖。 |

关于考试难度、词汇负担、得分友好度这类市场判断，只能作为 planning note，
不能写成官方事实或产品能力，除非经过学科老师或升学顾问复核。

### 后续路线

1. 强化 PDF 分段：subject content、指令词、assessment objectives、
   appendices、version history。
2. 用合成 PDF fixtures 补测试，避免提交官方 PDF。
3. 增加经过审核的 authoring adapter，生成更深度 worked examples。
4. 为常见题型增加更专业的学科 SVG 图解模板。
5. 增加可配置的 explanation-style presets，适配不同学生的阅读偏好。
6. 增加可选 image-provider adapter，用于经过复核的教学插图，并记录每张图的
   model、prompt、source metadata 和 review status。
7. 增加 HTML 视觉回归检查。
8. Edexcel 与 CAIE 在当前基础上继续补 fixture、质量门槛和更多真实科目回归。