> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xneon.org/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Подключение AgentHost, работа с чатами, подтверждениями, контекстом и адаптерами провайдеров.

Пакет содержит логику Xneon Agent: инструменты управления лаунчером, состояние чатов, цикл вызовов модели, вопросы пользователю, подтверждения действий, подготовку контекста и адаптеры AI-протоколов.

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

> [!NOTE]
>
> Документ описывает текущие исходники лаунчера 1.0.7. Отдельная пользовательская инструкция: [Xneon AI](https://docs.xneon.org/guide/ai-agent.md).

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

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

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

```json theme={null}
{
  "dependencies": {
    "@xnlc/agent": "workspace:*"
  }
}
```

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

```ini .npmrc theme={null}
@xnlc:registry=https://git.xneon.org/api/packages/MAINER4IK/npm/
```

```bash theme={null}
pnpm add @xnlc/agent
```

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

| Формат | Каталог | Использование |
| - | - | - |
| 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:

```ts theme={null}
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`.

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

```ts theme={null}
import {
  newAgentChat,
  setAgentDraft,
  setAgentMode,
  sendAgentMessage,
} from "@xnlc/agent/runtime"

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

> [!WARNING]
>
> 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. Точное количество зависит от текущей версии исходников — фиксированное число в документации быстро устаревает.

```ts theme={null}
import { AGENT_TOOLS } from "@xnlc/agent/tools"

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

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

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

Реализованы протоколы `openai`, `anthropic`, `gemini`, `ollama`. Адаптеры формируют запросы соответствующего формата; реальная поддержка вызовов инструментов и изображений зависит от выбранной модели и сервера.

Настройки модели содержат `id`, `contextWindow` и `supportsImages`. Задавайте реальный размер окна модели: значение по умолчанию runtime не является гарантией возможностей провайдера.

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

Изображения передаются в формате выбранного протокола. Если поддержка изображений у модели выключена, отправка новых изображений блокируется. Требования к файлам интерфейса приведены в [пользовательском руководстве](https://docs.xneon.org/guide/ai-agent.md).

Транспорт и ключ провайдера обслуживает приложение в `electron/main/ai-agent.ts` и `electron/main/agent-workspace.ts`. Отдельные функции `providers` подготавливают данные запроса и ответа; они не заменяют host и хранилище чатов.

## Разработка

```bash theme={null}
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 и каталога. Подробности границ процессов: [архитектура модулей](https://docs.xneon.org/core/architecture.md).

## Исходники

* [Публичные экспорты](https://github.com/XneonTeam/Xneon-Launcher/blob/main/packages/xnlc-agent/src/index.ts).
* [Host](https://github.com/XneonTeam/Xneon-Launcher/blob/main/packages/xnlc-agent/src/host.ts), [runtime](https://github.com/XneonTeam/Xneon-Launcher/blob/main/packages/xnlc-agent/src/runtime.ts), [инструменты](https://github.com/XneonTeam/Xneon-Launcher/blob/main/packages/xnlc-agent/src/tools.ts).
* [Контракты агента](https://github.com/XneonTeam/Xneon-Launcher/blob/main/packages/xnlc-types/src/agent-types.ts).
* [Main-адаптер](https://github.com/XneonTeam/Xneon-Launcher/blob/main/electron/main/agent-workspace.ts).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.