vscode-extension-builder

VS Code 拡張機能ビルダー

適切なアーキテクチャ、ベストプラクティス、充実したツールサポートを備えた、プロフェッショナルな VS Code 拡張機能を構築します。

クイックスタート

すぐに拡張機能を作成する場合：

1. 初期化：npx --package yo --package generator-code -- yo code を実行します
2. 種類を選択：New Extension (TypeScript) を選択します
3. 詳細を入力：名前、識別子、説明を入力します
4. 開発：VS Code で開き、F5 キーを押してデバッグします
5. テスト：Extension Development Host でコマンドを実行します
6. パッケージ化：準備ができたら vsce package を実行します

詳細については、以下のワークフローに従ってください。

拡張機能の種類

ニーズに合った種類を選択してください：

• コマンド拡張機能：コマンドパレットにコマンドを追加します（最もシンプルで、最も一般的）
• 言語サポート：構文ハイライト、IntelliSense、フォーマット
• Webview 拡張機能：HTML/CSS/JS を使ったカスタム UI パネル
• ツリービュー：階層データを表示するカスタムサイドバービュー
• デバッガー：言語のデバッグサポートを追加します
• テーマ：カラーテーマ、ファイルアイコンテーマ
• スニペットプロバイダー：言語用のコードスニペット

基本的なワークフロー

1. 要件を収集する

ユーザーに次の点を確認します：

• 目的：拡張機能に何をさせたいですか？
• 種類：どの種類の拡張機能ですか？（コマンド、言語、Webview など）
• 機能：必要な具体的な機能
• UI：コマンド、ビュー、パネル、ステータスバー項目のどれですか？
• 有効化：いつ有効化する必要がありますか？

2. 拡張機能の種類とアーキテクチャを選択する

要件に基づいて、適切なパターンを選択します：

シンプルなコマンド拡張機能（最も一般的）：

• 単一の役割
• コマンドパレットとの連携
• すばやく構築できます

言語拡張機能：

• 構文ハイライト（TextMate 文法）
• IntelliSense 用の言語サーバー
• 複雑ですが高機能です

Webview 拡張機能：

• カスタム UI が必要
• 豊富なインタラクション
• より複雑な状態管理

詳細な構成については、extension-anatomy.md を参照してください。

3. プロジェクトを初期化する

オプション A：Yeoman Generator を使う（推奨）

npx --package yo --package generator-code -- yo code

次の項目を入力します：

• 種類：New Extension (TypeScript)
• 名前：ユーザーにわかりやすい名前
• 識別子：小文字とハイフンを使用
• 説明：目的を明確に記述
• Git：はい
• バンドラー：esbuild（推奨）または webpack
• パッケージマネージャー：npm

オプション B：テンプレートを使う

特定のパターンには、assets/templates/ からコピーします：

• command-extension/ - コマンドベースの拡張機能
• language-support/ - 言語拡張機能のスターター
• webview-extension/ - Webview ベースの拡張機能

4. 中核となる機能を実装する

コマンド拡張機能の場合：

1. package.json でコマンドを定義します：

{
  "contributes": {
    "commands": [{
      "command": "extension.commandId",
      "title": "Command Title"
    }]
  }
}

2. extension.ts でコマンドを登録します：

export function activate(context: vscode.ExtensionContext) {
  let disposable = vscode.commands.registerCommand('extension.commandId', () => {
    vscode.window.showInformationMessage('Hello from Extension!');
  });
  context.subscriptions.push(disposable);
}

言語拡張機能の場合： 言語機能の API については、common-apis.md を参照してください。

Webview 拡張機能の場合： Webview の作成パターンについては、common-apis.md を参照してください。

5. 有効化と拡張機能の提供項目を設定する

有効化イベントは、拡張機能が読み込まれるタイミングを決定します：

• onCommand：コマンドが実行されたとき
• onLanguage：ファイルの種類に応じたファイルが開かれたとき
• onView：ツリービューが表示されたとき
• *：起動時（可能であれば避けてください）

詳細については、activation-events.md を参照してください。

拡張機能の提供項目では、package.json で拡張機能の機能を宣言します：

• commands：コマンドパレットの項目
• menus：コンテキストメニュー項目
• keybindings：キーボードショートカット
• languages：言語サポート
• views：ツリービュー
• configuration：設定

6. テストとデバッグ

ローカルテスト：

1. VS Code で F5 キーを押し、Extension Development Host を起動します
2. コマンドと機能をテストします
3. Debug Console でログを確認します
4. ブレークポイントを設定してデバッグします

自動テスト：

• 単体テスト：ビジネスロジックをテストします
• 統合テスト：VS Code API との連携をテストします
• テストには @vscode/test-electron を使います

よくある問題：

• コマンドが表示されない：contributes.commands と有効化イベントを確認してください
• 拡張機能が有効化されない：package.json の有効化イベントを確認してください
• API エラー：VS Code API のバージョン互換性を確認してください

7. パッケージ化と配布

公開の準備：

1. 機能と使い方を記載して README.md を更新します
2. 拡張機能のアイコンを追加します（128x128 PNG）
3. package.json にリポジトリの URL を設定します
4. LICENSE ファイルを追加します
5. 十分にテストします

拡張機能をパッケージ化する：

npm install -g @vscode/vsce
vsce package

配布用の .vsix ファイルを作成します。

マーケットプレイスに公開する：

vsce publish

Azure DevOps の個人用アクセストークンが必要です。

よく使われるパターン

パターン 1：シンプルなコマンド

情報を表示する簡単なコマンドです：

vscode.commands.registerCommand('extension.showInfo', () => {
  vscode.window.showInformationMessage('Information message');
});

パターン 2：ユーザー入力を伴うコマンド

実行前に入力を受け取ります：

vscode.commands.registerCommand('extension.greet', async () => {
  const name = await vscode.window.showInputBox({
    prompt: 'Enter your name'
  });
  if (name) {
    vscode.window.showInformationMessage(`Hello, ${name}!`);
  }
});

パターン 3：ファイル操作コマンド

アクティブなエディターを操作します：

vscode.commands.registerCommand('extension.processFile', () => {
  const editor = vscode.window.activeTextEditor;
  if (!editor) {
    vscode.window.showErrorMessage('No active editor');
    return;
  }
  
  const document = editor.document;
  const text = document.getText();
  // Process text...
});

パターン 4：ステータスバー項目

常に表示されるステータスを示します：

const statusBarItem = vscode.window.createStatusBarItem(
  vscode.StatusBarAlignment.Right,
  100
);
statusBarItem.text = "$(check) Ready";
statusBarItem.show();
context.subscriptions.push(statusBarItem);

リファレンスの参照

必要に応じて、以下のリファレンスを読み込みます：

• extension-anatomy.md：次の詳細が必要な場合：

  • 拡張機能の構造とファイル構成
  • package.json マニフェストのフィールド
  • エントリーポイントとライフサイクルフック
  • 拡張機能のコンテキストと破棄可能オブジェクト

• common-apis.md：次を実装する場合：

  • ウィンドウやエディターの操作
  • ワークスペースやファイルシステムへのアクセス
  • 言語機能（IntelliSense、診断）
  • Webview の作成とメッセージング
  • ツリービューとカスタム UI

• activation-events.md：次を設定する場合：

  • 拡張機能を読み込むタイミング
  • パフォーマンスの最適化
  • 遅延読み込みの戦略

• best-practices.md：次を検討する場合：

  • UX ガイドラインとデザインパターン
  • パフォーマンスの最適化
  • セキュリティに関する考慮事項
  • テスト戦略
  • 公開に関するガイドライン

重要な原則

パフォーマンス

• 遅延読み込み：* ではなく、具体的なアクティベーションイベントを使用します
• 非同期操作：I/O には async/await を使用します
• リソースの破棄：サブスクリプションをクリーンアップします
• 起動処理の最小化：負荷の高い処理は後回しにします

ユーザーエクスペリエンス

• 明確なコマンド：説明的なタイトルとカテゴリを設定します
• フィードバック：時間のかかる操作では進行状況を表示します
• エラー処理：わかりやすいエラーメッセージを表示します
• 一貫性のある UI：VS Code の規約に従います

コード品質

• TypeScript：型安全性のために strict モードを使用します
• エラー処理：すべての操作で try-catch を使用します
• ロギング：デバッグには console.log を使用します
• テスト：重要な機能のテストを作成します

トラブルシューティング

拡張機能が表示されない

• package.json の構文を確認します（有効な JSON であること）
• main フィールドがコンパイル済み出力を指していることを確認します
• アクティベーションイベントが正しいことを確認します
• ウィンドウを再読み込みします：Developer: Reload Window

コマンドが動作しない

• コマンド ID が package.json とコード内で一致していることを確認します
• アクティベーションイベントにコマンドが含まれていることを確認します
• デバッグコンソールでエラーを確認します
• activate() でコマンドが登録されていることを確認します

ビルドエラー

• npm install を実行して依存関係をインストールします
• TypeScript の設定を確認します
• VS Code API のバージョンとの互換性を確認します
• 必要に応じて @types/vscode を更新します

ユースケース別の例

コードをフォーマットするコマンドを追加する

1. 種類：コマンド拡張機能
2. アクティベーション：onCommand
3. 実装：エディターのテキストを取得し、フォーマットして置き換えます
4. UI：コマンドパレットの項目

シンタックスハイライトを追加する

1. 種類：言語拡張機能
2. アクティベーション：onLanguage:mylang
3. 実装：JSON 形式の TextMate 文法
4. UI：ファイルを開くと自動的に適用されます

カスタムサイドバービューを追加する

1. 種類：ツリービュー拡張機能
2. アクティベーション：onView:myView
3. 実装：TreeDataProvider インターフェース
4. UI：アクティビティバーのアイコンとサイドバーパネル

クイックピックメニューを追加する

1. 種類：UI を備えたコマンド拡張機能
2. アクティベーション：onCommand
3. 実装：項目を指定した showQuickPick
4. UI：検索可能なドロップダウンメニュー

このスキルのリソース

• references/：詳細なドキュメント（必要に応じて読み込みます）
• assets/templates/：よく使われるパターンのひな形
• 公式ドキュメント：https://code.visualstudio.com/api

関連スキル

拡張機能のコードの品質とアーキテクチャをレビューする場合：

• detect-code-smells：拡張機能のコード品質を確認します
• security-pattern-check：拡張機能のセキュリティをレビューします
• suggest-performance-fix：拡張機能のパフォーマンスを最適化します

注意事項

このスキルでは、初期の構想から公開済みの拡張機能まで、VS Code 拡張機能開発のワークフロー全体を提供します。段階的開示を活用し、簡単なケースではクイックスタートから始め、複雑な要件についてはリファレンスを確認してください。assets/ 内のテンプレートは、一般的なパターンにすぐ使える出発点としてコピーして利用できます。