Introduzione agli HCP Chart e a MakingHCPChartSkill

Indice

1. Cos’è un HCP Chart?
2. Il problema che risolve questo repository
3. Comprendere la struttura del repository nel minor tempo possibile
4. Prova pratica in 10 minuti (esempio MCD)
5. Come leggere i due esempi
6. Cosa succede dentro (HCP Chart)
7. Conclusione

Quando vuoi che gli HCP chart siano “diagrammi leggibili come specifiche,” i diagrammi disegnati a mano da soli diventano difficili da mantenere. MakingHCPChartSkill è un repository di skill per interpretare HCP-DSL (testo) secondo la specifica e restituire SVG deterministici.

In questo articolo partiamo dalle basi degli HCP chart fino a eseguire effettivamente lo strumento.

1. Cos’è un HCP Chart?

Un HCP chart è una notazione per descrivere l’elaborazione in modo gerarchico. In questo repository, lo stile di scrittura seguente è trattato come regola obbligatoria.

• A sinistra si indica “cosa raggiungere (l’obiettivo)”
• A destra (con indentazione maggiore) si indica “come raggiungerlo (i mezzi e i dettagli)”
• Il livello più alto (livello 0) porta un’etichetta di obiettivo

Scrivere testo secondo queste regole rende facile leggere la corrispondenza tra intento di design e dettaglio di implementazione.

2. Il problema che risolve questo repository

Quando i diagrammi sono gestiti solo a mano, tendono a verificarsi problemi come questi.

• Il diagramma e il testo della specifica divergono
• I vincoli su diramazioni e gerarchia diventano vaghi
• Le diff review diventano difficili

Con MakingHCPChartSkill, passi HCP-DSL come richiesta JSON e hcp_render_svg.py esegue validazione e rendering. Lo stesso input produce sempre lo stesso output, il che rende facile integrare i diagrammi in CI e revisioni.

3. Comprendere la struttura del repository nel minor tempo possibile

Repository target: https://github.com/gomurin0428/MakingHCPChartSkill

• hcp-chart-svg-v2/SKILL.md Come usare la skill e i suoi vincoli (per esempio, renderAllModules e module non possono essere specificati insieme).
• hcp-chart-svg-v2/scripts/hcp_render_svg.py Lo script principale che valida l’input JSON, interpreta l’HCP-DSL e restituisce la risposta SVG.
• hcp-chart-svg-v2/references/ Riferimento sulla specifica, richiesta/risposta di esempio, SVG di esempio.
• hcp-chart-svg-v2/scripts/hcp_xml_to_svg.py Deprecato. Usa ora hcp_render_svg.py.

4. Prova pratica in 10 minuti (esempio MCD)

4.1. Clona il repository

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

4.2. Installa la skill nel tuo Codex locale

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

4.3. Genera la risposta SVG dall’input di esempio

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. Estrai l’SVG dalla risposta 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. Note (vincoli di input)

• Quando renderAllModules=true, non si può specificare module.
• Se diagnostics contiene un error, svg o svgs saranno vuoti.

5. Come leggere i due esempi

5.1. Algoritmo di Euclide (MCD)

• Input di esempio: example-gcd-request.json
• Output di esempio: example-gcd-response.json

“Ricevere input,” “iterare” e “restituire” sono separati gerarchicamente, rendendo facile seguire gli obiettivi e i mezzi dell’elaborazione.

5.2. Flusso di approvazione ordini

• Input di esempio: example-order-approval-request.json
• Output di esempio: example-order-approval-response.json

Anche per flussi di lavoro aziendali, fork e true/false permettono di descrivere chiaramente l’intento di ciascun ramo.

6. Cosa succede dentro (HCP Chart)

Scritto in HCP-DSL, il flusso di elaborazione di execute_request appare così.

\module main
Receive the request and check the prerequisites
    Validate the required fields of the input JSON
Parse the DSL into a structure
    Interpret the modules and hierarchy
    Collect diagnostics
Choose the response path based on the diagnostics
    \fork does an error exist
        \true yes
            Return empty SVG-related payloads
        \false no
            Determine the modules to render
            \fork is renderAllModules true
                \true yes
                    Generate SVG for all modules
                    Assemble the response JSON containing svgs
                \false no
                    Generate SVG for a single module
                    Assemble the response JSON containing svg
Return the result to the caller

Ecco il diagramma prodotto effettivamente renderizzando l’HCP-DSL sopra.

7. Conclusione

La forza degli HCP chart non è solo che siano facili da leggere come diagrammi — possono essere gestiti in una forma trattabile come specifica. Con MakingHCPChartSkill, puoi validare HCP-DSL e generare SVG in una pipeline coerente.

Come passo successivo, prova a scrivere una delle tue specifiche quotidiane in HCP-DSL e affinala osservando diagnostics — questo è il modo più semplice per percepire il beneficio.

Riferimenti

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

Articoli correlati

Articoli recenti con gli stessi tag per approfondire argomenti vicini.

Argomenti correlati

Queste pagine collocano l’argomento in un contesto più ampio di servizi e decisioni.

Servizi collegati all’argomento

L’articolo è direttamente collegato ai servizi seguenti.

Domande frequenti

Domande che ricorrono nelle consulenze sull’argomento dell’articolo.

Cos'è un HCP chart?

Un HCP chart è una notazione per descrivere l'elaborazione in modo gerarchico. A sinistra si indica cosa raggiungere (l'obiettivo), a destra, con indentazione maggiore, si indica come raggiungerlo (mezzi e dettagli), e il livello più alto porta un'etichetta di obiettivo. Scrivere testo secondo queste regole rende facile leggere la corrispondenza tra intento di design e dettaglio di implementazione, quindi i diagrammi possono essere trattati come specifiche.

Che problema risolve MakingHCPChartSkill?

Quando i diagrammi sono gestiti solo a mano, il diagramma e il testo della specifica tendono a divergere, i vincoli su diramazioni e gerarchia diventano vaghi e le diff review diventano difficili. MakingHCPChartSkill accetta HCP-DSL come richiesta JSON e lo renderizza con uno script che esegue validazione e rendering. Lo stesso input produce sempre lo stesso output SVG, il che rende facile integrare i diagrammi in CI e revisioni.

Come genero un SVG da HCP-DSL con MakingHCPChartSkill?

Clona il repository MakingHCPChartSkill da GitHub ed esegui hcp_render_svg.py con un file JSON di richiesta e un percorso di output. Lo script valida il JSON, interpreta l'HCP-DSL e restituisce una risposta JSON contenente l'SVG, che puoi poi estrarre in un file. Il repository include richieste di esempio come l'algoritmo di Euclide (MCD) e un flusso di approvazione ordini.

Quali sono i vincoli di input per il rendering degli HCP chart?

Ci sono due vincoli principali. Quando renderAllModules è impostato a true, non si può anche specificare un singolo modulo — le due opzioni sono mutualmente esclusive. E se i diagnostics nella risposta contengono un errore, i campi svg e svgs saranno vuoti, quindi conviene affinare il DSL osservando l'output dei diagnostics.

Profilo dell’autore

Pagina di presentazione dell’autore dell’articolo.

Go Komura

Rappresentante di KomuraSoft LLC

Specializzato nello sviluppo di software Windows, nella consulenza tecnica e nell’analisi dei malfunzionamenti, soprattutto nei progetti con sistemi esistenti e guasti difficili da riprodurre.