ClassFeedback/.claude/rules/20-workflow.md

工作流程规则：输入格式、批量生成、存储与特殊处理

合并文件：快捷输入格式 + 批量课评生成 + 新学生/补课处理 + 速记符号 + 快速入门 版本：v3.2（拆分版）| 更新日期：2026-05-05

v3.2 变更：

• 速记符号系统拆分至 21-shorthand.md
• 补课/新学生/转正规则拆分至 22-student-mgmt.md
• 修复第10节重复子章节（原10.3-10.7出现两次）

---

一、快速入门（30秒上手）

1.1 三步完成课评

第1步：指定班级（一次即可）
/课评 班级：发现世界-周四19点

第2步：输入学生表现
乔乔：观望5分钟→主动搭3层→自己调整，开心，比上周进步
昊昊：慢热，搭3层，反复调整，稳定

第3步：AI自动生成并保存
AI生成 → 自动双轨保存 → 完成！

完成！课评已自动保存到班级汇总和个人档案，无需确认。

1.2 核心理念

• 有姓名 → AI知道是谁
• 有行为 → AI知道做了什么
• 其他随意 → AI自动补充

支持：口语化、碎片化、无序化、语音转文字。

---

二、输入格式

2.1 自然语言输入（推荐）

方式1：极简一句话

乔乔今天开始不敢碰，后来主动搭了三层，球卡住自己调高度，挺稳定的，比上周主动多了

方式2：关键词速记

乔乔：gj5→zd3→zt ↑++
昊昊：慢热→zd3→反复调 →

2.2 批量输入格式

标准列表式（推荐）

课程：DISC-007
班级：发现世界-周四19点
日期：4月16日

1. 乔乔：gj5→zd3→zt ↑++
2. 昊昊：慢热→zd3→反复调 →
3. 张小明[体验]：搭了3层，开心
4. 李小红[补课]：专注完成，稳定

简化表格式

学生      核心表现              情绪   对比
─────────────────────────────────────────
乔乔      gj5→zd3→zt            ↑      ++
昊昊      慢热→zd3→反复调        →      渐入佳境
小明[体验] 搭3层参与             ↑      积极

2.3 语音输入优化

AI自动匹配班级学生名单，实时纠正谐音：

• "良心桥" → "梁昕乔"
• "中云浩" → "钟昀昊"

速记符号完整定义：参见 21-shorthand.md

---

三、学生类型标记

3.1 标记说明

标记	含义	处理方式	保存位置
无标记	正式学生	双轨保存	班级汇总+个人档案
[补课]	补课学生	自动检测档案位置，跨班级自动双轨保存	班级汇总+个人档案
[体验]	体验课学生	仅班级汇总	班级汇总（标记体验）
[缺课]	今天缺席	记录缺席	班级汇总（标记缺课）
[new]	新学生首次	创建档案	班级汇总+个人档案

3.2 标记使用示例

批量输入示例：

周四19点 DISC-007

乔乔：gj5→zd3→zt ↑++
昊昊：慢热→zd3→反复调 →
张小明[体验]：搭了3层，开心
李小红[补课]：专注完成，稳定

AI自动处理：

• 乔乔、昊昊：双轨保存
• 张小明[体验]：仅保存到班级汇总，不询问
• 李小红[补课]：检查档案 → 当前班级存在 → 双轨保存；其他班级存在 → 自动跨班级双轨保存

补课/新学生/转正详细规则：参见 22-student-mgmt.md

---

四、批量生成流程

4.1 标准流程

教师极简输入 → AI并行解析每个学生 → 预加载课程/档案 →
并行生成个性化课评 → 质量检查 → 【自动双轨保存】→ 完成

预加载说明：

• 课程预加载：系统根据日期自动计算学期周数，匹配课程主题和知识点（详见 15-semester-weeks.md）
• 档案预加载：调取学生画像（性格气质、学习特点、历史表现）实现千人千面生成（详见 30-student.md）

4.2 批量输出界面

━━━━━━━━━━━━━━━━━━━━━━━
📊 批量生成完成（5份）｜发现世界-周四19点｜DISC-007
━━━━━━━━━━━━━━━━━━━━━━━

✅ 乔乔      198字  正常
✅ 昊昊      205字  正常
⚠️  小强      165字  偏短
✅ 张小明[体验] 192字  体验学生
✅ 李小红[补课] 201字  补课学生

【批量操作】
[全部发送] [逐个查看] [标记修改] [取消]
━━━━━━━━━━━━━━━━━━━━━━━

4.3 自动通过条件（同时满足）

• ✅ 学生有完整档案
• ✅ 字数在弹性范围内（180-350字）
• ✅ 无敏感词/异常表述
• ✅ 情绪描述合理

4.4 需教师关注条件（任一满足）

• ⚠️ 体验/补课学生（无档案）
• ⚠️ 字数偏差>20字
• ⚠️ 检测到负面情绪词
• ⚠️ 与上周表现差异过大
• ⚠️ 内容重复度高

---

五、存储规则

5.1 双轨保存机制

存储位置	文件路径	用途	时机
班级周汇总	memory/class-evaluation-summary/第X周/{班级}.md	每周全班课评汇总（含出勤）	生成后自动保存
个人档案	memory/student/{班级}/{学生名}/历史课评记录.md	个人完整轨迹	生成后自动保存

5.2 存储优先级

1. 第一优先级：班级周汇总（必须成功）
2. 第二优先级：个人档案（允许失败，下次补存）

5.3 失败处理

• 班级汇总保存成功，个人档案保存失败 → 记录到待补存队列，下次生成前自动补存
• 教师可输入补存或同步手动触发

5.4 学生类型保存对照

类型	标记	保存位置
正式学生	无标记	班级汇总 + 个人档案
本班补课	[补课] + 当前班级档案存在	班级汇总 + 个人档案
跨班级补课	[补课] + 其他班级档案存在	班级汇总（补课班级）+ 个人档案（原班级，标注补课信息）
体验学生	[体验]	仅班级汇总
缺课学生	[缺课]	仅班级汇总（记录缺席）

5.5 班级周汇总文件格式

班级周汇总文件包含以下部分：

头部信息

# {班级名} 第{X}周汇总

> 课程代码：{CODE-XXX}  
> 课程主题：{主题名称}（{知识点}）  
> 上课日期：{YYYY-MM-DD}（{星期} {时间段}）  
> 班级人数：{N}人（出勤{M}人，缺勤{K}人）
> 代课老师：{老师姓名（如有）}

规则：

1. 如未特别标明代课老师，默认本班由常规老师授课，头部信息中不显示代课老师字段，班级整体情况中不显示代课老师反馈部分。
2. 出勤判定：有课评=出勤，无课评=缺课。补课/体验在课评状态表中标注。

本周课评状态

## 本周课评状态

| 学生 | 状态 | 类型 | 档案位置 | 操作 |
|:-----|:----:|:----:|:---------|:----:|
| {姓名}（{小名}） | ✅ 已保存 | 常规学生 | 本班 | [查看] [修改] |
| {姓名}（{小名}） | ✅ 已保存 | 补课学生 | {原班级} | [查看] [修改] |
| {姓名}（{小名}） | ✅ 已保存 | 体验学生 | - | [查看] [修改] |

学生课评列表

每个学生包含：

• 学生姓名（小名）
• 类型标记（补课/体验/常规）
• 三段式课评内容
• 教师备注

本周班级整体情况

## 本周班级整体情况

### 课程目标达成度
- **知识点掌握**：{主题}（{N}/{N}学生掌握）
- **技能操作**：{技能点}（{掌握情况}）
- **{其他维度}**：{评估结果}

### 共性亮点
1. {亮点1}
2. {亮点2}
3. {亮点3}

### 共性问题
1. {问题1}
2. {问题2}

### 教师反馈
> {授课老师的整体评价}
> 
> **注**：如为代课老师授课，标题改为"代课老师反馈"，并注明代课老师姓名。

---

六、推荐工作流程

6.1 课后5分钟快速流程

Step 1（1分钟）: 指定班级
/课评 班级：发现世界-周四19点

Step 2（2分钟）: 速记输入
乔乔：gj5→zd3→zt ↑++
昊昊：慢热→zd3→反复调 →
小明[体验]：zd3 ↑
小红[补课]：专注完成 →

Step 3（2分钟）: 查看并保存
AI生成 → 查看质量报告 → 完成（已自动双轨保存）

完成！课评已自动双轨保存，无需确认。

6.2 不同场景推荐

场景	推荐方式	预计时间
常规课后（8人）	速记批量输入	3-5分钟
重点关注学生	自然语言详细描述	2-3分钟/人
边走边记	语音转文字	实时
周汇总整理	查看班级周汇总文件	1分钟

---

七、自动双轨保存机制（核心功能）

课评生成后立即自动保存到班级汇总和个人档案，无需教师确认

7.1 机制概述

生成阶段                    保存阶段                    完成阶段
─────────                  ─────────                  ─────────
AI生成课评              →  【自动双轨保存】      →  教师可随时查看/修改
     ↓                         ↓                          ↓
质量检查通过            →  班级汇总 + 个人档案    →  完成（无需确认）

核心原则：

• ✅ 生成即双轨保存：课评生成后立即自动保存到班级周汇总和个人档案
• ✅ 无需确认：教师无需点击"确认"，课评直接生效
• ✅ 全程可修改：生成后教师可随时修改，修改后自动同步到两个位置
• ✅ 出勤自动记录：有课评即视为出勤，状态直接体现在班级汇总中

7.2 保存流程

标准流程

教师输入表现 → AI生成课评 → 质量检查 → 【自动双轨保存】→ 完成

详细步骤

def on_evaluation_generated(student, evaluation):
    """课评生成后自动触发"""
    
    # 1. 质量检查
    if not quality_check(evaluation):
        return regenerate(student)
    
    # 2. 自动保存到班级汇总
    try:
        save_to_class_summary(student, evaluation)
        log_success(f"{student} 课评已保存到班级汇总")
    except SaveError as e:
        log_error(f"班级汇总保存失败：{e}")
        return retry_or_alert()
    
    # 3. 自动保存到个人档案（如有档案）
    if has_archive(student):
        try:
            save_to_personal_archive(student, evaluation)
            log_success(f"{student} 课评已保存到个人档案")
        except SaveError as e:
            add_to_compensation_queue(student, evaluation, error=e)
            log_warning(f"{student} 个人档案保存失败，已加入补存队列")
    
    # 4. 展示给教师（已保存状态）
    return show_to_teacher(student, evaluation, status="已保存")

7.3 学生类型处理

类型	档案状态	保存位置
正式学生	有档案	✅ 班级汇总 + ✅ 个人档案
本班补课	有档案（本班）	✅ 班级汇总 + ✅ 个人档案
跨班级补课	有档案（他班）	✅ 班级汇总 + ✅ 个人档案（原班级）
其他老师班级补课	有档案（其他老师班级）	✅ 班级汇总（仅）
体验/临时学生	无档案	✅ 班级汇总（仅）
缺课学生	有档案	❌ 不生成课评

7.4 自动触发条件

场景	触发动作	自动保存
单学生课评生成完成	立即触发	班级汇总 + 个人档案（双轨）
批量课评全部生成完成	全部生成后批量触发	班级汇总 + 个人档案（双轨，批量）
课评修改完成	立即触发	班级汇总 + 个人档案（双轨，更新）

自动保存优先级：

优先级1（必须成功）：班级周汇总文件写入
   ↓ 成功
优先级2（允许失败）：个人档案写入
   ↓ 失败
加入待补存队列，下次触发时重试

7.5 教师交互指令

查看类指令

指令	功能	返回内容
查看{学生}	查看指定学生课评详情	完整课评内容 + 状态 + 操作按钮
查看全部	查看所有已生成课评	列表视图，含快速操作
查看本周	查看本周班级汇总	打开本周班级汇总文件

修改类指令

指令	功能	触发动作
修改{学生}：{内容}	修改指定学生课评	直接编辑，更新班级汇总和个人档案
重生成{学生}	完全重新生成	删除原课评，重新生成，自动双轨保存
删除{学生}	删除该学生课评	从班级汇总和个人档案中删除（保留记录）

7.6 修改规则

支持修改的范围

修改类型	示例	处理方式	字数限制
词语替换	"搭建"→"拼搭"	直接替换	不影响
称呼修改	"乔乔"→"昕乔"	全文替换	不影响
内容补充	在"完成了"后添加"还帮助了同伴"	插入文本	单条≤50字
内容删除	删除"这个调整值得注意"	删除文本	单条≤50字
情绪调整	"开心"→"兴奋"	替换关键词	不影响

不支持修改的场景（需重生成）

• 改变课评结构（如从3段改为4段）
• 改变评价基调（从负面改为正面）
• 补充大量内容（>100字）
• 改变课程主题理解

修改流程

教师：修改乔乔：把"搭建"改为"拼搭"
      ↓
AI定位班级汇总中乔乔的课评
      ↓
执行替换 → 字数检查 → 质量检查
      ↓
更新班级汇总文件
      ↓
同步更新个人档案（如有）
      ↓
提示修改完成

7.7 个人档案存储格式规范

文件结构

个人档案memory/student/{班级}/{学生名}/历史课评记录.md必须遵循以下结构：

# 历史课评记录

> 按时间倒序记录所有课后评价（最新课评始终在最上方）

## 学生信息
- **姓名**：{学生姓名}
- **班级**：{班级名称}
- **建档日期**：{YYYY-MM-DD}

## 课评记录列表

### 最新记录

### {日期} | {课程代码} | {课程主题}
**核心表现**：{关键词}

**课评内容**：
{三段式课评内容}

**能力评估**（当时）：
- 专注度：/5
- 精细动作：/5
- 工具使用：/5
- 问题解决：/5
- 社交合作：/5

**教师备注**：
- 亮点：
- 需关注：
- 保存时间：{日期时间}
- 代课老师：{如有}

---

### {更早日期} | {课程代码} | {课程主题}
...

存储顺序规则（重要）

必须遵循：时间倒序排列，最新课评在最上方

文件结构示意：

# 历史课评记录

### 最新记录  ← 这是占位符，指向最新的课评

### 2026-05-01 | DISC-009  ← 最新课评（第1条，刚保存的）
...
---

### 2026-04-23 | DISC-008  ← 次新课评（第2条）
...
---

### 2026-04-17 | DISC-007  ← 更早前课评（第3条）
...
---

追加新课的算法

def append_evaluation_to_archive(student, new_evaluation):
    """
    将新课评追加到个人档案
    规则：插入到文件顶部（最新记录位置）
    """
    
    # 1. 读取现有档案
    archive = read_personal_archive(student)
    
    # 2. 定位插入点（"### 最新记录"标记之后）
    insert_position = find_marker(archive, "### 最新记录")
    
    # 3. 构建新课评条目（包含日期、课程代码、内容等）
    new_entry = format_evaluation_entry(new_evaluation)
    
    # 4. 插入到顶部（确保最新在最上面）
    archive.insert_after(insert_position, new_entry)
    
    # 5. 保存文件
    write_personal_archive(student, archive)
    
    log_success(f"{student} 新课评已保存到个人档案顶部")

现有档案顺序修复

对于已存在顺序混乱的档案，提供修复指令：

教师输入：修复{学生}档案顺序
或
教师输入：整理{学生}历史课评

AI处理：
1. 读取该学生所有历史课评
2. 按日期降序排序（最新的在前）
3. 重写个人档案文件
4. 报告修复结果

7.8 失败处理机制

失败类型	处理方式	教师感知	补偿机制
班级汇总写入失败	立即重试3次，仍失败则报错	显示错误提示	手动重试按钮
个人档案写入失败	标记FAILED，加入待补存队列	静默处理，下次提示	自动补存
并发冲突（班级）	自动合并（追加模式）	无感知	自动解决
并发冲突（个人）	队列化处理，串行重试	延迟1-2秒	自动重试
磁盘满/权限不足	加入待补存队列，提醒教师	显示警告	手动触发补存

待补存队列处理

检测到待补存课评（2条）：

1. 乔乔 - 第7周发现世界
   状态：班级汇总已保存，个人档案保存失败
   原因：磁盘临时满
   [立即补存] [忽略]

2. 昊昊 - 第7周发现世界
   状态：班级汇总已保存，个人档案保存失败
   原因：权限被拒绝
   [立即补存] [忽略]

[全部补存]

7.9 批量生成界面

生成完成展示

━━━━━━━━━━━━━━━━━━━━━━━
📊 课评生成完成（5份）｜发现世界-周四19点｜DISC-007
━━━━━━━━━━━━━━━━━━━━━━━

✅ 已保存

✅ 乔乔      198字  已保存
✅ 昊昊      205字  已保存
✅ 张小明    192字  体验学生（仅班级汇总）
✅ 李小红    201字  补课学生（跨班级自动保存）
⚠️  小强      165字  字数偏短（建议检查）

【操作选项】
[查看全部] [修改] [重生成]
━━━━━━━━━━━━━━━━━━━━━━━

逐个查看模式

━━━━━━━━━━━━━━━━━━━━━━━
📋 课评详情 1/5 ｜乔乔
━━━━━━━━━━━━━━━━━━━━━━━

【课评内容】
乔乔本节课学习了"旋转飞机"...
（完整课评内容）

【状态】✅ 已双轨保存
【字数】198字 ✅ 符合标准
【质量】✅ 无敏感词 ✅ 情绪合理 ✅ 学生档案完整

【操作】
[查看下一份] [修改] [重生成]
━━━━━━━━━━━━━━━━━━━━━━━

7.10 状态管理面板

在班级汇总文件顶部自动维护状态面板：

---
class: 发现世界-周四19点
week: 7
course: DISC-007
generated_at: 2026-04-17T16:00:00
status:
  total: 5
  saved: 5
  failed: 0
students:
  - name: 乔乔
    status: saved
    saved_at: 2026-04-17T16:05:00
  - name: 昊昊
    status: saved
    saved_at: 2026-04-17T16:06:00
  - name: 张小明
    status: saved
    saved_at: 2026-04-17T16:07:00
    note: 体验学生，仅班级汇总
---

## 本周课评状态

| 学生 | 状态 | 操作 |
|:-----|:----:|:----:|
| 乔乔 | ✅ 已保存 | [查看] [修改] |
| 昊昊 | ✅ 已保存 | [查看] [修改] |
| 张小明 | ✅ 已保存 | [查看] [修改] |
| 李小红 | ✅ 已保存 | [查看] [修改] |
| 小强 | ⚠️ 保存失败 | [重试] [查看] |

7.11 快捷指令速查

场景	指令	效果
查看全部	查看全部	查看本周所有已保存课评
查看单个	查看乔乔	查看乔乔的课评详情
修改课评	修改乔乔：把"搭建"改为"拼搭"	修改指定课评内容
重生成	重生成乔乔	重新生成乔乔的课评
手动补存	补存 / 同步	手动触发待补存队列处理

---

八、出勤统计（嵌入班级汇总）

出勤信息直接记录在班级周汇总文件中，无需独立的出勤统计文件

8.1 出勤判定规则

状态	图标	判定方式
出勤	✅	有档案 + 已生成课评
补课	🔄	档案在其他班级 + 来本班上课（课评状态表标注）
体验/临时	📝	无档案 + 已生成课评（课评状态表标注）
缺课	❌	有档案 + 未生成课评（头部人数自动体现）

8.2 出勤信息位置

出勤数据直接体现在班级周汇总文件中：

头部信息（一行搞定）：

> 班级人数：{N}人（出勤{M}人，缺勤{K}人）

课评状态表（已有，兼做出勤记录）：

| 学生 | 状态 | 类型 | 操作 |
|:-----|:----:|:----:|:----:|
| 乔乔 | ✅ 已保存 | 常规 | [查看] |
| 小红 | ✅ 已保存 | 补课 | [查看] |
| 小明 | ✅ 已保存 | 体验 | [查看] |

8.3 查看出勤

指令	功能	返回内容
查看出勤	查看本周各班级出勤	读取各班级汇总头部信息汇总
查看{班级}出勤	查看指定班级	返回该班级汇总的头部+状态表
标记缺课 {学生}	手动标记缺课	在班级汇总中添加缺课记录

---

九、快速编辑功能

支持小修改直接编辑，无需重新生成：

修改乔乔：把"搭建"改为"拼搭"
修改昊昊：称呼改为"昊昊小朋友"
修改小明：在"完成了"后添加"还帮助了同伴"

限制：单次修改不超过50字，单篇累计不超过100字。超出限制建议重新生成。