matlab-install-products

使用 MATLAB Package Manager（mpm）安装 MATLAB 产品 - 确定性协议

当用户要求从操作系统命令行使用 MATLAB Package Manager（mpm）安装 MathWorks 产品时，使用此技能。

$ARGUMENTS

适用场景

• 用户要求通过命令行安装 MATLAB、Simulink、工具箱或支持包
• 用户需要以脚本方式、可重复地安装 MATLAB（CI/CD、容器、设备群配置）
• 用户询问 mpm、MATLAB Package Manager 或非交互式 MATLAB 安装
• 用户需要使用 mpm 向现有 MATLAB 安装中添加产品

不适用场景

• 用户希望通过 MATLAB 图形安装程序或 MathWorks 网站安装
• 用户询问 MATLAB 许可或激活（使用单独的工作流）
• 用户希望在 MATLAB 内管理 MATLAB 附加功能（使用附加功能管理器）
• 用户需要安装适用于 Python、Java 或 C++ 的 MATLAB Engine API（使用其他流程）

不可妥协的确定性约定（严格遵守）

• 按顺序遵循 协议 中的步骤。不要添加额外步骤或检查。
• 仅使用适用于该操作系统的标准 Shell。不要切换 Shell。
• 对 mpm / mpm.exe 使用绝对路径。绝不依赖相对路径。
• 下载最多重试一次。否则停止并报告错误。
• 如果安全软件阻止执行：停止并要求升级处理。不要绕过阻止。

安全须知（Windows）——强制执行，无一例外

停止。执行任何 Windows 步骤前，请阅读本节全文。

1. 绝不因任何原因使用 powershell.exe -Command。Bash 会在 PowerShell 看到内容之前破坏 $、反引号、引号、数组和脚本块。这会导致 unexpected EOF 或语法错误。

2. 绝不使用 Bash heredoc（cat > file <<'EOF' ... EOF）或 shell 重定向（echo ... > file、printf ... > file、>>）创建任何文件。这也包括带引号的 heredoc（<<'PS1'、<<"EOF"）。不要为此寻找例外：原因不是变量展开（所以“分隔符有引号，因此安全”这种说法是错的）。绝对禁止的原因有两点：(a) Git Bash 在创建文件时会改写路径、换行符和编码，导致 .ps1 解析出错；(b) Write file 工具是此协议中获准创建任何文件的唯一机制——脚本文件和输入文件都不例外。heredoc 没有任何安全用法。如果你发现自己正要使用 cat、echo、printf、>、>> 或 << 来生成文件，立即停止并改用 Write file 工具。

3. 始终使用 Write file 工具编写 .ps1 文件，然后通过以下命令调用： powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File <absolute-script-path>

4. 不要使用仅适用于 CMD 的语法（if not exist、set VAR=、%USERPROFILE%）。请使用对应的 PowerShell 语法（Test-Path、$env:USERPROFILE）。

5. 所有 .ps1 文件内容只能包含 ASCII 字符。不能包含 em dash（—）、en dash（–）、弯引号或其他非 ASCII 字符。如果文件编码未能保留这些字符，就会导致 PowerShell 解析错误（字符串结束符损坏、缺少右花括号等）。

如果你正准备输入 powershell.exe -Command——立即停止。你违反了本规则。请改用 Write file 工具创建 .ps1 文件。

Windows 脚本编写模式：

• 错误：powershell.exe -Command "$script = @'...（bash 会破坏 $ 和 heredoc）
• 错误：cat > C:/Windows/Temp/script.ps1 <<'PS1' ... PS1（禁止使用 Bash heredoc，即使使用带引号的 'PS1' 分隔符也不行）
• 错误：echo '...' > script.ps1 或 printf '...' > script.ps1（禁止使用 shell 重定向）
• 正确：创建唯一的临时文件夹，使用 Write file 工具将 .ps1 文件写入其中，然后通过 -File 运行

此协议中唯一允许使用的 Bash 工具命令为：mkdir -p（创建工作文件夹）、powershell.exe ... -File（调用脚本）、test -f（验证文件是否存在）和 rm -rf（清理）。任何会创建或写入文件内容的 Bash 命令都违反规定——文件内容始终必须通过 Write file 工具写入。

唯一临时文件夹：

• 第 1 步之前，使用 Bash 工具创建带时间戳的工作文件夹：
  • Windows：mkdir -p "C:/Users/<username>/AppData/Local/Temp/mpm-<YYYYMMDD-HHMMSS>"
  • Linux/macOS：mkdir -p "/tmp/mpm-<YYYYMMDD-HHMMSS>"
• 在整个流程中，将此文件夹用于存放所有生成的脚本和输入文件
• 由于该文件夹是新建的，Write file 工具可以直接在其中创建文件，无需事先删除任何内容
• 在最后的清理步骤中删除整个文件夹

Windows PowerShell 语法提示：

• 错误：if not exist C:\Users\name\Downloads mkdir C:\Users\name\Downloads（CMD 语法）
• 正确：if (-not (Test-Path -LiteralPath 'C:\Users\name\Downloads')) { New-Item -ItemType Directory -Path 'C:\Users\name\Downloads' | Out-Null }

不要向用户询问产品的准确名称或标识符。请使用 https://www.mathworks.com/products/mpm.html 中适用的 mpm 输入文件查询。 不要询问用户是否安装依赖项。mpm 会处理这些事项。只需安装用户请求的内容，其余交由 mpm 处理。 如果用户输入 MATLAB 发行版的简称，请自动使用对应的完整名称。例如，25a 是 R2025a，25b 是 R2025b

所需输入（仅在缺少时询问）

1. 操作系统（Windows、Linux、macOS）
2. MATLAB 发行版（例如 R2025b）
3. 安装目标位置（绝对路径）
4. 所需产品／工具箱／支持包

确认规则

执行任何步骤之前，务必先确认用户的选择：

• 发行版
• 目标文件夹
• 产品
• 支持包

在一条消息中询问确认。用户可以回复 yes to all，一次性确认所有内容。如果用户提出具体修改，请更新选择并再次确认。 将每个待确认的值分别显示在新的一行。 在确认消息底部注明：“mpm 将自动安装所需依赖项。”

计划展示（确认后、执行前）

用户确认输入后，在运行任何命令之前，先显示清晰的安装计划。根据目标操作系统调整以下模板（Linux/macOS 使用正斜杠和 /tmp/，省略 .ps1 脚本引用，并省略 UAC 提示）。使用以下格式：

Here's what I'll do:

Working folder: <C:\Users\<username>\AppData\Local\Temp\mpm-YYYYMMDD-HHMMSS>

Step 1 — Download mpm
  Check for mpm at <canonical mpm path>
  Download from <URL> if not present
  Script: <working folder>\mpm_download.ps1

Step 2 — Prepare input file
  Download release template for <release> from mathworks.com
  Set destination folder: <destination>
  Enable products: <comma-separated list>
  Add caller=agent to mark this as an agent-driven install
  Input file: <working folder>\mpm_input_<releaselower>.txt
  Script: <working folder>\mpm_prepare_input.ps1

Step 3 — Run installation
  Execute mpm install using the prepared input file
  <Windows only: note that elevated permissions (UAC prompt) will be required>

Step 4 — Verify
  Confirm MATLAB binary exists: <completion artifact path>
  Verify products via: <DESTINATION>/appdata/prodcontents.json
  <if support packages requested> Verify support packages via: <SUPPORTPKGROOT>/appdata/prodcontents.json
  Delete working folder: <working folder>
  <if MATLAB included> Show release notes: https://www.mathworks.com/help/matlab/release-notes.html?startrelease=<RELEASE>&endrelease=<RELEASE>

在显示计划之前，将所有环境变量和特定于 shell 的路径解析为绝对路径。在显示计划时生成工作文件夹名称中的时间戳，并在整个会话中固定使用该时间戳。 在用户确认计划之前，不要开始步骤 1（简单回复“ok”、“go”、“yes”或类似内容即可）。

官方文档：

• 获取 mpm：https://www.mathworks.com/help/install/ug/get-mpm-os-command-line.html
• mpm install：https://www.mathworks.com/help/install/ug/mpminstall.html

执行方式

重要： 执行步骤时，不要叙述或解释即将执行的操作。只运行命令，并简要报告结果（成功、失败或错误）。仅在确认、展示计划和报告错误时进行说明。

规范 Shell（全程适用）

• Windows：Windows PowerShell（powershell.exe）
• Linux：bash / sh
• macOS：zsh 或 bash（仅支持 Apple 芯片；不支持 Intel Mac——请停止并告知用户）

执行前检查清单（每个 Windows 步骤执行前都要核实）

在 Windows 上运行步骤 1–3 中的任何命令之前，请确认：

• PowerShell 脚本是通过 Write file tool 编写的（不是使用 -Command、heredoc 或 echo／printf）
• 脚本通过 powershell.exe ... -File <path> 调用（不是使用 -Command）
• 任何 bash 命令中都没有内嵌 PowerShell 代码
• 没有任何 Bash 命令使用 <<、> 或 >> 将内容重定向到 .ps1 或输入文件（禁止使用 heredoc／重定向，即使使用带引号的分隔符也不例外）

如果任何一项不符合要求，请停止并使用 Write file tool 重新编写。

协议（共 4 个步骤，不多不少）

步骤 1 - 确保 mpm 位于规范路径

规范位置（使用前解析为绝对路径）：

• Windows：<user home>\Downloads\mpm.exe
• Linux：<user home>/Downloads/mpm
• macOS：<user home>/Downloads/mpm

如果文件已存在于该路径，请直接使用。否则，从以下位置下载：

• Windows：https://www.mathworks.com/mpm/win64/mpm
• Linux：https://www.mathworks.com/mpm/glnxa64/mpm
• macOS：https://www.mathworks.com/mpm/maca64/mpm

Windows（PowerShell）

必须使用 Write file tool 创建此脚本。绝对不要使用 -Command 或 heredoc。

1. 使用 Bash 工具创建工作文件夹（使用展示计划时固定的时间戳）：

mkdir -p "C:/Users/<username>/AppData/Local/Temp/mpm-YYYYMMDD-HHMMSS"

2. 使用 Write file tool 将以下内容写入 <working folder>\mpm_download.ps1：

param(
  [Parameter(Mandatory = $true)]
  [string]$Destination
)
if (Test-Path -LiteralPath $Destination) {
  Write-Host "mpm already present at $Destination"
} else {
  Write-Host "Downloading mpm from https://www.mathworks.com/mpm/win64/mpm - this may take a few minutes..."
  Invoke-WebRequest -Uri "https://www.mathworks.com/mpm/win64/mpm" -OutFile $Destination -UseBasicParsing
  if (-not (Test-Path -LiteralPath $Destination)) { throw "mpm download failed: $Destination" }
  Write-Host "mpm downloaded to $Destination"
}

3. 运行该脚本：

powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "<working folder>\mpm_download.ps1" -Destination "C:\Users\<username>\Downloads\mpm.exe"

Linux/macOS

完整 Shell 脚本请参阅 reference/linux-macos-steps.md。概要：在 /tmp/mpm-YYYYMMDD-HHMMSS 创建工作文件夹，使用 curl -fL -o 将 mpm 下载到 ~/Downloads/mpm，并运行 chmod +x。

第 2 步 - 下载并编辑发行版输入文件

始终使用来自以下网址的发行版模板输入文件： https://www.mathworks.com/products/mpm.html

下载所需发行版的模板输入文件，然后进行编辑：

• 取消注释并将 destinationFolder 设置为所需安装路径。
• 取消注释所需产品和支持包对应的每个 product.<Name> 行。
• 在输入文件中添加 noJRE=true（单独占一行，位于 destinationFolder 之后）。这样可防止 mpm 捆绑 Java Runtime。只有用户明确要求安装 JRE 时，才省略此行。
• 添加 caller=agent 行（见下方“caller — 标记由 Agent 驱动的安装”）。
• 除非用户要求特定更新，否则不要取消注释 updateLevel。
• 不要编辑校验和行（?checksum=...）。

编辑文件后，请验证：

• 输入文件存在于预期路径。
• destinationFolder 与用户要求的安装路径完全一致。
• 每个所需的 product.<Name> 行都已取消注释（行首没有 #）。
• 未请求的产品仍保持注释状态。
• 文件中存在 caller=agent 行。

如果任何验证失败，请停止并重试下载一次，然后重新编辑并验证。 如果仍然失败，请停止并报告错误。

输入文件格式使用 product.<Name> 条目表示产品和支持包。 必须在发行版输入文件中查找准确的 product.<Name> 标识符。 产品标识符用下划线替代空格（例如，“Signal Processing Toolbox” → product.Signal_Processing_Toolbox）。

• 始终显示生成的 ps1 脚本的完整路径

caller — 标记由 Agent 驱动的安装（必需）

较新版本的 mpm 支持 caller 输入文件键，用于记录发起安装的对象。始终在输入文件中单独添加一行，固定值为 agent，因此该行应准确写为 caller=agent。

请使用此确切值 — 不要替换为 Agent 名称、模型或任何其他标识符。它仅记录此次安装由自动化 Agent 执行，以便在遥测数据中区分 Agent 驱动的安装与手动安装。

将 caller 设置在输入文件中，而不是命令行上。使用 --inputfile 时，mpm 会拒绝任何其他命令行选项，因此 caller 值必须写入输入文件。mpm 会在安装遥测数据中记录此值（并转换为大写），因此大小写无关紧要。

Windows（PowerShell）

必须：使用 Write file tool 创建此脚本。绝不能使用 -Command 或 heredoc。

1. 使用 Write file tool 将以下内容写入 <working folder>\mpm_prepare_input.ps1：

param(
  [Parameter(Mandatory = $true)]
  [string]$Release,
  [Parameter(Mandatory = $true)]
  [string]$Destination,
  [Parameter(Mandatory = $true)]
  [string]$WorkingFolder,
  [Parameter(Mandatory = $true)]
  [string]$Products
)

Set-StrictMode -Version Latest
$ErrorActionPreference = "Stop"

# -File mode passes "a,b" as one string; split into an array
$ProductList = $Products -split ',' | ForEach-Object { $_.Trim() }

$releaseLower = $Release.ToLower()
$inputUrl  = "https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/products/mpm/mpm-input-${releaseLower}.txt"
$inputFile = Join-Path $WorkingFolder "mpm_input_${releaseLower}.txt"

Write-Host "Downloading input file from $inputUrl..."
Invoke-WebRequest -Uri $inputUrl -OutFile $inputFile -UseBasicParsing
if (-not (Test-Path -LiteralPath $inputFile)) {
  throw "Input file was not downloaded: $inputFile"
}

$lines = Get-Content -LiteralPath $inputFile

$lines = $lines | ForEach-Object {
  if ($_ -match '^\s*#?\s*destinationFolder=') {
    "destinationFolder=$Destination"
    "noJRE=true"
    "caller=agent"
  }
  else {
    $_
  }
}

foreach ($product in $ProductList) {
  $escaped = [Regex]::Escape($product)
  $lines = $lines | ForEach-Object {
    if ($_ -match "^\s*#\s*$escaped\s*$") {
      $product
    }
    else {
      $_
    }
  }
}

Set-Content -LiteralPath $inputFile -Value $lines -Encoding UTF8

$lines = Get-Content -LiteralPath $inputFile

$destinationLine = $lines | Where-Object { $_ -match '^destinationFolder=' } | Select-Object -First 1
if (-not $destinationLine) { throw "destinationFolder line not found in $inputFile" }
if ($destinationLine -ne "destinationFolder=$Destination") { throw "destinationFolder mismatch: $destinationLine" }

$callerLine = $lines | Where-Object { $_ -match '^caller=' } | Select-Object -First 1
if ($callerLine -ne "caller=agent") { throw "caller line missing or incorrect: $callerLine" }

$uncommentedProducts = $lines | Where-Object { $_ -match '^\s*product\.' }
$unexpectedProducts  = $uncommentedProducts | Where-Object { $ProductList -notcontains $_ }
if ($unexpectedProducts) { throw "Unrequested products enabled: $($unexpectedProducts -join ', ')" }

foreach ($product in $ProductList) {
  if (-not ($lines -contains $product)) { throw "Requested product not enabled: $product" }
}

Write-Host "Input file ready: $inputFile"

注意：该脚本会将输入文件写入 <working folder>\mpm_input_<releaselower>.txt，因此清理工作文件夹时会自动删除该文件。脚本完成后会报告输入文件路径。

2. 运行脚本（替换为实际的工作文件夹、发行版、目标路径和产品标识符）：

powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "<working folder>\mpm_prepare_input.ps1" -Release "R2025b" -Destination "C:\MATLAB\R2025b" -WorkingFolder "<working folder>" -Products "product.MATLAB,product.Simulink"

Linux/macOS

完整 Shell 脚本请参阅 reference/linux-macos-steps.md。概要：使用 curl 下载发行版输入文件，使用 sed 设置 destinationFolder，添加 noJRE=true 和 caller=agent 行，并取消注释所需产品，然后验证所有编辑内容。

• 暂时不要删除生成的文件；清理将在第 3 步之后进行。

第 3 步 - 运行安装命令并检查是否完成

重要：

• 使用 --inputfile 时，不要传入任何其他 mpm 选项。caller 值应在第 2 步中设置在输入文件内（caller=agent），而不是放在命令行上 — mpm 会拒绝将 --inputfile 与任何其他选项组合使用。
• Windows 需要提升权限。请使用 Start-Process -Verb RunAs 以提升权限运行。
• 运行前始终显示完整展开后的命令。
• 将下方代码片段中的发行版、工作文件夹和目标路径替换为实际值。

Windows

必须：使用 Write file 工具为此步骤创建 .ps1 脚本。绝不要使用 -Command 或 heredoc。然后通过 powershell.exe ... -File <path> 调用。

使用 Write file 工具将以下内容写入 <working folder>\mpm_install.ps1，然后使用 -File 运行：

param(
  [Parameter(Mandatory = $true)]
  [string]$MpmPath,
  [Parameter(Mandatory = $true)]
  [string]$InputFile
)

$installArgs = @(
  "install",
  "--inputfile=$InputFile"
)

$display = '"' + $MpmPath + '" install ' + ('--inputfile="' + $InputFile + '"')
Write-Host "Running: $display"

Start-Process -FilePath $MpmPath -ArgumentList $installArgs -Verb RunAs -Wait

运行：

powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "<working folder>\mpm_install.ps1" -MpmPath "C:\Users\<username>\Downloads\mpm.exe" -InputFile "<working folder>\mpm_input_<releaselower>.txt"

Linux/macOS

请参阅 reference/linux-macos-steps.md。摘要：直接运行 mpm install --inputfile=<path>（无需提升权限）。caller=agent 行已在步骤 2 中写入输入文件。

步骤 4 - 验证

此步骤用于定义完成状态，必须执行。 等待 mpm 进程退出。完成前不要继续。 如果完成标记不存在，请停止并报告失败。不要重新运行步骤 3。

完成标记（使用输入文件中设置的目标文件夹）：

• Windows：<DESTINATION>\bin\matlab.exe
• Linux：<DESTINATION>/bin/matlab
• macOS：<DESTINATION>/Contents/MacOS/MATLAB

使用 Bash 工具通过 test -f 检查文件是否存在。不要使用 powershell.exe -Command 进行此检查。

test -f "<DESTINATION>/bin/matlab.exe" && echo "VERIFIED" || echo "NOT FOUND"

逐项验证

确认 MATLAB 二进制文件存在后，验证每个请求的项目是否已安装。产品和支持包存储在不同位置，且各自拥有独立的 prodcontents.json 文件。不要在错误的位置检查项目。

产品（mpm 标识符中不包含 Support_Package 的项目）：

• 使用 Read 工具读取 <DESTINATION>/appdata/prodcontents.json。
• 这是一个 JSON 对象。键为包含版本和平台标记的产品名称（例如 "Simulink 25.1 win64"）。
• 对于每个请求的产品，检查是否存在一个键，其名称以该产品的显示名称开头（去掉 product. 前缀并将下划线替换为空格）。例如，product.Signal_Processing_Toolbox 匹配以 Signal Processing Toolbox 开头的键。

支持包（mpm 标识符中包含 Support_Package 的项目）：

• 根据平台确定支持包根目录：
  • Windows： C:\ProgramData\MATLAB\SupportPackages\<RELEASE>
  • Linux： /usr/local/MATLAB/SupportPackages/<RELEASE>
  • macOS： ~/Library/Application Support/MathWorks/MATLAB/SupportPackages/<RELEASE>
• 使用 Read 工具读取 <SUPPORTPKGROOT>/appdata/prodcontents.json。
• 如果文件不存在，则支持包安装失败。请报告失败。
• 对于每个请求的支持包，检查是否存在匹配的键（名称映射方式与上述产品相同）。

对每个项目报告“已验证”或“未找到”。如果有任何项目未找到，请停止并报告失败的项目。

所有项目验证完成后，使用 Bash 工具删除整个工作文件夹及其内容：

rm -rf "C:/Users/<username>/AppData/Local/Temp/mpm-YYYYMMDD-HHMMSS"

发行说明链接

仅当安装中包含 MATLAB（基础产品）时，才在成功验证和清理后提供发行说明链接：

https://www.mathworks.com/help/matlab/release-notes.html?startrelease=<RELEASE>&endrelease=<RELEASE>&rntext=&groupby=release&sortby=descending&searchHighlight=

将 <RELEASE> 替换为已安装的发行版（例如 R2025b）。为便于阅读，请将链接单独放在一行：

访问此链接查看 MATLAB R2025b 发行说明： https://www.mathworks.com/help/matlab/release-notes.html?startrelease=R2025b&endrelease=R2025b&rntext=&groupby=release&sortby=descending&searchHighlight=

如果用户仅安装了工具箱或支持包，而未安装 MATLAB，请勿显示此链接。

常见错误

• ErrorCode::IncompatibleProduct（“所选产品不兼容”）：目标文件夹很可能已包含 MATLAB 安装。请告知用户，并让其选择一个空的目标文件夹。

关键功能和模式

命令 / 模式	用途
mpm install --inputfile=<file>	安装输入文件中定义的产品
mpm_input_<release>.txt	mathworks.com 提供的特定发行版输入文件模板
product.<Name>	产品和支持包的输入文件条目格式
destinationFolder=<path>	设置安装位置的输入文件指令
caller=agent	标记安装由 Agent 驱动的输入文件指令
Start-Process -Verb RunAs -Wait	在 Windows 上提升执行权限（UAC）
Invoke-WebRequest -OutFile	在 PowerShell 中下载文件
curl -fL -o	在 Linux/macOS 上下载文件

注意事项

• mpm 会自动安装所需的依赖项。
• 许可和激活属于独立的工作流。安装结束时不要询问用户许可或激活事宜。
• 始终使用以下位置提供的发行版输入文件： https://www.mathworks.com/products/mpm.html

---

版权所有 2026 The MathWorks, Inc.

---