_OpenSource Web4 agent & app starter kit_

# База данных вашего узла

Каждый элемент хранит здесь свои таблицы, каждый в своём файле базы, который открывает его собственный ключ. Здесь же журнал выкладок и записи разговоров агентов, на вашем компьютере.

[Подключить свой элемент](#connect)
[Что под капотом](#hood)

## Как идёт строка

#### Элемент присылает строку

Он читает и пишет свои таблицы через /db своим ключом, который установщик положил в его окружение.

#### Его файл её хранит

Таблицы элемента лежат в его собственном файле базы, data/elements/<id>.db, рядом с файлом узла.

#### Узел видит все файлы

Ядро, нативные элементы и главный агент открывают файл любого элемента ключом данных узла.

#### Журналы лежат рядом

Каждая выкладка оставляет запись, а агенты хранят здесь свои разговоры, последние 10 000.

Через туннель Cloudflare каждая дверь отвечает 404, с ключом и без.

## Работает всегда

Узел никогда не выключает этот элемент: от него зависят остальные. Он запускается вместе с узлом и не засыпает, даже когда памяти мало.

## Что меняется для вас

| Без него | С элементом базы данных |
| --- | --- |
| Каждый элемент хранил бы данные по-своему | Каждый элемент держит свои таблицы за одной дверью |
| Два элемента могли бы случайно писать в одну таблицу | У каждого элемента свой файл базы, и таблицы соседа для него просто нет |
| Неудачная выкладка не оставляет следа | Каждая выкладка оставляет запись: когда шла, сколько длилась, чем кончилась |
| Ваши данные лежат на чужом сервере | Они остаются на вашем компьютере, внутри вашего узла |

## Чья это таблица

## undefined

**Главный агент узла** — Открывает файл базы каждого элемента и видит, чья каждая таблица.

- **Элемент мамы** — Только своё: её таблицы и её строки.
- **Элемент сына** — Только своё: его уроки и его ответы.
- **Ваш сайт** — Только своё: таблицы его страниц.

Каждый элемент открывает базу своим ключом, и таблицы соседа для него просто нет.

Вызов с ключом элемента работает с файлом этого элемента. SQL, который тянется к другому файлу, например ATTACH, получает отказ.

Ключ данных узла работает с собственным файлом узла и с файлом любого элемента, если вызов назовёт его через ?space=<элемент>. Таблицы, которые элемент записал в файл узла до того, как получил свой, переносит архитектор своим словом (/db/claim).

База разводит двери, а не диск: каждый файл лежит в папке этого элемента на вашем компьютере, и все элементы работают от одного его пользователя.

## Подключить свой элемент

У каждого элемента узла уже есть адрес базы и свой ключ. Прочитать десять строк таблицы:

```
const r = await fetch(`${process.env.REMOTE_DATA_URL}/db/tables/notes?limit=10`, {
  headers: { 'X-Element-Key': process.env.ELEMENT_KEY },
})
const { columns, rows, total } = await r.json()
```

Таблицу объявляет элемент, которому она принадлежит, один раз, при своём старте: CREATE TABLE IF NOT EXISTS через POST /db/migrate. Вызов отдаёт не больше 1000 строк, а столбцы вроде password никогда не покидают базу.

## Что под капотом

| Часть | Что делает |
| --- | --- |
| SQLite | По файлу на каждый элемент и один на узел, в папке этого элемента, никогда в git |
| /db/tables | Строки: чтение с поиском, limit и offset, вставка одной, правка одной по её id |
| /db/migrate | Схема и любой SQL, только с ключом, никогда из сессии браузера |
| /deploy-runs | Журнал выкладок каждого элемента узла |
| /a2a-log | Разговоры агентов, последние 10 000, поля с именами секретов вырезаны |
| /media, /vectors | Передаются элементам хранилища и векторов, ответы без изменений |

## Свой строитель в комплекте

Каждый элемент узла приходит со своим агентом Claude Code и может получить свой Telegram-бот. Нужно что-то поменять в этом элементе — напишите его боту с телефона, и агент обновит логику или дизайн.

Агент работает только в папке своего элемента и не читает весь узел, поэтому каждая правка стоит меньше токенов. Платит за неё ваша подписка Claude Code.

- Бот элемента подключается в ядре, на его странице «Telegram».
- Агент возвращает коммит; вы смотрите его в «Предпросмотре» и принимаете или отклоняете.
- За компьютером терминал агента — в ядре, в разделе «Сборка» этого элемента.

## Открытый код

Сделано Fractera для протокола [Lagrix](https://lagrix.dev) и для любого web2-проекта, которому нужна база данных. Лицензия MIT, код — [github.com/Fractera/fractera-data-starter](https://github.com/Fractera/fractera-data-starter).

## Вопросы и ответы

**Нужна ли схема базы?**
Каждой таблице нужна, но общей схемы узла нет. Таблицу объявляет элемент, которому она принадлежит: при своём старте он отправляет CREATE TABLE IF NOT EXISTS в POST /db/migrate, и база создаёт то, чего ещё нет.

**Кто пишет это объявление?**
Агент элемента, вместе с кодом, который пользуется таблицей. Вы словами говорите, что хранить, а агент превращает это в таблицу и её миграцию при старте.

**Может ли элемент читать чужие таблицы?**
Нет. Вызов с ключом элемента работает только с файлом этого элемента; SQL, который тянется к другому файлу, например ATTACH, получает отказ. Ядро и нативные элементы открывают любой файл ключом данных узла.

**Сколько строк отдаёт вызов?**
Не больше 1000, а столбцы вроде password никогда не покидают базу.

**Можно ли делать резервные копии?**
Да. Элемент готов к тому, что его агент-программист настроит резервное копирование по расписанию или вручную: скажите об этом агенту элемента в Telegram или в терминале. Сам по себе он копий не делает.