Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

code_assistant — Documentation

Assistant IA interactif pour l'analyse, la correction et le contrôle de code. Utilise Ollama (local/swarm), Qdrant (mémoire sémantique) et cpscript pour offrir un cycle complet d'amélioration de code guidé par l'IA.


Table des matières


Vue d'ensemble

code_assistant orchestre 4 couches :


Prérequis

Composant
Requis
Installation

python3

✅

sudo apt install python3

ollama (Python)

✅

pip install ollama

requests (Python)

Recommandé

pip install requests

Ollama (serveur)

✅

https://ollama.ai ou via IA/ollama.me.sh

Modèle grand contexte

Recommandé

sélectionné automatiquement (plus grand num_ctx)

deepseek-r1:14b

Fallback analyse

ollama pull deepseek-r1:14b

qwen2.5-coder:14b

Fallback correction

ollama pull qwen2.5-coder:14b

nomic-embed-text

Recommandé (mémoire)

ollama pull nomic-embed-text

Qdrant

Optionnel

Stack rnostr (install/install_rnostr_semantic.sh) ou docker run -p 6333:6333 -v ~/.zen/qdrant-data:/qdrant/storage qdrant/qdrant

curl, diff, jq

✅

sudo apt install curl diffutils jq

node

Optionnel (validation JS)

sudo apt install nodejs


Installation rapide

Note PATH : Si code_assistant est introuvable, ajoutez export PATH="$HOME/.local/bin:$PATH" à votre ~/.bashrc.


Utilisation de base

Mode interactif guidé (recommandé)

L'assistant affiche les problèmes triés par urgence décroissante et guide chaque étape :

Arbre de décision

Flux en ligne de commande (non-interactif)

Exemple de sortie — Phase ANALYSE


Options complètes


Profils automatiques (server / client)

code_assistant détecte automatiquement le profil selon l'extension du fichier fourni :

Extension
Profil
Contexte LLM injecté

.sh, .py

server

scripts Linux, Python, Bash

.html, .js, .css

client

web old-school, jQuery/vanilla

.md, .json

auto

client si .html/.js coexistent, sinon server

autre

server

fallback

Profil client — contraintes injectées automatiquement

Si aucun --supplement n'est fourni, le système injecte :

"HTML5 + CSS3 + JavaScript vanilla ou jQuery. Bibliothèques via <script src='...'> uniquement (CDN). PAS de frameworks modernes (React, Vue, Angular, Svelte, Next.js). PAS de npm, webpack, vite, TypeScript, Babel. PAS de modules ES6 (import/export)."

Les CDN déjà utilisés dans les .html du projet sont détectés et listés dans la contrainte.

Le profil est affiché dans l'en-tête :


Règles projet (.assistant_rules)

Créez un fichier .assistant_rules dans le répertoire du script, du projet ou de Astroport.ONE/ pour injecter des règles permanentes dans tous les prompts :

Recherche en cascade (premier trouvé) :

  1. <dir_du_script>/.assistant_rules

  2. <dir_du_script>/../.assistant_rules

  3. <dossier_code_assistant>/.assistant_rules

Si trouvé, affiché dans l'en-tête :

Le contenu est annexé au --supplement existant (sans l'écraser).


Flux de travail détaillé

Phase analyse

Objectif : Identifier les 3 problèmes prioritaires du code.

Entrée : Contexte code extrait par cpscript --json Sortie : Liste numérotée 1/2/3 avec catégorie, localisation, impact

Modèle : auto-sélectionné (meilleur contexte disponible) ou deepseek-r1:14b en fallback


Phase correction

Objectif : Générer 3 variantes de correction pour le problème choisi.

Modèle : même modèle que l'analyse (contexte max conservé) ou qwen2.5-coder:14b en fallback

Format JSON LLM :


Phase controle

Objectif : Vérifier la correction, identifier les risques.

Sortie : Rapport avec verdict (OK / ATTENTION / REFUSER)

Exemple de sortie :


Mode --test — Diagnostic actif

Le mode --test passe de l'injection passive à un diagnostic d'exécution réel :

1. Détection des fichiers de test

Cherche dans 4 répertoires candidats : tests/, ../tests/, test/, ../test/ Patterns : test_<script>.* et <script>_test.*

2. Dry Run

Avant l'envoi au LLM, exécute les tests détectés :

Extension
Runner prioritaire
Fallback

.py

pytest -x --tb=short

unittest

.sh

bats

bash <test>

3. Coverage Map (ast)

Extrait les fonctions publiques du script source et vérifie leur présence dans les fichiers de test. Sans coverage.py, 100% fiable via ast.

4. Injection dans le contexte LLM

Les résultats sont injectés dans des sections dédiées du contexte :

  • ### RÉSULTATS DES TESTS (dry run) ### — stacktraces réelles

  • ### COUVERTURE — fonctions non testées ### — gaps de couverture

5. System prompt adaptatif

Si tests en échec : l'IA est contrainte à résoudre uniquement les erreurs réelles. Si tests passants : l'IA identifie les fonctions non couvertes.

6. Contrainte non-régression (phase contrôle)

Avec --test, la phase controle exige obligatoirement :

"🔒 Fournis le bloc pytest/shunit2 qui aurait échoué AVANT et passe AVEC la correction."

Exemples


Mode --doc — Diagnostic actif

Le mode --doc va au-delà de l'injection des .md : il compare les signatures du code avec la documentation.

1. Détection des .md associés

cpscript --doc charge les fichiers .md de docs/ qui référencent le script.

2. Diagnostic signatures (Python)

Un script Python ast embarqué :

  • Extrait toutes les signatures def func(arg1, arg2) du code source

  • Cherche leurs mentions dans les .md

  • Détecte les arguments dans la doc qui n'existent plus dans le code

  • Détecte les fonctions `func()` dans la doc mais absentes du code

3. Injection dans le contexte LLM

Section ajoutée : ### INCOHÉRENCES DOC vs CODE ###

4. System prompt adaptatif

En mode --doc, l'IA est guidée vers la conformité code ↔ documentation.


Mémoire KV (--kvbasename)

La session est stockée dans ~/.zen/flashmem/code_assistant/<kvbasename>.json.

Structure KV

Reprendre une session


Intégration Qdrant

Qdrant est utilisé pour la mémoire sémantique entre les sessions.

Indexation automatique

À chaque phase, l'assistant indexe automatiquement le résumé de la session avec un ID stable via SHA-256 (pas de doublons entre redémarrages).

Apprentissage des refus

Quand un patch est refusé (n), l'outil propose d'enregistrer la raison :

La raison est indexée dans la collection ca_refusals de Qdrant. Lors des prochaines analyses, l'IA peut recevoir ce contexte : "L'utilisateur a précédemment rejeté une solution de type X car Y".

Recherche sémantique au démarrage

Avant chaque analyse, les 3 sessions les plus similaires sont récupérées et injectées dans le prompt (filtrées par langue : Python/Shell).

Utilisation directe de embed.py


Application des patches (--patch)

Mode diff interactif

Validation syntaxique préalable

Avant d'écraser le fichier, la syntaxe est vérifiée :

Extension
Outil
Comportement

.py

python3 -m py_compile

Bloque si invalide

.sh

bash -n

Bloque si invalide

.json

jq .

Bloque si invalide

.js

node --check

Bloque si invalide

.html

heuristique ast

Avertissement (non bloquant)

Sécurité anti-destruction

Si le patch représente moins de 70% des lignes de l'original (sur un fichier > 20 lignes) :

Backup automatique

Application directe en phase contrôle

Avec --patch en phase controle, l'approbation déclenche directement la phase correction+patch via exec — pas de commande à copier-coller.


Outils connexes

cpscript — Extraction récursive

Supporte .sh, .py, .html, .js, .css — suit récursivement les dépendances.

embed.py — Embeddings + Qdrant


Architecture

Flux de données complet


Dépannage

Ollama non disponible

Modèle manquant

cpscript ne génère pas de JSON valide

Patch non appliqué (aucun patch dans la réponse)

Le LLM n'a pas répondu au bon format. Consultez le log :

Solutions :

  • Réduisez le contexte : --maxtoken 16000 ou --depth 1

  • Reformulez via --supplement

  • Relancez la phase correction avec un autre --choice

Qdrant non accessible


Variables d'environnement

Variable
Défaut
Description

OLLAMA_HOST

http://localhost:11434

URL du serveur Ollama

QDRANT_URL

http://localhost:6333

URL du serveur Qdrant

CA_MAX_STDIN_MB

500

Limite RAM pour le JSON entrant


Exemples avancés

Analyse d'un projet Python complet

Cycle complet avec test et doc

Mode client web (profil auto)

Pipeline CI non-interactif



Assistants de code alternatifs pour le Capitaine

code_assistant est l'outil souverain et hors-ligne d'Astroport.ONE. Pour les phases de développement connectées, le capitaine peut utiliser des interfaces visuelles plus riches. Voici les options recommandées :


🖥️ Option 1 — VSCode + Roo Code (interface graphique)

Roo Code est une extension VSCode open-source qui offre une expérience similaire à Claude Code, avec support multi-modèle (Anthropic, OpenAI, Ollama…).

Avantages Roo Code :

  • Interface visuelle dans l'IDE avec diff coloré et approbation inline

  • Gestion des fichiers multi-repo dans un seul workspace

  • Support Ollama local → fonctionne hors-ligne avec les modèles de l'essaim

  • Mémoire de projet via .roo/ (règles, contexte)

  • Compatible .assistant_rules (même philosophie que code_assistant)

Fichier de règles Roo (~/.zen/Astroport.ONE/.roo/rules/rules.md) :

🔗 Dépôt officiel : https://github.com/RooVetGit/Roo-Code


⚡ Option 2 — OpenCode (terminal, style Claude Code)

OpenCode est un assistant de code en ligne de commande (TUI), open-source, inspiré de Claude Code. Il fonctionne dans le terminal sans VSCode.

Avantages OpenCode :

  • Interface TUI (terminal) — fonctionne en SSH sur une ♥BOX distante

  • Pas besoin de VSCode installé

  • Support natif Ollama → 100% local et souverain

  • Gestion de conversation multi-tours avec contexte projet

  • Compatible avec le workflow en 3 phases de code_assistant

🔗 Dépôt officiel : https://github.com/sst/opencode


📊 Comparatif des approches

Critère

code_assistant

Roo Code (VSCode)

OpenCode (TUI)

Interface

Terminal bash

Graphique IDE

Terminal TUI

Hors-ligne

✅ Ollama/P2P

✅ si Ollama

✅ si Ollama

Contexte Astroport

✅ cpscript récursif

Manuel

Manuel

Mémoire Qdrant

✅ intégrée

❌

❌

Accès SSH ♥BOX

✅

❌ (besoin X11)

✅

Multi-fichiers

✅ depth N

✅ workspace

✅

Souveraineté

✅✅ essaim swarm

✅ si Ollama

✅ si Ollama

Apprentissage refus

✅ Qdrant

❌

❌

Recommandation :

  • Sur la ♥BOX en SSH → code_assistant ou opencode

  • Sur le poste de travail avec écran → Roo Code (VSCode)

  • En production / maintenance → code_assistant (souverain, sans dépendance cloud)


🔗 Ressources

Outil
Lien

Roo Code extension

https://marketplace.visualstudio.com/items?itemName=RooVetGit.roo-cline

Roo Code GitHub

https://github.com/RooVetGit/Roo-Code

OpenCode GitHub

https://github.com/sst/opencode

Ollama (moteur IA local)

https://ollama.ai

Astroport.ONE essaim

bash ~/.zen/Astroport.ONE/IA/ollama.me.sh SCAN


Mis à jour le 2026-03-19 — Astroport.ONE / UPlanet

Dernières évolutions

Date
Fonctionnalité

2026-03-19

cpscript : support HTML/JS/CSS récursif (<script src>, import from, require)

2026-03-19

cpscript : --only html|js|css — filtres de type web

2026-03-19

code_assistant : sélection automatique du modèle avec le plus grand num_ctx (parallèle, ~0.5s)

2026-03-19

code_assistant : menu interactif station/modèle avant chaque lancement

2026-03-19

code_assistant : MAX_TOKEN calculé dynamiquement (80% du contexte réel du modèle)

Last updated