Homework Grading

---
name: homework-grading
description: 批改对分易教学平台上的学生作业。当用户要求批改作业、看还有哪些作业没批、或针对某次作业/某个学生打分写评语时使用。
---

# 对分易教学平台作业批改

通过五个 MCP 工具完成"读作业 → 对照标准 → 打分 → 写回"的完整批改闭环。用户只需一句自然语言，例如"批改高二三班今天的作业"，你需要自动完成整班逐份批改。

## 适用范围

- **只支持个人作业**。小组作业、学生互评作业、课程思政作业不在本连接器范围内，遇到时告知用户需在网页端处理。
- **只能访问当前密钥所属老师负责的课程和班级**。越权访问会被服务端拒绝。
- **批改结果不会自动通知学生**。写回后学生端不会收到通知，需老师自行在网页端确认并发送。

## 前置条件

用户须已在连接器配置页填入教师访问密钥。若工具返回"API Key 无效或已停用"，说明密钥错误或已被停用，请引导用户在网页端「课程下的作业管理 → AI批改 → MCP 访问密钥」重新生成后再连接。

## 标准批改流程

这是一个**有固定顺序的多步流程**，请严格按此执行：

```
1. list_pending_homework            取待批改列表（可按 class_id / date / course_id 缩小范围）
2. 从列表中识别出涉及哪些 homework_id（通常只有 1 个，也可能多个）
3. 对每个 homework_id 调一次 get_grading_criteria   ← 每个作业只调一次
4. 对每个 submission_id 依次：
     get_submission_detail  → 结合评分标准判分 → save_grade
5. 全部完成后，汇报批改份数与分数分布
```

**关键约束：`get_grading_criteria` 每个 homework_id 只调用一次。** 同一作业可能布置给多个班级、涉及几十份提交，但评分标准只有一份。拿到后所有学生复用，不要对每份提交都重新获取——这会浪费大量时间并可能触发限流。

### 大结果集的处理

`list_pending_homework` 返回 `truncated: true` 时说明结果被截断（上限 500 条），**只批改了返回的部分**。此时应提示用户用 `class_id` 或 `date` 缩小范围，分批继续，不要静默忽略。

## 工具说明

### 1. list_pending_homework

列出当前老师名下**待批改**的学生提交（状态为"已提交未批改"）。

**参数**（全部可选，都不传则返回全部）：

| 参数 | 类型 | 说明 |
|---|---|---|
| `course_id` | string | 课程 ID **令牌**，取自接口返回的 `course_id`（形如 `crs_xxxxxxxx`） |
| `class_id` | string | 班级 ID **令牌**，取自接口返回的 `class_id`（形如 `cls_xxxxxxxx`） |
| `date` | string | 提交日期，格式 `yyyy-MM-dd`，按学生**提交时间**筛选 |

用户说"今天的作业"时，传入今天的日期。用户说"高二三班的作业"时，先通过返回结果中的 `class_name` 匹配，或询问用户是哪个班。

**返回**：

```json
{
  "total": 37,
  "truncated": false,
  "id_note": "以上 *_id 字段均为不透明 ID 令牌，请原样回传，不要自行构造或替换成明文数字。",
  "items": [
    {
      "course_id": "crs_W8vWn4kL", "course_name": "高等数学",
      "class_id": "cls_W8vWX3GL", "class_name": "高二三班",
      "homework_id": "hw_BMvX57Gn", "homework_name": "第三章习题",
      "student_name": "张三", "idno": "20240101",
      "submission_id": "sub_gGPzjxkd",
      "submit_date": "2026-09-23 09:10:00"
    }
  ]
}
```

> **关于 ID 字段**：所有 `*_id` 都是**不可读的令牌**（如 `hw_BMvX57Gn`），不是数据库 ID。
> 它们由服务端生成，**只需原样回传**，不要去解析、拼接或改成数字 —— 传明文数字会被服务端拒绝。
> 返回结果里**没有** `student_id`，识别学生请用 `student_name` 和 `idno`（学号）。

`items` 为空且有 `message` 字段时，说明没有待批改的作业，直接告知用户即可，不要反复重试。

### 2. get_grading_criteria

取某次作业的**参考答案与评分标准**。一次批改任务中对同一 `homework_id` 只调一次。

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `homework_id` | string | 是 | 作业 ID **令牌**（形如 `hw_xxxxxxxx`），取自 `list_pending_homework` |

**返回**：

```json
{
  "homework_id": "hw_BMvX57Gn",
  "homework_name": "第三章习题",
  "description": "请完成第三章课后习题1-5题，写出完整推导过程。",
  "reference_answer": "第1题 x=2；第2题 3/4；……",
  "grading_criteria": "每题20分：思路正确12分，过程6分，答案2分。",
  "full_score": 100,
  "has_reference": true,
  "score_mode": "score"
}
```

两个必须处理的分支：

- **`has_reference: false`** — 老师尚未录入参考答案与评分标准。此时应依据 `description`（作业描述）和学科常识评分，并在评语中说明"本次为无标准参考评分"。**不要因为缺少标准就拒绝批改，也不要编造标准。**
- **`score_mode: "grade"`** — 该作业采用等级制，`score` 只能取 **100（优）/ 80（良）/ 60（及）** 三个值之一，不得输出其他分数。

### 3. save_grading_criteria

保存或修改某次作业的**参考答案与评分标准**。已有则覆盖，没有则新建。

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `homework_id` | string | 是 | 作业 ID **令牌**（形如 `hw_xxxxxxxx`） |
| `reference_answer` | string | 二选一 | 参考答案 |
| `grading_criteria` | string | 二选一 | 评分标准 |

`reference_answer` 与 `grading_criteria` **至少要填一个**，两个都空会被拒绝。

**返回**：

```json
{
  "success": true,
  "homework_id": "hw_BMvX57Gn",
  "homework_name": "第三章习题",
  "action": "updated",
  "reference_answer": "第1题 x=2；……",
  "grading_criteria": "每题20分：……",
  "full_score": 100
}
```

`action` 为 `created`（原本没有，本次新建）或 `updated`（覆盖了已有内容）。

**使用要点**：

- 这是**写操作，会直接影响后续批改结果**。调用前必须把要写入的内容读给老师确认。
- 只修改其中一项时，**另一项也要原样带上**（工具是整体覆盖，不是局部更新）。不传的字段会被清空 —— 例如只想改评分标准，那 `reference_answer` 也要把原值一起传进去。
- **本工具不能清空标准**。若确需清空，请引导老师到网页端「评分标准」操作（那里有二次确认）。
- 只能修改**该老师负责的课程**下的作业，越权会被拒绝。
- `full_score` 取自作业本身的满分设置，不可通过本工具修改。

### 4. get_submission_detail

取某个学生本次提交的全部内容。**必须先调用此工具拿到内容，再判分**，不要凭学生姓名或历史印象打分。

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `submission_id` | string | 是 | 提交 ID **令牌**（形如 `sub_xxxxxxxx`），取自 `list_pending_homework` 的 `submission_id` |

**返回**：

```json
{
  "submission_id": "sub_gGPzjxkd",
  "homework_id": "hw_BMvX57Gn",
  "homework_name": "第三章习题",
  "student_name": "张三",
  "idno": "20240101",
  "class_name": "高二三班",
  "submit_date": "2026-09-23 09:10:00",
  "text_answers": ["第1题 x=2。第2题我算得 3/4。……"],
  "attachments": [
    {
      "file_name": "作业扫描件.jpg",
      "file_url": "https://fs.duifene.com/hw/2026/09/abc123.pdf",
      "origin_url": "https://fs.duifene.com/hw/2026/09/abc123.jpg",
      "file_ext": ".jpg",
      "file_size": 204800
    }
  ]
}
```

- `text_answers` 是学生的文字作答，可直接阅读判分。
- `attachments` 中的 `file_url` 是可直接访问的链接（有 PDF 时优先给 PDF），需要读取其中的图片或文档内容再判分。
- 若 `text_answers` 为空且 `attachments` 也为空，说明学生未实际提交内容，**不要打分**，在汇报中单独列出该学生并提示老师核实。

### 5. save_grade

把一个学生的批改结果写回系统。调用后该提交标记为"已批改"。

**参数**：

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `submission_id` | string | 是 | 提交 ID **令牌**（形如 `sub_xxxxxxxx`） |
| `score` | int | 是 | **0–100 的整数**百分制分数 |
| `comment` | string | 是 | 文字评语 |

**返回**：

```json
{"success": true, "submission_id": "sub_gGPzjxkd", "score": 88,
 "comment": "第3题反证法思路正确但缺少关键步骤，扣12分；其余正确。",
 "previous_score": 0}
```

`previous_score` 非 0 表示这份作业**此前已被批改过，本次是覆盖**。若原始分数明显高于本次评分，请在汇报中提醒老师确认，避免误覆盖。

评语要求：**具体、可执行**，指出扣分点与改进方向，避免"很好""继续努力"这类空泛表述。评语过长会被截断（上限 1000 字）。

## 高风险操作与确认

本连接器有两个**写操作**，都会真实改动系统数据，执行前需谨慎：

### save_grade —— 写成绩

`save_grade` 会**真实写入作业成绩册**，学生和老师都可能看到：

1. **影响多人的批量批改**（例如整班几十份）在开始前，先用一句话向用户确认范围，例如"将为高二三班《第三章习题》的 37 份提交打分并写回，是否继续？"
2. **覆盖已批改的作业**（`previous_score` 非 0）需逐条提醒。
3. **单份批改**可直接执行，无需额外确认。
4. 一旦写入无法通过本连接器撤销，只能由老师在网页端重新批改。发现批错时，应提示老师在网页端核对修正。

### save_grading_criteria —— 写批改标准

`save_grading_criteria` 会改动**后续所有批改的依据**，影响面比单份成绩更大：

1. **必须先读后写**：先调 `get_grading_criteria` 取到当前内容，把要改成什么样讲清楚，**等老师明确同意后再写入**。
2. **覆盖已有标准时要点明**：如果该作业原本已有标准，明确告诉老师"将覆盖原有参考答案/评分标准"，不要静默覆盖。
3. **整体覆盖、不是局部更新**：只改一项时，另一项也必须把原值一起传，否则会被清空。写入前务必确认这一点。
4. 老师若想清空标准，引导他到网页端操作，本工具不支持清空。

## 常见错误与处理

| 错误信息 | 原因 | 处理方式 |
|---|---|---|
| `API Key 无效或已停用` | 密钥错误或被停用 | 引导用户重新生成密钥并重连 |
| `无权访问课程/班级 X` | 该课程/班级不在此老师名下 | 跳过该条，在汇报中说明；不要重试 |
| `分数必须在 0-100 之间` | 分数越界 | 修正分数后重新调用 |
| `提交 X 尚未提交作业，无法批改` | 学生未提交或已退回 | 跳过并告知用户 |
| `作业 X 不存在，或它不是个人作业` | 作业是小组作业/思政作业，或已删除 | 告知用户本连接器只支持个人作业 |
| `already_graded` | 该提交已批改且不允许覆盖 | 告知用户当前配置不允许重复批改 |
| HTTP 503 | 服务端数据库暂时不可用 | 稍后重试；持续失败则告知用户联系管理员 |

## 汇报格式

全部完成后，用简洁的中文汇报：

- 批改份数、涉及作业与班级
- 分数分布（如"最高 95，最低 52，平均 78"）
- 需老师关注的异常：未提交内容的学生、被覆盖的分数、被截断未批改的部分
- 提醒：学生端不会自动收到通知，需老师在网页端确认后发送

示例汇报：

> 已完成高二三班《第三章习题》的批改，共 37 份：
> - 平均分 78.4，最高 95（张三），最低 52（李四）
> - 王五本次未提交任何内容和附件，已跳过，请核实
> - 赵六此前已批改为 90，本次按标准评为 82，已覆盖，请确认是否需要恢复
>
> 提示：批改结果已写回，学生暂不会收到通知，需你在网页端确认后发送。