بناء Full-Stack Bookmark Manager باستخدام OpenCode في 30 دقيقة (خطوة بخطوة)

ما الذي نقوم ببنائه

انسَ قوائم الميزات. أفضل طريقة لتعلم أداة هي بناء شيء ما بها.

في هذا البرنامج التعليمي، ستستخدم OpenCode — وهو AI coding agent مفتوح المصدر مع 120K+ نجوم على GitHub — لبناء مدير إشارات مرجعية كامل من الصفر. سيحتوي التطبيق على:

• REST API باستخدام Express.js و TypeScript
• قاعدة بيانات SQLite مع بحث كامل في النص
• نظام وسوم لتنظيم الإشارات المرجعية
• واجهة أمامية بسيطة ولكنها وظيفية
• Unit tests

يتم تقديم كل ميزة من ميزات OpenCode في اللحظة التي تحتاج إليها — وليس في قسم ميزات تجريدي. بحلول النهاية، ستعرف كيفية تثبيت OpenCode، وتكوين الموديلات، واستخدام Build mode و Plan mode، وإعداد MCP servers، وإنشاء custom agents — كل ذلك لأنك استخدمتها لبناء مشروع حقيقي.

الوقت: ~30 دقيقة المتطلبات الأساسية: تثبيت Node.js 18+، وتيرمينال (macOS، Linux، أو WSL على Windows) التكلفة: مجاني (باستخدام موديلات OpenCode Zen)

المرحلة 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 الخاص بك من 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 agent وصولاً كاملاً لإنشاء الملفات وتحرير الأكواد وتشغيل الأوامر. هذا هو ما نريده للهيكلة.

موجهك الأول

اكتب هذا في دردشة 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. تثبيت التبعيات باستخدام npm install
3. إنشاء src/index.ts مع إعداد سيرفر Express
4. تحديث package.json مع نصوص البدء

راقب TUI — سترى الـ agent وهو ينفذ أوامر التيرمينال، ويقوم بإنشاء الملفات، ويشرح ما يفعله في كل خطوة. هذا ليس توليد كود في فراغ؛ 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 هو الـ agent الافتراضي في 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: بناء نقاط نهاية REST API (5 دقائق)

توليد المسارات

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 }

تسجيل المسارات

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 agent. هذا يمنع الـ 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: بناء واجهة أمامية بسيطة (5 دقائق)

توليد الواجهة الأمية

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 بتوليد الواجهة الأمامية الكاملة — هيكل HTML، وتنسيق CSS، و JavaScript لتفاعلات API — في تمريرة واحدة. ميزة بناء هذا في التيرمينال باستخدام AI agent هي أنه يمكنه اختبار ما إذا كانت الواجهة الأمامية تتصل بـ 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: إضافة الاختبارات باستخدام Custom Agent (5 دقائق)

إنشاء Custom Test Agent

هنا تظهر ميزة custom agents في OpenCode. بدلاً من استخدام Build agent العام للاختبار، سنقوم بإنشاء واحد متخصص.

أضف هذا إلى ملف 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"]
    }
  }
}

الآن انتقل إلى test agent:

/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)

تسمح لك الـ custom agents بإنشاء شخصيات مركزة بتعليمات محددة ووصول إلى الأدوات. لا يمكن لـ test agent الذي أنشأناه إلا قراءة الملفات، وكتابة ملفات الاختبار، وتشغيل أوامر التيرمينال — ولا يمكنه تعديل الكود المصدري. يمنع هذا القيد المشكلة الشائعة المتمثلة في قيام الـ AI بـ "إصلاح" الكود المصدري الخاص بك عند فشل الاختبارات بدلاً من إصلاح الاختبارات نفسها.

يمكنك إنشاء agents لأي سير عمل متخصص: مراجعة الكود، التوثيق، ترحيل قواعد البيانات، نصوص DevOps البرمجية. تحتوي وثائق وكلاء OpenCode على المزيد من الأمثلة.

مكافأة: توصيل MCP Server لوظائف محسنة

إذا كنت ترغب في توسيع مدير الإشارات المرجعية الخاص بك، يمكنك توصيل أدوات خارجية عبر MCP (Model Context Protocol) servers.

مثال: إضافة Link Preview MCP Server

تخيل أنك تريد أن يقوم OpenCode تلقائيًا بجلب البيانات الوصفية (العنوان، الوصف، favicon) من URLs عند إنشاء الإشارات المرجعية. يمكنك توصيل MCP server يقوم بجلب HTTP:

أضف هذا إلى ملف opencode.json الخاص بك:

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

الآن أصبح لدى OpenCode أداة جديدة متاحة: يمكنه جلب البيانات الوصفية لـ URL كجزء من سير عمله. عندما تطلب منه "إضافة إشارة مرجعية لـ https://example.com وتعبئة العنوان والوصف تلقائيًا"، فسيستخدم MCP server لجلب تلك البيانات.

Remote MCP Servers

للخدمات السحابية، استخدم remote MCP servers مع معالجة 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 integration إصدارًا أكثر انسيابية من سير العمل هذا.

هيكل المشروع الكامل

بعد اتباع هذا البرنامج التعليمي، يجب أن يبدو مشروعك كما يلي:

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 وأدوات البرمجة بالذكاء الاصطناعي الأخرى هو أنه مفتوح المصدر بالكامل، ويعمل في التيرمينال الخاص بك، ولا يخزن الكود الخاص بك أو بيانات السياق. أنت تتحكم في الموديلات، وتبقى البيانات محلية، ويستمر مجتمع مكون من 800+ مساهم في تطويره بسرعة.

بالنسبة للفرق التي تستخدم أدوات ذكاء اصطناعي متعددة، يعمل OpenCode بشكل جيد كمكمل يعتمد على التيرمينال لمساعدي IDE. في ZBuild، غالبًا ما نستخدمه جنبًا إلى جنب مع الأدوات القائمة على المحرر لأجزاء مختلفة من سير عمل التطوير.

الخطوات التالية

الآن بعد أن أصبح لديك مدير إشارات مرجعية يعمل وفهم قوي لـ OpenCode، إليك بعض الاتجاهات لاستكشافها:

1. إضافة المصادقة — استخدم Build agent لإضافة JWT-based auth مع حسابات المستخدمين
2. النشر للإنتاج — اطلب من OpenCode إنشاء Dockerfile ونشره في Fly.io أو Railway
3. بناء إضافة متصفح — أنشئ Chrome extension يضيف إشارات مرجعية عبر API
4. استكشاف المزيد من موديلات Zen — جرب Big Pickle، MiniMax M2.1، أو قم بتشغيل موديل محلي من خلال Ollama
5. إنشاء المزيد من custom agents — وكيل "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