diff --git a/docs/wiki/sl/deployment.md b/docs/wiki/sl/deployment.md new file mode 100644 index 0000000..cf29329 --- /dev/null +++ b/docs/wiki/sl/deployment.md @@ -0,0 +1,171 @@ +--- +title: Namestitev +description: Nameščevalnik gostitelja clawdie — odkrije ZFS, pripravi podatkovne zbirke, ustvari uporabnika storitve in namesti enoto rc.d/systemd. +--- + +← [kazalo](./index.md) + +Zaboj `clawdie` je Colibrijev nameščevalnik gostitelja. Odkrije postavitev +ZFS na napravi in pripravi storitev `clawdie`. Na FreeBSD to pomeni storitev +rc.d, podatkovne zbirke ZFS in neprivilegiranega uporabnika. Na Linuxu lahko +uporablja systemd in bodisi ZFS bodisi navadne imenike. + +→ `crates/clawdie/src/main.rs` | `crates/clawdie/src/plan.rs` +→ `docs/ISO-SERVICE-LAYOUT.md` | `docs/CLAWDIE-INSTALLER-HANDOFF.md` + +## Odločitve + +### ZFS je obvezen na FreeBSD, priporočen na Linuxu + +FreeBSD ne podpira postavitve z navadnimi imeniki. Če ZFS uporabniški prostor +manjka, načrt takoj sporoči napako. Linux lahko pade na navadne imenike, če +ni imenovan noben bazen in ZFS ni na voljo, na zahtevo pa lahko ustvari svež +bazen na prostem disku. + +To ustreza produkcijskemu cilju: goli FreeBSD na zrcalnem polju ZFS RAID1. +Podpora za Linux omogoča razvoj in CI brez gostitelja ZFS. + +### Shramba je razrešena, ne nastavljena + +`clawdie plan` razreši shrambo v tem vrstnem redu: + +1. Če je podano `--pool NAME --create-pool DEVICE`, ustvari ta bazen. +2. Če je podano `--pool NAME`, uporabi ta obstoječi bazen. +3. Če ni podan noben bazen in obstaja natanko en bazen, ga uporabi. +4. Če obstaja več bazenov in noben ni imenovan, napaka. +5. Na Linuxu brez ZFS padec na navadne imenike. + +To odpravlja potrebo po ročno napisani topološki datoteki na tipičnih +enobazenskih gostiteljih, hkrati pa omogoča ekspliciten nadzor, ko je +potreben. + +→ `crates/clawdie/src/main.rs` (`pick_pool`, `validate_storage`) + +### Podatkovne zbirke ločujejo stanje od dnevnikov + +Ko je ZFS uporabljen, nameščevalnik ustvari: + +- `/clawdie` kot vsebniško podatkovno zbirko z `canmount=off` +- `/clawdie/db` priklopljeno na `/var/db/clawdie` +- `/clawdie/log` priklopljeno na `/var/log/clawdie` + +Hramba podatkovne zbirke in dnevnikov v ločenih podatkovnih zbirkah omogoča, +da posnetki, kvote in pravilniki vrtenja dnevnikov veljajo neodvisno. + +→ `crates/clawdie/src/plan.rs` (`zfs_dataset_steps`) + +### Privzeto suhi tek + +`clawdie apply` izpiše načrt in konča, razen če je podano `--yes`. `discover` +in `plan` sta samo za branje. To ščiti produkcijske gostitelje pred nenamernim +pripravljanjem. + +→ `crates/clawdie/src/main.rs` (`Cmd::Apply`) + +### Ustvarjanje bazena je varovano pred zasedenimi diski + +`--create-pool` na nepraznem disku je zavrnjeno, razen če je podano tudi +`--force`. Nameščevalnik uporablja `lsblk` na Linuxu za zaznavanje particij, +datotečnih sistemov, priklopnih točk in korenskega diska. Varovalo je +konzervativno: če je disk dvoumen, ga je treba eksplicitno vsiliti. + +→ `crates/clawdie/src/disk.rs` | `crates/clawdie/src/main.rs` (`validate_create_device`) + +### En sam neprivilegiran uporabnik storitve + +Storitev teče kot `_clawdie` na obeh platformah. Na FreeBSD je uporabnik +ustvarjen z `pw useradd -s /usr/sbin/nologin -d /var/db/clawdie`, izhodna koda +`65` (že obstaja) pa se obravnava kot preskok. Na Linuxu se uporabi `useradd +--system`. Imeniki stanja se nato chownajo temu uporabniku. + +→ `crates/clawdie/src/platform.rs` + +### Upravitelji storitev, specifični za platformo, ista specifikacija + +`Platform` je notranji trait. Izvedbi se razlikujeta samo v tem, kako +namestita in omogočita enoto: + +- FreeBSD: zapiše `/usr/local/etc/rc.d/clawdie`, uporabi `sysrc clawdie_enable=YES`. +- Linux: zapiše `/etc/systemd/system/clawdie.service`, zažene `systemctl enable --now clawdie`. + +Obe uporabljata isto `ServiceSpec` (binarna datoteka, uporabnik, podatkovni +imenik, ime storitve). Zagon `apply` na različnih platformah zato ustvari +enako postavitev datotečnega sistema in se razlikuje samo v ovoju upravitelja +storitev. + +→ `crates/clawdie/src/platform.rs` (`FreeBsd`, `Linux`) + +### Demon teče skozi nadzornika platforme + +Ustvarjeni skript rc.d za FreeBSD izvede `/usr/local/bin/colibri-daemon` skozi +`/usr/sbin/daemon -u _clawdie`, tako da nadzornik ob zrušitvi ponovno zažene +in proces pade na neprivilegiranega uporabnika. Enota systemd je preprosta +storitev z `Restart=on-failure`. + +Nameščevalnik sam ne zažene demona ali ne pripravi binarne datoteke; samo +ustvari okolje. Operater ali paketna gradnja pripravi `colibri-daemon` in nato +`service clawdie start`. + +→ `docs/ISO-SERVICE-LAYOUT.md` (rc.d prek daemon(8)) + +### Skrivnosti ne piše nameščevalnik + +Nameščevalnik se ne dotika ključev API ponudnika. Ločena datoteka — običajno +`/usr/local/etc/colibri/provider` — hrani skrivnosti in jo pred zagonom +demona prebere rc.d. To ohranja domet nameščevalnika omejen na ZFS, imenike, +uporabnike in datoteke storitev. + +→ [vault-provision](./vault-provision.md) + +### Koraki se izvajajo zaporedno in se ustavijo ob napaki + +`deploy::apply` zažene vsak `Step` po vrsti. Koraki `Run` pokličejo lupino in +padejo ob neničelnem izhodu, razen če korak navede dovoljene izhodne kode. +Koraki `WriteFile` ustvarijo starševske imenike, zapišejo datoteko in jo +chmodajo. Če katerikoli korak pade, se apply takoj ustavi in sporoči ukaz, ki +je padel, ter stderr. + +→ `crates/clawdie/src/deploy.rs` + +## Oblika načrta + +```text +clawdie plan + ├── ZFS layout (ali navadni imeniki) + │ ├── create /clawdie container + │ ├── create /clawdie/db -> /var/db/clawdie + │ └── create /clawdie/log -> /var/log/clawdie + └── service install + ├── create user _clawdie + ├── chown state dirs + ├── write service unit (rc.d / systemd) + ├── enable service (sysrc / systemctl) + └── [systemd] daemon-reload + start +``` + +## Tipična namestitev FreeBSD + +```sh +# odkrij +clawdie discover + +# predogled +clawdie plan + +# pripravi podatkovne zbirke, uporabnika in storitev rc.d +sudo clawdie apply --yes + +# zaženi, ko je binarna datoteka colibri-daemon pripravljena +sudo service clawdie start +``` + +## Navzkrižne povezave na izvajalne poti + +Po namestitvi ima storitev te poti: + +- `/var/db/clawdie/colibri.sqlite` — koordinacijska shramba SQLite +- `/var/run/clawdie/clawdie.sock` — Unix vtičnica demona +- `/var/log/clawdie/daemon.log` — dnevnik stdout/stderr +- `/usr/local/etc/colibri/` — konfiguracija in skrivnosti ponudnika + +→ [store-schema](./store-schema.md) | [operator-cli](./operator-cli.md) diff --git a/docs/wiki/sl/headroom-sidecar.md b/docs/wiki/sl/headroom-sidecar.md new file mode 100644 index 0000000..bd45985 --- /dev/null +++ b/docs/wiki/sl/headroom-sidecar.md @@ -0,0 +1,49 @@ +--- +title: Stranski vagon Headroom +description: Colibri lahko neobvezno prosi krajevni stranski vagon headroom-ai, da stisne rezultate orodij, preden dosežejo proračun žetonov. +--- + +← [kazalo](./index.md) + +Colibri lahko neobvezno prosi krajevni stranski vagon `headroom-ai`, da stisne +rezultate orodij, preden dosežejo proračun žetonov. Je ločen proces Python, ki +posluša na drugi vtičnici Unix, in je privzeto izklopljen. + +→ `crates/colibri-daemon/src/session.rs` (klicatelj) +→ `headroom-ai/` (izvedba stranskega vagona) + +## Odločitve + +### Kompresija, gnana s proračunom, ne vedno vklopljena + +Stranski vagon se pokliče samo, ko seja tvega, da bo presegla svoj proračun +— ne ob vsakem rezultatu orodja. Sprožilec je prag v sledilcu stroškov: če +bi naslednji korak presegel proračun, najprej stisni, nato obreži. Brez +stranskega vagona je zasilni izhod preprosto krajšanje. + +→ [cost-model](./cost-model.md) (stiskanje T14) + +### Unix vtičnica, ne HTTP + +Komunikacija poteka prek druge vtičnice Unix (`/var/run/headroom/headroom.sock`). +Stranski vagon sprejme surovo besedilo, vrne povzetek. Brez avtentikacije — +zaupa meji vtičnice Unix in temu, da oba procesa tečeta kot isti uporabnik. + +### Enostaven protokol — besedilo noter, besedilo ven + +Stranski vagon prejme eno vrstico JSON `{"text": "..."}`, vrne eno vrstico +JSON `{"summary": "..."}`. Brez sej, brez konteksta, brez zgodovine. Vsak +klic je brez stanja. + +### Ločen proces, ne knjižnica + +Stranski vagon teče kot neodvisen proces Python, ne kot uvoz Rust. To ga +izolira od zrušitev (če stranski vagon pade, demon nadaljuje brez njega), +izolira njegov pomnilnik (model Python je lačen) in omogoča neodvisno +posodabljanje. + +→ `headroom-ai/src/server.py` + +## Glej tudi + +- [cost-model](./cost-model.md) — kdaj se sproži stranski vagon diff --git a/docs/wiki/sl/operator-cli.md b/docs/wiki/sl/operator-cli.md new file mode 100644 index 0000000..0bfb0a9 --- /dev/null +++ b/docs/wiki/sl/operator-cli.md @@ -0,0 +1,62 @@ +--- +title: Operaterski CLI (`colibri`) +description: Binarna datoteka `colibri` je operaterski vmesnik ukazne vrstice do demona — tanek tipiziran odjemalec Unix vtičnice. +--- + +← [kazalo](./index.md) + +Binarna datoteka `colibri` je operaterski vmesnik ukazne vrstice do demona. +Je tanek odjemalec — pošilja ukaze JSON po vtičnici Unix, razčlenjuje odgovore +in jih izpisuje. Vsak podukaz CLI se preslika v en ukaz demona. Vmesnik CLI +dodaja priročnost (barvni izpis, privzetki, oblikovalci), ne poslovne logike. + +→ `crates/colibri-client/src/bin/colibri.rs` + +## Odločitve + +### Ena binarna datoteka, ena vtičnica + +Obstaja ena binarna datoteka `colibri`, ki se poveže na eno vtičnico +(`/var/run/colibri/colibri.sock` ali `COLIBRI_SOCKET`). Ni podukazov za +izbiro demona — večgostiteljske operacije gredo skozi most krmilne ravnine. +Operater izrecno usmeri na drug gostitelj (`nc 9190`), ne da bi +CLI podpiral več končnih točk. + +**Zakaj ne več profilov demona**: en demon na gostitelja je zadosten. Več +končnih točk bi v CLI vneslo stanje (`colibri --host osa status`), ki ga most +že rešuje na omrežni plasti. + +### CLI je generičen odjemalec JSON-RPC + +Vsak podukaz zgradi objekt `ColibriCommand`, pokliče +`client.request(command).await` in izpiše rezultat. Odjemalec ne ve ničesar o +pomenu kateregakoli ukaza — samo serializira in razčlenjuje. + +Oblikovalci izhodov (`print_json`, `print_table`, `print_key_value`) so čiste +funkcije nad `serde_json::Value`. Če demon doda novo polje, se samodejno +prikaže v izhodu JSON brez spremembe v CLI. + +### En ukaz na zagon, ne interaktivno + +Vsak zagon `colibri` izvede natanko en ukaz in konča. Brez lupine REPL, brez +več ukazov v eni seji. To ohranja CLI brez stanja in varnega za skriptanje: +`colibri status | jq '.data.agents'` je enako zanesljiv v cronu kot v +terminalu. + +→ `crates/colibri-client/src/bin/colibri.rs` (`main`) + +### Podukazi, specifični za tablo opravil, sledijo istemu vzorcu + +Ukazi za opravila (`create-task`, `intake-task`, `claim-task`, +`transition-task`) sprejemajo argumente CLI, ki se preslikajo v polja ukaza +JSON. Izhod je bodisi celoten objekt opravila (za `create-task`, +`intake-task`) bodisi potrditev (`claim-task`, `transition-task`). Noben +podukaz ne zahteva več kot ~3 argumentov — opravilna tabla je namenjena +dodeljevanju s strani agenta, ne ročnemu upravljanju. + +→ `crates/colibri-client/src/bin/colibri.rs` + +## Glej tudi + +- [task-board](./task-board.md) — ukazi, ki jih CLI zrcali +- [deployment](./deployment.md) — kako je nameščena binarna datoteka demona diff --git a/docs/wiki/sl/terminal.md b/docs/wiki/sl/terminal.md new file mode 100644 index 0000000..572d9e7 --- /dev/null +++ b/docs/wiki/sl/terminal.md @@ -0,0 +1,49 @@ +--- +title: Terminal — zmožnost, ne znamka +description: Zmožnost terminala kot ozka, prenosljiva abstrakcija — Kitty, ne iTerm2; ANSI, ne lastniški protokoli. +--- + +← [kazalo](./index.md) + +Colibrijeva zmožnost terminala je namenoma ozka: zajemi zaslon tmux, pošlji +tipke, beri izhod. Ne vključuje večpredstavnosti, brskalnika ali obogatenega +besedila. Izbira terminalskega odjemalca temelji na enem kriteriju: ali +protokol podpira **razširjeno poročanje tipk**, tako da lahko Glasspane +razlikuje `Enter` od `Ctrl+Enter`? + +## Odločitve + +### Kitty kot terminalski odjemalec (protokol, ne GUI) + +Colibri cilja na terminalski odjemalec Kitty zaradi njegovega protokola +razširjenega poročanja tipk — brez tega Glasspane ne more razlikovati +modifikatorskih tipk (`Ctrl+Enter` proti `Enter`), ne da bi zajel vnosno +plast. To ni predpis GUI — vsak terminalski odjemalec, ki izvaja protokol +Kitty (WezTerm, foot, Ghostty), deluje enako dobro. + +### tmux kot terminalski multiplekser (ne alternativni terminal) + +Agentske seje se izvajajo znotraj sej tmux, ker tmux zagotavlja obstojnost +seje (preživi odklop), več oken na agenta in programski vmesnik `capture-pane`, +ki ga Glasspane uporablja za zajem terminala. Tmux se vstavi med terminalski +odjemalec in agenta, ne nadomesti terminalskega odjemalca. + +### SSH terminfo — `tmux-256color`, ne `xterm-256color` + +`tmux-256color` je edina vrednost `TERM`, podprta za SSH povezave do agentov. +Ne podpira `xterm-256color`, ker zunaj tmux ta vrednost ne more poročati +razširjenih zaporedij Kitty. Terminfo se uveljavi v zanki demona za vse +povezave. + +### ANSI, ne lastniški — vendar s prehodom Kitty + +Izhod agenta uporablja ANSI ubežna zaporedja za barve in pozicioniranje +kazalke. To je univerzalno. Edina razširitev onkraj ANSI je stiskanje vnosa +tipk, kjer Glasspane potrebuje protokol Kitty za razlikovanje modifikatorjev. + +→ `crates/colibri-daemon/src/terminal.rs` + +## Glej tudi + +- [tui](./tui.md) — nadzorna plošča TUI, ki se upodablja v tem terminalu +- [operator-attention](./operator-attention.md) — zajem terminala kot signal diff --git a/docs/wiki/sl/tui.md b/docs/wiki/sl/tui.md new file mode 100644 index 0000000..9966637 --- /dev/null +++ b/docs/wiki/sl/tui.md @@ -0,0 +1,56 @@ +--- +title: Terminalska nadzorna plošča (colibri-tui) +description: Colibrijeva živa terminalska nadzorna plošča — povezuje se na Unix vtičnico demona in prikazuje agente, stanja ter pozornostna opozorila. +--- + +← [kazalo](./index.md) + +TUI je Colibrijeva živa terminalska nadzorna plošča. Poveže se na Unix +vtičnico demona, poizveduje API posnetkov (`glasspane-snapshot`) in ga +upodablja kot tabelo podoken s stanjem. Zgrajena z ratatui + crossterm za +barvni terminalski izhod. + +→ `crates/colibri-glasspane-tui/src/main.rs` + +## Odločitve + +### En zaslon, en pogled — ni navigacije po zavihkih + +TUI upodablja eno glavno tabelo s podokni in neobvezno pozornostno vrstico na +vrhu. Brez zavihkov, brez stranskih plošč, brez oken. Operater filtrira z +vnosom s tipkami (`/` za sejo, `a` za pozornost), ne s klikanjem. + +### Razporeditev glede na stanje + +Vsako podokno dobi barvo glede na `AgentState`: zelena (Working), rumena +(Blocked), modra (Done), rdeča (Error), siva (Idle). Podokna z napako že +prikazujejo rdeče besedilo. Pozornostna vrstica, tipke za skok in filter +dodajajo rdečo obrobo in inverzno ozadje na vrstice, ki potrebujejo pozornost. + +→ [operator-attention](./operator-attention.md) + +### Enovrstične vrstice podoken po meri agentov + +Vsaka vrstica podokna vsebuje: ime agenta, stanje, ID seje (skrajšan), +časovni žig zadnjega dogodka in zastavico stalled. To je minimalen nabor, ki +ga operater potrebuje za oceno agenta na prvi pogled. Prihodnje delo: površina +metapodatkov podokna za bogatejše vrstice. + +### Osveževanje — poizvedovanje, ne potiskanje + +TUI poizveduje demonov API posnetkov (`glasspane-snapshot`) vsakih 250 ms. +Brez WebSocket, brez SSE, brez potisnih obvestil med TUI in demonom. +Poizvedovanje ohranja vtičnico demona brez stanja. + +### Barve so nosilne + +`NO_COLOR=1`, ki uhaja iz sej Hermesa, bi naredil TUI neberljiv brez barv. +`main()` vsili `crossterm::style::force_color_output(true)`, da to prepreči. +To je nadzorna plošča, ne orodje za cevovod. + +→ `crates/colibri-glasspane-tui/src/main.rs` + +## Glej tudi + +- [glasspane](./glasspane.md) — avtomat stanj, ki ga TUI upodablja +- [operator-attention](./operator-attention.md) — pozornostna vrstica in tipke za skok