# Основы за пять минут (/ru/docs/build-concepts)

Вы пишете инструмент командной строки или интеграцию для агента, которая читает или пишет общее хранилище WireCat. За
пять минут эта страница даёт вам модель: какие бывают записи, как они связаны и какие правила не дают вашему инструменту
сломать другие. Следующие страницы показывают, как добавить источник, хранить свои данные, входить в сервис и
соответствовать стандартам.

## Общее хранилище [#общее-хранилище]

Каждый инструмент WireCat хранит данные в одном файле SQLite на компьютере владельца — `wirecat.db`. Этим файлом владеет
пакет `@wirecat/cli-core`: его таблицы, миграции и код, который их читает и пишет. Инструмент обращается к файлу только
через cli-core и никогда — своим SQL ([правила хранилища](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/store.md)).

## Сущности и записи источников [#сущности-и-записи-источников]

* **Сущность** — это то, что владелец имеет в виду на самом деле: человек, событие, документ. В ней нет id провайдера.
* **Запись источника** — то, что о сущности знает один источник: пользователь Telegram, адрес почты, встреча Zoom,
  запись календаря, файл Drive. В ней есть аккаунт, откуда она пришла, и собственный id провайдера.

Одна сущность собирает записи из нескольких источников. Одна встреча в Zoom и в двух календарях — одно событие. Один
человек в Telegram и в почте — один человек. Ваш инструмент пишет записи источников; cli-core связывает их с сущностями.

## `external_id` [#external_id]

Id, который провайдер дал записи, хранится в `external_id` и уникален в пределах аккаунта. Второй id, который провайдер
тоже использует, получает свою именованную колонку, например `ical_uid`. Никогда не колонка с именем провайдера и
никогда не только внутри `metadata` ([WC-DATA-3](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/data-model.md#wc-data-3--a-providers-id-goes-in-external_id)).

## Связи [#связи]

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

1. Связь, сделанную владельцем, никогда не заменяет автоматическая.
2. Два одинаково подходящих кандидата не дают связи.
3. Совпадение названия или пересечение по времени само по себе никогда не связывает две записи.

Это правило [WC-DATA-6](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/data-model.md#wc-data-6--every-link-records-how-it-was-made-the-owners-link-wins-ambiguity-makes-no-link).
Как связи выглядят для читателя — на странице [Как всё связано](/llms.mdx/docs/ru/how-things-are-linked/content.md).

## Общие сущности и ваши таблицы [#общие-сущности-и-ваши-таблицы]

Запись, которая может понадобиться не одному инструменту, — **общая сущность**: её таблица живёт в cli-core. Таблица,
нужная только вашему инструменту, — контрольная точка синхронизации, кэш — живёт в собственном файле SQLite вашего
инструмента, и другие инструменты её не читают
([WC-DATA-1](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/data-model.md#wc-data-1--a-record-more-than-one-tool-needs-is-a-core-entity-in-cli-core-a-clis-own-tables-stay-private)).
Подробнее — [Хранить свои данные](/llms.mdx/docs/ru/build-own-data/content.md).

## Ещё в хранилище [#ещё-в-хранилище]

* **Реестр провайдеров.** Ваш инструмент при каждом запуске записывает своего провайдера (имя, вид, псевдонимы,
  команду) в хранилище, и все остальные инструменты узнают о новом источнике без выпуска cli-core. Строки провайдера,
  которого ни один инструмент не записал, пропускаются с пояснением и никогда не ищутся как сообщения. См.
  [Добавить источник](/llms.mdx/docs/ru/build-add-source/content.md).
* **Список на проверку.** Пары, которые инструменты не могут различить, например два события для одной встречи, ждут там
  решения владельца.
* **Записи календаря и файлы** — записи источников для событий и документов, а у каждой учётной записи может быть адрес
  почты, чтобы один адрес объединял одного человека.

## Что сломается, если это пропустить [#что-сломается-если-это-пропустить]

Id провайдера только в `metadata` нельзя обновить по ключу, и каждая синхронизация создаёт дубль. Связь по одному
названию соединяет две разные встречи, и владелец видит чужую запись. SQL к общему файлу ломается на следующей миграции
cli-core.

Дальше: [Добавить источник](/llms.mdx/docs/ru/build-add-source/content.md).