Создание приложений для агентов

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

Эта страница написана для AI-агента, которого попросили создать или изменить приложение Laze. Прочитайте ее перед первым laze app create. Люди оценивают приложение за первые пять секунд: сделайте так, чтобы оно выглядело законченным, разместите его там, где попросили, и проверьте сами, прежде чем говорить, что оно готово.

Рабочий процесс

Создайте его в переписке, где попросили:
```
laze app create "Insights" --channel <channel>
```
Приложение запускается пустым, с папкой, которая принадлежит вам: создайте его с нуля, начиная с index.html, затем laze app push. --channel закрепляет приложение как вкладку этой переписки. Все в ней, а также их агенты, могут открыть его и продолжить работу над ним (Редактор). Назовите приложение словами, которые люди читают, а не slug.

Подключите набор платформы и клиент со своей страницы:
```
<link rel="stylesheet" href="/_laze/theme.css" />
<link rel="stylesheet" href="/_laze/kit.css" />
<script src="/_laze/laze.js"></script>
```
Слайды, дека или доклад являются единственным исключением: они начинаются с --template slides, единственного шаблона. Его файлы являются первой актуальной версией приложения, которую вы можете менять. Каждый слайд находится в отдельном файле в slides/, порядок задан в slides/deck.json; README.md шаблона объясняет, как добавлять, менять порядок и оформлять слайды. В деке уже есть панель слайдов, навигация с клавиатуры, полноэкранный режим Present, а также кнопки Export PDF и Export HTML, поэтому не создавайте их заново. Через MCP create_app с template: "slides" делает то же самое, а write_app_files меняет по одному слайду.

Шаблон слайдов предназначен только для новой деки. Когда человек отправляет файлы, которые уже являются страницей или декой (HTML-экспорт, zip с index.html, статический сайт), разместите их как есть: создайте приложение без --template, распакуйте файлы в его папку с index.html в корне, скопируйте любой скрипт, который загружается с CDN, и сделайте push. "Перенеси их сюда" или "помести это сюда" с вложением означает ровно это: сделайте это и не спрашивайте, что имеется в виду.
Уже существующее приложение добавляется в переписку закрепленной вкладкой, а не сообщением со ссылкой:
```
laze app pin <app> --channel <channel>
```
--role editor позволяет участникам менять данные, но не код, --view-only позволяет только смотреть. laze app pins <channel> показывает список вкладок. Никогда не закрепляйте заново приложение, которое человек открепил.
Опишите структуру данных в laze.app.json: одна коллекция для каждого типа сущностей, с типизированными полями и несколькими начальными записями. Данные живут в записях, а не в коде страницы. Страница, где числа, строки или текст зашиты в код, сделана неправильно: когда данные меняются, приложение должно измениться без push.
Измените страницу, затем посмотрите ее локально до публикации (см. Проверьте свою работу).
Сделайте push:
```
laze app push -m "Added the pipeline board" --seed
```
Каждый push сразу становится актуальным приложением. Здесь нет черновиков, веток и pull request: приложения разрабатываются от trunk. Пишите сообщение простой фразой о том, что изменилось для людей. --seed заполняет только коллекции, в которых еще нет записей.
Вернуться назад, если push был неправильным: laze app versions, затем laze app revert <version> -m "<why>". Это новая актуальная версия; записи не теряются. История git внутри приложения нужна только для этого.

Кто может открыть приложение

Видимость	Кто может открыть
Ограничено	Люди, агенты и переписки, с которыми оно расшарено или где оно закреплено, а также владельцы и админы рабочего пространства
Канал	Участники канала приложения
Внутреннее	Все в рабочем пространстве
Публичное	Любой, у кого есть адрес

Новое приложение имеет ограниченный доступ. Приложение, закрепленное в переписке, открывается для всех в ней, поэтому закрепления обычно достаточно для командного приложения. Не расшаривайте приложение только с человеком, который попросил о нем, если он попросил в канале: закрепите его там. Расширяйте доступ с помощью laze app access visibility internal|public только по просьбе; команда скажет, когда требуется одобрение админа. laze app members показывает, кто может открыть приложение сейчас. Проверьте это, прежде чем сказать людям, что приложение готово.

Правила дизайна

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

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

Набор Laze идет с платформы (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). Это набор инструментов, а не макет для заполнения: возьмите его токены и нужные элементы управления, а свой CSS положите поверх в собственный файл. Никогда не копируйте набор в приложение.

Сначала визуал. Сделайте изображение предмета самим приложением: inline SVG, canvas, карту, временную шкалу, диаграмму, что-то, по чему люди кликают и что исследуют. Придайте ему собственный вид, со своим макетом и движением на токенах набора.
Одна задача на экран. Первый экран отвечает на вопрос, ради которого существует приложение. Вторую задачу поместите на вкладку (lz-tabs), а не ниже первой.
Правильная форма. Используйте таблицу (lz-table) или доску (lz-board), когда люди просматривают или перемещают строки, плитку статистики (lz-stats, lz-stat-value), когда важна одна цифра, график (lz-chart) для чисел во времени и нумерованные шаги (lz-steps) для короткой последовательности. Текст длиннее трех строк должен быть в документе, а не в приложении.
Реальные данные. Показывайте записи, которые важны людям, с настоящими именами и датами. Никаких "Lorem", "Item 1" или диаграмм-заглушек. Каждое утверждение на странице должно идти из записи или ссылки.
Шкала текста. Один заголовок страницы (lz-title), одна строка под ним (lz-lede), заголовки разделов (lz-h2 или lz-card-title), основной текст. Не добавляйте другие размеры.
Отступы. Используйте классы страницы (lz-page), карточки (lz-card lz-card-body) и сетки (lz-grid, lz-row); они сохраняют ритм от 12 до 20 px. Не вкладывайте карточки в карточки.
Обе темы. Цвета берутся только из токенов (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) и тона lz-badge-*). Hex-цвет ломает темный режим.
Узкая ширина. Приложения открываются в боковой панели шириной около 380 px. Задайте ячейкам таблицы data-label, чтобы строки складывались, и оставляйте заголовки в одну строку.
Пустые состояния и ошибки. Пустой список сообщает, что здесь появится и как добавить первую запись. Неудачный вызов показывает Laze.fail(error), а не пустую страницу.
Статусы как бейджи. Показывайте состояния через lz-badge и тон (-success, -warning, -danger, -info, -primary), а не цветным текстом.
Формы не мешают. Поместите "Новый элемент" за кнопку; список является основным содержимым.

Справочник набора

Потребность	Классы
Страница и заголовок	`lz-page`, `lz-header`, `lz-title`, `lz-lede`
Макет	`lz-row`, `lz-grow`, `lz-grid`, `lz-stats`
Карточки	`lz-card`, `lz-card-body`, `lz-card-title`, `lz-h2`
Таблицы	`lz-table-wrap`, `lz-table`, `lz-num` (числа с выравниванием вправо)
Доски	`lz-board`, `lz-column`, `lz-column-head`, `lz-tile`
Числа	`lz-stat-value`, `lz-chart`, `lz-chart-col`, `lz-chart-track`, `lz-chart-bar`, `lz-chart-value`, `lz-chart-label`
Шаги	`ol.lz-steps` с одним `li` на каждый шаг
Элементы управления	`lz-btn`, `lz-btn-primary`, `lz-btn-ghost`, `lz-input`, `lz-select`, `lz-textarea`, `lz-field`, `lz-form`, `lz-tabs`, `lz-tab`
Состояния	`lz-badge` (+ тон), `lz-callout`, `lz-empty`, `lz-muted`

Скрипты загружаются только с собственного origin приложения: CDN <script> отклоняется, поэтому скопируйте нужную библиотеку в папку приложения. Если переносите артефакт claude.ai или другую страницу React, скомпилируйте ее JSX перед push (например, npx esbuild app.jsx --bundle --minify --outfile=app.js) и подключите собранный файл. Babel в браузере тоже работает, но загружает мегабайты при каждом открытии.

В скрипте страницы Laze.records("<collection>") показывает список, создает, обновляет и удаляет записи, Laze.subscribe перезагружает данные при изменениях, Laze.h создает элементы, а Laze.mount отрисовывает их.

Сочетания клавиш

Laze передает свои сочетания клавиш из вашего приложения в Laze, если приложение не обрабатывает их само. Поэтому люди могут нажать Cmd+K (Ctrl+K в Windows и Linux), чтобы выйти из приложения, не кликая сначала за его пределами. Передаются сочетания Cmd+K, Cmd+[ и Cmd+], Cmd+1 до Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. и Cmd+/, а также Alt+Up и Alt+Down вне текстовых полей. Все остальные клавиши остаются в вашем приложении.

Чтобы оставить одно из этих сочетаний для своего приложения, обработайте клавишу и вызовите event.preventDefault(); тогда Laze не будет его трогать:

document.addEventListener("keydown", (event) => {
  if ((event.metaKey || event.ctrlKey) && event.key === "k") {
    event.preventDefault();
    openSearch();
  }
});

Проверьте свою работу

Смотрите на каждое изменение перед push:

laze app serve --port 4173

Это раздает вашу папку на http://127.0.0.1:4173/ с набором платформы и записями актуального приложения, только для чтения. Нужна актуальная версия, поэтому сначала один раз выполните laze app push. Откройте ее своим браузерным инструментом и сделайте скриншоты в обеих темах и на ширине панели, например:

npx -y playwright install chromium   # once
npx -y playwright screenshot --viewport-size=1100,800 http://127.0.0.1:4173/ light.png
npx -y playwright screenshot --viewport-size=1100,800 "http://127.0.0.1:4173/?theme=dark" dark.png
npx -y playwright screenshot --viewport-size=390,800 http://127.0.0.1:4173/ narrow.png

Посмотрите на каждое изображение. Исправьте текст, который вылезает за границы, колонки, которые не помещаются, цвета, которые исчезают в темном режиме, и все, где еще написано "demo".

Перед тем как отправить приложение:

Оно закреплено там, где о нем попросили, а laze app members показывает людей, которые должны его открыть.
Первый экран отвечает на запрос без прокрутки.
Скриншоты в светлой теме, темной теме и на 390 px выглядят законченными.
Ваше сообщение указывает название приложения и одной строкой объясняет, что оно делает. Вкладка в переписке и есть ссылка.

Спрашивайте, если не уверены

Задайте человеку один короткий вопрос вместо того, чтобы создавать не то. Не ждите "можно" для шагов, о которых уже попросили: если попросили приложение в этом канале, создайте его там, закрепите и сообщите об этом.

Создание приложений для агентов

Рабочий процесс#

Кто может открыть приложение#

Правила дизайна#

Справочник набора#

Сочетания клавиш#

Проверьте свою работу#

Спрашивайте, если не уверены#