الوثائق

دليل البدء

ثبّت srooterctl ووكيل البرمجة بأمر واحد، ثم سجّل الدخول. يفتح الأمر login المتصفح لاعتماد الجهاز الذي يحصل على مفتاحه الخاص (يمكنك الاعتماد من أي متصفح، لذا يعمل عبر SSH). تتطلب البرمجة Node.js 20 أو أحدث.

curl -fsSL https://api.palgu.ai/install.sh | bash
srooterctl login                     # approve in your browser
srooterctl                           # coding session in this directory
srooterctl -p "fix the failing test" # one task, then exit

irm https://api.palgu.ai/install.ps1 | iex       # PowerShell, no admin rights
srooterctl login                     # approve in your browser
srooterctl                           # coding session in this directory
srooterctl -p "fix the failing test" # one task, then exit

هل أنت جديد هنا؟ سجّل حسابك أولاً (عبر رمز لمرة واحدة يصلك بالبريد الإلكتروني؛ وبذلك تُنشأ مؤسستك). تتوفر في صفحة التنزيل أيضاً نسخة Studio لنظامي Mac وWindows.

اختياري: توجيه Claude Code أو Codex عبر Palgu

لا تجري أداة srooterctl أي تعديل على Claude Code أو Codex ما لم تطلب ذلك. يعرض الأمر enable تعديل الإعدادات بدقة قبل حفظه، ولا يؤدي تشغيله مرة أخرى إلى أي تغيير.

srooterctl enable claude    # Claude Code, via ~/.claude/settings.json
srooterctl enable codex     # Codex, via ~/.codex/config.toml
curl -fsSL https://api.palgu.ai/install.sh | bash -s -- --with-claude-codex   # both, at install

أدوات أخرى

تحتوي البوابة على نقطتي نهاية: واحدة أصلية لـ Anthropic على المسار /anthropic/v1/messages وأخرى متوافقة مع OpenAI على المسار /v1/chat/completions. وجّه أي أداة إلى إحداهما باستخدام مفتاح srt_ من لوحة التحكم. الإعداد الكامل: Claude Code وCodex وأدوات أخرى.

أدوات بنمط Anthropic

ANTHROPIC_BASE_URL=https://api.palgu.ai/anthropic
ANTHROPIC_API_KEY=srt_xxx_yyy

aider / العملاء المتوافقون مع OpenAI

OPENAI_BASE_URL=https://api.palgu.ai/v1
OPENAI_API_KEY=srt_xxx_yyy

Claude Code وCodex وأدوات أخرى

أبسط مسار هو تشغيل srooterctl login ثم srooterctl enable claude أو srooterctl enable codex. يؤدي ذلك إلى إعادة استخدام المفتاح الذي حفظه srooterctl لهذا الجهاز. لا يلزم وجود مفتاح API من لوحة التحكم إلا عند ربط أداة يدوياً، أو لإجراء استدعاءات API مباشرة.

كيف يربط الأمر enable كل عميل

يمر Claude Code عبر طبقة الحافة (edge) في Palgu (وهو آمن للمطالبات التي تحتوي على كود)، ويُثبَّت في ~/.claude/settings.json الذي يقرؤه Claude Code في كل جلسة، بما في ذلك --continue والتشغيل من بيئة التطوير (IDE). ويحصل Codex على مزوّد srooter في ~/.codex/config.toml: فهو يتجاهل OPENAI_BASE_URL، لذا فإن الاعتماد على متغيرات البيئة وحدها سيرسل مفتاحك إلى OpenAI ويفشل بالخطأ 401. أعد تشغيل الجلسات المفتوحة بعد التفعيل. هل تنقل جلسة قائمة؟ يلتقطها الأمر srooterctl --continue-claude (أو --continue-codex) في ذلك المجلد.

ربط Claude Code يدويا

أضِف كتلة env إلى ~/.claude/settings.json. يتجاوز هذا طبقة الحافة (edge)، لذا قد يحظر جدار حماية الاستضافة الطلبات التي تحتوي مطالباتها على كود. يُفضَّل استخدام srooterctl enable claude.

ANTHROPIC_BASE_URL=https://api.palgu.ai/anthropic
ANTHROPIC_API_KEY=<your key>

ربط Codex يدويا

ادمجه في ~/.codex/config.toml (مفاتيح المستوى الأعلى قبل أي قسم [section]) مع ضبط المتغير SROOTER_API_KEY. تحذير Model metadata for 'glm-5.3' not found غير ضار. وهذا يتجاوز أيضاً طبقة الحافة (edge).

model = "glm-5.3"
model_provider = "srooter"

[model_providers.srooter]
name = "srooter"
base_url = "https://api.palgu.ai/v1"
env_key = "SROOTER_API_KEY"
wire_api = "responses"

توجيه جلسة واحدة، أو إيقاف التوجيه

srooterctl shell            # routes only this session; exit to leave
srooterctl disable          # new terminals stop routing through Palgu
srooterctl claude-env off   # Claude Code stops routing through Palgu
eval "$(srooterctl on)"     # route this shell in place (off: restore)

فحص سريع للـ API

استبدل النموذج بآخر فعّلته مؤسستك.

source ~/.srooter/config   # loads SROOTER_API_KEY (saved by srooterctl)
curl https://api.palgu.ai/v1/chat/completions \
  -H "Authorization: Bearer $SROOTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<your-model>","messages":[{"role":"user","content":"hello"}]}'

أدوات أخرى

أدوات Cline وRoo Code وKilo Code وContinue وCursor وZed وOpenHands وOpenCode: اختر المزوّد OpenAI Compatible، وعنوان URL الأساسي https://api.palgu.ai/v1، وضع مفتاح srt_ في إعدادات الأداة (وليس في ملف ترفعه إلى المستودع). ولأداة aider:

source ~/.srooter/config   # loads SROOTER_API_KEY (saved by srooterctl)
export OPENAI_API_BASE='https://api.palgu.ai/v1'
export OPENAI_API_KEY="$SROOTER_API_KEY"
aider --model openai/deepseek-pro

الأدوات غير المدعومة أمام Palgu حتى الآن: Windsurf وGemini CLI وAntigravity. مع ذلك، يمكن لـ Palgu تقديم هذه النماذج كواجهات خلفية (backends).

استكشاف الأخطاء وإصلاحها: جلسة لا تمر عبر Palgu

الأعراض: يكتفي الوكيل بوصف التعديلات بدلاً من إجرائها، أو يُظهر سجل التدقيق حركة مرور ضئيلة أو معدومة، أو لا تُطبّق سياساتك. شغّل srooterctl doctor في تلك الطرفية: سيعرض لك بالضبط ما الذي فشل.

• Claude Code: installed, NOT routed through Palgu: شغّل الأمر srooterctl enable claude، ثم أعد تشغيل الجلسة.
• gateway probe: FAIL (401): مفتاحك غير صالح أو منتهي الصلاحية. شغّل srooterctl login مجدداً، أو الصق مفتاحاً جديداً باستخدام srooterctl repair --key-stdin (إدخال مخفي).
• أي غلاف محلي لتوجيه النماذج يسلّم مهام البرمجة إلى أداة CLI أخرى يتعارض مع Palgu: أوقف تشغيله في ذلك المستودع.

ما الجديد

Palgu Studio، تطبيق سطح المكتب

تطبيق palgu> Studio هو تطبيق macOS للبرمجة عبر Palgu. لا يتطلب أي تعديلات على بيئة العمل، ويعتمد التطوير القائم على الاختبار (TDD) مع التحقق الوظيفي والبصري افتراضيا، ويزود الوكيل بالرسم البياني للكود لتوفير سياق المشروع. يمر كل طلب عبر البوابة (التوجيه، الميزانيات، السياسات، والتدقيق). التطبيق موقع وموثق لمعالجات Apple Silicon وIntel.

كل شيء في نافذة واحدة

• المهام حدد مشروعاً، وصف ما تريده؛ وسيتولى وكيل تنفيذ المهمة عبر محادثة حية، مع بث تقدمه لحظياً وطلب الإذن قبل عمليات الكتابة وأوامر الطرفية (shell). شغّل عدة مهام بالتوازي (ضمن شجرة عمل مشتركة أو شجرة عمل معزولة worktree).
• الجلسات جلسات الوكيل السابقة مصنفة حسب اليوم؛ استأنف أي جلسة من حيث توقفت.
• المعرفة الرسم البياني للكود Cortex بالإضافة إلى سجلات جلسات Mnemos. يُفهرَس الرسم البياني عند فتح مشروع، ليبدأ الوكيل بخريطة واضحة للكود. يمكنك تحديث Agent Codemap من هنا أيضاً.
• المجلس (Council) تراجع خمسة نماذج التغيير وفق معايير SOLID و C4 و OWASP وهرم الاختبار (Test Pyramid). يمكنك الاطلاع على نتائجها واختلافاتها، والاعتراض على أي نتيجة.
• المراجعات الصق رابط PR من GitHub (أو راجع الفروق المحلية لديك) للحصول على مراجعة موثوقة من المجلس.
• التوجيه اطّلع على النموذج الذي يوجّه إليه كل مستوى والسبب وراء ذلك (للقراءة فقط؛ التعديل متاح عبر لوحة التحكم على الويب).

هل أنت جديد هنا؟ نزّل Studio أو أدوات CLI، ثم سجّل الدخول: يصحبك دليل البدء داخل التطبيق خطوة بخطوة لإنجاز مهمتك الأولى.

واجهة سطر أوامر البرمجة srooterctl

شغّل srooterctl لفتح جلسة برمجة في مشروعك، أو srooterctl -p "…" لتنفيذ مهمة واحدة والخروج. وهو يحل محل claude أو codex في سير عملك. يتصل وكيل البرمجة ببوابة Palgu الخاصة بك فقط، لذا فإن التوجيه والميزانيات والسياسات والتدقيق وcortex تُطبّق على كل طلب. يتحقق srooterctl من الوكيل مقابل إصدار موقّع قبل كل تشغيل، ويحدثه الأمر srooterctl update.

srooterctl                           # interactive session in this directory
srooterctl -p "summarize src/index.ts"   # one task, then exit (CI-friendly)
srooterctl --continue                # continue your last session (--resume <id> for one)
srooterctl --continue-claude         # pick up a Claude Code session (--continue-codex: Codex)
srooterctl code [--] <args…>          # pass any other agent flag through unchanged
srooterctl review [base] [--yes]     # council review; exit 0 approve, 1 changes requested
srooterctl doctor                    # check the agent, clients and your key

لا يتم أبداً تخمين الكلمات غير المعروفة كأمر توجيهي (prompt): يتوقف الأمر srooterctl fix the test ويقترح srooterctl code -p "fix the test". يظل الأمر srooter-agent صالحاً للعمل ويبدأ من خلال srooterctl. تُقرأ الإعدادات من الخيارات (flags)، ثم من متغيرات البيئة (SROOTER_URL وSROOTER_MODEL وSROOTER_PROJECT لمشروع cortex المعتمد كمرجع)، ثم من الملف ~/.srooter/config الذي ينشئه الأمر login.

الأذونات: تعمل أدوات القراءة فقط دائماً؛ بينما تطلب أدوات الكتابة والطرفية (shell) الموافقة أثناء الجلسة ([y] مرة واحدة، [a] دائماً، [n] رفض). وفي التشغيل غير التفاعلي، تُرفض هذه الأدوات ما لم تمرر الخيار --dangerously-allow-all.

مرجع الأوامر

أوامر الشرطة المائلة (داخل الجلسة)

الخيارات (بعد srooterctl code)

الاستقلالية والتنسيق

• /loop <task> يشغّل مهمة ذاتياً. بعد كل دورة، يقرر نبض البوابة ما إذا كان الوكيل قد توقف قبل الأوان ويجب أن يستمر، فيحقن توجيهه كدورة تالية. تفرض البوابة ميزانية لكل جلسة وحداً أقصى يبلغ 25 تكراراً.
• الوكلاء الفرعيون يمكن للنموذج استدعاء run_subagent لتفويض مهمة فرعية مركزة إلى وكيل فرعي جديد: بسياق مستقل، ونفس الأدوات، ومستوى واحد من التداخل (دون استدعاء ذاتي متكرر). يعمل الوكيل الفرعي بشكل غير تفاعلي، لذا لا تعمل الأدوات ذات التأثيرات الجانبية إلا إذا منح الوكيل الأصلي إذن السماح للكل (allow-all). استخدم الوكلاء الفرعيين للبحث المركز أو المهام المستقلة.
• MCP (مفعّل افتراضياً) اضبط الخوادم في ~/.srooter/mcp.json (للمستخدم) و .mcp.json (للمشروع). تُحمَّل أدواتها تلقائياً بصيغة server__tool، وتخضع لضوابط الأذونات مثل أي أداة كتابة. يُسجَّل الخادم المعطل في السجلات ويُتخطى، ولا يؤدي أبداً إلى إيقاف النظام.

العمليات والجدولة وسير العمل

srooterctl code monitor            # sessions, token totals, spend, scheduled count
srooterctl code schedule           # fire any due scheduled tasks once (cron tick)
srooterctl code schedule run       # foreground scheduler: tick every minute
srooterctl code workflow wf.json   # run a multi-step workflow

• /schedule add <m h dom mon dow> :: <prompt> · list · rm <id>. تُخزَّن في ~/.srooter/agent/schedule.json؛ شغّلها باستخدام schedule (نبضة واحدة، تُربط مع cron النظام) أو schedule run (في الواجهة الأمامية).
• /workflow <file> ملف JSON للخطوات بصيغة { name, steps: [{ id, prompt, dependsOn? }] }. تُنفَّذ الخطوات حسب ترتيب الاعتمادية (تُنفَّذ الخطوات المستقلة في المستوى نفسه بالتوازي)؛ ويمكن لمطالبة أي خطوة الإشارة إلى مخرجات خطوة سابقة باستخدام {{stepId}}. تعمل كل خطوة كوكيل فرعي.

Cortex والمراجعة

• Cortex يمكن للنموذج استدعاء أداة search_cortex التي تستعلم عن الرسم البياني للكود الخاص بمؤسستك عبر البوابة، ليرتكز على رموز برمجية حقيقية بدلاً من الاكتفاء ببحث grep المحلي. يشغّله الأمر /cortex <query> مباشرة. يتطلب مشروعاً مفهرساً (SROOTER_PROJECT).
• المراجعة يرسل الأمر srooterctl review [base]، أو /review داخل جلسة، فرعك المعتمد (بدءاً من نقطة الدمج الأساسية مع origin/<default branch>، أو الأساس الذي تحدده) إلى مجلس المراجعة متعدد النماذج في البوابة، ويطبع الحكم النهائي مع النتائج موضحة بصيغة file:line. ويعرض قائمة بالملفات وحجمها بالبايت ويطلب تأكيدك قبل الإرسال. لا تُرسل ملفات .env* و *.pem و *.key و *secret* و id_rsa* مطلقاً، ويُحدَّد سقف الفروق (diff) عند 120,000 حرف. يقرأ المجلس الفروق فقط ولا يشغّل الكود الخاص بك. راجع مراجعة Palgu.

قواعد التوجيه

يصنّف Palgu كل طلب ضمن مستوى (tier) ويوجهه إلى النموذج المعيّن لذلك المستوى. يمكنك ضبط هذه التعيينات في لوحة التحكم. الإعدادات الافتراضية:

عدّلها في لوحة التحكم لديك ضمن Routing & Flow: اختر النموذج لكل طبقة، ونموذج تصنيف المقاصد، وأعضاء المجلس، وعتبة السياق الطويل. تقيّم المعاينة الفورية إعداداتك من حيث السرعة والتكلفة والجودة ومتوسط التكلفة المدمج لكل $/1k رمز (token)، مع مقارنة مرجعية مقابل تشغيل نموذج رائد واحد لكل المهام. تسري التغييرات على الطلبات الجديدة، ويمكنك استعادة إعدادات Palgu الافتراضية في أي وقت. أما الحدود القصوى الصارمة (قوائم النماذج المسموح بها، وأقصى جهد للاستدلال، وطبقة السرعة) فتوجد ضمن Policies.

الرسم البياني للكود في Cortex

Cortex هو iCPG (رسم بياني ذكي لخصائص الكود)، ويمثّل معرفة مؤسستك بكودها الخاص: الرموز، وروابط الاعتماديات، والمقاصد المستخلصة من سلاسل التوثيق (docstrings). وبمجرد فهرسة المستودع، تجيب جلسات البرمجة عن أسئلة «أين يوجد X» مباشرة من الرسم البياني، وتستخدمه جلسات البرمجة ومراجعات المخاطر لمعرفة ما يتأثر بأي تغيير.

srooter هي أداة CLI الخاصة بـ Cortex من Palgu، ويقوم install.sh بإعدادها إلى جانب srooterctl.

srooter cortex build .         # index this repo (project auto-detected)
srooterctl cortex .            # same, using your saved key + gateway
srooter cortex build . --force # force a re-index
srooterctl cortex-hook on      # auto-index on every Claude Code session
srooterctl doctor             # verify ("cortex auto-index: OK")

تصفّحه في لوحة التحكم لديك ضمن Cortex: بحث عبر الكود والمقصد والذاكرة، وعرض بياني مجمّع، وإحصاءات، وعُقد المقاصد (الأهداف، والثوابت، والقرارات) المستخلصة من الكود.

Codemap للوكيل

ملف CODEMAP.md هو خريطة موجّهة للآلة يقرؤها وكيل الذكاء الاصطناعي أولاً لاستكشاف المستودع: ماهية النظام، وأين تقع المكوّنات، وكيف يتدفق الطلب، والثوابت التي يجب عدم كسرها، بدلاً من استهلاك عشرات استدعاءات الأدوات في تصفح شجرة الملفات. فبينما يمنح AGENTS.md وCLAUDE.md الوكيل القواعد، يمنحه Codemap الخريطة. يولّده Palgu من الرسم البياني للكود لديك، ويكشف الخيار --check أي خريطة قديمة. وهو مكتوب بصيغة Markdown عادية، لذا يمكن لأي وكيل قراءته (Claude Code، وCodex، وCursor، وWindsurf، وOpenCode).

srooter cortex codemap .           # preview a fresh map (stdout)
srooter cortex codemap . --write   # write / refresh CODEMAP.md
srooter cortex codemap . --check   # validate anchors + freshness (exit 1 on error)
srooterctl codemap .               # same, using your saved key
# also: /codemap in a srooterctl session, Studio Knowledge Refresh CODEMAP.md

يتولى المولّد إدارة الأقسام الحتمية (البنية المعمارية، خريطة الوحدات، مناطق الخطر) ويصوغ الباقي مع مؤشرات ثقة لتقوم أنت بمراجعتها وتنقيحها. يتحكم الخيار --check في عمليات الكتابة ويعمل عند بدء الجلسة، مما يضمن رصد أي خريطة قديمة أو معطوبة وعدم الوثوق بها بصمت أبداً. راجع ADR-067.

المهارات

تدمج المهارات ممارساتك الهندسية في النموذج، حسب الغرض. يأتي Palgu مزوداً بأربع مهارات افتراضية:

التوجيه المدرك للمهارات: للمهام التي تُنفَّذ من مرة واحدة مثل العروض التقديمية أو لوحات المعلومات أو صفحات الهبوط أو المستندات المتقنة، يمكن للتوجيه إضافة مهارة مطابقة وترقية النموذج لهذا الطلب تحديداً. حدد مهاراتك الخاصة على مستوى المؤسسة (الاسم، التوجيه، المقاصد، الإلزام المرن أو الصارم، الأولوية) في قسم المعايير والمهارات، ومهاراتك الشخصية المبنية فوق سياسة المؤسسة دون تجاوز الحوكمة أبداً في قسم مهاراتي.

ذاكرة الجلسة

Mnemos هي الذاكرة العاملة في Palgu لكل جلسة برمجة. بالنسبة لحركة البيانات بصيغة Anthropic، تسجّل الطلب الافتتاحي للجلسة، والملفات التي عدّلتها أو كتبتها، وأخطاء الأدوات، وتنشئ لها نقاط حفظ كلما طالت الجلسة. وهي اليوم سجلّ متاح لك لفحصه، ولا يُعاد إدراج محتواها في طلبات وكلائك.

افحصها في لوحة التحكم لديك ضمن Sessions → Memory: الجلسات مع أحدث نقطة حفظ لها (الهدف، والقيود النشطة، ودرجة الإجهاد) والعُقد المصنّفة (Goal · Constraint · Error · Decision · Result).

مراجعات المخاطر

ترصد مراجعات المخاطر التغييرات التي تمس الجوانب الحساسة: المصادقة، ونطاق المستأجرين (tenant scoping)، والأسرار. يقيّم نموذج حراسة سريع كل تغيير بشكل مستقل عن المسار الرئيسي؛ وعندما تكون النتيجة مرتفعة، يفحص نموذج مراجعة متقدم (claude-opus) النهج المتبع ويضيف توجيهات تصحيحية إلى الدور التالي للوكيل. لا تعيق مراجعات المخاطر عمل المطور.

راجع الأحداث في لوحة التحكم ضمن قسم Risk: يعرض كل حدث مستوى الخطورة، والنتائج (الأبعاد التي تفعّلت مع الأدلة)، والتوجيهات التصحيحية، وأزراراً لتحديد النتيجة (مؤكد / حادثة / مستبعد / بسيط) ليتكيف الحد الفاصل مع قاعدة الكود الخاصة بك.