Справочное руководство по плагинам 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": {
"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для записи содержимого обновления версии