2、项目交付基础：源码管理、模型文件、硬件接线、演示流程四要素的职责划分与协作关系
机器人AI项目交付不是“把代码跑通”那么简单，而是一个涉及软件资产、模型资产、物理连接与现场演示的系统工程。任何一个环节的缺失或错位，都会导致交付延期、客户体验差，甚至项目验收失败。本章聚焦交付阶段的四个核心要素——源码管理、模型文件、硬件接线、演示流程，明确各自的职责边界、交付标准以及它们之间的协作关系，帮助项目团队建立一套可复用、可追溯、可排障的交付框架。
上图展示了四要素在项目交付中的核心定位与协作关系。源码管理负责“逻辑正确”，模型文件负责“智能能力”，硬件接线负责“物理连通”，演示流程负责“价值呈现”。四者并非孤立工作，而是通过交付协调中枢进行版本对齐、变更同步和验收基线管理。下面逐一展开每个要素的职责、操作方法和协作要点。
2.1 源码管理：交付的“逻辑骨架”
核心原理：源码管理不仅仅是把代码放进Git仓库，而是要确保任何一位新加入的工程师或客户方的维护人员，都能在30分钟内从零搭建出可运行的环境。交付级源码管理包含三个层次：版本控制（谁改了什么）、构建可复现（依赖锁定）、运行可追溯（日志与配置分离）。
操作流程：交付前的源码整理应遵循以下步骤：
- 清理临时文件：删除调试用的print、临时测试脚本、本地配置文件（如
config_local.yaml）。 - 锁定依赖版本：使用
requirements.txt（Python）或package.json（Node.js）锁定精确版本号，避免使用>=范围。 - 编写README：包含环境要求、安装步骤、启动命令、目录结构说明。
- 打版本标签：使用语义化版本号（如
v1.2.0），并关联对应的模型文件版本和硬件接线图版本。
pip install -r requirements.txt，但requirements.txt中有一行 numpy>=1.20，而实际测试环境安装的是numpy 2.0，导致API不兼容。解决方法是锁定精确版本 numpy==1.24.3，并在README中增加“已验证环境”一节，列出操作系统、Python版本、CUDA版本等关键信息。
2.2 模型文件：交付的“智能大脑”
核心原理：模型文件是AI项目的核心资产，但“模型文件”本身并不只是 .pt 或 .onnx 权重文件。一个完整的模型交付物应包含：权重文件、推理配置（输入尺寸、归一化参数、类别标签）、精度报告（在验证集上的mAP或准确率）、以及模型版本说明（训练数据范围、已知限制）。
判断方法：如何判断模型文件是否达到交付标准？使用以下检查清单：
| 检查项 | 标准 | 常见问题 |
|---|---|---|
| 权重文件完整性 | 文件哈希值可验证，大小与训练产出一致 | 传输中断导致文件损坏，加载时报错 |
| 推理配置一致性 | 预处理参数与训练时完全一致 | 训练时用RGB，推理时用BGR，导致精度下降 |
| 精度指标可复现 | 在标准测试集上达到合同约定指标 | 测试集与训练集重叠，指标虚高 |
| 模型格式兼容性 | 目标部署平台（Jetson、PC、树莓派）可加载 | PyTorch模型未转成ONNX，边缘设备无法运行 |
协作要点：模型文件与源码管理的协作关键在于“版本对齐”。建议在源码中创建一个 model_config.yaml，记录模型文件名、版本号、输入输出规范，并在启动时校验文件哈希值。这样，当模型更新时，源码无需改动，只需替换模型文件并更新配置。
2.3 硬件接线：交付的“物理经络”
核心原理：硬件接线是机器人项目中最容易“现场翻车”的环节。即使源码和模型完全正确，一根接错的杜邦线或一个虚焊的焊点，都会导致系统行为异常。交付级硬件接线管理强调“文档先行、验证闭环”。
操作流程：硬件接线的交付物应包括：
- 接线图：使用Fritzing或Draw.io绘制清晰的引脚级接线图，标注颜色、信号名、电压等级。
- 电源分配表：列出每个模块的工作电压、最大电流、供电来源，确保总功率不超过电源额定值。
- 检查清单：逐项核对“上电前检查”项目，如“确认VCC和GND无短路”“确认舵机信号线方向正确”。
案例拆解：某AGV项目交付时，客户反映“电机偶尔抖动，且无法通过串口读取编码器数据”。工程师现场排查发现：
- 电机驱动板的信号线使用了过长（超过30cm）的杜邦线，且与电源线绑扎在一起，导致PWM信号受干扰。
- 编码器A/B相线序接反，导致读数跳变。
- 驱动板的地线未与主控板共地，导致电平参考不一致。
解决措施：更换为双绞屏蔽线，将信号线与电源线分开走线；重新核对编码器线序；在主控板和驱动板之间增加粗地线。修复后，电机运行平稳，编码器读数稳定。复盘经验：硬件接线交付前，必须进行“连续运行2小时”的稳定性测试，而不仅仅是“能跑起来”。
2.4 演示流程：交付的“价值呈现”
核心原理：演示流程是将技术成果转化为客户可感知价值的“最后一公里”。一个成功的演示不是“碰运气”，而是经过精心设计的“确定性事件”。演示流程设计应包含：场景脚本（做什么动作）、操作步骤（如何触发）、异常预案（如果失败怎么办）、验收标准（怎样算通过）。
操作流程：设计演示流程时，建议遵循“5W1H”框架：
| 维度 | 问题 | 示例 |
|---|---|---|
| Why | 演示目的是什么？ | 证明机器人可以自主导航并避障 |
| What | 展示什么功能？ | 从A点导航到B点，遇到障碍物自动绕行 |
| Where | 在什么环境演示？ | 室内平整地面，光照均匀，无玻璃墙 |
| When | 演示时长多少？ | 3分钟内完成导航，绕行时间不超过10秒 |
| Who | 谁负责操作和讲解？ | 工程师A负责启动，工程师B负责讲解 |
| How | 如何触发和监控？ | 通过平板发送目标点，实时查看机器人视角画面 |
实战场景：某客户验收时，要求演示“机械臂抓取随机位置的物体”。第一次演示失败，因为物体颜色与背景相近，视觉识别漏检。团队立即启动异常预案：切换到备用识别模型（基于深度信息的模型），并调整了补光灯亮度。第二次演示成功。复盘发现，第一次失败是因为没有提前检查现场光照条件。此后，演示流程中增加了“环境预检”步骤：用照度计测量光照强度，用色卡验证相机白平衡。
2.5 四要素的协作机制与常见误区
协作机制：四要素的协作不是线性的“源码→模型→硬件→演示”，而是围绕“交付基线”的环形协作。具体机制如下：
- 版本对齐会议：交付前一周，组织四方（源码负责人、模型负责人、硬件负责人、演示负责人）对齐版本号，确认“源码v1.2.0 + 模型v2.1.0 + 接线图Rev3 + 演示脚本v1.0”是一个经过验证的组合。
- 变更控制：任何一方在交付前3天内提出变更，必须走“变更申请→影响评估→回归测试”流程。例如，模型更新后，必须重新验证源码中的推理代码是否兼容，硬件上的推理延迟是否满足要求。
- 联合调试记录：使用共享表格记录每次联调的时间、参与人、测试项、结果、问题描述。这不仅是过程记录，更是验收时的证据。
常见误区：
- 误区一：认为“源码能跑就行”，忽略环境依赖的锁定。结果客户换了台电脑就运行失败。
- 误区二：把模型文件直接放在源码目录下，导致Git仓库过大，且无法追踪模型版本。
- 误区三：硬件接线只画“示意图”，不标注引脚号和线色。现场接线时全靠猜，极易出错。
- 误区四：演示流程只排练“顺利路径”，不准备异常预案。一旦现场出问题，手忙脚乱。