حُرّاس Vercel AI SDK: سدّ ثغرة المطابقة المقسومة

خمسة أمثلة، ولا واحد منها يجتاز المصرِّف

يوثّق AI SDK وسيطَ النماذج اللغوية في صفحة واحدة، وكانت تلك الصفحة تحمل خمسة أمثلة عملية. وبنسخها إلى مشروع يعمل على ai@7.0.107 و@ai-sdk/provider@4.0.17، أخفق كل واحد منها على النحو نفسه:

error TS2741: Property 'specificationVersion' is missing in type
'{ wrapGenerate: ... }' but required in type 'LanguageModelV4Middleware'.

وspecificationVersion: 'v4' حقل مطلوب غير قابل للتعديل في نوع الوسيط، ولم تذكره الصفحة في أي موضع — لا في المثال الأول، ولا في ملاحظة، ولا عَرَضًا. ولم يكن الخلل خفيًّا: فكل مثال على الصفحة أخفق على الخاصية الناقصة نفسها، مهما كان ما يعرضه كل واحد منها. فالقارئ الذي يتبع الصفحة يحصل على هذا الخطأ في أول وسيط يكتبه، ولا يجد في الصفحة ما يفسّره.

النصف الذي تُرك تعليقًا

أما المشكلة الثانية فأكبر، وقد كانت الصفحة صريحة بشأنها. فمثال الحماية ينفّذ wrapGenerate، ويُجري .replace() على النص بعد اكتماله، ويترك نصف البثّ تعليقًا، وهذا نصّه كما التُقط بالضبط:

here you would implement the guardrail logic for streaming // Note: streaming guardrails are difficult to implement, because you do not know the full content of the stream until it's finished.

الملاحظة صحيحة، وهي تذكر الصعوبة كلّها بوضوح. لكنها لا تقول ما الذي يحدث للقارئ الذي يقرؤها دعوةً. فالخطوة البديهية أن ينقل .replace() من wrapGenerate ويضعها في تحويل يمرّ على أجزاء البثّ. والنتيجة تبدو حارسًا عاملًا، وتنجو من تجربة يدوية بطلب قصير، وهي خاطئة من وجهين منفصلين.

الوجه الأول: المطابقة ليست هناك أصلًا لتُلتقط

يُخرج النموذج نصّه دفعاتٍ مقسومة على حدود الرموز لا على المعنى. وأي قيمة تطول بما يستحقّ الحجب تتوزّع عادةً على عدّة دفعات منها.

delta 1:  "...your card is 4111 11"
delta 2:  "11 1111 1111, charge it."

و.replace() على الدفعة الأولى لا تجد رقم بطاقة، وعلى الثانية لا تجد رقم بطاقة. وتذهب الدفعتان إلى العميل، فيصلهما المتصفّح، ويظهر الرقم على الشاشة. وبأحجام الدفعات التي يرسلها المزوّدون فعلًا، ليست هذه حالة طرفية — بل هي الحالة الغالبة في معظم القيم التي تستحقّ الترشيح.

الوجه الثاني: السرّ المحجوب نصفه

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

بعض الأنماط تتوقّف عن النمو، وكثير منها لا يتوقّف. فالنمط الذي يطابق سرًّا متغيّر الطول يطابق بمجرّد أن يطول النص بما يكفي، ثم يظلّ يطابق كلّما وصلت محارف أخرى. وإن وقعت نقطة الإخراج داخل قيمة ما زالت تنمو — وهذا ما يقع كثيرًا مع نافذة ثابتة — حجب المرشّح ما بين يديه وبثّ الباقي مكشوفًا:

out:  "your key is <REDACTED>uvwxyz123456"

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

القاعدة

لا تتصرّف بناءً على مطابقة يمكن أن تنمو، ولا تُخرج نصًّا لم تفحصه في صورته النهائية.

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

الخاصية مكتوبةً اختبارًا

القاعدة تعليمة تصميم، وهذه صورتها القابلة للفحص آليًّا:

لأي مدخل وأي تقسيم، يجب أن يطابق الناتج المبثوث — بايتًا ببايت — ترشيحَ النص كاملًا دفعة واحدة.

أعد تشغيل المدخل نفسه بكل حجم دفعة — محرف واحد، ثم اثنان، ثم ثلاثة، حتى النص كلّه — وقارن كل تشغيلة بنتيجة المرور الواحد. فيتحوّل الإخفاقان أعلاه إلى اختلاف، ولا يحتاج أحد إلى الاستدلال على أي حدّ كان الحدّ المشؤوم. وهو قصير، ولا يعنيه كيف بُني المرشّح. وللصنف الذي يكشفه اسم وكتابة أطول: بيانات شخصية مقسومة بين أجزاء البثّ.

ما الذي دُمج

كان البلاغ vercel/ai#21209، «docs: guardrails example leaves wrapStream unimplemented» (مثال الحماية ترك wrapStream دون تنفيذ)، رُفع في 20 سبتمبر 2026. وأُغلق في 22 سبتمبر بعد تسعة تعليقات. وفي 28 سبتمبر 2026 كان المستودع يحمل 27,011 نجمة. ودُمجت ثلاثة طلبات دمج بفارق ستّ عشرة ثانية بينها:

• #21210 على main — ملف واحد، +92/-7
• #21211 على release-v6.0 — ملف واحد، +92/-7
• #21212 على release-v5.0 — ملفان، +151/-21

أي +335/-35 على ثلاثة فروع. ويحمل البلاغ الوسوم merged-main وmerged-v5.0 وmerged-v6.0 وdocumentation-fix، من بين غيرها. وحتى 28 سبتمبر 2026، تحمل صفحة الوسيط الحيّة specificationVersion: 'v4'.

ومثال wrapStream الذي حطّ لا يعتمد على أي مكتبة. يحتفظ بمخزن لكل مُعرّف نصّي — إذ يمكن للبثّ أن يحمل عدّة كتل نصّية في آن واحد، وهذا بالضبط ما وُجد من أجله المُعرّف على كل جزء، والمخزن الواحد المشترك ينسب النص إلى الكتلة الخطأ. ثم يحسب نقطة حسم، ويمشي على المطابقات في المخزن، وحين تتجاوز مطابقةٌ نقطةَ الحسم يحتجز من m.index لا من نقطة الحسم. ولا يقطع داخل زوج بديل أبدًا، فلا يصل الرمز التعبيري نصفين مكسورين. وهو، إذا قُرئ كلّه، القاعدةُ أعلاه مكتوبةً كودًا بدل أن تُوصف في تعليق.

الإفصاح جاء أولًا

وثمّة تفصيل يزن أكثر من الفرق في الأسطر. فقد افتُتح البلاغ بهذا، قبل وصف المشكلة أصلًا: «إفصاح: أنا أشرف على مكتبة برخصة MIT تُجري الحجب على البثّ، فلي مصلحة هنا. والاقتراح أدناه قائم بذاته عن قصد — لا يعتمد عليها إطلاقًا، ويمكنك وضعه في التوثيق كما هو.»

والمكتبة هي llm-stream-guardrails، وقد نُشرت على npm في 21 سبتمبر 2026 — في اليوم التالي لرفع البلاغ. فالبلاغ جاء أولًا، وما اقترحه رقعةٌ يستطيع المشرف أن يأخذها دون أن يأخذ معها شيئًا آخر. وهذا هو الترتيب الوحيد الذي يجوز فيه لمن يشرف على بديل أن يرفع بلاغًا على مشروع بهذا الحجم: أعلن المصلحة في الأعلى، ثم اجعل الاقتراح جيّدًا بما يكفي ليصمد بعد إعلانها.

إن كنت تكتب واحدًا من هذه

خذ القاعدة والشرط الثابت، ولا تحتاج إلى شيء آخر في هذه الصفحة. كلاهما يعمل بلا أي اعتماد على مكتبة، والمثال الموجود الآن في توثيق AI SDK تنفيذ كامل لهما. وثمّة مكتبات أخرى تعالج حدود الأجزاء باستطلاع محدود وتؤدّي عملها — فالسؤال ليس أي حزمة تقف على سطر الاستيراد، بل هل يصمد الناتج إن أُعيد تشغيله بكل حجم جزء. وإن لم يصمد، لم تعد الحزمة تعني شيئًا.

ويحسن ذكر الحدود صراحةً، لأن مرشّح البثّ يغري بثقة أكبر مما يستحقّ. فهو يطابق صيغًا لا معانيَ: يلتقط رقم بطاقة ولا يلتقط التاريخ الطبي لعميل مكتوبًا نثرًا. ويعمل بعد أن يقرّر النموذج ما يقوله، فهو خط أخير لا خط أول. ولا يجعل أي مرشّح في أي مكتبة منظومةً ممتثلة لشيء؛ فالامتثال صفة المنظومة ومن يشغّلها. وما تكسبه من القاعدة أضيق من ذلك، ويستحقّ أن يُقتنى وحده: ناتج واحد سواء وصل قطعة واحدة أو أربعمئة.