cupcake

# كب كيك

<p align="left">
  <picture>
    <source srcset="docs/docs/assets/cupcake-dark.png" media="(prefers-color-scheme: dark)">
    <img src="https://assets.kitploit.com/production/public/readmes/9383/83f62bdfaf3dc99bbad39428c2cf11efd35fea9adf67a584350d05a24a5e1f6e.png" alt="شعار كب كيك" width="180">
  </picture>
</p>

اجعل وكلاء الذكاء الاصطناعي يتبعون القواعد.

[![Docs](https://img.shields.io/badge/docs-Start%20here-8A2BE2)](https://cupcake.eqtylab.io/)
[![رخصة](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![اختبارات](https://img.shields.io/github/actions/workflow/status/eqtylab/cupcake/ci.yml?branch=main&label=tests)](https://github.com/eqtylab/cupcake/actions/workflows/ci.yml)
[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://github.com/eqtylab/cupcake/actions/runs/19737865145/job/56558251812)

طبقة **فرض السياسات** لوكلاء الذكاء الاصطناعي؛ مما يحقق أداءً وأمانًا أفضل **دون استهلاك سياق النموذج**.

- **اتباع قواعد حتمي** لوكلائك. [أمثلة تفاعلية](https://cupcake-policy-studio.vercel.app/example-policies/security/symlink-detection?harness=claude-code&format=rego)
- **أداء أفضل** بنقل القواعد خارج السياق إلى سياسة كرمز.
- **تشغيل التنبيهات** ووضع الوكلاء _السيئين_ في وضع الانتظار عند تكرار مخالفتهم للقواعد.

يعترض كب كيك أحداث الوكيل ويقيمها وفقًا لـ **قواعد محددة من المستخدم** مكتوبة بلغة **[Open Policy Agent (OPA)](https://www.openpolicyagent.org/) [Rego](https://www.openpolicyagent.org/docs/policy-language).** يمكن حظر إجراءات الوكيل وتعديلها وتصحيحها تلقائيًا من خلال تقديم ملاحظات مفيدة للوكيل. تشمل الفوائد الإضافية الأتمتة التفاعلية للمهام التي لا تحتاج إلى الاعتماد على الوكيل لتنفيذها (مثل التدقيق اللغوي بعد تعديل ملف).

## التحديثات

**`2025-12-10`**: إصدار مفتوح المصدر رسمي. سيتم إنتاج خارطة الطريق في الربع الأول من 2026.

**`2025-04-04`**: قمنا بإنتاج [طلب الميزة](https://github.com/anthropics/claude-code/issues/712) لـ Claude Code Hooks. تتطلب المحاذاة في وقت التشغيل التكامل مع أدوات الوكيل، وتخلينا عن مراقبة سلوك الوكيل على مستوى نظام الملفات ونظام التشغيل (نموذج كب كيك الأولي).

## أدوات الوكيل المدعومة

يوفر كب كيك **تكاملات أصلية** خفيفة الوزن لوكلاء ترميز ذكاء اصطناعي متعددين:

| الأداة                                                                           | الحالة             | دليل التكامل                                                            |
| -------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------- |
| **[Claude Code](https://claude.ai/code)**                                         | ✅ مدعوم بالكامل   | [دليل الإعداد](https://cupcake.eqtylab.io/getting-started/usage/claude-code/) |
| **[Cursor](https://cursor.com)**                                                  | ✅ مدعوم بالكامل   | [دليل الإعداد](https://cupcake.eqtylab.io/getting-started/usage/cursor/)      |
| **[Factory AI](https://docs.factory.ai/welcome)**                                 | ✅ مدعوم بالكامل   | [دليل الإعداد](https://cupcake.eqtylab.io/getting-started/usage/factory-ai/)  |
| **[OpenCode](https://opencode.ai)**                                               | ✅ مدعوم بالكامل   | [دليل الإعداد](https://cupcake.eqtylab.io/getting-started/usage/opencode/)    |
| **[AMP](https://ampcode.com)**                                                    | قريبًا             | [في انتظار الإصدار](https://ampcode.com/manual?internal#hooks)                |
| **[Gemini CLI](https://docs.cloud.google.com/gemini/docs/codeassist/gemini-cli)** | قريبًا             | [في انتظار الإصدار](https://github.com/google-gemini/gemini-cli/issues/2779)  |

تستخدم كل أداة تنسيقات أحداث أصلية. على غرار terraform، يتم فصل السياسات حسب الأداة (`policies/claude/`, `policies/cursor/`, `policies/factory/`, `policies/opencode/`) لضمان الوضوح والوصول الكامل إلى الإمكانيات الخاصة بالأداة. إذا كانت أداة معينة غير مدعومة، فهذا لأنه لا توجد وسيلة للتكامل في وقت التشغيل.

#### ربطات اللغات

يمكن تضمين كب كيك في تطبيقات وكلاء JavaScript من خلال ربطات أصلية. يتيح ذلك التكامل مع أطر عمل الوكيل المستندة إلى الويب مثل LangChain و Google ADK و NVIDIA NIM و Vercel AI SDK والمزيد.

| اللغة                                                                        | الربطة        |
| ----------------------------------------------------------------------------- | -------------- |
| <img src="https://raw.githubusercontent.com/eqtylab/cupcake/HEAD/docs/docs/assets/typescript.svg" width="24" height="24"> TypeScript | `./cupcake-ts` |

## كيف يعمل

يعمل كب كيك كطبقة فرض بين وكلاء الترميز وبيئة وقت التشغيل الخاصة بهم **عبر هوكز** مباشرة في مسار إجراء الوكيل.

<img src="https://assets.kitploit.com/production/public/readmes/9383/9933b2ee724061c3ca34b04027b9ded4872292a22aaa456def9effe6072e8267.png" alt="معمارية أمن هوكز وكيل كب كيك" width="600"/>

`وكيل → (إجراء مقترح) → كب كيك → (قرار السياسة) → بيئة الوكيل`

1. **الاعتراض**: يستعد الوكيل لتنفيذ إجراء/استدعاء أداة (مثل `git push`, `fs_write`).
2. **الإثراء**: يجمع كب كيك **إشارات** في الوقت الفعلي—حقائق من البيئة مثل فرع Git الحالي، حالة CI، أو بيانات وصفية لقاعدة البيانات.
3. **التقييم**: يتم تغليف الإجراء والإشارات في إدخال JSON وتقييمها مقابل سياسات Wasm الخاصة بك في ميلي ثانية.

### التقييم الحتمي وغير الحتمي

يدعم كب كيك نموذجي تقييم:

1. **السياسات الحتمية**: تُكتب السياسات بلغة **OPA/Rego** ويتم **ترجمتها إلى WebAssembly (Wasm)** لتقييم سريع ومعزول. دليل [كتابة السياسات](https://cupcake.eqtylab.io/reference/policies/custom/) لتفاصيل التنفيذ.
2. **LLM كقاضي**: للإشراف الأبسط والأكثر تقدمًا على قواعدك، يمكن لـ كب كيك التدخل عبر LLM ثانوي أو وكيل لتقييم كيفية متابعة الإجراء. دليل [Cupcake Watchdog](https://cupcake.eqtylab.io/watchdog/getting-started/) لتفاصيل التنفيذ.

### القرارات والتغذية الراجعة

بناءً على التقييم، يعيد كب كيك أحد القرارات الخمسة إلى بيئة الوكيل، إلى جانب رسالة قابلة للقراءة البشرية:

- **السماح**: يستمر الإجراء. اختياريًا، يمكن لكب كيك حقن **سياق** (مثل "تذكر: أنت على الفرع الرئيسي") لتوجيه السلوك اللاحق دون حظر. _ملاحظة: حقن السياق مدعوم في Claude Code و Factory AI، وليس في Cursor._
- **التعديل**: يستمر الإجراء مع إدخال محوَّل. يمكن للسياسات تعقيم الأوامر، إضافة علامات أمان، أو فرض اصطلاحات قبل التنفيذ. _ملاحظة: مدعوم في Claude Code و Factory AI فقط._
- **الحظر**: يتم إيقاف الإجراء. يرسل كب كيك **ملاحظات** تشرح _لماذا_ تم حظره (مثل "يجب أن تنجح الاختبارات قبل الدفع")، مما يسمح للوكيل بتصحيح نفسه.
- **التحذير**: يستمر الإجراء، ولكن يتم تسجيل تحذير أو عرضه.
- **طلب المراجعة**: يتوقف الإجراء حتى يوافق عليه إنسان.

## لماذا كب كيك؟

الوكلاء الحديثة قوية ولكنها غير متناسقة في اتباع القواعد التشغيلية والأمنية، خاصة مع نمو السياق. يحول كب كيك القواعد التي تحتفظ بها بالفعل (مثل `CLAUDE.md`, `AGENT.md`, `.cursor/rules`) إلى **حواجز قابلة للفرض** تعمل قبل تنفيذ الإجراءات.

- **دعم متعدد الأدوات** مع تكاملات من الدرجة الأولى لـ **Claude Code** و **Cursor** و **Factory AI** و **OpenCode**.
- **الحوكمة كرمز** باستخدام OPA/Rego المترجمة إلى WebAssembly لتقييم سريع ومعزول.
- **ضوابط جاهزة للمؤسسات**: السماح/الرفض/المراجعة، مسارات **تدقيق محسَّنة** لمراكز عمليات أمن الذكاء الاصطناعي، وتحذيرات استباقية.

### القدرات الأساسية

- **التحكم الدقيق في الأدوات**: منع أدوات أو وسائط معينة (مثل حظر `rm -rf /`).
- **دعم MCP**: حوكمة أصلية لأدوات بروتوكول سياق النموذج (مثل `mcp__memory__*`, `mcp__github__*`).
- **LLM كقاضي**: استخدام LLM ثانوي أو وكيل لتقييم الإجراءات لإشراف أكثر ديناميكية.
- **مكتبات الحواجز**: تكاملات من الدرجة الأولى مع `NeMo` و `Invariant` لفحوص المحتوى والسلامة.
- **المراقبة**: تُنشئ جميع المدخلات والإشارات والقرارات سجلات منظمة وآثار تقييم لتصحيح الأخطاء.

## التثبيت والتطوير باستخدام Nix

إذا كنت تستخدم [nix](https://nixos.org/)، يمكنك تثبيت وتشغيل كب كيك باستخدام الفليك المقدم:

### تثبيت واجهة سطر الأوامر كب كيك باستخدام Nix

```bash
# Install directly from GitHub
nix profile install github:eqtylab/cupcake#cupcake-cli

# Or run without installing
nix run github:eqtylab/cupcake#cupcake-cli -- --help
```

### تثبيت واجهة سطر الأوامر كب كيك على NixOS

أضف ما يلي إلى ملف `flake.nix` الخاص بك:
```nix
inputs.cupcake.url = "github:eqtylab/cupcake";
```

ثم الحزمة التالية إلى `environment.systemPackages` أو `home.packages`:
```nix
inputs.cupcake.packages.${system}.cupcake-cli
```

### واجهة التطوير

للتطوير، يمكنك أيضًا استخدام واجهة التطوير المقدمة التي تتضمن سلسلة أدوات Rust و just والاعتماديات الأخرى:

```bash
# Enter the development shell
nix develop
```

## الأسئلة الشائعة

**هل يستهلك كب كيك رموز المطالبة/السياق؟**
لا. تعمل السياسات خارج النموذج وتعيد قرارات منظمة.

**هل كب كيك مرتبط بنموذج معين؟**
لا. يدعم كب كيك وكلاء ترميز متعددين للذكاء الاصطناعي مع تكاملات خاصة بالأدوات.

**ما سرعة التقييم؟**
أقل من ملي ثانية للسياسات المخزنة مؤقتًا في الإعدادات النموذجية.

## المساهمة

نرحب بالمساهمات! راجع [CONTRIBUTING.md](https://github.com/eqtylab/cupcake/blob/main/CONTRIBUTING.md) للإرشادات.

## الترخيص

[Apache 2.0](https://github.com/eqtylab/cupcake/blob/main/LICENSE)

---

تم تطوير كب كيك بواسطة [EQTYLab](https://eqtylab.io/)، مع دعم أبحاث سلامة الوكيل من [Trail of Bits](https://www.trailofbits.com/).

[تابع على X](https://x.com/CupcakeSecures) للحصول على تحديثات منتظمة.