specifying-plant-models

被控对象模型规格

用于闭环仿真的被控对象模型结构化规格。将 specifying-software 模板改编用于物理建模领域。

适用场景

• 创建被控对象模型，与现有控制器构成闭环
• 更新或扩展现有被控对象模型规格
• 在构建被控对象模型前编写规格
• 确定模型架构（子系统分解、保真度级别）
• 规划被控对象模型的验证

不适用场景

• 构建被控对象模型 → 使用 building-simulink-models
• 测试现有被控对象模型 → 使用 testing-simulink-models
• 控制器算法或 MBD 算法规格 → 使用 specifying-mbd-algorithms
• 传统软件的规格（C、C++、Python、MATLAB 脚本）→ 使用 specifying-software
• 完整闭环系统的规格 → 算法部分使用 specifying-mbd-algorithms，被控对象部分使用此技能

输出约定

为每个被控对象模型分别存储规格。每个文件名都以被控对象名称为前缀，确保文件在编辑器标签页、搜索结果和平铺列表中都能清楚识别：

docs/specs/plant-models/<plant-name>/
├── <plant-name>-system.md              # What & why
├── <plant-name>-architecture.md        # Subsystem decomposition
├── <plant-name>-implementation-plan.md # Build sequence
└── <plant-name>-test-plan.md           # Validation plan

以名为 motor 的被控对象为例：

docs/specs/plant-models/motor/
├── motor-system.md
├── motor-architecture.md
├── motor-implementation-plan.md
└── motor-test-plan.md

模式选择

该被控对象是否状态数少于 5、具有单速率动态、没有强非线性，并且将由一名人员/Agent 构建？

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

文档边界

规格	回答的问题	不包含的内容
系统	我们要构建什么，为什么？	子系统分解、方程
架构	它的结构是什么？	Simulink 模块细节、参数值
实施计划	如何构建它？	实际的 model_edit 命令
测试计划	如何验证它？	测试执行结果

在快速模式下，将系统与架构合并为一份文档，将实施与测试合并为另一份文档。

工作流

步骤 1：分析控制器接口

使用 model_overview 和 model_read 读取控制器模型。将每个信号分类为：

• u（来自控制器的命令输入）、w（外生扰动）、
• y（发送给控制器的测量输出，包含传感器效应）、z（用于调试的真实值输出）

定义被控对象边界并记录采样时间。

步骤 2：评估验证依据

在研究领域知识之前，先确认现有依据：测试数据、数据手册、标准工况、解析预期、参考模型。

保真度必须由可用的依据支撑——无法验证的动态特性不值得建模。预期用途也很重要：MIL 快速迭代可以接受较低保真度；HIL/代码生成则需要满足固定步长和实时约束。

步骤 3：研究物理领域

使用 web_search 和 read_web_page 查找标准建模方法、参考参数和权威来源。如有需要，可查阅 references/plant-model-guidance.md 了解跨领域模式。

步骤 4：编写系统规格

使用 assets/system-spec-template.md。被控对象模型的关键部分：运行场景、物理模型要求、控制器接口契约（u/w/y/z 的采样时间、数据类型、单位）、初始化与工作点、速率与时序对齐、验证依据、参考来源。

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

• 接口要求完整（涵盖 u、y 信号）
• 保真度适合预期用途，且有可用的验证依据支撑
• 运行场景覆盖控制器的工作范围
• 已指定可行的工作点/初始化策略
• 已明确与控制器的速率/采样时间对齐方式
• 每项主要要求都有明确的验证参照

继续之前请先让用户评审。

步骤 5：编写架构规范

使用 assets/architecture-spec-template.md。关键的被控对象模型章节：组件目录（包含物理领域和端口接口）、各子系统的运动方程、非线性与约束、数值注意事项（求解器、刚性、代数环）、参数管理、不确定性接口。

定稿前的评审关卡——请核实：

• 物理分解正确——子系统边界应位于自然的领域边界
• 从 u 经由动力学到 y 的信号流完整
• 扰动 w 在正确位置引入
• 接口一致：端到端的单位、符号约定、坐标系
• 已处理 DAE／代数环风险；遵守守恒定律
• 已包含会影响控制器的缺失动力学（执行器限幅、传感器噪声、传输延迟）

继续之前先取得用户评审意见。

步骤 6：编写实施计划和测试计划

使用 assets/implementation-plan-template.md 和 assets/test-plan-template.md。

实施计划要点：

• 阶段 0（接口契约和桩模块）是所有并行工作的前置关卡——先冻结端口、单位和符号约定
• 松耦合子系统（传感器、执行器、负载、环境）可在阶段 0 之后由不同 Agent 并行构建；紧耦合拆分（逆变器↔电机、轮胎↔底盘）则需要协调
• Model References 可实现最有效的并行开发（使用单独的 .slx 文件）
• 参数表：每个参数都应包含名称、值、单位、来源、模块路径
• 同步点使用 model_read 验证，并通过 model_query_params 抽查

测试计划要点：

• 三阶段验证：子系统开环 → 集成开环 → 闭环
• 输入信号定义及其参数（阶跃、斜坡、正弦扫频）
• 将 Gherkin 场景映射到 model_test 格式
• 设置具有物理依据的定量验收标准

评审关卡——实施计划——请核实：

• 自底向上的构建顺序切实可行（先构建叶子子系统）
• 阶段 0 接口桩模块可作为并行工作的前置关卡
• Simulink 模块类型符合物理特性
• 求解器选择符合刚性情况和离散元素的要求
• 参数表完整，包含来源和单位

评审关卡——测试计划——请核实：

• 验证阶段安排：子系统开环 → 集成开环 → 闭环（MIL）
• 若被控对象面向 HIL，已评估实时执行可行性
• 每种机动均指定：输入、输出、比较方法、验收标准
• 已包含参数灵敏度检查
• 已包含数值鲁棒性测试（求解器容差、步长）
• Gherkin 场景可通过 model_test 执行

开始构建之前先取得用户批准。

护栏

始终遵守

• 在每个接口处将信号分类为 u/w/y/z
• 为每个参数注明来源（值、单位、来源、不确定性、适用条件）
• 选择保真度级别前评估验证证据
• 按自然的领域边界划分子系统（执行器、动力学、传感器、环境、负载）

先行询问

• 系统规范获批后更改保真度级别
• 添加架构规范中未列出的子系统
• 偏离控制器的采样时间对齐方式

绝不

• 在规范中重现教科书推导——应引用权威来源；针对特定领域的研究请使用 web_search
• 对无法根据现有证据验证的动力学进行建模
• 计划并行构建时跳过阶段 0 接口桩模块
• 使用未经审核来源的 web_search 结果——优先采用标准、教科书、MathWorks 文档和同行评审论文

参考资料

• assets/system-spec-template.md — 系统规范模板（是什么及原因）
• assets/architecture-spec-template.md — 架构模板（子系统分解）
• assets/implementation-plan-template.md — 构建顺序模板
• assets/test-plan-template.md — 验证计划模板
• references/plant-model-guidance.md — 可选的领域参考资料（分解示例、验证操作、求解器指南）。供人阅读；请勿逐字复制到规范中。

---

版权所有 2026 The MathWorks, Inc.

---