الانتقال إلى المحتوى الرئيسي
تم تصميم Youka ليُدار بواسطة الوكلاء. كل أمر في CLI يعيد ظرف JSON قابلًا للقراءة آليًا، وكل عملية كتابة تدعم مفاتيح idempotency، كما تكشف API العامة السطح نفسه وبالدلالات نفسها. تجمع هذه الصفحة قواعد التشغيل التي يحتاجها مؤلف الوكيل قبل توصيل Youka ضمن سير عمل.

​
ابدأ

إذا كنت تُعد وكيلاً للمرة الأولى، ثبّت Youka CLI أولاً، ثم ثبّت مهارة Youka karaoke: 
npm install -g @youka/cli
npx skills add https://github.com/youka-io/skills --skill youka-karaoke
هذا يمنح الوكيل مهارة Youka جاهزة مدعومة بالـ CLI. بعد تثبيتها، استخدم أنماط سير العمل أدناه لإنشاء فيديوهات كاريوكي، وتخصيص النمط، وتصدير ملفات MP4 بأمان.

​
اطلب من وكيلك

بعد تثبيت CLI والمهارة، يمكنك إعطاء وكيلك مهمة مباشرة مثل هذه: 
استخدم Youka لإنشاء فيديو كاريوكي من /path/to/song.mp3. قم بتفريغ الكلمات بالإنجليزية، واستخدم نمط ترجمة كاريوكي نظيفًا، وصدّر الفيديو النهائي بدقة 1080p، واحفظه باسم ./karaoke.mp4.

​
قواعد التشغيل

استخدم --json دائمًا

على CLI، مرّر دائمًا --json. وفي API، اضبط دائمًا Accept: application/json. لا تقم أبدًا بتحليل مخرجات موجهة للبشر.

أرسل دائمًا مفتاح idempotency

يجب أن تحمل كل عملية كتابة مفتاح idempotency ثابتًا حتى تعيد المحاولات بعد انتهاء المهلة النتيجة الأصلية بدلًا من تكرار العمل.

أعد قراءة الحالة الدائمة

لا تثق باستجابات التعديل القديمة. بعد مهمة نهائية، أعد قراءة المشروع أو التصدير للحصول على الحالة النهائية.

استطلع مع التراجع التدريجي

ابدأ بفاصل 2–3 ثوانٍ. زد الفاصل أُسّياً للوظائف الطويلة. احترم استجابات 429.

​
عقد المخرجات

كل أمر CLI في وضع --json يكتب ظرفًا واحدًا فقط إلى stdout. نجاح: 
{
  "schemaVersion": "1",
  "ok": true,
  "data": { "id": "prj_abc123", "title": "My Song" }
}
فشل: 
{
  "schemaVersion": "1",
  "ok": false,
  "error": {
    "code": "CONFLICT",
    "message": "A request with this Idempotency-Key is already in progress.",
    "retryable": true
  }
}
رموز الخروج:
CodeMeaningRetry?
0نجاح.N/A
1خطأ وقت التشغيل (شبكة، API، تصيير).تحقق من error.retryable.
2إدخال غير صالح (خيارات سيئة، حمولة غير قابلة للقراءة).لا — أصلح الإدخال.

​
سير عمل من البداية إلى النهاية

سير عمل الوكيل القياسي هو: إنشاء مشروع، الانتظار، التصدير، تنزيل النتيجة. إليك النمط الكامل مع تنفيذين لكل من CLI وSDK. 
# 1. إنشاء المشروع والانتظار حتى يكتمل فصل المسارات + مزامنة الكلمات
PROJECT_JSON=$(youka project create ./song.mp3 \
  --mode transcribe \
  --lang en \
  --wait \
  --idempotency-key "create-song-2026-04-08-001" \
  --json)

PROJECT_ID=$(echo "$PROJECT_JSON" | jq -r '.data.projectId')

# 2. بدء التصدير والانتظار
EXPORT_JSON=$(youka export create "$PROJECT_ID" \
  --resolution 1080p \
  --quality high \
  --wait \
  --download \
  --output ./karaoke.mp4 \
  --idempotency-key "export-$PROJECT_ID-v1" \
  --json)

echo "Done:" "$(echo "$EXPORT_JSON" | jq -r '.data.fileUrl')"

​
إرشادات الاستطلاع

تعيد معظم عمليات الكتابة مقابض عمليات في SDK. فضّل client.projects.wait(...) وclient.exports.wait(...)، ولا تنزل إلى client.tasks.* إلا عندما تحتاج صراحةً إلى وصول منخفض المستوى للمهام.
Job typeRecommended initial intervalMax wait
Project create (stems + lyrics sync)3 s15 min
Stem separation only3 s10 min
Lyrics sync only2 s5 min
Export render3 s30 min
على CLI، يتولى --wait الاستطلاع نيابةً عنك. على SDK، تستخدم دوال الانتظار المساعدة فاصلًا افتراضيًا قدره 2 s وتقبل pollIntervalMs.
احترم استجابات 429. عند حدود المعدّل، تراجع بما لا يقل عن ترويسة Retry-After (أو 30 s إذا كانت غير موجودة).

​
مفاتيح idempotency

كل عملية إنشاء وتحديث تدعم مفتاح idempotency. القواعد:
  • استخدم مفتاحًا ثابتًا وفريدًا وحتميًا لكل تعديل منطقي. جيد: create-song-${sourceHash}. سيئ: UUID جديد لكل إعادة محاولة.
  • أعد استخدام المفتاح نفسه عبر إعادة المحاولات. يتعرف الخادم على الإعادة ويعيد النتيجة الأصلية.
  • المفاتيح بنطاق كل حساب وتنتهي صلاحيتها بعد 24 ساعة.
  • إذا أعاد الخادم IDEMPOTENT_REPLAY_IN_PROGRESS (HTTP 202)، فالطلب الأصلي ما يزال يعمل. انتظر وأعد المحاولة بالمفتاح نفسه.
نمط مثال: 
const key = `create-${sha256(sourceBytes)}`;

try {
  return await client.projects.create(body, { idempotencyKey: key });
} catch (error) {
  if (error instanceof YoukaRequestError && error.retryable) {
    // آمن لإعادة المحاولة بالمفتاح نفسه
    return await client.projects.create(body, { idempotencyKey: key });
  }
  throw error;
}
راجع API idempotency للعقد الكامل.

​
استعادة الأخطاء

تفرّع بناءً على error.code وerror.retryable. الحالات الشائعة:
CodeCauseAction
INVALID_REQUESTفشل جسم الطلب في التحقق من مخطط البيانات.أصلح الحمولة. بلا إعادة محاولة.
UNAUTHORIZEDمفتاح API مفقود أو غير صالح.اعرضه على المستدعي. بلا إعادة محاولة.
NOT_FOUNDالمورد غير موجود أو لا تملك صلاحية الوصول.بلا إعادة محاولة.
CONFLICT (409)تعارض إصدار أو تصادم idempotency.أعد المحاولة باستخدام مفتاح idempotency نفسه.
TOO_MANY_REQUESTS (429)حد المعدّل.تراجع وفق Retry-After أو 30 s.
INTERNAL_SERVER_ERROR (500)فشل خادم عابر.أعد المحاولة حتى 3 مرات مع تراجع تدريجي.
IDEMPOTENT_REPLAY_IN_PROGRESS (202)طلب سابق ما يزال قيد التشغيل.انتظر وأعد المحاولة بالمفتاح نفسه.
TASK_FAILEDانتهت المهمة غير المتزامنة بفشل.اعرض error.task.error على المستدعي. بلا إعادة محاولة.
TASK_TIMED_OUTتجاوزت المهمة غير المتزامنة ميزانيتها.آمن لإعادة المحاولة مرة واحدة.

​
اكتشاف الحقول القابلة للتعديل

قبل تعديل presets، اجلب مخطط preset حتى يعرف النموذج الحقول الصالحة وأنواع القيم: 
# مخطط جسم preset
youka preset schema --json
بالنسبة لإعدادات المشروع، فضّل قراءة إعدادات المشروع الحالية أولاً، ثم إرسال جسم تحديث أدنى عبر youka project settings <id> --body .... اجلبه مرة واحدة لكل جلسة وكيل وخزّن النتيجة مؤقتًا.

​
وكلاء متوازيون

عندما يعمل عدة وكلاء بالتوازي على الحساب نفسه:
  • اجعل مفاتيح idempotency بنطاق كلٍ من هوية الوكيل والتعديل المنطقي: agent-${agentId}-create-${sourceHash}. يمنع ذلك اصطدام إعادة محاولة وكيل بطلب جديد لوكيل آخر.
  • اترك القراءات دون قيود — طلبات GET رخيصة ولا آثار جانبية لها.
  • استخدم قائمة انتظار واحدة لـ POST /projects/{projectId}/exports لكل مشروع إذا كنت تحتاج سجل تصدير مرتب. وإلا فقد تصل عمليات التصدير بترتيب غير متوقع.

​
ما التالي