Libretto

Libretto هي مجموعة أدوات لبناء تكاملات ويب قوية. تزوّد وكيل البرمجة الخاص بك بمتصفح حي وواجهة سطر أوامر فعّالة من حيث الرموز المميزة (token-efficient) لـ:

• فحص الصفحات الحية بأقل حمل سياقي
• التقاط حركة مرور الشبكة لهندسة عكسية لواجهات برمجة التطبيقات (APIs) للموقع
• تسجيل إجراءات المستخدم وإعادة تشغيلها كنصوص برمجية أتمتة
• تصحيح سير العمل المعطل بشكل تفاعلي مقابل الموقع الحقيقي

قمنا في Saffron Health ببناء Libretto لمساعدتنا في صيانة تكاملات المتصفح الخاصة بنا مع البرامج الصحية الشائعة. نحن نُتيحه كمصدر مفتوح حتى تتمكن الفرق الأخرى من القيام بنفس الشيء بسهولة أكبر.

https://github.com/user-attachments/assets/9b9a0ab3-5133-4b20-b3be-459943349d18

روابط سريعة

• الموقع: libretto.sh
• التوثيق: libretto.sh/docs
• المستودع: github.com/saffron-health/libretto
• ديسكورد: discord.gg/NYrG56hVDt

التثبيت

# أضف Libretto إلى مشروعك. يتطلب Node.js و npm.
npm install libretto

# الإعداد لأول مرة: تثبيت المهارات وتنزيل Chromium
npx libretto setup

# التحقق من جاهزية مساحة العمل في أي وقت
npx libretto status

setup ينشئ المجلد .libretto/، ويُثبّت مهارات الوكيل، ويُحمّل Chromium ما لم تمرر --skip-browsers.

حالات الاستخدام

صُمّم Libretto لاستخدامه كمهارة عبر وكيل البرمجة الخاص بك. إليك بعض الأمثلة على المطالبات (prompts):

إنشاء نص برمجي (script) بخطوة واحدة

استخدم مهارة Libretto. اذهب إلى LinkedIn واستخرج أول 10 منشورات بمحتواها، وناشرها، وعدد التفاعلات، وأول 25 تعليق، وأول 25 إعادة نشر.

سيفتح وكيل البرمجة الخاص بك نافذة لتسجيل الدخول إلى LinkedIn، ثم يبدأ تلقائياً في الاستكشاف.

بناء نص برمجي تفاعلي

سأريك سير عمل في نظام السجلات الصحية الإلكترونية eClinicalWorks للحصول على معرف التأمين الأساسي لمريض. استخدم مهارة libretto لتحويله إلى نص برمجي Playwright يأخذ اسم المريض وتاريخ ميلاده كمدخلات ويُرجع معرف التأمين. الرابط هو ...

يستطيع Libretto قراءة الإجراءات التي تقوم بها في المتصفح، لذا يمكنك تنفيذ سير عمل، ثم تطلب منه استخدام إجراءاتك لإعادة بناء سير العمل.

تحويل أتمتة المتصفح إلى طلبات شبكة

لدينا نص برمجي للمتصفح في ./integration.ts يقوم بأتمتة الذهاب إلى Hacker News وجلب أول 10 منشورات. حوّله إلى نصوص برمجية شبكية مباشرة بدلاً من ذلك. استخدم مهارة Libretto.

يستطيع Libretto قراءة طلبات الشبكة من المتصفح، والتي يمكنه استخدامها لهندسة عكسية لواجهة API وإنشاء نص برمجي يستدعي تلك الطلبات مباشرة. استدعاءات API المباشرة أسرع وأكثر موثوقية من أتمتة واجهة المستخدم. يمكنك أيضاً أن تطلب من Libretto إجراء تحليل أمني يحلل الطلبات بحثاً عن ملفات تعريف الارتباط (cookies) الأمنية الشائعة، حتى تتمكن من فهم ما إذا كان نهج طلب الشبكة آمناً.

إصلاح التكاملات المعطلة

لدينا نص برمجي للمتصفح في ./integration.ts من المفترض أن يذهب إلى Availity ويجري فحص أهلية لمريض. لكنني أحصل على خطأ broken selector عند تشغيله. أصلحه. استخدم مهارة Libretto.

يمكن للوكلاء استخدام Libretto لإعادة إنتاج الفشل، وإيقاف سير العمل مؤقتاً في أي نقطة، وفحص الصفحة الحية، وإصلاح المشكلات، كل ذلك بشكل مستقل.

استخدام سطر الأوامر (CLI)

يمكنك أيضاً استخدام Libretto مباشرة من سطر الأوامر. جميع الأوامر تقبل --session <name> لاستهداف جلسة معينة.

npx libretto open <url>                    # تشغيل المتصفح وفتح عنوان URL
npx libretto run ./integration.ts --headless # تشغيل سير العمل وإغلاقه عند النجاح
npx libretto run ./integration.ts --headless --stay-open-on-success # إبقاء التشغيل الناجح قابلاً للفحص
npx libretto snapshot --session <name>     # التقاط لقطة شاشة وشجرة وصول مضغوطة
npx libretto exec "<code>"                 # تنفيذ Playwright TypeScript مقابل الصفحة المفتوحة
npx libretto close                         # إغلاق المتصفح

جلسات run قابلة للفحص من خلال نفس الأوامر المدعومة بالخادم الخلفي (daemon) مثل جلسات open. التشغيلات الناجحة تغلق المتصفح افتراضياً؛ مرّر --stay-open-on-success لإبقاء المتصفح مفتوحاً لأوامر pages و snapshot و exec. سير العمل الفاشل أو المتوقف يبقي المتصفح مفتوحاً حتى تتمكن من فحص حالة الصفحة بالضبط قبل إصلاح سير العمل أو استئنافه.

شغّل npx libretto help للحصول على القائمة الكاملة للأوامر.

الإعدادات

جميع حالة Libretto موجودة في مجلد .libretto/ في جذر مشروعك. راجع وثائق الإعدادات للتفاصيل حول ملفات الإعدادات والجلسات والملفات الشخصية.

القياس عن بُعد (Telemetry)

يسجل Libretto بيانات القياس عن بُعد الخاصة بسطر الأوامر للمساعدة في فهم استخدام CLI ومساعدتنا في تحديد أولويات التحسينات. يمكن لكل أمر تم حله إرسال فقط: معرف التثبيت، الطابع الزمني، اسم حدث الأمر مثل libretto run، قيمة خطأ منطقية (boolean)، إصدار الحزمة، قناة البناء (node_modules أو source أو unknown) وعند تسجيل الدخول إلى Libretto Cloud، معرف مستخدم السحابة المُعدّل. لا يرسل Libretto وسائط الأوامر أو عناوين URL أو مسارات المشروع أو ملفات تعريف الارتباط للجلسة أو مفاتيح API أو رسائل الخطأ أو التفاصيل أو عناوين البريد الإلكتروني.

يُخزّن معرف التثبيت في ملف القياس عن بُعد في ~/.libretto/telemetry.json. التطبيق موجود في packages/libretto/src/cli/core/telemetry.ts.

لتعطيل القياس عن بُعد، عيّن LIBRETTO_TELEMETRY_DISABLED=1 أو DO_NOT_TRACK=1 أو شغّل باستخدام CI=1، أو حرّر ~/.libretto/telemetry.json واضبط "enabled": false.

انضم إلى المجتمع

انضم إلى خادم ديسكورد (Discord) الخاص بنا للتواصل مع مطورين آخرين، والحصول على المساعدة، ومشاركة ما قمت ببنائه:

للنقاشات الطويلة، توجّه إلى GitHub Discussions. وجدت خطأً؟ افتح مشكلة.

الترخيص

رخصة MIT — استخدمه بحرية في المشاريع التجارية ومفتوحة المصدر.

التطوير

للتطوير المحلي في هذا المستودع:

pnpm i
pnpm build
pnpm type-check
pnpm test

هيكل المصدر:

• packages/libretto/src/cli/ — أوامر سطر الأوامر
• packages/libretto/src/runtime/ — بيئة تشغيل المتصفح (الشبكة، الاسترداد، التنزيلات)
• packages/libretto/src/shared/ — أدوات مشتركة (إعدادات، عميل LLM، تسجيل، حالة)
• packages/libretto/test/ — ملفات الاختبار (*.spec.ts)
• packages/libretto/README.template.md — مصدر الحقيقة لملفات README الخاصة بالمستودع والحزمة
• packages/libretto/skills/libretto/ — مصدر الحقيقة لمهارة Libretto

شغّل pnpm sync:mirrors بعد تعديل packages/libretto/README.template.md أو أي شيء داخل packages/libretto/skills/libretto/.

للتحقق من أن ملفات README المُنشأة ومرايا المهارات وبيانات تعريف إصدار المهارة متزامنة دون إصلاحها، شغّل pnpm check:mirrors. للإصدار، شغّل pnpm prepare-release.

[!NOTE] هذا مشروع في مرحلة مبكرة قيد التطوير النشط. قد تتغير واجهات برمجة التطبيقات (APIs) قبل الإصدار 1.0. نوصي بتثبيت إصدارات محددة في الإنتاج.

بُني بواسطة فريق Saffron Health.