# Создание своего плагина

Локальный плагин — это плагин, который вы делаете для себя. Он меняет внешний вид или раскладку Gemini, AI Studio, ChatGPT, Claude или DeepSeek, хранится только в вашем браузере и не требует ни pull request, ни копии исходного кода Voyager.

Как и любой плагин Voyager, он декларативный: манифест `plugin.json` плюс CSS. Собственного кода он не выполняет. Voyager проверяет его при импорте, применяет изменения и убирает все изменения, когда вы выключаете плагин. Импортированный плагин сначала выключен, поэтому его можно просмотреть перед включением.

## Три способа сделать плагин

### Опишите изменение, а код напишет любой ИИ

1. Откройте сайт, который хотите изменить, откройте всплывающее окно Voyager и найдите карточку **Локальные плагины** (в Gemini и AI Studio это последний пункт настроек).
2. Выберите **Описать изменение**, напишите одно предложение («Сделай мои сообщения уже и скрой боковую панель») и выберите **Составить промпт**.
3. Скопируйте промпт в любой чат с ИИ сами, вставьте его ответ целиком обратно и выберите **Проверить ответ**.
4. Voyager простым языком покажет, что меняет плагин. Импортируйте его и включите в списке плагинов.

Voyager никуда не отправляет промпт: вы сами выбираете ИИ и переносите текст туда и обратно.

### Поручите это ИИ-агенту для программирования

Если вы пользуетесь агентом для программирования (Claude Code, Codex, Cursor и подобными), дайте ему skill Voyager для плагинов:

```text
https://voyager.nagi.fun/skills/write-voyager-plugin/SKILL.md
```

В карточке **Локальные плагины** откройте **Описать изменение**: там есть кнопка **Копировать ссылку на skill**. Skill описывает весь контракт: поля манифеста, что объявляет каждый сайт, примитивы и то, чего плагин не может делать. Попросите агента о нужном изменении: он создаст папку, напишет `plugin.json` и `style.css` и проверит их офлайн. После этого во всплывающем окне выберите **Импорт файлов** и укажите оба файла.

Чтобы skill всегда был под рукой, сохраните файл как `write-voyager-plugin/SKILL.md` в папке skills вашего агента (для Claude Code это `~/.claude/skills/`).

### Напишите вручную

Нужен Node.js 18 или новее:

```sh
npx create-voyager-plugin@latest init my-plugin --site claude
# отредактируйте my-plugin/plugin.json и my-plugin/style.css
npx create-voyager-plugin@latest check my-plugin
```

`init` создаёт `plugin.json` и `style.css`, которые уже проходят проверку, а также `AGENTS.md` с правилами для выбранного сайта. `--site` принимает `gemini`, `aistudio`, `chatgpt`, `claude` или `deepseek`.

`check` офлайн выполняет те же проверки, что и импорт во всплывающем окне. Если плагин можно импортировать, команда завершается с кодом 0; иначе она выводит по одной строке вида `путь: сообщение` на каждую проблему. Добавьте `--json`, чтобы получить вывод в машиночитаемом виде.

## Что умеет плагин

- Добавлять CSS, ограниченный классом `gv-`, который плагин добавляет на страницу.
- Добавлять класс, задавать безопасный атрибут или inline-стиль и скрывать элементы. Цели — семантические ключи, которые объявляет сайт (`userTurn`, `assistantTurn`, `composer` и т. д.), или CSS-селекторы.
- Показывать настройки во всплывающем окне: переключатели, ползунки и выпадающие списки; их значения попадают в CSS через токены `{{key}}`.
- На ChatGPT, Claude и DeepSeek включать примитивы Voyager (копирование формул, таймлайн, диаграммы Mermaid и другие) и подкрашивать собственный интерфейс Voyager.

## Чего плагин не умеет

Плагин не может выполнять JavaScript, реагировать на клики или нажатия клавиш, загружать что-либо из сети (шрифты, изображения, таблицы стилей), читать или переписывать текст сообщений и работать на других сайтах. Если запрос требует чего-то из этого, материалы для авторов велят ИИ прямо сказать об этом и собрать ближайший вариант, который действительно работает.

## Правила, которые проверяет импорт

Помимо общих проверок манифеста (см. [Участие в разработке плагинов](./plugin-contribution.md)), локальный плагин должен:

- совпадать только с URL внутри сайтов, которые поддерживает Voyager;
- использовать только те семантические ключи, которые объявлены на всех совпадающих сайтах;
- добавлять ровно один класс в каждом `addClass`, и этот класс должен начинаться с `gv-`;
- использовать настройки типа boolean, number или select (у string и color пока нет элемента управления во всплывающем окне);
- не использовать `theme` в Gemini и AI Studio, а примитивы брать только те, которые разрешены для каждого сайта: `formulaCopy`, `vimInput`, `userLatex`, `codeCollapse`, `mermaid`, `wavedrom` и `echarts`, `sendShortcut`, `draftSave`, `turnNavigator` в Gemini, а `formulaCopy` и `sendShortcut` в AI Studio. Они запускают тот же код, что и встроенные настройки Voyager. `formulaCopy` и `vimInput` (копирование формул и Vim-режим ввода) работают на странице в одном экземпляре: либо встроенная настройка, либо плагин, но не оба. При загрузке страницы или пока ни один из них не работает, приоритет у встроенной настройки; дальше тот, который уже работает, продолжает работать, а второй отображается как приостановленный. Выключите один из них, чтобы передать функцию другому. `userLatex`, `codeCollapse`, `mermaid`, `wavedrom` и `echarts` занимают элементы страницы поштучно и работают одновременно со встроенной настройкой: строку или блок кода, которые уже заняты другим, они оставляют ему.

В потребительской версии Gemini локальный `turnNavigator` теперь поддерживается с `params.dataBackend: "shared"` и `engine: ">=1.9.0"`. Он читает и записывает те же нативные данные звёздочек и иерархии, что и официальный таймлайн; параметры идентификации беседы, аккаунта и реплик переопределять нельзя. Настройка **Показывать таймлайн** конфликтует с ним: перед включением локального плагина отключите её. Чтобы вернуться к официальному таймлайну, сначала отключите локальный плагин, затем включите настройку. Business, Enterprise и покрытие произвольных сайтов не поддерживаются.

Переводы (`i18n`) необязательны.

## Как поделиться

Локальный плагин остаётся в вашем браузере; чтобы перенести его в другое место, экспортируйте его JSON из списка плагинов. Если он пригодится всем, предложите его для официального каталога: этот путь описан в [руководстве по участию в разработке плагинов](./plugin-contribution.md).

На каждом сайте на странице работает только один плагин сочетания клавиш отправки. Пока один плагин занимает режим отправки, другой сообщает о конфликте и остаётся приостановленным. Необязательный `mode` (требует `"engine": ">=1.9.0"`) — это `ctrlEnterSends` (по умолчанию) или `enterSends`. Подтверждение ввода через IME не отправляет сообщение. Gemini и AI Studio уже разрешают этот примитив; поддерживаемые режимы описаны ниже.

В Gemini `sendShortcut` может заменить встроенную функцию Ctrl/Cmd+Enter: отключите официальный переключатель и включите локальный плагин. Поддерживается только `ctrlEnterSends`; в Enterprise функция остаётся неактивной. `composerRoot` охватывает основное поле ввода и редактирование сообщений; `sendButton` не включает кнопку остановки.

В AI Studio для `sendShortcut` требуется `params.mode: "enterSends"`. Отключите официальный переключатель отправки по Enter, чтобы управление перешло к локальному плагину. Ctrl/Cmd+Enter добавляет новую строку; Shift/Alt+Enter обрабатывает сам сайт.

В Gemini `draftSave` использует те же записи черновиков `gvDraft_<полный pathname>`, что и официальная функция, включая маршруты `/u/N` и Gem. Отключение сохраняет уже записанные черновики; несколько плагинов на одной странице могут использовать эти записи. Перед закрытием страницы плагин пытается сохранить последний введённый текст, но браузер при закрытии не гарантирует завершение асинхронной записи. Запись и очистку координируют только в пределах этой страницы; смена почты внутри одного слота `/u/N` по-прежнему использует общие сохранённые черновики.