Публикация и обновления

Магазина нет: карточка опубликована, когда она на GitHub, и ставится по своему адресу на GitHub. Проверка — по желанию: чтобы карточка попала в каталог проверенных приложения (поиск прямо из меню добавления и значок «Проверена»), пришлите pull request в glmn-ai/neurosquad-cards, как описано в его SUBMITTING.md . Каждая проверенная версия закреплена на одном коммите.

Опубликовать

Выполните npx @neurosquad/card-sdk validate и pack --dry-run. Исправьте все ошибки; прочитайте превью диалога установки глазами незнакомого человека.
Закоммитьте всё, что нужно карточке, — включая результат сборки (dist/): приложение никогда ничего не собирает. pack перечисляет ровно то, что будет установлено.
Запушьте в публичный репозиторий на GitHub (приватные тоже работают — для пользователей, которые добавят GitHub-токен).
При желании поставьте тег релиза: git tag v1.0.0 && git push --tags — и создайте из тега релиз на GitHub.
Сообщите людям адрес.

Несколько карточек в одном репозитории — это нормально: каждая лежит в своей папке со своим манифестом и ставится как owner/repo/path/to/folder.

С каких адресов можно установить

Адрес	Что ставится	За чем следят обновления
`owner/repo`	свежий коммит ветки по умолчанию	ветка по умолчанию
`owner/repo@main`	эта ветка	эта ветка
`owner/repo@v1.2.0`	этот тег	ни за чем — тег неизменен
`owner/repo@<40-hex commit>`	этот коммит	ни за чем
`https://github.com/owner/repo/releases/tag/v1.2.0`	этот релиз	последний релиз
`owner/repo/cards/pomodoro`, `https://github.com/owner/repo/tree/main/cards/pomodoro`	карточка из этой папки	как выше

Подойдут и github.com/owner/repo, https://github.com/owner/repo.git. Ссылку (ref), в которой есть /, нужно указывать через @ref.

Привязка к коммиту. Какой бы ни был адрес, приложение сводит его к одному коммиту и ставит файлы этого коммита. Коммит, заданный хешем, должен быть достижим из ветки по умолчанию репозитория — коммит, который есть только в форке, отклоняется, — а переименованный или переданный репозиторий нужно ставить под его текущим именем. Приложение записывает коммит и хеш дерева всех файлов. Введённый пользователем адрес — не идентичность карточки, ею является github:owner/repo[/folder], — поэтому обновление сохраняет разрешения карточки, её хранилище и все копии на всех холстах.

Как обновления доходят до пользователей

Приложение проверяет через минуту после запуска, потом каждые 24 часа и когда пользователь нажимает Check for updates.
Более новый коммит скачивается и проверяется, а потом предлагается: Update в настройках и точка на карточке. Ничего не применяется автоматически.
Пользователь видит, что меняется: новую версию, старый → новый коммит со ссылкой на сравнение в GitHub и разницу в разрешениях:
- новые разрешения и новые сетевые хосты → обновление ждёт согласия пользователя;
- разрешения, которые больше не нужны → отзываются при обновлении;
- новые необязательные разрешения → показываются как «может попросить позже» и никогда не выдаются сами;
- новые или переформулированные инструменты, новые порты или порты с другим типом, новые секретные настройки, изменённые displayName, автор или домашняя страница → обновление тоже ждёт согласия пользователя.
При обновлении каждая открытая копия карточки перезагружается с launch === 'updated'. Хранилище и настройки переносятся — если вы поменяли их структуру, переносите данные в коде.
Если в новом приложении манифест перестал проходить проверку, карточка показывается сломанной, с причиной; запускать её всё равно не будут.

Перезапись тега или истории не протащит код мимо пользователей: тот же коммит, скачанный заново с другим содержимым, отклоняется, а каждое обновление показывается до применения. Но с каждым принятым обновлением пользователи доверяют вам — защитите свой аккаунт GitHub (2FA) и проверяйте пул-реквесты в вашу карточку как код, который будет работать на чужих машинах.

Версии

version вашей карточки — для информации (установка привязана к коммитам), но пользователи видят её в диалоге установки, в диалоге обновления и в Settings → Custom cards. Пользуйтесь SemVer и повышайте её в каждом релизе. Ломающие изменения портов и инструментов описывайте в описании: от них могут зависеть чужие карточки и привычки агентов.

minAppVersion не даёт поставить карточку в слишком старое приложение.

Протокол версионируется отдельно: "protocol": 1 в манифесте, CARD_PROTOCOL_VERSION в SDK.

Новые методы, события и необязательные поля появляются внутри протокола 1. Проверяйте их наличие через card.host.supports('method.name') и продолжайте работать без них.
Ломающее изменение стало бы протоколом 2. Приложение, которое знает только 1, отклонит карточку под 2 с сообщением «нужен более новый NeuroSquad»; карточки протокола 1 приложение продолжало бы обслуживать параллельно ещё минимум год.
Обновлять @neurosquad/card-sdk в пределах одной мажорной версии безопасно; пересоберите и опубликуйте заново.

Изменение разрешений и того, что предлагает карточка

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

сделать новое разрешение необязательным и просить его, когда пользователь дойдёт до функции;
выпустить изменение разрешений отдельным релизом и объяснить его в описании.

Как вывести карточку из обращения

Не удаляйте репозиторий: установленным копиям он для работы не нужен, но нужен для обновлений и переустановки. Напишите об этом в описании и укажите замену.