TypeBox

​

النموذج الذهني (30 ثانية)

• طلب: { type: "req", id, method, params }
• استجابة: { type: "res", id, ok, payload | error }
• حدث: { type: "event", event, payload, seq?, stateVersion? }

العميل                   Gateway
  |---- طلب:connect -------->|
  |<---- استجابة:hello-ok ----|
  |<---- حدث:tick ------------|
  |---- طلب:health ---------->|
  |<---- استجابة:health ------|

​

مواضع المخططات

• ملف التصدير المصدر: يعيد packages/gateway-protocol/src/schema.ts تصدير وحدات النطاق ضمن packages/gateway-protocol/src/schema/*.ts ‏(frames.ts للأغلفة العليا والمصافحة، وagent.ts وsessions.ts وcron.ts وغيرها بحسب مجال الميزة). يمثّل protocol-schemas.ts سجل ProtocolSchemas المركزي الذي يربط أسماء المخططات بتعريفاتها في TypeBox.
• أدوات التحقق أثناء التشغيل (AJV): packages/gateway-protocol/src/index.ts
• سجل الميزات/الاكتشاف المعلن: src/gateway/server-methods-list.ts
• مصافحة الخادم وتوجيه الأساليب: src/gateway/server.impl.ts
• عميل Node: src/gateway/client.ts
• JSON Schema المولَّد: dist/protocol.schema.json (ناتج بناء، غير مُضمَّن في المستودع)
• نماذج Swift المولَّدة: apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

​

مسار المعالجة الحالي

• يكتب pnpm protocol:gen ملف JSON Schema ‏(draft-07) إلى dist/protocol.schema.json.
• يولّد pnpm protocol:gen:swift نماذج Gateway بلغة Swift.
• يشغّل pnpm protocol:check كلا المولّدين ويتحقق من تضمين ناتج Swift في المستودع (أما ناتج JSON Schema فهو أثر بناء يتجاهله Git).

​

كيفية استخدام المخططات أثناء التشغيل

• جانب الخادم: يُتحقق من كل إطار وارد باستخدام AJV. لا تقبل المصافحة سوى طلب connect تطابق معاملاته ConnectParams.
• جانب العميل: يتحقق عميل JS من إطارات الأحداث والاستجابات قبل استخدامها.
• اكتشاف الميزات: يرسل Gateway قائمة متحفظة من features.methods وfeatures.events ضمن hello-ok، مصدرها listGatewayMethods() وGATEWAY_EVENTS.
• قائمة الاكتشاف هذه ليست تفريغًا مولَّدًا لكل دالة مساعدة قابلة للاستدعاء في coreGatewayHandlers؛ إذ توجد بعض إجراءات RPC المساعدة المنفَّذة في src/gateway/server-methods/*.ts من دون إدراجها في قائمة الميزات المعلنة.

​

أمثلة على الإطارات

{
  "type": "req",
  "id": "c1",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 4,
    "client": {
      "id": "openclaw-macos",
      "displayName": "macos",
      "version": "1.0.0",
      "platform": "macos 15.1",
      "mode": "ui",
      "instanceId": "A1B2"
    }
  }
}

{
  "type": "res",
  "id": "c1",
  "ok": true,
  "payload": {
    "type": "hello-ok",
    "protocol": 4,
    "server": { "version": "dev", "connId": "ws-1" },
    "features": { "methods": ["health"], "events": ["tick"] },
    "snapshot": {
      "presence": [],
      "health": {},
      "stateVersion": { "presence": 0, "health": 0 },
      "uptimeMs": 0
    },
    "auth": { "role": "operator", "scopes": ["operator.read"] },
    "policy": { "maxPayload": 1048576, "maxBufferedBytes": 1048576, "tickIntervalMs": 30000 }
  }
}

{ "type": "req", "id": "r1", "method": "health" }

{ "type": "res", "id": "r1", "ok": true, "payload": { "ok": true } }

{ "type": "event", "event": "tick", "payload": { "ts": 1730000000 }, "seq": 12 }

​

عميل مبسّط (Node.js)

import { WebSocket } from "ws";

const ws = new WebSocket("ws://127.0.0.1:18789");

ws.on("open", () => {
  ws.send(
    JSON.stringify({
      type: "req",
      id: "c1",
      method: "connect",
      params: {
        minProtocol: 4,
        maxProtocol: 4,
        client: {
          id: "cli",
          displayName: "example",
          version: "dev",
          platform: "node",
          mode: "cli",
        },
      },
    }),
  );
});

ws.on("message", (data) => {
  const msg = JSON.parse(String(data));
  if (msg.type === "res" && msg.id === "c1" && msg.ok) {
    ws.send(JSON.stringify({ type: "req", id: "h1", method: "health" }));
  }
  if (msg.type === "res" && msg.id === "h1") {
    console.log("health:", msg.payload);
    ws.close();
  }
});

​

مثال عملي: إضافة أسلوب من البداية إلى النهاية

1. المخطط (مصدر الحقيقة)

export const SystemEchoParamsSchema = Type.Object(
  { text: NonEmptyString },
  { additionalProperties: false },
);

export const SystemEchoResultSchema = Type.Object(
  { ok: Type.Boolean(), text: NonEmptyString },
  { additionalProperties: false },
);

  SystemEchoParams: SystemEchoParamsSchema,
  SystemEchoResult: SystemEchoResultSchema,

export type SystemEchoParams = Static<typeof SystemEchoParamsSchema>;
export type SystemEchoResult = Static<typeof SystemEchoResultSchema>;

2. التحقق

export const validateSystemEchoParams = ajv.compile<SystemEchoParams>(SystemEchoParamsSchema);

3. سلوك الخادم

export const systemHandlers: GatewayRequestHandlers = {
  "system.echo": ({ params, respond }) => {
    const text = String(params.text ?? "");
    respond(true, { ok: true, text });
  },
};

4. إعادة التوليد

pnpm protocol:check

5. الاختبارات والتوثيق

​

سلوك توليد شيفرة Swift

• تعداد GatewayFrame يتضمن حالات req وres وevent وunknown
• بُنى/تعدادات حمولة قوية الأنواع
• قيم ErrorCode وGATEWAY_PROTOCOL_VERSION وGATEWAY_MIN_PROTOCOL_VERSION

​

إدارة الإصدارات والتوافق

• يوجد PROTOCOL_VERSION في packages/gateway-protocol/src/version.ts (القيمة الحالية: 4).
• ترسل البرامج العميلة minProtocol وmaxProtocol؛ ويرفض الخادم النطاقات التي لا تشمل بروتوكوله الحالي.
• تحتفظ نماذج Swift بأنواع الإطارات غير المعروفة لتجنب تعطيل البرامج العميلة الأقدم.

​

أنماط المخططات واصطلاحاتها

• تستخدم معظم الكائنات additionalProperties: false للحِمولات الصارمة.
• يمثّل NonEmptyString ‏(Type.String({ minLength: 1 })) الخيار الافتراضي للمعرّفات وأسماء الأساليب/الأحداث.
• يستخدم GatewayFrame عالي المستوى مميِّزًا على type.
• تتطلب الأساليب ذات الآثار الجانبية عادةً idempotencyKey ضمن المعاملات (مثل send وpoll وagent وchat.send).
• يقبل agent الخيار internalEvents لأجل سياق التنسيق المولَّد أثناء التشغيل (مثل تسليم اكتمال مهمة وكيل فرعي أو Cron)؛ تعامل معه كسطح API داخلي.

​

ملف JSON المباشر للمخطط

• https://raw.githubusercontent.com/openclaw/openclaw/main/dist/protocol.schema.json

​

عند تغيير المخططات

1. حدّث مخططات TypeBox في وحدة packages/gateway-protocol/src/schema/*.ts المالكة وسجّلها في protocol-schemas.ts.
2. سجّل الأسلوب/الحدث في src/gateway/server-methods-list.ts.
3. حدّث src/gateway/method-scopes.ts عندما يحتاج إجراء RPC الجديد إلى تصنيف نطاق المشغّل أو العُقدة.
4. شغّل pnpm protocol:check.
5. ضمّن نماذج Swift المعاد توليدها في المستودع.

​

ذو صلة

• بروتوكول المخرجات الغنية
• مهايئات RPC