Narzędzia dev (Layer 2)#
Narzędzia eksploracji pozwalają AI czytać kod źródłowy, przeszukiwać pliki, przeglądać logi i badać pełny rejestr urządzeń z metadanymi. Wymagają włączonego Dev Mode.
Przegląd#
| Narzędzie | Opis |
|---|---|
vclu_read_file | Odczyt pliku (Lua, dokumentacja, pluginy) |
vclu_list_files | Lista plików pasujących do wzorca glob |
vclu_grep | Przeszukiwanie kodu regexem |
vclu_logs | Logi runtime z filtrowaniem |
vclu_config | Konfiguracja systemu (bez sekretów) |
vclu_registry | Pełny rejestr urządzeń z metadanymi |
vclu_read_file#
Odczytuje plik z katalogu danych vCLU. Limit rozmiaru: 100 KB.
Parametry#
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
path | string | tak | Ścieżka względna, np. a/user.lua, modules/init.lua |
Dozwolone ścieżki#
| Wzorzec | Opis |
|---|---|
a/main.lua, a/user.lua, a/om.lua | Systemowe pliki Lua |
modules/**/*.lua | Moduły użytkownika |
imports/proxy_*.lua | Pliki proxy OM |
docs/ai/*.md | Dokumentacja |
plugins/**/*.lua, plugins/**/plugin.json | Kod źródłowy pluginów |
Pliki z sekretami (
.vclu.json,keys.json) są zawsze zablokowane.
Przykład odpowiedzi#
{
"env": "runtime",
"path": "modules/init.lua",
"content": "require(\"tasmota_biurko\")\nrequire(\"biuro_auto\")\nprint(\"[MODULES] User modules initialized\")\n"
}vclu_list_files#
Zwraca listę plików pasujących do wzorca glob. Wyniki ograniczone do dozwolonych ścieżek.
Parametry#
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
pattern | string | tak | Wzorzec glob, np. modules/*.lua, docs/ai/*.md |
Przykład odpowiedzi#
{
"env": "runtime",
"files": [
{ "path": "modules/init.lua", "size": 120, "modified": 1740900000 },
{ "path": "modules/biuro_auto.lua", "size": 850, "modified": 1740905000 },
{ "path": "modules/salda_expose.lua", "size": 1200, "modified": 1740906000 }
],
"count": 3
}vclu_grep#
Przeszukuje pliki regexem. Domyślnie szuka w *.lua, można zmienić wzorcem glob.
Parametry#
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
pattern | string | tak | Wyrażenie regularne |
glob | string | nie | Filtr plików (domyślnie: *.lua) |
max_results | number | nie | Maks. wyników (domyślnie: 50, max: 200) |
Przykład odpowiedzi#
{
"env": "runtime",
"matches": [
{ "file": "modules/biuro_auto.lua", "line": 5, "content": "local HOUR_ON = 17" },
{ "file": "modules/salda_expose.lua", "line": 12, "content": "expose(salda:get(\"fanSpeed\"), \"fan\", {" }
],
"count": 2
}vclu_logs#
Zwraca ostatnie wpisy z logu runtime, od najnowszych. Opcjonalny filtr regexem.
Parametry#
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
limit | number | nie | Liczba wpisów (domyślnie: 100, max: 1000) |
filter | string | nie | Regex filtrujący po treści i źródle |
Przykład odpowiedzi#
{
"env": "runtime",
"logs": [
{ "time": "2026-03-02T18:30:00Z", "level": "info", "source": "ExposedObjects", "message": "Exposed: salda:fanSpeed (type=fan)" },
{ "time": "2026-03-02T18:29:55Z", "level": "info", "source": "MODULES", "message": "User modules initialized" }
],
"count": 2
}Użycie z filtrem#
vclu_logs(filter: "error|warn", limit: 50) - pokaże tylko błędy i ostrzeżenia.
vclu_config#
Zwraca konfigurację systemu bez sekretów (bez kluczy API, haseł, tokenów).
Parametry#
Brak.
Przykład odpowiedzi#
{
"env": "runtime",
"devModeEnabled": true,
"mcpBots": ["Claude", "Codex"]
}vclu_registry#
Zwraca pełny rejestr urządzeń z metadanymi: area (pokój), group (grupa logiczna), tags, description. Obsługuje filtrowanie po wielu polach jednocześnie.
Parametry#
| Parametr | Typ | Wymagany | Opis |
|---|---|---|---|
filter | object | nie | Filtr (wszystkie pola opcjonalne, łączone AND) |
Pola filtra#
| Pole | Typ | Opis |
|---|---|---|
type | string | Typ urządzenia: switch, dimmer, cover, sensor, scene itp. |
area | string | Pokój / strefa fizyczna |
group | string | Grupa logiczna |
tag | string | Tag do dopasowania |
text | string | Wyszukiwanie w name, description, path |
Przykład odpowiedzi#
{
"env": "runtime",
"devices": [
{
"path": "CLU220000592.DOU3328",
"type": "switch",
"name": "BIURO_LED",
"state": 1,
"readonly": false,
"methods": ["toggle", "switchOn", "switchOff"],
"area": "Biuro",
"group": "Oświetlenie",
"tags": ["led"],
"description": "Oświetlenie LED w biurze"
}
],
"count": 1
}Różnica: vclu_devices vs vclu_registry#
vclu_devices (Layer 1) | vclu_registry (Layer 2) | |
|---|---|---|
| Dev Mode | nie wymagany | wymagany |
| Metadane | area, group, tags (jeśli wystawione) | pełne metadane |
| Filtrowanie | tylko type | type, area, group, tag, text |
| Przeznaczenie | sterowanie | eksploracja i zrozumienie domu |
Pole description - instrukcje dla AI#
Pole description w rejestrze urządzeń może zawierać zasady i ograniczenia dla AI:
expose(salda:get("fanSpeed"), "fan", {
name = "Rekuperator",
path = "salda:fanSpeed",
area = "Techniczny",
description = "Fan speed 0=off, 1=low, 2=medium, 3=high, 4=max. "
.. "Never set to 0 when temperature outside < 5°C."
})AI czyta description i stosuje się do zawartych w nim reguł. To sposób na komunikowanie ograniczeń bez pisania kodu walidacyjnego.
Registry a expose()#
Obiekty trafiają do _registry na dwa sposoby:
| Funkcja | Registry | MQTT/HomeKit/MCP | Kiedy |
|---|---|---|---|
registerObject(path, obj) | tak | nie | Hardware z om.lua, obiekty wewnętrzne |
expose(obj, type, options) | tak (automatycznie) | tak | Sceny, pluginy, Tasmota, cokolwiek do wystawienia |
expose() automatycznie dodaje obiekt do _registry, jeśli go tam jeszcze nie ma. Dzięki temu _registry:get() działa zarówno dla hardware jak i scen/pluginów.
expose(scene, "scene", { path = "scene:movie" })
_registry:get("scene:movie"):execute() -- działaNastępny krok#
Sandbox i promocja - jak AI pisze i wdraża kod Lua