analyze-grade-distribution-aa/TUTORIAL.md

使用教程

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

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

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

---

本技能做什么

【课程成绩明细 + 教学大纲权重 + 历史成绩】 → 【统计指标计算 + 三种异常模式识别】 → 【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 评语明显失真	可手动编辑后保存；评语仅供草稿参考

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