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
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_assistantest introuvable, ajoutezexport 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 :
.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é) :
<dir_du_script>/.assistant_rules<dir_du_script>/../.assistant_rules<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 :
.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 sourceCherche leurs mentions dans les
.mdDé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 :
.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 16000ou--depth 1Reformulez via
--supplementRelancez la phase
correctionavec un autre--choice
Qdrant non accessible
Variables d'environnement
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 quecode_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_assistantouopencodeSur le poste de travail avec écran → Roo Code (VSCode)
En production / maintenance →
code_assistant(souverain, sans dépendance cloud)
🔗 Ressources
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
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