Építsen egy Full-Stack Bookmark Managert az OpenCode segítségével 30 perc alatt (Lépésről lépésre)

Amit építünk

Felejtse el a funkciólistákat. Egy eszköz megtanulásának legjobb módja, ha épít vele valamit.

Ebben az útmutatóban az OpenCode-ot fogja használni — a 120K+ GitHub csillaggal rendelkező nyílt forráskódú AI kódoló agenst —, hogy a nulláról felépítsen egy teljes könyvjelzőkezelőt. Az alkalmazás a következőket fogja tartalmazni:

• Egy REST API Express.js és TypeScript használatával
• Egy SQLite adatbázis teljes szöveges kereséssel (full-text search)
• Egy címkerendszer a könyvjelzők rendszerezéséhez
• Egy egyszerű, de funkcionális frontend
• Unit tests

Minden OpenCode funkciót abban a pillanatban mutatunk be, amikor szüksége van rá — nem egy absztrakt funkciólistában. A végére tudni fogja, hogyan kell telepíteni az OpenCode-ot, konfigurálni a modelleket, használni a Build és Plan módokat, beállítani az MCP szervereket és egyedi ágenseket létrehozni — mindezt azért, mert egy valódi projekt felépítéséhez használta őket.

Idő: ~30 minutes Előfeltételek: Node.js 18+ telepítve, egy terminál (macOS, Linux, vagy WSL Windows-on) Költség: Free (az OpenCode Zen modellek használatával)

1. fázis: Az OpenCode telepítése és a projekt beállítása (5 minutes)

Az OpenCode telepítése

Nyissa meg a terminált és futtassa az alábbi parancsok egyikét:

# Option 1: npm (recommended)
npm i -g opencode-ai@latest

# Option 2: Homebrew (macOS/Linux)
brew install sst/tap/opencode

# Option 3: One-line installer
curl -fsSL https://opencode.ai/install.sh | bash

Ellenőrizze a telepítést:

opencode --version

Látnia kell a verziószámot. March 2026-tól a legújabb stabil kiadás elérhető az OpenCode GitHub repository oldalon.

A projekt könyvtár létrehozása

mkdir bookmark-manager && cd bookmark-manager
git init
npm init -y

Az OpenCode első indítása

opencode

Ez megnyitja az OpenCode TUI-ját (Terminal User Interface) — egy teljes képernyős interaktív felületet, amely a Bubble Tea segítségével készült. Alul egy chat beviteli mezőt, a fő területen pedig egy beszélgetési panelt fog látni.

Modell választása

Az első indításkor az OpenCode kérni fogja, hogy válasszon egy modellt. Három út áll rendelkezésére:

Free (Zen modellek): Gépelje be a /models parancsot és válasszon egyet a szabad Zen modellek közül. Ehhez az útmutatóhoz a Grok Code Fast 1 vagy a GLM 4.7 jól megfelel. Ezek ingyenesek és nem igényelnek API kulcsot.

Local (Ollama): Ha telepítve van az Ollama, az OpenCode automatikusan felismeri azt. Az ajánlott modell Ollama-hoz a glm-4.7:cloud.

Paid (hozza a saját kulcsát): Gépelje be a /connect parancsot az Anthropic, OpenAI, vagy Google API kulcsának összekapcsolásához. A kulcsok helyben, a ~/.local/share/opencode/auth.json fájlban tárolódnak.

Ehhez az útmutatóhoz bármelyik modell megfelel. A nagyobb képességű modellek (Claude Sonnet 4.6, GPT-5.4) jobb eredményeket produkálnak összetett feladatoknál, de az ingyenes Zen modellek mindenre képesek, amit itt építünk.

2. fázis: A projekt vázának elkészítése a Build mód használatával (4 minutes)

Az OpenCode alapértelmezés szerint Build módban indul. A Build mód teljes hozzáférést biztosít az AI ágensnek fájlok létrehozásához, kód szerkesztéséhez és parancsok futtatásához. Ez az, amire a váz elkészítéséhez szükségünk van.

Az első prompt

Írja be ezt az OpenCode chatbe:

Set up a TypeScript Node.js project with Express for a bookmark manager REST API.
Use SQLite via better-sqlite3 for the database. Add TypeScript, ts-node, and
nodemon as dev dependencies. Create a src/ directory with an index.ts entry point
that starts an Express server on port 3000.

Az OpenCode a következőket fogja tenni:

1. Létrehoz egy tsconfig.json fájlt
2. Telepíti a függőségeket a npm install segítségével
3. Létrehozza a src/index.ts fájlt az Express szerver beállításaival
4. Frissíti a package.json fájlt az indító szkriptekkel

Figyelje a TUI-t — látni fogja, ahogy az ágens terminálparancsokat hajt végre, fájlokat hoz létre, és minden lépésnél elmagyarázza, mit csinál. Ez nem kódgenerálás vákuumban; az OpenCode teljes hozzáféréssel rendelkezik a fájlrendszeréhez és termináljához.

Működés ellenőrzése

Miután az OpenCode végzett, mondja neki:

Run the server and verify it starts correctly on port 3000.

Az OpenCode futtatni fogja a npx nodemon src/index.ts parancsot, és megerősíti, hogy a szerver figyel. Olyan kimenetet kell látnia, mint: Server running on http://localhost:3000.

Mi történt az imént (Funkció: Build mód)

A Build mód az OpenCode alapértelmezett ágense. Hozzáférése van minden eszközhöz: fájlok olvasása/írása, terminál végrehajtás és kódszerkesztés. Az OpenCode dokumentáció szerint úgy tekinthet rá, mint egy AI páros programozóra, aki teljes hozzáféréssel rendelkezik a fejlesztői környezetéhez.

3. fázis: Az adatmodell és az adatbázis létrehozása (4 minutes)

A séma megtervezése

Írja be ezt a promptot:

Create a database module at src/db.ts that:
1. Initializes a SQLite database at ./data/bookmarks.db
2. Creates a bookmarks table with: id (auto-increment), url (text, unique),
   title (text), description (text, nullable), created_at (datetime),
   updated_at (datetime)
3. Creates a tags table with: id (auto-increment), name (text, unique)
4. Creates a bookmark_tags junction table for many-to-many relationships
5. Enables WAL mode for concurrent read performance
6. Creates an FTS5 virtual table for full-text search on title and description
Export a function to get the database instance.

Az OpenCode legenerálja a teljes adatbázis modult. Figyelje meg, hogyan kezeli az FTS5 (Full-Text Search 5) beállítást — ez egy olyan SQLite funkció, amely később a keresési funkciónkat fogja támogatni.

Az adatbázis inicializálása a szerver indulásakor

Import the database module in index.ts and initialize it when the server starts.
Log a confirmation message.

Az opencode.json konfiguráció létrehozása

Ez egy jó alkalom a projekt konfigurációjának bemutatására. Hozzon létre egy fájlt az OpenCode-nak mondva:

Create an opencode.json file in the project root with the project name
"bookmark-manager" and a rule that says "This is a TypeScript Express API
using better-sqlite3. Follow RESTful conventions. Use async/await. Return
JSON responses with consistent error formatting."

Ez létrehozza a projekt konfigurációs fájlt, amelyet az OpenCode indításkor beolvas. Ez tartós kontextust biztosít az AI-nak a projektről — kódolási szabványokról, architektúrális döntésekről és megkötésekről —, így nem kell ezeket minden promptban megismételnie.

4. fázis: A REST API végpontok felépítése (5 minutes)

Az útvonalak generálása

Create a routes module at src/routes/bookmarks.ts with these endpoints:
- POST /api/bookmarks — create a bookmark (validate url and title are present)
- GET /api/bookmarks — list all bookmarks with pagination (page, limit params)
- GET /api/bookmarks/:id — get a single bookmark with its tags
- PUT /api/bookmarks/:id — update a bookmark
- DELETE /api/bookmarks/:id — delete a bookmark and its tag associations
Use proper HTTP status codes. Return JSON with a consistent shape:
{ success: boolean, data: any, error?: string }

Az útvonalak regisztrálása

Import the bookmark routes in index.ts and register them. Also add
express.json() middleware and a global error handler.

Tesztelés curl használatával

Start the server, then create a test bookmark using curl:
curl -X POST http://localhost:3000/api/bookmarks \
  -H "Content-Type: application/json" \
  -d '{"url": "https://opencode.ai", "title": "OpenCode - AI Coding Agent"}'
Then fetch all bookmarks to verify it was saved.

Az OpenCode végrehajtja ezeket a parancsokat a termináljában, és megmutatja a válaszokat. Itt ragyog az eszköz — soha nem hagyja el a terminált, és az AI ellenőrzi a saját munkáját.

5. fázis: Keresés hozzáadása FTS5 segítségével (4 minutes)

A Plan mód bemutatása

A keresés megépítése előtt használjuk a Plan módot a megvalósítás átgondolásához. Váltson módot:

/plan

Most Plan módban van. Az AI tudja olvasni a kódját és elemezni azt, de nem módosíthat fájlokat. Ez hasznos a változtatások előtti tervezéshez.

Analyze my current database schema and FTS5 table. Plan how to implement a
search endpoint that queries the FTS5 table and returns bookmarks ranked by
relevance. Consider edge cases: empty queries, special characters, partial
matches.

Az OpenCode megvizsgálja a kódját, tervet ír a .opencode/plans/ könyvtárba, és elmagyarázza a megközelítését anélkül, hogy bármilyen fájlhoz nyúlna. Olvassa el a tervet, módosítsa ha szükséges, majd váltson vissza:

/build

Keresés implementálása

Based on the plan, implement a GET /api/bookmarks/search?q=query endpoint
that uses the FTS5 virtual table for full-text search. Include snippet
highlighting and relevance ranking. Handle edge cases from the plan.

Keresés tesztelése

Create three more test bookmarks with different titles and descriptions,
then test the search endpoint with a query that should match two of them.

Mi történt az imént (Funkció: Plan mód)

A Plan/Build munkafolyamat az, ahogyan a tapasztalt fejlesztők használják az OpenCode-ot összetett feladatoknál. Először tervezés, a megközelítés felülvizsgálata, majd az építés. A tervfájlok a .opencode/plans/ könyvtárba mentődnek, és később hivatkozhat rájuk a build ágens. Ez megakadályozza, hogy az AI menet közben hozzon nagy horderejű strukturális döntéseket.

6. fázis: A címkerendszer implementálása (4 minutes)

Címke végpontok létrehozása

Create a routes module at src/routes/tags.ts with:
- POST /api/tags — create a new tag
- GET /api/tags — list all tags with bookmark counts
- POST /api/bookmarks/:id/tags — add a tag to a bookmark
- DELETE /api/bookmarks/:id/tags/:tagId — remove a tag from a bookmark
- GET /api/bookmarks?tag=tagname — filter bookmarks by tag (update existing
  list endpoint to support this query parameter)
Register the tag routes in index.ts.

A címke folyamat tesztelése

Create two tags: "dev-tools" and "tutorials". Add the "dev-tools" tag to
the OpenCode bookmark. Then fetch bookmarks filtered by the "dev-tools" tag.

7. fázis: Egy egyszerű frontend felépítése (5 minutes)

A frontend generálása

Create a public/ directory with a single-page frontend:
- index.html with a clean, minimal design (no framework, just HTML/CSS/JS)
- A form to add bookmarks (url, title, description)
- A search bar that queries the search endpoint with debounced input
- A list of bookmarks showing title, url, tags, and a delete button
- A tag filter sidebar that shows all tags with counts
- Use fetch() for API calls. Mobile responsive. No build step needed.
Serve the public/ directory as static files from Express.

Az OpenCode egyetlen menetben legenerálja a teljes frontendet — HTML struktúrát, CSS stílust és JavaScriptet az API interakciókhoz. Az AI ágenssel történő terminálon belüli építés előnye, hogy azonnal tudja tesztelni, hogy a frontend csatlakozik-e az API-hoz.

A teljes stack tesztelése

Start the server, open http://localhost:3000 in a description, and verify
that adding a bookmark from the form, searching, and filtering by tag all
work correctly.

8. fázis: Tesztek hozzáadása egyedi ágenssel (5 minutes)

Egyedi tesztelő ágens létrehozása

Itt jön képbe az OpenCode egyedi ágensek funkciója. Ahelyett, hogy az általános Build ágenst használnánk a teszteléshez, létrehozunk egy speciálisat.

Adja hozzá ezt az opencode.json fájlhoz:

{
  "agents": {
    "test": {
      "name": "Test Writer",
      "instructions": "You are a testing specialist. Write comprehensive tests using Vitest. Focus on edge cases and error paths. Never modify source code — only create and edit test files.",
      "tools": ["read", "write", "terminal"]
    }
  }
}

Most váltson a teszt ágensre:

/agent test

Tesztek generálása

Write comprehensive tests for the bookmark API using Vitest and supertest.
Cover:
- Creating a bookmark with valid data
- Creating a bookmark with missing required fields
- Fetching all bookmarks with pagination
- Searching with FTS5 (matching and non-matching queries)
- Adding and removing tags
- Deleting a bookmark removes its tag associations
Use an in-memory SQLite database for test isolation.

A tesztek futtatása

Install vitest and supertest as dev dependencies, add a test script to
package.json, then run the test suite.

Mi történt az imént (Funkció: Egyedi ágensek)

Az egyedi ágensek lehetővé teszik fókuszált személyiségek létrehozását specifikus utasításokkal és eszközhozzáféréssel. Az általunk létrehozott teszt ágens csak fájlokat olvashat, tesztfájlokat írhat és terminálparancsokat futtathat — nem módosíthatja a forráskódot. Ez a megkötés megakadályozza azt a gyakori problémát, hogy az AI a forráskódot "javítja meg", amikor a tesztek sikertelenek, ahelyett, hogy a teszteket javítaná ki.

Létrehozhat ágenseket bármilyen speciális munkafolyamathoz: kód felülvizsgálat, dokumentáció, adatbázis migrációk, DevOps szkriptek. Az OpenCode ágensek dokumentációja további példákat tartalmaz.

Bónusz: MCP szerver csatlakoztatása a bővített funkcionalitás érdekében

Ha bővíteni szeretné könyvjelzőkezelőjét, külső eszközöket csatlakoztathat MCP (Model Context Protocol) szervereken keresztül.

Példa: Link Preview MCP szerver hozzáadása

Képzelje el, hogy szeretné, ha az OpenCode automatikusan lekérné a metaadatokat (cím, leírás, favicon) az URL-ekből könyvjelzők létrehozásakor. Csatlakoztathat egy MCP szervert, amely HTTP lekérést végez:

Adja hozzá ezt az opencode.json fájlhoz:

{
  "mcp": {
    "link-preview": {
      "type": "local",
      "command": ["npx", "link-preview-mcp-server"]
    }
  }
}

Most az OpenCode-nak új eszköz áll rendelkezésére: a munkafolyamat részeként le tudja kérni az URL metaadatokat. Amikor arra kéri, hogy "add a bookmark for https://example.com and auto-fill the title and description," az MCP szervert fogja használni az adatok lekéréséhez.

Távoli MCP szerverek

Felhőalapú szolgáltatásokhoz használjon távoli MCP szervereket automatikus OAuth kezeléssel:

{
  "mcp": {
    "cloud-storage": {
      "type": "remote",
      "url": "https://mcp.example.com/storage",
      "headers": {
        "Authorization": "Bearer ${STORAGE_TOKEN}"
      }
    }
  }
}

Az OpenCode észleli a 401-es válaszokat, és automatikusan elindítja az OAuth folyamatot, ha a szerver támogatja a Dynamic Client Registration-t.

Bónusz: Az OpenCode használata CI/CD folyamatokban

Az OpenCode rendelkezik egy CLI móddal, amely a TUI nélkül fut — tökéletes az automatizálááláshoz. Használhatja GitHub Actions-ben vagy bármilyen CI folyamatban:

# Run a single prompt and exit
opencode -p "Review the changes in the last commit for security issues" --no-tui

# Use a specific model
opencode -m "claude-sonnet-4-6" -p "Generate a changelog entry for this release" --no-tui

A könyvjelzőkezelőnkhöz hozzáadhatna egy CI lépést, amely futtatja az OpenCode-ot a PR-ok automatikus felülvizsgálatához. Az OpenCode GitHub integráció ennek a munkafolyamatnak egy egyszerűsített verzióját kínálja.

A teljes projektstruktúra

Az útmutató követése után a projektjének így kell kinéznie:

bookmark-manager/
  opencode.json          # OpenCode projekt konfiguráció + egyedi ágensek + MCP
  package.json
  tsconfig.json
  src/
    index.ts             # Express szerver belépési pont
    db.ts                # SQLite adatbázis modul FTS5-tel
    routes/
      bookmarks.ts       # CRUD + keresési végpontok
      tags.ts            # Címkekezelő végpontok
  public/
    index.html           # Egyoldalas frontend
  tests/
    bookmarks.test.ts    # API tesztcsomag
  data/
    bookmarks.db         # SQLite adatbázis (gitignored)
  .opencode/
    plans/               # Tervek a Plan mód munkameneteiből

Amit tanult

Egy valódi projekt felépítésével gyakorolta ezeket az OpenCode képességeket:

A kulcsfontosságú különbség az OpenCode és más AI kódoló eszközök között az, hogy teljesen nyílt forráskódú, a terminálban fut, és nem tárolja a kódját vagy a kontextus adatait. Ön irányítja a modelleket, az adatok helyben maradnak, és a több mint 800 közreműködőből álló közösség gondoskodik a gyors fejlődéséről.

A több AI eszközt használó csapatok számára az OpenCode jól működik az IDE asszisztensek terminálalapú kiegészítőjeként. A ZBuildnél gyakran használjuk szerkesztőalapú eszközökkel együtt a fejlesztési munkafolyamat különböző részeihez.

Következő lépések

Most, hogy van egy működő könyvjelzőkezelője és alaposan ismeri az OpenCode-ot, íme néhány irány a felfedezéshez:

1. Hitelesítés hozzáadása — Használja a Build ágenst JWT-alapú hitelesítés hozzáadásához felhasználói fiókokkal
2. Telepítés éles környezetbe — Kérje meg az OpenCode-ot, hogy generáljon egy Dockerfile-t, és telepítse a Fly.io-ra vagy a Railway-re
3. Böngészőbővítmény készítése — Hozzon létre egy Chrome bővítményt, amely az API-n keresztül ad hozzá könyvjelzőket
4. További Zen modellek felfedezése — Próbálja ki a Big Pickle, MiniMax M2.1 modelleket, vagy futtasson egy helyi modellt az Ollama segítségével
5. További egyedi ágensek létrehozása — Egy "refaktor" ágenst, egy "dokumentációs" ágenst, vagy egy "biztonsági audit" ágenst

Az OpenCode dokumentáció és az awesome-opencode repository további bővítményeket, témákat és közösségi konfigurációkat kínál a felfedezéshez.

Források

• OpenCode — Hivatalos dokumentáció
• OpenCode — GitHub Repository
• OpenCode — Zen modellek
• OpenCode — Ágensek dokumentációja
• OpenCode — MCP szerverek
• OpenCode — CLI mód
• OpenCode — Konfiguráció
• OpenCode — GitHub integráció
• Ollama — OpenCode integráció
• awesome-opencode — Közösségi erőforrások
• Composio — MCP az OpenCode-dal
• Computing for Geeks — OpenCode AI beállítása