مدخل إلى مخطّط HCP وMakingHCPChartSkill

المحتويات

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

عندما تريد لمخطّط HCP أن يصير «رسمًا يُقرأ كمواصفة»، يصعب التشغيل بالرسوم اليدوية وحدها. MakingHCPChartSkill مستودع skill يفسّر HCP-DSL (نصًا) وفق المواصفة ويعيد SVG حتميًا (أي أنّ المدخل نفسه يعطي SVG نفسه دائمًا).

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

في المخطّط، يشير الخطّ المتّصل إلى علاقة قائمة دائماً، ويشير الخطّ المتقطّع إلى علاقة مشروطة (شروط قيامها مذكورة في شرح كلّ علاقة في الصفحة التفصيليّة). القائمة الكاملة للعلاقات (المجموع 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، وهي طريقة رسم وُضعت في مختبر يوكوسوكا للاتصالات الكهربائية التابع لهيئة البرق والهاتف اليابانية (NTT حاليًا). أي أنّها ليست مصطلحًا اخترعه هذا المقال أو المستودع، بل تدوين مستخدم في اليابان من قبل. من سماتها: إمكان وصف المعالجة هرميًا، وسهولة إلحاق علاقة البيانات والمعالجة، وسهولة الرسم يدويًا، ووضع الشرح قرب الرمز لا داخل إطار فيدخل في الصفحة الواحدة محتوى أكثر.

إذا صففتها مع طرائق أخرى يتّضح موضعها.

بعد ذلك، ما يخصّ 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 وضع الغاية يسارًا، ورتّب فرعي true وfalse مباشرة تحت fork.

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

إذا أُدير الرسم وحده يدويًا، يشيع وقوع مشكلات كهذه.

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

في MakingHCPChartSkill تمرّر HCP-DSL كطلب JSON، ويتولّى hcp_render_svg.py التحقّق والرسم. المدخل نفسه يعطي المخرج نفسه دائمًا، لذلك يسهل إدخال الرسوم في CI والمراجعة.

flowchart TB
    accTitle: مشكلات الرسم اليدوي وحلّ الإدارة كنصّ
    accDescr: إذا أُدير الرسم وحده يدويًا يقع انحراف عن نص المواصفة وصعوبة مراجعة الفروقات، أمّا تمرير HCP-DSL كطلب JSON فيتولّى معه hcp_render_svg.py التحقّق والرسم، والمدخل نفسه يعطي SVG نفسه.
    hand["إدارة الرسم وحده يدويًا"] -.-> issue["انحراف · غموض · صعوبة مراجعة الفروقات"]
    dsl["تمرير HCP-DSL كطلب JSON"] --> render["hcp_render_svg.py يتحقّق ويرسم"]
    render --> svg["يعود SVG حتمي"]
    svg --> ci["يمكن إدخاله في CI والمراجعة"]

الشكل 4: بدل رسم اليد يُولَّد SVG حتميًا من نص HCP-DSL، فيمكن حمله على مراجعة الفروقات و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 غير مستحسن.
    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 غير مستحسن"]

الشكل 5: المدخل SKILL.md، والجسم hcp_render_svg.py، والمواصفة والعيّنات مجمّعة تحت references.

4. تمرين عملي في 10 دقائق (عيّنة GCD)

بيئة الافتراض

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. خوارزمية إقليدس (GCD)

• مثال المدخل: example-gcd-request.json
• مثال المخرج: example-gcd-response.json

«استلام المدخل» و«التكرار» و«الإعادة» مفصولة هرميًا، فيسهل تتبّع غاية المعالجة ووسيلتها.

إذا قرأت العمود الأيسر فقط تحصل على ثلاثة أسطر: «استلام قيم المدخل وتهيئة الحساب ← الاقتراب من القاسم المشترك الأكبر ما بقي باقٍ ← إعادة النتيجة إلى المستخدم»، وهذا وحده ملخّص الخوارزمية. حساب ملموس مثل r <- a mod b مُنزَّل من «تحديد القيمة التي تُمرَّر تاليًا» داخل التكرار إلى إزاحة أعمق يمينًا. هذا الموضع هو تقابل «الغاية (يسار) والوسيلة (يمين)» نفسه. إن ظهر r <- a mod b فجأة في الطرف الأيسر، فهذه إشارة إلى مخالفة قاعدة حبيبات الوصف (1.1).

flowchart TB
    accTitle: الملخّص الذي يبيّنه العمود الأيسر في عيّنة GCD
    accDescr: العمود الأيسر في عيّنة GCD ثلاثة أسطر: استلام قيم المدخل وتهيئة الحساب، والاقتراب ما بقي باقٍ، وإعادة النتيجة إلى المستخدم، والحساب الملموس مُنزَّل إلى إزاحة أعمق يمينًا.
    g1["استلام قيم المدخل والتهيئة"] --> g2["الاقتراب ما بقي باقٍ"]
    g2 --> g3["إعادة النتيجة إلى المستخدم"]
    g2 -.-> d1["الحساب الملموس في طبقة أعمق يمينًا"]

الشكل 8: العمود الأيسر في عيّنة GCD. ثلاثة أسطر وحدها تعطي ملخّص الخوارزمية، وتفاصيل الحساب تنزل يمينًا.

سطر 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 فارغة
        \false لا
            تحديد وحدة أو وحدات الرسم
            \fork هل renderAllModules يساوي true
                \true نعم
                    توليد SVG لكلّ الوحدات
                    تجميع JSON استجابة يتضمّن svgs
                \false لا
                    توليد SVG لوحدة واحدة
                    تجميع JSON استجابة يتضمّن svg
إعادة النتيجة إلى المستدعي

الرسم الناتج عن تصيير DSL أعلاه فعلاً هو هذا.

7. خلاصة

قوّة مخطّط HCP ليست سهولة قراءته كرسم فقط، بل أنّه يمكن إدارته بشكل يُعامل كمواصفة. باستخدام MakingHCPChartSkill يمكن توليد SVG باتّساق مع التحقّق من HCP-DSL.

إن أردت التجربة تاليًا، فكتابة مواصفة معالجة يومية واحدة بـ 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 والمراجعة.

ما الفرق عن إدارة الرسوم يدويًا؟

إذا أُدير الرسم وحده يدويًا، يشيع انحراف الرسم عن نص المواصفة، وغموض قيود التفرّع والهرمية، وصعوبة مراجعة الفروقات. إذا وُلِّد SVG حتميًا من نص HCP-DSL، يمكن إدارة الرسم بشكل يُعامل كمواصفة، وتحسينه مع مراقبة diagnostics.

هل توجد قيود عند الاستخدام؟

عندما يكون renderAllModules=true لا يمكن تحديد module في الوقت نفسه. وإذا احتوى diagnostics على error، يكون svg أو svgs فارغًا. السكربت hcp_xml_to_svg.py صار deprecated، ويُستخدم الآن hcp_render_svg.py.

الملف الشخصي للمؤلف

صفحة الملف الشخصي لمؤلف المقالة.

غو كومورا

مؤسّس شركة كومورا سوفت ذ.م.م.

يركّز على تطوير برامج ويندوز، والاستشارات التقنية، والتحقيق في الأخطاء، ويتميّز في المشاريع التي تبقى فيها الأصول القديمة ناشطة، وفي تشخيص الأعطال التي يصعب تحديد سببها.