Narzędzia Layer 2 (Dev Mode)#

Oprócz podstawowych narzędzi sterowania (Layer 1), vCLU udostępnia rozszerzone narzędzia dla agentów AI w trybie Dev Mode. Wymagają włączenia Dev Mode w panelu MCP.

Warstwy narzędzi#

Warstwa	Wymagania	Cel
Layer 1	Bot + API key	Sterowanie urządzeniami, sceny
Layer 2	Bot + Dev Mode	Eksploracja kodu, konfiguracja, deployment
Exec Mode	Bot + Dev Mode + Exec	Wykonywanie dowolnego kodu Lua

Włączanie Dev Mode#

Przejdź do MCP w panelu webowym
Włącz Dev Mode (globalny przełącznik)
Przy bocie włącz Sandbox access (opcjonalnie Exec Mode)

Eksploracja kodu#

vclu_read_file#

Odczytuje plik z katalogu vCLU (kod Lua, dokumentacja, moduły).

Parametr	Typ	Opis
`path`	string	Ścieżka względna, np. `modules/init.lua`, `ai/house.md`

Agent używa tego do zrozumienia istniejącego kodu przed wprowadzeniem zmian.

vclu_list_files#

Lista plików pasujących do wzorca glob.

Parametr	Typ	Opis
`pattern`	string	Wzorzec, np. `modules/.lua`, `plugins/*/init.lua`

vclu_grep#

Wyszukiwanie wzorca regex w plikach.

Parametr	Typ	Opis
`pattern`	string	Wyrażenie regularne
`glob`	string	Filtr plików (domyślnie `*.lua`)
`max_results`	number	Limit wyników (domyślnie 50, max 200)

vclu_logs#

Ostatnie logi systemowe - agent używa do diagnostyki problemów.

Parametr	Typ	Opis
`limit`	number	Liczba wpisów (domyślnie 100, max 1000)
`filter`	string	Regex filtr wiadomości

Przykład: agent szuka błędów MQTT → vclu_logs(filter: "MQTT.*error", limit: 50)

Konfiguracja i status#

vclu_config#

Zwraca konfigurację systemu (bez sekretów). Agent widzi jakie boty istnieją, czy Dev Mode jest włączony.

vclu_registry#

Pełny rejestr urządzeń z metadanymi - obszar, grupa, tagi, opis. Bogatsze dane niż vclu_devices.

Parametr	Typ	Opis
`filter`	object	Filtr: `type`, `area`, `group`, `tag`, `text`

Przykład: vclu_registry(filter: {area: "Salon", type: "switch"}) - wszystkie przełączniki w salonie.

vclu_runtime_schema#

Schemat runtime: typy obiektów, API dashboardów, metody pluginów, zainstalowane pluginy z ich sensorami i kontrolkami. Agent odczytuje to przed pisaniem kodu.

vclu_plugin_config#

Konfiguracja pluginów (sekrety zamaskowane). Agent widzi jakie pluginy są zainstalowane i jak skonfigurowane.

Parametr	Typ	Opis
`id`	string	Filtr po ID pluginu (opcjonalnie)

vclu_device_history#

Ostatnie zmiany stanów urządzeń - agent widzi co się działo.

Parametr	Typ	Opis
`path`	string	Filtr po urządzeniu (opcjonalnie)
`limit`	number	Liczba wpisów (domyślnie 50, max 500)

vclu_dashboards#

Lista zarejestrowanych dashboardów z widgetami - agent widzi co jest wyświetlane.

vclu_metrics#

Metryki i dane historyczne do wykresów.

Parametr	Typ	Opis
`path`	string	Ścieżka metryki (pomiń = lista wszystkich)
`range`	string	Zakres: `30m`, `2h`, `24h`, `7d` (domyślnie `2h`)

MQTT Discovery#

vclu_mqtt_discover#

Skanuje brokery MQTT w poszukiwaniu urządzeń smart home. Rozpoznaje Zigbee2MQTT, Tasmota, ESPHome, Shelly i Home Assistant Discovery.

Parametr	Typ	Opis
`source`	string	`all` (domyślnie), `broker` (tylko wbudowany), lub ID instancji klienta

Zwraca listę odkrytych urządzeń z:

Nazwa, typ, model, producent, IP, firmware
Topici MQTT (state/command)
Flaga exposed - czy urządzenie jest już skonfigurowane w vCLU
suggestedLua - gotowy snippet kodu integracji

Typowy flow agenta po discovery:

vclu_mqtt_discover → lista urządzeń
Łączy snippety w moduł Lua
vclu_draft_write → zapisuje draft
vclu_draft_test → testuje w sandbox
vclu_draft_promote → wdraża na produkcję

Sandbox pipeline#

Bezpieczny pipeline do wdrażania kodu - agent nigdy nie wgrywa kodu bezpośrednio.

vclu_draft_write#

Zapisuje plik draftu (tylko modules/*.lua).

Parametr	Typ	Opis
`path`	string	Ścieżka, np. `modules/mqtt_devices.lua`
`content`	string	Kod Lua

vclu_draft_read#

Odczytuje plik draftu.

Parametr	Typ	Opis
`path`	string	Ścieżka draftu

vclu_draft_list#

Lista wszystkich plików w workspace draftu.

vclu_draft_delete#

Usuwa plik draftu.

Parametr	Typ	Opis
`path`	string	Ścieżka draftu

vclu_draft_validate#

Sprawdza składnię Lua i listę zablokowanych funkcji.

Parametr	Typ	Opis
`path`	string	Ścieżka draftu

Zwraca: czy plik jest poprawny, lista ostrzeżeń i błędów.

vclu_draft_test#

Uruchamia draft w sandbox - izolowanym środowisku bez efektów ubocznych.

Parametr	Typ	Opis
`path`	string/array	Ścieżka draftu lub tablica ścieżek
`inject_events`	array	Zdarzenia do zasymulowania (opcjonalnie)

Zwraca:

state_changes - jakie zmiany stanów BY nastąpiły
blocked_calls - jakie wywołania zostały zablokowane (MQTT publish, HTTP, etc.)
Błędy runtime jeśli wystąpiły

vclu_draft_promote#

Wdraża drafty na produkcję: backup → zamiana → reload Lua.

Parametr	Typ	Opis
`path`	string/array	Ścieżka lub `"all"` (pomiń = wszystkie drafty)

Limit: Maksymalnie 10 deploymentów na godzinę.

vclu_diff#

Pokazuje różnicę między draftem a wersją produkcyjną (unified diff).

Parametr	Typ	Opis
`path`	string	Ścieżka draftu

vclu_audit_log#

Ostatnie wpisy audytowe Layer 2 - kto co zrobił.

Parametr	Typ	Opis
`limit`	number	Liczba wpisów (domyślnie 50, max 200)

Pamięć agenta#

vclu_context_save#

Zapisuje notatki do pamięci trwałej - przetrwają między sesjami.

Parametr	Typ	Opis
`notes`	string	Notatki w Markdown (dopisywane, nie nadpisywane)

Agent zapisuje odkryte ograniczenia, konwencje, TODO na przyszłość.

vclu_context_read#

Odczytuje wcześniej zapisane notatki agenta. Zwykle wywoływany na początku sesji.

Wykonywanie kodu#

vclu_exec#

Wykonuje snippet Lua na żywym runtime. Wymaga Exec Mode - dodatkowe uprawnienie na bocie.

Parametr	Typ	Opis
`script`	string	Kod Lua (max 8KB). Użyj `return expr` żeby uzyskać wynik

Uwaga: Ten tool wykonuje kod bezpośrednio na produkcji - bez sandbox. Używaj do diagnostyki i szybkich poprawek, nie do wdrażania nowego kodu. Do wdrożeń używaj sandbox pipeline.

Reload#

vclu_reload#

Przeładowuje runtime Lua - stosuje zmiany kodu bez restartu vCLU.

Używane po ręcznych zmianach plików. Sandbox pipeline (vclu_draft_promote) automatycznie przeładowuje - nie trzeba wywoływać osobno.

Podsumowanie#

Kategoria	Narzędzia
Eksploracja	`read_file`, `list_files`, `grep`, `logs`, `runtime_schema`
Status	`config`, `registry`, `dashboards`, `plugin_config`, `device_history`, `metrics`
MQTT	`mqtt_discover`
Sandbox	`draft_write`, `draft_read`, `draft_list`, `draft_delete`, `draft_validate`, `draft_test`, `draft_promote`, `diff`
Pamięć	`context_save`, `context_read`
Audyt	`audit_log`
Runtime	`exec`, `reload`