Přístup k souborům v lokálním AI agentovi: nástroje

Přístup k souborům pro lokálního AI agenta: implementace nástrojů a odstranění chyb

Lokální AI agent Doka získal přístup k souborům, ale předtím bylo nutné odstranit kritickou chybu s KV-mezipamětí v llama.cpp. Systémový prompt začínal řetězcem Session started: ${new Date().toISOString()}, který se měnil při každé iteraci. To invalidovalo celou mezipaměť: model přepočítával 2000 tokenů promptu znovu při 10 iteracích, přidávaje 20 000 nadbytečných tokenů.

Přesun timestampu na konec promptu nebo do user-turn obnovil mezipaměť. Vícekrokové úlohy se zrychlily 2–3krát na cyklech s 8+ iteracemi. Tento vzor je podobný doporučením Anthropic pro Claude, ale je kritický i pro lokální modely.

Bezpečný přístup k souborům prostřednictvím povolovací brány

Nástroje pro čtení souborů jsou implementovány jednoduše, ale zápis vyžaduje kontrolu. Každý nástroj v sadě má příznak dangerous:

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

Při volání dangerous-nástroje se zobrazí dialog s argumenty: cesta, obsah (prvních 500 znaků). Tlačítko „Povolit“ není výchozí. Odmítnutí vrátí agentovi chybu:

{
  "error": "Uživatel odmítl povolení pro write_file",
  "canRetry": false,
  "suggestion": "Požádejte uživatele o potvrzení zamýšlené cesty k souboru"
}

Kompletní sada nástrojů pro soubory

Implementováno šest nástrojů:

• 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 aplikuje záplatu podle instrukce (read → patch → write → verify), čímž se vyhne přenosu velkých souborů přes kontext.

Odstranění chyb s cestami k souborům

Agent zaměňoval soubory se stejným názvem v různých adresářích kvůli relativním cestám. Řešení:

• Pracovní adresář ve výchozím nastavení v systémovém promptu.
• Validace cest: výstup mimo povolené hranice – chyba.
• Instrukce: při nejednoznačnosti se ptát uživatele.

Chyba se projevila při 3.–4. testu: agent vybral notes.md z kořene místo cílové složky.

Po write_file nebo edit_file následuje auto-verify: automatické read_file pro kontrolu. To přidává krok, ale předchází tichým selháním (práva, disk). MAX_TOOL_STEPS zvýšeno na 12 pro plan + read + write + verify.

Agent Timeline pro transparentnost

Uživatelé si stěžovali na „černou skříňku“: tři minuty čekání bez pochopení kroků. Přidána boční panel s logem:

• Volání nástrojů s argumenty.
• Výsledky.
• Časová razítka.

Stream událostí (tool_call_start / tool_call_end) se vykresluje v React v reálném čase. Kritické pro přístup k souborům: viditelné přesné cesty a operace.

Strukturované chyby a logika opakování

Dříve chyby vracely stacktrace Node.js, což způsobovalo nekonečné opakování nebo halucinace. Nyní struktura:

{
  "error": "Soubor nebyl nalezen: /path/to/file.md",
  "canRetry": false,
  "suggestion": "Nejprve zkontrolujte, zda je cesta správná pomocí list_dir"
}

canRetry snižuje zbytečné opakování. Pro síťové časové limity – true, pro neexistující soubory – false.

Restrukturalizace systémového promptu

Systémový prompt rozdělen na sekce:

• Role a hranice: schopnosti a omezení.
• Pravidla s prioritami: bezpečnost > přesnost > rychlost.
• Formát odpovědi: struktura pro různé typy.
• Few-shot příklad: reasoning na hraničním případě.

Struktura snížila halucinace v dlouhých řetězcích, zejména odmítnutí podle pravidel.

Fáze plánování: Think → Plan → Act

Instrukce před nástroji:

Před použitím nástrojů napište krátký plán:
THINK: [jaké informace potřebuji?]
PLAN: [krok 1 → krok 2 → krok 3]
ACT: [provedení plánu]

Snižuje opakovaná volání stejného nástroje na polovinu. Nutí zaměřit se na cíl před akcí.

Co je důležité

• Přesun dynamických dat (timestamp) na konec promptu urychluje cykly 2–3krát díky KV-mezipaměti.
• Povolovací brána s dialogem a strukturovanými chybami minimalizuje rizika zápisu.
• Auto-verify a validace cest odstraňují tichá selhání souborových operací.
• Agent Timeline zajišťuje transparentnost kroků pro důvěru v přístup k souborům.
• Strukturovaný prompt s plánováním zvyšuje stabilitu na vícekrokových úlohách.

— Editorial Team