zen-code-docs/website/content/ja/core/tools-api.md

Qwen Code Core: Tools API

Qwen Code のコア (packages/core) には、ツールを定義・登録・実行するための堅牢なシステムが備わっています。これらのツールはモデルの機能を拡張し、ローカル環境との連携、Web コンテンツの取得、単純なテキスト生成を超えたさまざまなアクションの実行を可能にします。

コアコンセプト

• Tool (tools.ts): すべてのツールの契約を定義するインターフェースとベースクラス（BaseTool）。各ツールには以下が必要です：

  • name: モデルへの API 呼び出しで使用される一意の内部名。
  • displayName: ユーザーに表示される分かりやすい名前。
  • description: モデルに提供される、ツールが何を行うかを明確に説明するテキスト。
  • parameterSchema: ツールが受け取るパラメータを定義する JSON スキーマ。モデルがツールを正しく呼び出すために重要。
  • validateToolParams(): 受信したパラメータを検証するメソッド。
  • getDescription(): 実行前に、特定のパラメータでツールが何を行うかを人間が読める形式で返すメソッド。
  • shouldConfirmExecute(): 実行前にユーザー確認が必要かどうかを判断するメソッド（例：破壊的な操作など）。
  • execute(): ツールのアクションを実行し、ToolResult を返すコアメソッド。

• ToolResult (tools.ts): ツールの実行結果の構造を定義するインターフェース：

  • llmContent: LLM に送り返される履歴に含める事実情報。単純な文字列か、リッチなコンテンツ用の PartListUnion（Part オブジェクトと文字列の配列）。
  • returnDisplay: CLI に表示するためのユーザー向け文字列（多くの場合 Markdown）または特別なオブジェクト（例：FileDiff）。

• リッチなコンテンツの返却: ツールは単純なテキストに限らず、llmContent に PartListUnion を返すことができます。これは Part オブジェクト（画像、音声など）と string の混合を含む配列で、1回のツール実行で複数のリッチコンテンツを返すことが可能です。

• Tool Registry (tool-registry.ts): 以下の責務を持つクラス（ToolRegistry）：

  • ツールの登録: 利用可能なすべての組み込みツール（例：ReadFileTool、ShellTool）を保持。
  • ツールの発見: 動的にツールを発見することも可能：
    • コマンドベースの発見: 設定で toolDiscoveryCommand が指定されている場合、そのコマンドを実行し、カスタムツールを記述した JSON を出力することが期待される。出力されたツールは DiscoveredTool インスタンスとして登録される。
    • MCP ベースの発見: mcpServerCommand が設定されている場合、レジストリは Model Context Protocol (MCP) サーバーに接続してツールを一覧取得・登録（DiscoveredMCPTool）できる。
  • スキーマの提供: 登録されたすべてのツールの FunctionDeclaration スキーマをモデルに公開し、利用可能なツールとその使用方法を認識させる。
  • ツールの取得: コアが実行のために名前で特定のツールを取得できるようにする。

組み込みツール

コアには、packages/core/src/tools/ に通常配置されている一連の事前定義ツールが含まれています。これには以下が含まれます：

• ファイルシステムツール:
  • LSTool (ls.ts): ディレクトリの内容を一覧表示します。
  • ReadFileTool (read-file.ts): 単一ファイルの内容を読み込みます。absolute_path パラメータを受け取り、これは絶対パスである必要があります。
  • WriteFileTool (write-file.ts): ファイルに内容を書き込みます。
  • GrepTool (grep.ts): ファイル内のパターンを検索します。
  • GlobTool (glob.ts): glob パターンに一致するファイルを検索します。
  • EditTool (edit.ts): ファイルに対してその場での変更を実行します（多くの場合、確認が必要です）。
  • ReadManyFilesTool (read-many-files.ts): 複数のファイルまたは glob パターンから内容を読み込んで連結します（CLI の @ コマンドで使用されます）。
• 実行ツール:
  • ShellTool (shell.ts): 任意の shell コマンドを実行します（慎重なサンドボックス化とユーザー確認が必要です）。
• Web ツール:
  • WebFetchTool (web-fetch.ts): URL から内容を取得します。
  • WebSearchTool (web-search.ts): Web 検索を実行します。
• メモリツール:
  • MemoryTool (memoryTool.ts): AI のメモリとやり取りします。

これらの各ツールは BaseTool を拡張し、特定の機能に必要なメソッドを実装しています。

ツール実行フロー

1. モデルリクエスト: モデルは、ユーザーのプロンプトと提供されたツールスキーマに基づいて、ツールを使用することを決定し、レスポンス内で FunctionCall パートを返却します。このパートには、ツール名と引数が指定されています。
2. Core がリクエストを受信: Core はこの FunctionCall をパースします。
3. ツール検索: ToolRegistry 内で要求されたツールを検索します。
4. パラメータ検証: ツールの validateToolParams() メソッドが呼び出されます。
5. 確認（必要な場合）:
   • ツールの shouldConfirmExecute() メソッドが呼び出されます。
   • このメソッドが確認用の詳細を返す場合、Core は CLI にこの情報を伝え、ユーザーにプロンプトを表示します。
   • ユーザーの判断（例：実行、キャンセル）が Core に送り返されます。
6. 実行: 検証および確認が完了した場合（または確認が不要な場合）、Core はツールの execute() メソッドを、指定された引数と AbortSignal（キャンセル用）とともに呼び出します。
7. 結果処理: execute() から返された ToolResult が Core に受信されます。
8. モデルへのレスポンス: ToolResult の llmContent が FunctionResponse としてパッケージ化され、モデルに送り返され、モデルがユーザー向けのレスポンス生成を続行できるようにします。
9. ユーザーへの表示: ToolResult の returnDisplay が CLI に送られ、ユーザーにツールが何を行ったかが表示されます。

カスタムツールによる拡張

エンドユーザー向けの一般的なワークフローとして、ユーザーによる新規ツールの直接的なプログラムによる登録については、提供されているファイルには明確に記載されていませんが、アーキテクチャでは以下の方法で拡張をサポートしています：

• コマンドベースの検出: 上級ユーザーまたはプロジェクト管理者は、settings.json に toolDiscoveryCommand を定義できます。このコマンドは、core によって実行され、FunctionDeclaration オブジェクトの JSON 配列を出力する必要があります。core はこれらを DiscoveredTool インスタンスとして利用可能にします。対応する toolCallCommand が、これらのカスタムツールを実際に実行する役割を担います。
• MCP サーバー: より複雑なシナリオでは、1つ以上の MCP サーバーをセットアップし、settings.json の mcpServers 設定で構成できます。core はこれらのサーバーが公開するツールを検出して利用することが可能です。前述の通り、複数の MCP サーバーがある場合、ツール名には設定に記載されたサーバー名がプレフィックスとして付加されます（例：serverAlias__actualToolName）。

このツールシステムにより、モデルの機能を柔軟かつ強力に拡張でき、Qwen Code をさまざまなタスクに対応可能な多機能なアシスタントにしています。