@zhouchangui/math-ati 0.1.1 → 0.1.3

package/server/practiceGenerator.js

@@ -1,9 +1,11 @@
 import { callChatAgent } from './agentClient.js';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { chapterDataPaths, isActionableMistake, readChapterMistakes, readJson } from './fileStore.js';
 import { flattenKnowledgePoints } from './knowledgeBase.js';
 import { promptPayload, readPrompt } from './promptStore.js';
 import { ABILITY_CATALOG } from './abilityService.js';
+import { verifyAndRepairSvgFigures } from './svgFigureVerifier.js';
 
 function generationError(reason, detail = '') {
   const error = new Error(`practice_generation_failed:${reason}`);
@@ -123,6 +125,86 @@ function chunkArray(items, size) {
   return chunks;
 }
 
+async function readStageCache(cacheDir, fileName) {
+  if (!cacheDir) return null;
+  try {
+    return JSON.parse(await readFile(path.join(cacheDir, fileName), 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+async function writeStageCache(cacheDir, fileName, data) {
+  if (!cacheDir) return;
+  await mkdir(cacheDir, { recursive: true });
+  await writeFile(path.join(cacheDir, fileName), `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+async function callPracticeAgentCached({ cacheDir, cacheFile, onProgress, ...input }) {
+  const cached = await readStageCache(cacheDir, cacheFile);
+  if (cached) {
+    onProgress?.({
+      step: 'practice_generate.cache_hit',
+      message: `复用阶段缓存：${cacheFile}。`
+    });
+    return cached;
+  }
+  const result = await callPracticeAgent(input);
+  if (result.ok) await writeStageCache(cacheDir, cacheFile, result);
+  return result;
+}
+
+function mergeRevisionQuestions(originalQuestions, revisedQuestions) {
+  const revisedById = new Map((revisedQuestions || []).map((question) => [question.id, question]));
+  return (originalQuestions || []).map((question) => revisedById.get(question.id) || question);
+}
+
+function omitSvgSourceForTextReview(question) {
+  if (!question || !question.svg) return question;
+  return {
+    ...question,
+    svg: '[inline SVG omitted from text review; rendered figure is reviewed separately]',
+    svgReview: question.svgReview
+      ? {
+          passed: question.svgReview.passed,
+          summary: question.svgReview.summary,
+          findings: question.svgReview.findings
+        }
+      : undefined
+  };
+}
+
+function omitSvgSourcesForTextReview(practiceDraft) {
+  return {
+    ...practiceDraft,
+    questions: (practiceDraft.questions || []).map(omitSvgSourceForTextReview)
+  };
+}
+
+function normalizeSvgSelectionItems(data) {
+  if (Array.isArray(data?.items)) return data.items;
+  if (!Array.isArray(data?.findings)) return [];
+  return data.findings
+    .map((finding) => {
+      const instruction = String(finding.fixInstruction || finding.visualPriority || '').toLowerCase();
+      const message = String(finding.message || '');
+      const priority = instruction.includes('required')
+        ? 'required'
+        : instruction.includes('useful')
+          ? 'useful'
+          : instruction.includes('not_needed') || instruction.includes('not needed')
+            ? 'not_needed'
+            : '';
+      return {
+        questionId: finding.questionId,
+        visualPriority: priority,
+        reason: message || finding.fixInstruction || ''
+      };
+    })
+    .filter((item) => item.questionId && item.visualPriority);
+}
+
 function contextForQuestions(baseContext, questions) {
   const usedIds = new Set();
   for (const question of questions || []) {
@@ -288,6 +370,204 @@ function coverageSummaryForQuestions(targetKnowledgePoints, questions) {
   };
 }
 
+async function selectQuestionsForSvgReview({
+  stageCacheDir,
+  onProgress,
+  baseContext,
+  revision,
+  minSvgQuestions
+}) {
+  const existingSvgIds = revision.questions
+    .filter((question) => String(question.svg || '').includes('<svg'))
+    .map((question) => question.id);
+  const targetCount = minSvgQuestions > 0
+    ? geometryVisualSampleCount(revision.questions.length, minSvgQuestions)
+    : existingSvgIds.length;
+  if (!targetCount) return existingSvgIds;
+  if (existingSvgIds.length >= targetCount && !minSvgQuestions) return existingSvgIds;
+  onProgress({
+    step: 'practice_generate.svg_select',
+    message: `正在判断哪些题需要配图或适合作为几何视觉校验样本（目标至少 ${targetCount} 题）。`
+  });
+  const result = await callPracticeAgentCached({
+    cacheDir: stageCacheDir,
+    cacheFile: 'svg-selection.json',
+    onProgress,
+    promptName: 'practice-review.system.md',
+    task: '判断定稿题目中哪些题需要或适合补充 SVG 配图，以便进入渲染后视觉校验。',
+    context: {
+      ...baseContext,
+      practiceDraft: omitSvgSourcesForTextReview(revision)
+    },
+    requirements: [
+      '逐题判断题目是否需要视觉信息才能唯一作答。',
+      'required 表示没有图会导致位置关系、展开图、角、线段、射线方向、交点数量等条件不完整或不唯一。',
+      'useful 表示题目文字可答，但配图能显著降低几何表述歧义，适合作为几何 SVG 回归样本。',
+      'not_needed 表示纯概念、纯换算或纯文字辨析，配图不会增加有效信息。',
+      `如果 required 题不足 ${targetCount} 题，请从 useful 中按最能验证几何画图机制的题补足。`,
+      '不要因为题目属于几何章节就机械判 required；必须说明理由。'
+    ],
+    schema: {
+      items: [{
+        questionId: 'q1',
+        visualPriority: 'required|useful|not_needed',
+        reason: 'string'
+      }]
+    }
+  });
+  const selectionItems = result.ok ? normalizeSvgSelectionItems(result.data) : [];
+  if (!result.ok || !selectionItems.length) {
+    const attempts = result.attempts ? ` attempts=${result.attempts}` : '';
+    throw generationError(`svg_selection_${result.reason || 'invalid_agent_response'}`, `${result.detail || ''}${attempts}`);
+  }
+  const validQuestionIds = new Set(revision.questions.map((question) => question.id));
+  const required = selectionItems
+    .filter((item) => item.visualPriority === 'required' && validQuestionIds.has(item.questionId))
+    .map((item) => item.questionId);
+  const useful = selectionItems
+    .filter((item) => item.visualPriority === 'useful' && validQuestionIds.has(item.questionId))
+    .map((item) => item.questionId);
+  const selected = [...new Set([...existingSvgIds, ...required])];
+  for (const questionId of useful) {
+    if (selected.length >= targetCount) break;
+    selected.push(questionId);
+  }
+  if (selected.length < targetCount) {
+    for (const question of revision.questions) {
+      if (selected.length >= targetCount) break;
+      if (!selected.includes(question.id)) selected.push(question.id);
+    }
+  }
+  onProgress({
+    step: 'practice_generate.svg_select_done',
+    message: `已选择 ${selected.length} 道题进入 SVG 补图/渲染审查：${selected.join('、')}。`
+  });
+  return {
+    questionIds: selected,
+    strictQuestionIds: [...new Set([...existingSvgIds, ...required])]
+  };
+}
+
+async function runFinalReview({
+  stageCacheDir,
+  cacheFile,
+  onProgress,
+  baseContext,
+  revision,
+  revisionCoverage,
+  initialReview,
+  isAbilityAssessment
+}) {
+  return callPracticeAgentCached({
+    cacheDir: stageCacheDir,
+    cacheFile,
+    onProgress,
+    promptName: 'practice-review.system.md',
+    task: '复审修订后的最终练习题目和知识点绑定；本阶段不评审答案元数据',
+    context: {
+      ...baseContext,
+      practiceDraft: omitSvgSourcesForTextReview(revision),
+      localCoverageCheck: revisionCoverage,
+      initialReview
+    },
+    requirements: [
+      '这是定稿复审；评审题目质量、可作答性、重复风险、题量规划和 knowledgePointIds。',
+      '如果仍有 blocker，必须 passed=false，并指出具体题号和修正原因。',
+      '必须拦截题目条件缺失、答案不唯一、选项不完整、知识点绑定不在 targetKnowledgePoints 中的问题。',
+      '覆盖判断必须以 context.localCoverageCheck 为准；只有 missingPointIds 或 outsidePointIds 非空时，才能给 bad_coverage blocker。',
+      '必须检查 knowledgePoints、expectedErrorTypes、skillAtoms、expectedAbilityErrors 是否为纯文本标签；出现 $...$、\\(...\\)、\\[...\\]、HTML 或公式包装时要求修正。',
+      isAbilityAssessment ? '能力评估题必须检查 abilityIds 是否完整且只来自 context.options.abilityIds。' : '',
+      '定稿复审必须拦截 LaTeX 反斜杠损坏、制表符残留、几何/SVG 标注与题干不一致、标签遮挡关键条件。'
+    ].filter(Boolean),
+    schema: {
+      passed: false,
+      summary: 'string',
+      findings: [{
+        level: 'blocker|warning',
+        type: 'string',
+        questionId: 'q1',
+        message: 'string',
+        fixInstruction: 'string'
+      }],
+      coverage: {
+        coveredPointIds: ['chapter-01-kp-01'],
+        missingPointIds: ['chapter-01-kp-02']
+      }
+    }
+  });
+}
+
+async function repairFinalBlockers({
+  stageCacheDir,
+  onProgress,
+  baseContext,
+  revision,
+  finalBlockers,
+  isAbilityAssessment,
+  repairRound = 1
+}) {
+  const globalFindings = finalBlockers.filter((finding) => !finding.questionId);
+  const questionIds = new Set(finalBlockers.map((finding) => finding.questionId).filter(Boolean));
+  const questionsToRevise = globalFindings.length
+    ? revision.questions
+    : revision.questions.filter((question) => questionIds.has(question.id));
+  if (!questionsToRevise.length) return revision;
+  const chunks = chunkArray(questionsToRevise, 4);
+  const revisionChunks = [];
+  for (let index = 0; index < chunks.length; index += 1) {
+    const questions = chunks[index];
+    const chunkQuestionIds = questions.map((question) => question.id);
+    const findings = finalBlockers
+      .filter((finding) => !finding.questionId || chunkQuestionIds.includes(finding.questionId));
+    onProgress({
+      step: 'practice_generate.final_blocker_repair',
+      message: `正在按终审 blocker 修订题目：第 ${index + 1}/${chunks.length} 批（${chunkQuestionIds.join('、')}）。`
+    });
+    const chunk = assertAgentQuestions(await callPracticeAgentCached({
+      cacheDir: stageCacheDir,
+      cacheFile: `final-blocker-revision-r${String(repairRound).padStart(2, '0')}-chunk-${String(index + 1).padStart(2, '0')}.json`,
+      onProgress,
+      promptName: 'practice-revise.system.md',
+      task: `根据最终复审 blocker 修正题目（第 ${repairRound} 轮，第 ${index + 1}/${chunks.length} 批）`,
+      context: {
+        ...contextForQuestions(baseContext, questions),
+        practiceDraft: {
+          ...revision,
+          questions: questions.map(omitSvgSourceForTextReview)
+        },
+        review: {
+          passed: false,
+          summary: '最终复审发现 blocker，必须逐项修复后才能生成试卷。',
+          findings
+        }
+      },
+      requirements: [
+        '必须逐条修复终审 blocker，不能只复述问题。',
+        '如果 blocker 类型是 bad_options、unanswerable 或指出答案不唯一，必须先保证题目存在唯一、明确、可判分的答案；选择题必须确保四个选项中恰好一个正确。',
+        '遇到选项唯一性问题时，不要只微调一个模糊选项；如果不能确信唯一正确，必须重写整道题的题干和全部选项，必要时改成填空题或简答题。',
+        '正方体展开图等视觉题不要使用“可能、并非明显、也许可以”这类不确定条件作为错误选项；错误选项必须是概念上明确错误或与给定图形明确矛盾。',
+        '只输出 practiceDraft.questions 中的题目，不新增题目，不删除题目，不改变题目 ID。',
+        '保持 knowledgePointIds 来自 targetKnowledgePoints；如果修复导致知识点绑定变化，必须同步改题干使题目仍可作答。',
+        '修订版必须包含题目、题型、难度、knowledgePointIds、knowledgePoints、expectedErrorTypes、配图字段和答题空间行数。',
+        isAbilityAssessment ? '能力评估修订版还必须保留 abilityIds、skillAtoms、expectedAbilityErrors。' : '',
+        '如果 blocker 指出题目缺图或视觉信息不清，必须补充或修复内联 SVG，并确保题干与图中标签完全一致。',
+        '不要输出 answer、solutionSteps 或 rubric；这些字段会在题目定稿后分批补全。'
+      ].filter(Boolean),
+      schema: questionRevisionSchema()
+    }), 'final_blocker_revision');
+    revisionChunks.push(chunk);
+  }
+  const firstRevision = revisionChunks[0] || {};
+  return {
+    title: normalizePracticeTitle(firstRevision.title || revision.title),
+    personalizationBasis: firstRevision.personalizationBasis || revision.personalizationBasis || [],
+    revisionSummary: [revision.revisionSummary, ...revisionChunks.map((chunk) => chunk.revisionSummary)]
+      .filter(Boolean)
+      .join('\n'),
+    questions: mergeRevisionQuestions(revision.questions, revisionChunks.flatMap((chunk) => chunk.questions))
+  };
+}
+
 function answerMetadataSchema() {
   return {
     questions: [{
@@ -302,6 +582,56 @@ function answerMetadataSchema() {
   };
 }
 
+function questionRevisionSchema() {
+  return {
+    title: 'string',
+    personalizationBasis: ['string'],
+    revisionSummary: 'string',
+    questions: [{
+      id: 'q1',
+      stem: 'plain text with LaTeX delimiters; only question',
+      questionKind: 'choice|blank|short_answer',
+      difficulty: 'basic|medium|challenge',
+      knowledgePointIds: ['chapter-01-kp-01'],
+      knowledgePoints: ['plain Chinese tag label, no LaTeX delimiters or HTML'],
+      expectedErrorTypes: ['plain Chinese tag label, no LaTeX delimiters or HTML'],
+      abilityIds: ['calculation_accuracy'],
+      skillAtoms: ['plain Chinese calculation skill atom'],
+      expectedAbilityErrors: ['plain Chinese ability error label, no LaTeX delimiters or HTML'],
+      svg: 'optional inline SVG string',
+      imagePrompt: 'optional gpt-image-2 prompt',
+      score: 6,
+      answerSpaceLines: 2
+    }]
+  };
+}
+
+function compactFinding(finding) {
+  return [
+    finding.questionId || 'global',
+    finding.type || 'unknown',
+    finding.message || '',
+    finding.fixInstruction ? `修复：${finding.fixInstruction}` : ''
+  ].filter(Boolean).join(' - ');
+}
+
+function blockerDetail(findings) {
+  return (findings || []).map(compactFinding).join(' | ');
+}
+
+function blockerMessage(findings, prefix = '最终复审仍有 blocker') {
+  const list = (findings || []).map(compactFinding);
+  if (!list.length) return prefix;
+  return `${prefix}：${list.slice(0, 4).join('；')}${list.length > 4 ? `；另 ${list.length - 4} 条` : ''}`;
+}
+
+function geometryVisualSampleCount(totalQuestionCount, configuredCount) {
+  const requested = Number(configuredCount);
+  if (Number.isFinite(requested) && requested > 0) return Math.floor(requested);
+  const total = Math.max(1, Number(totalQuestionCount || 0));
+  return Math.max(1, Math.min(4, Math.ceil(total / 4)));
+}
+
 function mergeAnswerMetadata(questions, answerChunks) {
   const answersById = new Map();
   for (const chunk of answerChunks) {
@@ -396,8 +726,27 @@ function recommendedQuestionCount(targetCount, maxQuestionCount) {
   return Math.max(3, Math.min(maxCount, Math.ceil(targetCount / 2)));
 }
 
-async function callPracticeAgent({ promptName, task, context, requirements, schema, timeoutMs = 120000, temperature = 0.2, retries = 2 }) {
+function isGeometryLikeChapter(chapter) {
+  const text = `${chapter?.title || ''} ${chapter?.fullTitle || ''} ${chapter?.track || ''}`;
+  return /几何|图形|三角形|平行|垂直|圆|角|线段|直线|射线|展开图|立体/.test(text);
+}
+
+async function readPracticeSystemPrompt(promptName, context) {
   const systemPrompt = await readPrompt(promptName);
+  const geometryPromptNames = new Set([
+    'practice-generate.system.md',
+    'practice-review.system.md',
+    'practice-revise.system.md'
+  ]);
+  if (!geometryPromptNames.has(promptName) || !isGeometryLikeChapter(context?.chapter)) {
+    return systemPrompt;
+  }
+  const geometryExperience = await readPrompt('geometry-practice-experience.md');
+  return `${systemPrompt}\n\n${geometryExperience}`;
+}
+
+async function callPracticeAgent({ promptName, task, context, requirements, schema, timeoutMs = 120000, temperature = 0.2, retries = 1 }) {
+  const systemPrompt = await readPracticeSystemPrompt(promptName, context);
   return callChatAgent({
     timeoutMs,
     retries,
@@ -474,6 +823,11 @@ async function generationHistory(chapterId) {
 export async function generatePracticeContent(input) {
   const { profile, chapter, options } = input;
   const onProgress = progressReporter(input.onProgress);
+  const stageCacheDir = options.generationCacheDir || '';
+  const fastReview = Boolean(options.fastReview);
+  const verifySvgFigures = Boolean(options.verifySvgFigures);
+  const requireSvg = Boolean(options.requireSvg);
+  const minSvgQuestions = Number(options.minSvgQuestions || 0);
   onProgress({ step: 'practice_generate.history', message: '正在整理历史题目和近期错因。' });
   const history = await generationHistory(chapter.id);
   const knowledgeDoc = options.knowledgeDoc;
@@ -559,6 +913,7 @@ export async function generatePracticeContent(input) {
     history
   };
   const isAbilityAssessment = options.type === 'ability_assessment';
+  const isMistakeRepair = options.type === 'mistake_repair';
   const baseRequirements = [
     '全部内容只能由 LLM 生成，不能使用本地模板或规则兜底。',
     '题目之间不能重复，也不要和 previousStems 高度相似。',
@@ -572,7 +927,9 @@ export async function generatePracticeContent(input) {
       ? '本次是指定知识点范围覆盖，只能围绕 targetKnowledgePoints 出题，不要覆盖范围外知识点；必须用少题高覆盖策略，一道题可以覆盖多个紧密相关知识点。'
       : isAbilityAssessment
         ? '本次是能力评估卷：目标来自 abilitySpecs 与本章知识范围，题目应围绕能力表现取样，不要机械追求知识点全覆盖。'
-        : '本次是章节知识点覆盖卷，不要要求用户提供知识点编号；首轮覆盖尚未完成时，knowledge_coverage 必须优先从 previousKnowledgePointIds 没有覆盖过的 targetKnowledgePoints 出题；已覆盖点只做必要合并抽样。首轮完成后，再按 needs_review、wrongCount 高和 recentMistakes 命中的点优先。',
+        : isMistakeRepair
+          ? '本次是易错点覆盖/巩固卷：优先围绕 recentMistakes、needs_review、wrongCount 高的知识点和易错类型设计题目；如果当前没有可用易错点，则生成基础巩固卷，但题目仍要体现常见易错辨析，不要伪装成首轮知识点覆盖。'
+          : '本次是章节知识点覆盖卷，不要要求用户提供知识点编号；首轮覆盖尚未完成时，knowledge_coverage 必须优先从 previousKnowledgePointIds 没有覆盖过的 targetKnowledgePoints 出题；已覆盖点只做必要合并抽样。首轮完成后，再按 needs_review、wrongCount 高和 recentMistakes 命中的点优先。',
     isAbilityAssessment
       ? '能力评估第一版只评估计算准确性，不纳入用时、速度、限时达标；题目以短题、多题、低语境为主，尽量暴露计算准确性和常见计算错误。'
       : '',
@@ -588,16 +945,20 @@ export async function generatePracticeContent(input) {
     'knowledgePoints 和 expectedErrorTypes 是讲解版胶囊标签，只能写纯中文短标签；禁止使用 $...$、\\(...\\)、\\[...\\]、HTML 或复杂公式包装。例如写“特殊值 0 误判”，不要写“特殊值 $0$ 误判”。',
     '题干只放题目，不放解题过程。',
     '可以在题干中使用 Markdown 表格表达分类、对照或数据，但不要使用 HTML table 标签。',
-    '题目使用纯文本加 LaTeX 分隔符；只有几何、数轴或图形题必要时才使用内联 SVG 或 imagePrompt。',
+    '题目使用纯文本加 LaTeX 分隔符；出题时必须先判断题目是否需要视觉信息才能作答。',
     'LaTeX 命令必须保留完整反斜杠，例如 \\triangle、\\angle、\\perp、\\parallel、\\text{}；禁止输出 triangle/riangle/angle/perp/parallel/ext{} 或把 \\t 变成制表符。',
-    '几何、数轴或 SVG 图形题必须保证题干、图中标签、角弧、垂直/平行/长度标注完全一致；如果题干问 angle 2、切点、垂足或某条边，图中对应位置必须准确。',
+    '如果没有图，题干必须仍然信息完整、唯一可答、无需学生凭想象补出位置关系或图形结构；否则必须提供内联 SVG，或把题目改写成纯文字可答题。',
+    '展开图、折叠、图形甲/乙、点线面位置、直线/射线/线段位置、角、垂直、平行、中点、延长线、交点数量、方格拼图等通常需要视觉判断，但这不是固定清单；最终以本题是否依赖视觉信息为准。',
+    '几何、数轴或 SVG 图形题必须保证题干、图中标签、角弧、垂直/平行/长度标注完全一致；如果题干问 angle 2、切点、垂足、某条边或某个展开图，SVG 中对应位置必须准确。',
     'SVG 标签必须可读且不遮挡线段、角弧、表格或答题区；优先使用简单清晰的线图。',
     '题面不给学生显示分值，不要在题干里写“本题多少分”。',
     '第一阶段只生成题面、题型、知识点绑定、预期错因、分值和留白行数；answer、solutionSteps、rubric 会在题目定稿后由第二阶段分批补全。'
   ].filter(Boolean);
   onProgress({
     step: 'practice_generate.plan',
-    message: `正在分析首轮覆盖策略：已覆盖 ${firstRoundCoveredIds.length}/${compactTargetKnowledgePoints.length} 个知识点，本次候选 ${targetKnowledgePoints.length} 个。`
+    message: isMistakeRepair
+      ? `正在分析易错巩固策略：当前可用易错点 ${history.recentMistakes.length} 个，本次候选知识点 ${targetKnowledgePoints.length} 个。`
+      : `正在分析首轮覆盖策略：已覆盖 ${firstRoundCoveredIds.length}/${compactTargetKnowledgePoints.length} 个知识点，本次候选 ${targetKnowledgePoints.length} 个。`
   });
   const questionGenerationRequirements = [
     ...baseRequirements,
@@ -613,7 +974,8 @@ export async function generatePracticeContent(input) {
     '不要输出 answer、solutionSteps 或 rubric；本阶段只定稿题目本身和知识点绑定。'
   ];
   const totalQuestionCount = options.questionCount || localRecommendedQuestionCount;
-  const questionTargetChunks = chunkArray(targetKnowledgePoints, 3);
+  const questionTargetChunkSize = totalQuestionCount <= 10 ? 4 : 5;
+  const questionTargetChunks = chunkArray(targetKnowledgePoints, questionTargetChunkSize);
   const questionBatchCounts = distributeQuestionCounts(questionTargetChunks, totalQuestionCount);
   const questionChunks = [];
   const promptName = 'practice-generate.system.md';
@@ -646,7 +1008,10 @@ export async function generatePracticeContent(input) {
       step: 'practice_generate.questions',
       message: `正在生成题目草稿：第 ${index + 1}/${questionTargetChunks.length} 批（${batchQuestionCount} 题，约 ${Math.round(requestChars / 1000)}KB 请求）。`
     });
-    const chunk = assertAgentQuestions(await callPracticeAgent({
+    const chunk = assertAgentQuestions(await callPracticeAgentCached({
+      cacheDir: stageCacheDir,
+      cacheFile: `question-chunk-${String(index + 1).padStart(2, '0')}.json`,
+      onProgress,
       promptName,
       task: batchTask,
       context: batchContext,
@@ -699,12 +1064,15 @@ export async function generatePracticeContent(input) {
     source: 'agent'
   });
   onProgress({ step: 'practice_generate.review', message: '正在评审题目可作答性、覆盖规划和知识点绑定。' });
-  const review = await callPracticeAgent({
+  const review = await callPracticeAgentCached({
+    cacheDir: stageCacheDir,
+    cacheFile: 'initial-review.json',
+    onProgress,
     promptName: 'practice-review.system.md',
     task: '评审练习题目草稿和知识点绑定；本阶段不评审答案元数据',
     context: {
       ...contextForQuestions(baseContext, practiceDraft.questions),
-      practiceDraft
+      practiceDraft: omitSvgSourcesForTextReview(practiceDraft)
     },
     requirements: [
       '至少完成一次 LLM review；发现问题必须给出具体修正指令。',
@@ -713,7 +1081,8 @@ export async function generatePracticeContent(input) {
       isAbilityAssessment ? '能力评估题必须检查 abilityIds 是否完整且只来自 context.options.abilityIds。' : '',
       '如果题目缺少必要条件、答案无法唯一推出、选项不完整或题型不合适，必须判 blocker。',
       '必须检查 LaTeX 反斜杠是否损坏，尤其是 \\triangle、\\angle、\\perp、\\parallel、\\text{}；发现丢反斜杠或制表符残留必须判 blocker。',
-      '必须检查几何/SVG 题的题干与图中角标、垂足、切点、边名、长度和平行/垂直标注是否一致；不一致必须判 blocker。'
+      '必须检查几何/SVG 题的题干与图中角标、垂足、切点、边名、长度和平行/垂直标注是否一致；不一致必须判 blocker。',
+      '必须由评审判断每道题是否需要视觉信息才能作答。若没有 svg 但题干仍信息完整、唯一可答，则不要因为题目属于几何题而判错；若缺少图会导致学生凭想象补条件、空间位置不明确或答案不唯一，必须判 blocker 并要求补 SVG 或改成纯文字题。'
     ].filter(Boolean),
     schema: {
       passed: false,
@@ -740,7 +1109,20 @@ export async function generatePracticeContent(input) {
     message: `质量评审完成：${review.data.findings.length} 条意见，开始修订题目。`
   });
   const revisionChunks = [];
-  const questionRevisionChunks = chunkArray(practiceDraft.questions, 3);
+  const globalReviewFindings = (review.data.findings || []).filter((finding) => !finding.questionId);
+  const questionIdsNeedingRevision = new Set((review.data.findings || [])
+    .map((finding) => finding.questionId)
+    .filter(Boolean));
+  const questionsToRevise = globalReviewFindings.length
+    ? practiceDraft.questions
+    : practiceDraft.questions.filter((question) => questionIdsNeedingRevision.has(question.id));
+  const questionRevisionChunks = chunkArray(questionsToRevise, 4);
+  if (!questionRevisionChunks.length) {
+    onProgress({
+      step: 'practice_generate.revision_skip',
+      message: '评审未提出逐题修改意见，跳过 LLM 修订阶段。'
+    });
+  }
   for (let index = 0; index < questionRevisionChunks.length; index += 1) {
     const questions = questionRevisionChunks[index];
     const questionIds = questions.map((question) => question.id);
@@ -750,14 +1132,17 @@ export async function generatePracticeContent(input) {
       step: 'practice_generate.revision',
       message: `正在修订题目：第 ${index + 1}/${questionRevisionChunks.length} 批（${questionIds.join('、')}）。`
     });
-    const revisionChunk = assertAgentQuestions(await callPracticeAgent({
+    const revisionChunk = assertAgentQuestions(await callPracticeAgentCached({
+      cacheDir: stageCacheDir,
+      cacheFile: `revision-chunk-${String(index + 1).padStart(2, '0')}.json`,
+      onProgress,
       promptName: 'practice-revise.system.md',
       task: `根据评审意见修正练习卷并输出修订版（第 ${index + 1}/${questionRevisionChunks.length} 批）`,
       context: {
         ...contextForQuestions(baseContext, questions),
         practiceDraft: {
           ...practiceDraft,
-          questions
+          questions: questions.map(omitSvgSourceForTextReview)
         },
         review: {
           ...review.data,
@@ -775,33 +1160,15 @@ export async function generatePracticeContent(input) {
         '必须修复 LaTeX 反斜杠损坏，并同步校准几何/SVG 题的题干与图中角标、垂足、切点、边名、长度和平行/垂直标注。',
         '不要输出未修正草稿。'
       ].filter(Boolean),
-      schema: {
-        title: 'string',
-        personalizationBasis: ['string'],
-        revisionSummary: 'string',
-        questions: [{
-          id: 'q1',
-          stem: 'plain text with LaTeX delimiters; only question',
-          questionKind: 'choice|blank|short_answer',
-          difficulty: 'basic|medium|challenge',
-          knowledgePointIds: ['chapter-01-kp-01'],
-          knowledgePoints: ['plain Chinese tag label, no LaTeX delimiters or HTML'],
-          expectedErrorTypes: ['plain Chinese tag label, no LaTeX delimiters or HTML'],
-          abilityIds: ['calculation_accuracy'],
-          skillAtoms: ['plain Chinese calculation skill atom'],
-          expectedAbilityErrors: ['plain Chinese ability error label, no LaTeX delimiters or HTML'],
-          svg: 'optional inline SVG string',
-          imagePrompt: 'optional gpt-image-2 prompt',
-          score: 6,
-          answerSpaceLines: 2
-        }]
-      }
+      schema: questionRevisionSchema()
     }), 'revision');
     revisionChunks.push(revisionChunk);
   }
-  const revisionQuestions = revisionChunks.flatMap((chunk) => chunk.questions);
+  const revisionQuestions = questionRevisionChunks.length
+    ? mergeRevisionQuestions(practiceDraft.questions, revisionChunks.flatMap((chunk) => chunk.questions))
+    : practiceDraft.questions;
   const firstRevision = revisionChunks[0] || {};
-  const revision = {
+  let revision = {
     title: normalizePracticeTitle(firstRevision.title || practiceDraft.title),
     personalizationBasis: firstRevision.personalizationBasis || practiceDraft.personalizationBasis || [],
     revisionSummary: revisionChunks
@@ -811,42 +1178,124 @@ export async function generatePracticeContent(input) {
     questions: revisionQuestions
   };
   onProgress({ step: 'practice_generate.revision_done', message: `题目修订完成：${revision.questions.length} 题。` });
-  const revisionCoverage = coverageSummaryForQuestions(targetKnowledgePoints, revision.questions);
-  onProgress({ step: 'practice_generate.final_review', message: '正在复审题目质量和重复风险。' });
-  const finalReview = await callPracticeAgent({
-    promptName: 'practice-review.system.md',
-    task: '复审修订后的最终练习题目和知识点绑定；本阶段不评审答案元数据',
-    context: {
-      ...baseContext,
-      practiceDraft: revision,
-      localCoverageCheck: revisionCoverage,
-      initialReview: review.data
-    },
-    requirements: [
-      '这是定稿复审；评审题目质量、可作答性、重复风险、题量规划和 knowledgePointIds。',
-      '如果仍有 blocker，必须 passed=false，并指出具体题号和修正原因。',
-      '必须拦截题目条件缺失、答案不唯一、选项不完整、知识点绑定不在 targetKnowledgePoints 中的问题。',
-      '覆盖判断必须以 context.localCoverageCheck 为准；只有 missingPointIds 或 outsidePointIds 非空时，才能给 bad_coverage blocker。',
-      '必须检查 knowledgePoints、expectedErrorTypes、skillAtoms、expectedAbilityErrors 是否为纯文本标签；出现 $...$、\\(...\\)、\\[...\\]、HTML 或公式包装时要求修正。',
-      isAbilityAssessment ? '能力评估题必须检查 abilityIds 是否完整且只来自 context.options.abilityIds。' : '',
-      '定稿复审必须拦截 LaTeX 反斜杠损坏、制表符残留、几何/SVG 标注与题干不一致、标签遮挡关键条件。'
-    ].filter(Boolean),
-    schema: {
-      passed: false,
-      summary: 'string',
-      findings: [{
-        level: 'blocker|warning',
-        type: 'string',
-        questionId: 'q1',
-        message: 'string',
-        fixInstruction: 'string'
-      }],
-      coverage: {
-        coveredPointIds: ['chapter-01-kp-01'],
-        missingPointIds: ['chapter-01-kp-02']
-      }
-    }
-  });
+  let revisionCoverage = coverageSummaryForQuestions(targetKnowledgePoints, revision.questions);
+  if (!isAbilityAssessment && revisionCoverage.missingPointIds.length) {
+    const missingPoints = targetKnowledgePoints.filter((point) => revisionCoverage.missingPointIds.includes(point.id));
+    onProgress({
+      step: 'practice_generate.coverage_repair',
+      message: `正在修复知识点覆盖缺口：${revisionCoverage.missingPointIds.join('、')}。`
+    });
+    const repair = assertAgentQuestions(await callPracticeAgentCached({
+      cacheDir: stageCacheDir,
+      cacheFile: 'coverage-repair.json',
+      onProgress,
+      promptName: 'practice-revise.system.md',
+      task: '在不新增题目、不删除题目的前提下修复定稿题目的知识点覆盖缺口',
+      context: {
+        ...baseContext,
+        practiceDraft: omitSvgSourcesForTextReview(revision),
+        localCoverageCheck: revisionCoverage,
+        missingTargetKnowledgePoints: missingPoints
+      },
+      requirements: [
+        '只修复覆盖缺口，不新增题目，不删除题目，不改变题目 ID。',
+        `必须让修订后的 questions 覆盖这些 missingPointIds：${revisionCoverage.missingPointIds.join('、')}。`,
+        '优先选择最相关的已有题目进行小幅改写或补充 knowledgePointIds；不能硬塞不相关知识点。',
+        '如果题面需要随知识点绑定变化而调整，必须同步改题干，保证学生可作答且答案唯一。',
+        '继续遵守视觉信息判断：题目需要图才能唯一作答时必须提供 SVG，否则应改成纯文字可答题。',
+        '不要输出 answer、solutionSteps 或 rubric；这些字段会在题目定稿后补全。'
+      ],
+      schema: questionRevisionSchema()
+    }), 'coverage_repair');
+    revision = {
+      ...revision,
+      title: normalizePracticeTitle(repair.title || revision.title),
+      personalizationBasis: repair.personalizationBasis || revision.personalizationBasis || [],
+      revisionSummary: [revision.revisionSummary, repair.revisionSummary]
+        .filter(Boolean)
+        .join('\n'),
+      questions: mergeRevisionQuestions(revision.questions, repair.questions)
+    };
+    revisionCoverage = coverageSummaryForQuestions(targetKnowledgePoints, revision.questions);
+    onProgress({
+      step: 'practice_generate.coverage_repair_done',
+      message: `覆盖修复完成：已覆盖 ${revisionCoverage.coveredCount}/${revisionCoverage.intendedCount} 个目标点。`
+    });
+  }
+  const shouldRunSvgVerification = verifySvgFigures || requireSvg || minSvgQuestions > 0;
+  if (shouldRunSvgVerification) {
+    const svgSelection = requireSvg
+      ? {
+          questionIds: revision.questions.map((question) => question.id),
+          strictQuestionIds: revision.questions.map((question) => question.id)
+        }
+      : await selectQuestionsForSvgReview({
+          stageCacheDir,
+          onProgress,
+          baseContext,
+          revision,
+          minSvgQuestions
+        });
+    onProgress({
+      step: 'practice_generate.svg_verify',
+      message: requireSvg
+        ? '正在逐题渲染并审查 SVG 配图；本次要求每题都必须有图。'
+        : `正在渲染并审查 SVG 配图：${svgSelection.questionIds.join('、') || '已有配图'}。`
+    });
+    revision = {
+      ...revision,
+      questions: await verifyAndRepairSvgFigures({
+        questions: revision.questions,
+        context: {
+          chapter,
+          targetKnowledgePoints
+        },
+        workDir: path.join(stageCacheDir || chapterDataPaths(chapter.id).context, 'svg-renders'),
+        requireSvg,
+        requiredQuestionIds: svgSelection.questionIds,
+        strictQuestionIds: svgSelection.strictQuestionIds,
+        maxRounds: 3,
+        onProgress
+      })
+    };
+    revisionCoverage = coverageSummaryForQuestions(targetKnowledgePoints, revision.questions);
+    onProgress({
+      step: 'practice_generate.svg_verify_done',
+      message: 'SVG 渲染审查完成，继续复审题目质量。'
+    });
+  }
+  let finalReview = null;
+  const reviewBlockers = (review.data.findings || []).filter((finding) => finding.level === 'blocker');
+  const canSkipFinalReview = fastReview
+    && reviewBlockers.length === 0
+    && revisionCoverage.outsidePointIds.length === 0
+    && (isAbilityAssessment || revisionCoverage.missingPointIds.length === 0);
+  if (canSkipFinalReview) {
+    finalReview = {
+      ok: true,
+      data: {
+        passed: true,
+        summary: 'fast_review 模式：初评无 blocker，且本地覆盖检查通过，跳过 LLM 定稿复审。',
+        findings: [],
+        coverage: revisionCoverage,
+        source: 'fast_review_skip'
+      },
+      attempts: 0
+    };
+    onProgress({ step: 'practice_generate.final_review_skip', message: '快速回归模式下跳过定稿 LLM 复审。' });
+  } else {
+    onProgress({ step: 'practice_generate.final_review', message: '正在复审题目质量和重复风险。' });
+    finalReview = await runFinalReview({
+      stageCacheDir,
+      cacheFile: 'final-review.json',
+      onProgress,
+      baseContext,
+      revision,
+      revisionCoverage,
+      initialReview: review.data,
+      isAbilityAssessment
+    });
+  }
   if (!finalReview.ok || !Array.isArray(finalReview.data?.findings)) {
     const attempts = finalReview.attempts ? ` attempts=${finalReview.attempts}` : '';
     throw generationError(`final_review_${finalReview.reason || 'invalid_agent_response'}`, `${finalReview.detail || ''}${attempts}`);
@@ -857,18 +1306,92 @@ export async function generatePracticeContent(input) {
   if (!isAbilityAssessment && revisionCoverage.missingPointIds.length) {
     throw generationError('coverage_missing_targets', revisionCoverage.missingPointIds.join(','));
   }
-  const finalBlockers = (finalReview.data.findings || [])
-    .filter((finding) => finding.level === 'blocker')
-    .filter((finding) => finding.type !== 'bad_coverage');
-  if (finalBlockers.length) {
-    throw generationError(
-      'final_review_blockers',
-      finalBlockers.map((finding) => `${finding.questionId || 'global'}:${finding.type}`).join('|')
-    );
+  const maxFinalBlockerRepairRounds = 3;
+  for (let repairRound = 1; ; repairRound += 1) {
+    const finalBlockers = (finalReview.data.findings || [])
+      .filter((finding) => finding.level === 'blocker')
+      .filter((finding) => finding.type !== 'bad_coverage');
+    if (!finalBlockers.length) break;
+    if (repairRound > maxFinalBlockerRepairRounds) {
+      onProgress({
+        step: 'practice_generate.final_review_failed',
+        message: blockerMessage(finalBlockers, '自动修订后仍有终审 blocker')
+      });
+      throw generationError('final_review_blockers', blockerDetail(finalBlockers));
+    }
+    onProgress({
+      step: 'practice_generate.final_review_blockers',
+      message: blockerMessage(finalBlockers, `最终复审发现 blocker，正在自动修订（第 ${repairRound}/${maxFinalBlockerRepairRounds} 轮）`)
+    });
+    revision = await repairFinalBlockers({
+      stageCacheDir,
+      onProgress,
+      baseContext,
+      revision,
+      finalBlockers,
+      isAbilityAssessment,
+      repairRound
+    });
+    revisionCoverage = coverageSummaryForQuestions(targetKnowledgePoints, revision.questions);
+    if (revisionCoverage.outsidePointIds.length) {
+      throw generationError('coverage_outside_target_after_final_repair', revisionCoverage.outsidePointIds.join(','));
+    }
+    if (!isAbilityAssessment && revisionCoverage.missingPointIds.length) {
+      throw generationError('coverage_missing_targets_after_final_repair', revisionCoverage.missingPointIds.join(','));
+    }
+    if (shouldRunSvgVerification) {
+      const svgSelection = requireSvg
+        ? {
+            questionIds: revision.questions.map((question) => question.id),
+            strictQuestionIds: revision.questions.map((question) => question.id)
+          }
+        : await selectQuestionsForSvgReview({
+            stageCacheDir,
+            onProgress,
+            baseContext,
+            revision,
+            minSvgQuestions
+          });
+      revision = {
+        ...revision,
+        questions: await verifyAndRepairSvgFigures({
+          questions: revision.questions,
+          context: {
+            chapter,
+            targetKnowledgePoints
+          },
+          workDir: path.join(stageCacheDir || chapterDataPaths(chapter.id).context, 'svg-renders'),
+          requireSvg,
+          requiredQuestionIds: svgSelection.questionIds,
+          strictQuestionIds: svgSelection.strictQuestionIds,
+          maxRounds: 3,
+          onProgress
+        })
+      };
+      revisionCoverage = coverageSummaryForQuestions(targetKnowledgePoints, revision.questions);
+    }
+    onProgress({
+      step: 'practice_generate.final_review_retry',
+      message: `终审 blocker 第 ${repairRound} 轮修订完成，正在重新复审。`
+    });
+    finalReview = await runFinalReview({
+      stageCacheDir,
+      cacheFile: `final-review-after-blocker-repair-${String(repairRound).padStart(2, '0')}.json`,
+      onProgress,
+      baseContext,
+      revision,
+      revisionCoverage,
+      initialReview: review.data,
+      isAbilityAssessment
+    });
+    if (!finalReview.ok || !Array.isArray(finalReview.data?.findings)) {
+      const attempts = finalReview.attempts ? ` attempts=${finalReview.attempts}` : '';
+      throw generationError(`final_review_retry_${finalReview.reason || 'invalid_agent_response'}`, `${finalReview.detail || ''}${attempts}`);
+    }
   }
   onProgress({ step: 'practice_generate.final_review_done', message: `最终复审通过：${finalReview.data.findings.length} 条提示。` });
   const answerChunks = [];
-  const answerQuestionChunks = chunkArray(revision.questions, 3);
+  const answerQuestionChunks = chunkArray(revision.questions, 4);
   for (let index = 0; index < answerQuestionChunks.length; index += 1) {
     const questions = answerQuestionChunks[index];
     const questionIds = questions.map((question) => question.id);
@@ -876,7 +1399,10 @@ export async function generatePracticeContent(input) {
       step: 'practice_generate.answers',
       message: `正在生成标准答案和讲解：第 ${index + 1}/${answerQuestionChunks.length} 批（${questionIds.join('、')}）。`
     });
-    const answerChunk = assertAgentQuestions(await callPracticeAgent({
+    const answerChunk = assertAgentQuestions(await callPracticeAgentCached({
+      cacheDir: stageCacheDir,
+      cacheFile: `answer-chunk-${String(index + 1).padStart(2, '0')}.json`,
+      onProgress,
       promptName: 'practice-generate.system.md',
       task: `为定稿题目补全答案元数据（第 ${index + 1}/${answerQuestionChunks.length} 批）`,
       context: contextForAnswerMetadata(baseContext, questions),
@@ -884,7 +1410,8 @@ export async function generatePracticeContent(input) {
         '只输出输入 questions 中已有题目的 id、answer、solutionSteps、rubric。',
         '不得修改题目 ID、题干、题型、难度、knowledgePointIds、knowledgePoints、expectedErrorTypes、abilityIds、skillAtoms、expectedAbilityErrors、score、answerSpaceLines、svg 或 imagePrompt。',
         'answer 必须是可核对的标准答案；选择题写正确选项和结论，填空/问答题写完整答案。',
-        'solutionSteps 必须是 2-5 步中文解题过程，能够解释孩子错在哪里。',
+        'solutionSteps 面向讲解卷阅读，不要机械写 2-5 步。简单选择题/填空题只写 1 条简短说明，说明本题考察什么和关键辨析点；需要推导、几何观察或多步判断的题，再写 2-4 条解题要点。',
+        'solutionSteps 不要重复标准答案，不要写成批改标准；语言要像给孩子看的讲解。',
         'rubric 必须可用于批改，至少包含关键结论和关键过程；各项 score 之和应接近题目 score。',
         '公式继续使用 LaTeX 分隔符，并保留完整反斜杠。'
       ],