# Вопросы и решение проблем

> Ответы для пользователей и авторов карточек и решения частых ошибок — карточка не подключается, скрипты заблокированы, после установки не хватает файлов, ошибки разрешений и стрелок, ограничения частоты.

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

## Для всех

### Безопасна ли карточка сообщества?

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

### Карточка просит ввести API-ключ прямо в ней. Вводить?

Нет. NeuroSquad никогда не спрашивает ключи внутри карточки. Хорошо сделанная карточка просит ключи
в своей форме **Settings…** (это собственная форма приложения), где они хранятся в зашифрованном виде
и никогда не показываются карточке. Всё, что вы вводите в тело карточки, уходит карточке.

### Почему карточка пишет «Paused to save memory»?

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

### Карточка пишет «Not responding».

Её код занят больше 15 секунд. Нажмите **Reload**. Если это повторяется, выключите карточку в
**Settings → Custom cards** и сообщите её автору. Больше ничего на холсте это не затрагивает.

### Почему нельзя пользоваться своей карточкой на телефоне?

Код карточек работает только на компьютере; телефон показывает шапку и сводку. См.
[На телефоне](https://docs.neurosquad.ai/ru/card-sdk/phone).

### При установке пишет, что GitHub ограничивает запросы.

GitHub ограничивает анонимные скачивания. Добавьте **GitHub token** в **Settings → Custom cards** — с
ним можно ставить и из приватных репозиториев.

## Для авторов

### `connect()` падает с `UNAVAILABLE`.

- **Страница открыта вне приложения** (во вкладке браузера): так и должно быть. Для превью
используйте [мок-хост](https://docs.neurosquad.ai/ru/card-sdk/testing), как это делают шаблоны.
- **Внутри приложения:** SDK должен импортироваться входным скриптом, чтобы слушать ещё до окончания
загрузки страницы. Ленивый `import()` SDK может пропустить рукопожатие приложения.

### Мой скрипт не запускается. В консоли — нарушение политики безопасности контента.

Карточки не могут выполнять встроенные скрипты и атрибуты `onclick="…"` и не могут загружать скрипты,
стили, шрифты и картинки из интернета. Перенесите код в файлы `.js`, соберите зависимости в пакет,
положите шрифты в пакет. `npx @neurosquad/card-sdk validate` укажет на проблемные места во входной
странице. См. [Правила песочницы](https://docs.neurosquad.ai/ru/card-sdk/styling#sandbox-rules-for-pages).

### С `dev` всё работает, а после установки с GitHub страница пустая или не хватает файлов.

Установленная карточка — это ровно то, что лежит в вашем репозитории на этом коммите. Обычно
результат сборки не закоммичен (`dist/` в `.gitignore`) или ресурсы указаны абсолютными путями
(`/assets/…`) вместо относительных (`./assets/…`; в Vite — `base: './'`). Запустите
`pack --dry-run`, чтобы увидеть, что получат пользователи.

### `validate` пишет, что файл «exists but would not be in the package (ignored by git?)».

Список файлов — это то, что git положил бы в архив GitHub: отслеживаемые файлы плюс
неотслеживаемые, но не игнорируемые. Закоммитьте файл или уберите его из игнорируемых. Так бывает
и когда папка карточки лежит внутри игнорируемой папки другого репозитория — перенесите её или
заведите для неё отдельный репозиторий.

### `PERMISSION_DENIED`

Разрешение не объявлено в манифесте, пользователь его отозвал, или оно необязательное и ещё не
выдано. Какое именно — в `error.permission`. Объявите его или попросите через
`card.permissions.request()`, пока карточка видна. Для подключённой папки изменение разрешений в
манифесте снова спросит вас.

### `NOT_CONNECTED`

Агент, терминал или карточка, к которой вы обращаетесь, не соединены с вашей карточкой стрелкой.
Попросите пользователя её провести — что подключено, говорят `card.ports.peers` и `agent.connected`.

### `emit` возвращает 0.

Ни у одной карточки ниже по стрелке нет совместимого входа. Проверьте направление стрелки (от вашей
карточки к соседней), типы (см. [Преобразование типов](https://docs.neurosquad.ai/ru/card-sdk/api/ports#conversion)) и, для
встроенных карточек, наличие `cards.connected`.

### `NOT_VISIBLE`

Диалогам, ссылкам, полёту камеры, запросам разрешений, форме настроек и промптам агентам в опасном
режиме нужно, чтобы карточка была на экране. Вызывайте их из действия пользователя или ждите, пока
`lifecycle.visibility` станет `visible`.

### `RATE_LIMITED`

Подождите `error.retryAfterMs`. Лимиты методов: внимание раз в 10 с, тосты раз в 2 с, изменение
размера раз в 500 мс, буфер обмена раз в секунду, промпты 6 в минуту, команды 30 в минуту, сеть 120
в минуту, выходы портов 20 в секунду. См. [Лимиты](https://docs.neurosquad.ai/ru/card-sdk/api/errors#limits).

### `HOST_NOT_ALLOWED`

Хоста из URL нет среди ваших хостов `network` (поддомен не совпадает с точным хостом — используйте
`*.example.com`), редирект увёл в другое место, или хост резолвится в частный адрес. Для `localhost`
объявите `network.local`.

### Мой инструмент не появляется у агента.

- Инструменты карточки видят только агенты, соединённые с ней стрелкой, и только агенты с MCP
(Claude Code, Codex, Qwen Code).
- Агенту может понадобиться новый ход, чтобы заметить изменившийся список инструментов.
- Проверьте имя: агенты видят `<card name with _>_<tool>`, например `test_radar_run_tests`.
- `card.tools.setEnabled(name, false)` скрывает инструмент у всех копий карточки.

### Где смотреть ошибки моей карточки?

Запустите `npx @neurosquad/card-sdk dev`: он транслирует `card.log.*`, необработанные ошибки и
отклонённые промисы. Приложение тоже хранит последние 256 КБ журнала каждого пакета.

### Может ли карточка работать в фоне?

Объявите разрешение `background`. Без него карточку, чей воркспейс скрыт минуту, усыпляют:
сохраняйтесь в `card.lifecycle.onSuspend` и восстанавливайтесь при `launch === 'resumed'`.

### Можно ли пользоваться `localStorage`, IndexedDB, cookies, WebSocket, `window.open`?

Нет — у песочницы нет источника (origin) для хранилища и нет всплывающих окон. Используйте
`card.storage`, `card.net.fetch` (потоковые ответы покрывают server-sent events; WebSocket в
версии 1 не поддерживается) и `card.openLink`.

### Может ли карточка читать буфер обмена, пользоваться камерой или микрофоном, выбрать файл?

Не в версии 1. Карточка может записать текст в буфер обмена (`clipboard.write`) и работать с файлами
в папке воркспейса (`fs.read`, `fs.write`).

### Есть ли галерея карточек?

Пока нет — карточками делятся по их адресу на GitHub.

### Форма ничего не перезагружает и никуда не отправляет.

Так и задумано: события `submit` срабатывают, но страница карточки никогда не уходит на другой адрес
и не отправляет форму. Обрабатывайте данные в обработчике `submit` (вызовите
`event.preventDefault()`). См. [Правила песочницы](https://docs.neurosquad.ai/ru/card-sdk/styling#sandbox-rules-for-pages).

### Карточка продолжает пульсировать после перезагрузки.

Внимание, поднятое прежним запуском страницы, переживает перезагрузки и обновления. При запуске
проверьте `card.context.chrome?.attention` и снимите его через `card.attention('none')`, когда
причины больше нет.

### В пакете нет `dist/`, хотя я его собрал.

`.gitignore` родительского репозитория может игнорировать `dist`. Добавьте `!dist/` в `.gitignore`
карточки (в шаблоне React это уже сделано) и проверьте через `pack --dry-run`.

### Кнопка «копировать» ничего не делает.

Страница не может писать в буфер обмена через события `copy` или `execCommand`. Объявите
`clipboard.write` (можно необязательным) и вызывайте `card.copyText(text)`.

### `new Worker('worker.js')` не работает.

В карточке работают только blob-воркеры: скачайте скрипт, сделайте из него `Blob` и запустите
воркер из `URL.createObjectURL(blob)`.

### Установка карточки отклонена: «only official cards may call themselves…».

Карточки, опубликованные не из официальной организации, не могут использовать «NeuroSquad»,
«official» или «verified» в имени или авторе. Переименуйте карточку.

### Запись отклоняется с `FS_DENIED`, хотя у меня есть `fs.write`.

Путь [защищён](https://docs.neurosquad.ai/ru/card-sdk/api/files#protected) (`.git`, настройки агентов, CI-процессы, настройки
пакетных менеджеров), или воркспейс — это домашняя папка или корень диска, где у карточек нет доступа
к файлам.