跳至主要內容

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，作為自行選用的途徑。

使用範例
使用範例 的直接連結

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

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

建構函式參數
建構函式參數 的直接連結

options:

SkillSearchProcessorOptions
Skill 搜尋處理器的設定選項
SkillSearchProcessorOptions

workspace:

Workspace
包含 Skill 的 Workspace 實例。Skill 透過 workspace.skills 存取。

search?:

{ topK?: number; minScore?: number }
搜尋行為的設定。

search.topK?:

number
搜尋結果最多傳回的 Skill 數目。

search.minScore?:

number
搜尋結果納入 Skill 所需的最低相關性分數。

ttl?:

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

傳回值
傳回值 的直接連結

id:

string
設為 'skill-search' 的處理器識別碼

name:

string
設為 'Skill Search Processor' 的處理器顯示名稱

providesSkillDiscovery:

'on-demand'
向 Agent 表示此處理器負責探索 Skill 及載入指示。

processInputStep:

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

延伸使用範例
延伸使用範例 的直接連結

src/mastra/agents/skill-agent.ts
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
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 比較 的直接連結

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