# 水利智学系统 · 本地AI全面升级 使用说明

> 升级日期：2026-09-29
> 核心能力：夜间智能调度 + 144专家AI需求 + 日常巡查分析 + 闪卡全量审核 + 跨模块一致性检查 + 自适应学习策略 + 学习数据分析 + 知识库优化 + 系统自愈建议

---

## 一、升级概览

本次升级为系统新增 **10项夜间自动运行的AI分析任务**、**4组API接口（共49个端点）**、**10张新数据库表**，以及一个全新的前端「AI智能中心」页面。所有AI分析均使用本地Ollama模型（qwen2.5:7b / deepseek-r1:7b），不依赖外部API。

### 新增功能清单

| # | 功能模块 | 说明 | 夜间自动运行 |
|---|---------|------|------------|
| 1 | 夜间智能调度器 | 22:00-06:00自动按优先级执行10项任务，白天休眠 | — |
| 2 | 144专家全量体检 | 复用现有专家系统，全量运行并缓存 | ✓ |
| 3 | RAG知识库优化 | 文档质量分析 + 知识缺口识别 | ✓ |
| 4 | 数据质量分析 | 空值/重复/孤立记录检查 + AI修复建议 | ✓ |
| 5 | 知识库摘要生成 | AI为长文档生成100字摘要（每夜≤100篇） | ✓ |
| 6 | 学习数据分析报告 | 错题规律 + 进度预测 + 综合学习报告 | ✓ |
| 7 | 日常巡查分析报告 | 8模块健康 + 专家异常 + deepseek-r1根因分析 | ✓ |
| 8 | 144专家AI需求汇总 | 每位专家提出AI功能改进需求，汇总排序 | ✓ |
| 9 | 系统自愈建议 | AI分析专家/健康中心/数据质量，生成修复方案 | ✓ |
| 10 | 闪卡全量AI审核 | 逐张审核闪卡正确性，标记错误/存疑 | ✓ |
| 11 | 跨模块一致性检查 | 题目-答案-解析 / 题库-闪卡 / 跨模块关联 | ✓ |
| 12 | 自适应学习策略 | 做题后实时分析 + 出题权重动态调整 + SM-2增强 | 手动/实时 |
| 13 | 题目智能分析 | 难度评估 + 错题归因 + 相似题聚类 | 手动 |

---

## 二、如何启动

### 1. 重启后端

由于修改了 `main.py` 和 `router_registry.py`，**需要重启后端服务**才能生效：

```
关闭当前后端窗口 → 双击 start.bat 重新启动
```

> 注意：后端进程可能因权限问题无法自动重启，请手动关闭后重新启动。

### 2. 确认Ollama运行

确保本地Ollama已启动并拉取了所需模型：
```bash
ollama list
# 应包含：qwen2.5:7b, deepseek-r1:7b, quentinz/bge-small-zh-v1.5
```

### 3. 访问AI智能中心

启动后端后，在浏览器中打开系统，侧边栏「智能训练分析」分组下点击 **「🤖 AI智能中心」** 即可进入。

也可直接访问API：`http://localhost:8000/api/night-ai/status`

---

## 三、夜间调度系统使用

### 自动模式（推荐）

后端启动后，夜间调度器自动运行守护线程：
- **运行窗口**：每天 22:00 - 次日 06:00
- **执行顺序**：按优先级10→100依次执行当天未完成的任务
- **防重复**：同一任务当天成功后自动跳过
- **资源保护**：CPU≥80%或内存≥90%时自动延迟执行
- **白天休眠**：非夜间时段每5分钟巡检一次，不执行任务

### 手动触发

通过AI智能中心页面的「🌙 夜间调度」标签页，可：
- 查看调度器状态和今日任务执行情况
- 点击「立即运行全部任务」一次性触发所有任务
- 单独触发某个任务
- 查看任务执行历史记录

或通过API：
```bash
# 查看状态
GET /api/night-ai/status

# 触发单个任务
POST /api/night-ai/trigger/expert_full_check

# 触发全部任务
POST /api/night-ai/trigger-all

# 查看执行历史
GET /api/night-ai/task-runs?limit=50

# 修改夜间窗口
PUT /api/night-ai/config  body: {"night_start_hour": 23, "night_end_hour": 5}
```

### 10项夜间任务说明

| 优先级 | 任务名 | 预计耗时 | 说明 |
|-------|--------|---------|------|
| 10 | expert_full_check | 15分钟 | 144专家全量体检 |
| 20 | rag_index_optimize | 20分钟 | 知识库文档质量+知识缺口 |
| 30 | data_quality_analysis | 10分钟 | 数据质量检查 |
| 40 | knowledge_summary | 30分钟 | 文档摘要生成（≤100篇） |
| 50 | learning_analysis_report | 15分钟 | 学习数据分析报告 |
| 60 | daily_patrol_report | 10分钟 | 日常巡查AI分析报告 |
| 70 | expert_ai_requirements | 25分钟 | 144专家AI需求汇总 |
| 80 | self_healing_analysis | 10分钟 | 系统自愈建议 |
| 90 | flashcard_audit | 60分钟 | 闪卡全量AI审核 |
| 100 | consistency_check | 30分钟 | 跨模块一致性检查 |

> 全部任务跑完约需3.5小时，完全在夜间窗口（8小时）内完成。

---

## 四、各功能模块详细使用

### 4.1 闪卡自动全量对错判断

**入口**：AI智能中心 → 「📇 闪卡审核」标签页

**功能**：
- AI（qwen2.5:7b）逐张审核闪卡：正面问题合理性、背面答案正确性、正反面逻辑一致性、事实性错误
- 标记为「正确/错误/存疑」，给出修正建议
- 支持断点续跑，批量处理每20张间隔0.5秒

**API**：
```bash
POST /api/ai-intelligence/flashcard/audit-start?limit=0   # 启动全量审核（limit=测试数量）
GET  /api/ai-intelligence/flashcard/audit-status           # 查看进度
GET  /api/ai-intelligence/flashcard/audit-results          # 审核结果列表
GET  /api/ai-intelligence/flashcard/audit-stats            # 统计概览
PUT  /api/ai-intelligence/flashcard/audit/{id}/fixed       # 标记已修正
```

### 4.2 跨模块一致性检查

**入口**：AI智能中心 → 「🔗 一致性检查」标签页

**三项检查**：
1. **题目-答案-解析一致性**：选择题答案是否在选项中、判断题答案格式、解析与答案是否一致（AI深度验证）
2. **题库-闪卡匹配**：按科目+章节匹配，识别有题无卡和有卡无题的知识缺口
3. **跨模块关联一致性**：题库/闪卡/思维导图/错题本的知识点覆盖度统计

**API**：
```bash
POST /api/ai-intelligence/consistency/question-answer   # 题目-答案-解析检查
POST /api/ai-intelligence/consistency/flashcard-match   # 题库-闪卡匹配
POST /api/ai-intelligence/consistency/cross-module      # 跨模块一致性
GET  /api/ai-intelligence/consistency/results           # 检查结果
GET  /api/ai-intelligence/consistency/report            # 汇总报告
```

### 4.3 做题后自适应策略调整

**入口**：AI智能中心 → 「🎯 自适应策略」标签页

**功能**：
- **做题后实时分析**：传入答题记录，AI（30秒超时）生成本次表现分析、薄弱知识点、下一步学习建议
- **出题权重动态调整**：薄弱知识点（掌握度<60%）权重×1.5，已掌握（>85%）权重×0.7
- **闪卡复习间隔AI增强**：基于SM-2算法，结合掌握度调整间隔（薄弱缩短20%，已掌握延长15%）
- **知识点掌握度追踪**：45个章节级掌握度矩阵，贝叶斯平滑计算
- **考试分数预测**：线性回归预测下次考试分数和通过概率

**API**：
```bash
POST /api/ai-intelligence/adaptive/analyze          # 做题后分析（body: {user_id, results:[{question_id,is_correct}]}）
GET  /api/ai-intelligence/adaptive/weights/{user_id}  # 出题权重
POST /api/ai-intelligence/adaptive/flashcard-interval # 闪卡间隔调整
GET  /api/ai-intelligence/adaptive/mastery/{user_id}  # 掌握度矩阵
GET  /api/ai-intelligence/adaptive/predict/{user_id}  # 分数预测
```

### 4.4 日常巡查分析报告

**入口**：AI智能中心 → 「📋 巡查报告」标签页

**功能**：
- 汇总健康中心8模块状态（正常/警告/错误数量）
- 专家体检异常项汇总
- 系统资源状态（DB表数、记录数、磁盘、Ollama模型）
- 数据变化趋势（对比昨日）
- **deepseek-r1:7b根因分析**：对异常项AI自动推断原因并给出修复建议
- 支持日报和周报

**API**：
```bash
POST /api/patrol/generate              # 生成今日报告
POST /api/patrol/generate-weekly       # 生成本周报告
GET  /api/patrol/reports?type=daily    # 报告列表
GET  /api/patrol/reports/{id}          # 报告详情
```

### 4.5 144名专家AI需求汇总

**入口**：AI智能中心 → 「🧠 专家AI需求」标签页

**功能**：
- 每位专家结合自身领域提出3-5条AI功能改进需求
- 144名专家共约500条需求，按优先级（高/中/低）排序
- 按专家分类统计，高优先级需求TOP列表
- 全量生成约需25分钟（144次Ollama调用，每专家间隔1秒）

**API**：
```bash
POST /api/patrol/expert-requirements/generate    # 启动全量生成（后台执行）
GET  /api/patrol/expert-requirements/status      # 生成进度
GET  /api/patrol/expert-requirements             # 聚合视图
GET  /api/patrol/expert-requirements/top?limit=20 # 高优先级TOP
GET  /api/patrol/expert-requirements/{expert_id}  # 按专家查询
```

### 4.6 学习数据分析

**入口**：AI智能中心 → 「📊 学习分析」标签页

**功能**：
- **错题规律分析**：按科目/章节/题型统计错题分布，识别薄弱知识点TOP10，AI分析错题原因
- **学习进度预测**：正确率变化曲线、学习时长趋势、通过概率预测（纯Python线性回归）
- **个性化学习报告**：综合分析+AI生成学习建议

**API**：
```bash
POST /api/ai-capabilities/learning/analyze-wrong   # 错题规律分析（body: {user_id}）
POST /api/ai-capabilities/learning/predict         # 进度预测
POST /api/ai-capabilities/learning/report          # 生成学习报告
GET  /api/ai-capabilities/learning/history         # 分析历史
```

### 4.7 知识库智能优化

**功能**：
- **文档质量分析**：19375篇文档的长度分布、空文档、过短文档（<50字）、标题重复检测
- **文档摘要生成**：AI为>500字的长文档生成100字摘要
- **知识缺口分析**：对比题库知识点和知识库覆盖度

**API**：
```bash
POST /api/ai-capabilities/kb/quality       # 文档质量分析
POST /api/ai-capabilities/kb/summarize     # 摘要生成（body: {limit: 100}）
POST /api/ai-capabilities/kb/gaps          # 知识缺口分析
GET  /api/ai-capabilities/kb/results       # 优化结果
```

### 4.8 系统自愈建议

**入口**：AI智能中心 → 「🩹 自愈建议」标签页

**功能**：
- **专家结果分析**：筛选体检失败/警告的专家，AI分析原因并生成修复建议
- **健康中心分析**：对8模块的error/warning/stale状态生成修复建议
- **数据质量分析**：关键表空值率、重复记录、孤立记录检查
- 建议按优先级排序，可标记已处理

**API**：
```bash
POST /api/ai-capabilities/healing/analyze-experts   # 分析专家结果
POST /api/ai-capabilities/healing/analyze-health    # 分析健康中心
POST /api/ai-capabilities/healing/analyze-data      # 分析数据质量
GET  /api/ai-capabilities/healing/suggestions       # 建议列表
PUT  /api/ai-capabilities/healing/{id}/done         # 标记已处理
```

### 4.9 题目智能分析

**功能**：
- **难度自动评估**：AI评级（1-5星）+ 历史正确率校准，回写difficulty字段
- **错题归因分析**：归因到6类（概念不清/计算错误/审题失误/记忆模糊/超纲/其他）
- **相似题聚类**：bigram Jaccard相似度≥0.8标记疑似重复

**API**：
```bash
POST /api/ai-intelligence/questions/assess-difficulty    # 难度评估
POST /api/ai-intelligence/questions/attribute-errors     # 错题归因
POST /api/ai-intelligence/questions/cluster              # 相似题聚类
GET  /api/ai-intelligence/questions/intelligence-results # 分析结果
```

---

## 五、文件清单

### 新建文件（17个）

**后端核心模块（11个）**：
| 文件 | 作用 |
|------|------|
| `backend/core/night_scheduler.py` | 夜间调度核心（单例、守护线程、资源保护、防重复） |
| `backend/core/night_task_wrappers.py` | 夜间任务包装器（10个无参任务入口） |
| `backend/core/expert_ai_requirements.py` | 144专家AI需求汇总 |
| `backend/core/daily_patrol_analysis.py` | 日常巡查AI分析报告 |
| `backend/core/ai_learning_analyzer.py` | 学习数据分析引擎 |
| `backend/core/ai_kb_optimizer.py` | 知识库智能优化 |
| `backend/core/ai_self_healing.py` | 系统自愈建议引擎 |
| `backend/core/ai_flashcard_auditor.py` | 闪卡全量AI审核 |
| `backend/core/ai_consistency_checker.py` | 跨模块一致性检查 |
| `backend/core/ai_adaptive_strategy.py` | 自适应学习策略（SM-2增强） |
| `backend/core/ai_question_intelligence.py` | 题目智能分析（难度/归因/聚类） |

**后端API路由（4个）**：
| 文件 | 前缀 | 端点数 |
|------|------|--------|
| `backend/api/v1/night_ai_routes.py` | /api/night-ai | 7 |
| `backend/api/v1/patrol_analysis_routes.py` | /api/patrol | 9 |
| `backend/api/v1/ai_capabilities_routes.py` | /api/ai-capabilities | 14 |
| `backend/api/v1/ai_intelligence_routes.py` | /api/ai-intelligence | 19 |

**前端（1个+目录）**：
| 文件 | 作用 |
|------|------|
| `frontend/modules/ai-intelligence/ai-intelligence-center.js` | AI智能中心前端页面（8个标签页） |

### 修改文件（4个）

| 文件 | 修改内容 |
|------|---------|
| `backend/main.py` | init_db()中新增夜间调度器启动 |
| `backend/api/router_registry.py` | 注册4组新API路由 |
| `frontend/index.html` | 引入AI智能中心JS + 模块映射 |
| `frontend/modules/layout/sidebar.js` | 侧边栏新增「AI智能中心」入口 |

### 新增数据库表（10张，自动创建）

| 表名 | 用途 |
|------|------|
| `night_task_runs` | 夜间任务执行记录 |
| `expert_ai_requirements` | 144专家AI需求 |
| `daily_patrol_reports` | 巡查分析报告 |
| `ai_learning_analysis` | 学习分析结果 |
| `ai_kb_optimization` | 知识库优化结果 |
| `ai_self_healing` | 自愈建议 |
| `flashcard_audit_results` | 闪卡审核结果 |
| `consistency_check_results` | 一致性检查结果 |
| `adaptive_strategy_results` | 自适应策略结果 |
| `ai_question_intelligence` | 题目智能分析结果 |

---

## 六、设计要点

1. **全本地AI**：所有AI分析走 `http://127.0.0.1:11434`，Ollama不可用时自动降级为规则化分析，不报错
2. **后台异步**：所有耗时操作（闪卡审核、专家需求生成等）均在 `threading.Thread(daemon=True)` 中执行，API立即返回batch_id
3. **结果持久化**：所有分析结果存SQLite，不依赖内存，重启不丢失
4. **断点续跑**：闪卡审核和一致性检查支持进度文件断点续跑
5. **资源保护**：夜间调度器执行前检查CPU/内存，过高时自动延迟
6. **容错设计**：单个任务异常不影响调度循环，单个专家/闪卡失败记录后继续
7. **语法验证**：全部17个Python文件通过 `py_compile` 验证，运行时冒烟测试通过

---

## 七、快速验证清单

重启后端后，按以下步骤验证升级生效：

- [ ] 侧边栏出现「🤖 AI智能中心」入口，点击可打开8个标签页
- [ ] `GET /api/night-ai/status` 返回10个已注册任务，全部显示「已实现」
- [ ] `GET /api/patrol/reports` 接口可访问（返回空列表或已有数据）
- [ ] `GET /api/ai-intelligence/flashcard/audit-stats` 接口可访问
- [ ] `POST /api/night-ai/trigger/daily_patrol_report` 可手动触发巡查报告生成
- [ ] 夜间22:00后调度器自动开始执行任务
- [ ] 任务执行记录出现在 `night_task_runs` 表中

---

*本文档随升级自动生成，如有疑问请参考各模块源码中的详细注释。*
