Einführung in HCP-Charts und MakingHCPChartSkill

Inhaltsverzeichnis

1. Was ist ein HCP-Chart?
2. Welches Problem dieses Repository löst
3. Den Repository-Aufbau in kürzester Zeit erfassen
4. 10 Minuten Hands-on (GCD-Beispiel)
5. Wie die beiden Beispiele zu lesen sind
6. Was im Inneren passiert (HCP-Chart)
7. Zusammenfassung

Wenn Sie HCP-Charts als „Diagramme, die sich wie Spezifikationen lesen lassen“ haben möchten, wird die Pflege allein mit handgezeichneten Diagrammen schwierig. MakingHCPChartSkill ist ein Skill-Repository, das HCP-DSL (Text) gemäß der Spezifikation interpretiert und deterministisches SVG zurückgibt (deterministisch bedeutet hier: Aus derselben Eingabe entsteht immer dasselbe SVG).

In diesem Artikel beginnen wir bei den Grundlagen von HCP-Charts und gehen bis zur tatsächlichen Ausführung durch.

1. Was ist ein HCP-Chart?

Ein HCP-Chart ist eine Notation zur hierarchischen Beschreibung von Verarbeitungsabläufen. In diesem Repository gilt folgende Schreibweise als zwingende Regel.

• Links steht, „was erreicht werden soll (das Ziel)“
• Rechts (tiefer eingerückt) steht, „wie es erreicht wird (Mittel und Details)“
• Auf der obersten Ebene (Ebene 0) steht die Ziel-Bezeichnung

Wenn der Text nach diesen Regeln geschrieben wird, lässt sich der Zusammenhang zwischen Entwurfsabsicht und Implementierungsdetail leicht ablesen.

1.1. Die Herkunft von HCP und die Unterschiede zu anderen Notationen

HCP steht für Hierarchical ComPact description chart und ist eine Notation, die am Yokosuka Electrical Communication Laboratory der Nippon Telegraph and Telephone Public Corporation (heute NTT) entwickelt wurde. Es handelt sich also nicht um einen Begriff, den dieser Artikel oder dieses Repository erfunden hat, sondern um eine Notation, die in Japan schon lange verwendet wird. Zu ihren Merkmalen zählen, dass sich Verarbeitung hierarchisch schreiben lässt, dass sich der Zusammenhang zwischen Daten und Verarbeitung leicht ergänzen lässt, dass sie sich auch freihändig gut zeichnen lässt, und dass die Erläuterungen nicht in Kästen, sondern direkt neben den Symbolen stehen, sodass auf einer Seite viel Inhalt Platz findet.

Stellt man sie neben andere Notationen, wird die Einordnung deutlicher.

Vor diesem Hintergrund ist das, was an dem in diesem Artikel behandelten MakingHCPChartSkill eigentlich repository-spezifisch ist, nicht die Notation selbst, sondern folgende zwei Dinge.

• HCP-DSL, mit der sich HCP-Charts als Text schreiben lassen, sowie ihre Interpretationsspezifikation (references/hcpchartspec.md)
• Die Regel zur Beschreibungsgranularität: „Auf Ebene 0 steht ausschließlich die Ziel-Bezeichnung; codeartige Formulierungen wie Zuweisungen oder Vergleiche werden in Kindknoten verschoben.“ Diese wird vom Repository als zwingende Regel festgelegt und ist keine allgemeine Vorgabe von HCP-Charts

1.2. Wie HCP-DSL geschrieben wird (Syntax-Kurzübersicht)

Der Gesamtüberblick über die Schreibweise lässt sich weitgehend mit der folgenden Tabelle abdecken. Die vollständige Spezifikation steht in references/hcpchartspec.md, die Kernpunkte allein in references/hcp-chart-schema.md.

Zeilenarten

Einrückung (Hierarchie)

Befehle

Das minimale Beispiel sieht wie folgt aus. Man beginnt mit \module, setzt das Ziel links und das Mittel rechts.

\module main
Eingabe entgegennehmen und die Voraussetzung prüfen
    Prüfen, dass der Wert eine positive Ganzzahl ist
\fork Ist die Eingabe gültig?
    \true ja
        Die Hauptverarbeitung ausführen
    \false nein
        Als Fehler an den Aufrufer zurückgeben
        \return
Ergebnis zurückgeben

2. Welches Problem dieses Repository löst

Wenn nur das Diagramm von Hand gepflegt wird, treten typischerweise diese Probleme auf.

• Das Diagramm und der Spezifikationstext driften auseinander
• Die Einschränkungen für Verzweigungen und Hierarchien werden unscharf
• Diff-Reviews werden schwierig

Mit MakingHCPChartSkill übergeben Sie HCP-DSL als JSON-Anfrage, und hcp_render_svg.py führt Validierung und Rendering durch. Dieselbe Eingabe liefert immer dieselbe Ausgabe, wodurch sich die Diagramme leicht in CI und Reviews einbinden lassen.

3. Den Repository-Aufbau in kürzester Zeit erfassen

Ziel-Repository: https://github.com/gomurin0428/MakingHCPChartSkill

• hcp-chart-svg-v2/SKILL.md Nutzung des Skills und seine Einschränkungen (u. a. dass renderAllModules und module nicht gleichzeitig angegeben werden dürfen).
• hcp-chart-svg-v2/scripts/hcp_render_svg.py Der Kern, der die JSON-Eingabe validiert, HCP-DSL interpretiert und die SVG-Antwort zurückgibt.
• hcp-chart-svg-v2/references/ Spezifikationsreferenz, Beispiel-Request/-Response, Beispiel-SVG.
• hcp-chart-svg-v2/scripts/hcp_xml_to_svg.py Deprecated. Aktuell wird hcp_render_svg.py verwendet.

4. 10 Minuten Hands-on (GCD-Beispiel)

Voraussetzungen

4.1. Das Repository beziehen

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

4.2. Den Skill im lokalen Codex einrichten

Mit Codex ist hier der Coding-Agent von OpenAI gemeint. $HOME\.codex (unter Windows C:\Users\<Benutzername>\.codex) ist dessen Konfigurationsverzeichnis, und die README des Repositorys beschreibt, das ganze Verzeichnis darunter nach skills\<Skill-Name> zu kopieren. So eingerichtet, ruft der Agent auf Anfrage „Zeichne einen HCP-Chart“ den Renderer gemäß den Schritten in dieser SKILL.md auf.

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

Dieser Schritt ist nicht zwingend erforderlich. Der Renderer ist ein eigenständiges Skript, das --input und --output entgegennimmt; wer Codex nicht verwendet, kann direkt zu 4.3 übergehen.

4.3. Aus der Beispieleingabe eine SVG-Antwort erzeugen

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. Das SVG aus der Antwort-JSON extrahieren

$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. Hinweise (Eingabebeschränkungen)

• Wenn renderAllModules=true gesetzt ist, kann module nicht angegeben werden.
• Enthält diagnostics einen error, bleiben svg beziehungsweise svgs leer.

5. Wie die beiden Beispiele zu lesen sind

Wenn Sie das Diagramm öffnen, lässt es sich lesen, indem Sie den Blick in dieser Reihenfolge bewegen.

1. Lesen Sie zunächst nur die ganz linke Spalte von oben nach unten. Was hier steht, ist „was erreicht werden soll (das Ziel)“ – das ist die Kurzfassung des gesamten Ablaufs
2. Verfolgen Sie von einer Zeile, die Sie interessiert, den Weg nach rechts. Was in der rechten Einrückung steht, ist, „wie“ dieses Ziel erreicht wird (Mittel und Details)
3. Prüfen Sie mit der senkrechten Linie (dem Stamm) die Eltern-Kind-Beziehung. Der Stamm verbindet Verarbeitungsschritte derselben Tiefe und wird so gezeichnet, dass er keine Zeile mit geringerer Tiefe durchbricht

Die Bedeutung der Symbole ist wie folgt.

5.1. Der euklidische Algorithmus (GCD)

• Beispieleingabe: example-gcd-request.json
• Beispielausgabe: example-gcd-response.json

„Eingabe entgegennehmen“, „Wiederholung“ und „Rückgabe“ sind hierarchisch getrennt, sodass sich Ziel und Mittel der Verarbeitung leicht verfolgen lassen.

Liest man nur die äußerste linke Spalte, ergeben sich drei Zeilen: „Eingabewerte entgegennehmen und die Berechnung vorbereiten → sich, solange ein Rest bleibt, dem größten gemeinsamen Teiler annähern → das Ergebnis an den Aufrufer zurückgeben.“ Allein daraus ergibt sich schon die Kurzfassung des Algorithmus. Eine konkrete Berechnung wie r <- a mod b ist von „den nächsten zu übergebenden Wert bestimmen“ innerhalb der Wiederholung noch eine Einrückungsebene weiter nach rechts verschoben. Genau diese Positionsbeziehung ist der Zusammenhang zwischen „Ziel (links)“ und „Mittel (rechts)“ selbst. Tauchte r <- a mod b plötzlich in der äußersten linken Spalte auf, wäre das ein Signal, dass die Regel zur Beschreibungsgranularität (1.1) verletzt wird.

Auch die Data:-Zeile oben im Diagramm sowie die in:/out:-Anmerkungen unter den Knoten sind Lesehinweise. In diesem Diagramm stehen in: a, b und out: a, sodass sich Ein- und Ausgang allein am Diagramm ablesen lassen.

5.2. Der Auftragsfreigabe-Ablauf

• Beispieleingabe: example-order-approval-request.json
• Beispielausgabe: example-order-approval-response.json

Auch bei Geschäftsabläufen lässt sich mit fork und true/false die Absicht einer Verzweigung eindeutig beschreiben.

Auch hier besteht die äußerste linke Spalte aus nur drei Zeilen: „Auftragsinhalt entgegennehmen → Versandfähigkeit prüfen → Verarbeitungsergebnis zurückgeben.“ Implementierungsnahe Vorgänge wie Bestandsabfrage, Freigabeantrag und Versanderfassung stehen alle in der rechten Einrückung. Verzweigungen erscheinen als Pfeile, die vom Stamm nach rechts abgehen, wobei unter (ja)/(nein) jeweils die zugehörige Verarbeitung hängt. Die Geschäftsentscheidung „bei Fehlbestand zurückweisen, bei erfolgter Freigabe den Versand veranlassen, andernfalls zurückstellen“ lässt sich allein durch das Verfolgen der Pfeile aus den zwei Verzweigungsstellen nachvollziehen.

Beim Review der Fachspezifikation lässt sich diese äußerste linke Spalte gut gemeinsam mit den Fachverantwortlichen durchgehen, während die rechten Details mit der Implementierung abgestimmt werden – eine Arbeitsteilung, die sich so leicht herstellen lässt.

6. Was im Inneren passiert (HCP-Chart)

Der Verarbeitungsablauf von execute_request, in HCP-DSL geschrieben, sieht so aus.

\module main
Die Anfrage entgegennehmen und die Voraussetzungen prüfen
    Die Pflichtfelder der Eingabe-JSON validieren
Die DSL parsen und strukturieren
    Module und Hierarchie interpretieren
    diagnostics sammeln
Den Antwortpfad anhand des Diagnoseergebnisses wählen
    \fork Existiert ein error?
        \true ja
            Leere SVG-bezogene Payloads zurückgeben
        \false nein
            Die zu rendernden Module bestimmen
            \fork Ist renderAllModules true?
                \true ja
                    SVG für alle Module erzeugen
                    Die Antwort-JSON mit svgs zusammenstellen
                \false nein
                    SVG für ein einzelnes Modul erzeugen
                    Die Antwort-JSON mit svg zusammenstellen
Das Ergebnis an den Aufrufer zurückgeben

Das folgende Diagramm entsteht, wenn man die obige DSL tatsächlich rendert.

7. Zusammenfassung

Die Stärke von HCP-Charts liegt nicht nur darin, dass sie als Diagramm gut lesbar sind – sie lassen sich in einer Form verwalten, die als Spezifikation behandelt werden kann. Mit MakingHCPChartSkill können Sie HCP-DSL validieren und daraus durchgängig bis zum SVG generieren.

Als Nächstes bietet es sich an, eine Ihrer alltäglichen Verarbeitungsspezifikationen in HCP-DSL zu schreiben und anhand von diagnostics weiter zu verfeinern – so lässt sich der Nutzen am einfachsten erfahren.

Quellen

• MakingHCPChartSkill
• hcp-chart-svg-v2/SKILL.md
• hcp-chart-svg-v2/scripts/hcp_render_svg.py
• hcp-chart-svg-v2/references/hcpchartspec.md (vollständige Spezifikation der DSL)
• hcp-chart-svg-v2/references/hcp-chart-schema.md (die Kernpunkte der Syntax)
• HCP-Chart – Wikipedia (offizielle Bezeichnung und Herkunft)

Verwandte Artikel

Aktuelle Artikel mit denselben Schlagwörtern führen zu verwandten Themen weiter.

Verwandte Themen

Diese Seiten ordnen den Artikel in einen größeren Leistungs- und Entscheidungskontext ein.

Leistungen zu diesem Thema

Dieser Artikel ist direkt mit den folgenden Leistungen verbunden.

Häufige Fragen

Fragen, die in Beratungen zu diesem Artikelthema häufig gestellt werden.

Was ist ein HCP-Chart?

Ein HCP-Chart ist eine Notation zur hierarchischen Beschreibung von Verarbeitungsabläufen. Auf der linken Seite steht, was erreicht werden soll (das Ziel), auf der rechten Seite, tiefer eingerückt, steht, wie es erreicht wird (Mittel und Details), und auf der obersten Ebene (Ebene 0) steht die Ziel-Bezeichnung. Wenn der Text nach diesen Regeln geschrieben wird, lässt sich der Zusammenhang zwischen Entwurfsabsicht und Implementierungsdetail leicht ablesen.

Was macht das Werkzeug MakingHCPChartSkill?

MakingHCPChartSkill ist ein Skill-Repository, das HCP-DSL (Text) gemäß der Spezifikation interpretiert und deterministisches SVG zurückgibt. Übergibt man HCP-DSL als JSON-Anfrage, führt hcp_render_svg.py Validierung und Rendering durch. Dieselbe Eingabe liefert immer dieselbe Ausgabe, wodurch sich die Diagramme leicht in CI und Reviews einbinden lassen.

Was unterscheidet das von der manuellen Pflege von Diagrammen?

Wenn nur das Diagramm von Hand gepflegt wird, treten typischerweise diese Probleme auf: Das Diagramm und der Spezifikationstext driften auseinander, die Einschränkungen für Verzweigungen und Hierarchien werden unscharf, und Diff-Reviews werden schwierig. Mit einer Methode, die aus dem Text HCP-DSL deterministisch SVG erzeugt, lässt sich das Diagramm in einer Form verwalten, die als Spezifikation behandelt werden kann, und man kann es anhand von diagnostics weiter verfeinern.

Gibt es Einschränkungen bei der Nutzung?

Wenn renderAllModules=true gesetzt ist, kann module nicht gleichzeitig angegeben werden. Enthält diagnostics außerdem einen error, bleiben svg beziehungsweise svgs leer. Das Skript hcp_xml_to_svg.py ist deprecated; aktuell wird hcp_render_svg.py verwendet.

Autorenprofil

Profilseite des Artikelautors.

Go Komura

Geschäftsführer von KomuraSoft LLC

Spezialisiert auf Windows-Softwareentwicklung, technische Beratung und Fehleranalyse, insbesondere bei bestehenden Systemen und schwer reproduzierbaren Störungen.