@zhouchangui/math-ati 0.1.0

package/server/fileStore.js

@@ -0,0 +1,726 @@
+import { access, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  flattenKnowledgePoints,
+  knowledgeToMarkdown
+} from './knowledgeBase.js';
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const dataDir = path.resolve(process.env.MATH_AGENT_DATA_DIR || path.join(rootDir, 'data'));
+const imageRoot = path.resolve(
+  process.env.MATH_AGENT_IMAGE_ROOT || path.join(rootDir, 'output', 'images', '初中数学_提分笔记_按章节')
+);
+
+export const paths = {
+  rootDir,
+  dataDir,
+  imageRoot,
+  global: path.join(dataDir, 'global'),
+  globalProfile: path.join(dataDir, 'global', 'student_profile.json'),
+  globalChapters: path.join(dataDir, 'global', 'chapters.json'),
+  globalMasteryIndex: path.join(dataDir, 'global', 'mastery_index.json'),
+  globalMistakesIndex: path.join(dataDir, 'global', 'mistakes_index.json'),
+  globalAbilityIndex: path.join(dataDir, 'global', 'ability_index.json'),
+  chapterData: path.join(dataDir, 'chapters'),
+  profile: path.join(dataDir, 'global', 'student_profile.json'),
+  chapters: path.join(dataDir, 'global', 'chapters.json'),
+  legacyProfile: path.join(dataDir, 'student_profile.json'),
+  legacyChapters: path.join(dataDir, 'chapters.json'),
+  mistakes: path.join(dataDir, 'mistakes.json'),
+  knowledge: path.join(dataDir, 'knowledge_points.json'),
+  knowledgeDocs: path.join(dataDir, 'knowledge_docs'),
+  knowledgeExtracts: path.join(dataDir, 'knowledge_extracts'),
+  mastery: path.join(dataDir, 'mastery.json')
+};
+
+export async function ensureDataDirs() {
+  await Promise.all([
+    mkdir(paths.knowledgeDocs, { recursive: true }),
+    mkdir(paths.knowledgeExtracts, { recursive: true }),
+    mkdir(paths.global, { recursive: true }),
+    mkdir(paths.chapterData, { recursive: true })
+  ]);
+}
+
+export async function readJson(filePath, fallback = undefined) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT' && fallback !== undefined) return fallback;
+    throw error;
+  }
+}
+
+export async function writeJson(filePath, data) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+export function relativeDataPath(filePath) {
+  return path.relative(rootDir, filePath);
+}
+
+export function chapterDataPaths(chapterId) {
+  const root = path.join(paths.chapterData, chapterId);
+  return {
+    root,
+    chapter: path.join(root, 'chapter.json'),
+    sourcePages: path.join(root, 'source_pages'),
+    sourceManifest: path.join(root, 'source_pages', 'manifest.json'),
+    knowledge: path.join(root, 'knowledge'),
+    pageExtracts: path.join(root, 'knowledge', 'page_extracts'),
+    knowledgeJson: path.join(root, 'knowledge', 'knowledge.json'),
+    knowledgeMarkdown: path.join(root, 'knowledge', 'knowledge.md'),
+    knowledgeSummary: path.join(root, 'knowledge', 'summary.json'),
+    mastery: path.join(root, 'mastery.json'),
+    abilities: path.join(root, 'abilities.json'),
+    mistakes: path.join(root, 'mistakes.json'),
+    practices: path.join(root, 'practices'),
+    submissions: path.join(root, 'submissions'),
+    reports: path.join(root, 'reports'),
+    context: path.join(root, 'context'),
+    generationHistory: path.join(root, 'context', 'generation_history.json'),
+    generatedCoverage: path.join(root, 'context', 'generated_coverage.json'),
+    mistakeSummary: path.join(root, 'context', 'mistake_summary.json'),
+    nextPlan: path.join(root, 'context', 'next_plan.json')
+  };
+}
+
+export async function ensureChapterDataDirs(chapterId) {
+  const chapterPaths = chapterDataPaths(chapterId);
+  await Promise.all([
+    mkdir(chapterPaths.sourcePages, { recursive: true }),
+    mkdir(chapterPaths.pageExtracts, { recursive: true }),
+    mkdir(chapterPaths.practices, { recursive: true }),
+    mkdir(chapterPaths.submissions, { recursive: true }),
+    mkdir(chapterPaths.reports, { recursive: true }),
+    mkdir(chapterPaths.context, { recursive: true })
+  ]);
+  return chapterPaths;
+}
+
+export async function ensureChapterWorkspace(chapter) {
+  const chapterPaths = await ensureChapterDataDirs(chapter.id);
+  await writeJson(chapterPaths.chapter, chapter);
+  try {
+    const folderPath = path.join(paths.imageRoot, chapter.imageFolder);
+    const files = (await readdir(folderPath))
+      .filter((file) => /\.(png|jpe?g|webp)$/i.test(file))
+      .sort();
+    await writeJson(chapterPaths.sourceManifest, {
+      chapterId: chapter.id,
+      chapterTitle: chapter.fullTitle,
+      imageFolder: chapter.imageFolder,
+      pageCount: files.length,
+      pages: files.map((file) => ({
+        file,
+        sourcePath: relativeDataPath(path.join(folderPath, file)),
+        localPath: relativeDataPath(path.join(chapterPaths.sourcePages, file))
+      }))
+    });
+  } catch {
+    await writeJson(chapterPaths.sourceManifest, {
+      chapterId: chapter.id,
+      chapterTitle: chapter.fullTitle,
+      imageFolder: chapter.imageFolder,
+      pageCount: 0,
+      pages: []
+    });
+  }
+  return chapterPaths;
+}
+
+async function writeChapterMasteryFiles(mastery) {
+  const chapters = Object.entries(mastery?.chapters || {});
+  for (const [chapterId, chapterMastery] of chapters) {
+    const chapterPaths = chapterDataPaths(chapterId);
+    try {
+      await access(chapterPaths.root);
+    } catch {
+      continue;
+    }
+    await ensureChapterDataDirs(chapterId);
+    await writeJson(chapterPaths.mastery, chapterMastery);
+  }
+}
+
+async function chapterIdsWithData(chapters) {
+  const ids = new Set((chapters || []).map((chapter) => chapter.id));
+  try {
+    const entries = await readdir(paths.chapterData, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) ids.add(entry.name);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return [...ids].sort();
+}
+
+export async function readChapterMistakes(chapterId) {
+  const chapterPaths = chapterDataPaths(chapterId);
+  const chapterMistakes = await readJson(chapterPaths.mistakes, null);
+  if (Array.isArray(chapterMistakes)) return chapterMistakes.map(normalizeMistakeRecord);
+  return (await readJson(paths.mistakes, []))
+    .filter((item) => item.chapterId === chapterId)
+    .map(normalizeMistakeRecord);
+}
+
+export function normalizeMistakeRecord(item = {}) {
+  item ||= {};
+  const status = item.status || (item.resolved ? 'resolved' : 'open');
+  const primaryKnowledgePointId = item.knowledgePointId || item.knowledgePointIds?.[0] || null;
+  const sourceKnowledgePointIds = [
+    ...new Set([
+      ...(Array.isArray(item.sourceKnowledgePointIds) ? item.sourceKnowledgePointIds : []),
+      ...(Array.isArray(item.knowledgePointIds) ? item.knowledgePointIds : []),
+      primaryKnowledgePointId
+    ].filter(Boolean))
+  ];
+  return {
+    ...item,
+    status,
+    resolved: status === 'resolved',
+    knowledgePointId: primaryKnowledgePointId,
+    sourceKnowledgePointIds,
+    occurrences: Math.max(1, Number(item.occurrences || 1)),
+    reviewDates: Array.isArray(item.reviewDates) ? item.reviewDates : [],
+    repairEvidence: Array.isArray(item.repairEvidence) ? item.repairEvidence : []
+  };
+}
+
+export function isResolvedMistake(item = {}) {
+  return normalizeMistakeRecord(item).status === 'resolved';
+}
+
+export function isActionableMistake(item = {}) {
+  return ['open', 'regressed'].includes(normalizeMistakeRecord(item).status);
+}
+
+export function isUnresolvedMistake(item = {}) {
+  return !isResolvedMistake(item);
+}
+
+export async function writeChapterMistakes(chapterId, mistakes) {
+  const chapterPaths = await ensureChapterDataDirs(chapterId);
+  const normalizedMistakes = mistakes.map(normalizeMistakeRecord);
+  await writeJson(chapterPaths.mistakes, normalizedMistakes);
+  await writeJson(chapterPaths.mistakeSummary, {
+    chapterId,
+    updatedAt: new Date().toISOString(),
+    total: normalizedMistakes.length,
+    unresolved: normalizedMistakes.filter(isUnresolvedMistake).length,
+    actionable: normalizedMistakes.filter(isActionableMistake).length,
+    mistakes: normalizedMistakes.slice(-30)
+  });
+
+  const allMistakes = await readJson(paths.mistakes, []);
+  const next = [
+    ...allMistakes.filter((item) => item.chapterId !== chapterId),
+    ...normalizedMistakes
+  ].sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')));
+  await writeJson(paths.mistakes, next);
+  await syncGlobalIndexes();
+  return normalizedMistakes;
+}
+
+async function countDirectoryEntries(dirPath, { filesOnly = false } = {}) {
+  try {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    return entries.filter((entry) => !filesOnly || entry.isFile()).length;
+  } catch (error) {
+    if (error.code === 'ENOENT') return 0;
+    throw error;
+  }
+}
+
+export async function resetChapterLearningLoop(chapterId) {
+  const chapterPaths = await ensureChapterDataDirs(chapterId);
+  const cleared = {
+    practices: await countDirectoryEntries(chapterPaths.practices, { filesOnly: true }),
+    submissions: await countDirectoryEntries(chapterPaths.submissions),
+    reports: await countDirectoryEntries(chapterPaths.reports, { filesOnly: true })
+  };
+
+  await Promise.all([
+    rm(chapterPaths.practices, { recursive: true, force: true }),
+    rm(chapterPaths.submissions, { recursive: true, force: true }),
+    rm(chapterPaths.reports, { recursive: true, force: true }),
+    rm(chapterPaths.generatedCoverage, { force: true }),
+    rm(chapterPaths.generationHistory, { force: true }),
+    rm(chapterPaths.mistakeSummary, { force: true }),
+    rm(chapterPaths.nextPlan, { force: true }),
+    rm(chapterPaths.abilities, { force: true })
+  ]);
+  await ensureChapterDataDirs(chapterId);
+  await writeChapterMistakes(chapterId, []);
+
+  const chapters = await readJson(paths.chapters, []);
+  const chapter = chapters.find((item) => item.id === chapterId);
+  if (chapter) {
+    chapter.status = 'not_started';
+    chapter.mastery = 0;
+    chapter.latestAccuracy = null;
+    chapter.topErrorTypes = [];
+    chapter.resetAt = new Date().toISOString();
+    await writeJson(paths.chapters, chapters);
+  }
+  await syncGlobalIndexes();
+  return { chapterId, cleared };
+}
+
+export async function syncGlobalIndexes() {
+  await ensureDataDirs();
+  const chapters = await readJson(paths.chapters, []);
+  await writeJson(paths.globalProfile, await readJson(paths.profile, {}));
+  await writeJson(paths.globalChapters, chapters);
+
+  const legacyMastery = await readJson(paths.mastery, { chapters: {} });
+  const legacyMistakes = await readJson(paths.mistakes, []);
+  const ids = await chapterIdsWithData(chapters);
+  const masteryIndex = {
+    student: '周子烊',
+    version: 1,
+    updatedAt: new Date().toISOString(),
+    source: 'chapter-masteries',
+    chapters: {}
+  };
+  const mistakesIndex = {
+    student: '周子烊',
+    version: 1,
+    updatedAt: new Date().toISOString(),
+    source: 'chapter-mistakes',
+    chapters: {},
+    recent: []
+  };
+
+  for (const chapterId of ids) {
+    const chapterPaths = chapterDataPaths(chapterId);
+    const chapter = chapters.find((item) => item.id === chapterId);
+    const mastery = await readJson(chapterPaths.mastery, legacyMastery.chapters?.[chapterId] || null);
+    if (mastery) {
+      masteryIndex.chapters[chapterId] = {
+        chapterTitle: mastery.chapterTitle || chapter?.fullTitle || chapterId,
+        track: mastery.track || chapter?.track || '',
+        coverage: mastery.coverage || null,
+        updatedAt: mastery.updatedAt || legacyMastery.updatedAt || null
+      };
+    }
+
+    const mistakes = await readJson(
+      chapterPaths.mistakes,
+      legacyMistakes.filter((item) => item.chapterId === chapterId)
+    );
+    mistakesIndex.chapters[chapterId] = {
+      chapterTitle: chapter?.fullTitle || chapterId,
+      total: mistakes.length,
+      unresolved: mistakes.filter(isUnresolvedMistake).length,
+      actionable: mistakes.filter(isActionableMistake).length,
+      topErrorTypes: Object.entries(
+        mistakes.filter(isUnresolvedMistake).reduce((acc, item) => {
+          const key = item.errorType || '待确认';
+          acc[key] = (acc[key] || 0) + 1;
+          return acc;
+        }, {})
+      )
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 8)
+        .map(([errorType, count]) => ({ errorType, count }))
+    };
+    mistakesIndex.recent.push(...mistakes.slice(-5));
+  }
+
+  mistakesIndex.recent = mistakesIndex.recent
+    .sort((a, b) => String(b.createdAt || '').localeCompare(String(a.createdAt || '')))
+    .slice(0, 30);
+  await writeJson(paths.globalMasteryIndex, masteryIndex);
+  await writeJson(paths.globalMistakesIndex, mistakesIndex);
+  return { masteryIndex, mistakesIndex };
+}
+
+export async function readText(filePath, fallback = '') {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return fallback;
+    throw error;
+  }
+}
+
+function parseCsvLine(line) {
+  const values = [];
+  let current = '';
+  let quoted = false;
+  for (const char of line) {
+    if (char === '"') {
+      quoted = !quoted;
+    } else if (char === ',' && !quoted) {
+      values.push(current);
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+  values.push(current);
+  return values;
+}
+
+function trackForChapter(title) {
+  const algebra = [
+    '有理数',
+    '有理数的运算',
+    '代数式',
+    '整式的加减',
+    '一元一次方程',
+    '二元一次方程组',
+    '不等式与不等式组',
+    '整式的乘法',
+    '因式分解',
+    '分式',
+    '二次根式',
+    '一元二次方程'
+  ];
+  const functions = ['平面直角坐标系', '函数', '一次函数', '反比例函数', '二次函数'];
+  const statistics = ['数据的收集、整理与描述', '数据的分析', '随机事件的概率'];
+  if (algebra.some((item) => title.includes(item))) return '计算与代数地基';
+  if (functions.some((item) => title.includes(item))) return '函数主线';
+  if (statistics.some((item) => title.includes(item))) return '统计概率主线';
+  return '几何证明主线';
+}
+
+export async function seedChaptersFromManifest() {
+  await ensureDataDirs();
+  let existingChapters = null;
+  try {
+    existingChapters = JSON.parse(await readFile(paths.chapters, 'utf8'));
+    await seedKnowledgeAssets(existingChapters);
+    return;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+
+  const manifest = await readText(path.join(paths.imageRoot, 'manifest.csv'));
+  const rows = manifest.trim().split(/\r?\n/).slice(1).map(parseCsvLine);
+  const chapters = [];
+  for (const [chapter, bookStart, bookEnd, pdfStart, pdfEnd, folder] of rows) {
+    const folderPath = path.join(paths.imageRoot, folder);
+    const imageFiles = (await readdir(folderPath))
+      .filter((file) => file.endsWith('.png'))
+      .sort();
+    chapters.push({
+      id: `chapter-${String(chapters.length + 1).padStart(2, '0')}`,
+      title: chapter.replace(/^第.+?章/, '').trim() || chapter,
+      chapterLabel: chapter.match(/^第.+?章/)?.[0] ?? `第${chapters.length + 1}章`,
+      fullTitle: `${chapter.match(/^第.+?章/)?.[0] ?? ''} ${chapter.replace(/^第.+?章/, '').trim()}`.trim(),
+      track: trackForChapter(chapter),
+      bookStart: Number(bookStart),
+      bookEnd: Number(bookEnd),
+      pdfStart: Number(pdfStart),
+      pdfEnd: Number(pdfEnd),
+      imageFolder: folder,
+      imageCount: imageFiles.length,
+      coverImage: `/chapter-images/${encodeURIComponent(folder)}/${imageFiles[0]}`,
+      status: 'not_started',
+      mastery: 0,
+      latestAccuracy: null,
+      topErrorTypes: []
+    });
+  }
+  await writeJson(paths.chapters, chapters);
+  await seedKnowledgeAssets(chapters);
+}
+
+export async function updateChapterAfterArchive(chapterId, accuracy, errorTypes) {
+  const chapters = await readJson(paths.chapters, []);
+  const chapter = chapters.find((item) => item.id === chapterId);
+  if (!chapter) return;
+  chapter.latestAccuracy = accuracy;
+  chapter.mastery = Math.max(chapter.mastery ?? 0, Math.round(accuracy));
+  chapter.topErrorTypes = errorTypes;
+  chapter.status = accuracy >= 90 ? 'review_due' : 'in_progress';
+  await writeJson(paths.chapters, chapters);
+}
+
+function normalizeKnowledgeDoc(chapter, doc, source = 'seed') {
+  const sections = (doc.sections || []).map((section, sectionIndex) => ({
+    title: section.title || `知识组 ${sectionIndex + 1}`,
+    points: (section.points || []).map((point, pointIndex) => ({
+      id: point.id || `${chapter.id}-kp-${String(sectionIndex + 1).padStart(2, '0')}-${String(pointIndex + 1).padStart(2, '0')}`,
+      title: point.title || `知识点 ${pointIndex + 1}`,
+      summary: point.summary || '待补充。',
+      formulas: Array.isArray(point.formulas) ? point.formulas : [],
+      pitfalls: Array.isArray(point.pitfalls) ? point.pitfalls : [],
+      examples: Array.isArray(point.examples) ? point.examples : [],
+      questionTemplates: Array.isArray(point.questionTemplates) ? point.questionTemplates : []
+    }))
+  })).filter((section) => section.points.length);
+  return {
+    chapterId: chapter.id,
+    chapterTitle: chapter.fullTitle,
+    track: chapter.track,
+    source,
+    extractionStatus: source === 'agent' ? 'agent_extracted' : 'seeded',
+    updatedAt: new Date().toISOString(),
+    sections
+  };
+}
+
+function buildInitialMastery(chapters, knowledgeDocs, existing = null) {
+  const next = {
+    student: '周子烊',
+    version: 1,
+    updatedAt: new Date().toISOString(),
+    chapters: existing?.chapters || {}
+  };
+  for (const chapter of chapters) {
+    const knowledgeDoc = knowledgeDocs.find((item) => item.chapterId === chapter.id);
+    if (!knowledgeDoc) continue;
+    const current = next.chapters[chapter.id] || {
+      chapterTitle: chapter.fullTitle,
+      track: chapter.track,
+      coverage: { total: 0, covered: 0, mastered: 0, needsReview: 0 },
+      points: {}
+    };
+    current.chapterTitle = chapter.fullTitle;
+    current.track = chapter.track;
+    for (const point of flattenKnowledgePoints(knowledgeDoc)) {
+      current.points[point.id] ||= {
+        id: point.id,
+        title: point.title,
+        sectionTitle: point.sectionTitle,
+        status: 'not_started',
+        coveredCount: 0,
+        correctCount: 0,
+        wrongCount: 0,
+        lastPracticeId: null,
+        lastSubmissionId: null,
+        lastUpdatedAt: null,
+        errorTypes: []
+      };
+      current.points[point.id].title = point.title;
+      current.points[point.id].sectionTitle = point.sectionTitle;
+    }
+    current.coverage = masteryCoverage(current.points);
+    next.chapters[chapter.id] = current;
+  }
+  return next;
+}
+
+function masteryCoverage(points) {
+  const values = Object.values(points || {});
+  return {
+    total: values.length,
+    covered: values.filter((item) => item.coveredCount > 0).length,
+    mastered: values.filter((item) => item.status === 'mastered').length,
+    needsReview: values.filter((item) => item.status === 'needs_review').length
+  };
+}
+
+function mergeChapterMastery(template, existing) {
+  if (!existing) return template;
+  const next = {
+    ...template,
+    ...existing,
+    points: {}
+  };
+  const pointIds = new Set([
+    ...Object.keys(template.points || {}),
+    ...Object.keys(existing.points || {})
+  ]);
+  for (const pointId of pointIds) {
+    next.points[pointId] = {
+      ...(template.points?.[pointId] || {}),
+      ...(existing.points?.[pointId] || {})
+    };
+  }
+  next.coverage = masteryCoverage(next.points);
+  return next;
+}
+
+export async function seedKnowledgeAssets(chapters) {
+  await ensureDataDirs();
+  const existingDocs = await readJson(paths.knowledge, []);
+  const byChapter = new Map(existingDocs.map((doc) => [doc.chapterId, doc]));
+  const knowledgeDocs = [];
+  for (const chapter of chapters) {
+    const existing = byChapter.get(chapter.id);
+    if (!existing) {
+      const error = new Error(`knowledge_doc_missing:${chapter.id}`);
+      error.status = 422;
+      throw error;
+    }
+    const doc = existing;
+    const docPath = path.join(paths.knowledgeDocs, `${chapter.id}.md`);
+    doc.docPath = relativeDataPath(docPath);
+    knowledgeDocs.push(doc);
+    await writeFile(docPath, knowledgeToMarkdown(chapter, doc), 'utf8');
+  }
+  await writeJson(paths.knowledge, knowledgeDocs);
+  const existingMastery = await readJson(paths.mastery, null);
+  const mastery = buildInitialMastery(chapters, knowledgeDocs, existingMastery);
+  for (const chapter of chapters) {
+    const chapterPaths = chapterDataPaths(chapter.id);
+    const chapterMastery = await readJson(chapterPaths.mastery, null);
+    if (mastery.chapters[chapter.id]) {
+      mastery.chapters[chapter.id] = mergeChapterMastery(mastery.chapters[chapter.id], chapterMastery);
+    }
+  }
+  await writeJson(paths.mastery, mastery);
+  await writeChapterMasteryFiles(mastery);
+  await syncGlobalIndexes();
+}
+
+export async function getKnowledgeBundle(chapterId = null) {
+  const chapters = await readJson(paths.chapters, []);
+  await seedKnowledgeAssets(chapters);
+  const knowledge = await readJson(paths.knowledge, []);
+  const mastery = await readJson(paths.mastery, { chapters: {} });
+  if (!chapterId) return { knowledge, mastery };
+  const chapterPaths = chapterDataPaths(chapterId);
+  const chapter = chapters.find((item) => item.id === chapterId);
+  if (chapter) await ensureChapterWorkspace(chapter);
+  const doc = await readJson(chapterPaths.knowledgeJson, null);
+  const markdown = doc && chapter
+    ? await readText(chapterPaths.knowledgeMarkdown, doc.docPath ? await readText(path.join(rootDir, doc.docPath), '') : '')
+    : '';
+  const chapterMastery = await readJson(chapterPaths.mastery, mastery.chapters?.[chapterId] || null);
+  const sourceManifest = await readJson(chapterPaths.sourceManifest, null);
+  const summary = await readJson(chapterPaths.knowledgeSummary, null);
+  const pageExtracts = sourceManifest?.pages
+    ? await Promise.all(sourceManifest.pages.map(async (page, index) => {
+      const extractFile = `${path.basename(page.file, path.extname(page.file))}.json`;
+      const extractPath = path.join(chapterPaths.pageExtracts, extractFile);
+      const extract = await readJson(extractPath, null);
+      return extract
+        ? { ...extract, extractPath: relativeDataPath(extractPath) }
+        : {
+          chapterId,
+          imageFile: page.file,
+          pageIndex: index + 1,
+          rawOutline: [],
+          knowledgePoints: [],
+          extractPath: relativeDataPath(extractPath)
+        };
+    }))
+    : [];
+  const pointCount = (doc?.sections || []).reduce((sum, section) => sum + (section.points || []).length, 0);
+  const sourcePageCount = Number(sourceManifest?.pageCount || sourceManifest?.pages?.length || 0);
+  const extractProfile = doc?.extractProfile || summary?.extractProfile || {
+    detailLevel: 'exam_focus',
+    studentBaseline: 'strong',
+    focus: ['exam_points', 'error_prone'],
+    displayLayer: 'exam_point_wall'
+  };
+  const availability = {
+    status: pointCount > 0 ? 'available' : sourcePageCount > 0 ? 'missing' : 'missing_source',
+    reason: pointCount > 0
+      ? ''
+      : sourcePageCount > 0
+        ? 'knowledge_not_extracted'
+        : 'source_pages_missing',
+    knowledgePointCount: pointCount,
+    sourcePageCount,
+    extractedAt: doc?.extractedAt || doc?.updatedAt || summary?.updatedAt || null,
+    extractionStatus: doc?.extractionStatus || null,
+    source: doc?.source || null
+  };
+  return {
+    knowledge: doc || null,
+    markdown,
+    mastery: chapterMastery,
+    availability,
+    extractProfile,
+    extractionSummary: summary,
+    sourcePages: sourceManifest || null,
+    pageExtracts
+  };
+}
+
+export async function saveKnowledgeDoc(chapter, doc, source = 'agent', metadata = {}) {
+  await ensureDataDirs();
+  const chapters = await readJson(paths.chapters, []);
+  const knowledge = await readJson(paths.knowledge, []);
+  const normalized = normalizeKnowledgeDoc(chapter, doc, source);
+  if (metadata.extractProfile) normalized.extractProfile = metadata.extractProfile;
+  if (metadata.sourceManifest) normalized.sourceManifest = metadata.sourceManifest;
+  if (metadata.extractorVersion) normalized.extractorVersion = metadata.extractorVersion;
+  if (metadata.extractedAt) normalized.extractedAt = metadata.extractedAt;
+  const docPath = path.join(paths.knowledgeDocs, `${chapter.id}.md`);
+  normalized.docPath = relativeDataPath(docPath);
+  const next = knowledge.filter((item) => item.chapterId !== chapter.id);
+  next.push(normalized);
+  next.sort((a, b) => a.chapterId.localeCompare(b.chapterId));
+  await writeJson(paths.knowledge, next);
+  await writeFile(docPath, knowledgeToMarkdown(chapter, normalized), 'utf8');
+  const chapterPaths = await ensureChapterDataDirs(chapter.id);
+  const chapterDoc = {
+    ...normalized,
+    docPath: relativeDataPath(chapterPaths.knowledgeMarkdown)
+  };
+  await writeJson(chapterPaths.knowledgeJson, chapterDoc);
+  await writeFile(chapterPaths.knowledgeMarkdown, knowledgeToMarkdown(chapter, chapterDoc), 'utf8');
+  const existingMastery = await readJson(paths.mastery, null);
+  const scopedExistingMastery = metadata.resetLearningState && existingMastery?.chapters
+    ? {
+        ...existingMastery,
+        chapters: Object.fromEntries(
+          Object.entries(existingMastery.chapters).filter(([chapterId]) => chapterId !== chapter.id)
+        )
+      }
+    : existingMastery;
+  const mastery = buildInitialMastery(chapters, next, scopedExistingMastery);
+  const existingChapterMastery = await readJson(chapterPaths.mastery, null);
+  if (!metadata.resetLearningState && mastery.chapters[chapter.id]) {
+    mastery.chapters[chapter.id] = mergeChapterMastery(mastery.chapters[chapter.id], existingChapterMastery);
+  }
+  await writeJson(paths.mastery, mastery);
+  await writeJson(chapterPaths.mastery, mastery.chapters[chapter.id]);
+  await syncGlobalIndexes();
+  return chapterDoc;
+}
+
+export async function updateKnowledgeMasteryAfterArchive(practice, grading) {
+  const chapters = await readJson(paths.chapters, []);
+  const knowledge = await readJson(paths.knowledge, []);
+  const mastery = buildInitialMastery(chapters, knowledge, await readJson(paths.mastery, null));
+  const chapterPaths = await ensureChapterDataDirs(practice.chapterId);
+  const existingChapterMastery = await readJson(chapterPaths.mastery, null);
+  mastery.chapters[practice.chapterId] = mergeChapterMastery(mastery.chapters[practice.chapterId], existingChapterMastery);
+  const chapterMastery = mastery.chapters[practice.chapterId];
+  if (!chapterMastery) return mastery;
+
+  for (const item of grading) {
+    const question = practice.questions.find((candidate) => candidate.id === item.questionId);
+    const ids = question?.knowledgePointIds?.length ? question.knowledgePointIds : [];
+    const maxScore = Number(item.maxScore || question?.score || 0);
+    const score = Number(item.score || 0);
+    const ratio = maxScore > 0 ? score / maxScore : 0;
+    for (const pointId of ids) {
+      const point = chapterMastery.points[pointId];
+      if (!point) continue;
+      point.coveredCount += 1;
+      point.lastPracticeId = practice.id;
+      point.lastSubmissionId = item.submissionId || null;
+      point.lastUpdatedAt = new Date().toISOString();
+      point.errorTypes = [...new Set([...(point.errorTypes || []), ...(item.errorTypes || [])].filter(Boolean))].slice(0, 8);
+      if (item.status === 'correct' || ratio >= 0.85) {
+        point.correctCount += 1;
+        point.status = point.correctCount >= 2 || ratio >= 0.95 ? 'mastered' : 'covered';
+      } else if (ratio > 0 || item.status === 'partial') {
+        point.wrongCount += 1;
+        point.status = 'needs_review';
+      } else {
+        point.wrongCount += 1;
+        point.status = 'needs_review';
+      }
+    }
+  }
+  chapterMastery.coverage = masteryCoverage(chapterMastery.points);
+  chapterMastery.updatedAt = new Date().toISOString();
+  mastery.updatedAt = new Date().toISOString();
+  await writeJson(chapterPaths.mastery, chapterMastery);
+  await writeJson(paths.mastery, mastery);
+  await syncGlobalIndexes();
+  return mastery;
+}