مرکزی مواد پر جائیں
اے آئی ٹیوٹوریلز

fast-jev-compaction کے ساتھ Claude Code کا عین سیاق و سباق محفوظ رکھیں

fast-jev-compaction کو npm لائبریری یا Claude Code پلگ اِن کے طور پر انسٹال اور استعمال کرنے کا طریقہ سیکھیں۔ یہ ٹیوٹوریل Jev پر مبنی فیصلوں، کنفیگریشن کے اختیارات، کسٹم ٹرانسپورٹ سپورٹ، ناکامی کی صورتِ حال، اور اہم متن کو لفظ بہ لفظ محفوظ رکھتے ہوئے طویل ٹرانسکرپٹس کو محفوظ طریقے سے مختصر کرنے کی تکنیکوں کی وضاحت کرتا ہے۔

تقریباً 23 منٹ کا مطالعہ
fast-jev-compaction کے ساتھ Claude Code کا عین سیاق محفوظ رکھیں

fast-jev-compaction کیا کرتا ہے

fast-jev-compaction ایک npm لائبریری اور Claude Code پلگ اِن ہے جو طویل ایجنٹ ٹرانسکرپٹس کو خلاصے میں دوبارہ لکھے بغیر مختصر کرتا ہے۔ اس کے بجائے، یہ Jev ماڈل سے پرانی ٹول کالز اور ٹول نتائج کو اسکور کرنے کے لیے کہتا ہے، پھر قابلِ ترتیب حدوں کے مطابق انہیں برقرار رکھتا، مختصر کرتا یا حذف کر دیتا ہے۔

صارف اور اسسٹنٹ کا متن اصل ترتیب میں بعینہٖ برقرار رہتا ہے۔ صرف ٹول کالز اور ان کے متعلقہ نتائج حذف کیے جا سکتے ہیں۔ اس طرح روایتی خلاصہ سازی کے ذریعے عین پابندیاں، فائل پاتھس، کمانڈز اور خرابی کے پیغامات ضائع نہیں ہوتے۔

ریپوزٹری میں src/ کے تحت دوبارہ قابلِ استعمال پیکیج، اور hooks/ اور .claude-plugin/ کے تحت Claude Code فنکشن ہُک پلگ اِن، دونوں شامل ہیں۔

کمپیکشن کیسے کام کرتی ہے

  1. ہر tool_use کو tool_use_id کے ذریعے اس کے tool_result کے ساتھ جوڑا جاتا ہے۔

  2. پہلے پیغام اور تازہ ترین preserveRecentMessages پیغامات کی کالز کو پن کیا جاتا ہے، اس لیے ان میں تبدیلی نہیں کی جاتی۔

  3. مکمل گفتگو Jev کو پرانے سے نئے پیغام کی ترتیب میں پیش کی جاتی ہے۔ اس فیصلہ جاتی حالت میں ٹول نتائج کے مواد کو مختصر نوٹس سے بدل دیا جاتا ہے، جیسے ok, 4213 chars (omitted)، جبکہ ٹول اِن پٹس اور متن دستیاب رہتے ہیں۔

  4. ہر غیر پن شدہ کال کے لیے Jev دو سوالات کے جواب دیتا ہے: کیا اس کال کے بارے میں جاننا اب بھی اہم ہے، اور کیا مکمل نتیجہ بعینہٖ دستیاب رہنا ضروری ہے؟

  5. واپس آنے والے احتمالات کا موازنہ keepThreshold سے کیا جاتا ہے۔

  6. ٹرانسکرپٹ کو دوبارہ بنایا جاتا ہے، اس طرح کوئی بے جوڑ نتیجہ باقی نہیں رہتا۔

فیصلوں کے نتائج

  • اگر نتیجے کا اسکور حد تک پہنچ جائے، تو کال اور مکمل نتیجہ دونوں برقرار رہتے ہیں۔

  • اگر صرف کال کا اسکور حد تک پہنچے، تو کال برقرار رہتی ہے اور نتیجہ اس کے پہلے truncateHeadChars حروف تک مختصر کر کے، اس کے بعد ایک نوٹ شامل کیا جاتا ہے۔

  • اگر کوئی بھی اسکور حد تک نہ پہنچے، تو کال اور اس کا نتیجہ دونوں اکٹھے حذف کر دیے جاتے ہیں۔

خالی ہو جانے والے پیغامات حذف کر دیے جاتے ہیں۔ جن پیغامات میں تبدیلی کی ضرورت نہیں ہوتی، انہیں وہی آبجیکٹس واپس کیا جاتا ہے۔

بڑی ہسٹری کو Jev درخواستوں میں فِٹ کرنا

فیصلہ جاتی حالت کی تخمینی حدِ حجم بطورِ ڈیفالٹ 25000 ٹوکنز ہے۔ اگر اصل حالت بہت بڑی ہو، تو لائبریری Jev کو دکھائی جانے والی نمائندگی کو مرحلہ وار مختصر کرتی ہے۔ یہ ٹول اِن پٹس کو مختصر کرتی ہے، طویل متن کو سر اور آخر کے حصے رکھ کر مختصر کرتی ہے، پرانے پیغامات کو سمیٹتی ہے، پرانی کالز کو ایک سطری ریکارڈز تک محدود کرتی ہے، کال کے بغیر پرانے پیغامات کو چھوڑ دیتی ہے، اور صرف پرانی کالز والے پیغامات کے مسلسل سلسلوں کو یکجا کرتی ہے۔

یہ تبدیلیاں اس حالت پر اثر انداز ہوتی ہیں جو اسکورنگ کے لیے استعمال ہوتی ہے، آخری ٹرانسکرپٹ میں محفوظ متن پر نہیں۔ اگر حالت پھر بھی فِٹ نہ ہو سکے، تو کمپیکشن ایک خرابی پیدا کرتی ہے۔

سوالات کو بھی بیچز میں تقسیم کیا جاتا ہے تاکہ ہر حالت اور سوال پر مشتمل درخواست maxRequestTokens سے کم رہے، جس کی ڈیفالٹ قدر 30000 ہے۔ درخواستیں بیک وقت چلتی ہیں اور ان کے فیصلے یکجا کر دیے جاتے ہیں۔

npm لائبریری انسٹال کریں

پیکیج انسٹال کریں اور ماحول کے ذریعے TypeSafe API کلید فراہم کریں:

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

API کلید کو commit نہ کریں اور نہ ہی اسے براہِ راست کسی سورس فائل میں رکھیں۔

ڈیفالٹ کلائنٹ process.env.TYPESAFE_API_KEY پڑھتا ہے۔ API کال کرتے وقت آپ 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 قسم Claude Code کی SessionMessage کا ذیلی مجموعہ ہے، اس لیے 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: TypeSafe API key۔ ڈیفالٹ طور پر یہ TYPESAFE_API_KEY ہوتا ہے۔

  • model: Jev ماڈل کا نام۔ ڈیفالٹ jev-latest ہے۔

  • baseUrl: System One اینڈ پوائنٹ۔ ڈیفالٹ https://api.typesafe.ai/v1/systemone ہے۔

  • fetch: انجیکٹ کیا جانے والا fetch implementation، جو خاص طور پر ٹیسٹس میں مفید ہے۔

  • goal: جاری کام کی وضاحت جو state میں شامل کی جاتی ہے۔ ڈیفالٹ طور پر اس میں صارف کے آخری تین prompts شامل ہوتے ہیں۔

  • keepThreshold: کسی call یا مکمل result کو برقرار رکھنے کے لیے درکار کم از کم probability۔ ڈیفالٹ 0.5 ہے۔

  • preserveRecentMessages: نئے ترین پیغامات کی تعداد جن میں ترمیم نہیں کی جا سکتی۔ ڈیفالٹ 6 ہے؛ پہلا پیغام بھی ہمیشہ محفوظ رہتا ہے۔

  • maxStateTokens: decision state کے لیے اندازاً زیادہ سے زیادہ token حد۔ ڈیفالٹ 25000 ہے۔

  • maxRequestTokens: ایک request میں state اور questions کے لیے اندازاً زیادہ سے زیادہ حد۔ ڈیفالٹ 30000 ہے۔

  • truncateHeadChars: result کو مختصر کرتے وقت برقرار رکھے جانے والے ابتدائی حروف کی تعداد۔ ڈیفالٹ 300 ہے۔

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

زیادہ keepThreshold کے لیے برقرار رکھنے کی probabilities زیادہ مضبوط ہونی چاہییں، اس لیے tool activity کا زیادہ حصہ حذف ہو سکتا ہے۔ چونکہ probability اس بات کا ثبوت نہیں ہوتی کہ حذف کرنا محفوظ ہے، اس لیے threshold میں تبدیلیوں کو نمائندہ transcripts پر جانچیں۔

حسبِ ضرورت Jev transport استعمال کریں

اگر built-in TypeSafe client آپ کے ماحول کے لیے موزوں نہ ہو تو exported JevAsker interface کو implement کریں۔ اس میں ask(state, questions) method لازمی ہے۔ پھر compactMessages کے بجائے compact(messages, asker, options) کو call کریں۔

یہ package HTTP request body بنانے کے لیے buildJevRequest اور response validation کے لیے parseJevResponse بھی export کرتا ہے۔ مزید خصوصی integrations کے لیے نچلی سطح کے building blocks دستیاب ہیں:

  • collectToolCalls calls کو ان کے results کے ساتھ جوڑتا ہے۔

  • fitState configured size ceiling کے اندر state تیار کرتا ہے۔

  • batchCalls questions کو مختلف requests میں تقسیم کرتا ہے۔

  • decideCall scores کو keep، truncate، یا remove decision میں تبدیل کرتا ہے۔

  • applyDecisions message history کو دوبارہ بناتا ہے۔

Claude Code plugin انسٹال کریں

Plugin کے لیے Claude Code 2.1.274 یا اس کے بعد کا ورژن درکار ہے۔ Function hooks early-access feature ہیں، اس لیے انہیں ہر اس جگہ enable کریں جہاں Claude Code چلتا ہے۔ مثال کے طور پر، ~/.claude/settings.json میں environment settings شامل کریں:

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

Repository کو plugin marketplace کے طور پر شامل کریں اور plugin انسٹال کریں:

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

Installer thresholds اور truncateHeadChars جیسے options کے بارے میں پوچھتا ہے۔ API-key option کو ڈیفالٹ پر رہنے دیں تاکہ ماحول سے TYPESAFE_API_KEY استعمال ہو۔

Claude Code کو restart کریں یا چلائیں:

/reload-plugins

فعال ہونے کے بعد /compact اور automatic compaction دونوں Jev hook سے گزرتے ہیں۔ کامیاب replacement پر fast-jev-compaction: kept N/M messages, no summary (...) جیسا toast ظاہر ہوتا ہے۔ اگر Jev ناکام ہو جائے یا reduction ناکافی ہو تو hook، Claude Code کے built-in summary پر واپس چلا جاتا ہے۔

Plugin کو checkout سے براہِ راست چلائیں

آپ repository کو publish یا install کیے بغیر test کر سکتے ہیں:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .

یہ command repository کے root سے چلائیں۔

Advanced usage tips

فعال کام کو محفوظ رکھیں

جب حالیہ tool outputs کے دوبارہ استعمال کا امکان ہو تو preserveRecentMessages بڑھا دیں۔ ان پیغامات میں موجود calls pin ہو جاتے ہیں اور انہیں حذف یا مختصر نہیں کیا جا سکتا۔

واضح goal فراہم کریں

ڈیفالٹ goal صارف کے آخری تین prompts سے اخذ کیا جاتا ہے۔ طویل یا بدلتے ہوئے sessions کے لیے goal واضح طور پر set کرنے سے Jev کو جاری کام کی زیادہ واضح وضاحت مل سکتی ہے۔

Fallback policy طے کرنے کے لیے statistics استعمال کریں

ہر compacted result کو خودکار طور پر قبول کرنے کے بجائے result.stats اور reductionRatio(result) کا جائزہ لیں۔ مختصر sessions میں اصل transcript کی جگہ لینے کے لیے کافی reduction پیدا نہیں ہو سکتی۔

Errors کے لیے منصوبہ بنائیں

Compaction اس وقت throw کرتا ہے جب Jev ناکام ہو، malformed data واپس کرے، required key موجود نہ ہو، یا ایسی history موصول ہو جسے state limit کے اندر fit نہ کیا جا سکے۔ Library calls کو error handling میں wrap کریں اور ضرورت پڑنے پر original transcript محفوظ رکھیں یا کوئی دوسری compaction strategy استعمال کریں۔ Claude Code hook پہلے ہی اپنے built-in summary پر واپس چلا جاتا ہے۔

Request cost سمجھیں

ہر questions batch کے لیے مکمل fitted state دوبارہ بھیجی جاتی ہے۔ اس لیے state ceiling کے قریب history کو questions کے ہر چھوٹے group کے لیے ایک بڑی request درکار ہو سکتی ہے۔ Limits کو tune کرتے وقت result.stats میں request count کا جائزہ لیں۔

Network calls کے بغیر test کریں

Repository کے unit tests fake Jev implementation استعمال کرتے ہیں اور کبھی TypeSafe سے رابطہ نہیں کرتے۔ Custom JevAsker یا injected fetch implementation آپ کی application tests میں بھی یہی طریقہ اختیار کرنے میں مدد دے سکتی ہے۔

Development commands

Repository سے کام کرتے وقت dependencies انسٹال کریں اور دستیاب checks چلائیں:

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

demo کمانڈ لائیو نیٹ ورک چیک انجام دیتی ہے۔ ریپوزٹری میں demo/JevDemo کے اندر macOS SwiftUI اینیمیشن بھی شامل ہے۔ یہ پہلے سے تیار کردہ ٹرانسکرپٹ کے ذریعے کمپیکشن کو نمایاں کرتی ہے اور API کو کال نہیں کرتی:

demo/JevDemo/build.sh

اینیمیشن دوبارہ چلانے کے لیے ایپ میں اسپیس دبائیں۔

اہم حدود

  • صرف ٹول کالز اور نتائج کو ہٹایا یا مختصر کیا جا سکتا ہے۔ ٹیکسٹ پیغامات آؤٹ پٹ میں بغیر تبدیلی کے رہتے ہیں۔

  • ٹوکن کی تعداد ٹوکنائزر کے بجائے حروف کے نمونوں سے اخذ کردہ اندازے ہیں۔

  • Jev کے احتمالات اس بات کی ضمانت نہیں دیتے کہ کوئی نتیجہ حذف کرنے کے لیے محفوظ ہے، اگرچہ ضرورت پڑنے پر اسسٹنٹ حذف کی گئی ٹول کال دوبارہ چلا سکتا ہے۔

  • ہر درخواست کا بیچ مکمل حالت کو دوبارہ شامل کرتا ہے، جس سے ترتیب شدہ حد کے قریب موجود ہسٹریز کے لیے لاگت بڑھ سکتی ہے۔

نتیجہ

fast-jev-compaction، گفتگو کے خلاصوں کی وجہ سے ہونے والے معلوماتی نقصان کے ایک متبادل کے طور پر، صارف اور اسسٹنٹ کے متن کو محفوظ رکھتے ہوئے پرانی ٹول سرگرمی کو منتخب طور پر کم کرتا ہے۔ ایپلیکیشن کی سطح پر کنٹرول کے لیے npm API، خودکار انضمام کے لیے Claude Code پلگ اِن، اور کمپیکشن کو اپنے ورک فلو کے مطابق ڈھالنے کے لیے فراہم کردہ حدود، تحفظ کی ترتیبات، اعداد و شمار اور فال بیک رویے استعمال کریں۔