مستندات و راهنمای پلوک

پلوک (پَلوَک) یک دستیار هوشمند و بومی برنامه‌نویسی دسکتاپ بر پایه یک ویرایشگر آشنا و محبوب است. بخش‌های چت، عامل‌های هوشمند، تکمیل تب (⁦Tab completions⁩) و جستجو در کدبیس همگی از یک حساب کاربری، یک کاتالوگ مدل و یک فضای کار یکپارچه استفاده می‌کنند.

• برنامه دسکتاپ ⁦IDE⁩: یک ویرایشگر قدرتمند و کامل همراه با قابلیت میز کار عامل (⁦Agent Desk⁩)، ابزارهای پیشرفته و دسترسی به فایل‌های محلی پروژه.
• ابر پلوک (پَلوَک ⁦Cloud⁩): مدیریت امور احراز هویت، صورت‌حساب‌ها، مسیریابی امن مدل‌ها و برخورداری اختیاری از قابلیت ایندکس ابری.
• وب‌سایت ⁦palvak.com⁩: پورتال مدیریت حساب کاربری، بخش دانلود نرم‌افزار، مشاهده تعرفه‌ها و دسترسی به مستندات راهنما.

۱. ایجاد حساب کاربری

در وب‌سایت ⁦palvak.com⁩ ثبت‌نام کنید. آدرس ایمیل خود را تأیید کرده و سپس طرح رایگان (⁦Free⁩) را برای ارزیابی قابلیت‌های اولیه انتخاب فرمایید.

۲. دانلود محیط توسعه (⁦IDE⁩)

آخرین نسخه رسمی و پایدار را متناسب با سیستم‌عامل خود نصب کنید. نسخه‌های نصب‌کننده ویندوز و لینوکس در صفحه دانلود وب‌سایت در دسترس هستند؛ نسخه ویندوز از قابلیت به‌روزرسانی خودکار درون‌برنامه‌ای پشتیبانی می‌کند و نسخه ⁦macOS⁩ نیز به‌زودی ارائه خواهد شد.

۳. ورود به حساب کاربری از داخل ⁦IDE⁩

1. برنامه پلوک را اجرا کرده و بخش میز کار عامل (پنل چت) را باز کنید.
2. گزینه ورود (⁦Sign In⁩) را انتخاب کنید یا دستور «⁦palvak⁩: ⁦Sign In⁩» را از منوی پالت دستورات (با کلیدهای ⁦Ctrl⁩+⁦Shift⁩+⁦P⁩) اجرا کنید.
3. مراحل ورود را در مرورگر وب خود تکمیل کنید؛ محیط توسعه به طور خودکار توکن انتقال امن دسترسی را دریافت خواهد کرد.
4. تأیید کنید که آدرس ایمیل شما در مسیر ⁦Settings⁩ → ⁦General⁩ → پَلوَک ⁦Account⁩ نمایش داده می‌شود.

۴. ارسال اولین دستور در بخش چت

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

میز کار عامل (⁦Agent Desk⁩) رابط کاربری اصلی شما با هوش مصنوعی است. از ⁦Ask⁩ برای پرسش خواندنی، از ⁦RFC⁩ (بتا) برای نگارش سند طراحی در ⁦docs/⁩، از ⁦Plan⁩ برای برنامه پیش از کد، و از ⁦Agent⁩ برای کارهای اجرایی چندمرحله‌ای استفاده فرمایید.

آشنایی با حالت‌های مختلف فعالیت

• حالت ⁦Ask⁩ (پرسش): پرسش سوالات صرفاً خواندنی و کاوش در کدبیس به کمک ابزارهای جستجو، بدون اعمال تغییر روی فایل‌ها یا اجرای ترمینال.
• حالت ⁦RFC⁩ (بتا): نگارش سند طراحی نسخه‌دار فقط در مسیر ⁦docs/RFC-⁩*⁦.md⁩، گفت‌وگو فقط گزارش وضعیت است؛ بدون کد محصول و بدون ابزار ⁦Plan.⁩
• حالت ⁦Plan⁩ (برنامه‌ریزی): بررسی کامل کدبیس، شفاف‌سازی نیازمندهای فنی و تهیه نقشه راه دقیق پیش از آغاز برنامه‌نویسی برای اخذ تایید شما.
• حالت ⁦Agent⁩ (عامل): پیاده‌سازی و اجرای کارهای تاییدشده؛ فراخوانی ابزارهای خودکار، ویرایش فایل‌ها و اجرای دستورات با تایید مستقیم شما.

تأیید و صدور مجوز برای ابزارها

به طور پیش‌فرض، پلوک پیش از اجرای دستورات ترمینال، تغییر فایل‌ها یا وب‌گردی همواره از شما اجازه می‌گیرد. شما می‌توانید تنظیمات تایید خودکار (⁦Auto-approve⁩) را برای هر ابزار به طور مجزا در مسیر ⁦Settings⁩ → ⁦Permissions⁩ پیکربندی کنید. هرگز تایید خودکار سراسری را در محیط‌های کاری ناشناس و غیرقابل‌اعتماد فعال نفرمایید.

درک بافتار و زمینه (⁦Context⁩)

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

مدل‌های در دسترس در مسیر ⁦Settings⁩ → ⁦Models⁩ و منوی انتخابگر مدل در چت فهرست شده‌اند. پلوک درخواست‌های چت را از طریق درگاه ⁦API⁩ پلوک به مدل‌های ⁦MiMo⁩ (شیائومی)، ⁦Meta Muse⁩، ⁦GLM⁩ (⁦Z.AI⁩) و ⁦DeepSeek⁩ ارسال می‌کند.

کاتالوگ مدل‌های فعلی

• ⁦MiMo-V2.6-Flash⁩: نسل فعلی ⁦MiMo⁩ برای کدنویسی و عامل، تا ۱⁦M⁩ زمینه
• ⁦MiMo-V2.6-Pro⁩: مدل پرچم ⁦MiMo⁩ برای کارهای عامل پیچیده، تا ۱⁦M⁩ زمینه
• ⁦GLM-5.3-Flash⁩: مدل عامل چندوجهی سریع با ⁦vision⁩، ابزار و کدنویسی، ۱⁦M⁩ زمینه
• ⁦Muse Spark 1.2 Contributor⁩: مدل عامل ⁦Meta⁩ با ۱⁦M⁩ زمینه، ⁦vision⁩، فراخوانی ابزار و سطح ⁦Reasoning effort⁩ قابل تنظیم (کم، متوسط، زیاد، بسیار زیاد)
• ⁦DeepSeek-V4.1-Flash⁩: مدل چندوجهی و هوشمند ⁦DeepSeek⁩ با پشتیبانی از ۱⁦M⁩ توکن زمینه، ورودی تصویر (⁦Vision⁩) و فراخوانی ابزار. این مدل از طریق انتخابگر چت قابل انتخاب بوده و قابلیت تفکر (⁦Thinking⁩) به‌منظور ارائه پاسخ‌های سریع‌تر به‌طور پیش‌فرض در آن خاموش است.

ساعات اوج (⁦Peak⁩) و غیر اوج (⁦Off-Peak⁩) مدل ⁦DeepSeek⁩

محاسبه اعتبار مصرفی مدل ⁦DeepSeek-V4.1-Flash⁩ بر اساس زمان استفاده (⁦Time-of-Use⁩) انجام می‌شود. ساعات اوج مصرف (⁦Peak⁩) شامل روزهای کاری هفته بر اساس ساعت جهانی ⁦UTC⁩ (دوشنبه تا جمعه، به‌استثنای تعطیلات رسمی چین) و در دو بازه زمانی است: از ساعت ۰۱:۰۰ تا ۰۴:۰۰ ⁦UTC⁩ (ساعت ۰۴:۳۰ تا ۰۷:۳۰ به وقت تهران) و از ساعت ۰۶:۰۰ تا ۱۰:۰۰ ⁦UTC⁩ (ساعت ۰۹:۳۰ تا ۱۳:۳۰ به وقت تهران). در تمامی ساعات دیگر، روزهای آخر هفته و تعطیلات رسمیت‌یافته، نرخ غیر اوج (⁦Off-Peak⁩) با هزینه اعتبار کمتر به‌صورت خودکار اعمال می‌شود. وضعیت فعال (⁦Peak⁩ یا ⁦Off-Peak⁩) هنگام انتخاب مدل در انتخابگر چت مشخص شده است.

طرح‌ها و پیش‌فرض‌ها

انتخاب شما در انتخابگر برای هر جلسه به خاطر سپرده می‌شود. رایگان: ⁦MiMo-V2.6-Flash⁩، ⁦GLM-5.3-Flash⁩ و ⁦DeepSeek-V4.1-Flash⁩ (انتخاب دستی در انتخابگر)⁦. Pro⁩: ⁦MiMo-V2.6-Pro⁩ و ⁦Muse Spark 1.2 Contributor. Plus⁩: همان مدل‌ها با سهمیه ماهانه بالاتر.

پلوک می‌تواند پیشنهادهای تکمیل تب (⁦Tab completions⁩) را هم‌زمان با تایپ کردن شما، با استفاده از همان زیرساخت قدرتمند بک‌اند چت، به صورت متون سایه‌ای کم‌رنگ نمایش دهد. این پیشنهادها کاملاً با زبان برنامه‌نویسی و بافتار فایل پروژه شما همخوانی دارند.

فعال‌سازی و غیرفعال‌سازی

به مسیر ⁦Settings⁩ رفته و عبارت ⁦tab⁩ را جستجو کنید یا از بخش ⁦Tab⁩ در تنظیمات پلوک استفاده نمایید. در صورت غیرفعال بودن پیشنهادهای خودکار، می‌توانید با کلیدهای ⁦Alt⁩+\ به صورت دستی پیشنهاد بگیرید.

پلوک روی دستگاه شما ایندکس محلی کدبیس می‌سازد. فایل‌های منبع روی دیسک می‌مانند؛ در طرح ⁦Pro⁩ و ⁦Plus⁩، اثر انگشت امبدینگ به‌صورت خودکار برای جست‌وجوی معنایی ابری با مدل امبدینگ به‌روزشده همگام می‌شود تا نتایج مرتبط‌تر باشد.

ایندکس محلی (همه طرح‌ها)

• ایندکس‌گذاری با باز کردن ⁦workspace⁩ به‌صورت خودکار انجام می‌شود
• رد خودکار: پوشه‌های وابستگی (مثل ⁦node_modules⁩)، ⁦.git⁩، خروجی ⁦build⁩ (⁦dist⁩)، فایل‌های محرمانه ⁦env⁩، به‌علاوه ⁦.palvakignore⁩ و قوانین نادیده‌گرفتن جست‌وجو
• ⁦View included files⁩: تب فقط‌خواندنی با فهرست مسیرهای ایندکس محلی فعلی
• وضعیت در کارت ⁦Indexing⁩ & ⁦Docs⁩: ⁦In progress⁩ یا ⁦Done⁩ (بدون نوار درصد)

جست‌وجوی معنایی ابری (⁦Pro / Plus⁩)

• آپلود امبدینگ ابری پس از ورود و آماده‌شدن ایندکس محلی خودکار است، بدون دکمه ⁦Sync⁩ یا ⁦Delete Index⁩
• متن ⁦chunk⁩ روی سرور ذخیره نمی‌شود؛ بردارها و مسیر/هش برای بازیابی معنایی استفاده می‌شوند
• پس از ارتقای مدل امبدینگ، پلوک در پس‌زمینه با سرعت کنترل‌شده دوباره همگام می‌کند

⁦Cache repeated Grep and Glob searches⁩

گزینه اختیاری در ⁦Indexing⁩ & ⁦Docs.⁩ نتایج اخیر ⁦Grep⁩ و ⁦Glob⁩ عامل را در حافظه محلی نگه می‌دارد تا جست‌وجوهای تکراری در همان جلسه سریع‌تر تمام شوند. جدا از ایندکس کدبیس است.

در مسیر ⁦Settings⁩ → ⁦Indexing⁩ & ⁦Docs⁩ → ⁦Docs⁩، فایل‌های ⁦markdown⁩ محلی یا نشانی‌های اینترنتی عمومی مستندات را وارد کنید. پلوک به طور خودکار محتوای آن‌ها را قطعه‌بندی و ایندکس می‌کند تا بتوانید با عبارت ⁦docs@⁩ در چت به آن‌ها ارجاع دهید.

1. بر روی گزینه ⁦Add Doc⁩ کلیک کرده و گزینه فایل محلی (⁦Local file⁩) یا آدرس اینترنتی (⁦URL⁩) را انتخاب کنید.
2. منتظر بمانید تا فرآیند ایندکس‌گذاری کامل شود (به‌روزرسانی به صورت خودکار انجام می‌شود).
3. اکنون می‌توانید با عبارت ⁦docs@⁩ یا به زبان طبیعی در چت به این مستندات ارجاع دهید.

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

• مسیر ⁦Settings⁩ → ⁦Configure Tools⁩: فعال‌سازی گروه ابزار مرورگر.
• گزینه ⁦workbench.browser.enableChatTools⁩: فعال‌سازی کل ابزارهای خودکارسازی مرورگر وب.
• بخش دسترسی‌ها (⁦Permissions⁩): صدور تاییدیه برای وب‌گردی‌ها و اقدامات حساس برای هر جلسه کاری.

سرورهای ⁦MCP⁩ (⁦Model Context Protocol⁩)

سرورهای ⁦MCP⁩ را جهت اتصال پایگاه‌های داده، ⁦API⁩ها و ابزارهای اختصاصی به پلوک متصل فرمایید. پیکربندی سرورها در مسیر ⁦Settings⁩ → ⁦MCP⁩ انجام می‌شود و عامل هوشمند در حین اجرا به طور خودکار ابزارها را شناسایی می‌کند.

مهارت‌ها (⁦Skills⁩)

مهارت‌ها بسته‌های آماده‌ای از دستورالعمل‌ها و فرآیندهای کاری هستند که عامل هوشمند می‌تواند از آن‌ها برای وظایف تخصصی (مانند مراحل استقرار، چک‌لیست بازبینی کد یا استانداردهای فریم‌ورک‌ها) استفاده کند.

قلاب‌ها (⁦Hooks⁩)

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

پلاگین‌ها (⁦Plugins⁩)

پلاگین‌ها تنظیمات، ابزارها و پرامپت‌های مرتبط با هم را در قالب یک بسته منسجم ارائه می‌دهند. شما می‌توانید آن‌ها را در مسیر ⁦Settings⁩ → ⁦Plugins⁩ مدیریت کنید.

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

حالت اعلان

• تنظیمات پلوک → اعلان‌ها
• خاموش، بدون اعلان ⁦OS⁩ برای چت
• وقتی پلوک در پس‌زمینه است، فقط وقتی برنامه دیگر فعال است (پیشنهادی)
• همیشه، حتی وقتی پنجره پلوک فعال است

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

• بخش ⁦General⁩ (عمومی): مدیریت حساب کاربری، انتخاب تم‌ها، کلیدهای میانبر و درون‌ریزی تنظیمات از ⁦VS Code.⁩
• بخش ⁦Plan⁩ & ⁦Usage⁩ (طرح و مصرف): وضعیت طرح، سهمیه ماهانه، ارتقا و داشبورد وب.
• بخش ⁦Models⁩ (مدل‌ها): کاتالوگ مدل‌ها و پیش‌فرض‌ها.
• بخش ⁦Notifications⁩ (اعلان‌ها): حالت اعلان ⁦OS⁩، صداها و اعلان‌ها
• بخش ⁦Indexing⁩ & ⁦Docs⁩: وضعیت ایندکس، ⁦.palvakignore⁩، منابع ⁦Docs⁩ و کش ⁦Grep/Glob.⁩
• آیکون چرخ‌دنده (چت) → ⁦Configure Tools⁩؛ ⁦Permissions⁩: ابزارها و تأیید

• کلیدهای ⁦Ctrl⁩+⁦Shift⁩+⁦P⁩: باز کردن پالت دستورات (⁦Command Palette⁩).
• کلیدهای ⁦Ctrl⁩+⁦L⁩: تمرکز و قرار دادن فوکوس روی بخش میز کار عامل (پنل چت).
• کلیدهای ⁦Ctrl⁩+⁦Shift⁩+⁦I⁩: نمایش یا پنهان کردن پنل میز کار عامل.
• کلیدهای ⁦Alt⁩+\: درخواست دستی پیشنهاد تکمیل تب (⁦Tab completions⁩).
• کلیدهای ⁦Ctrl⁩+⁦K Ctrl⁩+⁦S⁩: باز کردن ویرایشگر اختصاصی کلیدهای میانبر صفحه‌کلید.

در زمان راه‌اندازی اولیه، پلوک به شما امکان می‌دهد کلیدهای میانبر محبوب خود را به راحتی از نرم‌افزارهای ⁦VS Code⁩، ⁦IntelliJ⁩، ⁦Vim⁩، ⁦Sublime⁩ و دیگر ویرایشگرها وارد کنید.

طرح رایگان شامل مدل‌های اصلی، ایندکس محلی کدبیس و ⁦Agent Desk⁩ است⁦. Pro⁩ ایندکس معنایی ابری، مدل‌های ویژه و امکانات کامل را باز می‌کند؛ ⁦Plus⁩ سهمیه ماهانه بالاتر دارد.

شما می‌توانید میزان مصرف خود را به صورت زنده در مسیر ⁦Settings⁩ → ⁦Plan⁩ & ⁦Usage⁩ یا در داشبورد مدیریت وب‌سایت مشاهده کنید. دکمه‌های ارتقا به طور خودکار صفحه قیمت‌گذاری را در بافتار حساب کاربری شما باز می‌کنند.

نسخه‌های پایدار ویندوز از قابلیت به‌روزرسانی خودکار درون‌برنامه‌ای (منوی ⁦Help⁩ → ⁦Check for Updates⁩) پشتیبانی می‌کنند. کاربران سیستم‌عامل لینوکس نیز می‌توانند آخرین فایل‌های نصب با فرمت ⁦.deb⁩ یا ⁦AppImage⁩ را از صفحه دانلود وب‌سایت دریافت کنند.

خطا در ورود به حساب کاربری یا انتقال توکن دسترسی

• اتصال شبکه خود را بررسی کرده و مطمئن شوید وب‌سایت ⁦palvak.com⁩ در دسترس است.
• فرآیند ورود را دوباره امتحان فرمایید؛ در صورت لزوم کوکی‌ها و جلسات فعال را پاک کرده و مجدداً لاگین کنید.

بروز خطا در چت یا عدم نمایش مدل‌ها

• سهمیه ماهانه را در ⁦Settings⁩ → ⁦Plan⁩ & ⁦Usage⁩ بررسی کنید.
• در صورت قطعی موقت، ⁦MiMo-V2.6-Flash⁩، ⁦GLM-5.3-Flash⁩ یا مدل دیگری را امتحان کنید.

بروز خطای ۵۰۲ در همگام‌سازی ایندکس ابری

معمولاً اختلال موقت بک‌اند یا ارائه‌دهنده امبدینگ است. ایندکس محلی کار می‌کند؛ همگام‌سازی ابری پس از بهبود ⁦API⁩ خودکار در پس‌زمینه ادامه می‌یابد.

عدم نمایش تم‌ها یا افزونه‌های پیش‌فرض

پیشنهاد می‌شود نرم‌افزار را با دریافت فایل نصب جدید از وب‌سایت دانلود مجدداً نصب فرمایید. نسخه‌های پایدار رسمی همواره با بسته‌ای کامل از افزونه‌ها و تم‌های پیش‌فرض ارائه می‌شوند.

• فایل‌های منبع روی دستگاه شما می‌مانند؛ در ⁦Pro/Plus⁩ اثر انگشت امبدینگ برای جست‌وجوی ابری خودکار همگام می‌شود (نه آپلود کامل سورس).
• درخواست‌های چت شما به درگاه ⁦API⁩ پلوک و ارائه‌دهندگان مرجع هوش مصنوعی در قالب حساب کاربری خودتان ارسال می‌گردند.
• اجرای ابزارها (مانند کارهای ترمینال یا نوشتن فایل‌ها) همواره مستلزم تایید مستقیم شماست، مگر اینکه تنظیمات بخش ⁦Permissions⁩ را تغییر داده باشید.
• هرگز کلیدهای ⁦API⁩ شخصی خود را در مخزن کدهای پروژه کامیت نکنید؛ پیشنهاد می‌شود در سمت بک‌اند از فایل‌های ⁦.env⁩ و برای کاربران از سیستم احراز هویت یکپارچه ⁦IDE⁩ استفاده فرمایید.