בניית Full-Stack Bookmark Manager עם OpenCode ב-30 דקות (שלב אחר שלב)

מה אנחנו בונים

שכחו מרשימות תכונות. הדרך הטובה ביותר ללמוד כלי היא לבנות איתו משהו.

במדריך זה, תשתמשו ב-OpenCode — סוכן הקידוד ב-AI בקוד פתוח עם 120K+ כוכבי GitHub — כדי לבנות מנהל סימניות שלם מאפס. האפליקציה תכלול:

• REST API עם Express.js ו-TypeScript
• מסד נתונים SQLite עם חיפוש טקסט מלא
• מערכת תגיות לארגון סימניות
• frontend פשוט אך פונקציונלי
• Unit tests

כל תכונה של OpenCode תוצג ברגע שתזדקקו לה — לא בסעיף תכונות מופשט. בסיום, תדעו כיצד להתקין את OpenCode, להגדיר מודלים, להשתמש ב-Build mode ו-Plan mode, להגדיר שרתי MCP וליצור סוכנים מותאמים אישית — כל זאת מכיוון שהשתמשתם בהם כדי לבנות פרויקט אמיתי.

זמן: ~30 דקות דרישות מוקדמות: Node.js 18+ מותקן, טרמינל (macOS, Linux, או WSL ב-Windows) עלות: חינם (באמצעות מודלי Zen של OpenCode)

שלב 1: התקנת OpenCode והגדרת הפרויקט (5 דקות)

התקנת OpenCode

פתחו את הטרמינל והריצו אחת מהפקודות הבאות:

# 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

אמתו את ההתקנה:

opencode --version

אתם אמורים לראות את מספר הגרסה. נכון ל-March 2026, הגרסה היציבה האחרונה זמינה ב-OpenCode GitHub repository.

יצירת ספריית הפרויקט

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

הפעלת OpenCode בפעם הראשונה

opencode

זה יפתח את ה-TUI (Terminal User Interface) של OpenCode — ממשק אינטראקטיבי במסך מלא שנבנה עם Bubble Tea. תראו שדה קלט לצ'אט בתחתית וחלון שיחה באזור הראשי.

בחירת מודל

בהפעלה הראשונה, OpenCode יבקש מכם לבחור מודל. יש לכם שלושה נתיבים:

חינם (מודלי Zen): הקלידו /models ובחרו אחד ממודלי Zen החינמיים. עבור מדריך זה, Grok Code Fast 1 או GLM 4.7 יעבדו היטב. אלו הם בחינם ואינם דורשים API key.

מקומי (Ollama): אם מותקן אצלכם Ollama, OpenCode יזהה אותו אוטומטית. ה-מודל המומלץ עבור Ollama הוא glm-4.7:cloud.

בתשלום (השתמשו במפתח שלכם): הקלידו /connect כדי לקשר את ה-API key שלכם מ-Anthropic, OpenAI, או Google. המפתחות נשמרים מקומית ב-~/.local/share/opencode/auth.json.

עבור מדריך זה, כל מודל יעבוד. מודלים בעלי יכולות גבוהות יותר (Claude Sonnet 4.6, GPT-5.4) יפיקו תוצאות טובות יותר במשימות מורכבות, אך מודלי Zen החינמיים מטפלים היטב בכל מה שאנחנו בונים כאן.

שלב 2: יצירת תשתית הפרויקט עם Build Mode (4 דקות)

OpenCode מתחיל ב-Build mode כברירת מחדל. Build mode מעניק לסוכן ה-AI גישה מלאה ליצירת קבצים, עריכת קוד והרצת פקודות. זה מה שאנחנו רוצים עבור יצירת התשתית.

הפרומפט הראשון שלכם

הקלידו זאת בצ'אט של OpenCode:

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.

OpenCode יבצע:

1. יצירת tsconfig.json
2. התקנת dependencies עם npm install
3. יצירת src/index.ts עם הגדרת שרת Express
4. עדכון package.json עם סקריפטים להפעלה

צפו ב-TUI — אתם תראו את הסוכן מבצע פקודות טרמינל, יוצר קבצים ומסביר מה הוא עושה בכל שלב. זה לא ייצור קוד בוואקום; ל-OpenCode יש גישה מלאה למערכת הקבצים ולטרמינל שלכם.

אימות הפעולה

לאחר ש-OpenCode מסיים, אמרו לו:

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

OpenCode יריץ את npx nodemon src/index.ts ויאשר שהשרת מאזין. אתם אמורים לראות פלט כמו Server running on http://localhost:3000.

מה קרה עכשיו (תכונה: Build Mode)

Build mode הוא סוכן ברירת המחדל של OpenCode. יש לו גישה לכל הכלים: קריאה/כתיבה של קבצים, הרצה בטרמינל ועריכת קוד. על פי ה-תיעוד של OpenCode, ניתן לחשוב עליו כעל AI pair programmer עם גישה מלאה לסביבת הפיתוח שלכם.

שלב 3: יצירת מודל הנתונים ומסד הנתונים (4 דקות)

עיצוב הסכימה (Schema)

הקלידו פרומפט זה:

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.

OpenCode ייצור את מודול מסד הנתונים המלא. שימו לב כיצד הוא מטפל בהגדרת FTS5 (Full-Text Search 5) — זוהי תכונה של SQLite שתפעיל את יכולת החיפוש שלנו בהמשך.

אתחול מסד הנתונים בהפעלת השרת

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

יצירת קובץ ההגדרות opencode.json

זהו רגע טוב להציג את הגדרות הפרויקט. צרו קובץ על ידי הנחיה ל-OpenCode:

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."

זה יוצר את קובץ הגדרות הפרויקט ש-OpenCode קורא בזמן העלייה. הוא נותן ל-AI הקשר קבוע על הפרויקט שלכם — סטנדרטים של קידוד, החלטות ארכיטקטורה ומגבלות — כך שלא תצטרכו לחזור עליהם בכל פרומפט.

שלב 4: בניית נקודות הקצה (Endpoints) של ה-REST API (5 דקות)

יצירת ה-Routes

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 }

רישום ה-Routes

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

בדיקה עם curl

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.

OpenCode יריץ את הפקודות האלו בטרמינל שלכם ויציג לכם את התגובות. כאן הכלי זורח — אתם לעולם לא עוזבים את הטרמינל, וה-AI מאמת את העבודה של עצמו.

שלב 5: הוספת חיפוש עם FTS5 (4 דקות)

היכרות עם Plan Mode

לפני בניית החיפוש, בואו נשתמש ב-Plan mode כדי לחשוב על המימוש. החליפו מצבים:

/plan

עכשיו אתם ב-Plan mode. ה-AI יכול לקרוא את הקוד שלכם ולנתח אותו אך לא יכול לשנות אף קובץ. זה שימושי עבור תכנון לפני ביצוע שינויים.

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.

OpenCode יבחן את הקוד שלכם, יכתוב תוכנית ל-.opencode/plans/, ויסביר את הגישה שלו מבלי לגעת בקבצים. קראו את התוכנית, התאימו אם צריך, ואז חזרו חזרה:

/build

מימוש החיפוש

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.

בדיקת החיפוש

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

מה קרה עכשיו (תכונה: Plan Mode)

זרימת העבודה של Plan/Build היא הדרך שבה מפתחים מנוסים משתמשים ב-OpenCode במשימות מורכבות. קודם מתכננים, בוחנים את הגישה, ואז בונים. קבצי התוכנית נשמרים ב-.opencode/plans/ וניתן להתייחס אליהם מאוחר יותר על ידי סוכן ה-build. זה מונע מה-AI לקבל החלטות מבניות גדולות תוך כדי תנועה.

שלב 6: מימוש מערכת התגיות (4 דקות)

יצירת נקודות קצה לתגיות

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.

בדיקת זרימת התגיות

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: בניית Frontend פשוט (5 דקות)

יצירת ה-Frontend

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.

OpenCode ייצור את ה-frontend המלא — מבנה HTML, עיצוב CSS ו-JavaScript לאינטראקציות עם ה-API — בפעימה אחת. היתרון בבניית זה בטרמינל עם סוכן AI הוא שהוא יכול לבדוק מיד אם ה-frontend מתחבר ל-API.

בדיקת ה-Full Stack

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: הוספת בדיקות עם סוכן מותאם אישית (5 דקות)

יצירת סוכן בדיקות מותאם אישית

כאן נכנסת לתמונה תכונת ה-סוכנים המותאמים אישית של OpenCode. במקום להשתמש בסוכן Build הכללי לבדיקות, ניצור אחד ייעודי.

הוסיפו זאת ל-opencode.json שלכם:

{
  "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"]
    }
  }
}

עכשיו עברו לסוכן הבדיקות:

/agent test

יצירת בדיקות

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.

הרצת הבדיקות

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

מה קרה עכשיו (תכונה: Custom Agents)

סוכנים מותאמים אישית מאפשרים לכם ליצור דמויות ממוקדות עם הוראות ספציפיות וגישה לכלים. סוכן הבדיקות שיצרנו יכול רק לקרוא קבצים, לכתוב קבצי בדיקה ולהריץ פקודות טרמינל — הוא אינו יכול לשנות קוד מקור. מגבלה זו מונעת את הבעיה הנפוצה שבה AI "מתקן" את קוד המקור שלכם כשבדיקות נכשלות במקום לתקן את הבדיקות.

ניתן ליצור סוכנים לכל זרימת עבודה ייעודית: code review, תיעוד, database migrations, סקריפטים של DevOps. ב-תיעוד הסוכנים של OpenCode יש דוגמאות נוספות.

בונוס: חיבור שרת MCP לפונקציונליות משופרת

אם תרצו להרחיב את מנהל הסימניות שלכם, תוכלו לחבר כלים חיצוניים באמצעות שרתי MCP (Model Context Protocol).

דוגמה: הוספת שרת MCP לתצוגה מקדימה של קישורים

דמיינו שאתם רוצים ש-OpenCode ימשוך אוטומטית מטא-דאטה (כותרת, תיאור, favicon) מכתובות URL בעת יצירת סימניות. אתם יכולים לחבר שרת MCP שמבצע משיכת HTTP:

הוסיפו זאת ל-opencode.json שלכם:

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

עכשיו ל-OpenCode יש כלי חדש זמין: הוא יכול למשוך מטא-דאטה של URL כחלק מזרימת העבודה שלו. כשתבקשו ממנו "להוסיף סימניה עבור https://example.com ולמלא אוטומטית את הכותרת והתיאור", הוא ישתמש בשרת ה-MCP כדי למשוך את הנתונים האלו.

שרתי MCP מרוחקים

עבור שירותי ענן, השתמשו בשרתי MCP מרוחקים עם ניהול OAuth אוטומטי:

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

OpenCode מזהה תגובות 401 ויוזם את תהליך ה-OAuth אוטומטית אם השרת תומך ב-Dynamic Client Registration.

בונוס: שימוש ב-OpenCode בתוך CI/CD

ל-OpenCode יש CLI mode שרץ ללא ה-TUI — מושלם לאוטומציה. תוכלו להשתמש בו ב-GitHub Actions או בכל CI pipeline:

# 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

עבור מנהל הסימניות שלנו, תוכלו להוסיף שלב CI שמריץ את OpenCode כדי לבדוק PRs אוטומטית. ה-אינטגרציה של OpenCode עם GitHub מספקת גרסה פשוטה יותר של זרימת עבודה זו.

מבנה הפרויקט המלא

לאחר המעקב אחר מדריך זה, הפרויקט שלכם אמור להיראות כך:

bookmark-manager/
  opencode.json          # OpenCode project config + custom agents + MCP
  package.json
  tsconfig.json
  src/
    index.ts             # Express server entry point
    db.ts                # SQLite database module with FTS5
    routes/
      bookmarks.ts       # CRUD + search endpoints
      tags.ts            # Tag management endpoints
  public/
    index.html           # Single-page frontend
  tests/
    bookmarks.test.ts    # API test suite
  data/
    bookmarks.db         # SQLite database (gitignored)
  .opencode/
    plans/               # Plans from Plan mode sessions

מה למדתם

על ידי בניית פרויקט אמיתי, תרגלתם את יכולות OpenCode הבאות:

ההבדל העיקרי בין OpenCode לכלי קידוד AI אחרים הוא שהוא קוד פתוח לחלוטין, רץ בטרמינל שלכם, ואינו שומר את הקוד או את נתוני ההקשר שלכם. אתם שולטים במודלים, הנתונים נשארים מקומיים, וקהילת של 800+ תורמים דואגת שהוא ימשיך להתפתח מהר.

עבור צוותים המשתמשים בכלי AI מרובים, OpenCode עובד היטב כמשלים מבוסס טרמינל לעוזרי IDE. ב-ZBuild, אנחנו משתמשים בו לעיתים קרובות לצד כלים מבוססי עורך עבור חלקים שונים של זרימת עבודת הפיתוח.

צעדים הבאים

עכשיו שיש לכם מנהל סימניות עובד והבנה מוצקה של OpenCode, הנה כמה כיוונים לחקור:

1. הוספת אימות (Authentication) — השתמשו בסוכן Build כדי להוסיף אימות מבוסס JWT עם חשבונות משתמשים.
2. פריסה ל-Production — בקשו מ-OpenCode לייצר Dockerfile ולפרוס ל-Fly.io או Railway.
3. בניית תוסף לדפדפן — צרו תוסף Chrome שמוסיף סימניות דרך ה-API.
4. חקירת מודלי Zen נוספים — נסו את Big Pickle, MiniMax M2.1, או הריצו מודל מקומי דרך Ollama.
5. יצירת סוכנים מותאמים אישית נוספים — סוכן "refactor", סוכן "docs", או סוכן "security audit".

ב-תיעוד של OpenCode וב-awesome-opencode repository יש עוד פלאגינים, ערכות נושא והגדרות קהילה לחקור.

מקורות

• OpenCode — Official Documentation
• OpenCode — GitHub Repository
• OpenCode — Zen Models
• OpenCode — Agents Documentation
• OpenCode — MCP Servers
• OpenCode — CLI Mode
• OpenCode — Configuration
• OpenCode — GitHub Integration
• Ollama — OpenCode Integration
• awesome-opencode — Community Resources
• Composio — MCP with OpenCode
• Computing for Geeks — Setup OpenCode AI