Antigravity 拡張の設定入門｜contributes.configuration・階層と SecretStorage

公式の流れ（VS Code Extension API）

設定項目を設定 UI に載せるには、拡張マニフェストの contributes.configuration にプロパティを書きます。 ユーザーは設定エディタか settings.json で値を変更し、拡張は vscode.workspace.getConfiguration(section) で読み取ります。

定義は JSON Schema のスーパーセットとして扱われ、settings.json を直に編集するときのIntelliSenseにも使われます。 IntelliSense は Microsoft の用語で、入力補完・候補リスト・ホバー説明など、タイプしながらエディタが手助けしてくれる機能の総称だと捉えれば十分です。

詳細は Contribution Points — contributes.configuration を参照してください。

宣言の最小例（抜粋）

properties のキーが設定 ID です。getConfiguration には、ドットより前のセクション名（例では settingsLab.playground）を渡します。

{
  "contributes": {
    "configuration": [
      {
        "title": "Playground",
        "properties": {
          "settingsLab.playground.windowDemo": {
            "type": "string",
            "default": "(未設定)",
            "scope": "window",
            "description": "User または Workspace の settings.json に平文で保存されます。"
          }
        }
      }
    ]
  }
}

scope と「階層」

scope はマニフェスト上で「そのキーをどの種類の保存先に書けるか」を宣言する属性です。 未指定時のデフォルトは公式どおり window です。

一方、User → Workspace → フォルダといった上書きの重なりは、別の話です。 実行時に「どの層に値が入っているか」を見るには inspect() の globalValue / workspaceValue / workspaceFolderValue などを使います。

scope（概要）	開発者メモ
window	多くの拡張設定がここ。User / Workspace の settings.json に載りやすいイメージ。
resource	フォルダ（ワークスペースフォルダ）に紐づく。マルチルートではフォルダごとに .vscode/settings.json へ分かれうる。
machine	マシン単位。同期の扱いに注意（公式の ignoreSync 記述と併読）。
application / machine-overridable / language-overridable	用途に応じて公式表を確認。言語別は [typescript] ブロックなどと組み合わせ。

厳密な定義は Contribution Points と User and workspace settings を優先してください。

拡張から設定を読む・書く（get / inspect / update）

次のコードは、拡張の activate などから呼ぶ TypeScript（JavaScript でも可）向けの API です。 vscode パッケージの workspace.getConfiguration で、宣言した設定セクション（例では settingsLab.playground）にアクセスします。

• get — ユーザー設定・ワークスペース・既定値などがマージされたあとの「いま効いている値」だけが欲しいとき。
• inspect — その値がどの層（ユーザー全体・ワークスペース・フォルダ・既定）に入っているか調べたいとき。globalValue などが分かります。
• update — コードから値を書き込むとき。第3引数でどこに保存するか（例: ユーザー全体 = ConfigurationTarget.Global）を指定します。

// 拡張内（例: extension.ts）— TypeScript
const cfg = vscode.workspace.getConfiguration('settingsLab.playground');

// いま効いている文字列だけ欲しい
const effective = cfg.get<string>('windowDemo'); // <string> は型のヒント（TS）

// 層ごとに中身を見る（デバッグや UI 表示向き）
const layers = cfg.inspect('windowDemo');
// layers?.defaultValue / globalValue / workspaceValue / workspaceFolderValue など

// ユーザー設定へ書き込み（await 必須）
await cfg.update('windowDemo', 'from-extension', vscode.ConfigurationTarget.Global);

設定が変わったタイミングで処理したいときは vscode.workspace.onDidChangeConfiguration を使います。 自分の拡張のキーだけ反応させるなら、e.affectsConfiguration('settingsLab.playground') のようにキーの先頭（プレフィックス）で絞ると負荷が減ります。

設定 JSON と SecretStorage の使い分け

contributes.configuration 経由で保存した値は、User / Workspace 等の設定ファイルに平文で残ります。リポジトリ共有や設定同期のリスクを踏まえ、トークン類は載せない運用が安全です。

	getConfiguration + update	context.secrets
保存場所	設定 JSON（平文）	暗号化ストア（設定ファイル外）
設定 UI	宣言すれば一覧に出やすい	自動では出ない（コマンド等で保存）
同期	ユーザー設定は同期対象になりうる	公式説明ではマシン間同期されない

const KEY = 'settingsLab.playground.demoApiToken';
await context.secrets.store(KEY, plainText);
const token = await context.secrets.get(KEY);
await context.secrets.delete(KEY);

API 概要: Common Capabilities — Data Storage / SecretStorage

Antigravity で試したこと（2026-03 時点）

次は、学習用拡張 Antigravity Settings & Secret Playground（antigravity-vscode-extention-secret v0.0.3）を Extension Development Host（拡張のデバッグ用ウィンドウ）で動かしたときのメモです。 Antigravity は VS Code 派生なので、本家 VS Code と挙動が少し違っても不思議ではない、という前提で読んでください。

1. 設定が設定画面に出てこない

設定 ID を antigravity.something のように先頭が antigravityにすると、package.json に間違いがなくても、設定 UI に1行も出ないことがありました。 本体側がすでに antigravity という名前を内部で使っている可能性が高いです。

対処: 設定の「頭の名前」だけ変える。例では settingsLab.playground.〇〇 にしたら、中身は同じでも一覧に表示された、という結果でした。

2. 「設定を開く」コマンドの渡し方

workbench.action.openSettings は、設定画面を開くときに検索欄に文字列を入れるのに使えます。 VS Code では @ext:出版社ID.拡張ID でその拡張の設定だけ絞る書き方がよく使われますが、Antigravity ではそれが「該当なし」扱いになることがありました。

対処: 検索語に 設定キーの共通の頭を渡す。例: settingsLab.playground。そうすると一覧に自分の項目が残りやすいです。

3. コマンド名と設定名は別でよい

コマンド ID（例: antigravity.secretPlayground.refresh）はそのままでも問題になりにくかったです。 本体と被らせたくないのは「設定のキー」の方だと割り切ると、名前の付け方が整理しやすいです。

設定が UI に出ないときのチェック順

下の図は「何の説明か」を一文で言うと、拡張の設定が設定画面に載らないときに、上から順に試す手順です。 以前の版は「疑わしい／不明」などの分岐ラベルだけが目立ち、意味が伝わりにくかったので、一直線のステップにしました（クリックで全画面表示できます）。