# Быстрый старт
> Создайте карточку из шаблона, запустите её вживую в NeuroSquad с горячей перезагрузкой, опубликуйте на GitHub и установите оттуда.
Source: https://docs.neurosquad.ai/ru/card-sdk/quick-start
Нужны NeuroSquad и Node.js 18.17 или новее. Никакого аккаунта разработчика; для простого шаблона — никаких
инструментов сборки.
## 1. Создайте карточку
```bash
npx @neurosquad/card-sdk create my-card # plain HTML + JS, no build step
npx @neurosquad/card-sdk create my-card --template react # React + Vite + TypeScript
```
Оба шаблона дают одну и ту же рабочую карточку: агенты на холсте с живыми статусами, черновик,
который сохраняется в хранилище карточки, входной и выходной [порт](https://docs.neurosquad.ai/ru/card-sdk/api/ports) и
[инструмент](https://docs.neurosquad.ai/ru/card-sdk/api/tools), который могут вызывать подключённые агенты. Прочитайте её, потом
меняйте.
**Простой шаблон** (`vanilla`):
```text
my-card/
neurosquad-card.json the manifest: name, size, permissions, settings, ports, tools
index.html the page loaded into the card
main.js the card's code
style.css
icon.png square PNG or WebP, 128 KB at most
vendor/ the SDK (card-sdk.js), the UI kit (ui.css), the mock host, the manifest schema
```
**Шаблон React**: тот же манифест и иконка, папка `src/` с `main.tsx`, `App.tsx` и `i18n.ts` и
конфиг Vite, уже настроенный под карточки (относительные URL, никаких встроенных скриптов). Сначала
выполните `npm install`; `npm run build` пишет `dist/` — именно его загружает приложение.
## 2. Посмотрите без приложения
Откройте страницу саму по себе — она заработает на **мок-хосте** с примерами агентов и подключённой
заметкой, так что над внешним видом можно работать в любом браузере:
```bash
npx serve . # plain template, then open http://localhost:3000
npm run dev # React template
```
В консоли браузера им управляет `mockHost`: `mockHost.setAgentStatus('a2', 'working')`,
`mockHost.setLanguage('ru')`, `mockHost.sendPortMessage('text', 'hello')`. См.
[Тесты с мок-хостом](https://docs.neurosquad.ai/ru/card-sdk/testing).
## 3. Запустите её вживую в NeuroSquad
**1. Включите режим разработчика**
В NeuroSquad: **Settings → Custom cards → Developer mode**. Он позволяет CLI на этом компьютере
попросить подключить папку; слушает только `127.0.0.1`.
**2. Подключите папку**
В папке карточки выполните `npx @neurosquad/card-sdk dev`. Приложение попросит подтвердить
подключение, а потом покажет тот же диалог разрешений, что увидит пользователь. Примите его.
**3. Добавьте карточку**
На холсте: **+ → Custom card…** и выберите свою карточку (у неё значок **Dev**).
**4. Правьте и сохраняйте**
Каждое сохранение перезагружает карточку. Терминал, где запущен `dev`, печатает журнал карточки —
`card.log.*`, необработанные ошибки и отклонённые промисы. **r** — перезагрузить вручную, **q** —
выйти.
С шаблоном React `dev` ещё и запускает за вас `npm run watch`, так что `dist/` пересобирается при
каждом сохранении. Передайте `--no-build`, чтобы запускать свой наблюдатель.
> Режим разработчика — не обход согласия: подключённая папка получает ровно те разрешения, что
> объявлены в её манифесте, и только после того же диалога. Поменяете разрешения в манифесте —
> карточка спросит снова.
**Без CLI.** Кнопка **Settings → Custom cards → Link a folder…** тоже подключает папку — удобно,
если вы просто хотите попробовать карточку, которую вам прислали папкой.
## 4. Проверьте её так, как проверит установщик
```bash
npx @neurosquad/card-sdk validate
```
`validate` прогоняет собственные проверки манифеста из приложения и правила установщика для файлов,
предупреждает о том, что заблокирует песочница (встроенные скрипты, внешние файлы), и печатает диалог
установки, который увидят ваши пользователи. `pack` идёт на шаг дальше и перечисляет, какие именно
файлы будут установлены, вместе с **хешем дерева**, который записывает приложение. См.
[Справочник CLI](https://docs.neurosquad.ai/ru/card-sdk/cli).
## 5. Опубликуйте на GitHub
Запушьте папку карточки в репозиторий на GitHub — в отдельный или в папку внутри большого. Это и есть
вся публикация. Важно не ошибиться в нескольких вещах:
- `neurosquad-card.json` должен лежать в корне папки карточки.
- **Коммитьте результат сборки.** Приложение ставит прямо из репозитория и никогда ничего не
собирает. В `.gitignore` шаблона React папка `dist/` намеренно не игнорируется.
- Ставьте теги на релизы (`v1.0.0`) — тогда можно установить фиксированную версию или следить за
последним релизом.
Подробнее — в [Публикации и обновлениях](https://docs.neurosquad.ai/ru/card-sdk/publishing).
## 6. Установите её с GitHub
В **Settings → Custom cards → Install a card** вставьте `your-name/my-card` (или
`your-name/my-cards/pomodoro` для карточки из папки `pomodoro` репозитория, `your-name/my-card@v1.0.0`
для тега) и нажмите **Install**. Именно так делают ваши пользователи; см.
[Установку карточек сообщества](https://docs.neurosquad.ai/ru/card-sdk/community-cards).
## Самая маленькая карточка
Шаблон не нужен. Три файла:
```json filename="neurosquad-card.json"
{
"manifestVersion": 1,
"name": "hello-card",
"displayName": "Hello",
"version": "0.1.0",
"protocol": 1
}
```
```html filename="index.html"
…
```
```js filename="main.js"
// card-sdk.js is dist/card-sdk.js from the @neurosquad/card-sdk package, copied next to this file.
import { connect } from './card-sdk.js'
const card = await connect()
document.getElementById('title').textContent = `Hello from ${card.workspace.name}`
card.setStatus('Ready', { tone: 'success' })
```
Она не просит разрешений, поэтому может только рисовать в своей коробке, пользоваться хранилищем и
настройками и менять свою шапку — и это уже полезная карточка.
## Дальше
- **[Справочник по манифесту](https://docs.neurosquad.ai/ru/card-sdk/manifest)**: Размер, разрешения, настройки, порты, инструменты.
- **[Справочник API](https://docs.neurosquad.ai/ru/card-sdk/api)**: Что умеет `card.*`.
- **[Чек-лист безопасности](https://docs.neurosquad.ai/ru/card-sdk/security)**: Прежде чем делиться.