4. 版本治理核心概念

控制原型开发有一个典型特征：模型、代码、标定参数、测试脚本和实验数据往往同时演进，而且经常需要“回到某个能稳定跑的版本”。如果团队只靠文件名区分，例如 motor_ctrl_v3_final_new.mdl，很快就会陷入无法判断差异、无法复现实验的困境。版本治理的核心，就是给这些变化建立一套可识别、可比较、可追溯的语义体系。本节围绕版本、修订、基线、分支、标签、合并、冲突、追溯、审计九个术语，说明它们在控制原型场景中的准确含义和实际用法。

版本与修订：从“一个状态”到“一次变化”

版本（Version）指某个时刻被正式标识的一组受控对象状态。在控制原型中，一个版本通常不是单个文件，而是一组关联对象的快照，例如：Simulink 模型 ctrl_top.slx、底层 C 代码、参数文件 calib_v2.mat、测试用例 test_step.m 以及对应的需求条目。版本号只是标识，真正重要的是它绑定了一组确定的输入。

修订（Revision）强调“相对上一次的变化”。一次修订可以只改一个增益参数，也可以同时改模型结构和接口。修订记录应回答三个问题：改了什么、为什么改、由谁改。例如某次修订把电流环比例增益从 0.85 改为 1.20，原因是阶跃响应上升时间超标，提交说明中应写明“提升电流环带宽，目标上升时间 ≤ 8 ms”。没有修订说明的版本，即使能打开，也无法支撑后续追溯。

基线：可复现的锚点

基线（Baseline）是被正式批准、后续变更必须受控的版本集合。控制原型中常见的基线包括：需求基线、模型基线、标定基线和测试基线。基线的价值在于“锚定”——当实验出现异常时，可以回到基线重新运行，判断问题是新引入的还是基线本身就有。

例如某电机控制原型在台架测试中出现低速抖动。团队先切回“M1 基线”（模型 v1.4 + 标定 calib_2024_03 + 测试脚本 test_suite_A），复现抖动；再切到当前开发版，抖动加剧。由此可判断：基线已存在轻微问题，当前修订放大了它。若没有基线，这个判断只能靠猜测。

分支、标签与合并：并行开发的组织方式

分支（Branch）是从某个版本派生出的独立开发线。控制原型中常见的分支策略是：主干保持可集成，功能分支用于新算法，标定分支用于参数整定，紧急修复分支用于现场问题。分支让不同目标互不干扰，但也带来合并成本。

标签（Tag）是给某个版本起的固定别名，通常不可移动。例如 release_2024Q2、bench_pass_0612、field_issue_017_fix。标签比版本号更易读，适合标记“已通过台架”“已交付现场”“已复现故障”等关键节点。

合并（Merge）是把一个分支的修订并入另一个分支。控制原型的合并不只是文本合并，还涉及模型结构、接口、参数和测试用例的同步。合并前应确认：接口是否一致、参数单位是否一致、测试是否覆盖变更点。

冲突：不只是文本冲突

冲突（Conflict）指两个分支对同一对象做了不兼容修改。控制原型中的冲突比代码冲突更隐蔽，常见类型包括：

• 参数冲突：两个分支分别把同一增益改为不同值，合并后必须明确保留哪一个。
• 接口冲突：一个分支改了输入端口数量，另一个分支仍按旧接口调用。
• 语义冲突：两边都能合并，但组合后控制逻辑矛盾，例如一个分支加入积分限幅，另一个分支依赖无限制积分。
• 数据冲突：标定文件与模型版本不匹配，导致参数被错误解释。

处理冲突的原则是：先定位冲突对象，再判断哪一侧符合当前基线目标，最后通过测试验证。不能只看“能否合并成功”，还要看“合并后是否还能通过关键测试”。

追溯与审计：从结果回到原因

追溯（Traceability）是建立需求、设计、模型、代码、参数、测试和缺陷之间的双向链接。控制原型中，追溯要能回答：这个增益为什么是 1.20？它对应哪条需求？哪次测试验证了它？如果现场出现问题，能追到哪个版本、哪次修订、哪个参数。

审计（Audit）是对版本治理过程的独立检查，关注的是“记录是否完整、变更是否受控、基线是否可复现”。审计不直接判断控制算法好坏，而是判断治理链条是否可信。例如审计会检查：每次基线发布是否有批准记录、每个标签是否对应可复现的构建、每次合并是否有测试证据。

在控制原型中如何落地

把上述概念落到日常操作，可以遵循几条具体规则。第一，每次提交必须写清“改了什么、为什么改、影响哪些对象”，避免只写“update”。第二，基线发布前必须完成一次可复现构建，记录模型版本、标定文件、测试脚本和工具链版本。第三，标签只用于关键节点，不要给每次提交都打标签，否则标签失去筛选价值。第四，合并前先跑接口一致性检查和关键测试，合并后再跑一次回归，确认没有引入语义冲突。第五，追溯链要覆盖“需求—模型—参数—测试—缺陷”，至少保证从任一参数能追到对应需求和验证记录。

以一个电流环整定为例：需求条目 REQ-017 要求“阶跃响应上升时间 ≤ 8 ms，超调 ≤ 5%”。开发者在功能分支 feat/current_loop 上把 Kp 从 0.85 调到 1.20，Ki 从 12 调到 18，提交修订说明并附上台架测试曲线。测试通过后，该分支合并回主干，打标签 bench_pass_0612，并纳入 M2 基线。若后续现场出现振荡，追溯链可以快速定位到这次参数修订，审计则检查这次修订是否有批准记录和测试证据。这样，版本治理就不是额外负担，而是控制原型可复现、可交付的基础设施。