Блоки (.lnb)

Пакет блоков — это папка, имя которой заканчивается на .lnb; в дереве она показывается как один элемент (двойной щелчок открывает). Каждый блок — настоящий файл на диске; порядок хранится в blocks.json в корне пакета. Это работает как блокнот: ячейки с кодом или текстом, сложенные стопкой. Блокнот Jupyter попадает сюда так: щёлкните правой кнопкой по .ipynb в дереве и выберите Импортировать как блоки (.lnb). Каждая ячейка становится настоящим файлом — его можно версионировать, и его читает поиск, — а .ipynb остаётся на месте, потому что импорт — не преобразование. Сохранённые в блокноте выводы не переносятся: запуск ячейки здесь даёт настоящий результат, с временем и командой. Если blocks.json не читается (конфликт Git или прерванная запись), блокнот предупреждает и не перезаписывает его: порядок, подключение и сеанс снова сохраняются только после того, как вы его исправите.

Ячейки, панель блокнота и сочетания клавиш

У каждой ячейки есть имя, кнопка типа (markdown, python, javascript, sql, shell, powershell, bat, r, julia, http, ии, mermaid, latex и текстовые типы) и кнопки: копировать, вставить (щелчок — ниже; стрелка — выше и дублировать), удалить, переместить вверх и вниз и выполнить (стрелка предлагает Выполнить до этого места). Новая ячейка наследует тип соседней. Кнопка справа сворачивает ячейку, оставляя в заголовке только первую строку, а счётчик [n] показывает, в каком порядке ячейки выполнялись в этом сеансе. Создать блокнот можно из дерева (Создать) или через Файл → Создать.

Панель блокнота наверху действует на весь блокнот: Выполнить всё запускает ячейки с кодом по порядку; Остановить прерывает текущую и очищает очередь (запуск попадает в историю с кодом выхода -1); Очистить выводы закрывает панели, ничего не удаляя; меню Ещё экспортирует блокнот и удаляет историю. Ключ timeoutSec в blocks.json задаёт ограничение времени на ячейку (0, значение по умолчанию, — без ограничения).

Сочетания клавиш при фокусе в ячейке: Ctrl+Enter выполняет и остаётся; Shift+Enter выполняет и переходит к следующей (на последней создаёт новую); Alt+Enter выполняет и вставляет ячейку сразу ниже. В текстовой ячейке выполнить — значит отрисовать: она открывается отрисованной, если в ней есть содержимое, а двойной щелчок (или Enter на ней) возвращает к редактированию.

Сохранённый результат, вложения и история

Результат сохраняется (как в лабораторном журнале): по завершении каждый запуск становится файлом .md в saida/<ячейка>/ внутри самого пакета — с временем, кодом выхода, длительностью, командой и самим выводом. Поскольку это Markdown, его можно читать в любом редакторе, версионировать в Git вместе с блокнотом и находить через поиск по заметкам. Повторное открытие пакета возвращает полосу Последний запуск над панелью: щёлкните по ней, чтобы увидеть результат, не запуская заново.

Вложения: у каждого запуска есть своя папка рядом с .md, и её путь приходит программе в переменной окружения LN_RUN_DIR. Всё, что ячейка туда запишет — график matplotlib, CSV, — появляется под выводом (изображения отрисованы, остальное как ссылка на папку) и перечисляется в файле истории. Вывод, который уже является Markdown (таблица SELECT, ответ ИИ, диаграмма), открывается отрисованным; кнопка Текст/Отрисовать на полосе переключает.

История: кнопка История рядом с этой полосой перечисляет предыдущие запуски этой ячейки (время и код выхода) — удобно сравнивать, что та же ячейка возвращала со временем. Мы храним 10 последних на ячейку; чтобы изменить, отредактируйте ключ historyLimit в blocks.json пакета (0 отключает сохранение, а с ним и вложения). Очень большой вывод обрезается (файл сообщает truncated: true). Переименование ячейки или смена её типа переносит историю; удаление ячейки отправляет историю в корзину.

Постоянный сеанс

По умолчанию каждая ячейка — новый процесс: то, что определила одна, следующая не видит. При включённом постоянном сеансе (кнопка Сеанс на панели; ключ session в blocks.json) ячейки Python, JavaScript, shell и PowerShell выполняются в процессе, который живёт между запусками — переменные, функции и импорты одной ячейки действуют в следующих, как в Jupyter. В Python фигуры matplotlib, открытые к концу ячейки, сами сохраняются в папку вложений. Перезапустить сеанс забывает всё; Остановить тоже, потому что прервать — значит завершить процесс. В JavaScript объявляйте через var (или без объявления): let, const и class верхнего уровня нельзя объявить повторно — даже повторным запуском той же ячейки.

Ячейки SQL

Без выбранного подключения ячейка sql выполняется в DuckDB самого блокнота (в памяти): таблицы, созданные в одной ячейке, действуют в следующих, а read_csv('data/sales.csv') читает файлы из папки блокнота — держите данные во вложенной папке, потому что каждый отдельный файл в папке блокнота — это ячейка. Для настоящей базы данных укажите блокноту подключение .lnc на полосе подключения (она перечисляет подключения рабочего пространства): ячейки станут выполняться в базе данных через то же подключение, что и панель «Подключения», — запомненный пароль, SSH-туннель, перечитывание .lnc и подтверждение продакшена перед любой записью. Результат SELECT становится таблицей в файле вывода; INSERT/UPDATE и подобные сообщают, сколько строк изменилось, а ошибка прерывает скрипт и записывает инструкцию, которая не прошла. Мы берём до 100 строк на запрос (sqlMaxRows в blocks.json; файл предупреждает, когда их было больше).

@set имя = значение определяет переменную с областью действия блокнота, а :имя (или ?) — параметр, который запрашивается при выполнении, как в редакторе SQL. Последний SELECT также записывает resultado.csv в папку вложений (те же строки, что и в таблице, до sqlMaxRows), и следующие ячейки получают его путь в LN_LAST_SQL — в Python: pd.read_csv(os.environ["LN_LAST_SQL"]). Подключение хранится в blocks.json как относительный путь; .lnc, лежащий внутри пакета, считается конфигурацией, а не ячейкой.

HTTP, ИИ, Mermaid и LaTeX

Четыре типа выполняются самим LightNote, без интерпретатора: ячейка http — это тест .lnh, выполняемый тем же исполнителем, что и тестер API (отчёт попадает в историю; окружение — то, что указано ключом httpEnv в blocks.json, а файл, который отправляет запрос, должен лежать внутри рабочего пространства); ячейка ai отправляет промпт ассистенту по умолчанию с контекстом блокнота — исходным кодом предыдущих ячеек и последним выводом каждой, кроме ячеек http, которые могут содержать учётные данные, — и ответ приходит отрисованным; ячейки mermaid и latex рисуют диаграмму или формулу в изображение во вложениях. Остановить отменяет первые две.

Экспорт блокнота

Меню Ещё на панели экспортирует весь блокнот: как Markdown (текстовые ячейки как есть, код в ограждениях с указанием языка, последний вывод сразу ниже и изображения по ссылкам) или как блокнот Jupyter (.ipynb, с последним выводом каждой ячейки и встроенными изображениями; ячейка другого языка несёт метку, которую читает VS Code). Это копия, чтобы делиться, — блокнотом остаётся папка.