vim-ai レビュー: Vim のバッファから OpenAI 互換 API を呼ぶプラグインの設計と境界

:AIEdit /grammar が示す「選択範囲だけを送る」設計

このプラグインが解く問題は、エディタの外に出ずにテキスト変換とコード生成を回すことである。README は「You can generate code, edit text, or have an interactive conversation with GPT models」と述べ、さらに「the plugin does not send any of your code behind the scenes」と明記する。つまりバッファ全体を勝手に送るのではなく、ビジュアル選択やレンジで指定した範囲だけが API に渡る。この一点が、IDE 拡張やチャット UI を別ウィンドウで開く運用との差になる。対象読者は Vim を離れたくない人、そして送信範囲を自分で制御したい人だ。逆に、リポジトリ全体を文脈として渡したい用途は、この設計では成立しない。範囲指定が送信単位だからである。

コマンド体系とレンジ指定の実際

基本コマンドは 5 つで、:AI が補完、:AIEdit が選択テキストのその場編集、:AIChat が対話、:AIStopChat が応答生成の停止、:AIImage が画像生成である。ユーティリティとして :AIRedo、:AIUtilRolesOpen、:AIUtilDebugOn、:AIUtilDebugOff が用意されている。README は「Press Ctrl-c anytime to cancel :AI and :AIEdit completion」と述べ、生成の中断手段を明示している。レンジとの組み合わせも記載があり、「:%AIE fix grammar」でバッファ全体を対象にできる。ショートカットは :AIE、:AIC、:AIS、:AIR、:AII が示されている。ここで注意したいのは、:AIChat だけは補完系と性質が異なり、ストリーミング表示と停止コマンドを持つ点だ。補完とチャットで失敗時の挙動が揃わないのは、使う側が意識しておくべき非対称性である。

セットアップ: トークンファイルと +python3 の前提

前提は 2 つ。README は「Vim or Neovim compiled with python3 support」と「API key」を挙げる。キーの渡し方は 3 通りが示されている。ファイルに書く場合は echo "YOUR_OPENAI_API_KEY" > ~/.config/openai.token、環境変数なら export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"、組織 ID を併記する場合はカンマ区切りで echo "YOUR_OPENAI_API_KEY,YOUR_OPENAI_ORG_ID" > ~/.config/openai.token とする。既定の参照先は ~/.config/openai.token で、変更したいときは .vimrc に let g:vim_ai_token_file_path = '~/.config/openai.token' を書く。導入は vim-plug なら Plug 'madox2/vim-ai' の 1 行、手動なら Vim は ~/.vim/pack/plugins/start、Neovim は ~/.local/share/nvim/site/pack/plugins/start に git clone する。ここまでが README に載っている範囲である。なお、リポジトリにはリリースが取得できておらず、バージョンを指定したインストール手順は README に存在しない。

role はプロンプトと API オプションを同じ .ini に束ねる

roles の仕組みはこのプラグインで最も特徴的な部分だ。g:vim_ai_roles_config_file で .ini を指定し、セクション名がそのまま role 名になる。README の例では [grammar] に prompt = fix spelling and grammar と options.temperature = 0.4 を書き、[o1-mini] に options.model、options.max_completion_tokens = 25000、options.temperature = 1、options.initial_prompt を設定する。さらに [o1-mini.chat] のようにコマンド単位の上書きができ、options.stream = 0 と ui.populate_all_options = 1 をそこに置いている。呼び出しは :AIEdit /grammar、組み合わせは :AI /o1-mini /grammar helo world! の形だ。プロンプトとモデル設定を同じファイルに同居させられるので、チームで roles.ini を共有すれば指示の揺れを減らせる。ただし .ini はあくまでテキスト設定であり、role ごとに送信内容が変わるわけではない。何が送られるかは選択範囲と prompt の組み合わせで決まる。

プロバイダは本体に同梱されず、外部プラグインに分離されている

README は「Integrates with any OpenAI-compatible API」とうたい、OpenAI 以外を使う場合は OpenRouter やローカルの LiteLLM のようなプロキシを挟む方法を案内する。加えて provider plugins という拡張点があり、google provider（Gemini）、OpenAI Responses API Provider、OpenAI Provider with MCP support の 3 つが一覧に載っている。ただし README 自身が「there aren't many available yet」と書いており、本体にプロバイダ実装が同梱されているわけではない。新しいプロバイダを書く場合の参照実装として google provider が挙げられている。ここは採用判断で見落とされやすい。OpenAI 互換のエンドポイントを持たないサービスを使いたいなら、プロキシを立てるか、プロバイダプラグインを自分で書くか、どちらかの作業が発生する。README はその負担を隠していない。

コストはトークン従量、送信範囲は利用者の選択に依存する

README は「Usage of the API is not free, but the cost is reasonable and depends on how many tokens you use」と述べ、料金ページへのリンクを置く。課金対象は送受信したテキスト量であり、README の表現では「You only share and pay for what you specifically select」。つまり :%AIE でバッファ全体を対象にすれば、その分だけ送信され、その分だけ課金される。ここに固有のリスクがある。レンジ指定を誤ってバッファ全体に広げたまま実行すれば、意図しない規模の送信と課金が一度に発生する。Ctrl-c での中断は補完系について案内されているが、送信済みトークンの扱いについては README に記述がない。コスト管理はプラグイン側ではなく、レンジの指定と role の設計で行う性質のものである。

向かない場面: キー保管、python3 なしのビルド、監査用途

制約ははっきりしている。第一に、python3 サポート付きでビルドされた Vim か Neovim が必要で、:version に +python3 がなければ動かない。第二に、既定の運用は ~/.config/openai.token に平文でキーを置く。環境変数を使う選択肢はあるが、いずれにせよキーはエディタプロセスから読める場所にある。第三に、README にはリリースもバージョン番号も記載がなく、変更履歴を追う手段が本文からは見えない。監査や再現性が要求される環境で、どの時点のコードを使っているかを記録する仕組みは README からは読み取れない。第四に、リポジトリ全体を文脈として渡す用途には向かない。送信単位が選択範囲だからだ。これらは欠陥ではなく設計の帰結だが、採用可否を分ける境界になる。

比較対象としての汎用 CLI エージェントとの違い

同じ「ターミナルから LLM を使う」目的では、汎用の CLI エージェントや、エディタ側の AI 統合機能が代替になる。違いは送信の単位にある。vim-ai はバッファとレンジ、つまり編集中のテキストそのものを入力にする。:AIEdit は選択範囲をその場で書き換え、:AIChat は別バッファで対話を続ける。CLI エージェントは通常、作業ディレクトリやファイル群を対象にし、シェルコマンドの実行まで含む。つまり vim-ai はファイルシステムを操作せず、編集バッファの中だけで完結する。この差は利点にも制約にもなる。既存ファイルを横断して調査させたいなら CLI 側が適し、いま開いている関数のコメントだけを整えたいなら vim-ai のレンジ指定のほうが速い。役割分担の問題であって、どちらか一方が上位という話ではない。

ライセンスと保守の見え方

ライセンスは MIT で、改変と再配布の条件は軽い。ただし MIT であることは、API 利用規約やプロバイダ側の契約を緩めるものではない。API キーの保管と送信内容の扱いは利用者側の責任であり、ここについて法的な判断を本記事で示すことはできない。保守面では、README がプロバイダプラグインの開発を歓迎し、一覧への PR を求めている点が運用コストに直結する。本体が対応しないプロバイダを使いたい場合、その保守は外部プラグイン側に依存する。README の表現を借りれば「there aren't many available yet」という段階であり、選択肢の広さを前提に導入計画を立てるのは危うい。まず自分の使いたいモデルが OpenAI 互換 API で叩けるかを確認し、叩けないならプロキシを立てる前提で見積もるべきである。

編集部の結論

バッファ内で完結する編集とチャットを、外部エディタやブラウザを経由せずに使いたい Vim/Neovim ユーザーには向いている。逆に、python3 サポートなしでビルドされた Vim、API キーをファイルに置きたくない環境、プラグインの更新頻度を前提に運用を組み立てたいチームには向かない。導入前に確認すべきは、:version に +python3 が含まれるか、g:vim_ai_token_file_path を書き換えるか環境変数 OPENAI_API_KEY で渡すか、そして g:vim_ai_roles_config_file で指定する roles.ini の options.model をどのモデル名にするかである。README にはリリースノートもバージョン番号も記載がないため、固定バージョンを前提にした運用計画は立てられない。

公式情報源

1. Issues
2. License: MIT
3. madox2/vim-ai on GitHub
4. README