author-modeladvisor-checks

编写 Model Advisor 检查项

适用场景

• 用户提出任何建模约束（例如“模块必须……”“信号必须匹配……”）
• 用户要求制定建模指南
• 用户要求编写、实现或撰写 Model Advisor 检查项
• 用户要求测试、评定或验证自定义检查项
• 用户提到“强制执行”“标准”“合规规则”或“建模规则”

不适用场景

• 对现有模型进行事后合规检查——使用 checking-model-compliance
• 不涉及强制执行要求的一般模型构建——使用 building-simulink-models
• 运行现有检查项或查看结果——直接使用 Model Advisor

关键：审核关卡

你是控制整个工作流的状态机。流程参考文件说明了如何执行每个步骤——你需要阅读相关细节，并在流程中执行其中的操作。

共有 3 个审核关卡和 1 个条件关卡。在这些关卡处，你必须暂停并请用户选择后再继续。如果用户提供反馈，请将其纳入流程。如果用户选择推荐选项，请立即继续。

如果用户的提示中包含“无需询问，直接继续”“跳过确认”“无需确认即可继续”或类似表述，则跳过所有审核关卡，并直接完成整个工作流。此模式下不得使用 AskUserQuestion 或任何交互式工具。

审核关卡（使用描述性名称——绝不要说“关卡 1”“关卡 2”或“关卡 3”）：

1. 指南 ID 与范围审核——推导出 ID 后、编写指南前
2. 检查项规格审核——生成检查项规格后、实现前
3. 测试计划审核——生成测试规格后、实现测试前

条件关卡（介于步骤 2 和步骤 3 之间）：

• 指南与测试衔接——编写检查项后，检查是否存在指南文档。如果不存在，请询问用户是否在其他位置有该文档，或者是否希望创建一个，然后询问是否继续测试。如果指南存在，则静默跳过此关卡。

在各审核关卡之间，直接继续，无需暂停。对于操作性决策（例如加载哪个参考文件、使用哪种模式、如何组织代码），不要征求用户意见。

关键——仅向用户展示以下内容： 用户只能看到决策点、创建完成后的产物摘要，以及最终报告。不要透露内部工作流细节——不得提及步骤转换、参考文件名称、模式选择或关卡编号。沟通内容应聚焦于用户需要审核的事项或已生成的内容。

此技能的工作方式

你是唯一的入口点——所有领域知识都位于 references/ 中。根据当前步骤，参照下表按需加载文件。遵循每个文件 frontmatter 中的 related: 链接，以了解其他相关背景。

在审核关卡之间积极推进。仅在 3 个审核关卡和条件关卡处暂停。如果用户说“停止”或“不”，请立即停止（参见下文“停止与清理”）。

参考目录（完整说明见 references/index.md）：

步骤	加载内容	文件
1 — 指南	流程	procedures/author-guideline.md
2 — 检查项	流程 + 模式 + API	procedures/author-check.md、patterns/{standard,edittime,config-param,format-template}.md、apis/{blocks,signals,stateflow,data-resolution,code-analysis,system-composer,framework}.md
3 — 测试	流程 + 模板	procedures/test-check.md、templates/{test-spec,test-recipes}.md
旧版	工作流	workflows/legacy-conversion.md
规格格式	模板	templates/{guideline,check-spec}.md

入口：检测意图

匹配符合条件的第一行（顺序很重要——特定检查的意图优先）：

用户说	转到
“测试/验证我的检查……”	STEP 3
“编写/撰写/创建一项检查……” / “实现一项检查” / “创建一项 Model Advisor 检查……”	先询问用户是否需要先编写指南，然后转到 STEP 2
“创建指南” / “强制执行……” / “编写标准” / 未提及“检查”的建模约束	STEP 1（完整流程）

重要 — “编写/创建检查”意图的入口： 当用户提到“检查”（编写、撰写、创建、实现）时，始终先询问：

Would you like me to also create a formal guideline document for this rule, or just the check implementation?

选项：

1. “从指南开始（完整流程）（推荐）”——转到 STEP 1
2. “只创建检查，跳过指南”——直接转到 STEP 2

如果提示明确说“只创建检查”或“跳过指南”，则直接转到 STEP 2，无需询问。

如果提示说“跳过指南和测试”或“只创建检查——跳过指南和测试”，则转到 STEP 2，编写检查后立即呈现最终报告（不要继续到 STEP 3）。

如果提示包含“无需询问，直接继续”或“跳过确认”，则跳过此问题，直接转到 STEP 2。

---

STEP 1：编写指南

推导默认值：

• 指南 ID：使用 cust_ 前缀和顺序编号（可选添加简短描述），例如 cust_0001、cust_0002_unitygain。
• 输出文件夹：使用当前工作目录。创建一个以指南 ID 命名的子文件夹：./<guideline_id>/

指南 ID 和范围审核 — 暂停并询问用户：

展示推导出的默认值并请求确认：

I've derived: Guideline ID = `<id>`, Check ID = `mathworks.custom.<id>`, Output = `./<id>/`
Scope: <1-line summary of what the guideline will cover>

选项：

1. “使用这些 ID（推荐）”——继续使用推导出的默认值
2. “我想提供自己的 ID”——由用户提供自定义 ID，并将其纳入

如果用户选择选项 2，则纳入其更改。否则立即继续。

**执行：**按照 references/procedures/author-guideline.md 编写指南。

产物通知（简短，不加叙述）：

Guideline `<id>`: <title>
  → ./<id>/guideline_<id>.md
  → ./<id>/compliant_<short>.slx
  → ./<id>/violating_<short>.slx
  → ./<id>/example_correct.png (or text table if parameter-focused)
  → ./<id>/example_incorrect.png (or text table if parameter-focused)

立即继续到 STEP 2——不要等待用户输入。

---

步骤 2：生成检查规范并编写检查

指南 ID 与范围审查——暂停并询问用户：

如果直接进入（并非从步骤 1 进入），请先展示 ID 与范围审查关卡，再继续。如果从步骤 1 进入，ID 已确认——请沿用该 ID 并跳过此关卡。

需要经过此关卡时，使用 cust_ 前缀生成默认 ID（格式与步骤 1 相同），并请用户确认。

执行规范： 按照 references/templates/check-spec.md 生成检查规范文档，并将指南和用户的原始约束作为输入。保存到 <output_dir>/<id>-check-spec.md。

向用户展示规范，使用 references/templates/check-spec.md 中定义的摘要格式——展示关键字段（ID、标题、类型、上下文、自动修复）和需求表。最后注明保存路径。

检查规范审查——暂停并询问用户：

请用户在实现前审查检查规范：

选项：

1. “看起来不错，继续实现（推荐）”
2. “我想修改规范”

如果用户选择选项 2，请等待用户反馈，相应更新规范文档，然后继续。否则立即继续。

执行检查： 按照 references/procedures/author-check.md 操作，并使用（可能已更新的）规范作为输入。根据检查类型读取相应的模式和 API 参考文件。使用 check_matlab_code 进行验证，直到警告/错误数量为 0。

工件通知（简要）：

Check authored: define<Name>.m
Registration: sl_customization.m
  → <path>

指南扫描与过渡关卡：

继续测试前，扫描输出文件夹，查找指南文档（guideline_*.md）。

• 如果指南已存在（例如，之前已执行步骤 1），请跳过此关卡并直接继续步骤 3。

如果不存在指南文档：

1. 暂停并请用户从以下选项中选择：
   • “跳过指南，继续测试（推荐）”——继续步骤 3
   • “我在其他位置有指南文档”——用户提供路径，将其复制/链接到输出文件夹，然后继续步骤 3
   • “先创建正式指南”——先执行步骤 1（author-guideline 过程），再继续步骤 3
   • “跳过指南并跳过测试”——仅展示包含检查工件的最终报告

如果用户选择“我在其他位置有指南文档”，请询问路径，读取该文档，并将其用作推导测试的源指南。

如果用户选择“先创建正式指南”，请使用编写检查时所用的约束执行步骤 1，然后返回此处继续步骤 3。

通过关卡后继续步骤 3。

---

步骤 3：生成测试规范并通过测试进行验证

**重要 — TDD 独立性：**只能根据准则和用户的原始约束推导测试用例。绝不可读取检查规范或实现。参见 references/procedures/test-check.md § TDD 独立性防护。

**执行测试规范：**按照 references/templates/test-spec.md 生成测试规范文档，并以准则和用户的原始约束为输入。保存到 <output_dir>/<id>-test-spec.md。

向用户展示测试规范，使用 references/templates/test-spec.md 中定义的摘要格式——显示关键字段（准则 ID、检查 ID、检查类型、自动修复）和测试用例表。最后给出保存路径。

测试计划审查 — 暂停并询问用户：

请用户在实现前审查测试规范：

选项：

1. “看起来不错，继续生成测试（推荐）”
2. “我需要修改测试计划”

如果用户选择选项 2，请等待其反馈，根据反馈更新测试规范，然后继续。否则立即继续。

**执行测试：**按照 references/procedures/test-check.md 操作，并使用（可能已更新的）测试规范作为输入。运行测试并展示结果（通过 N 项，失败 N 项）。

重要 — 测试执行重试上限： 如果初次运行后测试失败：

• 分析失败的根本原因（模型问题、检查逻辑问题或测试断言问题）
• 应用有针对性的修复
• 重新运行测试
• **最多重试 3 次。**如果重试 3 次后测试仍然失败，请停止并如实报告状态：

  Tests: X passed, Y failed (after 3 fix attempts)
  Remaining failures: <list with brief description>
  Recommended next steps: <what the user should investigate>
  

• 不要进入无止境的修复循环

**测试完成（或达到重试上限）后，展示最终报告。**工作流结束。

---

停止与清理

如果用户在乐观执行期间的任何时候说“stop”“no”“halt”或“don't continue”：

1. 立即停止——不要开始下一步
2. 删除当前正在进行的步骤中的产物（尚未完成）：
   • 如果在步骤 2 期间停止：删除正在生成的检查规范、检查定义 .m 和 sl_customization.m 条目
   • 如果在步骤 3 期间停止：删除正在生成的测试规范、测试类 .m 和测试模型 .slx 文件
3. 保留所有已完成步骤的产物——如果步骤 1 已完成，则保留准则；如果步骤 2 已完成，则保留检查
4. 展示最终报告，说明保留和删除的内容

---

最终报告

在工作流完成（所有步骤均已完成）或停止时展示：

## Workflow Summary

| Step | Artifact | Path | Status |
|------|----------|------|--------|
| Guideline | <id>: <title> | <path> | Done / Skipped |
| Demo Models | compliant.slx, violating.slx | <path> | Done / Skipped |
| Screenshots | example_correct.png, example_incorrect.png | <path> | Done / Skipped |
| Check Spec | <id>-check-spec.md | <path> | Done / Removed |
| Check | define<Name>.m | <path> | Done / Removed |
| Registration | sl_customization.m | <path> | Done / Removed |
| Test Spec | <id>-test-spec.md | <path> | Done / Removed |
| Tests | Test<Name>.m | <path> | Done / Removed |
| Test Models | <list>.slx | <path> | Done / Removed |

**Status:** <Pipeline completed / Halted at <step description> by user request>

---

版权所有 2026 The MathWorks, Inc.

---