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

> Список карточек сообщества, которые просмотрела команда NeuroSquad, — где его найти, что значит значок Verified и чего он не значит, как устроены проверенные обновления и как автору отправить карточку на проверку.

Source: https://docs.neurosquad.ai/ru/card-sdk/verified-cards

Выложить [карточку сообщества](https://docs.neurosquad.ai/ru/card-sdk/community-cards) на GitHub может кто угодно, и до установки
её никто не проверяет. **Проверенные карточки** (verified) — исключение: это карточки сообщества,
которые команда NeuroSquad прочитала и опробовала, каждый раз — одну конкретную версию. Они собраны в
открытом каталоге, и приложение умеет ставить их прямо оттуда.

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

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

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

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

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

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

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

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

**2. Нажмите Install**

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

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

Вы увидите тот же [диалог установки](https://docs.neurosquad.ai/ru/card-sdk/community-cards#reading-the-install-dialog), что и
для любой другой карточки. Проверка не отменяет вашего согласия: получит ли карточка то, что
просит, по-прежнему решаете вы.

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

## Значок Verified

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

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

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

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

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

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

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

Когда список указывает для карточки новую проверенную версию, в **Settings → Custom cards** у неё
появляется **Verified update available**. Нажатие ставит ровно этот проверенный коммит через обычный
[диалог обновления](https://docs.neurosquad.ai/ru/card-sdk/community-cards#updates), который показывает, что меняется в разрешениях
карточки. Сами по себе обновления не ставятся никогда.

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

## На телефоне

При [удалённом доступе](https://docs.neurosquad.ai/ru/remote) список проверенных карточек можно листать на телефоне, но не ставить
из него: установка возможна только на компьютере.

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

Проверка — это pull request в
[glmn-ai/neurosquad-cards](https://github.com/glmn-ai/neurosquad-cards), который добавляет запись
вашей карточки в `verified.json`. Точные правила и формат записи — в его
[CONTRIBUTING.md](https://github.com/glmn-ai/neurosquad-cards/blob/HEAD/CONTRIBUTING.md); прочитайте
его до того, как открывать pull request.

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

Она должна лежать в **открытом** репозитории на GitHub, в **ветке по умолчанию**. См.
[Публикация и обновления](https://docs.neurosquad.ai/ru/card-sdk/publishing).

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

Выберите точный коммит, который хотите отдать на проверку. Для хеша дерева запустите
[`neurosquad-card pack`](https://docs.neurosquad.ai/ru/card-sdk/cli#pack) на папке карточки на этом коммите — он печатает хеш
дерева, который приложение записывает при установке.

**6. Откройте pull request**

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

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

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

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

Большую часть этого покрывает [чек-лист безопасности](https://docs.neurosquad.ai/ru/card-sdk/security) — пройдите его перед
отправкой.