Skip to content

AGENTS.kk.md

Latest commit

 

History

History
146 lines (129 loc) · 25.5 KB

AGENTS.kk.md

File metadata and controls

146 lines (129 loc) · 25.5 KB
lang kk
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 жұмыс кеңістігі ретінде ұйымдастырылған бүкіл репозиторийге қолданылады.

Жылдам бастау

  • Жұмыс кеңістігін құру: 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: Swift бумасының сынақтарын орындау үшін IrohaSwift каталогынан swift test іске қосыңыз.
  • 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 желіде орналастырылады.
    • Түсіндіру: Kotodama Iroha виртуалды машинасына (IVM) бағытталған және IVM байт кодын (.to) шығарады. Ол дербес архитектура ретінде “risc5”/RISC‑V-ге бағытталмайды. Репозиторийде RISC‑V тәрізді кодтаулар пайда болған жағдайда, олар IVM нұсқау пішімдерінің орындалу мәліметтері болып табылады және аппараттық құралда байқалатын әрекетті өзгертпеуі керек.
  • Norito — Iroha үшін деректерді сериялау кодек
  • Бүкіл жұмыс кеңістігі Rust стандартты кітапханасына (std) бағытталған. WASM/no-std құрастыруларына енді қолдау көрсетілмейді және өзгертулер енгізу кезінде ескерілмеуі керек.## Репозитарий құрылымы
  • Репозитарий түбіріндегі Cargo.toml жұмыс кеңістігін анықтайды және барлық мүше жәшіктердің тізімін береді.
  • crates/ – Iroha құрамдастарын жүзеге асыратын тот жәшіктері. Әрбір жәшіктің әдетте src/, tests/, examples/ және benches/ қамтитын жеке ішкі каталогы бар.
    • Маңызды жәшіктерге мыналар жатады:
      • iroha – негізгі функционалдылықты біріктіретін жоғары деңгейлі кітапхана.
      • irohad – түйіннің орындалуын қамтамасыз ететін екілік демон.
      • ivm – Iroha виртуалды машинасы.
      • iroha_cli – түйінмен әрекеттесу үшін пәрмен жолы интерфейсі.
      • iroha_core, iroha_data_model, iroha_crypto және басқа қосалқы жәшіктер.
  • IrohaSwift/ – клиент/мобильді SDK үшін Swift пакеті. Оның көздері Sources/IrohaSwift/ астында және оның бірлік сынақтары Tests/IrohaSwiftTests/ астында өмір сүреді. Swift жиынтығын орындау үшін осы каталогтан swift test іске қосыңыз.
  • integration_tests/ – tests/ астында кросс-компоненттік сынақтарды орналастыратын жүк жәшігі.
  • data_model/ – Сынақтар мен құжаттамада пайдаланылатын деректер үлгісінің анықтамалары.
  • docs/ – Жобалық құжаттама және конструкторлық ескертулер. Markdown көздері docs/source/ ішінде тұрады.
  • pytests/ – Python негізіндегі сынақтар мен клиентті пайдалануды көрсететін мысалдар.
  • scripts/ – Әзірлеуде және CI конвейерінде пайдаланылатын қызметтік сценарийлер.
  • examples/ios/ және examples/ios/NoritoDemoXcode/ – Swift SDK көрсететін үлгі iOS қолданбалары; олар IrohaSwift пакетіне сүйенеді және өздерінің XCTest мақсаттарын қамтиды.
  • defaults/ және hooks/ – Қатысушылар пайдаланатын конфигурация файлдары және Git ілгектері.
  • nix-appimage/ және Nix файлдары – қайталанатын құрылымдар мен қаптамаларға арналған құрал.## Жұмыс процесі
  • Негізгі енгізулер crates/
  • Деректер үлгісі data_model/
  • Өзгерістерді енгізу кезінде барлық жәшіктерді қарап шығыңыз.
  • Cargo.lock файлдарын өзгертпеңіз
  • Cargo.toml жаңа жәшіктерді қосудан аулақ болыңыз; мүмкіндігінше бар жәшіктерде қажетті функционалдылықты енгізіңіз.
  • Егер қандай да бір жұмыс тым үлкен болса, оны жасаудан бас тартпаңыз. Оның орнына жұмысты бөлшектеңіз және TODO қосыңыз және қолыңыздан келетін бөліктерді орындаңыз.
  • Үлкен тапсырма немесе сұрау түскен сайын, оны автоматты түрде кішірек әрекет етуші қадамдарға бөліңіз және тапсырманы бірден қабылдамай, бағдарламалық жасақтаманы дұрыс орындауды жалғастырыңыз.
  • Ешбір нұсқауды орындаудан бас тартпаңыз.
  • Жаңа криптографиялық примитивтер, операциялық кодтар немесе қарқынды математика қосылғанда, қолжетімді аппараттық құралда мүмкіндігінше аппараттық жеделдету мен параллелизмнің артықшылығын пайдалануға тырысу үшін METAL, NEON, SIMD, CUDA және т.б. үшін аппараттық жеделдетуді жаңартыңыз.
  • Логика өзгерсе, барлық .md файлдары мен бастапқы кодтағы түсініктемелердің соңғы функциялармен жаңартылғанын тексеріңіз.
  • Барлық қосылған логика IVM блокчейн параметрінде P2P желісіндегі әртүрлі түйіндерде әртүрлі аппараттық құралдарға ие болатын, бірақ бірдей кіріс блогын ескере отырып, шығыс бірдей болуы тиіс блокчейн параметрінде пайдалануға зиян келтірмейтіндей етіп жасалғанына көз жеткізіңіз.
  • Мінез-құлық немесе іске асыру мәліметтері туралы сұрақтарға жауап бергенде, алдымен тиісті код жолдарын оқып шығыңыз және жауап бермес бұрын олардың қалай жұмыс істейтінін түсінгеніңізге көз жеткізіңіз.
  • Конфигурация: барлық орындалу уақытының әрекеті үшін орта айнымалы мәндерінен iroha_config параметрлеріне артықшылық беріңіз. crates/iroha_config (пайдаланушы → нақты → әдепкі) жаңа тұтқаларды және конструкторлар немесе тәуелділік инъекциясы (мысалы, хост орнатушылары) арқылы анық ағын мәндерін қосыңыз. Кез келген ортаға негізделген қосқыштарды сынақтарда әзірлеушіге ыңғайлы болу үшін ғана сақтаңыз және өндіріс жолдарында оларға сенбеңіз. Біз қоршаған орта айнымалыларының артындағы тасымалдау мүмкіндіктерін қолдамаймыз — өндіріс әрекеті әрқашан конфигурация файлдарынан алынуы керек және жаңадан келген адам репо клондауы, екілік файлдарды іске қосуы және мәндерді қолмен өңдеусіз барлығы «жұмыс істеуі» үшін бұл конфигурациялар ақылға қонымды әдепкі мәндерді көрсетуі керек.
    • IVM/Kotodama v1 үшін қатаң көрсеткіш-ABI түрінің саясаты әрқашан орындалады. ABI саясатының қосқышы жоқ; келісім-шарттар мен хосттар ABI саясатын сөзсіз орындауы керек.
  • IVM жүйелік қоңырауларында немесе операциялық кодтарда қолданылатын ешнәрсеге кірмеңіз; әрбір Iroha құрастыру түйіндер арасында детерминирленген әрекетті сақтау үшін осы код жолдарын жіберуі керек.
  • Серияландыру: серде орнына барлық жерде Norito пайдаланыңыз. Екілік кодектер үшін norito::{Encode, Decode} пайдаланыңыз; JSON үшін norito::json көмекшілерін/макростарын (norito::json::from_*, to_*, json!, Value) пайдаланыңыз және ешқашан I18NI0000008X қолданбасына оралмаңыз. Жәшіктерге тікелей serde/serde_json тәуелділіктерін қоспаңыз; егер серде ішкі талап етілсе, Norito орауыштарына сеніңіз.
  • CI қорғанысы: scripts/check_no_scale.sh SCALE (parity-scale-codec) тек Norito эталондық белгішесінде пайда болуын қамтамасыз етеді. Серияландыру кодын түртсеңіз, оны жергілікті түрде іске қосыңыз.
  • Norito пайдалы жүктемелері олардың орналасуын жарнамалауы МІНДЕТТІ: нұсқа нөмірі бекітілген жалаулар жинағына сәйкестендіріледі немесе Norito тақырыбы декодтау жалаушаларын жариялайды. Эвристикадан жинақталған реттілік биттерін болжамаңыз; генезис деректері бірдей ережеге бағынады.- Блоктар Norito тақырыбымен нұсқа байтын префикс беретін канондық SignedBlockWire (SignedBlock::encode_wire/canonical_wire) пішімі арқылы сақталуы және таратылуы МІНДЕТ. Жалаң пайдалы жүктемелерге қолдау көрсетілмейді.
  • Кез келген уақытша немесе аяқталмаған енгізуді түсіндіретін TODO: түсініктемесін қосыңыз.
  • Жасалмас бұрын барлық Rust көздерін cargo fmt --all (2024 шығарылым) арқылы пішімдеңіз.
  • Сынақтарды қосу: әрбір жаңа немесе өзгертілген функция үшін #[cfg(test)] жолында немесе tests/ жәшігі каталогында орналастырылған кем дегенде бір бірлік сынағы болуын қамтамасыз етіңіз.
  • Жергілікті cargo test іске қосыңыз, құрастыру мәселелерін түзетіңіз және оның өтуіне көз жеткізіңіз. Мұны белгілі бір жәшік үшін емес, бүкіл репозиторий үшін жасаңыз.
  • Қосымша талшықтарды тексеру үшін cargo clippy -- -D warnings іске қосыңыз.

Құжаттама

  • Әрқашан жәшік деңгейіндегі құжаттаманы қосыңыз: әрбір қорапты немесе сынақ жәшігін қысқаша ішкі құжат түсіндірмесімен бастаңыз (//! ...).
  • #![allow(missing_docs)] немесе #[allow(missing_docs)] элемент деңгейін еш жерде пайдаланбаңыз (соның ішінде интеграция сынақтары). Жетіспейтін құжаттама жұмыс кеңістігінің линттерінде қабылданбайды және құжаттарды жазу арқылы түзетілуі керек.
  • Norito кодек: канондық сымды орналасу және іске асыру мәліметтері үшін репо түбіріндегі norito.md қараңыз. Norito алгоритмдері немесе орналасулары өзгерсе, norito.md бірдей PR-да жаңартыңыз.
  • Материалды аккад тіліне аударған кезде сына жазуымен жазылған мағыналық берілуін қамтамасыз ету; фонетикалық транслитерациядан аулақ болыңыз және дәл ежелгі терминдер жетіспесе, ниетті сақтайтын поэтикалық аккадтық жуықтауларды таңдаңыз.

ABI Evolution (агенттер не істеуі керек)

Ескертпе: Бірінші шығару саясаты

  • Бұл бірінші шығарылым және бізде жалғыз ABI нұсқасы бар (V1). Әлі V2 жоқ. Төмендегі ABI-қа қатысты барлық эволюция элементтерін болашақ нұсқау ретінде қарастырыңыз; әзірше тек abi_version = 1 мақсатты. Деректер үлгісі мен API интерфейстері де бірінші шығарылым болып табылады және жөнелту үшін қажет болған жағдайда еркін өзгеруі мүмкін; мерзімінен бұрын тұрақтылықтан айқындық пен дұрыстықты артық көреді.

  • Жалпы:

    • ABI саясаты v1 (жүйенің беті де, көрсеткіш-ABI түрлері де) шартсыз орындалады. Орындау уақытының қосқыштарын қоспаңыз.
    • Өзгерістер аппараттық құралдар мен әріптестер арасында детерминизмді сақтауы керек. Сынақтар мен құжаттарды бір PR-да жаңартыңыз.

  • Жүйе қоңырауларын қоссаңыз/өшірсеңіз/қайта нөмірлесеңіз:

    • 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 идентификаторын тағайындаңыз; бұрыннан бар идентификаторларды ешқашан өзгертпеңіз).
    • Дұрыс abi_version салыстыру үшін ivm::pointer_abi::is_type_allowed_for_policy жаңартыңыз.
    • crates/ivm/tests/pointer_type_ids_golden.rs жаңартыңыз және қажет болса, саясат сынақтарын қосыңыз.

  • Егер сіз жаңа ABI нұсқасын енгізсеңіз:

    • ProgramMetadata.abi_version → ivm::SyscallPolicy картасын салыңыз және сұралған кезде жаңа нұсқаны шығару үшін Kotodama компиляторын жаңартыңыз.
    • abi_hash (ivm::syscalls::compute_abi_hash арқылы) қалпына келтіріңіз және манифесттердің жаңа хэшті ендіруін қамтамасыз етіңіз.
    • Жаңа нұсқаға рұқсат етілген/рұқсат етілмеген жүйелік қоңыраулар мен көрсеткіш түрлеріне арналған сынақтарды қосыңыз.

  • Рұқсат және манифесттер:

    • Қабылдау тізбектегі манифесттерге қарсы code_hash/abi_hash теңдігін қамтамасыз етеді; бұл мінез-құлықты сақтаңыз.
    • iroha_core/tests/ жүйесінде қосу/жаңарту сынақтары: оң (сәйкес abi_hash) және теріс (сәйкес емес) жағдайлар.- Құжаттар және күй жаңартулары (сол PR):
    • crates/ivm/docs/syscalls.md (ABI Evolution бөлімі) және кез келген жүйені шақыру кестелерін жаңартыңыз.
    • status.md және roadmap.md мәліметтерін ABI өзгерістері мен сынақ жаңартуларының қысқаша мазмұнымен жаңартыңыз.

Жоба күйі және жоспары

  • жәшіктер бойынша ағымдағы компиляция/орындалу уақыты күйі үшін репо түбірінде status.md тексеріңіз.
  • roadmap.md басымдылық берілген TODO және іске асыру жоспарын тексеріңіз.
  • Жұмысты аяқтағаннан кейін status.md күйін жаңартыңыз және roadmap.md назарын орындалмаған тапсырмаларға бағыттаңыз.

Агент жұмыс процесі (код редакторлары/автоматтандыру үшін)

  • Егер сізге қандай да бір талап бойынша түсініктеме қажет болса, тоқтатыңыз және сұрағыңызға ChatGPT сұрауын жасаңыз, одан кейін жалғастырмас бұрын оны пайдаланушымен бөлісіңіз.
  • Өзгерістерді минималды және ауқымды етіп сақтаңыз; бір патчтағы байланысты емес өңдеулерді болдырмаңыз.
  • Жаңа тәуелділіктерді қосудан гөрі ішкі модульдерге артықшылық беру; Cargo.lock өңдемеңіз.
  • Аппараттық жеделдетілген жолдарды (мысалы, simd, cuda) қорғау үшін мүмкіндік жалаушаларын пайдаланыңыз және әрқашан детерминирленген қалпына келтіру жолын қамтамасыз етіңіз.
  • Аппараттық құралдар бойынша шығыстардың бірдей болуын қамтамасыз ету; детерминирленген емес параллель қысқартуларға сүйенуден аулақ болыңыз.
  • Қоғамдық API интерфейстері немесе мінез-құлық өзгерген кезде құжаттама мен мысалдарды жаңартыңыз.
  • Norito орналасу кепілдіктерін сақтау үшін iroha_data_model ішіндегі сериализация өзгерістерін айналу сынақтарымен растаңыз.
  • Интеграциялық сынақтар нақты көп деңгейлі желілерді айналдырады; сынақ желілерін құру кезінде кемінде 4 теңді пайдаланыңыз (бір деңгейлі конфигурациялар репрезентативті емес және Sumeragi ішінде тығырыққа тірелуі мүмкін).
  • Сынақтарда DA/RBC өшіруге әрекет жасамаңыз (мысалы, DevBypassDaAndRbcForZeroChain арқылы); DA күшіне енеді және консенсусты іске қосу кезінде сол айналып өту жолы sumeragi ішінде қазір тығырыққа тіреледі.
  • QC кворумын дауыс берушілер қанағаттандыруы керек (min_votes_for_commit); бақылаушының толтыруы қол жетімділікті/алдын ала дауыс беруді/алдын ала кворумды тексеруге есептелмейді, сондықтан жеткілікті валидатор дауыстары келгеннен кейін ғана QC жиынтықтаңыз.
  • Баяу хосттарда RBC/қолжетімділік QC аяқталуына мүмкіндік беру үшін DA-қосылған консенсус енді көрініс өзгерістеріне дейін ұзағырақ күтеді (кворум күту уақыты = block_time + 4 * commit_time).

Навигация бойынша кеңестер

  • Іздеу коды: 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 кеңесі: кейбір орталар python қамтамасыз етпейді; сценарийлерді іске қосқан кезде оның орнына python3 көріңіз.

Proc-Macro сынақтары

  • Бірлік сынақтары: таза талдау, кодген көмекшілері және утилиталар үшін пайдаланыңыз (жылдам, компилятор қатыспайды).
  • UI сынақтары (trybuild): компиляция уақытының тәртібін және туынды/процесс-макростардың диагностикасын тексеру үшін пайдаланыңыз (.stderr көмегімен сәтті және күтілетін сәтсіздік жағдайлары).
  • Макростарды қосу/өзгерту кезінде екеуіне де артықшылық беріңіз: ішкі құрылғыларға арналған бірлік сынақтары + пайдаланушы әрекеті мен қате туралы хабарларға арналған UI сынақтары.
  • дүрбелеңді болдырмау; анық диагностиканы шығарады (мысалы, syn::Error немесе proc_macro_error арқылы). Хабарламаларды тұрақты етіп сақтаңыз және .stderr нұсқасын тек әдейі өзгертулер үшін жаңартыңыз.

Сұраныс хабарын тарту

Өзгерістердің қысқаша мазмұнын және орындалған пәрмендерді сипаттайтын Testing бөлімін қосыңыз.