Управляйте командой кодирования с несколькими агентами с Herdr

Последнее тестирование и обновление: 17 августа 2026 года, против Herdr 0.8.0. CLI Herdr, Grok и worker-agent быстро меняются; перед использованием этого в продакшн-репозитории ознакомьтесь с официальной документацией по ссылке.

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

Наш рабочий паттерн имеет три четко различимых уровня:

Слой	Работа	Что это не доказывает
Модель умного оркестратора	Делить цель на ограниченные задачи, выбирать работников, проверять доказательства и решать, что делать дальше	Проверять, что работник действительно выполнил задачу или что его вывод корректен
Herdr	Создавать и организовывать терминалы, запускать агентов, отправлять запросы, наблюдать состояние, читать вывод и держать сессии доступными	Изоляция файловой системы или учетных данных
Изолированная рабочая среда	Дайте каждому работнику свою собственную кассу, процессы и разрешённые ресурсы	Чтобы объединённый результат прошёл проверку

Мы используем высокопроизводительную модель Grok для роли оркестратора и изолированные рабочие среды для выполнения. Herdr — это соединительная ткань. Вы можете использовать другого поддерживаемого агента в качестве оркестратора; важна не марка модели, а контракт между слоями.

Рисунок 1: Официальный сайт Herdr представляют его как среду выполнения, в которой живут агенты кодирования. Это устаревший скриншот продукта, а не макет рабочего процесса нашей команды.

Что вы завершите

К концу этого руководства вы сможете:

1. установить и проверить Herdr;
2. открыть один репозиторий как постоянное рабочее пространство;
3. запустить именованных рабочих агентов в отдельных панелях или средах;
4. давать команды, ждать и собирать результаты через CLI, который учитывает агента;
5. справляться с заблокированными, застопорившимися, истекшими по времени и неизвестными состояниями без слепой отправки клавиш; и
6. определить контроль завершения на основе артефактов и тестов, а не на основании того, что агент сказал «готово».

Почему Herdr подходит для многокомандных задач

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

Herdr предоставляет вам три примитива:

• a рабочее пространство организует один проект, задачу или исследование;
• a панель является настоящей оболочкой для агента, тестового процесса, сервера или журналов;
• an агент является поддерживаемым процессом кодирующего агента, который Herdr может идентифицировать и адресовать по состоянию жизненного цикла.

Такое разделение позволяет системе масштабироваться лучше, чем стена анонимных вкладок терминала. Оркестратор может нацеливаться researcher вместо того чтобы угадывать, что «третья панель справа» всё ещё содержит тот же процесс.

Сервер Herdr владеет панелями. Терминальный интерфейс является только клиентом. Отключите клиент, и процессы продолжат работу на включённом хосте; подключитесь позже, и активные панели всё ещё будут там.

Перед установкой

Вам потребуется:

• macOS или Linux для текущего стабильного пути; нативная Windows остаётся только в бета-версии предварительного просмотра;
• как минимум один поддерживаемый CLI coding-agent уже установлен и аутентифицирован;
• jq для примеров автоматизации, которые анализируют JSON-ответы Herdr;
• одноразовое хранилище для первого запуска; и
• отдельные контрольные бюджеты для каждого поставщика моделей или платной подписки агента.

Проверьте инструменты, которые вы планируете использовать:

git --version
jq --version
grok --version       # только если Grok CLI является вашим оркестратором
codex --version      # пример рабочего; используйте CLI, который вы действительно запускаете

Не вставляйте API-ключи в подсказки Herdr, скриншоты или файлы репозитория. Herdr владеет реальными терминалами, поэтому процессы могут видеть все, что доступно текущему пользователю ОС и окружению.

Установите Herdr

На macOS или Linux официальным прямым установщиком является:

curl -fsSL https://herdr.dev/install.sh | sh

Если вы уже используете Homebrew:

brew install herdr

Прямой установщик и Homebrew представляют собой разные пути обновления. Используйте один; не насло́вывайте их и не пытайтесь угадать, какой бинарник нашел ваш shell.

Откройте новый терминал и проверьте бинарный файл:

herdr -V
herdr статус

Для этого руководства ожидаемая строка версии:

herdr 0.8.0

Если у вас более новая версия, используйте установленный бинарный файл как эталон синтаксиса:

herdr --help
herdr агент
herdr панель
herdr рабочее пространство

Не выполняйте команду с изменением состояния без полного понимания её работы. herdr workspace create, например, допустима с настройками по умолчанию и создаст состояние.

Запустите первую рабочую область

Перейдите в временный репозиторий и запустите Herdr:

cd /path/to/disposable-repository
herdr

Когда в сессии нет рабочих областей, Herdr открывает одну. Используйте мышь, если предпочитаете: щелкайте по панелям и рабочим областям, перетаскивайте границы разделения и щелкайте правой кнопкой мыши, чтобы создать панель. Пользователи клавиатуры могут нажать ctrl+b, затем v чтобы разделить вправо или - чтобы разделить вниз.

Отсоединяйтесь, не останавливая работу:

ctrl+b q

Повторное присоединение:

herdr

Делать не использовать herdr server stop как команда отсоединения. Остановка сервера завершает процессы его панели.

Обучите оркестратор управлять Herdr

Herdr поставляется с агентским навыком, соответствующим версии выпуска. Выведите его из установленного исполняемого файла:

herdr --skill

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

npx навыки добавить herdrdev/herdr --skill herdr -g

Пропустить -g для навыка в рамках проекта. Навык начинается с полезной проверки безопасности: управляющий агент должен использовать Herdr только когда HERDR_ENV=1 подтверждает, что он работает внутри панели, управляемой Herdr.

Если Grok CLI является оркестратором, установите интеграцию Herdr для Grok после того, как Grok создаст свой каталог конфигурации:

herdr интеграция install grok
herdr интеграция статус

Текущая интеграция сообщает личность сеанса Grok через SessionStart хук. Состояние жизненного цикла по-прежнему поступает от обнаружения экрана Herdr. Хук позволяет Herdr возобновить сохраненный сеанс с использованием родного grok --resume <id> пути Grok после перезапуска сервера; он не настраивает модель и не предоставляет Grok дополнительных разрешений.

Запустите оркестратор внутри в панели Herdr, используя команду Grok и выбор модели, уже проверенные для вашей учетной записи. Затем предоставьте ему операционный контракт, например:

Вы являетесь оркестратором этого репозитория.

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

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

Завершите с измененными файлами, выполненными проверками, сбоями, неразрешенными решениями и затратами или использованием, которые могут быть наблюдаемы.

Этот запрос является политикой, а не границей изоляции. Обеспечивайте доступ с помощью среды рабочего процессора и разрешений ОС.

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

Самое простое первое упражнение — держать рабочие процессы в соседних панелях временного чекаута. С панели Herdr оркестратора:

тест "${HERDR_ENV:-}" = 1

research_split=$(herdr панель сплит --current --direction вправо --cwd "$PWD" --no-focus)
research_pane=$(printf '%s
' "$research_split" | jq -r '.result.pane.pane_id')

обзор_раздела=$(herdr панель сплит --current --direction вниз --cwd "$PWD" --no-focus)
панель_обзора=$(printf '%s
' "$review_split" | jq -r '.result.pane.pane_id')

Всегда анализируйте возвращаемые идентификаторы. Не предсказываете их по порядку в боковой панели.

Запустите CLIs рабочих процессов, которыми вы действительно пользуетесь. Эти примеры используют только Codex, чтобы показать синтаксис Herdr:

herdr агент старт исследователь --вид codex --панель "$research_pane"
herdr агент старт рецензент --вид codex --панель "$review_pane"

Аргументы родного агента идут после --. Флаги модели относятся к CLI этого агента, а не к Herdr:

herdr агент старт рецензент --вид codex --панель "$review_pane" -- -m <режим_проверенного_работникал>

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

Проверьте текущие запасы:

herdr агент список
herdr агент получить исследователь
herdr агент получить рецензент

Дайте каждому работнику контракт на артефакт

Избегайте подсказок типа «исследуй это» или «исправь приложение». Контракт работника должен указывать свою область, результат и проверку.

herdr агент подсказка исследователь "$(кот <<'PROMPT'
Исследуйте текущий поток аутентификации в этом одноразовом репозитории.
Только читайте; не редактируйте исходные файлы.
Запишите вывод в /tmp/auth-research.md с:
1. точками входа,
2. потоком данных,
3. рисками с указанием файла и строки,
4. нерешенными вопросами.
Ответьте только путем к артефакту.
ПОДСКАЗКА
)" --ожидать --таймаут 180000

Затем соберите видимый результат:

herdr агент читать исследователь --источник недавно_распакованные --строки 120

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

Используйте отдельный контракт для рецензента:

herdr агент подсказка рецензент "$(кот <<'PROMPT'
Проверьте /tmp/auth-research.md по сравнению с текущим репозиторием.
Не редактируйте исходные файлы.
Сообщайте о неподдерживаемых утверждениях, отсутствующих доказательствах и трех самых рискованных пробелах.
Напишите рецензию в /tmp/auth-review.md и отвечайте только этим путем.
ПОДСКАЗКА
)" --ожидать --таймаут 180000

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

Размещайте сотрудников в изолированных средах

Рабочее пространство Herdr является организационным контейнером, а не границей безопасности. Две панели в одном и том же чекауте могут перезаписать один и тот же файл. Git worktree уменьшает количество столкновений файлов, но каждый процесс по-прежнему выполняется от имени одного и того же пользователя ОС, если только другой инструмент не изолирует его.

Для работы с низким риском на локальном уровне Herdr может создавать отдельные чекауты Git worktree:

herdr рабочее_дерево создать --cwd "$PWD" --ветка agent/research --метка исследование --no-focus
herdr рабочее_дерево создать --cwd "$PWD" --ветка agent/build --метка сборка --no-focus

Herdr группирует эти чекауты в рабочие пространства. Закрытие рабочего пространства не удаляет чекаут или ветку. Удаление worktree — это отдельная, потенциально опасная команда; Git откажется от грязного чекаута, если не будет предоставлен --force соответствующий параметр.

Для командного производственного стека создайте среды с Gas Town сначала, запишите их точные пути и откройте эти пути в Herdr:

исследовательская_среда=/absolute/path/returned/by/gastown-for-research
среда_сборки=/absolute/path/returned/by/gastown-for-build

тест -d "$research_env" && тест -d "$build_env"
herdr рабочее пространство создать --cwd "$research_env" --метка исследование --no-focus
herdr рабочее пространство создать --cwd "$build_env" --метка сборка --no-focus

Используйте точные команды из связанного учебника Gas Town; не придумывайте пути и не предполагайте, что разные каталоги означают разные учетные данные. Слой изоляции должен определять доступ к файловой системе, секретам, сетевой доступ и очистку.

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

HERDR_АГЕНТ=клод <sandbox-wrapper> -- claude

Устанавливайте это предложение только на процессе оболочки. Не экспортируйте его глобально.

Понимать конечный автомат

Herdr сообщает о пяти полезных состояниях:

Состояние	Оперативное значение	Что должен делать оркестратор
working	Распознанный агент выглядит активным	Ждите с конечным тайм-аутом; не добавляйте дублирующие инструкции
blocked	Herdr распознал интерфейс одобрения, разрешения или вопроса	Прочитайте панель и направьте решение человеку
done	Фоновая работа завершена и еще не была просмотрена	Прочтите вывод и проверьте артефакт
idle	Агент готов к вводу и был замечен	Проверьте результат перед назначением дополнительной работы
unknown	Herdr не может уверенно классифицировать агента	Проверьте вручную; никогда не считайте это успехом

agent prompt --wait отслеживает состояние жизненного цикла, а не уникальный идентификатор задачи. Если вы запустите уже работающего агента, конец его текущего шага может удовлетворить ожидание. Для точной производственной работы назначайте одну ограниченную задачу за раз и требуйте уникально названный артефакт.

Безопасно обрабатывайте заблокированных агентов

Явно ждите точки принятия решения человеком, когда это то событие, которое вам нужно:

herdr агент ждать рецензент --до заблокировано --таймаут 120000
herdr агент читать рецензент --источник недавно_распакованные --строки 80

Если пользовательский интерфейс является безопасным тестом и вы сознательно решили его отклонить, используйте логические клавиши:

herdr агент отправить_клавиши рецензент эск

Не создавайте оркестратор, который отправляет enter каждый раз, когда работник заблокирован. Блокировка может быть утверждением развертывания, удалением файла, запросом учетных данных или вопросом, от ответа на который зависит задание.

Проверяйте результаты вне разговора с агентом

Состояние «завершено» агента означает, что терминал завершился. Это не означает, что код правильный.

Используйте отдельную панель для детерминированной проверки:

тест_раздела=$(herdr панель сплит --current --direction вниз --cwd "$PWD" --no-focus)
тест_панель=$(printf '%s
' "$test_split" | jq -r '.result.pane.pane_id')

herdr панель запуск "$test_pane" "npm test"
herdr панель ждать-вывод "$test_pane" --регекс "passed|failed|error" --таймаут 180000
herdr панель читать "$test_pane" --источник недавно_распакованные --строки 160

pane wait-output ищет текст в терминале; он не понимает, была ли успешной тестовая группа. Также может совпадать существующий вывод. Предпочтительнее использовать реальный код выхода команды или машиночитаемый отчет, если ваш каркас его предоставляет. Чтение терминала является доказательством для человека, а не заменой CI.

Используйте этот язык завершения:

• Подготовлено: оркестратор создал план или подсказку.
• Выполняется: назначенный рабочий активен.
• Сообщено о выполнении: рабочий завершил работу и выдал заявленный результат.
• Проверено: назначенный артефакт был проверен, и независимая проверка прошла успешно.
• Интегрировано: принятые изменения были объединены, и все комбинированные проверки прошли успешно.

Обработка сбоев

Подсказка возвращает agent_blocked

Herdr не отправил подсказку, так как агент уже находился в интерфейсе одобрения или вопроса. Проверьте это:

herdr агент получить <имяe>
herdr агент читать <имяe> --источник видно

Направьте решение человеку. Не повторяйте запрос, пока блокировка не будет устранена.

Подсказка возвращает agent_prompt_stalled

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

herdr агент читать <имяe> --источник видно
herdr агент объяснить <имяe> --подробно

Время ожидания истекло

Тайм-ауты и ошибки сервера выводят JSON в stderr и завершаются с кодом состояния 1; ошибки синтаксиса CLI завершаются с кодом состояния 2. Тайм-аут означает «не завершено в пределах этого окна», а не «ошибка». Проверьте текущее состояние и вывод перед тем, как решать, продлевать, прерывать или отменять.

Состояние выглядит неправильным

Выполнить:

herdr агент объяснить <имяe> --подробно
herdr сервер обновить-агент-манифесты

Обнаружение блокировки Herdr специально строгое. Может появиться новый интерфейс агента idle вместо blocked до тех пор, пока его манифест не поймёт форму экрана.

Результат прокрутился за пределы видимости

Попробовать:

herdr агент читать <имяe> --источник недавно_распакованные --строки 160

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

Herdr обновлён, но запущенный сервер старый

Проверить:

herdr -V
herdr статус

Для версий с прямой установкой, herdr update управляет бинарным файлом. Установки через Homebrew, mise и Nix должны обновляться через их менеджер пакетов. Остановка сессии для смены серверов завершает процессы панели, поэтому сначала дождитесь безопасной контрольной точки.

Вам нужны диагностические логи

Каталог логов по умолчанию ~/.config/herdr/:

herdr.log
herdr-client.log
herdr-server.log

Для воспроизведения отладки:

HERDR_LOG=herdr=отладка herdr

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

Границы безопасности

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

• Рабочие области не являются песочницами. Они организуют панели.
• Рабочие деревья не обеспечивают изоляцию безопасности. Они разделяют проверки Git, но обычно используют одного и того же пользователя, сеть и учетные данные.
• Переменные среды передают полномочия. Передавайте только те учетные данные, которые нужны работнику; предпочтительны короткоживущие токены.
• Заблокированный ввод по умолчанию относится к человеку. Никогда не одобряйте автоматически развертывание, удаление, покупку или запросы учетных данных.
• Вывод терминала может содержать секреты. История панели по умолчанию отключена не случайно.
• Удалённый доступ использует SSH. Сначала проверьте обычное ssh <host> , используйте ключи с паролем и ssh-agent, и держите удалённый хост обновлённым.
• Остановка разрушает работающие процессы. herdr server stop и herdr session stop <name> завершает процессы панели.
• Плагины и интеграции выполняют код. Устанавливайте только официальную интеграцию или плагин, чей исходный код и разрешения вы проверили.

Контроль затрат

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

Используйте четыре контроля:

1. Дайте оркестратору бюджет на планирование, а рабочим — меньшие бюджеты на выполнение.
2. Установите конечные тайм-ауты для каждого ожидания; бесконечное ожидание является настройкой по умолчанию в Herdr, когда --timeout опущено.
3. Начните с двух работников. Добавляйте параллелизм только тогда, когда потоки действительно независимы.
4. Требуйте артефакты и проверку, чтобы ошибки работы обнаруживались до начала следующего дорогостоящего этапа.

Не публикуйте статические цены Grok 4.6 до тех пор, пока xAI не опубликует официальную страницу модели или живую запись вашей модели в аккаунте. API xAI предоставляет GET /v1/models конечную точку, которая возвращает модели и цены, доступные для аутентифицирующегося аккаунта; ответ аккаунта является правильной текущей проверкой.

Цикл оркестрации производства

Используйте эту последовательность для реальной работы:

1. Определить: напишите критерии принятия, исключенный объём и команду проверки.
2. Изолировать: создайте одну среду Gas Town для каждого потока с возможностью записи; сохраните возвращённые пути.
3. Разместить: открывайте каждый путь как рабочее пространство или панель Herdr, не отвлекая фокус.
4. Запустить: запускайте одного именованного рабочего на каждой линии и проверяйте, что он достиг цели idle.
5. Подсказка: отправляйте ограниченную задачу с путем артефакта и конечным тайм-аутом.
6. Наблюдать: ожидайте состояние жизненного цикла; маршрутизируйте blocked к человеку; проводите инспекцию unknown вручную.
7. Собрать: читайте артефакт из изолированной среды, а не только из трансляции терминала.
8. Проверить: выполняйте тесты, проверку стиля, проверку типов, обзоры или проверку исходного кода независимо.
9. Интегрировать: объединяйте только принятые работы и повторно запускайте объединенные проверки.
10. Закрыть: фиксируйте нерешенные работы и наблюдаемые затраты, затем тщательно очищайте среды.

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

Ворота завершения

Не отмечайте этот учебник как завершённый, потому что видны три агента. Отметьте его как завершённый, когда все шесть утверждений будут верны:

1. herdr -V записывает установленную версию.
2. Одноразовая рабочая зона сохраняется при отсоединении и повторном присоединении, пока хост остаётся активным.
3. Два именованных работника появляются в herdr agent list.
4. Каждый работник создал отдельный, проверяемый артефакт.
5. Заблокированный или истёкший по времени тест был обработан без слепого одобрения.
6. Независимая проверка — а не проза работника — решила, прошёл ли результат.

Источники и дополнительная литература

• Официальный сайт Herdr
• Установите Herdr
• Быстрый старт
• Концепции Herdr
• Автоматизация агентов
• Поддерживаемые агенты и государственные органы
• Интеграции, включая Grok CLI
• Состояние сеанса и восстановление
• Сохранение данных и удаленный доступ
• Справочник CLI
• Устранение неполадок и журналы
• Официальный репозиторий Herdr и лицензия Apache-2.0
• Документация моделей xAI
• Конечная точка REST моделей xAI