micro-models-agent 0.59.0 → 0.60.0

package/README.md

@@ -1,358 +1,358 @@
-# MMA — Micro Models Agent v2
-
-[![npm version](https://img.shields.io/npm/v/micro-models-agent)](https://www.npmjs.com/package/micro-models-agent)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-
-**MMA** — модульный AI-coding агент, оптимизированный для **небольших локальных языковых моделей** (9B параметров, 32K–64K контекст). Работает на ноутбуке, облачное API не требуется.
-
-```bash
-npm install -g micro-models-agent
-mma "перепиши модуль авторизации на JWT"
-```
-
-Создан и протестирован с [Qwen3.5-9B](https://qwen.readthedocs.io/) через LM Studio / Ollama / llama.cpp.
-
----
-
-## Зачем MMA?
-
-Большинство AI-агентов для кода (Devin, Cursor, Copilot) завязаны на облачные модели или дорогие API. MMA работает иначе:
-
-- **Создан для моделей 9B** — оптимизирован под Qwen3.5-9B на обычном железе
-- **Не требует облака** — полностью работает офлайн с любым OpenAI-совместимым бэкендом
-- **Выживает в узком контексте** — умное sliding-window compaction держит 32K-модели продуктивными
-- **Отлавливает галлюцинации** — 3-стадийный пайплайн валидации ловит выдумки, к которым склонны маленькие модели
-- **Agent-Level MoE** — иерархическая декомпозиция задач: маленькие модели справляются со сложной многошаговой работой
-
----
-
-## Возможности
-
-- **6-состояний цикл агента** (INIT → THINK → ACT → OBSERVE → OUTPUT → ERROR) — чистый, предсказуемый, отлаживаемый
-- **Управление бюджетом контекста** — динамический бюджет под модель, sliding-window compaction с извлечением фактов/решений/ошибок
-- **Детекция галлюцинаций** — фактическая (пути файлов), согласованности (откат решений), уверенности (короткие/повторяющиеся ответы)
-- **Гарантии выполнения** — авто-планирование через LLM (без keyword-эвристик), stuck-detection, off-track предупреждения, авто-продвижение плана
-- **Agent-Level MoE** — Router + экспертные сабагенты с фильтрацией инструментов, изолированным контекстом, файловым скоупом и топологическим параллельным выполнением
-- **33 инструмента** — файловая система, шелл, веб-поиск/fetch, браузер (Playwright), планирование, взаимодействие, сабагенты, MCP, пайплайны
-- **19 модулей** — скиллы, плагины, MCP-клиент, пайплайны, indexer проекта, постоянная память, контекст, сессии, браузер, выполнение, детекция галлюцинаций, апдейтер, профиль пользователя, LSP, сертификация моделей, безопасность, артефакты, процессы, ценообразование
-- **MCP-клиент** — подключение к любому MCP-серверу (stdio или SSE)
-- **Модуль безопасности** — включён по умолчанию (balanced): валидация bash-команд, path/network-политики, сканирование контента, шифрование сессий, audit-лог
-- **LSP-диагностика** — TypeScript/CSS/HTML серверы: проверка типов после каждой правки и по запросу
-- **YAML-пайплайны** — DAG-движок с параллельными волнами, зависимостями и повторными попытками
-- **Управление сессиями** — постоянные JSONL-сессии с REPL-командами
-- **Карта проекта** — автоматический обход файлов + извлечение экспортов + дисковый кэш
-- **i18n** — все строки интерфейса через `t()`, включены английский и русский
-- **8K–120K контекст** — адаптируется под любое контекстное окно модели
-- **Без TUI** — минимальный CLI + REPL с markdown→ANSI форматированием
-- **llama.cpp / Jinja proven** — проверено на граничных случаях Jinja-шаблонов (system-first, streaming fallback, явный `stream: false`)
-
----
-
-## Установка
-
-### Требования
-
-- **Среда выполнения:** [Bun](https://bun.sh) (рекомендуется) или Node.js ≥ 20
-- **LLM-бэкенд:** Любой OpenAI-совместимый сервер (LM Studio, Ollama, vLLM, llama.cpp, Together AI)
-
-### Через npm (рекомендуется)
-
-```bash
-npm install -g micro-models-agent@latest
-```
-
-После установки команда `mma` будет доступна в терминале. Если после установки `mma` не находится — попробуйте переоткрыть терминал или выполните:
-
-```bash
-# PowerShell
-npm uninstall -g micro-models-agent
-npm install -g micro-models-agent@latest
-
-# Проверка
-mma --version
-```
-
-### Из исходников
-
-```bash
-git clone https://github.com/your-org/micro-models-agent
-cd micro-models-agent
-bun install
-bun run build:prod
-```
-
----
-
-## Быстрый старт
-
-### 1. Запустите LLM-бэкенд
-
-Направьте MMA на любой OpenAI-совместимый эндпоинт. Пример с LM Studio:
-
-```bash
-# LM Studio слушает http://localhost:1234 по умолчанию
-```
-
-### 2. Запустите мастер настройки
-
-```bash
-bun run mma init
-```
-
-Сканирует локальные порты, находит модель, тестирует соединение и записывает конфиг.
-
-### 3. Используйте агента
-
-```bash
-# Одноразовый режим
-bun run mma "создай REST API на Express и добавь тесты"
-
-# Интерактивный REPL
-bun run dev
-```
-
----
-
-## Использование
-
-### CLI
-
-```bash
-bun run mma "<prompt>"
-
-# Подкоманды
-bun run mma init                       # Интерактивный мастер настройки
-bun run mma config set model qwen/qwen3.5-9b
-bun run mma config show
-bun run mma model list                 # Список доступных моделей (✔ = сертифицирована)
-bun run mma model use qwen3.5-9b       # Переключить модель
-bun run mma model certify <name>       # Сертификация модели на бэкенде
-bun run mma model cert-status <name>   # Статус сертификации
-bun run mma model cert-list            # Все сертификации
-bun run mma model uncertify <name>     # Отозвать сертификацию
-bun run mma provider list              # Список провайдеров
-bun run mma provider use opencode-zen  # Хостед-провайдер (zen / go)
-bun run mma context                    # Токены/бюджет контекста
-bun run mma security status            # Текущая конфигурация безопасности
-bun run mma security policies          # Доступные политики (strict/balanced/permissive)
-bun run mma security set-policy strict # Применить политику
-bun run mma plugins list               # Загруженные плагины (--all — включая встроенные)
-bun run mma session list               # Список сессий
-bun run mma session show <id>          # Детали сессии
-bun run mma session delete <id>        # Удалить сессию
-
-# Флаги одноразового запуска
-bun run mma "<prompt>" --json              # Машиночитаемый JSON-результат
-bun run mma "<prompt>" -d <dir>            # Рабочая директория агента
-bun run mma "<prompt>" --no-agents-md      # Не грузить AGENTS.md в системный промпт
-bun run mma "<prompt>" --exit-on-complete  # Выйти после первого финального ответа
-```
-
-### REPL
-
-```bash
-bun run dev
-```
-
-| Команда | Алиасы | Описание |
-|---------|--------|----------|
-| `/help` | | Показать справку |
-| `/sessions` | `/ls` | Список сессий (* = активная) |
-| `/new <name>` | `/create` | Создать новую сессию |
-| `/resume <id\|name>` | `/switch`, `/use` | Переключиться на сессию |
-| `/rename <name>` | | Переименовать текущую сессию |
-| `/delete <id>` | `/rm` | Удалить сессию |
-| `/model [name]` | | Показать/сменить модель |
-| `/provider` | | Показать/сменить провайдера |
-| `/status` | | Статус: модель, плагины, сессия, стоимость |
-| `/context` | `/ctx` | Токены и бюджет контекста |
-| `/reasoning` | | Переключить показ reasoning |
-| `/image <path\|url>` | | Прикрепить изображение (или Ctrl+V) |
-| `/run <cmd>` | | Выполнить shell-команду без агента |
-| `/sysprompt` | | Показать системный промпт |
-| `/wizard` | | Мастер настройки |
-| `/skill <name>` | | Загрузить скилл |
-| `/plugins` | | Плагины (`--all` — все) |
-| `/lsp [status\|restart\|check <path>]` | | Диагностика LSP |
-| `/reload` | | Перечитать конфиг и модули |
-| `/clear` | | Очистить контекст сессии |
-| `/exit` | | Выйти из REPL |
-
-Горячие клавиши: `Esc Esc` — прервать агента; `Ctrl+C` — выход; `Ctrl+V` — вставить изображение из буфера обмена; `Shift+Enter` — перенос строки.
-
-### Разработка
-
-```bash
-bun run mma "почини страницу логина"    # Запуск агента
-bun run dev                             # Watch-режим (авто-перезапуск при изменениях)
-bun run build:prod                      # Сборка для публикации
-bun test                                # Запуск тестов
-bun run typecheck                       # Проверка типов
-```
-
----
-
-## Конфигурация
-
-3-слойный конфиг: `defaults.ts` → `~/.mma/config.json` (глобальный) → `.mmrc` (проект) + переменные окружения.
-
-Ключевые опции (полный список в `src/config/defaults.ts`):
-
-| Опция | По умолчанию | Описание |
-|-------|-------------|----------|
-| `model` | `qwen/qwen3.5-9b` | Имя модели для бэкенда |
-| `provider.baseUrl` | `http://localhost:1234/v1` | URL OpenAI-совместимого API |
-| `contextWindow` | `32768` | Контекстное окно модели в токенах |
-| `autoPlan` | `true` | Авто-создание планов для многошаговых задач |
-| `maxToolIterations` | `1000` | Макс. вызовов инструментов за запуск |
-| `stuckThreshold` | `6` | Итераций без прогресса до stuck-detection |
-| `moe.enabled` | `false` | Включить Agent-Level MoE |
-| `security.enabled` | `true` | Модуль безопасности (balanced-политика по умолчанию) |
-| `locale` | `en` | Язык интерфейса (`en` / `ru`) |
-| `logLevel` | `info` | Уровень логирования |
-
-### Agent-Level MoE
-
-```json
-{
-  "moe": { "enabled": true },
-  "orchestrator": {
-    "model": "qwen3-70b-414k",
-    "provider": { "baseUrl": "http://localhost:1234/v1" }
-  },
-  "experts": {
-    "code": { "model": "qwen/qwen3.5-9b", "tool_tags": ["file", "code", "shell"], "max_attempts": 3 },
-    "research": { "model": "qwen/qwen3.5-9b", "tool_tags": ["research"], "max_attempts": 3 },
-    "browser": { "model": "qwen/qwen3.5-9b", "tool_tags": ["browser", "vision"], "max_attempts": 3 }
-  }
-}
-```
-
----
-
-## Архитектура
-
-```
-CLI (main.ts → commands.ts / repl.ts / setup.ts)
-  → Core (agent.ts state machine → prompt-builder.ts)
-    → LLM Layer (provider.ts → openai-compat.ts → response.ts → token-counter.ts)
-      → Tools (registry.ts → executor.ts → 33 tools)
-        → Modules (skills, plugins, mcp, pipelines, indexer, memory, context, session,
-                   hallucination, execution, updater, user-profile, browser, lsp,
-                   security, certification, artifacts, processes, pricing)
-```
-
-### Структура проекта
-
-```
-src/
-├── core/          # Цикл агента, сборщик промптов, типы
-├── llm/           # Абстракция провайдера, OpenAI-совместимость, стриминг, подсчёт токенов
-├── tools/         # 33 инструмента с реестром, исполнителем, скоуп-гардами
-├── modules/       # 19 модулей (скиллы, плагины, mcp, пайплайны, indexer, память, контекст,
-│                  #   сессии, галлюцинации, выполнение, апдейтер, профиль, браузер, LSP,
-│                  #   безопасность, сертификация моделей, артефакты, процессы, ценообразование)
-├── cli/           # Точка входа, команды, REPL, мастер настройки
-├── config/        # 3-слойный конфиг: defaults → глобальный → проект
-├── i18n/          # en.json + ru.json + t()
-├── ui/            # Markdown→ANSI форматтер
-└── logger/        # Структурированный логгер с уровнями и дочерними логгерами
-```
-
----
-
-## Инструменты
-
-| Инструмент | Описание |
-|------------|----------|
-| `read_file` | Чтение файла с offset/limit |
-| `write_file` | Создание/перезапись с созданием директорий |
-| `edit_file` | Поиск-и-замена в существующих файлах |
-| `glob` | Поиск по glob-паттернам |
-| `grep` | Поиск по содержимому через ripgrep |
-| `list_dir` | Список содержимого директории |
-| `create_dir` | Создание директории (рекурсивно) |
-| `delete_file` | Удаление файла или пустой директории |
-| `move_file` | Перемещение/переименование файла или директории |
-| `file_info` | Метаданные файла/директории |
-| `bash` | Выполнение shell-команд |
-| `subagent` | Изолированный сабагент со скоупом |
-| `web_search` | Поиск в интернете |
-| `web_fetch` | Загрузка веб-страницы (15K символов, 15s таймаут) |
-| `web_browse` | JS-less HTTP fetch страницы (без движка браузера) |
-| `browser` | Браузер на Playwright (клик, ввод, скролл, скриншот) |
-| `plan` | Создание/обновление/отмена планов |
-| `todo` | Отслеживание задач |
-| `load_skill` | Загрузить скилл во время выполнения |
-| `pipeline_run` | Выполнить YAML-пайплайн |
-| `mcp_call` | Вызвать инструмент MCP-сервера |
-| `search_history` | Поиск по истории сессий |
-| `project_map` | Запрос карты проекта (summary, refresh, find) |
-| `chunk_query` | Параллельная обработка больших текстов чанками |
-| `download_file` | Скачать бинарный файл по URL на диск |
-| `process_list` / `process_log` / `process_kill` | Управление фоновыми процессами |
-| `remember` / `recall` | Постоянная память агента |
-| `attach_image` | Прикрепить изображение (файл/URL/буфер обмена) |
-| `enable_tools` | Включить скрытые группы инструментов на ходу |
-| `lsp_check` | Диагностика LSP (TypeScript/CSS/HTML) |
-| `verify` | Верификация шагов плана |
-
-> Примечание: интерактивные тулзы `question`/`approve` выключены — модель задаёт вопросы текстом в ответе.
-
----
-
-## Тестирование
-
-```bash
-bun test                              # Модульные + компонентные тесты
-bun test tests/agent.test.ts          # Один файл
-bun run test:integration              # Интеграционные тесты (требуют LLM-бэкенд)
-bun run typecheck                     # Проверка типов
-```
-
-### Тестирование агента из консоли (agent-driven)
-
-MMA можно тестировать в одноразовом headless-режиме без интерактивного REPL — это удобно для проверки фич и регрессий из терминала или другим агентом:
-
-```bash
-# Одноразовый прогон: без AGENTS.md, выход сразу после ответа, песочница
-bun run mma "<промпт>" --no-agents-md --exit-on-complete -d <путь-к-песочнице>
-```
-
-- **Песочница** — всегда внутри `_testing/` в корне проекта (например `_testing/<case-name>/`), никогда в корне или в `src/`. Папка `_testing/` добавлена в `.gitignore`.
-- **`--no-agents-md`** — не грузить AGENTS.md проекта в системный промпт (чистая среда).
-- **`--exit-on-complete`** — выйти сразу после первого финального ответа; интерактивные тулзы (`question`/`approve`) не блокируют stdin, а возвращают ошибку.
-- **`-d <dir>`** — рабочая директория агента (туда он создаёт файлы).
-- Каждый прогон сохраняется в сессию `~/.mma/sessions/<id>/` — можно посмотреть через `bun run mma session list` / `session show <id>`.
-
----
-
-## Принципы дизайна
-
-1. **Ни одного файла >300 строк** — разделяй при приближении к лимиту
-2. **Маленькие файлы, одна ответственность** — каждый файл делает одно дело
-3. **KISS state machine** — никаких god-объектов, никакой вложенности if-else в цикле агента
-4. **Изоляция ошибок плагинов** — падение одного плагина не останавливает другие
-5. **Безопасность путей** — все файловые инструменты проверяют `targetPath.startsWith(baseDir)`
-6. **TDD** — сначала тест, потом реализация, потом коммит
-7. **Никаких захардкоженных строк** — весь текст через `t()` i18n
-8. **Никакого keyword matching** — LLM решает когда планировать, не эвристики
-9. **Без TUI** — минимальный CLI + REPL с markdown→ANSI
-
----
-
-## Лицензия
-
-MIT
-
----
-
-## Благодарности
-
-- [Qwen3.5-9B](https://qwen.readthedocs.io/) — основная целевая модель
-- [LM Studio](https://lmstudio.ai/) — рекомендуемый локальный инференс-сервер
-- [llama.cpp](https://github.com/ggerganov/llama.cpp) — инференс-движок
-
----
-
-**Сделано для локальных моделей. Работает везде.**
+# MMA — Micro Models Agent v2
+
+[![npm version](https://img.shields.io/npm/v/micro-models-agent)](https://www.npmjs.com/package/micro-models-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**MMA** — модульный AI-coding агент, оптимизированный для **небольших локальных языковых моделей** (9B параметров, 32K–64K контекст). Работает на ноутбуке, облачное API не требуется.
+
+```bash
+npm install -g micro-models-agent
+mma "перепиши модуль авторизации на JWT"
+```
+
+Создан и протестирован с [Qwen3.5-9B](https://qwen.readthedocs.io/) через LM Studio / Ollama / llama.cpp.
+
+---
+
+## Зачем MMA?
+
+Большинство AI-агентов для кода (Devin, Cursor, Copilot) завязаны на облачные модели или дорогие API. MMA работает иначе:
+
+- **Создан для моделей 9B** — оптимизирован под Qwen3.5-9B на обычном железе
+- **Не требует облака** — полностью работает офлайн с любым OpenAI-совместимым бэкендом
+- **Выживает в узком контексте** — умное sliding-window compaction держит 32K-модели продуктивными
+- **Отлавливает галлюцинации** — 3-стадийный пайплайн валидации ловит выдумки, к которым склонны маленькие модели
+- **Agent-Level MoE** — иерархическая декомпозиция задач: маленькие модели справляются со сложной многошаговой работой
+
+---
+
+## Возможности
+
+- **6-состояний цикл агента** (INIT → THINK → ACT → OBSERVE → OUTPUT → ERROR) — чистый, предсказуемый, отлаживаемый
+- **Управление бюджетом контекста** — динамический бюджет под модель, sliding-window compaction с извлечением фактов/решений/ошибок
+- **Детекция галлюцинаций** — фактическая (пути файлов), согласованности (откат решений), уверенности (короткие/повторяющиеся ответы)
+- **Гарантии выполнения** — авто-планирование через LLM (без keyword-эвристик), stuck-detection, off-track предупреждения, авто-продвижение плана
+- **Agent-Level MoE** — Router + экспертные сабагенты с фильтрацией инструментов, изолированным контекстом, файловым скоупом и топологическим параллельным выполнением
+- **33 инструмента** — файловая система, шелл, веб-поиск/fetch, браузер (Playwright), планирование, взаимодействие, сабагенты, MCP, пайплайны
+- **19 модулей** — скиллы, плагины, MCP-клиент, пайплайны, indexer проекта, постоянная память, контекст, сессии, браузер, выполнение, детекция галлюцинаций, апдейтер, профиль пользователя, LSP, сертификация моделей, безопасность, артефакты, процессы, ценообразование
+- **MCP-клиент** — подключение к любому MCP-серверу (stdio или SSE)
+- **Модуль безопасности** — включён по умолчанию (balanced): валидация bash-команд, path/network-политики, сканирование контента, шифрование сессий, audit-лог
+- **LSP-диагностика** — TypeScript/CSS/HTML серверы: проверка типов после каждой правки и по запросу
+- **YAML-пайплайны** — DAG-движок с параллельными волнами, зависимостями и повторными попытками
+- **Управление сессиями** — постоянные JSONL-сессии с REPL-командами
+- **Карта проекта** — автоматический обход файлов + извлечение экспортов + дисковый кэш
+- **i18n** — все строки интерфейса через `t()`, включены английский и русский
+- **8K–120K контекст** — адаптируется под любое контекстное окно модели
+- **Без TUI** — минимальный CLI + REPL с markdown→ANSI форматированием
+- **llama.cpp / Jinja proven** — проверено на граничных случаях Jinja-шаблонов (system-first, streaming fallback, явный `stream: false`)
+
+---
+
+## Установка
+
+### Требования
+
+- **Среда выполнения:** [Bun](https://bun.sh) (рекомендуется) или Node.js ≥ 20
+- **LLM-бэкенд:** Любой OpenAI-совместимый сервер (LM Studio, Ollama, vLLM, llama.cpp, Together AI)
+
+### Через npm (рекомендуется)
+
+```bash
+npm install -g micro-models-agent@latest
+```
+
+После установки команда `mma` будет доступна в терминале. Если после установки `mma` не находится — попробуйте переоткрыть терминал или выполните:
+
+```bash
+# PowerShell
+npm uninstall -g micro-models-agent
+npm install -g micro-models-agent@latest
+
+# Проверка
+mma --version
+```
+
+### Из исходников
+
+```bash
+git clone https://github.com/your-org/micro-models-agent
+cd micro-models-agent
+bun install
+bun run build:prod
+```
+
+---
+
+## Быстрый старт
+
+### 1. Запустите LLM-бэкенд
+
+Направьте MMA на любой OpenAI-совместимый эндпоинт. Пример с LM Studio:
+
+```bash
+# LM Studio слушает http://localhost:1234 по умолчанию
+```
+
+### 2. Запустите мастер настройки
+
+```bash
+bun run mma init
+```
+
+Сканирует локальные порты, находит модель, тестирует соединение и записывает конфиг.
+
+### 3. Используйте агента
+
+```bash
+# Одноразовый режим
+bun run mma "создай REST API на Express и добавь тесты"
+
+# Интерактивный REPL
+bun run dev
+```
+
+---
+
+## Использование
+
+### CLI
+
+```bash
+bun run mma "<prompt>"
+
+# Подкоманды
+bun run mma init                       # Интерактивный мастер настройки
+bun run mma config set model qwen/qwen3.5-9b
+bun run mma config show
+bun run mma model list                 # Список доступных моделей (✔ = сертифицирована)
+bun run mma model use qwen3.5-9b       # Переключить модель
+bun run mma model certify <name>       # Сертификация модели на бэкенде
+bun run mma model cert-status <name>   # Статус сертификации
+bun run mma model cert-list            # Все сертификации
+bun run mma model uncertify <name>     # Отозвать сертификацию
+bun run mma provider list              # Список провайдеров
+bun run mma provider use opencode-zen  # Хостед-провайдер (zen / go)
+bun run mma context                    # Токены/бюджет контекста
+bun run mma security status            # Текущая конфигурация безопасности
+bun run mma security policies          # Доступные политики (strict/balanced/permissive)
+bun run mma security set-policy strict # Применить политику
+bun run mma plugins list               # Загруженные плагины (--all — включая встроенные)
+bun run mma session list               # Список сессий
+bun run mma session show <id>          # Детали сессии
+bun run mma session delete <id>        # Удалить сессию
+
+# Флаги одноразового запуска
+bun run mma "<prompt>" --json              # Машиночитаемый JSON-результат
+bun run mma "<prompt>" -d <dir>            # Рабочая директория агента
+bun run mma "<prompt>" --no-agents-md      # Не грузить AGENTS.md в системный промпт
+bun run mma "<prompt>" --exit-on-complete  # Выйти после первого финального ответа
+```
+
+### REPL
+
+```bash
+bun run dev
+```
+
+| Команда | Алиасы | Описание |
+|---------|--------|----------|
+| `/help` | | Показать справку |
+| `/sessions` | `/ls` | Список сессий (* = активная) |
+| `/new <name>` | `/create` | Создать новую сессию |
+| `/resume <id\|name>` | `/switch`, `/use` | Переключиться на сессию |
+| `/rename <name>` | | Переименовать текущую сессию |
+| `/delete <id>` | `/rm` | Удалить сессию |
+| `/model [name]` | | Показать/сменить модель |
+| `/provider` | | Показать/сменить провайдера |
+| `/status` | | Статус: модель, плагины, сессия, стоимость |
+| `/context` | `/ctx` | Токены и бюджет контекста |
+| `/reasoning` | | Переключить показ reasoning |
+| `/image <path\|url>` | | Прикрепить изображение (или Ctrl+V) |
+| `/run <cmd>` | | Выполнить shell-команду без агента |
+| `/sysprompt` | | Показать системный промпт |
+| `/wizard` | | Мастер настройки |
+| `/skill <name>` | | Загрузить скилл |
+| `/plugins` | | Плагины (`--all` — все) |
+| `/lsp [status\|restart\|check <path>]` | | Диагностика LSP |
+| `/reload` | | Перечитать конфиг и модули |
+| `/clear` | | Очистить контекст сессии |
+| `/exit` | | Выйти из REPL |
+
+Горячие клавиши: `Esc Esc` — прервать агента; `Ctrl+C` — выход; `Ctrl+V` — вставить изображение из буфера обмена; `Shift+Enter` — перенос строки.
+
+### Разработка
+
+```bash
+bun run mma "почини страницу логина"    # Запуск агента
+bun run dev                             # Watch-режим (авто-перезапуск при изменениях)
+bun run build:prod                      # Сборка для публикации
+bun test                                # Запуск тестов
+bun run typecheck                       # Проверка типов
+```
+
+---
+
+## Конфигурация
+
+3-слойный конфиг: `defaults.ts` → `~/.mma/config.json` (глобальный) → `.mmrc` (проект) + переменные окружения.
+
+Ключевые опции (полный список в `src/config/defaults.ts`):
+
+| Опция | По умолчанию | Описание |
+|-------|-------------|----------|
+| `model` | `qwen/qwen3.5-9b` | Имя модели для бэкенда |
+| `provider.baseUrl` | `http://localhost:1234/v1` | URL OpenAI-совместимого API |
+| `contextWindow` | `32768` | Контекстное окно модели в токенах |
+| `autoPlan` | `true` | Авто-создание планов для многошаговых задач |
+| `maxToolIterations` | `1000` | Макс. вызовов инструментов за запуск |
+| `stuckThreshold` | `6` | Итераций без прогресса до stuck-detection |
+| `moe.enabled` | `false` | Включить Agent-Level MoE |
+| `security.enabled` | `true` | Модуль безопасности (balanced-политика по умолчанию) |
+| `locale` | `en` | Язык интерфейса (`en` / `ru`) |
+| `logLevel` | `info` | Уровень логирования |
+
+### Agent-Level MoE
+
+```json
+{
+  "moe": { "enabled": true },
+  "orchestrator": {
+    "model": "qwen3-70b-414k",
+    "provider": { "baseUrl": "http://localhost:1234/v1" }
+  },
+  "experts": {
+    "code": { "model": "qwen/qwen3.5-9b", "tool_tags": ["file", "code", "shell"], "max_attempts": 3 },
+    "research": { "model": "qwen/qwen3.5-9b", "tool_tags": ["research"], "max_attempts": 3 },
+    "browser": { "model": "qwen/qwen3.5-9b", "tool_tags": ["browser", "vision"], "max_attempts": 3 }
+  }
+}
+```
+
+---
+
+## Архитектура
+
+```
+CLI (main.ts → commands.ts / repl.ts / setup.ts)
+  → Core (agent.ts state machine → prompt-builder.ts)
+    → LLM Layer (provider.ts → openai-compat.ts → response.ts → token-counter.ts)
+      → Tools (registry.ts → executor.ts → 33 tools)
+        → Modules (skills, plugins, mcp, pipelines, indexer, memory, context, session,
+                   hallucination, execution, updater, user-profile, browser, lsp,
+                   security, certification, artifacts, processes, pricing)
+```
+
+### Структура проекта
+
+```
+src/
+├── core/          # Цикл агента, сборщик промптов, типы
+├── llm/           # Абстракция провайдера, OpenAI-совместимость, стриминг, подсчёт токенов
+├── tools/         # 33 инструмента с реестром, исполнителем, скоуп-гардами
+├── modules/       # 19 модулей (скиллы, плагины, mcp, пайплайны, indexer, память, контекст,
+│                  #   сессии, галлюцинации, выполнение, апдейтер, профиль, браузер, LSP,
+│                  #   безопасность, сертификация моделей, артефакты, процессы, ценообразование)
+├── cli/           # Точка входа, команды, REPL, мастер настройки
+├── config/        # 3-слойный конфиг: defaults → глобальный → проект
+├── i18n/          # en.json + ru.json + t()
+├── ui/            # Markdown→ANSI форматтер
+└── logger/        # Структурированный логгер с уровнями и дочерними логгерами
+```
+
+---
+
+## Инструменты
+
+| Инструмент | Описание |
+|------------|----------|
+| `read_file` | Чтение файла с offset/limit |
+| `write_file` | Создание/перезапись с созданием директорий |
+| `edit_file` | Поиск-и-замена в существующих файлах |
+| `glob` | Поиск по glob-паттернам |
+| `grep` | Поиск по содержимому через ripgrep |
+| `list_dir` | Список содержимого директории |
+| `create_dir` | Создание директории (рекурсивно) |
+| `delete_file` | Удаление файла или пустой директории |
+| `move_file` | Перемещение/переименование файла или директории |
+| `file_info` | Метаданные файла/директории |
+| `bash` | Выполнение shell-команд |
+| `subagent` | Изолированный сабагент со скоупом |
+| `web_search` | Поиск в интернете |
+| `web_fetch` | Загрузка веб-страницы (15K символов, 15s таймаут) |
+| `web_browse` | JS-less HTTP fetch страницы (без движка браузера) |
+| `browser` | Браузер на Playwright (клик, ввод, скролл, скриншот) |
+| `plan` | Создание/обновление/отмена планов |
+| `todo` | Отслеживание задач |
+| `load_skill` | Загрузить скилл во время выполнения |
+| `pipeline_run` | Выполнить YAML-пайплайн |
+| `mcp_call` | Вызвать инструмент MCP-сервера |
+| `search_history` | Поиск по истории сессий |
+| `project_map` | Запрос карты проекта (summary, refresh, find) |
+| `chunk_query` | Параллельная обработка больших текстов чанками |
+| `download_file` | Скачать бинарный файл по URL на диск |
+| `process_list` / `process_log` / `process_kill` | Управление фоновыми процессами |
+| `remember` / `recall` | Постоянная память агента |
+| `attach_image` | Прикрепить изображение (файл/URL/буфер обмена) |
+| `enable_tools` | Включить скрытые группы инструментов на ходу |
+| `lsp_check` | Диагностика LSP (TypeScript/CSS/HTML) |
+| `verify` | Верификация шагов плана |
+
+> Примечание: интерактивные тулзы `question`/`approve` выключены — модель задаёт вопросы текстом в ответе.
+
+---
+
+## Тестирование
+
+```bash
+bun test                              # Модульные + компонентные тесты
+bun test tests/agent.test.ts          # Один файл
+bun run test:integration              # Интеграционные тесты (требуют LLM-бэкенд)
+bun run typecheck                     # Проверка типов
+```
+
+### Тестирование агента из консоли (agent-driven)
+
+MMA можно тестировать в одноразовом headless-режиме без интерактивного REPL — это удобно для проверки фич и регрессий из терминала или другим агентом:
+
+```bash
+# Одноразовый прогон: без AGENTS.md, выход сразу после ответа, песочница
+bun run mma "<промпт>" --no-agents-md --exit-on-complete -d <путь-к-песочнице>
+```
+
+- **Песочница** — всегда внутри `_testing/` в корне проекта (например `_testing/<case-name>/`), никогда в корне или в `src/`. Папка `_testing/` добавлена в `.gitignore`.
+- **`--no-agents-md`** — не грузить AGENTS.md проекта в системный промпт (чистая среда).
+- **`--exit-on-complete`** — выйти сразу после первого финального ответа; интерактивные тулзы (`question`/`approve`) не блокируют stdin, а возвращают ошибку.
+- **`-d <dir>`** — рабочая директория агента (туда он создаёт файлы).
+- Каждый прогон сохраняется в сессию `~/.mma/sessions/<id>/` — можно посмотреть через `bun run mma session list` / `session show <id>`.
+
+---
+
+## Принципы дизайна
+
+1. **Ни одного файла >300 строк** — разделяй при приближении к лимиту
+2. **Маленькие файлы, одна ответственность** — каждый файл делает одно дело
+3. **KISS state machine** — никаких god-объектов, никакой вложенности if-else в цикле агента
+4. **Изоляция ошибок плагинов** — падение одного плагина не останавливает другие
+5. **Безопасность путей** — все файловые инструменты проверяют `targetPath.startsWith(baseDir)`
+6. **TDD** — сначала тест, потом реализация, потом коммит
+7. **Никаких захардкоженных строк** — весь текст через `t()` i18n
+8. **Никакого keyword matching** — LLM решает когда планировать, не эвристики
+9. **Без TUI** — минимальный CLI + REPL с markdown→ANSI
+
+---
+
+## Лицензия
+
+MIT
+
+---
+
+## Благодарности
+
+- [Qwen3.5-9B](https://qwen.readthedocs.io/) — основная целевая модель
+- [LM Studio](https://lmstudio.ai/) — рекомендуемый локальный инференс-сервер
+- [llama.cpp](https://github.com/ggerganov/llama.cpp) — инференс-движок
+
+---
+
+**Сделано для локальных моделей. Работает везде.**