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

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

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

Через npm:

npm install -g soba-agent

Пакет npm включает закреплённую runtime-зависимость Bun, поэтому перед запуском soba не нужно отдельно ставить Bun.

Через Bun:

bun add -g soba-agent

Используйте установку через Bun, если Bun уже входит в ваш toolchain и вы хотите управлять глобальным пакетом через него.

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

Проверьте CLI:

soba --version
soba --help
soba init --check

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

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
/sessions list
/budget
/permissions
/auto-compact on
/plan on

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

/permissions ask

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

/permissions repo

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

/plan on включает read-only режим для подготовки плана до изменения проекта. Подробнее: Plan и goal mode.

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
/sessions list
/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 doctor и Memory health commands:

soba memory doctor
soba memory doctor --format json
soba memory stale
soba memory verify
soba memory explain "provider registry"

soba memory explain даёт Memory receipt explanations: найденные capsules, source receipts, score и doctor issues.

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

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

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

.soba/mcp.json

Проверить servers:

/mcp status
/mcp start <server>
/mcp reload
/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

Для reusable skills используйте цикл Skill eval bench and trace:

/skill eval <name>
/skill bench <name>
/skill trace <name>

Подробнее: 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. Проверить proof receipts

После нетривиальной задачи проверьте локальный proof trail:

soba prove --last
soba verify --last
soba explain-claim "No test regressions detected"

Evidence proof receipts лежат в .soba/evidence/*.soba-proof.json. Proof receipt должен показывать changed files, checks, proof claim mapping, risks и proof permission receipts. Если важный claim не подтверждён, он должен оставаться явно unverified. Для Proof claim explanations по конкретному файлу используйте soba explain-claim --proof .soba/evidence/<id>.soba-proof.json.

Подробнее: Proof receipts.

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

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

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

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

!bun run lint

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