generate-requirement-drafts

生成需求草案

根据环境支持的最丰富工件，从 Simulink 模型生成需求草案。所有输出均为草案，在建立基线之前需要人工审查和批准。

适用场景

• 根据 Simulink 模型起草或更新需求
• 创建 .slreqx 或 .yaml 需求工件
• 建立模型到需求的可追溯性

不适用场景

• 从现有的事实来源（ReqIF、DOORS、Word、Excel）导入需求——直接使用 Requirements Toolbox 导入 API
• 编写或运行测试——使用 testing-simulink-models 技能
• 不保存为工件的自由格式文本笔记
• 用户明确要求使用其他文本格式（markdown、Word）

输出约定

• 默认文件名：<Model>_Requirements.slreqx 或 <model>_requirements.yaml
• 稳定 ID：REQ_<SYSTEM>_001、REQ_<SYSTEM>_002……——在整个项目中使用一个一致的前缀，并为所有需求使用连续的整数，即使这些需求源自不同的子系统。不要改用按子系统划分的前缀或分层小数编号（例如 CB-1.1、TP-1.1）。
• 如果仓库中已有 .slreqx 或 .yaml 文件，则遵循现有约定
• 更新现有工件时，保留已有 ID——追加新 ID，绝不重新编号
• 每条生成的需求都必须标记为草案——在 Keywords 中使用 "draft"（slreq），或在 YAML 中使用 status: Draft + keywords: [draft]

编写优质需求

需求必须表达行为意图（系统应做什么），而不是复述模型拓扑（如何实现）。在 Rationale 中说明原因。使用 **EARS（需求句式简易方法）**模式：

EARS 模式

选择最符合模型行为的模式：

模式	模板	适用场景
通用	The <system> shall <response>.	始终启用的行为、不变量
事件驱动	When <trigger>, the <system> shall <response>.	瞬时触发导致一次性响应：输入事件、进入 Stateflow 状态（转换本身）
状态驱动	While <state>, the <system> shall <response>.	在 Stateflow 状态或模式下持续保持的行为——持续响应，而非进入状态的转换
非预期行为	If <condition>, then the <system> shall <response>.	错误处理、安全限值、饱和
可选功能	Where <feature>, the <system> shall <response>.	变体子系统、可配置功能
组合	While <state>, when <trigger>, the <system> shall <response>.	状态与事件的组合

示例——将模型概念转化为 EARS 需求

❌ 不佳——复述实现方式	✅ 良好——EARS 模式
"Saturation block limits output to [0,1]"	"如果油门指令超过 ThrottleMax (1.0) 或低于 ThrottleMin (0.0)，控制器应将输出限制在有效范围内。"
"BrakeLogic subsystem disengages controller"	"当制动踏板输入超过 BrakeThreshold (0.0) 时，控制器应退出巡航控制。"
"Gain block multiplies by 2.5"	"巡航控制处于启用状态时，控制器应将速度误差放大 Kp (2.5) 倍，以计算比例校正量。"
"Stateflow chart transitions to Idle"	"当驾驶员按下关闭按钮时，系统应转换到 Idle 状态。"
"Defrost state runs the heater at full power"	"处于 Defrost 状态时，系统应以满功率驱动加热器。"
"Variant subsystem selects Algorithm A"	"自适应模式启用时，控制器应使用预测算法。"

规则

• 使用 EARS 模式编写需求——选择与模型行为相匹配的模式
• 仅在 Rationale、Description 或来源说明中使用模块／子系统名称（例如 Saturation、BrakeLogic）——绝不能在需求的 Summary 中使用。（以 VarName (value) 格式呈现的工作区参数必须写在 Summary 中，且不属于模块名称。）
• 引用数值时，必须包含工作区变量名和解析后的值：VarName (value)。如果模型使用的是没有对应变量的字面值，则直接记录该数值字面值
• 将原因写在 Rationale 中，而不是需求陈述中
• 一个子系统可以支撑零个、一个或多个行为需求——不要强行建立一对一映射
• 对于 Stateflow 状态或模式，应将进入该状态或模式与处于该状态或模式分开：进入转换由事件驱动（When <trigger>, … shall transition to <state>），而贯穿整个模式的行为由状态驱动（While <state>, … shall <response>）。当询问某个模式的行为时，优先使用 While <state> 形式——不要将其合并到 When 进入语句中

后端决策门

在开始时选择一次，然后始终沿用该路径。

情况	后端
用户明确要求 .slreqx、可追溯性视图，或仓库已使用 .slreqx	Requirements Toolbox——如果探测失败，告知用户 Requirements Toolbox 不可用；不要静默回退
用户明确要求 .yaml，或仓库已使用 .yaml 需求文件	结构化 YAML
未指定格式——探测 Requirements Toolbox	探测成功时使用 Requirements Toolbox
未指定格式且探测失败	结构化 YAML（用户没有指定偏好时，可以静默回退）

探测（通过 evaluate_matlab_code 运行）：

hasSlreq = ~isempty(which('slreq.new'));
if hasSlreq, try, slreq.find(Type="Link"); catch, hasSlreq = false; end, end
disp(hasSlreq)

工作流

• 将 model_overview、model_read、model_query_params、model_resolve_params 作为 MCP 工具调用——绝不要将它们的名称传递给 evaluate_matlab_code。
• evaluate_matlab_code 仅用于 MATLAB 代码，例如后端探测和路径 A 中的 slreq.* API。

1. 理解模型——使用 model_overview 和 model_read 工具了解子系统、接口和控制逻辑。

2. 提取参数——使用 model_query_params / model_resolve_params 工具查找应出现在需求文本中的阈值、增益、采样时间。记录变量名及解析后的值。

3. 构建捕获表（与后端无关）：

   Id	ParentId	Summary	Description	SourceBlock	Rationale	ASIL	Priority	Keywords

4. 运行后端路径（以下 A 或 B）。

5. 使用下方的门槛进行审核。

路径 A——Requirements Toolbox（.slreqx）

探测成功时使用。完整 API 模式请参阅 references/slreq-patterns.md。

model = "CruiseControl";
load_system(model);
rs = slreq.new(model + "_Requirements");

% Add requirements with hierarchy — note behavioral "shall" statements
req = add(rs, Id="REQ_CC_001", ...
    Summary="If throttle command exceeds ThrottleMax (1.0) or falls below ThrottleMin (0.0), then the controller shall clamp the output to the valid range.", ...
    Description="Derived from CruiseControl/ThrottleCmd.");
req.Rationale = "Prevents invalid actuator commands that could damage the throttle body.";
req.Keywords = ["draft","auto-generated","control","safety"];

child = add(req, Id="REQ_CC_002", ...
    Summary="When brake pedal input exceeds BrakeThreshold (0.0), the controller shall disengage cruise control.", ...
    Description="Derived from CruiseControl/BrakeLogic.");
child.Keywords = ["draft","auto-generated","safety","brake"];

% Create traceability links: use block handle from SID (blk_X → X) for robustness
lnk = slreq.createLink(Simulink.ID.getHandle(model + ":5"), req);
slreq.createLink(Simulink.ID.getHandle(model + ":8"), child);

save(rs);
% Save all link sets
linkSets = slreq.find(Type="LinkSet");
for i = 1:numel(linkSets), save(linkSets(i)); end

链接规则：

• 源 = 模型元素，目标 = 需求 → 链接类型自动设为 Implement
• 优先使用子系统级链接；仅当需求特定于某个模块时才使用模块级链接
• 每项源自模型的需求必须至少有一个可追溯性链接
• 使用模块路径创建链接之前，必须加载模型（load_system）

路径 B——结构化 YAML 回退

Requirements Toolbox 不可用时使用。架构和字段规则请参阅 references/yaml-requirements.md。

1. 根据捕获表生成 <model>_requirements.yaml 文件
2. 将 status: Draft 设为每项需求的状态，并在每项需求的 keywords 中包含 draft
3. 自我审核：设置所有必填字段；asil／status／priority 使用有效值；ID 连续；derived_from 引用有效 ID 或为 null
4. 验证：

python -c "import yaml, sys; yaml.safe_load(open(sys.argv[1])); print('OK')" path/to/requirements.yaml

防护措施

始终	切勿
将每条生成的需求标记为 DRAFT	当 .slreqx 可用且用户未要求文本格式时，输出 Markdown 或临时文本
使用 EARS 模式编写需求	将块拓扑重新表述为需求摘要
包含参数名称和值：VarName (value)	除非用户要求同时提供，否则不要同时创建 .slreqx 和 .yaml
链接方向：模型元素 → 需求	反转链接方向（需求 → 块）
创建可追溯性链接前先调用 load_system	为每个基本块都创建过多链接——优先链接子系统
仅使用 R2023a+ API	用户明确要求 .slreqx 时，悄悄改用 YAML
与现有仓库格式保持一致	重新生成时重新编号已有需求 ID

审核关卡

完成前，请验证（两种后端均适用）：

• 每条需求都包含 Id、Summary 和 Description
• 每条需求都标记为 DRAFT（通过 Keywords 或状态字段）
• 摘要使用 EARS 模式，而非对块拓扑的重新表述
• 存在工作区变量时，数值应包含参数名称和值
• ID 稳定且连续；重新生成时保留已有 ID

仅适用于 slreq 路径：

• 从模型派生的需求具有指向源模型元素的可追溯性链接
• 链接方向为模型元素 → 需求（不可反向）
• 优先在子系统级别而非块级别建立链接
• 已保存需求集和所有链接集

仅适用于 YAML 路径：

• 文件解析无错误
• asil 和 priority 使用有效的枚举值（未知时使用 Unset）

参考资料

• references/slreq-patterns.md — Requirements Toolbox API 操作手册
• references/yaml-requirements.md — 结构化 YAML 架构和字段规则
• assets/slreq_from_model.m — 端到端 slreq 示例
• assets/requirements.yaml — 结构化 YAML 示例

---

版权所有 2026 The MathWorks, Inc.

---