课评: 转出学生归档（王子墨/张立坤/黄俊博）+ 周四班级总结 + 新生章梓皓档案 + C++示例代码

2026-09-29 22:43:54 +08:00
parent 6f57dfe67e
commit 73cce4c4f5
116 changed files with 6817 additions and 248 deletions
--- a/.workbuddy/skills/课评生成/SKILL.md
+++ b/.workbuddy/skills/课评生成/SKILL.md
@@ -1,5 +1,5 @@
 ---
-name: 课评生成
+name: feedback-generator
 description: 快速生成个性化课评，你只需提供学生本节课的表现，自动匹配班级风格生成高质量课评
 type: skill
 ---
@@ -27,10 +27,10 @@ type: skill
   HTML 以 `samples/report-sample.html` 为样式基准，`pdf` 用 `scripts/mkpdf.mjs` 生成（单页 660px）。
 4. **审核红线**（必须写进每次交付说明）：报告是草稿、须教师审核；只写学习习惯不写人身评价；
   代码/报错/错题选项只发对应家长、不进班级群；不做学生横向对比排名。
-5. **存档结构改用新技能体系**（见下方「CSP 班（v2 存档结构）」）：
-   `Class-2026-X/<班组>/<学生>/` + `Students/<学生>/profile.md`。
+5. **存档结构（2026-09-26 统一）**：所有课程体系统一存档到
+   `.claude/memory/class/<班组>/<学生>/`，画像在 `.claude/memory/class/<班组>/<学生>/profile.md`。

-> AIAGENT03 班、体验课 **不**适用本规则，仍按本技能原有流程与存档（`.claude/memory/class/...` + `output/课评汇总/`）执行。
+> AIAGENT03 班、体验课**不**使用 OJ 报告三件套流程，但存档路径与下方通用规则相同。
 >
 > **快速触发**：对 AI 说「整理 XX 班的课堂反馈」或「引导我进行操作」即可调用该技能；其脚本自动读取仓库根 `.env`（已配置 OJ 凭据）。

@@ -58,18 +58,19 @@ type: skill

 ```
 📝 问题1：这次写哪个班？（列出当前所有班级选项）
-  AIAGENT03班：周五下午1700、周六晚上1900、周日早上0845、周日下午1400
+  AIAGENT03班：周五下午1500、周五下午1630、周六晚上1900、周日早上0845、周日早上1045、周日下午1400
  CSP04班：周六早上0830、周六下午1400
  CSP00班：周五晚上1900（2课时）
+  CSP01班：周六下午1610（一对一，随机补课）
  体验课

 📝 问题2（AIAGENT03班）：作品文件夹路径是什么？

 📝 问题3（CSP00/CSP04班）：OJ题目的token是什么？
-
-📝 问题4：本节课出勤情况如何？（来了哪些学生，谁请假）
 ```

+⚠️ **出勤情况自动获取，无需你提供！** 我会调用校宝API自动查询，详见下方规则。
+
 你回答完所有问题，我就会自动完成整个课评生成流程！

 ---
@@ -79,12 +80,13 @@ type: skill
 你提供信息后，我会自动完成：

 ### 第1阶段：课评准备
-1. 使用python-docx读取录音转写文件
-2. AI分析录音文本，识别"发言人1,2,3"对应的学生
-3. **AIAGENT班**：查看作品文件夹，分析每个学生作品的创意和亮点
-4. 读取课程计划，获取5个知识点
-5. 读取每个学生的画像
-6. **CSP00/CSP04班**：使用token查询OJ做题数据
+1. **🎯 自动获取出勤数据**（优先校宝API，失败再问你，详见下方规则）
+2. 使用python-docx读取录音转写文件
+3. AI分析录音文本，识别"发言人1,2,3"对应的学生
+4. **AIAGENT班**：查看作品文件夹，分析每个学生作品的创意和亮点
+5. 读取课程计划，获取5个知识点
+6. 读取每个学生的画像
+7. **CSP00/CSP04班**：使用token查询OJ做题数据

 ### 第2阶段：课评生成
 1. 读取班级风格指南
@@ -186,9 +188,74 @@ type: skill

 ### 工作流程
 ```
-确认班型班次 → 读取录音转写(docx) → AI分析识别发言人 → 获取课程知识点 → 读取学生画像 → 润色生成 → 确认修改 → 课评质检 → 保存
+确认班型班次 → 🎯校宝API查出勤 → 读取录音转写(docx) → AI分析识别发言人 → 获取课程知识点 → 读取学生画像 → 润色生成 → 确认修改 → 课评质检 → 保存
 ```

+### 0. 🎯 自动获取出勤数据（校宝API · 优先执行）
+
+**执行时机**：确认班型和授课日期后，第一时间查询校宝API获取出勤数据。
+
+**API信息**（从 `.env` 读取）：
+```
+API Base URL: https://api.qonnwolf.com/api/v1
+Authorization: Bearer <从 .env 读取>
+```
+
+**查询接口**：
+```
+GET /reports/teaching-schedule?teaching_date={日期}&teacher_name=橙子&include_students=true
+```
+
+**班级名映射**（授课日期 → 校宝班级名，用 teacher_name=橙子 筛选后自动匹配）：
+
+| 我们的班次 | 校宝 class_name 特征 | 时间段 |
+|-----------|---------------------|--------|
+| 周五下午1500 AIAGENT03 | AIAGENT03 | 15:00-16:30 |
+| 周五下午1630 AIAGENT03 | AIAGENT03 | 16:30-18:00 |
+| 周五晚上1900 CSP00 | CSP00 | 19:00-20:30 |
+| 周六早上0830 CSP04 | CSP04 | 08:30-10:00 |
+| 周六下午1400 CSP04 | CSP04 | 14:00-15:30 |
+| 周六下午1610 CSP01 | CSP01 | 16:10-17:40 |
+| 周六晚上1900 AIAGENT03 | AIAGENT03 | 19:00-20:30 |
+| 周日早上0845 AIAGENT03 | AIAGENT03 | 08:45-10:15 |
+| 周日早上1045 AIAGENT03 | AIAGENT03 | 10:45-12:15 |
+| 周日下午1400 AIAGENT03 | AIAGENT03 | 14:00-15:30 |
+
+**执行流程**：
+
+1. **调用API**：用 curl 调用接口，传入授课日期和 `teacher_name=橙子`，设置 `include_students=true`
+2. **匹配班级**：API返回当天橙子老师所有课次，根据用户选择的班次对应的时间段和 class_name 匹配到具体课次
+3. **提取出勤**：从匹配课次的 `students[]` 数组提取每个学生的 `attendance_status`
+   - `attendance_status` 值：`正常` / `请假` / `迟到` / `缺勤` / `补课` 等
+   - 映射到课评系统：
+     - `正常` → 正常上课（生成课评）
+     - `请假` → 请假记录（生成请假记录）
+     - `迟到` → 正常上课（照常生成课评，可提及迟到）
+     - `缺勤` → 未到课记录
+     - `补课` → 补课课评
+4. **格式化**：将出勤数据转为标准格式供后续流程使用：
+   ```
+   正常上课：卢皓霖、朱浩铭、沙佩琪
+   请假：李汶浩
+   迟到：无
+   补课：无
+   ```
+
+**异常处理**（三级降级策略）：
+
+| 情况 | 判断方式 | 处理 |
+|------|---------|------|
+| ✅ 正常返回 | API返回 code=0，且有匹配的时间段 | 直接使用出勤数据 |
+| ⚠️ API 过期/401 | HTTP 401 或返回 token 相关错误 | **立即告知橙子**：「校宝API token过期了，麻烦你提供新的token，我会保存到 `.env`」。橙子提供新token后更新 `.env` 中的 Authorization，然后重试 |
+| ⚠️ 校宝无此班级 | API返回 code=0 但无匹配的时间段/班级 | **问橙子**：「校宝上没查到这个班的出勤，你手动告诉我吧：谁来了？谁请假？」 |
+| ⚠️ 校宝数据不全 | API返回了班级但学生列表为空或明显缺失 | **问橙子**：「校宝上这个班的学生数据好像不全（只查到X人，应该是Y人），你确认一下？」 |
+| ⚠️ 网络错误 | curl 超时或连接失败 | 重试一次，仍失败则降级问橙子 |
+
+**⚠️ Token 更新流程**：
+当橙子提供新的 token 时，更新项目根目录 `.env` 文件中的 `Authorization: Bearer <新token>` 行，然后重试查询。
+
+> 💡 **核心原则**：出勤数据优先自动获取，减少橙子手动输入。API 出问题时及时告知并降级处理，绝不能因为 API 故障卡住整个课评流程。
+
 ### 1. 读取课堂录音转写文件
 自动从 `D:\03-下载` 目录读取课堂录音转写文件（`.docx` 格式），查找该目录下最新的 `.docx` 文件：

@@ -223,7 +290,7 @@ Read 工具直接读取 _提取.txt 文件，中文显示完全正常

 > **为什么这样做？** python-docx 底层 XML 是 UTF-8 编码，能正确读取中文。但 bash 终端渲染 UTF-8 中文时会产生乱码。保存为 txt 后，用 Read 工具读取即可正常显示。
 >
-> **清理**：课评保存完成后，删除 `_提取.txt` 临时文件。
+> **清理**：课评全部保存完成后，自动删除 `_提取.txt` 临时文件和原始 `.docx` 录音文件（详见第4阶段「🧹 自动清理录音临时文件」）。

 **录音文本特点**：
 - 语音转文字质量参差不齐，常见同音字、模糊识别
@@ -764,20 +831,18 @@ python scripts/get_student_oj.py \
  - 未上课：`YYYYMMDD_课程编号-课次(未到).md`
  - 补课：正常文件名 `YYYYMMDD_课程编号-课次.md`，放在补课班级下的 `补课/` 目录中

-### ⚠️ CSP 班（v2 存档结构 · 覆盖上方通用规则）
+### ✅ 存档路径统一规则（2026-09-26 起，全部课程适用）

-CSP00 / CSP04 课评**不**使用 `.claude/memory/class/...` 与 `output/课评汇总/` 路径，统一改用
-`.claude/skills/class-feedback-report` 的归档体系（详见该技能 SKILL.md）：
+所有课评、家长版报告、班级汇总**统一存 `.claude/memory/class/` 对应班级目录**，
+不再使用 `Class-2026-X/` 或 `output/课评汇总/`：

- **家长版三件套**（发给家长）：`Class-2026-X/<班组>/<学生>/<姓名>-<班组>-<章节号>-反馈报告.{md,html,pdf}`
-  - 例：`Class-2026-C/克力周日0830CSP02/王凯平/王凯平-克力周日0830CSP02-03-反馈报告.md`
-  - `Class-2026-X`：A春 / B暑 / C秋 / D寒（2026秋季班用 `Class-2026-C`）
+- **家长版三件套**（发给家长）：`.claude/memory/class/<班级>/<学生>/<姓名>-<班级>-<课次>-反馈报告.{md,html,pdf}`
+  - 例：`.claude/memory/class/CSP04橙子周六1400/张雨禾/张雨禾-CSP04橙子周六1400-04-反馈报告.md`
  - HTML 以 `samples/report-sample.html` 为样式基准；PDF 用 `scripts/mkpdf.mjs` 单页 660px 生成
- **内部课评正本**（校宝核查用）：`Class-2026-X/<班组>/<学生>/feedback/YYYYMMDD_课程编号-课次.md`
- **学生画像**：`Students/<学生>/profile.md`（跨学期连续，按学生名扁平存放）
- **班级汇总**：`Class-2026-X/<班组>/summaries/<班组>-<章节号>-反馈汇总-<日期>.md`
-
-> AIAGENT03 班、体验课仍按下方通用规则（`.claude/memory/class/...` + `output/课评汇总/`）保存。
+- **内部课评正本**（校宝核查用）：`.claude/memory/class/<班级>/<学生>/feedback/YYYYMMDD_课程编号-课次.md`
+- **补课生**：`.claude/memory/class/<班级>/补课/<学生>/feedback/`（家长版报告同放该目录）
+- **学生画像**：`.claude/memory/class/<班级>/<学生>/profile.md`（随班级存放，每次课评后更新成长记录）
+- **班级汇总 / 上课通知 / 质检报告**：`.claude/memory/class/<班级>/summaries/YYYYMMDD_课程编号-课次_班级反馈.md`

 ### 1. 保存到学生个人单次课评文件（必须，用于自动化统计）
 为每位学生生成单独的单次课评文件，这是课评完成率统计的依据：
@@ -799,7 +864,7 @@ CSP00 / CSP04 课评**不**使用 `.claude/memory/class/...` 与 `output/课评
 ### 2. 保存到统一周课评汇总（后写的放上面）
 同时保存到统一的课评汇总目录，同一周的课评放在同一个文件里，新生成的放在最顶部：
 **根目录**：`E:/cc/4work_project/ClassFeedback/output/课评汇总/`
-**文件名规则**：`202X年第X周课评汇总.md`（比如「2026年第18周课评汇总.md」）
+**文件名规则**：`202X年教学第X周课评汇总.md`（比如「2026年教学第18周课评汇总.md」）
 **排序规则**：最新生成的课评放在文件的最前面，旧的课评在后面，倒序排列
 **班级分组**：同一个班级的课评放在一起，按班级分组展示

@@ -895,10 +960,37 @@ output/课评汇总/第{X}周{星期时间}{课程编号}课评.html

 ---

+### 🧹 自动清理录音临时文件（保存完成后执行）
+
+课评全部保存完成后，**自动删除本次使用的录音转写文件**，避免 `D:\03-下载` 目录堆积：
+
+1. **删除 `_提取.txt` 临时文件**：本次流程中由 python-docx 提取生成的 `_提取.txt` 文件
+2. **删除原始 `.docx` 录音转写文件**：本次读取的录音转写 `.docx` 源文件
+
+**执行方式**：
+```bash
+# 删除本次提取的 txt（在读取阶段已记录文件路径）
+rm "D:/03-下载/xxx_提取.txt"
+
+# 删除原始 docx
+rm "D:/03-下载/xxx.docx"
+```
+
+**安全规则**：
+- 只删除本次流程中实际读取过的那一个 `.docx` 和对应的 `_提取.txt`，不误删其他文件
+- 如果 `D:\03-下载` 下有多个 `.docx`，只删本次用到的那个，不动其他的
+- 删除前无需确认（橙子已确认此规则）
+- 删除后在完成报告中告知：`🧹 已清理录音临时文件：xxx.docx + xxx_提取.txt`
+
+> 💡 **为什么删？** 录音转写文件只是中间材料，课评已保存到结构化目录，原始录音留着占空间。如果橙子某次想保留某个录音，随时可以说「这次的录音先别删」来临时跳过。
+
+---
+
 ### 保存完成后我会告诉你：
 ✅ 已保存X条课评
 ✅ 周汇总已更新：[周数]周汇总文件已更新，新课评已放在最顶部
 ✅ 课评汇总网页：output/课评汇总/第X周[星期时间][课程编号]课评.html（如已存在则跳过）
+🧹 已清理录音临时文件：xxx.docx + xxx_提取.txt

 ---