2026-10-12 00:41:17 +02:00

9.7 KiB

Raw Blame History

MagicCode

Assistant IA en ligne de commande. Le mode (comportement de l'agent) vient d'une extension, le LLM se choisit indépendamment, l'interface utilise Ink (React pour CLI).

Démarrer

pnpm install
cp btp_AI_tpl.json btp_AI.json   # puis renseigner url, basic, serviceurls.AI_API_URL
pnpm dev                                  # mode claudecode ; le modèle est choisi dans la liste au démarrage
pnpm dev -- --model sapaicore:anthropic--claude-4.5-sonnet
pnpm dev -- --model anthropic:opus       # API Anthropic directe (ANTHROPIC_API_KEY)
pnpm test                                 # test de la boucle agent (provider factice)
pnpm build && node packages/cli/dist/index.js

Lancer MagicCode depuis un autre dossier

pnpm dev s'exécute depuis la racine du dépôt : le dossier de travail est alors cette racine (./btp_AI.json, ./CLAUDE.md… y sont cherchés). Pour utiliser MagicCode sur un autre projet ./X, lancez-le depuis ./X :

pnpm build
cd packages/cli && pnpm link --global     # une fois : installe la commande `magiccode`
cd ~/X && magiccode                       # le dossier de travail est ~/X
# ou sans installer :  cd ~/X && node /chemin/vers/magiccode/packages/cli/dist/index.js
# ou en développement : MAGICCODE_CWD=~/X pnpm --dir /chemin/vers/magiccode dev

Pourquoi pas pnpm --filter … dev : pnpm exécute alors le script depuis packages/cli, pas depuis le dossier où vous avez tapé la commande. MagicCode tient compte de MAGICCODE_CWD, puis de INIT_CWD (dossier où pnpm/npm a été lancé), puis de process.cwd().

Architecture

Paquet	Rôle
`core`	Contrats (`LLMProvider`, `AgentMode`, `Extension`, `Tool`, `AgentUI`), boucle agent, registre, chargement des extensions
`providers`	Adaptateurs LLM : `sapaicore` (premier provider, voir ci-dessous), `anthropic` (direct), `openai` et `ollama` (à faire)
`ui`	Interface Ink/React (journal, saisie, listes de choix, confirmations, spinner)
`ext-claudecode`	Mode par défaut : CLAUDE.md, dossiers `.claude` (settings, commandes, skills) + outils Read/Glob/Grep/Write/Edit/Bash
`cli`	Point d'entrée : configuration, extensions, boucle de conversation

Résolution du mode et du modèle (le modèle n'a pas de défaut : s'il n'est pas défini, il est demandé) : flags CLI > variables MAGICCODE_MODE / MAGICCODE_MODEL

.magiccode/config.json (projet) > ~/.magiccode/config.json > défauts.

Extensions tierces : ~/.magiccode/extensions/<nom>/index.js (export default d'un objet Extension).

Interface (Ink)

L'interface est une application React rendue par Ink (Ink 7 : React ≥ 19.2 ; vérifiez la version de Node qu'il exige). Le CLI garde une façade impérative (InkUI : info, select, readInput, confirm, withSpinner…) au-dessus d'un UIStore sans dépendance à React, ce qui rend la logique testable (store.test.ts). Les composants (saisie, liste, confirmation, spinner) sont écrits sans bibliothèque tierce, pour ne dépendre que d'ink et de react. Un terminal interactif (TTY) est requis.

Présentation : le titre « MagicCode » est affiché dans un cadre à double bordure (largeur du terminal), centré, en dégradé arc-en-ciel ; les messages d'information sont en bleu clair (LIGHT_BLUE dans packages/ui/src/colors.ts) ; une ligne vide sépare chaque message.

Contexte	Touches
Saisie	Entrée : envoyer · ←/→, Ctrl+A/E : se déplacer · ↑/↓ : historique · Ctrl+U/W : effacer · Ctrl+C ou Ctrl+D (saisie vide) : quitter · le collage multi-lignes est conservé
Liste (`/model`, `/mode`, choix initial)	↑/↓ (ou j/k) · Entrée : valider · Échap : annuler
Confirmation d'une action (Write, Edit, Bash…)	`o` : autoriser · `n` ou Échap : refuser · Entrée seule est ignorée (réponse explicite exigée)
Pendant un tour de l'agent	Ctrl+C : interrompt la requête et restaure la conversation avant cette demande

Dossier de base

Le dossier où MagicCode est lancé (ex. ./X) est la base de tous les chemins relatifs : fichiers lus, créés ou modifiés par les outils (Read, Write, Edit, Glob, Grep, Bash), ./btp_AI.json, .magiccode/config.json, CLAUDE.md et .claude/. Un chemin complet est utilisé tel quel (~/… désigne le dossier personnel). Ce dossier est capturé une fois au démarrage, affiché (« Dossier de travail : … ») et transmis aux outils et aux providers ; les règles de permissions (Read(./.env), Edit(src/**)) sont elles aussi relatives à ce dossier. Seuls ~/.claude et ~/.magiccode (config et extensions utilisateur) sont lus depuis le dossier personnel.

Skills : appel direct avec `§`

Quel que soit le mode chargé, §nom_du_skill [arguments] lance un skill de l'agent (ex. §sk_test) ; § seul liste les skills disponibles. Chaque mode expose ses skills via ModeInitResult.skills (contrat AgentSkill : name, description, invoke(args)), ce qui rend l'appel indépendant du format propre à l'agent. invoke retourne le prompt envoyé au LLM. En mode ClaudeCode, ce prompt contient les instructions du SKILL.md (avec $ARGUMENTS / ARGUMENTS:), sans passer par l'outil Skill du modèle. Les extensions Copilot, opencode, etc. n'ont qu'à renvoyer leurs propres skills sous cette forme.

Provider SAP AI Core / Generative AI Hub

Configuration : ./btp_AI.json (ou $MAGICCODE_BTP_CONFIG), modèle fourni dans btp_AI_tpl.json. Ne jamais versionner ce fichier (il est dans .gitignore).

OAuth client_credentials : GET {url}/oauth/token avec Authorization: Basic {basic} (token mis en cache, renouvelé sur expiration ou HTTP 401).
Découverte : GET {AI_API_URL}/v2/lm/deployments (header AI-Resource-Group, default sauf resourceGroup dans le JSON).
Appel du modèle sur son deploymentUrl selon la famille : Claude → /converse (Bedrock), GPT → /chat/completions (Azure OpenAI). Les autres familles (Gemini, embeddings…) sont ignorées.

Choix du modèle : au démarrage (sauf si --model, MAGICCODE_MODEL ou une config le définit), MagicCode interroge tous les providers (déploiements SAP AI Core, et API Anthropic si ANTHROPIC_API_KEY est définie) et demande de choisir le modèle de la session. /model rouvre cette liste en cours de session (la conversation est conservée). Un provider injoignable donne un avertissement sans bloquer les autres. Spécification explicite : sapaicore:<nom du déploiement>.

Extension ClaudeCode : dossiers `.claude` (lot 2)

Les dossiers .claude sont lus dans cet ordre (le plus spécifique l'emporte) : ~/.claude, puis ceux de la racine jusqu'au dossier courant.

settings.json / settings.local.json : permissions.allow|ask|deny au format Claude Code (Bash(npm run test:*), Edit(src/**), Read(./.env), Write) et env (transmis à Bash). Priorité deny > ask > allow. Pour Bash, une règle allow ne couvre une commande composée (&&, ;, |) que si chaque partie est autorisée, et jamais une commande avec redirection ou substitution (>, $(…), backticks). Les règles deny sont du « meilleur effort » : elles ne remplacent pas un vrai bac à sable.
commands/**/*.md : slash-commandes. $ARGUMENTS, $1…$9 ; en-tête description et argument-hint. Un sous-dossier préfixe le nom (commands/git/commit.md → /git:commit). Les noms help, clear, mode, model, exit sont réservés.
skills/<nom>/SKILL.md : en-tête name et description. Seule la liste est mise dans le prompt ; le contenu est chargé à la demande par l'outil Skill.

Commandes shell `!` dans les prompts et commandes

MagicCode supporte l'exécution de commandes shell directement dans les prompts et les fichiers de commandes markdown via la syntaxe ! :

Simple : !pwd exécute pwd et remplace par sa sortie
Avec espaces : !ls -la pour les commandes avec arguments
Dans les prompts : Analyse le projet : !git status``
Dans les commandes : .claude/commands/status.md peut contenir !git log --oneline -5``

Les commandes respectent les permissions, utilisent le cwd et les variables d'env de settings.json, avec un timeout de 30s et buffer 10MB. Voir SHELL_COMMANDS.md pour plus de détails.

Extension ClaudeCode : outils (lot 1 + lot 3)

Lot 1 (outils de fichiers)

Read : lit un fichier texte avec offset/limit
Write : crée ou écrase un fichier
Edit : modifie un fichier (ancien → nouveau)
Glob : recherche des fichiers par motif
Grep : recherche textuelle avec regex
Bash : exécute une commande shell

Lot 3 (outils avancés)

WebFetch : récupère des URL (GET/POST/etc.), retourne statut + en-têtes + corps
TodoWrite : gère une liste TODO persistante (JSON), avec export markdown
Task : gère une arborescence de tâches avec priorités, assignations et statuts

Voir LOT3.md pour la documentation détaillée.

Reste à faire

Provider SAP AI Core : streaming (actuellement une réponse complète par appel), autres familles (Gemini), validation sur un vrai service
ext-claudecode : lots 1 et 2 terminés (Glob/Grep en JS pur sans ripgrep ; à l'initialisation, ce qui est trouvé et chargé est listé, sinon un avertissement). Lot 3 terminé (WebFetch, TodoWrite, Task). Commande ! implémentée pour l'exécution de shell dans les prompts et commandes markdown. Pas encore gérés dans les commandes : allowed-tools, model, @fichier
ext-claudecode lot 3+ : sous-agents, hooks, MCP
Providers OpenAI et Ollama
Sessions (reprise), compaction du contexte, annulation (AbortSignal) depuis l'UI

9.7 KiB Raw Blame History Unescape Escape