docs/COURSEWARE_AGENT.md

# AI Teacher Assistant Agent（Courseware）API

将原有教师端能力重构为**模块化 AI Teacher Assistant Agent**，基于「课程描述 + 辅助材料」与 RAG，生成全链路教学资源。所有生成内容均带 **Reference**。

## Reference 规范（技术约束）

- **本地 VDB（Weaviate / 上传文件）**：`[Source: Filename/Page]`
- **Web Search**：`[Source: URL]`

回答末尾包含 References 小节，或正文中按上述格式标注来源。

## 核心模块与 API

| 模块 | 路径 | 说明 |
|------|------|------|
| Course Vision & Structure Builder | `POST /api/courseware/vision` | 输入课程基本信息 + 教学大纲 → 课程定位、学习目标、层级化知识树 |
| Activity & Assignment Designer | `POST /api/courseware/activities` | 设计课堂活动、作业及 Rubric；支持从上传资料提取核心知识点（`rag_context_override`） |
| Teaching Copilot & Student Adaptation | `POST /api/courseware/copilot` | 课堂实时辅助；根据学生画像（Name, Progress, Behavior）动态调整建议 |
| Course QA Optimizer | `POST /api/courseware/qa-optimize` | 基于 Smart Quiz 答题数据分析弱点，输出教学优化建议 |
| Content Generator | `POST /api/courseware/content` | 生成 Markdown 详细教案 + 可用于 PPT 的结构化数据 |

- 状态：`GET /api/courseware/status`

## 请求/响应示例

### 1. Course Vision

```json
POST /api/courseware/vision
{
  "course_info": "IST345 生成式人工智能与负责任创新",
  "syllabus": "Week 1–5 基础；Week 6–10 应用与伦理。"
}

→ { "ok": true, "content": "...课程定位、学习目标、知识树...\n\n## References\n[Source: GenAICourses]", "weaviate_used": true }
```

### 2. Activities（可传入上传资料摘要）

```json
POST /api/courseware/activities
{
  "topic": "RAG 与检索增强",
  "learning_objectives": "理解 embedding、检索流程",
  "rag_context_override": "（可选）从上传文件 RAG 得到的摘要，覆盖 Weaviate 检索"
}
```

### 3. Teaching Copilot

```json
POST /api/courseware/copilot
{
  "current_content": "正在讲 Transformer 自注意力",
  "student_profiles": [
    { "name": "张三", "progress": "80%", "behavior": "积极提问" },
    { "name": "李四", "progress": "60%", "behavior": "沉默" }
  ]
}
```

### 4. QA Optimizer

```json
POST /api/courseware/qa-optimize
{
  "quiz_summary": "第 3 题正确率 45%，多数混淆了 encoder/decoder",
  "course_topic": "Transformer 与 Seq2Seq"
}
```

### 5. Content（教案 + PPT 数据）

```json
POST /api/courseware/content
{
  "topic": "Prompt Engineering",
  "duration": "1 课时",
  "outline_points": "Zero-shot, Few-shot, CoT"
}
```

## 代码结构

- `api/courseware/`：模块化实现
  - `prompts.py`：各模块独立 Prompt 模板
  - `references.py`：Reference 格式化（Filename/Page、URL）
  - `rag.py`：RAG 上下文 + 引用（Weaviate + 可选 Web）
  - `vision_builder.py`、`activity_designer.py`、`teaching_copilot.py`、`qa_optimizer.py`、`content_generator.py`
- `api/weaviate_retrieve.py`：新增 `retrieve_from_weaviate_with_refs()` 返回 `(text, refs)`
- `api/routes_courseware.py`：Courseware API 路由

## 与教师端原有接口的关系

- 原有 `api/teacher/*`（课程描述、文档建议、作业建议、评估分析）保留不变。
- `GET /api/teacher/status` 增加 `courseware_modules` 与 `courseware_base`，便于前端跳转或聚合展示。