Agentic-Class-Assistant

一个通用、交互式的课堂助手的 Gemini/Antigravity Skill。该工具旨在通过命令行界面（CLI）帮助教师和助教自动化班级作业管理，包含：下载作业包、使用大模型多模态能力直接批改原始 PDF/DOCX 文件、计算本地成绩单（Excel/CSV）中的统计数据以及将成绩同步至课堂派（课堂派 Mock）。

整个系统均提供完全的中文交互支持，并会用中文输出报告。

项目结构

Agentic-Class-Assistant/
├── .gitignore
├── README.md                    # 本文档
├── SKILL.md                     # Gemini/Antigravity Skill 配置文件
├── bin/
│   └── class_assistant.py       # 主交互式 CLI 工具 (中文交互)
├── src/
│   ├── __init__.py
│   ├── grading.py               # 作业文档解析与评分模块
│   ├── spreadsheet.py           # 成绩单电子表格管理模块
│   └── syncing.py               # 课堂派同步与下载 Mock 模块
├── tests/
│   ├── __init__.py
│   ├── test_grading.py          # 评分引擎单元测试
│   ├── test_spreadsheet.py      # 成绩单管理器单元测试
│   ├── test_syncing.py          # 同步模块单元测试
│   └── test_cli.py              # CLI 交互逻辑单元测试
└── tests_e2e/                   # 端到端黑盒/白盒测试套件
    ├── test_e2e_runner.py       # E2E 测试运行器
    └── test_cases/              # Tier 1-4 自动化测试用例

功能特点

1. 中文交互与提示：
   • 交互模式下，向用户请求确认关键参数（如：评分细则比重、目标文件、课堂会话 ID）。
   • 在需要用户手动操作时（例如从邮箱下载附件），输出详细且易读的中文提示信息。
   • 在向文件写入成绩或进行云端同步前，获取用户的明确确认。
2. 多模态评分：
   • 支持读取学生提交的 PDF 与 DOCX 作业，并使用预定义的评分标准 JSON 文件进行精确打分。
3. 成绩统计：
   • 自动更新成绩单，统计平均分、中位数、分段分数对应的人数等，并生成格式化的中文统计报告。
4. 测试覆盖率：
   • 包含单元测试与涵盖 Tier 1-4 的 E2E 自动化测试，确保整体交互逻辑与计算逻辑的健壮性。

快速使用

1. 交互模式

运行以下命令启动中文命令行向导：

python bin/class_assistant.py --class-id "physics_101" --rubric "rubric.json" --grades-file "grades.csv" --output-dir "submissions"

2. 非交互式 Dry-run 模式

在自动化测试或 CI 环境中进行空转测试：

python bin/class_assistant.py --dry-run

自动化测试

您可以使用 pytest 来运行包含在项目中的 112 个测试用例：

pytest