Guia de Início Rápido do DeepSeek-Reasonix: Agent de Programação com IA de Baixo Custo

Visão geral do projeto

O DeepSeek-Reasonix é um agente de codificação com IA voltado para o usuário final. Ele não é apenas um comando de chat em linha de comando; em vez disso, organiza o modelo, ferramentas, plugins, contexto do projeto e o fluxo de aprovação em um motor local de agentes, configurável.

As suas características principais são três: primeiro, ele já vem com otimizações para sessões longas focadas no DeepSeek por padrão, especialmente dando grande importância ao prefix cache, para reduzir o custo de tokens em tarefas de desenvolvimento contínuas; segundo, Provider, modelos e ferramentas e plugins ficam todos definidos no reasonix.toml, em vez de estarem embutidos de forma fixa no programa; terceiro, ele é distribuído como um binário Go estático, reutilizável para CLI/TUI, aplicativo desktop e extensão do VS Code, usando a mesma base do motor Reasonix.

Neste artigo, vamos montar juntos um exemplo prático mínimo: instalar o Reasonix, configurar a DeepSeek API Key, inicializar as instruções do projeto para que ele conclua uma tarefa de alteração de código e, por fim, integrar um gateway compatível com OpenAI. No final, você vai saber quando é melhor usar o DeepSeek diretamente e quando vale mais a pena usar o Defapi como uma interface unificada.

Dificuldade: Intermediário | Duração: 20-40 minutos | Resultado: rodar o DeepSeek-Reasonix e entender a abordagem orientada a configuração, as instruções do projeto, a colaboração entre dois modelos e a integração de uma interface de baixo custo

Perfil de público-alvo

• Desenvolvedores que querem montar um agent de programação de baixo custo com DeepSeek
• Pessoas que frequentemente alteram código no terminal e desejam um assistente local de IA
• Quem quer integrar agentes de IA ao repositório da equipe, mas se preocupa com o custo de tokens
• Já usaram Claude Code, Codex e OpenClaw e querem comparar as ferramentas do ecossistema DeepSeek

Dependências principais e ambiente

Árvore completa de estrutura do projeto

Preparamos um projeto de demonstração mínimo:

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

1. Instalar o Reasonix CLI

A forma mais simples é instalar via npm:

npm i -g reasonix

Confirmar o resultado da instalação:

reasonix --version

Se você usa macOS, também pode usar Homebrew:

brew install esengine/reasonix/reasonix

Para usuários do Windows, recomenda-se executar no PowerShell ou no Windows Terminal:

npm i -g reasonix
reasonix --version

2. Configurar a DeepSeek API Key

Crie um diretório de demonstração:

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

Prepare o .env.example:

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
DEFAPI_API_KEY=defapi_xxxxxxxxxxxxxxxxxxxxx

Copie para o arquivo de ambiente local:

cp .env.example .env

No PowerShell:

Copy-Item .env.example .env

Agora preencha com sua própria DeepSeek API Key.

3. Rodar setup para concluir a configuração inicial

Agora execute o comando de inicialização:

reasonix setup

Siga as instruções para escolher o Provider e o modelo. O DeepSeek-Reasonix já vem por padrão mais amigável ao DeepSeek; você pode primeiro escolher o Provider DeepSeek e depois selecionar um modelo adequado para tarefas comuns de codificação.

Após concluir a configuração, inicie a sessão interativa:

reasonix

Você pode começar perguntando algo simples:

Por favor, informe quais arquivos existem no diretório atual do projeto e onde você recomenda começar a inicialização.

Se o Reasonix responder normalmente, significa que a cadeia CLI → modelo → API Key já está funcionando.

4. Criar um reasonix.toml para fixar o Provider

Para garantir que a configuração seja reproduzível, vamos escrever as partes principais no 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

Aqui estão alguns pontos-chave:

• default_model aponta para o nome do Provider; depois você pode alternar o modelo padrão dentro do Provider.
• temperature = 0.0 é mais adequado para tarefas de modificação de código, pois deixa a saída mais estável.
• context_window reserva espaço para sessões longas.
• soft_compact_ratio e compact_ratio tornam a manutenção do contexto mais controlável.

Na inicialização, carregue explicitamente as variáveis de ambiente:

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

No PowerShell:

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

5. Usar /init para gerar as instruções do projeto

Ao fazer tarefas de código, o agente mais teme ter que explicar novamente as regras do projeto a cada vez. O Reasonix permite executar no contexto de uma sessão interativa:

/init

Ele vai gerar um conjunto de instruções do projeto a partir do projeto atual. Você também pode preparar manualmente o REASONIX.md:

# Instruções do Projeto Reasonix

## Objetivos do projeto

Este é um projeto mínimo de exemplo para validar um agent de programação com Reasonix.

## Regras de desenvolvimento

- Antes de alterar o código, explique o plano.
- Adicione comentários em chinês às funções principais.
- Após concluir a alteração, execute os testes do projeto.
- Não faça commit no Git, a menos que o usuário solicite explicitamente.

## Comandos comuns

```bash
npm test

> [!TIP]
> Quanto mais estáveis forem as instruções do projeto, mais fácil será atingir o prefix cache do DeepSeek. Não é recomendado colocar detalhes de tarefas que mudam todos os dias em instruções de longo prazo; é melhor deixá-los em arquivos de tarefas separados.

## 6. Preparar uma tarefa real de código

Vamos criar um projeto mínimo em TypeScript:

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

Crie 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);
}

Essa função tem um problema comum: o discountRate não tem validação de limites; se você passar 1.5, o resultado será um preço negativo.

Crie tasks/bugfix.md:

# Tarefa: corrigir problema de limites no cálculo de preços

Por favor, altere demo-app/src/price.ts:

1. amount deve ser maior ou igual a 0.
2. discountRate tem valor padrão 0.
3. discountRate só pode ficar entre 0 e 1.
4. Adicione comentários em chinês para calculateFinalPrice.
5. Inclua um teste mínimo ou um script de validação executável.

Agora deixe o Reasonix executar a tarefa:

reasonix run "Leia tasks/bugfix.md e conclua a alteração de código descrita ali."

Você verá que o Reasonix lê a tarefa, verifica os arquivos, propõe um plano de mudanças e então chama as ferramentas para gravar o código. Esse processo é a diferença entre um coding agent e um robô de chat comum: ele não só explica o problema, como também entra no projeto e modifica os arquivos.

7. Configurar o modo de dois modelos planner/executor

O modo de um único modelo consegue resolver muitas tarefas, mas exigências complexas geralmente pedem planejamento antes da execução. O Reasonix permite separar planner e executor na configuração:

[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"

Uma combinação prática é:

Assim você controla custos e, ao mesmo tempo, deixa o modelo mais forte participar das decisões nas etapas críticas.

8. Integrar uma interface compatível com Defapi

O Provider do Reasonix é orientado por configuração: basta que o serviço alvo seja compatível com uma interface no estilo OpenAI para ser usado como Provider. Isso é perfeito para integrar Defapi.

A vantagem do Defapi é que o preço costuma ser normalmente metade do oficial, e os modelos são compatíveis com o seguinte protocolo:

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

Podemos adicionar um Provider do Defapi no 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

Depois, altere o modelo padrão:

default_model = "defapi-claude"

Também é possível manter o DeepSeek como executor padrão e usar os modelos fortes do Defapi como 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

Esse tipo de combinação é ideal para desenvolvimento real: tarefas comuns passam pelo DeepSeek para controlar custos, enquanto planejamento complexo ou revisão de código passam pelos modelos fortes do Defapi. Como a camada Provider fica unificada, o Reasonix não precisa escrever código novo para cada fornecedor de modelos.

9. Executar uma validação completa

Agora vamos fazer uma validação completa:

reasonix run "Verifique a implementação de demo-app/src/price.ts e diga se ainda existem problemas de limites."

Em seguida, peça para executar uma tarefa mais próxima do trabalho real:

reasonix run "Adicione um comando npm test para demo-app e use um script mínimo para validar três cenários: preço normal, desconto e desconto inválido para calculateFinalPrice."

Por fim, verifique as alterações no Git:

git diff

Se você perceber que o Reasonix alterou o código, adicionou testes e explicou as razões das mudanças, isso significa que o fluxo mínimo do seu agent já está funcionando.

Solução de problemas comuns

1. Não foi possível encontrar o comando reasonix

Primeiro confirme o diretório global do npm:

npm config get prefix
npm bin -g

Se npm bin -g não estiver disponível, use:

npm root -g

Depois de encontrar o diretório de instalação global, adicione o diretório dos executáveis ao PATH. No Windows, normalmente é necessário abrir o terminal novamente.

2. Permissão insuficiente para instalar globalmente no npm

No macOS/Linux, não é recomendado instalar forçando com sudo. Podemos alterar o diretório global do npm para o diretório do usuário:

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

Depois, grave a configuração do PATH no arquivo de inicialização do seu shell.

3. A DeepSeek API Key não está funcionando

Verifique primeiro se a variável de ambiente existe:

echo "$DEEPSEEK_API_KEY"

No PowerShell:

$env:DEEPSEEK_API_KEY

Se estiver vazia, significa que o terminal atual não carregou o .env. Você pode injetar manualmente antes:

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"
reasonix

4. reasonix.toml não está sendo lido

A configuração do Reasonix normalmente é interpretada na ordem: parâmetros do comando, configuração do diretório atual, configuração global do usuário e valores padrão embutidos. Primeiro confirme que você está executando a partir da raiz do projeto:

pwd
ls reasonix.toml

Depois execute:

reasonix run "Explique qual modelo e qual Provider você está usando no momento."

Se a saída não bater com a configuração, verifique primeiro se os argumentos de linha de comando ou a configuração global estão sobrepondo a configuração do diretório atual.

5. O modelo responde devagar ou o custo está alto

Primeiro quebre a tarefa em partes menores:

reasonix run "Apenas leia demo-app/src/price.ts; não modifique nada; aponte possíveis problemas."

Depois peça para que ele modifique:

reasonix run "Com base nos problemas mencionados, altere apenas demo-app/src/price.ts."

Em sessões longas, instruções de projeto estáveis e descrições com poucas mudanças aumentam as chances de acerto no cache. Para tarefas complexas, ative o modo de dois modelos planner/executor e deixe o modelo mais caro apenas nas etapas de planejamento.

6. O agent não solicita aprovação antes de alterar arquivos

Verifique o modo de trabalho atual. Na sessão interativa, você pode alternar para um modo mais conservador, que exige confirmação antes de chamar as ferramentas. Para projetos em equipe, recomenda-se manter a aprovação ativada por padrão e não entrar diretamente em um modo de alteração automática sem supervisão.

Você pode fazer o Reasonix primeiro fazer apenas análise (somente leitura):

reasonix run "Apenas analise, não modifique arquivos: verifique os problemas em demo-app/src/price.ts."

Depois de confirmar o plano, execute a alteração.

7. Texto em chinês ilegível no terminal do Windows

No PowerShell, você pode primeiro configurar UTF-8:

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

Se a saída ainda estiver estranha, recomenda-se usar o Windows Terminal e garantir que o editor, o terminal e o Git estejam usando UTF-8.

Leitura adicional / Direções avançadas

• Use o app desktop do Reasonix para levar o fluxo de trabalho do agente no terminal para uma interface gráfica.
• Instale a extensão do VS Code para que o Reasonix leia o contexto do editor e trate aprovações das ferramentas.
• Configure plugins compatíveis com MCP para integrar scripts internos, consultas a banco de dados e busca em documentos ao agente.
• Use sub-agentes para tarefas como review, security_review e research.
• Integre o Reasonix ao fluxo de trabalho do OpenClaw para que a entrada do chat dispare tarefas reais de código.
• Integre Defapi em v1/chat/completions ou v1/messages para gerenciar de forma unificada provedores de modelos como DeepSeek, Claude e Gemini.