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

Для всех

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

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

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

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

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

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

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

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

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

Код карточек работает только на компьютере; телефон показывает шапку и сводку. См. На телефоне.

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

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

Для авторов

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

Страница открыта вне приложения (во вкладке браузера): так и должно быть. Для превью используйте мок-хост, как это делают шаблоны.
Внутри приложения: SDK должен импортироваться входным скриптом, чтобы слушать ещё до окончания загрузки страницы. Ленивый import() SDK может пропустить рукопожатие приложения.

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

Карточки не могут выполнять встроенные скрипты и атрибуты onclick="…" и не могут загружать скрипты, стили, шрифты и картинки из интернета. Перенесите код в файлы .js, соберите зависимости в пакет, положите шрифты в пакет. npx @neurosquad/card-sdk validate укажет на проблемные места во входной странице. См. Правила песочницы.

С `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.

Ни у одной карточки ниже по стрелке нет совместимого входа. Проверьте направление стрелки (от вашей карточки к соседней), типы (см. Преобразование типов) и, для встроенных карточек, наличие cards.connected.

`NOT_VISIBLE`

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

`RATE_LIMITED`

Подождите error.retryAfterMs. Лимиты методов: внимание раз в 10 с, тосты раз в 2 с, изменение размера раз в 500 мс, буфер обмена раз в секунду, промпты 6 в минуту, команды 30 в минуту, сеть 120 в минуту, выходы портов 20 в секунду. См. Лимиты.

`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()). См. Правила песочницы.

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

Внимание, поднятое прежним запуском страницы, переживает перезагрузки и обновления. При запуске проверьте 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`.

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