KomuraSoft LLC
Contáctenos
Menú

Introducción a HCP Chart y MakingHCPChartSkill

· Actualizado el: · · HCP, Codex, SVG, Python, Diseño

Índice

  1. Qué es un HCP Chart
  2. El problema que resuelve este repositorio
  3. Cómo entender la estructura del repositorio en el menor tiempo posible
  4. Manos a la obra en 10 minutos (ejemplo de MCD)
  5. Cómo leer los dos ejemplos
  6. Qué ocurre internamente (HCP Chart)
  7. Resumen

Cuando se quiere que un HCP Chart sea «un diagrama que se pueda leer como especificación», gestionarlo solo con diagramas dibujados a mano resulta difícil. MakingHCPChartSkill es un repositorio de skill para interpretar el HCP-DSL (texto) conforme a una especificación y devolver un SVG determinista (es decir, que la misma entrada produzca siempre el mismo SVG).

En este artículo partimos de los fundamentos del HCP Chart y llegamos hasta ponerlo en marcha de verdad.

1. Qué es un HCP Chart

Un HCP Chart es una representación para describir procesos de forma jerárquica. En este repositorio, la siguiente forma de escritura se trata como regla obligatoria.

  • El lado izquierdo indica «qué se quiere lograr (el objetivo)»
  • El lado derecho (con sangría profunda) indica «cómo se logra (los medios/detalles)»
  • En el nivel superior (nivel 0) se escribe la etiqueta del objetivo

Al escribir el texto siguiendo esta regla, la correspondencia entre la intención de diseño y los detalles de implementación resulta más fácil de leer.

1.1. Origen de HCP y diferencias con otras notaciones

HCP son las siglas de Hierarchical ComPact description chart, una notación creada en el Laboratorio de Telecomunicaciones Eléctricas de Yokosuka de la Corporación Pública de Telégrafos y Teléfonos de Japón (actual NTT). Es decir, no es un término acuñado en este artículo ni en este repositorio, sino una notación que se usa en Japón desde hace tiempo. Entre sus características están la posibilidad de escribir procesos de forma jerárquica, la facilidad para añadir la relación entre datos y procesos, la facilidad para dibujarla incluso a mano alzada, y el hecho de que, al colocar las explicaciones junto a los símbolos en lugar de dentro de recuadros, cabe mucho contenido en una sola página.

Al compararla con otras notaciones, su posición se ve con más claridad.

Notación Cómo representa la estructura Diferencia con el HCP Chart
Diagrama de flujo Coloca los procesos en cajas y sigue el flujo con líneas No puede expresar la jerarquía de «qué proceso es detalle de qué otro proceso». Cuando aumentan las bifurcaciones, las líneas tienden a cruzarse
Diagrama NS (diagrama estructurado) Representa la estructura con rectángulos anidados Como las explicaciones se escriben dentro de las cajas, con jerarquías profundas o explicaciones largas suele faltar ancho horizontal
PAD Estructura de árbol que va detallando de izquierda a derecha La orientación «izquierda es el objetivo, derecha es el medio» es una idea cercana a la del HCP. En el HCP los símbolos son sobre todo círculos, y la explicación se añade a la derecha del símbolo

Dicho esto, lo propio de MakingHCPChartSkill, que es lo que trata este artículo, no es la notación en sí, sino estos dos elementos:

  • El HCP-DSL para escribir el HCP Chart como texto, y su especificación de interpretación (references/hcpchartspec.md)
  • La convención de granularidad de descripción: «en el nivel 0 se escribe solo la etiqueta del objetivo, y las descripciones de estilo código, como asignaciones o comparaciones, se bajan a los nodos hijos». Esta es una regla obligatoria definida por el propio repositorio, no una norma general del HCP Chart

1.2. Cómo escribir HCP-DSL (referencia rápida de sintaxis)

La visión general de cómo escribirlo queda cubierta, a grandes rasgos, por la siguiente tabla. La especificación detallada está en references/hcpchartspec.md, y solo los puntos clave están resumidos en references/hcp-chart-schema.md.

Tipos de línea

Forma de la línea Tratamiento
Línea en blanco Se ignora
Línea cuyo inicio (sin contar espacios) es # Se ignora como comentario
Línea cuyo inicio (sin contar espacios) es \ o ¥ Línea de comando. El nombre del comando llega hasta el primer espacio de ancho medio, y lo que sigue son los argumentos
Cualquier otro caso Se dibuja como un nodo de proceso normal (círculo)

Sangría (jerarquía)

Regla Contenido
Unidad de un nivel Un tabulador, o cuatro espacios de ancho medio
Sangría a medias Un incremento como dos espacios se convierte en error
Profundizar de golpe Si se profundiza dos niveles o más respecto a la línea anterior, se produce error. Hay que bajar de un nivel en un nivel

Comandos

Comando Significado Nota
\title / \author / \date / \version Información de cabecera Si se escribe antes de \module, se aplica a todos los módulos; si se escribe después, solo sobrescribe ese módulo
\module <nombre> Inicio de un módulo Obligatorio. Solo puede escribirse en el nivel 0. Un módulo con el mismo nombre produce error
\mod <etiqueta> Llamada a un módulo o función Se dibuja como un círculo doble en el diagrama
\repeat <etiqueta> Repetición El contenido que se repite se escribe un nivel más abajo
\fork <etiqueta> Padre de una bifurcación (distribución) Los destinos de la bifurcación se colocan justo debajo
\true <etiqueta> / \false <etiqueta> Ramas de una bifurcación booleana (verdadero/falso) Solo pueden colocarse justo debajo de \fork (un nivel más profundo). Si no hay un \fork entre los ancestros, produce error
\branch <condición> Rama de una bifurcación múltiple distinta de la booleana Igual que arriba
\return [n] Salida n es un entero opcional
\ec <etiqueta> / \ex <etiqueta> Comprobación de error / salida de error En la versión actual solo afecta al dibujo, no tiene significado de control
\data <nombre> Definición de datos El nombre no puede contener espacios ni . (si los contiene, produce error)
\in <nombre> / \out <nombre> Anotación de datos de entrada/salida Se trata como una anotación del nodo padre, un nivel arriba

El ejemplo mínimo queda así. Basta con empezar con \module, colocar el objetivo a la izquierda y el medio a la derecha.

\module main
Recibir la entrada y verificar los prerequisitos
    Confirmar que el valor es un entero positivo
\fork ¿La entrada es válida?
    \true Sí
        Ejecutar el proceso principal
    \false No
        Devolver un error a quien realizó la llamada
        \return
Devolver el resultado

2. El problema que resuelve este repositorio

Cuando los diagramas se gestionan solo a mano, suelen producirse estos problemas.

  • El diagrama y el texto de la especificación se desalinean
  • Las restricciones de las bifurcaciones y la jerarquía quedan ambiguas
  • Es difícil revisar las diferencias

En MakingHCPChartSkill, el HCP-DSL se pasa como una solicitud JSON, y hcp_render_svg.py se encarga de la validación y del dibujo. Como la misma entrada produce siempre la misma salida, resulta fácil incorporar los diagramas a CI o a revisiones.

3. Cómo entender la estructura del repositorio en el menor tiempo posible

Repositorio de referencia: https://github.com/gomurin0428/MakingHCPChartSkill

  • hcp-chart-svg-v2/SKILL.md Cómo usar la skill y sus restricciones (por ejemplo, la prohibición de especificar renderAllModules y module a la vez).
  • hcp-chart-svg-v2/scripts/hcp_render_svg.py El script principal, que valida la entrada JSON, interpreta el HCP-DSL y devuelve la respuesta SVG.
  • hcp-chart-svg-v2/references/ Referencia de la especificación, ejemplos de request/response y ejemplos de SVG.
  • hcp-chart-svg-v2/scripts/hcp_xml_to_svg.py Obsoleto (deprecated). Actualmente se usa hcp_render_svg.py.

4. Manos a la obra en 10 minutos (ejemplo de MCD)

Entorno previo

Elemento Contenido
Python hcp_render_svg.py se ejecuta con Python 3. El repositorio no indica una versión mínima, pero como usa dataclasses y from __future__ import annotations, funciona a partir de la 3.7
Paquetes adicionales No hacen falta. Se usan argparse / json / logging / math / re / sys / dataclasses / pathlib / typing / xml.sax.saxutils, todos parte de la biblioteca estándar
Shell Los siguientes comandos están escritos suponiendo PowerShell de Windows. Si aparecen caracteres corruptos, indique UTF-8 explícitamente antes de ejecutarlos con $env:PYTHONUTF8 = "1" y chcp 65001
Codex Solo es necesario si se coloca como skill en 4.2. Si no usa Codex, puede saltarse 4.2 (a partir de 4.3 el script funciona por sí solo)

4.1. Obtener el repositorio

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

4.2. Colocar la skill en un Codex local

Aquí, Codex se refiere al agente de codificación de OpenAI. $HOME\.codex (en Windows, C:\Users\<nombre de usuario>\.codex) es su directorio de configuración, y el README del repositorio indica el procedimiento para copiar el directorio completo a skills\<nombre de la skill>, dentro de ese directorio. Haciendo esto, cuando se le pida al agente «dibuja un HCP Chart», este invocará al renderizador siguiendo los pasos de este SKILL.md.

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

Este paso no es obligatorio. El renderizador es un script independiente que recibe --input y --output, así que quienes no usen Codex pueden pasar directamente a 4.3.

4.3. Generar la respuesta SVG a partir de la entrada de ejemplo

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. Extraer el SVG de la respuesta 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. Nota adicional (restricciones de entrada)

  • Cuando renderAllModules=true, no se puede especificar module.
  • Si diagnostics contiene algún error, svg o svgs quedará vacío.

5. Cómo leer los dos ejemplos

Al abrir un diagrama, si se sigue este orden con la vista se puede leer con claridad.

  1. Leer solo la columna más a la izquierda, de arriba hacia abajo. Ahí aparece «qué se quiere lograr (el objetivo)», que forma el resumen de todo el proceso
  2. Desde la línea que le interese, seguir hacia la derecha. Lo que aparece en la sangría de la derecha es «cómo se logra ese objetivo (medios/detalles)»
  3. Confirmar la relación padre-hijo con la línea vertical (el tronco). El tronco conecta procesos de la misma profundidad, y se dibuja de modo que no atraviese líneas de menor profundidad

El significado de los símbolos es el siguiente.

Símbolo Significado
○ (círculo) Proceso normal
Círculo doble Llamada a un módulo o función (\mod)
Círculo con una flecha circular dentro Repetición (\repeat)
Círculo con un triángulo hacia la derecha dentro Padre de una bifurcación (\fork)
Flecha que sale del tronco hacia la derecha Rama de una bifurcación (\branch / \true / \false). La condición se escribe a la derecha de la flecha
Triángulo hacia abajo Salida (\return)
Círculo con una × dentro Comprobación de error (\ec)
Dos círculos pequeños Salida de error (\ex)

5.1. Algoritmo de Euclides (MCD)

  • Entrada de ejemplo: example-gcd-request.json
  • Salida de ejemplo: example-gcd-response.json

HCP Chart del ejemplo de MCD

«Recibir la entrada», «repetir» y «devolver» están separados por jerarquía, lo que facilita seguir el objetivo y los medios del proceso.

Si se lee solo la columna del extremo izquierdo, se obtienen tres líneas: «recibir el valor de entrada y preparar el cálculo → acercarse al máximo común divisor mientras quede resto → devolver el resultado al usuario», y con esto ya se entiende el resumen del algoritmo. Un cálculo concreto como r <- a mod b está bajado a una sangría todavía más a la derecha, dentro de «decidir el valor que se transmite a la siguiente iteración», que está dentro de la repetición. Esta relación de posición es precisamente la correspondencia entre «objetivo (izquierda) y medio (derecha)». Si r <- a mod b apareciera de golpe en el extremo izquierdo, sería una señal de que se está incumpliendo la convención de granularidad de descripción (1.1).

La línea Data: de la parte superior del diagrama, y las anotaciones in: / out: que acompañan a los nodos, también son pistas para la lectura. En este diagrama aparecen in: a, b y out: a, de modo que se puede saber dónde está la entrada y dónde la salida solo con mirar el diagrama.

5.2. Flujo de aprobación de pedidos

  • Entrada de ejemplo: example-order-approval-request.json
  • Salida de ejemplo: example-order-approval-response.json

HCP Chart del ejemplo de aprobación de pedidos

También en un flujo de negocio se puede describir con claridad la intención de una bifurcación usando fork y true/false.

En este caso, la columna del extremo izquierdo también tiene solo tres líneas: «recibir el contenido del pedido → determinar si es posible enviarlo → devolver el resultado del proceso». Las operaciones más cercanas a la implementación, como la consulta de inventario, la solicitud de aprobación o el registro del envío, están todas en la sangría de la derecha. La bifurcación se representa con una flecha que sale del tronco hacia la derecha, con los procesos correspondientes colgando debajo de (Sí) / (No). La decisión de negocio «si falta stock se devuelve, si está aprobado se organiza el envío, y en cualquier otro caso queda en espera» se puede seguir solo trazando las flechas que salen de las dos bifurcaciones.

En la revisión de la especificación de negocio, esto facilita repartir el trabajo: revisar esta columna del extremo izquierdo con las partes interesadas, y dejar los detalles del lado derecho para afinarlos con el equipo de implementación.

6. Qué ocurre internamente (HCP Chart)

El flujo de proceso de execute_request, escrito en HCP-DSL, queda así.

\module main
Recibir la solicitud y verificar los prerequisitos
    Validar los campos obligatorios del JSON de entrada
Analizar el DSL y estructurarlo
    Interpretar los módulos y la jerarquía
    Recopilar diagnostics
Elegir la ruta de respuesta según el resultado del diagnóstico
    \fork ¿Existe algún error?
        \true Sí
            Devolver una carga útil de tipo SVG vacía
        \false No
            Determinar el módulo objetivo del dibujo
            \fork ¿renderAllModules es true?
                \true Sí
                    Generar el SVG de todos los módulos
                    Componer el JSON de respuesta con svgs
                \false No
                    Generar el SVG de un único módulo
                    Componer el JSON de respuesta con svg
Devolver el resultado a quien realizó la llamada

Arriba se muestra el diagrama que resulta de renderizar realmente ese DSL.

HCP Chart del flujo de proceso interno de MakingHCPChartSkill

7. Resumen

El HCP Chart tiene la ventaja de que no solo es fácil de ver como diagrama, sino que también se puede gestionar en una forma tratable como especificación. Con MakingHCPChartSkill es posible validar el HCP-DSL y generar el SVG de forma coherente, en un solo flujo.

Si quiere probarlo a continuación, le recomendamos escribir en HCP-DSL una especificación de proceso que use habitualmente e ir dando forma al resultado observando diagnostics; así resulta más fácil notar el efecto de introducir esta herramienta.

Referencias

Artículos relacionados

Artículos recientes con las mismas etiquetas para profundizar en temas cercanos.

Temas relacionados

Estas páginas sitúan el tema en un contexto más amplio de servicios y decisiones.

Servicios relacionados con este tema

El artículo está directamente relacionado con los siguientes servicios.

Preguntas frecuentes

Preguntas habituales en las consultas sobre el tema del artículo.

¿Qué es un HCP Chart?
Es una representación para describir procesos de forma jerárquica. En el lado izquierdo se escribe «qué se quiere lograr (el objetivo)», y en la sangría profunda de la derecha, «cómo se logra (los medios/detalles)»; en el nivel superior (nivel 0) se escribe la etiqueta del objetivo. Al escribir el texto siguiendo esta regla, la correspondencia entre la intención de diseño y los detalles de implementación resulta más fácil de leer.
¿Qué hace la herramienta MakingHCPChartSkill?
Es un repositorio de skill que interpreta el HCP-DSL (texto) conforme a una especificación y devuelve un SVG determinista. Al pasar el HCP-DSL como una solicitud JSON, hcp_render_svg.py se encarga de la validación y del dibujo. Como la misma entrada produce siempre la misma salida, resulta una estructura fácil de incorporar a CI o a revisiones.
¿Qué diferencia hay respecto a gestionar los diagramas a mano?
Cuando los diagramas se gestionan solo a mano, suelen producirse problemas como que el diagrama y el texto de la especificación se desalineen, que las restricciones de las bifurcaciones y la jerarquía queden ambiguas, o que sea difícil revisar las diferencias. Con un método que genera el SVG de forma determinista a partir de un texto llamado HCP-DSL, se puede gestionar el diagrama como si fuera una especificación, y se puede ir dando forma al resultado observando los diagnostics.
¿Hay alguna restricción a la hora de usarlo?
Cuando renderAllModules=true, no se puede especificar module al mismo tiempo. Además, si diagnostics contiene algún error, svg o svgs quedará vacío. En cuanto a los scripts, hcp_xml_to_svg.py está marcado como deprecated, y actualmente se usa hcp_render_svg.py.

Perfil del autor

Página de presentación del autor del artículo.

Go Komura

Representante de KomuraSoft LLC

Especializado en desarrollo de software para Windows, consultoría técnica e investigación de fallos, sobre todo en proyectos con sistemas existentes y errores difíciles de reproducir.

Contactar
Volver al blog