Руководство по началу работы с DeepSeek-Reasonix: ИИ-агент для программирования с низкими затратами

Обзор проекта

DeepSeek-Reasonix — это терминальный AI coding-агент. Это не просто командная строка для общения: он организует модель, инструменты, плагины, контекст проекта и процесс согласования в виде настраиваемого локального движка агента.

У него три ключевые особенности: во‑первых, по умолчанию он оптимизирован под длительные диалоги вокруг DeepSeek, особенно за счёт prefix cache — чтобы токены для последовательных задач разработки обходились дешевле; во‑вторых, Provider, модели, инструменты и плагины описываются в reasonix.toml, а не «зашиты» в коде программы; в‑третьих, он распространяется в виде бинарника для Go — поэтому CLI/TUI, десктоп‑клиент и расширение для VS Code могут переиспользовать один и тот же движок Reasonix.

В этой статье мы вместе соберём самый минимальный практический стенд: установим Reasonix, настроим DeepSeek API Key, инициализируем команды проекта, чтобы выполнить одну задачу на правку кода, а затем подключим OpenAI‑совместимый шлюз. В конце вы поймёте: когда стоит напрямую использовать DeepSeek, а когда лучше задействовать Defapi как единый интерфейс — так будет проще и спокойнее.

Сложность: средний уровень | Время: 20–40 минут | Результат: запуск DeepSeek-Reasonix и понимание подхода с конфигурацией, команд проекта, взаимодействием двух моделей и способом подключения к интерфейсу с низкой стоимостью

Кому это подойдёт

• Разработчикам, которые хотят собрать низкозатратный программный агент на базе DeepSeek
• Тем, кто часто правит код в терминале и ищет инженера‑помощника с локальным ИИ
• Тем, кто хочет подключить AI‑агента к репозиторию команды, но при этом беспокоится о стоимости токенов
• Тем, кто уже пробовал Claude Code, Codex, OpenClaw и хочет сравнить инструменты из экосистемы DeepSeek

Ключевые зависимости и окружение

Полное дерево структуры проекта

Мы подготовим минимальный демонстрационный проект:

reasonix-agent-demo/
├── .env.example
├── reasonix.toml
├── REASONIX.md
├── tasks/
│   └── bugfix.md
└── demo-app/
    ├── package.json
    └── src/
        └── price.ts

1. Установка Reasonix CLI

Самый простой способ — установить через npm:

npm i -g reasonix

Проверьте результат установки:

reasonix --version

Если вы используете macOS, можно также установить через Homebrew:

brew install esengine/reasonix/reasonix

Пользователям Windows рекомендуется запускать в PowerShell или Windows Terminal:

npm i -g reasonix
reasonix --version

2. Настройка DeepSeek API Key

Создайте демонстрационный каталог:

mkdir reasonix-agent-demo
cd reasonix-agent-demo

Подготовьте .env.example:

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
DEFAPI_API_KEY=defapi_xxxxxxxxxxxxxxxxxxxxx

Скопируйте в локальный env‑файл:

cp .env.example .env

В PowerShell:

Copy-Item .env.example .env

Затем внесите свой DeepSeek API Key.

3. Выполните setup для завершения начальной настройки

Теперь запустите команду инициализации:

reasonix setup

Следуя подсказкам, выберите Provider и модель. DeepSeek-Reasonix по умолчанию «дружелюбен» к DeepSeek — можно сначала выбрать Provider DeepSeek, а затем модель, подходящую для повседневных задач кодирования.

После завершения настройки запустите интерактивную сессию:

reasonix

Можете начать с простого вопроса:

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

Если Reasonix отвечает нормально — значит цепочка CLI ↔ модель ↔ API Key работает.

4. Создайте reasonix.toml, чтобы зафиксировать Provider

Чтобы конфигурация была воспроизводимой, запишем ключевые параметры в reasonix.toml:

default_model = "deepseek"
language = "zh"

[ui]
theme = "auto"

[agent]
temperature = 0.0
reasoning_language = "zh"
soft_compact_ratio = 0.5
tool_result_snip_ratio = 0.6
compact_ratio = 0.8
compact_force_ratio = 0.9

[[providers]]
name = "deepseek"
kind = "openai"
base_url = "https://api.deepseek.com"
models = ["deepseek-v4-flash", "deepseek-v4-pro"]
default = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

[environment]
enabled = true

Здесь несколько ключевых моментов:

• default_model указывает на имя Provider; дальше в рамках Provider можно переключать модель по умолчанию.
• temperature = 0.0 лучше подходит для задач правки кода — вывод будет стабильнее.
• context_window резервирует место для длинных диалогов.
• soft_compact_ratio и compact_ratio позволяют более управляемо поддерживать контекст.

При старте явно загрузите переменные окружения:

export $(grep -v '^#' .env | xargs)
reasonix

В PowerShell можно так:

Get-Content .env | ForEach-Object {
  if ($_ -match "^(.*?)=(.*)$") {
    [Environment]::SetEnvironmentVariable($matches[1], $matches[2], "Process")
  }
}
reasonix

5. Сгенерируйте команды проекта через /init

Когда агент выполняет задачи по коду, самое страшное — каждый раз заново объяснять правила проекта. Reasonix позволяет запускать это в интерактивной сессии:

/init

Он сгенерирует проектную инструкцию на основе текущего проекта. Также можно подготовить её вручную в REASONIX.md:

# Инструкция проекта Reasonix

## Цели проекта

Это минимальный пример проекта для проверки Reasonix programming‑агента.

## Правила разработки

- Перед изменением кода сначала опишите план.
- Для ключевых функций добавляйте комментарии на китайском.
- После завершения правок запускайте тесты проекта.
- Не отправляйте Git commit, если пользователь явно не просит.

## Частые команды

```bash
npm test

> [!TIP]
> Чем стабильнее проектная инструкция, тем проще попадать в prefix cache DeepSeek. Не стоит каждый день менять детали задач в долгосрочной инструкции — лучше держать их в отдельных task‑файлах.

## 6. Подготовьте реальную задачу по коду

Создадим минимальный TypeScript‑проект:

```bash
mkdir -p demo-app/src tasks
cd demo-app
npm init -y
npm i -D typescript tsx
npx tsc --init
cd ..

Создайте demo-app/src/price.ts:

export type PriceInput = {
  amount: number;
  discountRate?: number;
};

export function calculateFinalPrice(input: PriceInput): number {
  const discount = input.discountRate || 0;
  return input.amount * (1 - discount);
}

У этой функции есть типичная проблема: discountRate не проходит проверку границ; если передать 1.5, получится отрицательная цена.

Создайте tasks/bugfix.md:

# Задача: исправить проблему с границами расчёта цены

Пожалуйста, измените demo-app/src/price.ts:

1. amount должен быть больше или равен 0.
2. discountRate по умолчанию равен 0.
3. discountRate может быть только в диапазоне от 0 до 1.
4. Добавьте комментарии на китайском к calculateFinalPrice.
5. Добавьте минимальный тест или исполняемую проверку‑скрипт.

Теперь пусть Reasonix выполнит задачу:

reasonix run "Прочитайте tasks/bugfix.md и выполните описанную там правку кода."

Вы увидите, что Reasonix читает задачу, проверяет файлы, предлагает план изменений и затем вызывает инструменты, чтобы записать код. Это и есть отличие coding‑agent от обычного чат‑бота: он не только объясняет проблему — он входит в проект и правит файлы.

7. Настройте режим с двумя моделями: planner/executor

Одной модели уже хватает для многих задач, но для сложных обычно нужно сначала планировать, а затем выполнять. Reasonix поддерживает разбиение planner и executor в конфигурации:

[agent]
temperature = 0.0
planner_model = "deepseek-pro"
reasoning_language = "zh"

[[providers]]
name = "deepseek"
kind = "openai"
base_url = "https://api.deepseek.com"
models = ["deepseek-v4-flash", "deepseek-v4-pro"]
default = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

[[providers]]
name = "deepseek-pro"
kind = "openai"
base_url = "https://api.deepseek.com"
model = "deepseek-v4-pro"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

Практичная связка такая:

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

8. Подключение Defapi-совместимого интерфейса

Provider в Reasonix управляется конфигурацией: если целевой сервис совместим с интерфейсом в стиле OpenAI, его можно подключить как Provider. Это особенно удобно для подключения Defapi.

Преимущество Defapi в том, что цена обычно примерно вдвое ниже, а модели в целом совместимы с протоколами ниже:

• v1/chat/completions
• v1/messages
• v1beta/models/

Добавим Defapi Provider в reasonix.toml:

[[providers]]
name = "defapi-claude"
kind = "openai"
base_url = "https://api.defapi.org/api/v1"
model = "anthropic/claude-sonnet-4.5"
api_key_env = "DEFAPI_API_KEY"
context_window = 200000

Затем переключите модель по умолчанию:

default_model = "defapi-claude"

Также можно оставить DeepSeek как основной executor, а сильные модели с Defapi — использовать как planner:

default_model = "deepseek"

[agent]
planner_model = "defapi-claude"
temperature = 0.0

[[providers]]
name = "deepseek"
kind = "openai"
base_url = "https://api.deepseek.com"
models = ["deepseek-v4-flash", "deepseek-v4-pro"]
default = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000
effort = "high"

[[providers]]
name = "defapi-claude"
kind = "openai"
base_url = "https://api.defapi.org/api/v1"
model = "anthropic/claude-sonnet-4.5"
api_key_env = "DEFAPI_API_KEY"
context_window = 200000

Такая комбинация отлично подходит под реальную разработку: обычные задачи идут через DeepSeek для контроля затрат, а сложное планирование или ревью кода — через сильную модель на Defapi. После унификации на уровне Provider Reasonix не нужно писать новый код под каждого вендора моделей.

9. Запустите полную проверку

Теперь сделаем полноценную валидацию:

reasonix run "Проверьте реализацию demo-app/src/price.ts и скажите, есть ли ещё проблемы с границами."

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

reasonix run "Добавьте для demo-app команду npm test и используйте минимальный скрипт, чтобы проверить три сценария: нормальная цена, скидка и некорректная скидка для calculateFinalPrice."

И в конце посмотрите изменения в Git:

git diff

Если вы увидите, что Reasonix изменил код, добавил тесты и объяснил причины правок — значит минимальный workflow агента уже работает.

Частые проблемы и как их устранить

1. Команда reasonix не находится

Сначала проверьте глобальный npm‑каталог:

npm config get prefix
npm bin -g

Если npm bin -g недоступен, используйте:

npm root -g

После того как найдёте глобальный каталог установки, добавьте каталог с соответствующими исполняемыми файлами в PATH. На Windows обычно нужно заново открыть терминал.

2. Недостаточно прав для глобальной установки npm

На macOS/Linux не рекомендуется жёстко ставить с sudo. Можно перенести глобальный каталог npm в домашний каталог пользователя:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
npm i -g reasonix

Затем запишите конфигурацию PATH в файл запуска вашего shell.

3. DeepSeek API Key не применяется

Сначала проверьте, существует ли переменная окружения:

echo "$DEEPSEEK_API_KEY"

В PowerShell:

$env:DEEPSEEK_API_KEY

Если значение пустое — значит текущий терминал не загрузил .env. Можно сначала подставить вручную:

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"
reasonix

4. reasonix.toml не читается

Конфигурация Reasonix обычно разбирается в порядке: параметры командной строки, конфигурация текущего каталога, пользовательская глобальная конфигурация, встроенные значения по умолчанию. Сначала проверьте, что вы запускаете команду из корня проекта:

pwd
ls reasonix.toml

Затем выполните:

reasonix run "Пожалуйста, укажите, какую модель и Provider вы сейчас используете."

Если вывод не совпадает с конфигурацией — в первую очередь проверьте, не перекрывают ли аргументы командной строки или глобальная конфигурация параметры из текущего каталога.

5. Модель отвечает медленно или слишком дорого

Сначала разбейте задачу на части:

reasonix run "Сначала только прочитайте demo-app/src/price.ts, не изменяйте, а укажите потенциальные проблемы."

А затем попросите внести правки:

reasonix run "На основе только что найденных проблем внесите правки только в demo-app/src/price.ts."

В длинных диалогах стабильные проектные инструкции и небольшие изменения в описании задач повышают шанс попадания в кэш. Для сложных задач включайте режим planner/executor с двумя моделями: модель с высокой стоимостью держите только в планировании.

6. Агент не запрашивает согласование перед изменением файлов

Проверьте текущий режим работы. В интерактивной сессии можно переключиться на более консервативный режим, где перед вызовом инструментов требуется подтверждение. Для командных проектов рекомендуется включать согласование по умолчанию — не переходите сразу в полностью автоматический режим без надзора.

Сначала можно попросить Reasonix только анализировать:

reasonix run "Только анализируйте, не меняйте файлы: проверьте проблему в demo-app/src/price.ts."

После подтверждения плана — выполняйте изменения.

7. Китайские иероглифы отображаются с искажениями в терминале Windows

В PowerShell можно сначала настроить UTF‑8:

chcp 65001
$OutputEncoding = [System.Text.Encoding]::UTF8

Если вывод всё равно работает некорректно, рекомендуется использовать Windows Terminal и убедиться, что редактор, терминал и Git настроены на UTF‑8.

Дополнительное чтение / направление развития

• Используйте десктоп‑клиент Reasonix и переносите терминальный workflow агента в графический интерфейс.
• Установите расширение для VS Code, чтобы Reasonix мог читать контекст редактора и обрабатывать согласование вызовов инструментов.
• Настройте MCP-compatible плагины: подключайте внутренние скрипты, запросы к базе данных и поиск по документации к агенту.
• Используйте sub‑agent’ов для задач вроде review, security_review, research и т. п.
• Подключите Reasonix к рабочему процессу OpenClaw, чтобы точка входа в чат запускала реальные задачи с кодом.
• Подключите Defapi через v1/chat/completions или v1/messages, чтобы единообразно управлять поставщиками моделей вроде DeepSeek, Claude, Gemini.