specifying-mbd-algorithms

MBD 算法规范

面向基于模型设计（MBD）领域的算法结构化规范。改编自 specifying-software 模板。

适用场景

• 规范控制器、估算器、信号处理器、诊断或监督逻辑算法
• 算法将在 Simulink、Stateflow、System Composer 中编写，或作为 MATLAB Function 模块编写
• 算法属于基于模型的设计工作流（仿真、代码生成，或两者兼有）
• 创建、更新或审查算法规范文档

不适用场景

• 构建算法模型 → 使用 building-simulink-models
• 测试现有模型 → 使用 testing-simulink-models
• 对象／环境模型 → 使用 specifying-plant-models
• 传统软件（C、C++、Python、独立 MATLAB 脚本）→ 使用 specifying-software
• 完整闭环系统 → 算法侧使用此技能，对象侧使用 specifying-plant-models

输出约定

按算法存储规范。每个文件名都必须以算法名称为前缀：

docs/specs/algorithms/<algorithm-name>/
├── <algorithm-name>-system.md
├── <algorithm-name>-architecture.md
├── <algorithm-name>-implementation-plan.md
└── <algorithm-name>-test-plan.md

模式选择

这是一个单函数算法，运行模式少于 3 种、采用单速率，并将由一人／一个 Agent 构建吗？

• 是 → 快速规范：2 份文档（系统与架构合并，实施与测试合并）
• 否 → 完整规范：4 份独立文档

工作流

步骤 1：确定外部接口

确定此算法连接到哪些对象。如果已有系统，使用 model_overview 和 model_read 阅读。如果是全新设计，则根据需求定义边界。

对每个跨越算法边界的信号进行分类：

• 输入：来自其他子系统的测量值、命令、总线信号
• 输出：执行器命令、处理后的信号、状态／诊断标志
• 参数：可调（可标定）参数与固定（设计时）参数

步骤 2：定义算法目标

明确算法必须实现的目标——跟踪性能、带宽、抗扰能力、检测阈值、处理延迟等。这些是驱动架构决策和测试计划设计的验收标准。

步骤 3：领域验证 （如引用了方程、标准或领域惯例）

使用 web_search 确认规范中引用的关键方程、标准或惯例。在附录 B：研究说明中记录已确认的来源。

以下情况可跳过：算法完全基于逻辑、领域知识广为人知，或不涉及方程。

步骤 4：编写系统规范

模板：assets/system-spec-template.md

继续前设置审查关卡——确认：

• 算法目标明确，并包含量化的验收标准
• 外部接口约定完整（所有输入、输出、参数均注明单位和符号约定）
• 运行模式完整——是否定义了所有模式，包括启动、故障和降级模式？
• 执行器／效应器映射正确——哪个输出驱动哪个执行器，符号是否正确？
• 边界行为明确——饱和、过零、启用／停用阈值时会发生什么？

第 5 步：编写架构规范

模板：assets/architecture-spec-template.md

定稿前的审查关卡——请确认：

• 量纲一致性——端到端的所有接口单位一致
• 反馈极性——稳定回路采用负反馈，整个回路的符号正确
• 为每个积分器指定抗积分饱和和复位行为
• 模式转换逻辑——无扰切换、进入模式时初始化、不存在未经保护的转换
• 速率转换——正确处理多速率接口
• 执行器输出和各通道级别均有饱和与限幅
• 代数环——每条反馈路径都有明确的延迟元素，并在组件目录中注明其 IC 和 DFT 状态
• 如适用，处理代码生成约束（数据类型、调度、内存）

必需： 对任何尚未在相邻代码中使用过的 API、函数或模块行为进行 API 验证。使用 evaluate_matlab_code、web_search 或现有代码库中的用法，测试实际签名和行为。将结果记录在架构规范的附录 B 中。

第 6 步：编写实现计划 + 测试计划

模板：assets/implementation-plan-template.md、assets/test-plan-template.md

审查关卡——实现计划——请确认：

• 第 0 阶段的接口冻结是所有并行工作的前置关卡
• 构建顺序符合数据流依赖关系（先构建叶组件）
• 紧密耦合的组件分配给同一个 Agent，或进行协调
• 每个检查点都有具体的验证步骤（model_read、model_query_params、test）
• 参数表完整且注明来源

审查关卡——测试计划——请确认：

• 分阶段验证：组件 MIL → 集成 MIL → 系统在环 MIL → 鲁棒性 → SIL/PIL（如通过代码生成）
• 测试所有运行模式，包括启动和故障模式
• 模式转换场景包含无扰切换检查
• 饱和和抗积分饱和恢复测试
• 每项测试都有基于设计依据的定量验收标准
• 输入信号定义可在各阶段重复使用

开始实施前须获得用户批准。

更新现有规范

更新规范时：检查受影响的章节，更新这些章节，更新“Last Updated”日期，并检查与其他规范的一致性。

防护措施

始终

• 定稿前验证任何控制回路架构的反馈极性
• 端到端验证所有接口的单位和符号约定
• 在开始并行子系统工作前冻结接口（第 0 阶段）

先询问

• 添加系统规范中未列出的运行模式
• 第 0 阶段冻结后更改接口信号
• 偏离工厂或系统的采样时间对齐方式

切勿

• 在未指定积分器的抗积分饱和／饱和行为时实现控制
• 对应可校准的调参参数进行硬编码
• 省略多模式算法的模式转换规范
• 在连续时间路径中使用 Memory 模块打破代数环（离散情形使用 Unit Delay；连续情形使用具有较小时间常数的 Transfer Fcn）

规范类型

有关何时创建可选规范（详细规范、组件规范）的指导，请参阅 references/spec-types.md。当架构受以下因素阻碍时，请创建详细规范：控制律定义、状态机定义或接口契约。

参考资料

• assets/system-spec-template.md——系统规范模板（内容与原因）
• assets/architecture-spec-template.md——架构模板（功能分解）
• assets/implementation-plan-template.md——构建顺序模板
• assets/test-plan-template.md——验证计划模板
• references/algorithm-guidance.md——可选的领域研究检查清单
• assets/detailed-spec-template.md——控制律、状态机或接口契约（架构受阻时使用）
• assets/component-spec-template.md——复杂组件内部结构（很少需要）

---

Copyright 2026 The MathWorks, Inc.

---