教材使用指南：用18周推进物理AI项目

本书按18周组织，每周4学时。第1—12周由教师带领完成共同项目，第13—18周由学生主导原创项目。章节顺序同时也是项目版本演进顺序，前一章形成的仓库状态是后一章的起点。

18周项目路线

章节中的项目版本

阅读一章前，先确认以下信息：

课程仓库地址
当前分支
起始标签或提交号
本章允许修改的文件
本章结束时的验证条件

这些信息共同确定本章的工程边界。若起始提交不同、工作区已有修改或工具链版本不一致，应先恢复课程基线，再开始本章操作。

第1—2章采用人工操作

第1章和第2章不使用AI。学生需要亲自完成下面两条基本链路。

第1章：

取得仓库
→ 确认远程地址和提交号
→ 检查工作区
→ 编译和烧录
→ 输入真实声音
→ 记录运行结果

第2章：

确认基线
→ 手工修改一项事件规则
→ 查看差异
→ 重新编译和验证
→ 暂存并再次检查
→ 完成第一次提交

这两章先建立工程状态、验证证据和Git操作之间的关系。只有学生知道自己在没有AI帮助时怎样判断一次修改是否合格，第3章的AI协同才有可靠基础。

第3章以后采用AI协同

AI协同不是把整个仓库交给工具自动完成。每次任务都要明确四个要素：

AI生成的内容只有通过Git差异检查和运行验证，才能进入暂存区；只有通过同伴评审和流水线检查，才能进入受保护主分支。

三门课程的接口

本书不替代另外两门课程，而是接收它们形成的工程成果。

正文涉及采样率、模型输入、内存预算或器件接口时，只讲清它们怎样影响工程决策和版本关系。算法推导、训练方法、驱动和硬件细节由对应课程深入。

运行证据怎样记录

一次运行记录至少包含：

• 仓库提交号或标签；
• 开发板和关键外设型号；
• 工具链版本；
• 输入条件；
• 串口、测试或服务端输出；
• 观察到的结果；
• 未通过项目和可能原因。

截图可以作为辅助材料，但不能代替可复制的命令、日志和文字说明。涉及模型结果时，应区分模型原始输出、产品事件规则和用户最终收到的通知。

数据回放与真实设备

声音项目可以使用麦克风实时输入，也可以使用经过许可的音频样本。样本采用波形音频文件格式（Waveform Audio File Format，WAV）。两种输入应进入同一条处理链路。只有处理条件一致，比较结果才有意义。

进入智能感知终端项目后，可以在设备尚未到位时使用符合接口契约的数据回放验证上层服务。回放结果和实机结果应分别记录；回放通过不能证明硬件采集、功耗或实时性能已经通过。

Git与GitLab怎样逐步进入

• 第1章使用 clone、remote、branch、rev-parse 和 status 固定项目基线；
• 第2章使用 diff、add、diff --staged、commit 和 show 保存第一次合格变化；
• 第3章使用Git确认AI在规划阶段没有修改仓库；
• 第4章建立议题、任务分支、受限AI实施、合并请求、评审和合并流程；
• 第7—10章练习冲突处理、回退、接口兼容和多构建物版本关系；
• 第11—12章使用持续集成、标签、发布版本和许可证完成发布。

Git命令只在当前项目确有需要时进入。附录提供按场景组织的命令速查表。

安全与公开边界

• 不把Wi-Fi密码、接口密钥、校内地址和个人信息提交到仓库；
• 不把真实个人数据用于公开演示；
• 不让AI自动执行删除、推送、合并和发布；
• 不把教学模型用于健康诊断、生命安全或身份判断；
• 不把回放结果写成实机结果；
• 公开前检查代码、数据、模型、字体、图片和第三方资源的许可；
• 对外发布仓库只包含已经通过审查的内容，校内GitLab保留完整课程过程。

完成一章的标准不是文件数量，而是项目确实向前推进了一步。仓库状态应当清楚，变化范围应当明确，结论应有证据支持。综合实践还应形成新的设计、数据、代码或工程判断，不能停留在复现预设结果。