ساخت Environment
فضای مستقلی که کاربر وارد آن میشود. میتواند فقط رابط سهبعدی داشته باشد یا به بکاند ناشر متصل شود؛ frontend آن بهصورت bundle تغییرناپذیر بازبینی و منتشر میشود.
نتیجه و حالتهای قابل ساخت
در پایان یک Environment منتشرشده با bundle تغییرناپذیر و اثبات ورود یک consumer مستقل دارید.
- frontend-only: صحنه، SDK، Runtime و Presence بدون سرویس ناشر
- with-backend: همان Environment بههمراه backend متعلق به ناشر برای داده و منطق دامنه
جزئیات، نمونهها و قراردادهای کامل: راهنمای انسانی این محصول
پیشنیازهای دادهمحور
- وضعیت
- مسیر CLI آماده؛ گواهی Agent در انتظار
- زمان تقریبی
- ساخت اولیه: حدود ۱۰ دقیقه (وابسته به پروژه)
- CLI دقیق
npx @al-amr/cli@0.1.0-alpha.7
میتوانید همین حالا پروژه را با CLI عمومی بسازید و تا ارسال به بازبینی جلو بروید. این وضعیت به معنی فعالبودن Agent index و Context Pack رسمی نیست؛ آن دو پس از ترفیع Release Set فعال میشوند. زمان بالا فقط برای ساخت اولیه است، نه میزبانی و بازبینی نهایی.
شروع با AI
این دکمه یک پرامپت کامل با فرمان نسخهدار، راهنمای انسانی و توقفهای اجباری کپی میکند. Agent باید بداند Context Pack رسمی هنوز گواهی نشده است و نباید آن را فعال فرض کند.
شروع دستی
npx @al-amr/cli@0.1.0-alpha.7 create environment my-world --yes --jsonفایلها و ساختار پروژهٔ ایجادشده
- al-amr.environment.json — هویت، نسخهٔ bundle، قابلیتها و Pluginهای موردنیاز
- .al-amr/project.json — پیوند محلی غیرمحرمانه با Project و آخرین handoff؛ نه محل نگهداری token
- src/App.tsx — صحنه داخل AlAmrRuntimeGate و مرز رسمی Runtime
- dist/index.html — سند ورودی bundle بههمراه assetها و کاور اعلانشده
- packages/backend — فقط در نوع with-backend و خارج از اختیار Registry برای دادهٔ دامنه
جزئیات، نمونهها و قراردادهای کامل: راهنمای انسانی این محصول
تعریف Done محلی
ابتدا package manager ثبتشده در package.json پروژه را برای نصب dependencyها و اجرای scriptهای typecheck،build و test بهکار ببر؛ از وجود یک manager سراسری حدس نزن.
npx @al-amr/cli@0.1.0-alpha.7 validate --cwd my-world --json- manifest معتبر است و هیچ workspace dependency یا مسیر خصوصی monorepo ندارد.
- typecheck و build موفقاند و نخستین frame در WebGPU یا fallback پشتیبانیشده render میشود.
- Runtime gate حفظ شده، Widget داخل bundle mount نشده و هیچ token یا callback مرورگری به frontend سپرده نشده است.
- خروجی build شامل index.html و کاور bundle است و entry.version با همین نسل بایتها همخوان است.
اتصال حساب و پروژه
- در همان دایرکتوری پروژه، device login را آغاز کن و کد و URL را به مالک انسانی نشان بده.
- پس از تأیید انسانی، فقط resumeCommand برگشتی را اجرا کن؛ کد دستگاه را حدس یا بازتولید نکن.
- پروژه را link کن؛ Registry شناسهٔ پایدار asset و Project را صادر و manifest را همگام میکند.
- با status مالکیت، target و allowedActions را بخوان؛ Console و CLI از همان Management API استفاده میکنند.
npx @al-amr/cli@0.1.0-alpha.7 login --device --json
# سپس resumeCommand دقیق خروجی را اجرا کن
npx @al-amr/cli@0.1.0-alpha.7 link --yes --json
npx @al-amr/cli@0.1.0-alpha.7 status --json --non-interactiveحساب، نقشها، انتقال مالکیت و tokenهای CI در راهنمای حساب و پروژه توضیح داده شدهاند.
میزبانی یا نیازمندیهای artifact
- خروجی کامل frontend را با index.html و assetهای نسبی در پوشهٔ build نگه دار؛ مسیر پیشفرض dist است.
- برای پیشنمایش، alamr dev همان بایتها را در کلاینت دسکتاپ باز میکند؛ Environment ناشر-hosted نیست.
- alamr test پوشهٔ build را قطعی pack میکند، SHA-512 میگیرد و bundle تغییرناپذیر را در Managed Store بارگذاری میکند.
- backend اختیاری را ناشر deploy و نگهداری میکند؛ رازها هرگز وارد manifest یا فایل عمومی نمیشوند.
تست و ارسال برای بازبینی
- با package manager ثبتشده build بگیر و کاملبودن dist/index.html و کاور را بررسی کن.
- alamr test --bundle dist همان بایتها را در یک عملیات pack، upload و بررسی میکند.
- فقط bundle بررسیشده را برای review ارسال کن و status را از Registry بخوان.
- نتیجهٔ ساختیافته و digestهای bundle را نگه دار؛ متن آزاد مبنای اتوماسیون نیست.
npx @al-amr/cli@0.1.0-alpha.7 build --json
npx @al-amr/cli@0.1.0-alpha.7 test --bundle dist --json --visibility unlisted --channel preview
npx @al-amr/cli@0.1.0-alpha.7 publish --yes --json
npx @al-amr/cli@0.1.0-alpha.7 status --json --non-interactiveماشین وضعیت و digestها: چرخهٔ انتشار
بازبینی انسانی
- بازبین مستقل snapshot، یکپارچگی bundle، disclosureها، Plugin lock و artifactهای backend را میبیند.
- مالک، submitter و همان reviewer نمیتوانند خودبازبینی یا انتشار نهایی انجام دهند.
- پس از تأیید، ادمین انتشار action مجازِ Registry را برای digest بررسیشده اجرا میکند؛ پنجرهٔ preview یا heartbeat بعدی وجود ندارد.
بازبین باید از حساب مستقل، inspection تازه و snapshot/artifact digest دقیق استفاده کند؛ راهنمای کامل در بازبینی انسانی است.
انتشار و اثبات مصرف
- ادمین انتشار فقط action مجازِ برگشتی از Registry را روی digest تأییدشده اجرا میکند.
- پس از publication، ورود یک مصرفکنندهٔ مستقل به همان revision باید اثبات شود.
- قرارگرفتن در Hub خودکار نیست؛ ادمین در عملیاتی جدا یک slot دستی را set میکند و بعداً میتواند clear کند.
Hub placement یک عملیات دستی، audited و قابل clear کردن است.
خطاهای رایج با کد پایدار و رفع خطا
خطاها با کد پایدار در مرجع خطاها و شرح گامهای این محصول در راهنمای انسانی آمده است.
ادامه و پاکسازی
- تغییر manifest یا بایتهای build بعد از test یعنی entry.version و revision تازه؛ snapshot منجمد را بازنویسی نکن.
- اگر bundle ناقص یا integrity متفاوت است، build را اصلاح و alamr test را برای نسل تازه دوباره اجرا کن.
- برای محیط آزمایشی، Hub placement را پس از اثبات پاک کن؛ publication immutable را حذف یا دستکاری نکن.
از روی status و کد پایدار ادامه بده: راهنمای بازیابی. برای خطای ناشناخته ابتدا JSON همان شکست را بدون حذف diagnosticها حفظ کن.