类class io.agentscope.core.skill.util 2.x

SkillFileSystemHelper

public final class SkillFileSystemHelper

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:46–495

技能文件系统 Helper，让智能体以受控方式调用外部能力。位于 io.agentscope.core.skill.util 包。核心成员包括 loadSkill、loadSkillFromDirectory、getAllSkillNames、getAllSkills、saveSkills、deleteSkill。

Utility class for file system operations related to skills.

This class provides reusable operations for loading, listing, saving, and deleting skills on the file system. It is designed to be shared by multiple repositories such as file system and Git based repositories.

方法摘要Method Summary

方法Method	说明Description
`public static` `AgentSkill loadSkill(Path baseDir, String skillName, String source)` static	加载技能。 Loads a skill by name from the given base directory.
`public static` `AgentSkill loadSkillFromDirectory(Path skillDir, String source)` static	加载技能来自目录。 Loads a skill from a specific directory, eagerly reading every non-hidden file in the skill tree into memory.
`public static` `AgentSkill loadSkillFromDirectory(Path skillDir, String source, boolean includeResources)` static	加载技能来自目录。 Loads a skill from a specific directory.
`public static List<String> getAllSkillNames(Path baseDir)` static	获取 `getAllSkillNames`。 Retrieves all skill names by parsing SKILL.md metadata in each skill folder.
`public static List<AgentSkill> getAllSkills(Path baseDir, String source)` static	获取所有技能。 Retrieves all skills from the base directory with resources pre-loaded into memory.
`public static List<AgentSkill> getAllSkills(Path baseDir, String source, boolean includeResources)` static	获取所有技能。 Retrieves all skills from the base directory.
`public static boolean saveSkills(Path baseDir, List<AgentSkill> skills, boolean force)` static	保存技能。 Saves skills to the base directory.
`public static boolean deleteSkill(Path baseDir, String skillName)` static	删除技能。 Deletes a skill by name based on SKILL.md metadata.
`public static boolean skillExists(Path baseDir, String skillName)` static	执行 `skillExists` 方法。 Checks whether a skill exists by scanning SKILL.md metadata.
`public static Path validateAndResolvePath(Path baseDir, String skillName)` static	校验和解析路径。 Validates that a resolved path is within the base directory.
`public static boolean hasSkillFile(Path dir)` static	判断是否具有技能文件。 Checks if a directory contains a SKILL.md file.
`public static void deleteDirectory(Path directory) throws IOException` static	删除目录。 Recursively deletes a directory and all its contents.
`public static Thread registerTempDirectoryCleanup(Path directory)` static	注册 `registerTempDirectoryCleanup`。 Registers a shutdown hook to delete the given directory on JVM exit.

方法详情Method Detail

loadSkill

public static AgentSkill loadSkill(Path baseDir, String skillName, String source)

static

加载技能。

Loads a skill by name from the given base directory.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	Path	基类目录（类型 `Path`）。The base directory containing skill folders
`skillName`	String	技能名称到加载。The skill name to load
`source`	String	来源（类型 `String`）。The source identifier for the created skill

返回Returns AgentSkill

已加载 AgentSkill。The loaded AgentSkill

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if the skill cannot be found or is invalid

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:62–71

loadSkillFromDirectory

public static AgentSkill loadSkillFromDirectory(Path skillDir, String source)

static

加载技能来自目录。

Loads a skill from a specific directory, eagerly reading every non-hidden file in the skill tree into memory.

参数Parameters

名称Name	类型Type	说明Description
`skillDir`	Path	技能目录（类型 `Path`）。The skill dir.
`source`	String	来源（类型 `String`）。The source.

返回Returns AgentSkill

返回AgentSkill。Returns agent skill.

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:78–80

loadSkillFromDirectory

public static AgentSkill loadSkillFromDirectory(Path skillDir, String source, boolean includeResources)

static

加载技能来自目录。

Loads a skill from a specific directory.

参数Parameters

名称Name	类型Type	说明Description
`skillDir`	Path	技能目录（类型 `Path`）。The directory containing SKILL.md
`source`	String	来源（类型 `String`）。The source identifier for the created skill
`includeResources`	boolean	include Resources（类型 `boolean`）。when `true`, all non-hidden files under `skillDir` are pre-loaded into the skill's in-memory resource map (legacy behavior). When `false`, only SKILL.md is read; callers fall back to disk through `originDir` on demand.

返回Returns AgentSkill

返回AgentSkill。The loaded AgentSkill (with `originDir` populated)

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if SKILL.md is missing or invalid

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:96–121

getAllSkillNames

public static List<String> getAllSkillNames(Path baseDir)

static

获取 getAllSkillNames。

Retrieves all skill names by parsing SKILL.md metadata in each skill folder.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	Path	基类目录（类型 `Path`）。The base directory containing skill folders

返回Returns List<String>

返回列出。A list of skill names sorted alphabetically

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:129–146

getAllSkills

public static List<AgentSkill> getAllSkills(Path baseDir, String source)

static

获取所有技能。

Retrieves all skills from the base directory with resources pre-loaded into memory.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	Path	基类目录（类型 `Path`）。The base dir.
`source`	String	来源（类型 `String`）。The source.

返回Returns List<AgentSkill>

返回列出。Returns list.

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:153–155

getAllSkills

public static List<AgentSkill> getAllSkills(Path baseDir, String source, boolean includeResources)

static

获取所有技能。

Retrieves all skills from the base directory.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	Path	基类目录（类型 `Path`）。The base directory containing skill folders
`source`	String	来源（类型 `String`）。The source identifier for created skills
`includeResources`	boolean	include Resources（类型 `boolean`）。when `false`, each skill's resource map is left empty and callers must rely on the skill's `originDir` for disk-side reads

返回Returns List<AgentSkill>

一种列出的技能。A list of skills

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:166–193

saveSkills

public static boolean saveSkills(Path baseDir, List<AgentSkill> skills, boolean force)

static

保存技能。

Saves skills to the base directory.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	Path	基类目录到保存技能。The base directory to save skills
`skills`	List<AgentSkill>	技能到保存。The skills to save
`force`	boolean	force（类型 `boolean`）。Whether to overwrite existing skills

返回Returns boolean

返回布尔值，表示判断结果。true if all skills were saved, false otherwise

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:203–261

deleteSkill

public static boolean deleteSkill(Path baseDir, String skillName)

static

删除技能。

Deletes a skill by name based on SKILL.md metadata.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	Path	基类目录（类型 `Path`）。The base directory containing skill folders
`skillName`	String	技能名称到删除。The skill name to delete

返回Returns boolean

返回布尔值，表示判断结果。true if deleted, false if not found

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:270–285

skillExists

public static boolean skillExists(Path baseDir, String skillName)

static

执行 skillExists 方法。

Checks whether a skill exists by scanning SKILL.md metadata.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	Path	基类目录（类型 `Path`）。The base directory containing skill folders
`skillName`	String	技能名称到检查。The skill name to check

返回Returns boolean

返回布尔值，表示判断结果。true if a matching skill exists

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:294–299

validateAndResolvePath

public static Path validateAndResolvePath(Path baseDir, String skillName)

static

校验和解析路径。

Validates that a resolved path is within the base directory.

参数Parameters

名称Name	类型Type	说明Description
`baseDir`	Path	基类目录（类型 `Path`）。The base directory to constrain resolution
`skillName`	String	技能名称到解析。The skill name to resolve

返回Returns Path

返回路径。The validated absolute path

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if the path escapes the base directory

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:309–325

hasSkillFile

public static boolean hasSkillFile(Path dir)

static

判断是否具有技能文件。

Checks if a directory contains a SKILL.md file.

参数Parameters

名称Name	类型Type	说明Description
`dir`	Path	目录到检查。The directory to check

返回Returns boolean

返回布尔值，表示判断结果。true if SKILL.md exists in the directory

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:333–340

deleteDirectory

public static void deleteDirectory(Path directory) throws IOException

static

删除目录。

Recursively deletes a directory and all its contents.

参数Parameters

名称Name	类型Type	说明Description
`directory`	Path	目录到删除。The directory to delete

抛出Throws

IOException 可能抛出 `IOException`。Thrown when the operation cannot be completed.

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:348–365

registerTempDirectoryCleanup

public static Thread registerTempDirectoryCleanup(Path directory)

static

Registers a shutdown hook to delete the given directory on JVM exit.

参数Parameters

名称Name	类型Type	说明Description
`directory`	Path	目录（类型 `Path`）。The directory to delete at shutdown

返回Returns Thread

返回会话线程。Returns thread.

源码Source io/agentscope/core/skill/util/SkillFileSystemHelper.java:372–390