@zhouchangui/math-ati 0.1.0

package/server/practiceGenerator.js

@@ -0,0 +1,908 @@
+import { callChatAgent } from './agentClient.js';
+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';
+
+function generationError(reason, detail = '') {
+  const error = new Error(`practice_generation_failed:${reason}`);
+  error.status = 502;
+  error.reason = reason;
+  error.detail = detail;
+  return error;
+}
+
+function assertAgentQuestions(agent, phase) {
+  if (!agent.ok || !Array.isArray(agent.data?.questions)) {
+    const attempts = agent.attempts ? ` attempts=${agent.attempts}` : '';
+    throw generationError(`${phase}_${agent.reason || 'invalid_agent_response'}`, `${agent.detail || ''}${attempts}`);
+  }
+  return agent.data;
+}
+
+function difficultyScore(question) {
+  if (question.difficulty === 'challenge') return 8;
+  if (question.difficulty === 'medium') return 6;
+  return 4;
+}
+
+function normalizePracticeTitle(title) {
+  return String(title || '')
+    .replace(/最终版/g, '')
+    .replace(/[（(][^）)]*(?:修订版|第\s*\d+(?:\s*\/\s*\d+)?\s*批)[^）)]*[）)]/g, '')
+    .replace(/[（(]\s*[·｜|:：-]*\s*[）)]/g, '')
+    .replace(/修订版/g, '')
+    .replace(/[（(]\s*第\s*\d+\s*\/\s*\d+\s*批\s*[）)]/g, '')
+    .replace(/[（(]\s*第\s*\d+\s*批\s*[）)]/g, '')
+    .replace(/第\s*\d+\s*\/\s*\d+\s*批/g, '')
+    .replace(/第\s*\d+\s*批/g, '')
+    .replace(/[｜|]\s*$/g, '')
+    .replace(/[:：]\s*$/g, '')
+    .replace(/·\s*$/g, '')
+    .replace(/\s+（/g, '（')
+    .replace(/·\s+/g, '·')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+function plainMetadataLabel(value) {
+  return String(value ?? '')
+    .replace(/\$\$([^$]+)\$\$/g, '$1')
+    .replace(/\$([^$]+)\$/g, '$1')
+    .replace(/\\\((.*?)\\\)/g, '$1')
+    .replace(/\\\[(.*?)\\\]/g, '$1')
+    .replace(/\\left|\\right/g, '')
+    .replace(/\\frac\{([^{}]+)\}\{([^{}]+)\}/g, '$1/$2')
+    .replace(/<[^>]+>/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function plainMetadataLabels(items) {
+  if (!Array.isArray(items)) return [];
+  return items.map((item) => plainMetadataLabel(item)).filter(Boolean);
+}
+
+function answerSpaceLines(question) {
+  const byKind = {
+    choice: 2,
+    blank: 3,
+    short_answer: 6
+  };
+  return Math.max(byKind[question.questionKind] || 5, Number(question.answerSpaceLines || 0));
+}
+
+function withProcessDefaults(content) {
+  const normalizeDifficulty = (difficulty, fallbackDifficulty) => {
+    if (['basic', 'medium', 'challenge'].includes(difficulty)) return difficulty;
+    if (['基础', '基础题', 'easy'].includes(difficulty)) return 'basic';
+    if (['中档', '中等', 'middle'].includes(difficulty)) return 'medium';
+    if (['挑战', '较难', 'hard'].includes(difficulty)) return 'challenge';
+    return fallbackDifficulty || 'basic';
+  };
+  return {
+    ...content,
+    title: normalizePracticeTitle(content.title),
+    questions: content.questions.map((question, index) => {
+      return {
+        ...question,
+        id: question.id || `q${index + 1}`,
+        questionKind: ['choice', 'blank', 'short_answer'].includes(question.questionKind)
+          ? question.questionKind
+          : 'short_answer',
+        knowledgePointIds: Array.isArray(question.knowledgePointIds) ? question.knowledgePointIds : [],
+        knowledgePoints: plainMetadataLabels(question.knowledgePoints),
+        expectedErrorTypes: plainMetadataLabels(question.expectedErrorTypes),
+        abilityIds: Array.isArray(question.abilityIds) ? question.abilityIds : [],
+        skillAtoms: plainMetadataLabels(question.skillAtoms),
+        expectedAbilityErrors: plainMetadataLabels(question.expectedAbilityErrors),
+        answer: String(question.answer || '').trim(),
+        solutionSteps: Array.isArray(question.solutionSteps)
+          ? question.solutionSteps.map((step) => String(step || '').trim()).filter(Boolean)
+          : String(question.solution || '')
+            .split(/\n+/)
+            .map((step) => step.trim())
+            .filter(Boolean),
+        rubric: Array.isArray(question.rubric)
+          ? question.rubric
+          : [],
+        difficulty: normalizeDifficulty(question.difficulty, 'basic'),
+        score: Number(question.score || difficultyScore(question)),
+        answerSpaceLines: answerSpaceLines(question)
+      };
+    })
+  };
+}
+
+function chunkArray(items, size) {
+  const chunks = [];
+  for (let index = 0; index < items.length; index += size) {
+    chunks.push(items.slice(index, index + size));
+  }
+  return chunks;
+}
+
+function contextForQuestions(baseContext, questions) {
+  const usedIds = new Set();
+  for (const question of questions || []) {
+    for (const pointId of question.knowledgePointIds || []) usedIds.add(pointId);
+  }
+  const targetKnowledgePoints = baseContext.targetKnowledgePoints
+    .filter((point) => usedIds.size === 0 || usedIds.has(point.id));
+  return {
+    student: baseContext.student,
+    chapter: baseContext.chapter,
+    options: {
+      type: baseContext.options.type,
+      questionCount: baseContext.options.questionCount,
+      maxQuestionCount: baseContext.options.maxQuestionCount,
+      adaptiveQuestionCount: baseContext.options.adaptiveQuestionCount,
+      difficulty: baseContext.options.difficulty,
+      questionKind: baseContext.options.questionKind,
+      knowledgePointIds: [...usedIds],
+      abilityIds: baseContext.options.abilityIds || []
+    },
+    abilitySpecs: baseContext.abilitySpecs || [],
+    targetKnowledgePoints,
+    history: {
+      previousStems: baseContext.history.previousStems,
+      recentMistakes: baseContext.history.recentMistakes
+    }
+  };
+}
+
+function compactPreviousStem(stem) {
+  return String(stem || '')
+    .replace(/\s+/g, ' ')
+    .slice(0, 220);
+}
+
+function contextForAnswerMetadata(baseContext, questions) {
+  const usedIds = new Set();
+  for (const question of questions || []) {
+    for (const pointId of question.knowledgePointIds || []) usedIds.add(pointId);
+  }
+  return {
+    chapter: baseContext.chapter,
+    options: {
+      type: baseContext.options.type,
+      questionCount: baseContext.options.questionCount,
+      difficulty: baseContext.options.difficulty,
+      questionKind: baseContext.options.questionKind,
+      knowledgePointIds: [...usedIds],
+      abilityIds: baseContext.options.abilityIds || []
+    },
+    abilitySpecs: baseContext.abilitySpecs || [],
+    targetKnowledgePoints: baseContext.targetKnowledgePoints
+      .filter((point) => usedIds.size === 0 || usedIds.has(point.id)),
+    questions
+  };
+}
+
+function contextForQuestionTargets(baseContext, targetKnowledgePoints, previousStems) {
+  return {
+    student: {
+      name: baseContext.student?.name,
+      stage: baseContext.student?.stage,
+      primaryGoal: baseContext.student?.primaryGoal
+    },
+    chapter: baseContext.chapter,
+    options: {
+      type: baseContext.options.type,
+      difficulty: baseContext.options.difficulty,
+      questionKind: baseContext.options.questionKind,
+      knowledgePointIds: targetKnowledgePoints.map((point) => point.id),
+      abilityIds: baseContext.options.abilityIds || []
+    },
+    abilitySpecs: baseContext.abilitySpecs || [],
+    knowledgeDoc: {
+      chapterId: baseContext.knowledgeDoc.chapterId,
+      targetOnly: true,
+      totalKnowledgePointCount: baseContext.knowledgeDoc.totalKnowledgePointCount,
+      selectedKnowledgePointCount: targetKnowledgePoints.length,
+      firstRoundCoveredCount: baseContext.knowledgeDoc.firstRoundCoveredCount,
+      firstRoundRemainingCount: baseContext.knowledgeDoc.firstRoundRemainingCount,
+      selectionPolicy: baseContext.knowledgeDoc.selectionPolicy
+    },
+    targetKnowledgePoints,
+    history: {
+      previousStems,
+      recentMistakes: baseContext.history.recentMistakes
+    }
+  };
+}
+
+function compactRequestChars({ systemPrompt = '', task, context, requirements, schema }) {
+  return systemPrompt.length + promptPayload({ task, context, requirements, schema }).length;
+}
+
+function questionDraftSchema(questionCount) {
+  return {
+    title: 'string',
+    personalizationBasis: ['string'],
+    coveragePlan: {
+      recommendedQuestionCount: questionCount,
+      rationale: 'string',
+      priorityPointIds: ['chapter-01-kp-01'],
+      sampledMasteredPointIds: ['chapter-01-kp-02']
+    },
+    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 distributeQuestionCounts(chunks, totalQuestionCount) {
+  const total = Math.max(1, Number(totalQuestionCount || chunks.length));
+  if (chunks.length <= 1) return [total];
+  const totalTargets = chunks.reduce((sum, chunk) => sum + chunk.length, 0) || chunks.length;
+  let remainingQuestions = total;
+  let remainingTargets = totalTargets;
+  return chunks.map((chunk, index) => {
+    const remainingChunks = chunks.length - index;
+    if (index === chunks.length - 1) return Math.max(1, remainingQuestions);
+    const proportional = Math.round((remainingQuestions * chunk.length) / Math.max(1, remainingTargets));
+    const count = Math.max(1, Math.min(proportional, remainingQuestions - (remainingChunks - 1)));
+    remainingQuestions -= count;
+    remainingTargets -= chunk.length;
+    return count;
+  });
+}
+
+function coverageSummaryForQuestions(targetKnowledgePoints, questions) {
+  const intendedPointIds = targetKnowledgePoints.map((point) => point.id);
+  const intendedPointIdSet = new Set(intendedPointIds);
+  const coveredPointIds = [
+    ...new Set((questions || [])
+      .flatMap((question) => question.knowledgePointIds || [])
+      .filter((pointId) => intendedPointIdSet.has(pointId)))
+  ];
+  const coveredPointIdSet = new Set(coveredPointIds);
+  const missingPointIds = intendedPointIds.filter((pointId) => !coveredPointIdSet.has(pointId));
+  const outsidePointIds = [
+    ...new Set((questions || [])
+      .flatMap((question) => question.knowledgePointIds || [])
+      .filter((pointId) => !intendedPointIdSet.has(pointId)))
+  ];
+  return {
+    intendedPointIds,
+    coveredPointIds,
+    missingPointIds,
+    outsidePointIds,
+    intendedCount: intendedPointIds.length,
+    coveredCount: coveredPointIds.length
+  };
+}
+
+function answerMetadataSchema() {
+  return {
+    questions: [{
+      id: 'q1',
+      answer: 'string',
+      solutionSteps: ['string'],
+      rubric: [{
+        point: 'string',
+        score: 2
+      }]
+    }]
+  };
+}
+
+function mergeAnswerMetadata(questions, answerChunks) {
+  const answersById = new Map();
+  for (const chunk of answerChunks) {
+    for (const answer of chunk.questions || []) {
+      answersById.set(answer.id, answer);
+    }
+  }
+  const merged = questions.map((question) => {
+    const answer = answersById.get(question.id);
+    if (!answer) {
+      throw generationError('answer_generation_missing', question.id);
+    }
+    const solutionSteps = Array.isArray(answer.solutionSteps)
+      ? answer.solutionSteps.map((step) => String(step || '').trim()).filter(Boolean)
+      : [];
+    const rubric = Array.isArray(answer.rubric) ? answer.rubric : [];
+    if (!String(answer.answer || '').trim() || solutionSteps.length === 0 || rubric.length === 0) {
+      throw generationError('answer_generation_incomplete', question.id);
+    }
+    return {
+      ...question,
+      answer: String(answer.answer || '').trim(),
+      solutionSteps,
+      rubric
+    };
+  });
+  return merged;
+}
+
+function progressReporter(onProgress) {
+  return typeof onProgress === 'function' ? onProgress : () => {};
+}
+
+function compactKnowledgePoint(point, mastery = null) {
+  return {
+    id: point.id,
+    title: point.title,
+    sectionTitle: point.sectionTitle,
+    summary: point.summary,
+    pitfalls: Array.isArray(point.pitfalls) ? point.pitfalls.slice(0, 3) : [],
+    masteryStatus: mastery?.status || 'not_started',
+    masteryStats: mastery
+      ? {
+          coveredCount: Number(mastery.coveredCount || 0),
+          correctCount: Number(mastery.correctCount || 0),
+          wrongCount: Number(mastery.wrongCount || 0),
+          errorTypes: Array.isArray(mastery.errorTypes) ? mastery.errorTypes.slice(0, 4) : []
+        }
+      : null
+  };
+}
+
+function priorityScore(point, recentMistakes = []) {
+  const mastery = point.masteryStats || {};
+  const status = point.masteryStatus || 'not_started';
+  const mistakeHit = recentMistakes.some((mistake) => {
+    const text = `${mistake.knowledgePoint || ''} ${mistake.summary || ''}`;
+    return text.includes(point.id) || text.includes(point.title);
+  });
+  let score = 0;
+  if (status === 'needs_review') score += 6;
+  if (status === 'not_started') score += 3;
+  if (status === 'mastered') score -= 5;
+  score += Number(mastery.wrongCount || 0) * 3;
+  score += Number(mastery.coveredCount || 0) > 0 && Number(mastery.correctCount || 0) === 0 ? 2 : 0;
+  score += mistakeHit ? 8 : 0;
+  return score;
+}
+
+function selectGenerationTargets(points, { scopedIds, maxQuestionCount, recentMistakes, previousKnowledgePointIds = [] }) {
+  if (scopedIds) return points;
+  const previousIds = new Set(previousKnowledgePointIds);
+  const requestedCount = Number(maxQuestionCount || 12);
+  const limit = Math.max(8, Math.min(24, requestedCount));
+  const ordered = [...points]
+    .map((point, order) => ({
+      point,
+      order,
+      coveredInFirstRound: previousIds.has(point.id),
+      score: priorityScore(point, recentMistakes)
+    }))
+    .sort((a, b) => (
+      Number(a.coveredInFirstRound) - Number(b.coveredInFirstRound) ||
+      b.score - a.score ||
+      a.order - b.order
+    ));
+  return ordered.slice(0, Math.min(limit, ordered.length)).map((item) => item.point);
+}
+
+function recommendedQuestionCount(targetCount, maxQuestionCount) {
+  const maxCount = Math.max(1, Number(maxQuestionCount || 12));
+  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 }) {
+  const systemPrompt = await readPrompt(promptName);
+  return callChatAgent({
+    timeoutMs,
+    retries,
+    temperature,
+    system: systemPrompt,
+    user: promptPayload({
+      task,
+      context,
+      requirements,
+      schema
+    })
+  });
+}
+
+async function generationHistory(chapterId) {
+  const chapterPaths = chapterDataPaths(chapterId);
+  const mistakeSummary = await readJson(chapterPaths.mistakeSummary, null);
+  const mastery = await readJson(chapterPaths.mastery, null);
+  const mistakes = (await readChapterMistakes(chapterId)).filter(isActionableMistake).slice(-12);
+  let previousStems = [];
+  let previousKnowledgePointIds = [];
+  try {
+    const fs = await import('node:fs/promises');
+    const files = (await fs.readdir(chapterPaths.practices))
+      .filter((file) => file.endsWith('.json'))
+      .map((file) => path.join(chapterPaths.practices, file))
+      .sort()
+      .reverse();
+    for (const file of files.slice(0, 100)) {
+      const practice = await readJson(file);
+      if (practice.chapterId === chapterId) {
+        if (previousStems.length < 30) {
+          previousStems.push(...practice.questions.map((question) => compactPreviousStem(question.stem)));
+        }
+        if (practice.type === 'knowledge_coverage') {
+          previousKnowledgePointIds.push(...practice.questions.flatMap((question) => question.knowledgePointIds || []));
+        }
+      }
+    }
+  } catch {
+    previousStems = [];
+    previousKnowledgePointIds = [];
+  }
+  return {
+    mistakeSummary,
+    mastery: mastery
+      ? {
+          coverage: mastery.coverage || null,
+          points: Object.values(mastery.points || {})
+            .filter((point) => point.status !== 'mastered' || point.wrongCount || point.errorTypes?.length)
+            .sort((a, b) => Number(b.wrongCount || 0) - Number(a.wrongCount || 0))
+            .slice(0, 24)
+            .map((point) => ({
+              id: point.id,
+              title: point.title,
+              status: point.status || 'not_started',
+              coveredCount: Number(point.coveredCount || 0),
+              correctCount: Number(point.correctCount || 0),
+              wrongCount: Number(point.wrongCount || 0),
+              errorTypes: Array.isArray(point.errorTypes) ? point.errorTypes.slice(0, 5) : []
+            }))
+        }
+      : null,
+    recentMistakes: mistakes.map((item) => ({
+      knowledgePoint: item.knowledgePoint,
+      errorType: item.errorType,
+      summary: item.summary
+    })),
+    previousKnowledgePointIds: [...new Set(previousKnowledgePointIds)].filter(Boolean),
+    previousStems: previousStems.slice(0, 30)
+  };
+}
+
+export async function generatePracticeContent(input) {
+  const { profile, chapter, options } = input;
+  const onProgress = progressReporter(input.onProgress);
+  onProgress({ step: 'practice_generate.history', message: '正在整理历史题目和近期错因。' });
+  const history = await generationHistory(chapter.id);
+  const knowledgeDoc = options.knowledgeDoc;
+  if (!knowledgeDoc?.sections?.length) {
+    throw generationError('missing_knowledge_doc');
+  }
+  const allTargetKnowledgePoints = flattenKnowledgePoints(knowledgeDoc);
+  const scopedIds = Array.isArray(options.knowledgePointIds) && options.knowledgePointIds.length
+    ? new Set(options.knowledgePointIds)
+    : options.knowledgePointId
+      ? new Set([options.knowledgePointId])
+      : null;
+  const scopedTargetKnowledgePoints = scopedIds
+    ? allTargetKnowledgePoints.filter((point) => scopedIds.has(point.id))
+    : allTargetKnowledgePoints;
+  const masteryByPointId = new Map((history.mastery?.points || []).map((point) => [point.id, point]));
+  const compactTargetKnowledgePoints = scopedTargetKnowledgePoints.map((point) => ({
+    ...compactKnowledgePoint(point, masteryByPointId.get(point.id) || null)
+  }));
+  const scopedTargetIds = new Set(compactTargetKnowledgePoints.map((point) => point.id));
+  const firstRoundCoveredIds = (history.previousKnowledgePointIds || [])
+    .filter((pointId) => scopedTargetIds.has(pointId));
+  const targetKnowledgePoints = selectGenerationTargets(compactTargetKnowledgePoints, {
+    scopedIds,
+    maxQuestionCount: options.maxQuestionCount || options.questionCount,
+    recentMistakes: history.recentMistakes || [],
+    previousKnowledgePointIds: firstRoundCoveredIds
+  });
+  const priorityKnowledgePointIds = [
+    ...(history.mastery?.points || [])
+      .slice(0, 12)
+      .map((point) => point.id),
+    ...(history.recentMistakes || [])
+      .map((item) => item.knowledgePoint)
+      .filter((value) => typeof value === 'string')
+  ].filter(Boolean);
+  const localRecommendedQuestionCount = recommendedQuestionCount(
+    targetKnowledgePoints.length,
+    options.maxQuestionCount || options.questionCount
+  );
+  const agentOptions = {
+    type: options.type,
+    questionCount: options.questionCount,
+    maxQuestionCount: options.maxQuestionCount,
+    adaptiveQuestionCount: options.adaptiveQuestionCount,
+    difficulty: options.difficulty,
+    includeMistakes: options.includeMistakes,
+    knowledgePointId: options.knowledgePointId,
+    knowledgePointIds: options.knowledgePointIds,
+    abilityIds: options.abilityIds || [],
+    questionKind: options.questionKind
+  };
+  const abilitySpecs = (options.abilityIds || [])
+    .map((abilityId) => ABILITY_CATALOG.find((ability) => ability.id === abilityId))
+    .filter(Boolean)
+    .map((ability) => ({
+      id: ability.id,
+      title: ability.title,
+      description: ability.description,
+      category: ability.category,
+      passThreshold: ability.passThreshold,
+      requiredConsecutivePasses: ability.requiredConsecutivePasses,
+      firstVersionScope: ability.firstVersionScope
+    }));
+  const baseContext = {
+    student: profile,
+    chapter,
+    options: agentOptions,
+    knowledgeDoc: {
+      chapterId: knowledgeDoc.chapterId,
+      targetOnly: true,
+      totalKnowledgePointCount: compactTargetKnowledgePoints.length,
+      selectedKnowledgePointCount: targetKnowledgePoints.length,
+      firstRoundCoveredCount: firstRoundCoveredIds.length,
+      firstRoundRemainingCount: Math.max(0, compactTargetKnowledgePoints.length - firstRoundCoveredIds.length),
+      localRecommendedQuestionCount,
+      selectionPolicy: scopedIds
+        ? 'specified knowledge point scope'
+        : 'uncovered first-round knowledge points first, then mastery status, wrong count, and recent mistakes'
+    },
+    targetKnowledgePoints,
+    abilitySpecs,
+    history
+  };
+  const isAbilityAssessment = options.type === 'ability_assessment';
+  const baseRequirements = [
+    '全部内容只能由 LLM 生成，不能使用本地模板或规则兜底。',
+    '题目之间不能重复，也不要和 previousStems 高度相似。',
+    options.questionCount
+      ? `本次用户已选择练习时长，整份试卷目标题量为 ${options.questionCount} 题；如果任务要求“本批”，则只按本批指定题量生成。`
+      : `先根据 targetKnowledgePoints、history.mastery 和 recentMistakes 规划完整覆盖所需的最少题量；本次最多 ${options.maxQuestionCount || 18} 题，不要机械等于上限。`,
+    options.questionCount
+      ? `本地预估建议题量为 ${localRecommendedQuestionCount} 题，但用户时长选择优先，题量以 ${options.questionCount} 题为准。`
+      : `本地预估建议题量为 ${localRecommendedQuestionCount} 题；只有确实需要时才接近上限。`,
+    scopedIds
+      ? '本次是指定知识点范围覆盖，只能围绕 targetKnowledgePoints 出题，不要覆盖范围外知识点；必须用少题高覆盖策略，一道题可以覆盖多个紧密相关知识点。'
+      : isAbilityAssessment
+        ? '本次是能力评估卷：目标来自 abilitySpecs 与本章知识范围，题目应围绕能力表现取样，不要机械追求知识点全覆盖。'
+        : '本次是章节知识点覆盖卷，不要要求用户提供知识点编号；首轮覆盖尚未完成时，knowledge_coverage 必须优先从 previousKnowledgePointIds 没有覆盖过的 targetKnowledgePoints 出题；已覆盖点只做必要合并抽样。首轮完成后，再按 needs_review、wrongCount 高和 recentMistakes 命中的点优先。',
+    isAbilityAssessment
+      ? '能力评估第一版只评估计算准确性，不纳入用时、速度、限时达标；题目以短题、多题、低语境为主，尽量暴露计算准确性和常见计算错误。'
+      : '',
+    isAbilityAssessment
+      ? '每道能力评估题必须填写 abilityIds、skillAtoms、expectedAbilityErrors；abilityIds 只能来自 context.options.abilityIds，首批通常是 calculation_accuracy。'
+      : '',
+    isAbilityAssessment
+      ? 'skillAtoms 和 expectedAbilityErrors 是讲解版胶囊标签，只能写纯中文短标签；禁止使用 $...$、\\(...\\)、\\[...\\]、HTML 或复杂公式包装。'
+      : '',
+    'questionKind 为 auto 时，由你根据知识点覆盖需要自主组合 choice、blank、short_answer；choice 必须给出 4 个选项；blank 适合概念/公式/结果检测；short_answer 适合方法、辨析和计算步骤检测。',
+    '每题填写 questionKind 字段，值只能是 choice、blank 或 short_answer。',
+    '每题必须填写 knowledgePointIds，且 id 必须来自 targetKnowledgePoints；一题可填写多个知识点 ID。',
+    'knowledgePoints 和 expectedErrorTypes 是讲解版胶囊标签，只能写纯中文短标签；禁止使用 $...$、\\(...\\)、\\[...\\]、HTML 或复杂公式包装。例如写“特殊值 0 误判”，不要写“特殊值 $0$ 误判”。',
+    '题干只放题目，不放解题过程。',
+    '可以在题干中使用 Markdown 表格表达分类、对照或数据，但不要使用 HTML table 标签。',
+    '题目使用纯文本加 LaTeX 分隔符；只有几何、数轴或图形题必要时才使用内联 SVG 或 imagePrompt。',
+    'LaTeX 命令必须保留完整反斜杠，例如 \\triangle、\\angle、\\perp、\\parallel、\\text{}；禁止输出 triangle/riangle/angle/perp/parallel/ext{} 或把 \\t 变成制表符。',
+    '几何、数轴或 SVG 图形题必须保证题干、图中标签、角弧、垂直/平行/长度标注完全一致；如果题干问 angle 2、切点、垂足或某条边，图中对应位置必须准确。',
+    'SVG 标签必须可读且不遮挡线段、角弧、表格或答题区；优先使用简单清晰的线图。',
+    '题面不给学生显示分值，不要在题干里写“本题多少分”。',
+    '第一阶段只生成题面、题型、知识点绑定、预期错因、分值和留白行数；answer、solutionSteps、rubric 会在题目定稿后由第二阶段分批补全。'
+  ].filter(Boolean);
+  onProgress({
+    step: 'practice_generate.plan',
+    message: `正在分析首轮覆盖策略：已覆盖 ${firstRoundCoveredIds.length}/${compactTargetKnowledgePoints.length} 个知识点，本次候选 ${targetKnowledgePoints.length} 个。`
+  });
+  const questionGenerationRequirements = [
+    ...baseRequirements,
+    !scopedIds && compactTargetKnowledgePoints.length > targetKnowledgePoints.length
+      ? `为了保证生成稳定，本次只给出 ${targetKnowledgePoints.length} 个优先候选知识点；全章共有 ${compactTargetKnowledgePoints.length} 个知识点。后续掌握状态改善后，候选集应继续变小。`
+      : '本次候选知识点已经是完整目标范围。',
+    priorityKnowledgePointIds.length
+      ? `本次优先覆盖这些知识点：${priorityKnowledgePointIds.slice(0, 16).join('、')}。`
+      : '本次按掌握状态和错因历史自动排序优先级。',
+    firstRoundCoveredIds.length
+      ? `这些知识点已经在知识点覆盖试卷中出过题，除非为组合题必要条件，否则本轮不要优先覆盖：${firstRoundCoveredIds.slice(0, 30).join('、')}。`
+      : '还没有历史知识点覆盖记录，本轮从章节核心知识点开始首轮覆盖。',
+    '不要输出 answer、solutionSteps 或 rubric；本阶段只定稿题目本身和知识点绑定。'
+  ];
+  const totalQuestionCount = options.questionCount || localRecommendedQuestionCount;
+  const questionTargetChunks = chunkArray(targetKnowledgePoints, 3);
+  const questionBatchCounts = distributeQuestionCounts(questionTargetChunks, totalQuestionCount);
+  const questionChunks = [];
+  const promptName = 'practice-generate.system.md';
+  const questionSystemPrompt = await readPrompt(promptName);
+  let generatedQuestionCount = 0;
+  let previousBatchStems = [...(baseContext.history.previousStems || [])];
+  for (let index = 0; index < questionTargetChunks.length; index += 1) {
+    const batchTargets = questionTargetChunks[index];
+    const batchQuestionCount = questionBatchCounts[index];
+    const batchContext = contextForQuestionTargets(baseContext, batchTargets, previousBatchStems.slice(-36));
+    const batchRequirements = [
+      ...questionGenerationRequirements,
+      `本批只围绕 batch targetKnowledgePoints 出题，必须正好生成 ${batchQuestionCount} 题。`,
+      `本批目标知识点：${batchTargets.map((point) => point.id).join('、')}。`,
+      '除非题目确实需要组合，不要使用本批 targetKnowledgePoints 之外的 knowledgePointIds。',
+      generatedQuestionCount
+        ? `前面批次已生成 ${generatedQuestionCount} 题，本批题号可先临时输出，服务端会统一改为全卷连续题号。`
+        : '这是本卷第一批题。'
+    ];
+    const batchTask = `只生成练习题目草稿：第 ${index + 1}/${questionTargetChunks.length} 批，正好 ${batchQuestionCount} 题，暂不生成标准答案、解题步骤和批改要点`;
+    const batchSchema = questionDraftSchema(batchQuestionCount);
+    const requestChars = compactRequestChars({
+      systemPrompt: questionSystemPrompt,
+      task: batchTask,
+      context: batchContext,
+      requirements: batchRequirements,
+      schema: batchSchema
+    });
+    onProgress({
+      step: 'practice_generate.questions',
+      message: `正在生成题目草稿：第 ${index + 1}/${questionTargetChunks.length} 批（${batchQuestionCount} 题，约 ${Math.round(requestChars / 1000)}KB 请求）。`
+    });
+    const chunk = assertAgentQuestions(await callPracticeAgent({
+      promptName,
+      task: batchTask,
+      context: batchContext,
+      requirements: batchRequirements,
+      schema: batchSchema
+    }), `question_generation_batch_${index + 1}`);
+    if (chunk.questions.length !== batchQuestionCount) {
+      throw generationError(
+        'question_batch_count_mismatch',
+        `batch=${index + 1} expected=${batchQuestionCount} actual=${chunk.questions.length}`
+      );
+    }
+    chunk.questions = chunk.questions.map((question, questionIndex) => ({
+      ...question,
+      id: `q${generatedQuestionCount + questionIndex + 1}`
+    }));
+    generatedQuestionCount += chunk.questions.length;
+    previousBatchStems.push(...chunk.questions.map((question) => compactPreviousStem(question.stem)));
+    questionChunks.push(chunk);
+  }
+  const questionDraft = {
+    title: normalizePracticeTitle(questionChunks[0]?.title || `${chapter.fullTitle || chapter.title}知识点覆盖练习`),
+    personalizationBasis: questionChunks
+      .flatMap((chunk) => Array.isArray(chunk.personalizationBasis) ? chunk.personalizationBasis : [])
+      .filter(Boolean)
+      .slice(0, 8),
+    coveragePlan: {
+      recommendedQuestionCount: totalQuestionCount,
+      rationale: questionChunks
+        .map((chunk) => chunk.coveragePlan?.rationale)
+        .filter(Boolean)
+        .join('；'),
+      priorityPointIds: targetKnowledgePoints.map((point) => point.id),
+      sampledMasteredPointIds: []
+    },
+    questions: questionChunks.flatMap((chunk) => chunk.questions)
+  };
+  if (questionDraft.questions.length !== totalQuestionCount) {
+    throw generationError(
+      'question_count_mismatch',
+      `expected=${totalQuestionCount} actual=${questionDraft.questions.length}`
+    );
+  }
+  onProgress({
+    step: 'practice_generate.questions_done',
+    message: `题目草稿已生成：${questionDraft.questions.length} 题，开始 LLM 质量评审。`
+  });
+  const practiceDraft = withProcessDefaults({
+    ...questionDraft,
+    source: 'agent'
+  });
+  onProgress({ step: 'practice_generate.review', message: '正在评审题目可作答性、覆盖规划和知识点绑定。' });
+  const review = await callPracticeAgent({
+    promptName: 'practice-review.system.md',
+    task: '评审练习题目草稿和知识点绑定；本阶段不评审答案元数据',
+    context: {
+      ...contextForQuestions(baseContext, practiceDraft.questions),
+      practiceDraft
+    },
+    requirements: [
+      '至少完成一次 LLM review；发现问题必须给出具体修正指令。',
+      '评审题目质量、可作答性、题量规划和 knowledgePointIds。',
+      '必须检查 knowledgePoints、expectedErrorTypes、skillAtoms、expectedAbilityErrors 是否为纯文本标签；出现 $...$、\\(...\\)、\\[...\\]、HTML 或公式包装时必须要求修正。',
+      isAbilityAssessment ? '能力评估题必须检查 abilityIds 是否完整且只来自 context.options.abilityIds。' : '',
+      '如果题目缺少必要条件、答案无法唯一推出、选项不完整或题型不合适，必须判 blocker。',
+      '必须检查 LaTeX 反斜杠是否损坏，尤其是 \\triangle、\\angle、\\perp、\\parallel、\\text{}；发现丢反斜杠或制表符残留必须判 blocker。',
+      '必须检查几何/SVG 题的题干与图中角标、垂足、切点、边名、长度和平行/垂直标注是否一致；不一致必须判 blocker。'
+    ].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']
+      }
+    }
+  });
+  if (!review.ok || !Array.isArray(review.data?.findings)) {
+    const attempts = review.attempts ? ` attempts=${review.attempts}` : '';
+    throw generationError(`review_${review.reason || 'invalid_agent_response'}`, `${review.detail || ''}${attempts}`);
+  }
+  onProgress({
+    step: 'practice_generate.review_done',
+    message: `质量评审完成：${review.data.findings.length} 条意见，开始修订题目。`
+  });
+  const revisionChunks = [];
+  const questionRevisionChunks = chunkArray(practiceDraft.questions, 3);
+  for (let index = 0; index < questionRevisionChunks.length; index += 1) {
+    const questions = questionRevisionChunks[index];
+    const questionIds = questions.map((question) => question.id);
+    const reviewFindings = (review.data.findings || [])
+      .filter((finding) => !finding.questionId || questionIds.includes(finding.questionId));
+    onProgress({
+      step: 'practice_generate.revision',
+      message: `正在修订题目：第 ${index + 1}/${questionRevisionChunks.length} 批（${questionIds.join('、')}）。`
+    });
+    const revisionChunk = assertAgentQuestions(await callPracticeAgent({
+      promptName: 'practice-revise.system.md',
+      task: `根据评审意见修正练习卷并输出修订版（第 ${index + 1}/${questionRevisionChunks.length} 批）`,
+      context: {
+        ...contextForQuestions(baseContext, questions),
+        practiceDraft: {
+          ...practiceDraft,
+          questions
+        },
+        review: {
+          ...review.data,
+          findings: reviewFindings
+        }
+      },
+      requirements: [
+        '必须根据 review 修正后输出最终题目。',
+        '只输出 practiceDraft.questions 中的题目，不新增题目，不删除题目，不改变题目 ID。',
+        '修订版必须包含题目、题型、难度、knowledgePointIds、knowledgePoints、expectedErrorTypes、配图字段和答题空间行数。',
+        isAbilityAssessment ? '能力评估修订版还必须保留 abilityIds、skillAtoms、expectedAbilityErrors。' : '',
+        'knowledgePoints 和 expectedErrorTypes 必须是纯文本短标签，不能包含 $...$、\\(...\\)、\\[...\\]、HTML 或公式包装。',
+        isAbilityAssessment ? 'skillAtoms 和 expectedAbilityErrors 必须是纯文本短标签，不能包含 $...$、\\(...\\)、\\[...\\]、HTML 或公式包装。' : '',
+        '不要输出 answer、solutionSteps 或 rubric；这些字段会在题目定稿后分批补全。',
+        '必须修复 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
+        }]
+      }
+    }), 'revision');
+    revisionChunks.push(revisionChunk);
+  }
+  const revisionQuestions = revisionChunks.flatMap((chunk) => chunk.questions);
+  const firstRevision = revisionChunks[0] || {};
+  const revision = {
+    title: normalizePracticeTitle(firstRevision.title || practiceDraft.title),
+    personalizationBasis: firstRevision.personalizationBasis || practiceDraft.personalizationBasis || [],
+    revisionSummary: revisionChunks
+      .map((chunk) => chunk.revisionSummary)
+      .filter(Boolean)
+      .join('\n'),
+    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']
+      }
+    }
+  });
+  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}`);
+  }
+  if (revisionCoverage.outsidePointIds.length) {
+    throw generationError('coverage_outside_target', revisionCoverage.outsidePointIds.join(','));
+  }
+  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('|')
+    );
+  }
+  onProgress({ step: 'practice_generate.final_review_done', message: `最终复审通过：${finalReview.data.findings.length} 条提示。` });
+  const answerChunks = [];
+  const answerQuestionChunks = chunkArray(revision.questions, 3);
+  for (let index = 0; index < answerQuestionChunks.length; index += 1) {
+    const questions = answerQuestionChunks[index];
+    const questionIds = questions.map((question) => question.id);
+    onProgress({
+      step: 'practice_generate.answers',
+      message: `正在生成标准答案和讲解：第 ${index + 1}/${answerQuestionChunks.length} 批（${questionIds.join('、')}）。`
+    });
+    const answerChunk = assertAgentQuestions(await callPracticeAgent({
+      promptName: 'practice-generate.system.md',
+      task: `为定稿题目补全答案元数据（第 ${index + 1}/${answerQuestionChunks.length} 批）`,
+      context: contextForAnswerMetadata(baseContext, questions),
+      requirements: [
+        '只输出输入 questions 中已有题目的 id、answer、solutionSteps、rubric。',
+        '不得修改题目 ID、题干、题型、难度、knowledgePointIds、knowledgePoints、expectedErrorTypes、abilityIds、skillAtoms、expectedAbilityErrors、score、answerSpaceLines、svg 或 imagePrompt。',
+        'answer 必须是可核对的标准答案；选择题写正确选项和结论，填空/问答题写完整答案。',
+        'solutionSteps 必须是 2-5 步中文解题过程，能够解释孩子错在哪里。',
+        'rubric 必须可用于批改，至少包含关键结论和关键过程；各项 score 之和应接近题目 score。',
+        '公式继续使用 LaTeX 分隔符，并保留完整反斜杠。'
+      ],
+      schema: answerMetadataSchema()
+    }), 'answer_generation');
+    answerChunks.push(answerChunk);
+  }
+  const enrichedQuestions = mergeAnswerMetadata(revision.questions, answerChunks);
+  onProgress({ step: 'practice_generate.answers_done', message: `答案和讲解已补全：${enrichedQuestions.length} 题。` });
+  return withProcessDefaults({
+    ...revision,
+    questions: enrichedQuestions,
+    coveragePlan: practiceDraft.coveragePlan || questionDraft.coveragePlan || null,
+    source: 'agent',
+    llmReview: finalReview.data,
+    initialLlmReview: review.data,
+    revision: {
+      summary: revision.revisionSummary || ''
+    }
+  });
+}