مرکزی مواد پر جائیں
اے آئی ٹیوٹوریلز

ZCode ڈویلپمنٹ ٹیوٹوریل: ڈیسک ٹاپ، ویب اور ٹرمینل AI کوڈنگ ورک بینچ ترتیب دینا

یہ ٹیوٹوریل ZCode ڈویلپمنٹ ماحول ترتیب دینے، Electron ڈیسک ٹاپ ایپ، ویب ورک بینچ اور Agent CLI چلانے، اور ریموٹ وسائل، رسائی کی توثیق اور ریلیز پیکیجز کو مزید ترتیب دینے کا طریقہ بیان کرتا ہے۔

تقریباً 27 منٹ کا مطالعہ
ZCode ڈویلپمنٹ ٹیوٹوریل: ڈیسک ٹاپ، ویب اور ٹرمینل AI کوڈنگ ورک بینچ

ZCode کا تعارف

ZCode پروجیکٹ کا لوگو

ZCode ایک AI پروگرامنگ ورک بینچ ہے، جو Electron ڈیسک ٹاپ ایپ، براؤزر انٹرفیس اور ٹرمینل Agent فراہم کرتا ہے۔ ریپوزٹری کو workspace کی صورت میں منظم کیا گیا ہے، جس میں کلائنٹ، بیک اینڈ سروسز، مشترکہ UI، Agent CLI، TUI اور رن ٹائم سورس کوڈ مرکزی طور پر برقرار رکھا جاتا ہے۔

پروجیکٹ تین بنیادی ترقیاتی راستے فراہم کرتا ہے:

  • Desktop: Electron ڈیسک ٹاپ ایپ، جسے pnpm dev:desktop سے شروع کیا جاتا ہے۔
  • Web: براؤزر ورک بینچ اور مقامی بیک اینڈ کو بیک وقت شروع کرتا ہے، pnpm dev:web استعمال کریں۔
  • Agent CLI: ٹرمینل Agent یا TUI کی براہِ راست ترقی کے لیے، pnpm --filter @zcode/cli dev استعمال کریں۔

اس کے علاوہ ZCode کو متحدہ کمانڈ لائن ڈسٹری بیوشن پیکیج میں بھی بنایا جا سکتا ہے۔ انسٹالیشن کے بعد TUI میں داخل ہونے کے لیے zcode چلائیں، جبکہ مقامی Web ورک بینچ شروع کرنے کے لیے zcode --web چلائیں۔

اہم خصوصیات

  • ڈیسک ٹاپ، براؤزر اور ٹرمینل کے ذریعے استعمال کی سہولت۔
  • Web فرنٹ اینڈ، HTTP/WebSocket بیک اینڈ اور Agent مقامی طور پر مکمل ورک فلو تشکیل دے سکتے ہیں۔
  • Desktop اور Web مشترکہ Agent CLI رن ٹائم استعمال کرتے ہیں۔
  • SSH، WSL اور دیگر ریموٹ ورک اسپیسز میں ترقی کی معاونت۔
  • مشترکہ React components، hooks، Zustand state، پروٹوکول اقسام، RPC framework اور Agent client SDK۔
  • ڈیسک ٹاپ انسٹالر اور متحدہ ZCode کمانڈ لائن ڈسٹری بیوشن پیکیج الگ الگ بنائے جا سکتے ہیں۔
  • Web کو بیرونی طور پر سننے پر خودکار رسائی ٹوکن تیار کیا جا سکتا ہے، یا authentication token واضح طور پر ترتیب دیا جا سکتا ہے۔

ترقیاتی ماحول کی تیاری

ضروری ٹولز انسٹال کریں

شروع کرنے سے پہلے درج ذیل ٹولز تیار کریں۔ درست ورژن ریپوزٹری کی جڑ میں موجود mise.toml کے مطابق ہیں:

  • Git
  • Node.js 24.14.0
  • pnpm 10.33.2

ریپوزٹری کلون کرکے جڑ والے فولڈر میں جانے کے بعد تجویز کردہ ابتدائی کمانڈ چلائیں:

pnpm bootstrap

pnpm bootstrap workspace dependencies انسٹال کرتا ہے، ڈیسک ٹاپ کے مقامی رن ٹائم وسائل تیار کرتا ہے، اور build:bootstrap چلاتا ہے۔ Agent CLI اور رن ٹائم پہلے ہی apps/zcode-cli/ میں موجود ہیں، اس لیے Git submodule کی اضافی ابتدا ضروری نہیں۔

ڈیفالٹ bootstrap ریموٹ وسائل کی تیاری چھوڑ دیتا ہے، اس لیے یہ مقامی ڈیسک ٹاپ ترقی کے لیے زیادہ موزوں ہے۔ SSH، WSL یا ریموٹ ڈسٹری بیوشن وسائل درکار ہوں تو ہی ریموٹ وسائل سے متعلق کمانڈ چلائیں۔

ضرورت کے مطابق ابتدائی کمانڈ منتخب کریں

  • pnpm install：صرف dependencies انسٹال کرتا ہے۔
  • pnpm prepare:desktop-runtime：ڈیسک ٹاپ رن ٹائم وسائل تیار کرتا ہے، جس میں ڈیفالٹ طور پر ریموٹ وسائل بھی شامل ہیں۔
  • pnpm prepare:remote-assets：صرف ریموٹ رن ٹائم وسائل تیار کرتا ہے۔
  • pnpm bootstrap:with-remote：dependencies، مقامی اور ریموٹ وسائل کو تیار کرتا ہے، متعلقہ پیکیجز کو سلسلہ وار بناتا ہے، لیکن ڈیسک ٹاپ ایپ bundle چھوڑ دیتا ہے۔
  • pnpm build：تمام workspace پیکیجز کے build scripts کو recursively چلاتا ہے، جن میں پیکیج کے اندر وسائل کی تیاری بھی شامل ہے۔

ڈیسک ٹاپ ورژن چلانا

ابتدائی تیاری مکمل ہونے کے بعد ریپوزٹری کی جڑ سے Electron ڈیسک ٹاپ ایپ شروع کریں:

pnpm dev:desktop

pnpm dev:desktop ڈیفالٹ طور پر pnpm dev:desktop:prod کے مساوی ہے اور production service configuration استعمال کرتا ہے۔ آغاز کی اسکرپٹ مقامی رن ٹائم وسائل تیار کرتی ہے، ڈیسک ٹاپ Agent بناتی ہے، پھر Electron اور source watcher شروع کرتی ہے۔

ٹیسٹ ماحول استعمال کرنے کے لیے یہ کمانڈ چلائیں:

pnpm dev:desktop:test

ترقیاتی ڈیٹا الگ رکھیں

ترقیاتی ڈیٹا کو روزمرہ استعمال کے ڈیٹا کے ساتھ ملنے سے روکنے کے لیے ZCODE_DATA_BASE_DIR کے ذریعے الگ data base directory مقرر کی جا سکتی ہے۔ ایپ کا ڈیٹا اس فولڈر کے اندر .zcode/ میں لکھا جائے گا:

ZCODE_DATA_BASE_DIR="$HOME/.zcode-dev-home" pnpm dev:desktop:test

یہ طریقہ macOS اور Linux کے لیے موزوں ہے۔

Web ورک بینچ چلانا

Web فرنٹ اینڈ یا بیک اینڈ سورس میں ترمیم کرتے وقت مشترکہ ترقیاتی موڈ تجویز کیا جاتا ہے:

pnpm dev:web

یہ کمانڈ بیک وقت شروع کرے گی:

  • Web development server، جس کا ڈیفالٹ پتہ http://localhost:5173 ہے۔
  • مقامی بیک اینڈ، جس کا ڈیفالٹ پتہ http://localhost:3030 ہے۔

براؤزر میں فرنٹ اینڈ کا پتہ کھولیں۔ development server /ws اور عام /api درخواستوں کو مقامی بیک اینڈ پر proxy کرے گا؛ /api/v1/oauth/token کو موجودہ configured product service پر الگ proxy کیا جائے گا۔

بیک اینڈ ورک اسپیس مقرر کریں

macOS یا Linux میں environment variable کے ذریعے Web بیک اینڈ کے لیے پروجیکٹ فولڈر مقرر کیا جا سکتا ہے:

ZCODE_SERVER_WORKSPACE=/path/to/project pnpm dev:web

Agent سورس میں ترمیم کے بعد CLI اور اس کی workspace dependencies کو دوبارہ بنائیں، پھر سروس restart کریں:

pnpm --filter @zcode/cli... build

Agent CLI اور TUI کی ترقی

اگر بنیادی کام ٹرمینل انٹرفیس یا Agent پر ہو تو سورس entry point براہِ راست چلایا جا سکتا ہے:

pnpm --filter @zcode/cli dev --help
pnpm --filter @zcode/cli dev

CLI اور اس کی dependencies بنانے کے بعد تیار شدہ CommonJS فائل بھی براہِ راست چلائی جا سکتی ہے:

pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --help

یہ source entry point براہِ راست Agent CLI چلاتا ہے اور متحدہ distribution command میں موجود --web routing نہیں چلاتا۔ Web کی ترقی کے لیے pnpm dev:web استعمال کریں؛ متحدہ zcode کمانڈ کی جانچ کے لیے کمانڈ لائن distribution package بنائیں اور extract کریں۔

ZCode کمانڈ لائن ورژن استعمال کرنا

کمانڈ لائن distribution package TUI، Web، بیک اینڈ اور Agent کو یکجا کرتا ہے اور سب کو zcode کے ذریعے شروع کرتا ہے۔ یہ Electron پر منحصر نہیں، لیکن رن ٹائم کے لیے پھر بھی mise.toml کے تقاضوں کے مطابق Node.js درکار ہے۔

بنیادی کمانڈز

# ٹرمینل interactive interface میں داخل ہوں
zcode

# Web ورک بینچ شروع کریں
zcode --web

# پروجیکٹ اور پورٹ مقرر کریں، اور براؤزر خودکار طور پر کھولنے سے روکیں
zcode --web --workspace /path/to/project --port 3030 --no-open

# مدد دیکھیں
zcode --help
zcode --web --help

Web موڈ ڈیفالٹ طور پر موجودہ فولڈر کو working directory، 127.0.0.1 کو listening address، اور خودکار طور پر دستیاب پورٹ کو استعمال کرتا ہے، پھر براؤزر کھولتا ہے۔ ڈیفالٹ طور پر access token فعال نہیں ہوتا۔ کام مکمل ہونے پر ٹرمینل میں Ctrl+C دباکر سروس روک دیں۔

مقامی نیٹ ورک سے رسائی

دیگر آلات کو رسائی دینے کے لیے listening address کو 0.0.0.0 پر تبدیل کریں:

zcode --web --host 0.0.0.0

جب مقامی مشین کے علاوہ کسی address پر listening ہو تو ZCode ڈیفالٹ طور پر access token تیار کرتا ہے۔ سروس تک رسائی کے لیے ٹرمینل میں دکھائے گئے token والے link کا استعمال کریں۔ --token کے ذریعے token مقرر کیا جا سکتا ہے، یا --no-token کے ذریعے token authentication بند کی جا سکتی ہے۔

عمومی Web service کا HTTP entry point براہِ راست شروع کرتے وقت API اور WebSocket authentication کو ZCODE_SERVER_AUTH_TOKEN کے ذریعے مقرر کیا جا سکتا ہے؛ programmatic interface سے service بناتے وقت authToken option استعمال کریں۔

Environment variables ترتیب دیں

ریپوزٹری کی جڑ میں موجود .env.example service addresses اور build configuration کی مثال فراہم کرتی ہے۔ ضرورت کے مطابق اسے .env میں کاپی کریں، اور صرف مقامی استعمال کے overrides کو .env.local میں رکھیں۔

  • ZCODE_DATA_BASE_DIR：ایپ کی data base directory؛ ڈیٹا اس کے اندر .zcode/ میں لکھا جاتا ہے۔
  • ZCODE_SERVER_WORKSPACE：Web بیک اینڈ workspace path مقرر کرتا ہے۔
  • ZCODE_BUILTIN_PROVIDER_CONFIG_FILE：مقامی Provider configuration file مقرر کرتا ہے؛ مقرر نہ ہونے پر built-in configuration استعمال ہوتی ہے۔
  • ZCODE_DIST_BASE_URL：کمانڈ لائن installation script کے ذریعے استعمال ہونے والا download base address۔

یہ runtime variables براہِ راست startup command کے environment میں بھی رکھی جا سکتی ہیں۔ Desktop کی development service configuration کا انتخاب dev:desktop:test اور dev:desktop:prod کے ذریعے کیا جاتا ہے۔

SSH اور WSL ریموٹ خصوصیات کی ترقی

ریموٹ workspace خصوصیات پر کام کرنے سے پہلے ریموٹ وسائل تیار کریں:

pnpm bootstrap:with-remote
pnpm dev:desktop

ریموٹ پروجیکٹ سے جڑتے وقت resource option "مقامی طور پر ڈاؤن لوڈ کرکے upload کریں" منتخب کریں۔ development environment مقامی packages/desktop/mock-cdn اور مقامی build output سے وسائل حاصل کرتا ہے، پھر انہیں SFTP کے ذریعے ریموٹ host پر upload کرتا ہے؛ CDN تک رسائی نہیں کی جاتی۔

ڈیسک ٹاپ انسٹالر بنائیں

ڈیسک ٹاپ ورژن بنانے کے لیے یہ کمانڈ چلائیں:

pnpm bundle:desktop

ڈیفالٹ target macOS arm64 ہے، اور output directory packages/desktop/dist/ ہے۔ operating system اور CPU architecture بھی مقرر کیے جا سکتے ہیں:

pnpm bundle:desktop -- --os win --arch x64
pnpm bundle:desktop -- --help

--os میں mac، win اور linux، جبکہ --arch میں x64 اور arm64 شامل ہیں۔ حقیقی packaging اور signing کے لیے target platform کے متعلقہ tools اور configuration پھر بھی درکار ہوں گے۔

macOS پر تیار شدہ DMG کھولیں اور ZCode کو Applications میں drag کریں۔ اگر مقامی unsigned build پہلی بار شروع کرتے وقت سسٹم روک دے تو یہ کمانڈ چلائیں:

sudo xattr -rd com.apple.quarantine /Applications/ZCode.app

کمانڈ لائن distribution package بنائیں

کمانڈ لائن distribution package کا build entry point pnpm build:zcode ہے۔ build سے پہلے download base address ZCODE_DIST_BASE_URL مقرر کرنا ضروری ہے، یا اسے --base-url کے ذریعے براہِ راست فراہم کیا جا سکتا ہے:

pnpm build:zcode --base-url https://downloads.example.com/zcode/

# جب ZCODE_DIST_BASE_URL پہلے سے تشکیل شدہ ہو
pnpm build:zcode

# موجودہ build artifacts دوبارہ استعمال کریں، صرف پیکیجنگ کریں
pnpm build:zcode --skip-build

# اختیاری پیرامیٹرز دیکھیں
pnpm build:zcode --help

اس میں موجود ڈاؤن لوڈ URL صرف ایک عارضی مثال ہے؛ حتمی ریلیز کے وقت اسے حقیقی میزبانی کے پتے سے تبدیل کرنا ضروری ہے۔ build script بالترتیب CLI/TUI، backend اور Web کو پروسیس کرتی ہے، native libraries، workers اور runtime dependencies جمع کرتی ہے، پھر release package تیار کرتی ہے۔

ڈیفالٹ ورژن root directory کی package.json سے لیا جاتا ہے، جبکہ output directory dist/zcode/ ہے، جس میں شامل ہیں:

  • releases/<version>/zcode-<version>.tar.gz: runtime package۔
  • releases/<version>/sha256.txt: checksum digest۔
  • latest.json: ورژن index۔
  • install.sh: installation script۔

installation script ڈیفالٹ طور پر runtime کو ~/.zcode/runtime میں install کرتی ہے اور ~/.local/bin میں zcode command بناتی ہے۔ آپ بالترتیب ZCODE_DIST_HOME اور ZCODE_DIST_BIN_DIR کے ذریعے ان دونوں مقامات کو تبدیل کر سکتے ہیں۔

لوکل طور پر release package کی تصدیق

فائلیں upload کیے یا installation script چلائے بغیر بھی آپ build result کو براہِ راست extract کرکے چلا سکتے ہیں:

zcode_version=$(node -p "require('./dist/zcode/latest.json').version")
mkdir -p dist/zcode/debug
tar -xzf "dist/zcode/releases/$zcode_version/zcode-$zcode_version.tar.gz" \
  -C dist/zcode/debug

# TUI شروع کریں
node dist/zcode/debug/zcode/bin/zcode.mjs

# Web شروع کریں
node dist/zcode/debug/zcode/bin/zcode.mjs --web \
  --workspace "$PWD" --port 3030 --no-open

اس کے بعد http://127.0.0.1:3030 کھولیں تاکہ اسی backend کے زیرِ میزبانی Web page اور Agent کے مکمل flow کی تصدیق کی جا سکے۔ پورٹ خالی ہونی چاہیے؛ اگر pnpm dev:web پہلے سے یہ پورٹ استعمال کر رہا ہو تو --port کے ذریعے کوئی دوسری پورٹ منتخب کریں۔

اعلیٰ درجے کی development تجاویز

  1. متعلقہ entry point کو ترجیح دیں: desktop features کے لیے dev:desktop، frontend اور backend integration testing کے لیے dev:web، جبکہ Agent اور TUI کے لیے CLI workspace کا dev command استعمال کریں۔
  2. Agent میں ترمیم کے بعد دوبارہ build کریں: Web service خودکار طور پر Agent کے تمام build results حاصل نہیں کرے گی؛ ترمیم کے بعد pnpm --filter @zcode/cli... build چلائیں اور service restart کریں۔
  3. Test data الگ رکھیں: مختلف development scenarios کے لیے ZCODE_DATA_BASE_DIR کے ذریعے الگ data directories بنائیں۔
  4. بیرونی listening کے وقت authentication برقرار رکھیں: --host 0.0.0.0 استعمال کرنے کے بعد خودکار طور پر بننے والے token کو برقرار رکھیں یا واضح طور پر --token مقرر کریں۔
  5. Command کا ماخذ چیک کریں: pnpm build:zcode صرف release package بناتا ہے، یہ system PATH میں موجود پہلے سے قائم zcode کو replace نہیں کرتا۔ macOS اور Linux پر command -v zcode، جبکہ Windows پر where.exe zcode چلایا جا سکتا ہے۔
  6. Development اور release verification میں فرق رکھیں: pnpm dev:web source code iteration کے لیے موزوں ہے؛ extract کیا گیا bin/zcode.mjs حتمی unified command اور مکمل release flow کی تصدیق کے لیے زیادہ موزوں ہے۔

Repository structure کا جائزہ

  • packages/desktop: Electron Main، Host، Renderer اور desktop packaging۔
  • packages/web: Web client۔
  • packages/server: HTTP، WebSocket services اور remote connections۔
  • packages/zcode-server-cli: standalone Server startup اور process management۔
  • packages/ui: مشترکہ React components، hooks اور Zustand state۔
  • packages/services: business services اور persistence۔
  • packages/shared، packages/rpc، packages/client: shared protocols اور types، RPC framework، اور Agent client SDK۔
  • packages/provider، packages/provider-node: Provider کی عمومی صلاحیتیں اور Node.js implementation۔
  • apps/zcode-cli: Agent CLI، TUI، runtime اور tools۔
  • scripts، config، third-party: build maintenance scripts، built-in configuration اور third-party declaration materials۔

خلاصہ

ZCode desktop، Web، backend اور Agent CLI کو ایک ہی workspace میں مربوط کرتا ہے۔ پہلی مرتبہ development شروع کرتے وقت pnpm bootstrap چلائیں، پھر اپنے مقصد کے مطابق pnpm dev:desktop، pnpm dev:web یا CLI source entry point منتخب کریں۔ Remote workspace کی testing یا باقاعدہ release کی ضرورت ہو تو remote resources تیار کرکے متعلقہ desktop یا command-line installation package build کریں۔