بناء وكيل مراجعة كود طويل الأمد مع Claude Fable 5 وTypeScript

npx tsx review-agent.ts ./my-project

mkdir fable5-reviewer && cd fable5-reviewer
npm init -y
npm install @anthropic-ai/sdk dotenv
npm install -D typescript tsx @types/node

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  }
}

// stream-test.ts
import Anthropic from '@anthropic-ai/sdk';
import 'dotenv/config';
 
const client = new Anthropic();
 
async function main(): Promise<void> {
  const stream = client.messages.stream({
    model: 'claude-fable-5',
    max_tokens: 512,
    messages: [
      {
        role: 'user',
        content: 'اذكر 5 أشياء يجب فحصها في مراجعة أمان TypeScript. كن مختصراً.',
      },
    ],
  });
 
  for await (const chunk of stream) {
    if (
      chunk.type === 'content_block_delta' &&
      chunk.delta.type === 'text_delta'
    ) {
      process.stdout.write(chunk.delta.text);
    }
  }
 
  const final = await stream.finalMessage();
  console.log(
    `\n\nالرموز: ${final.usage.input_tokens} إدخال / ${final.usage.output_tokens} إخراج`
  );
}
 
main();

npx tsx stream-test.ts

// tools.ts
import { readFileSync, readdirSync, statSync } from 'fs';
import { join, extname } from 'path';
import type Anthropic from '@anthropic-ai/sdk';
 
const ALLOWED_EXTENSIONS = new Set([
  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
  '.json', '.md', '.yaml', '.yml', '.toml', '.env.example',
]);
 
export const toolDefinitions: Anthropic.Tool[] = [
  {
    name: 'list_directory',
    description: 'استعرض الملفات والمجلدات في مسار معين.',
    input_schema: {
      type: 'object' as const,
      properties: {
        path: { type: 'string', description: 'مسار المجلد' },
        recursive: { type: 'boolean', description: 'الاستعراض التكراري' },
      },
      required: ['path'],
    },
  },
  {
    name: 'read_file',
    description: 'اقرأ محتوى نصي لملف مصدر.',
    input_schema: {
      type: 'object' as const,
      properties: {
        path: { type: 'string', description: 'مسار الملف' },
      },
      required: ['path'],
    },
  },
  {
    name: 'search_pattern',
    description: 'ابحث عن نمط regex في جميع ملفات المصدر داخل مجلد. يُرجع الأسطر المتطابقة مع مسار الملف ورقم السطر.',
    input_schema: {
      type: 'object' as const,
      properties: {
        pattern: { type: 'string', description: 'نمط regex للبحث' },
        directory: { type: 'string', description: 'المجلد الجذر للبحث' },
        maxResults: {
          type: 'number',
          description: 'الحد الأقصى للنتائج (الافتراضي 50)',
        },
      },
      required: ['pattern', 'directory'],
    },
  },
];
 
function walkDir(dir: string, recursive: boolean): string[] {
  const results: string[] = [];
  for (const name of readdirSync(dir)) {
    if (name.startsWith('.') || name === 'node_modules' || name === 'dist') continue;
    const full = join(dir, name);
    const stat = statSync(full);
    if (stat.isDirectory()) {
      results.push(`${full}/`);
      if (recursive) results.push(...walkDir(full, true));
    } else {
      results.push(full);
    }
  }
  return results;
}
 
function grepFiles(pattern: string, dir: string, maxResults: number): string[] {
  const regex = new RegExp(pattern, 'gi');
  const matches: string[] = [];
  const files = walkDir(dir, true).filter(
    (f) => !f.endsWith('/') && ALLOWED_EXTENSIONS.has(extname(f))
  );
  for (const file of files) {
    if (matches.length >= maxResults) break;
    try {
      const lines = readFileSync(file, 'utf-8').split('\n');
      for (let i = 0; i < lines.length; i++) {
        if (regex.test(lines[i])) {
          matches.push(`${file}:${i + 1}: ${lines[i].trim()}`);
          if (matches.length >= maxResults) break;
        }
      }
    } catch {
      // تجاهل الملفات غير القابلة للقراءة
    }
  }
  return matches;
}
 
export function executeTool(
  name: string,
  input: Record<string, unknown>
): string {
  try {
    if (name === 'list_directory') {
      const path = input.path as string;
      const recursive = (input.recursive as boolean) ?? false;
      const entries = walkDir(path, recursive);
      return entries.slice(0, 300).join('\n') || '(مجلد فارغ)';
    }
 
    if (name === 'read_file') {
      const path = input.path as string;
      if (!ALLOWED_EXTENSIONS.has(extname(path))) {
        return `تم التجاهل: الامتداد ${extname(path)} غير مسموح به.`;
      }
      const content = readFileSync(path, 'utf-8');
      return content.length > 50_000
        ? content.slice(0, 50_000) + '\n\n[تم اقتطاع الملف — أكثر من 50000 حرف]'
        : content;
    }
 
    if (name === 'search_pattern') {
      const pattern = input.pattern as string;
      const directory = input.directory as string;
      const maxResults = (input.maxResults as number) ?? 50;
      const hits = grepFiles(pattern, directory, maxResults);
      return hits.length > 0 ? hits.join('\n') : 'لم يُعثر على تطابقات.';
    }
 
    return `أداة غير معروفة: ${name}`;
  } catch (err) {
    return `خطأ في الأداة: ${(err as Error).message}`;
  }
}

// agent-loop.ts
import Anthropic from '@anthropic-ai/sdk';
import { toolDefinitions, executeTool } from './tools.js';
 
const client = new Anthropic();
 
const SYSTEM = `أنت مهندس برمجيات أول تُجري مراجعة كود شاملة ومنهجية.
 
سير العمل:
1. استدعِ list_directory على جذر المشروع (recursive: true) لفهم البنية.
2. اقرأ ملفات الإعداد الرئيسية أولاً: package.json، tsconfig.json، .eslintrc.
3. اقرأ كل ملف مصدر رئيسي بالتسلسل.
4. استخدم search_pattern للبحث عن المشاكل الأمنية الشائعة: eval، dangerouslySetInnerHTML، بناء SQL بالنصوص، الأسرار المضمّنة.
5. بعد قراءة جميع الملفات ذات الصلة، اكتب تقريراً منظماً.
 
صيغة التقرير:
## مشاكل حرجة
## أولوية عالية
## أولوية متوسطة
## توصيات`;
 
export async function runReviewAgent(projectPath: string): Promise<void> {
  const messages: Anthropic.MessageParam[] = [
    {
      role: 'user',
      content: `أجرِ مراجعة شاملة للكود في المسار: ${projectPath}
 
راجع كل شيء — الأمان، الصحة، جودة TypeScript، معالجة الأخطاء، والبنية المعمارية. ابدأ باستكشاف بنية المشروع.`,
    },
  ];
 
  let iteration = 0;
  const maxIterations = 40;
 
  console.log(`\nمراجعة كود Fable 5 — ${projectPath}\n${'─'.repeat(60)}\n`);
 
  while (iteration < maxIterations) {
    iteration++;
 
    const response = await client.messages.create({
      model: 'claude-fable-5',
      max_tokens: 8192,
      system: SYSTEM,
      tools: toolDefinitions,
      messages,
    });
 
    messages.push({ role: 'assistant', content: response.content });
 
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
 
    for (const block of response.content) {
      if (block.type === 'text' && block.text) {
        process.stdout.write(block.text);
      } else if (block.type === 'tool_use') {
        const input = block.input as Record<string, unknown>;
        console.log(`\n  [${block.name}] ${JSON.stringify(input).slice(0, 80)}`);
        const result = executeTool(block.name, input);
        toolResults.push({
          type: 'tool_result',
          tool_use_id: block.id,
          content: result,
        });
      }
    }
 
    if (toolResults.length > 0) {
      messages.push({ role: 'user', content: toolResults });
      continue;
    }
 
    if (response.stop_reason === 'end_turn') {
      console.log(`\n${'─'.repeat(60)}\nاكتمل — ${iteration} دورة`);
      break;
    }
 
    console.warn(`\nstopped: ${response.stop_reason}`);
    break;
  }
 
  if (iteration >= maxIterations) {
    console.warn('بلغت الحد الأقصى للدورات — قد تكون المراجعة غير مكتملة.');
  }
}

// deep-review.ts
import Anthropic from '@anthropic-ai/sdk';
import { toolDefinitions, executeTool } from './tools.js';
 
const client = new Anthropic();
 
export async function runDeepSecurityAudit(projectPath: string): Promise<void> {
  const messages: Anthropic.MessageParam[] = [
    {
      role: 'user',
      content: `أجرِ تدقيقاً أمنياً عميقاً للمشروع في: ${projectPath}
 
ركّز على:
- ثغرات الحقن (SQL، الأوامر، اجتياز المسار)
- عيوب المصادقة والتفويض
- كشف البيانات الحساسة والأسرار في الكود
- التبعيات الضعيفة في package.json
 
افحص جميع ملفات المصدر بعناية، ثم قدّم تقرير أمني مفصلاً.`,
    },
  ];
 
  let iteration = 0;
 
  while (iteration < 30) {
    iteration++;
 
    const response = await client.messages.create({
      model: 'claude-fable-5',
      max_tokens: 16000,
      tools: toolDefinitions,
      messages,
      thinking: {
        type: 'enabled',
        budget_tokens: 8000,
      },
    });
 
    messages.push({ role: 'assistant', content: response.content });
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
 
    for (const block of response.content) {
      if (block.type === 'thinking') {
        console.log(`\n  [تفكير — ${block.thinking.length} حرف]`);
      } else if (block.type === 'text' && block.text) {
        process.stdout.write(block.text);
      } else if (block.type === 'tool_use') {
        console.log(`\n  [${block.name}]`);
        const result = executeTool(
          block.name,
          block.input as Record<string, unknown>
        );
        toolResults.push({
          type: 'tool_result',
          tool_use_id: block.id,
          content: result,
        });
      }
    }
 
    if (toolResults.length > 0) {
      messages.push({ role: 'user', content: toolResults });
      continue;
    }
    if (response.stop_reason === 'end_turn') break;
  }
}

// cached-agent.ts
import Anthropic from '@anthropic-ai/sdk';
import { readFileSync } from 'fs';
import { toolDefinitions, executeTool } from './tools.js';
 
const client = new Anthropic();
 
export async function runCachedReview(projectPath: string): Promise<void> {
  let packageJson = '(لا يوجد package.json)';
  try {
    packageJson = readFileSync(`${projectPath}/package.json`, 'utf-8');
  } catch { /* غير موجود */ }
 
  const systemContent: Anthropic.TextBlockParam[] = [
    {
      type: 'text',
      text: `أنت مراجع أمان وجودة كود.\n\nملف package.json للمشروع:\n\`\`\`json\n${packageJson}\n\`\`\`\n\nارجع إليه عند تحليل التبعيات.`,
      cache_control: { type: 'ephemeral' }, // تخزين هذه الكتلة الكبيرة مؤقتاً لمدة 5 دقائق
    },
    {
      type: 'text',
      text: 'استخدم الأدوات المتاحة لقراءة ملفات المصدر. صنّف المشاكل حسب الخطورة.',
    },
  ];
 
  const messages: Anthropic.MessageParam[] = [
    {
      role: 'user',
      content: `راجع جميع ملفات TypeScript في ${projectPath} للكشف عن مشاكل الأمان وجودة الكود.`,
    },
  ];
 
  let iteration = 0;
  let cachedTokensSaved = 0;
 
  while (iteration < 30) {
    iteration++;
 
    const response = await client.messages.create({
      model: 'claude-fable-5',
      max_tokens: 8192,
      system: systemContent,
      tools: toolDefinitions,
      messages,
    });
 
    const usage = response.usage as Anthropic.Usage & {
      cache_read_input_tokens?: number;
    };
    if (usage.cache_read_input_tokens) {
      cachedTokensSaved += usage.cache_read_input_tokens;
    }
 
    messages.push({ role: 'assistant', content: response.content });
    const toolResults: Anthropic.ToolResultBlockParam[] = [];
 
    for (const block of response.content) {
      if (block.type === 'text') process.stdout.write(block.text);
      else if (block.type === 'tool_use') {
        const result = executeTool(
          block.name,
          block.input as Record<string, unknown>
        );
        toolResults.push({
          type: 'tool_result',
          tool_use_id: block.id,
          content: result,
        });
      }
    }
 
    if (toolResults.length > 0) {
      messages.push({ role: 'user', content: toolResults });
      continue;
    }
 
    if (response.stop_reason === 'end_turn') {
      const savedUsd = ((cachedTokensSaved * 9) / 10 / 1_000_000) * 10;
      console.log(
        `\n\nوفّر التخزين المؤقت ~${savedUsd.toFixed(4)} دولار (${cachedTokensSaved.toLocaleString()} رمز بخصم 90%)`
      );
      break;
    }
  }
}

// review-agent.ts
import 'dotenv/config';
import { runCachedReview } from './cached-agent.js';
 
const projectPath = process.argv[2];
 
if (!projectPath) {
  console.error('الاستخدام: npx tsx review-agent.ts <المسار>');
  process.exit(1);
}
 
console.log('مراجع كود Claude Fable 5');
console.log(`المسار  : ${projectPath}`);
console.log('النموذج : claude-fable-5');
console.log('السياق  : مليون رمز  |  الإخراج الأقصى: 128 ألف رمز\n');
 
runCachedReview(projectPath).catch((err) => {
  console.error('\nخطأ في الوكيل:', err.message);
  process.exit(1);
});

npx tsx review-agent.ts ./src