Panneaux de leçon pour les développeurs
Cette page s'adresse aux contributeurs qui vérifient un hôte de panneaux, lancent le serveur de développement local ou ajoutent un hôte. Elle consigne aussi la politique des ressources des fichiers de panneau. Pour simplement ouvrir un panneau, lisez Panneaux de leçon dans votre assistant.
Avant de commencer
Compilez le fichier serveur que lancent la sonde et le serveur de développement :
pnpm --filter @studium/lesson-mcp bundle
Cette commande compile les renderers de panneau (@studium/lesson-panel-ui) et écrit apps/lesson-mcp/dist/studium-mcp.cjs. tools/panel-probe.mjs et tools/panel-http-dev.mjs lancent exactement ce chemin, et non le fichier serveur du build VS Code.
Les deux fichiers serveur partent du même point d'entrée, lesson-mcp-entry.ts, et des mêmes renderers : ils servent donc les mêmes panneaux. Pour un assistant, utilisez apps/studium-vscode/dist/lesson-mcp.cjs, comme dans Connecter votre assistant. Le binaire studium-mcp du paquet @studium/lesson-mcp est apps/lesson-mcp/dist/studium-mcp.cjs.
Comment un hôte obtient des panneaux
L'entrée stdio de Codex est node /chemin/absolu/studium-mcp.cjs. Un hôte compatible MCP Apps annonce io.modelcontextprotocol/ui à l'initialisation. C'est alors seulement que le serveur expose deux ressources ui:// et annote les trois outils de panneau et get_workflow_graph. Sans cette annonce, le serveur propose les mêmes 40 outils, sans métadonnée UI et sans ressource.
Vérifier un hôte
Lancez la sonde depuis la racine du dépôt, après la compilation ci-dessus :
STUDIUM_EPHEMERAL=1 node tools/panel-probe.mjs
La sonde lance deux fois le serveur embarqué, une fois sans et une fois avec la prise en charge de MCP Apps. Elle vérifie que le serveur propose 40 outils, que 4 d'entre eux portent des métadonnées UI et que 2 ressources existent quand le client prend en charge MCP Apps, et qu'aucune n'existe sinon. Elle vérifie que la vue ne contient aucune clé de réponse, que chaque ressource HTML reste sous 1,5 Mo et que la surface est panel pour un client qui a négocié MCP Apps, text sinon. Elle charge ensuite l'App embarquée dans un DOM, puis réalise le handshake postMessage et un aller-retour d'action.
Deux options modifient l'exécution :
--http=http://127.0.0.1:3001/mcpteste le serveur HTTP local ci-dessous au lieu d'un processus lancé par la sonde.--dom=/chemin/absolu/panneau.htmlconserve le DOM rendu.
La sonde est un hôte de contrat automatisé. Elle ne remplace pas un essai dans un vrai hôte. Le ext-apps/examples/basic-host externe nécessite ses propres dépendances et son build avant de se connecter au serveur de développement.
Lancer le serveur de développement local
La route du connecteur distant pour claude.ai et Claude Desktop est distincte de l'API HTTP de leçon. Studium n'ouvre aucun endpoint public, tunnel ou connecteur. Pour essayer cette route sur votre machine uniquement, compilez le bundle comme ci-dessus, puis lancez :
node tools/panel-http-dev.mjs
Le serveur écoute sur 127.0.0.1:3001, à l'adresse /mcp. Définissez PANEL_HTTP_PORT pour changer le port. Pour chaque connexion, il lance un serveur embarqué en mémoire seule et lui transmet MCP. Il n'accepte que les hôtes et origines localhost et 127.0.0.1, et ne fournit ni authentification de production ni contrat de déploiement. Arrêtez-le après usage.
Ajouter un hôte
- Écrivez un bridge dans
apps/lesson-panel-ui/srcqui appellerenderViewet transmet lesPanelActionpubliques au serveur. - Gardez les accès disque, la notation et les clés de réponse côté serveur.
- Suivez la langue et le thème de l'hôte, ses états d'attente et d'erreur, et ses règles de liens et de taille.
- Pour prévisualiser un bridge, définissez
window.__studiumViewet envoyez des événementsstudium:viewau bridge standalone.
Politique des ressources
| Élément | Règle |
|---|---|
| Ressources MCP | text/html;profile=mcp-app, prefersBorder: true, un seul domaine de ressources CSP, https://cdn.jsdelivr.net |
| Bibliothèques embarquées | marked, KaTeX JS et mhchem |
| Bibliothèques CDN | CSS et polices KaTeX, Vega, Vega-Lite, Vega-Embed, 3Dmol, Cytoscape et dagre, chargés depuis des URL de la version installée avec intégrité SHA-384 ; les polices suivent le chemin versionné du CSS KaTeX vérifié |
| Une bibliothèque CDN manque | Une représentation de secours lisible la remplace |
| Images distantes d'une leçon | Bloquées ; les images approuvées par le serveur arrivent en URI data: |
| VS Code | Garde sa CSP à nonce et son mode vendor entièrement local |
| Taille | 1,5 Mo par ressource HTML ; le build échoue au-delà |
Les licences sont dans VENDOR-LICENSES.md. Pour les couches autour des panneaux, voyez Architecture.