Initial commit

.gitea/workflows/autograde.yml

@@ -0,0 +1,233 @@
+name: autograde-assignment-02-grades
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'submit'
+      - 'submit-*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  check-trigger:
+    runs-on: docker
+    container:
+      image: alpine:latest
+    outputs:
+      should_run: ${{ steps.check.outputs.trigger }}
+    steps:
+      - name: Check commit message for trigger keyword
+        id: check
+        run: |
+          COMMIT_MSG="${{ github.event.head_commit.message || '' }}"
+          echo "Commit message: $COMMIT_MSG"
+          if echo "$COMMIT_MSG" | grep -q "完成作业"; then
+            echo "trigger=true" >> $GITHUB_OUTPUT
+            echo "✅ Commit contains \"完成作业\"，即将执行评分"
+          else
+            echo "trigger=false" >> $GITHUB_OUTPUT
+            echo "⛔ 只有包含"完成作业"的提交才会执行自动评分" >&2
+          fi
+
+  grade:
+    needs: check-trigger
+    if: needs.check-trigger.outputs.should_run == 'true'
+    runs-on: docker
+    container:
+      image: python:3.11
+      options: --user root
+    timeout-minutes: 20
+
+    steps:
+      - name: Configure APT mirror (Aliyun)
+        run: |
+          set -e
+          for f in /etc/apt/sources.list /etc/apt/sources.list.d/*.list /etc/apt/sources.list.d/*.sources; do
+            [ -f "$f" ] || continue
+            sed -i -E 's|https?://deb.debian.org|http://mirrors.aliyun.com|g' "$f" || true
+            sed -i -E 's|https?://security.debian.org|http://mirrors.aliyun.com/debian-security|g' "$f" || true
+            sed -i -E 's|https?://archive.ubuntu.com|http://mirrors.aliyun.com|g' "$f" || true
+            sed -i -E 's|https?://ports.ubuntu.com|http://mirrors.aliyun.com|g' "$f" || true
+          done
+          apt-get -o Acquire::Check-Valid-Until=false update -y
+          DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends git ca-certificates python3-pip rsync fonts-noto-cjk fonts-wqy-microhei
+          rm -rf /var/lib/apt/lists/*
+
+      - name: Checkout code
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          git config --global --add safe.directory ${{ github.workspace }}
+          git init
+          REPO_URL="${{ github.server_url }}/${{ github.repository }}.git"
+          AUTH_URL=$(echo "$REPO_URL" | sed "s|://|://${GITHUB_TOKEN}@|")
+          git remote add origin "$AUTH_URL"
+          git fetch --depth=1 origin ${{ github.sha }}
+          git checkout ${{ github.sha }}
+
+      - name: Fix permissions
+        run: chown -R $(whoami):$(whoami) ${{ github.workspace }} || true
+
+      - name: Fetch hidden tests and grading scripts
+        working-directory: ${{ github.workspace }}
+        env:
+          EXTERNAL_GITEA_HOST: ${{ secrets.EXTERNAL_GITEA_HOST }}
+        run: |
+          set -e
+          TESTS_USERNAME="${RUNNER_TESTS_USERNAME:-}"
+          TESTS_TOKEN="${RUNNER_TESTS_TOKEN:-}"
+          if [ -z "$TESTS_TOKEN" ] || [ -z "$TESTS_USERNAME" ]; then
+            echo "❌ RUNNER_TESTS_USERNAME / RUNNER_TESTS_TOKEN not set!"
+            exit 1
+          fi
+
+          # Resolve host
+          if [ -n "$EXTERNAL_GITEA_HOST" ]; then
+            HOST="$EXTERNAL_GITEA_HOST"
+          elif [ -n "$GITEA_ROOT_URL" ]; then
+            HOST=$(echo "$GITEA_ROOT_URL" | sed 's|https\?://||' | sed 's|/$||')
+          else
+            HOST=$(echo "${{ github.server_url }}" | sed 's|https\?://||' | cut -d'/' -f1)
+          fi
+
+          ORG=$(echo "${{ github.repository }}" | cut -d'/' -f1)
+          REPO_NAME=$(echo "${{ github.repository }}" | cut -d'/' -f2)
+
+          if echo "$REPO_NAME" | grep -q -- '-stu_'; then
+            ASSIGNMENT_ID=$(echo "$REPO_NAME" | sed 's/-stu_.*//')
+          elif echo "$REPO_NAME" | grep -q -- '-template'; then
+            ASSIGNMENT_ID=$(echo "$REPO_NAME" | sed 's/-template.*//')
+          else
+            ASSIGNMENT_ID="assignment-02-grades"
+          fi
+
+          echo "📥 Fetching tests from ${ORG}/${ASSIGNMENT_ID}-tests..."
+          AUTH_URL="http://${TESTS_USERNAME}:${TESTS_TOKEN}@${HOST}/${ORG}/${ASSIGNMENT_ID}-tests.git"
+          git -c http.sslVerify=false clone --depth=1 "$AUTH_URL" _priv_tests
+
+          rm -rf .autograde
+          mkdir -p .autograde
+          cp _priv_tests/autograde/*.py .autograde/
+          cp _priv_tests/autograde/*.sh .autograde/ 2>/dev/null || true
+          # Copy metadata scripts if available
+          if [ -f "_priv_tests/autograde/create_minimal_metadata.py" ]; then
+            cp _priv_tests/autograde/create_minimal_metadata.py .autograde/ 2>/dev/null || true
+          fi
+          if [ -f "_priv_tests/autograde/upload_metadata.py" ]; then
+            cp _priv_tests/autograde/upload_metadata.py .autograde/ 2>/dev/null || true
+          fi
+
+          # Copy Python tests
+          if [ -d "_priv_tests/python" ]; then
+            mkdir -p tests
+            rsync -a _priv_tests/python/ tests/
+            echo "✅ Private tests copied"
+          fi
+
+          # Copy test groups
+          if [ -f "_priv_tests/test_groups.json" ]; then
+            cp _priv_tests/test_groups.json .
+          fi
+
+          # Copy LLM rubrics
+          if [ -d "_priv_tests/llm" ]; then
+            mkdir -p .llm_rubrics
+            cp _priv_tests/llm/*.json .llm_rubrics/ 2>/dev/null || true
+          fi
+
+          rm -rf _priv_tests
+
+      - name: Install Python dependencies
+        run: |
+          pip config set global.index-url https://mirrors.aliyun.com/pypi/simple
+          pip install --no-cache-dir -r requirements.txt
+
+      - name: Run tests
+        working-directory: ${{ github.workspace }}
+        run: |
+          mkdir -p test-results
+          export PYTHONPATH="$(pwd):${PYTHONPATH}"
+          pytest --junitxml=test-results/junit.xml || true
+
+      - name: Grade programming tests
+        run: |
+          python ./.autograde/grade_grouped.py \
+            --junit-dir test-results \
+            --groups test_groups.json \
+            --out grade.json \
+            --summary summary.md
+
+      - name: Grade REPORT.md
+        run: |
+          if [ -f REPORT.md ] && [ -f .llm_rubrics/rubric_report.json ]; then
+            python ./.autograde/llm_grade.py \
+              --question "请评估这份反思报告" \
+              --answer REPORT.md \
+              --rubric .llm_rubrics/rubric_report.json \
+              --out report_grade.json \
+              --summary report_summary.md
+            echo "✅ REPORT.md graded"
+          else
+            echo '{"total": 0, "flags": ["missing_file"]}' > report_grade.json
+            echo "⚠️ REPORT.md or rubric not found"
+          fi
+
+      - name: Aggregate grades
+        run: |
+          python ./.autograde/aggregate_grade.py \
+            --programming grade.json \
+            --report report_grade.json \
+            --out final_grade.json \
+            --summary final_summary.md
+
+      - name: Create metadata
+        working-directory: ${{ github.workspace }}
+        env:
+          REPO: ${{ github.repository }}
+          LANGUAGE: python
+        run: |
+          if [ -f final_grade.json ]; then
+            # Use final grade type for aggregated grades
+            export GRADE_TYPE=final
+            export GRADE_FILE=final_grade.json
+            if [ -f .autograde/create_minimal_metadata.py ]; then
+              python ./.autograde/create_minimal_metadata.py > metadata.json || echo "{}" > metadata.json
+            else
+              echo "⚠️ create_minimal_metadata.py not found, skipping metadata creation"
+              echo "{}" > metadata.json
+            fi
+          fi
+
+      - name: Upload metadata
+        if: env.RUNNER_METADATA_TOKEN != ''
+        working-directory: ${{ github.workspace }}
+        env:
+          # 使用当前组织的 course-metadata 仓库
+          METADATA_REPO: ${{ github.repository_owner }}/course-metadata
+          METADATA_TOKEN: ${{ env.RUNNER_METADATA_TOKEN }}
+          METADATA_BRANCH: ${{ env.RUNNER_METADATA_BRANCH }}
+          STUDENT_REPO: ${{ github.repository }}
+          RUN_ID: ${{ github.run_id }}
+          COMMIT_SHA: ${{ github.sha }}
+          SERVER_URL: ${{ github.server_url }}
+        run: |
+          if [ -f metadata.json ] && [ -f .autograde/upload_metadata.py ]; then
+            python ./.autograde/upload_metadata.py \
+              --metadata-file metadata.json \
+              --metadata-repo "${METADATA_REPO}" \
+              --branch "${METADATA_BRANCH:-main}" \
+              --student-repo "${STUDENT_REPO}" \
+              --run-id "${RUN_ID}" \
+              --commit-sha "${COMMIT_SHA}" \
+              --workflow grade \
+              --server-url "${SERVER_URL}" \
+              --external-host "${EXTERNAL_GITEA_HOST}"
+          else
+            echo "⚠️ metadata.json or upload_metadata.py not found, skipping upload"
+          fi
+

.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+.pytest_cache/
+.autograde/
+.llm_rubrics/
+test-results/
+*.pyc
+*.pyo
+*.mp4
+*.csv
+!grades_normal.csv
+!grades_edge.csv
+.DS_Store
+grade*.json
+final_grade.json
+*.xml
+*.pdf
+metadata.json
+report_*.json

README.md

@@ -0,0 +1,24 @@
+# 作业 2：成绩统计分析器
+
+## 任务
+- 在 `src/grade_analyzer.py` 中完成 `GradeAnalyzer` 类：实现从 CSV 读取、统计分析、生成报告的功能。
+- 处理真实数据中的边界情况，如缺失值、无效分数、重复学号、文件编码问题等。
+- 通过公开测试与隐藏测试；提交 `REPORT.md` 反思报告。
+
+## 环境与依赖
+- Python 3.11+
+- 安装依赖：`pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple`
+
+## 本地运行
+```bash
+pytest -q
+```
+
+## 提交要求
+- 提交信息需包含关键字"完成作业"以触发评分。
+- 确保 `REPORT.md` 已填写。
+
+## 评分构成（总分 20）
+- Core 测试：10 分
+- Edge 测试：5 分
+- REPORT.md：5 分

REPORT.md

@@ -0,0 +1,47 @@
+# 作业 2 反思报告
+
+## 1. 设计决策
+
+在开始编码前，你需要做一些设计决策。请回答：
+
+- 你选择了什么数据结构来存储学生成绩？为什么这样选择？
+- 你考虑过其他方案吗？它们的优缺点是什么？
+
+> [在此处回答]
+
+## 2. 复杂需求的表达
+
+这个作业有一些"不那么直接"的需求，比如：
+- 并列排名的处理（两个 95 分应该怎么排？）
+- 缺失值的处理（空成绩是 0 分还是不参与计算？）
+
+你是如何向 AI 清晰表达这些需求的？请分享你的 prompt 策略或对话片段。
+
+> [在此处回答]
+
+## 3. 遇到的挑战
+
+在完成作业过程中，你遇到的最大挑战是什么？你是如何解决的？
+
+（可以是技术问题、与 AI 沟通的问题、理解需求的问题等）
+
+> [在此处回答]
+
+## 4. 代码质量与责任
+
+AI 生成的代码你直接用了吗？还是做了修改？
+
+- 如果做了修改，是什么样的修改？为什么？
+- 你是如何确保代码的正确性的？
+- 如果这段代码要交付给"客户"，你有信心吗？
+
+> [在此处回答]
+
+## 5. 反思与成长
+
+经过两次作业，你对"AI 辅助编程"的理解有变化吗？
+
+- AI 擅长什么？不擅长什么？
+- 作为程序员，你的价值在哪里？
+
+> [在此处回答]

grades_normal.csv

@@ -0,0 +1,6 @@
+学号,姓名,语文,数学,英语
+2024001,张三,85,92,78
+2024002,李四,76,88,82
+2024003,王五,90,95,88
+2024004,赵六,68,72,65
+2024005,钱七,92,95,90

requirements.txt

@@ -0,0 +1,3 @@
+pytest>=7.4
+python-dotenv>=1.0
+requests>=2.31

src/__init__.py

@@ -0,0 +1 @@
+

src/grade_analyzer.py

@@ -0,0 +1,217 @@
+"""
+成绩统计分析器
+
+你的任务是实现 GradeAnalyzer 类，从 CSV 文件读取学生成绩数据，进行统计分析并生成报告。
+
+功能要求：
+1. 从 CSV 文件加载学生成绩数据（学号、姓名、各科成绩）
+2. 计算各科目的平均分（需排除缺失值，不能将空值当作 0 分）
+3. 生成分数分布统计（优秀/良好/及格/不及格）
+4. 生成排名列表，需要处理并列情况（同分同名次，下一名跳过）
+5. 导出分析报告到新文件
+
+分数等级标准：
+- 优秀：90-100 分
+- 良好：80-89 分
+- 及格：60-79 分
+- 不及格：0-59 分
+
+输入数据格式（CSV）：
+学号,姓名,语文,数学,英语
+2024001,张三,85,92,78
+2024002,李四,76,88,82
+2024003,王五,90,95,88
+2024004,赵六,,80,75
+
+边界情况处理：
+- 缺失值：空单元格不应参与平均分计算，也不应视为 0 分
+- 无效分数：负数或超过 100 的分数应被识别或标记
+- 文件编码：可能需要处理 GBK/UTF-8 编码问题
+- 重复学号：同一学号出现多次的情况
+- 空文件：文件为空或只有表头的情况
+
+示例用法：
+analyzer = GradeAnalyzer()
+analyzer.load_csv("grades.csv")
+avg = analyzer.get_average("数学")  # 返回平均分
+dist = analyzer.get_distribution("语文")  # 返回 {'优秀': 2, '良好': 3, ...}
+ranking = analyzer.get_ranking("英语")  # 返回排名列表
+analyzer.export_report("report.txt")  # 导出报告
+
+提示：
+- 思考：用什么数据结构存储学生数据？list of dict? dict of dict?
+- 思考：并列排名如何处理？两个 95 分都排第 1，下一个 90 分排第 3（跳过 2）
+- 思考：缺失值如何表示？None? 空字符串？如何区分"0分"和"缺失"？
+- 可以让 AI 帮你设计代码结构，但你需要理解并验证每个部分
+"""
+
+import csv
+from typing import List, Dict, Optional
+
+
+class GradeAnalyzer:
+    """
+    成绩分析器
+    
+    从 CSV 文件读取学生成绩，提供统计分析功能。
+    """
+
+    def __init__(self):
+        """
+        初始化成绩分析器
+        
+        你需要决定如何存储学生数据。
+        建议：使用列表存储，每个元素是一个字典，包含学号、姓名、各科成绩。
+        """
+        self.students: List[Dict] = []
+        # TODO: 你可以添加其他属性来辅助实现
+
+    def load_csv(self, filepath: str) -> bool:
+        """
+        加载 CSV 文件
+        
+        从指定路径读取 CSV 文件，解析学生成绩数据。
+        需要处理：
+        - 文件编码问题（UTF-8 或 GBK）
+        - 缺失值（空单元格）
+        - 数据类型转换（字符串转数字）
+        
+        Args:
+            filepath: CSV 文件路径
+            
+        Returns:
+            bool: 是否加载成功
+            
+        提示：
+        - 可以使用 csv 模块或 pandas（如果允许）
+        - 缺失值可以存储为 None 或空字符串，但要能区分"0分"和"缺失"
+        - 建议先尝试 UTF-8，失败再尝试 GBK
+        """
+        # TODO: 在此实现你的代码
+        pass
+
+    def get_average(self, subject: str) -> float:
+        """
+        计算某科目平均分
+        
+        计算指定科目的平均分，排除缺失值。
+        例如：如果有 3 个学生，但只有 2 个有数学成绩，则用 2 个成绩计算平均。
+        
+        Args:
+            subject: 科目名称（'语文', '数学', '英语'）
+            
+        Returns:
+            float: 平均分，保留 2 位小数
+            
+        示例：
+            analyzer.get_average("数学")  # 返回 91.67
+        """
+        # TODO: 在此实现你的代码
+        pass
+
+    def get_distribution(self, subject: str) -> Dict[str, int]:
+        """
+        获取分数分布
+        
+        统计指定科目各等级的人数。
+        
+        Args:
+            subject: 科目名称
+            
+        Returns:
+            dict: 分数分布字典，格式如 {'优秀': 2, '良好': 5, '及格': 3, '不及格': 1}
+            
+        注意：
+        - 只统计有成绩的学生（排除缺失值）
+        - 如果某个等级没有人，该键也应存在，值为 0
+        """
+        # TODO: 在此实现你的代码
+        pass
+
+    def get_ranking(self, subject: str) -> List[Dict[str, any]]:
+        """
+        获取排名，处理并列情况
+        
+        返回指定科目的排名列表，按分数从高到低排序。
+        并列处理规则：
+        - 如果两个学生都是 95 分，他们并列第 1 名
+        - 下一个 90 分的学生排第 3 名（跳过第 2 名）
+        
+        Args:
+            subject: 科目名称
+            
+        Returns:
+            list: 排名列表，每个元素是一个字典，包含：
+                - 'rank': 排名（整数）
+                - 'id': 学号（字符串）
+                - 'name': 姓名（字符串）
+                - 'score': 分数（浮点数或整数）
+                
+        示例：
+            [
+                {'rank': 1, 'id': '2024003', 'name': '王五', 'score': 95},
+                {'rank': 1, 'id': '2024005', 'name': '钱七', 'score': 95},
+                {'rank': 3, 'id': '2024002', 'name': '李四', 'score': 90},
+                ...
+            ]
+            
+        注意：
+        - 只包含有成绩的学生（排除缺失值）
+        - 排名从 1 开始
+        """
+        # TODO: 在此实现你的代码
+        pass
+
+    def export_report(self, filepath: str) -> bool:
+        """
+        导出分析报告
+        
+        将统计分析结果导出到文本文件。
+        报告应包含：
+        - 各科目平均分
+        - 各科目分数分布
+        - 各科目排名（前几名）
+        
+        Args:
+            filepath: 导出文件路径
+            
+        Returns:
+            bool: 是否导出成功
+            
+        提示：
+        - 报告格式可以自由设计，但要清晰易读
+        - 可以使用中文
+        - 建议包含标题、分隔线等格式化元素
+        """
+        # TODO: 在此实现你的代码
+        pass
+
+
+if __name__ == "__main__":
+    # 测试你的实现
+    analyzer = GradeAnalyzer()
+    
+    # 加载测试数据（需要先创建 grades_normal.csv）
+    if analyzer.load_csv("grades_normal.csv"):
+        print("✅ CSV 加载成功")
+        print(f"学生数量: {len(analyzer.students)}")
+        
+        # 测试平均分
+        math_avg = analyzer.get_average("数学")
+        print(f"数学平均分: {math_avg:.2f}")
+        
+        # 测试分数分布
+        chinese_dist = analyzer.get_distribution("语文")
+        print(f"语文分数分布: {chinese_dist}")
+        
+        # 测试排名
+        english_ranking = analyzer.get_ranking("英语")
+        print(f"英语排名（前3名）:")
+        for item in english_ranking[:3]:
+            print(f"  第{item['rank']}名: {item['name']} ({item['score']}分)")
+        
+        # 导出报告
+        if analyzer.export_report("test_report.txt"):
+            print("✅ 报告导出成功")
+    else:
+        print("❌ CSV 加载失败")

tests/test_public.py

@@ -0,0 +1,51 @@
+"""
+公开测试 - 学生可见
+这些测试帮助你验证基本功能是否正确
+"""
+
+import pytest
+from src.grade_analyzer import GradeAnalyzer
+
+
+@pytest.fixture
+def sample_csv(tmp_path):
+    """创建测试用的 CSV 文件"""
+    content = """学号,姓名,语文,数学,英语
+2024001,张三,85,92,78
+2024002,李四,76,88,82
+2024003,王五,90,95,88"""
+    p = tmp_path / "test_grades.csv"
+    p.write_text(content, encoding='utf-8')
+    return str(p)
+
+
+def test_load_csv(sample_csv):
+    """测试能否成功加载 CSV 文件"""
+    analyzer = GradeAnalyzer()
+    result = analyzer.load_csv(sample_csv)
+    assert result == True
+    assert len(analyzer.students) == 3
+
+
+def test_get_average(sample_csv):
+    """测试平均分计算是否正确"""
+    analyzer = GradeAnalyzer()
+    analyzer.load_csv(sample_csv)
+    # 数学: (92 + 88 + 95) / 3 = 91.67
+    avg = analyzer.get_average("数学")
+    assert abs(avg - 91.67) < 0.1
+
+
+def test_get_ranking_structure(sample_csv):
+    """测试排名返回值的数据结构"""
+    analyzer = GradeAnalyzer()
+    analyzer.load_csv(sample_csv)
+    ranking = analyzer.get_ranking("英语")
+    
+    assert isinstance(ranking, list)
+    assert len(ranking) > 0
+    # 检查必要字段
+    first = ranking[0]
+    assert 'rank' in first
+    assert 'name' in first
+    assert 'score' in first