# Разрешения

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

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

Карточка без разрешений может рисовать в своей коробке, пользоваться [хранилищем](https://docs.neurosquad.ai/ru/card-sdk/api/storage-settings),
читать свои настройки, менять свою шапку — и ни с кем ничем не обмениваться. Всё остальное — это
разрешения, которые вы объявляете в [манифесте](https://docs.neurosquad.ai/ru/card-sdk/manifest#permissions), а пользователь
выдаёт.

Как это устроено:

- **На пакет, с проверкой на каждый запрос.** Пользователь выдаёт разрешение вашему пакету
карточки (всем её копиям на всех холстах). Приложение проверяет выдачу при каждом вызове, внутри
приложения — не в SDK и не в вашей карточке.
- **Обязательные — целиком при установке.** Диалог установки перечисляет их, начиная с самых
рискованных. Отказаться — значит не устанавливать.
- **Необязательные — во время работы** (`"optional": true`). Вызовите
[`card.permissions.request()`](https://docs.neurosquad.ai/ru/card-sdk/api/environment#permissions), пока карточка на экране;
приложение спросит в своём диалоге на всё окно, и пользователь может отказать.
- **Одни включают другие.** `fs.write` включает `fs.read`; `agents.output`, `agents.prompt` и
`terminals.write` включают `agents.read`.
- **Пользователь может отозвать** любое разрешение в **Settings → Custom cards**. Страницы карточки
перезагружаются с урезанными правами и получают событие `permissions.changed`; пишите код с
расчётом на это.
- **Обновление, добавляющее разрешения или сетевые хосты,** применяется только после согласия
пользователя. Разрешения, которые вы убрали, отзываются.
- **Стрелка — согласие на данные.** Разрешения, которые затрагивают другую карточку, агента или
терминал, работают только с карточками, соединёнными с вашей [стрелкой](https://docs.neurosquad.ai/ru/canvas/arrows), — в любом
направлении, если не сказано иное.

Если разрешения нет, вызов падает с `PERMISSION_DENIED` (`error.permission` называет какое).

## Коротко

| Разрешение | Риск | Открывает |
| --- | --- | --- |
| `agents.read` | Низкий | `agents.list/get`, события статуса, ходов и изменений, порт агента `status` |
| `agents.output` | Высокий | Чтение экранов и ответов **подключённых** агентов и терминалов |
| `agents.prompt` | Высокий | Отправку промптов **подключённым** ИИ-агентам |
| `terminals.write` | Высокий | Запуск команд в **подключённых** терминалах |
| `cards.connected` | Средний | Чтение и изменение **подключённых** заметок, списков задач, досок задач, стикеров |
| `network` + хосты | Средний | `net.fetch` к перечисленным хостам |
| `network.local` | Высокий | `net.fetch` к серверам на этом компьютере |
| `fs.read` | Высокий | Чтение файлов в папке воркспейса |
| `fs.write` | Высокий | Запись файлов в папке воркспейса (включает `fs.read`) |
| `clipboard.write` | Низкий | Копирование текста в буфер обмена |
| `canvas.spawn` | Низкий | Добавление до 4 карточек рядом с собой |
| `background` | Низкий | Работу, пока никто не смотрит |
| `usage.read` | Низкий | Расход токенов и стоимость воркспейса |

## Каждое разрешение

### `agents.read` — низкий

**Пользователь видит:** *See the agents on this canvas* — «Видеть агентов на этом холсте. Их имена,
какой инструмент у каждого и работает ли он, ждёт вас или закончил».

**Открывает:** [`card.agents.list()` / `get()`](https://docs.neurosquad.ai/ru/card-sdk/api/agents), события `agents.status`,
`agents.turn`, `agents.changed` и встроенный выходной порт агента `status`.

**Границы:** ИИ-агенты и терминалы воркспейса самой карточки. Другие карточки — не агенты и в
список не попадают.

### `agents.output` — высокий

**Пользователь видит:** *Read what agents and terminals connected to it print* — «Читать вывод
подключённых к ней агентов и терминалов. Всё, что на экранах карточек агентов и терминалов,
соединённых с ней стрелкой, включая показанные там секреты».

**Открывает:** `card.agents.readScreen()`, `card.agents.lastReply()`, живой вывод через
`card.agents.onOutput()`, выходные порты агента `reply` и терминала `exit`.

**Границы:** только агенты и терминалы, подключённые стрелкой. Включает `agents.read`.

### `agents.prompt` — высокий

**Пользователь видит:** *Give instructions to agents connected to it* — «Давать указания
подключённым к ней агентам. Набирать и отправлять промпты ИИ-агентам, соединённым с ней стрелкой.
Агент может править файлы и запускать команды, значит, карточка может заставить его сделать всё,
что умеет агент».

**Открывает:** [`card.agents.prompt()`](https://docs.neurosquad.ai/ru/card-sdk/api/agents#prompting) и входной порт агента `prompt`.

**Границы:** подключённые стрелкой **ИИ**-агенты (не терминалы). Промпты идут через очередь промптов
и [бюджет](https://docs.neurosquad.ai/ru/cards/budget) воркспейса, не больше 6 в минуту на карточку (метод и входной порт агента
`prompt` считаются вместе); каждый виден на стрелке и в журнале стрелки. Агенту в
[опасном режиме](https://docs.neurosquad.ai/ru/agents/dangerous-mode) каждый промпт отправляется только после согласия
пользователя на карточке. Включает `agents.read`.

### `terminals.write` — высокий

**Пользователь видит:** *Run commands in terminals connected to it* — «Запускать команды в
подключённых к ней терминалах. Набирать и выполнять команды в карточках терминалов, соединённых с
ней стрелкой, — всё, что могли бы запустить вы сами».

**Открывает:** [`card.terminals.run()` и `write()`](https://docs.neurosquad.ai/ru/card-sdk/api/agents#terminals), входной порт
терминала `command`.

**Границы:** карточки терминалов (bash, PowerShell, cmd), подключённые стрелкой. Не больше 30 команд
в минуту на карточку — `run` и порт терминала `command` считаются вместе; `write` — не больше 60 в
минуту. Каждая команда видна на стрелке. Включает `agents.read`.

### `cards.connected` — средний

**Пользователь видит:** *Read and change cards connected to it* — «Читать и менять подключённые к
ней карточки. Заметки, чек-листы, доски задач и стикеры, соединённые с ней стрелкой».

**Открывает:** [порты встроенных карточек](https://docs.neurosquad.ai/ru/card-sdk/api/ports#built-in-cards) — заметки, списка
задач, доски задач и стикера: дописать заметку, добавить задачи, прочитать список.

**Границы:** карточки этих четырёх видов, подключённые стрелкой.

### `network` — средний, нужны `hosts`

**Пользователь видит:** *Connect to `api.github.com`, `*.example.com`* — «Подключаться к …
Отправлять и получать данные только с этих адресов в интернете. Туда может уйти всё, что видит
карточка».

**Открывает:** [`card.net.fetch()`](https://docs.neurosquad.ai/ru/card-sdk/api/network) к этим хостам по `https`.

**Границы:** ровно объявленные шаблоны хостов и только публичные адреса — хост, который резолвится
в частный, локальный или адрес облачных метаданных, отклоняется, и при каждом редиректе тоже.
Попросить «любой хост» в версии 1 нельзя.

### `network.local` — высокий

**Пользователь видит:** *Connect to servers on this computer* — «Подключаться к серверам на этом
компьютере. Обращаться к программам на localhost, например дев-серверам и локальным базам данных».

**Открывает:** `card.net.fetch()` к `localhost`, `127.0.0.1` и `::1`, по `http` или `https`.

**Границы:** любой порт, кроме собственных серверов NeuroSquad: его MCP-сервера, сервера удалённого
доступа, сервера подключения папок для разработчиков, порта отладки Chrome каждой браузерной
карточки и дев-сервера самого приложения. [Подстановки секретов](https://docs.neurosquad.ai/ru/card-sdk/api/network#secrets) в
запросах к этому компьютеру никогда не заполняются.

### `fs.read` — высокий

**Пользователь видит:** *Read files in the workspace folder* — «Читать файлы в папке воркспейса.
Любой файл в папке проекта этого воркспейса, включая секреты в файлах вроде `.env`».

**Открывает:** [`card.fs.stat/list/read*/watch()`](https://docs.neurosquad.ai/ru/card-sdk/api/files) и абсолютный путь `path`
воркспейса в `card.workspace`.

**Границы:** папка воркспейса. Пути задаются относительно неё; `..` и абсолютные пути отклоняются,
ссылка, ведущая наружу, — тоже. Если папка воркспейса — это домашняя папка пользователя, корень диска
или в ней лежит папка данных самого NeuroSquad, отклоняется любой вызов к файлам.

### `fs.write` — высокий

**Пользователь видит:** *Change files in the workspace folder* — «Менять файлы в папке воркспейса.
Создавать, перезаписывать и переносить в корзину файлы в папке проекта этого воркспейса. Агенты
воркспейса читают и запускают эти файлы, поэтому карточка может заставить их выполнять команды.
Защищены: `.git`, настройки агентов (`.claude`, `.mcp.json`, `CLAUDE.md`, `AGENTS.md` и подобные) и
данные самого NeuroSquad».

**Открывает:** `card.fs.writeText/writeBytes/mkdir/trash()`.

**Границы:** как у `fs.read`, за вычетом [защищённых путей](https://docs.neurosquad.ai/ru/card-sdk/api/files#protected): любой
`.git`, настройки агентов и редакторов, CI-процессы. Безвозвратного удаления нет — `trash` переносит
в корзину ОС. Включает `fs.read`.

### `clipboard.write` — низкий

**Пользователь видит:** *Copy to your clipboard* — «Копировать в буфер обмена. Заменять содержимое
буфера обмена текстом из карточки».

**Открывает:** [`card.copyText()`](https://docs.neurosquad.ai/ru/card-sdk/api/files#clipboard), не чаще раза в секунду. Читать
буфер обмена нельзя.

### `canvas.spawn` — низкий

**Пользователь видит:** *Add cards next to itself* — «Добавлять карточки рядом с собой. Ставить на
холст до 4 новых карточек рядом с собой».

**Открывает:** [`card.spawn()`](https://docs.neurosquad.ai/ru/card-sdk/api/card-ui#spawn) — ещё одну копию вашей карточки или
заметку, список задач, доску задач, стикер, соединённые с ней стрелкой.

**Границы:** 4 карточки на карточку, 4 в минуту, в пределах лимита карточек воркспейса.

### `background` — низкий

**Пользователь видит:** *Keep running when you are not looking* — «Работать, когда вы не смотрите.
Оставаться активной, пока её воркспейс скрыт. Тратит больше памяти и батареи».

**Открывает:** карточку не [усыпляют](https://docs.neurosquad.ai/ru/card-sdk/api/environment#lifecycle), когда она скрыта.

**Границы:** в фоне во всём приложении работает не больше 8 таких карточек; сверх этого те, что
давно не показывались, всё равно усыпляются.

### `usage.read` — низкий

**Пользователь видит:** *See token usage and costs* — «Видеть расход токенов и стоимость. Сколько
токенов потратили агенты этого воркспейса и сколько это стоило».

**Открывает:** [`card.usage()`](https://docs.neurosquad.ai/ru/card-sdk/api/files#usage) и [`card.agents.usage()`](https://docs.neurosquad.ai/ru/card-sdk/api/agents#usage) для агентов, подключённых стрелкой.

**Границы:** воркспейс самой карточки.

## Что ещё перечисляет диалог установки

Выводится из манифеста, а не из разрешений: имена [инструментов](https://docs.neurosquad.ai/ru/card-sdk/api/tools), которые
карточка даёт подключённым агентам, и сколько у неё входных и выходных портов. Необязательные
разрешения показываются под **It may ask later for**.

> Просите минимум. Каждая строка высокого риска заставляет осторожного пользователя задуматься, а
> отсутствие `reason` — гадать. Если сильное разрешение нужно лишь иногда, сделайте его
> необязательным и попросите, когда пользователь дойдёт до этой функции.