adp-openclaw 0.0.2

package/DESIGN.md

@@ -0,0 +1,733 @@
+# Simple Go Channel Plugin - 设计文档
+
+## 1. 系统架构
+
+```mermaid
+graph TB
+    subgraph "OpenClaw Gateway"
+        PR[Plugin Registry]
+        TG[Telegram Plugin]
+        MX[Matrix Plugin]
+        SG[Simple Go Plugin]
+        RT[OpenClaw Runtime]
+    end
+
+    subgraph "Go HTTP Server :9876"
+        AUTH[Auth Middleware]
+        POLL["/poll"]
+        SEND["/send"]
+        INB["/inbound"]
+        CONV[Conversations]
+        CLIENTS[Clients Registry]
+        INQ[Inbound Queues]
+        OUTQ[Outbound Queue]
+    end
+
+    subgraph "External"
+        USER1[User 1]
+        USER2[User 2]
+        OC1[OpenClaw Client 1]
+        OC2[OpenClaw Client 2]
+    end
+
+    PR --> TG
+    PR --> MX
+    PR --> SG
+    SG --> RT
+
+    OC1 -->|Bearer Token| AUTH
+    OC2 -->|Bearer Token| AUTH
+    AUTH --> POLL
+    AUTH --> SEND
+
+    USER1 --> INB
+    USER2 --> INB
+    INB --> CONV
+    CONV --> INQ
+
+    POLL --> INQ
+    SEND --> OUTQ
+    SEND --> CONV
+```
+
+## 2. 数据结构
+
+### 2.1 Go 服务端结构体
+
+```mermaid
+classDiagram
+    class Message {
+        +string ID
+        +string ConversationID
+        +string ClientID
+        +string From
+        +string To
+        +string Text
+        +int64 Timestamp
+    }
+
+    class Conversation {
+        +string ID
+        +string UserID
+        +string ClientID
+        +[]Message Messages
+        +int64 CreatedAt
+        +int64 UpdatedAt
+    }
+
+    class Client {
+        +string ID
+        +string Token
+        +string Name
+        +int64 LastSeenAt
+    }
+
+    class Server {
+        +map~string,Client~ clients
+        +map~string,string~ tokens
+        +map~string,Conversation~ conversations
+        +map~string,[]Message~ inbound
+        +[]Message outbound
+        +string adminToken
+        +authMiddleware()
+        +adminAuth()
+        +handlePoll()
+        +handleSend()
+        +handleInbound()
+    }
+
+    Server "1" *-- "*" Client : manages
+    Server "1" *-- "*" Conversation : manages
+    Conversation "1" *-- "*" Message : contains
+```
+
+### 2.2 TypeScript 插件结构体
+
+```mermaid
+classDiagram
+    class SimpleGoConfig {
+        +channels.simplego.enabled: boolean
+        +channels.simplego.serverUrl: string
+        +channels.simplego.apiToken: string
+        +channels.simplego.pollIntervalMs: number
+    }
+
+    class ResolvedSimpleGoAccount {
+        +string accountId
+        +string name
+        +boolean enabled
+        +boolean configured
+        +string serverUrl
+        +string apiToken
+        +number pollIntervalMs
+    }
+
+    class MonitorParams {
+        +string serverUrl
+        +string apiToken
+        +number pollIntervalMs
+        +PluginRuntime runtime
+        +AbortSignal abortSignal
+        +PluginLogger log
+    }
+
+    class InboundMessage {
+        +string id
+        +string conversationId
+        +string from
+        +string text
+        +number timestamp
+    }
+
+    SimpleGoConfig --> ResolvedSimpleGoAccount : resolves to
+    ResolvedSimpleGoAccount --> MonitorParams : configures
+```
+
+## 3. HTTP API
+
+### 3.1 认证模型
+
+```mermaid
+flowchart LR
+    subgraph "Token Types"
+        AT[Admin Token]
+        CT[Client Token]
+    end
+
+    subgraph "Admin Endpoints"
+        RC["POST /clients"]
+        LC["GET /clients"]
+        LCV["GET /conversations"]
+    end
+
+    subgraph "Client Endpoints"
+        POLL["GET /poll"]
+        SEND["POST /send"]
+        GCV["GET /conversations/:id"]
+    end
+
+    subgraph "Public Endpoints"
+        INB["POST /inbound"]
+        OUT["GET /outbox"]
+        HLT["GET /health"]
+    end
+
+    AT -->|Bearer| RC
+    AT -->|Bearer| LC
+    AT -->|Bearer| LCV
+
+    CT -->|Bearer| POLL
+    CT -->|Bearer| SEND
+    CT -->|Bearer| GCV
+```
+
+### 3.2 API 请求/响应
+
+| Endpoint | Method | Auth | Request | Response |
+|----------|--------|------|---------|----------|
+| `/health` | GET | - | - | `{ok, server, clients, conversations}` |
+| `/clients` | POST | Admin | `{name}` | `{clientId, token, name}` |
+| `/clients` | GET | Admin | - | `{clients: [...]}` |
+| `/conversations` | GET | Admin | - | `{conversations: [...]}` |
+| `/poll` | GET | Client | - | `{messages: [...]}` |
+| `/send` | POST | Client | `{to, text, conversationId}` | `{ok, message}` |
+| `/conversations/:id` | GET | Client | - | `Conversation` |
+| `/inbound` | POST | - | `{from, text}` | `Message` |
+| `/outbox` | GET | - | - | `{messages: [...]}` |
+
+## 4. 时序图
+
+### 4.1 客户端注册流程
+
+```mermaid
+sequenceDiagram
+    participant Admin
+    participant Server as Go Server
+    participant DB as Server State
+
+    Admin->>Server: POST /clients {name: "client-1"}
+    Note over Admin,Server: Authorization: Bearer <admin-token>
+
+    Server->>DB: Generate clientID + token
+    Server->>DB: Store client info
+    Server->>DB: Create inbound queue
+
+    Server-->>Admin: {clientId, token, name}
+
+    Note over Admin: Save token for OpenClaw config
+```
+
+### 4.2 插件启动流程
+
+```mermaid
+sequenceDiagram
+    participant GW as Gateway
+    participant Plugin as SimpleGo Plugin
+    participant Monitor
+    participant Server as Go Server
+
+    GW->>Plugin: loadPlugins()
+    Plugin->>GW: registerChannel()
+
+    GW->>Plugin: startAccount(ctx)
+    Plugin->>Plugin: resolveAccount(cfg)
+
+    Plugin->>Monitor: monitorSimpleGo(params)
+
+    loop Poll Loop
+        Monitor->>Server: GET /poll
+        Note over Monitor,Server: Authorization: Bearer <client-token>
+        Server-->>Monitor: {messages: [...]}
+
+        alt Has Messages
+            Monitor->>GW: runtime.handleInbound()
+        end
+
+        Monitor->>Monitor: sleep(pollIntervalMs)
+    end
+```
+
+### 4.3 多轮对话流程
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Server as Go Server
+    participant OC1 as OpenClaw 1
+    participant OC2 as OpenClaw 2
+    participant AI
+
+    Note over Server: Load balancing: OC1 has 0 pending, OC2 has 2 pending
+
+    User->>Server: POST /inbound {from: "alice", text: "Hello"}
+    Server->>Server: getOrCreateConversation("alice")
+    Note over Server: Create conv-001, assign to OC1 (least busy)
+    Server->>Server: Queue message for OC1
+    Server-->>User: {id, conversationId: "conv-001"}
+
+    OC1->>Server: GET /poll
+    Server-->>OC1: {messages: [{...conversationId: "conv-001"}]}
+
+    OC1->>AI: Process message
+    AI-->>OC1: "Hi Alice!"
+
+    OC1->>Server: POST /send {to: "alice", text: "Hi!", conversationId: "conv-001"}
+    Server->>Server: Append to conv-001 history
+    Server-->>OC1: {ok: true}
+
+    Note over User,AI: === Second turn (same conversation) ===
+
+    User->>Server: POST /inbound {from: "alice", text: "How are you?"}
+    Server->>Server: Find existing conv-001 for alice
+    Note over Server: Reuse conv-001, still assigned to OC1
+    Server->>Server: Queue message for OC1
+
+    OC1->>Server: GET /poll
+    Server-->>OC1: {messages: [{...conversationId: "conv-001"}]}
+
+    OC1->>Server: GET /conversations/conv-001
+    Server-->>OC1: {messages: [msg1, msg2, msg3, ...]}
+    Note over OC1: Full conversation history available
+
+    OC1->>AI: Process with context
+    AI-->>OC1: "I'm doing great!"
+
+    OC1->>Server: POST /send {...conversationId: "conv-001"}
+```
+
+### 4.4 多客户端负载均衡
+
+```mermaid
+sequenceDiagram
+    participant U1 as User Alice
+    participant U2 as User Bob
+    participant U3 as User Carol
+    participant Server as Go Server
+    participant OC1 as OpenClaw 1
+    participant OC2 as OpenClaw 2
+
+    Note over Server: Initial state: OC1=0, OC2=0 pending
+
+    U1->>Server: POST /inbound {from: "alice"}
+    Server->>Server: Assign alice → OC1 (random tie-break)
+
+    U2->>Server: POST /inbound {from: "bob"}
+    Server->>Server: OC1=1, OC2=0 → Assign bob → OC2
+
+    U3->>Server: POST /inbound {from: "carol"}
+    Server->>Server: OC1=1, OC2=1 → Assign carol → OC1
+
+    par Parallel polling
+        OC1->>Server: GET /poll
+        Server-->>OC1: [alice msg, carol msg]
+    and
+        OC2->>Server: GET /poll
+        Server-->>OC2: [bob msg]
+    end
+
+    Note over OC1,OC2: Each client handles its assigned users
+
+    U1->>Server: POST /inbound {from: "alice", text: "follow-up"}
+    Note over Server: alice already assigned to OC1
+    Server->>Server: Queue for OC1 (sticky session)
+```
+
+## 5. 状态机
+
+### 5.1 对话生命周期
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created: User sends first message
+    Created --> Active: Client polls message
+    Active --> Active: User/Bot exchange messages
+    Active --> Idle: No activity for N minutes
+    Idle --> Active: New message received
+    Idle --> Expired: TTL exceeded
+    Expired --> [*]: Cleanup
+```
+
+### 5.2 客户端状态
+
+```mermaid
+stateDiagram-v2
+    [*] --> Registered: Admin creates client
+    Registered --> Connected: First poll received
+    Connected --> Connected: Regular polling
+    Connected --> Stale: No poll for 30s
+    Stale --> Connected: Poll received
+    Stale --> Disconnected: No poll for 5min
+    Disconnected --> Connected: Poll received
+```
+
+## 6. 组件职责
+
+| 组件 | 文件 | 职责 |
+|------|------|------|
+| **Go Server** | `server/main.go` | HTTP API, 认证, 消息路由, 会话管理 |
+| **Plugin Entry** | `index.ts` | 插件注册入口 |
+| **Channel Plugin** | `src/channel.ts` | ChannelPlugin 接口实现 |
+| **Monitor** | `src/monitor.ts` | 轮询循环, Token认证, 消息转发 |
+
+## 7. 配置示例
+
+```yaml
+# ~/.openclaw/config.yaml
+channels:
+  simplego:
+    enabled: true
+    serverUrl: "http://localhost:9876"
+    apiToken: "your-client-token-here"  # 从 POST /clients 获取
+    pollIntervalMs: 1000
+```
+
+## 8. 使用流程
+
+```mermaid
+flowchart TD
+    A[启动 Go Server] --> B[获取 Admin Token]
+    B --> C[注册 OpenClaw Client]
+    C --> D[获取 Client Token]
+    D --> E[配置 OpenClaw]
+    E --> F[启动 OpenClaw Gateway]
+    F --> G[测试发送消息]
+
+    subgraph "Admin 操作"
+        B
+        C
+    end
+
+    subgraph "Client 配置"
+        D
+        E
+        F
+    end
+```
+
+### 命令示例
+
+```bash
+# 1. 启动服务器 (会打印 admin token)
+cd server && go run main.go
+
+# 2. 注册客户端
+curl -X POST http://localhost:9876/clients \
+  -H "Authorization: Bearer <admin-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-openclaw"}'
+# 返回: {"clientId": "client-xxx", "token": "xxx", "name": "my-openclaw"}
+
+# 3. 配置 OpenClaw
+openclaw config set channels.simplego.enabled true
+openclaw config set channels.simplego.serverUrl "http://localhost:9876"
+openclaw config set channels.simplego.apiToken "<client-token>"
+
+# 4. 启动 Gateway
+openclaw gateway run
+
+# 5. 测试消息
+curl -X POST http://localhost:9876/inbound \
+  -H "Content-Type: application/json" \
+  -d '{"from": "test-user", "text": "Hello!"}'
+
+# 6. 查看响应
+curl http://localhost:9876/outbox
+```
+
+## 9. 部署流程
+
+### 9.1 部署架构
+
+```mermaid
+flowchart TB
+    subgraph "Production Environment"
+        subgraph "Server Node"
+            GO[Go Server]
+            NGINX[Nginx Reverse Proxy]
+            SYSTEMD[Systemd Service]
+        end
+
+        subgraph "Client Nodes"
+            OC1[OpenClaw Instance 1]
+            OC2[OpenClaw Instance 2]
+        end
+    end
+
+    subgraph "External"
+        USERS[Users / Webhooks]
+        DNS[DNS: api.example.com]
+    end
+
+    DNS --> NGINX
+    NGINX -->|":9876"| GO
+    USERS -->|HTTPS| NGINX
+    OC1 -->|HTTPS| NGINX
+    OC2 -->|HTTPS| NGINX
+    SYSTEMD -.->|manages| GO
+```
+
+### 9.2 Go 服务端部署
+
+#### 方式一：二进制部署
+
+```bash
+# 1. 编译
+cd server
+GOOS=linux GOARCH=amd64 go build -o simplego-server main.go
+
+# 2. 上传到服务器
+scp simplego-server user@server:/opt/simplego/
+
+# 3. 创建 systemd 服务
+cat <<'EOF' | sudo tee /etc/systemd/system/simplego.service
+[Unit]
+Description=Simple Go Channel Server
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/opt/simplego
+ExecStart=/opt/simplego/simplego-server --port 9876 --admin-token ${ADMIN_TOKEN}
+Restart=always
+RestartSec=5
+Environment=ADMIN_TOKEN=your-secure-admin-token
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+# 4. 启动服务
+sudo systemctl daemon-reload
+sudo systemctl enable simplego
+sudo systemctl start simplego
+
+# 5. 检查状态
+sudo systemctl status simplego
+journalctl -u simplego -f
+```
+
+#### 方式二：Docker 部署
+
+```dockerfile
+# Dockerfile
+FROM golang:1.21-alpine AS builder
+WORKDIR /app
+COPY server/ .
+RUN go build -o simplego-server main.go
+
+FROM alpine:latest
+RUN apk --no-cache add ca-certificates
+WORKDIR /app
+COPY --from=builder /app/simplego-server .
+EXPOSE 9876
+ENTRYPOINT ["./simplego-server"]
+CMD ["--port", "9876"]
+```
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  simplego:
+    build: .
+    ports:
+      - "9876:9876"
+    environment:
+      - ADMIN_TOKEN=${ADMIN_TOKEN}
+    command: ["--port", "9876", "--admin-token", "${ADMIN_TOKEN}"]
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://localhost:9876/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+```bash
+# 部署命令
+export ADMIN_TOKEN=$(openssl rand -hex 32)
+echo "Admin Token: $ADMIN_TOKEN"
+docker-compose up -d
+```
+
+### 9.3 Nginx 反向代理配置
+
+```nginx
+# /etc/nginx/sites-available/simplego
+upstream simple_go {
+    server 127.0.0.1:9876;
+    keepalive 32;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name api.example.com;
+
+    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
+
+    location / {
+        proxy_pass http://simple_go;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # 长轮询支持
+        proxy_read_timeout 120s;
+        proxy_connect_timeout 10s;
+    }
+
+    # 健康检查端点（无需认证）
+    location /health {
+        proxy_pass http://simple_go/health;
+        access_log off;
+    }
+}
+
+server {
+    listen 80;
+    server_name api.example.com;
+    return 301 https://$server_name$request_uri;
+}
+```
+
+```bash
+# 启用配置
+sudo ln -s /etc/nginx/sites-available/simplego /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl reload nginx
+```
+
+### 9.4 OpenClaw 客户端部署
+
+```mermaid
+sequenceDiagram
+    participant Admin
+    participant Server as Go Server
+    participant OC as OpenClaw Client
+
+    Admin->>Server: 1. 启动服务器
+    Note over Server: 记录 Admin Token
+
+    Admin->>Server: 2. POST /clients
+    Server-->>Admin: {clientId, token}
+
+    Admin->>OC: 3. 配置 config.yaml
+    Note over OC: serverUrl + apiToken
+
+    Admin->>OC: 4. 启动 Gateway
+    OC->>Server: 5. GET /poll (验证连接)
+    Server-->>OC: {messages: []}
+
+    Note over Admin,OC: 部署完成，开始接收消息
+```
+
+#### 客户端配置步骤
+
+```bash
+# 1. 在服务器上注册客户端
+ADMIN_TOKEN="your-admin-token"
+SERVER_URL="https://api.example.com"
+
+CLIENT_RESPONSE=$(curl -s -X POST "$SERVER_URL/clients" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "production-client-1"}')
+
+CLIENT_TOKEN=$(echo $CLIENT_RESPONSE | jq -r '.token')
+echo "Client Token: $CLIENT_TOKEN"
+
+# 2. 在 OpenClaw 机器上配置
+openclaw config set channels.simplego.enabled true
+openclaw config set channels.simplego.serverUrl "$SERVER_URL"
+openclaw config set channels.simplego.apiToken "$CLIENT_TOKEN"
+openclaw config set channels.simplego.pollIntervalMs 1000
+
+# 3. 验证配置
+openclaw channels status simplego
+
+# 4. 启动 Gateway
+openclaw gateway run
+```
+
+### 9.5 多节点部署拓扑
+
+```mermaid
+flowchart TB
+    subgraph "Load Balancer"
+        LB[HAProxy / AWS ALB]
+    end
+
+    subgraph "Go Server Cluster"
+        GO1[Go Server 1]
+        GO2[Go Server 2]
+        REDIS[(Redis)]
+    end
+
+    subgraph "OpenClaw Cluster"
+        OC1[OpenClaw 1<br/>Region: US]
+        OC2[OpenClaw 2<br/>Region: EU]
+        OC3[OpenClaw 3<br/>Region: APAC]
+    end
+
+    LB --> GO1
+    LB --> GO2
+    GO1 <--> REDIS
+    GO2 <--> REDIS
+
+    OC1 --> LB
+    OC2 --> LB
+    OC3 --> LB
+
+    Note1[共享状态存储于 Redis]
+```
+
+> **注意**：当前实现使用内存存储，多节点部署需要先实现 Redis 持久化层。
+
+### 9.6 部署检查清单
+
+```markdown
+## 部署前检查
+
+- [ ] Go 服务器编译完成
+- [ ] Admin Token 已安全存储
+- [ ] SSL 证书已配置
+- [ ] 防火墙规则已开放 (443/tcp)
+- [ ] Systemd 服务已启用
+
+## 部署后验证
+
+- [ ] `curl https://api.example.com/health` 返回 `{"ok": true}`
+- [ ] 成功注册客户端并获取 token
+- [ ] OpenClaw `channels status simplego` 显示 configured=true
+- [ ] 发送测试消息并收到响应
+- [ ] 日志正常无错误
+
+## 监控告警
+
+- [ ] 配置 /health 端点监控
+- [ ] 配置错误日志告警
+- [ ] 配置 CPU/内存告警阈值
+```
+
+### 9.7 环境变量参考
+
+| 变量名 | 说明 | 示例 |
+|--------|------|------|
+| `ADMIN_TOKEN` | 管理员认证令牌 | `openssl rand -hex 32` |
+| `PORT` | 服务端口 | `9876` |
+| `LOG_LEVEL` | 日志级别 | `info` / `debug` |
+
+## 10. 扩展点
+
+| 功能 | 实现建议 |
+|------|---------|
+| **WebSocket** | 替换轮询为双向 WebSocket |
+| **持久化** | 使用 SQLite/PostgreSQL 存储会话 |
+| **媒体支持** | 扩展 Message 结构，添加文件上传端点 |
+| **会话过期** | 添加 TTL 和定时清理 goroutine |
+| **指标监控** | 添加 Prometheus metrics 端点 |
+| **速率限制** | 添加 per-client 请求限流 |