মূল কনটেন্টে যান
এআই টিউটোরিয়াল

ZCode ডেভেলপমেন্ট টিউটোরিয়াল: ডেস্কটপ, Web ও টার্মিনাল AI প্রোগ্রামিং ওয়ার্কবেঞ্চ তৈরি

এই টিউটোরিয়ালে ZCode ডেভেলপমেন্ট পরিবেশ তৈরি, Electron ডেস্কটপ অ্যাপ, Web ওয়ার্কবেঞ্চ এবং Agent CLI চালানো, পাশাপাশি রিমোট রিসোর্স, অ্যাক্সেস অথেনটিকেশন ও ডিস্ট্রিবিউশন প্যাকেজ কনফিগার করার পদ্ধতি দেখানো হয়েছে।

পড়তে প্রায় 27 মিনিট লাগবে
ZCode ডেভেলপমেন্ট টিউটোরিয়াল: ডেস্কটপ, Web ও টার্মিনাল 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-কে একীভূত কমান্ড-লাইন ডিস্ট্রিবিউশন প্যাকেজ হিসেবে তৈরি করা যায়। ইনস্টল করার পর zcode চালিয়ে TUI-তে প্রবেশ করুন, আর zcode --web চালালে স্থানীয় Web ওয়ার্কবেঞ্চ চালু হবে।

প্রধান বৈশিষ্ট্য

  • ডেস্কটপ, ব্রাউজার ও টার্মিনাল ব্যবহারের তিনটি পদ্ধতি প্রদান করে।
  • Web ফ্রন্টএন্ড, HTTP/WebSocket ব্যাকএন্ড এবং Agent স্থানীয়ভাবে সম্পূর্ণ ওয়ার্কফ্লো তৈরি করতে পারে।
  • Desktop ও Web একই Agent CLI রানটাইম ব্যবহার করে।
  • SSH, WSL ইত্যাদির মাধ্যমে রিমোট workspace উন্নয়ন সমর্থন করে।
  • শেয়ার্ড React কম্পোনেন্ট, hooks, Zustand state, প্রোটোকল টাইপ, RPC ফ্রেমওয়ার্ক এবং Agent ক্লায়েন্ট SDK প্রদান করে।
  • ডেস্কটপ ইনস্টলার এবং একীভূত ZCode কমান্ড-লাইন ডিস্ট্রিবিউশন প্যাকেজ আলাদাভাবে তৈরি করা যায়।
  • Web বাইরে থেকে শোনার সময় স্বয়ংক্রিয়ভাবে অ্যাক্সেস টোকেন তৈরি করতে পারে; চাইলে স্পষ্টভাবে অথেনটিকেশন টোকেনও নির্ধারণ করা যায়।

উন্নয়ন পরিবেশ প্রস্তুত করা

প্রয়োজনীয় টুল ইনস্টল করুন

শুরু করার আগে নিচের টুলগুলো প্রস্তুত করুন। নির্দিষ্ট সংস্করণ রিপোজিটরির মূল ডিরেক্টরির mise.toml অনুযায়ী হবে:

  • Git
  • Node.js 24.14.0
  • pnpm 10.33.2

রিপোজিটরি ক্লোন করে মূল ডিরেক্টরিতে প্রবেশ করার পর প্রস্তাবিত ইনিশিয়ালাইজেশন কমান্ড চালান:

pnpm bootstrap

pnpm bootstrap workspace-এর নির্ভরতা ইনস্টল করবে, ডেস্কটপের স্থানীয় রানটাইম রিসোর্স প্রস্তুত করবে এবং build:bootstrap চালাবে। Agent CLI ও রানটাইম ইতিমধ্যে apps/zcode-cli/-তে রয়েছে, তাই অতিরিক্ত Git submodule ইনিশিয়ালাইজ করার প্রয়োজন নেই।

ডিফল্ট bootstrap দূরবর্তী রিসোর্স প্রস্তুত করা এড়িয়ে যায়, তাই এটি স্থানীয় ডেস্কটপ উন্নয়নের জন্য বেশি উপযোগী। SSH, WSL বা রিমোট ডিস্ট্রিবিউশন রিসোর্স প্রয়োজন হলেই কেবল রিমোট রিসোর্স-সংক্রান্ত কমান্ড চালাতে হবে।

প্রয়োজন অনুযায়ী ইনিশিয়ালাইজেশন কমান্ড বেছে নিন

  • pnpm install: শুধু নির্ভরতা ইনস্টল করে।
  • pnpm prepare:desktop-runtime: ডেস্কটপ রানটাইম রিসোর্স প্রস্তুত করে; ডিফল্টভাবে রিমোট রিসোর্সও প্রস্তুত করে।
  • pnpm prepare:remote-assets: আলাদাভাবে রিমোট রানটাইম রিসোর্স প্রস্তুত করে।
  • pnpm bootstrap:with-remote: নির্ভরতা, স্থানীয় ও রিমোট রিসোর্স ইনিশিয়ালাইজ করে এবং সংশ্লিষ্ট প্যাকেজগুলো ক্রমানুসারে তৈরি করে, তবে ডেস্কটপ অ্যাপ bundle বাদ দেয়।
  • pnpm build: প্রতিটি workspace প্যাকেজের build স্ক্রিপ্ট পুনরাবৃত্তভাবে চালায়, যার মধ্যে প্যাকেজের রিসোর্স প্রস্তুতির ধাপও রয়েছে।

ডেস্কটপ সংস্করণ চালানো

ইনিশিয়ালাইজেশন শেষ হলে রিপোজিটরির মূল ডিরেক্টরিতে Electron ডেস্কটপ অ্যাপ চালু করুন:

pnpm dev:desktop

pnpm dev:desktop ডিফল্টভাবে pnpm dev:desktop:prod-এর সমতুল্য এবং প্রোডাকশন পরিষেবা কনফিগারেশন ব্যবহার করে। চালু করার স্ক্রিপ্টটি স্থানীয় রানটাইম রিসোর্স প্রস্তুত করবে, ডেস্কটপ Agent তৈরি করবে, তারপর Electron ও সোর্স পর্যবেক্ষণ চালু করবে।

টেস্ট পরিবেশ ব্যবহার করতে চাইলে চালান:

pnpm dev:desktop:test

ডেভেলপমেন্ট ডেটা আলাদা রাখা

ডেভেলপমেন্ট ডেটা ও দৈনন্দিন ব্যবহারের ডেটা মিশে যাওয়া এড়াতে ZCODE_DATA_BASE_DIR দিয়ে আলাদা ডেটা বেস ডিরেক্টরি নির্ধারণ করা যায়। অ্যাপের ডেটা ওই ডিরেক্টরির অধীনে .zcode/-তে লেখা হবে:

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

এই পদ্ধতি macOS ও Linux-এ প্রযোজ্য।

Web ওয়ার্কবেঞ্চ চালানো

Web ফ্রন্টএন্ড বা ব্যাকএন্ড সোর্স কোড পরিবর্তনের সময় যৌথ উন্নয়ন মোড ব্যবহার করার পরামর্শ দেওয়া হয়:

pnpm dev:web

এই কমান্ড একসঙ্গে চালু করবে:

  • Web ডেভেলপমেন্ট সার্ভার, যার ডিফল্ট ঠিকানা http://localhost:5173।
  • স্থানীয় ব্যাকএন্ড, যার ডিফল্ট ঠিকানা http://localhost:3030।

ব্রাউজারে ফ্রন্টএন্ডের ঠিকানায় প্রবেশ করুন। ডেভেলপমেন্ট সার্ভার /ws এবং সাধারণ /api অনুরোধ স্থানীয় ব্যাকএন্ডে প্রক্সি করবে; /api/v1/oauth/token আলাদাভাবে বর্তমানে কনফিগার করা প্রোডাক্ট পরিষেবায় প্রক্সি হবে।

ব্যাকএন্ড workspace নির্ধারণ

macOS বা Linux-এ পরিবেশ ভেরিয়েবলের মাধ্যমে Web ব্যাকএন্ডের প্রকল্প ডিরেক্টরি নির্ধারণ করা যায়:

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

Agent-এর সোর্স কোড পরিবর্তন করলে CLI ও তার workspace নির্ভরতাগুলো পুনরায় তৈরি করে পরিষেবা পুনরায় চালু করতে হবে:

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

Agent CLI ও TUI উন্নয়ন

টার্মিনাল ইন্টারফেস বা Agent নিয়ে প্রধানত কাজ করলে সরাসরি সোর্স এন্ট্রি চালাতে পারেন:

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

CLI ও তার নির্ভরতাগুলো তৈরি করার পর তৈরি হওয়া CommonJS ফাইলও সরাসরি চালানো যায়:

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

এই সোর্স এন্ট্রি সরাসরি Agent CLI চালায়; একীভূত ডিস্ট্রিবিউশন কমান্ডের --web রাউটিং কার্যকর করে না। Web উন্নয়নের জন্য pnpm dev:web ব্যবহার করুন; একীভূত zcode কমান্ড পরীক্ষা করতে কমান্ড-লাইন ডিস্ট্রিবিউশন প্যাকেজ তৈরি করে আনজিপ করতে হবে।

ZCode কমান্ড-লাইন সংস্করণ ব্যবহার

কমান্ড-লাইন ডিস্ট্রিবিউশন প্যাকেজ TUI, Web, ব্যাকএন্ড ও Agent-কে একত্র করে এবং সবকিছু zcode দিয়ে চালু করে। এটি Electron-এর ওপর নির্ভর করে না, তবে রানটাইমের জন্য এখনও mise.toml-এ নির্ধারিত Node.js প্রয়োজন।

মৌলিক কমান্ড

# টার্মিনাল ইন্টার‌্যাক্টিভ ইন্টারফেসে প্রবেশ
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-এ শোনা হয়, খালি পোর্ট স্বয়ংক্রিয়ভাবে বেছে নেওয়া হয় এবং ব্রাউজার খোলা হয়। ডিফল্টভাবে অ্যাক্সেস টোকেন সক্রিয় থাকে না। কাজ শেষ হলে টার্মিনালে Ctrl+C চাপুন।

লোকাল নেটওয়ার্কে প্রবেশ

অন্য ডিভাইসগুলোকে প্রবেশের অনুমতি দিতে listening address 0.0.0.0 করুন:

zcode --web --host 0.0.0.0

স্থানীয় কম্পিউটার ছাড়া অন্য ঠিকানায় শুনলে ZCode ডিফল্টভাবে একটি অ্যাক্সেস টোকেন তৈরি করবে। টার্মিনালের আউটপুটে থাকা টোকেন-সহ লিংক ব্যবহার করে পরিষেবায় প্রবেশ করুন। --token দিয়ে টোকেন নির্ধারণ করা যায়, অথবা --no-token দিয়ে টোকেন প্রমাণীকরণ বন্ধ করা যায়।

সাধারণ Web পরিষেবার HTTP entry সরাসরি চালু করার সময় ZCODE_SERVER_AUTH_TOKEN দিয়ে API ও WebSocket প্রমাণীকরণ কনফিগার করা যায়; প্রোগ্রামেটিক API দিয়ে পরিষেবা তৈরি করার সময় authToken অপশন ব্যবহার করতে হবে।

পরিবেশ ভেরিয়েবল কনফিগার করা

রিপোজিটরির মূল ডিরেক্টরির .env.example ফাইলে পরিষেবা ঠিকানা ও build কনফিগারেশনের উদাহরণ রয়েছে। প্রয়োজনে এটি .env হিসেবে কপি করুন এবং শুধু স্থানীয় ব্যবহারের override-গুলো .env.local-এ রাখুন।

  • ZCODE_DATA_BASE_DIR: অ্যাপের ডেটা বেস ডিরেক্টরি; ডেটা এর অধীনে .zcode/-তে লেখা হয়।
  • ZCODE_SERVER_WORKSPACE: Web ব্যাকএন্ড workspace-এর পথ নির্ধারণ করে।
  • ZCODE_BUILTIN_PROVIDER_CONFIG_FILE: স্থানীয় Provider কনফিগারেশন ফাইল নির্ধারণ করে; নির্ধারণ না করলে বিল্ট-ইন কনফিগারেশন ব্যবহার করা হয়।
  • ZCODE_DIST_BASE_URL: কমান্ড-লাইন ইনস্টলেশন স্ক্রিপ্টে ব্যবহৃত ডাউনলোডের মূল ঠিকানা।

এই রানটাইম ভেরিয়েবলগুলো সরাসরি চালু করার কমান্ডের পরিবেশেও রাখা যায়। Desktop-এর ডেভেলপমেন্ট পরিষেবা কনফিগারেশন dev:desktop:test ও dev:desktop:prod দিয়ে নির্বাচন করা হয়।

SSH ও WSL রিমোট ফিচার উন্নয়ন

রিমোট workspace ফিচার উন্নয়নের আগে রিমোট রিসোর্স প্রস্তুত করুন:

pnpm bootstrap:with-remote
pnpm dev:desktop

রিমোট প্রকল্পে সংযোগ করার সময় রিসোর্স হিসেবে “স্থানীয়ভাবে ডাউনলোড করে আপলোড” নির্বাচন করুন। ডেভেলপমেন্ট পরিবেশ স্থানীয় packages/desktop/mock-cdn এবং স্থানীয় build artifact থেকে রিসোর্স সংগ্রহ করবে, তারপর SFTP-এর মাধ্যমে রিমোট হোস্টে আপলোড করবে; CDN-এ প্রবেশ করবে না।

ডেস্কটপ ইনস্টলার তৈরি

ডেস্কটপ সংস্করণ তৈরি করতে নিচের কমান্ড চালান:

pnpm bundle:desktop

ডিফল্ট লক্ষ্য macOS arm64 এবং আউটপুট ডিরেক্টরি packages/desktop/dist/। অপারেটিং সিস্টেম ও CPU আর্কিটেকচারও নির্ধারণ করা যায়:

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

--os mac, win ও linux সমর্থন করে; --arch x64 ও arm64 সমর্থন করে। প্রকৃত প্যাকেজিং ও সাইনিংয়ের জন্য লক্ষ্য প্ল্যাটফর্মের উপযুক্ত টুল ও কনফিগারেশন এখনও প্রয়োজন।

macOS-এ তৈরি DMG খুলে ZCode-কে “Applications”-এ টেনে আনুন। স্থানীয়ভাবে unsigned build প্রথমবার চালু করার সময় সিস্টেম বাধা দিলে চালান:

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

কমান্ড-লাইন ডিস্ট্রিবিউশন প্যাকেজ তৈরি

কমান্ড-লাইন ডিস্ট্রিবিউশন প্যাকেজ তৈরির entry point হলো pnpm build:zcode। Build করার আগে ডাউনলোডের মূল ঠিকানা ZCODE_DIST_BASE_URL নির্ধারণ করা আবশ্যক; চাইলে --base-url দিয়ে সরাসরি পাঠানো যায়:

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

# ZCODE_DIST_BASE_URL কনফিগার করা থাকলে
pnpm build:zcode

# বিদ্যমান বিল্ড আর্টিফ্যাক্ট পুনর্ব্যবহার করে শুধু পুনরায় প্যাকেজ করা
pnpm build:zcode --skip-build

# ঐচ্ছিক প্যারামিটার দেখা
pnpm build:zcode --help

এখানকার ডাউনলোড ঠিকানাটি শুধু একটি প্লেসহোল্ডার উদাহরণ; আনুষ্ঠানিক প্রকাশের সময় এটি প্রকৃত হোস্টিং ঠিকানা দিয়ে প্রতিস্থাপন করতে হবে। বিল্ড স্ক্রিপ্টটি ক্রমানুসারে CLI/TUI, ব্যাকএন্ড এবং Web প্রক্রিয়া করে, নেটিভ লাইব্রেরি, worker ও রানটাইম নির্ভরতা সংগ্রহ করে, তারপর রিলিজ প্যাকেজ তৈরি করে।

ডিফল্ট সংস্করণটি মূল ডিরেক্টরির package.json থেকে নেওয়া হয় এবং আউটপুট ডিরেক্টরি হলো dist/zcode/। এতে রয়েছে:

  • releases/<version>/zcode-<version>.tar.gz: রানটাইম প্যাকেজ।
  • releases/<version>/sha256.txt: যাচাইকরণ হ্যাশ।
  • latest.json: সংস্করণ সূচি।
  • install.sh: ইনস্টলেশন স্ক্রিপ্ট।

ইনস্টলেশন স্ক্রিপ্টটি ডিফল্টভাবে রানটাইম ~/.zcode/runtime-এ ইনস্টল করে এবং ~/.local/bin-এ zcode কমান্ড তৈরি করে। ZCODE_DIST_HOME ও ZCODE_DIST_BIN_DIR দিয়ে যথাক্রমে এই দুটি অবস্থান পরিবর্তন করা যায়।

স্থানীয়ভাবে রিলিজ প্যাকেজ যাচাই

ফাইল আপলোড বা ইনস্টলেশন স্ক্রিপ্ট চালানো ছাড়াই সরাসরি বিল্ড ফলাফল এক্সট্র্যাক্ট করে চালানো যায়:

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访问 করলে একই ব্যাকএন্ডে হোস্ট করা Web পেজ এবং Agent-এর সম্পূর্ণ সংযোগপ্রবাহ যাচাই করা যাবে। পোর্টটি অবশ্যই খালি থাকতে হবে; pnpm dev:web যদি ইতিমধ্যে এই পোর্ট ব্যবহার করে, তাহলে --port দিয়ে অন্য পোর্ট ব্যবহার করুন।

উন্নত ডেভেলপমেন্ট পরামর্শ

  1. সংশ্লিষ্ট এন্ট্রি ব্যবহারকে অগ্রাধিকার দিন: ডেস্কটপ ফিচারের জন্য dev:desktop, ফ্রন্টএন্ড ও ব্যাকএন্ড একসঙ্গে ডিবাগ করার জন্য dev:web, এবং Agent ও TUI-এর জন্য CLI workspace-এর dev কমান্ড ব্যবহার করুন।
  2. Agent পরিবর্তনের পর পুনরায় বিল্ড করুন: Web পরিষেবা স্বয়ংক্রিয়ভাবে সব Agent বিল্ড ফলাফল পায় না। পরিবর্তনের পর pnpm --filter @zcode/cli... build চালিয়ে পরিষেবা পুনরায় চালু করুন।
  3. পরীক্ষার ডেটা আলাদা রাখুন: বিভিন্ন ডেভেলপমেন্ট পরিস্থিতির জন্য পৃথক ডেটা ডিরেক্টরি তৈরি করতে ZCODE_DATA_BASE_DIR ব্যবহার করুন।
  4. বাহ্যিকভাবে শুনলে প্রমাণীকরণ বজায় রাখুন: --host 0.0.0.0 ব্যবহার করার পর স্বয়ংক্রিয়ভাবে তৈরি টোকেনটি বজায় রাখুন অথবা স্পষ্টভাবে --token সেট করুন।
  5. কমান্ডের উৎস যাচাই করুন: pnpm build:zcode শুধু রিলিজ প্যাকেজ তৈরি করে; সিস্টেমের PATH-এ থাকা বিদ্যমান zcode প্রতিস্থাপন করে না। macOS ও Linux-এ command -v zcode, Windows-এ where.exe zcode চালানো যায়।
  6. ডেভেলপমেন্ট ও রিলিজ যাচাই আলাদা রাখুন: pnpm dev:web সোর্স কোডে দ্রুত পরিবর্তনের জন্য উপযুক্ত; এক্সট্র্যাক্ট করা bin/zcode.mjs চূড়ান্ত একীভূত কমান্ড এবং সম্পূর্ণ রিলিজ প্রবাহ যাচাইয়ের জন্য বেশি উপযোগী।

রিপোজিটরি কাঠামোর সংক্ষিপ্ত পরিচয়

  • packages/desktop: Electron Main, Host, Renderer এবং ডেস্কটপ প্যাকেজিং।
  • packages/web: Web ক্লায়েন্ট।
  • packages/server: HTTP, WebSocket পরিষেবা এবং রিমোট সংযোগ।
  • packages/zcode-server-cli: স্বতন্ত্র Server চালু করা ও প্রসেস পরিচালনা।
  • packages/ui: শেয়ার করা React কম্পোনেন্ট, hooks এবং Zustand স্টেট।
  • packages/services: ব্যবসায়িক পরিষেবা ও স্থায়ীকরণ।
  • packages/shared, packages/rpc, packages/client: শেয়ার করা প্রোটোকল ও টাইপ, RPC ফ্রেমওয়ার্ক এবং Agent ক্লায়েন্ট SDK।
  • packages/provider, packages/provider-node: Provider-এর সাধারণ সক্ষমতা এবং Node.js বাস্তবায়ন।
  • apps/zcode-cli: Agent CLI, TUI, রানটাইম ও টুল।
  • scripts, config, third-party: বিল্ড রক্ষণাবেক্ষণ স্ক্রিপ্ট, অন্তর্নির্মিত কনফিগারেশন এবং তৃতীয় পক্ষের ঘোষণাসংক্রান্ত উপকরণ।

সারসংক্ষেপ

ZCode একই workspace-এর মধ্যে ডেস্কটপ, Web, ব্যাকএন্ড এবং Agent CLI একত্রিত করে। প্রথমবার ডেভেলপমেন্ট শুরু করতে pnpm bootstrap চালান, এরপর লক্ষ্য অনুযায়ী pnpm dev:desktop, pnpm dev:web অথবা CLI সোর্স এন্ট্রি বেছে নিন। রিমোট workspace পরীক্ষা করতে বা আনুষ্ঠানিক রিলিজ তৈরি করতে হলে রিমোট রিসোর্স প্রস্তুত করে সংশ্লিষ্ট ডেস্কটপ বা কমান্ড-লাইন ইনস্টলেশন প্যাকেজ বিল্ড করুন।