matlab-create-experiment

为 Experiment Manager 创建实验

通过分析用户代码或问题描述，确定实验类型，并生成相应的实验函数、超参数表和实验对象，从而在 MATLAB Experiment Manager 中规划并创建实验。

适用场景

• 用户有 MATLAB 脚本/函数，并希望扫描参数或超参数
• 用户要求创建实验或比较配置
• 用户描述了一个问题，并希望探索参数空间
• 用户希望跟踪不同参数组合下的输出

不适用场景

• 用户正在调试现有实验或训练失败问题
• 用户想运行、恢复或查看现有实验的结果
• 用户已经设置好了可运行的 Experiment Manager 实验
• 用户想编辑实验设置（超参数、策略、描述）——请引导他们在 Experiment Manager 应用中进行更改。不过，可以编辑实验函数代码（.m 文件）。
• 用户想使用贝叶斯优化或随机采样策略——请引导他们在 Experiment Manager 应用中进行配置

---

自主性模型

此技能遵循指导 + 自主性模式。决策点带有以下标签：

标签	含义
[user]	始终暂停并询问。不可协商。
[auto]	Agent 自行决定，不作说明。失败时升级处理。
[depends]	根据线索是否明确来决定——明确时自动处理，有歧义时询问。

分析后，用一句通俗的话告知用户你打算如何开展工作。 始终补充：“如果你希望拥有更多或更少的控制权，请告诉我。”

---

阶段 1：分析

阅读用户的代码或问题描述，并对实验类型进行分类。

类型分类

根据 API 层面和语义线索，将实验分为以下三种类型之一。

重要： 如果语义线索表明涉及训练（即使没有显式调用 DL API）， 也应分类为训练——而不是通用类型。

类型	线索	模板类
通用	不使用 DL 函数，也没有训练指标。优化、仿真、数据分析。	'experiments.internal.experimentTemplates.MATLABFunction'
内置训练	使用 trainnet/trainNetwork/trainingOptions、标准层、数据存储。或者：文件名包含 "train"，用户提到 "classification"/"transfer learning"。	'experiments.internal.experimentTemplates.BlankTrainnetTraining'
自定义训练（自定义循环）	使用 dlnetwork/dlfeval/dlgradient/dlarray、手动梯度、GAN。或者：包含损失计算的训练循环，用户提到 "fine-tune"/"detector"。	'experiments.internal.experimentTemplates.CustomTraining'

分类优先级

1. 训练循环结构（迭代 epoch、跟踪损失）→ 自定义训练
2. 设置数据/层/选项，但没有循环 → 内置训练
3. 语义和 API 线索均未表明涉及训练 → 通用

发现变量

变量	标签	说明
实验类型	[depends]	线索明确时自动判断；有歧义时询问
要扫描的参数	[depends]	根据硬编码值自动推断；不明确时询问
参数值	[auto]	在硬编码值附近建议 2-3 个备选值
是否需要初始化函数	[auto]	检测到与参数无关的高开销操作时需要
函数签名	[auto]	根据类型确定（参见 REFERENCES.md）

退出条件：已确定类型、参数和输出。

---

阶段 2：设计

生成实验函数，并准备完整设计供用户审核。

1. 描述 — 创建一段 2-4 行的描述，涵盖：实验的作用、扫描的参数、每次试验捕获的输出，以及评估标准。

2. 参数 — 构建参数表（名称 | 值 | 描述）。

   • 硬编码值 → 提出 2-3 个相近的备选值
   • 分类值 → 列出合理的备选值
   • [auto] 如果试验总数 > 50，则发出警告（建议减少取值数量）

3. 函数签名 — 根据类型选择：

   类型	签名
   通用用途	[out1, out2, ...] = func(params)
   内置（形式 A，目标位于数据存储中）	[trainingData, net, lossFcn, options] = func(params)
   内置（形式 B，目标分开提供）	[trainingData, targets, net, lossFcn, options] = func(params)
   自定义训练	output = func(params, monitor)

   内置训练的最后 3 个输出必须始终为 net、lossFcn、options。 有关形式 A 与形式 B 的选择指南以及支持的损失函数，请参阅 references/REFERENCES.md。

4. 生成实验函数 — 将用户的代码改写为实验函数。

   展示时的标题约定：

   • 通用用途 → “生成的实验函数”
   • 内置训练 → “生成的设置函数”
   • 自定义训练循环 → “生成的训练函数”

   关键规则：

   • 对所有可调值使用 params.<field>（绝不要硬编码扫描值）
   • 每个 params.<field> 都是单个标量值（数值、字符串或逻辑值）——Experiment Manager 会为每次试验分配一个值。绝不要在函数内循环遍历参数值；扫描由外部处理。
   • 在 trainingOptions 中使用 'Plots', 'none'
   • 包含 H1 帮助注释块
   • 所有文件/数据引用都使用绝对路径——请参阅 REFERENCES.md §“绝对路径规则”
   • 有关自定义训练监视器模式，请参阅 REFERENCES.md §“自定义训练监视器模式”

   类型	函数体包含	返回值
   通用用途	用户的计算逻辑，包括图形/绘图代码	命名输出（任何可序列化类型）
   内置训练	数据加载、网络定义、trainingOptions	[data..., net, lossFcn, options]
   自定义训练	集成监视器的训练循环，包括图形/绘图代码	output（任何可序列化类型）

5. [auto] 初始化函数 — 如果检测到与超参数无关的一次性高开销操作（数据下载、大型文件加载、不依赖 params 的数据存储），则将其提取到初始化函数中。 有关代码模板，请参阅 references/REFERENCES.md §“初始化函数模板”。

---

阶段 3：确认

门槛：[user] — 提交设计供审核，然后再执行。

必须遵守： 创建任何文件或运行任何 MATLAB 代码之前，务必先展示设计并等待用户明确确认。即使用户之前确认过类似实验，也绝不能跳过此门槛。唯一例外是用户明确表示跳过确认（例如“直接创建，不用询问”）。

展示顺序很重要：

1. 生成的实验函数代码
2. 生成的初始化函数代码（如适用）
3. 汇总表
4. 询问是否确认

不要在函数代码之前展示汇总表。

汇总表：

主题	详情
实验类型	<所选类型及原因>
参数/超参数	<逗号分隔的列表>
试验总数	<数量>
函数名称	<functionName>
初始化函数	如果已生成，则为 <initFunctionName>；否则说明未生成的原因
关键指标	<指标名称>（<最小化/最大化>）
实时记录的指标	<逗号分隔的列表>

仅在用户确认后继续进入阶段 4。

---

阶段 4：创建与验证

在 MATLAB 中执行实验设置。

4a：项目设置 [auto]

1. 检查 currentProject — 如果已打开，则使用它；否则创建一个新项目
2. 绝不要关闭或替换已打开的项目。 如果 currentProject 成功，则始终使用该项目 — 将实验函数和 .mat 文件写入其根文件夹。仅在没有打开项目时调用 matlab.project.createProject。
3. matlab.project.createProject 会更改 pwd — 之后直接使用 pwd，不要在前面拼接文件夹
4. 项目创建后，使用 writelines 将函数文件写入项目根目录
5. 创建新项目时生成唯一的文件夹名称（追加 _2、_3）

完整代码请参阅 references/REFERENCES.md § "Step 6 Code Template"。

4b：创建实验对象 [auto]

使用 createExperiment 辅助函数（位于 scripts/ 中）。它会：

• 根据 params 结构体构建超参数表
• 生成唯一的 .mat 文件名（绝不覆盖）
• 根据文件名设置实验名称
• 添加到项目中

4c：验证 [auto]

运行验证前，简要告知用户验证内容：“我正在验证函数是否位于路径上、能否通过静态分析、签名是否正确，以及参数引用是否与超参数表匹配。”

路径可移植性检查： 验证前，扫描生成的函数中是否有相对文件路径。如果有，则解析为绝对路径并重写。

运行分层验证（参见 REFERENCES.md § "Validation"）：

1. 第 0 层 — 存在性： 通过 which() 确认函数位于路径上
2. 第 1 层 — 静态分析： 运行 checkcode()。严重级别 > 1 时阻止继续（错误）。严重级别 ≤ 1 时发出警告。
3. 第 2a 层 — 签名： 验证 nargin 和 nargout 是否符合实验类型：
   • general：nargin=1，nargout≥1
   • builtin_A：nargin=1，nargout=4
   • builtin_B：nargin=1，nargout=5
   • custom：nargin=2，nargout=1
4. 第 2b 层 — 参数覆盖： 解析函数源代码中的 params.<field> 引用。 如果函数引用了超参数表中没有的参数，则验证失败。如果表中的条目未使用，则发出警告。

门槛：[auto] — 验证结果

• 所有层级均通过 → 打开 Experiment Manager（参见 REFERENCES.md § "Open Experiment Manager"）
• 遇到阻止继续的失败 → 修复并重写 .m 和 .mat 文件，然后重新验证（最多 2 次）
• 2 次尝试后仍失败 → [user] 上报并提供错误详情

---

第 5 阶段：交接

创建实验并打开 Experiment Manager 后：

你的实验已在 Experiment Manager 中就绪！开始运行前，你可以进行以下操作：

建议的编辑操作：

• 在 Hyperparameter Table 中编辑超参数值或添加新参数
• 修改实验描述
• 在 Experiment Manager 应用中打开并调整函数：
  • 通用用途 → “实验函数”
  • 内置训练 → “设置函数”
  • 自定义训练循环 → “训练函数”
• 在应用界面中添加或配置初始化函数

准备就绪后，点击 Experiment Manager 工具栏中的 Run，开始运行试验。

---

关键规则

1. 始终创建新文件——绝不覆盖现有文件（追加数字后缀）。
2. 在 MATLAB 中编写函数文件——直接使用 writelines 写入项目文件夹。
3. 保留用户逻辑——将代码改编为实验函数；不要重写用户的算法。
4. 不绘制训练进度图——在 trainingOptions 中使用 'Plots', 'none'（仅限内置训练）。对于通用训练和自定义训练，保留用户的图形/绘图代码。
5. 使用 params struct——所有可调值都从 params 获取，不要硬编码。
6. 基于项目——实验必须位于 MATLAB 项目中。
7. 名称唯一——为函数和实验文件生成描述性且唯一的名称。项目名称使用后缀 Project，实验名称使用后缀 Experiment（例如，AntennaProject、AntennaExperiment）。
8. 绝不暴露内部 API——不要向用户展示模板类名称。
9. 使用绝对路径——所有文件引用都必须使用带有绝对路径组件的 fullfile()。

有关模板类、签名映射和常见超参数，请参阅 references/REFERENCES.md。

---

错误恢复

错误	修复方法
验证失败	修复函数、重写 .mat 文件，然后重新验证（最多尝试 2 次）
找到相对路径	根据源脚本目录解析为绝对路径，然后重写
项目未打开且无法创建	询问用户项目位置
超过 50 次试验	发出警告，建议减少取值
实验类型不明确	请用户澄清
文件已存在	追加数字后缀（_2、_3、...）
无法解析路径	询问用户完整路径

---

版权所有 2026 The MathWorks, Inc.