Így építette újra a Mintlify az önfrissítő dokumentáció rendszerét

Két ügynök kezeli a dokumentáció frissítését

A Mintlify október 30-án közzétett mérnöki beszámolója szerint a rendszert egy háttérügynökre és egy futtatóügynökre osztották. Mindkettő ügynöki ciklusként működik, hozzáféréssel egy elkülönített futtatási környezethez, kód­tárak klónozásához, külső integrációk olvasásához és közös memóriához.

A memóriát egy Git-alapú adattárban tárolják. Ebben különböző memóriafájlok találhatók, az egyes ügynöki futások naplói pedig JSON-formátumban kerülnek elmentésre. A rendszer eseményindítókat is kezel, például ütemezett futásokat, kód­tárbeli összeolvasztásokat vagy külső szolgáltatások eseményeit. Ilyen lehet például, ha egy Jira-projektet késznek jelölnek.

Az eseményindító egy készséghez kapcsolódik. Aktiválásakor a rendszer feladatot küld a futtatóügynöknek, amely gyakran dokumentációs pull requestet készít, majd értesíti a megfelelő embereket a felülvizsgálatról.

A háttérügynök a korábbi eredményekből módosítja a beállításokat

A Mintlify minden oldalhoz naponta elindítja a háttérügynököt. A rendszerutasítás szerint az ügynöknek a dokumentáció sikeréért kell felelősséget vállalnia. Optimalizálási célja a beolvasztott dokumentációs pull requestek számának növelése úgy, hogy az elfogadási arány 80 százalék felett maradjon.

Ehhez az ügynök módosíthatja a futtatóügynök eseményindítóit, készségeit és közös memóriáját. A döntésekhez korábbi futási naplókat, a kapcsolt integrációk adatait, a dokumentációs platform elemzéseit és az elfogadott pull requesteket vizsgálja.

A Mintlify egyik példájában egy kód­tárbeli pull requesteket figyelő eseményindító a parancssori felület dokumentációját is frissítette. Ezeket a módosításokat azonban rendszeresen bezárták, mert a parancssori eszköz folyamatos kiadási ciklusban jelent meg. A háttérügynök ezt felismerte, eltávolította a CLI-módosításokat az adott készségből, majd havi ütemezést hozott létre a CLI-kiadási jegyzetekhez.

A vállalat a vezérlőréteget házon belül építette meg. Korábban az OpenCode és a Pi használatával kísérleteztek, de a beszámoló szerint ezek túl sok mögöttes mérnöki döntést rejtettek el, és nehezebben illeszkedtek a Mintlify környezetéhez és adatmodelljeihez. A saját megoldásuk a Vercel AI SDK segítségével ismételgeti a nyelvi modell hívásait, valamint egyedi eszközöket biztosít többek között alügynökökhöz, munkamenetek szétágaztatásához, készségek használatához és parancsok sandboxban történő futtatásához. A Mintlify offline dokumentációs tesztkészletén a saját rendszer és a Pi hasonlóan teljesített, a Pi azonban 50 százalékkal több tokent használt.

A strukturált memória segíti a pontosabb frissítéseket

A Mintlify szerint a legnehezebb feladat a memória, az egyedi eszközök és az előre beállított készségek megfelelő kialakítása. Egy dokumentációs módosításnál tudni kell például, melyik csapat felel érte, hol beszélnek róla Slackben vagy Notionben, gördülő kiadási ciklushoz kapcsolódik-e, ki vizsgálja felül, és milyen értesítést kell küldeni.

Ennek kezelésére rögzített sémájú JSON-fájlokat használnak. Egy nagyobb kiadás memóriája tartalmazhatja a kód- és dokumentációs pull requesteket, az érintett személyeket, a specifikációkat és tervezési dokumentumokat, a közvetlen beolvasztásra vagy további pull requestekre vonatkozó döntést, valamint azt a dátumot, amely előtt nem kezdődhet meg a dokumentáció módosításának előkészítése.

A fájlszerkezetben külön helyet kapnak a teljes oldalra vonatkozó beállítások, a stílus útmutatója, a felhasználók, a nagyobb kiadások és az integrációk. A Mintlify egyes területeken szabadabb formátumú Markdown-fájlokat is engedélyez, ahol nehezebb előre meghatározni, milyen adatokat kell tárolni.

A vállalat érvelése szerint a strukturált memória könnyebben karbantartható, mérhető és ellenőrizhető, mint a szabad szöveges jegyzetelés. Az ügynök például célzott feladatot kaphat az összes, egy kiadáshoz tartozó kód-pull request megkeresésére. A felhasználói memóriánál kézzel címkézett adathalmazzal mérhetik, hogy az ügynök az elvárt mezők mekkora részét tölti ki helyesen.

Az architektúra már az Autopilotot is működteti

A rendszer módosításait egyszerű szöveges leírás formájában küldik el minden háttérügynöknek. Az ügynök feladata ilyenkor a jelenlegi beállítások ellenőrzése, az esetleges visszaesések figyelése és a memóriafájlok frissítése az új sémák szerint. A Mintlify egy nagyobb kódkiadásokhoz kapcsolódó támogatás bevezetésekor így töröltette az örökölt mezőket, feltérképeztette a nagyobb funkciókat, majd futtatóügynököket indított a megvalósításhoz.

Ugyanez a megközelítés termékek bevezetésénél is használható. A Mintlify példája szerint egy dokumentációs képernyőképeket automatizáló funkciónál a háttérügynök felmérheti, hogy az adott ügyfélnél van-e felhasználói felület, használnak-e képernyőképeket a dokumentációban, és elérték-e már a megfelelő működési állapotot. Ezután kiválaszthatja, kit érdemes értesíteni, és milyen üzenet lehet releváns.

A futási naplók minden ügynöki munkamenet üzeneteit, kimeneteit, létrehozott pull requestjeit és értesítéseit tartalmazhatják. A szétágaztatott munkamenetek fa struktúrát alkotnak, így egy végponti munkamenet teljes előzménye a gyökérig visszafejthető.

A Mintlify szerint ez az architektúra működteti a frissen elindított Autopilotot. A bejelentés alapján a rendszer célja, hogy a dokumentáció frissítései jobban illeszkedjenek az egyes csapatok munkafolyamataihoz, miközben a korábbi futások eredményei alapján képes módosítani saját beállításait.