@zhouchangui/math-ati 0.1.0

package/.env.local.example

@@ -0,0 +1,6 @@
+AI_BASE_URL=https://code.shoestravel.xin
+AI_API_KEY=
+AI_MODEL=gpt-5.5
+IMAGE_BASE_URL=https://code.shoestravel.xin
+IMAGE_API_KEY=
+IMAGE_MODEL=gpt-image-2

package/AGENTS.md

@@ -0,0 +1,273 @@
+# AGENTS.md
+
+## Project Goal
+
+This project is a local Vite + Express MVP for personalized junior high math practice for 周子烊.
+
+The product goal is a chapter-level learning feedback loop:
+
+1. **章节知识验证**: select a chapter and understand which knowledge points exist and what the student currently appears to know.
+2. **盲点评估**: generate assessment papers, let the student complete them on paper, upload the completed result as PDF, grade it, and identify weak knowledge points.
+3. **盲点覆盖**: generate new targeted practice papers from those weak points, then repeat the same upload/grading/update loop.
+
+The UI should stay workflow-focused and simple. For a selected chapter, the right side should mainly show:
+
+- chapter mastery data and practice counts,
+- inline knowledge extraction status/actions, plus secondary-page entries for knowledge coverage, mistake repair, and configured ability assessment,
+- printable paper links,
+- PDF upload and grading progress,
+- grading summary, weak points, correction pack, and confirmation actions.
+
+Overview practice entry cards should navigate to the relevant secondary page. Knowledge extraction lives in the inline overview module and starts only after the user opens the extraction settings/confirmation flow. Do not start generation, upload, grading, or confirmation directly from overview cards. Ability state should be shown as a compact ability status panel and must not be mixed into the knowledge heat map.
+
+Avoid over-designing dashboards before the loop is reliable.
+
+## Architecture Principle: No Fallback Design
+
+The product should be designed as one complete, maintainable, well-structured system.
+
+- Do not add compatibility layers, silent fallbacks, rollback-style product paths, or hidden local substitutes.
+- When an API, data model, paper format, or workflow changes, use an explicit migration and update the project assets. Do not keep two product paths alive indefinitely.
+- If an external model call, preprocessing step, PDF grading step, or long-running job fails, expose a clear failed state with actionable progress/error details instead of fabricating usable results.
+- Frontend screens should not silently replace API data with bundled/demo data. They may show an explicit unavailable or setup-required state.
+- Diagnostic smoke paths may exist only for local verification, and they must not update mastery, mistakes, archive state, or product-facing learning records.
+- Initial knowledge extraction and re-extraction are different operations. Initial extraction creates chapter knowledge assets. Re-extraction changes the knowledge-point coordinate system and must reset that chapter's practice loop: generated practices, submissions, reports, generated coverage, mistake queue, mastery evidence, and ability assessment state restart from the newly extracted knowledge.
+
+## Current Architecture
+
+- Frontend: `src/main.jsx`, `src/styles.css`
+- API server: `server/index.js`
+- File store and data helpers: `server/fileStore.js`
+- Practice generation: `server/practiceService.js`, `server/practiceGenerator.js`, `server/practiceReviewer.js`
+- Practice rendering: `server/practicePaperHtml.js`
+- PDF grading pipeline: `server/pdfSubmissionGrader.js`
+- Knowledge feedback and reports: `server/knowledgeFeedback.js`
+- Ability assessment config and state: `server/abilityService.js`
+- Long-task job registry: `server/jobStore.js`
+- Agent prompts: `prompts/`
+- CLI scripts: `scripts/`
+
+Run locally:
+
+```bash
+npm run dev
+```
+
+If running separately:
+
+```bash
+npm run dev:server
+npm run dev:client
+```
+
+The Vite frontend runs on `127.0.0.1:5173`; the Express API defaults to `127.0.0.1:4173`.
+
+## Core Data Assets
+
+Global data:
+
+- `data/global/student_profile.json`: student profile.
+- `data/global/chapters.json`: 34 chapter list and chapter-level status.
+- `data/global/mastery_index.json`: cross-chapter mastery summary.
+- `data/global/mistakes_index.json`: cross-chapter mistake summary.
+- `data/global/ability_index.json`: derived cross-chapter ability assessment summary.
+
+Chapter-scoped data:
+
+- `data/chapters/<chapter-id>/chapter.json`: chapter metadata.
+- `data/chapters/<chapter-id>/knowledge/knowledge.json`: chapter knowledge-point dictionary.
+- `data/chapters/<chapter-id>/knowledge/knowledge.md`: readable knowledge document.
+- `data/chapters/<chapter-id>/mastery.json`: chapter knowledge-point mastery state.
+- `data/chapters/<chapter-id>/abilities.json`: configured chapter ability assessment state.
+- `data/chapters/<chapter-id>/mistakes.json`: chapter mistakes.
+- `data/chapters/<chapter-id>/practices/`: generated papers.
+- `data/chapters/<chapter-id>/submissions/`: PDF/photo submissions, grading artifacts, reports.
+- `data/chapters/<chapter-id>/reports/`: archived learning reports.
+- `data/chapters/<chapter-id>/context/`: generation history, coverage summaries, plans.
+- `data/chapters/<chapter-id>/context/generated_coverage.json`: first-round generated-paper coverage derived from knowledge coverage practice JSON. This is not mastery evidence.
+
+Long-lived project maps live under `.agents/story/` and must be kept current when behavior, data models, APIs, modules, architecture constraints, or coding standards change.
+
+## Practice Paper Format
+
+HTML is now the preferred paper format.
+HTML is the only supported practice paper format.
+
+Each generated practice should write:
+
+- `<practice-id>.json`: source of truth for questions, answers, rubrics, `knowledgePointIds`, and ability metadata when applicable.
+- `<practice-id>.html`: printable student paper.
+- `<practice-id>.answers.html`: printable answer/rubric sheet.
+
+Practice generation must not write Markdown paper files. UI and printing work must use `htmlUrl` / `answersHtmlUrl`.
+
+Practice JSON must preserve:
+
+- `questions[].id`
+- `questions[].stem`
+- `questions[].answer`
+- `questions[].solutionSteps`
+- `questions[].rubric`
+- `questions[].score`
+- `questions[].knowledgePointIds`
+- `questions[].knowledgePoints`
+- `questions[].expectedErrorTypes`
+- `questions[].abilityIds` for `ability_assessment`
+- `questions[].skillAtoms` for `ability_assessment`
+- `questions[].expectedAbilityErrors` for `ability_assessment`
+
+PDF grading must treat the active `practice.json` as the source of truth. The uploaded PDF only provides student answer evidence.
+
+## PDF Grading Loop
+
+The reusable service is:
+
+```js
+gradePdfSubmission({
+  practiceId,
+  pdfPath,
+  notes,
+  autoArchive,
+  forceArchive,
+  submissionId,
+  useAgent,
+  maxRechecks,
+  gradingBatchSize,
+  onProgress
+})
+```
+
+Pipeline:
+
+1. render PDF pages to PNG,
+2. extract visible answer fragments page by page,
+3. stitch answers by `questionId` across pages,
+4. grade in batches against practice answers and rubrics,
+5. run optional second-pass rechecks for uncertain items,
+6. write grading artifacts,
+7. confirm/archive only after trusted grading or explicit confirmation.
+
+Submission artifacts include:
+
+- `pages/page-*.png`
+- `page_extracts/page-*.json`
+- `stitched_answers.json`
+- `grading.json`
+- `knowledge_evidence.json`
+- `weak_points.json`
+- `positive_report.md`
+- `correction_pack.md`
+- `self_check.json`
+- `process_log.jsonl`
+
+`needs_review` should be minimized. If the first pass produces `needs_review`, the pipeline should attempt a focused second pass before leaving it for humans.
+
+## Web API Surface
+
+Baseline:
+
+- `GET /api/profile`
+- `GET /api/chapters`
+- `GET /api/settings/llm`
+- `PUT /api/settings/llm`
+- `GET /api/knowledge`
+- `GET /api/knowledge/:chapterId`
+- `POST /api/knowledge/:chapterId/extract`
+- `GET /api/practices`
+- `GET /api/practices/:id`
+- `POST /api/practices/generate`
+- `POST /api/practices/:id/submissions`
+- `POST /api/submissions/:submissionId/photos`
+- `GET /api/submissions/:id`
+- `POST /api/submissions/:id/confirm`
+- `GET /api/archive`
+
+Chapter workflow:
+
+- `GET /api/chapters/:chapterId/practices`
+- `GET /api/chapters/:chapterId/generated-coverage`
+- `GET /api/chapters/:chapterId/abilities`
+- `GET /api/chapters/:chapterId/submissions`
+- `GET /api/chapters/:chapterId/weak-points`
+- `POST /api/practices/:id/pdf-submissions`
+- `GET /api/submissions/:id/artifacts`
+- `GET /api/submissions/:id/artifacts/:name`
+
+Long tasks:
+
+- `POST /api/jobs/knowledge-extract`
+- `POST /api/jobs/practice-generate`
+- `GET /api/jobs/:jobId`
+- `GET /api/jobs/:jobId/events`
+
+Long-running operations must use job/progress APIs or equivalent UI progress. Do not make the frontend wait silently on long requests.
+
+LLM settings:
+
+- `GET /api/settings/llm` returns local inference endpoint, model, API-key presence, and `.env.local` path; it must never return the API key value.
+- `PUT /api/settings/llm` writes `AI_BASE_URL`, `AI_MODEL`, and optionally `AI_API_KEY` to `.env.local`, then updates the running server process environment so new model calls use the saved values without restart.
+- In packaged `math-ati start` mode, `.env.local` belongs to the user workspace and is passed through `MATH_AGENT_ENV_FILE`; do not write provider credentials into the installed package directory.
+
+`POST /api/practices/generate` and `POST /api/jobs/practice-generate` support `type: "ability_assessment"` with `abilityIds` for chapters that explicitly enable those abilities.
+
+The frontend derives flow records as `knowledge_coverage -> knowledge`, `mistake_repair -> mistake`, and `ability_assessment -> ability`. Ability assessment should reuse the same practice workspace, PDF upload, grading, and confirmation loop rather than creating a parallel workflow.
+
+## Long-Task UX Rules
+
+Practice generation, knowledge extraction, and PDF grading can be slow.
+
+Every web flow for those operations should show progress using `event.message`, for example:
+
+- `正在把 PDF 渲染成逐页图片`
+- `正在识别第 3/6 页作答`
+- `正在批改第 2/7 批：q6、q7、q8、q9、q10`
+- `正在生成批改文件、知识点证据、薄弱点和讲解包`
+
+The frontend should support polling `GET /api/jobs/:jobId` and, when useful, SSE via `GET /api/jobs/:jobId/events`.
+
+## Knowledge Feedback Rules
+
+Grading updates long-term learning state only after confirmation/trusted archive.
+
+Correct answers create positive evidence for linked knowledge points.
+Wrong, partial, unrecognized, or unresolved answers create weak-point evidence.
+Mistake repair uses `data/chapters/<chapter-id>/mistakes.json` as the active work queue. Each mistake should use `status: open|practicing|resolved|regressed`; default weak-point APIs should expose only actionable `open|regressed` mistakes.
+
+Confirmed `ability_assessment` submissions update `data/chapters/<chapter-id>/abilities.json` and `data/global/ability_index.json`. They should not update knowledge mastery directly, though wrong answers may still feed the mistake lifecycle through their linked knowledge points and error types.
+
+Important files:
+
+- `data/chapters/<chapter-id>/mastery.json`
+- `data/mastery.json`
+- `data/chapters/<chapter-id>/mistakes.json`
+- `data/chapters/<chapter-id>/abilities.json`
+- `data/mistakes.json`
+- `data/chapters/<chapter-id>/submissions/<submission-id>/weak_points.json`
+- `data/chapters/<chapter-id>/submissions/<submission-id>/knowledge_evidence.json`
+
+Generation for blind-spot repair should use `knowledgePointIds` from weak points when possible.
+
+## Development Guidelines
+
+- Keep the workflow simple until the chapter loop is reliable.
+- Prefer chapter-scoped data under `data/chapters/<chapter-id>/...`.
+- Keep server-side provider calls and secrets out of browser code.
+- Preserve existing file-based source of truth; do not introduce a database unless explicitly requested.
+- Do not add compatibility or fallback layers; prefer explicit migrations and one source of truth.
+- Use HTML for printable practice papers. Do not generate Markdown practice papers.
+- Use `process_log.jsonl` and job events for progress; do not rely only on console logs.
+- When adding or changing APIs, modules, data models, or workflow behavior, update `.agents/story/` as well as this file if the change affects future agents.
+
+## Upaseo Assets
+
+- `.paseo/` stores runtime plans, todos, handoffs, and recovery context only.
+- `.agents/story/` stores long-lived project assets.
+
+Story assets:
+
+- `.agents/story/stories.md`
+- `.agents/story/data_models.md`
+- `.agents/story/apis.md`
+- `.agents/story/modules.md`
+- `.agents/story/architecture_constraints.md`
+- `.agents/story/coding_standards.md`

package/README.md

@@ -0,0 +1,34 @@
+# Math ATI 加油站
+
+本包提供本地运行的数学 ATI 学习闭环：章节知识点覆盖、易错题修复、能力评估、纸质试卷打印、PDF 批改和掌握状态回写。
+
+## 安装与初始化
+
+```bash
+npm install -g @zhouchangui/math-ati
+mkdir my-math-ati
+cd my-math-ati
+math-ati init
+```
+
+初始化会创建本地 `data/` 和 `.env.local`。编辑 `.env.local`，填入 LLM 推理地址、模型和 API Key。
+
+```bash
+math-ati start --open
+```
+
+默认启动地址是 `http://127.0.0.1:4173`。
+
+## 常用命令
+
+```bash
+math-ati init [workspace]
+math-ati start [workspace] --open --port 4173
+math-ati doctor [workspace]
+```
+
+## 数据边界
+
+`data/` 是本地孩子档案、练习、批改和掌握状态，不会随 npm 包发布。包内只包含干净的初始化模板、服务端、前端构建产物和提示词。
+
+教材原始图片与完整课程资源应通过独立资源包安装到本地 workspace，再由 `MATH_AGENT_IMAGE_ROOT` 指向资源目录。

package/bin/math-ati.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access, cp, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const templateRoot = path.join(packageRoot, 'templates', 'workspace');
+
+function printHelp() {
+  console.log(`math-ati
+
+Usage:
+  math-ati init [workspace]
+  math-ati start [workspace] [--open] [--port 4173] [--data-dir <dir>] [--env-file <file>]
+  math-ati doctor [workspace] [--data-dir <dir>] [--env-file <file>]
+
+Commands:
+  init     Create a local workspace with clean data and .env.local template.
+  start    Start the local API and production web UI.
+  doctor   Print package, workspace, and configuration status.
+`);
+}
+
+function parseArgs(argv) {
+  const args = [];
+  const flags = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith('--')) {
+      args.push(item);
+      continue;
+    }
+    const key = item.slice(2);
+    if (['open', 'force', 'help'].includes(key)) {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = argv[index + 1];
+    index += 1;
+  }
+  return { args, flags };
+}
+
+async function exists(filePath) {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureWorkspaceTemplate() {
+  if (await exists(templateRoot)) return;
+  throw new Error(`workspace_template_missing:${templateRoot}`);
+}
+
+async function copyTemplateSafely(targetDir, options) {
+  await ensureWorkspaceTemplate();
+  await mkdir(targetDir, { recursive: true });
+  const stack = [''];
+  while (stack.length) {
+    const rel = stack.pop();
+    const sourceDir = path.join(templateRoot, rel);
+    const targetSubdir = path.join(targetDir, rel);
+    await mkdir(targetSubdir, { recursive: true });
+    const entries = await readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const source = path.join(sourceDir, entry.name);
+      const destination = path.join(targetSubdir, entry.name);
+      const childRel = path.join(rel, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(childRel);
+      } else if (options.force || !(await exists(destination))) {
+        await cp(source, destination, { force: true });
+      }
+    }
+  }
+}
+
+async function initWorkspace(argv) {
+  const { args, flags } = parseArgs(argv);
+  const workspaceDir = path.resolve(args[0] || process.cwd());
+  await copyTemplateSafely(workspaceDir, { force: Boolean(flags.force) });
+  const envLocal = path.join(workspaceDir, '.env.local');
+  const envExample = path.join(workspaceDir, '.env.local.example');
+  if (!(await exists(envLocal)) && (await exists(envExample))) {
+    await writeFile(envLocal, await readFile(envExample, 'utf8'), 'utf8');
+  }
+  console.log(`[math-ati.init] workspace=${workspaceDir}`);
+  console.log(`[math-ati.init] data=${path.join(workspaceDir, 'data')}`);
+  console.log('[math-ati.init] edit .env.local, then run: math-ati start --open');
+}
+
+function workspaceFromArgs(args) {
+  return path.resolve(args[0] || process.cwd());
+}
+
+function dataDirFromArgs(args, flags) {
+  return path.resolve(flags['data-dir'] || path.join(workspaceFromArgs(args), 'data'));
+}
+
+function envFileFromArgs(args, flags) {
+  return path.resolve(flags['env-file'] || path.join(workspaceFromArgs(args), '.env.local'));
+}
+
+function openBrowser(url) {
+  const command = os.platform() === 'darwin'
+    ? 'open'
+    : os.platform() === 'win32'
+      ? 'cmd'
+      : 'xdg-open';
+  const args = os.platform() === 'win32' ? ['/c', 'start', '', url] : [url];
+  const child = spawn(command, args, { stdio: 'ignore', detached: true });
+  child.unref();
+}
+
+async function startServer(argv) {
+  const { args, flags } = parseArgs(argv);
+  const port = String(flags.port || process.env.PORT || 4173);
+  const dataDir = dataDirFromArgs(args, flags);
+  const envFile = envFileFromArgs(args, flags);
+  const chaptersPath = path.join(dataDir, 'global', 'chapters.json');
+  if (!(await exists(chaptersPath))) {
+    throw new Error(`workspace_not_initialized:${dataDir}. Run "math-ati init" first.`);
+  }
+
+  const url = `http://127.0.0.1:${port}`;
+  const server = spawn(process.execPath, [path.join(packageRoot, 'server', 'index.js')], {
+    cwd: packageRoot,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      PORT: port,
+      MATH_AGENT_DATA_DIR: dataDir,
+      MATH_AGENT_ENV_FILE: envFile
+    }
+  });
+  if (flags.open) setTimeout(() => openBrowser(url), 900);
+
+  const stop = (signal) => {
+    if (!server.killed) server.kill(signal);
+  };
+  process.on('SIGINT', () => stop('SIGINT'));
+  process.on('SIGTERM', () => stop('SIGTERM'));
+  server.on('exit', (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    process.exit(code ?? 0);
+  });
+}
+
+async function doctor(argv) {
+  const { args, flags } = parseArgs(argv);
+  const dataDir = dataDirFromArgs(args, flags);
+  const envLocal = envFileFromArgs(args, flags);
+  const distIndex = path.join(packageRoot, 'dist', 'index.html');
+  console.log(JSON.stringify({
+    packageRoot,
+    dataDir,
+    hasData: await exists(path.join(dataDir, 'global', 'chapters.json')),
+    hasEnvLocal: await exists(envLocal),
+    hasBuiltUi: await exists(distIndex),
+    node: process.version
+  }, null, 2));
+}
+
+async function main() {
+  const [command = 'help', ...argv] = process.argv.slice(2);
+  if (command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+  if (command === 'init') {
+    await initWorkspace(argv);
+    return;
+  }
+  if (command === 'start') {
+    await startServer(argv);
+    return;
+  }
+  if (command === 'doctor') {
+    await doctor(argv);
+    return;
+  }
+  throw new Error(`unknown_command:${command}`);
+}
+
+main().catch((error) => {
+  console.error(`[math-ati.error] ${error.message}`);
+  process.exit(1);
+});