إنتقل إلى المحتوى الرئيسي

استكشاف الأخطاء وإصلاحها

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

الملف الشخصي النشط خاطئ​

العرض: الأوامر تتصرف كما لو كانت الإعدادات أو بيانات الاعتماد مفقودة، لكنها موجودة في ملف شخصي آخر.

السبب المحتمل: الملف الشخصي النشط ليس الذي تقوم بتحريره.

الفحص:

cat ~/.estacoda/active-profile.json
estacoda profiles list

الإصلاح:

estacoda profile switch work
# أو استخدم --profile لأمر واحد
estacoda gateway status --profile work

مفتاح المزود مفقود​

العرض: خطأ يتطلب إعداد المزود، أو مسار النموذج يبلغ عن بيانات اعتماد مفقودة.

السبب المحتمل: متغير البيئة المشار إليه في apiKeyEnv غير موجود في .env الخاص بالملف الشخصي المحدد أو في بيئة العملية.

الفحص:

estacoda config show
# تحقق مما إذا كان متغير البيئة المشار إليه موجوداً
grep VOICE_TOOLS_OPENAI_KEY ~/.estacoda/profiles/<id>/.env

الإصلاح:

estacoda model setup
# أو قم بتحرير ~/.estacoda/profiles/<id>/.env يدوياً

مسار المزود غير متاح​

العرض: النموذج يستجيب بأنه غير متاح أو يتم تخطي المسار بصمت.

السبب المحتمل: تم اختيار مزود معروف بالكتالوج فقط، أو بيانات اعتماد مفقودة لمسار يحتاج اعتمادًا، أو نقطة نهاية المزود غير قابلة للوصول. بالنسبة للمزود المدمج local، مفتاح API اختياري؛ افحص قابلية الوصول إلى نقطة النهاية وقيمة baseUrl أولًا.

الفحص:

estacoda model status
estacoda gateway diagnose

الإصلاح:

  • قم بالتبديل إلى مزود مثبت عملياً.
  • تحقق من بيانات الاعتماد.
  • تحقق من اتصال الشبكة.

المتصفح غير مهيأ​

العرض: أداة المتصفح تُرجع غير مهيأ أو الخلفية غير متاحة.

السبب المحتمل: browser.backend غير مضبوط أو تم ضبطه على مزود سحابي غير منفذ بشكل مباشر.

الفحص:

estacoda config show | grep -A 5 browser

الإصلاح:

اضبط browser.backend على local-cdp لـ CDP المحلي، أو اضبط Browserbase مع BROWSERBASE_API_KEY وBROWSERBASE_PROJECT_ID وestacoda browser approve-cloud. تبقى browser-use وFirecrawl browser وCamofox مزودات مؤجلة ولا يمكنها إنشاء جلسات مباشرة.

فشل إعداد STT المحلي​

العرض: يفشل estacoda voice setup --stt-provider local أثناء إنشاء Python، أو تثبيت faster-whisper==1.2.1، أو التحقق من import faster_whisper.

السبب المحتمل: Python النظام مفقود، أو python -m venv غير متاح، أو فشل تثبيت الحزمة، أو أن venv المُدار في ~/.estacoda/python-env تالف.

الفحص:

estacoda voice status
ls -la ~/.estacoda/python-env
ls -la ~/.estacoda/cache/huggingface

الإصلاح:

estacoda voice setup --stt-provider local
# أو استخدم بيئة Python يملكها المشغل
estacoda voice setup --stt-provider local --python-binary /path/to/python

الـ venv المُدار مخصص لـ faster-whisper==1.2.1 المثبت بالإصدار فقط. لا تستخدمه لحزم عشوائية. إذا أبلغ الإعداد عن نقص ensurepip أو دعم venv، ثبّت حزمة venv الخاصة بـ Python النظام، مثل sudo apt install python3.13-venv أو sudo apt install python3-venv، ثم أعد تشغيل إعداد STT المحلي. إذا استخدمت --python-binary، تتخطى EstaCoda فحص/إنشاء البيئة المُدارة وتترك بيئة Python للمشغل.

تنزيل نموذج STT المحلي مرفوض في البوابة​

العرض: يبلغ نسخ الصوت في البوابة أن تنزيل نموذج faster-whisper غير مسموح.

السبب المحتمل: ترث تنزيلات النموذج عبر البوابة allowModelDownload. التنزيلات مسموحة افتراضياً لأن allowModelDownload افتراضياً true؛ يعني هذا الخطأ أن تنزيلات البوابة عُطّلت صراحةً باستخدام stt.local.fasterWhisper.gatewayAllowModelDownload: false، أو عُطّلت كل تنزيلات نموذج faster-whisper باستخدام allowModelDownload: false.

الفحص:

estacoda config show
ls -la ~/.estacoda/cache/huggingface

الإصلاح:

اسمح بتنزيلات النموذج أو خزّن النموذج مسبقاً أثناء الإعداد/الاستخدام المحلي. إذا أردت السماح للتنزيل في الاستخدام المحلي/CLI مع إلزام رسائل البوابة الصوتية باستخدام نموذج مخزّن مسبقاً، اضبط stt.local.fasterWhisper.gatewayAllowModelDownload: false.

قناة البوابة غير جاهزة​

العرض: estacoda gateway diagnose يبلغ عن تحذيرات لقناة ما.

السبب المحتمل: رمز بيئة مفقود، أو قائمة سماح مفقودة، أو المحول معطل.

الفحص:

estacoda gateway diagnose
estacoda channels status telegram

الإصلاح:

estacoda channels enable telegram
# تحقق من وجود رمز البيئة في .env الخاص بالملف الشخصي
# تحقق من تكوين allowedUserIds أو allowedSenders

اعتمادات جسر WhatsApp مفقودة​

العرض: يبلغ estacoda whatsapp أو estacoda gateway diagnose أو estacoda gateway status أن اعتمادات جسر WhatsApp مفقودة.

السبب المحتمل: لم يتم تشغيل npm ci داخل حزمة npm المعزولة scripts/whatsapp-bridge/، أو أزيل دليل node_modules.

الفحص:

ls -la scripts/whatsapp-bridge
estacoda gateway diagnose

الإصلاح:

شغّل estacoda whatsapp ووافق على خطوة إصلاح الجسر الصريحة، أو شغّل:

cd scripts/whatsapp-bridge
npm ci

استخدم ESTACODA_WHATSAPP_BRIDGE_INSTALL_TIMEOUT لضبط مهلة الإصلاح الصريح. لا تضف Baileys أو @hapi/boom إلى حزمة الجذر.

انتهت مهلة QR pairing في WhatsApp​

العرض: يطبع الإعداد Pairing timed out - run estacoda whatsapp to try again.

السبب المحتمل: لم يتم مسح QR code خلال 120 ثانية، أو أن الطرفية لم تعرض QR code بوضوح.

الإصلاح:

شغّل estacoda whatsapp مرة أخرى من طرفية تستطيع عرض QR code. لا يتم تخزين QR strings.

WhatsApp ينتظر تفويض المستخدم​

العرض: تعرض التشخيصات pairing-pending أو waiting for user authorization بعد نجاح QR pairing.

السبب المحتمل: لم تُدخل مرسلين مسموحين أثناء الإعداد، لذلك يستخدم config القيمة dmPolicy: "pairing" بدلاً من الوصول المفتوح.

الإصلاح:

استبدل رمز تفويض مستخدم WhatsApp الآمن من حساب WhatsApp المقصود، أو أعد تشغيل estacoda whatsapp وأدخل مرسلين مسموحين صراحةً. dmPolicy: "pairing" ليست سياسة مفتوحة.

WhatsApp voice bubble غير متاحة​

العرض: يتم إرسال الصوت ذي voice hint كصوت عادي مع رسالة fallback.

السبب المحتمل: ffmpeg غير متاح، أو فشل التحويل، أو أن الصوت المصدر غير قابل للتحويل إلى OGG/Opus.

الإصلاح:

ثبّت ffmpeg في بيئة المشغل وأعد المحاولة. تنفذ main runtime التحويل داخل جذور temp/media الخاصة بالملف الشخصي؛ الجسر المعزول لا يشغل ffmpeg.

رمز Telegram أو متغير البيئة مفقود​

العرض: محول Telegram يفشل في البدء مع خطأ رمز مفقود.

السبب المحتمل: ESTACODA_TELEGRAM_BOT_TOKEN (أو البيئة المسماة في botTokenEnv) غير موجود.

الفحص:

grep ESTACODA_TELEGRAM_BOT_TOKEN ~/.estacoda/profiles/<id>/.env
echo $ESTACODA_TELEGRAM_BOT_TOKEN

الإصلاح:

أضف الرمز إلى .env الخاص بالملف الشخصي المحدد وأعد تشغيل البوابة. الإعداد الموجّه لـ Telegram يكتب الرمز تحت ESTACODA_TELEGRAM_BOT_TOKEN ويخزن botTokenEnv فقط في الإعدادات. يجب ألا يظهر رمز البوت الخام في مراجعة الإعدادات أو مخرجات الإعداد.

الثقة في مساحة العمل أو الموافقة مطلوبة​

العرض: الأمر محظور برسالة ثقة أو موافقة.

السبب المحتمل: مساحة العمل غير موثوقة، أو استدعاء الأداة يتطلب موافقة صريحة.

الفحص:

estacoda workspace trust status
estacoda gateway approvals

الإصلاح:

estacoda workspace trust
# أو وافق على الموافقة المعلقة
estacoda gateway approvals approve <id>

الأمر مرفوض بحظر أمان صارم​

العرض: استدعاء الأداة مرفوض برسالة حظر صارم. لا يُعرض زر موافقة.

السبب المحتمل: الأمر يطابق نمط أمان خطي (عملية قرص تدميرية، أو قراءة سر، أو قنبلة شوكة، إلخ).

الفحص:

راجع الأمر مقابل الحد الأدنى الخطي. لا يمكن تجاوز الحظر الصارم بالموافقة أو /yolo أو الوضع المفتوح.

الإصلاح:

أعد صياغة الأمر أو قسمه بحيث لا يطابق نمطاً خطياً. إذا كان الحظر إيجابياً خاطئاً، أبلغ عنه مع الأمر الدقيق والسياق.

كتابة الذاكرة مرفوضة​

العرض: memory.curate يُرجع رفضاً بالماسح الضوئي أو الأمان.

السبب المحتمل: المحتوى يطابق أنماطاً تشبه السر، أو علامات حقن الموجهات، أو أحرف تحكم غير مرئية.

الفحص:

تحقق من المحتوى بحثاً عن سلاسل تشبه مفاتيح API أو يونيكود غير عادي.

الإصلاح:

أزل المحتوى المشبوه وحاول مرة أخرى. يرفض الماسح الضوئي/الأمان منع الأسرار من الترقية إلى الذاكرة.

المهارة غير محددة أو مخفية​

العرض: الوكيل لا يستخدم مهارة تتوقعها.

السبب المحتمل: المهارة مؤرشفة، أو قديمة، أو تفتقر إلى مجموعة أدوات مطلوبة، أو تمت تصفيتها بواسطة قيود المنصة.

الفحص:

estacoda skills list

الإصلاح:

  • قم بتحديث الجلسة باستخدام /reset أو ابدأ جلسة جديدة.
  • تحقق من توفر مجموعات الأدوات المطلوبة للمهارة.
  • تحقق مما إذا كانت المهارة مؤرشفة أو قديمة.

الجلسة مفقودة أو قديمة أو محدودة بالملف الشخصي​

العرض: سياق الجلسة السابقة غير مرئي.

السبب المحتمل: الجلسات محددة بالملف الشخصي. الجلسة التي تم إنشاؤها في الملف الشخصي default لا تظهر في الملف الشخصي work.

الفحص:

estacoda sessions list --profile default
estacoda sessions list --profile work

الإصلاح:

التبديل إلى الملف الشخصي الذي يملك الجلسة، أو إرفاق السطح بالجلسة الصحيحة.

التحديث يقول إن التثبيت هو manual-source​

العرض: estacoda update يطبع git fetch origin && git status بدلاً من تطبيق تحديث.

السبب المحتمل: الختم .install-method.json مفقود، أو غير صالح، أو غير متطابق. يعامل EstaCoda الشخص كمساهم.

الفحص:

cat .install-method.json 2>/dev/null || echo "No stamp found"
git remote get-url origin
git rev-parse --abbrev-ref HEAD

الإصلاح:

إذا كنت قد ثبتت عبر curl | bash والختم مفقود، قد يكون الشخص قد تم نقله أو حذف الختم. حدث يدوياً بعبر git pull أو أعد التثبيت عبر المثبت.

التحديث يرفض شجرة عمل متسخة​

العرض: estacoda update يخرج بالرمز 3 ويبلغ عن تغييرات غير مرتكمة.

السبب المحتمل: شجرة عمل managed-source تحتوي على تعديلات محلية.

الفحص:

git status --short

الإصلاح:

ارتكِم، stash، أو تخلص من التغييرات، ثم أعد المحاولة. التخزين الآلي غير منفذ في v0.1.0.

حدث استعادة للتحديث​

العرض: estacoda update يبلغ عن فشل أثناء build أو التحقق، ثم "استعادة شخص managed-source إلى <sha>".

السبب المحتمل: فشل pnpm install أو pnpm run build بعد pull.

الفحص:

git log --oneline -3
node --version
which pnpm

الإصلاح:

أصلح مشكلة البيئة المحلية (إصدار Node، وجود pnpm)، ثم أعد محاولة estacoda update.

تلميح التحديث عند البدء يبدو قديماً​

العرض: رمز البدء يقول إنه يوجد تحديث متاح، لكن estacoda update --check يبلغ عن أنه محدث.

السبب المحتمل: TTL لـ ~/.estacoda/update-cache.json هي 6 ساعات. إذا قمت بالتحديث بطريقة أخرى (مثل git pull مباشرة)، قد تكون الذاكرة قديمة.

الإصلاح:

ستتحدث الذاكرة في الفحص التالي الناجح. تجاهل التلميح أو قم بتشغيل estacoda update --check لتحديثه.

تحديث البوابة لم يعد تشغيل الخدمة​

العرض: estacoda update --gateway نجح لكن البوابة لا تزال تشغيل الإصدار القديم.

السبب المحتمل: لم يتم اكتشاف خدمة بوابة مدارة. --gateway يعيد تشغيل الخدمات المثبتة فقط عبر estacoda gateway install-service.

الإصلاح:

أعد تشغيل البوابة يدوياً: estacoda gateway restart.

إلغاء التثبيت يرفض حذف دليل التثبيت​

العرض: estacoda uninstall يبلغ "managed-source stamp was not trusted" ويحتفظ بدليل التثبيت.

السبب المحتمل: الختم .install-method.json مفقود، غير متطابق، أو أن installDir ليس في القائمة الآمنة (estacoda، estacoda.git، estacoda-source).

الإصلاح:

أزل الدليل يدوياً إذا كنت متأكداً من أنه مملوك من قبل المثبت. يوجد بوابة الأمان للمساهمة لمنع الحذف العرضي لشخصوات المساهمين.

رفض التطهير (purge)​

العرض: estacoda uninstall --purge يخرج بالرمز 1 ويقول "أعد التشغيل مع --purge --yes".

السبب المحتمل: --purge دون --yes مرفوض. يتطلب كلا من العلمتين للتأكيد غير التفاعلي.

الإصلاح:

شغّل estacoda uninstall --purge --yes إذا كنت تنوي إزالة ~/.estacoda.

تثبيت مدير الحزم يوجّه إلى أمر مدير الحزم​

العرض: estacoda update أو estacoda uninstall يطبع أمراً خارجياً بدلاً من التصرف مباشرة.

السبب المحتمل: اكتشف EstaCoda تثبيتاً مداراً بواسطة مدير الحزم أو حاوية. لا يقوم بالتعديل الذاتي لتثبيتات مدير الحزم.

الإصلاح:

شغّل الأمر المطبوع (brew upgrade، docker pull، npm install -g، إلخ) أو استخدم مسار إلغاء التثبيت الأصلي لمدير الحزم.

تاريخ الأدوات الأصلي غير نشط​

العرض: جلسة أدوات تبدو مدعومة لكنها تعاد كتاريخ نصي مسطح بدلاً من تاريخ مساعد/أداة أصلي.

السبب المحتمل: فشلت إحدى بوابات إعادة التشغيل الأصلية، أو لا توجد مجموعة أدوات كاملة وآمنة من المزود لإعادة تشغيلها.

الفحص:

estacoda trace list --limit 5
estacoda trace dump <trajectory-id> --raw

ابحث عن structured-tool-history-skipped وسببه الخشن. الأسباب الشائعة تشمل مزوداً غير مدعوم، نموذجاً لا يدعم الأدوات، عدم وجود رسائل أصلية، تاريخاً مشوهاً، fallback بسبب الميزانية، صدى مفقود، صدى أكبر من الحد، أو وسائط غير آمنة.

الإصلاح:

  • استخدم مسار OpenAI-compatible Chat Completions مختبراً ويدعم الأدوات.
  • لا تتوقع إعادة التشغيل الأصلية على مسارات Responses أو Anthropic؛ هذه المسارات تبقى fallback/deferred.
  • إذا كان الدور غير آمن، أصلح دخل الأداة أو دع fallback النص المسطح المنظف يحمل السياق.

إعادة التشغيل التي تتطلب الصدى تفشل مغلقة​

العرض: تاريخ أدوات DeepSeek أو Kimi في وضع التفكير يرجع إلى fallback بدلاً من تسلسل استدعاءات أدوات أصلية.

السبب المحتمل: يتطلب المزود صدى reasoning_content لنفس المزود/وضع API، لكن الدور السابق يملك providerReplayEcho مفقوداً أو أكبر من الحد أو غير مطابق.

الفحص:

افحص التشخيصات ذات الأعداد فقط بحثاً عن missing_echo أو echo_oversized. لا تبحث في السجلات عن قيم الصدى؛ لا ينبغي أن تكون موجودة هناك.

الإصلاح:

  • تابع على نفس عائلة المزود ونفس وضع Chat Completions API عندما تكون إعادة تشغيل الصدى الأصلية مطلوبة.
  • إذا لم يلتقط الصدى أو كان أكبر من الحد، اسمح بـ fallback النص المسطح أو ابدأ دور أداة جديداً.
  • لا تضف placeholder للصدى إلا إذا كان مسار المزود لديه تغطية اختبار صريحة.

تعطلت إعادة تشغيل الأداة بسبب وسائط تحمل أسراراً​

العرض: دور استدعاء أدوات من المزود موجود، لكن إعادة التشغيل الأصلية تتخطاه بسبب وسائط غير آمنة.

السبب المحتمل: احتوت وسيطة استدعاء أداة على مادة اعتماد واضحة، لذلك لم تحفظ الوسائط الصادقة.

الفحص:

ابحث عن nativeReplaySafe: false وargumentsRedacted: true على دور استدعاء الأدوات من المزود. قد تعد التشخيصات unsafe_arguments، لكنها يجب ألا تحتوي قيمة الوسيطة.

الإصلاح:

أزل مادة الاعتماد من وسائط الأداة المطلوبة. استخدم مراجع أسرار، أو إعدادات، أو بيانات اعتماد مرتبطة بالبيئة بدلاً من وضع قيم سرية في الموجهات أو وسائط استدعاء الأدوات.

تاريخ أدوات متعدد الاستدعاءات يفشل مغلقاً​

العرض: دور مساعد متعدد الاستدعاءات لا يتسلسل كتاريخ أدوات أصلي.

السبب المحتمل: استدعاء واحد على الأقل لا يملك نتيجة أداة صالحة ومطابقة قبل الرسالة التالية غير الأداة، أو المجموعة مشوهة.

الفحص:

قارن metadata.providerToolCalls[].id على دور استدعاء الأدوات من المزود مع قيم metadata.tool_call_id في نتائج الأدوات التالية.

الإصلاح:

عامل المجموعة كتاريخ أصلي تالف. دع fallback النص المسطح يحمل السياق، أو أعد تشغيل التدفق حتى تحفظ رسالة استدعاء الأدوات من المزود ونتائج الأدوات بشكل نظيف. لا تنشئ نتائج أدوات اصطناعية لترقيع النص البروتوكولي.

المتابعة الأصلية تبدو كأنها تكرر نتائج الأدوات​

العرض: تظهر نتيجة أداة مرة كرسالة tool أصلية ومرة أخرى في تعليمة المتابعة المسطحة.

السبب المحتمل: لا ينبغي أن يحدث هذا لمجموعات الأدوات الأصلية المختارة. مسار المتابعة يستبعد معرفات استدعاءات الأدوات الأصلية المختارة من كتلة النتائج المنفذة المسطحة.

الفحص:

تحقق هل النتيجة المكررة تنتمي إلى مجموعة أصلية مختارة أم إلى مجموعة أقدم غير مختارة. نتائج الأدوات غير المختارة قد تبقى في نص المتابعة المسطح.

الإصلاح:

إذا تكررت نتيجة أصلية مختارة، عاملها كخلل في تجميع الموجه وشغل:

pnpm exec vitest run src/prompt/prompt-assembly.test.ts

تشخيصات إعادة التشغيل الأصلية تحتوي على محتوى​

العرض: حدث structured-tool-history-* يحتوي على وسائط، نتائج أدوات، قيم صدى، تفكير خام، حمولات مزود، محتوى رسائل، مسارات، تجزئات، أجسام طلبات، أو بصمات محتوى.

السبب المحتمل: عبر حدث تشخيصي حد المراقبة وسجل مادة حساسة من الموجه.

الفحص:

استخدم estacoda trace dump <trajectory-id> --raw وراجع شكل حمولة التشخيص فقط.

الإصلاح:

عامل هذا كخلل أمني. التشخيصات يجب أن تكون أعداداً وأسباباً خشنة فقط.

صفحات ذات صلة​