ZCode dasturlash bo‘yicha qo‘llanma: desktop, Web va terminal AI dasturlash ish muhitini sozlash

ZCode bilan tanishish

ZCode — AI dasturlash ish stansiyasi bo‘lib, Electron ish stoli ilovasi, brauzer interfeysi va terminal Agent’ni taqdim etadi. Repozitoriy workspace shaklida tashkil etilgan bo‘lib, mijoz, backend xizmatlari, umumiy UI, Agent CLI, TUI va runtime manba kodlari markazlashgan holda boshqariladi.

Loyiha uchta asosiy ishlab chiqish kirish nuqtasini taqdim etadi:

• Desktop: Electron ish stoli ilovasi, pnpm dev:desktop orqali ishga tushiriladi.
• Web: brauzer ish stansiyasi va mahalliy backend’ni bir vaqtda ishga tushiradi, pnpm dev:web buyrug‘idan foydalaniladi.
• Agent CLI: terminal Agent yoki TUI’ni bevosita ishlab chiqish, pnpm --filter @zcode/cli dev buyrug‘idan foydalaniladi.

Bundan tashqari, ZCode yagona buyruq qatori distributivi sifatida ham yig‘ilishi mumkin. O‘rnatilgandan so‘ng zcode buyrug‘i TUI’ni ochadi, zcode --web esa mahalliy Web ish stansiyasini ishga tushiradi.

Asosiy xususiyatlar

• Ish stoli, brauzer va terminaldan foydalanishning uchta usulini taqdim etadi.
• Web frontend, HTTP/WebSocket backend va Agent mahalliy kompyuterda to‘liq ish zanjirini tashkil qilishi mumkin.
• Desktop va Web umumiy Agent CLI runtime’dan foydalanadi.
• SSH, WSL va boshqa masofaviy workspace’larda ishlab chiqishni qo‘llab-quvvatlaydi.
• Umumiy React komponentlari, hooks, Zustand holati, protokol turlari, RPC freymvorki va Agent mijoz SDK’ini taqdim etadi.
• Ish stoli o‘rnatish paketi va yagona ZCode buyruq qatori distributivini alohida yig‘ish mumkin.
• Web tashqi manzilda tinglaganda kirish tokenini avtomatik yaratishi, shuningdek autentifikatsiya tokenini aniq sozlashni qo‘llab-quvvatlaydi.

Ishlab chiqish muhitini tayyorlash

Zarur vositalarni o‘rnatish

Boshlashdan oldin quyidagi vositalarni tayyorlang. Aniq versiyalar repozitoriy ildiz katalogidagi mise.toml faylida ko‘rsatilgan:

• Git
• Node.js 24.14.0
• pnpm 10.33.2

Repozitoriyni klonlab, ildiz katalogiga kirgandan so‘ng tavsiya etilgan ishga tushirish buyrug‘ini bajaring:

pnpm bootstrap

pnpm bootstrap workspace bog‘liqliklarini o‘rnatadi, ish stoli uchun mahalliy runtime resurslarini tayyorlaydi va build:bootstrap buyrug‘ini bajaradi. Agent CLI va runtime allaqachon apps/zcode-cli/ katalogida joylashgan, qo‘shimcha Git submodule ishga tushirish talab etilmaydi.

Standart bootstrap masofaviy resurslarni tayyorlashni o‘tkazib yuboradi, shuning uchun mahalliy ish stoli ishlab chiqishiga mos keladi. SSH, WSL yoki masofaviy distributiv resurslari kerak bo‘lgandagina masofaviy resurslarga oid buyruqlarni bajarish kerak.

Zaruratga ko‘ra ishga tushirish buyrug‘ini tanlash

• pnpm install: faqat bog‘liqliklarni o‘rnatadi.
• pnpm prepare:desktop-runtime: ish stoli runtime resurslarini tayyorlaydi, sukut bo‘yicha masofaviy resurslarni ham tayyorlaydi.
• pnpm prepare:remote-assets: masofaviy runtime resurslarini alohida tayyorlaydi.
• pnpm bootstrap:with-remote: bog‘liqliklar, mahalliy va masofaviy resurslarni ishga tushiradi hamda tegishli paketlarni ketma-ket yig‘adi, ammo ish stoli ilovasi bundle’ini o‘tkazib yuboradi.
• pnpm build: barcha workspace paketlarining build skriptlarini, jumladan paket ichidagi resurslarni tayyorlash bosqichlarini rekursiv bajaradi.

Ish stoli versiyasini ishga tushirish

Tayyorlash yakunlangach, repozitoriy ildiz katalogida Electron ish stoli ilovasini ishga tushiring:

pnpm dev:desktop

pnpm dev:desktop sukut bo‘yicha pnpm dev:desktop:prod buyrug‘iga teng bo‘lib, production server konfiguratsiyasidan foydalanadi. Ishga tushirish skripti mahalliy runtime resurslarini tayyorlaydi, ish stoli Agent’ni yig‘adi, so‘ng Electron va manba kod kuzatuvini ishga tushiradi.

Test muhitidan foydalanmoqchi bo‘lsangiz, quyidagini bajaring:

pnpm dev:desktop:test

Ishlab chiqish ma’lumotlarini ajratish

Ishlab chiqish ma’lumotlarini kundalik foydalanish ma’lumotlari bilan aralashtirib yubormaslik uchun ZCODE_DATA_BASE_DIR orqali alohida ma’lumotlar bazasi katalogini ko‘rsatish mumkin. Ilova ma’lumotlari ushbu katalogdagi .zcode/ ichiga yoziladi:

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

Ushbu yozuv macOS va Linux’da ishlaydi.

Web ish stansiyasini ishga tushirish

Web frontend yoki backend manba kodini o‘zgartirganda, birgalikdagi ishlab chiqish rejimidan foydalanish tavsiya etiladi:

pnpm dev:web

Ushbu buyruq quyidagilarni bir vaqtda ishga tushiradi:

• Web ishlab chiqish serveri, standart manzili http://localhost:5173.
• Mahalliy backend, standart manzili http://localhost:3030.

Brauzer frontend manziliga murojaat qilishi kerak. Ishlab chiqish serveri /ws va odatiy /api so‘rovlarini mahalliy backend’ka proksi qiladi; /api/v1/oauth/token esa joriy sozlangan mahsulot xizmatiga alohida proksi qilinadi.

Backend workspace’ini ko‘rsatish

macOS yoki Linux’da Web backend foydalanadigan loyiha katalogini muhit o‘zgaruvchisi orqali ko‘rsatish mumkin:

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

Agent manba kodiga o‘zgartirish kiritilgan bo‘lsa, CLI va uning workspace bog‘liqliklarini qayta yig‘ib, xizmatni qayta ishga tushiring:

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

Agent CLI va TUI’ni ishlab chiqish

Terminal interfeysi yoki Agent ustida asosan ishlayotgan bo‘lsangiz, manba kod kirish nuqtasini bevosita ishga tushirishingiz mumkin:

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

CLI va uning bog‘liqliklarini yig‘gandan so‘ng, yaratilgan CommonJS faylini ham bevosita ishga tushirish mumkin:

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

Ushbu manba kod kirish nuqtasi Agent CLI’ni bevosita ishga tushiradi va yagona distributiv buyrug‘idagi --web yo‘naltirishini bajarmaydi. Web’ni ishlab chiqish uchun pnpm dev:web buyrug‘idan foydalaning; yagona zcode buyrug‘ini test qilish uchun esa buyruq qatori distributivini yig‘ib, arxivdan chiqaring.

ZCode buyruq qatori versiyasidan foydalanish

Buyruq qatori distributivi TUI, Web, backend va Agent’ni birlashtiradi va ularning barchasi zcode orqali ishga tushiriladi. U Electron’ga bog‘liq emas, ammo runtime hali ham mise.toml talablariga mos Node.js’ni talab qiladi.

Asosiy buyruqlar

# Terminal interaktiv interfeysiga kirish
zcode

# Web ish stansiyasini ishga tushirish
zcode --web

# Loyiha va portni ko‘rsatish, brauzerni avtomatik ochishni taqiqlash
zcode --web --workspace /path/to/project --port 3030 --no-open

# Yordamni ko‘rish
zcode --help
zcode --web --help

Web rejimi sukut bo‘yicha joriy katalogni ish katalogi sifatida ishlatadi, 127.0.0.1 manzilida tinglaydi, bo‘sh portni avtomatik tanlaydi va brauzerni ochadi. Sukut bo‘yicha kirish tokeni yoqilmaydi. Foydalanishni tugatgach, xizmatni to‘xtatish uchun terminalda Ctrl+C tugmalarini bosing.

Mahalliy tarmoq orqali kirish

Boshqa qurilmalarga kirishga ruxsat berish kerak bo‘lsa, tinglash manzilini 0.0.0.0 ga o‘zgartiring:

zcode --web --host 0.0.0.0

Mahalliy bo‘lmagan manzilda tinglaganda, ZCode sukut bo‘yicha kirish tokenini yaratadi. Xizmatga terminal chiqishida ko‘rsatilgan tokenli havola orqali kiring. Shuningdek, tokenni --token orqali belgilash yoki --no-token orqali token autentifikatsiyasini o‘chirish mumkin.

Umumiy Web xizmatining HTTP kirish nuqtasini bevosita ishga tushirganda, API va WebSocket autentifikatsiyasini ZCODE_SERVER_AUTH_TOKEN orqali sozlash mumkin; dastur interfeysi orqali xizmat yaratilganda esa authToken opsiyasidan foydalaniladi.

Muhit o‘zgaruvchilarini sozlash

Repozitoriy ildiz katalogidagi .env.example xizmat manzillari va build konfiguratsiyasi namunalarini taqdim etadi. Uni zaruratga ko‘ra .env sifatida nusxalash va faqat mahalliy foydalaniladigan o‘zgartirishlarni .env.local fayliga joylashtirish mumkin.

• ZCODE_DATA_BASE_DIR: ilova ma’lumotlari bazasi katalogi, ma’lumotlar uning ichidagi .zcode/ ga yoziladi.
• ZCODE_SERVER_WORKSPACE: Web backend workspace yo‘lini ko‘rsatadi.
• ZCODE_BUILTIN_PROVIDER_CONFIG_FILE: mahalliy Provider konfiguratsiya faylini ko‘rsatadi; belgilanmasa, ichki konfiguratsiya ishlatiladi.
• ZCODE_DIST_BASE_URL: buyruq qatori o‘rnatish skripti foydalanadigan yuklab olish ildiz manzili.

Ushbu runtime o‘zgaruvchilarini ishga tushirish buyrug‘i muhitiga bevosita joylashtirish ham mumkin. Desktop ishlab chiqish serveri konfiguratsiyasi esa dev:desktop:test va dev:desktop:prod orqali tanlanadi.

SSH va WSL masofaviy funksiyalarini ishlab chiqish

Masofaviy workspace funksiyasini ishlab chiqishdan oldin masofaviy resurslarni tayyorlang:

pnpm bootstrap:with-remote
pnpm dev:desktop

Masofaviy loyihaga ulanishda resurs sifatida “mahalliy yuklab olish va keyin yuklash”ni tanlang. Ishlab chiqish muhiti resurslarni mahalliy packages/desktop/mock-cdn va mahalliy build natijalaridan oladi, so‘ng ularni SFTP orqali masofaviy host’ga yuklaydi; CDN’ga murojaat qilmaydi.

Ish stoli o‘rnatish paketini yig‘ish

Ish stoli versiyasini quyidagi buyruq orqali yig‘ing:

pnpm bundle:desktop

Sukut bo‘yicha maqsad macOS arm64, chiqish katalogi esa packages/desktop/dist/. Operatsion tizim va CPU arxitekturasini ham ko‘rsatish mumkin:

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

--os mac, win va linux qiymatlarini, --arch esa x64 va arm64 qiymatlarini qo‘llab-quvvatlaydi. Haqiqiy paketlash va imzolash uchun maqsadli platformaga mos vositalar va konfiguratsiya ham talab qilinadi.

macOS’da yaratilgan DMG faylini ochib, ZCode’ni “Applications” jildiga sudrashingiz mumkin. Mahalliy imzolanmagan build birinchi ishga tushirilganda tizim tomonidan bloklansa, quyidagini bajaring:

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

Buyruq qatori distributivini yig‘ish

Buyruq qatori distributivini yig‘ish uchun pnpm build:zcode buyrug‘idan foydalaniladi. Build’dan oldin yuklab olish ildiz manzili ZCODE_DIST_BASE_URL o‘rnatilishi kerak; uni --base-url orqali bevosita ham berish mumkin:

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

# ZCODE_DIST_BASE_URL sozlangan bo‘lsa
pnpm build:zcode

# Mavjud build artefaktlaridan qayta foydalanib, faqat paketni qayta yig‘ish
pnpm build:zcode --skip-build

# Mavjud parametrlarni ko‘rish
pnpm build:zcode --help

Bu yerdagi yuklab olish manzili faqat namuna sifatidagi to‘ldiruvchidir; rasmiy nashrda uni haqiqiy hosting manziliga almashtirish kerak. Build skripti CLI/TUI, backend va Web’ni ketma-ket qayta ishlaydi, native kutubxonalar, worker’lar va runtime bog‘liqliklarini yig‘adi, so‘ng distributiv paketni shakllantiradi.

Standart versiya ildiz katalogidagi package.json faylidan olinadi, chiqish katalogi esa dist/zcode/ bo‘lib, unda quyidagilar mavjud:

• releases/<version>/zcode-<version>.tar.gz: ishga tushirish paketi.
• releases/<version>/sha256.txt: tekshiruv xulosasi.
• latest.json: versiyalar indeksi.
• install.sh: o‘rnatish skripti.

O‘rnatish skripti sukut bo‘yicha runtime’ni ~/.zcode/runtime katalogiga o‘rnatadi va ~/.local/bin ichida zcode buyrug‘ini yaratadi. Bu ikki joyni mos ravishda ZCODE_DIST_HOME va ZCODE_DIST_BIN_DIR orqali o‘zgartirish mumkin.

Distributiv paketni lokal tekshirish

Fayllarni yuklamasdan yoki o‘rnatish skriptini ishga tushirmasdan, build natijasini bevosita arxivdan chiqarib ishga tushirish mumkin:

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’ni ishga tushirish
node dist/zcode/debug/zcode/bin/zcode.mjs

# Web’ni ishga tushirish
node dist/zcode/debug/zcode/bin/zcode.mjs --web \
  --workspace "$PWD" --port 3030 --no-open

Shundan so‘ng http://127.0.0.1:3030 manziliga kirib, ayni backend tomonidan boshqariladigan Web sahifasi va Agent’ning to‘liq ishlash zanjirini tekshirish mumkin. Port bo‘sh bo‘lishi kerak; agar pnpm dev:web ushbu portdan foydalanayotgan bo‘lsa, --port orqali boshqa portni tanlang.

Ilg‘or ishlab chiqish bo‘yicha tavsiyalar

1. Tegishli kirish nuqtasidan foydalaning: desktop funksiyalari uchun dev:desktop, frontend va backend integratsion sinovi uchun dev:web, Agent va TUI uchun esa CLI workspace’ning dev buyrug‘idan foydalaning.
2. Agent’ni o‘zgartirgandan so‘ng qayta build qiling: Web xizmati barcha Agent build natijalarini avtomatik qabul qilmaydi; o‘zgarishlardan keyin pnpm --filter @zcode/cli... build buyrug‘ini bajaring va xizmatni qayta ishga tushiring.
3. Test ma’lumotlarini ajrating: turli ishlab chiqish ssenariylari uchun alohida ma’lumot kataloglarini ZCODE_DATA_BASE_DIR orqali yarating.
4. Tashqi ulanishlarda autentifikatsiyani saqlang: --host 0.0.0.0 ishlatilganda, avtomatik yaratilgan tokenni saqlash yoki --token orqali tokenni aniq belgilash ustuvor bo‘lishi kerak.
5. Buyruq manbasini tekshiring: pnpm build:zcode faqat distributiv paketni yaratadi, tizim PATH’idagi mavjud zcode buyrug‘ini almashtirmaydi. macOS va Linux’da command -v zcode, Windows’da esa where.exe zcode buyrug‘ini bajarish mumkin.
6. Ishlab chiqish va distributiv tekshiruvini farqlang: pnpm dev:web manba kodini iteratsion ishlab chiqish uchun mos; arxivdan chiqarilgan bin/zcode.mjs esa yakuniy yagona buyruq va to‘liq distributsiya zanjirini tekshirish uchun qulayroq.

Repo tuzilmasi bilan qisqacha tanishuv

• packages/desktop: Electron Main, Host, Renderer va desktop paketlash.
• packages/web: Web klienti.
• packages/server: HTTP, WebSocket xizmatlari va masofaviy ulanish.
• packages/zcode-server-cli: mustaqil Server’ni ishga tushirish va jarayonlarni boshqarish.
• packages/ui: umumiy React komponentlari, hook’lar va Zustand holati.
• packages/services: biznes xizmatlari va ma’lumotlarni doimiy saqlash.
• packages/shared, packages/rpc, packages/client: umumiy protokollar va turlar, RPC freymvorki hamda Agent klient SDK’si.
• packages/provider, packages/provider-node: Provider’ning umumiy imkoniyatlari va Node.js implementatsiyasi.
• apps/zcode-cli: Agent CLI, TUI, runtime va vositalar.
• scripts, config, third-party: build’ni qo‘llab-quvvatlash skriptlari, ichki konfiguratsiya va uchinchi tomon bayonot materiallari.

Xulosa

ZCode desktop, Web, backend va Agent CLI’ni bitta workspace ichida birlashtiradi. Ishlab chiqishni birinchi marta boshlaganda pnpm bootstrap buyrug‘idan boshlang, so‘ng maqsadga qarab pnpm dev:desktop, pnpm dev:web yoki CLI manba kod kirish nuqtasini tanlang. Masofaviy workspace’ni sinash yoki rasmiy nashrga tayyorlanish kerak bo‘lganda, masofaviy resurslarni tayyorlang va mos desktop yoki buyruq qatori o‘rnatish paketini build qiling.