أدوات التطوير (adk-devtools)

adk-devtools هي مجموعة أدوات الحلقة الداخلية التي يحتاجها وكيل البرمجة — القراءة، التحرير، البحث، والتشغيل — مع كون كل عملية مقيّدة بمجلد مساحة عمل. إنها crate مستقلة قابلة للنشر تعتمد فقط على adk-core، لذا فهي تتوافق مع أي LlmAgent (يقوم هيكل CodingAgent بتهيئتها لك).

الأدوات

DevToolset هو Toolset يضم ست أدوات:

سلوكان من سلوكيات الأمان يجدر معرفتهما:

• edit_file يتطلب read_file مسبقًا لذلك الملف في الجلسة، و افتراضيًا يجب أن تظهر السلسلة الهدف مرة واحدة بالضبط (replace_all للتجاوز). هذا يحمي من الكتابة فوق المحتوى بشكل أعمى.
• grep يتخطى أدلة البناء/‏VCS الشائعة (target، .git، node_modules، …) والملفات الثنائية/المتجاوزة للحجم.

تقوم أداة bash ببث خرج stdout/stderr سطرًا بسطر عبر ToolContext::emit_progress أثناء تنفيذ الأمر، بحيث يمكن لواجهات المستخدم عرض طرفية حية. تصل كل كتلة كحدث جزئي على EventStream الخاص بالوكيل (يمكن اكتشاف ذلك باستخدام event.tool_progress_stream())؛ ولا يزال الخرج الكامل يُعاد كنتيجة نهائية للأداة. راجع مثال streaming_bash و تقدم البث من أداة.

Workspace

تقوم Workspace بتأصيل كل عملية ضمن دليل وتفرض سياسة صغيرة:

use adk_devtools::Workspace;
use std::time::Duration;

let ws = Workspace::new("./my-repo");              // read-write, bash enabled
let ws = Workspace::read_only("./my-repo");        // explore/plan: no writes, no bash
let ws = Workspace::new("./my-repo")
    .allow_bash(false)                              // file edits, but no shell
    .bash_timeout(Duration::from_secs(60))
    .max_output_bytes(512 * 1024);

• احتواء المسار — أي مسار يُحلّ خارج الجذر يُرفض، لذا لا يستطيع الوكيل القراءة أو الكتابة إلى ../../etc/.... يُفرض الاحتواء على المسار المحلول، لا على الحرفي فقط: أي رابط رمزي يشير خارج الجذر يُرفض حتى لو كان موجودًا لغويًا داخله. وهذا يغطي المكوّن النهائي المرتبط برابط رمزي والدليل الأب المرتبط برابط رمزي، لذا يُرفض أيضًا الإنشاء عبر دليل معاد التوجيه. أما الرابط الرمزي الذي يبقى هدفه داخل مساحة العمل فيستمر في العمل، لأن المستودعات تتضمن روابط داخلية بشكل مشروع.

  هذا الفحص ليس قفلًا. فلو وُضع رابط رمزي بين الفحص والفتح اللاحق فسيظل متبوعًا؛ وإغلاق تلك النافذة يتطلب اجتيازًا مرتبطًا بالواصفات مع دلالات عدم المتابعة الخاصة بالمنصة. تعامل مع أدوات الملفات على أنها احتواء ضد وكيل يتجول، لا كعزل ضد خصم يستطيع الكتابة في مساحة العمل بالتزامن.

• وضع القراءة فقط — Workspace::read_only(..) يخفي أدوات التعديل بالكامل (النموذج لا يرى إلا read_file/glob/grep).

• بيئة bash تُفرَّغ — يتلقى الأمر فقط PATH وHOME وLANG، LC_ALL وTMPDIR وTERM وUSER وSHELL، لذلك مفاتيح المزود API الموجودة لدى عملية الوكيل ليست قابلة للقراءة باستخدام env. يعيد Workspace::inherit_env(true) السلوك القديم «مرّر كل شيء»، ويستبدل env_allowlist المجموعة.

• مهلة bash وحدود الخرج — الأوامر الطويلة أو كثيرة الكلام تكون محدودة. يُقتل الأمر الذي انتهت مهلة تنفيذه باعتباره مجموعة عمليات، لذا يُقتل كل ما بدأه أيضًا؛ سابقًا كان يُرسل إشارة إلى الابن المباشر فقط وكانت التوابع تبقى حية.

استخدامه مباشرة

أرفق مجموعة الأدوات بأي وكيل:

use adk_devtools::{DevToolset, Workspace};
use adk_agent::LlmAgentBuilder;
use std::sync::Arc;

let agent = LlmAgentBuilder::new("coder")
    .model(model)
    .toolset(Arc::new(DevToolset::new(Workspace::new("./my-repo"))))
    .build()?;

يعرض DevToolset فقط الأدوات التي تسمح بها مساحة العمل، لذا فإن مساحة عمل للقراءة فقط تعطي تلقائيًا وكيلًا للقراءة فقط.

نموذج العزل

المرحلة 1 تعمل bash محليًا على المضيف (sh -c، ودليل العمل مثبت إلى الجذر) مع مهلة وبيئة مُفرَّغة. ما الذي يقدمه ذلك وما الذي لا يقدمه:

لذلك فهو مقيّد بالمسار، ومعزول عن البيئة، ومحدود، لكنه ليس معزولًا عن نظام التشغيل. تتوافق مفردات السياسة مع adk-code's SandboxPolicy؛ ولعزلٍ قوي، شغّل bash خلف منفّذ تنفيذ مُحَوْصَل (انظر مستند التصميم). ادمجه مع adk-guardrail (قوائم السماح للأوامر، إخفاء الأسرار) وadk-auth للأدوات الموسومة برموز (مثلًا GitHub).

التالي: الإطار التشغيلي →