SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor · آخر تحديث في 2026-10-21

خريطة قاعدة الشيفرة لوكلاء البرمجة عبر MCP

يحلل Graft مستودعك باستخدام tree-sitter وينشئ خريطة دائمة من عقد Markdown ورسم بياني للرموز، ليستعلم وكيلك منها عبر MCP بدلاً من تكرار الاستكشاف.

خريطة قاعدة الشيفرة لوكلاء البرمجة

خريطة قاعدة الشيفرة لوكلاء البرمجة هي فهرس دائم لمستودعك، يرجع إليه الوكيل للبحث بدلاً من استعراض المستودع باستخدام grep من الصفر في كل جلسة جديدة. يُعد Graft أحد تطبيقات هذه الفكرة. فهو يحلل الشيفرة باستخدام tree-sitter، وينشئ مجلداً من عُقد Markdown المترابطة، بالإضافة إلى رسم بياني يوضح ترابط كل رمز، ثم يوفّر أدوات الاسترجاع عبر MCP (model context protocol، وهي الواجهة القياسية التي يستخدمها وكلاء البرمجة لاستدعاء الأدوات الخارجية).

Graft ليس proxy وليس gateway. لا يوجد أي مكوّن بين وكيلك وواجهة model API. الخريطة مجلد على القرص يقرأه الوكيل. يحدد هذا الفرق المشكلة التي تحاول حلها: بوابة رموز مستضافة ذاتياً تقيس الطلبات التي ترسلها بالفعل وتوجّهها، بينما تغيّر الخريطة عدد الطلبات التي تحتاج إلى إرسالها من الأساس.

هذه التقنية أقدم من هذه الأداة، وستستمر بعد زوالها. تعلّم التقنية أولاً، ثم تعلّم آلياتها.

لماذا تهدر وكلاء البرمجة سياقها في إعادة اكتشاف بنية المستودع

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

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

تقطع الخريطة هذه الحلقة بنقل الاكتشاف من النموذج إلى القرص. يحلل محلل المستودع مرة واحدة، ويسجل الرمز الذي يُعرَّف في كل موضع والرمز الذي يستدعي كل رمز، ثم يحافظ على تحديث هذا السجل مع تغيّر الشيفرة. يطرح الوكيل سؤالاً واحداً ويحصل على إجابة مرفقة بالملف ورقم السطر. ويتحول الاستكشاف المتكرر إلى عملية بحث منخفضة التكلفة.

أنت تستخدم بالفعل نسخة أضعف من ذلك. يوقف ملف AGENTS.md الذي يحدد اصطلاحاتك الوكيل عن إعادة اشتقاق اصطلاحاتك في كل مرة. وتوقف الخريطة المُنشأة آلياً إعادة اشتقاق بنية المستودع. والفرق هو الجهة التي تكتبها. تكتب ملف التعليمات يدوياً، لذلك يظل صغيراً. أما المحلل فينشئ الخريطة، لذلك يمكنها تغطية عشرة آلاف ملف. ولمعرفة كيفية توزيع الميزانية فعلياً داخل الجلسة، يشرح كيف ينفق Claude Code نافذة سياقه تفاصيل الحساب.

ما الذي ينشئه Graft فعلياً

ينشئ Graft مُصنَّفين، وكلاهما داخل مجلد graft/ واحد في جذر المستودع.

المُصنَّف الأول هو رسم بياني للعُقد مكتوب بصيغة Markdown مترابطة، مع ملف واحد لكل عقدة. تحتوي كل عقدة على ملخص بلغة إنجليزية واضحة، و"لبّ" أسطر المنطق المهمة المستخرجة من المصدر، وملفات المصدر الفعلية مع تجزئة للمحتوى، وروابط ويكي مكتوبة النوع إلى العقد الأخرى (depends_on وpart_of وuses وimplements)، وقسم للملاحظات يبقى بعد إعادة الإنشاء، بحيث يمكنك تسجيل السياق الذي لا يستطيع المحلل استنتاجه.

المُصنَّف الثاني هو graft/.graph/wiring.json، أي الرسم البياني البنيوي لكل رمز الذي يستخرجه tree-sitter: التعريفات، والمراجع، وحواف الاستدعاء بينها.

هذا الفصل مهم لأن نصف الناتج فقط يحتاج إلى نموذج. إن graft build يعتمد بالكامل على tree-sitter ولا يستدعي نموذجاً لغوياً كبيراً (LLM)، لذلك تكون نتائجه حتمية ولا تكلّف شيئاً. أما graft build --deep فيضيف الملخصات المكتوبة ولبّ كل رمز، وهذه تتطلب استدعاءات للنموذج تدفع تكلفتها.

دعم اللغات مقسّم إلى مستويات، ويحدد المستوى مدى ثقتك في رسم الاستدعاءات. تحصل TypeScript وJavaScript وPython وGo وJava وKotlin وPHP وSwift وR على تحليل للنطاق وحلّ للمراجع عبر الملفات. وتحصل Rust وC وC++ وC# وRuby وScala وElixir وSolidity وOCaml وZig وDart وClojure وNix وLua على الرموز وحواف الاستدعاء العامة، ما يعني أن الحافة قد تستند إلى تطابق الاسم بدلاً من مرجع محلول. وتصبح الحواف بمستوى المصرّف اختيارية باستخدام --lsp وخادم لغة مثل rust-analyzer أو gopls.

تثبيت Graft وتثبيت الإصدار

يحتاج Graft إلى Node.js 20 أو إصدار أحدث، وهو مرخّص بموجب MIT. في 17 October 2026، الإصدار الحالي هو 0.23.0، وقد نُشر في 15 October 2026، بينما يعود أول إصدار منشور، 0.1.0، إلى July 2026. تعامل معه بوصفه برنامجاً حديثاً. أعاد الإصدار 0.22.0، المنشور في 14 October 2026، تسمية المشروع إلى Trail-code: الشفرة نفسها تُنشر الآن أيضاً باسم @trailhq/trail-code مع الأمر trail، بينما يحتفظ @nanonets/graft بالأمر graft.

يثبّت هذا الدليل الإصدار 0.21.1، المنشور في 29 September 2026، وهو آخر إصدار قبل إعادة التسمية، لأن 0.22 و0.23 غيّرا الأوامر التي يعتمد عليها الدليل. بدءاً من 0.22، يقارن graft check الفروقات في فرعك مع المعارف التي جمعها الفريق في المستودع، وينتهي بالحالة 1 عند وجود تعارض. نُقلت آلية اكتشاف الانحراف إلى graft build --check، وأصبحت أدوات MCP تُسمى trail_*، بينما لا يزال الخادم يستجيب للأسماء القديمة graft_*. يذكر سجل تغييرات 0.23.0 أيضاً أنه في مستودع أُعدّ باستخدام trail، تنتقل الخريطة إلى .trail/cache/، ولا يحصل Claude Code على خادم MCP بعد الآن، بينما لا يزال README يصف graft/ و.mcp.json. اقرأ سجل التغييرات وشغّل --dry-run قبل نقل الإصدار المثبّت.

npm install -g @nanonets/graft@0.21.1
npm ls -g @nanonets/graft

يجب أن يطبع npm ls -g القيمة @nanonets/graft@0.21.1. ثبّت هذا الإصدار عن قصد. يحلّ npm install -g @nanonets/graft المجرد الوسم latest في لحظة تشغيله، ومع إصدار عدة إصدارات فرعية كل شهر، تحصل بهذه الطريقة على أداة مختلفة يوم Tuesday عن تلك التي ثبّتها زميلك يوم Monday. يحافظ الإصدار المثبّت على ثبات خيارات CLI وتنسيق الرسم البياني لدى الجميع، ولذلك تحدد أنت موعد الترقية.

بعد ذلك، اربطه بمستودع تملكه:

cd /path/to/your/repo
graft init --dry-run
graft init

يسألك graft init عن وكلاء البرمجة الذين تريد ربطهم، ثم ينشئ الرسم البياني. شغّل --dry-run أولاً واقرأ قائمة الملفات التي يخطط لتعديلها، لأن بعض هذه الملفات قد تكون خارج المستودع. عملية graft init قابلة للتكرار ولا تستبدل ملفات الإعداد الموجودة، لذلك يكون تشغيلها مرة ثانية آمناً. للتراجع، يزيل graft uninstall كل ملف وكل إدخال إعداد كتبه Graft، ويعمل في وضع التشغيل التجريبي حتى تمرر -y.

يتضمن مربع الحوار نفسه خياراً للقياس عن بُعد. منذ الإصدار 0.12.0، يرسل Graft افتراضياً إشارة استخدام مجهّلة: أعداداً مجمّعة وتسميات ثابتة، وليس شفرتك أو مسارات الملفات أو اسم المستودع. تُرسل الأحداث مرة واحدة يومياً كحد أقصى، باستثناء حدث التثبيت الذي يمرره npm عبر hook ‏postinstall إلى المرسل في الخلفية فوراً. ألغِ تحديد المربع أثناء graft init، أو شغّل graft telemetry disable، أو اضبط DO_NOT_TRACK=1 لتعطيله؛ وهو يعطّل نفسه أيضاً في CI. ويطبع graft telemetry debug الدفعة التي كان سيرسلها من دون إرسالها.

في 0.21.1، يشمل الربط Claude Code وCursor وCodex وGitHub Copilot وGoogle Gemini وKiro وWindsurf وGrok (xAI) وAdaL وHermes Agent وGoogle Antigravity. أصبح Hermes Agent مضيف graft init من الدرجة الأولى منذ الإصدار 0.13.0، وفي الإصدار المثبّت يختار graft init --agents hermes وgraft init --agents antigravity هذين المضيفين مثل أي مضيف آخر. أُضيف Grok في الإصدار 0.13.0، ويتم اختياره باستخدام graft init --agents grok. يحصل Claude Code على أعمق تكامل: إدخال لخادم MCP، وسطر حالة يعرض حجم الرسم البياني وتقادمه، وhooks بعد التعديل تعيد بناء الرسم البياني، وملف مهارة ضمن .claude/. ويحصل الباقون على ملف تعليمات أو قواعد يخبر الوكيل بوجود الأدوات؛ ويقرأ Hermes Agent وAntigravity كلاهما قسم AGENTS.md. كما يحصل Grok على كتلة MCP في ملف إعداده الخاص. لذلك تعني كلمة «مدعوم» أن Graft يكتب إعداد الربط، فإذا تجاهل وكيل ملف القواعد الخاص به فسيتجاهل الخريطة أيضاً. وهذا هو السبب المعتاد في أن يتجاهل الوكلاء التعليمات التي تكتبها لهم، وينطبق هنا كما ينطبق في أي موضع آخر.

ما الذي يُضاف إلى مستودعك وما الذي يبقى خارج git

بعد graft init، توقّع الملفات التالية:

  • graft/: الرسم البياني لعُقد Markdown وgraft/.graph/wiring.json. تتم إضافتهما إلى .gitignore تلقائياً.
  • .mcp.json: يسجّل خادم graft MCP لكي يشغّله Claude Code.
  • .claude/settings.json: يُدمج في موضعه، ويضيف statusline وpost-edit hooks.
  • AGENTS.md، GEMINI.md، .github/copilot-instructions.md، .cursor/rules/graft.mdc، .kiro/steering/graft.md، .windsurf/rules/graft.md، .grok/skills/graft/SKILL.md و.adal/skills/graft/SKILL.md: أقسام محاطة بعلامات markers تُضاف إلى الملفات المطابقة للوكلاء الذين اخترتهم.
  • .grok/config.toml: كتلة [mcp_servers.graft] على مستوى المستودع، وتُكتب فقط عند اختيار Grok.
  • ~/.codex/config.toml و~/.codex/hooks.json و~/.codex/hooks/graft/graft-hooks.cjs: ملفات على مستوى الجهاز، وتُكتب فقط عند اختيار Codex ووجود ~/.codex/ مسبقاً. يتجاوزها graft init --no-global، كما يتجاوز graft init --no-hooks وحده hook shim.

الرسم البياني عبارة عن cache، مثل node_modules. لا تُجرِ له commit. يُعاد توليده من الشيفرة خلال ثوانٍ، ويتغير مع كل تعديل تقريباً. ويؤدي إجراء commit له إلى تحويل إصلاح من سطر واحد إلى diff يضم عدة مئات من الملفات، ولن يراجعه أي مراجع. أجرِ commit لملفات الربط بدلاً من ذلك، ومنها AGENTS.md و.mcp.json. يستنسخ زميلك المستودع، ويشغّل graft build، ويحصل على رسم بياني محلي خاص به.

تحقق من إضافة قاعدة التجاهل قبل إجراء أول commit:

grep -n graft .gitignore
git status --short

يجب أن يطبع grep سطراً يحتوي على graft/، ويجب ألا يعرض git status --short أي شيء ضمن graft/. يعني ظهور ملفات ضمن graft/ في ذلك الإخراج أن إدخال التجاهل مفقود أو جرى تجاوزه في موضع آخر. أصلح ذلك قبل إجراء commit، لأن git يواصل تتبع الملف بعد إضافته، ولن يؤدي تعديل .gitignore لاحقاً إلى إلغاء تتبعه.

إذا كنت تفضّل تسجيل خادم MCP يدوياً، أو تثبيته على الإصدار نفسه الذي ثبّتَّه، فالإدخال صغير:

{
  "mcpServers": {
    "graft": {
      "command": "npx",
      "args": ["-y", "@nanonets/graft@0.21.1", "mcp"]
    }
  }
}

أدوات الاسترجاع التي يستدعيها وكيلك بدلاً من grep

يعرِض Graft ست أدوات عبر MCP. تعيد graft_find_code العقد المرتبة حسب الصلة بوصف المهمة، مع الملف ورقم السطر. تعيد graft_file_api كل توقيع في ملف من دون أجسام الدوال. وتتتبّع graft_trace_calls المتصلين أو الدوال المستدعاة عبر عدة مستويات. وتعُدّ graft_find_all نتائج المطابقة بالتعبيرات النمطية، مجمّعة حسب الرمز. وتوفّر graft_repo_map نظرة أولية على مستودع غير مألوف. وتُبلغ graft_check_freshness بما إذا كانت graph لا تزال مطابقة للشفرة.

ولكل أداة نسخة مطابقة في CLI. وهذه هي الطريقة التي تتحقق بها مما يتلقاه وكيلك فعلياً:

graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --json

يجب أن تطبع graft ask العقد المرتبة مع مراجع file:line، بدلاً من محتويات الملفات. هذه هي الآلية كلها: يتلقى الوكيل مؤشراً ويفتح ملفاً واحداً، بدلاً من قراءة عشرة ملفات للعثور على الملف الصحيح. تفتح graft viz عارضاً تفاعلياً على localhost إذا أردت فحص graph بنفسك. إذا لم تُرجع graft ask شيئاً مفيداً لسؤال يمكنك الإجابة عنه خلال ثلاثين ثانية، فلا تعِد صياغة السؤال وتطرحه مرة أخرى. قد يفشل الاسترجاع المرتب في العثور على النتيجة، ويذكر ملف المهارات الخاص بالمشروع أن النتائج الضعيفة تعني الانتقال إلى graft grep أو graft skeleton أو graft callers. وإذا لم تكن هذه الأدوات مفيدة أيضاً، فتحقق من drift عبر graft check . على الإصدار المثبّت 0.21.1، أو graft build --check بدءاً من الإصدار 0.22، وتأكد من الطبقة التي تنتمي إليها لغتك، لأن graph قديمة أو الحواف ذات الطبقة الواسعة ستؤدي إلى فشل وكيلك بالطريقة نفسها.

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

ما الذي يحدث للرسم البياني عند تغيّر التعليمات البرمجية

تحديث البنية سريع وتلقائي. يقرأ Graft شجرة العمل لديك بدلاً من git، لذلك تظهر له التعديلات التي لم تثبّتها والتعديلات التي أضفتها إلى staging بالطريقة نفسها. تبدأ كل استعلامات بفحص شجرة العمل، ثم تعيد تحليل الملفات التي تغيّرت فقط. توضّح وثائق 0.21.1 أن هذا الفحص يستغرق نحو 3 ms عندما لا يتغير شيء؛ ويذكر README الحالي بضع عشرات من المللي ثانية، أي نحو 50 ms في مستودع المشروع نفسه. في نهاية كل دورة، تصل إعادة البناء إلى الملفات التي تغيّرت فيها التعليمات البرمجية فقط. استخدم GRAFT_NO_REFRESH=1 أو مرّر --no-refresh للحصول على الإجابة من الرسم البياني الموجود على القرص من دون إعادة التحليل. مرّر --no-reuse لفرض إعادة تحليل كاملة من البداية، وهذا ما تحتاج إليه بعد ترقية Graft نفسه.

يتصرف الجزء الذي ينشئه النموذج بطريقة مختلفة، وهو الجزء الذي يتعطل بهدوء. تُخزّن الملخصات والنقاط الجوهرية مؤقتاً. تسجّل كل عقدة تجزئة محتوى لمصادرها، لذلك عند تغيّر ملف مصدر تُعلَّم العقدة بأنها قديمة بدلاً من عرضها على أنها حديثة. لا يفيد هذا العلم إلا إذا اتخذت خطوة بناءً عليه. نفّذ التحديث باستخدام graft build --deep، إذ يؤدي ذلك إلى استهلاك رموز النموذج مرة أخرى.

اجعل حالة القدم ظاهرة:

graft check .
echo $?

في الإصدار المثبّت 0.21.1، تعني حالة الخروج 0 أن الرسم البياني يطابق التعليمات البرمجية، وتعني حالة الخروج 1 وجود اختلاف. بدءاً من 0.22، يخرج graft check بالحالة 1 عند وجود تعارض مع تعلّم الفريق بدلاً من ذلك، بينما يكون فحص الاختلاف هو graft build --check، لذلك غيّر الأمر عند نقل الإصدار المثبّت. شغّله من hook ‏pre-push، حتى لا تجيب خريطة عمرها ستة أشهر بثقة عن تعليمات برمجية أُعيدت كتابتها في مارس. يصف README الخاص بالإصدار 0.21.1 graft check بأنه إشارة محلية إلى حداثة البيانات، بينما يدرج README الحالي build --check للاستخدام في CI. في كلتا الحالتين، يكون graft/ مستثنىً من git، لذلك يبدأ checkout جديد في CI من دون رسم بياني ما لم تنشئ المهمة واحداً.

اقرأ أرقام الاختبارات المنشورة بعناية

افتتح ملف README في الإصدار 0.21.1 بعبارة: "بتكلفة أقل بما يصل إلى 4x وسرعة أكبر 3x، مع دقة أفضل أو من دون خسارة في الدقة". أما ملف README الحالي فحذف هذه العبارة وبدأ بأرقام أقل: "عبر 162 تشغيلًا للوكيل نفسه على المهام نفسها: تكلفة أقل بنسبة 32%، ورموز إدخال غير مخزنة مؤقتًا أقل بنسبة 42%، ووقت أقل بنسبة 60%، مع النسبة نفسها من الإجابات الصحيحة." تستند هذه الأرقام إلى الاختبارات المعيارية الخاصة بالمشروع، والمنشورة في ملف README الخاص به. فيما يلي التشغيلان اللذان يوردهما بالتفصيل.

رسم بيانيGraft's own published benchmark results, versus a no-map baseline, as of October 2026
البيانات وراء هذا الرسم البياني
[
  {
    "label": "Controlled sweep",
    "run_count": 162,
    "token_saving_pct": 42,
    "tool_call_saving_pct": 46,
    "correctness_pct": 93,
    "baseline_correctness_pct": 93
  },
  {
    "label": "SWE-bench Verified",
    "run_count": 50,
    "token_saving_pct": 23,
    "tool_call_saving_pct": 25,
    "correctness_pct": 66,
    "baseline_correctness_pct": 54
  }
]

يتضمن المسح المنضبط 162 تشغيلًا عبر مستودعين، أحدهما مستودع Graft نفسه، مع إجراء ثلاث تجارب لكل مهمة. ويبلغ الانخفاض المبلغ عنه 42% في رموز الإدخال غير المخزنة مؤقتًا، و46% في استدعاءات الأدوات. أما تشغيل SWE-bench Verified فيشمل 50 حالة، مع استخدام النموذج نفسه في طرفي المقارنة، ويُبلغ عن انخفاض أصغر: 23% في الرموز و25% في استدعاءات الأدوات. كما كلّف تشغيل ثالث يضم 15 مهمة من PocketBase، منها عشرة أسئلة للمطورين وخمسة طلبات سحب مدمجة أعيد إنتاجها، 11.02 دولارًا أمريكيًا إجمالًا، مقابل 13.91 دولارًا للخط الأساسي.

تعامل مع كل هذه الأرقام باعتبارها نتائج اختبار معيارية من الجهة المورّدة. هناك عاملان يحدّان مما يمكنها إخبارك به. يتضمن المسح المنضبط مستودع Graft نفسه، وهو قاعدة الشيفرة التي ضبط مؤلفو الأداة أداءها عليها. أما SWE-bench Verified فهو مجموعة بيانات عامة تضم مشكلات من مشاريع Python مفتوحة المصدر معروفة، والمجموعات العامة هي التي تُحسَّن الأدوات لها، سواء كان ذلك مقصودًا أم لا. لا يمثل أي من الاختبارين مستودعك الخاص متعدد المشاريع، إذ يضم عادات تسمية خاصة به وشيفرة ميتة خاصة به.

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

قِسّ فرق الرموز الخاص بك قبل أن تصدّق أياً من ذلك

الرقم الوحيد المهم هو الرقم القادم من مستودعك. تستغرق هذه الطريقة فترة بعد الظهر.

اختر مهمة يمكنك تكرارها حرفياً. السؤال أفضل من التعديل، لأن التعديل يغيّر المستودع، وبالتالي لا تعود الجولة الثانية التجربة نفسها. السؤال «أي وحدة تفرض حد المعدل على مسار تسجيل الدخول؟» له الصيغة المناسبة.

فعّل القياس عن بُعد وأرسله إلى طرفيتك:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

يطبع مُصدِّر وحدة التحكم سجلات المقاييس عند جمعها. السجل المطلوب هو claude_code.token.usage، ويحمل سمة type بقيمة input أو output أو cacheRead أو cacheCreation. يظهر أثر التوجيه في input وcacheRead، لأن محتوى الملفات يُدرج هناك. اجمع هاتين القيمتين.

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

بعد ذلك اطرح التكاليف التي لا يعرضها الاختبار المعياري. ينفق graft build --deep رموزاً من النموذج في كل تحديث كامل. وتُرفق مخططات الأدوات الستة مع كل طلب. إذا كانت وكلاؤك يعملون على خادم تستأجره، فإن وضع سقف صارم للإنفاق على الوكلاء يحوّل ذلك من مفاجأة إلى ميزانية، بينما يوضّح ما الذي يعرضه القياس عن بُعد لوكيل البرمجة فعلياً ما يغادر الجهاز بعد تفعيل المُصدِّر.

متى تتوقف خريطة قاعدة الشيفرة عن تقديم الفائدة؟

  • عندما يتسع المستودع ضمن سياق الطلب. لا تحتاج خدمة صغيرة واحدة إلى خريطة، وستدفع مع ذلك تكلفة ستة مخططات لأدوات في كل طلب. إذا كان وكيلك يعثر اليوم على أي ملف عبر استدعاء أداة واحد أو اثنين، فتجاوز الخريطة.
  • عندما تكون لغتك ضمن الفئة العامة. قد تؤدي حواف الاستدعاء العامة إلى أن يفوّت graft callers أحد المستدعين، أو أن ينشئ مستدعياً بسبب تطابق في الاسم. أكّد النتيجة باستخدام graft grep قبل الوثوق بنطاق التأثير.
  • عندما تصبح الخريطة قديمة ولا يلاحظ أحد ذلك. في الإصدار 0.21.1 يخرج graft check بالرمز 1 عند اكتشاف اختلافات (ومن الإصدار 0.22 يفعل graft build --check ذلك)، ولا تكون هذه الآلية مفيدة إلا إذا شغّلها شيء ما. استخدم hook قبل الدفع، ولا تعتمد على عادة يدوية.
  • عندما يحتاج monorepo إلى تحديد النطاق. لا يُقسَّم monorepo واحد باستخدام git، لكن graft build يكتشف المشاريع الفرعية من pnpm-workspace.yaml، أو مساحات عمل package.json، أو go.mod أو pyproject.toml أو Cargo.toml الخاصة بكل حزمة، ويستخدمها كنطاقات لترتيب النتائج، بينما يضيّق graft ask "..." --in services/billing/ الاستعلام إلى مشروع فرعي واحد. ينطبق على الخريطة نفس المبدأ الذي يؤدي إلى استخدام ملفات AGENTS.md متداخلة لكل حزمة.
  • عندما يتجاهل الوكيل آلية الربط. راقب استدعاءات الأدوات في جلسة فعلية قبل أن تستنتج أن الخريطة مستخدمة. إذا استمر الوكيل في تشغيل grep، فهذا يعني أنه لم يقرأ ملف القواعد قط.

FAQ

هل يجب أن أضيف المجلد graft/ إلى git؟

لا. يضيف graft build ‏graft/ إلى .gitignore تلقائياً، لأن الرسم البياني ذاكرة مؤقتة قابلة لإعادة الإنشاء مثل node_modules. يتغير هذا المجلد تقريباً مع كل تعديل، لذلك تؤدي إضافته إلى إخفاء الفروقات الفعلية بين مئات الملفات المُنشأة. أضف إلى المستودع ملفات الربط التي توضّح للوكلاء وجود الخريطة، ومنها AGENTS.md و.mcp.json، ودَع كل زميل يشغّل graft build محلياً. تحقّق باستخدام grep -n graft .gitignore وgit status --short قبل أول commit، لأن git يواصل تتبّع الملف بعد إضافته، وتعديل .gitignore لاحقاً لا يوقف تتبّعه.

هل تشغيل Graft مُكلف؟

الجزء البنيوي ليس مُكلفاً. إنّ graft build وgraft ask وgraft check وأدوات الاسترجاع الست الخاصة بـMCP هي عمليات tree-sitter لا تستدعي أي نموذج. أما graft build --deep فهو الجزء المدفوع؛ إذ ينشئ الملخصات المكتوبة باللغة الإنجليزية البسيطة وملخصات crux لكل رمز عبر LLM، مع ضبطه باستخدام GRAFT_PROVIDER وGRAFT_API_KEY وGRAFT_MODEL، إضافة إلى GRAFT_BASE_URL لأي endpoint متوافق مع OpenAI. يمكنك تشغيل Graft بالهيكل فقط، ولن تستهلك أي token بسبب الرسم البياني نفسه.

كم سيوفّر رسم خريطة قاعدة الشيفرة فعلياً في مستودعي؟

لا يمكن لأحد تحديد ذلك من دون قياس. يذكر المشروع انخفاضاً بنسبة 42% في input tokens غير المخزنة مؤقتاً ضمن اختبار من 162 تشغيلات على مستودعه، وانخفاضاً بنسبة 23% في tokens على SWE-bench Verified، وذلك في الحالتين مقارنة بخط أساس لا يستخدم خريطة. هذان الرقمان ناتجان عن اختبارات يوردها المورّد؛ وقد أُجري أحد الاختبارين جزئياً على مستودع Graft نفسه، ولا يصف أي منهما شيفرتك الخاصة. شغّل سؤالاً واحداً قابلاً للتكرار ثلاث مرات مع الخريطة وثلاث مرات من دونها، مع ضبط CLAUDE_CODE_ENABLE_TELEMETRY=1 وOTEL_METRICS_EXPORTER=console، ثم قارن الوسيط في claude_code.token.usage لنوعي input وcacheRead.

ماذا يحدث للرسم البياني عند إعادة هيكلة الشيفرة؟

تعيد البنية تحليل نفسها. يفحص Graft شجرة العمل ويعيد تحليل الملفات التي تغيرت فقط، لذلك يظهر تغيير الاسم في الاستعلام التالي. عندما لا ينتقل أي شيء، تستغرق عملية التحقق نحو 3 ms في 0.21.1 وبضعة عشرات من المللي ثانية في الإصدار الحالي، كما أنها ترى التغييرات غير المُرحّلة إلى المستودع لأنها تقرأ الملفات بدلاً من سجل git. أما الملخصات التي يكتبها النموذج فهي التي تصبح قديمة؛ إذ تخزّن كل عقدة تجزئة محتوى لمصادرها، ويؤدي تغير المصدر إلى تعليم العقدة بأنها قديمة بدلاً من إعادة كتابتها. تحقّق من الانحراف باستخدام (graft check . في 0.21.1، وgraft build --check بدءاً من 0.22)، ثم شغّل graft build --deep لتحديث الجزء المكتوب.

ما وكلاء البرمجة الذين يمكنهم استخدام Graft حالياً؟

في الإصدار المثبّت 0.21.1، يربط graft init كلاً من Claude Code وCursor وCodex وGitHub Copilot وGoogle Gemini وKiro وWindsurf وGrok (xAI) وAdaL وHermes Agent وGoogle Antigravity، أي أحد عشر مضيفاً إجمالاً. يسرد سجل التغييرات Hermes Agent كمضيف من الدرجة الأولى منذ 0.13.0، كما أن hermes وantigravity هما معرّفا --agents عاديان في الإصدار المثبّت. يحصل Claude Code على أكبر قدر من التكامل: إدخال لخادم MCP في .mcp.json، وسطر حالة، وhooks بعد التعديل، وملف skill ضمن .claude/. يحصل Codex على قسم AGENTS.md، إضافة إلى إدخالات على مستوى الجهاز ضمن ~/.codex/، والتي يتجاوزها graft init --no-global. يحصل Grok على ملف skill وكتلة MCP في .grok/config.toml. يقرأ Hermes Agent وAntigravity قسم AGENTS.md، بينما تتلقى الأدوات الأخرى ملف rules أو steering. يمكن لأي عميل MCP آخر استخدام الخادم مباشرةً عبر تسجيل الأمر npx -y @nanonets/graft@0.21.1 mcp.

هل كان هذا المقال مفيدًا؟