> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# SkillSearchProcessor

`SkillSearchProcessor` 是一個**輸入處理器**，支援按需要探索及載入 Skill。它不會像 `SkillsProcessor` 一樣，預先將所有 Skill 中繼資料注入系統提示，而是向 Agent 提供兩個中繼 Tool（`search_skills` 及 `load_skill`），讓它按需要尋找及載入 Skill。當 Workspace 包含大量 Skill 時，這可減少 context token 用量。

預設情況下，當你只將 `SkillSearchProcessor` 附加至具備 Skill 功能的 `Workspace` 中的 Agent，Agent 會將 Skill 視為按需要提供：

- 系統不會自動加入預設的即時載入 `SkillsProcessor`。
- 系統會公開 `search_skills` 及 `load_skill`，以供探索及載入指示。
- 重疊的 `skill` 及 `skill_search` Tool 會被隱藏。
- `skill_read` 仍然可用，讓 Agent 讀取 references、scripts 及 assets 等 Skill 支援檔案。

如你明確設定 `SkillsProcessor` 與 `SkillSearchProcessor` 並用，Agent 會保留即時載入的 `skill` 及 `skill_search` Tool，作為自行選用的途徑。

## 使用範例

```typescript
import { SkillSearchProcessor } from '@mastra/core/processors'

const skillSearch = new SkillSearchProcessor({
  workspace,
  search: {
    topK: 5,
    minScore: 0.1,
  },
})
```

## 建構函式參數

**options** (`SkillSearchProcessorOptions`): Skill 搜尋處理器的設定選項

**options.workspace** (`Workspace`): 包含 Skill 的 Workspace 實例。Skill 透過 workspace.skills 存取。

**options.search** (`{ topK?: number; minScore?: number }`): 搜尋行為的設定。

**options.search.topK** (`number`): 搜尋結果最多傳回的 Skill 數目。

**options.search.minScore** (`number`): 搜尋結果納入 Skill 所需的最低相關性分數。

**options.ttl** (`number`): 執行緒狀態的存留時間（毫秒）。閒置時間超出此時限後，系統會清除執行緒狀態。設為 0 可停用清理。

## 傳回值

**id** (`string`): 設為 'skill-search' 的處理器識別碼

**name** (`string`): 設為 'Skill Search Processor' 的處理器顯示名稱

**providesSkillDiscovery** (`'on-demand'`): 向 Agent 表示此處理器負責探索 Skill 及載入指示。

**processInputStep** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): 處理每個步驟，以注入搜尋／載入中繼 Tool，並將先前載入的任何 Skill 指示注入為系統訊息。

## 延伸使用範例

```typescript
import { Agent } from '@mastra/core/agent'
import { SkillSearchProcessor } from '@mastra/core/processors'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './project' }),
  skills: ['skills'],
  bm25: true,
})

const skillSearch = new SkillSearchProcessor({
  workspace,
  search: {
    topK: 5,
    minScore: 0.1,
  },
})

const agent = new Agent({
  id: 'skill-agent',
  name: 'skill-agent',
  instructions:
    'You are a helpful assistant. Use search_skills to find relevant skills, then load_skill to load their instructions.',
  model: 'openai/gpt-5.6-sol',
  workspace,
  inputProcessors: [skillSearch],
})
```

Agent 的運作流程如下：

1. Agent 收到用戶訊息
2. Agent 使用關鍵字（例如「api design」）呼叫 `search_skills`
3. Agent 檢視結果，並以 Skill 名稱呼叫 `load_skill`
4. Skill 指示會在下一回合顯示為系統訊息
5. Agent 遵從已載入 Skill 的指示

## Workspace 檔案 Tool

`SkillSearchProcessor` 會將 Skill 指示載入對話。它不會阻止 Workspace 檔案 Tool 讀取檔案。

如要讀取已載入 Skill 的支援檔案（例如 `references/`、`scripts/` 或 `assets/` 下的檔案），請使用 `skill_read`。

Workspace 檔案 Tool（例如 `mastra_workspace_read_file`）應留作明確的檔案檢查或編輯流程。在一般任務執行期間，`load_skill` 成功後，Agent 無需再次讀取同一個 `SKILL.md` 檔案。

## 與 SkillsProcessor 比較

|            | SkillsProcessor | SkillSearchProcessor |
| ---------- | --------------- | -------------------- |
| 擴展方式       | 預先注入所有 Skill    | 按需要探索                |
| Context 用量 | 隨 Skill 數目增加    | 固定（只計已載入的 Skill）     |
| Agent 工作流程 | Skill 一直可見      | Agent 按需要搜尋及載入       |
| 最適合        | 少量 Skill（< 10）  | 大量 Skill（10+）        |

## 相關內容

- [ToolSearchProcessor](https://mastra.zisheng.pro/zh-HK/reference/processors/tool-search-processor)
- [處理器](https://mastra.zisheng.pro/zh-HK/docs/agents/processors)
- [Workspace Skill](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)