@xnlc/agent — инструменты и runtime AI-агента

Пакет содержит логику Xneon Agent: инструменты управления лаунчером, состояние чатов, цикл вызовов модели, вопросы пользователю, подтверждения действий, подготовку контекста и адаптеры AI-протоколов. Пакет не импортирует React, Electron или SQLite. Доступ к приложению передаётся через AgentHost. При этом runtime ориентирован на среду лаунчера: ему нужен реализованный ElectronAPI, а не только HTTP-ключ провайдера. Это не универсальный автономный SDK для любой программы.

Документ описывает текущие исходники лаунчера 1.0.7. Отдельная пользовательская инструкция: Xneon AI.

Версия пакета в текущих исходниках: 1.0.0. Лицензия пакета: MIT.

Установка и форматы

В монорепозитории зависимость подключена как workspace:*:

{
  "dependencies": {
    "@xnlc/agent": "workspace:*"
  }
}

Для внешнего проекта настройте реестр области @xnlc, затем установите пакет:

.npmrc

@xnlc:registry=https://git.xneon.org/api/packages/MAINER4IK/npm/

pnpm add @xnlc/agent

Авторизация в реестре зависит от настроек вашего доступа; токен в документацию или исходники не вставляется.

Формат	Каталог	Использование
ESM	`lib/`	`import` в renderer и ESM-приложении
CommonJS	`lib-cjs/`	`require` в main-процессе
TypeScript	`lib/*.d.ts`	Общие декларации типов

Прямая зависимость пакета — @xnlc/types. Список установленных сторонних библиотек приложения не является зависимостями самого агента.

Точки входа

Импорт	Содержимое
`@xnlc/agent`	Основные публичные экспорты
`@xnlc/agent/host`	`AgentHost`, `configureAgentHost`, доступ к адаптеру
`@xnlc/agent/runtime`	Чаты, отправка, остановка, подтверждения, подписка на состояние
`@xnlc/agent/tools`	`AGENT_TOOLS`, проверка аргументов и выбор групп
`@xnlc/agent/launcher-tools`	Подключение инструментов публичного API лаунчера
`@xnlc/agent/launcher-ipc-catalog`	Сгенерированный каталог методов bridge
`@xnlc/agent/providers`	Формирование запросов и разбор ответов провайдеров
`@xnlc/agent/protocol`	Обработка протокольных данных
`@xnlc/agent/model-config`	Проверка и чтение настроек моделей
`@xnlc/agent/project-cards`	Представление результатов поиска проектов
`@xnlc/agent/project-details`	Данные подробностей проекта
`@xnlc/agent/prompt`	Системные инструкции и подготовка промпта
`@xnlc/agent/extended-tools`	Регистрация дополнительных инструментов

Подключение AgentHost

Вызовите configureAgentHost до инициализации runtime или выполнения инструментов. Host хранится на уровне экземпляра модуля; API создания независимого runtime для каждого чата здесь нет. Host передаёт:

Поле	Обязанность приложения
`api()`	Вернуть действующий публичный `ElectronAPI`
`translate()`	Перевести ключ с параметрами
`language()`	Вернуть выбранный язык
`emit()`	Доставить событие обновления интерфейсу
`launch`	Загрузить настройки запуска, нормализовать Java, определить разрешение, сохранить последние параметры
`themes`	Передать пресеты и операции модели тем

Следующий пример принимает уже реализованный host; он не создаёт заглушки API:

import { configureAgentHost, type AgentHost } from "@xnlc/agent/host"
import {
  getAgentState,
  initializeAgent,
  refreshAgentConfig,
  subscribeAgentState,
} from "@xnlc/agent/runtime"

export async function connectAgent(host: AgentHost) {
  configureAgentHost(host)

  const unsubscribe = subscribeAgentState(() => {
    const state = getAgentState()
    // Подключите состояние к своему UI, не отправляя его целиком в логи.
    void state.running
  })

  try {
    await initializeAgent()
    await refreshAgentConfig()
    return unsubscribe
  } catch (error) {
    unsubscribe()
    throw error
  }
}

Готовый адаптер лаунчера находится в components/launcher/agent/host.ts; React-подписка — в components/launcher/agent/store.ts.

Чаты и выполнение запроса

import {
  newAgentChat,
  setAgentDraft,
  setAgentMode,
  sendAgentMessage,
} from "@xnlc/agent/runtime"

export async function askAboutBuilds() {
  await newAgentChat()
  setAgentMode("confirm")
  setAgentDraft("Покажи мои сборки и объясни различия между ними.")
  await sendAgentMessage()
}

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

Операция	Метод
Загрузить список чатов и восстановить последний активный	`initializeAgent()`
Создать чат	`newAgentChat(attachments?, draft?)`
Выбрать чат	`selectAgentChat(chatId)`
Архивировать или вернуть	`archiveAgentChat(chatId, archived)`
Удалить чат	`deleteAgentChat(chatId)`
Изменить черновик	`setAgentDraft(text)`
Выбрать режим	`setAgentMode("questions" \| "confirm" \| "auto")`
Ответить на подтверждение	`answerAgentApproval(allowed)`
Ответить на вопрос	`answerAgentQuestion(itemId, answer)`
Остановить текущий ход	`stopAgent()`
Открыть агента с логом	`openAgentWithLog(content, name?)`

Состояние содержит running, stopping, error, текущий чат, список чатов, ожидаемые вопрос и подтверждение. Хранение выполняется методами host API в main. Незавершённые вызовы после перезапуска помечаются прерванными и не запускаются повторно автоматически.

Режимы и категории действий

AgentChat.mode принимает три значения: questions, confirm, auto. В режиме questions runtime передаёт только инструменты категории read, исключая ask_user и update_plan, и повторно блокирует изменяющие действия перед выполнением.

Категория инструмента	`confirm`	`auto`
`read`	Без подтверждения	Без подтверждения
`write`	С подтверждением	Без обычного подтверждения записи
`delete`	С подтверждением	С подтверждением
`sensitive`	С подтверждением	С подтверждением

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

Инструменты и группы

Каждый AgentTool содержит имя, категорию risk, схему fields, протокольную декларацию spec, обработчик run и необязательную группу. parseToolInput проверяет JSON, допустимые имена полей, типы, длины, варианты enum, целочисленные числа и ограничения массивов. TypeScript-типы не заменяют эту проверку входящих аргументов модели. Не все инструменты отправляются в каждый запрос. Модель получает навигацию по каталогу и подключает тематические группы. getAgentTurnTools собирает схемы с бюджетом до 128 инструментов и 24 000 символов деклараций. Бюджет может вытеснить ранее подключённую группу; при необходимости её подключают снова. Основные области: сборки, версии, контент Modrinth/CurseForge/FTB, файлы сборок, серверы, миры, настройки, темы, скины, облако, статистика, новости и общий каталог IPC. Точное количество зависит от текущей версии исходников — фиксированное число в документации быстро устаревает.

import { AGENT_TOOLS } from "@xnlc/agent/tools"

export function listToolDescriptions() {
  return AGENT_TOOLS.map(({ name, risk, group }) => ({ name, risk, group }))
}

Прямой вызов tool.run обходит управление подтверждениями runtime. Для пользовательского агента запускайте полный цикл runtime либо реализуйте эквивалентную проверку действий в своём приложении.

Модели, провайдеры и контекст

Реализованы протоколы openai, anthropic, gemini, ollama. Адаптеры формируют запросы соответствующего формата; реальная поддержка вызовов инструментов и изображений зависит от выбранной модели и сервера. Настройки модели содержат id, contextWindow и supportsImages. Задавайте реальный размер окна модели: значение по умолчанию runtime не является гарантией возможностей провайдера. История включает сообщения, результаты инструментов, вложения и служебные данные. Runtime учитывает доступную статистику провайдера и приблизительные оценки, резервирует место для ответа и при необходимости сжимает историю. Индикатор контекста не равен точному счёту списанных денег или токенов. Изображения передаются в формате выбранного протокола. Если поддержка изображений у модели выключена, отправка новых изображений блокируется. Требования к файлам интерфейса приведены в пользовательском руководстве. Транспорт и ключ провайдера обслуживает приложение в electron/main/ai-agent.ts и electron/main/agent-workspace.ts. Отдельные функции providers подготавливают данные запроса и ответа; они не заменяют host и хранилище чатов.

Разработка

pnpm --filter @xnlc/agent run build
node scripts/gen-agent-ipc-catalog.mjs --check
pnpm run test:agent

Каталог IPC обновляется скриптом scripts/gen-agent-ipc-catalog.mjs, в том числе перед dev/build/package. Изменение API требует обновления контрактов, bridge и каталога. Подробности границ процессов: архитектура модулей.

Обзор

Пакеты @xnlc

@xnlc/agent — инструменты и runtime AI-агента

Установка и форматы

Точки входа

Подключение AgentHost

Чаты и выполнение запроса

Режимы и категории действий

Инструменты и группы

Модели, провайдеры и контекст

Разработка

Исходники