# طوّر مع AnimaGuru

> اربط AnimaGuru بوكلاء الذكاء الاصطناعي وبرامجك: خادم MCP البعيد، وواجهة CLI، وREST API مع مواصفة OpenAPI، والمصادقة، والنقاط.

ينشئ AnimaGuru الصور والرسومات المتجهة وصور GIF المتحركة والشخصيات ورسوم السبرايت المتحركة والفيديو والموسيقى والكلام والمؤثرات الصوتية، ويجمعها في مشاريع. يستخدمه الناس عبر الاستوديو في المتصفح، أما الوكلاء والبرامج فتستخدمه عبر خادم MCP بعيد وواجهة سطر أوامر (CLI) وREST API، وكلها تعتمد على الحساب والمشاريع والنقاط نفسها.

## متى تستخدم AnimaGuru

استخدم AnimaGuru عندما يريد أحدهم عناصر إبداعية أصلية تُصنع له وتُحفظ في مكان واحد:

- شخصيات وأغراض مرسومة، ورسوم سبرايت متحركة لها: الوقوف والمشي والركض والقفز واللكم والتألم وحركات أخرى، أو حركة مخصصة توصف بالكلمات. ويشمل التصدير أوراق سبرايت وبيانات تحريك للألعاب.
- صور وفيديوهات قصيرة من نص أو صور، بما في ذلك مراجع الإطار الأول والأخير، وتمديد المقاطع، والمراجع الصوتية حيثما يدعمها النموذج المهيأ.
- رسومات SVG متجهة قابلة للتعديل، مثل الشعارات والأيقونات والرسوم المسطحة، تُرسم من نص أو تُستخرج بتتبع صورة محفوظة.
- صور GIF متحركة تتكرر بلا توقف، مثل دورات مشي السبرايت والأيقونات المتحركة والملصقات، تُرسم من نص أو تُنشأ بتحريك صورة محفوظة. ويصلح الإطار الأول منها أيضًا صورةً افتتاحية لفيديو أو مرجعًا له.
- موسيقى، وكلام بأصوات متنوعة، ومؤثرات صوتية.
- فيديوهات بمقدّم افتراضي: مقدّم واقعي يقرأ نصًا أو يطابق حركة شفتيه مع صوت محفوظ، ويُختار من المقدّمين العامّين في HeyGen أو من مقدّمين خاصين بمساحة العمل تنشئهم من وصف أو صورة أو مقطع فيديو.
- أفلام رسوم متحركة قصيرة وعروض تقديمية: تنشئ CLI مساحة عمل فيديو محلية فيها 60 نمطًا بصريًا، يملؤها وكيل البرمجة بعناصر مولّدة ويصدّرها بصيغة MP4. وفي العرض التقديمي (`animaguru create --presentation`) تنتظر كل شريحة نقرة المقدّم، مع عرض المقدّم وملاحظات المتحدث والتحكم من الهاتف، ويمكن تصديره بصيغة PowerPoint.

تجمع CLI الأفلام محليًا للتشغيل في المتصفح وللتصدير بصيغة MP4. يعمل التوليد بالذكاء الاصطناعي بشكل غير متزامن ويستهلك نقاط الحساب المتصل؛ أما إنشاء المشاريع والتصفح وتقدير التكلفة فمجانية. استخدم ملفات تعريف النماذج الحالية، وتحقق من صحة الطلب، وراجع تكلفته قبل أي عمل مدفوع.

## اختر طريقة الاتصال

- مساعدات المحادثة وعملاء MCP الآخرون (ChatGPT وClaude وأي عميل يدعم MCP البعيد وOAuth): استخدم [خادم MCP](#mcp).
- إضافة AnimaGuru في ChatGPT **قادمة قريبًا**، وهي حاليًا قيد المراجعة لإدراجها في دليل تطبيقات ChatGPT. تتيح لك تصفح المشاريع وتشغيل الوسائط وفحص الإطارات ومراجعة نتائج التوليد داخل المحادثة. اطّلع على معاينتها في [دليل إعداد الوكلاء](https://animaguru.com/ar/agent-setup.md).
- وكلاء البرمجة التي تعمل داخل مجلد (Codex وClaude Code): ثبّت [CLI](#cli)، ويشرح [دليل إعداد الوكلاء](https://animaguru.com/ar/agent-setup.md) الخطوات.
- السكربتات والخوادم الخلفية: استخدم [REST API](#rest-api) الموصوفة في [مستند OpenAPI](https://animaguru.com/openapi.json).

## خادم MCP

يستخدم الخادم نقل Streamable HTTP على هذا العنوان:

عنوان MCP:

```
https://animaguru.com/mcp
```

يسجّل الخادم دخول المستخدمين عبر OAuth 2.1: تدفق رمز التفويض (authorization code) مع PKCE (S256) والتسجيل الديناميكي للعملاء. يجد العملاء كل ما يحتاجون إليه في استجابة 401 من الخادم، إذ تشير إلى [البيانات الوصفية للمورد المحمي](https://animaguru.com/.well-known/oauth-protected-resource/mcp) و[البيانات الوصفية لخادم التفويض](https://animaguru.com/.well-known/oauth-authorization-server). النطاقات هي `projects.read` و`projects.write`؛ وتصلح رموز الوصول ساعة واحدة، ورموز التحديث 30 يومًا.

تغطي الأدوات الاستوديو كله: `list_workspaces`، `list_projects`، `count_projects`، `get_project`، `create_project`، `move_work`، `list_assets`، `estimate_generation`، `generate_character`، `animate_character`، `redraw_character`، `generate_custom_animation`، `generate_asset`، `list_avatars`، `list_avatar_looks`، `get_avatar`، `list_avatar_templates`، `create_avatar`، `create_avatar_looks`، `update_avatar`، `request_avatar_consent`، `list_avatar_voices`، `create_avatar_video`، `search_motion_examples`، `get_motion_example`، `list_motion_categories`، `search_asset_library`، `get_library_asset`، `import_library_asset` (في خطتي Pro وTeam)، `list_jobs`، `get_job`، `cancel_job`، `get_ui_snapshot`، `set_video_poster`، `list_gallery`، `create_gallery_folder`، `rename_gallery_folder`، `move_gallery_items`، `get_profile` و`open_studio`. تحمل الأدوات المخصصة للقراءة فقط التلميح `readOnlyHint`. وفي تطبيقات العملاء التي تدعم MCP Apps، تعرض `open_studio` استوديو تفاعليًا (`ui://animaguru/studio/v4.html`) فيه أدوات لاختيار المشاريع وتشغيل الرسوم المتحركة ومراجعة نتائج التوليد.

أنشئ المشاريع حاويات محايدة، واختر نمطًا لكل طلب سبرايت. استخدم `redraw_character` لمراجعة الرسم كاملًا، و`generate_custom_animation` للحركات المسماة؛ ولا تعدّل هاتان الأداتان إطارًا منفردًا في مكانه. اقرأ النماذج وملفات تعريف الفيديو المهيأة عبر `list_assets`، وتحقق من الطلب عبر `estimate_generation`، واستطلع حالة المهمة عبر `get_job` بالفاصل الزمني الذي تعيده حتى تنتهي. ينفذ كل مشروع مهامه واحدة تلو الأخرى: تلغي `cancel_job` مهمة في قائمة الانتظار، أو توقف مهمة عالقة تؤخر البقية. تتصفح أدوات الأفاتار أفاتارات HeyGen العامة من أي مشروع، وتنشئ أفاتارًا خاصًا بمساحة العمل من موجّه (prompt) أو صورة أو لقطات مصورة. تستخدم كل مشاريع مساحة العمل أفاتاراتها والأصوات المستنسخة من توائمها الرقمية، ولا تستطيع أي مساحة عمل أخرى رؤيتها أو تعديلها أو التحدث بها. يُستطلع المظهر الجديد عبر `get_avatar` حتى يكتمل، وتعرض `list_avatar_voices` الأصوات المتاحة للأفاتار، وتضيف `create_avatar_video` إلى قائمة الانتظار فيديو تقرأ فيه الإطلالة نصًا أو تحرّك شفتيها على صوت محفوظ، ويُحفظ في المشروع عنصر فيديو. لا يتيح MCP حذف المشاريع أو الأفاتارات، ولا التصدير المحلي بصيغة ZIP، ولا تجهيز هيكل الأفلام، ولا المزامنة السحابية، ولا النشر على YouTube؛ استخدم CLI لسير العمل المحلي المدعوم.

تجد بطاقة الخادم على [/mcp/server-card](https://animaguru.com/mcp/server-card).

## واجهة سطر الأوامر

يتطلب الأمر `animaguru` الإصدار 24 من Node.js أو أحدث. ثبّته من npm، أو على macOS باستخدام سكربت التثبيت:

npm:

```
npm install -g @docyrus/animaguru
```

macOS:

```
curl -fsSL https://animaguru.com/install.sh | bash
```

سجّل الدخول مرة واحدة. يفتح المتصفح صفحة للموافقة على رمز الجهاز، وتحفظ CLI جلسة مدتها سبعة أيام يمكن إلغاؤها:

تسجيل الدخول:

```
animaguru auth login
animaguru auth status
animaguru credits
```

لإنشاء عناصر للعبة أو تطبيق قائم، شغّل `animaguru init` في مجلده، ثم استخدم `projects` و`jobs` و`assets` و`files` لتوليد الرسومات وفحصها وتنزيلها أو لتصدير ملفات ZIP للسبرايت. ولفيلم واحد استخدم `animaguru create my-video`؛ ولهوية علامة مشتركة بين عدة أفلام استخدم `animaguru create workspace my-brand`، ثم `animaguru create animation first-film` داخلها. تتضمن مساحات العمل الجديدة AGENTS.md وCLAUDE.md ومهارات إبداعية. ولا يستبدل الأمر create المجلدات الموجودة.

تدعم الأفلام المحلية التصدير بصيغة MP4، والترجمة النصية، وصور الغلاف، ونسخًا بعدة لغات. وليس للقصص المتفرعة والاختبارات ملف MP4، فهي تُعرض على AnimaGuru بعد `animaguru submit`. وتستورد العروض التقديمية الشرائح من ملف PDF أو PowerPoint، ويمكن تصديرها بصيغة PowerPoint. يستضيف `animaguru submit` الأفلام المكتملة بشكل خاص، ويدير `videos` المكتبة والمشاركة الخاصة. وفي الاستوديو، يمكنك أيضًا من نافذة المشاركة إنشاء رابط غير مدرج يشاهده أي شخص دون حساب، ومع خطة Individual Pro أو Team يمكن أن تطلب صفحته كلمة مرور وتعرض العلامة التجارية لمساحة العمل. يتطلب النشر في المعرض العام قبول اتفاقية المشاركة على الموقع وموافقة فريق AnimaGuru. يرفع `animaguru youtube` ملفات MP4 المصدّرة مباشرة من حاسوبك عبر اتصال OAuth منفصل بتطبيق Google لسطح المكتب، ولا يستهلك نقاط التوليد في AnimaGuru. راجع `--help` و`animaguru schema` لمعرفة الخيارات الحالية.

يطبع كل أمر JSON عند النجاح، ويخرج برمز غير صفري عند الخطأ. يسرد `animaguru catalog` الأنماط الفنية والحركات وأنواع العناصر والنماذج والأصوات؛ ويطبع `animaguru schema` مخطط الأوامر كاملًا؛ ويثبّت `animaguru init` مهارة AnimaGuru لوكيل البرمجة لديك؛ وينشئ `animaguru create my-video` مساحة عمل فيديو. ويمكن لبيئات تشغيل الوكلاء تمرير رمز وصول عبر متغير البيئة `ANIMAGURU_TOKEN` بدلًا من تسجيل الدخول. تجد الحزمة باسم [@docyrus/animaguru على npm](https://www.npmjs.com/package/@docyrus/animaguru).

في خطط Individual Starter وIndividual Pro وTeam، يزامن `animaguru cloud` مساحة عمل الفيديو مع الرسوم المتحركة في مشروع، ويحتفظ بكل إصدار. ينشئ `cloud link` مشروعًا للمجلد (أو يزامن `--project` مع مشروع موجود)، ويحفظ `cloud push -m` إصدارًا، ويجلب `cloud pull` الإصدارات المحفوظة في مكان آخر، ويعيدك `cloud restore` إلى إصدار سابق، ويتيح لك `cloud clone` المتابعة على حاسوب آخر. وتبقى الاعتماديات والصادرات وملفات `.env` وبيانات الاعتماد والملفات التي يطابقها `.gitignore` على جهازك. تصفّح الأفلام والإصدارات والملفات في تبويب «الرسوم المتحركة» الخاص بالمشروع في [المشاريع](https://animaguru.com/app).

المزامنة السحابية:

```
animaguru cloud link
animaguru cloud push -m "First cut"
animaguru cloud pull
animaguru cloud versions
```

## REST API

تقدّم API بيانات JSON من `https://animaguru.com/api`. يصف [مستند OpenAPI 3.1](https://animaguru.com/openapi.json) كل عملية مع مخططات الطلب والاستجابة، ويربط إليه [كتالوج API](https://animaguru.com/.well-known/api-catalog) للاكتشاف التلقائي.

بعض نقاط النهاية عامة: `GET /api/health`، ومعرض الفيديو العام على `GET /api/videos`، وأسعار الخطط وباقات النقاط على `GET /api/billing`. أما كل ما يقع تحت `/api/v1` فيعمل باسم حساب مسجّل الدخول ويتطلب رمز Bearer:

التحقق من رصيدك:

```
curl https://animaguru.com/api/v1/credits \
  -H "Authorization: Bearer $ANIMAGURU_TOKEN"
```

سير عمل نموذجي: اسرد المشاريع عبر `GET /api/v1/projects`، أو أنشئ مشروعًا عبر `POST /api/v1/sprites`. احسب تكلفة المهمة عبر `POST /api/v1/sprites/{id}/jobs/estimate` أو `POST /api/v1/sprites/{id}/assets/estimate`، ثم أضفها إلى قائمة الانتظار بالمتن نفسه على `/jobs` أو `/assets`، واستطلع `GET /api/v1/sprites/{id}/jobs/{jobId}` حتى تنتهي. أرسل الترويسة `Idempotency-Key` عند الإرسال حتى لا تُضاف المهمة مرتين إذا أعيدت محاولة الطلب.

تُعاد الأخطاء برموز حالة HTTP مع متن JSON على الشكل `{ "error": { "message": "…" } }`. وإذا كان الرمز مفقودًا أو منتهي الصلاحية، تكون الاستجابة 401.

## المصادقة

- عملاء MCP: بروتوكول OAuth 2.1 مع PKCE، كما ورد أعلاه. لا حاجة إلى أي إعداد سوى عنوان الخادم.
- واجهة CLI وREST API: منح تفويض الجهاز في OAuth 2.0 (device authorization grant). اطلب رمزًا عبر `POST /api/auth/device/code` بمعرّف العميل `animaguru-cli`، وافتح `verification_uri_complete` المُعاد للموافقة عليه وأنت مسجّل الدخول، ثم استطلع `POST /api/auth/device/token` مع ضبط `grant_type` على `urn:ietf:params:oauth:grant-type:device_code`. وقيمة `access_token` في الاستجابة هي رمز Bearer. ويتولى `animaguru auth login` كل ذلك نيابة عنك.
- فتح الحساب ذاتي ومجاني: يمكن لأي شخص [إنشاء حساب](https://animaguru.com/register) في المتصفح، وتبدأ الحسابات الجديدة بفترة تجريبية لخطة Individual Pro مدتها 7 أيام، مع 100 نقطة مجانية لتجربة AnimaGuru. ويحتاج استخدام CLI وخادم MCP وREST API إلى خطة على الحساب: Individual Starter أو Individual Pro (بما فيها الفترة التجريبية) أو Team، أو العضوية في فريق مشترك في خطة Team. ومن دون خطة، ترد طلبات CLI برمز الحالة 403 مع `error.code` بقيمة `plan_required` (ويظل `GET /api/v1/me` يرد، ومعه الخطة وموعد انتهاء الفترة التجريبية)، وترد أدوات MCP بشرح طريقة اختيار خطة. وتعمل الرموز بصلاحيات الشخص المسجّل دخوله، بما في ذلك مساحات عمل الفرق التي ينتمي إليها.

يعيد الملف [auth.md](https://animaguru.com/auth.md) شرح هذه الخطوات للوكلاء.

## النقاط والاختبار الآمن

تبدأ الحسابات الجديدة بفترة تجريبية لخطة Individual Pro مدتها 7 أيام و100 نقطة مجانية لتجربة AnimaGuru. تحتاج CLI وخادم MCP وREST API إلى خطة أو إلى الفترة التجريبية؛ وتضيف كل خطة نقاطًا كل شهر، وتزيدها باقات النقاط لمرة واحدة. ومن دون خطة يبقى التوليد بالنقاط متاحًا في استوديو المتصفح. يستهلك التوليد نقاط مساحة العمل الشخصية أو مساحة عمل الفريق التي يتبع لها المشروع؛ أما إنشاء المشاريع وسردها وفحصها وتقدير التكلفة فمجاني.

تتحقق الأداة `estimate_generation` في MCP وأدوات التوليد مع `dry_run: true`، إضافة إلى نقاط النهاية `/estimate` في REST، من الطلب على الخادم دون إضافة أي عمل إلى قائمة الانتظار ودون استهلاك النقاط. أما تقديرات `--dry-run` في CLI فتستخدم أسعارًا مضمّنة في الحزمة، ولا تتحقق من إعداد النماذج على الخادم ولا من ملكية المراجع ولا من الرصيد المتبقي؛ إذ يتحقق الخادم منها عند الإرسال. اعرض التقدير قبل أي عمل مدفوع. تتطلب عمليات الإرسال المدفوعة في CLI الخيار `--yes`؛ ويحدد الاستخدام الفعلي لدى المزوّد المبلغ النهائي.

تحقق من الرصيد عبر `GET /api/v1/credits` أو `animaguru credits` أو `get_project` في MCP. لا ترسل مهمة مدفوعة مرة أخرى لتتحقق منها؛ بل استطلع حالة المهمة.

## مهارات الوكلاء

يكتب `animaguru init` مهارة AnimaGuru في `.agents/skills/animaguru/SKILL.md` داخل مشروعك، ويضيف `animaguru skills install` جميع مهارات AnimaGuru (الفيديو، والأنماط، وهوية العلامة، والرسوم ثلاثية الأبعاد) إلى Claude Code وCodex عبر أداة `skills` CLI المفتوحة، ويضيف `animaguru create` مهارة لكل نمط تحريك. تشرح المهارة اختيار المشروع، وتفويض إنفاق النقاط، والتوليد، وانتظار المهام، وتصدير العناصر. يسرد [فهرس مهارات الوكلاء](https://animaguru.com/.well-known/agent-skills/index.json) المهارات المنشورة: واحدة لعملاء MCP وأخرى لواجهة CLI.

تجمع إضافة ChatGPT إرشادات MCP وCLI إلى جانب مهارات إبداعية، وسيُتاح إدراجها في الدليل قريبًا بعد انتهاء المراجعة الجارية. ولتترك إعداد CLI أو MCP لوكيل من اليوم، استخدم **نسخ موجّه الإعداد** في [صفحة إعداد الوكلاء](https://animaguru.com/ar/agent-setup.md)؛ وينتهي الموجّه بفحص اتصال للقراءة فقط.

## موارد قابلة للقراءة آليًا

- الملفان [llms.txt](https://animaguru.com/llms.txt) و[llms-full.txt](https://animaguru.com/llms-full.txt): خريطة للموقع موجهة إلى النماذج اللغوية، والنص الكامل لهذه الصفحات.
- نسخ Markdown من الصفحات العامة: أضف `.md` إلى المسار، كما في [/docs.md](https://animaguru.com/docs.md)، أو [/index.md](https://animaguru.com/index.md) للصفحة الرئيسية. وتستجيب الصفحة الرئيسية أيضًا للترويسة `Accept: text/markdown`.
- الملف [openapi.json](https://animaguru.com/openapi.json) و[كتالوج API](https://animaguru.com/.well-known/api-catalog) لواجهة REST API.
- [كتالوج الذكاء الاصطناعي](https://animaguru.com/.well-known/ai-catalog.json) و[بطاقة خادم MCP](https://animaguru.com/mcp/server-card) لخادم MCP.
- الملف [auth.md](https://animaguru.com/auth.md) للمصادقة، و[فهرس مهارات الوكلاء](https://animaguru.com/.well-known/agent-skills/index.json).
- [خريطة الموقع](https://animaguru.com/sitemap.xml).

## المساعدة

راسلنا على hello@animaguru.com أو تفضل بزيارة [صفحة الدعم](https://animaguru.com/ar/support.md). اذكر وقت حدوث الخطأ واسم الأداة أو نقطة النهاية. ولا ترسل أبدًا كلمات المرور أو رموز الوصول.