بناء وكلاء ذكاء اصطناعي جاهزين للإنتاج باستخدام Claude Agent SDK و TypeScript

mkdir claude-agent-project && cd claude-agent-project
npm init -y
npm install @anthropic-ai/claude-agent-sdk
npm install -D typescript @types/node tsx

npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNext --outDir dist

{
  "type": "module",
  "scripts": {
    "start": "tsx src/index.ts",
    "build": "tsc"
  }
}

mkdir src

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function main() {
  console.log("جاري تشغيل الوكيل...\n");
 
  for await (const message of query({
    prompt: "ما هي الملفات الموجودة في هذا المجلد؟ أعطني ملخصاً لهيكل المشروع.",
    options: {
      allowedTools: ["Bash", "Glob", "Read"],
      maxTurns: 10,
    },
  })) {
    // معالجة أنواع الرسائل المختلفة
    if ("result" in message) {
      console.log("\n--- نتيجة الوكيل ---");
      console.log(message.result);
    }
  }
}
 
main().catch(console.error);

npx tsx src/index.ts

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function main() {
  for await (const message of query({
    prompt: "ابحث عن جميع ملفات TypeScript واحسب إجمالي عدد سطور الكود.",
    options: {
      allowedTools: ["Bash", "Glob", "Read"],
      maxTurns: 15,
    },
  })) {
    switch (message.type) {
      case "assistant":
        // نص استجابة أو تفكير Claude
        const textBlocks = message.message.content
          .filter((block: { type: string }) => block.type === "text")
          .map((block: { type: string; text: string }) => block.text);
        if (textBlocks.length > 0) {
          console.log("[Claude]", textBlocks.join(""));
        }
        break;
 
      case "tool_use":
        // Claude يستدعي أداة
        console.log(`[استدعاء أداة] ${message.name}(${JSON.stringify(message.input).slice(0, 100)}...)`);
        break;
 
      case "tool_result":
        // نتيجة تنفيذ الأداة
        console.log(`[نتيجة الأداة] ${message.content?.slice(0, 200)}...`);
        break;
 
      case "result":
        if (message.subtype === "success") {
          console.log("\n✓ أكمل الوكيل بنجاح");
          console.log(message.result);
        } else {
          console.error("\n✗ فشل الوكيل:", message.error);
        }
        break;
    }
  }
}
 
main().catch(console.error);

import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function refactorAgent(targetFile: string, instruction: string) {
  for await (const message of query({
    prompt: `أعد هيكلة الملف ${targetFile}: ${instruction}`,
    options: {
      allowedTools: ["Read", "Edit", "Glob", "Grep"],
      permissionMode: "acceptEdits", // الموافقة التلقائية على تغييرات الملفات
      maxTurns: 20,
    },
  })) {
    if ("result" in message) {
      return message.result;
    }
  }
}
 
// الاستخدام
const result = await refactorAgent(
  "src/utils.ts",
  "استخرج جميع الدوال المساعدة إلى وحدات منفصلة حسب مجالها"
);
console.log(result);

import { query } from "@anthropic-ai/claude-agent-sdk";
import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk/mcp";
 
// تعريف أدوات مخصصة
const analyticsServer = createSdkMcpServer({
  name: "analytics",
  version: "1.0.0",
  tools: [
    tool(
      "get_page_views",
      "الحصول على تحليلات مشاهدات الصفحات لمسار URL ونطاق زمني محدد",
      {
        type: "object",
        properties: {
          path: { type: "string", description: "مسار URL (مثل /blog/my-post)" },
          startDate: { type: "string", description: "تاريخ البداية (YYYY-MM-DD)" },
          endDate: { type: "string", description: "تاريخ النهاية (YYYY-MM-DD)" },
        },
        required: ["path", "startDate", "endDate"],
      },
      async ({ path, startDate, endDate }) => {
        // استدعاء API التحليلات الفعلي هنا
        const response = await fetch(
          `https://api.analytics.example.com/views?path=${path}&start=${startDate}&end=${endDate}`
        );
        const data = await response.json();
        return JSON.stringify(data);
      }
    ),
    tool(
      "get_top_pages",
      "الحصول على أكثر N صفحة زيارة",
      {
        type: "object",
        properties: {
          limit: { type: "number", description: "عدد الصفحات المطلوبة" },
          period: { type: "string", enum: ["day", "week", "month"], description: "الفترة الزمنية" },
        },
        required: ["limit", "period"],
      },
      async ({ limit, period }) => {
        const response = await fetch(
          `https://api.analytics.example.com/top?limit=${limit}&period=${period}`
        );
        const data = await response.json();
        return JSON.stringify(data);
      }
    ),
  ],
});
 
// الاستخدام مع إدخال التدفق (مطلوب لخوادم MCP)
async function* generateMessages() {
  yield {
    type: "user" as const,
    message: {
      role: "user" as const,
      content: "ما هي أكثر 10 صفحات زيارة هذا الشهر؟ ثم حلل اتجاه الصفحة الأولى خلال آخر 30 يوماً.",
    },
  };
}
 
for await (const message of query({
  prompt: generateMessages(),
  options: {
    mcpServers: {
      analytics: analyticsServer,
    },
    allowedTools: [
      "mcp__analytics__get_page_views",
      "mcp__analytics__get_top_pages",
    ],
    maxTurns: 10,
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "اسرد المشاكل المفتوحة المصنفة كـ 'bug' ولخّص الأكثر أهمية.",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
        },
      },
    },
    allowedTools: ["mcp__github__*"], // حرف بدل: السماح بجميع أدوات GitHub
    maxTurns: 15,
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

options: {
  mcpServers: {
    "remote-api": {
      type: "sse",
      url: "https://mcp.example.com/sse",
      headers: {
        Authorization: `Bearer ${process.env.API_TOKEN}`,
      },
    },
  },
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
const CODE_REVIEW_PROMPT = `أنت مراجع كود خبير متخصص في TypeScript و React.
 
عملية المراجعة:
1. اقرأ الملفات المعدّلة
2. تحقق من الأخطاء ومشاكل الأمان والأداء
3. تحقق من صحة واكتمال أنواع TypeScript
4. تأكد من أفضل ممارسات React (قواعد hooks، خصائص key، استخدام memo)
5. قدّم مراجعة منظمة بمستويات خطورة
 
تنسيق المخرجات:
- 🔴 حرج: يجب إصلاحه قبل الدمج
- 🟡 تحذير: يجب إصلاحه لكنه غير مانع
- 🟢 اقتراح: تحسينات مستحسنة
 
كن محدداً. أشر إلى أرقام الأسطر. اقترح إصلاحات مع كود.`;
 
async function reviewCode(diffOrPath: string) {
  for await (const message of query({
    prompt: `راجع هذا الكود:\n\n${diffOrPath}`,
    options: {
      systemPrompt: CODE_REVIEW_PROMPT,
      allowedTools: ["Read", "Glob", "Grep"],
      maxTurns: 25,
    },
  })) {
    if ("result" in message) {
      return message.result;
    }
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "حلل تغطية الاختبارات في هذا المشروع، ثم اكتب اختبارات لأي دوال غير مغطاة في src/utils/.",
  options: {
    allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "Task"],
    agents: {
      "test-analyzer": {
        description: "يحلل تغطية الاختبارات ويحدد مسارات الكود غير المختبرة",
        tools: ["Bash", "Read", "Glob", "Grep"],
        prompt: "أنت محلل تغطية اختبارات. شغّل أدوات التغطية، وحلل التقارير، وحدد الدوال غير المختبرة.",
        model: "haiku", // استخدم نموذجاً أسرع للتحليل
      },
      "test-writer": {
        description: "يكتب اختبارات وحدة شاملة لدوال TypeScript",
        tools: ["Read", "Write", "Edit", "Glob"],
        prompt: "أنت مهندس اختبارات. اكتب اختبارات وحدة شاملة باستخدام Vitest مع محاكاة صحيحة وتغطية الحالات الطرفية.",
        model: "sonnet",
      },
    },
    maxTurns: 30,
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "حوّل جميع ملفات JavaScript إلى TypeScript مع أنواع صحيحة.",
  options: {
    allowedTools: ["Read", "Write", "Edit", "Glob", "Grep", "Bash"],
 
    // حدود الدورات
    maxTurns: 50,           // أقصى عدد من استدعاءات الأدوات قبل التوقف
 
    // ضوابط التكلفة
    maxBudgetUsd: 2.0,      // توقف إذا تجاوزت التكلفة $2.00
 
    // اختيار النموذج
    model: "claude-sonnet-4-5-20250929",  // استخدم نموذجاً محدداً
 
    // قيود الأدوات
    disallowedTools: ["WebSearch", "WebFetch"],  // حظر أدوات محددة
 
    // مجلد العمل
    cwd: "/path/to/project",
 
    // متغيرات البيئة المتاحة لأداة Bash
    env: {
      NODE_ENV: "development",
      DATABASE_URL: process.env.DATABASE_URL!,
    },
 
    // وضع الصلاحيات
    permissionMode: "acceptEdits",
  },
})) {
  // معالجة الرسائل
}

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "نظّف وحسّن قاعدة الكود.",
  options: {
    allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
    canUseTool: async (toolName, input) => {
      // حظر أوامر bash التدميرية
      if (toolName === "Bash") {
        const command = (input as { command: string }).command;
        const dangerous = ["rm -rf", "DROP TABLE", "git push --force"];
        if (dangerous.some((d) => command.includes(d))) {
          return { allowed: false, reason: "الأوامر التدميرية غير مسموح بها" };
        }
      }
 
      // حظر الكتابة على الملفات الحساسة
      if (toolName === "Write" || toolName === "Edit") {
        const filePath = (input as { file_path: string }).file_path;
        const protected_paths = [".env", "package-lock.json", "prisma/schema.prisma"];
        if (protected_paths.some((p) => filePath.includes(p))) {
          return { allowed: false, reason: `لا يمكن تعديل ملف محمي: ${filePath}` };
        }
      }
 
      return { allowed: true };
    },
  },
})) {
  if ("result" in message) {
    console.log(message.result);
  }
}

// src/review-bot.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
 
interface ReviewResult {
  summary: string;
  issues: Array<{
    severity: "critical" | "warning" | "suggestion";
    file: string;
    line?: number;
    message: string;
    suggestion?: string;
  }>;
  score: number;
}
 
const REVIEW_SYSTEM_PROMPT = `أنت خبير في مراجعة الكود. حلل تغييرات git وقدّم ملاحظات منظمة.
 
القواعد:
- ركز على الأخطاء والثغرات الأمنية ومشاكل الأداء
- تحقق من أمان أنواع TypeScript
- تحقق من شمولية معالجة الأخطاء
- ابحث عن حالات السباق المحتملة في الكود غير المتزامن
- اقترح تحسينات فقط عندما تقدم قيمة واضحة
 
أنهِ مراجعتك دائماً بكتلة JSON بهذا التنسيق بالضبط:
\`\`\`json
{
  "summary": "ملخص في فقرة واحدة",
  "issues": [
    {
      "severity": "critical|warning|suggestion",
      "file": "path/to/file.ts",
      "line": 42,
      "message": "وصف المشكلة",
      "suggestion": "كيفية الإصلاح"
    }
  ],
  "score": 85
}
\`\`\`
 
النتيجة: 0-100 حيث 100 كود مثالي.`;
 
async function reviewPullRequest(baseBranch: string = "main"): Promise<ReviewResult | null> {
  let result: string | null = null;
 
  for await (const message of query({
    prompt: `راجع تغييرات git الحالية مقابل فرع ${baseBranch}.
اقرأ الملفات المعدّلة للسياق الكامل، ثم قدّم مراجعة كود منظمة.`,
    options: {
      systemPrompt: REVIEW_SYSTEM_PROMPT,
      allowedTools: ["Bash", "Read", "Glob", "Grep"],
      maxTurns: 30,
      maxBudgetUsd: 1.0,
      permissionMode: "acceptEdits",
    },
  })) {
    if ("result" in message && message.subtype === "success") {
      result = message.result;
    }
  }
 
  if (!result) return null;
 
  // استخراج JSON من النتيجة
  const jsonMatch = result.match(/```json\n([\s\S]*?)\n```/);
  if (jsonMatch) {
    return JSON.parse(jsonMatch[1]) as ReviewResult;
  }
 
  return null;
}
 
// تشغيل المراجعة
async function main() {
  console.log("جاري بدء مراجعة الكود...\n");
 
  const review = await reviewPullRequest();
 
  if (review) {
    console.log(`\nنتيجة المراجعة: ${review.score}/100`);
    console.log(`الملخص: ${review.summary}\n`);
 
    for (const issue of review.issues) {
      const icon =
        issue.severity === "critical" ? "🔴" :
        issue.severity === "warning" ? "🟡" : "🟢";
      console.log(`${icon} [${issue.file}${issue.line ? `:${issue.line}` : ""}] ${issue.message}`);
      if (issue.suggestion) {
        console.log(`   الإصلاح: ${issue.suggestion}`);
      }
    }
  }
}
 
main().catch(console.error);

npx tsx src/review-bot.ts

import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";
 
async function interactiveSession() {
  await using session = unstable_v2_createSession({
    model: "claude-sonnet-4-5-20250929",
  });
 
  // الدور الأول
  await session.send("مرحباً! في أي مشروع TypeScript أنا؟");
  for await (const msg of session.stream()) {
    if (msg.type === "assistant") {
      const text = msg.message.content
        .filter((block: { type: string }) => block.type === "text")
        .map((block: { type: string; text: string }) => block.text)
        .join("");
      console.log(text);
    }
  }
 
  // الدور الثاني — الجلسة تتذكر السياق
  await session.send("الآن اسرد الاعتمادات الرئيسية من package.json");
  for await (const msg of session.stream()) {
    if (msg.type === "assistant") {
      const text = msg.message.content
        .filter((block: { type: string }) => block.type === "text")
        .map((block: { type: string; text: string }) => block.text)
        .join("");
      console.log(text);
    }
  }
}
 
interactiveSession().catch(console.error);

// src/test-agent.ts
import { query } from "@anthropic-ai/claude-agent-sdk";
 
async function testAgent() {
  const tests = [
    {
      name: "سرد الملفات الأساسي",
      prompt: "اسرد الملفات في المجلد الحالي",
      tools: ["Glob"],
      expectResult: true,
    },
    {
      name: "تحليل الكود",
      prompt: "اقرأ package.json وأخبرني باسم المشروع",
      tools: ["Read"],
      expectResult: true,
    },
  ];
 
  for (const test of tests) {
    console.log(`\nاختبار: ${test.name}`);
    let gotResult = false;
 
    for await (const message of query({
      prompt: test.prompt,
      options: {
        allowedTools: test.tools,
        maxTurns: 5,
      },
    })) {
      if ("result" in message) {
        gotResult = true;
        console.log(`  ✓ النتيجة: ${message.result.slice(0, 100)}...`);
      }
    }
 
    if (gotResult === test.expectResult) {
      console.log(`  ✓ نجح`);
    } else {
      console.log(`  ✗ فشل`);
    }
  }
}
 
testAgent().catch(console.error);

npm install -g @anthropic-ai/claude-code
claude --version  # التحقق من التثبيت

// تأكد من أن الأدوات التي تحتاجها في القائمة المسموحة
options: {
  allowedTools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"],
  permissionMode: "acceptEdits",
}

options: {
  maxTurns: 20,        // توقف بعد 20 استدعاء أداة
  maxBudgetUsd: 0.50,  // توقف إذا تجاوزت التكلفة $0.50
}

# اختبر خادم MCP مباشرة
npx -y @modelcontextprotocol/server-github