# Twórz talie Cramdeck przy pomocy ChatGPT lub Claude > **Wersja 1.0.0** · Aktualizacja 2026-04-26 · Zobacz [CHANGELOG](./CHANGELOG.md) > **Dla kogo:** dla Ciebie — użytkownika Cramdeck, który chce wykorzystać > asystenta AI (ChatGPT, Claude, Gemini lub innego), aby generować talie > fiszek i dodawać je do swojego konta bez kopiowania karta po karcie. > > *English version: [`end-user-setup.md`](./end-user-setup.md).* Ten przewodnik pokazuje krok po kroku, jak skonfigurować asystenta AI, żeby na zwykłą prośbę typu *"zrób mi 30-kartową talię o rewolucji francuskiej"* talia w kilka sekund pojawiła się w Twojej bibliotece Cramdeck. Są dwa schematy integracji. Wybierz ten, który pasuje do Twoich narzędzi: | Schemat | Co robi AI | Czas konfiguracji | Najlepszy do | |---|---|---|---| | **Tylko autorstwo** | Zwraca plik `.deck.md`, który importujesz samodzielnie | 2 minuty | Darmowy ChatGPT, Claude.ai, dowolny LLM, w którym możesz wkleić prompt | | **Z narzędziem (tool-use)** | Wywołuje API Cramdeck bezpośrednio i sam dodaje talie | 10 minut | Custom GPT (Plus), projekty Claude z narzędziami, MCP, integracje własne | Oba schematy produkują identyczną zawartość; różnią się tylko tym, gdzie odbywa się przesłanie do Cramdeck. --- ## Krok 1 — Utwórz osobisty token dostępu (PAT) Token jest potrzebny tylko do schematu **z narzędziem**. Jeśli chcesz schemat **tylko autorstwo**, przejdź od razu do Kroku 2. 1. W Cramdeck otwórz **Profil → Integracje**. 2. Kliknij **Utwórz token**. 3. Nazwij go tak, żebyś go zapamiętał — np. `ChatGPT custom GPT`, `Projekt Claude`. 4. Wybierz uprawnienia (scope): - `decks:read` — pozwala AI listować i odczytywać Twoje talie (zalecane). - `decks:write` — pozwala AI tworzyć i edytować talie (wymagane, żeby AI mogło dodawać talie za Ciebie). 5. Kliknij **Wygeneruj**. 6. **Skopiuj token od razu.** Zaczyna się od `cdk_pat_…` i wyświetla się dokładnie jeden raz. Nigdy nie zapisujemy postaci jawnej — jeśli go zgubisz, musisz wygenerować nowy. Traktuj token jak hasło. Każdy, kto go ma, może czytać i modyfikować Twoje talie w ramach przyznanych uprawnień. --- ## Krok 2 — Schemat „tylko autorstwo" (dowolny LLM) Ten schemat sprawdzi się, jeśli nie chcesz konfigurować akcji ani narzędzia. AI generuje treść `.deck.md`, Ty zapisujesz ją do pliku i importujesz przez UI Cramdeck. ### Konfiguracja jednorazowa 1. Otwórz wybrany model językowy (darmowy ChatGPT, Claude.ai, Gemini itp.). 2. Rozpocznij nowy czat / projekt / pole „custom instructions". 3. Otwórz **prompt systemowy autora Cramdeck**: 4. Skopiuj jego pełną treść i wklej w jedno z miejsc: - **ChatGPT** — pole *Custom Instructions* w sekcji „How would you like ChatGPT to respond?", **albo** wiadomość systemowa w Custom GPT, **albo** po prostu pierwsza wiadomość czatu. - **Claude.ai** — *Project knowledge*, *albo* pole *System prompt* w workbenchu, *albo* pierwsza wiadomość czatu. - **Inne narzędzia** — znajdź pole oznaczone „system prompt", „instructions" lub „persona" i wklej tam. ### Codzienne użycie W czacie z tym asystentem możesz teraz prosić o rzeczy w stylu: - *"Zrób mi 20-kartową talię o cyklu Krebsa, biologia, po angielsku."* - *"Talia francuskiego A1 — 25 słów, które usłyszę zamawiając kawę."* - *"Zamień tę listę pytań rekrutacyjnych z TypeScripta w talię fiszek."* Asystent odpowie **dokładnie jednym blokiem kodu Markdown** zawierającym kompletny dokument `.deck.md`. Aby go zaimportować: 1. Kliknij przycisk kopiowania na bloku kodu. 2. Zapisz zawartość do pliku. Konwencja to `.deck.md`, np. `cykl-krebsa.deck.md`. 3. W Cramdeck kliknij **Moje talie → ⋮ → Importuj talię** i wgraj plik. 4. Talia pojawi się w Twojej bibliotece, gotowa do nauki. To wszystko. Bez tokenów, bez konfiguracji API. --- ## Krok 3 — Schemat z narzędziem (ChatGPT custom GPT) Skorzystaj z tego, jeśli masz ChatGPT Plus i chcesz wrażenia *"powiem mu, talia się pojawia"*. ### Stwórz custom GPT 1. W ChatGPT kliknij **Explore GPTs → Create**. 2. Pomiń kreatora konwersacyjnego. Kliknij zakładkę **Configure**. 3. **Name**: „Cramdeck Builder" (albo dowolnie). 4. **Description**: „Dodaje wygenerowane przez AI talie fiszek do mojego konta Cramdeck." 5. **Instructions**: wklej pełną treść pliku . 6. **Capabilities**: wyłącz wszystko, czego nie potrzebujesz (Web Browsing, Code Interpreter, DALL·E), chyba że konkretnie chcesz z tych funkcji korzystać. ### Dodaj akcję (Action) 1. Przewiń do **Actions → Create new action**. 2. **Authentication**: - Type: **API Key** - API Key: wklej swój token `cdk_pat_…`. - Auth Type: **Bearer**. 3. **Schema**: wklej pełną treść z . 4. **Privacy policy URL**: link do Twojej polityki prywatności (ChatGPT wymaga, jeśli chciałbyś GPT opublikować — dla wersji prywatnej wystarczy placeholder). 5. Kliknij **Save**. ### Test W nowym czacie ze swoim custom GPT: > Wypisz moje talie. Za pierwszym razem ChatGPT poprosi o zgodę na wywołanie API Cramdeck — zatwierdź. Powinieneś zobaczyć listę swoich talii. A teraz: > Zrób mi 15-kartową talię o rewolucji francuskiej. Otaguj „historia" > i „liceum". Widoczność: prywatna. W ciągu kilku sekund odśwież Cramdeck — talia powinna już tam być. --- ## Krok 4 — Schemat z narzędziem (Claude Projects) Jeśli korzystasz z Claude.ai z funkcją Projects: 1. Utwórz nowy projekt. 2. **Custom instructions**: wklej treść `ai-agent-tool-use-prompt.md` (ten sam plik co wyżej). 3. **Project knowledge**: dodaj (lub zalinkuj) pięć przykładowych talii z oraz specyfikację OpenAPI z `/api/v1/integrations/openapi.json`. To daje Claude konkretne przykłady poprawnych plików `.deck.md`. 4. Do faktycznego wykonywania wywołań API użyj natywnego API Claude z funkcją Tool Use plus małego adaptera, który mapuje wywołania narzędzi Claude na żądania HTTP do `https://your-cramdeck-host/api/v1/integrations/...` z Twoim PAT w nagłówku `Authorization`. Zespół Cramdeck pracuje nad serwerem MCP, który wyeliminuje ten krok — postępy śledź na `/docs/integrations`. Jeśli pisanie adaptera Cię nie kręci, użyj schematu **„tylko autorstwo"** (Krok 2) wewnątrz Claude — działa świetnie z Claude Projects i nie wymaga ani jednej linii kodu. --- ## Krok 5 — Test end-to-end Wypróbuj poniższe prompty, żeby sprawdzić, czy wszystkie cztery typy treści renderują się poprawnie w Cramdeck: | Test | Prompt | Co sprawdzić | |---|---|---| | Tekst zwykły | *„5-kartowa talia podstawowych hiszpańskich powitań."* | Tekst po obu stronach to zwykły tekst. | | Markdown | *„5-kartowa talia o list comprehensions w Pythonie z przykładami kodu."* | Bloki kodu mają podświetlanie składni. | | HTML | *„5-kartowa talia popularnych związków chemicznych (H2O, CO2 itp.). Użyj HTML do wzorów."* | Indeksy dolne renderują się poprawnie (H2O). | | LaTeX | *„5-kartowa talia podstawowych tożsamości rachunku różniczkowego. Użyj LaTeX do wzorów."* | Równania renderują się jako matematyka, a nie surowe `\frac{...}`. | | Obrazy | *„5-kartowa talia flag krajów europejskich. Użyj flagcdn.com do obrazków."* | Pojawiają się obrazy flag, alt text jest ustawiony. | Jeśli któryś z tych testów nie zachowuje się tak, jak powinien, sprawdź **Profil → Integracje → log audytowy**, żeby zobaczyć dokładnie, co zostało wysłane. --- ## Rozwiązywanie problemów | Objaw | Prawdopodobna przyczyna | Co zrobić | |---|---|---| | `401 UNAUTHORIZED` | Brak tokenu, niepoprawny lub skopiowany z dodatkowymi spacjami. | Wygeneruj PAT ponownie i wklej go czysto. | | `401 TOKEN_REVOKED` | Cofnąłeś token (lub wygasł), ale AI nadal go używa. | Wygeneruj nowy PAT i zaktualizuj ustawienia GPT/projektu. | | `403 FORBIDDEN` | Token nie ma uprawnienia `decks:write`. | Wygeneruj PAT ponownie i zaznacz oba scope'y: `decks:read` i `decks:write`. | | `400 PARSE_FAILED` | AI wygenerowało niepoprawny `.deck.md` (zwykle brakuje `lang:` we frontmatter). | Powiedz: „lang jest wymagane we frontmatter; użyj kodów BCP-47 takich jak en, fr, pl." | | `400 SCHEMA_INVALID` z `imageUrl` | AI użyło URL `http://` lub data URI (base64). | Powiedz: „URL obrazków musi być https — zamień na https albo usuń obrazek." | | `400 TOO_MANY_CARDS` | AI zbudowało talię z więcej niż 250 fiszek. | Poproś o podział na kilka talii po max 250 fiszek. | | `429 RATE_LIMITED` | Przekroczyłeś limit zapytań na minutę. | Poczekaj 60 sekund i spróbuj jeszcze raz. | | Talia importuje się, ale wyświetla się dziwnie | Niepoprawny `frontType` / `backType` w `extras`. | Powiedz wprost: „użyj frontType: latex" / „użyj frontType: html". | Jeśli problem się powtarza, zarówno **prompt autora** jak i **prompt narzędziowy** zawierają sekcje „Common rejections" / „Error envelope", które AI przeczyta przy następnej turze — czasem wystarczy wskazać mu jego własne instrukcje. --- ## Prywatność i bezpieczeństwo - Twój PAT jest przechowywany **wyłącznie tam, gdzie go umieścisz** — w Twoim custom GPT, projekcie Claude albo lokalnym skrypcie. Cramdeck trzyma tylko hash bcrypt, nigdy postaci jawnej. - Każde wywołanie API jest zapisywane w Twoim **logu audytowym** (Profil → Integracje → nazwa tokenu → Aktywność). Widzisz dokładnie, które talie AI utworzyło lub zmodyfikowało. - Możesz **cofnąć** dowolny token natychmiast — Profil → Integracje. Cofnięte tokeny przestają działać w ciągu kilku sekund; AI zacznie dostawać `401 TOKEN_REVOKED` i straci możliwość czytania lub modyfikowania czegokolwiek. - Nadawaj tokenom wąskie uprawnienia. Jeśli AI ma tylko dodawać nowe talie, daj mu `decks:write`, a nie `decks:read`. Jeśli ma tylko czytać (np. do analiz), daj mu wyłącznie `decks:read`. --- ## Co dalej Aktualne API skupia się na operacjach na **całych taliach** (utwórz, listuj, czytaj, aktualizuj metadane). Wkrótce pojawi się: - CRUD na pojedynczych fiszkach (`POST /decks/{id}/cards`, `PATCH /cards/{id}`). - Pierwszostronny serwer MCP, dzięki któremu dowolny klient zgodny z MCP (Claude Desktop, Cursor, Continue) będzie mógł korzystać z Cramdeck bez własnego adaptera. - Webhooki dla zdarzeń typu „talia zaimportowana". - Współdzielenie z ograniczonym zakresem (np. AI ma prawo edytować tylko jedną konkretną talię). Postępy i feedback — `/docs/integrations`.