AGENTS.ka.md

lang	ka
direction	ltr
source	AGENTS.md
status	complete
generator	scripts/sync_docs_i18n.py
source_hash	5036d004829b1c2da0991b637aa735da9cdf2f3e8e42ac760ff651e60d25d433
source_last_modified	2026-01-31T07:37:05.947018+00:00
translation_last_reviewed	2026-02-07
translator	machine-google-reviewed

AGENTS ინსტრუქციები

ეს გაიდლაინები ვრცელდება მთელ საცავზე, რომელიც ორგანიზებულია როგორც ტვირთის სამუშაო სივრცე.

სწრაფი დაწყება

• სამუშაო ადგილი: cargo build --workspace
• მშენებლობას შეიძლება დასჭირდეს დაახლოებით 20 წუთი; გამოიყენეთ 20-წუთიანი ქრონომეტრაჟი მშენებლობის ნაბიჯებისთვის.
• შეამოწმეთ ყველაფერი: cargo test --workspace (გაითვალისწინეთ, რომ ამ გაშვებას ჩვეულებრივ რამდენიმე საათი სჭირდება; დაგეგმეთ შესაბამისად)
• მკაცრად: cargo clippy --workspace --all-targets -- -D warnings
• ფორმატის კოდი: cargo fmt --all (გამოცემა 2024)
• გამოცადეთ ერთი ყუთი: cargo test -p <crate>
• გაუშვით ერთი ტესტი: cargo test -p <crate> <test_name> -- --nocapture
• Swift SDK: IrohaSwift დირექტორიადან გაუშვით swift test Swift პაკეტის ტესტების შესასრულებლად.
• Android SDK: java/iroha_android-დან გაუშვით JAVA_HOME=$(/usr/libexec/java_home -v 21) ANDROID_HOME=~/Library/Android/sdk ANDROID_SDK_ROOT=~/Library/Android/sdk ./gradlew test.

მიმოხილვა

• Hyperledger Iroha არის ბლოკჩეინის პლატფორმა
• DA/RBC მხარდაჭერა განსხვავდება ძირითადი ვერსიით: Iroha 2 შეიძლება სურვილისამებრ იყოს DA/RBC ჩართული; Iroha 3 შეიძლება მხოლოდ DA/RBC იყოს ჩართული.
• IVM არის Iroha ვირტუალური მანქანა (IVM), ვირტუალური მანქანა Hyperledger Iroha v2 ბლოკჩეინისთვის
• Kotodama არის მაღალი დონის ჭკვიანი კონტრაქტის ენა IVM-ისთვის, რომელიც იყენებს .ko ფაილის გაფართოებას ნედლეული კონტრაქტის კოდისთვის და იგი იკრიბება ბაიტიკოდში, რომელიც იყენებს .to ფაილის გაფართოებას, როდესაც ინახება როგორც ფაილი ან ჯაჭვში. როგორც წესი, .to bytecode არის განლაგებული onchain.
  • დაზუსტება: Kotodama მიზნად ისახავს Iroha ვირტუალურ მანქანას (IVM) და აწარმოებს IVM ბაიტ კოდს (.to). ის არ მიზნად ისახავს “risc5”/RISC‑V, როგორც დამოუკიდებელ არქიტექტურას. სადაც RISC-V მსგავსი კოდირებები გამოჩნდება საცავში, ისინი წარმოადგენენ IVM-ის ინსტრუქციის ფორმატების იმპლემენტაციის დეტალებს და არ უნდა შეცვალონ დაკვირვებადი ქცევა აპარატურაში.
• Norito არის მონაცემთა სერიალიზაციის კოდეკი Iroha-ისთვის
• მთელი სამუშაო სივრცე მიზნად ისახავს Rust-ის სტანდარტულ ბიბლიოთეკას (std). WASM/no-std build-ები აღარ არის მხარდაჭერილი და არ უნდა იყოს გათვალისწინებული ცვლილებების შეტანისას.## საცავის სტრუქტურა
• Cargo.toml საცავის ძირში განსაზღვრავს სამუშაო სივრცეს და ჩამოთვლის ყველა წევრის ყუთს.
• crates/ - ჟანგის ყუთები, რომლებიც ახორციელებენ Iroha კომპონენტებს. თითოეულ კრატს აქვს საკუთარი ქვედირექტორია, რომელიც ჩვეულებრივ შეიცავს src/, tests/, examples/ და benches/.
  • მნიშვნელოვანი ყუთები მოიცავს:
    • iroha - უმაღლესი დონის ბიბლიოთეკის ძირითადი ფუნქციონირება.
    • irohad – დემონური ორობითი, რომელიც უზრუნველყოფს კვანძის განხორციელებას.
    • ivm – Iroha ვირტუალური მანქანა.
    • iroha_cli – ბრძანების ხაზის ინტერფეისი კვანძთან ურთიერთობისთვის.
    • iroha_core, iroha_data_model, iroha_crypto და სხვა დამხმარე ყუთები.
• IrohaSwift/ – Swift პაკეტი კლიენტისთვის/მობილური SDK-სთვის. მისი წყაროები ცხოვრობს Sources/IrohaSwift/-ის ქვეშ და მისი ერთეული ტესტები ქვეშ Tests/IrohaSwiftTests/. გაუშვით swift test ამ დირექტორიადან Swift კომპლექტის გამოსაყენებლად.
• integration_tests/ – ტვირთის კოლოფის ჰოსტინგის ჯვარედინი კომპონენტის ტესტები tests/-ის ქვეშ.
• data_model/ – მონაცემთა მოდელის განმარტებების ნიმუში, რომელიც გამოიყენება ტესტებსა და დოკუმენტაციაში.
• docs/ – საპროექტო დოკუმენტაცია და დიზაინის შენიშვნები. Markdown წყაროები ცხოვრობს docs/source/-ში.
• pytests/ – პითონზე დაფუძნებული ტესტები და კლიენტის გამოყენების მაგალითები.
• scripts/ – სასარგებლო სკრიპტები, რომლებიც გამოიყენება განვითარებისა და CI მილსადენებში.
• examples/ios/ და examples/ios/NoritoDemoXcode/ – iOS აპლიკაციების ნიმუში Swift SDK-ის ჩვენებით; ისინი ეყრდნობიან IrohaSwift პაკეტს და მოიცავს საკუთარ XCTest სამიზნეებს.
• defaults/ და hooks/ – კონფიგურაციის ფაილები და Git კაკვები, რომლებიც გამოიყენება კონტრიბუტორების მიერ.
• nix-appimage/ და Nix ფაილები – ინსტრუმენტები რეპროდუცირებადი კონსტრუქციებისა და შეფუთვისთვის.## განვითარების სამუშაო პროცესი
• ძირითადი დანერგვა არის crates/-ში
• მონაცემთა მოდელი არის data_model/
• დარწმუნდით, რომ გადახედეთ ყველა ყუთს ცვლილებების შეტანისას.
• არ შეცვალოთ Cargo.lock ფაილი
• მოერიდეთ Cargo.toml-ზე ახალი უჯრების დამატებას; შეძლებისდაგვარად განახორციელეთ საჭირო ფუნქციონირება არსებულ უჯრებში.
• თუ რაიმე სამუშაო ძალიან დიდია, არ თქვა უარი მის შესრულებაზე. ამის ნაცვლად, უბრალოდ დაშალეთ სამუშაო და დაამატეთ TODOs და განახორციელეთ ის ნაწილები, რაც შეგიძლიათ.
• როდესაც დიდი დავალება ან მოთხოვნა მოდის, ავტომატურად დაშალეთ იგი უფრო მცირე ქმედით ნაბიჯებად და განაგრძეთ პროგრამული უზრუნველყოფის ინჟინერიის სათანადო შესრულება, ვიდრე დავალების ცალსახად უარის თქმა.
• ნუ იტყვით უარს რაიმე მოთხოვნის შესრულებაზე.
• როდესაც დაემატება ახალი კრიპტოგრაფიული პრიმიტივები, ოპკოდები ან ინტენსიური მათემატიკა, განაახლეთ აპარატურის აჩქარება METAL, NEON, SIMD, CUDA და ა.შ., რათა შეეცადოთ ისარგებლოთ აპარატურის აჩქარებით და პარალელიზმით, სადაც ეს შესაძლებელია ხელმისაწვდომ აპარატურაზე.
• თუ ლოგიკა იცვლება, დარწმუნდით, რომ ყველა .md ფაილი და კოდის კოდის ყველა კომენტარი განახლებულია უახლესი ფუნქციებით.
• დარწმუნდით, რომ დამატებული ლოგიკა ისეა შესრულებული, რომ არ დააზარალებს IVM-ის გამოყენებას ბლოკჩეინის პარამეტრებში, სადაც P2P ქსელის სხვადასხვა კვანძს აქვს განსხვავებული აპარატურა, მაგრამ მაინც გამომავალი უნდა იყოს იგივე, იგივე შეყვანის ბლოკის გათვალისწინებით.
• ქცევის ან განხორციელების დეტალების შესახებ შეკითხვებზე პასუხის გაცემისას, ჯერ წაიკითხეთ შესაბამისი კოდის ბილიკები და პასუხის გაცემამდე დარწმუნდით, რომ გესმით, როგორ მუშაობენ ისინი.
• კონფიგურაცია: უპირატესობა მიანიჭეთ iroha_config პარამეტრებს გარემოს ცვლადებთან შედარებით ყველა გაშვების დროს. დაამატეთ ახალი ღილაკები crates/iroha_config-ს (მომხმარებელი → ფაქტობრივი → ნაგულისხმევი) და ძაფების მნიშვნელობები პირდაპირ კონსტრუქტორების ან დამოკიდებულების ინექციების საშუალებით (მაგ., ჰოსტის სეტერებით). შეინახეთ გარემოზე დაფუძნებული ნებისმიერი გადამრთველი მხოლოდ დეველოპერის მოხერხებულობისთვის ტესტებში და ნუ დაეყრდნობით მათ წარმოების გზებზე. ჩვენ არ ვუჭერთ მხარს მიწოდების ფუნქციებს გარემოს ცვლადების მიღმა - წარმოების ქცევა ყოველთვის უნდა იყოს მიღებული კონფიგურაციის ფაილებიდან და ამ კონფიგურაციებმა უნდა გამოავლინოს გონივრული ნაგულისხმევი პარამეტრები, რათა ახალბედამ შეძლოს რეპოს კლონირება, ბინარების გაშვება და ყველაფერი „უბრალოდ იმუშაოს“ მნიშვნელობების ხელით რედაქტირების გარეშე.
  • IVM/Kotodama v1-ისთვის ყოველთვის დაცულია მაჩვენებლის-ABI ტიპის მკაცრი პოლიტიკა. არ არსებობს ABI-პოლიტიკის გადართვა; კონტრაქტები და მასპინძლები უპირობოდ უნდა დაიცვან ABI პოლიტიკა.
• არ დაუშვათ IVM სისტემის ან ოპკოდებში გამოყენებული არაფერი; ყოველი Iroha build უნდა გაგზავნოს ეს კოდის ბილიკები, რათა შეინარჩუნოს დეტერმინისტული ქცევა კვანძებში.
• სერიალიზაცია: გამოიყენეთ Norito ყველგან serde-ის ნაცვლად. ბინარული კოდეკებისთვის გამოიყენეთ norito::{Encode, Decode}; JSON-ისთვის გამოიყენეთ norito::json დამხმარეები/მაკროები (norito::json::from_*, to_*, json!, Value) და არასოდეს დაბრუნდეთ I18NI0000000-ზე. არ დაამატოთ პირდაპირი serde/serde_json დამოკიდებულებები ყუთებში; თუ სერდი საჭიროა შინაგანად, დაეყრდნოთ Norito-ის შეფუთვას.
• CI მცველი: scripts/check_no_scale.sh უზრუნველყოფს SCALE (parity-scale-codec) გამოჩნდება მხოლოდ Norito საორიენტაციო აღკაზმულობაში. გაუშვით ლოკალურად, თუ შეეხებით სერიალიზაციის კოდს.
• Norito მომხმარებელმა უნდა განაცხადოს თავისი განლაგება: ან ვერსიის ნომერი აისახება ფიქსირებულ დროშის კომპლექტზე, ან Norito სათაური აცხადებს დეკოდირების დროშებს. არ გამოიცნოთ შეფუთული მიმდევრობის ბიტები ევრისტიკიდან; გენეზის მონაცემები იგივე წესს მიჰყვება.- ბლოკები უნდა იყოს შენარჩუნებული და განაწილებული იყოს კანონიკური SignedBlockWire ფორმატის გამოყენებით (SignedBlock::encode_wire/canonical_wire), რომელიც ასახავს ვერსიის ბაიტს Norito სათაურით. შიშველი დატვირთვები არ არის მხარდაჭერილი.
• დაამატეთ TODO: კომენტარი, რომელიც განმარტავს ნებისმიერ დროებით ან არასრულ განხორციელებას.
• დაფორმატეთ Rust-ის ყველა წყარო cargo fmt --all-ით (გამოცემა 2024) ჩადენამდე.
• დაამატეთ ტესტები: უზრუნველყოთ მინიმუმ ერთი ერთეულის ტესტი ყოველი ახალი ან შეცვლილი ფუნქციისთვის, რომელიც მოთავსებულია #[cfg(test)]-თან ან კრატის tests/ დირექტორიაში.
• გაუშვით cargo test ლოკალურად, მოაგვარეთ ნებისმიერი პრობლემა და დარწმუნდით, რომ გაივლის. გააკეთეთ ეს მთელი საცავისთვის და არა მხოლოდ კონკრეტული ყუთისთვის.
• სურვილისამებრ გაუშვით cargo clippy -- -D warnings დამატებითი ლაქის შემოწმებისთვის.

დოკუმენტაცია

• ყოველთვის დაამატეთ ყუთის დონის დოკუმენტაცია: დაიწყეთ თითოეული ყუთი ან სატესტო ყუთი მოკლე შიდა დოკუმენტის კომენტარით (//! ...).
• არ გამოიყენოთ არსად #![allow(missing_docs)] ან ელემენტის დონის #[allow(missing_docs)] (ინტეგრაციის ტესტების ჩათვლით). დაკარგული დოკუმენტაცია უარყოფილია სამუშაო სივრცის ლინზებში და უნდა დაფიქსირდეს დოკუმენტების ჩაწერით.
• Norito კოდეკი: იხილეთ norito.md რეპოს ძირში კანონიკური on-wire განლაგებისა და განხორციელების დეტალებისთვის. თუ Norito-ის ალგორითმები ან განლაგება შეიცვალა, განაახლეთ norito.md იმავე PR-ში.
• მასალის აქადურად თარგმნისას უზრუნველყოთ ლურსმული ასოებით დაწერილი სემანტიკური გადმოცემა; მოერიდეთ ფონეტურ ტრანსლიტერაციას და როდესაც ზუსტი ძველი ტერმინები აკლია, აირჩიეთ პოეტური აქადური მიახლოებები, რომლებიც ინარჩუნებენ ჩანაფიქრს.

ABI Evolution (რა უნდა გააკეთონ აგენტებმა)

შენიშვნა: პირველი გამოშვების პოლიტიკა

• ეს არის პირველი გამოშვება და გვაქვს ერთი ABI ვერსია (V1). V2 ჯერ არ არის. განიხილეთ ქვემოთ მოცემული ABI-თან დაკავშირებული ევოლუციის ყველა ელემენტი, როგორც მომავალი სახელმძღვანელო; ამ დროისთვის, სამიზნე მხოლოდ abi_version = 1. მონაცემთა მოდელი და API ასევე არის პირველი გამოშვება და შეიძლება თავისუფლად შეიცვალოს, როგორც საჭიროა გაგზავნისთვის; უპირატესობას ანიჭებს სიცხადეს და სისწორეს ნაადრევ სტაბილურობას.

• ზოგადი:

  • ABI პოლიტიკა ხორციელდება უპირობოდ v1-ში (როგორც syscall-ის ზედაპირი, ასევე პოინტერ-ABI ტიპის). არ დაამატოთ გაშვების გადამრთველები.
  • ცვლილებებმა უნდა შეინარჩუნოს დეტერმინიზმი აპარატურასა და თანატოლებში. განაახლეთ ტესტები და დოკუმენტები იმავე PR-ში.

• თუ დაამატეთ/წაშლით/გადანომრავთ syscals:

  • განაახლეთ 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 (სტაბილურობა + ვერსიის გამოყოფა)

• თუ დაამატებთ პოინტერ-ABI ტიპებს:

  • დაამატეთ ახალი ვარიანტი ivm::pointer_abi::PointerType-ს (მინიშნეთ ახალი u16 ID; არასოდეს შეცვალოთ არსებული ID).
  • განაახლეთ ivm::pointer_abi::is_type_allowed_for_policy სწორი abi_version რუკებისთვის.
  • განაახლეთ crates/ivm/tests/pointer_type_ids_golden.rs და საჭიროების შემთხვევაში დაამატეთ პოლიტიკის ტესტები.

• თუ შემოგთავაზებთ ახალ ABI ვერსიას:

  • რუკა ProgramMetadata.abi_version → ivm::SyscallPolicy და განაახლეთ Kotodama შემდგენელი, რათა გამოუშვას ახალი ვერსია მოთხოვნის შემთხვევაში.
  • განაახლეთ abi_hash (ivm::syscalls::compute_abi_hash-ის მეშვეობით) და დარწმუნდით, რომ მანიფესტებში ჩაშენებულია ახალი ჰეში.
  • დაამატეთ ტესტები ნებადართული/აკრძალული syscals-ისთვის და მაჩვენებლის ტიპებისთვის ახალი ვერსიის მიხედვით.

• მიღება და მანიფესტაციები:

  • დაშვება ახორციელებს code_hash/abi_hash თანასწორობას ჯაჭვურ მანიფესტებთან მიმართებაში; შეინახეთ ეს ქცევა ხელუხლებლად.
  • ტესტები iroha_core/tests/-ში დასამატებლად/განახლებისთვის: დადებითი (შესაბამისი abi_hash) და უარყოფითი (არაშესაბამისი) შემთხვევები.- დოკუმენტები და სტატუსის განახლებები (იგივე PR):
  • განაახლეთ crates/ivm/docs/syscalls.md (ABI Evolution განყოფილება) და ნებისმიერი syscall ცხრილი.
  • განაახლეთ status.md და roadmap.md ABI ცვლილებებისა და ტესტის განახლებების მოკლე შეჯამებით.

პროექტის სტატუსი და გეგმა

• შეამოწმეთ status.md რეპოს ძირში მიმდინარე კრებულის/გაშვების სტატუსისთვის ყუთებში.
• შეამოწმეთ roadmap.md პრიორიტეტული TODO-ებისთვის და განხორციელების გეგმისთვის.
• სამუშაოს დასრულების შემდეგ განაახლეთ სტატუსი status.md-ში და შეინახეთ roadmap.md ორიენტირებული გამორჩეულ ამოცანებზე.

აგენტის სამუშაო ნაკადი (კოდების რედაქტორებისთვის/ავტომატიზაციისთვის)

• თუ რაიმე მოთხოვნაზე გარკვევა გჭირდებათ, შეაჩერეთ და შეადგინეთ ChatGPT მოთხოვნა თქვენი შეკითხვით, შემდეგ გაუზიარეთ ის მომხმარებელს, სანამ გააგრძელებთ.
• შეინახეთ ცვლილებები მინიმალური და მასშტაბური; თავიდან აიცილეთ დაკავშირებული რედაქტირებები იმავე პაჩში.
• უპირატესობა მიანიჭეთ შიდა მოდულებს, ვიდრე ახალი დამოკიდებულებების დამატებას; არ დაარედაქტიროთ Cargo.lock.
• გამოიყენეთ ფუნქციების დროშები, რათა დაიცვან აპარატურით დაჩქარებული ბილიკები (მაგ., simd, cuda) და ყოველთვის უზრუნველყოთ განმსაზღვრელი სარეზერვო გზა.
• დარწმუნდით, რომ გამომავალი დარჩება იდენტური აპარატურაში; მოერიდეთ არადეტერმინისტულ პარალელურ შემცირებაზე დაყრდნობას.
• განაახლეთ დოკუმენტაცია და მაგალითები, როდესაც საჯარო API ან ქცევა იცვლება.
• დაადასტურეთ სერიალიზაციის ცვლილებები iroha_data_model-ში ორმხრივი ტესტებით, რათა შეინარჩუნოთ Norito განლაგების გარანტიები.
• ინტეგრაციის ტესტები ატრიალებენ რეალურ მრავალ თანატოლ ქსელებს; გამოიყენეთ მინიმუმ 4 თანატოლი სატესტო ქსელების აგებისას (ერთჯერადი კონფიგურაციები არ არის წარმომადგენლობითი და შეიძლება ჩაკეტილი იყოს Sumeragi-ში).
• არ შეეცადოთ გამორთოთ DA/RBC ტესტებში (მაგ., DevBypassDaAndRbcForZeroChain-ის საშუალებით); DA ძალაშია და ეს შემოვლითი გზა ამჟამად ჩიხშია sumeragi-ში კონსენსუსის გაშვების დროს.
• QC კვორუმი უნდა დაკმაყოფილდეს ხმის მიცემის ვალიდატორებმა (min_votes_for_commit); დამკვირვებლის შიგთავსი არ ითვლება ხელმისაწვდომობის/წინასწარი კენჭისყრის/წინასწარი კვორუმის შემოწმებებში, ამიტომ QC-ების აგრეგაცია მხოლოდ მას შემდეგ რაც საკმარისი ვალიდატორი ხმები იქნება.
• DA-ზე ჩართული კონსენსუსი ახლა უფრო მეტხანს ელოდება ხედის ცვლილებებამდე (ქვორუმის დროის ამოწურვა = block_time + 4 * commit_time), რათა RBC/ხელმისაწვდომობის QC დასრულდეს უფრო ნელ ჰოსტებზე.

ნავიგაციის რჩევები

• მოძებნეთ კოდი: rg '<term>' და ჩამოთვალეთ ფაილები: fd <name>.
• გამოიკვლიეთ ყუთები: fd --type f Cargo.toml crates | xargs -I{} dirname {}.
• სწრაფად იპოვნეთ მაგალითები/სკამები: fd . crates -E target -t d -d 3 -g "*{examples,benches}".
• პითონის რჩევა: ზოგიერთი გარემო არ იძლევა python; სცადეთ python3 ამის ნაცვლად სკრიპტების გაშვებისას.

პროკ-მაკრო ტესტები

• ერთეულის ტესტები: გამოიყენეთ სუფთა ანალიზისთვის, კოდიგენის დამხმარეებისთვის და კომუნალური პროგრამებისთვის (სწრაფი, შემდგენელი არ არის ჩართული).
• ინტერფეისის ტესტები (trybuild): გამოყენება კომპილაციის დროში ქცევისა და გამოყვანის/პროკ-მაკროს დიაგნოსტიკის დასადასტურებლად (წარმატება და მოსალოდნელი წარუმატებლობის შემთხვევები .stderr-ით).
• უპირატესობა მიანიჭეთ ორივეს მაკროების დამატების/შეცვლისას: ერთეულის ტესტები შიდა მოწყობილობებისთვის + UI ტესტები მომხმარებლის მიმართ ქცევისთვის და შეცდომის შეტყობინებებისთვის.
• მოერიდეთ პანიკას; გამოსცემს მკაფიო დიაგნოზს (მაგ., syn::Error ან proc_macro_error მეშვეობით). შეინახეთ შეტყობინებები სტაბილურად და განაახლეთ .stderr მხოლოდ განზრახ ცვლილებებისთვის.

გაიყვანეთ მოთხოვნის შეტყობინება

ჩართეთ ცვლილებების მოკლე შინაარსი და Testing განყოფილება, რომელიც აღწერს თქვენ მიერ შესრულებულ ბრძანებებს.