بقلم: ليلى | محررة أدوات المطورين · صوت تحريري بإشراف بشري
المشكلة التي يعرفها كل مطوّر يعمل مع وكلاء الكود: الوكيل يزحف عبر الملفات بشكل أعمى، يخمّن المراجع من مطابقة النصوص، ويختار الاختبارات بعد فوات الأوان. Open Kioku — أداة مفتوحة المصدر تُكتب اختصاراً ok — جاءت لتحل هذا تحديداً، بمنح Claude وCursor وCodex وأي وكيل متوافق مع MCP طبقةً من الأدلة المفهرسة قبل أن يلمس ملفاً واحداً.
الفكرة الجوهرية بسيطة: بدلاً من أن يحرق الوكيل التوكنات في تمشيط المشروع، يحصل على فهرس محلي مسبق يشمل الرموز والمراجع وتحليل الأثر والاختبارات المرتبطة، ثم يبني خطة تعديل مبنية على أدلة فعلية. الفهرس يُخزَّن محلياً في قاعدة بيانات SQLite وبيانات بحث Tantivy تحت مجلد .ok/، ولا يُرسَل شيء خارج الجهاز.
في اختبار علني على مستودع حقيقي، فهرس Open Kioku أكثر من 4,600 ملف، وأكثر من 46,000 رمز، وأكثر من 8,900 اختبار محلياً في 33.1 ثانية (وفقاً لـ Open Kioku GitHub). هذه الأرقام مسجّلة في docs/large-repo-proof.md مع تفاصيل الإصدار والتحفظات ومحدودية اللغات.
للبدء مع أي مستودع، ثلاثة أوامر تكفي:
- تثبيت الأداة عالمياً عبر npm:
npm install -g open-kioku— الحزمة متاحة على npm وتدعم المنصات darwin-x64 وdarwin-arm64 وlinux-x64 وlinux-arm64 وwin32-x64، إلى جانب التثبيت عبرcargo binstall open-kioku-cliأو مباشرةً من GitHub Releases مع checksums SHA-256. - فهرسة المستودع:
ok index .— تكتب البيانات في.ok/index.sqliteللمعاملات والرسم البياني، وفي.ok/search/tantivyلبحث BM25. مراحل التقدم مرئية: scan → parse → occurrences → store → graph → search → complete. - ربط الوكيل:
ok mcp install cursor --repo .أو استبدالcursorبـclaudeأوcodexأوgeminiأوwindsurfأوtraeأوzedأوopencode. بعدها تلصق إعدادات MCP المطبوعة في واجهة الوكيل. - توجيه الوكيل بالاستخدام الصحيح عبر هذا الـ prompt: “Use Open Kioku before editing. Check repo_status, search_code, get_definition, get_references, impact_analysis, and find_tests_for_change. Build a plan with plan_change first, then edit, and verify after the edit with verify_change.”
- التحقق من الجودة والمشاركة:
ok prove . --task "المهمة"ينتج تقريراً بـ Markdown أو HTML يتضمن أعداد الفهرسة ودرجات المهام وإشارات التحقق — مصمَّم للمشاركة دون كشف مقاطع الكود الأصلية. - إبقاء الفهرس حياً أثناء التعديل:
ok watch /path/to/repoيتابع التغييرات ويحدّث الفهرس تلقائياً.
ما يحصل عليه الوكيل من هذا الفهرس هو سلسلة متكاملة: search_code ثم get_definition ثم impact_analysis ثم find_tests_for_change ثم plan_change ثم verify_change. على المستودع التجريبي المرفق مع الأداة، تُنتج مهمة token المثالية خطةً تحدد الملفات الأساسية في src/auth.rs وsrc/lib.rs وtests/auth_flow.rs، وتقترح اختبارات التحقق مثل issue_token وvalidate_token وlogin_returns_valid_token عبر cargo test، مع حدود تعديل تستثني الملفات المُولَّدة والـ vendored والـ build ومجلد .ok/.
الأداة تدعم أيضاً تحليل تاريخ Git محلياً بشكل افتراضي، إذ تقرأ نافذة محدودة من الـ commits وتُنتج إشارات مثل history_churn وownership_risk وsimilar_change_overlap وreviewer_affinity، مع إمكانية ضبط النافذة عبر [history] max_commits = 500 في ok.toml أو تعطيلها كلياً. أما تحليل الـ runtime فهو اختياري بالكامل: تضع ملفات JSONL تحتوي على traces وlogs وأخطاء في .ok/runtime/، ويحوّلها open-kioku إلى إشارات سياق وترتيب، دون أن تحل محل أدلة المصدر والرموز.
للفرق والـ CI، تدعم الأداة مفهوم Index Snapshots: تصدير فهرس معتمد ومشاركته بين أعضاء الفريق دون مشاركة الذاكرة الشخصية أو الحالة المضغوطة. كما تدعم Multi-Project Workspace لربط خدمات متعددة عبر ملف workspace config وأمر ok index --mode cross-project. وتقبل Open Kioku تقارير تغطية الاختبارات بصيغ JUnit XML وlcov وCobertura وJaCoCo وcoverage.py من مسارات قياسية متعددة، وتربطها بالرموز والاختبارات المفهرسة كـ TEST_COVERS/VALIDATES في الرسم البياني.
القيد الواضح الذي لا تُخفيه الأداة: الدقة ترتفع بشكل ملحوظ مع توفر SCIP — بروتوكول فهرسة الرموز الدقيقة. تعمل الأداة بجودة معقولة بدونه، لكن ok scip setup يرفع مستوى التحليل في البحث وتحديد الأثر واختيار الاختبارات. وعند غياب أدلة معينة — مراجع دقيقة، بيانات runtime، تغطية الاختبارات — تُفصح الخطة صراحةً عن هذه الثغرات بدلاً من ملئها بتخمينات.
من منظور عملي، هذا هو السلوك الصحيح: وكيل يعرف حدود معرفته أفضل من وكيل واثق بشكل زائف. إن كنت تعمل مع Cursor أو Claude Code وتجد الوكيل يُعيد اكتشاف نفس الملفات مراراً أو يُصلح الأعراض بدلاً من الجذور، فإن طبقة أدلة مثل Open Kioku تحل هذه المشكلة من المصدر لا من الأعراض.
