دوز مباشرة للمحتوى الرئيسي
دروس فالذكاء الاصطناعي

شغّل وكلاء برمجة بلا فقدان فمسارات Shell باستعمال UNCUT

كيشرح هاد الدليل كيفاش تثبّت وتهيّأ UNCUT، وهو مشغّل صغير لوكلاء البرمجة بلا واجهة، مخصّص للطرفيات، ومهام CI، والحاويات، والتجارب. غادي تتعلّم كيفاش تشغّل التعليمات، وتعالج المدخلات الممرّرة عبر الأنابيب، وتستعمل الأدوات بأمان، وتكمّل جلسات JSONL، وتستهلك أحداث NDJSON، وتتعامل مع حدود المزوّد بلا اقتطاع صامت.

حوالي 23 دقايق ديال القراية
شغّل وكلاء برمجة بلا فقدان فمسارات Shell باستعمال UNCUT

شنو هي UNCUT؟

UNCUT هو harness ديال coding agents بلا واجهة، مصمّم للـ shell pipelines، مهام CI، الحاويات، وتجارب agents. كيتوزّع على شكل binary صغير ومربوط بشكل ثابت بـ Go، وكيتواصل عبر الإدخال والإخراج المعياريين. ما فيه لا واجهة مستخدم طرفية، لا telemetry، لا نظام plugins، لا agents خدامين فالخلفية، لا retries أوتوماتيكية، ولا ضغط خفي للسياق.

السلوك الأساسي ديالو هو عقد النقل بلا فقدان. UNCUT كيرسل المحادثة كاملة مع كل نداء للنموذج، وما كيقصّش، ما كيلخّصش، ما كينقّيش، وما كيعاودش يكتب prompts صحيحة بـ UTF-8، أو الرسائل المخزّنة، أو محتوى الملفات، أو خرج الأوامر. إلا وقف provider الجواب بسبب حدّ الإخراج، UNCUT كيعطي error بلا ما يعتبر الجواب الناقص جواباً ناجحاً.

مهم: النقل بلا فقدان ما كيكبّرش context window ديال النموذج وما كيتحكّمش فالمعالجة من جهة provider. provider يقدر ما زال يرفض request كبير بزاف. UNCUT كيبين هاد الفشل بلا ما يحيد المحتوى فصمت.

المزايا الرئيسية

  • سياق كامل: كل رسالة مخزّنة وكل نتيجة ديال tool كيتصيفطو مع كل request للنموذج.
  • خدمة بلا واجهة: النص النهائي كيتكتب فـ stdout، و--json كيعطي أحداث NDJSON منظّمة.
  • Binary قابل للنقل: الإصدارات متوفرة لـ Linux وmacOS وWindows على amd64 وarm64.
  • بروتوكول مستقل على provider: UNCUT كيخدم مع endpoints ديال OpenAI-compatible Chat Completions، بما فيها السيرفرات المحلية.
  • جلسات قابلة للاستئناف: ملفات JSONL كتزاد غير بالإلحاق وكتحافظ على الرسائل الكاملة ونتائج الأدوات.
  • ربعة ديال الأدوات المركّزة: الـ agent يقدر يقرا الملفات، يكتب فيها، يعوّض نص مطابق بالضبط، ويشغّل الأوامر.
  • أخطاء واضحة: UTF-8 غير صالح، جلسات خاسرة البنية، تقليص الإخراج، واستنفاد حدّ الخطوات كيعطيو errors بلا recovery ساكت.

ثبّت UNCUT

Linux

حمّل binary ديال الإصدار اللي كيناسب architecture ديالك. بدّل amd64 بـ arm64 إلا كان النظام 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؛ وMacات Intel كتستعمل 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

استعمل arm64 بلاصة amd64 فـ Windows ARM64. زيد directory ديال الوجهة لـ PATH ديال المستخدم باش يبقى الأمر متاح فجلسات PowerShell الجاية.

التثبيت أو البناء بـ Go

إلا كان Go 1.26 أو أحدث مثبت، ثبّت آخر نسخة مباشرة:

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

ولا بنِ نسخة من repository محمّلة عندك:

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 كمسار الإخراج.

تحقّق من الـ binaries اللي تحمّلو

كل إصدار فيه ملف 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 -

الـ binaries ديال الإصدار ما موقّعاش حالياً بالكود، وبهذا Gatekeeper أو SmartScreen يقدرو يبيّنو تحذير. تحقّق من checksum ديال SHA-256 قبل ما تسمح بتشغيل executable. من بعد التحقّق فـ macOS، تقدر تحيد quarantine غير من الـ binary المثبّت:

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

كوّن provider ديال النموذج

UNCUT محتاج معرّف ديال النموذج. بالنسبة لخدمة مستضافة، غالباً كيحتاج حتى API key. عيّن الجوج ديال القيم ومن بعد شغّل prompt:

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

الـ endpoint الافتراضي هو https://api.openai.com/v1، إلا كان UNCUT_BASE_URL أو OPENAI_BASE_URL معيّن. باش تستعمل endpoint آخر متوافق مع OpenAI، عطِ base URL ديالو:

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

UNCUT كيجرّب حتى OPENAI_API_KEY من بعد UNCUT_API_KEY. فالعادة ما كايناش حاجة لـ key مع endpoints المحلية.

ربط مع Ollama المحلي

المثال اللي تجرّب فـ README كيستعمل model qwen3:8b مثبّت وكيقدر يستعمل الأدوات:

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

عوّض المثال بنموذج مثبّت فالجهاز ديالك. الجودة والسلوك ديال tool calls كيعتمدو على النموذج المختار.

شغّل أول مهمة coding ديالك

بدا 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.

استعمل UNCUT فـ pipelines ديال Unix

UNCUT كيزيد الدخل اللي جاي عبر pipe للـ prompt حرفياً. هاد الشي كيخليه مناسب لمراجعة التغييرات وتحليل السجلات بلا ما تحتاج تصايب ملفات مؤقتة.

git diff | uncut "راجع هاد diff. ما تبدّل حتى ملف."
cat failing-test.log | uncut "قلّب على السبب المحتمل"

الدخل خاصو يكون UTF-8 صحيح. UNCUT كيرفض الدخل غير الصحيح بلا ما يعوّض البايتات فصمت. وكيرفض حتى الملفات الثنائية. فـ Windows، كوّن الأدوات باش تخرّج UTF-8 إلا أمكن، حيث شي أوامر كتنتج UTF-16 ولا مخرجات بترميز code page.

استهلك أحداث NDJSON مهيكلة

استعمل --json ملي كتدمج UNCUT مع السكريبتات، أنظمة CI، ولا بنية أخرى ديال الأَجينتات:

uncut --json "شغّل الاختبارات وصلّح المشكل"

تيار الأحداث يقدر يحتوي على أنواع السجلات التالية:

  • user لرسائل المستخدم.
  • assistant لرسائل المساعد واستدعاءات الأدوات الكاملة.
  • assistant_meta لمعلومات الاستعمال وأسباب التوقّف.
  • tool للنتائج الكاملة ديال الأدوات.
  • done ملي كتكمّل العملية بنجاح.
  • error ملي كتفشل العملية.

UNCUT كيستعمل Chat Completions بلا streaming. كيدعم النص واستدعاءات الأدوات، ولكن ما كيدعمش إدخال الصور.

صايب الجلسات وكملها

الجلسة هي سجل JSONL كيتزاد فيه فقط، وكيحتوي على المحادثة كاملة ونتائج الأدوات. بدا المهمة بملف جلسة، ومن بعد عاود استعمل نفس الملف باش تكمل:

uncut --session .uncut/work.jsonl "بدا refactor"
uncut --session .uncut/work.jsonl "كمّل بالاختبارات"

إلا كان الملف موجود من قبل، UNCUT كيحمّل التاريخ كامل ديالو. السجلات الجديدة كتزاد وكتتزامن من بعد كل خطوة. السجلات غير الصحيحة ولا الناقصة كتسبب خطأ واضح وما كيتحيدوش باش تفرض تحميل الجلسة.

ملفات الجلسات تقدر تحتوي على الكود المصدري، مخرجات الأوامر، بيانات الدخول، ولا أسرار أخرى. حميها بالشكل المناسب وتفادى ترفعها لنظام تتبّع الإصدارات.

تحكّم فمساحة العمل ودورة الأَجينت

استعمل --cwd باش تخدم على مساحة عمل مختلفة على الدوسي الحالي:

uncut --cwd ./services/api "شغّل اختبارات الـ API وشرح أي فشل وقع"

كاينين عدة ديال الخيارات كيتحكمو فالسلوك ديال الطلب والدورة:

  • --max-steps <n> كيحدّد عدد استدعاءات الموديل. القيمة الافتراضية هي 32.
  • --max-tokens <n> كيحدّد حدّاً صريحاً لمخرجات المزوّد عوض الاستعمال ديال القيمة الافتراضية ديالو.
  • --request-timeout <duration> كيبدّل المهلة الزمنية لكل طلب من القيمة الافتراضية ديال 10m. القيمة 0 كتعطّل المهلة.
  • --no-agents كيمنع UNCUT من قراية AGENTS.md ديال مساحة العمل.

بشكل افتراضي، UNCUT كيقرا AGENTS.md كامل من جذر مساحة العمل وكيزيدو للـ system prompt. ملي كتكمّل جلسة، كيعاود يستعمل رسالة النظام الأصلية المخزّنة عوض ما يعاود يبنيها من الملف الحالي.

فهم رموز الخروج

رموز الخروج الموثوقة كتخلي UNCUT مفيد فالأتمتة:

  • 0 كيعني أن الأَجينت عطى جواب نهائي ناجح.
  • 1 كيشير لخطأ فالمزوّد، الإدخال/الإخراج، الجلسة، ولا التنفيذ.
  • 2 كيشير لاستعمال غير صحيح لسطر الأوامر.
  • 3 كيعني أن المزوّد رجّع finish_reason=length ولا max_tokens؛ UNCUT رفض الجواب الناقص.
  • 4 كيعني أن الحد الأقصى ديال الخطوات توصل ليه قبل ما يخرج جواب نهائي.

فـ CI، اعتابر أي رمز ماشي صفر عملية فاشلة وفتّش إما فـ stderr ولا فآخر حدث error ديال --json.

نصائح متقدمة

اختار الحدود بقصد

حيت UNCUT ما كيديرش ضغط للسياق، الجلسات الطويلة ونتائج الأدوات الكبيرة يقدرو فالأخير يفوتو حجم السياق ديال الموديل. بدا جلسة جديدة ملي يكون مناسب، اختار مزوّداً عندو سعة سياق كافية، وما تحدّدش --max-tokens إلا إلا كنت فاهم حدّ الاستجابة ديال المزوّد. UNCUT ما غاديش يجمع الاستجابات الناقصة ولا يعاود المحاولة أوتوماتيكياً.

خلّي العمليات المؤتمتة قابلة للقراية آلياً

استعمل --json مع CI والدمجيات عوض تحليل النص النهائي الحواري. أحداث metadata المنفصلة كتخلي المستهلكين يفتاشو فـ أسباب التوقّف والاستعمال بلا ما يخلطوها مع محتوى المساعد.

استعمل بيئات معزولة للخدمة غير الموثوقة

UNCUT ماشي sandbox. رغم أن أدوات الملفات كتفرض حدود مساحة العمل، run_command كيتنفّذ بصلاحيات مستخدم نظام التشغيل الحالي وما كتقيّدوش فحوصات الملفات. شغّل الـ prompts ولا المستودعات غير الموثوقة داخل container مؤقت ولا بيئة معزولة أخرى. راجع تغييرات الملفات وسجلات الجلسات بنفسك.

ما كايناش ديالوجات ديال الموافقة، ولا كوميتات أوتوماتيكية، ولا معاودات أوتوماتيكية، ولا حلقات خفية ديال الاسترجاع. هاد الشي كيخلي سلوك التنفيذ مباشر، ولكن كيعني حتى بلي نتا المسؤول على اختيار بيئة مقيّدة بالشكل المناسب.

تحقّق محلياً من عقد النقل بلا فقدان

المستودع فيه سكريبت حتمي ديال الإثبات كيستعمل الباينري الحقيقي ومزوّد محلي. كيحتاج Python 3، ولكن ما كيحتاج لا مفتاح API، لا موديل خارجي، لا حزمة Python من طرف ثالث:

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

الإثبات كيتحقق من النقل الكامل ديال الملفات الكبيرة ومخرجات الأوامر، واستئناف الجلسة بشكل مطابق، وسلوك التعديل، وأخطاء الاقتطاع الصريحة، وحدود الخطوات، والتعامل مع UTF-8 غير الصالح. هاد الاختبارات كيقيسو سلوك النقل، ماشي جودة الموديل. النتائج المسجّلة وتعليمات إعادة الإنتاج متوفرة فـ مستودع UNCUT.

شغّل فحوصات التطوير

ملي كتعدّل UNCUT راسو، نسّق، واختبر، ودير vet لكود Go:

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

الخلاصة

UNCUT كيوفّر طريقة صغيرة وشفافة عن قصد لتشغيل وكلاء البرمجة من التيرمينالات، والـ pipelines، والكونتينرات، وأنظمة CI. النقل الكامل للرسائل، والتعامل الصريح مع الأخطاء، والجلسات القابلة للاستئناف، والأحداث المهيكلة، والأدوات الأربعة المدمجة، كيخليوه مفيد ملي كيكون الاختصار الصامت للسياق غير مقبول. كوّن endpoint متوافق مع OpenAI، وبدا فمساحة عمل معزولة، واستعمل الجلسات أو مخرجات NDJSON ملي كتحتاج أوتوماتيزاسيون قابلة لإعادة الإنتاج.