Начало работы

Эта страница посвящена первому диалогу — тому, что происходит между чьими-то словами «Я хочу создать фолио» и опубликованным сайтом, который можно открыть. Если у вас уже есть фолио и вы хотите настроить инструментарий, перейдите к §4 Установка и проверка.

1. 1. «Создать фолио» — это пять разных запросов
2. 2. Как агент принимает решение — и почему это таблица, а не субъективное суждение
   1. Три факта
   2. Семь правил
   3. Почему два правила возвращают «ask», и почему именно в этом вся суть
   4. Внесение изменений
3. 3. Как выглядит диалог
4. 4. Установка и проверка
5. 5. Подключите ваш LLM-харнесс
6. 6. Преобразование уже имеющегося у вас репозитория
7. 7. Просмотр опубликованного результата
8. 8. Настройте главную страницу под себя
   1. Узел markdown, который вы редактируете
   2. Ваш собственный фон
   3. Три вещи, которых она делать не станет
9. 9. Отслеживайте работу с помощью beans
10. Следующие шаги

---

1. «Создать фолио» — это пять разных запросов

Скажите эту фразу пяти людям, и вы получите пять разных задач. Первая задача агента — не начать работу, а выяснить, какую именно вы имели в виду.

вы имеете в виду	у вас есть	чего стоит неверная догадка
Новое фолио в новом репозитории	пока ничего	—
folio-assistant, добавленный в уже имеющийся у вас репозиторий	собственный проект со своими файлами	каркас фолио, развернутый поверх работы, на которую сначала никто не взглянул
Еще одно фолио в репозитории, где уже есть одно	инстанс folio-assistant	второй репозиторий, который вам не был нужен, и разделенный корпус
Новый документ внутри уже имеющегося у вас фолио	фолио и задуманная глава	целое пустое фолио, а глава так и осталась ненаписанной
Что-то, что вы предпочли бы описать своими словами	—	—

Четвертая строка — та, на которой стоит задержаться. Это не ошибка с вашей стороны — «фолио» — непривычное слово, и запросить его, имея в виду главу внутри него, — самая естественная оговорка. Агент, развернувший каркас на основе этого запроса, создаст пустой репозиторий, а не абзац текста, который вы просили.

2. Как агент принимает решение — и почему это таблица, а не субъективное суждение

Сортировка (триаж) — это реальный, читаемый артефакт, а не просто привычка, которая могла бы быть у агента:

• процесс описан в folio-assistant-core/processes/conduct/getting-started.bpmn;
• решение в его центре — это decisions/folio-intent.dmn, таблица решений DMN, которую можно открыть в любом инструменте DMN и изменить, не прикасаясь к коду.

Источник: folio-assistant-core/processes/conduct/getting-started.bpmn — SVG сгенерирован с помощью bun run cat render:bpmn.

Три факта

Шлюз считывает ровно три вещи, причем две из них получаются в результате осмотра, а не с помощью вопросов:

факт	как он получается
isFolio	есть ли файл harness.config.json в этом каталоге?
repoHasContent	содержит ли рабочее дерево файлы чьего-то проекта, в отличие от пустого репозитория?
statedIntent	что вы на самом деле сказали — один из пяти вариантов или unstated

statedIntent — это факт о разговоре. Он остается unstated до тех пор, пока вы не скажете, какой именно, а угадывание его по интонации или исходя из сиюминутного удобства — именно тот сбой, для предотвращения которого и создана эта таблица.

isFolio относится к каталогу, а не к вам. Человек, который годами пользовался folio-assistant, открывая новый каталог, по-прежнему находится в каталоге с isFolio=false. Опыт меняет то, насколько подробно агент дает пояснения; он не меняет то, какую ветку он выберет.

Семь правил

#	сказано	является фолио	содержит контент	→
1–4	любой из четырех	–	–	эта ветка
5	unstated	да	–	ask
6	unstated	нет	да	ask
7	unstated	нет	нет	новое фолио здесь

Политика совпадений (hit policy) — FIRST, поэтому правила 1–4 предшествуют любым выводам: человек, который говорит, чего он хочет, никогда не будет переопределен эвристикой о его файловой системе.

Почему два правила возвращают «ask», и почему именно в этом вся суть

Только правило 7 можно определить путем осмотра. Каталог, который уже является фолио, соответствует трем различным запросам, а каталог с чьим-то проектом внутри соответствует двум. Таблица не замалчивает это — она возвращает ask.

Это значит гораздо больше, чем может показаться:

ask — это результат работы таблицы, а не решение, к которому приходит агент.

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

Когда вы отвечаете, ваш ответ становится statedIntent, и та же самая таблица вычисляется заново. Вот почему диаграмма возвращается к шагу Read the repository facts («Считать факты о репозитории»), а не переходит сразу к ветке: ваш ответ — это свидетельство, считываемое как любой другой факт.

Внесение изменений

Таблица представляет собой XML-файл с семью правилами внутри. Чтобы добавить шестой тип запроса, добавьте правило и добавьте соответствующую ветку в шлюз — загрузчик откажется запускать процесс, таблица которого может вернуть результат, для которого не названа ни одна ветка, так что они не смогут разойтись. Ничего в src/ менять не требуется.

3. Как выглядит диалог

Форма вопроса важнее его содержания. Агент определяет, в каком виде вы хотели бы получать вопросы — варианты на выбор, обычный чат, чтение вслух, крупный шрифт — и записывает это в interaction/interaction.json, чтобы ни одна последующая сессия не спрашивала вас снова. См. Доступность.

Затем, когда ответ действительно неоднозначен:

Вы: Я хочу создать фолио

Ассистент: В этом каталоге уже есть фолио (content/atlas/), поэтому вы можете иметь в виду следующее —

1. Добавить что-то в фолио, которое уже здесь — главу, документ (рекомендуется — это то, что чаще всего означает «создать…» изнутри фолио)
2. Добавить второе фолио рядом с atlas
3. Начать новое фолио в новом репозитории
4. Рассказать подробнее

(Можно не отвечать — я выберу вариант 1 и покажу вам, прежде чем что-либо записывать.)

А затем — к работе над чем приступить — потому что «фолио» само по себе никому на самом деле не нужно:

тип контента	что это такое	что требуется
paper	научная статья или книга, строгие утверждения с верификацией в Lean, верстка в LaTeX	инструментарий Lean, TeX
document	структурированная проза — методические рекомендации, стандарт, отчет	pandoc; без Lean, без TeX
WHO SMART DAK	комплект цифровой адаптации (Digital Adaptation Kit, L2) — персоны, процессы, элементы данных, таблицы решений	—
WHO SMART IG	руководство по реализации FHIR (Implementation Guide, L3), созданное на основе DAK L2	Java, SUSHI, IG Publisher

См. Типы контента, чтобы узнать, что дает каждый формализм.

4. Установка и проверка

Следуйте инструкциям в разделе Установка, затем выполните:

bun run cat check-deps

Должно быть сообщено о наличии bun. Все, что требуется вашему типу контента, но отсутствует в системе, будет перечислено с подсказкой по установке — фолио типа document не требует ни одной из строк Lean или TeX.

5. Подключите ваш LLM-харнесс

Зарегистрируйте folio-assistant как MCP-сервер — см. Подключение LLM-харнесса для Claude Code, Antigravity, Gemini CLI и универсальных MCP-клиентов.

Инструменты, наиболее актуальные для этой страницы:

Инструмент	Назначение
folio_init	Развернуть каркас фолио. Зарегистрирован как универсальный инструмент, поскольку запускается до того, как у фолио появится тип контента
workflow_start / workflow_next / workflow_complete	Запустить getting-started.bpmn как реальный процесс; workflow_next сообщает, что доступно сейчас и какой навык это реализует
work_plan_prime	Отобразить план работы (beans)
check_dependencies	Проверить, какие инструментарии установлены
skill_list / skill_fetch	Найти и загрузить инструкции навыка

Полный список инструментов находится на странице Навыки и роли; инструменты для конкретных типов контента появляются только тогда, когда активен соответствующий адаптер.

6. Преобразование уже имеющегося у вас репозитория

На ветке overlay агент осматривает репозиторий, прежде чем к чему-либо прикоснуться:

bun run cat scan:repo            # отчет только для чтения
bun run cat scan:repo -- --json  # то же самое в виде фактов

Он распределяет найденное по трем категориям — library (исходный материал, написанный кем-то другим), content (проза, созданная здесь) и unclassified (не классифицировано).

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

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

1. Импортировать ли вообще? — всё, только исходники, ничего или выбрать по категориям.
2. Куда направить каждую группу? — в library/ или content/, для тех групп, в которых он не был уверен.
3. Оставить на месте или реорганизовать? — рекомендация оставить на месте дается вполне серьезно. Наведение порядка — это дело вкуса; а неработающая относительная ссылка в вашем README — это дефект.

Ничего не перемещается до тех пор, пока не получен ответ на вопрос 3. Этот шаг помечен как relaxable="false" в BPMN, поэтому никакой пакет контента не может отменить его через декларацию.

Полный регламент: навык repo-conversion.

7. Просмотр опубликованного результата

Создание фолио должно завершаться получением ссылки. Сразу после развертывания каркаса:

bun run cat pages:bootstrap            # определить адрес, вывести отчет, без опроса
bun run cat pages:bootstrap -- --wait  # опрашивать, пока сайт не ответит (с ограничением по времени)

Команда определяет адрес из harness.config.json или удаленного репозитория origin, находит процессы публикации по тому, что они делают, а не по тому, как они называются, и сообщает одно из трех состояний:

	значение
live	сайт ответил. Вот ссылка
not yet	зафиксированная ошибка 404 — адрес верный, но первая сборка еще не появилась там
could not check	адрес не удалось определить, опрос не проводился или запрос завершился ошибкой

Третье состояние не является смягченной версией второго, и агент не станет говорить вам «сайт скоро появится» на его основании. Зафиксированная ошибка 404 — это свидетельство; неудавшийся запрос — это отсутствие свидетельств, а автор, которому сообщили неверный статус, отправится искать сайт, который и не должен был появиться.

Эти же три состояния оформлены в виде таблицы решений — decisions/pages-live-gate.dmn, — а скрипт scripts/pages-bootstrap.ts протестирован на точное совпадение с ней, так что скрипт и таблица не могут разойтись.

8. Настройте главную страницу под себя

Главная страница вашего сайта открывается собственным описанием вашего инстанса, расположенным на вашем собственном фоне. И то, и другое задается в одном файле — <name>.json в корне репозитория, — и ничто, относящееся к сердитому коту платформы, не зашито в шаблон. Измените файл — страница обновится соответственно.

Узел markdown, который вы редактируете

// <name>.json -- ДЕКЛАРАЦИЯ. Каждый ключ ниже является одним из ее полей
// верхнего уровня, что и определяет эту метку: это не конфигурация фолио.
{
  "title": "My Folio",              // заголовок левой боковой панели
  "description": "One line.\nAnother line.",   // ← markdown главной страницы
  "icon": "mark-small",             // какое изображение используется для вкладки браузера
  "images": [ /* … */ ]
}

description — это markdown, отображаемый как есть. Это узел, который отрисовывает главная страница; нет отдельной страницы, которую нужно синхронизировать с ним, и в этом весь смысл: описание, присутствующее в двух местах, неизбежно станет противоречить самому себе.

Ваш собственный фон

Изображение становится фоном главной страницы при объявлении role: "landing" и указании, для какой области просмотра (viewport) оно кадрировано:

{
  "id": "landing-laptop",
  "src": "docs/assets/img/my-backdrop.webp",
  "role": "landing",
  "layout": "laptop",               // также: "mobile", "card"
  "width": 1671, "height": 941,
  "textRegion": { "x": 0.205, "y": 0.285, "w": 0.625, "h": 0.235 }
}

textRegion — это область, где текст может безопасно располагаться, в долях от размеров изображения. Она задается автором вручную, а не вычисляется, поскольку определяет, где изображение является спокойным (свободным от деталей), — суждение о композиции, которое никакой попиксельный анализ не заменит. Собственный фон платформы для ноутбуков содержит облачко мысли со свободным нижним пространством внутри, знак в верхней трети и кошачье ухо, поднимающееся в левой нижней части; прямоугольник, исключающий все три элемента, был найден путем рендеринга вариантов и их визуальной оценки. Сделайте то же самое для своего фона.

Объявите по одному варианту для каждой области просмотра. Каждый из них содержит свою собственную область, поскольку та же самая композиция по-другому смотрится при вертикальном кадрировании.

Затем:

bun run cat docs:harness         # передать декларацию в docs/_data/
bun run cat docs:harness -- --check   # ...и завершиться с ошибкой, если данные устарели (для CI)

Три вещи, которых она делать не станет

что вы объявляете	что делает страница
фон с областью текста	отображает ваше описание внутри нее
фон без области текста	показывает изображение, а текст размещает под ним
нет фона	показывает только текст

Средняя строка сделана намеренно. Текст, размещенный наугад, попадет прямо на кота, поэтому необъявленная область означает «не накладывать текст поверх», а не «сойдет в любом месте». А фолио вовсе без графики — это нормальное явление, а не поломка.

Если вы объявили вариант mobile и сайт открывается на телефоне, будет использован этот файл — а если не объявили, будет выбран самый широкий из имеющихся вариантов. Такой фолбэк — это реальная деградация, поскольку область широкого кадрирования не подходит для узкого экрана; об этом сообщается в отчете, а не скрывается, так что средство рендеринга может отказаться от наложения поверх, вместо того чтобы поместить текст туда, куда никто не планировал.

9. Отслеживайте работу с помощью beans

folio-assistant использует beans в качестве единого механизма плана работы — долговременного между сессиями, разделяемого между агентами и зафиксированного в репозитории.

scripts/install-beans.sh          # установить CLI, если отсутствует
beans prime                       # сгенерировать прайминг плана работы для агентов
beans list                        # текущие открытые задачи
beans create "draft chapter 1"    # создать новую задачу
beans <id> --status in-progress   # зарезервировать задачу

Проверяйте перед созданием. beans create генерирует новый id при каждом вызове и ничего не дедуплицирует. Повторный запуск автоматизированного шага без проверки существования привел к появлению 14 688 дубликатов задач beans в одном фолио всего за один день. Проверка описана в навыке todo-manager.

Хук SessionStart отображает план в начале каждой сессии, а инструмент MCP work_plan_prime предоставляет этот же интерфейс любому подключенному агенту.

Следующие шаги

• Доступность — как агент задает вопросы, и элементы управления настройками на этом сайте
• Руководство — написание статьи
• Написание документа
• Типы контента — формализм для каждого предметного домена
• Процесс публикации — каждый процесс в репозитории
• Архитектура — адаптеры, навыки и блочная модель