diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c8eb217..607696f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,16 +1,16 @@ { - "name": "miam-local", + "name": "a2m-plugins", "owner": { "name": "A2M Systèmes" }, "metadata": { - "description": "Plugins Claude Code pour MIAM (Mon IA Manager)" + "description": "Plugins Claude Code A2M Systèmes" }, "plugins": [ { "name": "miam", "source": "./plugins/miam", - "description": "Délégation de tâches à des modèles locaux gérés par MIAM" + "description": "Plugin Claude Code pour MIAM (Mon IA Manager)" } ] } diff --git a/LICENSE b/LICENSE deleted file mode 100644 index bc64199..0000000 --- a/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -MIT License - -Copyright (c) 2026 A2M Systèmes - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/README.md b/README.md index d0f4bb6..1891fcf 100644 --- a/README.md +++ b/README.md @@ -1,110 +1,141 @@ -# plugin-claude-miam -Plugin Claude Code pour déléguer des tâches à un modèle local géré par MIAM (Mon IA Manager, orchestrateur llama.cpp), via son serveur MCP. +# Plugins Claude Code — A2M Systèmes -## Contenu -- Serveur MCP `miam` (http://127.0.0.1:{port}/mcp, jeton Bearer) : point d'entrée pour la communication avec le serveur MCP de MIAM. -- Subagent `miam:delegue` : agent dédié qui pilote la délégation des tâches vers MIAM. -- Skill `deleguer` : règles, pour l'agent principal, sur quand et comment déléguer une tâche à MIAM. -- Skill `/miam:banc` : banc d'essai des presets de MIAM pour évaluer les performances. +Ce dépôt est le marketplace A2M Systèmes. Actuellement, il contient le plugin `miam`, MIAM est un orchestrateur de LLMs locaux avec un mcp pour opencode et claude code. -## Prérequis -MIAM 2.5.0 ou plus lancé avec son serveur MCP démarré (interrupteur du dashboard, menu « Serveur MCP » du tray, ou `--auto-start-mcp`) ; Python 3.12 pour le banc. +## Sommaire + +- [Plugins Claude Code — A2M Systèmes](#plugins-claude-code--a2m-systèmes) + - [Sommaire](#sommaire) + - [Plugins disponibles](#plugins-disponibles) + - [Installation](#installation) + - [1. Ajouter la marketplace](#1-ajouter-la-marketplace) + - [2. Installer un plugin](#2-installer-un-plugin) + - [Dépôt privé](#dépôt-privé) + - [Mises à jour](#mises-à-jour) + - [Ajouter un plugin au dépôt](#ajouter-un-plugin-au-dépôt) + - [Structure du dépôt](#structure-du-dépôt) + - [Licence](#licence) + +## Plugins disponibles + +| Plugin | Description | Documentation | +| :--- | :--- | :--- | +| `miam` | Délègue des tâches à un modèle local géré par MIAM (Mon IA Manager, orchestrateur llama.cpp), via son serveur MCP. | [plugins/miam/README.md](plugins/miam/README.md) | + +Le plugin `miam` fournit : +- le serveur MCP `miam` (outils `etat`, `presets`, `demarrer`, `deleguer`, `suivre`…) ; +- le subagent `miam:delegue`, qui démarre le bon preset, délègue, vérifie le résultat et rend un compte rendu court ; +- la skill `deleguer` (quand et comment déléguer) et la skill `/miam:banc` (banc d'essai des presets) ; +- un compteur de tokens économisés (notification, ligne d'état, `/miam-economies`), net du pilotage et des + corrections, sans coût en tokens. ## Installation -Depuis le dépôt Git (Gitea), dans Claude Code : + +### 1. Ajouter la marketplace + +Dans VS Code, utilisez la commande `/plugins`, puis l'onglet « Marketplaces ». Collez l'URL suivante et cliquez sur « Add » : + ```text -/plugin marketplace add https://a2msystemes-git.duckdns.org/ange/plugin-claude-miam -/plugin install miam@miam-local +https://a2msystemes-git.duckdns.org/ange/plugin-claude-miam.git ``` -Dépôt privé : Claude Code clone avec les identifiants Git du poste, sans jamais les demander. En SSH -(`git@:/plugin-claude-miam.git`), l'hôte doit être dans `known_hosts` et la clé utilisable sans -saisie de phrase de passe (agent SSH) ; en HTTPS, le gestionnaire d'identifiants de Git. Depuis une copie locale : -`/plugin marketplace add E:\0000WorkTechnique\0002dev\plugin-claude-miam`. -Portée, choisie à l'installation (le terminal et l'extension VS Code partagent les mêmes réglages) : -- **pour toi (user)**, recommandé : le plugin sert dans tous les projets du poste (`~/.claude/settings.json`) ; -- **pour ce dépôt, tous les collaborateurs (project)** : `.claude/settings.json`, versionné ; -- **pour toi, dans ce dépôt seulement (local)** : `.claude/settings.local.json`. +Dans le terminal, la commande équivalente est : -La marketplace, le code du plugin et ses réglages (jeton, port…) sont toujours propres au compte : ajoutés une fois, -quelle que soit la portée. +```text +/plugin marketplace add https://a2msystemes-git.duckdns.org/ange/plugin-claude-miam.git +``` -Mises à jour : `version` de `plugins/miam/.claude-plugin/plugin.json` fige la version installée ; l'augmenter à chaque -publication, puis `/plugin marketplace update miam-local`. +**Attention :** L'URL doit impérativement se terminer par `.git`. Sans cette extension, Claude Code interprète l'adresse comme un fichier `marketplace.json` et échoue avec l'erreur « expected object, received string ». -Puis : à l'activation, Claude Code demande les réglages (voir section suivante) ; le jeton se copie depuis MIAM (« Copier la config Claude Code », la valeur après « Bearer »). +### 2. Installer un plugin -## Réglages +Dans VS Code, allez dans l'onglet « Plugins » et cliquez sur « Install ». -| Réglage | Défaut | Rôle | -| :--- | :--- | :--- | -| jeton | (vide) | Jeton Bearer du serveur MCP de MIAM, rangé dans le coffre d'identifiants. | -| port | 8090 | Port du serveur MCP de MIAM sur 127.0.0.1. | -| modele_subagent | haiku | Modèle Claude qui pilote MIAM pour l'agent principal (rédige la consigne, attend, vérifie). | -| preset_defaut | pre-16312f8b | Preset MIAM par défaut, démarré quand aucun modèle n'est chargé et que le banc n'a pas encore de résultats. | +Dans le terminal, utilisez la commande suivante : -## Utilisation -L'agent principal lance le subagent miam:delegue ; celui-ci vérifie que MIAM répond (etat), démarre si aucun modèle n'est chargé le meilleur preset de la catégorie de la tâche d'après choix.json du banc (sinon le preset par défaut), ne remplace jamais un modèle déjà chargé sans demande, délègue, vérifie, et rend un compte rendu court. +```text +/plugin install miam@a2m-plugins +``` -## Tokens économisés +La portée conseillée est « Install for you » (tous les projets du poste). -Après chaque délégation réussie, une notification (`MIAM : ~6,1k tokens évités (5,2k lus, 900 écrits)`) et une ligne -d'état sous le prompt (`MIAM ▸ 2 délégation(s) · ~6,1k tokens évités · pilotage 1,5k · corrections 600 · net ~4k -(cumul ~35k)`), -dans le terminal comme dans VS Code. `/miam-economies` donne le détail de la session et le cumul ; `/miam-economies raz` -remet les compteurs à zéro. Le calcul se fait localement dans Claude Code : il ne coûte aucun token. -Chaque estimation est aussi envoyée à MIAM (`POST /economies`, toutes les 5 s, hors des hooks ; gardée et renvoyée si -MIAM ne répond pas) : contrat et modèle de données dans [docs/token-summary-mod.md](docs/token-summary-mod.md). +### Dépôt privé -- **Évités** : les fichiers lus et la réponse écrite par le modèle local (chiffres de MIAM), moins la consigne et ce que - Claude relit (estimés à 4 caractères par token). -- **Pilotage** : la consommation réelle du subagent `miam:delegue` (lecture en cache comptée au dixième), à déduire. -- **Corrections** : ce que l'agent principal relit (`Read`) ou retouche (`Edit`, `Write`, `NotebookEdit`, `Bash`) dans - un fichier écrit par une délégation (`sortie`), à déduire aussi. Celles du subagent sont déjà dans le pilotage. -- **Net** = évités − pilotage − corrections. -- **Limites** : le brief de l'agent principal et la lecture du compte rendu ne sont pas comptés ; un token de Haiku coûte - moins qu'un token d'Opus, ce que le net ne pondère pas ; une reprise hors du fichier `sortie` n'est pas vue (d'où - l'intérêt de faire écrire les résultats par MIAM avec `sortie`). +Ce dépôt est privé sur Gitea. Pour le cloner, Claude Code utilise les identifiants Git configurés sur votre poste. +- **HTTPS** : Les identifiants sont gérés par le gestionnaire d'identifiants de Git. +- **SSH** : L'hôte doit être présent dans `known_hosts` et la clé doit être utilisable sans saisie de phrase de passe (agent SSH). -## Banc d'essai -Tâches fixes reprises de llm-banc (catégories code, texte, rapide ; pas de vision), lancé par /miam:banc dans une fenêtre PowerShell externe, résultats rapport.md et choix.json dans le dossier de données du plugin, critère de choix (meilleure note par catégorie ; à moins de 0,02 d'écart, la vitesse en tok/s départage). Le script lit le jeton dans %LOCALAPPDATA%\MIAM\config.json ou la variable MIAM_JETON. +### Mises à jour + +Le champ `version` du fichier `plugin.json` de chaque plugin fige la version installée. Pour mettre à jour : +1. Augmentez la version dans le fichier `plugin.json` du plugin. +2. Poussez les modifications sur Gitea. +3. Exécutez l'une des commandes suivantes : + - Dans VS Code : onglet « Marketplaces » → « Update marketplace ». + - Dans le terminal : `/plugin marketplace update a2m-plugins`. + +## Ajouter un plugin au dépôt + +Pour ajouter un nouveau plugin au catalogue : + +1. Créez un dossier `plugins/` à la racine du dépôt. +2. Ajoutez un fichier `.claude-plugin/plugin.json` avec le nom en kebab-case, la version et la description. +3. Ajoutez les composants nécessaires (dossiers `skills/`, `agents/`, `hooks/`, fichier `.mcp.json`, etc.). +4. Ajoutez un fichier `README.md` et un fichier `LICENSE` (la licence est propre à chaque plugin ; il n'y en a pas à + la racine), et une ligne au tableau de la section [Licence](#licence). +5. Ajoutez une entrée dans la liste `plugins` du catalogue `.claude-plugin/marketplace.json` : + ```json + { + "name": "", + "source": "./plugins/", + "description": "Description courte du plugin" + } + ``` +6. Vérifiez la validité du catalogue et du plugin avec : + ```text + claude plugin validate . + claude plugin validate ./plugins/ + ``` ## Structure du dépôt + ```text .claude-plugin/ - marketplace.json + marketplace.json # Catalogue central des plugins +docs/ + token-summary-mod.md # Contrat technique pour le compteur de tokens plugins/ - miam/ + miam/ # Plugin actuel .claude-plugin/ - plugin.json - .mcp.json + plugin.json # Métadonnées et version du plugin + .mcp.json # Configuration du serveur MCP agents/ - delegue.md + delegue.md # Définition du subagent de délégation hooks/ - hooks.json - register.ts # compteur de tokens économisés (ligne d'état, notifications, /miam-economies) - economies.ts # calcul pur, testé (claude plugin test plugins/miam) - *.test.ts # 35 tests + hooks.json # Liste des hooks + register.ts # Enregistrement des hooks (compteur de tokens) + economies.ts # Calcul des économies de tokens + *.test.ts # Tests unitaires skills/ - deleguer/ + deleguer/ # Skill pour déclencher la délégation SKILL.md - banc/ + banc/ # Skill pour le banc d'essai SKILL.md - banc/ + banc/ # Composants du banc d'essai banc_miam.py mcp_http.py taches.py verifier_controles.py fichiers/ + LICENSE # Licence du plugin (MIT) + README.md # Documentation du plugin +README.md # Ce fichier ``` -## Limites connues -- Si MIAM est fermé puis relancé, Claude Code ne se reconnecte pas seul (/mcp → Reconnect sur plugin:miam:miam). -- deleguer ne transmet que du texte (pas d'image). -- Un `.mcp.json` de projet qui déclare déjà le serveur `miam` (celui de ce dépôt, celui de MIAM) fait doublon avec le - plugin : le retirer une fois le plugin installé. -- Le modèle du subagent réglé par modele_subagent s'applique quand il est lancé via la skill deleguer (sinon : haiku, défaut du fichier de l'agent). - ## Licence -MIT, voir [LICENSE](LICENSE). Les fichiers du banc (`plugins/miam/banc/`) reprennent ceux de llm-banc, du même auteur. +Chaque plugin a sa propre licence, dans son dossier (`plugins//LICENSE`) : elle s'installe avec lui. + +| Plugin | Licence | +| :--- | :--- | +| `miam` | MIT, voir [plugins/miam/LICENSE](plugins/miam/LICENSE) | diff --git a/plugins/miam/.claude-plugin/plugin.json b/plugins/miam/.claude-plugin/plugin.json index 42cdf94..a0b0f68 100644 --- a/plugins/miam/.claude-plugin/plugin.json +++ b/plugins/miam/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "miam", "displayName": "MIAM", - "version": "0.1.0", + "version": "0.3.0", "description": "Délégation de tâches à un modèle local géré par MIAM (Mon IA Manager) : subagent, règles de délégation, banc d'essai des presets", "author": { "name": "Ange-Marie MAURIN" diff --git a/plugins/miam/README.md b/plugins/miam/README.md new file mode 100644 index 0000000..551818b --- /dev/null +++ b/plugins/miam/README.md @@ -0,0 +1,103 @@ +# miam + +[← Tous les plugins](../../README.md) + +Plugin Claude Code pour déléguer des tâches à un modèle local géré par MIAM (Mon IA Manager, orchestrateur llama.cpp), via son serveur MCP. + +## Contenu +- Serveur MCP `miam` (http://127.0.0.1:{port}/mcp, jeton Bearer) : point d'entrée pour la communication avec le serveur MCP de MIAM. +- Subagent `miam:delegue` : agent dédié qui pilote la délégation des tâches vers MIAM. +- Skill `deleguer` : règles, pour l'agent principal, sur quand et comment déléguer une tâche à MIAM. +- Skill `/miam:banc` : banc d'essai des presets de MIAM pour évaluer les performances. + +## Prérequis +MIAM 2.5.0 ou plus lancé avec son serveur MCP démarré (interrupteur du dashboard, menu « Serveur MCP » du tray, ou `--auto-start-mcp`) ; Python 3.12 pour le banc. + +## Installation +Le plugin fait partie de la marketplace `a2m-plugins` (voir le [README du dépôt](../../README.md#installation) pour +l'ajout de la marketplace, les dépôts privés et les mises à jour). + +- **VS Code** : `/plugins` → onglet « Marketplaces » : ajouter + `https://a2msystemes-git.duckdns.org/ange/plugin-claude-miam.git` (avec `.git`), puis onglet « Plugins » → `miam` → + Install. +- **Terminal** : + ```text + /plugin marketplace add https://a2msystemes-git.duckdns.org/ange/plugin-claude-miam.git + /plugin install miam@a2m-plugins + ``` + +Portée conseillée : « Install for you » (tous les projets du poste). Mises à jour : augmenter `version` dans +`.claude-plugin/plugin.json` à chaque publication. + +Puis : à l'activation, Claude Code demande les réglages (voir section suivante) ; le jeton se copie depuis MIAM (« Copier la config Claude Code », la valeur après « Bearer »). + +## Réglages + +| Réglage | Défaut | Rôle | +| :--- | :--- | :--- | +| jeton | (vide) | Jeton Bearer du serveur MCP de MIAM, rangé dans le coffre d'identifiants. | +| port | 8090 | Port du serveur MCP de MIAM sur 127.0.0.1. | +| modele_subagent | haiku | Modèle Claude qui pilote MIAM pour l'agent principal (rédige la consigne, attend, vérifie). | +| preset_defaut | pre-16312f8b | Preset MIAM par défaut, démarré quand aucun modèle n'est chargé et que le banc n'a pas encore de résultats. | + +## Utilisation +L'agent principal lance le subagent miam:delegue ; celui-ci vérifie que MIAM répond (etat), démarre si aucun modèle n'est chargé le meilleur preset de la catégorie de la tâche d'après choix.json du banc (sinon le preset par défaut), ne remplace jamais un modèle déjà chargé sans demande, délègue, vérifie, et rend un compte rendu court. + +## Tokens économisés + +Après chaque délégation réussie, une notification (`MIAM : ~6,1k tokens évités (5,2k lus, 900 écrits)`) et une ligne +d'état sous le prompt (`MIAM ▸ 2 délégation(s) · ~6,1k tokens évités · pilotage 1,5k · corrections 600 · net ~4k +(cumul ~35k)`), +dans le terminal comme dans VS Code. `/miam-economies` donne le détail de la session et le cumul ; `/miam-economies raz` +remet les compteurs à zéro. Le calcul se fait localement dans Claude Code : il ne coûte aucun token. +Chaque estimation est aussi envoyée à MIAM (`POST /economies`, toutes les 5 s, hors des hooks ; gardée et renvoyée si +MIAM ne répond pas) : contrat et modèle de données dans [docs/token-summary-mod.md](../../docs/token-summary-mod.md). + +- **Évités** : les fichiers lus et la réponse écrite par le modèle local (chiffres de MIAM), moins la consigne et ce que + Claude relit (estimés à 4 caractères par token). +- **Pilotage** : la consommation réelle du subagent `miam:delegue` (lecture en cache comptée au dixième), à déduire. +- **Corrections** : ce que l'agent principal relit (`Read`) ou retouche (`Edit`, `Write`, `NotebookEdit`, `Bash`) dans + un fichier écrit par une délégation (`sortie`), à déduire aussi. Celles du subagent sont déjà dans le pilotage. +- **Net** = évités − pilotage − corrections. +- **Limites** : le brief de l'agent principal et la lecture du compte rendu ne sont pas comptés ; un token de Haiku coûte + moins qu'un token d'Opus, ce que le net ne pondère pas ; une reprise hors du fichier `sortie` n'est pas vue (d'où + l'intérêt de faire écrire les résultats par MIAM avec `sortie`). + +## Banc d'essai +Tâches fixes reprises de llm-banc (catégories code, texte, rapide ; pas de vision), lancé par /miam:banc dans une fenêtre PowerShell externe, résultats rapport.md et choix.json dans le dossier de données du plugin, critère de choix (meilleure note par catégorie ; à moins de 0,02 d'écart, la vitesse en tok/s départage). Le script lit le jeton dans %LOCALAPPDATA%\MIAM\config.json ou la variable MIAM_JETON. + +## Structure du plugin +```text +.claude-plugin/ + plugin.json # manifeste : nom, version, réglages (jeton, port, modèle, preset) +.mcp.json # serveur MCP miam (http://127.0.0.1:/mcp) +agents/ + delegue.md # subagent miam:delegue +skills/ + deleguer/SKILL.md # quand et comment déléguer + banc/SKILL.md # /miam:banc +hooks/ + hooks.json + register.ts # compteur de tokens économisés (ligne d'état, notifications, /miam-economies) + economies.ts # calcul pur, testé + *.test.ts # 35 tests : claude plugin test plugins/miam +banc/ + banc_miam.py # banc d'essai des presets via MIAM + mcp_http.py # client MCP minimal + taches.py # tâches et contrôles (repris de llm-banc) + verifier_controles.py + fichiers/ # données fixes du banc +LICENSE +README.md +``` + +## Limites connues +- Si MIAM est fermé puis relancé, Claude Code ne se reconnecte pas seul (/mcp → Reconnect sur plugin:miam:miam). +- deleguer ne transmet que du texte (pas d'image). +- Un `.mcp.json` de projet qui déclare déjà le serveur `miam` (celui de ce dépôt, celui de MIAM) fait doublon avec le + plugin : le retirer une fois le plugin installé. +- Le modèle du subagent réglé par modele_subagent s'applique quand il est lancé via la skill deleguer (sinon : haiku, défaut du fichier de l'agent). + +## Licence + +MIT, voir [LICENSE](LICENSE). Les fichiers du banc (`banc/`) reprennent ceux de llm-banc, du même auteur.