Использование CLI

Инструмент командной строки awr — полная точка входа для управления проектом AWR: всё, что агент может делать через MCP, вы можете делать из терминала — плюс администрирование проекта, которое MCP не предоставляет.

Установка

Оба канала пакетов устанавливают один и тот же Rust CLI и MCP-сервер; отдельного JavaScript- или Python-SDK нет:

npm install -g @originoneai/agent-work-runtime@0.5.1
# or, in a Python virtual environment
python -m pip install agent-work-runtime==0.5.1

Проверьте с помощью awr --version и awr-mcp --version.

Поддерживаемые цели: macOS 15+ (arm64 и Intel), Linux с glibc 2.39+ (базовый уровень Ubuntu 24.04, x64 и arm64) и Windows x64. Загрузчик npm требует Node 22.14+ и опирается на опциональные нативные пакеты, поэтому не отключайте опциональные зависимости; загрузчик PyPI требует Python 3.9+. В Linux проверьте glibc командой ldd --version | head -n 1. Git требуется только для операций, связанных с Git; SQLite встроен. Пошаговое руководство по первому проекту — в Быстром старте.

Форма каждой команды

Примеры CLI во всей документации используют общий префикс:

awr --project /absolute/project --json <command>

--project указывает на корень проекта; --json переключает stdout на один машиночитаемый JSON-объект (детали ниже). Опускайте --json, когда читаете вывод сами, — человекочитаемый вывод по умолчанию намеренно ограничен: status показывает не более одного текущего предложения, а ready перечисляет не более 10 элементов.

Проверка состояния проекта

status — ваша первая остановка. Его представление action по умолчанию показывает текущее продолжение, доступную для захвата работу, ожидания, фактические блокировки и сводку истории:

awr --project /absolute/project status --view full --branch main

--view action/full/summary — по умолчанию action; full даёт прежнюю полную структуру.
--branch NAME_OR_ID — читает ветку по имени, внутреннему ID или main вместо ветки по умолчанию. Выбор ветки для чтения никогда не меняет ветку по умолчанию, сессии, захваты или ваш Git checkout.

ready перечисляет элементы работы, которые можно подобрать, с диагностикой, информацией о захватах и подсказками об усечении. --limit по умолчанию равен 10 и принимает значения от 1 до 100; --branch работает и здесь:

awr --project /absolute/project ready --limit 25

Чтение элементов работы

work show даёт один элемент полностью — задачу, критерии приёмки, зависимости, решения, свидетельства и происхождение. --source-sha SHA читает его по состоянию на конкретную ревизию источника; --branch читает его на другой ветке:

awr --project /absolute/project work show W-123 --source-sha abc123

search находит элементы по всему проекту. Текст запроса позиционный; --type, --status, --work и --limit сужают результаты:

awr --project /absolute/project search "payment retry" --type work --limit 20

Компиляция контекста для задачи

context compile собирает контекст выполнения L1 — бюджетированный рабочий набор для задачи — с полнотой, пробелами, происхождением и хешем контекста:

awr --project /absolute/project context compile --work W-123

Все эти параметры необязательны: --session и --detached управляют привязкой сессии; --agent, --intent и --budget направляют компиляцию; --goal, --path и --tag повторяемы; --source-sha компилирует по конкретной версии источника; --checkpoint и --after-revision задают пользовательские базовые линии и взаимно исключают друг друга. --branch ID использует обычную базовую линию контекста на другой ветке — это другое значение, чем у branch context, которая компилирует инкремент именованной ветки с момента её ответвления, не переключая вашу ветку по умолчанию:

awr --project /absolute/project branch context feature-x --work W-123

Текстовый вывод по умолчанию — ограниченный бюджетом контекст выполнения с полными критериями приёмки и сохранёнными жёсткими правилами. Если есть обязательные пробелы, JSON-результат содержит ok=false с error.code=ContextIncomplete; если жёсткие факты превышают бюджет, вы получаете BudgetExceeded — факты никогда не усекаются молча.

Продвижение работы

Элементы работы меняют состояние через подкоманды work:

awr --project /absolute/project work progress W-123 \
  --session S-1 --reason "starting implementation" --expected-revision 10

Та же форма применяется к block, unblock, cancel и reopen, при этом --next-action, --summary и --blocker несут соответствующие детали. Завершение привязывает критерии приёмки и свидетельства из JSON-файла и при успехе освобождает захват этой сессии:

awr --project /absolute/project work complete W-123 \
  --session S-1 --reason "all checks green" \
  --input /absolute/completion.json --expected-revision 10

Запись событий и свидетельств

event append пишет в журнал проекта:

awr --project /absolute/project event append \
  --type note --summary "reviewer asked for retry tests" \
  --expected-revision 11

Необязательные флаги: --work, --session, --branch, --importance (по умолчанию normal) и --payload FILE (файл со значением JSON, {} при пропуске). Вывод по умолчанию показывает ID, тип, краткое описание и версию — он не повторяет полезную нагрузку; используйте event show --full, чтобы развернуть событие явно. Вы не можете подделать зарезервированные доменные события вроде work.completed; они возникают только из команд изменения состояния.

evidence add записывает свидетельство из входного JSON-файла:

awr --project /absolute/project evidence add \
  --input /absolute/evidence.json --expected-revision 11

Входные поля включают work_item_key, branch_id, external_key, evidence_type, level, summary, locator, sha256, source_sha, command, scope и verified_at. Успешная запись возвращает сохранённую запись и event_id, но запись — это не выполнение: validation_basis=caller_supplied_bindings означает, что AWR сохранил привязки, которые вы передали, — а не то, что он выполнил вашу команду или что бизнес-приёмка прошла. evidence show даёт сводное представление записи для чтения; это не квитанция о записи.

Правила путей и размеров: относительные пути во входных данных свидетельств и полезных нагрузках событий разрешаются относительно корня --project; относительные пути во входных данных завершения разрешаются относительно текущего каталога процесса, поэтому в автоматизации используйте абсолютные пути. Входные файлы свидетельств и полезные нагрузки событий ограничены 1 МиБ, входные файлы завершения — 64 КиБ.

Ревизии и оптимистичная конкурентность

Записи принимают --expected-revision R, где R — последняя наблюдавшаяся вами project_revision. Если проект ушёл вперёд, запись завершается ошибкой RevisionConflict вместо молчаливой перезаписи чужой работы — перечитайте состояние через status и повторите с новой ревизией. В выводе встречаются три номера версий, и они не взаимозаменяемы: revision — версия объекта, source_revision — версия источника, а project_revision — версия состояния проекта.

Если запись прервана или применена частично, проверьте предложение, события, сессию и текущую ревизию, прежде чем решать, что делать дальше, — не повторяйте вслепую после сбоя процесса. Две ошибки рабочей области заслуживают упоминания: WorkspaceConflict (из awr workspace) означает, что обе стороны редактировали один и тот же отслеживаемый файл и ничего не сливается автоматически; WorkspaceContended означает, что publish или drop были вытеснены три коммита подряд, и средство — просто выполнить ту же команду снова.

Вывод JSON, ошибки и коды выхода

С --json успешная команда печатает ровно один JSON-объект в stdout. Ошибки — типизированный JSON в stderr:

{
  "code": "RevisionConflict",
  "message": "revision conflict: expected 10, actual 11",
  "details": {"expected": 10, "actual": 11}
}

Разбирайте два потока отдельно — никогда не объединяйте их через 2>&1 и не разбирайте объединённый текст. code и details — машиночитаемая основа для решений; message — для людей. --json может стоять до или после известной подкоманды; поставьте его перед командой, чтобы получать JSON-ошибки для неизвестных команд верхнего уровня. Коды выхода:

0 — успех (также --help и --version).
1 — доменная ошибка (типизированная ошибка в stderr), возможно, с частичным, доступным для инспекции телом в stdout; также Unsupported для нереализованных команд верхнего уровня.
2 — отсутствующие или недопустимые аргументы или неизвестные вложенные подкоманды; InvalidInput в режиме --json.

Где заканчивается CLI и начинается MCP

CLI и MCP-сервер предоставляют одно и то же доменное состояние: для общих инструментов работы и контекста оба возвращают одни и те же идентификаторы, версии, критерии приёмки, зависимости, диагностику и пробелы при одном и том же проекте, выборе ветки, проиндексированном источнике и параметрах. Разница — в позиции:

CLI — полная точка входа для управления проектом, и его чтения могут обновлять перестраиваемые проекции базы данных (source_refresh).
Инструменты чтения MCP строго только для чтения (read_only=true). Если источник изменился, чтение MCP отказывается от устаревшего снимка с SourceStale вместо обновления; выполните awr source reindex и прочитайте снова.
MCP через stdio предоставляет фиксированный каталог инструментов для клиентов агентов (общий HTTP-сервис добавляет инструменты каталога проектов); администрирование за пределами этого каталога остаётся в CLI.

На практике вы управляете настройкой, администрированием, переиндексацией и разовыми расследованиями из терминала, а ваш клиент агента вызывает MCP-инструменты во время сессии. См. Инструменты MCP для стороны агента и Устранение неполадок, когда что-то идёт не так.