# 使用教程

本技能有两种**平行**的使用方式：

- **数据管理**：在左侧「课程成绩」表上点工具栏 / 行内按钮
- **对话任务**：用自然语言让 Agent 完成同一能力

定时任务是否提供：**见下方「入口三」**（当前为占位，按需启用）。

---

## 本技能做什么

```text
【课程成绩明细 + 教学大纲权重 + 历史成绩】 → 【统计指标计算 + 三种异常模式识别】 → 【AI 三段式评语】 → 【HTML 报告 + 高风险课程标记】
```

- **输入**：某门课程全班学生成绩明细 + 教学大纲（考核项权重）+ 前置课程历史成绩
- **输出**：HTML 报告（含统计表 + 正态分布图 + AI 评语）+ 异常预警通知
- **说明**：本技能不替代教学督导终审；AI 评语为草稿，教师修改后用于存档

---

## 开始前

确认：

1. 已安装并登录匠厂客户端
2. 已在技能市场安装本技能（建议更新到最新版）
3. 教务系统 API 凭证已配置（`AA_API_TOKEN` 已登记到本技能 `.env`）
4. 【如需】教师录完成绩后才能触发分析
5. 【如需】历史成绩数据已入库（首次使用需先在「数据管理 → 历史成绩」点击一次「立即同步」）

---

## 入口一：数据管理

适合：任课教师、教学督导、学院教学副院长。

### 左侧各表是干什么的

| 表名（中文） | 作用 |
|--------------|------|
| 课程成绩 | 各学期各课程成绩主表（含分析状态） |
| 分析报告 | 每次成绩分析的产物（含统计指标、AI 评语） |
| 历史成绩 | 该课程近 3 年的成绩数据（用于对比） |
| 高风险课程 | 被标记为高风险的课程列表 |

### 首次准备（若需要）

1. 进入 **数据管理** → **历史成绩**
2. 点击表顶 **「立即同步」**（空表可点）
3. 成功后应看到：本校该课程近 3 年的历史成绩数据

### 主流程：分析一门课程的成绩

1. 进入 **课程成绩**
2. 选中待分析的行 → 点击 **「分析这份成绩」**
3. 等待 10~30 秒（统计 + 异常识别 + AI 评语生成）
4. 完成后：
   - 分析报告表新增一行（含统计指标 + AI 评语）
   - 如触发预警，课程行状态变为「高风险」
   - 教学督导 / 学院教学副院长收到"高风险课程"通知

### 行级 / 批量

| 你想做什么 | 操作 |
|------------|------|
| 分析单门课程成绩 | **课程成绩** 行内 → **「分析这份成绩」** |
| 批量分析某学期所有课程 | 表顶 → **「批量分析本学期」** |
| 查看分析报告 | **分析报告** 行内 → **「查看报告」** |
| 标记为高风险 | **分析报告** 行内 → **「标记为高风险」** |
| 同步历史成绩 | **历史成绩** 表顶 → **「立即同步」** |

---

## 入口二：对话任务

适合：临时提问、不想切换表的用户。

### 什么时候用对话

- 临时想分析一份成绩，但不想打开数据管理
- 想用自然语言解释「为什么这份成绩被标为高风险」
- 想看「本学期一共多少门课程被标为高风险」

### 示例话术

| 你想做什么 | 可以这样说 |
|------------|------------|
| 分析一门课程 | 「帮我分析一下《高等数学 A》本学期的成绩」 |
| 批量分析 | 「请把本学期计算机学院所有课程都分析一遍」 |
| 查看报告 | 「《XX 课程》成绩分析报告出来了吗？」 |
| 解释预警 | 「为什么《XX 课程》被标为高风险？」 |
| 标记高风险 | 「把《XX 课程》标记为高风险」 |

### Agent 可能追问什么

- 缺参数时：「请告诉我课程名称 / 学期 / 课程 ID」
- 历史数据缺失时：「该课程历史成绩尚未同步，请先到数据管理同步」
- 失败时：可改用数据管理点按钮重新触发

---

## 入口三：定时任务

### 本技能当前为占位（按需启用）

本技能**当前未启用定时任务入口**。如未来启用，建议场景：

- 每学期末（考试结束后第 7 天）自动对全校课程做一次批量分析
- 历史成绩数据每日同步一次

启用条件：教务系统提供定时回调 API，并经教务处教学科确认自动化边界。

当前请使用 **数据管理** 或 **对话任务**。

---

## 主能力对照表

| 想做什么 | 数据管理 | 对话任务 |
|----------|----------|----------|
| 分析一门课程成绩 | **课程成绩** 行内 → **「分析这份成绩」** | 「帮我分析一下《XX》成绩」 |
| 批量分析 | 表顶 → **「批量分析本学期」** | 「请把本学期所有课程都分析一遍」 |
| 查看分析报告 | **分析报告** 行内 → **「查看报告」** | 「《XX 课程》报告出来了吗？」 |
| 标记高风险 | **分析报告** 行内 → **「标记为高风险」** | 「把《XX 课程》标记为高风险」 |
| 同步历史成绩 | **历史成绩** 表顶 → **「立即同步」** | 「同步一下历史成绩」 |

按钮名必须与 `assets/actions.json` 的 `label` 一致。

---

## 常见卡住怎么办

| 现象 | 你可以先试 |
|------|------------|
| 「分析这份成绩」点不了 | 是否已配置教务系统 API；是否装错版本 |
| 分析很久没结果 | 看任务中心进度；学生数 > 200 可能耗时较久 |
| 评分异常被标为高风险 | 检查历史成绩是否同步；阈值是否配置过高 |
| 历史成绩数据缺失 | 先到「数据管理 → 历史成绩」点击「立即同步」 |
| AI 评语明显失真 | 可手动编辑后保存；评语仅供草稿参考 |

仍无法解决时，把「你用的入口 + 操作步骤 + 界面提示原文」发给支持人员。