Verzió: 2.4.0 | Utolsó frissítés: 2026-03-25

AI multi-agent rendszer szoftverfejlesztés automatizálására lokális LLM-ekkel (Ollama), MCP protokollal és hibrid Node.js/Python architektúrával.

Ha AI ügynökként dolgozol (Claude, Gemini, Cursor, Copilot, stb.), ez a szekció KÖTELEZŐ!

# 🔴 KÖTELEZŐ minden munkamenet elején!
scripts\sync.bat              # Windows CMD
# VAGY
.\scripts\sync.ps1            # PowerShell
# VAGY
bash scripts/sync.sh          # Git Bash / WSL

# Opciók:
scripts\sync.bat --build      # Sync + build check
scripts\sync.bat --build --test  # Sync + build + test (teljes ellenőrzés)

Mit csinál a sync script:

• ✅ Fetch + Pull GitHub változásokat (Jules work!)
• ✅ Auto-stash uncommitted changes
• ✅ Jules PR-ek listázása
• ✅ Conflict detection
• ✅ Build/Test check (opcionális)

Részletek: scripts/SYNC_README.md

Monitoring docs: docs/MONITORING_PROMETHEUS.md

Elv: Ne olvass be mindent vakon — fázisonként haladj, és csak azt olvasd, amire szükséged van.

🟢 FÁZIS 1 — GYORS KONTEXTUS (MINDIG, ~5 perc)

1. .ai/BOOTSTRAP.md              # Projekt összefoglaló (LEGELŐSZÖR!)
2. conductor/tracks.md            # Aktív fejlesztések (mit csinálunk MOST)
3. .ai/FOSZAL.md                  # Mi történt legutóbb? (egyesített napló)
4. .ai/<te_neved>.md              # Te mit csináltál legutóbb (claude/gemini/copilot/cursor)

Ez a 4 fájl elegendő a kontextushoz. Ha van folyamatban lévő feladatod, innen kiderül.

🟡 FÁZIS 2 — FELADAT-SPECIFIKUS (csak ami releváns)

🔴 FÁZIS 3 — REFERENCIA (szükség szerint, bármikor)

A README.md a master dokumentum (~1100 sor). NE olvasd be egészben induláskor — használd szekciónként:

• "Build, Test, Lint" — parancsok
• "Kód Konvenciók" — szabályok, minták
• "EPP v2" — fejlesztési protokoll
• "API Végpontok" — REST endpoint lista
• "Hibaelhárítás" — gyakori hibák és megoldások
• "Environment Variables" — .env beállítások

• Agent registry entries: 81
• Route modulok a src/server/routes/ alatt: 91
• Aktív route mountok a központi routerben: 106
• MCP tool fájlok a src/tools/ alatt: 52
• Detektált MCP tool definíciók / regisztrációk: 4
• CLI parancs deklarációk: 276
• Dashboard navigációs panelek: 106

Ezt a blokkot a npm run sync:doc-stats generálja.

# STEP 1: Build check
npm run build                 # TypeScript fordítás (MUSZÁJ OK!)

# STEP 2: Test check (válaszd a megfelelőt)
npm run test:fast             # ⚡ Gyors tesztek (~1-2 perc) — napi munka, commit/push előtt
npm test                      # 🔒 Teljes suite (~10 perc) — napi scheduled run / manuális release-check

# STEP 3: Phoenix Protocol Állapot Ellenőrzés
# Ellenőrizd a legfrissebb Phoenix logokat:
tail -n 50 logs/phoenix.log   # Windows: type logs\phoenix.log | more

⚠️ 0-HIBA STRATÉGIA:

• Ha BUILD FAIL → NE kezdj fejlesztésbe! Javítsd először!
• Ha TESZT FAIL → Dokumentáld TEST_RESULTS.md-ben, majd javítsd!
• Ha Phoenix hibát ír → Olvasd el logs/phoenix.log-ot és reagálj rá!

Teszt cadence szabály (2026-04-01):

• helyi pre-push csak a npm run test:fast profilt futtatja,
• a teljes Node.js tesztkör napi egyszer, külön GitHub Actions workflow-ban fut,
• manuálisan továbbra is ajánlott teljes suite-ot futtatni nagyobb merge / release / track lezárás előtt.

🔴 KRITIKUS: A Phoenix Protocol öngyógyító, de TE vagy felelős a logok ellenőrzéséért!

# 1. Frissítsd a saját naplódat
# Szerkeszd: .ai/<te_neved>.md (formátum alább)

# 2. Szinkronizáld a FŐSZÁLAT
python scripts/sync_foszal.py

# 3. Commit (ha működő állapot)
git add -A
git commit -m "Leírás"

.ai/
├── FOSZAL.md           # 🔴 EGYESÍTETT NAPLÓ (auto-generált, olvasd KÖTELEZŐEN!)
├── claude.md           # Claude Code napló (TE frissíted!)
├── gemini.md           # Gemini CLI napló
├── cursor.md           # Cursor AI napló
└── copilot.md          # GitHub Copilot napló

• Mit tartalmaz: Összes ügynök munkája időrendben
• Generálás: python scripts/sync_foszal.py (automatikus)
• MIÉRT FONTOS: Tudod mi történt mióta utoljára dolgoztál

MINDEN munkamenet végén add hozzá:

### YYYY-MM-DD HH:MM - [Rövid cím]

**Feladat:** Mit csináltál (1-2 mondat)
**Érintett fájlok:** fájl1.ts, fájl2.py, fájl3.md
**Státusz:** ✅ Befejezve / ⏳ Folyamatban / ❌ Sikertelen
**Megjegyzés:** Fontos info a következő ügynöknek (félbehagyott feladat, blocker, stb.)

Példa:

### 2026-02-06 14:30 - Dashboard Theme Fix

**Feladat:** Sötét téma beállítások javítása, theme-provider.tsx runtime error fix
**Érintett fájlok:** src/dashboard/components/theme-provider.tsx, src/dashboard/components/ui/theme-provider.tsx
**Státusz:** ✅ Befejezve
**Megjegyzés:** Dashboard most működik, tesztek PASS (58/58)

src/index.ts két párhuzamos kommunikációs csatornát indít:

1. MCP stdio (StdioServerTransport) - Claude Desktop / MCP kliens
2. Express webszerver (:3000) - REST API + Socket.IO + Dashboard

OrchestratorAgent / EnterpriseOrchestratorAgent (Koordinátorok)
├── Core: DeveloperAgent, EvaluatorAgent, ResearcherAgent, TaskDecomposerAgent
├── Automation: RobotkezV2Agent (Playwright/LLM), VoiceAgent (Whisper)
├── Engineering: SpecWriterAgent, GenesisOrchestrator, UXDesignerAgent, LintFixerAgent
├── Enterprise Suite (~20 ügynök):
│   ├── Finance: FinanceGuardian, FinancialGuardAgent, ProcurementAgent
│   ├── Sales/Marketing: SalesAgent, CopywriterAgent, MarketingDirectorAgent
│   ├── HR: HeadHunterAgent, ConflictMediatorAgent
│   ├── Logistics: LogisticsDispatcherAgent
│   └── Admin: EmailTriageAgent, GrantWatcherAgent, KnowledgeBaseBuilderAgent
├── TOML-alapú DynamicAgent: myai/agents/*.toml
├── Management: ProjectConductorAgent (tracks.md szinkron)
└── Swarm: SwarmManager + SwarmColony (párhuzamos kolónia-alapú feladatkiosztás)

1. Harvest (browser_worker.py)    → Webes adatgyűjtés
2. Refine (refiner_logic.py)      → Adat tisztítás
3. Index (LanceDB)                → Vektoros indexelés
4. Learn (RAG Query)              → Releváns dokumentumok keresése
5. Execute (OrchestratorAgent)    → Feladat végrehajtás
   └─► Feedback loop: újra Harvest-be

Hiba detektálva → Checkpointing (SQLite task queue)
                → Chaos Awareness (429/504 adaptív várakozás) [ÚJ]
                → Auto-Reset (max 3 kísérlet)
                → Git Recovery (sync_foszal.py + commit)

A BAS mostantól beépített védelmet tartalmaz az Indirekt Prompt Injektálás (IPI) ellen:

• Strukturális izoláció: A külső forrásból (web, fájlrendszer) érkező adatokat XML elválasztók (<external_data>) közé zárja.
• Mintafelismerés: Proaktívan szűri a gyanús utasításokat (pl. "ignore previous instructions").
• Edge Protection: A védelem a Cloudflare Worker szintjén is aktív.

A hagyományos hierarchikus delegálás mellett elérhető a Raj Intelligencia üzemmód:

• Unified Group Chat: Több ügynök dolgozik egyetlen megosztott kontextusban.
• Direct Agent Interakció: Az ügynökök "@mention" segítségével tudnak egymástól segítséget kérni.
• Vizualizáció: Az AgentGraph a Dashboard-on valós időben mutatja a raj-kapcsolatokat.

Model Router (src/core/modelRouter.ts) — Brain vs Muscle routing:

• Brain (Cloud): Gemini (1M ctx), GitHub Models GPT-4o → complexity: 'high'
• Muscle (Local): Ollama → complexity: 'low' vagy budget=0

Bifrost Gateway (src/core/bifrost_gateway.ts) — Multi-LLM Gateway:

• 5 provider: Ollama, Gemini, GitHub Models, Anthropic, Cloudflare Workers AI
• Auto-fallback: ha egy provider nem elérhető, automatikusan átvált
• setMode('edge-only'|'local-preferred'|'cloud-preferred')
• userId alapú preferenciák támogatása

PROPOSED → ACTIVE → TESTING → COMPLETED → ARCHIVED

Minden nagyobb fejlesztés = Track a conductor/tracks/ mappában. Jelenleg: 7 aktív track, 5 proposed, 114 archivált. (2026-03-25 rendszerezés)

mcp-brunella-core/
├── .ai/                      # 🔴 AI ügynök koordináció (OLVASD!)
│   ├── FOSZAL.md            # Egyesített napló (KÖTELEZŐ olvasni!)
│   └── <ügynök>.md          # Saját naplód (KÖTELEZŐ frissíteni!)
│
├── src/                      # 💻 TypeScript forráskód
│   ├── agents/              # AI ügynökök (NE TÖRÖLD!)
│   │   ├── types.ts         # IAgent interfész
│   │   ├── BaseAgent.ts     # Absztrakt ősosztály
│   │   ├── registry.json    # Ügynök regisztráció
│   │   └── *.ts             # Ügynök implementációk
│   ├── tools/               # MCP eszközök
│   ├── server/              # Express + Socket.IO
│   │   ├── web.ts           # Web szerver
│   │   └── registry.ts      # MCP tool regisztráció
│   ├── dashboard/           # React UI (Vite, Tailwind v4)
│   ├── core/
│   │   ├── llm_client.ts          # Ollama/Gemini LLM hívások
│   │   ├── modelRouter.ts         # Brain vs Muscle routing
│   │   ├── bifrost_gateway.ts     # Multi-LLM Gateway (5 provider, auto-fallback)
│   │   ├── observabilityLogger.ts # LLM hívás naplózás (SQLite)
│   │   ├── toolRunCapture.ts      # Golden Dataset tool instrumentáció
│   │   └── checkpoint.ts          # Phoenix Protocol
│   ├── utils/
│   │   ├── logger.ts        # Naplózás (használd console.log helyett!)
│   │   └── pythonShell.ts   # Python alrendszer kommunikáció
│   ├── cli.ts               # CLI belépési pont
│   └── index.ts             # Fő belépési pont (MCP server)
│
├── myai/                     # 🐍 Python alrendszer
│   ├── server.py            # FastAPI szerver (:8000)
│   ├── browser_worker.py    # Playwright automatizálás (Robotkéz)
│   └── refiner_logic.py     # Adat tisztítás + LanceDB
│
├── conductor/                # 📋 Projekt menedzsment
│   ├── tracks.md            # Aktív track-ek (opcionális olvasás)
│   └── workflow.md          # Részletes workflow (opcionális)
│
├── .env                      # 🔐 TITKOS - NE commitold!
├── package.json             # 📦 NE TÖRÖLD!
└── README.md                # 📖 Ez a fájl (MASTER DOCUMENT)

Ha "takarítani" akarsz vagy "tisztítani" a projektet - KÉRDEZZ ELŐSZÖR!

# Kanonikus kezi stable inditas (ajanlott - Windows operator mod)
inditas.bat

# Kozvetlen stable console fallback (ha nincs service telepitve)
Inditsd_Brunellat_Stabil.bat

# Stable runtime kezzel, kulon terminálokban
npm run build:stable
npm run start:python:stable   # Python (:8000)
npm run start:stable          # Brunella Core + Dashboard (:3000)

# Development only
npm install && npm run build
npm run dev          # Backend (:3000)
npm run dev:ui       # Dashboard (:5173)

# Python alrendszer (FastAPI :8000)
cd myai
uv sync              # Függőségek telepítése
uvicorn server:app --reload --port 8000

# Host-native supervision
npm run services:preflight
powershell -ExecutionPolicy Bypass -File scripts\supervisors\windows\install-windows-services.ps1
bash scripts/supervisors/linux/install-systemd-services.sh

# Service operations
npm run services:status:windows
npm run services:status:linux
npm run services:uninstall:windows
npm run services:uninstall:linux

Stable runtime contract (minden stable indítási út ugyanazt a budgetet használja):

BRUNELLA_NODE_MAX_OLD_SPACE_SIZE=1536         # Node heap budget (MB)
BRUNELLA_RUNTIME_MEMORY_LIMIT_MB=2048         # Teljes runtime envelope (MB)
BRUNELLA_RUNTIME_RESTART_THRESHOLD_MB=1792    # Supervisor restart threshold (MB)

• A scripts/start-stable.mjs ezt a contractet validálja boot előtt.
• Ha a launcher más heap budgettel indul, a stable startup fail-fast leáll.
• Docker / PM2 / Windows service / systemd ugyanarra a contractre van igazítva.
• A npm run services:preflight service install előtt ellenőrzi a stable buildet, a Python runtime-ot és a logs/data írhatóságát.

# Build
npm run build        # TypeScript → build/ (MUSZÁJ sikerülnie!)

# Tesztek
npm test             # Build + Vitest run (MUSZÁJ PASS!)
npm run test:watch   # Watch mód (fejlesztés közben)
npx vitest run test/foo.test.ts  # Egy specifikus teszt

# Gyors health check
npm run smoke        # Ollama, Express, FastAPI ellenőrzés
npm run health       # Teljes health riport, runtime memória telemetriával

brunella chat                 # Interaktív chat (VIP menü)
brunella agents               # Ügynökök listázása
brunella tools                # MCP eszközök listázása
brunella run <tool>           # MCP tool futtatás

# Conductor (projekt menedzsment)
brunella conductor status     # Projekt státusz
brunella conductor sync       # Dokumentáció szinkron
brunella conductor health     # Track-ek health check

# Task Decomposer (komplex feladat bontás)
brunella decompose [task]     # Feladat dekompozíció (preview-only DAG)

# Agent Architect (új ügynök generálás)
brunella architect create [description]  # Új ügynök létrehozása TOML config-ból

# Új integrációk (Phase 2-4)
brunella crawl4ai              # Webcrawling menü (URL crawl, status, konfiguráció)
brunella preferences           # Felhasználói preferenciák (nyelv, provider, stílus)
brunella observability         # LLM Observability (provider stats, latencia, tokens)

/edge on|off         # Cloudflare Edge mód be/ki
/switch ollama       # Váltás Ollama-ra
/switch gemini       # Váltás Gemini-re
/switch claude       # Váltás Claude-ra
/model <név>         # Ollama modell váltás
/save                # Utolsó kód mentése
/run                 # Utolsó kód futtatása
/exit                # Kilépés

Ez a protokoll garantálja, hogy a rendszer mérnöki precizitással működjön, és soha ne "felejtsen el" feladatokat.

"Nem lépünk tovább hibás rendszerrel."

Ha bármilyen munkafolyamat során (fejlesztés, tesztelés, robotkéz) hibát észlelsz:

1. AZONNAL ÁLLJ MEG! Ne folytasd a feature fejlesztést.
2. JAVÍTSD KI! A hibát addig kell diagnosztizálni és javítani, amíg el nem tűnik.
3. CSAK AKKOR FOLYTASD, ha a rendszer újra "Zöld" (Build OK, Test OK).

Tilos a "majd később visszatérünk rá" vagy "ez most nem az én dolgom" mentalitás.

Soha ne írj kódot "vázlatos" utasítás alapján. Konvertáld a szöveget mérnöki tervvé:

1. User Input: "Csinálj egy olyat, hogy..."
2. Specifikáció: Hozz létre egy Track-et (conductor/tracks/uj_feature/spec.md).
3. Jóváhagyás: A userrel (vagy Conductorral) validáltasd a tervet.
4. Implementáció: Csak a jóváhagyott spec alapján kódolj.

Minden feladatnak nyoma kell legyen. Ami nincs írásban, az nem létezik.

• Aktív Feladat: conductor/tracks.md (Track)
• Hiba/Javítás: data/fix_queue.json (Self-Healing Queue)
• Ötlet: conductor/backlog.md (ha van) vagy tracks.md (Proposed)

Engineering Precision Protocol v2 - Teljes fejlesztési protokoll frissítése.

📖 Teljes dokumentáció: conductor/epp-v2.md

Mi változott v1 → v2:

• ✅ 6. szabály hozzáadva: Minden új funkció = Dashboard komponens + CLI parancs (magyar, menüvezérelt)
• ✅ Track template frissítve (Dashboard + CLI checklist kötelező)
• ✅ COMPLETED státusz csak ha MINDKETTŐ működik

Minden új funkció implementálása során:

1. Dashboard Komponens (src/dashboard/components/)

   • React komponens Radix UI + Tailwind
   • Működő backend integráció (API endpoint)
   • Real-time frissítés ahol releváns (WebSocket)
   • Responsive design + error handling

2. CLI Parancs (src/cli/commands/)

   • MAGYAR nyelven, menüvezérelt! (NINCS begépelés!)
   • inquirer.js menü (nyíl + enter navigáció)
   • Színes output (chalk, boxen, ora)
   • Interaktív kiválasztás

3. Track Checklist kötelező pontok minden track-ben:

   ## 🎨 Dashboard Integráció
   
   - [ ] React komponens létrehozva: src/dashboard/components/<Feature>.tsx
   - [ ] Radix UI + Tailwind használat
   - [ ] Backend API integráció
   - [ ] Real-time updates (ha releváns)
   
   ## 🖥️ CLI Integráció
   
   - [ ] Magyar menü: src/cli/commands/<feature>-hu.ts
   - [ ] Inquirer.js menü (nyíl + enter)
   - [ ] Színes output (chalk, boxen)
   - [ ] CLI regisztráció (src/cli.ts)

Ha valamelyik elmarad → Track NEM lehet COMPLETED!

További részletek, példák, anti-patterns: conductor/epp-v2.md

npm run test:fast             # Gyors unit tesztek (~1-2 perc) — commit előtt
npm test                      # Build + összes teszt (~10 perc) — track lezáráskor / push előtt
npm run test:nightly          # Azonos mint npm test — éjszakai / CI futtatásra
npm run test:watch            # Watch mód (fejlesztés közben)
npx vitest run test/foo.test.ts  # Egy teszt fájl
npm run test:coverage         # Lefedettségi jelentés

# Python tesztek
cd myai
pytest tests/

Szabály: E2E és smoke tesztek (test/cli-e2e*, test/phase*, test/swarm_smoke*) NEM futnak minden commitnál. Ezeket track lezárásakor vagy push előtt kell futtatni (npm test). A pre-push hook automatikusan lefuttatja a teljes suite-ot.

• npm run build - TypeScript fordítás OK
• npm run test:fast - Gyors tesztek PASS
• git status - Nincs váratlan változás

• npm run build - Még mindig OK
• npm run test:fast - Még mindig PASS
• Track lezárásnál: npm test + npm run smoke — KÖTELEZŐ
• .ai/<te_neved>.md - Napló frissítve
• python scripts/sync_foszal.py - FOSZAL szinkronizálva

15 párhuzamos teszt suite 4 óránként + napi összesítő

# CLI használat
brunella jules tests           # Interaktív menü: futások / trigger

# Dashboard
# Mission Control → Jules Integration → "Async Tests" szekció
# - Latest runs táblázat
# - Success trend chart
# - "Trigger" gomb

Workflow-k:

• .github/workflows/jules-async-tests.yml - 15 suite (unit, integration, e2e, performance, security)
• .github/workflows/jules-test-coordinator.yml - Napi összesítő (8 AM UTC)

Test Suites:

1. unit_fast / unit_slow
2. integration_ollama / integration_gemini / integration_github_models
3. dashboard
4. e2e_full / e2e_critical
5. performance_stress / performance_memory
6. security_scan
7. api_contracts
8. accessibility / browser_compat / regression

Trigger:

• Automatikus: 4 óránként (cron)
• Manuális: brunella jules tests → "Workflow indítása"
• Dashboard: "Trigger" gomb

A projekt "type": "module". Minden import .js kiterjesztéssel:

import { foo } from "./bar.js"; // ✅ HELYES
import { foo } from "./bar"; // ❌ HELYTELEN (build fail!)

Használd a logger.ts függvényeket:

// Agent kódban:
import { logInfo, logError, setAgentStatus } from "../utils/logger.js";
logInfo("AgentName", "message");
setAgentStatus("AgentName", "working", "task desc");

// Szerver kódban:
import { Logger } from "../utils/logger.js";
const logger = new Logger("feature.log");
await logger.info("message");

NE használj console.log() production kódban!

import { IAgent, AgentResponse } from "./types.js";
import { logInfo, logError, setAgentStatus } from "../utils/logger.js";

export class MyAgent implements IAgent {
  name = "MyAgent";
  role = "Cél";
  description = "Mit csinál";
  capabilities = ["skill1", "skill2"];

  async execute(task: string, context?: unknown): Promise<AgentResponse> {
    setAgentStatus(this.name, "working", task.slice(0, 50));
    try {
      // Implementáció
      return { status: "success", data: result };
    } catch (e: unknown) {
      const error = e instanceof Error<