adp-openclaw 0.0.2

package/WEBSOCKET_PROTOCOL.md

@@ -0,0 +1,506 @@
+# ADP-OpenCraw WebSocket 协议文档
+
+## 📋 概述
+
+本文档描述了 adp-opencraw 项目中插件端（TypeScript）与 Go Server 之间的 WebSocket 通信协议和 Key 验证机制。
+
+## 🏗️ 架构概览
+
+```
+┌─────────────────┐                         ┌──────────────────┐
+│                 │   WebSocket (双向通信)   │                  │
+│   插件端        │ ◀════════════════════▶ │   Go Server      │
+│  (TypeScript)   │                         │                  │
+│                 │                         │                  │
+└─────────────────┘                         └──────────────────┘
+        │                                           │
+        │                                           │
+        ▼                                           ▼
+  ┌───────────┐                             ┌─────────────┐
+  │  OpenClaw │                             │  用户消息   │
+  │  Runtime  │                             │  HTTP接口   │
+  └───────────┘                             └─────────────┘
+```
+
+---
+
+## 🔐 Key 验证流程
+
+### 1. Token 类型
+
+| Token 类型 | 用途 | 生成方式 | 长度 |
+|-----------|------|---------|------|
+| **Admin Token** | 管理员操作（注册客户端） | 启动时生成或 `--admin-token` 指定 | 64 字符 hex |
+| **Client Token** | 客户端 WebSocket 认证 | 注册客户端时自动生成 | 64 字符 hex |
+
+### 2. Token 生成算法
+
+```go
+// 生成 32 字节随机数，转换为 64 字符的十六进制字符串
+func generateToken() string {
+    bytes := make([]byte, 32)
+    rand.Read(bytes)
+    return hex.EncodeToString(bytes)
+}
+```
+
+### 3. WebSocket 认证流程
+
+```
+┌──────────┐                              ┌──────────┐
+│  Client  │                              │  Server  │
+└────┬─────┘                              └────┬─────┘
+     │                                         │
+     │  1. 建立 WebSocket 连接                  │
+     │ ─────────────────────────────────────▶ │
+     │                                         │
+     │  2. 发送 Auth 消息 (30秒超时)            │
+     │ ─────────────────────────────────────▶ │
+     │  {                                      │
+     │    type: "auth",                        │
+     │    payload: {                           │
+     │      token: "client_api_token",         │
+     │      nonce: "random_nonce",             │  3. 验证 Token
+     │      signature: "hmac_sha256"           │     验证签名
+     │    }                                    │
+     │  }                                      │
+     │                                         │
+     │  4. 返回认证结果                         │
+     │ ◀───────────────────────────────────── │
+     │  {                                      │
+     │    type: "auth_result",                 │
+     │    payload: {                           │
+     │      success: true,                     │
+     │      clientId: "client-xxx",            │
+     │      message: "Authentication ok"       │
+     │    }                                    │
+     │  }                                      │
+     │                                         │
+     │  5. 开始双向消息通信                     │
+     │ ◀════════════════════════════════════▶ │
+     │                                         │
+```
+
+### 4. 签名验证（可选增强安全）
+
+```typescript
+// 客户端生成签名
+function generateSignature(token: string, nonce: string): string {
+  return crypto.createHash("sha256")
+    .update(`${token}:${nonce}`)
+    .digest("hex");
+}
+
+// 示例
+const token = "92527c1a...";
+const nonce = "abc123def456";
+const signature = sha256(token + ":" + nonce);
+```
+
+```go
+// 服务端验证签名
+func verifySignature(token, nonce, signature string) bool {
+    h := sha256.New()
+    h.Write([]byte(token + ":" + nonce))
+    expected := hex.EncodeToString(h.Sum(nil))
+    return expected == signature
+}
+```
+
+---
+
+## 📡 WebSocket 消息协议
+
+### 基础消息格式
+
+所有 WebSocket 消息都遵循统一的 JSON 格式：
+
+```typescript
+interface WSMessage {
+  type: string;           // 消息类型
+  requestId?: string;     // 请求ID（用于关联请求/响应）
+  payload?: any;          // 消息载荷
+  timestamp: number;      // Unix毫秒时间戳
+}
+```
+
+### 消息类型一览
+
+| 类型 | 方向 | 说明 |
+|------|------|------|
+| `auth` | Client → Server | 认证请求 |
+| `auth_result` | Server → Client | 认证结果 |
+| `ping` | Client → Server | 心跳请求 |
+| `pong` | Server → Client | 心跳响应 |
+| `inbound` | Server → Client | 用户消息推送 |
+| `outbound` | Client → Server | Bot 回复消息 |
+| `ack` | Server → Client | 消息确认 |
+| `error` | Server → Client | 错误消息 |
+| `conv_history` | Client → Server | 请求会话历史 |
+| `conv_response` | Server → Client | 会话历史响应 |
+
+---
+
+### 详细消息格式
+
+#### 1. 认证请求 (auth)
+
+**方向**: Client → Server
+
+```json
+{
+  "type": "auth",
+  "requestId": "req-1706951234567-abc123",
+  "payload": {
+    "token": "92527c1a861bb50bd1acc47180ef317369e97529c7a5491b2bc67839992cfbb8",
+    "nonce": "a1b2c3d4e5f6",
+    "signature": "sha256_hash_of_token_colon_nonce"
+  },
+  "timestamp": 1706951234567
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `token` | string | ✅ | 客户端 API Token |
+| `nonce` | string | ❌ | 随机数（用于签名） |
+| `signature` | string | ❌ | HMAC-SHA256 签名 |
+
+#### 2. 认证结果 (auth_result)
+
+**方向**: Server → Client
+
+```json
+{
+  "type": "auth_result",
+  "requestId": "req-1706951234567-abc123",
+  "payload": {
+    "success": true,
+    "clientId": "client-abc123def456",
+    "message": "Authentication successful"
+  },
+  "timestamp": 1706951234890
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `success` | boolean | 认证是否成功 |
+| `clientId` | string | 分配的客户端ID |
+| `message` | string | 状态消息 |
+
+#### 3. 心跳 (ping/pong)
+
+**ping** (Client → Server):
+```json
+{
+  "type": "ping",
+  "requestId": "req-1706951234567-xyz",
+  "timestamp": 1706951234567
+}
+```
+
+**pong** (Server → Client):
+```json
+{
+  "type": "pong",
+  "requestId": "req-1706951234567-xyz",
+  "timestamp": 1706951234890
+}
+```
+
+> 💡 建议心跳间隔：25-30 秒
+
+#### 4. 用户消息推送 (inbound)
+
+**方向**: Server → Client
+
+当有用户发送消息时，服务器实时推送给对应客户端：
+
+```json
+{
+  "type": "inbound",
+  "payload": {
+    "id": "msg-1",
+    "conversationId": "conv-abc123def456",
+    "clientId": "client-xyz789",
+    "from": "user123",
+    "to": "bot",
+    "text": "Hello, how are you?",
+    "timestamp": 1706951234567
+  },
+  "timestamp": 1706951234567
+}
+```
+
+#### 5. Bot 回复消息 (outbound)
+
+**方向**: Client → Server
+
+```json
+{
+  "type": "outbound",
+  "requestId": "req-1706951235000-reply",
+  "payload": {
+    "to": "user123",
+    "text": "I'm doing great! How can I help you today?",
+    "conversationId": "conv-abc123def456"
+  },
+  "timestamp": 1706951235000
+}
+```
+
+#### 6. 消息确认 (ack)
+
+**方向**: Server → Client
+
+```json
+{
+  "type": "ack",
+  "requestId": "req-1706951235000-reply",
+  "payload": {
+    "ok": true,
+    "message": {
+      "id": "msg-2",
+      "conversationId": "conv-abc123def456",
+      "clientId": "client-xyz789",
+      "from": "bot",
+      "to": "user123",
+      "text": "I'm doing great! How can I help you today?",
+      "timestamp": 1706951235123
+    }
+  },
+  "timestamp": 1706951235123
+}
+```
+
+#### 7. 错误消息 (error)
+
+**方向**: Server → Client
+
+```json
+{
+  "type": "error",
+  "requestId": "req-xxx",
+  "payload": {
+    "error": "invalid_payload",
+    "message": "Missing required field: conversationId"
+  },
+  "timestamp": 1706951235000
+}
+```
+
+常见错误码：
+
+| 错误码 | 说明 |
+|--------|------|
+| `auth_timeout` | 认证超时（30秒内未发送auth） |
+| `invalid_auth` | 首条消息不是auth类型 |
+| `invalid_token` | Token 无效 |
+| `invalid_signature` | 签名验证失败 |
+| `invalid_payload` | 消息载荷格式错误 |
+| `not_found` | 资源不存在 |
+
+#### 8. 会话历史请求/响应
+
+**请求** (Client → Server):
+```json
+{
+  "type": "conv_history",
+  "requestId": "req-1706951236000-hist",
+  "payload": {
+    "conversationId": "conv-abc123def456"
+  },
+  "timestamp": 1706951236000
+}
+```
+
+**响应** (Server → Client):
+```json
+{
+  "type": "conv_response",
+  "requestId": "req-1706951236000-hist",
+  "payload": {
+    "id": "conv-abc123def456",
+    "userId": "user123",
+    "clientId": "client-xyz789",
+    "messages": [
+      {"id": "msg-1", "from": "user123", "text": "Hello", ...},
+      {"id": "msg-2", "from": "bot", "text": "Hi there!", ...}
+    ],
+    "createdAt": 1706951234000,
+    "updatedAt": 1706951235123
+  },
+  "timestamp": 1706951236123
+}
+```
+
+---
+
+## 📊 数据结构
+
+### Message（消息）
+
+```typescript
+interface Message {
+  id: string;             // 消息ID，格式: "msg-{序号}"
+  conversationId: string; // 会话ID，格式: "conv-{随机hex}"
+  clientId: string;       // 客户端ID，格式: "client-{随机hex}"
+  from: string;           // 发送者
+  to: string;             // 接收者
+  text: string;           // 消息内容
+  timestamp: number;      // Unix毫秒时间戳
+}
+```
+
+### Conversation（会话）
+
+```typescript
+interface Conversation {
+  id: string;        // 会话ID
+  userId: string;    // 用户ID
+  clientId: string;  // 分配的客户端ID
+  messages: Message[];
+  createdAt: number;
+  updatedAt: number;
+}
+```
+
+---
+
+## 🌐 HTTP API（保留）
+
+以下 HTTP 接口仍然可用：
+
+### 公共端点
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/health` | 健康检查 |
+| POST | `/inbound` | 模拟用户发送消息（会通过 WS 推送） |
+| GET | `/outbox` | 查看已发送的消息 |
+
+### 管理端点（需 Admin Token）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/clients` | 注册新客户端 |
+| GET | `/clients` | 列出所有客户端 |
+| GET | `/conversations` | 列出所有会话 |
+
+---
+
+## 🔄 完整通信流程
+
+```
+┌─────────────┐      POST /inbound       ┌──────────────┐      WebSocket        ┌─────────────┐
+│   用户端    │ ──────────────────────▶ │  Go Server   │ ═══════════════════▶ │  插件端     │
+│  (浏览器)   │                         │              │                       │ (OpenClaw)  │
+└─────────────┘                         │              │                       │             │
+                                        │   实时推送   │                       │             │
+                                        │  inbound     │                       │  处理消息   │
+                                        │              │ ◀═══════════════════ │             │
+                                        │              │      outbound         │             │
+                                        │              │                       │             │
+                                        │   返回 ack   │ ═══════════════════▶ │             │
+                                        └──────────────┘                       └─────────────┘
+```
+
+---
+
+## 🛠️ 配置示例
+
+### 插件端配置
+
+```typescript
+{
+  serverUrl: "http://localhost:9876",  // 会自动转换为 ws://localhost:9876/ws
+  apiToken: "your_client_token_here",
+  pollIntervalMs: 3000  // 作为重连延迟使用
+}
+```
+
+### 环境变量
+
+```bash
+SIMPLEGO_SERVER_URL=http://localhost:9876
+SIMPLEGO_API_TOKEN=your_client_token
+```
+
+---
+
+## 🚀 启动服务
+
+### Go Server
+
+```bash
+cd server
+
+# 安装依赖
+go mod tidy
+
+# 启动服务
+go run main.go -port 9876 -admin-token "your_admin_token"
+
+# 如果不指定 admin-token，会自动生成并打印到控制台
+```
+
+### 注册客户端
+
+```bash
+# 使用 admin token 注册新客户端
+curl -X POST http://localhost:9876/clients \
+  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "OpenClaw-Client-1"}'
+
+# 返回示例：
+# {
+#   "clientId": "client-abc123",
+#   "token": "92527c1a861bb50bd1acc47180ef317369e97529c7a5491b2bc67839992cfbb8",
+#   "name": "OpenClaw-Client-1"
+# }
+```
+
+---
+
+## 📝 最佳实践
+
+### 1. 连接管理
+
+- 连接断开后自动重连（建议延迟 3-5 秒）
+- 使用心跳保持连接活跃（25-30 秒间隔）
+- 处理认证超时（30 秒内必须完成认证）
+
+### 2. 安全建议
+
+- 生产环境使用 WSS（WebSocket Secure）
+- 启用签名验证增强安全性
+- 定期轮换 Token
+
+### 3. 错误处理
+
+- 监听 `error` 类型消息
+- 使用 `requestId` 关联请求和响应
+- 记录所有错误日志用于排查
+
+---
+
+## 📋 检查清单
+
+- [ ] Go Server 启动并打印 admin token
+- [ ] 使用 admin token 注册客户端获取 client token
+- [ ] 插件配置正确的 serverUrl 和 apiToken
+- [ ] WebSocket 连接成功建立
+- [ ] 认证流程通过
+- [ ] 心跳保持连接活跃
+- [ ] 消息收发正常
+
+---
+
+## 📚 版本历史
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 0.0.2 | 2026-02-05 | 升级为 WebSocket 协议 |
+| 0.0.1 | - | 初始 HTTP 轮询版本 |

package/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { simpleGoPlugin } from "./src/channel.js";
+import { setSimpleGoRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "simplego",
+  name: "Simple Go",
+  description: "Demo channel plugin backed by a Go HTTP server",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setSimpleGoRuntime(api.runtime);
+    api.registerChannel({ plugin: simpleGoPlugin });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,22 @@
+{
+  "id": "simplego",
+  "name": "@openclaw/simplego",
+  "version": "0.0.1",
+  "description": "OpenClaw demo channel plugin (Go HTTP backend)",
+  "configSchema": {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": false
+  },
+  "extensions": [
+    "./index.ts"
+  ],
+  "channel": {
+    "id": "simplego",
+    "label": "Simple Go",
+    "selectionLabel": "Simple Go (demo)",
+    "docsPath": "/channels/simplego",
+    "blurb": "demo channel backed by a Go HTTP server.",
+    "order": 999
+  }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "adp-openclaw",
+  "version": "0.0.2",
+  "description": "OpenClaw demo channel plugin (Go WebSocket backend)",
+  "type": "module",
+  "dependencies": {
+    "ws": "^8.16.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.10"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "adp",
+      "label": "Simple Go",
+      "selectionLabel": "Simple Go (demo)",
+      "docsPath": "/channels/adp",
+      "blurb": "demo channel backed by a Go HTTP server.",
+      "order": 999
+    }
+  }
+}

package/server/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(go run:*)",
+      "Bash(apt-get:*)",
+      "Bash(apt-get install:*)",
+      "Bash(yum install:*)",
+      "Bash(go version:*)",
+      "Bash(curl -OL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz)",
+      "Bash(sudo rm -rf /usr/local/go)",
+      "Bash(sudo tar -C /usr/local -xzf go1.22.0.linux-amd64.tar.gz)",
+      "Bash(export PATH=$PATH:/usr/local/go/bin)",
+      "Bash(~/.bashrc)"
+    ]
+  }
+}

package/server/go.mod

@@ -0,0 +1,5 @@
+module simplego
+
+go 1.21
+
+require github.com/gorilla/websocket v1.5.1