Ta strona jest dla osób zmieniających kod Lolly: jak silnik, powłoki i paczki narzędzi do siebie pasują, gdzie każde mieszka w repozytorium oraz zobowiązania ograniczające każdą zmianę. Jeśli chcesz wiedzieć, co robi Lolly i kto go używa, najpierw przeczytaj How Lolly works.
Dwa uzupełnienia idą głębiej. engine/README.md to mapa silnika moduł po module, generowana z kodu. Threat Model & Trust Boundaries czyta tę samą architekturę jako granice zaufania i jest stroną na każde pytanie o to, co silnik traktuje jako niezaufane.
Ogólny obraz
Narzędzia są danymi na górze. Silnik pośrodku nie wie nic o żadnej platformie. Powłoki na dole implementują jeden kontrakt, a katalogi dostarczają treść.
Jeśli da się to opisać czystymi danymi i Handlebars, należy do silnika. Jeśli dotyka DOM, systemu plików, sieci lub jakiegokolwiek API przeglądarki lub systemu operacyjnego, należy do hosta, czyli strony powłoki po stronie mostu. Silnik jest open source i nic, co zna konkretną markę lub platformę, nie trafia do silnika.
Układ repozytorium
Lolly to jedno repozytorium. Każdy poniższy katalog jest w nim zwykłym katalogiem, z wyjątkiem brands/suse, prywatnego submodułu git z paczką narzędzi i katalogiem SUSE, którego publiczny klon nie pobiera. To, które paczki czyta kompilacja, określa profil treści (profiles.json), rozwiązywany dla procesu, a nie przełączany globalnie. Build Guide ma polecenie klonowania i opis zatwierdzania zmiany wewnątrz prywatnej paczki.
| Katalog | Co zawiera |
|---|---|
engine/ | Niezależny od platformy rdzeń: loader, runtime, dane wejściowe, szablony, tryb URL, jednostki i moduły formatów |
shells/ | Aplikacja internetowa, aplikacje Tauri na komputer i urządzenia mobilne, CLI, TUI i rozszerzenie przeglądarki |
packages/ | SDK dla autorów narzędzi (@lolly-tools/core), wspólne elementy powłoki Node i renderer dokumentacji, między innymi |
community/ | Narzędzia niezależne od marki oraz wspólne paczki emoji |
brands/ | Paczki marek: lolly-demo (Lolly Demo, system projektowy, którego używa lolly.tools), lolly-start (pusty starter) i prywatna suse |
services/ | Opcjonalne usługi MCP, certyfikatów i Penpot oraz kod serwerowy, który współdzielą |
schemas/ | JSON Schema dla manifestów narzędzi, wpisów zasobów i odwołań do zasobów |
scripts/, tests/, docs/, api/ | Skrypty budowania i katalogu, zestaw testów silnika, te dokumenty i generowane paczki bezserwerowe |
Pliki silnika i powłoki, które spotkasz najpierw
engine/src/
index.ts public surface: loader, runtime, template, inputs, url-mode
loader.ts fetches and validates tool files
runtime.ts orchestrates one mounted tool, from load to export
template.ts Handlebars hydration and annotateTemplate
inputs.ts manifest to runtime input model
url-mode.ts URL to input state and back
validate.ts JSON Schema validation of manifests
compose.ts nested tool renders (composes)
embed.ts portable lolly.tools embed URLs
bridge/host-v1.ts type re-export of the @lolly-tools/core contract
shells/web/src/
main.ts boot and routing
bridge/ the web implementations of the host APIs
catalog/sync.ts boot-time catalog sync and offline cache
views/ the gallery, tool, projects, free canvas and the other views
pro/ Batch (#/batch)
shells/cli/ bin/lolly.ts (entry), src/run.ts (headless render), src/bridge.ts
shells/tui/ src/main.tsx (the full-screen app), src/bridge.tsNie ma katalogu tools/ ani catalog/ w korzeniu repozytorium. packages/node-shell/src/content-roots.ts odpowiada na pytanie "gdzie mieszka narzędzie <id>" i "gdzie jest katalog" na podstawie profiles.json, gdy się o to zapyta. Prawdziwa para tools/ i catalog/ jest zapisywana tylko w wyniku budowania, takim jak dist/, ładunek RPM lub obraz kontenera, ponieważ przeglądarka pobiera te dwie ścieżki przez HTTP.
Gdzie działa Lolly
Każda powierzchnia używa tego samego silnika i tych samych plików narzędzi.
- Aplikacja internetowa. Progresywna aplikacja internetowa, która działa offline, gdy jej service worker zapamiętał narzędzia i zasoby. Nie wymaga konta; stan żyje w IndexedDB na każdym urządzeniu. Jeden responsywny układ obsługuje komputer i telefon: na telefonie kontrolki stają się arkuszem, a kontrolki eksportu otwierają się z pływającej pigułki.
- Aplikacje na komputer i urządzenia mobilne. Pakiety Tauri tej samej aplikacji internetowej, z natywnymi oknami plików, stanem w systemie plików i pełnym użyciem offline.
- CLI.
lolly <tool-id> --input=value --output=file.pngładuje ten sam silnik w DOM bez interfejsu i zapisuje plik. To tryb URL w innym transporcie, a nie osobna implementacja. Zobacz CLI. - TUI. Pełnoekranowa, zorientowana na klawiaturę aplikacja terminalowa, która używa mostu CLI, trzyma zapisane sesje na dysku (we własnym folderze aplikacji komputerowej, gdy jest zainstalowana, a w przeciwnym razie w
~/.lolly) i uruchamia ograniczoną przeglądarkę bez interfejsu tylko wtedy, gdy format jej potrzebuje. Zobacz TUI.
signed by Lollyvector SVG131 paths~6.1k nodes158 groups1 image142 KBCheck it yourselfPobierz podpisany plik
To samo narzędzie przy szerokości telefonu nie potrzebuje drugiego układu: kontrolki stają się arkuszem u góry, a podgląd zajmuje ekran.
signed by Lollyvector SVG97 paths~3.3k nodes113 groups99 KBCheck it yourselfPobierz podpisany plik
signed by Lollyvector SVG97 paths~3.3k nodes113 groups100 KBCheck it yourselfPobierz podpisany plik
Aplikacja internetowa zawiera też Batch (#/batch, shells/web/src/pro/), siatkę w stylu arkusza kalkulacyjnego, która renderuje wiele wierszy naraz dla jednego lub wielu narzędzi; Batch i Lolly Multi-edit opisuje Batch. Settings → Capabilities mapuje wszystko, co platforma deklaruje, że potrafi.
signed by Lollyvector SVG133 paths~15k nodes185 groups1 image195 KBCheck it yourselfPobierz podpisany plik
signed by Lollyvector SVG133 paths~15k nodes185 groups1 image195 KBCheck it yourselfPobierz podpisany plik
Zobowiązania architektoniczne
Te decyzje są ustalone. Zmiana któregokolwiek z nich to poważne przedsięwzięcie, ponieważ kształtują każdą inną decyzję w bazie kodu.
1. Deklaratywne narzędzia, z imperatywnym wyjściem awaryjnym
Narzędzie to manifest (tool.json), szablon (template.html) i opcjonalny hooks.js. Manifest deklaruje dane wejściowe, nigdy szablon: dane wejściowe nie są wywnioskowane z tokenów Handlebars. Większość narzędzi to sam manifest i szablon, co pozwala je pisać osobom niebędącym programistami.
signed by Lollyvector SVG39 paths~2.6k nodes54 groups2 images43 KBCheck it yourselfPobierz podpisany plik
signed by Lollyvector SVG39 paths~2.6k nodes54 groups2 images43 KBCheck it yourselfPobierz podpisany plik
Narzędzia, które obliczają wartości, takie jak kodowanie QR czy kształtowanie wykresów, dodają hooki: nazwane funkcje cyklu życia, które runtime wywołuje z wstrzykniętym mostem możliwości. Hooki to kontrakt przenośności, a nie piaskownica bezpieczeństwa, i działają w ramach budżetu czasu. Narzędzia, których hooki są udowodnione jako wolne od globalnych obiektów strony, mają isolate: true i działają w Workerze. Tool hooks opisuje cykl życia i budżety, a Threat Model mówi, co wykonawca w stronie zawiera, a czego nie.
2. Narzędzia i zasoby to dane, nie spakowany kod
Aplikacje web i Tauri pobierają katalogi narzędzi i zasobów przy starcie, zapamiętują je i pracują z tym, co jest, więc nowe narzędzie lub zasób nie wymaga wydania aplikacji. Bajty zasobów mają sumy kontrolne SHA-256, a id i version zasobu sterują unieważnianiem pamięci podręcznej.
3. Most możliwości to jedyne API, które widzą narzędzia
Narzędzia nigdy nie dotykają DOM poza swoim szablonem, nigdy nie wywołują fetch bezpośrednio i nigdy nie czytają systemu plików. Wywołują wersjonowane metody host.*. Kanoniczna definicja kontraktu to packages/core/src/host-v1.ts, SDK dla autorów narzędzi @lolly-tools/core, więc osoba trzecia może budować na nim bez zależności od silnika; engine/src/bridge/host-v1.ts reeksportuje jego typy.
| Wymagane API | Co robi |
|---|---|
host.profile | Dane użytkownika; wypełnia dane wejściowe przez bindToProfile |
host.assets | Zapytania do katalogu, rozwiązywanie zasobów i selektor hosta |
host.state | Zapis i odczyt slotów danych wejściowych: IndexedDB w sieci, system plików w Tauri, pamięć w CLI |
host.clipboard | Zapis tekstu lub obrazu do schowka, z rozwiązaniami zastępczymi platform |
host.export | Rasteryzacja lub serializacja celu renderowania oraz ścieżka transformacji plików na urządzeniu |
host.log | Logowanie z poziomami do hosta |
Każde inne API jest opcjonalne i addytywne: tokens, text, color, geom, pdf, compose, media, recorder i wiele innych. Manifest narzędzia wymienia w requires opcjonalne API, które jego hooki wywołują bez sprawdzenia, a host, któremu któregoś brakuje, odmawia zamontowania narzędzia; hooki wykrywają resztę. Kilka, jak recorder, wymaga też zdolności urządzenia deklarowanej przez narzędzie. packages/core/src/host-v1/apis.ts wymienia je wszystkie, a Host API dokumentuje każde. Dodanie metody to wersja minor; usunięcie lub zmiana to wersja major, a v1 działa dalej, gdy pojawi się v2.
4. Identyfikatory zasobów są na zawsze
lolly/logo/primary to kontrakt. Po opublikowaniu identyfikator nigdy się nie zmienia i nie jest używany ponownie. Zmiana bajtów podbija version we wpisie zasobu, a zamiennik ustawia deprecated: true i opcjonalnie replacedBy, więc istniejące odwołania zawsze się rozwiązują. To dzięki temu zapisane sesje i udostępnione linki działają latami.
5. Tryb URL jest pierwszorzędny
Każde dane wejściowe da się wyrazić jako parametr URL, więc link jest gotowym plikiem:
https://lolly.tools/t/qr-code?url=https://example.com&ecl=H signed by Lollyvector SVG55 paths~2.6k nodes38 groups60 KBCheck it yourselfPobierz podpisany plik
signed by Lollyvector SVG55 paths~2.6k nodes38 groups61 KBCheck it yourselfPobierz podpisany plik
Zmień parametr, a masz inny plik. Cała ta paleta to jeden kolor wyjściowy, harmonia i liczba kroków:
signed by Lollyvector SVG10 groups25 KBCheck it yourselfPobierz podpisany plik
signed by Lollyvector SVG10 groups25 KBCheck it yourselfPobierz podpisany plik
CLI buduje ten sam stan URL ze swoich argumentów i uruchamia ten sam potok, więc CLI nie może się rozjechać z aplikacją. engine/src/url-mode.ts parsuje i serializuje; zestaw zarezerwowanych nazw (format, width, dpi, c2pa, z i inne) nigdy nie jest przekazywany narzędziu, a Reserved URL parameters wymienia je wszystkie. Dane wejściowe typu zasób podróżują po id i są rozwiązywane przez host.assets.get(), zanim szablon się wypełni.
6. Pamięć idzie przez most
Aplikacja internetowa używa IndexedDB, Tauri system plików, a CLI pamięci. Narzędzia widzą tylko host.state.save(slot, data) i host.state.load(slot), nigdy localStorage. Ludzie mogą trzymać kilka nazwanych sesji na narzędzie bez konta. Ponieważ most jest jedynym szwem, ten stan jest też przenośny: shells/web/src/data-transfer.ts odczytuje go z powrotem do jednego pliku lolly-backup, który importuje się na każdej innej instalacji (Data transfer), a Sync wysyła ten sam pakiet do magazynu wybranego przez osobę.
7. Znaczniki dojrzałości mówią, czym jest narzędzie
Każde narzędzie deklaruje status: official | community | experimental. Galeria sortuje według statusu, a narzędzia eksperymentalne domyślnie oznaczają eksporty znakiem wodnym: runtime włącza znak wodny, chyba że wywołujący poda watermark: false, a narzędzia na urządzeniu są wyłączone. Jakikolwiek proces zespół ułoży wokół katalogu, leży na tym.
8. Dane wejściowe są typowane w manifeście
Dane wejściowe deklarują type: text, longtext, number, boolean, color, select, asset, date, time, datetime-local, url, blocks, vector, table lub file. Host renderuje kontrolkę dla każdego typu, więc narzędzia nie piszą kodu kontrolek, a każde dane wejściowe mogą nieść bindToProfile. Trzy mają największe znaczenie:
asset, zfilteriallowUpload, to most do systemu zasobów.allowUpload: falseogranicza slot do zasobów biblioteki, a wgrane przez użytkownika pliki dzielą kształtAssetRefbiblioteki.blocksto powtarzalna grupa pól edytowana w panelu bocznym, używana przez Meeting Planner, Wayfinding, Diagrams i inne. Kliknięcie wyrenderowanego bloku ustawia fokus na jego wierszu.filetrzyma własny plik użytkownika w pamięci dla utilities na urządzeniu, takich jak Lolly Strip Hidden Data i Compress, avectorgrupuje stały zestaw liczb w jedną kontrolkę.
9. Szablony są bez logiki
Szablony to Handlebars, wybrane, aby mogły je pisać osoby niebędące programistami: {{x}} escapuje, a {{{x}}} to jawna zgoda. Logika żyje w hooks.js, gdzie jest jawna i podlega przeglądowi. Wiele szablonów używa {{{ dla znaczników obliczonych przez hook, więc każdy hook musi escapować to, co przekazuje. Helpery to default, upper, lower, eq, markdown, asset, framing i media, plus icsStamp, rfcText, csvCell i arrow dla siostrzanych szablonów .ics, .vcf i .csv. Templates and rendering je omawia.
10. Narzędzia komponują narzędzia
Narzędzie może osadzić render innego narzędzia bez importów między narzędziami; silnik rozwiązuje kompozycję. Manifest może zadeklarować composes: [{ id, tool, inputs }] i umieścić dziecko przez {{asset <id>}}, a przenośny adres osadzenia (https://lolly.tools/tool/<id>.svg?…) renderuje dziecko lokalnie, i tak Lolly Design umieszcza żywy kod QR lub wykres. Dziecko SVG pozostaje wektorowe w rodzicu SVG lub PDF. Dzieci są produktami pośrednimi, nigdy nie dostają znaku wodnego ani stempla, a powłoka, która nie może ich wyrenderować, zostawia slot pusty, podczas gdy rodzic nadal się renderuje. Composition and brand overlays podaje szczegóły.
Czego postanowiliśmy nie robić
- Żadnego dowolnego JavaScriptu w szablonach. Logika żyje w
hooks.js. - Żadnego obowiązkowego serwera zasobów. Ludzie dodają własne pliki do Assets w aplikacji i przekazują pracę jako sesję: link udostępniania dla danych wejściowych i ustawień, plik
.lolly, gdy podróżują też wgrane pliki. Udostępniona sesja może stać się szablonem w wyborze narzędzia. Organizacja, która chce nadzorowanego katalogu, może użyć katalogu, zatwierdzeń i polityk Lolly Work albo zarządzać paczką marki w git i tam przeglądać zmiany. - Żadnej wymuszonej kontroli dostępu. Otwarta aplikacja jest domyślnie publiczna, a znaczniki dojrzałości i znaki wodne niosą ryzyko marki. Logowanie organizacji, role i polityki pochodzą z Lolly Work, gdy zespół ich chce.
- Żadnej centralnej bazy danych. Stan użytkownika żyje na każdym urządzeniu, a opcjonalny Sync kopiuje go do magazynu wybranego przez osobę, nigdy do bazy Lolly.
- Żadnej wspólnej ścieżki kodu między narzędziami a silnikiem. Silnik i narzędzia społeczności są open source, a paczka marki, taka jak prywatna
brands/suse/, niesie własne narzędzia i katalog na własnych warunkach. Żadne narzędzie nie importuje zengine/, więc podział pozostaje czysty.
Cykl życia jednego renderu
Ktoś otwiera https://lolly.tools/t/qr-code?url=https://example.com&ecl=H:
- Start. Aplikacja internetowa otwiera IndexedDB, buduje most możliwości i synchronizuje katalogi narzędzi i zasobów albo ładuje je z pamięci podręcznej offline.
- Trasa. Ścieżka wybiera widok narzędzia dla
qr-code, z zapytaniem jako wartościami początkowymi. - Wczytanie.
loadToolpobieratool.json, waliduje go względem schematu i pobiera szablon, style i hooki. - Parsowanie linku.
parseUrlStatezamienia parametry na wartości danych wejściowych. Odwołanie do zasobu, takie jak?logo=lolly/logo/primary, staje się nierozwiązanym{ id }. - Uruchomienie runtime.
createRuntime(tool, host, initialValues)buduje model danych wejściowych z danych profilu, wartości domyślnych i linku, rozwiązuje odwołania do zasobów, ładuje hooki i wywołujeonInit. - Renderowanie. Powłoka subskrybuje runtime, rysuje kontrolki z modelu i zapisuje wypełniony szablon do
#tool-canvas. - Interakcja. Pisanie wywołuje
runtime.setInput, które stosuje ograniczenia, wywołujeonInput, ponownie wypełnia szablon i przerysowuje. - Eksport. Download wywołuje
runtime.export(node, format), ahost.exportpowłoki tworzy plik: raster, wektor z przejścia po DOM, PDF, dokument lub jeden z pozostałych formatów wschemas/tool.schema.json. Jednostki fizyczne są przeliczane dla każdego formatu, a metadane i Content Credentials są osadzane tam, gdzie format może je pomieścić. Narzędzia eksperymentalne dostają znak wodny od hosta, a nie od narzędzia. Templates and rendering i Export a file omawiają krok eksportu.
signed by Lollyvector SVG77 paths~6.0k nodes87 groups3 images88 KBCheck it yourselfPobierz podpisany plik
signed by Lollyvector SVG77 paths~6.0k nodes87 groups3 images88 KBCheck it yourselfPobierz podpisany plik
Ten sam cykl życia działa w Tauri i w CLI z DOM bez interfejsu, gdzie wynik trafia do pliku lub stdout.
Licencje
Kod, w tym engine/, shells/, services/, schemas/ i generator dokumentacji, jest na MPL-2.0, w jednym publicznym repozytorium, lolly-tools/lolly. Proza dokumentacji jest na CC BY-SA 4.0. Paczki marek niosą własne warunki w NOTICE.md każdej paczki: narzędzia społeczności są na MPL-2.0, a prywatna paczka SUSE jest własnościowa SUSE. About zawiera pełną notę licencyjną.