突破软工-教学项目总结与心得
一、项目核心思路
这个项目的本质不是"做一个App"，而是**把一份教育研究方案变成可操作、可演示的原型系统。
核心逻辑围绕一条线展开：
学生个人经验（情感锚点）
↓
AI生成信息（知识输入）
↓
核查AI输出（批判思维）
↓
人机对话追问（深度理解）
↓
AI结构化反馈（精准提升）
↓
反思写作（语言产出）
这个链条的精妙之处在于：AI素养不是单独教的，而是嵌入在"获取信息→判断信息→使用信息"的自然学习流程里。学生每一步都在接触AI，但每一步都被要求反思AI——AI生成背景简介后要核查它、AI追问后要回应它、AI给反馈后要判断采纳还是拒绝、最终还要填写AI使用声明。这叫"用中学"，不是"学了再用"。
文档里反复出现的4张伦理表单（AI输出核查表、文化视角核查表、AI使用记录、AI使用声明），表面看是防作弊，深层设计是**培养学生的元认知——知道AI能帮什么、不能替什么、自己负责什么。
二、技术应用
2.1 架构选择
React 19 + Vite + TypeScript (前端)
Express + JSON文件存储 (后端)
DeepSeek API (AI引擎)
选型逻辑是**原型优先：不需要 PostgreSQL、Redis、Docker 这些重型设施。JSON文件存储看似简陋，但原型阶段够用——数据量小、部署零依赖、调试直接看文件。等真正进入准实验阶段再切数据库，成本很低。
全栈 TypeScript 的好处：前后端共享类型定义，改一个字段编译器直接告诉你哪里要同步修改，不用靠"我好像记得那里也要改"。
2.2 AI集成
DeepSeek API 的集成是整个项目最关键的技术决策。5种AI角色（预习助手、文本追问者、观点启发助手、输出支持助手、写作反馈助手）本质上是对同一个 LLM 的不同 System Prompt 约束。
最有趣的是"文本追问者"的设计——约束它只能提问不能概括。这看似简单，但在 Prompt 工程里其实很难：LLM 天然倾向于"给出答案"，要让它克制住不概括、不解释，需要非常明确的 Prompt 指令。测试时确实出现过它偷偷给提示的情况，后来加了 NEVER summarize or explain 的大写强调才压住。
写作反馈助手的结构化 JSON 输出是另一个技术点。DeepSeek 的 `response_format: json_object参数保证了返回值是合法 JSON，但不保证 JSON 的内容结构符合预期。实测中偶有字段名拼错或缺少维度的情况，前端需要做兜底处理（try-catch 解析 + 降级为纯文本展示）。
2.3 局域网扫码访问
这个问题的解决过程本身就是一堂课：从"localhost二维码手机扫不了" → "加个地址编辑栏让老师手动改IP" → "自动检测局域网IP并一键切换" → "夸克云加速拦截请求，API层双通道fallback"。每一步都是用户真实踩出来的坑。
最有价值的认知是：中国手机浏览器生态（夸克/UC/QQ/微信）的云加速功能会拦截局域网请求。这不是技术bug，是产品设计冲突——云加速的设计目标是省流量提速，但局域网场景下反而成了障碍。最终解决方案是API层加"先走代理，失败则直连"的双通道回退，同时检测浏览器类型给用户提示。
2.4 一键启动器
`launcher.js 的设计思路是"让非技术人员也能启动"。自动检测端口冲突、等待后端就绪后再启动前端、显示访问地址——这些细节对于答辩演示场景至关重要。评委不会关心你的技术栈，但会因为"双击就能跑"而觉得项目完整度高。
三、学习与感悟
3.1 原型 ≠ 半成品
原型不是"简化的项目"，而是"项目的核心逻辑被压缩到最小的可演示形式"。这个项目里，完整的3次课教学流程、9步任务链、5种AI角色、4张伦理表单都在原型里做到了能用——不是"这里以后再做"，而是"现在就能点、能提交、教师能看到"。这种完整感对答辩来说比技术复杂度更重要。
3.2 AI应用的本质是设计"人机分工"
这个项目不是"让AI教英语"，而是设计了一套人机协作的教学流程：AI负责生成信息、追问、给反馈（机器擅长的：速度快、不疲倦、多维度），教师负责引导、判断、总结（人擅长的：情感连接、价值判断、灵活应变），学生负责输入、反思、修订（学习的核心）。好的AI教育应用不是替代人，是重新分配人机各自该做的事。
3.3 交互细节决定演示效果
提交按钮从一个简单的"提交"字样，演化出三种状态：
保存提交 → 提交中... → 提交成功！（绿色脉冲）→ 已提交
这个改动只有几十行代码，但是对演示体验的提升是巨大的——观众能看到系统在工作，不是点完按钮不知道发生了什么。Toast通知、AI思考动画、进度条、关键词云动画——这些"小事"加起来构成了一个"看起来像真产品"的感觉。
3.4 编码问题不是小事
整个开发过程中最隐蔽的坑是UTF-8编码。种子数据直接写JSON文件是正确的中文，但通过curl发的POST请求中文就变乱码。排查了很久才发现是Git Bash终端编码问题，而浏览器fetch是正常的。教训：永远用浏览器/Node.js验证，不要用curl/终端判断中文编码是否正常。
3.5 先跑通再优化
这个项目的开发顺序是：脚手架 → 数据库 → API → AI → 前端页面 → 联调 → 打磨。每一步完成后都能独立验证。没有出现"前端写了一周才发现后端接口设计错了"的情况，因为先定义了API、先测试了接口、再写前端。这个顺序看起来很"教科书"，但真正执行时很容易被跳过——因为写UI有即时反馈，写API没有。坚持先通后美，最终反而更快。
四、一句话总结
这个项目教会我：做一个教育AI原型的核心不是技术有多新，而是把教学逻辑翻译成用户操作流，让每一步都有反馈、每一环都可追溯、每一个AI行为都有约束边界。技术是骨架，教学设计才是灵魂。