Most Cordis

Most vestavuje DeepSeek Harness (DSH) do backendu Libre WebUI. DSH běží jako strom pluginů v hostovaném runtime Cordis, takže schopnosti přicházejí jako služby Cordis místo importovaných modulů.

Most je ve výchozím stavu vypnutý. Popsané chování nastane až po povolení operátorem; viz Konfigurace Cordis.

Proč most místo přímé integrace

Přímý import balíčků DSH do služeb by byl kratší, ale horší. Modul by se stal závislostí při kompilaci; záměna adaptéru, smyčky agenta nebo odstranění modulu by vyžadovaly úpravu a nové nasazení Libre WebUI.

Most závislost obrací: Libre WebUI spoléhá na abstraktní kontrakt a dokument kompozice určuje jeho implementaci:

• Jiný cíl bez sestavení. YAML kompozice dovoluje změnit poskytovatele konfigurací.
• Nastavení schopností. Každá je řádek Loaderu; změny operátorovy kompozice platí při příštím startu hostitele.
• Čisté odstranění. Kořenové vlákno vlastní všechny služby, posluchače a efekty. Jeho uvolnění je všechny odebere a umožní zastavit modul bez restartu aplikace.

Vrstvy

Konkrétní závislosti DSH zůstávají v backend/src/cordis/dsh/. Cesty a aplikační služby používají kontrakty mostu. Ovladač Work má vlastní kompozici v paměti a nikdy nenačítá hostitelské souborové pluginy.

Kontrakty

Kontrakt je v backend/src/cordis/contracts.ts. Záměrně popisuje jen tvary potřebné API Libre WebUI, bez slovníku vnitřního modulu.

Kontrakt	Účel
DshEngine.status()	Životní cyklus služeb (pending / ready / failed)
DshEngine.modelConfiguration()	Výchozí model a poskytovatel aktivní kompozice
DshEngine.listSessions()	Přehled relací od nejnovější
DshEngine.getSession(id)	Relace s promítnutými zprávami
DshEngine.createSession(opts)	Rezervovat ID a pracovní adresář
DshEngine.updateSessionSettings(id, settings)	Uložit skutečný model a nativní režim souborových oprávnění při nečinnosti
DshEngine.decideApproval(id, approvalId, decision)	Rozhodnout nativní schválení pro příslušnou relaci
DshEngine.deleteSession(id)	Ukončit relaci a uvolnit agenta
DshEngine.listAgents()	Živí kořenoví a podřízení agenti
DshEngine.listTools()	Registrované nástroje viditelné modelu
DshEngine.sendMessage(id, txt)	Spustit tah a vrátit streamovací handle
DshEngine.cancel(id)	Zrušit probíhající tah

Publikuje se jako služba Cordis libreDshEngine; spotřebitel čte ctx.get('libreDshEngine'), neimportuje modul mostu.

EngineStreamChunk přenáší text, reasoning, tool-call, tool-result, approval-request, approval-decision, error a done. Živé rámce jsou směrovány vlastnícím agentem a relací; odpovídající trvalá zpráva se nevysílá podruhé. sendMessage vrací handle, jehož subscribe přehraje už vyslaná data, takže rychlý první token nezmizí před připojením HTTP posluchače.

Průběh jednoho tahu chatu

NDJSON se používá místo WebSocketu, protože tah je jediná posloupnost server–klient po požadavku. Ponechání na POST odstraní další handshake, ticket a protokol obnovy spojení a drží tah v jediném autentizovaném požadavku.

DONE a PENDING

Cordis aktivuje plugin při dostupných závislostech, proto řádek prochází i stavy před spuštěním. Záměna následujících pojmů bývá hlavní příčinou tichého modulu.

Stav řádku Loaderu. Řádek prochází PENDING → LOADING → ACTIVE nebo FAILED. Chybějící služby znamenají nekonečné čekání, nikoli chybu; neúplná kompozice tak může startovat a nic neposkytovat.

Dostupnost služby. Hostitel očekávané služby hlásí takto:

Stav	Význam	Příčina
pending	Neregistrovaná v kontextu	Poskytující řádek se neaktivoval nebo je vypnutý
ready	Registrovaná a použitelná	Poskytující řádek se aktivoval
failed	Deklarovaná, ale nepoužitelná	Hlášena s řetězcem detail

host.status() uvádí dostupnost i chybějící povinné služby; GET /api/cordis/health totéž zveřejní. Chybějící povinná služba vyvolá chybu startu místo zveřejnění modulu s prázdnými odpověďmi.

Dvě snadno chybně sestavené závislosti:

• dsh-tools potřebuje systemPrompt.
• dsh-agent-loop čeká na agents, sessions, llm, tools, systemPrompt a sessionProjections.

Bez některé může fungovat úložiště relací, ale žádná zpráva nedostane odpověď.

Nastavení poskytovatele

Dodaná řádka libre-webui-llm-adapter obsluhuje poskytovatele nastavené v Libre WebUI. Výběr modelu relace na stránce modulu tento řádek nenahrazuje.

Změny kompozice platí při příštím startu. Restartujte backend nebo vypněte a zapněte Cordis, pokud správní přepínač není uzamčený. Uložené relace zůstávají ve svém úložišti a obnoví se přes aktuální kompozici.

Důvěryhodný integrační kód může přímo použít lifecycle API Loaderu. Most nenabízí endpoint na výměnu adaptéru ani automatický návrat předchozího při selhání náhrady.

Vrácení

Uvolnění kořenového vlákna odstraní vše instalované modulem. Tato vlastnická vazba zaručuje úklid:

• Služby registrované pluginy mizí s jejich vlákny.
• Odběry session/event vznikají v konstruktoru mostu a vlastní je jeho řádek.
• Most sleduje handly agentů a uvolňuje je svým efektem úklidu.
• Hostitel uvolní kořenový kontext vlastnící všechny řádky.

stopCordisHost() je idempotentní a zapojené do vypínání backendu, takže časovače a soubory se uvolní, nečekají jen na konec procesu.

Identita a trvalost relací

Stránka rezervuje při vytvoření neprůhledné ID. Při zapnuté persistenci ihned uloží hlavičku, takže restart přežije i prázdná relace. Most uvádí živé i uložené relace, čte logy validovaným API DSH a pokračuje na stejném ID. Nové uživatelské zprávy vznikají identifikovaným konstruktorem DSH.

Odstranění nejprve zruší a uvolní agenta, potom odstraní soubor. Adaptér místního JSONL ověřuje úložiště a cesty relací a odmítá symlinky. Vlastní backend bez mazacího adaptéru vrátí chybu místo tvrzení, že data odstranil.

Zrušení dosáhne nativního agenta, požadavku modelu i nástrojů. Odpojení klienta ruší tah; dokončené zprávy zůstávají čitelné. Omezený replay buffer zachová rychlý výstup před připojením čtenáře.

Hostitelský modul je funkce solo s jedinou replikou. Team nemůže načíst místní JSONL runtime. Sandboxed Work používá stávající SQL úložiště úloh, běhů, zpráv, schválení a událostí.

Rozhraní HTTP

Metoda	Cesta	Účel
GET	/api/cordis/health	Stav mostu; bez autentizace
GET	/api/cordis/sessions	Seznam relací
POST	/api/cordis/sessions	Vytvořit relaci
GET	/api/cordis/sessions/:id	Číst relaci i zprávy
DELETE	/api/cordis/sessions/:id	Ukončit relaci
POST	/api/cordis/sessions/:id/messages	Poslat zprávu a streamovat NDJSON
POST	/api/cordis/sessions/:id/cancel	Zrušit aktivní tah
GET	/api/cordis/agents	Seznam živých agentů
GET	/api/cordis/tools	Seznam registrovaných nástrojů

Vše mimo /health vyžaduje autentizovanou relaci správce. Není-li most připraven, odpoví 503 a code hodnotou CORDIS_DISABLED, CORDIS_STARTING nebo CORDIS_UNAVAILABLE.

Stránka frontend/src/pages/CordisPage.tsx je dostupná na /cordis z panelu. Uvádí relace a nástroje, vytváří relace a streamuje tah do přepisu. Při vypnutí nebo selhání ukazuje důvod místo prázdného seznamu, protože jinak vypadají „žádné relace“ a „žádný modul“ stejně.

Klient frontend/src/utils/api/cordisApi.ts používá jen toto API, bez backendových typů a @deepseek-ai/*. Modul tak lze vyměnit bez frontendové změny. sendMessage(sessionId, text, { onChunk }) čte tah; klient sám parsuje JSON po řádcích a zvládá rozdělení rámců mezi síťová čtení.

Ovládání chatu modulu

Stránka zobrazuje Markdown, tabulky a zvýrazněný kód s kopírováním odpovědí i kódu. Systémové prompty a vložený kontext jsou ve sbaleném Kontext relace, ne jako zprávy uživatele. Zpřístupněné uvažování a nástroje mají vlastní rozbalovací části; výsledky po obnovení stále odpovídají správné operaci.

Vyberte skutečný model poskytovatele z místních či pluginových modelů přihlášeného správce, včetně identity poskytovatele. Persony a agenti Chat nejsou ID modelů a své instrukce do této konverzace nevkládají. Staré chybné persona-model hlavičky se ignorují jako výchozí tip, bez změny uloženého logu.

Relace má Pouze čtení nebo Zápis v pracovním prostoru, vynucený DSH i kanonickou hranicí mostu. Editor ukazuje rozsah. Nastavení je nativní uložená událost a přežívá restart; za aktivního tahu se měnit nesmí.

Nativní žádost o vyšší práva se připojí k operaci jako Povolit jednou / Odmítnout. Souhlas platí jen pro ni a nemění trvalý režim. Zastaralou či zrušenou žádost schválit nelze; Chat bez UI odmítá otázky, které nemůže ukázat. Most nedává neomezený přístup k hostiteli.

Další administrační endpointy:

Metoda	Cesta	Účel
GET	/api/cordis/models	Dostupné modely a aktuální skutečný výchozí model
PATCH	/api/cordis/sessions/:id/settings	Nastavit model nebo oprávnění relace
POST	/api/cordis/sessions/:id/approvals/:approvalId	Rozhodnout žádost pomocí allowed-once nebo rejected

Použití modulu v Chat

Zapněte Přístup a zásady → Modely agentů CLI a Modul Cordis. Správci pak v Chat zvolí DeepSeek Harness. Každý požadavek má novou dočasnou relaci s dodaným přepisem. Autoritou zůstává databáze Chat; nesouvisející konverzace, větve a opakované pokusy nesdílejí skrytou historii. Dočasný log se po dokončení či zrušení smaže a na stránce modulu není vidět.

Standardní kompozice nabízí také DeepSeek Harness · model (poskytovatel) ve skupině Agenti. Uložená ID obalují stejné kvalifikované cesty: dsh:lwui:ollama:<model> nebo dsh:lwui:plugin:<plugin>:<model>, s procentovým kódováním částí. Volitelné místní nativní připojení DSH přidává dsh:native:<provider>:<model> ze živého katalogu s konfigurací a údaji jeho poskytovatele.

Instalujte samostatný balíček Apache-2.0 z libre-webui/dsh-native-provider, nebo připravte bundle z distribuce LWUI. Oba používají @libre-webui/dsh-native-provider a drží klíče v DSH. Vyžadují stejný Unix hostitel i účet OS a soukromý Unix socket; aplikace sdílející účet neizolují. Nabízejí pouze inferenci bez nativních relací agenta a nástrojů. Instalaci, restarty profilu, aktualizace a odebrání popisuje konfigurace. Nedostupný model nebo připojení selže bez změny poskytovatele. Nativní volání jsou ve Využití poskytovatelů s modelem, hlášenými tokeny, latencí a výsledkem.

Základní profil dsh zachová výchozí model aktivní kompozice. Vlastní adaptéry nabízejí jen základní profil, ne nepodporované přepsání poskytovatelů LWUI.

Názvy a souhrny uvažování převedou volbu DSH na podkladového poskytovatele a požádají přímo o text, bez agenta a nástrojů. Základní profil čte nastavení běžícího modulu včetně řádku mostu, neodhaduje katalog. Vlastní adaptéry potřebují výslovný model úloh Ollama nebo pluginu. Nedostupná volba vede k běžné chybě či místnímu náhledu názvu, ne požadavku jinému poskytovateli.

Používají se údaje a preference autentizovaného správce, nikdy implicitně jiného správce. Nastavený prostor Cordis je výchozí; Chat jej nenahradí domovskou složkou serverového uživatele.

Work v sandboxu

Po zapnutí Cordis nabízí Work samostatný Engine s volbou Libre WebUI nebo DeepSeek Harness. Názvy modelů a poskytovatelů zůstávají běžné. Pro LWUI se ukládá dsh:<model>; nativní volba ukládá providerType: dsh, přesný ID poskytovatele a původní model. Kontroly nástrojů a přístupu platí dál; nativní údaje navíc vyžadují aktivního správce.

Běh vytváří izolovanou smyčku DSH v paměti. Adaptér dostává aktuální přepis, metadata, obrázky a schémata nástrojů Work. Těla nástrojů pouze čekají na výsledky Work; nečtou hostitelské soubory ani nespouštějí hostitelské procesy.

Work ověřuje argumenty, žádá schválení, vykonává v pracovním runtime, zapisuje výsledky a replay stav do SQL, uplatňuje rozpočty a publikuje události. Odmítnutí vrací běžný výsledek odmítnutí. Zrušení uvolní DSH a uklidí kontejner obvyklým postupem. Po obnově workeru dostane nový ovladač obnovený kontext bez opakování dokončených účinků.

Není potřeba hostitelská kompozice ani JSONL. Platí pravidla Work pro Docker/Kubernetes a nasazení, včetně sdílené persistence team režimu.

Bezpečnostní hranice

Stránka modulu a hostitelský agent Chat jsou jen pro správce. Relace jsou sdílená správní konzole včetně systémových promptů, ne pracovní prostor uživatele. Běžné účty je přes API nesmějí číst, vytvářet, měnit ani rušit.

Dodané souborové nástroje omezují čtení i zápis kanonickými cestami a rozlišením symlinků na nastavený prostor. Pracovní adresář relace musí zůstat uvnitř. Platí nativní politika změn DSH i jednorázové souhlasy. Pluginy operátora jsou důvěryhodný serverový kód a mohou rozšířit schopnosti. Schválení modulu jsou oddělená od schvalování a kontejnerů Work.

Ovladač Work je samostatný: nenačítá hostitelské pluginy filesystemu, shellu ani persistence a vykonává pouze přes autorizaci a sandbox Work. Vzdálení poskytovatelé zůstávají volitelní a používají nastavenou cestu vybraného účtu.