@zhouchangui/math-ati 0.1.0

package/server/abilityService.js

@@ -0,0 +1,259 @@
+import {
+  chapterDataPaths,
+  paths,
+  readJson,
+  writeJson
+} from './fileStore.js';
+
+export const ABILITY_CATALOG = [
+  {
+    id: 'calculation_accuracy',
+    title: '计算能力',
+    description: '评估本章相关计算的准确性与稳定性。',
+    category: 'calculation',
+    passThreshold: 0.9,
+    requiredConsecutivePasses: 2,
+    firstVersionScope: '只评估正确率、错误类型和连续达标；暂不考虑用时。'
+  }
+];
+
+const DEFAULT_ASSESSMENT_FLOWS = {
+  knowledge: true,
+  mistakeRepair: true,
+  abilities: []
+};
+
+export function normalizeAbilityIds(ids = []) {
+  const known = new Set(ABILITY_CATALOG.map((ability) => ability.id));
+  return [...new Set(ids.filter((id) => known.has(id)))];
+}
+
+export function normalizeAssessmentFlows(chapter = {}) {
+  const flows = chapter.assessmentFlows || {};
+  return {
+    knowledge: flows.knowledge !== false,
+    mistakeRepair: flows.mistakeRepair !== false,
+    abilities: normalizeAbilityIds(Array.isArray(flows.abilities) ? flows.abilities : DEFAULT_ASSESSMENT_FLOWS.abilities)
+  };
+}
+
+function initialAbilityState(abilityId) {
+  const catalog = ABILITY_CATALOG.find((item) => item.id === abilityId);
+  return {
+    id: abilityId,
+    title: catalog?.title || abilityId,
+    status: 'not_started',
+    assessmentCount: 0,
+    correctCount: 0,
+    wrongCount: 0,
+    consecutivePasses: 0,
+    lastAssessmentPracticeId: null,
+    lastSubmissionId: null,
+    lastUpdatedAt: null,
+    lastAccuracy: null,
+    errorTypes: []
+  };
+}
+
+export async function enabledAbilityIdsForChapter(chapterId) {
+  const state = await buildChapterAbilities(chapterId);
+  return state.enabledAbilityIds;
+}
+
+export async function assertChapterAbilitiesEnabled(chapterId, requestedAbilityIds = []) {
+  const enabledAbilityIds = await enabledAbilityIdsForChapter(chapterId);
+  const enabled = new Set(enabledAbilityIds);
+  const requested = Array.isArray(requestedAbilityIds) && requestedAbilityIds.length
+    ? [...new Set(requestedAbilityIds)]
+    : enabledAbilityIds;
+  const unknown = requested.filter((id) => !ABILITY_CATALOG.some((ability) => ability.id === id));
+  if (unknown.length) {
+    const error = new Error(`unknown_ability:${unknown.join(',')}`);
+    error.status = 422;
+    throw error;
+  }
+  const disabled = requested.filter((id) => !enabled.has(id));
+  if (disabled.length) {
+    const error = new Error(`ability_not_enabled:${disabled.join(',')}`);
+    error.status = 422;
+    throw error;
+  }
+  if (!requested.length) {
+    const error = new Error(`ability_assessment_not_enabled:${chapterId}`);
+    error.status = 422;
+    throw error;
+  }
+  return requested;
+}
+
+function plainLabel(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 abilityIdsForQuestion(question, practiceAbilityIds) {
+  const ids = Array.isArray(question.abilityIds) && question.abilityIds.length
+    ? question.abilityIds
+    : practiceAbilityIds;
+  return normalizeAbilityIds(ids);
+}
+
+function isCorrectGrade(item) {
+  if (item?.status === 'correct') return true;
+  const maxScore = Number(item?.maxScore || 0);
+  const score = Number(item?.score || 0);
+  return maxScore > 0 && score >= maxScore;
+}
+
+function mergeUniqueLabels(...groups) {
+  return [...new Set(groups.flat().map(plainLabel).filter(Boolean))].slice(0, 12);
+}
+
+export async function buildChapterAbilities(chapterId) {
+  const chapters = await readJson(paths.chapters, []);
+  const chapter = chapters.find((item) => item.id === chapterId);
+  if (!chapter) {
+    const error = new Error(`chapter_not_found:${chapterId}`);
+    error.status = 404;
+    throw error;
+  }
+  const assessmentFlows = normalizeAssessmentFlows(chapter);
+  const chapterPaths = chapterDataPaths(chapterId);
+  const existing = await readJson(chapterPaths.abilities, null);
+  const existingAbilities = existing?.abilities || {};
+  const abilities = Object.fromEntries(assessmentFlows.abilities.map((abilityId) => [
+    abilityId,
+    {
+      ...initialAbilityState(abilityId),
+      ...(existingAbilities[abilityId] || {}),
+      id: abilityId,
+      title: ABILITY_CATALOG.find((item) => item.id === abilityId)?.title || abilityId
+    }
+  ]));
+  return {
+    chapterId,
+    chapterTitle: chapter.fullTitle || chapter.title || chapterId,
+    updatedAt: existing?.updatedAt || null,
+    assessmentFlows,
+    catalog: ABILITY_CATALOG,
+    enabledAbilityIds: assessmentFlows.abilities,
+    abilities
+  };
+}
+
+export async function syncChapterAbilities(chapterId) {
+  const state = {
+    ...(await buildChapterAbilities(chapterId)),
+    updatedAt: new Date().toISOString()
+  };
+  await writeJson(chapterDataPaths(chapterId).abilities, state);
+  return state;
+}
+
+export async function buildAbilityIndex() {
+  const chapters = await readJson(paths.chapters, []);
+  const chapterStates = {};
+  for (const chapter of chapters) {
+    const state = await buildChapterAbilities(chapter.id);
+    if (!state.enabledAbilityIds.length) continue;
+    chapterStates[chapter.id] = {
+      chapterTitle: state.chapterTitle,
+      enabledAbilityIds: state.enabledAbilityIds,
+      abilities: state.abilities,
+      updatedAt: state.updatedAt
+    };
+  }
+  return {
+    version: 1,
+    updatedAt: new Date().toISOString(),
+    source: 'chapter-abilities',
+    catalog: ABILITY_CATALOG,
+    chapters: chapterStates
+  };
+}
+
+export async function syncAbilityIndex() {
+  const index = await buildAbilityIndex();
+  await writeJson(paths.globalAbilityIndex, index);
+  return index;
+}
+
+export async function updateAbilitiesAfterArchive({ practice, grading = [], submissionId }) {
+  if (practice?.type !== 'ability_assessment') return null;
+  const requestedAbilityIds = await assertChapterAbilitiesEnabled(practice.chapterId, practice.abilityIds || []);
+  const state = await buildChapterAbilities(practice.chapterId);
+  const gradingByQuestionId = new Map((grading || []).map((item) => [item.questionId, item]));
+  const now = new Date().toISOString();
+  const nextAbilities = { ...state.abilities };
+
+  for (const abilityId of requestedAbilityIds) {
+    const catalog = ABILITY_CATALOG.find((item) => item.id === abilityId);
+    const relatedQuestions = (practice.questions || []).filter((question) =>
+      abilityIdsForQuestion(question, requestedAbilityIds).includes(abilityId)
+    );
+    const relatedGrades = relatedQuestions
+      .map((question) => ({
+        question,
+        grade: gradingByQuestionId.get(question.id)
+      }))
+      .filter((item) => item.grade);
+    const previous = nextAbilities[abilityId] || initialAbilityState(abilityId);
+    if (!relatedGrades.length) {
+      nextAbilities[abilityId] = {
+        ...previous,
+        lastAssessmentPracticeId: practice.id,
+        lastSubmissionId: submissionId,
+        lastUpdatedAt: now
+      };
+      continue;
+    }
+    const totalScore = relatedGrades.reduce((sum, item) => sum + Number(item.grade.maxScore || item.question.score || 0), 0);
+    const earnedScore = relatedGrades.reduce((sum, item) => sum + Number(item.grade.score || 0), 0);
+    const correctItems = relatedGrades.filter((item) => isCorrectGrade(item.grade)).length;
+    const weakItems = relatedGrades.length - correctItems;
+    const accuracy = totalScore > 0 ? earnedScore / totalScore : 0;
+    const passed = accuracy >= Number(catalog?.passThreshold || 0.9);
+    const consecutivePasses = passed ? Number(previous.consecutivePasses || 0) + 1 : 0;
+    const status = consecutivePasses >= Number(catalog?.requiredConsecutivePasses || 2)
+      ? 'mastered'
+      : passed
+        ? 'in_progress'
+        : 'needs_review';
+    const gradingErrors = relatedGrades.flatMap((item) => Array.isArray(item.grade.errorTypes) ? item.grade.errorTypes : []);
+    const expectedErrors = relatedGrades
+      .filter((item) => !isCorrectGrade(item.grade))
+      .flatMap((item) => Array.isArray(item.question.expectedAbilityErrors) ? item.question.expectedAbilityErrors : []);
+    nextAbilities[abilityId] = {
+      ...previous,
+      id: abilityId,
+      title: catalog?.title || previous.title || abilityId,
+      status,
+      assessmentCount: Number(previous.assessmentCount || 0) + 1,
+      correctCount: Number(previous.correctCount || 0) + correctItems,
+      wrongCount: Number(previous.wrongCount || 0) + weakItems,
+      consecutivePasses,
+      lastAssessmentPracticeId: practice.id,
+      lastSubmissionId: submissionId,
+      lastUpdatedAt: now,
+      lastAccuracy: Math.round(accuracy * 100),
+      errorTypes: mergeUniqueLabels(previous.errorTypes || [], gradingErrors, expectedErrors)
+    };
+  }
+
+  const nextState = {
+    ...state,
+    updatedAt: now,
+    abilities: nextAbilities
+  };
+  await writeJson(chapterDataPaths(practice.chapterId).abilities, nextState);
+  await syncAbilityIndex();
+  return nextState;
+}

package/server/agentClient.js

@@ -0,0 +1,202 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getLlmRuntimeConfig } from './llmConfig.js';
+
+function mimeForFile(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+  if (ext === '.webp') return 'image/webp';
+  return 'image/png';
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function fixtureMode() {
+  return process.env.NODE_ENV === 'test' ? process.env.MATH_AGENT_AGENT_FIXTURE || '' : '';
+}
+
+function knowledgeExtractPageFixture() {
+  return {
+    ok: true,
+    data: {
+      pageTitle: '测试页知识点',
+      rawOutline: ['测试用章节知识点提取流程'],
+      knowledgePoints: [
+        {
+          title: '有理数的运算核心知识点',
+          summary: '理解有理数加减乘除的运算顺序和符号处理。',
+          formulas: [],
+          examples: ['-3 + 5 = 2'],
+          prerequisite: '有理数的概念',
+          difficulty: 'basic'
+        }
+      ],
+      easyMistakes: [
+        {
+          title: '符号处理错误',
+          errorType: '符号处理错误',
+          description: '负数参与运算时容易漏写负号。',
+          correction: '先确定符号，再计算绝对值。'
+        }
+      ],
+      exerciseHints: ['设计一道有理数混合运算题。']
+    },
+    attempts: 1
+  };
+}
+
+function knowledgeSummarizeFixture() {
+  return {
+    ok: true,
+    data: {
+      sections: [
+        {
+          title: '知识点覆盖',
+          points: [
+            {
+              id: 'fixture-kp-01',
+              title: '有理数的运算核心知识点',
+              summary: '理解有理数加减乘除的运算顺序和符号处理。',
+              formulas: [],
+              pitfalls: ['符号处理错误'],
+              examples: ['-3 + 5 = 2'],
+              questionTemplates: [
+                ['计算：-3 + 5。', '2', '符号处理错误']
+              ],
+              sources: ['fixture-page.png']
+            }
+          ]
+        }
+      ],
+      review: {
+        passed: true,
+        coverageSummary: '测试 fixture 覆盖 1 个知识点。',
+        missingOrWeak: [],
+        duplicateMerged: []
+      }
+    },
+    attempts: 1
+  };
+}
+
+function shouldRetry(result) {
+  if (result.ok) return false;
+  return [
+    'timeout',
+    'fetch_failed',
+    'empty_response',
+    'invalid_json',
+    'http_408',
+    'http_409',
+    'http_425',
+    'http_429',
+    'http_500',
+    'http_502',
+    'http_503',
+    'http_504'
+  ].includes(result.reason);
+}
+
+async function postChatCompletionOnce({ messages, temperature = 0.3, timeoutMs = 12000 }) {
+  const { baseUrl, apiKey, model } = await getLlmRuntimeConfig();
+  if (!baseUrl || !apiKey) {
+    return { ok: false, reason: 'missing_env' };
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetch(`${baseUrl.replace(/\/$/, '')}/v1/chat/completions`, {
+      method: 'POST',
+      signal: controller.signal,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        model,
+        temperature,
+        messages,
+        response_format: { type: 'json_object' }
+      })
+    });
+  } catch (error) {
+    return { ok: false, reason: error.name === 'AbortError' ? 'timeout' : 'fetch_failed', detail: error.message };
+  } finally {
+    clearTimeout(timeout);
+  }
+  if (!response.ok) {
+    return { ok: false, reason: `http_${response.status}`, detail: await response.text() };
+  }
+  const payload = await response.json();
+  const text = payload.choices?.[0]?.message?.content;
+  if (!text) return { ok: false, reason: 'empty_response' };
+  try {
+    return { ok: true, data: JSON.parse(text) };
+  } catch {
+    return { ok: false, reason: 'invalid_json', detail: text };
+  }
+}
+
+async function postChatCompletion({ messages, temperature = 0.3, timeoutMs = 12000, retries = 1 }) {
+  let lastResult = null;
+  const attempts = Math.max(1, Number(retries || 0) + 1);
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const result = await postChatCompletionOnce({ messages, temperature, timeoutMs });
+    if (result.ok || !shouldRetry(result) || attempt === attempts) {
+      return {
+        ...result,
+        attempts: attempt,
+        previousReason: lastResult?.reason || null
+      };
+    }
+    lastResult = result;
+    await sleep(Math.min(1000 * attempt, 3000));
+  }
+  return lastResult;
+}
+
+export async function callChatAgent({ system, user, temperature = 0.3, timeoutMs = 12000, retries = 1 }) {
+  if (fixtureMode() === 'knowledge-extract') return knowledgeSummarizeFixture();
+  return postChatCompletion({
+    temperature,
+    timeoutMs,
+    retries,
+    messages: [
+      { role: 'system', content: system },
+      { role: 'user', content: user }
+    ]
+  });
+}
+
+export async function callVisionAgent({ system, text, imagePaths, temperature = 0.1, timeoutMs = 45000, retries = 1 }) {
+  if (fixtureMode() === 'knowledge-extract') return knowledgeExtractPageFixture();
+  const imageContent = [];
+  for (const imagePath of imagePaths || []) {
+    const bytes = await readFile(imagePath);
+    imageContent.push({
+      type: 'image_url',
+      image_url: {
+        url: `data:${mimeForFile(imagePath)};base64,${bytes.toString('base64')}`
+      }
+    });
+  }
+  return postChatCompletion({
+    temperature,
+    timeoutMs,
+    retries,
+    messages: [
+      { role: 'system', content: system },
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text },
+          ...imageContent
+        ]
+      }
+    ]
+  });
+}

package/server/env.js

@@ -0,0 +1,4 @@
+import dotenv from 'dotenv';
+
+dotenv.config({ path: process.env.MATH_AGENT_ENV_FILE || '.env.local' });
+dotenv.config();