Skip to content

README_RU.md

Latest commit

 

History

History
606 lines (461 loc) · 43.2 KB

README_RU.md

File metadata and controls

606 lines (461 loc) · 43.2 KB

CoreAI Banner

CoreAI Icon CoreAI — AI-агенты в Unity

Читать на других языках: English, Русский.

🎬 Представьте

Игрок подходит к кузнецу-NPC и пишет: «Есть огненные мечи?». Кузнец вызывает ваш код инвентаря, ничего не находит, и отвечает по роли: «Огненных клинков нет, но могу выковать, если принесёшь Кристалл Огня.» Игрок крафтит — Programmer-агент пишет Lua, CoreMechanic считает статы, и уникальный Меч Пламени падает в инвентарь. Всё в рантайме, стримингом токен за токеном в чат-пузырь, на локальной модели 4 ГБ. Без облачных ключей. Без скриптовых деревьев диалогов. Это CoreAI.

Одно хранилище, два пакета: портативное ядро C# и Unity-слой с DI, панелью чата и тестами. Хотите демо за пять минут — или многошаговый пайплайн с инструментами и Lua — используются одни и те же кирпичики.

  • 🧠 Агенты, которые вызывают ваш код — не просто генерация текста, а реальный function calling с ретраем, авто-ремонтом и памятью.
  • 🛡️ Самовосстанавливающаяся устойчивость — TryRepairToolName автоматически чинит регистр имён инструментов; HTTP retry читает Retry-After заголовки с экспоненциальным backoff.
  • 🌊 Стриминг, переживший разорванные теги — stateful SSE-аккумуляция собирает фрагментированные <think> блоки и tool calls.
  • 💬 Чат-панель в один клик — CoreAI → Setup → Create Chat Demo Scene → Play.
  • ⚡ Одна строка из любого скрипта — await CoreAi.AskAsync("…") — без DI-бойлерплейта.
  • 🧭 LLM-режимы под разные production-сценарии — LocalModel, ClientOwnedApi, ClientLimited, ServerManagedApi или смешанная маршрутизация по ролям.
  • 🗜️ Длинный чат без «переполнения» — бюджет токенов на историю, блок ## Conversation Summary, опциональная LLM-свёртка (в духе Kilocode) и переключатели по ролям: AgentBuilder.WithLlmContextCompaction(...) и глобальный флаг на CoreAISettings.
  • 🎯 Self-Service Skills — группируй инструменты по доменам (крафт, бой, торговля). Модель видит только 2 мета-инструмента (read_skill + call_skill_tool), а не сотни тулов. Экономия токенов ~91%.
  • 🛡️ Production-устойчивость — MaxToolResultChars (обрезка больших результатов), DefaultToolTimeoutMs (таймаут на тул), MaxResponseChars (лимит ответа), MaxToolCallRoundtrips (защита от зацикливания), MaxToolCallHistoryMessages (обрезка истории). RateLimiterMetrics диагностика. Всё в Inspector.
  • 🔄 Dual-backend с автопереключением — настрой secondary HTTP backend в Inspector. При ошибке primary запрос автоматически уходит на secondary (FallbackLlmClientDecorator). Идеально для локальная модель + облачный fallback.

🚀 Проверено на малых моделях: полный набор PlayMode-тестов проходит на локальной Qwen3.5-4B GGUF. Облачные API не обязательны.

Версия: см. Assets/CoreAiUnity/package.json и Assets/CoreAI/package.json (одинаковый semver). Стриминг WebGL: WebGlNativeStreaming (fetch + jslib) — STREAMING_ARCHITECTURE.md. Сборка WebGL: WEBGL_BUILD_TROUBLESHOOTING.md.

EditMode tests Unity License

Содержание

Раздел
Три входа UI · CoreAi · агенты
Что умеет CoreAI Агенты, скиллы, чат, инструменты, память, свёртка
Архитектура Два пакета, схема
Установка NuGet, manifest, Git URL, сцена
Быстрый старт Первый агент
Документация Карта гайдов
Тесты EditMode и PlayMode

Полные заметки по версиям: Assets/CoreAiUnity/CHANGELOG.md · CoreAI CHANGELOG.

🧭 Три входа: UI · CoreAi · агенты

Делаешь… С чего начать В одно предложение
Внутриигровой чат для игрока CoreAI → Setup → Create Chat Demo Scene + CoreAiChatPanel Включил Play — пишешь в чат
Любой скрипт, без DI в первый день using CoreAI; → await CoreAi.AskAsync("…") или StreamAsync COREAI_SINGLETON_API
Полноценного агента, инструменты, оркестратор AgentBuilder + IAiOrchestrationService AGENT_BUILDER

Все три пути при одной настройке сцены разделяют CoreAILifetimeScope и бэкенд LLM.

✨ Что умеет CoreAI

🏗️ Создавай своих AI-агентов за 3 строки

var merchant = new AgentBuilder("Blacksmith")
    .WithSystemPrompt("You are a blacksmith. Sell weapons and remember purchases.")
    .WithTool(new InventoryLlmTool(myInventory))  // Знает свой ассортимент
    .WithMemory()                                  // Помнит покупателей
    .Build();                                      // → AgentConfig (чертеж в памяти)

// Подключает чертёж к глобальной политике (её создаёт CoreAILifetimeScope при старте).
// Оркестратор ищет инструменты и системный промпт по RoleId ("Blacksmith") в этой политике.
merchant.ApplyToPolicy(CoreAIAgent.Policy);

// Ask* идут через CoreAIAgent.Orchestrator — нужен Play и сцена с CoreAILifetimeScope.
merchant.Ask("Покажи мечи");
merchant.Ask("Покажи мечи", (response) => Debug.Log(response));
  • Build() — даёт AgentConfig (id роли, тулы, промпты). Сам по себе рантайм о нём не знает.
  • ApplyToPolicy(CoreAIAgent.Policy) — регистрирует роль в живой AgentMemoryPolicy, чтобы RunTask/маршрутизация тулов видела твой InventoryLlmTool и слитый промпт для "Blacksmith". Без этого роль — просто строка без стека.
  • Ask / AskAsync — обёртка над CoreAIAgent.Orchestrator (AiTaskRequest с RoleId из конфига). То же, что взять IAiOrchestrationService из DI — см. COREAI_SINGLETON_API.

3 режима агентов: 🛒 ToolsAndChat · 🤖 ToolsOnly · 💬 ChatOnly

🎯 Self-Service Skills — агент подгружает инструменты по требованию

Когда у агента десятки инструментов из разных доменов (крафт, бой, торговля, квесты), слать их все каждый запрос — тратить токены. Skills решают это:

// Группируй инструменты в скиллы
var crafting = new SkillSet("Crafting",
    "Ковка оружия и брони из материалов",
    "1. Вызови get_recipes.\n2. Вызови craft_item.",
    new DelegateLlmTool("get_recipes", "Список рецептов", (string type) => ...),
    new DelegateLlmTool("craft_item", "Создать предмет", (string id) => ...));

// Модель видит только 2 мета-инструмента, не все тулы скиллов
var gm = new AgentBuilder("GameMaster")
    .WithSkill(crafting)
    .WithSkill(combat)
    .WithSkill(trading)
    .Build();

Как работает:

  1. Модель видит лёгкий каталог (имя + описание скилла) в system prompt
  2. Вызывает read_skill("Crafting") → получает инструкции + схемы инструментов
  3. Вызывает call_skill_tool("get_recipes", "{}") → прокси маршрутизирует к реальному тулу
  4. Токен-оверхед: константный (2 мета-тула) независимо от общего числа скиллов/тулов

💡 50 инструментов в 10 скиллах? Без скиллов: ~4,000 токенов. Со скиллами: ~360 токенов. Экономия 91%.

Совмещай прямые тулы и скиллы: WithTool(memory) (всегда виден) + WithSkill(crafting) (по требованию).

Документация: AGENT_BUILDER.md §Skills

💬 Готовый чат без своего UI

Сцена с NPC-чатом за минуты — без ручной вёрстки:

CoreAI → Setup → Create Chat Demo Scene

Получаешь CoreAiChatDemo.unity с CoreAiChatPanel (UI Toolkit, UXML/USS, тёмная тема; окно по умолчанию ~650×910, скроллбар вплотную справа, опциональная строка «долго ждём» под индикатором набора), CoreAiChatConfig_Demo и настроенным CoreAILifetimeScope — Play и печатаешь.

// Тот же стек, что у панели — выбери удобный API:
await foreach (var chunk in CoreAi.StreamAsync("Привет", "SmartChat"))
    Debug.Log(chunk);

// Или явно через сервис (например в тестах):
var service = CoreAiChatService.TryCreateFromScene();
await foreach (var chunk in service.SendMessageStreamingAsync("Привет", "SmartChat"))
    if (!string.IsNullOrEmpty(chunk.Text)) Debug.Log(chunk.Text);

Цепочка стриминга: SSE (HTTP) или callback LLMUnity → stateful ThinkBlockStreamFilter (срезает <think>, даже если тег разорван) → индикатор печати → пузырь. Отмена снимает активный HTTP-запрос / перечислитель на MEAI-пути (HttpClient).

Доки: README_CHAT.md · STREAMING_ARCHITECTURE.md

🎯 Одна строка из скрипта: COREAI_SINGLETON_API.md
📖 Быстрый путь: LLM и сцена: QUICK_START.md
🏗️ Агенты + рецепты: AGENT_BUILDER.md

🔧 Инструменты (Tools) — AI вызывает код

AI может вызывать инструменты для получения данных и выполнения действий:

Инструмент Что делает Кто использует
🌍 WorldCommandTool Спавнит, двигает, меняет объекты в мире Creator AI
⚡ Action/Event Tool Вызывает любой C# метод или Event напрямую Все агенты
🧠 MemoryTool Сохраняет/читает память между сессиями Все агенты
📜 LuaTool Выполняет Lua скрипты Programmer AI
🎒 InventoryTool Получает инвентарь NPC Merchant AI
⚙️ GameConfigTool Читает/меняет конфиги игры Creator AI
🎭 SceneLlmTool Читает и меняет иерархию/transform в PlayMode Все агенты
📸 CameraLlmTool Делает скриншоты (Base64 JPEG) для Vision Все агенты
🧩 (Твой Инструмент) Добавь сюда (либо используй ⚡ Action/Event Tool) Ваш Агент

Создай свой инструмент:

public class WeatherLlmTool : ILlmTool
{
    public string Name => "get_weather";
    public string Description => "Get current weather in game world.";
    public string ParametersSchema => "{}";
    
    public IEnumerable<AIFunction> CreateAIFunctions()
    {
        yield return AIFunctionFactory.Create(
            async (CancellationToken ct) => await _provider.GetWeatherAsync(ct),
            "get_weather", "Get current weather.");
    }
}

💡 Дизайн инструментов для экономии токенов: используйте короткие ключи параметров (q вместо question_text), краткие описания, индексы вместо строк и умные дефолты. Подробнее: TOOL_CALL_SPEC.md

🎮 Динамические механики — AI меняет игру на лету

Игрок крафтит оружие
  ↓
CoreMechanicAI: "Железо + Кристалл Огня → Меч Пламени, урон 45"
  ↓
Programmer AI: вызывает execute_lua tool
  ↓
Lua: create_item("Flame Sword", "weapon", 75)
     add_special_effect("fire_damage: 15")
     report("crafted Flame Sword")
  ↓
Игрок получает уникальный предмет!

AI может:

  • 🔄 Менять правила игры (волны, модификаторы, сложности)
  • 🎨 Создавать процедурный контент (предметы, квесты, локации)
  • 📊 Анализировать поведение игрока и адаптировать игру
  • 🐛 Автоматически чинить Lua ошибки (до 3 попыток)

🧠 Память агентов — AI помнит всё

Два типа памяти:

Memory ChatHistory
Хранение JSON файл на диске В LLMAgent (RAM)
Срок Между сессиями Текущая сессия
Для чего Факты, покупки, квесты Контекст разговора 
var agent = new AgentBuilder("Merchant")
    .WithMemory()         // Помнит что купил игрок (между сессиями)
    .WithChatHistory()    // Помнит текущий разговор
    .Build();

🗜️ Длинные диалоги — бюджет, сводки и «умная» свёртка

Если включён WithChatHistory() и сообщений становится много, CoreAI сохраняет хвост свежих реплик, а более старые сворачивает в блок ## Conversation Summary в system (по умолчанию детерминированно). В актуальных релизах добавлено:

Возможность Смысл
Бюджет контекста HistoryTokenBudget из IContextBudgetPolicy — честнее делит окно между system/user/tools и историей.
Сводки на диске InMemoryConversationSummaryStore (процесс) или FileConversationSummaryStore (persistentDataPath в Unity) — сводки живут между ходами.
LLM-свёртка (опционально) Доп. вызов CompleteAsync на роли __CoreAI_ContextCompaction переписывает rolling-summary; включается в CoreAISettings, затем можно отключить per-role.
По умолчанию по роли У агентов из AgentBuilder умное сжатие включено; у встроенного Programmer — выкл. (обычно хватает усечённой истории для Lua/tool). WithLlmContextCompaction(false) — явный офф для кастомной роли. 
new AgentBuilder("LoreKeeper")
    .WithChatHistory(8192, persistBetweenSessions: true)
    .WithLlmContextCompaction(true) // по умолчанию так; можно опустить
    .Build()
    .ApplyToPolicy(policy);

new AgentBuilder("ToolsFirst")
    .WithChatHistory(4096)
    .WithLlmContextCompaction(false) // только детерминированный rollup
    .Build();

Подробнее: Core CHANGELOG (v1.5.2–1.5.3) · MemorySystem · ARCHITECTURE · COREAI_SETTINGS.

🔄 Tool Call Retry + Самовосстановление — AI учится на ошибках

Маленькие модели (Qwen3.5-2B) иногда забывают формат или регистр имён. CoreAI автоматически:

  • 🔧 Чинит регистр имён — TryRepairToolName молча конвертирует MEMORY → memory, Spawn_Quiz → spawn_quiz до того, как выполнение провалится.
  • ♻️ Повтор при ошибке — до 3 попыток с обратной связью ошибки в историю чата, чтобы модель сама исправилась.
  • 🌐 Повтор HTTP-ошибок — 429 (Rate Limited) и 5xx триггерят автоматический retry с поддержкой заголовка Retry-After или экспоненциальным backoff (2s → 4s, настраивается в Inspector).
  • ✅ Немедленная проверка Lua-блоков.
Модель говорит: {"name":"MEMORY", ...}
     ↓ TryRepairToolName
Исполняется: {"name":"memory", ...}  ← молча исправлено, ошибка не показана

🚀 Поддерживаемые LLM бэкенды

Бэкенд Описание Когда использовать
LLMUnity Локальная GGUF модель Без интернета, приватность
OpenAI HTTP LM Studio, Ollama, OpenAI-compatible Мощные модели, быстрый старт
Stub Заглушка для тестов CI/CD, разработка без LLM

Auto-режим: CoreAI сам выберет доступный бэкенд.

📏 Рекомендуемые модели

Модель Размер Tool Calling Когда использовать
Qwen3.5-4B 4B ✅ Отлично Рекомендуемая для локального запуска
Qwen3.5-35B (MoE) 35B/3A ✅ Превосходно Идеально через API — быстро и точно
Gemma 4 26B (через LM Studio) 26B ✅ Превосходно Отличный выбор через HTTP API
LM Studio API Любая ✅ Отлично Внешние модели через HTTP — лучший выбор
Qwen3.5-2B 2B ⚠️ Работает Работает, но иногда ошибается
Qwen3.5-0.8B 0.8B ⚠️ Базовый Большинство тестов проходит, сложности с многошаговыми

💡 Рекомендация: Qwen3.5-4B локально или Qwen3.5-35B (MoE) через API
MoE-модели (Mixture of Experts) используют только часть параметров при инференсе — быстрые как 4B, точные как 35B.

🧪 Результаты PlayMode тестов по размерам моделей

Все PlayMode тесты CoreAI проверены на реальных LLM бэкендах:

Категория тестов 0.8B 2B 4B+
Memory Tool (запись/добавление/очистка) ✅ Пройден ✅ Пройден ✅ Пройден
Custom Agents (вызов инструментов) ✅ Пройден ✅ Пройден ✅ Пройден
World Commands (list/play/spawn) ✅ Пройден ✅ Пройден ✅ Пройден
Execute Lua (один инструмент) ✅ Пройден ✅ Пройден ✅ Пройден
Multi-Agent (Creator→Mechanic→Programmer) ⚠️ Частично ✅ Пройден ✅ Пройден
Crafting Memory (многошаговый: memory + lua) ⚠️ Частично ⚠️ В основном ✅ Пройден
Chat History (постоянный контекст) ❌ Слишком мала ⚠️ В основном ✅ Пройден
Player Chat (диалоги NPC) ✅ Пройден ✅ Пройден ✅ Пройден

🏆 Qwen3.5-4B проходит ВСЕ тесты. Рекомендуемый минимум для продакшена.
📊 Qwen3.5-0.8B проходит большинство тестов — впечатляюще для своего размера! Сложности только с многошаговыми цепочками tool calling.
📈 2B — золотая середина — редкие ошибки в многошаговых сценариях, но в целом надёжна.

📦 Установка

1. Установи NuGet DLL (обязательно)

CoreAI использует Microsoft.Extensions.AI для LLM пайплайна. Скопируй эти DLL в папку Assets/Packages/ своего проекта (скачай с NuGet или скопируй из Assets/Packages/ этого репозитория):

NuGet пакет Версия Зачем нужен
Microsoft.Extensions.AI 10.4.1 CoreAI Core
Microsoft.Extensions.AI.Abstractions 10.4.1 CoreAI Core
Microsoft.Bcl.AsyncInterfaces 10.0.4 Системная зависимость
System.Text.Json 10.0.4 JSON сериализация
System.Text.Encodings.Web 10.0.4 Системная зависимость
System.Numerics.Tensors 10.0.4 Системная зависимость
Microsoft.Extensions.Logging.Abstractions 10.0.4 Логирование
Microsoft.Extensions.DependencyInjection.Abstractions 10.0.4 DI
System.Diagnostics.DiagnosticSource 10.0.4 Системная зависимость

💡 Проще всего: Клонируй этот репозиторий и скопируй всю папку Assets/Packages/ в свой проект.

2. Зависимости Git в manifest.json (обязательно)

Unity Package Manager сам не подтягивает все транзитивные Git-пакеты за вас.

Предпочтительно: когда в проект уже добавлен CoreAiUnity, используй меню CoreAI → Setup → Install Git Dependencies — недостающие ключи допишутся в manifest.json, существующие пины не трогаются.

Или вручную: открой файл Packages/manifest.json и добавь строки в блок "dependencies":

    "jp.hadashikick.vcontainer": "https://github.com/hadashiA/VContainer.git?path=VContainer/Assets/VContainer#1.17.0",
    "org.moonsharp.moonsharp": "https://github.com/moonsharp-devs/moonsharp.git?path=/interpreter#upm/beta/v3.0",
    "com.cysharp.messagepipe": "https://github.com/Cysharp/MessagePipe.git?path=src/MessagePipe.Unity/Assets/Plugins/MessagePipe",
    "com.cysharp.messagepipe.vcontainer": "https://github.com/Cysharp/MessagePipe.git?path=src/MessagePipe.Unity/Assets/Plugins/MessagePipe.VContainer",
    "com.cysharp.unitask": "https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask",
    "ai.undream.llm": "https://github.com/undreamai/LLMUnity.git",

(После сохранения файла Unity сама скачает все нужные библиотеки: VContainer, MoonSharp, UniTask, MessagePipe и LLMUnity)

3. Пакеты CoreAI через Git URL

Unity Editor → Window → Package Manager → + → Add package from git URL…

Шаг 1 — Ядро (чистый C#, без UnityEngine):

https://github.com/NeoXider/CoreAI.git?path=Assets/CoreAI

Шаг 2 — Unity-слой (MonoBehaviour, LLM клиенты, инструменты):

https://github.com/NeoXider/CoreAI.git?path=Assets/CoreAiUnity

4. Собери сцену

Чатовая демо-сцена (лучший первый запуск):

CoreAI → Setup → Create Chat Demo Scene

Облегчённая сцена (только scope и ассеты — без UI демо):

CoreAI → Setup → Create Bare Scene (advanced)

Оба пункта:

  • ✅ Создадут или подготовят CoreAILifetimeScope на сцене
  • ✅ Сгенерируют нужные ассеты (CoreAISettings, GameLogSettings, AgentPromptsManifest и др.)
  • ✅ Пропишут ссылки на scope
  • ✅ При бэкенде LLMUnity могут добавить LLM + LLMAgent (wizard «голой» сцены)

5. Настрой LLM бэкенд

Открой настройки: CoreAI → Settings и выбери бэкенд:

Бэкенд Настройка
LLMUnity (локально) Скачай GGUF модель (напр. Qwen3.5-4B) через LLMUnity Model Manager
HTTP API (LM Studio, OpenAI) Укажи API Base URL и API Key в Settings
Auto CoreAI сам выберет лучший доступный бэкенд

6. Первый агент

var storyteller = new AgentBuilder("Storyteller")
    .WithSystemPrompt("You are a campfire storyteller. Share tales about the world.")
    .WithMemory()
    .WithChatHistory()
    .WithMode(AgentMode.ChatOnly)
    .Build();

📖 Полный гайд: QUICK_START.md
🏗️ Справочник AgentBuilder: AGENT_BUILDER.md

Готово! AI-агенты работают. 🎉

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

1. Создай агента

var blacksmith = new AgentBuilder("Blacksmith")
    .WithSystemPrompt("You are a blacksmith. Sell weapons and remember what players bought.")
    .WithTool(new InventoryLlmTool(GameServices.Inventory))
    .WithMemory()
    .WithMode(AgentMode.ToolsAndChat)
    .Build();

blacksmith.ApplyToPolicy(policy);

2. Вызови агента

await orchestrator.RunTaskAsync(new AiTaskRequest
{
    RoleId = "Blacksmith",
    Hint = "What weapons do you have for sale?"
});

3. Результат

Blacksmith: "Добро пожаловать, путник! Вот моё лучшее оружие:
  • Железный меч — 50 золотых
  • Стальной топор — 100 золотых
  • Клинок Пламени — 250 золотых (зачарован!)
Что приглянулось?"

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

Язык: подробные Markdown-гайды в Assets/CoreAiUnity/Docs/ и Assets/CoreAI/Docs/ ведутся на английском; портативный пакет CoreAI — тоже. Разбор токенов/таймаутов MEAI: MEAI_TOKENS_FACT_VS_ESTIMATE.md (EN). Старые ссылки на русский файл ведут на редирект: MEAI_TOKENS_FACT_VS_ESTIMATE_RU.md. Корневой README_RU — навигатор по-русски; за деталями — по ссылкам на англоязычные гайды.

Сначала: Docs/README.md — общий вход по документации репозитория. По Unity-пакету: DOCS_INDEX.md — от новичка до архитектуры.

Сброс файловых сохранений в редакторе: CoreAI → Delete All Persistent Saves... (не во время Play Mode) удаляет persistentDataPath/CoreAI — память агентов, сохранённый чат, сводки (desktop), версии Lua/оверлеев. Ассеты в Assets/ не трогаются. Подробнее: TROUBLESHOOTING.md.

Старт

Документ Содержание
🚀 QUICK_START.md Установка → сцена → LLM → Play
🚀 QUICK_START_FULL.md 10-минутный путь: LM Studio → Unity → первая команда
🎯 COREAI_SINGLETON_API.md CoreAi в одну строку
🏗️ AGENT_BUILDER.md Агент за три шага, режимы, рецепты
⚙️ COREAI_SETTINGS.md Бэкенды, таймауты, стриминг

Чат и стриминг

Документ Содержание
💬 README_CHAT.md CoreAiChatPanel + демо
🌊 STREAMING_ARCHITECTURE.md SSE / LLMUnity → фильтры → UI · стрим в оркестраторе
📊 MEAI_TOKENS_FACT_VS_ESTIMATE.md (EN) usage из API vs префлайт-оценки; SSE include_usage; таймауты HTTP/оркестратора
🔒 LUA_SANDBOX_SECURITY.md (EN) граница Lua sandbox, вырезанные API, лимиты исполнения

Инструменты, память, роли

Документ Содержание
🛠️ MEAI_TOOL_CALLING.md MEAI: ILlmTool → AIFunction
🧰 TOOL_CALLING_BEST_PRACTICES.md (EN) схемы тулов, идемпотентность, SkillSet
🔧 TOOL_CALL_SPEC.md Спека tool calling
🛒 CHAT_TOOL_CALLING.md Торговец с инвентарём
🧠 MemorySystem.md Память и ChatHistory
🤖 AI_AGENT_ROLES.md Роли и промпты

Архитектура

Документ Содержание
🗺️ DEVELOPER_GUIDE.md Карта кода, PR-чеклист
📐 DGF_SPEC.md Нормы: DI, потоки, власть
🔀 LLM_ROUTING.md Портативный роутинг: режимы, политика, usage, таймауты
📑 CoreAI/Docs/README.md Оглавление всех гайдов в Assets/CoreAI/Docs
📋 CHANGELOG · Unity История версий

🧪 Тесты

Unity → Window → General → Test Runner
  ├── EditMode — большой быстрый набор (без реального LLM): промпты, стрим, Lua,
  │              инструменты, rate limit, фасад CoreAi, ремонт имён, backoff мат.,
  │              стрим оркестратора, паритет извлечения tool-call, …
  └── PlayMode — интеграция с настроенным HTTP или локальным GGUF
                 ├── FullPipelineResiliencePlayModeTests — стрим/не-стрим
                 │   tool calls с гарантией no-JSON-leak, memory write/read,
                 │   оркестратор merchant + инвентарь, trace-диагностика
                 ├── ToolNameRepairPlayModeTests — гибрид скрипт+реальный LLM:
                 │   ремонт регистра, самокоррекция неизвестного инструмента
                 └── StreamingToolCallingPlayModeTests — отмена, state parity

В CI сначала гоняй EditMode. PlayMode опционален и требует бэкенд (для HTTP — переменные окружения, см. LLMUNITY_SETUP_AND_MODELS).

💡 Примеры и идеи интеграции

Как можно использовать CoreAI в вашей игре? Вот несколько идей:

  1. «Живой» Торговец: Вместо статического списка товаров, кузнец помнит, что вчера вы продали ему легендарную чешую дракона. Сегодня он может предложить вам «особую сделку» на меч для убийства драконов.
  2. Автономный Гейм-Мастер: Позвольте ИИ следить за здоровьем и ресурсами игрока. Если игроку тяжело, ГМ может «прошептать» подсказку или «случайно» спавнить зелье здоровья неподалёку через WorldCommandTool.
  3. Рассказчик лора в реальном времени: Когда игрок входит в новый биом, ИИ генерирует уникальную историю места, основываясь на текущей погоде, времени суток и экипировке игрока.
  4. Процедурные квесты на базе ИИ: Квесты больше не ограничиваются Убей X волков. Король просит вас Узнать, почему волки светятся, и вы можете реально допросить волков (которые могут быть под действием Lua-заклинания).
  5. Голосовое/Чат-управление миром: «Пусть пойдёт огненный дождь!» -> ИИ разбирает намерение, проверяет WeatherTool и исполняет соответствующий Lua-скрипт для запуска огненного шторма.

🏗️ Архитектура

┌─────────────────────────────────────────────────────────────┐
│                      Player / Game                           │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│                   AiOrchestrator                              │
│  • Priority queue  • JSON strip (defense-in-depth)            │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│              LoggingLlmClientDecorator                        │
│  • HTTP retry (429/5xx)  • Retry-After  • Exp. backoff        │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│                     LLM Client (MeaiLlmClient)               │
│  • LLMUnity (local GGUF)  • OpenAI HTTP  • Stub             │
│  • TryExtractToolCallsFromText (JSON-in-text → tool call)    │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│               SmartToolCallingChatClient                      │
│  • TryRepairToolName (MEMORY → memory)                       │
│  • Дедупликация  • Счётчик ошибок подряд                      │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│                   AI Agents                                  │
│  🛒 Merchant  📜 Programmer  🎨 Creator  📊 Analyzer        │
│  🗡️ CoreMechanic  💬 SmartChat  + Ваши кастомные!          │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│              SkillSet (Self-Service Skills)                   │
│  read_skill → инструкции + схемы                             │
│  call_skill_tool → прокси к реальным тулам                   │
│  Модель видит 2 мета-тула, остальные — по требованию         │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│                   Tools (ILlmTool)                           │
│  🧠 Memory  📜 Lua  🎒 Inventory  ⚙️ GameConfig  + Ваши!    │
└──────────────────────┬──────────────────────────────────────┘
                       ↓
┌─────────────────────────────────────────────────────────────┐
│                   Game World                                 │
│  • Lua Sandbox (MoonSharp)  • MessagePipe  • DI (VContainer)│
└─────────────────────────────────────────────────────────────┘

🤝 Автор и сообщество

Автор: Neoxider
Экосистема: NeoxiderTools
Лицензия: LICENSE

Вопросы, идеи, баги? — создавай Issue! 🐛💡

🎮 CoreAI — хватит писать деревья диалогов. Выпускайте агентов, которые думают, вызывают ваш код и помнят — на локальной 4B-модели или через облачный API, ваш выбор.