شاهد وأوقف وأرجِع: مراقبة وكيل البرمجة المباشر في Potato

ما الذي يميّز المراقبة المباشرة

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

وهذا يغيّر ما يمكنك فعله. فإذا بدأ الوكيل يسلك مساراً خاطئاً، أمكن للمعلّق أن يتدخل قبل أن يهدر وقته هناك. ويمكنه الإيقاف المؤقت ليقرأ diff بتمعّن قبل أن يمضي الوكيل، أو أن يرسل تعليمة بلغة عادية ليعيد توجيهه. وأكثر ما أراه مفيداً هو التراجع. فعند أي نقطة تحقق سابقة يمكنك الرجوع وترك الوكيل يجرّب مقاربة أخرى. وهذه الفروع هي نوع البيانات الذي يحتاج إليه تعلّم التفضيل.

ليس هذا بديلاً عن التعليق التوضيحي على التتبعات الساكنة، بل ينتج نوعاً آخر من البيانات. التعليق الساكن أفضل حين تريد كمّاً كبيراً منها بتكلفة يمكن توقعها. والمراقبة المباشرة أفضل حين تبحث عن بيانات موجّهة، أو تحاول فهم كيف يفشل الوكيل، أو تبني أزواج تفضيل من التفريع.

للاطلاع على مرجع الميزة الكامل، انظر الوثائق المصدرية.

تبث واجهة وكيل البرمجة المباشر إجراءات الوكيل في الوقت الفعلي، فتعرض فروق الكود ومخرجات الطرفية أثناء عمله:

مراقبة وكيل برمجة مباشر مع تصيير الـ diff ومخرجات الطرفية في الوقت الفعلي

ثلاث واجهات خلفية

يمنحك Potato ثلاث واجهات خلفية للمراقبة المباشرة. تشغّل كل واحدة منها وكيل برمجة في بيئة معزولة وتبث إجراءاته إلى الواجهة لحظة وقوعها.

Ollama (محلي بالكامل)

تعمل واجهة Ollama الخلفية على جهازك بالكامل، من دون مفاتيح API ومن دون نداءات شبكية. الجأ إليها حين تكون قاعدة الكود حساسة، أو حين تريد التجريب فقط من دون تكديس فاتورة API.

أولاً، ثبّت Ollama واجلب نموذجاً يدعم استخدام الأدوات:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
 
# Pull a coding-capable model
ollama pull qwen2.5-coder:32b
 
# Verify the model is available
ollama list

هيّئ Potato لاستخدام واجهة Ollama الخلفية:

# config.yaml
annotation_task_name: "Live Agent Observation - Ollama"
port: 8000
 
live_coding_agent:
  backend_type: ollama_tool_use
  ai_config:
    model: "qwen2.5-coder:32b"
    base_url: "http://localhost:11434"
    temperature: 0.2
    max_tokens: 4096
  working_dir: ./workspace       # Agent's working directory
  max_turns: 50
  sandbox_mode: container        # container (default) | bubblewrap | trusted
  sandbox_image: "python:3.11-slim"

Anthropic API (Claude مع استخدام الأدوات)

تتصل واجهة Anthropic API الخلفية بنماذج Claude مع استخدام الأدوات. تحصل على تفكير وتوليد كود أقوى مما تعطيه معظم النماذج المحلية، وفي المقابل تدفع ثمن نداءات API.

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# config.yaml
annotation_task_name: "Live Agent Observation - Claude"
port: 8000
 
live_coding_agent:
  backend_type: anthropic_tool_use
  ai_config:
    model: "claude-sonnet-4-20250514"
    max_tokens: 8192
    temperature: 0.1
  system_prompt: >
    You are a coding agent. You will be given a task description and
    access to a codebase. Use the provided tools to read files, make
    edits, and run commands to complete the task. Think step by step
    and verify your changes by running tests.
  working_dir: ./workspace
  max_turns: 50
  sandbox_mode: container
  sandbox_image: "python:3.11-slim"

Claude Agent SDK (قدرات Claude Code كاملة)

واجهة Claude Agent SDK الخلفية هي الأقدر بين الثلاث، إذ تأتي بمجموعة أدوات Claude Code كاملة وبسلوك مستقل. وهي تتطلب حزمة claude-agent-sdk.

# Install the Claude Agent SDK
pip install claude-agent-sdk

# config.yaml
annotation_task_name: "Live Agent Observation - Claude Agent SDK"
port: 8000
 
live_coding_agent:
  backend_type: claude_sdk
  ai_config:
    model: "claude-sonnet-4-20250514"
  working_dir: ./workspace
  max_turns: 50                  # Maximum number of agent turns
  sandbox_mode: container
  sandbox_image: "node:20-slim"

سير عمل التعليق التوضيحي

متى عمل الخادم، تمر جلسة المراقبة المباشرة بعدة مراحل.

بدء جلسة

يفتح المعلّق واجهة Potato فيرى حقل إدخال لوصف المهمة. ويلصق فيه أو يكتب المهمة التي ينبغي للوكيل إتمامها، مثل «أصلح الاختبار الفاشل في tests/test_parser.py الناتج عن صيغة التهيئة الجديدة» أو «أضف دعم الترقيم إلى نقطة النهاية /api/users».

# Start the server
potato start config.yaml -p 8000

ينقر المعلّق على Start Agent فيبدأ وكيل البرمجة عمله. ويظهر كل إجراء في الوقت الفعلي في لوحة CodingTraceDisplay.

مراقبة الوكيل وهو يعمل

مع تشغيل الوكيل، تظهر كل خطوة في عارض التتبع:

• خطوات التفكير تظهر ككتل رمادية قابلة للطي تعرض تفكير الوكيل.
• قراءات الملفات تظهر ككتل كود ملوّنة الصياغة مع أرقام الأسطر ومسار الملف.
• تحريرات الملفات تظهر كـ diffs موحّدة بإبراز أحمر/أخضر.
• أوامر الطرفية تظهر ككتل طرفية داكنة مع الأمر ومخرجاته ورمز الخروج.
• شجرة الملفات تتحدّث في الشريط الجانبي مع إنشاء الملفات أو تعديلها أو قراءتها.

يعرض مؤشر تقدّم في الأعلى رقم الخطوة الحالية والزمن المنقضي. وتُعرض حالة الوكيل بصيغة Thinking... أو Editing file... أو Running command... وما إليها.

عناصر التحكم بالإيقاف المؤقت والتعليمات

أثناء تشغيل الوكيل، يمكن للمعلّق التدخل من شريط التحكم:

Pause: يجمّد الوكيل بعد اكتمال خطوته الحالية. فلا ينتقل إلى الخطوة التالية حتى يُستأنف. استخدمه لتفحص diff أو مخرجات طرفية بتمعّن قبل أن يمضي الوكيل.

إرسال تعليمة: أثناء الإيقاف المؤقت (أو حتى أثناء التشغيل)، اكتب رسالة بلغة طبيعية تُحقن في سياق الوكيل. مثل «لا تعدّل مخطط قاعدة البيانات، استخدم migration بدلاً من ذلك» أو «راجع سجل الأخطاء في /var/log/app.log قبل إجراء أي تغيير».

Resume: يتابع تنفيذ الوكيل بعد الإيقاف المؤقت.

Stop: ينهي جلسة الوكيل تماماً. ويُحفظ المسار حتى هذه النقطة.

يمكن للمعلّقين تقييم عمل الوكيل باستخدام تعليق PRM إلى جانب عرض التتبع:

واجهة تعليق PRM لتوسيم الصحة على مستوى الخطوة إلى جانب تتبع البرمجة

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

نظام نقاط التحقق المبني على Git

يعتمد التراجع والتفريع وتصدير المسارات كلها على نظام نقاط التحقق، الذي يودع في git بعد كل تغيير يجريه الوكيل على الملفات.

كيف يعمل

عند بدء الجلسة، يهيّئ Potato مستودع git في مساحة العمل المعزولة، أو يستخدم المستودع الموجود فيها. وبعد كل تحرير ملف، يودع تلقائياً برسالة منظمة:

[potato-checkpoint] Step 7: Edit src/parser.py
- Modified lines 45-52
- Agent reasoning: Fix the regex pattern to handle escaped quotes

والنتيجة سجل إيداعات خطي يقابل خطوات المسار واحدة بواحدة. وتلتقط كل نقطة تحقق حالةَ مساحة العمل كاملة في تلك اللحظة.

# You can inspect checkpoints directly with git
cd workspace/
git log --oneline
 
# Output:
# f8a2c1d [potato-checkpoint] Step 12: Edit tests/test_parser.py
# 3b7e9f0 [potato-checkpoint] Step 10: Edit src/parser.py
# a1c4d8e [potato-checkpoint] Step 8: Edit src/parser.py
# 9e2f6b3 [potato-checkpoint] Step 5: Edit src/config.py
# 7d0a3c1 [potato-checkpoint] Step 0: Initial state

التراجع

انقر Rollback واختر أي نقطة تحقق سابقة من القائمة المنسدلة. يعيد Potato مساحة العمل إلى تلك الحالة بـ git checkout ويرجع عرض المسار ليطابقها، ثم يستأنف الوكيل من هناك بسياق مقتطع إلى تلك الخطوة.

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

تفريع المسارات

التفريع تراجعٌ يحتفظ بكلا المسارين. فحين تتراجع ويسلك الوكيل طريقاً مختلفاً، ينشئ Potato فرع git مسمّى ويتتبع المسارين معاً:

Step 0 → Step 1 → Step 2 → Step 3 → Step 4 (Branch A: original path)
                          ↘
                           Step 3' → Step 4' → Step 5' (Branch B: after rollback)

يمكنك التفريع من أي نقطة تحقق، فتبني شجرة مسارات كاملة. وهذا مفيد لتعلّم التفضيل، لأن كل زوج فروع هو أصلاً مقارنة موسومة. فأنت تراجعت لأنك حكمت بخطأ الفرع A، وهذا يجعل الفرع B هو المسار المفضل ابتداءً من نقطة التفريع.

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

صيغ التصدير

تنتج الجلسة المباشرة بيانات مسار مفصّلة، ويمكنك تصديرها بأشكال عدة بحسب ما تدرّب عليه.

تصدير المسارات الخطية

صدّر كل فرع بوصفه مساراً مستقلاً:

python -m potato.export \
  -c config.yaml \
  -f trajectory_correction \
  -o ./training_data/

{
  "session_id": "session_001",
  "branch": "branch-A",
  "task": "Fix the failing test in tests/test_parser.py",
  "steps": [
    {"step_idx": 0, "type": "file_read", "path": "tests/test_parser.py", "...": "..."},
    {"step_idx": 1, "type": "thinking", "content": "The test expects..."},
    {"step_idx": 2, "type": "file_edit", "path": "src/parser.py", "diff": "..."},
    {"step_idx": 3, "type": "bash_command", "command": "pytest tests/test_parser.py"}
  ],
  "human_interventions": [
    {"after_step": 2, "type": "instruction", "content": "Use a migration instead"}
  ],
  "rollback_from_step": null,
  "outcome": "resolved"
}

أزواج التفضيل من الفروع

صدّر أزواج الفروع بوصفها بيانات تفضيل لـ DPO أو RLHF:

المُصدِّر نفسه هو الذي يكتبها. ففي مجلد المخرجات يحمل الملف trajectory_dpo.jsonl مقارنات الفروع بوصفها أزواج تفضيل، إلى جانب trajectory_sft.jsonl وtrajectory_corrections.json.

python -m potato.export \
  -c config.yaml \
  -f trajectory_correction \
  -o ./training_data/

{
  "session_id": "session_001",
  "task": "Fix the failing test in tests/test_parser.py",
  "branch_point_step": 2,
  "branch_point_reason": "Agent started modifying the wrong file",
  "rejected_branch": "branch-A",
  "rejected_steps": [
    {"step_idx": 3, "type": "file_edit", "path": "src/wrong_file.py", "...": "..."},
    {"step_idx": 4, "type": "bash_command", "command": "pytest", "exit_code": 1}
  ],
  "chosen_branch": "branch-B",
  "chosen_steps": [
    {"step_idx": 3, "type": "file_edit", "path": "src/parser.py", "...": "..."},
    {"step_idx": 4, "type": "bash_command", "command": "pytest", "exit_code": 0}
  ]
}

وسوم PRM من المراقبة المباشرة

يمكنك ضم المراقبة المباشرة إلى توسيم PRM، لأن نقطة التراجع تكون عادةً خطوة الخطأ الأول:

python -m potato.export \
  -c config.yaml \
  -f coding_eval \
  -o ./training_data/ \
  --option types=prm

هنا تُوسم الخطوة التي تراجعت عنها بوصفها الخطأ الأول، وتُوسم خطوات الفرع الجديد بأنها صحيحة، لأنك قبلتها.

مجموعات بيانات مراجعة الأكواد

صدّر تعليمات المعلّقين وأسباب التراجع بوصفها بيانات تدريب لمراجعة الأكواد:

python -m potato.export \
  -c config.yaml \
  -f coding_eval \
  -o ./training_data/ \
  --option types=code_review

بداية سريعة كاملة

التسلسل كاملاً، من الصفر إلى جلسة Ollama عاملة:

# 1. Install Potato with live agent support
pip install potato-annotation[live-agents]
 
# 2. Install and start Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen2.5-coder:32b
 
# 3. Set up a workspace with a repo to work on
mkdir -p workspace/
git clone https://github.com/example/test-project workspace/repo
 
# 4. Create the config file
cat > config.yaml << 'YAML'
annotation_task_name: "Live Agent Observation"
port: 8000
 
live_coding_agent:
  backend_type: ollama_tool_use
  ai_config:
    model: "qwen2.5-coder:32b"
    base_url: "http://localhost:11434"
    temperature: 0.2
  working_dir: ./workspace/repo
  max_turns: 50
  sandbox_mode: trusted
 
annotation_schemes:
  - annotation_type: radio
    name: outcome
    description: "Final outcome"
    labels:
      - name: "resolved"
        text: "Task Fully Resolved"
      - name: "partial"
        text: "Partially Resolved"
      - name: "failed"
        text: "Failed"
 
  - annotation_type: text
    name: notes
    description: "Session Notes"
    placeholder: "Key observations about agent behavior..."
    label_requirement:
      required: false
 
output_annotation_dir: "./output/"
export_annotation_format: jsonl
 
user_config:
  allow_all_users: false
  users:
    - "observer1"
YAML
 
# 5. Start Potato
potato start config.yaml -p 8000
 
# 6. Open http://localhost:8000 in your browser

بعد تسجيل الدخول، الصق مهمة مثل «أضف التحقق من المدخلات إلى نقطة النهاية POST على /api/users» وانقر Start Agent. راقبه وهو يعمل، وأوقفه مؤقتاً حين يبدو شيء ما في غير محله، وأرسل تعليمات لتوجيهه، وتراجع لتجرّب مقاربات أخرى. وحين تنتهي، قيّم النتيجة ودوّن ملاحظاتك.

ممارسات مفيدة

ابدأ بمهام واضحة ومحدودة النطاق. أفضل نطاق هو عمل يستغرق من الوكيل 5 إلى 15 دقيقة. فما هو أقصر من ذلك لا ينتج مساراً يستحق التعليق، وما هو أطول بكثير يرهق المعلّق.

أبقِ العزل مفعّلاً في الإنتاج. sandbox_mode: container هو الإعداد الافتراضي ويُبقي الوكيل بعيداً عن نظامك المضيف، وbubblewrap هو البديل الأخف على Linux. أما trusted فيشغّل نداءات أدوات الوكيل مباشرة على الجهاز، وهذا معقول فقط أثناء التطوير مع نموذج تثق به.

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

قارن بين واجهات خلفية متعددة. شغّل المهام نفسها عبر Ollama وAnthropic API وClaude Agent SDK للحصول على بيانات تفضيل بين الوكلاء. وبما أن قسم الواجهة الخلفية وحده هو ما يتغير في التهيئة، فالإعداد سهل.

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