---
name: japanese-conversation-grader
display_name: 日语会话测试批改
description: A1/A2/B1(约对应JLPT的N5/N4/N3)日语会话测试音频批改；基于faster-whisper实现ASR转写，系统自动转写学生回答并做初步内容匹配与三维诊断（内容完整性/准确性/流利度）；不确定内容不扣分，只输出可疑候选供教师复核。支持单人/批量批改、纠错反馈、成绩归档；AI预批改辅助，教师人工复核，满分10分。
use_when: 教师批改日语会话作业录音、会话测试打分、批量评分与反馈
platform_independent: true
triggers:
 - 日语会话测试批改
 - 日语会话作业评分
---

## 会话测试形式与录音要求

**对话模式：师生对话**
教师根据课文内容编写5～6道提问。提前录制提问音频，每题之间预留固定作答时长。学生跟随音频参考课文内容回答，结束后提交音频文件。

---

## 标准答案与题目标注

1. **标准答案存储路径**：`./answer/{COURSE_ID}_{ASSIGNMENT_ID}_answer.txt`
2. **题目标注格式要求**
 - 每道题以 `[Q1]`、`[Q2]`……格式标注，便于音频转写后逐题对齐
 - 每题标注参考回答要点（关键词/句式），不要求逐字匹配

---

## 专有名词白名单配置
路径：`./answer/{COURSE_ID}_{ASSIGNMENT_ID}_proper_noun.txt`
每行1个名词，读音变体用`|`分隔，无专有名词则文件可不提供。

规则：
- 白名单内人名、地名、作品名，**AI不自动判错、不自动扣分**；
- ASR识别小偏差直接过滤；
- 专有名词严重读错，仅允许教师人工复核后扣分。

---

## 工作流程概览

Step1 音频预处理 → Step2 音频质量检测 → Step3 ASR转写 → Step4 ASR可靠性检测（置信度分级）→ Step5 三维AI评分 → Step6 教师复核 → Step7 成绩录入与反馈生成

---

## Step 1：音频预处理

- 批量转为 wav 格式，统一采样率
- 存放路径：`./audio/{student_id}/`

---

## Step 2：音频质量检测

检测项：
- 有效语音比例
- 音量范围
- 背景噪声
- 是否存在多人声音

**异常处理**：音频质量不足 → 不评分 → 请求重新上传。

---

## Step 3：ASR 转写

### 转写工具规格（强制）

- **唯一转写工具**：`faster-whisper`
- **仅允许模型**：`large-v3 fp16` / `medium`；禁用 `small` / `base` / `tiny` 及全部其他规格
- **硬件调度**：有充足 GPU 用 `large-v3 fp16`；无 GPU 自动降级 `medium`
- **固定开启** `word_timestamps=True` 输出词级时间戳

```bash
# 音频预处理
ffmpeg -y -i "input.mp4" -vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/audio.wav

# faster-whisper 日语转写
faster-whisper /tmp/audio.wav --model large-v3 --language ja --output_format txt --word_timestamps True
```

### 异常处理规则

- 音频损坏/空文件/无法识别 → 标记「转写失败」
- 自动移入 `./error_audio/`，触发人工复核
- 跳过自动评分，不直接判定低分

---

## Step 4：ASR 可靠性检测

系统综合判断以下方面：
- 文本匹配程度
- 音频质量
- ASR 置信度
- 对齐情况

输出：**高 / 中 / 低置信度**（用于 Step 6 教师复核的投入分级）。

### 置信度分级判定标准

| 置信度 | 判定条件 |
| :--- | :--- |
| **高** | 转写完整率 ≥80% 且 ASR 平均置信度 ≥0.8 且 音频信噪比 ≥20dB |
| **中** | 转写完整率 ≥60% 且 <80%，ASR 平均置信度 ≥0.5 且 <0.8 |
| **低** | 转写完整率 <60%，或 ASR 平均置信度 <0.5，或音频质量检测不通过 |

> 置信度‑AI评分衔接规则
> 1. **高、中置信度**：CAF三维AI加权分数作为正式预评分，教师仅做异常修正；
> 2. **低置信度**：AI三维加权分数仅作为后台诊断参考，**不计入、不对外展示，最终成绩完全由教师人工给出**。

---

## Step 5：三维 AI 评分

### 能力层级说明

遵循 **CEFR（欧洲语言共同参考框架）**；本系统采用 A1、A2、B1 三个等级。

| 能力层级 | 操作标签 | 会话评价重点 |
| :--- | :--- | :--- |
| **A1** | 约对应 JLPT N5 | 能围绕熟悉题目作简单、完整回答 |
| **A2** | 约对应 JLPT N4 | 能围绕日常话题进行较完整简单交流 |
| **B1** | 约对应 JLPT N3 | 能表达经历、理由和简单观点，注意连贯性 |

> JLPT 没有口语考试；N5/N4/N3 仅作为词汇、语法和课程任务难度参考。

---

### 评分原则

1. 内容切题比语法完美更重要
2. A1/A2（N5/N4）阶段轻微语法偏差以反馈为主，不扣分
3. 不确定错误不扣分
4. 鼓励为主，微小误差不扣分

> 准确性维度重要说明
> 准确性维度占20%权重参与AI加权运算，但**该维度输出仅为趋势预估值，不能直接等价于发音或语法错误**；系统不会依靠该维度自动判定发音或语法对错；所有错误必须经教师复核确认后方可扣分。

### 评分前置过滤规则（评分前必须执行）

计算任何维度分数前，先筛除以下情况，**排除出扣分范围**：

1. **ASR 误识别**——不进入评分计算
 - 同音词差异、语气词误识别
 - 系统标记为"ASR疑似误识别"的项
2. **转写存疑**——不进入评分计算
 - 系统置信度 < 0.5 的识别结果
3. **学习者自然偏差**——反馈但不扣分
 - A1/A2 阶段轻微语法偏差
 - 句尾语气词添加或省略
4. **白名单专有名词**——不进入AI自动扣分计算
   - 匹配白名单内的人名、地名、作品名；识别出现字形、读音轻微偏差，AI不自动判定词汇错误
   - 专有名词的严重误读，仅可由教师人工复核确认后扣分
---

### AI 自动评分模型（三维加权·主线）

| 评价维度 | 权重 | 数据来源 | 评分要点 |
| :--- | :--- | :--- | :--- |
| **内容完整性 (Content)** | 50% | 内容匹配度 + 关键词覆盖 | 回答是否切题、关键词覆盖、回答完整度 |
| **准确性 (Accuracy)** | 20% | ASR + 文本分析 | 语法正确性、词汇选用规范、发音清晰可辨 |
| **流利度 (Fluency)** | 30% | 停顿时长、语速 | 语速适中、停顿合理、语句衔接连贯 |

**权重设计理念**（鼓励为主，内容重于语法）：
- 内容完整性权重最高（50%），确保"回答切题"是核心底线
- 准确性（20%）权重调低，A1/A2阶段不强求语法完美，降低准确度对总分的拖累
- 流利度（30%）支撑表达流畅度

**跑题判罚宽松规则**（Step5 应用）：
- 仅"完全偏离题意"才判跑题扣分；"部分偏题但答及背景信息"不扣或轻扣
- 关键词缺失：仅当"核心要点缺失1个"才扣；非核心细节缺漏不扣
- 误读、认知性偏差（如课文段落张冠李戴）不单独重扣，反馈为主

**计算方式**：
> `单题得分 = 内容完整性×50% + 准确性×20% + 流利度×30%`
> `总分 = 各题得分之和 ÷ 题目数`（换算为10分制，保留1位小数）

### 各维度判定规则

| 发现的问题 | 归属维度 | 扣分规则 |
| :--- | :--- | :--- |
| 回答不切题/跑题 | **内容完整性** | 扣分 |
| 关键词缺失（≥3个关键词） | **内容完整性** | 扣分 |
| 明显语法错误（影响理解） | **准确性** | 扣分 |
| 发音错误（影响理解） | **准确性** | 经教师确认后扣分 |
| 长时间停顿（≥3秒） | **流利度** | 扣分 |
| 语速过慢或过快 | **流利度** | 反馈但不扣分 |
| ASR未识别出但音频有回答 | - | 不扣分，标记ASR误识别 |
| 轻微发音/语法偏差 | - | 反馈但不扣分 |

### 不扣分的情况

- 句尾语气词使用（よ/ね）
- 轻微发音偏差（A1/A2阶段容错空间大）
- 轻微卡顿（单次停顿＜3秒）
- 转写存疑、不确定是否为错误 → **不扣分**

### 等级划分

| 分数区间 | 等级 | 能力描述 |
| :--- | :--- | :--- |
| 8.0～10.0 | 优秀 | 完全符合目标会话能力要求，流畅完成沟通 |
| 6.0～7.9 | 良好 | 符合中阶会话能力，核心沟通无明显障碍 |
| 4.0～5.9 | 达标 | 达到基础会话要求，可完成核心信息传递 |
| <4.0 | 待加强 | 未达到基础要求，需强化核心能力 |

**低置信度规则**：低置信下AI预评分仅后台留存，不对外展示，最终成绩完全来自教师人工评分。

---

## Step 6：教师复核

### 人工复核调整规则

| 错误类型 | 调整分值 | 单类上限 | 说明 |
| :--- | :--- | :--- | :--- |
| 确认内容跑题 | -0.5 | -1.5 | 教师确认回答内容偏离题意 |
| 确认语法/发音错误 | -0.5 | -1.5 | 教师确认的明显语法或发音错误 |
| 确认断句/停顿异常 | -0.5 | -1.5 | 影响表达的明显停顿或中断 |

### 调整原则

1. 人工调整仅用于修正AI评分异常，不替代AI综合评分
2. 以下情况不得扣分：ASR误识别、同音词差异、语气词偏差
3. 只有满足以下条件才扣分：音频证据明确、非ASR单独判断、对内容或理解产生影响
4. 同类错误最多调整1.5分
5. 教师仅在 AI 未扣或扣分不合理时调整，确认 AI 已扣的项不再重复扣

> **最终成绩口径**
> - 高/中置信度 → 教师仅确认、不逐项重打全部分数，最终成绩 = AI评分
> - 低置信度 → 教师综合判断，AI三维分数仅做后台诊断参考，**不计入最终得分，最终成绩 = 教师评分**

---

## 分级纠错规则（A1/A2/B1）
注：纠错上限为 AI 内部生成约束，学生反馈报告中不展示纠错计数、上限数字，仅按上限筛选输出错误点。

### 纠错上限（按水平）

| 学生水平 | 纠错上限 |
| :--- | :--- |
| **A1** | 2项 |
| **A2** | 3项 |
| **B1** | 4项 |

### 纠错优先级（超过上限时）

1. 影响语义的关键错误
2. 反复出现的高频错误
3. 语法/表达不当

### 通用纠错原则

- 优先纠正影响语义的关键错误
- 同一错误只纠正一次
- 先表扬优点，再提出改进建议
- 不使用emoji（如⚠），语气鼓励为主
- 转写存疑、不确定的地方不纠错，一律不扣分

---

## 学生反馈配置（可配置，默认值如下）

```yaml
反馈字段:
  带每题得分: 可选        # 学生版是否展示 Q1~Q5 各题分数；默认关闭（更精简/鼓励）
  总评长度: 2-3句        # 默认；可改为1句(极简)
  练习建议: 2条          # 默认；可改为1条或4条
  带学生原话: 否          # 学生版默认不展示学生原话转录
  等级标注: 是            # 是否附 优秀/良好/达标
```
> 此配置为全局可调，使用老师可按需覆盖；不改则用默认值。

---

## Step 7：成绩录入与反馈生成

### 双产物原则
每次批改产出**两套独立产物**：
1. **老师版（详细）**——默认输出到聊天窗口，供教师复核、确认、人工修正。
2. **学生版（逐人简洁）**——每位学生一份，单独生成，用于反馈给对应学生本人（不含批改内部判定细节）。

### 平台无关输出（可插拔适配器）
本技能为通用批改内核，不绑定任何一家课程平台。不同院校可通过实现对应适配器、填入本校课程平台 API 凭证，实现自动拉取作业、自动批改、自动向学生推送反馈，批改业务逻辑无需改动；没有平台 API 的学校，可直接使用 CSV 导出手工导入。

技能**不绑定任何课程平台**，输出方式由适配器决定：

```
japanese-conversation-grader/
  SKILL.md                      # 通用：只描述批核与双产物，不含平台绑定
  adapters/
    csv_adapter.py        # 通用：导出CSV，老师导入任意平台(默认，全平台通用)
    canvas_adapter.py     # Canvas：读submission_map→API拉取/逐人反馈(可选)
    moodle_adapter.py     # 其他学校课程网站(可选)
    feishu_adapter.py     # 飞书：逐人发送(可选)
  scripts/
    download_audio_submissions.py  # 平台专用下载脚本(Canvas等)，生成submission_map.json
  config.json             # 本地机密配置（含API Token），绝不随技能共享
  report/
    detailed/{student_id}.txt      # 老师版详细报告（本地归档）
    student/{student_id}.txt       # 学生版简洁反馈（每位学生一份）
    summary.csv                    # 批量汇总（如需）
```

- **默认输出**：通用 `CSV 导出`（任何平台老师都能自己导入）。
- **具体平台**（Canvas/自家课程网站/飞书等）作为**可选适配器**，由配置 `platform` 指定启用。
- 技能只管生成"老师版报告 + 学生版反馈"两个标准产物，**发到哪由适配器决定**，从而适配不同学校的不同平台。

### 凭证与 Token 安全（强制）
1. **API Token 绝不写入 SKILL.md**、不写入共享代码、不上传 ClawHub。
2. Token 只存本地 `config.json` 的字段（如 `CANVAS_API_TOKEN`），或使用环境变量 `CANVAS_API_TOKEN`。
3. `config.json` 必须加入 `.gitignore`，**不得入库、不得随技能分发**。
4. SKILL.md 只写"读取 config.json / 环境变量中的 Token"，不出现任何真实 Token 值。

### 下载层与批核层分离
1. **下载层（平台专用）**：`scripts/download_audio_submissions.py` 调平台 API（如 Canvas）拉取学生作业，依赖 Token，产出**标准中间产物** `submission_map.json`（含 user_id / student_id / name / file_name / local_path / file_type / assignment_id / course_id 等字段）。
2. **批核层（通用）**：技能本体只消费 `submission_map.json` 这个标准结构，**不关心它来自哪个平台**。
3. 好处：新增平台只需新增下载脚本（适配层），主技能零改动；不同学校各用自己的私有下载层，通用部分共享。

### 输出文件

- 老师版详细报告：`./report/detailed/{student_id}.txt`（本地归档）
- 学生版简洁反馈：`./report/student/{student_id}.txt`（每位学生一份）
- 批量汇总：`./report/summary.csv`（如需）
- 默认同时输出到聊天窗口（老师版）

---

### 老师版详细报告模板（聊天框）
```
学生姓名:{name}（{student_id}）
评分结果:{total_score}/10

【总体评价】
{positive_comment}，{constructive_feedback}。{encouragement}

【逐题评分】
[Q1]:{question_1}
学生回答:{transcript_1}
评语:{comment_1}（简短提示）
得分:{score_1}/10

[Q2]:{question_2}
学生回答:{transcript_2}
评语:{comment_2}
得分:{score_2}/10

……（按实际题目数重复）

```

### 学生版简洁反馈模板（逐人，发/导入课程平台）
```
学生姓名:{name}（{student_id}）
评分结果:{total_score}/10  （如需可附等级）

【总评】（默认2-3句，鼓励为主）
{一个优点}，{1~2个关键改进}。{鼓励收尾}

【练习建议】
1. {suggestion_1}
2. {suggestion_2}

（若配置"带每题得分=是"，在此追加一行：Q1 x | Q2 x | …）
```

### 输出排版规则

- 老师版/学生版所有一级反馈大项必须单独另起一行
- 老师版总体评价：80‑150 汉字，优点 + 1‑2 条关键改进 + 鼓励收尾，不得与练习建议重复
- 学生版总评：默认 2-3 句，简明鼓励为主（可配1句极简）
- 问题编号用 Q1、Q2、Q3……
- 老师版单题评语：80‑150 汉字；仅针对本题作答表现，写本题的内容、语法、表达问题及简短提示，不输出全局性练习建议
- 练习建议共 2 条（可配），每条 30‑80 汉字，为跨题全局训练方向
- 禁用emoji、⚠等特殊符号

### 平台反馈（Canvas 等逐人反馈）

- 每位学生**单独一份**，只发给该生本人，不混入他人成绩。
- 学生版内容 = 总分 + 总评 + 练习建议（按反馈配置）。
- 批量时按 adapter 逐人推送/导出。

---

## 批量处理规则

1. 进度文件：`./progress/{course}_{task}_progress.json`
2. 支持中断后继续执行
3. 分批处理建议≤50人/批
4. 失败音频记录于 `./progress/{course}_{task}_failed.json`，含学生ID、失败原因、时间戳

---

## 核心原则

1. **综合评分**：AI依据内容完整性、准确性、流利度生成基础预评分；准确性维度仅为趋势参考，错误依靠教师确认
2. **教师修正**：教师根据课堂目标进行最终调整
3. **不���定时不判错**：转写存疑或判定不确定时，优先不判定为错误
4. **鼓励为主**：从鼓励出发，微小误差不扣分
5. **数据诚实**：准确性维度数据源（ASR置信度）非专业评价模型，不确定时标记"待复核"交由教师确认
6. **低置信度规则**：低置信下AI预评分仅后台留存，不对外展示，最终成绩完全来自教师人工评分

---

## 注意事项

- 成绩录入使用 `submission[posted_grade]`
- Whisper转写仅作参考，必须执行对齐校验
- 严格按A1/A2/B1能力层级控制纠错数量
- 评语简洁友好，不使用特殊符号