VS Code 中的 Agent 外掛 (預覽)

Agent 外掛是預先打包的聊天自訂組合，您可以從 Visual Studio Code 中的外掛市集探索並安裝。單一外掛可以提供斜線指令、Agent 技能、自訂 Agent、Hook 和 MCP 伺服器的任意組合。

外掛與您在本機定義的自訂功能協同工作。當您安裝外掛時，其指令、技能、Agent、Hook 和 MCP 伺服器將會出現在聊天中。

外掛提供什麼

Agent 外掛可以捆綁以下一種或多種自訂類型

• 斜線指令：您可以在聊天中以 / 叫用的額外指令
• 技能：Agent 技能，包含指令、指令碼和按需載入的資源
• Agent：自訂 Agent，包含專門的人格設定和工具配置
• Hook：Hook，用於在 Agent 生命週期點執行殼層指令
• MCP 伺服器：MCP 伺服器，用於外部工具整合

例如，一個測試外掛可能包含一個帶有指令碼的 test-runner 技能、一個帶有唯讀工具的 test-reviewer Agent，以及一個用於測試報告儀表板的 MCP 伺服器。外掛的目錄結構如下所示

my-testing-plugin/
  plugin.json              # Plugin metadata and configuration
  skills/
    test-runner/
      SKILL.md             # Testing skill instructions
      run-tests.sh         # Supporting script
  agents/
    test-reviewer.agent.md # Code review agent
  hooks/
    hooks.json             # Hook configuration
  scripts/
    validate-tests.sh      # Hook script
  .mcp.json                # MCP server definitions

安裝後，外掛提供的自訂功能會與您本機定義的功能一同顯示。例如，外掛中的技能會顯示在設定技能選單中，而外掛中的 MCP 伺服器會出現在 MCP 伺服器清單中。

外掛中的 Hook

外掛可以包含 Hook，用於在 Agent 生命週期點執行殼層指令。外掛 Hook 與您的工作區和使用者層級 Hook 協同工作。當外掛啟用時，除了為相同事件設定的任何其他 Hook 之外，其 Hook 也會觸發。

Hook 檔案位置

Hook 檔案位置取決於外掛格式

VS Code 會自動偵測外掛格式並自動發現 Hook 檔案。

my-plugin/
  hooks/
    hooks.json           # Hook configuration (Claude format)
  scripts/
    format.sh            # Hook script referenced by hooks.json

Hook 配置格式

外掛 Hook 使用與 工作區 Hook 相同的基本格式。VS Code 會解析 Claude Code Hook 配置，包括比對器語法。目前，VS Code 會忽略比對器值，因此 Hook 會在每個匹配事件上執行。

扁平格式 (與工作區 Hook 相同)

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
      }
    ]
  }
}

比對器格式 (Claude 相容性語法)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh"
          }
        ]
      }
    ]
  }
}

VS Code 會解析 matcher 欄位以與 Claude Code 相容，但目前會忽略比對器值。如果您需要在 VS Code 中篩選 Hook 行為，請檢查 Hook 指令碼中的事件輸入。

在 Hook 指令中參照外掛路徑

對於 Claude 格式的外掛，請在 Hook 指令中使用 ${CLAUDE_PLUGIN_ROOT} 權杖來參照外掛目錄中的指令碼和檔案。VS Code 會在執行階段將此權杖展開為外掛的絕對路徑，並為 Hook 處理程序設定一個 CLAUDE_PLUGIN_ROOT 環境變數。在您的指令碼中，可以將其存取為 $CLAUDE_PLUGIN_ROOT (或在 Windows 上為 %CLAUDE_PLUGIN_ROOT%)。

這很重要，因為外掛會安裝到工作區以外的位置，因此您無法使用相對路徑。

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-tool.sh"
      }
    ]
  }
}

支援的 Hook 事件

外掛 Hook 支援與工作區 Hook 相同的生命週期事件：SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、SubagentStart、SubagentStop 和 Stop。有關每個事件的詳細資訊，請參閱Hook 生命週期事件。

外掛 Hook 如何與其他 Hook 互動

外掛 Hook 與工作區層級和使用者層級 Hook 並行執行。當多個 Hook 針對相同事件時，它們都會執行。對於 PreToolUse Hook，所有 Hook 中最嚴格的權限決定會生效：deny 會覆寫 ask，而 ask 會覆寫 allow。

停用外掛也會停用其 Hook。您可以從擴充功能檢視中全域或針對特定工作區啟用或停用外掛。

外掛中的 MCP 伺服器

外掛可以捆綁 MCP 伺服器，為 Agent 提供額外的工具和資料來源。外掛 MCP 伺服器在外掛啟用時自動啟動，並在外掛停用時停止。

MCP 配置檔案

將 MCP 伺服器定義放置在外掛根目錄的 .mcp.json 中。VS Code 在載入外掛時會自動發現此檔案。

my-plugin/
  .mcp.json              # MCP server definitions
  servers/
    db-server             # Server executable
  config.json             # Server configuration

MCP 配置格式

外掛 MCP 伺服器定義在頂層的 mcpServers 物件中。每個伺服器項目都會指定指令、引數和選用的環境變數

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

在伺服器配置中參照外掛路徑

對於 Claude 格式的外掛，請在 MCP 伺服器欄位中使用 ${CLAUDE_PLUGIN_ROOT} 權杖來參照外掛目錄中的可執行檔和檔案。VS Code 會在以下欄位中展開此權杖

• command：可執行檔路徑
• args：命令列引數
• cwd：工作目錄
• env：環境變數值
• envFile：環境檔案路徑
• url：用於基於 HTTP 的 MCP 伺服器
• headers：HTTP 標頭值

VS Code 還會將 CLAUDE_PLUGIN_ROOT 環境變數注入到伺服器處理程序中，因此伺服器程式碼可以在執行階段存取外掛路徑。

外掛 MCP 伺服器如何與其他伺服器互動

外掛 MCP 伺服器與工作區和使用者層級 MCP 伺服器一同顯示。您可以透過相同的工具管理它們

• 在聊天檢視中選取設定工具以查看所有 MCP 伺服器（包括外掛伺服器）中的工具。
• 從命令調色盤執行 MCP：列出伺服器以與其他伺服器一同查看外掛伺服器。

安裝外掛時，外掛 MCP 伺服器會被隱含信任。與工作區 MCP 伺服器不同，它們在啟動時不會顯示單獨的信任提示。

停用外掛會停止其 MCP 伺服器。停止的伺服器提供的工具不再在聊天中可用。

探索並安裝外掛

VS Code 在擴充功能側邊欄中提供了一個專用檢視，用於瀏覽和管理 Agent 外掛。

瀏覽可用的外掛

1. 開啟擴充功能檢視 (⇧⌘X (Windows、Linux Ctrl+Shift+X)) 並在搜尋欄位中輸入 @agentPlugins。

   或者，在擴充功能側邊欄中選取更多動作 (三個點) 圖示，然後選擇檢視 > Agent 外掛。

2. 瀏覽您已設定市集中的可用外掛清單。

   

3. 選取安裝以在外掛使用者設定檔中安裝外掛。

   首次從新的市集安裝外掛時，VS Code 會顯示信任提示。在確認之前，請檢閱市集來源。

從原始碼安裝外掛

您可以直接從 Git 儲存庫 URL 安裝外掛，而無需先新增完整的市集。

• 從命令調色盤執行 聊天：從原始碼安裝外掛。
• 或者，在聊天自訂編輯器的外掛頁面上選取 + 按鈕。

輸入 Git 儲存庫 URL (例如，https://github.com/rwoll/markdown-review)，VS Code 會複製並安裝此外掛。

檢視已安裝的外掛

擴充功能檢視中的Agent 外掛 - 已安裝檢視會顯示您已安裝的外掛。從此檢視中，您可以啟用、停用或解除安裝外掛。

您也可以從聊天檢視中選取齒輪圖示 > 外掛來管理已安裝的外掛。

啟用或停用外掛

您可以全域或針對特定工作區啟用或停用外掛

• 在擴充功能檢視的Agent 外掛 - 已安裝區段中，使用外掛上的內容選單。
• 使用 聊天自訂編輯器來切換外掛的啟用狀態。

啟用/停用狀態與外掛配置分開儲存，因此不會影響共用工作區設定。

當外掛停用時，其技能、Agent、Hook、MCP 伺服器和斜線指令將不再可用。例如，停用外掛中的技能不會出現在聊天：設定技能中。停用的外掛會在聊天自訂編輯器和擴充功能檢視中以暗淡樣式顯示。

解除安裝外掛

若要移除外掛，請在Agent 外掛 - 已安裝檢視中右鍵點選它並選取解除安裝。從外部來源 (例如 npm、PyPI 或外部 Git 儲存庫) 安裝的外掛將從磁碟中移除。在市集儲存庫中內嵌的外掛會保留在磁碟上，但不再作用。

設定外掛市集

預設情況下，VS Code 會從 copilot-plugins 和 awesome-copilot 發現外掛。您可以使用 chat.plugins.marketplaces Open in VS Code Open in VS Code Insiders 設定來新增額外的市集。

市集是包含外掛定義的 Git 儲存庫。您可以使用多種格式參照它們

• 簡寫：用於公開 GitHub 儲存庫的 owner/repo。例如，anthropics/claude-code。
• HTTPS Git 遠端：以 .git 結尾的完整 URL。例如，https://github.com/anthropics/claude-code.git。
• SCP 樣式 Git 遠端：SSH 樣式參照。例如，git@github.com:anthropics/claude-code.git。
• 檔案 URI：指向已在磁碟上複製的市集儲存庫的 file:/// 路徑。

私有儲存庫也受支援。如果公開查找失敗，VS Code 會退回到直接複製儲存庫。

市集外掛也可以參照外部套件來源，例如 npm 或 PyPI 套件。有關完整的市集外掛架構，請參閱 Claude Code 外掛市集文件。

// settings.json
"chat.plugins.marketplaces": [
    "anthropics/claude-code"
]

使用本機外掛

如果您手動複製或下載外掛，可以使用 chat.pluginLocations Open in VS Code Open in VS Code Insiders 設定來註冊它。此設定將本機外掛目錄路徑映射到啟用或停用狀態。

// settings.json
"chat.pluginLocations": {
    "/path/to/my-plugin": true,
    "/path/to/another-plugin": false
}

將值設定為 true 以啟用外掛，或設定為 false 以保持註冊但停用。

更新外掛

當您從命令調色盤執行 擴充功能：檢查擴充功能更新時，或者當 extensions.autoUpdate Open in VS Code Open in VS Code Insiders 啟用時，VS Code 會每 24 小時自動檢查外掛更新。

更新會從已複製的市集儲存庫中提取變更，並檢查外部來源外掛的新版本。

從 npm 或 PyPI 來源的外掛永遠不會自動更新。相反，它們會在擴充功能檢視中顯示更新按鈕。選取該按鈕會提示您確認，然後再執行安裝指令。如果在背景檢查期間發現更新，則在您明確選取更新之前不會採取任何動作。

工作區外掛建議

專案可以透過在工作區設定中配置外掛設定，為團隊成員推薦外掛。

• enabledPlugins：列出應預設啟用的外掛。VS Code 會在第一次傳送聊天訊息時顯示通知，並在擴充功能檢視的 @agentPlugins @recommended 下列出這些外掛。
• extraKnownMarketplaces：為專案註冊額外的市集。當您在擴充功能檢視中搜尋 @agentPlugins 時，這些市集會出現。

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/plugin-marketplace"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true
  }
}

相關資源

• 尋找並安裝 GitHub Copilot CLI 的外掛
• 使用 Agent 技能
• 新增和管理 MCP 伺服器
• 使用 Hook 進行生命週期自動化
• 建立自訂代理