taojianmin
1d20cfa708
基于匠厂 skill-template 主仓 v1.0.108 派生的业务技能。 核心业务： - 教师在教务系统录完成绩后自动触发 - 统计指标计算 + 三种异常模式识别（高分低能 / 两极分化 / 挂科异常） - 生成三段式 AI 评语（总体 / 问题 / 建议） 输出形态： - HTML 报告（含统计表 + 正态分布图 + AI 评语） - 高风险课程自动标记 + 异常预警通知 预期提效：教师撰写成绩分析报告的时间从半天 → 10 分钟。 业务行生命周期：无（一次性报告存档，不重复处理） Co-Authored-By: Claude Code <noreply@anthropic.com>
183 lines
7.1 KiB
Markdown
183 lines
7.1 KiB
Markdown
# 课程成绩异常诊断与报告生成 — 技能需求文档
|
||
|
||
> 派生自匠厂 skill-template 主仓 `development/REQUIREMENTS.md`，对应规格书第 4.2 节「🟣 教务处 Skill 002 —— 成绩分析"异常诊断与报告生成"」。
|
||
|
||
---
|
||
|
||
## 0. 技能标识
|
||
|
||
- **拟定 slug（英文）**：`analyze-grade-distribution-aa`
|
||
- **中文 name**：课程成绩异常诊断与报告生成
|
||
- **中文 description（一句话）**：教师在教务系统录完成绩后，自动计算统计指标、识别"高分低能 / 两极分化 / 挂科异常"三种异常模式、生成三段式评语，输出图文并茂的《课程成绩分析报告》
|
||
- **account-manager platform_key（如有）**：N/A
|
||
- **命名形态**：标准型
|
||
- **目标 OEM 市场 `brands`（可选）**：未写则仅挂匠厂
|
||
- **网页 RPA（如有）— 登录策略**：**不适用**
|
||
|
||
## 0.1 宿主入口定位（必填）
|
||
|
||
| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 教程章节 | 不挂理由 |
|
||
|---------------------------|------|----------|------|----------|----------|
|
||
| `health` / `version` / `config-path` | 挂 | 不挂 | 不挂 | 入口二 | 默认必备 |
|
||
| `analyze-grade-distribution` | 挂 | row（课程成绩） | 不挂 | 入口一/入口二 | sync |
|
||
| `batch-analyze-courses` | 挂 | toolbar（课程成绩） | 不挂 | 入口一/入口二 | async |
|
||
| `render-html` | 挂 | row（分析报告） | 不挂 | 入口一/入口二 | sync |
|
||
| `flag-high-risk-course` | 不挂 | row（分析报告） | 不挂 | 入口一 | 写状态 |
|
||
| `sync-historical-grades` | 挂 | toolbar（历史成绩） | 挂（占位） | 入口一/入口三 | cron 占位 |
|
||
|
||
### 0.1.1 用户市场文档
|
||
|
||
- `README.md`：能力 / 场景 / 边界
|
||
- `TUTORIAL.md`：覆盖两入口，入口三写「占位」
|
||
|
||
## 0.2 AI + RPA 协作与授权边界
|
||
|
||
### Agent 设计
|
||
|
||
- 用户意图：分析单门课程 / 批量分析 / 查看报告 / 解释预警 / 标记高风险 / 同步历史成绩
|
||
- 意图 → Action 映射：
|
||
- 分析单门课程 → `analyze-grade-distribution`
|
||
- 批量分析 → `batch-analyze-courses`
|
||
- 查看报告 → `render-html`
|
||
- 标记高风险 → `flag-high-risk-course`
|
||
- 同步历史 → `sync-historical-grades`
|
||
- 缺参数追问：课程名称 / 学期 / 课程 ID
|
||
- 必须确认的动作：
|
||
- `batch-analyze-courses` 批量分析前确认范围与数量
|
||
- `flag-high-risk-course` 标记前提示推送对象
|
||
- 结果解释：成功（评分 + 异常模式 + 评语）、部分成功（评语生成失败但统计完成）、失败（历史数据缺失 → 仅做统计不预警）
|
||
|
||
### 授权与平台边界
|
||
|
||
- 教务系统 API 由教务处统一开通
|
||
- 学生个人成绩明细受教务系统权限控制，技能仅输出聚合统计与匿名分布
|
||
- 严禁逆向教务系统、破解私有协议
|
||
- 异常检测算法调参时停止并上报
|
||
|
||
### RPA 风控设计
|
||
|
||
- 执行端：**N/A**
|
||
|
||
## 0.3 业务行生命周期
|
||
|
||
本技能对「分析报告」无角色约束（一次性报告存档）。
|
||
|
||
---
|
||
|
||
## 1. 文档目标
|
||
|
||
本文档用于明确 `analyze-grade-distribution-aa` 的研发范围、交付标准、依赖关系和验收要求。
|
||
|
||
## 2. 业务背景
|
||
|
||
- **现状**：教师每学期末需撰写课程总结与成绩分析报告，平均耗时半天
|
||
- **痛点**：人工计算统计指标效率低；"高分低能 / 两极分化 / 挂科异常"难以识别；督导难以及时锁定高风险课程
|
||
- **目标**：自动完成「统计指标计算 + 三种异常识别 + AI 评语生成」，输出「HTML 报告 + 高风险课程标记」
|
||
|
||
## 3. 开发目标
|
||
|
||
- 拉取某课程全班成绩明细（平时分 / 期中分 / 实验分 / 期末分 / 总评）
|
||
- 拉取该课程的教学大纲（考核项权重）
|
||
- 拉取历史成绩数据（前置课程 / 同课程历史）
|
||
- 计算统计指标 + 正态分布 + 三种异常模式识别
|
||
- 生成 AI 三段式评语
|
||
- 输出 HTML 报告 + 异常预警通知
|
||
- 写入业务表（课程成绩 / 分析报告 / 历史成绩 / 高风险课程）
|
||
|
||
## 4. 功能范围
|
||
|
||
### 必须实现
|
||
|
||
- 支持 `python scripts/main.py health` / `version` / `config-path` / `init-db`
|
||
- 支持 `python scripts/main.py analyze-grade-distribution --course-id <id>`
|
||
- 支持 `python scripts/main.py batch-analyze-courses --semester-id <id>`（async）
|
||
- 支持 `python scripts/main.py render-html --report-id <id>`
|
||
- 支持 `python scripts/main.py flag-high-risk-course --report-id <id>`
|
||
- 支持 `python scripts/main.py sync-historical-grades`（async，cron 占位）
|
||
- 完成 §0.1 入口定位表
|
||
|
||
### 可后续扩展
|
||
|
||
- 多课程横向对比报告
|
||
- 学生个人学习轨迹预警
|
||
- 与学校教学质量监控平台对接
|
||
|
||
## 5. 非功能要求
|
||
|
||
- 目录结构符合 skill-template 规范
|
||
- 入口统一为 `scripts/main.py`
|
||
- 用户市场四 Tab
|
||
- 输出机读友好；错误前缀 `ERROR:`
|
||
- Windows UTF-8 兼容
|
||
- 单门课程分析耗时 ≤ 30 秒（学生数 ≤ 200）
|
||
|
||
## 6. 输入输出要求
|
||
|
||
### 输入
|
||
|
||
- `course_id`：课程主键（必填）
|
||
- `semester_id`：学期主键（仅 batch 必填）
|
||
- `report_id`：报告主键（仅 render / flag 必填）
|
||
- 依赖系统：教务系统 API（成绩读写）
|
||
- 环境变量（`.env`）：
|
||
- `AA_API_BASE_URL`：教务系统 API 入口
|
||
- `AA_API_TOKEN`：调用凭证
|
||
- `HIGH_FAIL_RATE_THRESHOLD`：挂科异常阈值（默认 0.30）
|
||
- `SCORE_GAP_THRESHOLD`：高分低能阈值（默认 20）
|
||
- `STD_DEV_RATIO_THRESHOLD`：两极分化阈值（默认 1.5）
|
||
|
||
### 输出
|
||
|
||
- 成功结果：`analyze-grade-distribution` 返回 `{max_score, min_score, avg, median, std, pass_rate, excellent_rate, anomaly_flags, ai_comment}`
|
||
- 错误输出：`ERROR:` 稳定码 + 中文 message
|
||
- 数据库记录：写入 `分析报告` 表
|
||
- HTML 报告：落到 `html/`
|
||
|
||
## 7. 依赖的兄弟技能或外部系统
|
||
|
||
### 兄弟技能依赖
|
||
|
||
- 无强制依赖
|
||
|
||
### 外部系统依赖
|
||
|
||
- **教务系统 API**（成绩读写）：必须
|
||
|
||
### Python 包依赖（requirements.txt）
|
||
|
||
- HTTP 请求：`requests>=2.31.0,<3`
|
||
- 数值计算：`numpy>=1.24.0,<2`
|
||
- 数据处理：`pandas>=2.0.0,<3`
|
||
- 统计可视化（图表占位）：`matplotlib>=3.7.0,<4`
|
||
- `jiangchang-platform-kit` 由宿主提供
|
||
|
||
## 8. 不在本次范围内的内容
|
||
|
||
- 本次不实现学生个人学习轨迹预警
|
||
- 本次不集成教学质量监控平台
|
||
- 本次不做 cron 启用（占位 Action 已就位）
|
||
- 本次不兼容旧模板历史结构
|
||
|
||
## 9. 验收标准
|
||
|
||
- 代码结构符合模板规范
|
||
- `health` / `version` / `config-path` / `init-db` 命令执行正常
|
||
- `analyze-grade-distribution` 在含 100 门课程的样例库中完成一次分析，耗时 ≤ 30 秒
|
||
- 业务表写入和查询符合 `references/SCHEMA.md`
|
||
- 异常识别准确率 ≥ 90%（基于样例库）
|
||
- `SKILL.md` 的 `developer_ids` 已配置
|
||
- 安装后按 §0.1 完成宿主多入口验收
|
||
|
||
## 10. 开发注意事项
|
||
|
||
- 只修改当前 skill 仓库
|
||
- 学生个人成绩明细受教务系统权限控制
|
||
- 异常检测阈值可在 `runtime/config` 调参
|
||
- `cli` 只做参数解析；核心逻辑在 `service`
|
||
|
||
## 11. 变更记录
|
||
|
||
| 日期 | 版本 | 变更人 | 变更内容 |
|
||
|------|------|--------|----------|
|
||
| 2026-09-14 | v1.0.1 | 匠厂 | 初版需求文档，骨架就位 |
|