matlab

MATLAB 和 GNU Octave

使用此技能来设计或审查数值代码、迁移 MATLAB 版本、准备可复现项目，并规划可信执行。MATLAB 和 GNU Octave 是不同的产品：两者仅部分兼容，不能据此推断许可或行为保证。

产品与许可检查

• MATLAB R2026a 是专有软件。 不要假设用户已安装、获许可或可使用 MATLAB、MATLAB Online、指定工具箱、MATLAB Test、MATLAB Compiler、MATLAB Coder、Parallel Computing Toolbox 或任何附加组件。
• MATLAB Runtime 不是 MATLAB。 它只能运行由 MATLAB Compiler 生成的兼容应用；不能运行任意源代码，也不能为 Python 托管 MATLAB Engine。构建制品需要相应的已获许可编译器，以及源代码使用的每个产品。
• GNU Octave 11.3.0 是基于 GPLv3+ 的自由软件。 Octave 软件包不是 MATLAB 工具箱。名称相似并不意味着 API、数值、图形或许可等效。
• 询问用户实际拥有的运行时、版本、平台、已安装产品和许可情况。在得到确认前，将可用性视为 unknown。

参见 Octave 兼容性 和 执行与产品边界。

不可妥协的安全边界

绝不运行不受信任的 .m、.mlx、MEX 二进制文件、MAT 文件、项目启动或关闭操作、软件包安装程序或生成的制品。静态审查无法证明安全。

将以下内容视为执行或加载代码的入口：

• eval、evalin、assignin、由文本派生的 feval、str2func、回调、计时器、应用回调和动态修改的路径；
• system、unix、dos、Shell 转义符 !、Java、.NET、Python（py.*、pyrun、pyrunfile）、MEX 和原生库；
• mex、codegen、MATLAB Compiler、构建任务、软件包／项目启动代码和生成的代码；
• load、对象反序列化（loadobj、自定义序列化）、函数句柄、Java/System 对象，以及可从 MAT 文件访问的类代码。

对于此工具包而言，.mlx 是不透明的存档，MEX 是原生可执行代码。不要使用 Python pickle 进行交换。先检查，必要时进行隔离，取得明确批准，然后才调用用户确认的可执行文件和许可。捆绑的脚本仅用于静态分析或试运行：没有任何脚本会启动 MATLAB、Octave、Python Engine、编译器或子进程。

默认工作流

1. 明确目标。 记录 MATLAB 版本或 Octave 版本、操作系统／体系结构、基础产品与所需工具箱／软件包、预期输入／输出、数值容差，以及是否获准执行。
2. 静态盘点。 在任何运行时加载文件之前，扫描 .m 文件、不透明制品、项目路径、所需产品和 MAT 标头。
3. 选择代码形式。 自动化优先使用带 arguments 块的函数。脚本仅用于受控编排，实时脚本仅用于经过审查的交互式说明。
4. 明确语义。 记录形状、类、单位、缺失值规则、索引、隐式扩展、RNG 算法／种子、容差和输出格式。
5. 在无隐藏状态下测试。 使用合成测试夹具，将路径限制在项目内，确保图形输出具有确定性，并使测试不依赖基础工作区的残留状态。
6. 规划执行。 生成 argv 计划，审查启动／路径影响和许可；只有在明确批准后，才在这些辅助工具之外启动。
7. 记录溯源信息。 对具名输入／代码进行哈希，并记录版本、产品、RNG 策略、容差和命令计划，但不要转储环境信息。

语言与数据检查清单

脚本、函数和实时脚本

• 脚本与调用方／基础工作区共享工作区，并会留下变量。 函数具有局部工作区和显式输入／输出。
• 实时脚本（.mlx）混合代码和丰富输出，但不是纯文本审查材料。将审查过的代码导出为 .m 以进行静态检查。
• 避免使用 clear all、宽泛的 addpath(genpath(...))、依赖 pwd、全局变量以及静默的名称遮蔽。使用项目根目录和 fullfile。
• 在 arguments 块中验证大小、类和取值。请记住，类型声明可能会转换输入；验证器只检查，不进行转换。
• 主函数文件应与主函数同名。局部函数仅在文件内可见；从 R2024a 起，它们可出现在脚本中的任意位置，但不能位于条件上下文中。

function y = scaleSignal(x, options)
arguments
    x (:,1) double {mustBeFinite}
    options.Scale (1,1) double {mustBeFinite, mustBeNonzero} = 1
end
y = x .* options.Scale;
end

阅读编程。

数组、索引和数值计算

• MATLAB 使用从 1 开始的列优先索引。A(i,j)、A(k)、A(:,j)、 A{...} 和 A.(name) 的语义各不相同。
• *、/、\ 和 ^ 是矩阵运算；带点的形式是逐元素运算。使用 A\b，不要使用 inv(A)*b。
• 从 R2016b 起，兼容维度会隐式扩展。在可能意外形成外积结果的运算前，断言预期的形状。
• 已知输出大小时进行预分配，但不要为了向量化而牺牲大量临时变量或代码可读性。使用 timeit 或性能分析器进行测量。
• 根据领域需求选择绝对和相对容差来比较浮点结果，不要一概使用 ==，也不要使用某个固定的 eps 倍数。
• 固定随机算法和种子。使用命名的 RandStream 子流执行相互独立的并行工作；不要使用基于时间的 rng("shuffle") 来声称结果可复现。

阅读数组和 数学。

表、时间表和缺失值

• table 包含具有名称且高度相同的变量，这些变量的类型可以不同。 T(rows,vars) 返回一个表；T{rows,vars} 提取内容；T.Var 选择一个变量。
• timetable 还包含行时间。先排序并验证时区和唯一性，再有意使用 retime／synchronize。
• 缺失值标记因类型而异：NaN、NaT、<missing>、 <undefined> 和空字符向量。整数和逻辑数组没有标准的缺失值标记。
• 对生产数据，应定义导入选项，而不要依赖推断。保留单位、时区、变量名称、编码和缺失值规则。

阅读数据导入／导出。

图形和导出

使用显式的图形和坐标区句柄以及 tiledlayout；标注单位；有意设置坐标轴范围、颜色范围、字体大小和颜色映射。对于出版级输出，优先使用 exportgraphics 而不是 saveas。在 R2026a 中，它可导出栅格、PDF/EPS/EMF、SVG、GIF 和交互式 HTML；不同格式的功能有所差异。对于适用的 PDF/SVG 类输出，指定 ContentType="vector"；对于栅格输出，指定 Resolution。检查无障碍特性和嵌入式栅格的行为。

阅读图形和可视化。

MAT 文件和数据交换

• Version 7 是 save 的常规默认版本；matfile 默认创建 7.3 文件。 4/6/7/7.3 版本在类型、压缩和单变量限制方面各不相同。
• Version 7.3 基于 HDF5，但并非通用的 HDF5 数据交换规范。 对大型数组，部分访问和分块可能会有所帮助。
• 切勿加载不可信的 MAT 文件。先检查文件头和数据集。对象可能会调用类反序列化行为；不透明内容、函数内容或原生内容需要升级处理。
• 对于简单的数据交换，优先使用带有文档化架构的 CSV/JSON/Parquet/HDF5。不要将 pickle 载荷改名为 MAT 文件，也不要反序列化 pickle。

阅读数据导入／导出。

项目、分析与测试

• 使用 MATLAB Projects 管理受控路径、启动／关闭任务、依赖项、源代码管理和可复现的入口点。打开不可信项目之前，请先检查项目操作。
• matlab.codetools.requiredFilesAndProducts 和 Dependency Analyzer 只是静态近似；动态分派可能导致漏报或误报。必需产品报告无法证明许可证可用。
• 迁移前，请使用 Code Analyzer（codeIssues；旧版文本工作流可使用 checkcode）和 codeCompatibilityReport。
• MATLAB 基础版支持基于脚本、函数和类的 matlab.unittest 工作流。并行运行需要 Parallel Computing Toolbox。基于依赖项的选择、更丰富的质量仪表板、生成的测试以及高级覆盖率／等效性功能，可能需要 MATLAB Test 或其他产品。
• 在 R2026a 中，如果目标测试所属的项目尚未打开，runtests 会自动打开该项目，并在稍后将其关闭。使用此行为之前，请考虑启动和关闭操作的影响。

请阅读编程和执行／测试。

Python 集成（固定为 R2026a）

• R2026a 的 MATLAB Interface to Python、MATLAB Engine for Python 和 MATLAB Compiler SDK for Python 支持 64 位 CPython 3.9-3.13。
• 此处审查的当前 R2026a PyPI 软件包为 matlabengine==26.1.12（发布于 2026-05-08）。它要求已安装 R2026a；仅安装 MATLAB Runtime 不够。R2026a 还会在一个名为 matlabroot 的路径下附带预安装的 Engine 发行版。
• 安装软件包不会授予 MATLAB 或工具箱许可证。请配置一个指定的解释器／可执行文件；不要输出完整环境、PATH、PYTHONPATH 或凭据。
• pyenv 控制 MATLAB 到 Python 的解释器选择。通常需要重启 MATLAB 才能切换进程内 Python；进程外 Python 则可以终止并重新配置。
• 启动 Engine 是一项明确的执行操作：matlab.engine.start_matlab() 会启动 MATLAB 进程，并可能检出许可证。切勿仅为探测可用性而调用它。
• 请验证 NumPy 数组、pandas DataFrames、表／时间表、字符串／缺失值、datetime／duration、字典、形状／顺序以及不支持的稀疏／对象／分类数据情形下的转换语义。

请阅读 Python 集成。

本地辅助 CLI

所有辅助工具均无需联网、操作范围受限、拒绝符号链接且不会执行代码。请使用 Python 3.11+ 从此技能目录运行。仅允许使用 Bash 调用这些 Python CLI 和验证命令；切勿使用它来执行生成的 MATLAB／Octave argv 计划或不可信制品。

辅助工具	用途
scripts/plan_batch_command.py	生成经审查的 MATLAB／Octave argv；切勿执行
scripts/scan_m_code.py	扫描 .m 文本并标记不透明的 .mlx／MEX 风险
scripts/validate_project_manifest.py	验证路径及声明的产品／许可证状态
scripts/inventory_mat_file.py	清点标头／元数据；切勿调用 loadmat
scripts/plan_python_compatibility.py	检查 R2026a CPython／Engine 兼容性
scripts/reproducibility_report.py	为指定的本地制品生成哈希并输出范围受限的报告
scripts/generate_function_scaffold.py	试运行或创建函数和单元测试脚手架

python scripts/scan_m_code.py path/to/source --root path/to/project
python scripts/plan_batch_command.py matlab script path/to/main.m --root path/to/project
python scripts/validate_project_manifest.py project-manifest.json --root path/to/project
python scripts/inventory_mat_file.py data.mat --root path/to/project
python scripts/plan_python_compatibility.py --python-version 3.13
python scripts/reproducibility_report.py --root path/to/project --file src/analyze.m
python scripts/generate_function_scaffold.py analyzeSignal --root path/to/project

脚手架生成器默认采用试运行模式；写入需要使用 --write，且遇到冲突时会拒绝操作。SciPy 和 h5py 是可选的清点后端；如获授权，请将经审查的确切版本添加到调用方项目的锁定文件中。运行 --help 或仅清点标头时不需要它们，且此技能不会执行软件包安装。

参考资料

• 编程、工作区、项目、分析、测试
• 矩阵、索引、类型、缺失值、性能
• 数值方法、容差、RNG、工具箱边界
• 图形和 exportgraphics
• 导入/导出、表格/时间表、MAT 语义和安全性
• MATLAB/Octave 命令行执行和迁移
• MATLAB 和 Python 互操作
• GNU Octave 11.3.0 兼容性差异

随附的 JSON 资源包括项目清单、 可复现性清单和 R2026a Python 表格。没有 templates/ 目录，也不会从 assets/ 加载 Markdown 文件； 本地链接测试会强制执行此软件包约定。

主要来源（已于 2026-07-23 核实）

• MATLAB R2026a 文档
• MATLAB R2026a 发行说明
• R2026a 系统要求
• 各版本的 Python 兼容性
• MATLAB Engine 安装
• GNU Octave 11.3.0 发行版
• GNU Octave 当前手册