بنية سير العمل لـ Arxi CLI والمشغل

Audience: Engineers extending CLI behavior and operators automating Arxi الجمهور: المهندسون الذين يقومون بتمديد سلوك CLI والمشغلون الذين يقومون بأتمتة Arxi باستخدام مخرجات الآلة.

جدول المحتويات

نظرة عامة تنفيذية
واجهة الأوامر والتوجيه
نموذج دقة وقت التشغيل
عمليات العمل
نموذج الإخراج والتعريب
حدود الإدخال الصعبة وسلوك الفشل المغلق
دلالات رمز الخروج
مرجع متقاطع ملف بملف

نظرة عامة تنفيذية

arxi هو الحدود التشغيلية لعمليات Arxi المحلية. يقوم بتنظيم arxi-recorder و arxi-store مع مجموعات أوامر واضحة ووضع JSON حتمي لأغراض الأتمتة.

F:crates/arxi-cli/src/main.rs L137-L187 F:crates/arxi-cli/src/main.rs L864-L909 F:crates/arxi-cli/src/commands.rs L19-L29 F:crates/arxi-cli/src/support.rs L19-L23

واجهة الأوامر والتوجيه

مجموعات الأوامر على المستوى الأعلى:

recorder (عمليات المقطع + الظرف)،
recorder envelope record-with-attachments (استيعاب المرفقات)
recorder signer (دورة حياة دوران مفتاح التوقيع الصريح)،
استعلام (استرجاع الظرف)،
bundle (بناء/تحقق/تفتيش)،
config (فحوصات تكوين وقت التشغيل)،
contract (أداة العقد المولدة generate/check)،
decision-gate (استيعاب التركيب عبر محول الإنتاج)،
doctor (تشخيص المتجر والقطاعات النشطة).

F:crates/arxi-cli/src/main.rs L137-L272

تستخدم بنية الإرسال أجهزة توجيه فرعية صريحة بدلاً من المطابقة الضمنية للمعالجات، مع تقسيم تنفيذات الأوامر حسب منطقة سير العمل. F:crates/arxi-cli/src/main.rs L913-L980 F:crates/arxi-cli/src/commands.rs L19-L29

نموذج دقة وقت التشغيل

تُحل إعدادات وقت التشغيل وفقًا للأولوية:

علامات CLI،
ملف التكوين الاختياري،
الافتراضات.

الإعدادات الافتراضية المهمة:

store_path: arxi.db
recorder_id: arxi-cli
schema_version: المخطط الحالي
auto_seal: لا شيء ما لم يتم تقديم عدد و/أو مدة صريحة
query.limit: الافتراضي 1000، الحد الأقصى 10000
security_profile: secure

نموذج وقت تشغيل الموقّع:

تحميل الموقّع المدرك للملف الشخصي (secure, standard, dev),
افتراضي آمن يتطلب مواد مفتاح مشفرة PKCS#8،
خيار صريح للتقليل من استخدام نص عادي/بذور التطوير في dev,
تم الاحتفاظ ببيانات التعريف الخاصة بالدوران (store_meta) مع فحوصات الاتساق.

F:crates/arxi-cli/src/main.rs L102-L126 F:crates/arxi-cli/src/support/runtime.rs L20-L122 F:crates/arxi-cli/src/support/runtime.rs L247-L556

اختيار خلفية المتجر:

file-backed SQLite or in-memory SQLite. SQLite المدعومة بالملفات أو SQLite في الذاكرة. F:crates/arxi-cli/src/support/runtime.rs L124-L179

عمليات العمل

تتوافق سير العمل التمثيلية مباشرة مع معالجات الأوامر:

فتح/تسجيل/إغلاق/حالة/قائمة دورة حياة الجزء،
تسجيل المظاريف مع ملف مرفق ومدخلات base64 مضمنة (record-with-attachments),
explicit key rotation (recorder signer rotate) with deterministic تدوير المفاتيح بشكل صريح (recorder signer rotate) مع إصدار دليل system.adapter.key_rotated المحدد،
استعلامات الظرف المصفاة مع دعم المؤشر،
بناء الحزمة من JSON المحدد، التحقق (اختياريًا مع جذر الثقة)، والتفتيش،
توليد/تحقق من توقعات العقد (contract generate|check),
إدخال نص قرار البوابة / تثبيت حزمة التشغيل من خلال محول الإنتاج.

F:crates/arxi-cli/src/commands/recorder.rs L20-L524 F:crates/arxi-cli/src/commands/query.rs L20-L88 F:crates/arxi-cli/src/commands/bundle.rs L20-L170 F:crates/arxi-cli/src/commands/admin.rs L20-L194

تغطي اختبارات التكامل سير العمل الأساسي وحالات الفشل المغلقة. F:crates/arxi-cli/tests/commands.rs L78-L191 F:crates/arxi-cli/tests/commands.rs L193-L219

نموذج الإخراج والتعريب

أوضاع الإخراج:

--json: حمولات هيكلية حتمية للأتمتة،
وضع النص: رسائل مشغل محلية.

عقد استعلام وضع JSON الآن يصدر:

{"envelopes": [...], "next_cursor": ..., "applied_limit": ...}.

فشل وضع JSON يصدر غلافًا حتميًا:

{"error": "<message>"}.

حل مشكلة اللغة:

--lang يتجاوز ARXI_LANG,
اللغات المدعومة: en, ca,
الرجوع إلى الإنجليزية عند فقدان المفاتيح.

F:crates/arxi-cli/src/main.rs L102-L103 F:crates/arxi-cli/src/support/util.rs L19-L31 F:crates/arxi-cli/src/support/util.rs L301-L345 F:crates/arxi-cli/src/i18n.rs L26-L63 F:crates/arxi-cli/src/i18n.rs L336-L356

حدود الإدخال الصعبة وسلوك الفشل المغلق

تفرض واجهة سطر الأوامر قراءات ملفات محدودة:

config: 1 ميغابايت,
payload JSON: 4 ميغابايت,
ملف المرفق/حمولة مضمنة: 16 ميغابايت,
JSON بوابة القرار: 8 ميغابايت،
محدد JSON: 1 ميغابايت,
حزمة JSON: 32 ميغابايت،
trust-root JSON: 1 ميغابايت,
ملف مفتاح الموقّع: 64 KiB,
مادة عبارة مرور الموقّع: 1 KiB.

F:crates/arxi-cli/src/main.rs L108-L123

يتم رفض المدخلات الكبيرة قبل التحليل/المعالجة. F:crates/arxi-cli/src/support/util.rs L225-L277

bundle verify يمكنه تحميل جذر ثقة صريح وتوجيهه إلى Verifier::with_trust_root، مما يمكّن من إجراء فحوصات سياسة ثقة التوقيع داخل واجهة سطر الأوامر. F:crates/arxi-cli/src/commands/bundle.rs L74-L116

تغطية اختبار النظام الآن تتحقق من:

رفض إدخال الجذر الثقة/الحزمة/المحدد/التكوين الكبير الحجم،
رفض إدخال مفتاح/عبارة مرور كبيرة الحجم للموقعين،
سلوك فشل معرف غير صحيح مغلق بدون تغيير في المسجل،
التحقق من صحة شكل معرف المسجل في وضع JSON config validate,
مدة الإغلاق التلقائي وسلوك دورة الحياة المدمجة عبر سير العمل الحقيقي لـ CLI،
record-with-attachments success roundtrip and hostile-input fail-closed record-with-attachments سلوك نجاح جولة العودة وفشل الإدخال العدائي مع عدم وجود تغيير في المسجل،
query JSON pagination contract (applied_limit + next_cursor) and استعلام عن عقد ترقيم JSON (applied_limit + next_cursor) وحواجز الفشل المغلقة عند تجاوز الحد،
سلوك نجاح ingest-fixture في بوابة القرار وسلوك الفشل الصارم في عدم التطابق،
تنفيذ سياسة ملف الموقّع الآمن (رابط رمزي + أذونات)،
استرداد دوران الموقّع وسلوك الفشل المغلق للبيانات الوصفية التالفة،
رفض الجذر الناتج عن ارتباط CLI للعقد،
hostile bundle-verify parse-boundary rejection for invalid attachment content type. F:system-tests/tests/suites/operations.rs L238-L570 F:system-tests/tests/suites/recorder.rs L333-L678 F:system-tests/tests/suites/security.rs L267-L1024 F:system-tests/tests/suites/integration_decision_gate.rs L935-L1161

دلالات رمز الخروج

تعود أخطاء الأوامر العامة برمز الخروج 1 عبر emit_error.
JSON-mode command errors still return exit code 1 with machine-parseable لا تزال أخطاء أوامر وضع JSON تعيد رمز الخروج 1 مع حمولة قابلة للتحليل بواسطة الآلة {"error": ...}.
bundle verify يُرجع رمز الخروج 2 عندما تكون حالة الحكم غير صالحة.

F:crates/arxi-cli/src/support/util.rs L343-L345 F:crates/arxi-cli/src/commands/bundle.rs L112-L114

مرجع متقاطع لكل ملف

المنطقة	الملف	الملاحظات
إدخال CLI وتوجيهه	`crates/arxi-cli/src/main.rs`	نموذج Clap، تدفق الإعداد/التهيئة، توجيه التوزيع على المستوى الأعلى.
معالجات الأوامر	`crates/arxi-cli/src/commands.rs`	تجميع وحدات معالجة مجموعة الأوامر.
معالجات المسجل	`crates/arxi-cli/src/commands/recorder.rs`	عمليات الشريحة/المغلف ومنطق تدوير الموقّع.
معالجات الاستعلام والحزمة	`crates/arxi-cli/src/commands/query.rs`, `crates/arxi-cli/src/commands/bundle.rs`	مرشحات الاستعلام وعمليات بناء/تحقق/فحص الحزمة.
معالجات الإدارة	`crates/arxi-cli/src/commands/admin.rs`	التحقق من الإعداد، تشخيص الطبيب، أوامر العقد.
مساعدات وقت التشغيل والأدوات	`crates/arxi-cli/src/support.rs`, `crates/arxi-cli/src/support/runtime.rs`, `crates/arxi-cli/src/support/util.rs`	حل وقت التشغيل، سياسة الموقّع، التحليل، الإدخال/الإخراج المحدود، مساعدات الإخراج.
كتالوج i18n	`crates/arxi-cli/src/i18n.rs`	حل الموقع وبنية قوالب الرسائل.
اختبارات تكامل CLI	`crates/arxi-cli/tests/commands.rs`	تغطية سير العمل من البداية إلى النهاية لسمات CLI.
تكامل مولد العقد	`crates/arxi-contract/src/lib.rs`	سلطة الأثر الناتج المحدد التي تستهلكها أوامر عقد CLI.
مجموعة عمليات اختبار النظام	`system-tests/tests/suites/operations.rs`	يتحقق من توافق فحوصات التحقق من الإعداد وسلوك ترقيم/حد JSON للاستعلام.
مجموعة مسجل اختبار النظام	`system-tests/tests/suites/recorder.rs`	يتحقق من عدد/مدة الإغلاق التلقائي وسلوك دورة الحياة المجمعة وسجل التسجيل.
مجموعة أمان اختبار النظام	`system-tests/tests/suites/security.rs`	يتحقق من سلوك حدود CLI المغلقة عند الفشل عبر الحدود، عدائية المرفقات، سياسة الموقّع، استرداد التدوير، سلامة مسار العقد، ومدخلات الحزمة العدائية.
مجموعة CLI لبوابة القرار لاختبار النظام	`system-tests/tests/suites/integration_decision_gate.rs`	يتحقق من نجاح إدخال ملحق CLI لمحول الإنتاج وسلوك عدم التطابق الصارم.