Guide de démarrage de DeepSeek-Reasonix : un agent de programmation IA à faible coût

Présentation du projet

DeepSeek-Reasonix est un agent de codage IA orienté terminal. Ce n’est pas une simple interface de chat en ligne de commande, mais un moteur d’agent local configurable qui organise le modèle, les outils, les plugins, le contexte du projet et le flux d’approbation en un ensemble cohérent.

Ses trois caractéristiques principales sont les suivantes : premièrement, il est optimisé par défaut pour les longues sessions autour de DeepSeek, avec une attention particulière portée au prefix cache, afin de réduire le coût en tokens des tâches de développement continues ; deuxièmement, le Provider, les modèles, les outils et les plugins sont définis dans reasonix.toml, et non codés en dur dans le programme ; troisièmement, il est distribué sous forme d’un binaire Go unique, réutilisable par le CLI/TUI, l’application de bureau et l’extension VS Code via le même moteur Reasonix.

Dans cet article, construisons ensemble une mise en pratique minimale : installer Reasonix, configurer la clé API DeepSeek, initialiser les instructions du projet, lui faire effectuer une tâche de modification de code, puis connecter une passerelle compatible OpenAI. À la fin, vous saurez quand utiliser DeepSeek directement, et quand il est plus simple d’utiliser Defapi comme interface unifiée.

Difficulté : intermédiaire | Durée : 20-40 minutes | Résultat : faire fonctionner DeepSeek-Reasonix et comprendre la configuration pilotée par fichier, les instructions projet, la collaboration à deux modèles et l’intégration d’interfaces à faible coût

Profil des lecteurs visés

• Développeurs qui veulent construire un agent de programmation à faible coût avec DeepSeek
• Ingénieurs qui modifient souvent du code dans le terminal et souhaitent un assistant IA local
• Personnes qui veulent intégrer un agent IA dans un dépôt d’équipe tout en surveillant le coût en tokens
• Utilisateurs de Claude Code, Codex ou OpenClaw qui souhaitent comparer les outils de l’écosystème DeepSeek

Dépendances et environnement requis

Arborescence complète du projet

Nous préparons un projet de démonstration minimal :

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

1. Installer le CLI Reasonix

La méthode la plus simple consiste à l’installer via npm :

npm i -g reasonix

Vérifiez l’installation :

reasonix --version

Si vous utilisez macOS, vous pouvez aussi passer par Homebrew :

brew install esengine/reasonix/reasonix

Pour Windows, il est recommandé d’exécuter la commande dans PowerShell ou Windows Terminal :

npm i -g reasonix
reasonix --version

2. Configurer la clé API DeepSeek

Créez un répertoire de démonstration :

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

Préparez .env.example :

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
DEFAPI_API_KEY=defapi_xxxxxxxxxxxxxxxxxxxxx

Copiez-le en fichier d’environnement local :

cp .env.example .env

Sous PowerShell :

Copy-Item .env.example .env

Renseignez ensuite votre propre clé API DeepSeek.

3. Exécuter setup pour terminer la configuration initiale

Exécutez maintenant la commande d’initialisation :

reasonix setup

Suivez les invites pour choisir le Provider et le modèle. DeepSeek-Reasonix est optimisé pour DeepSeek par défaut : vous pouvez d’abord sélectionner le Provider DeepSeek, puis choisir un modèle adapté aux tâches de codage quotidiennes.

Une fois la configuration terminée, lancez une session interactive :

reasonix

Vous pouvez commencer par poser une question simple :

Expliquez quels fichiers se trouvent actuellement dans le répertoire du projet, et par où vous recommandez de commencer l’initialisation.

Si Reasonix répond correctement, cela signifie que la chaîne CLI, modèle et clé API fonctionne.

4. Créer reasonix.toml pour figer le Provider

Pour rendre la configuration reproductible, nous écrivons les paramètres clés dans 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

Quelques points clés ici :

• default_model pointe vers le nom du Provider ; vous pourrez ensuite changer le modèle par défaut à l’intérieur du Provider.
• temperature = 0.0 convient mieux aux tâches de modification de code, avec des sorties plus stables.
• context_window réserve de l’espace pour les longues sessions.
• soft_compact_ratio et compact_ratio rendent la gestion du contexte plus contrôlable.

Chargez explicitement les variables d’environnement au démarrage :

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

Sous PowerShell, vous pouvez écrire :

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

5. Générer des instructions de projet avec /init

Lorsqu’un agent effectue des tâches de code, le plus difficile est souvent de ne pas devoir réexpliquer à chaque fois les règles du projet. Reasonix permet d’exécuter dans la session interactive :

/init

Il générera alors des instructions de projet à partir du dépôt courant. Nous pouvons aussi préparer manuellement REASONIX.md :

# Instructions de projet Reasonix

## Objectif du projet

Il s’agit d’un projet minimal servant à vérifier l’agent de programmation Reasonix.

## Règles de développement

- Expliquer le plan avant de modifier le code.
- Ajouter des commentaires en chinois aux fonctions clés.
- Exécuter les tests du projet après les modifications.
- Ne pas valider de commit Git, sauf demande explicite de l’utilisateur.

## Commandes courantes

```bash
npm test

> [!TIP]
> Plus les instructions du projet sont stables, plus le prefix cache de DeepSeek a de chances d’être activé. N’écrivez pas dans les instructions longues des détails qui changent tous les jours ; il est plus approprié de les placer dans un fichier de tâche séparé.

## 6. Préparer une tâche de code réelle

Créons un projet TypeScript minimal :

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

Créez 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);
}

Cette fonction a un problème courant : discountRate n’a pas de validation des bornes ; si l’on passe 1.5, on obtient un prix négatif.

Créez tasks/bugfix.md :

# Tâche : corriger le problème de bornes du calcul de prix

Veuillez modifier demo-app/src/price.ts :

1. amount doit être supérieur ou égal à 0.
2. discountRate doit par défaut valoir 0.
3. discountRate ne peut être compris qu’entre 0 et 1.
4. Ajouter des commentaires en chinois à calculateFinalPrice.
5. Ajouter un test minimal ou un script de vérification exécutable.

Demandez maintenant à Reasonix d’exécuter la tâche :

reasonix run "Lisez tasks/bugfix.md et réalisez les modifications de code qui y sont décrites."

Vous verrez Reasonix lire la tâche, vérifier les fichiers, proposer un plan de modification, puis utiliser les outils pour écrire le code. C’est précisément ce qui distingue un agent de codage d’un simple chatbot : il n’explique pas seulement le problème, il entre dans le projet et modifie les fichiers.

7. Configurer le mode double modèle planner/executor

Le mode à modèle unique permet déjà d’accomplir de nombreuses tâches, mais les demandes complexes nécessitent souvent une phase de planification avant l’exécution. Reasonix permet de séparer planner et executor dans la configuration :

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

Une combinaison pratique est la suivante :

De cette façon, vous contrôlez le coût tout en faisant intervenir un modèle plus puissant dans les étapes critiques de décision.

8. Connecter une interface compatible Defapi

Les Providers de Reasonix sont pilotés par configuration : tant que le service cible est compatible avec une interface de style OpenAI, il peut être ajouté comme Provider. C’est particulièrement adapté à l’intégration de Defapi.

L’avantage de Defapi est que son prix est généralement la moitié de celui de l’offre officielle, et que les modèles sont globalement compatibles avec les protocoles suivants :

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

Nous pouvons ajouter un Provider Defapi dans 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

Puis changer le modèle par défaut :

default_model = "defapi-claude"

Il est aussi possible de conserver DeepSeek comme exécuteur par défaut, et d’utiliser le modèle puissant disponible via Defapi comme 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

Cette combinaison est très adaptée au développement réel : les tâches courantes passent par DeepSeek pour maîtriser les coûts, tandis que la planification complexe ou la revue de code passent par le modèle plus fort de Defapi. Une fois la couche Provider unifiée, Reasonix n’a plus besoin d’écrire du nouveau code pour chaque fournisseur de modèles.

9. Effectuer une vérification complète

Faisons maintenant une validation complète :

reasonix run "Vérifiez l’implémentation de demo-app/src/price.ts et indiquez s’il reste des problèmes de bornes."

Demandez ensuite une tâche plus proche du travail réel :

reasonix run "Ajoutez à demo-app une commande npm test, et utilisez un script minimal pour vérifier les trois cas suivants pour calculateFinalPrice : prix normal, remise, remise invalide."

Enfin, examinez les modifications Git :

git diff

Si vous voyez que Reasonix a modifié le code, ajouté des tests et expliqué la raison des changements, cela signifie que ce workflow minimal d’agent fonctionne correctement.

Dépannage des problèmes courants

1. La commande reasonix est introuvable

Vérifiez d’abord le répertoire global de npm :

npm config get prefix
npm bin -g

Si npm bin -g n’est pas disponible, utilisez :

npm root -g

Une fois le répertoire d’installation globale trouvé, ajoutez le dossier des exécutables correspondant à PATH. Sous Windows, il faut souvent rouvrir le terminal.

2. Permissions insuffisantes lors de l’installation globale npm

Sur macOS/Linux, il n’est pas recommandé d’ajouter simplement sudo pour forcer l’installation. Vous pouvez déplacer le répertoire global npm dans le dossier utilisateur :

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

Ajoutez ensuite cette configuration PATH au fichier de démarrage de votre shell.

3. La clé API DeepSeek ne semble pas prise en compte

Vérifiez d’abord si la variable d’environnement existe :

echo "$DEEPSEEK_API_KEY"

Sous PowerShell :

$env:DEEPSEEK_API_KEY

Si c’est vide, cela signifie que le terminal courant n’a pas chargé .env. Vous pouvez l’injecter manuellement :

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"
reasonix

4. reasonix.toml n’est pas lu

Reasonix analyse généralement la configuration dans l’ordre « arguments de commande, configuration du répertoire courant, configuration globale utilisateur, valeurs par défaut intégrées ». Vérifiez d’abord que vous exécutez la commande à la racine du projet :

pwd
ls reasonix.toml

Puis lancez :

reasonix run "Indiquez quel modèle et quel Provider sont actuellement utilisés."

Si la sortie ne correspond pas à la configuration, commencez par vérifier si des paramètres de ligne de commande ou une configuration globale ne remplacent pas la configuration du répertoire courant.

5. Le modèle répond lentement ou le coût est trop élevé

Commencez par découper la tâche :

reasonix run "Lisez uniquement demo-app/src/price.ts, ne modifiez rien pour l’instant, et signalez les problèmes potentiels."

Puis demandez-lui de modifier le fichier :

reasonix run "En vous basant sur les problèmes identifiés, modifiez uniquement demo-app/src/price.ts."

Dans les longues sessions, des instructions de projet stables et des descriptions de tâche peu changeantes favorisent davantage les hits de cache. Pour les tâches complexes, vous pouvez activer le double modèle planner/executor et ne réserver le modèle coûteux qu’à l’étape de planification.

6. L’agent modifie les fichiers sans approbation

Vérifiez le mode de travail actuel. Dans une session interactive, vous pouvez passer à un mode plus conservateur et exiger une confirmation avant les appels d’outils. Pour les projets d’équipe, il est conseillé d’activer l’approbation par défaut et d’éviter le mode de modification automatique sans supervision.

Vous pouvez d’abord demander à Reasonix une analyse en lecture seule :

reasonix run "Analyse uniquement, ne modifiez aucun fichier : vérifiez les problèmes de demo-app/src/price.ts."

Après validation du plan, lancez ensuite les modifications.

7. Caractères chinois illisibles dans le terminal Windows

Sous PowerShell, commencez par définir l’UTF-8 :

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

Si la sortie reste anormale, il est recommandé d’utiliser Windows Terminal et de vérifier que l’éditeur, le terminal et Git utilisent tous UTF-8.

Lectures complémentaires / pistes avancées

• Utiliser l’application de bureau Reasonix pour déplacer le workflow d’agent terminal vers une interface graphique.
• Installer l’extension VS Code afin que Reasonix lise le contexte de l’éditeur et gère les approbations d’outils.
• Configurer des plugins compatibles MCP pour intégrer scripts internes, requêtes de base de données et recherche documentaire dans l’agent.
• Utiliser des sous-agents pour répartir les tâches review, security_review, research, etc.
• Connecter Reasonix au workflow OpenClaw pour déclencher de vraies tâches de code depuis l’interface de chat.
• Intégrer les v1/chat/completions ou v1/messages de Defapi pour gérer de manière unifiée des fournisseurs de modèles comme DeepSeek, Claude ou Gemini.