تفضل ترجمة الـ HTML إلى العربية:
يواجه معظم المطورين الذين يديرون العديد من وكلاء الذكاء الاصطناعي نفس العقبة عند الوكيل رقم خمسة. لديك Claude Code في نافذة طرفية واحدة تعيد كتابة خدمة خلفية، وCodex في أخرى يولد الاختبارات، وCursor يقوم بتحرير مكون، وثلاث علامات تبويب أخرى نسيت التحقق منها. لا أحد يعرف ما يفعله الآخر. تتصاعد التكاليف. يتكرر نفس العمل بواسطة وكيلين. يعمل أحدهما لمدة ست ساعات ولا ينتج أي شيء مفيد لأن أحداً لم يمنحه هدفاً واضحاً.
Paperclip يصلح هذا. إنه منصة تنسيق مفتوحة المصدر تحول وكلاء الذكاء الاصطناعي المتناثرين لديك إلى شركة منظمة، مكتملة بخرائط تنظيمية، أدوار محددة، إدارة مهام، حدود ميزانية، وسجلات تدقيق. حقق أكثر من 35,000 نجمة على GitHub في أقل من ثلاثة أسابيع، وهذا يخبرك كم عدد المطورين الذين كانوا يعانون من نفس الإحباط.
يوضح لك هذا المقال كيفية إعدادها، وهيكلة أول شركة وكلاء لك، وتشغيلها بحيث يتم إنجاز العمل بالفعل دون الحاجة إلى مراقبة كل نافذة طرفية.
ما هو Paperclip (وما ليس هو)
قبل أن تبدأ في التثبيت، يجب أن تفهم بالضبط وظيفة Paperclip وكيف يمكن دمجه في سير عملك.
Paperclip هو طبقة تنسيق للوكلاء. يقوم بتنظيمهم، تتبع أعمالهم، التحكم في ميزانياتهم، وتوفير السياق حول أهداف الشركة. لا يقوم Paperclip ببناء الوكلاء بنفسه، ولا يحل محل مزود الذكاء الاصطناعي، ولا يضيف واجهة دردشة.
- الوكلاء لديهم أدوار واضحة، وليس فقط أوامر (prompts)
- المهام لها مالكون محددون
- الميزانيات لها حدود صارمة
- كل شيء مسجل في سجلات تدقيق
يدعم Paperclip Claude Code، OpenAI Codex، Cursor، Gemini CLI، وأي وكيل يدعم webhook أو heartbeat. أنت من يضيف الوكلاء، وPaperclip يدير الشركة.
Paperclip ليس:
- واجهة دردشة
- منشئ سير عمل بالسحب والإفلات مثل n8n أو Zapier
- إطار عمل لكتابة الوكلاء
- مناسب لحالات الاستخدام الفردية
إذا كنت تستخدم وكيلًا واحدًا فقط من حين لآخر، Paperclip ليس لك. إذا كنت تدير عدة وكلاء بشكل متواصل، فهو أداة أساسية.
تثبيت Paperclip
المتطلبات: Node.js 20+ و pnpm 9.15+ فقط. لا تحتاج إلى إعداد قاعدة بيانات خارجية، فـ Paperclip يأتي مع PostgreSQL مدمجة.
الخطوات السريعة للبدء:
npx paperclipai onboard --yes
سيقوم ذلك بتنزيل CLI، تشغيل إعدادات افتراضية، وتشغيل الخادم على المنفذ 3100. افتح http://127.0.0.1:3100 للوصول إلى لوحة التحكم.
للعمل مع الكود أو المساهمة:
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
باستخدام Docker:
docker compose -f docker-compose.quickstart.yml up --build
أماكن تخزين الملفات:
~/.paperclip/instances/default/
config.json — إعدادات الخادم والتخزين
db/ — ملفات بيانات PostgreSQL
secrets/master.key — مفتاح التشفير
logs/ — سجلات الخادم
data/storage/ — مرفقات الملفات
workspaces/<agent>/ — مجلد عمل لكل وكيل
في الوضع المحلي، يستخدم Paperclip مصادقة local_trusted، فتتمكن من استخدام لوحة التحكم فورًا بدون تسجيل حساب.
للتحقق من الصحة:
paperclipai doctor
لإصلاح أي مشاكل تلقائيًا:
paperclipai doctor --repair
إعداد شركتك الأولى
"الشركة" هي الحاوية الرئيسية للوكلاء والمهام والأهداف والميزانيات. أنشئ شركة جديدة من لوحة التحكم، وأضف بيان مهمة واضح. سيكون هذا البيان مرجعًا لكل مهمة ومصدرًا للسياق لوكلائك.
مثال لبيان مهمة:
"بناء وصيانة واجهة برمجة تطبيقات REST لإدارة طلبات العملاء. إعطاء الأولوية للصحة على السرعة. توثيق كل نقطة نهاية عامة."
إضافة وكلائك الأوائل
كل وكيل في Paperclip يحتاج محول (adapter) يحدد أداة الذكاء الاصطناعي وطريقة الاتصال.
| الوكيل | نوع المحول | الحزمة |
|---|---|---|
| Claude Code | claude_local |
@paperclipai/adapter-claude-local |
| OpenAI Codex | codex_local |
@paperclipai/adapter-codex-local |
| Gemini CLI | gemini_local |
@paperclipai/adapter-gemini-local |
| Cursor | cursor |
@paperclipai/adapter-cursor-local |
| HTTP webhooks | محول HTTP | نقطة نهاية مخصصة |
لإضافة وكيل Claude Code عبر CLI:
paperclipai agent local-cli "Backend Engineer" --company-id <your-company-id>
سيتم تهيئة الوكيل وتثبيت مهاراته في ~/.claude/skills وتوليد بيانات اعتماد API. الآن الوكيل جزء من الشركة ويمكنك تعيين مهام له.
تهيئة وكيل Claude (يمكنك ضبطها في لوحة التحكم أو في ملف تهيئة الوكيل):
| الحقل | ما يفعله |
|---|---|
model |
أي نموذج Claude سيتم استخدامه (مثال: claude-sonnet-4-6) |
cwd |
دليل العمل للوكيل (يتم إنشاؤه تلقائيًا إذا كان مفقودًا) |
promptTemplate |
مطالبة النظام مع استبدال {{variable}}
|
maxTurnsPerRun |
عدد الدورات الأقصى لكل نبضة (افتراضي: 300) |
timeoutSec |
حد أقصى لمدة التنفيذ (0 = بدون مهلة) |
تخصيص النموذج حسب الدور: شغل Opus لكل وكيل مكلف جدًا. استخدم Sonnet للأدوار الاستراتيجية/الإدارية، وHaiku للتوجيه أو المهام الروتينية. مثال عملي:
- الرئيس التنفيذي / أدوار التنسيق: Sonnet
- المديرون: Haiku
- المهندسون المبدعون: Sonnet
- المهام الروتينية: Haiku
هذا التوزيع يقلل التكلفة الشهرية بنسبة 40-60% دون التأثير على جودة المهام الروتينية.
هيكلة منظمة وكلائك
مثال هيكلة لمشروع برمجي صغير:
الرئيس التنفيذي (CEO) (Sonnet)
├── المدير التقني (CTO) (Haiku)
│ ├── مهندس الواجهة الخلفية (Backend Engineer) (Sonnet)
│ ├── مهندس الواجهة الأمامية (Frontend Engineer) (Sonnet)
│ └── مهندس ضمان الجودة (QA Engineer) (Haiku)
└── الكاتب التقني (Technical Writer) (Haiku)
الرئيس التنفيذي يقسم المهمة إلى أهداف، المدير التقني يوزعها، المهندسون ينفذون، QA يراجع، والكاتب يوثق.
كل وكيل لديه فترة نبض (heartbeat interval) تحدد متى يستيقظ الوكيل للتحقق من المهام وتنفيذها. هذا يمنع استهلاك الموارد غير الضرورية.
توصيات الفترات:
- وكلاء البرمجة: 10 دقائق (600 ثانية)
- وكلاء عند الطلب: مرة يوميًا (86,400 ثانية) مع إمكانية الاستيقاظ عند الطلب
- الحد الأدنى: 30 ثانية (أقل من ذلك يزيد المخاطر والتكلفة)
كيف تعمل نبضة القلب (Heartbeat)
كل نبضة قلب تمر بخطوات محددة:
- تأكيد الهوية عبر
GET /api/agents/me - معالجة الردود المعلقة
- جلب المهام من
GET /api/companies/{companyId}/issues - تحديد الأولوية: مهام قيد التقدم أولاً، ثم المخطط لها، وتخطي المحظورة
- سحب المهمة عبر
POST /api/issues/{issueId}/checkout - قراءة سياق المهمة والتعليقات
- تنفيذ العمل
- تحديث الحالة والتعليقات
- تفويض مهام فرعية إذا لزم الأمر
آلية السحب تمنع تكرار العمل بين الوكلاء. يتم تمرير السياق للوكلاء عبر متغيرات البيئة:
PAPERCLIP_TASK_ID # رقم المهمة
PAPERCLIP_WAKE_REASON # سبب الاستيقاظ (مؤقت، إشارة، تعيين)
PAPERCLIP_AGENT_ID # هوية الوكيل
PAPERCLIP_API_URL # رابط API
يمكن للوكلاء تحديث الحالة، إنشاء مهام فرعية، طلب موافقات، والتفويض في نفس نبضة القلب.
تعيين المهام وتتبع العمل
أنشئ مهمة من CLI أو لوحة التحكم:
paperclipai issue create \
--company-id <id> \
--title "Add pagination to the orders endpoint" \
--assignee-agent-id <backend-engineer-id>
المهام تدعم:
- مهام رئيسية وفرعية
- روابط للأهداف
- تعليقات وسياق وطلبات الموافقة
- إشارات @ لإيقاظ وكيل معين فورًا
لعرض المهام المفتوحة:
paperclipai issue list
التحكم في الميزانية الذي يعمل فعليًا
لكل وكيل ميزانية شهرية. عند 80% من الاستهلاك، يركز على المهام الحرجة فقط. عند 100% يتوقف تمامًا.
يمكنك تعيين الميزانية من تهيئة الوكيل (20-50 دولار/شهر كبداية). تتبع الاستهلاك وتكلفة كل نبضة من لوحة التحكم. إذا لاحظت تصاعد التكلفة، راجع وضوح المهام أولاً.
Paperclip يوقف الاستهلاك المفرط تلقائيًا.
مهارات وقت التشغيل: تعليم الوكلاء سير عمل جديد دون إعادة تدريب
Paperclip يدعم حقن المهارات عبر ملفات SKILL.md في مجلد المهارات لكل وكيل. عند تنفيذ النبضة، يقرأ الوكيل هذه الملفات ويلتزم بها دون الحاجة لإعادة تدريبه.
# SKILL: Database migrations When creating a migration: 1. Never modify existing migration files 2. Use descriptive names: YYYYMMDD_description.sql 3. Include both up and down SQL 4. Test locally before committing 5. Add a comment explaining the business reason for the change
ضع الملف في مجلد المهارات الخاص بالوكيل المعني وستطبق القواعد تلقائيًا في كل نبضة قلب قادمة.
إذا كنت تختبر واجهات برمجة التطبيقات (APIs) التي أنشأها وكلاؤك
عند بناء واجهات برمجة التطبيقات (APIs) بواسطة الوكلاء، تحتاج إلى اختبارها بسرعة. Apidog يوفر لك منصة واحدة لتصميم واختبار APIs، مع دعم الموك، والاختبارات الآلية، واختبار المخرجات مباشرة بعد كل تحديث.
يمكنك إنشاء مجموعات اختبار تلقائيًا من مواصفات OpenAPI، تشغيلها على نتائج الوكيل، وإرجاع النتائج كتعليق مهمة. الوكيل يلتقط ذلك في النبضة التالية ويقوم بالإصلاحات المطلوبة. حلقة مغلقة من الكود إلى الاختبار إلى التصحيح بدون تدخل بشري.
يدعم Apidog REST وGraphQL وgRPC، ومجاني للبدء.
إدارة عدة مثيلات
Paperclip يدعم تشغيل مثيلات متعددة معزولة على نفس الجهاز عبر متغير PAPERCLIP_INSTANCE_ID أو --instance لكل أمر. لكل مثيل إعداداته وقاعدة بياناته ومساحة عمله المنفصلة.
لإنشاء مثيل تطوير جديد لكل فرع git:
paperclipai worktree:make feature/orders-pagination
سيتم عزل المنافذ، التهيئة، وقاعدة البيانات لكل فرع. عند الانتهاء يمكنك حذف المثيل بسهولة.
إعدادات وكلاء متعددين فعالة
- تسلسل الأهداف: ابدأ بهدف رئيسي، ثم دع الوكلاء يقسمونه إلى أهداف ومهام فرعية.
- بوابات الموافقة: لأي إجراء حساس، أضف بوابة موافقة يدوية.
- الاستيقاظ عند الطلب: استخدم الإشارة @ في التعليقات لإيقاظ الوكلاء فورًا بدلًا من تقليل فاصل النبض.
- مساحات عمل معزولة: استخدم مجلد عمل منفصل لكل وكيل لتجنب تداخل الأعمال.
البدء يستغرق حوالي 15 دقيقة
الإعداد الأولي يستغرق أقل من 15 دقيقة: أمر واحد لتثبيت الخادم، خمس دقائق لإضافة أول وكيل وإنشاء أول مهمة. أكبر فارق في النتائج يأتي من هيكلة الشركة، اختيار النموذج المناسب لكل دور، وتحديد ميزانيات واضحة. استثمر 30 دقيقة في التخطيط وستحصل على إنتاجية واستدامة أعلى بكثير.
إذا كنت تدير أكثر من وكيلين ذكاء اصطناعي في مشروع مستمر، Paperclip يستحق أن تخصص له فترة بعد الظهر للتهيئة. الفرق بين فوضى النوافذ الطرفية وهيكل مؤسسي واضح مع تحكم في الميزانية وسجلات تدقيق هو الفرق بين مشروع جانبي ونظام يمكنه العمل فعليًا بدون إشراف دائم.
