كل نقرة في واجهة Sharkly هي قرار اتخذه شخص ما: إنشاء هذه المهمة، إسناد ذلك الوكيل، التحقق من تشغيل ما. تلك هي الواجهة المناسبة للأحكام والقرارات. لكنها الواجهة الخاطئة عند تكرار القرار نفسه للمرة الألف. فبمجرد أن يقرر فريقك أن كل عملية بناء ليلية فاشلة يجب أن تصبح مهمة، يتحول النقر عبر الشاشات من سير عمل إلى عبء روتيني.
هنا يأتي دور الواجهة البرمجية. تتيح واجهة Sharkly الطرفية (CLI) للأشخاص والوكلاء والنصوص البرمجية العمل مع Sharkly من الطرفية: إدارة موارد المؤسسة، وتسجيل جهاز Computer لتنفيذ مهام الوكلاء، وفحص الخدمة المحلية، وأتمتة سير العمل المتكرر. وخلف كل ذلك تقف واجهة REST API على api.sharkly.ai التي تقبل نفس رموز الوصول الشخصية التي تستخدمها واجهة CLI.
هذا الأمر أكثر أهمية بالنسبة لـ Sharkly من أدوات إدارة المشاريع التقليدية، لأن Sharkly ليست مجرد مكان يُوصَف فيه العمل، بل هي المكان الذي يُنفَّذ فيه العمل. تضيف Sharkly طبقة المهام المشتركة وأجهزة Computer والسياق والتحكم والمراجعة حول أدوات البرمجة مثل Claude Code وCodex، لذا فإن أمرًا برمجيًا مثل sharkly task create لا يقتصر على تسجيل تذكرة. فإذا كانت المهمة مسندة إلى وكيل وفي حالة جاهزة، فيمكنها بدء تشغيل حقيقي على جهاز Computer حقيقي. أي أن أتمتة الواجهة تعني أتمتة القوى العاملة.
باختصار
تتيح واجهة Sharkly الطرفية (الأمر sharkly) للأشخاص والوكلاء والنصوص البرمجية العمل مع Sharkly من الطرفية، وهي أيضًا الطريقة التي تُثبَّت بها الخدمة المحلية على المضيفات البعيدة ومضيفات Linux حتى تنضم إلى أسطولك كأجهزة Computer. المصادقة مقسّمة عن قصد: رمز الوصول الشخصي (بادئة shk_) يسجّل دخول إنسان أو نص برمجي، ورمز التثبيت لمرة واحدة (بادئة sit_) يسجّل جهاز Computer، أما تشغيلات الوكلاء فتستخدم بيانات اعتماد تنفيذ محددة النطاق تُوفّرها Sharkly. وبوجود الرمز، يمكن للنصوص البرمجية إنشاء المهام وتعديلها والتعليق عليها وفحص التشغيلات والسجلات وإدارة أجهزة Computer، وكل ذلك مع --output json لتحليل نظيف. ويعمل الرمز نفسه shk_ كرمز bearer مع واجهة REST API، كما تتيح محفزات webhook في الأتمتة لأنظمة CI والأنظمة الخارجية الأخرى بدء تشغيلات الوكلاء بطلب POST.
منصة واحدة، وواجهتان
واجهة Sharkly وواجهتها البرمجية مدخلان إلى النظام نفسه. فالمهمة التي ينشئها نصك البرمجي هي المهمة ذاتها التي يراها زميلك على اللوحة، بالحالة وسير العمل والتعليقات وسجل التنفيذ نفسها. ولا تتجاوز الأتمتة أبدًا السجل المشترك: فالأتمتة تغذّي نظام السجل الرسمي.
من المفيد تقسيم الواجهتين حسب من يتخذ القرار. استخدم الواجهة الرسومية عندما يتخذ شخص حكمًا أو قرارًا: صياغة متطلب، مراجعة فرق برمجي، قبول نتيجة. واستخدم واجهة CLI أو API عندما يكون القرار قد اتُّخذ بالفعل ولا يتبقى سوى تكرار الجوانب الميكانيكية: تسجيل مهام من نظام مراقبة، أو سحب سجلات التشغيل إلى لوحة معلومات، أو فحص سلامة أجهزة Computer من مهمة cron. يمكن للنص البرمجي إنشاء المهمة وحتى بدء التشغيل، لكن القبول يبقى بيد شخص.
تثبيت واجهة CLI، وما الذي تثبّته
على macOS أو Linux، المُثبِّت الرسمي أمر واحد:
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
أما Windows فلديه مُثبِّت PowerShell رسمي، وهو حاليًا لمعمارية AMD64 فقط. وعلى أي منصة، تحقق من التثبيت وحافظ عليه بالأمرين:
sharkly version
sharkly update
لواجهة CLI دور ثانٍ يتجاوز كونها عميلًا. تصف الوثائق مسارين لتوصيل جهاز Computer: تثبيت Sharkly Desktop على حاسوب شخصي مدعوم، أو تثبيت واجهة Sharkly الطرفية والخدمة المحلية على مضيف بعيد أو حاسوب Linux. وهذا المسار الثاني هو الكيفية التي يصبح بها خادم بناء أو جهاز Linux احتياطي أو حاوية قدرة تنفيذية لوكلائك. فالخدمة المحلية التي تُنشئها تسجّل جهاز Computer، وتكتشف بيئات التشغيل (Runtimes) المثبَّتة، وترسل نبضات الحياة، وتستقبل التشغيلات المُصطفّة، وتُعدّ أدلة المهام، وتبثّ التقدم عائدًا، وهي التي تبادر بالاتصال بنفسها فلا حاجة لأي منفذ وارد.
وإذا كنت لا تزال توصّل جهازك الأول عبر الواجهة الرسومية، فإن دليل البدء يغطي ذلك المسار.
ثلاث بيانات اعتماد، وثلاث مهام
تستخدم Sharkly بيانات اعتماد منفصلة لأغراض منفصلة، ويستحق هذا الفصل أن تستوعبه جيدًا قبل أتمتة أي شيء.
يبدأ رمز الوصول الشخصي بـ shk_ ويتيح لواجهة CLI أو لنص برمجي أو لعميل موثوق آخر التصرف بصفته حسابك. تنشئ واحدًا في الإعدادات، وتختار مدة انتهاء صلاحية من 30 يومًا أو 90 يومًا أو سنة أو بلا انتهاء، وتنسخ القيمة كاملة عند إنشائها مرة واحدة. سجّل الدخول عبر التدفق القائم على المطالبة حتى لا يقع الرمز أبدًا في سجل الأوامر:
sharkly login --token
sharkly auth status
ويبدأ رمز تثبيت جهاز الكمبيوتر بـ sit_، وتنتهي صلاحيته بعد 30 دقيقة، ويمكن استخدامه مرة واحدة فقط. ومهمته الوحيدة هي تسجيل جهاز Computer:
sharkly computer register --install-token sit_...
أما بيانات الاعتماد الثالثة فلا تتعامل معها إطلاقًا: إذ يحصل تشغيل الوكيل النشط على بيانات اعتماد تنفيذ محددة النطاق تُوفّرها Sharkly، ومحصورة في عائلات الأوامر التي تسمح بها سياقاته التنفيذية.
ترسم الوثائق الحدود بوضوح: رمز الوصول الشخصي لا يسجّل جهاز كمبيوتر، ورمز التثبيت لا ينشئ تسجيل دخول بشري لواجهة CLI. فالتسجيل ينشئ جلسة خدمة محلية مستقلة، ولهذا فإن إبطال رمزك الشخصي لاحقًا لا يُخرج أجهزة Computer المسجلة لديك عن الاتصال. وبالمثل، فإن sharkly auth logout يزيل الرمز فقط من ملفك الشخصي المحلي؛ ويبقى الرمز صالحًا على الخادم حتى تُبطله في الإعدادات.
أما في CI، فتخطَّ تدفق تسجيل الدخول بالكامل. إذ تقرأ واجهة CLI الرمز من متغير البيئة SHARKLY_TOKEN، الذي له أولوية على أي ملف شخصي محفوظ. واملأه من مخزن أسرار محمي، مثل أسرار GitHub Actions، بدلًا من كتابته في ملف سير العمل، وأبقِ المؤسسة صريحة باستخدام --organization-id.
إدارة أسطول من أجهزة Computer من الطرفية
بعد تسجيل المضيفات، تغطي مجموعة الأوامر sharkly computer الفحص والصيانة دون متصفح:
sharkly computer list --output json
sharkly computer show <computer-id> --output json
sharkly computer usage <computer-id> <runtime-id> --days 30 --output json
sharkly computer ping <computer-id> <runtime-id> --wait --output json
sharkly computer update <computer-id> <runtime-id>
يعرض list أجهزة Computer المسجلة للمؤسسة الحالية، ويعيد show جهاز Computer واحدًا مع بيئات التشغيل الخاصة به، ويفحص usage بيئة تشغيل محددة، ويتحقق ping مما إذا كانت تلك البيئة قادرة على إكمال رحلة ذهاب وعودة، ويطلب update تحديثًا لواجهة CLI لبيئة تشغيل. والسبب الذي وُجد ping من أجله: كون جهاز Computer متصلًا يعني فقط أن خدمته المحلية ترسل نبضات الحياة، لا أن بيئة تشغيل معينة قادرة على تنفيذ تشغيل الآن.
وعلى المضيف نفسه، يستخدم التشخيص الروتيني الأوامر الموجّهة للمستخدم:
sharkly computer status --output json
sharkly computer logs --lines 100
وتكشف مساحة الأسماء daemon عن دورة حياة العمليات وأدوات التحكم بالقرص، بما في ذلك sharkly daemon disk-usage وsharkly daemon cleanup، وهو تنفيذ تجريبي ما لم تُضف --confirm. وقاعدة القرار في الوثائق: فضّل computer status وcomputer logs للتشخيص الروتيني، ولا تلجأ إلى daemon إلا عندما تحتاج إلى دورة حياة العمليات أو تقارير القرص أو التنظيف. وتتناول تدوينة أجهزة Computer في هذه السلسلة الملكية والظهور وسياسات التنظيف بمزيد من العمق.
أتمتة المهام: عمل يصل دون اجتماع
المهام هي حيث تستحق واجهة CLI مكانها في أي خط أنابيب. وتُقرأ مجموعة الأوامر كنسخة قابلة للبرمجة من اللوحة:
sharkly task list --output json
sharkly task search "authentication error" --output json
sharkly task create --title "Investigate authentication error" --output json
sharkly task edit <task-id> --status <status> --output json
sharkly task comment <task-id> --body "Investigation started." --output json
حالة الاستخدام الواضحة في CI هي تسجيل العمل تلقائيًا. فمهمة ليلية تكتشف إصدارًا فاشلًا لا تحتاج إلى شخص يملأ نموذجًا:
sharkly task create \
--title "Investigate the failed release" \
--body-file ./task-body.md \
--output json
استخدم --body-file أو --body-stdin كلما كان المحتوى الدقيق مهمًا، لأن الصيغة القصيرة --body تفكّك تسلسلات الهروب. ولأن المهمة المسندة إلى وكيل تبدأ تشغيلًا عندما تكون في حالة جاهزة، يمكن لهذا الأمر الواحد أن يكون قمة حلقة مؤتمتة بالكامل: يسجّل النص البرمجي المهمة، فيطالب بها الوكيل المُسنَد، وتعود عمليات التنفيذ والعوائق والنتيجة إلى المهمة حيث يراجعها شخص في صباح اليوم التالي.
وتحصل نصوص التقارير على مرشحات حقيقية بدل الفرز على جانب العميل. يمكنك التصفية حسب عمر الحالة باستخدام --status-changed-within 7d، وحسب الحقول المخصصة:
sharkly task list --space HF --field "Customer Tier=VIP" --output json
تُدمج أعلام --field المتكررة بعملية AND، والمطابقة واعية بالنوع ودقيقة، وتحدث التصفية على الخادم قبل ترقيم الصفحات. واعتمد اصطلاحات البرمجة في الوثائق بالكامل: اطلب --output json صراحةً، وأضف --color never و--quiet، وأبقِ --organization-id ظاهرًا، واستخدم set -euo pipefail. ورموز الخروج تعاقدية: 0 للنجاح، و1 لأخطاء الأوامر أو التحقق أو المصادقة أو واجهة API البعيدة، و2 لظروف الخدمة المحلية أو الشبكة العابرة، ما يجعل منطق إعادة المحاولة مباشرًا.
كما أن واجهة CLI تصف نفسها بنفسها. إذ يكشف sharkly schema task create --format json سجل الأوامر بصيغة قابلة للقراءة الآلية، ويعرض sharkly tldr task سيناريوهات مختارة بعناية، وهو أمر مهم عندما يكون الكاتب للنص البرمجي وكيلًا بحد ذاته.
متابعة التشغيلات دون فتح لوحة معلومات
التنفيذ قابل للمراقبة عبر الواجهة نفسها:
sharkly run list --task <task-id> --output json
sharkly run view <run-id> --output json
sharkly run log <run-id> --since <sequence> --output json
sharkly run cancel <run-id> --output json
يجعل العلم --since الاستقصاء الدوري معقولًا: إذ يسجّل نص المراقبة آخر رقم تسلسل تمت معالجته ولا يسترجع إلا الرسائل الأحدث في كل جولة. وإذا أضفت إلى ذلك sharkly agent list وsharkly automation view وsharkly automation runs، يمكنك بناء صفحة حالة لقواك العاملة من الوكلاء باستخدام نص shell بسيط و jq.
واجهة REST API ومحفزات webhook
كل ما تفعله واجهة CLI يستند إلى واجهة REST API، وتوضح الوثائق المسار المباشر: أرسل رمز وصولك الشخصي كرمز bearer عبر HTTPS.
curl -fsS https://api.sharkly.ai/rest/v1/users/current \
-H "Authorization: Bearer ${SHARKLY_TOKEN}"
الوصول عبر واجهة API محدود بصلاحيات المستخدم الذي يقف خلف الرمز؛ ولا يتيح نموذج الرموز الحالي اختيار نطاق لكل رمز على حدة، وهذا سبب وجيه لإنشاء رمز منفصل لكل خدمة بمدة انتهاء محددة. ويوجد مرجع نقاط الوصول على docs.sharkly.ai، كما أن استجابات --output json في واجهة CLI معاينة دقيقة للبنى التي ستتعامل معها.
وتتدفق الحركة في الاتجاه المعاكس أيضًا. إذ يمكن لـ أتمتة أن تحمل محفز webhook: تولّد Sharkly رابطًا سريًا يقبل طلب POST، ويبدأ أي طلب صالح تشغيل الوكيل أو الطاقم (Crew) الخاص بالأتمتة. ويُعرض الرابط الكامل مرة واحدة ويعمل كسرّ bearer افتراضيًا، مع تحقق اختياري من التوقيع. وهذا هو النصف الوارد من قصة CI: خط أنابيبك يخبر Sharkly «حدث شيء ما، شغّل وكيل الفرز».
يجدر الدقة في توضيح ما ليست عليه هذه الواجهة. فواجهة Sharkly الطرفية ليست وكيل برمجة آخر، وواجهة API ليست نقطة وصول لنموذج. فبيئات التشغيل مثل Claude Code وCodex تنفذ العمل، بينما تدير الواجهة البرمجية لـ Sharkly الطبقة المحيطة بها. وهذا الحياد يفصلها عن الخيارات المرتبطة بمنظومة بعينها مثل GitHub Agent HQ، حيث تعيش واجهة الأتمتة والتنفيذ داخل أسوار مورّد واحد.
من أين تبدأ
ابدأ أصغر مما تتخيل. أنشئ رمز وصول شخصي بمدة صلاحية 90 يومًا، ثم نفّذ sharkly login --token، وأتمت أكثر قراءة مملة تقوم بها كل يوم، مثل قائمة مهام تُمرّر عبر jq إلى ملخص صباحي. القراءات آمنة، وهي تعلمك بنى JSON. ثم أتمت كتابة واحدة بمحفز واضح، مثل إنشاء مهمة من مهمة CI فاشلة. ولا توصّل محفز webhook إلا بعد أن يصبح الأمران روتينيين.
النمط الذي يجب الحفاظ عليه هو الذي بُنيت عليه المنصة بأكملها: النصوص البرمجية والوكلاء يولّدون العمل وينفذونه، ويبقى السياق والتقدم والعوائق والنتائج والمراجعة البشرية ظاهرة من الطلب حتى الإصدار. أتمت المداخل، واحتفظ بالمراجعة.
الأسئلة الشائعة
هل أحتاج إلى واجهة CLI لاستخدام Sharkly؟
لا. فـ Sharkly Desktop يغطي توصيل حاسوب شخصي، ويغطي تطبيق الويب العمل اليومي على المهام. وتصبح واجهة CLI ضرورية عندما توصّل مضيفًا بعيدًا أو حاسوب Linux، لأن تثبيت واجهة Sharkly الطرفية والخدمة المحلية هو مسار الإعداد الموثق هناك، وتصبح ذات قيمة كلما تكرر سير عمل بما يكفي ليصبح النقر عبره تكلفة.
ما الفرق بين رمز الوصول الشخصي ورمز التثبيت؟
رمز الوصول الشخصي (بادئة shk_) يوثّق هوية إنسان أو نص برمجي بصفته حسابك، لتسجيلات دخول CLI ومهام CI وطلبات API المباشرة. أما رمز تثبيت جهاز الكمبيوتر (بادئة sit_) فهو لمرة واحدة وقصير العمر، وتنتهي صلاحيته بعد 30 دقيقة، ولا يسجّل إلا جهاز Computer. ولا يغني أحدهما عن الآخر.
هل يمكنني استدعاء واجهة Sharkly REST API مباشرةً بدلًا من استخدام واجهة CLI؟
نعم. أرسل رمز الوصول الشخصي كرمز bearer عبر HTTPS إلى api.sharkly.ai؛ وتوضح الوثائق النمط curl -fsS https://api.sharkly.ai/rest/v1/users/current مع ترويسة Authorization: Bearer. ويحمل الرمز صلاحيات حسابك.
كيف أنشئ مهمة من خط أنابيب CI؟
خزّن رمز shk_ كسرّ CI محمي واعرضه كمتغير البيئة SHARKLY_TOKEN، الذي تقرأه واجهة CLI تلقائيًا. ثم نفّذ sharkly task create مع --title و--body-file للمحتوى متعدد الأسطر الدقيق، و--organization-id صريح، و--output json حتى تتمكن المهمة من التقاط معرّف المهمة المُنشأة.
هل يؤدي إبطال رمز وصولي الشخصي إلى إيقاف أجهزة Computer المسجلة لدي؟
لا. فتسجيل جهاز Computer ينشئ جلسة خدمة محلية مستقلة عبر رمز التثبيت، لذا فإن إبطال رمز الوصول الشخصي لا يوقف تلك الأجهزة. لكن الإبطال يُلغي صلاحية الرمز في كل مكان يُستخدم فيه لطلبات CLI وAPI والأتمتة، ولهذا يجب أن يحدّث التبديل النصوص البرمجية المعتمدة عليه قبل إبطال الرمز القديم.
