# 输入数据格式（元镜 yotta-mirror）

## 一、成绩 / 答题表（CSV / TSV）

- 首行必须是表头，**第一列 = 学生标识**（姓名或学号均可，列名不限）；
- 其余列名 = 题目 id，必须与题目映射中的 `id` 完全一致（大小写敏感）；
- 单元格 = 该题得分；判定题写 `0` / `1`；留空表示缺失；
- 支持逗号分隔与制表符分隔（按表头自动识别）、UTF-8（含 BOM）、CRLF 与 LF；
- 空的整行会被跳过；列数与表头不一致会报错。

示例：

```csv
student,T1,T2,T3
S01,5,3,2
S02,5,3,
```

## 二、题目-知识点映射（JSON，必填）

```json
{
  "schema_version": "1.0",
  "items": [
    {"id": "T1", "max_score": 5, "knowledge": ["有理数运算"], "difficulty": "easy"},
    {"id": "T2", "max_score": 3, "knowledge": ["有理数运算", "计算"]}
  ]
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `id` | string | 是 | 题目 id，必须与成绩表列名一致，不可重复 |
| `max_score` | number | 是 | 该题满分，必须为正数 |
| `knowledge` | string[] | 是 | 该题关联的知识点（可多个，聚合按分值加权） |
| `difficulty` | string | 否 | `easy` / `medium` / `hard`，仅用于分组展示 |

## 三、阈值配置（JSON，可选）

```json
{
  "schema_version": "1.0",
  "mastery": {"weak_below": 0.6, "solid_at_or_above": 0.8},
  "layers": {"a_at_or_above": 0.85, "b_at_or_above": 0.7},
  "min_respondents": 3,
  "critical_margin": 0.05
}
```

| 字段 | 默认 | 说明 |
|---|---|---|
| `mastery.weak_below` | 0.6 | 掌握率低于该值判为薄弱（必须小于 `solid_at_or_above`） |
| `mastery.solid_at_or_above` | 0.8 | 掌握率不低于该值判为掌握 |
| `layers.a_at_or_above` | 0.85 | 学生分层 A 档下限 |
| `layers.b_at_or_above` | 0.7 | 学生分层 B 档下限（必须小于 A 档下限） |
| `min_respondents` | 3 | 样本量下限；低于该值的统计降级为人工复核项 |
| `critical_margin` | 0.05 | 距分界线在该范围内标记为临界生（百分点小数） |

## 四、常见报错对照

| 提示 | 原因 | 处理 |
|---|---|---|
| `表格列不在题目映射中：T9` | 表头多出未声明题目 | 补进映射，或删除该列 |
| `题目映射声明但表格缺失的题目：T2` | 映射里有题，表里没有列 | 补列，或从映射移除 |
| `学生标识重复：S01` | 同一学生出现多行 | 合并为一行后再分析 |
| `题目 T1 不是数字：'好'` | 单元格含非数值内容 | 改为分值或留空 |
| `得分 6 超出范围（0 - 5）` | 超过该题满分 | 核对分值或 `max_score` |
| `缺失单元格` | 有留空 | 确认是缺考还是漏录；缺失不计入该题分母 |
| `- ./escape.json 不可写` 类错误 | 输出路径是目录或含 `..` | 换一个常规文件路径 |

## 五、录入建议

- 一次分析一个班级 / 一次测验，避免混班混卷；
- 题目 id 建议直接用卷面题号（T1 / 第3题）；
- 判分规则变化（如部分给分）时，保留原始得分，只改 `max_score` 与阈值配置，不手改结果。