@ynhcj/xiaoyi 0.0.1-beta

package/README.md

@@ -0,0 +1,207 @@
+# @ynhcj/xiaoyichannel
+
+XiaoYi channel plugin for OpenClaw with A2A protocol support.
+
+## Features
+
+- WebSocket-based connection to XiaoYi servers
+- AK/SK authentication mechanism
+- A2A (Agent-to-Agent) message protocol support
+- Automatic reconnection with exponential backoff
+- Heartbeat mechanism for connection health monitoring
+- Full integration with OpenClaw's message routing and session management
+
+## Installation
+
+Install the plugin in your OpenClaw project:
+
+```bash
+openclaw plugins install @ynhcj/xiaoyichannel@1.0.0
+```
+
+## Configuration
+
+After installation, add the XiaoYi channel configuration to your `openclaw.json` (or `.openclawd.json`):
+
+```json
+{
+  "channels": {
+    "xiaoyi": {
+      "enabled": true,
+      "accounts": {
+        "default": {
+          "enabled": true,
+          "wsUrl": "wss://hag.com/ws/link",
+          "ak": "your-access-key",
+          "sk": "your-secret-key",
+          "agentId": "your-agent-id"
+        }
+      }
+    }
+  },
+  "agents": {
+    "bindings": [
+      {
+        "agentId": "main",
+        "match": {
+          "channel": "xiaoyi",
+          "accountId": "default"
+        }
+      }
+    ]
+  }
+}
+```
+
+### Configuration Parameters
+
+- `wsUrl`: WebSocket server URL (e.g., `wss://hag.com/ws/link`)
+- `ak`: Access Key for authentication
+- `sk`: Secret Key for authentication
+- `agentId`: Your agent identifier
+
+### Multiple Accounts
+
+You can configure multiple XiaoYi accounts:
+
+```json
+{
+  "channels": {
+    "xiaoyi": {
+      "enabled": true,
+      "accounts": {
+        "account1": {
+          "enabled": true,
+          "wsUrl": "wss://hag.com/ws/link",
+          "ak": "ak1",
+          "sk": "sk1",
+          "agentId": "agent1"
+        },
+        "account2": {
+          "enabled": true,
+          "wsUrl": "wss://hag.com/ws/link",
+          "ak": "ak2",
+          "sk": "sk2",
+          "agentId": "agent2"
+        }
+      }
+    }
+  }
+}
+```
+
+## A2A Protocol
+
+This plugin implements the A2A (Agent-to-Agent) message protocol as specified in the [Huawei Message Stream documentation](https://developer.huawei.com/consumer/cn/doc/service/message-stream-0000002505761434).
+
+### Message Structure
+
+**Incoming Request Message:**
+```json
+{
+  "sessionId": "session-123",
+  "messageId": "msg-456",
+  "timestamp": 1234567890,
+  "sender": {
+    "id": "user-id",
+    "name": "User Name",
+    "type": "user"
+  },
+  "content": {
+    "type": "text",
+    "text": "Hello, agent!"
+  }
+}
+```
+
+**Outgoing Response Message:**
+```json
+{
+  "sessionId": "session-123",
+  "messageId": "msg-789",
+  "timestamp": 1234567891,
+  "agentId": "your-agent-id",
+  "sender": {
+    "id": "your-agent-id",
+    "name": "OpenClaw Agent",
+    "type": "agent"
+  },
+  "content": {
+    "type": "text",
+    "text": "Hello! How can I help you?"
+  },
+  "status": "success"
+}
+```
+
+## Authentication
+
+The plugin uses AK/SK authentication as specified in the [Huawei Push Message documentation](https://developer.huawei.com/consumer/cn/doc/service/pushmessage-0000002505761436).
+
+The authentication signature is generated using HMAC-SHA256:
+
+```
+signature = HMAC-SHA256(SK, "ak={AK}&timestamp={TIMESTAMP}")
+```
+
+## Connection Management
+
+The plugin automatically manages WebSocket connections with the following features:
+
+- **Automatic Reconnection**: Reconnects automatically on connection loss with exponential backoff
+- **Heartbeat Monitoring**: Sends ping messages every 30 seconds to keep the connection alive
+- **Connection Health**: Monitors connection status and reports health via OpenClaw's status system
+- **Max Retry Limit**: Stops reconnection attempts after 10 failed attempts
+
+## Session Management
+
+The plugin integrates with OpenClaw's session management system:
+
+- Sessions are scoped by `sessionId` from incoming A2A messages
+- Each conversation maintains its own session context
+- Session keys are automatically generated based on OpenClaw's configuration
+
+## Usage
+
+Once configured, the plugin will:
+
+1. Automatically connect to the XiaoYi WebSocket server on startup
+2. Authenticate using the provided AK/SK credentials
+3. Receive incoming messages via WebSocket
+4. Route messages to the appropriate OpenClaw agent
+5. Send agent responses back through the WebSocket connection
+
+## Troubleshooting
+
+### Connection Issues
+
+Check the OpenClaw logs for connection status:
+
+```bash
+openclaw logs
+```
+
+### Authentication Failures
+
+Verify your AK/SK credentials are correct and have the necessary permissions.
+
+### Message Delivery
+
+Ensure your `agentId` is correctly configured and matches your XiaoYi account settings.
+
+## Development
+
+To build the plugin from source:
+
+```bash
+npm install
+npm run build
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, please visit the [GitHub repository](https://github.com/ynhcj/xiaoyichannel).

package/dist/auth.d.ts

@@ -0,0 +1,36 @@
+import { AuthCredentials } from "./types.js";
+/**
+ * Generate authentication signature using AK/SK mechanism
+ * Based on: https://developer.huawei.com/consumer/cn/doc/service/pushmessage-0000002505761436
+ *
+ * Signature format: Base64(HMAC-SHA256(secretKey, ts))
+ */
+export declare class XiaoYiAuth {
+    private ak;
+    private sk;
+    private agentId;
+    constructor(ak: string, sk: string, agentId: string);
+    /**
+     * Generate authentication credentials with signature
+     */
+    generateAuthCredentials(): AuthCredentials;
+    /**
+     * Generate HMAC-SHA256 signature
+     * Format: Base64(HMAC-SHA256(secretKey, ts))
+     * Reference: https://developer.huawei.com/consumer/cn/doc/service/pushmessage-0000002505761436
+     * @param timestamp - Timestamp as string (e.g., "1514764800000")
+     */
+    private generateSignature;
+    /**
+     * Verify if credentials are valid
+     */
+    verifyCredentials(credentials: AuthCredentials): boolean;
+    /**
+     * Generate authentication headers for WebSocket connection
+     */
+    generateAuthHeaders(): Record<string, string>;
+    /**
+     * Generate authentication message for WebSocket (legacy, kept for compatibility)
+     */
+    generateAuthMessage(): any;
+}

package/dist/auth.js

@@ -0,0 +1,111 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XiaoYiAuth = void 0;
+const crypto = __importStar(require("crypto"));
+/**
+ * Generate authentication signature using AK/SK mechanism
+ * Based on: https://developer.huawei.com/consumer/cn/doc/service/pushmessage-0000002505761436
+ *
+ * Signature format: Base64(HMAC-SHA256(secretKey, ts))
+ */
+class XiaoYiAuth {
+    constructor(ak, sk, agentId) {
+        this.ak = ak;
+        this.sk = sk;
+        this.agentId = agentId;
+    }
+    /**
+     * Generate authentication credentials with signature
+     */
+    generateAuthCredentials() {
+        const timestamp = Date.now();
+        const signature = this.generateSignature(timestamp.toString());
+        return {
+            ak: this.ak,
+            sk: this.sk,
+            timestamp,
+            signature,
+        };
+    }
+    /**
+     * Generate HMAC-SHA256 signature
+     * Format: Base64(HMAC-SHA256(secretKey, ts))
+     * Reference: https://developer.huawei.com/consumer/cn/doc/service/pushmessage-0000002505761436
+     * @param timestamp - Timestamp as string (e.g., "1514764800000")
+     */
+    generateSignature(timestamp) {
+        // HMAC-SHA256(secretKey, ts)
+        const hmac = crypto.createHmac("sha256", this.sk);
+        hmac.update(timestamp);
+        const digest = hmac.digest();
+        // Base64 encode
+        return digest.toString("base64");
+    }
+    /**
+     * Verify if credentials are valid
+     */
+    verifyCredentials(credentials) {
+        const expectedSignature = this.generateSignature(credentials.timestamp.toString());
+        return credentials.signature === expectedSignature;
+    }
+    /**
+     * Generate authentication headers for WebSocket connection
+     */
+    generateAuthHeaders() {
+        const timestamp = Date.now();
+        const signature = this.generateSignature(timestamp.toString());
+        return {
+            "x-access-key": this.ak,
+            "x-sign": signature,
+            "x-ts": timestamp.toString(),
+            "x-agent-id": this.agentId,
+        };
+    }
+    /**
+     * Generate authentication message for WebSocket (legacy, kept for compatibility)
+     */
+    generateAuthMessage() {
+        const credentials = this.generateAuthCredentials();
+        return {
+            type: "auth",
+            ak: credentials.ak,
+            agentId: this.agentId,
+            timestamp: credentials.timestamp,
+            signature: credentials.signature,
+        };
+    }
+}
+exports.XiaoYiAuth = XiaoYiAuth;

package/dist/channel.d.ts

@@ -0,0 +1,189 @@
+import type { ChannelOutboundContext, ChannelGatewayContext, OpenClawConfig } from "openclaw/dist/plugin-sdk/index.js";
+type OutboundDeliveryResult = {
+    channel: string;
+    messageId: string;
+    chatId?: string;
+    channelId?: string;
+    roomId?: string;
+    conversationId?: string;
+    timestamp?: number;
+    meta?: Record<string, unknown>;
+};
+import { XiaoYiChannelConfig } from "./types.js";
+/**
+ * Resolved XiaoYi account configuration (single account mode)
+ */
+export interface ResolvedXiaoYiAccount {
+    accountId: string;
+    config: XiaoYiChannelConfig;
+}
+/**
+ * XiaoYi Channel Plugin
+ * Implements OpenClaw ChannelPlugin interface for XiaoYi A2A protocol
+ * Single account mode only
+ */
+export declare const xiaoyiPlugin: {
+    id: string;
+    meta: {
+        id: string;
+        label: string;
+        selectionLabel: string;
+        docsPath: string;
+        blurb: string;
+        aliases: string[];
+    };
+    capabilities: {
+        chatTypes: string[];
+        polls: boolean;
+        reactions: boolean;
+        threads: boolean;
+        media: boolean;
+        nativeCommands: boolean;
+    };
+    /**
+     * Config schema for UI form rendering
+     */
+    configSchema: {
+        schema: {
+            type: string;
+            properties: {
+                enabled: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+                wsUrl1: {
+                    type: string;
+                    default: string;
+                    description: string;
+                };
+                wsUrl2: {
+                    type: string;
+                    default: string;
+                    description: string;
+                };
+                ak: {
+                    type: string;
+                    description: string;
+                };
+                sk: {
+                    type: string;
+                    description: string;
+                };
+                agentId: {
+                    type: string;
+                    description: string;
+                };
+                debug: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+                apiId: {
+                    type: string;
+                    default: string;
+                    description: string;
+                };
+                pushId: {
+                    type: string;
+                    default: string;
+                    description: string;
+                };
+                taskTimeoutMs: {
+                    type: string;
+                    default: number;
+                    description: string;
+                };
+            };
+        };
+    };
+    onboarding: any;
+    /**
+     * Config adapter - single account mode
+     */
+    config: {
+        listAccountIds: (cfg: OpenClawConfig) => string[];
+        resolveAccount: (cfg: OpenClawConfig, accountId?: string | null) => {
+            accountId: string;
+            config: XiaoYiChannelConfig;
+            enabled: boolean;
+        };
+        defaultAccountId: (cfg: OpenClawConfig) => string;
+        isConfigured: (account: any, cfg: OpenClawConfig) => boolean;
+        isEnabled: (account: any, cfg: OpenClawConfig) => boolean;
+        disabledReason: (account: any, cfg: OpenClawConfig) => string;
+        unconfiguredReason: (account: any, cfg: OpenClawConfig) => string;
+        describeAccount: (account: any, cfg: OpenClawConfig) => {
+            accountId: any;
+            name: string;
+            enabled: any;
+            configured: boolean;
+        };
+    };
+    /**
+     * Gateway adapter - manage connections
+     * Using xy-monitor for message handling (xy_channel architecture)
+     */
+    gateway: {
+        startAccount: (ctx: ChannelGatewayContext<ResolvedXiaoYiAccount>) => Promise<void>;
+        stopAccount: (ctx: ChannelGatewayContext<ResolvedXiaoYiAccount>) => Promise<void>;
+    };
+    /**
+     * Outbound adapter - send messages via push
+     */
+    outbound: {
+        deliveryMode: string;
+        textChunkLimit: number;
+        resolveTarget: ({ cfg, to, accountId, mode }: any) => {
+            ok: boolean;
+            to: any;
+        };
+        sendText: (ctx: ChannelOutboundContext) => Promise<OutboundDeliveryResult>;
+        sendMedia: (ctx: ChannelOutboundContext) => Promise<OutboundDeliveryResult>;
+    };
+    /**
+     * Messaging adapter - normalize targets
+     * In new openclaw version, normalizeTarget receives a string and returns a normalized string
+     */
+    messaging: {
+        normalizeTarget: (raw: string) => string;
+    };
+    /**
+     * Status adapter - health checks
+     * Using buildAccountSnapshot for compatibility with new openclaw version
+     */
+    status: {
+        buildAccountSnapshot: (params: {
+            account: ResolvedXiaoYiAccount;
+            cfg: OpenClawConfig;
+            runtime?: any;
+            probe?: unknown;
+            audit?: unknown;
+        }) => Promise<{
+            accountId: string;
+            state: "offline";
+            lastEventAt: number;
+            issues: {
+                severity: "error";
+                message: string;
+            }[];
+            lastInboundAt?: undefined;
+        } | {
+            accountId: string;
+            state: "ready";
+            lastEventAt: number;
+            lastInboundAt: number;
+            issues?: undefined;
+        } | {
+            accountId: string;
+            state: "authenticating";
+            lastEventAt: number;
+            issues: {
+                severity: "warning";
+                message: string;
+            }[];
+            lastInboundAt?: undefined;
+        }>;
+    };
+};
+export {};