دليل تكامل الوكيل وMCP في OT Flash
البروتوكول والتفويض وعقود الأدوات وتدفق الاستدعاء الكامل
بناء تطبيقات بيانات ومعرفة قابلة للتتبع باستخدام Remote MCP العام لـ OT Flash r56. يقدّم هذا الدليل OAuth، ورسائل البروتوكول، ومرجع معلمات لجميع الأدوات المعلنة، وقواعد الأدلة، والقدرات الشرطية، وإجراءات الاستعادة، إضافة إلى عميل قابل للتشغيل وأمثلة ببيانات اصطناعية.
مطوّرو الوكلاء ومهندسو التكامل والمسؤولون
تحتفظ العينات المرفقة بأسماء الحقول المعروضة بالصينية. لا تؤدي ترجمات لغة الواجهة ونصوص الشرح إلى تغيير أسماء الجداول الفعلية أو أسماء الأعمدة أو قيم التعداد أو أسماء الأدوات أو حقول البروتوكول.
جدول المحتويات
- 1نطاق تكامل الوكيل ومعايير الإنجاز
- 2الاتصال السريع واكتشاف القدرات
- 3اكتشاف OAuth والتسجيل والتفويض
- 4Scope وحدود الموارد والصلاحيات الآنية
- 5رسائل HTTP وMCP الحديثة
- 6توافق عملاء البروتوكول القديم
- 7اختيار الأداة الصحيحة وقناة الأدلة
- 8موارد الأنطولوجيا وأنواع المعرفات
- 9استعلام جداول Doris وعقد البنية
- 10أفضل 3 عبر أبعاد متعددة ومعالجة الاقتطاع
- 11استرجاع المعرفة: النص الأصلي الكامل وأهلية الدليل
- 12نماذج Search الأصلي وجلساته
- 13اصطلاحات اللغة والمنطقة
- 14التحليل المدمج والنتائج التفاعلية
- 15التقارير المرئية الدائمة وMCP Apps
- 16مسودات المُخرَجات والمعاينة والخطة والتطبيق
- 17عقد إنشاء مرشحات الأنطولوجيا ونشرها
- 18النموذج المنشور واستعلام المرشحات وإغلاق المراجع
- 19إسناد المهام إلى وكيل الأنطولوجيا
- 20MCP لمساحة عمل الأعمال
- 21إدخال معرفة الأعمال والأسئلة التي تنتظر التأكيد
- 22الاستجابة والأخطاء وإعادة المحاولة الآمنة
- 23أمن التكامل وحدود القدرات
- 24توصيلات المسؤول ومفاتيح التفعيل الشرطية
- 25عميل قابل للتشغيل وأمثلة استدعاء
- 26تضمين واجهة محادثة الأنطولوجيا
- 27قائمة قبول التكامل
- 28الموارد القياسية والصيانة
- 29مرجع معلمات الأدوات: الأساسيات وSearch الأصلي
- 30مرجع معلمات الأدوات: الجداول والرسم البياني والمعرفة
- 31مرجع معلمات الأدوات: التحليل والتقارير
- 32مرجع معلمات الأدوات: النمذجة والمهام الأصلية
- 33مرجع معلمات الأدوات: إدخال المعرفة والنطاق
- 34مرجع معلمات الأدوات: مساحة عمل الأعمال
نطاق تكامل الوكيل ومعايير الإنجاز
اختر مدخل التفويض، وأكمل الاستعلام أو جمع الأدلة أو الكتابة الخاضعة للتحكم استنادًا إلى إيصالات الخادم.
يوفّر OT Flash r56 قدرات البيانات والمعرفة ضمن نطاق الأنطولوجيا للوكلاء الخارجيين عبر Remote MCP، مع مدخل مستقل لمساحة عمل الأعمال. يجب على الوكيل أن يحدد العمل القابل للتنفيذ بناءً على tools/list الفعلية وinputSchema وscope الخاصة بـ OAuth وصلاحيات الموارد الحالية، ولا يجوز الاستنتاج من هذا الدليل الثابت أن بيئة نشر (deployment) معيّنة قد فعّلت جميع الميزات الاختيارية.
| المدخل | الغرض | الحدود |
|---|---|---|
| /mcp | الأنطولوجيا وجداول البيانات ومعرفة المستندات وSearch الأصلي، إضافة إلى التحليل والنمذجة المتاحَين شرطيًا | تقاطع صلاحيات المستخدم الحالي مع الموارد المفوَّضة في هذا التفويض |
| /mcp/business | اكتشاف أنظمة الأعمال والاستعلام وخطط الإجراءات والحالة والتنفيذ | تفويض مستقل لأنظمة الأعمال والعقود المنشورة |
| صفحة تضمين وكيل الأنطولوجيا | استخدام محادثة الأنطولوجيا داخل الواجهة البشرية | يعتمد على حالة تسجيل دخول حقيقية، وليس مدخل تبادل MCP Token بدون تسجيل دخول |
تصنيف القدرات
- القراءة الأساسية: الأنطولوجيا والموارد، وتحديد المواقع في الرسم البياني، واسترجاع المعرفة والنص الأصلي الكامل، وتفاصيل الجداول المفوَّضة، وDoris SQL.
- الإسناد المستقل: تتطلب الأداة dfc_search الـscope search:operate، وتواصل استخدام صلاحيات المستخدم والنموذج الأصلية.
- متاح شرطيًا: التحليل، والتقارير الدائمة، ومسودات المُخرَجات وتطبيقها، واستعلامات نماذج الأنطولوجيا، ومهام الوكيل المُسنَدة.
- قدرات غير متاحة: يقتصر dfc_etl الخاص بـ Flash على الإبلاغ عن capabilities دون توفير تنفيذ Heavy ETL. ولا يُعدّ AutoML ولا مدخل مساحة عمل FocusCode الداخلية جزءًا من Flash API العام الذي يغطيه هذا الدليل.
معايير الإنجاز
تتطلب قراءة الحقائق إيصال استعلام فعليًا قابلًا للاستخدام أو إيصال نص أصلي كامل؛ ويجب عند توليد مرشح التوضيح بأنه لم يُطبَّق بعد؛ ويتطلب النشر إيصال APPLIED حقيقيًا؛ ويجب في الإلغاء التمييز بين طلب الإلغاء وتأكيده. ولا يكفي نص الرد أو HTTP 200 أو قبول الأداة للطلب أو وصف النموذج بأنه "اكتمل"، كلٌّ بمفرده، لإثبات نجاح عملية الأعمال.
يُعدّ الملف المرفق reference/mcp-tool-catalog.json مرجعًا تصريحيًا لـ r56 للاستخدام دون اتصال، ويتضمن تعريفات الميزات الشرطية، وليس tools/list آنية لأي مستخدم. يشمل الكتالوج الكامل 28 أداة أساسية للأنطولوجيا، و4 امتدادات شرطية مرتبطة بوحدة التحكم، و8 أدوات على جانب الأعمال، ولا يعني ذلك أنها جميعًا متاحة افتراضيًا.
الاتصال السريع واكتشاف القدرات
ابدأ باسم النطاق الرسمي للمثيل، واكتشف الأدوات المتاحة فعليًا بأقل قدر من الصلاحيات.
- احصل من المسؤول على العنوان الجذر الرسمي بـ HTTPS، وعلى الأنطولوجيا أو نظام الأعمال الذي تحتاج إلى الوصول إليه. لا تستخدم أسماء النطاقات الواردة كأمثلة في هذه الوثائق لاستدعاء أعمال حقيقية.
- اضبط عنوان خادم MCP على https://flash.example.com/mcp، واستخدم لمساحة عمل الأعمال المسار /mcp/business على النطاق نفسه.
- ابدأ تسجيل الدخول والتفويض عبر OAuth بحسب ما يدعمه العميل، وتحقق من الموارد وscope؛ ولا تُرسل اسم المستخدم وكلمة المرور إلى MCP.
- استخدم آلية الاكتشاف أو التهيئة الخاصة بجيل البروتوكول المناسب، ثم اقرأ tools/list وأوصاف الموارد.
- نفّذ أولًا طلب قراءة فقط محدود النطاق، وتحقق من النتائج المهيكلة والأخطاء، ثم نفّذ هدف المستخدم.
مقطع تكوين العميل
{
"mcpServers": {
"ot-flash": {
"url": "https://flash.example.com/mcp"
}
}
}يوضح هذا المقطع نية تكوين عنوان الخادم، بينما يعتمد هيكل ملف التكوين ودعم OAuth على العميل. لا تضع قيمًا حقيقية لـ access_token أو refresh_token أو Cookie أو كلمة مرور المسؤول في ملفات عامة.
اكتشاف البروتوكول الحديث
POST /mcp HTTP/1.1
Host: flash.example.com
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover
{
"jsonrpc": "2.0",
"id": 1,
"method": "server/discover",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {"name": "flash-client", "version": "1.0.0"},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}فحوصات قبل التكامل
- تطابق عنوان جذر المورد وOAuth issuer والعنوان الخارجي للخادم الوكيل العكسي (reverse proxy).
- يدعم العميل جيل البروتوكول المناسب، بدلًا من إرسال initialize دائمًا إلى مدخل البروتوكول الجديد.
- التفويض الحالي مرتبط بالأنطولوجيا أو نظام الأعمال المطلوب.
- Token صالح، وقد مُنح التفويض الصريح لأي scope اختيارية جديدة.
اكتشاف OAuth والتسجيل والتفويض
استخدم رمز التفويض مع PKCE، ولا تكشف للوكيل بيانات اعتماد تسجيل الدخول إلى المنتج.
| نقطة النهاية | الطريقة | الوظيفة |
|---|---|---|
| /.well-known/oauth-protected-resource | GET | اكتشاف موارد MCP للأنطولوجيا |
| /.well-known/oauth-protected-resource/mcp | GET | اكتشاف متوافق لمسارات موارد الأنطولوجيا |
| /.well-known/oauth-protected-resource/mcp/business | GET | اكتشاف موارد MCP للأعمال |
| /.well-known/oauth-authorization-server | GET | بيانات وصفية لخادم التفويض |
| /oauth/register | POST JSON | تسجيل ديناميكي لعميل public |
| /oauth/authorize | GET أو نموذج POST | تسجيل الدخول واختيار الموارد وتأكيد التفويض |
| /oauth/token | POST form | استبدال رمز التفويض، والتحديث مع تدوير الرمز |
| /oauth/revoke | POST form | إبطال Token |
| /oauth/grants | GET | عرض الاتصالات المفوَّضة للمستخدم المسجِّل دخوله |
| /oauth/grants/revoke | POST form | إبطال الاتصال وفق تدفق الصفحة الأصلي |
ترتيب التفويض
- اقرأ البيانات الوصفية للمورد المحمي والبيانات الوصفية لخادم التفويض. تشير الاستجابة 401 وترويسة WWW-Authenticate، المُعادتان للطلب الذي لا يحمل Token، إلى عنوان اكتشاف المورد.
- سجّل هوية العميل أو استخدم هوية موجودة. يستخدم التسجيل الديناميكي للعميل public في r56 القيمة token_endpoint_auth_method=none؛ ولا يجوز استخدام سرّ العميل (client secret) بديلًا عن PKCE.
- أنشئ state وcode_verifier عشوائيين، واحسب code_challenge بطريقة S256.
- افتح عنوان authorize المحدد في البيانات الوصفية، مُمرِّرًا response_type=code وclient_id وredirect_uri الدقيق وscope وresource وstate وcode_challenge وcode_challenge_method=S256.
- يسجّل المستخدم الدخول في DataFocus ويختار الأنطولوجيا أو نظام الأعمال. ولا يجوز للعميل أن يختار مسبقًا موارد لا يملك المستخدم صلاحية الوصول إليها.
- استقبل رد النداء (callback)، وتحقق من state وissuer؛ ثم استخدم code_verifier الأصلي لاستبدال رمز التفويض.
- استخدم access_token لمصادقة MCP Bearer فقط. نفّذ التحديث عبر تدفق OAuth الأصلي، واحفظ refresh_token الجديد الناتج عن التدوير بأمان.
مثال التسجيل
{
"client_name": "OT Flash Knowledge Client",
"redirect_uris": ["http://127.0.0.1:8765/callback"],
"application_type": "native",
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"]
}يستخدم رد النداء لعملاء الويب HTTPS؛ ويمكن لعملاء native استخدام عناوين loopback المدعومة. يجب أن يطابق عنوانُ رد النداء العنوانَ المسجَّل تمامًا عند التفويض وعند استبدال Token. كل Grant موجّه إلى مورد محمي (protected resource) واحد، فلا تخلط scope الأنطولوجيا وscope مساحة عمل الأعمال في الاتصال نفسه.
دورة حياة Token
القيم الافتراضية على خادم r56: access token 3600 ثانية، refresh token 2592000 ثانية، رمز التفويض 300 ثانية، ويمكن لكل بيئة نشر تغيير هذه القيم. يجب أن يعتمد العميل على expires_in في استجابة Token وعلى الأخطاء الفعلية، دون تثبيت القيم الافتراضية في الكود. حدّث Token المخزَّن بعد كل تحديث؛ ويؤدي سحب الدور أو صلاحية المورد أو Grant إلى رفض الاستدعاءات اللاحقة.
Scope وحدود الموارد والصلاحيات الآنية
تمنح scope تفويضًا بصلاحيات قائمة فقط، ولا ترقّي الأدوار، ولا تشارك حالة الأعمال بين Grant مختلفة.
| Scope | قدرات نموذجية | قيود مهمة |
|---|---|---|
| ontology.metadata:read | الأنطولوجيا والموارد وبنية الجداول | يجب أن تكون الأنطولوجيا والجداول ضمن نطاق التفويض والقراءة الحالي |
| ontology.graph:read | البحث في الرسم البياني والعُقد المجاورة | تُعيد معلومات تحديد الموقع، لا أدلة على الحقائق |
| ontology.knowledge:read | تحديد موقع المعرفة والنص الأصلي الكامل | تحافظ على صلاحيات قاعدة المعرفة والمستند الأصلية |
| ontology.table:query | استعلام SQL لجداول الأنطولوجيا واستعلام النماذج المنشورة | يتطلب استعلام الجدول أيضًا metadata scope؛ وتظل صلاحيات المصادر والأعمدة الفعلية سارية |
| search:operate | نماذج الكلمات المفتاحية الأصلية والجلسات | إسناد مستقل وصريح، يُنفَّذ وفق صلاحيات النموذج الأصلية وصلاحيات المستخدم على الجداول والأعمدة |
| etl:operate | capabilities الخاصة بـ Flash ETL | Heavy ETL غير متاح |
| authoring.contract:read | عقود النمذجة المتاحة شرطيًا | تتطلب أيضًا مفتاح الميزة والموارد ذات الصلة |
| authoring.artifact:read | قراءة المرشحات والخطط وغيرها ضمن التفويض الحالي | مرتبطة بـ Grant الجهة الأصلية (principal) وبالموارد |
| authoring.artifact:draft | إرسال المرشحات والمعاينة وغيرها | لا تمنح تفويضًا بالتنفيذ أو النشر |
| authoring.artifact:apply | الخطط الخاضعة للتحكم والتطبيق | ما زالت تتطلب دور الأعمال الأصلي والسياسات والموافقات |
| execution.script:draft | مسودات برامج نصية محددة | لا تمنح تفويضًا بالتنفيذ الفعلي للبرامج النصية |
| datasource.http:read / draft / test / import | قدرات HTTP الخاصة بمُخرَجات مصادر البيانات، المتاحة شرطيًا | مفتاح تفعيل مستقل لكل بند، مع الصلاحيات الأصلية |
متطلبات تركيبات القراءة
يتطلب dfc_table detail وجود ontology.metadata:read؛ ويتطلب query أيضًا ontology.table:query. يتطلب dfc_ontology_query نطاقي القراءة graph وknowledge معًا. يتطلب dfc_knowledge_search/detail وجود knowledge. يستخدم published_model/published_query الـscope table:query؛ ويتطلب candidate_query أيضًا authoring.artifact:read. وتتحقق أدوات التحليل أيضًا من scope الأدلة المسموح بها؛ وتتطلب التقارير الدائمة metadata مع table query.
لا تُثبِّت التفويض الافتراضي في الكود
تشمل مجموعة scope الافتراضية للأنطولوجيا في r56 قيمة table query؛ أما Search وETL فيتطلبان إسنادًا صريحًا. ويبقى المرجع النهائي البيانات الوصفية للاكتشاف وصفحة التفويض وscope الفعلية في Token وtools/list. ولا يجوز اعتماد عبارات الوثائق القديمة مثل "الإعداد الافتراضي للأنطولوجيا لا يتضمن SQL مطلقًا" أو "توجد ست أدوات فقط" مرجعًا للتطبيق الحالي.
عزل الحالة
لكلٍّ من الجلسات والتقارير والمرشحات وخطط الإجراءات مالكه ونطاقه الخاص. ولا ينقل تحديث access token عمل Grant الأصلي إلى Grant آخر. لا تدمج sessionId أو reportId أو planId أو رموز الموافقة أو رموز Token المصدر المُعادة من اتصال آخر في الاتصال الحالي.
رسائل HTTP وMCP الحديثة
أرسل البيانات الوصفية لكل طلب وترويسات التوجيه المطابقة بشكل صحيح، وعالج HTTP ونتائج الأدوات بشكل منفصل.
| البند | سلوك r56 |
|---|---|
| النقل | Streamable HTTP عديم الحالة، POST JSON-RPC |
| معرّفات مدعومة | 2026-07-28، إضافة إلى 2025-11-25 و2025-06-18 و2025-03-26 |
| الطرق (methods) الحديثة | server/discover tools/list tools/call resources/list resources/read، وتُتاح وفق القدرات الفعلية |
| ترويسة الجلسة | لا يتم تخصيص Mcp-Session-Id |
| GET وDELETE | تُعيد /mcp و/mcp/business الرمز 405 |
| إشعارات SSE من الخادم | لا يوفّرها مدخلا MCP العامّان هذان |
| التخزين المؤقت للكتالوج | تُعيد استجابات الاكتشاف والسرد الحديثة القيمتين ttlMs=60000 وcacheScope=private |
| النتيجة العادية | تتضمن النتيجة الحديثة القيمة resultType=complete وبيانات وصفية لهوية الخدمة |
المحتوى الواجب مطابقته
- يجب أن يتطابق MCP-Protocol-Version مع io.modelcontextprotocol/protocolVersion في params._meta.
- يجب أن يتطابق Mcp-Method مع قيمة method في JSON-RPC.
- يجب أن يتطابق Mcp-Name في tools/call مع params.name؛ ويجب أن تتطابق ترويسة الاسم في resources/read مع URI.
- يحمل كل طلب حديث كائن io.modelcontextprotocol/clientCapabilities؛ ويُقدَّم أيضًا الكائن clientInfo القياسي لتسهيل التعرّف على العميل.
مثال استدعاء
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "dfc_ontologies",
"arguments": {"page": 1, "pageSize": 20},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {"name": "flash-client", "version": "1.0.0"},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}ترويسات HTTP المقابلة هي Mcp-Method: tools/call وMcp-Name: dfc_ontologies. جميع قيم ACCESS_TOKEN في جميع الأمثلة عناصر نائبة. لا تضع Bearer Token في URL أو في معاملات JSON أو في مفاتيح التخزين المؤقت.
قراءة النتيجة
عالج حالة HTTP أولًا، ثم تحقق من خطأ JSON-RPC؛ وعند وجود result تابع التحقق من isError. تقدّم نتائج الأدوات الناجحة عادةً structuredContent، إضافة إلى محتوى text يتضمن JSON الأعمال نفسه؛ اقرأ القناة المهيكلة أولًا، وتجنّب جمع text وstructuredContent مرتين بوصفهما حقيقتين مستقلتين. قد تحمل استجابة HTTP 200 فشلًا في الأداة.
الموارد العامة وواجهة المستخدم
لا تعتمد موارد الشرح المدمجة على MCP Apps، ولا يعني ذلك أن مدخل مساحة عمل الأعمال يحصل على موارد شرح الأنطولوجيا. ينبغي للعملاء الداعمة للعرض المرئي اكتشاف واجهة المستخدم المقابلة من خلال القدرات الفعلية و_meta للأدوات، دون تخمين URI لموارد لم تُعَد في الاستجابة.
توافق عملاء البروتوكول القديم
حافظ على اتساق جيل البروتوكول لدى العملاء التي ما زالت تستخدم مصافحة التهيئة.
{
"jsonrpc": "2.0", "id": 1, "method": "initialize",
"params": {
"protocolVersion": "2025-11-25",
"capabilities": {},
"clientInfo": {"name": "flash-legacy-client", "version": "1.0.0"}
}
}- أرسل initialize واقرأ إصدار البروتوكول والقدرات التي تفاوض عليها الخادم.
- أرسل إشعارات إتمام التهيئة اللازمة وفق بروتوكول العميل؛ ولا تُرجع الإشعارات نتائج أدوات عادية.
- استخدم tools/list لقراءة الأدوات المتاحة بموجب التفويض الحالي، ثم أرسل tools/call.
- حافظ على اتساق ترويسات الطلب ورسائله مع جيله الحالي، ولا ترسل تسلسل initialize أو ping القديم ضمن رسائل 2026-07-28.
يستخدم البروتوكول القديم آلية Bearer/OAuth نفسها والصلاحيات وعقود الأدوات نفسها. ولا يعني ذلك أن الخادم يوفّر بالضرورة اتصال SSE طويلًا بالنمط القديم أو Mcp-Session-Id؛ وتظل الخدمة العامة في r56 عديمة الحالة.
أخطاء البروتوكول
| الحالة | النتيجة النموذجية | المعالجة |
|---|---|---|
| عدم اتساق الترويسات الحديثة مع الرسالة | HTTP 400 JSON-RPC -32020 | تصحيح الترويسات والبيانات الوصفية وأسماء الأدوات |
| إصدار غير مدعوم | -32022 مع قائمة الإصدارات المدعومة | اختيار بروتوكول مدعوم فعليًا |
| طريقة غير معروفة | JSON-RPC -32601، وقد يرجع الطلب الحديث الرمز HTTP 404 | التحقق من جيل البروتوكول والطريقة |
| معاملات ناقصة أو غير صالحة | JSON-RPC: خطأ في المعاملات، أو خطأ أداة isError | التصحيح وفق inputSchema الفعلي |
اختيار الأداة الصحيحة وقناة الأدلة
وجّه الطلب بحسب سؤال الأعمال الذي لم يُحسم بعد، ولا تكرر جمع الأدلة عبر سلسلة استدعاءات ثابتة.
| المهمة | الأداة المفضلة | الأدلة المطلوبة للإتمام |
|---|---|---|
| اكتشاف المواضيع والموارد المصرح بها | dfc_ontologies dfc_ontology_resources | أنواع معرفات الموارد الفعلية ونطاق الظهور الحالي |
| إحصاءات الجداول وTopN | dfc_table query | إيصال التنفيذ الناجح وevidenceRows الكاملة |
| البحث في اللوائح أو العقود أو التقارير | dfc_ontology_query أو knowledge search/detail | النص الأصلي الكامل المصرح به والقابل للاستخدام كحقيقة |
| تحديد موقع كائنات الرسم البياني | dfc_ontology_graph search/neighbors | تحديد المصدر الفعلي أولًا، ثم الحصول على الحقيقة المقابلة |
| التفاعل بالكلمات المفتاحية الأصلية | dfc_manual ثم dfc_search | النتائج الفعلية في النموذج الأصلي وإطار الأعمال |
| التحليل المدمج والتقارير | dfc_analysis_* أو dfc_report_* | الحالة الحقيقية لكل فرع مهيكل ولأدلة المستندات |
| تعديل العرض أو نموذج الأنطولوجيا | dfc_authoring_* وأدوات artifact | التحقق بشكل منفصل من المرشح والخطة والموافقة والتطبيق الفعلي |
| تنفيذ أوامر الأعمال | أدوات dfb_* في /mcp/business | العقود المنشورة وإيصال ActionPlan الأصلي |
تجنب الاستدعاءات غير الضرورية
عند توفر بنية جدول حالية وكاملة ومصرح بها، لا يُشترط إعادة detail عند كل استعلام؛ وعند توفر تحديد موقع موثوق وأدلة، لا تكرر الاسترجاع نفسه. وعند الحاجة إلى بُعد مفقود، أجرِ استعلامًا تكميليًا محدود النطاق. وعندما يكون الفشل صراحةً غير قابل لإعادة المحاولة، عالج الفجوة أولًا، ولا تجعل "المحاولة مرة أخرى" بديلًا عن التقدير.
الاستثناءات في Flash
قد يُعيد الإجراء capabilities في dfc_etl القيمة available=false مع ETL_NOT_INCLUDED_IN_OT_FLASH. الوصف الثابت لدوال ETL المدمجة مرجع مشترك بين المنتجات، ولا يثبت أن ETL مثبَّت في Flash، ولا يسمح للوكيل بالانتقال تلقائيًا إلى Heavy أو إلى مستأجر آخر للتنفيذ.
موارد الأنطولوجيا وأنواع المعرفات
احصل أولًا على إحداثيات الموارد الفعلية لتجنب الخلط بين أسماء التخزين ومعرفات المستندات ومعرفات قاعدة المعرفة.
- استدعِ dfc_ontologies وتصفّح باستخدام page وpageSize الأنطولوجيات المفوَّضة في هذا التفويض والتي ما زالت قابلة للقراءة حاليًا.
- استدعِ dfc_ontology_resources مع قيمة ontologyId حقيقية؛ واختر حسب الحاجة بين tables وanswers وpinboards وdocuments وknowledgeBindings.
- عالج الترقيم لكل نوع مورد على حدة. الحد الأقصى لـpageSize هو 100؛ ولا تستنتج نطاق المورد بأكمله من الصفحة الأولى.
- احفظ النوع المعلن للمورد ومعرفه الأصلي، واستخدمهما كما هما في الاستدعاءات اللاحقة.
{"name":"dfc_ontology_resources","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"resourceTypes":["tables","documents","knowledgeBindings"],
"page":1,"pageSize":100
}}| الإحداثيات | المصدر | لا يجوز استبداله بـ |
|---|---|---|
| ontologyId | قائمة الأنطولوجيات المفوَّضة أو السياق الساري حاليًا | معرّف أنطولوجيا أخرى |
| معرف مورد الجدول | قائمة tables أو سياق موثوق | physicalName أو اسم الجدول المعروض |
| tblDisplayName colDisplayName | البيانات الوصفية الحالية للجدول والأعمدة | معرّف SQL فيزيائي مُخمَّن |
| knowledgeId | knowledgeBindings أو إيصال استرجاع المعرفة الفعلي | معرف مورد المستند |
| assetId documentId chunkId evidenceId | إيصال تحديد الموقع الفعلي نفسه | حقول مُجمَّعة من نتائج تحديد مواقع مختلفة |
| rid revisionId releaseId | النموذج المنشور أو سياق المرشح على الخادم | معرّف مُولَّد ذاتيًا أو latest |
اصطلاحات الدقة
يُفضَّل تمثيل جميع معرّفات الموارد ذات 64 بت كسلاسل عشرية، ولا تُحوَّل في JavaScript عبر Number. تقبل بعض مخططات Schema للأعمال النوع string أو integer، ولا يعني ذلك جواز التفريط في دقة الأعداد الصحيحة. واحفظ كذلك opaque locator وUUID والتجزئات والرموز أحادية الاستخدام كما هي تمامًا.
استعلام جداول Doris وعقد البنية
نفّذ استعلامات SQL للقراءة فقط على الجداول المفوَّضة، وحافظ على دلالات المخرجات والقيم الدقيقة واكتمال النتائج.
قراءة البنية
{"name":"dfc_table","arguments":{
"action":"detail","ontologyId":"<ONTOLOGY_ID>","id":"<TABLE_RESOURCE_ID>"
}}استخدم معرف مورد جدول حقيقي في detail. تحقق من schemaComplete وtblDisplayName وcolDisplayName في columns وsqlDataType المرجعي، وكذلك من queryContract المُعاد. إن dataType مجرد مطابقة للتوافق، واسم التخزين الفيزيائي ليس اسم الجدول الذي يُستخدم في SQL المُرسَل.
تنفيذ الاستعلام
{
"name": "dfc_table",
"arguments": {
"action": "query",
"ontologyId": "<ONTOLOGY_ID>",
"sql": "SELECT \"区域\", SUM(\"销售金额\") AS \"销售金额合计\" FROM \"电商销售数据\" WHERE \"订单状态\" = '已完成' GROUP BY \"区域\" ORDER BY \"销售金额合计\" DESC",
"maxRows": 100
}
}قيود SQL
- استخدم اسم الجدول المعروض وأسماء الأعمدة المعروضة، وأحط المعرفات بعلامتي اقتباس مزدوجتين. الطلب هو استعلام Doris واحد للقراءة فقط ضمن نطاق الأنطولوجيا.
- أدرج المخرجات صراحةً، ويُمنع SELECT * وtable.*؛ إذ لا يجوز استخدامهما لتجاوز صلاحيات الأعمدة المسجلة عبر الأعمدة الفيزيائية.
- استخدم في الربط JOIN صريحًا ... ON؛ وسيُرفض NATURAL JOIN وJOIN USING.
- يمكن استخدام تعبيرات للقراءة فقط صالحة مثل التجميع متعدد الأبعاد وCTE والنوافذ وCASE وCOUNT(DISTINCT ...)؛ وعدم تغطية التحقق الدلالي لتعبير معين لا يعني حظره من التنفيذ بشكل إجمالي.
- أكمل التجميع والفرز وحساب الرتب في SQL أولًا، ثم طبّق حدًا أقصى على النتائج. الافتراضي لـmaxRows هو 100 والحد الأقصى 200.
التواريخ والمناطق الزمنية
| النوع أو الهدف | الصيغة | ملاحظة |
|---|---|---|
| DATE | CAST('2026-09-01' AS DATE) وCURRENT_DATE | لا تفترض نوع التاريخ من النص الحرفي مباشرةً |
| DATETIME | CAST('2026-09-01 00:00:00' AS DATETIME) وCURRENT_TIMESTAMP | تحقق من المنطقة الزمنية للمصدر والمنطقة الزمنية للجلسة |
| الوقت النسبي | DATE_SUB(CURRENT_DATE, INTERVAL 1 YEAR) | استخدم الدوال الحالية المقابلة للتواريخ والطوابع الزمنية |
| تجميع الوقت | YEAR(column) أو DATE_TRUNC(column, 'month') | استخدم اسمًا مستعارًا فريدًا لكل مخرج؛ واعتمد queryContract كمرجع |
دالة DATE('now', ...) في SQLite ليست عقد تواريخ Doris لهذا المدخل. لا تنقل طريقة التحقق دون الاتصال عبر SQLite من أمثلة الوثائق إلى بيئة SQL الفعلية.
قراءة إيصال استعلام v8
evidenceRows هي القناة الوحيدة المتاحة للوكيل (Agent) لبيانات الصفوف، وraw data غير متاحة للوكيل. تُرمَّز أرقام SQL في سلاسل نصية JSON عشرية دقيقة؛ حدّد قيمتها العددية ونوعها في الأعمال من خلال resultColumnContracts، ولا تفسرها كـ VARCHAR لمجرد أنها مُرمَّزة كسلسلة نصية في JSON. اقرأ executionReceipt ومعلومات الاكتمال والاقتطاع، واحتفظ بمعلومات المصدر مثل evidenceRowsSha256.
يمكن الاستشهاد بمخرجات الاستعلام التي تمتلك إيصال تنفيذ قابلًا للاستشهاد كما هي؛ ولا يُجيز إعادة الحساب الحتمي اللاحقة إلا الدلالات التي تحقّق منها الخادم. لا تخمّن "الرصيد التراكمي" أو "القيمة في نهاية الفترة" أو "العملة" من اسم الحقل، ولا تُضف الوحدات من عندك. ولا يجوز وصف النتائج الخالية من الصفوف أو الفاشلة أو المقتطعة بأنها إحصاءات كاملة.
أفضل 3 عبر أبعاد متعددة ومعالجة الاقتطاع
أجب عن أسئلة الترتيب باستخدام التجميع ودوال النوافذ على الخادم، ولا تُجرِ حسابًا ثانويًا على نتائج غير مكتملة.
يستخدم الملف المرفق examples/top3.sql جدول الأمثلة؛ إذ يجمّع أولًا حسب 区域 و类别 و产品، ثم ينفّذ ROW_NUMBER داخل كل 区域 و类别، ويستخدم اسم 产品 ترتيبًا ثابتًا عند تساوي المبالغ. القيمة maxRows=100 في الطلب تكفي لاستيعاب صفوف المثال الـ36؛ أما بيانات الأعمال الأخرى فيجب تقديرها وفق العدد الفعلي للمجموعات.
- احصل على البنية الحقيقية ومعيار الاحتساب الحالي، وحدّد العملة والفترة و订单状态 وقواعد التعادل.
- أرسل SQL يُجري التجميع وحساب الرتب على الخادم. لا تستعلم أولًا عن إجمالي كل 区域 فقط ثم تتعامل معه على أنه ترتيب لـ 产品 ضمن 类别.
- تحقق من عقد أعمدة المخرجات وevidenceRows الفعلية، وتأكد من أن النتائج المُعادة تغطي جميع المجموعات المطلوبة.
- عند اكتشاف اقتطاع، نفّذ استعلامات مقسّمة محدودة النطاق ضمن الحدود التي يدعمها الخادم، مثل الحصول على أفضل 3 كاملة لكل 区域 على حدة؛ مع الحفاظ في كل مرة على معيار الاحتساب نفسه.
- إذا تغيّرت فترة المصدر، أعد الاستعلام ووضّح الإصدار الجديد، ولا تخلط بين إصدارات بيانات مختلفة أو مؤشرات (cursor) منتهية الصلاحية.
استعادة الأخطاء
TABLE_SCHEMA_INCOMPLETE يستلزم تصحيح البنية أو الحصول عليها كاملة؛ أما حالات الفشل مثل ONTOLOGY_SQL_FAILURE_CONTRACT_INVALID فتُعالج وفق errorCode وretryable وremediation المُعادة. لا تدّعِ أن "جميع عبارات GROUP BY متعددة الأبعاد أو دوال النوافذ محظورة"، ولا تختلق ترتيبات دون نتائج استعلام.
استرجاع المعرفة: النص الأصلي الكامل وأهلية الدليل
افصل بين تحديد الموقع والقراءة والاستشهاد بالحقائق، واحتفظ بالمصدر ومعلومات الاكتمال.
مساران شائعان
| المسار | الغرض | النقاط الأساسية |
|---|---|---|
| dfc_ontology_query | البحث ضمن المعرفة المرتبطة بالأنطولوجيا مع إمكانية الجمع بينها وبين توجيه الرسم البياني | فحص المحتوى القياسي (canonical) في answerContextItems الكامل وأهلية الدليل |
| dfc_knowledge_search → dfc_knowledge_detail chunk | تحديد الموقع عبر بحث صريح، ثم قراءة الأجزاء المختارة | معاينة البحث لا تُعد حقيقة؛ اقرأ النص الأصلي الكامل لنفس الموقع |
{"name":"dfc_knowledge_search","arguments":{
"ontologyId":"<ONTOLOGY_ID>","query":"销售金额是否排除退货", "topK":5
}}
{"name":"dfc_knowledge_detail","arguments":{
"action":"chunk","ontologyId":"<ONTOLOGY_ID>",
"evidenceId":"<EVIDENCE_ID_FROM_THE_SAME_SEARCH_RESULT>"
}}شروط قابلية الاستخدام كحقيقة
- افحص ACL الحالية واكتمال المحتوى وcanonicalFactEligible أو citationEligible من الخادم أو عقد التنفيذ المقابل.
- المحتوى الكامل مرتبط بـ contentSha256. تُعالج حالات الاقتطاع أو الإغفال بسبب الميزانية أو المحتوى منخفض الجودة وفق الحقول الفعلية.
- لا يمكن للبيانات الوصفية للمستند وpage_context وتحديد الموقع في الرسم البياني وملخصات الاسترجاع والمعاينات أن تحل محل النص الأصلي القياسي (canonical).
- يُفضَّل نسخ evidenceId؛ وعند الحاجة إلى chunkId وdocumentId، فيجب أن يأتيا من نتيجة تحديد الموقع نفسها، دون تجميعهما من نتائج مختلفة أو اختلاقهما.
توجيه الرسم البياني
نتائج search/neighbors معلومات لتحديد الموقع. لا تمرّر إلى query في الأنطولوجيا إلا كائن routeLocator الذي أعاده الخادم كاملًا، بما في ذلك الربط والإصدار وحقول الإثبات. لا تغلّف assetId أو knowledgeId بنفسك على هيئة locator صادر عن الخادم، ولا تُعِد إرسال إثبات مصدر ادّعاه النموذج.
استعادة الوثائق المهيكلة
structuredPlan في dfc_ontology_query مخصص للاستعادة المقيدة والتحقق الحتمي لجداول الوثائق غير المنتظمة. استخدم الخطة المعلنة من الخادم فقط بعد إرجاع executionContractSha256 وtableIndex والأعمدة والجدول الكامل الحاليين. يجب أن تمر جداول الأعمال المستوردة العادية عبر dfc_table SQL؛ ولا تتخذ استعادة جداول Markdown قناةً لتجاوز تفويض استعلام الجداول.
استراتيجية الاسترجاع
عادةً تُهمَل knowledgeIds لتغطية الارتباطات المفعّلة حاليًا؛ وعند تمريرها استخدم فقط معرفات قاعدة المعرفة الحقيقية من knowledgeBindings. لا تعامل معرف مورد الوثيقة كمعرف قاعدة معرفة. أجرِ بحثًا جديدًا محدود النطاق لكل مسألة لم تُحل بعد، وتجنّب تكرار الاسترجاع نفسه تمامًا دون الحصول على دليل جديد.
نماذج Search الأصلي وجلساته
استخدم بروتوكول الكلمات المفتاحية لـ Search المكتوب بلغة Rust عبر dfc_search، وانتظر الحالة النهائية لإطار الأعمال الأصلي.
اقرأ الشرح أولًا ثم اكتشف القدرات
{"name":"dfc_manual","arguments":{
"action":"read","uri":"datafocus://manuals/search-keyword-queries/v1"
}}
{"name":"dfc_search","arguments":{"action":"capabilities"}}يتطلب dfc_search الـscope search:operate بشكل صريح. وهو يغلّف WebSocket الأصلي للكلمات المفتاحية، ولا يعيد صياغة الكلمات المفتاحية كطلبات SQL أو LLM. ترتبط الجلسة بالمستأجر والمستخدم وGrant والعميل والنموذج الحاليين، وتعيد فحص صلاحيات أعمدة الجدول الأصلي عند التنفيذ.
الحد الأدنى لتدفق الجلسة
{"name":"dfc_search","arguments":{
"action":"model_create","data":{"tableIds":["<ACTUAL_TABLE_ID>"]}
}}
{"name":"dfc_search","arguments":{
"action":"open","data":{"sourceToken":"<MODEL_SOURCE_TOKEN>","language":"en-US"}
}}
{"name":"dfc_search","arguments":{
"action":"poll","data":{"sessionId":"<SEARCH_SESSION_ID>","waitMillis":10000}
}}
{"name":"dfc_search","arguments":{
"action":"request","data":{"sessionId":"<SEARCH_SESSION_ID>",
"message":{"type":"assist","datas":{}}}
}}
{"name":"dfc_search","arguments":{
"action":"request","data":{"sessionId":"<SEARCH_SESSION_ID>",
"message":{"type":"search","datas":{"search":"<QUERY_USING_ACTUAL_COLUMNS>","ambiguities":[]}}}
}}- يستخدم model_create من 1 إلى 100 معرّف جدول حقيقي يملك المستخدم صلاحية الوصول إليه، أو يقرأ model_read قيمة sourceToken موجودة يملكها المستخدم نفسه.
- يعيد open initializationSent فقط؛ نفّذ poll أولًا، واقرأ استجابة init الأصلية وتأكد من نجاحها.
- اقرأ assist والاقتراحات، ثم أرسل message أصليًا مدعومًا. في datas الخاصة بـ query يثبّت المُغلِّف (wrapper) قيمة isNl على false.
- واصل قراءة frames، وفرّق بين الاقتراحات والتحليل والاستلام ونتيجة الأعمال النهائية.
- عند الانتهاء نفّذ close؛ وعند الحاجة إلى الإلغاء نفّذ cancel، وتحقق من حالة المهمة الفعلية لمعرفة ما إذا كانت قد توقفت.
| action | data | المعنى |
|---|---|---|
| capabilities | محذوف، أو كائن فارغ | قراءة الإجراءات والأوامر وTTL وتعليمات النقل |
| model_create | مصفوفة tableIds | إنشاء نموذج مفوَّض للمستخدم الحالي |
| model_read | sourceToken | قراءة النموذج مع تصفية الأعمدة غير المخوّلة وإعدادات المصادر الحساسة |
| open | sourceToken وlanguage اختياري | إنشاء جلسة أصلية وإرسال init |
| request | sessionId وmessage | إرسال رسالة بروتوكول type/datas الأصلي |
| poll | sessionId مع waitMillis من 0 إلى 30000 | سحب الإطارات المخزّنة مؤقتًا حاليًا مع إمكانية انتظار محدود المدة |
| cancel close | sessionId | إغلاق هذه الجلسة الأصلية، دون إمكانية الجزم بحالة BI النهائية |
الأوامر الأصلية المدعومة
search associateSearch guide assist exportContext reInit
putFormula modifyFormula deleteFormula fnamecheck
disambiguite reDisambiguite clearDisambiguiteتخضع حالة أحرف الأوامر وبنية datas لما تحدده capabilities الحالية وبروتوكول الجلسة الأصلي. لا تُضِف إجراءات غير موجودة إلى request؛ على سبيل المثال يجب الحفاظ على تهجئة disambiguite كما هي في البروتوكول الفعلي. الحد الأقصى لطول الرسالة 256 Ki حرف.
الجلسة والاكتمال
مدة الجلسة TTL هي 10 دقائق ولا تُحفظ إلا خلال عمر العملية الحالية؛ وليست مهمة دائمة قابلة للاستئناف. يضم المخزن المؤقت 256 إطارًا كحد أقصى ويخضع لحدود الذاكرة، وعندما تكون bufferOverflow=true لا يجوز اعتبار الإطارات المسحوبة نتيجة كاملة. بعد خطأ في النقل نفّذ poll على الجلسة الأصلية أولًا، ولا تُعِد إرسال استعلامات ربما نُفّذت بالفعل.
لا يوفّر المُغلِّف (wrapper) الحالي حفظ الإجابات أو اللوحات، ولا قراءة السجل أو الكتابة فيه، ولا استعادة سياق اعتباطي. ووجود exportContext لا يعني أنه يمكنك استعادة أي سياق بنفسك. عند الحاجة إلى حفظ النتائج استخدم قدرات الموارد الأصلية المتاحة فعلياً في المثيل، ولا تختلق action.
اصطلاحات اللغة والمنطقة
حافظ على الحدود بين locale واجهة المستخدم، وقاموس الاستعلام، ولغة الاستجابة، وأسماء الحقول الأصلية.
أولوية التحديد هي: اللغة المطلوبة صراحةً، ثم لغة نظام التطبيق، ثم locale عقدة التنفيذ الفعلية. ولا يؤدي إغفال القيمة أو null أو السلسلة الفارغة أو المسافات البيضاء إلى رجوع ثابت إلى الصينية. يجب الحفاظ على دقة قيم المنطقة في languageRegistry، ولا يجوز طيّ en-GB أو fr-CA أو pt-BR أو es-US أو ar-AE إلى منطقة أخرى بشكل اعتباطي.
| اللغة أو المنطقة | locale الاستعلام | الوصف |
|---|---|---|
| الصينية المبسطة والصينية التقليدية | zh-CN zh-Hant | قواعد الصينية الأصلية تختلف عن كتالوج الصينية التقليدية |
| الإنجليزية الأمريكية والبريطانية والأسترالية والكندية | en-US en-GB en-AU en-CA | يمكن مشاركة حزمة UI/الكلمات المفتاحية، مع الاحتفاظ بالبيانات الوصفية للمنطقة |
| الألمانية والإيطالية والروسية | de-DE it-IT ru-RU | يُستخدم وفق اقتراحات الجلسة الحالية |
| الإسبانية في إسبانيا وأمريكا اللاتينية | es-ES es-US | معرّف المنطقة في المنتج هو es-US |
| الفرنسية في فرنسا وكندا | fr-FR fr-CA | لا تُدمج معرّفات المناطق |
| البرتغالية في البرتغال والبرازيل | pt-PT pt-BR | يُحتفظ بالكتالوج وباصطلاحات المنطقة كلٌّ على حدة |
| الهولندية والدنماركية والنرويجية والفنلندية والسويدية | nl-NL da-DK nb-NO fi-FI sv-SE | النرويجية هي Bokmål |
| اليابانية والكورية | ja-JP ko-KR | لا تُقسَّم الكلمات ذاتيًا وفق قواعد المسافات في الإنجليزية |
| العربية في السعودية والإمارات | ar-SA ar-AE | أوصاف الواجهة تدعم RTL، ولا تُعكس معرّفات البروتوكول |
استخدام كتالوج الكلمات المفتاحية
{"name":"dfc_manual","arguments":{
"action":"keywords","locale":"de-DE","names":["<ACTUAL_KEYWORD_ID>"]
}}لا يتضمن كتالوج الكلمات المفتاحية الثابت في dfc_manual إلا قيم locale المدرجة صراحةً، وعند إغفالها يُستخدم المرجع الإنجليزي؛ وهذه قيمة افتراضية مرجعية، وليست قاعدة لتحديد لغة الاستعلام. وعندما لا يتوفر كتالوج ثابت لمتغير إقليمي، احصل على الاقتراحات الفعلية عبر assist في الجلسة الحالية، ولا تختلق أسماء مستعارة أو نتائج رجوع بديلة. الحد الأقصى لعناصر names في الطلب الواحد 32 عنصرًا.
ما لا يُترجم
- الجداول والأعمدة وقيم التعداد وأسماء العملاء وأسماء الصيغ وسلاسل النماذج الحقيقية الأخرى.
- أسماء الأدوات وaction وscope وحقول Schema وأكواد الأخطاء وقيم الحالة.
- معرفات الموارد والتجزئات (hash) وopaque locator والمراجع الصادرة عن الخادم.
على سبيل المثال يمكن لسؤال بالألمانية الاستعلام عن عمود العرض الصيني "销售金额". وتغييره إلى اسم عمود ألماني يجعله معرّفًا مختلفًا، لا ترجمةً للواجهة. بعد تغيير اللغة أعد تهيئة الجلسة أو حدّثها وفق البروتوكول الأصلي، وأعد الحصول على الاقتراحات ومرشحات إزالة الغموض.
التحليل المدمج والنتائج التفاعلية
في أدوات التحليل المتاحة شرطيًا، حافظ على حالة التفويض والإصدار والفرع والأدلة.
dfc_analysis_* يتحكم فيها الإعداد datafocus.mcp.analysis.tools.enabled. يستمر الجزء المهيكل في المرور عبر استعلام Search المرجعي وسياسة الصفوف الحالية؛ بينما يعيد الجزء الخاص بالمستندات الحصول على النص الأصلي الكامل وفق ACL الحالية. وهذه الأدوات ليست مداخل لـ SQL مفتوح، ولا لحقن تعليمات أو عوامل تصفية اعتباطية.
| الأداة | الغرض | الإحداثيات المطلوبة |
|---|---|---|
| dfc_analysis_ask | طرح سؤال تحليل باللغة الطبيعية | ontologyId وquestion، واختياريًا language وsessionId |
| dfc_analysis_result_get | قراءة نتيجة سبق إرجاعها | ontologyId sessionId resultId |
| dfc_analysis_refine | طرح أسئلة متابعة أو إجراء تغييرات بناءً على أحدث نتيجة كاملة | النتيجة الأصلية expectedRevision ومفتاح idempotency المستقر |
| dfc_analysis_page | الحصول على صفحة واحدة من فرع على الخادم | الفرع الأصلي وإصدار النتيجة pageNo pageSize |
| dfc_analysis_cancel | إلغاء نتيجة ما زالت قيد المعالجة | الجلسة الأصلية والنتيجة |
| dfc_analysis_close | تحرير جلسة ليست قيد العمل | الجلسة الأصلية |
بدء التحليل
{"name":"dfc_analysis_ask","arguments":{
"ontologyId":"<ONTOLOGY_ID>",
"question":"按区域分析已完成订单销售金额,并引用退货统计口径",
"language":"zh-CN"
}}- قراءة sessionId وresultId والحالة وrevision المُعادة، ومتابعة قراءة النتيجة الأصلية عند الحاجة.
- فحص حالة كل فرع مهيكل واكتماله وسياسة صفوفه ومصادره على حدة، دون اعتبار اكتمال فرع واحد دليلًا على اكتمال التحليل بأكمله.
- فحص أدلة المستندات ودفتر الحقائق وأهلية الاستشهاد والقيود. السرد المُولَّد من النموذج لا يرقّي أهلية الدليل من تلقاء نفسه.
- عند الحاجة إلى متابعة سؤال، اعتمد على أحدث نتيجة كاملة ومرّر expectedRevision؛ وعند إعادة محاولة التغيير نفسه، أعد استخدام مفتاح idempotency نفسه.
- قبل الإغلاق، تأكد من أن الجلسة لم تعد قيد العمل؛ فالإلغاء والإغلاق إجراءان مختلفان.
التصفية وترقيم الصفحات الخاضعان للتحكم
يستخدم filter_patch الـbranchId والـfieldRef والـvalueRef والعوامل (operators) المسموح بها التي يوفرها الخادم؛ ولا تعلن التصفية المحددة الأنواع حاليًا إلا EQ. يُحظر استبدال مراجع opaque بـ SQL خام أو tableId أو columnId أو شجرة تصفية يختلقها العميل. يبدأ ترقيم الصفحات pageNo من 1 وبحد أقصى 10000؛ والحد الأقصى لـpageSize هو 100.
تلميحات القدرات والسلوك
التعليقات التوضيحية للأدوات (annotations) تلميحات للعميل، وليست تفويضًا أمنيًا. تستخدم بعض القوالب العامة readOnlyHint، ولا يُغني ذلك عن تقدير طبيعة الإجراء الفعلي؛ فالإلغاء والإغلاق وإنشاء التقارير تغيّر حالة العمل ذات الصلة. نفّذ دائمًا وفق دلالات الأداة وهدف المستخدم وصلاحيات الخادم.
التقارير المرئية الدائمة وMCP Apps
أنشئ تقارير قابلة للاستئناف، واقرأ نتائجها وواجهاتها التفاعلية وفق الصلاحيات الحالية.
يخضع dfc_report_* للتحكم عبر datafocus.mcp.analysis.report-tools.enabled ويتطلب الـscope metadata وtable query. وهو يختلف عن جلسات Search داخل العملية؛ فالتقارير تستخدم معرّفًا دائمًا reportId، ودوام التقرير لا يعني التوقف عن التحقق من الصلاحيات.
{"name":"dfc_report_create","arguments":{
"ontologyId":"<ONTOLOGY_ID>","goal":"比较区域与类别销售表现并核对口径",
"title":"零售经营分析","language":"zh-CN",
"idempotencyKey":"retail-report-20261019-01"
}}
{"name":"dfc_report_status","arguments":{
"ontologyId":"<ONTOLOGY_ID>","reportId":"<REPORT_ID>"
}}سير العمل
- عند الإنشاء، استخدم idempotencyKey مستقرًا بطول 8 إلى 128 حرفًا من الأحرف المدعومة.
- احفظ reportId، واستطلع status، وتحقق من الحالة الفعلية: مكتملة أو فاشلة أو مكتملة جزئيًا أو ملغاة.
- عند قراءة النتائج، راجع الفروع المهيكلة والمرئيات ومصادر الحقائق والاستشهادات من المستندات والاكتمال.
- لإلغاء تقرير غير مكتمل، استخدم reportId الأصلية؛ ولا تنشئ تقريرًا آخر بديلًا عن الإلغاء.
- بعد انتهاء مهلة الشبكة، اقرأ حالة التقرير الأصلي أولًا؛ فإعادة الإرسال بمفتاح idempotency الأصلي يجب أن تحافظ على نية الأعمال نفسها.
MCP Apps
يقرأ العملاء الداعمة لامتدادات واجهة المستخدم صفحات التقارير عبر _meta الخاص بالأداة واكتشاف الموارد الفعلي. صفحة التقرير الدائم المقابلة لـr56 هي ui://datafocus/analysis-report/v16/index.html، ويستخدم التحليل التفاعلي مراجع موارد الخادم المناسبة؛ ولا ينبغي للعميل تثبيت هذه القيم في الكود بدلًا من القيم التي تُعيدها الأداة. وعند غياب امتداد واجهة المستخدم يظل بالإمكان قراءة النتائج المهيكلة.
ربط الأصل (Origin)
عند قراءة التقرير يُعاد التحقق من Grant وربط الأنطولوجيا وأصل الطلب (Origin) وصلاحيات الجدول الحالية. تتطلب تكاملات المتصفح عبر الأصول (cross-origin) استخدام Origin فعلي معتمد؛ ولا يجوز للعميل تجاوز الربط بتزييف Origin. إن reportId القديمة ليست رابطًا عامًا دائمًا ولا بيانات اعتماد للوصول نيابةً عن مستخدمين آخرين.
مسودات المُخرَجات والمعاينة والخطة والتطبيق
سلّم المحتوى المُولَّد إلى الخادم الأصلي ليتولى توحيده والتحقق منه والموافقة عليه، ولا تسمح للنموذج بتعديل موارد الإنتاج مباشرةً.
تتطلب أدوات المُخرَجات (artifacts) تفعيل ميزة authoring، وartifact type فعليًا، والـscope ذات الصلة، وصلاحية الكتابة الأصلية الخاصة بالمسؤول. الأنواع المُهيأة افتراضيًا هي CONTROL_PANEL_SPEC وVIEW_SPEC؛ أما أنواع الاستمارات الأخرى ومصادر HTTP والبرامج النصية فتخضع أيضًا لإعدادات مستقلة. لا يتضمن Flash الميزة AutoML، ولذلك لا تُدرج الأنواع المتعلقة بها ضمن المُخرَجات المتاحة في هذا الإصدار.
- dfc_authoring_capabilities تقرأ العقود والإجراءات المتاحة وفق Grant الحالية.
- dfc_artifact_context تحصل على السياق المحدود وcontractVersion وcontextHash وbaseArtifactHash وbaseArtifactVersion.
- أنشئ المرشح في العميل وفق العقود الحقيقية، دون تنفيذ أي كود يتضمنه.
- dfc_artifact_submit تُرسل السياق الأصلي والمرشح، مع الحفاظ على instruction نفسها، واستخدام clientRequestId مستقر.
- قراءة proposalId وcandidateHash ونتائج التحقق والمعاينة؛ وعند وجود أخطاء فعلية يُعدَّل المرشح، دون تزييف حالة نجاح التحقق على الخادم.
- عند الحاجة إلى إعادة المعاينة، استخدم dfc_artifact_preview وتجزئة المرشح نفسها.
- dfc_artifact_plan تُنشئ خطة غير قابلة للتغيير باستخدام المرشح الحقيقي والإصدار المستهدف ومفتاح idempotency.
- عالج الموافقة عبر الموافقة التفاعلية الأصلية أو وفق سياسة مفوَّضة مسبقًا، ثم استدعِ dfc_artifact_apply؛ وإيصال APPLIED وحده هو ما يمثّل التطبيق الفعلي.
الحد الأدنى لطلب السياق
{"name":"dfc_artifact_context","arguments":{
"artifactType":"CONTROL_PANEL_SPEC",
"ontologyId":"<ONTOLOGY_ID>",
"instruction":"为当前授权销售指标建立区域比较面板"
}}تستخدم VIEW_SPEC projectId المفوَّضة حاليًا؛ وعند تحرير مُخرَج موجود استخدم artifactId الفعلية. تُقدَّم حقول مثل variables وpreviewInput وviewport وفق العقد المُعاد، دون تخمين البنية الداخلية للمرشح.
التزامن وإعادة المحاولة
تربط الخطة الإصدار المستهدف وتجزئة المرشح ومفتاح idempotency. وبعد تغيّر الهدف، لا يمكن مواصلة تطبيق الخطة القديمة؛ بل أعد قراءة السياق وعالج التعارضات الفعلية. ولا يُثبت انتهاء مهلة النقل الفشل؛ استخدم dfc_artifact_status أولًا للاستعلام عن proposalId أو planId الأصلية. لا تعني READY APPLIED.
الموافقة والسياسات التلقائية
تتطلب خطط المُخرَجات العامة الموافقة البشرية الأصلية. وتُعالَج الخطط المطابقة لسياسة النشر التلقائي للأنطولوجيا وفق approvalMode، ولا يُطلب من المستخدم توقيع موافقة يخترعها الوكيل. إن approvalToken مادة يُصدرها الخادم، ولا يجوز للوكيل استبدالها بسلسلة نصية يكتبها؛ وتُحدِّد inputSchema الفعلية وإيصال الخطة الحقولَ الإلزامية.
عقد إنشاء مرشحات الأنطولوجيا ونشرها
استخدم إعلانات الأنطولوجيا وإعدادات النشر ذات الإصدارات المستقلة، ولا تطبّق عقود مُخرَجات العرض العادية على نشر النماذج.
إنشاء مرشح
يجب أن تكون حاوية الأنطولوجيا موجودة مسبقًا وضمن Grant. استخدم dfc_ontology_table_schema للتحقق من حقول المصادر المهيكلة الحالية وبصمة v4 Binding؛ ويمكن الاكتفاء بتقديم sourceField للحقل ليُكتشف نوعه تلقائيًا. تتطلب إعلانات DECIMAL الصريحة الدقة الحالية وعدد المنازل العشرية، أما الأنواع الأخرى فلا تحمل هذين الحقلين.
{"name":"dfc_ontology_table_schema","arguments":{
"ontologyId":"<ONTOLOGY_ID>","sourceAssetRef":"table:<ACTUAL_TABLE_ID>",
"fields":[{"sourceField":"区域"},{"sourceField":"销售金额"}]
}}المرشح وتكوين النشر
| العقد | الغرض | الحدود الرئيسية |
|---|---|---|
| ontology-workspace-create-mcp-submit-v1 | إنشاء مرشح من إعلانات محلية | مصادر حقيقية مفوَّضة، ويُجري الخادم الترجمة البرمجية (compile)، ولا يُقبل إثبات الإكمال |
| ontology-workspace-create-mcp-submit-v2 | مزج المراجع المحلية والمراجع المنشورة الدقيقة | توفير releaseSelections دقيقة وتبعيات الإغلاق |
| ontology-publication-mcp-submit-v1 إلى v3 | ربط مرشح موجود بطلب خطة النشر | إحداثيات صريحة؛ ويستعيد الخادم الهدف والمصدر والموافقة والتحقق |
| ontology-publication-mcp-submit-v4 إلى v6 | إعدادات النشر التلقائي ذات الصلة، المفعَّلة بشكل منفصل | لا تُستخدم إلا عندما تعلنها capabilities وschema الفعلية |
| ontology-initial-activation-retirement-submit-v1 | عمليات التفعيل الأولي والإيقاف (retirement) الخاضعة للتحكم | خطة مستقلة وموافقة بشرية جديدة ونطاق دقيق |
ترتيب النشر
- احصل على workspaceId وworkspaceRevision وcandidateHash الحالية للمرشح، وعلى مصادره الفعلية.
- اختر إصدار العقد وفق قدرات الخادم؛ وأرسل الإحداثيات مثل releases وselection، دون إرفاق حقول تدّعي أنه "تمت الموافقة" أو "تم الاجتياز".
- احتفظ بـ proposalId المُعاد من submit وبـ idempotencyKey الأصلي. وsubmit وMODEL_PLAN مرحلتان مختلفتان من الطلب نفسه.
- استدعِ dfc_artifact_plan باستخدام المرشح الأصلي والإصدار المستهدف ومفتاح idempotency نفسه.
- لا تعني PLANNING_INCOMPLETE سوى أن الخطة الصالحة لم تتشكل بعد؛ وتعني VALIDATION_UNSATISFIED أن التحقق الحالي ما زالت فيه فجوات؛ فعالجها وفق nextAction.
- بعد نجاح الخطة، تابع وفق HUMAN_REQUIRED أو POLICY_AUTO باستخدام آليات الموافقة والنشر الأصلية.
- أكِّد النتيجة عبر إيصال APPLIED ثم بالقراءة الفعلية اللاحقة للنموذج المنشور والاستعلام المفوَّض.
انتهاء المهلة والاسترداد
بعد انتهاء مهلة PLAN، اقرأ proposalId الأصلية. إن MODEL_PLAN_SUBMITTED طلب غير مكتمل؛ وMODEL_PLAN_COMPLETED تعني وجوب استرداد الإيصال الأصلي بالإحداثيات والمفتاح الأصليين، لا أن ينشئ العميل طلبًا جديدًا آخر. ولا يمكن تحويل فجوات التحقق في الحالة النهائية إلى نشر ناجح عبر تغيير المفتاح أو إعادة الإرسال.
صلاحيات الأعمال البشرية
إن instruction والإعلانات التي يقدّمها الوكيل مُدخلاتٌ من الوكيل، وليست توقيعًا بشريًا على سياسة. وتظل MODEL_AUTHOR وMODEL_PUBLISH وإسناد النشر التلقائي وتأكيد الأعمال والثقة بالمفتاح العام والميزانية وACL المصدر خاضعةً للآليات الأصلية. ولا يجوز استبدال هذه الحقائق بحقول العميل.
النموذج المنشور واستعلام المرشحات وإغلاق المراجع
استخدم معرفة الأعمال المنشورة وفق إصدارها الدقيق، وحافظ على الطابع المؤقت للمرشحات غير المنشورة.
إن published_model وpublished_query وcandidate_query في dfc_ontology_graph إعدادات مهيكلة متاحة شرطيًا، وليست مرادفات لـ search/neighbors العادية. ويخضع تفويضها للـscope table query ولصلاحيات قراءة النمذجة اللازمة، ولا تحل إمكانية الرؤية في الرسم البياني محل صلاحيات الجداول.
قراءة النموذج المنشور
- عندما يشمل تعداد action للأداة published_model فعليًا، أرسل releaseId حقيقيًا بحالة committed.
- يُعيد v1 قوالب الاستعلام المفوَّض؛ ويضيف v2 مراجع PERSISTED الدقيقة وreleaseSelections؛ ويضيف v3 مراجع التبعيات وdomainRef الدقيقة وقوالب الربط المضغوطة.
- اختر الكائنات والخصائص والـBinding والـscope والإصدارات من القيم المُعادة الفعلية، ولا تُنشئ RIDs ولا تستخدم latest.
- أرسل عبر published_query استعلامًا ثابتًا محدد الأنواع؛ وما زالت النتائج تخضع لتفويض المصدر والحقول الحالي.
استعلام المرشحات
تستخدم candidate_query قيم workspaceId وrevision وcandidateHash الفعلية وإعلانات المرشح. وعند مزج مراجع منشورة، استخدم إحداثيات LOCAL/PERSISTED المحددة الأنواع الخاصة بـ v2 مع اختيار دقيق. تبقى نتائج المرشح غير منشورة ومؤقتة دائمًا، ولا تُعامل كمعرفة مؤسسية مؤكدة.
الصيانة الجزئية والإغلاق
اختر التبعيات الانتقالية اللازمة لجذر المرشح فقط، واضمن أن لكل مرجع منشور releaseSelections دقيقة. ولا يُغني نسخ نص النشر، أو إرسال مجموعة واحدة من المعرّفات، أو التوسع ليشمل جميع الموارد التاريخية، عن التحقق الحالي من التبعيات والمصادر.
الحقل query في هذه الإجراءات كائن محدد الأنواع وذو إصدار، ولا يقبل SQL أو معرّفات الجداول الفيزيائية أو أسماء جداول المصدر بديلًا عن مراجع الأعمال. ولا تتمتع قوالب البيانات الوصفية ونتائج الرسم البياني بذاتها بأهلية الاستشهاد بها كحقائق.
إسناد المهام إلى وكيل الأنطولوجيا
استخدم المهام الدائمة وGrant الأصلية لاستئناف العمل، ولا تعدّ تعليمات الوكيل موافقة بشرية.
لا يظهر dfc_ontology_agent إلا عند توفر Pi Runtime الفعلي والصلاحيات ذات الصلة. تستخدم QUERY قدرات القراءة؛ وتتطلب AUTHORING كذلك دور النمذجة والـscope المقابلة من نوع authoring. ولا تتيح هذه الأداة محرك تنفيذ آخر غير مقيَّد.
{"name":"dfc_ontology_agent","arguments":{
"contractVersion":"ontology-agent-task-v1","action":"start",
"ontologyId":"<ONTOLOGY_ID>","mode":"QUERY",
"instruction":"列出当前可查询的表,并说明各表用途",
"idempotencyKey":"retail-discovery-01"
}}
{"name":"dfc_ontology_agent","arguments":{
"contractVersion":"ontology-agent-task-v1","action":"status",
"ontologyId":"<ONTOLOGY_ID>","runId":"<RUN_ID>"
}}مجموعة المعلمات الصارمة
يستخدم start الحقول contractVersion وaction وontologyId وmode وinstruction وidempotencyKey؛ ويستخدم status/cancel الحقول contractVersion وaction وontologyId وrunId. يتحقق الخادم من مجموعة الحقول الدقيقة وفق action. الحد الأقصى لـinstruction هو 16000 حرف؛ والمفتاح من 1 إلى 128 حرفًا مدعومًا ويبدأ بحرف أو رقم.
الاستئناف والإلغاء
- احتفظ بقيم runId وGrant وmode ومفتاح idempotency الأصلية.
- المفتاح نفسه مع instruction نفسها يستأنفان الـrun نفسه، دون إرسال مهمة أخرى؛ أما استخدام المفتاح نفسه مع تعليمات مختلفة فيُرفض.
- يستعلم status عن حالة المهمة الأصلية. وبعد الاكتمال ما زال يلزم التحقق من استعلامات الجداول أو الأدلة أو إيصالات النشر الخاصة بها.
- يستخدم الإلغاء runId الأصلية؛ وتُؤكَّد النتيجة عبر حالة المهمة الفعلية.
اكتمال الـrun ليس إيصال نشر نموذج. ويظل تأكيد مهمة النشر عبر حالة artifact الأصلية وفحص المصادر؛ ولا يمنح QUERY أي صلاحية كتابة أو نشر ضمنية.
MCP لمساحة عمل الأعمال
استعلم عن السجلات وفق عقود الأعمال المنشورة، ونفّذ الأوامر عبر ActionPlan الأصلية.
تستخدم /mcp/business موردًا محميًا مستقلًا (protected resource) واختيارًا خاصًا لنظام الأعمال، ولا يجوز إعادة استخدام Grant الأنطولوجيا بديلًا عن تفويض الأعمال. يجب أن يكون نظام الأعمال منشورًا ومتاحًا لاستدعاء الوكيل ومستوفيًا لسياسات الأمان الأصلية، وأن يملك المستخدم الحالي أدوارًا وقدرات فعلية في وقت التشغيل.
| Scope | الأداة | الحدود |
|---|---|---|
| business-system:discover | dfb_systems dfb_system_describe | لا يكتشف إلا الأنظمة المفوَّضة في هذا التفويض والقابلة للاستدعاء حاليًا |
| business-system:read | dfb_query dfb_record dfb_work_items dfb_action_status | السجلات التي يمكن للمستخدم الحالي قراءتها، وخططه الخاصة |
| business-system:plan | dfb_action_plan | إنشاء خطة غير قابلة للتغيير فقط، دون تنفيذ |
| business-system:execute | dfb_action_execute | تفويض مستقل وصريح، ويُنفَّذ وفق المخاطر والموافقة |
- dfb_systems تكتشف الأنظمة المفوَّضة.
- تقرأ dfb_system_describe العقد المنشور الحالي وreleaseId وجميع التجزئات والاستعلامات والأوامر.
- تستخدم dfb_query الـqueryKey المنشورة، مع تحديد objectKey وstate وpage وpageSize حسب الحاجة. وهي ليست أداة لتنفيذ SQL اعتباطي.
- تقرأ dfb_record وdfb_work_items السجلات وعناصر العمل المسموحة حاليًا.
- قبل التنفيذ، قدّم عبر dfb_action_plan قيم releaseId وreleaseHash وcanonicalIrHash وagentManifestHash وcommandType وplanIdempotencyKey الفعلية وحِمل العقد (payload).
- راجع riskClass وrequiresApproval وstatus؛ وإذا تعلّق الأمر بسجل مستهدف فاحتفظ بـ expectedRecordVersion.
- تنفِّذ dfb_action_execute فقط الخطط التي يملكها الاتصال الحالي والجاهزة للتنفيذ، أما رموز الموافقة التي تتطلبها الموافقة البشرية فتُصدرها DataFocus.
- بعد الفشل أو انتهاء المهلة، استخدم dfb_action_status لاسترداد الخطة الأصلية؛ وتحافظ إعادة المحاولة على دلالات idempotency الأصلية.
ربط الاتصال والإصدار
ترتبط الخطة بمعرّف العزل المستقر لـ Grant الحالية. وبعد تحديث Access Token يظل بالإمكان معالجة خطط الاتصال نفسه، ولا يمكن لاتصال OAuth آخر الاستيلاء عليها. وعند التنفيذ يُعاد التحقق من إصدار النشر، وتجزئة IR/manifest، وإصدار السجل المستهدف، وانتهاء صلاحية الخطة، وidempotency، والموافقة. ولا يمكن لقائمة السماح (allowlist) في OAuth تجاوز حوكمة الأعمال.
إدخال معرفة الأعمال والأسئلة التي تنتظر التأكيد
سجّل مدخلات الأعمال عندما يكون معالِج الإنتاج المقابل متاحًا، وحافظ على حدود التأكيد البشري.
يضيف متحكم MCP العام الأدوات الأربع التالية شرطيًا وفقًا للمعالِجات المثبتة وscope الحالية، ولذلك لا تظهر دائمًا في الكتالوج الأساسي. ووجود Schema معلَن لا يعني أن المثيل مزوَّد بالمعالِجات والميزانيات والصلاحيات كاملة؛ يجب التحقق من tools/list أولًا.
| الأداة | الغرض | ما لا تمنحه من تفويض أو تُحدثه من أثر |
|---|---|---|
| dfc_ontology_knowledge_input_propose | تسجيل مدخلات الأعمال الأصلية لمساحة عمل قائمة | لا يولّد أسئلة تأكيد، ولا يمنح موافقة، ولا ينشر |
| dfc_ontology_knowledge_input_preview | معاينة مؤقتة لمسودات الأسئلة من المدخل الأصلي | لا يحفظ بشكل دائم، ولا يؤكد، ولا يُنشئ إيصالًا إنتاجيًا |
| dfc_ontology_knowledge_question_submit | حفظ الأسئلة المؤلَّفة (authored) غير المؤكدة | لا يدمج الإجابات تلقائيًا، ولا يمنح صلاحية المسؤولية أو صلاحية النشر |
| dfc_ontology_business_scope_initialize | تهيئة صريحة لنطاق مستهلك لنظام أعمال واحد | لا ينشر ولا يفعّل ولا يمنح وصولًا للمصادر |
الإدخال والمعاينة
- احصل على workspaceId وworkspaceRevision وlocalRef وpreparationDigest من أعمال التحضير الفعلية.
- تسجّل propose مدخل الأعمال باستخدام عقد input الأصلي وidempotencyKey مستقر؛ ولا يجوز أن يقابل المفتاح نفسه إلا المدخل نفسه.
- تستخدم preview مفتاح idempotency وontologyId الخاصين بالمدخل الأصلي؛ وهي تُعيد في كل مرة revision من الخادم ونافذة مدتها 60 ثانية، وليست إيصال إتمام إنتاجي idempotent.
- عند الحاجة إلى تخزين السؤال، تستخدم question_submit مفتاح أمر جديدًا، وoriginalInputKey الأصلي، وقيمًا صريحة لـ questionRevision وvalidFrom وvalidUntil وexpectedRevision؛ ويكون expectedRevision = null عند الإنشاء.
مدخل التأكيد البشري
knowledgeConfirmationPage الذي تُعيده question_submit مجرد موقع نسبي على صفحة تسجيل الدخول الأصلية، مع تعبئة مسبقة لسؤال معيّن. لا يحمل Bearer، ولا يفتح الصفحة تلقائيًا، ولا يؤكد المعرفة. يشير QUESTION_STORED_UNCONFIRMED صراحةً إلى أن التأكيد لم يتم بعد، ولا يجوز كتابة "تم نشر المعرفة" في الإجابة.
تهيئة نطاق المستهلك
تتطلب business scope initialize كلًّا من صلاحية نشر الأنطولوجيا، وصلاحية المنشئ أو صلاحية إدارة SourceManager على نظام الأعمال المحدد بدقة. تستخدم الإحداثيات الحقيقية لـ domainRid وdomainRevisionId وbusinessSystemId، ولا يجوز للعميل تعبئة أي consumerScope اعتباطية أو إثبات اكتمال. وعند إعادة INITIALIZED وCOMPLETED تبقى القيمتان published=false وactivationAuthorized=false صريحتين.
تخضع هذه الطلبات أيضًا لتحقق صارم من JSON ومن مجموعات الحقول وعدد البايتات والعمق. الحد الأقصى لطلبات الإدخال 1 MiB؛ وبعض العمليات المحددة لها حدود أصغر. تُسلَّم مخططات الإدخال والإخراج الكاملة ضمن مرجع الأدوات، ولا يجوز تطبيق منطق المعاملات المتساهل في مُغلِّفات MCP العامة على هذه العقود الصارمة.
الاستجابة والأخطاء وإعادة المحاولة الآمنة
فسّر الأخطاء طبقةً طبقة، وحافظ على إحداثيات المهمة ودلالات idempotency.
| الطبقة | ما يجب فحصه | مبدأ المعالجة |
|---|---|---|
| الشبكة وHTTP | الاتصال وTLS و401 و403 و400 و404 و405 وغيرها | لا تتعامل مع الاستجابة الفاشلة كنتيجة استعلام عادية |
| JSON-RPC | error.code message data | التمييز بين مشكلات البروتوكول والطريقة والمعاملات والتفويض |
| أدوات MCP | result.isError وstructuredContent | رمز 200 من HTTP لا يعني عدم الفشل |
| نتيجة الأعمال | الحالة الحقيقية والاكتمال وأسباب الفشل وnextAction | الاستلام أو الجاهزية لا يعنيان الاكتمال |
| أهلية الحقائق | executionReceipt citationEligible contentComplete | المحتوى غير المؤهَّل يُستخدم فقط لتحديد الموقع أو تفسير الفجوات |
حالات HTTP الشائعة
- 401: Bearer مفقود أو لم يعد صالحًا؛ حدِّث أو أعد التفويض وفق تدفق OAuth الحالي.
- 403: شروط Grant أو الدور أو الموارد المختارة أو صلاحيات المصدر أو Origin أو الإعدادات غير مستوفاة؛ ولا تحاول تجاوز ذلك بإعادة الإرسال.
- 400: الرسالة أو العقد ذو الإصدار غير صالح، بما في ذلك تعارض الترويسات الحديثة مع البيانات الوصفية.
- 404: تحقَّق من مسار الخدمة الدقيق وطريقة البروتوكول وقدرات بيئة التشغيل؛ لا تبدِّل معرّف الأنطولوجيا عشوائيًا.
- 405: الطريقتان GET وDELETE على /mcp العام غير متاحتين أصلًا؛ استخدم POST الصحيح بدلًا من إنشاء اتصال SSE طويل.
عمليات الكتابة ذات النتيجة غير المعروفة
قد يحتوي MCP_OPERATION_OUTCOME_UNKNOWN على outcome=UNKNOWN وretryable=false وnextAction=READ_ORIGINAL_STATUS وrecoveryTool ومعاملات تحديد الموقع الأصلية. تحقَّق أولًا من الحالة الأصلية، ثم استأنف الطلب الأصلي. لا تعيد تقديم المرشح، ولا تبدّل مفتاح idempotency، ولا تتعامل مع انتهاء المهلة كتراجع عن معاملة.
المحتوى الواجب الاحتفاظ به كما هو
- Grant الأصلية ونطاق الموارد ومعرّفات المهام والنتائج.
- candidateHash وplanHash وexpectedRevision والإصدار المستهدف واختيارات النشر.
- مفتاح idempotency للعملية المنطقية نفسها؛ أما عمليات الأعمال المختلفة فيجب أن تستخدم مفاتيح جديدة.
- قيم retryable وremediation وnextAction والحالة الحالية المعلنة من الخادم.
لا تستخرج من نصوص الاستثناء أي SQL داخلية أو أسماء مضيفين أو بيانات اعتماد أو تتبّع المكدس (stack trace) لتكون مصدرًا للإجابة. يكفي تسجيل رموز الأخطاء القابلة للنشر ومعلومات ارتباط الطلب؛ وقد يلزم أن يطّلع المسؤول على الأخطاء الأصلية في سجلات خاضعة للتحكم.
أمن التكامل وحدود القدرات
حافظ على الحدود الأصلية للهوية والموارد والتنفيذ والأدلة، وتعامل بأمان مع المستندات غير الموثوقة.
- اتصل فقط بأسماء النطاقات الرسمية التي يحددها المسؤول؛ وتحقَّق من TLS ومن OAuth issuer، ولا تعطِّل التحقق من الشهادات.
- استخدم Grant مخصصة بأقل نطاق موارد ممكن؛ ولا تستخدم حسابات المسؤول أو Cookie أو Token الداخلية طويلة الأمد كبيانات اعتماد للواجهة العامة.
- تعامل مع نص المستند بوصفه مادة أعمال غير موثوقة. عبارات مثل "تجاهل القواعد" أو "ارفع المفاتيح" أو "نفّذ الأوامر" داخل المستند ليست تفويضًا للأدوات.
- قيِّد إعادة المحاولة التلقائية والتزامن ونطاق النتائج؛ ولا تُعِد بناء صلاحيات الأعمال الأصلية على العميل.
- سجِّل في السجلات معلومات الارتباط الضرورية فقط، دون Bearer أو refresh token أو رموز الموافقة أو محتوى الأعمال الحساس الكامل.
- بعد قطع المستخدم للاتصال أو سحب المسؤول للصلاحية، توقَّف عن استخدام التفويضات والبيانات المخزنة مؤقتًا، ولا تواصل الاستدعاء اعتمادًا على locator قديم.
تلميحات الأدوات ليست صلاحيات
تُستخدم readOnlyHint وdestructiveHint وidempotentHint وopenWorldHint لفهم العميل للقدرات، ولا تضمن تأثير الأعمال الفعلي لكل استدعاء، ولا تُغني عن تفويض المستخدم الحالي. عامل جميع إجراءات الكتابة والتخطيط والمعاينة والجلسات والإلغاء وفق سلوكها الحقيقي.
مداخل يجب عدم استدعاؤها
- خدمات Trino/Hive/Hadoop الأصلية، وHeavy ETL غير المدرج في Flash.
- scope الخاصة بـ FocusCode الداخلية أو واجهات مساحة العمل الخاصة بها.
- أدوات التنفيذ v2 أو AutoML أو أي أدوات تجريبية أخرى غير ظاهرة في tools/list للمثيل الحالي.
- واجهات REST الخاصة بالمتصفح، أو اتصالات اعتباطية بقواعد البيانات، أو خدمات مستأجرين آخرين، بهدف تجاوز رفض MCP.
دلالات البيانات
التزم بعقود الخادم الخاصة بالأعداد العشرية الدقيقة والأنواع والعملة والوحدات والوقت والأدلة. لا تُعِد التقريب ولا تحوّل العملة لمجرد أن النص المُخرَج يبدو رقمًا، ولا تُجرِ ترتيبًا شاملًا على الصفوف المرئية عندما تكون النتائج مقتطعة.
توصيلات المسؤول ومفاتيح التفعيل الشرطية
قبل تمكين القدرات الموسعة، تحقَّق من المكونات الفعلية والعناوين العامة وإعدادات الصلاحيات الأصلية.
| الإعداد | الغرض | متطلبات الإطلاق |
|---|---|---|
| datafocus.mcp.public-base-url | عنوان الجذر الخارجي الرسمي | اتساق اكتشاف OAuth وissuer وعنوان رد النداء والخادم الوكيل العكسي |
| datafocus.mcp.allowed-origins | أصول (Origin) إضافية معتمدة للمتصفح | إعداد دقيق، دون التوسع إلى أي أصل اعتباطي |
| datafocus.mcp.oauth.route-proof-secret | سرّ خادم مخصص لإثبات توجيه الرسم البياني | يُحفظ بشكل مستقل، ولا يُستخدم Bearer مفتاحًا |
| datafocus.mcp.analysis.tools.enabled | أدوات التحليل التفاعلي | توافر خدمات البيانات والمعرفة والصلاحيات المصاحبة فعليًا |
| datafocus.mcp.analysis.report-tools.enabled | أدوات التقارير الدائمة | توافر الـ worker والتخزين المصاحبين وسلسلة الاستعادة |
| datafocus.mcp.analysis.apps.enabled | عرض MCP Apps | إعلان العميل دعمه، والتحقق من _meta المُعاد |
| datafocus.mcp.authoring.enabled | عقود المسودات والنمذجة | الحفاظ على صلاحيات المسؤول والموارد الأصلية |
| datafocus.mcp.authoring.apply-enabled | قدرة تطبيق المُخرَجات (artifacts) | خطة غير قابلة للتغيير، والموافقة الأصلية، وإعادة التحقق من الحالة الحالية |
| datafocus.mcp.ontology-published-query-enabled | النماذج والاستعلامات المنشورة | إصدارات ملتزمة (committed) فعليًا وتفويض المصادر |
| datafocus.mcp.ontology-candidate-query-enabled | الاستعلامات المهيكلة على المرشحات | ملكية المرشح والإصدار الدقيق وصلاحية القراءة |
| datafocus.mcp.authoring.ontology-auto-publication-enabled | التفويضات المتعلقة بإسناد النشر التلقائي | سياسة أصلية سارية، والثقة بالمفتاح العام، والميزانية، وصلاحية النشر |
تأتي هذه الأسماء من إعدادات r56 وتطبيقه البرمجي؛ وتعتمد إمكانية تفعيلها على الخدمات المصاحبة وبوابات الإطلاق الأصلية. ولا يؤدي تغيير القيمة المنطقية وحده إلى توفير المعالِجات أو قواعد البيانات أو ميزانيات التحقق أو السياسات الناقصة. ويتحدد ظهور امتداد إدخال المعرفة ومهام Pi وفق المكونات المثبتة فعليًا.
الخادم الوكيل الطرفي (edge proxy)
احتفظ بـ Authorization وContent-Type وMCP-Protocol-Version وMcp-Method وMcp-Name وOrigin المعتمد. واضبط حدود جسم الطلب والمهلة وTLS وفق متطلبات الخدمة الفعلية؛ ولا تُمرِّر /mcp العام إلى منفذ الإدارة أو إلى منتج آخر.
قائمة التحقق قبل الإطلاق
- حالات الاكتشاف دون مصادقة والاستدعاءات المحمية مطابقة للمتوقع.
- المستخدم العادي يكتشف نطاق تفويضه فقط، وتُرفض الطلبات اللاحقة بعد سحب الصلاحية.
- جلسات Search الأصلية وSQL والنص الأصلي والتقارير الاختيارية لكل منها نتائج حقيقية.
- تحافظ الموافقات واستعادة idempotency لعمليات الكتابة والنشر على السلوك الأصلي.
- السجلات والمستندات العامة خالية من المفاتيح الخاصة وToken وCookie وكلمات المرور وبيانات العملاء الداخلية.
عميل قابل للتشغيل وأمثلة استدعاء
تحقَّق من الرسائل باستخدام العميل المبسّط المرفق، دون تجاوز OAuth أو التفويض الحالي.
examples/flash_mcp.py عميل بروتوكول مبسّط لا يعتمد إلا على مكتبة Python القياسية. لا يسجّل الدخول، ولا يمنح الموافقات نيابةً عن أحد، ولا يستدعي تلقائيًا أدوات غير ظاهرة، ويدعم البروتوكولات الحديثة والقديمة، ويُنهي التنفيذ بحسب طبقة الخطأ: HTTP أو JSON-RPC أو خطأ الأداة. يُمرَّر Token عبر متغيرات بيئة العملية، ولا يُكتب في النص البرمجي أو ملفات الشرح.
export FLASH_BASE_URL='https://flash.example.com'
read -r -s -p 'Access token: ' FLASH_ACCESS_TOKEN
export FLASH_ACCESS_TOKEN
python3 examples/flash_mcp.py discover
python3 examples/flash_mcp.py tools
python3 examples/flash_mcp.py call dfc_ontologies --arguments '{"page":1,"pageSize":20}'
unset FLASH_ACCESS_TOKENالقراءة والاستعلام
python3 examples/flash_mcp.py call dfc_ontology_resources \
--arguments-file examples/requests/ontology-resources.json
python3 examples/flash_mcp.py call dfc_table \
--arguments-file examples/requests/table-detail.json
python3 examples/flash_mcp.py call dfc_table \
--arguments-file examples/requests/top3-query.jsonاستبدل أولًا العناصر النائبة مثل ONTOLOGY_ID وTABLE_RESOURCE_ID في ملف الطلب بالقيم الحقيقية التي أرجعها التفويض الحالي. يرفض العميل التنفيذ عند وجود عناصر نائبة. يتطلب مثال SQL استيراد CSV المصاحب بأسماء الأعمدة الأصلية؛ ولا يمكن إرساله مباشرة عند غياب schema المقابلة.
سيناريوهات أخرى
- مدخل الأعمال: استخدم --endpoint business، واحصل من جديد على Grant موجَّهة إلى /mcp/business.
- العميل القديم: اختر --protocol 2025-11-25، ونفِّذ initialize أولًا، ثم استدعِ بالبروتوكول نفسه.
- الشرح المدمج: استخدم resources أو read-resource لقراءة URI الفعلي.
- الاختبار الذاتي دون اتصال: يتحقق --self-test من إنشاء الترويسات الحديثة والبيانات الوصفية، ولا يحتاج إلى Token، ولا يطلب خادم المنتج.
حدود المثال
العميل هو نقطة الانطلاق للاتصال بالبروتوكول، ولا يولّد تلقائيًا مرشحات النمذجة أو يحفظ الأسئلة والأجوبة أو ينفذ النشر. وهو يُخرج JSON الأصلي ليتمكن الوكيل في الطبقة الأعلى من التحقق من حالة الأعمال؛ ولا تَعِد المستخدم بإنجاز الاستعلام أو التقرير أو النشر استنادًا إلى رمز خروج العملية وحده.
تضمين واجهة محادثة الأنطولوجيا
ضمّن صفحة المحادثة البشرية في الواجهة الأمامية لتطبيق الأعمال، وحافظ على حدود تسجيل الدخول وأمان المتصفح.
<iframe
title="OT Flash ontology agent"
src="https://flash.example.com/10001/#/embed/ontology-agent/1001"
style="width:100%;height:760px;border:0"
referrerpolicy="strict-origin-when-cross-origin">
</iframe>10001 معرّف مستأجر على سبيل المثال، و1001 معرّف أنطولوجيا على سبيل المثال؛ استبدلهما عند الاستخدام بإحداثيات حقيقية لديك صلاحية عليها. يمكن تحديد أنطولوجيا واحدة عبر path أو query مدعوم؛ ويوفر وضع all خيار @ لاختيار الأنطولوجيات التي يمكن للمستخدم الحالي الوصول إليها. skillId يُمرَّر كما هو فقط، ولا يجوز الاستناد إليه للادعاء بأن تنسيق المهارات قابل للتنفيذ.
المصادقة واسم النطاق
تعتمد الصفحة المضمّنة حاليًا على حالة تسجيل دخول DataFocus حقيقية وتتحقق من /uc/status. تؤثر ملفات تعريف الارتباط عبر المواقع وSSO وframe-ancestors لـCSP وإعدادات البوابة جميعها على التضمين. ولا تقبل الصفحة وضع MCP Bearer داخل URL كقناة للدخول دون تسجيل؛ ولا يجوز أن تُركِّب بنفسك الرابط الخارجي outside غير المُنفَّذ استنادًا إلى مقترحات التصميم.
الفرق بين MCP وiframe
| الطريقة | المستخدم | الهوية والنتيجة |
|---|---|---|
| Remote MCP | تكامل وكيل خارجي أو خدمة خارجية | OAuth Grant وإيصالات أدوات مهيكلة |
| iframe محادثة الأنطولوجيا | المستخدم النهائي البشري | حالة تسجيل الدخول الأصلية وواجهة المحادثة |
| MCP Apps | عميل MCP يدعم الامتدادات | موارد خاضعة للتحكم ونتائج الأداة الحالية، وليست بديلًا عن تسجيل الدخول عبر iframe عام |
قائمة قبول التكامل
أثبت سلسلة الأعمال الكاملة على مثيل حقيقي، ولا تكتفِ بالتأكد من أن الواجهة تُعيد 200.
- الاكتشاف: الحصول على الإصدارات المدعومة فعليًا وكتالوج الأدوات الحالي والموارد المدمجة.
- التفويض: يرى المستخدم العادي الأنطولوجيات وأنظمة الأعمال المصرّح بها فقط؛ وتُرفض العمليات التي لا تملك scope المطلوبة.
- بنية الجدول: الأسماء المعروضة الحقيقية والأعمدة والأنواع والصلاحيات مكتملة.
- SQL: تتوافق استعلامات البعد الواحد والأبعاد المتعددة وJOIN والتواريخ وTopN وفحوص الاقتطاع مع معيار الاحتساب الفعلي للأعمال.
- المعرفة: يتطابق تحديد الموقع والنص الأصلي الكامل وأهلية الاستشهاد بالحقائق، والأسئلة المختلطة لها سند من البيانات والمستندات معًا.
- Search: تنجح فحوص النموذج وinit والاقتراحات والنتائج والإغلاق واكتمال المخزن المؤقت.
- التحليل والتقارير الاختيارية: الحالات الحقيقية للفروع المتعددة وتقليب الصفحات وتغييرات الصلاحيات والإلغاء تحافظ على السلوك الأصلي.
- النمذجة الاختيارية: التحقق مرحلة بمرحلة من المرشح والخطة والموافقة الأصلية والتطبيق الفعلي واستعلام الإصدار.
- إجراءات الأعمال: التحقق من تجزئة النشر والإصدار الهدف والموافقة وidempotency والعزل بين Grant المختلفة.
- الاسترداد: استعادة الحالة الأصلية بعد انتهاء مهلة الشبكة، وتصبح تحديدات المواقع القديمة غير صالحة بعد تحديث المصدر ويُستخدم الاستعلام الجديد.
تسجيل النتائج
سجّل إصدار المثيل ودور المستخدم ونطاق Grant وإصدار الإعدادات والعمليات الفعلية ونتائجها. ميّز بشكل منفصل بين: الاختبار الذاتي دون اتصال لعميل البروتوكول، والقيم المتوقعة دون اتصال لملف CSV النموذجي، والتحقق الثابت من مخطط JSON، وقبول الوظائف الفعلي عبر الإنترنت. لا تَعمّم نجاح مرحلة واحدة لتقرير نجاح المنتج بالكامل.
الموارد القياسية والصيانة
استخدم مخططات الأدوات الكاملة المرفقة مع الدليل، وحافظ على مزامنتها مع نتائج الاكتشاف الفعلية في المثيل.
| الموارد | المحتوى |
|---|---|
| reference/mcp-tool-catalog.json | 32 مخطط إدخال معلنًا من جانب الأنطولوجيا و8 من جانب الأعمال؛ وبعض الأدوات تتضمن مخططات إخراج أصلية |
| reference/locales.json | 21 خيارًا قابلًا للاختيار و24 locale متوافقة، ومصطلحات واجهة المستخدم |
| reference/search-keywords.json | كتالوج كلمات مفتاحية ثابت لـ 17 locale محددة صراحةً |
| reference/analysis-contract-manifest.json | قيود الإصدارات المتعلقة بالتحليل والفروع والحقائق والإيصالات والتقارير |
| examples/ | ملفات CSV اصطناعية، وشرح معايير الاحتساب، وSQL لأفضل 3، والنتائج المتوقعة، وعميل بروتوكول مبسّط |
موارد الشرح المدمجة
datafocus://manuals/etl-formulas/v1
datafocus://manuals/search-keyword-queries/v1
datafocus://manuals/etl-functions/v1
datafocus://manuals/search-keywords/v1يتطلب resources/list وresources/read أن يمتلك المستخدم الحالي واحدة على الأقل من صلاحيات القراءة المقابلة: metadata أو search operate أو etl operate. مستندات ETL مرجع ثابت مشترك بين المنتجات؛ أما القدرة القابلة للتنفيذ في Flash فتبقى مقصورة على النطاق الذي تُبلغ عنه صراحةً.
مرجع البروتوكول الخارجي
للاطلاع على خلفية بروتوكول MCP والتفويض، يُرجع إلى المواصفات الرسمية: https://modelcontextprotocol.io/specification/2026-07-28/basic وhttps://modelcontextprotocol.io/specification/2025-11-25/basic/authorization. أما نقاط النهاية والأدوات والسلوكيات الشرطية لهذا المنتج فالمرجع فيها تطبيق r56 ونتائج الاكتشاف الحالية في المثيل؛ ولا يجوز اعتبار دعم البروتوكول العام مساويًا لتوفير الخادم جميع الميزات الاختيارية.
الترقية والصيانة
عند الترقية، أعد اكتشاف الأدوات والإصدارات وقارن مخططات الإدخال وعقود الإخراج والإعدادات؛ ولا تكتسب Grant القديمة scope جديدة تلقائيًا. أبقِ المراجع والتخزين المؤقت والإيصالات مرتبطة بإصدار المصدر، وأعد الحصول على السياق بعد التأكد من وجود تغييرات غير متوافقة، ولا تفرض استخدام تحديدات المواقع القديمة على حالة أعمال جديدة.
مرجع معلمات الأدوات: الأساسيات وSearch الأصلي
الأسماء الكاملة وحقول الإدخال، مرتبة حسب الأداة للاطلاع.
الجداول التالية مرجع قراءة لحقول إدخال أدوات r56 الحالية. أما الأنواع المتداخلة الكاملة وoneOf والحقول الإلزامية شرطيًا وقيود الأنماط وبعض مخططات Schema للإخراج فانظر reference/mcp-tool-catalog.json؛ وقبل الإرسال النهائي يجب قراءة tools/list الخاصة بـ Grant الحالية. كلمة "اختياري" في الجداول لا تُلغي متطلبات التحقق الداخلية للإجراء.
dfc_manual
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| names | array | اختياري أو إلزامي مشروط | الأسماء الصريحة المطلوب البحث عنها، بحد أقصى 32 لكل استدعاء. maxItems: 32 |
| action | string | اختياري أو إلزامي مشروط | اسم العملية. يُستخدم وفق التعداد الحالي والمعاملات المقابلة للإجراء. enum: list, read, keywords, functions, etl_requests |
| locale | string | اختياري أو إلزامي مشروط | قيمة locale لكتالوج المرجع الثابت، محددة صراحةً، وليست اللغة الافتراضية للاستعلام. |
| uri | string | اختياري أو إلزامي مشروط | URI للموارد المدمجة المدرجة في الأداة الحالية. enum: datafocus://manuals/etl-formulas/v1, datafocus://manuals/search-keyword-queries/v1, datafocus://manuals/etl-functions/v1, datafocus://manuals/search-keywords/v1 |
dfc_search
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| data | object | اختياري أو إلزامي مشروط | حمولة الإجراء الأصلية؛ يُرجع إلى جدول اكتشاف القدرات وحقول الإجراء. |
| action | string | إلزامي | اسم العملية. يُستخدم وفق التعداد الحالي والمعاملات المقابلة للإجراء. enum: capabilities, model_create, model_read, open, request, poll, cancel, close |
dfc_etl
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| data | object | اختياري أو إلزامي مشروط | حمولة الإجراء الأصلية؛ يُرجع إلى جدول اكتشاف القدرات وحقول الإجراء. |
| action | string | إلزامي | اسم العملية. يُستخدم وفق التعداد الحالي والمعاملات المقابلة للإجراء. enum: capabilities |
dfc_ontologies
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| pageSize | integer | اختياري أو إلزامي مشروط | عدد السجلات في الصفحة؛ وفق الحد الأعلى في المخطط. minimum: 1; maximum: 100 |
| page | integer | اختياري أو إلزامي مشروط | رقم الصفحة، يبدأ من 1. minimum: 1 |
dfc_ontology_resources
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| resourceTypes | array | اختياري أو إلزامي مشروط | مجموعة أنواع الموارد المطلوب إرجاعها. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| pageSize | integer | اختياري أو إلزامي مشروط | عدد السجلات في الصفحة؛ وفق الحد الأعلى في المخطط. minimum: 1; maximum: 100 |
| page | integer | اختياري أو إلزامي مشروط | رقم الصفحة، يبدأ من 1. minimum: 1 |
مرجع معلمات الأدوات: الجداول والرسم البياني والمعرفة
الأسماء الكاملة وحقول الإدخال، مرتبة حسب الأداة للاطلاع.
الجداول التالية مرجع قراءة لحقول إدخال أدوات r56 الحالية. أما الأنواع المتداخلة الكاملة وoneOf والحقول الإلزامية شرطيًا وقيود الأنماط وبعض مخططات Schema للإخراج فانظر reference/mcp-tool-catalog.json؛ وقبل الإرسال النهائي يجب قراءة tools/list الخاصة بـ Grant الحالية. كلمة "اختياري" في الجداول لا تُلغي متطلبات التحقق الداخلية للإجراء.
dfc_ontology_graph
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| relationTypes | array | اختياري أو إلزامي مشروط | تصفية نوع العلاقة. |
| depth | integer | اختياري أو إلزامي مشروط | عمق اجتياز العُقد المجاورة. minimum: 1; maximum: 3 |
| sourceTypes | array | اختياري أو إلزامي مشروط | تصفية نوع المصدر. |
| query | object | اختياري أو إلزامي مشروط | نص الاستعلام، أو كائن الاستعلام ذو الإصدار الدقيق المقابل لـ action. |
| limit | integer | اختياري أو إلزامي مشروط | الحد الأقصى لعدد النتائج المُرجعة. minimum: 1; maximum: 100 |
| action | string | إلزامي | اسم العملية. يُستخدم وفق التعداد الحالي والمعاملات المقابلة للإجراء. enum: search, neighbors, published_model, published_query, candidate_query |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| nodeKey | string | اختياري أو إلزامي مشروط | مفتاح عقدة منسوخ من نتائج الرسم البياني الفعلية. |
| keyword | string | اختياري أو إلزامي مشروط | كلمة مفتاحية لتحديد الموقع في الرسم البياني، وليست صيغة طرح الأسئلة بالكلمات المفتاحية. |
| nodeTypes | array | اختياري أو إلزامي مشروط | تصفية نوع العقدة. |
dfc_ontology_query
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| routeLocators | array | اختياري أو إلزامي مشروط | انسخ كاملةً محددات المسار ذات الأنواع التي أصدرها الخادم. maxItems: 20 |
| topK | integer | اختياري أو إلزامي مشروط | الحد الأقصى لعدد النتائج المرشحة المسترجَعة، ولا يُثبت اكتمال التغطية. minimum: 1; maximum: 20 |
| queryMode | string | اختياري أو إلزامي مشروط | اختيار وضع استرجاع الأدلة وفق تعداد الأداة. enum: vector, hybrid, graph |
| fanoutPlan | object | اختياري أو إلزامي مشروط | خطة استرجاع مقيّدة متعددة الفروع، وفق Schema المتداخلة. |
| structuredPlan | object | اختياري أو إلزامي مشروط | خطة مرتبطة بعقد الخادم لجدول المستندات الكامل، وليست SQL. |
| knowledgeIds | array | اختياري أو إلزامي مشروط | معرّف قاعدة المعرفة داخل knowledgeBindings الفعلية. |
| query | string | إلزامي | نص الاستعلام، أو كائن الاستعلام ذو الإصدار الدقيق المقابل لـ action. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
dfc_knowledge_search
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| topK | integer | اختياري أو إلزامي مشروط | الحد الأقصى لعدد النتائج المرشحة المسترجَعة، ولا يُثبت اكتمال التغطية. minimum: 1; maximum: 20 |
| minScore | number | اختياري أو إلزامي مشروط | الحد الأدنى لدرجة التطابق. minimum: 0; maximum: 1 |
| knowledgeIds | array | اختياري أو إلزامي مشروط | معرّف قاعدة المعرفة داخل knowledgeBindings الفعلية. |
| query | string | إلزامي | نص الاستعلام، أو كائن الاستعلام ذو الإصدار الدقيق المقابل لـ action. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| assetIds | array | اختياري أو إلزامي مشروط | معرّفات أصول المستندات المسموح بها حاليًا. |
| retrievalStrategy | string | اختياري أو إلزامي مشروط | استراتيجية الاسترجاع المدعومة فعليًا. enum: auto, hybrid_stage2 |
dfc_knowledge_detail
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| qdrantId | string / integer | اختياري أو إلزامي مشروط | معرّف الفهرس المُرجع من تحديد الموقع الفعلي. |
| pageNo | integer | اختياري أو إلزامي مشروط | رقم الصفحة الفعلية أو رقم صفحة الترقيم. |
| evidenceId | string | اختياري أو إلزامي مشروط | معرّف الدليل الذي أعاده تحديد موقع المعرفة نفسه. |
| action | string | إلزامي | اسم العملية. يُستخدم وفق التعداد الحالي والمعاملات المقابلة للإجراء. enum: chunk, document, page_context |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| documentId | string / integer | اختياري أو إلزامي مشروط | معرّف المستند من تحديد الموقع نفسه. |
| radius | integer | اختياري أو إلزامي مشروط | نطاق الصفحات المجاورة. minimum: 0; maximum: 3 |
| chunkId | string | اختياري أو إلزامي مشروط | معرّف الجزء الفعلي من تحديد الموقع نفسه. |
dfc_table
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| maxRows | integer | اختياري أو إلزامي مشروط | الحد الأقصى لعدد الصفوف المُرجعة؛ وليس نطاق ترتيب من جهة العميل. minimum: 1; maximum: 200 |
| action | string | إلزامي | اسم العملية. يُستخدم وفق التعداد الحالي والمعاملات المقابلة للإجراء. enum: detail, query |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| id | string | اختياري أو إلزامي مشروط | معرّف مورد الجدول الحقيقي، وليس الاسم الفيزيائي أو الاسم المعروض. |
| sql | string | اختياري أو إلزامي مشروط | استعلام Doris SQL للقراءة فقط ضمن نطاق أنطولوجيا واحد، مع أعمدة إخراج صريحة. |
مرجع معلمات الأدوات: التحليل والتقارير
الأسماء الكاملة وحقول الإدخال، مرتبة حسب الأداة للاطلاع.
الجداول التالية مرجع قراءة لحقول إدخال أدوات r56 الحالية. أما الأنواع المتداخلة الكاملة وoneOf والحقول الإلزامية شرطيًا وقيود الأنماط وبعض مخططات Schema للإخراج فانظر reference/mcp-tool-catalog.json؛ وقبل الإرسال النهائي يجب قراءة tools/list الخاصة بـ Grant الحالية. كلمة "اختياري" في الجداول لا تُلغي متطلبات التحقق الداخلية للإجراء.
dfc_analysis_ask
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| question | string | إلزامي | سؤال باللغة الطبيعية أو سؤال متابعة متوافق. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| language | string | اختياري أو إلزامي مشروط | قيمة locale صريحة للإجابة أو الاستعلام؛ وعند إغفالها تُطبَّق قواعد الأداة المقابلة. |
| sessionId | string | اختياري أو إلزامي مشروط | محدِّد الجلسة الحقيقي ضمن Grant نفسها. |
dfc_analysis_refine
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| branchId | string | اختياري أو إلزامي مشروط | محدِّد الفرع المهيكل الذي أصدره الخادم. |
| resultId | string | إلزامي | محدِّد نتيجة التحليل التي أُعيدت أصلًا. |
| question | string | اختياري أو إلزامي مشروط | سؤال باللغة الطبيعية أو سؤال متابعة متوافق. |
| idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. |
| change | object | اختياري أو إلزامي مشروط | تغيير باللغة الطبيعية أو filter_patch محدد الأنواع. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| language | string | اختياري أو إلزامي مشروط | قيمة locale صريحة للإجابة أو الاستعلام؛ وعند إغفالها تُطبَّق قواعد الأداة المقابلة. |
| sessionId | string | إلزامي | محدِّد الجلسة الحقيقي ضمن Grant نفسها. |
| expectedRevision | integer | إلزامي | الشرط المسبق لإصدار النتيجة الأصلية أو إصدار رأس الأعمال؛ ويمكن أن يكون null عند إنشاء سؤال. minimum: 1 |
| visualId | string | اختياري أو إلزامي مشروط | محدِّد العنصر المرئي المرتبط بالفرع. |
dfc_analysis_page
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| branchId | string | إلزامي | محدِّد الفرع المهيكل الذي أصدره الخادم. |
| resultId | string | إلزامي | محدِّد نتيجة التحليل التي أُعيدت أصلًا. |
| pageNo | integer | إلزامي | رقم الصفحة الفعلية أو رقم صفحة الترقيم. minimum: 1; maximum: 10000 |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| pageSize | integer | إلزامي | عدد السجلات في الصفحة؛ وفق الحد الأعلى في المخطط. minimum: 1; maximum: 100 |
| sessionId | string | إلزامي | محدِّد الجلسة الحقيقي ضمن Grant نفسها. |
| expectedRevision | integer | إلزامي | الشرط المسبق لإصدار النتيجة الأصلية أو إصدار رأس الأعمال؛ ويمكن أن يكون null عند إنشاء سؤال. minimum: 1 |
dfc_analysis_result_get
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| resultId | string | إلزامي | محدِّد نتيجة التحليل التي أُعيدت أصلًا. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| sessionId | string | إلزامي | محدِّد الجلسة الحقيقي ضمن Grant نفسها. |
dfc_analysis_cancel
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| resultId | string | إلزامي | محدِّد نتيجة التحليل التي أُعيدت أصلًا. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| sessionId | string | إلزامي | محدِّد الجلسة الحقيقي ضمن Grant نفسها. |
dfc_analysis_close
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| sessionId | string | إلزامي | محدِّد الجلسة الحقيقي ضمن Grant نفسها. |
dfc_report_create
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| goal | string | إلزامي | هدف تحليل التقرير. |
| idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| language | string | اختياري أو إلزامي مشروط | قيمة locale صريحة للإجابة أو الاستعلام؛ وعند إغفالها تُطبَّق قواعد الأداة المقابلة. |
| title | string | اختياري أو إلزامي مشروط | عنوان تقرير اختياري. |
dfc_report_status
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| reportId | string | إلزامي | محدِّد التقرير الدائم ضمن Grant الحالية. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
dfc_report_cancel
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| reportId | string | إلزامي | محدِّد التقرير الدائم ضمن Grant الحالية. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
مرجع معلمات الأدوات: النمذجة والمهام الأصلية
الأسماء الكاملة وحقول الإدخال، مرتبة حسب الأداة للاطلاع.
الجداول التالية مرجع قراءة لحقول إدخال أدوات r56 الحالية. أما الأنواع المتداخلة الكاملة وoneOf والحقول الإلزامية شرطيًا وقيود الأنماط وبعض مخططات Schema للإخراج فانظر reference/mcp-tool-catalog.json؛ وقبل الإرسال النهائي يجب قراءة tools/list الخاصة بـ Grant الحالية. كلمة "اختياري" في الجداول لا تُلغي متطلبات التحقق الداخلية للإجراء.
dfc_ontology_agent
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| mode | string | اختياري أو إلزامي مشروط | QUERY أو AUTHORING، وتُمنح القدرات لكلٍّ منهما على حدة. enum: QUERY, AUTHORING |
| instruction | string | اختياري أو إلزامي مشروط | نص طلب المستخدم؛ ويجب أن يبقى متطابقًا بين context وsubmit. maxLength: 16000 |
| idempotencyKey | string | اختياري أو إلزامي مشروط | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. maxLength: 128 |
| action | string | إلزامي | اسم العملية. يُستخدم وفق التعداد الحالي والمعاملات المقابلة للإجراء. enum: start, status, cancel |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| runId | string | اختياري أو إلزامي مشروط | معرّف المهمة الأصلية ضمن الأنطولوجيا وGrant نفسيهما. |
| contractVersion | string | إلزامي | يجب استخدام إصدار العقد الدقيق المدعوم فعليًا. enum: ontology-agent-task-v1 |
dfc_authoring_capabilities
لا يحتوي الكائن الجذري لإدخال هذه الأداة على أي حقول؛ استخدم كائن arguments فارغًا.
dfc_artifact_context
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| artifactType | string | إلزامي | نوع المُخرَج أو نشر الأنطولوجيا المفعَّل فعليًا. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| scopeType | string | اختياري أو إلزامي مشروط | نوع نطاق الموارد في عقد المُخرَج الفعلي. |
| ontologyId | string | اختياري أو إلزامي مشروط | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| projectId | string | اختياري أو إلزامي مشروط | معرّف المشروع المفوَّض حاليًا. |
| artifactId | string | اختياري أو إلزامي مشروط | المعرّف الحقيقي للمُخرَج الموجود المراد تحريره. |
| instruction | string | إلزامي | نص طلب المستخدم؛ ويجب أن يبقى متطابقًا بين context وsubmit. |
| variables | object | اختياري أو إلزامي مشروط | كائن المتغيرات المقدَّم وفق العقد المُعاد. |
| previewInput | object | اختياري أو إلزامي مشروط | مدخلات المعاينة المحدودة المقدَّمة وفق العقد. |
| viewport | object | اختياري أو إلزامي مشروط | منفذ العرض (viewport) الذي يتطلبه العقد الأصلي. |
dfc_ontology_table_schema
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| sourceAssetRef | string | إلزامي | مرجع أصل مهيكل مُسجَّل، مثل table:123. |
| fields | array | إلزامي | حقول المصدر الحالي مع تعريفات أنواع صريحة اختيارية. minItems: 1; maxItems: 64 |
dfc_artifact_preview
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| proposalId | string | إلزامي | معرّف المرشح الأصلي الذي أُنشئ ضمن Grant الحالية. |
| candidateHash | string | إلزامي | التجزئة الدقيقة للمرشح الأصلي على الخادم. |
| previewInput | object | إلزامي | مدخلات المعاينة المحدودة المقدَّمة وفق العقد. |
dfc_artifact_status
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| proposalId | string | اختياري أو إلزامي مشروط | معرّف المرشح الأصلي الذي أُنشئ ضمن Grant الحالية. |
| planId | string | اختياري أو إلزامي مشروط | معرّف خطة التطبيق غير القابلة للتغيير. |
dfc_artifact_plan
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| proposalId | string | إلزامي | معرّف المرشح الأصلي الذي أُنشئ ضمن Grant الحالية. |
| candidateHash | string | إلزامي | التجزئة الدقيقة للمرشح الأصلي على الخادم. |
| expectedTargetVersion | integer | إلزامي | الشرط المسبق للإصدار المستهدف الحقيقي الحالي. minimum: 0 |
| idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. |
dfc_artifact_apply
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| planId | string | إلزامي | معرّف خطة التطبيق غير القابلة للتغيير. |
| planHash | string | إلزامي | التجزئة التي أعادتها الخطة الأصلية. |
| approvalToken | string | إلزامي | مادة الموافقة الصادرة عن الخادم الأصلي، ويُحظر توليدها ذاتيًا. |
| idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. |
dfc_artifact_submit
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| التكوين 1 / artifactType | string | إلزامي | نوع المُخرَج أو نشر الأنطولوجيا المفعَّل فعليًا. enum: CONTROL_PANEL_SPEC, VIEW_SPEC |
| التكوين 1 / scopeType | string | اختياري أو إلزامي مشروط | نوع نطاق الموارد في عقد المُخرَج الفعلي. |
| التكوين 1 / ontologyId | string | اختياري أو إلزامي مشروط | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| التكوين 1 / projectId | string | اختياري أو إلزامي مشروط | معرّف المشروع المفوَّض حاليًا. |
| التكوين 1 / artifactId | string | اختياري أو إلزامي مشروط | المعرّف الحقيقي للمُخرَج الموجود المراد تحريره. |
| التكوين 1 / instruction | string | إلزامي | نص طلب المستخدم؛ ويجب أن يبقى متطابقًا بين context وsubmit. |
| التكوين 1 / variables | object | اختياري أو إلزامي مشروط | كائن المتغيرات المقدَّم وفق العقد المُعاد. |
| التكوين 1 / previewInput | object | اختياري أو إلزامي مشروط | مدخلات المعاينة المحدودة المقدَّمة وفق العقد. |
| التكوين 1 / viewport | object | اختياري أو إلزامي مشروط | منفذ العرض (viewport) الذي يتطلبه العقد الأصلي. |
| التكوين 1 / contractVersion | string | إلزامي | يجب استخدام إصدار العقد الدقيق المدعوم فعليًا. |
| التكوين 1 / contextHash | string | إلزامي | تجزئة السياق الكامل التي أعادها context. |
| التكوين 1 / baseArtifactHash | string | إلزامي | تجزئة المُخرَج الأساسي التي أعادها context. |
| التكوين 1 / baseArtifactVersion | integer | إلزامي | الإصدار الأساسي الذي أعاده context. minimum: 0 |
| التكوين 1 / candidate | object | إلزامي | كائن مرشح متوافق مع العقد الحالي المُعاد. |
| التكوين 1 / clientRequestId | string | إلزامي | مفتاح idempotency الخاص بالعميل، ويُستخدم بثبات لطلب المرشح الحالي. |
| التكوين 2 / artifactType | string | إلزامي | نوع المُخرَج أو نشر الأنطولوجيا المفعَّل فعليًا. enum: ONTOLOGY_RELEASE |
| التكوين 2 / contractVersion | string | إلزامي | يجب استخدام إصدار العقد الدقيق المدعوم فعليًا. enum: ontology-publication-mcp-submit-v1, ontology-publication-mcp-submit-v2, ontology-publication-mcp-submit-v3, ontology-publication-mcp-submit-v4, ontology-publication-mcp-submit-v5, ontology-publication-mcp-submit-v6 |
| التكوين 2 / ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| التكوين 2 / candidateHash | string | إلزامي | التجزئة الدقيقة للمرشح الأصلي على الخادم. |
| التكوين 2 / workspaceId | string | إلزامي | إحداثيات مساحة عمل المرشّح الفعلية. |
| التكوين 2 / workspaceRevision | string | إلزامي | إصدار المرشّح الدقيق، دون استخدام latest. |
| التكوين 2 / releases | object | إلزامي | اختيار الإصدار الدقيق المقدَّم وفق عقد نشر الأنطولوجيا. |
| التكوين 2 / selection | object | إلزامي | يقدّم إحداثيات اختيار الأعمال الصريحة فقط، دون صلاحيات أو إثبات إتمام. |
| التكوين 2 / idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. |
| التكوين 3 / التكوين 1 / artifactType | string | إلزامي | نوع المُخرَج أو نشر الأنطولوجيا المفعَّل فعليًا. enum: ONTOLOGY_RELEASE |
| التكوين 3 / التكوين 1 / contractVersion | string | إلزامي | يجب استخدام إصدار العقد الدقيق المدعوم فعليًا. enum: ontology-workspace-create-mcp-submit-v1 |
| التكوين 3 / التكوين 1 / ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| التكوين 3 / التكوين 1 / workspaceId | string | إلزامي | إحداثيات مساحة عمل المرشّح الفعلية. |
| التكوين 3 / التكوين 1 / resources | array | إلزامي | إعلانات النموذج الأصلية التي يترجمها الخادم برمجيًا (compile). minItems: 1 |
| التكوين 3 / التكوين 1 / idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. |
| التكوين 3 / التكوين 2 / artifactType | string | إلزامي | نوع المُخرَج أو نشر الأنطولوجيا المفعَّل فعليًا. enum: ONTOLOGY_RELEASE |
| التكوين 3 / التكوين 2 / contractVersion | string | إلزامي | يجب استخدام إصدار العقد الدقيق المدعوم فعليًا. enum: ontology-workspace-create-mcp-submit-v2 |
| التكوين 3 / التكوين 2 / ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| التكوين 3 / التكوين 2 / workspaceId | string | إلزامي | إحداثيات مساحة عمل المرشّح الفعلية. |
| التكوين 3 / التكوين 2 / resources | array | إلزامي | إعلانات النموذج الأصلية التي يترجمها الخادم برمجيًا (compile). minItems: 1 |
| التكوين 3 / التكوين 2 / idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. |
| التكوين 3 / التكوين 2 / releaseSelections | object | إلزامي | قيمة releaseId الدقيقة وإغلاق التبعيات لكل مرجع منشور. |
| التكوين 4 / artifactType | string | إلزامي | نوع المُخرَج أو نشر الأنطولوجيا المفعَّل فعليًا. enum: ONTOLOGY_RELEASE |
| التكوين 4 / contractVersion | string | إلزامي | يجب استخدام إصدار العقد الدقيق المدعوم فعليًا. enum: ontology-initial-activation-retirement-submit-v1 |
| التكوين 4 / ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| التكوين 4 / domainRid | string | إلزامي | قيمة RID لنطاق الأعمال الحقيقي. |
| التكوين 4 / consumerScopes | array | إلزامي | نطاقات المستهلكين الدقيقة التي يسمح بها الخادم. minItems: 1; maxItems: 256 |
| التكوين 4 / idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. |
مرجع معلمات الأدوات: إدخال المعرفة والنطاق
الأسماء الكاملة وحقول الإدخال، مرتبة حسب الأداة للاطلاع.
الجداول التالية مرجع قراءة لحقول إدخال أدوات r56 الحالية. أما الأنواع المتداخلة الكاملة وoneOf والحقول الإلزامية شرطيًا وقيود الأنماط وبعض مخططات Schema للإخراج فانظر reference/mcp-tool-catalog.json؛ وقبل الإرسال النهائي يجب قراءة tools/list الخاصة بـ Grant الحالية. كلمة "اختياري" في الجداول لا تُلغي متطلبات التحقق الداخلية للإجراء.
dfc_ontology_knowledge_input_propose
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| request | object | إلزامي | طلب مدخلات الأعمال الأصلي؛ وفق Schema المتداخلة الكاملة. |
| idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. minLength: 1; maxLength: 128 |
لهذه الأداة أيضًا outputSchema أصلية. تحقّق من اكتمال المخرجات وحالتها وحقول التفويض التي قيمتها false صراحةً، ولا ترفع بنفسك دلالة الإتمام.
dfc_ontology_knowledge_input_preview
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. minLength: 1; maxLength: 128 |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
لهذه الأداة أيضًا outputSchema أصلية. تحقّق من اكتمال المخرجات وحالتها وحقول التفويض التي قيمتها false صراحةً، ولا ترفع بنفسك دلالة الإتمام.
dfc_ontology_knowledge_question_submit
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| questionRevision | $ref | إلزامي | الإصدار الصريح للسؤال الذي ينتظر التأكيد في هذا الطلب. |
| idempotencyKey | $ref | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. |
| originalInputKey | $ref | إلزامي | مفتاح idempotency الخاص بمدخل المعرفة الأصلي المقابل. |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. |
| validUntil | $ref | إلزامي | نهاية نافذة صلاحية السؤال، بتوقيت UTC. |
| expectedRevision | oneOf | إلزامي | الشرط المسبق لإصدار النتيجة الأصلية أو إصدار رأس الأعمال؛ ويمكن أن يكون null عند إنشاء سؤال. |
| validFrom | $ref | إلزامي | بداية نافذة صلاحية السؤال، بتوقيت UTC. |
لهذه الأداة أيضًا outputSchema أصلية. تحقّق من اكتمال المخرجات وحالتها وحقول التفويض التي قيمتها false صراحةً، ولا ترفع بنفسك دلالة الإتمام.
dfc_ontology_business_scope_initialize
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| domainRevisionId | string | إلزامي | إصدار نطاق الأعمال الدقيق. minLength: 1; maxLength: 128 |
| idempotencyKey | string | إلزامي | مفتاح idempotency يُعاد استخدامه بثبات لعملية منطقية واحدة. minLength: 1; maxLength: 128 |
| businessSystemId | string | إلزامي | معرّف نظام الأعمال الحقيقي. minLength: 1 |
| ontologyId | string | إلزامي | معرّف الأنطولوجيا الحقيقي ضمن هذا التفويض، ويُحفظ كسلسلة نصية. minLength: 1 |
| domainRid | string | إلزامي | قيمة RID لنطاق الأعمال الحقيقي. minLength: 1; maxLength: 128 |
لهذه الأداة أيضًا outputSchema أصلية. تحقّق من اكتمال المخرجات وحالتها وحقول التفويض التي قيمتها false صراحةً، ولا ترفع بنفسك دلالة الإتمام.
مرجع معلمات الأدوات: مساحة عمل الأعمال
الأسماء الكاملة وحقول الإدخال، مرتبة حسب الأداة للاطلاع.
الجداول التالية مرجع قراءة لحقول إدخال أدوات r56 الحالية. أما الأنواع المتداخلة الكاملة وoneOf والحقول الإلزامية شرطيًا وقيود الأنماط وبعض مخططات Schema للإخراج فانظر reference/mcp-tool-catalog.json؛ وقبل الإرسال النهائي يجب قراءة tools/list الخاصة بـ Grant الحالية. كلمة "اختياري" في الجداول لا تُلغي متطلبات التحقق الداخلية للإجراء.
dfb_systems
لا يحتوي الكائن الجذري لإدخال هذه الأداة على أي حقول؛ استخدم كائن arguments فارغًا.
dfb_system_describe
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| systemId | string / integer | إلزامي | معرّف النظام المسموح به ضمن Grant الأعمال هذه. |
dfb_query
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| systemId | string / integer | إلزامي | معرّف النظام المسموح به ضمن Grant الأعمال هذه. |
| queryKey | string | إلزامي | مفتاح الاستعلام المنشور الذي أعاده describe. |
| objectKey | string | اختياري أو إلزامي مشروط | مفتاح الكائن المنشور. |
| pageSize | integer | اختياري أو إلزامي مشروط | عدد السجلات في الصفحة؛ وفق الحد الأعلى في المخطط. minimum: 1; maximum: 100 |
| page | integer | اختياري أو إلزامي مشروط | رقم الصفحة، يبدأ من 1. minimum: 1 |
| state | string | اختياري أو إلزامي مشروط | تصفية حالة الأعمال أو حالة الخادم. |
dfb_record
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| recordId | string / integer | إلزامي | معرّف سجل الأعمال المسموح بقراءته حاليًا. |
| systemId | string / integer | إلزامي | معرّف النظام المسموح به ضمن Grant الأعمال هذه. |
dfb_work_items
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| systemId | string / integer | إلزامي | معرّف النظام المسموح به ضمن Grant الأعمال هذه. |
dfb_action_plan
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| expectedRecordVersion | integer | اختياري أو إلزامي مشروط | إصدار القفل المتفائل الحالي للسجل المستهدف. minimum: 1 |
| systemId | string / integer | إلزامي | معرّف النظام المسموح به ضمن Grant الأعمال هذه. |
| commandType | string | إلزامي | نوع الأمر في العقد المنشور. |
| canonicalIrHash | string | إلزامي | تجزئة IR القياسية (canonical) للإصدار المنشور الحالي. |
| releaseId | string / integer | إلزامي | معرّف إصدار العقد المنشور الفعلي. |
| payload | object | إلزامي | الحمولة المتوافقة مع عقد الأمر الحالي في describe. |
| releaseHash | string | إلزامي | تجزئة العقد المنشور الفعلي. |
| targetRecordId | string / integer | اختياري أو إلزامي مشروط | السجل المستهدف الحقيقي المطلوب تنفيذ العملية عليه. |
| agentManifestHash | string | إلزامي | تجزئة manifest قدرات الوكيل الفعلية. |
| planIdempotencyKey | string | إلزامي | مفتاح idempotency الثابت لخطة الأعمال. |
dfb_action_status
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| actionPlanId | string / integer | إلزامي | معرّف خطة الإجراءات التي تملكها Grant الأعمال الحالية. |
dfb_action_execute
| المعامل | النوع | الشرط | المعنى والنطاق |
|---|---|---|---|
| approvalToken | string | اختياري أو إلزامي مشروط | مادة الموافقة الصادرة عن الخادم الأصلي، ويُحظر توليدها ذاتيًا. |
| actionPlanId | string / integer | إلزامي | معرّف خطة الإجراءات التي تملكها Grant الأعمال الحالية. |