الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
هذه الصفحة تبني coding agent يعمل في الـ terminal على طريقة Claude Code: يقرأ ملفات مشروعك ويعدّلها، ويشغّل أوامر، ويسألك قبل أن يكتب ملفًا أو يشغّل شيئًا خطرًا، ويُبقي المحادثة مستمرة لأسئلة المتابعة. تحتاج إلى Node 22، ومفتاح API في متغيّر البيئة الذي يتوقعه الـ provider (OPENAI_API_KEY للـ model المستخدم هنا)، ومجلد مشروع تشغّله فيه. الملف الجاهز في آخر الخطوة 5، وتشغّله هكذا npx tsx coding.ts "Fix the failing test".

1. أعطِ الـ agent workspace

الـ workspace مجلد يعمل فيه الـ agent. NodeWorkspace هو نظام الملفات والـ shell لها، وcreateFsTools() وcreateShellTool() تحوّل الـ workspace إلى tools.
root مهم: كل path يمرّره الـ model ينحصر داخله، و.. والمسارات المطلقة وحروف الأقراص مرفوضة (راجع نموذج الأمان). شغّل البرنامج من مجلد المشروع واستخدم process.cwd() كـ root، وبهذا لا تصل file tools إلى أي شيء خارج المشروع. يرى الـ model سبع tools: read_file وwrite_file وedit_file وlist_dir وglob وgrep من createFsTools()، وshell من createShellTool(). وسيطاتها وخياراتها في Workspace tools.

2. حدّد ما يحتاج approval

أي tool عليها needsApproval توقف الـ run قبل التنفيذ، لكي يقرر إنسان. القراءة لا ضرر فيها، فاطلب approval (موافقة) على file tools التي تغيّر شيئًا فقط، بخريطة لكل tool. وللـ shell مرّر predicate (دالة تعيد true أو false) على نص الأمر، واطلب approval على الأوامر التي تعتبرها خطرة فقط.
أداة الـ shell تطلب approval افتراضيًا (needsApproval: true)؛ الـ predicate أعلاه يجعل أي شيء آخر، مثل npm test أو git status، يعمل دون سؤال. الطريقة الأخرى لتخطّي السؤال هي قائمة allow بالأوامر التي تثق بها مع needsApproval: false، كما هو مكتوب في بداية Workspace tools. استخدم هناك قواعد دقيقة مثل { command: 'npm test' }: النص العادي مثل 'npm test' يسمح بالأمر مع أي arguments، بما فيها flags تكتب خارج الـ workspace. الـ regex تسهيل، وليس حدًا أمنيًا: أمر الـ shell يمكن كتابته بطرق كثيرة. لأي شيء لا تتحكم فيه، أبقِ الافتراضي ووافق على كل أمر، أو شغّل الـ shell داخل sandbox (راجع SandboxShell في Workspace tools).

3. شغّله وتابع الـ stream

أنشئ الـ agent بالـ tools، ثم استدعِ agent.stream(). تعيد run تمرّ عليه بـ for await وتأخذ typed events: text.delta يحمل نص الـ model أولًا بأول أثناء كتابته، وtool.start يعلن عن كل tool call (راجع Streaming).
maxSteps يحدد عدد استدعاءات الـ model في run واحد، فلا يدور الـ agent المرتبك إلى ما لا نهاية. هذا البرنامج يتوقف عند أول call يحتاج approval: ينتهي الـ stream بحدث approval.requested وينتهي الـ run بالحالة 'awaiting-approval'. الخطوة التالية تعالج هذا. بادئة vendor/ في اسم الـ model تختار الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini).

4. تعامل مع التوقف

عندما ينتهي الـ stream، يعطيك await run.result النتيجة النهائية. إذا توقف الـ run، يسمّي result.approvalId الـ call المعلّق. اسأل المستخدم، ثم تابع بـ agent.approvals.streamResolve() التي تعيد run جديدًا لبقية العمل. وقد يتوقف هذا الـ run مرة أخرى، فكرّر الحلقة حتى لا يبقى approvalId.
تفصيلتان في الـ stream بعد الاستئناف. الـ call الذي وافقت عليه للتو يُستأنف بحدث tool.resume — فقد طُبع tool.start الخاص به في الـ run الذي توقف، فتطبع الحلقة كل call مرة واحدة (وtool.resume هو الحدث الذي تطابقه إذا أردت أن تعلّم الـ call بأنه عاد إلى العمل). والـ call المرفوض لا يُفشل الـ run: يأخذ الـ model نتيجة رفض بدلًا من output الـ tool ويتابع. ولإخباره بالسبب، مرّر note: streamResolve({ id, approved: false, note: 'Do not touch the lockfile' }). وtry / finally تغلق واجهة readline حتى لو رُفض run.result لأن الـ run فشل. حدث approval.requested يحمل أيضًا toolName وargs، فتستطيع طباعة ما سينفذه الـ call قبل أن تسأل. راجع Approvals للـ API كامل.

5. حافظ على استمرار المحادثة

حتى الآن تبدأ كل مهمة من الصفر. agent.session() تنشئ session (جلسة) تحتفظ بالـ transcript (سجل المحادثة)، فترى متابعةٌ مثل “now add a test for the empty case” الـ turns السابقة. وsession.stream(input) هي agent.stream() لكن لمحادثة، وتعيد نوع الـ run نفسه؛ والـ turn الذي يتوقف على call يحتاج approval يكتمل في الـ session نفسها عندما تحسمه عبر الـ agent نفسه (راجع الـ streaming داخل session). حوّل الحلقة إلى REPL: session.stream() واحدة لكل سطر يكتبه المستخدم، مع معالجة التوقف نفسها.
تأتي المهمة الأولى من سطر الأوامر (أو من prompt إذا لم توجد مهمة)؛ وبعد كل رد يسأل البرنامج عن السطر التالي، والسطر الفارغ أو exit ينهي البرنامج. الـ session موجودة في الذاكرة، فتنتهي بانتهاء العملية؛ إذا أردت محادثة تبقى بين runs، أعطِ الـ agent store (مخزن) (راجع اختيار store).

الـ turns الطويلة وإعادة التشغيل

  • السياق. الـ turn في coding agent يقرأ ملفات ويشغّل اختبارات ويعدّل على مدى خطوات كثيرة؛ وكل نتيجة tool تبقى في الـ transcript، فقد يتجاوز turn من 40 خطوة نافذة سياق (context window) بحجم 128k token قبل أن ينتهي. مرّر createAgent({ compaction: true }) (أو دالة تلخيص، راجع ضغط السياق): يضغط السياق قبل كل استدعاء للـ model، حتى بين خطوات الـ turn الواحد.
  • الانهيار. مع store متين، يُكمل session.send() التالي أو session.resume() الـ turn الذي قُتل في منتصفه. والـ tool call الذي كان قيد التشغيل عندما توقفت العملية يعمل مرة أخرى (at-least-once). وwrite_file وedit_file المدمجتان آمنتان لإعادة التشغيل: write_file تكتب المحتوى نفسه مرة أخرى، وedit_file التي يوجد تعديلها أصلًا في الملف (old_string اختفى وnew_string موجود) تنجح برسالة “the edit was already applied” بدلًا من أن تفشل. ومع WorkspaceCheckpoints، تُحفظ نسخة احتياطية لكل تغيير قبل كتابة الملف، وتحتفظ إعادة التشغيل بالنسخة الأولى، فيعيد rewind() الأصل حتى بعد الانهيار.
  • عرض التقدّم أثناء الاستئناف. session.resume() تعيد نتيجة، لا stream، وsession.stream() لا تبث الـ turn المعلّق الذي تكمله قبل الرسالة الجديدة. لعرض التقدّم، سجّل session.on((event) => ...) قبل الاستدعاء، أو مرّر createAgent({ onEvent }): كلاهما يستلم AgentEvents الخاصة بالـ turn المستأنف (tool.start، text.delta، …، run.done) أولًا بأول.
  • الـ approvals بعد إعادة التشغيل. agent.approvals.streamResolve({ id, approved }) (أو resolve()) من process جديد، بالـ store المتين نفسه، يكمل الـ turn المتوقف في الـ session الخاصة به؛ دون أن تستدعي session.resume() قبل ذلك.

6. اختبره بدون model

الـ agent لا يحتاج إلى شبكة لكي تختبره. MemoryWorkspace يُبقي الملفات في الذاكرة ويأخذ exec مكتوبًا مسبقًا للـ shell، وmockModel يؤدي دور الـ model. تحقق من workspace.snapshot() وworkspace.commands.
لاختبار مسار الـ approval، اطلب approval على write_file كما يفعل الـ agent الحقيقي. send() تنتهي بـ finishReason: 'awaiting-approval' وapprovalId، ويبقى الملف دون تغيير، وagent.approvals.resolve() تنفّذ الكتابة وتنهي الـ turn.
وللتحقق من الـ prompt الحقيقي والـ tool schemas على model مرة واحدة ثم إعادة تشغيل التسجيل بعدها، راجع Record and replay.

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

  • Workspace tools: المرجع الكامل للـ tools، ونموذج الأمان، وSandboxShell لتشغيل الأوامر في Docker.
  • التراجع عن تعديلات الـ agent على الملفات: مرّر WorkspaceCheckpoints إلى createFsTools(workspace, { checkpoints })، ثم يعرض لك checkpoints.rewind(turn, { sessionId: session.id, dryRun: true }) ما سيُستعاد إذا عدت إلى turn معيّن.
  • Approvals: الـ durable approval stores، ودوال approve، واتخاذ القرار من process آخر.
  • Streaming: كل أنواع الـ events، وإلغاء run، وصيغ الـ stream للويب.
  • Sessions: الـ stores والحدود والـ durable sessions.
  • Durable execution: يكتمل الـ run حتى لو تعطّلت العملية في منتصفه.
  • Configuration: projectInstructions: true يلحق ملف AGENTS.md أو CLAUDE.md بالـ instructions.