adp-openclaw 0.0.2 → 0.0.4

package/WEBSOCKET_PROTOCOL.md

@@ -1,506 +0,0 @@
-# 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/server/.claude/settings.local.json

@@ -1,16 +0,0 @@
-{
-  "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

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