Skip to Content
Card SDKБыстрый старт

Быстрый старт

Нужны NeuroSquad и Node.js 18.17 или новее. Никакого аккаунта разработчика; для простого шаблона — никаких инструментов сборки.

1. Создайте карточку

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

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

Простой шаблон (vanilla):

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. Посмотрите без приложения

Откройте страницу саму по себе — она заработает на мок-хосте с примерами агентов и подключённой заметкой, так что над внешним видом можно работать в любом браузере:

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'). См. Тесты с мок-хостом.

3. Запустите её вживую в NeuroSquad

Включите режим разработчика

В NeuroSquad: Settings → Custom cards → Developer mode. Он позволяет CLI на этом компьютере попросить подключить папку; слушает только 127.0.0.1.

Подключите папку

В папке карточки выполните npx @neurosquad/card-sdk dev. Приложение попросит подтвердить подключение, а потом покажет тот же диалог разрешений, что увидит пользователь. Примите его.

Добавьте карточку

На холсте: + → Custom card… и выберите свою карточку (у неё значок Dev).

Правьте и сохраняйте

Каждое сохранение перезагружает карточку. Терминал, где запущен dev, печатает журнал карточки — card.log.*, необработанные ошибки и отклонённые промисы. r — перезагрузить вручную, q — выйти.

С шаблоном React dev ещё и запускает за вас npm run watch, так что dist/ пересобирается при каждом сохранении. Передайте --no-build, чтобы запускать свой наблюдатель.

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

Без CLI. Кнопка Settings → Custom cards → Link a folder… тоже подключает папку — удобно, если вы просто хотите попробовать карточку, которую вам прислали папкой.

4. Проверьте её так, как проверит установщик

npx @neurosquad/card-sdk validate

validate прогоняет собственные проверки манифеста из приложения и правила установщика для файлов, предупреждает о том, что заблокирует песочница (встроенные скрипты, внешние файлы), и печатает диалог установки, который увидят ваши пользователи. pack идёт на шаг дальше и перечисляет, какие именно файлы будут установлены, вместе с хешем дерева, который записывает приложение. См. Справочник CLI.

5. Опубликуйте на GitHub

Запушьте папку карточки в репозиторий на GitHub — в отдельный или в папку внутри большого. Это и есть вся публикация. Важно не ошибиться в нескольких вещах:

  • neurosquad-card.json должен лежать в корне папки карточки.
  • Коммитьте результат сборки. Приложение ставит прямо из репозитория и никогда ничего не собирает. В .gitignore шаблона React папка dist/ намеренно не игнорируется.
  • Ставьте теги на релизы (v1.0.0) — тогда можно установить фиксированную версию или следить за последним релизом.

Подробнее — в Публикации и обновлениях.

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. Именно так делают ваши пользователи; см. Установку карточек сообщества.

Самая маленькая карточка

Шаблон не нужен. Три файла:

neurosquad-card.json
{
  "manifestVersion": 1,
  "name": "hello-card",
  "displayName": "Hello",
  "version": "0.1.0",
  "protocol": 1
}
index.html
<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <script type="module" src="main.js"></script>
  </head>
  <body>
    <h1 id="title">…</h1>
  </body>
</html>
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' })

Она не просит разрешений, поэтому может только рисовать в своей коробке, пользоваться хранилищем и настройками и менять свою шапку — и это уже полезная карточка.

Дальше

Справочник по манифесту
Размер, разрешения, настройки, порты, инструменты.
Справочник API
Что умеет card.*.
Чек-лист безопасности
Прежде чем делиться.
Проверенные карточкиСправочник по манифесту