matlab-build-app

MATLAB 应用构建

确定 MATLAB 应用的最佳架构，基于内部参考资料制定实现计划，并执行构建。对于 UIFigure 应用，可选择将其序列化为 App Designer 格式。

适用场景

在以下情况下使用此技能：

• 用户想要构建 MATLAB 应用、GUI 或交互式工具
• 用户询问“我该如何构建这个应用？”或“我该采用哪种方案？”
• 用户描述了一个应用，无论是否指定实现路径
• 用户提到：MATLAB 应用、GUI、uifigure、uihtml、交互式工具、仪表板、可视化应用、App Designer、.mlapp、纯文本应用
• 用户描述了空间布局需求：仪表板、控制面板、侧边栏、选项卡、向导、步骤指示器、画布、工作区
• 用户已经选择了实现路径（例如，“为我构建一个 uihtml 应用”）——直接处理

不适用场景

• 请求纯粹涉及 MATLAB 计算，不包含 UI 组件
• 用户想修改现有应用 → 阅读 references/editing-guide.md
• 用户想在 App Designer 格式之间转换（例如，将 .mlapp 转为纯文本，或反向转换）→ 告知用户在 App Designer 中使用 File > Save As。不要尝试以编程方式转换。

关键规则

• 除非用户已指定实现路径，否则必须先询问探索性问题，再推荐方案
• 制定实现计划前，必须先与用户确认所选方案
• 编写任何代码前，必须基于内部参考资料制定实现计划
• 必须将计划写入工作目录中的文件（<app-name>-plan.md）
• 除非用户已预先指定实现路径，否则绝不能在未了解用户约束的情况下推荐方案
• 除非用户明确要求，否则绝不能应用深色模式、自定义颜色或视觉主题
• 始终将推荐作为指导而非强制要求——由用户决定
• 必须根据用户的主要任务选择应用类型，而不是根据美观程度
• 绝不能在同一个应用中将两种应用类型视为并列方案——始终有一种是主要容器
• UIFigure 应用：所有结构布局都必须使用 uigridlayout——绝不能基于 Position 调整尺寸
• UIHTML/Web 应用：界面框架必须使用 CSS Grid 或 Flexbox——结构面板不得使用绝对定位
• 界面框架（标题栏、侧边栏、选项卡、步骤指示器）必须保持空间位置稳定
• 后台执行（任何耗时超过约 1 秒的操作）需要使用类结构应用，并且必须先阅读 references/background-tasks.md——不得凭记忆手写 parfeval/backgroundPool/DataQueue 基础设施。对于 App Designer 应用（.mlapp 或纯文本），必须使用 addBackgroundTask 动作，绝不能自行编写基础设施或复用独立程序的手动接线方式。对于独立程序化应用，按照该文档使用 MVVM 结构。需要后台工作的扁平嵌套函数应用必须改用上述其中一种结构。
• App Designer 序列化：构建前必须阅读 references/app-designer/agent-guide-shared.md（涵盖所有权模型、编辑规范、属性规则、引号用法）以及对应格式的指南（agent-guide-mlapp.md 或 agent-guide-plaintext.md）。这些文档是唯一权威依据；未阅读前不得尝试编辑应用文件。

工作流

User request arrives
        │
        ├── Path NOT specified → Full Discovery
        │       │
        │       ▼
        │   Ask Q1-Q4 (purpose, lifespan, polish, team skills)
        │       │
        │       ▼
        │   Identify layout archetype
        │       │
        │       ▼
        │   Recommend UIFigure vs UIHTML based on Q1-Q4
        │       │
        │       ▼
        │   *** STOP: Present recommendation and WAIT for user confirmation ***
        │   (Do NOT produce a plan or read references until user says yes)
        │       │
        │       ▼
        │   Ask Q5 (FINAL): Serialization format? (UIFigure apps only)
        │       │
        │       ├── App Designer → release check, present format choice,
        │       │       continue with UIFigure references + add serialization step
        │       │
        │       └── Standalone programmatic → no extra step
        │       │
        │       ▼
        │   Produce Implementation Plan → write to <app-name>-plan.md
        │       │
        │       ▼
        │   User reviews plan → confirms or adjusts
        │       │
        │       ▼
        │   Begin building (read references per the plan)
        │
        └── Path IS specified
                │
                ├── Serialization explicit (e.g., ".mlapp app", "plain-text app")
                │       → Skip Q5, proceed with stated format
                │       → Ask only missing requirements + archetype if unclear
                │       → Produce Implementation Plan
                │
                ├── Architecture explicit but serialization not stated
                │   (e.g., "build me a uifigure app")
                │       → Still ask Q5 (serialization) before planning
                │       → Ask missing requirements + archetype if unclear
                │       → Produce Implementation Plan
                │
                └── UIHTML or standalone programmatic explicit
                        → Skip Q5 entirely (not applicable)
                        → Ask missing requirements + archetype if unclear
                        → Produce Implementation Plan

探索性问题

以自然对话的方式询问，不要照搬僵化的检查清单。先了解需求和布局意图；等理解应用需要完成的任务后，再最后询问序列化问题。

核心问题

1. 这个应用能做什么？面向哪些用户？

这个应用要做什么？谁会使用它？

留意能体现应用类型的线索：“仪表板”“控制面板”“分步操作”“工作区”。

2. 这是一个快速工具，还是需要长期维护的应用？

这个应用需要维护和演进，还是更像一个快速搭建的概念验证工具？

• 需要维护 → 继续回答其余问题；团队技能很重要
• 临时使用 → 优先考虑 UIHTML 应用路径；可以跳过团队问题

3. UI 需要多精致？

标准 MATLAB 按钮、滑块、表格和绘图够用吗？还是需要定制视觉效果，例如品牌化、动画或更丰富的视觉呈现？

• 标准控件足够 → 倾向于 UIFigure 应用
• 需要定制视觉效果 → 倾向于 UIHTML 应用

4. 后续由谁来维护这个应用？

维护者只熟悉 MATLAB，还是也熟悉 Web 技术？

仅询问需要维护的应用。

• 团队只熟悉 MATLAB → UIFigure 应用
• 团队熟悉 Web 技术 → UIHTML 应用

5.（最终问题）这个应用应如何保存？

你希望在 App Designer 中打开和编辑这个应用，还是更倾向于使用独立的程序化文件（不依赖 App Designer）？

这是一个关于序列化的问题，而不是架构问题。无论答案如何，应用的结构（组件、布局、回调）都基于 UIFigure 知识来设计。Q5 只决定如何将设计持久化到磁盘。

• App Designer → .mlapp 或纯文本 .m + .xml。检查 MATLAB 版本（纯文本需要 R2026b+）。如果 Q3 表示需要定制视觉效果，请说明 App Designer 对视觉定制的限制，并确认用户是否接受。
• 独立程序化文件 → 程序化 .m 代码，不依赖 App Designer。MVVM 可能需要多个文件；这将在构建时决定。

补充问题（仅在路径不明确时询问）

• 交互方式： 是否需要实时反馈？→ 稍微倾向于 UIFigure
• 现有工作： 是否已有 MATLAB UI 代码？→ UIFigure。是否已有 Web 资源？→ UIHTML
• 分发方式： 是否需要在 MATLAB 之外运行？→ UIHTML
• 耗时计算： 是否有操作需要超过 1 秒？→ 使用后台任务（阅读 references/background-tasks.md）。请注意，这需要采用类结构的应用：使用 App Designer 序列化，或在独立程序化方案中使用 MVVM。繁重、耗时或仅执行一次的工作始终应使用后台任务，绝不能使用计时器；计时器仅适用于需要在主线程上更新 UI 的定时、单次开销较小的工作（阅读 references/timers.md）。

路径决策逻辑

分两个阶段：先确定架构（Q1-Q4），再确定序列化格式（Q5）。

Stage A — Architecture (from Q1-Q4):

Ephemeral app? → Strong default to UIHTML app

Maintained app? → Weigh signals:

Strong UIFigure signals:
  ✓ Maintained + MATLAB-only team
  ✓ Standard UI components sufficient
  ✓ Tight real-time interaction
  ✓ Existing MATLAB UI code

Strong UIHTML signals:
  ✓ Ephemeral (regardless of team)
  ✓ Maintained + web-skilled team
  ✓ Custom visuals, branded look, animations
  ✓ Existing web assets
  ✓ Future portability outside MATLAB

UIFigure + uihtml accent:
  Mostly standard app but needs one custom visualization panel.

Stage B — Serialization format (Q5, UIFigure apps only):

Q5 = Standalone → programmatic code (no App Designer). Done.

Q5 = App Designer → adds a serialization layer ON TOP of Stage A.
  UIFigure references still apply in full. Serialization is IN ADDITION TO,
  not instead of, the normal UIFigure build.
  → Check release, present format choice (plain text vs .mlapp).
  → If Stage A indicated UIHTML for custom visuals, surface the trade-off:
    App Designer constrains custom visuals — confirm before committing.

权重： 1. 架构（Q1-Q4） 2. 序列化（Q5，仅适用于 UIFigure）

路径一览

架构	主要优势
UIFigure 应用	使用单一语言，任何 MATLAB 开发者都能维护
UIHTML 应用	完全掌控视觉效果，交互丰富
UIFigure + 点缀	需要一个定制视觉元素时，兼具两者优势

UIFigure 应用有三种序列化格式：

格式	权衡
程序化 .m	独立运行，不依赖 App Designer
App Designer .mlapp	二进制格式，适用于任何版本，可在 App Designer 中打开
App Designer 纯文本 .m + .xml	可进行源代码管理、可由 AI 编辑，需要 R2026b+

布局类型

根据用户的主要任务选择：

类型	用户的主要任务	结构
仪表板	一目了然地监控和比较	KPI 卡片 + 图表 + 表格；只读
探索器	调整参数并观察实时结果	侧边栏控件 + 实时显示
选项卡式	在相互独立的版块之间导航	选项卡栏 + 内容面板
向导	完成顺序工作流	步骤指示器 + 一次一步
画布	创建、检查或编辑空间对象	中央工作区 + 工具

如果不明确，请询问：“用户主要是查看结果（仪表板）、调整控件（探索器）、切换版块（选项卡式）、逐步完成任务（向导），还是在中央图形上进行操作（画布）？”

实施计划

确认路径和类型后，制定计划并将其写入工作目录中的 <app-name>-plan.md。在请求批准时，同时简要概述计划。

计划模板

**Implementation Plan: [App Name]**

**Architecture:** [UIFigure app / UIHTML app / UIFigure + accent]
**Serialization:** [Programmatic .m / App Designer .mlapp / App Designer plain text]
**Layout:** [Archetype] — [one sentence describing spatial structure]

**Structure:**
- [Major panel/area — spatial description]
- [e.g., "Left sidebar (220px) with date range picker, category filter, refresh button"]
- [e.g., "Main area with line chart showing filtered results"]

**Key behaviors:**
- [User-visible interaction effects]

**Internal references that will be used:**

| Reference | Role in this app |
|-----------|-----------------|
| `references/path/file.md` | [what it provides] |
| ... | ... |

**External skills:**
- `matlab-build-chart` — [role, if applicable]
- `matlab-apply-theme` — [role, if applicable]

**File organization:**
[app directory tree]

**Implementation sequence:**
1. [First reference read] — [what it establishes]
2. [Next reference] — [what it adds]
3. [...]

每个参考指针都包含来源信息：[src: references/uifigure/grid-layout.md §Spanning]

计划质量检查

提交前：

• 所列每项参考资料都有明确用途
• 结构使用用户能够想象的空间布局术语
• 行为描述用户可见的效果
• 实施顺序符合逻辑的构建顺序
• 计划足够具体，让用户能够回答“是，这正是我想要的”或“更改 X”

参考资料路由

计划获批后，阅读相关内部参考资料以执行构建。

UIFigure 路径

构建内容...	阅读
网格布局、尺寸、组件	references/uifigure/guide.md
网格详情（跨列、折叠）	references/uifigure/grid-layout.md
面板、选项卡组、嵌套网格	references/uifigure/containers.md
组件参考（控件、显示）	references/uifigure/components.md
回调模式、数据共享	references/uifigure/callbacks.md
布局方案（侧边栏、表单、分栏）	references/uifigure/layout-patterns.md
MVVM 架构（复杂应用）	references/uifigure/mvvm-guide.md
视图绑定模式	references/uifigure/mvvm-view-binding.md
ViewModel 测试	references/uifigure/mvvm-testing.md
后台执行——概念 + 路由（先阅读）	references/background-tasks.md
后台执行——独立的程序化（MVVM）接线	references/uifigure/mvvm-background-tasks.md
定时器——周期性主线程工作（不用于卸载繁重工作）	references/timers.md

UIHTML 路径

构建内容……	阅读
MATLAB-JS 桥接、setup()、事件	references/uihtml/bridge-guide.md
通信模式（4 种模式）	references/uihtml/communication-patterns.md
数据类型转换	references/uihtml/data-types.md
平台限制	references/uihtml/platform-limitations.md
uihtml 创建、混合布局	references/uihtml/setup.md
错误处理（两端）	references/uihtml/error-handling.md
JS MVVM 架构	references/uihtml/mvvm-guide.md
Observable/Computed 类	references/uihtml/mvvm-observable-classes.md
JS 视图绑定	references/uihtml/mvvm-view-binding.md
JS 编码模式、模块	references/uihtml/js-coding-guide.md
JS 测试与调试	references/uihtml/js-testing-debugging.md
Chart.js 设置与模式	references/uihtml/charting-guide.md
图表类型选择	references/uihtml/chart-type-selection.md
Chart.js 初始化	references/uihtml/chartjs-setup.md
折线图与条形图	references/uihtml/line-bar-charts.md
环形图与散点图	references/uihtml/doughnut-scatter-charts.md
图表数据更新	references/uihtml/chart-updates.md
图表 ↔ 桥接集成	references/uihtml/chart-bridge-integration.md
图表性能	references/uihtml/chart-performance.md
CSS 样式与令牌	references/uihtml/styling-guide.md
组件 CSS（按钮、输入框）	references/uihtml/component-styles.md
CSS 布局模式	references/uihtml/css-layout-patterns.md
品牌设计令牌	references/uihtml/brand-design-tokens.md
深色模式	references/uihtml/dark-mode.md
外部配色方案	references/uihtml/external-color-schemes.md

App Designer 序列化（仅适用于 UIFigure 应用）

**重要：**App Designer 序列化是在常规 UIFigure 构建之后的额外步骤。你还必须阅读上文 UIFigure 路径的参考资料（组件、grid-layout、回调、容器、layout-patterns），以设计应用的结构。以下序列化参考资料仅介绍如何将该设计保存到磁盘。

两种格式都通过捆绑的 scripts/ 工具使用相同的 AppDesignerAgentInterface API；区别仅在于传递给 create()/open() 的文件扩展名。

请先阅读（两种格式均适用）：

构建内容……	阅读
动词、构建顺序、编辑、save()/validate()/finalize()、inspect()	references/app-designer/agent-guide-shared.md
后台执行——概念与路由（先阅读）	references/background-tasks.md
后台执行——addBackgroundTask 动词参考	references/app-designer/background-tasks.md

纯文本格式（.m + .xml）：

构建内容……	阅读
所有权模型、.xml 编写、流程、注意事项	references/app-designer/agent-guide-plaintext.md
classdef 结构与块排序规则	references/app-designer/plaintext/classdef-template.md
XML 结构以及需要设置的属性	references/app-designer/plaintext/xml-template.md
每个组件的属性名称、类型、默认值	references/app-designer/plaintext/property-reference.md
权威 XML 架构	references/app-designer/plaintext/matlabAppSchema.xsd

二进制 .mlapp：

构建内容……	阅读
构建流程、原生属性值、save()/finalize()	references/app-designer/agent-guide-mlapp.md

编辑现有应用

编辑内容……	阅读
任何现有应用（确定格式并指引处理方式）	references/editing-guide.md

原型参考

原型	文件
仪表板	references/archetypes/dashboard.md
浏览器	references/archetypes/explorer.md
标签页	references/archetypes/tabbed.md
向导	references/archetypes/wizard.md
画布	references/archetypes/canvas.md

外部技能（调用，不读取）

• matlab-build-chart — 当应用包含 MATLAB 图表时（UIFigure 路径或 UIFigure + accent）
• matlab-apply-theme — 当应用需要深色模式、品牌颜色或自定义调色板时（UIFigure 路径）

计划获批后

所有 UIFigure 应用（无论序列化格式如何）

1. 阅读原型参考，了解空间骨架
2. 如果适合采用 MVVM（浏览器、向导、画布或复杂应用）：阅读架构参考
3. 阅读 UIFigure 指南，确定布局（网格、组件、容器）
4. 根据实现顺序，加入特定路径的参考内容
5. 如需视觉润色：调用 matlab-apply-theme（UIFigure）或阅读样式参考（UIHTML accent）
6. 如需图表：调用 matlab-build-chart（UIFigure）或阅读图表参考（UIHTML accent）
7. 如果使用 App Designer 序列化： 阅读 App Designer 参考文档（共享指南 + 特定格式指南），然后使用 AppDesignerAgentInterface API 保存应用。文档包含完整的构建流程、属性规则和编辑规范。

UIHTML 路径

1. 阅读原型参考，了解空间骨架
2. 如果适合采用 MVVM：阅读 JS MVVM 架构参考
3. 阅读桥接指南，建立 MATLAB-JS 连接
4. 根据实现顺序，加入特定路径的参考内容
5. 如需视觉润色：阅读样式/CSS 参考
6. 如需图表：阅读图表参考

格式回退

如果纯文本路径出现无法解决的错误（例如版本不匹配或组件不受支持），则回退到 .mlapp 路径——两种格式都使用相同的动词；使用 .mlapp 扩展名重新创建句柄。只有作为最后手段，才回退到完全以编程方式编写的 UIFigure 代码。

推荐模板

推荐架构：[UIFigure 应用 / UIHTML 应用 / UIFigure + accent]

根据你的描述：

• [关键信号 1]
• [关键信号 2]
• [关键信号 3，如适用]

这意味着：[用 1-2 句话说明开发体验]

权衡：[与另一种路径相比需要放弃的主要方面]

**序列化（如果使用 App Designer）：**我建议使用 [.mlapp / 纯文本]，因为[原因]。这不会改变应用的结构，只会改变其保存方式。

你想按此方案继续，还是更倾向于另一种路径？

---

版权所有 2026 The MathWorks, Inc.

---