# Card SDK

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

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

**Своя карточка** — это небольшое веб-приложение, которое живёт на холсте рядом с вашими агентами,
терминалами и заметками. Сделать такую может кто угодно с помощью Card SDK (`@neurosquad/card-sdk`),
выложить на GitHub — а любой другой поставит её, вставив в NeuroSquad адрес `owner/repo`.

Этот раздел для двух читателей:

- **Для всех**, кто хочет пользоваться карточкой, сделанной кем-то другим, — начните с
[Установки карточек сообщества](https://docs.neurosquad.ai/ru/card-sdk/community-cards). Там объяснено, что карточка может и
чего не может, что говорит диалог установки и как забрать доступ обратно.
- **Для разработчиков**, которые хотят сделать свою, — начните с [Быстрого старта](https://docs.neurosquad.ai/ru/card-sdk/quick-start):
рабочая карточка на вашем холсте за несколько минут.

## Что умеет карточка

Своя карточка — полноправный житель холста: у неё такая же шапка, она меняет размер, входит в
[группы](https://docs.neurosquad.ai/ru/canvas/groups), принимает [стрелки](https://docs.neurosquad.ai/ru/canvas/arrows), показывает плитку при отдалении и
лежит в сайдбаре, как любая другая карточка. Внутри своей коробки она рисует что угодно. Через SDK
она может:

  - **Следить за агентами**: Кто работает, кто ждёт вас, когда ход начался и закончился — а если вы её подключите, то и что агент выводит на экран.
  - **Давать указания агентам**: Отправить промпт агенту, к которому вы её подключили. Пока агент работает, промпты встают в очередь и учитывают бюджет воркспейса.
  - **Общаться с другими карточками**: Типизированные порты по стрелкам: карточка может дописать заметку, добавить задачи в список или передать данные другой своей карточке.
  - **Давать агентам инструменты**: Объявите инструмент и реализуйте его в карточке — подключённые агенты вызовут его через MCP-сервер приложения.
  - **Ходить в интернет**: Запросы к объявленным хостам — через прокси приложения и с секретами, которых карточка никогда не видит.
  - **Работать с файлами проекта**: Читать и писать файлы в папке воркспейса, если вы разрешите.
  - **Запускать команды**: Выполнить команду в подключённом терминале и получить код выхода и вывод.
  - **Настройки и хранилище**: Форма настроек, которую рисует приложение, хранилище карточки, переживающее перезапуски, тема и язык приложения.

## Карточки никогда не покидают холст

Коду сообщества не доверяют по умолчанию, поэтому карточка работает **запертой в своей коробке**:

- Она работает в отдельном изолированном процессе. Зависшая или упавшая карточка не может
заморозить холст или утянуть что-то за собой.
- Сама по себе она не может добраться ни до приложения, ни до ваших других карточек, ни до Node.js,
ваших файлов, cookies или интернета. Всё идёт через SDK, и приложение сверяет каждый запрос с тем,
что вы разрешили.
- Она не может открывать окна и всплывающие окна, уходить в полноэкранный режим, показывать
системные диалоги, присылать уведомления ОС, скачивать файлы или уводить приложение на другую
страницу. Она рисует только внутри своей карточки.
- Когда от вас нужно решение — подтверждение, ссылка, разрешение, промпт агенту в опасном режиме,
секрет вроде API-ключа, — спрашивает **приложение**, в своём собственном диалоге, который
**затемняет всё окно**, включая сайдбар и заголовок. Карточка не может рисовать за пределами своей
коробки, поэтому подделать такой диалог ей не удастся. Всё, что внутри тела карточки, принадлежит
самой карточке: NeuroSquad никогда не спрашивает там ключи.

## Модель безопасности простыми словами

  - **Что ей можно — решаете вы**: Карточка перечисляет нужные ей [разрешения](https://docs.neurosquad.ai/ru/card-sdk/permissions). Вы видите их — сначала самые рискованные — ещё до установки. Карточка без разрешений может только рисовать в своей коробке.
  - **Стрелка — это согласие**: Всё, что доходит до другой карточки или агента, — данные через порт, промпт, команда, чтение экрана, — требует стрелки между двумя карточками **и** соответствующего разрешения. Нет стрелки — нет данных.
  - **Привязка к коммиту**: Установка — это этот репозиторий на этом конкретном коммите, причём коммите самого репозитория, а не форка. За вашей спиной ничего не меняется: обновления никогда не ставятся сами, а обновление, которому нужно больше доступа или которое меняет то, что карточка даёт агентам, спрашивает вас снова.
  - **Секреты остаются в приложении**: API-ключи вводятся только в собственном диалоге приложения, хранятся в зашифрованном виде, и приложение само подставляет их в запросы к тем адресам в интернете, которые вы разрешили. Сама карточка их никогда не видит.
  - **Некоторые файлы недоступны**: Даже с доступом к файлам карточка никогда не может менять `.git`, настройки и инструкции ваших агентов (`.claude/`, `.mcp.json`, `CLAUDE.md`, `AGENTS.md`…) и CI-процессы — а если воркспейс — это ваша домашняя папка или целый диск, доступа к файлам у неё нет вообще.
  - **Всё на виду**: Промпт или вызов инструмента через карточку подсвечивает стрелку, по которой он прошёл, и попадает в [журнал стрелки](https://docs.neurosquad.ai/ru/canvas/arrows#arrow-log) с именем карточки.

> Карточки сообщества не делает и не проверяет команда NeuroSquad. Ставьте карточки от тех, кому
> доверяете, и читайте список разрешений: карточка, которой можно давать указания агентам или
> запускать команды, может всё, что могут эти агенты и терминалы.

## В этом разделе

  - **[Установка карточек сообщества](https://docs.neurosquad.ai/ru/card-sdk/community-cards)**: Для пользователей: установить, проверить, отозвать, обновить и удалить.
  - **[Быстрый старт](https://docs.neurosquad.ai/ru/card-sdk/quick-start)**: От пустой папки до карточки на холсте и на GitHub.
  - **[Справочник по манифесту](https://docs.neurosquad.ai/ru/card-sdk/manifest)**: Каждое поле `neurosquad-card.json`.
  - **[Разрешения](https://docs.neurosquad.ai/ru/card-sdk/permissions)**: Каждое: что видит пользователь, что оно открывает.
  - **[Справочник API](https://docs.neurosquad.ai/ru/card-sdk/api)**: Все методы и события, с типами и примерами.
  - **[React-привязки](https://docs.neurosquad.ai/ru/card-sdk/react)**: `CardProvider` и хуки.
  - **[UI-кит и оформление](https://docs.neurosquad.ai/ru/card-sdk/styling)**: Выглядеть как родная — или по-своему.
  - **[Тесты](https://docs.neurosquad.ai/ru/card-sdk/testing)**: Хост в памяти для тестов и превью в браузере.
  - **[Справочник CLI](https://docs.neurosquad.ai/ru/card-sdk/cli)**: `create`, `dev`, `validate`, `pack`.
  - **[Публикация и обновления](https://docs.neurosquad.ai/ru/card-sdk/publishing)**: GitHub, версии, что видят пользователи при обновлении.
  - **[Чек-лист безопасности](https://docs.neurosquad.ai/ru/card-sdk/security)**: Что проверить, прежде чем делиться карточкой.
  - **[Вопросы и решение проблем](https://docs.neurosquad.ai/ru/card-sdk/faq)**: Частые ошибки и как их исправить.
  - **[Список изменений](https://docs.neurosquad.ai/ru/card-sdk/changelog)**: Что изменилось в каждой версии SDK и какая версия NeuroSquad ей нужна.

> Card SDK — новинка. Всё здесь описывает версию 1 протокола карточек; кое-что сознательно отложено
> на потом — галерея карточек, автоматические обновления, карточки, работающие вовсе без страницы,
> выбор файла и запуск кода карточек на телефоне. Об этом сказано там, где это важно.