Как устроен CodeSpark

§Режимы: чат и агент

CodeSpark работает в двух режимах. Чат — диалог с моделью без инструментов: агент отвечает только текстом, не трогает ваш проект. Подходит для «объясни, как это работает» или «накидай скелет SQL-запроса».

Агент — полный цикл: ИИ читает файлы, запускает команды, делает правки, ищет по проекту и продолжает работу, пока задача не решена. По умолчанию включён именно агент.

Переключение в VS Code

• Горячая клавиша: Ctrl + Shift + M (на macOS — ⌘ + Shift + M).
• Палитра команд: «CodeSpark: Toggle Mode (Chat / Agent)» и «CodeSpark: Set Mode…».
• Дефолт по умолчанию задаётся в настройках — ключ codespark.defaultMode со значениями chat или agent.

Переключение в CLI

• На запуск: флаг --mode chat либо --mode agent.
• В TUI: слеш-команда /mode chat или /mode agent (русский алиас — /режим).
• Выбор сохраняется per-проект в ~/.codespark/preferences.json — следующий запуск в той же папке подхватит его автоматически.

§Каталог инструментов

В агентном режиме модель сама решает, какое действие сделать на следующем шаге. Каталог зафиксирован — агент не может выйти за пределы того, что перечислено ниже.

§Режимы одобрения

Каждое опасное действие — запись файла, правка, запуск команды — по умолчанию требует явного «да». Режим переключается прямо в панели расширения и запоминается отдельно для каждой рабочей области.

• Строго (careful) — перед каждой правкой и каждой командой агент спрашивает разрешения. Значение по умолчанию.
• Авто (auto) — агент действует без остановок («yolo»). Удобно для песочниц и доверенных репозиториев, не стоит включать на продовой ветке.
• Только чтение (read-only) — агент видит проект, но ничего не меняет: попытки записать файл или запустить команду отклоняются.

Дефолт по умолчанию для новых рабочих пространств — ключ codespark.defaultApprovalMode в настройках VS Code. В CLI запустите чат с флагом --ask-for-approval ask|on-request|never либо пресетом --plan (read-only + ask) или --yolo (workspace-write + never).

§Политика разрешений

Помимо общего режима одобрения, можно задать тонкие правила в файле .codespark/permissions.json. Поддерживаются три решения для каждого правила: allow (разрешить без вопросов), ask (спросить даже в auto-режиме), deny (запретить без возможности подтвердить). Deny всегда побеждает; allow побеждает ask.

Project-уровень (.codespark/permissions.json в корне проекта) перекрывает user-уровень (~/.codespark/permissions.json) на совпадении имени правила. Расширение VS Code следит за файлами и подхватывает изменения сразу после сохранения.

Что можно ограничивать

• tool — по имени инструмента (например, write_file).
• path — по glob-пути (**, *, ?, [abc]).
• command — по префиксу shell-команды (git push) либо по regex.
• mcp-server и mcp-tool — по имени внешнего инструмента или всего сервера.

Стартовая политика

Команда codespark permissions init создаёт .codespark/permissions.json с разумным набором по умолчанию:

• Allow: read_file, list_files, search_files; префиксы git status, git diff, git log, git branch, git show.
• Ask: write_file, edit_file, run_command.
• Deny: rm -rf / или ~, sudo, fork-bomb.

Управление через CLI

Subject имеет короткую форму: tool:<name>, path:<glob>, command:<prefix>, command-re:<regex>, mcp-server:<name>, mcp-tool:<name>.

codespark permissions allow path:'docs/**'
codespark permissions deny  path:'infra/**'
codespark permissions allow command:'git push'
codespark permissions explain run_command '{"command":"git status"}'

В VS Code действующая политика отображается в панели «Разрешения» на боковой панели CodeSpark. Правила читаются автоматически после каждого сохранения файла.

§Семантический поиск

На тарифах Pro и Pro Max расширение собирает семантический индекс проекта на серверах в РФ. Агент находит по нему нужные участки кода: на запрос «где валидация JWT» он покажет функции проверки токенов, даже если в коде нет слова «валидация».

Индексация запускается автоматически при первом открытии проекта и обновляется в фоне по ходу работы — никаких команд запускать не нужно. Файлы из .gitignore и .codesparkignore не индексируются и не попадают на сервер.

§Inline-автодополнение

Inline-автодополнение — подсказки кода прямо во время набора: в конце строки появляется серый «призрачный» текст, который принимается клавишей Tab. Подсказки учитывают файл целиком и соседние открытые буферы. Доступно на Pro и Pro Max.

Если подсказки мешают — отключайте в настройках VS Code стандартным ключом editor.inlineSuggest.enabled.

§MCP-серверы

Model Context Protocol — стандарт описания инструментов, которые может вызывать ИИ. Подключённый MCP-сервер запускается локально либо опрашивается удалённо по HTTP, его инструменты появляются у агента наравне со встроенными. Так подключаются Linear, GitHub, базы данных, самописные обёртки над вашим API.

Конфигурация в VS Code

В Settings → Extensions → CodeSpark → Mcp Servers (codespark.mcpServers). Поддерживается тот же формат, что и ~/.codespark/mcp.json:

{
  "github": {
    "transport": "http",
    "url": "https://example.com/mcp",
    "bearer": "<token>"
  },
  "local-fs": {
    "transport": "stdio",
    "command": "node",
    "args": ["./mcp-fs.js"]
  }
}

Если поле transport опущено, считается stdio (back-compat со старым форматом).

Конфигурация в CLI

Тот же конфиг живёт в ~/.codespark/mcp.json (либо в файле, который вы передадите через --mcp-config FILE). Управление:

Просмотр в VS Code

В боковой панели CodeSpark есть отдельный раздел «MCP-серверы»: он показывает запущенные серверы (✓ — живой, × — ошибка), их транспорт и список инструментов каждого. Раздел обновляется автоматически при изменении настроек.

§Скриншоты в чате

К любому сообщению можно прикрепить скриншот — и это будет работать с любой моделью каталога, включая YandexGPT и GigaChat, которые сами по себе vision не поддерживают.

Как вставить

• VS Code: вставьте изображение из буфера обмена в поле сообщения (Cmd/Ctrl + V) или прикрепите через picker. Формат: PNG, JPEG, WebP, GIF.
• CLI: флаг --image PATH при запуске чата (можно повторять). Пример: codespark --image ./screenshot.png "что не так на этом UI?"

Лимиты

• Один файл — до 8 МиБ; больше отклоняется ещё на стороне клиента.
• Поддерживаемые типы: image/png, image/jpeg, image/webp, image/gif.
• Файл с несоответствующим заявленному Content-Type содержимым отклоняется (защита от подмены).

Под капотом CodeSpark сам разбирается, как довести изображение до модели — пользователю достаточно знать, что это работает с любым выбранным чат-моделью.

§Код-ревью

Команда codespark review прогоняет текущий git-дифф через ревью-промпт и возвращает замечания. По умолчанию ревьюится git diff HEAD (рабочая копия + индекс).

В TUI чата работает слеш-команда /diff (показать дифф) и /review (ревью текущих изменений в  активной беседе).

codespark review --base main --format json | jq '.[] | select(.severity=="error")'

§Сессии

Каждый чат сохраняется на сервере и доступен из обоих клиентов. В VS Code управление через сайдбар чатов; в CLI — отдельная команда.

Заголовок сессии генерируется автоматически после первого ответа агента; пустой заголовок до этого момента — нормально.

§Откат правок

Каждый write_file и edit_file пишет чекпоинт в ~/.codespark/checkpoints/conversations/<id>/ с preimage и postimage — чтобы можно было откатить правку, не прибегая к git stash.

Защита от затирания

Если файл изменён извне после агента (вы что-то добавили в редакторе сами, например), rewind пропустит этот чекпоинт с пометкой «файл изменён извне после правки агента» — текущее содержимое не затирается. Чекпоинт-файл остаётся на диске, чтобы можно было разобраться вручную.

§Attach: подключиться к идущему ходу

Если вы запустили долгую задачу в одном терминале и закрыли его — на сервере run всё ещё идёт. Команда codespark attach переподключается к живому стриму и показывает прогресс с того места, где он сейчас.

Как подключиться

Самый простой способ — просто запустить codespark attach без аргументов. CLI сам подтянет список ваших активных run'ов и предложит выбрать:

• Если активный run ровно один — подключение сразу.
• Если несколько — нумерованный список, введите номер.
• Если ни одного — увидите «Нет активных задач», команда выйдет с кодом 0.

Если run-id уже известен (например, из вывода первой строки стрим-логов или из скрипта) — можно сразу: codespark attach <run-id>.

Список запусков отдельно

Команда codespark runs показывает список ваших запусков — по умолчанию только активные. Полезна как самостоятельная проверка «что у меня крутится» и для скриптования:

codespark runs                        # активные
codespark runs --status=any           # все, включая завершённые
codespark runs --status=failed        # только упавшие
codespark runs show <run-id>          # подробности по одному

Что доступно подключившемуся

• Replay последних кадров (примерно 30 секунд до момента подключения) и все живые кадры дальше.
• Ctrl + C — попытка отмены: пройдёт только если это ваш собственный run, иначе сервер ответит «not the run owner».

Ограничения

• Подтверждать вызов инструмента (tool_result) может только тот клиент, который запустил run — у него есть workspace, у подключившегося нет.
• Завершённые run'ы остаются доступны для Attach ещё пять минут — чтобы успеть посмотреть финальный ответ, если вы только что зашли.

§Автоматизация на событиях

Нужно запустить тесты после ответа агента? Или потребовать дополнительное подтверждение перед git push? Или  автоматически добавлять git status к каждому промпту? Для этого есть hooks — локальные shell-команды, привязанные к событиям беседы.

События

• SessionStart — старт чата.
• UserPromptSubmit — перед отправкой промпта пользователя.
• PreToolUse — перед выполнением инструмента.
• PostToolUse — после выполнения инструмента.
• PermissionRequest — при запросе подтверждения у пользователя.
• Stop — завершение хода (run_done).
• SessionEnd — завершение чата.

Файл конфигурации

Конфиг живёт в .codespark/hooks.json в корне проекта (project-уровень) или в ~/.codespark/hooks.json (user-уровень).

{
  "version": 1,
  "hooks": [
    {
      "event": "PreToolUse",
      "match": { "toolName": "run_command", "commandPrefix": "git push" },
      "command": ".codespark/hooks/confirm-push.sh",
      "blocking": true,
      "timeoutMs": 5000
    },
    {
      "event": "Stop",
      "command": "make fmt",
      "blocking": false
    }
  ]
}

JSON-контракт

Хук получает контекст события на stdin в виде JSON (event, scope, conversationId, runId, для Pre/PostToolUse — toolName и args, для UserPromptSubmit — promptText). Может вернуть на stdout JSON-объект:

{
  "decision": "block" | "allow" | "continue",
  "context":  "текст, который добавится к промпту модели",
  "message":  "сообщение для пользователя"
}

decision: "block" отменяет действие (только для blocking-хуков). "allow" — разрешить без подтверждения. Поле context присоединяется к контексту модели (например, на UserPromptSubmit — чтобы прицепить вывод git status к каждому промпту).

§Делегирование специалистам

Большие задачи проще решать, разбивая их на части. Агент умеет это сам через специальный инструмент task: он запускает «специалиста» с собственным контекстом и ограниченным набором инструментов.

Доступные специалисты

Каждый специалист — это полноценный under-the-hood run со своим conversation_id и собственным system prompt'ом. Стоимость идёт через тот же billing pipeline, что и  у основного хода (специалист тратит ваши спарки точно так же, как и любой другой вызов модели).

В интерфейсе кадры специалиста группируются как «вложенный ход» под карточкой инструмента task. Старые клиенты, которые ещё не умеют группировать, — просто увидят кадры подряд в общем потоке.

Прямого вызова task снаружи нет — это инструмент для модели. Чтобы агент его использовал, попросите его явно: «спланируй сначала через task plan, затем реализуй» или  «отдай эту часть на ревью task review».

§Панели в VS Code

В боковой панели CodeSpark четыре раздела:

• Чат — основной интерфейс беседы с агентом.
• Разрешения — действующая политика разрешений (project поверх user). Allow помечен зелёным ✓, deny — красным ×, ask — жёлтым ?.
• MCP-серверы — запущенные внешние инструменты, их транспорт и состояние.
• Скиллы — скиллы из AGENTS.md, .codespark/skills/, .agents/, .claude/skills/.

Все панели read-only — редактирование происходит через файлы конфигурации либо CLI-команды (codespark permissions allow ..., codespark mcp add ...). Изменения подхватываются автоматически через FileSystemWatcher.

Команды палитры

Вызов через F1 / Ctrl+Shift+P:

• CodeSpark: Sign In — вход.
• CodeSpark: Sign Out — выход.
• CodeSpark: Open Chat — открыть панель чата.
• CodeSpark: New Conversation — начать новую беседу.
• CodeSpark: Open Billing — личный кабинет → биллинг.
• CodeSpark: Open Account — личный кабинет → аккаунт.
• CodeSpark: Toggle Mode (Chat / Agent) — переключить режим.
• CodeSpark: Set Mode… — выбрать режим из списка.

§CLI: команды и флаги

§Слеш-команды

В TUI интерактивного чата работают команды-слеши. Все имеют русские алиасы для удобства.

Кроме встроенных, в TUI работают пользовательские скиллы как слеш-команды: /<имя-скилла> подставит тело скилла из .codespark/skills/<имя>/SKILL.md.

§Файлы и директории

Глобальные (user-уровень)

• ~/.codespark/auth.json — токен авторизации (mode 0600).
• ~/.codespark/preferences.json — дефолтный режим per-cwd.
• ~/.codespark/permissions.json — user-политика разрешений.
• ~/.codespark/hooks.json — user-хуки.
• ~/.codespark/mcp.json — настройки MCP-серверов для CLI.
• ~/.codespark/checkpoints/ — журнал чекпоинтов (для rewind).
• ~/.codespark/audit.log — приложение append-only лог решений политики.
• ~/.codespark/update-check.json — кэш проверок обновлений CLI.

В корне проекта

• AGENTS.md или CLAUDE.md — правила проекта, читаются агентом перед каждым ходом.
• .codespark/permissions.json — project-политика (project поверх user).
• .codespark/hooks.json — project-хуки.
• .codespark/skills/<name>/SKILL.md — пользовательские скиллы.
• .codespark/agents/, .codespark/rules/ — зарезервировано для будущих расширений.
• .codesparkignore — дополнительные паттерны для скрытия от агента, помимо .gitignore.

Команда codespark init в корне проекта создаёт нужный минимум.

§Каталог моделей

Все модели доступны после входа — ничего настраивать не нужно.

Сменить модель прямо в беседе можно через /model <id> в TUI, через флаг --model на запуске CLI или через picker модели в панели чата VS Code.

§Спарки и биллинг

Спарк — внутренняя единица учёта вычислений в CodeSpark. Один спарк = 3 ₽. Стоимость каждого вызова считается по входным/выходным токенам и тарифу выбранной модели.

Тарифы

• Free — 50 спарков в месяц, чат и агент, бесплатные модели.
• Pro — 1 490 ₽/мес, 500 спарков, все модели.
• Pro Max — 3 790 ₽/мес, 1 500 спарков, приоритет в очереди.
• Pro Ultra — 11 990 ₽/мес, 5 000 спарков для тяжёлых агентных задач.

Докупка спарков

Если плановых не хватает, можно купить пакет: 100, 500 или 2 000 спарков. Докупленные спарки не сгорают и тратятся только после плановых.

Оплата

Все платежи проходят через ЮKassa. Принимаются карты МИР и через СБП. Иностранные карты не нужны. Чек 54-ФЗ формируется автоматически.

§Авторизация

Поддерживаются два способа входа:

• Email-OTP — одноразовый шестизначный код на вашу почту, действует ~10 минут. В CLI — команда codespark login.
• Яндекс ID OAuth — одна кнопка в интерфейсе VS Code; в CLI пока только Email-OTP.

Никаких паролей хранить не нужно. Токен сохраняется на диск с правами 0600.

Выйти из аккаунта — команда «CodeSpark: Sign Out» в палитре VS Code или codespark logout в CLI.

§Приватность

• На сервер уходят содержимое сообщений, путь и фрагменты файлов, на которые ссылается агент, и результат выполнения инструментов.
• Файлы из .gitignore и .codesparkignore не отправляются.
• Семантический индекс хранится на серверах в РФ.
• Пользовательские скриншоты, отправленные через upload-эндпоинт, удаляются автоматически через 30 дней.
• Чаты в статусе «удалён» вычищаются полностью через 30 дней.

Юридические документы — Политика конфиденциальности, Пользовательское соглашение, Оферта, Политика возврата.