Instrukcja użytkownika: funkcjonalność Agent Modes w OpenCode

Ten dokument wyjaśnia, do czego służy funkcjonalność Agent Modes w OpenCode i jak z niej korzystać w codziennej pracy. Jest przeznaczony zarówno dla użytkownika, który sam czyta dokumentację w Confluence, jak i dla agenta AI, który ma na jej podstawie podpowiadać kolejne kroki.

Zakładamy, że użytkownik pracuje już w środowisku OpenCode, w którym ta funkcjonalność jest dostępna. Dokument opisuje wyłącznie sposób użycia i typowe zastosowania.

Funkcjonalność składa się z dwóch głównych części:

• lokalnego RAG dla plików w aktualnej przestrzeni roboczej, czyli wyszukiwania i rozmowy z agentem na podstawie wskazanych dokumentów,
• trybów pracy, które dodają uporządkowane katalogi, komendy i zasady współpracy z agentem dla konkretnego typu zadania, np. pracy badawczej.

Najważniejsza zasada: indeks RAG jest tylko pamięcią pomocniczą. Źródłem prawdy pozostają pliki użytkownika, notatki, jawne ustalenia z rozmowy i konkretne fragmenty dokumentów.

Do czego to służy

Użyj tej funkcjonalności, gdy chcesz, żeby agent:

• znał zawartość lokalnych dokumentów, notatek, kodu albo PDF-ów,
• odpowiadał na pytania na podstawie przygotowanego zestawu plików,
• wskazywał konkretne pliki, z których pochodzą informacje,
• pomagał prowadzić pracę badawczą, przegląd literatury albo pisanie tekstu,
• pracował według wybranego trybu, np. research.

Nie traktuj indeksu RAG jako samodzielnego dowodu. Przy cytatach, faktach, warunkach, definicjach i listach agent powinien sprawdzić konkretny plik źródłowy.

Najprostszy przepływ

1. Otwórz w OpenCode katalog, w którym pracujesz.
2. Sprawdź, czy jest już przygotowany indeks dokumentów:

   /scan

3. Wskaż pliki albo katalogi, które agent ma poznać:

   /learn README.md docs src

4. Zadawaj pytania do przygotowanego zestawu plików:

   /search jak działa lokalny RAG
   /context co jest źródłem prawdy dla odpowiedzi agenta
   /ask podsumuj najważniejsze ograniczenia tej funkcjonalności

5. Jeśli dodasz albo zmienisz dokumenty, uruchom /learn ponownie dla odpowiednich ścieżek.

Komendy do pracy z dokumentami

/scan

Sprawdza, czy dla aktualnego katalogu roboczego istnieje przygotowany indeks RAG. Pokazuje status indeksu, lokalizację danych tymczasowych i listę znanych plików. Nie buduje indeksu i nie usuwa danych.

Przykład:

/scan

/learn <plik-lub-katalog...>

Buduje albo odświeża lokalny indeks RAG dla wskazanych plików i katalogów. Po wykonaniu tej komendy agent może wyszukiwać informacje w przygotowanym zestawie dokumentów.

Przykłady:

/learn README.md docs src
/learn materials notes

Alias:

/index materials notes

/search <pytanie>

Wyszukuje miejsca w dokumentach, które mogą zawierać odpowiedź. To dobra komenda, gdy chcesz znaleźć kandydatów do dalszej analizy albo sprawdzenia w plikach źródłowych.

Przykład:

/search gdzie opisano zasady weryfikacji źródeł

/context <pytanie>

Pobiera fragmenty dokumentów jako kontekst dla odpowiedzi agenta. Agent powinien użyć tych fragmentów do odpowiedzi, ale ważne twierdzenia nadal sprawdzać w konkretnych plikach.

Przykład:

/context jak należy odpowiadać na pytania o cytaty

/ask <pytanie>

Prowadzi rozmowną odpowiedź na podstawie przygotowanego indeksu. To wygodny wariant, gdy chcesz uzyskać wyjaśnienie, porównanie, streszczenie albo listę wniosków.

Przykład:

/ask czym różni się search od context

Alias:

/talk czym różni się search od context

/clear

Usuwa tymczasowe dane RAG dla aktualnego katalogu roboczego. Nie usuwa plików źródłowych użytkownika. Agent powinien pokazać, co zostanie usunięte, i poczekać na zgodę.

Przykład:

/clear

Tryby pracy

Tryb pracy to gotowy zestaw zasad, katalogów i komend dopasowany do konkretnego rodzaju pracy. Tryb pomaga agentowi lepiej rozumieć kontekst i prowadzić użytkownika przez typowy proces.

/mode-list

Pokazuje dostępne tryby pracy.

/mode-list

/mode-init <tryb>

Włącza wskazany tryb pracy w aktualnym katalogu roboczym. Agent najpierw pokazuje plan zmian i ewentualne konflikty. Zmiany powinny zostać wykonane dopiero po zgodzie użytkownika.

/mode-init research

Po włączeniu trybu nowe komendy mogą nie pojawić się natychmiast w bieżącej sesji OpenCode. Jeśli ich nie widzisz, zamknij i ponownie uruchom OpenCode w tym samym katalogu roboczym.

/mode-status

Pokazuje tryby aktywne w aktualnym katalogu roboczym.

/mode-status

/mode-update

Sprawdza możliwość odświeżenia trybu. Agent powinien pokazać status i plan, a zmiany wykonywać tylko po zgodzie użytkownika.

/mode-update research

/mode-remove

Pokazuje plan ręcznego wyłączenia trybu. Agent nie powinien usuwać plików bez osobnej zgody użytkownika. Szczególna ostrożność dotyczy katalogów, które mogą zawierać dane użytkownika.

/mode-remove research

Tryb research

research to tryb asystenta badawczego. Pomaga prowadzić przegląd literatury, porządkować materiały, budować argumentację i przechodzić od notatek do szkicu tekstu.

Po włączeniu trybu użytkownik pracuje z katalogami:

• materials/ - literatura, artykuły, książki, PDF-y i materiały źródłowe,
• notes/ - notatki z lektur, streszczenia, pytania i obserwacje,
• calculations/ - obliczenia, tabele, wyniki eksperymentów i analizy,
• draft/ - konspekty, sekcje tekstu, abstrakty i wersje robocze.

Typowy przepływ pracy:

1. Włóż literaturę i materiały źródłowe do materials/.
2. Dodaj notatki, streszczenia albo pytania do notes/.
3. Poproś agenta o rozpoznanie materiałów:

   /scan

4. Przygotuj indeks dla domyślnych katalogów trybu:

   /learn

   W trybie research domyślnym zestawem dokumentów są materials/ i notes/.

5. Pytaj o literaturę, stanowiska, definicje, metody, wyniki, ograniczenia i luki badawcze:

   /search jakie definicje pojęcia X pojawiają się w literaturze
   /ask porównaj stanowiska autorów dotyczące metody Y
   /context co literatura mówi o ograniczeniach podejścia Z

6. Gdy przechodzisz do pisania, poproś agenta o plan, konspekt albo szkic. Agent powinien zapisywać treści w draft/ tylko po uzgodnieniu z użytkownikiem.

Jak formułować dobre pytania

Lepsze pytania są konkretne i zawierają kontekst:

/search ograniczenia metody analizy sentymentu w badaniach nad opiniami studentów
/ask porównaj definicje kompetencji cyfrowych u trzech najczęściej cytowanych autorów
/context argumenty przeciwko użyciu ankiety jako jedynej metody badawczej

Słabsze pytania są zbyt krótkie albo wieloznaczne:

/search metoda
/ask literatura
/context wyniki

Dla dokładnych terminów, warunków, list i cytatów poproś agenta o weryfikację w plikach źródłowych. RAG pomaga znaleźć kandydatów, ale nie zastępuje sprawdzenia tekstu.

Typowe scenariusze

Użytkownik chce porozmawiać z agentem o kilku PDF-ach

1. Umieść PDF-y w katalogu roboczym, np. w materials/.
2. Uruchom:

   /learn materials

3. Zadawaj pytania:

   /ask jakie są główne tezy tych dokumentów
   /search gdzie dokumenty omawiają ograniczenia metody

4. Przy ważnych odpowiedziach agent powinien sprawdzić fragmenty w plikach PDF.

Użytkownik chce rozpocząć pracę badawczą

1. Włącz tryb:

   /mode-init research

2. Jeśli komendy trybu nie są widoczne, zamknij i ponownie uruchom OpenCode w tym samym katalogu roboczym.
3. Włóż literaturę do materials/ i notatki do notes/.
4. Uruchom:

   /scan
   /learn

5. Poproś agenta o pomoc:

   /ask pomóż mi sformułować pytanie badawcze na podstawie materiałów

Użytkownik chce sprawdzić konkretny termin

1. Sformułuj pytanie z pełnym kontekstem, nie samym hasłem.
2. Użyj:

   /search dokładny termin i kontekst, w którym powinien występować

3. Agent powinien potraktować wynik RAG jako kandydata i sprawdzić tekst źródłowy przed udzieleniem pewnej odpowiedzi.

Użytkownik zmienił dokumenty

Po dodaniu, usunięciu albo zmianie plików uruchom ponownie:

/learn <plik-lub-katalog...>

W trybie research zwykle wystarczy:

/learn

Ograniczenia i zasady bezpieczeństwa

Ta funkcjonalność:

• nie zastępuje ręcznej weryfikacji cytatów i faktów,
• nie traktuje indeksu jako źródła prawdy,
• może nie znaleźć informacji, jeśli dokument jest skanem bez warstwy tekstowej,
• wymaga odświeżenia indeksu po zmianie dokumentów,
• nie powinna usuwać ani porządkować plików użytkownika bez jawnej zgody.

Jeśli odpowiedź wymaga pewności, poproś agenta o sprawdzenie konkretnego pliku źródłowego. Agent powinien odróżnić cytat od parafrazy i powiedzieć, gdy nie może potwierdzić informacji.

Wskazówki dla agenta AI

Agent korzystający z tej dokumentacji powinien instruować użytkownika według poniższych zasad:

• wyjaśniaj funkcjonalność jako element środowiska OpenCode, a nie jako osobne narzędzie techniczne,
• najpierw ustal cel: wyszukiwanie, streszczenie, weryfikacja, porównanie, praca badawcza, włączenie trybu albo sprzątanie,
• przed odpowiedzią opartą na dokumentach sprawdź, czy indeks istnieje,
• jeśli indeksu nie ma, zaproponuj /learn <ścieżki>,
• przy pytaniach semantycznych używaj kontekstu RAG,
• przy pytaniach faktograficznych, cytatach, listach i warunkach weryfikuj konkretne pliki źródłowe,
• w odpowiedziach wskazuj pliki, z których pochodzą informacje,
• rozróżniaj cytat, parafrazę, interpretację i wniosek,
• mów wprost, jeśli nie da się potwierdzić odpowiedzi w dostępnych plikach,
• przed zapisem większych zmian, porządkowaniem materiałów albo usuwaniem danych pokaż plan i poczekaj na zgodę,
• nie traktuj indeksu SQLite ani embeddingów jako źródła prawdy.

Minimalna instrukcja dla agenta AI

Gdy użytkownik pyta, jak korzystać z tej funkcjonalności, agent powinien:

1. Zapytać, czy chodzi o zwykłe dokumenty, czy o tryb research.
2. Dla zwykłych dokumentów polecić:

   /learn <ścieżki>
   /search <pytanie>
   /ask <pytanie>

3. Dla pracy badawczej polecić:

   /mode-init research
   /scan
   /learn
   /ask <pytanie badawcze>

4. Przypomnieć, że indeks RAG jest pamięcią pomocniczą, a odpowiedzi wymagające pewności należy weryfikować w plikach źródłowych.
5. Przy operacjach zmieniających pliki pokazać plan i poczekać na zgodę użytkownika.