什麼是 HCP 圖表 - 把 HCP-DSL 轉為決定性 SVG 的 MakingHCPChartSkill 使用方式

1. 什麼是 HCP 圖表

HCP 圖表是一種以階層方式描述處理流程的表達方式。
在這個儲存庫裡，下列寫法被視為必備規則。

• 左側是「要達成什麼（目的）」
• 右側（更深的縮排）是「如何達成（手段・細節）」
• 最頂層（level 0）寫上目的標籤

依照這些規則撰寫文本，可以讓設計意圖與實作細節之間的對應變得容易閱讀。

2. 這個儲存庫解決的問題

若只以人工維護圖檔，常會遇到下列問題。

• 圖和規格文字對不上
• 分支或階層的限制變模糊
• 不容易做 diff 審查

MakingHCPChartSkill 的流程是：把 HCP-DSL 作為 JSON request 傳入，由 hcp_render_svg.py 進行驗證與繪製。
相同輸入會得到相同輸出，因此圖檔可以很自然地納入 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。

4. 10 分鐘 Hands-on（GCD 範例）

4.1. 取得儲存庫

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

4.2. 把 skill 放到本機的 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. 從回應 JSON 取出 SVG

$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. 歐幾里得演算法（GCD）

• 輸入範例：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 圖表）

execute_request 的處理流程若以 HCP-DSL 表達，如下所示。

\module main
接收請求並確認前提
    驗證輸入 JSON 的必要項目
剖析 DSL 並結構化
    解讀模組與階層
    收集 diagnostics
依診斷結果選擇回應路徑
    \fork 是否存在 error
        \true 是
            回傳空的 SVG 系 payload
        \false 否
            決定要繪製的模組
            \fork renderAllModules 是否為 true
                \true 是
                    生成所有模組的 SVG
                    組出含 svgs 的回應 JSON
                \false 否
                    生成單一模組的 SVG
                    組出含 svg 的回應 JSON
把結果回傳給呼叫端

把上述 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