Справочное руководство по плагинам Claude Code

Плагины — этоядро функционального расширения, которое помогает добавлять пользовательские слэш-команды, субагентов, хуки автоматизации и другие возможности. В этом руководстве рассматриваютсяосновные компоненты、и спецификации конфигурации、Управление CLIпо трём измерениям, чтобы быстро помочь вам освоить ключевые моменты использования и разработки плагинов.


Основные компоненты плагина: 5 типов возможностей расширения

Плагины обеспечивают функциональное расширение с помощью 5 типов компонентов, каждый из которых имеет фиксированные места хранения и требования к формату.

Тип компонента Место хранения Формат файла Основная функция
Команда Корневой каталог плагинаcommands/ Файл Markdown с метаданными frontmatter Добавление пользовательских слэш-команд, например,/deploy /code-review
Агент Корневой каталог плагинаagents/ Файл Markdown Предоставляйте специализированных субагентов, таких как агенты для проверки кода, агенты для тестирования производительности
Навык Корневой каталог плагинаskills/ содержащийSKILL.mdкаталога Позвольте Claude автоматически распознавать сценарии и вызывать их, например, парсинг PDF, визуализация данных
Хук Корневой каталог плагинаhooks/hooks.jsonилиplugin.jsonВстроенный Файл конфигурации JSON Прослушивайте события Claude и автоматически реагируйте, например, автоматически форматируйте код после редактирования файла
Сервер MCP Корневой каталог плагина.mcp.jsonилиplugin.jsonВстроенный Файл конфигурации JSON Подключайте внешние инструменты (такие как GitHub, Jira) и превращайте их возможности в инструменты, доступные для использования Claude
Сервер LSP Корневой каталог плагина.lsp.jsonилиplugin.jsonВстроенный Файл конфигурации JSON Предоставляйте возможности анализа кода, такие как проверка синтаксиса, переход к определению, подсказки при наведении

Примеры ключевых компонентов

1. Пример конфигурации хука: Автоматическое форматирование после редактирования файла

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

: Поддержка интеллектуальных подсказок языка Go

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

Основные спецификации плагина: область установки и манифест

1. Область установки: определяет диапазон доступности плагина

При установке плагина необходимо выбрать область. Разные области соответствуют разным файлам конфигурации и сценариям использования:

Область действия Путь к файлу конфигурации Сценарий применения
user ~/.claude/settings.json Персональная, общая для всех проектов (по умолчанию)
project .claude/settings.json Общая для команды, синхронизируется с репозиторием
local .claude/settings.local.json Специфичная для проекта,.gitignoreигнорируется
managed managed-settings.json Управляемый плагин, только для чтения и автоматически обновляемый

2. Манифест плагина:plugin.jsonКлючевые моменты, которые нужно знать

plugin.jsonявляетсяосновным конфигурационным файлом плагина, хранящимся в.claude-plugin/каталог, используемый для определения метаданных плагина и путей к компонентам.

a. Обязательные поля

Поле Type Требование Пример
name string Уникальный идентификатор, формат kebab-case "go-code-helper"

b. Основные поля метаданных

{
  "version": "1.0.0", // 语义化版本
  "description": "提供 Go 语言代码智能和调试能力",
  "author": {
    "name": "Dev Team",
    "email": "dev@example.com"
  },
  "license": "MIT"
}

c. Поля путей к компонентам

Используется для указания расположения пользовательских компонентов. Путь должен бытьотносительно корневого каталога плагинаи./начинаться с:

{
  "commands": ["./custom-commands/deploy.md"],
  "agents": "./custom-agents/",
  "hooks": "./hooks.json"
}

d. Переменные окружения

${CLAUDE_PLUGIN_ROOT}Абсолютный путь к корневому каталогу плагина, используется для ссылки на файлы внутри плагина в скриптах и конфигурациях, что позволяет избежать ошибок в путях.

3. Стандартная структура каталогов плагина

my-plugin/
├── .claude-plugin/           # 元数据目录
│   └── plugin.json          # 插件清单(必需)
├── commands/                 # 自定义斜杠命令
├── agents/                   # 子代理定义
├── skills/                   # 自动技能
├── hooks/                    # 事件钩子配置
├── .mcp.json                # MCP 服务器配置
├── .lsp.json                # LSP 服务器配置
└── scripts/                 # 钩子执行脚本

Примечание:commands/ agents/Такие каталоги компонентов должны находиться вкорневом каталогеплагина и не могут быть размещены.claude-plugin/внутри.


Управление плагинами: краткий справочник по командам CLI

С помощью Claude Code CLI можно быстро устанавливать, удалять, включать и отключать плагины; подходит для сценариев скриптинга и автоматизации.

Команда Назначение Пример
claude plugin install <插件名> -s <范围> Установить плагин claude plugin install go-lsp --scope project
claude plugin uninstall <插件名> Удалить плагин claude plugin uninstall go-lsp
claude plugin enable <插件名> Включить отключенный плагин claude plugin enable go-lsp
claude plugin disable <插件名> Отключить плагин (без удаления) claude plugin disable go-lsp
claude plugin update <插件名> Обновить плагин до последней версии claude plugin update go-lsp

Отладка и диагностика: решения типичных проблем

1. Команды отладки

Выполните следующую команду, чтобы просмотреть подробности загрузки плагинов и выявить проблемы с конфигурацией и загрузкой:

claude --debug

Можно просмотреть: состояние загрузки плагинов, синтаксические ошибки манифеста, состояние регистрации компонентов, журналы инициализации серверов MCP/LSP.

2. Частые проблемы и решения

Проблема Причина Решение
Плагин не загружен plugin.jsonОшибка синтаксиса или отсутствуют обязательные поля использоватьclaude plugin validateПроверьте синтаксис JSON, добавьте отсутствующееnameполе
Пользовательские команды не отображаются Файл команды размещён в.claude-plugin/внутри будетcommands/Переместите каталог в корневой каталог плагина
Скрипт хука не выполняется Скрипт не имеет разрешения на выполнение Запуститеchmod +x scripts/your-script.shчтобы предоставить разрешение
Подсказка LSPExecutable not found Соответствующий языковой сервер не установлен Установите, например, Go требуетgopls)
Не удалось запустить сервер MCP Путь использует абсолютный путь, не использует${CLAUDE_PLUGIN_ROOT} Замените ссылкой на переменную окружения, затем${CLAUDE_PLUGIN_ROOT}/server

Управление версиями и распространение

  • Спецификация версии: следуйте семантическому версионированиюMAJOR.MINOR.PATCH, например1.2.3
  • Каналы распространения: распространяйте через маркетплейс плагинов или делитесь каталогом плагина напрямую (должен включать полную структуру)
  • Журнал изменений: рекомендуется размещать в корневом каталоге плагинаCHANGELOG.mdдля записи содержимого обновления версии
Другие расширения