Isifundo Sokuthuthukisa i-ZCode: Ukwakha Indawo Yokusebenzela Yokuhlela nge-AI Yedeskithophu, Yewebhu Neyetheminali

Ukwazi i-ZCode

I-ZCode iyindawo yokusebenzela yokuhlela esebenzisa i-AI, ehlinzeka ngohlelo lokusebenza lwedeskithophu lwe-Electron, isixhumi esibonakalayo sesiphequluli kanye ne-Terminal Agent. Indawo yokugcina ikhodi ihlelwe ngendlela ye-workspace, futhi igcina ndawonye ikhodi yomthombo yeklayenti, izinsizakalo zangemuva, i-UI eyabiwe, i-Agent CLI, i-TUI kanye ne-runtime.

Iphrojekthi inezindawo ezintathu eziyinhloko zokuthuthukisa:

• Desktop: Uhlelo lokusebenza lwedeskithophu lwe-Electron, luqalwa nge-pnpm dev:desktop.
• Web: Iqala ndawonye indawo yokusebenzela yesiphequluli kanye nesevisi yangemuva yasendaweni, kusetshenziswa pnpm dev:web.
• Agent CLI: Ukuthuthukisa ngokuqondile i-Terminal Agent noma i-TUI, kusetshenziswa pnpm --filter @zcode/cli dev.

Ngaphezu kwalokho, i-ZCode ingakhiwa ibe yiphakheji yokusabalalisa yomugqa womyalo ehlanganisiwe. Ngemva kokuyifaka, sebenzisa zcode ukuze ungene ku-TUI, noma usebenzise zcode --web ukuze uqale indawo yokusebenzela ye-Web yasendaweni.

Izici eziyinhloko

• Ihlinzeka ngezindlela ezintathu zokusetshenziswa: ideskithophu, isiphequluli kanye netheminali.
• I-frontend ye-Web, i-backend ye-HTTP/WebSocket kanye ne-Agent zingakha ndawonye uchungechunge oluphelele lokusebenza emshinini wendawo.
• I-Desktop ne-Web zabelana nge-runtime ye-Agent CLI.
• Isekela ukuthuthukiswa kwezindawo zokusebenzela ezikude nge-SSH, WSL nezinye izindlela.
• Iabelana ngezingxenye ze-React, ama-hooks, isimo se-Zustand, izinhlobo zamaphrothokholi, uhlaka lwe-RPC kanye ne-Agent client SDK.
• Ingakha ngokwehlukana amaphakheji okufaka edeskithophu kanye nephakheji yokusabalalisa yomugqa womyalo ehlanganisiwe ye-ZCode.
• Lapho i-Web ilalela ngaphandle, ingakhiqiza ngokuzenzakalelayo ithokheni yokufinyelela, futhi ingalungiselelwa nethokheni yokuqinisekisa ebekwe ngokusobala.

Ukulungisa indawo yokuthuthukisa

Ukufaka amathuluzi adingekayo

Ngaphambi kokuqala, lungisa amathuluzi alandelayo. Izinguqulo eziqondile zicaciswa ku-mise.toml esiqwini sendawo yokugcina ikhodi:

• Git
• Node.js 24.14.0
• pnpm 10.33.2

Ngemva kokukhipha indawo yokugcina ikhodi nokungena esiqwini sayo, sebenzisa umyalo wokulungiselela onconyiwe:

pnpm bootstrap

pnpm bootstrap izofaka iz依依 ze-workspace, ilungise izinsiza zokuqalisa zasendaweni zedeskithophu, bese isebenzisa build:bootstrap. I-Agent CLI ne-runtime sezitholakala ku-apps/zcode-cli/, ngakho akudingeki ukuthi kulungiswe i-Git submodule eyengeziwe.

I-bootstrap ezenzakalelayo yeqa ukulungiswa kwezinsiza ezikude, ngakho ifaneleka kakhulu ukuthuthukisa ideskithophu yasendaweni. Izinsiza ezikude kufanele zilungiswe kuphela uma kudingeka i-SSH, i-WSL noma izinsiza zokusabalalisa ezikude.

Ukukhetha umyalo wokulungiselela ngokwesidingo

• pnpm install: Ifaka iz依依 kuphela.
• pnpm prepare:desktop-runtime: Ilungisa izinsiza ze-runtime yedeskithophu; ngokuzenzakalelayo ihlanganisa nokulungiswa kwezinsiza ezikude.
• pnpm prepare:remote-assets: Ilungisa izinsiza ze-runtime ezikude ngokwehlukana.
• pnpm bootstrap:with-remote: Ilungisa iz依依, izinsiza zasendaweni nezikude, futhi yakha amaphakheji ahlobene ngokulandelana, kodwa yeqa i-bundle yohlelo lokusebenza lwedeskithophu.
• pnpm build: Isebenzisa ngokuphindaphindiwe izikripthi zokwakha zawo wonke amaphakheji e-workspace, kuhlanganise nezinyathelo zokulungisa izinsiza ezingaphakathi kwephakheji.

Ukuqalisa inguqulo yedeskithophu

Ngemva kokuqeda ukulungiselela, qalisa uhlelo lokusebenza lwedeskithophu lwe-Electron esiqwini sendawo yokugcina ikhodi:

pnpm dev:desktop

pnpm dev:desktop ngokuzenzakalelayo ilingana no-pnpm dev:desktop:prod, futhi isebenzisa ukucushwa kwesevisi yokukhiqiza. Isikripthi sokuqalisa silungisa izinsiza zasendaweni ze-runtime, sakhe i-Agent yedeskithophu, bese siqalisa i-Electron nokulalela ikhodi yomthombo.

Uma ufuna ukusebenzisa indawo yokuhlola, sebenzisa:

pnpm dev:desktop:test

Ukuhlukanisa idatha yokuthuthukisa

Ukuze ugweme ukuhlanganisa idatha yokuthuthukisa nedatha yokusetshenziswa kwansuku zonke, sebenzisa ZCODE_DATA_BASE_DIR ukuze ucacise uhla oluzimele lwesisekelo sedatha. Idatha yohlelo lokusebenza izobhalwa ku-.zcode/ engaphansi kwalolo hlu:

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

Le ndlela isebenza ku-macOS naku-Linux.

Ukuqalisa indawo yokusebenzela ye-Web

Lapho uguqula ikhodi yomthombo ye-frontend noma ye-backend ye-Web, kunconywa ukusebenzisa imodi yokuthuthukisa ehlangene:

pnpm dev:web

Lo myalo uzoqala ndawonye:

• Isiphakeli sokuthuthukisa i-Web, esinekheli elizenzakalelayo elingu-http://localhost:5173.
• I-backend yasendaweni, enekheli elizenzakalelayo elingu-http://localhost:3030.

Isiphequluli kufanele sivakashele ikheli le-frontend. Isiphakeli sokuthuthukisa sizodlulisela izicelo ze-/ws kanye nezicelo ezijwayelekile ze-/api ku-backend yasendaweni; i-/api/v1/oauth/token izodluliselwa ngokwehlukana kusevisi yomkhiqizo elungiselelwe njengamanje.

Ukucacisa i-workspace ye-backend

Ku-macOS noma ku-Linux, ungacacisa uhla lwephrojekthi oluzosetshenziswa yi-backend ye-Web ngokusebenzisa le variable yemvelo:

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

Uma uguqule ikhodi yomthombo ye-Agent, yakha kabusha i-CLI kanye nez依依 zayo ze-workspace, bese uqala kabusha isevisi:

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

Ukuthuthukisa i-Agent CLI ne-TUI

Uma ugxile ekuthuthukiseni isixhumi esibonakalayo setheminali noma i-Agent, ungasebenzisa ngokuqondile indawo yokungena yekhodi yomthombo:

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

Ngemva kokwakha i-CLI kanye nez依依 zayo, ungasebenzisa ngokuqondile ifayela le-CommonJS elikhiqiziwe:

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

Le ndawo yokungena yekhodi yomthombo isebenzisa ngokuqondile i-Agent CLI, futhi ayisebenzisi ukuhlukaniswa kwe---web komyalo wokusabalalisa ohlanganisiwe. Ukuze uthuthukise i-Web, sebenzisa pnpm dev:web; ukuze uhlole umyalo ohlanganisiwe we-zcode, yakha bese ukhipha iphakheji yokusabalalisa yomugqa womyalo.

Ukusebenzisa inguqulo yomugqa womyalo ye-ZCode

Iphakheji yokusabalalisa yomugqa womyalo ihlanganisa i-TUI, i-Web, i-backend kanye ne-Agent, futhi konke kuqalwa nge-zcode. Ayincikile ku-Electron, kodwa i-runtime isadinga i-Node.js ehambisana nezimfuneko ze-mise.toml.

Imiyalo eyisisekelo

# Ngena kusixhumi esibonakalayo setheminali
zcode

# Qalisa indawo yokusebenzela ye-Web
zcode --web

# Cacisa iphrojekthi nechweba, futhi uvimbele ukuvulwa kwesiphequluli ngokuzenzakalelayo
zcode --web --workspace /path/to/project --port 3030 --no-open

# Bona usizo
zcode --help
zcode --web --help

Imodi ye-Web ngokuzenzakalelayo isebenzisa uhla lwamanje njengohla lokusebenza, ilalele ku-127.0.0.1, ikhethe ngokuzenzakalelayo ichweba elikhululekile bese ivula isiphequluli. Ngokuzenzakalelayo ayiniki amandla ithokheni yokufinyelela. Ngemva kokuqeda ukusebenzisa, cindezela Ctrl+C etheminali ukuze umise isevisi.

Ukufinyelela kunethiwekhi yasendaweni

Uma kudingeka ukuthi amanye amadivayisi afinyelele, shintsha ikheli lokulalela libe ngu-0.0.0.0:

zcode --web --host 0.0.0.0

Lapho ilalela ikheli elingelona lasemshinini wendawo, i-ZCode ngokuzenzakalelayo izokhiqiza ithokheni yokufinyelela. Sebenzisa isixhumanisi esinethokheni esiboniswa etheminali ukuze ufinyelele isevisi. Ungacacisa futhi ithokheni nge---token, noma uvale ukuqinisekiswa kwethokheni nge---no-token.

Lapho uqala ngokuqondile indawo yokungena ye-HTTP yesevisi evamile ye-Web, sebenzisa ZCODE_SERVER_AUTH_TOKEN ukuze ulungise ukuqinisekiswa kwe-API ne-WebSocket; lapho udala isevisi ngesixhumi esibonakalayo sohlelo, sebenzisa inketho ethi authToken.

Ukulungisa ama-variable emvelo

I-.env.example esiqwini sendawo yokugcina ikhodi inikeza izibonelo zamakheli esevisi kanye nokucushwa kokwakha. Ungayikopisha ibe yi-.env ngokwesidingo, bese ufaka izilungiselelo ezisetshenziswa endaweni kuphela ku-.env.local.

• ZCODE_DATA_BASE_DIR: Uhlu lwesisekelo sedatha yohlelo lokusebenza; idatha ibhalwa ku-.zcode/ engaphansi kwalo.
• ZCODE_SERVER_WORKSPACE: Icacisa indlela ye-workspace ye-backend ye-Web.
• ZCODE_BUILTIN_PROVIDER_CONFIG_FILE: Icacisa ifayela lokucushwa le-Provider yasendaweni; uma lingasethiwe, kusetshenziswa ukucushwa okwakhelwe ngaphakathi.
• ZCODE_DIST_BASE_URL: Ikheli eliyisisekelo lokulanda elisetshenziswa isikripthi sokufaka somugqa womyalo.

Lawa ma-variable e-runtime angafakwa ngokuqondile endaweni yemvelo yomyalo wokuqalisa. Ukucushwa kwesevisi yokuthuthukisa ye-Desktop kukhethwa nge-dev:desktop:test nange-dev:desktop:prod.

Ukuthuthukisa izici ezikude ze-SSH ne-WSL

Ngaphambi kokuthuthukisa izici ze-workspace ekude, lungisa izinsiza ezikude:

pnpm bootstrap:with-remote
pnpm dev:desktop

Lapho uxhuma iphrojekthi ekude, khetha insiza ethi “landa endaweni bese uyilayisha”. Indawo yokuthuthukisa izothola izinsiza ku-packages/desktop/mock-cdn yasendaweni nakumafayela akhiwe endaweni, bese iwathumela kuseva ekude nge-SFTP; ngeke ifinyelele ku-CDN.

Ukwakha iphakheji yokufaka yedeskithophu

Sebenzisa lo myalo olandelayo ukuze wakhe inguqulo yedeskithophu:

pnpm bundle:desktop

Okuhlosiwe okuzenzakalelayo yi-macOS arm64, futhi uhla lokuphumayo luyi-packages/desktop/dist/. Ungacacisa futhi isistimu yokusebenza kanye nokwakheka kwe-CPU:

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

--os isekela mac, win ne-linux, kanti --arch isekela x64 ne-arm64. Ukupakisha nokusayina kwangempela kusadinga amathuluzi nokucushwa okuhambisana nenkundla okuqondiwe.

Ku-macOS, ungavula i-DMG ekhiqiziwe bese uhudulela i-ZCode ku-“Applications”. Uma ukwakha kwasendaweni okungasayiniwe kuvinjwa uhlelo lapho kuqalwa okokuqala, sebenzisa:

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

Ukwakha iphakheji yokusabalalisa yomugqa womyalo

Indawo yokungena yokwakha iphakheji yokusabalalisa yomugqa womyalo yi-pnpm build:zcode. Ngaphambi kokwakha, kufanele kusethwe ikheli eliyisisekelo lokulanda ZCODE_DIST_BASE_URL; lingadluliswa futhi ngokuqondile nge---base-url:

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

# Uma i-ZCODE_DIST_BASE_URL isilungisiwe
pnpm build:zcode

# Sebenzisa kabusha imiphumela yokwakha ekhona, uhlanganise iphakheji kabusha kuphela
pnpm build:zcode --skip-build

# Buka amapharamitha atholakalayo
pnpm build:zcode --help

Ikheli lokulanda elingenhla liyisibonelo nje; lapho kukhishwa ngokusemthethweni, kufanele lishintshwe libe ikheli langempela lokusingatha. Iskripthi sokwakha sicubungula i-CLI/TUI, i-backend ne-Web ngokulandelana, siqoqe amalabhulali omdabu, ama-worker nokuncika kwesikhathi sokusebenza, bese sihlanganisa iphakheji yokusabalalisa.

Inguqulo ezenzakalelayo ivela ku-package.json yomkhombandlela oyimpande, kanti umkhombandlela wokukhipha ngu-dist/zcode/, oqukethe:

• releases/<version>/zcode-<version>.tar.gz: iphakheji yokusebenza.
• releases/<version>/sha256.txt: isifinyezo sokuqinisekisa.
• latest.json: inkomba yezinguqulo.
• install.sh: iskripthi sokufaka.

Iskripthi sokufaka ngokuzenzakalela sifaka isikhathi sokusebenza ku-~/.zcode/runtime, bese sakha umyalo we-zcode ku-~/.local/bin. Ungashintsha lezi zindawo ezimbili ngokwehlukana usebenzisa i-ZCODE_DIST_HOME ne-ZCODE_DIST_BIN_DIR.

Ukuqinisekisa iphakheji yokusabalalisa endaweni yangakini

Awudingi ukulayisha amafayela noma ukusebenzisa iskripthi sokufaka; ungakwazi ukukhipha ngokuqondile bese usebenzisa umphumela wokwakha:

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

# Qalisa i-TUI
node dist/zcode/debug/zcode/bin/zcode.mjs

# Qalisa i-Web
node dist/zcode/debug/zcode/bin/zcode.mjs --web \
  --workspace "$PWD" --port 3030 --no-open

Bese uvakashela http://127.0.0.1:3030 ukuze uqinisekise uchungechunge oluphelele, lapho i-backend efanayo isingatha khona ikhasi le-Web ne-Agent. Imbobo kufanele ibe ayisetshenziswa; uma pnpm dev:web isebenzisa leyo mbobo, sebenzisa --port ukhethe enye.

Iziphakamiso ezithuthukile zokuthuthukisa

1. Sebenzisa indawo yokungena efanele kuqala: sebenzisa dev:desktop emisebenzini yedeskithophu, dev:web ekuhlanganiseni nasekuhloleni i-frontend ne-backend, kanye nomyalo dev we-CLI workspace ku-Agent ne-TUI.
2. Yakha kabusha ngemva kokushintsha i-Agent: isevisi ye-Web ngeke izithole ngokuzenzakalela zonke iziphumo zokwakha ze-Agent; ngemva kwezinguquko, sebenzisa pnpm --filter @zcode/cli... build bese uqala kabusha isevisi.
3. Hlukanisa idatha yokuhlola: sebenzisa ZCODE_DATA_BASE_DIR ukuze wakhe imikhombandlela yedatha ezimele yezimo ezihlukene zokuthuthukisa.
4. Gcina ukuqinisekiswa lapho ulalela ngaphandle: ngemva kokusebenzisa --host 0.0.0.0, gcina ithokheni ekhiqizwe ngokuzenzakalela noma usethe ngokusobala --token.
5. Hlola umsuka womyalo: pnpm build:zcode ikhiqiza kuphela iphakheji yokusabalalisa; ayishintshi i-zcode esivele ikhona ku-PATH yesistimu. Ku-macOS ne-Linux sebenzisa command -v zcode, kanti ku-Windows sebenzisa where.exe zcode.
6. Hlukanisa ukuqinisekiswa kokuthuthukisa nokusabalalisa: pnpm dev:web ilungele ukuphindaphinda ikhodi yomthombo; i-bin/zcode.mjs ekhishiwe ilungele kakhulu ukuqinisekisa umyalo wokugcina ohlanganisiwe kanye nochungechunge oluphelele lokusabalalisa.

Ukubuka ngokushesha isakhiwo sendawo yokugcina ikhodi

• packages/desktop: i-Electron Main, i-Host, i-Renderer nokupakishwa kwedeskithophu.
• packages/web: iklayenti le-Web.
• packages/server: amasevisi e-HTTP, e-WebSocket nokuxhumana okukude.
• packages/zcode-server-cli: ukuqaliswa okuzimele kwe-Server nokuphathwa kwezinqubo.
• packages/ui: izingxenye ze-React ezabiwe, ama-hooks nesimo se-Zustand.
• packages/services: amasevisi ebhizinisi nokugcinwa kwedatha.
• packages/shared, packages/rpc, packages/client: amaphrothokholi nezinhlobo ezabiwe, uhlaka lwe-RPC kanye ne-Agent client SDK.
• packages/provider, packages/provider-node: amakhono omphakathi e-Provider nokusetshenziswa kwe-Node.js.
• apps/zcode-cli: i-Agent CLI, i-TUI, isikhathi sokusebenza namathuluzi.
• scripts, config, third-party: izikripthi zokugcina ukwakha, ukucushwa okwakhelwe ngaphakathi nezinto zokumemezela zezinkampani zangaphandle.

Isifinyezo

I-ZCode ihlanganisa ideskithophu, i-Web, i-backend ne-Agent CLI ku-workspace eyodwa. Ekuthuthukiseni kokuqala, qala nge-pnpm bootstrap, bese ukhetha pnpm dev:desktop, pnpm dev:web noma indawo yokungena yekhodi yomthombo ye-CLI kuye ngomgomo wakho. Lapho udinga ukuhlola ama-workspace akude noma ukusabalalisa ngokusemthethweni, lungisa izinsiza ezikude bese wakha iphakheji yokufaka yedeskithophu noma yomugqa womyalo efanele.