GitHub Copilot Enterprise لمطوّري أوراكل: PL/SQL وAPEX وSQLcl

يعرف GitHub Copilot الكثير عن SQL عمومًا، لكنه لا يعرف قواعدك أنت: متغيرات الربط فقط، ولا WHEN OTHERS THEN NULL، ومعرّفات Static ID ثابتة في APEX، وSQLcl أداةً للنشر. يشرح هذا الدليل كيف تكتب هذه القواعد مرة واحدة ليطبّقها Copilot في كل محادثة، وكيف تحتفظ بأوامر قابلة لإعادة الاستخدام لإعادة هيكلة PL/SQL وتعديلات APEXlang، وكيف تسمح لوضع الوكيل في Copilot بالاستعلام من Oracle AI Database 26ai Free محلية عبر خادم SQLcl MCP.

يستخدم جانب القاعدة البيئةَ نفسها من دليل تثبيت Oracle AI Database 26ai وAPEX عبر Docker: المضيف localhost والمنفذ 1521 والخدمة FREEPDB1. أما سير عمل APEXlang فهو نفسه في دليل برمجة Oracle APEX مع APEXlang.

اختر خطة Copilot المناسبة

خطط GitHub الحالية للأفراد هي Copilot Free وCopilot Student وCopilot Pro وCopilot Pro+ وCopilot Max، وللمؤسسات Copilot Business وCopilot Enterprise. التعليمات المخصّصة وملفات الأوامر ووضع الوكيل وخوادم MCP وCopilot CLI متاحة في الخطط الفردية أيضًا. أما مراجعة طلبات الدمج عبر Copilot فغير مشمولة في Copilot Free (تتيح Free فقط "Review selection" داخل VS Code).

ما تضيفه خطط المؤسسات هو التحكم. يوزّع المسؤولون المقاعد، ويضبطون السياسات (مثل السماح بخوادم MCP أو بـ Copilot CLI)، ويهيّئون استبعاد المحتوى. وعند كتابة هذا الدليل تذكر GitHub أن سعر Copilot Business هو 19 دولارًا وCopilot Enterprise هو 39 دولارًا لكل مقعد شهريًا؛ راجع صفحة الخطط لدى GitHub لمعرفة السعر الحالي ورصيد الاستخدام.

اكتب قواعد أوراكل في copilot-instructions.md

أنشئ الملف .github/copilot-instructions.md في جذر المستودع. يضيفه Copilot إلى كل طلب محادثة يجري في سياق المستودع: إذ يقرؤه Copilot Chat في VS Code وCopilot CLI ومراجعة الشيفرة عبر Copilot والوكيل السحابي. اكتب قواعد قصيرة يمكن التحقق منها، لا مقالات. هذه نقطة بداية لمستودع فيه حزم PL/SQL وتطبيق APEXlang:

# Copilot instructions for this repository

This repository holds Oracle PL/SQL packages and an Oracle APEX app exported as APEXlang.

## Stack
- Oracle AI Database 26ai. Local development uses the Free container, service FREEPDB1.
- PL/SQL packages live in db/packages as .pks (spec) and .pkb (body) files.
- The APEX app lives in apex/my-app as APEXlang .apx files.
- SQLcl is the only deploy tool. Never suggest running scripts in SQL Developer by hand.

## PL/SQL rules
- Use bind variables. Never build SQL by concatenating values into a string.
- If dynamic SQL is unavoidable, use EXECUTE IMMEDIATE ... USING binds and
  DBMS_ASSERT for object names.
- Never write WHEN OTHERS THEN NULL. Log the error and re-raise with RAISE.
- Do not COMMIT inside reusable package procedures; the caller owns the transaction.
- Keep public signatures in the .pks stable. Add new procedures instead of changing
  existing parameters.
- Prefer set-based SQL over row-by-row loops. Use BULK COLLECT with LIMIT for large sets.

## APEXlang rules
- Never rename existing components and never change their Static IDs.
- Refer to page items by name (for example :P12_STATUS) and to components by Static ID.
- After editing .apx files, tell me to run: apex validate -input apex/my-app

## Deploy
- Database objects: SQLcl scripts under db/, run with sql -S.
- APEX app: apex validate, then apex import -input apex/my-app, run in SQLcl.
- Never connect to production. Only the saved SQLcl connection for development may be used.

قواعد تخص بعض الملفات فقط

للقواعد التي تهمّ مجلدات بعينها، أضف ملفات خاصة بالمسارات داخل .github/instructions/. يجب أن ينتهي اسم الملف بـ .instructions.md، ويأخذ الحقل applyTo في الترويسة أنماطَ مسارات مفصولة بفواصل. احفظ هذا الملف باسم .github/instructions/plsql.instructions.md:

---
applyTo: "db/**/*.pks,db/**/*.pkb,db/**/*.sql"
---
Every procedure that changes data must have an exception handler that logs the
error with the package name and re-raises it. Use %TYPE and %ROWTYPE for
variables that hold column values.

يقرأ Copilot أيضًا ملفات AGENTS.md بوصفها تعليمات للوكيل. فإن كان فريقك يحتفظ بواحد منها، فسيستخدمه Copilot Chat في VS Code وCopilot CLI إلى جانب copilot-instructions.md، فلا داعي لتكرار القواعد.

احفظ الأوامر المتكررة في ملفات الأوامر

ملفات الأوامر (prompt files) أوامر محفوظة تشغّلها كأوامر مائلة. ضعها في .github/prompts/ بالامتداد .prompt.md. احفظ الملف أدناه باسم .github/prompts/refactor-plsql.prompt.md وشغّله من Copilot Chat بكتابة /refactor-plsql. يحوّل السطر agent: 'agent' المحادثةَ إلى وضع الوكيل عند تشغيل الأمر. وتصنّف GitHub ملفات الأوامر على أنها معاينة عامة، مدعومة في VS Code وVisual Studio وبيئات JetBrains.

---
agent: 'agent'
description: 'Refactor one PL/SQL package without changing its public API'
---
Refactor the PL/SQL package in the file I attach.

Rules:
- Keep every public signature in the .pks exactly as it is.
- Replace string-concatenated SQL with bind variables.
- Replace row-by-row loops with set-based SQL where the result is identical.
- Remove WHEN OTHERS THEN NULL; log and re-raise instead.
- Do not add COMMIT or ROLLBACK.

First list the changes you plan to make and wait for my confirmation.
Then edit the .pkb file and explain each change in one line.

أنماط أوامر تنجح مع شيفرة أوراكل

سواء استخدمت ملف أوامر أو كتبت الأمر بنفسك، فالنمط واحد: سمِّ الملف بدقة، واذكر ما يجب ألا يتغيّر، واطلب خطة قبل التعديل. مثال لإعادة هيكلة PL/SQL:

Refactor #file:db/packages/order_api.pkb.
Keep the spec in order_api.pks unchanged.
Replace the concatenated SQL in get_orders with bind variables,
and turn the cursor loop in close_old_orders into one UPDATE.
Show me the plan first, then make the edit.

ولتعديل APEXlang، أشِر إلى مجلد التصدير واحمِ المعرّفات. يشير APEXlang إلى المكوّنات بمعرّف Static ID وإلى عناصر الصفحة بأسمائها، فإعادة تسمية مكوّن تكسر الإشارات إليه في أماكن أخرى من التطبيق:

In apex/my-app/pages, add a "Status" select list to page 12
with the static values Open, In Progress and Closed, default Open.
Do not rename existing components or change any Static ID.
When you are done, list the .apx files you changed.

ثم راجع الفروقات في Git، وشغّل apex validate، واستورد التطبيق إلى مساحة عمل تطوير عبر SQLcl، تمامًا كما تفعل مع أي وكيل آخر.

اربط وضع الوكيل بأوراكل عبر خادم SQLcl MCP

يتضمّن SQLcl خادم MCP. يشغّله عميل MCP مثل Copilot عبر sql -mcp. وفي SQLcl 26.3 يوفّر أدوات مثل list-connections وconnect وdisconnect وrun-sql وrun-sqlcl وschema-information، إضافةً إلى أدوات أحدث (context_retrieve وannotation_generate وskill_sync وrequest_status). وتذكر وثائق أوراكل SQLcl 25.2.0 أو أحدث وبيئة تشغيل Java بالإصدار 17 أو 21.

لا يرى الخادم إلا الاتصالات المحفوظة في مخزن اتصالات SQLcl (داخل ~/.dbtools)، وتحديدًا المحفوظة مع كلمة مرورها. احفظ اتصالًا بمخطط تطوير في FREEPDB1 المحلية. استخدم المخطط الذي تطوّر فيه، ولا تستخدم SYS أو SYSTEM أبدًا:

sql /nolog
SQL> conn -save ora26ai_dev -savepwd app_dev/<password>@//localhost:1521/FREEPDB1
SQL> exit

بعد ذلك أنشئ الملف .vscode/mcp.json في المستودع. استبدل /path/to/sqlcl بالمسار الكامل لمجلد SQLcl لديك (على Windows مثلًا C:/tools/sqlcl/bin/sql.exe):

{
  "servers": {
    "sqlcl": {
      "command": "/path/to/sqlcl/bin/sql",
      "args": ["-mcp"]
    }
  }
}

احفظ الملف واضغط Start فوق تعريف الخادم. وفي Copilot Chat افتح قائمة الوكلاء أسفل نافذة المحادثة واختر Agent. ثم اسأل سؤالًا يحتاج إلى القاعدة:

Use the sqlcl tools. Connect to ora26ai_dev, list the invalid objects
in my schema, and show me the compile errors for each one.
Do not change anything in the database.

يمرّ Copilot عبر الأدوات list-connections وconnect وrun-sql. اقرأ كل استدعاء أداة وما يحمله من SQL في المحادثة قبل أن تسمح له بالمتابعة. وإن كنت تستخدم إضافة SQL Developer for VS Code من أوراكل، فوثائق أوراكل تذكر أنها تسجّل خادم SQLcl MCP لـ Copilot تلقائيًا، فلا تحتاج إلا إلى اتصال محفوظ.

استخدم Copilot CLI في الطرفية

يجلب Copilot CLI الوكيلَ نفسه إلى الطرفية. ثبّته عبر npm (يتطلب Node.js 22 أو أحدث) أو عبر WinGet. وعلى Windows يحتاج إلى PowerShell 6 أو أحدث:

npm install -g @github/copilot
# أو على Windows:
winget install GitHub.Copilot

شغّل copilot داخل المستودع وسجّل الدخول عبر /login في المرة الأولى. يقرأ CLI ملف copilot-instructions.md والتعليمات الخاصة بالمسارات وAGENTS.md. أضف إليه خادم SQLcl MCP عبر copilot mcp add (يُحفظ في ~/.copilot/mcp-config.json)، واستخدم --deny-tool لحظر الأوامر التي لا يجوز للوكيل تشغيلها أبدًا:

copilot mcp add sqlcl -- /path/to/sqlcl/bin/sql -mcp
copilot --deny-tool='shell(rm)' --deny-tool='shell(git push)'

وكيل مخصّص لمراجعة PL/SQL

الوكلاء المخصّصون ملفات Markdown فيها name وdescription في الترويسة والتعليمات في المتن. احفظ هذا الملف باسم .github/agents/plsql-reviewer.agent.md؛ سيظهر في Copilot CLI ضمن /agent، ويمكن للوكيل السحابي وVS Code استخدامه أيضًا:

---
name: plsql-reviewer
description: Reviews PL/SQL changes for bind variables, exception handling and transaction control without editing files
---
You review PL/SQL code. Do not edit files.
For each finding, give the file, the line, the rule it breaks
(from .github/copilot-instructions.md) and a corrected snippet.

وإن كنت تستخدم حزمة المهارات من Harby، فملفات SKILL.md فيها تعمل في Copilot بوصفها مهارات للوكيل: ضع كل مهارة في مجلد خاص بها داخل .github/skills/ (مثلًا .github/skills/plsql/SKILL.md). ويحمّل وضع الوكيل في VS Code وCopilot CLI ومراجعة الشيفرة والوكيل السحابي المهارةَ حين تكون ذات صلة بالمهمة.

دع Copilot يراجع طلبات الدمج

عيّن Copilot مراجعًا لطلب الدمج (pull request)، أو فعّل المراجعات التلقائية من إعداداتك أو عبر قواعد المستودع (ruleset). تقرأ مراجعة Copilot الملف .github/copilot-instructions.md وملفات .instructions.md من فرع المصدر في طلب الدمج (head branch)، فتتحوّل قواعد PL/SQL لديك إلى تعليقات مراجعة. ولا تُحتسب مراجعاته افتراضيًا ضمن الموافقات المطلوبة، فيبقى إنسان هو من يوافق على الدمج.

ضوابط المؤسسات: السياسات والبيانات واستبعاد المحتوى

• سياسة MCP: لمستخدمي Copilot Business وCopilot Enterprise لا يعمل MCP إلا إذا كانت سياسة MCP servers in Copilot مفعّلة. كانت معطّلة افتراضيًا، لكن GitHub تفعّل الميزات غير المضبوطة افتراضيًا ابتداءً من 22 أكتوبر 2026، فالأمر يعتمد على إعدادات المسؤول. إن لم يعمل خادم SQLcl فاسأل مالك المؤسسة أو المنشأة.
• Copilot CLI ووضع الوكيل يمكن إيقافهما أيضًا عبر السياسات. إن لم ترَ Agent في القائمة فاسأل المسؤول.
• استبعاد المحتوى (في Copilot Business وCopilot Enterprise) يُضبط على مستوى المستودع أو المؤسسة أو المنشأة من Copilot ← Content exclusion، بأنماط مسارات مثل "/db/secrets/**".
• تعليمات المؤسسة التي يضعها المالك تنطبق على Copilot Chat ومراجعة الشيفرة والوكيل السحابي في GitHub.com، لا على VS Code أو Copilot CLI. أبقِ قواعد المشروع داخل المستودع.

اختبر فهمك