Qwen Code のアーキテクチャ概要

このドキュメントでは、Qwen Code のアーキテクチャについて概要を説明します。

コアコンポーネント

Qwen Code は主に 2 つの主要パッケージで構成されており、さらにコマンドライン入力の処理中にシステムが利用可能なツール群も含まれます。

1. CLI パッケージ (`packages/cli`)

目的: Qwen Code のユーザー向け部分を含み、初期のユーザー入力の処理、最終出力の表示、および全体的なユーザーエクスペリエンスの管理を行います。

主な機能:

入力処理: 直接テキスト入力、スラッシュコマンド（例: /help、/clear、/model）、アットマークコマンド（例: @file でファイル内容を挿入）、感嘆符コマンド（例: !command でシェルコマンドを実行）など、さまざまな方法によるユーザー入力の処理を行います。
履歴管理: 会話履歴を保持し、セッションの再開などの機能を提供します。
表示レンダリング: ターミナル上で応答を構文強調表示および適切なフォーマットでユーザーに表示します。
テーマおよび UI のカスタマイズ: 個別の体験を実現するため、カスタマイズ可能なテーマおよび UI 要素をサポートします。
設定の管理: JSON 設定ファイル、環境変数、コマンドライン引数を通じて、さまざまな設定オプションを管理します。

2. コアパッケージ (`packages/core`)

目的: このパッケージは Qwen Code のバックエンドとして機能します。packages/cli から送信されたリクエストを受信し、設定済みのモデル API とのやり取りを調整するとともに、利用可能なツールの実行を管理します。

主な機能:

API クライアント: Qwen モデル API と通信し、プロンプトを送信して応答を受信します。
プロンプト構築: 会話履歴および利用可能なツール定義を組み込んだ、適切なプロンプトをモデル向けに構築します。
ツールの登録および実行: 利用可能なツールの登録を管理し、モデルからの要求に基づいてそれらを実行します。
状態管理: 会話およびセッションの状態情報を維持します。
サーバー側の設定: サーバー側の設定および各種オプションを処理します。

3. ツール (`packages/core/src/tools/`)

目的: これらは Qwen モデルの機能を拡張する個別のモジュールであり、ローカル環境（例：ファイルシステム、シェルコマンド、Web フェッチ）との対話を可能にします。

連携方法: packages/core が、Qwen モデルからのリクエストに基づいてこれらのツールを呼び出します。

代表的なツールには以下が含まれます:

ファイル操作: ファイルの読み込み、書き込み、編集
シェルコマンド: 危険な操作を含む可能性のあるシステムコマンドを、ユーザーの承認を得て実行
検索ツール: プロジェクト内のファイルを検索したり、コンテンツ内を検索したりする
Web ツール: Web 上のコンテンツを取得する
MCP 統合: 拡張機能を提供する Model Context Protocol サーバーに接続

インタラクションのフロー

Qwen Code との典型的なインタラクションは、以下のフローに従います。

ユーザー入力: ユーザーが端末にプロンプトまたはコマンドを入力します。この処理は packages/cli によって管理されます。
コアへのリクエスト: packages/cli がユーザーの入力を packages/core へ送信します。
リクエストの処理: コアパッケージは以下の処理を行います。
- 設定されたモデル API に適したプロンプトを構築します（会話履歴や利用可能なツール定義を含む場合があります）。
- 構築したプロンプトをモデル API へ送信します。
モデル API の応答: モデル API がプロンプトを処理し、応答を返します。この応答は、直接の回答である場合もあれば、利用可能なツールのいずれかを実行するよう依頼する場合もあります。
ツールの実行（該当する場合）:
- モデル API がツールの実行を依頼した場合、コアパッケージはそのツールを実行する準備をします。
- 要求されたツールがファイルシステムを変更したりシェルコマンドを実行したりする場合、まずユーザーに対してツールの詳細および引数が提示され、ユーザーによる実行承認が必要になります。
- ファイルの読み取りなど、読み取り専用の操作については、明示的なユーザー確認なしで実行される場合があります。
- 実行が承認された場合、あるいは承認が不要な場合は、コアパッケージが関連するツール内で対応するアクションを実行し、その結果をコアパッケージからモデル API へ送信します。
- モデル API がツールの結果を処理し、最終的な応答を生成します。
CLI への応答: コアパッケージが最終応答を CLI パッケージへ送信します。
ユーザーへの表示: CLI パッケージが応答を整形し、端末上でユーザーに表示します。

設定オプション

Qwen Code では、その動作を設定する方法が複数用意されています。

設定の優先順位（上から順に高優先）

コマンドライン引数
環境変数
プロジェクト設定ファイル（.qwen/settings.json）
ユーザー設定ファイル（~/.qwen/settings.json）
システム設定ファイル
デフォルト値

主な設定カテゴリ

一般設定: Vim モード、推奨エディター、自動更新の設定
UI 設定: テーマのカスタマイズ、バナーの表示／非表示、フッターの表示
モデル設定: モデルの選択、セッション内のターン数制限、圧縮設定
コンテキスト設定: コンテキストファイル名、含めるディレクトリ、ファイルフィルタリング
ツール設定: 承認モード、サンドボックス化、ツールの制限
プライバシー設定: 使用状況統計情報の収集
高度な設定: デバッグオプション、カスタムバグ報告コマンド

主要な設計原則

モジュール性: CLI（フロントエンド）とコア（バックエンド）を分離することで、それぞれの独立した開発が可能になり、将来的には同一のバックエンドに対して異なるフロントエンドを実装するなどの拡張も見込まれます。
拡張性: ツールシステムは拡張可能な設計となっており、カスタムツールの追加や MCP サーバーとの連携によって新たな機能を容易に追加できます。
ユーザーエクスペリエンス: CLI は、構文ハイライト、カスタマイズ可能なテーマ、直感的なコマンド構造といった機能を備えた、豊かでインタラクティブなターミナル体験を提供することに重点を置いています。
セキュリティ: 危険な操作を実行する前に承認を得る仕組みや、ユーザーのシステムを保護するためのサンドボックス機能を実装しています。
柔軟性: 複数の設定方法をサポートし、さまざまなワークフローおよび実行環境への対応が可能です。