Blender Headless Automation

1. مسئلهٔ واقعی: Headless بودن مساوی قطعی‌بودن نیست

اجرای Blender با --background رابط گرافیکی را حذف می‌کند، اما به‌تنهایی اثبات نمی‌کند که job قابل‌تکرار، امن یا حتی موفق بوده است. یک اجرای قابل اتکا باید دقیقاً بداند کدام build از Blender، کدام فایل .blend، کدام اسکریپت، کدام assetها، کدام scene/frame/engine و کدام سیاست اجرای کد استفاده شده‌اند. خروجی این درس Blender Headless Job Contract & Render Evidence Record v1 است؛ رکوردی که launch، termination و اعتبار artifact را سه مرحلهٔ جدا می‌بیند.

2. مرز درس و non-goalها

اینجا مدل‌سازی سه‌بعدی، نورپردازی، rigging، animation یا انتخاب هنری موتور رندر را آموزش نمی‌دهیم. فرض این است که task هنری از قبل مشخص شده و مسئله، خودکارسازی محدود و قابل ممیزی آن است. همچنین این درس render farm و scheduler را طراحی نمی‌کند و خروجی ComfyUI را دوباره تعریف نمی‌کند. سؤال ما ساده است: «آیا این job مشخص با input و policy مشخص اجرا شد و artifact مورد انتظار واقعاً تولید و تأیید شد؟»

3. مدل شواهد سه‌مرحله‌ای

سه checkpoint را قاطی نکنید. Qualification می‌پرسد job مجاز و قابل اجرا هست یا نه؛ Execution می‌پرسد process چگونه خاتمه یافته؛ Artifact Validation می‌پرسد فایل مورد انتظار وجود دارد و با digest/metadata قرارداد تطابق دارد یا نه. exit code = 0 فقط درباره process evidence است. حتی پس از exit موفق، artifact می‌تواند مفقود، اشتباه، stale یا متعلق به scene/frame دیگری باشد.

4. هویت job و pin کردن Blender

هر job باید job_id، نسخه Blender، build identity و مسیر executable را ثبت کند. نام کلی «Blender 4.5» برای بازتولید کافی نیست اگر build یا بسته‌بندی متفاوت باشد. contract باید فرق «نسخه اعلامی» و «build مشاهده‌شده» را حفظ کند. اگر build مورد انتظار قابل اثبات نیست، نتیجه UNKNOWN یا BLOCKED است؛ نباید با حدس نسخهٔ نزدیک را معادل گرفت.

5. Bind کردن .blend، اسکریپت و assetها

فایل .blend و اسکریپت automation هر دو input هستند و باید با digest شناخته شوند. assetهای خارجی—texture، cache، linked library، font یا هر dependency دیگر—باید در یک asset manifest قابل بررسی باشند. filename یا path به‌تنهایی identity نیست. اگر digest تغییر کند، job جدید به evidence جدید نیاز دارد؛ موفقیت نسخه قبلی به bytes جدید منتقل نمی‌شود.

6. ترتیب آرگومان‌های CLI بخشی از contract است

Blender آرگومان‌ها را به ترتیب دریافت‌شده اعمال می‌کند و بارگذاری فایل .blend می‌تواند بعضی settingهای قبلی را جایگزین کند. بنابراین فرمان را به‌صورت یک آرایهٔ ترتیبی ذخیره کنید، نه صرفاً مجموعه‌ای از flagها. برای رندر، -f یا -a باید بعد از settingهای لازم بیاید. تغییر ترتیب، حتی با همان tokenها، می‌تواند job مؤثر را عوض کند.

7. Background mode و اجرای اسکریپت

الگوی مستند برای automation غیرتعاملی استفاده از blender --background ... --python script.py است. Background mode فقط surface اجرایی بدون UI را فراهم می‌کند. اسکریپت باید ورودی‌هایش را صریح بخواند، از state پنهان desktop فرض نگیرد، و نتیجهٔ قابل مشاهده بسازد: log، فایل خروجی یا metadata قابل بررسی. وابستگی به کلیک‌های UI یا preferenceهای نامعلوم، job را شکننده می‌کند.

8. Auto-exec یک تصمیم اعتماد مستقل است

فایل .blend می‌تواند driver یا scriptهایی داشته باشد که اجرای خودکارشان مهم است. Blender برای CLI کنترل --enable-autoexec و --disable-autoexec دارد. policy باید پیش از launch مشخص کند آیا embedded code لازم است و source آن trusted است یا نه. اگر job به embedded code نیاز دارد ولی provenance مورد اعتماد نداریم، نتیجه باید BLOCKED باشد؛ فعال‌کردن auto-exec برای عبور از خطا، evidence نیست.

9. Scene، frame، engine و output را صریح کنید

Contract باید scene، frame یا frame range، render engine، output path و output format را ثبت کند. به setting داخل .blend فقط وقتی تکیه کنید که digest آن فایل دقیقاً bind شده و policy اجازه دهد. اگر output path بیرون از workspace کنترل‌شده است، normalization و permission آن را بررسی کنید. اگر frame 42 خواسته شده، وجود هر PNG دیگری موفقیت محسوب نمی‌شود.

10. Environment و external dependencyها

Working directory، متغیرهای محیطی مرتبط، asset roots، OpenColorIO config و resource limitهای مهم باید یا pin شوند یا صریحاً خارج از ادعا قرار بگیرند. هر چیز محیطی که می‌تواند نتیجه را عوض کند باید در environment manifest دیده شود. اگر asset ضروری مفقود است، launch نکردن بهتر از تولید artifact ناقص و بعدیِ غیرقابل تشخیص است.

11. Timeout، resource bound و process evidence

هر job باید timeout مشخص و termination reason داشته باشد. stdout و stderr را به‌عنوان evidence نگه دارید و exit code را ثبت کنید. timeout با nonzero exit یکی نیست و هر دو با BLOCKED پیش از launch فرق دارند. این تفکیک برای retry، debugging و audit مهم است. retry نیز باید idempotency key داشته باشد تا تکرار ناخواستهٔ خروجی‌ها یا هزینه‌ها رخ ندهد.

12. Artifact validation یک مرحلهٔ مستقل است

پس از process success، وجود فایل، digest، ابعاد، فرمت و metadata مورد انتظار را بررسی کنید. می‌توانید برای PNG ابعاد و format را از metadata بخوانید، برای فایل .blend یا export نیز contract مخصوص داشته باشید. artifact_exists = true کافی نیست. اگر process exit=0 باشد ولی فایل مورد انتظار وجود نداشته باشد، حالت درست OUTPUT_VALIDATION_FAILED است.

13. ماشین حالت پیشنهادی

پیش از launch، policy یا input نامعتبر → BLOCKED. زمان تمام‌شده → TIMEOUT. process با exit غیرصفر → EXECUTION_FAILED. process کامل ولی artifact مفقود/نامنطبق → OUTPUT_VALIDATION_FAILED. فقط وقتی qualification، execution و artifact validation همه پاس شوند → VERIFIED_RESULT. اگر evidence کافی ندارید، UNKNOWN را نگه دارید و success نسازید.

14. مثال کاری و ضدنمونه‌ها

Baseline: Blender 4.5 LTS/build مشخص، scene-v12.blend و render.py با digest ثبت‌شده، scene=Product، frame=42، output PNG با ابعاد مورد انتظار، asset manifest کامل، auto-exec خاموش و timeout=240s. ضدنمونه ۱: output flag قبل از load فایل قرار گرفته و با load بازنویسی می‌شود؛ job باید بازسازی شود. ضدنمونه ۲: embedded driver لازم است ولی source مورد اعتماد نیست؛ launch مجاز نیست. ضدنمونه ۳: exit=0 ولی PNG هدف وجود ندارد؛ success ممنوع است.

15. Transfer و چک‌لیست نهایی

در transfer، source جدید به driver تأییدشده نیاز دارد و output path هم تغییر کرده است. فقط پس از binding digestهای جدید، ثبت provenance trusted، فعال‌کردن auto-exec تحت policy صریح و اعمال output setting بعد از load می‌توان job را qualified کرد. سپس process و artifact را جدا validate کنید. چک‌لیست: build pinned؟ input digestها bind؟ asset manifest کامل؟ CLI order صریح؟ trust policy روشن؟ timeout/logها ثبت؟ artifact digest/metadata تأیید؟ فقط در این صورت handoff به downstream مجاز است.