mountChannels() قنواتك كلها خلف handler واحد (req, res) وتشغّل
كل طلب بالطريقة نفسها:
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.
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 لكي تحقن بديلًا في الاختبارات).
- يُفحص توقيع كل طلب (
v0HMAC-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 هي الإجابة، بعد إعادة التشغيل أيضًا (انظر أدناه).
- OAuth & Permissions: scopes البوت
app_mentions:readوchat:writeوchannels:history(معgroups:historyللقنوات الخاصة) للمتابعات دون إشارة، وim:historyللرسائل المباشرة. ثبّت التطبيق وانسخ الـ bot token (xoxb-...). - Event Subscriptions: الـ Request URL هو
https://<host>/channels/slack؛ وأحداث البوتapp_mentionوmessage.channels(message.groupsللقنوات الخاصة)، وmessage.imللرسائل المباشرة (وفعّل Messages Tab في App Home لكي يتمكن المستخدمون من مراسلة البوت). - Interactivity & Shortcuts: الـ Request URL هو
https://<host>/channels/slack(المسار نفسه). - Basic Information: انسخ الـ signing secret.
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.
- General Information: انسخ الـ application id والمفتاح العام.
- Interactions Endpoint URL:
https://<host>/channels/discord(يرسل Discord طلبPINGموقَّعًا عند الحفظ). - Installation: يكفي scope
applications.commands(أضفbotفقط إذا كنت تريد مستخدم البوت في السيرفر). - سجّل الأمر مرة واحدة (يظهر أمر الـ guild فورًا؛ استخدم
/applications/{id}/commandsلأمر عام):
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.
- أرسل
/newbot، واختر اسمًا واسم مستخدم، وانسخ الـ bot token. وللاستخدام في المجموعات، يحدد/setprivacyما إذا كان البوت يرى كل رسالة؛ أما/askوالإشارات والردود فتعمل في الحالتين. - اختر secret token عشوائيًا (من 1 إلى 256 حرفًا من
A-Zوa-zو0-9و_و-). - سجّل الـ webhook مرة واحدة، مع الـ bot token في الـ URL والـ secret token في الجسم (أبقِ كليهما بعيدًا عن history الـ shell والسجلات):
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)المعرّف ويُرجع ما إذا كان موجودًا من قبل) لكي تحفظها في مكان مشترك ودائم، مثل RedisSET 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من إنسان تسمح لهtriggersturn على 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.
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].
/approve يُرفض. وهي snapshot تُؤخذ عند الأمر، لا فحص صلاحية حيّ؛ فإذا كان يجب أن
يسري سحب الصلاحية داخل تلك النافذة، فاستخدم approvers بدالة تسأل GitHub API
(مثلًا عن صلاحية المتعاون) قبل أن تُرجع true. وترى دالة approvers، كما في القنوات
الأخرى، الاستدعاء المعلّق بعد إعادة التشغيل أيضًا (إذ يُسأل الـ approval store
الدائم)، ولا تفشل fail-closed إلا مع approval store محلي للعملية.
أعدّ تطبيق GitHub:
- أنشئ التطبيق (Settings ← Developer settings ← GitHub Apps ← New GitHub
App). وتحت Webhook، اضبط الـ URL على
https://<host>/channels/github، وأبقِه مفعّلًا، واختر secret عشوائيًا طويلًا (وهوwebhookSecret). - الصلاحيات: Issues قراءة وكتابة، وPull requests قراءة وكتابة. واشترك في Issue comment وPull request review comment.
- ولّد private key (يُنزّله GitHub بصيغة PKCS#1 PEM،
BEGIN RSA PRIVATE KEY؛ وتعمل PKCS#8 أيضًا) ودوّن الـ App ID. ثبّت التطبيق على المستودعات التي يجب أن يجيب فيها. كل webhook يسمّي الـ installation الخاص به، وتستبدل القناة JWT موقَّعًا بـ installation token لكلٍّ منها وتخزّنه مؤقتًا حتى 5 دقائق قبل انتهاء صلاحيته. botNameهو الـ slug الخاص بالتطبيق:@my-agentفي تعليق يشير إلى التطبيقmy-agent، الذي ينشر باسمmy-agent[bot].
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)، والـ issuerhttps://api.botframework.com، والـ audienceappId، مع تسامح في انحراف الساعة مقداره 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.
- أنشئ Azure Bot (single-tenant أو multi-tenant) ودوّن الـ Microsoft App
ID (
appId). وتحت Configuration، اضبط الـ messaging endpoint علىhttps://<host>/channels/teams. - وتحت Manage Password، أنشئ client secret (
appPassword). ولبوت single-tenant مرّر أيضًاtenantId(وعندئذ يُطلب الـ secret من الـ tenant الخاص بك). - وتحت Channels، فعّل Microsoft Teams.
- أنشئ manifest لتطبيق Teams يكون فيه مدخل
botsذوbotIdمساوٍ للـ App ID مع الـ scopes التي تريدها (personalوteamوgroupChat)، وثبّته.
onError بالاستدعاء وحالة HTTP فقط
(LOUSHO_CHANNEL_REQUEST_FAILED). والنقرة على بطاقة تعمل على عملية أُعيد
تشغيلها، لأنها تسمّي المحادثة والـ approval نفسه؛ ومع durable checkpoints
تُربط النقرة بـ turn الـ session المعلّق أولًا، لذا تنضم المتابعة إلى transcript
الـ session ولا تحسم النقرة التي لا تنتظرها الـ session شيئًا.