الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
يربط الـ channel الـ agent بطرف واحد: JSON API، أو webhook، أو تطبيق محادثة. وهو الذي يحدد طريقة مصادقة الطلب الوارد، والمحادثة التي ينتمي إليها، وكيف يعود رد الـ agent (أو الـ approval الذي توقف عنده) إلى الطرف نفسه. تقدّم mountChannels() قنواتك كلها خلف handler واحد (req, res) وتشغّل كل طلب بالطريقة نفسها:
حلّت الـ channels محل الـ trigger adapters المدمجة (راجع الانتقال من الـ triggers). وتضيف ما ينقص الـ triggers: كل محادثة على الطرف هي session (جلسة)، والـ approvals والأسئلة تعود إلى الطرف. على host من نوع Fetch مثل Cloudflare Worker، تقدّم mountFetchChannels() المسارات نفسها: يدخلها Request ويخرج منها Response (ويُبقي ctx.waitUntil الخاص بالـ host الـ turn حيًّا بعد الرد على الـ webhook). ويركّب lousho build --target=cloudflare-worker مجلد channels/ الخاص بالـ agent directory تحت /channels بواسطتها. الـ channel الذي يُقرّ بالطلب مبكرًا (Slack، Discord، Telegram، GitHub، Teams) يُرسل رده فورًا فقط عندما يستطيع الـ turn مواصلة العمل بعد الرد: عبر ctx.waitUntil الخاص بالـ handler، أو خيار waitUntil لـ host لا يمرّر ctx. ودون أيٍّ منهما، ينتظر الرد الـ turn كله (ويُكتب تحذير مرة واحدة)، وهذا يتجاوز مهلة الـ 3 ثوانٍ الخاصة بـ Slack وDiscord إذا كان الـ turn بطيئًا.

البداية السريعة

httpChannel() هو الـ channel المرجعي: يدخله { sessionKey, input }، ويخرج منه JSON.

تأمين الـ http channel

الـ sessions مرتبطة بالـ sessionKey الذي يرسله المتصل، لذا فإن httpChannel() دون verify يتيح لأي شخص يصل إلى الـ port أن يقرأ محادثة مستخدم آخر أو يُكملها إذا خمّن المفتاح. ويسجّل تحذيرًا مرة واحدة عند إنشائه. مرّر verify دائمًا (فحص bearer token مثل المثال أعلاه، أو فحص session خاص بك)، واربطه على 127.0.0.1 ما لم يكن أمامه proxy أو firewall، واشتقّ sessionKey من المستخدم المصادَق عليه بدلًا من الوثوق بالعميل. يُرجع الـ handler القيمة true عندما يخدم الطلب، وfalse (دون أن يكتب شيئًا) لأي مسار آخر، مثل مسارات /chat في lousho dev. أي أنك تستطيع تركيبه بجانب مساراتك.

العقد

تفحص defineChannel({ ... }) الاسم وتُرجع التعريف: تُمرَّر metadata إلى الـ turn بوصفها metadata الخاصة بـ send() (وتراها دوال نطاق الذاكرة ودوال model / instructions / tools). وprincipal هو المتصل المتحقَّق منه في الـ turn، ويمر في الموضع نفسه الذي يمر فيه principal الخاص بـ send(). لا تضبط principal إلا من بيانات ضمنها verify. يتيح ctx (ChannelContext) لـ parse أن يسأل الـ host بدلًا من تخزين state: ctx.approval(id) (الاستدعاء المعلّق)، وctx.sessionId(key)، وctx.hasSession(key) (أي هل توجد session محفوظة لذلك المفتاح في الـ store)، وctx.pendingQuestion(key) (معرّف الـ ask_question الذي تنتظره session ذلك المفتاح، أو undefined؛ ويجد أيضًا سؤالًا طُرح قبل إعادة التشغيل عندما تكون الـ sessions والـ checkpoints والـ approvals في durable stores (مخازن تصمد بعد إعادة التشغيل)، ويربطه بالـ session فتنضم turn الإجابة إلى الـ transcript). استدعِ pendingQuestion فقط لرسالة ستُرجعها كإجابة، { decision: { id, answer: text }, inbound }: يُعطى المعرّف مرة واحدة حتى تُشغَّل تلك الإجابة. ويمكن أن يحمل { decision } الحقل inbound (المحادثة كما تسمّيها النقرة نفسها، فيبقى التوقف قائمًا بعد إعادة التشغيل) وapprover (مَن اتخذ القرار؛ ويُمرَّر إلى mountChannels({ onDecision }) لسجل التدقيق الخاص بك). req هو ChannelRequest مستقل عن أي framework: method وurl وheaders (أسماء بأحرف صغيرة) وrawBody (البايتات كما وصلت تمامًا: تحقّق من التواقيع عليها هي، لا على JSON أُعيدت سَلسَلته أبدًا) وtext وnative (طلب الـ host). الرد الذي لا يستدعي respond يتبعه 200 {"ok":true}. والطرف الذي يوصل الردود خارج الطلب (بالنشر على chat API مثلًا) يكفيه الإقرار بالطلب. والخطأ الذي يرميه verify أو parse يُرد عليه بـ 400 إذا كان SyntaxError (JSON غير صالح) وبـ 500 فيما عدا ذلك؛ والجسم الذي يتجاوز 1MB يأخذ 413. وجسم الـ 500 هو فقط { "error": "The request failed. The server log has the details.", "code"? }، مثل مسارات الـ session: يذهب الخطأ نفسه إلى onError (المرحلة 'parse')، ولا يصل إلى المتصل أبدًا. والـ turn الذي يفشل قبل أن يُقرّ الـ channel بالطلب يذهب إلى onError بالمرحلة 'turn'؛ وعندما تشغّل process أو replica أخرى turn تلك المحادثة (LOUSHO_SESSION_BUSY) يكون الرد 409 { "error", "code": "LOUSHO_SESSION_BUSY" } مع ترويسة Retry-After، فيستطيع المرسل إعادة الإرسال بعد قليل. والـ channel الذي يُقرّ بالطلب في parse (Slack و Discord وTelegram وTeams وGitHub) يحتفظ برده الخاص، ويُبلغ المستخدم في المحادثة أن الطلب فشل.

Sessions

الرسائل التي لها sessionKey نفسه على الـ channel نفسه تتشارك session واحدة، فيرى الـ agent التبادلات السابقة؛ وتعمل turns الـ session الواحدة واحدًا تلو الآخر. لا تقبل معرّفات الـ sessions إلا A-Za-z0-9_-، لذا في المعرّف الذي يحتوي على حروف أخرى (والافتراضي `${name}:${sessionKey}` يحتوي على : دائمًا) تُستبدل تلك الحروف بـ _ ويُلحق به hash للمعرّف الأصلي: فيصبح sms:+1555 sms__1555-<hash>. أرجِع معرّفًا صالحًا من sessionId() لكي يُستخدم كما هو. تُحفظ الـ transcripts في mountChannels(agent, channels, { store }): SessionStore أو { sessions, checkpoints } مثل SqliteStore (مرّر الـ store نفسه الذي أعطيته لـ createAgent({ store })). ودون store، يستخدم الـ handler الخيار createAgent({ store }) الخاص بالـ agent إذا كان يحفظ sessions، لذا ترى turns القنوات ومتابعات الـ approvals وagent.session({ id }) وagent.resume(id) كلها transcript واحدًا (ويشمل ذلك أيضًا createDeployedServer وLOUSHO_STORE)؛ أما الـ agent الذي ليس لديه session store فيحتفظ بها في الذاكرة.

approvals والأسئلة

عندما يتوقف turn عند tool يحتاج approval (موافقة)، أو عند استدعاء ask_question، يستدعي الـ handler الدالة onApproval (الافتراضي reply مع prompt مثل Approve send_email {"to":"sam@example.com"}? (approval id: ...)). احسمها بإحدى طريقتين؛ وتعود المتابعة عبر reply الخاص بالقناة نفسها (أو onApproval مرة أخرى إذا توقفت مجددًا):
  • handler.resolveApproval({ id, approved, note? }) أو handler.resolveApproval({ id, answer }) من الكود الخاص بك، مثلًا من callback زر في الطرف. وهي تحسم فقط التوقفات التي أنشأتها هذه العملية: بعد إعادة التشغيل (أو على replica أخرى) ترمي LOUSHO_APPROVAL_NOT_FOUND، لأنها لا تعرف أي محادثة تُكمل. استخدم المسار أدناه مع sessionKey بدلًا منها.
  • POST <basePath>/<name>/approvals/<id> مع { approved, note? } أو { answer }. يعمل verify الخاص بالقناة أولًا؛ والمعرّف الذي لم تتوقف عنده القناة يأخذ 404. أضف sessionKey (مفتاح المحادثة، كما هو في رسائلها) لكي تحسم توقفًا نسيته هذه العملية: مع sessions وcheckpoints وapprovals في durable stores، يُقبل القرار عندما ينتظر turn تلك المحادثة هذا الـ approval تحديدًا (وإلا 404)، وتنضم المتابعة إلى الـ transcript الخاص بها. وداخل العملية نفسها، فإن sessionKey الذي يسمّي محادثة غير التي توقفت يأخذ 404.
عندما يتوقف step واحد من الـ model عند أكثر من استدعاء (راجع عدة استدعاءات في step واحد)، تُستدعى onApproval مرة لكل استدعاء، بترتيب الاستدعاءات: يأخذ كلٌّ منها الـ approval الخاص به، وتأخذ جميعها الاستدعاءات المعلّقة الخاصة بالـ step في approvals، ولا يأخذ respond إلا الأول (وتردّ قناة http بـ approval وapprovals). يُحسم كل استدعاء على حدة، بأي من الطرق المذكورة أعلاه، مع sessionKey الخاص بالمحادثة بعد إعادة التشغيل. والقرار الذي يترك استدعاءات أخرى من الـ step نفسه دون حسم لا يشغّل شيئًا، ويُرد عليه عبر reply بـ Decision recorded. Still waiting on: ...؛ أما القرار على آخر استدعاء فيشغّل الـ step ويوصل المتابعة. يُحجز القرار قبل تشغيل onDecision، لذا فإن قرارين على الـ approval نفسه في الوقت نفسه (نقرة مزدوجة) يحسمانه مرة واحدة: يأخذ الثاني 409 { code: 'LOUSHO_APPROVAL_CONFLICT' } ما دام طلبه مفتوحًا، ويُتجاهل بصمت إذا كان الطرف قد تلقى الإقرار بالفعل. وترمي resolveApproval() الخطأ LOUSHO_APPROVAL_CONFLICT لـ approval يحسمه طلب آخر حاليًا.

القنوات الجاهزة

تفحص webhookChannel({ secret }) توقيع HMAC-SHA256 للجسم الخام في x-signature-256: sha256=<hex>؛ ويقبل auth أي مصادقة webhook (خيارات HMAC مع حماية من الـ replay، أو bearer token، أو مصادقة مخصّصة). والفحوصات والـ 401 العام هي نفسها لكل webhook. وprincipal هي (body, req) => Principal | undefined تسمّي متصل الـ turn من الطلب المتحقَّق منه (نظام التنبيهات الذي أرسل الـ hook، أو مستخدم تكامل)؛ وbody هو جسم JSON بعد الـ parsing، أو undefined إذا لم يكن JSON.

داخل agent directory

يستطيع agent directory أن يخزّن قنواته في channels/*.ts، بقناة واحدة default-exported في كل ملف. والمسار المخدوم هو POST /channels/<name>، حيث <name> هو name الخاص بالقناة نفسها؛ ولا يُطبَّق اسم الملف إلا على export بلا اسم — وكل factory جاهز يضبط اسمًا (webhookChannel() ← webhook، slackChannel() ← slack، …)، لذا فإن الملف channels/support.ts الذي يصدّر webhookChannel() يُخدَّم على /channels/webhook لا /channels/support. تُرجعها resolveAgentDir() بوصفها channels، ويركّبها سيرفر node الذي يُنتجه lousho build (createDeployedServer(agent, { channels })، وهو helper داخلي).

من يستطيع الموافقة (Slack و Discord)

تقبل القناتان approvers: قائمة بمعرّفات مستخدمي المنصة، أو دالة (user: { id, name?, roles? }, { toolName, input, sessionId, principal? }) => boolean | Promise<boolean> (يملأ Discord الحقل roles بمعرّفات أدوار العضو؛ وprincipal هو المرسل الذي توقف الـ turn الخاص به). يُسجَّل المستخدم الذي ينقر بوصفه approver (ctx.approval.by داخل الـ tool، راجع المصادقة)؛ ويظل الـ tool يعمل لصالح المرسل. ونقرة أي شخص آخر لا تحسم الـ approval: يصله تنبيه مؤقت “غير مسموح” ويظل الـ approval معلّقًا. ملاحظة أمنية. دون approvers، لا يستطيع الموافقة إلا المستخدم الذي بدأ الـ turn (كاتب الرسالة على Slack، أو مستخدم الأمر على Discord). في الإصدارات السابقة كان بإمكان أي شخص يرى الرسالة أن يوافق؛ وapprovers: () => true تُعيد ذلك السلوك، فلا تفعل ذلك إلا في قناة خاصة. وترى دالة approvers الاستدعاء المعلّق بعد إعادة التشغيل أيضًا: يسأل ctx.approval(id) الـ approval store الدائم عندما لا تكون هذه العملية هي التي توقفت عند المعرّف، فتقرر بالطريقة نفسها التي قررت بها من قبل. ولا تفشل fail-closed إلا مع approval store محلي للعملية (الافتراضي InMemoryApprovalStore — وفي هذه الحالة لا يصمد شيء أصلًا بعد إعادة التشغيل). وإجابات ask_question غير مقيّدة: الرسالة التالية (Slack) أو /ask (Discord) في المحادثة هي الإجابة. ويُمرَّر مَن اتخذ القرار إلى mountChannels(agent, channels, { onDecision({ approver, decision, sessionId, channel }) {} }). وتقبل قناة Telegram الخيار approvers نفسه (معرّفات مستخدمي Telegram كنصوص؛ وتأخذ الدالة { id, name }، حيث name هو اسم المستخدم أو الاسم الأول). تذهب الأعطال التي تحدث بعد الإقرار إلى onError (خيار في القناة، أو في mountChannels)؛ راجع العقد أعلاه.

Slack

تربط slackChannel({ signingSecret, botToken, name?, fetch? }) تطبيق Slack. كل thread في Slack هو session واحدة: الإشارة (mention) إلى البوت تبدأ session الـ thread (أو تُكملها)، ومفتاحها الـ workspace والقناة وts رسالة الجذر؛ والرسائل اللاحقة في thread له session تُكملها دون إشارة (يُسأل الـ session store، لذا يظل هذا يعمل بعد إعادة التشغيل). والرسالة المباشرة إلى البوت تبدأ session مفتاحها قناة الـ DM. وتُنشر الردود في الـ thread بـ chat.postMessage (fetch عادي، دون Slack SDK؛ مرّر fetch لكي تحقن بديلًا في الاختبارات).
  • يُفحص توقيع كل طلب (v0 HMAC-SHA256 بـ Web Crypto، ونافذة replay مدتها خمس دقائق)؛ ويُرد على الفشل بـ 401.
  • يُرد على الطلب فورًا (200، أو تحدي url_verification) ويعمل الـ turn بعد الرد، ضمن حد Slack البالغ 3 ثوانٍ.
  • الحدث المعاد تسليمه (event_id نفسه، مثلًا retry مع X-Slack-Retry-Num) ورسائل البوتات (بما فيها رسائل البوت نفسه) ونسخة message من الإشارة: كلها يُقَرّ بها وتُتجاوز، فلا يعمل أي turn مرتين. أما retry لحدث لم تستلمه هذه العملية أبدًا (ضاع تسليمه الأول) فيعمل. وتُحفظ معرّفات التسليم في الذاكرة لمدة ساعة.
  • يُنشر approval الـ tool في الـ thread مع زرّي Approve وDeny؛ وتستأنف النقرة الـ session وتُنشر المتابعة في الـ thread. وتُستبدل الرسالة المنقورة بالنتيجة (“Approved by @user”) فتختفي أزرارها. وتحمل النقرة قناتها والـ thread الخاص بها والمستخدم الذي يستطيع القرار، لذا تعمل بعد إعادة التشغيل. ويُنشر ask_question كنص، والرسالة التالية في الـ thread هي الإجابة، بعد إعادة التشغيل أيضًا (انظر أدناه).
أعدّ التطبيق في api.slack.com/apps:
  1. OAuth & Permissions: scopes البوت app_mentions:read وchat:write وchannels:history (مع groups:history للقنوات الخاصة) للمتابعات دون إشارة، وim:history للرسائل المباشرة. ثبّت التطبيق وانسخ الـ bot token (xoxb-...).
  2. Event Subscriptions: الـ Request URL هو https://<host>/channels/slack؛ وأحداث البوت app_mention وmessage.channels (message.groups للقنوات الخاصة)، وmessage.im للرسائل المباشرة (وفعّل Messages Tab في App Home لكي يتمكن المستخدمون من مراسلة البوت).
  3. Interactivity & Shortcuts: الـ Request URL هو https://<host>/channels/slack (المسار نفسه).
  4. Basic Information: انسخ الـ signing secret.
مصدر الـ threads النشطة هو session store الخاص بالقنوات (الـ store الذي تمرّره إلى mountChannels()، وإلا store الـ agent). وتُحسم الـ approvals المعلّقة من النقرة نفسها. ويصمد ask_question المعلّق بعد إعادة التشغيل عندما تكون الـ session والـ checkpoints والـ approvals في durable stores (مثلًا mountChannels(agent, channels, { store: sqlite }) مع SqliteStore، وapprovalStore الخاص بالـ agent): تظل الرسالة التالية في الـ thread هي الإجابة، ويكتمل الـ turn، ويُلحق السؤال والإجابة والرد بـ transcript الـ session. والرسالة في thread تنتظر الـ session الخاصة به approval على tool لا تحسمه؛ فالأزرار وحدها تحسمه. ونقرة الزر بعد إعادة التشغيل تُربط بـ session الـ thread أولًا — إذ يجب أن تسمّي النقرة thread الـ turn المحفوظ في checkpoint ينتظر ذلك الـ approval تحديدًا — لذا تنضم المتابعة إلى transcript الـ session، ولا تشغّل النقرة المعادة (replay) الـ tool مرتين، وتُرفض النقرة في thread آخر.

Discord

تربط discordChannel({ publicKey, applicationId, botToken?, name?, fetch? }) تطبيق Discord عبر HTTP Interactions endpoint (دون اتصال gateway ودون مكتبة Discord؛ Web Crypto وfetch فقط، لذا تعمل حتى على Workers). والأمر المتوقع هو /ask prompt:<text>: خيار نصي واحد، والخيار prompt (أو أول خيار نصي) هو الرسالة.
  • في كل طلب يُتحقَّق من X-Signature-Ed25519 / X-Signature-Timestamp على timestamp + body؛ والتوقيع الناقص أو غير الصالح، أو الـ timestamp الأقدم من خمس دقائق أو الذي يسبق الوقت المحلي بأكثر من دقيقة (طلب مُعاد)، يُرد عليه بـ 401، كما يشترط Discord. ويُرد على PING بـ PONG.
  • يُقَرّ بالأمر فورًا برد مؤجَّل (ضمن حد Discord البالغ 3 ثوانٍ)؛ ثم يعدّل الردُّ الردَّ الأصلي (PATCH /webhooks/{applicationId}/{token}/messages/@original). والنص الذي يتجاوز 2000 حرف يُستكمل في رسائل متابعة.
  • تتشارك الأوامر في القناة نفسها session واحدة، مفتاحها الـ guild والقناة (والـ thread إذا كان الأمر داخل thread).
  • يُنشر approval الـ tool مع زرّي Approve وDeny (ولا يستطيع النقر عليهما إلا approvers — وهم افتراضيًا مستخدم الأمر)؛ وتستأنف النقرة الـ session وتصل المتابعة كرسالة متابعة. وتحمل النقرة المحادثة، لذا تعمل بعد إعادة التشغيل. ويُنشر ask_question كنص، و/ask التالي في تلك القناة هو الإجابة، بعد إعادة التشغيل أيضًا (انظر أدناه).
  • تعيش interaction tokens مدة 15 دقيقة، لذا يفشل أي رد (أو نقرة) بعدها. وbotToken محجوز لاستدعاءات REST الخاصة بالبوت؛ والردود لا تحتاج إلا الـ interaction token.
أعدّ التطبيق في discord.com/developers/applications:
  1. General Information: انسخ الـ application id والمفتاح العام.
  2. Interactions Endpoint URL: https://<host>/channels/discord (يرسل Discord طلب PING موقَّعًا عند الحفظ).
  3. Installation: يكفي scope applications.commands (أضف bot فقط إذا كنت تريد مستخدم البوت في السيرفر).
  4. سجّل الأمر مرة واحدة (يظهر أمر الـ guild فورًا؛ استخدم /applications/{id}/commands لأمر عام):
تُحسم الـ approvals المعلّقة من نقرة الزر والـ approval store. وكما في Slack، يصمد ask_question المعلّق بعد إعادة التشغيل إذا كانت الـ sessions والـ checkpoints والـ approvals في durable stores: /ask التالي في القناة هو الإجابة، والـ turn المكتمل ينضم إلى transcript الـ session. ونقرة الزر بعد إعادة التشغيل تسمّي محادثتها، فتُربط بتلك الـ session قبل حسم الـ approval — فتنضم المتابعة إلى الـ transcript، ولا تحسم النقرة القديمة أو المنسوخة شيئًا. تُحمَّل ملفات channels/*.ts في agent directory كقنوات أيضًا، ويركّبها سيرفر node. وإذا كان لديك handler خاص لـ Slack، فإن verifySlackSignature() (راجع Triggers) يفحص توقيع الطلب.

Telegram

تضع telegramChannel({ botToken, secretToken, botUsername?, name?, fetch?, approvers?, onError? }) agent خلف بوت Telegram عبر webhooks (دون long polling ودون مكتبة Telegram؛ Web Crypto وfetch فقط، لذا تعمل حتى على Workers).
  • تُقارَن ترويسة X-Telegram-Bot-Api-Secret-Token في كل طلب بـ secretToken في زمن ثابت؛ والقيمة الناقصة أو غير الصالحة يُرد عليها بـ 401. وليس للقناة وضع دون مصادقة، لذا مرّر secret_token دائمًا إلى setWebhook.
  • يُقَرّ بالتحديث بـ 200 فورًا ويعمل الـ turn بعده، فلا يعيد Telegram إرسال الـ webhook. والتحديث الذي يُعاد تسليمه رغم ذلك (update_id نفسه) يُقَرّ به ولا يعمل مرة ثانية؛ وتُحفظ المعرّفات في الذاكرة لمدة ساعة.
  • في المحادثة الخاصة، كل رسالة نصية (أو caption صورة أو مستند) هي رسالة للـ agent. أما في مجموعة أو supergroup فلا يوقظ البوت إلا أمر /ask (أو /ask@<botUsername>)، أو رسالة تحتوي على @<botUsername>، أو رد على رسالة من رسائل البوت نفسه؛ ويُحذف الأمر والإشارة من النص وتُتجاهل كل رسالة أخرى. وتُتجاهل رسائل البوتات. اضبط botUsername (دون @) لكي تستخدم قواعد المجموعات التي تحتاجه.
  • session واحدة لكل محادثة، وواحدة لكل topic في supergroup من نوع منتدى. وتذهب الردود إلى المحادثة والـ topic نفسيهما، كرد على الرسالة التي أطلقت الـ turn.
  • الردود نص عادي (دون parse_mode)، لذا لا يمكن للـ Markdown الذي يُنتجه الـ model أن يجعل Telegram يرفض الرسالة. والنص الذي يتجاوز 4096 حرفًا ينقسم عند فواصل الأسطر إلى عدة رسائل.
  • يُنشر approval الـ tool مع inline keyboard تحتوي على Approve وDeny. ولا يستطيع النقر عليهما إلا approvers (الافتراضي: المستخدم الذي بدأت رسالته الـ turn)؛ ويصل الآخرين تنبيه ويظل الـ approval معلّقًا. وتجيب النقرة على الـ callback، وتعدّل الرسالة فتضيف “Approved by …” أو “Denied by …” وتحذف لوحة المفاتيح، وتُرسل المتابعة كرسالة جديدة. وتحمل النقرة محادثتها، لذا تعمل بعد إعادة التشغيل. ويحدّ Telegram الحقل callback_data بـ 64 بايت: فهو يحمل a: أو d: ومعرّف المستخدم الذي بدأ ومعرّف الـ approval (نحو 55 بايت). وإذا تجاوز 64 بايت، يُحذف معرّف البادئ، وعندئذ لا يستطيع الموافقة إلا قائمة approvers أو الدالة (والافتراضي يرفض الجميع).
  • يُرسل ask_question كنص مع force_reply، والرسالة التالية في المحادثة هي الإجابة (في المجموعة يجب أن تكون موجّهة إلى البوت، وهذا ما يحققه الرد على السؤال).
  • لا تُقرأ المرفقات بعد: النص أو الـ caption وحده يصل إلى الـ agent.
أعدّ البوت عبر @BotFather:
  1. أرسل /newbot، واختر اسمًا واسم مستخدم، وانسخ الـ bot token. وللاستخدام في المجموعات، يحدد /setprivacy ما إذا كان البوت يرى كل رسالة؛ أما /ask والإشارات والردود فتعمل في الحالتين.
  2. اختر secret token عشوائيًا (من 1 إلى 256 حرفًا من A-Z وa-z و0-9 و_ و-).
  3. سجّل الـ webhook مرة واحدة، مع الـ bot token في الـ URL والـ secret token في الجسم (أبقِ كليهما بعيدًا عن history الـ shell والسجلات):
الـ bot token جزء من كل URL في Bot API، لذا تبني القناة رسائل الخطأ من اسم الدالة وحالة HTTP فقط: لا يصل الـ token أبدًا إلى onError ولا إلى سطر السجل الافتراضي. تُحسم الـ approvals المعلّقة من النقرة والـ approval store. وكما في Slack وDiscord، يصمد ask_question المعلّق بعد إعادة التشغيل إذا كانت الـ sessions والـ checkpoints والـ approvals في durable stores: الرسالة التالية في المحادثة هي الإجابة، والـ turn المكتمل ينضم إلى transcript الـ session. وكما في نقرة الزر في القنوات الأخرى، تُفحص النقرة بعد إعادة التشغيل مقابل الـ turn المحفوظ في checkpoint الخاص بـ session المحادثة، لذا تنضم المتابعة إلى الـ transcript ولا تشغّل النقرة المعادة الـ tool مرتين.

GitHub

تتيح githubChannel({ webhookSecret, botName, token?, app?, name?, apiUrl?, fetch?, triggers?, approvers?, pullRequestOpened?, onError? }) للناس استدعاء agent بـ @<botName> في تعليق على issue أو pull request أو review في GitHub؛ ويجيب الـ agent بتعليق في الـ thread نفسه. وهي تقرأ webhooks تطبيق GitHub (أو مستودع واحد) وتنشر عبر REST API بـ fetch وWeb Crypto فقط (دون node:* import ودون مكتبة GitHub)، لذا تعمل حتى على Workers.
  • تُفحص ترويسة X-Hub-Signature-256 في كل طلب مقابل الجسم الخام بـ webhookSecret (HMAC-SHA256، مقارنة في زمن ثابت) قبل إجراء parse للجسم؛ والتوقيع الناقص أو غير الصالح يُرد عليه بـ 401. وليس للقناة وضع دون مصادقة.
  • يُقَرّ بالـ webhook بـ 200 فورًا ويعمل الـ turn بعده: ينتظر GitHub مدة 10 ثوانٍ ولا يعيد المحاولة، ويُنشر الرد البطيء كتعليق جديد. ويُقَرّ بـ ping دون turn. وإعادة التسليم (X-GitHub-Delivery نفسه، مثلًا “Redeliver” في إعدادات التطبيق) يُقَرّ بها ولا تعمل مرة ثانية؛ وتُحفظ المعرّفات في الذاكرة لمدة ساعة، وهذا لا تراه إعادة تشغيل أو replica أخرى. مرّر deliveries (DeliveryStore، الذي يسجّل فيه seen(id) المعرّف ويُرجع ما إذا كان موجودًا من قبل) لكي تحفظها في مكان مشترك ودائم، مثل Redis SET NX EX:
  • التعليق على issue، أو على pull request (تبويب المحادثة)، أو review comment (على سطر من الـ diff) الذي يحتوي على @<botName> ككلمة كاملة (دون حساسية لحالة الحروف) يبدأ turn، وتُحذف الإشارة من النص. وبمجرد أن تصبح للـ thread session، يُعدّ كل تعليق لاحق فيه متابعة ولا يحتاج إلى إشارة. وتُتجاهل التعليقات المعدّلة والمحذوفة، وتعليقات البوتات (user.type هو Bot)، وتعليقات <botName>[bot]، وتعليقات botLogin، وأي تعليق نشرته القناة نفسها — لذا لا يجيب الـ agent نفسه أبدًا. وتُتجاهل الأحداث الأخرى (فتح issues، وpushes، وreactions، وcheck runs) — باستثناء pull_request: مع pullRequestOpened: true، يبدأ إجراء opened من إنسان تسمح له triggers turn على session الـ PR نفسها (<owner>/<repo>#<number>، وهي الـ session نفسها التي تتشاركها تعليقاته)، لذا يستطيع بوت المراجعة قراءة الـ PR فور فتحه. وتُتجاهل synchronize وclosed وreopened والـ PRs التي فتحها بوت أو التي لا تسمح لها triggers.
  • session واحدة لكل issue أو pull request (<owner>/<repo>#<number>)، وواحدة لكل review thread (الـ review comment والردود تحته).
  • الرد تعليق جديد: تعليق في timeline الـ issue أو الـ pull request، أو رد في الـ review thread. والنص الذي يتجاوز 60,000 حرف (حد GitHub هو 65,536) ينقسم عند فواصل الأسطر إلى عدة تعليقات. ويحمل كل تعليق علامة مخفية (تعليق HTML) تعرفها القناة.
  • approval الـ tool هو تعليق يحتوي على الـ tool ووسائطها في fenced block وسطر “Reply /approve <id> or /deny <id>.”. والتعليق الذي يكون سطره الأول /approve <id> أو /deny <id> (بأي حالة حروف) يحسمها؛ وما بعد السطر الأول ملاحظة للـ model. أما اقتباس الـ prompt، أو الأمر في أي موضع غير السطر الأول، فلا يحسم شيئًا. وتجيب القناة بـ “Approved by @login.” أو “Denied by @login.” ويكتمل الـ run بتعليق جديد. والمعرّف هو معرّف الـ approval المعلّق، لذا لا يستطيع أمر قديم (webhook أُعيد تسليمه، أو تعليق approval حُسم سابقًا) أن يحسم approval لاحقًا.
  • يُنشر ask_question كتعليق والتعليق التالي في ذلك الـ thread هو الإجابة (دون إشارة، من أي شخص تسمح له triggers). ويصمد السؤال المعلّق بعد إعادة التشغيل إذا كانت الـ sessions والـ checkpoints والـ approvals في durable stores، كما في Slack وDiscord؛ والثمن lookup واحد في الـ store لكل تعليق ليس إشارة في thread ليس له session.
ملاحظة أمنية. تعليق GitHub نص يكتبه أي شخص يستطيع التعليق على المستودع، وفي المستودع العام يعني ذلك الجميع. لذا فهو إدخال غير موثوق للـ agent، مثل أي رسالة مستخدم، وقد يحاول توجيهه (prompt injection)؛ ونص الـ issue والـ pull request الذي يشير إليه غير موثوق بالقدر نفسه. لا تعطِ الـ agent إلا tools تقبل أسوأ استخدام لها، وأبقِ needsApproval على ما يكتب أو ينفق. هناك خياران يحددان مَن هو الموثوق، وكلاهما صريح:
  • triggers (الافتراضي: كل من يستطيع التعليق) يحدد من يستطيع بدء turn أو الإجابة عن سؤال: قائمة logins، أو دالة ({ login, association }) => boolean. وفي المستودع العام قيّده (مثلًا بـ association من OWNER أو MEMBER أو COLLABORATOR) ما لم تكن تريد أن ينفق الغرباء رصيد الـ models الخاص بك.
  • approvers يحدد من يستطيع /approve و/deny، وافتراضه مغلق: دونه لا يستطيع القرار إلا المعلّق الذي يكون author_association الخاص به OWNER أو MEMBER أو COLLABORATOR. وهذا يختلف عن Slack وDiscord عن قصد: فـ thread GitHub مرئي لكل من يستطيع قراءة المستودع، ومن بدأ الـ turn قد يكون أي شخص، لذا فإن كاتب الطلب ليس موثوقًا للموافقة عليه. ويصل الأمرَ المرفوض الرد “@login is not allowed to approve this request.” ويظل الـ approval معلّقًا. ومع قائمة logins (دون حساسية لحالة الحروف) لا يقرر إلا أولئك المستخدمون، مهما كانت الـ association الخاصة بهم. ومع دالة (user, { toolName, input, sessionId }) => boolean، يكون user.id هو الـ login وuser.roles هو [author_association].
تُقرأ الـ association من webhook تعليق الأمر نفسه، لذا يُبنى القرار على ما أبلغ عنه GitHub عند كتابة ذلك التعليق (والطلب أصلي بفضل التوقيع)، لا على العضوية التي كانت للمعلّق عند طلب الـ approval: فالمتعاون الذي أُزيل قبل أن ينشر /approve يُرفض. وهي snapshot تُؤخذ عند الأمر، لا فحص صلاحية حيّ؛ فإذا كان يجب أن يسري سحب الصلاحية داخل تلك النافذة، فاستخدم approvers بدالة تسأل GitHub API (مثلًا عن صلاحية المتعاون) قبل أن تُرجع true. وترى دالة approvers، كما في القنوات الأخرى، الاستدعاء المعلّق بعد إعادة التشغيل أيضًا (إذ يُسأل الـ approval store الدائم)، ولا تفشل fail-closed إلا مع approval store محلي للعملية. أعدّ تطبيق GitHub:
  1. أنشئ التطبيق (Settings ← Developer settings ← GitHub Apps ← New GitHub App). وتحت Webhook، اضبط الـ URL على https://<host>/channels/github، وأبقِه مفعّلًا، واختر secret عشوائيًا طويلًا (وهو webhookSecret).
  2. الصلاحيات: Issues قراءة وكتابة، وPull requests قراءة وكتابة. واشترك في Issue comment وPull request review comment.
  3. ولّد private key (يُنزّله GitHub بصيغة PKCS#1 PEM، BEGIN RSA PRIVATE KEY؛ وتعمل PKCS#8 أيضًا) ودوّن الـ App ID. ثبّت التطبيق على المستودعات التي يجب أن يجيب فيها. كل webhook يسمّي الـ installation الخاص به، وتستبدل القناة JWT موقَّعًا بـ installation token لكلٍّ منها وتخزّنه مؤقتًا حتى 5 دقائق قبل انتهاء صلاحيته.
  4. botName هو الـ slug الخاص بالتطبيق: @my-agent في تعليق يشير إلى التطبيق my-agent، الذي ينشر باسم my-agent[bot].
لمستودع واحد يمكنك تخطي التطبيق: أضف webhook للمستودع (content type application/json، والحدثان نفسهما، والـ URL والـ secret نفسهما) ومرّر token — fine-grained personal access token بصلاحية قراءة وكتابة على Issues وPull requests في ذلك المستودع (أو دالة تُرجع token). وعندئذ تُنشر الردود باسم مستخدم الـ token، لذا مرّر أيضًا botLogin بـ login ذلك المستخدم. ودونه، لا يمنع الـ agent من الإجابة على تعليقاته إلا العلامة المخفية الخاصة بالقناة.
يوجّه apiUrl القناة إلى GitHub Enterprise Server (https://<host>/api/v3). ولا يوضع الـ token ولا الـ private key ولا الـ JWT أبدًا في رسالة خطأ أو سطر سجل: يُبلَّغ عن الاستدعاء الفاشل إلى onError بالاستدعاء وحالة HTTP فقط (LOUSHO_CHANNEL_REQUEST_FAILED). تُحسم الـ approvals المعلّقة من تعليق الأمر والـ approval store. ويُحفظ ask_question المعلّق في الذاكرة حتى التعليق التالي، ويصمد بعد إعادة التشغيل إذا كانت الـ stores durable، كما في القنوات الأخرى. وبعد إعادة التشغيل، يسمّي الأمر الـ thread الخاص به، لذا مع durable checkpoints يُربط بـ session ذلك الـ thread قبل حسم الـ approval: تنضم المتابعة إلى transcript الـ session، والمعرّف الذي لا ينتظره الـ thread (حُسم بالفعل، أو approval لـ thread آخر) يفشل بتعليق “Sorry, that request failed.” العام.

Microsoft Teams

تضع teamsChannel({ appId, appPassword, tenantId?, name?, fetch?, approvers?, onError? }) agent خلف Azure Bot في Microsoft Teams: تبدأ المحادثات الشخصية والإشارات في القنوات session أو تُكملها، وتعود الردود عبر Bot Framework Connector، وapproval الـ tool بطاقة Adaptive Card فيها زرّا Approve وDeny. وهي تستخدم fetch وWeb Crypto فقط (دون node:* import ودون مكتبة Bot Framework)، لذا تعمل حتى على Workers.
  • يجب أن يحمل كل طلب Bot Framework token في Authorization: Bearer. ويُتحقَّق منه قبل parsing الجسم: يُفحص توقيع RS256 مقابل مجموعة المفاتيح التي تشير إليها بيانات OpenID الثابتة الخاصة بـ Bot Framework (https://login.botframework.com/v1/.well-known/openidconfiguration) (مخزّنة مؤقتًا، ولا تُؤخذ أبدًا من URL داخل الـ token)، والـ issuer https://api.botframework.com، والـ audience appId، مع تسامح في انحراف الساعة مقداره 5 دقائق. ويجب أن تساوي مطالبة serviceurl في الـ token قيمة serviceUrl في الـ activity أيضًا، لذا لا يمكن إعادة استخدام token صالح لعنوان خدمة واحد لجعل البوت ينشر في مكان آخر. ويُرد على أي فشل بـ 401. وليس للقناة وضع دون مصادقة، ومُحاكي Bot Framework دون مصادقة غير مدعوم.
  • يُقَرّ بالـ activity بـ 200 فورًا ويعمل الـ turn بعده. ولا تصل إلى الـ agent إلا activities من نوع message؛ وتُتجاهل conversationUpdate وtyping وinvoke ورسائل البوت نفسه.
  • تبدأ المحادثة الشخصية session أو تُكملها دائمًا. أما في المحادثة الجماعية أو القناة فلا يفعل ذلك إلا رسالة تتضمن @mention للبوت؛ وتُحذف الإشارة من النص وتُتجاهل كل رسالة أخرى.
  • session واحدة لكل محادثة (conversation.id؛ وفي قناة Teams يشمل رسالة جذر الـ thread، لذا كل thread هو session مستقلة). والمرسل (from.aadObjectId، وإلا from.id) هو principal الخاص بالـ run (authenticator: 'teams'، وissuer: الـ tenant)، كما في القنوات الأخرى.
  • تُنشر الردود بصيغة Markdown على {serviceUrl}/v3/conversations/{id}/activities/{replyToId}، باستخدام serviceUrl الذي ضمنه الـ token (https فقط). والنص الذي يتجاوز 25,000 حرف ينقسم عند فواصل الأسطر. ويأتي الـ access token الصادر من تدفق client-credentials بـ appId وappPassword ويُخزَّن مؤقتًا حتى 5 دقائق قبل انتهائه.
  • approval الـ tool بطاقة Adaptive Card (الإصدار 1.4) تحتوي على الـ tool ووسائطها (تُقتطع عند 2,000 حرف) وزرّي Action.Submit. ولا يستطيع استخدامهما إلا approvers (معرّفات مستخدمي Teams مثل from.id، أو دالة)؛ وافتراضيًا المستخدم الذي بدأ الـ turn فقط. ويصل أي شخص آخر الرد “You are not allowed to approve this request.” ويظل الـ approval معلّقًا. وتستبدل النقرة البطاقة بـ “Approved by <name>.” أو “Denied by <name>.” (دون أزرار) ويكتمل الـ run برسالة جديدة. ويحمل الزر المحادثة التي نُشر فيها، والنقرة التي تختلف محادثتها (مرجع منسوخ) لا تحسم شيئًا؛ ومعرّف الـ approval هو معرّف المعلّق، لذا لا تستطيع بطاقة قديمة أن تحسم approval لاحقًا، والبطاقة المستخدمة مسبقًا لا تفعل شيئًا، حتى بعد إعادة التشغيل.
  • يُنشر ask_question كنص والرسالة التالية في المحادثة هي الإجابة. ويصمد السؤال المعلّق بعد إعادة التشغيل إذا كانت الـ sessions والـ checkpoints والـ approvals في durable stores، كما في Slack وDiscord.
أعدّ البوت:
  1. أنشئ Azure Bot (single-tenant أو multi-tenant) ودوّن الـ Microsoft App ID (appId). وتحت Configuration، اضبط الـ messaging endpoint على https://<host>/channels/teams.
  2. وتحت Manage Password، أنشئ client secret (appPassword). ولبوت single-tenant مرّر أيضًا tenantId (وعندئذ يُطلب الـ secret من الـ tenant الخاص بك).
  3. وتحت Channels، فعّل Microsoft Teams.
  4. أنشئ manifest لتطبيق Teams يكون فيه مدخل bots ذو botId مساوٍ للـ App ID مع الـ scopes التي تريدها (personal وteam وgroupChat)، وثبّته.
لا يوضع الـ app password ولا الـ access token في رسالة خطأ أو سطر سجل: يُبلَّغ عن الاستدعاء الفاشل إلى onError بالاستدعاء وحالة HTTP فقط (LOUSHO_CHANNEL_REQUEST_FAILED). والنقرة على بطاقة تعمل على عملية أُعيد تشغيلها، لأنها تسمّي المحادثة والـ approval نفسه؛ ومع durable checkpoints تُربط النقرة بـ turn الـ session المعلّق أولًا، لذا تنضم المتابعة إلى transcript الـ session ولا تحسم النقرة التي لا تنتظرها الـ session شيئًا.