analyze-grade-distribution-aa/development/REQUIREMENTS.md

课程成绩异常诊断与报告生成 — 技能需求文档

派生自匠厂 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	匠厂	初版需求文档，骨架就位