فلیٹ ورکر چلائیں

اپنی فلیٹ میں ایگزیکیوشن صلاحیت بڑھانے کے لیے کسی فارغ مشین پر cc_worker چلائیں۔ یہ ایک pure-Dart بائنری ہے — کوئی Flutter انجن نہیں — جو کسی cc_server سے پیئر ہوتی ہے، میزبان کی صلاحیتیں ظاہر کرتی ہے، ہارٹ بیٹ دیتی ہے، لیز پر لیے گئے جابز کھینچتی ہے، اُنہیں چلاتی ہے اور پروسیس ایونٹس واپس اسٹریم کرتی ہے۔ یہ کوئی پائیدار حالت نہیں رکھتی: ایک سپروائزر اسے دوبارہ شروع کرتا ہے اور یہ پھر رجسٹر ہو جاتی ہے۔

پہلے آپ کو ایک چلتا ہوا cc_server درکار ہے — دیکھیں ہیڈلیس سرور چلائیں۔

ایک پیئر شدہ ورکر رجسٹر ہوتی ہے، ہارٹ بیٹ دیتی ہے اور لیز پر لیے گئے جابز کا انتظار کرتی ہے۔ fleet.submitJob سے کام جمع کرائیں۔ اِس سرور پر ایجنٹ ڈسپیچ فلیٹ سے ہو کر نہیں گزرتا؛ اِس گائیڈ کی کامیابی کی علامت یہ ہے کہ ورکر تازہ ہارٹ بیٹ کے ساتھ فلیٹ پینل میں ظاہر ہو۔ بوٹ پر رجسٹرڈ in-process ورکر کا رنر نقشہ خالی ہوتا ہے، اس لیے اُس پر رکھا گیا جاب No local runner for job kind … واپس کرتا ہے۔

پیشگی شرائط

Dart SDK۔ یہ ریپو اپنا SDK fvm سے پن کرتا ہے، اس لیے کمانڈز سے پہلے fvm لگائیں۔
یہ ریپوزٹری ورکر مشین پر چیک آؤٹ ہو۔
ایک قابلِ رسائی cc_server (ڈیولپمنٹ کے لیے loopback، پروڈکشن کے لیے LAN یا ریموٹ)۔
PATH پر git — ورکر ریپوز میٹیریلائز کرتی ہے اور git پروبز چلاتی ہے۔

مرحلہ 1: بائنری بنائیں

cd apps/cc_worker
fvm dart build cli

یہ ./build/cli/<os_arch>/bundle/bin/cc_worker پر ایک خود مکتفی بنڈل تیار کرتا ہے۔

مرحلہ 2: ورکر کی اسناد جاری کریں

ایک cc_server صرف اُسی ورکر کو قبول کرتا ہے جو پیئر شدہ ڈیوائس id اور پہلے سے شیئر کی گئی کلید پیش کرے — بشمول loopback سرور۔ انہیں سرور مشین پر جاری کریں (pair سرور کے چلتے ہوئے بھی چل سکتا ہے؛ نئی ڈیوائس بغیر ری اسٹارٹ کے اٹھا لی جاتی ہے):

cc_server pair --data-dir <dir> --device my-worker --label "Build box"

یہ ایک Device id اور ایک Pairing key پرنٹ کرتا ہے — --device-id اور --psk / --psk-file / CC_WORKER_PSK یہی لیتے ہیں۔

مرحلہ 3: ورکر شروع کریں

پیئر شدہ سرور کے سامنے:

./build/cli/<os_arch>/bundle/bin/cc_worker \
  --server wss://host:9030 --device-id my-worker --psk-file /path/to/worker.psk

loopback سرور کے سامنے (پھر بھی پیئر شدہ — cc_server ہمیشہ PSK ہینڈ شیک چلاتا ہے):

fvm dart run cc_worker --server ws://localhost:9030 \
  --device-id my-worker --psk-file /path/to/worker.psk

فلیگ	تفصیل	ڈیفالٹ
`--server <url>`	cc_server URL (`ws://`/`wss://`؛ `http(s)` اور غائب `/rpc` راستہ زبردستی درست کر دیے جاتے ہیں)۔ لازمی۔	—
`--name <name>`	آپریٹر کو دکھنے والا ورکر نام۔	میزبان کا نام
`--device-id <id>`	مستحکم پیئر شدہ ڈیوائس id، جو ورکر id کے طور پر بھی استعمال ہوتا ہے۔	`cc-worker`
`--psk-file <path>`	وہ فائل جس کی پہلی غیر خالی سطر پیئرنگ کلید ہے۔ `--psk` پر ترجیح دی جاتی ہے۔	—
`--psk <key>`	کمانڈ لائن پر پیئرنگ کلید۔ `ps` اور شیل ہسٹری میں نظر آتی ہے — بائنری انتباہ دیتی ہے۔	—
`--max-jobs <n>`	اِس پروسیس کے بیک وقت چلنے والے جابز کی سخت حد (مثبت عدد)۔	`4`

کلید کے لیے ترجیحی ترتیب --psk-file → CC_WORKER_PSK → --psk ہے۔ ہر ذریعہ چھوڑ دینے سے ورکر کا auth ہینڈ شیک چھوٹ جاتا ہے؛ پھر ایک حقیقی cc_server غیر تصدیق شدہ ورکر قبول کرنے کے بجائے سیشن مسترد کر دیتا ہے (auth_denied)۔ نامعلوم فلیگز استعمال کی خرابی ہیں (exit 64) — cc_server کے برعکس یہ بائنری package:args استعمال کرتی ہے اور ٹائپو نظر انداز نہیں کرتی۔

CC_WORKER_CACHE ورک ٹری میٹیریلائزیشن کیش ڈائریکٹری کو اوور رائیڈ کرتا ہے (ڈیفالٹ: سسٹم ٹیمپ ڈائر کے نیچے ایک cc_worker_cache ڈائریکٹری)۔

ورکر fleet.registerWorker سے رجسٹر ہوتی ہے، پھر ہر 20 سیکنڈ بعد ہارٹ بیٹ دیتی ہے اور ہر 2 سیکنڈ بعد لیز کے لیے پول کرتی ہے۔ یہ SIGINT/SIGTERM تک چلتی ہے؛ اسے systemd یا launchd کے تحت رکھیں تاکہ کریش یا ری بوٹ کے بعد دوبارہ شروع ہو کر پھر رجسٹر ہو جائے۔

مرحلہ 4: فلیٹ پینل میں تصدیق کریں

ڈیسک ٹاپ یا ویب ایپ میں آبزرویبلٹی کھولیں، لائیو ٹیب پر جائیں اور نیچے تک اسکرول کریں۔ ورکرز ہر رجسٹرڈ ورکر کو اُس کے پلیٹ فارم، کورز، قابلیت کی کلیدوں اور آخری ہارٹ بیٹ کے ساتھ فہرست کرتا ہے؛ جابز اُن میں تقسیم شدہ جابز کی فہرست دیتا ہے۔

آپ کی ورکر کا وہاں حالیہ ہارٹ بیٹ کے ساتھ ظاہر ہونا ہی اِس بات کی تصدیق ہے کہ پیئرنگ اور رجسٹریشن کام کر گئی۔

کسی ورکر کے ٹائل سے آپ ڈرین کے ذریعے اُسے روک سکتے ہیں (موجودہ جابز مکمل کرے، کوئی نئی لیز نہ لے)، جاری رکھیں سے ڈرین ہو رہی ورکر بحال کر سکتے ہیں، منسوخ کریں سے اس کی اسناد باطل کر سکتے ہیں، یا ہٹائیں سے قطار ہٹا سکتے ہیں۔

ورکر اور جاب کی قطاریں سرور کی global.db میں رہتی ہیں — ورکر خود میٹیریلائزیشن کیش کے سوا ڈسک پر کچھ نہیں لکھتی۔

ورکر کیا ظاہر کرتی ہے

رجسٹریشن پر ورکر اپنی صلاحیتیں خودکار طور پر شناخت کرتی ہے اور شیڈیولر اُن کے مطابق جابز رکھتا ہے۔ آپ انہیں ہاتھ سے کنفیگر نہیں کرتے:

OS اور آرک (macos/linux/windows, arm64/x64) — درست پروبز، uname -m / PROCESSOR_ARCHITECTURE پر فال بیک کے ساتھ
کورز اور RAM — درست کور گنتی؛ جب پروب نہ ہو سکے تو RAM 0 تک گر جاتی ہے
flutter — جب Flutter SDK قابلِ رسائی ہو تو سیٹ ہوتا ہے (سادہ flutter، پھر fvm flutter)؛ golden-render جابز کو اِس کی ضرورت ہوتی ہے
sandbox — macOS پر native-macos، Linux پر native-linux۔ یہ ایک پلیسمنٹ اشارہ ہے، کوئی وعدہ نہیں: ورکر وہ بیک اینڈ ظاہر کرتی ہے جو اس کے پلیٹ فارم کے پاس ہے، مگر وہ اپنے چلائے جانے والے جابز کو کسی ایک میں نہیں لپیٹتی۔ cc_server کے برعکس، cc_worker لیز پر لیا گیا جاب براہِ راست اسپان کرتی ہے
always-on اور parallel — ایک مخصوص cc_worker ہمیشہ دونوں ظاہر کرتی ہے، اس لیے یہ ایوال بیچز اور دیگر وقتی متوازی صلاحیت کے لیے اہل ہوتی ہے

شناخت حتیٰ الامکان ہوتی ہے: جو چیز بھی پروب نہ ہو سکے وہ اسٹارٹ اپ ناکام کرنے کے بجائے ایک محفوظ ڈیفالٹ تک گر جاتی ہے۔

ورکر کیا چلائے گی

لیز پروٹوکول چھ جاب اقسام اٹھاتا ہے:

قسم	یہ کیا ہے
`agentRun`	ایک واحد ایجنٹ رن (ڈسپیچ)
`pipelineStep`	ایک پائپ لائن قدم کا عمل درآمد
`codeIndex`	ایک ریپو کوڈ انڈیکس بلڈ
`goldenRender`	ایک UI بصری گولڈن رینڈر (`flutter` درکار)
`benchmark`	ایک پرفارمنس بینچ مارک رن
`evalBatch`	ایک ایوال بیچ (`parallel` صلاحیت کو ترجیح دیتا ہے)

عمل درآمد ایک حقیقی subprocess-اسٹریمنگ نفاذ ہے، کوئی مکمل ایمبیڈڈ ایجنٹ رن ٹائم نہیں۔ جب کوئی لیز repoRemote اٹھائے تو ورکر ایک ریموٹ-اور-SHA-کلید شدہ کیش ڈائریکٹری میں git clone --depth 1 کرتی ہے، پھر git fetch اور git checkout۔ agentRun کے لیے یہ لیز ماحول کے CC_JOB_COMMAND میں دی گئی کمانڈ ورک ڈائریکٹری میں چلاتی ہے اور stdout اور stderr کو ایونٹس کے طور پر واپس اسٹریم کرتی ہے؛ CC_JOB_COMMAND نہ ہونے پر یہ پرامپٹ کی بازگشت دیتی ہے تاکہ ٹرانسپورٹ پھر بھی شروع سے آخر تک آزمایا جائے۔ باقی اقسام چھوٹی حقیقی کمانڈز (git rev-parse HEAD، git --version) بطور دیانت دار پروبز چلاتی ہیں۔ لیز ماحول میں جاب سے وابستہ اسناد ہر subprocess میں انجیکٹ کی جاتی ہیں اور کبھی کسی لاگ میں نہیں لکھی جاتیں۔

ایونٹس بیچ ہو کر ہر 250ms یا ہر 32 ایونٹس پر فلیش ہوتے ہیں؛ ہر جاب ایک done ایونٹ اور ایک تکمیل رپورٹ پر ختم ہوتا ہے۔ یہ ماڈل ہارٹ بیٹس اور مختصر-TTL لیزز پر چلتا ہے: اگر کوئی ورکر رابطہ کھو دے تو اس کی لیز ختم ہو جاتی ہے اور سرور جاب کو دوبارہ کوشش کے لیے اٹھا لیتا ہے۔ ورکر پر کوئی پائیدار حالت نہیں اور ورکرز آپس میں نہ کسی اتفاقِ رائے پر چلتے ہیں نہ ایک دوسرے سے کام چھینتے ہیں۔