Введение в HCP-диаграммы и MakingHCPChartSkill

Оглавление

1. Что такое HCP-диаграмма
2. Проблема, которую решает этот репозиторий
3. Кратчайший способ понять структуру репозитория
4. 10-минутный практикум (пример НОД)
5. Как читать два примера
6. Что происходит внутри (HCP-диаграмма)
7. Заключение

Когда хочется, чтобы HCP-диаграммы были «диаграммами, которые можно читать как спецификацию», одних рукописных диаграмм становится недостаточно для сопровождения. MakingHCPChartSkill — это репозиторий навыка для интерпретации HCP-DSL (текста) в соответствии со спецификацией и возврата детерминированного SVG.

В этой статье мы начнём с основ HCP-диаграмм и дойдём до реального запуска инструмента.

1. Что такое HCP-диаграмма

HCP-диаграмма — это нотация для иерархического описания обработки. В этом репозитории следующий стиль написания трактуется как обязательное правило.

• слева указывается «чего нужно достичь (цель)»;
• справа (с более глубоким отступом) — «как этого достичь (средства и детали)»;
• на верхнем уровне (уровень 0) размещается метка цели.

Написание текста по этим правилам делает соответствие между замыслом проектирования и деталями реализации легко читаемым.

2. Проблема, которую решает этот репозиторий

Когда диаграммы ведутся только вручную, обычно возникают такие проблемы:

• диаграмма и текст спецификации расходятся;
• ограничения ветвления и иерархии становятся расплывчатыми;
• различия трудно отследить при ревью.

В MakingHCPChartSkill вы передаёте HCP-DSL как JSON-запрос, а hcp_render_svg.py выполняет валидацию и отрисовку. Одинаковый ввод всегда даёт одинаковый вывод, что упрощает встраивание диаграмм в CI и ревью.

3. Кратчайший способ понять структуру репозитория

Целевой репозиторий: https://github.com/gomurin0428/MakingHCPChartSkill

• hcp-chart-svg-v2/SKILL.md Как пользоваться навыком и его ограничения (например, запрет одновременного указания renderAllModules и module).
• hcp-chart-svg-v2/scripts/hcp_render_svg.py Основной скрипт, который валидирует входной JSON, интерпретирует HCP-DSL и возвращает ответ с SVG.
• hcp-chart-svg-v2/references/ Справочник спецификации, примеры запросов/ответов, примеры SVG.
• hcp-chart-svg-v2/scripts/hcp_xml_to_svg.py Устарел. Сейчас используется hcp_render_svg.py.

4. 10-минутный практикум (пример НОД)

4.1. Клонируем репозиторий

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

4.2. Устанавливаем навык в локальный Codex

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

4.3. Генерируем SVG-ответ из примера входных данных

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. Извлекаем SVG из 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. Примечания (ограничения ввода)

• Когда renderAllModules=true, указывать module нельзя.
• Если в diagnostics есть error, svg или svgs будут пустыми.

5. Как читать два примера

5.1. Алгоритм Евклида (НОД)

• Пример входных данных: example-gcd-request.json
• Пример выходных данных: example-gcd-response.json

«Приём входных данных», «повторение» и «возврат результата» разделены по уровням иерархии, что делает цели и средства обработки легко прослеживаемыми.

5.2. Процесс согласования заказа

• Пример входных данных: example-order-approval-request.json
• Пример выходных данных: example-order-approval-response.json

Даже для бизнес-процессов fork и true/false позволяют чётко описать замысел каждого ветвления.

6. Что происходит внутри (HCP-диаграмма)

Записанный на HCP-DSL, поток обработки execute_request выглядит так.

\module main
Принять запрос и проверить предпосылки
    Проверить обязательные поля входного JSON
Разобрать DSL в структуру
    Интерпретировать модули и иерархию
    Собрать diagnostics
Выбрать путь ответа на основе диагностики
    \fork есть ли error
        \true да
            Вернуть пустые полезные данные, связанные с SVG
        \false нет
            Определить модули для рендеринга
            \fork равно ли renderAllModules true
                \true да
                    Сгенерировать SVG для всех модулей
                    Собрать JSON-ответ, содержащий svgs
                \false нет
                    Сгенерировать SVG для одного модуля
                    Собрать JSON-ответ, содержащий svg
Вернуть результат вызывающей стороне

Вот диаграмма, полученная в результате реального рендеринга приведённого выше DSL.

7. Заключение

Сила HCP-диаграмм не только в том, что их удобно читать как диаграммы, — их можно вести в форме, которую можно трактовать как спецификацию. С помощью MakingHCPChartSkill можно валидировать HCP-DSL и генерировать из него SVG в едином последовательном процессе.

В качестве следующего шага попробуйте записать одну из ваших повседневных спецификаций обработки на HCP-DSL и дорабатывать её, наблюдая за diagnostics, — это самый простой способ ощутить пользу от такого подхода.

Источники

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

Похожие статьи

Недавние статьи с теми же тегами помогут подробнее изучить близкие темы.

Связанные темы

Эти страницы показывают тему статьи в более широком контексте услуг и решений.

Услуги по этой теме

Статья напрямую связана со следующими услугами.

Частые вопросы

Вопросы, которые часто возникают при консультациях по теме статьи.

Что такое HCP-диаграмма?

HCP-диаграмма — это нотация для иерархического описания обработки. Слева указывается, чего нужно достичь (цель), справа с более глубоким отступом — как это достичь (средства и детали), а на верхнем уровне размещается метка цели. Написание текста по этим правилам делает соответствие между замыслом проектирования и деталями реализации легко читаемым, поэтому диаграммы можно трактовать как спецификацию.

Какую проблему решает MakingHCPChartSkill?

Когда диаграммы ведутся только вручную, диаграмма и текст спецификации расходятся, ограничения ветвления и иерархии становятся расплывчатыми, а различия при ревью трудно отследить. MakingHCPChartSkill принимает HCP-DSL как JSON-запрос и рендерит его с помощью скрипта, который выполняет валидацию и отрисовку. Одинаковый ввод всегда даёт одинаковый вывод SVG, что упрощает встраивание диаграмм в CI и ревью.

Как сгенерировать SVG из HCP-DSL с помощью MakingHCPChartSkill?

Клонируйте репозиторий MakingHCPChartSkill с GitHub и запустите hcp_render_svg.py, указав входной JSON-запрос и путь для вывода. Скрипт валидирует JSON, интерпретирует HCP-DSL и возвращает JSON-ответ, содержащий SVG, который затем можно извлечь в файл. В репозитории есть примеры запросов, такие как пример НОД (алгоритм Евклида) и рабочий процесс согласования заказа.

Какие есть ограничения на входные данные при рендеринге HCP-диаграмм?

Есть два основных ограничения. Когда renderAllModules установлен в true, нельзя одновременно указывать конкретный module — эти два варианта взаимоисключающие. И если в diagnostics ответа присутствует error, поля svg и svgs будут пустыми, поэтому DSL стоит дорабатывать, наблюдая за выводом diagnostics.

Об авторе

Страница с профилем автора статьи.

Го Комура

Представитель KomuraSoft LLC

Специализируется на разработке программного обеспечения для Windows, техническом консалтинге и расследовании сбоев, особенно в проектах с унаследованными системами и трудно воспроизводимыми ошибками.