setup-custom-libraries

设置自定义库

注册或更新自定义 Simulink 模块库，以便 Agent 在构建模型时优先使用它们，而非内置模块。

适用场景

• 用户要求设置、注册、添加或配置自定义库
• 用户想要向现有库配置中添加新的 .slx 文件
• 用户说“设置自定义库”“添加我的库”“配置库”“添加新的库文件”
• building-simulink-models 通过策略门控（gatePass: false）路由到此处
• 绝不要在 found: false 时调用——这表示尚未配置自定义库，且用户也没有要求配置

不适用场景

• 用户想要从头创建自定义库（编写新模块、构建新的 .slx 库文件）→ 直接使用 building-simulink-models 技能和 model_edit。此技能仅注册现有库，无法创建库内容。
• 仅配置模块排除项或参数保护（库已声明）→ 使用 configuring-block-policy
• 仅整理模块描述或类别（库已声明）→ 使用 simulink-curating-library-kg

工作流程

首先单独执行此操作——同一条消息中不要调用其他工具。

调用 library.settingsLookup()——返回包含已解析绝对路径的结构体：

• found — 是否找到库文件（satk-libraries.json 或旧版 reuse-libraries.json）
• enabled — 是否已配置自定义库
• gatePass — 是否满足门控条件
• dataRoot — 包含 .satk/ 的目录的绝对路径
• kgIndexPath、librariesPath、policyPath — 数据文件的绝对路径

解读结果：

• found: false → 尚未配置自定义库。除非用户明确要求，否则不要继续设置。将控制权交还给调用技能。
• gatePass: true, found: true → 所有数据文件均已就绪，且知识库已填充。提供管理菜单（见下文）。
• gatePass: false, found: true → 已声明库，但知识库需要填充。跳过门控 1（库已存在）。从下文的门控 2 开始，将 dataRoot 用作目标路径。

所有门控 API 的详细信息均参阅 references/library-setup.md——这是 API 调用、示例和各门控选项的唯一权威来源。

门控 1——库声明：仅当用户明确要求设置自定义库，且尚不存在库文件时执行。停止并询问用户是否有可复用的库。提供两个选项：是（声明库）或无（目前没有库）。在用户回复前，不要读取参考文件、打开模型或规划模块。

• 如果用户提供了库（是）→ 使用 library.LibraryConfig.save(prefdir(), libraries) 保存到 prefdir。
• 如果用户说**“无”** → 不要创建任何文件。门控保持开放状态（未配置时使用标准模块）。

**门控 2——模块策略：**如果缺少 .satk/block-policy.json，停止并按照 references/library-setup.md 询问用户是否要设置策略。在策略问题解决前不要继续。

门控 3——库模块知识索引：如果知识库为空（index.md 中包含 populated: false）或缺失，停止并询问用户是否要为其库模块建立索引，以便 Agent 在构建模型时了解有哪些模块可用。提供两个选项：自动（由 Agent 自主推断类别和描述）或引导设置（交互式整理）。两种选项都会调用 simulink-curating-library-kg 技能。详情请参阅 references/library-setup.md。在知识图谱（KG）生成完成前不要继续。

管理菜单（配置已完成）

使用 references/library-setup.md §「状态显示（管理菜单）」中的 API，检索并显示用户当前的配置状态。显示库名称/路径、带回退选项的策略模式，以及 KG 块和类别数量。然后提供以下选项：

• (a) 添加或移除库 — 使用 library.LibraryConfig.load(dataRoot) 加载现有配置，追加/移除条目，使用 library.LibraryConfig.save(dataRoot, allLibs) 保存，然后调用 simulink-curating-library-kg 技能（自动模式）以重新生成 KG。
• (b) 更新块策略 — 加载 configuring-block-policy 技能。
• (c) 将配置提升到 prefdir — 仅当层级为 project 或 legacy 时显示。将 .satk/ 文件夹复制到 prefdir/.satk/（将相对路径展开为绝对路径）。有关提升 API，请参阅 references/library-setup.md §「Gate 1」。
• (d) 重新生成知识索引 — 加载 simulink-curating-library-kg 技能。

向现有配置添加文件

当 satk-libraries.json 已存在且其中声明了库时：读取现有配置，追加新的库条目，使用 library.LibraryConfig.save() 保存，然后调用 simulink-curating-library-kg 技能（自动模式），为新块推断类别/描述并重新生成知识索引。

防护规则

• 绝不手动写入配置文件或 .satk/ JSON。 对于每种情况，始终遵循 references/library-setup.md 中的说明和 API。
• 不要使用 find_system、load_system 来发现、验证或枚举库内容。所有库操作都必须通过 references/library-setup.md 中指定的 API 进行。
• 每个关卡都需要用户明确输入后才能继续。 不要擅自假设；等待用户回复后再进入下一关。
• prefdir 中的路径必须为绝对路径。（项目级路径可以相对于项目根目录。）

---

版权所有 2026 The MathWorks, Inc.

---