Initial project blueprint

docs/architecture/01_overview.md

@@ -0,0 +1,116 @@
+# Архитектура AI Orchestrator
+
+## Почему отдельный проект
+
+Оркестратор должен быть независимым от текущей Local LLM Platform.
+
+Он должен уметь работать:
+- с локальными моделями из Local LLM Platform;
+- с внешними моделями;
+- с любыми MCP-серверами;
+- с local worker на компьютере пользователя;
+- с будущими инструментами: файлы, браузер, 1С, SQL, desktop, image, audio, video.
+
+## Разделение ответственности
+
+### Local LLM Platform
+
+Провайдер моделей:
+
+```text
+GET /models
+POST /v1/chat/completions
+POST /v1/embeddings
+POST /v1/vision/analyze
+```
+
+### AI Orchestrator
+
+Runtime управления задачами:
+
+```text
+POST /chat
+POST /tasks
+POST /confirmations/{id}/approve
+POST /confirmations/{id}/reject
+GET /tasks/{id}
+GET /tasks/{id}/events
+```
+
+### 1C MCP Server
+
+Источник инструментов:
+
+```text
+tools/list
+tools/call
+resources/list
+resources/read
+prompts/list
+prompts/get
+```
+
+### Local Worker
+
+Исполнитель на локальном компьютере:
+
+```text
+file.read
+file.write
+file.search
+file.apply_patch
+command.run
+desktop.screenshot
+browser.open
+mcp.proxy
+```
+
+## Оркестратор и агент
+
+В системе нет отдельной магической сущности “главный агент”.
+
+Есть:
+
+```text
+Orchestrator = управляет выполнением
+Execution Graph = план задачи
+Planner = строит граф
+Worker = выполняет конкретный узел графа
+Reviewer = проверяет результат
+Finalizer = формирует итог пользователю
+```
+
+Agent — это технический профиль выполнения:
+
+```text
+AgentProfile = prompt + model_slot + tools + limits + output_schema
+```
+
+## Правильная модель
+
+Не так:
+
+```text
+agent запускает agent
+  agent запускает agent
+    agent запускает agent
+```
+
+А так:
+
+```text
+Orchestrator
+   ↓
+Planner
+   ↓
+Execution Graph
+   ├─ worker: sql
+   ├─ worker: 1c
+   ├─ worker: file
+   ├─ worker: vision
+   └─ reviewer
+```
+
+Workers не создают других workers.
+Они возвращают предложения или результаты orchestrator.
+Только orchestrator запускает следующие узлы.

docs/architecture/02_components.md

@@ -0,0 +1,127 @@
+# Компоненты
+
+## 1. Conversation Manager
+
+Отвечает за пользовательский контекст:
+
+- диалоги;
+- сообщения;
+- вложения;
+- выбранный проект;
+- активные workers;
+- выбранные режимы доступа;
+- настройки моделей;
+- историю подтверждений.
+
+Не выполняет tools напрямую.
+
+## 2. Orchestrator
+
+Главный серверный компонент.
+
+Функции:
+
+- принять задачу;
+- определить тип задачи;
+- выбрать execution mode;
+- запустить planner;
+- создать execution graph;
+- запускать узлы графа;
+- вызывать model router;
+- вызывать MCP tools;
+- отправлять команды local worker;
+- обрабатывать подтверждения;
+- логировать;
+- собирать финальный результат.
+
+## 3. Model Router
+
+Единый интерфейс к моделям.
+
+Слоты:
+
+```text
+weak
+strong
+vision
+embedding
+reranker
+```
+
+Каждый слот настраивается:
+
+```text
+provider = local | external | disabled
+model = string
+base_url = string
+api_key_env = string
+```
+
+## 4. MCP Client
+
+Универсальный клиент к MCP-серверам.
+
+Не должен знать про 1С.
+
+Поддержать:
+
+- initialize;
+- tools/list;
+- tools/call;
+- resources/list;
+- resources/read;
+- prompts/list;
+- prompts/get.
+
+## 5. Local Worker Gateway
+
+Серверная часть для связи с local workers.
+
+Local worker сам открывает исходящее соединение:
+
+```text
+Local Worker → WebSocket/gRPC stream → Server
+```
+
+Сервер не открывает входящий порт на ПК пользователя.
+
+## 6. Policy Engine
+
+Не содержит жестких запретов.
+
+Он читает настройки проекта и решает:
+
+- выполнять сразу;
+- запросить подтверждение;
+- показать preview;
+- поставить задачу в ручной режим;
+- пропустить, если выбран full_auto.
+
+## 7. Execution Graph Engine
+
+Хранит и исполняет граф:
+
+```text
+nodes:
+  - id
+  - type
+  - input
+  - output
+  - status
+  - dependencies
+  - assigned_runner
+  - attempts
+  - logs
+```
+
+Статусы:
+
+```text
+pending
+running
+waiting_confirmation
+completed
+failed
+cancelled
+skipped
+```

docs/architecture/03_no_hardcoded_bans.md

@@ -0,0 +1,99 @@
+# Принцип: нет жестких запретов в коде
+
+## Требование
+
+В проекте не должно быть hardcoded-запретов вида:
+
+```text
+if tool == "command.run": deny
+if sql contains "DELETE": deny
+if action == "filesystem": deny
+```
+
+Так делать нельзя.
+
+## Правильный подход
+
+Код должен классифицировать действие и спросить policy engine.
+
+```text
+action → classify → policy.check → decision
+```
+
+Policy decision:
+
+```json
+{
+  "decision": "allow | confirm | manual | disabled_by_config",
+  "reason": "string",
+  "requires_confirmation": true,
+  "preview": {}
+}
+```
+
+## Пример
+
+Команда:
+
+```text
+file.write D:/Projects/test.txt
+```
+
+Tool возвращает metadata:
+
+```json
+{
+  "risk_level": "write",
+  "resource": "filesystem",
+  "preview_available": true
+}
+```
+
+Policy проекта:
+
+```json
+{
+  "filesystem": {
+    "mode": "confirm"
+  }
+}
+```
+
+Результат:
+
+```text
+Нужно подтверждение.
+```
+
+Если policy:
+
+```json
+{
+  "filesystem": {
+    "mode": "full_auto"
+  }
+}
+```
+
+Результат:
+
+```text
+Выполнить сразу.
+```
+
+## Режимы
+
+```text
+full_auto — выполнять без подтверждения
+confirm — спросить подтверждение
+manual — показать план и ждать ручного запуска
+disabled — отключено настройкой
+```
+
+`disabled` допустим только как настройка проекта, а не как зашитый запрет.
+
+## Зачем
+
+Пользователь сам выбирает уровень риска.
+
+Система не должна становиться бесполезной из-за того, что разработчик заранее запретил все потенциально опасные действия.