HCP-диаграмма и MakingHCPChartSkill: с чего начать

Оглавление

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

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

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

Карта знаний этой статьи

HCP-диаграмма — иерархическая нотация, предложенная в Yokosuka Electrical Communication Laboratory при Nippon Telegraph and Telephone Public Corporation. MakingHCPChartSkill даёт HCP-DSL, чтобы записывать её текстом, и Python-скрипт hcp_render_svg.py, который проверяет DSL и рисует SVG. hcp_render_svg.py — преемник старого скрипта hcp_xml_to_svg.py, помеченного как deprecated; он работает на Python 3 только со стандартной библиотекой, и renderAllModules нельзя указывать вместе с module. В HCP-DSL действует обязательное соглашение о гранулярности: на верхнем уровне пишут только метку цели. Агент для написания кода вроде OpenAI Codex может вызвать этот skill, если положить его в каталог skills под домашним каталогом.

flowchart LR
    accTitle: Карта знаний HCP-диаграммы и MakingHCPChartSkill
    accDescr: Схема связей нотации HCP-диаграммы с HCP-DSL и соглашением о гранулярности описания, которые её реализуют; того, что MakingHCPChartSkill преобразует HCP-DSL в SVG через hcp_render_svg.py и заменил старый скрипт hcp_xml_to_svg.py; способа вызова из Codex; взаимного исключения renderAllModules и параметра module
    hcp_chart["HCP-диаграмма"]
    making_hcp_chart_skill["MakingHCPChartSkill"]
    hcp_dsl["HCP-DSL"]
    hcp_render_svg["hcp_render_svg.py"]
    hcp_xml_to_svg["hcp_xml_to_svg.py"]
    description_granularity_convention["соглашение о гранулярности описания"]
    codex["Codex"]
    render_all_modules_option["renderAllModules"]
    module_parameter["параметр module"]
    python["Python"]
    diagnostics_output["diagnostics (результат проверки)"]
    hcp_dsl -->|"реализует"| hcp_chart
    hcp_render_svg -->|"реализует"| hcp_chart
    making_hcp_chart_skill -->|"использует"| hcp_dsl
    making_hcp_chart_skill -->|"использует"| hcp_render_svg
    hcp_render_svg -->|"реализует"| hcp_dsl
    hcp_render_svg -->|"преемник"| hcp_xml_to_svg
    hcp_dsl -->|"требует"| description_granularity_convention
    making_hcp_chart_skill -->|"требует"| description_granularity_convention
    codex -.->|"использует"| making_hcp_chart_skill
    render_all_modules_option -->|"несовместимо с"| module_parameter
    hcp_render_svg -->|"использует"| render_all_modules_option
    hcp_render_svg -->|"использует"| module_parameter
    hcp_render_svg -->|"требует"| python
    hcp_render_svg -->|"реализует"| diagnostics_output

На схеме сплошная линия обозначает отношение, которое выполняется всегда, а пунктирная — условное отношение (условия указаны в пояснении к каждому отношению на странице сведений). Полный список отношений (всего 14, с доказательствами и степенью уверенности) и определения основных понятий собраны на странице сведений карты знаний (на японском). Данные: JSON-LD / Turtle

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

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

• слева — «чего нужно достичь (цель)»
• справа (более глубокий отступ) — «как этого достичь (средства и детали)»
• на верхнем уровне (уровень 0) пишут метку цели

Если писать текст по этим правилам, проще увидеть, как замысел проекта соотносится с деталями реализации.

flowchart TB
    accTitle: Базовые правила записи HCP-диаграммы
    accDescr: На верхнем уровне 0 пишут только метку цели; слева — цель (чего достичь), справа с более глубоким отступом — средства (как достичь), чтобы было видно соответствие замысла проекта и деталей реализации.
    l0["Уровень 0 — только метка цели"] --> goal["Слева — цель (чего достичь)"]
    goal --> means["Справа — средства (как достичь)"]
    means -.-> effect["Соответствие замысла и реализации читается"]

Рис. 1: HCP-диаграмма описывает обработку иерархически: слева цель, справа отступ — средства.

1.1. Откуда взялась HCP и чем она отличается от других нотаций

HCP — это Hierarchical ComPact description chart. Нотацию разработали в лаборатории электросвязи Йокосука при государственной корпорации Nippon Telegraph and Telephone (ныне NTT). То есть это не термин, придуманный для этой статьи или репозитория, а запись, которой в Японии пользовались и раньше. Среди особенностей: обработку можно записывать иерархически; рядом удобно указывать связь данных и обработки; диаграмму легко набросать от руки; пояснения ставят не внутрь рамок, а рядом с символами, поэтому на один лист помещается больше содержания.

Если поставить HCP рядом с другими нотациями, место становится понятнее.

При этом специфично для MakingHCPChartSkill в этой статье не сама нотация, а следующие две вещи.

• HCP-DSL — текстовая запись HCP-диаграммы — и спецификация её разбора (references/hcpchartspec.md)
• соглашение об уровне детализации: «на уровне 0 пишут только метку цели, а записи в стиле кода вроде присваивания или сравнения опускают в дочерние узлы». Это обязательное правило репозитория, а не общее правило HCP-диаграмм

flowchart TB
    accTitle: Разделение общей нотации и части, специфичной для репозитория
    accDescr: Сама HCP-диаграмма — существующая нотация, созданная в лаборатории электросвязи Йокосука; специфичны для этого репозитория только две вещи: HCP-DSL со спецификацией разбора и соглашение об уровне детализации.
    general["HCP-диаграмма (существующая нотация)"] --> repo["Часть, специфичная для MakingHCPChartSkill"]
    repo --> dsl["HCP-DSL и спецификация разбора"]
    repo --> conv["Соглашение об уровне детализации"]
    conv -.-> rule["Уровень 0 — только метка цели"]

Рис. 2: Сама нотация существовала и раньше; специфичны для этого репозитория только HCP-DSL и соглашение об уровне детализации.

1.2. Как писать HCP-DSL (краткая таблица синтаксиса)

Общей картины из следующей таблицы обычно достаточно. Полная спецификация — в references/hcpchartspec.md, только суть синтаксиса — в references/hcp-chart-schema.md.

Типы строк

Отступы (иерархия)

Команды

Минимальный пример выглядит так. Начинаете с \module, цель ставите слева, средства — справа.

\module main
Принять ввод и проверить предусловия
    Убедиться, что значение — положительное целое
\fork Ввод допустим?
    \true да
        Выполнить основную обработку
    \false нет
        Вернуть ошибку вызывающей стороне
        \return
Вернуть результат

flowchart TB
    accTitle: Поток обработки, который описывает минимальный пример DSL
    accDescr: Начиная с module, проверяют предусловия ввода, ветвят fork по допустимости ввода, при допустимом вводе выполняют основную обработку и возвращают результат, при недопустимом — возвращают ошибку вызывающей стороне.
    m["Начало module main"] --> pre["Принять ввод и проверить предусловия"]
    pre --> fork{"Ввод допустим?"}
    fork -->|"да"| main["Выполнить основную обработку"]
    fork -->|"нет"| err["Вернуть ошибку (return)"]
    main --> ret["Вернуть результат"]

Рис. 3: Поток минимального примера. Начинаете с module, цель ставите слева, непосредственно под fork располагаете ветви true и false.

2. Какую задачу решает этот репозиторий

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

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

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

flowchart TB
    accTitle: Проблемы рисунков от руки и решение через ведение текстом
    accDescr: Если диаграмму ведут только вручную, она расходится с текстом спецификации и ревью по diff затрудняется; если передать HCP-DSL как JSON-запрос, hcp_render_svg.py проверяет его и рисует диаграмму, и из одного ввода получается один и тот же SVG.
    hand["Диаграммы ведут только вручную"] -.-> issue["Расхождение, размытость, трудное ревью по diff"]
    dsl["HCP-DSL передают JSON-запросом"] --> render["hcp_render_svg.py проверяет и рисует"]
    render --> svg["Возвращается детерминированный SVG"]
    svg --> ci["Можно встроить в CI и ревью"]

Рис. 4: Вместо рисунка от руки SVG детерминированно собирается из текстового HCP-DSL, поэтому диаграмму можно отдавать на ревью по diff и в CI.

3. Структура репозитория за минуту

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

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

flowchart TB
    accTitle: Основные файлы репозитория
    accDescr: В hcp-chart-svg-v2 лежат SKILL.md с правилами использования и ограничениями, основной скрипт hcp_render_svg.py и каталог references со спецификацией и примерами; старый скрипт hcp_xml_to_svg.py помечен как deprecated.
    root["hcp-chart-svg-v2"] --> skill["SKILL.md (использование и ограничения)"]
    root --> script["hcp_render_svg.py в scripts"]
    root --> refs["references (спецификация и примеры)"]
    script -.-> old["hcp_xml_to_svg.py помечен как deprecated"]

Рис. 5: Вход — SKILL.md, основа — hcp_render_svg.py, спецификация и примеры собраны в references.

4. Практика за 10 минут (пример НОД)

Требования к среде

4.1. Получить репозиторий

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

4.2. Разместить skill в локальном Codex

Codex здесь — агент OpenAI для написания кода. Каталог настроек — $HOME\.codex (в Windows это C:\Users\<имя пользователя>\.codex). README репозитория предлагает скопировать туда целиком каталог skills\<имя skill>. Тогда по просьбе «нарисуй HCP-диаграмму» агент вызовет отрисовщик по шагам из этого SKILL.md.

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

Этот шаг не обязателен. Отрисовщик — самостоятельный скрипт с --input и --output; если Codex вы не используете, переходите к 4.3.

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

flowchart TB
    accTitle: Путь практики до получения SVG
    accDescr: Пример JSON-запроса передают в hcp_render_svg.py, получают JSON-ответ и извлекают свойство svg в файл SVG.
    req["Пример JSON-запроса"] --> py["Запуск hcp_render_svg.py"]
    py --> res["Выводится JSON-ответ"]
    res --> ext["Извлекают свойство svg"]
    ext --> file["Сохраняют как файл SVG"]

Рис. 6: Ход практики. JSON-запрос передают скрипту, свойство svg из ответа записывают в файл.

4.5. Дополнение (ограничения ввода)

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

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

Когда открываете диаграмму, читайте в таком порядке.

1. Сначала только самый левый столбец сверху вниз. Здесь стоит «чего нужно достичь (цель)» — это краткая картина обработки в целом.
2. От заинтересовавшей строки идите вправо. На правом отступе — «как этого достичь (средства и детали)» для этой цели.
3. По вертикальной линии (стволу) проверьте родителя и потомков. Ствол соединяет обработку одной глубины и рисуется так, чтобы не проходить сквозь более мелкие строки.

flowchart TB
    accTitle: Как двигать взгляд, читая HCP-диаграмму
    accDescr: Сначала читают левый столбец сверху вниз и схватывают общую картину обработки, затем от заинтересовавшей строки идут вправо к средствам и деталям и по вертикальному стволу проверяют отношение родителя и потомков.
    s1["Читать левый столбец сверху вниз"] --> a1["Увидеть общую картину обработки"]
    a1 --> s2["От заинтересовавшей строки идти вправо"]
    s2 --> a2["Проверить средства и детали"]
    a2 --> s3["По вертикальному стволу проверить родителя и потомков"]

Рис. 7: Сначала левый столбец целей даёт общую картину, затем только нужные строки спускаются вправо к средствам — это основной способ чтения.

Смысл символов такой.

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

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

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

Если читать только левый столбец, получаются три строки: «принять входные значения и подготовить расчёт → приближаться к НОД, пока остаётся остаток → вернуть результат пользователю». Этого уже достаточно, чтобы увидеть ход алгоритма. Конкретные вычисления вроде r <- a mod b опущены ещё правее, внутрь повтора, под «определить значения, которые пойдут дальше». Это расположение и есть соответствие «цель слева, средства справа». Если в левом столбце сразу появляется r <- a mod b, это сигнал, что нарушено соглашение об уровне детализации (раздел 1.1).

flowchart TB
    accTitle: Общая картина, которую показывает левый столбец примера НОД
    accDescr: Левый столбец примера НОД состоит из трёх строк: принять входные значения и подготовить расчёт, приближаться к НОД пока остаётся остаток, вернуть результат пользователю; конкретные вычисления опущены ещё правее.
    g1["Принять входные значения и подготовиться"] --> g2["Приближаться, пока остаётся остаток"]
    g2 --> g3["Вернуть результат пользователю"]
    g2 -.-> d1["Конкретные вычисления ещё правее"]

Рис. 8: Левый столбец примера НОД. Трёх строк достаточно, чтобы увидеть ход алгоритма; детали расчёта уходят вправо.

Строка Data: в верхней части диаграммы и пометки in: / out: под узлами тоже помогают читать. На этой диаграмме стоят in: a, b и out: a, поэтому вход и выход видны по самой картинке.

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

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

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

Здесь левый столбец тоже из трёх строк: «принять содержимое заказа → решить, можно ли отгружать → вернуть результат обработки». Операции ближе к реализации — запрос остатков, заявка на согласование, регистрация отгрузки — все уходят на правый отступ. Ветвления — это стрелки вправо от ствола; под (да) / (нет) висит соответствующая обработка. Деловое решение «если нет на складе — вернуть на доработку, если согласовано — оформить отгрузку, иначе — отложить» прослеживается, просто идя по стрелкам из двух ветвлений.

flowchart TB
    accTitle: Ветвления делового решения в примере согласования заказа
    accDescr: Принимают содержимое заказа и решают, можно ли отгружать; деловое решение — вернуть на доработку при отсутствии на складе, оформить отгрузку если согласовано, иначе отложить — выражено двумя ветвлениями.
    o1["Принять содержимое заказа"] --> o2["Решить, можно ли отгружать"]
    o2 --> f1{"Нет на складе?"}
    f1 -->|"да"| back["Вернуть на доработку"]
    f1 -->|"нет"| f2{"Согласовано?"}
    f2 -->|"да"| ship["Оформить отгрузку"]
    f2 -->|"нет"| hold["Отложить"]

Рис. 9: Деловое решение в примере согласования заказа. По двум ветвлениям сразу видно, куда ведут возврат на доработку, оформление отгрузки и отложение.

На ревью бизнес-спецификации удобно разделить работу: левый столбец читать вместе с заинтересованными сторонами, правые детали уточнять с теми, кто реализует.

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

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

\module main
Принять запрос и проверить предусловия
    Проверить обязательные поля входного JSON
Разобрать DSL и привести к структуре
    Интерпретировать модули и иерархию
    Собрать diagnostics
Выбрать путь ответа по результату диагностики
    \fork есть ли error
        \true да
            Вернуть пустой SVG-payload
        \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-chart-svg-v2/references/hcpchartspec.md (полная спецификация DSL)
• hcp-chart-svg-v2/references/hcp-chart-schema.md (суть синтаксиса)
• HCP-диаграмма — Wikipedia (официальное название и происхождение)

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

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

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

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

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

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

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

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

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

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

Что делает инструмент MakingHCPChartSkill?

Это репозиторий skill: он разбирает HCP-DSL (текст) по спецификации и возвращает детерминированный SVG. Если передать HCP-DSL как JSON-запрос, hcp_render_svg.py проверяет его и рисует диаграмму. Один и тот же ввод всегда даёт один и тот же вывод, поэтому диаграммы удобно встраивать в CI и ревью.

Чем это отличается от ведения диаграмм вручную?

Когда диаграмму правят только руками, она обычно расходится с текстом спецификации, ограничения ветвлений и иерархии становятся размытыми, а ревью по diff затрудняется. Если SVG детерминированно собирается из текстового HCP-DSL, диаграмму можно хранить как спецификацию и править её, глядя на diagnostics.

Есть ли ограничения при использовании?

Если renderAllModules=true, параметр module одновременно указать нельзя. Если в diagnostics есть error, поля svg или svgs будут пустыми. Скрипт hcp_xml_to_svg.py помечен как deprecated; сейчас используют hcp_render_svg.py.

Об авторе

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

Го Комура

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

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