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

پلوک (پَلوَک) یک دستیار هوشمند و بومی برنامه‌نویسی دسکتاپ بر پایه یک ویرایشگر آشنا و محبوب است. بخش‌های چت، عامل‌های هوشمند، تکمیل تب (⁦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⁩، برای تحقیق و تدوین کارهای پیش از کدنویسی از حالت ⁦Plan⁩، و برای سپردن کارهای اجرایی چندمرحله‌ای به سیستم از حالت ⁦Agent⁩ استفاده فرمایید.

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

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

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

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

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

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

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

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

• مدل‌های ⁦MiMo V2.5 / V2.5 Pro⁩: مدل‌های اختصاصی پیش‌فرض پلوک با کارایی بسیار بالا و هزینه کاملاً اقتصادی.
• ⁦Muse Spark 1.2 Contributor⁩: مدل عامل ⁦Meta⁩ با زمینه ۱⁦M⁩، فراخوانی ابزار، و سطح ⁦Reasoning effort⁩ قابل تنظیم (کم، متوسط، زیاد، بسیار زیاد)، طرح ⁦Pro⁩

مدل پیش‌فرض

مدل انتخاب‌شده شما برای هر جلسه کاری به خاطر سپرده می‌شود. طرح رایگان شامل ⁦MiMo V2.5⁩ است؛ طرح ⁦Pro⁩ مدل‌های ⁦MiMo V2.5 Pro⁩ و ⁦Muse Spark 1.2 Contributor⁩ را باز می‌کند؛ طرح ⁦Plus⁩ سهمیه ماهانه بالاتری اضافه می‌نماید.

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

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

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

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

بخش تنظیمات در مسیر ⁦Settings⁩ → ⁦Indexing⁩ & ⁦Docs⁩

• گزینه ⁦Sync⁩ (همگام‌سازی): ارسال بخش‌های پردازش‌شده محلی به ایندکس ابری شما.
• گزینه ⁦Delete Index⁩ (حذف ایندکس): پاک کردن کامل بردارها و متاداده‌های ابری متعلق به فضای کاری فعلی.
• گزینه ⁦Index new folders⁩ (ایندکس پوشه‌های جدید): مدیریت ریشه‌های اصلی پروژه که نیاز به اسکن دارند.
• فایل ⁦palvakignore.⁩: استثنا کردن مسیرها و پوشه‌های دلخواه از فرآیند جستجو (مشابه اصول کارکرد فایل ⁦.gitignore⁩).

قابلیت جستجوی سریع (⁦Instant Grep⁩)

یک سیستم جستجوی متنی فوق‌العاده سریع اختیاری که مکمل فرآیند بازیابی معنایی است. این قابلیت را در بخش ⁦Indexing⁩ & ⁦Docs⁩ فعال فرمایید تا از سرعتی معادل ابزار ⁦ripgrep⁩ در تعیین بافتار کار عامل بهره‌مند شوید.

در مسیر ⁦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⁩ مدیریت کنید.

• بخش ⁦General⁩ (عمومی): مدیریت حساب کاربری، انتخاب تم‌ها، کلیدهای میانبر و درون‌ریزی تنظیمات از ⁦VS Code.⁩
• بخش ⁦Plan⁩ & ⁦Usage⁩ (طرح و مصرف): پایش میزان توکن‌های مصرف‌شده، ارتقای طرح اشتراک و دسترسی به داشبورد مدیریت وب.
• بخش ⁦Models⁩ (مدل‌ها): کاتالوگ جامع مدل‌های هوش مصنوعی و تعیین مدل پیش‌فرض.
• بخش ⁦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⁩ و دیگر ویرایشگرها وارد کنید.

طرح رایگان (⁦Free⁩) شامل سهمیه توکن ماهانه مشخصی جهت آشنایی با پلوک است. طرح ⁦Pro⁩ تمامی امکانات پیشرفته را باز می‌کند و طرح ⁦Plus⁩ حجم توکن به مراتب بالاتری (به همراه تکمیل تب نامحدود) ارائه می‌دهد.

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

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

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

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

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

• سهمیه توکن‌های خود را در مسیر ⁦Settings⁩ → ⁦Plan⁩ & ⁦Usage⁩ بررسی فرمایید.
• در صورتی که ارائه‌دهنده اصلی با قطعی موقت مواجه شده است، مدل را به ⁦MiMo⁩ یا مدل فعال دیگری تغییر دهید.

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

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

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

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

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