Skip to Content
デベロッパーガイドツールファイルシステム

Qwen Code のファイルシステムツール

Qwen Code は、ローカルファイルシステムと対話するための包括的なツール群を提供します。これらのツールにより、モデルはファイルおよびディレクトリから読み取り、書き込み、一覧表示、検索、および変更を行うことができます。すべての操作はユーザーの制御下で実行され、特に機密性の高い操作については通常、事前の確認が求められます。

[!note]
すべてのファイルシステムツールは、セキュリティ上の理由から rootDirectory（通常は CLI を起動した現在の作業ディレクトリ）内でのみ動作します。これらのツールに指定するパスは、原則として絶対パスであるか、この rootDirectory を基準として解決される相対パスである必要があります。

1. list_directory（ListFiles）

list_directory は、指定されたディレクトリパス直下のファイルおよびサブディレクトリの名前を一覧表示します。オプションで、指定されたグロブパターンに一致するエントリを無視できます。

  • ツール名: list_directory
  • 表示名: ListFiles
  • ファイル: ls.ts
  • パラメーター:
    • path（文字列、必須）: 一覧表示対象のディレクトリの絶対パス。
    • ignore（文字列の配列、任意）: 一覧表示から除外するグロブパターンのリスト（例: ["*.log", ".git"]）。
    • respect_git_ignore（ブール値、任意）: ファイルの一覧表示時に .gitignore のパターンを尊重するかどうか。デフォルトは true。
  • 動作:
    • ファイルおよびディレクトリの名前を含むリストを返します。
    • 各エントリがディレクトリであるかどうかを示します。
    • エントリは、まずディレクトリを優先し、その後アルファベット順にソートされます。
  • 出力（llmContent）: 次のような文字列: Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png
  • 確認: なし

2. read_file（ReadFile）

read_file は、指定されたファイルの内容を読み取り、その内容を返します。このツールはテキストファイルおよび、現在のモデルが対応するモダリティを持つメディアファイル（画像、PDF、音声、動画）を処理します。テキストファイルの場合、特定の行範囲を読み取ることができます。一方、現在のモデルが対応しないモダリティのメディアファイルについては、親切なエラーメッセージとともに拒否されます。その他のバイナリファイル形式は、原則としてスキップされます。

  • ツール名: read_file
  • 表示名: ReadFile
  • ファイル: read-file.ts
  • パラメーター:
    • path（文字列、必須）: 読み取るファイルの絶対パス。
    • offset（数値、任意）: テキストファイル向け。読み取り開始位置の0ベースの行番号。limit も同時に指定する必要があります。
    • limit（数値、任意）: テキストファイル向け。読み取る最大行数。省略した場合、デフォルトの最大行数（例：2000行）または実行可能な場合はファイル全体が読み込まれます。
  • 動作:
    • テキストファイルの場合: ファイルの内容を返します。offset と limit を使用した場合は、該当する行範囲のみを返します。行数制限や1行あたりの長さ制限により内容が切り捨てられた場合は、その旨を明示します。
    • メディアファイル（画像、PDF、音声、動画）の場合: 現在のモデルがそのファイルのモダリティをサポートしている場合、ファイル内容を base64 エンコードされた inlineData オブジェクトとして返します。モデルがそのモダリティをサポートしていない場合は、代替手段（例：特定のスキルや外部ツールの利用）を示すエラーメッセージを返します。
    • その他のバイナリファイルの場合: ファイルを識別してスキップを試み、それが汎用的なバイナリファイルであることを示すメッセージを返します。
  • 出力:（llmContent）
    • テキストファイルの場合: ファイルの内容（例：[ファイル内容が切り捨てられました：全500行中1–100行を表示しています...]\n実際のファイル内容... のように、必要に応じて切り捨てメッセージが先頭に付加される場合があります）。
    • 対応済みのメディアファイルの場合: mimeType と base64 エンコードされた data を含む inlineData オブジェクト（例：{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }）。
    • 非対応のメディアファイルの場合: 現在のモデルがこのモダリティをサポートしていない旨を説明し、代替手段を提案するエラーメッセージ文字列。
    • その他のバイナリファイルの場合: バイナリファイルの内容は表示できません: /path/to/data.bin のようなメッセージ。
  • 確認: なし

3. write_file（WriteFile）

write_file は、指定されたファイルにコンテンツを書き込みます。ファイルが既に存在する場合は上書きされます。ファイルが存在しない場合は、必要に応じて親ディレクトリも含めて作成されます。

  • ツール名: write_file
  • 表示名: WriteFile
  • ファイル: write-file.ts
  • パラメーター:
    • file_path（文字列、必須）: 書き込み先ファイルの絶対パス。
    • content（文字列、必須）: ファイルに書き込むコンテンツ。
  • 動作:
    • 指定された content を file_path に書き込みます。
    • 親ディレクトリが存在しない場合は、それらを自動的に作成します。
  • 出力（llmContent）: 成功メッセージ（例：Successfully overwrote file: /path/to/your/file.txt や Successfully created and wrote to new file: /path/to/new/file.txt）。
  • 確認: あり。書き込み前に変更の差分（diff）を表示し、ユーザーの承認を要求します。

4. glob（グロブ）

glob は、特定のグロブパターン（例：src/**/*.ts、*.md）に一致するファイルを検索し、最終更新時刻でソートされた絶対パス（新しいものから順）を返します。

  • ツール名: glob
  • 表示名: Glob
  • ファイル: glob.ts
  • パラメーター:
    • pattern（文字列、必須）: マッチさせるグロブパターン（例："*.py"、"src/**/*.js"）。
    • path（文字列、任意）: 検索対象のディレクトリ。指定しない場合、現在の作業ディレクトリが使用されます。
  • 動作:
    • 指定されたディレクトリ内で、グロブパターンに一致するファイルを検索します。
    • 最終更新時刻が新しい順にソートされた絶対パスのリストを返します。
    • デフォルトで .gitignore および .qwenignore のパターンを尊重します。
    • コンテキストの過負荷を防ぐため、結果は最大100件に制限されます。
  • 出力 (llmContent): 以下のようなメッセージ: "/path/to/search/dir" 内で "*.ts" に一致する 5 個のファイルが見つかりました（最終更新時刻が新しい順）:\n---\n/path/to/file1.ts\n/path/to/subdir/file2.ts\n---\n[95 個のファイルを省略] ...
  • 確認: なし

5. grep_search（Grep）

grep_search は、指定されたディレクトリ内のファイルの内容に対して正規表現パターンを検索します。グロブパターンでファイルをフィルタリングできます。一致した行、およびそのファイルパスと行番号を返します。

  • ツール名: grep_search

  • 表示名: Grep

  • ファイル: grep.ts（ripGrep.ts をフォールバックとして使用）

  • パラメーター:

    • pattern（文字列、必須）: ファイル内容内で検索する正規表現パターン（例: "function\\s+myFunction"、"log.*Error"）。
    • path（文字列、任意）: 検索対象のファイルまたはディレクトリ。デフォルトはカレント作業ディレクトリです。
    • glob（文字列、任意）: ファイルをフィルタリングするためのグロブパターン（例: "*.js"、"src/**/*.{ts,tsx}"）。
    • limit（数値、任意）: 出力を先頭から N 行の一致結果に制限します。省略可能で、未指定時はすべての一致結果を表示します。

  • 動作:

    • 利用可能な場合は高速検索のために ripgrep を使用し、そうでない場合は JavaScript ベースの検索実装にフォールバックします。
    • 一致した行、およびそのファイルパスと行番号を返します。
    • デフォルトで大文字小文字を区別しません。
    • .gitignore および .qwenignore のパターンを尊重します。
    • コンテキストの過剰な増加を防ぐため、出力を制限します。

  • 出力 (llmContent): 一致結果を整形した文字列（例）:

    パターン "myFunction" に対する一致が 3 件、パス "." 内で見つかりました（フィルター: "*.ts"）:
---
src/utils.ts:15:export function myFunction() {
src/utils.ts:22:  myFunction.call();
src/index.ts:5:import { myFunction } from './utils';
---

[0 行が省略されました] ...

  • 確認: なし

grep_search の使用例

デフォルトの結果数制限でパターンを検索：

grep_search(pattern="function\\s+myFunction", path="src")

カスタムの結果数制限でパターンを検索：

grep_search(pattern="function", path="src", limit=50)

ファイルフィルタリングとカスタムの結果数制限を指定してパターンを検索：

grep_search(pattern="function", glob="*.js", limit=10)

6. edit（編集）

edit はファイル内のテキストを置換します。デフォルトでは、old_string が一意な単一の場所と一致することを要求します。意図的にすべての出現箇所を変更したい場合は、replace_all を true に設定してください。このツールは、正確かつターゲットを絞った変更を目的として設計されており、正しい場所を確実に変更するために、old_string の周囲に十分なコンテキストを含める必要があります。

  • ツール名: edit

  • 表示名: 編集

  • ファイル: edit.ts

  • パラメーター:

    • file_path（文字列、必須）: 変更対象のファイルへの絶対パス。

    • old_string（文字列、必須）: 置換する正確なリテラル文字列。

      重要: この文字列は、変更対象となる単一のインスタンスを一意に特定する必要があります。対象テキストの周囲の十分なコンテキスト（空白文字やインデントを含む）を正確に含める必要があります。old_string が空の場合、ツールは file_path に new_string を内容とする新規ファイルを作成しようとします。

    • new_string（文字列、必須）: old_string を置換する正確なリテラル文字列。

    • replace_all（ブール値、任意）: old_string のすべての出現箇所を置換します。デフォルトは false です。

  • 動作:

    • old_string が空で file_path が存在しない場合、new_string を内容とする新規ファイルが作成されます。
    • old_string が指定されている場合、file_path のファイルを読み込み、replace_all が true でない限り、正確に1つの出現箇所を検出しようとします。
    • マッチが一意である（または replace_all が true の場合）、テキストが new_string で置換されます。
    • 信頼性向上（マルチステージ編集補正）: 特にモデルが提供した old_string が完全に正確でない可能性がある場合など、編集操作の成功率を大幅に向上させるため、このツールにはマルチステージの編集補正機構が組み込まれています。
      • 初期の old_string が見つからない、あるいは複数の場所とマッチする場合、ツールは Qwen モデルを活用して、反復的に old_string（および必要に応じて new_string）を精緻化できます。
      • この自己補正プロセスにより、モデルが意図した一意のセグメントを特定しやすくなり、初期のコンテキストがやや不完全であっても、edit 操作の堅牢性が高まります。

  • 失敗条件: 補正機構を備えていても、以下のいずれかの条件が満たされた場合、ツールは失敗します。

    • file_path が絶対パスでない、またはルートディレクトリの外にある。
    • old_string が空でないにもかかわらず、file_path が存在しない。
    • old_string が空であるにもかかわらず、file_path がすでに存在する。
    • 補正を試みた後でも、ファイル内に old_string が見つからない。
    • old_string が複数箇所で見つかり、replace_all が false であり、かつ自己補正機構によって一意かつ明確なマッチに解決できない。

  • 出力（llmContent）:

    • 成功時: Successfully modified file: /path/to/file.txt (1 replacements). または Created new file: /path/to/new_file.txt with provided content.（成功したファイルの編集: /path/to/file.txt（1 箇所置換）。または、新規ファイル /path/to/new_file.txt を指定された内容で作成しました。）
    • 失敗時: 失敗理由を説明するエラーメッセージ（例: Failed to edit, 0 occurrences found...（編集に失敗しました。出現箇所が 0 箇所見つかりました…）、Failed to edit because the text matches multiple locations...（編集に失敗しました。テキストが複数の場所と一致します…）など）。

  • 確認: はい。提案された変更の差分（diff）を表示し、ファイルへの書き込み前にユーザーの承認を要求します。

これらのファイルシステムツールは、Qwen Code がローカルプロジェクトのコンテキストを理解・操作するための基盤を提供します。

Last updated on
はじめに複数ファイルの読み取り