Skip to content

AGENTS.mn.md

Latest commit

 

History

History
146 lines (129 loc) · 24.5 KB

AGENTS.mn.md

File metadata and controls

146 lines (129 loc) · 24.5 KB
lang mn
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: 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 нь onchain дээр тавигддаг.
    • Тодруулга: 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 файлууд болон эх кодын тайлбарууд хамгийн сүүлийн үеийн функцээр шинэчлэгдсэн эсэхийг шалгаарай.
  • P2P сүлжээн дэх өөр өөр зангилаанууд өөр өөр техник хангамжтай байдаг, гэхдээ ижил оролтын блоктой гаралт нь ижил байх ёстой блокчейн тохиргоонд IVM-ийг ашиглахад хор хөнөөл учруулахгүй байхаар нэмсэн бүх логик хийгдсэн эсэхийг шалгаарай.
  • Зан төлөв эсвэл хэрэгжилтийн талаархи асуултуудад хариулахдаа эхлээд холбогдох кодын замыг уншиж, хариулахаасаа өмнө тэдгээр нь хэрхэн ажилладагийг ойлгосон эсэхээ шалгаарай.
  • Тохиргоо: Ажиллах үеийн бүх үйлдлийн хувьд орчны хувьсагчдаас iroha_config параметрүүдийг илүүд үз. crates/iroha_config (хэрэглэгч → бодит → өгөгдмөл) дээр шинэ товчлууруудыг нэмж, хэлхээний утгыг бүтээгч эсвэл хамаарлын инжээр (жишээ нь, хост тохируулагч) ашиглан тодорхой зааж өгнө үү. Туршилтанд зөвхөн хөгжүүлэгчийн тав тухыг хангах үүднээс хүрээлэн буй орчинд суурилсан унтраалгатай байлгаж, үйлдвэрлэлийн замд тэдгээрт бүү найд. Бид хүрээлэн буй орчны хувьсагчийн цаана байгаа тээвэрлэлтийн онцлогийг дэмждэггүй—үйлдвэрлэлийн үйл ажиллагаа нь үргэлж тохиргооны файлуудаас үүсэлтэй байх ёстой бөгөөд тэдгээр тохиргоонууд нь анхдагч тохиргоог илчлэх ёстой бөгөөд ингэснээр шинээр ирсэн хүн репо-г клончилж, хоёртын файлуудыг ажиллуулж, утгыг гараар засварлахгүйгээр бүх зүйл "зүгээр л ажиллах" боломжтой болно.
    • IVM/Kotodama v1-ийн хувьд заагч-ABI төрлийн хатуу бодлогыг үргэлж хэрэгжүүлдэг. ABI-бодлогын унтраалга байхгүй; гэрээ болон хостууд ABI бодлогыг болзолгүйгээр дагаж мөрдөх ёстой.
  • IVM системийн дуудлагууд болон үйлдлийн кодуудад ашигласан аливаа зүйлийг бүү хаагаарай; Iroha бүтээх бүр нь зангилаа хоорондын детерминист зан төлөвийг хадгалахын тулд тэдгээр кодын замыг илгээх ёстой.
  • Цувралчлал: Serde-ийн оронд Norito-г хаа сайгүй ашигла. Хоёртын кодлогчийн хувьд norito::{Encode, Decode}; JSON-д norito::json туслах/макро (norito::json::from_*, to_*, json!, Value) ашиглах ба хэзээ ч I18NI00000089 руу буцахгүй. 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 ID оноож, одоо байгаа ID-г хэзээ ч өөрчлөхгүй).
    • 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-д одоогоор мухардмал байна.
  • Саналыг баталгаажуулагч (min_votes_for_commit) чанарын хяналтын чуулга хангасан байх ёстой; Ажиглагчийн бөглөх нь чуулгын бэлэн байдлыг шалгах/урьдчилан санал өгөх/урьдчилан гаргахад тооцогдохгүй тул баталгаажуулагчийн санал хангалттай ирсний дараа л QC-г нэгтгэнэ.
  • DA-г идэвхжүүлсэн зөвшилцөл нь удаашралтай хостууд дээр RBC/хүртээмжтэй чанарын хяналтыг дуусгахын тулд харагдацын өөрчлөлтийг хүлээхээс өмнө удаан хүлээх болно (чуулгын хугацаа дуусах = 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): эмхэтгэх хугацааны төлөвийг баталгаажуулах, derive/proc-makros-ийн оношлогоо (.stderr-ийн амжилт ба хүлээгдэж буй бүтэлгүйтэл).
  • Макро нэмэх/өөрчлөхдөө аль алиныг нь илүүд үзээрэй: дотоод системийн нэгжийн тест + хэрэглэгчийн нүүр царай болон алдааны мэдэгдлийн UI тест.
  • үймээн самуунаас зайлсхийх; тодорхой оношийг ялгаруулна (жишээ нь, syn::Error эсвэл proc_macro_error-ээр). Зурвасуудыг тогтвортой байлгаж, .stderr-г зөвхөн санаатайгаар өөрчлөхөд шинэчилнэ үү.

Хүсэлтийг татах мессеж

Өөрчлөлтүүдийн товч хураангуй болон таны гүйцэтгэсэн тушаалуудыг тайлбарласан Testing хэсгийг оруулна уу.