Создайте Full-Stack менеджер закладок с OpenCode за 30 минут (пошаговое руководство)

Что мы будем создавать

Забудьте о списках функций. Лучший способ изучить инструмент — это создать что-то с его помощью.

В этом руководстве вы будете использовать OpenCode — агент для кодирования на базе AI с открытым исходным кодом, имеющий более 120K+ звезд на GitHub — чтобы создать полноценный менеджер закладок с нуля. Приложение будет иметь:

• REST API на Express.js и TypeScript
• База данных SQLite с полнотекстовым поиском
• Система тегов для организации закладок
• Простой, но функциональный фронтенд
• Unit-тесты

Каждая функция OpenCode представляется именно в тот момент, когда она вам нужна, а не в абстрактном разделе функций. К концу вы будете знать, как устанавливать OpenCode, настраивать модели, использовать режимы Build и Plan, настраивать 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 предложит вам выбрать модель. У вас есть три пути:

Free (Zen models): Введите /models и выберите одну из free Zen models. Для этого руководства хорошо подойдут Grok Code Fast 1 или GLM 4.7. Они бесплатны и не требуют API ключа.

Local (Ollama): Если у вас установлен Ollama, OpenCode обнаружит его автоматически. Рекомендуемая модель для Ollama — glm-4.7:cloud.

Paid (bring your own key): Введите /connect, чтобы привязать ваш Anthropic, OpenAI или Google API ключ. Ключи хранятся локально в ~/.local/share/opencode/auth.json.

Для этого руководства подойдет любая модель. Модели с более высокими возможностями (Claude Sonnet 4.6, GPT-5.4) дадут лучшие результаты в сложных задачах, но бесплатные Zen модели справятся со всем, что мы здесь создаем.

Этап 2: Создание каркаса проекта в режиме Build (4 минуты)

OpenCode запускается в режиме Build mode по умолчанию. Режим Build дает 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. Установит зависимости через 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 — это агент OpenCode по умолчанию. У него есть доступ ко всем инструментам: чтение/запись файлов, выполнение команд в терминале и редактирование кода. Согласно OpenCode documentation, вы можете воспринимать его как AI-напарника по программированию с полным доступом к вашей среде разработки.

Этап 3: Создание модели данных и базы данных (4 минуты)

Проектирование схемы

Введите этот промпт:

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

Перед созданием поиска давайте воспользуемся режимом Plan, чтобы продумать реализацию. Переключите режимы:

/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: Создание простого фронтенда (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-агентом заключается в том, что он может немедленно проверить, подключается ли фронтенд к API.

Тестирование всего стека

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 custom agents. Вместо использования общего агента 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 «исправляет» ваш исходный код при провале тестов вместо того, чтобы исправлять сами тесты.

Вы можете создавать агентов для любого специализированного рабочего процесса: код-ревью, документация, миграции баз данных, DevOps скрипты. В OpenCode agents documentation есть больше примеров.

Бонус: Подключение 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, который работает без TUI — идеально подходит для автоматизации. Вы можете использовать его в GitHub Actions или любом CI-конвейере:

# 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 для автоматической проверки PR. Интеграция 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. Добавьте аутентификацию — используйте агента Build, чтобы добавить аутентификацию на базе JWT с учетными записями пользователей.
2. Разверните в продакшн — попросите OpenCode сгенерировать Dockerfile и развернуть приложение на Fly.io или Railway.
3. Создайте расширение для браузера — создайте расширение для Chrome, которое добавляет закладки через API.
4. Изучите больше Zen моделей — попробуйте Big Pickle, MiniMax M2.1 или запустите локальную модель через Ollama.
5. Создайте больше кастомных агентов — агента для «рефакторинга», агента для «документации» или агента для «аудита безопасности».

В OpenCode documentation и репозитории awesome-opencode можно найти больше плагинов, тем и конфигураций сообщества.

Источники

• OpenCode — Официальная документация
• OpenCode — Репозиторий GitHub
• OpenCode — Zen модели
• OpenCode — Документация по агентам
• OpenCode — MCP-серверы
• OpenCode — Режим CLI
• OpenCode — Конфигурация
• OpenCode — Интеграция с GitHub
• Ollama — Интеграция с OpenCode
• awesome-opencode — Ресурсы сообщества
• Composio — MCP с OpenCode
• Computing for Geeks — Настройка OpenCode AI