144 lines
7.7 KiB
Markdown
144 lines
7.7 KiB
Markdown
---
|
||
issueRef: "#282"
|
||
version: 5
|
||
updatedBy: {"kind":"agent","agent_id":"a6c6ea12-bfc6-4bdc-8031-324102dfa34d"}
|
||
updatedAt: 1788875629546
|
||
---
|
||
# Cadrage initial
|
||
|
||
Besoin utilisateur : les plugins IdeA doivent pouvoir apporter des skills et des tools MCP consommables par les agents, avec une configuration par projet. L'utilisateur veut un panneau Settings projet permettant de choisir quels plugins sont utilisés dans ce projet, puis d'attribuer les skills/tools de ces plugins aux agents, comme les skills IdeA et les tools MCP IdeA.
|
||
|
||
# Décision produit proposée
|
||
|
||
Modèle en trois niveaux :
|
||
|
||
1. Plugin installé globalement dans IdeA.
|
||
2. Plugin activé explicitement pour un projet.
|
||
3. Skills/tools du plugin attribués explicitement à un agent du projet.
|
||
|
||
Un plugin installé globalement ne rend pas automatiquement ses capabilities disponibles partout. L'activation projet rend les capabilities visibles/attribuables ; l'attribution agent décide ce que l'agent peut réellement utiliser.
|
||
|
||
# Contrainte multi-harness
|
||
|
||
La feature doit être IdeA-native et fonctionner pour tous les harness/profils supportés par IdeA : Claude Code, Codex, OpenCode local/cloud, et futurs adapters. Elle ne doit pas dépendre d'un mécanisme propre à Codex, ni de `.codex-plugin/plugin.json`, ni d'un dossier `$CODEX_HOME`.
|
||
|
||
Le contrat attendu : IdeA résout les plugins activés pour le projet et les assignments de l'agent, puis projette les capabilities effectives dans la surface adaptée à chaque harness :
|
||
|
||
- Claude Code : convention file / contexte injecté + MCP config selon les mécanismes déjà projetés pour Claude.
|
||
- Codex : AGENTS.md/contexte injecté + config MCP Codex selon les mécanismes déjà projetés pour Codex.
|
||
- OpenCode : contexte/config OpenCode selon les mécanismes déjà projetés pour OpenCode.
|
||
|
||
`idea_skill_read(name)` doit rester une API IdeA, pas une API Codex : elle lit les skills effectivement assignés à l'agent quelle que soit son implémentation de harness, dès lors que ce harness dispose du pont/outillage IdeA correspondant. En mode sans MCP, conserver les stratégies existantes de projection fichier/contexte.
|
||
|
||
# UX recommandé
|
||
|
||
Ajouter `Settings projet > Plugins` :
|
||
|
||
- liste des plugins installés globalement ;
|
||
- toggle `Activé pour ce projet` ;
|
||
- résumé des capabilities : `N skills`, `N tools MCP`, etc. ;
|
||
- détail `Voir les capabilities` avec sections `Skills fournis`, `Tools MCP fournis` ;
|
||
- dans la configuration agent, section `Capabilities de plugins`, groupée par plugin, séparée de `Skills IdeA` et `Tools MCP IdeA`.
|
||
|
||
Libellés à préserver :
|
||
|
||
- `Installé globalement` = existe dans IdeA ;
|
||
- `Activé pour ce projet` = chargé/exposé dans ce projet ;
|
||
- `Attribué à l'agent` = utilisable par cet agent.
|
||
|
||
# Architecture recommandée
|
||
|
||
Étendre `idea-plugin.json` avec `contributes.skills` read-only, package-relative, par exemple :
|
||
|
||
```json
|
||
{
|
||
"capabilities": ["ui", "mcp", "tooling"],
|
||
"contributes": {
|
||
"skills": [
|
||
{
|
||
"id": "unity.build-debug",
|
||
"name": "unity-build-debug",
|
||
"description": "Diagnose Unity build failures.",
|
||
"kind": "workflow",
|
||
"path": "skills/unity-build-debug/SKILL.md"
|
||
}
|
||
],
|
||
"mcpServers": [
|
||
{
|
||
"id": "unity-tools",
|
||
"displayName": "Unity Tools",
|
||
"command": "dist/mcp-server.js",
|
||
"transport": "stdio",
|
||
"autoStart": true
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
Créer un document projet versionné dédié, par exemple `.ideai/project-plugins.json`, séparé du registry global plugin et des agents natifs. Il stocke plugins activés et assignments agent vers `{ source: "plugin", pluginId, skillId/serverId/toolName }`.
|
||
|
||
Au lancement agent : charger agent + settings projet plugins + plugins activés, vérifier état installed/runtime-active/hash, résoudre skills natifs + plugin skills assignés, injecter seulement le manifeste `# Skills disponibles`, et faire en sorte que `idea_skill_read(name)` lise uniquement les skills effectivement assignés à cet agent.
|
||
|
||
Pour MCP tools plugin : garder la policy existante, namespace stable des tools plugin (`{ pluginId, serverId, toolName }`) et refuser l'exécution si non autorisé dans les permissions effectives de l'agent. La projection MCP doit passer par les adapters déjà responsables de chaque harness, pas par une configuration spécifique à Codex.
|
||
|
||
# Contraintes
|
||
|
||
- Hot reload plugin doit relire `contributes.skills` et `contributes.mcpServers`, publier `plugin_reloaded`, recalculer le catalogue projet effectif et marquer les assignments cassés `missing/stale` sans les supprimer.
|
||
- Uninstall global conserve des tombstones projet/agent, pour éviter de perdre une config lors d'un uninstall temporaire.
|
||
- Scope cross-project : un plugin installé est global, mais son usage est project-scoped ; `idea_project_ask_agent` utilise uniquement les assignments du projet cible.
|
||
- Ne pas mélanger avec `.codex-plugin/plugin.json` : cette feature est IdeA-native et multi-harness. Les skills Codex bundlés restent hors contrat tant qu'un pont explicite n'est pas conçu.
|
||
|
||
# Découpage proposé
|
||
|
||
B1 Domaine : contributions skills plugin, settings projet plugins, refs skills/tools plugin, validation.
|
||
B2 Infrastructure : validator manifest, store `.ideai/project-plugins.json`, lecture package-relative des SKILL.md, catalogue tools plugin.
|
||
B3 Application : use cases settings/assignments, resolver skills, `idea_skill_read`, lancement agent, permissions MCP dynamiques avec projection par harness.
|
||
F1 Frontend : Settings projet > Plugins, détail plugin, attribution agent, catalogue permissions groupé.
|
||
QA : validator, store, injection/read-skill sur Claude Code/Codex/OpenCode, permissions MCP par harness, hot reload, uninstall tombstones.
|
||
|
||
# Implémentation livrée
|
||
|
||
Implémentation effectuée sur `feature/282-project-plugin-settings-multi-harness`.
|
||
|
||
Backend/domaine :
|
||
|
||
- `idea-plugin.json` accepte `contributes.skills` avec `id`, `name`, `description`, `kind`, `path` package-relative Markdown.
|
||
- Ajout du store `.ideai/project-plugins.json` version 1 pour activer/désactiver un plugin par projet et stocker les assignments par agent.
|
||
- Ajout des refs plugin skills/tools et use cases projet : list settings, enable/disable plugin, assign/unassign skill, assign/unassign tool.
|
||
- `idea_skill_read` et l’injection du catalogue de skills passent par le resolver IdeA des skills assignés, pas par `.codex-plugin`.
|
||
- Le contrat est multi-harness : projection via les mécanismes IdeA existants pour Claude Code, Codex et OpenCode.
|
||
|
||
Frontend :
|
||
|
||
- Panneau plugins projet avec état installé globalement / activé pour ce projet.
|
||
- Détail des capabilities déclarées par plugin.
|
||
- Attribution des skills et tools MCP de plugin dans la configuration agent.
|
||
|
||
SDK :
|
||
|
||
- `@idea/plugin-sdk` expose et valide `IdeAPluginSkillContribution` / `contributes.skills`.
|
||
- Docs SDK mises à jour : manifeste, séparation skills IdeA-native vs `.codex-plugin` Codex.
|
||
|
||
# Validation QA
|
||
|
||
Verdict QA : VERT.
|
||
|
||
Commandes vertes :
|
||
|
||
```bash
|
||
npm --prefix sdk/IdeaSDK run build
|
||
cargo test -p application
|
||
cargo test -p infrastructure --test project_plugin_settings -- --nocapture
|
||
cargo test -p app-tauri --test dto_plugins -- --nocapture
|
||
npm --prefix frontend test -- ProjectPluginSettings plugin.test --run
|
||
cargo test -p application --test structured_launch_d3 -- --nocapture
|
||
cargo test -p application agent::catalogue::mcp_tests --lib -- --nocapture
|
||
npm --prefix frontend run build
|
||
```
|
||
|
||
Risques résiduels connus :
|
||
|
||
- Pas d’E2E runtime AppImage avec vrais harness Claude/Codex/OpenCode ; validation par contrats/tests existants.
|
||
- Pour les tools MCP de plugin, `toolName` reste saisi librement tant que le catalogue dynamique des tools n’est pas disponible.
|
||
- Le build frontend garde l’avertissement Vite habituel sur chunk > 500 kB. |