Ghid operator pentru Visualize

Ce face

visualize este capabilitatea care creează vizualizări și mici instrumente interactive direct în conversație, atunci când forma vizuală chiar face explicația mai clară. Este potrivită pentru simulatoare, laboratoare interactive, hărți, ploturi, grafice, comparații, scenarii cu inputuri ajustabile și explorări vizuale.

Nu este un mod decorativ. Dacă textul explică suficient, rămâne text. Dacă o structură statică poate fi explicată complet prin noduri și muchii etichetate, forma potrivită este Mermaid. Dacă ai nevoie de mișcare, spațiu, controale, parametri ajustabili sau interacțiune, forma potrivită este HTML inline.

Pe scurt: visualize nu înfrumusețează răspunsul. Îl face testabil cu ochii.

Când îmi folosește

Îți folosește când întrebarea are o componentă vizuală, spațială, numerică sau exploratorie. De exemplu:

• vrei să vezi cum curge un proces între etape;
• compari opțiuni, scenarii, valori sau distribuții;
• ai date numerice și vrei un grafic;
• vrei o hartă bazată pe geometrie reală, nu pe contururi inventate;
• vrei un simulator cu inputuri modificabile;
• vrei să înțelegi un mecanism printr-un lab interactiv;
• vrei să observi bottleneck-uri, timpi, relații sau alocări.

Pentru explicații simple, cere text. Pentru scheme statice, cere Mermaid. Pentru explorare, simulare, hartă sau control ajustabil, cere o vizualizare interactivă.

All guides include restul ghidurilor din aceeași familie.

Cum îl invoc / declanșez

Invocarea exactă depinde de runtime și de faptul că skillul visualize este instalat și disponibil. Sursa definește capabilitatea ca skill numit visualize, cu scopul de a crea vizualizări și instrumente interactive în conversație.

În practică, îl declanșezi prin cereri naturale precum:

• „arată-mi cum funcționează asta”;
• „fă-mi un grafic din datele astea”;
• „compară vizual opțiunile”;
• „fă un simulator cu input ajustabil”;
• „vreau o hartă cu date reale”;
• „fă un lab interactiv”;
• „desenează fluxul dintre pașii ăștia”.

Nu trebuie să inventezi o comandă specială dacă runtime-ul routează automat cererea. Dacă instalarea cere invocare explicită, folosește numele skillului doar când mediul respectiv îl acceptă. Ghidul acesta nu garantează disponibilitatea în toate interfețele.

Exemplu practic

Vrei să compari trei strategii de lucru: una secvențială, una cu două lane-uri și una cu fan-out complet. O cerere bună ar fi:

„Arată-mi vizual cum diferă cele trei strategii, cu o axă de timp și marcaje pentru așteptare și bottleneck.”

Un răspuns bun ar începe cu vizualul: lane-uri aliniate pe aceeași axă de timp, faze codate clar, totaluri și așteptări annotate direct pe axă sau pe mark-uri. Dacă ai cerut doar comparația, nu ar adăuga filtre, căutare, butoane de reset, carduri KPI sau panouri secundare. Controalele apar doar când le-ai cerut sau când sunt necesare pentru interacțiune.

Output / unde aterizează

Pentru Mermaid, outputul este un bloc Markdown fenced Mermaid în conversație. Nu este nevoie de fișier separat de vizualizare.

Pentru HTML inline, runtime-ul scrie un fragment HTML într-o zonă de lucru scoped pe conversație, folosind un titlu scurt, ASCII, lowercase și cu cratime. Răspunsul include doar directiva inline unde trebuie să apară vizualul:

::codex-inline-vis{file="<title>.html"}

Orice explicație necesară stă în afara fragmentului și rămâne concisă. Fragmentul conține doar vizualul: etichete, legendă, valori, controale necesare și text alternativ accesibil unde trebuie. Nu trebuie anunțat ca atașament, site, link, download, fișier local sau artefact tehnic.

Limite / gotchas

Vizualul trebuie să fie mic, concentrat și util. HTML-ul inline trebuie să rămână sub 2 MB. Nu are voie să folosească fetch, XHR, WebSocket sau alte API calls. Resursele statice externe sunt permise doar din origini CDN aprobate de runtime; alte origini pot eșua tăcut.

Nu se pun paragrafe explicative, formule lungi, instrucțiuni sau narațiune în fragment. Nu se anunță HTML-ul, SVG-ul, scripturile, fișierele locale sau implementarea. Utilizatorul trebuie să vadă decizia mai clar, nu mecanismul intern.

Pentru hărți, contururile geografice nu se ghicesc și nu se desenează manual. Se folosesc GeoJSON/TopoJSON publicate și coordonate reale proiectate corect. Pentru țări, state, comitate, coduri poștale sau orașe, geometria trebuie să vină din surse publicate sau oficiale, nu din presupuneri.

Interacțiunile trebuie să fie accesibile: controale native, etichete clare, focus păstrat, contrast lizibil, layout care funcționează și pe ecrane înguste. Nu cere visualize doar pentru că ar arăta frumos. Cere-l când scade confuzia. Restul e mobilier.