UNCUT کے ساتھ شیل پائپ لائنز میں لاس لیس کوڈنگ ایجنٹس چلائیں

UNCUT کیا ہے؟

UNCUT ایک ہیڈلیس کوڈنگ ایجنٹ ہارنس ہے جو شیل پائپ لائنز، CI جابز، کنٹینرز اور ایجنٹ تجربات کے لیے تیار کیا گیا ہے۔ یہ ایک چھوٹی، جامد طور پر منسلک Go بائنری کے طور پر تقسیم کیا جاتا ہے اور معیاری ان پٹ اور معیاری آؤٹ پٹ کے ذریعے مواصلت کرتا ہے۔ اس میں ٹرمینل یوزر انٹرفیس، ٹیلی میٹری، پلگ اِن سسٹم، بیک گراؤنڈ ایجنٹس، خودکار دوبارہ کوششیں یا پوشیدہ سیاق و سباق کا کمپیکشن نہیں ہے۔

اس کا بنیادی رویہ لاس لیس ٹرانسپورٹ معاہدہ ہے۔ UNCUT ہر ماڈل کال پر پوری گفتگو بھیجتا ہے اور درست UTF-8 پرامپٹس، محفوظ شدہ پیغامات، فائل کے مواد یا کمانڈ آؤٹ پٹ کو مختصر، خلاصہ، حذف یا دوبارہ تحریر نہیں کرتا۔ اگر کوئی فراہم کنندہ آؤٹ پٹ کی حد کی وجہ سے جواب روک دیتا ہے تو UNCUT جزوی جواب کو کامیاب جواب سمجھنے کے بجائے ایک خرابی رپورٹ کرتا ہے۔

اہم: لاس لیس ٹرانسپورٹ ماڈل کی سیاق و سباق ونڈو کو بڑا نہیں کرتا اور نہ ہی فراہم کنندہ کی جانب سے ہونے والی پراسیسنگ کو کنٹرول کرتا ہے۔ کوئی فراہم کنندہ اب بھی حد سے بڑے ریکویسٹ کو مسترد کر سکتا ہے۔ UNCUT مواد کو خاموشی سے حذف کرنے کے بجائے اس ناکامی کو نمایاں کرتا ہے۔

اہم خصوصیات

• مکمل سیاق و سباق: ہر ماڈل ریکویسٹ پر ہر محفوظ شدہ پیغام اور ٹول کا نتیجہ بھیجا جاتا ہے۔
• ہیڈلیس آپریشن: حتمی متن stdout پر لکھا جاتا ہے، جبکہ --json ساخت یافتہ NDJSON ایونٹس فراہم کرتا ہے۔
• قابلِ نقل بائنری: ریلیزز Linux، macOS اور Windows کے لیے amd64 اور arm64 پر دستیاب ہیں۔
• فراہم کنندہ سے غیر وابستہ پروٹوکول: UNCUT OpenAI کے موافق Chat Completions اینڈ پوائنٹس کے ساتھ کام کرتا ہے، جن میں مقامی سرورز بھی شامل ہیں۔
• قابلِ بحالی سیشنز: صرف اضافے والی JSONL فائلیں مکمل پیغامات اور ٹول کے نتائج محفوظ رکھتی ہیں۔
• چار مرکوز ٹولز: ایجنٹ فائلیں پڑھ سکتا ہے، فائلیں لکھ سکتا ہے، عین متن تبدیل کر سکتا ہے اور کمانڈز چلا سکتا ہے۔
• واضح ناکامیاں: غلط UTF-8، خراب سیشنز، آؤٹ پٹ کا کٹ جانا اور اسٹیپ کی حد ختم ہونا خاموش بحالی کے بجائے خرابی پیدا کرتے ہیں۔

UNCUT انسٹال کریں

Linux

اپنے آرکیٹیکچر سے مطابقت رکھنے والی ریلیز بائنری ڈاؤن لوڈ کریں۔ ARM64 سسٹم پر amd64 کو arm64 سے تبدیل کریں۔

VERSION=0.1.1
ARCH=amd64
curl -fSLo uncut "https://github.com/Balanov/uncut/releases/download/v${VERSION}/uncut-linux-${ARCH}"
mkdir -p "$HOME/.local/bin"
install -m 0755 uncut "$HOME/.local/bin/uncut"
export PATH="$HOME/.local/bin:$PATH"
uncut --version

اگر $HOME/.local/bin پہلے سے موجود نہ ہو تو اسے اپنی مستقل PATH کنفیگریشن میں شامل کریں۔

macOS

Apple Silicon سسٹمز عموماً arm64 استعمال کرتے ہیں؛ Intel Macs amd64 استعمال کرتے ہیں۔

VERSION=0.1.1
ARCH=arm64
curl -fSLo uncut "https://github.com/Balanov/uncut/releases/download/v${VERSION}/uncut-darwin-${ARCH}"
mkdir -p "$HOME/.local/bin"
install -m 0755 uncut "$HOME/.local/bin/uncut"
export PATH="$HOME/.local/bin:$PATH"
uncut --version

Windows PowerShell

$Version = "0.1.1"
$Arch = "amd64"
$Dest = "$env:LOCALAPPDATA\Programs\UNCUT"
New-Item -ItemType Directory -Force $Dest | Out-Null
Invoke-WebRequest -Uri "https://github.com/Balanov/uncut/releases/download/v$Version/uncut-windows-$Arch.exe" -OutFile "$Dest\uncut.exe"
$env:Path = "$Dest;$env:Path"
uncut --version

Windows ARM64 پر amd64 کے بجائے arm64 استعمال کریں۔ مستقبل کے PowerShell سیشنز میں کمانڈ دستیاب رکھنے کے لیے منزل کے ڈائریکٹری کو اپنے صارف PATH میں شامل کریں۔

Go کے ذریعے انسٹال یا بلڈ کریں

اگر Go 1.26 یا اس کے بعد کا ورژن انسٹال ہے تو تازہ ترین ورژن براہِ راست انسٹال کریں:

go install github.com/Balanov/uncut/cmd/uncut@latest

متبادل طور پر، ریپوزٹری کے چیک آؤٹ کو بلڈ کریں:

git clone https://github.com/Balanov/uncut.git
cd uncut
go build -trimpath -ldflags="-s -w" -o bin/uncut ./cmd/uncut

Windows پر آؤٹ پٹ پاتھ کے طور پر bin/uncut.exe استعمال کریں۔

ڈاؤن لوڈ کی گئی بائنریز کی تصدیق کریں

ہر ریلیز میں checksums.txt فائل شامل ہوتی ہے۔ درج ذیل مثال Linux amd64 ڈاؤن لوڈ کی تصدیق کرتی ہے:

VERSION=0.1.1
ARCH=amd64
curl -fSLO "https://github.com/Balanov/uncut/releases/download/v${VERSION}/checksums.txt"
grep "uncut-linux-${ARCH}$" checksums.txt | sha256sum -c -

ریلیز بائنریاں فی الحال کوڈ سائن شدہ نہیں ہیں، اس لیے Gatekeeper یا SmartScreen انتباہ دکھا سکتے ہیں۔ ایگزیکیوٹیبل کو اجازت دینے سے پہلے SHA-256 چیک سم کی تصدیق کریں۔ macOS پر تصدیق کے بعد قرنطینہ صرف انسٹال شدہ بائنری سے ہٹایا جا سکتا ہے:

xattr -d com.apple.quarantine "$HOME/.local/bin/uncut"

ماڈل فراہم کنندہ کو کنفیگر کریں

UNCUT کے لیے ماڈل شناخت کنندہ درکار ہے۔ ہوسٹڈ سروس کے لیے عموماً API کلید بھی درکار ہوتی ہے۔ دونوں قدریں سیٹ کریں اور پھر ایک پرامپٹ چلائیں:

export UNCUT_API_KEY="your-api-key"
export UNCUT_MODEL="your-model-id"
uncut "Inspect this repository and fix the failing tests"

ڈیفالٹ اینڈ پوائنٹ https://api.openai.com/v1 ہے، الا یہ کہ UNCUT_BASE_URL یا OPENAI_BASE_URL سیٹ ہو۔ کسی دوسرے OpenAI-compatible اینڈ پوائنٹ کو استعمال کرنے کے لیے اس کا بنیادی URL فراہم کریں:

export UNCUT_BASE_URL="https://openrouter.ai/api/v1"

UNCUT UNCUT_API_KEY کے بعد OPENAI_API_KEY پر بھی انحصار کرتا ہے۔ مقامی اینڈ پوائنٹس کے لیے ڈیفالٹ طور پر کلید درکار نہیں ہوتی۔

مقامی Ollama سے مربوط ہوں

README کی آزمودہ مثال میں ٹولز کے قابل، انسٹال شدہ qwen3:8b ماڈل استعمال کیا گیا ہے:

ollama pull qwen3:8b
export UNCUT_BASE_URL="http://localhost:11434/v1"
export UNCUT_MODEL="qwen3:8b"
uncut "Explain this repository"

مثال کو اپنی مشین پر انسٹال شدہ ماڈل سے تبدیل کریں۔ ٹول کال کا معیار اور رویہ منتخب ماڈل پر منحصر ہے۔

اپنا پہلا کوڈنگ ٹاسک چلائیں

UNCUT کو اس ریپوزٹری سے شروع کریں جس کا ایجنٹ معائنہ کرے گا۔ پہلے سے طے شدہ طور پر موجودہ ڈائریکٹری فائل ٹولز اور شیل کمانڈز کے لیے ورک اسپیس بن جاتی ہے۔

cd path/to/project
uncut "اس ریپوزٹری کا معائنہ کریں، ٹیسٹ چلائیں، اور خرابی دور کریں"

ٹاسک کے دوران ماڈل چار ٹولز کال کر سکتا ہے:

• read_file مکمل UTF-8 ٹیکسٹ فائل پڑھتا ہے۔
• write_file مکمل مواد لکھتا ہے اور موجود نہ ہونے والی پیرنٹ ڈائریکٹریاں بناتا ہے۔
• replace عین ایک وقوعہ کو تبدیل کرتا ہے۔ اگر کوئی میچ نہ ملے یا ایک سے زیادہ میچ ملیں تو یہ ناکام ہو جاتا ہے۔
• run_command ایگزٹ کوڈ اور stdout و stderr کا مکمل مشترکہ نتیجہ واپس کرتا ہے۔

فائل ٹولز کے راستے ورک اسپیس کے اندر ہی رہنے چاہییں۔ Unix پر کمانڈز /bin/sh -c کے ذریعے چلتی ہیں۔ Windows پر وہ cmd.exe /D /S /C کے ذریعے چلتی ہیں۔

Unix پائپ لائنز میں UNCUT استعمال کریں

UNCUT پائپ کیا گیا ان پٹ جوں کا توں پرامپٹ کے آخر میں شامل کرتا ہے۔ اس لیے یہ عارضی فائلیں بنائے بغیر جائزوں اور لاگ کے تجزیے کے لیے موزوں ہے۔

git diff | uncut "اس diff کا جائزہ لیں۔ فائلوں میں ترمیم نہ کریں۔"
cat failing-test.log | uncut "ممکنہ وجہ تلاش کریں"

ان پٹ درست UTF-8 ہونا چاہیے۔ UNCUT غلط ان پٹ کو خاموشی سے بائٹس تبدیل کرنے کے بجائے مسترد کرتا ہے۔ یہ بائنری فائلیں بھی مسترد کرتا ہے۔ Windows پر جہاں ممکن ہو یوٹیلیٹیز کو UTF-8 آؤٹ پٹ دینے کے لیے ترتیب دیں، کیونکہ کچھ کمانڈز UTF-16 یا کوڈ پیج آؤٹ پٹ تیار کرتی ہیں۔

منظم NDJSON ایونٹس استعمال کریں

UNCUT کو اسکرپٹس، CI سسٹمز یا دیگر ایجنٹ انفراسٹرکچر کے ساتھ مربوط کرتے وقت --json استعمال کریں:

uncut --json "ٹیسٹ چلائیں اور خرابی دور کریں"

ایونٹ اسٹریم میں درج ذیل ریکارڈ اقسام شامل ہو سکتی ہیں:

• user صارف کے پیغامات کے لیے۔
• assistant اسسٹنٹ کے پیغامات اور مکمل ٹول کالز کے لیے۔
• assistant_meta استعمال کی معلومات اور تکمیل کی وجوہات کے لیے۔
• tool مکمل ٹول نتائج کے لیے۔
• done رن کامیابی سے مکمل ہونے پر۔
• error رن ناکام ہونے پر۔

UNCUT نان اسٹریمنگ Chat Completions استعمال کرتا ہے۔ یہ ٹیکسٹ اور ٹول کالز کو سپورٹ کرتا ہے، لیکن تصویری ان پٹ کو نہیں۔

سیشنز بنائیں اور دوبارہ شروع کریں

سیشن ایک append-only JSONL ریکارڈ ہوتا ہے جس میں مکمل گفتگو اور ٹول نتائج شامل ہوتے ہیں۔ سیشن فائل کے ساتھ ٹاسک شروع کریں، پھر جاری رکھنے کے لیے اسی فائل کو دوبارہ استعمال کریں:

uncut --session .uncut/work.jsonl "ری فیکٹرنگ شروع کریں"
uncut --session .uncut/work.jsonl "ٹیسٹ جاری رکھیں"

اگر فائل پہلے سے موجود ہو تو UNCUT اس کی مکمل تاریخ لوڈ کرتا ہے۔ نئے ریکارڈ شامل کیے جاتے ہیں اور ہر مرحلے کے بعد ہم آہنگ کیے جاتے ہیں۔ غلط یا نامکمل ریکارڈ واضح خرابی پیدا کرتے ہیں اور سیشن لوڈ کرنے پر مجبور کرنے کے لیے انہیں خارج نہیں کیا جاتا۔

سیشن فائلوں میں سورس کوڈ، کمانڈ آؤٹ پٹ، اسناد یا دیگر راز شامل ہو سکتے ہیں۔ ان کی مناسب حفاظت کریں اور انہیں ورژن کنٹرول میں شامل کرنے سے گریز کریں۔

ورک اسپیس اور ایجنٹ لوپ کو کنٹرول کریں

موجودہ ڈائریکٹری کے علاوہ کسی ورک اسپیس کے خلاف چلانے کے لیے --cwd استعمال کریں:

uncut --cwd ./services/api "API ٹیسٹ چلائیں اور کسی بھی خرابی کی وضاحت کریں"

کئی فلیگز درخواست اور لوپ کے رویے کو کنٹرول کرتے ہیں:

• --max-steps <n> ماڈل کالز کی حد مقرر کرتا ہے۔ پہلے سے طے شدہ قدر 32 ہے۔
• --max-tokens <n> فراہم کنندہ کی پہلے سے طے شدہ حد کے بجائے واضح provider آؤٹ پٹ حد مقرر کرتا ہے۔
• --request-timeout <duration> ہر درخواست کی ٹائم آؤٹ کو اس کی پہلے سے طے شدہ 10m قدر سے تبدیل کرتا ہے۔ 0 ٹائم آؤٹ کو غیر فعال کر دیتا ہے۔
• --no-agents UNCUT کو ورک اسپیس کی AGENTS.md پڑھنے سے روکتا ہے۔

پہلے سے طے شدہ طور پر UNCUT ورک اسپیس کی جڑ سے AGENTS.md کو مکمل طور پر پڑھ کر سسٹم پرامپٹ میں شامل کرتا ہے۔ سیشن دوبارہ شروع کرتے وقت یہ موجودہ فائل سے اسے دوبارہ بنانے کے بجائے اصل محفوظ شدہ سسٹم پیغام دوبارہ استعمال کرتا ہے۔

ایگزٹ کوڈز سمجھیں

قابلِ اعتماد ایگزٹ کوڈز UNCUT کو آٹومیشن کے لیے مفید بناتے ہیں:

• 0 کا مطلب ہے کہ ایجنٹ نے کامیاب حتمی جواب تیار کیا۔
• 1 provider، ان پٹ/آؤٹ پٹ، سیشن یا execution خرابی ظاہر کرتا ہے۔
• 2 کمانڈ لائن کے غلط استعمال کو ظاہر کرتا ہے۔
• 3 کا مطلب ہے کہ provider نے finish_reason=length یا max_tokens واپس کیا؛ UNCUT نے نامکمل جواب مسترد کر دیا۔
• 4 کا مطلب ہے کہ حتمی جواب سے پہلے زیادہ سے زیادہ مراحل کی تعداد پوری ہو گئی۔

CI میں ہر غیر صفر کوڈ کو ناکام رن سمجھیں اور stderr یا --json کے حتمی error ایونٹ کا معائنہ کریں۔

اعلیٰ درجے کی تجاویز

حدود سوچ سمجھ کر منتخب کریں

چونکہ UNCUT سیاق و سباق کو مختصر نہیں کرتا، اس لیے طویل سیشنز اور بڑے ٹول نتائج بالآخر ماڈل کی context window سے تجاوز کر سکتے ہیں۔ مناسب وقت پر نیا سیشن شروع کریں، کافی context capacity رکھنے والا provider منتخب کریں، اور --max-tokens صرف اسی وقت مقرر کریں جب آپ provider کی response limit کو سمجھتے ہوں۔ UNCUT جزوی جوابات کو یکجا نہیں کرے گا اور خودکار طور پر دوبارہ کوشش نہیں کرے گا۔

خودکار رنز کو مشینی طور پر قابلِ مطالعہ رکھیں

CI اور انضمامات کے لیے گفتگو کے حتمی ٹیکسٹ کو parse کرنے کے بجائے --json استعمال کریں۔ الگ metadata ایونٹس صارفین کو finish reasons اور usage کا معائنہ کرنے دیتے ہیں، بغیر انہیں اسسٹنٹ کے مواد میں ملائے۔

غیر معتبر کام کے لیے الگ تھلگ ماحول استعمال کریں

UNCUT sandbox نہیں ہے۔ اگرچہ فائل ٹولز ورک اسپیس کی حدود نافذ کرتے ہیں، run_command موجودہ آپریٹنگ سسٹم صارف کی اجازتوں کے ساتھ چلتا ہے اور ان فائل چیکس سے محدود نہیں ہوتا۔ غیر معتبر پرامپٹس یا ریپوزٹریز کو عارضی container یا کسی دوسرے الگ تھلگ ماحول میں چلائیں۔ فائل تبدیلیوں اور سیشن ریکارڈز کا خود معائنہ کریں۔

اس میں منظوری کے کوئی ڈائیلاگ، خودکار کمٹس، خودکار دوبارہ کوششیں، یا پوشیدہ بحالی کے لوپس نہیں ہیں۔ اس سے عمل درآمد کا رویہ براہِ راست رہتا ہے، لیکن اس کا مطلب یہ بھی ہے کہ مناسب طور پر محدود ماحول کا انتخاب آپ کی ذمہ داری ہے۔

نقصان سے پاک معاہدے کی مقامی طور پر تصدیق کریں

ریپوزٹری میں ایک متعین ثبوتی اسکرپٹ شامل ہے جو اصل بائنری اور مقامی فراہم کنندہ استعمال کرتا ہے۔ اس کے لیے Python 3 درکار ہے، لیکن API کلید، بیرونی ماڈل، یا کسی تیسرے فریق کے Python پیکیج کی ضرورت نہیں:

go build -o bin/uncut ./cmd/uncut
python bench/proof.py ./bin/uncut

یہ ثبوت بڑی فائلوں اور کمانڈ کے آؤٹ پٹ کی مکمل ترسیل، سیشن کی درست بحالی، ترمیم کے رویے، واضح truncation ناکامیوں، مرحلہ جاتی حدود، اور غیر درست UTF-8 ہینڈلنگ کی جانچ کرتا ہے۔ یہ جانچیں ماڈل کے معیار کے بجائے ترسیل کے رویے کی پیمائش کرتی ہیں۔ ریکارڈ شدہ نتائج اور دوبارہ عمل درآمد کی ہدایات UNCUT ریپوزٹری میں دستیاب ہیں۔

ترقیاتی جانچیں چلائیں

UNCUT میں ترمیم کرتے وقت Go کوڈ کو فارمیٹ، ٹیسٹ اور vet کریں:

gofmt -w cmd internal
go test -count=1 ./...
go vet ./...

نتیجہ

UNCUT ٹرمینلز، پائپ لائنز، کنٹینرز، اور CI سسٹمز سے کوڈنگ ایجنٹس چلانے کا جان بوجھ کر سادہ اور شفاف طریقہ فراہم کرتا ہے۔ اس کی مکمل پیغام ترسیل، واضح ناکامی سے نمٹنے کا طریقہ، بحال کیے جا سکنے والے سیشنز، ساخت یافتہ ایونٹس، اور چار بلٹ اِن ٹولز اسے ان حالات میں مفید بناتے ہیں جہاں خاموشی سے سیاق و سباق کم کیا جانا ناقابلِ قبول ہو۔ OpenAI سے مطابقت رکھنے والے اینڈ پوائنٹ کو تشکیل دیں، الگ تھلگ ورک اسپیس سے آغاز کریں، اور جب قابلِ تکرار آٹومیشن درکار ہو تو سیشنز یا NDJSON آؤٹ پٹ استعمال کریں۔