HCP 图表与 MakingHCPChartSkill 入门

目录

1. 什么是 HCP 图表
2. 这个仓库解决的问题
3. 最快掌握仓库结构
4. 10 分钟上手（GCD 示例）
5. 两个示例的读法
6. 内部在做什么（HCP 图表）
7. 总结

当想把 HCP 图表变成「可以当作规范来阅读的图」时，仅靠手绘图表就很难维持运作。 MakingHCPChartSkill 是一个技能仓库，用于 按照规范解析 HCP-DSL（文本），并返回决定性的 SVG。

本文将从 HCP 图表的基础讲起，一直确认到实际动手运行为止。

1. 什么是 HCP 图表

HCP 图表是一种以层级方式描述处理流程的表达形式。 在这个仓库中，以下写法被当作必须遵循的规则。

• 左侧是「要达成什么（目的）」
• 右侧（更深的缩进）是「如何达成（手段・细节）」
• 最上层（level 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/ 规范参考、示例 request/response、示例 SVG。
• hcp-chart-svg-v2/scripts/hcp_xml_to_svg.py 已废弃（deprecated）。目前请使用 hcp_render_svg.py。

4. 10 分钟上手（GCD 示例）

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. 从响应 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

相关文章

共享相同标签的最新文章。可以围绕相近的主题进一步加深理解。

常见问题

汇总了咨询这一主题时常见的问题。

什么是 HCP 图表？

HCP 图表是一种以层级方式描述处理流程的表达形式。左侧写「要达成什么（目的）」，右侧更深的缩进处写「如何达成（手段・细节）」，最上层（level 0）写目的标签。按照这套规则书写文本，可以让设计意图与实现细节之间的对应关系变得容易阅读。

MakingHCPChartSkill 是做什么的工具？

它是一个技能仓库，按照规范解析 HCP-DSL（文本），并返回决定性的 SVG。把 HCP-DSL 作为 JSON 请求传入后，由 hcp_render_svg.py 进行验证与绘制。相同输入必定得到相同输出，因此这种结构很容易把图表纳入 CI 或代码评审流程。

与手动管理图表相比有什么不同？

如果只靠人工管理图表，容易出现图表与规范文本不一致、分支或层级的约束变得含糊、难以进行差异评审等问题。而通过 HCP-DSL 这种文本以决定性方式生成 SVG 的方式，可以把图表作为规范来管理，并可以一边查看 diagnostics 一边进行调整。

使用上有哪些限制？

当 renderAllModules=true 时，不能同时指定 module。此外，如果 diagnostics 中存在 error，svg 或 svgs 就会为空。脚本方面，hcp_xml_to_svg.py 已被标记为 deprecated，目前应使用 hcp_render_svg.py。

作者简介

本文作者的个人简介页面。

Go Komura

小村软件有限公司 代表

以 Windows 软件开发、技术咨询与故障排查为中心，擅长难以复现的故障调查，以及既有资产仍在运行的项目。