canvas-bulk-grading

Canvas 批量评分

使用基于评分标准的工作流，高效批改 Canvas LMS 作业。此技能要求 Canvas MCP 服务正在运行，并已使用教师或助教令牌完成身份验证。

前提条件

• Canvas MCP 服务正在运行并已连接
• 已使用 教育工作者（教师／助教）Canvas API 令牌完成身份验证
• 作业必须已创建，并且有待批改的提交
• 必须已创建评分标准，并将其与作业关联，且设置 use_for_grading=true。创建时使用 create_rubric，关联现有评分标准时使用 associate_rubric；修改文本或分值时使用 update_rubric（先预览，再使用令牌进行第二次调用）；添加或移除评分标准项请在 Canvas 界面中操作。

工作流

步骤 1：收集作业和评分标准信息

评分前，获取作业详情及其评分标准项。

get_assignment_details(course_identifier, assignment_id)

接着获取评分标准。如果评分标准已关联到作业，请使用 get_rubric；如果要浏览课程中的所有评分标准，请使用 list_rubrics：

get_rubric(course_identifier, assignment_id=assignment_id)
list_rubrics(course_identifier)
get_rubric(course_identifier, rubric_id=rubric_id)

记录评分标准响应中的评分标准项 ID（通常以下划线为前缀，例如 _8027）和评级 ID。这些信息是基于评分标准评分所必需的。

步骤 2：列出提交

获取所有学生的提交，以确定需要批改的数量：

list_submissions(course_identifier, assignment_id)

记录每份提交的 user_id 和 workflow_state（submitted、graded、pending_review）。统计需要批改的提交数量，以确定使用哪种策略。

步骤 3：选择评分策略

根据需要批改的提交数量，使用以下决策树：

How many submissions need grading?
|
+-- 1-9 submissions
|   Use grade_with_rubric (one call per submission)
|
+-- 10-29 submissions
|   Use bulk_grade_submissions (concurrent batch processing)
|   Set max_concurrent: 5, rate_limit_delay: 1.0
|   Run with dry_run: true first (Safety Rule 1)
|
+-- 30+ submissions OR custom grading logic needed
    Use execute_typescript with bulkGrade function
    Grading logic runs locally; only selected output returns to the model
    Pass dryRun: true on the first run

策略 A：单份评分（1-9 份提交）

为每位学生调用一次 grade_with_rubric：

grade_with_rubric(
  course_identifier,
  assignment_id,
  user_id,
  rubric_assessment: {
    "criterion_id": {
      "points": <number>,
      "rating_id": "<string>",    // optional
      "comments": "<string>"      // optional per-criterion feedback
    }
  },
  comment: "Overall feedback"     // optional
)

策略 B：批量评分（10-29 份提交）

务必先进行试运行。 构建将每个用户 ID 映射到其评分数据的字典，然后在提交前进行验证：

bulk_grade_submissions(
  course_identifier,
  assignment_id,
  grades: {
    "user_id_1": {
      "rubric_assessment": {
        "criterion_id": {"points": 85, "comments": "Good analysis"}
      },
      "comment": "Overall feedback"
    },
    "user_id_2": {
      "grade": 92,
      "comment": "Excellent work"
    }
  },
  dry_run: true,          // VALIDATE FIRST
  max_concurrent: 5,
  rate_limit_delay: 1.0
)

检查试运行输出。如果结果看起来正确，请将 dry_run: false 后重新运行。

策略 C：执行代码（30 份及以上提交）

对于大型班级或自定义评分逻辑，请使用 execute_typescript 在本地运行评分。这可以避免将所有提交数据加载到对话上下文中。

execute_typescript(code: `
  import { bulkGrade } from './canvas/grading/bulkGrade.js';

  await bulkGrade({
    courseIdentifier: "COURSE_ID",
    assignmentId: "ASSIGNMENT_ID",
    dryRun: true,  // preview first; re-run with false after review
    gradingFunction: (submission) => {
      // Custom grading logic runs locally -- no token cost
      const notebook = submission.attachments?.find(
        f => f.filename.endsWith('.ipynb')
      );

      if (!notebook) return null; // skip ungraded

      return {
        points: 100,
        rubricAssessment: { "_8027": { points: 100 } }
        // No `comment` here on purpose -- see Safety Rule 6. Add one only when
        // the instructor asked for written feedback, and make it feedback.
      };
    }
  });
`)

编写代码前，使用 search_canvas_tools("grading", "signatures") 查找可用的 TypeScript 模块及其函数签名。

令牌效率

三种策略的令牌成本差异很大：

策略	适用情况	令牌成本	原因
grade_with_rubric	1-9 份提交	低	往返调用少，载荷较小
bulk_grade_submissions	10-29 份提交	中	一次调用即可发送批量数据
execute_typescript	30 份及以上提交	取决于工作量	评分逻辑在本地运行；只有代码和选定的输出需要进入模型上下文

关键在于：随着提交数量增加，将评分逻辑发送到服务端，比将所有提交数据载入对话更节省模型上下文。

安全规则

1. 始终先进行试运行。 对于 bulk_grade_submissions，实际运行前先设置 dry_run: true。检查输出是否正确。
2. 评分前核实评分标准。 确认标准 ID、分值范围和评级 ID 与作业评分标准一致。ID 不匹配会导致无提示的失败或错误评分。
3. 批量评分前抽查。 对于策略 B 和 C，先用 grade_with_rubric 手动评阅 1-2 份提交。确认评分和评分标准反馈在 Canvas 中正确显示。
4. 遵守速率限制。 使用 max_concurrent: 5 和 rate_limit_delay: 1.0（批次之间间隔 1 秒）。Canvas 的速率限制约为每 10 分钟 700 个请求。
5. 未经教师明确确认，不得评分。 始终先提供评分计划（评分标准映射、分值、受影响的学生人数），并等待批准后再提交评分。
6. 绝不要附上教师未要求的评论。 提交评论会在 SpeedGrader 中对学生可见；每次调用都会追加评论，而不是替换评论，并且无法撤回。“将分数设为 8”仅表示评分。绝不要生成复述分数或说明已进行评分的评论（例如“已通过自动审核评分”）——学生会把这类评论看作机器人对其作业的标记，而且没有任何反馈。只有教师要求书面反馈时才添加评论，并且评论内容应针对作业提供反馈。

示例提示词

• “使用评分标准为作业 5 评分”
• “向我展示期中项目的评分标准，并为所有提交评分”
• “为作业 3 的所有未评分提交批量评分——标准 1 给满分，标准 2 给 80% 分”
• “期末论文还有多少份提交需要评分？”
• “对作业 7 进行批量评分试运行，让我在提交前检查”
• “使用代码执行，通过自定义逻辑为全部 150 份家庭作业评分”

错误恢复

错误	原因	操作
401 Unauthorized	令牌已过期或无效	重新生成 Canvas API 令牌
403 Forbidden	不是此课程的教师或助教	核实 Canvas 角色
404 Not Found	课程、作业或评分标准 ID 错误	使用 list_assignments 或 list_rubrics 重新核对 ID
422 Unprocessable	评分标准评估格式无效	核实标准 ID 和分值范围是否与评分标准一致
批量操作部分失败	部分评分已提交，其他失败	检查每项状态。未经确认的评估可能已经保存：重试前先检查 Canvas，以免重复添加评论。仅重试已确认尚未保存的失败项