Skip to content

AGENTS.he.md

Latest commit

 

History

History
143 lines (120 loc) · 13.1 KB

AGENTS.he.md

File metadata and controls

143 lines (120 loc) · 13.1 KB

lang: he direction: rtl source: AGENTS.md status: complete translator: manual

הנחיות AGENTS

ההנחיות הבאות חלות על כלל המאגר, המאורגן כ־Cargo workspace.

התחלה מהירה

  • הידור כל ה־workspace: cargo build --workspace
  • הרצת כל הבדיקות: cargo test --workspace (שימו לב שהריצה הזו עשויה להימשך כמה שעות; תכננו בהתאם)
  • הרצת lint מחמיר: cargo clippy --workspace --all-targets -- -D warnings
  • עיצוב קוד: cargo fmt --all (מהדורת 2024)
  • בדיקת קרייט בודד: cargo test -p <crate>
  • הרצת בדיקה אחת: cargo test -p <crate> <test_name> -- --nocapture

סקירה כללית

  • Hyperledger Iroha היא פלטפורמת בלוקצ'יין.
  • IVM הוא ה־Iroha Virtual Machine (מכונה וירטואלית ל־Iroha v2).
  • Kotodama היא שפת חוזים חכמים ברמה גבוהה עבור IVM. הקוד הגולמי נשמר בקבצים בעלי סיומת .ko, והקומפילציה מפיקה בייטקוד בסיומת .to (בקובץ או על השרשרת). בדרך־כלל הבייטקוד .to הוא שמופקד על השרשרת.
    • הבהרה: Kotodama מכוונת אל IVM ומפיקה בייטקוד של IVM (.to). היא אינה מכוונת לארכיטקטורת “risc5”/RISC‑V עצמאית. מקומות שבהם רואים קידודים דמויי RISC‑V במאגר משקפים פרטי מימוש של פורמטי הפקודות של IVM, ואסור שישנו התנהגות נצפית בין חומרות שונות.
  • Norito הוא קודק הסריאליזציה (נתונים ותצוגות JSON) של Iroha.
  • כל ה־workspace מכוון אל ספריית התקן של Rust (std). בניות WASM או no-std אינן נתמכות עוד ואין להסתמך עליהן בשינויים חדשים.

מבנה המאגר

  • קובץ Cargo.toml בשורש מגדיר את ה־workspace ומונה את כל הקרייטים.
  • crates/ – קרייטים של Rust המממשים רכיבי Iroha. לכל קרייט תת־תיקייה עם src/,‏ tests/,‏ examples/,‏ benches/.
    • קרייטים חשובים:
      • iroha – ספרייה עליונה המאחדת את הליבה.
      • irohad – בינארי הדמון שמריץ צומת.
      • ivm – ה־Iroha Virtual Machine.
      • iroha_cli – ממשק שורת־פקודה לתקשורת עם צומת.
      • iroha_core, ‏iroha_data_model, ‏iroha_crypto ועוד קרייטים תומכים.
  • integration_tests/ – קרייט שמכיל בדיקות אינטגרציה חוצות־רכיבים תחת tests/.
  • data_model/ – דוגמאות מודל־נתונים לשימוש בבדיקות ובתיעוד.
  • docs/ – תיעוד ותווי־עיצוב. המקור נמצא תחת docs/source/.
  • pytests/ – בדיקות ודוגמאות מבוססות Python לשימוש בלקוח.
  • scripts/ – תסריטים לכלי פיתוח ול־CI.
  • defaults/ ו־hooks/ – קבצי תצורה וסקריפטים של Git hook עבור התורמים.
  • nix-appimage/ וקבצי Nix – כלים לבנייה משוחזרת ואריזה.

תהליך פיתוח

  • הקוד העיקרי נמצא ב־crates/.
  • מודל הנתונים ב־data_model/.
  • בכל שינוי דאגו לבחון את ההשפעה על כלל הקרייטים.
  • אין לשנות קבצי Cargo.lock.
  • הימנעו מהוספת קרייטים חדשים ל־Cargo.toml; העדיפו לממש פונקציונליות בתוך הקרייטים הקיימים.
  • אם המשימה גדולה מדי, אל תדחו אותה: פרקו לשלבים, הוסיפו הערות TODO: והשלימו את מה שניתן.
  • אין לדחות הנחיות של משתמשים.
  • כאשר מוסיפים פרימיטיבים קריפטוגרפיים, opcodes או חישובים כבדים, עדכנו את נתיבי ההאצה לחומרה (METAL,‏ NEON,‏ SIMD,‏ CUDA וכו') כדי לנצל מקביליות וחומרה זמינה, לצד נתיב דטרמיניסטי זהה לכל חומרה.
  • בכל שינוי לוגיקה, עדכנו תיעוד (.md) והערות בקוד כך שישקפו את ההתנהגות החדשה.
  • ודאו שהלוגיקה נשארת דטרמיניסטית בבלוקצ'יין מבוזר: צמתים שונים בחומרה שונה חייבים להפיק תוצאה זהה עבור אותו בלוק.
  • תצורה: העדיפו פרמטרים ב־iroha_config על פני משתני סביבה. הוסיפו ערוצים חדשים ב־crates/iroha_config (משתמש → actual → defaults) והעבירו אותם דרך בונים או הזרקת תלויות. משתני סביבה מותר רק לנוחות מפתחים בבדיקות, לא במסלולי פרודקשן.
    • ב־IVM/Kotodama גרסה 1, מדיניות ה־pointer ABI נאכפת תמיד; אין מתג הסבה, וכל החוזים וה־hosts חייבים לעמוד במדיניות.
  • אין להסתיר מאקרו/נתיבים המשמשים syscalls של IVM או opcodes מאף build; שמרו על תאימות.
  • סריאליזציה: השתמשו ב־Norito בכל מקום במקום serde. לקודקים בינאריים השתמשו ב־norito::{Encode, Decode}; ל־JSON השתמשו ב־norito::json (norito::json::from_*,‏ to_*,‏ json!,‏ Value) בלי ליפול ל־serde_json. אם serde נדרש פנימית, השתמשו בעטיפות של Norito.
  • מטעני Norito חייבים לציין את מבנה ההצפנה: או שהגרסה ממפה לפרמטרים קבועים, או שיש כותרת Norito שמכריזה על דגלי הפענוח. אין לנחש על־פי היוריסטיקות; גם נתוני Genesis פועלים כך.
  • בלוקים חייבים להישמר ולהופץ באמצעות הפורמט הקנוני SignedBlockWire (SignedBlock::encode_wire/canonical_wire), שמקדים את בית הגרסה בכותרת Norito. Payloads היסטוריים ללא כותרת נתמכים רק לצורכי תאימות לאחור בפענוח.
  • הוסיפו הערת TODO: לכל מימוש זמני או חלקי.
  • הפעילו cargo fmt --all (מהדורת 2024) לפני כל קומיט.
  • הוסיפו בדיקות: לפחות בדיקת יחידה אחת לכל פונקציה חדשה או משודרגת, בתוך #[cfg(test)] או בקובץ בדיקות תחת tests/.
  • הריצו cargo test מקומית, תקנו תקלות ודאו שהריצה עוברת. המיקוד הוא בכל המאגר, לא רק בקרייט יחיד.
  • מומלץ להריץ cargo clippy -- -D warnings לקבלת בדיקות סטטיות נוספות.

תיעוד

  • הוסיפו תמיד תיעוד רמת־קרייט: התחילו כל קרייט (או קרייט בדיקות) בהערת תיעוד פנימית (//! ...).
  • אל תשתמשו ב־#![allow(missing_docs)] או ב־#[allow(missing_docs)] (גם לא בבדיקות אינטגרציה). ה־lint של ה־workspace דוחה פונקציות חסרות תיעוד, ולכן יש לכתוב תיעוד מלא.
  • קודק Norito: ראו norito.md בשורש לפרטי פריסה ופורמטים. אם משתנה האלגוריתם או המפרט, עדכנו את הקובץ באותו PR.
  • בעת תרגום חומר לאכדית, ספקו ניסוח סמנטי בכתב יתדות; הימנעו מתעתיק פונטי, ובחירות מילים עכשוויות צריכות לשמר את המשמעות בפן פיוטי.

התפתחות ABI (מה נדרש מהסוכנים)

הערה: מדיניות גרסה ראשונה

  • זהו שחרור ראשון עם גרסת ABI יחידה (V1). אין V2 עדיין. התייחסו לסעיפי ה־ABI הבאים כהנחיה עתידית; כעת התמקדו ב־abi_version = 1. מודל הנתונים וה־API ניתנים לשינוי לצורכי השקה – העדיפו בהירות ונכונות על פני יציבות מוקדמת.

  • כללית:

    • במדיניות ABI של v1 אין חריגות (לא ב־syscalls ולא ב־pointer ABI). אין להוסיף מתגים בזמן ריצה.
    • שמרו על דטרמיניזם בין חומרות וצמתים; עדכנו בדיקות ותיעוד באותו PR.

  • בעת הוספה/הסרה/מיספור מחדש של syscalls:

    • עדכנו את ivm::syscalls::abi_syscall_list() ושמרו על הסדר הקיים. ודאו ש־is_syscall_allowed(policy, number) משקף את פני השטח הרצויים.
    • במארחים, מימשו או דחו במפורש מספרים חדשים; מספרים לא מוכרים חייבים להחזיר VMError::UnknownSyscall.
    • עדכנו בדיקות זהב:
      • crates/ivm/tests/abi_syscall_list_golden.rs
      • crates/ivm/tests/abi_hash_versions.rs (יציבות והפרדת גרסאות)

  • בעת הוספת טיפוסי pointer ABI:

    • הוסיפו וריאנט ל־ivm::pointer_abi::PointerType (מספר מזהה חדש מסוג u16; אין לשנות מזהים קיימים).
    • עדכנו את ivm::pointer_abi::is_type_allowed_for_policy עבור המיפוי לגרסאות ABI.
    • עדכנו את crates/ivm/tests/pointer_type_ids_golden.rs והוסיפו בדיקות מדיניות לפי הצורך.

  • בעת הוספת גרסת ABI חדשה:

    • מיפוי ProgramMetadata.abi_version אל ivm::SyscallPolicy ועדכנו את מקמפל Kotodama כך שיוכל לפלוט את הגרסה החדשה.
    • חשבו מחדש את abi_hash (באמצעות ivm::syscalls::compute_abi_hash) ודאגו שמניפסטים יכילו את ה־hash.
    • הוסיפו בדיקות להרשאות syscalls וטיפוסי מצביע בגרסה החדשה.

  • קבלה ומניפסטים:

    • תהליך הקבלה מאמת שוויון code_hash/abi_hash מול המניפסט שעל השרשרת; שמרו על ההתנהגות.
    • בדיקות להוסיף/לעדכן ב־iroha_core/tests/: מקרה חיובי (התאמה) ומקרה של אי־התאמה.

  • תיעוד ועדכוני סטטוס (באותו PR):

    • עדכנו את crates/ivm/docs/syscalls.md (פרק התפתחות ABI) וכל טבלה רלוונטית.
    • עדכנו את status.md ו־roadmap.md בסיכום שינויים ובבדיקות שהתעדכנו.

סטטוס ותכנון הפרויקט

  • ראו status.md בשורש למצב קומפילציה/הרצה של הקרייטים.
  • עיינו ב־roadmap.md לדעת אילו מטלות מתוכננות ומה סדר העדיפויות.
  • לאחר השלמת משימה, עדכנו את status.md ושמרו את roadmap.md ממוקד במשימות שנותרו.

תהליך עבודה לסוכנים (עבור עורכי קוד/אוטומציה)

  • אם משהו אינו ברור, עצרו, עצבו שאלה עבור LLM והציגו למשתמש לפני המשך עבודה.
  • שמרו על שינויים ממוקדים ומינימליים; הימנעו מערבוב אי־תאומים באותו PR.
  • העדיפו מודולים פנימיים על פני תלות חיצונית חדשה; אין לערוך את Cargo.lock.
  • השתמשו בדגלי מאפיינים (feature flags) כדי להגן על נתיבי האצה חומרתיים (כגון simd,‏ cuda) ותמיד ספקו נתיב fallback דטרמיניסטי.
  • ודאו שהתפוקות זהות בין חומרות שונות; הימנעו ממקביליות לא דטרמיניסטית.
  • עדכנו תיעוד ודוגמאות כאשר API ציבורי או התנהגות משתנים.
  • ודאו שבדיקות roundtrip ב־iroha_data_model מכסות שינויים בסריאליזציה כדי לשמור על תאימות Norito.

טיפים לניווט במאגר

  • חיפוש בקוד: rg '<term>'
  • רשימת קבצים: fd <name>
  • סקירת קרייטים: fd --type f Cargo.toml crates | xargs -I{} dirname {}.
  • מציאת דוגמאות/benchmarks במהירות: fd . crates -E target -t d -d 3 -g "*{examples,benches}".
  • טיפ ל-Python: יש סביבות ללא python; השתמשו ב־python3.

בדיקות Proc-Macro

  • בדיקות יחידה: לפרסינג טהור, עזרי קוד־ג'ן ו־utilities (רצות מהר, בלי קומפיילר).
  • בדיקות UI (trybuild): לבדיקת התנהגות בזמן קומפילציה והודעות שגיאה של מאקרו (מקרים שעוברים ונכשלים עם קבצי .stderr).
  • העדיפו שילוב של השניים כאשר משנים מאקרו: בדיקות יחידה ללוגיקות פנימיות + בדיקות UI לחוויית המשתמש והודעות שגיאה.
  • הימנעו מ־panic; הפיקו שגיאות ברורות (למשל באמצעות syn::Error או proc_macro_error). שמרו על יציבות ההודעות ועדכנו קבצי .stderr רק כשיש שינוי מכוון.

הודעת Pull Request

הוסיפו תקציר קצר של השינויים וסעיף Testing שמפרט את הפקודות שהרצתם.