من تجربة جافة إلى تقرير مطابقة

مسار أول واحد موصى به، ثم حزم SDK والواجهة والارتباطات والتقييمات. كل ما يلي يعمل اليوم؛ وما لم يوجد بعد يقول ذلك. الوثائق التقنية بالإنجليزية.

البداية السريعة مرجع النواة 0.2 واجهة النواة (OpenAPI)

البداية السريعة: خمس دقائق، بلا عتاد

احصل على الأدوات.

git clone https://github.com/amado2k5/cookwala && cd cookwala
pip install -e sdk/python            # المكتبة القياسية فقط؛ أضف [full] للتحقق من المخططات والتوقيعات

احسب بصمة وصفة. يطبخ المنفّذ هذه المراجعة بالضبط ويرفض عند عدم التطابق.
```
cookwala hash examples/koshari.cookwala.json
```
sha256:f7fc3745af514…
هل يستطيع هذا الجهاز طهيها؟ لا يُنفَّذ شيء؛ تأتي الإجابة قبل التسخين.
```
cookwala dryrun examples/koshari.cookwala.json --device examples/capabilities/robot-arm.json
```
{"state": "refused", "refusal": {"reason": "missing_capability", "node": "n1", "detail": "device cannot perform cw.op.boil and no person is present to do it"}}
```
cookwala dryrun examples/koshari.cookwala.json --device examples/capabilities/robot-arm.json --human-present
```
{"state": "accepted", "plan": [{"node": "n1", "op": "cw.op.boil", "by": "human", "verifiedBy": "human"}, …]}
افحص أثر حرارة مقابل نطاق آمن. 99 درجة غليان لا نار هادئة.
```
python -c "import cookwala as cw; print(cw.check_envelope('cw.op.simmer', [{'t':0,'tempC':60},{'t':60,'tempC':94},{'t':90,'tempC':99}]))"
```
{'envelopeOk': False, 'targetOk': None, 'reason': 'left_envelope'}
شغّل متّجهات المطابقة واكتب تقريرًا. التقرير هو الوثيقة وراء أي ادعاء.
```
cookwala conformance --report report.json
```
conformance: 137/137 passed (7 core suites, 5 profile suites) report -> report.json
شغّل المحور المرجعي واطبخ عبر واجهة النواة.
```
cookwala hub --port 7878
curl -s localhost:7878/v1/safety-limits | head
```
ثم POST /v1/executions كما في ملف الموزّع: مرفوض بلا شخص حاضر، مقبول معه، وstop يعمل دائمًا، والسجل بلا بيانات شخصية.

حزم SDK والأدوات

عميل محور واحد بالعمليات الـ25 نفسها بـ13 لغة برمجة (Python وTypeScript وJavaScript وGo وRust وJava وKotlin وC# وSwift وC++ وRuby وPHP وcurl)، و101 سيناريو بالكود بكل منها: حزمة التطوير والسيناريوهات.

حزمة بايثون وسطر الأوامر

pip install -e sdk/python. hash وverify وdryrun وenvelope وconvert وsms وconstraints وvalidate وconformance وhumanitarian وexport وinit وhub وmcp. المكتبة القياسية فقط.

الآن · تثبيت قابل للتحرير؛ عجلة PyPI لاحقًا ←

أنواع TypeScript

أنواع لكل المخططات الـ24، مولَّدة ومفحوصة الأنواع؛ والتجربة الجافة للمتصفح كوحدة. فضاء أسماء لكل مخطط.

الآن · حزمة مصدر؛ npm لاحقًا ←

خادم MCP

أربع عشرة أداة للقراءة فقط لأي عميل MCP، تُشغَّل بـ npx -y @cookwala/mcp: بحث، جلب، تجربة جافة، شرح خطوة، فحص مظروف، فحص تفويض، تحليل رسالة وغيرها. لا خادم لاستضافته. لا يطبخ أبدًا.

الآن ←

المحور المرجعي

واجهة النواة بجهاز محاكى: تجربة جافة قبل التسخين، وآلة حالات على ساعة، واحترام المظاريف، والإيقاف يعمل دائمًا. ملف Dockerfile مرفق.

الآن ←

واجهات ROS 2

cookwala_msgs: إجراءا ExecuteRecipe وExecuteNode؛ الإلغاء إيقاف آمن؛ لا يستطيع أي حقل هدف رفع حد.

الآن · عقدة الجسر مساهمة أولى جيدة ←

مصدّرا LeRobot وOpenTelemetry

تصبح سجلات التنفيذ مهام LeRobotDataset v3 وآثار OTLP، بموافقة الأسرة فقط.

الآن ←

جديد: أمثلة برمجية لكل دور

عملاء، ووكيل تخطيط يعمل بتفويض، ومنسّق، وبوابات سلامة، واستعادة، وتقارير، بلغات بايثون وجافاسكربت وجافا وC#. شغّل العرض دون تثبيت، ثم خذ الشيفرة نفسها إلى pip وnpm وMaven وGradle وNuGet وHomebrew وChocolatey وScoop وapt وRPM وpacman وconda وsnap، أو إلى حاوية أو Helm أو Artifactory، أو كدالة على Azure أو AWS أو Google Cloud أو OpenShift.

الأمثلة والحزم شغّل العرض

مبنية ومختبرة في التكامل المستمر؛ تصل إلى السجلات مع أول إصدار موسوم.

واجهة النواة

واجهة واحدة ينفّذها كل منفّذ: POST /v1/executions، والحالة، والإيقاف، والاستئناف، والسجل، وحدود السلامة، والقدرات؛ وتضيف الكتالوجات السحوبات والحوادث. مفاتيح تكرار على كل POST، وIf-Match على التغييرات، والرفض إجابة عادية، والإيقاف لا يُرفض أبدًا لأسباب الصلاحية.

core.openapi.yaml · registry.openapi.yaml · humanitarian.openapi.yaml · household.openapi.yaml (محلي) · كل المخططات في حزمة واحدة

الإصدارات

ترقيم دلالي لكل مواصفة؛ الإصدارات الفرعية إضافية؛ الإصدارات الكبرى تُعلن قبل 12 شهرًا؛ يخدم الفهرس كل إصدار كبير 3 سنوات. النواة 0.2.x؛ وتُرقَّم الملفات مستقلة وتعلن إصدار النواة الذي تحتاجه. الحوكمة

المطابقة

137 متّجه عام: البصمات (ومنها مثال RFC 8785)، والتوقيعات (ومنها مفتاح RFC 8032)، والإلغاء، والإفصاح الانتقائي، وسلاسل الأحداث ونقاط التحقق المشهودة، والوحدات، والمظاريف وسلالم الحساسات، وآلات الحالات، وسياسة الإفصاح، وقواعد السجل، وقواعد الرسائل، وسياسة الإشارات، والتحقق من الوسطاء.

الادعاء تقرير ConformanceReport موقّع: إعلان ذاتي ← تحقق مشغّل سجل ← اعتماد جهة مستقلة (لم تُشرك أي جهة بعد). تقارير لا شارات. المسار · المتّجهات

تقييمات الوكلاء

عشر حالات promptfoo تفحص اتباع الوكيل لقواعد النواة: النص غير الموثوق، والتفويضات والحدود، وحظر مسببات الحساسية، وحدود السلامة، والعمليات بلا مراقبة، والسحوبات، والرفض المفرط. أضف مزوّدين لمقارنة النماذج؛ وانشر مع معرّف النموذج والتاريخ وبصمة الإعداد. المعيار

ما يجاوره، وما ليس هو

لا شيء من هذه عقدٌ يتحقق منه الجهاز بين وصفة وجهاز. كوكوالا هو ذلك فقط، ويستعمل البقية حيث تناسب.

Schema.org Recipe	يصف وصفة لمحركات البحث: مقادير وأوقات وتغذية. لا عمليات ولا شروط إنهاء ولا شيء يتحقق منه جهاز. يمكن نشر وصفة كوكوالا بحقول Schema.org للاكتشاف.
LeRobot (Hugging Face)	صيغة مجموعات بيانات لما فعله الروبوت: مشاهدات وأفعال. لا تقول ما الوصفة ولا متى تكون خطوة غير آمنة. يصدّر كوكوالا سجلات التنفيذ بموافقة إليها.
HACCP	نظام إدارة للناس: مخاطر ونقاط تحكم حرجة وسجلات. يرمّز كوكوالا نقاط التحكم ليتحقق منها جهاز؛ ولا يحل محل خطة HACCP للمطبخ.
Matter (CSA)	تحكم بالأجهزة: ضبط فرن على حرارة، قراءة مسبار. يقول كوكوالا ما يُطلب من الفرن ومتى يُرفض؛ جدول الربط في bindings/matter.json.
ROS 2	طبقة وسيطة للروبوتات: كيف يتحرك الروبوت ويتخاطب داخليًا. يقع كوكوالا فوق الحركة ويقدّم واجهات ROS 2 لطبقة المهمة.

المفاهيم في جدول واحد

المصطلح	ما هو	ما ليس هو
مظروف العملية	المعنى الفيزيائي للعملية: الوسط، ونطاق الحرارة، والانتباه، والسماح بلا مراقبة، وسلّم الحساسات، والمخاطر	إعداد في وصفة؛ تضيّقه الوصفات ولا توسّعه أبدًا
سلّم الحساسات	طرق التحقق من خطوة، الأفضل أولًا: حساس، تقدير مسجّل، وقت، شخص. لا درجة متاحة يعني الرفض	تراجع إلى التخمين
حد السلامة	يُفرض على الجهاز؛ الأشد يفوز دائمًا؛ لا تستطيع رسالة رفعه	حقل في وصفة أو طلب
تفويض الوكيل	نطاقات وحدود ومزوّدون مسموحون وانتهاء وقائمة «أكّد قبل»، يوقّعه الموكِّل	موجّه نصي
القيد المشتق	الشيء الوحيد الآتي من المنزل الذي يتلقاه مزوّد («التسليم من 17:00 إلى 18:00، ملصق للفول السوداني»)	حقيقة منزلية
تقرير المطابقة	سجل موقّع بأي المتّجهات شُغّلت وبأي أداة ومتى وعلى ماذا	شارة

مشكلات شائعة

كل شيء مرفوض بسبب needs_human_present: التقطيع والتشويح والقلي لا تعمل بلا مراقبة؛ مرّر --human-present.
مرفوض بـ missing_sensor_no_fallback في القلي الغزير: للقلي الغزير درجة واحدة، ترمومتر زيت؛ هذا هو المعيار يعمل.
البصمة لا تتطابق: تستثني البصمة hash وsignature فقط؛ أي تغيير آخر مراجعة جديدة.
يقول التحقق إن درجة الحرارة خارج المظروف: يجب أن يقع هدف الوصفة داخل نطاق العملية؛ غيّر العملية أو الهدف.
بايثون لا يستورد cookwala: ثبّت من نسخة المستودع أو اضبط COOKWALA_ROOT.

ساهم

نفّذ واجهة النواة على جهاز أو موزّع وانشر تقريرًا؛ اكتب عقدة جسر ROS 2؛ أضف حالات هجوم إلى معيار الوكلاء؛ أضف متّجهات؛ اقترح RFC. كيف · المقترحات · GitHub

الوثائق أيضًا في /llms.txt وبصيغة ماركداون لكل صفحة لقرّاء الذكاء الاصطناعي.