APAW/agent-evolution/README.md

# Agent Evolution Dashboard

Интерактивная панель для отслеживания эволюции агентной системы APAW.

## 🚀 Быстрый старт

### Синхронизация данных

```bash
# Синхронизировать агентов + построить standalone HTML
bun run sync:evolution

# Только построить HTML из существующих данных
bun run evolution:build
```

### Открыть в браузере

**Способ 1: Локальный файл (рекомендуется)**

```bash
# Windows
start agent-evolution\index.standalone.html

# macOS
open agent-evolution/index.standalone.html

# Linux
xdg-open agent-evolution/index.standalone.html

# Или через npm
bun run evolution:open
```

**Способ 2: HTTP сервер**

```bash
cd agent-evolution
python -m http.server 3001

# Открыть http://localhost:3001
```

**Способ 3: Docker**

```bash
# Linux/macOS
bash agent-evolution/docker-run.sh restart

# Windows
agent-evolution\docker-run.bat restart

# Открыть http://localhost:3001
```

## 📁 Структура файлов

### Быстрый запуск

```bash
# Linux/macOS
bash agent-evolution/docker-run.sh restart

# Windows
agent-evolution\docker-run.bat restart

# Открыть в браузере
http://localhost:3001
```

### Docker Compose

```bash
# Стандартный запуск
docker-compose -f docker-compose.evolution.yml up -d

# С nginx reverse proxy
docker-compose -f docker-compose.evolution.yml --profile nginx up -d

# Остановка
docker-compose -f docker-compose.evolution.yml down
```

### Управление контейнером

```bash
# Linux/macOS
bash agent-evolution/docker-run.sh build    # Собрать образ
bash agent-evolution/docker-run.sh run      # Запустить контейнер
bash agent-evolution/docker-run.sh stop      # Остановить
bash agent-evolution/docker-run.sh restart   # Пересобрать и запустить
bash agent-evolution/docker-run.sh logs      # Логи
bash agent-evolution/docker-run.sh open      # Открыть в браузере
bash agent-evolution/docker-run.sh sync      # Синхронизировать данные
bash agent-evolution/docker-run.sh status     # Статус
bash agent-evolution/docker-run.sh clean      # Удалить всё
bash agent-evolution/docker-run.sh dev        # Dev режим с hot reload

# Windows
agent-evolution\docker-run.bat build
agent-evolution\docker-run.bat run
agent-evolution\docker-run.bat stop
agent-evolution\docker-run.bat restart
agent-evolution\docker-run.bat logs
agent-evolution\docker-run.bat open
agent-evolution\docker-run.bat sync
agent-evolution\docker-run.bat status
agent-evolution\docker-run.bat clean
agent-evolution\docker-run.bat dev
```

### NPM Scripts

```bash
bun run evolution:build   # Собрать Docker образ
bun run evolution:run     # Запустить контейнер
bun run evolution:stop    # Остановить
bun run evolution:dev      # Docker Compose
bun run evolution:logs     # Логи
```

## Структура

```
agent-evolution/
├── data/
│   ├── agent-versions.json      # Текущее состояние + история
│   └── agent-versions.schema.json # JSON Schema
├── scripts/
│   └── sync-agent-history.ts    # Скрипт синхронизации
├── index.html                   # Дашборд UI
└── README.md                    # Этот файл
```

## Быстрый старт

```bash
# Синхронизировать данные агентов
bun run sync:evolution

# Запустить дашборд
bun run evolution:dashboard

# Открыть в браузере
bun run evolution:open
# или http://localhost:3001
```

## Возможности дашборда

### 1. Overview — Обзор

- **Статистика**: общее количество агентов, с историей, рекомендации
- **Recent Changes**: последние изменения моделей и промптов
- **Pending Recommendations**: критические рекомендации по обновлению

### 2. All Agents — Все агенты

- Поиск и фильтрация по категориям
- Карточки агентов с:
  - Текущей моделью
  - Fit Score
  - Количеством capability
  - Историей изменений

### 3. Timeline — История

- Полная хронология изменений
- Типы событий: model_change, prompt_change, agent_created
- Фильтрация по дате

### 4. Recommendations — Рекомендации

- Агенты с pending recommendations
- Приоритеты: critical, high, medium, low
- Экспорт в JSON

### 5. Model Matrix — Матрица моделей

- Таблица Agent × Model
- Fit Score для каждой пары
- Визуализация provider distribution

## Источники данных

### 1. Agent Files (`.kilo/agents/*.md`)

```yaml
---
model: ollama-cloud/qwen3-coder:480b
description: Primary code writer
mode: subagent
color: "#DC2626"
---
```

### 2. Capability Index (`.kilo/capability-index.yaml`)

```yaml
agents:
  lead-developer:
    model: ollama-cloud/qwen3-coder:480b
    capabilities: [code_writing, refactoring]
```

### 3. Kilo Config (`.kilo/kilo.jsonc`)

```json
{
  "agent": {
    "lead-developer": {
      "model": "ollama-cloud/qwen3-coder:480b"
    }
  }
}
```

### 4. Git History

```bash
git log --all --oneline -- ".kilo/agents/"
```

### 5. Gitea Issue Comments

```markdown
## ✅ lead-developer completed

**Score**: 8/10
**Duration**: 1.2h
**Files**: src/auth.ts, src/user.ts
```

## JSON Schema

Формат `agent-versions.json`:

```json
{
  "version": "1.0.0",
  "lastUpdated": "2026-04-05T17:27:00Z",
  "agents": {
    "lead-developer": {
      "current": {
        "model": "ollama-cloud/qwen3-coder:480b",
        "provider": "Ollama",
        "category": "Core Dev",
        "fit_score": 92
      },
      "history": [
        {
          "date": "2026-04-05T05:21:00Z",
          "commit": "caf77f53c8",
          "type": "model_change",
          "from": null,
          "to": "ollama-cloud/qwen3-coder:480b",
          "reason": "Initial configuration"
        }
      ],
      "performance_log": [
        {
          "date": "2026-04-05T10:30:00Z",
          "issue": 42,
          "score": 8,
          "duration_ms": 120000,
          "success": true
        }
      ]
    }
  }
}
```

## Интеграция

### В Pipeline

Добавьте в `.kilo/commands/pipeline.md`:

```yaml
post_steps:
  - name: sync_evolution
    run: bun run sync:evolution
```

### В Gitea Webhooks

```typescript
// Добавить webhook в Gitea
{
  "url": "http://localhost:3000/api/evolution/webhook",
  "events": ["issue_comment", "issues"]
}
```

### Чтение из кода

```typescript
import { agentEvolution } from './agent-evolution/scripts/sync-agent-history';

// Получить все агенты
const agents = await agentEvolution.getAllAgents();

// Получить историю конкретного агента
const history = await agentEvolution.getAgentHistory('lead-developer');

// Записать изменение модели
await agentEvolution.recordChange({
  agent: 'security-auditor',
  type: 'model_change',
  from: 'gpt-oss:120b',
  to: 'nemotron-3-super',
  reason: 'Better reasoning for security analysis',
  source: 'manual'
});
```

## Рекомендации

### Приоритеты

| Priority | Criteria | Action |
|----------|----------|--------|
| Critical | Fit score < 70 | Немедленное обновление |
| High | Модель недоступна | Переключение на fallback |
| Medium | Доступна лучшая модель | Рассмотреть обновление |
| Low | Возможна оптимизация | Опционально |

### Примеры рекомендаций

```json
{
  "agent": "requirement-refiner",
  "recommendations": [{
    "target": "ollama-cloud/nemotron-3-super",
    "reason": "+22% quality, 1M context for specifications",
    "priority": "critical"
  }]
}
```

## Мониторинг

### Метрики агента

- **Average Score**: Средний балл за последние 10 выполнений
- **Success Rate**: Процент успешных выполнений
- **Average Duration**: Среднее время выполнения
- **Files per Task**: Среднее количество файлов на задачу

### Метрики системы

- **Total Agents**: Количество активных агентов
- **Agents with History**: Агентов с историей изменений
- **Pending Recommendations**: Количество рекомендаций
- **Provider Distribution**: Распределение по провайдерам

## Обслуживание

### Очистка истории

```bash
# Удалить дубликаты
bun run agent-evolution/scripts/cleanup.ts --dedupe

# Слить связанные изменения
bun run agent-evolution/scripts/cleanup.ts --merge
```

### Экспорт данных

```bash
# Экспортировать в CSV
bun run agent-evolution/scripts/export.ts --format csv

# Экспортировать в Markdown
bun run agent-evolution/scripts/export.ts --format md
```

### Резервное копирование

```bash
# Создать бэкап
cp agent-evolution/data/agent-versions.json agent-evolution/data/backup/agent-versions-$(date +%Y%m%d).json

# Восстановить из бэкапа
cp agent-evolution/data/backup/agent-versions-20260405.json agent-evolution/data/agent-versions.json
```

## Будущие улучшения

1. **API Endpoints**:
   - `GET /api/evolution/agents` — список агентов
   - `GET /api/evolution/agents/:name/history` — история агента
   - `POST /api/evolution/sync` — запустить синхронизацию

2. **Real-time Updates**:
   - WebSocket для обновления дашборда
   - Автоматическое обновление при изменениях

3. **Analytics**:
   - Графики производительности во времени
   - Сравнение моделей
   - Прогнозирование производительности

4. **Integration**:
   - Slack/Telegram уведомления
   - Автоматическое применение рекомендаций
   - A/B testing моделей