6.4 KiB
6.4 KiB
项目记忆文件
课评工作流优化框架（v4.5）
创建日期：2026-05-16 | 基于实际跑流度的经验总结 更新日期：2026-05-20
v4.5 更新内容
- 表单直连提交：网页表单直接 POST 到本地服务器（
src/form_server.py），AI 通过检测.claude/.tmp/EVALUATION_READY.txt信号文件自动触发课评生成，彻底取消「复制→粘贴」步骤 - 补课存储规则简化：取消补课专用目录和双向记录，补课记录统一保存在学生原班级，文件名加
_补课后缀 - 体验课记录扁平化：体验课记录统一放在
体验课记录/目录，命名格式日期-班级-课程主题.md，一个文件可包含多个学生 - 临时数据清理：课评保存完成后自动清理
.claude/.tmp/下的 JSON 和信号文件
课评工作流优化框架（v4.4）
创建日期：2026-05-16 | 基于实际跑流度的经验总结
优化核心：「Form-First」三步式
/周几 → 选班级 → 自动打开网页表单 → 填表提交 → 自动生成保存
适用范围：所有上课日（周一~周日），
/周六、/周日、/周四、/周五等均按此流程执行
关键规则
规则1：自动推演课程进度
选择班级后，系统自动从 summaries/ 读取最新课次，推算当前课次：
- 若上次课距当前日期>1周且全班请假 → 提示"需补课吗？"供确认
- 否则直接使用下一课次
- 目标：减少1轮"确认课程"的交互
规则2：默认网页表单输入（Form-First）
选择班级后默认直接创建并打开网页表单，不先展示文本输入：
- 表单包含每个学生的：状态按钮（出勤/请假/体验/补课）+ 独立文本区
- 表单显示学生画像摘要（性格特点、上次表现）
- 显示速记符号参考
- 目标：消除"需要输入框→创建表单"的切换摩擦
规则3：表单直连提交 + 输出头信息
网页表单增加"直接提交"功能，提交后：
- 后台自动接收数据
- 输出内容头部自动包含：班级名称、课程编号·主题、日期
- 系统可自动识别班级和课次，不会搞错
- 目标：消除"复制粘贴回聊天"的中间步骤 + 消除班级/课次识别错误
规则4：表单辅助功能
- 填写进度条：实时显示已填写/总人数（含补课学生）
- 待填写提示：红色标记未填写的学生
- 输入框状态：填写后自动变绿，视觉反馈
- 一键复制：复制到剪贴板，带成功提示
- 补课/体验学生区 🆕：虚线边框独立区域，可动态添加多个补课学生，含姓名输入、状态（补课/体验）、表现描述，进度条自动计算在内
规则5：年级感知
根据班级课程类型自动选择输出模板：
- 学龄前（TUBE/DISC/INVENT/CREATE）→ 学龄前格式
- 小学（SPIKE/AICODE03）→ 小学格式
已确认优化效果
- 交互轮数：5轮 → 3轮
- 输入方式：聊天文本→临时表单 → 默认网页表单
- 课程确认：需人工回答 → 自动推算
- 数据提交：手动复制粘贴 → 一键提交
规则6：课评文字代码块包裹（便于预览复制）
班级总结文件（*_班级反馈.md）中，每位学生的课评正文必须用代码块 ``` 包裹，而非引用块 > 或纯文本：
- 代码块在 VS Code 预览时右上角显示复制按钮，方便一键复制课评文字
- 格式示例：
{课评正文}
**课评内容** - 请假/体验等无课评正文的学生，用
**状态**：描述即可，无需代码块
Hard Constraints
- All class days (Monday-Sunday) must follow the Form-First workflow
- Course progress must be automatically matched based on current week's date using semester week mapping (NOT inferred from last session progress)
- Web forms must be created by default for student performance input, no manual text input first
- Web forms must support direct POST submission to local server (
src/form_server.py) — no copy-paste required - AI detects
.claude/.tmp/EVALUATION_READY.txtsignal file to auto-trigger evaluation generation - Temporary JSON and signal files in
.claude/.tmp/are auto-cleaned after save completion - 补课记录存储规则（v4.5）：跨班级补课学生，课评文件保存在学生原班级
feedback/目录，文件名加_补课后缀（如20260505_DISC-009_补课.md），不再创建补课专用目录或双向记录 - 体验课记录规则（v4.5）：体验课记录统一放在
.claude/memory/class/体验课记录/目录，命名格式日期-班级-课程主题.md（如2025-05-17-SPIKE-电动螺丝刀.md），一个文件可包含多个体验学生
Engineering Conventions
- Class selection is triggered by "/weekday" (e.g., "/周六", "/周四")
- Class lists display current week's course theme based on semester week number (e.g., Week 11 → DISC-011 鳄鱼)
- Student input forms include individual text areas and attendance status buttons
- Form data is saved as JSON to
.claude/.tmp/evaluation_input_{class}.jsonvia POST to local server - Signal file
.claude/.tmp/EVALUATION_READY.txttriggers AI to read JSON and generate evaluations - Temporary JSON files and signal files are auto-cleaned after evaluation saving is complete
- 补课记录命名（v4.5）：
YYYYMMDD_课程编号-课次_补课.md，保存在学生原班级feedback/目录 - 体验课记录命名（v4.5）：
日期-班级-课程主题.md（如2025-05-17-SPIKE-电动螺丝刀.md），保存在.claude/memory/class/体验课记录/目录
Lessons Learned
- Manual course confirmation caused unnecessary interaction rounds; automatic inference saves time
- Chat-based text input was replaced with web forms due to user preference for dedicated input fields
- Course theme should be determined by current week's scheduled theme, not by tracking last session's progress
- Copy-paste from web form to chat was the #1 friction point; local server POST + signal file eliminates it entirely
- Generated form files must be auto-cleaned after use to avoid project directory clutter
- 补课记录简化（v4.5）：双向记录和补课专用目录造成文件冗余，改为单记录保存在原班级更简洁
- 体验课扁平化（v4.5）：多层嵌套目录不利于快速查看，扁平化结构更符合使用习惯