أنبوب الخطاف

ملف precc-hook الثنائي هو جوهر PRECC. يقع بين Claude Code والصدفة، ويعالج كل أمر bash في أقل من 5 ميلي ثانية.

كيف يستدعي Claude Code الخطاف

يدعم Claude Code خطافات PreToolUse – برامج خارجية يمكنها فحص وتعديل مدخلات الأدوات قبل التنفيذ. عندما يكون Claude على وشك تشغيل أمر bash، يرسل JSON إلى precc-hook عبر stdin ويقرأ الاستجابة من stdout.

مراحل الأنبوب

Claude Code
    |
    v
+---------------------------+
| 1. Parse JSON stdin       |  Read the command from Claude Code
+---------------------------+
    |
    v
+---------------------------+
| 2. Skill matching         |  Query heuristics.db for matching skills (Pillar 4)
+---------------------------+
    |
    v
+---------------------------+
| 3. Directory correction   |  Resolve correct working directory (Pillar 1)
+---------------------------+
    |
    v
+---------------------------+
| 4. GDB check              |  Detect debug opportunities (Pillar 2)
+---------------------------+
    |
    v
+---------------------------+
| 5. RTK rewriting          |  Apply command rewrites for token savings
+---------------------------+
    |
    v
+---------------------------+
| 6. Emit JSON stdout       |  Return modified command to Claude Code
+---------------------------+
    |
    v
  Shell executes corrected command

مثال: إدخال وإخراج JSON

الإدخال (من Claude Code)

{
  "tool_input": {
    "command": "cargo build"
  }
}

يكتشف PRECC أن الدليل الحالي لا يحتوي على Cargo.toml، لكن ./myapp/Cargo.toml موجود.

الإخراج (إلى Claude Code)

{
  "hookSpecificOutput": {
    "updatedInput": {
      "command": "cd /home/user/projects/myapp && cargo build"
    }
  }
}

إذا لم تكن هناك حاجة للتعديل، يكون updatedInput.command فارغًا ويستخدم Claude Code الأمر الأصلي.

تفاصيل المراحل

المرحلة 1: تحليل JSON

يقرأ كائن JSON الكامل من stdin. يستخرج tool_input.command. إذا فشل التحليل، يخرج الخطاف فورًا ويستخدم Claude Code الأمر الأصلي (تصميم fail-open).

المرحلة 2: مطابقة المهارات

يستعلم قاعدة بيانات SQLite الاستدلالية عن المهارات التي يتطابق نمط تشغيلها مع الأمر. يتم التحقق من المهارات بترتيب الأولوية. يتم تقييم مهارات TOML المدمجة والمهارات المستخرجة.

المرحلة 3: تصحيح الدليل

لأوامر البناء (cargo، go، make، npm، python، إلخ)، يتحقق مما إذا كان ملف المشروع المتوقع موجودًا في الدليل الحالي. إذا لم يكن كذلك، يفحص الدلائل القريبة للعثور على أقرب تطابق ويضيف cd <dir> && في البداية.

يستخدم مسح الدليل فهرس نظام ملفات مخزنًا مؤقتًا مع TTL مدته 5 ثوانٍ للحفاظ على السرعة.

المرحلة 4: فحص GDB

إذا كان من المحتمل أن ينتج الأمر عطلًا (مثل تشغيل ملف ثنائي للتصحيح)، يمكن لـ PRECC اقتراح أو حقن أغلفة GDB لالتقاط مخرجات تصحيح منظمة بدلاً من سجلات الأعطال الخام.

المرحلة 5: إعادة كتابة RTK

يطبق قواعد RTK (مجموعة أدوات إعادة الكتابة) التي تختصر الأوامر المطولة وتقمع المخرجات المزعجة أو تعيد هيكلة الأوامر لكفاءة الرموز.

المرحلة 6: إصدار JSON

يُسلسل الأمر المعدل مرة أخرى إلى JSON ويكتبه إلى stdout. إذا لم يتم إجراء تغييرات، تشير المخرجات إلى Claude Code لاستخدام الأمر الأصلي.

الأداء

يكتمل الأنبوب بأكمله في أقل من 5 ميلي ثانية (p99). التحسينات الرئيسية:

• SQLite في وضع WAL للقراءات المتزامنة بدون قفل
• أنماط regex مترجمة مسبقًا لمطابقة المهارات
• عمليات مسح نظام الملفات المخزنة مؤقتًا (TTL مدته 5 ثوانٍ)
• لا توجد مكالمات شبكة في المسار الساخن
• Fail-open: أي خطأ يعود إلى الأمر الأصلي

اختبار الخطاف يدويًا

يمكنك استدعاء الخطاف مباشرة:

$ echo '{"tool_input":{"command":"cargo build"}}' | precc-hook
{"hookSpecificOutput":{"updatedInput":{"command":"cd /home/user/myapp && cargo build"}}}