---
title: "talents - SkillTalent 对接海量 Claude Agent Skills"
---

在 Solon AI 生态中，`SkillTalent` 是一个基于 Pool-Manager（挂载池管理）模型的 CLI 综合技能组件。它深度对齐了 Claude Code 的执行协议，使您可以直接复用海量的开源 AI 技能插件，快速打造一个类似于 Claude Code CLI 的智能终端应用。

`SkillTalent` 由三个核心 Talent 组成，可以独立使用或组合使用：

* **TerminalTalent**：充当 Agent 的"手"和"眼"，负责文件操作（ls, read, write, edit）和命令执行（bash）。
* **SkillTalent**：负责解析挂载池中的 SKILL.md，为 Agent 提供领域专家的指令指引。
* **TodoTalent**：提供复杂任务的拆解、进度跟踪及计划修订能力。


相关依赖包：[solon-ai-skill-cli](/article/1358)


### 1、什么是 SkillTalent？能干什么？

`SkillTalent` 是一个 AI 技能管理器。它基于底层的 `MountManager`（挂载池管理器），自动扫描挂载目录中包含 `SKILL.md` 的子目录，将其识别为一个个独立的技能单元，并为 Agent 提供发现、搜索和加载能力。

它能干什么？

* **技能发现**：自动扫描挂载池中的技能目录（含 `SKILL.md` 的目录），提取名称和描述，构建技能索引。
* **三阶段自适应模式**：根据技能数量自动切换交互模式 —— 少量时展示完整摘要，中等规模仅展示路径索引，大量时强制搜索定位。
* **技能检索**：支持多关键字搜索，快速在海量技能库中找到匹配项。
* **技能加载**：读取指定技能的 SKILL.md 详细说明书，同时列出该技能目录下的可用文件及逻辑路径映射。
* **热刷新**：支持增量刷新指定挂载点或全量刷新所有挂载点的技能列表。

#### 三阶段自适应模式

SkillTalent 内置了两个阈值参数（`listThreshold` 和 `searchThreshold`），根据当前技能库规模自动选择最优的交互策略：

| 技能数量 | 运行模式 | 可用工具 | Agent 行为指引 |
| -------- | -------- | -------- | -------------- |
| ≤ `listThreshold`（默认 30） | 摘要发现 | `skillread`, `skillrefresh` | 直接展示技能名称和描述，Agent 可判断后调用 `skillread` 深入阅读 |
| ≤ `searchThreshold`（默认 100） | 路径导航 | `skillread`, `skilllist`, `skillrefresh` | 仅展示技能路径索引（无描述），Agent 需推断功能后读取，不确定时可搜索 |
| > `searchThreshold` | 动态发现 | 全部工具（含 `skillsearch`） | 禁止猜测路径，Agent 必须先用 `skillsearch` 检索关键字，确认后再读取 |

这种设计确保了在少量技能时不暴露多余工具干扰 Agent，在大量技能时又提供了足够的检索能力。


### 2、快速开始

#### 第一步：准备技能包

在使用 SkillTalent 之前，您需要下载一批符合 Claude Code 规范的技能插件。这些插件目录中通常包含一个 SKILL.md 文件，用于描述工具的用法。

* 推荐资源：[https://github.com/zrt-ai-lab/opencode-skills](https://github.com/zrt-ai-lab/opencode-skills) 开源仓库 您可以将其克隆到本地目录。

#### 第二步：创建挂载管理器

`MountManager` 是整个技能体系的基础设施。它负责管理工作区路径、注册挂载点，并将逻辑路径（如 `@skills`）解析为物理路径。

```java
// 创建挂载管理器，指定工作区目录
MountManager mountManager = new MountManager("/WORK/my_project");

// 注册技能挂载点（类型为 SKILLS）
// 支持路径语法："./"（工作区相对）、"~/"（用户目录相对）、绝对路径
mountManager.register(MountDir.builder()
        .alias("@skills")
        .type(MountType.SKILLS)
        .path("/path/to/opencode-skills")
        .build());
```

#### 第三步：集成到 Agent

通过 `TerminalTalent` 和 `SkillTalent` 组装完整的 CLI 能力，并配置 `ReActAgent`。

```java
// 创建 TerminalTalent（提供 ls, read, write, edit, bash 等文件和命令工具）
TerminalTalent terminalTalent = new TerminalTalent(mountManager);
terminalTalent.setSandboxEnabled(true); // 默认已启用沙盒模式

// 创建 SkillTalent（提供技能发现、搜索和加载工具）
SkillTalent skillTalent = new SkillTalent(mountManager);

// 创建 TodoTalent（提供任务进度跟踪）
TodoTalent todoTalent = new TodoTalent();

ReActAgent agent = ReActAgent.of(LlmUtil.getChatModel())
        .name("SolonCodeAgent")
        .defaultTalentAdd(terminalTalent)  // 注入终端能力
        .defaultTalentAdd(skillTalent)     // 注入技能管理能力
        .defaultTalentAdd(todoTalent)      // 注入任务追踪能力
        .maxTurns(30)
        .autoRethink(true)
        .build();

// 发起任务：Agent 会自动 ls 目录，阅读代码，并根据需要调用 bash 执行指令
agent.prompt("帮我把当前目录下的所有 .wav 文件转换成 .mp3");
```


### 3、标准工具映射说明

#### TerminalTalent 内置工具

Agent 会根据上下文自动选择以下工具：

| 工具 | 说明 |
| ---- | ---- |
| `ls` | 列出目录内容。支持递归 Tree 结构展示（最多 3 层深度），支持逻辑路径（如 @pool）。自动过滤 `.git`、`node_modules`、`target` 等干扰目录。 |
| `read` | 分页读取文件内容。自动识别编码，支持 `offset` 和 `limit` 参数分页。单次读取受 128KB 物理长度保护，超限时提示续读参数。会自动检测并拒绝二进制文件。 |
| `grep` | 递归搜索内容，返回 `路径:行号:内容` 格式。支持正则表达式匹配。搜索结果同样受 128KB 限制保护。 |
| `glob` | 按通配符模式（如 `**/*.java`）搜索文件。最多返回 500 个匹配结果。 |
| `write` | 创建新文件或覆盖现有文件。自动创建父目录。 |
| `edit` | 精准文本替换工具。支持单次调用执行多处编辑（传入 `edits` 数组）。具有原子性：所有编辑预校验通过才会写入，否则全部回滚。要求 `old_str` 在文件中唯一。支持 `replace_all` 模式批量替换。 |
| `bash` | 执行非交互式 Shell 指令。支持多行脚本。自动将 `@pool` 路径转为环境变量。内置安全校验：禁止 kill 宿主进程、禁止 `exit`、禁止 `rm -rf /`。支持自定义超时时间（默认 120 秒）。 |

#### TerminalTalent 异步会话工具（可选启用）

通过 `terminalTalent.setBashAsyncEnabled(true)` 启用后，额外提供以下工具，用于处理长时间运行的命令：

| 工具 | 说明 |
| ---- | ---- |
| `bash_start` | 启动 shell 命令会话。若命令在 `yield_time_ms`（默认 1 秒）内未完成，会返回 `session_id` 供后续操作。支持 `hard_timeout_ms`（默认 120 秒）硬超时兜底。 |
| `bash_wait` | 继续等待仍在运行的命令会话，返回自上次读取后的新增输出。 |
| `bash_stdin` | 向运行中的命令会话写入 stdin 文本。 |
| `bash_stop` | 终止运行中的命令会话及其子进程树。 |

#### SkillTalent 内置工具

| 工具 | 说明 |
| ---- | ---- |
| `skilllist` | 列出所有挂载点中的可用技能清单（含名称和描述）。当技能数量超过 `searchThreshold` 时禁止全量列出。 |
| `skillsearch` | 在所有挂载点中搜索技能关键字。支持空格分隔多个词，匹配名称和描述。最多返回 15 条结果。 |
| `skillread` | 读取指定技能的详细说明书（SKILL.md 内容）及目录下的可用文件列表（含逻辑路径映射）。 |
| `skillrefresh` | 重新扫描所有挂载点，更新技能列表。返回刷新后的技能总数。 |

#### TodoTalent 内置工具

| 工具 | 说明 |
| ---- | ---- |
| `todoread` | 读取当前任务清单（Markdown 格式）。清单为空时返回提示。 |
| `todowrite` | 写入任务列表（新建、更新或重构）。接收完整的 Markdown 格式清单，支持 `##` 标题分组和 checkbox 标记（`- [ ]` 待办、`- [/]` 进行中、`- [x]` 已完成）。 |


### 4、挂载管理体系

#### MountManager 核心概念

`MountManager` 是 SkillTalent 的基础设施，管理着逻辑路径到物理路径的映射关系：

| 概念 | 说明 |
| ---- | ---- |
| **工作区（WorkDir）** | Agent 的主目录，支持读写。使用相对路径访问。 |
| **挂载点（MountDir）** | 以 `@` 开头的逻辑路径别名，映射到一个真实的物理目录。每个挂载点具有 `alias`、`type`（SKILLS/AGENTS）、`path`、`writeable`、`enabled` 等属性。 |
| **技能目录（SkillDir）** | 挂载点下包含 `SKILL.md` 文件的子目录，被视为一个独立的技能单元。 |
| **路径语法** | `./` 表示工作区相对路径，`~/` 表示用户主目录相对路径，`@xxx` 表示挂载点逻辑路径。 |

#### 多技能池挂载

支持注册多个不同类型的挂载点，实现资源隔离：

```java
MountManager mountManager = new MountManager("/WORK/my_project");

// 技能类挂载（只读）
mountManager.register(MountDir.builder()
        .alias("@media")
        .type(MountType.SKILLS)
        .path("/path/to/ffmpeg-skills")
        .build());

// 另一个技能挂载
mountManager.register(MountDir.builder()
        .alias("@ops")
        .type(MountType.SKILLS)
        .path("/path/to/deploy-scripts")
        .build());

// 代理类挂载
mountManager.register(MountDir.builder()
        .alias("@agents")
        .type(MountType.AGENTS)
        .path("/path/to/agent-configs")
        .build());
```

Agent 在执行时，可以通过逻辑路径（如 `@media/extract_audio.sh`）安全地访问这些资源。

#### 挂载点操作

```java
// 移除挂载（同时清理关联的技能缓存）
mountManager.remove("@ops");

// 增量刷新指定挂载点
mountManager.refresh("@media");

// 全量刷新所有挂载点
mountManager.refresh();

// 查询挂载下的技能列表
List<SkillDir> skills = mountManager.getSkillsByMount("@media");

// 路径解析
Path realPath = mountManager.resolve(workDir, "@media/scripts/convert.sh");
```

#### TerminalTalentProxy 精细化工具控制

如果不需要暴露 TerminalTalent 的全部工具，可以使用 `TerminalTalentProxy` 进行按需筛选：

```java
TerminalTalent terminalTalent = new TerminalTalent(mountManager);

// 创建代理，仅暴露指定工具
TerminalTalentProxy proxy = new TerminalTalentProxy(terminalTalent);
proxy.addTools("read", "grep", "glob", "ls");

// 将代理注册到 Agent（而非原始 TerminalTalent）
agent.defaultTalentAdd(proxy);
```


### 5、沙盒模式

沙盒模式是 TerminalTalent 的核心安全机制，默认启用。启用后，Agent 的所有文件和命令操作都受到严格约束。

#### 沙盒层级

TerminalTalent 提供了从轻量到严格的逐级安全防护：

| 层级 | 配置 | 说明 |
| ---- | ---- | ---- |
| Java 层最小自保护 | 默认生效 | 禁止 kill 宿主进程、禁止 `exit`、禁止 `rm -rf /`。仅限相对路径或逻辑路径访问。 |
| 用户主目录控制 | `sandboxAllowUserHome` | 控制是否允许 `~` 路径访问（默认允许）。关闭后 Agent 无法访问用户主目录。 |
| OS 内核级强制隔离 | `sandboxSystemRestrict` | 启用后通过 Seatbelt（macOS）/ bwrap（Linux）实现内核级沙盒。关闭后仅保留 Java 层保护，可减少对构建工具的误伤（默认关闭）。 |
| 文件系统策略 | `SandboxRuntimeConfig` | 支持配置读写白名单、读写拒绝规则，实现细粒度的目录访问控制。 |

#### 沙盒关键行为

* **路径约束**：沙盒模式下只能使用相对路径（如 `src/app.java`）或逻辑路径（如 `@skills/tool.sh`），严禁使用绝对路径。
* **符号链接防护**：会解析真实路径，防止通过符号链接越界。
* **强制拒绝清单**：即使在开放模式下，也禁止写入 `.gitconfig`、`.bashrc`、`.mcp.json` 等敏感配置文件及 `.git/hooks`、`.vscode`、`.idea` 等敏感目录。
* **自动忽略目录**：`ls`、`grep`、`glob` 等工具会自动忽略 `.git`、`node_modules`、`target`、`build`、`.idea` 等干扰目录。

```java
// 基础沙盒配置
terminalTalent.setSandboxEnabled(true);
terminalTalent.setSandboxAllowUserHome(false); // 禁止 ~ 路径

// 高级沙盒配置（OS 内核级隔离 + 文件系统策略）
terminalTalent.setSandboxSystemRestrict(true);
terminalTalent.setSandboxConfig(SandboxRuntimeConfig.builder()
        .filesystem(FilesystemConfig.builder()
                .allowWrite(Arrays.asList("./src", "./config"))
                .denyRead(Arrays.asList("./secrets"))
                .build())
        .build());
```


### 6、TerminalTalent 环境自适应

TerminalTalent 在初始化时会自动探测运行环境并适配：

* **Shell 类型**：自动识别 Unix Shell（bash/sh）、Windows CMD、Windows PowerShell，使用对应的命令执行方式和环境变量语法（`$VAR` / `%VAR%` / `$env:VAR`）。
* **运行时探测**：自动探测系统中的 Python（python3/python）和 Node.js（node/nodejs）命令，并作为 `$PYTHON` 和 `$NODE` 环境变量注入到 bash 执行环境中。
* **跨平台路径处理**：自动处理 Windows 和 Unix 的路径分隔符差异。