ما هو HCP chart - كيفية استخدام MakingHCPChartSkill لتحويل HCP-DSL إلى SVG حتمي

المحتويات

1. ما هو HCP chart
2. ما الذي يحلّه هذا المستودع
3. أسرع طريقة لفهم بنية المستودع
4. مثال عملي في 10 دقائق (عيّنة GCD)
5. كيفيّة قراءة العيّنتين
6. ما الذي تفعله Skill داخليّاً (HCP chart)
7. الخلاصة

إذا أردتَ لـ HCP chart أن يعمل بوصفه مخطّطاً بيانيّاً يمكن قراءته كأنّه مواصفة، فإنّ المخطّطات المرسومة يدويّاً وحدها تصبح في النهاية صعبة الصيانة.
إنّ MakingHCPChartSkill هو مستودع skill يقوم بـ تفسير نصّ HCP-DSL وفقاً للمواصفة وإرجاع مخرجات SVG حتميّة.

ينطلق هذا المقال من الفكرة الأساسيّة لـ HCP charts ويصل بك حتى تشغيل الأداة فعليّاً.

1. ما هو HCP chart

HCP chart هو طريقة لوصف المعالجة وصفاً هرميّاً.
في هذا المستودع، تُعامَل قواعد الكتابة التالية بوصفها قواعد إلزاميّة:

• الجانب الأيسر يعبّر عن ما يُراد تحقيقه (الهدف)
• الإزاحة الأعمق على الجانب الأيمن تعبّر عن كيفيّة تحقيقه (الوسائل والتفاصيل)
• المستوى الأعلى (المستوى 0) يحتوي على عنوان الهدف

بكتابة النصّ وفق هذه القواعد، تصبح قراءة العلاقة بين نيّة التصميم وتفاصيل التنفيذ أسهل.

2. ما الذي يحلّه هذا المستودع

إنّ إدارة المخطّطات يدويّاً تَخلق عادةً مشكلات شائعة:

• ينحرف المخطّط عن نصّ المواصفة
• تصبح قواعد التفرّع والهرمية غامضة
• تصبح مراجعة الفروقات أصعب ممّا ينبغي

يحلّ MakingHCPChartSkill هذا الأمر بقبول HCP-DSL بوصفه طلب JSON ودَع 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 دقائق (عيّنة 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. استخراج 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. خوارزميّة إقليدس (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. ما الذي تفعله Skill داخليّاً (HCP chart)

إذا عبّرتَ عن تدفّق المعالجة داخل execute_request بـ HCP-DSL، فإنّه يبدو كما يلي:

\module main
Receive the request and confirm the prerequisites
    Validate required fields in the input JSON
Parse the DSL and build structure
    Interpret modules and hierarchy
    Collect diagnostics
Choose the response path according to the diagnostic result
    \fork does an error exist
        \true yes
            Return an empty SVG payload
        \false no
            Decide which module or modules to render
            \fork is renderAllModules true
                \true yes
                    Generate SVG for all modules
                    Build a response JSON that contains svgs
                \false no
                    Generate SVG for a single module
                    Build a response JSON that contains svg
Return the result to the caller

وهذا هو المخطّط الناتج من تصيير ذلك الـ DSL فعليّاً:

7. الخلاصة

ليست قوّة HCP charts فقط في كونها سهلة القراءة بوصفها مخطّطات بيانيّة.
بل في أنّها يمكن إدارتها بصيغة تعمل بوصفها مواصفةً.

مع MakingHCPChartSkill، يمكنك التحقّق من HCP-DSL وتوليد مخرج SVG ضمن تدفّق متّسق واحد.

إن أردتَ تجربتها لاحقاً، فإنّ خطوة أولى جيّدة هي أن تأخذ إحدى مواصفات المعالجة اليوميّة لديك وتكتبها بـ HCP-DSL وتصقلها أثناء مراقبة diagnostics.

مراجع

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