Mafunzo ya Maendeleo ya ZCode: Kuunda Kituo cha Kazi cha AI kwa Kompyuta, Wavuti na Kituo cha Amri

Utangulizi wa ZCode

ZCode ni kituo cha kazi cha upangaji programu kwa kutumia AI, kinachotoa programu ya kompyuta ya Electron, kiolesura cha kivinjari na Agent ya terminal. Hifadhi imepangwa kwa mfumo wa workspace, ikisimamia kwa pamoja msimbo wa mteja, huduma za nyuma, UI zinazoshirikiwa, Agent CLI, TUI na runtime.

Mradi una njia kuu tatu za kuanza uendelezaji:

• Desktop: Programu ya kompyuta ya Electron, inayowashwa kwa pnpm dev:desktop.
• Web: Huanzisha kwa pamoja kituo cha kazi cha kivinjari na backend ya ndani, kwa kutumia pnpm dev:web.
• Agent CLI: Kwa kuendeleza moja kwa moja Agent ya terminal au TUI, kwa kutumia pnpm --filter @zcode/cli dev.

Zaidi ya hayo, ZCode inaweza kujengwa kuwa kifurushi cha usambazaji cha mstari wa amri. Baada ya kusakinisha, endesha zcode kuingia kwenye TUI, au endesha zcode --web kuanzisha kituo cha kazi cha Web cha ndani.

Sifa Kuu

• Inatoa njia tatu za matumizi: kompyuta, kivinjari na terminal.
• Frontend ya Web, backend ya HTTP/WebSocket na Agent vinaweza kuunda mnyororo kamili wa kazi kwenye kompyuta ya ndani.
• Desktop na Web hushiriki runtime ya Agent CLI.
• Inasaidia uendelezaji wa workspace za mbali kupitia SSH, WSL na njia nyingine.
• Inashiriki vipengele vya React, hooks, hali ya Zustand, aina za itifaki, mfumo wa RPC na SDK ya mteja wa Agent.
• Inaweza kujenga kifurushi cha kusakinisha cha kompyuta na kifurushi cha pamoja cha usambazaji cha mstari wa amri cha ZCode.
• Web inapowekwa wazi kwa nje, inaweza kutengeneza tokeni ya ufikiaji kiotomatiki, au kutumia tokeni ya uthibitishaji iliyowekwa wazi.

Kuandaa Mazingira ya Uendelezaji

Sakinisha Zana Muhimu

Kabla ya kuanza, andaa zana zifuatazo. Toleo mahususi linapaswa kufuata mise.toml iliyoko kwenye mzizi wa hifadhi:

• Git
• Node.js 24.14.0
• pnpm 10.33.2

Baada ya kuiga hifadhi na kuingia kwenye mzizi wake, endesha amri inayopendekezwa ya uanzishaji:

pnpm bootstrap

pnpm bootstrap husakinisha utegemezi wa workspace, huandaa rasilimali za ndani za uendeshaji wa Desktop, na kutekeleza build:bootstrap. Agent CLI na runtime tayari ziko kwenye apps/zcode-cli/, kwa hiyo hakuna haja ya kuanzisha Git submodule ya ziada.

Bootstrap ya kawaida huruka maandalizi ya rasilimali za mbali, hivyo inafaa zaidi kwa uendelezaji wa Desktop wa ndani. Tekeleza amri za rasilimali za mbali tu unapohitaji SSH, WSL au rasilimali za usambazaji za mbali.

Chagua Amri ya Uanzishaji Inayohitajika

• pnpm install: Husakinisha utegemezi pekee.
• pnpm prepare:desktop-runtime: Huandaa rasilimali za runtime ya Desktop; kwa kawaida hujumuisha maandalizi ya rasilimali za mbali.
• pnpm prepare:remote-assets: Huandaa rasilimali za runtime za mbali pekee.
• pnpm bootstrap:with-remote: Huanzisha utegemezi na rasilimali za ndani na za mbali, kisha hujenga vifurushi husika kwa mfululizo, lakini huruka bundle ya programu ya Desktop.
• pnpm build: Hutekeleza kwa kujirudia script za ujenzi za vifurushi vyote vya workspace, pamoja na hatua za maandalizi ya rasilimali ndani ya vifurushi.

Kuendesha Toleo la Desktop

Baada ya kukamilisha uanzishaji, anzisha programu ya Desktop ya Electron kutoka kwenye mzizi wa hifadhi:

pnpm dev:desktop

pnpm dev:desktop kwa kawaida ni sawa na pnpm dev:desktop:prod, na hutumia usanidi wa huduma za uzalishaji. Script ya uanzishaji huandaa rasilimali za ndani za runtime, hujenga Agent ya Desktop, kisha huanzisha Electron na ufuatiliaji wa msimbo wa chanzo.

Ukitaka kutumia mazingira ya majaribio, endesha:

pnpm dev:desktop:test

Kutenga Data ya Uendelezaji

Ili kuzuia data ya uendelezaji kuchanganyika na data ya matumizi ya kila siku, tumia ZCODE_DATA_BASE_DIR kubainisha saraka huru ya msingi wa data. Data ya programu itaandikwa kwenye .zcode/ iliyo ndani ya saraka hiyo:

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

Muundo huu unafaa kwa macOS na Linux.

Kuendesha Kituo cha Kazi cha Web

Unaporekebisha msimbo wa frontend au backend ya Web, inashauriwa kutumia hali ya uendelezaji wa pamoja:

pnpm dev:web

Amri hii huanzisha kwa pamoja:

• Seva ya uendelezaji ya Web, yenye anwani ya kawaida http://localhost:5173.
• Backend ya ndani, yenye anwani ya kawaida http://localhost:3030.

Kivinjari kinapaswa kufikia anwani ya frontend. Seva ya uendelezaji itapeleka maombi ya /ws na maombi ya kawaida ya /api kwenye backend ya ndani; /api/v1/oauth/token itaelekezwa pekee kwenye huduma ya bidhaa iliyosanidiwa kwa sasa.

Kubainisha Workspace ya Backend

Kwenye macOS au Linux, unaweza kutumia kigezo cha mazingira kubainisha saraka ya mradi itakayotumiwa na backend ya Web:

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

Ukirekebisha msimbo wa Agent, jenga upya CLI pamoja na utegemezi wake wa workspace, kisha uanzishe tena huduma:

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

Kuendeleza Agent CLI na TUI

Ikiwa unaendeleza hasa kiolesura cha terminal au Agent, unaweza kuendesha moja kwa moja sehemu ya kuingilia ya msimbo wa chanzo:

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

Baada ya kujenga CLI na utegemezi wake, unaweza pia kuendesha moja kwa moja faili ya CommonJS iliyotengenezwa:

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

Sehemu hii ya kuingilia ya msimbo wa chanzo huendesha Agent CLI moja kwa moja, na haitatekeleza uelekezaji wa --web wa amri ya usambazaji wa pamoja. Kwa uendelezaji wa Web, tumia pnpm dev:web; kwa kujaribu amri ya pamoja ya zcode, jenga na utoe kifurushi cha usambazaji cha mstari wa amri.

Kutumia Toleo la Mstari wa Amri la ZCode

Kifurushi cha usambazaji cha mstari wa amri huunganisha TUI, Web, backend na Agent, na kuvianzisha kwa pamoja kupitia zcode. Hakitegemei Electron, lakini runtime bado inahitaji Node.js inayokidhi mahitaji ya mise.toml.

Amri za Msingi

# Ingia kwenye kiolesura shirikishi cha terminal
zcode

# Anzisha kituo cha kazi cha Web
zcode --web

# Bainisha mradi na mlango, na zuia kufungua kivinjari kiotomatiki
zcode --web --workspace /path/to/project --port 3030 --no-open

# Tazama msaada
zcode --help
zcode --web --help

Hali ya Web kwa kawaida hutumia saraka ya sasa kama saraka ya kazi, husikiliza kwenye 127.0.0.1, huchagua kiotomatiki mlango usiotumika na kufungua kivinjari. Kwa kawaida tokeni ya ufikiaji haiwezeshwi. Baada ya kumaliza matumizi, bonyeza Ctrl+C kwenye terminal ili kusimamisha huduma.

Kufikia Kutoka Kwenye Mtandao wa Ndani

Ukitaka vifaa vingine vifikie huduma, badilisha anwani ya usikilizaji kuwa 0.0.0.0:

zcode --web --host 0.0.0.0

Inaposikiliza kwenye anwani isiyo ya kompyuta ya ndani, ZCode kwa kawaida hutengeneza tokeni ya ufikiaji. Tumia kiungo chenye tokeni kilichoonyeshwa kwenye terminal kufikia huduma. Unaweza pia kubainisha tokeni kwa --token, au kuzima uthibitishaji wa tokeni kwa --no-token.

Unapoanzisha moja kwa moja sehemu ya HTTP ya huduma ya jumla ya Web, unaweza kusanidi uthibitishaji wa API na WebSocket kupitia ZCODE_SERVER_AUTH_TOKEN; unapounda huduma kupitia kiolesura cha programu, tumia chaguo la authToken.

Kusanidi Vigezo vya Mazingira

.env.example iliyo kwenye mzizi wa hifadhi hutoa mifano ya anwani za huduma na usanidi wa ujenzi. Unaweza kuinakili kuwa .env kulingana na mahitaji, na kuweka mipangilio ya ziada ya matumizi ya ndani pekee kwenye .env.local.

• ZCODE_DATA_BASE_DIR: Saraka ya msingi wa data ya programu; data huandikwa kwenye .zcode/ iliyo ndani yake.
• ZCODE_SERVER_WORKSPACE: Hubainisha njia ya workspace ya backend ya Web.
• ZCODE_BUILTIN_PROVIDER_CONFIG_FILE: Hubainisha faili ya usanidi wa Provider ya ndani; ikiwa haijawekwa, hutumika usanidi uliojengewa ndani.
• ZCODE_DIST_BASE_URL: Anwani ya mzizi wa upakuaji inayotumiwa na script ya kusakinisha mstari wa amri.

Vigezo hivi vya runtime vinaweza pia kuwekwa moja kwa moja kwenye mazingira ya amri ya uanzishaji. Usanidi wa huduma ya uendelezaji ya Desktop huchaguliwa kupitia dev:desktop:test na dev:desktop:prod.

Kuendeleza Vipengele vya Mbali vya SSH na WSL

Kabla ya kuendeleza kipengele cha workspace ya mbali, andaa kwanza rasilimali za mbali:

pnpm bootstrap:with-remote
pnpm dev:desktop

Unapounganisha mradi wa mbali, chagua rasilimali “pakua ndani kisha pakia”. Mazingira ya uendelezaji hupata rasilimali kutoka packages/desktop/mock-cdn ya ndani na bidhaa za ujenzi za ndani, kisha huzipakia kwenye seva ya mbali kupitia SFTP bila kufikia CDN.

Kujenga Kifurushi cha Kusakinisha cha Desktop

Endesha amri ifuatayo ili kujenga toleo la Desktop:

pnpm bundle:desktop

Lengo la kawaida ni macOS arm64, na saraka ya matokeo ni packages/desktop/dist/. Unaweza pia kubainisha mfumo wa uendeshaji na usanifu wa CPU:

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

--os inasaidia mac, win na linux; --arch inasaidia x64 na arm64. Ufungashaji na utiaji saini halisi bado vinahitaji zana na usanidi unaolingana na jukwaa lengwa.

Kwenye macOS, unaweza kufungua DMG iliyotengenezwa na kuburuta ZCode kwenye “Applications”. Ikiwa ujenzi wa ndani usiotiliwa saini umezuiwa na mfumo unapoanzishwa kwa mara ya kwanza, unaweza kutekeleza:

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

Kujenga Kifurushi cha Usambazaji cha Mstari wa Amri

Sehemu ya kuingilia ya ujenzi wa kifurushi cha usambazaji cha mstari wa amri ni pnpm build:zcode. Kabla ya kujenga, lazima uweke anwani ya mzizi wa upakuaji ZCODE_DIST_BASE_URL; unaweza pia kuipitisha moja kwa moja kupitia --base-url:

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

# Wakati ZCODE_DIST_BASE_URL imesanidiwa
pnpm build:zcode

# Tumia tena vifaa vya ujenzi vilivyopo, pakia upya tu
pnpm build:zcode --skip-build

# Angalia vigezo vinavyopatikana
pnpm build:zcode --help

Anwani ya upakuaji hapo ni mfano wa kishikilia nafasi tu; wakati wa uchapishaji rasmi inahitaji kubadilishwa kuwa anwani halisi ya upangishaji. Hati ya ujenzi itashughulikia CLI/TUI, backend na Web kwa mfuatano, kukusanya maktaba asili, worker na vitegemezi vya wakati wa utekelezaji, kisha kuunda kifurushi cha usambazaji.

Toleo chaguo-msingi linatoka kwenye package.json ya saraka kuu, na saraka ya matokeo ni dist/zcode/, inayojumuisha:

• releases/<version>/zcode-<version>.tar.gz: kifurushi cha wakati wa utekelezaji.
• releases/<version>/sha256.txt: muhtasari wa uthibitishaji.
• latest.json: faharasa ya matoleo.
• install.sh: hati ya usakinishaji.

Kwa chaguo-msingi, hati ya usakinishaji huweka wakati wa utekelezaji kwenye ~/.zcode/runtime, na kuunda amri ya zcode kwenye ~/.local/bin. Unaweza kubadilisha maeneo haya mawili kupitia ZCODE_DIST_HOME na ZCODE_DIST_BIN_DIR mtawalia.

Kuthibitisha kifurushi cha usambazaji ndani ya kompyuta

Bila kupakia faili au kutekeleza hati ya usakinishaji, unaweza pia kufungua moja kwa moja na kuendesha matokeo ya ujenzi:

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

# Anzisha TUI
node dist/zcode/debug/zcode/bin/zcode.mjs

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

Baadaye tembelea http://127.0.0.1:3030 ili kuthibitisha mnyororo kamili ambapo backend hiyo hiyo inapangisha ukurasa wa Web na Agent. Porti lazima iwe huru; ikiwa pnpm dev:web inatumia porti hiyo, tumia --port kuchagua porti nyingine.

Mapendekezo ya hali ya juu ya uendelezaji

1. Tumia kwanza ingizo linalolingana: kwa utendaji wa eneo-kazi tumia dev:desktop, kwa kuunganisha frontend na backend tumia dev:web, na kwa Agent na TUI tumia amri ya dev ya CLI workspace.
2. Jenga upya baada ya kurekebisha Agent: huduma ya Web haitapata kiotomatiki matokeo yote ya ujenzi wa Agent; baada ya marekebisho tekeleza pnpm --filter @zcode/cli... build na uwashe upya huduma.
3. Tenganisha data ya majaribio: tumia ZCODE_DATA_BASE_DIR kuunda saraka huru za data kwa hali tofauti za uendelezaji.
4. Hifadhi uthibitishaji unapomsikiliza mtandao wa nje: baada ya kutumia --host 0.0.0.0, ni vyema kuhifadhi tokeni inayozalishwa kiotomatiki au kuweka --token wazi.
5. Kagua chanzo cha amri: pnpm build:zcode huunda kifurushi cha usambazaji pekee; haitabadilisha zcode iliyopo kwenye PATH ya mfumo. Kwenye macOS na Linux unaweza kuendesha command -v zcode, na kwenye Windows unaweza kuendesha where.exe zcode.
6. Tenganisha uthibitishaji wa uendelezaji na usambazaji: pnpm dev:web inafaa kwa maboresho ya msimbo chanzi; bin/zcode.mjs baada ya kufunguliwa inafaa zaidi kwa kuthibitisha amri ya mwisho iliyounganishwa na mnyororo kamili wa usambazaji.

Muhtasari wa muundo wa hazina

• packages/desktop: Electron Main, Host, Renderer na ufungashaji wa programu ya eneo-kazi.
• packages/web: mteja wa Web.
• packages/server: huduma za HTTP, WebSocket na miunganisho ya mbali.
• packages/zcode-server-cli: uanzishaji huru wa Server na usimamizi wa michakato.
• packages/ui: vipengele vya React vinavyoshirikiwa, hooks na hali ya Zustand.
• packages/services: huduma za biashara na uhifadhi endelevu.
• packages/shared, packages/rpc, packages/client: itifaki na aina zinazoshirikiwa, mfumo wa RPC na SDK ya mteja wa Agent.
• packages/provider, packages/provider-node: uwezo wa jumla wa Provider na utekelezaji wa Node.js.
• apps/zcode-cli: Agent CLI, TUI, wakati wa utekelezaji na zana.
• scripts, config, third-party: hati za ujenzi na matengenezo, usanidi uliojengewa ndani na nyenzo za matamko ya wahusika wengine.

Muhtasari

ZCode inaunganisha programu ya eneo-kazi, Web, backend na Agent CLI katika workspace moja. Kwa uendelezaji wa kwanza, anza na pnpm bootstrap, kisha chagua pnpm dev:desktop, pnpm dev:web au ingizo la msimbo chanzi wa CLI kulingana na lengo. Unapohitaji kujaribu workspace ya mbali au kufanya usambazaji rasmi, andaa rasilimali za mbali kisha ujenge kifurushi cha usakinishaji cha eneo-kazi au mstari wa amri kinacholingana.