من ملف موثّق إلى أول عملية مضبوطة.

1. التنزيل والتثبيت

اختر الملف التنفيذي المطابق لنظام تشغيل الجهاز المستهدف ومعماريته. تحقّق من بصمة SHA-256 في صفحة التنزيلات، ثم ضعه في مسار دائم.

Expand-Archive -LiteralPath '.\helixflow-windows-amd64.exe.zip' -DestinationPath '.'

التحقق من سلامة الملف

احسب البصمة من مجلد التنزيل وقارنها بالقيمة المعروضة في صفحة التنزيلات.

Get-FileHash .\helixflow-windows-amd64.exe -Algorithm SHA256

استخدام مسار دائم

من مجلد الملف التنفيذي المستخرج، نفّذ هذه الأوامر في طرفية ضمن حسابك. تثبّت HelixFlow وتحدد المجلدات نفسها للطرفية وClaude وCodex. أبقِ الجلسة مفتوحة للخطوات التالية. استبدل «you» باسم حسابك في المسارات التوضيحية: C:\Users\you\HelixFlow\helixflow-windows-amd64.exe

.\helixflow-windows-amd64.exe version

2. تفعيل ترخيص الجهاز

أنشئ request.json بالإصدار الحالي على الجهاز الذي سيشغّل HelixFlow. يبقى الطلب ملف JSON، أما الترخيص الذي تتلقاه فهو ملف .lic بصيغة HFL1. يستمر الترخيص التجريبي 7 أيام (168 ساعة)، ولا تنتهي صلاحية الترخيص الدائم. كلاهما مرتبط بالجهاز.

.\helixflow-windows-amd64.exe license request --output request.json

يعرّف الطلب الجهاز لأغراض الترخيص. راقب مكان نقله ولا تنشره.

لديك ترخيص JSON قديم؟ احتفظ بالبرنامج القديم واطلب من الناشر إعادة إصدار الترخيص باستخدام طلب جديد من الإصدار الحالي. تغيير اسم الملف لا يحوّل صيغته. الترحيل لا يعيد بدء الفترة التجريبية. اتصل بنا

نزّل helixflow.lic من حسابك بعد إصداره (يتطلب الترخيص الدائم موافقة الناشر). ضعه في المجلد الحالي للطرفية ثم استورده وتحقق منه:

.\helixflow-windows-amd64.exe license import helixflow.lic
.\helixflow-windows-amd64.exe license status

3. إعداد ملف تعريف

ملف التعريف ملف نصي صغير بصيغة YAML يحدد خادم SecureTransport ‏(ST) الذي يتصل به HelixFlow وطريقة تسجيل الدخول. أنشئه على جهازك. لا يستقبل الموقع هذا الملف ولا بيانات دخول ST.

قبل البدء: اطلب معلومات الاتصال بـ ST

يدير SecureTransport حسابات مؤسستك وعمليات نقل الملفات. تستخدم هذه الأمثلة صلاحية الدخول إلى الإدارة.

1. اطلب عنوان HTTPS ومنفذ إدارة ST، مثل https://st01.example.test:8444. المنفذ 8444 مثال وقد يختلف لديكم. لا تضف ‎/api/v2.0 أو مسار صفحة ويب إلى base_url.
2. اطلب حساب مسؤول ST يملك صلاحيات القراءة المطلوبة. حساب موقع HelixFlow وحساب ST المخصص لنقل الملفات لا يعوّضان حساب المسؤول.
3. تحقق مع فريق ST من إمكانية الوصول إلى العنوان من جهازك عبر الشبكة الداخلية أو VPN، ثم اختبر الحساب في واجهة ST. اطلب من الفريق معالجة كلمة مرور منتهية أو حساب مقفل.

شهادة الخادم: «هل هذا هو خادم ST المقصود؟»

يتحقق القسم tls من هوية الخادم: يستخدم system الجهات الموثوقة في نظام التشغيل، ويستخدم ca ملف جهة التصديق الذي يقدمه فريقك، بينما يعطّل insecure هذا التحقق.

شهادة العميل: «من يتصل بخادم ST؟»

يقدّم القسم client_auth شهادتك إلى ST ويستخدم مفتاحها الخاص محليًا لإثبات هويتك. تسمّى هذه الطريقة mTLS. لا يُرسل المفتاح الخاص إلى الخادم مطلقًا؛ يمكن مشاركة الشهادة العامة فقط.

اختر إحدى الطريقتين التاليتين: أ. الاتصال باسم مستخدم وكلمة مرور · ب. الاتصال باستخدام شهادة عميل

اختيار جذر إعداد صريح

إذا فتحت طرفية جديدة، أعد ضبط هذه المتغيرات الأربعة قبل أوامر الترخيص أو إعداد MCP. تبقى المجلدات ضمن مجلد المستخدم، بما في ذلك عند استخدام Codex على Windows: C:\Users\you\HelixFlow\config

$env:HELIXFLOW_CONFIG_DIR = 'C:\Users\you\HelixFlow\config'

أنشئ مجلد profiles ثم أنشئ الملف C:\Users\you\HelixFlow\config\profiles\validation.yaml

افتح محرر نصوص والصق مثالًا كاملًا واحدًا واحفظه باسم validation.yaml وليس validation.yaml.txt. حافظ على مسافات الإزاحة ولا تستخدم علامات الجدولة. الأمثلة بدائل: استبدل محتوى الملف بدل جمعها معًا.

أ. الاتصال باسم مستخدم وكلمة مرور

استخدم اسم مستخدم مسؤول ST وكلمة مروره. يحدد YAML مكان الحصول عليهما فقط: لا تضع قيمتهما في حقول login أو password داخل الملف.

مثال مع التحقق من هوية الخادم

base_url: https://st01.example.test:8444
env_class: test
tls:
  mode: system
credentials:
  source: env

استبدل عنوان المثال. تصف env_class البيئة الفعلية: test للمختبر وpreprod لما قبل الإنتاج وprod للإنتاج. لا تصنّف خادم إنتاج على أنه test. الاسم validation هو اسم الملف دون ‎.yaml.

مثال للمختبر مع tls.mode: insecure

إذا كان مختبرك يستخدم شهادة خادم ذاتية التوقيع وغير موثوقة، يتيح هذا المثال تجربة أولى. يبقى الاتصال مشفّرًا عبر HTTPS، لكن HelixFlow لا يتحقق من هوية الخادم؛ وقد يلتقط خادم منتحل بيانات دخولك.

base_url: https://st01.example.test:8444
env_class: test
tls:
  mode: insecure
credentials:
  source: env

احصر insecure في مختبر معزول. للاستخدام المعتاد، اختر system أو استخدم القسم tls من مثال الشهادة أدناه، بالقيمة mode: ca ومسار مطلق إلى server-ca.pem. احصل على شهادة جهة التصديق من فريق ST. لا يفرض استخدام اسم المستخدم وكلمة المرور وضع insecure.

$stCredentials = Get-Credential -Message 'SecureTransport credentials for validation'
$env:HELIXFLOW_LOGIN = $stCredentials.UserName
$env:HELIXFLOW_PASSWORD = $stCredentials.GetNetworkCredential().Password
Remove-Variable stCredentials

keyring set helixflow/validation login
keyring set helixflow/validation password

printf 'ST login: '; IFS= read -r HELIXFLOW_LOGIN
printf 'ST password: '; IFS= read -rs HELIXFLOW_PASSWORD; printf '\n'
export HELIXFLOW_LOGIN HELIXFLOW_PASSWORD

لا تلصق بيانات اعتماد SecureTransport في هذا الموقع أو ملف إعداد MCP أو محادثة مع المساعد.

ب. الاتصال باستخدام شهادة عميل

تستبدل هذه الطريقة كلمة مرور ST بشهادة موثوقة مرتبطة بحساب مسؤول ST. أعدّ ST أولًا مع فريق إدارته، ثم أعدّ جهازك.

1. الحصول على الملفات من فريق ST أو PKI

يشير PKI إلى الفريق أو الخدمة المسؤولة عن إصدار الشهادات. اطلب شهادة X.509 لمصادقة العميل، باستخدام clientAuth، ومفتاحها المطابق وشهادات جهات التصديق. تغيير اسم الملف لا يغيّر صيغته.

client.pem

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

client.key

المفتاح الخاص المطابق بصيغة PEM غير مشفّرة، ويجب حمايته بصلاحيات نظام التشغيل. إذا تلقيت P12/PFX أو مفتاح PEM مشفّرًا، استخدم بديل P12 أدناه بمساعدة فريق PKI.

client-issuer-ca.pem

الشهادة العامة للجهة التي وقّعت شهادة العميل، مع الشهادات الوسيطة اللازمة. يستخدمها فريق ST لاعتماد شهادة العميل.

server-ca.pem

جهة التصديق التي يستخدمها جهازك للتحقق من شهادة HTTPS لخادم ST. قد تختلف عن الجهة التي وقّعت شهادة العميل.

2. إعداد مصادقة الشهادة في SecureTransport

نفّذ هذه الخطوات في واجهة إدارة ST مع مسؤول مخوّل. الأسماء أدناه تخص واجهات ST التقليدية وقد تختلف حسب الإصدار.

1. احتفظ بطريقة دخول احتياطية للمسؤول بكلمة مرور سبق اختبارها، وجهّز إجراء استعادة الوصول قبل تغيير الإعدادات.
2. في Setup > Certificates > Trusted CAs، استورد جهة إصدار شهادة العميل وشهاداتها الوسيطة مع فريق ST. استورد الشهادات العامة فقط، ولا تستورد client.key.
3. في Setup > Admin Settings، فعّل دخول المسؤول باستخدام شهادات العميل. اختر Client certificates: optional وقبول الجهات الموثوقة (any trusted issuer)، ثم احفظ. لا تفرض required في التجربة الأولى.
4. في Accounts > Administrators، افتح حساب المسؤول المعني واضبط Certificate DN على الموضوع الدقيق لشهادة العميل. DN هو الهوية الكاملة مثل CN=helixflow-reader,O=Example، وليس بالضرورة اسم المستخدم. احفظ التغيير.
5. اطلب من فريق ST تطبيق الإعداد وإعادة تشغيل خدمة إدارة ST حسب إجراءاته. قد تنقطع واجهة الإدارة أثناء ذلك؛ ولا تكفي إعادة تشغيل خدمة HTTP الخاصة بنقل الملفات وحدها.
6. بعد إعادة التشغيل، تحقق من استمرار عمل الدخول الاحتياطي بكلمة المرور. ثم اختبر ملف الشهادة الجديد بعملية قراءة كما هو موضح أدناه.

لعرض موضوع الشهادة العامة، شغّل هذا الأمر من مجلدها إذا كان OpenSSL مثبتًا. انسخ القيمة بعد subject= دون هذه البادئة، واطلب من فريق ST التحقق من مطابقتها الدقيقة مع Certificate DN. وإلا فاطلب DN من الفريق.

openssl x509 -in client.pem -noout -subject -issuer -dates -nameopt RFC2253

تخص هذه الخطوات واجهة API الإدارية. أما Authentication > Login Settings وLogin Certificates في حساب نقل الملفات فتخص وصولًا مختلفًا. إذا استخدم المسؤول LDAP أو مصادقة خارجية، فاطلب تأكيد توافقها مع الشهادة أو الوضع dual قبل المتابعة.

مراجع Axway: راجع «Administrator login options» وإدارة المسؤولين للإصدار المستخدم. Axway SecureTransport 5.5 — Administrator Guide · Axway — LDAP (KB 71206)

3. إنشاء ملف التعريف وحماية المفتاح على جهازك

أنشئ مجلد certs داخل جذر الإعدادات الذي اخترته أعلاه وضع الملفات فيه. استبدل «you» في ca_path باسم حسابك؛ يجب أن يكون هذا المسار مطلقًا. تبدأ مسارات ‎../certs في client_auth من مجلد profiles الذي يحتوي validation.yaml وتعمل على الأنظمة الثلاثة.

config/
  profiles/
    validation.yaml
  certs/
    server-ca.pem
    client.pem
    client.key

base_url: https://st01.example.test:8444
env_class: test
tls:
  mode: ca
  ca_path: 'C:/Users/you/HelixFlow/config/certs/server-ca.pem'
client_auth:
  mode: certificate
  cert_path: ../certs/client.pem
  key_path: ../certs/client.key

لا يوجد قسم credentials: هذا يعني المصادقة بالشهادة فقط دون اسم مستخدم أو كلمة مرور ST. إذا كان نظامك يثق بشهادة الخادم أصلًا، استخدم tls.mode: system واحذف ca_path. تحقق من وجود اسم الخادم المحدد في base_url ضمن شهادة الخادم.

في Windows، افتح خصائص client.key ثم الأمان ثم خيارات متقدمة. بمساعدة الدعم عند الحاجة، احصر الوصول في حساب Windows الذي تستخدمه؛ يمكن إبقاء SYSTEM والمسؤولين المحليين. أزل صلاحيات المستخدمين والمجموعات الآخرين، بما فيها الصلاحيات الموروثة الواسعة. يرفض HelixFlow مفتاحًا غير محمي بما يكفي.

chmod 700 "$HELIXFLOW_CONFIG_DIR/certs"
chmod 600 "$HELIXFLOW_CONFIG_DIR/certs/client.key"

base_url: https://st01.example.test:8444
env_class: test
tls:
  mode: ca
  ca_path: 'C:/Users/you/HelixFlow/config/certs/server-ca.pem'
client_auth:
  mode: certificate
  format: pkcs12
  cert_path: ../certs/client.p12
  passphrase_entry: p12-passphrase

keyring set helixflow/validation p12-passphrase

credentials:
  source: env

4. التحقق من الاتصال دون تعديل ST

اربط المساعد في الخطوة التالية، ثم استدعِ server_info للتحقق من MCP المحلي. لا يختبر هذا الاستدعاء ST. اطلب بعده سرد الحسابات باستخدام ملف validation: تؤكد استجابة دون خطأ الاتصال بـ ST وصلاحية القراءة لهذا الاستدعاء. قد تعني قائمة فارغة فقط عدم وجود حسابات ظاهرة. 4. ربط مساعدك · 5. تنفيذ أول قراءة

4. ربط مساعدك

تستخدم الأمثلة الثلاثة الملف التنفيذي والترخيص والمجلدات نفسها. نفّذ الأوامر في جلسة هذا الدليل. إذا كان securetransport موجودًا بالفعل، حدّث إعداده الحالي في عميلك.

Claude Desktop

استبدل «you» باسم حسابك في جميع المسارات. ادمج هذا الإعداد مع خوادمك الأخرى في %APPDATA%\Claude\claude_desktop_config.json

لا ترث عملية Desktop التي تبدأ خارج جلسة PowerShell بيانات اعتمادها. استخدم طريقة تشغيل موثّقة من تلك الجلسة أو استخدم Claude Code.

في Linux استخدم Claude Code أو عميل MCP آخر يدعم stdio.

Claude Code

بعد تثبيت Claude Code، سجّل الخادم لحساب المستخدم:

Codex

بعد تثبيت واجهة Codex الطرفية، سجّل الخادم نفسه. سيستخدم Codex مجلد الترخيص المشترك بشكل صريح:

تحقق فقط من العميل الذي تستخدمه، ثم أغلق Claude أو Codex بالكامل وأعد تشغيله لتحميل الإعدادات الجديدة. اطلب من المساعد استدعاء server_info وتحقق من الإصدار المعروض.

احتفظ ببيانات اعتماد SecureTransport في مخزن مفاتيح النظام أو بيئة العملية المدعومة. لا تلصقها أبدًا في محادثة.

5. تنفيذ أول قراءة

ابدأ بـ server_info للتحقق من اتصال MCP دون الاتصال بـ SecureTransport. ثم اطلب قراءة باستخدام الاسم الدقيق لملف الاختبار.

يشير ملف validation إلى validation.yaml. تحقّق من هدفه قبل أول استدعاء. قد تستخدم القراءات ذاكرة مؤقتة لمدة ثلاثين ثانية افتراضيًا.

6. إعداد تغيير

تتبع تغييرات التدفق دورة صريحة. هذه الأسماء أدوات MCP وليست أوامر طرفية.

1. تحقّق من مستند التدفق باستخدام flow_validate.
2. عاينه باستخدام flow_plan وراجع مرجع الخطة الناتج.
3. أكّد قبل أن يستخدم flow_apply المستند ومرجع الخطة نفسيهما.

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

تُدار الاشتراكات (الخيارات وسمات التدفق والاشتراك دون إعداد نقل) عبر مستندات التدفق. أما المسارات، فيمكن تحديث القالب الذي ينفّذ مسارات أخرى تحديثًا موجّهًا: وصفه، أو حالة إحدى خطواته، أو إضافة خطوة تنفيذ مسار واحدة في آخر القائمة، ويُرفض حذف مثل هذه الخطوة. وأصبح التصدير الكامل يُعاد تحميله مطابقًا للأصل.

المجلد flows المحدد بواسطة HELIXFLOW_FLOW_DIR هو الجذر المسموح لمستندات flow_path والشهادات المستوردة عبر تدفق. تبقى شهادة اتصال client_auth في مجلد certs الموضّح في الخطوة 3.

7. حل المشكلات

لا يجد العميل الملف التنفيذي

تحقّق من المسار المطلق واسم الملف الخاص بالمعمارية وإذن التنفيذ في macOS أو Linux. شغّل version مجددًا في الطرفية.

لم يُعثر على ملف تعريف

تحقّق من HELIXFLOW_CONFIG_DIR ومجلد profiles تحته. يطابق الاسم المطلوب اسم ملف YAML دون الامتداد.

فشل اتصال TLS

عند «unknown authority»، تحقق من server-ca.pem وtls.ca_path. إذا كان اسم الخادم خاطئًا، صحّح base_url أو الشهادة بدل استخدام insecure. عند «certificate required» أو «bad certificate»، اطلب فحص شهادة العميل وسلسلتها وجهات التصديق المقبولة في ST.

رُفضت المصادقة

يعني الخطأ 401 أن ST رفض الهوية، وقد يشير 403 إلى نقص الصلاحيات. مع كلمة المرور، تحقق من بيانات الدخول وقفل الحساب والمخزن أو البيئة التي يتلقاها MCP. مع الشهادة، تحقق من Certificate DN والجهة الموثوقة وإعداد optional وإعادة تشغيل الإدارة. تأكد إن كان ST يتطلب الوضع dual.

رُفض ملف الشهادة أو المفتاح

تحقق من المسارات بالنسبة إلى مجلد التعريف وتواريخ الصلاحية وتطابق الشهادة والمفتاح والصلاحيات. مفتاح PEM المشفّر المنفرد غير مدعوم؛ استخدم P12 مع كلمة مروره في المخزن. مع P12، تحقق أيضًا من المدخل helixflow/validation → p12-passphrase.

رُفض الترخيص

نفّذ license status في الجلسة المعدّة أعلاه. تحقق من صيغة HFL1 والجهاز وتاريخ الانتهاء. يجب أن تكون قيمة HELIXFLOW_LICENSE_DIR متطابقة في الطرفية وعميل MCP. يتطلب ترخيص JSON القديم إعادة إصدار.