HCP chart ו-MakingHCPChartSkill — איך כותבים ומפיקים SVG

תוכן עניינים

1. מה זה HCP chart
2. הבעיה שהמאגר הזה פותר
3. להבין את מבנה המאגר במהירות
4. הדרכה של 10 דקות (דוגמת GCD)
5. איך קוראים את שתי הדוגמאות
6. מה קורה בפנים (HCP chart)
7. סיכום

כשרוצים ש-HCP chart יהיה “תרשים שאפשר לקרוא כמפרט”, קשה לתחזק זאת רק עם תרשימים שרושמים ביד. MakingHCPChartSkill הוא מאגר skill שמפרש HCP-DSL (טקסט) לפי המפרט, ומחזיר SVG דטרמיניסטי (כלומר, אותו קלט תמיד מייצר את אותו SVG).

במאמר הזה נתחיל מהיסודות של HCP chart, ונגיע עד להרצה בפועל, הכול ברצף אחד.

ב-diagram, solid line מציינת relation שתמיד מתקיים ו-dashed line מציינת relation מותנה (התנאים מופיעים בהסבר של כל relation ב-detail page). הרשימה המלאה של ה-relations (סה”כ 14, כולל evidence ו-certainty) וההגדרות של ה-concepts המרכזיים נמצאות ב-detail page של ה-knowledge map (ביפנית). Data: JSON-LD / Turtle

1. מה זה HCP chart

HCP chart הוא צורת ייצוג לתיאור עיבוד בהיררכיה. במאגר הזה, אופן הכתיבה הבא נחשב לכלל חובה.

• בצד שמאל: “מה משיגים (המטרה)”
• בצד ימין (הזחה עמוקה יותר): “איך משיגים (האמצעי/הפרטים)”
• ברמה העליונה ביותר (level 0) כותבים תווית מטרה

כתיבת טקסט לפי הכלל הזה מקלה על קריאת ההתאמה בין כוונת התכנון לפרטי המימוש.

flowchart TB
    accTitle: כלל הבסיס של תיאור HCP chart
    accDescr: ברמה העליונה ביותר, level 0, כותבים תווית מטרה, בצד שמאל את המטרה — מה משיגים, ובצד ימין בהזחה עמוקה יותר את האמצעי — איך משיגים, וכך אפשר לקרוא את ההתאמה בין כוונת התכנון לפרטי המימוש.
    l0["level 0 מכילה רק תווית מטרה"] --> goal["בצד שמאל: המטרה (מה משיגים)"]
    goal --> means["בצד ימין: האמצעי (איך משיגים)"]
    means -.-> effect["אפשר לקרוא את ההתאמה בין כוונה לפרטי מימוש"]

איור 1: HCP chart מתאר עיבוד בהיררכיה לפי ההתאמה “שמאל = מטרה, הזחה מימין = אמצעי”.

1.1. המקור של HCP וההבדל מול צורות תרשים אחרות

HCP הוא קיצור של Hierarchical ComPact description chart, צורת תרשים שנוצרה במעבדת המחקר לתקשורת אלקטרונית של יוקוסוקה, שהייתה שייכת לתאגיד הטלפון והטלגרף היפני (כיום NTT). כלומר, זו לא המצאה של המאמר הזה או של המאגר הזה, אלא סימון שהיה בשימוש ביפן עוד קודם. מבין המאפיינים שלו: אפשר לכתוב עיבוד בהיררכיה, קל להוסיף את הקשר בין נתונים לעיבוד, קל לכתוב גם בכתב יד חופשי, וההסבר ממוקם ליד הסמל ולא בתוך מסגרת, כך שהרבה תוכן נכנס בדף אחד.

כשמשווים לצורות תרשים אחרות, קל יותר לראות את מיקומו.

מעבר לזה, מה שייחודי למאגר MakingHCPChartSkill שבו עוסק המאמר הזה, אינו הסימון עצמו אלא שני הדברים הבאים:

• HCP-DSL לכתיבת HCP chart כטקסט, ומפרט הפרשנות שלו (references/hcpchartspec.md)
• מוסכמת רזולוציית התיאור: “ב-level 0 כותבים רק תווית מטרה, וכתיבה בסגנון קוד כמו השמה או השוואה מורידים לצומת ילד”. זה כלל חובה שהמאגר קובע, ולא כלל כללי של HCP chart

flowchart TB
    accTitle: הפרדה בין הסימון הכללי לחלק הייחודי למאגר
    accDescr: HCP chart כשלעצמו הוא סימון קיים שנוצר במעבדת המחקר של יוקוסוקה, ומה שייחודי למאגר הזה הוא רק שני דברים — HCP-DSL ומפרט הפרשנות שלו, ומוסכמת רזולוציית התיאור.
    general["HCP chart (סימון קיים)"] --> repo["החלק הייחודי ל-MakingHCPChartSkill"]
    repo --> dsl["HCP-DSL ומפרט הפרשנות"]
    repo --> conv["מוסכמת רזולוציית התיאור"]
    conv -.-> rule["level 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, בודקים תנאים מוקדמים של הקלט, מסתעפים לפי תקינות הקלט — אם תקין מריצים את העיבוד העיקרי ומחזירים תוצאה, ואם לא — מחזירים כשגיאה לצד הקורא.
    m["התחלת module main"] --> pre["לקבל קלט ולבדוק תנאים מוקדמים"]
    pre --> fork{"האם הקלט תקין"}
    fork -->|"כן"| main["להריץ את העיבוד העיקרי"]
    fork -->|"לא"| err["להחזיר כשגיאה (return)"]
    main --> ret["להחזיר תוצאה"]

איור 3: זרימת הדוגמה המינימלית. מתחילים מ-module, שמים את המטרה משמאל, ומציבים את הענפים true ו-false ישירות מתחת ל-fork.

2. הבעיה שהמאגר הזה פותר

כשמנהלים רק תרשימים בידיים, נוטות לקרות בעיות כאלה.

• פער בין התרשים לטקסט המפרט
• אי-בהירות במגבלות של ההסתעפויות וההיררכיה
• קושי בסקירת diffs

ב-MakingHCPChartSkill, מעבירים את ה-HCP-DSL כבקשת JSON, ו-hcp_render_svg.py מבצע validation ו-render. כי אותו קלט תמיד נותן אותו פלט, קל לשלב את התרשים ב-CI או בסקירות.

flowchart TB
    accTitle: הבעיה בניהול ידני של תרשימים והפתרון בניהול טקסטואלי
    accDescr: ניהול תרשימים בידיים בלבד גורם לפער מול טקסט המפרט ולקושי בסקירת diffs, לעומת זאת העברת HCP-DSL כבקשת JSON גורמת ל-hcp_render_svg.py לבצע validation ו-render ולקבל SVG דטרמיניסטי.
    hand["ניהול תרשימים בידיים בלבד"] -.-> issue["פער, אי-בהירות, קושי בסקירת diffs"]
    dsl["העברת HCP-DSL כבקשת JSON"] --> render["hcp_render_svg.py מבצע validation ו-render"]
    render --> svg["מתקבל SVG דטרמיניסטי"]
    svg --> ci["ניתן לשלב ב-CI או בסקירות"]

איור 4: במקום לצייר תרשים ביד, מייצרים SVG באופן דטרמיניסטי מתוך טקסט ה-HCP-DSL, כך שאפשר לשלב בסקירת diffs וב-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 דקות (דוגמת 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 chart”, הוא יקרא ל-renderer בהתאם להוראות של SKILL.md הזה.

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

השלב הזה אינו חובה. ה-renderer הוא סקריפט עצמאי שמקבל --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 chart
    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 chart)

תהליך העיבוד של execute_request, כשכותבים אותו ב-HCP-DSL, נראה כך.

\module main
לקבל בקשה ולבדוק תנאים מוקדמים
    לאמת את השדות הנדרשים ב-JSON הקלט
לפרש את ה-DSL ולבנות מבנה
    לפרש modules והיררכיה
    לאסוף diagnostics
לבחור מסלול תגובה לפי תוצאות האבחון
    \fork האם קיים error
        \true כן
            להחזיר payload מסוג SVG ריק
        \false לא
            לקבוע את ה-module המיועד לציור
            \fork האם renderAllModules הוא true
                \true כן
                    לייצר SVG לכל ה-modules
                    לבנות JSON תגובה הכולל svgs
                \false לא
                    לייצר SVG ל-module יחיד
                    לבנות JSON תגובה הכולל svg
להחזיר תוצאה לצד הקורא

זהו התרשים שמתקבל מ-render בפועל של ה-DSL שלמעלה.

7. סיכום

HCP chart לא רק קל לקריאה כתרשים — היתרון שלו הוא שאפשר לנהל אותו בצורה שנחשבת מפרט. כשמשתמשים ב-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 chart?

צורת ייצוג לתיאור עיבוד בהיררכיה. בצד שמאל כותבים "מה משיגים (המטרה)", ובצד ימין בהזחה עמוקה יותר כותבים "איך משיגים (האמצעי/הפרטים)", וברמה העליונה ביותר (level 0) כותבים תווית מטרה. כתיבת טקסט לפי הכלל הזה מקלה על קריאת ההתאמה בין כוונת התכנון לפרטי המימוש.

מה עושה הכלי MakingHCPChartSkill?

זה מאגר skill שמפרש HCP-DSL (טקסט) לפי המפרט, ומחזיר SVG דטרמיניסטי. כשמעבירים HCP-DSL כבקשת JSON, hcp_render_svg.py מבצע validation ו-render. אותו קלט תמיד מייצר את אותו פלט, ולכן קל לשלב את התרשימים ב-CI או בסקירות קוד.

מה ההבדל מול ניהול תרשימים בכתב יד?

כשמנהלים רק תרשימים בידיים, נוטות לקרות בעיות כמו פער בין התרשים לטקסט המפרט, אי-בהירות במגבלות של ההסתעפויות וההיררכיה, וקושי בסקירת diffs. בשיטה שמייצרת SVG באופן דטרמיניסטי מטקסט שנקרא HCP-DSL, אפשר לנהל את התרשים כמפרט, ולעצב אותו תוך התבוננות ב-diagnostics.

יש מגבלות בשימוש?

כן. renderAllModules=true ו-module לא ניתנים לציון בו-זמנית. בנוסף, אם ב-diagnostics יש error, svg או svgs יהיו ריקים. הסקריפט hcp_xml_to_svg.py הוא deprecated, וכעת משתמשים ב-hcp_render_svg.py.

פרופיל הכותב

עמוד היכרות עם כותב המאמר.

Go Komura

מנהל KomuraSoft LLC

מתמחה בפיתוח תוכנה עבור Windows, ייעוץ טכני וחקירת תקלות, בעיקר בפרויקטים עם מערכות קיימות ובאגים שקשה לשחזר.