Agent API و MCP

الجمهور: وكلاء LLM، بيئات استدعاء الأدوات، وعملاء MCP (Cursor وClaude Desktop). للواجهات الخلفية البشرية والمتاجر، استخدم /v1/* + OpenAPI .

تكاملات الذكاء الاصطناعي: MCP ومهارة hiobuy-agent-api تعرض لوكلاء LLM أدوات China sourcing مباشرة على 1688 وTaobao وWeidian — بحث بالكلمة المفتاحية وبحث بالصورة وتفاصيل منتج ثنائية اللغة لسير عمل shopping agent في Cursor وClaude Desktop.

المصادقة: مفاتيح Live hio_live_* فقط. مفاتيح Sandbox (hio_test_*) وتثبيتات Sandbox لا تنطبق على /ai/v1 أو /mcp.

ذات صلة: المصادقة · المنتجات · تنسيق الاستجابة · الأخطاء · حدود المعدل

متى تستخدم أي واجهة

حمولات data للأدوات تطابق الأشكال القياسية من نماذج استجابة المنتج ونقاط القائمة — وليس التنسيق الخام upstream.

المتطلبات المسبقة (مفتاح Live)

قبل استدعاء /ai/v1 أو /mcp:

1. سجّل وأنشئ تطبيقاً في بوابة مطوري HIOBuy ؛ انتظر الموافقة.
2. فوّض القنوات (1688 وTaobao وWeidian و…) — كما في تفويض البوابة.
3. أنشئ مفتاح API Live ضمن API Keys (hio_live_* — يُعرض مرة واحدة عند الإنشاء).
4. امنح النطاقات الدنيا لأدوات Phase 1:
   • product:detail — product.get_detail
   • product:search — product.search وproduct.upload_image وproduct.search_by_image

غياب تفويض القناة أو النطاق → 401 / 403. استدعاءات Live تستهلك حصة القناة وتُسجَّل مثل /v1.

عنوان URL الأساسي والمصادقة

نفس المضيف كـ Public API، مثلاً https://api.hiobuy.com.

Authorization: Bearer hio_live_<your_key>

كل أداة تطابق نطاق API Key موجود — لا يوجد نطاق منفصل tools:*.

نقاط النهاية HTTP (/ai/v1)

قائمة الأدوات

curl -s https://api.hiobuy.com/ai/v1/tools \
  -H "Authorization: Bearer hio_live_xxx"

تُرجع فقط الأدوات المسموح بها بنطاقات المفتاح. كل إدخال يتضمن id وversion وdomain وdescription وJSON Schema input_schema.

استدعاء أداة

POST /ai/v1/tools/call
Authorization: Bearer hio_live_xxx
Content-Type: application/json
 
{
  "tool_id": "product.get_detail",
  "arguments": {
    "channel": "1688",
    "product_id": "554456348334",
    "language": "en"
  }
}

غلاف النجاح (كل الأدوات):

الفشل: HTTP 4xx/5xx مع { "error": { "code", "message", "request_id" } } — بلا حقل ok. راجع الأخطاء للرموز المشتركة (INVALID_API_KEY وFORBIDDEN وRATE_LIMITED و…).

أدوات Phase 1 (المنتجات)

product.get_detail

• القناة: taobao | 1688 | weidian
• مطلوب: channel + أحد product_id | url | mi_id | tao_password
• اختياري: language (افتراضي en)
• data: { "product": StandardProduct }

product.search

• مطلوب: channel وkeyword
• اختياري: page وpage_size وlanguage وsort وprice_start وprice_end
• data: StandardProductList (نفس جسم POST /v1/products/search)

product.upload_image

• القناة: 1688 | taobao
• 1688: image_base64 أو image_url
• Taobao: image_base64 مطلوب
• data: { "channel", "image_id" } — أعد استخدام image_id للبحث بالصورة مع ترقيم الصفحات

product.search_by_image

• القناة: 1688 | taobao (ليس Weidian)
• الإدخال: image_id | image_url | image_base64
• التدفق الموصى به للترقيم: product.upload_image مرة → عدة استدعاءات product.search_by_image بـ image_id فقط

سير عمل الوكيل (HTTP)

1. GET /ai/v1/tools → تخزين بيانات الأدوات / input_schema مؤقتاً
2. النموذج يختار tool_id + arguments من نية المستخدم
3. POST /ai/v1/tools/call (Bearer hio_live_…)
4. تلخيص data للمستخدم

سلاسل نموذجية:

• بحث صورة بخطوة واحدة: product.search_by_image مع image_url أو image_base64
• بحث صورة مع ترقيم: product.upload_image → product.search_by_image (image_id + page)
• بعد اختيار المستخدم لمنتج: product.get_detail

خادم MCP (/mcp) — China sourcing لوكلاء الذكاء الاصطناعي

في Cursor وClaude Desktop وعملاء MCP آخرين، يستدعي الوكلاء أدوات China sourcing والشراء بالوكالة على 1688 (جملة) وTaobao (تجزئة) وWeidian — بحث كلمات مفتاحية ورفع/بحث صور وتفاصيل منتج ثنائية اللغة. سلاسل shopping agent النموذجية: مقارنة عروض المصانع على 1688، بدائل Taobao، تصفّح كتالوجات Weidian، ثم التعمّق في SKU/المخزون عبر product.get_detail.

نفس وقت تشغيل الأدوات مُعرَّض كـ MCP Server عبر Streamable HTTP (Cursor وClaude Desktop وعملاء MCP آخرون).

المصادقة: نفس ترويسة Authorization: Bearer hio_live_*.

القدرات:

• Tools — tools/list وtools/call (نفس قيم tool_id كـ /ai/v1)
• Prompts — سير عمل مدمج للبحث عن المنتجات / بالصورة / البحث
• Resources — عناوين hiobuy://agent/* (resources/list وresources/read وقوالب)
• Subscriptions — resources/subscribe → SSE notifications/resources/updated
• Streaming — GET /mcp يفتح SSE؛ POST مع Accept: text/event-stream قد يبث JSON-RPC
• Sampling — الخادم قد يرسل sampling/createMessage عبر SSE؛ العميل يرد عبر POST /mcp (202)

تدفق الجلسة الموصى به:

1. POST initialize → احفظ ترويسة الاستجابة Mcp-Session-Id
2. GET /mcp مع الجلسة → افتح مستمع SSE
3. POST notifications/initialized
4. POST tools/list / tools/call

عند النجاح، tools/call → result.content[0].text هو نفس غلاف JSON كـ /ai/v1/tools/call.

إعداد Cursor (MCP shopping agent + China sourcing 1688/Taobao/Weidian)

أضف في Settings → MCP أو .cursor/mcp.json لمنح Cursor أدوات China sourcing مباشرة على 1688 / Taobao / Weidian:

{
  "mcpServers": {
    "hiobuy": {
      "url": "https://api.hiobuy.com/mcp",
      "headers": {
        "Authorization": "Bearer hio_live_xxx"
      }
    }
  }
}

استبدل hio_live_xxx بمفتاح Live. احتفظ بالمفاتيح على الخادم — لا ترفعها إلى مستودعات عامة.

Cursor Agent Skill (hiobuy-agent-api) — China shopping agent

Cursor Agent Skill الاختياري hiobuy-agent-api يساعد وكلاء البرمجة على ربط تدفقات China sourcing على 1688 وTaobao وWeidian — نطاقات مفاتيح Live وأغلفة /ai/v1 وترويسات جلسة MCP وسلاسل بحث → بحث صورة → تفاصيل. لمتاجر REST على /v1/*، استخدم OpenAPI.

يعلّم النموذج:

• متطلبات مفاتيح Live والنطاقات لأدوات 1688 / Taobao / Weidian
• أغلفة طلب/استجابة /ai/v1 ومعاملات أدوات Phase 1
• ترويسات جلسة MCP وتوصيل Cursor mcp.json لسير China shopping
• رموز الأخطاء وسلاسل sourcing (بحث → بحث صورة → تفاصيل)

ثبّت من المستودع العام hiobuy-agent-skills  — استنسخ أو انسخ SKILL.md إلى دليل skills في Cursor (انظر Cursor Agent Skills ).

git clone https://github.com/hubinjie/hiobuy-agent-skills.git

المهارة تكمّل هذه الصفحة — هذا الموقع يبقى المرجع الرسمي للـ API للنطاقات والحصص ودلالات حقول المنتج.

مرجع سريع

BASE=https://api.hiobuy.com
KEY=hio_live_xxx
 
curl -s "$BASE/ai/v1/tools" -H "Authorization: Bearer $KEY"
 
curl -s "$BASE/ai/v1/tools/call" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_id":"product.search","arguments":{"channel":"1688","keyword":"phone case","page":1,"page_size":5}}'