شغّل أوامر shell تلقائيًا في نقاط رئيسية من جلسة Bob Shell لتسجيل النشاط أو إضافة السياق أو حظر الإجراءات وفقًا لمنطقك.

تتيح لك خطافات دورة الحياة تشغيل أوامر shell في نقاط محددة من جلسة Bob Shell. استخدمها لتسجيل النشاط، أو إضافة السياق إلى النموذج، أو ضبط الإجراءات أو حظرها، أو بدء أتمتة لاحقة، وكل ذلك من دون تعديل Bob Shell نفسه.

الخطافات المدعومة

الخطاف	وقت التشغيل	الحظر	سلوك stdout
`SessionStart`	مرة واحدة عند بدء جلسة	لا	يُضاف كسياق
`UserPromptSubmit`	في كل مرة ترسل فيها موجّهًا	نعم، برمز الخروج `2`	يُضاف كسياق
`PreToolUse`	قبل تشغيل أداة مطابقة	نعم، برمز الخروج `2`	يُتجاهل
`PostToolUse`	بعد اكتمال أداة مطابقة	لا	يُتجاهل
`Stop`	عند توقف الوكيل	لا	يُتجاهل

الإعداد

تُعرَّف الخطافات تحت المفتاح hooks في settings.json. يدمج Bob Shell الخطافات من موقعين:

النطاق	الملف
عام (كل مساحات العمل)	`~/.bob/settings/settings.json`
مساحة العمل (المشروع الحالي)	`.bob/settings.json`

تعمل الخطافات العامة دائمًا. وتُدمج خطافات مساحة العمل فوق الخطافات العامة ولا تنطبق إلا على المشروع الحالي.

مهم:

لا تعمل خطافات مساحة العمل إلا في المجلدات الموثوقة. إذا كان المجلد الحالي غير موثوق، فلن يُحمَّل ملف .bob/settings.json وستُتخطى خطافات مستوى مساحة العمل بصمت. لا تتأثر الخطافات العامة في ~/.bob/settings/settings.json بثقة المجلد.

للاطلاع على كيفية تحديد موقع ملفات الإعدادات وتحميلها، راجع تهيئة Bob Shell.

مخطط الخطاف

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^write_file$",
        "hooks": [
          {
            "type": "command",
            "command": "sh .bob/hooks/check.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

حقول الإعداد

الحقل	النوع	القيمة الافتراضية	الوصف
`type`	`"command"`	(لا يوجد)	مطلوب. لا يُدعم سوى `command`.
`command`	string	(لا يوجد)	مطلوب. أمر shell المطلوب تشغيله. يُشغَّل عبر `sh -c` على macOS/Linux، وعبر `cmd /c` على Windows.
`matcher`	string	(لا يوجد)	اختياري. تعبير regex يُطابق اسم الأداة (`PreToolUse` و`PostToolUse` فقط). احذفه لمطابقة جميع الأدوات.
`timeout`	number	`10`	عدد الثواني قبل إيقاف الخطاف. اضبطه على `0` لتعطيل المهلة.

مرجع الخطافات

يعمل مرة واحدة عند بدء جلسة جديدة، قبل الدور الأول.

مخطط stdin

{
  "event": "string",
  "session_id": "string"
}

حمولة مثال

{
  "event": "SessionStart",
  "session_id": "ses_01abc123"
}

stdout: يُكتب في سياق النموذج بوصفه معلومات إضافية عن الجلسة.

الحظر: لا يُدعم رمز الخروج 2. تبدأ الجلسة دائمًا. تُسجَّل رموز الخروج الأخرى غير الصفرية وتُتجاهل.

يعمل في كل مرة ترسل فيها موجّهًا، قبل إرساله إلى النموذج.

مخطط stdin

{
  "event": "string",
  "session_id": "string",
  "prompt": "string"
}

حمولة مثال

{
  "event": "UserPromptSubmit",
  "session_id": "ses_01abc123",
  "prompt": "Refactor the auth module"
}

stdout: يُكتب في سياق النموذج إلى جانب الموجّه.

الحظر: يمنع رمز الخروج 2 إرسال الموجّه. يعرض Bob Shell خطأً ولا يُرسَل الموجّه.

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

مخطط stdin

{
  "event": "string",
  "session_id": "string",
  "tool": "string",
  "input": "object"
}

حمولة مثال

{
  "event": "PreToolUse",
  "session_id": "ses_01abc123",
  "tool": "write_file",
  "input": {
    "path": "src/index.ts",
    "content": "..."
  }
}

stdout: يُتجاهل.

الحظر: يمنع رمز الخروج 2 تشغيل الأداة. يبلغ Bob Shell بأن الأداة محظورة ويتابع الجلسة.

يعمل بعد اكتمال أداة مطابقة، سواء نجحت أم لا.

مخطط stdin

{
  "event": "string",
  "session_id": "string",
  "tool": "string",
  "input": "object",
  "output": "string"
}

حمولة مثال

{
  "event": "PostToolUse",
  "session_id": "ses_01abc123",
  "tool": "write_file",
  "input": {
    "path": "src/index.ts",
    "content": "..."
  },
  "output": "File written successfully"
}

stdout: يُتجاهل.

الحظر: ليس لرمز الخروج 2 أي تأثير. تكون الأداة قد شُغّلت بالفعل.

يعمل عند توقف الوكيل، بعد اكتمال الدور الأخير.

مخطط stdin

{
  "event": "string",
  "session_id": "string"
}

حمولة مثال

{
  "event": "Stop",
  "session_id": "ses_01abc123"
}

stdout: يُتجاهل.

الحظر: ليس لرمز الخروج 2 أي تأثير. تكون الجلسة قد انتهت بالفعل.

رموز الخروج والحظر

رمز الخروج	السلوك	ينطبق على
`0`	نجاح: تم تشغيل الخطاف بلا مشكلة	جميع الخطافات
`2`	حظر: أوقف الإجراء الحالي	`UserPromptSubmit`، `PreToolUse`
أي قيمة أخرى غير صفرية	فشل غير حاجب: يُسجَّل ويُتجاهل	جميع الخطافات

ملاحظة:

لا يدعم الحظر إلا UserPromptSubmit وPreToolUse. ويُعامل رمز الخروج 2 من SessionStart أو PostToolUse أو Stop على أنه فشل غير حاجب.

تفاصيل الأوامر

دليل العمل: تعمل الأوامر من دليل عمل المهمة، أي المجلد الذي يعمل فيه Bob Shell.

المهلة الافتراضية: 10 ثوانٍ. تجاوزها لكل خطاف باستخدام الحقل timeout. اضبط timeout على 0 لتعطيل المهلة تمامًا.

Stderr: يُكتب في سجلات Bob Shell، لكنه لا يؤثر في نتيجة الخطاف.

Shell: تُشغّل الأوامر عبر sh -c على macOS وLinux، وعبر cmd /c على Windows.

البدء

افتح ملف إعداداتك العامة أو أنشئه في ~/.bob/settings/settings.json.

أضف مفتاح hooks مع الخطاف الذي تريد استخدامه. يشغّل المثال التالي سكريبتًا قبل كل استدعاء لـ write_file:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^write_file$",
        "hooks": [
          {
            "type": "command",
            "command": "sh ~/.bob/hooks/log-write.sh"
          }
        ]
      }
    ]
  }
}

أنشئ ملف السكريبت. يسجل هذا السكريبت البسيط حمولة JSON الواردة:

#!/bin/sh
# ~/.bob/hooks/log-write.sh
cat >> ~/.bob/hooks/write-log.txt

ابدأ جلسة Bob Shell واستخدم الأداة المطابقة. تحقّق من ~/.bob/hooks/write-log.txt للتأكد من تشغيل الخطاف وكتابة الحمولة.

أمثلة

تسجيل جميع مدخلات الخطافات

اكتب stdin لكل خطاف في ملف لأغراض تصحيح الأخطاء:

#!/bin/sh
# Append the incoming JSON payload with a timestamp
echo "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> ~/.bob/hooks/debug.log
cat >> ~/.bob/hooks/debug.log
echo "" >> ~/.bob/hooks/debug.log

اضبط هذا تحت أي خطاف:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{ "type": "command", "command": "sh ~/.bob/hooks/debug.sh" }]
      }
    ]
  }
}

إضافة سياق الجلسة

أعد نصًا من خطاف SessionStart لإضافته إلى سياق النموذج:

#!/bin/sh
# Output project metadata for the model to use
echo "Project: $(basename $PWD)"
echo "Git branch: $(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'unknown')"
echo "Node version: $(node --version 2>/dev/null || echo 'not installed')"

حظر موجّه

اخرج بالرمز 2 من خطاف UserPromptSubmit لمنع إرسال موجّه:

#!/bin/sh
# Block prompts containing the word "delete"
PROMPT=$(cat | python3 -c "import sys,json; print(json.load(sys.stdin)['prompt'])")
case "$PROMPT" in
  *delete*|*DELETE*)
    echo "Prompt blocked: contains 'delete'" >&2
    exit 2
    ;;
esac

حظر أداة مطابقة

اخرج بالرمز 2 من خطاف PreToolUse لمنع تشغيل أداة محددة:

#!/bin/sh
# Block write_file operations on files outside the src/ directory
PATH_VAL=$(cat | python3 -c "import sys,json; print(json.load(sys.stdin)['input'].get('path',''))")
case "$PATH_VAL" in
  src/*) ;;
  *)
    echo "Blocked: writes outside src/ are not allowed" >&2
    exit 2
    ;;
esac

تشغيل أتمتة لاحقة من `Stop`

استخدم Stop لبدء التنظيف أو إعداد تقرير بعد انتهاء جلسة:

#!/bin/sh
# Commit any staged changes after the agent finishes
cd "$PWD"
git diff --cached --quiet || git commit -m "chore: auto-commit from Bob Shell session"

القيود الحالية

لا يدعم هذا الإصدار إلا خطافات command وأنواع الخطافات الخمسة المذكورة أعلاه. ولا يتوفر ما يلي بعد:

أنواع الخطافات غير command: لا تُدعم خطافات الدوال وخطافات السكريبتات المضمنة وما شابهها.

الخطافات المجدولة: لا يمكن ضبط الخطافات للتشغيل بمؤقت أو استجابةً لحدث خارجي.

إعادة كتابة المدخلات: لا تستطيع الخطافات تعديل الموجّه أو إدخال الأداة قبل وصوله إلى النموذج.

التشغيل المعزول: تعمل الخطافات بصلاحيات المستخدم الكاملة؛ ولا يُطبَّق عليها عزل.

قياس مخصص للخطافات: لا يُتتبع نشاط الخطافات منفصلًا في تحليلات الجلسة.

الحظر من PostToolUse أو Stop: ليس لرمز الخروج 2 أي تأثير على هذين الخطافين.

خطافات دورة الحياة

في هذه الصفحة