cargo adk build

نظرة عامة

يقوم الأمر cargo adk build بتجميع مشروع الوكيل ADK-Rust من دون نشره. ويوفّر لك ذلك طريقة سريعة للتحقق من تجميع وكيلك بشكل صحيح — واكتشاف مشكلات التبعيات وأخطاء الأنواع ومشكلات الإعداد — قبل الالتزام بدورة نشر كاملة.

استخدم cargo adk build كجزء من سير عمل التطوير المحلي وخطوط CI للتحقق من التغييرات مبكرًا، من دون الحاجة إلى بيانات اعتماد المنصة أو الوصول إلى الشبكة.

بناء جملة الأمر

cargo adk build [OPTIONS]

يغلّف الأمر cargo build --release افتراضيًا، مستهدفًا مشروع وكيلك. عند النجاح، يعرض ملف تعريف البناء ودليل الهدف وحجم الملف الثنائي.

العلامات والخيارات

أمثلة

# Build in release mode (default)
cargo adk build

# Build in debug mode for faster iteration
cargo adk build --debug

# Build a project at a specific path
cargo adk build --manifest-path /path/to/my-agent/Cargo.toml

البناء مقابل النشر

يخدم cargo adk build وcargo adk deploy أغراضًا مختلفة في دورة حياة تطوير الوكيل:

متى تستخدم كلًّا منها

• cargo adk build — استخدمه أثناء التطوير للتحقق من نجاح التجميع، وفي مسارات CI كشرط قبل الدمج، أو للتحقق من أن تحديثات التبعيات لا تؤدي إلى تعطيل وكيلك.
• cargo adk deploy — استخدمه عندما تكون مستعدًا لشحن وكيلك إلى منصة ADK. يتضمن النشر خطوة بناء داخليًا (يمكن تخطيها باستخدام --skip-build).

أمثلة الاستخدام

بناء ناجح

$ cargo adk build
   Compiling adk-core v0.9.2
   Compiling adk-agent v0.9.2
   Compiling my-agent v0.1.0 (/home/user/my-agent)
    Finished `release` profile [optimized] target(s) in 42.3s
✅ Build successful
   profile: release
   target:  target/release
   binary:  target/release/my-agent (12.4 MB)

بناء تصحيح لتكرار أسرع

$ cargo adk build --debug
   Compiling my-agent v0.1.0 (/home/user/my-agent)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 8.1s
✅ Build successful
   profile: debug
   target:  target/debug
   binary:  target/debug/my-agent (45.2 MB)

التكامل مع مسار CI

# .github/workflows/ci.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo install cargo-adk
      - run: cargo adk build

سيناريوهات الأخطاء وحلولها

التبعيات المفقودة

العَرَض: يفشل التجميع بسبب أخطاء استيراد لم يتم حلها.

error[E0432]: unresolved import `adk_tool`
 --> src/main.rs:3:5
  |
3 | use adk_tool::FunctionTool;
  |     ^^^^^^^^ use of undeclared crate or module `adk_tool`

الحل: أضف الحزمة المفقودة إلى تبعيات Cargo.toml:

[dependencies]
adk-tool = { version = "2.1.0", features = ["mcp"] }

بنية المشروع غير صالحة

العَرَض: يتعذر على cargo adk build العثور على Cargo.toml.

Error: failed to run cargo build: No such file or directory (os error 2)

الحل: شغّل الأمر من جذر مشروعك، أو حدّد مسار البيان:

cargo adk build --manifest-path ./my-agent/Cargo.toml

تعارضات أعلام الميزات

العَرَض: يفشل البناء بسبب مجموعات ميزات غير متوافقة.

error: the package `my-agent` depends on `adk-realtime`, with features:
       `openai-webrtc` but `openai-webrtc` is not a feature of `adk-realtime`

الحل: تحقق من تطابق أعلام الميزات مع الميزات المتاحة لإصدار ADK الذي تستخدمه. شغّل cargo doc -p adk-realtime --open للاطلاع على الميزات المتاحة، أو راجع توثيق الحزمة.

ملف القفل القديم

العَرَض: أخطاء في حل الإصدارات بعد ترقية حزم ADK.

error: failed to select a version for the requirement `adk-core = "^0.9.2"`

الحل: حدّث ملف القفل:

cargo update
cargo adk build

مشكلات بيئة البناء

العَرَض: أخطاء في الرابط أو مكتبات النظام المفقودة.

error: linker `cc` not found

الحل: ثبّت سلسلة أدوات البناء المطلوبة لمنصتك:

# Ubuntu/Debian
sudo apt install build-essential pkg-config libssl-dev

# macOS
xcode-select --install

# Fedora/RHEL
sudo dnf install gcc openssl-devel

نفاد الذاكرة أثناء التجميع

العَرَض: يتم إنهاء عملية البناء أو تتوقف بسبب فشل التخصيص.

الحل: قلّل التوازي أو استخدم جهازًا بذاكرة وصول عشوائي أكبر:

# Limit parallel compilation jobs
CARGO_BUILD_JOBS=2 cargo adk build

# Or set in .cargo/config.toml
# [build]
# jobs = 2