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

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

{
  "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": {...}
}

Модель

{
  "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
}

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

{
  "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!)..."
}

Очки агента

{
  "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

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 Действия:

# Предпросмотр
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:

# Правильно
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. Исследование моделей

$ /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

$ 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

$ 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. Применение

$ 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. Проверка дашборда

$ 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. Тест пайплайна

$ /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 — маршрутизация и назначения