راهنمای کاربر ZIAForge

گام‌های نخست

سیستم ZIAForge گفتگو، برنامه‌ریزی، اجرا و راستی‌آزمایی را در یک تسک نگه می‌دارد. Code را برای یک پروژه Git، یا Work را برای اسناد، تحقیقات و سایر نتایج در یک پوشه معمولی انتخاب کنید.

با یک تسک کوچک در یک پروژه مجزا شروع کنید. اگر یک CLI بومی انتخاب می‌کنید، ابتدا آن را نصب کرده و با حساب خودش در یک ترمینال وارد شوید. روش دیگر، پیکربندی اتصال API است. اشتراک CLI و یک API پولی روش‌های اتصال مجزا هستند؛ ZIAForge شما را وارد حساب نمی‌کند و اعتبارات را بین آنها منتقل نمی‌سازد.

1. بخش Settings را باز کرده و پوشه فضای کاری و زبان را بررسی کنید. بخش About مشخصات دقیق نسخه در حال اجرا را نشان می‌دهد.
2. برای Code، یک مخزن Git در نوار کناری اضافه کنید. برای Work، هنگام ایجاد تسک یک پوشه مجزا انتخاب کنید.
3. یک پیش‌تنظیم با CLI، مدل، تلاش استدلال و سطح دسترسی ذخیره کنید. همچنین می‌توانید مستقیماً Custom را بدون پیش‌تنظیم ذخیره‌شده انتخاب کنید.
4. یک تسک ایجاد کنید، مسیر، نقش‌ها و پیشروی دستی یا خودکار آن را انتخاب نمایید. قبل از Start انتخاب‌ها را بازبینی کنید.

دستورالعمل‌های مرتبط: مرور کلی پروژه · سازگاری ارائه‌دهنده.

نصب بسته دسکتاپ مناسب

بسته‌ای متناسب با سیستم‌عامل و معماری CPU خود انتخاب کنید: x64 یا arm64. پایپ‌لاین ساخت می‌تواند فرمت‌های macOS DMG/ZIP، Windows نصب‌کننده NSIS/ZIP، و Linux DEB/RPM/AppImage/tar.gz/ZIP را تولید کند. یک فایل تولیدشده یا ساخت متقابل (cross-build) اثباتی بر موفقیت‌آمیز بودن نصب‌کننده و UI بومی روی سیستم شما نیست؛ به گزارش راستی‌آزمایی آن انتشار رجوع کنید.

ساخت‌های macOS با استفاده از Electron 44 به macOS 13 یا بالاتر نیاز دارند. از بسته arm64 در اپل سیلیکون و از بسته x64 برای اینتل استفاده کنید. قبل از جایگزینی، برنامه قدیمی‌تر را کاملاً ببندید. بسته‌های پیش‌نمایش ممکن است بدون امضا و فاقد تأیید نوتاریزه (notarized) باشند؛ یک آرتیفکت در حال توسعه را با یک نسخه منتشرشده امضاشده عمومی اشتباه نگیرید.

پلتفرم Windows به سیستم‌عاملی نیاز دارد که توسط نسخه همراه Electron پشتیبانی شود و Git در PATH در دسترس باشد. معماری منطبق را انتخاب کنید. پیش‌نمایش بدون امضا فاقد گواهی Authenticode است. یک نسخه پرتابل ZIP باید کل دایرکتوری برنامه و فایل‌های زمان اجرا را حفظ کند، نه فقط فایل اجرایی آن را.

سیستم Linux به یک محیط دسکتاپ گرافیکی سازگار، کتابخانه‌های سیستمی مورد نیاز توسط Electron، و Git نیاز دارد. برای اعتبارات کنترل رمزگذاری‌شده، یک Secret Service فعال مانند gnome-libsecret یا KWallet فراهم کنید؛ بک‌اند ناامن basic_text پذیرفته نمی‌شود. شواهد تست دود (smoke) بدون واسط گرافیکی/کانتینری، هر دسکتاپ یا توزیعی را تأیید نمی‌کند.

یک DEB را با apt install ./file.deb نصب کنید، یا یک RPM را از طریق مدیر بسته توزیع خود نصب نمایید. یک AppImage به مجوز اجرایی و پشتیبانی مناسب FUSE نیاز دارد؛ --appimage-extract-and-run در صورت پشتیبانی یک گزینه جایگزین است. بسته‌های tar.gz و ZIP را همراه با تمام فایل‌های زمان اجرای آنها استخراج کنید. هنگام جایگزینی یک بسته، داده‌های کاربر و فایل‌های برنامه را مجزا نگه دارید.

برای ساخت از مبدأ (سورس)، از Node نسخه 24، Git و npm ci، از جمله نصب‌کننده استاندارد Electron استفاده کنید. بازسازی‌های بومی نیاز به ابزارهای پلتفرم دارند: ابزارهای خط فرمان Xcode در macOS؛ MSVC C++، Windows SDK و پایتون در Windows؛ کامپایلر، make، پایتون، pkg-config و ابزارهای بسته‌بندی لازم در Linux. برای دستورات دقیق و محدودیت‌های فعلی پلتفرم، از PLATFORM_BUILDS.md پیروی کنید.

نسخه‌های انتشار به‌طور متمرکز رزرو شده و خروجی‌ها غیرقابل تغییر هستند. یک ساخت راستی‌آزمایی CI یک نصب‌کننده منتشرشده نیست. آرشیوهای سورس حاوی کد منبع، فایل قفل (lockfile)، مستندات و اسکریپت‌ها هستند؛ وابستگی‌ها، اعتبارات، پروفایل‌های کاربری و تحقیقات خصوصی حذف شده‌اند. هرگز از یک ساخت موفق x64 اعتبارسنجی بومی ARM یا Windows را استنباط نکنید.

دستورالعمل‌های مرتبط: بسته‌های پلتفرم، پیش‌نیازها و محدودیت‌های راستی‌آزمایی · شناسه ساخت و بررسی‌های انتشار.

Code: پنج مسیر

حالت Auto محدوده را ارزیابی می‌کند: یک پرسش ساده ممکن است با یک پاسخ تمام شود، در حالی که یک تسک بزرگ‌تر نیاز به آماده‌سازی دارد. گزینه Fix a bug علت را بررسی کرده و یک اصلاحیه آماده می‌کند. مسیر Spec first با راه‌حل فنی آغاز می‌شود؛ مسیر Requirements first با نیازمندی‌ها و معیارهای پذیرش شروع می‌شود.

مسیر Multi-model از زمینه‌های متنی جداگانه برای کاوش، طراحی، پیاده‌سازی و بازبینی استفاده می‌کند. نام این مسیر نیازمند ارائه‌دهندگان متفاوت نیست: هر نقش از پیش‌تنظیم یا پیکربندی Custom که شما انتخاب می‌کنید استفاده می‌کند.

یک Worktree تغییرات Git یک تسک را ایزوله می‌کند. حالت Branch درون checkout انتخاب‌شده کار می‌کند. پروژه، شاخه و مدل را پیش از شروع بررسی کنید؛ شرح تسک علاوه بر این به گفتگوی عادی ارسال نمی‌شود.

برای ایده‌ای با انتخاب‌های فنی یا محصولی حل‌نشده، از Requirements first استفاده کرده و پایه کار را در گفتگو بسازید. Auto درخواست را طبقه‌بندی می‌کند؛ این فرمانی برای پیاده‌سازی فوری هر عبارت کوتاه نیست. گزینه Save draft درخواست را بدون تماس با مدل نگه می‌دارد؛ Start جریان مدیریت‌شده را یک‌بار ذخیره و راه‌اندازی می‌کند. یک تا چهار نسخه کپی‌شده از تسک، شناسه‌های ایجاد و تنظیمات نقش مستقل دارند.

دستورالعمل‌های مرتبط: قرارداد جریان کار Code · پروفایل‌های پرامپت Code.

گفتگوی Forge

دکمه Start گفتگوی مرکزی را باز می‌کند. به‌طور طبیعی پاسخ دهید، سوالات متقابل بپرسید، محدودیت‌ها را اضافه کنید و درباره انتخاب‌های فنی بحث نمایید. مکالمه و پرسش‌ها همراه تسک باقی می‌مانند.

ارسال متن، سندی را نمی‌پذیرد یا برنامه پیاده‌سازی جدیدی را مجاز نمی‌سازد. شفاف‌سازی در حین اجرا ابتدا نوبت مدیریت‌شده را متوقف کرده و محدوده تحت‌تأثیر را دوباره بررسی می‌کند. پاسخ به یک پرسش درون یک مرحله از قبل پذیرفته‌شده می‌تواند همان مرحله را ادامه دهد.

برای بازنگری عامدانه پایه کار، نیازمندی‌ها (Requirements)، مشخصات (Specification) یا برنامه‌ریزی (Planning) را انتخاب کنید. یک نسخه جدید مستلزم پذیرش مجدد تصمیم‌های وابسته است. مراحل تکمیل‌شده و شواهد آن‌ها باقی می‌مانند؛ فازهای ناتمام جایگزین‌شده در تاریخچه می‌مانند.

جلسات فازهای مدیریت‌شده با گفتگوی آزاد متفاوت هستند. به‌جای ارسال مستقیم پرامپت‌های دستی به یک جلسه تحت مالکیت جریان کار، از گفتگوی Forge استفاده کنید.

دستورالعمل‌های مرتبط: قرارداد گفتگوی Forge.

اسناد و تصمیم‌ها

سندی را باز کنید، نسخه آن را بررسی کنید و در صورت نیاز تغییرات اعمال نمایید. ارسال ویرایش‌ها از طریق گفتگو نسخه جدیدی ایجاد می‌کند؛ گزارش‌ها و نتایج تأییدشده عطف به ماسبق بازنویسی نمی‌شوند.

پیش از پذیرش یک برنامه پیشنهادی، ترتیب، دستورالعمل‌ها، معیارهای پذیرش و دستورات راستی‌آزمایی را ویرایش کنید. دستورات ملموسی را تأیید کنید که درک می‌کنید: آنها در پوشه تسک اجرا می‌شوند. حالت Multi-model یک مرحله پیاده‌سازی برای کل تسک را پیشنهاد می‌دهد، همراه با جزئیات در اسناد و دستورالعمل‌های آن.

گزینه Approve یک تصمیم عامدانه و مجزا است. Auto پرسش‌ها یا پذیرش نیازمندی‌ها، مشخصات و برنامه‌ها را دور نمی‌زند. سندی که به‌صورت خارجی تغییر یافته باشد نمی‌تواند از تأییدیه قدیمی استفاده کند.

فایل‌های آماده‌سازی به‌عنوان آرتیفکت ظاهر می‌شوند. نسخه، فاز تولیدکننده و هش آن‌ها، این فایل‌ها را به یک نتیجه پیوند می‌دهد. اسناد Code خارج از worktree نگهداری می‌شوند و به‌طور خودکار وارد کامیت نمی‌شوند.

پیش از پذیرش، هم سند و هم تصمیمِ نمایش‌داده‌شده را بررسی کنید. پذیرش، گیت فعلی ID، بازبینی برنامه و هش اسناد نگه‌داری‌شده را مقید و متعهد می‌سازد. در صورت نادرست بودن محدوده یا شواهد، Request changes را انتخاب کنید. اگر یک تصمیم منسوخ شد، قبل از گرفتن تصمیم جدید، وضعیت ذخیره‌شده را دوباره بارگیری کنید؛ یک فایل تغییریافته را نمی‌توان تحت نسخه قبلی پذیرفت.

دستورالعمل‌های مرتبط: گیت‌های جریان کار و نسخه‌های اسناد.

اجرا و بازبینی

بخش To-do مراحل واقعی، تلاش جاری، نتایج راستی‌آزمایی و بازبینی را نشان می‌دهد. اینکه یک ایجنت بگوید «انجام شد» یک مرحله را تکمیل نمی‌کند: شواهد مورد نیاز برنامه باید وجود داشته باشند.

حالت Manual بین مراحل واجد شرایط مکث می‌کند. Auto مراحل تأییدشده را پیش می‌برد و اجازه تلاش مجدد محدود را می‌دهد. گزینه Stop after همیشه یک چک‌پوینت ایجاد می‌کند. دستور Pause کار فعال جریان کار را متوقف می‌کند؛ بستن یک پنل آن را متوقف نمی‌سازد.

یک بازبین مستقل از یک زمینه جداگانه همراه با فایل‌ها و نتایج راستی‌آزمایی استفاده می‌کند. هر یافته مسدودکننده الزامی باید حل شود؛ بازبین‌های متعدد نمی‌توانند با رأی‌گیری یک خطای مسدودکننده را حذف کنند.

در Multi-model، اصلاح یافته‌ها مستلزم یک تصمیم صریح است. اصلاح به‌طور خاموش بازبینی دیگری را آغاز نمی‌کند: گزینه Review again چرخه جدیدی را باز می‌کند. نظرات بازبینی می‌توانند بدون تکرار پیاده‌سازی، تقاضای تجدید نظر هماهنگ‌کننده را داشته باشند.

مراحل تکمیل‌شده را نمی‌توان به‌طور خاموش ویرایش کرد. در TDD، حالت Red واقعاً باید به دلیل مورد انتظار شکست بخورد، سپس Green باید با موفقیت بگذرد. تلاش‌های محدود از تکرار بی‌نهایت جلوگیری می‌کند.

بازبین‌های مستقل CLI/API را در تنظیمات ← Review teams ذخیره کنید، سپس تیم را در Code یا Work انتخاب نمایید. بازبین‌ها به‌صورت موازی اجرا می‌شوند و سپس معمار گزارش تیم قرار دارد. همچنین می‌توانید بازبین‌های مستقل را بدون تیم ذخیره‌شده پیکربندی کنید. معمار گزارش تنها گزارش‌های ساختاریافته ناشناس دریافت می‌کند، بدون فایل‌های پروژه یا ابزارها؛ این جداسازی در حال حاضر به Claude Code یا API نیاز دارد.

هر مرحله پیاده‌سازی به یک بررسی قابل اجرا، بازبینی مستقل الزامی، یا هر دو نیاز دارد. فازهای آماده‌سازی در عوض نتایج معتبر و رسیدهای آرتیفکت را حفظ می‌کنند؛ این موارد وانمود نمی‌کنند که آزمون‌های پیاده‌سازی اجرا شده‌اند. یک دستور تنها زمانی موفق می‌شود که وضعیت خروج واقعی آن و پاک‌سازی فرایندهای وابسته به آن تأیید شود. بررسی Red برای TDD باید قبل از پیاده‌سازی و تأیید Green به‌طور عادی با شکست مواجه شود؛ فایل اجرایی مفقود یا اتمام مهلت زمانی (timeout)، نتیجه Red معتبر نیست.

فیوزهای قطع خودکار پیش‌فرض پس از سه تلاش ناموفق در یک مرحله یا پنجاه تلاش در مجموع متوقف می‌شوند. ایجاد وقفه یک تلاش را مصرف می‌کند اما به‌خودی‌خود یک تلاش ناموفق به‌شمار نمی‌آید. محدودیت‌ها و شواهد تکمیل‌شده پس از راه‌اندازی مجدد باقی می‌مانند؛ دکمه Retry آن‌ها را بازنشانی نمی‌کند. خطای ثبت‌شده را قبل از اجازه تلاش دیگر مطالعه کنید.

دستورالعمل‌های مرتبط: راستی‌آزمایی و بازبینی.

تیم‌های بازبینی موازی و معمار گزارش

بخش تنظیمات ← Review teams را باز کرده و یک تیم را ذخیره کنید. بازبین‌های مستقل را با CLI یا API، مدل، تلاش استدلال و تخصص خاص خودشان اضافه کنید، سپس یک معمار گزارش انتخاب نمایید. تیم را در پیکربندی بازبینی تسک انتخاب کنید. یک پیش‌تنظیم مجری نیز می‌تواند توسط یک بازبین استفاده شود، و Custom همچنان در دسترس است؛ نقش‌های مستقل کماکان زمینه‌های جداگانه‌ای دارند.

بازبین‌ها به‌طور موازی روی همان شواهد تسک اجرا می‌شوند. هر گزارش الزامی، خطا و حکم نگهداری می‌شود. معمار گزارش، گزارش‌های شماره‌گذاری‌شده ناشناس را بدون نام بازبین، هویت مدل یا ارائه‌دهنده، محتوای اصلی تسک، دسترسی به مخزن یا ابزار دریافت می‌کند. این بخش گزارش‌ها را مقایسه کرده و یک حکم ساختاریافته واحد برمی‌گرداند؛ بازبینی سورس جدیدی انجام نمی‌دهد.

یک یافته مسدودکننده یا رد توسط بازبین الزامی را نمی‌توان با رأی اکثریت یا ترجیح معمار نادیده گرفت. گزارش‌های مفقود یا نامعتبر مانع از تأیید می‌شوند. یافته‌های فردی و تصمیم نهایی تجمیعی را قبل از پذیرش یا تأیید اصلاحات بررسی کنید. یک تیم ذخیره‌شده برای اجرای مربوطه تثبیت و قفل می‌شود؛ ویرایش پیش‌تنظیم آن شواهد تکمیل‌شده را بازنویسی نمی‌کند.

معمار صرفاً مبتنی بر گزارش در حال حاضر از پیکربندی‌های بدون ابزار پشتیبانی‌شده Claude یا API استفاده می‌کند. Codex و Antigravity همچنان به‌عنوان بازبین در دسترس هستند، اما برای این نقش معمارِ ایزوله‌شده تا زمان وجود یک قرارداد بدون ابزار راستی‌آزمایی‌شده رد می‌شوند. یک پرامپت که صرفاً بگوید «بدون ابزار» کافی نیست.

دستورالعمل‌های مرتبط: پیکربندی تیم تایپ‌شده · تجمیع بازبینی.

تخصص‌های ایجنت و سیاست پرامپت

مدل موتور اجرا است؛ تخصص، یک پروفایل دستورالعمل است. None را برای عدم تخصص، Standard را برای راهنمای پیش‌فرض، Auto را برای یک راهنمای توکار مرتبط، یا Manual را برای راهنماهای انتخاب‌شده و دستورالعمل‌های محدود خود انتخاب کنید. پیش‌تنظیم‌ها می‌توانند این انتخاب را حفظ کنند.

کاتالوگ اصلی برنامه‌نویسی عمومی، معماری، امنیت، قابلیت اطمینان، عملکرد، تست و قابلیت استفاده رابط کاربری را پوشش می‌دهد. حالت Auto از متن در دسترس تسک/مرحله برای انتخاب یک راهنما استفاده می‌کند؛ این ویژگی پنهانی مدل دیگری را فراخوانی نکرده یا تخصص را تأیید نمی‌کند. پیشنهادات برنامه‌ریزی را می‌توان قبل از پذیرش برنامه پیاده‌سازی بازبینی و تغییر داد.

تخصص‌های بازبینی به هدایت توجه کمک می‌کنند اما هرگز جایگزین شواهد مستقل، محدودیت‌های دسترسی یا حکم ساختاریافته نمی‌شوند. دستورالعمل‌های سفارشی را به‌عنوان بخشی از محدوده تسک در نظر بگیرید: از آنها برای دور زدن پذیرش اسناد، سیاست ابزار، احراز هویت یا خطاهای بازبین استفاده نکنید.

دستورالعمل‌های مرتبط: کاتالوگ اصلی پرامپت.

Work: از پرسش تا سند

حالت Work نیازی به Git ندارد. گزینه Default یک پوشه تسک مجزا ایجاد می‌کند؛ Custom یک پوشه موجود را از طریق انتخاب‌گر بومی برمی‌گزیند. گزینه Save draft تنظیمات را بدون استنتاج ذخیره می‌کند؛ Start فاز اول را اجرا می‌کند.

حالت Auto مستقیماً پاسخ می‌دهد یا یک برنامه مناسب با To-doهای واقعی پیشنهاد می‌کند. Brainstorm پیش از انتخاب ایده‌های بیشتر یا ارزیابی، ideas.md ایجاد می‌کند. Research نتایج findings.md، منابع و محدودیت‌ها را نگه می‌دارد. Write از مقصود و در صورت سودمندی، outline.md به سمت یک سند توصیفی یا draft.md پیش می‌رود؛ بازنگری‌ها نسخه‌های قبلی را حفظ می‌کنند.

ورودی‌های فایل را از طریق انتخاب‌گر بومی انتخاب کرده و با @ به آن‌ها ارجاع دهید. برنامه آنها را به‌عنوان ورودی‌های تسکِ غیرقابل‌تغییر کپی کرده و صحت شناسه آنها را قبل از اجرا اعتبارسنجی می‌کند. حالت Default یک پوشه تسک تحت مالکیت برنامه ایجاد می‌کند؛ دسترسی به پوشه در Custom یک مجوز ذخیره‌شده مالکیتی است. یک پیش‌نویس ذخیره‌شده و شروع‌نشده می‌تواند پوشه خود را تغییر دهد.

نسخه‌های 1–4 را با تنظیمات مجری مستقل ایجاد کنید. تسک‌هایی که از پوشه‌های هم‌پوشان استفاده می‌کنند نمی‌توانند به‌طور هم‌زمان بنویسند. این هماهنگی برای عملیات ZIAForge اعمال می‌شود، نه برنامه‌های خارجی دلخواه.

بخش Deep Brainstorm به‌طور پیش‌فرض از سه ورکر مستقل استفاده می‌کند و تا هشت ورکر را پشتیبانی می‌نماید. ترتیب و پیکربندی آن‌ها را انتخاب کنید، از جمله استفاده مجدد از یک پیش‌تنظیم در زمینه‌های متنی جداگانه. سوالات ورکرها منشأ خود را حفظ می‌کنند؛ گزارش‌های معیوب یک تلاش برای ترمیم قالب دریافت می‌کنند. شکست جزئی به‌جای اینکه به‌عنوان موفقیت یکپارچه نشان داده شود، قابل مشاهده باقی می‌ماند.

حالت Deep گزارش‌های حفظ‌شده ورکرها را در brainstorm_report.md ترکیب کرده و همیشه تصمیم کاربر را جویا می‌شود. یک پیگیری کوچک گزارش را از طریق هماهنگ‌کننده اصلاح می‌کند؛ یک تغییر عمده دور دیگری از ورکرهای تثبیت‌شده را آغاز می‌نماید. آرتیفکت‌ها نسخه‌های خود را حفظ می‌کنند.

نقش‌های تعیین‌شده در زمان ایجاد تسک یا ذخیره صریح پیش‌نویس تثبیت می‌شوند. پس از اولین فراخوانی، تنها پیشروی خودکار/دستی قابل تغییر است؛ برای تنظیمات مدل یا نقش متفاوت از یک تسک جدید استفاده کنید. ویرایش یک پیش‌تنظیم عمومی به‌طور خاموش فازهای بعدی را تغییر نمی‌دهد.

حالت Manual بین فازهای واجد شرایط، از جمله طرح کلی تفصیلی Write مکث می‌کند. Auto می‌تواند در سراسر آن طرح کلی ادامه دهد. سوالات، برنامه‌های اجرایی پیشنهادی، جهت‌گیری Brainstorm و بازبینی گزارش Deep حتی در Auto نیز تصمیم‌های صریح باقی می‌مانند. یک استناد به‌تنهایی وبگردی را اثبات نمی‌کند، و یک فایل باینری نگه‌داری‌شده به‌تنهایی رندر شدن آن را اثبات نمی‌کند.

دستورالعمل‌های مرتبط: حالت‌ها و تصمیم‌های Work.

پیش‌تنظیم‌ها، مدل‌ها و دسترسی

یک پیش‌تنظیم، یک CLI/API، مدل، تلاش استدلال و مجوزها را ذخیره می‌کند. پاورقی گفتگو دارای بخش‌های پیش‌تنظیم، CLI، مدل و گزینه‌ها است. حالت Custom بدون پیش‌تنظیم کار می‌کند؛ Create preset انتخاب فعلی را ذخیره می‌نماید.

کاتالوگ از CLI یا API نصب‌شده و انتخابی در صورت پشتیبانی به دست می‌آید. Refresh فهرست را بدون تغییر انتخاب به‌روزرسانی می‌کند. اگر شناسایی خودکار در دسترس نیست، یک ID مدل را به‌صراحت وارد کنید؛ ارائه‌دهنده همچنان باید از آن پشتیبانی کند. سطوح استدلال به مدل و CLI بستگی دارند. پیش‌فرض ارائه‌دهنده از توکن صریح none متمایز است.

تغییرات را تنها پس از تأیید بک‌اند اعمال کنید. جابجایی در حین یک نوبت فعال یا صف غیرخالی محدود است. پیش‌نویس‌ها و تاریخچه قابل مشاهده باقی می‌مانند، اما تغییر ارائه‌دهندگان وضعیت داخلی خصوصی آنها را منتقل نمی‌کند.

در Forge، برچسب نقش اهمیت دارد: آماده‌سازی می‌تواند از یک برنامه‌ریز مجزا استفاده کند. پاورقی نقش نمایش‌داده‌شده را تغییر می‌دهد؛ بازبین‌ها و دستیارها در تنظیمات جریان کار انتخاب می‌شوند. خط‌مشی مربوط به پیاده‌سازی از قبل تأییدشده ممکن است قفل باشد.

مجوزها بین ارائه‌دهندگان متفاوت است. گزینه‌های Read only و Workspace write در جایی که آداپتور از آنها پشتیبانی کند در دسترس هستند. Antigravity از تنظیمات بومی CLI یا دسترسی کامل صریحاً انتخاب‌شده استفاده می‌کند. دسترسی کامل یک جعبه شنی (sandbox) نیست.

تخصص‌گرایی راهنمایی‌های پرامپت را اضافه می‌کند، نه یک مدل یا مجوز دیگر. پیش‌تنظیم‌ها و نقش‌ها از گزینه‌های None، Standard، Auto و Manual پشتیبانی می‌کنند. گزینه Auto پروفایل‌ها را از متن مرحله بدون فراخوانی مدل اضافی انتخاب می‌کند؛ حالت Manual تا چهار تخصص و دستورالعمل‌های سفارشی را می‌پذیرد. انتساب‌های پیشنهادی برنامه‌ریز را می‌توان پیش از پذیرش برنامه ویرایش کرد.

یک ID مدل یا تلاش که به‌صورت دستی وارد شده انتخاب شما باقی می‌ماند، اما ارائه‌دهنده ممکن است آن را رد کند. ویرایش یک پیش‌تنظیم عمومی، گفتگوی در حال اجرا یا برنامه پذیرفته‌شده را عطف به ماسبق تغییر نمی‌دهد. برای تغییر عامدانه یک مکالمه بیکار، از کنترل‌های پیکربندی خود آن استفاده کنید و منتظر تأیید بمانید. یک گزینه غیرفعال باید به‌عنوان یک محدودیت قابلیتی یا چرخه حیات درک شود، نه اینکه با ویرایش JSON ذخیره‌شده دور زده شود.

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

گفتگوها، Stop و صف

تب‌های باز، Recent و پیش‌نویس‌ها به یک تسک تعلق دارند. بستن یک تب آن را از Open حذف می‌کند اما آن را در Recent نگه می‌دارد و فرایند ارائه‌دهنده یا جریان کار مدیریت‌شده آن را متوقف نمی‌کند. جستجوی تاریخچه، باز کردن مجدد یک گفتگو یا بستن همه تب‌های اضافی از منوی تاریخچه انجام می‌شود.

دستور Stop نوبت جاری را متوقف می‌کند. قبل از Send بعدی منتظر بمانید تا توقف پایان یابد: تأیید توقف به‌معنای اتمام فرآیند نیست. در این فاصله می‌توانید پیش‌نویس بعدی را تایپ کنید.

در گفتگوی عادی، Queue درخواست بعدی را جدا از پیش‌نویس جاری ذخیره می‌کند. دستور Pause queue ارسال‌های بعدی را متوقف نگه می‌دارد. گزینه‌های Stop و Quit صف را متوقف می‌کنند. پس از راه‌اندازی مجدد، ابتدا Resume و سپس صراحتاً Continue queue را بزنید.

وضعیت Uncertain به این معنی است که وضعیت تحویل نامشخص است. چنین پیامی به‌طور خودکار دوباره ارسال نمی‌شود: تاریخچه را بررسی کنید، در صورت لزوم متن را کپی کنید و مورد درون صف را رد نمایید. ارسال مجدد آن یک درخواست عامدانه و جدید است.

گفتگوهای مراحل مدیریت‌شده از جریان کار خود استفاده می‌کنند، نه از صف عادی. گزینه Follow stage فاز جاری را نشان می‌دهد؛ انتخاب دستی تب دیگر، دنبال کردن را متوقف می‌کند. لاگ‌های CLI موارد تشخیصی را جدا از پاسخ نشان می‌دهند.

پاسخ‌های مارک‌داون عناوین، فهرست‌ها، جدول‌ها، پیوندها و کدهای داخل بلوک را نمایش می‌دهند. کارت‌های ابزار و عیب‌یابی‌های CLI جدا از پاسخ باقی می‌مانند. تفکر گزارش‌شده توسط مدل و معیارهای توکن تنها زمانی ظاهر می‌شوند که ارائه‌دهنده واقعاً آن‌ها را ارائه دهد؛ استدلال خصوصی یا میزان مصرف را از روی انیمیشن استنباط نکنید.

پس از ارسال نامشخص یا تأیید صف، تاریخچه را بررسی کنید و تنها همان درخواستِ ذخیره‌شده را در صورت ارائه‌شدن مجدداً امتحان کنید. رسید صف به این معنی است که ذخیره‌سازی مورد را پذیرفته است، نه اینکه استنتاج پایان یافته است. یک مورد نامشخص درون صف را تنها به‌عنوان یک رد و ابطال صریح حذف کنید؛ این کار نمی‌تواند پرامپتی را که قبلاً تحویل داده شده پس بگیرد.

دستورالعمل‌های مرتبط: صف پیام بادوام.

فایل‌ها، Git و تکمیل

بخش Files پوشه تسک را نشان می‌دهد. نتایج را با نیازمندی‌ها مقایسه کنید، اسناد را باز نمایید و diffها را بررسی کنید. حفظ یک فایل باینری، رندر صحیح در برنامه مقصد آن را اثبات نمی‌کند.

بخش Git وضعیت، تغییرات و عملیات را همراه با نتایج ثبت‌شده ارائه می‌دهد. کامیت، ادغام و push به‌طور پیش‌فرض دستی هستند؛ عملیات خودکار انتخاب‌های جداگانه‌ای برای یک برنامه کاملاً تأییدشده هستند.

بین راستی‌آزمایی و انتشار، فایل‌های کاری را تغییر ندهید: تأییدیه به بایت‌های دقیق وابسته است. تعارض‌ها، pushهای ناموفق و نتایج نامشخص عملیات، پیشرفت را تا زمان تصمیم‌گیری صریح متوقف می‌کنند. Auto به‌طور خاموش اجازه انتشار نمی‌دهد.

حالت Work هیچ شاخه Git ایجاد نمی‌کند و نهایی‌سازی Git ندارد. اسناد مورد نیاز را از پوشه انتخاب‌شده حفظ کنید، از جمله نسخه‌ها و منابع.

ویرایشگر فایل ویژگی‌هایی نظیر هایلایت نحو بر اساس پسوند، جستجو و جایگزینی، تاریخچه undo، شکست خط و پیش‌نویس‌های هر تب را ارائه می‌دهد. ذخیره‌سازی، رمزگذاری‌های پشتیبانی‌شده UTF-8/UTF-16 را حفظ کرده و تعارض‌های تغییر خارجی را رد می‌کند. سایر رمزگذاری‌ها و محتوای باینری به ویرایشگر خارجی نیاز دارند. پیش‌نویس‌های ذخیره‌نشده از خروج (Quit) برنامه جلوگیری می‌کنند تا زمانی که مالک آن‌ها را ذخیره کرده یا دور بیندازد.

هایلایت کامل نحو تا 8 مبی‌بایت فعال است. فایل‌های متنی بزرگ‌تر در پنجره‌های 256 کیبی‌بایتی باز می‌شوند؛ فایل‌های 8 تا 64 مبی‌بایتی را می‌توان صراحتاً به‌طور کامل بدون هایلایت نحو بارگیری کرد. بالای 64 مبی‌بایت از ویرایش پنجره‌ای و جستجوی محدود مسابقه بعدی استفاده کنید. این یک حالت محدود برای فایل‌های بزرگ است، نه برابری کامل با سابلایم تکست برای اسناد در ابعاد دلخواه بزرگ.

گزینه Open folder از زمینه تسک فعلی یا زمینه شاخه/worktree استفاده می‌کند، به‌جای اینکه به‌طور خاموش فقط مخزن اصلی را باز کند. ردیف یک فایل می‌تواند پوشه والد آن فایل را آشکار کند. مسیرها توسط بک‌اند در برابر مجوزهای ثبت‌شده تسک اعتبارسنجی می‌شوند. فایل‌های باینری به‌عنوان متن ساده قابل ویرایش نیستند؛ از نمایشگر مقصد آن‌ها استفاده کنید و بایت‌های اصلی را حفظ نمایید.

حذف Worktree یک اقدام محافظت‌شده و مجزا است. جلسات ساختاریافته و ترمینال‌های متصل را قبل از حذف آن متوقف کنید، از جمله جلساتی که بیکار هستند. نتیجه ذخیره‌شده Git و وضعیت بازیابی را بررسی کنید؛ حذف یک رکورد تسک جایگزینی برای حفظ امن کارهای کامیت‌نشده نیست.

دستورالعمل‌های مرتبط: قرارداد ویرایشگر تایپ‌شده · سیاست‌های Git.

اتصالات API

بخش اتصالات، یک نقطه پایانی (endpoint) سازگار با OpenAI را که صراحتاً انتخاب شده اضافه می‌کند. نام، URL پایه، مدل و در صورت نیاز کلید را وارد کنید. بسیاری از سرورها به یک URL پایه نیاز دارند که با /v1 خاتمه یابد؛ به مستندات نقطه پایانی خود مراجعه کنید.

استفاده از HTTPS الزامی است مگر برای HTTP لوپ‌بک. از یک نقطه پایانی ساده بدون گنجاندن اعتبارات در URL استفاده کنید. کلیدها از رمزگذاری OS پشتیبانی‌شده استفاده می‌کنند و به UI بازگردانده نمی‌شوند. تغییر نقطه پایانی مستلزم وارد کردن مجدد کلید آن است. خالی گذاشتن فیلد کلید، کلید ذخیره‌شده را حفظ می‌کند؛ گزینه Remove the saved key صراحتاً آن را پاک می‌کند.

فراخوانی‌های API از اشتراک CLI استفاده نمی‌کنند. ابزارها و مدل‌ها با جلسات بومی تفاوت دارند و کشف موفق مدل، اجرای فرآیند استنتاج را اثبات نمی‌کند. مصرف توکن تنها زمانی نمایش داده می‌شود که ارائه‌دهنده واقعاً آن را بازگرداند.

اعتبارات را به‌جای متن تسک یا دستورالعمل‌های پیش‌تنظیم، در اتصالات نگه دارید. بازبین‌های فقط‌خواندنی فقط ابزارهای مجاز فایل API را دریافت می‌کنند؛ معمار گزارش هیچ ابزاری ندارد. فراخوانی ابزارهای پشتیبانی‌نشده به‌جای اجرای خاموش، رد می‌شوند. سرورها از نظر پارامترهای استدلال، پشتیبانی از ابزار و فهرست مدل‌ها متفاوت هستند؛ خطا را با قرارداد نقطه پایانی خود مقایسه کنید.

دستورالعمل‌های مرتبط: اتصالات API.

تنظیمات، زبان‌ها و بازنشانی ایمن

تنظیمات عمومی فضای کاری، زبان رابط کاربری و پیش‌فرض‌ها را انتخاب می‌کند. بخش Connections نقاط پایانی API را مدیریت می‌نماید. بخش‌های Presets و Review teams پیکربندی نقش‌ها را حفظ می‌کنند. Remote control اعتبارات محلی، محدوده سرور و مجوزهای مالک را مدیریت می‌کند؛ بخش Updates منبع/کانال انتشار را مدیریت می‌نماید. About مشخصات دقیق بیلد در حال اجرا را نمایش می‌دهد.

زبان رابط کاربری از زبان پرامپت و وضعیت بازبینی مستندات مستقل است. نام‌های محصول، شناسه‌های دستور، پسوندهای فایل، شناسه‌های مدل ارائه‌دهنده و نام‌های ایجادشده توسط کاربر به‌عنوان شناسه باقی می‌مانند. در صورت در دسترس بودن ترجمه فعلی، راهنما از زبان رابط کاربری انتخاب‌شده پیروی می‌کند؛ ترجمه‌های ماشینی برچسب‌گذاری می‌شوند و انگلیسی همچنان مرجع اصلی باقی می‌ماند.

ذخیره، پیکربندی نمایش‌داده‌شده را اعمال می‌کند. بازنشانی پایگاه داده یا بازنشانی کارخانه‌ای می‌تواند متاداده‌های برنامه را حذف کند؛ پیش از استفاده عمدی از بازنشانی، فایل‌ها و یک نسخه پشتیبان آزمایش‌شده را نگه دارید. این عملیات‌ها اقداماتی مختص مالک محلی هستند. از آن‌ها به‌عنوان میان‌بری برای بررسی یک جریان کاری ناموفق یا رکورد آسیب‌دیده استفاده نکنید.

دستورالعمل‌های مرتبط: دستورالعمل‌های بومی‌سازی · بازیابی داده‌ها.

پرسش از دستیار راهنما

راهنما را باز کنید، یک پیش‌تنظیم متصل و ذخیره‌شده را در پنل دستیار آن انتخاب کنید و درباره ZIAForge سؤال بپرسید. پاسخ‌ها از راهنمای انگلیسی مرجع فعلی و زبان انتخابی رابط کاربری شما استفاده می‌کنند. دکمه‌های ارجاع به بخش، مباحث مربوطه در راهنما را باز می‌کنند تا بتوانید توضیح را با مرجع مقایسه کنید.

این دستیار گفتگوی خصوصی جداگانه‌ای تا سقف 100 مورد ذخیره‌شده و 3 مبی‌بایت نگه می‌دارد. سؤالی تا سقف 12,000 نویسه وارد کنید؛ ارسال (Send) آن را می‌پرسد، توقف (Stop) پاسخ فعال را متوقف کرده و سؤال شما را در دسترس نگه می‌دارد، و پاک‌سازی (Clear) این گفتگوی راهنما را حذف می‌کند. پیش‌نویس ارسال‌نشده و پیش‌تنظیم انتخابی شما با بستن یا باز کردن مجدد راهنما در همان نشست برنامه باقی می‌مانند، اما پیش‌نویس روی دیسک ذخیره نمی‌شود. دستیار دستورات برنامه را ارسال نمی‌کند، جریان کاری را تغییر نمی‌دهد یا گیتی را تأیید نمی‌کند. توصیه‌ها راستی‌آزمایی زنده یک تسک، حساب یا اتصال خارجی نیستند.

نشست‌های راهنمای Claude Code و API خط‌مشی پشتیبانی‌شده بدون ابزار را اعمال می‌کنند. نشست‌های راهنمای بومی Codex و Antigravity به مجوز بومی موجود کامپیوتر متعلق به مالک محلی نیاز دارند. اگر این مجوز غیرفعال باشد، برنامه به‌جای انتخاب ارائه‌دهنده‌ای دیگر، پیش‌نیاز را توضیح می‌دهد. فقط مالک می‌تواند آن را در تنظیمات کنترل محلی فعال کند؛ دستیار نمی‌تواند خودش آن را فعال کند.

راهنمای Codex از یک سندباکس فقط‌خواندنی استفاده می‌کند و درخواست‌های تأیید ابزار را رد می‌کند. Antigravity از حالت طرح (plan mode) و پرچم سندباکس بومی خود استفاده می‌کند. این حالت‌های بومی تضمین جهانی برای محدودسازی در سطح سیستم‌عامل نیستند. هش راهنمای منبع، مرجع استفاده‌شده برای پاسخ را مشخص می‌کند؛ یک توضیح تولیدشده همچنان ممکن است اشتباه باشد، بنابراین بخش‌های پیوندداده‌شده آن را قبل از اقدام بررسی کنید. پاسخ‌های قدیمی‌تر هنگامی که نسخه راهنمای منبع آن‌ها با راهنمای فعلی متفاوت باشد علامت‌گذاری می‌شوند.

دستورالعمل‌های مرتبط: نگهداری راهنمای مرجع و ترجمه · دستیار برنامه و مجوزها.

دستیار و Telegram

دستیار از پیش‌تنظیم انتخاب‌شده و همان API کنترل برنامه استفاده می‌کند. مجوز بررسی وضعیت و مجوز انجام عملیات جدا هستند. دستورات و نتایج را بررسی کنید: متن دستیار دلیلی بر تکمیل یک اقدام نیست.

Telegram فقط توسط مالک محلی، با یک توکن ربات موجود و یک ID عددی مالک فعال می‌شود. کنترل مختص چت خصوصی همان مالک است. ربات پیکربندی‌نشده یا غیرفعال نباید پیام‌های برنامه را دریافت کند.

توکن ربات را در چت عادی جای‌گذاری نکنید. پیکربندی یکپارچه‌سازی، اتصال Telegram را اثبات نمی‌کند و به‌طور خودکار رباتی ایجاد نمی‌کند. اسکرین‌شات‌ها و پاسخ‌ها می‌توانند حاوی داده‌های خصوصی فضای کاری باشند.

یک پیش‌تنظیم دستیار انتخاب کنید و مجوز انجام عملیات برنامه را جدا از بررسی اعطا کنید. اجرای دستیار Codex و Antigravity به مجوز بومی مالک نیاز دارد؛ آن‌ها به‌طور خاموش جایگزین یک نشست بدون ابزار API یا Claude نمی‌شوند. اسکرین‌شات‌ها را می‌توان در گفتگوی دستیار نمایش داد، اما ورودی فعلی مدل شامل تحلیل تصویر نیست. صرفاً به این دلیل که دستیار تصویری را نمایش داده است، فرض نکنید که آن را به‌صورت بصری بررسی کرده است.

دستیار می‌تواند خلاصه‌ها، تسک‌ها، چت‌ها، وضعیت جریان کاری، زمینه فرآیند و پنجره‌های برنامه را از طریق ابزارهای تایپ‌شده بررسی کند. دستیار می‌تواند تنظیمات عادی مجاز را تغییر دهد و عملیات‌های مجاز برنامه را راه‌اندازی کند. دستیار نمی‌تواند حقوق بومی اعطا کند، اطلاعات کاربری ذخیره‌شده را فاش کند، مجوز فضای کاری ریشه را از راه دور تغییر دهد یا یک گیت Forge را صرفاً به دلیل راحت بودن تأیید کند.

دستورالعمل‌های مرتبط: قرارداد کنترل برنامه.

مدیریت ربات خصوصی Telegram

ربات خود را بسازید یا تهیه کنید، چت خصوصی آن را آغاز کنید، و توکن آن به همراه ID عددی کاربر Telegram خود را در تنظیمات کنترل محلی وارد کنید. یکپارچه‌سازی را تنها زمانی فعال کنید که قصد دارید برنامه متصل شود. شناسه مالک ID یک شناسه کاربری است، نه نام کاربری یا شناسه ربات ID. تنها پیام‌های ارسال‌شده از سوی آن کاربر در همان چت خصوصی پذیرفته می‌شوند.

از /start، /menu یا /status برای نمای کلی از نسخه در حال اجرا، تعداد پروژه‌ها/تسک‌ها و وضعیت تسک‌ها استفاده کنید. دکمه‌ها بخش‌های پروژه‌ها، تسک‌ها، اسکرین‌شات، راهنما و زبان را باز می‌کنند. فهرست‌ها هشت مورد در هر صفحه را نمایش می‌دهند، همراه با ناوبری بازگشت، نوسازی، خانه و قبلی/بعدی. دکمه‌های پروژه فهرست تسک‌ها را فیلتر می‌کنند. کارت تسک، پیشرفت ذخیره‌شده جریان کاری، مدل/پیش‌تنظیم و سؤالات معلق را در صورت وجود نمایش می‌دهد.

بخش چت‌های یک تسک را باز کنید تا پیش‌نمایش گفتگوهای باز/اخیر و چت‌های فاز جریان کاری را مشاهده نمایید. هر پیش‌نمایش تا شش پیام اخیر کاربر/دستیار را نشان می‌دهد که طول هر کدام به‌صورت مشهود به 200 نویسه کوتاه شده است. استدلال خصوصی نمایش داده نمی‌شود. خواندن سوابق ارائه‌دهنده‌ای را راه‌اندازی نمی‌کند. پیش‌نمایش‌ها فقط‌خواندنی هستند: متن عادی و /ask TEXT همچنان خطاب به دستیار برنامه است و هرگز به‌طور ضمنی متوجه چت تسکی که مشاهده می‌کنید نخواهد بود.

گزینه اجرا / ادامه جریان کاری فعلی Code یا Work را مجدداً می‌خواند و یک جریان کاری ذخیره‌شده واجد شرایط را آغاز می‌کند. مکث درخواست توقف موقت آن را می‌دهد. هیچ‌کدام نیازمندی‌ها، مشخصات فنی، طرح، یافته‌های بازبینی یا سؤالات را قبول نمی‌کنند؛ یک تصمیم معلق مانع از اجرا می‌شود. تصمیمات را در برنامه اتخاذ کنید، یا از یک دستور تایپ‌شده به‌صراحت مجازشده با گیت و ویرایش دقیق فعلی آن استفاده نمایید.

از گزینه زبان یا /language برای انتخاب هر یک از 56 زبان رابط کاربری با نام بومی آن استفاده کنید. این کار ترجیح را تنها برای این ربات و مالک ماندگار می‌سازد. استفاده از زبان برنامه آن ترجیح را پاک می‌کند. این اقدام نه زبان برنامه و نه مجوزهای دسترسی را تغییر نمی‌دهد؛ پیام‌های موجود به‌طور خودکار دوباره ارسال نمی‌شوند.

ناوبری معمولاً همان پیام منوی منتشرشده را به‌روزرسانی می‌کند. دکمه‌ها شناسه‌های مبهمی دارند که پس از 15 دقیقه منقضی می‌شوند و یک‌بارمصرف هستند؛ تغییر یک کارت دکمه‌های قدیمی آن را باطل می‌کند. دکمه‌های منقضی‌شده، مصرف‌شده، پیام نامطابق و متعلق به فرآیند قبلی نمی‌توانند اقدامی انجام دهند. پیامی که قطعاً غیرقابل‌ویرایش باشد را می‌توان با یک کارت جدید جایگزین کرد؛ خطای ناشناخته شبکه به‌عنوان پیام جدید مجدداً تلاش نمی‌شود.

هنگام فعال‌سازی، دریافت‌کننده پیام‌ها انباشت قبلی را دور می‌ریزد و پذیرش به‌روزرسانی را قبل از ارسال ثبت می‌کند تا دستورات متوقف‌شده هنگام راه‌اندازی مجدد به‌طور خودکار بازپخش نشوند. این کار از بازپخش جلوگیری می‌کند اما تکمیل را تضمین نمی‌کند. قبل از صدور آگاهانه کار جدید پس از یک خطا، وضعیت/زمینه را بررسی کنید. اعلان خودکاری برای وضعیت تسک وجود ندارد.

دستورات صریح همچنان در دسترس هستند: /projects، /tasks، /task TASK_ID، /run TASK_ID، /pause TASK_ID، /screenshot و /ask TEXT. دستور /new {JSON} تسکی را از طریق متد تایپ‌شده createTask ایجاد می‌کند؛ دستور /command {JSON} یک دستور صریح کاتالوگ ارسال می‌کند. برای ساختار آرگومان‌ها کاتالوگ زنده را مطالعه کنید. همان مجوزهای بک‌اند و دسترسی‌های پوشه اعمال می‌شوند که در برنامه وجود دارند.

برنامه هرگز مقادیر توکن ذخیره‌شده ربات را به دستیار ارسال نمی‌کند. با این حال، اسکرین‌شات‌ها، خلاصه‌ها و متن گفتگو ممکن است حاوی اطلاعات خصوصی پروژه باشند. اگر ربات یا حساب کاربری مالک دیگر مورد اعتماد نیستند، یکپارچه‌سازی را به‌صورت محلی متوقف کنید. یک توکن فاش‌شده را نزد ارائه‌دهنده ربات باطل و جایگزین کنید، سپس پیکربندی رمزگذاری‌شده محلی آن را به‌روزرسانی نمایید.

دستورالعمل‌های مرتبط: ربات خصوصی و دستورات.

مجوز بومی کامپیوتر اختصاصی مالک

دسترسی بومی کامپیوتر در ابتدا غیرفعال است. فقط مالک می‌تواند آن را در تنظیمات محلی ← کنترل از راه دور فعال کند. دستیار و دستورات HTTP/MCP/Telegram نمی‌توانند این پرچم را برای خود فعال کنند. اگر عملیاتی رد شد، دستیار باید تنظیمات را شرح داده و تصمیم‌گیری را به مالک واگذار کند.

هنگامی که به‌طور صریح فعال شود، computer.run یک فایل اجرایی، آرایه آرگومان و پوشه کاری مطلق اختیاری را می‌پذیرد. این قابلیت از درونیابی شل استفاده نمی‌کند، محدودیت 30 ثانیه‌ای دارد و خروجی را به 1 مبی‌بایت محدود می‌کند. پوشه ناموجود یا نامعتبر ارائه‌شده رد می‌شود؛ در صورت حذف cwd از پوشه تنظیمات متعلق به برنامه استفاده می‌شود، نه HOME. خروج (Quit) دستورات فعال تحت مالکیت را لغو کرده و منتظر پاک‌سازی فرآیند آن‌ها می‌ماند.

محدوده خواندن/عملیات برنامه و دسترسی بومی تصمیماتی جداگانه هستند. ورک‌تری دسترسی فایل‌سیستمی یک ارائه‌دهنده نامحدود را محدود نمی‌کند. در صورتی که پس از اتمام تسک دیگر نیازی به دسترسی بومی نیست، آن را لغو کنید و به‌جای پذیرفتن متن دستیار به‌عنوان مدرک، رسیدهای دستور را بررسی کنید.

دستورالعمل‌های مرتبط: قرارداد کنترل اختصاصی مالک.

مرورگر و نمونه‌های راه دور

مالک محلی سرور را فعال می‌کند و آدرس، درگاه و محدوده آن را انتخاب می‌کند: خواندن (read) برای بررسی یا عملیات (operate) برای اقدامات. آدرس پیش‌فرض 127.0.0.1 فقط روی این کامپیوتر در دسترس است. 0.0.0.0 روی رابط‌های شبکه شنود می‌کند؛ قبل از فعال کردن آن، دسترسی شبکه را بررسی کنید.

مرورگر پس از ورود با توکن، همان رابط را باز می‌کند. توکن‌ها را در پیوندهای عمومی یا اسکرین‌شات‌ها قرار ندهید. HTTP به‌تنهایی ترافیک را رمزگذاری نمی‌کند؛ از یک کانال حفاظت‌شده روی شبکه غیرقابل‌اعتماد استفاده کنید.

مالک نمونه‌های دیگر را از طریق URL و توکن پیکربندی می‌کند. بک‌اند درخواست‌ها را پروکسی می‌کند؛ این کار پروژه‌های آن‌ها را روی دستگاه محلی کپی نمی‌کند. قبل از هر اقدامی، نمونه انتخاب‌شده را بررسی کنید.

دستورات و رویدادهای تایپ‌شده، کنترل برنامه را به همراه دارند. محدوده خواندن (Read scope) مجوزی برای تغییرات تسک صادر نمی‌کند. کنترل بومی کامپیوتر یک انتخاب جداگانه متعلق به مالک محلی است و در ابتدا غیرفعال است.

برنامه باید برای کنترل از طریق مرورگر، Telegram و عامل خارجی در حال اجرا بماند. هر نمونه دارای نمایه خصوصی، وضعیت تسک، توکن و درگاه سرور مخصوص به خود است. از یک نمایه به‌طور همزمان بین نمونه‌های مستقل استفاده مجدد نکنید. رویدادهای مرورگر و پاسخ‌های دستور به نمونه انتخاب‌شده محدود می‌شوند؛ جابه‌جایی UI فایل‌ها را جابه‌جا نمی‌کند و لاگین بومی را کپی نمی‌کند.

دستورالعمل‌های مرتبط: HTTP و کنترل نمونه.

OpenClaw، Hermes و سایر عامل‌های خارجی

از API احرازهویت‌شده کنترل برنامه یا پل stdio همراه MCP استفاده کنید. سرور را به‌صورت محلی فعال کنید، حالت خواندن (read) یا عملیات (operate) را انتخاب کنید و هر کلاینت را با URL و توکن آن نمونه پیکربندی کنید. برای اجرای پل مستقل MCP به Node.js نسخه 22 یا جدیدتر نیاز است؛ برنامه Electron کلاینت عامل شما را نصب نمی‌کند. نشانی اینترنتی URL مرورگر یک اندپوینت جریانی HTTP MCP نیست: آن را به‌عنوان ZIAFORGE_URL به پل stdio تحویل دهید.

این پل ziaforge_status، ziaforge_commands، ziaforge_command و ziaforge_screenshot را ارائه می‌دهد. با وضعیت و کاتالوگ زنده دستورات شروع کنید، سپس system.context را برای تسک انتخاب‌شده بخوانید. دستورات تایپ‌شده از همان بررسی‌های نسخه، گیت، پوشه تسک و پاک‌سازی پیروی می‌کنند که در UI محلی اعمال می‌شود.

کاتالوگ زنده دستورات شامل documentation.guide، راهنمای انگلیسی مرجع، با مسیر مبدأ و sourceSha256 آن است. معمار داخلی برنامه نیز همان مرجع را از طریق ابزارهای خود دریافت می‌کند. این کار کل بافت محصول را بدون اتکا به یادداشت‌های قدیمی در اختیار عامل‌ها قرار می‌دهد؛ مستندات هرگز مجوزی صادر نمی‌کند یا جایگزین تصمیم فعلی انسانی نمی‌شود.

عامل‌ها باید نیازمندی‌ها، تصمیمات فنی و برنامه‌ریزی را بر اساس یک ایده کوتاه انسانی مورد بحث قرار دهند. آن‌ها باید گیت‌های صریح انسانی، مدل‌های انتخاب‌شده، خط‌مشی دستی/Auto و بازبینی لازم را حفظ کنند. آن‌ها نباید تأییدیه جعل کنند، دستورات نامطمئن را با ID جدید بازپخش کنند یا تغییرات Git را بدون خواست مالک منتشر کنند.

چندین سرور نام‌گذاری‌شده MCP را برای چند نصب پیکربندی کنید. تعویض نمونه یک تصمیم مسیریابی است، نه همگام‌سازی. نمونه‌های پیکربندی OpenClaw و Hermes در AGENT_CONTROL.md موجود است؛ راه‌اندازی و سازگاری خاص کلاینت باید برای نسخه کلاینت نصب‌شده بررسی شود.

کش بیرونی requestId تنها مجموعه‌ای محدود از درخواست‌ها را در حین اجرای برنامه یکتازدایی می‌کند. عملیات‌های پایدار از شناسه‌های خود استفاده می‌کنند: createRequestId برای ایجاد تسک، commandId برای تصمیمات جریان کاری، clientMessageId برای پیام‌ها و operationId برای جهش‌های Git. شناسه و محموله داده اصلی را پس از یک تأیید دریافت نامشخص حفظ کنید؛ قبل از صدور آگاهانه کار جدید، وضعیت ذخیره‌شده را بخوانید.

دستورالعمل‌های مرتبط: دستورالعمل‌های کلاینت MCP.

CLI محلی و محدودیت‌های خودکارسازی

توزیع‌کننده ziaf همان برنامه در حال اجرا و جریان کاری ذخیره‌شده را کنترل می‌کند. از سورس کد، از npm run ziaf -- list، npm run ziaf -- status --task TASK_ID --json، npm run ziaf -- start --task TASK_ID یا npm run ziaf -- pause --task TASK_ID استفاده کنید. دریافت موفقیت‌آمیز تأیید Start به این معنی نیست که تسک تکمیل شده است.

گزینه --until-success به‌طور آگاهانه Auto را برای جریان کاری ذخیره‌شده فعال می‌کند، اما سؤالات، بازبینی، گیت‌های پذیرش، محدودیت‌ها و چک‌پوینت‌ها همچنان اعمال می‌شوند. کلیدهای ترکیبی Ctrl+C از توزیع‌کننده نظاره‌گر خارج می‌شود؛ این کار جریان کاری برنامه را به‌طور ضمنی متوقف نمی‌کند. برای کدهای خروج، اندپوینت محلی و مدیریت نمایه به CLI.md مراجعه کنید.

رابط خودکارسازی‌ها در حال حاضر تعاریف نمایشی و شمارنده‌های اجرای محلی را ذخیره می‌کند. این رابط یک زمان‌بند تکرارشونده تأییدشده نیست و اثبات نمی‌کند که نوبت مدل در پس‌زمینه اجرا شده است. برای اجرای واقعی از کنترل‌های جریان کاری ذخیره‌شده، ziaf یا API احرازهویت‌شده استفاده کنید و رسیدهای آن‌ها را بررسی کنید. پنل نمایشی را با زمان‌بندی بدون نظارت اشتباه نگیرید.

دستورالعمل‌های مرتبط: دستورات توزیع‌کننده.

نسخه و به‌روزرسانی‌ها

بخش About نسخه دقیق در حال اجرا را نمایش می‌دهد. به‌روزرسانی‌های عمومی نیازمند مخزن انتشار قابل‌اعتماد GitHub و یک کانال پایدار (stable) یا پیش‌نمایش (preview) هستند. بررسی، دانلود و نصب وضعیت‌های جداگانه‌ای دارند؛ یک خطا به معنای نصب شدن به‌روزرسانی نیست.

نصب خودکار مختص نسخه‌های امضاشده macOS است. بیلد‌های توسعه امضانشده به‌طور خودکار از طریق این سازوکار نصب نمی‌شوند. برای جایگزینی دستی، برنامه فعلی را به‌طور کامل ببندید و از یک آرتیفکت تأییدشده استفاده کنید.

بررسی خودکار بلافاصله پس از فعال‌سازی، و سپس هر شش ساعت یک‌بار اجرا می‌شود.

کانال پایدار (Stable) نسخه‌های پیش‌نمایش را مستثنی می‌کند؛ پیش‌نمایش (Preview) نسخه‌های توسعه را نیز مجاز می‌داند. یک بررسی موفق تنها فراداده نسخه موجود را مشخص می‌کند. دانلود و نصب به بسته پلتفرم و فید انتشار پیکربندی‌شده نیاز دارد. تحویل بسته DEB در Linux مسیر نصب جداگانه‌ای است؛ فرض نکنید که یک فایل DEB به‌طور خودکار توسط سازوکار به‌روزرسانی macOS ارتقا می‌یابد.

دستورالعمل‌های مرتبط: آمادگی انتشار.

راه‌اندازی مجدد و بازیابی

در macOS، از Quit / ⌘Q برای خاموش کردن کامل استفاده کنید. بستن پنجره ممکن است برنامه را در حال اجرا باقی بگذارد. قبل از جایگزینی برنامه، نسخه قدیمی را به‌طور کامل ببندید.

پس از راه‌اندازی، همان تسک را انتخاب کنید. تاریخچه و پیش‌نویس‌ها بازمی‌گردند. فرمان Resume یک بافت بومی/محلی را بازیابی می‌کند اما پیش‌نویسی ارسال نمی‌کند، صف را از مکث خارج نمی‌کند یا مجوزی برای تکرار یک عملیات نامشخص صادر نمی‌کند.

اگر بازیابی (Recovery) ظاهر شد، JSON را به‌صورت دستی ویرایش نکنید. نوع سند متأثر را بررسی کنید، فایل‌های اصلی را نگه دارید و یک پشتیبان اعتبارسنجی‌شده را انتخاب کنید. بازیابی یک صف قدیمی‌تر، آیتم‌های آن را نامطمئن علامت‌گذاری می‌کند.

هنگامی که وضعیت تحویل نامشخص است، یک جریان کاری مدیریت‌شده ممکن است برای ایجاد یک بافت جدید به مجوز صریح نیاز داشته باشد. کارهای قبلی و تلاش‌های ناموفق باقی می‌مانند؛ امتناع آشکار ایمن‌تر از موفقیت ساختگی است.

از فایل‌های تسک و نمایه برنامه در حالی که تمام نمونه‌های برنامه بسته‌اند پشتیبان‌گیری کنید. یک پوشه کپی‌شده، بازیابی آزمایش‌شده محسوب نمی‌شود. اگر بازیابی از شما خواست یک پشتیبان اعتبارسنجی‌شده انتخاب کنید، فایل‌های آسیب‌دیده دقیق را نیز حفظ کنید. بازیابی یک جریان کاری یا صف قدیمی‌تر، مجوزی برای بازپخش استنتاج نامطمئن یا عملیات‌های Git صادر نمی‌کند.

دستورالعمل‌های مرتبط: قرارداد بازیابی.

عیب‌یابی

CLI یافت نشد: نصب و نسخه آن را در یک ترمینال عادی بررسی کنید، سپس ZIAForge را مجدداً راه‌اندازی کنید. موجود بودن یک فایل اجرایی به معنای وارد شدن به حساب کاربری نیست. از سازوکار ورود اختصاصی ارائه‌دهنده استفاده کنید.

مدل در دسترس نیست یا احراز هویت ناموفق بود: شناسایی را نوسازی کنید، یک ID موجود را انتخاب کنید و حساب کاربری و محدودیت‌های خود را بررسی نمایید. درخواستی نامطمئن را قبل از بررسی سوابق آن تکرار نکنید.

جریان کاری متوقف شد: فاز فعلی، سؤال، رسید راستی‌آزمایی یا لاگ‌های CLI را باز کنید. علت مشخص را برطرف کنید: سؤالی بی‌پاسخ، دستور، مجوز پوشه یا حد مجاز دفعات تلاش. دستور Continue نمی‌تواند یک بررسی ناموفق را به موفقیت تبدیل کند.

پوشه مفقود یا جایگزین شده است: دسترسی به پوشه اصلی را بازیابی کنید یا یک تسک جدید بسازید. برنامه نباید از HOME ادامه دهد. اگر cwd دیگری مشاهده کردید، نوبت را متوقف کرده و داده‌های عیب‌یابی را حفظ کنید.

برای گزارش، نسخه موجود در About، مسیر، CLI/مدل، رفتار مورد انتظار و واقعی، یک اسکرین‌شات و گزیده‌ای امن از لاگ را ضمیمه کنید. اسرار، محتوای شخصی و مسیرهایی را که نباید منتشر شوند حذف کنید.

صفحه راه دور در دسترس نیست: تأیید کنید که مالک سرور را فعال کرده باشد، آدرس و پورت شنود را بررسی کنید، سپس با توکن صحیح نمونه احراز هویت کنید. خطای 401 نشان‌دهنده نیاز به احراز هویت است؛ یک جهش ردشده ممکن است ناشی از محدوده فقط‌خواندنی یا کنترل اختصاصی مالک باشد. تغییر توکن، کلاینت‌های مرورگر موجود را می‌بندد. پورت مجزای بررسی DevTools را به‌عنوان کنترل برنامه از راه دور در معرض شبکه قرار ندهید.

ذخیره در ویرایشگر رد شد: پیش‌نویس را نگه دارید، فایل فعلی روی دیسک را بررسی کنید و تداخل ناشی از تغییر خارجی را برطرف نمایید. مقایسه را با بازنویسی متاداده‌های برنامه دور نزنید. اگر بارگذاری کامل فایل‌های بزرگ امکان‌پذیر نیست، از ویرایش/جستجوی پنجره‌ای پشتیبانی‌شده یا یک ویرایشگر خارجی استفاده کنید.

Telegram در دسترس نیست: توکن ربات، شناسه عددی مالک، چت خصوصی و وضعیت را به‌صورت محلی بررسی کنید. وب‌هوک یا پولر همزمان دیگر می‌تواند مانع پولینگ شود؛ ZIAForge به‌طور خودکار وب‌هوکی را حذف نمی‌کند یا کنترل پولر دیگری را به دست نمی‌گیرد. دستوراتی که در مرزی نامشخص رد یا متوقف شده‌اند به‌طور خودکار بازپخش نمی‌شوند.

دستورالعمل‌های مرتبط: تست و عیب‌یابی.

گزارش مشکلات و بررسی شواهد

نسخه دقیق در حال اجرا را از About، OS/معماری، حالت تسک، ارائه‌دهنده/مدل انتخاب‌شده و مراحلی که مشکل را بازتولید می‌کنند ثبت کنید. نتیجه مورد انتظار و نتیجه مشاهده‌شده را شرح دهید. به‌جای کل نمایه خصوصی، یک اسکرین‌شات امن و رسید دستور یا راستی‌آزمایی نگهداری‌شده مرتبط را ضمیمه کنید.

لاگ‌های CLI، ژورنال‌های رویداد، رونوشت‌های مدل، ردپاهای مرورگر و اسکرین‌شات‌ها ممکن است سورس کد، مسیرهای شخصی یا توکن‌ها را فاش کنند. پیش از اشتراک‌گذاری، آن‌ها را بازبینی و بازداری کنید. یک ابزار بازداری لاگ با بهترین تلاش، قابل‌انتشار بودن اسکرین‌شات یا آرشیو را تأیید نمی‌کند.

برای مشارکت‌کنندگان، qa:doctor هویت محیط/بیلد را می‌خواند؛ qa:inspect یک نمایه ایزوله با استاب‌های ارائه‌دهنده را باز می‌کند. یک فیکسچر مسیر تست‌شده برنامه را بدون تماس با مدل اثبات می‌کند. استنتاج زنده، اتصال Telegram، دسکتاپ بومی Linux، امضا و بررسی‌های آرتیفکت بسته‌بندی‌شده شواهد جداگانه‌ای هستند. برای دستورات بازتولیدپذیر و پاک‌سازی به TESTING.md مراجعه کنید.

دستورالعمل‌های مرتبط: دستورات شواهد.

داده‌های محلی و مرزها

پروژه‌ها، سوابق، طرح‌ها، اسناد و ابزارهای عیب‌یابی ممکن است حاوی متن خصوصی باشند. نمایه‌ها، ثبت‌های خام، کلیدها یا لاگ‌های کامل را به همراه سورس کد منتشر نکنید.

در Linux، ذخیره‌سازی اطلاعات کاربری API، کنترل، Telegram و نمونه نیازمند یک سرویس مخفی قفل‌گشایی‌شده GNOME یا KWallet است؛ بدون یک مخزن امن پشتیبانی‌شده، ZIAForge به‌جای استفاده از راهکار جایگزین basic_text در Electron، از ذخیره این اسرار خودداری می‌کند.

ذخیره‌سازی محلی به معنای باقی ماندن درخواست‌ها روی رایانه شما نیست: CLI/API انتخاب‌شده، آن‌ها را به ارائه‌دهنده‌اش ارسال می‌کند. پوشه کاری و نظارت بر فرآیند، ایزولاسیون OS به شمار نمی‌روند. مجوزهای انتخاب‌شده را بررسی کنید.

انواع شواهد را تفکیک کنید: فیکسچرها برنامه را بدون مدل آزمایش می‌کنند؛ اجرای بومی زنده یک CLI/حساب کاربری واقعی را به کار می‌گیرد؛ بررسی‌های بسته‌بندی‌شده یک آرتیفکت خاص را تصدیق می‌کنند. موفقیت در یکی تضمین‌کننده بقیه نیست.

محدوده برنامه، ورک‌تری و پرامپت فقط‌خواندنی با اعمال در سطح سیستم‌عامل تفاوت دارند. خط‌مشی‌های بازبین/دستیار Antigravity به‌جای اعمال دسترسی فقط‌خواندنی فایل‌سیستم، تغییرات را در شواهد جمع‌آوری‌شده فضای کاری شناسایی می‌کنند. کنترل بومی کامپیوتر برنامه‌های مجازشده توسط مالک را خارج از مرز معمول ابزارهای برنامه اجرا می‌کند؛ زمانی که دیگر نیازی به آن نیست، آن را خاموش کنید.

دستورالعمل‌های مرتبط: مبدأ و انتشار.

شناخت و تغییر این پروژه متن‌باز

ابتدا AGENTS.md و CONTRIBUTING.md و سپس PROJECT_MAP.md را برای مرزهای فعلی سورس کد مطالعه کنید. قراردادهای تایپ‌شده پیاده‌سازی‌شده و اسناد فعلی جریان کاری/ارائه‌دهنده حاکم بر رفتار هستند. CONCEPT.md و بخش‌های اولویت‌ترمینال در ARCHITECTURE.md قصد و هدف تاریخی را حفظ می‌کنند و نباید با ادعاهای نسخه فعلی اشتباه گرفته شوند.

منبع راهنمای انگلیسی docs/help/en.json است. فایل‌های تولیدشده USER_GUIDE.md یا website/guide.html را به‌صورت دستی ویرایش نکنید. بخش مرجع را تغییر دهید، قرارداد متأثر را به‌روزرسانی کرده و node scripts/help/generate.cjs را اجرا کنید. راهنمای درون‌برنامه‌ای همان منبع را می‌خواند. موارد اضافه‌شده را با پیاده‌سازی واقعی، از جمله محدودیت‌ها، مجوزها و مسیرهای پشتیبانی‌نشده بازبینی کنید.

هر یک از 56 زبان رابط کاربری، وضعیت راهنمای جداگانه‌ای در docs/help/locales.json دارند. راهنمای مفقود یا ناقص به زبان انگلیسی بازمی‌گردد. متن‌های کاملاً ترجمه‌شده ماشینی برچسب‌گذاری شده و به هش منبع انگلیسی متصل می‌شوند، بدون ادعای بازبینی انسانی. ترجمه‌ای که توسط انسان بازبینی شده باشد علاوه‌بر این نام بازبین خود را ثبت می‌کند. هر ترجمه باید شناسه‌های بخش، اقدامات، شناسه‌های فایل/دستور و محدودیت‌های فنی را حفظ کند، از جهت مناسب استفاده کند، و هنگام تغییر منبع انگلیسی‌اش تازه‌سازی شود.

قبل از انتشار، node scripts/help/generate.cjs --check را اجرا کنید تا خروجی‌های کهنه تولیدشده، داربست‌های نامعتبر محلی یا پیوندهای خراب قرارداد محلی را شناسایی کنید. بررسی‌های ترجمه UI و بررسی‌های رفتار برنامه جدا از هم باقی می‌مانند. فایل HELP_MAINTENANCE.md روند به‌روزرسانی برای مشارکت‌کننده و AI را شرح می‌دهد؛ مستندات نباید ادعای قبولی در آزمونی را داشته باشند که اجرا نشده است.

دستورالعمل‌های مرتبط: نقشه فعلی پروژه · نگهداری مستندات · دستورالعمل‌های مشارکت‌کننده · دستورالعمل‌های عامل.