أداة سطر أوامر واحدة لكل خدمات زوهو
zone هي واجهة سطر الأوامر الموحّدة لمنظومة زوهو — 64 خدمة، و9,432 أمرًا مكتوبًا، وتسجيل دخول OAuth واحد.
كل خدمة في زوهو لها واجهة برمجية خاصة بها، وصلاحيات خاصة بها، وخصوصياتها الدقيقة — فينتهي كل من يعمل على أتمتة زوهو إلى كتابة دورة OAuth نفسها، وحلقة الترقيم نفسها، ومنطق إعادة المحاولة نفسه مرارًا. تقوم zone بذلك مرة واحدة: تسجّل الدخول مرة، ثم تدير CRM وBooks وDesk وPeople وProjects و59 خدمة أخرى من أداة واحدة بعقد إخراج واحد متّسق.
npm install -g wanas-zone-cli
zone loginكل ما تحتاجه هو Node.js واتصال بسجل npm. تنشرها ونس ابس FZ-LLC — شريك زوهو المميّز.
موافقة واحدة، بلا مطاردة للرموز
المصادقة هي الجزء الذي يعيد الجميع كتابته ولا يستمتع به أحد. تتعامل zone معه باعتباره بنية تحتية محسومة.
موافقة OAuth واحدة
موافقة واحدة في المتصفح تغطّي كل خدمة تختارها عند تسجيل الدخول. لا تسجيل عميل لكل خدمة، ولا نسخ لرموز التحديث بين السكربتات.
الرموز تبقى على جهازك
تُحفظ الجلسات في مخزن محلي، ملف لكل خدمة. ويجري التحديث وإعادة المحاولة عند الخطأ 401 تلقائيًا، فلا يتوقف سكربت طويل بسبب رمز منتهي الصلاحية.
هوية مستقلة لكل مشروع
يكتب أمر zone login مخزنًا باسم ./.zone ويعثر عليه بالطريقة نفسها التي يعثر بها git على .git — بالصعود من مجلد العمل. وهكذا يمكن لكل مجلد مشروع أن يحمل هوية زوهو مختلفة: مؤسسة عميل هنا، وبيئة اختبار هناك. أما --global فيعود إلى ~/.zone.
إدراك لمراكز البيانات منذ البداية
يُختار مركز البيانات عند تسجيل الدخول ويُدمج في كل عنوان أساسي، فلا تختلط مؤسسة إماراتية بأخرى أوروبية أبدًا.
طريقتان لتشغيلها
أوامر مكتوبة لكل ما جرى تغليفه بالفعل، ووسيط عام لكل ما عداه. وكلاهما يتشارك المصادقة نفسها وعقد الإخراج نفسه ورموز الخروج نفسها.
الأوامر المكتوبة
أمر حقيقي لكل عملية — تتكفّل الأداة بأجسام الطلبات والترقيم وتنزيل الملفات وخصوصيات زوهو في كل نقطة نهاية. وكل مجموعة أوامر قابلة للاستكشاف عبر --help.
zone crm record list Deals --fields Deal_Name,Stage,Amount
zone crm field list Deals
zone books invoice list --status overdue
zone desk ticket list --jsonالوسيط zone api
ما لم يُغلَّف بعد يبقى على بعد أمر واحد. يوقّع الوسيط الطلب بالجلسة نفسها، ويحدّد العنوان الأساسي وفق مركز البيانات، ويعيد الجسم الخام — فلا تعطّلك نقطة نهاية جديدة في زوهو.
zone api crm GET /crm/v8/settings/modules
zone api books POST /invoices --data @invoice.json
zone api desk GET /api/v1/tickets --jsonمبنية لوكلاء البرمجة الأذكياء
اطلب من وكيل برمجة ذكي أن «يجلب الفواتير المتأخرة ويطابقها بصفقات CRM»، وبلا أدوات مناسبة سيفعل ثلاثة أشياء بصورة رديئة: يكتب تدفّق OAuth لا يستطيع إتمامه، ويخمّن مسارات REST من ذاكرته، ويخترع أسماء حقول لا وجود لها في مؤسستك. وكل هذه الإخفاقات صامتة — فتحصل على شيفرة تبدو سليمة ولا تُرجع شيئًا. تستبدل zone بهذه التخمينات الثلاثة سطحَ أوامر واحدًا: مُصادَقًا، ومكتوبًا، وموثّقًا ذاتيًا.
لماذا يغيّر ذلك النتيجة
المصادقة منتهية سلفًا
ينفّذ إنسانٌ أمر zone login مرة واحدة. فلا يرى الوكيل أي سر، ولا يكتب معالج OAuth، ولا يطلب منك لصق رمز في نافذة محادثة.
أسماء الحقول من مؤسستك أنت
يُعيد الأمر zone crm field list Deals أسماء الحقول الحقيقية من CRM لديك. فيقرأها الوكيل بدل أن يهلوس بين Deal_Name وdealName — وهو السبب الأول لسكربت زوهو الذي يعمل بلا أخطاء ولا ينجز شيئًا.
مخرجات قابلة للتحليل فعلًا
يضع --json و--toon البيانات القابلة للقراءة الآلية على stdout ويبقيان رسائل التقدّم على stderr، فلا حاجة لانتزاع أي شيء من نصٍّ سردي. وصيغة TOON أكثرهما إيجازًا حين تكون ميزانية السياق ضيّقة.
إخفاقات يستطيع رصدها
لرموز الخروج معنى: 0 نجاح، و2 خطأ استخدام، و3 غير مسجّل الدخول، و4 صلاحية ناقصة، و5 رفض من زوهو، و6 محجوب بسياسة، و7 قابل لإعادة المحاولة (شبكة أو 429 أو 5xx). ومع --json يكون آخر سطر على stderr دائمًا كائن خطأ منظَّمًا — حتى عند نقص وسيط — مع تلميح يسمّي الحل. فيتفرّع الوكيل بناءً عليه بدل إعادة المحاولة عشوائيًا.
قابلة للاستكشاف، فيبحث بدل أن يخمّن
يعرض zone <service> --help مجموعات الأوامر، ويعرض zone <svc> <group> --help أوامرها المفردة. فالوكيل الذي يجهل أمرًا يجده باستدعاء واحد بدل أن يخترعه.
الدليل كاملًا عند الطلب
يطبع zone llm دليل استخدام كاملًا مولَّدًا من مواصفات الأوامر الحيّة، فلا يمكن أن يتخلّف عمّا تشحنه الأداة فعلًا. ويحصره zone llm <service> في خدمة واحدة حين تضيق نافذة السياق.
ثبّت الدليل حيث يبحث وكيلك أصلًا
يثبّت أمر zone skill موجِّهًا ومهارةً لكل خدمة — أسماء الأوامر الحقيقية، والوسائط التي تشترطها زوهو، وأشكال الحِمل، والمزالق المكتشفة على مؤسسات حيّة — في صورة ملفات مهارات أو قواعد أصلية لوكيلك. ولا يُقيم في كل موجّه إلا وصف المهارة من سطر واحد؛ أما متنها فيُحمَّل حين يُستدعى. وإعادة التشغيل بعد الترقية تحدّث ملفات zone وحدها ولا تمسّ ما كتبته أنت.
zone skill --ide claude- Claude Code — .claude/skills/zoho-zone/SKILL.md
- Antigravity / Gemini — .agents/skills/zoho-zone/SKILL.md
- Cursor — .cursor/rules/zoho-zone.mdc
- Windsurf — .windsurfrules
- GitHub Copilot — .github/copilot-instructions.md
- Cline / Roo Code — .clinerules
- Gemini CLI — GEMINI.md
- Codex / معيار AGENTS.md — AGENTS.md
- ملف Markdown مستقل — ZOHO_ZONE_AI_CONTEXT.md
سير عمل واقعي لوكيل ذكي
المهمة: العثور على كل صفقة بحالة Closed Won في CRM لا تقابلها فاتورة مدفوعة في Books. وهذا ما ينفّذه الوكيل فعليًا.
- ٠١
إنسان يصادق على المشروع، مرة واحدة
موافقة المتصفح هي الخطوة الوحيدة التي تحتاج إلى شخص. ونفّذها داخل مجلد المشروع فتكتب ./.zone، لتقتصر هذه الهوية على هذا المستودع وحده.
zone login crm books - ٠٢
الوكيل يحمّل سطح الأوامر
أمر واحد يضع كل مجموعات الأوامر المكتوبة في ملف قواعد الوكيل. ومن هنا يصير يختار الأوامر بدل أن يخترعها.
zone skill --ide claude - ٠٣
يقرأ بنية بياناتك الحقيقية قبل كتابة أي استعلام
قائمة الحقول تأتي من مؤسستك، فيبني المرشّح التالي بأسماء برمجية موجودة فعلًا.
zone crm field list Deals --json - ٠٤
يسحب الطرفين بهوية واحدة
الجلسة نفسها، وخدمتان، وبلا تدفّق OAuth ثانٍ. ويتكفّل الأمر بالترقيم.
zone crm record list Deals --fields Deal_Name,Stage,Amount --per-page 200 --json zone books invoice list --status paid --json - ٠٥
يتعامل مع الإخفاق بدل إخفائه
إن لم تكن Books ضمن الموافقة، يخرج الأمر بالرمز 3 ويطبع خطأً منظَّمًا. فيتوقف الوكيل ويطلب منك تسجيل الدخول لتلك الخدمة وحدها — بدل تكرار نداء لا يمكن أن ينجح.
# exit 3 — not authenticated {"ok":false,"error":{"code":"NOT_AUTHENTICATED","message":"Not signed in to books.","hint":"Run \"zone login books\" (or \"zone login --all\").","http_status":null,"zoho":null,"context":null}}
لا تُنفَّذ عمليات الكتابة إلا حين تُستدعى صراحةً. ولا شيء مما سبق يعدّل سجلًا، ولا يستطيع وكيل أن يحصل على صلاحية لم توافق عليها.
آمنة في يد وكيل موجَّه إلى مؤسسة حيّة
حين يمنح إطارُ برمجةٍ وكيلَه صلاحية تشغيل zone من الصدفة، فقد منحه كل عملية كتابة على كل خدمة زوهو مصادَق عليها — ولا يستطيع التعبير عن «القراءة فقط». لذلك تسكن الضوابط داخل zone، عند المفصل الوحيد الذي يمرّ به كل طلب، ويفشل اختبار إن تجاوزه أي نداء.
--dry-run على كل أمر
تُحلّ عملية الكتابة وتُطبع — الطريقة والمسار والجسم — بدل إرسالها، وبرمز خروج 0. أما القراءات فتعمل، ليتمكّن الوكيل من إبقائها مفعّلة وهو يبني النداء. وتحترمها عمليات الرفع والتنزيل وأمر zone bug أيضًا.
zone crm record delete Leads 123 --dry-run --json
{"dry_run":true,"service":"crm","method":"DELETE","path":"/Leads/123","query":{},"body":null,"api_version":null}سياسة قراءة فقط تعني القراءة فقط
يحكم ZONE_POLICY (أو --allow / --deny) بالخدمة والطريقة؛ والمنع يغلب دائمًا، ويخرج النداء المحجوب بالرمز 6 مسمّيًا القاعدة. وتُصنَّف نقاط النهاية بما تفعله لا بفعلها: فـ COQL والقراءة الجماعية قراءتان، وعمليات الكتابة التي تخدمها Campaigns عبر GET كتابات.
ZONE_POLICY='*:GET' zone crm record create Leads --data @lead.json --json
{"ok":false,"error":{"code":"POLICY_DENIED","message":"Blocked by policy: crm:POST /Leads — not in the allow list.", ...}}الأسرار لا تخرج مكشوفة أبدًا
تُحجب الحقول المسمّاة كبيانات اعتماد على كل مسار خروج — stdout وتفاصيل --verbose وسطر الخطأ الآلي سواء — وتُمسح القيمة الحرفية لأي سرّ ZONE_* من النص الحرّ. ولا تُرفَق الرموز إلا بمضيفات زوهو، ويُرفض أي مسار يحوي «..» قبل تشغيل السياسة.
zone books org list --json | grep -c "«redacted»"سجلّ تدقيق تسلّمه للعميل
يُلحق --audit <file> سطر JSONL واحدًا لكل طلب — حقيقيًا كان أو محجوبًا أو تجريبيًا — بالطريقة والمسار والأثر (قراءة أو كتابة) والحالة والتوقيت. بيانات وصفية فقط بلا أي جسم، فلا يصير السجلّ موضعًا جديدًا تتسرّب منه بيانات العميل.
{"ts":"2026-09-04T16:35:54.367Z","service":"crm","method":"DELETE","path":"/Leads/1","effect":"write","status":null,"outcome":"denied","policy":"denied","dry_run":false,"ms":null,"pid":40992}تُفرض الأربع كلّها عند مفصل واحد — عميل API الخاص بـ zone — الذي يمرّ به كل أمر مكتوب، والوسيط zone api، وكل رفع وتنزيل للملفات، وأمر zone bug. وتفشل مجموعة الاختبارات إن ظهر نداء HTTP خام في أي موضع خارجه.
تغطية مقيسة على وثائق زوهو نفسها
قِيست كل خدمة على وثائق واجهتها البرمجية الرسمية ثم سُدَّت الفجوة. و30 من الـ64 تغطّي اليوم 100% من سطحها الموثّق؛ أي نحو 7,280 عملية موثّقة عبر المنظومة كلها. وحيثما تنشر زوهو مواصفة قابلة للقراءة الآلية، تُولَّد الأوامر منها لا من النصّ.
| الخدمة | الأوامر | ما تغطّيه |
|---|---|---|
| Zoho Desk | 931 | التذاكر وقاعدة المعرفة والمجتمع وقواعد الإسناد والتحفيز |
| Zoho Books | 903 | مولَّدة من مواصفات OpenAPI الخاصة بزوهو، ومعها Invoice وBilling وExpense |
| Zoho CRM | 792 | بيانات V8/V9 الوصفية كاملة — التخصيص وأتمتة العمليات والأمان وZia — ومعها COQL والمهام الجماعية وأدوات Deluge |
| Zoho Inventory | 556 | الأصناف والمستودعات والطلبات والشحنات ودورة المخزون كاملة |
| Zoho Projects | 507 | سطح V3 كاملًا، بما فيه نقاط النهاية في v3.1 |
| Zoho People | 447 | الإصداران المنشوران: v1/v2 للتعلّم والجداول الزمنية، وv3 للإجازات والورديات |
Deluge من محرّرك
ارفع دوال Deluge واسحبها واختبرها كملفات. وتعود أخطاء الترجمة بأرقام أسطر حقيقية مطابقة للملف على قرصك، لا برسالة 400 فارغة.
استخراج كامل لبيانات CRM الوصفية
يسحب zone crm extract وحدات مؤسستك وحقولها وتخطيطاتها ودوالّها إلى القرص — وهو المرجع المعتمد لكتابة Deluge أو شيفرة REST على تلك المؤسسة، ومُدخَل طبيعي لأي وكيل ذكي.
كل مراكز البيانات، بما فيها الاستثناءات الإقليمية
مركز البيانات جزء من تسجيل الدخول لا فكرة لاحقة — وzone تعرف أي المنتجات موجود فعلًا في كل مركز.
- com
- eu
- in
- com.au
- jp
- uk
- ca
- sa
- ae
- cn
تُفرض المنتجات الإقليمية عند تسجيل الدخول بدل أن تفشل لاحقًا: فـ Zoho Payroll مثلًا لا يوجد إلا في com وin وae وsa، ولذلك ترفض zone تسجيل دخول Payroll على أي مركز بيانات آخر ابتداءً. فطلب صلاحية إقليمية على مركز بيانات خاطئ كان سيُبطل الموافقة كلها.
الحزم المنشورة
zone واجهة رقيقة فوق أربع حزم قابلة لإعادة الاستخدام. الخمس جميعها مفتوحة المصدر ومجانية، تنشرها ونس ابس FZ-LLC على npm، وشيفرتها على GitHub.
بنينا zone لأننا ننفّذ مشاريع زوهو يوميًا، واحتجنا أداة واحدة بدل أربع وأربعين. هي مجانية، وستبقى كذلك.
تحتاج ربط هذا بمنظومة زوهو لديك؟
نحن شريك زوهو المميّز بأكثر من 300 مشروع تطبيق منجز. وإن أردت تكاملات مخصّصة أو أتمتة Deluge أو وكلاء ذكاء اصطناعي يعملون على مؤسسة زوهو لديك، فنحن هنا.