课程反馈生成工具

面向教师的本地课程反馈工作台。记录每位学生的课堂表现，生成并校对反馈，再按自定义模板复制。

使用流程

1. 选择或新建班级，填写本次课程、授课时间、内容和教学目标。复用历史课程不会改变本次日期。
2. 在“管理名单”粘贴学生姓名，支持换行、英文或中文逗号、顿号和制表符。同名学生可以分别记录。
3. 选择学生，使用“简要记录”或“分项记录”填写观察。输入时可选择历史记录与启发提示，Ctrl+Enter 切换下一位。
4. 在设置中选择 AI 服务，保存密钥并测试连接。生成未完成反馈，也可单独重新生成或只重试失败项；可以随时停止。
5. 在正文中直接修改，点击“确认并下一位”。重新生成失败或取消后，原稿保留。
6. 预览最终反馈，选择纯文本或 Markdown 复制。批量复制只包含已确认、已启用且完成生成的反馈。
7. 页面自动保存到当前设备。“开始新一课”会保留本次记录，之后可通过“历史课次”恢复。

复制成功只表示内容已进入剪贴板，不表示已经发送给家长。

常用时间、多人编辑与语音

• 在授课时间旁打开“常用时间”，保存当前时段。每个班级可保存多个备选，点击“设为默认”后，新课会自动填写当天的默认时段；已有课次保留原时间。支持“昨天”“上周”“本日”快捷切换，其中昨天与上周以当前所选日期为基准。
• “紧凑 · 多人编辑”适用于任何班级，同时展示多名学生的观察与反馈。每页可选 6、10、16、24 或 50 人；切回“逐人编辑”继续详细校对，记录共用。
• 点击表现输入框即可查看两组补全。“历史记录”来自该学生已保存的课次，“启发提示”参考其他学生所有已保存课次、本次观察及常用表达。输入文字后按文字相似度排列，选择后填入当前栏，使用前请核对是否符合本次表现。
• 点击输入框旁的“语音填写”，开始录音，结束后检查识别文字，再点击“填入文本”追加到当前栏。支持普通话；需要浏览器支持语音识别并允许麦克风。语音可能由浏览器在线服务处理，识别结果可手动修改。不支持时可使用系统输入法语音。
• 页面右上角可选择浅色、暗色或跟随系统，选择会在此设备保留。

数据与备份

课程草稿、名单和设置保存在浏览器本地，常用短语保存在 IndexedDB。切班与刷新可恢复未完成草稿。学生通过稳定身份关联输入、结果与任务，排序不会改变归属。

设置中的“下载备份”包含课程、历史课次、名单、反馈、模板和常用短语，不包含 API 密钥。恢复前会显示数据数量，同名记录覆盖、其他记录保留。建议定期下载备份，清除浏览器数据会删除本地记录。

生成时，课程背景和当前学生观察会发送给所选 AI 服务。基础内容检查用于提醒明显问题，最终反馈需要教师核对。

本地开发

项目使用 React、TypeScript、Ant Design、Zustand、Dexie 和 Vite。保留 Yarn 4 锁文件。

Node.js 要求 ^20.19.0 || >=22.12.0。

yarn install
yarn dev

验证与构建：

yarn test
yarn lint
yarn build

代码结构

src/
  components/
    workspace/   工作台、学生导航、进度与批量操作
    course/      课程信息与时间选择
    student/     学生编辑与表现提示
    settings/    设置与反馈模板
    common/      通用按钮、图标与语音输入
    layout/      页面框架
    updates/     更新提示
    dev/         开发诊断组件
  types/         共享类型
  constants/     提示词等常量
  domain/        课程、学生与生成规则
  services/      AI、持久化、反馈模板与版本服务
  store/         页面状态
  hooks/         通用 React hooks
  utils/         通用工具
  AI_API/        AI 服务请求适配

测试与对应实现放在同一目录。性能监控使用 import.meta.env.DEV 判断开发环境；PerformanceMonitor 与 LazyIcons 目前作为备用组件保留，未接入页面。

本地模拟 AI 验收

node scripts/mock-ai.mjs

在本地开发页面设置自定义服务：

• 生成地址 http://127.0.0.1:5199/v1/chat/completions
• 模型列表地址 http://127.0.0.1:5199/v1/models
• 密钥填写任意测试字符串，无需真实密钥
• local-test 返回模拟流；slow-test 返回较慢的流；error-test 模拟 401 错误

模拟服务只监听本机，不发送外部请求。测试后切回实际使用的服务。

验收记录

见 本轮实施与验证。初轮范围包括可靠性、校对交付、响应式界面和性能优化。后续已增加班级常用时间、多人编辑、历史提示、语音填写与暗色模式；见 编辑体验补充验收。

许可证

MIT