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

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

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

الخطاف	وقت التشغيل	الحظر	سلوك Stdout
`SessionStart`	مرة واحدة عند بدء الجلسة	لا	يُدرج كسياق
`UserPromptSubmit`	في كل مرة تُرسل فيها prompt	نعم (رمز الخروج `2`)	يُدرج كسياق
`PreToolUse`	قبل تشغيل أداة مطابقة	نعم (رمز الخروج `2`)	يُتجاهل
`PostToolUse`	بعد اكتمال أداة مطابقة	لا	يُتجاهل
`Stop`	عند توقف الوكيل	لا	يُتجاهل

الإعداد

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

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

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

مخطط الخطاف

{
  "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. تبدأ الجلسة دائمًا. وتُسجَّل رموز الخروج الأخرى غير الصفرية وتُتجاهل.

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

مخطط Stdin

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

مثال على الحمولة

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

Stdout: يُكتب في سياق النموذج إلى جانب prompt.

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

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

مخطط 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 بأن الأداة حُظرت ويواصل الجلسة.

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

مخطط 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).

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

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

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

البدء

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

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

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

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

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

ابدأ جلسة Bob واستخدم الأداة المطابقة. تحقّق من ~/.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')"

حظر prompt

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

#!/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 session"

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

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

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

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

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

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

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

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

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

في هذه الصفحة