TUT — Бери свою очередь

English | 简体中文

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

TUT — это многопользовательская система коллаборации агентов, работающая на вашем локальном компьютере. Её ядром является Context Hub — локальный MCP-сервер, выступающий в роли общей памяти для агентов (журнал задач с только добавлением записей). Состояние задачи выводится из последовательности записей с помощью чистой функции; Notifier опрашивает изменения состояния и управляет циклом проектирование → реализация → ревью → доработка в ручном или автоматическом режиме; человек принимает решение только на точках утверждения.

Проблема

Традиционный способ координации нескольких агентов — передача файлов (передача design.md / review.md). Он имеет три недостатка:

• Контекст передаётся через файлы: файлы передают только выводы — обоснование и отвергнутые альтернативы теряются. Следующий агент получает «что», но не «почему»

• Рабочий процесс управляется вручную: цикл ревью–доработка обычно проходит 2-3 раунда, каждый из которых запускается вручную, с повторной настройкой запросов и контекста каждый раз

• Инструменты изолированы друг от друга: сессии агентов не видят друг друга; нет единого состояния или точки входа для оркестрации

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

Related MCP server: kitty-hive

Основные механизмы

• Только добавление записей: агенты добавляют записи в журнал задач через 5 MCP-инструментов (create / publish / read / list / decide) — design, code_changes, review, revision, note, decision. Записи никогда не удаляются; любой, начинающий с нуля, может восстановить каждое решение и его обоснование только из журнала

• Производное состояние: состояние задачи (где мы находимся, чей ход) не сохраняется и не принуждается — это представление, вычисляемое из последовательности записей чистой функцией. Комбинации вне таблицы состояний (например, публикация ревью в задаче solo) всё равно попадают на диск, но устанавливают needs_attention, чтобы человек мог с ними разобраться

• Шлюз утверждения: после прохождения ревью производное состояние становится pending_approval, и человек должен опубликовать запись решения (approve / reject), прежде чем что-либо продолжится. close допустим в любом состоянии — человек сохраняет право завершить задачу в любой момент

• Варианты потока: выберите --flow full|direct|solo при создании задачи — full выполняет полный цикл; direct пропускает этап проектирования (в репозитории уже есть дизайн); solo пропускает ревью для небольших изменений — без ревью, но не без утверждения (сразу к шлюзу утверждения)

• Ручное / автоматическое продвижение: в ручном режиме (по умолчанию) человек уведомляется, когда чей-то ход, и запускает следующий шаг; в автоматическом режиме Notifier запускает следующего агента напрямую через лаунчер (с градуированным доверием через белый список ролей), и человек принимает только решения

Архитектура

┌─────────────────────────────── local machine ────────────────────────────────┐
│                                                                              │
│  coding agent ──MCP read/write──► Context Hub ──► storage (local JSON)       │
│       ▲                            (memory + state projection)               │
│       │ launch                          ▲                                    │
│  Agent Host ──state events──► Notifier ─┘                                    │
│  (signal source + launcher, pluggable)   │ reads derived state (GET /state)  │
│                                          │                                   │
└──────────────────────────────────────────┼───────────────────────────────────┘
                                           ▼ notifications
                                        Channel ──► human
     manual: the human starts the next one | auto: the Notifier starts it via the launcher

Состояние задачи выводится из последовательности записей:

designing → implementing → reviewing ─┬─ pass       → pending_approval → human decide(approve) → approved → closed
                                       ├─ fail_code  → revising → revision → back to reviewing
                                       └─ fail_design → sent back to designing

Быстрый старт

Предварительные требования: Node.js ≥ 20, Herdr (Agent Host, предоставляющий панели терминала, в которых живут агенты; установка через brew install herdr, домашняя страница проекта https://github.com/herdrdev/herdr), и хотя бы один CLI-инструмент агента кодирования. Платформы: только macOS / Linux (лаунчер — это POSIX-шелл; поддержка Windows в Herdr ещё в стадии бета).

git clone https://github.com/ianf-ai/take-ur-turn.git
cd take-ur-turn
npm install
npm run build

Результат сборки: dist/cli.js. Используйте npm link, чтобы поместить команду tut в PATH; если вы не хотите создавать ссылку, node dist/cli.js <subcommand> всегда работает (далее упоминается как tut).

Запустите workspace (главный выключатель, идемпотентен — две системные панели: панель хаба + панель уведомлений):

tut up

Запустите задачу (отправляет одно предложение с требованием в панель Architect; затем опрашивайте tut list, пока задача не появится):

tut new "add a --url flag to the CLI's mode subcommand"

Оттуда агенты продвигают задачу, читая и записывая Hub через MCP-инструменты из своих панелей; tut status показывает обзор, Notifier уведомляет вас, когда требуется утверждение, и вы принимаете решение с помощью tut decide <task_id> --decision approve --by <your-name>.

Побочные каналы Notifier (мгновенные оповещения о блокировках, проверки завершения) полагаются на то, что Herdr перенаправляет изменения состояния агента каждой панели в scripts/on-agent-event.sh — одноразовая настройка окружения (плагин Herdr); см. инструкции по подключению в разделе 7.2 design/system-design.md.

Подключение CLI-агентов (одноразово)

Hub предоставляет свои MCP-инструменты через Streamable HTTP по адресу http://127.0.0.1:3001/mcp (доступен, как только tut serve запущен; без сохранения сессии, без потока). Настройте один раз для каждого CLI-агента, который будет участвовать:

Codex CLI (~/.codex/config.toml):

[mcp_servers.tut]
url = "http://127.0.0.1:3001/mcp"

Другие MCP-клиенты, поддерживающие Streamable HTTP: укажите им тот же URL.

После настройки агент видит 5 инструментов: context.create / context.publish / context.read / context.list / context.decide.

CLI без поддержки MCP через HTTP: используйте эквивалентный канал CLI — подкоманды tut create / publish / read / list / decide отображаются один к одному на MCP-инструменты, так что агент может просто вызывать их из оболочки (созданные для таких CLI «шпаргалки по инструментам» для каждой роли — отображение MCP | CLI — именно для этого; два канала можно смешивать; в одной задаче каждая роль может использовать свой канал — это полностью совместимо).

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

Обзор команд

Вызов tut без аргументов выводит полное использование. Цитата дословно:

tut serve [--port <n>] [--root <dir>]
tut notify [--url <u>] [--interval <s>] [--event-port <p>] [--stall-timeout <m>]
tut mode <manual|auto> [--url <u>]
tut start-next [<task_id>] [--url <u>] [--force]
tut create --title <t> --description <d> --creator <c> --role <r> [--flow <full|direct|solo>] [--cast <role=agent,...>] [--url <u>]
tut publish <task_id> --role <r> --content-type <t> --summary <s>
             (--body <text> | --payload-file <md>)
             [--verdict <pass|fail_code|fail_design>] [--commits <a,b>]
             [--ref-version <n>] [--expected-version <n>] [--agent <a>] [--model <m>] [--url <u>]
tut read <task_id> [--since-version <n>] [--json] [--url <u>]
tut list [--status <s>] [--json] [--url <u>]
tut decide <task_id> --decision <approve|reject|close> --by <b> [--reason <text>] [--url <u>]
tut new "<one-sentence requirement>" [--pane <label>]
tut assign <role> <agent>
tut up [--url <u>] [--dry-run]
tut ack <task_id> [--note <text>] [--url <u>]
tut status [--json] [--url <u>]

Эквивалентный канал на стороне агента — 5 MCP-инструментов (context.create / context.publish / context.read / context.list / context.decide); подкоманды CLI отображаются на них один к одному.

Типичный рабочий процесс

Architect publishes design
    ↓ derived: designing → implementing
Executor reads context → codes the implementation (runs tests) → publishes code_changes
    ↓ derived: implementing → reviewing
Reviewer reads context → reviews (each finding carries a closing condition) → publishes review
    ├─ pass        → pending_approval → human decide(approve) → approved
    └─ fail_code   → revising → Executor publishes revision → back to reviewing
(The Notifier polls state changes: in manual mode it notifies the human to start the next step; in auto mode it can advance automatically)

Диаграмма выше — это поток по умолчанию, full. Варианты выбираются при создании задачи (фиксируются при создании, неизменяемы после сохранения):

• direct: в репозитории уже есть дизайн, поэтому этап проектирования пропускается — задача начинается с реализации; ревью и утверждение человеком выполняются как обычно

• solo: небольшие изменения пропускают ревью — code_changes переводит в pending_approval напрямую для утверждения/отклонения человеком. Без ревью, но не без утверждения: approve всё ещё является шлюзом человека

Конфигурация

Три поверхности конфигурации, различные по природе и расположению:

① Конфигурация времени выполнения проекта — .context-hub/config.json (в gitignore, один на проект)

Управляет поведением Hub и Notifier. Изменения вступают в силу в следующем цикле опроса — перезапуск не требуется:

② Конфигурация workspace — scripts/workspace.json (поставляется с репозиторием)

Стандартная расстановка: роль → { label, agent } (метка панели + CLI-агент, занимающий это место). Применяется для задач, созданных без явного назначения; редактируйте с помощью tut assign <role> <agent>. routes.json остаётся как резервный формат старого образца.

③ Параметры вызова — флаги CLI и переменные окружения

Также есть одноразовая настройка окружения: плагин Herdr для привязки событий (см. примечание о подключении в конце раздела Быстрый старт).

Разработка

Зависимости перечислены в package.json: зависимости времени выполнения — @modelcontextprotocol/sdk + zod (zod объявлен явно, чтобы он разделял один экземпляр с SDK); других зависимостей времени выполнения нет.

npm install        # install dependencies
npm test           # run tests (vitest)
npm run typecheck  # type-check
npm run build      # compile to dist/

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

Документация

• design/system-design.md — Системный дизайн (в настоящее время авторитетный): архитектура, правила вывода состояний, схемы MCP-инструментов, контракты модулей, технологические решения

• design/context-design.md — Дизайн контекста: что входит (область / типы записей / шаблоны полезной нагрузки и тела) и как это управляется

Документы по дизайну и навыки в настоящее время на китайском языке; код, вывод CLI и соглашения о коммитах — на английском.

Устранение неполадок и известные ограничения

Устранение неполадок:

• Агент сообщает, что не видит инструменты context.*: убедитесь, что tut serve запущен (curl http://127.0.0.1:3001/state отвечает — значит, жив); проверьте, что конфигурация MCP в CLI указывает на конечную точку /mcp; некоторые сессии CLI могут быть изолированы от обратной петли localhost — в этом случае пусть агент использует канал CLI (tut read / tut publish) вместо этого; поведение полностью эквивалентно

• Порт 3001 уже занят (EADDRINUSE): переключите порты с помощью tut serve --port <n> и укажите остальным командам новый адрес через --url (включая зонд выделения в tut up)

• Пользовательская конфигурация потеряна после npm i -g: tut assign записывает внутренний scripts/workspace.json (внутри node_modules), который сбрасывается при обновлении — если вам нужна настраиваемая конфигурация/расположение, клонируйте репозиторий и устанавливайте из него

Известные ограничения (компромиссы в дизайне, не ошибки):

• Панель агента — это одна сессия: когда несколько задач одновременно ожидают одного и того же агента, раундовые запросы поступают один за другим в одной сессии (последовательное выполнение, общий контекст)

• Notifier наблюдает состояние с гранулярностью опроса: промежуточные состояния внутри окна опроса остаются незамеченными (можно видеть, как номера версий «перескакивают»); воспроизведение записей является источником истины, и любое промежуточное состояние может быть восстановлено из лога

• В автоматическом режиме нет криптографического способа проверить, что запись решения «действительно пришла от человека» — текущее запасное решение — аудит уведомлений плюс трассировка через поле by; более структурированное решение оставлено для сценария развёртывания на нескольких машинах

Благодарности

Хостинг агентов обеспечивается Herdr — отдельно устанавливаемый компонент времени выполнения; этот пакет не распространяет его код.

Лицензия

Apache-2.0