Mahzad AI Developer — VS Code Extension
افزونهٔ ایجنت برنامه‌نویسی Mahzad AI برای VS Code. این افزونه نیمی از معماری
اکوسیستم است: سرور = مغز تصمیم‌گیر | افزونه = خواننده/نویسنده/اجراکننده.
استنتاج فقط سمت سرور انجام می‌شود.
⚠️ این افزونه سیستم کاربری یا اعتباری تکراری نمی‌سازد، API پولی را فعال
نمی‌کند و سایت اصلی را تغییر نمی‌دهد. احراز هویت از همان endpoint مرکزی
Sanctum موجود استفاده می‌کند.
قابلیت‌ها
| قابلیت |
توضیح |
| Chat |
رابط چت در sidebar؛ ارسال پیام به /api/v1/conversations مرکزی |
| تحلیل پروژه |
اسکن محلی workspace → Project Knowledge Map (زبان/فریم‌ورک/نقاط ورود) |
| ویرایش کد با Diff |
نمایش vscode.diff و تأیید صریح قبل از نوشتن فایل |
| اجرای دستور با تأیید |
اجرای دستور ترمینال فقط پس از تأیید مودال کاربر |
| ورود امن (حساب مشترک) |
ورود با همان ایمیل/موبایل + رمز سایت و اپ اندروید (POST /api/v1/auth/token)؛ توکن Sanctum فقط در SecretStorage سیستمی (OS keychain) |
| ثبت‌نام (v0.2.1) |
فرم ثبت‌نام حرفه‌ای در بخش حساب → POST /api/v1/auth/register روی همان جدول کاربران مرکزی؛ اگر سرور کد تأیید پیامکی بخواهد، مرحلهٔ «تأیید کد» (/auth/register/verify) نمایش داده می‌شود و توکن فقط پس از تأیید صادر می‌گردد |
| فراموشی رمز (v0.2.1) |
بازیابی با کد پیامکی مرکزی: POST /api/v1/auth/forgot-password سپس POST /api/v1/auth/reset-password؛ پاسخ سرور صادقانه و بدون افشای وجود/عدم وجود شماره است. بازیابی از طریق ایمیل زمانی فعال می‌شود که بک‌اند API آن را ارائه دهد |
| ورود اجتماعی Google/GitHub (v0.2.1) |
زیرساخت کامل OAuth 2.0 + PKCE (S256) با مرورگر خارجی و redirect حلقه‌برگشتی 127.0.0.1 آماده است، اما دکمه‌ها فقط وقتی فعال می‌شوند که سرور مرکزی GET /api/v1/auth/oauth/providers آن‌ها را ارائه دهد؛ تا آن زمان غیرفعال و همراه با توضیح صادقانه نمایش داده می‌شوند (هیچ حساب جداگانه‌ای ساخته نمی‌شود) |
| فرم ورود وب‌ویو (v0.2.3) |
دکمهٔ «ورود» (نوار وضعیت و Command Palette) اکنون مستقیماً فرم ورود واقعی وب‌ویو (ایمیل/موبایل + رمز عبور) را در سایدبار باز می‌کند؛ دسترسی با پیام ready همگام می‌شود تا درخواست بازشدن فرم هنگام بارگذاری اولیه گم نشود |
گیت‌های اتصال (مهم)
از نسخهٔ 0.2.0 دو گیت جدا داریم:
| گیت |
پیش‌فرض |
کنترل چه چیزی را دارد |
mahzadAI.authEnabled |
true |
ورود/خروج/اطلاعات حساب + ثبت‌نام و بازیابی رمز (v0.2.1) — endpointهای رایگان مرکزی (/auth/token, /auth/me, /auth/logout, /auth/register, /auth/forgot-password, /auth/reset-password)؛ حساب‌ها همان حساب‌های سایت و اپ اندروید است |
mahzadAI.liveRequestsEnabled |
false |
مسیر پولی گفتگوی AI (agents / conversations / messages) — تا وقتی روشن نشود هیچ درخواست گفتگویی ارسال نمی‌شود |
بنابراین کاربر می‌تواند با تنظیمات پیش‌فرض وارد حساب مشترک خود شود، بدون آنکه هیچ
درخواست پولی/گفتگویی فعال شود. برای فعال‌سازی گفتگوی زنده:
- Command Palette →
Preferences: Open Settings (UI)
- جستجو:
Mahzad AI
- روشن کردن
Live Requests Enabled (mahzadAI.liveRequestsEnabled)
یا در settings.json:
{
"mahzadAI.apiUrl": "https://testsite1.ir",
"mahzadAI.apiPrefix": "/api/v1",
"mahzadAI.authEnabled": true,
"mahzadAI.liveRequestsEnabled": false,
"mahzadAI.requireCommandApproval": true,
"mahzadAI.requireEditApproval": true
}
بازیابی نشست
هنگام فعال‌سازی افزونه، توکن ذخیره‌شده با GET /auth/me مرکزی بازیابی و
تازه‌سازی می‌شود. اگر توکن منقضی/باطل شده باشد، نشست محلی صادقانه پاک و پیام
«دوباره وارد شوید» نمایش داده می‌شود. خروج (/auth/logout) توکن همان دستگاه را
سمت سرور باطل می‌کند.
دستورات
| Command |
عنوان |
mahzadAI.login |
Mahzad AI: Sign In |
mahzadAI.logout |
Mahzad AI: Sign Out |
mahzadAI.account |
Mahzad AI: Account (منوی حساب: تازه‌سازی/خروج) |
mahzadAI.analyzeProject |
Mahzad AI: Analyze Current Project |
mahzadAI.runCommand |
Mahzad AI: Run Approved Command |
mahzadAI.editFile |
Mahzad AI: Propose Edit to Active File |
معماری (هم‌سبک android-app / desktop-agent)
src/
├─ extension.ts # نقطهٔ ورود: ثبت دستورات، sidebar، وضعیت
├─ config.ts # خواندن تنظیمات mahzadAI.* (گیت live)
├─ api/
│ └─ client.ts # ApiClient مرکزی (Bearer token, Idempotency, gate)
├─ auth/
│ └─ secretStore.ts # ذخیرهٔ امن توکن در SecretStorage (مثل Stronghold)
├─ agent/
│ ├─ projectAnalyzer.ts # اسکن محلی + Project Knowledge Map
│ ├─ commandRunner.ts # اجرای دستور با تأیید صریح
│ └─ codeEditor.ts # Diff + تأیید + نوشتن فایل
├─ chat/
│ ├─ ChatViewProvider.ts # میزبان Webview sidebar
│ └─ webview.html # رابط چت (RTL، CSP سخت‌گیرانه)
└─ media/
└─ icon.svg # آیکون activity bar
ساخت و بسته‌بندی
npm install # نصب وابستگی‌ها (شامل @vscode/vsce)
npm run compile # tsc + کپی webview.html و آیکون به out/
npm run package # ساخت mahzad-ai-developer-<version>.vsix
نصب و به‌روزرسانی برای کاربران (روش رسمی)
کاربران فقط از Visual Studio Marketplace نصب می‌کنند؛ نیازی به دانلود دستی فایل VSIX نیست:
Ctrl+Shift+X → جستجوی Mahzad AI → Install- به‌روزرسانی خودکار: پس از انتشار نسخهٔ جدید در Marketplace، خودِ VS Code آن را
دانلود و نصب می‌کند (
extensions.autoUpdate پیش‌فرض روشن است). کاربر برای دریافت
نسخه‌های بعدی هیچ کار دستی انجام نمی‌دهد.
نصب VSIX (فقط توسعه‌دهندگان / تست محلی)
نصب دستی VSIX از به‌روزرسانی خودکار Marketplace برخوردار نیست:
code --install-extension mahzad-ai-developer-<version>.vsix
یا در VS Code: Extensions: Install from VSIX...
انتشار نسخهٔ جدید (توسعه‌دهندگان)
npm run bump:patch # یا bump:minor / bump:major — افزایش نسخه
npm run release:prepare # اعتبارسنجی + تست + ساخت VSIX (بدون انتشار)
# → تأیید صریح مالک →
npm run publish:marketplace # انتشار در همان صفحهٔ Marketplace
جزئیات کامل و نکات امنیتی توکن: PUBLISHING.md
نکات امنیتی
- هیچ رمز/کلید API در کد ذخیره نمی‌شود؛ فقط توکن Sanctum در SecretStorage.
- رمز عبور هرگز ذخیره یا لاگ نمی‌شود — یک‌بار روی HTTPS ارسال و بلافاصله از
وب‌ویو هم پاک می‌شود؛ توکن هم هیچ‌جا در لاگ نمی‌آید (با تست خودکار پوشش داده شده).
- ورود هیچ کاربر/دیتابیس جداگانه‌ای نمی‌سازد؛ همان جدول کاربران سایت (Sanctum).
- اجرای دستور و ویرایش فایل همیشه نیاز به تأیید صریح کاربر دارند.
liveRequestsEnabled=false تا وقتی مالک روشن نکرده — هیچ درخواست گفتگویی ارسال نمی‌شود.
تست
npm test # تست‌های محلی (شامل جریان کامل ورود/خروج/بازیابی نشست روی استاب همان قرارداد)
npm run test:live # بررسی قرارداد واقعی endpointهای احراز هویت محیط تست (بدون حساب معتبر)
npm run test:live-login # تست ورود واقعی با حساب مشترک (نیازمند MAHZAD_TEST_LOGIN و MAHZAD_TEST_PASSWORD)
