Ducklab

Полноцикловый харнесс разработки ПО, который мульти-LLM по умолчанию и честен по построению.

В одном блоке: самохостинговый харнесс разработки (движок на Go + CLI + десктоп, в первую очередь Linux) · бриф → требования → спека → план → сборка → ревью → релиз · вердикты — это коды выхода, а не мнения моделей · локальные модели в первую очередь (llama.cpp, vLLM) рядом с любым OpenAI-совместимым или Anthropic-эндпоинтом · управляется людьми или другими агентами через MCP с записанными и атрибутированными решениями · Apache-2.0 · развивает сам себя (записи запусков в .ducklab/ — это чеки). Агенты: начните с AGENTS.md и llms.txt.

Вы даёте ему бриф. Он пишет требования, спеку и план; собирает задачи одной моделью или несколькими в споре; прогоняет реальный тестовый гейт вашего проекта; и останавливается перед вами до того, как что-либо будет закоммичено. Каждый вызов модели логируется. Ни одна модель никогда не решает вердикт.

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

Зачем это существует

Большинство агентных инструментов для кодинга предполагают одну сильную модель и доверяют ей. Ducklab предполагает несколько дешёвых моделей и не доверяет ни одной из них:

• Гейт решает, никогда не модель. Вердикт — это код выхода команды. Запуск test-first измеряет зелёный бейзлайн до того, как написан любой тест, красный на новом тесте после, и каждое принятие воспроизводит гейт из чистого чекаута закоммиченного sha — ничего не попадает в код, что не воспроизвелось, и принятие, чьё воспроизведение провалилось, откатывает собственный коммит.

• Декорреляция везде. Ревьюит другая модель; ревьюер никогда не узнаёт, кто написал код (отсутствует в полезной нагрузке, а не скрыт в UI); судьи турнира выбирают вслепую; критики совета читают черновик, а не друг друга.

• Работа — это контракт. Результаты задачи — это нумерованный чеклист исполнителя; он отчитывается по каждому пункту по номеру, ревьюер проверяет каждый пункт по диффу, а невыполненный пункт вызывает резиновую утку — место советника, которое просыпается только на измеренный дистресс (отказы тормозов, серии провалов, красные гейты) и отвечает none, заметкой, которая отправляет исполнителя прямо обратно к работе, или stop.

• Места выбираются на основе доказательств. Каждый утёнок несёт карточку результатов — процент прохождения в кресле из ваших собственных запусков, стоимость за запуск, индекс кодинга — и доска ростера предлагает места на её основе, причём критерии ранжирования ваши, чтобы переупорядочить. Предложения редки и обоснованы: показатели прохождения ранжируются по нижней границе Уилсона, минимум три запуска, локальные никогда не выигрывают по цене $0.

• Ничто не безгранично. Ходы, токены, стоимость, стенное время, вывод инструментов, команды оболочки — каждый потолок виден и поднимаем в середине запуска, на записи.

• Ваша документация не ограничена окном модели. Прикрепите вики к этапу, и большое кресло прочитает её целиком; маленькое кресло получает каждый документ переваренным под размер, полный текст — в одном вызове ref_read вдали, а гейт называет любой документ, который никто не открыл. Локальную модель на 32k можно ввести в курс дела четвертью миллиона символов справочного материала — харнесс несёт рабочую память.

И доказательство существования: ducklab разрабатывается внутри ducklab. План, баги, релизы и последние девяносто с лишним принятых задач прошли через его собственный цикл, управляемый теми же локальными и хостинговыми моделями, которые он измеряет — самые последние функции (мультимодальный чат, кресло консультанта, история запусков направляющей рейки) были построены уткой, с гейтом от человека.

Related MCP server: Loki Mode

Статус

v0.6.1+, движется быстро. Семь этапов, пять режимов, доска ростеров с доказательствами и предложениями, справочные документы с автоматическим перевариванием, навыки, управляемые с десктопа, усаженный консультант, с которым можно чатиться (включая изображения, зрение проверяется до их отправки), баги с доказательствами в виде скриншотов, релизы, автопилот, CLI, десктоп-приложение и MCP-сервер, который позволяет другой модели управлять всем циклом с записанными и атрибутированными решениями.

docs/status.md отслеживает все критерии приёмки и не округляет. Где код и спека расходятся, разница записана в docs/decisions/.

Установка

Нужны Go 1.25+, Node 22+ для десктопа и git.

Linux

CLI и движок — чистый Go. Десктоп — это приложение Wails v3 и ему нужны пакеты разработки GTK/WebKit:

sudo apt install libgtk-3-dev libwebkit2gtk-4.1-dev   # Debian/Ubuntu names
make desktop && make install

На Ubuntu 24.04+ десктопу также нужен профиль AppArmor — см. решение 0003 и packaging/apparmor/.

macOS

xcode-select --install    # the desktop build links against WebKit
brew install go node
make desktop && make install

Заметка о честности: ducklab разрабатывается и ежедневно используется на Linux. CLI и движок проходят проверку компиляции для darwin/arm64 при каждом make cross, но ни одна сборка десктопа ещё не была проверена на Mac — первый человек, который попробует, и есть тест, а make install в любом случае даёт вам CLI и движок. Пожалуйста, сообщайте обо всём, что ломается.

Обе системы

make install устанавливает в ~/.local/bin — убедитесь, что он в вашем PATH. Он предупреждает, когда бинарник десктопа старше frontend/src, потому что он с радостью установит устаревший.

Три бинарника

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

Цикл, от начала до конца

С десктопа: Projects → New project, затем Cycle → Draft it. Из терминала:

cd ~/dev/myproject
git init                                    # ducklab needs a git repo
ducklab project init --name MyProject       # auto-starts the engine if none is running

ducklab intake --from brief.txt             # brief        → requirements
ducklab spec                                # requirements → spec
ducklab plan                                # spec         → milestones and tasks

ducklab run T-001                           # build it
ducklab run accept r-20260729-...           # commit it

ducklab review T-001                        # read the commit
ducklab release plan --bump minor           # what shipped

Каждый этап сначала пишет файл .proposed и ждёт вас. accept продвигает его; reject восстанавливает ровно то, что записал запуск, и ничего больше; «request changes» отправляет любой черновик — спеку, план, заметки к релизу — обратно с вашей заметкой. Ничто не коммитится без вас (или без уровня автономии, который вы явно предоставили).

Справочные документы едут на любом этапе: --ref ~/wiki/product/ (или дверь прикрепления в десктопе) загружает файлы или целые директории как фон для архитектора — обосновано двумя правилами, которые промпт заявляет прямо: утверждённые требования владеют объёмом, а где справочник и код расходятся, код — истина. Когда корпус перерастает контекст кресла, каждый документ переваривается один раз (кэшируется по хешу содержимого), полный текст остаётся доступным через инструмент ref_read, а карточка предложения перечисляет любой документ, который ни одно кресло никогда не открыло.

Принятие существующей кодовой базы работает так же: интэйк читает код и пишет требования as-built, спека помечает свои секции as-built, а план намеренно остаётся пустым — новая работа затем входит через отчёты о багах и поправки к плану, именно так разрабатывается сам ducklab.

Ваш проект объявляет свою собственную истину в .ducklab/project.toml: гейт ([verify] — с link_deps и setup для того, что нужно чистому чекауту), как запускается приложение ([run] с предварительной проверкой) и как пересобираются собственные бинарники проекта ([install]), чтобы весь цикл работал, не покидая ducklab.

Добавление модели

ducklab provider set openrouter --url https://openrouter.ai/api/v1 \
                                --key-env OPENROUTER_API_KEY
ducklab duckling set pato-sonnet --provider openrouter \
                                 --model anthropic/claude-sonnet-4.5 \
                                 --roles reviewer,judge --context 200000 \
                                 --cost-in 3.0 --cost-out 15.0
ducklab duckling test pato-sonnet --prompt "say OK"

--key-env — это имя переменной окружения, никогда не ключ. Никакой ключ не записывается в конфиг, не отправляется через API и не остаётся в истории оболочки.

Представление Roster в десктопе — это то, где назначаются кресла: перетащите из стаи на кресло режима, глобально или для каждого проекта, с доказательствами каждого утёнка на карточке и предложениями движка рядом с креслами. Индексы кодинга / интеллекта / агентности берутся из эндпоинта бенчмарков OpenRouter, когда утёнок живёт там; ваши собственные запуски дают остальное.

Пять режимов

ducklab run T-001 --mode <режим>

Чего он не будет делать

Это несущие, а не предпочтения.

• Модель никогда не решает вердикт. Гейт — это код выхода команды.

• Зелёный кандидат применяется байт-в-байт. Ничто не перегенерируется после того, как он прошёл.

• Ревьюер никогда не узнаёт, кто написал код.

• Ничто не попадает в код, что не воспроизвелось из чистого чекаута.

• Отклонение отменяет то, что записал запуск, и ничью чужую работу.

• Ничто не безгранично.

• Секреты никогда не касаются состояния проекта.

• Движок только loopback. Удалённого режима нет.

Навыки

Навык — это директория с SKILL.md — в .ducklab/skills/ для одного проекта или в общесистемной директории навыков, чтобы обслуживать каждый проект (проектный затеняет глобальный при совпадении имён). Форма только для документации не имеет скрипта и является по умолчанию: рецепт, который модель читает и следует. Архитектор читает руководства по обследованию перед принятием (skill_list есть в его промпте), консультант читает их в чате, и только исполнитель может skill_run исполняемый навык.

Навыками управляют с десктопа (gear → Skills): список с бейджами области действия и проблемами валидации, чтение, редактирование всего SKILL.md, запуск с аргументами, удаление. Навык, который утёнок пишет во время запуска, показывается там серым pending acceptance, пока его запуск не принят — предложение навыка проходит через тот же гейт, что и предложение кода.

ducklab skill new house-style
ducklab skill run changelog-entry --arg summary="..."

Консультант

Каждый проект размещает консультанта (обычное место на доске состава): модель за дверями «чат об этом» и свободный чат в направляющей. Она читает код, запуски, доски и навыки — никогда не пишет — и принимает изображения: вставьте скриншот сломанного вида и спросите. Зрение проверяется, а не предполагается: место с заявленным зрением один раз проверяется реальным запросом изображения, а текстовое место отказывается от вставки словами, а не галлюцинирует ответ.

Управление ducklab из другой модели

ducklab mcp serve предоставляет весь цикл через stdio как MCP-сервер: внешняя модель читает каждый результат, принимает решения по шлюзам (с обязательной записанной причиной — решения попадают как approved_by: mcp:<client>, никогда как «human»), отвечает на вопросы, заводит баги, вносит правки в планы и запускает работу. Списки next движка — закон: оператор не может совершить действие, которое не мог бы совершить человек.

Участие в разработке

См. CONTRIBUTING.md — как собрать проект, как тесты защищают архитектуру, как работа проходит через собственный цикл ducklab и с чего начать. Краткая версия:

make            # vet, test, build the frontend
go test ./...   # 38 packages
cd frontend && npx vitest run

Лицензия: Apache-2.0. Вклад принимается на тех же условиях (§5 лицензии — без CLA). Название Ducklab и утка принадлежат мейнтейнеру (§6).

Спецификация

Код реализует письменную спецификацию, находящуюся в этом репозитории: docs/spec/ (00-VISION по 08-DESKTOP-UI) — это нормативный слой — видение, инварианты, контракты протокола, критерии приёмки. То, чем система является СЕГОДНЯ, находится в .ducklab/docs/ — требования «как построено», спецификация и план, которые поддерживает сам цикл, каждая версия подписана на человеческом шлюзе. Там, где они намеренно различаются, разница зафиксирована в docs/decisions/; разница между ними — это дорожная карта, и этап согласования вычисляет её.