Blog

كيف تجعل وكلاء الذكاء الاصطناعي يثبتون عملهم بالصور: وداعًا للهلوسة

Ashley Innocent

Ashley Innocent

19 مارس 2026

كيف تجعل وكلاء الذكاء الاصطناعي يثبتون عملهم بالصور: وداعًا للهلوسة

Apidog للمؤسسات

النشر على الخوادم المحلية

SSO و RBAC

متوافق مع SOC 2

استكشف Apidog للمؤسسات

باختصار

أوقف هلوسات الذكاء الاصطناعي في 4 خطوات: (1) قم بتثبيت Playwright وتهيئة نقاط التوقف (للسطح المكتب، الجهاز اللوحي، الهاتف المحمول)، (2) أنشئ مجموعة اختبار لقطة الشاشة التي تلتقط الصفحة بالكامل، والتصميمات سريعة الاستجابة، والتفاعلات، (3) قم بتشغيل ./qa-playwright-capture.sh لجمع الأدلة، (4) قم بتنشيط وكيل مدقق الواقع (Reality Checker) لمقارنة المطالبات بنتائج grep ولقطات الشاشة. تقوم الوكلاء بإخراج حالة "ناجح" (PASS) أو "يحتاج إلى عمل" (NEEDS WORK) مع مشكلات حظر محددة — لا مزيد من الموافقات الوهمية.

مقدمة

توقف عن قبول "يبدو رائعاً" من وكلاء الذكاء الاصطناعي. قم ببناء سير عمل لضمان الجودة (QA) قائم على الأدلة باستخدام لقطات شاشة Playwright التي تتطلب إثباتاً مرئياً قبل أي موافقة.

تطلب من وكيل ذكاء اصطناعي مراجعة صفحتك المقصودة. فيستجيب:

The design looks premium and polished. The glassmorphism effects are well-implemented. The page is fully responsive. Ready for production!

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

وكلاء الذكاء الاصطناعي يهلوسون. يخبرونك بما تريد سماعه. يتجنبون النزاع. يوافقون على كل شيء.

وكيل مدقق الواقع (Reality Checker) من مجموعة Agency يتبع نهجاً مختلفاً:

Status: NEEDS WORK

Evidence:
- grep for "glassmorphism" returned NO PREMIUM FEATURES FOUND
- responsive-mobile.png shows broken layout at 375px width
- test-results.json shows 3 console errors, 2.1s load time

Blocking issues: 4

لا مشاعر. لا آراء. مجرد أدلة.

في هذا البرنامج التعليمي، ستقوم ببناء سير عمل لضمان الجودة (QA) قائم على الأدلة يكمل مسار اختبار واجهة برمجة التطبيقات (API) الخاص بك. سواء كنت تقوم بالتحقق من تخطيطات الواجهة الأمامية أو التحقق من استجابات API في Apidog، المبدأ هو نفسه: طلب إثبات قبل الموافقة. ستقوم بإعداد Playwright لالتقاط لقطات الشاشة تلقائياً، وإنشاء أوامر إلزامية للتحقق من الواقع، ومقارنة ادعاءات الوكلاء بالتعليمات البرمجية الفعلية، وطلب شهادة "نجاح" (PASS) أو "فشل" (FAIL) قبل الشحن.

لماذا الأدلة مهمة

وكلاء الذكاء الاصطناعي يسعون لإرضاء الآخرين. يريدون المساعدة. يريدون أن تحبهم. لذا يقولون ما يبدو جيداً:

ضمان الجودة القائم على الأدلة يغير هذا. بدلاً من الآراء، تحصل على:

لا مزيد من "ثق بي". فقط دليل.

الخطوة 1: إعداد Playwright

تثبيت Playwright:

npm install -D @playwright/test
npx playwright install chromium

إنشاء qa-playwright.config.ts:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testMatch: '**/qa-screenshots.spec.ts',
  timeout: 30000,
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:8000',
    screenshot: 'on',
    trace: 'on-first-retry',
    headless: true,
  },
  projects: [
    {
      name: 'desktop',
      use: { viewport: { width: 1920, height: 1080 } },
    },
    {
      name: 'tablet',
      use: { viewport: { width: 768, height: 1024 } },
    },
    {
      name: 'mobile',
      use: { viewport: { width: 375, height: 667 } },
    },
  ],
  reporter: [['json', { outputFile: 'public/qa-screenshots/test-results.json' }]],
  outputDir: 'public/qa-screenshots',
});

الخطوة 2: إنشاء مجموعة اختبار لقطة الشاشة

إنشاء qa-screenshots.spec.ts:

import { test, expect } from '@playwright/test';
import * as fs from 'fs';
import * as path from 'path';

// Ensure output directory exists
const outputDir = 'public/qa-screenshots';
if (!fs.existsSync(outputDir)) {
  fs.mkdirSync(outputDir, { recursive: true });
}

test.describe('Reality Check Screenshots', () => {
  test('capture full page at all breakpoints', async ({ page, browserName }) => {
    const errors: string[] = [];
    const consoleLogs: string[] = [];

    // Capture console errors
    page.on('console', msg => {
      if (msg.type() === 'error') {
        consoleLogs.push(`[ERROR] ${msg.text()}`);
      }
    });

    // Capture network failures
    page.on('requestfailed', request => {
      errors.push(`[NETWORK] ${request.url()} failed`);
    });

    // Navigate to page
    await page.goto('/');
    await page.waitForLoadState('networkidle');

    // Capture performance metrics
    const metrics = await page.metrics();
    const performance = {
      jsHeapSize: metrics.JSHeapUsedSize,
      loadTime: await page.evaluate(() => performance.timing.loadEventEnd - performance.timing.navigationStart),
      domContentLoaded: await page.evaluate(() => performance.timing.domContentLoadedEventEnd - performance.timing.navigationStart),
    };

    // Save screenshot
    const projectName = browserName || 'chromium';
    await page.screenshot({
      path: path.join(outputDir, `full-page-${projectName}.png`),
      fullPage: true,
    });

    // Save metrics
    fs.writeFileSync(
      path.join(outputDir, 'performance-metrics.json'),
      JSON.stringify({ performance, consoleErrors: consoleLogs, networkErrors: errors }, null, 2)
    );
  });

  test('capture responsive layouts', async ({ page }) => {
    const breakpoints = [
      { name: 'desktop', width: 1920, height: 1080 },
      { name: 'tablet', width: 768, height: 1024 },
      { name: 'mobile', width: 375, height: 667 },
    ];

    for (const breakpoint of breakpoints) {
      await page.setViewportSize({ width: breakpoint.width, height: breakpoint.height });
      await page.goto('/');
      await page.waitForLoadState('networkidle');
      await page.screenshot({
        path: path.join(outputDir, `responsive-${breakpoint.name}.png`),
        fullPage: true,
      });
    }
  });

  test('capture navigation interactions', async ({ page }) => {
    await page.goto('/');

    // Find and click navigation items
    const navItems = await page.$$('nav a, header a, .nav a');
    for (let i = 0; i < Math.min(navItems.length, 5); i++) {
      await page.screenshot({ path: path.join(outputDir, `nav-${i}-before.png`) });
      await navItems[i].click();
      await page.waitForLoadState('networkidle');
      await page.screenshot({ path: path.join(outputDir, `nav-${i}-after.png`) });
      await page.goBack();
      await page.waitForLoadState('networkidle');
    }
  });

  test('capture form interactions', async ({ page }) => {
    await page.goto('/');

    // Find forms
    const forms = await page.$$('form');
    for (let i = 0; i < forms.length; i++) {
      const form = forms[i];
      await form.screenshot({ path: path.join(outputDir, `form-${i}-initial.png`) });

      // Fill inputs
      const inputs = await form.$$('input[type="text"], input[type="email"], input[type="password"]');
      for (const input of inputs) {
        await input.fill('test@example.com');
      }

      await form.screenshot({ path: path.join(outputDir, `form-${i}-filled.png`) });
    }
  });

  test('capture accordion/dropdown interactions', async ({ page }) => {
    await page.goto('/');

    // Find accordions
    const accordions = await page.$$('[data-accordion], details, .accordion');
    for (let i = 0; i < accordions.length; i++) {
      await accordions[i].screenshot({ path: path.join(outputDir, `accordion-${i}-closed.png`) });
      await accordions[i].click();
      await page.waitForTimeout(300);
      await accordions[i].screenshot({ path: path.join(outputDir, `accordion-${i}-open.png`) });
    }
  });
});

الخطوة 3: إنشاء سكربت التحقق من الواقع

إنشاء qa-playwright-capture.sh:

#!/usr/bin/env bash
#
# qa-playwright-capture.sh — تشغيل لقطات شاشة Playwright للتحقق من الواقع
#
# الاستخدام: ./qa-playwright-capture.sh [BASE_URL] [OUTPUT_DIR]
#

set -euo pipefail

BASE_URL="${1:-http://localhost:8000}"
OUTPUT_DIR="${2:-public/qa-screenshots}"

echo "بدء التقاط لقطات شاشة للتحقق من الواقع..."
echo "  عنوان URL الأساسي: $BASE_URL"
echo "  المخرج: $OUTPUT_DIR"

# التأكد من وجود دليل الإخراج
mkdir -p "$OUTPUT_DIR"

# تشغيل اختبارات Playwright
export BASE_URL
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

# إنشاء ملخص
echo ""
echo "إنشاء ملخص..."

# عد لقطات الشاشة
SCREENSHOT_COUNT=$(find "$OUTPUT_DIR" -name "*.png" | wc -l)
echo "  لقطات الشاشة الملتقطة: $SCREENSHOT_COUNT"

# التحقق من أخطاء وحدة التحكم
if [ -f "$OUTPUT_DIR/performance-metrics.json" ]; then
  ERROR_COUNT=$(cat "$OUTPUT_DIR/performance-metrics.json" | grep -c '"\[ERROR\]"' || echo "0")
  echo "  أخطاء وحدة التحكم: $ERROR_COUNT"
fi

# التحقق من وقت التحميل
if [ -f "$OUTPUT_DIR/performance-metrics.json" ]; then
  LOAD_TIME=$(cat "$OUTPUT_DIR/performance-metrics.json" | grep -o '"loadTime": [0-9.]*' | head -1 | awk '{print $2}')
  echo "  وقت التحميل: ${LOAD_TIME:-N/A}ms"
fi

echo ""
echo "التحقق من الواقع اكتمل. راجع لقطات الشاشة في: $OUTPUT_DIR"
echo ""
echo "الخطوة التالية: تشغيل وكيل مدقق الواقع للتحقق من الأدلة"

جعله قابلاً للتنفيذ:

chmod +x qa-playwright-capture.sh

الخطوة 4: تشغيل أوامر التحقق من الواقع

قبل أن يتمكن أي وكيل ذكاء اصطناعي من الموافقة على العمل، قم بتشغيل هذه الأوامر:

# 1. التحقق مما تم بناؤه فعلياً
ls -la resources/views/ || ls -la *.html
ls -la src/components/ || ls -la components/

# 2. مقارنة الميزات المطالب بها
grep -r "glassmorphism\|backdrop-filter\|blur" . --include="*.css" --include="*.html" || echo "NO GLASSMORPHISM FOUND"
grep -r "responsive\|media-query\|@media" . --include="*.css" || echo "NO RESPONSIVE CSS FOUND"
grep -r "jwt\|authentication\|auth" . --include="*.ts" --include="*.js" || echo "NO AUTH FOUND"

# 3. تشغيل التقاط لقطات الشاشة
./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots

# 4. مراجعة الأدلة
ls -la public/qa-screenshots/
# الملفات المتوقعة:
# - responsive-desktop.png
# - responsive-tablet.png
# - responsive-mobile.png
# - nav-*-before.png, nav-*-after.png
# - form-*-initial.png, form-*-filled.png

# 5. التحقق من المقاييس
cat public/qa-screenshots/test-results.json
cat public/qa-screenshots/performance-metrics.json

الخطوة 5: تنشيط وكيل مدقق الواقع

افتح جلسة Claude Code:

Activate Reality Checker mode.

Run your mandatory reality check process:

1. Verify files exist: ls -la src/components/
2. Cross-reference claimed features: grep for "premium", "glassmorphism"
3. Review screenshot evidence: public/qa-screenshots/
4. Check test-results.json for metrics

Project URL: http://localhost:8000

Output: PASS or NEEDS WORK with specific blocking issues.

الإخراج المتوقع:

## نتائج التحقق من الواقع

### التحقق من الملفات: ناجح (PASS)
- ملفات المكونات موجودة: تم العثور على 12 ملفاً
- الهيكل المتوقع يتطابق

### التحقق من الميزات: يحتاج إلى عمل (NEEDS WORK)
- المدعى به: "تصميم زجاجي فاخر"
- نتيجة grep: لم يتم العثور على زجاج (NO GLASSMORPHISM FOUND)
- الحالة: المطالبة غير مدعومة

### دليل لقطة الشاشة: يحتاج إلى عمل (NEEDS WORK)
- سطح المكتب (1920x1080): التخطيط صحيح
- الجهاز اللوحي (768x1024): تم اكتشاف تداخل في التنقل
- الهاتف المحمول (375x667): شبكة المنتج معطلة (عمودين بدلاً من عمود واحد)

### مقاييس الأداء: يحتاج إلى عمل (NEEDS WORK)
- وقت التحميل: 2.3 ثانية (الهدف: <1 ثانية)
- أخطاء وحدة التحكم: 3 (الهدف: 0)
- فشل الشبكة: 1 (الهدف: 0)

## الحالة النهائية: يحتاج إلى عمل (NEEDS WORK)

### مشكلات الحظر:
1. تم الادعاء بوجود الزجاج ولكن لم يتم تنفيذه
2. تخطيط الهاتف المحمول معطل عند 375 بكسل
3. وقت التحميل يتجاوز الهدف البالغ 1 ثانية
4. 3 أخطاء في وحدة التحكم يجب إصلاحها

### غير حاجبة:
- تداخل التنقل على الجهاز اللوحي
- إضافة حالات التحميل

لا توافق حتى يتم حل مشكلات الحظر.

الخطوة 6: مقارنة المطالبات بالأدلة

إنشاء قائمة تحقق بالمطالبات:

## قائمة تحقق المطالبات مقابل الأدلة

| المطالبة | أمر الدليل | النتيجة |
|-------|------------------|--------|
| "زجاجي فاخر" | grep "backdrop-filter" | لم يتم العثور عليه (NOT FOUND) |
| "سريع الاستجابة بالكامل" | responsive-mobile.png | فشل (شبكة معطلة) |
| "لا توجد أخطاء في وحدة التحكم" | test-results.json | تم العثور على 3 أخطاء |
| "وقت تحميل سريع" | performance-metrics.json | 2.3 ثانية (الهدف: <1 ثانية) |
| "مصادقة JWT" | grep "jsonwebtoken" | تم العثور عليه (FOUND) |
| "تحديد المعدل" | grep "rateLimit" | لم يتم العثور عليه (NOT FOUND) |

قم بتحديث قائمة التحقق هذه لكل مشروع. اطلب دليلاً لكل مطالبة.

سير عمل التحقق من الواقع الكامل

┌─────────────────────────────────────────────────────────────────┐
│  1. المطور/الذكاء الاصطناعي يكمل العمل                         │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  2. تشغيل أوامر التحقق من الواقع                               │
│     - ls للتحقق من الملفات                                     │
│     - grep للتحقق من الميزات                                   │
│     - Playwright لالتقاط لقطات الشاشة                          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  3. تنشيط وكيل مدقق الواقع                                      │
│     - مراجعة التحقق من الملفات                                 │
│     - مقارنة المطالبات                                         │
│     - تحليل لقطات الشاشة                                        │
│     - التحقق من المقاييس                                        │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  4. الإخراج: ناجح (PASS) أو يحتاج إلى عمل (NEEDS WORK)         │
│     - ناجح: شحن بثقة                                           │
│     - يحتاج إلى عمل: إصلاح مشكلات الحظر، إعادة التشغيل          │
└─────────────────────────────────────────────────────────────────┘

التكامل مع CI/CD

أضف فحوصات الواقع إلى مسار CI الخاص بك:

# .github/workflows/qa-reality-check.yml
name: Reality Check

on: [pull_request]

jobs:
  reality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright
        run: npx playwright install chromium

      - name: Start server
        run: npm start &
        env:
          PORT: 8000

      - name: Wait for server
        run: sleep 5

      - name: Run reality check screenshots
        run: ./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots

      - name: Upload screenshots
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: reality-check-screenshots
          path: public/qa-screenshots/

      - name: Check for console errors
        run: |
          ERRORS=$(cat public/qa-screenshots/performance-metrics.json | grep -c '"\[ERROR\]"' || echo "0")
          if [ "$ERRORS" -gt "0" ]; then
            echo "Console errors found: $ERRORS"
            exit 1
          fi

      - name: Check load time
        run: |
          LOAD_TIME=$(cat public/qa-screenshots/performance-metrics.json | grep -o '"loadTime": [0-9.]*' | head -1 | awk '{print $2}')
          if (( $(echo "$LOAD_TIME > 1000" | bc -l) )); then
            echo "Load time too slow: ${LOAD_TIME}ms (target: <1000ms)"
            exit 1
          fi

ما قمت ببنائه

المكون الغرض
تكوين Playwright التقاط لقطات شاشة تلقائي عند 3 نقاط توقف
مجموعة الاختبار صفحة كاملة، متجاوبة، تفاعلات
سكربت التحقق من الواقع جمع الأدلة بأمر واحد
قائمة التحقق من المطالبات مقارنة مطالبات الذكاء الاصطناعي بنتائج grep
تكامل CI/CD تحقق تلقائي من الواقع عند طلبات السحب (PR)

الخطوات التالية

توسيع سير العمل:

بناء قاعدة بيانات للمطالبات:

شارك مع فريقك:

استكشاف المشكلات الشائعة وإصلاحها

مهلة اختبارات Playwright:

لقطات الشاشة لا تلتقط:

أخطاء وحدة التحكم لا يتم التقاطها:

لقطات شاشة الهاتف المحمول تظهر تخطيط سطح المكتب:

فشل مسار CI/CD على Ubuntu:

أنماط متقدمة للتحقق من الواقع

النمط 1: اختبار الانحدار البصري

قارن لقطات الشاشة مقابل الأساسات لاكتشاف التغييرات غير المقصودة:

import { expect } from '@playwright/test';

test('visual regression check', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveScreenshot('homepage-base.png', {
    maxDiffPixels: 100, // السماح بفروق طفيفة
    fullPage: true,
  });
});

النمط 2: تدقيق إمكانية الوصول

تكامل axe-core لأدلة إمكانية الوصول:

import AxeBuilder from '@axe-core/playwright';

test('accessibility audit', async ({ page }) => {
  await page.goto('/');
  const accessibilityScanResults = await new AxeBuilder({ page }).analyze();

  // حفظ النتائج
  const fs = require('fs');
  fs.writeFileSync(
    'public/qa-screenshots/accessibility-results.json',
    JSON.stringify(accessibilityScanResults, null, 2)
  );

  // الفشل إذا كانت هناك انتهاكات خطيرة
  const criticalViolations = accessibilityScanResults.violations.filter(
    v => v.impact === 'critical' || v.impact === 'serious'
  );
  expect(criticalViolations).toHaveLength(0);
});

النمط 3: تطبيق ميزانية الأداء

فشل البناء الذي يتجاوز عتبات الأداء:

test('performance budget', async ({ page }) => {
  await page.goto('/');

  const metrics = await page.metrics();
  const loadTime = await page.evaluate(() =>
    performance.timing.loadEventEnd - performance.timing.navigationStart
  );

  // عتبات الميزانية
  expect(loadTime).toBeLessThan(2000); // 2 ثانية كحد أقصى
  expect(metrics.JSHeapUsedSize).toBeLessThan(5 * 1024 * 1024); // 5 ميغابايت كحد أقصى
});

لم يعد بإمكان وكلاء الذكاء الاصطناعي الإفلات بقول "يبدو رائعاً". يجب عليهم إثبات عملهم بلقطات الشاشة والمقاييس ونتائج grep.

لا مزيد من الهلوسات. لا مزيد من الموافقات الوهمية. مجرد دليل.

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

دورك الآن: أضف فحوصات الواقع إلى سير عملك. اشحن بثقة.

زر

الأسئلة الشائعة

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

كيف أقوم بإعداد Playwright لاختبار لقطات الشاشة؟ قم بالتثبيت باستخدام npm install -D @playwright/test، ثم قم بتشغيل npx playwright install chromium، وأنشئ ملف تكوين بنقاط توقف لإطار العرض، واكتب مجموعات اختبار تلتقط لقطات الشاشة عند كل نقطة توقف.

ما هي أوامر التحقق من الواقع التي يجب تشغيلها قبل الموافقة؟ قم بتشغيل ls للتحقق من وجود الملفات، و grep للتحقق من وجود الميزات المطالب بها في التعليمات البرمجية، واختبارات Playwright لقطات الشاشة، وتحقق من test-results.json لأخطاء وحدة التحكم ومقاييس الأداء.

ما هو وكيل مدقق الواقع (Reality Checker)؟ مدقق الواقع هو وكيل ذكاء اصطناعي متخصص من وكالة يتحقق من العمل باستخدام الأدلة. يقوم بتشغيل أوامر التحقق، ويراجع لقطات الشاشة، ويقارن المطالبات، ويخرج حالة "ناجح" (PASS) أو "يحتاج إلى عمل" (NEEDS WORK) مع مشكلات حظر محددة.

كيف أدمج فحوصات الواقع في CI/CD؟ أضف سير عمل GitHub Actions الذي يقوم بتثبيت Playwright، ويشغل خادمك، ويلتقط لقطات الشاشة، ويحمل Artifacts، ويفشل البناء إذا تجاوزت أخطاء وحدة التحكم 0 أو تجاوز وقت التحميل العتبة المحددة.

ماذا لو أظهرت لقطات الشاشة مشكلات ولكن الوكيل يقول "ناجح" (PASS)؟ الوكيل غير مهيأ بشكل صحيح. يجب على مدقق الواقع مراجعة الأدلة قبل إخراج الحالة. قم بإعادة تدريبه ليطلب: (1) نتائج grep التي تثبت الميزات، (2) مراجعة لقطة الشاشة، (3) المقاييس ضمن العتبات.

كيف أقنع فريقي بتبني ضمان الجودة القائم على الأدلة؟ وثّق عملية التحقق من الواقع، وأضف بوابات CI/CD التي تتطلب اجتياز الاختبارات، واجعل مراجعة لقطة الشاشة إلزامية للموافقة على طلبات السحب (PR)، وتتبع أي الوكلاء يقدمون أدق التقييمات.

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات

التسجيل مجانًاتحميل