matlab-discover-hardware

硬件发现

1. 此技能的用途

使用此技能通过自然语言执行硬件发现任务：列出已连接的设备、按功能搜索、查看设备的详细信息和功能，以及检查是否已安装所需的支持包或附加组件。

此技能通过 scripts/ 中打包的 MATLAB 辅助函数提供硬件发现功能。始终使用提供的辅助函数 — 不要尝试复现其行为，也不要直接调用任何内部 MATLAB 函数。

何时使用

当用户询问以下内容时，启用此技能：

• 已连接或可用的硬件（例如：“插了什么设备？”、“我有哪些设备？”）
• 哪些设备支持特定功能（例如：“哪些设备支持 CAN？”、“哪些设备可以进行模拟输入？”）
• 特定设备的详细信息或功能（例如：“介绍一下 Arduino Due”、“NI USB-6211 能做什么？”）
• 设备所需的支持包或附加组件是否已安装
• 使用特定设备需要安装什么

何时不使用

以下情况不要启用此技能：

• 非硬件相关的 MATLAB 工作（常规脚本、算法开发、绘图等）
• 从设备采集或流式传输数据（请改用设备专用技能）
• 在发现设备后配置或编程（请改用设备专用技能）
• 直接安装支持包 — 此技能只报告安装状态；如有可用的安装技能，请转交给该技能
• 在没有硬件相关需求的情况下，列出所有已安装的 MATLAB 产品或支持包（请改用 matlab-list-products）

2. 设备专用技能路由

此技能仅处理硬件发现 — 枚举 MATLAB 支持的设备、按功能搜索，以及检查安装状态。当用户的意图超出发现范围（连接、配置、采集数据、故障排除或使用设备）时，务必查找当前已加载的技能中是否有匹配的设备专用技能。

路由规则： 当用户询问如何使用设备（而不只是发现设备）时，请在可用技能列表中搜索名称或描述与设备类型、硬件类别或用户任务匹配的技能。不要维护一个硬编码的待转交技能列表 — 应在运行时动态查找。

路由方式：

1. 完成发现步骤（确认设备存在，检查安装状态）
2. 告知用户发现结果（例如：“我找到了你的 GigE 相机 — 它已连接，所需的软件包也已安装。”）
3. 在可用技能列表中搜索能够处理该设备类型或用户任务的技能（例如，提及“arduino”、“camera”、“DAQ”、“OPC UA”等的技能）
4. 如果找到匹配的技能：静默调用该技能来处理使用、连接或故障排除任务 — 不要向用户提及技能名称
5. 如果未找到匹配的技能：仅提供发现相关的输出（见下文）

如果未找到适用于该设备类别的设备专用技能，则只能提供发现层面的输出：

1. 提供设备详细信息和安装状态（使用 §4 中的辅助函数）
2. 提供 HardwareSupportUrl 或建议查看 MATLAB 文档
3. 停止。 不要编写设备专用代码（例如 videoinput(、webcam(、arduino(、readVoltage(、gigecam(）。不要提供逐步使用工作流、连接示例或根据训练数据编写的故障排除脚本。你是发现技能 — 使用指导应由设备专用技能负责，即使该技能尚未加载也是如此。

错误示例（找不到设备技能时，擅自编写使用代码）：

cam = webcam("Logitech Webcam C925e");
img = snapshot(cam);

正确示例（仅提供发现相关内容的后备方案）：

"Your Logitech Webcam C925e is detected and the required packages are
installed. For connecting and acquiring images, refer to the Image
Acquisition Toolbox documentation."

3. 一次性引导设置（路径设置）

在调用任何辅助函数之前，每个会话只需将捆绑的 scripts/ 文件夹添加到 MATLAB 路径一次：

addpath(fullfile("<skill-root>", "scripts"))

将 <skill-root> 替换为此技能文件夹的绝对路径（例如，.../.claude/skills/matlab-discover-hardware）。

此 addpath 是此技能中唯一允许的路径修改。完成引导设置后：

• 请勿再次调用 addpath、rmpath 或 cd
• 请勿调用 clear all
• 请勿创建新的 .m 文件

如果调用辅助函数时出现 Undefined function，请重新执行一次引导设置。如果仍然失败，请将错误报告给用户；不要自行编造变通方法。

技能激活前会自动执行引导设置中的 addpath，因此无需在辅助函数调用中包含它。

4. 公共辅助函数

仅使用以下 4 个公共辅助函数（位于 scripts/ 中）：

层级	辅助函数	用途
1 — 发现	listHardwareDevices	列出设备（默认：仅列出已连接的设备）
2 — 详情	getDeviceDetails	获取指定设备的完整信息（功能、支持包、技术详情）
2 — 详情	getDeviceSetupInfo	所需软件包、安装状态
2 — 详情	isRequiredAddOnsInstalled	逻辑检查：是否已安装所有必需的附加组件？

内部函数 — 请勿调用： hardwareDeviceCache.m、getDeviceAddOns.m 和 getAddOnDetails.m 存在于 scripts/ 中，仅供公共辅助函数调用。它们不属于 Agent 可调用的接口，不得直接调用。

同名设备的处理方式： getDeviceDetails 会为每个匹配的设备返回一个结构体（如果有多个设备同名，则返回结构体数组）。getDeviceSetupInfo 和 isRequiredAddOnsInstalled 各返回一个结果（所有同名设备的附加组件要求相同）。

重要提示： 始终使用上面列出的公共辅助函数。请勿尝试调用 MATLAB 内部函数或手动复现辅助函数的行为。

5. 任务路由

选择与用户意图匹配的辅助函数。对于每项任务，将所有调用合并到尽可能少的 evaluate_matlab_code 调用中（批处理方式见 §6）。

用户意图	要调用的辅助函数
“我有哪些硬件？”／“哪些设备已连接？”	listHardwareDevices
“哪些设备支持 X？”（功能搜索）	listHardwareDevices(Capability=keyword)
“介绍一下 ”／“ 能做什么？”	getDeviceDetails(deviceName) + isRequiredAddOnsInstalled(deviceName)
“如何使用 ？”／“我无法连接到 ”／“如何从 采集数据？”	转交给设备专属技能（§2）。 先运行设备发现和安装状态检查，然后移交。只有在未加载设备专属技能时，才使用此技能的辅助函数。
“使用 需要安装什么？”／“使用 需要什么？”／“我可以使用 吗？”	getDeviceSetupInfo(deviceName)
“ 的附加组件安装好了吗？”	isRequiredAddOnsInstalled(deviceName)
“安装 支持包／工具箱”	检查可用技能列表，查找具有安装能力的技能；如果找到，则静默调用。否则，告知用户打开 MATLAB Add-On Explorer（Home 选项卡 → Add-Ons → Get Add-Ons），并按软件包名称搜索。
未找到设备（无论在已连接设备中还是“All”模式下）	告知用户未检测到该硬件。不要猜测需要哪些产品。静默检查可用技能列表，查找能够搜索或安装产品的技能，并主动提出协助查找所需内容，但不要向用户透露具体技能名称。

当用户的问题符合多项任务时，优先使用成本最低、目标最明确的辅助函数（例如，先使用 listHardwareDevices(Capability=...)，再使用 getDeviceDetails）。

6. 工作流模式与批处理

重要：尽量减少 MCP 往返次数

每次调用 evaluate_matlab_code 都是一次 MCP 往返，需要用户批准。尽可能将多个辅助函数调用批量合并到一次 evaluate_matlab_code 调用中。这些辅助函数共享内部缓存（TTL 为 60 s），因此在同一脚本中依次调用效率很高。

规则：

1. 已知设备名称时，合并 Layer 1 和 Layer 2 调用
2. 将安装状态检查与其前面的详细信息调用合并
3. 对于任何单个用户问题，目标是总共调用 1–2 次 MCP

批处理方案

方案 A：“连接了哪些硬件？”（1 次 MCP 调用）

deviceList = listHardwareDevices();
disp(deviceList)
clear deviceList

方案 B：“介绍一下 ”/“ 能做什么？”（2 次 MCP 调用）

调用 1 — 查找（确认设备存在）：

deviceList = listHardwareDevices();
disp(deviceList)
clear deviceList

调用 2 — 合并获取详细信息和检查安装状态：

details = getDeviceDetails("<deviceName>");
disp(details);
isInstalled = isRequiredAddOnsInstalled("<deviceName>");
if ~isInstalled
    setupInfo = getDeviceSetupInfo("<deviceName>");
    disp(setupInfo);
end
clear details isInstalled setupInfo

如果用户直接说出设备名称，且你确定名称无误（例如，他们输入了“Arduino Due”），则跳过调用 1，将所有操作合并到一次调用中：

details = getDeviceDetails("<deviceName>");
disp(details);
isInstalled = isRequiredAddOnsInstalled("<deviceName>");
if ~isInstalled
    setupInfo = getDeviceSetupInfo("<deviceName>");
    disp(setupInfo);
end
clear details isInstalled setupInfo

多个结果的处理： 如果多个设备具有相同名称（例如，两个“Kvaser Virtual”通道），getDeviceDetails 会返回结构体数组。如果 numel(details) > 1，不要展示所有结果，而应使用每个元素 BasicInfo 中的 ConnectionInfo 或其他可区分字段，启动消歧流程（§6 纯文本消歧）。

方案 C：“使用 需要安装什么？”（1 次 MCP 调用）

setupInfo = getDeviceSetupInfo("<deviceName>");
disp(setupInfo)
clear setupInfo

方案 D：按功能搜索（1–2 次 MCP 调用）

results = listHardwareDevices(Capability="<keyword>");
disp(results)
clear results

如果找到结果，且用户想了解详细信息，则继续执行方案 B 的调用 2。

先查找，再获取详细信息

在调用 Layer 2 辅助函数前，先调用 Layer 1 辅助函数（listHardwareDevices 或 listHardwareDevices(Capability=...)）。不要猜测设备名称。**例外：**如果用户明确说出设备名称，则跳过查找，直接调用 Layer 2（参见方案 B 的单次调用变体）。

优先按功能搜索

当用户描述一项任务（“我想读取 CAN 消息”）时，先调用 listHardwareDevices(Capability="CAN")，再提及具体设备。

如果功能搜索没有结果，不要猜测其他关键词，也不要根据自己的知识编造建议。应当：

1. 调用 listHardwareDevices()，显示所有已连接的设备
2. 向用户展示列表，并询问他们想用哪个设备执行该任务
3. 用户确定设备后，继续执行安装状态检查工作流

安装状态检查

当用户询问某个设备需要什么，或询问如何使用／是否可以使用某个特定设备时，请使用方案 C（getDeviceSetupInfo 包含安装状态布尔值）。如果缺少软件包，请列出它们的易读名称。静默检查可用技能列表中是否有支持安装的技能；如果有，则主动提出代用户安装，但不要说出该技能的名称。只有在没有此类技能时，才告知用户打开 MATLAB Add-On Explorer（主页选项卡 → 附加功能 → 获取附加功能）。

处理能力为空或缺失的情况

当 getDeviceDetails 返回设备的 Capabilities 字段为空时，不要根据对该开发板的一般了解猜测或推断其能力。请改为：

1. 检查当前已加载的技能中是否有与该硬件类型相关的技能（例如，NI 设备的 DAQ 技能、USRP 的无线电技能、Arduino 专用技能）
2. 如果存在相关的已加载技能，则静默调用该技能以获取能力或使用信息——不要向用户提及技能名称
3. 将收集到的信息作为设备能力呈现，只说明硬件及其支持的功能
4. 如果没有找到相关的已加载技能，且没有其他可用信息来源，则告知用户：“此设备的详细能力信息不可用。您可以在设备文档中了解更多信息。”如果有 HardwareSupportUrl，也一并提供

绝不要使用训练数据补充能力信息。只能报告来自辅助工具输出或其他已加载技能的经验证输出的信息。

后置条件：设备专属查询后始终检查安装状态

在与 getDeviceDetails 相同的批处理调用中加入 isRequiredAddOnsInstalled(deviceName)（参见 Recipe B）。如果缺少附加组件，请遵循“安装状态检查”工作流。在确认所需附加组件已安装之前，不要建议用户使用设备。

纯文本消歧

如果查询返回多个匹配项（或部分名称匹配到多个设备），必须先询问用户指的是哪个设备，再获取或呈现详细信息。不要默默显示所有匹配项的详细信息——请用带有区分属性的编号列表列出选项，并等待用户选择。

使用 FriendlyName 加上 Device ID 或 ConnectionInfo 作为区分属性来标识每个选项。如果多个条目代表由不同插件发现的同一物理端口，请说明它们是同一端口的不同接口（例如 VISA 与 serialport），并说明各自对应的工具箱——但绝不要提及插件名称、插件来源或内部检测机制。

7. 沟通规则

• 向用户标识设备时，使用 FriendlyName，而非供应商 ID 或类名
• 区分名称相同的设备时，将 Device ID 作为区分属性。按以下回退链解析 Device ID：UUID → ConnectionInfo（来自 listHardwareDevices 表，其中包含来自 CustomData.TransportProperties.Port 的端口信息）。向用户显示为“Device ID”——绝不要说“UUID”
• 绝不要向用户提及插件——包括插件名称、插件来源、Plugin 参数或内部检测机制。这些都是实现细节。区分重复条目时，应从接口类型的角度说明差异（例如“VISA 接口”与“serialport 接口”），以及用户应调用哪个工具箱／函数。
• 除非出于性能考虑需要在内部使用，否则不要向 listHardwareDevices 传递 Plugin= 选项；绝不要在回复中向用户透露插件名称。
• 列出超过约 10 个设备时，先按类别汇总数量，再询问用户是否要进一步查看
• 回答一般的设备列表／浏览查询（例如“连接了什么设备？”、“支持哪些设备类型？”）时，不要提及支持包、安装状态或“有其他可用软件包”。这适用于整个回复，包括正文和后续询问。列出设备时，任何地方都不要出现“支持包”一词，即使是作为多个选项之一也不行。反例：“您想了解功能、支持包还是设置的详细信息？”正例：“您想了解某个特定设备或其功能的详细信息吗？”只有当用户表示想要使用某个特定设备时（例如“如何使用 Arduino？”、“我可以使用网络摄像头吗？”），才提及支持包。
• 当支持包确实相关时，使用其易读名称介绍（例如“MATLAB Support Package for Arduino Hardware”）。绝不要向用户透露原始基础代码（例如 "ML_ARDUINO"）。
• 忠实于辅助函数的输出：不要虚构辅助函数未返回的功能、示例或文档链接

8. 严格防护规则

• 不得调用内部 API。 绝不要直接调用内部 MATLAB 函数——始终使用提供的辅助函数
• 除引导初始化外，不得修改路径。 一次性引导初始化之后，不得使用 addpath、rmpath 或 cd
• 不得使用 clear all。 仅在需要时清除特定变量
• 默认不使用 Refresh=true。 只有用户明确要求获取最新数据（“重新扫描”“刷新”“现在连接了什么？”）时，才传递 Refresh=true
• 不得创建新的 MATLAB 文件。 此技能仅用于使用现有内容
• 不得假定已安装。 在声称软件包已就绪前，始终通过 isRequiredAddOnsInstalled 或 getDeviceSetupInfo 检查安装状态
• 有可安装产品的技能可用时，不得手动安装作为备用方案。 静默检查可用技能列表；如果某项技能可以安装产品，应主动提出代用户安装，而不是介绍 Add-On Explorer 的操作步骤。绝不要向用户透露内部技能名称

9. 解读 CustomData

getDeviceDetails 的输出可能包含 CustomData 字段，其中提供标准字段中没有的设备专属技术信息。当 CustomData 存在且非空时，其中包含值得向用户展示的额外详情，例如：

• 传输属性： 串行端口（Address/Port）、波特率、连接类型（Serial、WiFi、Bluetooth）
• 硬件标识符： 序列号、制造商、VID/PID（USB 供应商/产品 ID）
• 特定开发板的信息： 开发板型号、固件版本、WiFi 端口

回答有关设备连接、端口、地址或硬件身份的问题时，务必检查 CustomData。即使 CustomData 中包含实际端口或地址，标准的 BasicInfo.ConnectionInfo 字段也可能为空。传输层详情应以 CustomData 为准。

向用户展示 CustomData 时，请使用通俗语言（例如，“通过 USB 连接到 COM4”），不要直接输出原始结构体字段。

10. 输出处理指南

根据 nargout，所有辅助函数都支持双重输出模式：

• 捕获输出（x = listHardwareDevices()）：需要分析数据、筛选数据或提取字段供后续调用时使用。这会禁止 MATLAB 显示输出。
• 不捕获输出直接调用（listHardwareDevices()）：用户明确要求在 MATLAB 命令窗口中显示辅助函数格式化输出时使用。

默认捕获输出并使用 disp() 显示。这样可以在同一个脚本中串联多次调用，同时仍能展示结果。仅在单个辅助函数独立调用时使用显示模式（不捕获输出）。

在一个脚本中批量调用多个辅助函数时，请在调用之间使用 disp() 或 fprintf() 展示中间结果。务必在末尾清除临时变量，避免污染用户的工作区：

details = getDeviceDetails("Arduino Due");
disp(details);
isInstalled = isRequiredAddOnsInstalled("Arduino Due");
fprintf("Add-ons installed: %d\n", isInstalled);
clear details isInstalled

---

版权所有 2026 The MathWorks, Inc.

---