APAW/agent-evolution/docs/bidirectional-data-flow.md

# Двунаправленный поток данных APAW Agent Model Research

Этот документ описывает архитектуру системы, которая автоматизирует исследование моделей AI для агентов APAW и синхронизирует данные между визуальной панелью, конфигурационными файлами и пайплайном эволюции.

## Цель

Изначально все данные исследования моделей были захардкожены в HTML-файле `apaw_agent_model_research_v3.html` (1168 строк JavaScript). Двунаправленный поток делает эту систему:

- **Машиночитаемой** — данные хранятся в JSON для автоматической обработки
- **Записываемой** — изменения в конфигурации агентов обновляют JSON и перегенерируют дашборд
- **Визуализированной** — любое изменение данных автоматически создаёт новый HTML

## Архитектура данных

### Файлы системы

| Файл | Назначение | Формат | Обновляется |
|------|-----------|--------|-------------|
| `data/model-benchmarks.json` | Статические бенчмарки | JSON | `/research models`, вручную |
| `data/model-research-latest.json` | Последнее исследование | JSON | `/evolution Step 0`, `/research models` |
| `data/model-research.schema.json` | Схема валидации | JSON Schema | Вручную |
| `data/model-benchmarks.schema.json` | Схема бенчмарков | JSON Schema | Вручную |
| `scripts/build-research-dashboard.ts` | Генерация HTML | TypeScript/Bun | Вручную |
| `scripts/sync-model-research.ts` | Применение изменений | TypeScript/Bun | Вручную |
| `research-dashboard.template.html` | Шаблон дашборда | HTML+JS+CSS | Вручную |
| `research-dashboard.html` | Готовый дашборд | HTML (standalone) | `build-research-dashboard.ts` |
| `dist/research-dashboard-YYYY_MM_DD.html` | Архив | HTML | `build-research-dashboard.ts` |

## Поток данных

### Направление 1: HTML → JSON (Исследование → Бенчмарки)

Источник: `apaw_agent_model_research_v3.html` (вручную исследованные данные)

```
apaw_agent_model_research_v3.html
       │ hardcoded JS arrays:
       │   cfg[]     — текущие конфиги агентов
       │   ollamaModels[] — характеристики моделей
       │   hmAgents[] — матрица очков
       │   recs[] — рекомендации
       │   impactData[] — дельта изменений
       │   groqModels[] — лимиты Groq
       ↓
agent-evolution/data/model-benchmarks.json
       ├─ models[] — 15 моделей, бенчмарки, IF-оценки
       ├─ agent_model_scores[] — 33 агента × 11 моделей
       ├─ agent_current_config[] — 36 текущих назначений
       ├─ recommendations[] — 11 рекомендуемых замен
       ├─ groq_models[] — 5 моделей Groq с лимитами
       ├─ impact_data[] — before/after
       └─ benchmark_comparison — сравнение с закрытыми моделями
```

**Как обновлять**: один раз данные извлечены из HTML. Дальнейшие обновления:
- Автоматически: `/research models` → `model-research-latest.json` → `model-benchmarks.json`
- Вручную: редактировать `model-benchmarks.json`, обновить `metadata.generated`

### Направление 2: JSON → Конфиг → HTML (Применение → Визуализация)

```
[/research models] OR [/evolution Step 0]
       ↓
model-research-latest.json
       │ validates against:
       ↓ model-research.schema.json
bun run agent-evolution/scripts/sync-model-research.ts
       ├─ обновляет .kilo/capability-index.yaml (model поля)
       ├─ обновляет kilo-meta.json (source of truth)
       ├─ обновляет kilo.jsonc (agent config)
       ├─ обновляет agent-evolution/data/agent-versions.json (история)
       ├─ обновляет .kilo/agents/*.md frontmatter (через sync-agents.js --fix)
       └─ rebuilds dashboard (build-research-dashboard.ts)
       ↓
bun run agent-evolution/scripts/build-research-dashboard.ts
       ├─ читает model-benchmarks.json
       ├─ инжектирует в research-dashboard.template.html
       ├─ записывает research-dashboard.html
       └─ копирует dist/research-dashboard-YYYY_MM_DD.html
       ↓
[/research models] ← цикл продолжается
```

## Структура model-benchmarks.json

### Верхний уровень

```json
{
  "version": "1.0.0",
  "generated": "2026-04-27T17:44:44.000Z",
  "source": "apaw_agent_model_research_v3.html",
  "total_agents": 36,
  "total_models_tracked": 11,
  "providers": ["ollama", "ollama-cloud", "openrouter", "groq"],
  "models": [...],
  "groq_models": [...],
  "agent_model_scores": [...],
  "if_scores": {...},
  "agent_current_config": [...],
  "recommendations": [...],
  "impact_data": [...],
  "benchmark_comparison": {...}
}
```

### Модель

```json
{
  "id": "ollama-cloud/qwen3-coder:480b",
  "name": "Qwen3-Coder 480B",
  "organization": "Qwen",
  "parameters": "480B/35B active",
  "context_window": "256K\u21921M",
  "swe_bench": 66.5,
  "swe_bench_pro": null,
  "terminal_bench": null,
  "live_codebench": null,
  "gpqa": null,
  "hle": null,
  "browse_comp": null,
  "if_score": 88,
  "categories": ["coding", "agent"],
  "tags": ["coding", "agent", "tools"],
  "provider": "ollama",
  "free": false,
  "cost_per_1m_input": "~$0.50",
  "description": "SOTA open-source \u043a\u043e\u0434\u0438\u043d\u0433. \u0421\u0440\u0430\u0432\u043d\u0438\u043c \u0441 Claude Sonnet 4.",
  "availability": null,
  "speed_tps": null
}
```

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

```json
{
  "agent": "planner",
  "action": "update_model",
  "current_model": "nemotron-3-super",
  "current_provider": "Ollama",
  "recommended_model": "deepseek-v4-pro-max",
  "recommended_provider": "Ollama Cloud",
  "impact": "high",
  "score_before": 80,
  "score_after": 88,
  "score_delta": 8,
  "expected_improvement": {
    "quality": "+10%",
    "speed": "~1x",
    "context_window": "1M"
  },
  "rationale": "\u2605 matri\u0446\u044b: V4-Pro=88(\u043b\u0443\u0447\u0448\u0438\u0439!)..."
}
```

### Очки агента

```json
{
  "agent": "lead-developer",
  "current_model_index": 0,
  "reasoning_effort": "M",
  "scores": {
    "ollama-cloud/qwen3-coder:480b": 92,
    "ollama-cloud/minimax-m2.5": 86,
    "ollama-cloud/minimax-m2.7": 82,
    "ollama-cloud/nemotron-3-super": 70,
    "ollama-cloud/glm-5": 68,
    "ollama-cloud/glm-5.1": 75,
    "ollama-cloud/deepseek-v4-pro-max": 88,
    "ollama-cloud/qwen3.5-122b": 66,
    "ollama-cloud/qwen3-coder-next": 80,
    "openrouter/qwen/qwen3.6-plus:free": 88,
    "ollama-cloud/kimi-k2.6:cloud": 90
  }
}
```

## Формула IF-ажастмента

Оценка агента с учётом способности модели следовать инструкциям:

```
IF-adjusted_score = raw_score × (0.7 + 0.3 × IF/100)

Где:
  raw_score — бенчмарк оценка пары агент×модель (0-100)
  IF — instruction following score модели (0-100)

Примеры:
  IF=100 → score × 1.00 (без изменений)
  IF=90  → score × 0.97
  IF=78  → score × 0.93
  IF=50  → score × 0.85
  IF=0   → score × 0.70

Чем ниже IF, тем сильнее штраф — модель плохо следует промпту и роли.
```

## Скрипты системы

### build-research-dashboard.ts

**Вход**: `model-benchmarks.json` + `research-dashboard.template.html`
**Выход**: `research-dashboard.html` + `dist/dashboard-YYYY_MM_DD.html`

```bash
bun run agent-evolution/scripts/build-research-dashboard.ts              # однократная сборка
bun run agent-evolution/scripts/build-research-dashboard.ts --watch       # watch-режим
bun run agent-evolution/scripts/build-research-dashboard.ts --template custom.html
```

Процесс:
1. Читает JSON, валидирует наличие полей
2. Читает шаблон, ищет placeholder `// BENCHMARK_DATA_PLACEHOLDER`
3. Заменяет `const EMBEDDED_DATA = {};` на полный JSON с данными
4. Обновляет `<title>` с датой генерации
5. Пишет `research-dashboard.html` и архивную копию

### sync-model-research.ts

**Вход**: `model-research-latest.json`
**Действия**:

```bash
# Предпросмотр
bun run agent-evolution/scripts/sync-model-research.ts --dry-run

# Применение всех рекомендаций
bun run agent-evolution/scripts/sync-model-research.ts

# Только для одного агента
bun run agent-evolution/scripts/sync-model-research.ts --agent planner
```

Для каждой рекомендации (`action: "update_model"`, `applied: false`):
1. Находит блок агента в `capability-index.yaml`, заменяет `model:`
2. Обновляет `kilo-meta.json` (source of truth)
3. Обновляет `kilo.jsonc` (через regex, требует ручной проверки)
4. Добавляет запись в `agent-versions.json` history
5. Запускает `node scripts/sync-agents.js --fix` → обновляет .md frontmatter
6. Запускает `node scripts/sync-agents.js --check` → проверка консистентности
7. Пересобирает дашборд через `build-research-dashboard.ts`

## Интеграция в пайплайн

### /research models

```
1. Загрузить текущие данные из model-benchmarks.json
2. Если stale (>7 дней) или --force:
   a. Fetch моделей с Ollama Cloud, OpenRouter, Groq
   b. Compute IF scores для каждой модели
   c. Score каждую модель против каждого агента
3. Сгенерировать рекомендации (gap > 5)
4. Записать model-research-latest.json
5. Валидировать против model-research.schema.json
6. Обновить model-benchmarks.json (если данные изменились)
7. Пересобрать дашборд
```

### /evolution (полный цикл)

```
Step 0: Model Research
  ├─ Проверить staleness model-benchmarks.json
  ├─ Если stale → @capability-analyst исследует модели
  ├─ Загрузить heatmap scores
  └─ Определить агентов с mismatch (gap > 5)

Step 1: Judge
  └─ @pipeline-judge → fitness score

Step 2: Decide
  ├─ fitness >= 0.85 → выход
  ├─ fitness >= 0.70 → @prompt-optimizer (minor)
  └─ fitness < 0.70 → @prompt-optimizer (major) + apply model recs

Step 3: Re-test
  └─ Перезапуск с обновлёнными промптами/моделями

Step 4: Log + Dashboard
  ├─ Append fitness-history.jsonl
  ├─ Apply рекомендации sync-model-research.ts
  └─ Пересобрать дашборд build-research-dashboard.ts
```

### /evolution research

```
1. Прочитать текущую конфигурацию
2. Исследовать модели (как /research models)
3. Сгенерировать рекомендации
4. Dry-run preview
5. Применить при подтверждении
6. Пересобрать дашборд
```

## Правила синхронизации

Из `.kilo/rules/evolutionary-sync.md`:

### Обязательный порядок

```
1. Обновить kilo-meta.json (source of truth)
2. Обновить capability-index.yaml
3. Запустить sync-agents.js --fix
4. Ручная проверка kilo.jsonc (sync script не гарантирует)
5. Запустить sync-agents.js --check
6. Проверить agent-versions.json history
7. Пересобрать дашборд
8. Если любая проверка не прошла — НЕ коммитить
```

### Облачный суффикс

При использовании `ollama-cloud/kimi-k2.6` ВСЕГДА с суффиксом `:cloud`:

```yaml
# Правильно
model: "ollama-cloud/kimi-k2.6:cloud"

# Неправильно — отсутствует суффикс
model: "ollama-cloud/kimi-k2.6"
```

## Чеклист применения изменений

```
□ Исследование: /research models завершено
□ Валидация: model-research-latest.json проходит schema check
□ Dry-run: sync-model-research.ts --dry-run показывает ожидаемые изменения
□ Применение: sync-model-research.ts выполнен без ошибок
□ YAML: capability-index.yaml обновлены поля model
□ Meta: kilo-meta.json соответствует
□ kilo.jsonc: модели обновлены (ручная проверка)
□ История: agent-versions.json записи добавлены
□ Sync: sync-agents.js --fix обновил все .md файлы
□ Check: sync-agents.js --check проходит
□ Старые модели: grep не находит предыдущие model IDs
□ Суффикс: kimi-k2.6:cloud (с :cloud)
□ Дашборд: build-research-dashboard.ts сгенерировал свежий HTML
□ Открыть: research-dashboard.html показывает актуальные данные
□ Гит: все изменения add и commit
```

## Устранение неполадок

| Проблема | Диагностика | Решение |
|----------|------------|---------|
| Дашборд пустой | Проверить placeholder в template.html | Пересобрать: `bun run build-research-dashboard.ts` |
| Schema validation fails | Сравнить JSON со схемой | Проверить model-research.schema.json актуальность |
| sync-agents.js check fails | Model mismatch в конфигах | Запустить `--fix`, затем `--check`; ручная проверка kilo.jsonc |
| Heatmap пустой | agent_model_scores отсутствует | Обновить бенчмарки через `/research models` |
| Рекомендации не отображаются | Empty recs array | Запустить research для генерации новых рекомендаций |
| Старые данные | metadata.generated > 7 дней | Обновить бенчмарки |
| sync-model-research.ts падает | Файл не найден | Проверить пути, запустить из корня проекта |

## Пример полного цикла

### 1. Исследование моделей

```bash
$ /research models

## Research: model optimization

### Models Analyzed
- Ollama Cloud: 20 models
- OpenRouter Free: 3 models
- Groq Free: 5 models

### Key Findings
- DeepSeek V4-Pro Max доступен (SWE-V 80.6, IF:88)
- Kimi K2.6 IF=91 (лучший для orchestration)
- Nemotron 3 Super IF=78 — слаб для prompt-heavy ролей
- Qwen 3.6 Plus FREE остаётся лучшим IF/cost (91, $0)

### Recommendations Generated
- 11 model swap recommendations
- 4 high, 3 medium, 4 low
- Средний expected improvement: +12 points

### Files Updated
- agent-evolution/data/model-research-latest.json
- agent-evolution/data/model-benchmarks.json (refreshed)
- agent-evolution/dist/research-dashboard-2026_04_27.html (archive)
```

### 2. Валидация schema

```bash
$ node -e "
const Ajv = require('ajv');
const ajv = new Ajv();
const schema = JSON.parse(require('fs').readFileSync('agent-evolution/data/model-research.schema.json','utf8'));
const data = JSON.parse(require('fs').readFileSync('agent-evolution/data/model-research-latest.json','utf8'));
const valid = ajv.validate(schema, data);
console.log(valid ? 'VALID' : 'INVALID');
if (!valid) console.log(JSON.stringify(ajv.errors, null, 2));
"
VALID
```

### 3. Dry-run

```bash
$ bun run agent-evolution/scripts/sync-model-research.ts --dry-run

=== SYNC PREVIEW (dry-run) ===
3 agents would be updated:

planner
  FROM: nemotron-3-super (Ollama)
  TO:   deepseek-v4-pro-max (Ollama Cloud)
  DELTA: +8 (80 → 88)
  IMPACT: high

go-developer
  FROM: qwen3-coder:480b (Ollama)
  TO:   deepseek-v4-pro-max (Ollama Cloud)
  DELTA: +3 (85 → 88)
  IMPACT: medium

[built-in] debug
  FROM: glm-5.1 (Ollama)
  TO:   kimi-k2.6:cloud (Ollama Cloud)
  DELTA: +2 (88 → 90)
  IMPACT: high

Files to modify: capability-index.yaml, kilo-meta.json, kilo.jsonc, agent-versions.json
```

### 4. Применение

```bash
$ bun run agent-evolution/scripts/sync-model-research.ts

✅ capability-index.yaml updated (3 agents)
✅ kilo-meta.json updated  
✅ kilo.jsonc updated
✅ agent-versions.json history updated (3 entries)
✅ sync-agents.js --fix completed
✅ sync-agents.js --check passed
✅ Dashboard rebuilt: research-dashboard.html (106KB)
```

### 5. Проверка дашборда

```bash
$ start agent-evolution/research-dashboard.html

# В браузере:
# - Overview: 3 agents updated, 11 recommendations total
# - Heatmap: V4-Pro Max column green for planner, go-developer
# - Recommendations: 3 marked as applied with checkmarks
# - Impact: +8 for planner shown in chart
```

### 6. Тест пайплайна

```bash
$ /evolve --issue 42

## Pipeline Judgment: Issue #42

**Fitness: 0.88/1.00** [PASS → improved from 0.82]

| Metric | Value | Weight | Contribution |
|--------|-------|--------|-------------|
| Tests  | 96% (46/48) | 50% | 0.480 |
| Gates  | 80% (4/5) | 25% | 0.200 |
| Cost   | 38.4K tok / 245s | 25% | 0.198 |

**Bottleneck:** none (all agents optimal)
**Verdict:** PASS — fitness improved!

✅ Logged to .kilo/logs/fitness-history.jsonl
✅ Auto-rebuilt: agent-evolution/research-dashboard.html
```

## Периодичность обновления

| Файл | Период | Триггер |
|------|--------|---------|
| model-benchmarks.json | Еженедельно (>7 дней = stale) | `/evolution Step 0` или `/research models` |
| model-research-latest.json | Каждый research cycle | `/research models`, `/evolution research` |
| research-dashboard.html | После каждого изменения | `sync-model-research.ts` или `build-research-dashboard.ts` |
| dist/*.html | Архив | Каждая генерация |
| agent-versions.json | При каждом изменении модели | `sync-model-research.ts` |

## Связанные документы

- `.kilo/commands/evolution.md` — команда /evolution
- `.kilo/commands/research.md` — команда /research
- `.kilo/shared/self-evolution.md` — протокол эволюции
- `.kilo/rules/evolutionary-sync.md` — правила синхронизации
- `.kilo/rules/agent-frontmatter-validation.md` — валидация YAML frontmatter
- `agent-evolution/README.md` — обзор системы эволюции
- `kilo-meta.json` — source of truth для моделей
- `.kilo/capability-index.yaml` — маршрутизация и назначения