matlab-create-live-script

Live 脚本

纯文本 .m 文件，可在 MATLAB Live Editor 中呈现为格式丰富的文档。便于版本控制——绝不使用二进制 .mlx。

适用场景

• 教程、报告、分析笔记本或文档
• 带有内嵌图形和公式的交互式探索
• 需要进行版本控制的内容（纯文本 .m，而非二进制 .mlx）
• 将现有二进制 .mlx 文件转换为纯文本 .m 文件

不适用场景

• 不需要丰富格式的普通脚本
• 函数文件
• 低于 R2025a 的 MATLAB 版本

从 .mlx 转换

要将二进制 .mlx 文件转换为纯文本 .m Live 脚本，请在 MATLAB 命令窗口中运行以下内容。此操作步骤不会成为生成的 .m 文件的一部分：

editor = matlab.desktop.editor.openDocument(mlxPath, Visible=0);
editor.saveAs(newMPath);  % use .m extension
editor.closeNoPrompt;

规则

• 文本行使用 %[text]——不能只写 %
• 一个段落写成一行 %[text]——不要手动换行；让 Live Editor 处理行宽
• 不要写空的 %[text] 行——它们会呈现为多余的空白
• 章节标题：单独一行写 %%，然后在下一行写 %[text] ## Title
• 文件中不得有空行，但 %[appendix] 前可有且仅有一个空行
• 不使用 figure 命令——仅使用隐式图形创建
• 每个章节最多绘制一个图（使用平铺布局时除外）
• 不使用 close all 或 clear
• 不使用 mfilename——它在 Live 脚本中的行为不符合预期。请硬编码文件名或使用 pwd。
• 将以下字符作为纯文本（而非 Markdown 语法）使用时进行转义：*、_、[、]、`、\。数字后的 . 和行首的 # 也需要转义。
• 公式仅使用单个 $ 的行内形式：$ a = \\pi r^2 $（不要使用 $$ ... $$）。对于居中或独立成行的公式，请将该行写为：%[text]{"align":"center"} $ X(k) = \\sum\_{n=0}^{N-1} x(n) e^{-j2\\pi kn/N} $
• 在公式内，LaTeX 命令使用两个反斜杠（\\sin、\\frac、\\pi），Markdown 字符使用一个反斜杠（\_、\*）。请使用能写入原义文本的工具（Edit、Write、fwrite）——不要使用 Bash heredoc；即使加引号，它也会将 \\ 转换为 \，从而破坏 LaTeX 公式。
• 最后一项列表项（项目符号或编号）以 \ 结尾
• 每个文件都必须以规定的附录结尾
• 避免使用 fprintf——删除分号或使用 disp()。输出会内嵌显示在生成它的代码下方，而不是出现在命令窗口中。
• 输出应帮助读者理解，而不是用于验证代码是否执行

必需的附录

每个 Live 脚本都必须以以下内容结尾：

%[appendix]{"version":"1.0"}
%---
%[metadata:view]
%   data: {"layout":"inline"}
%---

阅读 Live 脚本（优化 Token 用量）

阅读 Live 脚本文件时，请忽略 %[appendix] 标记下方的所有内容。附录包含嵌入的图像和元数据，会消耗 Token，却不提供有用信息。所有代码和文本内容都位于该标记之前。

格式参考

语法	呈现效果
%%	章节分隔符
%[text] # Title	H1 标题
%[text] ## Section	H2 标题
%[text] **bold**	粗体
%[text] *italic*	斜体
%[text] `code`	等宽字体
%[text] <u>text</u>	下划线文本
%[text] $ a = \\pi r^2 $	行内公式
%[text]{"align":"center"} $ ... $	居中或独立成行的公式
%[text] - item	项目符号列表项
%[text] - last \	最后一项项目符号列表项
%[text] 1. item	编号列表项
%[text] 2. last \	最后一项编号列表项
%[text] [text](url)	外部超链接
%[text] [text](internal:id)	指向锚点的内部链接
%[text] %[text:anchor:id] ...	锚点（链接目标）
%[text:tableOfContents]{"heading":"..."}	目录

**ID（锚点及其他带 ID 的元素）：**只能包含字母、数字和下划线。不能使用连字符——my-section 无法绑定；请使用 my_section。对于锚点，请将标记放在行首 %[text] 之后。

表格

%[text:table]
%[text] | Method | Result |
%[text] | --- | --- |
%[text] | Trapezoidal | 1.9998 |
%[text:table]

示例

%[text] # Sinusoidal Signals
%[text] Examples of sinusoidal signals in MATLAB.
%[text:tableOfContents]{"heading":"Contents"}
%[text] - sine waves
%[text] - cosine waves \
x = linspace(0,8*pi);
%%
%[text] ## Sine Wave
plot(x,sin(x))
title('Sine Wave')
xlabel('x (radians)')
ylabel('sin(x)')
grid on
%%
%[text] ## Cosine Wave
plot(x,cos(x))
title('Cosine Wave')
xlabel('x (radians)')
ylabel('cos(x)')
grid on
%%
%[text] ## Summary
%[text] The sine and cosine functions are $ \\pi/2 $ radians out of phase.

%[appendix]{"version":"1.0"}
%---
%[metadata:view]
%   data: {"layout":"inline"}
%---

常见模式

使用公式进行数学说明

%[text] ## Theory
%[text] The discrete Fourier transform is defined as:
%[text]{"align":"center"} $ X(k) = \\sum\_{n=0}^{N-1} x(n) e^{-j2\\pi kn/N} $
%[text] where $ x(n) $ are the time-domain samples and $ k $ indexes the frequency bins.

带内嵌注释的代码

%%
%[text] ## Data Processing
%[text] Load and filter the data, then visualize the results.
data = load('measurements.mat');
filtered = lowpass(data, 0.5);  % Apply lowpass filter
plot(filtered)
title('Filtered Data')

用于比较的平铺布局

仅在插图中并排比较至关重要时使用：

%%
%[text] ## Comparison of Methods
tiledlayout(1,2)
nexttile
plot(method1)
title('Method 1')
nexttile
plot(method2)
title('Method 2')

工作流

1. 规划 — 标题、设置、分析部分、摘要
2. 编写 — 文本使用 %[text]，章节使用 %%，附录放在末尾。使用可写入字面文本的工具（Edit、Write、fwrite）。不要使用 Bash heredoc（cat > file <<EOF）；即使加了引号，它们也会将 \\ 折叠为 \，从而破坏 LaTeX 公式。
3. 验证（如果已连接 MATLAB）— 通过 evaluate_matlab_code 运行代码，确认其可正常执行。记下实际耗时——Embed Outputs 大约需要相同的时间。
4. 嵌入输出（可选，如果已连接 MATLAB）— 运行 executeLiveScript("<absolute-path>.m")，将每个章节的输出（图表、显示的数值）内嵌到生成这些输出的代码旁边。
5. 验证渲染（可选，如果已连接 MATLAB）— 运行 export("<absolute-path>.m", "<absolute-path>.html")，生成渲染文档的 HTML 近似版本。重新读取该文件，确认公式已正确排版、图表已内嵌、%[text] 指令未作为字面文本泄漏等。完成后删除 .html——它是验证产物，不是交付内容。

编写步骤是关键——仅通过 Write 就能生成用户可打开并运行的有效实时脚本。验证、嵌入输出和验证渲染都是渐进式增强，需要已连接 MATLAB 会话。如果没有 MATLAB 会话，完成编写后即可停止。嵌入输出后，MATLAB 会将文件重写到磁盘——进行任何后续编辑前，请重新读取文件。

executeLiveScript

此工具随附于此技能的 scripts/ 文件夹中。首次使用前，将其添加到路径：

addpath(fullfile(skillRoot, "scripts"));   % skillRoot = directory containing this SKILL.md

调用 executeLiveScript(filePath) 成功时不返回任何内容。脚本内的运行时错误不会引发异常——脚本会将其写入附录，格式为 "dataType":"error" 块；可 grep 保存的 .m 文件以查找这些错误。

先运行 Validate，再运行 Embed Outputs。 如果 Embed Outputs 期间某个单元格出错，该单元格会变成错误块，其后的单元格输出也会从文件中移除。请先通过 evaluate_matlab_code 运行代码。

如果 Embed Outputs 因 "Nested Live Editor execution" 出错或挂起时间超过 Validate 的耗时： 请在 MATLAB 桌面可见时重试一次。如果仍然失败，Write 写入磁盘的文件仍然有效——跳过 Embed Outputs，让用户自行运行脚本。

检查清单

完成实时脚本前，请确认：

• 文件扩展名为 .m
• 章节使用独占一行的 %%，后接 %[text] ##
• 没有空行或空的 %[text] 行（紧挨 %[appendix] 之前的一行空行除外）
• 每个段落都写在单独的 %[text] 行上（不要硬换行）
• 每个章节一个图表（平铺布局除外）
• 项目符号列表和编号列表的最后一项以反斜杠结尾
• 保存文件中的 LaTeX 命令反斜杠已加倍：\\sin、\\frac、\\pi
• 没有 figure 命令
• 开头没有 close all 或 clear
• 没有 mfilename
• 附录存在且格式正确
• 输出服务于读者，而非开发者

尚不支持

计划在未来版本中支持的次要功能：

• 交互控件（滑块、下拉菜单、数字输入）
• 隐藏代码视图（隐藏源代码的输出视图）

---

版权所有 2026 The MathWorks, Inc.

---