v1.0.1: 课程成绩异常诊断与报告生成 - 初版骨架
基于匠厂 skill-template 主仓 v1.0.108 派生的业务技能。 核心业务： - 教师在教务系统录完成绩后自动触发 - 统计指标计算 + 三种异常模式识别（高分低能 / 两极分化 / 挂科异常） - 生成三段式 AI 评语（总体 / 问题 / 建议） 输出形态： - HTML 报告（含统计表 + 正态分布图 + AI 评语） - 高风险课程自动标记 + 异常预警通知 预期提效：教师撰写成绩分析报告的时间从半天 → 10 分钟。 业务行生命周期：无（一次性报告存档，不重复处理） Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
144
TUTORIAL.md
Normal file
144
TUTORIAL.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# 使用教程
|
||||
|
||||
本技能有两种**平行**的使用方式：
|
||||
|
||||
- **数据管理**：在左侧「课程成绩」表上点工具栏 / 行内按钮
|
||||
- **对话任务**：用自然语言让 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 评语明显失真 | 可手动编辑后保存；评语仅供草稿参考 |
|
||||
|
||||
仍无法解决时，把「你用的入口 + 操作步骤 + 界面提示原文」发给支持人员。
|
||||
Reference in New Issue
Block a user