كيفية تتبع أعطال وكلاء الذكاء الاصطناعي في قاعدة البرمجيات واستردادها
makedreamJuly 30, 2026
0
Computing/Software
Comments (0)
Log in to leave a comment
No posts yet
makedreammakedreamLog in to leave a comment
No posts yet
عند توصيل وكيل ذكاء اصطناعي مثل Claude Code أو Codex بمستودع برمجيات خلفي (Backend Repository) يتجاوز 100 ألف سطر، تنبهر في البداية بسرعه الأداء. ولكن في لحظة ما، وبمجرد إدخال موجه (Prompt) خاطئ لعدة أسطر، يخترق الذكاء الاصطناعي سياج الحماية ويمس الملفات المساعدة المشتركة أو ملفات إعدادات البيئة. تتضخم سجلات الجلسة لتصل إلى عدة ميجابايت، ويفشل البناء (Build)، وعندما تقضي ساعة كاملة في تفحص Git Diff بحثًا عن الملف المسبب للمشكلة، ينتابك شعور بأنه كان من الأفضل لو كتبت الكود بنفسك منذ البداية.
لمنح الوكيل الاستقلالية مع منع تلف الملفات غير الضروري، يلزم وجود نظام عزلمحكم وتتبع مرئي للمسار (Trace) بوضوح.
ملفات التعليمات باللغة الطبيعية مثل CLAUDE.md أو .aiignore غالباً ما يتجاهلها الوكيل عندما تتسع نافذة السياق (Context Window). فالطلبات في مرحلة الموجه ليست سوى توصيات، والمجال مفتوح أمام أدوات الوكيل لتجاوز الحدود بجرأة بمجرد فقدان السياق.
لحظر وصول الوكيل فيزياءً (فلياً)، يجب وضع محرك التحكم بالصلاحيات الحتمي .claude/settings.json مباشرة في المجلد الرئيسي للمشروع (Project Root).
`json
{
"permissions": {
"deny": [
"Edit(src/core/config/)",
"Edit(src/shared/utils/)",
"Read(./.env*)",
"Bash(rm -rf *)"
],
"ask": [
"Edit(src/api/v1/legacy/**)"
]
}
}
`
بعد وضع قواعد الحظر الصريحة، من الأفضل قفلها مرة أخرى على مستوى نظام الملفات لزيادة الأمان. بالنسبة لسكربتات بناء الإنتاج أو ملفات مفاتيح الأمان، يكون من الأنسب سحب صلاحيات الكتابة منها على مستوى نظام التشغيل (OS).
.claude/settings.json في المجلد الرئيسي للمشروع.permissions.deny.chmod 444 .env*.من خلال التحكم في الصلاحيات بهذه الطريقة، يمكنك التخلص من جزء كبير من أخطاء البناء التي تحدث نتيجة تعديل الذكاء الاصطناعي للموديولات المشتركة بشكل غير متوقع.
إذا تم الاحتفاظ بسجلات الجلسة (.jsonl) فقط في البيئة المحلية للمطور، فسيكون من الصعب تحديد السبب لاحقًا عند حدوث آثار جانبية (Side Effects). قم بإعداد بيئة عمل GitHub Actions لضغط تتبع الجلسة والتحقق منه في اللحظة التي يتم فيها تقديم طلب السحب (PR).
`yaml
name: AI Agent Session Audit & Risk Analysis
on:
pull_request:
types: [opened, synchronize]
jobs:
audit-session:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Mindwalk Telemetry Extractor
run: |
docker run --rm -v ${{ github.workspace }}:/workspace \
cosmtrek/mindwalk:v0.1.0 parse --log-dir=./.claude/sessions --out=telemetry.json
- name: Run Deterministic Repo Audit
id: repo_audit
run: |
curl -sSL https://github.com/aletheore/releases/download/v1.0/aletheore -o aletheore
chmod +x aletheore
./aletheore audit --telemetry=telemetry.json --max-allowed-depth=3
- name: Upload Mindwalk 3D Visual Artifact
uses: actions/upload-artifact@v4
with:
name: mindwalk-3d-trace-${{ github.event.pull_request.number }}
path: telemetry.json
`
باستخدام محرك تحليل قائم على Rust أو الدمج مع Tree-sitter للتحقق مما إذا كان الوكيل قد خرج عن النطاق المحدد، يمكنك إفشال عملية بناء CI فورًا عند تعديل موديولات عليا خارج نطاق الصلاحيات المسموح بها.
من المفيد حساب مستوى خطورة التغييرات بناءً على ترابط العقد بدلاً من الاقتصار على عدد أسطر الكود البسيطة.
هنا هو عدد الملفات المعدلة، و هو متوسط الترابط ثلاثي الأبعاد للعقد المعدلة. إذا تجاوزت القيمة الحد المسموح به، يمكنك إرسال رابط الخريطة المرئية ثلاثية الأبعاد عبر إشعار Slack حتى يتمكن المراجع من فهم مستوى الخطورة على الفور.
عندما يحدث الوكيل فوضى في الكود، بدلاً من إلغاء التغييرات (Commit) بالكامل، يجب تتبع الجدول الزمني واسترداد الملفات الملوثة فقط. إذا قمت باستخراج النطاق الزمني المحدد الذي بدأ فيه العطل، استخدم jq لاستخراج الموجه (Prompt) ومسار الاستدلال في تلك اللحظة من سجلات JSONL.
`bash
jq -c 'select(.timestamp >= "2026-07-11T14:20:00Z" and .timestamp <= "2026-07-11T14:25:00Z") |
{timestamp: .timestamp, prompt: .payload.prompt, tool_use: .payload.tool_use, thinking: .payload.thinking}'
./.claude/sessions/session_abc123.jsonl
`
بمجرد التأكد من السبب، تتم عملية الاسترداد مقسمة إلى 3 خطوات تالية:
git checkout <PRE_AI_COMMIT_SHA> -- src/legacy/broken_module.ts)git clean -fd -- src/unwanted_generated_dir/)باستخدام هذه الطريقة، يمكنك تجميع الملفات التالفة فقط بشكل نظيف دون التسبب في كارثة فقدان الكود الذي يعمل بشكل صحيح.
في بيئة Monorepo، عندما يرتفع عدد العقد إلى عشرات الآلاف، قد تتوقف أداة التصور المرئي نفسها عن العمل. وعندما يصبح المتصفح بطيئًا، يقل شغفك بتصحيح الأخطاء. لاستبعاد المجلدات غير الضرورية من عملية التقديم المرئي، يجب ضبط مرشح الاستبعاد في mindwalk.config.json بوضوح.
`json
{
"visualization": {
"excludePatterns": [
"/node_modules/",
"/vendor/",
"/.git/",
"/dist/",
"/coverage/",
"/*.log",
"/*.pb.go"
],
"maxDepth": 5,
"groupingStrategy": "directory-segmented"
}
}
`
أخيرًا، عند تشغيل خط أنابيب التصور المرئي أو أدوات التحليل كحاوية Docker في الخلفية، يجب تقييد حصص الموارد المخصصة حتى لا تتوقف بيئة التطوير المحلية (IDE).
mindwalk.config.json لاستبعاد عقد مجلدات التبعيات (Dependencies) من التقديم المرئي.--cpus="1.5" و --memory="2g" عند تشغيل الحاوية.--nice=19 في نهاية أمر تشغيل عملية الخلفية لتقليل أولوية وحدة المعالجة المركزية (CPU) إلى أدنى مستوى.