Słownik

Encje podstawowe

Agent: Pracownik AI z tożsamością, rolą, skillami i adapterem. Należy do dokładnie jednego obszaru roboczego. Główny aktor w systemie.

Adapter: Runner, który wykonuje turę agenta. Dostarczane są dwa: Control Center (wbudowany) — harness działający w procesie, który rozmawia z dostawcami modeli — oraz Claude Code przez claude -p. Cursor, Codex, Anthropic, OpenAI i pozostali to dostawcy na wbudowanym adapterze, a nie osobne CLI. Zobacz Zarządzaj adapterami i modelami.

Obszar roboczy: Najwyższy poziom izolacji. Grupuje agentów, repozytoria, przestrzenie, zgłoszenia, pamięć i potoki. Izolacja jest strukturalna, a nie konwencjonalna: każdy obszar roboczy ma własny plik SQLite (<dataDir>/<workspaceId>/workspace.db), więc odczyt między obszarami roboczymi się nie skompiluje. Każda trasa w aplikacji ma prefiks /workspaces/:workspaceId — zobacz mapę tras.

Host kodu: Usługa hostująca kod — GitHub, GitLab lub Bitbucket Cloud. Host kodu jest właściwością każdego repozytorium, odczytywaną z jego zdalnego origin przy rejestracji, i wybiera adapter API oraz poświadczenie tego repozytorium. Jeden obszar roboczy może zawierać repozytoria na wszystkich trzech; powierzchnie agregujące (skrzynka, kolejka PR-ów) rozchodzą się po każdym reprezentowanym hoście kodu i scalają wyniki, izolując awarie, dzięki czemu nieosiągalny host kodu nigdy nie opróżnia pozostałych. Hosty kodu różnią się obsługiwanymi funkcjami — zobacz tabelę możliwości w Połącz host kodu.

Repo: Repozytorium Git zarejestrowane w jednym obszarze roboczym. Przypisane do obszaru roboczego — ten sam checkout zarejestrowany w dwóch obszarach roboczych to dwa niezależne wiersze z dwoma identyfikatorami; tożsamość repozytorium między obszarami roboczymi wyznacza ścieżka w systemie plików, nigdy identyfikator. Rejestracja wymaga drzewa roboczego git, którego zdalne origin wskazuje na obsługiwany host kodu. Każde repozytorium niesie swój forge (github / gitlab / bitbucket), który wybiera używany dla niego adapter API i poświadczenie.

Izolowane repozytorium: Worktree przypisany do obszaru roboczego, utworzony z zarejestrowanego repozytorium. Copy-on-write przez rift wszędzie tam, gdzie ten natywny jest dostarczany; git worktree w Windows. Tworzony dla każdej przestrzeni — każda rozmowa w tej przestrzeni dzieli jeden checkout — więc agenci nigdy nie modyfikują źródła.

Przestrzeń: Kontener współpracy przypisany do obszaru roboczego, z uczestnikami ludzkimi i agentami, zapisanym Mode, statusem tworzenia i wartością SpaceKind (topic / agentPeer / system / pr / slack), która decyduje o podziale na sekcje, wyciszaniu, oznaczaniu plakietką i usuwaniu. Jest właścicielem izolowanych worktree współdzielonych przez jej rozmowy (copy-on-write przez rift; git worktree w Windows).

Rozmowa: Jeden strumień wiadomości wewnątrz przestrzeni, z własnym identyfikatorem, historią i kontekstem uruchomienia agenta. Rozmowy w przestrzeni są równorzędne — nie ma strumienia głównego ani „nadrzędnego”. Każda otwiera się jako karta edytora; stan nieprzeczytanych przestrzeni zbiera je wszystkie.

Wątek: Rozmowa z ustawionym anchorMessageId: zakotwiczona w jednej wiadomości rozmowy siostrzanej w tej samej przestrzeni, z nowym kontekstem agenta zainicjowanym tą wiadomością kotwiczącą. Tylko jeden poziom głębokości — wątki nigdy nie kotwiczą się w wątkach.

Zgłoszenie: Agregat jednostki pracy. Neutralny wobec dostawcy: local domyślnie, z adapterami synchronizacji dla Linear, GitHub Issues, Jira Cloud i ClickUp — choć żadna powierzchnia w aplikacji nie tworzy połączenia synchronizacji. Obsługuje hierarchię, powiązania i delegowanie. Przypisanie do agenta rejestruje własność i niczego nie uruchamia; przypisanie do zespołu jest wyjątkiem (TeamRoutingService uruchamia lidera).

Potok: Przepływ pracy oparty na DAG, który łączy kroki (uruchomienie agenta, skrypty, warunki). Definiowany przez szablony; wykonywany jako uruchomienia.

Obiekty wartości

AgentRole: Wyliczona rola (CEO, coder, reviewer, QA, designer, security, devops, PM, general). Określa personę, dostęp do pamięci i hierarchię.

AgentSkills: Zbiór identyfikatorów skilli niewrażliwy na wielkość liter, który wstrzykuje istotny kontekst do promptów w momencie uruchomienia.

Źródło skilla: Repozytorium GitHub zarejestrowane w obszarze roboczym jako katalog skilli. Z założenia niezaufane: metadane repozytorium służą tylko do wyświetlania, a każda instalacja przechodzi przez bramkę skanowania z zasadą fail-closed, zanim jakakolwiek treść trafi na dysk lub do promptu. Zobacz Instaluj i zarządzaj skillami.

skills-lock.json: Manifest zainstalowanych skilli dla danego obszaru roboczego: dla każdego z nich repozytorium źródłowe, ścieżka w repozytorium, commit, do którego jest przypięty, oraz zbiorczy hash treści. Instalacje, aktualizacje i deinstalacje utrzymują go w aktualnym stanie; verify_skills sprawdza go względem dysku.

Brama uruchomień agentów: Punkt końcowy na pętli zwrotnej w cc_server, który stosuje politykę akcji wewnątrz sandboxa agenta. Każdy push agenta do GitHuba jest do niego kierowany, sprawdzany regułą Push do zdalnego repozytorium i przekazywany z tokenem zapisu, którego agent nigdy nie posiada; polecenia Bash Claude Code są sprawdzane przez hook w tym samym punkcie końcowym. Zobacz Sandbox i bezpieczeństwo.

Tryb: chat, plan, review lub orchestrate. Przechowywany dla każdej przestrzeni, więc jeden agent może działać w różnych trybach w różnych przestrzeniach; każda rozmowa w przestrzeni dzieli ten sam tryb. Steruje promptem systemowym, regułami zapisu sandboxa i listą dozwolonych narzędzi MCP. Pole tworzenia wiadomości oferuje tylko chat, plan i orchestrate; chat ma etykietę „Agent”.

SandboxBackend: microvm (odizolowana maszyna wirtualna — jedyny backend z granicą jądra, stosowany do terminali interaktywnych), native (Seatbelt w macOS, bubblewrap w Linuksie i WSL2) lub none. Sondowany raz przy starcie; native jest stosowany do uruchomienia agenta, gdy jest dostępny, otaczając CLI Claude Code i narzędzie bash harnessu. Windows nie ma natywnego backendu, a Linux wymaga bwrap i socat, więc uruchomienia tam są nieotoczone; --sandbox off świadomie z tego rezygnuje.

Rig: Jednorazowa maszyna, którą agent steruje w czasie rzeczywistym — odizolowana przeglądarka lub pulpit Linuksa, zarządzany przez hosta emulator Androida lub Symulator iOS, albo odizolowany terminal. Obserwowana na żywo przez własny tor w pełnej rozdzielczości, z przejmowaniem wymuszanym po stronie serwera. Przypisana do rozmowy, dzięki czemu karta człowieka i wywołania agenta browser_use / computer_use / mobile_use / ios_use kierują do jednej domyślnej maszyny. Zobacz Rigi i izolacje.

Izolacja: Silniejsza granica riga oparta na VM — granica jądra, jednorazowy dysk nakładkowy, brama sieciowa domyślnie odmawiająca i broker poświadczeń. Rigi Android i iOS są jednorazowe, ale korzystają z sieci zarządzanej przez hosta i nie roszczą sobie tej granicy. Sterowanie dowolnym rigiem używa klasy guardrail enclosureControl.

RunCost: Zestawienie tokenów i kosztów (tokeny wejściowe, tokeny wyjściowe, szacowany koszt w centach) dla jednego uruchomienia agenta.

WakeReason: Powód uruchomienia agenta. Sześć wartości: wiadomość użytkownika, przypisanie zgłoszenia, ponowne uruchomienie naprawcze po awarii, ukończenie zgłoszenia podrzędnego, zaplanowany heartbeat kontynuacji i krok potoku.

Porty

SandboxPort: Zarządza cyklem życia sandboxa (probe, launch, events, exec, destroy).

CredentialBrokerPort: Wystawia ograniczone poświadczenia na potrzeby uruchomienia sandboxa — tylko do odczytu dla środowiska agenta, z prawem zapisu tylko dla ścieżki push po stronie serwera — i unieważnia je przy zamykaniu.

GitRepoInspectorPort: Wyodrębnia metadane (właściciel, repozytorium, gałąź) ze ścieżki lokalnego repozytorium Git.

EmbeddingPort: Tworzy wektory osadzeń tekstowych o jednostkowej normie na potrzeby wyszukiwania semantycznego.

NotificationPort: Pokazuje natywne powiadomienia pulpitu, respektując bramkowanie według kategorii i trasy.

TicketProviderPort: Niezależna od dostawcy granica wobec backendu zgłoszeń (create, get, list, update, transition, assign).

PipelineEnginePort: Uruchamia przebieg potoku z szablonu, odsprzęgając wywołujących od konkretnego silnika.

Usługi domenowe

AgentDispatchService: Uruchamia przebiegi agentów: tworzy izolowane repozytoria, buduje prompty, zakłada dzienniki przebiegów i zwraca strumienie zdarzeń na żywo.

TicketWorkflowService: Czysto domenowy silnik cyklu życia zgłoszeń z punktem kontrolnym mutacji przy optymistycznej współbieżności i wymuszaniem izolacji obszaru roboczego. Wymuszany przez niego graf przejść wiąże tylko agentów i automatyzację; zmiany w interfejsie inicjowane przez człowieka przekazują force: true i omijają go. Nie istnieje dyspozytor zgłoszeń dla agenta-przypisanego — uruchamianie należy do AgentDispatchService, a przypisanie zgłoszenia do agenta nie rozpoczyna przebiegu. Przypisanie zgłoszenia do zespołu jest wyjątkiem (TeamRoutingService uruchamia lidera).

PipelineEngine: Orkiestruje wykonanie przebiegu: uruchamia przebiegi, planuje kroki, zapisuje stan, obsługuje routery/joins/continue-on-fail i wznawia przebiegi w toku po restarcie.

PipelineTriggerDispatcher: Subskrybuje zdarzenia domenowe i automatycznie uruchamia pasujące przebiegi potoków dla włączonych wyzwalaczy.

MemoryAccessPolicy: Rozstrzyga i egzekwuje uprawnienia roli agenta do pamięci w domenach.

HarnessCostCalculator: Wycenia zużycie tokenów wbudowanego harnessu na RunCost z katalogu models.dev. Uruchomienie zapisuje to zestawienie w dzienniku przebiegu.

BudgetEnforcementService: Oblicza miesięczne wydatki na agenta i blokadę przed uruchomieniem (checkInvocationBlock). Tę blokadę uwzględniają wyłącznie rekoncyliatory odzyskiwania (OrphanRunReaper, StrandedTicketReconciler), nigdy zwykłe uruchomienie przez użytkownika lub agenta.

BudgetGovernanceService: Ocenia miesięczne wydatki na agenta po każdym przebiegu — miękki próg zapisuje incydent ostrzegawczy; wyczerpanie zapisuje incydent twardy i przełącza cykl życia agenta na paused.

Zdarzenia

DomainEventBus: Procesowa magistrala publikowania/subskrypcji z rozgłaszaniem do komunikacji między funkcjami. Zdarzenia są typowane; subskrybenci konsumują strumienie on<T>().

DomainEvent: Interfejs bazowy. Każde zdarzenie ma occurredAt. Kluczowe kategorie: obszar roboczy/agent, PR/recenzja, wiadomości, zgłoszenia, potok, spotkania/kalendarz, tożsamość, rigi, obserwowalność.

Spotkania i kalendarz

Spotkanie: Lokalnie nagrywana i transkrybowana sesja spotkania. Przechwytuje dźwięk mikrofonu i systemu, transkrybuje na urządzeniu wybieralnym modelem ASR (domyślnie Parakeet TDT v3; alternatywy to Parakeet TDT v2, Whisper large-v3-turbo i Whisper base.en), rozdziela mówiących i podsumowuje w notatki, zadania i decyzje. Wybrany model ASR jest wymuszenie instalowany przy starcie, a operacje nagrywania ożywają po jednym restarcie. Przypisane do obszaru roboczego; pozostaje na maszynie.

MeetingSegment: Jedno transkrybowane okno dźwięku, oznaczone mówiącym (me/them), z etykietą diaryzacji i przesunięciami w milisekundach.

MeetingActionItem / MeetingDecision: Ustrukturyzowane wyniki wyodrębniane przez potok podsumowania i przechowywane jako osobne wiersze. Zadania mogą być powiązane ze zgłoszeniem.

CalendarEvent: Zsynchronizowany wpis Google Calendar przypisany do obszaru roboczego i połączonego konta. Różni się od spotkania: wydarzenie to zaplanowane zobowiązanie; spotkanie to nagrana sesja. Powiązane jeden do jednego przez MeetingCalendarLink.

CalendarAccount: Połączone konto Google, dla danego obszaru roboczego i adresu e-mail. Tokeny odświeżania OAuth są przechowywane po stronie serwera jako klucze google_* w <dataDir>/secrets.json i nigdy nie trafiają do klienta; przepływ z kodem urządzenia kończy się na serwerze. Flaga authExpiredAt steruje banerem ponownego połączenia.

Pojęcia architektoniczne

Clean Architecture: Reguła zależności: Presentation → Application/Providers → Domain ← Infrastructure. Domena nie ma żadnych importów infrastruktury.

Porty i adaptery: Domena definiuje abstrakcyjne interfejsy (porty); infrastruktura dostarcza konkretne implementacje (adaptery). Korzeń kompozycji je wiąże.

Współdzielony kernel: Encje, obiekty wartości, porty i usługi z core/domain/ współdzielone przez 3 lub więcej funkcji.

Feature-first: Kod jest zorganizowany według domeny biznesowej (agenci, potoki, wiadomości), a nie według warstwy technicznej.

Wieloosobowość, tożsamość i tempo

Podmiot: Zapieczętowana wartość jednocząca ludzi i agentów w jedną abstrakcję aktora — UserPrincipal(userId) lub AgentPrincipal(agentId). Każda wiadomość, zgłoszenie, recenzja, plan i dziennik przebiegu są przypisywane przez Podmiot.

Użytkownik: Tożsamość ludzka, przechowywana w global.db, a więc globalna między obszarami roboczymi. Podmiot, który tworzy obszar roboczy, staje się jego właścicielem — wpisanym w Workspace.ownerUserId wraz z wierszem członkostwa o roli właściciela w tej samej operacji. Pozostali dołączają przez zaproszenie lub SSO.

WorkspaceMember / WorkspaceRole: Wiersz członkostwa wiążący użytkownika z obszarem roboczym w danej roli (owner / admin / member / viewer / guest). Członkostwo — a nie klucz parowania — jest granicą dostępu. Uprawnienia na poziomie poszczególnych repozytoriów nie pozwalają członkostwu przewyższyć uprawnień w hoście kodu.

ParticipantPresence: Ulotna obecność Principal (status, położenie, kursor, pisanie, status agenta na żywo i bieżący koszt). Nigdy nie jest zapisywana; hubem jest serwer; filtrowana według uprawnień do repozytorium przed rozgłoszeniem.

Tryb podążania: Kliknij awatar, aby jechać za jego widokiem, dopóki nie wykonasz działania, a potem się odłącz. Działa dla ludzi i dla agentów („obserwuj agenta przy pracy”).

Pokrętło autonomii: Sterowanie dla danego obszaru roboczego i agenta — propose-only / act-with-approval / act-freely — zaimplementowane jako nazwany profil nad magazynem guardraili akcji.

ActionClass: Zamknięty zbiór 13 klas efektów (fileDelete, gitPush, prCreate, networkEgress, processSpawn, enclosureControl, …). Każde narzędzie modyfikujące deklaruje swoje klasy; silnik guardraili rozstrzyga allow / prompt / deny dla danego zakresu (przestrzeń > agent > obszar roboczy > preset trybu > wbudowany domyślny).

WriteLedger / klucz idempotencji: Każda mutacja niesie wygenerowany po stronie klienta klucz idempotencji (UUIDv7, dla danej akcji logicznej). Rejestr przypisany do obszaru roboczego deduplikuje przed uruchomieniem handlera; powtórzenie zwraca identyczny co do bajtu wynik oryginalny. Z założenia czyni ponowne połączenie i pracę wielu klientów bezpiecznymi.

Skrzynka potrzeb: Kolejka obejmująca wszystkie filary z surową regułą — pozycja pojawia się tylko wtedy, gdy coś blokuje (agenta, scalenie, synchronizację) lub wprost prosi operatora.

Plan Studio: Interaktywna powierzchnia planowania — edytowalne plany jako typowany DAG, z kosztem, czasem i ryzykiem na krok oraz częściowym zatwierdzaniem.

Obliczenia recenzji: Obliczenia recenzji PR-a po stronie serwera (kohorty wyprowadzone z grafu, typowane diagramy, różnice wizualne, różnice kontraktu API, bramki na wielu osiach), udostępniane przez review_studio.* i wliczane do karty Recenzja.

Przestrzeń recenzji: Jedyna przestrzeń stojąca za PR-em (tryb review, rodzaj pr), tworzona idempotentnie i powiązana z PR-em przez ReviewSpaceAssociation. Każdy recenzent składa w niej ustalenia, co czyni je porównywalnymi; jej izolowany worktree ma PR wyewidencjonowany na jego czubku.

Węzeł recenzji: Ustrukturyzowana jednostka ustalenia z recenzji AI: rodzaj (bug, suggestion, recommendation, question, ticket), priorytet P0–P3, trójka triażu kategoria/istotność/nakład, kotwica pliku i linii, opcjonalna sugerowana poprawka i ocena pewności. Zgłaszany przez add_review_node; werdykt jest obliczany z węzłów, nie z prozy.

Consensus-ready: Status węzła recenzji osiągany tylko wtedy, gdy ustalenie potwierdzi recenzent partnerski — agent nie może potwierdzić własnego. Przycisk Opublikuj na GitHubie na karcie Recenzja wysyła każde pozostałe otwarte ustalenie (selection: all_open); narzędzie MCP publish_review_to_github nadal domyślnie ogranicza się do ustaleń potwierdzonych przez partnera.

Poziom recenzji: Zasada obszaru roboczego (light, balanced, thorough) regulująca, którzy recenzenci są rozsyłani (tylko inżynier; +qa+architekt; +security+perf) i gdzie pojawiają się ustalenia poniżej progu. Nigdy nie usuwa ustalenia.

Oś recenzji: Jedna z pięciu linii oceny w recenzji: correctness, security i testGap pochodzą z ustaleń recenzentów; visual i apiContract są deterministyczne. Osie objęte bramką wliczają się do werdyktu i mogą go tylko zaostrzyć — bramka partial lub unavailable wstrzymuje werdykt, zamiast go przepuścić.

Werdykt recenzji: ship, hold lub block. Każde ustalenie P0 z pewnością ≥ 0,7 blokuje; każde inne P0 lub dowolne P1 wstrzymuje; w przeciwnym razie ship. Oś objęta bramką, która nie przechodzi, wymusza block i nie mogą jej przegłosować ustalenia.

Flota i ewaluacje

cc_worker: Bezgłowa binarka wykonawcy floty w czystym Darcie. Paruje się z cc_server, deklaruje możliwości swojego hosta, pobiera dzierżawione zadania, wykonuje je i strumieniuje zdarzenia procesu z powrotem. Nie przechowuje żadnego trwałego stanu — jeden autorytatywny serwer, N bezmyślnych kończyn.

JobSpec: Typowana specyfikacja wszystkiego, co wykonywalne (uruchomienie agenta, krok potoku, indeks kodu, render golden, benchmark, wsad ewaluacji).

Zestaw ewaluacyjny: Definicja ewaluacji przypisana do obszaru roboczego (prompt, docelowy agent i tryb, oceniający). Pięć startowych zestawów jest zasiewanych przy tworzeniu obszaru roboczego; Obserwowalność → Jakość je wyświetla.

Wdrażanie i klienci

Architektura cienkiego klienta: Żaden klient nie otwiera bazy danych; bezgłowy proces cc_server jest właścicielem danych i udostępnia je przez RPC po WebSocket. Każdy klient (desktopowy, webowy, telefoniczny) jest rendererem nad tym jednym połączeniem RPC.

cc_server: Bezgłowa binarka serwera (czysty Dart, bez silnika Flutter). Jest właścicielem bazy Drift/SQLite, udostępnia repo-RPC po WebSocket i uruchamia usługi działające w tle (potoki, MCP, rekoncyliatory).

ServerConnectionMode: Sposób, w jaki pulpit łączy się ze swoim serwerem — local (uruchomienie cc_server na tej maszynie, wartość domyślna) lub remote (połączenie z serwerem gdzie indziej). Klient webowy jest zawsze remote.

RemoteRpcClient: Niezależny od transportu klient JSON-RPC, którego każdy cienki klient używa do rozmowy ze swoim serwerem — przez WSS, pętlę zwrotną lub przekaźnik brokera.

Zakres obszaru roboczego na wywołanie: Serwer jest bezstanowy — nie ma przypisania obszaru roboczego do sesji, więc wielu klientów na jednym serwerze nigdy nie dzieli „bieżącego obszaru roboczego”. Każde repo/call i sub/subscribe z zakresem obszaru roboczego musi zawierać workspace_id w argumentach; brakujący lub niezarejestrowany identyfikator jest odrzucany, zanim otworzy się jakakolwiek baza danych. Dostęp jest następnie bramkowany przez członkostwo i rolę w obszarze roboczym, a nie przez sesję.

cc_remote: Cienki klient telefoniczny — PWA we Flutterze na web, który zdalnie steruje flotą przez przekaźnik brokera, z polityką narzędzi domyślnie odmawiającą.

cc_signaling_server: Bezstanowy broker przekaźnika WebSocket hostujący pokoje dostępne na zaproszenie — prosty przekaźnik, który przekazuje tylko ramki zapieczętowane end-to-end, nie przechowuje żadnych danych aplikacji i nigdy nie widzi PSK parowania.