Проверенные карточки

Выложить карточку сообщества на GitHub может кто угодно, и до установки её никто не проверяет. Проверенные карточки (verified) — исключение: это карточки сообщества, которые команда NeuroSquad прочитала и опробовала, каждый раз — одну конкретную версию. Они собраны в открытом каталоге, и приложение умеет ставить их прямо оттуда.

Каталог — это файл verified.json в открытом репозитории glmn-ai/neurosquad-cards . Каждая запись фиксирует, что именно проверено:

название и описание карточки (на английском, русском и китайском), автор и лицензия;
где она лежит — репозиторий на GitHub owner/repo и, если нужно, папка внутри него;
проверенная версия, точный проверенный коммит и хеш дерева (tree hash) папки карточки на этом коммите;
разрешения и сетевые адреса, которыми карточка пользуется;
теги и категория — агенты, продуктивность, инструменты разработчика, данные, интеграции, развлечения или другое;
кто проверял, когда и заметки по итогам проверки.

Приложение скачивает список при запуске, каждые 6 часов и по кнопке Refresh. Без сети оно показывает последнюю скачанную копию, а на свежей установке — копию, которая поставляется вместе с приложением.

Найти и поставить проверенную карточку

Список есть в двух местах: вкладка Verified в окне Custom card… из меню добавления (+ на холсте или в сайдбаре) и раздел Verified cards в Settings → Custom cards.

Поиск идёт по названиям на всех трёх языках, описаниям и тегам — прямо на вашем компьютере. Можно также отфильтровать по категории. В каждой строке — иконка, название, описание, автор, категория и краткая сводка разрешений, а также кнопка: Install, Installed или Verified update.

Найдите карточку

Откройте вкладку Verified или раздел Verified cards, воспользуйтесь поиском или выберите категорию.

Нажмите Install

NeuroSquad скачивает ровно проверенный коммит — а не самый свежий код в репозитории — и сверяет хеш дерева файлов с проверенным. Если они не совпадают, установка отклоняется: «файлы отличаются от того, что проверяли».

Прочитайте диалог разрешений и подтвердите

Вы увидите тот же диалог установки, что и для любой другой карточки. Проверка не отменяет вашего согласия: получит ли карточка то, что просит, по-прежнему решаете вы.

Любую карточку по-прежнему можно поставить по её адресу на GitHub. Каталог лишь добавляет список карточек, которые кто-то уже посмотрел.

Значок Verified

У проверенной карточки есть значок Verified — щит с галочкой: в строке каталога, в диалоге установки, у установленной карточки в Settings → Custom cards и в панели About самой карточки.

Это не то же самое, что значок Official. Official значит, что карточку публикует команда NeuroSquad из своей организации glmn-ai на GitHub; Verified — что команда проверила эту версию. У карточки могут быть оба.

Значок показывается, только если с текущей записью списка совпадают все три пункта:

источник карточки — тот же репозиторий и та же папка;
коммит, с которого она установлена;
хеш дерева её файлов — равен проверенному.

Поэтому у карточки, подключённой из локальной папки, установленной с другого коммита (например, с последнего коммита ветки) или с отличающимися файлами, значка нет — даже если другая её версия проверена.

Verified значит: проверено командой NeuroSquad в версии X такого-то числа. Это не гарантия, что в карточке нет ошибок или что она навсегда останется безопасной, и ничего не говорит о других её версиях. Читайте диалог разрешений так же внимательно, как для любой другой карточки.

Проверенные обновления

Когда список указывает для карточки новую проверенную версию, в Settings → Custom cards у неё появляется Verified update available. Нажатие ставит ровно этот проверенный коммит через обычный диалог обновления, который показывает, что меняется в разрешениях карточки. Сами по себе обновления не ставятся никогда.

Если карточку убрали из списка, значок пропадает, а нейтральная пометка говорит, что её больше нет в списке проверенных. Карточка остаётся установленной и продолжает работать; оставлять ли её — решать вам.

На телефоне

При удалённом доступе список проверенных карточек можно листать на телефоне, но не ставить из него: установка возможна только на компьютере.

Авторам: как пройти проверку

Проверка — это pull request в glmn-ai/neurosquad-cards , который добавляет запись вашей карточки в verified.json. Точные правила и формат записи — в его CONTRIBUTING.md ; прочитайте его до того, как открывать pull request.

Опубликуйте карточку

Она должна лежать в открытом репозитории на GitHub, в ветке по умолчанию. См. Публикация и обновления.

Возьмите коммит и хеш дерева

Выберите точный коммит, который хотите отдать на проверку. Для хеша дерева запустите neurosquad-card pack на папке карточки на этом коммите — он печатает хеш дерева, который приложение записывает при установке.

Откройте pull request

Добавьте свою запись в verified.json — названия и описания, репозиторий и папку, версию, коммит, хеш дерева, разрешения, сетевые адреса, теги, категорию, лицензию, — как описано в CONTRIBUTING.md.

Обновление проверенной карточки — ещё один pull request, в котором поднимаются версия, коммит и хеш дерева. Каждая версия проверяется заново; пока новую не приняли, значок у пользователей остаётся на проверенной версии, а код, запушенный за это время, не предлагается как проверенное обновление.

Что смотрят при проверке

Весь исходный код на этом коммите. Никакого обфусцированного кода и никакого минифицированного кода без исходников.
Разрешения и сетевые адреса — минимум того, что нужно карточке, и совпадают с записью.
Описания её инструментов и портов честные.
Манифест совпадает с записью — название и версия.
Хеш дерева воспроизводится.
У карточки есть лицензия.
Она ставится и работает в текущей версии приложения.
Она не выдаёт себя за NeuroSquad или любой другой бренд.
Она не следит за пользователем сверх того, что объявила.

Большую часть этого покрывает чек-лист безопасности — пройдите его перед отправкой.