Dostęp do plików w lokalnym agencie AI: narzędzia

Dostęp do plików dla lokalnego agenta AI: implementacja narzędzi i usuwanie błędów

Lokalny agent AI Doka otrzymał dostęp do plików, ale wcześniej trzeba było naprawić krytyczny błąd z cache'em KV w llama.cpp. Prompt systemowy rozpoczynał się linią Session started: ${new Date().toISOString()}, która zmieniała się przy każdej iteracji. To unieważniało cały cache: model ponownie obliczał 2000 tokenów promptu przy 10 iteracjach, dodając 20 000 zbędnych tokenów.

Przeniesienie znacznika czasu na koniec promptu lub do user-turn przywróciło cache. Zadania wieloetapowe przyspieszyły 2–3 razy w cyklach z 8+ iteracjami. Wzór jest podobny do zaleceń Anthropic dla Claude, ale jest krytyczny również dla modeli lokalnych.

Bezpieczny dostęp do plików przez bramkę uprawnień

Narzędzia do czytania plików są zaimplementowane prosto, ale zapis wymaga kontroli. Każde narzędzie w zestawie ma flagę dangerous:

const fileTools: Tool[] = [
  {
    name: 'read_file',
    dangerous: false,
  },
  {
    name: 'write_file',
    dangerous: true,
  },
  {
    name: 'edit_file',
    dangerous: true,
  },
  {
    name: 'delete_file',
    dangerous: true,
  },
];

Przy wywołaniu dangerous-narzędzia pojawia się dialog z argumentami: ścieżka, zawartość (pierwsze 500 znaków). Przycisk "Zezwól" nie jest domyślnie wybrany. Odmowa zwraca agentowi błąd:

{
  "error": "User denied permission for write_file",
  "canRetry": false,
  "suggestion": "Ask the user to confirm the intended file path"
}

Pełny zestaw narzędzi do plików

Zaimplementowano sześć narzędzi:

• read_file(path: string): string
• write_file(path: string, content: string): void (dangerous)
• edit_file(path: string, instruction: string): void (dangerous)
• list_dir(path: string): FileEntry[]
• move_file(from: string, to: string): void (dangerous)
• delete_file(path: string): void (dangerous)

edit_file stosuje łatkę według instrukcji (read → patch → write → verify), unikając przesyłania dużych plików przez kontekst.

Usuwanie błędów ze ścieżkami do plików

Agent mylił pliki o tych samych nazwach w różnych katalogach z powodu względnych ścieżek. Rozwiązanie:

• Domyślny katalog roboczy w prompt systemowym.
• Walidacja ścieżek: wyjście poza granice — błąd.
• Instrukcja: w przypadku niejednoznaczności pytać użytkownika.

Błąd pojawiał się przy 3–4 teście: agent wybierał notes.md z katalogu głównego zamiast docelowego.

Po write_file lub edit_file następuje auto-verify: automatyczne read_file do weryfikacji. To dodaje krok, ale zapobiega cichym awariom (prawa, dysk). MAX_TOOL_STEPS zwiększono do 12 dla plan + read + write + verify.

Agent Timeline dla przejrzystości

Użytkownicy narzekali na "czarną skrzynkę": trzy minuty oczekiwania bez zrozumienia kroków. Dodano panel boczny z logiem:

• Wywołania narzędzi z argumentami.
• Wyniki.
• Znaczniki czasu.

Stream zdarzeń (tool_call_start / tool_call_end) renderowany w React w czasie rzeczywistym. Krytyczne dla dostępu do plików: widoczne dokładne ścieżki i operacje.

Ustrukturyzowane błędy i logika retry

Wcześniej błędy zwracały ślad stosu Node.js, powodując nieskończone retry lub halucynacje. Teraz struktura:

{
  "error": "File not found: /path/to/file.md",
  "canRetry": false,
  "suggestion": "Check if the path is correct with list_dir first"
}

canRetry zmniejsza bezcelowe powtórzenia. Dla timeoutów sieciowych — true, dla nieistniejących plików — false.

Restrukturyzacja prompt systemowego

Prompt systemowy podzielony na sekcje:

• Rola i granice: możliwości i ograniczenia.
• Zasady z priorytetami: bezpieczeństwo > dokładność > szybkość.
• Format odpowiedzi: struktura dla różnych typów.
• Few-shot przykład: reasoning na marginalnym przypadku.

Struktura zmniejszyła halucynacje w długich łańcuchach, szczególnie odmowy według zasad.

Faza planowania: Think → Plan → Act

Instrukcja przed narzędziami:

Before using tools, write a short plan:
THINK: [what information do I need?]
PLAN: [step 1 → step 2 → step 3]
ACT: [execute plan]

Zmniejsza ponowne wywołania jednego narzędzia o połowę. Wymusza cel przed działaniem.

Co ważne

• Przeniesienie danych dynamicznych (timestamp) na koniec promptu przyspiesza cykle 2–3 razy dzięki cache'owi KV.
• Bramka uprawnień z dialogiem i ustrukturyzowanymi błędami minimalizuje ryzyko zapisu.
• Auto-verify i walidacja ścieżek eliminują ciche awarie operacji na plikach.
• Agent Timeline zapewnia przejrzystość kroków dla zaufania do dostępu do plików.
• Ustrukturyzowany prompt z planowaniem zwiększa stabilność na zadaniach wieloetapowych.

— Editorial Team