matlab-read-documentation

使用 MathWorks 文档

系统化阅读 MathWorks 在线文档的方法。提供可重复的四轮策略（本地目录 → help → 用户指南页面 → 参考页面），让文档查询变得可预测且高效。通过 MCP 使用 MATLAB 的 webread 获取页面，并借助辅助脚本处理 URL 发现、HTML 解析和内容提取。

适用场景

• 你要回答与 MathWorks 产品和工作流相关的“如何……”问题
• 你猜测了一个 URL，但得到 404 — 使用此技能从索引中查找正确的 URL
• 你需要查找某个产品或工作流有哪些函数 — 从本地函数目录开始
• 你需要从权威来源核实函数的语法、参数或弃用状态
• 你想查看 MathWorks 针对特定工作流的最佳实践
• 训练数据中的知识不确定，或可能不适用于特定发行版的 API
• 用户询问 MathWorks 对特定主题的建议
• 你想通过系统化的方法，用最少的工具调用找到正确的页面（而非随便一个页面）

不适用场景

• 本地 help 命令已足够 — 查询 API 语法时优先使用 help function_name；速度更快，且始终适用于已安装的版本
• 问题涉及通用 MATLAB 编程模式，而非特定产品的工作流
• 你已经从本地 help 或成功获取的页面中获得权威答案

快速路径

并非每项任务都需要完整的四轮策略。选择最短路径来处理任务：

任务	快速路径	跳过
发行说明 / 新增内容	通过 webread 直接获取 https://www.mathworks.com/help/{product}/release-notes.md，然后提取 ## R20XXx 部分	步骤 0-2 — 无需脚本
已知的独立函数，需要参考页面	使用先前 extract_page_slugs 调用返回的 URL，或为简单的独立函数构造 baseUrl + "ref/{name}.html"	步骤 0-2 — 但 URL 必须来自已验证的来源，不可猜测
知道产品，需要函数列表	get_local_function_list(product)	步骤 1-4 — 无需访问 Web
不熟悉的 API，不知道有哪些内容	完整的四轮策略	不跳过 — 使用所有步骤

发行说明

发行说明以整洁的 Markdown 格式提供，网址为 https://www.mathworks.com/help/{product}/release-notes.md。使用 webread 获取此 URL，然后提取 ## R20XXx 与下一个 ## R 标题之间的部分。常见的产品 slug：matlab、simulink、ecoder、rtw、stateflow、fixedpoint、hdlcoder。

帮助中心页面层级

• 产品着陆页 — 列出顶级类别并附带简短说明。用于查找各分区的 slug。
• 中间类别页 — 链接到子类别，并附带单行说明。不包含叶级内容。继续深入浏览。
• 最低级类别页 — 包含参考内容组（函数、模块、应用），随后链接到相关主题和示例。
• 主题页（ug/ 或产品专属路径）— 介绍如何使用某项功能的概念性或任务型内容。
• 示例页 — 独立的完整示例，附带支持文件。可能包含实时脚本、数据文件或模型。
• 参考页（ref/ 或 slref/）— 函数、模块、对象或属性参考。包含多种类型：函数参考、对象参考、属性列表、模块参考、应用参考。
• 入门页（gs/）— 面向产品新用户的入门教程。
• 顺序主题（STEP 1、2、3）表示工作流有预定顺序。

选择要获取的内容

MathWorks 文档包含两个用途不同的内容层：

• 指南页（用户指南主题，通常位于 ug/ 下）— 说明要调用哪些函数以及调用顺序。以工作流为导向。最适合学习新 API 或确定采用何种方法。注意：并非所有产品都使用 ug/ — 有些产品（Simulink、Statistics and Machine Learning）采用不同的子目录结构。请始终通过分区索引查找。
• ref/ 页面（函数／对象参考）— 详细说明每个函数的确切调用方法：完整语法、参数类型、名称-值对、有效枚举值、返回类型以及每个参数的示例。最适合已知函数、但需要确认其确切签名的情况。有些产品使用产品专属的变体（例如，Simulink 使用 slref/）。

通常两者都需要。 ug/ 页面会告诉你操作步骤；ref/ 页面会说明各项参数的具体要求。跳过 ref/ 意味着要猜测属性名称和参数值 — 这往往会失败，因为 MathWorks API 使用的领域专用名称并不直观（例如，"ArxmlFilePackaging" 而不是 "FilePackaging"，"StopTime" 而不是 "SimulationDuration"）。

页面价值信号（与产品无关）

信号	可能价值较高	可能价值较低
slug 包含 programmatically、program- 或 command-line	是 — 始终为编程方式	—
slug 包含 property-map-functions	是 — API 工作流	—
slug 包含 explorer、interactively、using-...editor	—	是 — 仅限 GUI
页面类型为 ref/，且包含对象名或函数名	是 — 确切签名	—
页面很大（>30K），且所属产品同时支持 GUI 和编程方式	—	可能仅限 GUI — 阅读前先测量
Main Content 与页脚之间的页面内容少于约 1500 个字符	—	可能只是导航占位页或重定向页
slug 以 example- 开头	不确定 — 检查页面是否以 GUI 向导或实时脚本代码开头
ref/ 页面 slug 中列出 -properties	是 — 属性名称／值查询表

四轮策略

入口规则： 如果你已从用户请求或本次会话中的 get_local_function_list 调用获得函数名称，请从步骤 2 开始。不要仅凭训练数据中的知识跳过步骤 1——函数名称会随版本发布而变化，猜测名称会浪费调用。

1. 通过本地目录发现函数： 运行 get_local_function_list('product', 'keyword')，查找现有函数。仅在你还不知道函数名称时使用此方法。
2. 通过 help 获取签名： 运行 help functionName 或 help namespace。如果 help 已回答你的问题，就到此为止——不要再获取网页。
3. 第三轮（ug/）： 如果你需要工作流上下文——例如应先后调用哪些函数、它们如何组合，或应采用几种方法中的哪一种——请获取 slug 中包含 programmatically 的 ug/ 页面。该页面会提供调用顺序和整体模式。
4. 第四轮（ref/）： 如果 help 未能充分说明某个特定函数（输出被截断、缺少近期版本新增的名称-值参数、需要完整的属性枚举，或需要了解 find 调用的有效类别），请获取其 ref/ 页面。

何时 help 已足够（大多数情况）

• 任何函数的语法和基本参数
• 代码块说明（help simulink/Gain）
• 类和对象参考（help Simulink.SimulationInput）
• 列出命名空间中的所有函数（help matlab.io）或对象上的方法（methods(obj)）
• 每个函数功能的一句话说明
• 输入/输出参数类型
• 简单用法示例

何时 help 不够（获取网页）

• 网页 ref/ 页面： 近期版本新增的名称-值参数；设置/属性对象的完整属性名称枚举；参数的有效枚举值；find 调用可用的类别字符串；help 输出被截断或不完整。
• 网页 ug/ 页面： 工作流上下文（调用前后应执行什么）；了解多个函数如何组合；任务同时提供 GUI 和编程方式，且你需要找到编程方式；用于选择不同方法的决策指南。

URL 模式

MathWorks 文档 URL 遵循以下模式。不要猜测——使用索引查找 slug。

构建文档 URL

所有文档 URL 都按版本归档在 /help/releases/R20XXx/ 下，默认对应已安装的 MATLAB 版本。URL 的构建由 fetch_product_index 在内部处理——你无需手动构建 URL。请从以下已验证来源之一获取页面 URL：

1. fetch_product_index 的 hrefs 输出——直接返回的完整 URL，可直接使用
2. extract_page_slugs 的 fullUrls 输出——来自章节索引的完整 URL

baseUrl 已包含产品路径（例如，https://www.mathworks.com/help/releases/R2026a/autosar/）。仅追加子路径：baseUrl + "ref/name.html" 或 baseUrl + "ug/topic.html"。切勿再次添加产品名称。

页面类型模式

页面类型	模式	示例
产品索引	{base}/{product}/index.html	https://www.mathworks.com/help/releases/R2025b/simulink/index.html
章节索引	{base}/{product}/{section-slug}.html	https://www.mathworks.com/help/releases/R2025b/simulink/block-libraries.html
用户指南页面	{base}/{product}/ug/{page-slug}.html	https://www.mathworks.com/help/releases/R2025b/simulink/ug/some-topic.html
参考页面	{base}/{product}/ref/{function-name}.html	https://www.mathworks.com/help/releases/R2025b/matlab/ref/plot.html

URL 结构因产品而异。 请始终抓取章节索引以查找实际 slug，不要猜测子目录名称。

产品	指南页面	参考页面
matlab	matlab_prog/slug.html、matlab_oop/slug.html — 有多个子目录	ref/name.html
simulink	ug/slug.html	slref/name.html（配置参数也使用 gui/）
systemcomposer	ug/slug.html	ref/name.html
autosar	ug/slug.html	ref/name.html
stateflow	ug/slug.html	ref/name.html

对于 MATLAB，不含子目录的扁平 slug（例如 debug-code.html）通常是章节导航页面。抓取章节索引时，href 会显示为相对路径 — 请在前面加上基础 URL 以构造完整 URL。

常见产品 slug：matlab、simulink、systemcomposer、stateflow、autosar、ecoder、fixedpoint、stats、control、signal、dsp、deeplearning、images、optim、robust、mpc、sltest、parallel-computing

脚本

MATLAB 脚本可自动执行重复的获取和解析步骤。这些是函数文件 — 需要输入参数，必须通过 evaluate_matlab_code 调用，而不是使用 run_matlab_file。

如何调用

使用 evaluate_matlab_code，并将 project_path 设置为此技能的 scripts/ 目录（即本提示顶部显示的“此技能的基础目录”加上 /scripts）。 不要使用 run_matlab_file — 这些是需要输入参数的函数。

Tool: evaluate_matlab_code
code: "[t, hrefs] = fetch_product_index('simulink', 'Modeling')"
project_path: "<base-directory-for-this-skill>/scripts"

脚本参考

脚本	签名	用途
get_local_function_list.m	results = get_local_function_list(product, searchTerm)	从本地 MATLAB 安装中读取完整的分类函数列表（速度最快，可离线使用）
fetch_product_index.m	[t, hrefs, baseUrl] = fetch_product_index(product, search, rel)	自动检测发行版本，获取产品索引，并返回分节链接和可重复使用的基础 URL
extract_page_slugs.m	[slugs, fullUrls] = extract_page_slugs(sectionUrl)	从分节索引中提取页面 slug 和完整 URL
fetch_doc_page.m	content = fetch_doc_page(url, maxChars, startChar)	获取文档页面并提取可读文本（默认限制为 50K 个字符）。传入 startChar 可进行分页。
find_replacement.m	find_replacement(url)	搜索页面中有关弃用或替代方案的说明
DocUtilities.m	静态类（不直接调用）	共享实用工具：剥离 HTML、提取链接、解析 URL。供其他脚本在内部使用。

---

工作流

使用上方的快速路径表确定可跳过哪些步骤。以下完整工作流适用于不熟悉的 API，也就是你不知道有哪些内容时。

步骤 1 — 首先尝试 help（已有函数名时）

如果你从任何来源获得了函数名，请从这里开始：

help set_param               % function reference
help Simulink.SimulationInput  % class reference

如果 help 解答了你的问题，就到此为止。这是最常见的入口。

步骤 1b — 通过目录发现函数（没有函数名时）

如果你不知道该调用哪个函数，请先了解有哪些函数：

results = get_local_function_list('ecoder');
results = get_local_function_list('simulink', 'code generation');

此操作会返回包含 Name、Purpose 和 Category 的表格。如果你不知道产品 slug，请调用 get_local_function_list('unknown') 列出可用的 slug。然后使用发现的函数名继续步骤 1。

步骤 2 — 浏览产品索引，找到合适的页面

fetch_product_index 会自动检测发行版本、构建基础 URL，并返回分节链接：

[t, hrefs, baseUrl] = fetch_product_index('simulink', 'Modeling');

第三个输出 baseUrl 是已解析的、与版本对应的 URL；在本次会话的后续获取操作中重复使用它。

步骤 3 — 获取分节索引以查找页面 slug

直接使用 hrefs 中的 URL（由 fetch_product_index 返回）——不要手动构建 URL：

[slugs, fullUrls] = extract_page_slugs(hrefs{2,1});

步骤 4 — 获取并提取指定页面

content = fetch_doc_page(fullUrls{3});           % from discovered URLs

对于篇幅很长的页面，请限制输出：

content = fetch_doc_page(pageUrl, 10000);        % limit to 10K chars

步骤 5 — 核实弃用通知和替代方案

当 help 显示“not recommended”时，请在网页上查找推荐的替代方案：

find_replacement(baseUrl + "ref/hist.html");

---

说明

HTML 处理

获取脚本（fetch_doc_page、fetch_product_index、find_replacement）会在内部处理 HTML 剥离。不要重新实现 HTML 解析；请改为调用相应的获取脚本。

URL 发现——切勿猜测

• URL 返回 404 时，向上查找一级（分区索引或产品索引），并从页面内容中读取 slug。
• 独立函数参考页面的 URL（名称中有一个点或没有点：plot、set_param）也可以直接构造：baseUrl + "ref/{name}.html"——因为 baseUrl 已包含产品路径。
• 带命名空间的函数或对象（例如 Simulink.SimulationInput、autosar.api.create）：使用 extract_page_slugs 从相关分区索引中查找正确的 URL。
• 其他所有 URL 都必须从索引页面中查找。fetch_product_index 函数会在 hrefs 中返回完整 URL——请直接使用。

变量命名

避免使用会遮蔽 MATLAB 内置函数的名称：dir、input、length、size、path。如果工作区中已有变量遮蔽了这些名称，请在调用内置函数前使用 clear <name>。

特定产品的 URL 模式

• MATLAB：有多个子目录（matlab_prog/、matlab_oop/、ref/）。没有子目录的扁平 slug 几乎总是分区导航页面。
• Simulink：指南页面使用 ug/，模块/函数参考使用 slref/，配置参数使用 gui/。
• System Composer、Stateflow：指南页面使用 ug/，参考页面使用 ref/。层级结构简单明了。
• 同时提供 GUI 和编程路径的产品：字符数很多并不代表内容一定是编程内容——GUI 文档页面也可能包含 20K+ 字的 UI 元素说明。slug 中的 programmatically 或 program- 是可靠的判断依据。

特定版本的文档

• 所有 URL 都带版本号（/help/releases/R20XXx/）。fetch_product_index 默认使用已安装的 MATLAB 版本。传入版本参数（例如 "R2024b"）可指定其他版本。
• 请始终先核对 help 输出——它保证与已安装的版本一致。
• 如果网页文档介绍的功能在 help 中不可用，用户可能使用的是较旧版本。请指出这一差异，而不要假设该 API 存在。

---

版权所有 2026 The MathWorks, Inc.