Programmatic Integration

الفكرة في دقيقة

ابدأ بالمعنى، ثم انتقل إلى التفاصيل.

هذا الدرس يشرح Programmatic Integration ضمن موضوع داخل Hermes وكيف يوسّعه المطور. ستعرف ما الذي يفعله هذا الجزء، متى تحتاجه، وما أصغر خطوة آمنة للتأكد أنه يعمل.

إن كنت مبتدئًا

إن كنت جديدًا: لا تحفظ الأسماء. ركّز على ثلاثة أسئلة: ما المشكلة التي يحلها هذا الجزء؟ ما البيانات أو الصلاحيات التي يحتاجها؟ وكيف أعرف أن النتيجة صحيحة؟

للتطبيق العملي

للتطبيق: اقرأ المثال الأول، حدّد ما سيغيّره، نفّذه على بيانات تجريبية، ثم قارن الناتج بما وعد به المصدر.

للمتخصص

للمتخصص: راجع ACP (Agent Client Protocol)، TUI Gateway JSON-RPC، Method catalog (selected)، ثم افحص حالات الفشل والتوافق مع إصدارك.

ما الذي تحتاجه قبل البدء؟

اعرف Python وGit وبنية مشروع برمجي قبل تعديل الكود.

ماذا ستعرف؟

نتيجة واضحة قبل أن تقرأ.

تفهم Programmatic Integration من دون افتراض معرفة سابقة.
تفرّق بين الوصف والمعلومة التي تحتاج إلى اختبار في بيئتك.
اقرأ الأمر الأول وحدد المدخلات والمخرجات قبل نسخه.

مصطلحات هذا الدرس

تعريفات قصيرة قبل التفاصيل.

ACP: بروتوكول يربط الوكيل بواجهات ومحررات تدعم تشغيل جلساته وأحداثه.
Provider: الخدمة التي تشغّل النموذج أو توفّر الوصول إليه والمصادقة الخاصة به.
Gateway: العملية التي تربط Hermes بقنوات مثل Telegram وDiscord وتدير وصول الرسائل.

وصف الصفحة الرسمي

Three protocols for driving hermes-agent from external programs: ACP, the TUI gateway JSON-RPC, and the OpenAI-compatible HTTP API

خريطة الموضوع

ما الذي يقوله المصدر، وبأي ترتيب؟

01
ACP (Agent Client Protocol)
ابدأ بهذا القسم لتفهم الفكرة أو البنية الأساسية.
02
TUI Gateway JSON-RPC
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
03
Method catalog (selected)
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
04
Rewinding history on prompt.submit
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
05
Events streamed back
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
06
Pi-style RPC mapping
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
07
OpenAI-Compatible API Server
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
08
Model catalog surfaces
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
09
Which one should I use?
اقرأه بعد الأساسيات، ثم اربطه بالخطوة السابقة قبل المتابعة.
10
Model hot-swapping
اختم بهذا القسم لتفحص النتيجة والحالات الخاصة.

أمثلة من الصفحة الرسمية

انسخ بعد أن تفهم الأثر.

hermes acp                  # serve ACP on stdio
hermes acp --check          # verify ACP dependencies and adapter imports
hermes acp --setup          # interactive provider/model setup for ACP terminal auth

prompt.submit           prompt.background       session.steer
session.create          session.list            session.active_list
session.activate        session.close           session.interrupt
session.history         session.compress        session.branch
session.title           session.usage           session.status
clarify.respond         sudo.respond            secret.respond
approval.respond        config.set / config.get commands.catalog
command.resolve         command.dispatch        cli.exec
reload.mcp              reload.env              process.stop
delegation.status       subagent

POST /v1/chat/completions        OpenAI Chat Completions (streaming via SSE)
POST /v1/responses               OpenAI Responses API (stateful)
POST /v1/runs                    Start a run, returns run_id (202)
GET  /v1/runs/{id}               Run status
GET  /v1/runs/{id}/events        SSE stream of lifecycle events
POST /v1/runs/{id}/approval      Resolve a pending approval
POST /v1/runs/{id}/stop          Interrupt the run
GET  /v1/capabilities            Machine-readable feature flags
GET  /v1/models                  Lists hermes-agent
GET  /api/model/options          Provider-aware picker i

تطبيق الآن

اقرأ الأمر الأول وحدد المدخلات والمخرجات قبل نسخه.

طابق أي أمر مع إصدار Hermes المثبّت، وراجع الملفات والحسابات التي قد يصل إليها، واستخدم بيانات غير حساسة في أول اختبار. إذا اختلف الشرح عن المصدر، فالمصدر الرسمي هو المرجع النهائي.

اختبار الفهم

ثلاثة قرارات قبل علامة الاكتمال.

1. ما المرجع النهائي عند تغيّر معلومات «شرح Programmatic Integration»؟منشور غير مؤرخالتوثيق الرسمي ومستودع Hermesنتيجة بحث بلا مصدر

2. ما أفضل طريقة لتطبيق هذا الدرس؟نسخ كل أمر مباشرةتنفيذ خطوة صغيرة ثم التحقق من نتيجتهامنح كل الصلاحيات لتوفير الوقت

3. ماذا تفعل قبل خطوة قد تعدّل ملفات أو حسابًا خارجيًا؟تراجع النطاق والصلاحيات ومسار التراجعتلغي العزلتشارك المفتاح في المحادثة