# Список изменений Card SDK

> Что менялось в @neurosquad/card-sdk и контракте карточек от версии к версии — новые API, нужная версия NeuroSquad, разрешения и как перейти.

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

Изменения `@neurosquad/card-sdk` и контракта карточек, на котором он говорит, — новые сверху. Тот же
список лежит в пакете как `CHANGELOG.md`.

Автору карточки важны три версии:

- **Версия SDK / контракта** (`SDK_VERSION`) — заголовки ниже. Новые методы и события появляются в
минорных версиях.
- **Протокол** (`CARD_PROTOCOL_VERSION`, по-прежнему **1**) — карточку, собранную под более новый
протокол, старое приложение отклоняет с `PROTOCOL_MISMATCH`.
- **Версия NeuroSquad** — хост. Перед вызовом нового метода проверяйте `card.host.supports('<метод>')`
или задайте [`minAppVersion`](https://docs.neurosquad.ai/ru/card-sdk/manifest), если карточка без него не работает.

Версии NeuroSquad ниже — первый публичный релиз, в котором есть изменение.

## Ещё не выпущено

**Изменение хоста, NeuroSquad 0.1.264.** Карточка, чей процесс страницы падает сам — обычно когда на
компьютере кончается память, — автоматически перезагружается, а не остаётся серым прямоугольником;
новая страница стартует с `launch: 'reloaded'`. После трёх таких перезагрузок за 10 минут карточка
показывает *Карточка перестала работать* с кнопкой **Reload**. Менять в карточке ничего не нужно;
то, что должно пережить перезагрузку, держите в [хранилище](https://docs.neurosquad.ai/ru/card-sdk/api/storage-settings).

## 1.2.0 — 2026-10-04

Нужен NeuroSquad **0.1.264** или новее.

**Добавлено**

- [`card.agents.timeline(agentId, since, until?)`](https://docs.neurosquad.ai/ru/card-sdk/api/agents#timeline): запросы к модели
одного ИИ-агента, подключённого стрелкой (время завершения; время отправки — там, где журнал агента
его пишет; токены; вызовы инструментов), его статус непрерывными отрезками и его ходы — то, что
рисует официальная карточка [Agent Pulse](https://docs.neurosquad.ai/ru/cards/agent-pulse). `requestTimes` — `start-end`, `end`
или `none`; не больше 2000 запросов (самые новые, с `truncated`).
- Типы `AgentTimeline`, `AgentRequestSpan`, `AgentTurnSpan`.
- [Mock host](https://docs.neurosquad.ai/ru/card-sdk/testing): параметр `agentTimeline` и `setAgentTimeline()`.

**Совместимость.** Те же разрешение и область, что у `agents.usage`, —
[`usage.read`](https://docs.neurosquad.ai/ru/card-sdk/permissions#usage-read) и стрелка к ИИ-агенту; нового разрешения нет. 60
вызовов в минуту на карточку. Старое приложение отвечает `METHOD_NOT_FOUND`: проверяйте
`card.host.supports('agents.timeline')`.

## 1.1.0 — 2026-10-04

Нужен NeuroSquad **0.1.264** или новее.

**Добавлено**

- [`card.agents.usage(agentId, since, until?)`](https://docs.neurosquad.ai/ru/card-sdk/api/agents#usage): прогон одного ИИ-агента,
подключённого стрелкой, в окне времени — запросы к модели, токены по видам, промпты, время работы и
общее время, стоимость (с округлением вверх, с `costPartial`), модель и провайдер. То, что
показывает официальная карточка [Run Stats](https://docs.neurosquad.ai/ru/cards/run-stats). Время берётся из собственной истории
статусов приложения, поэтому оно верно, даже пока карточка стояла на паузе.
- Тип `AgentUsage`.
- [Mock host](https://docs.neurosquad.ai/ru/card-sdk/testing): параметр `agentUsage` и `setAgentUsage()`.
- Типы контракта для каталога [проверенных карточек](https://docs.neurosquad.ai/ru/card-sdk/verified-cards) (`VerifiedCatalog`,
`VerifiedEntry`, `validateVerifiedCatalog` и другие) — в пакете впервые после 1.0.0.

**Поведение**

- Несообщённое число токенов — `null`, а не `0`: числа нет в журнале агента, у CLI агента нет
читаемого журнала расхода (Amp, Cursor: `usageReadable: false`), нулевой счётчик кеша от
собственного сервера моделей пользователя, нулевая запись в кеш вне Anthropic API. Показывайте «не
сообщается».
- У модели без известной цены — в том числе модели на собственном сервере пользователя —
`costMicroUsd: null`, а не 0.
- `prompts` не считает завершённый ход без единого запроса к модели (мигание статуса).

**Совместимость.** Разрешение [`usage.read`](https://docs.neurosquad.ai/ru/card-sdk/permissions#usage-read) (было и в 1.0; теперь
оно открывает и этот метод для агентов, подключённых стрелкой). Нет стрелки — `NOT_CONNECTED`;
оболочка — `INVALID_PARAMS`. 60 вызовов в минуту на карточку. Старое приложение отвечает
`METHOD_NOT_FOUND`: проверяйте `card.host.supports('agents.usage')`. Протокол остаётся 1, карточки,
собранные на 1.0.0, работают без изменений; чтобы перейти, поднимите зависимость до `^1.1.0` (или
`^1.2.0`) — менять код не нужно.

### Изменения хоста внутри контракта 1.0

Вышли между SDK 1.0.0 и 1.1.0 без смены версии SDK; перечислены, потому что могут изменить то, что
видит карточка.

- **0.1.253, 0.1.230, 0.1.160, 0.1.141, 0.1.138** — зарезервированы новые значения `name` в
манифесте: семейства инструментов плагинов Graphify, Память, Context7, Code Graph, RTK и caveman,
инструменты проводки стрелок (`canvas_connect`, `canvas_disconnect`, `canvas_list`),
`agent_set_model` и `neurosquad_models`. Манифест с таким именем не проходит проверку.
- **0.1.214** — `fs.*` не даёт писать в новые файлы, которые запускают код при следующем push:
конфиги GitLab, Jenkins, CircleCI, Buildkite, Travis, Bitbucket, Drone, AppVeyor и Azure Pipelines.
У воркспейса в WSL `workspace.path` — его путь, как его видит этот компьютер; у SSH-воркспейса он
пустой, и `fs.*` отвечает `UNAVAILABLE`. `usage.summary` округляет стоимость вверх, чтобы крошечная
цена не читалась как 0. `neurosquad-card dev` требует включённого режима разработчика.
- **0.1.128** — `agents.lastReply` работает у любого CLI агента с читаемым транскриптом, а не только
у Claude Code, и встроенный порт агента `reply` отдаёт итоговый ответ у всех них.
- **0.1.125** — каталог [проверенных карточек](https://docs.neurosquad.ai/ru/card-sdk/verified-cards).

## 1.0.0 — 2026-09-25

Нужен NeuroSquad **0.1.123** или новее. Первый публичный выпуск: `connect()` и типизированный `Card`
со всем API, [манифест](https://docs.neurosquad.ai/ru/card-sdk/manifest) и его JSON Schema, [разрешения](https://docs.neurosquad.ai/ru/card-sdk/permissions),
[React-обвязка](https://docs.neurosquad.ai/ru/card-sdk/react), необязательный [UI-кит](https://docs.neurosquad.ai/ru/card-sdk/styling),
[mock host](https://docs.neurosquad.ai/ru/card-sdk/testing) и [CLI `neurosquad-card`](https://docs.neurosquad.ai/ru/card-sdk/cli).

> Используете новый метод, но хотите, чтобы карточка ставилась и на старые версии приложения? Не
> задавайте `minAppVersion`, проверяйте `card.host.supports()` и, если метода нет, показывайте
> короткое «обновите NeuroSquad, чтобы открыть этот вид».