Координируйте сохранённый план

Используйте bee plan для координации зависимых шагов между уже зарегистрированными сессиями. Текущая версия Bee включает create, show, next, children, claim, update и comment. Он не запускает агентов, не отправляет задачи автоматически и не выполняет тесты.

Перед началом

Примеры проверены по опубликованным справке/коду и не выполнялись в общем хранилище. Нужны настроенный профиль, доступная MongoDB, включённая совместная работа, поддерживаемый живой native-сеанс с подходящей локальной привязкой и рабочая копия репозитория. Используйте профиль/селектор сеанса из совместной работы. Один скопированный публичный ID не даёт доступа. Справка не подтверждает, что профиль может подключиться и пройти аутентификацию. Команда может завершиться ошибкой при запуске, ещё до чтения или сохранения работы.

1 · Определите работу

Сохраните как plan.json. Замените demo-team и example.com/team/catalog точными значениями настроенных space и идентичности репозитория. Местоположение/revision источника — заявленная ссылка; Bee не получает и не проверяет содержимое. ID и область чувствительны к регистру. У связанного worktree может быть другая область; имя репозитория в списке сеансов не подтверждает доступ к Plan.

Прочитайте фактическую область перед изменением plan.json. Репозиторий берётся из scope в stats, space — из настройки. Сохраняйте селектор сеанса из join для всех команд плана.

bee remember stats --json
bee config get collaboration.space

{
  "schemaVersion": 1,
  "revision": 1,
  "id": "catalog-change",
  "title": "Change catalog prices",
  "scope": {
    "space": "demo-team",
    "repository": "example.com/team/catalog"
  },
  "sources": [
    {
      "location": "docs/prices.md",
      "revision": "requirements-v1"
    }
  ],
  "steps": [
    {
      "id": "implement",
      "title": "Implement price change",
      "acceptanceCriteria": [
        {
          "id": "cents",
          "description": "Prices remain whole cents"
        }
      ]
    },
    {
      "id": "verify",
      "title": "Review tests",
      "dependencyIds": [
        "implement"
      ],
      "acceptanceCriteria": [
        {
          "id": "evidence",
          "description": "Review original test artifacts and runner exit"
        }
      ]
    }
  ]
}

2 · Создайте и прочитайте

Перед первым использованием задайте CREATE_REQUEST_ID, CLAIM_REQUEST_ID, COMPLETE_REQUEST_ID разными новыми UUID в нижнем регистре. Повторяйте точные ID и аргументы только для повтора той же операции. Ниже показаны переменные POSIX-оболочки.

Один раз создайте ID запросов в Bash/zsh (нужен Python 3):

CREATE_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
CLAIM_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
COMPLETE_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"

PowerShell:

$CREATE_REQUEST_ID = [guid]::NewGuid().ToString()
$CLAIM_REQUEST_ID = [guid]::NewGuid().ToString()
$COMPLETE_REQUEST_ID = [guid]::NewGuid().ToString()

bee plan create --file plan.json --request-id "$CREATE_REQUEST_ID" --json
bee plan show catalog-change --json
bee plan next catalog-change --limit 1 --json

show возвращает определение и состояние выполнения. Для нового неизменённого примера next предлагает implement, у которого нет зависимостей. verify готов только после сообщения о завершении зависимости. Это ожидаемая проекция определения, а не запись успешного живого запуска. next лишь предлагает и не резервирует работу. Возвращается до пяти шагов; проверяйте hasMore и счётчики пропусков.

3 · Возьмите работу и сообщите результат

Используйте claim generation из ответа claim. Сохраните в summary.txt одну строку UTF-8 без пробелов по краям и перевода строки, например Implementation ready for review. Следующий update сообщает о завершении, но не подтверждает его качество:

bee plan claim catalog-change implement --revision 1 --lease-seconds 300 --request-id "$CLAIM_REQUEST_ID" --json

До истечения lease продлите его с последним полученным claim generation. Нужен новый ID запроса; чтение плана не продлевает lease. В завершающем обновлении также используйте generation, полученный при продлении.

RENEW_REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
bee plan update catalog-change implement --revision 1 --claim-generation <returned-generation> --state renew --lease-seconds 300 --request-id "$RENEW_REQUEST_ID" --json

PowerShell:

$RENEW_REQUEST_ID = [guid]::NewGuid().ToString()
bee plan update catalog-change implement --revision 1 --claim-generation <returned-generation> --state renew --lease-seconds 300 --request-id "$RENEW_REQUEST_ID" --json

До команды завершения создайте сводку без завершающего перевода строки:

printf 'Implementation ready for review' > summary.txt

PowerShell:

[IO.File]::WriteAllText((Join-Path (Get-Location).Path 'summary.txt'), 'Implementation ready for review', [Text.UTF8Encoding]::new($false))

bee plan update catalog-change implement --revision 1 --claim-generation <returned-generation> --state reported_complete --summary-file summary.txt --request-id "$COMPLETE_REQUEST_ID" --json

--revision 1 — неизменная версия определения. Необязательный --if-version N проверяет текущую версию общего состояния. Запрошенный срок claim — 30–300 секунд; оставшийся срок сеанса может сократить его; чтение и повторы не продлевают его. running/blocked сохраняют владение; failed/abandoned освобождают; reported_complete освобождает и открывает зависимые шаги. renew явно продлевает действующее владение. После истечения срока или повторного входа старая generation не может завершить заново взятую работу.

Дочерние планы и прямые зависимости

Определение дочернего плана содержит неизменяемые parentId, parentStepId и parentRevision. children перечисляет прямых потомков выбранного родителя, при желании — одного шага. Команда не обходит потомков рекурсивно, не меняет определение родителя и не завершает его шаг. Для следующей ограниченной страницы (1–5 строк) используйте nextAfter; сохранённый курсор служит только для пагинации.

bee plan children catalog-change --limit 5 --json
bee plan children catalog-change implement --limit 5 --json
bee plan children catalog-change --after "$NEXT_AFTER" --limit 5 --json

В JSON дочернего плана укажите реальные ID родителя и шага и его revision. Перед распределением работы прочитайте возвращённый план и список детей. Требования к активной сессии описаны в совместной работе.

Восстановитесь без дублирования

Код 2 означает отсутствие инициализации, 3 — объект не найден, 4 — неверный ввод/определение, 5 — недоступность или неизвестный исход, 8 — конфликт, например потерянное владение или блокирующая зависимость. Другие отказы могут дать 1. Читайте код ошибки вместе с кодом процесса. При outcome_unknown сохраняйте точные request ID и содержимое: запись уже могла произойти. При известном конфликте владения прочитайте состояние и получите действующее владение до новой операции. Определения неизменяемы; update меняет состояние выполнения, а не текст плана.

Чего не доказывает завершение

reported_complete — отчёт исполнителя. Критерии приёмки являются требованиями, а не доказательством прохождения. Текущая версия Bee включает диагностическую bee qa assess и явную bee qa run: последняя выполняет заданную спецификацию проверок и может сообщить verifiedCompletion=true для объявленных критериев, но уровень доверия — in_process_only. Качество проверок и субъективную цель нужно оценить отдельно. Храните анализ компилятора, исходный вывод тестового раннера, идентификатор исходников и независимый review вместе со статусом плана. Сводка TRX сама по себе не доказывает выполнение всех нужных тестов.

Жизненный цикл совместной работы · Работа с кодом · Справочник команд