@ynhcj/xiaoyi 1.0.1 → 1.2.0

package/README.md

@@ -1,198 +1,202 @@
-# @openclaw/xiaoyi
+# @ynhcj/xiaoyichannel
 
-Openclaw Xiaoyi channel plugin - Huawei A2A (Agent-to-Agent) protocol integration via WebSocket.
-
-## Overview
-
-This plugin enables Openclaw to communicate with Huawei's A2A Gateway service, allowing AI agents to send and receive messages through Huawei's messaging infrastructure.
+XiaoYi channel plugin for OpenClaw with A2A protocol support.
 
 ## Features
 
-- **WebSocket Connection**: Persistent WebSocket connection to `wss://xiaoyi.com/ws/link`
-- **Auto-Reconnection**: Automatic reconnection with exponential backoff
-- **AK/SK Authentication**: Huawei Cloud Access Key/Secret Key authentication
-- **A2A Protocol**: Full support for Huawei's A2A message protocol
-- **Session Management**: Automatic session tracking and continuity
-- **Media Support**: Text and media message handling
+- 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
-npm install @openclaw/xiaoyi
+openclaw plugins install @ynhcj/xiaoyichannel@1.0.0
 ```
 
 ## Configuration
 
-Add the following to your Openclaw configuration file:
-
-```yaml
-channels:
-  xiaoyi:
-    enabled: true
-    # Huawei Cloud credentials
-    accessKeyId: "your-access-key-id"
-    secretAccessKey: "your-secret-access-key"
-    projectId: "your-project-id"
-    # Optional settings
-    serverUrl: "wss://xiaoyi.com/ws/link"  # Default: wss://xiaoyi.com/ws/link
-    agentId: "openclaw"                     # Default: openclaw
-    proxy: ""                               # Optional proxy URL
-
-    # Multiple accounts support
-    accounts:
-      account1:
-        enabled: true
-        accessKeyId: "account1-key-id"
-        secretAccessKey: "account1-secret"
-        projectId: "account1-project"
-        agentId: "openclaw-account1"
+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 via Environment Variables
+### Configuration Parameters
 
-```bash
-export XIAOYI_ACCESS_KEY_ID="your-access-key-id"
-export XIAOYI_SECRET_ACCESS_KEY="your-secret-access-key"
-export XIAOYI_PROJECT_ID="your-project-id"
+- `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"
+        }
+      }
+    }
+  }
+}
 ```
 
-## Message Protocol
+## 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).
 
-### A2A Request Message (Incoming)
+### Message Structure
 
-```typescript
+**Incoming Request Message:**
+```json
 {
-  "header": {
-    "messageId": "msg_1234567890_abc123",
-    "sessionId": "session_1234567890_def456",
-    "timestamp": 1703145600000,
-    "messageType": "request",
-    "version": "1.0"
-  },
+  "sessionId": "session-123",
+  "messageId": "msg-456",
+  "timestamp": 1234567890,
   "sender": {
-    "id": "user123",
-    "name": "John Doe",
+    "id": "user-id",
+    "name": "User Name",
     "type": "user"
   },
-  "receiver": {
-    "id": "openclaw",
-    "type": "agent"
-  },
   "content": {
-    "contentType": "text",
-    "text": "Hello, how can you help me?"
-  },
-  "context": {
-    "chatType": "direct"
+    "type": "text",
+    "text": "Hello, agent!"
   }
 }
 ```
 
-### A2A Response Message (Outgoing)
-
-```typescript
+**Outgoing Response Message:**
+```json
 {
-  "header": {
-    "messageId": "msg_1234567890_xyz789",
-    "sessionId": "session_1234567890_def456",
-    "timestamp": 1703145601000,
-    "messageType": "response",
-    "version": "1.0"
-  },
+  "sessionId": "session-123",
+  "messageId": "msg-789",
+  "timestamp": 1234567891,
+  "agentId": "your-agent-id",
   "sender": {
-    "id": "openclaw",
-    "name": "Openclaw Agent",
+    "id": "your-agent-id",
+    "name": "OpenClaw Agent",
     "type": "agent"
   },
-  "receiver": {
-    "id": "user123",
-    "type": "user"
-  },
   "content": {
-    "contentType": "text",
-    "text": "I'm here to help! What do you need?"
-  },
-  "status": {
-    "code": 200,
-    "message": "OK"
+    "type": "text",
+    "text": "Hello! How can I help you?"
   },
-  // Top-level fields for routing
-  "agentId": "openclaw",
-  "sessionId": "session_1234567890_def456"
+  "status": "success"
 }
 ```
 
 ## Authentication
 
-The plugin uses Huawei Cloud's AK/SK authentication mechanism:
+The plugin uses AK/SK authentication as specified in the [Huawei Push Message documentation](https://developer.huawei.com/consumer/cn/doc/service/pushmessage-0000002505761436).
 
-1. Generates a JWT-like token signed with the secret access key
-2. Sends an authentication message on WebSocket connection
-3. Automatically refreshes tokens before expiration
-4. Handles authentication failures with reconnection
+The authentication signature is generated using HMAC-SHA256:
 
-## Reconnection Strategy
+```
+signature = HMAC-SHA256(SK, "ak={AK}&timestamp={TIMESTAMP}")
+```
 
-- Initial delay: 1 second
-- Backoff multiplier: 1.5x
-- Maximum delay: 30 seconds
-- Maximum attempts: Unlimited (configurable)
-- Ping interval: 30 seconds
-- Pong timeout: 10 seconds
+## Connection Management
 
-## API Reference
+The plugin automatically manages WebSocket connections with the following features:
 
-### `XiaoyiWebSocketClient`
+- **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
 
-Main WebSocket client class for Xiaoyi connection.
+## Session Management
 
-```typescript
-import { createXiaoyiWebSocketClient } from '@openclaw/xiaoyi';
+The plugin integrates with OpenClaw's session management system:
 
-const client = createXiaoyiWebSocketClient({
-  serverUrl: 'wss://xiaoyi.com/ws/link',
-  credentials: {
-    accessKeyId: 'your-key',
-    secretAccessKey: 'your-secret',
-    projectId: 'your-project',
-    agentId: 'openclaw',
-  },
-  reconnect: true,
-  onMessage: (message) => console.log('Received:', message),
-  onStateChange: (status) => console.log('Status:', status.state),
-});
+- 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
 
-await client.connect();
-```
+## Usage
 
-### Message Handlers
-
-```typescript
-import {
-  createOutgoingMessage,
-  a2aToOpenclaw,
-  openclawToA2A,
-  validateA2ARequest,
-} from '@openclaw/xiaoyi';
-
-// Create outgoing message
-const outgoing = createOutgoingMessage({
-  to: 'user123',
-  text: 'Hello!',
-  sessionId: 'session_123',
-  agentId: 'openclaw',
-});
-
-// Validate incoming message
-if (validateA2ARequest(incoming)) {
-  const openclawMsg = a2aToOpenclaw(incoming, 'default', 'openclaw');
-}
+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
 ```
 
-## References
+### Authentication Failures
+
+Verify your AK/SK credentials are correct and have the necessary permissions.
+
+### Message Delivery
 
-- [Huawei Push Message Service](https://developer.huawei.com/consumer/cn/doc/service/pushmessage-0000002505761436)
-- [Huawei Message Stream (A2A Protocol)](https://developer.huawei.com/consumer/cn/doc/service/message-stream-0000002505761434)
+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
 
@@ -200,6 +204,4 @@ MIT
 
 ## Support
 
-For issues and questions:
-- GitHub Issues: [openclaw/xiaoyi-channel](https://github.com/openclaw/xiaoyi-channel/issues)
-- Openclaw Discord: [Join our server](https://discord.gg/openclaw)
+For issues and questions, please visit the [GitHub repository](https://github.com/ynhcj/xiaoyichannel).

package/dist/auth.d.ts

@@ -0,0 +1,27 @@
+import { AuthCredentials } from "./types";
+/**
+ * Generate authentication signature using AK/SK mechanism
+ * Based on: https://developer.huawei.com/consumer/cn/doc/service/pushmessage-0000002505761436
+ */
+export declare class XiaoYiAuth {
+    private ak;
+    private sk;
+    constructor(ak: string, sk: string);
+    /**
+     * Generate authentication credentials with signature
+     */
+    generateAuthCredentials(): AuthCredentials;
+    /**
+     * Generate HMAC-SHA256 signature
+     * Format: HMAC-SHA256(SK, "ak={AK}&timestamp={TIMESTAMP}")
+     */
+    private generateSignature;
+    /**
+     * Verify if credentials are valid
+     */
+    verifyCredentials(credentials: AuthCredentials): boolean;
+    /**
+     * Generate authentication message for WebSocket
+     */
+    generateAuthMessage(): any;
+}

package/dist/auth.js

@@ -0,0 +1,92 @@
+"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
+ */
+class XiaoYiAuth {
+    constructor(ak, sk) {
+        this.ak = ak;
+        this.sk = sk;
+    }
+    /**
+     * Generate authentication credentials with signature
+     */
+    generateAuthCredentials() {
+        const timestamp = Date.now();
+        const signature = this.generateSignature(timestamp);
+        return {
+            ak: this.ak,
+            sk: this.sk,
+            timestamp,
+            signature,
+        };
+    }
+    /**
+     * Generate HMAC-SHA256 signature
+     * Format: HMAC-SHA256(SK, "ak={AK}&timestamp={TIMESTAMP}")
+     */
+    generateSignature(timestamp) {
+        const stringToSign = `ak=${this.ak}&timestamp=${timestamp}`;
+        const hmac = crypto.createHmac("sha256", this.sk);
+        hmac.update(stringToSign);
+        return hmac.digest("hex");
+    }
+    /**
+     * Verify if credentials are valid
+     */
+    verifyCredentials(credentials) {
+        const expectedSignature = this.generateSignature(credentials.timestamp);
+        return credentials.signature === expectedSignature;
+    }
+    /**
+     * Generate authentication message for WebSocket
+     */
+    generateAuthMessage() {
+        const credentials = this.generateAuthCredentials();
+        return {
+            type: "auth",
+            data: {
+                ak: credentials.ak,
+                timestamp: credentials.timestamp,
+                signature: credentials.signature,
+            },
+        };
+    }
+}
+exports.XiaoYiAuth = XiaoYiAuth;

package/dist/channel.d.ts

@@ -0,0 +1,14 @@
+import type { ChannelPlugin } from "openclaw";
+import { XiaoYiAccountConfig } from "./types";
+/**
+ * Resolved XiaoYi account configuration
+ */
+export interface ResolvedXiaoYiAccount {
+    accountId: string;
+    config: XiaoYiAccountConfig;
+}
+/**
+ * XiaoYi Channel Plugin
+ * Implements OpenClaw ChannelPlugin interface for XiaoYi A2A protocol
+ */
+export declare const xiaoyiPlugin: ChannelPlugin<ResolvedXiaoYiAccount>;