Kérdőív- és QML-eszközök – MCP-eszközreferencia
A kérdőíveszközök a QML életciklusát kezelik: új verziók mentését, a Z3 formális elemzésével végzett validációt, egy verzió közzétételét egy kampányhoz, a projektek közötti áthelyezést és a közzététel visszavonását. Az életciklusnak megkötései vannak – például a közzététel nem vonható vissza, amíg aktív kampányok hivatkoznak a kérdőívre.
Hogyan tárolja a rendszer a QML-t
Szekció neve “Hogyan tárolja a rendszer a QML-t”Egy kérdőív QML-kódja az Askalot adatbázisában csak bővíthető verzióláncként él. Minden mentés új verziót ad hozzá, és a kérdőív aktuális verzióját (head) erre állítja; a korábbi verziókat a rendszer soha nem írja felül és nem törli.
A qml_name a kérdőív állandó címe, projects/{project_id}/questionnaires/{questionnaire_id}.qml alakban. Útvonalnak tűnik, és úgy is olvasható, de egy kérdőívet azonosít – nincs böngészhető könyvtár és nincs előkészítendő fájl. A list_qml_files a létező címeket adja vissza.
Ebből három szabály következik, és ezek magyarázzák az alábbi viselkedés nagy részét:
- A mentés megnevezi azt a verziót, amelyből írták. A mentést egy pillanattal korábban kiolvasott tartalomból állítja össze, és közben valaki más is menthetett. Ezért a
save_qml_fileés afinalize_uploadegybase_version_idparamétert vár: annak az olvasási vagy mentési válasznak aversion_idértékét, amelyből a tartalma származik. Ha az aktuális verzió még mindig ez, a tartalma lesz az új aktuális verzió. Ha az aktuális verzió elmozdult, és a két módosítás különböző sorokat érint, a kettő összefésülése lesz az aktuális verzió. Ha mindkettő ugyanazokat a sorokat módosította, a rendszer semmit sem ír ki, a válasz pedigoverlap. - A mentést a validáció soha nem akadályozza. Egy vázlatnak, egy beillesztett blokknak vagy egy félkész logikának is tárolhatónak kell lennie, ezért a mentés a létrejövő verzión feljegyzi a formális validáció ítéletét, a problémákat pedig
warningsformájában adja vissza. Azon túl, hogy a cím nem olyan kérdőívre mutat, amelybe írhat, vagy hogy a bemeneti séma elutasítja a hívást, a rendszer csak a következő esetekben utasít el egy mentést: az alap nem a kérdőív egyik verziója (base_version_unknown),overlap, az aktuális verzió minden próbálkozás előtt elmozdult (head_kept_moving), a kérdőívet a mentés futása közben egy másik projektbe helyezték át (questionnaire_moved), lezárt szervezet (org_sealed), valamint 32 KB-nál nagyobb közvetlen tartalom. - A közzététel viszont elutasíthat. A
publish_qml_fileegy verziót rögzít egy kampányhoz, és ez az a pillanat, amikor a mérőeszköz eljut egy válaszadóhoz – ezért ez az egyetlen kapu, amely elutasítja a hibás kérdőívtervet. A rögzített verzió ezután az adott kampány teljes élettartama alatt megváltoztathatatlan.
list_questionnaires
Szekció neve “list_questionnaires”Az összes kérdőív listázása, opcionálisan név szerint szűrve.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
name |
string |
Nem | — | Kis- és nagybetűt nem megkülönböztető részszöveg-szűrő |
limit |
integer |
Nem | 100 |
A visszaadott találatok legnagyobb száma |
Visszatérési érték: { items: [...], count, limit }
get_questionnaire
Szekció neve “get_questionnaire”Kérdőív lekérdezése azonosító alapján.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A kérdőív UUID-ja |
Visszatérési érték: a kérdőívobjektum vagy { error }.
create_questionnaire
Szekció neve “create_questionnaire”Új kérdőív létrehozása QML-tartalomból vagy a sablonkönyvtár egyik sablonjából. A kérdőív és a QML-kódjának 1. verziója együtt jön létre, így kérdőív soha nem létezik tartalom nélkül.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
name |
string |
content esetén |
a sablon neve | Megjelenített név |
content |
string |
A content / template egyike |
— | A QML YAML, amelyet a rendszer 1. verzióként tárol |
template |
string |
A content / template egyike |
— | Egy sablon slugja a list_questionnaire_templates eredményéből; az 1. verzió bájtra pontosan a sablon language nyelvű QML-kódja |
project_id |
string |
Igen | — | A szülőprojekt azonosítója |
description |
string |
Nem | — | Szabad szöveges leírás |
language |
string |
Nem | "en"; template esetén az Öné |
Nyelvkód. template esetén az a nyelv, amelyen a sablont másolni kell: a könyvtár languages értékeinek egyike. Ha elhagyja, a saját nyelve (az Ön beállítása, ennek hiányában a szervezete alapértelmezése), ha a könyvtár kínálja, különben en |
estimated_duration |
integer |
Nem | — | A kitöltés várható ideje percben |
A content vagy a template paramétert adja meg, soha ne mindkettőt: ha mindkettőt vagy egyiket sem adja meg, a rendszer elutasítja a hívást, és semmit sem ír. Ismeretlen template slugra a válasz „nem található”, a könyvtár által nem kínált language értéket pedig a rendszer a kínált nyelvek felsorolásával utasítja el.
A sablonmásolat azon a nyelven készül, amelyen kiolvasták, és a könyvtár által kínált minden más nyelv az 1. verzió fordításaként érkezik vele, így a válaszadóknak fordítási lépés nélkül kínálhatók ezek a nyelvek.
Visszatérési érték: a létrehozott kérdőívobjektum, valamint az 1. verzió version_id és version_number értéke. A version_id az a base_version_id, amelyet e tartalom első mentésekor kell megadni.
A létrehozást a formális validáció nem akadályozza – a content szerkezetileg hibás is lehet. content esetén a rendszer az ítéletet az 1. verzióval együtt feljegyzi, de nem érvényesíti; helyességet csak a kampányhoz való közzététel követel meg. template esetén a validáció a létrehozás után néhány másodperccel a háttérben fut, ahogy egy mentés után is: addig a logic_validated értéke false.
list_questionnaire_templates
Szekció neve “list_questionnaire_templates”A kérdőívsablon-könyvtár listázása: kész kérdőívek (kurzusértékelések, ügyfél-visszajelzések, eseményregisztráció, betegfelvétel és mások), kategóriákba csoportosítva. Egy slugot a create_questionnaire eszköznek template paraméterként adhat át.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
language |
string |
Nem | az Öné | A könyvtár nyelve, amelyen a sablonokat listázni kell. Ha elhagyja, a saját nyelve (az Ön beállítása, ennek hiányában a szervezete alapértelmezése), ha a könyvtár kínálja, különben en. A könyvtár által nem kínált nyelvet a rendszer a kínált nyelvek felsorolásával utasítja el |
category |
string |
Nem | — | Egy kategória slugja; az ismeretlent a rendszer a kategóriák listájával utasítja el |
query |
string |
Nem | — | Szavak, amelyeknek mind elő kell fordulniuk egy sablon nevében vagy leírásában, kis- és nagybetűtől függetlenül |
limit |
integer |
Nem | 50 |
Oldalméret, 1 és 100 között |
cursor |
string |
Nem | — | Az előző oldal next_cursor értéke |
Visszatérési érték: { data: [{ slug, name, category, subcategory, description }], categories: [{ slug, name }], language, language_fallback, languages, total, next_cursor, has_more }. A nevek, leírások és kategóriák language nyelvűek; a languages a könyvtár által kínált összes nyelvet felsorolja, az en nyelvvel kezdve. A language_fallback értéke true, ha nem neveztek meg language értéket, és a könyvtár még nem kínálja az Ön nyelvét, így a válasz angol nyelvű: ezt közölje a felhasználóval. A total az összes illeszkedő sablont számolja; kövesse a next_cursor értéket, amíg a has_more igaz. QML-törzs nem szerepel a listában: hozza létre a kérdőívet egy slugból, majd olvassa ki a get_qml_content eszközzel.
delete_questionnaire
Szekció neve “delete_questionnaire”Kérdőív logikai törlése (soft delete).
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A kérdőív UUID-ja |
Visszatérési érték: { success: true, questionnaire_id } vagy hiba.
A logikai törlés egy biztonsági másolatot tartalmazó sort szúr be; a restore_questionnaire (lásd alább) rövid ideig visszaállíthatja a kérdőívet.
rename_questionnaire
Szekció neve “rename_questionnaire”Kérdőív átnevezése. Tisztán metaadat-módosítás – a kérdőív címe és QML-verziólánca változatlan marad, így a rá hivatkozó kampányok továbbra is működnek.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A kérdőív UUID-ja |
name |
string |
Igen | — | Az új megjelenített név (legfeljebb 255 bájt) |
Visszatérési érték: a frissített kérdőívobjektum.
restore_questionnaire
Szekció neve “restore_questionnaire”Nemrég logikailag törölt kérdőív visszaállítása és a hivatkozásainak újrakapcsolása. A QML-verzióláncát a törlés nem érintette, így a visszaállított kérdőív pontosan azzal a verzióval tér vissza, amellyel rendelkezett.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A kérdőív UUID-ja |
Visszatérési érték: a visszaállított kérdőívobjektum, vagy hiba, ha a visszaállítási időszak lejárt.
list_qml_files
Szekció neve “list_qml_files”A szervezet QML-kérdőíveinek listázása. Nem igényel paramétert. Az egyes bejegyzések qml_name értéke bármely más QML-eszköznek átadható.
Visszatérési érték:
{ "items": [ { "name": "3f9c2b10-....qml", "qml_name": "projects/abc123/questionnaires/3f9c2b10-....qml", "tier": "project", "project_id": "abc123" } ], "count": 1}inspect_qml_file
Szekció neve “inspect_qml_file”Gyors összefoglaló egy kérdőív aktuális verziójáról – az elemek száma és a metaadatok, a teljes tartalom nélkül.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
qml_name |
string |
Igen | — | A kérdőív címe a list_qml_files eredményéből |
Visszatérési érték: { success, qml_name, items_count, metadata }
preview_qml_item
Szekció neve “preview_qml_item”Egy kérdőív aktuális verziójának egy elemét úgy jeleníti meg, ahogy a válaszadó látja. Az MCP Appseket megjelenítő gazdaalkalmazás (például a Claude) egy írásvédett panelt nyit meg az elem valódi vezérlőivel; minden más gazdaalkalmazás ugyanezt az elemet JSON-szövegként kapja meg.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
qml_name |
string |
Igen | — | A kérdőív címe a list_qml_files eredményéből |
item_id |
string |
Igen | — | Az elem id azonosítója |
Visszatérési érték: az elem megjelenített mezői (id, kind, title, input, valamint questions, rows vagy columns, ha az elemnek vannak ilyenjei), a szövegében lévő jelölőkód megtisztításával. Az ismeretlen elem vagy cím eszközhibát eredményez.
get_qml_content
Szekció neve “get_qml_content”Egy kérdőív aktuális verziójának nyers YAML-kódját adja vissza.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
qml_name |
string |
Igen | — | A kérdőív címe |
Visszatérési érték: { success, qml_name, content, size_bytes, version_id, version_number } legfeljebb 32 KB-os tartalom esetén. A version_id megnevezi, melyik verzió a content; adja át base_version_id paraméterként, amikor az ebből a válaszból írt tartalmat menti.
32 KB fölött a tartalom nem kerül közvetlenül a válaszba – ehelyett a válasz { success, qml_name, download_url, size_bytes, version_id, version_number, note }, ahol a download_url egy rövid életű (a lejáratáig újra felhasználható) link, amelyet közvetlenül HTTPS-en tölthet le (további hitelesítés nélkül). A link a version_id verziót szolgálja ki akkor is, ha azóta egy mentés elmozdította az aktuális verziót, így a bájtjai pontosan az a verzió, amelyet mentéskor base_version_id paraméterként megnevez. Ha a link lejárt, hívja meg újra a get_qml_content eszközt.
save_qml_file
Szekció neve “save_qml_file”QML-tartalom mentése egy meglévő kérdőívbe, egy Ön által megnevezett verzióhoz képest. A mentést a hibás YAML vagy a sémasértés soha nem akadályozza – a rendszer a félkész, még nem érvényes piszkozatot is elmenti, a problémákat pedig a rendszer warnings listaként adja vissza az írás elutasítása helyett.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
qml_name |
string |
Igen | — | Egy meglévő kérdőív címe |
content |
string |
Igen | — | QML YAML-tartalom, legfeljebb 32 KB |
base_version_id |
string |
Igen | — | Az a verzió, amelyből a tartalmat írták: az ehhez a kérdőívhez kapott legutóbbi get_qml_content, create_questionnaire vagy mentési válasz version_id értéke |
project_id |
string |
Nem | — | Ha megadja, egyeznie kell a kérdőív projektjével; az eltérést a rendszer elutasítja, nem hagyja figyelmen kívül |
Előbb olvasson, aztán mentsen. Hívja meg a get_qml_content eszközt, alkalmazza a módosítását a visszaadott tartalomra, és mentse a version_id értékével mint base_version_id. Mentés után a következő mentés azt a version_id értéket nevezi meg, amelyet az a mentés visszaadott, soha nem egy korábbit.
Visszatérési érték: { success, qml_name, questionnaire_id, version_id, version_number, created, merged, content_changed, bytes_written, logic_validated, content?, content_note?, warnings? }.
| Mi történt | A válaszban |
|---|---|
| Az alap még mindig az aktuális verzió volt | created: true, merged: false. Az Ön tartalma az új aktuális verzió |
| Valaki közben mentett, más sorokon | created: true, merged: true, content_changed: true. Az aktuális verzió mindkét módosítást tartalmazza, és a content hordozza: ez váltja fel az Ön példányát. A benne lévő, nem Ön által írt sorok a másik szerzőéi |
| Az Ön tartalma már az aktuális verzió | created: false. A rendszer semmit sem ír ki |
| Az Ön tartalma megegyezik az alapjával, és az aktuális verzió elmozdult | created: false, content_changed: true, az aktuális verzió content tartalmával |
A content csak akkor szerepel, ha a tárolt tartalom 32 KB alatti; különben a content_note jelzi, hogy hívja meg a get_qml_content eszközt. A warnings hibátlan mentésnél hiányzik, a mentett, de nem tökéletes piszkozatnál pedig az elemzési, illetve sémaproblémák listája.
A semmit sem író mentés válasza { success: false, error, detail }:
error |
Jelentés | Teendő |
|---|---|---|
overlap |
Valaki közben mentett, és ugyanazokat a sorokat módosította. Hordozza a head_version_id, head_version_number és conflict_count mezőket |
Hívja meg a get_qml_content eszközt, alkalmazza a módosítását a visszaadott tartalomra, és mentse annak version_id értékével. Ne küldje el ugyanazt a tartalmat újra az újabb azonosítóval: ez felülírná a másik mentést |
base_version_unknown |
A base_version_id üres, nem verzióazonosító, vagy nem ennek a kérdőívnek egy verziója |
Hívja meg a get_qml_content eszközt, és mentse a visszaadott version_id értékkel |
head_kept_moving |
A kérdőívet mindhárom próbálkozás előtt újra mentették | Olvassa ki újra, és próbálkozzon ismét |
org_sealed |
A szervezet le van zárva | Semmi sem írható |
questionnaire_moved |
A kérdőívet a mentés futása közben egy másik projektbe helyezték át | Kérje le a list_qml_files eszközzel az aktuális címét, olvassa ki a get_qml_content eszközzel, és mentse újra |
A formális validáció a mentés után néhány másodperccel a háttérben fut azon a verzión, amely akkor az aktuális (az Öné vagy az összefésült), a rendszer pedig ezen a verzión jegyzi fel az ítéletét, így egy verzió helyessége később, további szerkesztések után is megállapítható marad. Addig a mentési válasz logic_validated értéke null, és a logic_validation_note ezt jelzi, a get_questionnaire pedig logic_validated: false értéket ad; az ítéletet akkor adja vissza, amikor megérkezik, a validate_qml_file pedig kérésre jelenti. Az a mentés, amely elrontja a korábban hibátlan kérdőívet, nem akadályozza az írást, de a kérdőívet nem validált állapotba váltja; a kampányhoz való közzétételét a rendszer a javításig elutasítja.
A rendszer elutasítja azt a címet, amely mögött nincs kérdőív – előbb hívja meg a create_questionnaire eszközt.
A 32 KB-nál nagyobb tartalmat a rendszer elutasítja a {"error": "content_too_large_for_inline_save"} válasszal, és semmit sem ír. A tartalom méretre vágása helyett használja a request_upload_url / finalize_upload párost (lásd alább).
request_upload_url / finalize_upload
Szekció neve “request_upload_url / finalize_upload”Kétlépéses mechanizmus olyan QML-tartalom mentéséhez, amely túl nagy a save_qml_file 32 KB-os közvetlen korlátjához. Maga a tartalom soha nem jelenik meg eszközhívásban – kér egy feltöltési azonosítót, a bájtokat közvetlenül HTTPS-en tölti fel, majd véglegesít.
-
request_upload_url(qml_name, project_id?)– rövid életű, egyszer használható, méretkorlátos feltöltési azonosítót hoz létre.Visszatérési érték:
{ upload_url, artifact_id, max_size_bytes, expires_in } -
Töltse fel a nyers QML-bájtokat közvetlenül az
upload_urlcímre (egy HTTPPUTkéréssel, az MCP-eszközhíváson kívül). -
finalize_upload(artifact_id, base_version_id)– a feltöltött tartalmat pontosan úgy menti, ahogy asave_qml_filementené az adott alapra: a rendszer létrehozza, összefésüli egy újabb mentéssel, vagy elutasítja. Abase_version_idkötelező, és ugyanazt jelenti, mint asave_qml_fileesetén. Ugyanazzal azartifact_idértékkel biztonságosan újrapróbálható: egy mentést végző vagyoverlapválaszt adó véglegesítés után az újrapróbálás az első választ adja vissza, és semmit sem ír, bármilyen alapot nevez is meg.Visszatérési érték: ugyanaz a válaszszerkezet, mint a
save_qml_fileeseténAz
overlapelhasználja a feltöltési azonosítót, mert a feltöltött bájtokat a régi verzióhoz képest írták: olvassa ki újra, alkalmazza ismét a módosítását, és töltse fel az eredményt egy új azonosítón keresztül. Abase_version_unknownés ahead_kept_movingmegtartja az azonosítót, így egy javított hívás ugyanazt a feltöltést menti.
validate_qml_file
Szekció neve “validate_qml_file”Z3 SMT formális validáció futtatása egy kérdőív aktuális verzióján. Minden elemre vonatkozóan elemzi az elérhetőséget, a konzisztenciát és az utófeltételek teljesíthetőségét.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
qml_name |
string |
Igen | — | A kérdőív címe |
Visszatérési érték:
{ "is_valid": true, "item_count": 12, "block_count": 3, "item_classifications": { "q_age": { "precondition": "REACHABLE", "postcondition": "CONTINGENT" } }, "statistics": { "preconditions": {"REACHABLE": 11, "NEVER": 1}, "postconditions": {"CONTINGENT": 8, "TAUTOLOGICAL": 3, "INFEASIBLE": 1} }, "issues": [ { "item_id": "q_unreachable", "severity": "error", "type": "unreachable_item", "message": "Item is unreachable", "suggestion": "Check preconditions" } ], "validation_report": "..."}Besorolási referencia
Szekció neve “Besorolási referencia”Előfeltétel-állapotok (elérhető-e az elem?):
| Állapot | Jelentés |
|---|---|
REACHABLE |
Az elem legalább egy kitöltési úton elérhető |
NEVER |
Az elem elérhetetlen – halott kód |
UNKNOWN |
Az elemzés nem tudta megállapítani az elérhetőséget |
Utófeltétel-állapotok (teljesíthetők-e az elem feltételei?):
| Állapot | Jelentés |
|---|---|
TAUTOLOGICAL |
A feltétel mindig igaz (redundáns) |
CONTINGENT |
A feltétel a válaszoktól függ (normál) |
INFEASIBLE |
A feltétel soha nem teljesíthető |
UNKNOWN |
Az elemzés nem tudta megállapítani |
Problématípusok
Szekció neve “Problématípusok”| Típus | Súlyosság | Leírás |
|---|---|---|
unreachable_item |
error | Az előfeltétel NEVER – halott elem |
code_answered_item |
warning | Egy codeBlock minden olyan kitöltésben, ahol a feltétele teljesül, még azelőtt eltárolja az elem válaszát, hogy a kitöltés elérné az elemet, így azt soha nem kérdezik meg. Ha az elemet fel kell tenni, helyezze a codeBlockot az elem után |
infeasible_postcondition |
error | Az utófeltétel soha nem teljesíthető |
globally_false_postcondition |
error | Az utófeltétel mindig hamis |
tautological_postcondition |
warning | Az utófeltétel mindig igaz (redundáns) |
comment_titled_as_question |
warning | Egy csak megjelenítésre szolgáló Comment címe kérésként van megfogalmazva, így megválaszolására szolgáló mező nélkül jelenik meg |
roster_subject_not_answerable |
warning | Egy Roster subjectFrom mezője olyan elemet nevez meg, amely soha nem szolgáltathat alanyt (hiányzik, a blokkon kívül van, vagy Comment) |
none_unsafe_reference |
warning | Egy feltétel olyan elemen végez rendezést vagy számítást, amelyet nem minden odavezető úton kérdeznek meg – az elem kimenete None, és a predikátum kivételt dob. A None értékkel való egyenlőségvizsgálat biztonságos, a validátor nem jelöli meg |
inexact_condition |
warning | Egy feltétel olyan elemet olvas, amely megválaszolatlan lehet egy olyan helyen, ahol a validátor nem tudja eldönteni, hogy a None olvasása meghiúsítja-e (egy not alatt, egy or utolsó előtti operandusában, vagy bárhol egy utófeltételben). Az ellentmondást továbbra is jelenti, de a feltétel mindig igaz voltát nem bizonyítja. Először vizsgálja meg, van-e válasz: előfeltételben q.outcome is not None and (…), utófeltételben q.outcome is None or (…) |
uninitialized_read |
warning | Egy feltétel vagy codeBlock olyan változót olvas, amelyet a válaszadó bármilyen értékadás lefutása előtt elérhet – a változó később, csak az egyik ágon, vagy olyan elemtől kap értéket, amelyet a saját feltétele átugorhat. Az olvasás kivételt dob: az előfeltétel átugorja az elemet, míg az utófeltétel ellenőrzés nélkül elfogadja a választ, a codeBlock pedig félúton leáll – mindkettő kizárja a kitöltést az adatkészletekből. Adjon alapértéket a codeInit blokkban, adjon értéket mindkét ágon, vagy lássa el az olvasót ugyanazzal a feltétellel, mint az értékadást |
self_assignment |
warning | Egy codeBlock-utasítás önmagának ad értéket (q.outcome = q.outcome) – semmit sem változtat, de származtatásnak tűnik |
mandated_answer_postcondition |
warning | Egy utófeltétel egy választó vezérlőnek csak egyetlen válaszát engedi meg, így a bármely más választ adó válaszadó nem tud továbblépni, és azt a választ a rendszer soha nem rögzíti. Ehelyett a válasz alapján ágaztassa el a kérdőívet |
combinable_none_option |
warning | Egy Checkbox „Egyik sem” típusú opciója együtt jelölhető azokkal az opciókkal, amelyeket kizár, és egyetlen utófeltétel sem tiltja ezt a kombinációt |
questionnaire_level_condition |
warning | Gyökérszintű precondition/postcondition kulcs. A rendszer a feltételeket csak elem- és blokkszinten értékeli ki, így ez soha nem fut le |
language_not_judged |
warning | A kérdőív nyelve a támogatott nyelveken kívül esik, így a szóalapú ellenőrzések nem futottak le: a comment_titled_as_question megfogalmazásra vonatkozó része (a Comment címében lévő ? jelet a validátor továbbra is ellenőrzi) és a combinable_none_option. Ezeket kézzel ellenőrizze |
file_not_found |
error | A cím mögött nincs kérdőív |
validation_error |
error | Kivétel az elemzés vagy a feldolgozás során |
qml_quality_report
Szekció neve “qml_quality_report”Tervezésiminőség-értékelőlap (D2–D8 dimenziók) számítása egy kérdőív aktuális verziójára. Akkor használja, miután a validate_qml_file nulla hibát jelentett – a validáció a logikai helyességet bizonyítja; ez a tervezés minőségét osztályozza (a mérőeszköz gazdaságossága, a minőségkapuk sűrűsége, az ellenőrzési lefedettség, a szerkezeti összetettség, a sorrend koherenciája, az utak változatossága és a teher kiegyensúlyozottsága). A minőségkapuk sűrűségét a kérdőív numerikus bevitelein méri a rendszer – azokon a válaszokon, amelyeket a válaszadó begépel vagy csúszkával ad meg, és ahol az utófeltétel olyan érvényességi határt ad hozzá, amelyet maga a vezérlő nem. A választó elemek kimaradnak ebből az arányból, mert a címkekészletük már rögzíti a választ; az egyik választást egy másikhoz kötő utófeltételt a rendszer külön, konzisztenciakapuként jelenti. Determinisztikus és tájékoztató jellegű: az osztályzatok soha nem befolyásolják az is_valid értéket vagy a közzétételt.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
qml_name |
string |
Igen | — | A kérdőív címe |
Visszatérési érték:
{ "dimensions": { "instrument_economy": { "id": "D2", "grade": "strong", "metrics": { }, "offenders": [{"item_id": "...", "detail": "..."}], "truncated": false } }, "item_count": 12, "notes": []}Az egyes dimenziók grade értéke strong, adequate, weak vagy not_applicable. Ismeretlen cím vagy sikertelen elemzés esetén a válasz { error }.
publish_qml_file
Szekció neve “publish_qml_file”Kérdőív közzététele egy kampányhoz – a terepmunka kapuja, és ebben a referenciában az egyetlen eszköz, amely elutasítja a hibás kérdőívtervet.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A terepre viendő kérdőív UUID-ja |
campaign_id |
string |
Igen | — | Annak a kampánynak az UUID-ja, amelyhez rögzíteni kell |
A rendszer formálisan validálja a kérdőív aktuális verzióját, az ítéletet ezen a verzión jegyzi fel, és csak hibátlan ítélet esetén rögzíti a verziót a kampányhoz.
Visszatérési érték: { success, questionnaire_id, campaign_id, qml_version_id, logic_validated }
Elutasításkor: { error, issues } – az issues felsorolja a javítandó, hiba súlyosságú problémákat. A rendszer semmit sem rögzít, így a kampány továbbra is azt viszi terepre, amit addig.
A kampánynak már erre a kérdőívre kell hivatkoznia; ha egy másikat visz terepre, előbb kösse át az update_campaign_questionnaire eszközzel.
move_qml_to_project
Szekció neve “move_qml_to_project”Kérdőív áthelyezése egy másik projektbe. A kérdőív azonosítója változatlan marad, és a verzióláncát sem érinti az áthelyezés, így a rá hivatkozó kampányok – a korábbi verzióhoz rögzítetteket is beleértve – továbbra is működnek. Az áthelyezés nem szerkesztés.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A kérdőív UUID-ja |
target_project_id |
string |
Igen | — | A célprojekt UUID-ja |
Visszatérési érték: { success, questionnaire_id, qml_name } – a qml_name az új cím.
unpublish_qml_file
Szekció neve “unpublish_qml_file”Kérdőív visszavonása a projektjéből logikai törléssel. A QML-verziólánca megmarad – egy befejezett kampány még rögzítve lehet valamelyik verzióhoz, így a közzététel visszavonása eltávolítja a kérdőívet az Ön munkaanyagai közül anélkül, hogy kitörölné azt, amit terepre vittek. Nem hajtható végre, amíg a kérdőívnek aktív kampányai vannak.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A kérdőív UUID-ja |
Visszatérési érték: { success, questionnaire_id } vagy hiba.
Fordítások
Szekció neve “Fordítások”A fordítás egy adott kérdőívverzió mellett álló lefordított szöveg, nyelvenként egy. Csak a válaszadók számára látható szöveget cseréli le; az azonosítók, az opciókódok, a feltételek és a Z3-ítélet a forrásé marad. A válaszadóknak csak a teljes fordítást kínálja fel a rendszer. Fogalmak, befagyasztás és a válaszadói nyelvválasztó: Kérdőív fordítása.
Minden fordítási eszköz megnevezi a questionnaire_id értéket, a version_id értéket (azt a version_id értéket, amelyet a get_qml_content vagy egy mentés visszaadott), és – a lista kivételével – a locale értéket (en, es, fr, de vagy hu, soha nem a kérdőív saját forrásnyelve). Mindegyik először átviszi az előző verzió fordításait a megnevezett verzióra, így egy újonnan mentett verzió már tartalmaz minden olyan szöveget, amelynek a forrása nem változott.
A szövegkulcsok egy-egy, a válaszadó számára látható szöveget neveznek meg: questionnaire/title, block:<id>/title, item:<id>/title, item:<id>/labels/<code> (opciócímkék, kód szerint), item:<id>/rows/<n> és /columns/<n> (mátrix), item:<id>/questions/<n> (kérdéscsoport), item:<id>/left, /right, /on, /off, /placeholder, valamint .../postcondition/<n>/hint (a válasz elutasításakor megjelenő üzenet). Egy verzió pontos kulcsait a get_qml_translation source_texts mezőjéből olvashatja ki.
list_qml_translations
Szekció neve “list_qml_translations”Egy verzió összes fordítása, nyelvenként.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A kérdőív UUID-ja |
version_id |
string |
Igen | — | A kérdőív egyik verziója |
Visszatérési érték: { questionnaire_id, version_id, source_language, translations: [{ locale, started, withdrawn, complete, untranslated, frozen, human_edited, updated_at }] }, a forrásnyelv kivételével minden támogatott nyelvhez egy bejegyzéssel, így a lista azokat a nyelveket is megnevezi, amelyeket még senki sem kezdett el (started: false, üresen hagyott untranslated mezővel: minden kulcs lefordítatlan, és a get_qml_translation felsorolja őket), valamint azokat, amelyek fordítását törölték (withdrawn: true). Az untranslated a még hiányzó szövegkulcsokat sorolja fel; a frozen azt jelenti, hogy egy kitöltést ezen a nyelven válaszoltak meg, így nem menthető és nem törölhető; a human_edited azt, hogy egy ember szerkesztette a szerkesztőben.
get_qml_translation
Szekció neve “get_qml_translation”Egy nyelv fordítása az általa fordított forrással együtt.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A kérdőív UUID-ja |
version_id |
string |
Igen | — | A kérdőív egyik verziója |
locale |
string |
Igen | — | A célnyelv |
Visszatérési érték: az adott nyelv listamezői, valamint a texts (kulcs → lefordított szöveg), a source_language és a source_texts (minden fordítható kulcs → a forrásszövege, dokumentumsorrendben). A még fordítás nélküli nyelv üres texts mezőt és updated_at: null értéket ad vissza.
save_qml_translation
Szekció neve “save_qml_translation”Egy nyelv lefordított szövegének mentése. A mentés részleges: a rendszer a texts tartalmát ráfésüli a tárolt fordításra, és minden kihagyott kulcs megtartja a tárolt szövegét, így a hiánypótlás csak az untranslated listában szereplő kulcsokat küldi el.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A kérdőív UUID-ja |
version_id |
string |
Igen | — | A kérdőív egyik verziója |
locale |
string |
Igen | — | A célnyelv |
texts |
object |
Igen | — | Szövegkulcs → lefordított szöveg |
base_updated_at |
string | null |
Igen | — | Az olvasáskor kapott updated_at; null, ha az olvasás nem talált tárolt fordítást |
Visszatérési érték: a tárolt fordítás (texts, complete, untranslated, frozen, human_edited, updated_at). A következő mentés az ebben kapott updated_at értéket nevezi meg. Az MCP-n vagy API-n keresztüli mentést a rendszer ügynök által írtként rögzíti, és soha nem jelöli meg a fordítást human_edited értékkel.
| Elutasítás | Jelentés | Teendő |
|---|---|---|
| Érvénytelen kulcsok (hibás kérés, kulcsonként egy sor) | Egy kulcs olyan elemet, blokkot vagy opciókódot nevez meg, amely a forrásból hiányzik, tartományon kívüli indexet, részlegesen elküldött pozicionális listát (rows, columns, questions, utófeltétel-tippek), nem szöveges értéket, vagy jelölőkódot, például <script> elemet tartalmaz |
Javítsa ki pontosan a megnevezett kulcsokat, majd mentse újra |
translation_conflict (409) |
A fordítás az olvasás óta megváltozott, általában egy kutató szerkesztése miatt | Olvassa ki újra a get_qml_translation eszközzel, alkalmazza ismét a módosítását, és mentse az új updated_at értékkel |
translation_frozen (409) |
Ezen a verzión már megválaszoltak egy kitöltést ezen a nyelven | Ne próbálkozzon újra. Mentsen új kérdőívverziót, fordítsa le azt, és állítsa át rá a kampányt |
| Forrásnyelv (hibás kérés) | A nyelv a kérdőív saját nyelve | Magát a QML-t szerkessze, vagy fordítson egy másik nyelvre |
| Nem található | A verzió nem ennek a kérdőívnek egy verziója | Olvassa ki a kérdőívet a get_qml_content eszközzel, és a visszaadott version_id értéket nevezze meg |
delete_qml_translation
Szekció neve “delete_qml_translation”Egy verzió egy nyelvi fordításának törlése. A befagyasztott fordítás törlését a rendszer elutasítja (translation_frozen), a fordítás nélküli nyelvre pedig a válasz „nem található”.
| Paraméter | Típus | Kötelező | Alapértelmezés | Leírás |
|---|---|---|---|---|
questionnaire_id |
string |
Igen | — | A kérdőív UUID-ja |
version_id |
string |
Igen | — | A kérdőív egyik verziója |
locale |
string |
Igen | — | A törlendő nyelv |
Visszatérési érték: { questionnaire_id, version_id, locale, deleted: true }.
Hibakezelés
Szekció neve “Hibakezelés”A QML-életciklus megszorításai
Szekció neve “A QML-életciklus megszorításai”| Helyzet | Válasz |
|---|---|
| Közzététel visszavonása aktív kampányok mellett | {"error": "Cannot unpublish: questionnaire has active campaign {campaign_id}"} |
| Hibás verzió közzététele | {"error": "...", "issues": [...]} – a rendszer semmit sem rögzít |
| Közzététel olyan kampányhoz, amely egy másik kérdőívet visz terepre | {"error": "Campaign {id} fields questionnaire {other}, not {id}. Use update_campaign_questionnaire to rebind it first."} |
| Már a célprojektben van | {"error": "Questionnaire is already in this project"} |
Hatókör
Szekció neve “Hatókör”Minden eszköz kizárólag az Ön saját szervezetén belül keresi a kérdőíveket. Egy másik szervezethez tartozó cím megkülönböztethetetlen egy nem létezőtől, és a kérdőív saját projektjétől eltérő project_id értéket a rendszer elutasítja, nem hagyja csendben figyelmen kívül.
Gyakori hibák
Szekció neve “Gyakori hibák”| Helyzet | Válasz |
|---|---|
| A kérdőív nem található | {"error": "Questionnaire {id} not found"} |
| A szervezeti környezet nincs beállítva | {"error": "Organization context not set"} |
| A cím mögött nincs kérdőív | {"error": "QML document '{name}' not found for this organization"} |
| A mentés nem nevez meg használható alapot | {"success": false, "error": "base_version_unknown", "detail": "..."} |
| A mentés ütközik egy újabb mentéssel | {"success": false, "error": "overlap", "head_version_id": "...", "head_version_number": n, "conflict_count": n} |
| QML-elemzési hiba | {"error": "Failed to parse QML: {details}"} |