CLI-Anything : Construire des logiciels natifs pour agents de zéro à la production

Transformez n'importe quelle base de code en une interface en ligne de commande déterministe, contrôlable par IA, avec une sortie JSON structurée — guide étape par étape pour les ingénieurs

Table des matières

• Ce que nous construisons : Le pipeline CLI natif pour agents
• Prérequis : Outils, versions et configuration de l'environnement
• Phase 1 : Analyse de la base de code et conception de la CLI
• Phase 2 : Implémentation et tests automatisés de la CLI
• Phase 3 : Publication sur CLI-Hub et intégration avec les agents
• Configuration avancée : Performance et déterminisme
• Tests et validation : Garantir la fiabilité des agents
• Gestion des erreurs et débogage : Résilience de niveau production
• Renforcement pour la production : Sécurité, scalabilité et conformité
• Supervision et observabilité : Métriques pour les systèmes d'agents
• Coût et performance : Stratégies d'optimisation
• Prochaines étapes : Extensions et appel à l'action de Hyperion Consulting

Ce que nous construisons : Le pipeline CLI natif pour agents

L'impératif natif pour agents

L'écosystème logiciel moderne fait face à un désalignement architectural fondamental : les applications conçues pour l'interaction humaine via des interfaces graphiques doivent désormais servir des agents autonomes en tant qu'utilisateurs principaux. Cette évolution exige bien plus que de simples wrappers d'API ou des automatisations d'interfaces graphiques fragiles — elle nécessite une refonte complète de la manière dont les logiciels exposent leurs capacités. CLI-Anything répond à ce besoin grâce à un pipeline automatisé en 7 phases qui transforme n'importe quelle base de code en une interface en ligne de commande (CLI) native pour agents, dotée d'une sortie JSON structurée, d'une gestion standardisée des erreurs et d'une gestion d'état adaptée aux workflows.

Au cœur de CLI-Anything se trouvent trois problèmes critiques dans l'interaction entre agents et logiciels :

1. Déterminisme : Les outils d'automatisation d'interfaces graphiques comme Selenium ou PyAutoGUI introduisent des modes de défaillance non déterministes en raison de dépendances temporelles et de la détection d'éléments visuels. Les interfaces générées par CLI-Anything offrent des opérations atomiques et idempotentes avec des résultats prévisibles.

2. Observabilité : Les agents nécessitent des sorties lisibles par machine pour la prise de décision. Alors que la plupart des CLI émettent du texte non structuré, CLI-Anything impose un drapeau --json sur chaque commande, produisant des réponses formatées de manière cohérente avec des codes de statut, des messages d'erreur et des charges utiles de données typées CLI Anything.

3. Découvrabilité : Les agents ne peuvent pas inférer les fonctionnalités à partir d'interfaces visuelles. Le pipeline de documentation automatisé de CLI-Anything génère des schémas OpenAPI, des références en Markdown et des entrées dans le registre CLI-Hub qui permettent la découverte programmatique des capacités.

Le pipeline automatisé en 7 phases

Le pipeline de CLI-Anything fonctionne comme une machine à états déterministe qui traite la base de code d'une application cible à travers sept phases distinctes. Chaque phase produit des artefacts vérifiables qui alimentent les étapes suivantes, avec une couverture de test complète garantissant une fiabilité de bout en bout. Le diagramme Mermaid suivant illustre l'architecture du pipeline et le flux de données :

Phase 1 : Analyser (Couche SENSE)

Le pipeline commence par une analyse statique de la base de code de l'application cible, extrayant à la fois des informations structurelles et comportementales :

1. Analyse de l'arbre syntaxique abstrait (AST) : En utilisant le module ast de Python et les grammaires Tree-sitter, CLI-Anything construit une table de symboles complète des fonctions, classes et structures de données. Pour les applications C/C++ (par exemple, Blender), il exploite LibTooling de Clang pour une génération précise de l'AST GitHub - HKUDS/CLI-Anything.

2. Cartographie des actions GUI : Grâce à une combinaison de :

   • Introspection Qt/Cocoa/GTK (pour les applications de bureau)
   • Analyse DOM basée sur WebDriver (pour les applications Electron)
   • Inspection des API d'accessibilité (macOS AXUIElement, Windows IAccessible) CLI-Anything crée un registre des actions déclenchables par l'utilisateur avec leurs signatures d'entrée/sortie.

3. Graphe de dépendances : Un graphe acyclique dirigé (DAG) des appels de fonctions et des flux de données est construit à l'aide d'une analyse statique du graphe d'appels (via pycg pour Python, CodeViz pour C++).

Mode de défaillance : Des faux positifs dans la détection des actions GUI se produisent lorsque les API d'accessibilité exposent des contrôles non destinés à l'utilisateur. CLI-Anything atténue ce problème grâce à un système de notation de confiance (0-1) basé sur :

• La fréquence des actions dans la télémétrie utilisateur (si disponible)
• La présence dans les menus/barres d'outils de l'application
• La complexité des paramètres d'entrée (les actions destinées à l'utilisateur ont généralement moins de paramètres, plus simples)

Phase 2 : Concevoir (Couche REASON)

La phase de conception traduit les artefacts d'analyse en une spécification CLI :

1. Regroupement des commandes : En utilisant un clustering hiérarchique sur l'AST, les fonctions apparentées sont regroupées en sous-commandes. Par exemple, les opérations sur les calques de GIMP deviennent gimp layer create|delete|merge.

2. Modèle d'état : Une machine à états finis (FSM) est dérivée des structures de données principales de l'application. CLI-Anything la représente sous forme de schéma JSON avec :

   {
     "type": "object",
     "properties": {
       "current_document": {"$ref": "#/definitions/Document"},
       "clipboard": {"$ref": "#/definitions/ClipboardItem"},
       "undo_stack": {"type": "array", "items": {"$ref": "#/definitions/Action"}}
     },
     "required": ["current_document"]
   }
   

   Copy

3. Schémas d'entrée/sortie : Les paramètres et valeurs de retour de chaque commande sont formalisés sous forme de schémas JSON. CLI-Anything impose :

   • Des contraintes de type primitif (par exemple, width: {"type": "integer", "minimum": 1})
   • Des valeurs énumérées pour les options discrètes (par exemple, format: {"enum": ["png", "jpg", "tiff"]})
   • La validation des chemins de fichiers à l'aide de motifs pathlib.Path

Compromis : La phase de conception doit équilibrer exhaustivité et utilisabilité. Des regroupements de commandes trop granulaires (par exemple, des commandes séparées pour chaque filtre de GIMP) créent une surcharge cognitive pour les agents. CLI-Anything utilise une métrique de densité de commandes (commandes par groupe logique) pour diviser ou fusionner automatiquement les groupes lorsque cette métrique dépasse 15.

Phase 3 : Implémenter (Couche COMPUTE)

La phase d'implémentation génère une CLI Click prête pour la production avec les caractéristiques clés suivantes :

1. Interface REPL unifiée : Toutes les CLI générées héritent d'une classe de base AgentCLI qui fournit :

   • L'historique des commandes (via readline)
   • Des indicateurs de progression (spinners pour les opérations longues)
   • Une aide structurée (--help génère à la fois du texte lisible par l'homme et du JSON lisible par machine)
   • La complétion par tabulation pour les sous-commandes et paramètres

2. Contrat de sortie JSON : Chaque commande prend en charge un drapeau --json qui retourne :

   {
     "status": "success|error",
     "code": 200,
     "data": {"layer_id": 42, "name": "background"},
     "warnings": ["paramètre_déprécié: utilisez 'format' au lieu de 'type'"],
     "timestamp": "2026-04-05T14:30:45Z"
   }
   

   Copy

3. Gestion d'état : Les commandes reçoivent et mettent à jour l'état de l'application via un objet de contexte :

   @cli.command()
   @click.pass_context
   def layer_create(ctx, name: str, width: int, height: int):
       """Créer un nouveau calque dans le document courant."""
       state = ctx.obj["state"]
       layer = state["current_document"].create_layer(name, width, height)
       return {"layer_id": layer.id}
   

   Copy

Benchmark : Les mesures de temps de démarrage pour les CLI générées montrent des performances cohérentes entre les applications :

Phases 4-7 : Tester, documenter, publier (Couche ORCHESTRATE)

Les phases restantes garantissent que la CLI générée répond aux normes de production :

1. Planification des tests : Génère un fichier TEST.md avec :

   • Des modèles de tests unitaires pour chaque commande
   • Des scénarios de bout en bout (par exemple, "Créer un document, ajouter trois calques, exporter au format PNG")
   • Des matrices de cas limites (entrées invalides, transitions d'état)

2. Implémentation des tests : Produit une suite pytest avec :

   • 1 073 tests unitaires (testant les commandes individuelles en isolation)
   • 435 tests de bout en bout (validant les workflows multi-commandes)
   • Des tests basés sur les propriétés à l'aide de Hypothesis pour la validation des entrées

3. Documentation : Met à jour TEST.md avec :

   • Des tableaux de référence des commandes
   • Des exemples d'invocations
   • Une spécification OpenAPI 3.1 pour un accès programmatique

4. Publication : Crée :

   • Un setup.py avec les métadonnées PyPI
   • Un Dockerfile pour un déploiement en conteneur
   • Une entrée de registre CLI-Hub (registry.json)

Mode de défaillance : La génération de tests produit occasionnellement des tests flaky lorsque les applications ont un comportement non déterministe (par exemple, les simulations physiques de Blender). CLI-Anything aborde ce problème grâce à :

• Des timeouts pour les opérations longues
• Une logique de réessai avec backoff exponentiel
• Des tests golden master pour les sorties visuelles

CLI-Hub : Le registre central (Couche CONNECT)

CLI-Hub sert de tissu conjonctif dans le Physical AI Stack, permettant aux agents de découvrir, installer et exploiter des CLI natives pour agents via une interface standardisée. L'architecture du registre suit ces principes :

1. Contribution décentralisée : Les développeurs ajoutent de nouvelles CLI en soumettant une pull request avec un fichier registry.json :

   {
     "name": "gimp-cli",
     "version": "2.10.34",
     "description": "CLI native pour agents pour GIMP",
     "install": {
       "pip": "gimp-cli>=2.10.0",
       "npx": "@clianything/gimp@latest"
     },
     "commands": ["layer", "filter", "export"],
     "tags": ["créativité", "édition-d'image"],
     "license": "GPL-3.0"
   }
   

   Copy

2. Validation automatisée : Le pipeline CI de CLI-Hub vérifie la réactivité de la CLI (--help retourne en moins de 500 ms) CLI-Anything/CONTRIBUTING.md.

3. Intégration avec les agents : Les agents interagissent avec CLI-Hub via :

   • Une API REST (/api/v1/search?q=édition+d'image)
   • Une CLI (clihub install gimp-cli)
   • Un SDK Python (from clihub import Registry)

Métriques d'adoption : En mars 2026, CLI-Hub héberge des CLI natives pour agents pour 18 applications dans différents domaines :

Workflow de bout en bout : De la base de code à l'exécution par l'agent

Le diagramme de séquence suivant illustre un workflow complet où un agent IA utilise CLI-Anything pour effectuer une édition d'image dans GIMP :