# local-teaching-agent

**Repository Path**: henhenhahi/local-teaching-agent

## Basic Information

- **Project Name**: local-teaching-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# minna-no-nihongo-agent

本项目是一个“人机协同导学”视域下的本地化教学智能体原型。第一阶段用《大家的日语 初级1 第6课》做小样本验证：ANN 小模型快速识别学生输入句子的语法点/学习标签，规则诊断层识别基础错误，本地 Ollama 模型 `gemma4:e4b` 生成中文教学解释、例句和小练习。

第一版只做 CLI，不做网页、不做数据库、不做多用户，目标是在 Mac mini M4 上完全离线运行。

## ANN 与 GNN 的分工

当前系统采用并行协作结构，而不是用 GNN 替换 ANN：

- ANN：负责句子级分类，把学生输入的日语句子识别为语法标签，例如 `地点へ行きます`。
- GNN learning graph：负责学生、知识点、错误、教材资源和练习之间的关系建模，用于学情诊断、知识追踪和练习推荐。
- Gemma：负责把 ANN 识别结果、规则诊断和 GNN 推荐转化为面向初学者的自然语言教学解释。

当前 GNN 是规则图传播 baseline：使用 `networkx + numpy` 构建本地学习图，依据错误次数、掌握度和先修关系计算 `risk_score`，生成可解释推荐。后续可以升级为 PyTorch Geometric 或 DGL 的真实 GNN，但第一版先保持离线、轻量、可解释。

## 诊断仲裁层

ANN 是快速初判，不再直接作为学情事实入档。一次分析会同时保留：

- `ann_label`：ANN 初步识别标签。
- `rule_diagnosis`：规则层诊断。
- `gemma_review`：Gemma 教学解释中的语义复核信号。
- `final_label`：最终进入学情档案和 GNN 的标签。
- `final_diagnosis`：最终进入错误复习队列的诊断。
- `archive_status`：`safe`、`conflict` 或 `needs_review`。

只有 `safe` 状态会自动更新 mastery、error_log、review_queue 和 GNN 图谱。`conflict` 与 `needs_review` 会写入：

```text
data/review/diagnosis_conflicts.csv
```

等待教师审核，不会自动进入正式错误复习队列。这样可以避免 ANN 把“わたしはがっこうにいます”误判为其他标签后污染学情统计和 GNN 推荐。

### 诊断冲突教师审核闭环

Web UI 的 `训练数据审核` 页签中包含 `诊断冲突审核` 区域，用来处理 `data/review/diagnosis_conflicts.csv` 中的记录。完整流程是：

```text
ANN 初判
→ Gemma/规则复核
→ safe 自动入档
→ conflict/needs_review 进入 diagnosis_conflicts.csv
→ 教师在 UI 审核
→ 审核后可生成候选训练样本
→ 训练数据审核
→ 应用到 training.csv
→ 重新训练 ANN
```

教师可以在网页中编辑 `final_label` 和 `final_diagnosis`，然后选择：

- `批准修正`：把冲突记录标记为 `approved`，并尝试生成一条 `pending` 候选训练样本。
- `忽略`：标记为 `ignored`，不进入训练候选。
- `继续观察`：标记为 `needs_more_review`，保留给后续判断。

批准修正不会直接写入 `data/training.csv`。它最多只会写入 `data/review/candidate_training_samples.csv`，仍然需要经过候选样本审核、approved 应用、重新训练 ANN 之后，模型才会吸收该经验。

`诊断冲突审核` 在训练数据审核页签中优先显示，排在普通候选样本审核之前。`conflict` 和 `needs_review` 代表模型或规则判断仍需要教师确认，应先处理这些记录，再批量处理普通候选样本。诊断冲突表和候选样本表都支持状态筛选、分页和每页数量选择，避免一次性展开过长列表。

相关命令：

```bash
python scripts/build_learning_graph.py --student default_student
python scripts/recommend_next.py --student default_student
```

输出：

```text
data/graphs/nodes.csv
data/graphs/edges.csv
data/graphs/learning_graph.json
data/graphs/recommendations.json
```

## 本机目录约定

项目放在：

```bash
/Users/wuhao/LocalProjects/Codex/macmini/local-teaching-agent/minna-no-nihongo-agent
```

选择 `/Users/wuhao/LocalProjects/Codex/macmini/` 是为了和已有本机工程保持一致，也便于把 Mac mini 作为本地算力与教学实验工作区管理。

不要放在 iCloud、桌面、文稿或网盘同步目录中开发，原因是：

- Python 虚拟环境和 TensorFlow 依赖文件很多，同步目录容易变慢。
- 模型文件、缓存文件、训练输出会频繁变化，容易触发不必要的云同步。
- 离线教学 Agent 的数据和模型应尽量留在本机，减少同步冲突和隐私风险。

## 创建虚拟环境

```bash
cd /Users/wuhao/LocalProjects/Codex/macmini/local-teaching-agent/minna-no-nihongo-agent
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
```

如果本机默认 `python3` 不是 3.11+，可改用 Homebrew Python：

```bash
/opt/homebrew/bin/python3.11 -m venv .venv
```

如果 Homebrew Python 遇到 PyPI 证书校验问题，可临时使用：

```bash
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org -r requirements.txt
```

## 训练 ANN

```bash
python scripts/train_ann.py
```

训练脚本使用：

- `TfidfVectorizer(analyzer="char", ngram_range=(1, 3))`
- TensorFlow/Keras 简单 ANN 分类器

输出文件：

```text
models/ann_model.keras
models/vectorizer.pkl
models/label_encoder.pkl
```

## 评估

```bash
python scripts/evaluate.py
```

评估会输出 accuracy、逐条预测结果和按 label 汇总。当前数据量很小，所以这是训练集内评估，只能验证流程是否跑通，不能代表真实泛化能力。

## ANN-only 测试

交互模式：

```bash
python scripts/chat_cli.py --ann-only
```

直接测试一句：

```bash
python scripts/chat_cli.py --ann-only --sentence 京都へ行きます
python scripts/chat_cli.py --ann-only --sentence 京都を行きます
python scripts/chat_cli.py --ann-only --sentence きのう何しましたか
```

## Ollama + gemma4:e4b 完整测试

先检查 Ollama：

```bash
ollama list
```

如果没有 `gemma4:e4b`，请执行：

```bash
ollama pull gemma4:e4b
```

完整模式：

```bash
python scripts/chat_cli.py
```

默认完整模式会使用 Ollama 流式输出，Gemma 内容会边生成边显示，减少等待整段回答返回的停顿感。

或直接测试一句：

```bash
python scripts/chat_cli.py --sentence 京都へ行きます
```

如需回退到旧的一次性输出模式：

```bash
python scripts/chat_cli.py --no-stream
```

如果未检测到 Ollama 或本地模型不可用，CLI 会自动降级为 ANN-only，并提示：

```text
未检测到 Ollama，当前使用 ANN-only 模式。
```

## 接入 data/raw_md/ 中的 MD 文件

把新的 `.md` 文件放入：

```text
data/raw_md/
```

然后运行：

```bash
python scripts/build_dataset.py
```

脚本会尝试从 Markdown 中提取包含日文字符的候选句子。如果 `data/training.csv` 已存在，不会覆盖原文件，而是写入：

```text
data/training.generated.csv
```

第一版只做简单抽取，生成后仍需要人工补充 `label`、`explanation`、`pattern`、`lesson` 字段。

## OCR/MD/JSON 教材导入

OCR 工具输出目录一般包含 `XX.md`、`XX.json` 和 `images/`。先把 OCR 输出临时放入 `data/imports/` 或其他本机非同步目录，再运行：

```bash
python scripts/import_ocr_package.py --source /path/to/ocr_output --subject japanese --course minna_no_nihongo --lesson 006
```

导入后会生成教材档案：

```text
data/materials/japanese/minna_no_nihongo/lesson_006/
├── material.json
├── source.md
├── source.json
├── vocabulary.csv
├── grammar.csv
└── sentences.csv
```

第一版抽取规则很简单：含「を」「へ」「に」「で」「ます」「ました」「ませんか」「ましょう」的行进入 `sentences.csv`；含“语法”“文法”“句型”“例文”的段落进入 `grammar.csv`；无法判断的内容先进入 `sentences.csv`，后续人工修正。

## 教材结构化解析

OCR 只能把教材变成文本，不能直接得到教学结构。结构化解析层会继续识别课次、单词、语法点、例句、会话、练习和 ANN 训练候选样本。当前以《大家的日语 初级1》第6课为起始案例：

```bash
python scripts/structure_textbook.py \
  --source data/raw_md \
  --subject japanese \
  --course minna_no_nihongo \
  --lesson 006
```

输出目录：

```text
data/structured/japanese/minna_no_nihongo/lesson_006/
├── structured_lesson.json
├── vocabulary.csv
├── grammar.csv
├── examples.csv
├── exercises.csv
├── training_candidates.csv
└── validation_report.md
```

验证结构化结果：

```bash
python scripts/validate_structured_lesson.py \
  --subject japanese \
  --course minna_no_nihongo \
  --lesson 006
```

把结构化候选样本追加到教师审核池：

```bash
python scripts/import_training_candidates.py \
  --subject japanese \
  --course minna_no_nihongo \
  --lesson 006
```

完整流程：

```text
OCR工具输出：XX.md / XX.json / images/
↓
structure_textbook.py
↓
structured_lesson.json
↓
validate_structured_lesson.py
↓
training_candidates.csv
↓
import_training_candidates.py
↓
teacher review
↓
approve_training_samples.py
↓
train_ann.py
```

注意：`training_candidates.csv` 的 `status` 默认为 `pending`，只进入 `data/review/candidate_training_samples.csv` 等待教师审核，不会直接写入 `data/training.csv`，也不会自动重新训练 ANN。

## 教材样本审核

从教材档案生成候选训练样本：

```bash
python scripts/build_training_from_materials.py
```

输出：

```text
data/review/candidate_training_samples.csv
```

学生错误和互动记录不会自动进入训练集。老师必须人工审核候选样本，整理为：

```text
data/review/approved_training_samples.csv
```

然后才能追加到正式训练集：

```bash
python scripts/approve_training_samples.py
```

脚本只追加审核通过的样本，并按 `text + label` 去重，不会直接覆盖 `data/training.csv`。

## 新增语法点的标准流程

推荐通过网页审核流程管理训练数据，不要长期直接手工修改 `data/training.csv`，除非是临时应急。

1. 导入教材/OCR/MD：

```bash
python scripts/import_ocr_package.py --source /path/to/ocr_output --subject japanese --course minna_no_nihongo --lesson 006
python scripts/structure_textbook.py --source /path/to/ocr_output --subject japanese --course minna_no_nihongo --lesson 006
python scripts/import_training_candidates.py --subject japanese --course minna_no_nihongo --lesson 006
```

2. 启动网页：

```bash
python web/app.py
```

3. 打开：

```text
http://127.0.0.1:7860
```

4. 在 UI 的“训练数据审核”区域检查 `data/review/candidate_training_samples.csv`。
5. 直接在网页里修改错误的 `text`、`label`、`pattern`、`explanation`。
6. 对确认无误的样本点击“批准”，样本会进入 `data/review/approved_training_samples.csv`。
7. 点击“应用 approved 到 training.csv”，审核通过的样本才会追加到 `data/training.csv`，并按 `text + label` 去重。
8. 点击“重新训练 ANN”。
9. 在网页顶部输入句子测试新语法点是否能被识别。

网页中还提供“临时新增语法点 / 练习样本”和“标签字典”区域。新增样本会先以 `pending` 状态进入候选池，不会自动加入训练集；新标签建议先写入 `data/label_registry.json`，方便后续用下拉框统一管理。

“自动规范化”会根据例句补全常见语法标签、句型和基础中文解释。例如只输入 `サントスさんは学生じゃありません`，系统会尝试补全为 `名词否定`、`NはNじゃありません`、`表示“不是……”。`。如果识别到新标签或重复样本，UI 会给出提示。

注意：新增语法点不会直接进入 ANN 训练集。它必须先进入 `candidate_training_samples.csv`，经教师审核进入 `approved_training_samples.csv`，再应用到 `data/training.csv`，最后重新训练 ANN，模型才会真正识别新语法。

## 推荐输入格式

规范 MD 和规范 CSV 可以走增量导入入口：

```bash
python scripts/incremental_import_knowledge.py \
  --source /path/to/increment \
  --subject japanese \
  --course minna_no_nihongo \
  --lesson 007 \
  --import-type auto \
  --import-action pending_only
```

`--import-action` 有三种：

- `pending_only`：仅进入候选池，等待审核。最安全，适合 OCR 原始文本。
- `auto_approve`：自动批准，但不训练。适合已整理好的规范 MD/CSV。
- `apply_and_train`：自动应用并重新训练。只建议用于教师确认无误的规范 CSV/MD。

不建议对未经检查的 OCR 结果直接使用 `apply_and_train`。

规范 MD 模板：

```markdown
# 第7课 これ・それ・あれ

subject: japanese
course: minna_no_nihongo
lesson: 007
title: これ・それ・あれ

## 语法点：これ／それ／あれ

label: 指示代词
pattern: これ／それ／あれ
explanation:
「これ」「それ」「あれ」作名词使用，用来指代物体。

examples:
- それは辞書ですか。|那是词典吗？

training:
- それは辞書ですか。|指示代词|これ／それ／あれ|「それ」指离听话人近的物体。

## 单词
- 辞書,じしょ,词典,名词
```

规范 training_increment CSV 模板：

```csv
text,label,pattern,explanation,lesson,subject,course,status
それは辞書ですか。,指示代词,これ／それ／あれ,「それ」指离听话人近的物体。,007,japanese,minna_no_nihongo,pending
```

必需字段：

```text
text,label,pattern,explanation,lesson,subject,course
```

可选字段：

```text
status,source_file,import_batch_id,timestamp
```

规范 vocabulary CSV 模板：

```csv
word,reading,meaning,part_of_speech,lesson,source
辞書,じしょ,词典,名词,007,lesson007.csv
```

导入时系统会备份原始文件到 `data/incremental_imports/raw_backup/{import_batch_id}/`，写结构化输出到 `data/structured/{subject}/{course}/lesson_{lesson}/`，写教材档案到 `data/materials/{subject}/{course}/lesson_{lesson}/`，再按导入后处理方式决定是否批准、应用和训练。

## 学生档案结构

默认学生档案位于：

```text
data/students/default_student/
├── profile.json
├── interaction_log.jsonl
├── error_log.csv
├── mastery.json
├── review_queue.json
└── progress.json
```

同时，每次学习会话也会写入：

```text
data/sessions/<session_id>.jsonl
```

CLI 默认记录学情，可指定学生和课次：

```bash
python scripts/chat_cli.py --ann-only --sentence 京都を行きます --student default_student --subject japanese --course minna_no_nihongo --lesson 006
```

如果只是临时测试、不想记录：

```bash
python scripts/chat_cli.py --ann-only --sentence 京都を行きます --no-log
```

当规则诊断发现错误时，会写入 `error_log.csv`，并加入 `review_queue.json`。无错误输入会更新 `mastery.json` 和 `progress.json`，但不会增加错误数。

## 错误巩固

复习待巩固错误：

```bash
python scripts/review_errors.py --student default_student
```

学生重做后会再次调用 ANN + 规则诊断。若没有诊断错误，记为一次正确复习；连续 2 次正确后，该错误在 `review_queue.json` 中标记为 `mastered`，并同步更新 `mastery.json` 和 `error_log.csv`。

## 学习进度续接

查看当前课次、最近学习时间、最需要巩固的标签和下一步建议：

```bash
python scripts/continue_learning.py --student default_student
```

## 学情报告

终端查看：

```bash
python scripts/student_report.py --student default_student
```

导出 Markdown：

```bash
python scripts/export_student_report.py --student default_student --format md
```

输出：

```text
data/students/default_student/report.md
```

## 本地 Web UI

第一版 UI 使用 Flask + 原生 HTML/CSS/JS，不使用复杂前端框架，仍然完全离线运行。

启动：

```bash
source .venv/bin/activate
python web/app.py
```

浏览器访问：

```text
http://127.0.0.1:7860
```

UI 包含：

- 学生输入区：学生 ID、学科、课程、课次、日语句子。
- 输出区：ANN 标签、置信度、基础解释、错误诊断、Gemma 教学解释。
- 学情摘要区：当前进度、总交互次数、高频错误、未掌握错误数、下一步建议。
- 错误复习区：读取 `review_queue.json` 中的错误和 mastered 状态。
- 教材资源区：查看已导入课程，选择课程后自动填充学科、课程和课次。
- GNN 学习路径推荐区：显示学习图节点数、边数、风险知识点和下一步练习建议。

也可以使用启动脚本：

```bash
scripts/run_ui.sh
```

## iPad 局域网访问方式

Mac mini 作为本地服务器，iPad 作为同一局域网中的客户端访问。启动方式：

```bash
cd /Users/wuhao/LocalProjects/Codex/macmini/local-teaching-agent/minna-no-nihongo-agent
scripts/run_lan.sh
```

脚本会显示 Mac mini 当前局域网 IP。请让 iPad 与 Mac mini 连接同一个 Wi-Fi，然后在 iPad Safari 打开：

```text
http://<Mac-mini-IP>:7860
```

也可以手动启动局域网模式：

```bash
source .venv/bin/activate
python3 web/app.py --host 0.0.0.0 --port 7860
```

添加到 iPad 主屏幕：

```text
Safari 分享按钮 → 添加到主屏幕
```

注意：不要把服务暴露到公网，只建议在家庭或办公室可信局域网使用。Gemma/Ollama 仍然运行在 Mac mini，iPad 只是客户端。

后续封装 macOS App 可参考：

```text
scripts/make_macos_launcher.md
```

### 多页签 ITS 工作台

当前 Web UI 已升级为多页签教学工作台，不再把所有功能堆在一个超长页面中：

1. `教学分析`：面向学生输入与即时反馈，集中显示 ANN 标签、置信度、规则诊断和 Gemma 教学解释，也保留教材资源选择与临时候选样本录入。
2. `学情与错误复习`：面向学习追踪，展示学习进度、总交互次数、高频错误、mastery、最近错误和 review_queue 中的复习项。
3. `GNN 学习路径推荐`：面向关系建模与推荐，刷新时会重新构建学习图并生成下一步学习重点，显示节点数、边数、风险知识点、先修链和推荐练习。
4. `训练数据审核`：面向教师控制层，优先显示 `data/review/diagnosis_conflicts.csv` 的诊断冲突审核，再显示 `data/review/candidate_training_samples.csv` 的普通候选样本审核。两个表格都支持状态过滤、分页和每页数量选择；普通候选样本支持批量 approve/ignore。approve 只写入审核池或 `approved_training_samples.csv`，不会直接进入 `data/training.csv`。
5. `标签字典`：从 `data/training.csv` 和候选样本汇总当前系统支持的 label，显示 pattern、example_count、lessons、例句、相关错误和 prerequisite。

页签切换在前端完成，不刷新页面；浏览器会尽量记住上一次停留的页签。

### 在 UI 中选择课程资源

页面加载后会自动读取：

```text
data/materials/
```

教材资源按 `subject / course / lesson` 展示，例如：

```text
japanese / minna_no_nihongo / lesson_006
```

点击某个课程资源后，UI 会自动填充学生输入区中的 `subject`、`course`、`lesson`，并显示 `source.md` 前 1000 字摘要，以及 `vocabulary.csv`、`grammar.csv`、`sentences.csv` 的条数。

### 基于教材例句的练习生成

`教学分析` 页签支持四种练习模式：

1. `自主输入`：学生直接输入日语句子，保持原有 ANN-only 和 Gemma 完整解释流程。
2. `中译日`：从所选教材课次中选择带中文 meaning 的例句，生成中文翻译题。
3. `纠错重写`：从教材例句生成常见错误句，例如把 `京都へ行きます` 改成 `京都を行きます`，学生需要重写正确表达。
4. `填空练习`：挖掉关键语法点，例如 `京都（　）行きます`。学生可以只输入 `へ`，也可以输入完整句 `京都へ行きます`。

使用方式：

1. 在左侧 `教材资源` 中勾选一个或多个课次，例如 `lesson_006` 和 `lesson_007`。
2. 在 `练习模式` 中选择中译日、纠错重写或填空练习。
3. 点击 `生成练习` 或 `使用所选课文生成练习` 开始一组练习。
4. 学生在原来的 `日语句子` 输入框中作答。
5. 点击 `ANN-only 诊断` 或 `Gemma 完整解释`。

练习模式在 UI 中采用紧凑按钮组，避免占用教学分析页的主要输入空间。生成第一题后，可以点击 `换一道题`，系统会在已勾选的教材资源中尽量避开刚出过的题；如果当前所选教材的可用题目已经轮换完，界面会提示“当前所选教材题目已轮换完，开始重复。”并允许继续练习。

练习生成依赖以下文件，按优先级读取：

```text
data/structured/{subject}/{course}/lesson_{lesson}/examples.csv
data/structured/{subject}/{course}/lesson_{lesson}/training_candidates.csv
data/materials/{subject}/{course}/lesson_{lesson}/sentences.csv
```

学生提交练习答案后，仍然走现有 ANN 识别、规则诊断、Gemma 解释、诊断仲裁和学情记录流程。`interaction_log.jsonl` 和 `data/sessions/` 会额外记录 `exercise_mode`、`exercise_prompt`、`expected_answer`、`source_sentence`、`source_lesson`、`target_label`、`target_pattern` 和 `answer_exact_match`，方便后续分析具体练习表现。

### 在 UI 中导入 OCR 工具输出目录

在“本机 OCR/教材目录路径”中输入本机目录，例如：

```text
/Users/wuhao/LocalProjects/Codex/macmini/local-ocr-dataset-builder/output/lesson6
```

然后点击“导入 OCR/MD 资源”。目录中应包含 `.md` 文件，可选包含 `.json` 和 `images/`。导入结果会保存到：

```text
data/materials/{subject}/{course}/lesson_{lesson}/
```

### 通过 UI 新增语法点

在“临时新增语法点 / 练习样本”中填写：

```text
例句 text
语法标签 label
句型 pattern
中文解释 explanation
学科 subject
课程 course
课次 lesson
```

可以先只填 `text`，点击“自动规范化”。系统会按内置规则自动补全常见标签，例如 `じゃありません`、`ませんか`、`ましょう`、`何をしましたか`、`ました`、`へ行きます`、`で...ます`、`をします`、`を...ます`。

点击“加入候选样本”后，样本只会写入：

```text
data/review/candidate_training_samples.csv
```

状态为 `pending`，不会直接进入正式训练集。如果要进入训练，仍然必须走：

```text
candidate_training_samples.csv → approved_training_samples.csv → data/training.csv
```

也就是先生成候选样本，再由老师审核通过，最后才追加到正式训练集。

## GitHub 备份

`.gitignore` 已排除 `.venv/`、`__pycache__/`、学生档案、会话日志、临时 OCR 导入目录和日志文件。不要提交 Ollama 模型或其他大模型文件。

如果 GitHub CLI 不可用，可手动推送：

```bash
git remote add origin git@github.com:finalfantasyxme/local-teaching-agent.git
git branch -M main
git push -u origin main
```

## 后续迁移到高中物理

迁移路径可以保持三层结构不变：

1. ANN 小模型：从“日语语法标签”替换为“物理概念标签”，例如匀变速直线运动、牛顿第三定律、受力分析、功和能。
2. 规则诊断层：从助词和句型错误替换为常见错因规则，例如把速度和加速度混淆、漏画重力、把作用力和反作用力画在同一物体上。
3. 本地 Ollama 教学解释：系统提示词从“日语初级教师”替换为“高中物理预学习导师”，要求输出概念解释、错因定位、反例、微练习。

数据层仍可沿用：

```text
text,label,explanation,pattern,lesson
```

其中 `pattern` 可改为知识点表达式、题型结构或错因模式，`lesson` 可改为章节编号。