Быстрый старт

Этот гайд доводит от чистого запуска до рабочего SOBA v0.4.1 workflow. Он не заменяет справочник, а показывает минимальный безопасный путь: проверить provider, запустить TUI, выполнить задачу, сохранить память проекта и проверить MCP.

1. Установка и проверка

Через npm:

npm install -g soba-agent

Через Bun:

bun add -g soba-agent

Standalone-бинарники для macOS и Linux публикуются в GitHub Releases. Для обычной установки рекомендуется npm или Bun, а бинарник удобен для окружений, где не хочется ставить пакет глобально.

Проверьте CLI:

soba --version
soba --help

Если вы работаете из исходников:

git clone <repo-url> soba-agent
cd soba-agent
bun install
bun run build
bun run src/cli.ts --version

2. Настроить provider

Первый запуск может создать ~/.soba/config.json. Минимально нужен API key и модель.

Быстрая проверка:

soba --no-session --max-agent-iterations 1 "Ответь одним словом: ok"

Посмотреть providers:

soba provider list

Добавить local OpenAI-compatible provider:

soba provider add ollama \
  --base-url http://localhost:11434/v1 \
  --model llama3.1="Llama 3.1",8192,2048 \
  --set-active

Для локальных моделей лучше начинать с небольшого окна контекста и ответа: 8192,2048 обычно заметно спокойнее для ноутбука. Если модель и железо уверенно справляются, значения можно поднять позже.

Подробнее: Провайдеры и модели.

3. Запустить TUI

soba -i --lang ru --theme graphite

Внутри TUI:

/session
/budget
/permissions
/auto-compact on

Рекомендуемый режим разрешений для первого проекта:

/permissions ask

Для disposable-репозитория можно включить repo-scoped режим:

/permissions repo

repo убирает запросы только для dangerous-операций внутри текущего репозитория. /permissions full стоит включать только когда вы хотите доверить все dangerous-операции до конца текущей сессии, включая внешние команды.

4. Выполнить первую задачу

Пример prompt:

Проверь проект.
Сначала прочитай package.json и структуру src/tests.
Затем предложи короткий план.
Если нужно менять файлы, меняй только в рамках плана.
После изменений запусти targeted bun test.
Не делай git commit.

Быстрые shell-проверки выполняются через !:

!git status --short
!git diff --stat
!bun test

Если вывод не нужен в transcript:

!!bun run build

5. Использовать sessions

SOBA сохраняет историю работы в session JSONL.

# новая интерактивная сессия
soba -i

# продолжить последнюю сессию
soba -c -i

# выбрать сессию из списка
soba -r

# продолжить конкретную сессию
soba -s <SESSION_ID> "Продолжи задачу"

В TUI:

/session
/budget

Для временных задач:

soba --no-session "Одноразовый вопрос"

6. Управлять длинным контекстом

Proactive compaction включается так:

/auto-compact on

Ручной compact:

/compact Сохрани цель, решения, изменённые файлы, проверки, риски и следующий шаг.

Посмотреть capsules:

/capsule
/capsule CHECKPOINT_ID

Откатиться к checkpoint:

/rewind
/rewind CHECKPOINT_ID

Подробнее: Compaction и Context Capsules.

7. Сохранить Project Memory

Project Memory хранит знания проекта в .soba/memory/ и доступна агенту между сессиями.

Попросите SOBA записать устойчивые факты:

Обнови Project Memory:
- architecture: основные модули проекта и data flow;
- conventions: Bun only, strict TypeScript, тесты через bun test;
- known-errors: повторяющиеся ошибки и команды проверки;
- dependencies: важные runtime/dev зависимости.

Используй project memory tools. Не сохраняй секреты.

Проверить файлы:

!find .soba/memory -maxdepth 3 -type f | sort

Подробнее: Project Memory.

8. Подключить MCP tools

MCP config хранится в проекте:

.soba/mcp.json

Проверить servers:

/mcp status
/mcp start <server>
/mcp status

SOBA поддерживает local stdio servers и remote streamableHttp endpoints. Для первого рабочего remote подключения используйте bearerEnv или apiKeyEnv; OAuth-команды требуют подключённого auth controller для provider:

/mcp auth login <server>
/mcp auth status <server>

MCP tools появляются в agent tool registry с именами:

mcp_<server-id>_<tool-name>

Подробнее: MCP-серверы и Remote MCP: пошаговый гайд.

9. Использовать skills

Посмотреть skills:

/skill list

Активировать skill:

/skill:commit-message Предложи conventional commit message для текущих staged changes.

Project skills требуют trust:

/project-trust status
/project-trust approve

Подробнее: Skills.

10. Передать работу через Portable Capsule

Создать handoff capsule:

/capsule create "handoff current task"

Экспортировать:

/capsule export CHECKPOINT_ID ./handoff.capsule.md

Загрузить:

/capsule load ./handoff.capsule.md

Подробнее: Portable Capsules.

11. Минимальный gate перед завершением

Для Bun/TypeScript проекта:

!bun test
!bun run build
!bunx tsc --noEmit
!git diff --check
!git status --short

Для самого SOBA дополнительно:

!bun run lint

12. Куда идти дальше