Обслуговування встановлених плагінів

Використовуйте інсталятор для перегляду й зміни керованого стану встановлення. Досліджуючи проблему, зберігайте у звіті джерело пакета, обрані клієнти, область та ідентифікатор встановлення. Наведені нижче приклади використовують область користувача, якщо проєкт не обрано явно.

Спершу з'ясуйте стан

agentplugins list
agentplugins doctor
agentplugins outdated --all

list показує встановлення, doctor діагностує керований стан, а outdated знаходить можливі оновлення, не застосовуючи їх. Жодна з цих команд не доводить справність віддаленого сервісу чи завершення автентифікації в клієнті.

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

Локальний API керування (CLI 0.1.95)

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

manage serve працює як процес під керуванням застосунку з контекстом, зафіксованим під час запуску, та приватним автентифікованим API на IPv4 loopback. Застосунок передає JSON через stdin і зберігає початкову URL-адресу та bearer-токен у таємниці. Перед інтеграцією перевірте довідку команд:

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

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

Оновлюйте свідомо

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

Перевірте обране джерело, версію та місця встановлення. Приберіть --dry-run, щоб застосувати зміни:

agentplugins update context7 --target codex,cursor

update --all охоплює всі керовані пакети, для яких доступні оновлення. Використовуйте його, якщо маєте намір оновити весь набір. Джерело з точним комітом залишається незмінним; оновлення не переводить його на відстеження гілки. Збережені діапазони версій та рухомі посилання змінюються лише через відповідну явну операцію оновлення.

Відновіть записаний стан

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

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

Видаліть обране встановлення

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

Перегляньте перший план перед запуском другої команди. Видалення спирається на записані CLI дані про належність файлів. Воно не відкликає обліковий запис сервісу, не видаляє сторонні середовища виконання або каталог вихідного коду автора. Видалення з проєкту за замовчуванням зберігає дані плагінів і спільне сховище перевіреного вмісту.

Використайте збережене середовище залежностей

uap.toml описує потрібні пакети та клієнти; uap.lock записує їхні точні визначені джерела й дайджести. Перегляньте обране середовище:

agentplugins deps status
agentplugins deps tree

Для нового середовища виконайте agentplugins deps init, свідомо відредагуйте маніфест, потім запустіть agentplugins deps lock, щоб визначити залежності, і agentplugins install --locked --scope user, щоб застосувати зафіксований набір. Переглядайте запити підтвердження та використовуйте --dry-run для попереднього перегляду. Посібник із залежностей пояснює синтаксис маніфесту, обов'язкові залежності пакетів, діапазони версій і правила оновлення.

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

Відновіть середовище на іншому комп'ютері

Перенесіть збережене середовище користувача через папку обміну. На початковому комп'ютері виконайте в цій папці:

agentplugins deps export

Скопіюйте папку на інший комп'ютер, установіть цільові клієнти та виконайте там:

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

Або поєднайте імпорт і відновлення:

agentplugins deps import --install

Необов'язковий аргумент каталогу обирає іншу папку обміну. Експорт читає середовище користувача, а імпорт записує його; через 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 проєкту до системи контролю версій. В іншій наявній копії репозиторію встановіть потрібні клієнти та виконайте команду саме з каталогу проєкту:

agentplugins install

Наявний файл фіксації перевіряється суворо. --locked додатково вимагає, щоб він існував, що корисно в CI; якщо його немає, перше встановлення може створити його. Під час запуску з іншого каталогу оберіть наявний проєкт явно:

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

Для обслуговування обирайте ту саму область і корінь:

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/, журнали відновлення та залишені дані локально. Відновлюйте нативні компоненти з переносного опису залежностей і виконуйте інструкції клієнта щодо довіри чи активації. Джерела й доступ до приватних джерел мають залишатися доступними. Див. встановлення для проєкту та обмеження клієнтів.

Вибір області встановлення за замовчуванням у 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, а не очікуйте, що встановлення оновить їх. Лише відсутність файлу фіксації дозволяє визначення залежностей під час першого встановлення та його створення. --locked додатково вимагає наявного файлу фіксації. Для передбачуваної автоматизації й відновлення проєкту доречні наведені вище приклади з явною областю та --locked.

Чітко опишіть проблему

Запишіть версію CLI, операцію, область, джерело пакета, цільові клієнти та невиконані кроки активації. Зазначте, де саме сталася помилка: отримання джерела, планування, запис файлів, відновлення, виявлення клієнтом, автентифікація чи виконання. Перед поширенням діагностики видаліть облікові дані. Команда розробки doctor ./my-plugin досліджує вихідний пакет; doctor інсталятора діагностує керований стан встановлення.