التطوير مع وكلاء الذكاء الاصطناعي الأدلة التقنية

ابن وكيل برمجة Coding Agent بيدك: الحلقة والأدوات

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

ابن وكيل برمجة Coding Agent بيدك: الحلقة والأدوات

إذا كنت تستعمل وكيل برمجة Coding Agent كل يوم، فأنت تعرف ما يفعله من الخارج: يقرأ الملفات، ويعدل سطراً، ويشغل الاختبارات Tests، ثم يقول إنه انتهى. وقد شرحنا في مقال بيئة تشغيل الوكيل Harness الأجزاء التي تحيط بالنموذج: الحلقة Loop، والصلاحيات Permissions، والصندوق المعزول Sandbox، والميزانية Budget، ورأينا كل جزء يمنع ويتوقف بمخرجات حقيقية. ولكن معرفة الأجزاء شيء، وأن تبني منها وكيلاً يصلح مشكلة Issue حقيقية في مستودع Repository شيء آخر، لأنك عندها سوف تواجه أسئلة لا تظهر في الشرح: بأي شكل يكتب النموذج طلبه؟ وكيف يعدل سطراً واحداً دون أن يعيد كتابة الملف؟ ومن يقرر أن العمل انتهى فعلاً؟ وكيف تعرف أن الإصلاح صحيح وليس مجرد اختبارات خضراء؟

ولذلك سوف نبني في هذا المقال وكيل برمجة كاملاً بأيدينا، اسمه minicode، في ملف Python واحد دون أي مكتبة خارجية، ونشغله على نموذجين محليين صغيرين في Ollama على معالج عادي CPU، ونعطيه مشكلات حقيقية في مستودعات صغيرة، ثم نحكم على عمله باختبارات مخفية Hidden Tests لم يرها. والهدف ليس أن ننافس الأدوات التجارية، وإنما أن ترى من الداخل لماذا تبدو هذه الأدوات بالشكل الذي تبدو به، فكل قرار في التصميم سوف تراه هنا وهو يفشل أولاً، ثم نصلحه ونرى أثر الإصلاح بالأرقام.

في هذا المقال سوف نتناول:

  • الفرق بين بيئة التشغيل وبين وكيل البرمجة، وما الذي يضيفه الوكيل فوقها.
  • تصميم الأدوات Tools كواجهة بين النموذج والحاسوب Agent-Computer Interface، ولماذا لا نعطي الوكيل طرفية Terminal كاملة.
  • الكود كاملاً: الحلقة، والأدوات، وفحص المسارات، والتوقف، والفرق Diff في النهاية.
  • ثلاثة إصدارات من الوكيل، وما الذي أفشل كل إصدار، وكيف أصلحناه.
  • الرد المنظم Structured Outputs أم استدعاء الأدوات الأصلي Native Tool Calling، وأيهما يناسب أي نموذج.
  • لماذا نحكم على الوكيل باختبارات لا يراها، وماذا يحدث إذا سمحنا له أن يقرر بنفسه أنه انتهى.

ما الذي يضيفه وكيل البرمجة فوق بيئة التشغيل؟

بيئة التشغيل في مقالها كانت عامة: أعطيناها أداة لتشغيل أي أمر، وقواعد تسمح وتمنع، وصندوقاً معزولاً حول كل أمر. وهذا مناسب لشرح الأجزاء، ولكن وكيل البرمجة له مهمة أضيق وأوضح: أن يأخذ وصف مشكلة كتبه إنسان، ويجد الكود المتعلق بها، ويغيره أقل تغيير ممكن، ويثبت بالاختبارات أن التغيير يعمل، ثم يسلمك الفرق Diff لتراجعه. ولهذه المهمة الضيقة أربعة أجزاء لا تحتاجها بيئة تشغيل عامة:

  1. خريطة المستودع Repository Map: النموذج لا يرى مشروعك، فإذا لم تخبره بالملفات والدوال الموجودة فسوف يخمن أسماء ملفات لا وجود لها، كما سوف نرى في أول تشغيل.
  2. أداة تعديل جيدة: إعادة كتابة الملف كاملاً مكلفة وخطيرة، والتعديل بالسطر ورقمه يخطئ عندما يتغير الملف، والطريقة التي استقرت عليها أغلب الأدوات هي استبدال نص محدد بنص آخر بشرط أن يكون النص الأول موجوداً مرة واحدة فقط.
  3. تعريف الانتهاء: من يقرر أن العمل انتهى؟ إذا قرر النموذج وحده فسوف يعلن الانتهاء أحياناً دون أن يغير شيئاً، ولذلك تفحص بيئة التشغيل الاختبارات بنفسها قبل أن تقبل الانتهاء.
  4. المخرج للمراجعة: الوكيل لا يدمج شيئاً، وإنما يسلمك فرقاً موحداً Unified Diff تقرؤه كما تقرأ طلب دمج Pull Request من زميل.

وقد يتساءل البعض: لماذا لا نعطي الوكيل طرفية كاملة كما تفعل أغلب الأدوات، ونترك النموذج يشغل grep وsed وpytest بنفسه؟ والإجابة أن هذا ممكن وناجح مع النماذج الكبيرة، فمشروع mini-swe-agent مثلاً وكيل في قرابة 100 سطر من Python لا يملك أي أداة غير bash، ويقول مستودعه إنه يحقق أكثر من 74% على اختبار SWE-bench Verified. ولكن النموذج الصغير على جهازك يخطئ في الأوامر كثيراً، والطرفية الكاملة تعني أن كل خطأ له أثر جانبي محتمل، ولذلك اخترنا العكس: سبع أدوات ضيقة فقط، وكل أداة هي أيضاً صلاحية، فالوكيل لا يستطيع أن يحذف ملفاً لأنه لا توجد أداة للحذف، ولا يستطيع أن يشغل أي أمر غير الاختبارات لأن الأداة الوحيدة التي تشغل شيئاً تشغل الاختبارات فقط.

وهذه الفكرة لها اسم في الأبحاث، فقد سمى فريق SWE-agent في 2024 هذه الطبقة واجهة الوكيل مع الحاسوب Agent-Computer Interface، وبين أن تصميم أوامر البحث والتعديل نفسه يغير نسبة المشكلات التي يحلها النموذج نفسه، ووصل بها إلى 12.5% على SWE-bench الكامل في ذلك الوقت. وفي يناير 2025 كتبت Anthropic عن البيئة التي حققت بها 49% على SWE-bench Verified أنها أداتان فقط: bash وأداة تعديل، وأن الاستبدال النصي كان أكثر طرق التعديل موثوقية، بشرط أن يحدث الاستبدال فقط إذا وجد النص القديم مرة واحدة، وإلا يرجع خطأ ويحاول النموذج من جديد، وأنهم جعلوا الأداة تطلب المسار المطلق دائماً بعد أن رأوا النموذج يخطئ في المسار النسبي. وسوف ترى هذه القرارات نفسها في minicode، وترى لماذا تحتاجها.

شكل المختبر: الوكيل في صندوق، والحكم خارجه

المختبر يتكون من ثلاثة أجزاء منفصلة، والشكل التالي يبينها:

على اليمين Container الوكيل minicode داخل إطار أحمر مكتوب عليه الصندوق المعزول: شبكة داخلية فقط، نظام ملفات للقراءة، مستخدم 1000، 512 MB. داخله الحلقة والأدوات السبع ونسخة المستودع. سهم إلى Container فيه Ollama والنموذجان qwen2.5-coder:3b وqwen3:4b-instruct على شبكة adb-int الداخلية. وعلى اليسار Container الحكم دون شبكة، يأخذ نسخة المستودع بعد الوكيل ويضيف إليها الاختبارات المخفية ويطبع النتيجة
الوكيل يعمل في صندوق لا يصل إلا إلى النموذج، والحكم يعمل بعده في Container آخر بالاختبارات المخفية.
  • Ollama بالإصدار 0.40.13 في Container، وفيه نموذجان بتكميم Q4_K_M: qwen2.5-coder:3b المدرب على الكود، وqwen3:4b-instruct العام دون وضع التفكير. والـ Container متصل بشبكة Docker داخلية اسمها adb-int أنشئت بالخيار --internal، أي لا يخرج منها أي اتصال إلى الإنترنت.
  • الوكيل في Container جديد لكل مهمة من python:3.13.18-slim، على الشبكة الداخلية نفسها فقط، بنظام ملفات للقراءة فقط، ومستخدم غير root، ودون أي صلاحية في النواة، وبحد 512 MB للذاكرة. والمجلد الوحيد الذي يكتب فيه هو نسخة من المستودع.
  • الحكم Grader في Container ثالث دون أي شبكة، يأخذ نسخة المستودع بعد أن ينتهي الوكيل، ويضيف إليها الاختبارات المخفية، ويشغل الاختبارات الظاهرة والمخفية كلاً على حدة.

والسكربت run-task.sh يشغل الجزأين الأخيرين لكل مهمة، وهذا هو:

#!/bin/bash
# Runs the agent on one task in a sandbox container, then grades the result with the hidden tests.
#   bash run-task.sh <task-folder> <model> [label] [extra agent options...]
# The sandbox: network adb-int (internal: it reaches only the Ollama container, no internet),
# read-only root, a non-root user, no capabilities, 512 MB RAM, 128 processes, the repository copy as the only writable folder.
set -eo pipefail
cd "$(dirname "$0")"
TASK=${1%/}; MODEL=$2; LABEL=${3:-run}; shift 3 || true
NAME=$(basename "$TASK")
RUN=data/$LABEL/${MODEL//[:\/]/_}/$NAME
rm -rf "$RUN"; mkdir -p "$RUN/out"
cp -r "$TASK/repo" "$RUN/work"
w() { (cd "$1" && pwd -W); }

MSYS_NO_PATHCONV=1 docker run --rm --name "adb-agent-$$" --network adb-int \
  --read-only --tmpfs /tmp:size=64m --user 1000:1000 --cap-drop ALL --security-opt no-new-privileges \
  --memory 512m --memory-swap 512m --pids-limit 128 --cpus 1 \
  -e OLLAMA=http://adb-ollama:11434 -e PYTHONDONTWRITEBYTECODE=1 \
  -v "$(w "$RUN/work"):/work" -v "$(w "$RUN/out"):/out" \
  -v "$(w minicode):/agent:ro" -v "$(w "$TASK"):/task:ro" \
  python:3.13.18-slim python -u /agent/agent.py --task /task/task.md --model "$MODEL" "$@" | tee "$RUN/out/agent.log"

MSYS_NO_PATHCONV=1 docker run --rm --name "adb-grade-$$" --network none --read-only --tmpfs /tmp \
  -v "$(w "$RUN/work"):/work:ro" -v "$(w "$TASK/hidden"):/hidden:ro" -v "$(w minicode):/agent:ro" \
  python:3.13.18-slim python -B /agent/grade.py /work /hidden | tee "$RUN/out/grade.json"

والسؤال الطبيعي هنا: الوكيل لا يملك أداة تشغل أوامر، فلماذا نحتاج صندوقاً معزولاً أصلاً؟ والإجابة أن الأداة run_tests تشغل كوداً كتبه النموذج، فإذا كتب النموذج في دالة سطراً يتصل بالشبكة أو يحذف ملفات، فإن الاختبار هو الذي سوف ينفذه. ولذلك فإن الحد الحقيقي هو الـ Container، والأدوات الضيقة طبقة ثانية فوقه. وهذا ما يصل إليه كود داخل الصندوق، من القسم الثالث في السكربت run.sh:

http://adb-ollama:11434/api/version -> b'{"version":"0.40.13"}'
https://example.com -> blocked: <urlopen error [Errno -3] Temporary failure in name resolution>
http://1.1.1.1 -> blocked: <urlopen error [Errno 101] Network is unreachable>

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

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

كل مهمة في المختبر مجلد فيه ثلاثة أشياء: الملف task.md الذي فيه وصف المشكلة كما يكتبه موظف الدعم أو صاحب المنتج، والمجلد repo فيه الكود واختبارات ظاهرة Visible Tests يراها الوكيل ويشغلها، والمجلد hidden فيه اختبارات مخفية تفحص ما يطلبه الوصف فعلاً، والوكيل لا يراها أبداً. وكتبنا 12 مهمة بهذا الشكل، وسوف نستعمل خمساً منها في هذا المقال، ونستعمل المجموعة كاملة في مقال قياس وكلاء البرمجة في هذه المرحلة. وهذه المهمة الأولى كاملة:

Orders of exactly 500 SAR do not get the 10% discount.
Customer support says the discount should apply from 500 SAR and up, but an order of 500.00 is charged in full.
DISCOUNT_FROM = 500
DISCOUNT_RATE = 0.10


def final_total(total):
    """Total after discount, rounded to 2 decimals."""
    if total > DISCOUNT_FROM:
        total = total * (1 - DISCOUNT_RATE)
    return round(total, 2)
import unittest
from shop.pricing import final_total


class TestPricing(unittest.TestCase):
    def test_big_order(self):
        self.assertEqual(final_total(600), 540.0)

    def test_small_order(self):
        self.assertEqual(final_total(100), 100)

لاحظ أن الاختبارات الظاهرة تنجح من البداية، فطلب بقيمة 600 يحصل على الخصم، وطلب بقيمة 100 لا يحصل عليه، ولا يوجد اختبار للقيمة 500 نفسها. وهذا مقصود، لأنه الوضع الطبيعي في أي مشروع حقيقي: المشكلة موجودة لأن أحداً لم يكتب اختباراً لها. أما الاختبارات المخفية فتفحص الحد نفسه:

import unittest
from shop.pricing import final_total


class Hidden(unittest.TestCase):
    def test_exactly_500(self):
        self.assertEqual(final_total(500), 450.0)

    def test_just_below(self):
        self.assertEqual(final_total(499.99), 499.99)

    def test_rounding(self):
        self.assertEqual(final_total(533.33), 480.0)

وقبل أن نعطي أي مهمة لأي وكيل، يجب أن نتأكد من شيئين: أن الكود الأصلي يفشل في الاختبارات المخفية، أي أن المشكلة حقيقية، وأن حلاً كتبه إنسان ينجح فيها، أي أن الاختبارات نفسها صحيحة. ولذلك لكل مهمة مجلد reference فيه حل كتبناه بأنفسنا، والسكربت validate.py يفحص المهام كلها، والمخرج سوف يكون كما يلي:

T01-discount   original: visible pass, hidden FAIL  reference: visible pass, hidden pass  ok
T02-duration   original: visible FAIL, hidden FAIL  reference: visible pass, hidden pass  ok
T03-slugify    original: visible pass, hidden FAIL  reference: visible pass, hidden pass  ok
T04-csv        original: visible pass, hidden FAIL  reference: visible pass, hidden pass  ok
T05-merge      original: visible FAIL, hidden FAIL  reference: visible pass, hidden pass  ok
T06-paginate   original: visible FAIL, hidden FAIL  reference: visible pass, hidden pass  ok
T07-retry      original: visible pass, hidden FAIL  reference: visible pass, hidden pass  ok
T08-ttl        original: visible FAIL, hidden FAIL  reference: visible pass, hidden pass  ok
T09-median     original: visible pass, hidden FAIL  reference: visible pass, hidden pass  ok
T10-split      original: visible pass, hidden FAIL  reference: visible pass, hidden pass  ok
T11-intervals  original: visible pass, hidden FAIL  reference: visible pass, hidden pass  ok
T12-versions   original: visible pass, hidden FAIL  reference: visible pass, hidden pass  ok

في المخرج أعلاه لاحظ أن ثمانياً من المهام الاثنتي عشرة تنجح اختباراتها الظاهرة قبل أي إصلاح، وأن الاختبارات المخفية تفشل في كل المهام قبل الإصلاح وتنجح كلها مع الحل المرجعي. وهذا الفحص ليس تفصيلاً، فهو بالضبط ما فعلته OpenAI مع فريق SWE-bench عندما بنوا SWE-bench Verified: راجعوا المهام واحدة واحدة لأن جزءاً منها كان وصفه غامضاً أو اختباراته ترفض حلاً صحيحاً، وسوف نعود إلى ذلك في مقال القياس.

الكود كاملاً: minicode في ملف واحد

هذا هو الوكيل بعد الإصدار الثالث، أي بعد كل الإصلاحات التي سوف نمر عليها، وهو مقسم إلى سبعة أجزاء مرقمة في التعليقات:

# minicode: a small coding agent in one file (Python 3.13, standard library only).
# The model runs in Ollama; the agent reads, searches, edits and tests the repository in /work,
# and prints the change as a unified diff at the end.
#
#   python agent.py --task task.md --work /work --out /out [--model qwen2.5-coder:3b] [--mode json|tools]
#                   [--max-steps 14] [--max-seconds 900] [--no-verify-finish]
import argparse, ast, difflib, json, os, re, subprocess, sys, time, urllib.request
from pathlib import Path

OLLAMA = os.environ.get("OLLAMA", "http://adb-ollama:11434")
TOOLS = ["list_files", "read_file", "search", "replace", "write_file", "run_tests", "finish"]

# ---------------------------------------------------------------- 1. what the model is told
SYSTEM = """You are a coding agent. You fix issues in a small Python repository at /work.
You work in steps. In each step you call exactly one tool, then you see its result.

Tools:
- list_files: list the files of the repository.
- read_file(path): show a file with line numbers.
- search(pattern): regular expression search in all .py files, shows file:line: text.
- replace(path, old, new): replace the exact text old (it must appear exactly once in the file) with new.
- write_file(path, content): create a new file, or rewrite a whole file.
- run_tests: run the tests of the repository and show the result.
- finish(summary): stop and say what you changed.

Rules:
- Read the code and the tests that relate to the issue before you change anything.
- Never change files under tests/. They define what is correct.
- After every change, run_tests. Finish only when the tests pass.
- Keep changes small: change only what the issue needs.
"""

# The reply format: one flat JSON object with the tool name and its arguments. Ollama's "format" field turns
# this schema into a grammar the model cannot leave (structured outputs), so a small model cannot answer
# with free text or a broken call. Which arguments each tool needs is checked by the harness (ARGS).
ARGS = {"list_files": [], "read_file": ["path"], "search": ["pattern"], "replace": ["path", "old", "new"],
        "write_file": ["path", "content"], "run_tests": [], "finish": ["summary"]}
SCHEMA_FLAT = {"type": "object",
               "properties": {"thought": {"type": "string"}, "tool": {"type": "string", "enum": TOOLS},
                              **{arg: {"type": "string"} for arg in ["path", "pattern", "old", "new", "content", "summary"]}},
               "required": ["thought", "tool"]}
# The arguments in their own object with free keys: the grammar still forces valid JSON and a real tool name,
# but the model is not walked through a fixed list of argument slots (--schema args, the default).
SCHEMA_ARGS = {"type": "object",
               "properties": {"thought": {"type": "string"}, "tool": {"type": "string", "enum": TOOLS},
                              "args": {"type": "object"}},
               "required": ["thought", "tool", "args"]}
# A stricter variant: one object per tool with its own required arguments (--schema anyof).
SCHEMA_ANYOF = {"anyOf": [
    {"type": "object",
     "properties": {"thought": {"type": "string"}, "tool": {"type": "string", "enum": [name]},
                    **{arg: {"type": "string"} for arg in args}},
     "required": ["thought", "tool", *args]}
    for name, args in ARGS.items()]}
FORMAT_HINT = ('Reply with one JSON object only: {"thought": "...", "tool": "<tool name>", "args": {<the arguments of that tool>}}, '
               'for example {"thought": "find the code the issue talks about", "tool": "search", "args": {"pattern": "def "}}')

# The same tools in Ollama's native tool-calling form, used by --mode tools for comparison.
def _fn(name, desc, props=None, req=None):
    return {"type": "function", "function": {"name": name, "description": desc, "parameters": {
        "type": "object", "properties": {k: {"type": "string"} for k in (props or [])}, "required": req or []}}}
NATIVE_TOOLS = [
    _fn("list_files", "List the files of the repository."),
    _fn("read_file", "Show a file with line numbers.", ["path"], ["path"]),
    _fn("search", "Regular expression search in all .py files.", ["pattern"], ["pattern"]),
    _fn("replace", "Replace the exact text old (once in the file) with new.", ["path", "old", "new"], ["path", "old", "new"]),
    _fn("write_file", "Create a new file or rewrite a whole file.", ["path", "content"], ["path", "content"]),
    _fn("run_tests", "Run the tests of the repository."),
    _fn("finish", "Stop and say what you changed.", ["summary"], ["summary"]),
]


# ---------------------------------------------------------------- 2. the model client
def chat(model, messages, mode, temperature, seed, num_ctx, schema=None):
    body = {"model": model, "messages": messages, "stream": False, "keep_alive": "30m",
            "options": {"temperature": temperature, "seed": seed, "num_ctx": num_ctx, "num_predict": 700}}
    if mode == "json":
        body["format"] = schema
    else:
        body["tools"] = NATIVE_TOOLS
    if model.startswith("qwen3") and "instruct" not in model:
        body["think"] = False
    req = urllib.request.Request(OLLAMA + "/api/chat", data=json.dumps(body).encode(),
                                 headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=900) as r:
        return json.load(r)


def parse_action(reply, mode):
    """Turns the model reply into (tool, args). Returns (None, reason) when there is no usable call."""
    msg = reply.get("message", {})
    if mode == "tools":
        calls = msg.get("tool_calls") or []
        if not calls:
            return None, "no tool call in the reply (text: %r)" % msg.get("content", "")[:120]
        fn = calls[0]["function"]
        args = fn.get("arguments") or {}
        return fn.get("name"), {k: v for k, v in args.items() if isinstance(v, str)}
    try:
        obj = json.loads(msg.get("content", ""))
    except json.JSONDecodeError as e:
        return None, "reply is not JSON: %s" % e
    tool = obj.pop("tool", None)
    obj.pop("thought", None)
    if isinstance(obj.get("args"), dict):
        obj = obj["args"]
    return tool, {k: v for k, v in obj.items() if isinstance(v, str)}


# ---------------------------------------------------------------- 3. the tools (the only things the agent can do)
class Workspace:
    def __init__(self, root):
        self.root = Path(root).resolve()
        self.before = self.snapshot()          # for the diff at the end

    def snapshot(self):
        return {str(p.relative_to(self.root)): p.read_text(errors="replace")
                for p in sorted(self.root.rglob("*")) if p.is_file() and "__pycache__" not in p.parts}

    def path(self, rel, write=False):
        if not rel:
            raise ValueError("path is empty")
        p = (self.root / rel).resolve()
        if p != self.root and self.root not in p.parents:
            raise PermissionError("path is outside the repository: %s" % rel)
        if write and (p.relative_to(self.root).parts[0] == "tests" or p.name.startswith("test_")):
            raise PermissionError("tests are read-only for the agent: %s" % rel)
        return p

    def list_files(self, **_):
        return "\n".join(self.snapshot().keys())

    def read_file(self, path="", **_):
        lines = self.path(path).read_text().splitlines()
        return "\n".join("%4d  %s" % (i + 1, l) for i, l in enumerate(lines)) or "(empty file)"

    def search(self, pattern="", **_):
        rx = re.compile(pattern)
        hits = ["%s:%d: %s" % (f, i + 1, l.strip()) for f, text in self.snapshot().items() if f.endswith(".py")
                for i, l in enumerate(text.splitlines()) if rx.search(l)]
        return "\n".join(hits[:40]) or "no match"

    def replace(self, path="", old="", new="", **_):
        p = self.path(path, write=True)
        text = p.read_text()
        n = text.count(old) if old else 0
        if n == 0 and old.strip():
            # Models often copy the indentation wrong (or part of the line numbers of read_file).
            # Second try: compare line by line without leading spaces, and keep the file's own indentation.
            lines, want = text.splitlines(True), [l.strip() for l in old.strip("\n").splitlines()]
            hits = [i for i in range(len(lines) - len(want) + 1)
                    if [l.strip() for l in lines[i:i + len(want)]] == want]
            if len(hits) == 1:
                i = hits[0]
                pad = lines[i][:len(lines[i]) - len(lines[i].lstrip())]
                newl = new.strip("\n").splitlines()
                base = min((len(l) - len(l.lstrip()) for l in newl if l.strip()), default=0)
                body = "".join(pad + l[base:] + "\n" if l.strip() else "\n" for l in newl)
                p.write_text("".join(lines[:i]) + body + "".join(lines[i + len(want):]))
                return "replaced lines %d-%d in %s (matched without leading spaces)" % (i + 1, i + len(want), path)
        if n != 1:
            raise ValueError("old text found %d times in %s, it must appear exactly once; read the file and copy the exact lines" % (n, path))
        p.write_text(text.replace(old, new, 1))
        return "replaced %d chars with %d chars in %s" % (len(old), len(new), path)

    def write_file(self, path="", content="", **_):
        p = self.path(path, write=True)
        p.parent.mkdir(parents=True, exist_ok=True)
        p.write_text(content if content.endswith("\n") else content + "\n")
        return "wrote %d chars to %s" % (len(content), path)

    def run_tests(self, **_):
        r = subprocess.run([sys.executable, "-m", "unittest", "discover", "-s", "tests", "-t", "."],
                           cwd=self.root, capture_output=True, text=True, timeout=60,
                           env={"PATH": "/usr/local/bin:/usr/bin:/bin", "PYTHONDONTWRITEBYTECODE": "1"})
        out = (r.stdout + r.stderr).strip()
        return ("PASSED" if r.returncode == 0 else "FAILED (exit %d)" % r.returncode) + "\n" + out[-1800:]

    def repo_map(self):
        """Every file, and the functions and classes in each .py file: what the agent sees before its first step."""
        lines = []
        for f, text in self.snapshot().items():
            names = []
            if f.endswith(".py"):
                try:
                    for node in ast.walk(ast.parse(text)):
                        if isinstance(node, (ast.FunctionDef, ast.ClassDef)):
                            names.append(("class " if isinstance(node, ast.ClassDef) else "def ") + node.name)
                except SyntaxError:
                    names.append("(syntax error)")
            lines.append(f + (": " + ", ".join(names) if names else ""))
        return "\n".join(lines)

    def diff(self):
        after, lines = self.snapshot(), []
        for f in sorted(set(self.before) | set(after)):
            a, b = self.before.get(f, ""), after.get(f, "")
            if a != b:
                lines += difflib.unified_diff(a.splitlines(True), b.splitlines(True), "a/" + f, "b/" + f)
        return "".join(lines)


# ---------------------------------------------------------------- 4. the loop
def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--task", required=True)
    ap.add_argument("--work", default="/work")
    ap.add_argument("--out", default="/out")
    ap.add_argument("--model", default="qwen2.5-coder:3b")
    ap.add_argument("--mode", choices=["json", "tools"], default="json")
    ap.add_argument("--max-steps", type=int, default=14)
    ap.add_argument("--max-seconds", type=int, default=900)
    ap.add_argument("--temperature", type=float, default=0.0)
    ap.add_argument("--seed", type=int, default=1)
    ap.add_argument("--num-ctx", type=int, default=8192)
    ap.add_argument("--no-verify-finish", action="store_true")
    ap.add_argument("--no-repo-map", action="store_true")
    ap.add_argument("--schema", choices=["args", "flat", "anyof"], default="args")
    a = ap.parse_args()

    ws = Workspace(a.work)
    out = Path(a.out); out.mkdir(parents=True, exist_ok=True)
    log = open(out / "trajectory.jsonl", "w")
    task = Path(a.task).read_text().strip()
    system = SYSTEM + ("\n" + FORMAT_HINT if a.mode == "json" else "")
    first = "Issue:\n" + task
    if not a.no_repo_map:
        first += "\n\nRepository files:\n" + ws.repo_map()
    messages = [{"role": "system", "content": system}, {"role": "user", "content": first}]
    t0, tok_in, tok_out, seen, stop = time.time(), 0, 0, {}, "max steps"
    finish_refusals = 0
    print("task: %s\nmodel: %s, mode: %s, budget: %d steps, %d s" % (task.splitlines()[0], a.model, a.mode, a.max_steps, a.max_seconds))

    for step in range(1, a.max_steps + 1):
        if time.time() - t0 > a.max_seconds:
            stop = "time budget"
            break
        s0 = time.time()
        reply = chat(a.model, messages, a.mode, a.temperature, a.seed, a.num_ctx,
                     {"args": SCHEMA_ARGS, "flat": SCHEMA_FLAT, "anyof": SCHEMA_ANYOF}[a.schema])
        tok_in += reply.get("prompt_eval_count", 0)
        tok_out += reply.get("eval_count", 0)
        msg = reply.get("message", {})
        messages.append({k: msg[k] for k in ("role", "content", "tool_calls") if k in msg})
        tool, args = parse_action(reply, a.mode)
        thought = ""
        if a.mode == "json":
            try:
                thought = json.loads(msg.get("content", "{}")).get("thought", "")
            except json.JSONDecodeError:
                pass

        # ---- 5. permissions and execution: unknown tools and bad paths come back to the model as errors
        if tool is None:
            result, ok = "ERROR: " + args + ". " + (FORMAT_HINT if a.mode == "json" else "Call one of the tools."), False
        elif tool not in TOOLS:
            result, ok = "ERROR: unknown tool %r. Tools: %s" % (tool, ", ".join(TOOLS)), False
        elif [k for k in ARGS[tool] if k not in args]:
            result, ok = ("ERROR: %s needs the arguments %s; you sent %s"
                          % (tool, ", ".join(ARGS[tool]) or "none", ", ".join(args) or "none")), False
        elif tool == "finish":
            check = ws.run_tests()
            unchanged = ws.snapshot() == ws.before
            if a.no_verify_finish or finish_refusals >= 2 or (check.startswith("PASSED") and not unchanged):
                stop = "finished (tests %s)" % check.split()[0].lower()
                log.write(json.dumps({"step": step, "tool": tool, "args": args, "thought": thought,
                                      "result": check[:300], "secs": round(time.time() - s0, 1)}) + "\n")
                print("[%d] finish: %s\n    tests: %s  (%.0f s)" % (step, args.get("summary", "")[:160], check.split()[0], time.time() - s0))
                break
            finish_refusals += 1
            if unchanged:
                result, ok = ("You cannot finish yet: you have not changed any file, and the issue asks for a change. "
                              "The current tests may not cover the issue: read the code the issue talks about and fix it."), False
            else:
                result, ok = "You cannot finish yet: the tests fail.\n" + check, False
        else:
            try:
                result, ok = getattr(ws, tool)(**args), True
            except TypeError as e:
                result, ok = "ERROR: bad arguments for %s: %s" % (tool, e), False
            except subprocess.TimeoutExpired:
                result, ok = "ERROR: tests took longer than 60 s and were stopped", False
            except Exception as e:
                result, ok = "ERROR: %s" % e, False
        result = result if len(result) <= 2500 else result[:2500] + "\n[cut: %d more chars]" % (len(result) - 2500)

        # ---- 6. budget: the same call with the same result three times means the agent is stuck
        key = json.dumps([tool, args, result], sort_keys=True)
        seen[key] = seen.get(key, 0) + 1
        short = {k: (v if len(v) < 40 else v[:37] + "...") for k, v in args.items()} if isinstance(args, dict) else {}
        print("[%d] %s %s -> %s  (%d in / %d out, %.0f s)" % (step, tool, json.dumps(short, ensure_ascii=False),
              result.splitlines()[0][:90] if result else "", reply.get("prompt_eval_count", 0), reply.get("eval_count", 0), time.time() - s0))
        log.write(json.dumps({"step": step, "tool": tool, "args": args, "thought": thought, "ok": ok,
                              "result": result[:300], "in": reply.get("prompt_eval_count", 0),
                              "out": reply.get("eval_count", 0), "secs": round(time.time() - s0, 1)}) + "\n")
        if seen[key] >= 3:
            stop = "stuck (same call, same result, 3 times)"
            break
        note = "\nNote: you already did exactly this and got the same result. Try something different." if seen[key] == 2 else ""
        if a.mode == "tools" and msg.get("tool_calls"):
            messages.append({"role": "tool", "content": result + note})
        else:
            messages.append({"role": "user", "content": "Result of %s:\n%s%s" % (tool, result, note)})

    # ---- 7. the output: a diff for a human to review, and the numbers
    patch = ws.diff()
    (out / "patch.diff").write_text(patch)
    summary = {"model": a.model, "mode": a.mode, "steps": step, "stop": stop, "seconds": round(time.time() - t0),
               "tokens_in": tok_in, "tokens_out": tok_out, "files_changed": patch.count("\n+++ ") + patch.startswith("+++ ")}
    (out / "summary.json").write_text(json.dumps(summary))
    print("stop: %s | steps %d | %d s | tokens in %d, out %d" % (stop, step, summary["seconds"], tok_in, tok_out))
    print("---- patch.diff\n" + (patch or "(no change)"))


if __name__ == "__main__":
    main()

في الكود أعلاه لاحظ التالي:

  • الجزء 1 هو كل ما يقال للنموذج عن عالمه: سبع أدوات بجملة لكل منها، وأربع قواعد، أهمها أن ملفات الاختبارات تعرف ما هو الصحيح فلا تعدل. ولكن القاعدة المكتوبة للنموذج لا تحمي شيئاً، ولذلك نجد القاعدة نفسها في الكود في الدالة path، التي ترفض أي كتابة في المجلد tests أو في ملف يبدأ اسمه بـ test_، وترفض أي مسار يخرج من المستودع.
  • الجزء 2 يرسل المحادثة إلى Ollama، وفيه طريقتان لكتابة الطلب: الحقل format مع مخطط JSON Schema في الوضع json، والحقل tools بوصف الأدوات في الوضع tools. والمعامل num_ctx نضعه صراحة عند 8192، لأن النافذة الافتراضية في Ollama على جهاز دون بطاقة رسومية هي 4096 توكن، وقد رأينا في مقال النموذج المحلي أنها تقطع بداية المحادثة دون أي رسالة خطأ.
  • الجزء 3 هو الأدوات، وأهمها replace: تبحث عن النص القديم، فإذا وجدته مرة واحدة استبدلته، وإذا لم تجده تحاول مرة ثانية بمقارنة الأسطر دون المسافات في أولها، ثم تحافظ على مسافات الملف نفسه. وسوف نرى بعد قليل لماذا أضفنا هذه المحاولة الثانية.
  • الدالة repo_map تبني قبل الخطوة الأولى قائمة بالملفات، ومع كل ملف Python أسماء الدوال والكلاسات فيه، بتحليل الكود بالوحدة ast وليس بالتعبيرات النمطية Regex، فلا يحتاج النموذج أن يخمن أين الكود.
  • الجزء 5 يفحص كل طلب قبل تنفيذه: هل هناك طلب أصلاً، وهل الأداة موجودة، وهل وصلت المعاملات المطلوبة لها، ثم يرجع للنموذج رسالة خطأ واضحة تقول ما المطلوب وما الذي أرسله. والطلب finish لا يقبل مباشرة، وإنما تشغل بيئة التشغيل الاختبارات بنفسها، وترفض الانتهاء إذا فشلت أو إذا لم يتغير أي ملف، ثم تقبله بعد رفضين حتى لا تدور الحلقة بلا نهاية.
  • الجزء 6 يوقف الوكيل إذا تكرر الطلب نفسه مع النتيجة نفسها ثلاث مرات، ويضيف في المرة الثانية تنبيهاً، كما في مقال بيئة التشغيل.
  • الجزء 7 يكتب الفرق بالوحدة difflib بين لقطة المستودع في البداية وحالته في النهاية، فلا نحتاج Git داخل الـ Container، ويكتب ملخصاً بعدد الخطوات والتوكنات والزمن.

وقبل أن نشغل أي نموذج، نستدعي الأدوات مباشرة بطلبات ثابتة لنرى ما يرجع منها، فهذا ما يراه النموذج عندما يخطئ، والمخرج كما يلي:

read_file {'path': 'shop/pricing.py'}
       1  DISCOUNT_FROM = 500
       2  DISCOUNT_RATE = 0.10
       3  
       4  
       5  def final_total(total):
       6      """Total after discount, rounded to 2 decimals."""
       7      if total > DISCOUNT_FROM:
       8          total = total * (1 - DISCOUNT_RATE)
       9      return round(total, 2)
read_file {'path': '../etc/passwd'}
    ERROR: path is outside the repository: ../etc/passwd
read_file {'path': '/etc/passwd'}
    ERROR: path is outside the repository: /etc/passwd
write_file {'path': 'tests/test_pricing.py', 'content': "print('ok')"}
    ERROR: tests are read-only for the agent: tests/test_pricing.py
replace {'path': 'shop/pricing.py', 'old': 'DISCOUNT', 'new': 'X'}
    ERROR: old text found 4 times in shop/pricing.py, it must appear exactly once; read the file and copy the exact lines
replace {'path': 'shop/pricing.py', 'old': 'if total > 500:', 'new': 'if total >= 500:'}
    ERROR: old text found 0 times in shop/pricing.py, it must appear exactly once; read the file and copy the exact lines
search {'pattern': 'DISCOUNT_'}
    shop/pricing.py:1: DISCOUNT_FROM = 500
    shop/pricing.py:2: DISCOUNT_RATE = 0.10
    shop/pricing.py:7: if total > DISCOUNT_FROM:
    shop/pricing.py:8: total = total * (1 - DISCOUNT_RATE)
run_tests {}
    PASSED
    ..
    ----------------------------------------------------------------------
    Ran 2 tests in 0.000s
    
    OK
delete_file {'path': 'shop/pricing.py'}
    ERROR: unknown tool 'delete_file'

كل خطأ في المخرج أعلاه رسالة يقرؤها النموذج، ولذلك كتبناها بحيث تقول السبب وما المطلوب: «النص القديم وجد 4 مرات، ويجب أن يوجد مرة واحدة، اقرأ الملف وانسخ الأسطر كما هي». ولاحظ أن الطلب delete_file رجع بخطأ لأن الأداة غير موجودة أصلاً، فلا توجد قاعدة تمنع الحذف لأنه لا يوجد حذف.

الإصدار الأول: الوكيل يبحث عن ملف لا وجود له

الإصدار الأول من minicode، وهو الملف agent_v1.py في المختبر، كان مثل الكود أعلاه دون خريطة المستودع، ودون رفض الانتهاء عندما لا يتغير شيء، وفي تعليمات الرد مثال واحد يقرأ ملفاً اسمه tests/test_app.py. وأعطيناه المهمة الأولى مع qwen2.5-coder:3b، والمخرج كاملاً كما يلي:

task: Orders of exactly 500 SAR do not get the 10% discount.
model: qwen2.5-coder:3b, mode: json, budget: 14 steps, 900 s
[1] read_file {"path": "app.py"} -> ERROR: [Errno 2] No such file or directory: '/work/app.py'  (312 in / 32 out, 39 s)
[2] list_files {} -> shop/__init__.py  (377 in / 27 out, 5 s)
[3] finish: The file 'app.py' does not exist in the repository. Please verify the file path or create the file.
    tests: PASSED  (13 s)
stop: finished (tests passed) | steps 3 | 57 s | tokens in 1129, out 119
---- patch.diff
(no change)
{"visible": true, "hidden": false, "visible_detail": "Ran 2 tests in 0.000s OK", "hidden_detail": "Ran 3 tests in 0.001s FAILED (failures=1)"}

في المخرج أعلاه لاحظ التالي:

  • أول ما طلبه النموذج قراءة app.py، وهو ملف لا وجود له، والاسم جاء من المثال الذي كتبناه نحن في التعليمات. فالنموذج الصغير لا يفرق بين المثال وبين حقيقة عن المشروع، وكل اسم تكتبه في التعليمات قد يعامله كأنه موجود.
  • في الخطوة الثانية عرض الملفات ورأى shop/pricing.py فعلاً، ثم في الخطوة الثالثة أعلن الانتهاء وكتب أن الملف app.py غير موجود.
  • بيئة التشغيل فحصت الاختبارات قبل أن تقبل الانتهاء، فوجدتها ناجحة، لأنها كانت ناجحة من البداية، فقبلت. والنتيجة: لا تغيير، والاختبارات الظاهرة ناجحة، والمخفية فاشلة. ولو كان الحكم هو الاختبارات الظاهرة فقط لاعتبرنا هذا التشغيل ناجحاً.

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

الإصدار الثاني: نجح مرة، وكشف مشكلة في شكل الرد

شغلنا الإصدار الثاني على خمس مهام بالنموذجين، والتشغيل الأول بالمهمة نفسها مع qwen2.5-coder:3b كان كما يلي:

task: Orders of exactly 500 SAR do not get the 10% discount.
model: qwen2.5-coder:3b, mode: json, budget: 14 steps, 900 s
[1] search {"pattern": "def final_total"} -> shop/pricing.py:5: def final_total(total):  (367 in / 35 out, 5 s)
[2] read_file {"path": "shop/pricing.py"} ->    1  DISCOUNT_FROM = 500  (427 in / 36 out, 5 s)
[3] search {"pattern": "if total > DISCOUNT_FROM:"} -> shop/pricing.py:7: if total > DISCOUNT_FROM:  (573 in / 36 out, 7 s)
[4] replace {"path": "shop/pricing.py", "old": "if total > DISCOUNT_FROM:", "new": "if total >= DISCOUNT_FROM:"} -> replaced 25 chars with 26 chars in shop/pricing.py  (636 in / 64 out, 8 s)
[5] run_tests {} -> PASSED  (729 in / 27 out, 4 s)
[6] finish: The final_total function now correctly applies a 10% discount for orders of 500 SAR and above.
    tests: PASSED  (8 s)
stop: finished (tests passed) | steps 6 | 37 s | tokens in 3523, out 250
---- patch.diff
--- a/shop/pricing.py
+++ b/shop/pricing.py
@@ -4,6 +4,6 @@
 
 def final_total(total):
     """Total after discount, rounded to 2 decimals."""
-    if total > DISCOUNT_FROM:
+    if total >= DISCOUNT_FROM:

هذا هو الوكيل كما نريده: بحث عن الدالة، ثم قرأ الملف، ثم بحث عن السطر، ثم استبدل > بـ >=، ثم شغل الاختبارات، ثم أنهى، وفي 37 ثانية، والاختبارات المخفية الثلاثة نجحت. ولكن هذه كانت المهمة الوحيدة التي نجح فيها من خمس، أما النموذج الثاني qwen3:4b-instruct فلم ينجح في أي مهمة أكملها، والسبب ظهر في سجل أول مهمة وتكرر في المهام التي بعدها، وهذه أسطر الاستبدال من سجلاته:

model: qwen3:4b-instruct, mode: json, budget: 14 steps, 900 s
[3] replace {"path": "shop/pricing.py", "pattern": "if total > DISCOUNT_FROM:", "summary": "Changed the discount condition from '..."} -> ERROR: old text found 0 times in shop/pricing.py, it must appear exactly once; read the fi  (584 in / 131 out, 26 s)
[6] replace {"path": "shop/pricing.py", "pattern": "if total > DISCOUNT_FROM:", "summary": "Changed the discount condition from '..."} -> ERROR: old text found 0 times in shop/pricing.py, it must appear exactly once; read the fi  (1053 in / 116 out, 27 s)
model: qwen3:4b-instruct, mode: json, budget: 14 steps, 900 s
[3] replace {"path": "timeparse/durations.py", "pattern": "def parse_duration(text):\\s*\\\"\\\"\\\"Num...", "summary": "Update parse_duration to support hour..."} -> ERROR: old text found 0 times in timeparse/durations.py, it must appear exactly once; read  (566 in / 138 out, 27 s)
[5] replace {"path": "timeparse/durations.py", "pattern": "def parse_duration\\(text\\):\\s*\\\"\\\"\\\"N...", "summary": "Replace the docstring and function de..."} -> ERROR: old text found 0 times in timeparse/durations.py, it must appear exactly once; read  (891 in / 188 out, 53 s)
model: qwen3:4b-instruct, mode: json, budget: 14 steps, 900 s
model: qwen3:4b-instruct, mode: json, budget: 14 steps, 900 s
[5] replace {"path": "jobs/retry.py", "pattern": "for _ in range(times + 1):", "summary": "Change the loop to run exactly `times..."} -> ERROR: old text found 0 times in jobs/retry.py, it must appear exactly once; read the file  (873 in / 134 out, 54 s)
[7] replace {"path": "jobs/retry.py", "pattern": "for _ in range(times + 1):", "summary": "Change the loop to run exactly `times..."} -> ERROR: old text found 0 times in jobs/retry.py, it must appear exactly once; read the file  (1259 in / 199 out, 62 s)
model: qwen3:4b-instruct, mode: json, budget: 14 steps, 900 s

النموذج عرف الملف والسطر والتغيير المطلوب، ولكنه وضع النص القديم في الحقل pattern بدل الحقل old، ووضع وصف التغيير في summary، ولم يرسل new أصلاً. والسبب في شكل الرد الذي فرضناه: في الإصدار الثاني كان المخطط كائناً واحداً مسطحاً Flat فيه كل المعاملات الممكنة لكل الأدوات، path ثم pattern ثم old ثم new وهكذا، وكلها اختيارية. والنموذج عندما يكتب JSON مقيداً بالمخطط يمر على الحقول بترتيبها، فيصل إلى pattern قبل old، ويضع فيه ما يريد البحث عنه. والأسوأ أن رسالة الخطأ التي أرجعناها كانت «النص القديم وجد 0 مرة»، وهي رسالة صحيحة تقنياً، لأن old كان فارغاً، ولكنها لا تخبر النموذج بما أخطأ فيه فعلاً، فكرر الطلب نفسه حتى أوقفه كشف التكرار.

كيف يكتب النموذج طلبه؟ أربع طرق جربناها

هذا هو أهم قرار في وكيل يعمل بنموذج صغير، وهو ليس موضوعاً نظرياً، فقد رأينا في مقال النموذج المحلي أن نماذج Qwen2.5-Coder تكتب استدعاء الأداة نصاً عادياً بدل أن ترسله في الحقل المخصص له. والطرق المتاحة في Ollama اثنتان: استدعاء الأدوات الأصلي، حيث ترسل وصف الأدوات ويرجع النموذج الحقل tool_calls، والرد المنظم Structured Outputs، حيث ترسل مخطط JSON في الحقل format، فيحوله Ollama إلى قواعد Grammar تمنع النموذج من كتابة أي حرف لا يطابق المخطط. والطريقة الثانية تضمن JSON صحيحاً واسم أداة من القائمة، ولكنها كما رأينا تتأثر بشكل المخطط نفسه. والشكل التالي يلخص ما جربناه:

أربعة صفوف، لكل صفة شكل الرد ومثال حقيقي من المختبر والنتيجة: المخطط المسطح، والنموذج يضع النص القديم في pattern؛ مخطط anyOf لكل أداة، والنموذج يختار list_files دائماً؛ مخطط args بمعاملات حرة، ويعمل مع الفحص؛ واستدعاء الأدوات الأصلي، وqwen2.5-coder يكتبه نصاً بينما qwen3 يستعمله صحيحاً
شكل الرد الذي تفرضه على النموذج يغير ما يفعله، والنموذجان لم يتفقا على شكل واحد.

والتجارب كانت بالترتيب التالي:

  1. المخطط المسطح Flat Schema: كل المعاملات في مستوى واحد، وهو ما أفشل qwen3 في الإصدار الثاني كما رأينا.
  2. مخطط لكل أداة anyOf: الحل الذي يبدو صحيحاً من الكتب، فكل أداة كائن مستقل بمعاملاته المطلوبة، والرد يجب أن يطابق واحداً منها. وتأكدنا أولاً بطلب صغير، وهو الملف anyof_check.py، أن Ollama يحترم anyOf فعلاً ويختار البديل الثالث عندما يطلب منه، ثم شغلناه في الوكيل، فكانت النتيجة كما في الملف 04b-schema-experiments.txt:
### qwen3:4b-instruct, --schema anyof (one object per tool), T05
[1] list_files {} -> settings/__init__.py  (378 in / 22 out, 39 s)
[2] list_files {} -> settings/__init__.py  (435 in / 22 out, 44 s)
[3] list_files {} -> settings/__init__.py  (510 in / 26 out, 22 s)
stop: stuck (same call, same result, 3 times) | steps 3 | 105 s | tokens in 1323, out 70
{"visible": false, "hidden": false, "visible_detail": "Ran 2 tests in 0.002s FAILED (failures=1)", "hidden_detail": "Ran 3 tests in 0.003s FAILED (failures=1)"}

### thoughts of the same run
{"step": 1, "tool": "list_files", "args": {}, "thought": "Find the implementation of deep_merge in merge.py", "ok": true, "result": "settings/__init__.py\nsettings/merge.py\ntests/__init__.py\ntests/t
{"step": 2, "tool": "list_files", "args": {}, "thought": "Search for the deep_merge function in merge.py", "ok": true, "result": "settings/__init__.py\nsettings/merge.py\ntests/__init__.py\ntests/test
{"step": 3, "tool": "list_files", "args": {}, "thought": "Search for the deep_merge function in merge.py using a regex pattern", "ok": true, "result": "settings/__init__.py\nsettings/merge.py\ntests/_

في كل خطوة كتب النموذج في الحقل thought أنه يريد أن يبحث عن الدالة، ثم اختار الأداة list_files، وهي أول بديل في المخطط، ثلاث مرات حتى أوقفه كشف التكرار. ولم نجد في هذا المختبر سبباً مؤكداً لذلك، فالطلب الصغير اختار البديل الثالث بشكل صحيح، ولكن الدرس العملي واضح: المخطط الأكثر صرامة على الورق أفشل الوكيل كله مع هذا النموذج، فلا تقم بتغيير شكل الرد دون أن تشغل الوكيل على مهام حقيقية بعده.

  1. المعاملات في كائن حر args: المخطط يفرض ثلاثة حقول فقط: thought وtool من القائمة وargs كائناً بأي مفاتيح، ثم يفحص الكود المعاملات المطلوبة لكل أداة ويرجع خطأ يذكرها بالاسم. وهذا هو الشكل الذي استقر عليه الإصدار الثالث، وسوف نرى نتائجه بعد قليل.
  2. استدعاء الأدوات الأصلي: مع qwen3 كتب الطلب في الحقل الصحيح وبالمعاملات الصحيحة، ولكن ظهرت مشكلة أخرى في سجله، وهي التي جعلتنا نغير أداة التعديل:
[5] read_file {"path": "shop/pricing.py"} ->    1  DISCOUNT_FROM = 500  (1488 in / 55 out, 63 s)
[6] replace {"path": "shop/pricing.py", "old": "      if total > DISCOUNT_FROM:", "new": "      if total >= DISCOUNT_FROM:"} -> ERROR: old text found 0 times in shop/pricing.py, it must appear exactly once; read the fi  (1668 in / 131 out, 123 s)
[7] search {"pattern": "if total > DISCOUNT_FROM"} -> shop/pricing.py:7: if total > DISCOUNT_FROM:  (1857 in / 77 out, 40 s)
[8] replace {"path": "shop/pricing.py", "old": "      if total > DISCOUNT_FROM:", "new": "      if total >= DISCOUNT_FROM:"} -> ERROR: old text found 0 times in shop/pricing.py, it must appear exactly once; read the fi  (1960 in / 82 out, 115 s)
stop: stuck (same call, same result, 3 times) | steps 8 | 637 s | tokens in 11076, out 729
{"visible": true, "hidden": false, "visible_detail": "Ran 2 tests in 0.000s OK", "hidden_detail": "Ran 3 tests in 0.001s FAILED (failures=1)"}

[exited with code 0]

النموذج طلب استبدال السطر if total > DISCOUNT_FROM: بست مسافات في أوله، والسطر في الملف فيه أربع مسافات فقط. ومن أين جاءت المسافتان؟ من الأداة read_file نفسها، فهي تعرض كل سطر برقمه ثم مسافتين ثم السطر، والنموذج نسخ جزءاً من هذا الفاصل مع السطر. فالخطأ هنا ليس خطأ النموذج وحده، وإنما خطأ في الواجهة التي صممناها له، ولذلك أضفنا إلى replace المحاولة الثانية التي تقارن الأسطر دون المسافات في أولها، وتكتب السطر الجديد بمسافات الملف نفسه، وهذا ما تفعله أغلب الأدوات التي تستعمل الاستبدال النصي بطريقة أو بأخرى.

والشكل التالي يبين الخطأ والإصلاح خطوة خطوة:

أربع خطوات: ما يراه النموذج من read_file، أي رقم السطر ثم مسافتان ثم السطر؛ ثم ما طلبه النموذج وفيه ست مسافات بدل أربع فوجد 0 مرة؛ ثم المحاولة الثانية التي تقارن الأسطر دون المسافات في أولها؛ ثم النتيجة الحقيقية replaced lines 7-7 matched without leading spaces ونجاح الاختبارات
المسافتان الزائدتان جاءتا من طريقة عرض الملف، والإصلاح في أداة التعديل لا في النموذج.
📌
طريقة عرض الملف للنموذج جزء من أداة التعديل. إذا عرضت الأسطر بأرقامها فتوقع أن ينسخ النموذج جزءاً من الرقم أو الفاصل، وقد رأينا في المختبر نسخة أسوأ من ذلك: النموذج qwen2.5-coder:3b أعاد كتابة ملف كامل بالأداة write_file ومعه أرقام الأسطر في أول كل سطر، فأصبح الملف كوداً غير صالح. فإما أن تفصل الرقم عن السطر بفاصل واضح لا يشبه المسافات مثل Tab، كما تفعل أدوات كثيرة بصيغة cat -n، وإما أن تنظف المدخل في أداة الكتابة، والأفضل أن تفعل الاثنين.

والشكل التالي يلخص الإصدارات الثلاثة، وما الذي أفشل كل واحد منها، وما الذي غيرناه بعده:

ثلاثة أعمدة v1 وv2 وv3. تحت v1: قرأ app.py من مثال التعليمات وأعلن الانتهاء دون تغيير، وغيرنا بعده خريطة المستودع والمثال ورفض الانتهاء دون تغيير. تحت v2: المخطط المسطح جعل qwen3 يضع النص في pattern، ورسالة الخطأ لا تشرح، وغيرنا بعده المعاملات في كائن args وفحص المعاملات والمقارنة دون المسافات. تحت v3: ما بقي هو نسخ أرقام الأسطر والمهام التي تحتاج أكثر من تعديل
كل إصدار أصلح ما كشفه التشغيل السابق، وكل إصلاح كان في بيئة التشغيل لا في النموذج.

الإصدار الثالث: النتائج على خمس مهام

شغلنا الإصدار الثالث على المهام الخمس بالنموذجين في الوضع json بالمخطط args، ثم جمعنا النتائج بالسكربت summarize.py، والمخرج كما يلي:

label     model              task           steps   secs  tok_in   out  visible hidden  stop
json      qwen2.5-coder:3b   T01-discount       5    138    2850   219  pass    FAIL    finished (tests passed)
json      qwen2.5-coder:3b   T02-duration       8    301    7412   723  FAIL    FAIL    stuck (same call, same result, 3 times)
json      qwen2.5-coder:3b   T05-merge          5    102    2754   165  FAIL    FAIL    stuck (same call, same result, 3 times)
json      qwen2.5-coder:3b   T07-retry          7     59    5471   300  FAIL    FAIL    stuck (same call, same result, 3 times)
json      qwen2.5-coder:3b   T09-median         5     29    3080   153  pass    FAIL    stuck (same call, same result, 3 times)
json      qwen3:4b-instruct  T01-discount      12    227   12241   957  pass    pass    finished (tests passed)
json      qwen3:4b-instruct  T02-duration       8    193    7199   704  FAIL    FAIL    stuck (same call, same result, 3 times)
json      qwen3:4b-instruct  T05-merge          7    147    4867   549  pass    pass    finished (tests passed)
json      qwen3:4b-instruct  T07-retry         14    982   12298   714  pass    FAIL    max steps
json      qwen3:4b-instruct  T09-median        14    813   14415   755  pass    FAIL    max steps

في الجدول أعلاه لاحظ التالي:

  • qwen3:4b-instruct حل مهمتين من خمس بالاختبارات المخفية، T01 وT05، وqwen2.5-coder:3b لم يحل أي مهمة، رغم أنه حل T01 نفسها في الإصدار الثاني. والفرق بين التشغيلين تغيير في نص التعليمات وشكل الرد فقط، وهذا وحده سبب كاف لأن لا تحكم على وكيل بتشغيل واحد، وهو موضوع مقال القياس في هذه المرحلة.
  • العمود visible ناجح في ست تشغيلات، والعمود hidden ناجح في اثنتين فقط. أي أن الاختبارات الظاهرة وحدها كانت ستقول لك إن الوكيل نجح في ثلاثة أضعاف ما نجح فيه فعلاً.
  • سبب التوقف يقول الكثير: qwen2.5-coder توقف عالقاً في أربع مهام بعد 5 إلى 8 خطوات، أما qwen3 فوصل إلى حد الخطوات الأربع عشرة في مهمتين وهو يبحث ويبحث دون أن يعدل أي شيء.

والتشغيل الذي نجح فيه qwen3 في المهمة الأولى يبين ثلاثة أجزاء من بيئة التشغيل وهي تعمل معاً في تشغيل واحد:

task: Orders of exactly 500 SAR do not get the 10% discount.
model: qwen3:4b-instruct, mode: json, budget: 14 steps, 900 s
[1] search {"pattern": "def final_total"} -> shop/pricing.py:5: def final_total(total):  (382 in / 40 out, 13 s)
[2] read_file {"path": "shop/pricing.py"} ->    1  DISCOUNT_FROM = 500  (445 in / 39 out, 9 s)
[3] read_file {"path": "tests/test_pricing.py"} ->    1  import unittest  (594 in / 53 out, 12 s)
[4] search {"pattern": "test_big_order"} -> tests/test_pricing.py:6: def test_big_order(self):  (762 in / 43 out, 11 s)
[5] search {"pattern": "total > DISCOUNT_FROM"} -> shop/pricing.py:7: if total > DISCOUNT_FROM:  (832 in / 58 out, 12 s)
[6] replace {"path": "shop/pricing.py", "old": "if total > DISCOUNT_FROM:", "new": "if total >= DISCOUNT_FROM:"} -> replaced 25 chars with 26 chars in shop/pricing.py  (917 in / 98 out, 19 s)
[7] read_file {"path": "tests/test_pricing.py"} ->    1  import unittest  (1044 in / 48 out, 12 s)
[8] search {"pattern": "final_total\\(500\\)"} -> no match  (1224 in / 57 out, 16 s)
[9] replace {"path": "tests/test_pricing.py", "old": "self.assertEqual(final_total(600), 54...", "new": "self.assertEqual(final_total(500), 45..."} -> ERROR: tests are read-only for the agent: tests/test_pricing.py  (1296 in / 121 out, 24 s)
[10] run_tests {"tool": "run_tests", "thought": "Run the tests to verify that the upda..."} -> PASSED  (1445 in / 91 out, 24 s)
[11] finish {"tool": "finish", "thought": "The tests have passed after modifying..."} -> ERROR: finish needs the arguments summary; you sent tool, thought  (1570 in / 134 out, 32 s)
[12] finish: Modified the discount condition in pricing.py to apply the 10% discount at exactly 500 SAR and above by changing the condition from 'total > DISCOUNT_FROM' to '
    tests: PASSED  (43 s)
stop: finished (tests passed) | steps 12 | 227 s | tokens in 12241, out 957
---- patch.diff
--- a/shop/pricing.py
+++ b/shop/pricing.py
@@ -4,6 +4,6 @@
 
 def final_total(total):
     """Total after discount, rounded to 2 decimals."""
-    if total > DISCOUNT_FROM:
+    if total >= DISCOUNT_FROM:
         total = total * (1 - DISCOUNT_RATE)
     return round(total, 2)

{"visible": true, "hidden": true, "visible_detail": "Ran 2 tests in 0.000s OK", "hidden_detail": "Ran 3 tests in 0.000s OK"}

في المخرج أعلاه لاحظ التالي:

  • في الخطوة السادسة كتب الإصلاح الصحيح، ثم في الخطوة التاسعة حاول أن يعدل ملف الاختبارات نفسه ليضيف حالة 500، فرفضت الدالة path الطلب بالرسالة «الاختبارات للقراءة فقط». وهذا رغم أن التعليمات تقول صراحة لا تعدل الاختبارات، فالقاعدة المكتوبة للنموذج لم تمنعه، والفحص في الكود هو الذي منعه.
  • في الخطوتين العاشرة والحادية عشرة وضع النموذج اسم الأداة والتفكير داخل args بدل المعاملات، فرجع له خطأ يقول إن finish تحتاج summary، فأرسل الطلب الصحيح في الخطوة التالية. ولو كانت الرسالة «خطأ في المعاملات» فقط لما عرف ما الذي ينقصه.
  • قبل أن تقبل بيئة التشغيل الانتهاء شغلت الاختبارات بنفسها، والسطر tests: PASSED هو نتيجتها وليس كلام النموذج.

أما المهمة الثانية مع qwen2.5-coder فتبين المشكلة التي ذكرناها في الصندوق السابق، أي نسخ أرقام الأسطر إلى الملف:

task: parse_duration only understands minutes like "45m".
model: qwen2.5-coder:3b, mode: json, budget: 14 steps, 900 s
[1] search {"pattern": "def parse_duration"} -> timeparse/durations.py:1: def parse_duration(text):  (405 in / 37 out, 18 s)
[2] read_file {"path": "timeparse/durations.py"} ->    1  def parse_duration(text):  (468 in / 40 out, 16 s)
[3] write_file {"path": "timeparse/durations.py", "content": "   1  def parse_duration(text):\n   2 ..."} -> wrote 354 chars to timeparse/durations.py  (591 in / 160 out, 62 s)
[4] run_tests {} -> FAILED (exit 1)  (778 in / 40 out, 20 s)
[5] replace {"path": "timeparse/durations.py", "old": "\t", "new": " "} -> ERROR: old text found 0 times in timeparse/durations.py, it must appear exactly once; read  (1042 in / 58 out, 32 s)
[6] write_file {"path": "timeparse/durations.py", "content": "   1  def parse_duration(text):\n   2 ..."} -> wrote 354 chars to timeparse/durations.py  (1142 in / 173 out, 70 s)
[7] run_tests {} -> FAILED (exit 1)  (1360 in / 42 out, 18 s)
[8] write_file {"path": "timeparse/durations.py", "content": "   1  def parse_duration(text):\n   2 ..."} -> wrote 354 chars to timeparse/durations.py  (1626 in / 173 out, 65 s)
stop: stuck (same call, same result, 3 times) | steps 8 | 301 s | tokens in 7412, out 723
---- patch.diff
--- a/timeparse/durations.py
+++ b/timeparse/durations.py
@@ -1,5 +1,8 @@
-def parse_duration(text):
-    """Number of seconds in a duration such as "45m"."""
-    if not text.endswith("m"):
-        raise ValueError("unsupported duration: %r" % text)
-    return int(text[:-1]) * 60
+   1  def parse_duration(text):
+   2      if not text.endswith('m'):
+   3          if not text.endswith('h'):
+   4              if not text.endswith('s'):
+   5                  raise ValueError('unsupported duration: %r' % text)
+   6              return int(text[:-1]) * 60
+   7          return int(text[:-1]) * 3600
+   8      return int(text[:-1]) * 60

{"visible": false, "hidden": false, "visible_detail": "Ran 1 test in 0.000s FAILED (errors=1)", "hidden_detail": "Ran 1 test in 0.000s FAILED (errors=1)"}

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

والمهمتان اللتان وصل فيهما qwen3 إلى حد الخطوات تبينان نوعاً آخر من التعلق لا يكشفه كشف التكرار، وهذا جزء من المهمة T09:

task: Add a --median option to the stats command.
model: qwen3:4b-instruct, mode: json, budget: 14 steps, 900 s
[1] search {"pattern": "def main"} -> report/cli.py:5: def main(argv=None):  (396 in / 53 out, 70 s)
[2] search {"pattern": "def mean"} -> report/stats.py:1: def mean(values):  (470 in / 48 out, 39 s)
[3] search {"pattern": "median"} -> no match  (541 in / 49 out, 40 s)
[4] read_file {"pattern": "report/cli.py"} -> ERROR: read_file needs the arguments path; you sent pattern  (604 in / 52 out, 34 s)
[5] read_file {"path": "report/cli.py"} ->    1  import argparse  (681 in / 51 out, 66 s)
[6] read_file {"path": "report/stats.py"} ->    1  def mean(values):  (881 in / 47 out, 75 s)
[7] read_file {"path": "tests/test_cli.py"} ->    1  import io, unittest  (980 in / 49 out, 56 s)
[8] search {"pattern": "median"} -> no match  (1155 in / 49 out, 36 s)
[9] search {"pattern": "def main"} -> report/cli.py:5: def main(argv=None):  (1236 in / 54 out, 23 s)
[10] search {"pattern": "action=store_true"} -> no match  (1330 in / 63 out, 87 s)
[11] search {"pattern": "nargs\\+"} -> no match  (1407 in / 68 out, 70 s)
[12] search {"pattern": "print\\("} -> report/cli.py:11: print(mean(a.values))  (1490 in / 55 out, 30 s)
[13] search {"pattern": "mean\\("} -> report/cli.py:11: print(mean(a.values))  (1570 in / 58 out, 28 s)
[14] search {"pattern": "def mean"} -> report/stats.py:1: def mean(values):  (1674 in / 59 out, 158 s)
stop: max steps | steps 14 | 813 s | tokens in 14415, out 755
---- patch.diff
(no change)
{"visible": true, "hidden": false, "visible_detail": "Ran 1 test in 0.002s OK", "hidden_detail": "Ran 1 test in 0.000s FAILED (errors=1)"}

أربع عشرة خطوة، ثلاث منها قراءة ملفات، والباقي بحث بأنماط مختلفة، ولا تعديل واحد. وكشف التكرار لم يتدخل لأن كل طلب يختلف عن السابق في النمط، والذي أوقفه هو حد الخطوات وحده. ولذلك تحتاج بيئة التشغيل حداً ثالثاً غير التكرار والخطوات، مثل «عدد الخطوات دون أي تعديل»، فإذا مرت ست خطوات قراءة وبحث دون تغيير أضافت تنبيهاً يقول للنموذج إن عليه أن يبدأ التعديل أو يشرح لماذا لا يستطيع.

ثم شغلنا الوكيل نفسه في الوضع tools، أي باستدعاء الأدوات الأصلي في Ollama بدل الرد المنظم، على مهمتين لكل نموذج، والنتيجة في آخر الجدول نفسه، ومعها سطر أخير لتشغيل سوف نشرحه في القسم التالي:

tools     qwen2.5-coder:3b   T01-discount       4    984    2653   387  pass    FAIL    time budget
tools     qwen2.5-coder:3b   T02-duration       3   1048    3527  1155  FAIL    FAIL    stuck (same call, same result, 3 times)
tools     qwen3:4b-instruct  T01-discount       6    617    7214   681  pass    pass    finished (tests passed)
tools     qwen3:4b-instruct  T05-merge          7    752    8538   788  pass    pass    finished (tests passed)
noverify  qwen2.5-coder:3b   T07-retry          7     96    5222   255  pass    FAIL    stuck (same call, same result, 3 times)

والفرق هنا واضح لدرجة أنه يغير قرار التصميم كله. qwen2.5-coder لم يستعمل الحقل tool_calls ولا مرة، وهذا أول تشغيل له:

task: Orders of exactly 500 SAR do not get the 10% discount.
model: qwen2.5-coder:3b, mode: tools, budget: 14 steps, 900 s
[1] None {} -> ERROR: no tool call in the reply (text: '{"name": "read_file", "arguments": {"path": "shop  (695 in / 187 out, 560 s)
[2] None {} -> ERROR: no tool call in the reply (text: '{"name": "list_files", "arguments": {}}'). Call o  (951 in / 13 out, 30 s)
[3] None {} -> ERROR: no tool call in the reply (text: '{"name": "read_file", "arguments": {"path": "shop  (1007 in / 187 out, 395 s)
stop: time budget | steps 4 | 984 s | tokens in 2653, out 387
---- patch.diff
(no change)
{"visible": true, "hidden": false, "visible_detail": "Ran 2 tests in 0.001s OK", "hidden_detail": "Ran 3 tests in 0.010s FAILED (failures=1)"}

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

أما qwen3:4b-instruct فحل المهمتين في الوضع tools، وهذا تشغيل المهمة الأولى:

task: Orders of exactly 500 SAR do not get the 10% discount.
model: qwen3:4b-instruct, mode: tools, budget: 14 steps, 900 s
[1] list_files {} -> shop/__init__.py  (807 in / 72 out, 33 s)
[2] read_file {"path": "shop/pricing.py"} ->    1  DISCOUNT_FROM = 500  (914 in / 60 out, 46 s)
[3] read_file {"path": "tests/test_pricing.py"} ->    1  import unittest  (1082 in / 108 out, 86 s)
[4] replace {"path": "shop/pricing.py", "old": "      if total > DISCOUNT_FROM:", "new": "      if total >= DISCOUNT_FROM:"} -> replaced lines 7-7 in shop/pricing.py (matched without leading spaces)  (1303 in / 187 out, 214 s)
[5] run_tests {} -> PASSED  (1520 in / 34 out, 29 s)
[6] finish: Fixed the issue where orders of exactly 500 SAR did not get the 10% discount. Changed the condition in the final_total function from 'total > DISCOUNT_FROM' to 
    tests: PASSED  (208 s)
stop: finished (tests passed) | steps 6 | 617 s | tokens in 7214, out 681
---- patch.diff
--- a/shop/pricing.py
+++ b/shop/pricing.py
@@ -4,6 +4,6 @@
 
 def final_total(total):
     """Total after discount, rounded to 2 decimals."""
-    if total > DISCOUNT_FROM:
+    if total >= DISCOUNT_FROM:
         total = total * (1 - DISCOUNT_RATE)
     return round(total, 2)

{"visible": true, "hidden": true, "visible_detail": "Ran 2 tests in 0.000s OK", "hidden_detail": "Ran 3 tests in 0.000s OK"}

لاحظ الخطوة الرابعة: النموذج طلب الاستبدال بست مسافات في أول السطر، كما فعل في التجربة التي دفعتنا إلى تغيير أداة التعديل، ولكن هذه المرة رجعت الأداة بالعبارة matched without leading spaces، أي أن المحاولة الثانية في replace وجدت السطر وكتبته بمسافات الملف، ثم نجحت الاختبارات الظاهرة والمخفية. فالإصلاح الذي أضفناه في بيئة التشغيل هو الذي حول هذا التشغيل من فشل بالتكرار إلى نجاح في ست خطوات.

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

مصفوفة بالمهام الخمس في الأعمدة وثلاثة صفوف: qwen2.5-coder في الوضع json، وqwen3 في الوضع json، والنموذجان في الوضع tools. كل خانة فيها نتيجة الاختبارات الظاهرة والمخفية وسبب التوقف وعدد الخطوات
النتائج الحقيقية للإصدار الثالث: الاختبارات الظاهرة تنجح أكثر بكثير من المخفية.

ماذا لو ترك الوكيل يقرر بنفسه أنه انتهى؟

في minicode لا يكفي أن يقول النموذج إنه انتهى، فبيئة التشغيل تشغل الاختبارات بنفسها وترفض الانتهاء إذا فشلت أو إذا لم يتغير أي ملف. وقد يتساءل البعض: هل هذا الفحص ضروري فعلاً، أم يعرف النموذج متى ينتهي؟ والمختبر أجاب عن ذلك ثلاث مرات. ففي الإصدار الأول، قبل فحص «لم يتغير شيء»، أعلن qwen2.5-coder الانتهاء في الخطوة الثالثة دون أي تعديل، وقبلت بيئة التشغيل لأن الاختبارات الظاهرة كانت ناجحة أصلاً، كما رأينا. وفي الإصدار الثاني حاول النموذج نفسه أن ينهي المهمة الثانية والاختبارات فاشلة، ورسالته نفسها تقول إنه لم يغير شيئاً، فرفضت بيئة التشغيل:

[6] finish {"summary": "No changes were made to the `parse_du..."} -> You cannot finish yet: the tests fail.  (921 in / 55 out, 8 s)

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

ثم شغلنا المهمة T07 مرة إضافية بالخيار --no-verify-finish، أي أن بيئة التشغيل تقبل أي طلب انتهاء كما هو، لنرى هل يعلن النموذج النجاح دون أن يصلح شيئاً. والنتيجة في آخر سطر من جدول النتائج: النموذج لم يصل إلى طلب الانتهاء أصلاً، وإنما قرأ الملفين بالتناوب حتى أوقفه كشف التكرار في الخطوة السابعة، دون أي تغيير. أي أن هذا التشغيل لم يختبر الفحص، ولكنه يذكرنا بأن نموذجاً صغيراً قد يفشل بطرق كثيرة قبل أن يصل إلى لحظة الانتهاء.

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

أين تذهب التوكنات والوقت؟

انظر مرة أخرى إلى عمودي tok_in وout في جدول النتائج، فستجد أن التوكنات الخارجة من النموذج في كل تشغيل بين 150 و1000 تقريباً، أما الداخلة فبين 2,700 و14,400. والسبب أن كل خطوة ترسل المحادثة كلها من جديد: تعليمات النظام وخريطة المستودع والمشكلة، ثم كل طلب سابق ونتيجته، فالخطوة الرابعة عشرة تحمل الخطوات الثلاث عشرة قبلها. وفي المهمة الأولى مع qwen3 مثلاً بدأت الخطوة الأولى بـ 382 توكناً ووصلت الحادية عشرة إلى 1,570، ومجموع الداخل في التشغيل كله 12,241 مقابل 957 خارجة.

وهذا يعني ثلاثة أشياء عملية:

  • عند أي مزود سحابي يحاسب بالتوكن، تكلفة الوكيل في التوكنات الداخلة أولاً، والخطوات المتأخرة أغلى من الأولى، فالوكيل الذي يدور 14 خطوة في بحث لا ينتهي يكلف أكثر من ضعف الوكيل الذي أنهى المهمة في 7 خطوات. وقد شرحنا حساب ذلك بالأسعار الرسمية في مقال تكلفة وكلاء البرمجة.
  • الذاكرة المؤقتة للطلب Prompt Caching تخفض هذا كثيراً إذا بقيت بداية المحادثة كما هي، ولذلك وضعنا خريطة المستودع في أول رسالة ولم نغيرها، ولا يحذف minicode شيئاً من وسط المحادثة، كما شرحنا في مقال هندسة السياق.
  • كل نتيجة أداة تقص عند 2,500 حرف، وهذا ما منع ملف اختبارات طويل أو مخرج خطأ طويل من أن يضاعف الداخل في كل خطوة بعده.

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

كيف تشغل المختبر على جهازك؟

المختبر كله يعمل بـ Docker دون أي تثبيت على الجهاز، ويحتاج قرابة 5 GB على القرص للنموذجين، وذاكرة RAM بقدر 8 GB على الأقل لتحميلهما معاً. والخطوات بالترتيب كما يلي، ولاحظ أن مجلد النماذج يمكن أن يكون على أي قرص فيه مساحة:

docker network create adb-net
docker run -d --name adb-ollama --network adb-net -e OLLAMA_MAX_LOADED_MODELS=2 -e OLLAMA_KEEP_ALIVE=30m \
  -v "$PWD/ollama-models:/root/.ollama" ollama/ollama:0.40.13
docker exec adb-ollama ollama pull qwen2.5-coder:3b
docker exec adb-ollama ollama pull qwen3:4b-instruct
docker network create --internal adb-int
docker network connect adb-int adb-ollama
docker network disconnect adb-net adb-ollama
cd lab && bash run.sh

في الأوامر أعلاه لاحظ التالي:

  • الشبكة adb-int داخلية، ولذلك يبدأ Ollama على شبكة عادية adb-net لينزل النموذجين فقط، ثم نصله بالشبكة الداخلية ونفصله عن العادية، فيبقى بعد ذلك دون أي طريق إلى الإنترنت مثل الوكيل نفسه.
  • القيمة OLLAMA_MAX_LOADED_MODELS=2 تبقي النموذجين في الذاكرة معاً، فلا يعيد Ollama تحميل نموذج من القرص كلما انتقل السكربت من نموذج إلى آخر.
  • السكربت run.sh يشغل الأقسام بالترتيب، ويكتب كل قسم في ملف داخل المجلد out، وكل تشغيل يترك في data نسخة المستودع بعد الوكيل، والفرق، وسجل الخطوات trajectory.jsonl.

وإذا أردت أن تشغل مهمة واحدة فقط، فالأمر bash run-task.sh tasks/T01-discount qwen3:4b-instruct try يكفي، وتستطيع أن تضيف بعده أي خيار من خيارات الوكيل، مثل --mode tools أو --max-steps 6 أو --schema flat لتعيد تجربة من تجارب هذا المقال.

ما الذي ينقص minicode ليصبح أداة تستعملها كل يوم؟

minicode بني ليشرح، ولذلك ترك عمداً أشياء تجدها في كل أداة حقيقية، وكل واحد منها مشروع صغير إذا أردت أن تكمله:

  • Git بدل اللقطة في الذاكرة: الأدوات الحقيقية تعمل داخل مستودع Git، فتستطيع أن تحفظ كل تعديل في Commit كما يفعل Aider، أو ترجع عن خطوة واحدة، أو تعمل في Worktree منفصل لكل مهمة كما شرحنا في مقال Git مع الوكلاء.
  • أداة تراجع Undo: عندما يفسد تعديل اختباراً كان ناجحاً، فالأسهل للنموذج أن يرجع خطوة من أن يصلح فوق الخطأ.
  • إدارة السياق: minicode لا يحذف شيئاً من المحادثة، وهذا مقبول في 14 خطوة، أما في جلسة طويلة فتحتاج قصاً أو تلخيصاً كما في مقال بيئة التشغيل، مع الحفاظ على بداية المحادثة ثابتة من أجل الذاكرة المؤقتة.
  • حد للخطوات دون تعديل: كما رأينا مع qwen3، فالوكيل الذي يبحث ولا يعدل لا يكشفه كشف التكرار.
  • موافقة الإنسان: minicode يعمل وحده لأنه في صندوق، والفرق هو نقطة الموافقة الوحيدة. أما على جهازك فتحتاج سؤالاً قبل كل كتابة أو قبل كل أمر، كما في الوكلاء مفتوحة المصدر.
  • البث Streaming: على المعالج يأخذ الرد عشرات الثواني، والأدوات الحقيقية تعرض النص وهو يكتب، فلا تشعر أن البرنامج توقف.
  • أدوات من الخارج عبر MCP: قراءة التذكرة أو حالة الخدمة بدل أن تلصقها في وصف المهمة، وهذا موضوع مقال سيرفر MCP للفريق في هذه المرحلة.

ولكن قبل أن تضيف أي شيء من هذه القائمة، تذكر الدرس الذي تكرر في كل قسم من المقال: كل تغيير في بيئة التشغيل قد يحسن مهمة ويفسد أخرى، ولذلك تحتاج طريقة ثابتة لتقيس قبل وبعد، وهي موضوع مقال قياس وكلاء البرمجة.

كيف تفعل الأدوات الحقيقية هذه الأشياء؟

كل قرار في minicode له مقابل في الأدوات التي تستعملها، والفرق أن تلك الأدوات تعمل مع نماذج أكبر بكثير، فتستطيع أن تعطيها حرية أكبر:

القرارminicodeفي الأدوات المعروفة
شكل الطلبJSON بمخطط format، أو استدعاء الأدوات الأصلياستدعاء الأدوات الأصلي عند مزود النموذج، وبعض الأدوات مفتوحة المصدر تقرأ الطلب من النص أيضاً للنماذج المحلية
التعديلاستبدال نص موجود مرة واحدة، ثم مقارنة دون المسافاتأداة استبدال نصي في بيئة Anthropic المرجعية، وصيغ تعديل Edit Formats متعددة في Aider
الأوامرلا توجد طرفية، فقط تشغيل الاختباراتطرفية كاملة داخل صندوق معزول مع قواعد صلاحيات، أو bash فقط كما في mini-swe-agent
معرفة المستودعقائمة الملفات والدوال بالوحدة astخريطة المستودع في Aider، وأدوات بحث يستدعيها الوكيل في Claude Code وCodex
الانتهاءبيئة التشغيل تشغل الاختبارات قبل القبولغالباً النموذج يقرر، والتحقق عليك أو على خط CI
المخرجفرق موحد في ملففرق في المحرر، أو Commit لكل تعديل في Aider، أو طلب دمج

والنقطة الأخيرة في الجدول تستحق التوقف، فالأدوات التجارية تترك قرار الانتهاء للنموذج في الغالب، لأن النموذج الكبير يعرف متى ينتهي في أغلب الأحوال، ولأن كثيراً من المهام لا اختبارات لها. وهذا يعني أن جزء التحقق في عملك مع أي وكيل هو مسؤوليتك أنت، وقد شرحنا طريقته في مقال خطط ثم نفذ ثم تحقق، وكيف تقفل الاختبارات أمام الوكيل في مقال TDD مع الوكلاء.

أخطاء شائعة عند بناء وكيل

  • أسماء حقيقية في أمثلة التعليمات: النموذج الصغير يعامل المثال كحقيقة، كما فعل مع app.py. اكتب أمثلة لا تشير إلى ملفات، أو أعطه خريطة المستودع الحقيقية.
  • الحكم بالاختبارات الظاهرة فقط: في المهام التي تنجح اختباراتها من البداية، أي تغيير صغير أو لا تغيير يبدو نجاحاً. احتفظ دائماً باختبارات لا يراها الوكيل.
  • ترك قرار الانتهاء للنموذج: النموذج يعلن الانتهاء دون أن يغير شيئاً، أو والاختبارات فاشلة، فشغل الاختبارات في بيئة التشغيل قبل أن تقبل.
  • رسالة خطأ صحيحة ولكنها لا تفيد: «وجد 0 مرة» لم تخبر النموذج أنه أرسل معاملاً باسم خاطئ. اكتب الخطأ بحيث يقول ما المطلوب وما الذي وصل.
  • تغيير شكل الرد دون قياس: المخطط الأكثر صرامة أفشل الوكيل كله مع qwen3، فأي تغيير في التعليمات أو المخطط يحتاج تشغيلاً على المهام نفسها قبل أن تعتمده.
  • قاعدة مكتوبة للنموذج دون فحص في الكود: «لا تعدل الاختبارات» في التعليمات لم تمنع qwen3 من محاولة تعديلها، والذي منعه هو الدالة path.
  • تشغيل كود النموذج على جهازك مباشرة: حتى دون طرفية، فإن تشغيل الاختبارات ينفذ ما كتبه النموذج، فضع الوكيل في Container أو جهاز افتراضي، كما شرحنا في مقال الأسرار والصندوق المعزول.

قائمة تحقق Checklist قبل أن تعتمد على وكيل بنيته بنفسك

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

تدريب عملي

  1. غير طريقة عرض read_file لتفصل رقم السطر عن السطر بحرف Tab، ثم أعد المهمة الأولى مع qwen3 في الوضع tools واحذف المحاولة الثانية من replace، ولاحظ هل تختفي مشكلة المسافات.
  2. أضف أداة undo ترجع آخر تعديل، وقس هل يستعملها النموذج عندما تفشل الاختبارات بعد تعديله.
  3. اكتب مهمة جديدة بالشكل نفسه، بوصف واختبارات ظاهرة ومخفية وحل مرجعي، وتأكد بالسكربت validate.py أنها صحيحة قبل أن تعطيها للوكيل.
  4. غير --max-steps إلى 6 ثم إلى 20 في المهمة الثانية، ولاحظ هل يتغير ما يفعله النموذج أم تتغير فقط الخطوة التي يتوقف عندها.

الخلاصة

  • وكيل البرمجة بيئة تشغيل ضيقة الهدف: خريطة للمستودع، وأداة تعديل جيدة، وتعريف للانتهاء تتحقق منه بيئة التشغيل، وفرق يراجعه إنسان.
  • كل أداة صلاحية: minicode لا يملك طرفية ولا حذفاً، والشيء الوحيد الذي يشغله هو الاختبارات، داخل صندوق لا يصل إلا إلى النموذج.
  • الإصدار الأول قرأ ملفاً اسمه من مثال التعليمات، وأعلن الانتهاء دون تغيير، فأضفنا خريطة المستودع ورفض الانتهاء دون تغيير.
  • شكل الرد يغير كل شيء: المخطط المسطح جعل qwen3 يضع النص في الحقل الخطأ، ومخطط anyOf جعله يختار الأداة الأولى دائماً، والمعاملات في كائن حر مع فحص في الكود هي التي عملت.
  • qwen2.5-coder:3b لا يستعمل حقل الأدوات الأصلي ويحتاج الرد المنظم، وqwen3:4b-instruct حل مهمتين من خمس بالرد المنظم ومهمتين من اثنتين باستدعاء الأدوات الأصلي.
  • عرض الأسطر بأرقامها جعل النماذج تنسخ المسافات أو الأرقام، والمقارنة دون المسافات في أول السطر حولت فشلاً إلى نجاح في ست خطوات.
  • في الإصدار الثالث نجحت الاختبارات الظاهرة في تسع تشغيلات من أربع عشرة والمخفية في أربع فقط، فلا تحكم على وكيل باختباراته الظاهرة.
  • كشف التكرار لا يكشف وكيلاً يبحث بأنماط مختلفة دون أن يعدل، وتحتاج لذلك حداً للخطوات دون تعديل.

وفي المقالات التالية من هذه المرحلة بإذن الله نقيس هذا الوكيل نفسه على المهام الاثنتي عشرة بأكثر من تشغيل، ونضعه في خط النشر CI، ونجعله جزءاً من فريق وكلاء يبني منصة صغيرة:

دليلكيف تقيس وكيل البرمجة؟ SWE-bench ومهام فريقكما الذي تقيسه أرقام SWE-bench ولماذا توقفت OpenAI عن نشرها، وكيف تبني أداة قياس صغيرة من تذاكر فريقك باختبارات مخفية، مع تجربة حقيقية لإعدادين على 12 مهمة.دليلوكيل في خط النشر CI: مراجعة وإصلاح تلقائي مع موافقة بشريةخط نشر على Gitea Actions يراجع فيه نموذج محلي كل طلب دمج دون أي سر، ولا يصلح الكود إلا بعد وسم يضيفه إنسان، ثم يفتح طلب دمج جديداً يراجعه إنسان، مع سجلات حقيقية للتجربة.دليلفريق وكلاء Multi-agent يبني منصة: ماذا نجح وماذا فشل؟تجربة كاملة: مخطط وثلاثة مبرمجين ومراجع بنماذج محلية يبنون خدمة لاختصار الروابط من مواصفة، ثم نحكم عليها باختبارات قبول مخفية ونقارن بعقد كتبه إنسان وبوكيل واحد.دليلابن سيرفر MCP لفريقك: أدوات الشركة في يد الوكيلسيرفر MCP واحد للفريق بلغة Python، فيه توكن لكل شخص ونطاقات للقراءة والكتابة وحد للمعدل وسجل تدقيق، وماذا فعل وكيل محلي قرأ تذكرة فيها تعليمات مخفية.

سجل التحديثات

  • 21 نوفمبر 2026: كتابة المقال، وتشغيل المختبر على Ollama 0.40.13 بالنموذجين qwen2.5-coder:3b وqwen3:4b-instruct، وPython 3.13.18 في Docker.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.