vscode-extension-guide

VS Code 拡張機能ガイド

VS Code 拡張機能を作成、開発、公開します。

管理 UI を備える拡張機能では、別の入口が明示的に選択されていない限り、専用のアクティビティバーアイコンとサイドバーをデフォルトで使用してください。Marketplace の icon だけではナビゲーションは作成されません。以下の TreeView リファレンスを使用してください。

ユーザー向け拡張機能では、プライマリサイドバーまたは管理 UI に、バグ報告／機能リクエストへの明確なラベル付きの入口を設け、コマンドパレットからもアクセスできるようにしてください。README や Marketplace へのリンクだけでは不十分です。固定されたフィードバック送信先を開く前に、機密性のない最小限のメタデータをプレビューしてください。送信はユーザーに委ね、プロンプト、生ログ、シークレット、プライベートパスを自動で添付しないでください。

使用する場面

• VS Code 拡張機能、拡張機能の開発、vscode plugin
• VS Code 拡張機能をゼロから新規作成する
• 拡張機能にコマンド、キーバインド、設定を追加する
• VS Code Marketplace に公開する

クイックスタート

# Scaffold new extension (recommended)
npm install -g yo generator-code
yo code

# Or minimal manual setup
mkdir my-extension && cd my-extension
npm init -y && npm install -D typescript @types/vscode

プロジェクト構成

my-extension/
├── package.json          # Extension manifest
├── src/extension.ts      # Entry point
├── out/                  # Compiled JS (gitignore)
├── artifacts/vsix/       # Keep local VSIX archives out of the repo root
├── images/icon.png       # 128x128 PNG for Marketplace
└── .vscodeignore         # Exclude files from VSIX

ビルドとパッケージ化

npm run compile      # Build once
npm run watch        # Watch mode (F5 to launch debug)
mkdir -p artifacts/vsix
npx @vscode/vsce package --out artifacts/vsix/my-extension-1.0.0.vsix

PowerShell では、mkdir -p artifacts/vsix を New-Item -ItemType Directory -Force -Path 'artifacts\vsix' に置き換えてください。他の ビルド／パッケージ化コマンドはそのまま使用します。エージェントのホストではなく、実行環境に合わせてシェル構文を選択してください。

ローカルの .vsix アーカイブはリポジトリのルートではなく artifacts/vsix/ に保存し、リリース成果物が蓄積しないよう、定期的に古いローカルビルドを削除してください。

完了条件

• パッケージ化した VSIX が、分離されたプロファイルにインストールされて有効化される。変更されたユーザー向け連携機能は、そこで実際のワークフローを完了できる
• プライマリサイドバーのエントリとコマンドが機能し、参照されているアイコンが VSIX に含まれている
• パッケージサイズが 5MB 未満（.vscodeignore を使用）
• README のリンクとフィードバック UI が意図したサポート先に到達する。送信せずに、合成データを使って UI からフォームへの経路を検証する
• ローカルの VSIX 成果物をリポジトリのルート以外に保存し、定期的に削除する

トラブルシューティング

症状	対処
拡張機能が読み込まれない	main／engines.vscode を確認してください。提供されたコマンド／ビューは暗黙的に有効化されます（1.74 以降）。それ以外のトリガーにのみ activationEvents を追加してください
コマンドが見つからない	package.json／コード内のコマンド ID が一致しているか確認してください
ショートカットが機能しない	when 条件を削除し、競合を確認してください

Reference Map

Topic	Reference
AI Customization	references/ai-customization.md
Code Review Prompts	references/code-review-prompts.md
Code Samples	references/ai-customization.md and references/webview.md
TreeView	references/treeview.md
Webview	references/webview.md
Testing	references/testing.md
Publishing	references/publishing.md
Troubleshooting	references/troubleshooting.md
Notifications	references/notification-normalization.md

Best Practices

Extension Host 境界

• Extension Host 上で動く scanner / provider / TreeView は、同じことができるなら Node 固有の path / Buffer / 生 fs より VS Code API を優先する。Problems と実ビルドの環境差を避けやすい。
• 自分の拡張に同梱したリソースは、ユーザーのホーム配下や VS Code のインストール先を推測せず、context.extensionUri と vscode.Uri.joinPath など extension context から解決する。
• 他の installed extension に同梱されたリソースを読む必要がある場合も、resources/agents|skills|prompts|instructions|hooks|mcp の既知 root と、manifest の chatAgents / chatPromptFiles 宣言を優先して見る。built-in resource とは別の read-only resource として扱い、削除や再インストール導線を混ぜない。
• Runtime の診断ログは console.log に散らさず、Output Channel ベースの logger に集約する。ユーザーがログを開ける導線も command / notification / README のどこかに用意する。
• 大きい入力の parse や集計を Extension Host スレッドで同期実行しない。上限付きの bytes を node:worker_threads へ渡し、cancel / opt-out では await worker.terminate() と listener 解除を済ませ、世代 ID が一致する結果だけで cache / UI を更新する。
• transfer するのは専有した非 SharedArrayBuffer だけにし、transfer 後は送信側の view を使わない（同じ backing store の view はすべて detach される）。Buffer は pool を共有し得るので、offset 付き view や所有が曖昧な buffer は必要範囲だけを別 buffer へ copy して渡す。
• worker や別プロセスから受け取った結果をそのまま cache / 表示しない。許可キー検査は Reflect.ownKeys、必須キーの存在確認は Object.hasOwn で行う（Object.keys は非列挙の own property を見逃し、in や素の property 参照は継承値を通す）。
• 例外の Error.name や FileSystemError.code をそのままログ / UI へ出さない。既知 code の allowlist へ正規化し、未知は単一の汎用 code に落とす。path や token が名前に混ざるケースを防げる。
• キャッシュや共有ファイル（別拡張が書く index など）から読んだ表示用の値は、使う地点で型を確認し、長さに上限を付ける。非文字列で replace 等が例外になる。正規化関数は冪等にし（切り詰めた後に trim する）、先に再現テストを赤にしてから直す。

Manifest / Docs / Localization

• package.json の commands、views、configuration、menus を変えたら、コード上の command ID / setting key と同時に確認する。
• Marketplace 表示や設定説明をローカライズしている拡張では、package.nls.json と対象言語の package.nls.*.json を同じ変更で更新する。
• In markdownDescription, use native setting references such as `#editor.wordWrap#`, not [label](#editor.wordWrap#): the latter can leave a trailing hash in the Settings @id: filter. Guard each locale's syntax and verify the resolved target.
• 設定の並び順や説明を変えたら README の設定表、manifest consistency test、release notes の必要有無までまとめて見る。

Language Model Tools

• Extension-provided LM Tools need strong modelDescription intent phrases. Prefer Use when the user asks to ... plus natural-language verbs for create/update/delete/toggle paths, and add a manifest/doc guard so future wording changes do not silently weaken agent-mode tool selection.
• For configuration from VS Code Chat, prefer native LM Tools when no external client is required; do not call them an external MCP server. Share validated domain operations with the GUI, expose only necessary actions, and use explicit enable/disable values rather than retry-sensitive toggles.
• Keep prepareInvocation side-effect free and request confirmation for mutations or sensitive disclosure. Revalidate input, cancellation, trust and the queried revision inside the locked write after confirmation. Host approval UI/policies still apply; custom confirmation text is not a bypass. Never accept secret values through tool arguments or silently widen execution permissions.
• Page query results and omit prompt, environment and raw-output payloads by default. Make sensitive detail retrieval explicit with disclosure confirmation; describe which metadata reaches the model and treat stored strings as data, not instructions.
• Return typed outcomes from shared operations; a GUI handler that catches errors and returns nothing cannot prove a tool succeeded. Keep committed IDs/success when only presentation fails, return a sanitized warning and tell the caller to query rather than repeat the mutation. Configuration saved is not work executed.
• Never pick a tool target from a name alone: resolve by exact name plus the IDs its search/list result shows (for example source and path); several matches or only a partial name return the candidates and change nothing. Schema enum values are not enforced at runtime, so an unrecognized value must stop the call, not widen the filter. An install refuses an existing destination unless an explicit overwrite flag is passed, then verifies the file at the destination the installer reports.
• Before publishing an extension with LM Tools, inspect the packaged VSIX rather than trusting source files: confirm extension/package.json has the intended version, expected contributes.languageModelTools count, and no src/, test payloads, or sourcemaps unless intentionally shipped.

Generated Sections

• START / END marker で囲む generated section は単一の SSOT として扱う。
• 重複した marker pair を見つけたら、両方を残して追記せず、内容を統合して marker pair を1つに戻す。

命名の一貫性

公開前にパッケージ名・設定キー・コマンド名を統一：

項目	例
パッケージ名	copilot-scheduler
設定キー	copilotScheduler.enabled
コマンドID	copilotScheduler.createTask
ビューID	copilotSchedulerTasks

通知の一元管理

通知は共通helperへ集約し、設定値をruntimeで既知enumへ正規化する。重複抑止、ログとの分離、action、security、起動時の繰り返し失敗の一度きり通知の設計は Notification Normalization を参照する。