Перейти к содержимому

Обслуживать установленные плагины ​

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

Сначала изучите состояние ​

bash
agentplugins list
agentplugins doctor
agentplugins outdated --all

list перечисляет установки, doctor проверяет управляемое состояние, outdated ищет обновления без их применения. Они не доказывают доступность удалённого сервиса или завершённую аутентификацию клиента.

ПроблемаСледующий шаг
Пакета нетНайти и установить.
Управляемые файлы исчезли или изменилисьПроверить план repair для пакета и нужной области.
В отслеживаемом источнике есть новая версияПроверить план update.
Клиенту нужны доверие, активация или входВыполнить указанные клиентом действия.
Локальный пакет не проходит проверкуПередать автору отчёт и руководство по проверкам.

Локальный API управления ​

CLI добавляет agentplugins manage serve для приложений, встраивающих установщик, и agentplugins manage discover для локального обнаружения клиентов и профилей без изменений. Обнаружение не запускает клиенты, не проверяет их версии, не загружает источники и не меняет файлы.

manage serve работает как процесс под управлением встраивающего приложения с зафиксированным при запуске контекстом и закрытым аутентифицированным API на IPv4 loopback. Приложение передаёт JSON через stdin и сохраняет в тайне начальный URL и bearer-токен. Перед интеграцией проверьте справку команд:

bash
agentplugins version
agentplugins manage serve --help
agentplugins manage discover --help

Правила запуска и жизненного цикла описаны в контракте протокола управления. TypeScript Management SDK имеет независимую нумерацию версий и имя пакета universal-agent-plugins-management-sdk. Совместимые версии движка agentplugins и инструкции по установке пакета указаны в README SDK. Выберите опубликованный релиз в npm, а для ещё не выпущенных изменений соберите и протестируйте пакет из исходного кода на зафиксированном коммите. Фиксируйте версии и SDK, и движка.

Обновляйте осознанно ​

bash
agentplugins update context7 --target codex,cursor --dry-run

Проверьте источник, версию и пути. Для применения опустите --dry-run:

bash
agentplugins update context7 --target codex,cursor

update --all охватывает все управляемые кандидаты обновления. Используйте его, когда нужен весь этот набор. Точный коммит остаётся неизменяемым: обновление не превращает его в отслеживание ветки. Диапазоны версий и изменяемые ссылки Git сохранённых зависимостей продвигаются соответствующей явной операцией update.

Восстановите записанное состояние ​

bash
agentplugins repair context7 --target codex,cursor --dry-run
agentplugins repair context7 --target codex,cursor

Первая команда показывает план, вторая применяет его. Repair использует записанный источник для восстановления управляемого содержимого. Он не выбирает новую ревизию и не перезаписывает незаметно изменённые извне нативные записи. Изучите конфликты и указания по незавершённому восстановлению.

Удалите выбранную установку ​

bash
agentplugins remove context7 --target codex,cursor --dry-run
agentplugins remove context7 --target codex,cursor

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

Используйте сохранённое окружение зависимостей ​

uap.toml задаёт требуемые пакеты и клиенты; uap.lock фиксирует точные источники и хеши. Проверьте выбранное окружение:

bash
agentplugins deps status
agentplugins deps tree

Для нового окружения выполните agentplugins deps init, осознанно отредактируйте манифест, разрешите зависимости через agentplugins deps lock и примените lock через agentplugins install --locked --scope user. Изучайте подтверждения; для просмотра есть --dry-run. Руководство по зависимостям объясняет синтаксис, обязательные зависимости пакетов, диапазоны и обновления.

В CLI 0.1.93 подходящие удалённые операции add по умолчанию сохраняют переносимые зависимости. Явные локальные пути, источники discovery, отдельная подготовка ChatGPT и --no-save используют разовую установку. Ранее выполненная разовая установка не обязательно входит в соглашение: проверьте deps status и сами файлы перед переносом.

Восстановите на другом компьютере ​

В папке для переноса на исходном компьютере выполните:

bash
agentplugins deps export

Скопируйте папку на другой компьютер, установите нужные клиенты и выполните там:

bash
agentplugins deps import
agentplugins install --locked --scope user

Либо совместите импорт и восстановление:

bash
agentplugins deps import --install

Необязательный аргумент каталога выбирает другую папку обмена. Export читает пользовательское окружение, import записывает его; AGENTPLUGINS_HOME может выбрать конкретное окружение. Переданная папка не заменяет профиль клиента. Явный --scope user сохраняет пользовательскую область восстановления.

Переносятся только неизменённые, строго проверенные uap.toml и uap.lock. Фактическое копирование показывает план и требует подтверждения или --yes; --dry-run показывает его без записи. Импорт проверяется без сети, но установке нужны записанные источники или проверенный кэш. При пустом кэше загружаются точные закреплённые пакеты с проверкой хешей, без выбора новых версий.

Профили, настройки, учётные данные, квитанции и PLUGIN_DATA не переносятся. Настройте вход на новом компьютере, отдельно сохраните данные плагинов. Если установка не удалась после сохранения пары при импорте, исправьте причину и повторите install --locked --scope user. При сообщении о незавершённом восстановлении сначала выполните deps recover --scope user. Не пересоздавайте перенесённые закрепления через deps lock: подвижный источник может разрешиться иначе.

Восстановите и обслуживайте проект ​

Автоматическая установка в проект доступна в CLI 0.1.94 и новее. Добавьте проектные uap.toml и uap.lock в контроль версий. В другой уже существующей рабочей копии репозитория установите нужные клиенты и выполните из каталога самого проекта:

bash
agentplugins install

Существующий lock-файл строго проверяется. --locked дополнительно требует его наличия, что полезно в CI; без lock-файла первая установка может создать его. При запуске из другого каталога явно выберите существующий проект:

bash
agentplugins install --locked --scope project --project-root /path/to/project

Для обслуживания выбирайте ту же область и корень:

bash
agentplugins list --scope project --project-root /path/to/project
agentplugins deps status --scope project --project-root /path/to/project
agentplugins repair review --target cursor --scope project --project-root /path/to/project
agentplugins deps recover --scope project --project-root /path/to/project

При неоднозначном имени используйте идентификатор из list. Команды обслуживания используют пользовательскую область, если проект не выбран явно. Для install без аргумента источника действует описанное ниже правило 0.1.94. --scope project без --project-root выбирает текущую папку.

Квитанции, журналы восстановления и сохранённые данные .uap/ оставляйте локальными. Нативные компоненты восстанавливайте по переносимой паре файлов, после чего выполните требования клиента к доверию и активации. Источники и доступ к закрытым репозиториям должны оставаться доступны. См. установку в проект и ограничения клиентов.

Выбор области install в CLI 0.1.94 ​

Сначала проверьте agentplugins version. Нужно не менее 0.1.94; если пакетный канал ещё поставляет старую версию, используйте нативный установщик или Homebrew. Явные проектные команды выше совместимы и с 0.1.93.

Выпущено в CLI 0.1.94:agentplugins install без аргумента источника и явной области выбирает проект при обычном файле uap.toml непосредственно в текущей папке. Родители не просматриваются. Каталог или символическая ссылка с таким именем вызывают отказ автоматического выбора; укажите область явно. Без локального манифеста выбирается пользовательское окружение. Явные --scope user и --scope project имеют приоритет. Остальные команды по умолчанию продолжают использовать пользовательскую область.

Существующий uap.lock строго проверяется до изменений даже без --locked. Несоответствие останавливает операцию; для продвижения закреплённых версий используйте update, а не ожидайте обновления от install. Только отсутствие lock-файла допускает первоначальное разрешение и создание lock. --locked дополнительно требует существующий lock-файл. Для предсказуемой автоматизации и восстановления проекта подходят явная область и --locked из примеров выше.

Как сообщить о проблеме ​

Запишите версию CLI, команду, область, источник пакета, клиенты и оставшуюся активацию. Укажите этап: получение источника, планирование, запись файлов, восстановление, обнаружение клиентом, аутентификация или исполнение. Удалите секреты из диагностики. author doctor ./my-plugin изучает исходный пакет; agentplugins doctor проверяет состояние установщика.

Публичная документация для авторов плагинов и интеграторов.