帮助教师围绕题目组织教学逻辑的备课平台，从小学奥数起步，长期面向小学、初中、高中及更广泛的题目与备课场景。核心流程是“题目引入 → 理解概念与方法 → 回到原题 → 关联与迁移题”。
当前原型按人教版五年级上下册的 15 个单元组织专题目录，共提供 136 道题：36 道原创教学题和 100 道 CC BY 4.0 的 CMATH 五年级开放数据题。教师先选择年级和课题，再从题目进入“先做原题 → 理解概念与方法 → 回到原题 → 关联题”的备课链。观察物体题保留小正方体模型与三视图，其他专题使用文本、关系图或表格建议。
当前版本在本地单用户闭环上支持题目排序、难度筛选、四字题名、关联题匹配和正式入口页；备课草稿可持久化、编辑、确认并导出教师版或学生版。模型会结合当前题和检索到的相邻题，输出“知识点证据—可观察能力—教学活动—达成标准”，再由 LangGraph 整理为课堂节点，完整分析快照会随草稿保存。课后反馈提供教师引导填写、课堂作业图片、个人版与班群版预览、确认和导出。尚未完成自动 OCR、登录与多人权限、PostgreSQL、语义 embedding 或模型质量评测；CMATH 的单元归类和原创题教学质量仍需教师逐题复核。
产品名称为“一朵教学”；现有目录和包标识保留，避免影响本地运行。
- 选择年级，再按人教版五年级上下册单元进入题目文件夹。
- 在 15 个单元、136 道题中浏览或按题型、概念和方法搜索。
- 围绕同一道题依次完成先做、理解概念和回题，并进入下一道对比或迁移题。
- 查看题目来源与审核状态；开放数据和原创内容分别标记。
- 对空间题旋转小正方体并查看三视图；其他题显示板书与变式建议。
- 保存、重排、增删和编辑备课草稿，确认后导出教师版或无答案学生版 Markdown。
- 上传单题照片到本地私有目录，人工校对题目文字，再检索题库中的相近题。
- 配置模型后，由结构化输出识别知识点、难点、易错点和变式，再通过 Graph 生成三阶段备课内容；可继续围绕当前题实时问答。
- 由老师填写真实课堂内容、具体任务证据、完成方式、订正结果、建议和作业，生成相互隔离的个人反馈与班群反馈。
当前不抓取教学网站，不生成视频，照片识别也没有伪装成已经完成的 OCR。代码使用 MIT；CMATH 数据继续遵守 CC BY 4.0，详情见题库来源说明。第三方教材、竞赛试卷及用户资料不因进入系统而自动获得公开再分发许可。
备课草稿由 LangGraph 编排：校验需求、取得题目、检索上下文、可选模型分析、编排关联题、整理讲解、检查引用，最后停在等待教师确认。业务草稿由 SQLite 持久化，详见 A2 LangGraph 实现说明、A3 RAG 实现说明和 A4 基本功能说明。
需要 Python 3.12+ 和 Node.js 20+。
后端：
cd backend
python -m venv .venv
.venv/Scripts/python -m pip install -r requirements.txt
.venv/Scripts/python -m uvicorn app.main:app --reload前端另开终端：
cd frontend
npm install
npm run dev访问 http://localhost:5173。API 文档位于 http://localhost:8000/docs。
模型是可选能力。后端依次读取显式环境变量、仓库根目录 .env 和用户目录 .env，但不会覆盖已经存在的环境变量。DeepSeek 配置使用 DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL=https://api.deepseek.com 和 DEEPSEEK_MODEL=deepseek-flash；也保留 OPENAI_API_KEY 作为兼容入口。密钥只由后端读取；仓库、前端、草稿数据库和接口响应都不保存密钥。模型调用使用 Responses API 的 JSON Schema 结构化输出，并设置 store=false。没有密钥时，题库、基础备课、草稿、课后反馈和导出仍可使用。
cd backend
.venv/Scripts/python -m compileall app tests
.venv/Scripts/python -m pytest
cd ../frontend
npm run build最近一次实际验证结果见 Demo Verification Evidence。
对组合体观察题，几何关系必须稳定。可旋转模型可以暂停、换视角并让教师现场提问；由坐标计算投影也容易回归测试。后续可以把教师操作录制为确定性的镜头路径并导出讲解视频。生成式视频只适合补充情境，不作为几何事实来源。
代码采用 MIT License。CMATH 数据的 CC BY 4.0 署名与变更记录见 THIRD_PARTY_NOTICES.md。私有题库、教材图片、学生资料、模型密钥和运行产物不得提交到仓库。经来源与数学审核的原创或明确允许分发的种子题可以单独纳入公开样例，并保留各自许可。安全问题请按 SECURITY.md 的方式私下报告。
公开仓库用于复现备课、互动演示、AI 调整和课后反馈等功能，使用原创样例及许可明确的开放题目，不附带机构教材、真实学生资料或平台服务密钥。无需模型密钥即可体验基础流程；AI 功能需部署者自行配置服务并承担费用。
面向教师的私有交付可以复用同一套代码，分别配置模型服务和私有存储，接入教师有权使用的材料。默认的 private_data/、uploads/、exports/、环境变量文件及数据库均不纳入 Git；自定义存储位置也必须放在仓库外，或另行配置忽略规则。不要通过提交教材的方式制作“私有交付分支”，也不要使用 git add -f 绕过这些边界。
私有存放不等于取得版权授权，授课、分享和商业交付仍须核对材料允许用途。MIT 仅覆盖本项目代码及适用文档，不覆盖第三方教材；开放数据保留各自许可。当前交付形态仍为本地单用户原型，公开部署需要补齐认证、权限隔离及安全验收。
记录管理支持按姓名聚合展示课后反馈，进入姓名后查看每节课并单独删除；同名聚合不代表身份识别，同名不同人应由教师在名称中添加区分标签。使用说明入口可随时重新打开。
打开题目、查看关联题和保存资料只使用基础备课，不调用模型。进入“AI 帮我调整”，选择学生遇到的问题、教学方式和目标环节，确认平台服务后，点击“生成调整建议 · 使用 1 次 AI 额度”才调用；问答每次发送也计一次。补充文字为选填，只有“我有自己的教学设计”需要填写。
局部调整通过 POST /api/ai/adjust-stage 执行检索 → 生成 → 校验。模型输出固定为目标、2–5 个教学步骤（老师问什么、学生做什么、检查理解）和教师核对项，经 JSON Schema 与 Pydantic 校验后进入预览。教师可采用、放弃或撤销上次采用，这些操作不再调用模型。采用只替换所选环节，保留其他环节和原题；生成失败或原稿已变化时不覆盖原稿。采用后需保存草稿才会持久化，草稿和导出保留教学步骤。格式校验不能保证数学与教学内容正确，仍需教师审核。
前端局部替换回归：在 frontend 下使用 Node.js 24 执行 node --test tests/*.test.mjs。后端相关回归：在 backend 下执行 .venv/Scripts/python -m pytest tests/test_adjustment.py -q；使用模拟模型，不消耗真实额度。
后端通过 SQLite 原子计数限制本站共享请求次数，默认每天 20 次，可用环境变量 YIDUO_AI_DAILY_LIMIT 调整，0 表示关闭 AI 请求。北京时间零点按新日期计数，重启不清空。失败尝试不退回额度，已关闭模型空响应重试和 SDK 自动重试。已有输出 token 上限继续生效；次数上限并非人民币预算上限。
当前没有用户认证，额度属于整个部署，不是每个老师的个人额度，也未实现购买或支付。公开上线前仍需补齐账号、权限隔离与个人配额；不要把内测限制视为完整商业计费系统。API 密钥始终留在后端。
先保存课堂事实，再从「AI 润色」中选择个人反馈或班群通知。切换模式不调用模型；主动生成才使用一次共享额度。班群润色须确认共同授课内容，模型输入不含个体表现、姓名字段、图片、作业和提醒。自由文本仍需教师自行避免填写个人信息。
生成结果只是预览，可逐段对照原始事实；核对后采用并保存为草稿，再确认、导出。采用/恢复普通版不调用模型。修改并保存课堂事实会清除旧建议与已采用润色；过期或跨记录的建议不能采用。平台固定保留表现条件、作业清单与个人附件，不自动发送通知。
接口：POST /api/feedback/{id}/polish 生成；PUT 同一路径采用（proposal_id）或恢复普通版（proposal_id=null）。使用现有私有 SQLite，新增提案表；写入使用版本校验与事务，删除反馈级联清理提案。
本版按原始事实逐条润色并校验引用、数字和高风险措辞。尚未接入历史表现比较，趋势类措辞保守拒绝；语义忠实度仍需教师审核。群发 AI 版暂不插入自由文本提醒或“已发送”句。规则见 docs/AFTER_CLASS_AI_OUTPUT_SPEC.md；该文件的完整设计仍包含后续能力。
验证：backend 下执行 .venv/Scripts/python -m pytest tests/test_feedback_ai.py -q，使用模拟模型，不消耗真实额度。