canvas-bulk-grading

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Canvas Bulk Grading

Canvas 批量评分

Grade Canvas LMS assignments efficiently using rubric-based workflows. This skill requires the Canvas MCP server to be running and authenticated with an instructor or TA token.

基于评分标准（Rubric）的工作流高效完成Canvas LMS作业评分。使用该功能需确保Canvas MCP服务器已运行，并通过讲师或助教的token完成身份验证。

Prerequisites

前置条件

Canvas MCP server running and connected
Authenticated with an educator (instructor/TA) Canvas API token
Assignment must exist and have submissions to grade
Rubric must already be created in Canvas and associated with the assignment (Canvas API cannot reliably create rubrics -- use the Canvas web UI for that)

Canvas MCP服务器已运行并完成连接
使用教育工作者（讲师/助教）的Canvas API token完成身份验证
作业已创建且存在待评分的提交内容
评分标准（Rubric）已在Canvas中创建并关联至该作业（Canvas API无法可靠创建评分标准，请使用Canvas网页端完成此操作）

Workflow

工作流

Step 1: Gather Assignment and Rubric Information

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

Before grading, retrieve the assignment details and its rubric criteria.

get_assignment_details(course_identifier, assignment_id)

Then get the rubric. Use

get_assignment_rubric_details

if the rubric is already linked to the assignment, or

list_all_rubrics

to browse all rubrics in the course:

get_assignment_rubric_details(course_identifier, assignment_id)
list_all_rubrics(course_identifier)
get_rubric_details(course_identifier, rubric_id)

Record the criterion IDs (often prefixed with underscore, e.g.,

_8027

) and rating IDs from the rubric response. These are required for rubric-based grading.

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

get_assignment_details(course_identifier, assignment_id)

随后获取评分标准。若评分标准已关联至作业，使用

get_assignment_rubric_details

；若需浏览课程内所有评分标准，使用

list_all_rubrics

：

get_assignment_rubric_details(course_identifier, assignment_id)
list_all_rubrics(course_identifier)
get_rubric_details(course_identifier, rubric_id)

记录评分标准响应中的准则ID（通常以下划线开头，例如

_8027

）和评分等级ID。这些是基于评分标准进行评分的必填项。

Step 2: List Submissions

步骤2：列出提交内容

Retrieve all student submissions to determine how many need grading:

list_submissions(course_identifier, assignment_id)

Note the

user_id

for each submission and the

workflow_state

(submitted, graded, pending_review). Count the submissions that need grading to determine which strategy to use.

获取所有学生的作业提交记录，确定待评分的数量：

list_submissions(course_identifier, assignment_id)

记录每份提交的

user_id

和

workflow_state

（已提交、已评分、待审核）。统计待评分的提交数量，以此选择合适的评分策略。

Step 3: Choose a Grading Strategy

步骤3：选择评分策略

Use this decision tree based on the number of submissions to grade:

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
|   ALWAYS run with dry_run: true first
|
+-- 30+ submissions OR custom grading logic needed
    Use execute_typescript with bulkGrade function
    99.7% token savings -- grading logic runs locally
    ALWAYS run with dry_run: true first

根据待评分的提交数量，参考以下决策树选择策略：

待评分的提交数量是多少？
|
+-- 1-9份提交
|   使用grade_with_rubric（每份提交调用一次）
|
+-- 10-29份提交
|   使用bulk_grade_submissions（并发批量处理）
|   设置max_concurrent: 5, rate_limit_delay: 1.0
|   必须先以dry_run: true模式运行
|
+-- 30+份提交 或 需要自定义评分逻辑
    使用execute_typescript调用bulkGrade函数
    可节省99.7%的令牌消耗——评分逻辑在本地运行
    必须先以dry_run: true模式运行

Strategy A: Single Grading (1-9 submissions)

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

Call

grade_with_rubric

once per student:

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
)

为每位学生单独调用

grade_with_rubric

：

grade_with_rubric(
  course_identifier,
  assignment_id,
  user_id,
  rubric_assessment: {
    "criterion_id": {
      "points": <number>,
      "rating_id": "<string>",    // 可选
      "comments": "<string>"      // 可选的准则级反馈
    }
  },
  comment: "Overall feedback"     // 可选的整体反馈
)

Strategy B: Bulk Grading (10-29 submissions)

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

Always dry run first. Build the grades dictionary mapping each user ID to their grade data, then validate before submitting:

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
)

Review the dry run output. If everything looks correct, re-run with

dry_run: false

必须先执行试运行。构建映射每个用户ID与对应评分数据的字典，验证无误后再提交：

bulk_grade_submissions(
  course_identifier,
  assignment_id,
  grades: {
    "user_id_1": {
      "rubric_assessment": {
        "criterion_id": {"points": 85, "comments": "分析出色"}
      },
      "comment": "整体反馈"
    },
    "user_id_2": {
      "grade": 92,
      "comment": "作业完成优秀"
    }
  },
  dry_run: true,          // 先验证
  max_concurrent: 5,
  rate_limit_delay: 1.0
)

查看试运行输出。若所有内容无误，再以

dry_run: false

模式重新运行。

Strategy C: Code Execution (30+ submissions)

策略C：代码执行（30+份提交）

For large classes or custom grading logic, use

execute_typescript

to run grading locally. This avoids loading all submission data into the conversation context.

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

  await bulkGrade({
    courseIdentifier: "COURSE_ID",
    assignmentId: "ASSIGNMENT_ID",
    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 } },
        comment: "Graded via automated review"
      };
    }
  });
`)

Use

search_canvas_tools("grading", "signatures")

to discover available TypeScript modules and their function signatures before writing code.

针对大班课或需要自定义评分逻辑的场景，使用

execute_typescript

在本地运行评分逻辑。此方式可避免将所有提交数据加载至对话上下文。

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

  await bulkGrade({
    courseIdentifier: "COURSE_ID",
    assignmentId: "ASSIGNMENT_ID",
    gradingFunction: (submission) => {
      // 自定义评分逻辑在本地运行——无令牌消耗
      const notebook = submission.attachments?.find(
        f => f.filename.endsWith('.ipynb')
      );

      if (!notebook) return null; // 跳过未评分内容

      return {
        points: 100,
        rubricAssessment: { "_8027": { points: 100 } },
        comment: "通过自动化审核完成评分"
      };
    }
  });
`)

在编写代码前，可使用

search_canvas_tools("grading", "signatures")

探索可用的TypeScript模块及其函数签名。

Token Efficiency

令牌效率

The three strategies have very different token costs:

Strategy	When	Token Cost	Why
`grade_with_rubric`	1-9 submissions	Low	Few round-trips, small payloads
`bulk_grade_submissions`	10-29 submissions	Medium	One call with batch data
`execute_typescript`	30+ submissions	Minimal	Grading logic runs locally; only the code string is sent. 99.7% savings vs loading all submissions into context

The key insight: as submission count grows, sending grading logic to the server (code execution) is far cheaper than bringing all submission data into the conversation.

三种策略的令牌消耗差异显著：

策略	适用场景	令牌消耗	原因
`grade_with_rubric`	1-9份提交	低	往返请求少，负载小
`bulk_grade_submissions`	10-29份提交	中	单次调用即可传输批量数据
`execute_typescript`	30+份提交	极低	评分逻辑在本地运行；仅需发送代码字符串。与将所有提交数据加载至上下文相比，可节省99.7%的令牌消耗

核心结论：随着提交数量增加，将评分逻辑发送至服务器（代码执行）比将所有提交数据带入对话的成本低得多。

Safety Rules

安全规则

Always dry run first. For
```
bulk_grade_submissions
```
, set
```
dry_run: true
```
before the real run. Review the output for correctness.
Verify the rubric before grading. Confirm criterion IDs, point ranges, and rating IDs match the assignment rubric. Mismatched IDs cause silent failures or incorrect grades.
Spot-check before bulk. For Strategy B and C, grade 1-2 submissions manually with
```
grade_with_rubric
```
first. Verify in Canvas that the grade and rubric feedback appear correctly.
Respect rate limits. Use
```
max_concurrent: 5
```
and
```
rate_limit_delay: 1.0
```
(1 second between batches). Canvas rate limits are approximately 700 requests per 10 minutes.
Do not grade without explicit instructor confirmation. Always present the grading plan (rubric mapping, point values, number of students affected) and wait for approval before submitting grades.

始终先执行试运行。对于
```
bulk_grade_submissions
```
，正式运行前需设置
```
dry_run: true
```
。检查输出内容是否正确。
评分前验证评分标准。确认准则ID、分数范围和评分等级ID与作业的评分标准匹配。不匹配的ID会导致静默失败或评分错误。
批量评分前抽查。对于策略B和C，先使用
```
grade_with_rubric
```
手动评分1-2份提交。在Canvas中验证分数和评分标准反馈是否正确显示。
遵守速率限制。设置
```
max_concurrent: 5
```
和
```
rate_limit_delay: 1.0
```
（批次间隔1秒）。Canvas的速率限制约为每10分钟700次请求。
无讲师明确确认不评分。始终提交评分计划（评分标准映射、分数值、受影响的学生数量），并在提交评分前等待批准。

Example Prompts

示例提示词

"Grade Assignment 5 using the rubric"
"Show me the rubric for the midterm project and grade all submissions"
"Bulk grade all ungraded submissions for Assignment 3 -- give full marks on criterion 1 and 80% on criterion 2"
"How many submissions still need grading for the final paper?"
"Dry run bulk grading for Assignment 7 so I can review before submitting"
"Use code execution to grade all 150 homework submissions with custom logic"

"使用评分标准为作业5评分"
"展示期中项目的评分标准并为所有提交内容评分"
"批量为作业3的所有未评分提交打分——准则1给满分，准则2给80%分数"
"期末论文还有多少份提交待评分？"
"为作业7执行批量评分试运行，以便我在提交前审核"
"使用代码执行为150份作业提交以自定义逻辑评分"

Error Recovery

错误恢复

Error	Cause	Action
401 Unauthorized	Token expired or invalid	Regenerate Canvas API token
403 Forbidden	Not an instructor/TA for this course	Verify Canvas role
404 Not Found	Wrong course, assignment, or rubric ID	Re-check IDs with `list_assignments` or `list_all_rubrics`
422 Unprocessable	Invalid rubric assessment format	Verify criterion IDs and point ranges match the rubric
Partial failures in bulk	Some grades submitted, others failed	Check the response for per-student status; retry only failed ones

错误	原因	解决措施
401 Unauthorized	Token过期或无效	重新生成Canvas API token
403 Forbidden	非该课程的讲师/助教	验证Canvas角色权限
404 Not Found	课程、作业或评分标准ID错误	使用 `list_assignments` 或 `list_all_rubrics` 重新检查ID
422 Unprocessable	评分标准评估格式无效	验证准则ID和分数范围是否与评分标准匹配
批量处理部分失败	部分评分提交成功，其他失败	检查响应中的学生个体状态；仅重试失败的评分