Communitygithub.com

glyph-ai/glyph

Glyph est un établi pour composer les formes que prend l'intelligence aujourd'hui — et découvrir le langage qu'elle parlera demain.

Qu'est-ce que glyph ?

Cette compétence permet à un agent d'IA de contrôler un serveur Glyph via son interface en ligne de commande (CLI). Elle fournit une cartographie complète de la surface de commande `glyph`, incluant la discipline de portée de workspace qui empêche les conflits entre clients, ainsi que la gestion des codes de sortie et des codes d'erreur pour une automatisation robuste. L'agent peut gérer des workspaces, des sessions interactives, des tâches ponctuelles, des planifications cron, des catalogues d'agents et de compétences, ainsi que des workflows. Elle s'appuie sur des variables d'environnement (`GLYPH_SERVER`, `GLYPH_WORKSPACE`) pour la configuration, et impose des conventions strictes pour la sortie JSON (via `--json`) et la gestion des erreurs (via des codes structurés et des lignes `fix:`), permettant à l'agent de prendre des décisions de manière mécanique en fonction des échecs.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add glyphs-ai/glyph

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Compétence official/cli

Vous êtes une IA contrôlant un serveur glyph via son CLI. Cette compétence est une carte de toute la surface de commande glyph ainsi que des conventions qui ne sont pas évidentes dans --help — principalement la discipline de portée de workspace qui empêche vos commandes d'entrer en conflit avec d'autres clients, et la discipline des codes de sortie / codes d'erreur qui vous permet de réagir mécaniquement aux échecs.

Configuration

glyph injecte ce dont vous avez besoin dans votre environnement lorsqu'il lance votre tâche ou session :

  • GLYPH_SERVER — URL du serveur (le CLI l'utilise automatiquement)
  • GLYPH_WORKSPACE — UUID du workspace (les commandes limitées au workspace l'héritent)

Vérification rapide :

glyph health         # exit 0 ⇒ CLI fonctionne + serveur accessible
glyph workspace current --json | jq   # confirme le workspace résolu

Aperçu de la surface de commande

Chaque commande limitée à un workspace hérite de --server / --workspace-id / --output / --json et suit le tableau des codes de sortie partagé ci-dessous. Les groupes de sous-commandes :

GroupeObjectifRéférence
workspaceCréer / lister / afficher / mettre à jour / supprimer / recharger des workspaces ; afficher l'identifiant courantreferences/commands.md#workspace
sessionGérer les sessions interactives (lister / nouvelle / afficher / supprimer / lancer un terminal)references/commands.md#session
taskLancer des tâches ponctuelles, lister (y compris filtré par --origin), inspecter, suivre l'activité, annuler, supprimerreferences/commands.md#task
scheduleLanceurs de tâches déclenchés par cron (créer / lister / modifier / activer / désactiver / exécuter / prévisualiser / lister les tâches)references/commands.md#schedule
catalogInstaller / synchroniser / activer / désactiver des agents, compétences, MCPreferences/commands.md#catalog
workflowAmorcer un workflow, lire/modifier son DAG en direct (développer, modifier la spécification d'un nœud not_started via update-spec), répondre aux nœuds humains, terminerreferences/commands.md#workflow
runtimeLister les runtimes enregistrés (copilot, etc.)references/commands.md#runtime
Inspection du serveurhealth, config, status, logs — pas de cycle de viereferences/commands.md#server-inspection
Cycle de vie du serveurserve / start / stop / restart — hors de portée pour cette compétence—

Discipline du workspace

Chaque commande limitée à un workspace nécessite un sélecteur explicite. Le CLI lit GLYPH_WORKSPACE depuis votre environnement (déjà défini), donc les commandes fonctionnent telles quelles :

glyph task dispatch --agent writer --brief "..."

Pour agir sur un autre workspace, passez --workspace-id <id> par commande :

glyph task list --workspace-id ws-Y

Le CLI ne consulte aucun état partagé de type "workspace courant" côté serveur — les sélecteurs sont locaux au processus, à l'abri des interférences d'autres clients (autres sessions CLI, onglets du tableau de bord, agents IA sur le même serveur).

Discipline de sortie

  • Pour l'analyse, passez toujours --json. Le format humain/tableau n'est pas un contrat stable — l'ordre des colonnes et les en-têtes changent entre les versions.
  • Pour le streaming d'activité, utilisez jq -c pour conserver un événement par ligne.
  • Chaque forme --json que vous êtes susceptible de consommer est documentée dans references/json-shapes.md. Consultez-le avant d'écrire un filtre jq — la plupart des formes ont des champs optionnels (présents lorsque la ligne sous-jacente est non nulle) sur lesquels vous devez vous baser.

Discipline des erreurs

Les erreurs sur stderr portent toujours un code :

agent "writer" is not ready: prereqs not acknowledged (HTTP 409, EntryNotReadyError)
  agent: acme/writer
  cause: prereqs not acknowledged
  fix:   glyph catalog agent ack-prereqs acme/writer

La ligne fix: est votre prochaine commande, textuellement. Le catalogue complet des code (tous les noms d'erreur + HTTP typique + correction) se trouve dans references/error-codes.md. En particulier :

  • EntryNotReadyError est la ramification la plus courante que vous rencontrerez — il porte une reason structurée décrivant si l'agent nécessite ack-prereqs, est disabled, a missingDeps, ou a blockedDeps (qui récursent). Le tableau des raisons se trouve dans references/error-codes.md#entrynotreadyerror-reasons.

Codes de sortie

codesignificationconduite à tenir
0succèscontinuer
1erreur générique (incl. workspace manquant)lire stderr ; généralement un indicateur/env manquant
2erreur d'utilisation (indicateur requis manquant, sous-commande supprimée)corriger l'invocation ; ne pas réessayer telle quelle
3serveur inaccessibledemander à l'utilisateur de glyph start ou vérifier --server
4le serveur a renvoyé 4xx/5xxlire code dans stderr ; consulter references/error-codes.md

Le code de sortie 2 signifie "la commande elle-même est erronée" — ne la réessayez jamais sans modifier l'invocation. Le code de sortie 4 signifie "le serveur a rejeté ceci" — lisez le champ code, il vous indique la prochaine action.

Pièges

  • Pour attendre une tâche, utilisez glyph task activity <tid> --follow (SSE en temps réel). Interroger task list dans une boucle shell gaspille des cycles et retarde les événements réels.
  • Pour un instantané ponctuel "que s'est-il passé jusqu'à présent ?", omettez --follow — glyph task activity <tid> --json renvoie l'activité courante plus totalItems en un seul appel. --follow bloque jusqu'à la fin de la tâche.
  • Terminez avant de supprimer. Une simple task rm <tid> nécessite que la tâche soit dans un état terminal (succeeded / failed / cancelled) ; si elle est encore en cours d'exécution, faites d'abord glyph task cancel <tid>, puis task rm. N'utilisez --purge que lorsque vous voulez également supprimer le répertoire de travail + l'état d'exécution (le stderr.log post-mortem est perdu). Même distinction pour session rm et workspace rm.
  • Reprenez toujours --follow avec le last seq: affiché. À chaque sortie propre (event: end ou flux fermé) ET à chaque sortie sur erreur en milieu de flux, le CLI imprime last seq: <N> sur stderr — passez --after <N> lors de la prochaine invocation de --follow pour reprendre sans trous ni doublons. Ctrl+C est l'exception (stderr n'est pas vidé) ; dérivez le seq du dernier élément NDJSON de stdout à la place (... | tail -1 | jq .seq). Le manuel complet de reprise se trouve dans references/playbooks.md#monitor-a-long-running-task.
  • Obtenez toujours les identifiants de workspace depuis glyph workspace list --json | jq. Les fragments d'URL du tableau de bord varient entre les versions et ne sont pas un contrat filaire.
  • schedule patch est parcimonieux — seuls les indicateurs que vous passez sont envoyés sur le fil. Pour supprimer un champ, passez --clear-details / --clear-runtime (un --details "" vide est traité comme omis, pas comme une suppression).

Références (lecture obligatoire avant tout travail non trivial)

  • references/commands.md — référence des sous-commandes par groupe (workspace / session / task / schedule / catalog / workflow / runtime / inspection du serveur). Parcourez une fois, conservez comme référence.
  • references/playbooks.md — manuels multi-étapes orientés objectifs (installer et vérifier un agent, lancer et attendre, surveiller une tâche, synchroniser une entrée, nettoyer, intégrer un nouveau workspace, créer un agent local à la volée).
  • references/json-shapes.md — les formes courantes des charges utiles --json avec des listes de champs concrètes et des notes d'optionalité.
  • references/error-codes.md — chaque valeur de code que le serveur émet + la commande glyph correspondante pour la corriger.

Skills associés