Að opna Codex-umgjörðina: hvernig við byggðum App Server

Fulltrúi OpenAI, Codex, er til staðar á mörgum mismunandi verkvöngum: vefappinu⁠(opnast í nýjum glugga), CLI⁠(opnast í nýjum glugga), IDE-viðbótinni⁠(opnast í nýjum glugga) og nýja Codex macOS-appinu. Undir niðri eru þau öll knúin af sama Codex-kerfinu—fulltrúalykkjunni og rökunum sem liggja að baki allri Codex-reynslu. Hver er mikilvægasta tengingin á milli þeirra? Codex App Server⁠(opnast í nýjum glugga), viðskiptavænt, tvíátta JSON-RPC¹ API.

Í þessari færslu kynnum við Codex App Server; við deilum því sem við höfum lært hingað til um bestu leiðirnar til að færa getu Codex inn í vöruna þína til að hjálpa notendum þínum að auka afköst í verkflæði sínu. Við munum fjalla um högun og samskiptareglu App Server og hvernig hann samþættist við mismunandi Codex-viðmót, sem og ráð um hvernig má nýta Codex, hvort sem þú vilt breyta Codex í kóðayfirlesara, SRE-fulltrúa eða forritunaraðstoðarmann.

Áður en þú kafar ofan í högun er gagnlegt að þekkja forsögu App Server. Upphaflega var App Server hagnýt leið til að endurnýta Codex-umgjörðina yfir mismunandi vörur, sem smám saman þróaðist í staðlaða samskiptareglu okkar.

Codex CLI byrjaði sem TUI (terminal notendaviðmót), sem þýðir að Codex er opnað í gegnum skipanalínuna. Þegar við smíðuðum VS Code-viðbótina (IDE-vænni leið til að eiga samskipti við Codex-fulltrúa), þurftum við að finna leið til að nota sama kerfi til að keyra sömu fulltrúalykkju úr IDE notendaviðmóti án þess að endurútfæra hana. Það þýddi að styðja rík gagnvirknimynstur umfram beiðni/svar, eins og að skoða vinnusvæðið, streyma framvindu á meðan fulltrúinn rökstyður og gefa út breytingar. Við gerðum fyrst tilraunir með að gera Codex að MCP-netþjóni⁠(opnast í nýjum glugga), en það reyndist erfitt að viðhalda MCP-merkingarfræði á þann hátt sem var skynsamlegur fyrir VS Code. Í staðinn kynntum við JSON-RPC samskiptareglu sem speglaði TUI-lykkjuna, sem varð að óopinberri fyrstu útgáfu⁠(opnast í nýjum glugga) af App Server. Á þeim tíma bjuggumst við ekki við að aðrir viðskiptavinir myndu reiða sig á App Server svo hann var ekki hannaður sem stöðugt API.

Eftir því sem innleiðing Codex jókst á næstu mánuðum vildu innri teymi og ytri samstarfsaðilar geta fellt inn sama kerfi í eigin vörur til að flýta fyrir hugbúnaðarþróunarferlum notenda sinna. Til dæmis vildu JetBrains og Xcode fá IDE-stigs fulltrúaupplifun, á meðan Codex-skjáborðsappið þurfti að samræma marga Codex-fulltrúa samhliða. Þessar kröfur fengu okkur til að hanna yfirborð verkvangs sem bæði vörur okkar og samþættingar samstarfsaðila gætu treyst á til lengri tíma. Það þurfti að vera auðvelt að samþætta og afturvirkt samhæfa, sem þýddi að við gætum þróað samskiptaregluna án þess að trufla núverandi viðskiptavini.

Næst munum við fara yfir hvernig við hönnuðum högunina og samskiptareglurnar þannig að mismunandi viðskiptavinir geti notað sama ramma.

Fyrst skulum við skoða nánar hvað er inni í Codex-umhverfinu og hvernig Codex App Server gerir það aðgengilegt fyrir viðskiptavini. Í síðasta Codex blogginu okkar greindum við kjarnalykkju fulltrúa sem samhæfir samskiptin milli notandans, líkansins og verkfæranna. Þetta er kjarna rökfræði Codex-umhverfisins, en það er meira sem bætist við heildarupplifun fulltrúans:

1. Lífsferill þráða og viðvarandi ástand Þráður er samtal í Codex milli notanda og Codex-fulltrúa. Codex býr til, heldur áfram, gafflar og safnvistar þræði og varðveitir viðburðasöguna svo viðskiptavinir geti tengst aftur og birt samræmda tímalínu.

2. Stillingar og auðkenning Codex hleður stillingum, sér um sjálfgefnar stillingar og keyrir auðkenningarferli eins og „Skráðu þig inn með ChatGPT,“ þar á meðal ástand skilríkja.

3. Keyrsla verkfæra og viðbætur Codex keyrir skeljar- og skráarverkfæri í sandkassa og tengir samþættingar eins og MCP-netþjóna og hæfileika svo þau geti tekið þátt í fulltrúalykkjunni undir samræmdu stefnumótunarlíkani.

Öll fulltrúarreglan sem við nefndum hér, þar á meðal kjarnahringur fulltrúa, er í hluta af Codex CLI-kóðagrunninum sem kallast “Codex core⁠(opnast í nýjum glugga).” Codex core er bæði safn þar sem allur fulltrúakóði er geymdur og keyrsluumhverfi sem hægt er að ræsa til að keyra fulltrúalykkjuna og stjórna viðvarandi einnar Codex-þráðar (samtals).

Til að vera gagnlegt þarf Codex-kerfið að vera aðgengilegt viðskiptavinum. Þar kemur App Server til sögunnar.

App-netþjónninn er bæði JSON-RPC samskiptareglan milli biðlarans og netþjónsins og langvarandi ferli sem hýsir Codex kjarnaþræði. Eins og við sjáum á skýringarmyndinni hér að ofan, hefur App Server-ferli fjóra meginþætti: stdio-lesarann, Codex-skilaboðavinnsluna, þráðastjórann og kjarnaþræðina. Þráðastjórinn ræsir eina kjarnalotu fyrir hvern þráð, og Codex-skilaboðavinnslan hefur síðan bein samskipti við hverja kjarnalotu til að senda inn beiðnir frá viðskiptavinum og taka á móti uppfærslum.

Ein beiðni frá viðskiptavini getur leitt til margra uppfærslna á viðburðum, og þessir ítarlegu viðburðir gera okkur kleift að byggja upp ríkt notendaviðmót ofan á App Server. Að auki starfa stdio-lesarinn og Codex-skilaboðavinnslan sem þýðingarlag milli biðlarans og Codex-kjarnaþráða. Þeir umbreyta JSON-RPC beiðnum viðskiptavina í kjarnaaðgerðir Codex, hlusta á innri viðburðastraum Codex kjarna og breyta síðan þessum lágstigsviðburðum í lítið safn stöðugra, notendaviðmóts-tilbúinna JSON-RPC tilkynninga.

JSON-RPC samskiptareglurnar milli biðlarans og App Server eru fullkomlega tvíátta. Venjulegur þráður inniheldur beiðni frá viðskiptavini og margar tilkynningar frá netþjóni. Að auki getur netþjónninn hafið beiðnir þegar fulltrúi þarf inntak, eins og samþykki, og síðan gert hlé á ferlinu þar til viðskiptavinurinn svarar.

Næst munum við brjóta niður samræðu frumþættina, grunnbyggingareiningar samskiptareglna App Server. Að hanna API fyrir fulltrúalykkju er flókið vegna þess að samskipti milli notanda og fulltrúa eru ekki einföld beiðni og svar. Ein beiðni notanda getur þróast í skipulagða röð aðgerða sem viðskiptavinurinn þarf að endurspegla á trúverðugan hátt: inntak notandans, stigvaxandi framvindu fulltrúans, afurðir sem verða til á leiðinni (t.d., breytingar). Til að gera samskiptastrauminn auðveldan í samþættingu og sterkan yfir notendaviðmótum, ákváðum við að nota þrjá kjarnagrunnþætti með skýrum mörkum og lífsferlum:

1. Atriði: Atriði er minnsta eining inntaks/frálags í Codex. Atriði eru flokkuð eftir gerð (t.d. skilaboð notanda, skilaboð fulltrúa, keyrsla verkfæris, beiðni um samþykki, diff) og hvert þeirra hefur skýran lífsferil:

• item/started þegar atriðið byrjar
• valfrjálsir item/*/delta atburðir sem efnisstraumar (fyrir streymandi atriðategundir)
• item/completed þegar atriðið klárast með lokahleðslu sinni

Þessi lífsferill gerir viðskiptavinum kleift að hefja birtingu strax á started, streyma stigvaxandi uppfærslum á delta og ljúka á completed.

2. Umferð: Umferð er ein eining vinnu fulltrúa sem hefst með inntaki notanda. Ferlið hefst þegar viðskiptavinurinn sendir inn inntak (t.d. „keyra prófanir og draga saman bilanir“) og lýkur þegar fulltrúinn hefur lokið við að framleiða frálag fyrir það inntak. Umferð inniheldur röð atriða sem tákna milliskref og frálög sem verða til á leiðinni.

3. Þráður: Þráður er varanlegt ílát fyrir áframhaldandi Codex-lotu milli notanda og fulltrúa. Hann inniheldur mörg skipti. Hægt er að búa til þræði, halda áfram með þá, kljúfa þá og setja í geymslu. Ferill þráðarins er varðveittur þannig að notendur geta tengst aftur og birt samræmda tímalínu.

Nú ætlum við að skoða einfaldað samtal milli viðskiptavinar og fulltrúa, þar sem samtalið er táknað með frumstæðum einingum:

Í upphafi samtalsins þurfa biðlarinn og þjónninn að koma á initialize handabandi. Viðskiptavinurinn verður að senda eina initialize beiðni áður en nokkur önnur aðferð er kölluð og netþjónninn staðfestir með svari. Þetta gefur þjóninum tækifæri til að kynna getu sína og gerir báðum aðilum kleift að sammælast um útgáfustýringu samskiptareglna, eiginleikafána og sjálfgefin gildi áður en raunverulega verkið hefst. Hér er dæmi um gagnapakka frá VS Code-viðbót OpenAI:

Þetta er það sem netþjónninn skilar:

Þegar viðskiptavinur gerir nýja beiðni mun hann fyrst búa til þráð og síðan umferð. Þjónninn mun senda til baka tilkynningar um framvindu (thread/started og turn/started). Hann mun einnig senda til baka inntök sem hann skráir sem atriði, eins og skilaboð notandans hér.

Verkfæraköll eru einnig send aftur til viðskiptavinarins sem atriði. Að auki gæti þjónninn beðið um samþykki viðskiptavinarins áður en hann getur framkvæmt aðgerð með því að senda beiðni til þjónsins. Samþykkið mun stöðva ferlið þar til viðskiptavinurinn svarar með annaðhvort „leyfa“ eða „hafna“. Svona lítur samþykkisferlið út í VS Code-viðbótinni:

Að lokum sendir þjónninn skilaboð frá fulltrúa og lýkur síðan umferðinni með turn/completed. Delta-atburðir skilaboða frá fulltrúa senda hluta skilaboðanna aftur þar til skilaboðin eru fullgerðar með item/completed.

Skilaboðin í skýringarmyndinni eru einfölduð til að auka læsileika. Ef þú vilt sjá JSON fyrir heila umferð geturðu keyrt prófunarforritið úr Codex CLI-geymslunni:

Nú skulum við skoða hvernig mismunandi viðmót viðskiptavina fella Codex inn í gegnum App Server. Við munum fjalla um þrjú mynstur: staðbundin öpp og IDE, Codex vefkeyrsluumhverfi og TUI.

Í öllum þremur tilfellum er flutningurinn JSON-RPC yfir stdio (JSONL). JSON-RPC gerir það auðvelt að búa til biðlarabindingar á því tungumáli sem þú kýst. Codex-viðmót og samþættingar við samstarfsaðila hafa innleitt App Server-biðlara á tungumálum eins og Go, Python, TypeScript, Swift og Kotlin. Fyrir TypeScript geturðu búið til skilgreiningar beint úr Rust-samskiptareglunni með því að keyra:

Fyrir önnur tungumál geturðu búið til JSON-skemabúnt og fært það inn í valinn kóðaframleiðanda með því að keyra:

Staðbundnir biðlarar pakka venjulega saman eða sækja verkvangssértæka App Server tvíundarskrá, ræsa hana sem langvarandi undirferli og halda tvíátta stdio-rás opinni fyrir JSON-RPC. Í VS Code-viðbótinni okkar og skjáborðsappinu, til dæmis, inniheldur afhenta afurðin stýrikerfissértæka Codex-tvíundarskrá og er fest við prófaða útgáfu svo viðskiptavinurinn keyri alltaf nákvæmlega þá bita sem við höfum staðfest.

Ekki er hægt að senda uppfærslur á biðlaranum reglulega fyrir allar samþættingar. Sumir samstarfsaðilar eins og Xcode aðskilja útgáfuferla með því að halda viðskiptavininum stöðugum og leyfa honum að vísa í nýrri App Server tvíundarskrá þegar þess er þörf. Þannig geta þeir tekið upp endurbætur á netþjónshliðinni (til dæmis betri sjálfvirka þjöppun í Codex-kjarnanum eða nýlega studda stillingarlykla) og innleitt villuleiðréttingar án þess að bíða eftir útgáfu á biðlaranum. JSON-RPC-viðmót App Server er hannað til að vera afturvirkt samhæft, svo eldri biðlarar geti átt örugg samskipti við nýrri netþjóna.

Codex Web notar Codex-umhverfið en keyrir það í ílátsumhverfi. Starfsmaður útvegar ílát með útteknu vinnusvæði, ræsir App Server-tvíundarskrána inni í honum og viðheldur langlífri JSON-RPC yfir stdio² rás. Vefappið (sem keyrir í vafraflipa notandans) hefur samskipti við Codex bakvinnsluna í gegnum HTTP og SSE, sem streymir verkefnaatburðum sem vinnslueiningin framleiðir. Þetta heldur notendaviðmótinu í vafranum léttu en veitir samt samræmdan keyrslutíma bæði á skjáborði og vef.

Þar sem veflotur eru skammvinnar (flipar lokast, nettengingar rofna) getur vefappið ekki verið áreiðanlegur sannleiksgjafi fyrir langvarandi verkefni. Að halda stöðu og framvindu á netþjóninum þýðir að vinnan heldur áfram jafnvel þótt flipinn hverfi. Streymisreglan og vistaðar þráðalotur gera nýrri lotu kleift að tengjast aftur, halda áfram þar sem frá var horfið og ná upp án þess að endurbyggja ástandið í biðlaranum.

Sögulega var TUI „innbyggður“ biðlari sem keyrði í sama ferli og fulltrúalykkjan og talaði beint við kjarnategundir Rust frekar en við app-þjónsamskiptareglur. Það gerði fyrstu endurtekningarnar hraðar en það gerði TUI einnig að sérstöku yfirborði.

Nú þegar App Server er til staðar, ætlum við að endurskipuleggja TUI⁠(opnast í nýjum glugga) til að nota hann þannig að hann hegði sér eins og hver annar viðskiptavinur: ræsa undirferli App Server, tala JSON-RPC yfir stdio og birta sömu streymandi atburði og samþykktir. Þetta opnar verkflæði þar sem TUI getur tengst Codex-þjóni sem keyrir á fjartengdri tölvu, heldur fulltrúanum nálægt útreikningum og heldur áfram vinnu jafnvel þótt fartölvan fari í svefn eða aftengist, á sama tíma og hún skilar lifandi uppfærslum og stýringum á staðnum.

Codex App Server verður fyrsta flokks samþættingaraðferðin sem við munum viðhalda framvegis, en það eru einnig aðrar aðferðir með takmarkaðri virkni. Sjálfgefið mælum við með að viðskiptavinir noti Codex App Server til að samþætta við Codex, en það er þess virði að skoða mismunandi samþættingaraðferðir og skilja kosti þeirra og galla. Hér að neðan eru algengustu leiðirnar til að keyra Codex og hvenær hver þeirra gæti hentað vel.

Keyrðu codex mcp-server⁠(opnast í nýjum glugga) og tengstu frá hvaða MCP-biðlara sem styður stdio-þjóna (t.d. OpenAI Agents SDK⁠(opnast í nýjum glugga)). Þetta er góður kostur ef þú ert nú þegar með MCP-byggt verkflæði og vilt nota Codex sem verkfæri sem hægt er að kalla á. Ókosturinn er að þú færð aðeins það sem MCP afhjúpar, svo Codex-sértæk samskipti sem reiða sig á ríkari lotufræði (t.d. diff uppfærslur) gætu ekki varpast hreint í gegnum MCP endapunkta.

Sum vistkerfi bjóða upp á færanlegt viðmót sem getur miðað á marga líkanaveitendur og keyrsluumhverfi. Þetta gæti verið góður kostur ef þú vilt eina abstraksjón sem samræmir marga fulltrúa. Málamiðlunin er sú að þessar samskiptareglur renna oft saman í sameiginlegt undirmengi eiginleika, sem getur gert ríkari samskipti erfiðari að tákna, sérstaklega þegar merkingarfræði verkfæra og lotu sem er sértæk fyrir þjónustuveitanda skiptir máli. Þetta svið er að þróast hratt og við búumst við að algengari staðlar muni koma fram þegar við finnum út bestu frumþættina til að lýsa raunverulegu vinnuflæði fulltrúa (færni⁠(opnast í nýjum glugga) er gott dæmi um þetta).

Veldu App Server þegar þú vilt að full Codex-virkni sé birt sem stöðugan, notendaviðmótsvænan atburðastraum. Þú færð bæði alla virkni fulltrúalykkjunnar og aðra stuðningseiginleika eins og innskráningu með ChatGPT, líkanaleit og stillingastjórnun. Helsti kostnaðurinn er samþættingarvinna, þar sem þú þarft að smíða client-side JSON-RPC binding í þínu forritunarmáli. Í reynd getur Codex hins vegar séð um mikla erfiðisvinnu ef þú gefur því JSON-skemað og skjölin. Mörg teymi sem við unnum með gátu fljótt komið á fót virkri samþættingu með Codex.

Léttur, skrifanlegur CLI-hamur fyrir einstök verkefni og CI-keyrslur. Það er gott fyrir sjálfvirkni og leiðslur þar sem þú vilt að ein skipun keyri til enda án gagnvirkni, streymi skipulögðum frálögum fyrir skráningar og ljúki með skýru merki um árangur eða bilun.

TypeScript-safn til að forritunarlega stjórna staðbundnum Codex-fulltrúum innan eigin forrits. Það er best þegar þú vilt innbyggt safnaviðmót fyrir netþjónsverkfæri og verkflæði án þess að þurfa að smíða sérstakan JSON-RPC biðlara. Þar sem það var sent út fyrr en App Server, styður það nú færri tungumál og minna umfang. Ef forritarar hafa áhuga gætum við bætt við fleiri SDK sem umlykja App Server samskiptaregluna svo teymi geti náð yfir stærra svæði prófunarrammans án þess að þurfa að skrifa JSON-RPC bindingar.

Í þessari færslu deilum við því hvernig við nálgumst hönnun nýs staðals fyrir samskipti við fulltrúa og hvernig á að breyta Codex-umgjörðinni í stöðuga, viðskiptavæna samskiptareglu. Við fjölluðum um hvernig App Server gerir Codex-kjarnann aðgengilegan, leyfir viðskiptavinum að stjórna allri fulltrúalykkjunni og knýr fjölbreytt úrval viðmóta, þar á meðal TUI, staðbundnar IDE-samþættingar og keyrsluumhverfi vefsins.

Ef þetta kveikti hugmyndir um að samþætta Codex í þitt eigið verkflæði þá er þess virði að prófa App Server. Allur frumkóðinn er í Codex CLI opnum hugbúnaðar geymslu⁠(opnast í nýjum glugga). Deildu ábendingum þínum og beiðnum um eiginleika. Við erum spennt að heyra frá þér og halda áfram að gera fulltrúa aðgengilegri fyrir alla.