Introduction aux diagrammes HCP et à MakingHCPChartSkill

Sommaire

1. Qu’est-ce qu’un diagramme HCP ?
2. Le problème que ce dépôt résout
3. Comprendre la structure du dépôt en un minimum de temps
4. Un atelier pratique de 10 minutes (exemple PGCD)
5. Comment lire les deux exemples
6. Ce qui se passe à l’intérieur (diagramme HCP)
7. Conclusion

Quand on veut que les diagrammes HCP soient des « diagrammes que l’on peut lire comme une spécification », les diagrammes dessinés à la main seuls deviennent difficiles à maintenir. MakingHCPChartSkill est un dépôt de compétence pour interpréter le HCP-DSL (texte) conformément à la spécification et renvoyer un SVG déterministe.

Dans cet article, nous partons des bases des diagrammes HCP et allons jusqu’à faire fonctionner l’outil concrètement.

1. Qu’est-ce qu’un diagramme HCP ?

Un diagramme HCP est une notation permettant de décrire un traitement de façon hiérarchique. Dans ce dépôt, la façon d’écrire suivante est traitée comme une règle obligatoire.

• Le côté gauche indique « ce qu’il faut atteindre (l’objectif) »
• Le côté droit (à une indentation plus profonde) indique « comment l’atteindre (les moyens et les détails) »
• Le niveau le plus haut (niveau 0) porte l’étiquette de l’objectif

En écrivant le texte selon ces règles, la correspondance entre l’intention de conception et les détails d’implémentation devient plus facile à lire.

2. Le problème que ce dépôt résout

Quand on ne gère les diagrammes qu’à la main, ce genre de problèmes a tendance à survenir.

• Le diagramme et le texte de spécification finissent par diverger
• Les contraintes de branchement et de hiérarchie deviennent floues
• Les revues de différences sont difficiles à mener

Avec MakingHCPChartSkill, vous transmettez le HCP-DSL sous forme de requête JSON, et hcp_render_svg.py effectue la validation et le rendu. Comme la même entrée produit toujours la même sortie, cette structure permet d’intégrer facilement les diagrammes dans la CI ou dans les revues.

3. Comprendre la structure du dépôt en un minimum de temps

Dépôt cible : https://github.com/gomurin0428/MakingHCPChartSkill

• hcp-chart-svg-v2/SKILL.md Comment utiliser la compétence et ses contraintes (par exemple, l’interdiction de spécifier renderAllModules et module en même temps).
• hcp-chart-svg-v2/scripts/hcp_render_svg.py Le script principal qui valide l’entrée JSON, interprète le HCP-DSL et renvoie la réponse SVG.
• hcp-chart-svg-v2/references/ Référence de spécification, exemples de request/response, exemple de SVG.
• hcp-chart-svg-v2/scripts/hcp_xml_to_svg.py Déprécié. On utilise désormais hcp_render_svg.py.

4. Un atelier pratique de 10 minutes (exemple PGCD)

4.1. Cloner le dépôt

git clone https://github.com/gomurin0428/MakingHCPChartSkill.git
cd .\MakingHCPChartSkill

4.2. Installer la compétence dans votre Codex local

Copy-Item -Recurse -Force .\hcp-chart-svg-v2 "$HOME\.codex\skills\hcp-chart-svg-v2"

4.3. Générer la réponse SVG à partir de l’exemple d’entrée

python .\hcp-chart-svg-v2\scripts\hcp_render_svg.py `
  --input .\hcp-chart-svg-v2\references\example-gcd-request.json `
  --output .\hcp-chart-svg-v2\references\example-gcd-response.json `
  --pretty

4.4. Extraire le SVG de la réponse JSON

$r = Get-Content -Raw .\hcp-chart-svg-v2\references\example-gcd-response.json | ConvertFrom-Json
$r.svg | Set-Content -NoNewline -Encoding utf8 .\hcp-chart-svg-v2\references\example-gcd.svg

4.5. Remarque (contraintes d’entrée)

• Quand renderAllModules=true, vous ne pouvez pas spécifier module.
• Si diagnostics contient une error, svg ou svgs sera vide.

5. Comment lire les deux exemples

5.1. L’algorithme d’Euclide (PGCD)

• Exemple d’entrée : example-gcd-request.json
• Exemple de sortie : example-gcd-response.json

« La réception de l’entrée », « la répétition » et « le retour du résultat » sont séparés de façon hiérarchique, ce qui rend les objectifs et les moyens du traitement faciles à suivre.

5.2. Flux d’approbation de commande

• Exemple d’entrée : example-order-approval-request.json
• Exemple de sortie : example-order-approval-response.json

Même pour un flux métier, fork et true/false permettent de décrire clairement l’intention de chaque branchement.

6. Ce qui se passe à l’intérieur (diagramme HCP)

Voici à quoi ressemble le flux de traitement d’execute_request, écrit en HCP-DSL.

\module main
Recevoir la requête et vérifier les prérequis
    Valider les champs obligatoires du JSON d'entrée
Analyser le DSL pour le structurer
    Interpréter les modules et la hiérarchie
    Collecter les diagnostics
Choisir le chemin de réponse selon le résultat du diagnostic
    \fork une erreur existe-t-elle
        \true oui
            Retourner des payloads liés au SVG vides
        \false non
            Déterminer les modules à restituer
            \fork renderAllModules est-il true
                \true oui
                    Générer le SVG de tous les modules
                    Assembler le JSON de réponse contenant svgs
                \false non
                    Générer le SVG d'un seul module
                    Assembler le JSON de réponse contenant svg
Retourner le résultat à l'appelant

Voici le diagramme obtenu en rendant réellement le DSL ci-dessus.

7. Conclusion

La force des diagrammes HCP ne se limite pas à leur lisibilité en tant que diagrammes : ils peuvent être gérés sous une forme que l’on peut traiter comme une spécification. Avec MakingHCPChartSkill, vous pouvez valider le HCP-DSL et générer le SVG qui en découle dans un pipeline cohérent de bout en bout.

Comme prochaine étape, essayez d’écrire l’une de vos spécifications de traitement habituelles en HCP-DSL et de l’affiner en observant les diagnostics : c’est la façon la plus simple de ressentir concrètement les bénéfices de cette approche.

Références

• MakingHCPChartSkill
• hcp-chart-svg-v2/SKILL.md
• hcp-chart-svg-v2/scripts/hcp_render_svg.py

Articles associés

Articles récents partageant les mêmes étiquettes, pour approfondir des sujets proches.

Sujets associés

Ces pages replacent le sujet dans un contexte plus large de services et de décisions.

Services liés à ce sujet

Cet article est directement lié aux services suivants.

Questions fréquentes

Questions souvent posées lors d’une consultation sur le sujet de cet article.

Qu'est-ce qu'un diagramme HCP ?

Il s'agit d'une notation permettant de décrire un traitement de façon hiérarchique. Le côté gauche indique « ce qu'il faut atteindre (l'objectif) », le côté droit, à une indentation plus profonde, indique « comment l'atteindre (les moyens et les détails) », et le niveau le plus haut (niveau 0) porte l'étiquette de l'objectif. En écrivant le texte selon ces règles, la correspondance entre l'intention de conception et les détails d'implémentation devient plus facile à lire.

Que fait l'outil MakingHCPChartSkill ?

C'est un dépôt de compétence qui interprète le HCP-DSL (texte) conformément à la spécification et renvoie un SVG déterministe. En transmettant le HCP-DSL sous forme de requête JSON, hcp_render_svg.py effectue la validation et le rendu. Comme la même entrée produit toujours la même sortie, cette structure permet d'intégrer facilement les diagrammes dans la CI ou dans les revues.

Quelle est la différence avec une gestion manuelle des diagrammes ?

Quand on ne gère les diagrammes qu'à la main, on rencontre souvent ces problèmes : le diagramme et le texte de spécification finissent par diverger, les contraintes de branchement et de hiérarchie deviennent floues, et les revues de différences sont difficiles à mener. Avec une approche qui génère un SVG de façon déterministe à partir d'un texte HCP-DSL, on peut gérer le diagramme sous une forme que l'on peut traiter comme une spécification, et l'affiner en observant les diagnostics.

Y a-t-il des contraintes d'utilisation ?

Quand renderAllModules=true, vous ne pouvez pas spécifier module en même temps. Par ailleurs, si diagnostics contient une error, svg ou svgs sera vide. Côté scripts, hcp_xml_to_svg.py est déprécié ; on utilise désormais hcp_render_svg.py.

Profil de l’auteur

Page de présentation de l’auteur de l’article.

Go Komura

Représentant de KomuraSoft LLC

Spécialisé dans le développement de logiciels Windows, le conseil technique et l’analyse de pannes, notamment pour les systèmes existants et les incidents difficiles à reproduire.