matlab-analyze-dependencies

matlab-analyze-dependencies — 依赖分析器

你将生成依赖清单：完整说明该工具箱在运行时需要什么、哪些内容会打包到 .mltbx 中，以及哪些内容不会打包。对于未打包的内容，你需要解释原因并提供解决方案。

适用场景

• matlab-define-toolbox-api 规范获批后，或用户询问“这段代码依赖什么？”
• 代码更改后重新运行，以更新清单

不适用场景

• 编写代码或修复 bug——此技能只分析，不修改源代码
• 构建 .mltbx——依赖项解决后请使用 matlab-build-toolbox
• 初始项目设置——请先使用 matlab-define-toolbox-api 定义工具箱规范

主要函数

函数	用途
matlab.addons.toolbox.ToolboxOptions	确定实际文件集（哪些内容会打包）
matlab.codetools.requiredFilesAndProducts	跟踪传递性文件和产品依赖项
which	解析带命名空间限定的函数名
exist	检查不带命名空间的函数名是否能解析
matlab.addons.installedAddons	将附加组件文件路径与元数据关联起来

关键陷阱

以下三个问题会导致静默失败——不会引发错误，但分类结果会出错。务必应用这些修正。

陷阱 1：路径分隔符不匹配（Windows）

在 Windows 上，无论输入是什么，fList 都会返回反斜杠。如果 toolboxRoot 使用正斜杠，startsWith(fList, toolboxRoot) 会静默地对每个文件都返回 false。比较之前务必先规范化两者：

toolboxRoot = replace(toolboxRoot, '/', filesep);
fList = replace(fList, '/', filesep);

陷阱 2：泄漏出 matlabroot 文件

位于 matlabroot 下的文件（例如 toolbox/local/userpath.m）偶尔会出现在 fList 中，因为它们位于非产品目录结构中。将它们筛除：

mroot = matlabroot;
fList = fList(~startsWith(fList, mroot));

陷阱 3：命名空间解析需要使用 which()

即使函数有效且位于路径上，exist('pkg.subpkg.func', 'file') 也会返回 0。对于任何带点号或带命名空间限定的名称，请改用 which()：

% exist() FAILS for namespace calls:
exist('statskit.internal.computeRange', 'file')  % returns 0 (wrong!)

% which() WORKS:
which('statskit.internal.computeRange')  % returns full path

解析策略：

• 不带命名空间的名称（无点号）：exist(name, 'file') > 0 || exist(name, 'builtin') > 0
• 带点号的名称：~isempty(which(name))

核心概念

打包限制： .mltbx 只能包含工具箱根文件夹内的文件。安装时无法拉取外部文件。只有以下选项：复制到工具箱中、声明附加组件依赖项、通过 Additional Software 提供 URL zip，或重构。

实际文件集： 工具箱根目录中的所有文件，减去忽略文件和默认排除项。使用 ToolboxOptions 来权威地确定此文件集。忽略文件可能命名为 toolbox.ignore（R2026a 及更早版本）或 package.ignore（R2026b 及更高版本）。请检查这两种文件名——ToolboxOptions 会处理实际存在的文件。

工作流

阶段 1 — 确定实际文件集

identifier = matlab.lang.internal.uuid();
opts = matlab.addons.toolbox.ToolboxOptions(toolboxRoot, identifier);
effectiveFiles = opts.ToolboxFiles;

请勿手动重新实现忽略文件逻辑。ToolboxOptions 会处理这两种文件名、默认排除项和边缘情况。

Phase 2 — 追踪依赖项

mFiles = effectiveFiles(endsWith(effectiveFiles, ".m") | endsWith(effectiveFiles, ".mlx"));
[fList, pList] = matlab.codetools.requiredFilesAndProducts(mFiles);
fList = string(fList(:));

获取 fList 后，立即应用 Pitfall 1（规范化路径）和 Pitfall 2（过滤 matlabroot），然后再进行任何分类。

对 fList 中的文件分类：

• 已包含：以 toolboxRoot 开头且在有效集合中
• 附加组件：位于 fullfile(getenv('APPDATA'), 'MathWorks', 'MATLAB Add-Ons') 下
• 未解析的外部文件：其他所有文件——需要用户决定

对 pList 中的产品分类：

• Certain == 1：已确认的产品依赖项——在元数据中声明
• Certain == 0：启发式猜测——标记以供用户确认

**检查忽略项冲突：**位于工具箱根目录内、包含在 fList 中但不在 effectiveFiles 中的文件——代码需要这些文件，但它们不会随包发布。

检查运行时文件引用：fList 从不包含数据文件（.mat、.csv、图像等）。扫描 .m 文件中的 I/O 函数，查找参数为字符串字面量路径的调用，以检测代码在运行时需要但不会随包发布的文件。完整的函数列表、正则表达式模式和分类逻辑，请参见 references/runtime-file-references.md。

Phase 2b — 检测未解析的符号

requiredFilesAndProducts 会静默跳过无法解析的符号，因此需要单独执行检测步骤。

不要依赖 checkcode/codeIssues——MATLAB 的静态分析器有意对未解析的函数采取宽松处理。

对每个文件提取候选函数名（通过 mtree 或正则表达式 (?<![%.\w])([a-zA-Z]\w*)\s*\(）。过滤掉：

• MATLAB 关键字（if、for、while、switch、function、arguments、end、return）
• 函数自身的名称
• 同一文件中定义的局部函数
• arguments 块中的变量（验证语法在正则表达式看来像函数调用）
• 来自 localfunctions 模式的函数（测试文件）

对于带点的标识符（正则表达式：([a-zA-Z]\w*(?:\.[a-zA-Z]\w*)*)(?=\s*\()），应用 Pitfall 3——使用 which()。

对未解析的符号进行分类，并附上解决建议。完整的分类表和展示格式，请参见 references/unresolved-symbol-classification.md。

Phase 3 — 外部文件的传递闭包

对每个外部文件追踪其依赖子树。在每一层对子项进行分类。构建树形结构，展示引入这些文件的成本。

**提前终止：**如果子树涉及多个目录且文件数超过约 15 个，则标记为“范围庞大”——需要通过架构层面解决，而不是逐个复制文件。

**去重：**对每个工具箱文件使用 'toponly'，查找直接调用了哪些外部文件。仅通过另一个外部文件间接到达的外部文件应嵌套在其父项下，而不作为顶层决策项显示。

**检测模式：**来自同一目录的多个外部文件 → 将它们分组。父文件夹中包含 .prj 或 resources/project/ → 该目录属于 MATLAB Project。

Phase 4 — 展示结果

生成树形视图，展示直接调用的外部文件、调用链和传递成本，并附上汇总表。格式指南请参见 references/tree-view-format.md。

Phase 5 — 推荐解决方案

针对每个未解析的外部文件或文件组，提供不同方案及其权衡。方案矩阵和外移重构交接模板请参见 references/resolution-options.md。

此技能不会执行解决方案。它会展示选项，以便用户（或负责处理工具箱结构的下游技能）采取行动。不要复制文件、编辑忽略文件或重构代码。

Phase 6 — 持久化清单

用户确认分析后，将其保存为 buildUtilities/tbxManifest.m。清单记录当前状态——哪些内容会随包发布、哪些是外部内容、哪些尚未解析——而非解决方案的决策。模板结构请参见 scripts/tbxManifest-template.m。

输出

• 主要产物：buildUtilities/tbxManifest.m
• 展示内容：对话中提供树形视图、汇总表和建议

范围界定

此技能仅分析并提出建议。它不会：

• 将文件复制或移动到工具箱中
• 编辑忽略文件
• 重构代码或修正拼写错误
• 修改 MATLAB 路径

这些操作由用户负责，或交由了解工具箱应如何组织的下游技能处理。外部完成相应处理后，请重新运行此技能以确认进展。

关键规则

• 显示引入任何外部依赖的完整传递成本
• 将同一文件夹中的文件组作为一项架构决策呈现，而非拆成 N 项单独决策
• 提供带有利弊权衡的处理选项——不要执行这些操作
• 外部完成处理后，重新运行应能显示进展（外部依赖变为已包含项或附加组件）
• 标记忽略规则冲突——需要但被排除的文件会造成隐蔽的打包错误

后续步骤

• /matlab-create-project — 将文件整理到 MATLAB 项目中，并采用已确定的依赖结构

---

Copyright 2026 The MathWorks, Inc.

---