Kurs vibe coding z Claude Code · Moduł 14: Klon Pinteresta
Lupa na skarby: wyszukiwanie po obrazie i półka sklepowa
W tej lekcji10
Papuga Pola ma w telefonie zdjęcie zachodu słońca nad portem i chce znaleźć w Treasure Map coś w tym samym nastroju. Nikt nie wpisze w wyszukiwarkę "ten odcień pomarańczu". Potrzebna jest lupa: wrzucasz zdjęcie, dostajesz podobne piny. Część pinów to przy okazji rzeczy do kupienia, na przykład skrzynia albo mapa, więc pod wynikami przyda się półka z ceną i linkiem do sklepu. Wyszukiwanie obrazem da się jednak zbudować na kilka sposobów, które różnią się kosztem i tym, dokąd trafia zdjęcie. Dlatego zanim powstanie choć linia kodu, wysyłasz zwiadowcę.
Czego się nauczysz
- wysłać subagenta na zwiad i dostać notatkę decyzji, w której niepewne liczby są oznaczone;
- zbudować najprostsze podejście lokalnie, z wyraźnym miejscem na usługę w przyszłości;
- sprawdzić przesłany obraz na serwerze po pierwszych bajtach i rozmiarze;
- pokazać cenę w walucie produktu i bezpieczny link do sklepu.
Zwiad przed rejsem
Subagenta do researchu znasz z lekcji 5_4: pracuje we własnym kontekście i wraca z samym meldunkiem, więc Twoja rozmowa nie tonie w notatkach. Tym razem pytanie jest projektowe:
Nie pisz kodu. Użyj subagenta, żeby porównać trzy sposoby wyszukiwania
podobnych zdjęć w aplikacji Next.js: (1) zewnętrzna usługa analizy
obrazów, (2) embeddingi i baza wektorowa, (3) dopasowanie po kolorze
dominującym i tagach pinów. Dla każdego: co opuszcza aplikację, koszt,
wady. Każda liczba z linkiem do strony dostawcy, a czego nie
potwierdzisz, oznacz "do sprawdzenia". Wynik zapisz jako tabelę
w docs/wyszukiwanie-obrazem.md.Embedding to lista liczb, w którą model zamienia obraz albo tekst. Podobne obrazy dostają podobne listy, a baza wektorowa szybko znajduje listy najbliższe podanej. Otwórz w Cursorze docs/wyszukiwanie-obrazem.md. Najważniejsze dwie kolumny tabeli wyglądały u nas tak:
| Podejście | Co opuszcza aplikację | Koszt |
|---|---|---|
| 1. Usługa analizy obrazów | całe zdjęcie trafia do dostawcy | cena za 1000 zapytań: do sprawdzenia |
| 2. Embeddingi i baza wektorowa | zdjęcie albo jego wektor, zależnie od modelu | do sprawdzenia |
| 3. Kolor i tagi | nic | bez opłat |Notatkę czytasz jak meldunek z lekcji 5_4, czyli w trzech krokach. Najpierw sprawdzasz, czy każda liczba ma link do strony dostawcy, a nie do bloga. Potem, czy przy niepewnych stoi "do sprawdzenia". Na końcu, co z tego wynika dla Ciebie. Typowy błąd agenta to cennik i limity podane pewnym tonem bez źródła, na przykład dokładna kwota za tysiąc zapytań. Taką liczbę wykreślasz albo prosisz o link. Decyzja na dziś to podejście 3: zero kosztów i zero danych za burtą. Ma jednak znaną wadę: łapie nastrój, a nie przedmiot, więc dwa zupełnie różne niebieskie zdjęcia uzna za podobne.
Polecenie dla Claude Code
Polecenie dla Claude Code:
/plan Zbuduj podejście 3 z docs/wyszukiwanie-obrazem.md. Strona /search
z komponentem CameraSearch: wybór pliku oraz przeciągnij i upuść,
podgląd zdjęcia. Route Handler POST /api/visual-search: tylko JPEG,
PNG i WebP do 5 MB, typ po pierwszych bajtach, jak MP4 w lekcji 5_4.
Kolor dominujący liczy biblioteka sharp w lib/imageFeatures.ts; oznacz
tam miejsce na usługę zewnętrzną. Zdjęcia nie zapisuj i nie loguj.
Wynik: piny o najbliższym kolorze i ich najczęstsze tagi, nad nimi
półka produktów z ceną w walucie produktu. Najpierw testy
lib/visualSearch.ts i lib/imageCheck.ts. Na koniec testy, lint,
npx tsc --noEmit i npm run build.sharp to biblioteka do obróbki obrazów w Node.js. Claude doda ją do projektu poleceniem npm install sharp.
Co napisał Claude: odprawa na serwerze
Atrybut accept w polu pliku to tylko podpowiedź dla okna wyboru, co wiesz z lekcji 5_4. Prawdziwa kontrola stoi w lib/imageCheck.ts:
// lib/imageCheck.ts
export function detectImageKind(head: Uint8Array): ImageKind | null {
const ascii = (from: number, to: number) => String.fromCharCode(...head.slice(from, to));
if (head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff) return "jpeg";
if (ascii(1, 4) === "PNG" && head[0] === 0x89) return "png";
if (ascii(0, 4) === "RIFF" && ascii(8, 12) === "WEBP") return "webp";
return null;
}Każdy z trzech formatów zaczyna się od stałego podpisu. JPEG ma bajty FF D8 FF, PNG bajt 0x89 i napis PNG, a WebP napis RIFF i cztery bajty dalej WEBP. Funkcja patrzy tylko na dwanaście pierwszych bajtów i nie sprawdza, czy obrazek da się otworzyć. Sprawdza tylko, czy plik nie udaje obrazka. Trasa app/api/visual-search/route.ts stawia kontrole po kolei:
// app/api/visual-search/route.ts
if (file.size > MAX_IMAGE_BYTES) {
return Response.json({ error: "Zdjęcie może mieć najwyżej 5 MB." }, { status: 413 });
}
const bytes = Buffer.from(await file.arrayBuffer());
if (!detectImageKind(bytes.subarray(0, 12))) {
return Response.json({ error: "Przyjmujemy tylko JPEG, PNG i WebP." }, { status: 415 });
}Rozmiar idzie pierwszy, bo file.size jest gotowy od razu, a arrayBuffer() robi kopię całego pliku. Samo request.formData() wczytało już jednak całe żądanie, więc przy dużych plikach przydaje się kontrola nagłówka Content-Length z lekcji 5_4. Wyżej stoją request.formData().catch(() => null) i kontrola instanceof File z lekcji 5_4, a brak pliku daje 400. Pięć megabajtów to reguła naszego klonu, nie standard. U nas plik tekstowy wysłany jako kot.jpg z typem image/jpeg dostał 415, plik 6 MB dostał 413, a zdjęcie zatoki odpowiedź 200.
Co napisał Claude: kolor, tagi i szew
Otwórz lib/imageFeatures.ts:
// lib/imageFeatures.ts
// SZEW: tu kiedyś podłączymy zewnętrzną usługę analizy obrazów.
// Zanim zdjęcie opuści aplikację, użytkownik musi się na to zgodzić (patrz docs/wyszukiwanie-obrazem.md).
export async function extractFeatures(bytes: Buffer): Promise<ImageFeatures> {
const { dominant } = await sharp(bytes).stats();
const color = "#" + [dominant.r, dominant.g, dominant.b].map((v) => v.toString(16).padStart(2, "0")).join("");
return { color };
}Szew to jedno miejsce, w którym kiedyś podmienisz implementację, a reszta aplikacji tego nie zauważy. Trasa zna tylko extractFeatures i jej wynik ImageFeatures. stats() z sharp zwraca statystyki obrazka, a wśród nich kolor dominujący jako trzy liczby od 0 do 255, które funkcja zamienia na zapis #rrggbb. Dalej lib/visualSearch.ts:
// lib/visualSearch.ts
export function findSimilarPins(color: string, pins: readonly Pin[], limit = 12): Pin[] {
return [...pins]
.sort((a, b) => colorDistance(color, a.dominantColor) - colorDistance(color, b.dominantColor))
.slice(0, limit);
}colorDistance liczy odległość między kolorami jak między punktami w przestrzeni czerwony, zielony i niebieski. To prosta miara, a nie ludzkie oko, ale do nastroju wystarczy. [...pins] kopiuje listę przed sortowaniem, jak w lekcji 12_1. Obok stoi relatedTags, która zlicza tagi znalezionych pinów i zwraca pięć najczęstszych. Nazwa jest uczciwa: to hasła powiązane z wynikami, a nie rozpoznane na zdjęciu. U nas zdjęcie zachodu dało kolor #f8a858, na pierwszym miejscu "Zachód nad portem", a wśród haseł "port", "zachód" i "niebo".
Prywatność: zdjęcie zostaje w porcie
Zdjęcie z telefonu to często dane osobowe: twarze, wnętrze mieszkania, dokument na stole. Nasz klon ma trzy proste zasady. Zdjęcie żyje tylko w pamięci jednego żądania, więc nie zapisujemy go na dysk. Nie trafia do logów. Nie opuszcza aplikacji. Gdy kiedyś podłączysz usługę z podejścia 1 albo 2, szew wymaga zgody użytkownika przed wysłaniem zdjęcia. Napis pod strefą upuszczania mówi to wprost: "Zdjęcie nie jest zapisywane ani wysyłane dalej".
Co napisał Claude: strefa upuszczania
Stary kod obiecywał "drag and drop", a obsługiwał tylko pole pliku. Otwórz components/CameraSearch.tsx:
// components/CameraSearch.tsx
onDragOver={(e) => {
e.preventDefault();
setDragging(true);
}}
onDrop={(e) => {
e.preventDefault();
setDragging(false);
const dropped = e.dataTransfer.files[0];
if (dropped) search(dropped);
}}MDN wyjaśnia oba preventDefault. Zdarzenie drop przychodzi tylko wtedy, gdy element anulował dragover. Bez anulowania drop przeglądarka może za to sama otworzyć albo pobrać upuszczony plik. dataTransfer.files to lista upuszczonych plików. search wysyła plik w FormData, tak samo jak pole wyboru. Podgląd powstaje z URL.createObjectURL w efekcie ze sprzątaniem, wzorem z lekcji 9_3. U nas w Chrome upuszczony plik PNG dał te same wyniki co wybrany z okna, a plik tekstowy pokazał komunikat "Przyjmujemy tylko JPEG, PNG i WebP."
Co napisał Claude: półka sklepowa
Pin, który można kupić, ma dodatkowe pole product?: Product. Znak zapytania oznacza pole opcjonalne, a sam produkt opisuje typ:
// lib/types.ts
export interface Product {
price: number;
currency: string; // kod ISO 4217, np. "PLN", "EUR"
inStock: boolean;
rating: number; // 0-5
merchant: string;
url: string;
}Stary kod pisał cenę jako $ i liczbę, więc skrzynia za 149 złotych udawała towar w dolarach. Wersja Claude, lib/price.ts:
// lib/price.ts
export function formatPrice(product: Pick<Product, "price" | "currency">, locale = "pl-PL"): string {
return new Intl.NumberFormat(locale, { style: "currency", currency: product.currency }).format(product.price);
}Według MDN przy style: "currency" pole currency jest wymagane i nie ma wartości domyślnej. Przyjmuje kody ISO 4217, takie jak "USD" czy "EUR". U nas wyszło "149,00 zł", "24,50 €", "39,99 USD" i "1299,00 zł": cztery cyfry zostają razem, jak w lekcji 12_2. Ocena to product.rating.toFixed(1), czyli napis z jedną cyfrą po kropce, na przykład "4.7". Link do sklepu:
// components/ProductShelf.tsx
<a href={product.url} target="_blank" rel="noopener noreferrer">
Do sklepu
</a>MDN opisuje noopener tak: nowa karta nie dostaje window.opener, więc obca strona nie może sterować naszą. noreferrer dodatkowo nie wysyła sklepowi nagłówka Referer z adresem strony, z której przyszedł kursant. Gdy inStock jest false, zamiast linku stoi napis "Brak w magazynie".
Przegląd kapitana
- Kontrola na serwerze. Udawany obrazek wyślesz bez formularza:
curl -F 'image=@notatka.txt;type=image/jpeg' localhost:3000/api/visual-searchma zwrócić błąd z kodem 415. - Nic za burtę. Wyszukaj w
lib/iapp/api/słowafetch(,writeFileiconsole.log. W ścieżce zdjęcia nie ma żadnego. Typowy błąd agenta to gotowe wywołanie usługi w kodzie "na przyszłość", bez zgody i bez wpisu w notatce. - Waluta. Wyszukaj
$izłwcomponents/. Cena ma przechodzić tylko przezformatPrice. - Upuszczanie obok strefy. Upuść zdjęcie kawałek obok ramki. Przeglądarka otworzy plik zamiast strony, bo zdarzenie
dropobsługuje tylko strefa. MDN radzi anulować je też na całym oknie, ale tylko dla plików.
Następny krok
Gdy przegląd przejdzie, poproś o commit "Wyszukiwanie obrazem i półka sklepowa". Potem mały krok: "Upuszczony obok strefy plik nie może otwierać się w karcie; anuluj drop na window tylko dla plików". Klon ma już siatkę, skrzynie i lupę, ale wszystko trzyma w pamięci na globalThis: restart serwera i tablice znikają. W kolejnych lekcjach tej lokacji Claude zapisze piny i tablice w bazie danych i uporządkuje trasy API, a w następnej lokacji rejs płynie dalej. W edytorze poniżej czeka lupa w miniaturze: wybierz kolor, zobacz najbliższe piny i ceny w walucie każdego produktu.
Zapamiętaj: lupa pokazuje tylko to, co leży pod szkłem, a zanim wyślesz cudzy obraz za burtę, pytasz właściciela o zgodę.
Kod do tej lekcji: App.tsx
// Lupa w miniaturze: najbliższe kolory, powiązane hasła i ceny w walucie produktu
import { useState } from 'react';
interface Product {
price: number;
currency: string; // kod ISO 4217
inStock: boolean;
rating: number;
merchant: string;
url: string;
}
interface Pin {
id: string;
title: string;
dominantColor: string;
tags: string[];
product?: Product;
}
// Ceny i sklepy są wymyślone dla naszego klonu
const PINS: Pin[] = [
{ id: 'p1', title: 'Zatoka o świcie', dominantColor: '#289888', tags: ['morze', 'świt', 'zatoka'] },
{ id: 'p2', title: 'Zachód nad portem', dominantColor: '#f8a858', tags: ['zachód', 'port', 'niebo'] },
{ id: 'p3', title: 'Głębia oceanu', dominantColor: '#487898', tags: ['morze', 'głębia', 'nurkowanie'] },
{ id: 'p4', title: 'Złoto w skrzyni', dominantColor: '#f88808', tags: ['skarb', 'złoto', 'skrzynia'], product: { price: 149, currency: 'PLN', inStock: true, rating: 4.66, merchant: 'Kram pod Kotwicą', url: 'https://example.com/skrzynia' } },
{ id: 'p5', title: 'Stara mapa', dominantColor: '#986848', tags: ['mapa', 'skarb', 'papier'], product: { price: 24.5, currency: 'EUR', inStock: true, rating: 4.2, merchant: 'Map & Co', url: 'https://example.com/mapa' } },
{ id: 'p6', title: 'Bandera w porcie', dominantColor: '#d8a898', tags: ['port', 'bandera', 'statek'], product: { price: 39.99, currency: 'USD', inStock: false, rating: 3.85, merchant: 'Flag Shop', url: 'https://example.com/bandera' } },
{ id: 'p7', title: 'Pokład z drewna', dominantColor: '#785838', tags: ['statek', 'drewno', 'pokład'], product: { price: 1299, currency: 'PLN', inStock: true, rating: 4.9, merchant: 'Szkutnik Jan', url: 'https://example.com/poklad' } },
{ id: 'p8', title: 'Nocna wachta', dominantColor: '#080858', tags: ['noc', 'niebo', 'statek'] },
];
function hexToRgb(hex: string): [number, number, number] {
const n = parseInt(hex.slice(1), 16);
return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
}
function colorDistance(a: string, b: string) {
const [r1, g1, b1] = hexToRgb(a);
const [r2, g2, b2] = hexToRgb(b);
return Math.hypot(r1 - r2, g1 - g2, b1 - b2);
}
function findSimilarPins(color: string, pins: readonly Pin[], limit: number) {
return [...pins].sort((a, b) => colorDistance(color, a.dominantColor) - colorDistance(color, b.dominantColor)).slice(0, limit);
}
function relatedTags(pins: readonly Pin[], limit: number) {
const counts = new Map<string, number>();
for (const pin of pins) for (const tag of pin.tags) counts.set(tag, (counts.get(tag) ?? 0) + 1);
return [...counts].sort((a, b) => b[1] - a[1]).slice(0, limit).map(([tag]) => tag);
}
function formatPrice(product: Product) {
return new Intl.NumberFormat('pl-PL', { style: 'currency', currency: product.currency }).format(product.price);
}
const PRESETS = ['#f5a55a', '#2a9a86', '#7a5a3a', '#101060'];
export default function App() {
const [color, setColor] = useState('#f5a55a');
const [agentPrices, setAgentPrices] = useState(false);
const results = findSimilarPins(color, PINS, 4);
const tags = relatedTags(results, 5);
const products = results.filter((pin) => pin.product);
return (
<div className="min-h-screen space-y-4 bg-amber-50 p-4 text-zinc-900">
<h1 className="text-xl font-bold">Lupa na skarby</h1>
<div className="flex flex-wrap items-center gap-2">
<label className="flex items-center gap-2">
Kolor zdjęcia:
<input type="color" value={color} onChange={(e) => setColor(e.target.value)} />
</label>
{PRESETS.map((preset) => (
<button key={preset} type="button" onClick={() => setColor(preset)} aria-label={'Kolor ' + preset} className="size-8 rounded-full border border-zinc-400" style={{ backgroundColor: preset }} />
))}
</div>
<ol className="space-y-1">
{results.map((pin) => (
<li key={pin.id} className="flex items-center gap-2">
<span className="inline-block size-5 rounded" style={{ backgroundColor: pin.dominantColor }} />
{pin.title} <span className="text-xs text-zinc-500">odległość {Math.round(colorDistance(color, pin.dominantColor))}</span>
</li>
))}
</ol>
<p className="text-sm">Powiązane hasła: {tags.join(', ')}</p>
<section aria-labelledby="shelf" className="rounded-xl bg-white p-3">
<h2 id="shelf" className="font-semibold">Do kupienia</h2>
{products.length === 0 && <p className="text-sm text-zinc-500">Wśród wyników nie ma produktów.</p>}
<ul className="mt-2 space-y-2">
{products.map(({ id, title, product }) =>
product ? (
<li key={id} className="flex flex-wrap items-center gap-2">
<strong>{agentPrices ? '$' + product.price : formatPrice(product)}</strong>
{title} · {product.merchant} · ★ {product.rating.toFixed(1)}
{product.inStock ? (
<a href={product.url} target="_blank" rel="noopener noreferrer" className="rounded-full bg-red-600 px-3 py-1 text-sm text-white">
Do sklepu
</a>
) : (
<span className="text-sm text-zinc-500">Brak w magazynie</span>
)}
</li>
) : null,
)}
</ul>
</section>
<label className="flex items-center gap-2 text-sm">
<input type="checkbox" checked={agentPrices} onChange={(e) => setAgentPrices(e.target.checked)} />
Wersja agenta: znak $ na sztywno zamiast waluty produktu
</label>
</div>
);
}Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Które podejście do wyszukiwania obrazem wybrał kapitan na start i dlaczego?
2. Co subagent ma wpisać przy liczbie, której nie potwierdził na stronie dostawcy?
To 2 z 9 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Układanie w pionie
Uporządkuj kroki trasy POST /api/visual-search:
- Układanie w poziomie
Ułóż linię interfejsu Product z kodem waluty:
- Klikanie w kolejności
Kliknij elementy, aby zbudować linię, która w onDrop odczytuje upuszczony plik:
- Edytor kodu
Stwórz stronę board
- Układanie w pionie
Uporządkuj pracę nad wyborem podejścia do lupy:
- Klikanie w kolejności
Kliknij elementy, aby zbudować ocenę produktu z jedną cyfrą po kropce:
- Układanie w poziomie
Ułóż wyrażenie z formatPrice, które pokazuje cenę w walucie produktu:
- Edytor kodu
Stwórz visual search interface
- Układanie w pionie
Uporządkuj drogę od zdjęcia do sklepu w Treasure Map:
Zadania po tej lekcji
- PytanieQuiz: Wybór podejścia do lupy
- PytanieQuiz: Niepewne liczby w notatce
- Ułóż w kolejnościSortowanie: Odprawa zdjęcia na serwerze
- PytanieQuiz: Szew na usługę zewnętrzną
- Ułóż w kolejnościSortowanie: Pole waluty w Product
- Kliknij w kolejnościBudowanie: Upuszczony plik
- Zadanie z kodemPraktyka: Board page
- PytanieQuiz: Powiązane hasła
- Ułóż w kolejnościSortowanie: Od zwiadu do decyzji
- PytanieQuiz: Brak w magazynie
- Kliknij w kolejnościBudowanie: Ocena z jedną cyfrą
- Ułóż w kolejnościSortowanie: Cena w walucie produktu
- PytanieQuiz: Bezpieczny link do sklepu
- Zadanie z kodemPraktyka: Camera search
- PytanieQuiz: Strefa upuszczania
- Ułóż w kolejnościSortowanie: Lupa od zdjęcia do sklepu
- PytanieQuiz: Prywatność przesłanych zdjęć
- PytanieQuiz: Kontrola typu pliku