حافظ على كونطكست Claude Code كيف ما هو مع fast-jev-compaction

شنو كيدير fast-jev-compaction

fast-jev-compaction هي مكتبة npm وبلوغين ديال Claude Code كتنقص من طول السجلات الطويلة ديال الوكلاء بلا ما تعاود تكتبها فشكل ملخّص. عوض هاد الشي، كاتطلب من موديل Jev ينقّط استدعاءات الأدوات القديمة والنتائج ديالها، ومن بعد كاتخليها، كتقصّرها، ولا كتحيدها حسب العتبات القابلة للضبط.

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

المستودع فيه الحزمة القابلة لإعادة الاستعمال تحت src/، وزايد عليها بلوغين ديال Claude Code مبني على function-hook تحت hooks/ و.claude-plugin/.

كيفاش كيخدم الاختصار

1. كل tool_use كيتربط مع tool_result ديالو باستعمال tool_use_id.

2. الاستدعاءات اللي كاينة فالرسالة الأولى، والرسائل الجديدة بعدد preserveRecentMessages، كيتثبتو وما كيتبدل فيهم والو.

3. المحادثة كاملة كتتعرض على Jev من الأقدم حتى للأحدث. فحالة اتخاذ القرار، محتويات نتائج الأدوات كتتعوض بملاحظات قصيرة بحال ok, 4213 chars (omitted)، بينما مدخلات الأدوات والنص كيبقاو متاحين.

4. بالنسبة لكل استدعاء ماشي مثبت، Jev كيجاوب على جوج ديال الأسئلة: واش مازال مهم نعرفو بلي هاد الاستدعاء وقع، وواش خاص النتيجة كاملة تبقى متاحة حرفياً.

5. الاحتمالات اللي كترجع كتتقارن مع keepThreshold.

6. السجل كيتعاود يبنى بلا ما تبقى شي نتيجة بلا الاستدعاء ديالها.

نتائج القرار

• إلى وصل تنقيط النتيجة للعتبة، كيتحتافظ بالاستدعاء وبالنتيجة الكاملة.

• إلى غير تنقيط الاستدعاء هو اللي وصل للعتبة، كيبقى الاستدعاء وكتتقصر النتيجة لأول truncateHeadChars حرف، ومن بعد كتزاد ملاحظة.

• إلى حتى واحد من التنقيطين ما وصلش للعتبة، كيتحيد الاستدعاء والنتيجة ديالو بجوج.

الرسائل اللي كتولي خاوية كيتحيدو. والرسائل اللي ما محتاجاش تبديلات كترجع بنفس الكائنات.

إدخال السجلات الكبيرة فطلبات Jev

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

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

الأسئلة حتى هي كتتقسم على دفعات باش كل طلب فيه الحالة والسؤال يبقى تحت maxRequestTokens، اللي القيمة الافتراضية ديالو هي 30000. الطلبات كيتنفذو بالتوازي، ومن بعد كتندمج القرارات ديالها.

تثبيت مكتبة npm

ثبّت الحزمة ووفّر مفتاح API ديال TypeSafe من خلال البيئة:

npm install fast-jev-compaction
export TYPESAFE_API_KEY=...

ما تديرش مفتاح API فـ commit وما تحطوش مباشرة فشي ملف ديال المصدر.

العميل الافتراضي كيقرا process.env.TYPESAFE_API_KEY. وتقدر حتى تعطي الخيار apiKey ملي كتستعمل الواجهة البرمجية.

اختصر سجل المحادثة

استورد compactMessages، وجد سجل المحادثة، ودوز أي خيارات مختلفة على القيم الافتراضية:

import {
  compactMessages,
  reductionRatio,
  type Message,
} from 'fast-jev-compaction';

const transcript: Message[] = [
  {
    role: 'user',
    text: 'Fix the failing test. Never edit src/generated.',
    toolUses: [],
  },
  {
    role: 'assistant',
    text: '',
    toolUses: [
      {
        tool_use_id: 'toolu_1',
        tool: 'Read',
        input: { file_path: 'src/a.ts' },
      },
    ],
  },
  {
    role: 'user',
    text: '',
    toolUses: [],
    toolResults: [
      { tool_use_id: 'toolu_1', text: '…file contents…' },
    ],
  },
];

const result = await compactMessages(transcript, {
  preserveRecentMessages: 4,
});

console.log(result.messages);
console.log(result.decisions);
console.log(result.stats);

النوع المصدَّر Message هو مجموعة فرعية من SessionMessage ديال Claude Code، وهاد الشي كيخلي سجلات جلسات Claude Code تدوز مباشرة للحزمة.

تأكد واش الاختصار كان مفيد

الحزمة كتصدر reductionRatio، اللي يقدر يعاون التطبيق يقرر واش يستعمل السجل المختصر:

const result = await compactMessages(transcript);

if (reductionRatio(result) < 0.25) {
  // Keep the original transcript or use another fallback.
} else {
  // Continue with result.messages.
}

إحصائيات النتيجة فيها عدد الرسائل والحروف قبل الاختصار ومن بعدو، وعدد القرارات مجمّع حسب السبب، والحجم التقريبي للحالة، والمرحلة المستعملة للإدخال، وعدد طلبات Jev.

ضبط طريقة الاختصار

الخيارات الرئيسية هي:

• apiKey: مفتاح API ديال TypeSafe. القيمة الافتراضية ديالو هي TYPESAFE_API_KEY.

• model: سميّة موديل Jev. القيمة الافتراضية هي jev-latest.

• baseUrl: نقطة الولوج ديال System One. القيمة الافتراضية هي https://api.typesafe.ai/v1/systemone.

• fetch: تطبيق fetch قابل للحقن، ومفيد خصوصاً فالاختبارات.

• goal: وصف المهمة الجارية اللي كيتضمّن فالحالة. افتراضياً، كيستعمل آخر ثلاثة ديال الطلبات ديال المستخدم.

• keepThreshold: أقل احتمال مطلوب باش يتخلى على استدعاء ولا على النتيجة كاملة. القيمة الافتراضية هي 0.5.

• preserveRecentMessages: عدد الرسائل الجديدة اللي ما يمكنش يتبدلو. القيمة الافتراضية هي 6؛ والرسالة اللولة ديما محفوظة حتى هي.

• maxStateTokens: السقف التقديري ديال التوكنات لحالة القرار. القيمة الافتراضية هي 25000.

• maxRequestTokens: السقف التقديري للحالة زائد الأسئلة فطلب واحد. القيمة الافتراضية هي 30000.

• truncateHeadChars: عدد الحروف اللولة اللي كيتحتافظ بها ملي كتتقصّر نتيجة. القيمة الافتراضية هي 300.

const result = await compactMessages(transcript, {
  goal: 'Fix the test without editing generated files',
  keepThreshold: 0.6,
  preserveRecentMessages: 8,
  truncateHeadChars: 500,
});

إلى طلّعتي keepThreshold، غادي يطلب احتمالات أقوى للاحتفاظ، وبالتالي يقدر يحيد نشاط أكثر ديال الأدوات. وحيت الاحتمال ماشي دليل على أن الحذف آمن، قيّم تغييرات العتبة باستعمال نصوص محادثات كتمثّل الاستعمال الحقيقي.

استعمل نقل مخصص ديال Jev

إلى ما ناسَبكش عميل TypeSafe المدمج مع البيئة ديالك، طبّق الواجهة المصدّرة JevAsker. خاصها طريقة ask(state, questions). من بعد عيّط لـ compact(messages, asker, options) بلاصة compactMessages.

الحزمة كتصدّر حتى buildJevRequest باش تبني جسم طلب HTTP، وparseJevResponse باش تتحقق من الاستجابة. وكاينين مكوّنات منخفضة المستوى لتكاملات أكثر تخصصاً:

• collectToolCalls كيربط الاستدعاءات بالنتائج ديالها.

• fitState كيحضّر حالة داخل سقف الحجم المكوَّن.

• batchCalls كيقسم الأسئلة على الطلبات.

• decideCall كيحوّل النقط لقرار: الاحتفاظ، التقصير، ولا الحذف.

• applyDecisions كيعيد بناء تاريخ الرسائل.

ثبّت إضافة Claude Code

الإضافة كتحتاج Claude Code بالإصدار 2.1.274 ولا أحدث. خطافات الدوال ميزة فالولوج المبكر، لذلك فعّلها فين ما كيشغّل Claude Code. مثلاً، زِد إعدادات البيئة فـ ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1",
    "TYPESAFE_API_KEY": "<your key>"
  }
}

زِد المستودع كسوق ديال الإضافات وثبّت الإضافة:

claude plugin marketplace add tamaratran/fast-jev-compaction
claude plugin install fast-jev-compaction@fast-jev-compaction

المثبّت غادي يطلب اختيارات بحال العتبات وtruncateHeadChars. خلّي اختيار مفتاح API بالقيمة الافتراضية باش يستعمل TYPESAFE_API_KEY من البيئة.

عاود شغّل Claude Code ولا نفّذ:

/reload-plugins

من بعد التفعيل، كل من /compact والتقصير التلقائي غادي يدوز من خطاف Jev. التعويض الناجح كيظهر إشعار بحال fast-jev-compaction: kept N/M messages, no summary (...). إلا فشل Jev ولا كان التقليل غير كافي، الخطاف كيرجع للملخّص المدمج ديال Claude Code.

شغّل الإضافة مباشرة من نسخة محلية

تقدر تجرّب المستودع بلا ما تنشرو ولا تثبّتو:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .

نفّذ هاد الأمر من جذر المستودع.

نصائح للاستعمال المتقدم

حمي الخدمة الجارية

طلّع preserveRecentMessages ملي تكون مخرجات الأدوات الأخيرة غالباً غادي يعاود استعمالها. الاستدعاءات اللي فهاد الرسائل كتكون مثبّتة وما يمكنش تتحيد ولا تتقصّر.

عطي هدف دقيق

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

استعمل الإحصائيات باش تحدد سياسة الرجوع

فحص result.stats وreductionRatio(result) بلاصة ما تقبل تلقائياً كل نتيجة مقصّرة. الجلسات القصيرة يمكن ما تنقصش بما يكفي باش يبرّر تعويض نص المحادثة الأصلي.

خطط للأخطاء

التقصير كيرمي خطأ ملي كيفشل Jev، ولا كيرجع بيانات غير صالحة، ولا كينقص مفتاح مطلوب، ولا كيتوصل بتاريخ ما يمكنش يتحط داخل حدّ الحالة. دير معالجة للأخطاء حول استدعاءات المكتبة، وخلي نص المحادثة الأصلي ولا استعمل استراتيجية أخرى للتقصير ملي يكون ضروري. خطاف Claude Code كيرجع أصلاً للملخّص المدمج ديالو.

فهم تكلفة الطلبات

الحالة كاملة من بعد ما كتتوافق مع الحجم كتعاود فكل مجموعة ديال الأسئلة. لذلك، تاريخ قريب من سقف الحالة يقدر يحتاج طلباً كبيراً واحداً لكل مجموعة صغيرة ديال الأسئلة. راجع عدد الطلبات فـ result.stats ملي كتضبط الحدود.

اختبر بلا طلبات للشبكة

اختبارات الوحدات ديال المستودع كتستعمل تطبيق Jev مزيّف وما كتتاصلش بـ TypeSafe نهائياً. وتطبيق مخصص ديال JevAsker ولا تطبيق fetch محقون يقدر يدعم نفس الطريقة فاختبارات التطبيق ديالك.

أوامر التطوير

ملي كتخدم من المستودع، ثبّت الاعتماديات وشغّل الفحوصات المتاحة:

npm install
npm run typecheck
npm test
npm run build
npm run validate:plugin
TYPESAFE_API_KEY="$(cat ~/.typesafe_key)" npm run demo

الأمر ديال demo كيدير التحقق المباشر من الشبكة. المستودع فيه حتى هو أنيميشن ديال macOS SwiftUI فـ demo/JevDemo. كيجسّد عملية الضغط باستعمال نصّ مسجّل، وما كيتاصلش بالـ API:

demo/JevDemo/build.sh

ضغط على المسافة فالتطبيق باش تعاود تشغّل الأنيميشن.

قيود مهمّة

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

• أعداد التوكنات غير تقديرات محسوبة انطلاقاً من أنماط الحروف، وماشي من tokenizer.

• الاحتمالات ديال Jev ما كتضمنش باللي شي نتيجة آمنة للحذف، مع أن المساعد يقدر يعاود ينفّذ استدعاء أداة تحيّد ملي كيكون ضروري.

• كل دفعة ديال الطلبات كتعاود الحالة كاملة، وهاد الشي يقدر يزيد فالتكلفة بالنسبة للتواريخ اللي قراب للسقف المضبوط.

الخلاصة

‏fast-jev-compaction كيوفّر بديل لملخّصات المحادثات اللي كتضيّع المعلومات، بحيث كيحافظ على نصوص المستخدم والمساعد وكيحيد بشكل انتقائي نشاط الأدوات القديم. استعمل npm API للتحكم على مستوى التطبيق، وClaude Code plugin للدمج التلقائي، واستافد من العتبات، وإعدادات الحفاظ، والإحصائيات، والسلوك الاحتياطي الموفّرين باش تضبط الضغط حسب طريقة خدمتك.