93 lines
6.7 KiB
Markdown
93 lines
6.7 KiB
Markdown
# 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 **Clack**.
|
|
|
|
## Démarrer
|
|
|
|
```bash
|
|
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` :
|
|
|
|
```bash
|
|
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 Clack (saisies, spinner, confirmations) |
|
|
| `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`).
|
|
|
|
## 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`).
|
|
|
|
1. OAuth client_credentials : `GET {url}/oauth/token` avec `Authorization: Basic {basic}` (token mis en cache, renouvelé sur expiration ou HTTP 401).
|
|
2. Découverte : `GET {AI_API_URL}/v2/lm/deployments` (header `AI-Resource-Group`, `default` sauf `resourceGroup` dans le JSON).
|
|
3. 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`.
|
|
|
|
## 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). Pas encore gérés dans les commandes : `allowed-tools`, `model`, `@fichier`, `!`commande``
|
|
- `ext-claudecode` lot 3 : TodoWrite, WebFetch, sous-agents, hooks, MCP
|
|
- Providers OpenAI et Ollama
|
|
- Sessions (reprise), compaction du contexte, annulation (AbortSignal) depuis l'UI
|