Расширенные сценарии CLI

Эти команды описаны для текущего стабильного выпуска Bee. Выполняйте их в нужном checkout. bee --version показывает версию установленного бинарного файла; поведение другой версии может отличаться. Остальные команды описаны в справочнике, чтение для агентов — в инструментах MCP.

Сохранение и изучение артефакта

artifact add копирует UTF-8 файл в приватное хранилище, привязанное к физическому checkout. Поддерживается JSON (по умолчанию, проверяется при добавлении) и текст. Предел — 1 МиБ на файл и 64 артефакта на checkout. Чтение проверяет манифест и сохранённые байты, не перечитывает исходный файл и не запускает команду заново. Если артефакты нужны MCP, используйте каталог artifacts выбранного экземпляра Bee.

# Выполняйте в Git checkout с reports/results.json.
checkout="$(git rev-parse --show-toplevel)"
artifact_store="$HOME/.bee/artifacts" # экземпляр по умолчанию; для именованного используйте его корень
bee artifact add --root "$checkout" --store "$artifact_store" --file reports/results.json --format json
# Поместите возвращённый id (SHA-256) в artifact_id.
artifact_id='<returned-id>'
bee artifact search --root "$checkout" --store "$artifact_store" --text 'failed' --limit 20 --offset 0 --budget 65536
bee artifact get --root "$checkout" --store "$artifact_store" --id "$artifact_id" --out "$checkout/recovered-results.json"

add возвращает id, root, sourcePath, sourceSha256, sourceBytes, format и метаданные сырой записи. search ищет буквальную строку в строках текста всего архива checkout или одного --id. В ответе есть schemaVersion, для архива artifactsSearched, число matchedRecords до разбиения на страницы, offset, nextOffset и rows (ID артефакта, путь/хеш источника, номер строки, текст). Поиск одного ID также выдаёт artifactId, sourceSha256, operation: "search", totalRows. get создаёт новый файл, не перезаписывая существующий; ответ содержит status: "recovered", id, sourceSha256, sourceBytes.

Сохранённый массив JSON можно запросить без выполнения кода или SQL. Файл запроса — до 64 КиБ. JSON Pointer выбирает массив и поля строк; пустой arrayPointer выбирает массив верхнего уровня. eq/ne учитывают тип, contains ищет текст, exists проверяет наличие поля. Отсутствующее поле отличается от JSON null, а ne сопоставляет только существующие поля. countOnly не возвращает строки; groupBy требует скалярный pointer. limit — 1–1000, по умолчанию 100.

{
  "arrayPointer": "/results",
  "filters": [{"pointer": "/outcome", "operation": "eq", "value": "failed"}],
  "select": ["/name", "/outcome"],
  "offset": 0,
  "limit": 20,
  "maximumOutputBytes": 65536
}

Сохраните объект в query.json и выполните:

bee artifact query --root "$checkout" --store "$artifact_store" --id "$artifact_id" --query-file query.json

Ответ содержит schemaVersion, artifactId, sourceSha256, operation: "query", matchedRecords, totalRows, offset, nextOffset, rows. Если полный JSON не помещается в бюджет, поиск/запрос выдаёт ошибку, а не обрезает доказательство. Источник должен быть обычным файлом в точном Git checkout; символьные и жёсткие ссылки запрещены. Хранилище должно быть приватным. Ошибка синтаксиса — код выхода 4; отказ ввода, отсутствие/повреждение записи, лимит или отмена — 5, с errorCode в stderr.

Кодирование и декодирование JSON-представления

representation encode создаёт версионированный пакет JSON-значений; столбцовая форма выбирается только если весь конверт оказался меньше. Значения JSON и запись чисел сохраняются, исходные пробелы и порядок полей — нет. Для точных исходных байтов восстановите артефакт.

bee representation encode --file reports/results.json --encoding cl100k_base > packet.json
bee representation decode --file packet.json > decoded.json

Вторая поддерживаемая --encoding — o200k_base, по умолчанию cl100k_base. Пакет сообщает формат, кодировку, количество токенов и содержимое. Эти числа относятся к локальной кодировке, а не к оплате провайдера. JSON-вход ограничен 1 МиБ. Некорректный пакет или слишком большое раскрытие дают ошибку без частичного JSON. Команды читают локальные файлы и пишут только в stdout; перенаправление оболочки — ваше явное действие записи.

Сжатие необязательного текста и восстановление оригинала

Сжатие по умолчанию выключено и допускает потерю смысла. Принимается только текст, явно классифицированный как prose. Не передавайте код, промпты, инструкции, смешанные пакеты, юридические или точные тестовые доказательства. setup — единственная операция, которая может установить/скачать локальный Python runtime и модель; она не включает сжатие.

bee compression settings show
bee compression setup --python python3
bee compression doctor
bee compression settings on
bee context compress --input notes.txt --content-kind prose --rate 0.5
# Возьмите originalSha256 из ответа сжатия:
bee compression recover --sha256 '<originalSha256>'

Диапазон --rate — 0.1–0.9. Ответ содержит status, text, originalSha256, необязательные originalPath/compressedSha256, semanticRisk, локальные originalTokens/compressedTokens и доступные измерения runtime. Восстановление возвращает status: "recovered", точный text и проверенный sha256. При выключенном сжатии возвращается оригинал; успешное сжатие всё равно помечено semanticRisk: true. Сверяйте восстановленный текст до использования его смысла. Адаптер локальный, скрытого облачного fallback нет. Лимит ввода — 64 КиБ/8192 локальных токенов, вывод модели — до 120 секунд. Настройки и оригиналы записываются под корнем выбранного экземпляра. Неверное использование — выход 4, неготовый runtime/сжатие/восстановление — 5. Другие приёмы — в инструментах контекста и провайдеров.

Предпросмотр изменения символа C#

symbol ищет объявление по уже существующему свежему графу C#. Возьмите ID из graph outline, SHA-256 исходника — из графа/свидетельства исходного файла. Хеш защищает от изменения файла между выбором и записью. Поместите C# замену UTF-8 в replacement.txt: новый файл .cs внутри checkout сделал бы граф устаревшим. Изучите предварительный результат:

checkout="$(git rev-parse --show-toplevel)"
bee graph build --json
bee graph outline src/Example.cs --json
shasum -a 256 src/Example.cs # скопируйте первое поле как <source-sha256>
bee symbol preview --root "$checkout" --symbol '<symbol-id>' --expected-sha256 '<source-sha256>' \
  --operation replace --replacement-file replacement.txt --budget 65536 --json
# После проверки предпросмотра и хеша:
bee symbol apply --root "$checkout" --symbol '<symbol-id>' --expected-sha256 '<source-sha256>' \
  --operation replace --replacement-file replacement.txt --budget 65536 --json
bee graph build --json

Операции: replace, insert-before, insert-after; --replacement-file - читает stdin. preview ничего не пишет. apply меняет лишь проверенные строки объявления и сохраняет UTF-8 BOM. Оба отвечают полями ok, applied, supportedLanguage: "csharp", необязательным errorCode и данными edit (path, symbolId, хеши графа/источника/кандидата, операция, диапазон байтов, before, after). apply не пересоздаёт граф, не компилирует и не тестирует. Замена — до 64 КиБ, источник/кандидат — до 256 КиБ; бюджет вывода 512–262144 байт (по умолчанию 65536). Неоднозначный символ, устаревший граф или несовпадение хеша запрещают запись. Неверный ввод — выход 4, отказ изменения — 5.

Перенос экспорта дизайна в реализацию

design читает HTML, каталог или ZIP офлайн и не выполняет скрипты. prepare создаёт локальный пакет передачи, но не загружает его. import сохраняет полный исходный макет и индекс. list показывает ID, slice — ограниченный контекст источника и зависимостей для одного ID, map связывает источник с реализацией, verify проверяет целостность. Используйте физический путь источника/вывода; в macOS /tmp — символьная ссылка, поэтому пример создаёт каталог в home.

bee design doctor
demo_dir="$(mktemp -d "$HOME/bee-doc-demo.XXXXXX")"
bee design prepare mock.zip --output "$demo_dir/transfer"
bee design import mock.zip --output "$demo_dir/bundle"
bee design list "$demo_dir/bundle"
bee design slice "$demo_dir/bundle" --id '<id-from-list>' --budget 65536
bee design map "$demo_dir/bundle" --mapping mapping.json
bee design verify "$demo_dir/bundle" --json

mapping.json содержит id, абсолютные пути target и fixture, reuseStrategy (direct-extract, constrained-transform, existing-component, rebuild-region) и необязательные route, expectedRevision, reason; для rebuild-region причина обязательна. prepare допускает заданные пользователем --provider-file-limit-bytes и --provider-total-limit-bytes; Bee не узнаёт реальные лимиты провайдера. slice требует --id, бюджет 512–65536 байт. Ответы содержат schemaVersion/status; у операций результата данные находятся в result, а import сообщает bundle, revision, количество файлов/элементов/ограничений и visualAcceptance: false. Slice раскрывает complete, segments, dependencies, limitations и число пропусков. Выход 0 — полный результат, 4 — неверное использование, 5 — неполный/отклонённый. verify проверяет хеши и зависимости, не визуальное совпадение или утверждение дизайна. Создание экспорта описано в навыке дизайна.

Снимки и сравнение визуальных доказательств

Визуальные проверки требуют отдельного Node runner. doctor сообщает лишь наличие, не ставит пакеты и не подтверждает готовность браузера. Продолжайте в той же оболочке, сохраняя demo_dir от импорта. Экспортируйте runner в новый каталог, явно установите зафиксированные зависимости, создайте черновик спецификации из импортированного дизайна и завершите его:

bee visual doctor
bee visual export-runner --output "$demo_dir/visual-runner"
cd "$demo_dir/visual-runner" && npm ci
bee visual init --bundle "$demo_dir/bundle" --output "$demo_dir/visual-draft.json"
# Заполните селекторы, runtime-профиль, fixture, рецепты и проверки областей.
bee visual reference --request /absolute/path/reference-request.json --runner-dir "$demo_dir/visual-runner"
bee visual capture --request /absolute/path/capture-request.json --runner-dir "$demo_dir/visual-runner"
bee visual compare --request /absolute/path/compare-request.json --runner-dir "$demo_dir/visual-runner"
bee visual report --request /absolute/path/report-request.json --runner-dir "$demo_dir/visual-runner"

Операция	Получаемое доказательство
select	Выбирает сценарии по specPath, policyPath и относительным changedPaths; сообщает покрытие, визуальных проверок не выполняет.
cache-clean	По умолчанию предварительно показывает очистку кеша эталонов; только явный запрос remove: true удаляет проверенные записи Bee.
reference	Снимает объявленный источник дизайна как эталон; не использует скриншот приложения как golden.
capture	Снимает приложение с явными хешами web.files и идентичностью сборки/артефакта source; снимок приложения всегда новый.
compare	Проверяет области, состояние, fixture, профиль, идентичность источника/артефакта; пишет comparison.json с ограниченными выводами.
report	Проверяет существующие артефакты сравнения и пишет HTML-отчёт без скриптов; ничего не загружает.

Запросы reference/capture указывают абсолютные specPath, outputDir, необязательные scenarioIds и источник web. Capture дополнительно требует web.files: [{path, sha256}] и source: {sourceId, buildId, artifactSha256}. Экспортированный runner содержит точные схемы JSON и открытый генератор демо с полными примерами запросов.

Запрос должен иметь версию схемы 1 и абсолютные пути в полях путей; для снимка нужен установленный браузер или явный browserExecutable в запросе. --node выбирает абсолютный путь Node, --timeout — 1–300 секунд (по умолчанию 60). init записывает черновик с requiresCompletion: true, acceptance: false; заполните заглушки. Ответ runner содержит schemaVersion, operation, status, exitCode, trusted: false, acceptance: false. Выход 0 — прохождение runner, 3 — визуальное отличие, 4 — неполнота, другие ненулевые значения — ошибки. Предоставленное вызывающим свидетельство всё ещё недоверенное; отчёт диагностический и требует проверки человеком.

Изоляция нескольких экземпляров Bee на одной машине

Существующий экземпляр по умолчанию остаётся в ~/.bee. Именованный экземпляр получает собственные bootstrap, базу, пространство сотрудничества, persona, настройки worker и локальное состояние. Сопоставьте путь checkout и при необходимости шаблон remote. Перед записью работы проверьте фактически выбранную область:

bee instance list --json
bee instance add demo --path /absolute/path/to/checkout --json
bee instance which /absolute/path/to/checkout --json
cd /absolute/path/to/checkout
bee instance show --verify --json
bee instance doctor --json
bee instance env demo --shell zsh

add принимает повторяемые --path/--remote. map и unmap меняют одно сопоставление (--path или --remote). policy --unmatched legacy|hooks-silent|deny задаёт поведение для путей без соответствия. exec <name> [--cwd DIR] -- <cmd> запускает дочерний процесс в выбранной области и сохраняет его код выхода при соблюдении pin вызывающей сессии. stamp проверяет/фиксирует владельца базы; worker-agent создаёт конфигурацию и пишет её только с --write. doctor --scan DIR расширяет проверки, --fix-permissions явно меняет права. remove удаляет маршрутизацию, а не данные экземпляра. sessions prune --older-than DAYS --yes навсегда блокирует старые ID native-сессий и не умеет определять работающий процесс harness.

which — предпросмотр маршрутизации пути без pin; его JSON содержит name, reason, matchedPath, matchedRemote, root. show --verify показывает активный экземпляр и диагностику bootstrap/stamp. Одного пути checkout недостаточно для активной области: шаблон remote, --instance/BEE_INSTANCE и pin текущей native-сессии могут влиять на неё. Конфликт завершается кодом 8, не смешивая данные. Для реальной границы между организациями задайте отдельные учётные записи базы и брокера на экземпляр. См. настройку и решение проблем.

Запуск явно разрешённого worker

collaborate launch отправляет задание через существующую аутентифицированную сессию сотрудничества узлу, разрешившему локальный запуск worker. Программу, аргументы, окружение, разрешённые workspace и ёмкость определяет принимающий узел. Сначала проверьте локальную политику; проверка или принятая заявка не доказывают запуск процесса.

bee worker profiles --json
bee worker inspect '<profile>' --space '<space>' --workspace '<workspace-key>' --json
BEE_COLLABORATE_SESSION_ID='<joined-session-id>' bee collaborate launch \
  --request '<stable-uuid>' --node '<exact-node-id>' --profile '<profile>' \
  --workspace '<workspace-key>' --prompt-file task.txt --ttl-seconds 300 --json
BEE_COLLABORATE_SESSION_ID='<joined-session-id>' bee collaborate launch-status --request '<stable-uuid>' --json

--prompt-file - читает stdin; текст задания ограничен 128 КиБ. --ttl-seconds — 5–3600 (по умолчанию 300). Для проверки или отмены (launch-cancel --request ...) используйте тот же устойчивый UUID; новый UUID может создать вторую заявку. Успешный ответ содержит requestId, scope, nodeId, profile, workspace, state, version, время создания/истечения/обновления, cancelRequested и метаданные process. nativeBinding: "not_verified", agentOutcome: "not_assessed", qa: "not_assessed" означают, что квитанция запуска не равна приёмке работы. Проверяйте настоящую сессию harness, файлы и тесты. Неопределённый результат блокирует новые запуски на узле и в пространстве; не обходите это вторым запросом. См. сотрудничество и планы.