期末一键复习

设计理念

零配置启动：用户告知文件来源（微信/QQ/指定路径/不知道），skill 自动完成从多模态文件发现到逐章复习稿 PDF 输出的全过程。面向期末突击党和中英双语课程学生，无需任何技术背景。

环境依赖分层

Tier 0: 零依赖（模型原生能力）                Tier 1: pip install          Tier 2: + 系统依赖
──────────────────────────────────    ────────────────────────    ────────────────────
• 模型视觉能力 → 图片/扫描件理解      • .docx → python-docx        • OCR 扫描件（EasyOCR）
• .md / .txt / .html 直接读取         • .pptx → python-pptx        • PDF 输出（WeasyPrint）
• 资料类型分类（模型推理）             • .pdf (文本) → PyPDF2
• 课程命名（用户对话）                • .epub → ebooklib
• 目录创建 (bash mkdir)               • 大文件分段 (chunk_manager)
• Markdown 输出 (Write tool)          • 多格式输出 (output_writer)
• 章节拆分+内容整合（模型推理）         • PDF (WeasyPrint→pdfkit→fpdf2三引擎降级)
• 复习生成（模型推理）
• 关键词建议（模型文本分析）

PDF 三引擎保证：WeasyPrint (最佳) → pdfkit (备选) → fpdf2 (纯Python，零系统依赖，全平台永久保证）。任何平台、任何配置，最终一定能出 PDF。

启动时自动检测：模型支持 vision？→ 优先使用视觉能力。不支持？→ 检测 Python+OCR 引擎。都没有？→ 标记 [待OCR]，不跳过。

触发

"期末复习"、"考前冲刺"、"考前72小时"、"期末突击"、"一键复习"、"帮我整理XX课复习资料"、"生成复习材料"、"把课件整理成复习"、"把笔记整理成复习"、"PPT转复习"、"生成复习 for {课程名}"等。

完整决策树（6 Phase）

用户触发 /final-review
│
├─ PHASE 0: 路径发现 + 偏好设置
│  │
│  ├─ [0.1] 用户提供了具体路径？
│  │  ├─ YES → 验证路径 → [0.5]
│  │  └─ NO → [0.2]
│  │
│  ├─ [0.2] 用户提示了来源平台？
│  │  ├─ "微信" → file_finder.py --platform wechat
│  │  │  ├─ 找到 → 列出路径+文件数 → 用户选择 → [0.5]
│  │  │  └─ 未找到 → 回退到 [0.3]
│  │  ├─ "QQ" → file_finder.py --platform qq
│  │  │  ├─ 找到 → 用户选择 → [0.5]
│  │  │  └─ 未找到 → 回退到 [0.3]
│  │  └─ 不知来源 → [0.3]
│  │
│  ├─ [0.3] 通用扫描（bash find/ls，无需 Python）
│  │  ├─ Downloads / Desktop / Documents / D:\大学\ / D:\课程\
│  │  ├─ 文件类型过滤 + 课程关键词初筛 → 最多 50 个候选
│  │  └─ 找到？→ 分组展示 → 用户确认 → [0.5]
│  │     └─ 未找到 → 请用户手动指定路径
│  │
│  ├─ [0.4] 扩展扫描（可选）
│  │
│  ├─ [0.5] 文件初筛清单
│  │  ├─ 排除：系统文件(~$) 临时文件(.tmp) 空文件(<1KB) 安装程序(.exe)
│  │  └─ 按修改时间倒序 → 用户逐文件勾选确认【确认点①】
│  │
│  ├─ [0.6] 语言偏好设置
│  │  │
│  │  │  四种模式，精准对标不同学生群体：
│  │  │
│  │  │  [1] 中文主体 + 英文关键表达标注
│  │  │      正文中文（快速理解）。在影响考试阅读和答题的关键位置标注英文：
│  │  │      • 缩写 → 标注全称+中文（CISG = United Nations Convention on
│  │  │        Contracts for the International Sale of Goods, 国际货物销售合同公约）
│  │  │      • 关键词 → 括号标注英文（对价 consideration、允诺禁反言 promissory estoppel）
│  │  │      • 关键短语 → 标注英文（注意义务 duty of care、举证责任 burden of proof）
│  │  │      • 关键句 → 双语引用判例法标准表述
│  │  │      分层标注：首次完整标注，后续可仅保留英文关键词
│  │  │      适合：英语阅读慢、中文理解快、但必须应考英文的学生
│  │  │
│  │  │  [2] 英文主体 + 中文难词标注
│  │  │      正文英文（原生复习语言）。仅标注超常规的难词：
│  │  │      • 拉丁文/法语词（force majeure → 不可抗力, res judicata → 既判力）
│  │  │      • 难词生词（promulgate → 颁布, encumbrance → 权利负担）
│  │  │      • 不直观短语（ratio decidendi → 判决理由, obiter dicta → 附带意见）
│  │  │      常见法律术语不标注（如 contract, negligence 基础词汇不需要中文）
│  │  │      适合：英语好、用英文复习、遇到超纲词汇需要中文辅助的学生
│  │  │
│  │  │  [3] 纯中文 — 国内考试
│  │  │  [4] 纯英文 — 英文论文/国际期刊
│  │  │
│  │  └─ 默认 [1]。语言偏好写入 session context，贯穿全部 Phase
│  │
│  └─ [0.7] 源材料优先级确认
│     ├─ "你有没有教材？" → 有 / 没有
│     ├─ "笔记和教材以哪个为准？"
│     │   ├─ 教材为准 → 教材定章节结构，笔记补充
│     │   ├─ 笔记为准 → 笔记定章节结构，教材补充
│     │   └─ 自动 → 以 syllabus/key_points 为框架判断
│     └─ 优先级写入 session context，影响 Phase 7 章节整合
│
│  ├─ [0.8] 复习密度选择
│  │  │
│  │  │  根据剩余备考时间和个人偏好选择输出密度。写入 session context，作为 Phase 7 硬性总量约束。
│  │  │
│  │  │  [1] 精简版 —— 3–4万字
│  │  │      适合：只剩1–2天、只看框架和考点
│  │  │      每章基准定额：必考 7000–9000字 / 重点 4500–6500字 / 了解 1500–2500字
│  │  │
│  │  │  [2] 标准版 —— 6–8万字（默认，考前72小时急救）
│  │  │      每章基准定额：必考 13000–17000字 / 重点 9000–13000字 / 了解 3500–5500字
│  │  │
│  │  │  [3] 详细版 —— 10–12万字
│  │  │      适合：时间充裕、需要深入论证和案例细节
│  │  │      每章基准定额：必考 22000–28000字 / 重点 15000–20000字 / 了解 6000–9000字
│  │  │
│  │  │  默认 [2]。若章节数明显偏离 6–8 章，主 agent 可按比例上下调整单章定额，
│  │  │  但全稿总字数必须严格落在所选 tier 区间内。
│  │  │
│  │  └─ 选择结果写入 session context：`review_density = concise|standard|detailed`
│
├─ PHASE 1: 多模态格式归一化
│  │
│  │  原则：模型视觉能力 > OCR > 标记待处理。不可用的文件不跳过。
│  │
│  ├─ [1.0] 能力检测
│  │  │
│  │  ├─ 检测 1：当前模型是否支持多模态（vision）？
│  │  │   └─ 判断：能否读取图片文件并理解内容
│  │  │   ├─ 支持 → vision_mode = true
│  │  │   │   图片/扫描件/PPT截图 → 直接使用模型视觉能力理解
│  │  │   │   优势：零依赖、上下文内直接理解、无需额外安装
│  │  │   └─ 不支持 → vision_mode = false → 进入 OCR 降级
│  │  │
│  │  ├─ 检测 2：Python 环境？
│  │  │   ├─ Python ≥ 3.9 可用？→ python_ok = true
│  │  │   │   ├─ 检测 OCR 引擎（按优先级）：EasyOCR → Tesseract → PaddleOCR
│  │  │   │   │   引擎版本 vs Python 版本兼容性：
│  │  │   │   │   • EasyOCR: Py 3.6-3.11+, 瓶颈在 PyTorch, 中文~92%
│  │  │   │   │   • Tesseract: Py 3.6+ (无上限), C++引擎不受Python限制, 中文~85%
│  │  │   │   │   • PaddleOCR: Py 3.7-3.11, 瓶颈在PaddlePaddle, 中文~96%
│  │  │   │   │   → 安装第一个兼容的引擎
│  │  │   │   ├─ 检测文档依赖：python-docx / python-pptx / PyPDF2 / ebooklib
│  │  │   │   └─ 任一不可用 → 标记 [待安装: pip install X]
│  │  │   └─ Python 不可用 → python_ok = false
│  │  │      └─ 提示安装 Python 3.9+（winget/brew/apt 一键指令）
│  │  │
│  │  └─ 能力组合写入 session context
│  │
│  ├─ [1.1] 文本模态（零依赖，Claude 原生）
│  │  ├─ .md / .txt → 直接 Read，自动检测 UTF-8/GBK 编码
│  │  ├─ .html → 读取后去除标签，保留标题层级
│  │  └─ .json（幕布导出）→ 解析 JSON 节点树 → 层级 MD
│  │
│  ├─ [1.2] 文档模态（需 Python）
│  │  ├─ python_ok？
│  │  │  ├─ YES → format_converter.py
│  │  │  │  ├─ .docx → docx2md（含内嵌图片提取 → 走 [1.3] 视觉/OCR）
│  │  │  │  ├─ .pptx → pptx2md（文本 + 图片分离 → 图片走 [1.3]）
│  │  │  │  ├─ .pdf (文本) → pdf2md
│  │  │  │  └─ .epub → epub2md
│  │  │  └─ NO → 标记 [待转换: .docx/.pptx/.pdf 需要 Python]
│  │  │
│  │  └─ PPT 增强策略：
│  │     ├─ vision_mode → 直接理解 PPT 截图/导出图片（含布局+图表理解）
│  │     ├─ python_ok → python-pptx 提取文本 + 分离内嵌图片
│  │     └─ 都不可用 → 标记 [待转换]
│  │
│  ├─ [1.3] 视觉/OCR 模态
│  │  │
│  │  ├─ vision_mode = true？
│  │  │  ├─ YES → 直接让模型读取图片/扫描件
│  │  │  │   优势：零依赖，上下文内理解，不丢失排版信息
│  │  │  └─ NO → 进入 OCR 降级
│  │  │
│  │  ├─ OCR 降级链：
│  │  │  ├─ EasyOCR 可用？→ ocr_tool.py --engine easyocr
│  │  │  ├─ EasyOCR 不可用 → Tesseract 可用？→ ocr_tool.py --engine tesseract
│  │  │  ├─ Tesseract 不可用 → PaddleOCR 可用？→ ocr_tool.py --engine paddleocr
│  │  │  └─ 全部不可用 → 标记 [待OCR] + 保留原文件
│  │  │     └─ 不跳过！生成占位符，后续补装后重跑
│  │  │
│  │  └─ OCR 错误处理（增强）：
│  │     ├─ 引擎未安装 → pip install → 重试
│  │     ├─ Python 版本不兼容 → 降级到下一个引擎 → 重试
│  │     ├─ 图片质量差 → 图像增强预处理 → 重试
│  │     │   └─ 增强后仍失败 → 标记 [OCR失败: 图片质量过低]
│  │     ├─ 网络问题（模型下载失败）→ 重试 3 次，间隔递增
│  │     └─ 未知错误 → 收集完整错误日志 → 标记 + 汇总报告
│  │
│  └─ [1.4] 上下文窗口估算
│     ├─ 中文 ≈ 字数 × 1.5, 英文 ≈ 词数 × 1.3
│     ├─ token < 80% 上下文 → 直接全量处理
│     └─ token ≥ 80% 上下文 → 按章节边界拆分，分段处理
│
├─ PHASE 2: 资料类型分类（8 维逐层检视）
│  │
│  │  每层独立给分，按 `config/material_types.json` 优先级仲裁。
│  │  移除了"法条"维度——法条内容在笔记/教材章节中自然包含，不单独分类。
│  │
│  ├─ [2.1] 考纲/大纲？
│  │  ├─ 含"课程目标"+"学时"+"考核方式"？含学时分配表？
│  │  └─ YES → syllabus（最高优先级）→ 提取考点权重，写入 topic_map 骨架
│  │
│  ├─ [2.2] 重点/考点标记？
│  │  ├─ 含【★重点】【必考】【历年真题】【高频】？含"不考""了解即可"？
│  │  └─ YES → key_points → 提取标记项 + 与 topic_map 交叉验证
│  │
│  ├─ [2.3] 往年试题？
│  │  ├─ Q&A交替结构？题号+分值？含"简答题""论述题""名词解释"？
│  │  └─ YES → past_exams → 题型分类+年份标注+分值→考点频次统计
│  │
│  ├─ [2.4] 案例材料？（增强）
│  │  ├─ 含"原告""被告""法院认为""判决如下"？含案号？
│  │  ├─ YES → case_materials → 六段式结构化提取：
│  │  │  ① 案情事实  ② 当事人诉求/辩护  ③ 争议焦点归纳
│  │  │  ④ 裁判结果  ⑤ 关键论证  ⑥ 确立原则/后续影响
│  │  │
│  │  └─ 案例归属判断（关键）：
│  │     ├─ 案例在笔记/课件某个章节内被引用？→ 嵌入该章节
│  │     ├─ 案例是单独文件？
│  │     │   ├─ 仅涉及单一章节 → 嵌入对应章节
│  │     │   ├─ 涉及多章节，但后文章节非核心 → 嵌入主要涉及章节
│  │     │   └─ 涉及多章节，且后文章节为核心 → 放笔记最后（综合性案例）
│  │     │      判断标准：案例在笔记/课件中是章节内引用 vs 独立综合案例文件
│  │     └─ 案例后附Q&A？→ 逐题解答分析（案情仍六段式提供）
│  │
│  ├─ [2.5] 教材还是笔记？
│  │  ├─ 教材特征：层级标题规整、含"学习目标""课后习题""本章小结"
│  │  ├─ 笔记特征：非正式编号、含"老师""上课""PPT""→""ps:"
│  │  └─ 按 [0.7] 用户确认的优先级标记 primary/secondary
│  │
│  ├─ [2.6] 术语表/名词解释？
│  │  └─ YES → glossary → 术语-定义对拆分，按语言模式标注
│  │
│  ├─ [2.7] 学术论文/阅读材料？
│  │  └─ YES → reading_materials → 提取摘要+论点
│  │     └─ 注意：论文和阅读材料不区分，统一归入文献
│  │
│  └─ [2.8] 都不是 → 默认 lecture_notes
│
├─ PHASE 3: 课程归属 + 质量评估 + 去重
│  │
│  ├─ [3.1] 课程命名（用户主导，关键词辅助）
│  │  ├─ 先问："这些资料是关于哪门课/哪个考试的？"
│  │  ├─ 同时跑关键词轻量扫描 → "💡 看起来跟XX相关。是这个课吗？"
│  │  └─ 用户一句话决定 → 写入 course 字段
│  │
│  ├─ [3.2] 内容质量评估
│  │  ├─ 完整性：缺章节/缺上下文/缺附件 → 标记
│  │  ├─ 格式一致性：编号跳跃/表格残缺 → 标记
│  │  └─ 可信度：教材/课件=高, 个人笔记=中, 来源不明=低
│  │
│  └─ [3.3] 去重
│     ├─ 文件名相似度 > 85% + 文件大小相同 + 前800字相似 > 90%
│     └─ ≥2 项命中 → 重复，建议跳过
│
├─ PHASE 4: 项目目录结构创建
│  │
│  │  按用户命名的课程动态生成。法条嵌入章节，案例仅综合性独立案例单独列。
│  │
│  └─ 目录结构：
│     ```
│     复习资料/
│     └── {课程名}/
│         ├── 笔记/                   ← 各章节整合后的笔记
│         ├── 重点与考纲/             ← key_points + syllabus
│         ├── 试题/                   ← past_exams
│         ├── 案例/                   ← 仅综合性独立案例时创建
│         ├── 术语/                   ← glossary（如果有）
│         ├── 文献/                   ← 论文/阅读材料
│         ├── review/                 ← Phase 7 生成
│         │   ├── section_01.md
│         │   ├── ...
│         │   └── 复习材料_终稿.pdf
│         ├── _原始文件/              ← 原始文件只读保留
│         └── {课程}概述.md           ← MOC 索引
│     ```
│
├─ PHASE 5: 输出生成 + 进入复习判断
│  │
│  ├─ [5.1] 用户选择输出格式
│  │  ├─ PDF（默认，推荐打印装订）
│  │  ├─ MD / HTML / DOCX / ALL
│  │  └─ 用户未选 → 默认 PDF
│  │
│  ├─ [5.2] 上下文窗口分段
│  │  ├─ 单文件 token < 80% → 直接处理
│  │  └─ 单文件 token ≥ 80% → 按章节边界拆分 → 分段处理 → 合并
│  │
│  ├─ [5.3] 格式生成器（MD/HTML/PDF/DOCX）
│  │
│  └─ [5.4] 是否进入复习生成？
│     ├─ 含 syllabus / key_points / past_exams → "检测到备考材料，建议立即生成复习资料"
│     │   └─ 默认 YES → Phase 7
│     └─ 仅有 notes / textbook → "导入完成。是否需要生成复习资料？"
│         ├─ YES → Phase 7
│         └─ NO → 完成，输出导入摘要
│
├─ PHASE 7: 复习资料生成
│  │
│  │  设计原则：按章节逐个处理。每个章节先析出所有源材料内容，
│  │  再按优先级整合，产结构化内容，终检后进入下一章。
│  │
│  ├─ [7.1] 源材料盘点
│  │  ├─ 按资料类型分组展示 + 覆盖评估 + 缺源标记
│  │  ├─ 用户确认考试范围：哪些章不考？有额外考点？
│  │  └─ 为每份源材料生成来源索引（文件名 + 可定位的页/段/节），写入该章 source_index，供 Chapter Agent 引用。
│  │
│  ├─ [7.2] 建立考点映射（topic_map）
│  │  ├─ syllabus → 考点+权重（【必考】【★重点】【了解】）
│  │  ├─ key_points → 补充重点标记
│  │  ├─ past_exams → 高频考点+题型分布
│  │  ├─ 无 syllabus 降级：从笔记 H1/H2 自动生成
│  │  └─ topic_map 表格给用户确认调整【确认点②】
│  │
│  ├─ [7.3] 多 Agent 并行生成（核心）
│  │  │
│  │  │  原则：单 agent 上下文窗口有限 → 每章一个独立 sub-agent 并行启动。
│  │  │  每个 agent 独享上下文窗口，全量源材料，不跨章挤占 token。
│  │  │
│  │  │  Agent 数量 = Phase 2/3 确认的章节数（动态，非硬编码）。
│  │  │  **并发上限 8 个**（保证生成质量）。超过 8 章 → 分批：
│  │  │  Batch 1 前 8 章 → 全部完成 → Batch 2 剩余章节。
│  │  │
│  │  ├─ [7.3a-prep] 源材料 100% 提取 + 验证（硬阻塞，不可跳过）⚠️
│  │  │
│  │  │  此步骤是对源材料的**纯分发**，不做任何整合、摘要、过滤。
│  │  │  分发 = 把该章节在每个源文件中的对应内容**原样**打包给 Agent。
│  │  │  不达 100% → 阻塞 → 回退重做提取。不可以降低标准继续。
│  │  │
│  │  │  对每个章节，主 agent 必须逐项执行并输出验证结果：
│  │  │
│  │  │  验证项 1：英文笔记 — 该章节全部段落已提取？
│  │  │    检查：英文笔记中该章段落总数 = {N} | 已提取 = {M}
│  │  │    {M} = {N}? → ✅ 继续 | ❌ BLOCKED → 回退重新提取英文笔记
│  │  │
│  │  │  验证项 2：中文笔记/教材 — 该章节全部段落已提取？
│  │  │    检查：中文笔记中该章段落总数 = {N} | 已提取 = {M}
│  │  │    {M} = {N}? → ✅ 继续 | ❌ BLOCKED → 回退重新提取中文笔记
│  │  │
│  │  │  验证项 3：每个 PPT/PDF — 逐页文本已全部提取？
│  │  │    检查：PPT 总页数 = {N} | 已逐页提取 = {M}
│  │  │    检查：PDF 总页数 = {N} | 已逐页提取/全文提取 = {M}
│  │  │    {M} = {N} 且每页有内容? → ✅ | ❌ BLOCKED → 回退重新逐页提取
│  │  │
│  │  │  验证项 4：每个阅读材料/论文 — 全文或关键段落已提取？
│  │  │    检查：材料总数 = {N} | 已提取 = {M}
│  │  │    {M} = {N}? → ✅ | ❌ BLOCKED → 回退重新提取
│  │  │
│  │  │  验证项 5：每个案例 — 六段式完整结构化？
│  │  │    检查：案例总数 = {N} | 已六段式完整结构化 = {M}
│  │  │    每个案例的六段中是否有空段? → 有空段 ❌ BLOCKED
│  │  │    {M} = {N} 且全部完整? → ✅ | ❌ BLOCKED
│  │  │
│  │  │  全部 5 项验证通过 → 进入 [7.3b] 启动 Agent
│  │  │  任一项 BLOCKED → 输出阻塞报告 → 回到对应源文件重新提取 → 再次验证
│  │  │  禁止在 BLOCKED 状态下启动 Agent。禁止"先启动再说后面补"。
│  │  │
│  │  ├─ [7.3b] 启动：全部 Chapter Agent 并行执行
│  │  │  │
│  │  │  │  使用 Agent 工具同时启动 N 个 sub-agent（N ≤ 8）：
│  │  │  │
│  │  │  │  Agent_Ch1 → 生成 section_01.md（≥ 密度要求）
│  │  │  │  Agent_Ch2 → 生成 section_02.md
│  │  │  │  ...
│  │  │  │  Agent_ChN → 生成 section_NN.md
│  │  │  │
│  │  │  │  每个 Agent 使用以下标准指令模板：
│  │  │  │
│  │  │  ├─ [7.3c] Chapter Agent 标准指令模板
│  │  │  │
│  │  │  │  每个 Chapter Agent 收到完全相同的指令结构，仅源材料不同：
│  │  │  │
│  │  │  │  ┌──────────────────────────────────────────────────────┐
│  │  │  │  │  你是期末复习材料撰写专家。你的任务是独立完成        │
│  │  │  │  │  **第X章：[章节名]** 的期末复习稿。                  │
│  │  │  │  │  你有独立的上下文窗口，不需要考虑其他章节。         │
│  │  │  │  │                                                      │
│  │  │  │  │  ## 源材料（全量）                                   │
│  │  │  │  │  [粘贴该章节全部源材料]                              │
│  │  │  │  │                                                      │
│  │  │  │  │  ## 内容规则                                         │
### 必须保留（精简版）                                │
│  │  │  │  │  - 概念的定义、构成要件、法律后果——每考点1-3段      │
│  │  │  │  │  - 核心论证逻辑（一句话点明，不堆砌背景）            │
│  │  │  │  │  - 比较法差异——用对比表格呈现，不逐国叙述          │
│  │  │  │  │  - 学术争议——双方各1句核心论点，不铺陈论据链       │
│  │  │  │  │  - 老师明确强调的观点/立场                           │
│  │  │  │  │  - 核心标准要素——用表格/清单列出+简短说明          │
│  │  │  │  │  - 案例——每个1-2段（不必六段式，除非极重要）       │
│  │  │  │  │  - 往年真题关联——标注哪些考点考过                  │
### 必须删除                                            │
│  │  │  │  │  - 长法条原文 -> 仅保留"构成要件+法律效果"          │
│  │  │  │  │  - 同一观点反复表述 -> 保留最精炼版本                │
│  │  │  │  │  - 冗余过渡句（"首先""如上所述"等）                │
│  │  │  │  │  - 背景知识拓展、课堂逸事、个人经历                │
│  │  │  │  │  - 每个考点前面的长篇引言                           │
│  │  │  │  │  - 大段论文原文引用 -> 改为1-2句概括核心结论        │
## 输出规范                                             │
│  │  │  │  │                                                      │
│  │  │  │  │  1. 四段式结构：定义->构成要件->法律后果->评价       │
│  │  │  │  │  2. 表格格式——使用干净管道表格，:---:对齐：         │
│  │  │  │  │     | 概念 | 构成要件 | 法律效果 |                    │
│  │  │  │  │     |:----|:--------|:--------|                       │
│  │  │  │  │     | XX  | A+B+C   | YY      |                       │
│  │  │  │  │  3. 对比/分类表>=1个，替代流程图/层级图              │
│  │  │  │  │  4. 案例1段话：案名->要点->结论（极重要用2段）      │
│  │  │  │  │  5. 语言模式：按 session 中 language_mode 执行      │
│  │  │  │  │  6. 末尾 ## 考点速记，2列（考点|考查方式），<=15行   │
│  │  │  │  │  7. 禁止废话（综上所述/由此可见等）                   │
│  │  │  │  │  8. 禁止每个考点前加序号（一、二、三）               │
│  │  │  │  │  9. 末尾必须输出 ## 本章源索引 表格：                │
│  │  │  │  │     | 源编号 | 源文件 | 位置 | 本章使用要点 |        │
│  │  │  │  │     |:------|:------|:----|:------------|            │
│  │  │  │  │     | 源1   | 《笔记》 | 第X章第Y段 | 概念定义 |      │
│  │  │  │  │                                                      │
│  │  │  │  │  ### 反幻觉与来源引用规则（不可违反）               │
│  │  │  │  │  1. 源材料边界：所有定义、构成要件/要素、法律后果、   │
│  │  │  │  │     测试标准、案例结论、数据、引用句必须直接来自本    │
│  │  │  │  │     Chapter Agent 收到的源材料。禁止引入未提供的     │
│  │  │  │  │     背景知识。                                       │
│  │  │  │  │  2. 强制标注：凡出现关键信息，必须紧跟来源标注：      │
│  │  │  │  │     • 概念定义、构成要件、核心公式、测试标准          │
│  │  │  │  │     • 案例名称/要点/结论                             │
│  │  │  │  │     • 老师明确强调的观点                             │
│  │  │  │  │     • 数值、年份、比例、阈值                         │
│  │  │  │  │     格式：`（来源：《文件名》第X页/第X段）`；无页码   │
│  │  │  │  │     时用最近层级标题：`（来源：《文件名》·第X章/第X节）`│
│  │  │  │  │     图片/扫描件/PPT截图：`（来源：图片《文件名》）`   │
│  │  │  │  │  3. 信息不足：源材料缺失或仅一笔带过，不得编造，      │
│  │  │  │  │     应标注 `【源材料未涉及 / 待核实】` 并跳过细节。   │
│  │  │  │  │  4. 冲突处理：不同源材料表述冲突时，列出各方表述并    │
│  │  │  │  │     分别标注来源，不可自行调和为单一答案。           │
│  │  │  │  │  5. 禁止措辞：禁用"一般来说"、"普遍认为"、"众所周    │
│  │  │  │  │     知"等无来源支持的概括。                          │
│  │  │  │  │  6. 视觉材料：由模型视觉读取的图片/扫描件/PPT截图，   │
│  │  │  │  │     只描述可见内容，不推断未明确出现的文字或数字。   │
│  │  │  │  │  7. 不伪造页码：无法定位具体位置时，只标注到文件    │
│  │  │  │  │     层级即可。                                       │
## 总量约束（按 session 中 review_density，硬性）        │
│  │  │  │  │  当前选择：`{review_density}`。全稿总字数必须落在对应区间，单章定额按本章权重执行。│
│  │  │  │  │                                                      │
│  │  │  │  │  **精简版（3–4万字）**                               │
│  │  │  │  │  | 权重 | 中文字目标 | 约合行数 |                   │
│  │  │  │  │  |------|:----------:|:--------:|                   │
│  │  │  │  │  | 必考 | 7000–9000  | 230–300 |                   │
│  │  │  │  │  | 重点 | 4500–6500  | 150–220 |                   │
│  │  │  │  │  | 了解 | 1500–2500  | 50–80   |                   │
│  │  │  │  │                                                      │
│  │  │  │  │  **标准版（6–8万字）**                               │
│  │  │  │  │  | 权重 | 中文字目标 | 约合行数 |                   │
│  │  │  │  │  |------|:----------:|:--------:|                   │
│  │  │  │  │  | 必考 | 13000–17000 | 430–560 |                  │
│  │  │  │  │  | 重点 | 9000–13000  | 300–430 |                  │
│  │  │  │  │  | 了解 | 3500–5500   | 120–180 |                  │
│  │  │  │  │                                                      │
│  │  │  │  │  **详细版（10–12万字）**                             │
│  │  │  │  │  | 权重 | 中文字目标 | 约合行数 |                   │
│  │  │  │  │  |------|:----------:|:--------:|                   │
│  │  │  │  │  | 必考 | 22000–28000 | 730–930 |                  │
│  │  │  │  │  | 重点 | 15000–20000 | 500–660 |                  │
│  │  │  │  │  | 了解 | 6000–9000   | 200–300 |                  │
│  │  │  │  │                                                      │
│  │  │  │  │  超出定额意味其他章被压缩；不足则必须补充源材料细节，禁止灌水。│
│  │  │  │  │  生成后对照源材料逐条核实：该章涉及的核心概念/        │
│  │  │  │  │  测试/要件是否全部出现在复习稿中？                    │
│  │  │  │  │  如有遗漏 → 补充后再输出。                           │
│  │  │  │  └──────────────────────────────────────────────────────┘
│  │  │
│  │  └─ [7.3d] 分批策略
│  │     │
│  │     │  章节数 N ≤ 8 → 全部 Agent 在同一轮并行启动
│  │     │  章节数 N > 8 → 分批：
│  │     │    Batch 1: 前 8 章并行 → 全部完成
│  │     │    Batch 2: 剩余章节并行
│  │     │    Merge Agent 合并所有批次输出
│  │     │
│  │     └─ 主 agent 等待全部 Agent 完成 → 收集所有 section 文件
│  │
│  └─ [7.4] Merge + Quality Review
│     │
│     ├─ [7.4a] Merge Agent
│     │  ├─ 输入：所有已完成 section_NN.md
│     │  ├─ 合并为 `{课程}/review/复习材料_终稿.md`
│     │  ├─ 添加总目录（含各章链接）
│     │  ├─ 添加尾页：考点覆盖统计 + 源材料完整清单 + 全局 ## 源材料索引 表格
│     │
│     └─ [7.4b] Review Agent（独立 sub-agent，fresh eyes）
│        ├─ 总字数落在所选 density tier：精简版 3–4万 / 标准版 6–8万 / 详细版 10–12万
│        ├─ 每章密度达标（按 tier 下界核查）：
│        │    精简版：必考 ≥7000 / 重点 ≥4500 / 了解 ≥1500
│        │    标准版：必考 ≥13000 / 重点 ≥9000 / 了解 ≥3500
│        │    详细版：必考 ≥22000 / 重点 ≥15000 / 了解 ≥6000
│        ├─ 课程知识点清单 100% 通过——逐章核对源材料中的核心概念/测试/要件
│        ├─ 每章 ≥ 2 个结构化图表
│        ├─ 每章末尾有考点速记表格
│        ├─ 每章末尾有 ## 本章源索引 表格
│        ├─ 交叉验证：各章之间的引用一致性
│        ├─ 源引用审计：每章所有定义、要件、结论性陈述均含来源标注；随机抽查 5 处，验证标注文件真实存在且 claim 未夸大源材料
│        ├─ 无 AI 幻觉：抽查 5 处关键判断 vs 源材料原文
│        └─ 不通过 → 标注问题章节与具体违规项 → 回到 [7.3b] 单独重做该章
│
│  [7.5] 输出：PDF 三引擎降级链（Phase 7 完成的必要条件）
│     │
│     ├─ [7.5a] 格式生成
│     │  ├─ 默认 PDF——不可降级，不可跳过
│     │  │  └─ `python tools/output_writer.py --input review/ --format pdf`
│     │  ├─ 同步生成 MD（保留单章文件用于后续修改）
│     │  └─ PDF 生成失败? → 不是"降级到 MD 了事"
│     │     └─ 诊断原因 → 修复 → 重试
│     │     └─ 3 次重试仍失败 → 阻塞 + 报告错误详情给用户
│     │
│     └─ [7.5b] 完成条件（全部满足才算 Phase 7 完成）
│        ├─ ✅ PDF 文件存在且可打开
│        ├─ ✅ 全稿行数达标（精简版 ≥ 9000 行 / 标准版 ≥ 18000 行 / 详细版 ≥ 28000 行）
│        ├─ ✅ 全稿总字数落在所选 density tier 区间
│        ├─ ✅ 每章密度达标（按 tier 下界）
│        ├─ ✅ 每章包含 ## 本章源索引
│        ├─ ✅ Review Agent 全部检查项通过
│        └─ 任一 ❌ → 不视为完成 → 回到对应步骤重做
│
│  [EXIT GATE] Phase 7 完成验证（任何情况下不可跳过）⚠️
│     │
│     │  在向用户报告"Phase 7 完成"之前，必须逐项验证：
│     │
│     ├─ □ section 文件数：topic_map 章节数={N} | review/ 中 section_*.md={M}
│     │     {M}={N}? → ✅ | ❌ 缺失章节 → 回 [7.3b] 重做缺失章
│     │
│     ├─ □ PDF 存在：复习材料_终稿.pdf 存在且 > 0 字节? → ✅ | ❌ → 回 [7.5a]
│     │
│     ├─ □ 密度：全稿落在所选 tier（精简版 3–4万 / 标准版 6–8万 / 详细版 10–12万）?
│     │     必考章达到 tier 下界? 重点章达到 tier 下界? 了解章达到 tier 下界?
│     │     （精简版：必考≥7000 重点≥4500 了解≥1500）
│     │     （标准版：必考≥13000 重点≥9000 了解≥3500）
│     │     （详细版：必考≥22000 重点≥15000 了解≥6000）
│     │     全部达标 → ✅ | 任一不达标 → 标注不足章 → 回 [7.3b] 重做
│     │
│     ├─ □ 源索引：每章均包含 ## 本章源索引 表格且非空?
│     │     全部达标 → ✅ | 任一不达标 → 回到 [7.3b] 重做该章
│     │
│     ├─ □ Review Agent：[7.4b] 已执行且全部 ✅? → ✅ | ❌ → 先执行 [7.4b]
│     │
│     └─ 全部 ✅ → 允许报告"Phase 7 完成" | 任一 ❌ → 禁止报告 → 回对应步骤
│
└─ ERROR PATHS（降级不崩溃）
   ├─ Phase 0 路径不存在 → 重输
   ├─ Phase 1 格式不支持 → 标记"需手动处理"
   ├─ Phase 1 OCR 引擎未安装 → pip install → 重试
   ├─ Phase 1 Python版本不兼容 → 降级下一引擎 → 重试
   ├─ Phase 1 图片质量差 → 增强预处理 → 重试
   ├─ Phase 1 OCR 全链路失败 → 标记 [OCR失败] + 保留原文件 + 占位符
   ├─ Phase 1 大文件无法分段 → 截取前60%
   ├─ Phase 2 类型无法确定 → 默认 lecture_notes
   ├─ Phase 3 课程不明 → "待分类"
   ├─ Phase 4 目录创建失败 → 检查权限
   ├─ Phase 5 格式生成失败 → 降级到 MD
   ├─ Phase 7 无考纲 → 从笔记标题自动生成 topic_map
   ├─ Phase 7 源材料不足 → 仅生成已有章节 + 标记 [缺源]
   ├─ Phase 7 全稿过短 → 不灌水，标记"建议补充源材料"
   └─ 全局：单文件失败 → 跳过 + 继续其余 + 汇总报告列出全部失败项

独立调用 Phase 7（已有资料，直接生成复习）

如果用户已有整理好的课程目录（不管是之前导入的还是手动整理的）：

用户："帮我生成国际经济学复习资料" / "期末了，帮我整理XX课"

Claude：
  1. 扫描 {课程} 目录下所有 .md 文件
  2. 识别 syllabus（含"考纲/大纲"）→ topic_map 骨架
  3. 识别 key_points（含【★重点】）→ 权重补充
  4. 识别 past_exams → 频次统计
  5. 无 syllabus → 从笔记 H1/H2 自动生成 topic_map
  6. 进入 Phase 7.3 → 逐章生成复习稿 + 考点速记

安全原则

1. 只读原始文件：绝不移动/删除/修改。导入 = 复制+转换。
2. 新增不覆盖：同名文件自动加 _2 _3 后缀。
3. 来源可追溯：每个输出文件记录原始路径。
4. 失败安全：单文件失败不中断整体流程。
5. 确认门禁：Phase 0 文件选择 + Phase 7 topic_map 两次确认。
6. OCR 本地处理：不上传图片到任何云端服务。

依赖

# Tier 1: 文档提取
pip install python-docx PyPDF2 python-pptx markdownify ebooklib chardet

# Tier 2: OCR（至少一个）
pip install easyocr       # 推荐：GPU加速，中文~92%，MIT许可
# 或 pip install pytesseract  # 轻量：需系统安装 Tesseract 引擎
# 或 pip install paddleocr    # 中文最强~96%，安装最重

# Tier 2: PDF 输出 (三引擎自动降级)
pip install fpdf2         # 纯Python零依赖PDF — 全平台永久保证 (核心)
pip install weasyprint    # 更佳排版 — 可选 (Windows需GTK3)

开源分发清单

final-review/
├── SKILL.md                    # 唯一源文件 — 完整工作流
├── README.md
├── LICENSE                     # MIT
├── requirements.txt
├── install.py                  # 多 agent 一键安装
├── setup.py                    # 环境检测引导
├── agents.json                 # agent 路径映射
├── agents/
│   └── codex-plugin.json
├── tools/
│   ├── file_finder.py
│   ├── ocr_tool.py
│   ├── format_converter.py
│   ├── classifier.py
│   ├── chunk_manager.py
│   └── output_writer.py
├── config/
│   ├── material_types.json     # 8 种资料类型 + 双语标注规则
│   ├── subject_keywords.json
│   └── platform_paths.json
├── templates/
│   └── html_template.html
└── examples/
    └── demo_usage.md