Агентная оснастка

На этой странице

Состояния взаимодействия
1. Состояние ожидания (Idle state)
2. Состояние рабочего процесса (Workflow state)
Жизненный цикл сессии
Классификация запросов
1. Правило обнаружения запросов функциональности
Рабочие процессы контента
Детерминированная и агентная обработка
Выполнение BPMN: один навык, два движка
Рабочий процесс запросов функциональности (CRDM)
Предоставляемый пользователем контент и источники
1. Особенности для CRDM
Дисциплина задач и beans
1. Задачи против beans
2. Правила для агентов
Сводные ссылки на навыки
Что еще не реализовано

Эта страница сгенерирована из content/docs/agentic-harness/ — каждый раздел ниже ссылается на собственный исходный файл.

✎ Edit TR

Агентная оснастка (agentic harness) — это модель взаимодействия, на которой работает folio-assistant: правила, состояния и рабочие процессы, определяющие совместную работу агента и пользователя внутри этой платформы. Значительная часть этого поведения уже описана в отдельных навыках и методических документах; эта страница объединяет его в единый справочник, чтобы агент, входя в сессию, мог обратиться к ожидаемому поведению, а не восстанавливать его по разрозненным правилам.

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

Состояния взаимодействия

✎ Edit TR

Взаимодействие между пользователем и агентом всегда находится ровно в одном из двух состояний:

Состояние ожидания (Idle state)

У агента нет активного рабочего процесса. Он ожидает запроса пользователя. При получении запроса он классифицирует его (см. Классификация запросов) и переходит в состояние соответствующего рабочего процесса.

Состояние рабочего процесса (Workflow state)

Агент выполняет именованный рабочий процесс, каждый из которых представлен BPMN-диаграммой процесса с отдельными дорожками (swimlanes) для агента и пользователя. Активный рабочий процесс определяет, что агент делает дальше и чего он ожидает от пользователя.

Активные рабочие процессы на этой платформе:

Рабочий процесс	Источник BPMN	Условие входа
Создание контента (paper)	`authoring-a-paper.bpmn`	Пользователь запрашивает создание контента в фолио статьи (paper)
Создание контента (document)	`authoring-a-document.bpmn`	Пользователь запрашивает создание контента в фолио документа (document)
Жизненный цикл контента	`content-lifecycle.bpmn`	Контент проходит этапы validate → render → publish
Импорт документов	`document-ingestion.bpmn`	Пользователь помещает файл в `uploads/`
От черновика к публикации	`draft-to-publication.bpmn`	Контент переходит из состояния черновика в опубликованное
Требования CRDM	`crdm-requirements.bpmn`	Агент обнаруживает запрос новой функциональности (feature request)
Поиск свидетельств	`evidence-retrieval.bpmn`	Агент ищет свидетельства для подтверждения утверждения

Переходы состояний: рабочий процесс может быть приостановлен, когда пользователь просит переключить контекст. Агент фиксирует, где он находился (текущее действие BPMN), и может возобновить его позже. Одновременно активен только один рабочий процесс, но приостановленные рабочие процессы образуют стек — первым возобновляется наиболее недавний.

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

Жизненный цикл сессии

✎ Edit TR

Каждая сессия агента следует одному и тому же жизненному циклу:

Запуск (Start) — запуск обзорной процедуры начала сессии (beans prime, beans list, scripts/session-start-coord-sweep.sh). Это отображает текущий план работы, насколько сместилась ветка по умолчанию, а также недавнюю активность в соседних ветках. См. AGENTS.md § At session start.
Классификация (Classify) — каждый запрос пользователя классифицируется (см. следующий раздел) и направляется в соответствующий рабочий процесс.
Выполнение (Execute) — агент работает в рамках активного рабочего процесса, следуя его процессу BPMN. В каждой реплике сообщается о том, над каким bean ведется работа и что предстоит дальше.
Фиксация (Commit) — каждая содержательная единица работы получает собственный коммит и пуш. PR открываются при первом же коммите, а не в самом конце. См. AGENTS.md § Commit early, commit often, always PR.
Передача смены (Handoff) — при завершении сессии (пользователь уходит, достигнут лимит контекста, исчерпаны токены) долговременное состояние агента составляют:
- Закоммиченный и запушенный код
- Beans, обновленные актуальным статусом и примечаниями
- Комментарии к задачам (issues) с краткими итогами того, что было достигнуто
- Чат эфемерен; всё остальное сохраняется

Классификация запросов

✎ Edit TR

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

Категория	Описание	Запускаемый рабочий процесс
Создание контента	Написание, редактирование, расширение контента фолио (главы, блоки, разделы)	Рабочий процесс создания (paper или document)
Рецензирование контента	Проверка, валидация, обратная связь по существующему контенту	Жизненный цикл контента / рабочий процесс editing-HCI
Импорт контента	Импорт исходного документа в фолио	Рабочий процесс импорта документов
Запрос функциональности	Запрос новой возможности платформы (см. crdm-detect)	Рабочий процесс требований CRDM
Информационный запрос	Вопрос о платформе, контенте или процессе	Вне процессов — прямой ответ
Вызов инструмента	Запуск конкретного инструмента (`content_validate`, `qa_sweep` и т. д.)	Вне процессов — выполнить и отчитаться
Управление планом работы	Создание, обновление или запрос beans	Вне процессов — выполнить и отчитаться
Отчет об ошибке	Сообщение о некорректном поведении существующих возможностей	Сортировка: прямое исправление, если дефект небольшой; CRDM, если требуется переработка

Правило обнаружения запросов функциональности

Критическая граница классификации пролегает между созданием контента и запросом функциональности. Навык crdm-detect (skills/sdlc/crdm/crdm-detect.md) предоставляет подробные критерии обнаружения. Краткое правило:

Если реализация запроса потребует изменений в folio-assistant (репозитории платформы), а не в репозитории фолио, запрос является запросом новой функциональности, и агенту следует войти в рабочий процесс CRDM.

При возникновении сомнений агент уточняет: «Похоже, для этого могут потребоваться изменения платформы — так ли это, или я могу выполнить эту задачу в рамках текущей модели контента?»

Рабочие процессы контента

✎ Edit TR

Когда запрос классифицируется как работа с контентом (создание, рецензирование, импорт), агент следует соответствующему рабочему процессу BPMN. Существующие страницы документации описывают их подробно:

Процесс публикации — жизненный цикл контента от черновика через валидацию, рендеринг и публикацию. Охватывает роли (автор, рецензент, редактор), базовые процессы, действия и навыки.
Импорт документов — как добавленный файл становится источником L1: извлечение структуры, извлечение контента, построение графа знаний L1, шлюз полноты.
Руководства по написанию:

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

Детерминированная и агентная обработка

✎ Edit QA TR

Обработка рабочих процессов здесь представляет собой спектр, а не переключатель, и оснастка уже находится в четырех различных точках этого спектра, даже не давая оси формального названия: cat-harness.processes:policy enforcement определяет, отклоняется ли неактивированный шаг или лишь фиксируется в примечаниях; relaxable="false" определяет, может ли пакет отменить базовый шаг в ходе согласования; cat-harness.processes:decision определяет, вычисляется ли ветвление по таблице, а не выбирается произвольно; а шлюз на границе коммитов отклоняет запись действием сущности, не являющейся агентом.

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

Шлюз теперь прямо декларирует, к какому типу он относится. <cat-harness.processes:decision> означает, что его вычисляет таблица, а переданный вручную исход отклоняется; <cat-harness.processes:judgement reason="…"> означает чье-то экспертное решение с обязательным указанием причины. До появления этого маркера формулировки «нет таблицы, потому что это экспертное суждение» и «нет таблицы, потому что ее никто не написал» были неразличимы — теперь же команда bun run cat check:workflow-refs выводит разделение по трем категориям, так что вопрос «какая доля процесса решается моделью?» получает ответ, опирающийся на точный подсчет, а не на голословные утверждения.

Для чего нужен этот подсчет — предмет исследований, и вопрос остается открытым. Какие точки экспертных суждений несут риски безопасности, какая часть обязана быть детерминированной и как модели показывают себя в разных подпроцессах при контролируемом наложении контекста и памяти — вот три вопроса, которые этот репозиторий теперь может сформулировать, но еще не разрешил. План исследований, где каждое утверждение помечено как измеренное (measured), решенное (decided) или гипотеза (hypothesis), изложен в deterministic-and-agentic. Читайте его именно как план программы: в нем больше гипотез, чем измерений, о чем в нем прямо и сообщается.

Выполнение BPMN: один навык, два движка

✎ Edit QA TR

Владелец, 2026-09-23, дает определение навыку, к которому относится этот спектр:

Навык выполнения BPMN (BPMN Execution Skill): имея Процесс, Контекст, Состояние и Роль, задействовать один или несколько Навыков для выполнения Задачи.

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

	Детерминированный полюс	Агентный полюс
Инструмент (Tool)	Любой движок BPMN 2.0 с открытым исходным кодом	Агентный рой
Охват агента	Одна задача за раз, передаваемая движком	Большинство или все задачи
Состояние	Строго удерживается движком	Неуправляемое: состояние удерживает рой
Дорожки (Swimlanes)	Строгие: только роль дорожки может выполнять ее задачу	Ослабленные: агент может действовать поперек дорожек
Что обеспечивает соблюдение правил	Движок отклоняет шаг до того, как он произойдет	Механические + агентные отчеты QA/QC обнаруживают нарушения постфактум

Оба полюса различаются тем, когда проверяется правило, а не тем, какое правило проверяется. Один и тот же процесс, одни и те же роли и одни и те же разрешения определяют работу в обоих случаях. Движок проверяет их до запуска задачи и отклоняет ее; рой действует, а отчет QA/QC проверяет их после, на основе записи о том, что было выполнено. Это работает только в том случае, если правила и запись о действиях представляют собой данные, пригодные для считывания отчетом, как это имеет место для W3C ODRL 2.2 в качестве языка разрешений и W3C PROV-O в качестве журнала выполнения (владелец, 2026-09-23; вытекающая отсюда схема — предложение по субъектам, ODRL и PROV-O).

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

Реализовано частично. Ни один движок BPMN пока не подключен. Механический отчет QA/QC уже существует: команда bun run cat prov:qaqc записывает историю каждого экземпляра рабочего процесса в виде журнала PROV-O и повторно проверяет каждый шаг на соответствие политикам ODRL в рекомендательном режиме (issue #1180, шаг 5; навык task-authorization). Агентный отчет QA/QC пока не реализован. В остальной части этого раздела сформулирован целевой ориентир, чтобы предложение имело эталон для сравнения.

Рабочий процесс запросов функциональности (CRDM)

✎ Edit TR

Когда запрос классифицируется как запрос новой функциональности, агент входит в рабочий процесс требований CRDM (полная документация, BPMN).

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

Как агент входит в CRDM

Логика обнаружения описана в skills/sdlc/crdm/crdm-detect.md. Три сценария:

Новая сессия, первый запрос — запрос новой функциональности: → Подтвердить получение, объяснить, что сначала вы поможете проработать требования, перейти к Фазе 1.

Существующая сессия, уже находится в CRDM: → Включить новый запрос в текущий документ требований, продолжить.

Существующая сессия, выполняется работа над контентом: → Сформулировать потребность в функциональности, спросить пользователя, следует ли приостановить работу над контентом и рассмотреть ее сейчас или завести bean на будущее.

Что видит пользователь

Агент не говорит: «перехожу в режим CRDM» и не использует методологический жаргон. Вместо этого:

«Похоже, здесь требуются изменения в платформе — то, что нам понадобится добавить в сам folio-assistant. Прежде чем приступать к разработке, давайте я помогу вам точно проработать все требования, чтобы всё получилось правильно. Я зафиксирую требования в задаче (issue), чтобы остальные участники тоже могли высказать свое мнение».

Как агент выходит из CRDM

Рабочий процесс CRDM завершается, когда:

Разрешены все beans из утвержденных требований, ЛИБО
Пользователь прямо откладывает оставшуюся работу

При выходе, если рабочий процесс работы с контентом был приостановлен, агент возобновляет его.

Предоставляемый пользователем контент и источники

✎ Edit TR

Пользователи предоставляют контент и исходные материалы по различным каналам. Агент должен принимать их все и направлять в соответствующий конвейер:

Канал	Пример	Куда направляется
Каталог `uploads/`	Пользователь сбрасывает документ Word, PDF, файл Excel	Конвейер импорта документов
Ссылки на `library/`	Пользователь ссылается на ранее импортированный источник L1	Прямое цитирование в контенте
Правки в `content/`	Пользователь редактирует `.md`-блок напрямую	Рабочий процесс создания контента
Вложения в задачи GitHub	Пользователь прикрепляет файл к комментарию в issue	Агент скачивает и обрабатывает
Загрузка в чат	Пользователь загружает файл через интерфейс чата LLM	Агент сохраняет в `uploads/` или обрабатывает непосредственно
Указание URL	Пользователь вставляет ссылку на документ	Агент получает и импортирует при необходимости

Особенности для CRDM

В ходе сбора требований материалы, предоставленные пользователем, представляют собой входные данные для требований, а не контент для создания. Агенту следует:

Прочитать и осмыслить предоставленный материал
Извлечь сведения, относящиеся к требованиям
Синтезировать их в формулировку потребностей или документ требований
Сослаться на источник в комментарии к задаче (с ссылкой или вложением)

Пример: пользователь загружает таблицу Excel с отзывами по итогам общественных консультаций. Агент не пытается импортировать ее как контент фолио; он считывает пункты отзывов и обобщает их в требования для инструмента сортировки рецензий (review triage tool).

Дисциплина задач и beans

✎ Edit TR

Работа над функциональностью должна быть привязана к задаче GitHub (issue). В работе над контентом используются beans. Эти два понятия взаимосвязаны, но не тождественны.

Задачи против beans

	Задача GitHub (issue)	Bean
Масштаб	Функция, набор требований или пользовательская история	Единица работы размером в один PR
Аудитория	Стейкхолдеры, автор запроса, бизнес-аналитик	Агент, разработчик
Жизненный цикл	Open → requirements → sign-off → implementation → close	Created → in-progress → resolved
Связь	В одной задаче много beans	Каждый bean ссылается на родительскую задачу

Правила для агентов

Работа над функциональностью → сначала задача (issue). Перед реализацией проверьте:
- Существует ли уже открытая задача? Выполните поиск по ключевым словам.
- Если открытых совпадений нет, проверьте недавно закрытые задачи.
- Если совпадений нет вовсе, попросите пользователя создать задачу. Не создавайте задачу без разрешения пользователя.
Всегда отдельная ветка функциональности + PR. Никаких исключений для работы над функциональностью платформы. Название ветки должно содержать номер задачи (например, feat/197-word-import).
Всегда спрашивайте перед слиянием с main. Пользователь должен дать явное подтверждение. Это требование строже общего правила AGENTS.md для работы с контентом, поскольку изменения функций влияют на платформу в целом.
Публикуйте итоги итераций в задачу. После каждого раунда реализации (закрытия одного или нескольких beans) оставляйте комментарий в связанной задаче, включающий:
- Что было сделано в этом раунде
- Что еще предстоит сделать (открытые beans)
- Ссылки на обновленный контент для проверки (staging URL, страницы документации)
- Таблицу сравнения «до/после» для измененных страниц
Никогда не закрывайте задачу без явного указания. Задачу закрывает бизнес-аналитик или стейкхолдер. Агент закрывает ее исключительно тогда, когда бизнес-аналитик прямо указал сделать это. Агент ни при каких обстоятельствах не должен самостоятельно считать задачу завершенной.
Требования могут охватывать несколько задач. Агенту следует дать ссылки на все соответствующие задачи и отразить связи между ними.
Beans — это не задачи (issues). Команда beans create предназначена для пунктов рабочего плана. Задачи предназначены для требований со стороны стейкхолдеров. Не смешивайте их.

Сводные ссылки на навыки

✎ Edit TR

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

Поведение	Исходный навык / документ	Расположение
Стартовый обзор сессии	`AGENTS.md § At session start`	`AGENTS.md`
Протокол beans	`todo-manager.md`, `bean-coordination.md`	`skills/folio-core/`
Дисциплина коммитов и PR	`AGENTS.md § Commit early, commit often`	`AGENTS.md`
Обнаружение запросов функциональности	`crdm-detect.md`	`skills/sdlc/crdm/crdm-detect.md`
Рабочий процесс требований CRDM	`crdm-requirements-workflow.md`	`skills/sdlc/crdm/crdm-requirements-workflow.md`
Создание контента (paper)	навыки authoring-math	`skill_list` → `authoring-math`
Создание контента (document)	навыки folio-document-adapter	`skill_list` → `folio-document-adapter`
Жизненный цикл контента	навыки content-lifecycle	`skills/authoring/content-lifecycle/`
Импорт документов	`docs-generation.md`	`skills/ui/ui-core/docs-generation.md`
Диспетчеризация и координация	`dispatch-agent.md`, `coordinate.md`	`skills/folio-core/`
Типы контента и адаптеры	`AGENTS.md § Content types`	`AGENTS.md`
Разработка диаграмм BPMN	навык `bpmn-authoring`	`skills/folio-core/`

При расхождении между навыком и этой страницей приоритет имеет навык. Эта страница представляет собой сводный материал, а не новый первоисточник. Если вы обнаружите расхождение, исправьте эту страницу.

Что еще не реализовано

✎ Edit TR

Сохранение состояния рабочего процесса — оснастка описывает приостановку и возобновление рабочего процесса, однако механизма сохранения состояния рабочего процесса агента между сессиями нет. На сегодняшний день для этой цели используются beans и комментарии к задачам.
Автоматическая классификация запросов — таблица классификации является справочником для агентов; инструмента-классификатора, выполняющего автоматическую маршрутизацию, нет.
BPMN для жизненного цикла beans — у плана работы beans есть жизненный цикл (create → claim → in-progress → resolve), который обсуждается в AGENTS.md и навыке todo-manager, но диаграммы BPMN для него пока нет.
BPMN для самой агентной оснастки — высокоуровневая диаграмма BPMN, иллюстрирующая конечный автомат состояний ожидания / рабочего процесса и маршрутизацию по классификации, еще не создана.
Протокол передачи смены сессии — правила о том, что следует закоммитить перед завершением сессии, содержатся в AGENTS.md, однако структурированного артефакта передачи смены, который новая сессия могла бы прочитать для точного возобновления работы с места остановки предшествующей, пока нет.

Отслеживается в: #203