Praca z systemem plików#

Oprócz MCP, możesz pracować z vCLU bezpośrednio przez SSH/SFTP. Dowolny agent AI (Claude Code, Cursor, VS Code Remote) lub edytor może otworzyć katalog danych vCLU i edytować pliki jak w normalnym projekcie.

Kiedy wybrać system plików zamiast MCP#

Scenariusz	MCP	System plików
Sterowanie urządzeniami	tak	nie
Pisanie modułów Lua	tak (sandbox pipeline)	tak
Duży refactoring wielu plików	trudniej	łatwiej
Inspekcja pluginów	tak (read-only)	tak
Praca z gitem	nie	tak
Dostęp do logów	tak (`vclu_logs`)	tak (`journalctl`)

Połączenie#

SSH#

ssh vclu@192.168.0.218
cd /opt/vclu/data

Claude Code przez SSH#

claude --remote ssh://vclu@192.168.0.218 --directory /opt/vclu/data

VS Code Remote#

Zainstaluj rozszerzenie “Remote - SSH”
Połącz z vclu@192.168.0.218
Otwórz katalog /opt/vclu/data

SFTP (np. Cyberduck, FileZilla)#

Host: 192.168.0.218, użytkownik: vclu, katalog: /opt/vclu/data

Struktura katalogów#

/opt/vclu/data/
├── a/
│   ├── main.lua          # bootstrap (nie modyfikuj)
│   ├── om.lua            # generowany przez OM (nie modyfikuj!)
│   └── user.lua          # generowany przez OM (nie modyfikuj!)
├── modules/
│   ├── init.lua          # punkt wejścia modułów
│   ├── biuro_auto.lua    # moduł użytkownika
│   └── salda_expose.lua  # moduł użytkownika
├── imports/
│   └── proxy_*.lua       # proxy pliki OM
├── plugins/
│   └── vclu--salda-recuperator/
│       ├── plugin.json
│       └── init.lua
├── docs/
│   └── ai/
│       ├── house.md      # opis domu dla agentów AI
│       └── examples.md   # przykłady kodu Lua
└── .vclu.json            # konfiguracja (nie modyfikuj ręcznie)

Co wolno modyfikować#

Ścieżka	Status	Opis
`modules/*.lua`	edytuj swobodnie	Moduły użytkownika - tu trafia Twój kod
`docs/ai/*.md`	edytuj swobodnie	Dokumentacja dla agentów AI
`plugins/*/`	ostrożnie	Kod pluginów, lepiej nie modyfikować bezpośrednio

Czego NIE wolno modyfikować#

a/om.lua i a/user.lua - NIGDY nie modyfikuj tych plików!
Te pliki są generowane przez Object Manager (OM) i zostaną nadpisane przy każdym wgraniu konfiguracji z OM. Wszelkie ręczne zmiany zostaną utracone bez ostrzeżenia.
a/om.lua - definicje modułów, IO, obiekty z OM
a/user.lua - skrypty użytkownika z OM
Jeśli chcesz dodać własny kod, używaj modules/*.lua.

a/main.lua - nie modyfikuj bez dobrego powodu.
To bootstrap loader, który ładuje runtime, om.lua, user.lua i moduły. Zła modyfikacja może uniemożliwić start vCLU.

.vclu.json - nie edytuj ręcznie.
Plik konfiguracyjny z sekretami (klucze API, hashe haseł). Używaj dashboardu webowego do zmian konfiguracji.

Workflow: moduły Lua#

1. Utwórz moduł#

# Na vCLU przez SSH:
nano /opt/vclu/data/modules/moj_modul.lua

-- modules/moj_modul.lua
local Logger = Logger:getShared()
Logger:info("[MOJ_MODUL] Loaded")

-- Twój kod tutaj...

2. Zarejestruj w init.lua#

-- modules/init.lua
require("moj_modul")
print("[MODULES] User modules initialized")

3. Przeładuj runtime#

Zmiany w modułach wymagają przeładowania runtime Lua. Możesz to zrobić:

Z dashboardu - przycisk “Reload” na stronie głównej
Przez API - curl -X POST http://192.168.0.218:8080/api/reset
Restart serwisu - sudo systemctl restart vclu

Przy pracy przez MCP (vclu_draft_promote) reload jest automatyczny. Przy pracy przez system plików musisz go wywołać ręcznie.

Porównanie: MCP vs system plików#

Cecha	MCP (Layer 2)	System plików
Walidacja składni	automatyczna (`draft_validate`)	ręczna
Test w sandboxie	tak (`draft_test`)	nie
Automatyczny backup	tak (przy promote)	nie (chyba że git)
Automatyczny reload	tak (przy promote)	nie - ręczny reload
Audit trail	tak	nie
Rate limits	tak	nie
Wymaga Dev Mode	tak	nie
Git integration	nie	tak

Dobre praktyki#

Używaj gita - cd /opt/vclu/data && git init pozwala śledzić zmiany i cofać błędy
Testuj przed reloadem - sprawdź składnię: luac -p modules/moj_modul.lua
Nie commituj .vclu.json - zawiera sekrety; dodaj do .gitignore
Moduły, nie om.lua - cały Twój kod powinien być w modules/, nigdy w a/om.lua czy a/user.lua