Incur: фреймворк для создания CLI-утилит для людей и ИИ-агентов

Черное окно терминала десятилетиями создавалось под человеческий глаз: разноцветный текст, анимированные спиннеры загрузки, псевдографические рамки и подробные подсказки. Но когда за терминал садится автономный кодинг-агент на базе большой языковой модели, вся эта визуальная эстетика превращается в цифровую пыль. Языковая модель вынуждена считывать сотни управляющих символов ANSI и тратить драгоценную память контекстного окна на разбор неструктурированных ответов.

Команда wevm, создавшая известные в мире веб-разработки библиотеки viem и wagmi, предложила решение этой дилеммы во фреймворке Incur. Это библиотека на TypeScript, позволяющая создавать консольные утилиты, которые одинаково органично воспринимаются живым инженером и программным агентом.

Двойная жизнь терминальных команд

В повседневной разработке команды часто сталкиваются с неприятным компромиссом. Классические библиотеки вроде Commander.js или Yargs помогают собрать симпатичный CLI с цветными подсказками, но для ИИ-ассистента такой интерфейс оказывается крайне неудобным: модель регулярно путает позиционные аргументы и галлюцинирует при разборе вывода. Альтернатива — поднять отдельный сервер по протоколу Model Context Protocol (MCP) — удобна для робота, но лишает человека возможности быстро набрать команду в консоли без посредников.

Incur объединяет оба мира в одной точке входа. Разработчик описывает параметры и флаги утилиты один раз с помощью декларативных схем валидации Zod. Фреймворк берет на себя рутину: генерирует автодополнение типов для TypeScript, проверяет корректность аргументов и автоматически формирует манифесты возможностей для подключенных нейросетей.

Экономия контекста через формат TOON

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

В Incur встроен компактный формат сериализации TOON (Token-Oriented Object Notation). Он избавляет поток данных от синтаксического шума, сохраняя иерархическую типизацию. По замерам авторов, переход на TOON сокращает объем служебных данных до трех раз по сравнению со стандартным JSON. Для агента, выполняющего десятки обращений к локальным devtools в рамках одной рабочей сессии, это означает меньшие задержки и существенную экономию на счетах за API языковых моделей.

Сквозной сценарий: от Zod-схемы до вызова агентом

Создание утилиты в Incur строится вокруг единого контракта. Сначала объявляется команда с типизированными входными аргументами и опциями запуска:

import { Cli, z } from 'incur'

// Определение консольной команды с проверкой аргументов через Zod
const cli = Cli.create('deploy-tool', {
  description: 'Утилита развертывания сервисов для инженеров и ИИ-агентов',
  version: '1.0.0',
})
  .command('service', {
    description: 'Развертывание сервиса в целевой среде',
    args: z.object({
      name: z.string().describe('Уникальное имя сервиса в реестре'),
    }),
    options: z.object({
      environment: z.enum(['staging', 'production']).default('staging').describe('Целевой контур'),
      replicas: z.coerce.number().min(1).max(10).default(2).describe('Количество реплик'),
      dryRun: z.boolean().default(false).describe('Имитация запуска без применения изменений'),
    }),
    alias: { environment: 'e', dryRun: 'd' },
    run(c) {
      const { name } = c.args
      const { environment, replicas, dryRun } = c.options

      if (dryRun) {
        return {
          status: 'simulated',
          service: name,
          environment,
          replicas,
          ready: true,
        }
      }

      return {
        status: 'deployed',
        service: name,
        environment,
        replicas,
        deploymentId: `dep-${Date.now()}`,
      }
    },
  })

// Инициализация интерфейса обработки входящих вызовов
cli.serve()

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

# Вызов инженером с получением компактного структурированного ответа
$ deploy-tool service api-gateway --environment staging
service: api-gateway
environment: staging
replicas: 2
status: deployed
deploymentId: dep-1772605200000

# Регистрация утилиты в каталоге локальных навыков агента одной командой
$ deploy-tool skills add

# Запуск в режиме прямого stdio-транспорта для ассистентов с поддержкой MCP
$ deploy-tool --mcp

# Мгновенная выгрузка схемы команд в формате JSON Schema для контекста LLM
$ deploy-tool --llms

Архитектурные нюансы и рабочий вердикт

Фреймворк поддерживает запуск в среде Node.js, Bun и Deno, а также компиляцию в автономные бинарные файлы под Linux, macOS и Windows. Это позволяет распространять внутренние утилиты компании без требования предварительно настраивать рантайм на машине разработчика или в CI-контейнере.

Однако разработчикам стоит учитывать специфику компактных форматов: хотя ведущие нейросети (Claude 3.7, GPT-4o) уверенно интерпретируют разметку TOON, более простые локальные модели могут требовать классического JSON через флаг --format json. Кроме того, проектирование схем требует сдержанности: чрезмерно глубокая вложенность объектов в Zod раздувает генерируемую спецификацию инструментов.

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