Глоссарий¶

Эта страница — терминологическая база документации flower. У одной вещи по всему сайту ровно одно название, соответствие китайского и английского зафиксировано здесь — переводы идут по этой же таблице.

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

Фреймворк и прогон¶

Долгий горизонт¶

long-horizon

Один прогон растягивается на часы или дни, охватывает несколько сессий, переживает перезапуски процесса — это не «вопрос-ответ». Все механизмы flower существуют ради того, чтобы такой прогон не развалился на полпути.

Замер для ориентира: HT001 отработал 10.4 часа подряд.

Прогон¶

run

Полный путь одного Runtime от начала до конца. Внутри одного прогона может быть несколько шагов, несколько сессий, его можно прервать и потом продолжить. Записи прогона ложатся в runs/manifest.json и runs/sessions.db.

Не является: одним вызовом API, и не является одной сессией.

Сессия¶

session

Один контекст на стороне модели. У неё есть свой session_id, её можно resume, можно fork. Один прогон может сжечь несколько сессий — при каждом хэндоффе заводится новая.

Шаг¶

step · Step

Исполняемая единица внутри рабочего процесса. Получает словарь контекста, запускает агента, записывает результат обратно в словарь. Step — это класс, см. Python API.

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

workflow · Workflow

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

Роли¶

Роль — это способ flower разделить труд между агентами. Каждая роль = кусок внедряемого текста правил + набор инструментов + набор hook'ов. Все пять ролей — фабричные функции, см. Python API.

Координатор¶

coordinator · coordinator()

Тот самый агент в главном потоке. Он разбирает задачу, раздаёт работу, читает отчёты, принимает решения, но сам руками не делает — Write / Edit ему не выдаются. Базовые инструменты — Agent, TodoWrite, Read (roles.py:27), но это не итоговый список: по параметрам сверху добавляются ещё три вещи. glance=True (по умолчанию) добавляет урезанный Bash (хватает только на команды вида git status / ls, которые отрабатывают за один взгляд, за этим следит delegate_guard); если задан канал вопросов — добавляются inbox и ask; если у подчинённых исполнителей есть WebFetch / WebSearch, эти два тоже подмешиваются — allowed_tools действует на уровне сессии, и без подмешивания subagent при собственном вызове застрянет на согласовании прав, на которое некому ответить (roles.py:513-526).

Роль задаётся как «человек, умеющий пользоваться Claude Code», а не как исполнитель.

Не является: более умным агентом. По умолчанию он и исполнитель работают на модели одного класса; экономится контекст, а не модель.

Исполнитель¶

worker · worker()

subagent, который реально делает работу: пишет код, гоняет тесты, ищет материалы. Инструменты: Read Write Edit Bash Glob Grep WebFetch WebSearch.

Формат ответа ограничен текстом правил до четырёх разделов — вывод / основания / результат / непроверенное, не более 30 строк, запрещено вставлять содержимое файлов, вывод команд, логи и сырые diff'ы.

Уточнитель¶

clarifier · clarify()

Роль, которая выясняет требования до начала работы. Она ничего не делает, только задаёт вопросы — до тех пор, пока не станет ясно (лимита на число раундов нет), и в конце выдаёт бриф требований. См. Предварительное уточнение.

Судья¶

judge · judge()

Роль, которая решает, «сделано или нет». Она делает одно из двух: до старта ставит цель (выдаёт цель + чек-лист проверки) или после каждого раунда выносит решение по раунду (выдаёт вердикт). См. Страж цели.

Ключевое: судья судит результат, а не исходники.

В HT001 на этом уже прокололись: критерий приёмки был «запускается прямо в терминале macOS», а у сданного артефакта file выдавал ELF 64-bit LSB pie executable, ARM aarch64, GNU/Linux — и вердикт при этом был «пройдено».

Два момента надо проговорить, иначе пример прочитают неправильно:

1. Ошибся тогда не страж цели — в HT001 этого механизма ещё не было; ошибся аудитор, которого координатор отправил по собственной инициативе.
2. Судья в конфигурации по умолчанию, скорее всего, тоже это пропустит. У judge() по умолчанию can_run=False, инструменты только Read/Glob/Grep — он не может запустить file, он лишь прочитает Makefile, увидит там ветку Darwin и признает цель достигнутой.

Реально сработало в HT002: у судьи был включён judge_can_run, он сам запускал file и lsof, смотрел на фактическое состояние и явно обошёл эту яму. То есть фраза «судить результат» встаёт на ноги только при can_run=True.

Оракул¶

oracle · oracle()

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

subagent¶

Понятие Claude Agent SDK: дочерний агент, которого основной агент отправляет через инструмент Agent. У него собственный transcript, вызовы инструментов и попытки-ошибки пишутся туда, а в главный поток приходит только итоговый отчёт.

Это первый слой экономии контекста в flower и слой, дающий наибольшую экономию. См. Экономика контекста.

Четыре механизма¶

Предварительное уточнение¶

clarify

До начала работы выяснить требования, заморозить их в брифе требований и только потом приступать. Защищает от «сделали не то, что хотели». См. Предварительное уточнение.

Бриф требований¶

brief · Brief

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

Не путайте с брифом задачи. Бриф требований — это «чего хочет человек», бриф задачи — «что этот subagent делает вот сейчас».

Бриф задачи¶

task brief

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

Замер: 8/8 брифов задач пересказывали уже известную адресату дисциплину; в самом коротком из них на 521 символ приходилось около 120 символов, специфичных для задачи — примерно 4.8k впустую занятого постоянного контекста за раунд.

Страж цели¶

goal guard

Судья после каждого раунда независимо выносит решение, достигнута ли цель, и если нет — отправляет работу обратно. Защищает от «сказали, что готово, а на деле нет». См. Страж цели.

Вердикт¶

verdict · Verdict

Результат одного раунда судейства, ровно три раздела: вывод / обоснование / что не прошло.

Выводов три вида: ACHIEVED (достигнуто), NOT_YET (ещё нет), UNREACHABLE (в этой среде не проверить). Последние два — разные выводы: «здесь нельзя проверить» никогда не засчитывается как пройдено.

Непрерывность¶

continuity

Повторный запуск в том же каталоге автоматически подхватывает прогресс прошлого раза — так же и после убитого процесса, и после перезагрузки машины. Защищает от «упало после нескольких часов, начинаем сначала». См. Непрерывность.

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

Хэндофф¶

handoff

Когда контекст почти заполнен, текущая сессия пишет документ хэндоффа, который человек может прочитать и поправить, после чего дело принимает новая сессия. Защищает от «контекст заполнился, всё сжали в одну сводку». См. Хэндофф.

Это не compact. См. compact.

Документ хэндоффа¶

handoff document · Handoff

Документ, который пишется при хэндоффе, пять разделов: doing (что делается), decided (что решено), deadends (тупиковые пути), next (следующий шаг), scene (обстановка).

Обязательны только doing и next — жёсткое требование непустых «тупиковых путей» заставит модель их выдумывать.

compact¶

compact

Родной приём Claude Code: контекст заполнился — предыдущий диалог сворачивается в сводку.

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

Управление контекстом¶

Главный поток¶

main thread

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

Как главный поток определяется в коде: в данных hook'а нет agent_id. У hook'ов subagent'ов agent_id есть.

Верстак¶

workbench · Workbench

Рабочий каталог на диске, три подкаталога:

INDEX.md — индекс этих трёх каталогов, он внедряется в system prompt, поэтому агент в каждом раунде знает, что у него на руках.

Сброс на диск¶

spill

Когда результат инструмента превышает порог (по умолчанию 4000 символов), hook PostToolUse записывает его в <корень верстака>/spill/, а в контексте остаётся одна строка с путём.

Путь идёт следом за верстаком, он не зашит намертво — только когда верстак лежит в месте по умолчанию <рабочая область>/.flower, путь оказывается ровно .flower/spill/. При включённой изоляции, когда верстак уведён за пределы репозитория через home=, spill переезжает вместе с ним.

Режется на месте, а не откладывается до заполнения контекста, чтобы потом делать compact.

Одноразовая команда¶

ephemeral command

Команда, результат которой протухает и не имеет ценности для хранения — ls, git status, ps и подобные. Их результаты не попадают в постоянную запись сессии. Решения «пускать ли главный поток разок глянуть» и «будет ли результат срезан» принимает одна и та же функция, поэтому два множества всегда совпадают.

Усечение¶

trim · TrimmingSessionStore

Перед resume переписывает ту порцию сообщений, которая пойдёт обратно в модель (результаты одноразовых команд, сверхдлинный вывод инструментов).

Оно переопределяет только load(): оригинал в SQLite остаётся нетронутым, срезается лишь та копия, что уходит в контекст при этом resume. Поэтому усечение обратимо — смените стратегию, сделайте resume ещё раз и получите полную запись.

Отсечение¶

prune · PruningSessionStore

Держит сообщения об ошибках вне контекста. Куча ошибок, накопившаяся во время повторов при обрыве сети, не должна занимать контекст после resume.

Не путайте с усечением: усечение выбрасывает по объёму и ценности, отсечение — по признаку «ошибка или нет».

Рантайм¶

Изоляция¶

isolation

Помеченные роли автоматически расходятся по отдельным git worktree, это обеспечивается hook'ом, а не подсказками в промпте. При параллельной правке одного репозитория они не сталкиваются.

Устойчивость¶

resilience · Resilience

При обрыве сети — висеть и ждать, а не падать с ошибкой: за состоянием следят DNS- и TCP-пробы, после восстановления сети прогон продолжается через resume. Сообщения об ошибках, накопившиеся за время ожидания, отсечение держит вне контекста.

Родословная¶

lineage · Lineage

Межпроцессная запись того, «из какой сессии форкнут этот прогон», лежит в lineage.json. Непрерывность по ней находит, до чего дошли в прошлый раз.

Не путайте с манифестом прогонов — это runs/manifest.json, там ведётся учёт по каждому прогону.

Манифест прогонов¶

run manifest · runs/manifest.json

Учётная запись по каждому прогону: сколько денег потрачено, сколько времени заняло, насколько велик контекст. Все числа со страниц-кейсов пересчитываются отсюда.

Пробуждение¶

wake · wake_state()

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

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

Событие¶

event · Event

Поток сообщений SDK, сплющенный в стабильную структуру. Слой взаимодействия знает только Event и не импортирует ни одного типа SDK — это и есть граница, благодаря которой смена UI не требует правки ядра.

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

interaction layer

Слой UI между человеком и прогоном. По умолчанию терминал, можно заменить на Web, TUI, HTTP или полностью автоматический режим без человека. См. Смена слоя взаимодействия.

Хранилище сессий¶

session store · SessionStore

Бэкенд постоянного хранения сообщений сессии. По умолчанию SqliteSessionStore пишет в runs/sessions.db, поверх можно надеть две обёртки — усечение и отсечение.

Бюджет¶

budget · max_budget_usd

Верхний предел трат на один прогон, при превышении прогон останавливается. Долгогоризонтный прогон без него обходится дорого — HT001 стоил $171.62.

Переносимость¶

Переносимый¶

portable

Переехали на другую машину — поведение то же. Достигается через setting_sources=[] — не читается ни ~/.claude/ хост-машины, ни .claude/ проекта. Предметные возможности едут вместе с репозиторием через plugin, учётные данные приезжают со своим .env.

Цена: учётные данные надо возить с собой, конфигурация хост-машины автоматически не наследуется.

Дописывание¶

append

Предметные инструкции дописываются после родного системного промпта Claude Code, а не заменяют его:

system_prompt = {"type": "preset", "preset": "claude_code", "append": spec.instructions}

Поэтому специализация не покупается ценой потери общих способностей.

plugin¶

Пакет предметных возможностей, который едет вместе с репозиторием. Подключается через plugins=[local], в каталоге можно держать skills/, agents/, hooks/, .mcp.json. См. Развёртывание.