matlab-define-toolbox-api

matlab-define-toolbox-api — 工具箱范围与规范生成器

你接收一个代码文件夹，判断哪些内容属于工具箱、识别公共 API，并生成接口规范——用于定义工具箱对外提供的内容。一项技能，一个产物。

适用场景

• 用户想将代码打包成工具箱
• 用户指定一个文件夹，并说“把它做成工具箱”或“打包这个”
• 用户的文件夹中混有脚本、函数、测试、数据和临时文件
• 从头开始文件打包流程

不适用场景

• 向现有规范添加文件——直接编辑 buildUtilities/toolboxSpecification.m
• 分析依赖项——规范获批后使用 matlab-analyze-dependencies
• 构建 .mltbx 包——使用 matlab-build-toolbox
• 编写工具箱文档——使用 matlab-document-toolbox

关键函数

函数	用途
dir	递归列出文件以进行清点
which	解析路径上的函数位置
exist	检查名称是否对应文件、文件夹或内置项
matlab.codetools.requiredFilesAndProducts	跟踪调用方与被调用方的关系，以进行 Support 分类

输入

输入	必需	说明
path	否	要分析的文件夹或文件列表。如果未提供，则提示用户。
purpose	否	工具箱的功能及其使用者。如果未提供，则提示用户。

工作流

步骤 1 — 收集输入

如果未提供 path：

你想将哪个文件夹或哪些文件打包成工具箱？

如果未提供 purpose：

请用一两句话说明这个工具箱的功能及其使用者。

在两项输入都提供之前，不要继续。

步骤 2 — 清点文件夹

递归扫描路径。对每个文件进行分类：

类别	判定规则
Function	.m 文件的第一条非注释行包含 function 关键字
Class	.m 文件包含 classdef 关键字
Script	.m 文件不包含 function/classdef 关键字
Live Script	.mlx 文件
Test	位于 tests//test/ 文件夹中，或名称匹配 *Test.m、*_test.m、test_*.m
Data	.mat、.csv、.xlsx、.json、.xml（非配置文件）
Config/Meta	buildfile.m、projectStartup.m、Contents.m、.prj、resources/
Scratch/Temp	位于 scratch/、tmp/ 中，或名称类似 untitled*.m、Copy_of_*
Other	README、图片、许可证等

步骤 3 — 分类相关性

以 purpose 为依据，对每个文件进行分类：

• Include — 直接服务于工具箱所述用途
• Support — 被纳入的文件所需（内部调用的辅助工具）
• Exclude — 无关（测试、临时文件、不相关代码）
• Uncertain — 需要用户输入

启发式规则：

信号	处理方式
函数名称与用途关键词相符	Include
H1 文本提及用途中的概念	Include
被纳入的文件调用	Support
位于 private/ 或 +internal 文件夹中	Support
纳入函数的测试文件	Exclude
与用途无关的脚本	Exclude
被纳入代码引用的数据文件	Include
临时文件命名模式	Exclude

步骤 4 — 识别公共 API

根据 Include 集合确定可见性：

信号	分类
有 H1 帮助文本	可能是公共 API
有 arguments 块或输入验证	可能是公共 API
名称描述清晰且以动作导向	可能是公共 API
带有公共方法的 Classdef	公共 API
被其他文件调用但不能独立使用	内部 API
位于 private/ 文件夹中或名称为通用工具名	内部 API
Script	示例/入口点

Step 5 — 展示报告并获取确认

显示合并后的范围 + API 报告：

## Toolbox Scope & API — [Name]

**Purpose:** [user's stated purpose]
**Source:** [path]
**Total files:** N

### Public API (N functions)
| Function | Signature | H1 | Category |
|----------|-----------|-----|----------|

### Internal Support (N files)
| File | Type | Reason |
|------|------|--------|

### Excluded (N files)
| File | Reason |
|------|--------|

### Uncertain — Need Your Input
| File | Why Uncertain |
|------|--------------|

然后询问：

请审阅：

1. 是否应纳入任何已排除的文件？
2. 是否应移除任何已纳入的文件？
3. 对于不确定的文件——纳入还是排除？
4. 公共 API 范围是否正确？
5. 函数应按哪些类别分组？（例如“分析”“I/O”“可视化”）

继续之前，先整合反馈。

Step 6 — 生成接口规范

使用 scripts/toolboxSpecificationTemplate.m 作为结构模板，生成 toolboxSpecification.m。spec.entries 是一个元胞数组（而非结构体数组），因为 classdef 条目包含额外字段（methods、properties），而 function 条目没有这些字段——MATLAB 无法拼接字段不匹配的结构体。通过 spec.entries{i} 访问条目。每个条目都有一个 "type" 字段，值为 "function" 或 "classdef"。两种类型的完整字段约定请参见模板。

将文件保存到项目根目录下的 buildUtilities/toolboxSpecification.m（如有需要，请创建此文件夹）。此文件夹通过 toolbox.ignore 或 package.ignore 从工具箱包中排除。

输出

• 单个产物：buildUtilities/toolboxSpecification.m — 作为 MATLAB 结构体的可执行规范
• 展示内容：会话期间展示的 Markdown 报告，供审阅
• 下游用途：其他技能（matlab-assess-toolbox、matlab-build-toolbox、matlab-analyze-dependencies）使用 toolboxSpecification.m

检查点

此技能始终会在 Step 5 暂停，等待用户批准。 生成规范之前，用户必须确认范围和公共 API。确认前不会写入任何内容。

关键规则

• 缺少输入时，务必提问。 切勿猜测路径或用途。
• 每个文件都必须有明确处理结果。 不会静默丢弃任何文件——文件会被纳入、排除（并说明原因）或标记为不确定。
• 分类依据是用途。 用户说明的意图是主要筛选依据。
• 不确定性是有效选项。 明确指出模糊之处，不要贸然猜测。
• 必须说明原因。 每项纳入或排除的决定都必须注明原因。
• 排除测试文件，但需记录。 后续由 matlab-assess-toolbox 处理。
• 脚本作为示例。 不含 function 关键字的文件属于示例/入口点，而非公共 API。
• 可见性由用户决定。 启发式规则仅提供建议，最终由用户确认。
• 单个产物，存放于构建工具目录。 只写入 toolboxSpecification.m，并保存到 buildUtilities/——保持源代码整洁，并从打包的工具箱中排除。

后续步骤

• /matlab-analyze-dependencies — 解决接口规范中识别出的外部依赖项
• /matlab-create-project — 参考规范，将文件整理到 MATLAB 项目中

---

Copyright 2026 The MathWorks, Inc.

---